Deterministic templating and generation support

docs/template-generation.md

@@ -0,0 +1,89 @@
+# Templates and Generation Hooks
+
+`markitect-tool` keeps generation deterministic in core. LLM-assisted
+generation is represented as an external hook boundary, not as a provider
+dependency.
+
+## Template Variables
+
+Templates use simple double-brace variables:
+
+```markdown
+# {{title}}
+
+Owner: {{owner.name}}
+
+{{body}}
+```
+
+Variables can use dot paths into JSON/YAML data.
+
+```bash
+mkt template inspect template.md
+mkt template render template.md --data data.yaml --output rendered.md
+mkt template render template.md --set title="Draft" --set owner.name=Ada
+```
+
+Strict rendering is the default. Use `--lenient` to keep unresolved
+placeholders in place.
+
+## Contract Stubs
+
+Contracts can generate first-draft Markdown stubs:
+
+```bash
+mkt generate stub --contract examples/contracts/adr.contract.md --set status=proposed
+```
+
+The stub generator creates frontmatter from contract fields and emits required
+and recommended sections. Forbidden sections are skipped.
+
+## Rule-Based Generation
+
+A generation plan is a Markdown file with a fenced YAML block:
+
+````markdown
+# Letter Generation
+
+```yaml generation
+template: templates/letter.md
+data_file: data/letter.yaml
+output: out/letter.md
+```
+````
+
+Run it with:
+
+```bash
+mkt generate rules rules.md --output-dir .
+```
+
+The `documents` key can render multiple outputs:
+
+```yaml
+documents:
+  - template: templates/letter.md
+    data:
+      title: First
+    output: out/first.md
+  - template: templates/letter.md
+    data_file: data/second.yaml
+    output: out/second.md
+```
+
+## Assisted Generation Hook
+
+FR-042 is supported as a protocol boundary. External packages can implement a
+hook with:
+
+```python
+from markitect_tool.generation import GenerationHookRequest, GenerationHookResult
+
+class MyHook:
+    def generate(self, request: GenerationHookRequest) -> GenerationHookResult:
+        ...
+```
+
+Core does not call an LLM provider by itself. Higher layers can pass a hook into
+`generate_with_hook(...)` after handling credentials, policy, and provider
+selection.