# 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.