fraim 2.0.167 → 2.0.168

package/public/first-run/script.js

@@ -8,9 +8,20 @@
 
   const state = {
     session: null,
-    runningRowId: 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);
@@ -23,643 +34,561 @@
     if (LEDE_EL) LEDE_EL.textContent = lede;
   }
 
-  function applyHeading(rows) {
-    if (!LEDE_EL) return;
-    const complete = rows.every((r) => r.status === 'ok' || r.status === 'manual-required') && rows.some((r) => r.status === 'ok');
-    if (complete) {
-      const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
-      if (setupResult && setupResult.detectedSurfaceCount > 0) {
-        LEDE_EL.textContent = 'Your FRAIM employees are ready to work. Here are the surfaces available to them.';
-      } else {
-        LEDE_EL.textContent = "No execution surfaces found. Your FRAIM employees need at least one agent (Claude Code, Codex, etc.) to work in.";
-      }
-      return;
-    }
-    const errored = rows.find((r) => r.status === 'error');
-    if (errored) {
-      LEDE_EL.textContent = "Something did not go through. Pick the right next step below.";
-      return;
-    }
-    if (rows.some((r) => r.status === 'ok')) {
-      LEDE_EL.textContent = 'FRAIM is finishing setup on this machine.';
-      return;
-    }
-    LEDE_EL.textContent = 'We are getting your machine ready for FRAIM.';
-  }
-
   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;
-    }
+    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;
-    let json = null;
-    try {
-      json = await response.json();
-    } catch (e) {
-      throw new Error(`Server returned invalid JSON (status ${response.status}).`);
-    }
-    if (!response.ok) {
-      throw new Error(json && json.error ? json.error : `Request failed (status ${response.status}).`);
-    }
+    const json = await response.json();
+    if (!response.ok) throw new Error(json && json.error ? json.error : `Request failed (status ${response.status}).`);
     return json;
   }
 
-  async function loadSession() {
-    state.session = await api('/api/first-run/session');
-    render();
-  }
-
   function setSessionFromActionResponse(actionResp) {
-    if (!state.session) return;
+    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 makeIcon(status) {
-    const icon = document.createElement('span');
-    icon.className = 'icon';
-    icon.setAttribute('aria-hidden', 'true');
-    icon.textContent =
-      status === 'ok' ? '✓' :
-      status === 'in-progress' ? '...' :
-      status === 'manual-required' ? '!' :
-      status === 'error' ? '!' :
-      '.';
-    return icon;
+  function row(id) {
+    return (state.session && state.session.rows || []).find((r) => r.id === id) || null;
   }
 
-  function renderRow(row) {
-    const li = document.createElement('li');
-    li.className = 'row';
-    li.setAttribute('data-row-id', row.id);
-    li.setAttribute('data-row-status', row.status);
-
-    li.appendChild(makeIcon(row.status));
-
-    const label = document.createElement('span');
-    label.className = 'label';
-    label.textContent = row.label;
-    li.appendChild(label);
-
-    const verb = document.createElement('span');
-    verb.className = 'verb';
-    verb.setAttribute('data-testid', 'row-verb');
-    verb.textContent = row.verb || '';
-    li.appendChild(verb);
-
-    if (row.detail) {
-      const detail = document.createElement('span');
-      detail.className = 'detail';
-      detail.setAttribute('data-testid', 'row-detail');
-      detail.textContent = row.detail;
-      li.appendChild(detail);
-    }
-
-    if (row.streamOutput) {
-      const stream = document.createElement('pre');
-      stream.className = 'row-stream';
-      stream.setAttribute('data-testid', 'row-stream');
-      stream.textContent = row.streamOutput;
-      li.appendChild(stream);
-    }
+  function requiredPrereqsReady() {
+    const node = row('node');
+    return Boolean(node && node.status === 'ok');
+  }
 
-    if (row.manualMessage) {
-      const message = document.createElement('div');
-      message.className = 'manual-message';
-      message.textContent = row.manualMessage;
-      li.appendChild(message);
-    }
+  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 }));
+  }
 
