amicus 1.0.0

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

@@ -0,0 +1,218 @@
+/**
+ * Setup UI - Alias Editor Script
+ *
+ * Returns the inline JS for alias search, inline edit,
+ * delete, and add custom alias handlers.
+ * Extracted from setup-ui.js to keep file sizes under 300 lines.
+ */
+
+/**
+ * Build the alias editor JS for inline inclusion in the wizard script
+ * @returns {string} JavaScript source (no <script> tags)
+ */
+function buildAliasScript() {
+  return `
+  // Alias editor: search
+  var aliasSearchInput = $('alias-search');
+  if (aliasSearchInput) {
+    aliasSearchInput.addEventListener('input', function() {
+      var q = this.value.toLowerCase();
+      document.querySelectorAll('.alias-group').forEach(function(group) {
+        var rows = group.querySelectorAll('.alias-row');
+        var anyVisible = false;
+        rows.forEach(function(row) {
+          var name = row.getAttribute('data-alias') || '';
+          var model = (row.querySelector('.alias-model') || {}).textContent || '';
+          var match = !q || name.includes(q) || model.toLowerCase().includes(q);
+          row.style.display = match ? '' : 'none';
+          if (match) { anyVisible = true; }
+        });
+        group.style.display = anyVisible ? '' : 'none';
+        if (q && anyVisible) { group.open = true; }
+        if (!q) { group.open = false; }
+      });
+    });
+  }
+
+  // Helper: filter model groups by a keyword (alias name)
+  // Splits keyword on hyphens so "gemini-pro" matches "gemini-3-pro-preview"
+  function filterModels(groups, keyword) {
+    if (!keyword || !groups || groups.length === 0) { return groups; }
+    var parts = keyword.toLowerCase().split('-').filter(function(p) { return p.length > 0; });
+    var filtered = [];
+    groups.forEach(function(g) {
+      var matching = g.models.filter(function(m) {
+        var id = m.id.toLowerCase();
+        var name = (m.name || '').toLowerCase();
+        return parts.every(function(p) { return id.includes(p) || name.includes(p); });
+      });
+      if (matching.length > 0) {
+        filtered.push({ family: g.family, models: matching });
+      }
+    });
+    // Fall back to all models when no matches found
+    if (filtered.length === 0) { return groups; }
+    return filtered;
+  }
+
+  // Helper: build a model <select> dropdown from window.availableModels
+  function buildModelSelect(currentValue, cls, filterKeyword) {
+    var select = document.createElement('select');
+    select.className = cls || 'alias-model-select';
+    var groups = filterModels(window.availableModels, filterKeyword);
+    if (groups && groups.length > 0) {
+      groups.forEach(function(g) {
+        var optgroup = document.createElement('optgroup');
+        optgroup.label = g.family;
+        g.models.forEach(function(m) {
+          var opt = document.createElement('option');
+          opt.value = m.id;
+          opt.textContent = m.name || m.id;
+          if (m.id === currentValue) { opt.selected = true; }
+          optgroup.appendChild(opt);
+        });
+        select.appendChild(optgroup);
+      });
+    } else {
+      // Fallback: flat list from DEFAULT_ALIASES values
+      var seen = {};
+      Object.values(defaultAliases).forEach(function(v) {
+        if (!seen[v]) {
+          var opt = document.createElement('option');
+          opt.value = v; opt.textContent = v;
+          if (v === currentValue) { opt.selected = true; }
+          select.appendChild(opt);
+          seen[v] = true;
+        }
+      });
+    }
+    // If current value not in options, add it
+    if (currentValue && !select.querySelector('option[value="' + CSS.escape(currentValue) + '"]')) {
+      var custom = document.createElement('option');
+      custom.value = currentValue; custom.textContent = currentValue; custom.selected = true;
+      select.insertBefore(custom, select.firstChild);
+    }
+    return select;
+  }
+
+  // Alias editor: inline edit
+  document.addEventListener('click', function(e) {
+    var nameSpan = e.target.closest('.alias-name');
+    var modelSpan = e.target.closest('.alias-model');
+    var span = nameSpan || modelSpan;
+    if (!span) { return; }
+    var row = span.closest('.alias-row');
+    if (!row || row.classList.contains('alias-deleted')) { return; }
+    var isName = !!nameSpan;
+    var origValue = span.textContent;
+    var origAlias = row.getAttribute('data-alias');
+
+    if (isName) {
+      var input = document.createElement('input');
+      input.className = 'alias-name-input';
+      input.value = origValue;
+      span.replaceWith(input);
+      input.focus();
+      function commitName() {
+        var newVal = input.value.trim();
+        var newSpan = document.createElement('span');
+        newSpan.className = 'alias-name';
+        newSpan.textContent = newVal || origValue;
+        input.replaceWith(newSpan);
+        if (newVal && newVal !== origAlias) {
+          aliasEdits[origAlias] = null;
+          var modelEl = row.querySelector('.alias-model') || row.querySelector('.alias-model-select');
+          var modelVal = modelEl ? (modelEl.value || modelEl.textContent) : '';
+          aliasEdits[newVal] = modelVal || defaultAliases[origAlias];
+          row.setAttribute('data-alias', newVal);
+          var delBtn = row.querySelector('.alias-delete');
+          if (delBtn) { delBtn.setAttribute('data-alias', newVal); }
+        }
+      }
+      input.addEventListener('blur', commitName);
+      input.addEventListener('keydown', function(ev) { if (ev.key === 'Enter') { input.blur(); } });
+    } else {
+      var select = buildModelSelect(origValue, 'alias-model-select', origAlias);
+      span.replaceWith(select);
+      select.focus();
+      function commitModel() {
+        var newVal = select.value;
+        var newSpan = document.createElement('span');
+        newSpan.className = 'alias-model';
+        newSpan.textContent = newVal || origValue;
+        select.replaceWith(newSpan);
+        if (newVal && newVal !== origValue) {
+          aliasEdits[origAlias] = newVal;
+        }
+      }
+      select.addEventListener('change', commitModel);
+      select.addEventListener('blur', commitModel);
+    }
+  });
+
+  // Alias editor: delete
+  document.addEventListener('click', function(e) {
+    var btn = e.target.closest('.alias-delete');
+    if (!btn) { return; }
+    var alias = btn.getAttribute('data-alias');
+    if (!alias) { return; }
+    var row = btn.closest('.alias-row');
+    if (!row) { return; }
+    row.classList.add('alias-deleted');
+    if (defaultAliases[alias]) {
+      aliasEdits[alias] = null;
+    } else {
+      delete aliasEdits[alias];
+    }
+  });
+
+  // Alias editor: add custom shortcut
+  var addBtn = $('alias-add-btn');
+  if (addBtn) {
+    addBtn.addEventListener('click', function() {
+      var row = document.createElement('div');
+      row.className = 'alias-row';
+      var nameInput = document.createElement('input');
+      nameInput.className = 'alias-name-input';
+      nameInput.placeholder = 'shortcut';
+      var arrow = document.createElement('span');
+      arrow.className = 'alias-arrow';
+      arrow.textContent = '\\u2192';
+      var modelSelect = buildModelSelect('', 'alias-model-select');
+      var delBtn = document.createElement('button');
+      delBtn.className = 'alias-delete';
+      delBtn.textContent = '\\u00d7';
+      row.appendChild(nameInput);
+      row.appendChild(arrow);
+      row.appendChild(modelSelect);
+      row.appendChild(delBtn);
+      var editor = document.querySelector('.alias-editor');
+      if (editor) { editor.insertBefore(row, addBtn); }
+      nameInput.focus();
+      function commitNew() {
+        var n = nameInput.value.trim();
+        var m = modelSelect.value;
+        if (n && m) {
+          aliasEdits[n] = m;
+          row.setAttribute('data-alias', n);
+          var ns = document.createElement('span');
+          ns.className = 'alias-name'; ns.textContent = n;
+          nameInput.replaceWith(ns);
+          var ms = document.createElement('span');
+          ms.className = 'alias-model'; ms.textContent = m;
+          modelSelect.replaceWith(ms);
+          delBtn.setAttribute('data-alias', n);
+        }
+      }
+      modelSelect.addEventListener('change', commitNew);
+      nameInput.addEventListener('keydown', function(ev) { if (ev.key === 'Enter') { nameInput.blur(); commitNew(); } });
+      delBtn.addEventListener('click', function() {
+        var a = row.getAttribute('data-alias');
+        if (a) { delete aliasEdits[a]; }
+        row.remove();
+      });
+    });
+  }`;
+}
+
+module.exports = { buildAliasScript };

