# render — Render a Nunjucks Template

**Script name:** `render`

**Script location:** [`scripts/render.ts`](../../../scripts/render.ts)

**Invoke:**
```bash
npx --yes tsx .opencode/skills/templating-vault/scripts/render.ts \
  --template-key KEY [--prepare] [--id ID] [--output-file PATH] [OPTIONS]
```

**CRITICAL:** Always invoke the script using bash and the format noted above.

## Synopsis

```
render.ts (--template-key KEY | --template-file PATH)
          (--output-file PATH | --prepare [--id ID])
          [--config PATH] [--store-dir SPEC...]
```

Two modes:

- **File mode** (`--output-file`): Renders the template, writes result to a file,
  returns the path. Use for vault-unaware agents.
- **Prepare mode** (`--prepare`): Renders the template, stores the result in the
  vault under `prepared.<id>`, returns only the ID. Use for the prompt-by-reference
  protocol with vault-aware agents. See [prompt-by-reference workflow](../../workflows/).

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--template-key KEY` | string | Vault key whose value is the Nunjucks template text |
| `--template-file PATH` | string | Path to a template file (alternative to --template-key) |

Exactly one of `--template-key` or `--template-file` is required.

### Output Destination (one required)

| Flag | Type | Description |
|------|------|-------------|
| `--output-file PATH` | string | Write rendered text to this file (file mode) |
| `--prepare` | flag | Store rendered text in the vault and return an ID (prepare mode) |

### Optional

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--id ID` | string | auto-generated | ID for the prepared prompt (only with `--prepare`). If omitted, a unique ID is generated as `prep-<timestamp>-<random>`. |

## Variable Resolution

All non-template keys with values in all configured stores are collected as variables.
Templates use Nunjucks syntax: `{{ variable_name }}`.

Variables are available by:
- **Short name** (last key segment): `{{ max_workers }}`
- **Full key** (dots→underscores): `{{ global_config_max_workers }}`

Short names are matched first-found across stores. Use full names to disambiguate.

To get different values for the same variable name across agents, use different
`--store-dir` configurations that bind `session:` to different directories. See
[agent isolation](../../workflows/).

## Output (stdout)

Prepare mode:
```json
{
  "prepared": true,
  "id": "prep-1776923319515-kks5ef",
  "key": "prepared.prep-1776923319515-kks5ef",
  "substituted": ["forgejo_url", "forgejo_pat", "max_workers"],
  "missing": []
}
```

File mode:
```json
{
  "rendered": true,
  "output_file": "/tmp/rendered-prompt.txt",
  "substituted": ["forgejo_url", "forgejo_pat"],
  "missing": []
}
```

The `missing` array lists any `{{ placeholder }}` names that had no matching value.
Missing placeholders are left as-is in the output (not silently dropped).

## What the Script Stores (Prepare Mode)

Under `prepared.<id>`:
- `prepared.<id>` — the rendered prompt text
- `prepared.<id>.schema` — the variable schema from the template's `schema.yaml` (if it exists)
- `prepared.<id>.template_ref` — the source template key or file path

## Usage Examples

```bash
# Prepare mode: store rendered prompt, get back only an ID
npx --yes tsx .opencode/skills/templating-vault/scripts/render.ts \
  --template-key templates.imp_supervisor \
  --prepare \
  --store-dir /tmp/globals \
  --store-dir "session:/tmp/AUTO-IMP-SUP" \
  --store-dir "templates:/app/data/templates"

# Prepare with explicit ID
npx --yes tsx .opencode/skills/templating-vault/scripts/render.ts \
  --template-key templates.imp_supervisor \
  --prepare --id imp-sup-001 \
  --store-dir /tmp/globals

# File mode: render to a file for a vault-unaware agent
npx --yes tsx .opencode/skills/templating-vault/scripts/render.ts \
  --template-key templates.imp_supervisor \
  --output-file /tmp/supervisor-prompt.txt \
  --store-dir /tmp/globals
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Fatal error (missing args, template not found, render failure) |

## Dependencies

- Node.js >= 18, `npx tsx`, `nunjucks`, `js-yaml`
