Update tech_docs/jinja2_framework.md

tech_docs/jinja2_framework.md

@@ -1,3 +1,55 @@
+What we are really looking at is two different answers to the same meta-question:
+
+> “How much of the host language’s power do we allow to leak into a string that is *mostly* meant to be static markup?”
+
+Everything else—syntax, loops, auto-escaping—are just surface symptoms of that deeper design choice.
+
+──────────────────────────────────────
+1.  Language Leakage Spectrum
+──────────────────────────────────────
+• Jinja2  →  **Liberal Leakage**  
+  The template *is* a Python DSL.  You can call arbitrary Python functions, mutate state, import modules, and even monkey-patch while rendering.  
+  Runtime cost: you now need a Python VM and you inherit all of its security surface area.
+
+• Go templates  →  **Conservative Leakage**  
+  You may register Go functions, but the template engine itself has no loops that can run forever, no variables you can re-assign, and no way to open a file or start a goroutine *inside the template*.  
+  Runtime cost: you need only the compiled Go binary; the template is data, not code.
+
+──────────────────────────────────────
+2.  Meta-Implications
+──────────────────────────────────────
+A.  **Supply-chain Footprint**  
+   Jinja2 pulls in Python → whole interpreter, stdlib, possible venv.  
+   Go templates pull in nothing beyond the compiled binary.
+
+B.  **Static Analysis Horizon**  
+   Jinja2 can only be analysed by running Python; linters must see *both* the template and the Python context.  
+   Go templates are parsed once into an AST that the Go toolchain can reason about at compile time (unused templates, type-safe FuncMap, etc.).
+
+C.  **Security Model Shift**  
+   Jinja2’s sandbox plug-in is opt-in and porous (all it takes is one `__subclasses__` path).  
+   Go templates are sandboxed *by omission*: if you don’t register a dangerous func, it simply doesn’t exist.
+
+D.  **Deployment Shape**  
+   Jinja2 encourages “render server-side” or “render in an Ansible task”.  
+   Go templates encourage “compile templates into the binary and ship one file”.
+
+E.  **Philosophical Trade-off**  
+   • Jinja2: *“Let template authors express almost anything; trust them.”*  
+   • Go templates: *“Let template authors express almost nothing; trust the Go code instead.”*
+
+──────────────────────────────────────
+3.  Quick Litmus Test
+──────────────────────────────────────
+Imagine you have to hand your templates to a junior front-end contractor tomorrow.
+
+• With Jinja2 you will hand them a loaded gun and a safety manual.  
+• With Go templates you will hand them a paintbrush and a locked-down palette.
+
+That single difference is the *meta* comparison.
+
+---
+
 Here is a “menu” of hands-on project ideas that will give you real-world mileage with Jinja2, progressing from the simplest single-file scripts to more advanced, framework-driven work. Pick one or two from each tier and build them end-to-end; the list is deliberately varied so you can taste every common use-case.
 
 ------------------------------------------------