bullswarm 0.35.3 → 0.35.5

package/AGENTS.md

@@ -69,7 +69,7 @@ is the canonical reference for the CLI surface.
 - Every verb must work non-interactively (no TTY). The interactive wizard is
   a human convenience, never a requirement.
 - Version single source: package.json. Release via
-  `node bin/bullswarm.js release patch|minor|major`, then `git push` and
+  `npm run release -- patch|minor|major [--title "<headline>"]`, then `git push` and
   `git push --tags`
   — CI publishes through npm trusted publishing (OIDC), no tokens.
 
@@ -90,7 +90,8 @@ the authoring method is `skill/references/providers.md`.
 ## Releasing
 
 1. All tests green.
-2. `node bin/bullswarm.js release patch` (creates commit + tag v*).
+2. `npm run release -- patch --title "<headline>"` (dates `## Unreleased`
+   in CHANGELOG.md, bumps package.json, creates commit + tag v*).
 3. `git push && git push --tags`.
 4. GitHub Actions publishes to npm via trusted publishing; verify with
    `npm view bullswarm version`.

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # bullswarm changelog
 
+## Unreleased
+
+## 0.35.5 — model choices come from each CLI, newest version wins, setup stops pinning tiers
+
+- cli: the maintainer-only `release` verb is gone from the CLI and its help;
+  maintainers run `npm run release -- patch|minor|major`, which also dates
+  the `## Unreleased` changelog section.
+
+- package: the README screenshots and brand images (`docs/public/`) are no
+  longer shipped in the npm package; the npm page loads them from GitHub.
+
+- grok: every tier now suggests the newest Grok, and the tiers differ only by reasoning. This is an owner decision: Grok has one model line. One family now covers every plain `grok-N.M`, and the newest version wins. A fresh home suggests `grok-4.7` on all three tiers: high at the connector's `xhigh`, then `medium: grok-4.7 · high reasoning` and `low: grok-4.7 · medium reasoning`, both with the reason `one Grok line, lighter reasoning for lighter tiers`. Before, it suggested `grok-4.6` for high, `grok-4.5` for medium, and nothing for low, and it listed `grok-4.7` as unranked. A `grok-4.8` takes over every tier the day `grok models` lists it. `grok-4.7-build-fast` is the same model at twice the price, so it keeps its base model's rank but is never suggested; `strategy set-rung` still selects it. The tier-wide best pick, the Codex and Claude suggestions, and pace-based routing across pools do not change. grok-4.7 and grok-4.5 now have dated price rows from [xAI's models page](https://docs.x.ai/docs/models), and grok-4.6's row was re-checked there (all on 2026-09-23). build-fast stays unpriced: xAI's Pricing page lists its long-context rates as $6.00 / $1.50 / $18.00 per 1M tokens, which is not twice grok-4.7's. The fallback list (`knownModels`) now matches what `grok models` lists.
+
+- strategy: `generationFallback` now also covers a tier that no family serves. If a connector opts such a tier in and no exact row ranks a model for it, the tier takes the best-ranked family's newest-generation model at the declared reasoning. That stand-in is the pool's rung, and it stands at rank 0 against other pools, so it is the tier-wide pick only when no other pool serves the tier. A tier may also declare `why`, a plain reason that replaces the generated one; `provider validate` rejects an empty one.
+
+- strategy: applying recommendations no longer pins tiers. `strategy apply`, `refresh --apply`, `setup --yes --strategy`, the setup wizard, the TUI's apply key, and the daily auto-refresh now write only each pool's rungs (its model and reasoning per tier). Before, they also pinned every tier to one pool: a fresh `setup --yes --strategy` sent high, medium, and low to Codex even at 100% used, and the auto-refresh pinned them again every 24 hours, so pace-based routing never picked another plan. Now every dispatch picks its pool by spare quota, and `strategy routes` shows each tier moving between pools. `strategy.assignments` stays empty unless you pin a tier yourself. The apply JSON now reports `rungs`, `bestNow` (the tier-wide pick, for display), `unpinned`, and `keptPins`, in place of `applied`.
+
+- strategy: pins are explicit only. `strategy assign` makes one, marked `source: "user"`, and `strategy clear-assignment` removes it. Apply and the auto-refresh never remove a pin you set, and apply now keeps the pin's model on that pool's rung, so the pinned tier runs the model you named instead of the pool's recommended one.
+
+- strategy: if an earlier setup or apply pinned your tiers, the next `strategy apply` or automatic refresh removes those pins and lists them under `unpinned`. A pin is treated as written by apply when it still has the pool and model that apply recorded in the cached report. Pins you set or changed yourself stay (`keptPins`), as does any pin in a home where apply never ran. Run `bullswarm strategy show` to see which pins remain and what removes each one.
+
+- strategy: the tier suggestion reads as a suggestion, not a pin: `high: codex/gpt-6-astra (best now; routing picks by spare quota)` in `strategy show`, `best now (not pins): …` after the wizard and `setup --yes --strategy`, and `Routing now · by spare quota at each dispatch, unless pinned` in the TUI, whose route lines end in `by spare quota` or `pinned to <pool>`. A pinned tier gets its own line in `strategy show`, `pinned to <pool>/<model> by you · high dispatches go there while it is available · strategy clear-assignment high removes it`. `strategy routes` gives each route a `pin` field.
+
+- strategy: `strategy show` counts unranked models instead of listing them. It prints one line, such as `unranked: 312 models (command-code 180, opencode 130, grok 2) · never recommended · strategy show --json lists them`, and the setup review screen prints the same count for each provider. `strategy show --json` keeps the full `unranked` list, and the model pickers keep their `(unranked)` tag.
+
+- strategy: medium now falls back to the newest generation. When the family that serves a tier has no model in a pool's newest generation, a connector that opts the tier in (`generationFallback`) gives it the next-lower family's newest-generation model, at a declared reasoning level clamped to what that model supports. Codex opts medium in, and this is an owner decision, not a benchmark: 168 medium dispatches as luna at max reasoning ran 99% ok. So a fresh home suggests `medium: gpt-6-luna · max reasoning — no gpt-6 terra yet, newest generation preferred`, and medium returns to terra at the normal medium reasoning once a gpt-6 terra is discovered. High, low, and Claude are unchanged. `strategy apply`, `refresh --apply`, `setup --yes --strategy`, the wizard, and the TUI all write that level into the pool's rung, reported as `max (recommendation)`. It is never written over a level you set, and a later apply removes it when the fallback ends. `strategy show` and the setup screens say why. The cross-pool tier pick also skips a model disabled for its pool now, as each pool's own pick already did, so a tier suggestion can no longer name a model you turned off.
+
+- setup, doctor: old copies of packaged connectors in `<home>/connectors/` now follow the package. Those copies were made by installs older than 0.29.0. A copy of a pool the package defines was already ignored, so its old prices (such as Opus 5's on Opus 5.5) never applied; a contrib copy whose provider is not enabled was still used. Every verb now checks each copy against `connector-history.json`, which holds fingerprints of every value each field has shipped with. A copy with no edits moves to `connectors/retired/` so the packaged connector loads, and a contrib provider is enabled first when only the copy defined its pool. A copy you edited is kept, and `bullswarm doctor` (`connector-copies`, a `!` warning) and `strategy show` name its stale fields. The dead copy-to-home step in `setup` is gone.
+
+- strategy: connectors now declare model families (`modelFamilies`: a name pattern with a tier and base rank), and the version read from the model id orders each family. So a newly discovered model is ranked on the day it appears: gpt-6-sol and gpt-6-luna are no longer tierless, and a fresh home suggests gpt-6-luna for low instead of gpt-5.6-luna. Inside a pool and family, the newer version always wins, whatever benchmarks, prices, or pace say. Quality is compared on one scale, the rank, and benchmarks only break equal ranks. A model no rule classifies is listed as `unranked` and never recommended. Claude Code prices now follow the rate card line for each model: Opus 5.5 ($4/$20) and Fable 5.1 (cache hits $0.25) no longer inherit Opus 5's or Fable 5's price, and `provider validate` refuses a price on a family.
+
+- strategy: Claude Code and Codex model choices now come from bounded, no-prompt installed-CLI handshakes per account; Claude discovery suppresses hooks and preserves explicit 1M selectors, Codex pages `model/list` and records per-model reasoning support, and the static lists remain only as failure fallbacks.
+
+- docs: a new README with a banner, the problem, a comparison with the
+  alternatives, and dashboard screenshots taken from a made-up demo home;
+  a new playbook guide; `scripts/render-readme-shots.sh` rebuilds the
+  screenshots and refuses to write them if private terms or source IDs
+  survive.
+
+- stats: hyphenated project names keep their complete basename when the panel
+  has room instead of being reduced to the suffix after the final hyphen.
+
+- stats: charts share Home's even whole-unit ticks, zero baseline and daily
+  weekday labels, while compact money cells use the dashboard-wide source and
+  lower-bound glyphs and return the saved width to pool and project names.
+
+- mod: the Step pane follows, selects, and expands the newest turn by default,
+  refreshes an open running Step every four seconds, and ticks its projected
+  in-flight command name and elapsed time every second without refetching.
+- step: `workflow action show --json` and `workflow task show --json` now emit
+  compact Step schema v2: one activity per distinct attempt, one canonical
+  event array inside each activity, reference markers for aliases, and the
+  unchanged display projection used by the dashboard and Claude mod.
+- pools: per-home display labels (`bullswarm pools label`) now shorten pool ids
+  across human CLI output, progress, the dashboard, and the Claude Mod without
+  changing credential, routing, meter, history, or workflow-record keys. Pool
+  arguments accept either form; JSON retains `pool` and adds `poolLabel`.
+
+## 0.35.4 — one Runs table for workflows and tasks
+
+- mod: a live single task no longer replaces the selected workflow; each task
+  gets its own `task <8-char-tail>` pane button and a real dashboard Step model
+  from the read-only `workflow task show` command.
+- runs: workflow and task rows share one set of columns — status, id, project,
+  what, kind (`7/7 steps` or `task`), active time, cost and start clock — sized
+  once for the whole page, so every day section lines up; long project names
+  stop at 18 cells with `…`.
+- runs: a task says what it is about: its first Markdown heading, else a
+  labelled subject line (`Outcome:`, `Goal:`, `Task:`, `Defect:` …), else the
+  first sentence that is neither setup (`You are …`, `Workspace: …`) nor a
+  standing rule (`Edit only …`, `Do not commit.`, `Never …`).
+- runs: tasks recorded before the task ledger show their start clock, their
+  project when the cwd was recorded, and a dim `build task on codex`-style
+  description instead of a row of dashes.
+- runs: money is one cents cell: `$0.32` measured, `≈$4.01` or `~$25.87`
+  estimated, `≥$138.12` when some attempts are unpriced, and `~<$0.01` below
+  a cent; rows no longer print `API`, `summed`, `estimated`, `unmeasured` or
+  `span`. Day rules read `6 runs · 7 tasks · ≥$374.85 · 3 unpriced`, dropping
+  the money and then the unpriced count at narrow widths, never the words.
+- runs: the description shrinks first, then start, kind and project drop as
+  the terminal narrows; status, id, time and cost always stay, and no line is
+  wider than the page from 40 to 260 columns.
+- runs: the cursor bar is one even inverse band; the grey cost and clock cells
+  no longer show as darker blocks inside it.
+
 ## 0.35.3 — whole right edges in Ghostty and herdr, Enter opens the row you are on, named phases
 
 - dashboard: every row is erased before it is painted instead of after, so a
@@ -145,7 +230,7 @@
   sessions read-only; Command Code reads persisted project JSONL only when a
   session transcript exists and carries usage.
 - reprice: transcript lookup follows the loaded provider registry, so
-  `opencode2*`, `opencode2:kaihk-*`, and `command-code` pools reach their
+  `opencode2*`, `opencode2:orbit-*`, and `command-code` pools reach their
   provider-owned readers without a hard-coded provider list. Ambiguous,
   missing, and checkpoint-only records stay unknown rather than becoming
   zero-cost attempts.
@@ -153,7 +238,7 @@
   `--no-session`, so their checkpoints are documented as non-recoverable
   history.
 - pricing: public model cards are retained only with a source and date (the
-  cards were checked 2026-09-20). `kaihk/*` and `opencode/union-alpha` relay
+  cards were checked 2026-09-20). `orbit/*` and `opencode/union-alpha` relay
   identifiers have no public card, so the underlying OpenAI card is not
   substituted; observed Command Code models use the cited Command Code card.
 - evidence: live OpenCode and Command Code streams captured on 2026-09-20 are

package/README.md

@@ -1,273 +1,185 @@
-# bullswarm
+<p align="center">
+  <img src="docs/public/brand/bullswarm-banner.png" alt="Bullswarm — use every coding-agent plan you pay for" width="100%">
+</p>
 
-Bullswarm is a CLI that sends a coding task to whichever of your installed
-agent CLIs — Claude Code, Codex, Grok, OpenCode, or Command Code — currently
-has unused subscription quota, then checks the result by its content.
+<p align="center">
+  <img alt="npm version" src="https://img.shields.io/npm/v/bullswarm">
+  <img alt="MIT license" src="https://img.shields.io/npm/l/bullswarm">
+  <img alt="Node.js 22.12 or later" src="https://img.shields.io/badge/node-%3E%3D22.12-339933?logo=node.js&logoColor=white">
+</p>
 
-One command runs one task. A second command runs a graph of dependent tasks
-across those same CLIs. Every result is judged by what was actually written,
-not by whether the process exited 0.
+<p align="center">Route work across your coding-agent subscriptions, spend quota before it expires, and verify what comes back.</p>
 
-For an agent already working in a repo, the packaged `bullswarm` skill
-(`/bullswarm`, or `$bullswarm` where a skill uses that syntax) goes straight
-to `bullswarm run` or `bullswarm workflow goal`. A skill here is a short
-instruction file the agent CLI loads. There is no separate preview or
-classifier command to learn first.
+## The problem
 
-## Why it exists
+You pay for more than one coding agent: a Claude plan or two, Codex, Grok, maybe another.
 
-Subscription quota expires on a clock, whether you spend it or not, and a
-single coding agent's judgment on whether its own work is done should not be
-the only check in the loop. Bullswarm picks whichever installed agent CLI has
-the most unused quota right now, and treats every delegate's output as
-evidence to be verified — never as an authority to be trusted on its word.
+Every one of them meters you on a clock — five-hour windows, weekly caps, monthly allowances — and unused quota is simply gone when the window resets.
 
-The same problem compounds on multi-step goals: one agent planning and
-executing everything serially leaves every other installed CLI's quota idle,
-and having that same agent be the sole judge of whether the whole goal is
-done multiplies the risk instead of dividing it. Bullswarm's workflow engine
-runs a graph of dependent actions across whichever pools have quota to spare
-— a pool is one installed agent CLI, or one account of that CLI — and
-computes completion from evidence the graph itself required, not from any one
-delegate's own say-so.
+So one plan runs dry mid-task while the others sit idle. You switch tools by hand just to spend what you already paid for. And the agent that wrote the code is usually the one that decides it is done.
 
-## Install
+## What Bullswarm does
 
-```bash
-npm i -g bullswarm
-bullswarm setup
+Bullswarm turns the agent CLIs already signed in on your machine into **one fleet** that your main agent can command.
+
+```mermaid
+flowchart LR
+  you([You]) -->|goal| main["Your main agent<br/>Claude Code · Codex · Grok<br/>+ /bullswarm skill"]
+  main -->|"bullswarm run · workflow goal"| bs{{"Bullswarm<br/>pace router + workflow kernel"}}
+  bs --> c["claude -p"]
+  bs --> x["codex exec"]
+  bs --> g["grok -p"]
+  bs --> o["contributed providers"]
+  c & x & g & o -->|output| v["independent verification"]
+  v -->|"verdict + evidence"| main
 ```
 
-Later, `bullswarm update` upgrades that install to the latest published
-version in place (`bullswarm update --check` only reports). Requires Node.js
-22.12 or later. `bullswarm setup` walks through detecting your
-installed agent CLIs, showing their quota state, and writing a routing
-configuration. See
-[Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started)
-for integrating Bullswarm's skill into Codex, Claude, and Grok, and for the
-full quick-start command list.
-
-## Claude Mod (early access)
-
-`mods/bullswarm` is the same routing injected into Claude Code's own engine
-as a Claude Mod (a plugin of TypeScript function hooks, behind
-`CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`): the pool meters drawn above the
-prompt, the pools named in the model's context, Claude's general-purpose
-subagents routed to whichever pool has surplus and answered with the
-verified output, and the verdict appended to every `bullswarm run` the model
-runs. The Mod is the dashboard's read-only counterpart: its pane shows Run,
-Step, and the Usage/Pools view in the same meter colours. It does not expose
-the dashboard's Home, Runs, Budget, Stats, Fleet, or Help pages, and
-it has no edit or install action. See [mods/bullswarm/README.md](mods/bullswarm/README.md).
-
-Three ways to load it:
+- **Paces quota instead of guessing.** Each task goes to the eligible pool with the most unused quota relative to its reset clock. A pool that is furthest behind pace—or close to resetting with quota left—moves forward.
+- **Routes by the work.** The `analyze`, `build`, and `chore` lanes derive an effort tier; setup maps those tiers to provider and model choices, while `bullswarm setup --wizard` also configures reasoning depth. Or ask your agent to run the non-interactive setup.
+- **Runs one bounded task.** `bullswarm run` routes it to one agent, waits, and returns a verdict.
+- **Executes multi-phase workflows.** Your main agent authors a dependency graph; Bullswarm schedules ready, file-disjoint actions across agents in parallel, then runs integration and independent acceptance when the plan calls for them.
+- **Verifies content, not exit codes.** A delegate's output is evidence. A zero exit code is never enough by itself, and workflow completion stays separate from verified requirements.
+- **Shows the whole system live.** The terminal dashboard has Home, Runs, Run, Step, Budget, Stats, Fleet, and Help views, from portfolio-level quota and history down to individual agent turns.
+- **Reads licence meters.** Built-in readers cover Claude Code, Codex, and Grok; the provider interface extends routing, meters, models, and event streams without putting vendor quirks in the core.
+- **Lets your agent delegate.** The packaged `/bullswarm` skill teaches Claude Code, Codex, and Grok when to use a single run or a workflow.
+- **Lives inside Claude Code too.** The early-access Claude Code Mod adds Bullswarm routing, a run strip, and read-only Run, Step, and Usage panes inside Claude Code.
+- **Changes course while work is live.** Newer steering and plan-revision commands can add, amend, remove, or rerun actions; pause and resume remain explicit.
 
-```bash
-# with the CLI: links the mod under ~/.claude/skills and sets the flag in ~/.claude/settings.json
-bullswarm integrate install --agents claude --yes
+## Why not just…
 
-# from Claude Code's plugin marketplace (a copy that `claude plugin update` refreshes)
-claude plugin marketplace add Bulls-Work/bullswarm
-claude plugin install bullswarm@bullswarm
+| Approach | What you give up |
+|---|---|
+| **One agent's built-in subagents or workflows** | Everything draws on that one plan's quota, the same vendor grades its own work, and your process is tied to that vendor's feature. |
+| **An API gateway that re-exposes your subscriptions** | Turning a consumer subscription into a generic API endpoint can conflict with provider terms, and you lose each agent's own tools and harness. |
+| **Switching tools by hand** | You become the scheduler, and the quota you did not get to still expires. |
+| **Bullswarm** | Drives each vendor's own headless CLI—`claude -p`, `codex exec`, `grok -p`—the way those CLIs are meant to be scripted, with the accounts you already signed in. Work lands where quota is spare, and a different agent checks it. |
 
-# one session only, from the installed package
-CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir "$(npm root -g)/bullswarm/mods/bullswarm"
-```
+Bullswarm never proxies a subscription as an API and never collects or shares your vendor credentials.
 
-The marketplace route still needs `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`, in
-the shell or under `env` in `~/.claude/settings.json`, and the `bullswarm`
-CLI on `PATH`. Pick one route: an installed marketplace copy takes precedence
-over the skills-dir link, and Claude says so at startup.
+The controller is portable. Claude Code, Codex, Grok, or any capable caller drives the same CLI and durable workflow kernel, so your workflows are not locked into one vendor's orchestration.
 
-## Quick start
+## Why now
+
+Agent plans now come with hard weekly limits, and serious work spans hours rather than prompts. A workflow can run for one to two hours across several agents—builders in parallel, an integrator, then independent acceptance—while you keep handing new goals to your main agent.
+
+With Bullswarm routing by pace, running several goals at once no longer means worrying about wasting one plan's scarce quota: the fleet spends whichever plan is furthest behind.
+
+## See it
 
-Once setup is complete, bare `bullswarm` opens the dashboard on its Home page.
-Use `bullswarm --setup` or `bullswarm setup` to open setup again, and use
-`bullswarm workflow tui` when you want the explicit dashboard command. The
-eight pages answer different questions:
+![Bullswarm Home dashboard showing today's work, quota, spend, and recent runs](docs/public/screens/home.png)
 
-| Page | What it answers |
+*Home — today's work, budget position, trends, and recent runs in one view.*
+
+| Runs | Run |
 |---|---|
-| Home | What happened today, what is verified, what measured or labelled money/licence data exists, and what is active or recent; includes pool/model/project breakdowns. |
-| Runs | Which workflows are active or historical — one `active` block and the History day table below it — plus the product commands; the integration line and `/` filter live here, and `?` carries the agents and `run it` blocks. |
-| Run | Where one workflow is in its plan, which workers are live or next, and its ETA and budget shares. |
-| Step | What one action is doing: route, attempt, activity, verdict/failure, prompt, usage, events, output, and artifacts. |
-| Budget | Pool quota windows, measured worker-minutes versus rest, measured or `≈` money, fit, and biggest workflows. |
-| Stats | Runs, spend, worker-minutes, and verification over 7d/30d/all, by pool, model, and project. |
-| Fleet | Lane/provider model and reasoning rungs, records, meter state, and the setup edit hand-off. |
-| Help | Every key, click, layout rule, and dashboard command. |
-
-The visual-fidelity pass keeps the same real numbers while composing and
-colouring these pages like the approved prototype. At 55 columns every Home
-today tile and per-step bar, every Stats model, project and its sparkline, every
-Stats and Fleet pool row, and every run row in the Runs history table keeps one
-row per item on the phone; Budget's per-pool block (a header over `used`,
-`by bullswarm`, `room` and `so far`), Home's `budget · this week` pool (meter
-plus a reset line, as the prototype draws it) and the Runs `active` entry are
-the deliberate exceptions. At 200 columns every page composes to the frame
-rather than capping at the 120-column composition. Estimated figures still
-carry `≈` and their basis; a figure that cannot be measured is a line of words
-saying so — no page draws an empty or dotted track for missing data.
-
-Every page has a sticky header, a page tab row, and a sticky bottom nav. The
-tab row is five tabs — Home, Runs, Budget, Stats, Fleet — with Run and Step
-marking Runs, and Help shown only while it is open. The shared key table is:
-
-| Key | Does |
+| [![Bullswarm Runs dashboard showing active and historical workflows and tasks](docs/public/screens/runs.png)](docs/public/screens/runs.png) | [![Bullswarm Run page showing phases, live work, spend, and timeline](docs/public/screens/run.png)](docs/public/screens/run.png) |
+| Active and historical workflows and single tasks in one table. | Phases, live workers, costs, and the attempt timeline. |
+
+| Step | Stats |
 |---|---|
-| `r` | open Runs; the view refreshes itself, so `r` is no longer refresh |
-| `b` | open Budget; it is no longer move-out |
-| `s` | open Stats |
-| `y` | open Runs at its History table (the first day header), except that it confirms a pending stop |
-| `f` | open Fleet |
-| `h` | open Home |
-| `?` | open Help |
-| `1`–`9` | open that run from the nav |
-| `Tab` | cycle the current page's sub-tabs |
-| `Shift+Tab` | cycle workflows |
-| `p` | cycle the period on Home and Stats |
-| `Esc` / `←` | move out one page, then Home |
-| `↑`/`k`, `↓`/`j` | move one line |
-| `Enter` / `→` / `l` | open the selected run, step, tab, or action |
-| `PgUp` / `PgDn` | scroll one screen |
-| `Home` / `End` | jump to the top or bottom |
-| `ctrl+s` | copy the screen through OSC 52, falling back to `pbcopy`, `wl-copy`, or `xclip` |
-| `q` | quit the dashboard; workflows keep running |
-
-The 0.33.0 rebinding is deliberate: `r` no longer refreshes, `b` no longer
-moves out, and `Tab` no longer cycles workflows. Esc/left moves out, the view
-refreshes itself, and Shift+Tab still cycles workflows. Runs also provides `/`
-(filter), `a` (active/all), and `i` (install); Run provides `o`, `v`, and `t`,
-and Fleet provides `e` for setup. Click tabs, tiles, bars, runs, steps, dates,
-or controls, or use the wheel to scroll.
-
-Home, Runs, Budget, and Stats read a per-run rollup that every finishing
-run appends to `~/.bullswarm/history/runs.jsonl`. After upgrading, backfill
-the runs that finished before 0.33.0 once with `bullswarm workflow reindex`;
-legacy runs get a minimal record and only runs still in flight are skipped.
-
-One bounded outcome — a task with a clear finish line:
+| [![Bullswarm Step page showing agent turns, result, task, and cost](docs/public/screens/step.png)](docs/public/screens/step.png) | [![Bullswarm Stats dashboard showing usage and outcome trends](docs/public/screens/stats.png)](docs/public/screens/stats.png) |
+| The live or saved agent transcript, result, task, and cost evidence. | Workflow, spend, worker-time, and verification trends. |
+
+[![Bullswarm Budget dashboard showing licence meters, quota pace, and reset windows](docs/public/screens/budget.png)](docs/public/screens/budget.png)
+
+*Budget — spend spare quota before each weekly or monthly window resets.*
+
+<p align="center">
+  <img src="docs/public/screens/home-phone.png" alt="Bullswarm Home dashboard at phone width" width="360">
+  <img src="docs/public/screens/run-phone.png" alt="Bullswarm Run page at phone width" width="360">
+</p>
+
+*Home and Run retain their core evidence at a 55-column phone width.*
+
+## Quick start
+
+Requires Node.js 22.12 or later.
+
+```bash
+npm i -g bullswarm
+bullswarm setup
+```
+
+`setup` discovers installed agent CLIs, shows their quota state, and opens the provider/model control centre. An agent or CI process can use discovered defaults without prompts:
 
 ```bash
-bullswarm run --lane analyze --add-dir ~/some-repo --prompt "Explain the parser" --json
+bullswarm setup --yes --strategy --integrate
+bullswarm doctor
 ```
 
-`--lane analyze` tags the work as read-only analysis. The other lanes are
-`build` (edits) and `chore` (mechanical edits). This routes the prompt to
-whichever pool is eligible, dispatches it, watches it to completion, verifies
-the output, and prints one JSON verdict — nothing else runs and nothing is
-left in the background.
-
-Multi-step work, where you author the plan. The kernel — Bullswarm's own
-runtime, not an agent — validates that program and executes it:
-
-```json
-{
-  "schemaVersion": "bullswarm.workflow.program.v2",
-  "actions": [
-    { "id": "fix", "kind": "implement", "purpose": "Fix the failing tests",
-      "dependsOn": [], "ownedFiles": ["src/parser.js"], "affects": ["requirement-1"],
-      "evidenceFor": [], "prompt": "In ~/some-repo, fix the failing tests with the smallest correct change." }
-  ]
-}
+Run one bounded task:
+
+```bash
+bullswarm run --lane analyze --add-dir . \
+  --prompt "List every TODO in src with file and line number." --json
 ```
 
+Start a first workflow with an explicitly delegated planner:
+
 ```bash
-# 1. Write plan.json — the bounded action program the kernel will enforce.
-bullswarm workflow plan validate "Fix the failing tests and verify the change" \
-  --cwd ~/some-repo --program plan.json --json     # exit 0 valid, exit 2 with the issues; nothing launches
-bullswarm workflow goal "Fix the failing tests and verify the change" \
-  --cwd ~/some-repo --program plan.json             # launches, prints a short ID and observation commands, returns
+bullswarm workflow goal \
+  "Audit this repository and write a one-page summary" \
+  --cwd . --orchestrator auto --watch
 ```
 
-`workflow goal` starts a durable background run and returns immediately by
-default; add `--watch` to follow its low-noise progress in the same terminal
-instead.
-
-## How it picks a pool
-
-- Work is tagged by lane — read-only analysis, ordinary build work, or
-  mechanical chores — not assigned to a fixed pool ahead of time.
-- Among the pools that can do the work, the one furthest behind its own quota
-  pace (the most unspent surplus) wins, so quota doesn't expire unused.
-- A pool close to its rolling 5-hour usage ceiling gives way to one with
-  headroom only while another pool is actually behind its own pace — it is an
-  ordering penalty, not a cutoff. A step may run a pool all the way to 100% of
-  that window, because if the provider stops the worker at the wall the retry
-  is briefed on what it had already written.
-- A pool whose weekly or monthly subscription window is about to reset gets
-  priority for its remaining surplus, so quota doesn't run out the clock
-  unspent.
-- A pool already busy with other in-flight work yields to a quieter pool at a
-  similar pace, so a burst of parallel work spreads out instead of piling onto
-  one pool.
-- A pool that reports a usage-limit error is benched until the provider's own
-  reset time and automatically re-tried after that — never left down for good,
-  and never retried early.
-
-The full mechanics behind each of these are in
-[Routing](https://bulls-work.github.io/bullswarm/guide/routing).
-
-## What you get back
-
-`bullswarm run` prints a JSON verdict when it finishes:
-
-- `keepOnClaude: true` — the router says do this in-session; nothing ran
-- `ok: true` (and `keepOnClaude` is false) — the output passed verification;
-  read `outFile`
-- `ok: false` — `why` names the gate that failed
-- `contentUsableDespiteExit: true` — the process exited non-zero but the
-  content still verified; read it before re-running
-
-A non-zero exit from the delegate is never treated as success on its own. See
-[Result envelope](https://bulls-work.github.io/bullswarm/reference/result) for the full
-verdict shape.
-
-A workflow produces a durable, versioned result envelope — a JSON document
-with `runId` / `shortId`, status, per-requirement evidence, per-action
-outcomes, and usage — instead of leaving you to parse a transcript.
+For normal use, your main agent should author `plan.json`, validate it, and launch the exact same goal:
 
 ```bash
-bullswarm workflow watch <shortId> --next                  # wait for the next notable event, then exit
-bullswarm workflow runs result <shortId> --json --summary  # compact status once the run is terminal
+bullswarm workflow plan contract \
+  "1. Fix the parser. 2. Add independent verification." --cwd . --json
+
+bullswarm workflow plan validate \
+  "1. Fix the parser. 2. Add independent verification." \
+  --cwd . --program plan.json --json
+
+bullswarm workflow goal \
+  "1. Fix the parser. 2. Add independent verification." \
+  --cwd . --program plan.json --watch
 ```
 
-`workflow watch --next` prints one line per event and relaunches itself with
-the exact flags to keep polling; `runs result --summary` is what to read once
-a run finishes, and `runs result --json` (no `--summary`) gives the full
-envelope for a failed or partial run. See
-[Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) for the
-full shape of both.
+Open the dashboard at any time. Quitting it does not stop running workflows.
 
-## Documentation
+```bash
+bullswarm
+# explicit form:
+bullswarm workflow tui
+```
 
-The full documentation is published at
-[bulls-work.github.io/bullswarm](https://bulls-work.github.io/bullswarm/).
+## A practical playbook
 
-The dashboard is the main screen after setup: bare `bullswarm` opens Home,
-`bullswarm --setup` or `bullswarm setup` opens setup, and
-`bullswarm workflow tui` is the explicit form. The [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing)
-page maps its pages, keys, and mouse controls.
+1. **Nail down the outcome.** State what must change, what must remain untouched, and what evidence will count as done.
+2. **Hand it to your main agent.** With the `/bullswarm` skill installed, it chooses a bounded run or authors a workflow program with clear territories, dependencies, integration, and acceptance.
+3. **Let the graph fan out.** Ready, file-disjoint actions can run across Codex, Grok, Claude accounts, and contributed providers while routing spends the quota furthest behind pace.
+4. **Stay in control.** Follow the dashboard or `workflow watch`; send guidance, pause, or revise the live plan when the goal changes.
+5. **Sign off on evidence.** Read the durable result envelope and requirement evidence. `completed` and `verified` answer different questions.
 
-| Page | What it covers |
-|---|---|
-| [Introduction](https://bulls-work.github.io/bullswarm/guide/) | What Bullswarm is, the two entry points, and the four rules it never breaks |
-| [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started) | Install, `setup`, `doctor`, agent integration, and your first verified run |
-| [Concepts](https://bulls-work.github.io/bullswarm/guide/concepts) | Pools, lanes, surplus, the two windows, verdicts, quarantine, and the run directory |
-| [Run one task](https://bulls-work.github.io/bullswarm/guide/run) | Every `bullswarm run` option, and what each verdict asks you to do |
-| [Workflows](https://bulls-work.github.io/bullswarm/guide/workflows) | Authoring the program `workflow goal` executes: territories, dependencies, integration, acceptance |
-| [Observing runs](https://bulls-work.github.io/bullswarm/guide/observing) | `workflow watch`, the Home/Runs/Run/Step/Budget/Stats/Fleet/Help dashboard pages, keys, mouse, and terminal glyphs |
-| [Routing](https://bulls-work.github.io/bullswarm/guide/routing) | How a pool is picked: pace, 5-hour headroom, urgency, load, quarantine |
-| [CLI reference](https://bulls-work.github.io/bullswarm/reference/cli) | Every verb and nested subcommand, with its flags and defaults |
-| [Workflow program](https://bulls-work.github.io/bullswarm/reference/program) | The `bullswarm.workflow.program.v2` document: action fields, kinds, validation rules |
-| [Configuration](https://bulls-work.github.io/bullswarm/reference/configuration) | The Bullswarm home, `state.json`, strategy models and rungs, environment variables |
-| [Providers](https://bulls-work.github.io/bullswarm/reference/providers) | Adding your own agent CLI or reseller account as a provider plugin |
-| [Result envelope](https://bulls-work.github.io/bullswarm/reference/result) | Every field of `run --json` and of the workflow result document |
-| [Claude Code](https://bulls-work.github.io/bullswarm/integrations/claude-code) | The packaged skill, the MCP server, and the read-only Claude Mod counterpart under `mods/bullswarm` |
-| [Codex and Grok](https://bulls-work.github.io/bullswarm/integrations/agent-clis) | What `bullswarm integrate` writes for each agent CLI, and how to check it |
-| [Issue watcher](https://bulls-work.github.io/bullswarm/integrations/issue-watcher) | The launchd agent that triages and fixes new GitHub issues |
-| [Historical notes](https://bulls-work.github.io/bullswarm/notes/) | Working notes, audits, and experiment writeups, kept as records |
-
-## License
-
-MIT
+You can keep several independent goals running without manually balancing every plan. Bullswarm accounts for in-flight load, while each workflow keeps its own durable state, outputs, events, and result.
+
+## Supported agents and meters
+
+| Agent CLI | Provider status | Subscription meter declared by the shipped connector | Headless entry point |
+|---|---|---|---|
+| Claude Code | Built in | weekly + 5-hour | `claude -p` |
+| Codex | Built in | weekly | `codex exec` |
+| Grok | Built in | weekly | `grok -p` |
+| OpenCode | Contributed | none in the base connector | `opencode run --auto` |
+| Command Code | Contributed | weekly + monthly + 5-hour | `command-code -p` |
+
+Providers declare their own spawn command, meter reader, model discovery, reasoning levels, event decoding, and capabilities. See [Adding a provider](https://bulls-work.github.io/bullswarm/reference/providers).
+
+## Status
+
+Bullswarm is used daily. The maintainer's local records contained **335 workflow runs** and **507 single tasks** as of September 2026.
+
+The routing, content verification, durable workflow kernel, dashboard, and built-in providers are established parts of the project. Mid-run steering and whole-plan revision are newer; use their validation and revision guards, and inspect the resulting evidence.
+
+## Learn more
+
+- [Documentation](https://bulls-work.github.io/bullswarm/)
+- [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started)
+- [How routing works](https://bulls-work.github.io/bullswarm/guide/routing)
+- [Authoring workflows](https://bulls-work.github.io/bullswarm/guide/workflows)
+- [Observing runs and the dashboard](https://bulls-work.github.io/bullswarm/guide/observing)
+- [Provider reference](https://bulls-work.github.io/bullswarm/reference/providers)
+- Contributing: [open an issue](https://github.com/Bulls-Work/bullswarm/issues) or [submit a pull request](https://github.com/Bulls-Work/bullswarm/pulls)
+- [MIT licence](LICENSE)