package/electron/setup-ui-aliases.js

@@ -0,0 +1,85 @@
+/**
+ * Setup UI - Alias Editor
+ *
+ * Builds collapsible alias groups with search, inline editing,
+ * delete, and add functionality for the setup wizard Step 3.
+ */
+
+/** Grouping metadata for the 20 default aliases */
+const ALIAS_GROUPS = [
+  { name: 'Gemini', keys: ['gemini', 'gemini-pro'] },
+  { name: 'GPT', keys: ['gpt', 'gpt-pro', 'codex'] },
+  { name: 'Claude', keys: ['claude', 'sonnet', 'opus', 'haiku'] },
+  { name: 'DeepSeek', keys: ['deepseek'] },
+  { name: 'Qwen', keys: ['qwen', 'qwen-coder', 'qwen-flash'] },
+  { name: 'Mistral', keys: ['mistral', 'devstral'] },
+  { name: 'Other', keys: ['glm', 'minimax', 'grok', 'kimi', 'seed'] },
+];
+
+/**
+ * Build the HTML fragment for the alias editor section
+ * @param {Object<string,string>} aliases - Map of alias name to model string
+ * @returns {string} HTML fragment with search, groups, rows, and add button
+ */
+function buildAliasEditorHTML(aliases) {
+  const searchInput = `<input type="text" id="alias-search" class="alias-search" placeholder="Search aliases..." autocomplete="off" spellcheck="false">`;
+
+  const groups = ALIAS_GROUPS.map(group => {
+    const rows = group.keys
+      .filter(key => aliases[key] !== undefined)
+      .map(key => {
+        const model = aliases[key];
+        return `<div class="alias-row" data-alias="${key}">` +
+          `<span class="alias-name">${key}</span>` +
+          `<span class="alias-arrow">\u2192</span>` +
+          `<span class="alias-model">${model}</span>` +
+          `<button class="alias-delete" data-alias="${key}">\u00d7</button>` +
+          `</div>`;
+      }).join('\n        ');
+
+    const count = group.keys.filter(key => aliases[key] !== undefined).length;
+
+    return `<details class="alias-group">
+        <summary>${group.name} <span class="alias-count">(${count})</span></summary>
+        ${rows}
+      </details>`;
+  }).join('\n      ');
+
+  // Pick a representative example from actual aliases
+  const exampleAlias = 'gemini';
+  // Fallback literal kept in sync with curated-models (toDefaultAliases().gemini)
+  const exampleModel = aliases[exampleAlias] || 'openrouter/google/gemini-3.1-flash-lite-preview';
+
+  // SVG icons for the example box
+  const terminalIcon = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none"><rect x="1" y="2" width="14" height="12" rx="2" stroke="#D97757" stroke-width="1.5"/><path d="M4 6l2.5 2L4 10" stroke="#D97757" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="M8.5 10H11" stroke="#5A5550" stroke-width="1.5" stroke-linecap="round"/></svg>`;
+  const arrowIcon = `<svg width="20" height="12" viewBox="0 0 20 12" fill="none"><path d="M2 6h14" stroke="#D97757" stroke-width="1.5" stroke-linecap="round"/><path d="M13 2l4 4-4 4" stroke="#D97757" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+  const modelIcon = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none"><circle cx="8" cy="5" r="3" stroke="#6BBF6B" stroke-width="1.5"/><path d="M8 8v3" stroke="#6BBF6B" stroke-width="1.5" stroke-linecap="round"/><circle cx="4" cy="13" r="1.5" stroke="#6BBF6B" stroke-width="1.2"/><circle cx="8" cy="13" r="1.5" stroke="#6BBF6B" stroke-width="1.2"/><circle cx="12" cy="13" r="1.5" stroke="#6BBF6B" stroke-width="1.2"/><path d="M4 11.5L8 11M8 11l4 .5" stroke="#6BBF6B" stroke-width="1" stroke-linecap="round"/></svg>`;
+
+  const exampleBox = `<div class="routing-example">
+        <div class="example-label">How it works</div>
+        <div class="example-flow">
+          <div class="example-step">
+            ${terminalIcon}
+            <span class="example-cmd">amicus start --model <strong>${exampleAlias}</strong></span>
+          </div>
+          <div class="example-connector">${arrowIcon}</div>
+          <div class="example-step">
+            ${modelIcon}
+            <span class="example-model">${exampleModel}</span>
+          </div>
+        </div>
+      </div>`;
+
+  return `<div class="step-content">
+      <h1>Model Routing</h1>
+      <p class="subtitle">When you ask Amicus for help, you can pick which LLM to collaborate with or offload tasks to. These names on the left route to the specific model on the right.</p>
+      ${exampleBox}
+      <div class="alias-editor">
+        ${searchInput}
+        ${groups}
+        <button class="alias-add-btn" id="alias-add-btn">+ Add Custom Route</button>
+      </div>
+    </div>`;
+}
+
+module.exports = { ALIAS_GROUPS, buildAliasEditorHTML };

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

