amicus 1.5.1 → 1.6.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.5.1",
+  "version": "1.6.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" },
   "homepage": "https://bourbondog.github.io/amicus/",

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-06-30
+
+Project-directory and session-addressing correctness — agents, sessions, and the interactive GUI now agree on which project they're in.
+
+### Added
+- **`AMICUS_PROJECT_DIR` + MCP `roots` support.** When the project is not passed explicitly, the MCP
+  server now resolves the working directory from the client's first `file://` workspace root (falling
+  back to `AMICUS_PROJECT_DIR`, then the process cwd) — so a stdio MCP server spawned by a desktop
+  client no longer roots agents in the app install directory where they can't see your files.
+- **Global session index.** `amicus_status` / `amicus_read` / `amicus_list` now consult a global
+  `taskId -> project` index on a per-project miss, so a session created in one project is still found
+  when looked up from another.
+- **Per-command help for the rest of the CLI.** `amicus council --help` (and `continue`, `resume`,
+  `doctor`, `setup`, `key`, `mcp`) now print their own scoped usage instead of the full global help.
+
+### Fixed
+- **Interactive `--cwd`: follow-up prompts no longer fail "unable to retrieve session."** When the
+  launch directory differs from `--cwd` (the normal sidecar-skill pattern), the OpenCode session is now
+  scoped to the project directory and the Electron Web-UI route is built from the **server-echoed**
+  session directory rather than a guessed one, so turn 2+ resolve correctly.
+- **Shared-server MCP sessions are scoped to the project directory** — every create and follow-up call
+  carries the directory, so headless MCP sessions are found on a server shared across projects.
+- **`amicus_read` surfaces the failure reason** for crashed / timed-out / aborted runs that wrote no
+  summary, instead of a bare "No summary available."
+- **`amicus_abort`'s "session not found"** now names the resolved project, matching `status` / `read`.
+- Internal: a single `canonicalProjectPath()` now normalizes project paths (slash direction, drive-letter
+  case, trailing slash, UNC shares) so creation and lookup always agree.
+
+## [1.6.0] - 2026-06-30
+
+Install resilience and council-failure correctness — the first two blocks of the post-1.5 backlog program.
+
+### Added
+- **Per-subcommand help.** `amicus <command> --help` now prints only that command's options instead of
+  the full global usage; bare `amicus --help` is unchanged.
+- **Zero-credit OpenRouter key warning at setup.** Setup now does a non-blocking `GET /api/v1/key`
+  check and warns when a key is free-tier or has no remaining credit, so a credit-less key is flagged
+  up front instead of 402-ing on the first paid model call.
+- **`amicus doctor` engine-recovery guidance.** The opencode-engine check now explains the
+  transient install-rollback failure mode and gives copy-paste recovery steps.
+- **Postinstall verifies the Electron binary.** When the optional Electron download/extract fails (or
+  AV quarantines the binary), the install now prints a clear non-fatal notice that headless runs and
+  the council still work — instead of silently leaving a broken GUI to discover later.
+- **CI tarball guard.** A new `check:tarball` step asserts every lifecycle-referenced script actually
+  ships in the published package, so a future packaging change can't silently drop it.
+- **README "Requirements & Dependencies" section** consolidating Node, git, OpenRouter credits, API-key
+  env vars, the optional Electron GUI, the bundled opencode engine, and OS support.
+
+### Fixed
+- **Council / headless runs no longer report success when every model call fails.** On the shared-server
+  MCP path, a run whose calls all errored (e.g. an OpenRouter 402) was finalized as `complete` with a
+  0-byte summary, so `amicus_status` showed success and the error was lost. Non-2xx/402 responses are
+  now detected at the OpenCode client boundary even when no assistant message is emitted, the
+  shared-server finalize routes through the same terminal-state classifier as the CLI, and a failed run
+  can never silently default to `complete`; `amicus_read` surfaces the failure reason.
+- **`amicus_status` elapsed time** is now bounded by the run's completed/aborted/crashed timestamp
+  instead of wall-clock-since-start, so a finished run reports its real duration.
+- **`amicus_setup` (MCP)** no longer claims an Electron window appeared when Electron is unavailable —
+  it pre-flights and returns an honest error directing you to the headless terminal wizard.
+- **Clearer "session not found"** — the message now names the resolved project so you know to pass the
+  original `project`.
+- **Non-fatal postinstall.** An internal skill-copy / MCP-registration failure no longer exits non-zero
+  and rolls back the entire global install; it warns and continues.
+- **`github:` install on Windows now runs identically to the registry install.** Removed the
+  consumer-facing `prepare` lifecycle that triggered npm's clone→prepare→nested-install→cached-pack
+  path (the rollback source); git hooks are still configured for contributors via `postinstall`.
+
 ## [1.5.1] - 2026-06-29
 
 A headless-reliability fix for reasoning-heavy models.

