amicus 3.0.0 → 3.1.0

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-07-15
+
+### Added
+
+- **Direct-first gateway routing** (#61): bare `provider/model` model IDs (e.g. `anthropic/claude-opus-4-5`)
+  now route to your **direct** provider key when one is configured, falling back to OpenRouter only when
+  it isn't. An explicit `openrouter/...`-prefixed model ID remains a force-OpenRouter override — that
+  literal form never changes behavior.
+  - New `--gateway auto|direct|openrouter` CLI flag on `start`, `fanout`, and `continue` (`auto` is the
+    direct-first default) and a matching `gateway` enum on the MCP `amicus_start` / `amicus_fanout` /
+    `amicus_continue` tools.
+  - New `routing.prefer` config key (`"direct"` default | `"openrouter"`) sets the global default; the
+    per-call `--gateway`/`gateway` param overrides it for that run.
+  - Non-interactive CLI (`--json`) and MCP now emit a structured `model_route_error` (`type`, `field`,
+    `requested`, `reason`) instead of an ad hoc message when a request can't be routed — identical shape
+    on both surfaces.
+  - Interactive runs get a picker with alternatives when a direct route misses (e.g. key missing or model
+    not on that vendor's live catalog), instead of failing outright.
+  - Live Anthropic model fetcher: the model catalog now queries Anthropic's API directly for the current
+    model list, the same live-fetch treatment OpenAI and Google already had.
+- Session provenance (resume/continue) preserves the gateway a run originally resolved to, even if keys
+  or `routing.prefer` change in between.
+
+### Changed
+
+- **Default aliases for direct-capable vendors** (`openai`, `google`, `anthropic`, `deepseek`) now resolve
+  to bare canonical model IDs instead of `openrouter/...`-prefixed ones, so they participate in
+  direct-first routing out of the box. Gateway-only vendors (`qwen`, `grok`, `glm`, and other
+  OpenRouter-exclusive families) are unchanged — they still resolve through OpenRouter, since there's no
+  direct key path for them.
+  - **Migration:** if you hold both an OpenRouter key and a direct key for one of the four vendors above,
+    the next run against that vendor moves you to the direct route and prints a one-time notice; it's
+    silent after that. Set `routing.prefer: "openrouter"` in config (or pass `--gateway openrouter` /
+    `gateway: "openrouter"` per call) to keep routing everything through OpenRouter as before. Aliases you
+    already overrode via `amicus setup --add-alias` are untouched.
+
+### Notes
+
+- Builds on the #61 gateway-routing foundation (router core, resolution modes, key discovery) merged to
+  main ahead of this release; this release wires that router into the live launch path (CLI + MCP), adds
+  the control surface (`--gateway` / `gateway` / `routing.prefer`), and switches default guidance to the
+  direct-first form.
+
 ## [3.0.0] - 2026-07-15
 
 ### ⚠️ Breaking

package/README.md

@@ -319,7 +319,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }
@@ -338,7 +338,16 @@ amicus models                 # list the catalog
 amicus models --search gemini # filter by substring
 ```
 
-`start`/`fanout` validate your model against the catalog before launching (skip with `--no-validate-model`). You can also always bypass aliases and pass a full `provider/model` or `openrouter/provider/model` ID directly. Catalog internals, alias management, and the full-id passthrough table are in **[docs/usage.md § Models](./docs/usage.md#amicus-models--the-model-catalog)**.
+`start`/`fanout` validate your model against the catalog before launching (skip with `--no-validate-model`). You can also always bypass aliases and pass a full model ID directly — bare `provider/model` (canonical) or `openrouter/provider/model` (explicit override); see Routing below. Catalog internals, alias management, and the full-id passthrough table are in **[docs/usage.md § Models](./docs/usage.md#amicus-models--the-model-catalog)**.
+
+### Routing
+
+- **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `google/gemini-3.5-flash`) is the canonical, policy-routed form — Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only an OpenRouter key exists.
+- **`openrouter/provider/model`** is an explicit override that always forces OpenRouter, even when a direct key is present — reach for it deliberately, or for gateway-only vendors with no direct integration (Qwen, Grok, Mistral, GLM, …).
+- **`--gateway auto|direct|openrouter`** (CLI, also on the MCP tools) overrides routing for one call; `auto` is the direct-first default. `routing.prefer` in `config.json` (`"direct"` by default, or `"openrouter"`) sets the global default.
+- **One-time migration notice:** if you hold both an OpenRouter key and a direct key for a vendor, the first launch that resolves to that vendor under **`auto`** routing (the default) prints a one-time notice that routing moved to direct API; set `routing.prefer: "openrouter"` to restore the old all-OpenRouter behavior. The notice never fires when you explicitly pass `--gateway direct` — that's your own choice, not a migration.
+
+Full details, the API-key/prefix table, and the migration notice are in **[docs/configuration.md](./docs/configuration.md)**.
 
 ---
 
@@ -417,7 +426,7 @@ Run `amicus doctor` first — it checks keys, catalog, OpenCode binary, Electron
 | "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 keys and past sessions are not lost, but v2.0.0 no longer reads the old paths automatically — see [docs/SHIMS.md](./docs/SHIMS.md) for the one-time migration steps (rename `~/.config/sidecar/` and any `.claude/sidecar_sessions/` dirs). |
 | Install fails partway, or `amicus doctor` reports the OpenCode binary "not found" | A **transient** error during the OpenCode engine's own postinstall (a spawn `ENOENT`, or an antivirus file-lock while it lays down its 11 per-platform binaries) can roll back the whole atomic install — retrying usually succeeds | Just re-run `npm install -g amicus`. If it still fails, clear the cache first: `npm cache clean --force && npm install -g amicus`. |
-| `401` / auth error | API key missing, or the model prefix doesn't match the key you have | Run `amicus setup`; make sure the prefix (`openrouter/…` vs `google/…` vs `openai/…` vs `anthropic/…`) matches the credentials you configured. |
+| `401` / auth error | No usable key for the model's vendor — bare `provider/model` ids fall back to `OPENROUTER_API_KEY` automatically, so this means neither the direct key nor an OpenRouter key is configured (or `--gateway direct`/`openrouter` forced a gateway whose key is missing) | Run `amicus setup`, or `amicus key <provider> <key>` to add the missing key; see [Routing](#routing). |
 | `402` / "Payment Required" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter <key>` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See "Free council (zero-cost)" under [The Council](#the-council) above. |
 | 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/electron/setup-ui.js

@@ -10,6 +10,7 @@ const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
 const { PROVIDER_FAMILY_NAMES } = require('../src/utils/model-fetcher');
+const { listDirectProviders } = require('../src/utils/provider-registry');
 
 /**
  * @param {object} [options={}]
@@ -32,6 +33,7 @@ function buildSetupHTML(options = {}) {
   const providerNamesJson = JSON.stringify(PROVIDER_NAMES);
   const defaultAliasesJson = JSON.stringify(getDefaultAliases());
   const familyNamesJson = JSON.stringify(PROVIDER_FAMILY_NAMES);
+  const directProvidersJson = JSON.stringify(listDirectProviders());
   return `<!DOCTYPE html>
 <html><head><meta charset="utf-8"><title>Amicus Setup</title>
 <style>${css}</style></head><body>
@@ -53,11 +55,11 @@ function buildSetupHTML(options = {}) {
     </div>
   </div>
   <div class="footer"><div class="footer-brand"><svg width="15" height="15" viewBox="0 0 32 32" fill="none"><path d="M4 8H19"/><path d="M4 11H14L19 8"/><path d="M4 14H13L19 8"/><path d="M4 17H12L19 8"/><path d="M4 20H11L19 8"/><path d="M4 23H10L19 8"/><path class="brand-main" d="M19 8H28"/></svg> ${brandName}</div><div class="footer-nav"><button class="nav-btn" id="back-btn" style="display:none">Back</button><button class="nav-btn primary" id="next-btn" disabled>Next</button><button class="nav-btn primary" id="finish-btn" style="display:none">Finish</button></div></div>
-${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson)}
+${buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson, directProvidersJson)}
 </body></html>`;
 }
 
-function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson) {
+function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, defaultAliasesJson, familyNamesJson, directProvidersJson) {
   const keysJs = buildKeysScript();
   const aliasJs = buildAliasScript();
   const councilJs = buildCouncilScript();
@@ -72,7 +74,9 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   var providerNamesData = ${providerNamesJson};
   var defaultAliases = ${defaultAliasesJson};
   var PROVIDER_FAMILY_NAMES = ${familyNamesJson};
+  var directProviders = ${directProvidersJson};
   var routingChoices = {};
+  var explicitRouteChoices = {};
   var aliasEdits = {};
   var aliasDisplay = {};
   window.availableModels = null;
@@ -195,6 +199,21 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     } else { nextBtn.disabled = false; }
   }
 
+  // #61: an auto-selected (non-explicit) openrouter/<vendor>/<model> route
+  // whose vendor also has a direct integration must be stored bare
+  // (<vendor>/<model>) so the gateway router can policy-route it direct-first;
+  // a stored openrouter/... string is treated as an explicit force-OpenRouter
+  // literal and never reconsiders direct-first. Mirrors
+  // src/utils/curated-models.js's toCanonicalDefault exactly. Gateway-only
+  // vendors (not in directProviders, e.g. qwen/grok/glm/...) pass through
+  // unchanged since OpenRouter is their only route anyway.
+  function toBareIfDirect(route) {
+    if (typeof route !== 'string' || route.indexOf('openrouter/') !== 0) { return route; }
+    var rest = route.slice('openrouter/'.length);
+    var vendor = rest.split('/')[0];
+    return directProviders.indexOf(vendor) !== -1 ? rest : route;
+  }
+
   // Single source of the route choice for a quick-pick row: explicit pill
   // choice if its key still exists, else first provider with a key, else
   // the row's first route. Returns the full model id or null.
@@ -209,7 +228,11 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
       }
       if (!prov) { prov = provs[0]; }
     }
-    return mc.routes[prov] || null;
+    var route = mc.routes[prov] || null;
+    // Only canonicalize auto-picks; an explicit "via OpenRouter" pill click
+    // is a deliberate choice and is returned unchanged.
+    if (route && !explicitRouteChoices[mc.alias]) { route = toBareIfDirect(route); }
+    return route;
   }
 
   function updateRoutingPills() {
@@ -367,6 +390,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
     var provider = pill.getAttribute('data-provider');
     if (!alias || !provider) { return; }
     routingChoices[alias] = provider;
+    explicitRouteChoices[alias] = true;
     var toggle = pill.parentElement;
     toggle.querySelectorAll('.route-pill').forEach(function(p) { p.classList.toggle('active', p === pill); });
     updateWritePreviews();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "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/skills/second-opinion/SKILL.md

@@ -523,6 +523,8 @@ Use these together with `amicus council stats` (the ledger — authoritative qua
 
 Always **rank recommendations by fit**, state the trade-off for each option, and surface the estimated cost (an estimate, not a guarantee; unpriced legs disclosed as "cost unknown"). Never present a single option without explanation.
 
+**Model naming for council members.** Name bench members by alias (`gemini`, `gpt`, `deepseek`, `opus`, …) or by full `provider/model` id — both work with `--models`/`amicus_fanout`. A bare canonical id (e.g. `anthropic/claude-opus-4.8`) is policy-routed **direct-first**: Amicus uses the user's direct provider key when one is configured, falling back to OpenRouter automatically. `openrouter/provider/model` is an explicit force-OpenRouter override — reach for it only when the user deliberately wants a specific member to run through OpenRouter (e.g. to use a free-tier variant), or for gateway-only vendors with no direct integration. A per-run `--gateway auto|direct|openrouter` (also on `amicus_fanout`/`amicus_start`) overrides routing for the whole wave if the user asks for it; leave it unset (`auto`) by default.
+
 ---
 
 ## Output & naming

package/skills/sidecar/SKILL.md

@@ -75,9 +75,19 @@ Amicus uses the OpenCode SDK to communicate with LLM providers. You need to conf
 
 **Recommended:** run `amicus setup` — a guided wizard that stores keys in `~/.config/amicus/.env`, picks your default model from the live catalog, and seeds aliases. The options below are manual alternatives.
 
+### Model Naming: Bare Canonical Is the Normal Form
+
+Read this before picking a model string — it decides both routing and which credentials get used:
+
+- **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `google/gemini-3.5-flash`) is the **canonical, policy-routed** form — use it by default. Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only `OPENROUTER_API_KEY` exists. You never pick the gateway by hand.
+- **`openrouter/provider/model`** (e.g. `openrouter/google/gemini-3.5-flash`) is an **explicit force-OpenRouter override** — it always routes through OpenRouter even when a direct key is present. Reach for it deliberately, or for gateway-only vendors with no direct integration at all (Qwen, Grok, Mistral, GLM, MiniMax, Kimi, Seed, …) — those *require* the `openrouter/` prefix.
+- Short aliases (`gemini`, `gpt`, `opus`, `claude`, `deepseek`, …) resolve to one of the two forms above via your config; `amicus setup` seeds direct-capable vendors to the bare canonical form automatically.
+- **Routing controls:** `routing.prefer` in `~/.config/amicus/config.json` sets the global default — `"direct"` (the default) or `"openrouter"` to always prefer OpenRouter. Per call, `--gateway auto|direct|openrouter` overrides it (`auto` = direct-first, same as the default).
+- **One-time migration notice:** if you hold both an OpenRouter key and a direct key for a vendor, the first launch that resolves to that vendor prints a one-time notice that routing moved to direct API (previously OpenRouter); set `routing.prefer: "openrouter"` (or pass `--gateway openrouter`) to restore the old all-OpenRouter behavior.
+
 ### Option A: OpenRouter (Recommended for Multi-Model Access)
 
-OpenRouter provides unified access to many models (Gemini, GPT-4, Claude, o3, etc.) with a single API key. If you'd rather not hand-edit JSON, run `amicus setup` instead — it stores the key for you.
+OpenRouter provides unified access to many models (Gemini, GPT, Claude, o3, etc.) with a single API key. If you'd rather not hand-edit JSON, run `amicus setup` instead — it stores the key for you.
 
 **Step 1: Get an OpenRouter API key**
 - Sign up at https://openrouter.ai
@@ -103,12 +113,11 @@ EOF
 amicus start --model gemini --prompt "Say hello" --no-ui
 ```
 
-**Model names with OpenRouter:**
-When using OpenRouter, prefix the model with `openrouter/`:
+**With OpenRouter as your only key**, aliases and bare canonical ids both work — the router falls back to OpenRouter automatically since no direct key exists for the vendor:
 ```bash
-amicus start --model gemini --prompt "..."
-amicus start --model gpt --prompt "..."
-amicus start --model claude --prompt "..."
+amicus start --model gemini --prompt "..."                              # alias
+amicus start --model google/gemini-3.5-flash --prompt "..."             # bare canonical, falls back to OpenRouter
+amicus start --model openrouter/google/gemini-3.5-flash --prompt "..."  # explicit override — same result here
 ```
 
 ### Option B: Direct API Keys (Provider-Specific)
@@ -136,8 +145,8 @@ Add these to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
 - Run `amicus setup` to store keys in amicus's config (recommended)
 - Move your exports to `~/.zshenv` (sourced by all zsh shell types)
 
-**Model names with direct API keys:**
-When using direct API keys, use the provider/model format WITHOUT the `openrouter/` prefix:
+**Model names with a direct key configured:**
+Use the bare canonical `provider/model` form — direct-first routing picks up these keys automatically, no `openrouter/` prefix needed:
 ```bash
 amicus start --model google/<model-name> --prompt "..."
 amicus start --model openai/<model-name> --prompt "..."
@@ -146,18 +155,15 @@ amicus start --model anthropic/<model-name> --prompt "..."
 
 ### Model Naming Summary
 
-| Provider Access | Model Name Format | Example |
-|-----------------|-------------------|---------|
-| OpenRouter | `openrouter/provider/model` | `openrouter/google/<model-name>` |
-| Direct Google API | `google/model` | `google/<model-name>` |
-| Direct OpenAI API | `openai/model` | `openai/<model-name>` |
-| Direct Anthropic API | `anthropic/model` | `anthropic/<model-name>` |
+| Form | Meaning | Credentials used |
+|------|---------|-------------------|
+| `provider/model` (bare, canonical) | Policy-routed, direct-first | Direct provider key if configured, else `OPENROUTER_API_KEY` |
+| `openrouter/provider/model` | Explicit force-OpenRouter override (required for gateway-only vendors) | `OPENROUTER_API_KEY`, always |
 
-**Important:** The model name format tells the SDK which authentication to use:
-- `openrouter/...` → Uses OpenRouter API key from auth.json
-- `google/...` → Uses `GOOGLE_GENERATIVE_AI_API_KEY` environment variable
-- `openai/...` → Uses `OPENAI_API_KEY` environment variable
-- `anthropic/...` → Uses `ANTHROPIC_API_KEY` environment variable
+**Important:** the bare form is not tied to one credential — the router decides at launch time:
+- `google/...`, `openai/...`, `anthropic/...`, `deepseek/...` (bare) → that vendor's direct key if present, else `OPENROUTER_API_KEY`
+- `openrouter/...` → always `OPENROUTER_API_KEY`
+- `--gateway direct` forces the direct key (errors if it's missing); `--gateway openrouter` forces OpenRouter (errors if that key is missing); omit `--gateway` (or pass `auto`) for the default direct-first behavior described above
 
 ---
 
@@ -252,6 +258,10 @@ amicus start \
 - `--json`: With `--no-ui`, emit the run result as one stable JSON document on stdout
   (`schemaVersion: 2`; the `summary` field is the model's output).
 - `--no-validate-model`: Skip the model-catalog pre-flight check (validation is on by default).
+- `--gateway <mode>`: Routing override for this launch — `auto` (default, direct-first: your
+  direct provider key when present, else OpenRouter), `direct` (require a direct provider key,
+  errors if missing), or `openrouter` (force OpenRouter, errors if that key is missing). Omit to
+  fall back to the `routing.prefer` config default (`"direct"` unless changed).
 - `--agent <agent>`: Agent mode (controls tool permissions). If omitted, defaults to
   **Chat** in interactive mode and **Build** in headless (`--no-ui`) mode — `chat`
   stalls without user interaction, so headless runs need an agent that doesn't wait
@@ -281,17 +291,26 @@ The CLI validates all inputs **before** launching the sidecar. Invalid inputs fa
 | `--timeout` | Must be positive number | `Error: --timeout must be a positive number` |
 | `--context-turns` | Must be positive number | `Error: --context-turns must be a positive number` |
 | `--context-since` | Must match format: `30m`, `2h`, `1d` | `Error: --context-since must be in format: 30m, 2h, or 1d` |
-| API Key | Must be set for model's provider | `Error: <KEY_NAME> environment variable is required for <Provider> models` |
+| `--gateway` | If provided, must be one of `auto`, `direct`, `openrouter` | `Error: --gateway must be one of: auto, direct, openrouter` |
+| API Key | The router must be able to resolve *some* usable key for the requested model (see below) | Reason sentence + fix hint, e.g. `No API key was found for this vendor via any gateway.` / `Add a provider key or an OpenRouter key.` |
 
 **API Key Requirements by Provider:**
 
-| Model Prefix | Required Env Var | Example |
-|--------------|------------------|---------|
-| `openrouter/...` | `OPENROUTER_API_KEY` | `export OPENROUTER_API_KEY=sk-or-...` |
-| `google/...` | `GOOGLE_GENERATIVE_AI_API_KEY` | `export GOOGLE_GENERATIVE_AI_API_KEY=...` |
-| `openai/...` | `OPENAI_API_KEY` | `export OPENAI_API_KEY=sk-...` |
-| `anthropic/...` | `ANTHROPIC_API_KEY` | `export ANTHROPIC_API_KEY=sk-ant-...` |
-| `deepseek/...` | `DEEPSEEK_API_KEY` | `export DEEPSEEK_API_KEY=...` |
+Bare canonical ids (`google/...`, `openai/...`, `anthropic/...`, `deepseek/...`) are policy-routed —
+the direct key for that vendor if configured, else `OPENROUTER_API_KEY` as fallback. Only
+`openrouter/...` (the explicit override) and gateway-only vendors (Qwen, Grok, Mistral, GLM, …)
+strictly require `OPENROUTER_API_KEY`:
+
+| Model Prefix | Env Var Amicus Will Use | Notes |
+|--------------|--------------------------|-------|
+| `openrouter/...` | `OPENROUTER_API_KEY` | Always required for this form |
+| `google/...` (bare) | `GOOGLE_GENERATIVE_AI_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `openai/...` (bare) | `OPENAI_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `anthropic/...` (bare) | `ANTHROPIC_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `deepseek/...` (bare) | `DEEPSEEK_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+
+`--gateway direct` narrows this to "the direct key specifically" (errors if only OpenRouter is
+configured); `--gateway openrouter` narrows it to `OPENROUTER_API_KEY` specifically.
 
 **Handling validation errors:**
 
@@ -310,8 +329,8 @@ amicus start --model gemini --prompt "Task" --agent Build
 # Fix: Provide a non-empty briefing
 amicus start --model gemini --prompt "Detailed task description"
 
-# Error: OPENROUTER_API_KEY environment variable is required
-# Fix: Set the API key for your provider
+# Error: No API key was found for this vendor via any gateway.
+# Fix: add a direct provider key or an OpenRouter key
 export OPENROUTER_API_KEY=sk-or-your-key
 amicus start --model gemini --prompt "Task"
 ```
@@ -325,10 +344,11 @@ 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),
 then prints ONE JSON wave document: `status` (`complete`|`partial`|`error`), `counts`, and
 `legs[]` where each leg's `summary` is that model's answer. Exit codes: 0 complete, 2 partial,
-1 error/aborted. Aliases and full `provider/model` IDs both work; duplicates are allowed
+1 error/aborted. Aliases and full `provider/model` IDs both work — bare canonical ids route
+direct-first, `openrouter/provider/model` forces OpenRouter; duplicates are allowed
 (distinct legs). `--wave-id <id>` pins leg IDs to `<id>-1..N`. Shared per-leg knobs: `--agent`,
 `--thinking`, `--timeout`, `--summary-length`, `--no-context`, `--context-*`, `--mcp*`,
-`--no-validate-model`, `--cwd`.
+`--no-validate-model`, `--gateway`, `--cwd`.
 
 ### Inspect the Model Catalog
 
@@ -386,7 +406,10 @@ Starts a **new** sidecar session that inherits the old session's conversation as
 - `--prompt`: New task description for the continuation
 
 **Optional:**
-- `--model <model>`: Override model (defaults to original session's model)
+- `--model <model>`: Override model (defaults to original session's model) — bare canonical ids
+  route direct-first; `openrouter/provider/model` forces OpenRouter
+- `--gateway <mode>`: Routing override for the new session (`auto`|`direct`|`openrouter`), same
+  semantics as `start`. Only meaningful when `--model` is also given
 - `--context-turns <N>`: Max turns from previous session to include (default: 50)
 - `--context-max-tokens <N>`: Max tokens for context (default: 80000)
 - `--no-ui`: Run in autonomous mode
@@ -427,7 +450,9 @@ Use short aliases (run `amicus models` to see the live catalog, and `amicus mode
 - `--model deepseek` -- DeepSeek
 - Omit `--model` entirely to use your configured default
 
-Full model strings also work: `--model openrouter/provider/model-id`
+Full model strings also work: `--model provider/model-id` (bare canonical, direct-first — e.g.
+`--model anthropic/claude-opus-4.8`) or `--model openrouter/provider/model-id` (explicit
+force-OpenRouter override).
 
 ### Verifying Model Names
 
@@ -891,8 +916,8 @@ echo $ANTHROPIC_API_KEY # For Anthropic models
 ### "401 Unauthorized" or authentication errors
 
 1. Verify you're using the correct model name format:
-   - OpenRouter models: `openrouter/provider/model`
-   - Direct API models: `provider/model`
+   - Bare canonical (policy-routed, direct-first): `provider/model`
+   - Explicit force-OpenRouter override: `openrouter/provider/model`
 
 2. Check your API key is valid and has credits
 
@@ -967,11 +992,14 @@ amicus start --model ... --prompt "..." --agent Explore
 amicus start --model ... --prompt "..." --agent MyCustomAgent
 ```
 
-**"Error: <KEY_NAME> environment variable is required for <Provider> models"**
+**"No API key was found for this vendor via any gateway." / "No API key is configured for this vendor's direct API."**
 
-The API key for the model's provider is not set:
+A bare canonical id needs *some* usable key for the vendor — either its direct key or
+`OPENROUTER_API_KEY` as a fallback. `--gateway direct` narrows that to "the direct key
+specifically" (fails if only OpenRouter is configured); `--gateway openrouter` narrows it to
+`OPENROUTER_API_KEY` specifically:
 ```bash
-# For OpenRouter models (openrouter/...)
+# OPENROUTER_API_KEY is the fallback for every direct-capable vendor
 export OPENROUTER_API_KEY=sk-or-your-key
 
 # For Google models (google/...)

package/src/cli-handlers-resume-continue.js

@@ -10,9 +10,10 @@
 
 'use strict';
 
-const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { resolveLaunchModel } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson, requireValidTaskId } = require('./utils/cli-preflight');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Handle 'amicus resume' command
@@ -70,11 +71,35 @@ async function handleContinue(args) {
 
   requireNoUiForJson(args, useJson);
 
-  // F5: an explicitly passed --model gets the same resolution+validation as start.
+  // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
+  // --gateway via validateStartArgs (cli.js) — continue never did, so a
+  // typo'd value silently fell through to resolveGatewayMode's pass-through
+  // instead of failing fast with a clear error. Checked unconditionally
+  // (not just when --model is also given) since --gateway alone is still a
+  // user-facing typo worth catching.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
+  }
+
+  // F5/#61 Task 7.3: an explicitly passed --model routes through the gateway
+  // router exactly like start (resolveLaunchModel), so --gateway / direct-first
+  // policy / structured route errors apply here too. The NO-`--model` case
+  // (inherit the prior session's model) is unchanged below — that IS the
+  // "preserve prior route" behavior: the prior concrete id is reused verbatim,
+  // never re-resolved.
+  // #61 Task 5.2 (best-effort provenance): stash the freshly-resolved
+  // gateway/resolutionVersion so the NEW session's metadata can record them.
+  // These stay undefined on the inherit-prior-model path (no fresh routing
+  // happened there), so the metadata writer simply omits them — the prior
+  // concrete model id being reused verbatim already prevents a silent gateway
+  // change for a continued session without a fresh --model.
+  let routeGateway;
+  let routeResolutionVersion;
   if (args.model !== undefined) {
-    const { model, alias } = resolveModelFromArgs(args);
+    const { model, gateway, provenance } = await resolveLaunchModel(args);
     args.model = model;
-    args.model = await validateFallbackModel(args, alias);
+    routeGateway = gateway;
+    routeResolutionVersion = provenance && provenance.resolutionVersion;
   }
 
   const { continueAmicus } = require('./index');
@@ -91,6 +116,8 @@ async function handleContinue(args) {
       headless: args['no-ui'],
       timeout: args.timeout,
       json: useJson,
+      gateway: routeGateway,
+      resolutionVersion: routeResolutionVersion,
     });
   } catch (err) {
     // Same rationale as handleResume above: continueSidecar/loadPreviousSession

package/src/cli-handlers-run.js

@@ -14,9 +14,10 @@
 
 const { validateStartArgs } = require('./cli');
 const { validateTaskId } = require('./utils/validators');
-const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { resolveLaunchModel } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson } = require('./utils/cli-preflight');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Handle 'sidecar start' command
@@ -43,9 +44,8 @@ async function handleStart(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
   }
 
-  const { model, alias } = resolveModelFromArgs(args);
+  const { model, alias } = await resolveLaunchModel(args);
   args.model = model;
-  args.model = await validateFallbackModel(args, alias);
 
   // Normalize agent: --agent takes precedence, otherwise use --mode
   args.agent = args.agent || args.mode;
@@ -108,6 +108,14 @@ async function handleStart(args) {
 async function handleFanout(args) {
   const useJson = !!args.json;
 
+  // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
+  // --gateway via validateStartArgs (cli.js) — fanout never did, so a typo'd
+  // value silently fell through to resolveGatewayMode's pass-through instead
+  // of failing fast with a clear error.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
+  }
+
   const { resolvePromptSource } = require('./utils/prompt-source');
   const promptRes = resolvePromptSource(args);
   if (promptRes.error) {
@@ -161,7 +169,7 @@ async function handleFanout(args) {
 
   // Direct require — the src/index.js public re-export is added later (Task 13)
   const { runFanout } = require('./sidecar/fanout');
-  const { loadConfig } = require('./utils/config');
+  const { loadConfig, resolveGatewayMode } = require('./utils/config');
   const cfg = loadConfig() || {};
   const { exitCode } = await runFanout({
     models: args.models,
@@ -187,6 +195,9 @@ async function handleFanout(args) {
     noMcp: args['no-mcp'],
     excludeMcp: args['exclude-mcp'],
     noValidateModel: args['no-validate-model'],
+    // #61 Task 7.3: --gateway merged with routing.prefer, applied per leg
+    // by validateFanoutModels' router call.
+    gatewayMode: resolveGatewayMode(args.gateway),
     json: !!args.json,
     client: args.client,
     maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,

package/src/cli.js

@@ -18,6 +18,7 @@ const {
 } = require('./utils/validators');
 const { resolvePromptSource } = require('./utils/prompt-source');
 const { logger } = require('./utils/logger');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Default values per spec §4.1
@@ -245,6 +246,15 @@ function validateStartArgs(args) {
     }
   }
 
+  // Validate --gateway (if provided) — #61 Task 7.1. resolveGatewayMode()
+  // already treats any non-'direct'/'openrouter' string as a pass-through
+  // (effectively silent auto fallback), so this pre-flight check exists
+  // purely to catch typos with a clear error instead of letting them slip
+  // through unnoticed.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    return { valid: false, error: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` };
+  }
+
   // Validate MCP spec format (if provided)
   const mcpCheck = validateMcpSpec(args.mcp);
   if (!mcpCheck.valid) {
@@ -401,6 +411,7 @@ Options for 'start':
   --exclude-mcp <name>           Exclude specific MCP server (repeatable)
   --validate-model             (Deprecated: validation is on by default)
   --no-validate-model          Skip model-catalog validation before launch
+  --gateway <mode>             Routing: auto (direct-first), direct, or openrouter
   --position <pos>             Window position: right (default), left, center
 `,
   fanout: `
@@ -415,6 +426,7 @@ Options for 'fanout':
   --json                       Emit the wave result as stable JSON on stdout
   --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
   --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
+  --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
   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
@@ -456,6 +468,7 @@ 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)
+  --gateway <mode>             Routing when --model is given: auto (direct-first), direct, or openrouter
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
   --json                       With --no-ui: emit the run result as stable JSON