-    if (row.status === 'error' && row.errorFrame && window.FraimErrorFrame) {
-      const frame = window.FraimErrorFrame.render(row.errorFrame, (action) => onErrorAction(row.id, action));
-      li.appendChild(frame);
-    }
+  function configuredSurfaces() {
+    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
+    return setupResult && Array.isArray(setupResult.configuredSurfaces) ? setupResult.configuredSurfaces : [];
+  }
 
-    return li;
+  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 renderSetupSummary() {
-    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
-    if (!setupResult) return null;
-
-    const li = document.createElement('li');
-    li.className = 'setup-result';
-    li.setAttribute('data-testid', 'setup-result');
-
-    const title = document.createElement('strong');
-    title.textContent = setupResult.detectedSurfaceCount > 0
-      ? 'Your FRAIM employees are ready to work in these surfaces'
-      : 'No execution surfaces found';
-    li.appendChild(title);
-
-    if (setupResult.detectedSurfaceCount > 0) {
-      const list = document.createElement('ul');
-      list.className = 'surface-list';
-      for (const surface of setupResult.configuredSurfaces || []) {
-        const item = document.createElement('li');
-        item.textContent = surface.name;
-        list.appendChild(item);
-      }
-      li.appendChild(list);
-    } else {
-      const copy = document.createElement('p');
-      copy.textContent = "No execution surfaces found. Install Claude Code, Codex, or another agent to work in.";
-      li.appendChild(copy);
+  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);
+  }
 
-    return li;
+  function detectedAgentCount() {
+    const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
+    return (setupResult && setupResult.detectedSurfaceCount) || readyAgents().length;
   }
 
