amicus 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.0.0",
+  "version": "1.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.",
   "keywords": [
     "claude",
@@ -17,7 +17,7 @@
     "second-opinion",
     "fanout"
   ],
-  "author": "BourbonDog",
+  "author": "Christian Wagner",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -24,6 +24,10 @@ description: >
   --prompt-file <path> --json` (one headless wave, one JSON result) instead of N
   separate start calls. Different prompts per model → separate parallel
   `amicus start --no-ui` calls.
+  (7) For a SINGLE-model sidecar, DEFAULT to interactive — omit --no-ui so the
+  Electron UI opens and the user can watch, converse, and click Fold. Use --no-ui
+  for a single model only when the user asks for headless/autonomous, or for
+  unattended bulk automation. Interactive launches still use run_in_background: true.
 ---
 
 # Amicus: Multi-Model Sidecar Tool
@@ -608,13 +612,15 @@ amicus start --model gemini --prompt "Implement the login feature" --agent Build
 
 ### Interactive (Default)
 
+**The default for single-model sidecars — omit `--no-ui`.** Reach for headless only when the user asks for it, the run is part of a multi-model wave, or the task is unattended bulk automation.
+
 - Opens a GUI window
 - User can converse with the sidecar
 - **Model Picker:** Click the model name in the input area to switch models mid-conversation
 - Click **FOLD** when done to generate summary
 - Summary returns to your context via stdout
 
-**Use for:** Debugging, exploration, architectural discussions
+**Use for:** Any single-model sidecar — debugging, exploration, second opinions, reviews, architectural discussions
 
 **Mid-Conversation Model Switching:**
 In interactive mode, you can change models without restarting:
@@ -635,6 +641,7 @@ This is useful when you want to:
 - Summary returns automatically
 - **Default agent is `build`** — `chat` agent requires interactive UI and will stall in headless mode
 - **Always use headless when spawning multiple sidecars at once** (see Multi-LLM rule below)
+- **Not the default for single-model runs** — a single-model sidecar opens the UI unless the user asks for headless or the task is unattended bulk work
 
 **Multi-LLM Rule:** When the SAME prompt goes to N models, use `amicus fanout` (see [Fan Out One Prompt to N Models](#fan-out-one-prompt-to-n-models)) — one headless wave, one JSON result. When prompts differ per model, use separate parallel `amicus start --no-ui` calls with `run_in_background: true`. Only switch to interactive if the user explicitly asks.
 
@@ -656,7 +663,7 @@ amicus start --model gemini --prompt "..." --agent chat --no-ui
 # → Error: --agent chat requires interactive mode (remove --no-ui or use --agent build)
 ```
 
-**Use for:** Bulk tasks, test generation, documentation, linting
+**Use for:** Multi-model waves, bulk tasks, test generation, documentation, linting — or when the user explicitly asks for headless
 
 ```bash
 amicus start \
@@ -679,11 +686,14 @@ amicus start \
 **Example invocation pattern:**
 ```
 Bash tool:
