@navels/neal 0.1.0

package/docs/compat.md

@@ -0,0 +1,269 @@
+# `neal compat` — model compatibility smoke test
+
+`neal compat` answers one question per model: **can this OpenAI-compatible model
+drive neal's loop at all** — as a coder, a reviewer, or a planner? It is a
+**compatibility smoke test, not a performance benchmark**. There is no
+resolve-rate, no score, no ranking, and no real SWE-bench repo involved. The
+fixtures are deliberately trivial; any working agent should pass them. A failure
+therefore means something is **fundamentally wrong** with the model's ability to
+operate neal's contract — not that a task was hard.
+
+`neal compat` is fully self-contained in the neal repo. The only things an
+operator needs to qualify a model are the neal checkout plus an API key — no
+external benchmark assets, no dataset download, no remote runner.
+
+## Compatibility, not skill
+
+- **Measured:** whether the model can follow neal's contract end to end (valid
+  tool calls + structured output, no max-step loops, no unresolved operator
+  blocks, a clean finalization) **and** solve a trivial bundled fixture.
+- **Not measured:** skill. No resolve-rate, no scores, no rankings, no real
+  SWE-bench repos — trivial fixtures only.
+- **Outcome:** a binary **PASS / FAIL per (model, role)**, with a structural
+  failure mode recorded for every FAIL.
+
+## How it layers with `neal check`
+
+`neal check` and `neal compat` are two distinct gates:
+
+- **`neal check`** validates the effective config and confirms each configured
+  role's provider can answer one small structured probe
+  (`provider_check_payload`). It proves *connectivity and basic protocol*, not
+  that the model can complete a full neal run. When the resolved **coder or
+  reviewer** role uses a non-native (generic-agentic / openai-compatible)
+  provider, `neal check` prints a one-line pointer: *"This is a generic-agentic
+  model - run `neal compat` to confirm it can drive the full loop."* Native
+  adapters (`openai-codex`, `anthropic-claude`) do not get the pointer. The
+  planner inherits the coder provider by default, so the coder check covers the
+  common case; an explicitly configured non-native planner paired with native
+  coder/reviewer is not separately flagged (run `neal compat --role planner`
+  to qualify it).
+- **`neal compat`** runs the same structured pre-filter first (it reuses
+  `check`'s `verifyConfiguredProviders`), then drives the model through complete
+  neal runs against the bundled fixtures and produces a PASS/FAIL matrix.
+
+So: `neal check` is the cheap connectivity gate; `neal compat` is the full-loop
+qualification gate that `check` points generic-agentic users toward.
+
+## Usage
+
+```bash
+neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|generic-agentic:<slug>] [--json]
+```
+
+- `--role` (default `all`) selects which role(s) to test: `coder`, `reviewer`,
+  `planner`, or `all`.
+- `--model <slug>` runs the slug on the **`generic-agentic`** provider in the
+  candidate role (provider forced to `generic-agentic`, any configured effort
+  dropped, so the slug drives a clean OpenRouter call). When omitted, the
+  candidate role uses its configured provider/model unchanged.
+- `--reference <id>` names the provider for the **non-candidate** roles so a
+  FAIL is attributable to the candidate in the tested role, not to a weak (and
+  possibly flaky) partner. Accepted forms: a native provider id — `openai-codex`
+  (the default when omitted while `--model` is set) or `anthropic-claude` — or
+  `generic-agentic:<openrouter-model>` to run the reference roles on an
+  OpenRouter model. A bare model slug is rejected. Native reference roles run on
+  that adapter's default model (`gpt-5.5` for `openai-codex`, `claude-opus-4-8`
+  for `anthropic-claude`). Prefer a native reference for whitelist
+  qualification; see [compatible-models.md](compatible-models.md) for why
+  OpenRouter references proved unreliable as qualification partners. When
+  **neither** `--model` nor `--reference` is given, every role stays on its
+  configured provider/model (pure pass-through).
+- `--json` prints the stable machine-readable matrix instead of the human table
+  (schema below).
+
+The command resolves its base config via the same writer-provider resolver the
+other commands use, then derives a candidate config by cloning it and routing the
+tested role onto `generic-agentic` (when `--model` is set) and the non-candidate
+roles onto the native reference adapter (when either flag is set). It runs
+against **throwaway git copies** of the bundled fixtures and **never mutates** a
+committed fixture under `examples/compat/`. The process exits non-zero when the
+overall result is FAIL.
+
+Example (Phase B operational usage, OpenRouter paid slug with a native reference):
+
+```bash
+neal compat --model deepseek/deepseek-chat --role all --reference openai-codex --json
+```
+
+## Bundled fixtures (`examples/compat/`)
+
+Each fixture is a tiny self-contained project. `examples/compat/manifest.json`
+is the single data source that makes the command data-driven. The shipped
+fixtures are:
+
+| Fixture | Roles | Contract surface |
+| --- | --- | --- |
+| `add-edit-verify` | coder, reviewer | edit + verify + commit |
+| `reverse-grep-edit` | coder, reviewer | read/grep-then-edit |
+| `is-even-add-test` | coder, reviewer | add-a-test |
+| `plan-greeting` | planner | emit a `one_shot` plan |
+
+Each coder fixture bundles buggy source, a test that fails against the buggy
+source, and a `PLAN.md` declaring `executionShape: one_shot` that describes the
+smallest complete fix. The reviewer fixtures reuse the same projects, each paired
+with two pre-made unified diffs (`good.diff`, `broken.diff`). The planner fixture
+provides an issue-statement seed (`ISSUE.md`) and no reviewer diffs.
+
+`examples/issue-triage-js` remains an optional tier-2 "real-ish" check above the
+trivial gate; `neal compat` does not require it.
+
+### Manifest schema
+
+```jsonc
+{
+  "fixtures": [
+    {
+      "id": "add-edit-verify",
+      "roles": ["coder", "reviewer"],          // which roles use this fixture
+      "projectDir": "add-edit-verify",          // relative to examples/compat/
+      "planDoc": "add-edit-verify/PLAN.md",     // coder run plan (one_shot)
+      "verifyCommand": "node --test test/add.test.js", // coder PASS check
+      "referenceFix": { "file": "src/add.js", "from": "a - b", "to": "a + b" },
+      "reviewer": {
+        "goodDiff": "add-edit-verify/good.diff",   // reviewer must ACCEPT
+        "brokenDiff": "add-edit-verify/broken.diff" // reviewer must FLAG/REJECT
+      }
+    }
+  ]
+}
+```
+
+A planner fixture sets `"roles": ["planner"]` and provides `"issuePrompt"`
+instead of `reviewer`. Any fixture carrying the `reviewer` role must also define
+`verifyCommand`: reviewer fixtures reuse the coder project's command as the
+deterministic good/broken oracle — `goodDiff` must make it pass, `brokenDiff`
+must make it fail. The `referenceFix` is used only by the structural fixture
+self-test (`test/compat-fixtures.test.ts`), never by a model run.
+
+## Definition of PASS (per model, per role)
+
+Across **every** fixture for the role, the model must (1) **complete the run
+cleanly** — the run reaches `status: 'done'` (not `'failed'` / `'blocked'`), does
+not emit an `unattended.block_unresolved` event, and does not exceed its
+step/round budget — **and** (2) produce the **role-correct result**:
+
+- **coder:** `finalState.status === 'done'` **and** the fixture's
+  `verifyCommand` exits `0` in the throwaway worktree (the failing test now
+  passes).
+- **reviewer:** the review-findings loop converges (`outcome === 'accepted'`) for
+  **both** diffs, and the converged findings discriminate them: **zero** blocking
+  findings for the good diff and **≥1** blocking finding (a `ReviewFindingItem`
+  with `severity === 'blocking'`) for the broken diff. `outcome` alone is not
+  sufficient — it is `'accepted'` whenever the findings artifact converges,
+  including a zero-finding artifact — so the good/broken verdict is scored on
+  `draft.findings` severities.
+- **planner** (secondary): the emitted plan document validates via
+  `validatePlanDocument` as a schema-conformant `one_shot` plan.
+
+Any single fundamental failure on any fixture for the role → **FAIL** for that
+role, with the mode recorded.
+
+`neal compat` forces **unattended mode** on every run so a model is never
+penalized for a halt that a human operator would simply have resumed.
+
+## Failure-mode taxonomy
+
+Each FAIL records a mode derived from **structural run state** — `finalState.status`,
+emitted run events, `ReviewFindingsOutcome`, and `validatePlanDocument` — never
+from substring-matching model prose. When more than one applies, the earliest in
+this list (most specific cause first) is recorded:
+
+- `protocol` — the `verifyConfiguredProviders` pre-filter threw for the candidate
+  (it could not emit one valid `provider_check_payload`); fixtures were skipped.
+- `provider_failed` — the run failed with a model-attributable provider error
+  event (transport/auth/transient/other) rather than a clean completion, **except**
+  a provider error whose `errorKind` is a structured-output kind, which is recorded
+  as `structured_output` (below). This is also the bucket for a **writer** run that
+  ends `status: 'failed'` without a more specific structural signal — including
+  step/round-budget exhaustion, which the current runtime does not surface to compat
+  as a distinct cap event, so writer step-cap exhaustion is reported here rather than
+  as `max_step_loop`.
+- `block_unresolved` — the run emitted `unattended.block_unresolved` (the model
+  escalated to an operator block unattended mode could not resolve within budget),
+  or the review loop's outcome was `'blocked'`.
+- `max_step_loop` — the **reviewer** loop's outcome was `'cap_reached'` (the
+  review-findings convergence cap was hit). Writer (coder/planner) step-cap
+  exhaustion is not separately distinguishable under the current runtime and is
+  classified as `provider_failed` (above).
+- `wrong_or_empty_output` — coder: the run reached `done` but `verifyCommand`
+  exited non-zero (or the diff was empty); reviewer: the verdict was wrong
+  (accepted the broken diff with no blocking finding, or flagged the good diff
+  with a blocking finding); planner: the emitted plan was not a schema-conformant
+  `one_shot` plan.
+- `structured_output` — the model could not produce or honor **schema-enforced**
+  JSON. This covers a reviewer/planner round whose payload failed schema validation
+  (surfaced as the corresponding round error) **and** a coder/reviewer provider
+  error whose `errorKind` is `structured_output_invalid` or
+  `structured_output_missing` — e.g. an OpenRouter (generic-agentic) gateway that
+  rejects the `type: 'json_schema'` request (HTTP 400) or returns a missing/invalid
+  object. This is distinct from `provider_failed` (transport/auth/other transport
+  errors) and from `wrong_or_empty_output` (a syntactically valid verdict/output
+  that was substantively wrong). Both the coder (`classifyWriterFailure`) and
+  reviewer (`classifyReviewerThrownFailure`) paths attribute these kinds here.
+- `finalization_error` — the run failed during finalization/artifact writing, or
+  the run produced no final document where one was expected.
+
+When no structural signal is conclusive, `provider_failed` is recorded with the
+terminal error message attached.
+
+## Output
+
+By default `neal compat` prints a human-readable matrix: one row per
+role × fixture cell (with the reviewer `good`/`broken` diff kind), a per-role
+roll-up, and an overall verdict.
+
+### `--json` schema
+
+`--json` prints a single JSON object. This shape is stable and feeds the Phase B
+whitelist (`docs/compatible-models.md`):
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "model": "deepseek/deepseek-chat",   // candidate --model, or null when omitted
+  "reference": null,                    // native provider id (openai-codex | anthropic-claude), or null when omitted
+  "role": "all",                        // coder | reviewer | planner | all
+  "candidateProviders": {               // provider each role used as the candidate: "generic-agentic" per role when --model is set, else the configured provider
+    "coder": "generic-agentic",
+    "reviewer": "generic-agentic",
+    "planner": "generic-agentic"
+  },
+  "cells": [
+    {
+      "role": "coder",                  // coder | reviewer | planner
+      "fixtureId": "add-edit-verify",   // manifest id; "provider:<role>" for a protocol pre-filter FAIL
+      "diffKind": null,                 // "good" | "broken" for reviewer cells, else null
+      "pass": true,
+      "failureMode": null,              // one of the taxonomy modes when pass=false, else null
+      "detail": null                    // human-readable explanation when pass=false, else null
+    }
+  ],
+  "roles": [
+    {
+      "role": "coder",
+      "pass": true,
+      "cellCount": 3,                   // cells for this role
+      "passCount": 3                    // cells that passed
+    }
+  ],
+  "overallPass": true                   // true iff every targeted role's roll-up passed
+}
+```
+
+A role roll-up is PASS iff it has at least one cell and every one of its cells
+passed. `overallPass` is true iff every targeted role roll-up passed. The process
+exits non-zero when `overallPass` is false.
+
+## Cost
+
+Cheap by construction: trivial fixtures and cheap models. If qualifying a model
+gets expensive, the fixture set is too big.
+
+## Phase B — building the whitelist
+
+With a provider configured (OpenRouter **paid** slugs only, never `:free`) and a
+known-good `--reference`, run `neal compat --model <slug> --role all --json` for
+each candidate and fill the dated [`compatible-models.md`](compatible-models.md)
+matrix from the JSON output. Date and version the matrix — model behavior drifts,
+so re-run on version bumps.

package/docs/compatible-models.md

@@ -0,0 +1,135 @@
+# Compatible models
+
+> **Last updated:** 2026-06-18 · **Reference:** `openai-codex` (gpt-5.5) · **Pool:** 79 OpenRouter models
+>
+> The whitelist from running [`neal compat`](compat.md) across an OpenRouter candidate
+> pool. It records **compatibility, not skill**: a PASS means the model can drive neal's
+> loop on the trivial bundled fixtures in that role — it says nothing about how well the
+> model performs on real work. Choose among the PASSes by your own cost/quality needs.
+
+## How to read this
+
+- A PASS means the model drove neal under **real schema-enforced structured output**
+  (`type: 'json_schema'`), with `openai-codex` (gpt-5.5) running the non-tested roles as a
+  known-good partner. Role cells = passed/total fixtures (coder 3, reviewer 6, planner 1).
+- A FAIL is **attributable** to the model via its [failure mode](compat.md#failure-mode-taxonomy)
+  (e.g. `structured_output`, not a generic `provider_failed`).
+- **Single-run results are noisy at the margin.** Models that fail only 1–2 cells, or fail
+  with `provider error`, often flip on a re-run — treat the "borderline" table as *re-run
+  candidates*, not verdicts.
+- Native adapters (`openai-codex`, `anthropic-claude`) are supported by construction and
+  need no compat run.
+
+## ✅ Compatible (25) — verified across all roles
+
+Sorted cheapest first ($/Mtok in·out, from the live OpenRouter catalog).
+
+| Model | Coder | Reviewer | Planner | $/Mtok | ctx |
+|---|---|---|---|---|---|
+| `google/gemma-4-26b-a4b-it` | 3/3 | 6/6 | 1/1 | 0.06·0.33 | 262k |
+| `inclusionai/ling-2.6-1t` | 3/3 | 6/6 | 1/1 | 0.07·0.62 | 262k |
+| `deepseek/deepseek-v4-flash` | 3/3 | 6/6 | 1/1 | 0.09·0.18 | 1048k |
+| `nvidia/nemotron-3-super-120b-a12b` | 3/3 | 6/6 | 1/1 | 0.09·0.45 | 1000k |
+| `google/gemma-4-31b-it` | 3/3 | 6/6 | 1/1 | 0.12·0.35 | 262k |
+| `qwen/qwen3.6-35b-a3b` | 3/3 | 6/6 | 1/1 | 0.14·1.00 | 262k |
+| `minimax/minimax-m2.5` | 3/3 | 6/6 | 1/1 | 0.15·0.90 | 204k |
+| `deepseek/deepseek-chat-v3.1` | 3/3 | 6/6 | 1/1 | 0.21·0.79 | 163k |
+| `deepseek/deepseek-v3.2` | 3/3 | 6/6 | 1/1 | 0.23·0.34 | 131k |
+| `bytedance-seed/seed-2.0-lite` | 3/3 | 6/6 | 1/1 | 0.25·2.00 | 262k |
+| `google/gemini-3.1-flash-lite` | 3/3 | 6/6 | 1/1 | 0.25·1.50 | 1048k |
+| `minimax/minimax-m2.7` | 3/3 | 6/6 | 1/1 | 0.25·1.00 | 204k |
+| `google/gemini-3.1-flash-lite-preview` | 3/3 | 6/6 | 1/1 | 0.25·1.50 | 1048k |
+| `minimax/minimax-m2` | 3/3 | 6/6 | 1/1 | 0.26·1.00 | 204k |
+| `deepseek/deepseek-v3.1-terminus` | 3/3 | 6/6 | 1/1 | 0.27·0.95 | 163k |
+| `minimax/minimax-m2.1` | 3/3 | 6/6 | 1/1 | 0.29·0.95 | 204k |
+| `minimax/minimax-m3` | 3/3 | 6/6 | 1/1 | 0.30·1.20 | 1048k |
+| `qwen/qwen3.7-plus` | 3/3 | 6/6 | 1/1 | 0.32·1.28 | 1000k |
+| `z-ai/glm-5` | 3/3 | 6/6 | 1/1 | 0.60·1.92 | 202k |
+| `z-ai/glm-5.1` | 3/3 | 6/6 | 1/1 | 0.98·3.08 | 202k |
+| `qwen/qwen3.6-max-preview` | 3/3 | 6/6 | 1/1 | 1.04·6.24 | 262k |
+| `x-ai/grok-4.20` | 3/3 | 6/6 | 1/1 | 1.25·2.50 | 2000k |
+| `x-ai/grok-4.3` | 3/3 | 6/6 | 1/1 | 1.25·2.50 | 1000k |
+| `google/gemini-3.5-flash` | 3/3 | 6/6 | 1/1 | 1.50·9.00 | 1048k |
+| `google/gemini-3.1-pro-preview-customtools` | 3/3 | 6/6 | 1/1 | 2.00·12.00 | 1048k |
+
+## ⚠️ Borderline — re-run candidates (failed 1–2 cells, or transient)
+
+These drove most of neal but tripped on one or two cells. `provider error` rows are
+transient (re-run likely flips them); `bad review output` / `can't emit schema JSON` are
+single-run signals that often flip too. Re-run before excluding.
+
+| Model | Coder | Reviewer | Planner | Tripped on |
+|---|---|---|---|---|
+| `mistralai/devstral-2512` | 3/3 | 6/6 | 0/1 | planner: provider error |
+| `nvidia/nemotron-3-ultra-550b-a55b` | 3/3 | 5/6 | 1/1 | reviewer: provider error |
+| `x-ai/grok-build-0.1` | 3/3 | 5/6 | 1/1 | reviewer: provider error |
+| `nvidia/nemotron-3-nano-30b-a3b` | 3/3 | 5/6 | 1/1 | reviewer: bad review output |
+| `deepseek/deepseek-v3.2-exp` | 3/3 | 5/6 | 1/1 | reviewer: bad review output |
+| `mistralai/mistral-medium-3-5` | 3/3 | 5/6 | 1/1 | reviewer: bad review output |
+| `qwen/qwen3.5-plus-20260420` | 3/3 | 5/6 | 1/1 | reviewer: bad review output |
+| `qwen/qwen3.7-max` | 3/3 | 5/6 | 1/1 | reviewer: bad review output |
+| `qwen/qwen3.6-flash` | 3/3 | 5/6 | 1/1 | reviewer: can't emit schema JSON |
+| `deepseek/deepseek-v4-pro` | 3/3 | 4/6 | 1/1 | reviewer: can't emit schema JSON |
+| `meta-llama/llama-4-maverick` | 1/3 | 6/6 | 1/1 | coder: left block unresolved |
+| `moonshotai/kimi-k2.5` | 2/3 | 6/6 | 1/1 | coder: can't emit schema JSON |
+| `stepfun/step-3.7-flash` | 2/3 | 6/6 | 1/1 | coder: provider error |
+| `inclusionai/ring-2.6-1t` | 2/3 | 5/6 | 1/1 | coder+reviewer: schema JSON |
+| `z-ai/glm-5.2` | 2/3 | 5/6 | 1/1 | coder+reviewer: schema JSON |
+| `inclusionai/ling-2.6-flash` | 0/3 | 4/6 | 1/1 | coder+reviewer: provider error |
+| `meta-llama/llama-3.3-70b-instruct` | 0/3 | 3/6 | 0/1 | provider error |
+| `bytedance-seed/seed-1.6` | 0/3 | 5/6 | 1/1 | coder: can't emit schema JSON |
+| `bytedance-seed/seed-1.6-flash` | 0/3 | 5/6 | 0/1 | coder: can't emit schema JSON |
+
+> Notable: the flagship `deepseek-v4-pro` FAILs (reviewer schema), but the cheaper
+> `deepseek-v4-flash` / `v3.2` PASS cleanly — and v4-pro has flaked stochastically before,
+> so it's a re-run candidate, not a hard FAIL.
+
+## ❌ Incompatible — fail the provider handshake (no tool-use / unparsable JSON)
+
+These can't drive neal's agentic loop on OpenRouter at all (`protocol` failure on the
+provider check — 0/1 every role): mostly small models and ones whose OR endpoints don't
+support tool use.
+
+`amazon/nova-{micro,lite,2-lite,pro,premier}-v1`, `bytedance-seed/seed-2.0-mini`,
+`cohere/{command-a,command-r-08-2024,command-r-plus-08-2024,command-r7b-12-2024}`,
+`meta-llama/{llama-3.1-8b,llama-3.2-1b,llama-3.2-3b}-instruct`, `meta-llama/llama-4-scout`,
+`microsoft/{phi-4,phi-4-mini-instruct,wizardlm-2-8x22b}`, `minimax/minimax-m2-her`,
+`mistralai/{ministral-3b,ministral-8b,ministral-14b}-2512`, `mistralai/mistral-small-2603`,
+`moonshotai/{kimi-k2,kimi-k2-0905,kimi-k2-thinking,kimi-k2.6,kimi-k2.7-code}`,
+`nvidia/llama-3.3-nemotron-super-49b-v1.5`, `openai/{gpt-oss-120b,gpt-oss-20b,gpt-oss-safeguard-20b}`,
+`stepfun/step-3.5-flash`, `x-ai/grok-4.20-multi-agent`, `z-ai/{glm-4.7-flash,glm-5-turbo}`.
+
+## Native adapters (supported, no compat run required)
+
+| Provider id | Coder | Reviewer | Planner |
+| --- | --- | --- | --- |
+| `openai-codex` | supported | supported | supported |
+| `anthropic-claude` | supported | supported | supported |
+
+## Reproducing / extending
+
+```
+neal compat --model <slug> --role all --reference openai-codex --json
+```
+
+`neal compat` also accepts an OpenRouter model as the reference
+(`--reference generic-agentic:<slug>`) to escape codex capacity limits, but
+**no OpenRouter model has validated as a drop-in reference** — two were tried on
+2026-06-18 and both failed:
+
+- `deepseek/deepseek-v4-flash` (cheap/fast) reproduced only **9** of the codex-ref
+  **25** PASSes (13 dropped, confirmed in isolation — not a rate-limit artifact):
+  too weak, it emits coder diffs the candidate-reviewer flags and blocks good
+  candidate work as partner-reviewer.
+- `google/gemini-3.1-pro-preview-customtools` (strong/expensive) was worse in
+  practice: of the 25 codex-PASS models only **1** reproduced, and it **wedged
+  under load** (hung reference calls at 6-wide, timeouts/no-result on the
+  PASS-class models at 3-wide). A reference that can't run wide defeats the
+  throughput purpose of going off-codex in the first place.
+
+**Conclusion:** `openai-codex` (gpt-5.5) is the authoritative reference. To extend
+the whitelist beyond this pool, run additional candidates on codex-ref directly
+(throttle to about three concurrent `neal compat` invocations for codex
+capacity); the OpenRouter-reference path is not a viable shortcut today.
+
+Paid slugs only — never `:free`. Re-run when a slug's backing model version changes.

