amicus 4.5.2 → 4.5.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "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

@@ -3,6 +3,60 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.5.4] - 2026-08-01
+
+### Fixed
+
+- **README: corrected a false claim about Electron and install channels.** The install section
+  said "the standalone Electron window is npm-only." That is not true — the Council Workspace
+  auto-open gate (`src/sidecar/workspace-auto-open.js`) keys on `client === 'code-local'` plus
+  Electron presence, **not** on install channel, so a plugin-channel user in Claude Code local
+  does get the window. Removed.
+
+### Changed
+
+- **README now leads with npm as the recommended install**, with a per-channel comparison table.
+  The accurate reason npm is preferable for the interactive experience: the plugin's MCP config
+  sets `AMICUS_SKIP_POSTINSTALL=1`, and `scripts/postinstall.js` returns early on that — *before*
+  `provisionElectron()`. So the plugin channel gets no `amicus` on `PATH` (every window-opening
+  command becomes an `npx` call), no Electron provisioning or cache-heal, no reachable
+  `amicus doctor --fix` when the GUI breaks, and a fresh npx cache directory on every release.
+  The plugin block keeps its genuine strengths — native registration and the slash commands the
+  npm paths don't have — alongside an accurate statement of the tradeoff.
+- **README documents the single-MCP-registration behavior** when both channels are installed.
+  Config, API keys, and session history are shared, but the MCP server is one registration named
+  `amicus` that resolves to whichever install registered most recently — so the copy the CLI runs
+  and the copy Claude's MCP tools run can differ. This is the #76 confusion; `amicus doctor`
+  reports the MCP launch path and `--fix` repairs that copy in place.
+
+## [4.5.3] - 2026-08-01
+
+### Fixed
+
+- **Unknown CLI flags are rejected instead of silently absorbed.** `parseArgs` treated any
+  `--token` as a flag: an unrecognized one landed on the parsed args object, no handler read it,
+  and the command ran as though it were never typed. Found while smoke-testing v4.5.2 —
+  `amicus start -m deepseek --prompt "…" --headless` printed no error and exited 0, but `start`
+  has no `--headless`; the run silently took the **interactive** path, ignored `-m`, and left a
+  session running against the default model. A typo (`--modl`), a flag borrowed from another
+  command, or an invented one all behaved the same way, and an unknown flag followed by a
+  positional would swallow it as its value. Unknown flags now get the same treatment amicus
+  already gave an unknown *command*: name it, suggest the nearest real flag, point at `--help`,
+  exit 1. The known-flag set is **derived from the usage text** (the same source `getCommandNames()`
+  uses, for the same anti-rot reason) plus the boolean-flag list, plus a small explicitly-documented
+  allowlist of internal MCP→CLI passthroughs (`--task-id`, `--run-id`, `--council-name`,
+  `--cowork-process`) and undocumented-but-working flags (`--briefing`, `--mode`, `--quiet`).
+  A regression test asserts every `args.<flag>` any CLI handler reads is in the known set, so the
+  check can never silently start rejecting a flag that works.
+
+### Changed
+
+- **README Quick start is now four numbered steps**, with **Configure** promoted from a bold line
+  buried between two callouts to its own step and TOC entry. Installing without configuring is the
+  step people skip, and every council fails at the first model call when they do — so it now says
+  so plainly, notes that one OpenRouter key is enough to start, and ends with `amicus doctor` as
+  the confirmation that setup actually took.
+
 ## [4.5.2] - 2026-07-31
 
 ### Fixed

package/README.md

