done-done-axi 0.6.12 → 0.6.14

package/README.md

@@ -3,19 +3,19 @@
 
 <img src="docs/logo.svg" width="64" height="64" alt="done-done">
 
-[![npm](https://img.shields.io/npm/v/done-done-axi?label=done-done&color=5754d7)](https://www.npmjs.com/package/done-done-axi) [![Node 22.18+](https://img.shields.io/badge/node-22.18%2B-3fb950)](https://nodejs.org) [![Early preview](https://img.shields.io/badge/status-preview-d29922)](#whats-next)
-
-</div>
-
-# Prove your app really works.
+<h1>Prove your app really works.</h1>
 
-A command-line check of real screenshots, recordings and output.
+A command-line check that drives your app the way a user does, then has a separate agent judge what it captured.
 
-For developers using coding agents, alone or in a [Firstmate](#use-with-firstmate-or-another-agent-fleet) fleet. Tests can pass while the app is still broken.
+For developers using coding agents: the tests pass, the agent says "done", and the app is still broken.
 
-<img src="docs/media/demo.png" width="320" alt="Real sample app: Release checklist shows Capture the real app checked and Done. The actual claude-haiku-5-5 judge passes that captured screenshot at sample commit 08d635e46a98.">
+<picture>
+  <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="docs/media/hero-phone-dark.png">
+  <source media="(max-width: 600px)" srcset="docs/media/hero-phone-light.png">
+  <img src="docs/media/hero.gif" width="880" alt="A real run: done-done run records a capture for commit ca78363, done-done check passes with the judge's reason, done-done receipt writes the receipt, and done-done init refuses a journey that only runs npm test.">
+</picture>
 
-<sub>Real sample app + live judge verdict, at the captured commit.</sub>
+<sub>A real 0.6.12 run on a small sample app: a capture, the judge's pass and its reason, the receipt, and a test-only journey refused. Long paths shortened; [still, light](docs/media/hero-light.png) · [dark](docs/media/hero-dark.png).</sub>
 
 ```sh
 npm install -g done-done-axi
@@ -23,41 +23,50 @@ cd your-app && done-done init
 done-done verify --outcome "<what works now>"
 ```
 
-The last line is your first result: your agent drives the real app, a judge checks each capture, and you get a pass with a receipt, or the judge's reason it did not pass.
+The last line is your first result: your agent drives the real app, a fresh judge checks each capture, and you get a pass with a receipt, or the judge's reason it did not pass.
 
-**With or without Firstmate.** On its own, you or your agent run these three lines. In a [Firstmate](https://github.com/kunchenguid/firstmate) fleet, two files make every worker prove its task, plus an optional merge gate that checks that proof ([how](#use-with-firstmate-or-another-agent-fleet)).
+**With or without Firstmate.** Alone, you or your agent run these three lines; nothing else is needed. Inside a [Firstmate](https://github.com/kunchenguid/firstmate) fleet, two small files make every worker prove its task and let the merge check that proof ([how](#inside-firstmate-or-another-agent-fleet)).
 
-[Website](https://umeranjum17.github.io/done-done-axi/) · [Setup](#install-in-3-steps) · [Agent skill](#use-it-from-your-agent) · [Reference](docs/reference.md) · [npm](https://www.npmjs.com/package/done-done-axi)
+[Website](https://umeranjum17.github.io/done-done-axi/) · [Quick start](#quick-start) · [Why](#why-not-just-green-tests) · [Reference](docs/reference.md) · [npm](https://www.npmjs.com/package/done-done-axi)
 
-## Install in 3 steps
-
-You need **[Node 22.18+](https://nodejs.org) and git**, plus your own signed-in coding agent or API key for the judge. Early preview; see [what's next](#whats-next).
+[![npm](https://img.shields.io/npm/v/done-done-axi?label=done-done&color=5754d7)](https://www.npmjs.com/package/done-done-axi) [![Node 22.18+](https://img.shields.io/badge/node-22.18%2B-3fb950)](https://nodejs.org) [![Early preview](https://img.shields.io/badge/status-preview-d29922)](#whats-next)
 
-1. **Install.** The first line above puts `done-done` (and the long name `done-done-axi`) on your PATH. No `sudo`? Add `--prefix ~/.local` and put `~/.local/bin` on your `PATH`.
-2. **Set up your repo.** `init` asks you, in a terminal, which coding agent drives your app and which judge checks it. done-done never picks either for you. It then writes a minimal `.done-done.yaml` and a verify skill: how to launch and drive your app. Outside a terminal, pass `--agent <agent> --model <model> --judge <agent> --judge-model <model>` instead.
-3. **Get your first result.** Say what works now, in plain words. `verify` has your agent drive the real product the way a user does and save screenshots or output. A fresh judge checks whether each capture shows your claim. A pass names the capture and writes a receipt for this commit. Anything else stops at a gate with the judge's reason, and `done-done respond` answers it. No judge pass, no receipt.
+</div>
 
-`done-done --version` prints the bare version first; help headers show it too, and suffixed versions are labelled `pre-release`.
+## Quick start
 
-Optional setup check: `done-done doctor --probe` requires a real answer from your chosen agent; it checks setup, not whether your app works.
+You need **[Node 22.18+](https://nodejs.org) and git**, plus your own signed-in coding agent or API key for the judge.
 
-For a signed-in Claude Code setup, pass `--agent claude --model claude-haiku-5-5 --judge claude --judge-model claude-haiku-5-5` to `init`. For Codex, use `--agent codex --model gpt-6.1-sol` with that same judge. Codex readers and probes require a CLI with `exec --ignore-user-config` and `debug models --bundled`: they keep your login, but disable MCP, project instructions and model-provided tools; edit/drive steps keep your normal Codex config. Codex is not a judge route.
+1. **Install.** The first line above puts `done-done` and `done-done-axi` on your PATH. No `sudo`? Add `--prefix ~/.local` and put `~/.local/bin` on your `PATH`.
+2. **Set up your repo.** `init` asks which coding agent drives your app and which judge checks it, and never picks either for you. It writes a minimal `.done-done.yaml` and a verify skill that says how to launch and drive your app. Outside a terminal, pass `--agent <agent> --model <model> --judge <agent> --judge-model <model>`.
+3. **Get your first result.** Say what works now, in plain words. Your agent drives the real product as a user would and saves screenshots, a recording or output; a fresh judge checks whether each capture shows your claim. A pass names the capture and writes a receipt for this commit; anything else stops at a gate with the judge's reason, which `done-done respond` answers.
 
-Claude Code and Codex are proven live. **OpenCode is not yet proven live:** its free tier rejects done-done's tools-off calls with HTTP 403 (`opencode/deepseek-v4.1-flash-free`), so `init`, `doctor --probe` and a judged run are not proven there, and `opencode/muse-spark-1.3-contributor-free` may be absent from the installed catalog. To try OpenCode, choose a model your plan already covers from `opencode models` with `--agent opencode --model <provider/model>`; done-done never needs a new account or API spend.
+Commit `.done-done.yaml` and the verify skill so later runs and your teammates use the same recipe. Captures go to your judge's provider, on your plan or key.
 
-No result? `done-done doctor` changes nothing and names each missing piece, such as a verify skill `init` could not write, with the exact command that fixes it. Commit `.done-done.yaml` and the verify skill so later runs and your teammates use the same recipe. You choose the agents and models; captures go to your chosen judge's provider, on your own plan or key. [Manual CLI](#manual-cli) walks through recording a journey, checking it and saving a receipt.
+## Why: not just green tests
 
-## Why
+| | Green tests, or an agent's word | done-done |
+| --- | --- | --- |
+| What is checked | Code paths, types, lint, builds | The app, CLI or site, driven the way a user drives it |
+| Who looks | You, or nobody | A fresh judge agent you chose, tools off, on your plan |
+| Tied to a commit | No | A receipt names the commit and the sha256 of every capture |
+| Stale or reused proof | Passes | Fails: proof from an older commit, or a file used for another claim, is refused |
+| When it goes wrong | "Done" was wrong, later | The judge's reason, a gate to answer, and no receipt |
 
-<a id="no-proof-no-done"></a>
+## What it checks
 
-**No proof, no "done".** "Done" is easy to say. Screenshots get reused, recordings go stale, and a green test run is not the app.
+- 🧪 **The real product, not code checks.** A journey that only runs tests, typecheck, lint or a build is refused, and so is proof whose captures all come from such a run ([rule](docs/reference.md#real-product-evidence)).
+- 🔗 **Tied to a commit, fresh, not reused.** Every run records the commit and whether the tree was dirty; older-commit proof fails, and a file used for another claim is reuse ([how](docs/reference.md#where-proof-lives)).
+- 👀 **A judge always answers.** A fresh, tools-off judge on your plan looks at every `check`, `receipt` and `verify`. It cannot be turned off, and a judge that fails to answer stops the command instead of passing ([how](docs/reference.md#judge-relevance)).
+- 🧾 **Honest claims, no model.** `done-done lint <PR URL | file> <evidence folder>` gates a worker's `## Checks` block: four filled lines, and evidence that exists, differs, is newer than the folder and was never used by another PR ([how](docs/reference.md#lint-check)).
+- 🚦 **CI gate, no key.** `done-done gate` passes when a committed receipt covers the head; CI never runs `check`, `run` or `verify` and never gets a model key ([how](docs/reference.md#ci-gate)).
+- 🎨 **Looks right, fits the screen.** `done-done design` has the judge compare a screen with its approved mock; `done-done look <url>` fails a 390 px page that overflows, with no model ([design](docs/reference.md#design-check), [look](docs/reference.md#look-check)).
 
-done-done runs your capture and ties every screenshot, recording and log it saves to the exact commit. When someone says "done", it checks the proof they point to: is it really there, is it a real picture or video, is it from this commit, and is it new? If not, the check fails. If it can't tell, it says so instead of passing.
+Every answer is an exit code: **0** pass, **1** fail, **2** usage or config error, **3** can't tell either way, **4** a run is still going or waits at its gate ([all codes](docs/reference.md#exit-codes)).
 
 ## See it work
 
-Four moments from a demo notes app. Every picture is real output from the current build; the demo's judge is a stub that says the screen shows the outcome, so no model runs.
+Four more moments from a demo notes app: a capture for the current commit, a judged pass, a check that refuses an older commit and two bad files, and a config error that stops the run. Real output from the current build; these four use a stub judge that says the screen shows the outcome, so no model runs.
 
 <picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/run-dark.svg"><img src="docs/media/run-light.svg" alt="done-done run sync records one screenshot for the current commit." width="400" align="top"></picture>
 <picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/pass-dark.svg"><img src="docs/media/pass-light.svg" alt="A Checks block cites the new screenshot, the judge passes it, and done-done check passes." width="400" align="top"></picture>
@@ -65,52 +74,21 @@ Four moments from a demo notes app. Every picture is real output from the curren
 <picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/reasons-dark.svg"><img src="docs/media/reasons-light.svg" alt="done-done check fails: one screenshot is from an older commit, one file is empty, one is a blank frame." width="400" align="top"></picture>
 <picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/config-dark.svg"><img src="docs/media/config-light.svg" alt="done-done run stops with exit 2 because the config has an unknown key." width="400" align="top"></picture>
 
-done-done is an [AXI](https://axi.md), which means -
-
-- It's just a CLI any capable agent can run without setup.
-- It's built for agents: [TOON](https://github.com/toon-format/spec) output by default (`--json` and `--full` when needed), and every result names the next command in its `help` lines.
-- The skill below only handles discovery; agents learn done-done by using it.
+The hero above is a real run of the published CLI on a fresh sample repo, replayed line by line: `run` recorded the capture at commit `ca78363`, the Pi judge on `commandcode/deepseek/deepseek-v4.1-flash` read it and passed it with that reason, `receipt` wrote the receipt, and `init` refused a journey whose only command was `npm test`. [The manual walkthrough](docs/manual-cli.md) does the same by hand.
 
-## Use It From Your Agent
+## Use it from your agent
 
-You need Node 22.18 or later and git. Give your agent the done-done skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills), naming your agent with `-a`:
+Give your agent the done-done skill in the [Agent Skills](https://agentskills.io) format, naming your agent with `-a`:
 
 ```sh
 npx skills add umeranjum17/done-done-axi --skill done-done -a <agent> -y
 ```
 
-`<agent>` is `claude-code`, `codex`, `opencode`, `pi` or `gemini-cli`. `-a` and `-y` skip the installer's four prompts and keep it from writing skill folders for agents you do not use.
+`<agent>` is `claude-code`, `codex`, `opencode`, `pi` or `gemini-cli`. The skill lands in this project (`.claude/skills/done-done/` for Claude Code, `.agents/skills/done-done/` for the rest) next to a `skills-lock.json`: commit both so your teammates get it, or add `-g` to install it once for all projects. No npm install is needed: the skill runs `done-done` from your PATH, else the npm package through `npx`. Then ask in plain words ("prove the app in this repo works") or use your agent's slash command.
 
-The skill lands in this project (`.claude/skills/done-done/` for Claude Code, `.agents/skills/done-done/` for Codex, opencode, Pi and Gemini CLI) next to a `skills-lock.json`: commit both so your teammates get it too. Or add `-g` to install it once for all your projects (for example `~/.claude/skills/` for Claude Code) and leave the project untouched.
+## Journeys in plain words
 
-That is the entire setup - no npm install needed.
-The skill tells your agent to use `done-done` if it is on PATH and otherwise run the npm package through `npx`, so the CLI comes along on demand:
-
-```sh
-npx -y done-done-axi --help
-```
-
-The skill is a short stub and sends the agent to `--help` and the bare command for current instructions, so an installed copy cannot go stale against a newer CLI.
-
-Then, in agents that expose skills as slash commands (Claude Code, for example), invoke it directly:
-
-```
-/done-done prove the app in this repo works
-```
-
-Or just ask in plain words - "prove the app in this repo works", "is this really done?", "gate this PR on proof" - and the agent loads the skill on its own.
-
-## Other Ways to Use done-done
-
-The skill is the recommended path, but it is not the only one.
-
-### Manual CLI
-
-Prefer a terminal to an agent skill? The [manual walkthrough](docs/manual-cli.md) covers installation without sudo, choosing agents, capture recipes, core and upgrade journeys, hooks, `doctor`, checks, receipts and the verify/fix loop. All behavior details live there or in the [reference](docs/reference.md).
-
-## Write journeys in plain words
-
-A journey is the saved script that drives your app and captures what a user sees. You do not have to write it yourself. Describe it, and the agent you chose at `init` writes it:
+A journey is the saved script that drives your app and captures what a user sees. Describe it and your agent writes it:
 
 ```sh
 done-done journey add "greet Umer and check that Hello Umer is printed"
@@ -118,127 +96,51 @@ done-done journey enhance greet-umer-prints-hello "add checks for an empty name
 done-done journey improve greet-umer-prints-hello "also check that greeting Zoë prints exactly Hello Zoë"
 ```
 
-- **`add "<description>"`** writes a new journey: a capture script in `journeys/`, its entry in `.done-done.yaml` and a feature in your verify skill. It names the journey from your words and prints that name.
-- **`enhance <name> ["<focus>"]`** deepens one journey you already have with more steps, edge cases and checks, and keeps the checks it has. Leave out the focus for a general pass.
-- **`improve <name> "<instruction>"`** makes one specific change to one journey and nothing else.
+`add` writes the script, its config entry and its feature in the verify skill; `enhance` deepens one journey; `improve` makes one change to one journey. Each exercise runs once on uncommitted files, which is a trial, not proof: read the script, commit it, then `done-done run <name>`. The saved script needs no agent or model, so CI can replay it; generation runs only on your machine ([worked transcript](docs/manual-cli.md)).
 
-Each command prints the files it changed, then runs the journey once. This is the real output of the three lines above, from a clean install on a small greeting CLI with Claude Code as the agent (run paths cut short with `…`):
-
-```
-$ done-done journey add "greet Umer and check that Hello Umer is printed"
-Added journey greet-umer-prints-hello through claude. Review these repo changes:
-.agents/skills/done-done-verify-hello-umer/features/README.md | 1 +
- .done-done.yaml                                               | 3 +++
- 2 files changed, 4 insertions(+)
- journeys/greet-umer-prints-hello.mjs | 29 new lines
- .agents/skills/done-done-verify-hello-umer/features/greet-umer-prints-hello.md | 13 new lines
-The first run is a dirty-tree trial, not clean proof. Review and commit, then: done-done run greet-umer-prints-hello
-ok greet-umer-prints-hello
-command: run
-result: recorded
-dirty: true
-files: 1
-evidence[1]: …/terminal.txt
-
-$ done-done journey enhance greet-umer-prints-hello "add checks for an empty name and an unknown command"
-Enhanced journey greet-umer-prints-hello through claude. Review these repo changes:
-.../features/greet-umer-prints-hello.md            |  8 +++++++
- .done-done.yaml                                    |  4 +++-
- journeys/greet-umer-prints-hello.mjs               | 27 +++++++++++++++++++---
- 3 files changed, 35 insertions(+), 4 deletions(-)
-…
-files: 3
-evidence[3]: …/terminal-empty-name.txt,…/terminal-unknown-command.txt,…/terminal.txt
-
-$ done-done journey improve greet-umer-prints-hello "also check that greeting Zoë prints exactly Hello Zoë"
-Improved journey greet-umer-prints-hello through claude. Review these repo changes:
-.../features/greet-umer-prints-hello.md                       |  8 ++++++++
- .done-done.yaml                                               |  1 +
- journeys/greet-umer-prints-hello.mjs                          | 11 ++++++++++-
- 3 files changed, 19 insertions(+), 1 deletion(-)
-…
-files: 4
-evidence[4]: …/terminal-empty-name.txt,…/terminal-unknown-command.txt,…/terminal-zoe.txt,…/terminal.txt
-```
+## Inside Firstmate, or another agent fleet
 
-`.done-done.yaml` keeps what you asked for next to the journey:
+done-done works the same with or without Firstmate: the skill and CLI behave identically inside or outside a Firstmate home. [Firstmate](https://github.com/kunchenguid/firstmate) hands tasks to agent workers and merges their work, and [`integrations/firstmate/`](integrations/firstmate/) ships the two files those workers need:
 
-```yaml
-journeys:
-  greet-umer-prints-hello:
-    command:
-      # Enhanced focus: "add checks for an empty name and an unknown command"
-      # Improved instruction: "also check that greeting Zoë prints exactly Hello Zoë"
-      node journeys/greet-umer-prints-hello.mjs
+```sh
+npx skills add umeranjum17/done-done-axi --skill done-done -g -a <agent> -y
+npm install -g done-done-axi
+cat "$(npm root -g)/done-done-axi/integrations/firstmate/brief-include.md" >> "$FM_HOME/config/brief-include.md"
+cp "$(npm root -g)/done-done-axi/integrations/firstmate/merge-gate" "$FM_HOME/config/merge-gate"
 ```
 
-That first run is a trial on uncommitted files, not proof. Read the generated script as you would any code an agent wrote, commit it, then `done-done run greet-umer-prints-hello` records clean proof (`dirty: false`). The saved script needs no agent or model, so CI can replay it. Generation itself runs only on your machine, never in CI, and uses only the agent you configured. `done-done journey --help` shows these examples; the [reference](docs/reference.md#add-a-journey-from-a-description) has every rule.
-
-## What it checks
-
-- 🧪 **The real product, not code checks**: Proof must come from driving the app, CLI or site the way a user does. A config whose journeys only run tests, typecheck, lint or a build, or proof whose captures all come from such runs, is refused by `check`, `receipt` and `gate`, and `doctor` flags it ([rule](docs/reference.md#real-product-evidence)).
-- 🎯 **The core journey and the upgrade users take**: Each app names the one flow a user cannot live without, driven end to end on the real target, and an app that ships an installable artifact also names the upgrade over its previous release. `doctor` and the verify skill `init` writes require both ([rule](docs/reference.md#core-journey-and-release-path)).
-- 🧭 **The journeys your change needs**: `done-done affected [<base>]` reads the diff since the last receipt (or the default branch), maps each changed file to the journeys whose command runs it and the verify skill features whose file cites it, adds the core journey when a file is in no feature or journey, and exits 1 until a receipt for HEAD has a run of each. It flags the files no feature covers, so the feature map grows with the code ([how](docs/reference.md#affected-journeys)).
-- 🔗 **Tied to a commit**: Every run records the commit, and whether there were uncommitted changes.
-- 🖼️ **Real media**: Empty, cut-off, blank or tiny screenshots fail. Videos must hold real frames (needs `ffprobe`).
-- ⏱️ **Fresh**: Proof from an older commit fails. Commits that only touch docs can be set to keep it fresh.
-- ♻️ **Not reused**: Proof made only of files already used for a different claim fails, and so does citing the same file twice. A claim is named by `--claim-id <id>`, which defaults to your branch, so rewording it keeps its proof. Several claims on one branch each need their own `--claim-id`.
-- 🧾 **Honest claims**: Reads a pull request's `## Checks` block — from a file, a URL, or stdin — and makes sure every line is filled in.
-- 📌 **Verifiable later**: `receipt` records a passing check against the exact commit and the sha256 of every file it cited; `receipt --verify` re-checks it from any checkout of that commit on the same machine (a merge gate or a fresh clone) ([how](docs/reference.md#where-proof-lives)).
-- 👀 **Shows the outcome** (always): `check`, `receipt` and `verify` start done-done's own judge, a fresh, tools-off agent on your own plan or key (Claude Code, opencode, pi or Gemini CLI, or your own OpenAI API key), to say whether each capture is the right screen for the claim (and each text capture, such as a log, JSON or CLI output, the right output), and a wrong one fails. There is no way to turn it off: done-done gives no result without it. The checks above never pass on their own, and a check that cites only files the judge cannot read (a video) stops before the judge, with exit 2. You choose the judge route (`done-done init --judge <agent> --judge-model <model>`, or pick it from the list done-done shows in a terminal; `done-done check --judge <route>` overrides it for one call); for a Pi judge with no explicit model, done-done defaults to `openai-codex/gpt-6-luna` unless `agent_config.pi.model` is set. Any agent and model you choose runs, your coding agent's own too. A judge that fails or times out stops the command with its cause (exit 2; a `verify` run stops with exit 2 and its cause in the run record), and no receipt is written.
-- 🎨 **Looks right**: `done-done design <screens...> [--mock <screen>=<mock>]` has the same judge look at each captured screen, alone or next to its approved mock, and fails it on stretched or squashed images, clipped or squashed text, overlap, elements off-screen, blank or black strips and broken layout, naming each defect and where it is ([how](docs/reference.md#design-check)).
-- 📐 **Fits the screen**: `done-done look <url>` opens a web page in headless Chrome at a 390x844 phone viewport, captures it, and fails the journey that calls it on squashed text, clipped text, elements cut off by an edge or a page wider than the screen, naming each element, with no model ([how](docs/reference.md#look-check)).
-- 🧮 **Honest, cheap claim gate**: `done-done lint <PR URL | report file> <evidence folder>` is a no-model gate on a worker's `## Checks` block, on whenever you call it. It prints `PASS` or `FAIL: <reason>` and exits 1 on a fail: the four lines present, proof naming a command or path, a real repro on a fix PR, evidence files that exist, are non-empty, are newer than the evidence folder and differ from each other, at least one never used by another PR (hashes kept in `~/.done-done/lint.hashes`, every run logged to `lint.log` there), under 1,000 added non-generated lines, and a `WARN` when a PR changes `src/` with no `journeys/` file ([how](docs/reference.md#lint-check)). `evidence: not proven: <cause>` passes.
-- 🚦 **CI gate, no model**: `done-done gate [<head>]` passes when a receipt committed under `.done-done-receipts/` covers the head and its captures come from real-product runs, with no judge, config, key or evidence files. CI never runs `check`, `run` or `verify` and never gets a model key; proof runs on your desktop ([how](docs/reference.md#ci-gate)).
-- 🧩 **Page is clean** (with a `dom` block): each captured screen also needs its page-check record. A page that overflows the viewport, logs a console error, has a failed request or shows squashed, clipped or cut-off UI fails, unless an allow list names it ([how](docs/reference.md#dom-assertions)).
-
-Every answer is an exit code: **0** pass, **1** fail, **2** usage or config error (including no agent or judge set, a check that fails before its judge, a capture the judge cannot be sent, or a judge that did not answer: never a result), **3** can't tell either way, **4** a `verify`, `maintain` or `rerun` run is still running, or a `verify` run waits at its gate.
-
-### Interaction polish needs proof too
-
-Opt in with `interaction_checklist` in `.done-done.yaml`: detail next/previous plus swipe, instant send/answer state, destructive undo, scroll position on back, long-list search/filter, and useful empty states. Each item needs judged real-product frames or an explicit not-applicable reason; missing proof is flagged, never silently passed. The [shipped checklist and wiring](docs/reference.md#interaction-checklist-opt-in) extend `check`, `receipt` and `verify`; existing approved-design checks stay unchanged without opt-in.
-
-## Alone, and with the other tools
-
-done-done works on its own: the CLI and the skill need nothing else. It is one of three tools that each do one job and connect through small written contracts ([Vision](VISION.md)):
+- **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run the journeys `done-done affected` lists for its committed change, write a `## Checks` block, pass `check`, record a `receipt`, and see `affected` exit 0.
+- **`merge-gate`** (optional): refuses a PR whose head is not the one asked for, then runs `done-done check --from <PR URL>` and `done-done receipt --verify <head>` against your default branch's rules. Upstream Firstmate does not call a merge gate yet, so run it by hand until it does ([details](docs/reference.md#merge-gate-on-the-desktop)).
+- **Model pool**: point `judge.pool_command` and `judge.pool_config` at the fleet's `account-pool/bin/fm-model-pool` and done-done picks the Claude account, moves on a rate or usage limit, and falls over to DeepSeek Goat or Cursor auto ([details](docs/reference.md#config)).
 
-- [`sign-off-axi`](https://www.npmjs.com/package/sign-off-axi): the board where agents ask you questions. `done-done signoff` prepares a run's gate (when the judge was unsure) or evidence in sign-off's message format and prints the post command. done-done itself does not publish to a board; sign-off-axi posts the card. With the opt-in (`done-done signoff --post`, or `signoff.post: true` in `.done-done.yaml`), done-done hands the run to sign-off-axi, which posts the message and returns a card that done-done records. `done-done signoff --wait` brings the answer back to the same run. Without sign-off you answer at the terminal with `done-done respond`.
-- [`learn-from-mistakes-axi`](https://www.npmjs.com/package/learn-from-mistakes-axi): the retro tool that finds mistakes your agents keep repeating, with evidence. Neither tool needs the other.
-- [`first-draft-axi`](https://www.npmjs.com/package/first-draft-axi): turns a prompt into design mocks. Pass a mock to `done-done design <screen> --mock <screen>=<mock>` to judge a captured screen next to it.
+Another fleet works the same way: add the include text to whatever your workers read first, and run `merge-gate` before each merge, with `FM_HOME` set to the folder that holds `data/<task-id>/checks.md` for local-only tasks. Evidence and receipts stay in `~/.done-done/evidence/<app>` after teardown.
 
-## Use with Firstmate or another agent fleet
+## The other two tools
 
-done-done works the same with or without Firstmate: nothing below is needed to use it, and the skill and CLI behave identically inside or outside a Firstmate home.
+done-done works on its own: the CLI and the skill need nothing else. It is one of three tools that each do one job and connect through small written contracts ([Vision](VISION.md)): [sign-off-axi](https://www.npmjs.com/package/sign-off-axi) is the board where agents ask you questions (`done-done signoff` prepares a run's card, `--wait` brings the answer back, and the opt-in posts it); [learn-from-mistakes-axi](https://www.npmjs.com/package/learn-from-mistakes-axi) finds the mistakes your agents keep repeating; [first-draft-axi](https://www.npmjs.com/package/first-draft-axi) turns a prompt into design mocks you can judge a capture against.
 
+## Known limits
 
-[Firstmate](https://github.com/kunchenguid/firstmate) hands tasks to agent workers and merges their work. done-done ships what those workers need to prove each task, and what the merge needs to check that proof, in [`integrations/firstmate/`](integrations/firstmate/).
+- **Claude Code and Codex are proven live. OpenCode is not yet proven live** on our test machine ([why, and what to try](docs/reference.md#agent-and-judge-support-today)).
+- Codex readers and probes need a CLI with `exec --ignore-user-config` and `debug models --bundled`. Codex is not a judge route; a Pi judge on `openai-codex/gpt-6.1-sol` judges through your existing Codex login.
+- done-done keeps no login of its own: every agent and judge call runs your installed, signed-in CLI on your plan or key.
+- Early preview: behaviour and config keys can change between minor versions.
 
-Install the skill once per machine for your workers' agent (the same `-a` values), install the CLI from npm, and copy two files from it into your Firstmate home:
+## Manual CLI
 
-```sh
-npx skills add umeranjum17/done-done-axi --skill done-done -g -a <agent> -y
-npm install -g done-done-axi
-cat "$(npm root -g)/done-done-axi/integrations/firstmate/brief-include.md" >> "$FM_HOME/config/brief-include.md"
-cp "$(npm root -g)/done-done-axi/integrations/firstmate/merge-gate" "$FM_HOME/config/merge-gate"
-```
-
-- **`brief-include.md`**: Firstmate adds `config/brief-include.md` to every worker brief. It tells the worker to set up done-done, run the journeys `done-done affected` lists for its committed change, write a `## Checks` block, pass `check`, record a `receipt`, and see `affected` exit 0. The evidence and receipt stay in `~/.done-done/evidence/<app>` after teardown deletes the worktree.
-- **`merge-gate`** (optional): `merge-gate <task-id> <worktree|-> <head> <pr-url|->`. In the worktree, it refuses a PR whose head is not `<head>`, then runs `done-done check --from <PR URL or $FM_HOME/data/<task-id>/checks.md> --trusted-ref <default branch>` (`origin/HEAD`, else `origin/main` or `origin/master`, else the local `main` or `master` in a repo with no remote), then `done-done receipt --verify <head>`. Both paths read done-done's rules from your default branch, never from the task's own branch, so merge `.done-done.yaml` there before you rely on it. The gate does not fetch: it reads the local `origin` refs, so run `git fetch origin` before you run it. It needs `done-done` on PATH (the `npm install` line above). A nonzero exit refuses the merge, and done-done's output says why. A worktree of `-` means the task recorded none, so there is no repo to check: the gate refuses (exit 2) rather than check whatever folder it was called from. Its `check` always starts the judge the user set, which must pass each capture; with none set, the gate refuses (exit 2). Upstream Firstmate does not call a merge gate yet, so this file has no effect until it does; you can run it by hand before a merge.
-
-Another fleet works the same way: add the include text to whatever your workers read first, and run `merge-gate` before each merge, with `FM_HOME` set to the folder that holds `data/<task-id>/checks.md` for local-only tasks.
+Prefer a terminal to an agent skill? The [manual walkthrough](docs/manual-cli.md) covers installation without sudo, choosing agents, capture recipes, core and upgrade journeys, hooks, `doctor`, checks, receipts and the verify/fix loop. Every behaviour detail is there or in the [full reference](docs/reference.md).
 
 ## Learn more
 
 - [Vision](VISION.md): who done-done is for, the problem, where it is going, what it is not, and the next milestones.
-- [Worked example: a CLI project](docs/example-cli.md): set up, one journey, check and receipt on a command-line tool.
-- [Worked example: create and maintain a verify skill](docs/example-create-maintain.md): init writes the skill, a source change makes it drift, maintain fixes it, then a real browser journey is judged.
+- [Worked example: a CLI project](docs/example-cli.md) and [create and maintain a verify skill](docs/example-create-maintain.md).
 - [Full reference](docs/reference.md): every command and option, the Checks block rules, each file check, and both config files.
-- [Config reference](docs/reference.md#config): optional global `judge.account_command` selects a pooled Claude account for judge and agent calls; an exported `CLAUDE_CONFIG_DIR` wins; optional `judge.fallback_route: answerer:pi` with `agent_config.pi.model: openai-codex/gpt-6.1-sol` uses Codex when Claude has no eligible account, sign-in or usage left.
+- [Config reference](docs/reference.md#config): pooled Claude accounts for judge and agent calls, and the Codex fallback route.
 - [Report a problem or ask a question](https://github.com/umeranjum17/done-done-axi/issues)
 
 ## What's next
 
-So far: `init`, `doctor`, `run` (including `--open` and `--close`), `check`, `receipt`, `affected` (the journeys a diff needs), `lint` (a no-model gate on a Checks block), `gate` (a no-model CI check of a committed receipt), `verify` (by journey or by your coding agent, with a gate you answer with `respond`), `journey add`, `enhance` and `improve` (journeys from plain words), `maintain`, the capture judge (always on), the `design` visual check, the `look` step, the run tools (`status`, `attach`, `logs`, `rerun`, `abort`, `signoff`, `history`) and the opt-in session hooks for Claude Code, Codex, opencode, Gemini CLI and pi. Coming next: the [milestones in the vision](VISION.md#next-milestones).
+Early preview: behaviour and config keys can change between minor versions. Shipped so far: `init`, `doctor`, `run`, `check`, `receipt`, `verify`, `journey add|enhance|improve`, `maintain`, `affected`, `lint`, `gate`, `design`, `look`, and the run tools (`status`, `attach`, `logs`, `rerun`, `abort`, `signoff`, `history`). Next: the [milestones in the vision](VISION.md#next-milestones).
 
 ## Develop
 
@@ -246,20 +148,9 @@ So far: `init`, `doctor`, `run` (including `--open` and `--close`), `check`, `re
 git clone https://github.com/umeranjum17/done-done-axi
 cd done-done-axi
 npm install
-npm install -g --prefix ~/.local .   # optional: links this checkout as done-done on your PATH
-npm test   # builds, then runs the end-to-end tests against throwaway git repos
-npm run build:skill              # regenerate skills/done-done/SKILL.md from src/skill.ts
-npm run build:skill -- --check   # fail if the committed skill is out of date
-```
-
-To try an unreleased commit without cloning, run it straight from GitHub (npm 12 needs `--allow-git=all`):
-
-```sh
-npx -y --allow-git=all github:umeranjum17/done-done-axi --help
+npm test
 ```
 
-`dist/` is committed, so installing from GitHub needs no build step. `npm test` rebuilds it and fails while the rebuilt `dist/` differs from the commit or has files git does not track, so `git add` the new `dist/` files with your change.
-
-The first-screen PNG pairs an actual sample-app screenshot with its real configured-judge pass and captured commit. Start a fresh sample with `node docs/media/demo.mjs <fresh-scratch-directory> 0` (the server prints its owned port), open a native run in its `app/` repo, drive the checklist in the browser, save `app.png` at 400×140 DPR 2 into the run's evidence folder, seal it and run `check` with your configured judge. Save the open result as `<scratch>/open.json` and the check result as `<scratch>/check.json`; `/proof` displays that screenshot and verdict. Capture `/proof` at 400×230 DPR 2 with `chrome-devtools-axi`. It refuses to show a pass without a real passing result. Keep scratch outside the repo and stop the server afterwards. The lower terminal illustrations (hero, run, pass, reasons, config) use a stub judge (no model); redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
+`npm test` builds, then runs the end-to-end tests against throwaway git repos. `dist/` is committed, so installing from GitHub needs no build step; `npm test` fails while the rebuilt `dist/` differs from the commit, so `git add` the new files with your change. [Working on done-done](docs/reference.md#working-on-done-done) covers the skill build, the sample app and the screenshots.
 
 The landing page ([`docs/index.html`](docs/index.html), served by GitHub Pages from `main` `/docs`) is static: change it in the same PR as any README change it repeats (install steps, what it checks, the other tools).

package/dist/agents.js

@@ -342,9 +342,11 @@ export const agentChoices = () => [...AGENTS, 'acp:<target>'];
 const askError = (kind, choices, rule, save) => new UsageError(`no ${kind} is set: ask the user which ${kind} to use (${choices}); ${rule}`, `Save the user's answer: ${save}`);
 export const noAgent = () => askError('agent', agentChoices().join(', '), 'never pick one for them', `done-done init --agent <agent> --model <model>, e.g. done-done init --agent opencode --model ${CHEAP.opencode.model}`);
 export const modelFor = (cfg, agent) => cfg.agent_config[agent]?.model || CHEAP[agent]?.model || '';
+// The configured model pool (judge.pool_command and its helper config), or undefined: standalone users keep today's behaviour.
+export const modelPool = (cfg) => cfg.judge.pool_command ? { command: cfg.judge.pool_command, config: cfg.judge.pool_config, binFor: (agent) => agentPath(agent, cfg) } : undefined;
 export const agentRun = (cfg, agent, model = modelFor(cfg, agent)) => ({
     agent, model, effort: cfg.agent_config[agent]?.effort ?? '', args: cfg.agent_args_override[agent] ?? [], path: agentPath(agent, cfg), override: cfg.agent_path_override[agent] ?? '', timeoutMs: parseDuration(cfg.agent_timeout),
-    ...(agent === 'claude' && cfg.judge.account_command ? { accountCommand: cfg.judge.account_command } : {}),
+    ...(agent === 'claude' && (modelPool(cfg) ? { pool: modelPool(cfg) } : cfg.judge.account_command ? { accountCommand: cfg.judge.account_command } : {})),
 });
 export const notStartable = (agent, override = '') => (override ? `agent_path_override.${agent} ${override} is not an executable file` : `${agent} is not on PATH`);
 // The known agent an agent names, for the judge-independence check: acp:claude-code is claude; a target that
@@ -415,9 +417,24 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
         let error;
         let drain;
         let idle;
+        // pi streams JSON events, and it echoes the whole transcript (prompt and answer included), so on stdout only an event that
+        // reports an error is a limit: never the words it was sent or wrote.
+        const piQuiet = (l) => {
+            if (!l.trimStart().startsWith('{'))
+                return false;
+            try {
+                const parsed = JSON.parse(l);
+                return parsed?.type !== 'error' && parsed?.message?.stopReason !== 'error';
+            }
+            catch {
+                return false;
+            }
+        };
         // A rate-limit line ends the call with that line, whatever the agent does next. On stdout the line must also say when it resets or retries,
         // so an answer that only quotes a 429 from the app's code does not stop the call. A claude call with images streams JSON lines,
-        // and only a rejected rate_limit_event on stdout stops it, so its complete lines are parsed one at a time.
+        // and only a rejected rate_limit_event on stdout stops it, so its complete lines are parsed one at a time. pi streams its whole
+        // transcript at the end (agent_end carries the prompt and the answer), so only its own error event is a limit there: a judge
+        // asked about rate limits must not be stopped by the words it was sent.
         let pendingStdout = '';
         const limited = (chunk, stdoutLine) => {
             let line;
@@ -430,7 +447,8 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
                 line = text.slice(0, end).split('\n').find(isRejectedRateLimit);
             }
             else {
-                line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l)));
+                line = stripVTControlCharacters(chunk).split(/\r?\n/).find((l) => RATE_LIMIT.test(l) && (!stdoutLine || /reset|retry/i.test(l))
+                    && (!stdoutLine || c.agent !== 'pi' || !piQuiet(l)));
                 if (line)
                     line = limitText(line);
             }
@@ -510,6 +528,97 @@ function start(bin, argv, c, cwd, input, env, idleMs) {
         child.stdin.end(input);
     });
 }
+// A fall-over route as this machine runs it: the helper names a route id, done-done runs the agent and model it has here.
+const POOL_ROUTES = {
+    'route:openai-codex/gpt-6.1-sol': { agent: 'codex', model: 'gpt-6.1-sol' },
+    'route:deepseek/deepseek-goat': { agent: 'pi', model: 'commandcode/deepseek/deepseek-v4.1-flash' },
+    'route:cursor/auto': { agent: 'pi', model: 'cursor/auto' },
+};
+// A typed limit moves the call to the next account or route; usage credits and overage stop it with their own cause.
+const USAGE_CREDITS = /usage[ _-]?credits?|overage|credit balance|\bcredits?\b|insufficient (?:credits?|funds)|\b402\b/i;
+const TYPED_LIMIT = /rate[ -]?limit|usage limit|too many requests|quota exceeded|\b429\b/i;
+const poolKey = (p) => `${p.command}\0${p.config}`;
+let poolFirst; // one first answer per process, as the account command is
+let poolInUse; // the account or route this process is on now
+// One helper call: the request JSON on stdin, one answer JSON. Nothing but the configured command passes through a shell.
+function poolAsk(pool, verb, req) {
+    const fail = (why, unavailable = false) => {
+        throw new (unavailable ? ClaudeUnavailable : UsageError)(`judge.pool_command: ${why}`, 'Fix judge.pool_command and judge.pool_config in the global config, or remove them for plain Claude sign-in');
+    };
+    const r = spawnSync(`${pool.command} ${verb} --json`, { shell: true, encoding: 'utf8', input: JSON.stringify(req), timeout: 30_000, maxBuffer: 64 * 1024 });
+    if (r.error)
+        fail(r.error.code ?? 'command could not start');
+    const said = typeof r.stderr === 'string' ? errorLine(r.stderr) : '';
+    let a;
+    try {
+        a = JSON.parse(r.stdout);
+    }
+    catch {
+        fail(r.status === 0 ? 'invalid JSON' : `command exited ${r.status}: ${said || 'no answer'}`);
+    }
+    const reason = typeof a?.reason === 'string' ? errorLine(a.reason) : said || 'no answer';
+    const billing = String(a?.billing_classification ?? a?.billing ?? '');
+    // The helper refuses credits-enabled accounts and routes; a call that reached one anyway is refused the same way.
+    if (USAGE_CREDITS.test(billing) || USAGE_CREDITS.test(typeof a?.reason === 'string' ? a.reason : ''))
+        fail(`the pool answered ${typeof a?.id === 'string' ? a.id : 'a route'} on usage credits or overage, which done-done never spends${reason === 'no answer' ? '' : `: ${reason}`}`);
+    if (r.status !== 0 || a?.ok !== true)
+        fail(reason, a?.ok === false || a === null);
+    if (typeof a.id !== 'string' || !/^[A-Za-z0-9_:./-]{1,128}$/.test(a.id))
+        fail('invalid account or route id');
+    const set = a.set ?? {};
+    const unset = a.unset ?? [];
+    if (!set || typeof set !== 'object' || Array.isArray(set) || !Object.entries(set).every(([k, v]) => /^[A-Za-z_]\w*$/.test(k) && typeof v === 'string'))
+        fail('set must be a map of environment variable names to strings');
+    if (!Array.isArray(unset) || !unset.every((n) => typeof n === 'string' && /^[A-Za-z_]\w*$/.test(n)))
+        fail('unset must be a list of environment variable names');
+    if (unset.includes('CLAUDE_CONFIG_DIR'))
+        fail('cannot unset CLAUDE_CONFIG_DIR');
+    const route = typeof a.provider === 'string' && a.provider !== 'claude';
+    // A known route id runs on the agent and model this tool has here; any other route runs its own harness when done-done knows it.
+    const mapped = route ? POOL_ROUTES[a.id] ?? (AGENTS.includes(a.harness) ? { agent: a.harness, model: String(a.model ?? '') } : undefined) : undefined;
+    if (route && !mapped)
+        fail(`route ${a.id} names no agent done-done can run`, true);
+    if (!route) {
+        const folder = set.CLAUDE_CONFIG_DIR;
+        let directory = false;
+        try {
+            directory = typeof folder === 'string' && isAbsolute(folder) && statSync(folder).isDirectory();
+        }
+        catch { }
+        if (!directory)
+            fail('set.CLAUDE_CONFIG_DIR must be an absolute existing folder');
+    }
+    return { id: a.id, set, unset, agent: mapped?.agent ?? 'claude', model: mapped?.model ?? '', route, raw: a };
+}
+// The account or fall-over route a pooled call starts on: the first answer is shared by every call in this process.
+function poolPickFor(pool, model, deadlineMs) {
+    if (poolInUse)
+        return Promise.resolve(poolInUse);
+    const key = poolKey(pool);
+    if (poolFirst?.key !== key)
+        poolFirst = { key, pick: Promise.resolve().then(() => poolAsk(pool, 'pick', { v: 1, purpose: 'work', pool_config: pool.config, model, capabilities: ['text'], deadline: Math.floor(deadlineMs / 1000) })).then((p) => (poolInUse = p)) };
+    return poolFirst.pick;
+}
+// The account id or fall-over route a Claude call answers on, named in the judge's result detail; '' when none is configured.
+export async function accountDetail(cfg, agent, model) {
+    const pool = agent === 'claude' ? modelPool(cfg) : undefined;
+    if (pool) {
+        const deadline = Date.now() + parseDuration(cfg.agent_timeout);
+        const attempted = [];
+        let pick = await poolPickFor(pool, model, deadline);
+        // A route this machine cannot start (Codex is out until 30 Oct, for one) is not the one that would answer, so the
+        // pre-check asks for the next one exactly as the call does, and fails closed when none can start.
+        while (pick.route && !pool.binFor(pick.agent)) {
+            if (attempted.length === 5)
+                throw new ClaudeUnavailable(`judge.pool_command: no account or route the helper answered can start on this machine (${attempted.join(', ')})`, 'Install one of the route agents, or remove judge.pool_command and judge.pool_config');
+            attempted.push(pick.id);
+            pick = poolAsk(pool, 'next', { v: 1, purpose: 'work', pool_config: pool.config, model, capabilities: ['text'], deadline: Math.floor(deadline / 1000), selection: pick.raw, cause: 'unavailable', attempted: [...attempted] });
+        }
+        return pick.route ? `pool route ${pick.id}` : `Claude account ${pick.id}`;
+    }
+    const account = await claudeAccount(agent, cfg.judge.account_command);
+    return account ? `Claude account ${account.id}` : '';
+}
 // A valid picker refusal is availability, not a malformed account configuration.
 export class ClaudeUnavailable extends UsageError {
 }
@@ -552,8 +661,44 @@ export function claudeAccount(agent, command) {
     });
 }
 export async function askAgent(c) {
-    const adapter = adapterFor(c.agent);
-    const argv = (d) => (adapter ? [...adapter.argv(c, d), ...(c.effort ? EFFORT_FLAGS[c.agent]?.(c.effort) ?? [] : []), ...(c.args ?? [])] : []);
+    // The model pool owns the call's agent, model and account environment: a typed limit moves it to the helper's next
+    // account or fall-over route, and the call's own timeout is the one deadline that whole chain shares.
+    const deadline = Date.now() + c.timeoutMs;
+    let call = c;
+    let picked;
+    const attempted = [];
+    const argv = (d) => {
+        const adapter = adapterFor(call.agent);
+        return adapter ? [...adapter.argv(call, d), ...(call.effort ? EFFORT_FLAGS[call.agent]?.(call.effort) ?? [] : []), ...(call.args ?? [])] : [];
+    };
+    // The helper's next account or route that can run here, inside the one deadline: a route whose agent this machine cannot
+    // start (Codex is out until 30 Oct, for one) joins `attempted` and the helper is asked for the next one.
+    const poolStep = (cause) => {
+        const pool = call.pool;
+        while (pool && picked && Date.now() + 5_000 < deadline) {
+            const prior = picked;
+            const next = poolAsk(pool, 'next', { v: 1, purpose: 'work', pool_config: pool.config, model: c.model, capabilities: ['text'], deadline: Math.floor(deadline / 1000), selection: prior.raw, cause, attempted: [...attempted] });
+            const bin = next.agent === c.agent ? c.path : pool.binFor(next.agent);
+            if (bin) {
+                picked = poolInUse = next;
+                call = { ...call, agent: next.agent, model: next.model || c.model, path: bin, effort: next.agent === c.agent ? c.effort : '' };
+                return true;
+            }
+            attempted.push(next.id);
+        }
+        return false;
+    };
+    // One move on a typed limit: the helper rests the limited account and answers the next account or fall-over route.
+    const moveOn = async (text) => {
+        if (!call.pool || !picked)
+            return false;
+        if (USAGE_CREDITS.test(text))
+            throw new UsageError(`done-done never spends usage credits or overage: ${picked.id} answered (${errorLine(text)})`, 'Use an account or route on your plan, then re-run; nothing is charged');
+        if (!TYPED_LIMIT.test(text))
+            return false;
+        attempted.push(picked.id);
+        return poolStep('rate_limit');
+    };
     const started = Date.now();
     let dir = '';
     let cwd = c.cwd;
@@ -564,43 +709,69 @@ export async function askAgent(c) {
     try {
         dir = mkdtempSync(join(tmpdir(), 'done-done-agent-'));
         cwd = c.tools === 'none' ? dir : c.cwd;
-        if (!adapter)
-            throw new Error(`no adapter for ${c.agent} yet`);
-        const bin = c.path;
-        if (!bin)
-            throw new Error(c.agent.startsWith('acp:') ? `${c.agent} needs acpx, and acpx is not startable; ${ACPX_INSTALL}` : notStartable(c.agent, c.override));
-        const account = await claudeAccount(c.agent, c.accountCommand);
-        const env = { ...process.env, ...c.env, ...adapter.env?.(c), ...(account && { CLAUDE_CONFIG_DIR: account.folder }) };
-        for (const name of account?.unset ?? [])
-            delete env[name];
-        if (adapter.readsImages)
-            for (const i of c.images ?? [])
-                writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
-        for (const [name, text] of Object.entries(adapter.files?.(c) ?? {}))
-            writeFileSync(join(dir, name), text, { mode: 0o600 });
+        if (call.pool) {
+            // The pool's first answer, or the next one when the route it names cannot start here.
+            const pool = call.pool;
+            picked = await poolPickFor(pool, call.model, deadline);
+            const bin = picked.agent === c.agent ? c.path : pool.binFor(picked.agent);
+            if (bin)
+                call = { ...call, agent: picked.agent, model: picked.model || call.model, path: bin, effort: picked.agent === c.agent ? c.effort : '' };
+            else {
+                attempted.push(picked.id);
+                if (!poolStep('unavailable'))
+                    throw new ClaudeUnavailable(`judge.pool_command: no account or route the helper answered can start on this machine (${[...attempted].join(', ')})`, 'Install one of the route agents, or remove judge.pool_command and judge.pool_config');
+            }
+        }
         let lastError = '';
         for (;;) {
+            const adapter = adapterFor(call.agent);
+            if (!adapter)
+                throw new Error(`no adapter for ${call.agent} yet`);
+            const bin = call.path;
+            if (!bin)
+                throw new Error(call.agent.startsWith('acp:') ? `${call.agent} needs acpx, and acpx is not startable; ${ACPX_INSTALL}` : notStartable(call.agent, call.override));
+            const account = call.accountCommand ? await claudeAccount(call.agent, call.accountCommand) : undefined;
+            const env = { ...process.env, ...call.env, ...adapter.env?.(call), ...(account && { CLAUDE_CONFIG_DIR: account.folder }) };
+            for (const name of account?.unset ?? [])
+                delete env[name];
+            if (picked) {
+                for (const [name, value] of Object.entries(picked.set))
+                    env[name] = value;
+                for (const name of picked.unset)
+                    delete env[name];
+            }
+            if (adapter.readsImages)
+                for (const i of call.images ?? [])
+                    writeFileSync(join(dir, i.name), i.bytes, { mode: 0o600 });
+            for (const [name, text] of Object.entries(adapter.files?.(call) ?? {}))
+                writeFileSync(join(dir, name), text, { mode: 0o600 });
             attempts++;
             // An ask-again names what was wrong with the last answer. The trailer ends on words, not the schema: a weak model
             // (seen with one opencode model) copied a schema that closed the prompt back as its answer.
-            const schemaTrailer = `\n\nAnswer with only one JSON object that matches this JSON schema:\n${JSON.stringify(c.schema)}\nThat object holds your own values, never the schema itself, and you send no other text.\n`;
-            const prompt = c.tools === 'edit' && adapter.editNote ? `${c.prompt}\n\n${adapter.editNote}` : c.prompt;
+            const schemaTrailer = `\n\nAnswer with only one JSON object that matches this JSON schema:\n${JSON.stringify(call.schema)}\nThat object holds your own values, never the schema itself, and you send no other text.\n`;
+            const prompt = call.tools === 'edit' && adapter.editNote ? `${call.prompt}\n\n${adapter.editNote}` : call.prompt;
             const promptText = (attempts === 1 ? prompt : `${prompt}\n\nYour previous answer was not valid (${lastError}).`) + schemaTrailer;
             if (adapter.file)
                 writeFileSync(join(dir, 'prompt.md'), promptText, { mode: 0o600 });
-            const input = adapter.file ? '' : adapter.stdin ? adapter.stdin(c, promptText) : promptText;
-            res = await start(bin, argv(dir), c, cwd, input, env, adapter.streams ? c.idleMs ?? AGENT_IDLE_MS : 0);
-            if (res.error)
+            const input = adapter.file ? '' : adapter.stdin ? adapter.stdin(call, promptText) : promptText;
+            const remain = Math.max(1_000, Math.min(call.timeoutMs, deadline - Date.now()));
+            res = await start(bin, argv(dir), { ...call, timeoutMs: remain }, cwd, input, env, adapter.streams ? call.idleMs ?? AGENT_IDLE_MS : 0);
+            if (res.error) {
+                if (await moveOn(res.error.message)) {
+                    attempts--;
+                    continue;
+                }
                 throw res.error;
+            }
             // A permission the run refused explains a call with no answer; name it rather than the exit code text.
             const refused = adapter.reject?.(String(res.stderr ?? '')) ?? '';
             if (res.status !== 0 && refused)
-                throw new ProviderError(refused, `${c.agent} exited ${res.status}: `);
+                throw new ProviderError(refused, `${call.agent} exited ${res.status}: `);
             if (res.status !== 0) {
                 // An agent that exits non-zero may still say why in its own output (claude: a usage limit, a bad model).
                 let text = String(res.stderr || res.stdout).trim().slice(-500);
                 try {
-                    adapter.answer(String(res.stdout), c);
+                    adapter.answer(String(res.stdout), call);
                 }
                 catch (e) {
                     if (e instanceof ProviderError)
@@ -608,16 +779,20 @@ export async function askAgent(c) {
                     else if (!(e instanceof SyntaxError))
                         text = e.message;
                 }
-                throw new ProviderError(text, `${c.agent} exited ${res.status}: `, adapter.hint && c.tools !== 'none' ? `; ${adapter.hint}` : '');
+                if (await moveOn(text)) {
+                    attempts--;
+                    continue;
+                }
+                throw new ProviderError(text, `${call.agent} exited ${res.status}: `, adapter.hint && call.tools !== 'none' ? `; ${adapter.hint}` : '');
             }
             try {
-                const answer = adapter.answer(String(res.stdout), c);
+                const answer = adapter.answer(String(res.stdout), call);
                 if (!answer || typeof answer !== 'object' || Array.isArray(answer))
                     throw new Error(`the answer is not a JSON object: ${JSON.stringify(answer)}`);
-                const missing = (c.schema.required ?? []).filter((k) => !(k in answer));
+                const missing = (call.schema.required ?? []).filter((k) => !(k in answer));
                 if (missing.length)
                     throw new Error(`the answer does not match the schema (missing ${missing.join(', ')}): ${JSON.stringify(answer).slice(0, 200)}`);
-                out = { ok: true, answer: answer };
+                out = { ok: true, answer: answer, ...(picked && (picked.route ? { route: picked.id } : { account: picked.id })) };
                 break;
             }
             catch (e) {
@@ -625,10 +800,10 @@ export async function askAgent(c) {
                     throw e;
                 // A refused permission is why there is no usable answer, not a bad answer: name it instead of "no JSON object".
                 if (refused)
-                    throw new ProviderError(refused, `${c.agent} did not finish: `);
+                    throw new ProviderError(refused, `${call.agent} did not finish: `);
                 // Only a tool-less call is asked again: an edit or read step may already have changed the repo or read it.
                 lastError = e.message;
-                if (c.tools !== 'none' || attempts >= (c.attempts ?? ASK_ATTEMPTS))
+                if (call.tools !== 'none' || attempts >= (call.attempts ?? ASK_ATTEMPTS))
                     throw new Error(`the agent did not answer with valid JSON after ${attempts} ${attempts === 1 ? 'try' : 'tries'}: ${lastError}`);
             }
         }
@@ -638,7 +813,7 @@ export async function askAgent(c) {
         // carries its own line, so it is left as it is.
         const said = stderrHead(String(res?.stderr ?? ''));
         const provider = e instanceof ProviderError;
-        const note = (text) => (!provider && said && !text.includes(said.split(' | ')[0]) ? `${text}; ${c.agent} stderr: ${said}` : text);
+        const note = (text) => (!provider && said && !text.includes(said.split(' | ')[0]) ? `${text}; ${call.agent} stderr: ${said}` : text);
         out = { ok: false, error: note(e.message), ...(!provider && said ? { stderr: said } : {}) };
         failure = note(e instanceof ProviderError ? e.detail : e.message);
     }
@@ -647,9 +822,9 @@ export async function askAgent(c) {
             rmSync(dir, { recursive: true, force: true });
     }
     // The record holds what ran and what came back, never the prompt text or an image.
-    const { prompt, images, ...call } = c;
+    const { prompt, images, pool, ...spec } = c;
     try {
-        const record = { ...call, ...(images && { images: images.map((i) => i.name) }), cwd, prompt_bytes: Buffer.byteLength(prompt), argv: argv('<tmp>'), ms: Date.now() - started, exit: res?.status ?? null, attempts, ...out, error: failure, stderr: String(res?.stderr ?? '').slice(-2000) };
+        const record = { ...spec, agent: call.agent, model: call.model, ...(picked && (picked.route ? { route: picked.id } : { account: picked.id })), ...(images && { images: images.map((i) => i.name) }), cwd, prompt_bytes: Buffer.byteLength(prompt), argv: argv('<tmp>'), ms: Date.now() - started, exit: res?.status ?? null, attempts, ...out, error: failure, stderr: String(res?.stderr ?? '').slice(-2000) };
         mkdirSync(dirname(c.record), { recursive: true });
         writeFileSync(c.record, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
         out = { ...out, record: c.record };

package/dist/cli.js

@@ -118,6 +118,7 @@ const CONFIG_TEXT = `config: ~/.done-done/config.yaml (global; DONE_DONE_HOME mo
   global only: agent_config.<agent>.{model,effort} (effort: minimal, low, medium, high, xhigh, max), agent_args_override.<agent>
   (extra flags), agent_path_override.<agent> (binary), acpx_path, agent_timeout (one agent call, default 30m; a streaming agent that prints nothing for 5m is stopped early),
   judge.account_command (optional Claude account pick; exported CLAUDE_CONFIG_DIR wins),
+  judge.pool_command with judge.pool_config (optional shared model pool: the Claude account, a move on a rate/usage limit, and a fall-over route),
   judge.fallback_route (optional second judge, same values as judge.route; Claude usage/rate/sign-in limits or an empty pool trigger it;
   e.g. answerer:pi with agent_config.pi.model: openai-codex/gpt-6.1-sol; unset keeps Claude failures as errors; no fallback chains),
   evidence.local_root, judge.{route,model,floor} (the judge and shared confidence floor, set by the user with

package/dist/config.js

@@ -89,6 +89,8 @@ const KEYS = {
     'judge.floor': { scope: 'global', type: 'number' },
     'judge.env_file': { scope: 'global', type: 'string' },
     'judge.account_command': { scope: 'global', type: 'string' },
+    'judge.pool_command': { scope: 'global', type: 'string' },
+    'judge.pool_config': { scope: 'global', type: 'string' },
     'judge.fallback_route': { scope: 'global', type: 'route' },
 };
 const SECTIONS = new Set(['evidence', 'secrets', 'checks', 'judge', 'signoff']);
@@ -369,7 +371,7 @@ function defaultConfig(repo) {
         secrets: { patterns: {}, allow: [] },
         checks: { fix_title: '^(fix|bugfix|hotfix)\\b', upstream_catch_up: false, moved_from: false, generated_paths: [] },
         signoff: { post: false, board: '' },
-        judge: { route: '', fallback_route: '', model: '', floor: 0.7, env_file: '', account_command: '' },
+        judge: { route: '', fallback_route: '', model: '', floor: 0.7, env_file: '', account_command: '', pool_command: '', pool_config: '' },
         trusted: false,
         from: {},
     };
@@ -382,6 +384,18 @@ export function loadConfig(repo, projectText) {
     apply(cfg, readOptional(globalFile), globalFile, 'global');
     const projectFile = join(repo, '.done-done.yaml');
     apply(cfg, projectText ?? readOptional(projectFile), projectFile, 'repo');
+    // The model pool needs both its helper command and the helper's own pool config; it replaces the Claude account command.
+    if (cfg.judge.pool_config) {
+        cfg.judge.pool_config = tilde(cfg.judge.pool_config);
+        if (!isAbsolute(cfg.judge.pool_config))
+            throw new UsageError(`${globalFile}: judge.pool_config must be the absolute path of the model pool helper's config/account-pool`, 'Set judge.pool_config in the global config, or remove it');
+    }
+    if (cfg.judge.pool_command) {
+        if (!cfg.judge.pool_config)
+            throw new UsageError(`${globalFile}: judge.pool_command needs judge.pool_config, the absolute path of the helper's config/account-pool`, 'Set judge.pool_config in the global config, or remove judge.pool_command');
+        if (cfg.judge.account_command)
+            throw new UsageError(`${globalFile}: judge.pool_command and judge.account_command are both set: the model pool already picks the Claude account`, 'Delete the judge.account_command line in the global config');
+    }
     // A skill dir an older init wrote (verify-<app>) is still read until init renames it to the prefixed name.
     cfg.skill ||= existsSync(join(repo, `.agents/skills/done-done-verify-${cfg.app}`)) || !existsSync(join(repo, `.agents/skills/verify-${cfg.app}`))
         ? `.agents/skills/done-done-verify-${cfg.app}` : `.agents/skills/verify-${cfg.app}`;
@@ -460,5 +474,9 @@ judge:
   # env_file: ~/.config/done-done/judge.env
   # Optional shell command printing one account-pick JSON for Claude judge and agent calls; an exported CLAUDE_CONFIG_DIR wins.
   # account_command: account-picker pick claude --json
+  # Optional shared model pool (firstmate-addons account-pool/bin/fm-model-pool): it picks the Claude account, moves on a
+  # rate/usage limit, and falls over to another route; pool_config is the helper's own config/account-pool file.
+  # pool_command: fm-model-pool
+  # pool_config: ~/firstmate/config/account-pool
 `;
 }

package/dist/judge.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { accessSync, constants, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, delimiter, isAbsolute, join } from 'node:path';
-import { agentRun, askAgent, claudeAccount, ClaudeUnavailable, notStartable } from './agents.js';
+import { accountDetail, agentRun, askAgent, ClaudeUnavailable, notStartable } from './agents.js';
 import { home, KEY_ROUTES, parseDuration, tilde, UsageError } from './config.js';
 import { downscaleToPng } from './media.js';
 const MAX_SIDE = 1280; // long edge sent to the model, in pixels
@@ -146,7 +146,7 @@ export async function backend(cfg, choice, record = () => '', questions = { rele
     const claude = choice.agent === 'claude';
     if (!bin)
         throw new UsageError(`judge: ${notStartable(choice.agent, override)}`, claude ? (override ? 'Fix agent_path_override.claude in ~/.done-done/config.yaml, or install Claude Code' : 'Install Claude Code, or set agent_path_override.claude to its absolute path') : `Install ${choice.agent}, or ask the user for another judge and save it: done-done init --judge <agent> --judge-model <model>`);
-    const account = await claudeAccount(choice.agent, cfg.judge.account_command);
+    const account = await accountDetail(cfg, choice.agent, choice.model);
     const { answerer, resolve } = await kit();
     let lastError = '';
     // The kit hides a failed call's message from the verdict, so the real cause is kept here for the result.
@@ -168,7 +168,7 @@ export async function backend(cfg, choice, record = () => '', questions = { rele
             return { text: JSON.stringify(a.answer) };
         },
     }).ask;
-    return { ask, resolve, lastError: () => lastError, detail: account ? `Claude account ${account.id}` : claude ? `claude binary at ${bin} and the judge kit are present; it judges with your own claude sign-in` : `${choice.agent} at ${bin} and the judge kit are present; it judges with every tool off` };
+    return { ask, resolve, lastError: () => lastError, detail: account || (claude ? `claude binary at ${bin} and the judge kit are present; it judges with your own claude sign-in` : `${choice.agent} at ${bin} and the judge kit are present; it judges with every tool off`) };
 }
 // The parts list as the model gave it: labels trimmed and in its own order, so a cover position still names its label.
 const labels = (x) => (Array.isArray(x) && x.every((s) => typeof s === 'string') ? x.map((s) => s.trim()) : undefined);
@@ -354,16 +354,21 @@ async function judgeBatch(cfg, choice, outcome, captures, records, dir) {
     return { judged, notJudged, choice, missing };
 }
 async function judgeOn(cfg, choose, outcome, captures, records) {
-    // Check the account even on a verdict cache hit: a broken configured picker must never produce a pass.
-    const account = await claudeAccount(choose().agent, cfg.judge.account_command);
-    const detail = account ? { detail: `Claude account ${account.id}` } : {};
+    // Check the account or pool route even on a verdict cache hit: a broken configured picker must never produce a pass.
+    const first = choose();
+    await accountDetail(cfg, first.agent, first.model);
+    // After the calls, the detail names the account id or fall-over route that actually answered.
+    const named = async (result) => {
+        const detail = await accountDetail(cfg, first.agent, first.model);
+        return detail ? { ...result, detail } : result;
+    };
     const dir = join(home(), 'runs', cfg.app, 'judge');
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
     const judged = [];
     const notJudged = [];
     const batchChoice = captures.filter(judgeable).length > 1 ? choose() : undefined;
     if (batchChoice && batchChoice.route !== 'openai:key')
-        return { ...await judgeBatch(cfg, batchChoice, outcome, captures, records, dir), ...detail };
+        return named(await judgeBatch(cfg, batchChoice, outcome, captures, records, dir));
     let choice;
     let be;
     let calls = 0;
@@ -423,5 +428,5 @@ async function judgeOn(cfg, choose, outcome, captures, records) {
         judged.push(verdict);
     }
     // Only openai:key can have several independent calls here; it returns no coverage fields.
-    return { judged, notJudged, choice, missing: missingParts(judged), ...detail };
+    return named({ judged, notJudged, choice, missing: missingParts(judged) });
 }

package/docs/index.html

@@ -159,7 +159,7 @@ done-done verify --outcome "&lt;what works now&gt;"</code></pre>
   <section id="firstmate">
     <h2>Inside Firstmate, or outside</h2>
     <p class="lead">done-done behaves the same with or without <a href="https://github.com/kunchenguid/firstmate">Firstmate</a>. Nothing here is needed to use it.</p>
-    <p class="lead">Inside a Firstmate home, <code>integrations/firstmate/</code> ships a brief include that tells each worker to run a journey, write a <code>## Checks</code> block, pass <code>check</code> and record a <code>receipt</code>, and an optional merge gate that refuses a merge without it. A lone agent in a terminal skips all of that. Upstream Firstmate does not call the merge gate yet; run it by hand if you want it to enforce the check. <a href="https://github.com/umeranjum17/done-done-axi#use-with-firstmate-or-another-agent-fleet">Integration instructions</a>.</p>
+    <p class="lead">Inside a Firstmate home, <code>integrations/firstmate/</code> ships a brief include that tells each worker to run a journey, write a <code>## Checks</code> block, pass <code>check</code> and record a <code>receipt</code>, and an optional merge gate that refuses a merge without it. A lone agent in a terminal skips all of that. Upstream Firstmate does not call the merge gate yet; run it by hand if you want it to enforce the check. <a href="https://github.com/umeranjum17/done-done-axi#inside-firstmate-or-another-agent-fleet">Integration instructions</a>.</p>
   </section>
 
   </main>

package/docs/manual-cli.md

@@ -73,4 +73,70 @@ With `auto_fix: { verify: <n> }` (0, the default, reports only), a failed verify
 
 While a `verify` or `maintain` run goes, `done-done status` shows its steps and next move, `done-done attach` streams its events, and `done-done logs --step <name>` shows one step's log. `done-done rerun` runs a failed verify run again from the failed step, `done-done abort` stops a live run, `done-done signoff` writes a verify run's sign-off message, and `done-done history` lists past runs.
 
+**4. Write a journey from plain words**
+
+A journey is the saved script that drives your app and captures what a user sees. You do not have to write it yourself; describe it and the agent you chose at `init` writes it:
+
+```sh
+done-done journey add "greet Umer and check that Hello Umer is printed"
+done-done journey enhance greet-umer-prints-hello "add checks for an empty name and an unknown command"
+done-done journey improve greet-umer-prints-hello "also check that greeting Zoë prints exactly Hello Zoë"
+```
+
+- **`add "<description>"`** writes a new journey: a capture script in `journeys/`, its entry in `.done-done.yaml` and a feature in your verify skill. It names the journey from your words and prints that name.
+- **`enhance <name> ["<focus>"]`** deepens one journey you already have with more steps, edge cases and checks, and keeps the checks it has. Leave out the focus for a general pass.
+- **`improve <name> "<instruction>"`** makes one specific change to one journey and nothing else.
+
+Each command prints the files it changed, then runs the journey once. This is the real output of the three lines above, from a clean install on a small greeting CLI with Claude Code as the agent (run paths cut short with `…`):
+
+```
+$ done-done journey add "greet Umer and check that Hello Umer is printed"
+Added journey greet-umer-prints-hello through claude. Review these repo changes:
+.agents/skills/done-done-verify-hello-umer/features/README.md | 1 +
+ .done-done.yaml                                               | 3 +++
+ 2 files changed, 4 insertions(+)
+ journeys/greet-umer-prints-hello.mjs | 29 new lines
+ .agents/skills/done-done-verify-hello-umer/features/greet-umer-prints-hello.md | 13 new lines
+The first run is a dirty-tree trial, not clean proof. Review and commit, then: done-done run greet-umer-prints-hello
+ok greet-umer-prints-hello
+command: run
+result: recorded
+dirty: true
+files: 1
+evidence[1]: …/terminal.txt
+
+$ done-done journey enhance greet-umer-prints-hello "add checks for an empty name and an unknown command"
+Enhanced journey greet-umer-prints-hello through claude. Review these repo changes:
+.../features/greet-umer-prints-hello.md            |  8 +++++++
+ .done-done.yaml                                    |  4 +++-
+ journeys/greet-umer-prints-hello.mjs               | 27 +++++++++++++++++++---
+ 3 files changed, 35 insertions(+), 4 deletions(-)
+…
+files: 3
+evidence[3]: …/terminal-empty-name.txt,…/terminal-unknown-command.txt,…/terminal.txt
+
+$ done-done journey improve greet-umer-prints-hello "also check that greeting Zoë prints exactly Hello Zoë"
+Improved journey greet-umer-prints-hello through claude. Review these repo changes:
+.../features/greet-umer-prints-hello.md                       |  8 ++++++++
+ .done-done.yaml                                               |  1 +
+ journeys/greet-umer-prints-hello.mjs                          | 11 ++++++++++-
+ 3 files changed, 19 insertions(+), 1 deletion(-)
+…
+files: 4
+evidence[4]: …/terminal-empty-name.txt,…/terminal-unknown-command.txt,…/terminal-zoe.txt,…/terminal.txt
+```
+
+`.done-done.yaml` keeps what you asked for next to the journey:
+
+```yaml
+journeys:
+  greet-umer-prints-hello:
+    command:
+      # Enhanced focus: "add checks for an empty name and an unknown command"
+      # Improved instruction: "also check that greeting Zoë prints exactly Hello Zoë"
+      node journeys/greet-umer-prints-hello.mjs
+```
+
+That first run is a trial on uncommitted files, not proof. Read the generated script as you would any code an agent wrote, commit it, then `done-done run greet-umer-prints-hello` records clean proof (`dirty: false`). The saved script needs no agent or model, so CI can replay it. Generation itself runs only on your machine, never in CI, and uses only the agent you configured. `done-done journey --help` shows these examples; the [reference](reference.md#add-a-journey-from-a-description) has every rule.
+
 Run `done-done` with no arguments to see the current config and the next step.

package/docs/media/hero-refuse.txt

@@ -0,0 +1,4 @@
+$ done-done init --journey tests -- 'npm test'
+command: init
+error: "init --journey tests: npm test is code-only: a test, typecheck, lint or build run proves the code checks pass, not that the product works, so check and gate never count its run as proof; nothing was written"
+exit: 2

package/docs/media/hero-run.txt

@@ -0,0 +1,41 @@
+$ done-done run greet
+command: run
+result: recorded
+run_id: 20261025T033042Z-ca783630-43267e
+commit: ca783630026370864950bce53bc5efab802d29d6
+dirty: false
+files: 1
+record: ~/.done-done/evidence/sample/.done-done/runs/20261025T033042Z-ca783630-43267e.json
+evidence[1]: 20261025T033042Z-ca783630-43267e.terminal.txt
+
+$ done-done check --outcome "running greet.mjs with Umer prints Hello Umer" "$evidence"
+command: check
+result: pass
+claim: running greet.mjs with Umer prints Hello Umer
+files: 1
+evidence[1]: 20261025T033042Z-ca783630-43267e.terminal.txt
+judge:
+  route: "answerer:pi"
+  model: commandcode/deepseek/deepseek-v4.1-flash
+  independence: agent
+  author: claude (model claude-haiku-5-5)
+  judged[1]{path,verdict,reason,seen,cached}:
+    20261025T033042Z-ca783630-43267e.terminal.txt,pass,The output shows running greet.mjs with Umer and printing Hello Umer.,"I read the single capture entry. The command line \"$ node greet.mjs Umer\" runs greet.mjs with Umer, and the following output line \"Hello Umer\" matches the outcome exactly, with no error or contradiction.",false
+  note: "PNG and JPEG screens and text captures (logs, JSON, CLI output) are judged; video and other files are not"
+
+$ done-done receipt --outcome "running greet.mjs with Umer prints Hello Umer" "$evidence"
+command: receipt
+result: pass
+head: ca783630026370864950bce53bc5efab802d29d6
+tree: 3dff6448314deb0fe0325786bc9a7c2369366be6
+claim: running greet.mjs with Umer prints Hello Umer
+files: 1
+receipt: ~/.done-done/evidence/sample/.done-done/receipts/ca783630026370864950bce53bc5efab802d29d6.json
+judge:
+  route: "answerer:pi"
+  model: commandcode/deepseek/deepseek-v4.1-flash
+  independence: agent
+  author: claude (model claude-haiku-5-5)
+  judged[1]{path,verdict,reason,seen,cached}:
+    20261025T033042Z-ca783630-43267e.terminal.txt,pass,The output shows running greet.mjs with Umer and printing Hello Umer.,"I read the single capture entry. The command line \"$ node greet.mjs Umer\" runs greet.mjs with Umer, and the following output line \"Hello Umer\" matches the outcome exactly, with no error or contradiction.",true
+  note: "PNG and JPEG screens and text captures (logs, JSON, CLI output) are judged; video and other files are not"

package/docs/media/hero.mjs

@@ -0,0 +1,84 @@
+// Build the README hero pages from the captured CLI transcripts in this folder.
+// Every value shown is asserted to exist in a transcript; only field order and long paths change.
+// Usage: node docs/media/hero.mjs, then screenshot .hero/hero-desktop.html (828x596) and
+// .hero/hero-phone.html (418x792) at device scale factor 2, in light and dark:
+// hero-light.png, hero-dark.png (1600 px wide source shown at width 100%), hero-phone-*.png.
+// The animated hero.gif replays the same lines one by one (1200 px wide, 16 frames, ~9 s),
+// ending on the judge's pass and the receipt; it is captured from the same page with the
+// lines revealed a step at a time, one row's worth of pixels cropped off each earlier frame.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = dirname(fileURLToPath(import.meta.url));
+const pass = readFileSync(join(dir, 'hero-run.txt'), 'utf8');
+const refuse = readFileSync(join(dir, 'hero-refuse.txt'), 'utf8');
+const need = (hay, s) => {
+  if (!hay.includes(s)) throw new Error(`not in the captured transcript: ${s}`);
+  return s;
+};
+
+const commit = need(pass, 'ca783630026370864950bce53bc5efab802d29d6');
+const reason = need(pass, 'The output shows running greet.mjs with Umer and printing Hello Umer.');
+const model = need(pass, 'commandcode/deepseek/deepseek-v4.1-flash');
+const err = need(refuse, 'init --journey tests: npm test is code-only: a test, typecheck, lint or build run proves the code checks pass, not that the product works, so check and gate never count its run as proof; nothing was written');
+
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const L = (cls, s) => `<div class="${cls}">${esc(s)}</div>`;
+
+const body = ({ phone }) => [
+  L('cmd', '$ done-done run greet'),
+  L('out', 'result: recorded'),
+  L('out', `commit: ${commit}`),
+  L('out', 'dirty: false'),
+  L('out', 'files: 1'),
+  '',
+  L('cmd', `$ done-done check --outcome "greeting Umer prints Hello Umer" ${phone ? '…' : '…terminal.txt'}`),
+  L('ok', 'result: pass'),
+  L('out', 'judge: answerer:pi'),
+  L('out', `model: ${model}`),
+  L('ok', `reason: "${reason}"`),
+  '',
+  L('cmd', '$ done-done receipt --outcome "greeting Umer prints Hello Umer"'),
+  L('ok', 'result: pass'),
+  L('out', `receipt: receipts/${commit}.json`),
+  '<div class="rule"></div>',
+  L('cmd', "$ done-done init --journey tests -- 'npm test'"),
+  L('bad', 'result: fail'),
+  L('bad', `error: ${err}`),
+].join('\n');
+
+const page = ({ width, font, phone, title }) => `<!doctype html><meta charset="utf-8"><title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  html, body { margin: 0; background: #f6f8fa; }
+  body { font: ${font}px/1.62 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  .card { width: ${width}px; box-sizing: border-box; margin: 14px; padding: 16px 18px; border-radius: 10px;
+          background: #fff; border: 1px solid #d8dee4; color: #1f2328; }
+  .meta { font: 600 12px/1.4 ui-sans-serif, system-ui, sans-serif; letter-spacing: .01em; color: #57606a; margin-bottom: 10px; }
+  .cmd { color: #6639ba; font-weight: 600; margin-top: 10px; white-space: pre-wrap; word-break: break-word; }
+  .out { color: #1f2328; white-space: pre-wrap; word-break: break-word; }
+  .ok { color: #1a7f37; white-space: pre-wrap; word-break: break-word; }
+  .bad { color: #b42318; white-space: pre-wrap; word-break: break-word; }
+  .rule { border-top: 1px dashed #d8dee4; margin: 14px 0 2px; }
+  @media (prefers-color-scheme: dark) {
+    html, body { background: #0d1117; }
+    .card { background: #161b22; border-color: #30363d; color: #e6edf3; }
+    .meta { color: #8b949e; }
+    .cmd { color: #d2a8ff; }
+    .out { color: #e6edf3; }
+    .ok { color: #3fb950; }
+    .bad { color: #ff7b72; }
+    .rule { border-color: #30363d; }
+  }
+</style>
+<div class="card">
+<div class="meta">done-done 0.6.12 · real run on a small sample app</div>
+${body({ phone })}
+</div>`;
+
+const out = join(dir, '.hero');
+mkdirSync(out, { recursive: true });
+writeFileSync(join(out, 'hero-desktop.html'), page({ width: 800, font: 15, phone: false, title: 'done-done hero, desktop' }));
+writeFileSync(join(out, 'hero-phone.html'), page({ width: 390, font: 14, phone: true, title: 'done-done hero, phone' }));
+console.log(`wrote ${out}/hero-desktop.html and ${out}/hero-phone.html`);

package/docs/reference.md

@@ -100,6 +100,16 @@ done-done starts the coding agent you choose, and never picks one. `agent:` name
 
 Each call is a fresh, single-shot session that must answer one JSON object matching a schema. The prompt goes on stdin (claude, codex, pi, gemini, acp) or into a 0600 prompt file (opencode), never in argv. done-done can start claude (`claude -p --output-format json --json-schema <schema> --model <model> --no-session-persistence`, all tools off with `--tools ''`; tool-less calls also pass `--setting-sources ''` and run from a scratch folder, so no project settings or hooks load; read-only calls allow only `--tools Read,Grep,Glob` and pass `--setting-sources ''` and `--strict-mcp-config`, so no user settings or MCP servers load), opencode (`opencode run "Follow the attached instructions." --format json -m <provider/model> -f <prompt file>`, with the schema in the 0600 prompt file and every tool denied through `OPENCODE_PERMISSION` except on an edit step ([Drive by agent](#drive-by-agent), Scope)), pi (`pi -p --mode json --no-session --no-tools`, tools off for every read or probe call, since pi has no read-only mode that refuses outside reads, and `--model <model>` only when one is set) and gemini (`gemini -p "Follow the instructions on stdin." -o json -m <model> --approval-mode plan|auto_edit`, where `plan` is read-only for the probe and read steps and `auto_edit` is used for edit steps; `--skip-trust` is added only to the tool-less probe in its scratch folder, so repo calls keep Gemini's workspace trust gate) and codex (`codex exec --json --ephemeral [-m <model>]`, the answer being the last agent message of its JSONL events; an edit step runs in codex's `--sandbox workspace-write` with the run's evidence and scratch folders added by `--add-dir` and network on, so the drive can launch the app and talk to it, while it keeps your own codex config). Codex readers and probes run a separate `--no-daemon exec --ignore-user-config --ignore-rules --skip-git-repo-check --sandbox read-only` call, with project instructions disabled and your normal authentication untouched. Feature flags alone do not remove all tools: model metadata can force code-mode, collaboration and patch tools back on. done-done reads the CLI's public bundled catalog (`codex debug models --bundled`), writes a scratch-only copy with those capabilities removed, disables the remaining tool features and web search, and supplies it through `model_catalog_json`. A missing catalog, unsupported CLI or model not in that catalog fails with its cause; no unsafe fallback or copied login is used. `doctor --probe` now requires a real Codex answer, and `init` and maintain use the same clean reader. Native Codex image judging is not implemented; Codex image judging is available through `answerer:pi` with `openai-codex/gpt-6.1-sol` on your existing Codex login. `acp:<target>` runs `acpx --cwd <dir> --format json --json-strict --deny-all --non-interactive-permissions deny [--model <model>] <target> exec --file -`, with the prompt and schema on stdin; every tool is denied. pi has no permission gate for edit steps, so doctor adds a `tool_gate` warning row whenever pi is the agent: every pi tool runs without approval. codex's sandbox covers its shell too, so doctor adds a `tool_gate` warning row whenever codex is the agent: a drive's recipe tool can write only where the drive may (see [Drive by agent](#drive-by-agent), Scope).
 
+### Agent and judge support today
+
+Claude Code and Codex are proven live. **OpenCode is not yet proven live:** its free tier rejects done-done's tools-off calls with HTTP 403 (`opencode/deepseek-v4.1-flash-free`), so `init`, `doctor --probe` and a judged run are not proven there, and `opencode/muse-spark-1.3-contributor-free` may be absent from the installed catalog. To try OpenCode, choose a model your plan already covers from `opencode models` with `--agent opencode --model <provider/model>`; done-done never needs a new account or API spend.
+
+For a signed-in Claude Code setup, pass `--agent claude --model claude-haiku-5-5 --judge claude --judge-model claude-haiku-5-5` to `init`. For Codex, use `--agent codex --model gpt-6.1-sol` with that same judge. Codex readers and probes require a CLI with `exec --ignore-user-config` and `debug models --bundled`: they keep your login, but disable MCP, project instructions and model-provided tools; edit and drive steps keep your normal Codex config. Codex is not a judge route; a Pi judge on `openai-codex/gpt-6.1-sol` judges through your existing Codex login.
+
+`done-done --version` prints the bare version first; help headers show it too, and suffixed versions are labelled `pre-release`.
+
+Optional setup check: `done-done doctor --probe` requires a real answer from your chosen agent; it checks setup, not whether your app works.
+
 ### Add a journey from a description
 
 ```sh
@@ -388,7 +398,7 @@ done-done affected origin/main
 
 `affected [<base>]` says which journeys a change needs and whether HEAD's proof covers them. It is model-free and reads git, `.done-done.yaml` and the verify skill only.
 
-- **The change.** The files that differ from `<base>`, else from the newest receipt whose head is before HEAD (the commits since the last proof), else from the merge base with the default branch (`origin/HEAD`, `origin/main`, `origin/master`, then the local `main` or `master`, the order the [Firstmate merge gate](../README.md#use-with-firstmate-or-another-agent-fleet) uses), plus uncommitted changes to tracked files. Untracked files are not part of the change until added. A file that matches `evidence.ignore_paths`, or a committed receipt under `.done-done-receipts/` ([CI gate](#ci-gate)), needs nothing.
+- **The change.** The files that differ from `<base>`, else from the newest receipt whose head is before HEAD (the commits since the last proof), else from the merge base with the default branch (`origin/HEAD`, `origin/main`, `origin/master`, then the local `main` or `master`, the order the [Firstmate merge gate](../README.md#inside-firstmate-or-another-agent-fleet) uses), plus uncommitted changes to tracked files. Untracked files are not part of the change until added. A file that matches `evidence.ignore_paths`, or a committed receipt under `.done-done-receipts/` ([CI gate](#ci-gate)), needs nothing.
 - **The mapping.** A journey is needed when its command runs the changed file (`node journeys/e2e.mjs` runs `journeys/e2e.mjs`). A feature of the verify skill (`features/<name>.md`) is needed when its file cites the changed file: a repo path, a markdown link (read from the feature's folder), a folder written with a slash (`src/` covers every file under it) or a bare file name, which matches each tracked file of that name as `maintain` reads one; or when the feature file itself changed. The skill's `SKILL.md` and `features/README.md` are what every feature follows, so a change to them needs every feature. A needed feature brings each journey it names (`run <journey>` or `verify <journey>` in its text, or a file the journey's command runs that it cites too); a feature that names no journey is driven by your agent: `done-done verify --feature <name>`. A code-only journey ([Real-product evidence](#real-product-evidence)) is never needed.
 - **Uncertain means more, never less.** A changed file that no feature or journey covers, or no base to diff against, makes the mapping uncertain: the core journey ([Core journey and release path](#core-journey-and-release-path)) is needed too, or the feature the feature map marks `(core journey)`, or every journey when none is named. Each such file is listed under `unmapped` and flagged in `help`: add it to the feature file that drives it (`done-done maintain` reports recent files no feature covers), or record a journey for it.
 - **The proof.** `fresh` (exit 0) when the receipt for HEAD verifies ([Record a receipt](#record-a-receipt)), its `runs` include a run of every needed journey (by name, or by the journey's command) and every needed feature (a `verify --feature` drive, which the receipt records as the run's `feature`), and no tracked file has an uncommitted change. Otherwise exit 1: `stale` when the newest receipt is for an earlier commit (it names that commit and the journeys the new commits need), when the receipt for HEAD misses a needed journey or feature, or when there are uncommitted changes; `missing` when there is no receipt at all. `help` gives the commands that capture the missing proof (`done-done run <journey>`, `done-done verify --feature <name>`), then the receipt step.
@@ -785,10 +795,14 @@ judge:                                # done-done's own judge; check, receipt, v
   floor: 0.7                          # every judge's pick must reach this probability to count; below it the verdict is unsure (inconclusive), never a pass
   # env_file: ~/.config/done-done/judge.env  # KEY=value lines (a provider API key) handed to the judge for names your shell has not exported; the key stays in that file
   # account_command: account-picker pick claude --json  # optional shell command for Claude judge and agent calls (verify/maintain too), once per process; exported CLAUDE_CONFIG_DIR wins
+  # pool_command: fm-model-pool       # optional shared model pool (Firstmate account-pool/bin/fm-model-pool): the Claude account, limit moves and fall-over
+  # pool_config: ~/firstmate/config/account-pool  # the helper's own config/account-pool, absolute; needs pool_command
 ```
 
 `judge.account_command` must print one JSON object: `{"ok":true,"id":"pool-1","set":{"CLAUDE_CONFIG_DIR":"/absolute/existing/folder"},"unset":["ANTHROPIC_API_KEY"]}`. Only the selected folder is set, and each `unset` name is deleted from the spawned environment; it cannot unset `CLAUDE_CONFIG_DIR`. The detail names only the account id. A pick returning `ok: false` (or JSON `null`) is an unavailable Claude route and uses `judge.fallback_route` when configured; otherwise it stops with the same cause and no verdict. An invalid pick still stops the call. Neither case falls back to the default Claude login. Unset, it preserves normal Claude sign-in behavior; other agents and API-key routes do not run it.
 
+**Shared model pool.** Global `judge.pool_command` opts a home into a pool helper that picks the Claude account, moves on a rate/usage limit and falls over to another model route; `judge.pool_config` is the helper's own `config/account-pool`, absolute. It speaks the pool's protocol v1: done-done runs `<pool_command> pick --json` with one request JSON on stdin (`v: 1`, `purpose: work`, `pool_config`, the call's `model` and one overall deadline) and later `<pool_command> next --json` with the prior answer, `cause: rate_limit` and every account or route already `attempted`. The answer is either a Claude account (`id`, `set`, `unset`, as `judge.account_command` above) or a fall-over route (`provider` other than `claude`, `harness`, `model`). One answer per process is shared by the Claude judge, readers and drives; each call's environment gets that account's folder and its `unset` names removed, and nothing else. On a typed rate or usage limit the helper's next account or route runs that same call, once per account, inside the call's single `agent_timeout` deadline. A route the helper answers runs on the agent and model done-done has here: `route:deepseek/deepseek-goat` is `pi` at `commandcode/deepseek/deepseek-v4.1-flash`, `route:cursor/auto` is `pi` at `cursor/auto`, and any other route runs its own harness when that is an agent done-done knows. A route whose agent is not installed here is skipped and the helper is asked for the next one. Usage credits and overage are never spent: an account or route that enables them stops the call with a plain error naming it, and nothing is charged. The result's detail names the account id or the route id that answered, never a folder or a token. A pick returning `ok: false` (or JSON `null`) is an unavailable Claude route and uses `judge.fallback_route` when configured; invalid JSON or a malformed answer stops the call. Unset, plain Claude sign-in is unchanged. `judge.account_command` and `judge.pool_command` cannot both be set.
+
 An `agent_config` entry merges with the defaults field by field, so `claude: { model: claude-sonnet-5-5 }` keeps `effort: low`; the other maps merge entry by entry. `done-done doctor` shows which file set each agent setting.
 
 **Project:** `<repo>/.done-done.yaml`.
@@ -829,3 +843,23 @@ An `agent_config` entry merges with the defaults field by field, so `claude: { m
 
 Global-only keys describe the machine. Project-only keys describe the project. Setting a global-only or project-only key in the wrong file is an error (exit 2), not something silently ignored.
 
+
+## Working on done-done
+
+```sh
+npm install -g --prefix ~/.local .   # optional: links this checkout as done-done on your PATH
+npm run build:skill              # regenerate skills/done-done/SKILL.md from src/skill.ts
+npm run build:skill -- --check   # fail if the committed skill is out of date
+```
+
+To try an unreleased commit without cloning (npm 12 needs `--allow-git=all`):
+
+```sh
+npx -y --allow-git=all github:umeranjum17/done-done-axi --help
+```
+
+`dist/` is committed, so installing from GitHub needs no build step. `npm test` rebuilds it and fails while the rebuilt `dist/` differs from the commit or has files git does not track, so `git add` the new `dist/` files with your change.
+
+The first-screen terminal images (`docs/media/hero-*.png`, and the animated `hero.gif`) are real output from the published CLI, captured in a sample repo. `node docs/media/hero.mjs` rebuilds their pages from the captured transcripts beside it (`hero-run.txt`, `hero-refuse.txt`) and fails when a shown value is not in them; screenshot `.hero/hero-desktop.html` (828x596) and `.hero/hero-phone.html` (418x792) at device scale factor 2, in light and dark. The GIF replays the same lines a step at a time on that page, ending on the judge's pass and the receipt. The four lower terminal illustrations (`hero`, `run`, `pass`, `reasons`, `config`) use a stub judge, so no model runs; redraw them with `npx tsc && node docs/media/make.mjs`. The logo (`docs/logo.svg`) and the flow picture are hand-made SVGs.
+
+The demo notes app behind those pictures: start one with `node docs/media/demo.mjs <fresh-scratch-directory> 0` (the server prints its owned port), open a native run in its `app/` repo, drive the checklist in the browser, save `app.png` at 400×140 DPR 2 into the run's evidence folder, seal it and run `check` with your configured judge. Save the open result as `<scratch>/open.json` and the check result as `<scratch>/check.json`; `/proof` displays that screenshot and verdict and refuses to show a pass without a real passing result. Capture `/proof` at 400×230 DPR 2 with `chrome-devtools-axi`, keep the scratch outside the repo and stop the server afterwards.

package/docs/releasing.md

@@ -1,5 +1,5 @@
-# 0.6.12 patch release
+# 0.6.14 patch release
 
-This release shows the running version in CLI help headers, labels prereleases without changing the bare `--version` line, and clarifies the signoff posting hint.
+This release lets a home point its judge at a shared model pool: done-done picks the Claude account, moves on when one is rate or usage limited, and falls over to DeepSeek Goat or Cursor auto when every Claude account is under the floor.
 
-Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.12 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.
+Do not publish an unmerged candidate. The existing `release` workflow on main tests and publishes an unpublished package version using npm trusted publishing. After merge, confirm `npm view done-done-axi@0.6.14 version dist.integrity` and smoke-test a clean `npx` install with `done-done --version`. Do not run `npm publish` manually unless the workflow fails and the release is blocked; if so, stop and report.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "done-done-axi",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "license": "Apache-2.0",
-  "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
+  "description": "Prove your app really works: done-done drives your app the way a user does, a fresh judge checks every capture, and the proof is tied to a commit.",
   "type": "module",
   "repository": { "type": "git", "url": "git+https://github.com/umeranjum17/done-done-axi.git" },
-  "homepage": "https://github.com/umeranjum17/done-done-axi#readme",
+  "homepage": "https://umeranjum17.github.io/done-done-axi/",
   "bugs": { "url": "https://github.com/umeranjum17/done-done-axi/issues" },
-  "keywords": ["axi", "done", "proof", "evidence", "screenshot", "verification", "cli", "agent"],
+  "keywords": ["axi", "done", "proof", "evidence", "screenshot", "verification", "cli", "agent", "ai-agents", "coding-agents"],
   "bin": { "done-done-axi": "dist/cli.js", "done-done": "dist/cli.js" },
   "files": ["dist", "!dist/skill.js", "skills", "docs", "integrations"],
   "engines": { "node": ">=22.18" },

package/skills/done-done/SKILL.md

@@ -98,6 +98,8 @@ fresh session of its own, looks at each capture. `check` and `receipt` start the
 and nothing turns it off: there is no result without it. When it says no judge is set, ask the user which
 judge (and model) to use and save their answer with the command it prints; never choose one for them. When
 the judge fails, report its error to the user; never call the work proven without a judge pass.
+An optional shared model pool (`judge.pool_command` and `judge.pool_config`) picks the Claude account, moves on a rate or usage
+limit, and falls over to DeepSeek Goat or Cursor auto; results name the account or route that answered, and usage credits are never spent.
 An explicitly configured `judge.fallback_route` can judge when Claude has no eligible account, sign-in or usage left;
 `answerer:pi` with `agent_config.pi.model: openai-codex/gpt-6.1-sol` uses the existing Codex login.
 Read `done-done --help` for fallback configuration; results name the route that actually answered.