amicus 1.8.0 → 1.8.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "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,37 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.8.1] - 2026-07-02
+
+Docs & skills accuracy sprint from the Phase-8 whole-branch review — no engine changes. Every item fixed a claim
+that actively misdirected Claude or users, plus one headless completion-state bugfix.
+
+### Changed
+- **`report.html` is now the default final council artifact**, and an inline verdict summary in chat is
+  MANDATORY at Stage 5 of the second-opinion skill.
+- **The `sidecar` skill's frontmatter dropped the "second opinion from another model" trigger** — those requests
+  now route to the `second-opinion` skill instead.
+- **MODEL-NOTES seed updated** with durable lessons from council runs 4-7 (new Grok/Kimi/Mistral/Claude-in-council
+  sections; shipped/local split defined). Existing installs: the machine-local copy is installed only-if-missing —
+  merge/refresh manually by pointing at the shipped file.
+- **Council mechanics hardened:** mandatory no-tools preamble for judges and chair (plus scratch-cwd advice);
+  `--max-cost` / `--no-cost-gate` pass-through documented for repair and chair calls (the false solo-start
+  cost-gate exemption was removed); `--models` lists quoted in every example; current-date injection rule for
+  time-sensitive artifacts.
+
+### Fixed
+- **Plugin quick-start now states the truth:** plugin installs do not put `amicus` on `PATH`; use
+  `npx -y amicus@latest <cmd>`. Both skills gained an npx-fallback/transport rule.
+- **README/usage now document `doctor`, `key`, and `council`;** troubleshooting leads with `amicus doctor`; the
+  false "`amicus list` shows active servers" claim is replaced with real `netstat`/`lsof` guidance.
+- **Headless runs that finish via idle detection no longer write `status:"error"` / `reason:"Incomplete"` to
+  `metadata.json`.** The poll loop's two genuine idle-completion exits — the SDK-authoritative `session.status`
+  idle signal and the stable-poll activity heuristic (both gated on real output, F1 #16) — broke out of the loop
+  without setting `completed`, so `resolveTerminalState` fell through to error and poisoned `amicus_list` /
+  `amicus_status` / wave rollups for successful runs, while the stdout `--json` doc correctly said
+  `status:"complete"`. Both exits now mark the run completed, matching the fold-marker branch. Dead-server
+  classification is unchanged: the consecutive-poll-failure fast-exit (F4) and crash paths still report an error.
+
 ## [1.8.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -57,7 +57,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ## Quick start
 
-**Install** — pick whichever fits; all deliver the same CLI, MCP server, and both skills:
+**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 +67,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 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. (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):
 
@@ -96,6 +96,8 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 
 ```bash
 amicus setup
+# plugin-only install (no CLI on PATH):
+npx -y amicus@latest setup
 ```
 
 This opens a graphical wizard:
@@ -113,7 +115,7 @@ This opens a graphical wizard:
 
 > *council review this*
 
-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 installed in the previous step is what teaches Claude to recognize this — if nothing happens, confirm it landed in `~/.claude/skills/second-opinion/`.)
+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:
 
@@ -261,6 +263,9 @@ amicus update
 | `amicus read` | Output a session's summary / conversation / metadata. |
 | `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 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 abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -304,7 +309,7 @@ The `am` alias is interchangeable with `amicus` everywhere.
 ### `amicus fanout` — same prompt, many models
 
 ```bash
-amicus fanout --models gemini,deepseek,gpt --prompt "Review this design" --json
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "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.",
   "keywords": [
     "claude",

package/skills/second-opinion/MODEL-NOTES.md

@@ -4,7 +4,8 @@ This file is the `second-opinion` skill's evolving memory of **how to actually d
 well**. Read it before Stage 0 (council selection and launch); update it, with the user's
 approval, at the end of each run (Stage 6). Keep it tight — merge and prune rather than append.
 
-_Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see changelog)._
+_Last updated: 2026-07-02 (runs 4-7 folded back from the field ledger: PowerShell quoting, date
+injection, long-read failures, judge tool-wander; see changelog)._
 
 ## Global operating rules (all models)
 - **Council runs are headless by design** (autonomous batch work): `fanout` is headless by
@@ -26,6 +27,18 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   model-specific signals. Never present a half-finished run as an answer.
 - **Credentials:** keys live in `~/.config/amicus/.env` (legacy `~/.config/sidecar/.env` still
   read). Configure with `amicus setup`.
