amicus 3.1.1 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.1.1",
+  "version": "3.2.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,27 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-07-16
+
+### Added
+
+- **Cost-aware per-provider default model picker at key-add.** Adding a provider API key (`amicus key
+  <provider>`, the setup wizard, or the Electron key step) now offers a picker that pre-selects a
+  **balanced**-tier model instead of the priciest flagship, shows live `$/M` input pricing, and writes
+  your choice as a vendor-named alias (e.g. `--model anthropic`) — seeding your overall default
+  (`config.default`) on your first key. Applies to direct model vendors (OpenAI, Anthropic, Google,
+  DeepSeek).
+- **`routing.tier` preference** (`frontier` | `balanced` | `economy`, default `balanced`) biasing the
+  picker's per-vendor pre-selection.
+- A one-time onboarding tip on `amicus start` pointing existing users to the new picker.
+
+### Changed
+
+- Model aliases now resolve their per-gateway executable ids **by model**, so user-defined and
+  vendor-named aliases route correctly across the direct and OpenRouter gateways (extends the v3.1.1
+  gateway-correct-ids fix beyond the curated defaults). An alias whose value is an explicit
+  `openrouter/…` id still forces OpenRouter.
+
 ## [3.1.1] - 2026-07-16
 
 ### Fixed

package/README.md

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

package/electron/ipc-setup.js

@@ -42,6 +42,26 @@ function registerSetupHandlers(getMainWindow) {
             require('../src/utils/model-catalog').refreshCatalog().catch(() => {});
           } catch { /* best-effort */ }
         });
+        // Task 8: per-provider default picker choices for the key step.
+        // Per-provider defaults only make sense for DIRECT model vendors --
+        // openrouter is the GATEWAY, not a vendor, so it's skipped entirely
+        // (mirrors provider-default-prompt.js's runProviderDefaultFlow gate;
+        // this path calls the picker core directly instead of that
+        // readline-oriented helper, so it re-checks isDirectProvider itself).
+        const { isDirectProvider } = require('../src/utils/provider-registry');
+        if (isDirectProvider(provider)) {
+          try {
+            const { getCatalog } = require('../src/utils/model-catalog');
+            const { buildProviderDefaultChoices } = require('../src/utils/provider-default-picker');
+            const catalog = await getCatalog();
+            result.providerDefault = buildProviderDefaultChoices(provider, { catalog });
+          } catch (err) {
+            logger.error('save-key providerDefault error', { error: err.message });
+            result.providerDefault = null;
+          }
+        } else {
+          result.providerDefault = null;
+        }
       }
       return result;
     } catch (err) {
@@ -50,6 +70,19 @@ function registerSetupHandlers(getMainWindow) {
     }
   });
 
