catherd-cli 1.5.0 → 2.0.0-next.20261022115212

package/README.md

@@ -6,22 +6,24 @@
  (")(")
 ```
 
-Autopilot builds from your own Claude Code or native Codex session. Your profile routes the architect, verifier and workers to their backends; Codex, opencode, Cursor, Grok Build,
-Antigravity or headless Claude Code processes write the code, and [Jev](https://typesafe.ai) picks the model and effort for each piece
+Autopilot builds from your own Claude Code or native Codex session. Your profile routes the architect, verifier and workers to their backends; Codex, opencode, Cursor
+or headless Claude Code processes write the code, and [Jev](https://typesafe.ai) picks the model and effort for each piece
 of work, climbing a ladder only when a cheaper rung falls short.
 
 - **Your harness, as you set it up.** Every role runs in its vendor's own CLI with your config,
   hooks, skills and `AGENTS.md`. Isolation is an opt-in toggle per profile and harness, for when
   you'd rather save the tokens your customizations cost.
-- **Claude roles stay native on Claude Code.** `claude:` rungs require that host and run as ordinary Claude Code subagents; Codex,
-  opencode, Cursor, Grok Build, Antigravity and headless `claude-code:` rungs run through catherd's MCP server.
-- **Survives restarts.** Workers are detached processes writing straight to disk, so a dropped
-  MCP server never loses a run.
-- **Results come to you.** Roles run side by side while you keep talking. Claude Code uses its peer inbox; Codex uses queued next input through its existing native server. A busy Codex conversation processes it after the active turn. Queue acceptance and result collection are separate; `peek` shows how a run stands.
-- **A protocol the tools enforce.** Every lane is routed, every brief ends with the reply contract, and a
-  milestone lands only after a reviewer and a verifier passed it. Workers can run their own checks (network,
-  loopback, Docker, the lock dir); an owner question parks one milestone, not the run.
-- **Guard rails for autopilot.** Quota failover to a stand-in that clears the same bars, a preflight check
+- **A daemon drives the run.** `run_start` launches a detached daemon that plans, dispatches, reviews, verifies
+  and lands each milestone from the run's own `events.jsonl`. Every role runs headless in its vendor's CLI
+  (Claude Code, Codex, opencode, Cursor); the session needs none of it once the run has started, and a dropped
+  session or MCP server never loses a run.
+- **Questions reach your phone.** A parked question and the final report are sent to your ntfy topic
+  (`notify.url`), and answered from the session (`answer`) or the terminal (`catherd answer`).
+- **A protocol the daemon enforces.** Every lane implements its plan tasks as written, and every role, whatever vendor runs it, gets its role's text and ends with the reply contract, and a
+  milestone lands only after a reviewer and a verifier passed it. A judge role decides what no rule can (an
+  ambiguous finding, a stuck fix round, an unmet check) from the run's facts. An owner question parks one milestone,
+  not the run.
+- **Guard rails for autopilot.** Quota failover to an indexed stand-in at least as intelligent, a preflight check
   before any worker starts, per-repo knowledge carried between runs, and a run budget.
 
 ## Requirements
@@ -35,25 +37,20 @@ of work, climbing a ladder only when a cheaper rung falls short.
   - Claude Code's `claude` CLI 2.1.282 or newer, for headless `claude-code:` rungs
   - Cursor's CLI, `cursor-agent` 2026.09.28 or newer: `curl https://cursor.com/install -fsS | bash`, then
     `cursor-agent login` (below)
-  - Grok Build's `grok` 1.0.44 or newer: `curl -fsSL https://x.ai/cli/install.sh | bash`, then `grok login`
-    (below)
-  - Google's Antigravity CLI, `agy` 1.2.13 or newer: `brew install --cask antigravity-cli`, or
-    `curl -fsSL https://antigravity.google/cli/install.sh | bash` (with `~/.local/bin` on PATH), then run `agy` once
-    to sign in (below)
 - Optional: a TypeSafe API key for Jev, in `TYPESAFE_API_KEY` or saved by `catherd init`