@@ -0,0 +1,115 @@
+/**
+ * Setup UI - Step 1 Key Management Script
+ *
+ * Returns the inline JS for provider selection, key input,
+ * test/save, eye toggle, and remove handlers.
+ * Extracted from setup-ui.js to keep file sizes under 300 lines.
+ */
+
+/**
+ * Build the key management JS for inline inclusion in the wizard script
+ * @returns {string} JavaScript source (no <script> tags)
+ */
+function buildKeysScript() {
+  return `
+  // Step 1: Provider selection & key management
+  document.querySelectorAll('.provider-btn').forEach(function(btn) {
+    btn.addEventListener('click', function() {
+      var id = this.getAttribute('data-provider');
+      var prov = providers.find(function(p) { return p.id === id; });
+      if (!prov) { return; }
+      selectedProvider = prov;
+      document.querySelectorAll('.provider-btn').forEach(function(b) { b.classList.remove('selected'); });
+      this.classList.add('selected');
+      keySection.classList.add('visible');
+      keyLabel.textContent = prov.name + ' API Key';
+      keyInput.placeholder = prov.placeholder;
+      if (keyHints[prov.id]) {
+        keyInput.value = keyHints[prov.id]; keyInput.type = 'text'; keyValid = false;
+        setInputState('valid');
+        statusMsg.textContent = 'Key configured \\u2714'; statusMsg.className = 'status-valid';
+        removeBtn.style.display = '';
+      } else {
+        keyInput.value = ''; keyInput.type = 'password'; keyValid = false;
+        setInputState(null);
+        statusMsg.textContent = ''; statusMsg.className = '';
+        removeBtn.style.display = 'none';
+      }
+      eyeBtn.classList.remove('active'); keyInput.focus();
+      var a = document.createElement('a');
+      a.href = prov.helpUrl; a.textContent = prov.helpLabel;
+      helpLink.textContent = "Don't have a key? Get one at ";
+      helpLink.appendChild(a);
+      a.addEventListener('click', function(e) {
+        e.preventDefault();
+        if (window.sidecarSetup && window.sidecarSetup.openExternal) { window.sidecarSetup.openExternal(this.href); }
+      });
+    });
+  });
+
+  function setInputState(state) {
+    keyInput.classList.remove('input-valid', 'input-invalid', 'input-testing');
+    if (state) { keyInput.classList.add('input-' + state); }
+  }
+
+  testBtn.addEventListener('click', async function() {
+    if (!selectedProvider) { return; }
+    var key = keyInput.value.trim();
+    if (!key) {
+      statusMsg.textContent = 'Please enter an API key'; statusMsg.className = 'status-invalid';
+      setInputState('invalid'); return;
+    }
+    testBtn.disabled = true; testBtn.textContent = 'Testing...';
+    statusMsg.textContent = ''; statusMsg.className = ''; setInputState('testing');
+    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);
+        configuredKeys[selectedProvider.id] = true;
+        var c = document.getElementById('check-' + selectedProvider.id);
+        if (c) { c.textContent = '\\u2713'; }
+        statusMsg.textContent = 'Saved \\u2713'; statusMsg.className = 'status-valid';
+        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();
+      } else {
+        statusMsg.textContent = res.error || 'Invalid key'; statusMsg.className = 'status-invalid';
+        setInputState('invalid'); keyValid = false;
+      }
+    } catch (_e) {
+      statusMsg.textContent = 'Connection failed'; statusMsg.className = 'status-invalid';
+      setInputState('invalid'); keyValid = false;
+    }
+    testBtn.disabled = false; testBtn.textContent = 'Save \\u0026 Test';
+  });
+
+  keyInput.addEventListener('input', function() {
+    if (keyInput.type === 'text') { keyInput.type = 'password'; }
+    if (keyValid && keyInput.value.trim() !== validatedKey) { keyValid = false; statusMsg.textContent = ''; setInputState(null); }
+    if (!keyInput.value.trim()) { statusMsg.textContent = ''; statusMsg.className = ''; setInputState(null); }
+  });
+  keyInput.addEventListener('keydown', function(e) { if (e.key === 'Enter') { testBtn.click(); } });
+
+  eyeBtn.addEventListener('click', function() {
+    if (keyInput.type === 'password') { keyInput.type = 'text'; eyeBtn.classList.add('active'); }
+    else { keyInput.type = 'password'; eyeBtn.classList.remove('active'); }
+    keyInput.focus();
+  });
+
+  removeBtn.addEventListener('click', async function() {
+    if (!selectedProvider) { return; }
+    removeBtn.disabled = true;
+    try {
+      await window.sidecarSetup.invoke('sidecar:remove-key', selectedProvider.id);
+      delete configuredKeys[selectedProvider.id]; delete keyHints[selectedProvider.id];
+      var c = document.getElementById('check-' + selectedProvider.id);
+      if (c) { c.textContent = ''; }
+      keyInput.value = ''; keyInput.type = 'password'; keyValid = false; setInputState(null);
+      statusMsg.textContent = 'Key removed'; statusMsg.className = 'status-testing';
+      removeBtn.style.display = 'none'; updateNextState();
+    } catch (_e) { statusMsg.textContent = 'Failed to remove'; statusMsg.className = 'status-invalid'; }
+    removeBtn.disabled = false;
+  });`;
+}
+
+module.exports = { buildKeysScript };

