amicus 1.8.0 → 1.9.0

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

@@ -1,6 +1,19 @@
 ---
 name: second-opinion
-description: Run a structured, multi-model "council" review of material the user provides and turn it into decisions. Use when the user supplies one or more documents, artifacts, or links PLUS an analysis request and criteria, and wants other AI model(s) to independently evaluate, critique, fact-check, stress-test, or red-team that material and then help act on the findings. The council adds a peer cross-review stage — models review the material independently, then anonymously rank and adjudicate each other's reviews, and a designated non-Claude "chair" model synthesizes the verdict while Claude orchestrates but does not synthesize. Trigger on "second opinion", "multi-model review", "council review", "have other models review/critique/evaluate this", "cross-check this against the research", "red-team/stress-test this doc", "what would other models conclude about this", or any request to review provided material with external model(s) and turn it into accept/deny edits — even if the user never says "sidecar". Optionally includes Claude as a judged (non-voting, non-chairing) council member to see how the bench rates Claude's own take. Defaults to 3 models from different families; scales down to a single thorough pass. This is NOT for quick or exploratory single-model chats — for "ask Gemini…", "what does DeepSeek think", brainstorming with a model, or spawning/forking a conversation with another model, use the sidecar skill instead.
+description: >
+  Run a structured, multi-model "council" review of material the user provides plus
+  an analysis request and criteria, turning it into decisions. Models review the
+  material independently, then anonymously rank and adjudicate each other's reviews
+  in a peer cross-review stage, and a designated non-Claude "chair" model synthesizes
+  the verdict — Claude orchestrates but does not synthesize. Trigger on "second
+  opinion", "multi-model review", "council review", "have other models
+  review/critique/evaluate this", "cross-check this against the research",
+  "red-team/stress-test this doc", "what would other models conclude about this", or
+  any request to review provided material with external model(s) and turn it into
+  accept/deny decisions — even if the user never says "sidecar". This is NOT for
+  quick or exploratory single-model chats — "ask Gemini…", "what does DeepSeek
+  think", brainstorming with a model, or spawning/forking a conversation with
+  another model — use the sidecar skill instead.
 ---
 
 # Second Opinion (LLM Council)
@@ -18,6 +31,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,13 +68,17 @@ 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.:
 
 **Free council (zero-cost).** If the user asks for a "free council" / "zero-cost council",
 read `councils.free` from `~/.config/amicus/config.json` and run
 `amicus fanout --council free --prompt-file <briefing>`. Free-tier handling:
-- Cost ≈ $0 — skip the paid-run cost framing (the budget gate is a no-op at zero price).
+- Cost ≈ \$0 — skip the paid-run cost framing (the budget gate is a no-op at zero price).
 - No reliability history: free models have no `amicus council stats` / `MODEL-NOTES` record,
   so don't rank on street-cred. Pick the most capable free model as chair and state lower confidence.
 - Weak structured output: small free models are less reliable at the strict findings JSON; expect
@@ -97,10 +116,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 +166,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 +203,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 +212,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 +232,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 +272,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 +343,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 +361,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 +472,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 +482,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,52 @@
 ---
 name: sidecar
+argument-hint: "[model] [prompt...]"
 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.
 
+## Slash invocation (`/amicus:sidecar <model> <prompt…>`)
+
+When invoked as a slash command with arguments:
+
+- First argument (the model): $1
+- Full argument string: $ARGUMENTS
+
+Treat $1 as the target model alias and the remainder of $ARGUMENTS as the prompt.
+If $1 is not a plausible model alias (gemini, gemini-pro, gpt, codex, deepseek,
+qwen, grok, mistral, glm, …), treat the ENTIRE argument string as the prompt and
+default to gemini. Then apply the critical rules below exactly as for any other
+invocation (run_in_background: true, --prompt-file for long briefings, interactive
+by default for a single model, never o3/o3-pro unprompted).
+
+## 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 +217,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 +270,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 +296,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 +316,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 +417,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 +467,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 +862,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 +925,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/cli-handlers-doctor.js

@@ -34,7 +34,7 @@ function realDeps() {
       ensureNodeModulesBinInPath();
       return hasOpencodeBinary();
     },
-    getElectronPath: () => require('./sidecar/interactive').getElectronPath(),
+    getElectronPath: () => require('./sidecar/interactive-process').getElectronPath(),
     // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
     // stays separate; repair only runs when fix is requested.
     repairElectron: (opts) => require('./sidecar/electron-install').repairElectron(opts),

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 {