@drbaher/draft-cli 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,71 @@ 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.8.1 — 2026-05-17
+
+### Docs
+
+- **README refreshed for the v2 surface.** New "v2 features" section
+  with one-paragraph showcases for each shipped v2 capability (.docx
+  round-trip, typed parameters, computed placeholders, positional
+  addressing, `parties.json` registry, multi-document bundles,
+  `--from-deal` LLM inference). Command reference updated with new
+  flags + version annotations. Exit-code table updated with code 4
+  (validation / typed / computed / ref / positional) and code 5
+  (LLM). Intro paragraph rewritten to reflect the v2 capability
+  scope instead of just v1.
+- No code or behavior change. v0.8.0's API surface, schema contract,
+  and CLI flags are unchanged. Strictly a docs publish.
+
+## 0.8.0 — 2026-05-17
+
+### Added
+
+- **LLM inference from a deal description** (last v2 item). New
+  `--from-deal PATH` flag reads a free-form deal description and
+  asks the configured T5 LLM provider to extract values for the
+  schema's declared placeholders:
+  ```sh
+  draft nda.md --from-deal deal-notes.txt --output draft.md
+  ```
+  Where `deal-notes.txt` is unstructured prose:
+  ```
+  Mutual NDA between Acme Corporation (DE) and Globex (UK), effective
+  June 1, 2026, for a 2-year term.
+  ```
+  The LLM is asked to fill `party_a`, `party_a_state`, `party_b`,
+  `effective_date`, etc. — only the keys already detected as
+  placeholders are extracted.
+- **Value-resolution precedence updated:**
+  `CLI flag > --params JSON > --from-deal (LLM) > --interactive > schema default > error`.
+  CLI / --params always win, so users can fix or override anything
+  the LLM got wrong.
+- **New public API:** `inferFromDeal(dealText, placeholders, providerCfg, { fetcher })`.
+
+### Decisions locked (V2_BRIEFS_REMAINING Q4.1–Q4.3)
+
+- **Q4.1 Provider:** same T5 provider config — `ANTHROPIC_API_KEY`,
+  `OPENAI_API_KEY`, or explicit `DRAFT_LLM_*`. No separate inference
+  provider; one network surface, one set of env vars.
+- **Q4.2 Extra keys:** keys the LLM emits that aren't in the
+  detected placeholders are **warned** to stderr (not dropped
+  silently). The LLM gets a fresh list of allowed keys in the
+  prompt so this is rare in practice.
+- **Q4.3 Auto-LLM:** `--from-deal` does **not** require an
+  explicit `--llm` flag — the inference is implicit. `--no-llm`
+  still disables it (the user can opt out of the network call).
+
+### Notes
+
+- `--from-deal` errors are fatal (`EXIT.LLM` for provider /
+  network / parse failures). Users with bad provider configs see
+  the issue immediately rather than silently running with no
+  inferred values.
+- Bundle mode (v0.7.0) does not yet thread `--from-deal` through
+  per-template inference. Deferred to a follow-up; the shared
+  parameter resolution makes the single-doc API already useful
+  for bundles via `--params`.
+
 ## 0.7.0 — 2026-05-17
 
 ### Added

package/PARAM_SCHEMA.md

@@ -515,6 +515,71 @@ keys and their sources.
 Programmatic API: `loadBundle(path)` parses + validates; `cmdBundle`
 runs the orchestration with the same IO contract as `cmdDraft`.
 