package/electron/setup-ui-keys.js

@@ -0,0 +1,97 @@
+/**
+ * Setup UI - Step 1: API Keys
+ *
+ * Builds the HTML for the API key configuration step of the wizard.
+ * Supports multiple providers with checkmarks for configured keys,
+ * test connection, and save per provider.
+ */
+
+/** Provider metadata for the setup form */
+const PROVIDERS = [
+  {
+    id: 'openrouter',
+    name: 'OpenRouter',
+    description: 'Access all models (Gemini, GPT, Claude, etc.) with one key',
+    placeholder: 'sk-or-v1-...',
+    helpUrl: 'https://openrouter.ai/keys',
+    helpLabel: 'openrouter.ai/keys',
+    recommended: true
+  },
+  {
+    id: 'google',
+    name: 'Google AI (Gemini)',
+    description: 'Direct access to Gemini models',
+    placeholder: 'AIza...',
+    helpUrl: 'https://aistudio.google.com/apikey',
+    helpLabel: 'aistudio.google.com/apikey',
+    recommended: false
+  },
+  {
+    id: 'openai',
+    name: 'OpenAI',
+    description: 'Direct access to GPT models',
+    placeholder: 'sk-...',
+    helpUrl: 'https://platform.openai.com/api-keys',
+    helpLabel: 'platform.openai.com/api-keys',
+    recommended: false
+  },
+  {
+    id: 'anthropic',
+    name: 'Anthropic',
+    description: 'Direct access to Claude models',
+    placeholder: 'sk-ant-...',
+    helpUrl: 'https://console.anthropic.com/settings/keys',
+    helpLabel: 'console.anthropic.com/settings/keys',
+    recommended: false
+  }
+];
+
+/**
+ * Build the HTML fragment for Step 1 (API Keys)
+ * @param {Array} providers - Provider metadata array
+ * @returns {string} HTML fragment (not a full document)
+ */
+function buildKeysStepHTML(providers) {
+  const providerCards = providers.map(p => {
+    const badge = p.recommended
+      ? '<span class="badge">Recommended</span>'
+      : '';
+    return `<button class="provider-btn" data-provider="${p.id}">
+        <span class="provider-name">${p.name}${badge}</span>
+        <span class="provider-desc">${p.description}</span>
+        <span class="provider-check" id="check-${p.id}"></span>
+      </button>`;
+  }).join('\n      ');
+
+  return `<div class="step-content">
+    <h1>Configure API Keys</h1>
+    <p class="subtitle">Add at least one API key to get started.</p>
+
+    <div class="provider-list" id="provider-list">
+      ${providerCards}
+    </div>
+
+    <div class="key-section" id="key-section">
+      <label class="field-label" id="key-label" for="api-key-input">API Key</label>
+      <div class="input-row">
+        <div class="input-wrap">
+          <input id="api-key-input" type="password" placeholder="" autocomplete="off" spellcheck="false">
+          <button class="eye-btn" id="eye-btn" type="button" title="Show/hide key">
+            <svg id="eye-icon" width="16" height="16" viewBox="0 0 16 16" fill="none">
+              <path d="M8 3C4.4 3 1.4 5.4.5 8c.9 2.6 3.9 5 7.5 5s6.6-2.4 7.5-5c-.9-2.6-3.9-5-7.5-5z" stroke="currentColor" stroke-width="1.2" fill="none"/>
+              <circle cx="8" cy="8" r="2" stroke="currentColor" stroke-width="1.2" fill="none"/>
+            </svg>
+          </button>
+        </div>
+        <button class="test-btn" id="test-btn">Save &amp; Test</button>
+      </div>
+      <div class="key-actions">
+        <span id="status-msg"></span>
+        <button class="remove-btn" id="remove-btn" type="button" style="display:none">Remove key</button>
+      </div>
+      <p class="help-link" id="help-link"></p>
+    </div>
+  </div>`;
+}
+
+module.exports = { buildKeysStepHTML, PROVIDERS };