package/docs/demo.md

@@ -0,0 +1,55 @@
+# Demo Recording
+
+Use `asciinema` for public terminal demos when a recording is useful. It is an
+optional recording tool, not a package dependency.
+
+Record from a disposable repository or throwaway worktree, preferably under
+`/tmp`, so the demo does not expose real project history, paths, or artifacts.
+
+## Suggested Script
+
+Create a small demo plan in the disposable repository:
+
+```bash
+throwaway="$(mktemp -d /tmp/neal-demo.XXXXXX)"
+recording_dir="$(mktemp -d /tmp/neal-demo-recording.XXXXXX)"
+recording="$recording_dir/neal-demo.cast"
+cd "$throwaway"
+git init
+printf '# Neal demo target\n' > README.md
+git add README.md
+git -c user.name='Neal Demo' -c user.email='neal-demo@example.invalid' commit -m 'Initial demo baseline'
+mkdir -p tmp
+$EDITOR tmp/DEMO_PLAN.md
+```
+
+Configure providers and run `neal check` before recording, or record those
+steps only if the output is safe to share. Use current Neal commands while
+recording:
+
+```bash
+asciinema rec "$recording"
+neal run tmp/DEMO_PLAN.md
+neal status
+exit
+```
+
+Keep the recording output outside the demo repository so it does not appear as
+unrelated dirty work while Neal starts the writer run.
+
+If you specifically want to show recovery from a run that is waiting for
+operator guidance, record that as a separate segment with the selected run id:
+
+```bash
+neal resume --run <run-id> --message "Continue with the smallest safe follow-up."
+```
+
+## Scrubbing Checklist
+
+Before sharing a recording, review the terminal output for local paths, private
+project names, provider output, credentials, tokens, provider environment
+variables, and `.neal/` artifact contents. Re-record from a clean disposable
+repository if the output exposes anything sensitive.
+
+This repository should commit recording instructions only, not `.cast` files or
+generated terminal transcripts.