-  async function runRow(rowId, extraBody) {
-    if (state.runningRowId) return;
-    state.runningRowId = rowId;
-    PRIMARY_BUTTON.disabled = true;
-    setStatus(`Running ${rowId}...`);
-    try {
-      const resp = await api(`/api/first-run/rows/${rowId}/run`, 'POST', extraBody || {});
-      setSessionFromActionResponse(resp);
-      setStatus(resp.message, resp.ok ? null : 'error');
-    } catch (err) {
-      setStatus(err.message, 'error');
-    } finally {
-      state.runningRowId = null;
-      PRIMARY_BUTTON.disabled = false;
-      render();
-    }
+  function configureReady() {
+    const fraim = row('fraim');
+    return Boolean(fraim && fraim.status === 'ok' && detectedAgentCount() > 0);
   }
 
-  async function onErrorAction(rowId, action) {
-    const body = { errorActionId: action.id };
-    if (action.id === 'alternative' && action.alternativeAgentId) {
-      body.alternativeAgentId = action.alternativeAgentId;
-    }
-    await runRow(rowId, body);
+  function chooseActiveStep() {
+    if (!requiredPrereqsReady()) return 'prereqs';
+    if (detectedAgentCount() < 1) return 'agents';
+    if (!configureReady()) return 'configure';
+    return 'use';
   }
 
-  async function onPrimaryClick() {
-    if (!state.session) return;
+  function iconFor(status) {
+    if (status === 'ok') return '✓';
+    if (status === 'in-progress') return '...';
+    if (status === 'manual-required' || status === 'error') return '!';
+    return '.';
+  }
 
-    if (state.session.primaryButtonLabel === 'Get Started') {
-      PRIMARY_BUTTON.disabled = true;
-      const setupResult = state.session.state ? state.session.state.setupResult : null;
-      if (setupResult && setupResult.detectedSurfaceCount === 0) {
-        renderRecruitAgents();
-        return;
-      }
-      try {
-        const ideData = await api('/api/first-run/ide-commands');
-        renderStartWorking(ideData ? ideData.commands : []);
-      } catch (_err) {
-        renderStartWorking([]);
-      }
-      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 next = state.session.rows.find((r) => r.status === 'pending');
-    if (!next) return;
-    await runRow(next.id);
+    const pane = document.createElement('div');
+    pane.className = 'setup-pane';
+    pane.setAttribute('data-testid', 'setup-pane');
+    renderPane(pane);
 
-    while (state.session) {
-      const blockingError = state.session.rows.find((r) => r.status === 'error');
-      if (blockingError) break;
-      const nextRow = state.session.rows.find((r) => r.status === 'pending');
-      if (!nextRow) break;
-      await runRow(nextRow.id);
-    }
+    CHECKLIST_EL.appendChild(steps);
+    CHECKLIST_EL.appendChild(pane);
   }
 
-  function renderRecruitAgents() {
-    CHECKLIST_EL.className = 'selection-container recruit-container';
-    CHECKLIST_EL.innerHTML = '';
-    PRIMARY_BUTTON.style.display = 'none';
-    setHeader('Recruit AI Employees', 'Choose how you want to add AI Employees to this machine.');
+  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';
+  }
 
-    const agentOptions = (state.session && state.session.agentOptions) ? state.session.agentOptions : [
-      { id: 'claude-code', label: 'Claude Code' },
-      { id: 'codex', label: 'Codex' },
-      { id: 'gemini-cli', label: 'Gemini CLI' },
-    ];
+  function renderPrereqs(pane) {
+    const h = document.createElement('h2');
+    h.textContent = 'Prerequisites';
+    pane.appendChild(h);
 
-    const AGENT_DESCS = {
-      'claude-code': 'Install Claude Code and connect it to FRAIM.',
-      'codex': 'Install Codex and connect it to FRAIM.',
-      'gemini-cli': 'Install Gemini CLI and connect it to FRAIM.',
-    };
+    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();
+    if (readyLabels.length > 0) {
+      const readyList = document.createElement('div');
+      readyList.className = 'ready-strip';
+      readyList.setAttribute('data-testid', 'ready-agents');
+      readyList.textContent = `Already installed: ${readyLabels.join(', ')}`;
+      pane.appendChild(readyList);
+    } else {
+      const readyList = document.createElement('div');
+      readyList.className = 'ready-strip ready-strip--muted';
+      readyList.setAttribute('data-testid', 'ready-agents');
+      readyList.textContent = 'Already installed: none detected yet';
+      pane.appendChild(readyList);
+    }
 
+    const grid = document.createElement('div');
+    grid.className = 'agent-grid';
+    const agentOptions = state.session.agentOptions || [];
     for (const opt of agentOptions) {
-      const li = document.createElement('li');
       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 = AGENT_DESCS[opt.id] || ('Install ' + opt.label + ' and connect it to FRAIM.');
+      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);
-
-      const installBtn = document.createElement('button');
-      installBtn.type = 'button';
-      installBtn.className = 'btn btn-secondary btn-block';
-      installBtn.textContent = 'Install';
-      installBtn.setAttribute('data-testid', 'install-' + opt.id);
-      installBtn.addEventListener('click', () => renderAgentInstallFlow(opt));
-      card.appendChild(installBtn);
-
-      li.appendChild(card);
-      CHECKLIST_EL.appendChild(li);
+      card.appendChild(action);
+      grid.appendChild(card);
     }
 
-    const byoaLi = document.createElement('li');
-    const byoaCard = document.createElement('div');
-    byoaCard.className = 'user-type-card recruit-card';
-    const byoaTitle = document.createElement('strong');
-    byoaTitle.className = 'card-title';
-    byoaTitle.textContent = 'Bring Your Own Agent';
-    const byoaDesc = document.createElement('p');
-    byoaDesc.className = 'card-desc';
-    byoaDesc.textContent = 'Install Cursor, Windsurf, Kiro, VS Code, or another supported AI tool.';
-    const byoaNote = document.createElement('p');
-    byoaNote.className = 'card-desc';
-    byoaNote.textContent = 'When you are done installing your agent, run:';
-    const byoaCmd = document.createElement('div');
-    byoaCmd.className = 'cmd-block';
-    byoaCmd.textContent = 'npx fraim add-ide';
-    byoaCard.appendChild(byoaTitle);
-    byoaCard.appendChild(byoaDesc);
-    byoaCard.appendChild(byoaNote);
-    byoaCard.appendChild(byoaCmd);
-    byoaLi.appendChild(byoaCard);
-    CHECKLIST_EL.appendChild(byoaLi);
-
-    const continueLi = document.createElement('li');
-    const continueBtn = document.createElement('button');
-    continueBtn.type = 'button';
-    continueBtn.className = 'btn btn-primary btn-block';
-    continueBtn.textContent = 'Continue without AI Agent';
-    continueBtn.addEventListener('click', async () => {
-      try {
-        const ideData = await api('/api/first-run/ide-commands');
-        renderStartWorking(ideData ? ideData.commands : []);
-      } catch (_err) {
-        renderStartWorking([]);
-      }
-    });
-    continueLi.appendChild(continueBtn);
-    CHECKLIST_EL.appendChild(continueLi);
-  }
-
-  function renderAgentInstallFlow(opt) {
-    CHECKLIST_EL.className = 'selection-container recruit-container';
-    CHECKLIST_EL.innerHTML = '';
-    setHeader('Install ' + opt.label, 'Setting up ' + opt.label + ' on this machine...');
-
-    const statusLi = document.createElement('li');
-    const statusDiv = document.createElement('div');
-    statusDiv.className = 'install-status';
-    statusDiv.setAttribute('data-testid', 'agent-install-status');
-    statusDiv.textContent = 'Installing ' + opt.label + '...';
-    statusLi.appendChild(statusDiv);
-    CHECKLIST_EL.appendChild(statusLi);
-
-    (async () => {
-      try {
-        const result = await api('/api/first-run/install-agent', 'POST', { agentId: opt.id });
-        if (!result || !result.ok) {
-          statusDiv.textContent = (result && result.message) ? result.message : 'Install failed.';
-          statusDiv.setAttribute('data-tone', 'error');
-          const actions = document.createElement('div');
-          actions.className = 'install-actions';
-          const retryBtn = document.createElement('button');
-          retryBtn.type = 'button';
-          retryBtn.className = 'btn btn-primary';
-          retryBtn.textContent = 'Retry';
-          retryBtn.addEventListener('click', () => renderAgentInstallFlow(opt));
-          const backBtn = document.createElement('button');
-          backBtn.type = 'button';
-          backBtn.className = 'btn btn-ghost';
-          backBtn.textContent = 'Choose a different agent';
-          backBtn.addEventListener('click', () => renderRecruitAgents());
-          actions.appendChild(retryBtn);
-          actions.appendChild(backBtn);
-          statusLi.appendChild(actions);
-          return;
-        }
-        statusDiv.textContent = opt.label + ' installed successfully!';
-        renderAgentLoginStep(opt, result.loginCommand, result.loginHint, statusLi);
-      } catch (err) {
-        statusDiv.textContent = err.message || 'Install failed.';
-        statusDiv.setAttribute('data-tone', 'error');
-        const backBtn = document.createElement('button');
-        backBtn.type = 'button';
-        backBtn.className = 'btn btn-ghost btn-block';
-        backBtn.textContent = 'Choose a different agent';
-        backBtn.addEventListener('click', () => renderRecruitAgents());
-        statusLi.appendChild(backBtn);
-      }
-    })();
+    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);
+    }
   }
 