@@ -29,6 +29,10 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 - [The Council](#the-council)
 - [Ways to run the council](#ways-to-run-the-council)
 - [Quick start](#quick-start)
+  - [1. Install](#1-install)
+  - [**2. Configure — don't skip this**](#2-configure--dont-skip-this)
+  - [3. Your first council](#3-your-first-council)
+  - [4. Your first sidecar](#4-your-first-sidecar)
 - [Requirements & Dependencies](#requirements--dependencies)
 - [The parallel window](#the-parallel-window)
 - [Commands](#commands)
@@ -165,24 +169,40 @@ Any flag you also type on that second line overrides just that value — a pack
 
 > **Two install channels — read this first.** Amicus ships two ways, and CLI commands look different in each:
 >
-> - **npm global** (`npm install -g amicus` or the install script) puts `amicus`/`am` on your `PATH`. Every `amicus <command>` example in this README works as written.
+> - **npm global** (`npm install -g amicus` or the install script) — **the recommended path.** Puts `amicus`/`am` on your `PATH`, so every `amicus <command>` example in this README works as written, and provisions the Electron GUI that the parallel window runs in.
 > - **Claude Code plugin** (`/plugin install amicus@bourbondog-amicus`) does **not** put a CLI on your `PATH`. CLI calls go through `npx -y amicus@latest <command>` instead — e.g. `amicus doctor` becomes `npx -y amicus@latest doctor`. In exchange, the plugin channel gets two things npm does **not**: the slash commands `/amicus:council` and `/amicus:sidecar`. **These are plugin-channel-ONLY — npm users don't get them** and drive the same skills by saying "council review this" / talking to Claude instead.
 >
+> See the [comparison table below](#1-install) for the full tradeoff — the short version is that npm is what you want for the interactive window, and the two can be installed side by side.
+>
 > **Convention used throughout this README:** plugin-channel users: prefix CLI examples with `npx -y amicus@latest` (skip the bare `amicus`/`am`). Individual code blocks are not duplicated per channel — this note is the one translation you need.
 
-**Install** — pick whichever fits. Every path delivers the MCP server and both skills; the `amicus`/`am` CLI lands on your PATH with the **npm and install-script paths** (the plugin path runs the CLI on demand via `npx -y amicus@latest <command>`):
+### 1. Install
 
-**As a Claude Code plugin** — the most native path if you use Claude Code:
+Every path delivers the MCP server and both skills. They differ in what else you get:
 
-```text
-/plugin marketplace add BourbonDog/amicus
-/plugin install amicus@bourbondog-amicus
-/reload-plugins
+| | **npm / install script** | **Claude Code plugin** |
+|---|---|---|
+| `amicus` / `am` on your `PATH` | ✅ | ❌ — every call is `npx -y amicus@latest <command>` |
+| **Interactive Electron window** (`amicus start`, `watch --ui`) | ✅ provisioned at install | ⚠️ best-effort — see below |
+| Self-heal when the GUI breaks (`amicus doctor --fix`) | ✅ | ❌ no CLI to run it with |
+| MCP server + both skills | ✅ | ✅ |
+| Slash commands `/amicus:council`, `/amicus:sidecar` | ❌ | ✅ |
+
+---
+
+#### With npm — recommended
+
+The canonical path, and the one that gets you the full interactive experience (needs [Node.js](https://nodejs.org) ≥ 18):
+
+```bash
+npm install -g amicus
 ```
 
-Claude Code registers the MCP server and both skills for you — nothing to configure. It also gets you two slash commands the npm/install-script paths don't: **`/amicus:council`** (run a full council review) and **`/amicus:sidecar`** (fork a conversation to another model). (The plugin does not put `amicus` on your PATH — CLI calls go through `npx -y amicus@latest <command>`; the standalone Electron window is npm-only; and the first council/sidecar call downloads the OpenCode engine.)
+This is the path to pick unless you specifically want the plugin's slash commands. It puts `amicus`/`am` on your `PATH` — which is what the **parallel window** is driven by — and its postinstall provisions the Electron GUI, with `amicus doctor --fix` to repair it in place if anything goes wrong later.
+
+#### With the install script
 
-**With the install script** — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
+Same result as npm, one command — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
 
 ```bash
 # macOS / Linux
@@ -194,12 +214,26 @@ curl -fsSL https://raw.githubusercontent.com/BourbonDog/amicus/main/install.sh |
 irm https://raw.githubusercontent.com/BourbonDog/amicus/main/install.ps1 | iex
 ```
 
-**With npm** — the canonical path (needs [Node.js](https://nodejs.org) ≥ 18):
+#### As a Claude Code plugin
 
-```bash
-npm install -g amicus
+The most native *registration* path if you use Claude Code, and the only one with slash commands:
+
+```text
+/plugin marketplace add BourbonDog/amicus
+/plugin install amicus@bourbondog-amicus
+/reload-plugins
 ```
 
+Claude Code registers the MCP server and both skills for you — nothing to configure. You also get **`/amicus:council`** (run a full council review) and **`/amicus:sidecar`** (fork a conversation to another model), which the npm paths don't have.
+
+> **Know the tradeoff before you pick this.** The plugin does not put `amicus` on your `PATH`, so every CLI call goes through `npx -y amicus@latest <command>` — including the ones that open the interactive window. It also skips amicus's postinstall, which is what provisions and self-heals the Electron GUI. The window still works when Electron lands in the npx cache, and the Council Workspace still auto-opens on a council run from Claude Code — but nothing repairs it when Electron *doesn't* land, and each new release re-resolves into a fresh cache directory. **If you want the parallel window as a daily driver, install with npm.**
+>
+> (Also: the first council/sidecar call downloads the OpenCode engine.)
+
+**Running both is supported** — and is what you want if you like the slash commands *and* the window. Install with npm for the CLI and the GUI, then add the plugin for `/amicus:council`. Your config, API keys, and session history live outside either install and are shared automatically.
+
+> One thing to know if you do: the MCP server is a **single registration named `amicus`**, so it resolves to one install — whichever registered most recently, which is usually the plugin's `npx -y amicus@latest mcp`. That's harmless (both serve the same tools), but it means the copy your CLI runs and the copy Claude's MCP tools run can differ. `amicus doctor` reports the MCP launch path explicitly and `--fix` repairs that copy in place, so if a GUI or engine problem ever shows up in Claude but not in your terminal, that's the first thing to check.
+
 For the **npm** and **install-script** paths, a postinstall auto-configures everything — no manual registration:
 
 - Registers the **MCP server** in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
@@ -207,7 +241,15 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 
 > **Skipped the postinstall?** `--ignore-scripts` npm installs never run it, and the plugin channel skips it by design (Claude Code registers the plugin's MCP server and skills itself). Either way, run `amicus init` (plugin channel: `npx -y amicus@latest init`) any time to (re)register on demand — e.g. to also wire up Claude Desktop, which the plugin path doesn't touch. See [`amicus init`](./docs/usage.md#amicus-init).
 
-**Configure:**
+---
+
+### 2. Configure — don't skip this
+
+> ### ⚠️ Installing is not enough. Run this or nothing will work.
+>
+> Amicus has **no API keys of its own** — it drives *your* accounts at OpenRouter, Google,
+> OpenAI, Anthropic, or DeepSeek. Until you add at least one key, every council and every
+> sidecar fails at the first model call. **This is the step people skip.**
 
 ```bash
 amicus setup
@@ -215,6 +257,10 @@ amicus setup
 npx -y amicus@latest setup
 ```
 
+**One key is enough to start.** [OpenRouter](https://openrouter.ai/keys) is the usual choice —
+a single key reaches every model in the catalog, which is what makes a mixed-vendor council
+work without four separate accounts.
+
 This opens a graphical wizard:
 
 | Step | What it does |
@@ -226,7 +272,20 @@ This opens a graphical wizard:
 
 > **Headless environments:** if Electron can't open a window, the wizard falls back to a readline-based setup in the terminal.
 
-**Your first council** — no flags to learn. In Claude Code or Cowork, give Claude a document and say:
+**Confirm it took** — this is the fastest way to know you're actually ready:
+
+```bash
+amicus doctor
+```
+
+Green across the board (`0 error(s)`) means keys, catalog, engine, skills, and MCP registration
+are all in place. Anything red, `amicus doctor` tells you exactly what to run next.
+
+---
+
+### 3. Your first council
+
+No flags to learn. In Claude Code or Cowork, give Claude a document and say:
 
 > *council review this*
 
@@ -234,7 +293,9 @@ Plugin-channel users can also type **`/amicus:council`** directly instead of phr
 
 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:
+### 4. 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:
 
 ```bash
 amicus start --model gemini --prompt "Fact-check the auth approach Claude just proposed"
@@ -380,7 +441,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -22,6 +22,7 @@ const { handleStart, handleFanout, handleRead } = require('../src/cli-handlers-r
 const { handleResume, handleContinue } = require('../src/cli-handlers-resume-continue');
 const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
 const { suggestCommand } = require('../src/utils/input-validators');
+const { unknownFlags, getKnownFlags } = require('../src/utils/known-flags');
 const { logger } = require('../src/utils/logger');
 
 const VERSION = require('../package.json').version;
@@ -30,6 +31,28 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const command = args._[0];
 
+  // Reject unknown flags BEFORE anything can act on a half-understood command
+  // line. parseArgs accepts any `--token`, so an unrecognized one used to land
+  // on `args`, go unread, and let the command run as though it were never typed
+  // — `start … --headless` silently took the interactive path, ignored `--model`
+  // and left a session running. Same treatment as an unknown command: name it,
+  // suggest the nearest real flag, point at help, exit 1. See
+  // src/utils/known-flags.js for what counts as known and why.
+  const badFlags = unknownFlags(args);
+  if (badFlags.length > 0) {
+    for (const flag of badFlags) {
+      console.error(`Unknown option: --${flag}`);
+      const candidates = suggestCommand(flag, [...getKnownFlags()]);
+      if (candidates.length > 0) {
+        console.error(`Did you mean: ${candidates.map(c => `--${c}`).join(', ')}`);
+      }
+    }
+    console.error(command
+      ? `Run \`amicus ${command} --help\` to see valid options.`
+      : 'Run `amicus --help` to see valid options.');
+    process.exit(1);
+  }
+
   // Install crash handler for MCP-spawned processes (have --task-id)
   if (args['task-id'] && (command === 'start' || command === 'continue')) {
     const { installCrashHandler } = require('../src/sidecar/crash-handler');

package/docs/usage.md

@@ -443,7 +443,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.2",
+  "version": "4.5.4",
   "mcpName": "io.github.BourbonDog/amicus",
   "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": [

package/src/cli.js

@@ -122,10 +122,12 @@ function parseArgs(argv) {
 }
 
 /**
- * Check if a flag is boolean (doesn't take a value)
+ * Flags that take no value. Module-level (not rebuilt per call) so
+ * `getBooleanFlags()` can hand the same list to src/utils/known-flags.js —
+ * which needs it to tell a real boolean flag from an unknown token, and must
+ * not keep a second copy that can rot out of sync with this one.
  */
-function isBooleanFlag(key) {
-   const booleanFlags = [
+const BOOLEAN_FLAGS = [
      'no-ui',
      'no-mcp',
      'no-context',
@@ -156,8 +158,21 @@ function isBooleanFlag(key) {
      'ui',                   // watch: open the Council Workspace window; v4.4 seam (v4.3 Task 11)
      'follow',               // fanout / council run: stream this run's own events to stderr (v4.3 Task 13)
      'fallback',             // fanout / council run: opt-in cheaper-model substitution (v4.3 Task 18, spec 6.2); --no-fallback negates via the generic no-* catch-all below
-   ];
-  return booleanFlags.includes(key);
+];
+
+/**
+ * Check if a flag is boolean (doesn't take a value)
+ */
+function isBooleanFlag(key) {
+  return BOOLEAN_FLAGS.includes(key);
+}
+
+/**
+ * The boolean-flag names, for the unknown-flag check.
+ * @returns {string[]} copy — callers must not mutate the source list
+ */
+function getBooleanFlags() {
+  return [...BOOLEAN_FLAGS];
 }
 
 /**
@@ -765,5 +780,6 @@ module.exports = {
   validateStartArgs,
   getUsage,
   getCommandNames,
+  getBooleanFlags,
   DEFAULTS
 };

package/src/utils/known-flags.js

@@ -0,0 +1,90 @@
+// src/utils/known-flags.js
+'use strict';
+
+/**
+ * @module utils/known-flags
+ * The set of `--flags` amicus accepts, and the check that rejects the rest.
+ *
+ * WHY THIS EXISTS. `parseArgs` (src/cli.js) treats ANY `--token` as a flag: an
+ * unrecognized one lands on the parsed object, no handler reads it, and the
+ * command proceeds as if it were never typed. Found in the field while smoke-
+ * testing v4.5.2 — `amicus start -m deepseek --prompt "…" --headless` printed no
+ * error and exited 0, but `start` has no `--headless`. The run silently took the
+ * INTERACTIVE path, ignored `-m`, and left a session running against the default
+ * model. A typo (`--modl`), a flag borrowed from another command, or an invented
+ * one all behave the same way, and an unknown flag followed by a positional
+ * SWALLOWS it as its value.
+ *
+ * amicus already handles an unknown COMMAND correctly — error, "Did you mean",
+ * usage, exit 1. This gives flags the same treatment.
+ *
+ * DERIVED, NOT HAND-MAINTAINED. The bulk of the set is scraped from the usage
+ * text, which is the same source `getCommandNames()` uses and for the same
+ * stated reason: a second hand-maintained list would rot out of sync with the
+ * first. Only flags that are deliberately absent from usage are listed here, and
+ * each says why.
+ */
+
+/**
+ * Real flags that appear in NO usage block. Rejecting any of these would break
+ * working callers, so they are enumerated deliberately rather than derived.
+ *
+ * ⚠️ The first four are spawned by the MCP server onto its own CLI children
+ * (src/mcp-server.js, src/mcp-council-run.js). They are not user-facing and are
+ * intentionally undocumented — but they are on the argv of every MCP-launched
+ * run, so rejecting them would break the entire MCP surface.
+ */
+const INTERNAL_FLAGS = new Set([
+  'task-id',         // MCP → `start`/`continue`: pins the child's task id
+  'run-id',          // MCP → `council run`: pins the child's run id
+  'council-name',    // MCP → `council run`: preset name for ledger attribution
+  'cowork-process',  // MCP → `start`: Cowork process handle for context capture
+
+  // User-facing but undocumented, and read by real handlers today. Listed so the
+  // rejection is a bug fix and not a silent removal of working behaviour; if any
+  // of these should be dropped, that is a separate, deliberate change.
+  'briefing',        // src/cli-handlers-resume-continue.js — alias for --prompt
+  'mode',            // src/cli-handlers-run.js — legacy alias for --agent
+  'quiet',           // src/cli-handlers.js — suppresses the interactive prompt
+  'help',            // handled before dispatch; never reaches a usage block body
+]);
+
+/**
+ * Every flag amicus accepts: usage-derived ∪ boolean flags ∪ INTERNAL_FLAGS.
+ *
+ * Computed on each call rather than cached at module load, because `getUsage()`
+ * is itself composed at call time and a cached copy would pin whatever the first
+ * caller happened to see.
+ *
+ * @returns {Set<string>} kebab-case flag names, without the leading `--`
+ */
+function getKnownFlags() {
+  // Required lazily: src/cli.js is the module that will consume this one, and a
+  // top-level require here would close a cycle.
+  const { getUsage, getBooleanFlags } = require('../cli');
+  const known = new Set(INTERNAL_FLAGS);
+  for (const m of getUsage().matchAll(/--([a-z][a-z0-9-]*)/gi)) {
+    known.add(m[1].toLowerCase());
+  }
+  for (const f of getBooleanFlags()) { known.add(f); }
+  return known;
+}
+
+/**
+ * The unknown flags present on a parsed-argv object, in the order they were
+ * typed.
+ *
+ * Reads `__explicit` — the set parseArgs fills with every key it saw on the
+ * command line — so defaults (which are merged in from DEFAULTS and were never
+ * typed) are correctly ignored.
+ *
+ * @param {object} parsed result of parseArgs()
+ * @returns {string[]} kebab-case flag names, without the leading `--`
+ */
+function unknownFlags(parsed) {
+  if (!parsed || !parsed.__explicit) { return []; }
+  const known = getKnownFlags();
+  return [...parsed.__explicit].filter(f => !known.has(String(f).toLowerCase()));
+}
+
+module.exports = { getKnownFlags, unknownFlags, INTERNAL_FLAGS };