@drbaher/draft-cli 0.1.0

package/PARAM_SCHEMA.md

@@ -0,0 +1,341 @@
+# PARAM_SCHEMA — v1 contract (locked)
+
+This doc is the source of truth for how `draft-cli` discovers placeholders,
+maps them to parameters, validates inputs, and reports results. Locked
+after Q1–Q4 and D1–D4 review. Reviewer: DrBaher.
+
+---
+
+## 1. Stack & posture
+
+- **Runtime:** Node.js ≥ 18 (global `fetch`, `node:test`, `--env-file`-style behavior re-implemented inline so we don't require ≥ 20.6).
+- **Distribution:** `npm install -g @drbaher/draft-cli`, single-file `draft-cli.mjs` shebang executable.
+- **Runtime dependencies (v1):** exactly one — `jszip` (MIT, zero transitive) for `.docx` unzip. Everything else uses Node's stdlib. LLM tier uses global `fetch` directly; no SDK dep.
+- **Local-first.** No telemetry. The only network call is the optional LLM tier and only when explicitly configured (see §3 T5).
+
+## 2. Inputs and outputs
+
+```
+draft <template> [flags]
+draft - [flags]                  # template body from stdin
+draft <cat>/<name>[@ver] ...     # pulls via `template-vault get`
+```
+
+- **Input forms accepted:** `path/to/file.md`, `path/to/file.txt`, `path/to/file.docx`, stdin (`-`), or a `template-vault` ref shaped `<category>/<name>[@version]`. Vault refs shell out to `template-vault get` — no library import.
+- **Output:** stdout by default, `--output PATH` for files. Output is always plain text/markdown in v1 — `.docx` is **input-only** for v1. Writing `.docx` back is deferred to v2.
+- **Encoding:** UTF-8 in, UTF-8 out. No BOM written; BOM tolerated on read.
+
+## 3. Detection cascade (sequential-with-stop)
+
+The cascade runs each tier in order. The first tier that returns **≥ 1 placeholder** wins and the others are skipped. The active tier is reported in `--why` and in `--json` output.
+
+| Tier | Name           | Deterministic | Default | Trigger to skip                  |
+| ---- | -------------- | ------------- | ------- | -------------------------------- |
+| T1   | Bracket        | ✅            | on      | `--syntax mustache` selected     |
+| T2   | Mustache       | ✅            | opt-in  | not selected via `--syntax`      |
+| T3   | DOCX highlight | ✅            | auto    | input not `.docx`                |
+| T4   | Heuristic      | ✅            | on      | `--no-heuristic`                 |
+| T5   | LLM            | ❌            | env-gated | no LLM provider configured     |
+
+### T1 — Bracket `[...]`
+
+A bracketed run is treated as a placeholder when **all** of:
+
+1. `[...]`, no nested brackets, length 1–200.
+2. **Not** immediately followed by `(` — i.e. not a markdown link
+   (`[label](url)` is skipped).
+3. **Not** a checkbox marker — inner matches `[ xX]{1,3}` is skipped
+   (`[x]`, `[ ]`, `[X]`, etc.).
+4. **Not** a pure section reference — inner matches `\d+(\.\d+)*$` is
+   skipped (`[3.1]`, `[4.2.1]`).
+5. Inner contains **at least one letter** (excludes `[___]`, `[---]`).
+6. Inner is **not entirely uppercase letters** (excludes
+   `[CONFIDENTIALITY]`, `[ARTICLE I]`).
+
+Examples that match: `[Party A]`, `[Effective Date]`,
+`[State of California]`, `[Today’s date]`, `[1 year(s)]`,
+`[Fill in state]`,
+`[Evaluating whether to enter into a business relationship with the other party.]`.
+
+Examples that don't: `[3.1]`, `[ARTICLE I]`, `[CONFIDENTIALITY]`,
+`[x]`, `[ ]`, `[the docs](https://example.com)`.
+
+The rule is intentionally permissive because real legal templates
+(Common Paper, YC SAFE, Bonterms) use sentence-shaped placeholders
+with full punctuation. False positives are filtered via the
+`<template>.params.json` schema (§5); false negatives in this domain
+are higher-cost than false positives.
+
+**Canonical key derivation** (when no schema is present): inner →
+lowercase → non-alphanumeric runs collapsed to `_` → leading/trailing
+`_` stripped → prefix `_` if leading char is a digit → truncated at 60
+chars. So `[Party A]` → `party_a`, `[1 year(s)]` → `_1_year_s`,
+`[Today’s date]` → `today_s_date`. Templates with long sentence-shaped
+placeholders should ship a schema file to give them clean keys.
+
+Cross-references like `[See Section 4]` *do* match T1 by design. The
+**schema file** (§5) is the disambiguation tool: when present, only declared
+keys substitute and other bracketed runs are left untouched.
+
+### T2 — Mustache `{{...}}`
+
+Opt-in via `--syntax mustache`. Matches `{{<inner>}}` where `<inner>` is
+either Title Case (same rule as T1 inner) or snake_case `[a-z][a-z0-9_]{0,78}`.
+
+Mixed-convention templates (both `[X]` and `{{X}}` present) emit a
+`doctor`-style stderr warning. The selected `--syntax` family is the only
+one substituted; the other is left untouched in output.
+
+### T3 — DOCX highlight
+
+Triggered only when input is `.docx`. Unzip with `jszip`, read
+`word/document.xml`, regex-scan for highlight runs:
+
+```xml
+<w:r>
+  <w:rPr><w:highlight w:val="yellow"/></w:rPr>
+  <w:t>Acme Corporation</w:t>
+</w:r>
+```
+
+Highlight colors recognized as placeholders: `yellow`, `green`, `cyan`,
+`magenta` (Word's "highlight as TODO" colors). Black/white/auto highlights
+are ignored.
+
+The captured text becomes the bracket-equivalent. So `Acme Corporation`
+in a yellow highlight is treated identically to `[Acme Corporation]` from
+T1 — same canonical-key derivation, same alias machinery.
+
+Output for .docx input is plain markdown: the text is extracted in
+document order (one paragraph per `<w:p>`), highlights are replaced, and
+the result is written to stdout or `--output`. Round-trip to `.docx`
+is **v2**.
+
+### T4 — Generic-name heuristic
+
+A bundled dictionary (`config/heuristic.json` shipped in the wheel) lists
+known generic placeholder values: `Acme Corporation`, `Acme Inc`,
+`Foo Corp`, `John Doe`, `Jane Roe`, `123 Main Street`, `example@example.com`,
+`555-555-1234`, `MM/DD/YYYY`, `TBD`, `[INSERT ___]`, etc. Curated, not
+inferred.
+
+Matches against the **untemplated body** (after T1–T3 ran and found
+nothing). Case-sensitive whole-word matching.
+
+**Safety gate (D3 locked):** T4 matches **never substitute silently**.
+Behavior:
+
+- In a TTY without `--yes-heuristic`: print each match, prompt `y/N`.
+- In a non-TTY without `--yes-heuristic`: print a warning block and
+  **leave matches untouched**. Substitution requires explicit opt-in.
+- With `--yes-heuristic`: substitute non-interactively (the user
+  has taken ownership).
+- `--no-heuristic` disables T4 entirely.
+
+Dictionary override: `--dictionary PATH` replaces (not extends) the bundled list.
+
+### T5 — LLM (last resort, env-gated)
+
+Runs only when **both** are true:
+- T1–T4 produced zero placeholders.
+- A provider is configured via env (read from `.env` in the working
+  directory or process env — process env wins).
+
+Provider env vars (any one suffices):
+- `ANTHROPIC_API_KEY` → Anthropic Messages API (default model: claude-sonnet-4-6).
+- `OPENAI_API_KEY` → OpenAI Responses API (default model: gpt-4o-mini).
+- `DRAFT_LLM_PROVIDER` + `DRAFT_LLM_API_KEY` (+ optional `DRAFT_LLM_MODEL`) → explicit override.
+
+If no provider env is present, the cascade **stops at T4** and the CLI
+errors with a clear message: `no placeholders detected by deterministic
+tiers; set ANTHROPIC_API_KEY (or equivalent) in .env to enable LLM
+detection, or pass --syntax mustache if your template uses {{...}}.`
+
+The LLM call sends template text **only**, no params file, no user data.
+Prompt asks for a JSON array of placeholder spans with `start`, `end`,
+`suggested_key`. Result is validated against the same canonical-key
+rules; invalid entries are dropped with a warning.
+
+`--no-llm` disables T5 even when env is configured (the cascade ends at
+T4). `--llm` asserts that an LLM provider should be available and
+fail-fasts with a clear error if none is configured; it does **not**
+override the sequential-with-stop semantics. Running T5 on top of an
+earlier-tier hit (the "find missed generics in a bracketed template"
+workflow) is a v2 candidate, not v1 behavior.
+
+## 4. Key conventions
+
+Three surfaces, one canonical key per parameter.
+
+| Surface       | Form                  | Example          |
+| ------------- | --------------------- | ---------------- |
+| Match source  | Title Case w/ spaces  | `Party A Name`   |
+| Canonical key | snake_case            | `party_a_name`   |
+| CLI flag      | kebab-case            | `--party-a-name` |
+| JSON file key | snake_case            | `"party_a_name"` |
+
+Derivation when no schema is present: match text → lowercase, spaces → underscores. `Party A Name` → `party_a_name`. The original match text is preserved in output (case/spacing intact); we replace byte-for-byte.
+
+Disallowed in placeholders (will error if found in a schema file): dots, slashes, leading digits, hyphens inside the match text. Reserved schema-file keys: `_meta`, `_aliases`, `_required`, `_defaults`.
+
+## 5. Schema file: `<template>.params.json`
+
+Sibling file, opt-in. If absent, placeholders are inferred by the active
+cascade tier; every inferred placeholder is treated as required; keys are
+auto-derived.
+
+If present, the schema is **authoritative**: only declared parameters
+substitute. Anything else the cascade detects is left untouched and
+listed in `--why` as `unmapped`.
+
+**Schema rescue (T1/T2 only).** When a schema declares a phrase that the
+heuristic detection rule would reject (e.g. all-caps `[COMPANY]`, all-
+underscore `[_____________]`, snake_case `[party_a]`), the schema's
+alias list is consulted during detection and rescues that phrase.
+Without this, a schema-declared alias would be silently dropped before
+ever reaching the resolution step. The rescue applies only to bracket
+(T1) and mustache (T2) tiers; T3/T4/T5 use text-based detection that
+doesn't need rescuing.
+
+### Short form (default in docs)
+
+```json
+{
+  "party_a": ["Party A", "Disclosing Party"],
+  "party_b": ["Party B", "Receiving Party"],
+  "effective_date": ["Effective Date"]
+}
+```
+
+Each value is a list of phrase forms (bracket inner text, mustache inner
+text, or highlighted text). The canonical key is **NOT** implicitly in
+its own alias list (Q3 locked) — list it explicitly if needed.
+
+### Long form (with `_meta`)
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "party_a":        { "aliases": ["Party A"], "required": true },
+  "effective_date": { "aliases": ["Effective Date"], "required": false, "default": "the date first written above" }
+}
+```
+
+Parser selects long form iff a top-level `_meta` key is present. Short
+and long are not mixable within one file.
+
+### Orphan handling (Q4 locked)
+
+Schema declares a key whose alias list matches no detected phrase →
+**error**, exit 2. Catches drift early.
+
+## 6. Precedence
+
+CLI flag > JSON `--params` file > `--interactive` prompt > schema `default` > error.
+
+- CLI flag present (even `""`) wins.
+- JSON value present wins over prompt and default.
+- `--interactive` set AND still missing → prompt.
+- Schema `default` present AND still missing → use the default.
+- Still missing → error, exit 2.
+
+## 7. Validation, modes, errors
+
+### `draft --validate <template> --params FILE`
+
+Same lookup, never writes output. Exits 0 if every required key resolves;
+2 otherwise. Honors all five cascade tiers and the schema if present.
+
+### `draft --list-placeholders <template>`
+
+Prints detected placeholders in first-appearance order, deduplicated.
+With `--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": []
+}
+```
+
+### Error shapes (stderr, red on TTY, honors `NO_COLOR`/`FORCE_COLOR`)
+
+```
+error: missing required parameter(s):
+  - party_a   (matched: [Party A], [Disclosing Party])
+      supply --party-a or set "party_a" in --params
+  - effective_date (matched: [Effective Date])
+      supply --effective-date or set "effective_date" in --params
+hint: run `draft --list-placeholders nda/house-mutual` to see all parameters.
+```
+
+```
+error: mixed placeholder conventions in template (4 bracket, 2 mustache).
+note: pass --syntax bracket or --syntax mustache; the other family is left untouched.
+```
+
+```
+error: schema declares "party_c" with aliases ["Party C","Third Party"],
+       but no matching phrase was detected by tier 'bracket'.
+hint: remove the entry from the schema, or add the phrase to the template.
+```
+
+```
+error: no placeholders detected by deterministic tiers (bracket, mustache,
+       docx-highlight, heuristic).
+hint: set ANTHROPIC_API_KEY in .env to enable LLM detection,
+      or pass --syntax mustache if your template uses {{...}}.
+```
+
+Exit codes: `0` success, `1` template/input I/O error, `2` validation
+failure, `3` template-vault subprocess failure, `4` LLM tier failure
+(network, auth, malformed response).
+
+## 8. `--why` output
+
+Structured stderr block (or stdout under `--json`):
+
+```
+draft: substituted 7 placeholders in nda/house-mutual → draft.md
+why:
+  input         = nda/house-mutual (via template-vault get)
+  tier          = bracket
+  schema        = nda/house-mutual.params.json (short form)
+  placeholders  = 4 distinct, 12 occurrences
+  resolved      = 4 (3 from CLI, 1 from --params, 0 interactive, 0 default)
+  defaulted     = 0
+  unresolved    = 0
+  unmapped      = 1 ([See Section 4] — not in schema)
+  warnings      = 0
+```
+
+## 9. Out of scope for v1 (deferred — schema is forward-compatible)
+
+- Computed placeholders (`[Effective Date + 2 years]`). Long-form schema reserves a future `"computed"` key.
+- Typed parameters (`party`, `date`, `money`). Reserves a future `"type"` key.
+- Cross-template parameter registry (`parties.json`). Additive; would layer underneath `--params` in precedence.
+- `.docx` output round-trip.
+- LLM-assisted suggestion *from a deal description* (current T5 only suggests from template text).
+
+---
+
+## Locked decisions (audit trail)
+
+| ID  | Question                                | Decision |
+| --- | --------------------------------------- | -------- |
+| Q1  | Cross-references like [See Section 4]   | Subsumed: schema file disambiguates; T4/T5 expand coverage. |
+| Q2  | Short-form vs long-form schema          | Both supported; `_meta` selects long form. |
+| Q3  | Canonical key implicit-alias            | No — explicit list only. |
+| Q4  | Orphan schema declarations              | Error, exit 2. |
+| D1  | Cascade semantics                       | Sequential-with-stop. |
+| D2  | LLM default behavior                    | Env-gated auto-fallback at T4 boundary. |
+| D3  | Heuristic safety gate                   | Warn-only, requires `--yes-heuristic` or interactive confirm. |
+| D4  | .docx parsing                           | `jszip` + regex on `word/document.xml`. |
+
+*End of contract. Code begins once approved.*

package/README.md

@@ -0,0 +1,305 @@
+# draft-cli
+
+A **deterministic placeholder-filler** for legal-document templates. Reads
+bracketed (`[Party A]`) or mustache (`{{Party A}}`) markup, `.docx` yellow
+highlights, or generic-name heuristics; substitutes from CLI flags, a JSON
+params file, or an interactive prompt; writes a ready-to-review draft.
+
+Single-file Node.js. One runtime dependency (`jszip`, for `.docx`). Local-first,
+no telemetry, MIT-licensed. Part of the contract-operations suite (see
+[cli.drbaher.com](https://cli.drbaher.com)).
+
+---
+
+## What it does
+
+You have a template. You have a deal. You want a draft you can review and
+send. The middle step — finding every `[Party A]`, `[Effective Date]`, and
+`[State of California]` and replacing them with real values — is mechanical,
+deterministic work that doesn't need an LLM and shouldn't need to leave your
+machine.
+
+```
+template-vault get nda/house-mutual | draft - \
+    --party-a "Acme Corporation" \
+    --party-b "Vendor Inc." \
+    --effective-date 2026-06-01 \
+    --output draft.md
+```
+
+Or via a params file:
+
+```
+draft nda/house-mutual --params deal-acme.json --output draft.md
+```
+
+`draft` does **only** that step. Templates come from `template-vault-cli` or
+any markdown / .docx / stdin source. Review and red-line happens in
+`nda-review-cli`. Conversion to PDF goes through `docx2pdf-cli`. Signing
+goes through `sign-cli`. Each tool stays small and composable.
+
+---
+
+## Install
+
+```sh
+npm install -g @drbaher/draft-cli
+```
+
+Or run without installing:
+
+```sh
+npx @drbaher/draft-cli@latest --demo
+```
+
+Requires Node.js ≥ 18. Tested on Ubuntu and macOS, Node 18 / 20 / 22.
+
+### Shell completion
+
+```sh
+# bash
+draft --completion bash >> ~/.bashrc
+
+# zsh
+draft --completion zsh > ~/.zsh/completions/_draft
+# ensure ~/.zsh/completions is in fpath, then: autoload -U compinit && compinit
+```
+
+Completes flags, the `--syntax bracket|mustache` value, `--completion bash|zsh`,
+and file paths for `--params`, `--output`, and `--dictionary`.
+
+---
+
+## 30-second first run
+
+No file authoring required. The bundled demo runs end-to-end:
+
+```sh
+npx @drbaher/draft-cli@latest --demo
+```
+
+```
+demo: substituting [Party A], [Party B], [Effective Date]
+# Mutual Non-Disclosure Agreement (demo)
+
+This Agreement is entered into on 2026-06-01 between Acme Corporation
+and Vendor Inc. (collectively, the "Parties").
+
+1. Confidentiality. Acme Corporation and Vendor Inc. agree to keep confidential
+   any information disclosed under this Agreement.
+
+2. Term. This Agreement remains in effect for two years from the
+   2026-06-01.
+```
+
+What just happened: `draft-cli` detected three bracketed placeholders
+(`[Party A]`, `[Party B]`, `[Effective Date]`), mapped them to the
+canonical keys `party_a`, `party_b`, `effective_date`, and substituted
+in pre-canned demo values. Real runs use your own template and your own
+values.
+
+---
+
+## End-to-end transcript
+
+```sh
+$ cat > nda.md <<'EOF'
+This Agreement is between [Party A] and [Party B], effective [Effective Date].
+[Party A] and [Party B] agree to keep confidential information confidential.
+EOF
+
+$ draft --list-placeholders nda.md
+party_a  (Party A)  ×2  [tier=bracket]
+party_b  (Party B)  ×2  [tier=bracket]
+effective_date  (Effective Date)  ×1  [tier=bracket]
+
+$ draft nda.md --party-a "Acme" --party-b "Vendor Inc." --effective-date 2026-06-01
+This Agreement is between Acme and Vendor Inc., effective 2026-06-01.
+Acme and Vendor Inc. agree to keep confidential information confidential.
+
+$ cat > deal.json <<'EOF'
+{"party_a": "Acme", "party_b": "Vendor Inc.", "effective_date": "2026-06-01"}
+EOF
+
+$ draft nda.md --params deal.json --output draft.md --why
+draft: substituted 3 of 3 placeholders → draft.md
+why:
+  input         = nda.md
+  tier          = bracket
+  schema        = (none, inferred)
+  placeholders  = 3 distinct, 5 occurrences
+  resolved      = 3 (0 from CLI, 3 from --params, 0 interactive, 0 default)
+  defaulted     = 0
+  unresolved    = 0
+  unmapped      = 0
+  warnings      = 0
+
+$ draft --validate nda.md --params deal.json && echo "ok"
+ok: 3 parameter(s) resolved
+ok
+```
+
+---
+
+## Detection cascade
+
+`draft-cli` finds placeholders by trying five strategies in order. The
+**first non-empty tier wins** and the others are skipped.
+
+| Tier | Strategy             | When                                      |
+| ---- | -------------------- | ----------------------------------------- |
+| 1    | `[Title Case]`       | Default. Matches Common Paper / YC SAFE / Bonterms convention. |
+| 2    | `{{Title Case}}`     | Opt-in with `--syntax mustache`.          |
+| 3    | `.docx` highlights   | Auto on `.docx` input. Yellow / green / cyan / magenta runs. |
+| 4    | Heuristic dictionary | Bundled list of generic names (`Acme Corporation`, `John Doe`, `example@example.com`, etc.). Warn-only by default. |
+| 5    | LLM                  | Last resort. Runs only when `.env` or process env configures `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `DRAFT_LLM_*`. |
+
+The cascade is **deterministic through tier 4**. Tier 5 is the only
+non-deterministic step and runs only when you've explicitly configured a
+provider key. Pass `--no-llm` to disable it even when configured. Pass
+`--no-heuristic` to skip tier 4.
+
+See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) for the full contract.
+
+---
+
+## Schema file (optional)
+
+A sibling `<template>.params.json` lets you declare canonical keys, alias
+phrases, defaults, and whether each parameter is required.
+
+**Short form:**
+
+```json
+{
+  "party_a": ["Party A", "Disclosing Party"],
+  "party_b": ["Party B", "Receiving Party"],
+  "effective_date": ["Effective Date"]
+}
+```
+
+**Long form** (gates on `_meta`):
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "party_a":        { "aliases": ["Party A"], "required": true },
+  "effective_date": { "aliases": ["Effective Date"], "required": false, "default": "the date first written above" }
+}
+```
+
+With a schema, `draft-cli` substitutes **only** declared parameters and
+leaves other bracketed text untouched. Without one, every detected
+bracketed phrase is treated as a required parameter.
+
+---
+
+## Command reference
+
+```
+draft <template>              fill placeholders and emit the result
+draft <category>/<name>       pull via `template-vault get`
+draft -                       template body on stdin
+draft --demo                  bundled demo, no file needed
+draft --list-placeholders <t> enumerate placeholders and exit
+draft --validate <t> --params completeness check, no output
+
+OPTIONS
+  --params FILE          JSON file of param values (snake_case keys)
+  -o, --output PATH      write to PATH (default: stdout)
+  --syntax bracket|mustache
+  -i, --interactive      prompt for missing required parameters
+  --why                  structured explanation to stderr
+  --json                 machine-readable result on stdout
+  -q, --silent           suppress all stderr (warnings, --why, notes)
+  --no-heuristic         disable tier 4
+  --yes-heuristic        substitute tier-4 matches without confirmation
+  --no-llm               disable tier 5 even when env is configured
+  --llm                  assert that env is configured (fail-fast if not)
+  --check-llm            one-token roundtrip to verify provider config
+  --diff                 show substitution table without writing output
+  --dictionary PATH      override the bundled heuristic dictionary
+  --<param-name> VALUE   set a parameter directly (kebab → snake_case)
+  -h, --help             show full help
+  -V, --version          show version
+```
+
+Exit codes: `0` ok · `1` i/o · `2` validation · `3` template-vault failure
+· `4` llm failure.
+
+---
+
+## LLM tier (env-gated, opt-in)
+
+When tiers 1–4 all find nothing, `draft-cli` falls back to a language model
+**only if** a provider key is in the environment. Read order: `.env` in
+the working directory, then `process.env` (process wins).
+
+```sh
+echo 'ANTHROPIC_API_KEY=sk-ant-…' >> .env
+draft some-freeform-draft.md          # tier 5 auto-runs when 1-4 empty
+```
+
+Supported providers: Anthropic (`ANTHROPIC_API_KEY`), OpenAI
+(`OPENAI_API_KEY`), or explicit (`DRAFT_LLM_PROVIDER` + `DRAFT_LLM_API_KEY`
++ optional `DRAFT_LLM_MODEL`). The LLM receives template text only — no
+params file, no `.env` contents, no other data. Pass `--no-llm` to disable
+even when configured.
+
+---
+
+## Composability
+
+`draft-cli` reads from stdin, writes to stdout by default, and exits with
+distinct codes for each failure class. It composes with `template-vault-cli`
+on the read side and `nda-review-cli` / `docx2pdf-cli` / `sign-cli` on
+the write side:
+
+```sh
+template-vault get nda/house-mutual \
+  | draft - --params deal-acme.json \
+  | nda-review review - --playbook house \
+  | docx2pdf - draft.pdf
+```
+
+The `--why` and `--json` flags make every step inspectable by agents and
+shell pipelines.
+
+---
+
+## Part of the contract-operations suite
+
+`draft-cli` is one of a small set of single-purpose CLIs for contract
+operations. See [cli.drbaher.com](https://cli.drbaher.com) for the suite
+landing page.
+
+- **[nda-review-cli](https://github.com/DrBaher/nda-review-cli)** —
+  draft, review, and negotiate NDAs against your own house playbook.
+  Deterministic by default; opt-in LLM augmentation.
+- **[docx2pdf-cli](https://github.com/DrBaher/docx2pdf-cli)** —
+  honest DOCX → PDF conversion with batch processing, parallel runs,
+  font validation.
+- **[sign-cli](https://github.com/DrBaher/sign-cli)** —
+  fully-offline PAdES e-signature with hash-chained audit events,
+  RFC 3161 timestamps.
+
+`template-vault-cli` (a Git-backed, clause-aware package manager for
+legal-document templates) is the natural upstream of `draft-cli` and
+will join the suite when it ships.
+
+---
+
+## Documentation
+
+- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walk-through of every flow.
+- [AGENTS.md](AGENTS.md) — JSON shapes, exit codes, library use; everything an LLM agent driving `draft-cli` needs.
+- [PARAM_SCHEMA.md](PARAM_SCHEMA.md) — locked v1 contract: cascade, schema file, precedence.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — single-file rationale, substitution model, .docx parsing.
+- [FAQ.md](FAQ.md) — design questions and trade-offs.
+- [SECURITY.md](SECURITY.md) — threat model and how to report a vulnerability.
+- [CHANGELOG.md](CHANGELOG.md) — release notes and the v2 "Deferred" list.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — scope rules and release flow.
+
+## License
+
+MIT. See [LICENSE](LICENSE).