-  command: "amicus start --model gemini --prompt '...' --no-ui"
+  command: "amicus start --model gemini --prompt '...'"
   run_in_background: true
 ```
 
-After launching, tell the user:
+After launching an interactive sidecar, tell the user:
+> "The Amicus window is open — chat with it there and click FOLD when you're done. I'll pick up the summary here."
+
+After launching a headless sidecar, tell the user:
 > "Amicus is running in the background. I'll share the results when it completes."
 
 **When the background task completes**, you will be automatically notified. Use the `TaskOutput` tool with the task ID to read the sidecar's summary output, then present it to the user. Do NOT poll or sleep — the notification arrives automatically.

package/skills/second-opinion/COUNCIL-DESIGN.md

@@ -120,7 +120,9 @@ Run as ordered phases; track as todos. **Three sequential waves of model calls**
 ### Stage 6 — Capture lessons (compounding)
 - Reflect on failures/mitigations and briefing wording, as today.
 - **Additionally** update the per-model **reviewer-reliability** table (§7).
-- **Show the proposed MODEL-NOTES diff and get approval before writing.** Keep it tight.
+- **Write the proposed MODEL-NOTES diff to a run-folder file and get approval before writing.**
+  The approval prompt carries the diff file's path; chat text alone is not sufficient (an approval
+  dialog can hide the chat transcript). Keep it tight.
 
 ## 5. Key mechanics
 

package/skills/second-opinion/SKILL.md

@@ -279,13 +279,13 @@ Draft new or updated entries for the per-model sections of `MODEL-NOTES.md` that
 - **confirm-rate** — incorporate this run's share of each model's findings that ended up Confirmed.
 - Merge into the existing row for that model; prune the notes column to stay tight.
 
-**Compose the proposed MODEL-NOTES diff.** Combine the run-lessons updates and the reviewer-reliability table updates into a single proposed diff (old → new for every changed section). Show it to the user in full.
+**Compose the proposed MODEL-NOTES diff.** Combine the run-lessons updates and the reviewer-reliability table updates into a single proposed diff (old → new for every changed section). **Write the full diff to a file in the run folder** — `_tmp-proposed-model-notes-update.md` — so the user can open and review it before deciding. Presenting the diff as chat text alone is **not sufficient**: an approval dialog can hide the chat transcript, so the user may be asked to decide on a diff they never saw.
 
-**Wait for explicit approval before writing anything.** Present the diff and ask:
+**Wait for explicit approval before writing anything.** Ask, with the diff file's path inside the approval prompt itself:
 
-> Approve this MODEL-NOTES update? (yes / no / edit)
+> Proposed MODEL-NOTES update written to `<run-folder>/_tmp-proposed-model-notes-update.md` — open it to review. Approve this MODEL-NOTES update? (yes / no / edit)
 
-If the user approves, write the changes. If they say "edit", incorporate their corrections and show the revised diff before writing. Do not write any partial update — write only after the full diff is approved.
+If the user approves, write the changes. If they say "edit", incorporate their corrections, rewrite the diff file, and re-present its path for approval before writing. Do not write any partial update — write only after the full diff is approved.
 
 **Keep MODEL-NOTES tight.** Do not append new bullets when an existing entry covers the same ground — merge or reword instead. If a note has been superseded by a better mitigation, prune the old one. The goal is a compact, authoritative reference, not a changelog.
 
@@ -377,8 +377,9 @@ Always **rank recommendations by fit**, state the trade-off for each option, and
   - `report.md` — synthesis + decision log + what was applied (+ the "How Claude's review fared" readout when the toggle is on) + a
     **run-stats table**: one row per model call — **stage** (which stage you launched the call for) plus **model, status, durationMs** read from the wave/run JSON documents. The schema carries no cost data — do not invent cost figures.
 - Reviewed copy: `<stem>-reviewed.<ext>`, next to the source.
-- Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet) live in the
-  run folder and are cleaned up at the end of the run.
+- Temp working files (`_tmp-*.md`: extracts, stage briefings, red-team brief, bundle, chair packet, proposed
+  MODEL-NOTES diff) live in the run folder and are cleaned up at the end of the run — the proposed-diff file
+  only after the Stage-6 approval decision is resolved.
 
 ---
 

package/src/cli-handlers.js

@@ -180,9 +180,74 @@ async function handleMcp() {
   await startMcpServer();
 }
 
+/**
+ * Handle 'amicus key' command
+ * Lists, saves, or removes API keys for a provider without opening the Electron wizard.
+ */
+async function handleKey(args) {
+  const { readApiKeys, readApiKeyHints, saveApiKey, removeApiKey, PROVIDER_ENV_MAP } = require('./utils/api-key-store');
+  const { validateApiKey } = require('./utils/api-key-validation');
+
+  const provider = args._[1];
+  const keyArg = args._[2];
+
+  // List mode: no provider given
+  if (!provider) {
+    const configured = readApiKeys();
+    const hints = readApiKeyHints();
+    const knownProviders = Object.keys(PROVIDER_ENV_MAP);
+    console.log('');
+    console.log('Configured API keys:');
+    for (const p of knownProviders) {
+      const status = configured[p] ? `✓  ${hints[p]}` : '✗  not set';
+      console.log(`  ${p.padEnd(12)} ${status}`);
+    }
+    console.log('');
+    return;
+  }
+
+  // Validate provider
+  if (!PROVIDER_ENV_MAP[provider]) {
+    console.error(`Error: Unknown provider "${provider}". Known providers: ${Object.keys(PROVIDER_ENV_MAP).join(', ')}`);
+    process.exit(1);
+  }
+
+  // Remove mode
+  if (args.remove) {
+    const result = removeApiKey(provider);
+    if (!result.success) {
+      console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`${provider} key removed.`);
+    return;
+  }
+
+  // Save mode: key required
+  if (!keyArg) {
+    console.error(`Error: API key is required. Usage: amicus key ${provider} <apikey>`);
+    process.exit(1);
+  }
+
+  console.log(`Validating ${provider} key...`);
+  const validation = await validateApiKey(provider, keyArg);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+
+  const result = saveApiKey(provider, keyArg);
+  if (!result.success) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`${provider} key validated and saved.`);
+}
+
 module.exports = {
   handleSetup,
   handleAbort,
   handleUpdate,
   handleMcp,
+  handleKey,
 };

package/src/cli.js

@@ -110,7 +110,8 @@ function isBooleanFlag(key) {
      'help',
      'api-keys',
      'validate-model',
-     'no-validate-model'
+     'no-validate-model',
+     'remove'                // used by 'key' command only; other handlers ignore it
    ];
   return booleanFlags.includes(key);
 }
@@ -302,6 +303,10 @@ Commands:
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
     --add-alias <name=model> Add a model alias without the full wizard
+  key         Manage API keys from the command line
+    <provider> <apikey>      Validate and save a key
+    <provider> --remove      Remove a saved key
+    (no args)                List all configured providers
   update      Update to latest version
   mcp         Start MCP server (stdio transport)
 

package/src/sidecar/models.js

@@ -15,6 +15,8 @@
 const { getCatalogInfo, refreshCatalog, catalogPath } = require('../utils/model-catalog');
 const { collectAliasSources, findStaleAliases, suggestReplacements } = require('../utils/alias-audit');
 const { buildCatalogDoc, buildAuditDoc } = require('../utils/result-schema');
+const { getFamilies } = require('../utils/curated-models');
+const { pickCurrent } = require('../utils/quick-picks');
 
 const CHECK_EXIT_CAP = 100;
 
@@ -105,8 +107,13 @@ async function runCheck(args) {
     }), null, 2) + '\n');
     return Math.min(stale.length, CHECK_EXIT_CAP);
   }
+  const driftLines = buildFallbackDriftReport(catalog);
   if (stale.length === 0) {
     process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);
+    if (driftLines.length > 0) {
+      process.stdout.write('Pinned fallback drift:\n');
+      for (const l of driftLines) { process.stdout.write(l + '\n'); }
+    }
     return 0;
   }
   for (const s of stale) {
@@ -118,9 +125,32 @@ async function runCheck(args) {
       process.stdout.write('  no same-vendor candidates in catalog\n');
     }
   }
+  if (driftLines.length > 0) {
+    process.stdout.write('Pinned fallback drift:\n');
+    for (const l of driftLines) { process.stdout.write(l + '\n'); }
+  }
   return Math.min(stale.length, CHECK_EXIT_CAP);
 }
 
+/**
+ * Non-blocking drift report: pinned family fallbacks vs live resolution.
+ * Empty catalog → [] (cannot check). Never affects the exit code.
+ * @param {Array<{id:string}>} catalog
+ * @returns {string[]} human-readable warning lines
+ */
+function buildFallbackDriftReport(catalog) {
+  if (!catalog || catalog.length === 0) { return []; }
+  const lines = [];
+  for (const f of getFamilies()) {
+    const live = pickCurrent(catalog, 'openrouter/', f.vendorPath, f.idPattern);
+    if (live && f.fallback.openrouter && live !== f.fallback.openrouter) {
+      lines.push(
+        `  pinned fallback drift: ${f.alias} → ${f.fallback.openrouter} (live: ${live}) — update curated-models.js`);
+    }
+  }
+  return lines;
+}
+
 /** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
 async function handleModels(args) {
   if (args.search === true) {
@@ -132,4 +162,4 @@ async function handleModels(args) {
   return runList(args);
 }
 
-module.exports = { handleModels };
+module.exports = { handleModels, buildFallbackDriftReport };

package/src/sidecar/setup.js

@@ -13,15 +13,6 @@ const readline = require('readline');
 const { loadConfig, saveConfig, getDefaultAliases, getConfigDir } = require('../utils/config');
 const { logger } = require('../utils/logger');
 
-const { getCuratedModels } = require('../utils/curated-models');
-/**
- * Model choices presented during readline setup — derived from curated-models (F5).
- * @type {Array<{number: number, alias: string, label: string}>}
- */
-const MODEL_CHOICES = getCuratedModels().map((c, i) => ({
-  number: i + 1, alias: c.alias, label: `${c.label} (${c.blurb})`
-}));
-
 /**
  * Add a model alias to the existing config (or create config if none exists)
  * @param {string} name - Alias name
@@ -68,7 +59,7 @@ function createDefaultConfig(defaultModel) {
 
 /**
  * Detect available API keys from .env file and process.env
- * @returns {{openrouter: boolean, google: boolean, openai: boolean, anthropic: boolean}}
+ * @returns {{openrouter: boolean, google: boolean, openai: boolean, anthropic: boolean, deepseek: boolean}}
  */
 function detectApiKeys() {
   const { readApiKeys } = require('../utils/api-key-store');
@@ -90,21 +81,28 @@ function askQuestion(rl, prompt) {
 }
 
 /**
- * Resolve user input to a model alias name
- * @param {string} input - User input (number 1-5 or alias name)
- * @returns {string|null} Resolved alias name, or null if invalid
+ * Resolve readline input against the live picks.
+ * @returns {{alias?: string, modelId?: string, noUpgrade?: boolean}|null}
+ *   alias  → numbered/named quick pick (upgrades that alias unless noUpgrade)
+ *   modelId → free-form full model id (default only, no alias writes)
  */
-function resolveChoice(input) {
+function resolveChoice(input, picks, catalog) {
   const num = parseInt(input, 10);
-  if (num >= 1 && num <= MODEL_CHOICES.length) {
-    return MODEL_CHOICES[num - 1].alias;
+  if (num >= 1 && num <= picks.length) {
+    return { alias: picks[num - 1].alias };
   }
-
-  const defaults = getDefaultAliases();
-  if (defaults[input] !== undefined) {
-    return input;
+  if (input.includes('/')) {
+    const known = (catalog || []).some(m => m && m.id === input);
+    if (!known) {
+      console.log(`Warning: '${input}' not found in the model catalog (offline or new model) — using it anyway.`); // eslint-disable-line no-console
+    }
+    return { modelId: input };
+  }
+  const cfg = loadConfig();
+  const aliases = { ...getDefaultAliases(), ...((cfg && cfg.aliases) || {}) };
+  if (aliases[input] !== undefined) {
+    return { alias: input, noUpgrade: true };
   }
-
   return null;
 }
 
@@ -159,8 +157,8 @@ async function seedCatalog(print) {
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Default model selection
- * 3. Config file creation
+ * 2. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 3. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -187,34 +185,50 @@ async function runReadlineSetup() {
     }
     console.log('');
 
+    const { getCatalog } = require('../utils/model-catalog');
+    const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
+    let catalog = [];
+    try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
+    const picks = resolveQuickPicks(catalog);
+
     console.log('Choose your default model:');
     console.log('');
-    for (const choice of MODEL_CHOICES) {
-      console.log(`  ${choice.number}) ${choice.alias} - ${choice.label}`);
-    }
+    picks.forEach((p, i) => {
+      const badge = p.source === 'fallback' ? ' [offline list]' : '';
+      console.log(`  ${i + 1}) ${p.alias} - ${p.label} (${p.blurb}) → ${p.routes.openrouter}${badge}`);
+    });
     console.log('');
 
-    const answer = await askQuestion(rl, 'Pick a default (1-5 or alias name): ');
-    const chosen = resolveChoice(answer);
+    const answer = await askQuestion(rl,
+      `Pick a default (1-${picks.length}, alias name, or any full model id): `);
+    const chosen = resolveChoice(answer, picks, catalog);
 
     if (!chosen) {
-      console.log(`Invalid choice: "${answer}". Using "gemini" as default.`);
-      const cfg = createDefaultConfig('gemini');
-      await seedCatalog();
-      const aliasCount = Object.keys(cfg.aliases).length;
-      console.log('');
-      console.log(`Config created with ${aliasCount} aliases.`);
-      console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
+      console.log(`Invalid choice: "${answer}". Keeping configuration unchanged.`);
       return;
     }
 
-    const cfg = createDefaultConfig(chosen);
+    // Read-modify-write — never rebuild the alias table (no-clobber rule).
+    const cfg = loadConfig() || { aliases: toLiveSeedAliases(catalog) };
+    if (!cfg.aliases) { cfg.aliases = {}; }
+    if (chosen.alias) {
+      cfg.default = chosen.alias;
+      const pick = picks.find(p => p.alias === chosen.alias);
+      if (pick && !chosen.noUpgrade) {
+        cfg.aliases[chosen.alias] = pick.routes.openrouter || Object.values(pick.routes)[0];
+      } else if (cfg.aliases[chosen.alias] === undefined) {
+        const fallback = getDefaultAliases()[chosen.alias];
+        if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
+      }
+    } else {
+      cfg.default = chosen.modelId;
+    }
+    saveConfig(cfg);
     await seedCatalog();
-    const aliasCount = Object.keys(cfg.aliases).length;
 
     console.log('');
-    console.log(`Default model set to: ${chosen}`);
-    console.log(`Config created with ${aliasCount} aliases.`);
+    console.log(`Default model set to: ${cfg.default}`);
+    console.log(`Config saved (${Object.keys(cfg.aliases).length} aliases).`);
     console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
   } finally {
     rl.close();
@@ -276,5 +290,4 @@ module.exports = {
   runReadlineSetup,
   runApiKeySetup,
   seedCatalog,
-  MODEL_CHOICES,
 };

package/src/utils/curated-models.js

@@ -1,77 +1,120 @@
-/**
- * Curated Models — THE single source of truth for default model lists.
- *
- * Three consumers derive from this module (F5 anti-drift):
- *   - src/utils/config.js DEFAULT_ALIASES   (toDefaultAliases)
- *   - electron/setup-ui-model.js MODEL_CHOICES (getCuratedModels)
- *   - src/sidecar/setup.js MODEL_CHOICES      (getCuratedModels)
- * Never hand-edit a model id anywhere else. `amicus models --check`
- * audits every route here against the live catalog.
+/** Family definitions + pinned fallbacks for the wizard model picker (v2). */
+/*
+ * Families are MATCH RULES over the live catalog, not pinned truths:
+ * src/utils/quick-picks.js resolves each family to the current catalog
+ * flagship at setup time. The pinned `fallback` ids are used only when
+ * the catalog cannot resolve a route (offline / unkeyed provider) and to
+ * derive the static DEFAULT_ALIASES (runtime alias resolution must never
+ * wait on the network). `amicus models --check` audits every pinned route
+ * here against the live catalog AND warns when a fallback falls behind
+ * the live resolution.
  */
 
 'use strict';
 
 /**
- * Card entries (shown as wizard quick picks). `routes` maps provider →
- * full model id; the openrouter route doubles as the default alias target.
- * Direct (non-openrouter) route ids MUST be verified against the provider
- * whenever they change.
+ * Wizard quick-pick families. `idPattern` matches the model segment after
+ * `<vendorPath>/` (openrouter ns) or `<provider>/` (direct ns).
+ * `directProviders` lists direct namespaces the quick-picks resolver may
+ * resolve live from the catalog. A per-provider `fallback` entry is
+ * OPTIONAL: when absent and the catalog cannot resolve that namespace,
+ * the direct route is omitted (no pinned guess is better than a wrong one).
+ * `gpt`'s pattern intentionally matches any plain numeric flagship id
+ * (gpt-5.5, gpt-6) and excludes suffixed variants (-pro/-mini/-codex).
+ * Pinned ids verified against the live catalog 2026-06-11.
  */
-const CARDS = [
-  { alias: 'gemini', label: 'Gemini 3.1 Flash Lite', blurb: 'fast, large context',
-    routes: { openrouter: 'openrouter/google/gemini-3.1-flash-lite-preview',
-              google: 'google/gemini-3.1-flash-lite-preview' } },
-  { alias: 'gemini-pro', label: 'Gemini 3.1 Pro', blurb: 'advanced reasoning',
-    routes: { openrouter: 'openrouter/google/gemini-3.1-pro-preview',
-              google: 'google/gemini-3.1-pro-preview' } },
-  { alias: 'gpt', label: 'GPT-5.4', blurb: 'strong coding',
-    routes: { openrouter: 'openrouter/openai/gpt-5.4',
-              openai: 'openai/gpt-5.4' } },
-  { alias: 'opus', label: 'Claude Opus 4.6', blurb: 'deep analysis',
-    routes: { openrouter: 'openrouter/anthropic/claude-opus-4.6',
-              anthropic: 'anthropic/claude-opus-4-6' } },
-  { alias: 'deepseek', label: 'DeepSeek v3.2', blurb: 'open-source',
-    routes: { openrouter: 'openrouter/deepseek/deepseek-v3.2' } },
+const FAMILIES = [
+  { alias: 'gemini', label: 'Gemini Flash-class', blurb: 'fast, large context',
+    vendorPath: 'google',
+    idPattern: /^gemini-[\d.]+-flash(-preview|-exp|-latest)?$/,
+    directProviders: ['google'],
+    fallback: { openrouter: 'openrouter/google/gemini-3.5-flash',
+                google: 'google/gemini-3.5-flash' } },
+  { alias: 'gemini-pro', label: 'Gemini Pro-class', blurb: 'advanced reasoning',
+    vendorPath: 'google',
+    idPattern: /^gemini-[\d.]+-pro(-preview|-exp|-latest)?$/,
+    directProviders: ['google'],
+    fallback: { openrouter: 'openrouter/google/gemini-3.1-pro-preview' } },
+  { alias: 'gpt', label: 'GPT flagship', blurb: 'strong coding',
+    vendorPath: 'openai',
+    idPattern: /^gpt-[\d.]+$/,
+    directProviders: ['openai'],
+    fallback: { openrouter: 'openrouter/openai/gpt-5.5' } },
+  { alias: 'opus', label: 'Claude Opus-class', blurb: 'deep analysis',
+    vendorPath: 'anthropic',
+    idPattern: /^claude-opus-[\d.-]+$/,
+    directProviders: ['anthropic'],
+    fallback: { openrouter: 'openrouter/anthropic/claude-opus-4.8',
+                anthropic: 'anthropic/claude-opus-4-6' } },
+  { alias: 'deepseek', label: 'DeepSeek flagship', blurb: 'open-source',
+    vendorPath: 'deepseek',
+    idPattern: /^deepseek-v[\d.]+(-pro)?$/,
+    directProviders: ['deepseek'],
+    fallback: { openrouter: 'openrouter/deepseek/deepseek-v4-pro',
+                deepseek: 'deepseek/deepseek-chat' } },
 ];
 
-/** Alias-only entries (no wizard card); openrouter route only. */
+/**
+ * Alias-only entries (no wizard quick pick); openrouter route only.
+ * Refreshed against the live catalog 2026-06-11.
+ */
 const CARDLESS = [
-  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.4-pro' } },
+  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.5-pro' } },
   // codex: newest codex-specific model on OpenRouter (verified 2026-06-09).
   { alias: 'codex', routes: { openrouter: 'openrouter/openai/gpt-5.3-codex' } },
   { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
   { alias: 'sonnet', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
   { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5' } },
-  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.5-397b-a17b' } },
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.7-max' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
-  { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.5-flash-02-23' } },
-  { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-large-2512' } },
+  { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
+  { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },
   { alias: 'devstral', routes: { openrouter: 'openrouter/mistralai/devstral-2512' } },
-  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5' } },
-  { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.5' } },
+  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5.1' } },
+  { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.7' } },
   { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },
-  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.5' } },
-  { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-mini' } },
+  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.6' } },
+  { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-lite' } },
 ];
 
-/** @returns {Array<{alias,label,blurb,routes}>} card entries (wizard quick picks) */
-function getCuratedModels() {
-  return CARDS.map(c => ({ ...c, routes: { ...c.routes } }));
+/**
+ * @returns {Array} shallow-spread copies of the family definitions;
+ * `idPattern` is intentionally a shared RegExp reference — safe because
+ * none use the g/y flags (no lastIndex state) and callers treat it read-only.
+ */
+function getFamilies() {
+  return FAMILIES.map(f => ({
+    ...f,
+    directProviders: [...f.directProviders],
+    fallback: { ...f.fallback },
+  }));
 }
 
-/** @returns {Object<string,string>} alias → preferred route (openrouter first) */
+/**
+ * @returns {Object<string,string>} alias → pinned route (openrouter first). STATIC — runtime-safe.
+ */
 function toDefaultAliases() {
   const out = {};
-  for (const e of [...CARDS, ...CARDLESS]) {
+  for (const f of FAMILIES) {
+    out[f.alias] = f.fallback.openrouter || Object.values(f.fallback)[0];
+  }
+  for (const e of CARDLESS) {
     out[e.alias] = e.routes.openrouter || Object.values(e.routes)[0];
   }
   return out;
 }
 
-/** @returns {Array<{alias,provider,model}>} every route of every entry, flattened */
+/**
+ * @returns {Array<{alias,provider,model}>} every pinned route, flattened (for the alias audit).
+ */
 function listCuratedRoutes() {
   const out = [];
-  for (const e of [...CARDS, ...CARDLESS]) {
+  for (const f of FAMILIES) {
+    for (const [provider, model] of Object.entries(f.fallback)) {
+      out.push({ alias: f.alias, provider, model });
+    }
+  }
+  for (const e of CARDLESS) {
     for (const [provider, model] of Object.entries(e.routes)) {
       out.push({ alias: e.alias, provider, model });
     }
@@ -79,4 +122,4 @@ function listCuratedRoutes() {
   return out;
 }
 
-module.exports = { getCuratedModels, toDefaultAliases, listCuratedRoutes };
+module.exports = { getFamilies, toDefaultAliases, listCuratedRoutes };

package/src/utils/lifecycle.js

@@ -12,7 +12,7 @@
 // when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
 // `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
 // interactive Electron flow that must never be force-exited).
