@navels/neal 0.1.0 → 0.3.0

package/docs/compatible-models.md

@@ -1,103 +1,153 @@
 # Compatible models
 
-> **Last updated:** 2026-06-18 · **Reference:** `openai-codex` (gpt-5.5) · **Pool:** 79 OpenRouter models
+> **Last updated:** 2026-07-20 · **Reference:** `openai-codex` (gpt-5.5) · **Pool:** 90 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.
+> 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
+- Scored under the **discrimination criterion** ([#49](https://github.com/navels/neal/issues/49),
+  `schemaVersion: 2`): a reviewer PASSes a fixture iff it raises at least one blocking
+  finding on the broken diff **and** strictly fewer on the good diff. Severity
+  calibration is not graded. Earlier sweeps (2026-06-18) required zero blocking
+  findings on the good diff and are not comparable.
+- The pool is the 2026-06-18 pool plus every qualifying model added to OpenRouter
+  since (paid, text-output chat models; no `:free` variants, no routers/aliases, no
+  native-adapter providers).
+- Role cells = passed/total fixtures (coder 2, reviewer 2 pairs, planner 1. The
+  redundant `is-even-add-test` fixture was dropped 2026-07-20).
+- **Single-run results are noisy at the margin.** Fail-only-once models were
+  re-confirmed once. Results below note where a verdict flipped on re-run.
+- Native adapters (`openai-codex`, `anthropic-claude`) are supported by construction
+  and need no compat run.
+
+## Compatible (44) - verified across all roles
 
 Sorted cheapest first ($/Mtok in·out, from the live OpenRouter catalog).
 
-| Model | Coder | Reviewer | Planner | $/Mtok | ctx |
+| Model | Coder | Reviewer | Planner | $/Mtok | ctx | Note |
+|---|---|---|---|---|---|---|
+| `nex-agi/nex-n2-mini` | 2/2 | 4/4 | 1/1 | 0.02·0.10 | 262k |  |
+| `nvidia/nemotron-3-nano-30b-a3b` | 2/2 | 4/4 | 1/1 | 0.05·0.20 | 262k |  |
+| `google/gemma-4-26b-a4b-it` | 2/2 | 4/4 | 1/1 | 0.07·0.34 | 262k |  |
+| `inclusionai/ling-2.6-1t` | 2/2 | 4/4 | 1/1 | 0.07·0.62 | 262k |  |
+| `nvidia/nemotron-3-super-120b-a12b` | 2/2 | 4/4 | 1/1 | 0.08·0.40 | 1000k |  |
+| `deepseek/deepseek-v4-flash` | 2/2 | 4/4 | 1/1 | 0.10·0.20 | 1049k |  |
+| `qwen/qwen3.6-35b-a3b` | 2/2 | 4/4 | 1/1 | 0.14·1.00 | 262k |  |
+| `kwaipilot/kat-coder-air-v2.5` | 2/2 | 4/4 | 1/1 | 0.15·0.60 | 256k |  |
+| `minimax/minimax-m2.5` | 2/2 | 4/4 | 1/1 | 0.15·0.90 | 205k |  |
+| `mistralai/mistral-small-2603` | 2/2 | 4/4 | 1/1 | 0.15·0.60 | 262k |  |
+| `stepfun/step-3.7-flash` | 2/2 | 4/4 | 1/1 | 0.20·1.15 | 256k |  |
+| `tencent/hy3` | 2/2 | 4/4 | 1/1 | 0.20·0.80 | 262k |  |
+| `google/gemma-4-31b-it` | 2/2 | 4/4 | 1/1 | 0.22·0.55 | 262k |  |
+| `deepseek/deepseek-chat-v3.1` | 2/2 | 4/4 | 1/1 | 0.25·0.95 | 164k |  |
+| `google/gemini-3.1-flash-lite` | 2/2 | 4/4 | 1/1 | 0.25·1.50 | 1049k |  |
+| `google/gemini-3.1-flash-lite-preview` | 2/2 | 4/4 | 1/1 | 0.25·1.50 | 1049k |  |
+| `minimax/minimax-m2.7` | 2/2 | 4/4 | 1/1 | 0.25·1.00 | 205k | first attempt failed (protocol:3). Confirmed PASS on re-run |
+| `z-ai/glm-5.2` | 2/2 | 4/4 | 1/1 | 0.26·0.81 | 1049k |  |
+| `deepseek/deepseek-v3.1-terminus` | 2/2 | 4/4 | 1/1 | 0.27·1.00 | 131k |  |
+| `deepseek/deepseek-v3.2` | 2/2 | 4/4 | 1/1 | 0.27·0.40 | 164k |  |
+| `deepseek/deepseek-v3.2-exp` | 2/2 | 4/4 | 1/1 | 0.27·0.41 | 164k |  |
+| `minimax/minimax-m2` | 2/2 | 4/4 | 1/1 | 0.30·1.20 | 205k |  |
+| `qwen/qwen3.5-plus-20260420` | 2/2 | 4/4 | 1/1 | 0.30·1.80 | 1000k |  |
+| `qwen/qwen3.7-plus` | 2/2 | 4/4 | 1/1 | 0.32·1.28 | 1000k |  |
+| `deepseek/deepseek-v4-pro` | 2/2 | 4/4 | 1/1 | 0.43·0.87 | 1049k | first attempt failed (structured_output:1). Confirmed PASS on re-run |
+| `moonshotai/kimi-k2-0905` | 2/2 | 4/4 | 1/1 | 0.60·2.50 | 262k |  |
+| `moonshotai/kimi-k2-thinking` | 2/2 | 4/4 | 1/1 | 0.60·2.50 | 262k |  |
+| `nvidia/nemotron-3-ultra-550b-a55b` | 2/2 | 4/4 | 1/1 | 0.60·3.60 | 1000k |  |
+| `kwaipilot/kat-coder-pro-v2.5` | 2/2 | 4/4 | 1/1 | 0.74·2.96 | 256k |  |
+| `moonshotai/kimi-k2.7-code` | 2/2 | 4/4 | 1/1 | 0.85·3.80 | 262k |  |
+| `z-ai/glm-5` | 2/2 | 4/4 | 1/1 | 0.95·2.55 | 205k |  |
+| `z-ai/glm-5.1` | 2/2 | 4/4 | 1/1 | 0.97·3.04 | 203k |  |
+| `x-ai/grok-build-0.1` | 2/2 | 4/4 | 1/1 | 1.00·2.00 | 256k |  |
+| `qwen/qwen3.6-max-preview` | 2/2 | 4/4 | 1/1 | 1.04·6.24 | 262k |  |
+| `meta/muse-spark-1.1` | 2/2 | 4/4 | 1/1 | 1.25·4.25 | 1049k |  |
+| `x-ai/grok-4.20` | 2/2 | 4/4 | 1/1 | 1.25·2.50 | 2000k |  |
+| `x-ai/grok-4.3` | 2/2 | 4/4 | 1/1 | 1.25·2.50 | 1000k | first attempt failed (provider_failed:2). Confirmed PASS on re-run |
+| `qwen/qwen3.7-max` | 2/2 | 4/4 | 1/1 | 1.48·4.42 | 1000k |  |
+| `google/gemini-3.5-flash` | 2/2 | 4/4 | 1/1 | 1.50·9.00 | 1049k |  |
+| `mistralai/mistral-medium-3-5` | 2/2 | 4/4 | 1/1 | 1.50·7.50 | 262k |  |
+| `google/gemini-3.1-pro-preview-customtools` | 2/2 | 4/4 | 1/1 | 2.00·12.00 | 1049k |  |
+| `x-ai/grok-4.5` | 2/2 | 4/4 | 1/1 | 2.00·6.00 | 500k |  |
+| `moonshotai/kimi-k3` | 2/2 | 4/4 | 1/1 | 3.00·15.00 | 1049k | first attempt failed (provider_failed:1). Confirmed PASS on re-run |
+| `sakana/fugu-ultra` | 2/2 | 4/4 | 1/1 | 5.00·30.00 | 1000k |  |
+
+## Borderline - re-run candidates (10)
+
+Failed one or a few cells with a non-protocol mode, or failed differently across
+attempts. `provider_failed` rows are transient infrastructure. The rest are
+single-run signals that may flip. Re-run before excluding.
+
+| Model | Coder | Reviewer | Planner | Tripped on | Note |
 |---|---|---|---|---|---|
-| `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}`.
+| `bytedance-seed/seed-1.6` | 0/2 | 4/4 | 1/1 | coder/add-edit-verify: structured_output |  |
+| `bytedance-seed/seed-1.6-flash` | 0/2 | 0/4 | 1/1 | coder/add-edit-verify: provider_failed |  |
+| `bytedance-seed/seed-2.0-lite` | 0/2 | 4/4 | 1/1 | coder/add-edit-verify: structured_output | confirmed FAIL 2/2 (attempt 1 {'structured_output': 2}, attempt 2 {'structured_output': 1}) |
+| `inclusionai/ling-2.6-flash` | 1/2 | 0/4 | 0/1 | coder/add-edit-verify: provider_failed |  |
+| `meta-llama/llama-3.1-8b-instruct` | 0/2 | 0/4 | 0/1 | coder/add-edit-verify: provider_failed |  |
+| `meta-llama/llama-4-maverick` | 1/2 | 4/4 | 1/1 | coder/add-edit-verify: block_unresolved | confirmed FAIL 2/2 (attempt 1 {'block_unresolved': 1}, attempt 2 {'structured_output': 1, 'block_unresolved': 1}) |
+| `mistralai/devstral-2512` | 0/2 | 4/4 | 1/1 | coder/add-edit-verify: provider_failed | confirmed FAIL 2/2 (attempt 1 {'provider_failed': 2}, attempt 2 {'provider_failed': 1}) |
+| `moonshotai/kimi-k2.5` | 1/2 | 4/4 | 1/1 | coder/sum-grep-edit: structured_output |  |
+| `moonshotai/kimi-k2.6` | 2/2 | 2/4 | 1/1 | reviewer/sum-grep-edit: structured_output |  |
+| `qwen/qwen3.6-flash` | 2/2 | 0/4 | 1/1 | reviewer/add-edit-verify: structured_output |  |
+
+## Incompatible (36) - fail the provider handshake
+
+These can't drive neal's agentic loop on OpenRouter at all (`protocol` failure on
+the provider check, every role): mostly small models and ones whose OR endpoints
+don't support tool use.
+
+- `aion-labs/aion-3.0`
+- `aion-labs/aion-3.0-mini`
+- `amazon/nova-2-lite-v1`
+- `amazon/nova-lite-v1`
+- `amazon/nova-micro-v1`
+- `amazon/nova-premier-v1`
+- `amazon/nova-pro-v1`
+- `bytedance-seed/seed-2.0-mini`
+- `cohere/command-a`
+- `cohere/command-r-08-2024`
+- `cohere/command-r-plus-08-2024`
+- `cohere/command-r7b-12-2024`
+- `inclusionai/ring-2.6-1t`
+- `meta-llama/llama-3.2-1b-instruct`
+- `meta-llama/llama-3.2-3b-instruct`
+- `meta-llama/llama-3.3-70b-instruct`
+- `meta-llama/llama-4-scout`
+- `microsoft/phi-4`
+- `microsoft/wizardlm-2-8x22b`
+- `minimax/minimax-m2-her`
+- `minimax/minimax-m2.1` *(confirmed 2/2)*
+- `minimax/minimax-m3` *(confirmed 2/2)*
+- `mistralai/ministral-14b-2512`
+- `mistralai/ministral-3b-2512`
+- `mistralai/ministral-8b-2512`
+- `moonshotai/kimi-k2`
+- `openai/gpt-oss-120b`
+- `openai/gpt-oss-20b`
+- `openai/gpt-oss-safeguard-20b`
+- `poolside/laguna-xs-2.1`
+- `stepfun/step-3.5-flash`
+- `thinkingmachines/inkling`
+- `x-ai/grok-4.20-multi-agent`
+- `z-ai/glm-4.7`
+- `z-ai/glm-4.7-flash`
+- `z-ai/glm-5-turbo`
+
+> **`require_parameters` note:** `minimax-m2.1` and `minimax-m3` (June PASSes, now
+> `protocol`, confirmed 2/2) trace to the `require_parameters: true` OpenRouter
+> routing constraint (#46), which excludes backends that do not support
+> `json_schema`. This is a routing/infrastructure attribution, not a model
+> capability change. Re-run if OpenRouter adds a capable backend for these slugs.
+> `minimax-m2.7` is intermittent under the same constraint (failed the sweep,
+> passed the confirm). The same constraint also *fixed* several June `protocol`
+> failures by steering routing to capable backends: `moonshotai/kimi-k2-0905`,
+> `kimi-k2-thinking`, `kimi-k2.7-code`, and `mistralai/mistral-small-2603` all
+> flipped to full PASS.
 
 ## Native adapters (supported, no compat run required)
 
@@ -112,24 +162,9 @@ support tool use.
 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.
+`openai-codex` (gpt-5.5) is the authoritative reference. No OpenRouter model has
+validated as a drop-in reference (two tried 2026-06-18, both failed. See the
+2026-06-18 revision of this file). Throttle to about three concurrent invocations
+for codex capacity.
+
+Paid slugs only, never `:free`. Re-run when a slug's backing model version changes.

package/docs/demo.md

@@ -1,4 +1,4 @@
-# Demo Recording
+# Demo recording
 
 Use `asciinema` for public terminal demos when a recording is useful. It is an
 optional recording tool, not a package dependency.
@@ -6,7 +6,17 @@ 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
+## What to show
+
+The README doesn't ship an embedded recording. If you make one, show the part
+that's actually worth watching: the planner/coder/reviewer loop with the coder
+and reviewer on different vendors, and the findings and responses going back and
+forth until the reviewer is satisfied. A single trivial one-scope plan running
+to completion doesn't show any of that. Pick a small change with a real review
+point in it, so the reviewer has something to catch and the coder has something
+to respond to.
+
+## Suggested script
 
 Create a small demo plan in the disposable repository:
 
@@ -24,7 +34,7 @@ $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
+steps only if the output is safe to share. Use current neal commands while
 recording:
 
 ```bash
@@ -35,7 +45,7 @@ exit
 ```
 
 Keep the recording output outside the demo repository so it does not appear as
-unrelated dirty work while Neal starts the writer run.
+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:
@@ -44,7 +54,7 @@ operator guidance, record that as a separate segment with the selected run id:
 neal resume --run <run-id> --message "Continue with the smallest safe follow-up."
 ```
 
-## Scrubbing Checklist
+## Scrubbing checklist
 
 Before sharing a recording, review the terminal output for local paths, private
 project names, provider output, credentials, tokens, provider environment

package/docs/maintenance.md

@@ -1,49 +1,91 @@
-# Maintenance: dependencies & versioning
+# Maintenance: dependencies and 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.
+neal's behavior comes largely from the agent SDKs it drives, so dependency
+updates need real attention, not routine hygiene. Here's the policy.
 
-## Two dependency tiers
+## Dependency buckets
 
-| Tier | Packages | Pinning | Update posture |
+Grouped so at most a handful of dependency PRs are ever open at once:
+
+| Bucket | Contents | Cadence | 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 |
+| **Weekly non-major** | everything except the native SDKs (minor/patch/pin/digest) | weekly, one grouped PR | auto-merge after CI and the live smoke pass, subject to a 3-day soak |
+| **Native SDKs** | `@openai/codex-sdk` and `@anthropic-ai/claude-agent-sdk`, both exact-pinned. `ai`, `@ai-sdk/openai-compatible`, and `zod` also stay exact-pinned. | one grouped PR, opened after the 3-day soak instead of waiting for the weekly schedule | qualify on a subscription-authenticated machine with `scripts/qualify-sdk.sh`. Never auto-merge. Skip the CI smoke because it does not exercise the native adapters. |
+| **Library majors** | every npm major except the native SDKs (`typescript`, `@types/node`, `ai`, `@ai-sdk/openai-compatible`, `zod`, etc.) | monthly, one grouped PR | review manually because some need code changes |
+| **GitHub Actions majors** | `actions/checkout`, `actions/setup-node`, `actions/upload-artifact`, etc. | monthly, one grouped PR separate from library majors | review and merge on green CI. Do not auto-merge because a major action bump can still change behavior. |
 
-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 native-SDK split exists because an agentic-SDK bump can change
+tool-calling, structured output, or sandbox behavior. That breaks neal's loop
+**without** breaking compilation. And CI can't behaviorally exercise the
+native adapters: their auth is subscription-based and lives only on a
+maintainer's machine. Everything else is behaviorally exercised in CI: the
+live smoke runs on every package.json/lockfile PR, so the weekly grouped PR
+is gated on it as a whole.
 
 ## 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.
+1. **Detect.** [Renovate](../renovate.json) opens grouped PRs: the weekly
+   non-major bucket, the native-SDK bucket (labelled `agentic-sdk` +
+   `needs-qualification`), and, monthly, separate library-majors and
+   GitHub-Actions-majors buckets (both labelled `needs-review`).
+2. **Verify (automatic).** CI (`.github/workflows/ci.yml`) runs typecheck + lint
+   + unit tests + package verification on Node 24.18.0, which catches
+   **API-shape / contract** breaks. The live smoke
+   (`.github/workflows/smoke.yml`) runs on every package.json / lockfile PR: a
+   real `neal compat` run against a cheap OpenRouter model through
+   `openai-compatible`, catching **behavioral** breaks in the AI-SDK tier. The
+   weekly non-major PR auto-merges when both are green.
+   **The smoke requires the `OPENROUTER_API_KEY` repo secret.** Without it
+   the smoke skips (green) and the AI-SDK auto-merge gate is compile-only.
+3. **Verify (behavioral, native tier).** `@openai/codex-sdk` and
+   `@anthropic-ai/claude-agent-sdk` can't be smoked in CI, so qualify them
+   from any checkout with authenticated Claude/Codex CLIs:
+   ```
+   scripts/qualify-sdk.sh <pr-number>
+   ```
+   It runs the full suite plus a live `neal compat --role all` pass-through on
+   every bumped adapter in the PR (in a throwaway worktree, with roles and
+   models pinned explicitly so nothing leaks from `~/.neal/config.yml`), posts
+   the compat matrices to the PR, and approves on PASS (`--merge` also
+   squash-merges).
 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.
+   any behavior change, and cut a release via the existing workflow. Urgent
+   bumps (a fix neal needs immediately) may skip the Renovate soak with a
+   manual PR. Qualify them the same way.
+
+## TypeScript 6 and 7 side by side
+
+`package.json` carries two TypeScript copies on purpose:
+
+| Dependency | Version | Used by |
+| --- | --- | --- |
+| `typescript` | `^6.0.3` | typescript-eslint's parser, via `pnpm lint` |
+| `typescript-7` (alias of `typescript`) | `^7.0.2` | `pnpm typecheck` and `pnpm build` |
+
+TypeScript 7 ships no JavaScript API. Its `typescript` entry point exports only
+`version` and `versionMajorMinor`, so anything that calls `require('typescript')`
+expecting the classic compiler API breaks. typescript-eslint's parser is built on
+that API and crashes on load
+([typescript-eslint#12518](https://github.com/typescript-eslint/typescript-eslint/issues/12518),
+tracked in [#10940](https://github.com/typescript-eslint/typescript-eslint/issues/10940)).
+
+Microsoft [documented running the two side by side](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0)
+for exactly this reason, and expects TypeScript 7.1 to ship the replacement API.
+Lint stays on 6, the compiler is 7, and there's no syntax divergence to worry
+about because 7.0 is a port of 6.x semantics rather than a new language version.
+
+**When TypeScript 7.1 lands with an API and typescript-eslint supports it:** drop
+`typescript-7`, move `typescript` to `^7`, and point `build` / `typecheck` back at
+plain `tsc`.
 
 ## Versioning
 
 SemVer, treated as a **CLI/application** contract:
 
-- **MAJOR** — breaking CLI/behavior: a command or flag removed, a plan-format or
+- **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.
+- **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:
 
@@ -53,7 +95,7 @@ Mapping a dependency bump to neal's version:
 
 **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.
+and provider contracts are stable enough to promise compatibility, not before.
 
 ## Changelog discipline