+  // Task 8: apply a per-provider default picker choice. Read-modify-write,
+  // no-clobber -- applyProviderDefault only ever writes aliases[vendor] and
+  // seeds config.default when absent (see provider-default-picker.js).
+  ipcMain.handle('sidecar:set-provider-default', (_event, provider, chosenId) => {
+    try {
+      const { applyProviderDefault } = require('../src/utils/provider-default-picker');
+      return applyProviderDefault(provider, chosenId, { seedDefaultIfAbsent: true });
+    } catch (err) {
+      logger.error('set-provider-default handler error', { error: err.message });
+      return { success: false, error: err.message };
+    }
+  });
+
   ipcMain.handle('sidecar:remove-key', async (_event, provider) => {
     try {
       const { removeApiKey } = require('../src/utils/api-key-store');

package/electron/preload-setup.js

@@ -22,7 +22,8 @@ contextBridge.exposeInMainWorld('sidecarSetup', {
       'sidecar:get-api-keys',
       'sidecar:get-catalog',
       'sidecar:refresh-catalog',
-      'sidecar:fetch-free-models'
+      'sidecar:fetch-free-models',
+      'sidecar:set-provider-default'
     ];
     if (!allowedChannels.includes(channel)) {
       throw new Error(`IPC channel not allowed: ${channel}`);

package/electron/setup-ui-keys-script.js

@@ -19,6 +19,8 @@ function buildKeysScript() {
       var prov = providers.find(function(p) { return p.id === id; });
       if (!prov) { return; }
       selectedProvider = prov;
+      // Task 8: a picker rendered for the previously-selected provider is stale here.
+      if (window.hideProviderDefaultPicker) { window.hideProviderDefaultPicker(); }
       document.querySelectorAll('.provider-btn').forEach(function(b) { b.classList.remove('selected'); });
       this.classList.add('selected');
       keySection.classList.add('visible');
@@ -64,7 +66,7 @@ function buildKeysScript() {
     try {
       var res = await window.sidecarSetup.invoke('sidecar:validate-key', selectedProvider.id, key);
       if (res.valid) {
-        await window.sidecarSetup.invoke('sidecar:save-key', selectedProvider.id, key);
+        var saveResult = await window.sidecarSetup.invoke('sidecar:save-key', selectedProvider.id, key);
         configuredKeys[selectedProvider.id] = true;
         var c = document.getElementById('check-' + selectedProvider.id);
         if (c) { c.textContent = '\\u2713'; }
@@ -72,6 +74,10 @@ function buildKeysScript() {
         setInputState('valid'); keyValid = true; validatedKey = key;
         keyHints[selectedProvider.id] = key.slice(0, 8) + '\\u2022'.repeat(Math.min(key.length - 8, 12));
         removeBtn.style.display = ''; updateNextState();
+        // Task 8: inline per-provider default picker beneath the just-saved key.
+        if (window.renderProviderDefaultPicker) {
+          window.renderProviderDefaultPicker(selectedProvider.id, selectedProvider.name, saveResult && saveResult.providerDefault);
+        }
       } else {
         statusMsg.textContent = res.error || 'Invalid key'; statusMsg.className = 'status-invalid';
         setInputState('invalid'); keyValid = false;
@@ -107,6 +113,7 @@ function buildKeysScript() {
       keyInput.value = ''; keyInput.type = 'password'; keyValid = false; setInputState(null);
       statusMsg.textContent = 'Key removed'; statusMsg.className = 'status-testing';
       removeBtn.style.display = 'none'; updateNextState();
+      if (window.hideProviderDefaultPicker) { window.hideProviderDefaultPicker(); }
     } catch (_e) { statusMsg.textContent = 'Failed to remove'; statusMsg.className = 'status-invalid'; }
     removeBtn.disabled = false;
   });`;

package/electron/setup-ui-provider-default.js

@@ -0,0 +1,101 @@
+/**
+ * Setup UI — Per-provider default model picker (Part 2, Task 8).
+ *
+ * Rendered inline in the key step (Step 1), beneath the just-saved key, once
+ * `sidecar:save-key` (ipc-setup.js) returns a non-null `providerDefault` for a
+ * DIRECT provider (google/openai/anthropic/deepseek — never the openrouter
+ * gateway; see ipc-setup.js's own isDirectProvider guard, mirroring the skip
+ * rule in provider-default-prompt.js's runProviderDefaultFlow).
+ *
+ * Split into its own file (rather than growing setup-ui-keys.js /
+ * setup-ui-keys-script.js) per the existing setup-ui-* convention (see
+ * setup-ui-council.js, another Step-content add-on with its own HTML +
+ * script pair).
+ *
+ * Row data (from src/utils/provider-default-picker.js's
+ * buildProviderDefaultChoices): { preselectedId, rows: [{id, name,
+ * contextLength, pricePerMInput, isPreselected}] }. Row name/pricing come
+ * straight from the live model catalog, so the runtime script below builds
+ * rows via createElement/textContent (never innerHTML string interpolation)
+ * — the same convention Step 2's renderSearchResults uses for catalog rows.
+ */
+'use strict';
+
+/** Static (initially hidden) container the key step's picker renders into. */
+function buildProviderDefaultSectionHTML() {
+  return `<div class="provider-default-section" id="provider-default-section" style="display:none">
+      <div class="provider-default-label" id="provider-default-label">Default model</div>
+      <div class="provider-default-list" id="provider-default-list"></div>
+    </div>`;
+}
+
+/**
+ * Browser-only JS: exposes window.renderProviderDefaultPicker(provider,
+ * providerName, providerDefault) and window.hideProviderDefaultPicker(),
+ * wired to apply the pick via sidecar:set-provider-default
+ * (src/utils/provider-default-picker.js's applyProviderDefault,
+ * read-modify-write, no-clobber — see ipc-setup.js). Selecting a row (or
+ * leaving the preselection untouched) both apply the same way: the
+ * preselected id is applied immediately on render, and a change event
+ * re-applies whichever row the user picks instead.
+ * @returns {string} JavaScript source (no <script> tags)
+ */
+function buildProviderDefaultScript() {
+  return `
+  // Task 8: per-provider default picker, inline in the key step.
+  (function() {
+    var section = document.getElementById('provider-default-section');
+    var label = document.getElementById('provider-default-label');
+    var list = document.getElementById('provider-default-list');
+
+    function fmtPrice(p) { return (p === null || p === undefined) ? 'n/a' : '$' + Number(p).toFixed(2) + '/M in'; }
+    function fmtCtx(n) { return (n === null || n === undefined) ? '' : ' \\u00b7 ctx ' + n; }
+
+    function applyChoice(provider, chosenId) {
+      if (!provider || !chosenId) { return; }
+      window.sidecarSetup.invoke('sidecar:set-provider-default', provider, chosenId).catch(function() {});
+    }
+
+    function buildRow(provider, row) {
+      var rowEl = document.createElement('label');
+      rowEl.className = 'provider-default-row';
+      var radio = document.createElement('input');
+      radio.type = 'radio'; radio.name = 'provider-default-' + provider;
+      radio.value = row.id; radio.checked = !!row.isPreselected;
+      var text = document.createElement('span');
+      text.className = 'provider-default-text';
+      text.textContent = row.name + fmtCtx(row.contextLength) + ' \\u00b7 ' + fmtPrice(row.pricePerMInput);
+      rowEl.appendChild(radio); rowEl.appendChild(text);
+      if (row.isPreselected) {
+        var badge = document.createElement('span');
+        badge.className = 'pick-badge'; badge.textContent = 'recommended';
+        rowEl.appendChild(badge);
+      }
+      radio.addEventListener('change', function() { if (radio.checked) { applyChoice(provider, row.id); } });
+      return rowEl;
+    }
+
+    window.hideProviderDefaultPicker = function() {
+      if (!section) { return; }
+      section.style.display = 'none';
+      if (list) { list.innerHTML = ''; }
+    };
+
+    window.renderProviderDefaultPicker = function(provider, providerName, providerDefault) {
+      if (!section || !list) { return; }
+      if (!providerDefault || !Array.isArray(providerDefault.rows) || providerDefault.rows.length === 0) {
+        window.hideProviderDefaultPicker(); return;
+      }
+      if (label) { label.textContent = 'Default model for ' + (providerName || provider); }
+      list.innerHTML = '';
+      providerDefault.rows.forEach(function(row) { list.appendChild(buildRow(provider, row)); });
+      section.style.display = '';
+      // No-selection case: the preselected row is already checked above, so
+      // applying it immediately covers "advance without touching the list".
+      applyChoice(provider, providerDefault.preselectedId);
+    };
+  })();
+  `;
+}
+
+module.exports = { buildProviderDefaultSectionHTML, buildProviderDefaultScript };

package/electron/setup-ui-styles.js

@@ -415,7 +415,19 @@ function __rawWizardCSS() {
     content: ''; position: absolute; inset: 0;
     border-radius: 50%; background: var(--ok);
     animation: amicusPulse 1.6s var(--ease-out) infinite;
-  }`;
+  }
+
+  /* Per-provider default picker (Step 1, Task 8) */
+  .provider-default-section { margin-top: 14px; }
+  .provider-default-label { font-size: 12px; color: var(--text-muted); margin-bottom: 6px; }
+  .provider-default-list { display: flex; flex-direction: column; gap: 2px; }
+  .provider-default-row {
+    display: flex; align-items: center; gap: 8px;
+    padding: 6px 10px; font-size: 12px; color: var(--text); cursor: pointer;
+    border-radius: var(--r-6);
+  }
+  .provider-default-row:hover { background: var(--surface-hover); }
+  .provider-default-row input[type="radio"] { accent-color: var(--accent); flex-shrink: 0; }`;
 }
 
 function buildWizardCSS() {

package/electron/setup-ui.js

@@ -6,6 +6,7 @@ const { buildWizardCSS } = require('./setup-ui-styles');
 const { buildKeysScript } = require('./setup-ui-keys-script');
 const { buildAliasScript } = require('./setup-ui-alias-script');
 const { buildCouncilSectionHTML, buildCouncilScript } = require('./setup-ui-council');
+const { buildProviderDefaultSectionHTML, buildProviderDefaultScript } = require('./setup-ui-provider-default');
 const { getDefaultAliases } = require('../src/utils/config');
 const { getBrandName } = require('./toolbar');
 const { resolveQuickPicks } = require('../src/utils/quick-picks');
@@ -40,7 +41,7 @@ function buildSetupHTML(options = {}) {
   <div class="header"><svg width="18" height="18" 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><span class="header-title">${brandName} Setup</span></div>
   <div class="progress-bar"><div class="progress-step active" id="step-1"><span class="progress-dot">1</span><span>API Keys</span></div><div class="progress-connector"></div><div class="progress-step" id="step-2"><span class="progress-dot">2</span><span>Models</span></div><div class="progress-connector"></div><div class="progress-step" id="step-3"><span class="progress-dot">3</span><span>Routing</span></div><div class="progress-connector"></div><div class="progress-step" id="step-4"><span class="progress-dot">4</span><span>Review</span></div></div>
   <div class="content">
-    <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}</div>
+    <div class="wizard-step visible" id="wizard-step-1"><div id="import-notice"></div>${keysHtml}${buildProviderDefaultSectionHTML()}</div>
     <div class="wizard-step" id="wizard-step-2">${modelHtml}${buildCouncilSectionHTML()}</div>
     <div class="wizard-step" id="wizard-step-3">${aliasHtml}</div>
     <div class="wizard-step" id="wizard-step-4">
@@ -63,6 +64,7 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   const keysJs = buildKeysScript();
   const aliasJs = buildAliasScript();
   const councilJs = buildCouncilScript();
+  const providerDefaultJs = buildProviderDefaultScript();
   return `<script>
   window.onerror = function(msg, src, line, col, err) { console.error('WIZARD ERROR:', msg, 'at', src, line, col, err); };
   window.onunhandledrejection = function(e) { console.error('WIZARD UNHANDLED REJECTION:', e.reason); };
@@ -574,6 +576,8 @@ function buildWizardScript(providersJson, modelChoicesJson, providerNamesJson, d
   ${keysJs}
 
   ${councilJs}
+
+  ${providerDefaultJs}
 </script>`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "3.1.1",
+  "version": "3.2.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/src/cli-handlers-run.js

@@ -14,7 +14,7 @@
 
 const { validateStartArgs } = require('./cli');
 const { validateTaskId } = require('./utils/validators');
-const { resolveLaunchModel } = require('./utils/start-helpers');
+const { resolveLaunchModel, maybeOfferProviderDefaults } = 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');
@@ -55,6 +55,14 @@ async function handleStart(args) {
     process.exit(failJson(useJson, { code: validation.code || ERROR_CODES.BAD_ARGS, message: validation.error }));
   }
 
+  // Existing-user one-time onboarding offer (Part 2, Task 9): a non-blocking
+  // notice, printed at most once ever, pointing users who already have direct
+  // provider keys at the per-provider cost-aware default picker. No-ops on
+  // any non-interactive/--json run (see maybeOfferProviderDefaults). Fired
+  // only after validateStartArgs succeeds so a failed first `amicus start`
+  // doesn't burn the one-time flag.
+  maybeOfferProviderDefaults(args);
+
   // Budget gate for solo start
   if (!args['no-cost-gate']) {
     const { lookupPricing } = require('./utils/pricing');

package/src/cli-handlers.js

@@ -159,6 +159,46 @@ async function handleKey(args) {
     process.exit(1);
   }
   console.log(`${provider} key validated and saved.`);
+
+  await offerProviderDefault(provider, args);
+}
+
+/**
+ * After a successful key save, run the per-provider cost-aware default
+ * picker (Part 2, Task 6) and print its one-line summary. Wrapped end-to-end
+ * in try/catch: the key is ALREADY saved by the time this runs, so a picker
+ * failure (offline catalog, bad input, etc.) must never abort `amicus key`
+ * -- it just prints a soft notice instead.
+ * @param {string} provider
+ * @param {object} args parsed CLI args (checked for --json/--quiet to gate interactivity)
+ */
+async function offerProviderDefault(provider, args) {
+  let rl = null;
+  try {
+    const { runProviderDefaultFlow } = require('./utils/provider-default-prompt');
+    const { getCatalog } = require('./utils/model-catalog');
+
+    const interactive = !!process.stdin.isTTY && !args.json && !args.quiet;
+
+    let catalog = [];
+    try { catalog = await getCatalog(); } catch { /* offline/empty: handled gracefully by the picker */ }
+
+    let ask;
+    if (interactive) {
+      const readline = require('readline');
+      rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      ask = (q) => new Promise((resolve) => rl.question(q, (answer) => resolve((answer || '').trim())));
+    }
+
+    const { summaryLine } = await runProviderDefaultFlow(provider, {
+      interactive, ask, catalog, print: console.log,
+    });
+    console.log(summaryLine);
+  } catch (err) {
+    console.log(`Note: couldn't set a per-provider default (${err.message}). Run 'amicus key ${provider}' again later.`);
+  } finally {
+    if (rl) { rl.close(); }
+  }
 }
 
 module.exports = {

package/src/sidecar/setup.js

@@ -187,8 +187,12 @@ async function seedCatalog(print) {
  * (Enter = the vendor-diverse default), seeds aliases + councils.free, and
  * never touches config.default.
  * @param {readline.Interface} rl
+ * @param {Array<object>} [catalogArg] pre-fetched catalog from the caller
+ *   (`runReadlineSetup` already fetches one for the per-provider phase) --
+ *   reused as-is to avoid a second `getCatalog()` round trip. Falls back to
+ *   fetching its own when omitted (e.g. direct unit-test callers).
  */
-async function runFreeCouncilBranch(rl) {
+async function runFreeCouncilBranch(rl, catalogArg) {
   const keys = detectApiKeys();
   if (!keys.openrouter) {
     console.log('');
@@ -196,10 +200,14 @@ async function runFreeCouncilBranch(rl) {
     console.log('Set OPENROUTER_API_KEY and re-run: amicus setup. No changes made.');
     return;
   }
-  const { getCatalog } = require('../utils/model-catalog');
   const { listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS } = require('../utils/free-models');
   let catalog = [];
-  try { catalog = await getCatalog(); } catch (_e) { /* offline */ }
+  if (Array.isArray(catalogArg)) {
+    catalog = catalogArg;
+  } else {
+    const { getCatalog } = require('../utils/model-catalog');
+    try { catalog = await getCatalog(); } catch (_e) { /* offline */ }
+  }
   let free = listFreeModels(catalog);
   if (free.length === 0) {
     console.log('Live free-model list unavailable (offline?) — using a small pinned set.');
@@ -237,14 +245,63 @@ async function runFreeCouncilBranch(rl) {
   console.log('unless you enable data-sharing at openrouter.ai/settings/privacy.');
 }
 
+/**
+ * Run the shared per-provider default-model picker (Task 6, `runProviderDefaultFlow`)
+ * once for each keyed provider, in `foundKeys` detection order -- whichever
+ * comes first seeds `config.default` (`applyProviderDefault`'s
+ * seed-only-when-absent rule; see `provider-default-picker.js`). Each provider
+ * is its own read-modify-write against the real config file, so an alias
+ * written here is on disk before the standard model step's own `loadConfig()`
+ * runs -- no clobber, no shared in-memory object to race.
+ *
+ * Skippable and crash-proof: `runProviderDefaultFlow` already degrades to a
+ * graceful summary line on an empty/offline catalog (never calls `ask`), and
+ * a per-provider try/catch means one provider's failure can't block the rest
+ * of setup (mirrors `cli-handlers.js`'s `offerProviderDefault`). It's also a
+ * graceful no-op for a gateway provider (`openrouter`) -- see
+ * `runProviderDefaultFlow`'s `isDirectProvider` gate.
+ * @param {readline.Interface} rl
+ * @param {string[]} foundKeys keyed providers, in detection order
+ * @param {Array<object>} catalog
+ * @returns {Promise<Set<string>>} vendor alias NAMES actually written this run
+ *   (i.e. `runProviderDefaultFlow` returned a non-null `chosenId`) -- the
+ *   standard model step must not clobber these when a quick-pick family
+ *   alias collides with one (see the standard-model-step alias-upgrade guard).
+ */
+async function runProviderDefaultPickers(rl, foundKeys, catalog) {
+  const written = new Set();
+  if (foundKeys.length === 0) { return written; }
+  const { runProviderDefaultFlow } = require('../utils/provider-default-prompt');
+  for (const provider of foundKeys) {
+    try {
+      const { chosenId, summaryLine } = await runProviderDefaultFlow(provider, {
+        interactive: true,
+        ask: (q) => askQuestion(rl, q),
+        catalog,
+        print: console.log,
+      });
+      if (chosenId) { written.add(provider); }
+      console.log(summaryLine);
+    } catch (err) {
+      console.log(
+        `Note: couldn't set a default for ${provider} (${err.message}). ` +
+        `Run \`amicus key ${provider}\` again later.`
+      );
+    }
+  }
+  console.log('');
+  return written;
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Mode selection (standard or free council)
- * 3. Default model selection from live quick-picks (read-modify-write, no clobber)
- * 4. Config file save
+ * 2. Per-provider default-model picker (Task 7) -- once per keyed provider
+ * 3. Mode selection (standard or free council)
+ * 4. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 5. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -279,18 +336,25 @@ async function runReadlineSetup() {
       await warnOnLowOpenRouterCredit();
     }
 
+    const { getCatalog } = require('../utils/model-catalog');
+    let catalog = [];
+    try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
+
+    // Task 7 (cost-aware defaults P2): per-provider picker, once per keyed
+    // provider, BEFORE the mode prompt -- orthogonal to standard-vs-free-council.
+    // `vendorAliasesWritten` is consulted by the standard model step below so
+    // it never clobbers a vendor alias this phase just wrote (Fix 2).
+    const vendorAliasesWritten = await runProviderDefaultPickers(rl, foundKeys, catalog);
+
     const mode = await askQuestion(rl,
       'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
     if (mode === '2') {
-      await runFreeCouncilBranch(rl);
+      await runFreeCouncilBranch(rl, catalog);
       return;
     }
 
-    const { getCatalog } = require('../utils/model-catalog');
     const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
     const { toCanonicalDefault } = require('../utils/curated-models');
-    let catalog = [];
-    try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
     const picks = resolveQuickPicks(catalog);
 
     console.log('Choose your default model:');
@@ -316,7 +380,12 @@ async function runReadlineSetup() {
     if (chosen.alias) {
       cfg.default = chosen.alias;
       const pick = picks.find(p => p.alias === chosen.alias);
-      if (pick && !chosen.noUpgrade) {
+      // Fix 2: a quick-pick family alias (e.g. 'deepseek') can collide with a
+      // vendor alias the per-provider phase just wrote this run. `config.default`
+      // pointing at that alias name is fine (the user's explicit overall-default
+      // choice), but the alias's VALUE must stay the vendor phase's tier choice --
+      // skip the curated-flagship upgrade so it isn't discarded.
+      if (pick && !chosen.noUpgrade && !vendorAliasesWritten.has(chosen.alias)) {
         cfg.aliases[chosen.alias] = toCanonicalDefault(pick.routes.openrouter || Object.values(pick.routes)[0]);
       } else if (cfg.aliases[chosen.alias] === undefined) {
         const fallback = getDefaultAliases()[chosen.alias];

package/src/utils/config.js

@@ -419,6 +419,60 @@ function markMigrationNotified(vendor) {
   }
 }
 
+/**
+ * Existing-user one-time onboarding offer (Part 2, Task 9). Mirrors
+ * markMigrationNotified's flag pattern: a single boolean persisted at
+ * config.routing.tier_onboarded once the notice has fired, so it never
+ * repeats.
+ * @returns {boolean} true once the notice has fired
+ */
+function hasTierOnboarded() {
+  const config = loadConfig() || {};
+  return !!(config.routing && config.routing.tier_onboarded === true);
+}
+
+/**
+ * Persist the one-time onboarding-notice flag, preserving any other routing
+ * keys (prefer, tier, migration_notified). Best-effort: swallows any
+ * saveConfig failure so a persistence hiccup never breaks the command that
+ * triggered it (mirrors markMigrationNotified).
+ */
+function markTierOnboarded() {
+  try {
+    const config = loadConfig() || {};
+    if (!config.routing || typeof config.routing !== 'object') { config.routing = {}; }
+    config.routing.tier_onboarded = true;
+    saveConfig(config);
+  } catch (_err) {
+    // best-effort: never fail the command over a persistence error
+  }
+}
+
+/** Global cost-tier preference (Part 2, Task 1) — priciest-to-cheapest. */
+const COST_TIERS = ['frontier', 'balanced', 'economy'];
+
+/** @returns {'frontier'|'balanced'|'economy'} config.routing.tier, defaulting/coercing to 'balanced' */
+function getCostTier() {
+  const config = loadConfig() || {};
+  const tier = config.routing && config.routing.tier;
+  return COST_TIERS.includes(tier) ? tier : 'balanced';
+}
+
+/**
+ * Persist the global cost-tier preference under routing.tier, preserving any
+ * other routing keys (prefer, migration_notified).
+ * @param {string} tier one of COST_TIERS
+ * @throws {Error} when tier is not a recognized cost tier
+ */
+function setCostTier(tier) {
+  if (!COST_TIERS.includes(tier)) {
+    throw new Error(`Invalid cost tier '${tier}'. Must be one of: ${COST_TIERS.join(', ')}`);
+  }
+  const config = loadConfig() || {};
+  config.routing = { ...(config.routing || {}), tier };
+  saveConfig(config);
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -440,4 +494,9 @@ module.exports = {
   getRoutingConfig,
   resolveGatewayMode,
   markMigrationNotified,
+  COST_TIERS,
+  getCostTier,
+  setCostTier,
+  hasTierOnboarded,
+  markTierOnboarded,
 };

package/src/utils/curated-models.js

@@ -160,8 +160,10 @@ function listCuratedRoutes() {
  * versioning, distinct model names, etc.). NEVER derive a direct form for
  * these — derivation would emit the wrong (dot) id, or invent a direct id
  * for a model that is OpenRouter-only today (e.g. fable).
+ * Frozen so consumers can only read it (`.has()`) — a frozen Set still
+ * supports lookups, it just can't be `.add()`/`.delete()`/`.clear()`-ed.
  */
-const DIVERGENT_VENDORS = new Set(['anthropic']);
+const DIVERGENT_VENDORS = Object.freeze(new Set(['anthropic']));
 
 /**
  * @param {string} orRoute e.g. 'openrouter/anthropic/claude-sonnet-5'
@@ -212,5 +214,5 @@ function toGatewayRoutes() {
 }
 
 module.exports = {
-  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes
+  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes, DIVERGENT_VENDORS
 };