fraim 2.0.281 → 2.0.283

package/public/first-run/script.js

@@ -1,742 +1,747 @@
-(function () {
-  'use strict';
-
-  const CHECKLIST_EL = document.getElementById('checklist');
-  const PRIMARY_BUTTON = document.getElementById('primary-button');
-  const STATUS_EL = document.getElementById('status');
-  const LEDE_EL = document.getElementById('lede');
-
-  const state = {
-    session: null,
-    activeStep: 'prereqs',
-    configureInFlight: false,
-    configureError: null,
-  };
-
-
-  const STEP_LABELS = {
-    prereqs: 'Prerequisites',
-    agents: 'Local Agents',
-    configure: 'Configure FRAIM',
-    use: 'Use FRAIM',
-  };
-
-  const STEP_ORDER = ['prereqs', 'agents', 'configure', 'use'];
-
-  function setStatus(text, tone) {
-    STATUS_EL.textContent = text || '';
-    if (tone) STATUS_EL.setAttribute('data-tone', tone);
-    else STATUS_EL.removeAttribute('data-tone');
-  }
-
-  function setHeader(title, lede) {
-    const h1El = document.querySelector('.page-header h1');
-    if (h1El) h1El.textContent = title;
-    if (LEDE_EL) LEDE_EL.textContent = lede;
-  }
-
-  async function api(path, method, body) {
-    const headers = {};
-    if (body !== undefined) headers['Content-Type'] = 'application/json';
-    if (state.session && state.session.requestToken) headers['x-fraim-first-run-token'] = state.session.requestToken;
-    const response = await fetch(path, {
-      method: method || 'GET',
-      headers: Object.keys(headers).length > 0 ? headers : undefined,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    if (response.status === 204) return null;
-    const json = await response.json();
-    if (!response.ok) throw new Error(json && json.error ? json.error : `Request failed (status ${response.status}).`);
-    return json;
-  }
-
-  function setSessionFromActionResponse(actionResp) {
-    if (!state.session || !actionResp) return;
-    state.session.state = actionResp.state;
-    state.session.rows = actionResp.rows;
-    state.session.primaryButtonLabel = actionResp.primaryButtonLabel;
-    state.session.currentAgentId = actionResp.state.agentId;
-  }
-
-  function row(id) {
-    return (state.session && state.session.rows || []).find((r) => r.id === id) || null;
-  }
-
-  function requiredPrereqsReady() {
-    const node = row('node');
-    return Boolean(node && node.status === 'ok');
-  }
-
-  function readyAgents() {
-    const installs = state.session && state.session.state ? state.session.state.agentInstalls || {} : {};
-    return Object.entries(installs)
-      .filter(([, entry]) => entry && entry.status === 'ready')
-      .map(([id, entry]) => ({ id, label: entry.label }));
-  }
-
-  function configuredSurfaces() {
-    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
-    return setupResult && Array.isArray(setupResult.configuredSurfaces) ? setupResult.configuredSurfaces : [];
-  }
-
-  function readyAgentLabels() {
-    const labels = new Set();
-    for (const agent of readyAgents()) labels.add(agent.label);
-    for (const surface of configuredSurfaces()) {
-      if (surface && surface.name) labels.add(surface.name);
-    }
-    return Array.from(labels);
-  }
-
-  function slugifyAgentName(name) {
-    return String(name || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-  }
-
-  function isAgentReady(opt) {
-    const installState = state.session && state.session.state && state.session.state.agentInstalls
-      ? state.session.state.agentInstalls[opt.id]
-      : null;
-    if (installState && installState.status === 'ready') return true;
-    return configuredSurfaces().some((surface) => surface && (surface.id === opt.id || surface.name === opt.label));
-  }
-
-  function detectedAgentCount() {
-    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
-    return (setupResult && setupResult.detectedSurfaceCount) || readyAgents().length;
-  }
-
-  function configureReady() {
-    const fraim = row('fraim');
-    return Boolean(fraim && fraim.status === 'ok' && detectedAgentCount() > 0);
-  }
-
-  function chooseActiveStep() {
-    if (!requiredPrereqsReady()) return 'prereqs';
-    if (detectedAgentCount() < 1) return 'agents';
-    if (!configureReady()) return 'configure';
-    return 'use';
-  }
-
-  function iconFor(status) {
-    if (status === 'ok') return '✓';
-    if (status === 'in-progress') return '...';
-    if (status === 'manual-required' || status === 'error') return '!';
-    return '.';
-  }
-
-  function renderShell(renderPane) {
-    CHECKLIST_EL.className = 'setup-shell';
-    CHECKLIST_EL.innerHTML = '';
-    PRIMARY_BUTTON.style.display = 'none';
-    setHeader('Set up FRAIM', 'Complete these steps in order. FRAIM configures itself after a local AI agent is ready.');
-
-    const steps = document.createElement('div');
-    steps.className = 'setup-steps';
-    steps.setAttribute('data-testid', 'setup-stepper');
-
-    for (const step of STEP_ORDER) {
-      const btn = document.createElement('button');
-      btn.type = 'button';
-      btn.className = 'setup-step';
-      btn.setAttribute('data-step', step);
-      btn.setAttribute('aria-current', state.activeStep === step ? 'step' : 'false');
-      btn.setAttribute('data-status', stepStatus(step));
-      btn.disabled = (step === 'configure' && detectedAgentCount() < 1) || (step === 'use' && !configureReady());
-      btn.addEventListener('click', () => {
-        if (btn.disabled) return;
-        state.activeStep = step;
-        render();
-      });
-      const dot = document.createElement('span');
-      dot.className = 'step-dot';
-      dot.textContent = stepStatus(step) === 'done' ? '✓' : String(STEP_ORDER.indexOf(step) + 1);
-      const label = document.createElement('span');
-      label.textContent = STEP_LABELS[step];
-      btn.appendChild(dot);
-      btn.appendChild(label);
-      steps.appendChild(btn);
-    }
-
-    const pane = document.createElement('div');
-    pane.className = 'setup-pane';
-    pane.setAttribute('data-testid', 'setup-pane');
-    renderPane(pane);
-
-    CHECKLIST_EL.appendChild(steps);
-    CHECKLIST_EL.appendChild(pane);
-  }
-
-  function stepStatus(step) {
-    if (step === 'prereqs') return requiredPrereqsReady() ? 'done' : 'active';
-    if (step === 'agents') return detectedAgentCount() > 0 ? 'done' : 'active';
-    if (step === 'configure') return configureReady() ? 'done' : (detectedAgentCount() > 0 ? 'active' : 'locked');
-    if (step === 'use') return configureReady() ? 'active' : 'locked';
-    return 'active';
-  }
-
-  function renderPrereqs(pane) {
-    const h = document.createElement('h2');
-    h.textContent = 'Prerequisites';
-    pane.appendChild(h);
-
-    const list = document.createElement('ul');
-    list.className = 'row-list';
-    for (const id of ['node', 'git']) {
-      const r = row(id);
-      if (!r) continue;
-      const li = document.createElement('li');
-      li.className = 'row';
-      li.setAttribute('data-row-id', r.id);
-      li.setAttribute('data-row-status', r.status);
-      li.innerHTML = `<span class="icon" aria-hidden="true">${iconFor(r.status)}</span><span class="label"></span><span class="verb" data-testid="row-verb"></span>`;
-      li.querySelector('.label').textContent = r.label;
-      li.querySelector('.verb').textContent = r.verb || '';
-      list.appendChild(li);
-    }
-    pane.appendChild(list);
-
-    const btn = button(requiredPrereqsReady() ? 'Next' : 'Check prerequisites', 'primary');
-    btn.setAttribute('data-testid', 'check-prereqs');
-    btn.addEventListener('click', async () => {
-      btn.disabled = true;
-      try {
-        for (const id of ['node', 'git']) {
-          const r = row(id);
-          if (r && r.status !== 'ok') setSessionFromActionResponse(await api(`/api/first-run/rows/${id}/run`, 'POST', {}));
-        }
-        state.activeStep = 'agents';
-        setStatus('Prerequisites are ready.');
-      } catch (err) {
-        setStatus(err.message, 'error');
-      } finally {
-        btn.disabled = false;
-        render();
-      }
-    });
-    pane.appendChild(btn);
-  }
-
-  function renderAgents(pane) {
-    const h = document.createElement('h2');
-    h.textContent = 'Locally installed AI agents';
-    pane.appendChild(h);
-
-    const p = document.createElement('p');
-    p.className = 'pane-copy';
-    p.textContent = detectedAgentCount() > 0
-      ? 'At least one local AI agent is ready. You can add more agents or continue to configure FRAIM.'
-      : 'No problem, we will install AI agents next.';
-    pane.appendChild(p);
-
-    const readyLabels = readyAgentLabels();
-    const readyList = document.createElement('div');
-    readyList.className = readyLabels.length > 0 ? 'ready-strip' : 'ready-strip ready-strip--muted';
-    readyList.setAttribute('data-testid', 'ready-agents');
-    readyList.textContent = readyLabels.length > 0
-      ? `Already installed: ${readyLabels.join(', ')}`
-      : 'Already installed: none detected yet';
-    pane.appendChild(readyList);
-
-    const catalogHeading = document.createElement('h3');
-    catalogHeading.className = 'agent-section-heading';
-    catalogHeading.textContent = 'Supported AI tools and IDEs';
-    pane.appendChild(catalogHeading);
-
-    const catalogCopy = document.createElement('p');
-    catalogCopy.className = 'pane-copy';
-    catalogCopy.textContent = 'FRAIM can configure every supported local agent or IDE it detects. Download links stay available for tools not installed yet.';
-    pane.appendChild(catalogCopy);
-
-    const list = document.createElement('ul');
-    list.className = 'agent-list';
-    list.setAttribute('data-testid', 'supported-agent-list');
-    const supportedAgents = (state.session && state.session.supportedAgents) || [];
-    for (const agent of supportedAgents) {
-      const slug = slugifyAgentName(agent.name);
-      const detected = agent.detected || readyLabels.includes(agent.name);
-      const li = document.createElement('li');
-      li.className = 'agent-row' + (detected ? ' agent-row--detected' : '');
-      li.setAttribute('data-testid', `supported-agent-row-${slug}`);
-
-      const nameSpan = document.createElement('span');
-      nameSpan.className = 'agent-row__name';
-      nameSpan.textContent = agent.name;
-      li.appendChild(nameSpan);
-
-      const actionSpan = document.createElement('span');
-      actionSpan.className = 'agent-row__action';
-      if (detected) {
-        const badge = document.createElement('span');
-        badge.className = 'agent-badge agent-badge--installed';
-        badge.setAttribute('data-testid', `supported-agent-installed-${slug}`);
-        badge.textContent = 'Installed';
-        actionSpan.appendChild(badge);
-      } else if (agent.downloadUrl) {
-        const link = document.createElement('a');
-        link.className = 'agent-download-link';
-        link.href = agent.downloadUrl;
-        link.target = '_blank';
-        link.rel = 'noopener noreferrer';
-        link.textContent = 'Download';
-        link.setAttribute('data-testid', `supported-agent-download-${slug}`);
-        actionSpan.appendChild(link);
-      } else {
-        const unavailable = document.createElement('span');
-        unavailable.className = 'agent-row__muted';
-        unavailable.textContent = 'Manual setup';
-        actionSpan.appendChild(unavailable);
-      }
-      li.appendChild(actionSpan);
-      list.appendChild(li);
-    }
-    pane.appendChild(list);
-
-    const rescanBtn = button('Rescan supported tools', 'ghost');
-    rescanBtn.setAttribute('data-testid', 'rescan-agents');
-    rescanBtn.addEventListener('click', async () => {
-      rescanBtn.disabled = true;
-      rescanBtn.textContent = 'Scanning...';
-      try { await loadSession(false); } finally {
-        state.activeStep = 'agents';
-        render();
-      }
-    });
-    pane.appendChild(rescanBtn);
-
-    const hubHeading = document.createElement('h3');
-    hubHeading.className = 'agent-section-heading';
-    hubHeading.textContent = 'Hub-ready CLI agents';
-    pane.appendChild(hubHeading);
-
-    const hubCopy = document.createElement('p');
-    hubCopy.className = 'pane-copy';
-    hubCopy.textContent = 'FRAIM Hub runs jobs through CLI agents. Set up at least one of these if you plan to launch jobs in Hub.';
-    pane.appendChild(hubCopy);
-
-    const grid = document.createElement('div');
-    grid.className = 'agent-grid';
-    const agentOptions = state.session.agentOptions || [];
-    for (const opt of agentOptions) {
-      const card = document.createElement('div');
-      card.className = 'user-type-card recruit-card';
-      card.setAttribute('data-agent-id', opt.id);
-      card.setAttribute('data-testid', `agent-card-${opt.id}`);
-      const agentReady = isAgentReady(opt);
-
-      const title = document.createElement('strong');
-      title.className = 'card-title';
-      title.textContent = opt.label;
-
-      const desc = document.createElement('p');
-      desc.className = 'card-desc';
-      desc.textContent = agentReady
-        ? 'Already installed and ready for FRAIM.'
-        : `Available to set up: install, sign in, and verify ${opt.label}.`;
-
-      const action = button(agentReady ? 'Ready' : 'Set up', 'secondary');
-      action.disabled = agentReady;
-      action.setAttribute('data-testid', `install-${opt.id}`);
-      action.addEventListener('click', () => openAgentModal(opt));
-
-      card.appendChild(title);
-      card.appendChild(desc);
-      card.appendChild(action);
-      grid.appendChild(card);
-    }
-
-    const byoa = document.createElement('div');
-    byoa.className = 'user-type-card recruit-card byoa-card';
-    byoa.innerHTML = '<strong class="card-title">Bring Your Own Agent</strong><p class="card-desc">Use Cursor, Windsurf, Kiro, VS Code, or another supported local AI tool. If you install a new agent later and want FRAIM to use it, run this command from your project.</p><div class="cmd-block">npx fraim add-ide</div>';
-    grid.appendChild(byoa);
-    pane.appendChild(grid);
-
-    const done = button('Next', 'primary');
-    done.setAttribute('data-testid', 'done-installing-agents');
-    done.disabled = detectedAgentCount() < 1;
-    done.addEventListener('click', () => { state.activeStep = 'configure'; render(); });
-    pane.appendChild(done);
-
-    if (detectedAgentCount() < 1) {
-      const locked = document.createElement('p');
-      locked.className = 'locked-note';
-      locked.textContent = 'Configure FRAIM stays locked until one local AI agent is ready.';
-      pane.appendChild(locked);
-    }
-  }
-
-  async function configureFraim() {
-    if (state.configureInFlight) return;
-    state.configureInFlight = true;
-    state.configureError = null;
-    render();
-    setStatus('Configuring FRAIM for your local AI agents...');
-    try {
-      const resp = await api('/api/first-run/done-recruiting', 'POST', {});
-      setSessionFromActionResponse(resp);
-      setStatus(resp.message, resp.ok ? null : 'error');
-      state.activeStep = 'configure';
-      state.configureError = resp && resp.ok ? null : (resp && resp.message ? resp.message : 'FRAIM setup did not complete.');
-    } catch (err) {
-      state.configureError = err.message;
-      setStatus(state.configureError, 'error');
-    } finally {
-      state.configureInFlight = false;
-      render();
-    }
-  }
-
-  function renderConfigure(pane) {
-    const h = document.createElement('h2');
-    h.textContent = 'Configure FRAIM';
-    pane.appendChild(h);
-
-    if (detectedAgentCount() < 1) {
-      const p = document.createElement('p');
-      p.className = 'pane-copy';
-      p.textContent = 'A local AI agent is required before FRAIM setup can finish.';
-      pane.appendChild(p);
-      const back = button('Choose a local agent', 'primary');
-      back.addEventListener('click', () => { state.activeStep = 'agents'; render(); });
-      pane.appendChild(back);
-      return;
-    }
-
-    if (!configureReady()) {
-      const p = document.createElement('p');
-      p.className = 'pane-copy';
-      p.textContent = state.configureError
-        ? 'FRAIM setup needs attention before you continue.'
-        : 'FRAIM is configuring MCP and local setup files for every ready agent.';
-      pane.appendChild(p);
-      const status = document.createElement('div');
-      status.className = state.configureError ? 'ready-strip ready-strip--error' : 'ready-strip';
-      status.textContent = state.configureError || 'Configuring FRAIM...';
-      pane.appendChild(status);
-      if (state.configureError) {
-        const retry = button('Try again', 'primary');
-        retry.addEventListener('click', configureFraim);
-        pane.appendChild(retry);
-      } else if (!state.configureInFlight) {
-        window.setTimeout(configureFraim, 0);
-      }
-      return;
-    }
-
-    const success = document.createElement('div');
-    success.className = 'ready-strip';
-    success.textContent = 'FRAIM setup succeeded for your ready local AI agents.';
-    pane.appendChild(success);
-    const next = button('Next', 'primary');
-    next.addEventListener('click', () => { state.activeStep = 'use'; render(); });
-    pane.appendChild(next);
-  }
-
-  function renderUseFraim(pane) {
-    const h = document.createElement('h2');
-    h.textContent = 'Use FRAIM';
-    pane.appendChild(h);
-
-    const p = document.createElement('p');
-    p.className = 'pane-copy';
-    p.textContent = 'FRAIM is set up to use your ready local AI agents. Choose where you want to work.';
-    pane.appendChild(p);
-    renderStartWorkingChoices(pane);
-  }
-
-  function renderStartWorkingChoices(pane) {
-    const choices = document.createElement('div');
-    choices.className = 'choice-grid';
-
-    const ideCard = document.createElement('div');
-    ideCard.className = 'user-type-card user-type-card--featured';
-    ideCard.innerHTML = '<strong class="card-title">In my IDE</strong><p class="card-desc">Use FRAIM inside Claude Code, Codex, Cursor, or the local agent tool you already use.</p>';
-    const ideBtn = button('Continue in my IDE', 'primary');
-    ideBtn.addEventListener('click', async () => {
-      try { await api('/api/first-run/set-preference', 'POST', { choice: 'ide' }); } catch (_) {}
-      const ideData = await api('/api/first-run/ide-commands');
-      renderIdeCommandDisplay(ideData ? ideData.commands : []);
-    });
-    ideCard.appendChild(ideBtn);
-
-    const hubCard = document.createElement('div');
-    hubCard.className = 'user-type-card';
-    hubCard.innerHTML = '<strong class="card-title">In FRAIM Hub</strong><p class="card-desc">Open the Company, Manager, and Projects shell.</p>';
-    const hubBtn = button('Open FRAIM Hub', 'secondary');
-    hubBtn.addEventListener('click', async () => {
-      try { await api('/api/first-run/set-preference', 'POST', { choice: 'hub' }); } catch (_) {}
-      try {
-        hubBtn.disabled = true;
-        setStatus('Opening the FRAIM Hub desktop app...');
-        const openResp = await api('/api/first-run/open-hub', 'POST');
-        if (openResp && openResp.needsAgentSetup) {
-          state.activeStep = 'agents';
-          render();
-          setStatus(openResp.message, 'error');
-          return;
-        }
-        // Issue #866 R1: the Hub opens as the Electron desktop app, so the
-        // first-run tab does not navigate itself to a browser Hub. Confirm and
-        // let the user close this tab.
-        setStatus((openResp && openResp.message) || 'FRAIM Hub is opening in the desktop app. You can close this tab.');
-      } catch (err) {
-        hubBtn.disabled = false;
-        setStatus(err.message, 'error');
-      }
-    });
-    hubCard.appendChild(hubBtn);
-    choices.appendChild(ideCard);
-    choices.appendChild(hubCard);
-    pane.appendChild(choices);
-  }
-
-  function renderIdeCommandDisplay(commands) {
-    renderShell((pane) => {
-      const h = document.createElement('h2');
-      h.textContent = 'Continue in your IDE';
-      pane.appendChild(h);
-      const copy = document.createElement('p');
-      copy.className = 'pane-copy';
-      copy.textContent = 'Restart your IDE so it picks up FRAIM setup, then run:';
-      pane.appendChild(copy);
-      const cmdList = (commands && commands.length > 0) ? commands : ['/fraim onboard this project'];
-      for (const cmd of cmdList) {
-        const row = document.createElement('div');
-        row.className = 'command-row';
-        const block = document.createElement('div');
-        block.className = 'cmd-block';
-        block.textContent = cmd;
-        const copyBtn = button('Copy', 'secondary');
-        copyBtn.setAttribute('aria-label', `Copy command: ${cmd}`);
-        copyBtn.addEventListener('click', async () => {
-          await navigator.clipboard.writeText(cmd);
-          copyBtn.textContent = 'Copied';
-          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
-        });
-        row.appendChild(block);
-        row.appendChild(copyBtn);
-        pane.appendChild(row);
-      }
-      const back = button('Back to choices', 'secondary');
-      back.setAttribute('data-testid', 'back-to-use-fraim');
-      back.addEventListener('click', () => { state.activeStep = 'use'; render(); });
-      pane.appendChild(back);
-    });
-  }
-
-  function openAgentModal(opt) {
-    const overlay = document.createElement('div');
-    overlay.className = 'modal-backdrop';
-    overlay.setAttribute('data-testid', 'agent-install-modal');
-    const modal = document.createElement('div');
-    modal.className = 'modal';
-    modal.setAttribute('role', 'dialog');
-    modal.setAttribute('aria-modal', 'true');
-    modal.innerHTML = `<h2>Set up ${escapeHtml(opt.label)}</h2><p class="install-status" data-testid="agent-install-status">Ready to set up ${escapeHtml(opt.label)}.</p><p class="modal-help">Setup installs the CLI, opens sign-in, and verifies the agent is available before FRAIM uses it.</p>`;
-    const status = modal.querySelector('[data-testid="agent-install-status"]');
-    const actions = document.createElement('div');
-    actions.className = 'install-actions';
-
-    const install = button('Set up', 'primary');
-    const signIn = button(`Sign In to ${opt.label}`, 'secondary');
-    const check = button('Check readiness', 'secondary');
-    const close = button('Close', 'ghost');
-    signIn.disabled = true;
-    check.disabled = true;
-    close.addEventListener('click', () => { overlay.remove(); render(); });
-
-    install.addEventListener('click', async () => {
-      install.disabled = true;
-      status.textContent = `Setting up ${opt.label}...`;
-      try {
-        const result = await api('/api/first-run/install-agent', 'POST', { agentId: opt.id });
-        if (!result || !result.ok) throw new Error(result && result.message ? result.message : 'Setup failed.');
-        status.textContent = `${opt.label} setup started. Sign in next.`;
-        signIn.disabled = false;
-        await loadSession(false);
-      } catch (err) {
-        install.disabled = false;
-        install.textContent = 'Retry';
-        status.textContent = err.message;
-        status.setAttribute('data-tone', 'error');
-        showAgentInstallError(modal, opt, err.message, install, close);
-      }
-    });
-
-    signIn.addEventListener('click', async () => {
-      signIn.disabled = true;
-      status.textContent = 'Opening terminal for sign-in...';
-      try {
-        const result = await api('/api/first-run/trigger-agent-login', 'POST', { agentId: opt.id });
-        status.textContent = result && result.message ? result.message : 'Complete sign-in, then check readiness.';
-        check.disabled = false;
-      } catch (err) {
-        signIn.disabled = false;
-        status.textContent = err.message;
-        status.setAttribute('data-tone', 'error');
-      }
-    });
-
-    check.addEventListener('click', async () => {
-      check.disabled = true;
-      status.textContent = 'Checking that the CLI is installed, signed in, and available on PATH...';
-      try {
-        const result = await api('/api/first-run/check-agent', 'POST', { agentId: opt.id });
-        if (result && result.ready) {
-          status.textContent = `${opt.label} is ready!`;
-          await loadSession(false);
-          setTimeout(() => { overlay.remove(); state.activeStep = 'agents'; render(); }, 250);
-          return;
-        }
-        status.textContent = result && result.message ? result.message : `${opt.label} is not ready yet.`;
-        status.setAttribute('data-tone', 'error');
-        check.disabled = false;
-      } catch (err) {
-        status.textContent = err.message;
-        status.setAttribute('data-tone', 'error');
-        check.disabled = false;
-      }
-    });
-
-    actions.appendChild(install);
-    actions.appendChild(signIn);
-    actions.appendChild(check);
-    actions.appendChild(close);
-    modal.appendChild(actions);
-    overlay.appendChild(modal);
-    document.body.appendChild(overlay);
-    install.focus();
-  }
-
-  function showAgentInstallError(modal, opt, message, retryButton, closeButton) {
-    const existing = modal.querySelector('[data-testid="error-frame"]');
-    if (existing) existing.remove();
-    if (!window.FraimErrorFrame || typeof window.FraimErrorFrame.render !== 'function') return;
-    const frame = window.FraimErrorFrame.render({
-      whatTried: `We tried to set up ${opt.label}.`,
-      whatHappened: message,
-      actions: [
-        { id: 'retry', label: 'Retry', variant: 'primary' },
-        { id: 'alternative', label: 'Choose another agent', variant: 'secondary' },
-        { id: 'manual', label: 'Manual setup help', variant: 'ghost' },
-      ],
-    }, (action) => {
-      if (action.id === 'retry') {
-        retryButton.click();
-      } else if (action.id === 'alternative') {
-        closeButton.click();
-      } else if (action.id === 'manual') {
-        const status = modal.querySelector('[data-testid="agent-install-status"]');
-        if (status) {
-          status.textContent = 'Run npx fraim add-ide for manual setup, then return here when your local agent is ready.';
-          status.removeAttribute('data-tone');
-        }
-      }
-    });
-    modal.appendChild(frame);
-  }
-
-  function button(text, variant) {
-    const btn = document.createElement('button');
-    btn.type = 'button';
-    btn.className = variant === 'primary' ? 'btn btn-primary' : variant === 'ghost' ? 'btn btn-ghost' : 'btn btn-secondary';
-    btn.textContent = text;
-    return btn;
-  }
-
-  function escapeHtml(value) {
-    return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-  }
-
-  async function loadSession(shouldRender) {
-    state.session = await api('/api/first-run/session');
-    if (!state.session.state.agentInstalls) state.session.state.agentInstalls = {};
-    if (shouldRender !== false) {
-      state.activeStep = chooseActiveStep();
-      render();
-    }
-  }
-
-  // Issue #646: when first-run was launched without a key (the no-terminal macOS
-  // installer path), gate the whole wizard behind a paste-your-key step.
-  function renderKeyEntry() {
-    CHECKLIST_EL.className = 'setup-shell';
-    CHECKLIST_EL.innerHTML = '';
-    PRIMARY_BUTTON.style.display = 'none';
-    setHeader('Set up FRAIM', 'Paste the FRAIM key from your account page to get started.');
-
-    const card = document.createElement('div');
-    card.className = 'setup-pane';
-    card.setAttribute('data-testid', 'key-entry');
-
-    const label = document.createElement('label');
-    label.className = 'pane-copy';
-    label.setAttribute('for', 'fraim-key-input');
-    label.textContent = 'Your FRAIM key';
-    card.appendChild(label);
-
-    const input = document.createElement('input');
-    input.type = 'text';
-    input.id = 'fraim-key-input';
-    input.className = 'key-input';
-    input.placeholder = 'fraim_…';
-    input.autocapitalize = 'off';
-    input.autocomplete = 'off';
-    input.spellcheck = false;
-    input.setAttribute('data-testid', 'key-input');
-    card.appendChild(input);
-
-    const err = document.createElement('p');
-    err.className = 'locked-note';
-    err.setAttribute('data-testid', 'key-error');
-    err.hidden = true;
-    card.appendChild(err);
-
-    const submit = button('Continue', 'primary');
-    submit.setAttribute('data-testid', 'key-submit');
-    const onSubmit = async () => {
-      const value = input.value.trim();
-      err.hidden = true;
-      submit.disabled = true;
-      submit.textContent = 'Checking…';
-      try {
-        const resp = await api('/api/first-run/set-key', 'POST', { key: value });
-        state.session = resp.session;
-        if (!state.session.state.agentInstalls) state.session.state.agentInstalls = {};
-        state.activeStep = chooseActiveStep();
-        render();
-      } catch (e) {
-        err.textContent = e.message || 'That key was not accepted. Copy it again from your account page.';
-        err.hidden = false;
-        submit.disabled = false;
-        submit.textContent = 'Continue';
-      }
-    };
-    submit.addEventListener('click', onSubmit);
-    input.addEventListener('keydown', (e) => { if (e.key === 'Enter') onSubmit(); });
-    card.appendChild(submit);
-
-    CHECKLIST_EL.appendChild(card);
-    input.focus();
-  }
-
-  function render() {
-    if (!state.session) return;
-    if (state.session.needsKey) { renderKeyEntry(); return; }
-    if (!STEP_ORDER.includes(state.activeStep)) state.activeStep = chooseActiveStep();
-    renderShell((pane) => {
-      if (state.activeStep === 'prereqs') renderPrereqs(pane);
-      else if (state.activeStep === 'agents') renderAgents(pane);
-      else if (state.activeStep === 'configure') renderConfigure(pane);
-      else renderUseFraim(pane);
-    });
-  }
-
-  PRIMARY_BUTTON.addEventListener('click', () => {
-    state.activeStep = chooseActiveStep();
-    render();
-  });
-
-  loadSession().catch((err) => {
-    setStatus(err.message || 'Could not load first-run.', 'error');
-  });
-}());
+(function () {
+  'use strict';
+
+  const CHECKLIST_EL = document.getElementById('checklist');
+  const PRIMARY_BUTTON = document.getElementById('primary-button');
+  const STATUS_EL = document.getElementById('status');
+  const LEDE_EL = document.getElementById('lede');
+
+  const state = {
+    session: null,
+    activeStep: 'prereqs',
+    configureInFlight: false,
+    configureError: null,
+  };
+
+
+  const STEP_LABELS = {
+    prereqs: 'Prerequisites',
+    agents: 'Local Agents',
+    configure: 'Configure FRAIM',
+    use: 'Use FRAIM',
+  };
+
+  const STEP_ORDER = ['prereqs', 'agents', 'configure', 'use'];
+
+  function setStatus(text, tone) {
+    STATUS_EL.textContent = text || '';
+    if (tone) STATUS_EL.setAttribute('data-tone', tone);
+    else STATUS_EL.removeAttribute('data-tone');
+  }
+
+  function setHeader(title, lede) {
+    const h1El = document.querySelector('.page-header h1');
+    if (h1El) h1El.textContent = title;
+    if (LEDE_EL) LEDE_EL.textContent = lede;
+  }
+
+  async function api(path, method, body) {
+    const headers = {};
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (state.session && state.session.requestToken) headers['x-fraim-first-run-token'] = state.session.requestToken;
+    const response = await fetch(path, {
+      method: method || 'GET',
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (response.status === 204) return null;
+    const json = await response.json();
+    if (!response.ok) throw new Error(json && json.error ? json.error : `Request failed (status ${response.status}).`);
+    return json;
+  }
+
+  function setSessionFromActionResponse(actionResp) {
+    if (!state.session || !actionResp) return;
+    state.session.state = actionResp.state;
+    state.session.rows = actionResp.rows;
+    state.session.primaryButtonLabel = actionResp.primaryButtonLabel;
+    state.session.currentAgentId = actionResp.state.agentId;
+  }
+
+  function row(id) {
+    return (state.session && state.session.rows || []).find((r) => r.id === id) || null;
+  }
+
+  function requiredPrereqsReady() {
+    const node = row('node');
+    return Boolean(node && node.status === 'ok');
+  }
+
+  function readyAgents() {
+    const installs = state.session && state.session.state ? state.session.state.agentInstalls || {} : {};
+    return Object.entries(installs)
+      .filter(([, entry]) => entry && entry.status === 'ready')
+      .map(([id, entry]) => ({ id, label: entry.label }));
+  }
+
+  function configuredSurfaces() {
+    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
+    return setupResult && Array.isArray(setupResult.configuredSurfaces) ? setupResult.configuredSurfaces : [];
+  }
+
+  function readyAgentLabels() {
+    const labels = new Set();
+    for (const agent of readyAgents()) labels.add(agent.label);
+    for (const surface of configuredSurfaces()) {
+      if (surface && surface.name) labels.add(surface.name);
+    }
+    return Array.from(labels);
+  }
+
+  function slugifyAgentName(name) {
+    return String(name || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  }
+
+  function isAgentReady(opt) {
+    const installState = state.session && state.session.state && state.session.state.agentInstalls
+      ? state.session.state.agentInstalls[opt.id]
+      : null;
+    if (installState && installState.status === 'ready') return true;
+    return configuredSurfaces().some((surface) => surface && (surface.id === opt.id || surface.name === opt.label));
+  }
+
+  function detectedAgentCount() {
+    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
+    return (setupResult && setupResult.detectedSurfaceCount) || readyAgents().length;
+  }
+
+  function configureReady() {
+    const fraim = row('fraim');
+    return Boolean(fraim && fraim.status === 'ok' && detectedAgentCount() > 0);
+  }
+
+  function chooseActiveStep() {
+    if (!requiredPrereqsReady()) return 'prereqs';
+    if (detectedAgentCount() < 1) return 'agents';
+    if (!configureReady()) return 'configure';
+    return 'use';
+  }
+
+  function iconFor(status) {
+    if (status === 'ok') return '✓';
+    if (status === 'in-progress') return '...';
+    if (status === 'manual-required' || status === 'error') return '!';
+    return '.';
+  }
+
+  function renderShell(renderPane) {
+    CHECKLIST_EL.className = 'setup-shell';
+    CHECKLIST_EL.innerHTML = '';
+    PRIMARY_BUTTON.style.display = 'none';
+    setHeader('Set up FRAIM', 'Complete these steps in order. FRAIM configures itself after a local AI agent is ready.');
+
+    const steps = document.createElement('div');
+    steps.className = 'setup-steps';
+    steps.setAttribute('data-testid', 'setup-stepper');
+
+    for (const step of STEP_ORDER) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'setup-step';
+      btn.setAttribute('data-step', step);
+      btn.setAttribute('aria-current', state.activeStep === step ? 'step' : 'false');
+      btn.setAttribute('data-status', stepStatus(step));
+      btn.disabled = (step === 'configure' && detectedAgentCount() < 1) || (step === 'use' && !configureReady());
+      btn.addEventListener('click', () => {
+        if (btn.disabled) return;
+        state.activeStep = step;
+        render();
+      });
+      const dot = document.createElement('span');
+      dot.className = 'step-dot';
+      dot.textContent = stepStatus(step) === 'done' ? '✓' : String(STEP_ORDER.indexOf(step) + 1);
+      const label = document.createElement('span');
+      label.textContent = STEP_LABELS[step];
+      btn.appendChild(dot);
+      btn.appendChild(label);
+      steps.appendChild(btn);
+    }
+
+    const pane = document.createElement('div');
+    pane.className = 'setup-pane';
+    pane.setAttribute('data-testid', 'setup-pane');
+    renderPane(pane);
+
+    CHECKLIST_EL.appendChild(steps);
+    CHECKLIST_EL.appendChild(pane);
+  }
+
+  function stepStatus(step) {
+    if (step === 'prereqs') return requiredPrereqsReady() ? 'done' : 'active';
+    if (step === 'agents') return detectedAgentCount() > 0 ? 'done' : 'active';
+    if (step === 'configure') return configureReady() ? 'done' : (detectedAgentCount() > 0 ? 'active' : 'locked');
+    if (step === 'use') return configureReady() ? 'active' : 'locked';
+    return 'active';
+  }
+
+  function renderPrereqs(pane) {
+    const h = document.createElement('h2');
+    h.textContent = 'Prerequisites';
+    pane.appendChild(h);
+
+    const list = document.createElement('ul');
+    list.className = 'row-list';
+    for (const id of ['node', 'git']) {
+      const r = row(id);
+      if (!r) continue;
+      const li = document.createElement('li');
+      li.className = 'row';
+      li.setAttribute('data-row-id', r.id);
+      li.setAttribute('data-row-status', r.status);
+      li.innerHTML = `<span class="icon" aria-hidden="true">${iconFor(r.status)}</span><span class="label"></span><span class="verb" data-testid="row-verb"></span>`;
+      li.querySelector('.label').textContent = r.label;
+      li.querySelector('.verb').textContent = r.verb || '';
+      list.appendChild(li);
+    }
+    pane.appendChild(list);
+
+    const btn = button(requiredPrereqsReady() ? 'Next' : 'Check prerequisites', 'primary');
+    btn.setAttribute('data-testid', 'check-prereqs');
+    btn.addEventListener('click', async () => {
+      btn.disabled = true;
+      try {
+        for (const id of ['node', 'git']) {
+          const r = row(id);
+          if (r && r.status !== 'ok') setSessionFromActionResponse(await api(`/api/first-run/rows/${id}/run`, 'POST', {}));
+        }
+        state.activeStep = 'agents';
+        setStatus('Prerequisites are ready.');
+      } catch (err) {
+        setStatus(err.message, 'error');
+      } finally {
+        btn.disabled = false;
+        render();
+      }
+    });
+    pane.appendChild(btn);
+  }
+
+  function renderAgents(pane) {
+    const h = document.createElement('h2');
+    h.textContent = 'Locally installed AI agents';
+    pane.appendChild(h);
+
+    const p = document.createElement('p');
+    p.className = 'pane-copy';
+    p.textContent = detectedAgentCount() > 0
+      ? 'At least one local AI agent is ready. You can add more agents or continue to configure FRAIM.'
+      : 'No problem, we will install AI agents next.';
+    pane.appendChild(p);
+
+    const readyLabels = readyAgentLabels();
+    const readyList = document.createElement('div');
+    readyList.className = readyLabels.length > 0 ? 'ready-strip' : 'ready-strip ready-strip--muted';
+    readyList.setAttribute('data-testid', 'ready-agents');
+    readyList.textContent = readyLabels.length > 0
+      ? `Already installed: ${readyLabels.join(', ')}`
+      : 'Already installed: none detected yet';
+    pane.appendChild(readyList);
+
+    const catalogHeading = document.createElement('h3');
+    catalogHeading.className = 'agent-section-heading';
+    catalogHeading.textContent = 'Supported AI tools and IDEs';
+    pane.appendChild(catalogHeading);
+
+    const catalogCopy = document.createElement('p');
+    catalogCopy.className = 'pane-copy';
+    catalogCopy.textContent = 'FRAIM can configure every supported local agent or IDE it detects. Download links stay available for tools not installed yet.';
+    pane.appendChild(catalogCopy);
+
+    const list = document.createElement('ul');
+    list.className = 'agent-list';
+    list.setAttribute('data-testid', 'supported-agent-list');
+    const supportedAgents = (state.session && state.session.supportedAgents) || [];
+    for (const agent of supportedAgents) {
+      const slug = slugifyAgentName(agent.name);
+      const detected = agent.detected || readyLabels.includes(agent.name);
+      const li = document.createElement('li');
+      li.className = 'agent-row' + (detected ? ' agent-row--detected' : '');
+      li.setAttribute('data-testid', `supported-agent-row-${slug}`);
+
+      const nameSpan = document.createElement('span');
+      nameSpan.className = 'agent-row__name';
+      nameSpan.textContent = agent.name;
+      li.appendChild(nameSpan);
+
+      const actionSpan = document.createElement('span');
+      actionSpan.className = 'agent-row__action';
+      if (detected) {
+        const badge = document.createElement('span');
+        badge.className = 'agent-badge agent-badge--installed';
+        badge.setAttribute('data-testid', `supported-agent-installed-${slug}`);
+        badge.textContent = 'Installed';
+        actionSpan.appendChild(badge);
+      } else if (agent.downloadUrl) {
+        const link = document.createElement('a');
+        link.className = 'agent-download-link';
+        link.href = agent.downloadUrl;
+        link.target = '_blank';
+        link.rel = 'noopener noreferrer';
+        link.textContent = 'Download';
+        link.setAttribute('data-testid', `supported-agent-download-${slug}`);
+        actionSpan.appendChild(link);
+      } else {
+        const unavailable = document.createElement('span');
+        unavailable.className = 'agent-row__muted';
+        unavailable.textContent = 'Manual setup';
+        actionSpan.appendChild(unavailable);
+      }
+      li.appendChild(actionSpan);
+      list.appendChild(li);
+    }
+    pane.appendChild(list);
+
+    const rescanBtn = button('Rescan supported tools', 'ghost');
+    rescanBtn.setAttribute('data-testid', 'rescan-agents');
+    rescanBtn.addEventListener('click', async () => {
+      rescanBtn.disabled = true;
+      rescanBtn.textContent = 'Scanning...';
+      try { await loadSession(false); } finally {
+        state.activeStep = 'agents';
+        render();
+      }
+    });
+    pane.appendChild(rescanBtn);
+
+    const hubHeading = document.createElement('h3');
+    hubHeading.className = 'agent-section-heading';
+    hubHeading.textContent = 'Hub-ready CLI agents';
+    pane.appendChild(hubHeading);
+
+    const hubCopy = document.createElement('p');
+    hubCopy.className = 'pane-copy';
+    hubCopy.textContent = 'FRAIM Hub runs jobs through CLI agents. Set up at least one of these if you plan to launch jobs in Hub.';
+    pane.appendChild(hubCopy);
+
+    const grid = document.createElement('div');
+    grid.className = 'agent-grid';
+    const agentOptions = state.session.agentOptions || [];
+    for (const opt of agentOptions) {
+      const card = document.createElement('div');
+      card.className = 'user-type-card recruit-card';
+      card.setAttribute('data-agent-id', opt.id);
+      card.setAttribute('data-testid', `agent-card-${opt.id}`);
+      const agentReady = isAgentReady(opt);
+
+      const title = document.createElement('strong');
+      title.className = 'card-title';
+      title.textContent = opt.label;
+
+      const desc = document.createElement('p');
+      desc.className = 'card-desc';
+      desc.textContent = agentReady
+        ? 'Already installed and ready for FRAIM.'
+        : `Available to set up: install, sign in, and verify ${opt.label}.`;
+
+      const action = button(agentReady ? 'Ready' : 'Set up', 'secondary');
+      action.disabled = agentReady;
+      action.setAttribute('data-testid', `install-${opt.id}`);
+      action.addEventListener('click', () => openAgentModal(opt));
+
+      card.appendChild(title);
+      card.appendChild(desc);
+      card.appendChild(action);
+      grid.appendChild(card);
+    }
+
+    const byoa = document.createElement('div');
+    byoa.className = 'user-type-card recruit-card byoa-card';
+    byoa.innerHTML = '<strong class="card-title">Bring Your Own Agent</strong><p class="card-desc">Use Cursor, Windsurf, Kiro, VS Code, or another supported local AI tool. If you install a new agent later and want FRAIM to use it, run this command from your project.</p><div class="cmd-block">npx fraim add-ide</div>';
+    grid.appendChild(byoa);
+    pane.appendChild(grid);
+
+    const done = button('Next', 'primary');
+    done.setAttribute('data-testid', 'done-installing-agents');
+    done.disabled = detectedAgentCount() < 1;
+    done.addEventListener('click', () => { state.activeStep = 'configure'; render(); });
+    pane.appendChild(done);
+
+    if (detectedAgentCount() < 1) {
+      const locked = document.createElement('p');
+      locked.className = 'locked-note';
+      locked.textContent = 'Configure FRAIM stays locked until one local AI agent is ready.';
+      pane.appendChild(locked);
+    }
+  }
+
+  async function configureFraim() {
+    if (state.configureInFlight) return;
+    state.configureInFlight = true;
+    state.configureError = null;
+    render();
+    setStatus('Configuring FRAIM for your local AI agents...');
+    try {
+      const resp = await api('/api/first-run/done-recruiting', 'POST', {});
+      setSessionFromActionResponse(resp);
+      setStatus(resp.message, resp.ok ? null : 'error');
+      state.activeStep = 'configure';
+      state.configureError = resp && resp.ok ? null : (resp && resp.message ? resp.message : 'FRAIM setup did not complete.');
+    } catch (err) {
+      state.configureError = err.message;
+      setStatus(state.configureError, 'error');
+    } finally {
+      state.configureInFlight = false;
+      render();
+    }
+  }
+
+  function renderConfigure(pane) {
+    const h = document.createElement('h2');
+    h.textContent = 'Configure FRAIM';
+    pane.appendChild(h);
+
+    if (detectedAgentCount() < 1) {
+      const p = document.createElement('p');
+      p.className = 'pane-copy';
+      p.textContent = 'A local AI agent is required before FRAIM setup can finish.';
+      pane.appendChild(p);
+      const back = button('Choose a local agent', 'primary');
+      back.addEventListener('click', () => { state.activeStep = 'agents'; render(); });
+      pane.appendChild(back);
+      return;
+    }
+
+    if (!configureReady()) {
+      const p = document.createElement('p');
+      p.className = 'pane-copy';
+      p.textContent = state.configureError
+        ? 'FRAIM setup needs attention before you continue.'
+        : 'FRAIM is configuring MCP and local setup files for every ready agent.';
+      pane.appendChild(p);
+      const status = document.createElement('div');
+      status.className = state.configureError ? 'ready-strip ready-strip--error' : 'ready-strip';
+      status.textContent = state.configureError || 'Configuring FRAIM...';
+      pane.appendChild(status);
+      if (state.configureError) {
+        const retry = button('Try again', 'primary');
+        retry.addEventListener('click', configureFraim);
+        pane.appendChild(retry);
+      } else if (!state.configureInFlight) {
+        window.setTimeout(configureFraim, 0);
+      }
+      return;
+    }
+
+    const success = document.createElement('div');
+    success.className = 'ready-strip';
+    success.textContent = 'FRAIM setup succeeded for your ready local AI agents.';
+    pane.appendChild(success);
+    const next = button('Next', 'primary');
+    next.addEventListener('click', () => { state.activeStep = 'use'; render(); });
+    pane.appendChild(next);
+  }
+
+  function renderUseFraim(pane) {
+    const h = document.createElement('h2');
+    h.textContent = 'Use FRAIM';
+    pane.appendChild(h);
+
+    const p = document.createElement('p');
+    p.className = 'pane-copy';
+    p.textContent = 'FRAIM is set up to use your ready local AI agents. Choose where you want to work.';
+    pane.appendChild(p);
+    renderStartWorkingChoices(pane);
+  }
+
+  function renderStartWorkingChoices(pane) {
+    const choices = document.createElement('div');
+    choices.className = 'choice-grid';
+
+    const ideCard = document.createElement('div');
+    ideCard.className = 'user-type-card user-type-card--featured';
+    ideCard.innerHTML = '<strong class="card-title">In my IDE</strong><p class="card-desc">Use FRAIM inside Claude Code, Codex, Cursor, or the local agent tool you already use.</p>';
+    const ideBtn = button('Continue in my IDE', 'primary');
+    ideBtn.addEventListener('click', async () => {
+      try { await api('/api/first-run/set-preference', 'POST', { choice: 'ide' }); } catch (_) {}
+      const ideData = await api('/api/first-run/ide-commands');
+      renderIdeCommandDisplay(ideData ? ideData.commands : []);
+    });
+    ideCard.appendChild(ideBtn);
+
+    const hubCard = document.createElement('div');
+    hubCard.className = 'user-type-card';
+    hubCard.innerHTML = '<strong class="card-title">In FRAIM Hub</strong><p class="card-desc">Open the Company, Manager, and Projects shell.</p>';
+    const hubBtn = button('Open FRAIM Hub', 'secondary');
+    hubBtn.addEventListener('click', async () => {
+      try { await api('/api/first-run/set-preference', 'POST', { choice: 'hub' }); } catch (_) {}
+      try {
+        hubBtn.disabled = true;
+        setStatus('Opening the FRAIM Hub desktop app...');
+        const openResp = await api('/api/first-run/open-hub', 'POST');
+        if (openResp && openResp.needsAgentSetup) {
+          state.activeStep = 'agents';
+          render();
+          setStatus(openResp.message, 'error');
+          return;
+        }
+        if (openResp && openResp.hubUrl) {
+          setStatus('FRAIM is ready. Opening Hub in this app...');
+          window.location.replace(openResp.hubUrl);
+          return;
+        }
+        // Issue #866 R1: the Hub opens as the Electron desktop app, so the
+        // first-run tab does not navigate itself to a browser Hub. Confirm and
+        // let the user close this tab.
+        setStatus((openResp && openResp.message) || 'FRAIM Hub is opening in the desktop app. You can close this tab.');
+      } catch (err) {
+        hubBtn.disabled = false;
+        setStatus(err.message, 'error');
+      }
+    });
+    hubCard.appendChild(hubBtn);
+    choices.appendChild(ideCard);
+    choices.appendChild(hubCard);
+    pane.appendChild(choices);
+  }
+
+  function renderIdeCommandDisplay(commands) {
+    renderShell((pane) => {
+      const h = document.createElement('h2');
+      h.textContent = 'Continue in your IDE';
+      pane.appendChild(h);
+      const copy = document.createElement('p');
+      copy.className = 'pane-copy';
+      copy.textContent = 'Restart your IDE so it picks up FRAIM setup, then run:';
+      pane.appendChild(copy);
+      const cmdList = (commands && commands.length > 0) ? commands : ['/fraim onboard this project'];
+      for (const cmd of cmdList) {
+        const row = document.createElement('div');
+        row.className = 'command-row';
+        const block = document.createElement('div');
+        block.className = 'cmd-block';
+        block.textContent = cmd;
+        const copyBtn = button('Copy', 'secondary');
+        copyBtn.setAttribute('aria-label', `Copy command: ${cmd}`);
+        copyBtn.addEventListener('click', async () => {
+          await navigator.clipboard.writeText(cmd);
+          copyBtn.textContent = 'Copied';
+          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
+        });
+        row.appendChild(block);
+        row.appendChild(copyBtn);
+        pane.appendChild(row);
+      }
+      const back = button('Back to choices', 'secondary');
+      back.setAttribute('data-testid', 'back-to-use-fraim');
+      back.addEventListener('click', () => { state.activeStep = 'use'; render(); });
+      pane.appendChild(back);
+    });
+  }
+
+  function openAgentModal(opt) {
+    const overlay = document.createElement('div');
+    overlay.className = 'modal-backdrop';
+    overlay.setAttribute('data-testid', 'agent-install-modal');
+    const modal = document.createElement('div');
+    modal.className = 'modal';
+    modal.setAttribute('role', 'dialog');
+    modal.setAttribute('aria-modal', 'true');
+    modal.innerHTML = `<h2>Set up ${escapeHtml(opt.label)}</h2><p class="install-status" data-testid="agent-install-status">Ready to set up ${escapeHtml(opt.label)}.</p><p class="modal-help">Setup installs the CLI, opens sign-in, and verifies the agent is available before FRAIM uses it.</p>`;
+    const status = modal.querySelector('[data-testid="agent-install-status"]');
+    const actions = document.createElement('div');
+    actions.className = 'install-actions';
+
+    const install = button('Set up', 'primary');
+    const signIn = button(`Sign In to ${opt.label}`, 'secondary');
+    const check = button('Check readiness', 'secondary');
+    const close = button('Close', 'ghost');
+    signIn.disabled = true;
+    check.disabled = true;
+    close.addEventListener('click', () => { overlay.remove(); render(); });
+
+    install.addEventListener('click', async () => {
+      install.disabled = true;
+      status.textContent = `Setting up ${opt.label}...`;
+      try {
+        const result = await api('/api/first-run/install-agent', 'POST', { agentId: opt.id });
+        if (!result || !result.ok) throw new Error(result && result.message ? result.message : 'Setup failed.');
+        status.textContent = `${opt.label} setup started. Sign in next.`;
+        signIn.disabled = false;
+        await loadSession(false);
+      } catch (err) {
+        install.disabled = false;
+        install.textContent = 'Retry';
+        status.textContent = err.message;
+        status.setAttribute('data-tone', 'error');
+        showAgentInstallError(modal, opt, err.message, install, close);
+      }
+    });
+
+    signIn.addEventListener('click', async () => {
+      signIn.disabled = true;
+      status.textContent = 'Opening terminal for sign-in...';
+      try {
+        const result = await api('/api/first-run/trigger-agent-login', 'POST', { agentId: opt.id });
+        status.textContent = result && result.message ? result.message : 'Complete sign-in, then check readiness.';
+        check.disabled = false;
+      } catch (err) {
+        signIn.disabled = false;
+        status.textContent = err.message;
+        status.setAttribute('data-tone', 'error');
+      }
+    });
+
+    check.addEventListener('click', async () => {
+      check.disabled = true;
+      status.textContent = 'Checking that the CLI is installed, signed in, and available on PATH...';
+      try {
+        const result = await api('/api/first-run/check-agent', 'POST', { agentId: opt.id });
+        if (result && result.ready) {
+          status.textContent = `${opt.label} is ready!`;
+          await loadSession(false);
+          setTimeout(() => { overlay.remove(); state.activeStep = 'agents'; render(); }, 250);
+          return;
+        }
+        status.textContent = result && result.message ? result.message : `${opt.label} is not ready yet.`;
+        status.setAttribute('data-tone', 'error');
+        check.disabled = false;
+      } catch (err) {
+        status.textContent = err.message;
+        status.setAttribute('data-tone', 'error');
+        check.disabled = false;
+      }
+    });
+
+    actions.appendChild(install);
+    actions.appendChild(signIn);
+    actions.appendChild(check);
+    actions.appendChild(close);
+    modal.appendChild(actions);
+    overlay.appendChild(modal);
+    document.body.appendChild(overlay);
+    install.focus();
+  }
+
+  function showAgentInstallError(modal, opt, message, retryButton, closeButton) {
+    const existing = modal.querySelector('[data-testid="error-frame"]');
+    if (existing) existing.remove();
+    if (!window.FraimErrorFrame || typeof window.FraimErrorFrame.render !== 'function') return;
+    const frame = window.FraimErrorFrame.render({
+      whatTried: `We tried to set up ${opt.label}.`,
+      whatHappened: message,
+      actions: [
+        { id: 'retry', label: 'Retry', variant: 'primary' },
+        { id: 'alternative', label: 'Choose another agent', variant: 'secondary' },
+        { id: 'manual', label: 'Manual setup help', variant: 'ghost' },
+      ],
+    }, (action) => {
+      if (action.id === 'retry') {
+        retryButton.click();
+      } else if (action.id === 'alternative') {
+        closeButton.click();
+      } else if (action.id === 'manual') {
+        const status = modal.querySelector('[data-testid="agent-install-status"]');
+        if (status) {
+          status.textContent = 'Run npx fraim add-ide for manual setup, then return here when your local agent is ready.';
+          status.removeAttribute('data-tone');
+        }
+      }
+    });
+    modal.appendChild(frame);
+  }
+
+  function button(text, variant) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = variant === 'primary' ? 'btn btn-primary' : variant === 'ghost' ? 'btn btn-ghost' : 'btn btn-secondary';
+    btn.textContent = text;
+    return btn;
+  }
+
+  function escapeHtml(value) {
+    return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+
+  async function loadSession(shouldRender) {
+    state.session = await api('/api/first-run/session');
+    if (!state.session.state.agentInstalls) state.session.state.agentInstalls = {};
+    if (shouldRender !== false) {
+      state.activeStep = chooseActiveStep();
+      render();
+    }
+  }
+
+  // Issue #646: when first-run was launched without a key (the no-terminal macOS
+  // installer path), gate the whole wizard behind a paste-your-key step.
+  function renderKeyEntry() {
+    CHECKLIST_EL.className = 'setup-shell';
+    CHECKLIST_EL.innerHTML = '';
+    PRIMARY_BUTTON.style.display = 'none';
+    setHeader('Set up FRAIM', 'Paste the FRAIM key from your account page to get started.');
+
+    const card = document.createElement('div');
+    card.className = 'setup-pane';
+    card.setAttribute('data-testid', 'key-entry');
+
+    const label = document.createElement('label');
+    label.className = 'pane-copy';
+    label.setAttribute('for', 'fraim-key-input');
+    label.textContent = 'Your FRAIM key';
+    card.appendChild(label);
+
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.id = 'fraim-key-input';
+    input.className = 'key-input';
+    input.placeholder = 'fraim_…';
+    input.autocapitalize = 'off';
+    input.autocomplete = 'off';
+    input.spellcheck = false;
+    input.setAttribute('data-testid', 'key-input');
+    card.appendChild(input);
+
+    const err = document.createElement('p');
+    err.className = 'locked-note';
+    err.setAttribute('data-testid', 'key-error');
+    err.hidden = true;
+    card.appendChild(err);
+
+    const submit = button('Continue', 'primary');
+    submit.setAttribute('data-testid', 'key-submit');
+    const onSubmit = async () => {
+      const value = input.value.trim();
+      err.hidden = true;
+      submit.disabled = true;
+      submit.textContent = 'Checking…';
+      try {
+        const resp = await api('/api/first-run/set-key', 'POST', { key: value });
+        state.session = resp.session;
+        if (!state.session.state.agentInstalls) state.session.state.agentInstalls = {};
+        state.activeStep = chooseActiveStep();
+        render();
+      } catch (e) {
+        err.textContent = e.message || 'That key was not accepted. Copy it again from your account page.';
+        err.hidden = false;
+        submit.disabled = false;
+        submit.textContent = 'Continue';
+      }
+    };
+    submit.addEventListener('click', onSubmit);
+    input.addEventListener('keydown', (e) => { if (e.key === 'Enter') onSubmit(); });
+    card.appendChild(submit);
+
+    CHECKLIST_EL.appendChild(card);
+    input.focus();
+  }
+
+  function render() {
+    if (!state.session) return;
+    if (state.session.needsKey) { renderKeyEntry(); return; }
+    if (!STEP_ORDER.includes(state.activeStep)) state.activeStep = chooseActiveStep();
+    renderShell((pane) => {
+      if (state.activeStep === 'prereqs') renderPrereqs(pane);
+      else if (state.activeStep === 'agents') renderAgents(pane);
+      else if (state.activeStep === 'configure') renderConfigure(pane);
+      else renderUseFraim(pane);
+    });
+  }
+
+  PRIMARY_BUTTON.addEventListener('click', () => {
+    state.activeStep = chooseActiveStep();
+    render();
+  });
+
+  loadSession().catch((err) => {
+    setStatus(err.message || 'Could not load first-run.', 'error');
+  });
+}());