+### LLM inference from a deal description (v0.8.0, opt-in)
+
+`--from-deal PATH` reads a free-form deal description and asks the
+configured T5 LLM provider to extract values for the schema's
+declared placeholders. The inverse of T5 detection — instead of
+inferring *where* placeholders are in a template, infer *what
+values* they should take from the deal prose:
+
+```sh
+draft nda.md --from-deal deal-notes.txt --output draft.md
+```
+
+```
+# deal-notes.txt
+Mutual NDA between Acme Corporation (DE) and Globex (UK),
+effective June 1, 2026, for a 2-year term.
+```
+
+Then `[Party A]` → `Acme Corporation`, `[Effective Date]` →
+`June 1, 2026`, etc., without any `--party-a` / `--effective-date`
+flags.
+
+**Value-resolution precedence** with `--from-deal`:
+
+```
+CLI flag  >  --params JSON  >  --from-deal (LLM)  >  --interactive  >  schema default  >  error
+```
+
+CLI / --params always win, so users can fix or override anything the
+LLM got wrong without re-running inference.
+
+**Q4.1 locked:** same T5 provider config (`ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, or explicit `DRAFT_LLM_*`). One network surface,
+one set of env vars.
+
+**Q4.2 locked:** extra keys (LLM emits keys not in the detected
+placeholder list) are **warned** to stderr, not silently dropped.
+The LLM gets the allowed-key list in the prompt so this is rare in
+practice.
+
+**Q4.3 locked:** `--from-deal` does **not** require explicit
+`--llm` — the inference is implicit when the flag is present.
+`--no-llm` still disables the inference call (the user can opt
+out of the network).
+
+**Provider missing:** if no LLM provider is configured (no
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `DRAFT_LLM_*` in env),
+`--from-deal` errors immediately with `EXIT.LLM` (exit 5) and a
+clear message. Same for network / HTTP errors / non-JSON LLM
+responses.
+
+**Resolution interaction with typed parameters:** inferred values
+go through the same typed-normalization step as user-supplied
+values. So an LLM that returns `"June 1, 2026"` for a `type: date`
+parameter with `format: yyyy-MM-d` gets normalized to `2026-06-1`
+before substitution.
+
+**Bundle mode (v0.7.0) interaction:** bundles do not currently
+thread `--from-deal` through per-template inference. The shared
+parameter resolution already accepts `--params` JSON, which is the
+simpler structured-data path for bundle workflows. Deferred to a
+future release.
+
+Programmatic API: `inferFromDeal(dealText, placeholders, providerCfg, { fetcher })`.
+
 ### Orphan handling (Q4 locked)
 
 Schema declares a key whose alias list matches no detected phrase →

package/README.md

@@ -1,62 +1,64 @@
+<p align="center">
+  <img src="assets/icon.svg" width="120" alt="draft-cli">
+</p>
+
 # 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.
+> Part of the contract-operations CLI suite. **draft-cli** (fill placeholders) → [**nda-review-cli**](https://github.com/DrBaher/nda-review-cli) (review, redline, negotiate) → [**docx2pdf-cli**](https://github.com/DrBaher/docx2pdf-cli) (DOCX → PDF) → [**sign-cli**](https://github.com/DrBaher/sign-cli) (signing + audit). [Showcase site](https://cli.drbaher.com/).
 
-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)).
+[![npm version](https://img.shields.io/npm/v/@drbaher/draft-cli.svg)](https://www.npmjs.com/package/@drbaher/draft-cli)
+[![npm downloads](https://img.shields.io/npm/dw/@drbaher/draft-cli.svg)](https://www.npmjs.com/package/@drbaher/draft-cli)
+[![CI](https://github.com/DrBaher/Draft-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/DrBaher/Draft-CLI/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
----
+Agent-first placeholder-filler for legal-document templates. Reads bracketed (`[Party A]`) or mustache markup, `.docx` yellow highlights, or generic-name heuristics; substitutes from CLI flags, a JSON params file, a shared `parties.json` registry, or — optionally — values extracted by an LLM from a free-form deal description; writes a ready-to-review draft as text or `.docx` (round-trip, runs and styles preserved). Schema-declared placeholders can be **typed** (`date` / `money` / `party`), **computed** (date arithmetic from another placeholder), **positional** (same text disambiguated by role), and **bundled** (fill multiple templates with one set of values).
 
-## What it does
+**The asymmetry is the architecture**: every step is deterministic and machine-driven except the values themselves — which can come from a flag, a params file, a parties registry, or an LLM extracting them from a prose deal description that a human wrote.
 
-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.
+## Run this
 
-```
-template-vault get nda/house-mutual | draft - \
-    --party-a "Acme Corporation" \
-    --party-b "Vendor Inc." \
-    --effective-date 2026-06-01 \
-    --output draft.md
+```bash
+npx @drbaher/draft-cli@latest --demo
 ```
 
-Or via a params file:
+30 seconds, no file authoring required. Walks through a bracketed-template NDA with three placeholders, demoing the full cascade end-to-end. Or if you want to dive into a real template:
 
-```
-draft nda/house-mutual --params deal-acme.json --output draft.md
+```bash
+npm i -g @drbaher/draft-cli
+draft --list-placeholders examples/cp-mutual-nda-coverpage.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.
+## Where to go next
 
----
+| If you are… | Start here |
+|---|---|
+| **A new user** evaluating the tool | This README's [Quick start](#quick-start) and [What this gives you](#what-this-gives-you) |
+| **A drafter** filling your first template | [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walkthrough of the main flows |
+| **An LLM agent** driving the CLI | [AGENTS.md](AGENTS.md) → `draft --list-placeholders --json` → [PARAM_SCHEMA.md](PARAM_SCHEMA.md) for the locked contract |
+| **A schema author** declaring typed / computed / positional placeholders | [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5 |
+| **A contributor** | [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md) |
 
-## Install
+Concept deep-dives live in [PARAM_SCHEMA.md](PARAM_SCHEMA.md) (the v1 + v2 contract); architecture in [ARCHITECTURE.md](ARCHITECTURE.md); FAQ in [FAQ.md](FAQ.md).
 
-```sh
-npm install -g @drbaher/draft-cli
-```
+## Quick start
 
-Or run without installing:
+```bash
+# Install
+npm i -g @drbaher/draft-cli
 
-```sh
+# Or run without installing
 npx @drbaher/draft-cli@latest --demo
+
+# After install, the binary is named `draft`
+draft --version
+draft --demo
 ```
 
 Requires Node.js ≥ 18. Tested on Ubuntu and macOS, Node 18 / 20 / 22.
 
 ### Shell completion
 
-```sh
+```bash
 # bash
 draft --completion bash >> ~/.bashrc
 
@@ -65,40 +67,22 @@ 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.
+Completes flags, the `--syntax bracket|mustache` value, `--completion bash|zsh`, and file paths for `--params`, `--output`, `--dictionary`, `--parties`, `--bundle`, `--from-deal`.
 
-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.
+## What this gives you
 
----
+- **Five-tier detection cascade** — `[Title Case]` brackets / `{{mustache}}` / `.docx` highlights (yellow/green/cyan/magenta) / heuristic dictionary / optional LLM. First tier with hits wins; the rest are skipped. Deterministic through tier 4.
+- **`.docx` round-trip** — read a `.docx` template, fill placeholders, write `<basename>-filled.docx` with runs/styles/paragraph-breaks preserved. T3 highlight detection works against real templates (Common Paper, YC SAFE).
+- **Schema file** for canonical keys, alias phrases, defaults, required-ness, and the v2 fields below (`type`, `format`, `currency`, `computed`, `positions`). Without a schema, every detected bracketed phrase is treated as a required parameter.
+- **Typed parameters** — `type: date | money | party` validates and normalizes inputs before substitution. `"01/15/2027"` → `"January 15, 2027"`; `"$5M"` → `"$5,000,000.00"`. Bad inputs exit 4 with per-key error.
+- **Computed placeholders** — derive one placeholder's value from another via date arithmetic: `{ "from": "effective_date", "op": "+", "value": "2 years" }`. Cycle detection at schema parse time.
+- **Positional addressing** — same placeholder text with different semantic roles, addressed by position. Validated against the YC SAFE `$[_____________] × 2` case.
+- **`parties.json` registry** — declare known parties once; schemas reference `ref:parties.<key>.<field>`. Eliminates duplicating party metadata across templates.
+- **Multi-document bundles** — fill multiple templates with one shared set of values: `draft --bundle deal.bundle.json --params deal.json`. Abort-all on any pre-write error.
+- **LLM-from-deal inference** — `--from-deal PATH` reads a free-form deal description and asks the configured T5 provider (Anthropic / OpenAI / `DRAFT_LLM_*`) to fill the schema's parameters. CLI / `--params` still win over inferred values.
+- **Composable I/O** — stdin (`-`), stdout default, `--output PATH`, `template-vault get` integration for `<category>/<name>[@version]` template refs.
+- **Three modes** — `draft` (substitute and emit), `--list-placeholders` (enumerate), `--validate` (completeness check). All support `--json` and `--why`.
+- **Single file, stdlib + `jszip`**, no telemetry, local-first. Network only when the LLM tier is explicitly configured.
 
 ## End-to-end transcript
 
@@ -139,12 +123,9 @@ 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.
+`draft-cli` finds placeholders by trying five strategies in order. The **first non-empty tier wins** and the others are skipped.
 
 | Tier | Strategy             | When                                      |
 | ---- | -------------------- | ----------------------------------------- |
@@ -154,45 +135,32 @@ ok
 | 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.
+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`):
+A sibling `<template>.params.json` lets you declare canonical keys, alias phrases, defaults, and required-ness. The **long form** (gated on `_meta`) unlocks the v2 fields:
 
 ```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" }
+  "party_a":         { "aliases": ["Party A"], "required": true, "type": "party" },
+  "effective_date":  { "aliases": ["Effective Date"], "type": "date", "format": "MMMM d, yyyy" },
+  "term_end":        { "aliases": ["Term End"], "type": "date",
+                       "computed": { "from": "effective_date", "op": "+", "value": "2 years" } },
+  "purchase_amount": { "aliases": ["Purchase Amount"], "type": "money", "currency": "USD" },
+  "blank":           { "aliases": ["_____________"], "type": "money", "currency": "USD",
+                       "positions": [{ "role": "valuation_cap" }, { "role": "purchase_amount" }] }
 }
 ```
 
-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.
+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.
+
+The **short form** is just an aliases map: `{ "party_a": ["Party A"] }`.
 
----
+See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5 for the full schema contract and the locked design decisions per v2 feature.
 
 ## Command reference
 
@@ -203,10 +171,15 @@ 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
+draft --bundle <bundle.json>  multi-doc bundle mode (v0.7.0)
 
 OPTIONS
   --params FILE          JSON file of param values (snake_case keys)
-  -o, --output PATH      write to PATH (default: stdout)
+  --parties PATH         parties.json registry for ref:parties.<key>.<field>  (v0.6.0)
+  --bundle PATH          fill multiple templates in one invocation             (v0.7.0)
+  --from-deal PATH       LLM-extract values from a free-form deal description  (v0.8.0)
+  -o, --output PATH      write to PATH (default: stdout). `-` forces stdout.
+                         For .docx input, default is <basename>-filled.docx   (v0.2.0)
   --syntax bracket|mustache
   -i, --interactive      prompt for missing required parameters
   --why                  structured explanation to stderr
@@ -214,7 +187,7 @@ OPTIONS
   -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
+  --no-llm               disable tier 5 + --from-deal 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
@@ -224,81 +197,46 @@ OPTIONS
   -V, --version          show version
 ```
 
-Exit codes: `0` ok · `1` i/o · `2` validation · `3` template-vault failure
-· `4` llm failure.
-
----
+Exit codes: `0` ok · `1` i/o · `2` validation · `3` template-vault failure · `4` schema validation / typed parameter / computed / ref / positional · `5` 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).
+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.
+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.
 
----
+**v0.8.0 inverse direction — `--from-deal PATH`:** feed prose deal notes and the LLM extracts values for the schema's placeholders (instead of inferring where placeholders are). Uses the same provider config. Errors on provider missing, network failure, or non-JSON response. CLI / `--params` values always win over LLM-inferred ones. See [PARAM_SCHEMA.md](PARAM_SCHEMA.md) §5.
 
 ## 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:
+`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 \
+```bash
+# Pull a versioned template, fill it, hand it to review, convert to PDF, sign.
+template-vault get nda/house-mutual@v3 \
+  | draft - --from-deal deal-notes.txt --parties parties.json \
+  | nda-review --redline \
   | docx2pdf - draft.pdf
+sign-cli send draft.pdf --signer counsel@counterparty.com
 ```
 
-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.
-
----
+Each tool stays small and replaceable. None of them know about each other beyond the standard `stdin / stdout / argv / exit codes` contract.
 
 ## Documentation
 
-- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walk-through of every flow.
+- [GETTING_STARTED.md](GETTING_STARTED.md) — 10-minute walkthrough of the main flows.
 - [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.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the cascade, schema, and substitution pipeline fit together.
+- [PARAM_SCHEMA.md](PARAM_SCHEMA.md) — v1 + v2 schema contract; locked decisions per feature.
+- [FAQ.md](FAQ.md) — common questions about detection rules, T4 heuristics, and the LLM tier.
+- [V2_BRIEFS_REMAINING.md](V2_BRIEFS_REMAINING.md) — design briefs for the four v2 items shipped after v0.1.x; historical now that all four have landed.
+- [SECURITY.md](SECURITY.md) — reporting vulnerabilities.
+- [CHANGELOG.md](CHANGELOG.md) — every shipped version with locked design decisions.
 
 ## License
 

package/draft-cli.mjs

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
  */
 
 /** @type {string} */
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.1";
 
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**
@@ -279,6 +279,7 @@ export function parseArgs(argv) {
     if (a === "--params") { opts.params = argv[++i]; continue; }
     if (a === "--parties") { opts.parties = argv[++i]; continue; }
     if (a === "--bundle") { opts.bundle = argv[++i]; continue; }
+    if (a === "--from-deal") { opts.fromDeal = argv[++i]; continue; }
     if (a === "--output" || a === "-o") { opts.output = argv[++i]; continue; }
     if (a === "--syntax") {
       const v = argv[++i];
@@ -808,6 +809,95 @@ ${body.slice(0, 12000)}`;
   return out;
 }
 
+/**
+ * v2 #4: LLM inference from a free-form deal description.
+ *
+ * Takes the prose deal description (the user's notes about parties, dates,
+ * amounts, etc.) and asks the configured T5 LLM provider to extract values
+ * for the placeholders the cascade has already detected. Returns
+ * `{values, extraKeys, warnings}`:
+ *
+ *   - values: `{key: string}` for every placeholder key the LLM filled
+ *   - extraKeys: any keys the LLM emitted that aren't in the placeholders list (Q4.2 → warn)
+ *   - warnings: human-readable messages for malformed entries
+ *
+ * Throws on missing provider config, missing `fetch`, network/HTTP error, or
+ * non-JSON LLM response — same failure boundaries as `detectLlm`.
+ *
+ * @param {string} dealText — free-form deal description
+ * @param {Placeholder[]} placeholders — the post-detection placeholder list
+ * @param {ReturnType<llmProviderFromEnv>} providerCfg
+ * @param {{ fetcher?: typeof fetch | null }} [opts]
+ * @returns {Promise<{ values: Object<string,string>, extraKeys: string[], warnings: string[] }>}
+ */
+export async function inferFromDeal(dealText, placeholders, providerCfg, { fetcher = (typeof fetch !== "undefined" ? fetch : null) } = {}) {
+  if (!fetcher) {
+    const e = new Error("fetch is not available; Node 18+ is required for --from-deal");
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  if (!providerCfg) {
+    const e = new Error("--from-deal requires an LLM provider; set ANTHROPIC_API_KEY / OPENAI_API_KEY / DRAFT_LLM_* in .env");
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  const wantedKeys = placeholders.map((p) => ({
+    key: p.key,
+    aliases: (p.aliases || []).slice(0, 4),
+    first_seen_as: p.first_seen_as,
+  }));
+  if (wantedKeys.length === 0) {
+    return { values: {}, extraKeys: [], warnings: [] };
+  }
+  const fieldList = wantedKeys.map((w) =>
+    `  - ${w.key} (template placeholder: "${w.first_seen_as}"${w.aliases.length > 1 ? `; aliases: ${w.aliases.join(", ")}` : ""})`
+  ).join("\n");
+  const prompt = `You are filling parameters for a legal-document drafting tool.
+A user has written prose describing a deal. Extract values for the following
+fields from the deal description. Output JSON ONLY in this exact shape, with
+no commentary:
+
+{"values":{"<key>":"<extracted_value>",...}}
+
+If a field can't be confidently extracted from the description, omit it (do
+NOT guess). Do not invent additional fields not in the list. Match the deal's
+language verbatim — don't reformat dates, currencies, or names.
+
+FIELDS:
+${fieldList}
+
+DEAL DESCRIPTION:
+${dealText.slice(0, 12000)}`;
+  const raw = await callLlm(providerCfg, prompt, fetcher);
+  let parsed;
+  try {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    parsed = JSON.parse(jsonMatch ? jsonMatch[0] : raw);
+  } catch {
+    const e = new Error(`LLM returned non-JSON response for --from-deal`);
+    e.exitCode = EXIT.LLM;
+    throw e;
+  }
+  const rawValues = (parsed && typeof parsed.values === "object" && parsed.values) ? parsed.values : {};
+  const knownKeys = new Set(placeholders.map((p) => p.key));
+  const values = {};
+  const extraKeys = [];
+  const warnings = [];
+  for (const [k, v] of Object.entries(rawValues)) {
+    if (!knownKeys.has(k)) {
+      extraKeys.push(k);
+      continue;
+    }
+    if (v === null || v === undefined) continue;
+    if (typeof v !== "string" && typeof v !== "number") {
+      warnings.push(`--from-deal: value for "${k}" was ${typeof v}, expected string; skipped`);
+      continue;
+    }
+    values[k] = String(v);
+  }
+  return { values, extraKeys, warnings };
+}
+
 async function callLlm(cfg, prompt, fetcher) {
   if (cfg.provider === "anthropic") {
     const r = await fetcher("https://api.anthropic.com/v1/messages", {
@@ -1460,7 +1550,7 @@ export function loadBundle(path) {
  * @param {{ prompter?: (p: Placeholder) => Promise<string|null> }} [io]
  * @returns {Promise<ResolvedValues>}
  */
-export async function resolveValues(placeholders, opts, paramsObj, { prompter = nodePrompter } = {}) {
+export async function resolveValues(placeholders, opts, paramsObj, { prompter = nodePrompter, inferred = null } = {}) {
   const resolved = {};
   const missing = [];
   const sources = {};
@@ -1475,6 +1565,12 @@ export async function resolveValues(placeholders, opts, paramsObj, { prompter =
       sources[p.key] = "params";
       continue;
     }
+    // v2 #4: --from-deal LLM-inferred values, between --params and --interactive.
+    if (inferred && Object.prototype.hasOwnProperty.call(inferred, p.key)) {
+      resolved[p.key] = String(inferred[p.key]);
+      sources[p.key] = "deal-llm";
+      continue;
+    }
     if (opts.interactive) {
       const v = await prompter(p);
       if (v !== null && v !== undefined && v !== "") {
@@ -2089,7 +2185,7 @@ export async function cmdListPlaceholders(opts, input, schema, envObj, { fetcher
   return EXIT.OK;
 }
 
-export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
+export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null, dealText = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     err.write(paint("error: no placeholders detected by any tier\n", "red", err));
@@ -2109,7 +2205,24 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     }
     return EXIT.VALIDATION;
   }
-  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj);
+  // v2 #4: --from-deal LLM inference (when dealText is present and
+  // --no-llm not set). Provider config comes from env. Errors are fatal
+  // to keep the user from running with partial inferred values.
+  let inferred = null;
+  if (dealText && !opts.noLlm) {
+    try {
+      const r = await inferFromDeal(dealText, result.placeholders, llmProviderFromEnv(envObj), { fetcher });
+      inferred = r.values;
+      for (const k of r.extraKeys) {
+        err.write(paint(`warning: --from-deal LLM emitted unknown key "${k}" (not in template/schema)\n`, "yellow", err));
+      }
+      for (const w of r.warnings) err.write(paint(`warning: ${w}\n`, "yellow", err));
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.LLM;
+    }
+  }
+  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj, { inferred });
   if (missing.length > 0) {
     printMissing(missing, err);
     if (opts.json) {
@@ -2170,7 +2283,7 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
   return EXIT.OK;
 }
 
-export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
+export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null, dealText = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     const hasProvider = Boolean(llmProviderFromEnv(envObj));
@@ -2221,7 +2334,25 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     return EXIT.VALIDATION;
   }
 
-  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj);
+  // v2 #4: --from-deal LLM inference (when dealText is present and
+  // --no-llm not set). Provider config comes from env. Errors are fatal
+  // to keep the user from running with partial inferred values.
+  let inferred = null;
+  if (dealText && !opts.noLlm) {
+    try {
+      const r = await inferFromDeal(dealText, result.placeholders, llmProviderFromEnv(envObj), { fetcher });
+      inferred = r.values;
+      for (const k of r.extraKeys) {
+        err.write(paint(`warning: --from-deal LLM emitted unknown key "${k}" (not in template/schema)\n`, "yellow", err));
+      }
+      for (const w of r.warnings) err.write(paint(`warning: ${w}\n`, "yellow", err));
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.LLM;
+    }
+  }
+
+  const { resolved, missing, sources } = await resolveValues(result.placeholders, opts, paramsObj, { inferred });
   // Footgun guard: flag --typo'd-key VALUE that didn't match any detected
   // placeholder. Without this warning, a typo'd flag is silently dropped and
   // the user sees only a "missing required" error without the connection.
@@ -2839,13 +2970,22 @@ export async function main(argv, io = {}) {
     return EXIT.IO;
   }
 
-  let input, schema, paramsObj, envObj, parties;
+  let input, schema, paramsObj, envObj, parties, dealText;
   try {
     input = await resolveInput(opts.positional[0], { spawner, stdinReader });
     schema = loadSchema(input.path);
     paramsObj = loadParamsFile(opts.params);
     envObj = effectiveEnv(cwd, processEnv);
     parties = loadParties(opts.parties || null);
+    // v2 #4: --from-deal PATH reads a free-form deal description.
+    if (opts.fromDeal) {
+      if (!existsSync(opts.fromDeal)) {
+        const e = new Error(`deal description file not found: ${opts.fromDeal}`);
+        e.exitCode = EXIT.IO;
+        throw e;
+      }
+      dealText = readFileSync(opts.fromDeal, "utf8");
+    }
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;
@@ -2856,9 +2996,9 @@ export async function main(argv, io = {}) {
       return await cmdListPlaceholders(opts, input, schema, envObj, { fetcher, out, err });
     }
     if (opts.validate) {
-      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
+      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties, dealText });
     }
-    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
+    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties, dealText });
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drbaher/draft-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Fill placeholders in a legal-document template with parameter values. Part of the contract-operations suite.",
   "type": "module",
   "bin": {