fraim-framework 2.0.151 → 2.0.152

package/public/first-run/script.js

@@ -1,667 +1,667 @@
-(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,
-    runningRowId: null,
-  };
-
-  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;
-  }
-
-  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 = 'The following AI agents are now ready to function as your AI Employees.';
-      } else {
-        LEDE_EL.textContent = "You do not seem to have any AI agents on this machine.";
-      }
-      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;
-    }
-    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}).`);
-    }
-    return json;
-  }
-
-  async function loadSession() {
-    state.session = await api('/api/first-run/session');
-    render();
-  }
-
-  function setSessionFromActionResponse(actionResp) {
-    if (!state.session) 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 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);
-    }
-
-    if (row.manualMessage) {
-      const message = document.createElement('div');
-      message.className = 'manual-message';
-      message.textContent = row.manualMessage;
-      li.appendChild(message);
-    }
-
-    if (row.status === 'error' && row.errorFrame && window.FraimErrorFrame) {
-      const frame = window.FraimErrorFrame.render(row.errorFrame, (action) => onErrorAction(row.id, action));
-      li.appendChild(frame);
-    }
-
-    return li;
-  }
-
-  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
-      ? 'The following AI agents are now ready to function as your AI Employees'
-      : "You do not seem to have any AI agents on this machine";
-    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 = "Let's recruit some agents who can function as your AI Employees.";
-      li.appendChild(copy);
-    }
-
-    return li;
-  }
-
-  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();
-    }
-  }
-
-  async function onErrorAction(rowId, action) {
-    const body = { errorActionId: action.id };
-    if (action.id === 'alternative' && action.alternativeAgentId) {
-      body.alternativeAgentId = action.alternativeAgentId;
-    }
-    await runRow(rowId, body);
-  }
-
-  async function onPrimaryClick() {
-    if (!state.session) 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;
-    }
-
-    const next = state.session.rows.find((r) => r.status === 'pending');
-    if (!next) return;
-    await runRow(next.id);
-
-    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);
-    }
-  }
-
-  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.');
-
-    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' },
-    ];
-
-    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.',
-    };
-
-    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);
-
-      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.');
-      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);
-    }
-
-    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);
-      }
-    })();
-  }
-
-  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);
-  }
-
-  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);
-
-    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');
-      }
-    });
-
-    parentLi.appendChild(checkBtn);
-    parentLi.appendChild(skipEl);
-  }
-
-  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 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.');
-
-    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';
-    ideBtn.addEventListener('click', async () => {
-      try {
-        await api('/api/first-run/set-preference', 'POST', { choice: 'ide' });
-      } catch (_err) { /* non-fatal */ }
-      renderIdeCommandDisplay(ideCommands);
-    });
-    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';
-    hubBtn.addEventListener('click', async () => {
-      try {
-        await api('/api/first-run/set-preference', 'POST', { choice: 'hub' });
-      } catch (_err) { /* non-fatal */ }
-      try {
-        hubBtn.disabled = true;
-        setStatus('Opening Hub...');
-        const openResp = await api('/api/first-run/open-hub', 'POST');
-        if (openResp && openResp.needsAgentSetup) {
-          renderRecruitAgents();
-          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;
-  }
-
-  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 {
-          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);
-    }
-
-    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 () => {
-      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();
-          return;
-        }
-        if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
-      } catch (err) {
-        setStatus(err.message, 'error');
-      }
-    });
-    switchLi.appendChild(switchLink);
-    CHECKLIST_EL.appendChild(switchLi);
-  }
-
-  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);
-  }
-
-  PRIMARY_BUTTON.addEventListener('click', onPrimaryClick);
-
-  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,
+    runningRowId: null,
+  };
+
+  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;
+  }
+
+  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 = 'The following AI agents are now ready to function as your AI Employees.';
+      } else {
+        LEDE_EL.textContent = "You do not seem to have any AI agents on this machine.";
+      }
+      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;
+    }
+    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}).`);
+    }
+    return json;
+  }
+
+  async function loadSession() {
+    state.session = await api('/api/first-run/session');
+    render();
+  }
+
+  function setSessionFromActionResponse(actionResp) {
+    if (!state.session) 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 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);
+    }
+
+    if (row.manualMessage) {
+      const message = document.createElement('div');
+      message.className = 'manual-message';
+      message.textContent = row.manualMessage;
+      li.appendChild(message);
+    }
+
+    if (row.status === 'error' && row.errorFrame && window.FraimErrorFrame) {
+      const frame = window.FraimErrorFrame.render(row.errorFrame, (action) => onErrorAction(row.id, action));
+      li.appendChild(frame);
+    }
+
+    return li;
+  }
+
+  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
+      ? 'The following AI agents are now ready to function as your AI Employees'
+      : "You do not seem to have any AI agents on this machine";
+    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 = "Let's recruit some agents who can function as your AI Employees.";
+      li.appendChild(copy);
+    }
+
+    return li;
+  }
+
+  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();
+    }
+  }
+
+  async function onErrorAction(rowId, action) {
+    const body = { errorActionId: action.id };
+    if (action.id === 'alternative' && action.alternativeAgentId) {
+      body.alternativeAgentId = action.alternativeAgentId;
+    }
+    await runRow(rowId, body);
+  }
+
+  async function onPrimaryClick() {
+    if (!state.session) 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;
+    }
+
+    const next = state.session.rows.find((r) => r.status === 'pending');
+    if (!next) return;
+    await runRow(next.id);
+
+    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);
+    }
+  }
+
+  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.');
+
+    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' },
+    ];
+
+    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.',
+    };
+
+    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);
+
+      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.');
+      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);
+    }
+
+    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);
+      }
+    })();
+  }
+
+  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);
+  }
+
+  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);
+
+    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');
+      }
+    });
+
+    parentLi.appendChild(checkBtn);
+    parentLi.appendChild(skipEl);
+  }
+
+  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 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.');
+
+    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';
+    ideBtn.addEventListener('click', async () => {
+      try {
+        await api('/api/first-run/set-preference', 'POST', { choice: 'ide' });
+      } catch (_err) { /* non-fatal */ }
+      renderIdeCommandDisplay(ideCommands);
+    });
+    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';
+    hubBtn.addEventListener('click', async () => {
+      try {
+        await api('/api/first-run/set-preference', 'POST', { choice: 'hub' });
+      } catch (_err) { /* non-fatal */ }
+      try {
+        hubBtn.disabled = true;
+        setStatus('Opening Hub...');
+        const openResp = await api('/api/first-run/open-hub', 'POST');
+        if (openResp && openResp.needsAgentSetup) {
+          renderRecruitAgents();
+          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;
+  }
+
+  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 {
+          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);
+    }
+
+    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 () => {
+      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();
+          return;
+        }
+        if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
+      } catch (err) {
+        setStatus(err.message, 'error');
+      }
+    });
+    switchLi.appendChild(switchLink);
+    CHECKLIST_EL.appendChild(switchLi);
+  }
+
+  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);
+  }
+
+  PRIMARY_BUTTON.addEventListener('click', onPrimaryClick);
+
+  loadSession().catch((err) => {
+    setStatus(err.message || 'Could not load first-run.', 'error');
+  });
+}());