-  function renderAgentLoginStep(opt, loginCommand, loginHint, parentLi) {
-    const hintEl = document.createElement('p');
-    hintEl.className = 'install-hint';
-    hintEl.textContent = loginHint || ('Sign in to ' + opt.label + ' to activate it.');
-    parentLi.appendChild(hintEl);
-
-    const signInBtn = document.createElement('button');
-    signInBtn.type = 'button';
-    signInBtn.className = 'btn btn-primary btn-block';
-    signInBtn.textContent = 'Sign In to ' + opt.label;
-    signInBtn.addEventListener('click', async () => {
-      signInBtn.disabled = true;
-      signInBtn.textContent = 'Opening terminal...';
-      try {
-        const result = await api('/api/first-run/trigger-agent-login', 'POST', { agentId: opt.id });
-        signInBtn.style.display = 'none';
-        renderAgentReadyCheck(opt, result && result.message, parentLi);
-      } catch (err) {
-        signInBtn.disabled = false;
-        signInBtn.textContent = 'Sign In to ' + opt.label;
-        setStatus(err.message, 'error');
-      }
-    });
-    parentLi.appendChild(signInBtn);
+  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 renderAgentReadyCheck(opt, loginMessage, parentLi) {
-    const msgEl = document.createElement('p');
-    msgEl.className = 'install-hint';
-    msgEl.textContent = loginMessage || ('Complete sign-in in the terminal, then click Check if Ready.');
-    parentLi.appendChild(msgEl);
-
-    const checkBtn = document.createElement('button');
-    checkBtn.type = 'button';
-    checkBtn.className = 'btn btn-primary btn-block';
-    checkBtn.textContent = 'Check if Ready';
-
-    // Declare skipEl before the click handler so it can be hidden on success.
-    const skipEl = document.createElement('p');
-    const skipLink = document.createElement('button');
-    skipLink.type = 'button';
-    skipLink.className = 'text-button';
-    skipLink.textContent = 'Skip for now — I will sign in later';
-    skipLink.addEventListener('click', async () => {
-      try {
-        const ideData = await api('/api/first-run/ide-commands');
-        renderStartWorking(ideData ? ideData.commands : []);
-      } catch (_err) {
-        renderStartWorking([]);
-      }
-    });
-    skipEl.appendChild(skipLink);
+  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;
+    }
 
-    checkBtn.addEventListener('click', async () => {
-      checkBtn.disabled = true;
-      checkBtn.textContent = 'Checking...';
-      try {
-        const result = await api('/api/first-run/check-agent', 'POST', { agentId: opt.id });
-        if (result && result.ready) {
-          checkBtn.style.display = 'none';
-          skipEl.style.display = 'none';
-          msgEl.textContent = opt.label + ' is ready!';
-          setHeader(opt.label + ' is ready!', 'You can now open the Hub.');
-          renderOpenHubButton(parentLi);
-        } else {
-          checkBtn.disabled = false;
-          checkBtn.textContent = 'Check if Ready';
-          setStatus((result && result.message) || (opt.label + ' not detected yet. Complete sign-in and try again.'), 'error');
-        }
-      } catch (err) {
-        checkBtn.disabled = false;
-        checkBtn.textContent = 'Check if Ready';
-        setStatus(err.message, 'error');
+    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;
+    }
 
-    parentLi.appendChild(checkBtn);
-    parentLi.appendChild(skipEl);
+    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 renderOpenHubButton(parentLi) {
-    const openHubBtn = document.createElement('button');
-    openHubBtn.type = 'button';
-    openHubBtn.className = 'btn btn-primary btn-block';
-    openHubBtn.textContent = 'Open Hub';
-    openHubBtn.addEventListener('click', async () => {
-      openHubBtn.disabled = true;
-      setStatus('Opening Hub...');
-      try {
-        await api('/api/first-run/set-preference', 'POST', { choice: 'hub' });
-      } catch (_err) { /* non-fatal */ }
-      try {
-        const openResp = await api('/api/first-run/open-hub', 'POST');
-        if (openResp && openResp.message) setStatus(openResp.message);
-        if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
-        else openHubBtn.disabled = false;
-      } catch (err) {
-        openHubBtn.disabled = false;
-        setStatus(err.message, 'error');
-      }
-    });
-    parentLi.appendChild(openHubBtn);
+  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 renderStartWorking(ideCommands) {
-    CHECKLIST_EL.className = 'selection-container start-container';
-    CHECKLIST_EL.innerHTML = '';
-    PRIMARY_BUTTON.style.display = 'none';
-    setHeader('Start in your IDE', 'Recommended: fully restart your favorite IDE, open your project there, and let FRAIM run in the surface you already use.');
+  function renderStartWorkingChoices(pane) {
+    const choices = document.createElement('div');
+    choices.className = 'choice-grid';
 
-    const ideLi = document.createElement('li');
     const ideCard = document.createElement('div');
-    ideCard.className = 'user-type-card user-type-card--featured user-type-card--ide-default';
-    ideCard.appendChild(cardHeader('</>', 'In my IDE', 'Recommended. Restart Claude Code, Cursor, Codex, or your favorite AI IDE before you continue.'));
-    ideCard.appendChild(cardEyebrow('Recommended default'));
-    const ideNote = document.createElement('p');
-    ideNote.className = 'route-note';
-    ideNote.textContent = 'This keeps FRAIM inside the tool you already work in and avoids the extra layer of the Hub.';
-    ideCard.appendChild(ideNote);
-    const ideBtn = document.createElement('button');
-    ideBtn.type = 'button';
-    ideBtn.className = 'btn btn-primary btn-block';
-    ideBtn.textContent = 'Continue in my IDE';
+    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 (_err) { /* non-fatal */ }
-      renderIdeCommandDisplay(ideCommands);
+      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);
-    ideLi.appendChild(ideCard);
-    CHECKLIST_EL.appendChild(ideLi);
 
-    const hubLi = document.createElement('li');
     const hubCard = document.createElement('div');
-    hubCard.className = 'user-type-card user-type-card--compact user-type-card--alpha';
-    hubCard.appendChild(cardHeader('α', 'AI Hub Alpha', 'Early testers only'));
-    hubCard.appendChild(cardEyebrow('Optional fallback'));
-    const hubNote = document.createElement('p');
-    hubNote.className = 'route-note route-note--compact';
-    hubNote.textContent = 'Use the Hub only if you specifically want the experimental browser shell.';
-    hubCard.appendChild(hubNote);
-    const hubBtn = document.createElement('button');
-    hubBtn.type = 'button';
-    hubBtn.className = 'btn btn-secondary';
-    hubBtn.textContent = 'Open AI Hub Alpha';
+    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 (_err) { /* non-fatal */ }
+      try { await api('/api/first-run/set-preference', 'POST', { choice: 'hub' }); } catch (_) {}
       try {
         hubBtn.disabled = true;
         setStatus('Opening Hub...');
         const openResp = await api('/api/first-run/open-hub', 'POST');
         if (openResp && openResp.needsAgentSetup) {
-          renderRecruitAgents();
+          state.activeStep = 'agents';
+          render();
+          setStatus(openResp.message, 'error');
           return;
         }
-        if (openResp && openResp.message) setStatus(openResp.message);
         if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
-        else hubBtn.disabled = false;
       } catch (err) {
         hubBtn.disabled = false;
         setStatus(err.message, 'error');
       }
     });
     hubCard.appendChild(hubBtn);
-    hubLi.appendChild(hubCard);
-    CHECKLIST_EL.appendChild(hubLi);
-
-    setTimeout(() => ideBtn.focus(), 0);
-  }
-
-  function cardHeader(iconText, titleText, descText) {
-    const header = document.createElement('div');
-    header.className = 'card-header';
-    const icon = document.createElement('div');
-    icon.className = 'card-icon';
-    icon.textContent = iconText;
-    const text = document.createElement('div');
-    const title = document.createElement('strong');
-    title.className = 'card-title';
-    title.textContent = titleText;
-    const desc = document.createElement('p');
-    desc.className = 'card-desc';
-    desc.textContent = descText;
-    text.appendChild(title);
-    text.appendChild(desc);
-    header.appendChild(icon);
-    header.appendChild(text);
-    return header;
-  }
-
-  function cardEyebrow(text) {
-    const eyebrow = document.createElement('span');
-    eyebrow.className = 'card-eyebrow';
-    eyebrow.textContent = text;
-    return eyebrow;
+    choices.appendChild(ideCard);
+    choices.appendChild(hubCard);
+    pane.appendChild(choices);
   }
 
   function renderIdeCommandDisplay(commands) {
-    CHECKLIST_EL.className = 'selection-container';
-    CHECKLIST_EL.innerHTML = '';
-    setHeader('Restart your favorite IDE', 'Fully restart your IDE first so it picks up the new FRAIM setup. Then open your project there and type:');
-
-    const cmdList = (commands && commands.length > 0) ? commands : ['/fraim onboard this project'];
-    for (const cmd of cmdList) {
-      const li = document.createElement('li');
-      const row = document.createElement('div');
-      row.className = 'command-row';
-      const block = document.createElement('div');
-      block.className = 'cmd-block';
-      block.textContent = cmd;
-      const copyBtn = document.createElement('button');
-      copyBtn.type = 'button';
-      copyBtn.className = 'btn btn-secondary';
-      copyBtn.textContent = 'Copy';
-      copyBtn.setAttribute('aria-label', `Copy command: ${cmd}`);
-      copyBtn.addEventListener('click', async () => {
-        try {
+    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);
-        } catch (_err) {
-          // Fallback for environments where clipboard API is unavailable.
-          try {
-            const ta = document.createElement('textarea');
-            ta.value = cmd;
-            ta.style.position = 'fixed';
-            ta.style.opacity = '0';
-            document.body.appendChild(ta);
-            ta.select();
-            document.execCommand('copy');
-            document.body.removeChild(ta);
-            copyBtn.textContent = 'Copied';
-            setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
-          } catch (_e) {
-            copyBtn.textContent = 'Copy failed';
-            setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
-          }
-        }
-      });
-      row.appendChild(block);
-      row.appendChild(copyBtn);
-      li.appendChild(row);
-      CHECKLIST_EL.appendChild(li);
-    }
+        });
+        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);
+    });
+  }
 