package/README.md

@@ -23,6 +23,7 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 
 - [What is Amicus](#what-is-amicus)
 - [Quick start](#quick-start)
+- [Requirements & Dependencies](#requirements--dependencies)
 - [The Council](#the-council)
 - [The parallel window](#the-parallel-window)
 - [Commands](#commands)
@@ -67,16 +68,6 @@ The postinstall step auto-configures everything — no manual registration:
 - Registers the **MCP server** in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
 - Installs **both skills** into `~/.claude/skills/` — `second-opinion` (the council) and `sidecar` (the chat skill).
 
-## Prerequisites & what it costs you
-
-Before your first run:
-
-- **Node.js ≥ 18** — `node --version` to check.
-- **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
-- **At least one paid model API key** — OpenRouter (covers the most models) or a direct Google / OpenAI / Anthropic / DeepSeek key. Add one with `amicus setup` or `amicus key <provider> <key>`.
-
-**What a run costs.** A sidecar is a single model call. A full council is typically **~5–8 paid model calls** (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with `--no-cost-gate`. You pay your providers directly for the tokens; Amicus itself is free and open-source.
-
 **Configure:**
 
 ```bash
@@ -110,18 +101,55 @@ A window opens alongside your editor with Gemini ready, pre-loaded with your con
 
 ### Install from GitHub
 
-The npm package is the primary path. To install straight from the repo instead (the postinstall runs identically — same MCP registration, same two skills):
+The npm package is the primary path. To install straight from the repo instead — the postinstall runs **identically** (same MCP registration, same two skills) — you just need `git` on your `PATH`:
 
 ```bash
 npm install -g github:BourbonDog/amicus
 ```
 
+See [Requirements & Dependencies](#requirements--dependencies) for the full prerequisite list.
+
 ### Contributor setup
 
 Cloning to develop Amicus? See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, git-hook wiring, and test commands.
 
 ---
 
+## Requirements & Dependencies
+
+Everything you need before your first run, and what's optional.
+
+**Runtime**
+
+- **Node.js ≥ 18** — `node --version` to check. This is the only hard runtime prerequisite.
+- **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
+
+**Install path & the git toolchain**
+
+- **From the npm registry (recommended):** `npm install -g amicus`. No build toolchain required — the package ships prebuilt.
+- **From GitHub:** `npm install -g github:BourbonDog/amicus` runs **identically** — same MCP registration, same two skills, same postinstall. The one extra requirement is a working **git** on your `PATH`, since npm clones the repo to install it (`git --version` to check).
+
+**Model API keys** — at least one is required
+
+- **OpenRouter** covers the most models with one key, or use a **direct Google / OpenAI / Anthropic / DeepSeek** key. Add one with `amicus setup` or `amicus key <provider> <key>`; keys live in `~/.config/amicus/.env`. The supported env vars are `OPENROUTER_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` (the legacy `GEMINI_API_KEY` is still accepted), `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `DEEPSEEK_API_KEY`.
+- ⚠️ **OpenRouter keys need purchased credits.** A brand-new, zero-credit key *passes* setup's live validation but then fails at runtime with a **402** on the first real call. Buy a small amount of credit before you run a council.
+
+**Electron — optional (GUI only)**
+
+- Electron is an **optional** dependency. It powers the graphical setup wizard and the parallel sidecar window. **Headless runs and the full council work without it** — if Electron is absent or can't open a window, `amicus setup` falls back to a readline wizard and sidecars run headless. `amicus doctor` reports Electron's presence accurately and never treats its absence as fatal.
+
+**The OpenCode engine**
+
+- The bundled **`opencode-ai`** engine (the conversation runtime) installs automatically as a normal dependency — you don't install it separately. Its own postinstall lays down ~11 per-platform binaries; a **transient** failure there (a spawn `ENOENT`, or an antivirus file-lock) can roll back the atomic install. If install fails partway or `amicus doctor` reports the OpenCode binary "not found", just **re-run** `npm install -g amicus` (clear the cache first if it persists: `npm cache clean --force`).
+
+**OS support**
+
+- **Windows 11, macOS, and Linux** are all supported; Amicus is first-class on **Windows** (developed and tested there, no WSL required). See the [Windows](#windows) section for platform specifics.
+
+**What a run costs.** A sidecar is a single model call. A full council is typically **~5–8 paid model calls** (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with `--no-cost-gate`. You pay your providers directly for the tokens; Amicus itself is free and open-source.
+
+---
+
 ## The Council
 
 **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.
@@ -442,6 +470,7 @@ Most Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.
 |---------|--------------|-----|
 | "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). |
+| 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. |
 | Session not found | No session matches the given ID | Run `amicus list`, or omit `--session-id` to use the most recent. |
 | No conversation history found | Project-path encoding | Check `~/.claude/projects/`; `/` and `_` in the project path are encoded as `-` in the directory name. |

package/bin/amicus.js

@@ -75,9 +75,10 @@ async function main() {
     process.exit(0);
   }
 
-  // Handle --help or no command
+  // Handle --help or no command. 'amicus <cmd> --help' scopes the usage to that
+  // subcommand; bare 'amicus --help' (or no command) prints the full usage.
   if (args.help || args._.length === 0) {
-    console.log(getUsage());
+    console.log(getUsage(args.help ? command : undefined));
     process.exit(0);
   }
 

package/electron/main.js

@@ -21,6 +21,7 @@ const { createFoldHandler } = require('./fold');
 const { registerSetupHandlers } = require('./ipc-setup');
 const { computeWindowPosition } = require('./window-position');
 const { attachLoadFailsafe, buildLoadErrorHTML } = require('./load-failsafe');
+const { buildSessionRoute } = require('./session-route');
 
 const ICON_PATH = path.join(__dirname, 'assets', 'icon.png');
 
@@ -51,6 +52,11 @@ const MODE = getCompatEnv('MODE') || 'sidecar';
 const TASK_ID = getCompatEnv('TASK_ID') || 'unknown';
 const MODEL = getCompatEnv('MODEL') || 'unknown';
 const CWD = getCompatEnv('CWD') || process.cwd();
+// The directory the OpenCode session was actually scoped to (#45). Set by the
+// interactive launcher as canonicalProjectPath(--cwd) so the Web-UI route is
+// built from the SAME directory createSession used. Falls back to CWD for
+// back-compat with launchers that predate this env var.
+const SESSION_DIRECTORY = getCompatEnv('SESSION_DIRECTORY') || CWD;
 const CLIENT = getCompatEnv('CLIENT') || 'code-local';
 const OPENCODE_PORT = parseInt(getCompatEnv('OPENCODE_PORT') || '4096', 10);
 const OPENCODE_SESSION_ID = getCompatEnv('SESSION_ID');
@@ -152,10 +158,10 @@ function createAmicusWindow() {
   });
 
   // Navigate directly to the session URL to bypass the project selection screen.
-  // OpenCode's router format: /<base64url(projectPath)>/session/<sessionId>
-  const contentUrl = OPENCODE_SESSION_ID
-    ? `${OPENCODE_URL}/${Buffer.from(CWD).toString('base64url')}/session/${OPENCODE_SESSION_ID}`
-    : OPENCODE_URL;
+  // Build the route from SESSION_DIRECTORY — the directory the session was
+  // actually scoped to — NOT a fresh base64url(CWD) guess, so Web-UI follow-up
+  // prompts resolve the session even when process cwd != --cwd (#45).
+  const contentUrl = buildSessionRoute(OPENCODE_URL, OPENCODE_SESSION_ID, SESSION_DIRECTORY);
 
   // The window only becomes visible on the success path below. Without this
   // failsafe, a failed/stalled UI load leaves an invisible window and a

package/electron/session-route.js

@@ -0,0 +1,28 @@
+/**
+ * Web-UI session route builder (#45).
+ *
+ * OpenCode's router format is `/<base64url(projectPath)>/session/<sessionId>`.
+ * The route MUST be built from the directory the OpenCode session was actually
+ * created/scoped to — NOT a fresh base64url(process.cwd()) guess. When the
+ * amicus process cwd != --cwd (the normal sidecar-skill launch), a CWD-derived
+ * route points at a project route with no matching session, so Web-UI follow-up
+ * prompts fail "unable to retrieve session". The caller passes the same
+ * directory it used to scope createSession (the server-echoed session.directory,
+ * or a consistent canonicalProjectPath(--cwd) fallback).
+ *
+ * Pure function: no electron, no fs, no process state. Safe to unit-test.
+ *
+ * @param {string} baseUrl - OpenCode server base URL (e.g. http://localhost:4096)
+ * @param {string} [sessionId] - OpenCode session id; falsy → return baseUrl only
+ * @param {string} sessionDirectory - The directory the session is scoped to
+ * @returns {string} Fully-qualified route URL, or baseUrl when no session id.
+ */
+function buildSessionRoute(baseUrl, sessionId, sessionDirectory) {
+  if (!sessionId) {
+    return baseUrl;
+  }
+  const seg = Buffer.from(sessionDirectory).toString('base64url');
+  return `${baseUrl}/${seg}/session/${sessionId}`;
+}
+
+module.exports = { buildSessionRoute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.5.1",
+  "version": "1.6.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",
@@ -63,9 +63,10 @@
     "generate-docs": "node scripts/generate-docs.js",
     "generate-docs:check": "node scripts/generate-docs.js --check",
     "validate-docs": "node scripts/validate-docs.js --full",
-    "prepare": "node scripts/setup-hooks.js",
+    "setup-hooks": "node scripts/setup-hooks.js",
     "check:secrets": "node scripts/check-secrets.js --all",
-    "check:sizes": "node scripts/check-file-sizes.js --all"
+    "check:sizes": "node scripts/check-file-sizes.js --all",
+    "check:tarball": "node scripts/check-tarball-lifecycle.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",

package/scripts/postinstall.js

@@ -13,6 +13,8 @@ const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 
+const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
+
 const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'sidecar', 'SKILL.md');
 const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
 
@@ -172,6 +174,79 @@ function registerClaudeDesktop() {
   addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
 }
 
+/**
+ * Resolve the Electron binary path the same way src/sidecar/interactive.js
+ * getElectronPath() does: require('electron') returns the absolute path to the
+ * binary (or throws if the optionalDependency never installed/extracted).
+ * @returns {string|null} Path to the Electron binary, or null if unresolvable.
+ */
+function resolveElectron() {
+  try {
+    return require('electron');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * NON-FATAL verification that the OPTIONAL electron binary actually extracted.
+ * Electron is an optionalDependency: npm exits 0 even if its download/extract
+ * fails (or AV quarantines electron.exe), so without this the user only finds
+ * out the GUI is broken much later. Warn clearly that headless runs + the
+ * council still work, and point at `amicus doctor` / reinstall to get the GUI.
+ *
+ * This MUST never throw out of postinstall — the whole body is guarded so a
+ * resolver failure or a missing fs can never turn into a non-zero exit.
+ *
+ * @param {object} deps - { resolveElectron } override for testing.
+ */
+function verifyElectron(deps = {}) {
+  try {
+    const _resolve = deps.resolveElectron || resolveElectron;
+    const binPath = _resolve();
+    if (binPath && fs.existsSync(binPath)) { return; }
+    console.warn('[amicus] Warning: the Electron binary did not install — the interactive GUI / setup-wizard is unavailable.');
+    console.warn('[amicus] Headless runs and the council still work. Run `amicus doctor` to check, or `npm install -g amicus` to reinstall and add the GUI.');
+  } catch {
+    // Never let the electron check throw out of postinstall.
+  }
+}
+
+/**
+ * Configure git hooks for DEVELOPERS, folded into postinstall (#35).
+ *
+ * Previously this ran via npm's "prepare" lifecycle. But "prepare" also fires
+ * on the github: install path (`npm install -g github:BourbonDog/amicus`),
+ * where npm clones the repo, runs prepare, does a NESTED devDependency install,
+ * and re-packs — a fragile pipeline the registry install SKIPS entirely. That
+ * divergence (plus a reusable corrupt cached artifact) is what made github:
+ * installs roll back, especially on Windows. Removing the consumer-facing
+ * prepare lifecycle makes the github: path behave identically to the registry
+ * path.
+ *
+ * Hook setup still needs to happen for devs, so we run setup-hooks.js here.
+ * It is a no-op for consumers: setup-hooks.js exits 0 outside a git checkout
+ * (the published tarball / github: export has no .git), so this changes
+ * nothing for end users while keeping `npm install` wiring hooks for devs.
+ *
+ * Best-effort and self-contained: never throws (a hook-setup failure must
+ * never roll back the install), so it is safe to call before the optional
+ * skill/MCP setup.
+ *
+ * @param {object} deps - { env } override for testing.
+ */
+function setupHooks(deps = {}) {
+  try {
+    execFileSync('node', [SETUP_HOOKS_SCRIPT], {
+      stdio: 'inherit',
+      env: deps.env || process.env,
+    });
+  } catch (err) {
+    // Hook setup is for devs only and must never fail the install.
+    console.warn(`[amicus] Warning: could not configure git hooks: ${err && err.message}`);
+  }
+}
+
 function main(deps = {}) {
   if (process.env.AMICUS_SKIP_POSTINSTALL === '1') {
     console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup (plugin channel handles registration).');
@@ -181,22 +256,47 @@ function main(deps = {}) {
   const _installCouncilSkill = deps.installCouncilSkill || installCouncilSkill;
   const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
   const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
+  const _setupHooks = deps.setupHooks || setupHooks;
 
   console.log('[amicus] Installing...');
+  // Dev-only: configure git hooks (no-op for consumers). Folded in from the
+  // removed "prepare" lifecycle (#35) so github: installs run identically.
+  _setupHooks();
   _installSkill();
   _installCouncilSkill();
   _registerClaudeCode();
   _registerClaudeDesktop();
 
+  // Non-fatal: warn (only) if the optional Electron binary failed to extract.
+  verifyElectron(deps);
+
   console.log('');
   console.log('[amicus] Setup:');
   console.log('  - Configure API: Run `amicus setup` or set API keys directly');
   console.log('  - API keys: OPENROUTER_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENAI_API_KEY, etc.');
 }
 
-// Only run main when executed directly (not when required for testing)
+/**
+ * Top-level entry point. Wraps main() so a failure is never fatal: npm treats
+ * a non-zero postinstall as a reason to roll back / uninstall the ENTIRE global
+ * package, but skill-copy + MCP registration are optional — amicus itself still
+ * works without them. Warn clearly and exit 0 (mirrors scripts/setup-hooks.js).
+ */
+function runCli(deps = {}) {
+  try {
+    main(deps);
+  } catch (err) {
+    console.warn(`[amicus] Warning: optional post-install setup failed: ${err && err.message}`);
+    console.warn('[amicus] Skill install + MCP registration are optional — amicus itself still works.');
+    console.warn('[amicus] Run `amicus doctor` to check setup, or re-register manually later.');
+  }
+  // Always exit 0 so a failure here never rolls back the global install.
+  process.exit(0);
+}
+
+// Only run when executed directly (not when required for testing)
 if (require.main === module) {
-  main();
+  runCli();
 }
 
-module.exports = { main, addMcpToConfigFile, installSkill, installCouncilSkill, COUNCIL_FILES };
+module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, verifyElectron, resolveElectron, COUNCIL_FILES };

package/scripts/setup-hooks.js

@@ -12,10 +12,14 @@
  * core.hooksPath at it makes hooks fire in the main clone and in every
  * worktree with no per-worktree setup.
  *
- * Runs automatically via npm's "prepare" lifecycle. If you install with
- * --ignore-scripts (recommended for this repo), run it once by hand:
+ * Runs automatically via the postinstall flow (scripts/postinstall.js) so a
+ * fresh dev `npm install` still wires hooks. It is NOT a "prepare" script:
+ * prepare also fires on the github: install path, where it triggers a nested
+ * devDependency install + re-pack that the registry path skips (#35) — the
+ * source of the Windows github: rollback. If you install with --ignore-scripts
+ * (recommended for this repo), run it once by hand:
  *
- *   node scripts/setup-hooks.js
+ *   npm run setup-hooks      # or: node scripts/setup-hooks.js
  *
  * Safe to run anywhere: exits 0 outside a git checkout (npm tarball
  * installs, exported archives) and never fails the install.

package/src/cli-handlers-doctor.js

@@ -105,7 +105,7 @@ function runDoctorChecks(depsOverride = {}) {
   checks.push(guard('opencode-bin', 'OpenCode binary', () => (
     d.hasOpencodeBinary()
       ? { id: 'opencode-bin', name: 'OpenCode binary', status: 'ok', message: 'found', hint: null }
-      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: 'npm install -g amicus' }
+      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: 'npm install -g amicus  (a transient install error can roll back the engine binaries — re-run, or: npm cache clean --force && npm install -g amicus)' }
   )));
 
   checks.push(guard('electron', 'Electron (interactive GUI)', () => (

package/src/cli.js

@@ -292,10 +292,15 @@ function isValidDurationFormat(duration) {
 }
 
 /**
- * Get usage text
+ * Usage text, split into composable parts so 'amicus <cmd> --help' can print
+ * only the relevant block while bare 'amicus --help' still composes the full
+ * text byte-identically.
+ *
+ * Each value is a section of the original monolithic template; concatenating
+ * USAGE_HEADER + every USAGE_COMMAND_BLOCKS value (in insertion order) +
+ * USAGE_TRAILER reproduces the original string exactly.
  */
-function getUsage() {
-  return `
+const USAGE_HEADER = `
 Usage: amicus <command> [options]
 
 Commands:
@@ -320,7 +325,12 @@ Commands:
     (no args)                List all configured providers
   update      Update to latest version
   mcp         Start MCP server (stdio transport)
+`;
 
+// Per-command option blocks, keyed by the invoked subcommand. Insertion order
+// must match the original template so the composed full usage is unchanged.
+const USAGE_COMMAND_BLOCKS = {
+  start: `
 Options for 'start':
   --model <model>              Optional (uses config default). Model to use:
                                - Short aliases: gemini, opus, gpt (see 'amicus setup')
@@ -354,7 +364,8 @@ Options for 'start':
   --validate-model             (Deprecated: validation is on by default)
   --no-validate-model          Skip model-catalog validation before launch
   --position <pos>             Window position: right (default), left, center
-
+`,
+  fanout: `
 Options for 'fanout':
   --models <a,b,c>             Required. Comma-separated aliases or provider/model IDs
   --council <name>             Run a saved council instead of --models (e.g. free). Mutually exclusive with --models
@@ -369,27 +380,84 @@ Options for 'fanout':
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
-
+`,
+  models: `
 Options for 'models':
   --search <q>                 Filter by substring over model id and name
   --refresh                    Force-refresh the catalog from provider APIs
   --check                      Audit aliases against the catalog (exit = stale count)
   --json                       Machine-readable output
-
+`,
+  list: `
 Options for 'list':
   --status <filter>            Filter by status (running, complete)
   --all                        Show all projects
   --json                       Output as JSON
-
+`,
+  abort: `
 Options for 'abort':
   --all                        Abort all running sessions in this project
-
+`,
+  read: `
 Options for 'read':
   --summary                    Show summary (default)
   --conversation               Show full conversation
   --metadata                   Show session metadata
   --json                       Emit the run/wave result as stable JSON
+`,
+  continue: `
+Options for 'continue':
+  <task_id>                    Required. Session to build on (positional)
+  --prompt <text>              Required. Briefing for the new session
+  --model <model>              Optional. Override the model (alias or provider/model)
+  --cwd <path>                 Project directory (default: cwd)
+  --no-ui                      Run without GUI (autonomous mode)
+  --timeout <minutes>          Headless timeout (default: 15)
+  --context-turns <N>          Max conversation turns (default: 50)
+  --context-max-tokens <N>     Max context tokens (default: 80000)
+`,
+  resume: `
+Options for 'resume':
+  <task_id>                    Required. Session to reopen (positional)
+  --cwd <path>                 Project directory (default: cwd)
+  --no-ui                      Run without GUI (autonomous mode)
+  --timeout <minutes>          Headless timeout (default: 15)
+`,
+  council: `
+Subcommands for 'council':
+  tally <input.json>           Tally findings → tiers/street-cred (appends to ledger)
+    --no-ledger                Compute the record without appending to the ledger
+    --json                     Machine-readable output
+  stats                        Reviewer-reliability aggregates from the ledger
+    --json                     Machine-readable output
+  report <verdict.json>        Disagreement + verdict report
+    --wave <wave.json>         Include per-leg run stats from a wave file
+    --md                       Emit Markdown (default)
+    --html                     Emit a self-contained HTML page
+`,
+  doctor: `
+Options for 'doctor':
+  --json                       Machine-readable output
+`,
+  setup: `
+Options for 'setup':
+  (no args)                    Run the interactive setup wizard
+  --api-keys                   Open the API key setup window
+  --add-alias <name=model>     Add a model alias without the full wizard
+`,
+  key: `
+Usage for 'key':
+  key <provider> <apikey>      Validate and save a key
+  key <provider> --remove      Remove a saved key
+  key                          List all configured providers
+`,
+  mcp: `
+Usage for 'mcp':
+  mcp                          Start the MCP server (stdio transport)
+`
+};
 
+const USAGE_TRAILER = `
 OpenCode Agent Types:
     Chat       Reads auto, writes/bash ask permission (interactive default)
     Build      Full tool access (headless default)
@@ -409,6 +477,25 @@ Examples:
   amicus resume abc123
   amicus read abc123 --conversation
 `;
+
+/**
+ * Get usage text.
+ *
+ * @param {string} [command] When provided AND it has a dedicated options block,
+ *   returns the top-level header plus only that command's block (scoped --help).
+ *   When omitted, or when the command has no dedicated block, returns the full
+ *   composed usage (byte-identical to the original monolithic string).
+ */
+function getUsage(command) {
+  // Each part carries its own leading/trailing newlines exactly as they sat in
+  // the original single template literal, so plain concatenation reproduces the
+  // blank-line separators (the header's trailing "\n" + a block's leading "\n"
+  // form the blank line between them). Scoped help keeps the header + trailer
+  // and substitutes just the one command's block in place of all blocks.
+  const block = command && Object.prototype.hasOwnProperty.call(USAGE_COMMAND_BLOCKS, command)
+    ? USAGE_COMMAND_BLOCKS[command]
+    : Object.values(USAGE_COMMAND_BLOCKS).join('');
+  return USAGE_HEADER + block + USAGE_TRAILER;
 }
 
 module.exports = {