-const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'read', 'abort', 'fanout', 'models']);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'read', 'abort', 'fanout', 'models', 'key' /* local-only: no OpenCode server, no stray handles */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {

package/src/utils/model-fetcher.js

@@ -20,7 +20,8 @@ const PROVIDER_FAMILY_NAMES = {
   openrouter: 'OpenRouter',
   google: 'Google',
   openai: 'OpenAI',
-  anthropic: 'Anthropic'
+  anthropic: 'Anthropic',
+  deepseek: 'DeepSeek'
 };
 
 /** Provider API configs for fetching model lists */
@@ -68,6 +69,19 @@ const PROVIDER_FETCH_CONFIG = {
         pricing: null
       }));
     }
+  },
+  deepseek: {
+    url: 'https://api.deepseek.com/models',
+    authHeader: (key) => ({ 'Authorization': `Bearer ${key}` }),
+    normalize: (body) => {
+      const data = JSON.parse(body);
+      return (data.data || []).map(m => ({
+        id: `deepseek/${m.id}`,
+        name: m.id,
+        contextLength: null,
+        pricing: null
+      }));
+    }
   }
 };
 
@@ -75,7 +89,7 @@ const FETCH_TIMEOUT_MS = 5000;
 
 /**
  * Fetch models from a single provider API
- * @param {string} provider - Provider name (openrouter, google, openai, anthropic)
+ * @param {string} provider - Provider name (openrouter, google, openai, anthropic, deepseek)
  * @param {string} key - API key
  * @returns {Promise<Array<{id: string, name: string, contextLength: number|null, pricing: {prompt: string|null, completion: string|null}|null}>>} Normalized model list
  */