-    const switchLi = document.createElement('li');
-    const switchLink = document.createElement('button');
-    switchLink.type = 'button';
-    switchLink.className = 'text-button';
-    switchLink.textContent = 'Prefer AI Hub Alpha instead';
-    switchLink.addEventListener('click', async () => {
+  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 {
-        await api('/api/first-run/set-preference', 'POST', { choice: 'hub' });
-        const openResp = await api('/api/first-run/open-hub', 'POST');
-        if (openResp && openResp.needsAgentSetup) {
-          renderRecruitAgents();
+        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;
         }
-        if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
+        status.textContent = result && result.message ? result.message : `${opt.label} is not ready yet.`;
+        status.setAttribute('data-tone', 'error');
+        check.disabled = false;
       } catch (err) {
-        setStatus(err.message, 'error');
+        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');
+        }
       }
     });
-    switchLi.appendChild(switchLink);
-    CHECKLIST_EL.appendChild(switchLi);
+    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();
+    }
   }
 
   function render() {
     if (!state.session) return;
-    CHECKLIST_EL.className = 'checklist';
-    PRIMARY_BUTTON.style.display = '';
-    const { rows, primaryButtonLabel } = state.session;
-    CHECKLIST_EL.innerHTML = '';
-    for (const row of rows) {
-      CHECKLIST_EL.appendChild(renderRow(row));
-    }
-    if (primaryButtonLabel === 'Get Started') {
-      const summary = renderSetupSummary();
-      if (summary) CHECKLIST_EL.appendChild(summary);
-    }
-    PRIMARY_BUTTON.textContent = primaryButtonLabel || 'Set up FRAIM';
-    applyHeading(rows);
+    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', onPrimaryClick);
+  PRIMARY_BUTTON.addEventListener('click', () => {
+    state.activeStep = chooseActiveStep();
+    render();
+  });
 
   loadSession().catch((err) => {
     setStatus(err.message || 'Could not load first-run.', 'error');