@drbaher/draft-cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,224 @@
+# Agents
+
+Drive `draft-cli` from an LLM agent or non-interactive client. Same shape as the rest of the contract-operations suite.
+
+## Output contract
+
+- **Success**: substituted document body to **stdout** (or to `--output PATH` if given), exit `0`. With `--json`, **stdout** is a single JSON object instead.
+- **Failure**: human-readable error to **stderr**, non-zero exit. With `--json`, **stdout** is `{ok: false, missing: [...]}` or similar; the error message still goes to stderr.
+- Diagnostic text (`--why` block, warnings, `note:` lines, color) always goes to **stderr**. Stdout is reserved for the substituted document or the JSON report. This separation is the contract — pipelines can safely compose `template-vault get … | draft - | nda-review …` without stderr poisoning.
+- `--silent` (`-q`) suppresses stderr completely after argument parsing. Use this for fully-quiet pipelines where you only want the stdout artifact.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | I/O error — template not found, unreadable, malformed `.docx`, write failure on `--output` |
+| `2` | Validation — missing required parameters, orphan schema declarations, mixed-syntax without `--syntax`, no placeholders detected |
+| `3` | `template-vault get` subprocess failed (vault ref like `nda/house-mutual`) |
+| `4` | LLM tier failure — provider unreachable, auth rejected, non-JSON response, unsupported provider |
+
+## Discovery
+
+```sh
+draft --help                       # human-readable help
+draft --version                    # → draft-cli <semver>
+draft --check-llm                  # one-token roundtrip to verify env-configured LLM provider
+draft <template> --list-placeholders --json
+                                   # placeholders the agent will need to supply, machine-readable
+draft <template> --validate --params deal.json
+                                   # completeness check; exit 2 with `--json` `{ok:false, missing:[...]}` on failure
+draft <template> --diff --params deal.json --json
+                                   # structured diff (substitution table); never writes output
+```
+
+Discovery flow for a fresh template:
+
+1. `draft <template> --list-placeholders --json` to see what parameters exist, which tier matched, and the alias map.
+2. Resolve each `key` to a value from the deal context.
+3. `draft <template> --params deal.json --validate --json` to confirm everything resolves before generating output.
+4. `draft <template> --params deal.json --output draft.md --json` to substitute and capture a structured report.
+
+## JSON shapes
+
+### `--list-placeholders --json`
+
+```json
+{
+  "template": "nda/house-mutual",
+  "tier": "bracket",
+  "placeholders": [
+    {
+      "key": "party_a",
+      "first_seen_as": "Party A",
+      "aliases": ["Party A", "Disclosing Party"],
+      "required": true,
+      "occurrences": 4,
+      "tier": "bracket"
+    }
+  ],
+  "warnings": [],
+  "unmapped": []
+}
+```
+
+### `--validate --json`
+
+On success:
+
+```json
+{ "ok": true, "resolved": ["party_a", "party_b"], "sources": { "party_a": "params", "party_b": "cli" } }
+```
+
+On failure:
+
+```json
+{ "ok": false, "missing": ["party_b"] }
+```
+
+### `--diff --json`
+
+```json
+{
+  "ok": true,
+  "tier": "bracket",
+  "diff": [
+    { "key": "party_a", "from": "[Party A]", "to": "Acme Corporation", "occurrences": 2 },
+    { "key": "effective_date", "from": "[Effective Date]", "to": null, "occurrences": 1 }
+  ]
+}
+```
+
+`to: null` means the placeholder is unresolved — `--diff` doesn't error on missing values; it shows them so the caller can decide.
+
+### Main draft with `--json`
+
+```json
+{
+  "ok": true,
+  "tier": "bracket",
+  "output_path": null,
+  "output": "<substituted document body>",
+  "placeholders": [ /* same shape as --list-placeholders */ ],
+  "sources": { "party_a": "cli", "party_b": "params" },
+  "warnings": [],
+  "unmapped": [
+    { "phrase": "See Section 4", "tier": "bracket" }
+  ]
+}
+```
+
+If `--output PATH` is set, `output_path` is the path and `output` is `null` (the document was written to disk, not embedded in the JSON).
+
+## Tier names
+
+The `tier` field on JSON output indicates which detection strategy matched. Stable across minor versions:
+
+| Tier value | Meaning |
+|------------|---------|
+| `"bracket"` | `[Title Case]` literal match |
+| `"mustache"` | `{{...}}` literal match (only when `--syntax mustache`) |
+| `"docx-highlight"` | Yellow / green / cyan / magenta highlighted runs in `.docx` |
+| `"heuristic"` | Bundled generic-name dictionary (warn-only by default) |
+| `"llm"` | LLM-suggested placeholders (only when env-configured) |
+| `"none"` | Cascade found zero placeholders |
+
+## Failure → recovery
+
+| Symptom | Diagnose | Recover |
+|---|---|---|
+| exit 1, `template not found` | Check the path; if it looks like a vault ref (`nda/house-mutual`), make sure `template-vault` is on `PATH`. | Pipe the body via stdin: `template-vault get … \| draft -` |
+| exit 2, `missing required parameter(s)` | `draft <template> --list-placeholders --json` | Supply the missing keys via `--<key>` flags or `--params`. Note typo warnings in `warnings[]`. |
+| exit 2, `mixed placeholder conventions` | Inspect the template for both `[X]` and `{{Y}}` | Pass `--syntax bracket` or `--syntax mustache` to pick one family. The other is left untouched. |
+| exit 2, `schema declares … but no matching phrase` | Schema-template drift. The schema declares a key whose alias list doesn't appear in the template body. | Remove the orphan from the schema, or add the phrase to the template. |
+| exit 2, `no placeholders detected by deterministic tiers` | Template has no markup; T1–T4 all empty. | Either ship a schema with explicit aliases, opt into `.docx` highlights (already auto), or configure `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` in `.env` to enable T5 LLM detection. |
+| exit 3, `template-vault get … failed` | The vault subprocess returned non-zero. Stderr surfaces the vault's error. | Fix the vault ref or fall back to a local file. |
+| exit 4, `LLM call failed: 401` | Provider auth rejected | Rotate `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` in `.env`. |
+| exit 4, `LLM returned non-JSON response` | Model didn't follow the prompt format | Try a stronger model via `DRAFT_LLM_MODEL=…`. Or pass `--no-llm` to stay deterministic. |
+
+## Recommended defaults for agent invocations
+
+```sh
+# Discovery
+draft "$TEMPLATE" --list-placeholders --json
+
+# Validate before committing to substitution
+draft "$TEMPLATE" --validate --params deal.json --json
+
+# Substitute with structured output for downstream pipelining
+draft "$TEMPLATE" --params deal.json --output draft.md --json --why
+
+# Pipe via the suite
+template-vault get nda/house-mutual \
+  | draft - --params deal.json --json --no-llm \
+  | jq -r '.output' \
+  | nda-review review - --playbook house --json
+```
+
+`--no-llm` is recommended for agent-driven pipelines unless the agent has explicit license to invoke a network call. `draft-cli`'s T5 auto-runs only when env configures a provider; passing `--no-llm` disables it even then.
+
+## LLM safety
+
+- **No network by default.** T5 LLM tier runs only when `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `DRAFT_LLM_*` is configured in `.env` or the process environment.
+- **Template text only.** T5 sends the template body to the provider. It does **not** send `--params` values, schema contents, `.env` contents, or any other env variables.
+- **Explicit kill-switch.** `--no-llm` disables T5 even when configured. Use this in any pipeline that handles privileged contracts.
+- **Fail-fast assertion.** `--llm` asserts the provider is configured; exits `4` immediately if not. Use this in scripts that *require* T5 so they don't silently fall back to a deterministic-only cascade.
+
+Documented in [SECURITY.md](SECURITY.md).
+
+## Heuristic safety gate
+
+T4 (heuristic dictionary) has a higher false-positive risk than the other deterministic tiers — substituting over a real party name that happens to be `Acme Corporation` would be embarrassing. By default in non-TTY contexts T4 matches are **listed but not substituted**; the run exits `2` with a warning. Bypass with `--yes-heuristic` (the user has reviewed and accepts the risk) or disable T4 entirely with `--no-heuristic`.
+
+Agents should default to `--no-heuristic` unless the calling context has explicitly cleared the template for heuristic substitution.
+
+## Library use (Node.js)
+
+`draft-cli.mjs` is an ESM module. Every meaningful function is exported:
+
+```js
+import {
+  detectBracket, detectMustache, detectDocxHighlight, detectHeuristic, detectLlm,
+  parseSchema, loadSchema, runCascade, substitute, resolveValues,
+  parseArgs, main, completionScript, VERSION, EXIT
+} from "@drbaher/draft-cli";
+
+// Programmatic substitution
+const args = parseArgs(["x.md", "--party-a", "Acme"]);
+const input = { kind: "text", body: "Between [Party A] and [Party B]", path: null };
+const result = await runCascade(input, args, /*schema=*/null, /*env=*/{});
+// → { tier: "bracket", placeholders: [...], warnings: [], unmapped: [] }
+const { resolved, missing } = await resolveValues(result.placeholders, args, /*paramsJson=*/{});
+if (missing.length === 0) {
+  const out = substitute(input.body, result.placeholders, resolved, result.tier);
+  // out === "Between Acme and [Party B]"
+}
+```
+
+Or invoke the full CLI in-process with captured I/O:
+
+```js
+import { Writable } from "node:stream";
+import { main } from "@drbaher/draft-cli";
+
+class Capture extends Writable {
+  constructor() { super(); this.s = ""; }
+  _write(c, _e, cb) { this.s += c; cb(); }
+}
+const out = new Capture(), err = new Capture();
+const code = await main(["x.md", "--party-a", "Acme", "--json"], { out, err });
+// out.s is the JSON report; err.s has any --why block or warnings.
+```
+
+Test fixtures (mock spawners for `template-vault`, mock fetchers for LLM, synthesized `.docx` files) are in `tests/_helpers.mjs` if you want to drive the CLI in tests of your own.
+
+## See also
+
+- [README.md](README.md) — install, 30-second first run, command reference.
+- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walkthrough.
+- [PARAM_SCHEMA.md](PARAM_SCHEMA.md) — locked parameter contract: cascade, schema file, precedence.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — single-file rationale, substitution model, `.docx` parsing.
+- [SECURITY.md](SECURITY.md) — threat model + LLM data-flow disclosure.
+- [FAQ.md](FAQ.md) — design questions and trade-offs.
+- [CHANGELOG.md](CHANGELOG.md) — release notes + the v2 "Deferred" list.

package/ARCHITECTURE.md

@@ -0,0 +1,206 @@
+# Architecture
+
+A walk-through of how `draft-cli` is shaped and why. Read this before
+contributing — it explains the constraints that drove the design.
+
+## Single-file CLI
+
+`draft-cli.mjs` is one file. Helpers, tiers, command dispatchers, and
+the main entry point all live in it. There is no `src/` directory, no
+build step, no compiled output. Run it directly:
+
+```sh
+node draft-cli.mjs --demo
+```
+
+The file is exported as ESM so the test suite can `import` individual
+functions. The `if (isMain)` block at the bottom runs `main()` only
+when the file is invoked directly, not when imported.
+
+Trade-off: the file is large (≈ 1000 LOC) and you have to scroll. The
+upside is that the entire CLI is in one place, has one set of imports,
+and can be vendored or audited as a single artifact.
+
+## The cascade
+
+`runCascade()` in `draft-cli.mjs` orchestrates the five detection tiers
+in this order:
+
+```
+T1 bracket [Title Case]      ──► hits? stop.
+   else
+T2 mustache {{X}}            (only if --syntax mustache; else skip)
+                              hits? stop.
+   else
+T3 .docx highlight runs      (only if input is .docx)
+                              hits? stop.
+   else
+T4 heuristic dictionary      (skipped by --no-heuristic)
+                              hits? stop. Gate output behind confirmation.
+   else
+T5 LLM                       (skipped by --no-llm or no env provider)
+                              hits? stop.
+   else
+done with zero placeholders. Caller decides whether that's an error.
+```
+
+**Sequential-with-stop** is the locked semantic. A non-empty tier wins
+and the others are skipped. This is predictable; it means a bracketed
+template never accidentally invokes the LLM. The alternative — union
+all tiers — was rejected during the design review because the conflict
+resolution between tiers (same canonical key from two tiers with
+different match texts) was a hidden complexity.
+
+## Substitution model
+
+`substitute()` does byte-level replacement on the original template
+body. It does **not** parse the body, build an AST, and re-emit. This
+means:
+
+- Whitespace, line endings, and Markdown structure are preserved exactly.
+- The output is the input with placeholder runs swapped out — nothing
+  else changes.
+- `.docx` input is the one exception: we extract text from
+  `word/document.xml` first, then substitute on the extracted text.
+  The output is plain markdown, not a re-written `.docx` (that's v2).
+
+For T1/T2 (bracket/mustache), substitution uses literal string
+replacement of the full match (`[Party A]` → `Acme`). For T3/T4/T5
+(text-based tiers), substitution uses a whole-word regex
+(`(?<![A-Za-z0-9])Acme Corporation(?![A-Za-z0-9])`) so we don't
+overlap-substitute into adjacent words.
+
+## Schema file handling
+
+`loadSchema()` looks for a sibling file next to the template:
+`<template>.params.json` or `<template_basename>.params.json`. If
+neither exists, returns `null` and the cascade uses inferred keys.
+
+If the parsed JSON has a top-level `_meta` key, it's long form
+(`{ aliases, required, default }` per entry). Otherwise short form
+(`key: [aliases…]`). The two forms are not mixable within one file —
+the parser commits to one shape on the first call.
+
+`findOrphans()` checks that every schema-declared key has a matching
+detected placeholder. Orphans are exit-2 errors (locked decision Q4).
+
+## Value resolution precedence
+
+`resolveValues()` walks placeholders in order and assigns a value from
+the first source that has one:
+
+```
+CLI flag (--key-name VALUE)
+   → --params JSON file
+      → --interactive prompt (only if --interactive set)
+         → schema default (only if long form with "default")
+            → error (exit 2 with a listing of missing keys)
+```
+
+The empty string is a valid CLI value (`--party-a ""`). Only **absence**
+falls through to the next source.
+
+## Why we shell out to template-vault
+
+`resolveInput()` detects `<category>/<name>[@version]`-shaped args and
+runs `template-vault get` as a subprocess. We do NOT import
+template-vault-cli as a library, because:
+
+1. template-vault-cli is Python; draft-cli is Node. No shared runtime.
+2. Even if we re-implemented the vault read path in Node, we'd duplicate
+   the lookup semantics (default sources, hash pinning, version
+   resolution). The vault is the source of truth for its own data.
+3. Subprocess isolation is a feature: a draft-cli bug can't corrupt a
+   vault, and a vault bug can't crash draft-cli without a clear exit
+   code (`3` for vault failure).
+
+The `spawnSync` call is injectable via the `spawner` option on
+`resolveInput()`, which is how the tests mock it without invoking a
+real template-vault binary.
+
+## `.docx` parsing
+
+T3 uses `jszip` to unzip the `.docx`, reads `word/document.xml`, and
+regex-extracts highlight runs (`<w:r>` containing
+`<w:highlight w:val="..."/>`). The XML structure of a Word document is
+well-known enough that regex is robust:
+
+```js
+const runRe = /<w:r\b[\s\S]*?<\/w:r>/g;
+// inside each run: <w:rPr><w:highlight w:val="yellow"/></w:rPr><w:t>text</w:t>
+```
+
+We don't take a full XML parser dependency (`@xmldom/xmldom` or
+similar) because the surface we care about is narrow and the regex is
+under 10 lines.
+
+Output for `.docx` input is plain markdown — extracted text in document
+order, paragraphs joined with `\n`. Round-tripping back into `.docx`
+(preserving styles, numbering, run formatting) is intentionally out of
+scope for v1.
+
+## LLM tier
+
+`detectLlm()` is invoked only at the bottom of the cascade. It accepts
+a `fetcher` injection so tests can mock the HTTP call without a
+network. The prompt is fixed at the top of `callLlm()`:
+
+> Given the document text below, identify spans that look like
+> placeholders — names, dates, or party-identifier text that a drafter
+> would replace before sending. Do NOT detect cross-references or
+> section labels. Output JSON ONLY in this exact shape: …
+
+Response parsing is permissive: we look for a balanced `{…}` substring,
+parse it, validate each entry has a string `text` and a snake_case
+`suggested_key`. Anything else is dropped silently.
+
+## ANSI color
+
+`paint()` and `colorEnabled()` honor:
+
+- `NO_COLOR` env (any non-empty value → off, per https://no-color.org/)
+- `FORCE_COLOR` env (any non-empty value → on)
+- Otherwise: on iff the target stream `isTTY`.
+
+Color codes go to **stderr** only. Stdout is always plain so it pipes
+cleanly into downstream tools.
+
+## Test layout
+
+```
+tests/
+  _helpers.mjs                — Shared fixtures, CaptureStream, mock fetchers, .docx synthesis.
+  fixtures/                   — Template + schema files used by tests.
+  test_args.mjs               — parseArgs and UsageError.
+  test_cascade.mjs            — runCascade orchestration & tier-stop semantics.
+  test_env.mjs                — .env reader, llmProviderFromEnv, color.
+  test_modes.mjs              — Main 'draft', --list-placeholders, --validate end-to-end.
+  test_output.mjs             — --why, --json, --output PATH, --demo.
+  test_schema.mjs             — Short vs long form, orphans, key validity.
+  test_substitution.mjs       — substitute(), resolveValues(), precedence.
+  test_t1_bracket.mjs         — T1 detection rule + real Common Paper template.
+  test_t2_mustache.mjs        — T2 detection.
+  test_t3_docx.mjs            — T3 detection, jszip-synthesized .docx.
+  test_t4_heuristic.mjs       — T4 detection + dictionary override.
+  test_t5_llm.mjs             — T5 detection with mocked HTTP.
+  test_template_vault.mjs     — Subprocess spawning with mock spawner.
+```
+
+One concern per file, modeled on template-vault-cli's test layout.
+Run with `node --test tests/test_*.mjs`. Coverage with
+`node --test --experimental-test-coverage tests/test_*.mjs`. Target:
+≥ 80% line on `draft-cli.mjs`. Current: 87.2%.
+
+## Forward-compatibility hooks
+
+The locked schema reserves field names for v2:
+
+- Long-form entries can grow `"type": "date" | "money" | "party" | ...`
+  for typed parameters.
+- Long-form entries can grow `"computed": "..."` for computed values
+  (`[Effective Date + 2 years]`).
+- Long-form entries can grow `"detect": "highlight" | "literal" | "bracket"`
+  for tier-specific detection preferences.
+
+These are reserved but unused in v1. Adding them in v2 will not break
+existing v1 schema files.

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
+and the project adheres to semantic versioning once it leaves 0.x.
+
+## 0.1.0 — 2026-05-16
+
+Initial release. Single-file Node.js CLI for deterministic placeholder
+substitution in legal-document templates. Part of the contract-operations
+suite ([cli.drbaher.com](https://cli.drbaher.com)).
+
+### Added
+
+- **Five-tier sequential-with-stop detection cascade.** First non-empty
+  tier wins.
+  - T1: `[Title Case]` brackets. Common Paper / YC SAFE / Bonterms.
+  - T2: `{{Title Case}}` or `{{snake_case}}` mustache (opt-in via
+    `--syntax mustache`).
+  - T3: `.docx` highlight runs (yellow / green / cyan / magenta) via
+    `jszip` + regex on `word/document.xml`.
+  - T4: Heuristic dictionary (`Acme Corporation`, `John Doe`,
+    `example@example.com`, `MM/DD/YYYY`, etc.). Warn-only by default;
+    requires interactive confirmation or `--yes-heuristic` to substitute.
+  - T5: LLM (Anthropic / OpenAI / explicit `DRAFT_LLM_*`). Auto-runs only
+    when `.env` or process env configures a provider. `--no-llm` disables.
+- **Schema file `<template>.params.json`** in short or long form.
+  Auto-selected by presence of a top-level `_meta` key. Short form is
+  `{ key: [aliases…] }`; long form supports `required` and `default`.
+- **Value resolution precedence**: CLI flag > `--params` JSON >
+  `--interactive` prompt > schema `default` > error.
+- **Three modes**: main `draft`, `--list-placeholders`, `--validate`.
+  All three support `--json` and `--why` structured explanation.
+- **Composable I/O**: stdin (`-`), stdout default, `--output PATH`,
+  `template-vault get` integration for `<category>/<name>[@version]` refs.
+- **ANSI color** honors `NO_COLOR` and `FORCE_COLOR`; auto-disables off-TTY.
+- **`--demo`** flag for a zero-file 30-second first run (`npx @drbaher/draft-cli@latest --demo`).
+- **`--completion bash|zsh`** flag that emits a hand-rolled shell completion
+  script to stdout. Completes top-level flags, the `--syntax` value
+  (`bracket`/`mustache`), the `--completion` shell name, and file paths
+  for `--params`/`--output`/`--dictionary`. No third-party generator.
+- **`--check-llm`** runs a one-token roundtrip against the configured LLM
+  provider — verifies env, auth, and reachability without sending any
+  template content. Exits `0` on success, `1` if no provider is configured,
+  `4` on provider error. Useful for CI / startup health checks in agent
+  pipelines.
+- **`--diff`** prints a per-placeholder substitution table to stdout and
+  exits — never writes output. With `--json`, emits a structured `diff`
+  array. Unresolved placeholders appear as `(unresolved)` / `to: null`
+  rather than erroring, so the caller can decide what to do.
+- **`-q` / `--silent`** suppresses all stderr (warnings, `--why` block,
+  notes, heuristic confirmations) for fully-quiet pipeline use. Argument-
+  parse errors still surface on the real stderr.
+- **Schema-rescue for T1/T2 detection.** Bracketed runs whose inner text
+  matches a schema-declared alias are admitted by detection even when
+  the heuristic rule would reject them. Lets all-caps signature-block
+  markers (`[COMPANY]`) and fill-in markers (`[_____________]`) be
+  brought into the alias map without loosening the heuristic itself.
+- **Typo guard** on `--<param-name>` flags. Unused flags are surfaced
+  as warnings and named in the missing-required error, so a typo'd
+  `--party-bb` doesn't silently fall through to a "missing party_b"
+  error with no connection.
+- **Exit codes**: `0` ok, `1` i/o, `2` validation, `3` template-vault failure,
+  `4` LLM failure.
+- **GitHub Actions CI**: Ubuntu × macOS × Node 18 / 20 / 22 test matrix,
+  coverage gate at 80% line, and smoke job that packs + installs + runs
+  `--version` + `--demo`.
+- **GitHub Actions publish**: npm Trusted Publishing on `v*` tag push,
+  with version-vs-tag check and `--provenance` attestation.
+- **Test suite**: 106 tests across 13 files (`unittest`-style per concern),
+  87.2% line coverage on `draft-cli.mjs`.
+
+### Notes
+
+- One runtime dependency only: `jszip` (MIT, zero transitive deps).
+- The LLM tier sends template text only — no params, no `.env` contents,
+  no other data. No network call by default.
+- Configuration contract is captured in
+  [PARAM_SCHEMA.md](PARAM_SCHEMA.md), reviewed and locked before code.
+- **T1 bracket rule is permissive**, not strict Title-Case. Real
+  Common Paper / YC SAFE / Bonterms templates use sentence-shaped
+  placeholders with full punctuation (`[Today’s date]`, `[1 year(s)]`,
+  `[Fill in city or county and state, i.e. "courts located in New Castle, DE"]`).
+  The rule rejects markdown links (`[label](url)`), checkbox markers
+  (`[x]`, `[ ]`), pure section refs (`[3.1]`), all-caps headings, and
+  punctuation-only brackets — but otherwise admits anything bracketed
+  that contains at least one letter. False positives are filtered with
+  the schema file; false negatives in this domain are higher-cost.
+
+## Deferred (v2 candidates)
+
+- **`.docx` output round-trip.** v1 writes plain markdown even from a
+  `.docx` input. Re-writing back into a `.docx` (preserving styles,
+  numbering, and run formatting) is a separate problem.
+- **Computed placeholders** (`[Effective Date + 2 years]`). The long-form
+  schema reserves a future `"computed"` field.
+- **Typed parameters** (`party`, `date`, `money` with format validation).
+  Schema reserves a future `"type"` field.
+- **LLM-assisted parameter inference from a deal description.** v1's T5
+  only suggests placeholders from template text — not from external prose
+  describing the deal.
+- **Cross-template parameter registry** (`parties.json` remembering
+  addresses, e-signature contacts, etc.). Additive — would layer
+  underneath `--params` in precedence.
+- **Multi-document bundles** (MSA + SOW sharing parameters in one call).
+  v1 is one document per invocation.
+- **`.docx` highlight detection beyond yellow/green/cyan/magenta.** v1
+  ignores other colors (black/white/none) by design.