bullswarm 0.35.4 → 0.35.6

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,87 @@
 # bullswarm changelog
 
+## Unreleased
+
+## 0.35.6 — set reasoning per tier and per model from the setup screen
+
+- setup: the setup screen (`bullswarm setup`, `strategy tui`) can now set
+  reasoning. Opening a provider shows each effort tier's model and reasoning
+  level with who chose it; ←/→ on a tier steps auto → the levels that CLI
+  accepts → "CLI decides", and saves it for that provider as
+  `strategy set-rung --reasoning` would. Provider names are no longer cut off,
+  and model search now starts with `/`, so typing `f` or `q` in a search no
+  longer finishes setup. `strategy inventory --json` lists each provider's
+  `reasoningLevels`.
+
+- strategy: reasoning can be set per model. When a tier has more than one
+  model on a provider, each can think at its own level:
+  `strategy set-reasoning --tier high --level max --pool claude-code --model
+  claude-fable-5-1 --yes`, `reasoning.models` in `strategy configure`, or the
+  indented model rows on the setup screen. It sits above the provider's level
+  and below `run --reasoning`; resolved levels report source
+  `strategy-model`, and each model in `strategy inventory --json` carries the
+  level it would run at.
+
+- docs: the README keeps two screenshots and a plainer tone, and its quick
+  start is now a prompt you paste into your agent; the other dashboard screens
+  moved to a new gallery page on the docs site.
+
+## 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
@@ -172,7 +254,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.
@@ -180,7 +262,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,120 @@
-# bullswarm
-
-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.
-
-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.
-
-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.
-
-## Why it exists
-
-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.
-
-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.
-
-## Install
-
-```bash
-npm i -g bullswarm
-bullswarm setup
-```
+<p align="center">
+  <img src="docs/public/brand/bullswarm-banner.jpg" alt="Bullswarm: a fleet of bull agents in tuxedos wearing Claude, OpenAI and Grok pins" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/bullswarm"><img alt="npm version" src="https://img.shields.io/npm/v/bullswarm"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/bullswarm"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js 22.12 or later" src="https://img.shields.io/badge/node-%3E%3D22.12-339933?logo=node.js&logoColor=white"></a>
+</p>
+
+<p align="center">Route work across your coding-agent subscriptions, spend quota before it expires, and verify what comes back.</p>
+
+## The problem
+
+You pay for more than one coding agent: a Claude plan or two, Codex, Grok, maybe another.
+
+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.
+
+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.
+
+## What Bullswarm does
 
-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:
-
-```bash
-# with the CLI: links the mod under ~/.claude/skills and sets the flag in ~/.claude/settings.json
-bullswarm integrate install --agents claude --yes
-
-# 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
-
-# one session only, from the installed package
-CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir "$(npm root -g)/bullswarm/mods/bullswarm"
+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
 ```
 
-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.
+- **Spends quota by pace.** Each task goes to the plan with the most spare quota for how far its window has run, so a plan that is behind, or about to reset with quota left, gets used first.
+- **Picks models for you.** Tasks come in three lanes (`analyze`, `build`, `chore`). Setup asks each CLI which models it offers and suggests the newest one for each effort level, so you don't have to update settings every time a vendor ships a model.
+- **Runs one task or a whole workflow.** `bullswarm run` sends one task to one agent and returns a verdict. For bigger goals your main agent writes a plan; Bullswarm runs the independent steps in parallel across agents, then integration and a final check by a different agent.
+- **Checks the work, not the exit code.** A delegate saying "done" isn't enough. Bullswarm reads what it actually produced, and a workflow finishing is kept separate from its requirements being verified.
+- **Shows everything live.** A terminal dashboard covers quota, history, running workflows and each agent's individual turns.
+- **Works with the agent you already use.** The `/bullswarm` skill teaches Claude Code, Codex and Grok when to delegate. There's also an early-access Claude Code Mod that shows runs and usage inside Claude Code.
+- **Lets you steer mid-run.** Add, change, remove or rerun steps while a workflow is running, or pause and resume it.
+- **Extends with providers.** Claude Code, Codex and Grok are built in. Other CLIs can be added as providers without touching the core.
 
-## Quick start
+## 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:
+![The Bullswarm Home dashboard: today's work, quota, spend and recent runs](docs/public/screens/home.png)
 
-| Page | What it answers |
-|---|---|
-| 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 |
+*Home: what's running today, how much quota each plan has left, and what you've spent.*
+
+![A workflow's Run page: phases, steps, agents and cost](docs/public/screens/run.png)
+
+*Run: one workflow's plan, which agent took each step, and what it cost.*
+
+More screens, including phone-sized ones, are in the [gallery](https://bulls-work.github.io/bullswarm/guide/gallery).
+
+## Why not just…
+
+| Approach | What you give up |
 |---|---|
-| `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:
-
-```bash
-bullswarm run --lane analyze --add-dir ~/some-repo --prompt "Explain the parser" --json
-```
+| **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. |
 
-`--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." }
-  ]
-}
-```
+Bullswarm never proxies a subscription as an API and never collects or shares your vendor credentials.
 
-```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
-```
+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.
+
+## 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.
 
-`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.
-
-```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
+## Quick start
+
+You need Node.js 22.12 or later and at least one agent CLI you're signed in to (Claude Code, Codex or Grok).
+
+The easiest way to set up is to let your agent do it. Paste this into Claude Code, Codex or Grok:
+
+```text
+Install and set up Bullswarm for me:
+1. Run `npm i -g bullswarm`.
+2. Run `bullswarm setup --yes --strategy --integrate` to find my agent CLIs,
+   pick models, and install the /bullswarm skill for each agent.
+3. Run `bullswarm doctor` and tell me which agents are ready and how much
+   quota each one has left.
+4. Read the installed /bullswarm skill so you know when to use
+   `bullswarm run` and when to write a workflow.
 ```
 
-`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.
+After that, just give your agent goals as usual. It will hand work to Bullswarm when that helps. Run `bullswarm` in a terminal to open the dashboard; closing it doesn't stop anything that's running.
 
-## Documentation
+To set things up by hand, or to choose models and reasoning yourself, see [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started).
 
-The full documentation is published at
-[bulls-work.github.io/bullswarm](https://bulls-work.github.io/bullswarm/).
+## Supported agents and meters
 
-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.
+| Agent CLI | Support | Quota windows tracked | Command it runs |
+|---|---|---|---|
+| Claude Code | Built in | weekly + 5-hour | `claude -p` |
+| Codex | Built in | weekly | `codex exec` |
+| Grok | Built in | weekly | `grok -p` |
+| OpenCode | Contributed | none | `opencode run --auto` |
+| Command Code | Contributed | weekly + monthly + 5-hour | `command-code -p` |
 
-| 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
+Each provider describes how to launch its CLI, read its quota, list its models and read its output. To add one, see [Adding a provider](https://bulls-work.github.io/bullswarm/reference/providers).
+
+## Learn more
+
+- [Documentation](https://bulls-work.github.io/bullswarm/)
+- [Getting started](https://bulls-work.github.io/bullswarm/guide/getting-started)
+- [Day-to-day playbook](https://bulls-work.github.io/bullswarm/guide/playbook)
+- [How routing works](https://bulls-work.github.io/bullswarm/guide/routing)
+- [Authoring workflows](https://bulls-work.github.io/bullswarm/guide/workflows)
+- [The dashboard](https://bulls-work.github.io/bullswarm/guide/gallery) and [observing runs](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)