-- Optional: a free [Artificial Analysis](https://artificialanalysis.ai) API key for more scores, in
-  `ARTIFICIAL_ANALYSIS_API_KEY` or saved by `catherd init`; its numbers are read for you alone and never shipped
+- Optional: [gitleaks](https://github.com/gitleaks/gitleaks) (`brew install gitleaks`): catherd's milestone check
+  scans the commits of a milestone with it for a leaked secret; without it the scan is skipped and the record says so
 
 `catherd doctor` checks each backend's version and login and prints the fix for anything missing. The default
 profile runs its workers on Codex; without Codex, doctor's fix also names how to move those roles to a backend
-you have (`/catherd-setup`, or `catherd profile set roles.<role>.rungs <rung> --host <codex|claude-code>`). Codex-only setup does not require or configure Claude; enabled selected roles and reachable failover decide optional dependencies. Doctor sends nothing by default; `--test-push` is an explicit smoke send from a validated host session (`--thread <uuid>` names the Codex thread from a shell; inside a session, the `test_push` tool does the same).
+you have (`/catherd-setup`, or `catherd profile set roles.<role>.rungs <rung> --host <codex|claude-code>`). Codex-only setup does not require or configure Claude; enabled selected roles and reachable failover decide optional dependencies. Doctor sends nothing by default; `--test-push` is an explicit smoke send from a validated host session (`--thread <uuid>` names the Codex thread from a shell).
 
 ### Cursor
 
 A Cursor rung names Cursor's own model slug, with the effort as the slug's suffix: `cursor:gpt-6-sol#xhigh` runs
-`gpt-6-sol-xhigh`, and `#default` runs the bare slug (`cursor:composer-2.5#default`). `cursor-agent models` lists
+`gpt-6-sol-xhigh`, and `#default` runs the bare slug of a model whose index entry has no effort. `cursor-agent models` lists
 what your account offers; `catherd catalog refresh` reads it. No profile uses Cursor until you put a rung on it.
-Its Composer and Grok models bill from Cursor's own pool, the other models at API rates after your plan's included
+Its own models (Composer, Grok) bill from Cursor's own pool, the other models at API rates after your plan's included
 usage, so a Cursor rung ranks as `metered`.
 
 - **Native** (the default) runs with your login and your Cursor setup. It also loads your Claude Code hooks,
@@ -65,55 +62,14 @@ usage, so a Cursor rung ranks as `metered`.
   move to another home. catherd runs Cursor under its own HOME with its own `sandbox.json`, which gives a worker
   catherd's writable roots.
 
-### Grok Build
-
-A Grok rung names grok's model and effort: `grok:grok-4.6#high` runs `grok -m grok-4.6 --effort high`, and
-`#default` passes no effort. `grok models` lists your models but no efforts, so catherd offers Grok Build's `low`
-to `xhigh`; `catherd catalog refresh` reads the list. No profile uses grok until you put a rung on it. A Grok login
-(SuperGrok, X Premium+) bills your subscription and `XAI_API_KEY` bills per token: `catherd doctor` says when a
-profile's `billing.grok` differs from your login. On a usage limit, a Grok rung fails over to the same model on
-Cursor, and a Cursor Grok rung to grok, unless the profile names another stand-in.
-
-- **Native** (the default) runs with your login and your grok setup. It also loads your Claude Code plugins,
-  agents, skills, hooks and permission rules, and your Cursor rules and MCP. `workspace-write` runs in grok's
-  sandbox under catherd's own profile, `catherd-ws`, which lets a worker write the lock dir, temp and the
-  toolchain caches: catherd adds its marked `[profiles.catherd-*]` tables to `~/.grok/sandbox.toml` and leaves the
-  rest of that file alone. `read-only` runs grok's kernel `read-only` profile. On a Mac whose
-  `/var/run/docker.sock` is a link (Docker Desktop, OrbStack, Colima) grok refuses that profile, so catherd gives
-  the role only the read tools instead (`advisory`); `catherd doctor` says which applies. On macOS no grok profile
-  controls the network.
-- **Isolated** (`catherd profile set harness.grok.isolated true`) needs `XAI_API_KEY`: catherd never copies your
-  grok login, whose refresh token rotates. catherd runs grok under its own HOME with its own `sandbox.toml`.
-
-grok keeps a session on the access it started with, so catherd refuses to resume one under another access.
-
-### Antigravity
-
-An Antigravity rung names the model `agy models` lists, without an effort suffix; the effort is agy's `--effort`
-(`low`, `medium`, `high` or `max`), and `#default` passes none: `antigravity:gemini-3.8-flash#low`. No profile uses
-Antigravity until you put a rung on it. catherd never runs `agy -p` while agy is signed out, since agy would open a
-browser and wait; `catherd doctor` says so, with the fix. A sign-in check that passed is kept for 10 minutes, so
-after you sign agy out, restart the catherd MCP server (or wait those minutes) before the next Antigravity dispatch.
-A Google login draws on your plan's quota (doctor shows
-what is left); `GEMINI_API_KEY` bills the Gemini API project. Gemini rungs fail over between Antigravity and Cursor
-when either runs out, unless your profile names another stand-in.
-
-- **Native** (the default) runs with your Google login and your `~/.gemini` settings, which the Antigravity desktop
-  app shares and catherd never edits. `workspace-write` runs shell commands in agy's sandbox, which reaches the
-  workspace, temp and build caches but no network unless your own `read_url` rules grant it; the file tools are not
-  confined (`advisory`). agy has no read-only mode, so a read-only role (the reviewer, the architect) cannot run on
-  native Antigravity: `profile validate` refuses it.
-- **Isolated** (`catherd profile set harness.antigravity.isolated true`) needs `GEMINI_API_KEY`. catherd runs agy
-  under its own HOME, with its own settings: the Gemini API as the provider, write and command deny rules for
-  read-only roles, and catherd's writable roots and the network for `workspace-write`.
-
-Whether Google's plan terms allow an orchestrator to drive `agy` on a consumer plan is not settled here. The API-key
-route is the one meant for automation; check the terms before you rely on a plan login.
-
 ## Install
 
 catherd runs from Claude Code or, since 1.4, from native Codex; one global `catherd` and one plugin version serve both. To check a packaged build before you rely on it, follow the [local packaged acceptance procedure](docs/dev/live-verification.md#14-native-codex-packaging-and-completion-acceptance); a matching version alone does not prove that the feature core ran.
 
+Channels: `catherd-cli@latest` is the stable release. `catherd-cli@next` and the `plugin-next` marketplace carry
+every merge to `main` before it is stable (CONTRIBUTING.md, "Next channel"). `catherd-cli@1` is the 1.x line, which receives
+bug fixes only (CONTRIBUTING.md, "Maintenance line (1.x)").
+
 ### Claude Code
 
 ```sh
@@ -124,13 +80,12 @@ catherd init --host claude-code
 The npm package is `catherd-cli`; the command it installs is `catherd`. `bunx catherd-cli init --host claude-code`
 works too (a terminal with no host evidence cannot pick the architect/verifier defaults, so name the host): `init`
 installs the global command at its own version (`--no-global` skips it) and says `installing catherd…` before
-it does, though the first `bunx` resolve itself prints nothing for up to half a minute: bunx fetches about a
-hundred packages before catherd's first line, TypeScript among them (a peer dependency of OpenTUI's native
-layer, which Bun installs), so `bun add -g catherd-cli` first is the quicker start. `init` asks for the
-optional Jev key and the optional Artificial Analysis key, syncs the public model sources, writes the default
+it does, though the first `bunx` resolve itself prints nothing for up to half a minute: bunx fetches the
+package before catherd's first line, so `bun add -g catherd-cli` first is the quicker start. `init` asks for the
+optional Jev key, fetches the Slopalytics index, writes the default
 profile and links its Claude agents, lists your backends' models, and ends with a readiness report (`--no-input`
 asks nothing and keeps what exists; `--profile <name>` sets up and activates that profile instead of `default`;
-piped, it reads one answer per line once stdin closes: the Jev key, the Artificial Analysis key, the profile,
+piped, it reads one answer per line once stdin closes: the Jev key, the profile,
 whether to replace it, each on its own line even when a question is skipped). Then add the plugin to
 Claude Code:
 
@@ -161,11 +116,27 @@ Pass the actual project `repo` to repository-aware MCP profile/setup/catalog cal
 In either supported host, use the installed shared skills through that host's skill invocation and tool discovery:
 
 - `/catherd <task>` runs a task on autopilot; `/catherd` alone resumes the latest run. While it runs, keep
-  talking: completion arrives through the host's transport, and "how is it going?" gets a `peek`.
+  talking: a report arrives through the host's transport and on your phone, and "how is it going?" gets a `status`.
 - `/catherd-setup` tunes your profile in conversation: which models and efforts each role may
   use, cost or speed, isolation, budget and failover.
 
-`route` chooses the backend for every role. Native `claude:` uses Claude Code's `Agent` and `record_agent_run` only on Claude Code; process backends, including Codex architect/verifier, use `dispatch` followed by `result`. Omitted Codex architect/verifier choices are exactly `codex:gpt-6.1-sol#high` / `codex:gpt-6.1-sol#low`; omitted Claude choices retain their existing native defaults. Verify that exact model ID against native catalog discovery and validation; if spelling differs, resolve the mismatch explicitly with the owner, never silently normalize or substitute, and retain high/low efforts. Explicit ladders and materialized profiles are preserved, without silently converting `claude:` to `claude-code:`. To opt into host defaults, review and save the narrow reset:
+A session sees six tools:
+
+| Tool                                            | What it does                                                                                 |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `run_start(repo, title, a_lines, plan?, base?)` | Starts a run and returns its id and the notify url its questions go to                       |
+| `status(run?)`                                  | Phase, milestones, live roles, parked questions, quota holds and whether the daemon is alive |
+| `answer(run, unit, answer)`                     | Answers a parked unit (the run, a milestone or a lane); it runs again with the answer        |
+| `cancel(run)`                                   | Stops the run and every live role                                                            |
+| `result(run, name?)`                            | The run's report (the merge request body), or one role's record                              |
+| `profile(action, …)`                            | Reads, validates or changes a profile, or sets `notify_url`                                  |
+
+Set where questions go once: `notify.url` is an [ntfy](https://ntfy.sh) topic url (`catherd-setup`, or the `profile`
+tool's `notify_url`). The daemon sends to it from your machine, so a question and the final report reach the phone
+with no session open. If `notify.url` is unset, `run_start` makes a random, unlisted topic on the public ntfy.sh and
+sends questions there; set `notify.url` to your own ntfy server for privacy. Omitted Codex architect/verifier choices are exactly `codex:gpt-6.1-sol#high` /
+`codex:gpt-6.1-sol#low`; omitted Claude choices retain their existing defaults, and a `claude:` rung runs as its
+headless `claude-code:` twin. To opt into host defaults, review and save the narrow reset:
 
 ```sh
 catherd profile reset-host-defaults <profile> --host codex --preview --json > /tmp/catherd-host-defaults-review.json
@@ -175,79 +146,92 @@ catherd profile reset-host-defaults <profile> --host codex --expect /tmp/catherd
 
 It removes only architect/verifier `rungs` and `defaultRung`; every other setting stays intact. Run profile CLI commands from the project directory and choose the actual profile name. Use `--host claude-code` for Claude defaults.
 
-Completion never uses `await_results` or model polling. Codex sends through `codex queue --remote unix://` to the validated original thread: idle wake and ordered busy follow-up are the native semantics, without Claude's urgent tool-round priority. A receipt proves queue acceptance, not observed generation or collection; unloaded/interrupted hosts may retain input. Only `result` collects the actual stored record. Explicit `peek(run)` adopts the run for the current host/session; `status` and `result` do not. Unknown/conflicting identity never owns or pushes.
-
-When a role ends, its own supervisor also queues the notice to a Codex owner's thread, under the same receipt as the server's push, so a thread whose MCP server Codex has stopped still hears, and nothing arrives twice. Run a Codex coordinator inside `tmux` (or `screen`): Codex stops a thread's MCP servers once no client is attached, and the queued input waits for the next attach. Every catherd message names the role's `thread:`; resume it with `dispatch(…, thread: "latest")` under the same name.
-
-Roles get catherd's tools too. Headless Codex and Claude Code roles get a `catherd_role` MCP server, isolated or not, without any change to your config; roles on other backends run `catherd run-file read|write <run> <path>` and `catherd gate check|pass <run> …` from their shell, bound to their own run and to their role's tools: every role may read run files, only the architect and researcher write them, and only the verifier runs `gate check|pass` (anything else is `E_ROLE_SCOPE`). The coordinator tools (`dispatch`, `result`, `land`, `climb`, `peek` of another role, `run_start`, `park`, `answer`, `cancel`, `set_next`, `profile_set`, `test_push`, `run_pin`, `lane_set`, `owns_add`, `record_agent_run` and the workspace writers) are the orchestrator's: a role's process gets `E_ROLE_SCOPE` for them, so a role can never take the run over.
-
-Recover unread work with `peek` and `result`. Accepted or ambiguous attempts are not automatically resent. When ambiguity needs a deliberate retry, run from the current owner's validated host session:
-
-```sh
-catherd runs retry-push <run> <name> --event '<exact event ID from peek/status>' --acknowledge-possible-duplicate
-```
-
-This acknowledges possible duplicate native input; an accepted receipt still suppresses a repeat for that owner/event. Without a supported history reconciliation API, retain ambiguity until an explicit decision. Notices preserve all event IDs, including coalesced events; repeated input means idempotent reads, never another dispatch or landing. Stored records and independent reviewer/verifier gates are authoritative. Profile notification moments use an available host facility, without inventing a Codex notification tool or scheduled wake.
+A run's reports reach the session that started it (Claude Code's peer inbox, Codex's queued next input) and the phone.
+`status` revives a daemon that died, so asking "how is it going?" is always safe. Roles get catherd's tools too:
+headless Codex and Claude Code roles get a `catherd_role` MCP server, and other roles run
+`catherd run-file read|write <run> <path>` and `catherd gate check|pass <run> …` from their shell, bound to their own
+run and role (anything else is `E_ROLE_SCOPE`). `run_start`, `answer`, `cancel`, `result` and `profile` are the owner's: a role's process gets
+`E_ROLE_SCOPE` for them, so a role can never take the run over.
 
 In a terminal:
 
-| Command                                                                                                                                                                | What it does                                                                                                                                           |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `catherd`                                                                                                                                                              | The dashboard: Status, Profiles and Runs (below)                                                                                                       |
-| `catherd init [--host codex\|claude-code\|auto] [--no-input] [--no-global] [--profile <p>]`                                                                            | First-run setup; installs the global `catherd` at its own version unless `--no-global`                                                                 |
-| `catherd doctor [--host codex\|claude-code\|auto] [--test-push [--thread <uuid>]] [--docker] [--json]`                                                                 | Readiness and capability report; no send unless explicit smoke; `--docker` probes a compose network and the Docker disk; exits 3 when not ready        |
-| `catherd profile list\|show\|use [--repo]\|new [--from <p>]\|copy\|rm\|diff\|validate`                                                                                 | Profiles; `use --repo` binds one to the repo you are in                                                                                                |
-| `catherd profile use --repo --clear`                                                                                                                                   | Unbinds the repo you are in; it runs on the active profile again                                                                                       |
-| `catherd profile set <path> <value> [--profile <p>]`                                                                                                                   | One field, e.g. `roles.verifier.access read-only`, `roles.worker.network false`, `budget.usd 20`                                                       |
-| `catherd status [run]`, `catherd watch [--once] [--interval <s>]`                                                                                                      | Where runs stand, grouped by host and session; read-only ownership                                                                                     |
-| `catherd runs list [--repo <path>]\|show <id> [--debug [--name <n>]]\|cancel <id> <name>`                                                                              | Past runs, by session; `--debug` adds exit.json and the stderr and event tails, `--name` one role's                                                    |
-| `catherd runs clean [<id>]`                                                                                                                                            | Removes the roles' scratch folders (each role's `$TMPDIR`) of runs with no live role                                                                   |
-| `catherd catalog refresh\|list [--backend <b>] [--role <r>] [--text <t>] [--scored]`                                                                                   | The models catherd can place, filtered                                                                                                                 |
-| `catherd catalog sync [--force] [--unmatched]`                                                                                                                         | Fetches the public model facts and scores now (below); `--unmatched` lists ids no model matched                                                        |
-| `catherd catalog treat-like <rung> <like>`                                                                                                                             | Scores an unscored rung as a scored one                                                                                                                |
-| `catherd catalog treat-like --suggest <rung>\|--clear <rung>\|--reset`                                                                                                 | The three nearest stand-ins for a rung; removes one or every mapping of yours                                                                          |
-| `catherd knowledge show\|add "<line>"\|path [--repo <path>]`                                                                                                           | The repo's knowledge.md, keyed by its git origin (its toplevel when it has none), which new runs read; `add` appends a fact of yours, marked "by hand" |
-| `catherd knowledge env set NAME=value\|NAME --from VAR`, `env rm NAME`, `env list`                                                                                     | The repo's gate environment, which the verifier and preflight run with; a secret by reference only                                                     |
-| `catherd runs supersede <id> --by <id>`, `catherd runs pin <id>`                                                                                                       | Closes a run with a pointer to the one that took over; re-pins a run to the repo's profile now                                                         |
-| `catherd pause --machine\|--workspace <id> "<reason>"`, `catherd resume --machine\|--workspace <id>`                                                                   | Pauses every run on the machine (or in a workspace) on one blocker; dispatch is refused until resume                                                   |
-| `catherd lock [--slots N] [--role verifier [--run <id>]] -- <cmd>`                                                                                                     | Runs a heavy command behind the machine-wide semaphore, in its own session (no /dev/tty); `--role verifier` keeps two runs' verifiers apart            |
-| `catherd run-file read\|write <run> <path>`                                                                                                                            | A run's plan, lanes and notes (`write` reads stdin); in a role, its own run only                                                                       |
-| `catherd gate check <run> [--item <i> --command <c> --paths <p,…>] [--milestone <M>]`, `catherd gate pass <run> --item <i> --command <c> --paths <p,…> --evidence <e>` | A verifier's gate evidence, as `gate_check`/`gate_pass`; in a role, its own run only                                                                   |
-| `catherd mcp`                                                                                                                                                          | The MCP server on stdio; the plugin starts it, you never need to                                                                                       |
-| `catherd capture-fixtures [--backend <b>] [--out <dir>]`                                                                                                               | Contributors: records sanitized test fixtures from real runs (see CONTRIBUTING.md)                                                                     |
+| Command                                                                                                                                                                | What it does                                                                                                                                                                                                                                                                |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `catherd`, `catherd panel [--port <n>] [--no-open]`                                                                                                                    | The panel in your browser on 127.0.0.1: Setup, Runs and Questions; a fresh token each start; `catherd --help` for the commands                                                                                                                                              |
+| `catherd init [--host codex\|claude-code\|auto] [--no-input] [--no-global] [--profile <p>]`                                                                            | First-run setup; installs the global `catherd` at its own version unless `--no-global`                                                                                                                                                                                      |
+| `catherd doctor [--host codex\|claude-code\|auto] [--test-push [--thread <uuid>]] [--docker] [--json]`                                                                 | Readiness and capability report; no send unless explicit smoke; `--docker` probes a compose network and the Docker disk; exits 3 when not ready                                                                                                                             |
+| `catherd profile list\|show\|use [--repo]\|new [--from <p>]\|copy\|rm\|diff\|validate`                                                                                 | Profiles; `use --repo` binds one to the repo you are in                                                                                                                                                                                                                     |
+| `catherd profile use --repo --clear`                                                                                                                                   | Unbinds the repo you are in; it runs on the active profile again                                                                                                                                                                                                            |
+| `catherd profile set <path> <value> [--profile <p>]`                                                                                                                   | One field, e.g. `roles.verifier.access read-only`, `roles.worker.network false`, `budget.usd 20`                                                                                                                                                                            |
+| `catherd status [run]`, `catherd watch [--once] [--interval <s>]`                                                                                                      | Where runs stand, grouped by host and session; read-only ownership                                                                                                                                                                                                          |
+| `catherd runs list [--repo <path>]\|show <id> [--debug [--name <n>]]\|cancel <id> <name>`                                                                              | Past runs, by session; `--debug` adds exit.json and the stderr and event tails, `--name` one role's                                                                                                                                                                         |
+| `catherd runs clean [<id>]`                                                                                                                                            | Removes the roles' scratch folders (each role's `$TMPDIR`) of runs with no live role                                                                                                                                                                                        |
+| `catherd catalog refresh\|list [--backend <b>] [--role <r>] [--text <t>]`                                                                                              | The models catherd can place, with their indexed pairs                                                                                                                                                                                                                      |
+| `catherd catalog sync [--force]`                                                                                                                                       | Fetches the Slopalytics index now (below); it is refreshed at most hourly otherwise                                                                                                                                                                                         |
+| `catherd knowledge show [--role <role>]\|add "<line>"\|rm "<text>"\|path [--repo <path>]`                                                                              | The repo's knowledge.md, keyed by its git origin (its toplevel when it has none), which new runs read; `add` appends a fact of yours, marked "by hand"; a `[role, …]` tag after the source scopes a line to those roles' briefs; `rm` removes the one line the text matches |
+| `catherd knowledge env set NAME=value\|NAME --from VAR`, `env rm NAME`, `env list`                                                                                     | The repo's gate environment, which the verifier and preflight run with; a secret by reference only                                                                                                                                                                          |
+| `catherd runs supersede <id> --by <id>`, `catherd runs pin <id>`                                                                                                       | Closes a run with a pointer to the one that took over; re-pins a run to the repo's profile now                                                                                                                                                                              |
+| `catherd pause --machine\|--workspace <id> "<reason>"`, `catherd resume --machine\|--workspace <id>`                                                                   | Pauses every run on the machine (or in a workspace) on one blocker; dispatch is refused until resume                                                                                                                                                                        |
+| `catherd lock [--slots N] [--role verifier [--run <id>]] -- <cmd>`                                                                                                     | Runs a heavy command behind the machine-wide semaphore, in its own session (no /dev/tty); `--role verifier` keeps two runs' verifiers apart                                                                                                                                 |
+| `catherd run-file read\|write <run> <path>`                                                                                                                            | A run's plan, lanes and notes (`write` reads stdin); in a role, its own run only                                                                                                                                                                                            |
+| `catherd gate check <run> [--item <i> --command <c> --paths <p,…>] [--milestone <M>]`, `catherd gate pass <run> --item <i> --command <c> --paths <p,…> --evidence <e>` | A verifier's gate evidence, as `gate_check`/`gate_pass`; in a role, its own run only                                                                                                                                                                                        |
+| `catherd gate run <run> --milestone <M> [--command <c>] [--at <base checkout>] [--force]`                                                                              | A verifier's milestone check, run by catherd on the committed HEAD, detached: failures the base already has do not block, a new failure is rerun once, and `land` needs its record                                                                                          |
+| `catherd answer <run> <unit> <text>`                                                                                                                                   | Answers a parked unit from the terminal, as the `answer` tool does; the daemon picks it up                                                                                                                                                                                  |
+| `catherd mcp`                                                                                                                                                          | The MCP server on stdio; the plugin starts it, you never need to                                                                                                                                                                                                            |
+| `catherd capture-fixtures [--backend <b>] [--out <dir>]`                                                                                                               | Contributors: records sanitized test fixtures from real runs (see CONTRIBUTING.md)                                                                                                                                                                                          |
+| `catherd scorecard prepare <task>`, `record <dir> --label <l>`, `compare <label>`                                                                                      | Contributors: measures a catherd version on four fixed tasks against the 1.5.0 baseline (docs/dev/scorecard.md)                                                                                                                                                             |
 
 A profile command without a profile name (`show`, `set`, `diff`, `validate`), like the MCP profile tools, acts
 on the profile the repo you are in runs on: the one bound to it, else the active one. Pass `repo` explicitly to MCP tools; profile CLI commands accept `--host` for effective defaults. Run them as
 `bunx catherd-cli <command>` when catherd is not installed globally. Every read command takes `--json`; a bare `catherd runs` is `catherd runs list`. Exit codes: 0 ok, 1 error, 2 usage, 3 not ready, 130 interrupted; an error prints
 `error E_CODE: message` and a `fix:` line. `--verbose` (or `CATHERD_LOG=debug`) logs more to
-`~/.local/share/catherd/logs/`, kept for 7 days with secrets redacted. The dashboard takes `--plain` (ASCII, no colour)
-and `--reduced-motion`; `doctor` and `init` take `--plain` for ASCII glyphs too. `NO_COLOR` drops colour, never glyphs.
-
-Model facts and scores also come from public sources: models.dev, OpenRouter, LiteLLM, Arena (LMArena), Vectara's
-hallucination leaderboard and Epoch AI, plus Artificial Analysis when you give `catherd init` a free key. The MCP
-server syncs them in the background when a host session starts (each source at most every 12 hours, never
-delaying the session), `init` syncs them, and `catherd catalog sync` (or the `catalog_sync` tool) does it on demand.
-Each answer is kept in `~/.local/share/catherd/sources/`; a source that fails keeps its last good answer, and with no
-network and no sync at all catherd routes on the scores it ships. Those are the keyless sources' values, refreshed
-weekly (`catalog/ATTRIBUTION.md` credits each source); Artificial Analysis values are read with your key only and
-never shipped.
-
-A lane's kind and difficulty pick a bar: a threshold on each dimension it spans (`repo_code`, `terminal`,
-`honesty`, `agentic`, `frontend`; `steer` is shown but has no default bar), and the lane starts on the cheapest
-rung that clears them all. A rung with no value on a dimension takes its nearest stand-in's as `inferred`, and
-`profile validate` and `doctor` list it as a "stand-in to confirm": confirm or replace it with `catherd catalog
-treat-like --suggest <rung>`, then `treat-like <rung> <like>`. A ladder holds only rungs at least as strong as its
-start, and rungs of equal scores on two quotas start on the one the run has used least. `route` returns the rung,
-its ladder and a one-line why (a lane's declared `Kind:`/`Difficulty:` wins over Jev, and the why says when Jev
-disagreed, when no rung clears the bar, or when a tie decided); the run's `routes.jsonl` keeps every role's
-decision with, for the rung it picks, each threshold, the value used, its confidence and source, and catherd's own
-runs on it ("12 lanes, 2 climbed, 1 partial"), which it shows but never routes on. A bar of your own goes in `~/.config/catherd/catalog.override.json`, per dimension
-(`"bars": { "ui": { "hard": { "frontend": 1700, "honesty": null } } }`: a number sets a threshold, `null` removes
-the default's).
+`~/.local/share/catherd/logs/`, kept for 7 days with secrets redacted. `doctor` and `init` take `--plain` for ASCII glyphs. `NO_COLOR` drops colour, never glyphs.
+
+The catalog reads one source: the [Slopalytics](https://slopalyticsproxy.vercel.app) index, one `intelligence`
+number per model and effort. It is fetched hourly (the MCP server does it in the background when a host session
+starts, `init` does it, and `catherd catalog sync [--force]` does it on demand) and
+cached in `~/.local/share/catherd/slopalytics.json`; a fetch that fails keeps the last good index and `doctor`
+names the error. A model and effort the index does not list is not offered: it is absent from the catalog and
+`catherd catalog list`, and a profile that names one fails `profile validate`. `CATHERD_NO_SYNC=1` stops the automatic
+refreshes.
+
+A lane's difficulty picks a bar: a percentile of the intelligence of the shipped models' indexed pairs (copy the
+20th, build the 45th, logic the 60th, hard the 65th), and the lane starts on the cheapest rung that clears it
+(the fastest under `objective speed`). Every kind of lane is held to the same bar. A ladder holds only rungs at
+least as intelligent as its start, and rungs of equal intelligence on two quotas start on the one the run has used
+least. A failover stand-in must be indexed, on another quota and at least as intelligent as the rung it replaces.
+Routing gives the rung, its ladder and a one-line why (a lane's declared `Kind:`/`Difficulty:` wins over Jev, and
+the why says when Jev disagreed, when no rung clears the bar, or when a tie decided); the run's `routes.jsonl`
+keeps every role's decision with, for the rung it picks, its intelligence, the bar it was held to and catherd's own
+runs on it ("12 lanes, 2 climbed, 1 partial"), which it shows but never routes on. A run starts only when every
+enabled role has an indexed rung, and it keeps the index it started on: a later refresh never changes what it
+dispatches on.
+
+Jev's yes/no answers shape the difficulty it gives: a yes to an unexplained cause, a cross-service invariant or
+shared state lifts a lane to at least logic, and a yes to purely mechanical work holds it at build. A profile can
+move a bar's percentile (`catherd profile set bars.logic 55`), and so can one role (`catherd profile set
+roles.worker.bars.hard 65`), one difficulty at a time. `catherd profile set maxEffort.codex:gpt-6.1-sol xhigh` caps a
+model's effort for every route, climb and failover; the default profile ships Opus 5.5 and Sonnet 5.5 at high and
+GPT-6.1 Sol at xhigh (`null` removes one). A coding worker never runs below medium effort, whatever the objective or
+the budget. Every failover is a `failover` row in the run's `routes.jsonl`.
 
 Run data lives in `~/.local/share/catherd/`, config in `~/.config/catherd/` (both follow
 `XDG_*`).
 
+### A milestone per branch
+
+Start a run with `base` (a branch on origin, such as `main`) and each milestone becomes its own branch and git
+worktree, made from `origin/<base>` under the run's folder (`trees/<milestone>`) and set up once with the `Setup:`
+line the plan carries under its `#` title. Every role of the milestone works in that tree. Milestones whose `After:`
+milestones are merged run side by side, a new one starting only while the machine has the memory for it: it counts
+what is free (on macOS through `kern.memorystatus_level`, since `os.freemem()` reads almost nothing there), less a
+reserve, and starts one more only when a milestone's share still fits above a floor. The defaults are 2 GB of
+reserve and 3 GB per milestone and floor; set them per profile with `catherd profile set limits.memory.reserveMb
+<MB>` (or `perMilestoneMb`, `floorMb`). A landed milestone asks you to push its branch and merge its merge request;
+answer `push` and catherd pushes the branch and prints the command that opens the MR. catherd never opens an MR and
+never merges; once you answer that it is merged (or origin's base holds it), a clean worktree is removed. A run
+without `base` works in the repo, one milestone at a time.
+
 ### Coordinating several repositories
 
 A workspace can be a plain directory containing independent Git repositories. Declare its members explicitly
@@ -260,85 +244,57 @@ in `catherd.workspace.json`; catherd does not scan neighboring folders:
 }
 ```
 
-Run `catherd workspace inspect /path/to/workspace --json` to check the resolved members. Through MCP,
-`workspace_start` takes `root`, `title`, `a_lines`, and `steps`: each step has `id`, a member `repo`, `title`,
-`a_lines`, optional `depends_on` step ids, and the `milestone` that releases its dependents (default `M1`).
-A step with `release: "merge"` and a `base` ref (`origin/main`) releases them only once its landed commit is
-an ancestor of that ref (`git merge-base --is-ancestor`), checked when a dependent asks; fetch first, nothing
-is polled.
-An explicit `repos` map can replace the manifest. Only members used by the steps enter the run snapshot.
-Steps reusing one member must be ordered by dependencies. A final verification step can reuse a member
-after both parallel producer steps land; unordered steps in the same repository are refused.
-
-Write the shared interface or coordination agreement with `workspace_contract(workspace, content)` before
-starting children; the first child freezes it, and every child receives `workspace-contract.md`.
-`workspace_child_start(workspace, step)` creates a single-repo run only when its prerequisites have landed.
-Use the existing route, dispatch, verification and land workflow with that child's run id. Each member keeps
-its own profile, knowledge and repository rules; workers write within their own repository.
-
-`workspace_status(workspace)` and `catherd workspace status <id> --json` show the shared view and spending.
-The optional workspace `budget` (`minutes`, `tokens`, `usd`; no cap unless given, minutes from the first
-child) stops new admissions when aggregate observed spending reaches its cap, alongside each child's budget;
-`workspace_budget(workspace, …)` raises it. Running workers may overshoot; native subagent usage is reported
-after execution. Dependency readiness requires a recorded landing and finalized dispatches, not just a
-finished worker. Landing a step's completion milestone and dispatch admission share the parent lock; other
-milestones land freely, and a landed step admits a post-land fix. `workspace_pause(workspace, reason)` stops
-every child's admission on one blocker until `workspace_resume`. Workspaces support at most 100 repositories
-and 100 steps. A run folder without a readable `meta.json` is skipped and named in `workspace_status`; with a
-cap set, unreadable or negative usage evidence blocks admission until repaired. Stored status remains available after a checkout disappears, while child
-recovery and admission require the captured Git root. catherd never automatically commits, pushes,
-rolls back repositories or starts the next child.
+Run `catherd workspace inspect /path/to/workspace --json` to check the resolved members, and
+`catherd workspace status <id> --json` for a workspace run's children, dependencies and spending. The workspace
+tools (`workspace_start`, `workspace_child_start`, …) are not on the session in 2.0: the daemon runs single-repo
+runs, and a coordinated program is a later plan. The read-only commands, the stored runs and the `pause --workspace`
+switch stay.
 
 ### Environment variables
 
-| Variable                      | What it does                                                                                                |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `TYPESAFE_API_KEY`            | The Jev key, instead of the one `catherd init` saves                                                        |
-| `ARTIFICIAL_ANALYSIS_API_KEY` | An Artificial Analysis key for `catalog sync`, instead of the one `catherd init` saves                      |
-| `CATHERD_NO_SYNC`             | `1`: no automatic sync of the public sources (at MCP server start and in `init`); `catalog sync` still runs |
-| `CURSOR_API_KEY`              | Cursor's API key: logs `cursor-agent` in, and is what an isolated Cursor role runs on                       |
-| `XAI_API_KEY`                 | xAI's API key: logs `grok` in when no Grok login is active, and is what an isolated grok role runs on       |
-| `GEMINI_API_KEY`              | The Gemini API key an isolated Antigravity role runs on (agy reads it only with its Gemini API provider)    |
-| `CATHERD_HOME`                | Puts config and data under `$CATHERD_HOME/config` and `$CATHERD_HOME/data` instead of XDG                   |
-| `CATHERD_LOG`                 | Log level: `off`, `error`, `warn`, `info` (default) or `debug` (what `--verbose` sets)                      |
-| `CATHERD_LOCK_SLOTS`          | `catherd lock`'s slot count when `--slots` is not given (before the profile's `lock.heavy`)                 |
-| `CATHERD_REDUCED_MOTION`      | Any value: the dashboard's `--reduced-motion`                                                               |
-| `CATHERD_NO_KITTY`            | Any value: turns off the kitty keyboard protocol in the dashboard, for terminals it breaks                  |
-| `CATHERD_CLAUDE_AGENTS_DIR`   | Where catherd links its Claude agents (default: `$CLAUDE_CONFIG_DIR/agents`, else `~/.claude/agents`)       |
-| `NO_COLOR`                    | Drops colour (the dashboard's and `--help`'s; piped `--help` has none either)                               |
-
-For development only: `CATHERD_STORY=1` opens the dashboard's storybook, and `CATHERD_LIVE=1` enables the live
-tests (CONTRIBUTING.md has the rest).
-
-### The dashboard
-
-`catherd` opens three tabs: **1 Status** (every check with its fix; `y` copies the fix, `r` checks again),
-**2 Profiles** (one tree per profile: roles with their access, default rung, models and efforts, then routing,
-harness, budget, failover, timeouts and notify) and **3 Runs** (the host sessions that drove your runs, newest
-first; a session opens on its runs, their milestones and every role with its rung, status, time and last event, live
-ones first; a milestone opens on its digest (what landed, lanes and climbs, reviewer and verifier, tokens); a role
-opens on its brief, reply and record; the open screen redraws as run files change; `esc` goes back,
-`p` pauses). `catherd watch` opens it on Runs.
-
-- `ctrl+p` lists every command with its key and CLI twin; `?` lists the keys that work where you are.
-- `ctrl+x` is the leader: `ctrl+x 1`–`3` tabs, `ctrl+x n` new profile, `ctrl+x l` profiles, `ctrl+x u` and
-  `ctrl+x r` undo and redo, `ctrl+x q` quit.
-- Lists: arrows or `j`/`k`, `pgup`/`pgdn`, `home`/`g`, `end`/`G`, `/` to filter; `space` ticks, `enter`
-  changes or opens, `→`/`←` expand and collapse.
-- Edits are staged: nothing is written until `ctrl+s` shows the diff and you choose Save or Save & make active.
-  `enter` never saves.
-- Inside a repo bound to a profile, the dashboard opens on that profile, and making a profile active binds the
-  repo to it (as `catherd profile use <name> --repo`).
-- `esc` backs out one level and never quits. `q` quits, asking first if something is unsaved; `ctrl+c` quits
-  when nothing is, and pressed twice within 1.5 s discards and exits 130.
-- Deleting a profile or cancelling a live role takes `ctrl+d` twice.
-- `--plain` draws ASCII without colour, `NO_COLOR` drops the colour, `--reduced-motion` stops the spinner.
-- Rebind a key in `~/.config/catherd/config.json`: `"keybinds": { "profile.save": "ctrl+w", "app.help": "none" }`
-  (the palette shows each command by title; the ids are listed in
-  [`src/entry/tui/commands.ts`](src/entry/tui/commands.ts)).
+| Variable                    | What it does                                                                                                                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `TYPESAFE_API_KEY`          | The Jev key, instead of the one `catherd init` saves                                                                          |
+| `CATHERD_NO_SYNC`           | `1`: no automatic fetch of the Slopalytics index (at MCP server start, in `init` and at run start); `catalog sync` still runs |
+| `CURSOR_API_KEY`            | Cursor's API key: logs `cursor-agent` in, and is what an isolated Cursor role runs on                                         |
+| `CATHERD_HOME`              | Puts config and data under `$CATHERD_HOME/config` and `$CATHERD_HOME/data` instead of XDG                                     |
+| `CATHERD_LOG`               | Log level: `off`, `error`, `warn`, `info` (default) or `debug` (what `--verbose` sets)                                        |
+| `CATHERD_LOCK_SLOTS`        | `catherd lock`'s slot count when `--slots` is not given (before the profile's `lock.heavy`)                                   |
+| `CATHERD_CLAUDE_AGENTS_DIR` | Where catherd links its Claude agents (default: `$CLAUDE_CONFIG_DIR/agents`, else `~/.claude/agents`)                         |
+| `NO_COLOR`                  | Drops colour (`--help`'s; piped `--help` has none either)                                                                     |
+
+For development only: `CATHERD_LIVE=1` enables the live tests (CONTRIBUTING.md has the rest). `CATHERD_PANEL_DIST`
+points `catherd panel` at another build of the panel than the one the package ships.
+
+### The panel
+
+`catherd` (or `catherd panel`) serves the panel on `127.0.0.1` (port 4317; `--port 0` takes any free one) and opens
+your browser on it. It prints `catherd panel: http://127.0.0.1:<port>/login#token=<token>` and keeps running until
+Ctrl-C; `--no-open` prints the link without opening it. The token is new each start and travels in the link's
+fragment, so no request or log carries it; the login page reads it, clears it from the address bar and signs you
+in. A restart signs every tab out. The panel answers only to `127.0.0.1` and `localhost`, and refuses a write or a
+socket from another origin.
+
+- **Setup**: the catalog and each backend with doctor's status and fix, the profile this repo runs on with its
+  errors and warnings, and each role's rungs, picked from the indexed Slopalytics pairs and saved through the
+  profile service (other settings stay with `catherd profile set`).
+- **Runs**: every run, and for each one its milestones, live roles, parked questions, quota holds and its timeline,
+  newest first, live over the run's `events.jsonl`. **Cancel run** stops a live run; a run starts from your
+  session, never from the panel.
+- **Questions**: each parked unit with its question and an answer box; the unit runs again once you send it.
+
+`catherd watch` prints the live runs as text.
 
 ## Upgrading
 
+From 1.5: `bun add -g catherd-cli@latest && catherd doctor`, then `claude plugin marketplace update catherd && claude
+plugin update catherd@catherd` and a new session. A run started on 1.5 finishes on 1.5, so keep it installed until
+those end; new runs go through the daemon. The session has six tools (`run_start`, `status`, `answer`, `cancel`,
+`result`, `profile`), every role runs headless, and a parked question goes to `notify.url`. `catherd` opens the
+browser panel in place of the TUI. The catalog reads one source, the Slopalytics index, so a profile rung it does
+not list must be picked again (`catherd catalog list --role <role>`). Grok Build and Antigravity are gone.
+[MIGRATION.md](MIGRATION.md), "From 1.5 to 2.0", has the rest.
+
 From 1.4: `bun add -g catherd-cli@latest && catherd doctor`, update the plugin and start a new session; `doctor`
 names the Claude agent links to refresh. There is still no `wait` tool (it never shipped and is gone): end the
 turn, and on Codex run the coordinator inside `tmux`. A role calling a coordinator tool now gets `E_ROLE_SCOPE`,
@@ -369,12 +325,12 @@ Code session. The details are in [MIGRATION.md](MIGRATION.md).
 | [CHANGELOG.md](CHANGELOG.md)                                                                       | Releases                                                              |
 | [CONTRIBUTING.md](CONTRIBUTING.md)                                                                 | Development setup, the checks, commits, changesets, live tests        |
 | [SECURITY.md](SECURITY.md)                                                                         | Reporting a vulnerability; what catherd stores and how                |
+| [`docs/specs/2026-10-12-catherd-2.0-design.md`](docs/specs/2026-10-12-catherd-2.0-design.md)       | The 2.0 design (binding where it differs from the earlier ones)       |
 | [`docs/specs/2026-10-02-catherd-1.5-design.md`](docs/specs/2026-10-02-catherd-1.5-design.md)       | The 1.5 design (binding where it differs from the earlier ones)       |
 | [`docs/specs/2026-09-28-catherd-1.1-design.md`](docs/specs/2026-09-28-catherd-1.1-design.md)       | The 1.1 design (binding; builds on 1.0's)                             |
 | [`docs/specs/2026-09-25-catherd-1.0-design.md`](docs/specs/2026-09-25-catherd-1.0-design.md)       | The 1.0 design                                                        |
 | [`docs/dev/`](docs/dev/)                                                                           | Maintainer docs: live verification, manual tests, dependencies, ideas |
 | [`docs/dev/live-verification.md`](docs/dev/live-verification.md)                                   | What CI cannot run: live tests, fixture capture, the Codex sandbox    |
-| [`docs/tui-frames.md`](docs/tui-frames.md)                                                         | Every dashboard screen as text (generated, checked in CI)             |
 | [`docs/plans/`](docs/plans/), [`docs/handoff/`](docs/handoff/), [`docs/research/`](docs/research/) | How 1.0 was designed and built: plans, reviews, research              |
 | [`docs/archive/0.x/`](docs/archive/0.x/)                                                           | The 0.x design and plans, for history                                 |