package/docs/maintenance.md

@@ -0,0 +1,64 @@
+# Maintenance: dependencies & versioning
+
+neal's behavior is defined in large part by the agent SDKs it drives, so
+dependency updates are a first-class concern, not routine hygiene. This document
+is the policy.
+
+## Two dependency tiers
+
+| Tier | Packages | Pinning | Update posture |
+| --- | --- | --- | --- |
+| **Behavior-defining** | `@openai/codex-sdk`, `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`, `ai`, `@ai-sdk/openai-compatible`, `zod` | **exact** (enforced by `scripts/validate-release.mjs`) | **deliberate** — qualify before adopting; never auto-merge |
+| **Utility** | `dotenv`, `yaml`, `@types/node`, `tsx`, `typescript` | caret OK | routine — auto-merge on green CI after a soak period |
+
+The asymmetry exists because an agentic-SDK bump can change tool-calling,
+structured output, or sandbox behavior — i.e. break neal's loop **without**
+breaking compilation. Utility deps cannot.
+
+## The update flow
+
+1. **Detect.** [Renovate](../renovate.json) opens PRs weekly: utility deps grouped
+   (auto-merge), agentic SDKs one-per-PR (labelled `agentic-sdk` /
+   `needs-qualification`, auto-merge **off**, pinned exact).
+2. **Verify (automatic).** CI (`.github/workflows/ci.yml`) runs typecheck + unit
+   tests + package verification — catches **API-shape / contract** breaks.
+3. **Verify (behavioral).**
+   - The **AI-SDK tier** (`ai`, `@ai-sdk/openai-compatible`, `zod`) is exercised
+     automatically by the live smoke (`.github/workflows/smoke.yml`): a real
+     `neal compat` run against a cheap OpenRouter model through `generic-agentic`.
+   - The **native tier** (`@openai/codex-sdk`, `@anthropic-ai/*`) cannot be smoked
+     in CI (subscription auth isn't available there), so qualify it **locally**
+     before merging:
+     ```
+     neal compat --model <a-known-good-slug> --role all
+     ```
+     and ideally a one-fixture end-to-end run.
+4. **Adopt.** Merge, bump neal's version, add a CHANGELOG entry noting the bump +
+   any behavior change, and cut a release via the existing workflow.
+
+## Versioning
+
+SemVer, treated as a **CLI/application** contract:
+
+- **MAJOR** — breaking CLI/behavior: a command or flag removed, a plan-format or
+  config break, a provider-contract change users depend on.
+- **MINOR** — new backward-compatible surface: a new command, flag, or provider.
+- **PATCH** — bug fixes, no new surface.
+
+Mapping a dependency bump to neal's version:
+
+- Invisible to users (pin hygiene, internal) → **patch**.
+- Adds a capability neal now exposes → **minor**.
+- Changes observable behavior in a breaking way → **major** (or minor pre-1.0).
+
+**Pre-1.0:** while on `0.x`, minor may break (the honest "still evolving"
+contract). Move to **`1.0.0`** deliberately, once the CLI surface, plan format,
+and provider contracts are stable enough to promise compatibility — not before.
+
+## Changelog discipline
+
+Every release updates [CHANGELOG.md](../CHANGELOG.md) (Keep a Changelog format).
+Agentic-SDK bumps get an explicit line with the from→to versions and a one-line
+behavior note ("re-qualified with `neal compat`, no behavior change", or the
+specific change observed). The dependency churn *is* the risk surface, so it is
+recorded, not buried.