package/electron/setup-ui-model.js

@@ -0,0 +1,138 @@
+/**
+ * Setup UI - Step 2: Default Model Selection
+ *
+ * Builds the HTML for the model selection step of the wizard.
+ * Renders radio card choices with provider routing and pre-selection support.
+ * Models are disabled when no configured API key matches their routes.
+ */
+
+const { getCuratedModels } = require('../src/utils/curated-models');
+/**
+ * Wizard quick-pick cards \u2014 derived from curated-models (F5).
+ * @type {Array<{alias: string, label: string, routes: Object<string,string>}>}
+ */
+const MODEL_CHOICES = getCuratedModels().map(c => ({
+  alias: c.alias, label: `${c.label} \u2014 ${c.blurb}`, routes: c.routes
+}));
+
+const PROVIDER_NAMES = {
+  openrouter: 'OpenRouter',
+  google: 'Google AI',
+  openai: 'OpenAI',
+  anthropic: 'Anthropic'
+};
+
+/**
+ * Check if a model has at least one route with a configured key.
+ * When no keys are configured at all (empty configuredKeys), all models are available
+ * to allow the initial render before Step 1 completes.
+ * @param {string[]} providers - Route provider IDs for this model
+ * @param {Object<string,boolean>} configuredKeys - Which providers have keys
+ * @returns {boolean}
+ */
+function isModelAvailable(providers, configuredKeys) {
+  const hasAnyKey = Object.values(configuredKeys).some(v => v);
+  if (!hasAnyKey) { return true; }
+  return providers.some(p => configuredKeys[p]);
+}
+
+/**
+ * Find the best available provider for a model's static route text.
+ * Prefers the first provider with a configured key; falls back to first provider.
+ * @param {string[]} providers - Route provider IDs
+ * @param {Object<string,boolean>} configuredKeys - Which providers have keys
+ * @returns {string} Provider ID to display
+ */
+function bestAvailableProvider(providers, configuredKeys) {
+  const withKey = providers.find(p => configuredKeys[p]);
+  return withKey || providers[0];
+}
+
+/**
+ * Search-over-catalog section (F5). Hidden until the wizard script confirms
+ * a non-empty catalog; rows are rendered client-side from the get-catalog IPC.
+ * @returns {string} HTML fragment
+ */
+function buildModelSearchHTML() {
+  return `<div id="model-search-section" style="display:none">
+      <div class="search-head">
+        <input type="text" id="model-search-input" placeholder="Search all models (id or name)..." autocomplete="off">
+        <button class="icon-btn" id="model-search-refresh" title="Refresh catalog">&#x21bb;</button>
+      </div>
+      <div id="model-search-meta" class="search-meta"></div>
+      <div id="model-search-results" class="search-results"></div>
+    </div>`;
+}
+
+/**
+ * Build the HTML fragment for Step 2 (Model Selection)
+ * @param {Array<{alias: string, label: string, routes: Object<string,string>}>} choices
+ * @param {string} [selectedAlias] - Pre-selected alias, defaults to first available choice
+ * @param {Object<string,boolean>} [configuredKeys] - Provider IDs the user has keys for
+ * @returns {string} HTML fragment
+ */
+function buildModelStepHTML(choices, selectedAlias, configuredKeys = {}) {
+  // Determine availability for each model
+  const availability = choices.map(c => {
+    const providers = Object.keys(c.routes);
+    return { alias: c.alias, available: isModelAvailable(providers, configuredKeys) };
+  });
+
+  // Select: prefer selectedAlias if available, else first available model
+  const availableAliases = availability.filter(a => a.available).map(a => a.alias);
+  let selected;
+  if (selectedAlias && availableAliases.includes(selectedAlias)) {
+    selected = selectedAlias;
+  } else if (availableAliases.length > 0) {
+    selected = availableAliases[0];
+  } else {
+    selected = choices[0].alias;
+  }
+
+  const cards = choices.map(c => {
+    const providers = Object.keys(c.routes);
+    const available = providers.filter(p => configuredKeys[p]);
+    const modelAvailable = availability.find(a => a.alias === c.alias).available;
+    const checked = (c.alias === selected && modelAvailable) ? 'checked' : '';
+    const disabled = modelAvailable ? '' : ' disabled';
+    const cardClass = modelAvailable ? 'model-card' : 'model-card model-unavailable';
+    const hasMultipleRoutes = providers.length >= 2;
+    const showToggle = available.length >= 2;
+    const bestProvider = bestAvailableProvider(providers, configuredKeys);
+
+    let routeHtml = '';
+    if (!modelAvailable) {
+      routeHtml = '<span class="no-key-hint">No API key configured</span>';
+    } else if (hasMultipleRoutes) {
+      const pills = providers.map(p => {
+        const isActive = (showToggle && p === bestProvider) || (!showToggle && p === bestProvider);
+        const cls = isActive ? 'route-pill active' : 'route-pill';
+        return `<button class="${cls}" data-alias="${c.alias}" data-provider="${p}">${PROVIDER_NAMES[p]}</button>`;
+      }).join('');
+      const toggleDisplay = showToggle ? '' : ' style="display:none"';
+      const staticDisplay = showToggle ? ' style="display:none"' : '';
+      routeHtml = `<span class="route-toggle" data-alias="${c.alias}"${toggleDisplay}>${pills}</span>`;
+      routeHtml += `<span class="route-static" data-alias="${c.alias}"${staticDisplay}>via ${PROVIDER_NAMES[bestProvider]}</span>`;
+    } else {
+      routeHtml = `<span class="route-static">via ${PROVIDER_NAMES[bestProvider]}</span>`;
+    }
+    return `<label class="${cardClass}">
+        <input type="radio" name="default-model" value="${c.alias}" ${checked}${disabled}>
+        <span class="model-alias">${c.alias}</span>
+        <span class="model-label">${c.label}</span>
+        ${routeHtml}
+      </label>`;
+  }).join('\n      ');
+
+  return `<div class="step-content">
+    <h1>Choose Default Model</h1>
+    <p class="subtitle">Pick the model to use when no --model flag is given.</p>
+
+    <div class="model-list" id="model-list">
+      ${cards}
+    </div>
+    ${buildModelSearchHTML()}
+  </div>`;
+}
+
+module.exports = { buildModelSearchHTML, buildModelStepHTML, MODEL_CHOICES, PROVIDER_NAMES };