+- **PowerShell `--models` quoting (Windows):** always quote comma-separated model lists —
+  `--models "gemini,gpt,deepseek"`. Unquoted, PowerShell splits on commas and amicus receives one
+  mangled alias → instant arg-parse failure. (Now baked into every SKILL.md example.)
+- **Inject the current date into briefings for time-sensitive artifacts** (resumes, dated plans).
+  Headless models don't reliably know "today": one run produced a false "future-dated" blocker two
+  judges then confirmed. (Now a Stage-0 rule in SKILL.md.)
+- **Very long artifacts (80k+ words) break the agent-reads-the-file transport for some models.**
+  gpt/deepseek/grok have handled 82k-word agentic reads; gemini(-flash) and kimi stalled (narrate-
+  stall / 25-min timeout / poller "Incomplete"). Pre-select proven long-read models or inline the
+  text for large-context models.
+- **Stage-6 approvals:** write the proposed MODEL-NOTES diff to a run-folder file and put that path
+  in the approval prompt — chat-text diffs can be hidden behind the approval dialog.
 
 ## Stage-2 cross-review briefing tips
 
@@ -36,6 +49,11 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   finding referenced by run-global label id (e.g. `A2` = Review A's 2nd finding).
 - After de-anonymizing, assemble the tally input (see SKILL.md Stage 2 assembly recipe) and run
   `amicus council tally <input.json> --json` — do not hand-tally tiers or street-cred numbers.
+- Telling judges that **material severity inflation can justify a `dispute`** sharpens adjudications.
+- **Plan-agent judges can wander to tools** (reading run-folder files = anonymization leak). The
+  no-tools preamble is now mandatory in SKILL.md Stage 2/3 — keep it verbatim.
+- The tally input needs **all five keys** (`meta` incl. `meta.models`, `findings`, `adjudications`,
+  `rankings`, `runStats`) — see the SKILL.md Stage-2 recipe step 0.
 
 ## Per-model notes
 
@@ -45,17 +63,44 @@ _Last updated: 2026-06-10 (v3 migration: engine workarounds pruned — see chang
   structured output verbatim, without preamble. (Historical: its narrate-then-glob habit used to
   trip the old headless poller; the engine handles tool-call gaps now — F1.)
 - Don't trust its self-reported version string ("I am gemini-X") as ground truth.
+- **Red-team:** takes an adversarial brief well — high variance by design; use when consensus risk is high.
+- **Blind self-votes are inconsistent** (self-#1 in some runs, self-last in others) → discount self-votes either way.
+- Alias has resolved to **flash** tiers: fast, shallowest coverage, yet a recurring sharp fact/consistency checker (it alone refuted a bench-wide date error). Cheap cross-check value.
+- **Unreliable on long agentic reads** (see global rule) — inline the text or swap models for book-length material.
 
 ### DeepSeek  (`--model deepseek` → via OpenRouter)
 - **Strengths:** resilient; produces strong, well-structured, well-cited critical analysis. A good
   default reviewer and a proven chair.
 - **Quirk:** occasional transient 502 mid-run → re-run the leg.
+- Proven chair (5 clean chairings) — decisive, well-structured synthesis.
+- As a Stage-1 reviewer of human-facing documents it **over-escalates severity** (typos/tenure → "blocker"); discount its blocker labels against peers. Prune its self-retractions when tallying.
+- **"Agree-with-the-adversary" lean:** it has been the lone endorser of a red-team's harshest claims, turning them Contested — cross-check before treating its lone agreements as consensus.
 
 ### GPT  (`--model gpt` → via OpenRouter)
 - **Strengths:** reachable via the OpenRouter key; resilient; very thorough structured critique
   (25 findings on a 1-page framework). Cleanly separates the review criteria.
 - **Quirks:** verbose — peers dinged it for volume-over-judgment (good coverage, lower
   discrimination); **self-ranked its own review #1** in cross-review → discount self-votes.
+- Ranked genuine #1 by all judges (incl. non-self) in one run — thoroughness is real, not a self-vote artifact. Handled an 82k-word agentic read cleanly.
+- **Asserts context-dependent facts (dates, "is this future?") without verifying** — and self-confirms them in adjudication. Cross-check any time-dependent claim it raises.
+- A good calibration anchor in cross-review: confirms observational findings, disputes interpretive overreach.
+
+### Grok  (`--model grok` → via OpenRouter)
+- Very fast legs; credible judge and chair (rejected its own weak findings as chair; honest blind self-rank).
+- Strong red-team fit; handled an 82k-word agentic read. Weight its **observational** catches heavily and its **interpretive** verdicts cautiously (bench pattern: the former confirmed, the latter disputed).
+- Stage-1 non-red-team reviews skew to scope-inflated "missing content" majors.
+
+### Kimi  (`--model kimi` → via OpenRouter)
+- The bench's sharpest adjudicator (caught strawmen and misreads other judges waved through).
+- **Very slow legs (5-7 min)** — it gates wave wall-clock; budget timeouts around it.
+- Stalls on long agentic reads (poller "Incomplete" with only a preamble). Reserve for short-artifact adjudication.
+
+### Mistral  (`--model mistral` → via OpenRouter)
+- Fast, broad coverage, catches real issues.
+- **Hallucination risk is real:** has invented non-existent product models/specs, disputed independently by two judges. Cross-check every specific model number or product claim it introduces.
+
+### Claude  (in-council, when toggle on)
+- Consistently the most *calibrated* reviewer (no severity inflation; findings overwhelmingly Confirmed; bench-best street-cred in recent runs) but sometimes the least *original* — it can miss the boldest single catch. Treat as a reliability floor, not a discovery engine.
 
 ### (others — add as used)
 - Opus / o-series etc. are reachable via amicus **if their API keys are configured**. Add notes
@@ -114,3 +159,4 @@ This section keeps only per-model **qualitative quirks** and **structural-confor
   cap (superseded by `--prompt-file`), the absolute-path/cwd trap (fixed by F2), and the
   GUI-hangs-on-this-machine rule (resolved 2026-06-10; headless stays the council default by
   design). Config path updated to `~/.config/amicus/.env`.
+- **2026-07-02** — Folded back field lessons from runs 4-7 (AV-receiver, pork-shoulder, resume, novel ×2 councils): PowerShell `--models` quoting; current-date injection; long-read model selection; judge no-tools preamble; severity-inflation-justifies-dispute; five-keys tally schema; new Grok/Kimi/Mistral/Claude-in-council sections. Quantitative history stays in the ledger (`amicus council stats`).

package/skills/second-opinion/SKILL.md

@@ -18,6 +18,8 @@ Operating lessons from each run fold back into `MODEL-NOTES.md` (with approval),
 
 **Before launching any model, READ `MODEL-NOTES.md`** (next to this file). It holds the operating rules and per-model quirks that decide whether a run succeeds or silently fails. These were learned the hard way; skipping them wastes runs and produces empty results that look like answers.
 
+**Transport rule — CLI not on PATH:** every command below assumes the `amicus` CLI. If `amicus` is not on PATH (typical for **plugin-only installs**), run the identical commands as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest fanout --models "m1,m2,m3" --prompt-file <path> --json`), or use the equivalent MCP tools (`amicus_fanout`, `amicus_start`, `amicus_status`, `amicus_read`, `amicus_council_tally`, `amicus_council_stats`, `amicus_verdict`) — council briefings are always self-contained (`--no-context`), so MCP transport is equivalent.
+
 ## When to use
 
 - The user provides documents, artifacts, or links **and** an analysis request **and** criteria, and wants other models to weigh in independently.
@@ -53,6 +55,10 @@ in this run is written here. Use its absolute path in all `--prompt-file` argume
 - Write every briefing to a temp file (`_tmp-*.md` in the run folder) and pass it with
   `--prompt-file` — never inline a briefing as a CLI argument. All `_tmp-*` files are cleaned up
   after the run.
+- **Inject the current date into every briefing when the artifact is time-sensitive** (resumes, dated
+  plans, anything with start/end dates or 'present' ranges). Headless council models do not reliably
+  know "today" and have raised false "future-dated" blockers; state the date explicitly, e.g.
+  "Today's date is YYYY-MM-DD."
 
 **Pick the council.** Default: **3 models from different families (non-Claude)**. Recommend them ranked by fit, consulting both the reviewer-reliability data from `amicus council stats` (the authoritative quantitative source — runs, avg peers-only street-cred, confirm-rate, fact-error rate) and the qualitative quirks in `MODEL-NOTES.md`. State the estimated cost. The estimate is the budget gate's pre-flight figure (per-$/Mtok pricing from the cached catalog; direct-provider legs without catalog pricing are disclosed as "cost unknown"). State it as an estimate, not a guarantee. **Disclose the run shape up front** before asking for confirmation — e.g.:
 
@@ -97,10 +103,12 @@ Each council model reviews **the artifact** independently. Write one Stage-1 bri
 (`_tmp-briefing-stage1.md` in the run folder) and launch the whole wave as ONE background call:
 
 ```
-amicus fanout --models <m1,m2,m3> --prompt-file <run-folder>/_tmp-briefing-stage1.md --json \
+amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-briefing-stage1.md --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
+Always quote the `--models` list — unquoted, PowerShell splits on commas and the CLI receives one mangled alias (instant arg-parse failure).
+
 Run it in the background (`run_in_background: true`); you are notified on completion — do not
 poll. `fanout` is headless by definition. The command exits when every leg is terminal and prints
 ONE JSON wave document on stdout (`schemaVersion: 1`; the wave's id field is `waveId`, each leg's id is `taskId`): check `status` (`complete` | `partial` |
@@ -145,7 +153,7 @@ equivalent.
 Instruct models to emit the structured JSON verbatim after the prose, without preamble, so it parses cleanly.
 
 **After the wave returns, validate each leg's findings block** using `validateFindings` (Unit A — `src/council/findings.js`). If a leg's JSON fails validation:
-1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` is **not** subject to the WS-2 fanout cost gate, so a repair cannot be refused mid-council.)
+1. Issue a **solo `start --json`** re-prompt to that one model: "re-emit only the findings JSON, fixing: \<errors\>." Keep the first-pass prose. (Solo `start` passes through the **same budget gate** as `fanout`. If launching the wave required `--max-cost <$>` or `--no-cost-gate`, pass the **same flag on every repair re-prompt and on the chair call** — otherwise the gate can refuse a repair or the chair mid-council.)
 2. If still malformed, retry **once more** (cap = **2** re-prompts total).
 3. If still malformed after 2 retries, mark the review `unstructured` and hand-parse its prose into the schema. The review proceeds — never dropped for a formatting miss.
 
@@ -182,7 +190,7 @@ Each model **unknowingly ranks and adjudicates its own review** — this is the
 model. Write the bundle + judging instructions to `_tmp-bundle-stage2.md` and launch one wave:
 
 ```
-amicus fanout --models <m1,m2,m3> --prompt-file <run-folder>/_tmp-bundle-stage2.md --json \
+amicus fanout --models "<m1,m2,m3>" --prompt-file <run-folder>/_tmp-bundle-stage2.md --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
@@ -191,6 +199,12 @@ adjudication response. **Stage-2 degrade:** a judge leg dies → tally over the
 (≥ 1) and disclose the reduced bench in `crossreview-matrix.md`; tier definitions are unchanged
 (they already count "judges engaged"). Each judge is asked to do two things on the bundle:
 
+**Judge-briefing hardening (required).** Open `_tmp-bundle-stage2.md` with this preamble, verbatim, as its first line:
+
+> Do NOT use any tools or read any files; everything is in this message; begin immediately with A1:
+
+Plan-agent judges have wandered to tools mid-adjudication (reading files instead of judging and returning only narration), and a tool-capable judge can read the de-anonymized `review-<model>.md` files in the run folder — an anonymization leak. The preamble closes both. **Scratch-cwd (optional second layer):** launch the Stage-2 wave (and the Stage-3 chair call) with `--cwd <run-folder>/_scratch/` — create the empty directory first — so even a wandering agent finds nothing to read. Caveat: those legs' session records then live under `_scratch/.claude/amicus_sessions/`, so any later `amicus read <taskId>` for them needs the same `--cwd`.
+
 **Task A — Rank.** Order the reviews from most to least accurate and insightful. End the response with a parseable block in exactly this format (no other text on those lines):
 
 ```
@@ -205,11 +219,16 @@ FINAL RANKING:
 As each judge's ranking + adjudication response returns, collect it (the raw per-judge responses are working intermediates, not separate run-folder artifacts). Once all are in, **assemble the de-anonymized tally input** and then call `amicus council tally`:
 
 **Stage-2 → tally assembly recipe (Claude's work before calling `tally`):**
+0. **Build `meta` and `findings[]` first — `tally` requires both** (missing either fails with `BAD_ARGS: Cannot read properties of undefined (reading 'map')`):
+   - `meta` = `{ "runId": "<run-folder stem>", "models": [<every reviewed model id, including "claude" when the toggle is on — this is the street-cred universe>], "chair": "<confirmed chair model id>", "claudeInCouncil": <Stage-0 toggle> }`. Optional extras: `runType`, `date`.
+   - `findings[]` = one entry per finding across ALL reviews: `{ "id": "<run-global label id from step 1, e.g. A1>", "raiser": "<de-anonymized model that raised it>", "severity": "<from the review JSON>" }` (`claim` may be carried along but is not required).
 1. **Rewrite finding ids to run-global label ids.** Each Stage-1 review's local integer ids (`1`, `2`, `3`…) become `A1`, `A2`, `A3`… (where `A` is that review's anonymized label). The label↔model map (`Review A → deepseek`, etc.) is the key.
 2. **Build `adjudications`** — for every judge across all findings: `findingId` = run-global label id; `judge` = the model id (de-anonymized via the map); `verdict ∈ {agree, dispute, neutral}`. Include every judge's verdict on every finding. The raiser's own adjudication of its own finding is **included in the input** (the tally engine excludes it when computing peers-only tiers — do not pre-filter it).
 3. **Translate each judge's `FINAL RANKING:` block** — convert the label order (`1. Review C / 2. Review A / 3. Review B`) into a model `order` array via the same map (e.g. `{C→mistral, A→deepseek, B→gpt}` ⇒ `order: ["mistral","deepseek","gpt"]`). This is each entry in `rankings[]`.
 4. **Populate `runStats`** from the per-leg run documents emitted by `fanout --json` (and any solo red-team/chair `start --json` docs): copy `model`, `status`, `durationMs`, `usage` verbatim. Any leg with no run doc gets `durationMs: null` and `usage: null` — never invent a value. Attach `role` (`council` | `redteam` | `claude`), `wasChair`, and `conformance` (`clean` | `repaired` | `unstructured`) as council-domain labels.
 
+**Five-keys checklist — verify `tally-input.json` has ALL of:** `meta` (with `meta.models`), `findings`, `adjudications`, `rankings`, `runStats` (`runStats` may be `[]`; the other four are required). Do not call `tally` until all five are present.
+
 Then call:
 
 ```
@@ -240,11 +259,15 @@ amicus start --model <chair> --no-ui --json \
   --agent Plan --no-context --summary-length verbose --timeout <minutes>
 ```
 
+(The budget gate applies to this solo call too — if Stage 0 needed `--max-cost <$>` or `--no-cost-gate` to launch the wave, the chair call needs the same flag.)
+
 The run document's `summary` is the verdict. The packet contains:
 - All Stage-1 reviews (de-anonymized — model attribution restored)
 - All cross-review ranking outputs (with model attribution)
 - All adjudication outputs (with model attribution and `agree | dispute | neutral` verdicts per finding)
 
+Open `_tmp-chair-packet.md` with the no-tools preamble, adjusted for the chair: *'Do NOT use any tools or read any files; everything is in this message; begin immediately with the verdict.'* The packet is complete by construction — the chair must never go looking for files.
+
 Instruct the chair to write a **synthesized verdict** that:
 - Weighs each reviewer's findings by their peer-validated standing (street-cred rank and adjudication pattern)
 - Distinguishes findings the bench broadly endorsed from contested or singleton claims
@@ -307,15 +330,17 @@ Do not advance to Stage 5 until every finding in both tiers has a recorded decis
   — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
   invent a figure. Add a wave **total cost** row from the wave document's
   `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`; never invent a value.
-  - **Renderer:** once `verdict.json` is written, generate the human report with
-    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md`
-    (use `--html` for a self-contained, shareable page). This emits the
+  - **Renderer:** once `verdict.json` is written, generate BOTH renderings:
+    `amicus council report <run-folder>/verdict.json --md > <run-folder>/report.md` and
+    `amicus council report <run-folder>/verdict.json --html > <run-folder>/report.html`.
+    **`report.html` is the default final artifact to hand the user** — a self-contained,
+    shareable page. This emits the
     adjudication matrix (finding × judge), the peers-only street-cred table, the
     findings-by-tier groupings (Disputed-first), and the per-model + wave cost —
     deterministic data only. Prefer it over hand-assembling the matrix; reserve
     prose for the chair's synthesis and the decision log.
 
-Tell the user exactly which files were written and where.
+Tell the user exactly which files were written and where, leading with `report.html`, **and present the verdict inline in chat** — the chair's overall assessment (verbatim or lightly trimmed) plus the tier counts (Confirmed/Disputed/Contested/Singleton) and what was applied. Never hand over only file paths.
 
 ---
 
@@ -323,6 +348,8 @@ Tell the user exactly which files were written and where.
 
 This stage updates `MODEL-NOTES.md` to make future runs better. **Nothing is written until the user approves a specific diff.**
 
+The `MODEL-NOTES.md` **next to this file** is your machine-local run ledger: npm updates never overwrite it (it is installed only if missing), so lessons accumulate per machine. Durable, machine-independent lessons get folded back into the version-controlled copy in the amicus repo at release time (see the release checklist in `docs/publishing.md`).
+
 **Reflect on this run.** Review the run for:
 - Failures, near-misses, and mitigations that worked (poller traps, empty responses, timeout issues, briefing problems)
 - Briefing wording that produced **richer or poorer** structured output than expected
@@ -432,6 +459,7 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
     — exact for `reported`, `~` for `estimated`, `?` for `unknown` — and never
     invent a figure. Add a wave **total cost** row from the wave document's
     `usage.cost` (`source: reported|estimated|mixed|unknown`). Any leg with no run doc → `durationMs: null`, `usage: null`.
+  - `report.html` — the same report rendered as a self-contained page (`amicus council report <verdict.json> --html`); the default artifact to share.
 - Reviewed copy: `<stem>-reviewed.<ext>`, next to the source.
 - Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet, proposed
   MODEL-NOTES diff) live in the run folder and are cleaned up at the end of the run — the proposed-diff file
@@ -441,5 +469,5 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
 
 ## Files
 
-- `MODEL-NOTES.md` — operating rules, per-model qualitative quirks, cost guardrail, and structural-conformance notes. **Read it before Stage 0 (council selection and launch); update qualitative notes (with approval) in Stage 6.** Quantitative reliability data (runs, avg street-cred, confirm-rate, fact-error rate) comes from `amicus council stats`, not this file.
+- `MODEL-NOTES.md` — operating rules, per-model qualitative quirks, cost guardrail, and structural-conformance notes. **Read it before Stage 0 (council selection and launch); update qualitative notes (with approval) in Stage 6.** Quantitative reliability data (runs, avg street-cred, confirm-rate, fact-error rate) comes from `amicus council stats`, not this file. This copy is machine-local (never overwritten on update); the shipped seed lives in the amicus repo and absorbs durable lessons at release time.
 - `COUNCIL-DESIGN.md` — the design spec this skill implements (v3 + WS-3). Consult it if a mechanics question arises that the skill prose does not resolve.

package/skills/sidecar/SKILL.md

@@ -1,39 +1,37 @@
 ---
 name: sidecar
 description: >
-  Spawn conversations with other LLMs (Gemini, GPT, ChatGPT, Codex, o3, DeepSeek, Qwen,
-  Grok, Mistral, etc.) and fold results back into your context. TRIGGER when: user asks to
-  talk to, chat with, use, call, or spawn another LLM or model; user mentions Gemini, GPT,
-  ChatGPT, Codex, o3, DeepSeek, Claude (as a sidecar target), Qwen, Grok, Mistral, or any
-  non-current model by name; user asks to get a second opinion from another model; user
-  wants parallel exploration with a different model; user says "sidecar", "fork", or "fold".
-  CRITICAL RULES: (1) ALWAYS launch amicus CLI commands with Bash tool's
-  run_in_background: true. Never run amicus start/resume/continue in the foreground.
-  (2) The fold summary returns on stdout when the user clicks Fold in the GUI or the
-  headless agent finishes. Use TaskOutput to read it when the background task completes.
-  (3) For long or multi-line briefings, write them to a temp file and pass
-  --prompt-file <path> (mutually exclusive with --prompt; avoids shell-quoting hazards
-  and argument-size caps). (4) NEVER use o3 or o3-pro unless the user explicitly asks for it by
-  name. These models are extremely expensive ($10-60+ per request). If the user asks for
-  o3, warn them about the cost before proceeding. Default to gemini for most tasks.
-  (5) When the user asks to query MULTIPLE LLMs simultaneously (e.g., "ask Gemini AND
-  ChatGPT", "compare Gemini vs GPT"), ALWAYS use --no-ui (headless) for all of them
-  unless the user explicitly requests interactive. Opening multiple Electron windows at
-  once is disruptive. Launch them all in parallel with run_in_background: true.
-  (6) When the SAME prompt should go to N models, use `amicus fanout --models a,b,c
-  --prompt-file <path> --json` (one headless wave, one JSON result) instead of N
-  separate start calls. Different prompts per model → separate parallel
-  `amicus start --no-ui` calls.
-  (7) For a SINGLE-model sidecar, DEFAULT to interactive — omit --no-ui so the
-  Electron UI opens and the user can watch, converse, and click Fold. Use --no-ui
-  for a single model only when the user asks for headless/autonomous, or for
-  unattended bulk automation. Interactive launches still use run_in_background: true.
+  Spawn a conversation with another LLM (Gemini, GPT, ChatGPT, Codex, o3, DeepSeek,
+  Qwen, Grok, Mistral, or Claude as a target) and fold the results back into your
+  context. TRIGGER when: the user asks to talk to, chat with, call, use, or spawn
+  another LLM or model; names any non-current model; wants parallel exploration or
+  a quick take from a different model; or says "sidecar", "fork", or "fold". This
+  is NOT the skill for structured multi-model review of provided material — requests
+  like "second opinion", "council review", or red-team/stress-test against criteria
+  belong to the second-opinion skill. Before running any amicus command, read the
+  Operating Rules section at the top of this document: background launches,
+  --prompt-file briefings, interactive vs headless defaults, fanout for same-prompt
+  multi-model runs, the o3/o3-pro cost warning, and the npx fallback when amicus is
+  not on PATH.
 ---
 
 # Amicus: Multi-Model Sidecar Tool
 
 Spawn parallel conversations with different LLMs (Gemini, GPT, ChatGPT, Codex, o3, etc.) and fold results back into your context.
 
+## Operating Rules
+
+These rules are mandatory for every amicus invocation in this skill:
+
+1. **ALWAYS launch amicus CLI commands with the Bash tool's `run_in_background: true`.** Never run `amicus start/resume/continue` in the foreground.
+2. **The fold summary returns on stdout** when the user clicks Fold in the GUI or the headless agent finishes. Use TaskOutput to read it when the background task completes.
+3. **For long or multi-line briefings, write them to a temp file and pass `--prompt-file <path>`** (mutually exclusive with `--prompt`; avoids shell-quoting hazards and argument-size caps).
+4. **NEVER use o3 or o3-pro unless the user explicitly asks for it by name.** These models are extremely expensive (\$10-60+ per request). If the user asks for o3, warn them about the cost before proceeding. Default to gemini for most tasks. The CLI enforces this in code: a built-in budget gate refuses any model above a per-$/Mtok threshold (o3-pro class) before launch unless you pass `--no-cost-gate`; `--max-cost <$>` sets a soft estimated-total ceiling. When a run is refused with `BUDGET_EXCEEDED`, relay the gate's message — don't silently retry with the flag.
+5. **When the user asks to query MULTIPLE LLMs simultaneously** (e.g., "ask Gemini AND ChatGPT", "compare Gemini vs GPT"), ALWAYS use `--no-ui` (headless) for all of them unless the user explicitly requests interactive. Opening multiple Electron windows at once is disruptive. Launch them all in parallel with `run_in_background: true`.
+6. **When the SAME prompt should go to N models, use `amicus fanout --models "a,b,c" --prompt-file <path> --json`** (one headless wave, one JSON result) instead of N separate start calls. Different prompts per model → separate parallel `amicus start --no-ui` calls.
+7. **For a SINGLE-model sidecar, DEFAULT to interactive** — omit `--no-ui` so the Electron UI opens and the user can watch, converse, and click Fold. Use `--no-ui` for a single model only when the user asks for headless/autonomous, or for unattended bulk automation. Interactive launches still use `run_in_background: true`.
+8. **If `amicus` is not on PATH** (typical for plugin-only installs), run every command in this skill as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest start --model gemini --prompt "..."`), or use the MCP tools (`amicus_start`, `amicus_status`, `amicus_read`, …) instead. Do not conclude the tool is broken because `amicus` is not found.
+
 ## Installation
 
 ```bash
@@ -204,11 +202,11 @@ amicus start \
 ```
 
 **Required:**
-- `--model`: The model to use (see Models below)
-- `--prompt`: Detailed task description you generate
+- `--prompt` (or `--prompt-file`): Detailed task description you generate
 
 **Recommended:**
-- `--session`: Your Claude Code session ID for accurate context passing
+- `--model`: The model to use (see Models below). Omit it to use your configured default (`amicus setup`); the CLI errors only when neither an explicit model nor a configured default exists.
+- `--session-id`: Your Claude Code session ID for accurate context passing
 
 **Optional:**
 - `--no-ui`: Run autonomously without GUI (for bulk tasks)
@@ -257,7 +255,7 @@ The CLI validates all inputs **before** launching the sidecar. Invalid inputs fa
 
 | Input | Validation | Error Message |
 |-------|------------|---------------|
-| `--model` | Must be present, format: `provider/model` | `Error: --model is required` or `Error: --model must be in format provider/model` |
+| `--model` | Optional — falls back to the config default. An explicit value must resolve to a known alias or `provider/model` | `Error: Unknown model alias '<x>' …` or `No model specified and no default configured. Run 'amicus setup' to set a default model.` |
 | `--prompt` | Must be present and non-empty | `Error: --prompt is required` or `Error: --prompt cannot be empty or whitespace-only` |
 | `--cwd` | If provided, directory must exist | `Error: --cwd path does not exist: <path>` |
 | `--session-id` | If explicit ID provided (not 'current'), must exist | `Error: --session-id '<id>' not found. Use 'amicus list' to see available sessions or omit --session-id for most recent.` |
@@ -283,7 +281,7 @@ If you receive a validation error, fix the input and retry:
 
 ```bash
 # Error: --session-id 'abc123' not found
-# Fix: Use 'current' or omit --session
+# Fix: Use 'current' or omit --session-id
 amicus start --model gemini --prompt "Task" --session-id current
 
 # Error: --agent cannot be empty
@@ -303,7 +301,7 @@ amicus start --model gemini --prompt "Task"
 ### Fan Out One Prompt to N Models
 
 ```bash
-amicus fanout --models gemini,gpt,deepseek --prompt-file ./briefing.md --json
+amicus fanout --models "gemini,gpt,deepseek" --prompt-file ./briefing.md --json
 ```
 
 Runs the same prompt on every listed model in parallel (one shared engine server, headless),
@@ -404,7 +402,7 @@ amicus abort --all         # stop every running session in this project
 
 ### Model Selection
 
-Use short aliases (run `amicus guide` to see all available aliases and their current model IDs):
+Use short aliases (run `amicus models` to see the live catalog, and `amicus models --check` to audit your aliases):
 - `--model gemini` -- Google Gemini (fast, large context)
 - `--model opus` -- Claude Opus (deep analysis)
 - `--model gpt` -- OpenAI GPT
@@ -454,13 +452,13 @@ ls -lt ~/.claude/projects/-Users-john-myproject/*.jsonl | head -5
 The most recently modified file is likely your current session. Extract the UUID from the filename.
 
 **Session ID behavior:**
-- **Omit `--session`** or use `--session-id current`: Uses the most recently modified session file (less reliable if multiple sessions are active)
+- **Omit `--session-id`** or pass `--session-id current`: Uses the most recently modified session file (less reliable if multiple sessions are active)
 - **Explicit session ID** (`--session-id abc123-def456`): Must exist or the command fails immediately with: `Error: --session-id 'abc123-def456' not found`
 
 **If you get a session not found error:**
 1. List available sessions: `amicus list`
 2. Use one of the listed session IDs, OR
-3. Omit `--session` to use the most recent session
+3. Omit `--session-id` to use the most recent session
 
 ---
 
@@ -849,7 +847,7 @@ Find the correct encoded path for your project. Remember that `/`, `\`, and `_`
 
 ### "Multiple active sessions detected"
 
-You have multiple Claude Code windows. Pass `--session` explicitly:
+You have multiple Claude Code windows. Pass `--session-id` explicitly:
 ```bash
 ls -lt ~/.claude/projects/[your-path]/*.jsonl | head -3
 # Pick the correct session UUID
@@ -912,7 +910,7 @@ amicus start --model gemini --prompt "Debug the auth issue in TokenManager.ts"
 
 The explicit session ID doesn't exist. Either:
 1. Use `amicus list` to find valid session IDs
-2. Omit `--session` to use the most recent session
+2. Omit `--session-id` to use the most recent session
 3. Use `--session-id current` for automatic resolution
 
 ```bash

package/src/headless.js

@@ -463,6 +463,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             const s = (statusData && statusData.type) ? statusData : (statusData && statusData[sessionId]);
             if (s && s.type === 'idle') {
               logger.debug('Session reported idle by SDK — completing', { sessionId });
+              completed = true;
               break;
             }
           } catch (statusErr) {
@@ -493,6 +494,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             const threshold = assistantFinished ? stableFinishedPolls : stableIdlePolls;
             if (stablePolls >= threshold) {
               logger.debug('Session appears complete (idle)', { stablePolls, assistantFinished });
+              completed = true;
               break;
             }
           } else {