amicus 1.9.0 → 2.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -5,6 +5,155 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-07-03
+
+Amicus's first major release: the **`sidecar*` shim removal** (#19). v1.x carried a full
+compatibility surface so installs and integrations from before the Amicus rebrand kept working —
+legacy env vars, CLI bin names, config/session directory fallbacks, MCP tool aliases, and deprecated
+public-API exports. v2.0.0 removes all of it in one pass; see **Migration** below for the exact old
+form → new form for every removed shim, including the one that needs a manual one-time step. Most
+installs need zero action (config/session data auto-migrated forward across v1.x; plugin-channel
+installs float to the latest version automatically). Beyond the shim removal, this release rolls up
+five phases of engine and docs work that shipped since 1.9.1: a fully deterministic council CLI
+transport (`validate`/`verdict`/presets/spend ledger), `amicus_read` paging for large content, a
+per-tool-call stall detector, per-run-nonced fold markers, atomic metadata writes throughout, POSIX
+server teardown hardening, and a full documentation overhaul (`docs/council.md`, restructured
+README, "where things live" config-dir reference).
+
+### Migration (from any sidecar*-era setup)
+
+Full removal record and rationale: [docs/SHIMS.md](docs/SHIMS.md). Per-shim remedy:
+
+| Old form (sidecar*-era) | New form / remedy |
+| --- | --- |
+| `SIDECAR_*` env vars (`SIDECAR_ENV_DIR`, `SIDECAR_IDLE_TIMEOUT*`, `SIDECAR_DEBUG_PORT`, `SIDECAR_MOCK_UPDATE`) | Rename to the `AMICUS_*` equivalent (`AMICUS_ENV_DIR`, `AMICUS_IDLE_TIMEOUT*`, `AMICUS_DEBUG_PORT`, `AMICUS_MOCK_UPDATE`). Unrenamed vars are now silently ignored — no warning, no fallback. |
+| `SIDECAR_MAX_SESSIONS` | Rename to `AMICUS_MAX_SESSIONS` — this was the last legacy-prefixed env var read anywhere in the codebase. |
+| `sidecar` / `claude-sidecar` CLI commands | Use `amicus` (or the `am` short alias). An `EEXIST` on `npm install -g amicus` naming an old `claude-sidecar`/`sidecar` file means a *stale* global install of the old upstream package, not this shim — see [docs/troubleshooting.md](docs/troubleshooting.md#install-fails-with-eexist--claude-sidecar). |
+| `~/.config/sidecar` config dir | No action for most users — every v1.x launch auto-copied `~/.config/sidecar/` into `~/.config/amicus/` once, non-destructively. Only if you skipped every v1.x release and jump straight from pre-rebrand to v2.0.0: copy `~/.config/sidecar/` to `~/.config/amicus/` by hand — `getConfigDir()` no longer reads the old location at all. |
+| `.claude/sidecar_sessions/` | Not auto-migrated (per-project). Rename to `.claude/amicus_sessions/` in any project whose history you want `amicus list`/`amicus read` to see again. |
+| `[SIDECAR_CONFIG_UPDATE]` stderr marker / `sidecar-config-hash` HTML-comment | The `sidecar` skill now instructs the canonical forms only: `[AMICUS_CONFIG_UPDATE]` / `<!-- amicus-config-hash: ... -->`. A stale `<!-- sidecar-config-hash: ... -->` comment in an old CLAUDE.md is simply no longer recognized; the next `amicus setup` alias change writes a fresh one, and the stale comment can be deleted by hand. |
+| `sidecar_*` MCP tool names / `AMICUS_LEGACY_ALIASES=1` | The tool surface is `amicus_*` only, unconditionally — `AMICUS_LEGACY_ALIASES=1` is now a no-op (regression-pinned in `tests/mcp-server-legacy-aliases.test.js`). Update any MCP client config or tooling that still calls a `sidecar_*` tool name. |
+| `startSidecar`/`listSidecars`/`resumeSidecar`/`continueSidecar`/`readSidecar` (package-root exports) | These were deprecated aliases present on npm through v1.9.1. Only `startAmicus`/`listAmicus`/`resumeAmicus`/`continueAmicus`/`readAmicus` remain exported from `amicus`'s package root — rename any import. |
+
+**Kept, not removed** (not part of this migration): the `[SIDECAR_FOLD]`/`[SIDECAR_FOLD:<nonce>]`
+wire-format token (deliberate transport continuity, unrelated to the compat shims), the `sidecar`
+chat-skill's directory name, and the one-shot legacy-`'sidecar'`-MCP-entry cleanup in
+`src/utils/legacy-mcp-migration.js` (re-scoped as a permanent healing tool for stale pre-1.8.0
+dual-registrations — it only removes a `'sidecar'` MCP entry verified identical-in-effect to the
+`'amicus'` one; a customized entry is left alone). The `mcp-self-identity` recursive-spawn guard also
+continues to recognize the old `sidecar`/`claude-sidecar` bin/server names — a defense against a
+stale PATH or MCP config causing amicus to spawn itself, not a restoration of removed behavior.
+
+**Plugin-channel installs float automatically.** If you installed Amicus via the Claude Code plugin
+channel, `.claude-plugin/plugin.json` runs `npx -y amicus@latest mcp` — you adopt v2.0.0 on your
+next MCP server start with no upgrade action required. The only thing that can still break for you:
+if your client config or tooling relies on `sidecar_*` tool names or sets
+`AMICUS_LEGACY_ALIASES=1` expecting it to do something, update it — that opt-in is now a no-op and
+the legacy tool names are gone.
+
+### Added
+- **`docs/council.md` — the council pipeline documented end-to-end**: the stage flow, the tally-input and
+  tally-record schemas field-by-field (test-locked against the real validators), verdict.json provenance,
+  presets, and a complete worked example whose every command and output was executed against the binary.
+- **"Where things live"** (docs/configuration.md): the full config-dir tree (config.json shape, catalog
+  cache + refresh-outcome fields, both ledgers, tmp files and the doctor sweep), per-client session
+  storage, log reality (stderr-only — `LOG_LEVEL` never writes a file), and honest uninstall instructions
+  covering what `npm uninstall -g` does NOT clean.
+- README now leads with the **two install channels** (npm global vs Claude Code plugin, with the
+  `npx -y amicus@latest` translation note) and surfaces **`/amicus:council`** in the quick start and
+  council sections.
+- **`amicus council validate <file>` and `amicus council verdict <tally.json>`** — thin CLI wrappers over the
+  existing findings-validation and verdict-builder internals, making the second-opinion skill's council
+  transport fully deterministic. `validate` exits 0 (ok) / 2 (validation failed) / 1 (bad args); `verdict`
+  writes atomically to `-o` (default `./verdict.json`), `--decisions` optional. The skill's Stage-1 and
+  Stage-5 instructions now invoke these commands, and the Stage-2 recipe persists the tally record to
+  `<run-folder>/tally.json` (previously it existed only on stdout — the verdict step had nothing to read).
+- **Council presets: `amicus council save/list/show <name>` + built-in `free`/`budget`/`frontier` benches.**
+  Built-ins resolve only when the name isn't in your config (your saved councils shadow them; `list` marks
+  shadowing). `free` resolves dynamically against the catalog (pinned offline fallback); `budget` and
+  `frontier` are alias-based (cheapest / most premium distinct-vendor picks) so alias drift tooling covers
+  them. `show` resolves against the cached catalog, including the dynamic free pick.
+- **Per-run cost ledger + `amicus spend`.** Every completed run (headless, interactive, fanout legs)
+  appends a best-effort JSONL row (`spend-ledger.jsonl` in the config dir); `amicus spend` rolls up total
+  and per-model cost/tokens/source-mix with `--since <N>d` windowing and `--json`, plus an OpenRouter
+  remaining-credit footer when a key is configured. Ledger appends can never fail a run.
+- **`amicus_read` paging and size caps.** Responses are capped at ~50KB (default: the TAIL of the content,
+  with a truncation notice reporting true byte counts at the start of the body); new optional `offset`,
+  `limit`, and `tail` params page through large content. Under-cap reads are byte-identical to before;
+  slicing happens before the untrusted-output fence is applied; `metadata` mode is param-exempt but
+  defensively capped.
+- **Per-tool-call stall detector in headless runs.** A wedged tool call (pending `tool_use`, no result, no
+  other progress for `AMICUS_TOOL_CALL_STALL_MS`, default 3 min) now fails fast with a distinct
+  `Tool call stalled: …` reason instead of burning the full run timeout. Fanout legs inherit automatically.
+- **`amicus doctor --fix` sweeps orphaned sessions-index tmp files** (atomic-write artifacts from killed
+  processes; only files older than 60s are removed).
+
+### Changed
+- **README restructured for audience separation**: discovery + quick start + compact command table with
+  pointers; `docs/usage.md` is now the complete CLI reference (the ~30% duplicated content has one
+  canonical home each — nothing was dropped); deep dives live under `docs/`.
+- The second-opinion skill's Stage-2 briefing prose reads cleanly again (hardening sentence moved before
+  the sentence it interrupted), and `report.md`'s contract is stated once, coherently: `report.html` is
+  the deterministic renderer default; `report.md` is the chair-synthesis document that embeds the
+  rendered Markdown as one section.
+- **The fold completion marker is now per-run nonced: `[SIDECAR_FOLD:<nonce>]`.** Model output that
+  genuinely ends with a bare `[SIDECAR_FOLD]` can no longer force premature completion — the detector
+  requires the run's own nonce (BL-7's final hardening layer). The nonce is crypto-random, threaded through
+  every mode (headless, fanout, MCP shared-server, interactive GUI), and instructed to the model in the
+  prompt; `amicus resume` re-derives it from the transcript.
+- **All session/wave metadata writes are atomic** (`writeFileAtomic` tmp+rename), retiring the torn-read
+  race class that pollers previously tolerated via missed-tick workarounds.
+
+### Fixed
+- `amicus council --help` now lists `save`/`list`/`show` (the Phase-16 usage-string omission caught by
+  a later binary-verification pass).
+- **Setup wizard Step 3 (alias editor) now consumes the same TTL-cached catalog as Step 2** (#12) — one
+  catalog load for the whole wizard instead of a separate uncached network fetch per run; the redundant
+  `fetch-models` IPC channel is removed.
+- **Stale catalog data is now labeled** (#13): a failed refresh records the attempt and reason in the cache
+  doc (never touching the good data), `amicus models` shows a stale memo when refreshing keeps failing,
+  `amicus models refresh` reports failure honestly instead of "Refreshed catalog: 0 models" (and its
+  `--json` reports the real stale `fetchedAt` instead of `null`), and the wizard shows a stale hint.
+- **The free-council picker is readable** (#27): models grouped by provider with friendly names (raw id as
+  the mono secondary line), a roomier scroll area, and a provider count — selection values remain raw model
+  ids throughout.
+- **Orphaned `opencode serve` processes on macOS/Linux.** Server teardown now SIGTERMs the Go binary
+  directly and escalates to SIGKILL after a bounded grace window on a ref'd poll (the old unref'd 2s timer
+  silently died with fast-exiting parents). Windows semantics unchanged.
+- **Aborting a wave immediately after starting it can no longer flip its status back to `running`** — the
+  wave metadata merge now honors abort-wins precedence (same rule the per-leg writer already had).
+- **`kill(pid, 0)` throwing `EPERM` now classifies a process as ALIVE** (signal denied ≠ dead) in
+  `isProcessAlive`/`checkSessionLiveness` and both MCP crash-detection probes. EPERM no longer marks
+  healthy sessions crashed.
+- **A committed successful terminal status can no longer be clobbered to `error`** by a cleanup-step
+  failure in the MCP shared-server finalize chain (the Phase-5 review's residual gap).
+- **`discoverCoworkMcps` now checks `%APPDATA%\Claude` on Windows** instead of the XDG path — Claude
+  Desktop discovery and doctor's Cowork signal were always wrong on win32.
+
+### Removed
+- **Every pre-rebrand `sidecar*` compatibility shim** — see **Migration** above for the full old-form →
+  new-form mapping. Also removed: **`sidecar_*` MCP tool aliases + the `AMICUS_LEGACY_ALIASES=1` opt-in**
+  (`src/mcp-server.js`) and the **public API `*Sidecar` aliases** (`src/index.js` `module.exports`) —
+  both covered in Migration.
+
+### Documentation
+- Full sweep of every doc describing the shims as live (README, docs/usage.md, docs/configuration.md,
+  docs/testing.md, docs/troubleshooting.md, docs/opencode-integration.md, docs/architecture.md,
+  skills/sidecar/SKILL.md, skills/second-opinion/MODEL-NOTES.md) rewritten to v2.0.0 reality.
+  `docs/SHIMS.md` re-scoped from a live shim inventory into the removal record the Migration section
+  above is built from.
+
+## [1.9.1] - 2026-07-03
+
+### Fixed
+- **`server.json`'s description now fits the MCP Registry's 100-character cap.** The registry rejected
+  v1.9.0's publish (its first-ever attempt) with HTTP 422 — the description was 199 chars against a
+  100-char limit the schema doesn't advertise. Shortened to 98 chars; the cap is pinned by
+  `tests/scripts/package-manifest.test.js` (characters and UTF-8 bytes), and `docs/DISTRIBUTION.md` §3 now
+  documents that content-level 422s are not recoverable by workflow re-run (the re-run checks out the tag)
+  — fix `server.json` on main and use the manual path or the next tag. v1.9.0 itself shipped fully to npm
+  and GitHub Releases; this patch exists to land the registry publish.
+
 ## [1.9.0] - 2026-07-03
 
 Engine pull-forwards, release-rail hardening, docs sync, and a new Council Review GitHub Action.

package/README.md

@@ -57,6 +57,13 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ## Quick start
 
+> **Two install channels — read this first.** Amicus ships two ways, and CLI commands look different in each:
+>
+> - **npm global** (`npm install -g amicus` or the install script) puts `amicus`/`am` on your `PATH`. Every `amicus <command>` example in this README works as written.
+> - **Claude Code plugin** (`/plugin install amicus@bourbondog-amicus`) does **not** put a CLI on your `PATH`. CLI calls go through `npx -y amicus@latest <command>` instead — e.g. `amicus doctor` becomes `npx -y amicus@latest doctor`. In exchange, the plugin channel gets two things npm does **not**: the slash commands `/amicus:council` and `/amicus:sidecar`. **These are plugin-channel-ONLY — npm users don't get them** and drive the same skills by saying "council review this" / talking to Claude instead.
+>
+> **Convention used throughout this README:** plugin-channel users: prefix CLI examples with `npx -y amicus@latest` (skip the bare `amicus`/`am`). Individual code blocks are not duplicated per channel — this note is the one translation you need.
+
 **Install** — pick whichever fits. Every path delivers the MCP server and both skills; the `amicus`/`am` CLI lands on your PATH with the **npm and install-script paths** (the plugin path runs the CLI on demand via `npx -y amicus@latest <command>`):
 
 **As a Claude Code plugin** — the most native path if you use Claude Code:
@@ -67,7 +74,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 /reload-plugins
 ```
 
-Claude Code registers the MCP server and both skills for you — nothing to configure. (The plugin does not put `amicus` on your PATH — CLI calls go through `npx -y amicus@latest <command>`; the standalone Electron window is npm-only; and the first council/sidecar call downloads the OpenCode engine.)
+Claude Code registers the MCP server and both skills for you — nothing to configure. It also gets you two slash commands the npm/install-script paths don't: **`/amicus:council`** (run a full council review) and **`/amicus:sidecar`** (fork a conversation to another model). (The plugin does not put `amicus` on your PATH — CLI calls go through `npx -y amicus@latest <command>`; the standalone Electron window is npm-only; and the first council/sidecar call downloads the OpenCode engine.)
 
 **With the install script** — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
 
@@ -115,6 +122,8 @@ This opens a graphical wizard:
 
 > *council review this*
 
+Plugin-channel users can also type **`/amicus:council`** directly instead of phrasing it as a request — same skill, explicit invocation.
+
 Claude prepares the material, recommends a bench of models, discloses the run shape and cost, and orchestrates the rest. You make the accept/deny calls at the end. (The `second-opinion` skill is what teaches Claude to recognize this — if nothing happens, run `amicus doctor` (or `npx -y amicus@latest doctor`). npm/install-script installs place the skill at `~/.claude/skills/second-opinion/`; plugin installs keep it inside the plugin itself — check `/plugin` in Claude Code to confirm amicus is enabled.)
 
 **Your first sidecar.** The sidecar is the lower-level path — you can invoke it by phrase through Claude too, but the CLI gives you the flags directly:
@@ -178,12 +187,14 @@ Everything you need before your first run, and what's optional.
 
 ## The Council
 
+> Trigger it by saying *"council review this"* to Claude, or, on the plugin channel, run **`/amicus:council`** directly.
+
 **Why multi-model.** Any single model — including the one running your session — has consistent blind spots. Route the *same* material through models from *different* families and the disagreements surface: missed issues, overstated confidence, claims one model alone would have waved through. The council is the structured version of that idea.
 
 **The flow, in five beats:**
 
 1. **Independent reviews.** Each council model reviews the artifact on its own (one parallel wave), producing a structured findings list — claim, severity (`blocker | major | minor | nit`), location, rationale.
-2. **Anonymized cross-review.** Claude relabels every review (Review A, B, C…) and sends the identical bundle to every model. Each model ranks the reviews and adjudicates every finding (`agree | dispute | neutral`) — *unknowingly judging its own*, so self-bias washes out. This yields a **street-cred** ranking and sorts findings into **Confirmed / Contested / Singleton** tiers.
+2. **Anonymized cross-review.** Claude relabels every review (Review A, B, C…) and sends the identical bundle to every model. Each model ranks the reviews and adjudicates every finding (`agree | dispute | neutral`) — *unknowingly judging its own*, so self-bias washes out. This yields a **street-cred** ranking and sorts findings into **Disputed / Confirmed / Contested / Singleton** tiers.
 3. **Chair verdict.** A designated **non-Claude** chair receives the de-anonymized picture — all reviews, rankings, and adjudications — and synthesizes an independent verdict. Claude presents it verbatim; Claude does not synthesize.
 4. **Tiered decisions.** Confirmed findings get one bulk accept/deny; Contested and Singleton findings are decided one at a time (accept / deny / modify).
 5. **Outputs applied.** Accepted findings are written into a reviewed copy of the source; the full run is captured in the run folder.
@@ -194,6 +205,8 @@ Everything you need before your first run, and what's optional.
 - `crossreview-matrix.md` — the adjudication grid plus the de-anonymized street-cred table.
 - `verdict.md` — the chair's synthesis.
 - `report.md` — synthesis + the full decision log + a per-call run-stats table.
+- `report.html` — the deterministic renderer output (adjudication matrix, street-cred table,
+  findings-by-tier, cost — no chair prose). This is the default artifact handed to the user.
 - For an **editable source**, the accepted edits land in `<stem>-reviewed.<ext>` next to the original.
 
 **Claude in the council** (default off): you can add Claude's own fresh review to the bundle so the bench ranks and adjudicates it — Claude is *judged* but never votes or chairs, so the verdict stays independent.
@@ -204,7 +217,7 @@ Everything you need before your first run, and what's optional.
 
 Then the council waits for your confirmation.
 
-The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**.
+The skill lives at **[`skills/second-opinion/SKILL.md`](./skills/second-opinion/SKILL.md)**; the design spec behind it is **[`skills/second-opinion/COUNCIL-DESIGN.md`](./skills/second-opinion/COUNCIL-DESIGN.md)**. For what `amicus council tally|verdict|report|stats` actually take as input and produce — field-by-field schemas, verdict.json's provenance, and a full worked example run against the real CLI — see **[docs/council.md](./docs/council.md)**.
 
 **Free council (zero-cost).** Want the cross-examination without the model spend? `amicus setup` offers a **Free OpenRouter council** mode — readline wizard option 2, and the Electron **Models** step. It detects the free `:free` models live from the catalog, lets you multi-pick (Enter takes a vendor-diverse default), and saves them as `councils.free` — a first-class `councils` config primitive seeded under collision-safe `free-*` aliases. Your `config.default` is left untouched, and all you need is an `OPENROUTER_API_KEY`.
 
@@ -216,6 +229,8 @@ amicus fanout --council free --prompt "Review this design"
 
 The `amicus_fanout` MCP tool takes the same `council` parameter, and the `second-opinion` skill reads `councils.free` automatically. A member that gets delisted is dropped with a warning — the council still runs as long as ≥2 survive. Free models are **rate-limited and quality-variable**, and some return 404 unless you enable data-sharing at [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy).
 
+**Council presets.** Save your own named member lists with `amicus council save <name> --models a,b,c` (≥2 resolvable aliases or `provider/model` IDs), then run them with `--council <name>` anywhere a council runs. `amicus council list` shows saved presets plus three built-in benches that work with no setup at all — `free` (the same zero-cost dynamic pick described above, used when you haven't seeded `councils.free`), `budget` (cheap workhorses, one per vendor family), and `frontier` (premium flagships, one per vendor family). `amicus council show <name>` resolves any of them (saved or built-in) and reports which members are currently usable. A saved council always shadows a built-in of the same name — exactly how the wizard's `councils.free` seeding already worked.
+
 ---
 
 ## The parallel window
@@ -266,8 +281,9 @@ amicus update
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
 | `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
+| `amicus spend` | Cross-run cost rollup from the spend ledger — total + per-model spend, tokens, and source mix, most-expensive first (`--since 7d` windows it; `--json` for a versioned doc; shows remaining OpenRouter credit when a key is configured). |
 | `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
-| `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`. |
+| `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`, `validate <file>` (findings-block check, exit 0/2/1), `verdict <tally.json> [--decisions <d.json>] [-o <out.json>]` (build + write verdict.json). Presets: `save <name> --models a,b,c`, `list [--json]`, `show <name> [--json]` — see [The Council](#the-council) for the built-in `free`/`budget`/`frontier` benches. |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -275,85 +291,9 @@ amicus update
 
 The `am` alias is interchangeable with `amicus` everywhere.
 
-### `amicus start` options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--model <model>` | Alias, `provider/model`, or `openrouter/provider/model`. | config default |
-| `--prompt <text>` | Task description. | *(required unless `--prompt-file`)* |
-| `--prompt-file <path>` | Read the prompt from a UTF-8 file (XOR `--prompt`). | |
-| `--agent <agent>` | OpenCode agent: `Chat`, `Build`, `Plan`. | `Chat` interactive / `Build` headless |
-| `--no-ui` | Run headless (autonomous, no window). | off |
-| `--json` | Emit the run result as stable JSON (requires `--no-ui`). | off |
-| `--timeout <minutes>` | Headless timeout. | 15 |
-| `--context-turns <N>` | Max conversation turns to include. | 50 |
-| `--context-since <duration>` | Time filter (e.g. `2h`); overrides turns. | |
-| `--context-max-tokens <N>` | Max context tokens. | 80000 |
-| `--no-context` | Skip parent conversation history. | off |
-| `--thinking <level>` | Reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. | model default |
-| `--summary-length <length>` | Fold summary verbosity: `brief`, `normal`, `verbose`. | `normal` |
-| `--mcp <spec>` | Add an MCP server (`name=url` or `name=command`). | |
-| `--mcp-config <path>` | Path to an `opencode.json` with MCP config. | |
-| `--no-mcp` | Don't inherit MCP servers from the parent. | off |
-| `--exclude-mcp <name>` | Exclude a specific inherited MCP server (repeatable). | |
-| `--session-id <id\|current>` | Session to pull context from. | `current` |
-| `--cwd <path>` | Project directory. | cwd |
-| `--client <type>` | Client context: `code-local`, `code-web`, `cowork`. | `code-local` |
-| `--position <pos>` | Window position: `right`, `left`, `center`. | `right` |
-| `--fold-shortcut <key>` | Customize the fold keyboard shortcut. | `Cmd/Ctrl+Shift+F` |
-| `--opencode-port <port>` | Port override for the OpenCode server. | |
-| `--session-dir <path>` | Explicit session-data directory. | |
-| `--setup` | Force-open configuration before launching. Does **not** relax the `--prompt`/`--prompt-file` requirement — `start --setup` still fails fast with "Error: --prompt or --prompt-file is required" if neither is given. | |
-| `--no-validate-model` | Skip model-catalog validation before launch. | validation on |
-
-> Agents: **Chat** auto-approves reads and asks before writes/bash (interactive default); **Build** has full tool access (headless default); **Plan** is read-only analysis. `--agent Chat` is interactive-only and incompatible with `--no-ui`.
-
-### `amicus fanout` — same prompt, many models
-
-```bash
-amicus fanout --models "gemini,deepseek,gpt" --prompt "Review this design" --json
-```
-
-Fanout runs one **headless wave**: every leg gets the **same** prompt (this is the shared-prompt model the council's review stages are built on). When all legs are terminal it prints **one** JSON wave document on stdout.
-
-- `--models <a,b,c>` — comma-separated aliases or `provider/model` IDs (required, unless `--council`).
-- `--council <name>` — run a saved council (e.g. `free`) instead of `--models`; mutually exclusive with `--models`.
-- `--prompt <text>` / `--prompt-file <path>` — the shared briefing. `--prompt-file` avoids the ~32 KB Windows argument cap and is mutually exclusive with `--prompt`.
-- `--wave-id <id>` — set the wave ID explicitly (leg IDs become `<id>-1..N`).
-- `--json` — emit the wave document.
-- `--session-id <id|current>` — session to pull shared context from (same as `start`; supported on `fanout` too).
-- Shared per-leg knobs: `--agent`, `--thinking`, `--timeout`, `--summary-length`, `--no-context`, the `--context-*` flags, the `--mcp*` flags, `--no-validate-model`, `--cwd`.
-- **Exit codes:** `0` all legs complete, `2` partial wave, `1` none complete / hard failure.
-
-### Other commands
-
-```bash
-amicus list                          # current project
-amicus list --status running         # filter by status: running, complete, error,
-                                      # timed-out, aborted, crashed, idle-timeout
-amicus list --all                    # all projects
-amicus list --json                   # machine-readable
-
-amicus read <id>                     # summary (default)
-amicus read <id> --conversation      # full conversation
-amicus read <id> --metadata          # session metadata
-amicus read <id> --json              # stable JSON (run or wave document)
-
-amicus status <id>                   # one-shot status for a session or wave
-amicus status --wave <id>            # alternative spelling for a wave ID
-amicus status <id> --json            # machine-readable output
+**Every flag, every subcommand, every example** — including the full `amicus start` option table, `amicus fanout` (supports `--session-id`, `--council <name>` as an alternative to `--models`), council presets, and every other command — lives in **[docs/usage.md](./docs/usage.md)**, the canonical CLI reference. What follows here is just enough to see the shape of a run.
 
-amicus resume <id>                   # reopen with full history
-amicus continue <id> --prompt "..."  # new session, previous one as read-only context
-
-amicus abort <id>                    # stop one running session
-amicus abort --all                   # stop all running sessions in this project
-
-amicus setup --api-keys              # open just the API-key window
-amicus setup --add-alias fast=openrouter/google/gemini-2.5-flash   # add/override one alias
-```
-
-**`amicus status <id>` output.** Human-readable:
+`amicus status <id>` output. Human-readable:
 
 ```
 $ amicus status demo123
@@ -371,41 +311,26 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
 ```
 
-A running session additionally reports `messages`, `lastActivity`/`latest`, and (if stalled) a `STALLED` line with recovery guidance in `--json`. A wave ID (`amicus status <waveId>` / `--wave <waveId>`) instead reports `legsComplete`/`legsTotal` and a per-leg breakdown.
+`amicus list --status` accepts `running`, `complete`, `error`, `timed-out`, `aborted`, `crashed`, `idle-timeout`. Full field-by-field docs (a running session's `messages`/`STALLED` reporting, wave-ID status shape, etc.) are in [docs/usage.md](./docs/usage.md).
 
 ---
 
 ## Models
 
-Amicus does **not** ship a frozen table of model names. Aliases and validation resolve against a **live catalog** fetched from provider APIs and cached at `~/.config/amicus/model-catalog.json` (24-hour TTL; the fetch works without an API key).
+Amicus does **not** ship a frozen table of model names. Aliases and validation resolve against a **live catalog** fetched from provider APIs and cached at `~/.config/amicus/model-catalog.json` (24-hour TTL; the fetch works without an API key). Run `amicus models` to see exactly what resolves on *your* machine — that's the source of truth, not this README.
 
 ```bash
 amicus models                 # list the catalog
-amicus models --search gemini # filter by substring over id and name
-amicus models --refresh       # force-refresh from provider APIs
-amicus models --check         # audit your aliases against the catalog
+amicus models --search gemini # filter by substring
 ```
 
-`amicus models --check` exits with the **number of stale aliases** (capped at 100) and prints same-vendor replacement suggestions for each, so it drops cleanly into CI.
-
-**Validation on launch.** `start` and `fanout` validate the model against the catalog before launching. For an explicit `--model` on `continue`/`resume` this is **blocking** (a typo'd model fails fast with suggestions); for a model *inherited* from a prior session it's **advisory**. Skip it any time with `--no-validate-model`, or fix the catalog with `amicus models --refresh`.
-
-**Aliases are a curated seed, not a fixed list.** `amicus setup` seeds a curated set of short aliases (e.g. `gemini`, `gpt`, `opus`, `deepseek`), and you add or override them with `amicus setup --add-alias name=provider/model`. To see exactly what resolves on *your* machine, run `amicus models` — that is the source of truth, not this README.
-
-**Full-id passthrough.** You can always bypass aliases and name a model directly. The prefix decides which credentials are used:
-
-| Format | Example | Credentials |
-|--------|---------|-------------|
-| `openrouter/provider/model` | `openrouter/google/gemini-2.5-flash` | `OPENROUTER_API_KEY` |
-| `google/model` | `google/gemini-2.5-flash` | `GOOGLE_GENERATIVE_AI_API_KEY` |
-| `openai/model` | `openai/gpt-5` | `OPENAI_API_KEY` |
-| `anthropic/model` | `anthropic/claude-opus-4` (the `opus` alias resolves here by default) | `ANTHROPIC_API_KEY` |
+`start`/`fanout` validate your model against the catalog before launching (skip with `--no-validate-model`). You can also always bypass aliases and pass a full `provider/model` or `openrouter/provider/model` ID directly. Catalog internals, alias management, and the full-id passthrough table are in **[docs/usage.md § Models](./docs/usage.md#amicus-models--the-model-catalog)**.
 
 ---
 
@@ -430,68 +355,25 @@ The MCP server is auto-registered on install (Claude Code and Claude Desktop / C
 | `amicus_council_stats` | Reviewer-reliability stats from past council runs. |
 | `amicus_verdict` | Build the final council verdict from a tally + decisions. |
 
-The async pattern is **start → status → read**: `amicus_start` (or `amicus_fanout`) returns immediately, you poll `amicus_status`, then `amicus_read` once it's done — so the calling agent never blocks. Prefer `amicus_wait` over manual sleep+status polling for headless runs: it collapses the poll loop into a single blocking call that returns as soon as the run finishes (or the wait window closes).
+The async pattern is **start → status → read** — `amicus_start`/`amicus_fanout` return immediately, then you poll `amicus_status` and call `amicus_read`; `amicus_wait` collapses that poll loop into one blocking call.
 
-To register manually (user scope):
+> Legacy `sidecar_*` tool names were removed entirely in v2.0.0 — only `amicus_*` tools exist now. `AMICUS_LEGACY_ALIASES=1` is a no-op left over from the v1.8.0 opt-in switch. See [docs/SHIMS.md](./docs/SHIMS.md).
 
-```bash
-claude mcp add-json amicus '{"command":"npx","args":["-y","amicus@latest","mcp"]}' --scope user
-```
-
-> Legacy `sidecar_*` tool names are no longer registered by default (v1.8.0). To restore them, add `"env": {"AMICUS_LEGACY_ALIASES": "1"}` to the server entry. They will be removed entirely in the next major.
+Manual registration and per-tool detail are in **[docs/usage.md § MCP Server](./docs/usage.md#mcp-server)**.
 
 ---
 
 ## Configuration
 
-`amicus setup` is the recommended way to configure Amicus — it writes API keys to `~/.config/amicus/.env` (`0600`) and persists your default model and aliases. The environment variables below are for overrides and tuning. Dev-only variables (mock/update testing) are documented in [docs/configuration.md](./docs/configuration.md).
-
-**API keys**
-
-| Variable | Purpose |
-|----------|---------|
-| `OPENROUTER_API_KEY` | OpenRouter (multi-provider access). |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | Direct Google access. |
-| `OPENAI_API_KEY` | Direct OpenAI access. |
-| `ANTHROPIC_API_KEY` | Direct Anthropic access. |
-| `DEEPSEEK_API_KEY` | Direct DeepSeek access. |
-
-**Behavior**
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `LOG_LEVEL` | Log verbosity: `error`, `warn`, `info`, `debug`. | `error` |
-| `AMICUS_CONFIG_DIR` | Override the config directory (keys, catalog, sessions). | `~/.config/amicus` |
-| `AMICUS_FANOUT_MAX_LEGS` | Cap the number of legs in a single fanout wave; non-positive values fall back to 10. | `10` |
-| `AMICUS_SHARED_SERVER` | When `1`, multiple MCP sessions share a single OpenCode Go process, eliminating cold-start latency. Set to `0` for per-process isolation or to diagnose a crash loop. | `1` |
-| `AMICUS_MCP_CLIENT` | Override the auto-detected MCP caller (`code-local`, `code-web`, or `cowork`). Amicus detects Claude Code vs. Claude Desktop/Cowork from the MCP `initialize` handshake; set this only if detection picks the wrong one. Note: `code-web` requires an explicit `--session-dir` and is not usable for MCP-spawned sessions. | auto-detected |
-
-**Headless poller tuning** (advanced — rarely needed)
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `AMICUS_POLL_INTERVAL_MS` | Delay between poll cycles. | `2000` |
-| `AMICUS_POLL_CALL_TIMEOUT_MS` | Per-poll call timeout. | `30000` |
-| `AMICUS_STABLE_FINISHED_POLLS` | Stable polls required after a completion signal. | `2` |
-| `AMICUS_STABLE_IDLE_POLLS` | Stable polls required with no completion signal (~60 s at 2 s). | `30` |
-| `AMICUS_MAX_CONSECUTIVE_POLL_FAILURES` | Consecutive poll failures before bailing. | `15` |
-
-**GUI & debug**
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `AMICUS_GUI_LOAD_TIMEOUT_MS` | Max wait for the Electron UI to load before showing what's in flight. | `15000` |
-| `AMICUS_DEBUG_PORT` | Chrome DevTools Protocol port for the Electron window. | `9222` |
+`amicus setup` is the recommended way to configure Amicus — it writes API keys to `~/.config/amicus/.env` (`0600`) and persists your default model and aliases. Every environment variable (API keys, behavior tuning, headless poller, GUI/debug, process lifecycle) is documented in **[docs/configuration.md](./docs/configuration.md)**. v2.0.0 removed the legacy `SIDECAR_*` → `AMICUS_*` env-var mapping entirely; see [docs/SHIMS.md](./docs/SHIMS.md) for the removal record and rename table.
 
-> **Legacy names.** The pre-rebrand `SIDECAR_*` environment variables are still honored (with a one-time deprecation warning) and map to their `AMICUS_*` equivalents. See **[docs/SHIMS.md](./docs/SHIMS.md)** for the full mapping.
+**New to the disk footprint?** The config tree's file-by-file contents, session storage layout, where (and whether) logs are written, `config.json`'s exact shape, and full uninstall instructions all live in **[docs/configuration.md § Where things live](./docs/configuration.md#where-things-live)**.
 
 ---
 
 ## JSON output
 
-With `--json`, Amicus emits stable, versioned documents on stdout — built for scripting and agent consumption.
-
-**Run document** (a single session — `start`, `read`, each fanout leg):
+With `--json`, Amicus emits stable, versioned run/wave documents on stdout — built for scripting and agent consumption:
 
 ```json
 {
@@ -501,22 +383,7 @@ With `--json`, Amicus emits stable, versioned documents on stdout — built for
 }
 ```
 
-`modelInput` is the alias you passed; `model` is the resolved id. `status` is one of `complete | error | timeout | aborted` (plus `crashed` / `idle-timeout`); `summary` carries the fold output.
-
-**Wave document** (`fanout`, and `read <waveId> --json`):
-
-```json
-{
-  "schemaVersion": 1, "waveId": "...",
-  "status": "complete",
-  "counts": { "total": 0, "complete": 0, "error": 0, "timeout": 0, "aborted": 0 },
-  "legs": [ /* one run document per model, in --models order */ ]
-}
-```
-
-`status` is `complete | partial | error | aborted`. A leg's `summary` is that model's full response.
-
-**Exit codes** (for `--no-ui` / `fanout`): `0` success / all legs complete · `2` partial wave · `1` error, nothing completed, or hard failure · `130` interrupted (SIGINT) · `143` terminated (SIGTERM).
+The wave-document shape (for `fanout`), field meanings, and the full exit-code table are in **[docs/usage.md § JSON Output](./docs/usage.md#json-output)**.
 
 ---
 
@@ -535,10 +402,12 @@ Most Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.
 
 ## Troubleshooting
 
+Run `amicus doctor` first — it checks keys, catalog, OpenCode binary, Electron, skills, and MCP registration in one pass and prints a targeted fix for whatever's failing. For symptoms not covered below, or more diagnostic depth on any of these, see **[docs/troubleshooting.md](./docs/troubleshooting.md)**.
+
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
 | "council review this" does nothing | The `second-opinion` skill isn't installed | Check `~/.claude/skills/second-opinion/SKILL.md` exists; re-run `npm install -g amicus` (postinstall installs both skills) |
-| `npm install -g amicus` fails with `EEXIST: … claude-sidecar` | The old upstream `claude-sidecar` package is still installed globally; npm won't overwrite another package's bin shims | `npm uninstall -g claude-sidecar`, then `npm install -g amicus`. Your config and sessions carry over (legacy paths are still read). |
+| `npm install -g amicus` fails with `EEXIST: … claude-sidecar` | The old upstream `claude-sidecar` package is still installed globally; npm won't overwrite another package's bin shims | `npm uninstall -g claude-sidecar`, then `npm install -g amicus`. Your keys and past sessions are not lost, but v2.0.0 no longer reads the old paths automatically — see [docs/SHIMS.md](./docs/SHIMS.md) for the one-time migration steps (rename `~/.config/sidecar/` and any `.claude/sidecar_sessions/` dirs). |
 | Install fails partway, or `amicus doctor` reports the OpenCode binary "not found" | A **transient** error during the OpenCode engine's own postinstall (a spawn `ENOENT`, or an antivirus file-lock while it lays down its 11 per-platform binaries) can roll back the whole atomic install — retrying usually succeeds | Just re-run `npm install -g amicus`. If it still fails, clear the cache first: `npm cache clean --force && npm install -g amicus`. |
 | `401` / auth error | API key missing, or the model prefix doesn't match the key you have | Run `amicus setup`; make sure the prefix (`openrouter/…` vs `google/…` vs `openai/…` vs `anthropic/…`) matches the credentials you configured. |
 | `402` / "Payment Required" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter <key>` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See "Free council (zero-cost)" under [The Council](#the-council) above. |
@@ -562,7 +431,8 @@ LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui
 
 | Doc | Description |
 |-----|-------------|
-| [docs/usage.md](./docs/usage.md) | Command-by-command usage guide. |
+| [docs/usage.md](./docs/usage.md) | The complete CLI & MCP reference — every flag, every subcommand, every example. |
+| [docs/council.md](./docs/council.md) | Council pipeline reference: `tally`/`verdict`/`report` schemas, provenance, and a worked example. |
 | [docs/configuration.md](./docs/configuration.md) | Full configuration and environment reference. |
 | [docs/architecture.md](./docs/architecture.md) | How the engine, Electron shell, and context sharing fit together. |
 | [docs/opencode-integration.md](./docs/opencode-integration.md) | How Amicus drives the OpenCode runtime. |
@@ -570,7 +440,7 @@ LOG_LEVEL=debug amicus start --model gemini --prompt "test" --no-ui
 | [docs/electron-testing.md](./docs/electron-testing.md) | Chrome DevTools Protocol patterns for UI testing. |
 | [docs/testing.md](./docs/testing.md) | Test suite layout and how to run it. |
 | [docs/publishing.md](./docs/publishing.md) | Release and publish process. |
-| [docs/SHIMS.md](./docs/SHIMS.md) | Legacy `SIDECAR_*` → `AMICUS_*` compatibility shims. |
+| [docs/SHIMS.md](./docs/SHIMS.md) | v2.0.0 removal record for the pre-rebrand `sidecar*` compatibility shims — what was removed and how to migrate. |
 | [skills/second-opinion/SKILL.md](./skills/second-opinion/SKILL.md) | The LLM Council skill. |
 | [skills/sidecar/SKILL.md](./skills/sidecar/SKILL.md) | The `sidecar` chat skill. |
 | [evals/README.md](./evals/README.md) | End-to-end eval harness for LLM interactions. |

package/bin/amicus.js

@@ -7,18 +7,7 @@
  * Routes commands to appropriate handlers.
  */
 
-// One-time, non-destructive migration of the legacy ~/.config/sidecar dir onto
-// the canonical ~/.config/amicus (copy; legacy kept as a backup). Runs before
-// any config/credential read so both resolve to the unified dir. Best-effort.
-try {
-  const { migrateLegacyConfigDir } = require('../src/utils/config');
-  const _m = migrateLegacyConfigDir();
-  if (_m && _m.migrated) {
-    process.stderr.write(`[amicus] Migrated config ${_m.from} → ${_m.to} (legacy kept as a backup).\n`);
-  }
-} catch { /* best-effort: never block startup on migration */ }
-
-// Load API keys from all sources: process.env > sidecar .env > auth.json
+// Load API keys from all sources: process.env > amicus .env > auth.json
 const { loadCredentials } = require('../src/utils/env-loader');
 loadCredentials();
 
@@ -123,6 +112,11 @@ async function main() {
         exitCode = await handleDoctor(args);
         break;
       }
+      case 'spend': {
+        const { handleSpend } = require('../src/cli-handlers-spend');
+        exitCode = await handleSpend(args);
+        break;
+      }
       case 'setup':
         await handleSetup(args);
         break;
@@ -162,9 +156,9 @@ async function main() {
  * Spec Reference: §4.2
  */
 async function handleList(args) {
-  const { listSidecars } = require('../src/index');
+  const { listAmicus } = require('../src/index');
 
-  await listSidecars({
+  await listAmicus({
     status: args.status,
     all: args.all,
     json: args.json,
@@ -181,7 +175,7 @@ async function handleResume(args) {
 
   if (!taskId) {
     console.error('Error: task_id is required for resume');
-    console.error('Usage: sidecar resume <task_id>');
+    console.error('Usage: amicus resume <task_id>');
     process.exit(1);
   }
 
@@ -191,9 +185,9 @@ async function handleResume(args) {
     process.exit(1);
   }
 
-  const { resumeSidecar } = require('../src/index');
+  const { resumeAmicus } = require('../src/index');
 
-  return await resumeSidecar({
+  return await resumeAmicus({
     taskId,
     project: args.cwd,
     headless: args['no-ui'],
@@ -210,7 +204,7 @@ async function handleContinue(args) {
 
   if (!taskId) {
     console.error('Error: task_id is required for continue');
-    console.error('Usage: sidecar continue <task_id> --prompt "..."');
+    console.error('Usage: amicus continue <task_id> --prompt "..."');
     process.exit(1);
   }
 
@@ -245,9 +239,9 @@ async function handleContinue(args) {
     args.model = await validateFallbackModel(args, alias);
   }
 
-  const { continueSidecar } = require('../src/index');
+  const { continueAmicus } = require('../src/index');
 
-  return await continueSidecar({
+  return await continueAmicus({
     taskId,
     newTaskId: args['task-id'],
     briefing: args.prompt || args.briefing,

package/commands/council.md

@@ -19,4 +19,6 @@ don't re-ask for what is already present).
 
 Then follow the second-opinion skill end to end: Stage 0 intake/prep and run-folder
 setup, council selection with a cost estimate and explicit user confirmation, the
-three review waves, `amicus council tally`, and the accept/deny decision pass.
+three review waves, `amicus council validate` on each leg's findings block,
+`amicus council tally`, the accept/deny decision pass, and `amicus council verdict`
+to write the final `verdict.json`.