fraim 2.0.134 → 2.0.136

package/dist/src/ai-hub/catalog.js

@@ -27,11 +27,13 @@ const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 //                        (per-project override layer; CLAUDE.md says it
 //                        "takes precedence over synced baseline content")
 const EMPLOYEE_JOB_LAYERS = [
+    { base: 'registry', segments: ['jobs', 'ai-employee'] },
     { base: 'fraim', segments: ['ai-employee', 'jobs'] },
     { base: 'fraim', segments: ['personalized-employee', 'jobs'] },
 ];
 // Manager templates use the matching two-layer model.
 const MANAGER_JOB_LAYERS = [
+    { base: 'registry', segments: ['jobs', 'ai-manager'] },
     { base: 'fraim', segments: ['ai-manager', 'jobs'] },
     { base: 'fraim', segments: ['personalized-employee', 'manager-jobs'] },
 ];
@@ -137,7 +139,8 @@ function summarizeProject(projectPath) {
         };
     }
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
-    const hasFraim = fs_1.default.existsSync(fraimDir);
+    const registryJobsDir = path_1.default.join(projectPath, 'registry', 'jobs');
+    const hasFraim = fs_1.default.existsSync(fraimDir) || fs_1.default.existsSync(registryJobsDir);
     if (!hasFraim) {
         return {
             path: projectPath,
@@ -154,6 +157,9 @@ function summarizeProject(projectPath) {
     };
 }
 function resolveLayerRoot(projectPath, layer) {
+    if (layer.base === 'registry') {
+        return path_1.default.join(projectPath, 'registry', ...layer.segments);
+    }
     return path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath), ...layer.segments);
 }
 function discoverLayers(projectPath, layers) {

package/dist/src/ai-hub/hosts.js

@@ -207,6 +207,7 @@ function extractSignalFromArgs(args) {
 const EMPLOYEE_LABELS = {
     codex: 'Codex',
     claude: 'Claude Code',
+    gemini: 'Gemini CLI',
 };
 const executableName = (command) => command;
 function quoteWindowsArg(value) {
@@ -237,9 +238,7 @@ const availableByVersionProbe = (command) => {
 };
 function detectEmployees() {
     return Object.keys(EMPLOYEE_LABELS).map((id) => {
-        const available = id === 'codex'
-            ? availableByVersionProbe(executableName('codex'))
-            : availableByVersionProbe(executableName('claude'));
+        const available = availableByVersionProbe(executableName(id));
         return {
             id,
             label: EMPLOYEE_LABELS[id],
@@ -256,6 +255,13 @@ function buildStartPlan(hostId, message) {
             stdin: message,
         };
     }
+    if (hostId === 'gemini') {
+        return {
+            command: executableName('gemini'),
+            args: ['--yolo'],
+            stdin: message,
+        };
+    }
     return {
         command: executableName('claude'),
         args: ['-p', '--verbose', '--output-format', 'stream-json', '--dangerously-skip-permissions'],
@@ -270,6 +276,15 @@ function buildContinuePlan(hostId, sessionId, message) {
             stdin: message,
         };
     }
+    if (hostId === 'gemini') {
+        // Gemini CLI does not have a native session-resume flag; each message
+        // is sent as a fresh invocation. The Hub still tracks state client-side.
+        return {
+            command: executableName('gemini'),
+            args: ['--yolo'],
+            stdin: message,
+        };
+    }
     return {
         command: executableName('claude'),
         args: ['-p', '--verbose', '--output-format', 'stream-json', '--dangerously-skip-permissions', '-r', sessionId],
@@ -307,6 +322,18 @@ function parseHostLine(hostId, line) {
             return withSignal({ raw: trimmed });
         }
     }
+    // Gemini CLI output: if the line is valid JSON, apply signal scanning and
+    // capture the raw line. Plain-text output (non-JSON) is captured as a raw
+    // message so it still surfaces in the Hub timeline.
+    if (hostId === 'gemini') {
+        try {
+            JSON.parse(trimmed); // validate JSON — if this throws, fall through to plain text
+            return withSignal({ raw: trimmed });
+        }
+        catch {
+            return withSignal({ message: trimmed, raw: trimmed });
+        }
+    }
     try {
         const parsed = JSON.parse(trimmed);
         if (parsed.type === 'system' && parsed.session_id) {
@@ -385,6 +412,7 @@ class FakeHostRuntime {
         this.employees = [
             { id: 'codex', label: 'Codex', available: true, detail: 'Test double employee.' },
             { id: 'claude', label: 'Claude Code', available: true, detail: 'Test double employee.' },
+            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Test double employee.' },
         ];
     }
     detectEmployees() {
@@ -444,6 +472,7 @@ class ScriptedHostRuntime {
         this.employees = [
             { id: 'codex', label: 'Codex', available: true, detail: 'Scripted test double.' },
             { id: 'claude', label: 'Claude Code', available: true, detail: 'Scripted test double.' },
+            { id: 'gemini', label: 'Gemini CLI', available: true, detail: 'Scripted test double.' },
         ];
         // Track each active run so the test can emit signals at it. Key is the
         // sessionId we hand back on startRun; mapping sessionId → handlers

package/dist/src/ai-hub/preferences.js

@@ -8,7 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const DEFAULT_CATEGORY = 'marketing';
-const DEFAULT_EMPLOYEE = 'codex';
+const DEFAULT_EMPLOYEE = 'claude';
 const defaultPreferences = (projectPath) => ({
     projectPath,
     employeeId: DEFAULT_EMPLOYEE,
@@ -27,8 +27,8 @@ class AiHubPreferencesStore {
             const raw = JSON.parse(fs_1.default.readFileSync(this.stateFilePath, 'utf8'));
             return {
                 projectPath: raw.projectPath || projectPath,
-                employeeId: raw.employeeId === 'claude' ? 'claude' : DEFAULT_EMPLOYEE,
-                categoryId: raw.categoryId === 'go-to-market' ? 'go-to-market' : DEFAULT_CATEGORY,
+                employeeId: (raw.employeeId === 'claude' || raw.employeeId === 'codex') ? raw.employeeId : DEFAULT_EMPLOYEE,
+                categoryId: typeof raw.categoryId === 'string' && raw.categoryId.length > 0 ? raw.categoryId : DEFAULT_CATEGORY,
                 recentJobIds: Array.isArray(raw.recentJobIds) ? raw.recentJobIds.filter((value) => typeof value === 'string') : [],
             };
         }

package/dist/src/ai-hub/server.js

@@ -9,8 +9,10 @@ const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const net_1 = __importDefault(require("net"));
+const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
+const types_1 = require("../first-run/types");
 const catalog_1 = require("./catalog");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
@@ -210,19 +212,100 @@ function deriveStages(run, projectPath) {
     const currentIndex = run.currentPhase
         ? declaredPath.findIndex((p) => p.id === run.currentPhase)
         : -1;
+    const historyMap = new Map((run.phaseHistory || []).map((e) => [e.phaseId, e]));
     return declaredPath.map((phase, index) => {
         let state;
-        if (currentIndex < 0)
+        if (currentIndex < 0) {
             state = 'upcoming';
-        else if (index < currentIndex)
+        }
+        else if (index < currentIndex) {
             state = 'done';
-        else if (index === currentIndex)
-            state = 'current';
-        else
+        }
+        else if (index === currentIndex) {
+            // If the agent has already reported this phase as 'complete', advance
+            // its visual state to 'done' so the tracker doesn't look frozen while
+            // waiting for the agent to start the next phase (e.g. after
+            // implement-submission completes but before address-feedback starts).
+            const entry = historyMap.get(phase.id);
+            state = entry?.latestStatus === 'complete' ? 'done' : 'current';
+        }
+        else {
             state = 'upcoming';
+        }
         return { phaseId: phase.id, label: phase.label, state };
     });
 }
+// ---------------------------------------------------------------------------
+// Agent install helpers (shared with first-run; duplicated here to avoid
+// the session-key dependency in that module's public API).
+// ---------------------------------------------------------------------------
+const HUB_TO_FIRST_RUN_ID = {
+    claude: 'claude-code',
+    codex: 'codex',
+    gemini: 'gemini-cli',
+};
+function hubAgentOption(hubId) {
+    const frId = HUB_TO_FIRST_RUN_ID[hubId];
+    return frId ? types_1.FIRST_RUN_AGENT_OPTIONS.find((o) => o.id === frId) : undefined;
+}
+function hubCommandVersion(command) {
+    const executable = process.platform === 'win32' ? 'cmd.exe' : command;
+    const args = process.platform === 'win32'
+        ? ['/d', '/s', '/c', `${command} --version`]
+        : ['--version'];
+    const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000 });
+    if (result.status !== 0 || result.error)
+        return null;
+    const raw = (result.stdout || result.stderr || '').trim();
+    return raw || null;
+}
+function hubRunProcess(command, args, env) {
+    return new Promise((resolve, reject) => {
+        const executable = process.platform === 'win32' && command === 'npm' ? 'npm.cmd' : command;
+        const child = (0, child_process_1.spawn)(executable, args, {
+            env: { ...process.env, ...env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(stderr || `Process exited with code ${code}`));
+        });
+        child.on('error', reject);
+    });
+}
+function hubOpenTerminal(command) {
+    if (process.platform === 'win32') {
+        (0, child_process_1.spawn)('cmd.exe', ['/c', 'start', 'cmd.exe', '/k', command], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    if (process.platform === 'darwin') {
+        const script = `tell application "Terminal" to do script "${command.replace(/"/g, '\\"')}"`;
+        (0, child_process_1.spawn)('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    const linux = [
+        ['gnome-terminal', ['--', 'bash', '-c', `${command}; exec bash`]],
+        ['xterm', ['-e', `bash -c '${command}; exec bash'`]],
+        ['konsole', ['--noclose', '-e', 'bash', '-c', command]],
+        ['x-terminal-emulator', ['-e', `bash -c '${command}; exec bash'`]],
+    ];
+    for (const [term, args] of linux) {
+        if ((0, child_process_1.spawnSync)('which', [term], { encoding: 'utf8' }).status === 0) {
+            (0, child_process_1.spawn)(term, args, { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+    }
+    (0, child_process_1.spawn)('bash', ['-c', command], { detached: true, stdio: 'ignore' }).unref();
+}
+function getUserHubDir() {
+    return path_1.default.join(os_1.default.homedir(), '.fraim');
+}
 function ensureDirectoryPath(projectPath) {
     const trimmed = (projectPath || '').trim();
     if (!trimmed) {
@@ -275,7 +358,18 @@ class AiHubServer {
     }
     bootstrapResponse(projectPath) {
         const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
-        const preferences = this.preferencesStore.load(normalizedProjectPath);
+        const employees = this.hostRuntime.detectEmployees();
+        let preferences = this.preferencesStore.load(normalizedProjectPath);
+        // If the stored employee isn't available on this machine, auto-select the
+        // first available one so the Hub never opens showing "(unavailable)".
+        const storedAvailable = employees.find((e) => e.id === preferences.employeeId)?.available ?? false;
+        if (!storedAvailable) {
+            const firstAvailable = employees.find((e) => e.available);
+            if (firstAvailable) {
+                preferences = { ...preferences, employeeId: firstAvailable.id };
+                this.preferencesStore.save(preferences);
+            }
+        }
         const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
         const jobs = (0, catalog_1.discoverEmployeeJobs)(normalizedProjectPath);
         const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath);
@@ -291,7 +385,7 @@ class AiHubServer {
             categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath),
             jobs,
             managerTemplates,
-            employees: this.hostRuntime.detectEmployees(),
+            employees,
             activeRun,
         };
     }
@@ -314,13 +408,76 @@ class AiHubServer {
                 return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open the folder picker.' });
             }
         });
+        this.app.post('/api/ai-hub/install-agent', async (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            try {
+                const prefix = path_1.default.join(getUserHubDir(), 'node');
+                fs_1.default.mkdirSync(prefix, { recursive: true });
+                await hubRunProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+                return res.json({
+                    ok: true,
+                    message: `${option.label} installed successfully.`,
+                    needsLogin: true,
+                    loginCommand: option.loginCommand,
+                    loginHint: `Sign in to ${option.label} to activate it. A terminal window will open — complete sign-in there, then click "Check if Ready".`,
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : 'Unknown error';
+                return res.status(500).json({ ok: false, error: `Failed to install ${option.label}: ${detail}` });
+            }
+        });
+        this.app.post('/api/ai-hub/trigger-agent-login', (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            try {
+                hubOpenTerminal(option.loginCommand);
+                return res.json({
+                    ok: true,
+                    message: `A terminal window opened with the ${option.label} sign-in command. Complete sign-in there, then return here.`,
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : 'Unknown error';
+                return res.json({
+                    ok: false,
+                    message: `Could not open a terminal automatically: ${detail}. Run \`${option.loginCommand}\` in a terminal to sign in.`,
+                });
+            }
+        });
+        this.app.post('/api/ai-hub/check-agent', (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            const ver = hubCommandVersion(option.launchCommand);
+            if (ver) {
+                return res.json({ ok: true, ready: true, message: `${option.label} is ready.` });
+            }
+            return res.json({
+                ok: true,
+                ready: false,
+                message: `${option.label} is not detected yet. Make sure sign-in is complete and try again.`,
+            });
+        });
         this.app.post('/api/ai-hub/runs', (req, res) => {
             try {
                 const projectPath = ensureDirectoryPath(req.body.projectPath || this.projectPath);
                 const hostId = req.body.hostId;
                 const jobId = req.body.jobId;
                 const message = (req.body.message || '').trim();
-                if (hostId !== 'codex' && hostId !== 'claude') {
+                if (hostId !== 'codex' && hostId !== 'claude' && hostId !== 'gemini') {
                     throw new Error('Choose an available employee before starting a job.');
                 }
                 if (!jobId) {

package/dist/src/cli/setup/ide-detector.js

@@ -102,7 +102,7 @@ exports.IDE_CONFIGS = [
         configPath: '~/.gemini/antigravity/mcp_config.json',
         configFormat: 'json',
         configType: 'standard',
-        invocationProfile: 'instructions-only',
+        invocationProfile: 'cursor-mention',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.gemini/antigravity')),
         description: 'Google Gemini Antigravity IDE'
     },

package/dist/src/cli/setup/ide-global-integration.js

@@ -72,6 +72,10 @@ async function installGlobalRules(homeDir) {
     if (fs_1.default.existsSync(geminiDir)) {
         installFileIfMissing(path_1.default.join(geminiDir, 'commands', 'fraim.toml'), (0, ide_invocation_surfaces_1.buildGeminiCommandContent)(), 'Gemini CLI FRAIM command (~/.gemini/commands/fraim.toml)');
     }
+    const antigravityDir = path_1.default.join(home, '.gemini', 'antigravity');
+    if (fs_1.default.existsSync(antigravityDir)) {
+        installFileIfMissing(path_1.default.join(antigravityDir, 'commands', 'fraim.md'), (0, ide_invocation_surfaces_1.buildAntigravityCommandContent)(), 'Antigravity FRAIM command (~/.gemini/antigravity/commands/fraim.md)');
+    }
     const windsurfDir = path_1.default.join(home, '.codeium', 'windsurf');
     if (fs_1.default.existsSync(windsurfDir)) {
         installFileIfMissing(path_1.default.join(windsurfDir, 'commands', 'fraim.md'), (0, ide_invocation_surfaces_1.buildWindsurfCommandContent)(), 'Windsurf FRAIM command (~/.codeium/windsurf/commands/fraim.md)');

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -9,6 +9,7 @@ exports.buildCursorMentionRuleContent = buildCursorMentionRuleContent;
 exports.buildCodexSkillContent = buildCodexSkillContent;
 exports.buildWindsurfCommandContent = buildWindsurfCommandContent;
 exports.buildKiroCommandContent = buildKiroCommandContent;
+exports.buildAntigravityCommandContent = buildAntigravityCommandContent;
 exports.buildGeminiCommandContent = buildGeminiCommandContent;
 exports.describeInvocationSurface = describeInvocationSurface;
 exports.FRAIM_LAUNCH_PHRASE = 'Use FRAIM for <job or task>';
@@ -111,6 +112,11 @@ ${buildFraimInvocationBody('generic-tool-discovery')}`;
 function escapeTomlMultiline(value) {
     return value.replace(/"""/g, '\\"""');
 }
+function buildAntigravityCommandContent() {
+    return `# FRAIM
+
+${buildFraimInvocationBody('generic-tool-discovery')}`;
+}
 function buildGeminiCommandContent() {
     return `description = "Discover and execute FRAIM jobs and skills"
 prompt = """

package/dist/src/core/fraim-config-schema.generated.js

@@ -231,6 +231,37 @@ exports.FRAIM_CONFIG_SCHEMA = {
                     "required": true
                 }
             }
+        },
+        "stakeholderUpdate": {
+            "kind": "object",
+            "properties": {
+                "stakeholderListPath": {
+                    "kind": "string"
+                },
+                "cadence": {
+                    "kind": "enum",
+                    "values": [
+                        "monthly",
+                        "quarterly"
+                    ]
+                },
+                "historyPath": {
+                    "kind": "string"
+                }
+            }
+        },
+        "operatingReview": {
+            "kind": "object",
+            "properties": {
+                "cadence": {
+                    "kind": "enum",
+                    "values": [
+                        "weekly",
+                        "bi-weekly",
+                        "monthly"
+                    ]
+                }
+            }
         }
     },
     "required": true
@@ -292,5 +323,11 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "customer-communication.senderEmail",
     "customer-communication.senderReplyTo",
     "customer-communication.newsletterAudienceProvider",
-    "customer-communication.deliveryProvider"
+    "customer-communication.deliveryProvider",
+    "stakeholderUpdate",
+    "stakeholderUpdate.stakeholderListPath",
+    "stakeholderUpdate.cadence",
+    "stakeholderUpdate.historyPath",
+    "operatingReview",
+    "operatingReview.cadence"
 ];

package/dist/src/first-run/server.js

@@ -234,6 +234,44 @@ class FirstRunServer {
             (0, setup_preferences_1.writeSetupHandoffChoice)(choice);
             return res.json({ ok: true });
         });
+        this.app.post('/api/first-run/install-agent', async (req, res) => {
+            try {
+                const { agentId } = req.body || {};
+                if (!agentId || typeof agentId !== 'string') {
+                    return res.status(400).json({ error: 'agentId is required.' });
+                }
+                const result = await this.sessionService.installAgent(agentId);
+                return res.json(result);
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not install agent.' });
+            }
+        });
+        this.app.post('/api/first-run/trigger-agent-login', async (req, res) => {
+            try {
+                const { agentId } = req.body || {};
+                if (!agentId || typeof agentId !== 'string') {
+                    return res.status(400).json({ error: 'agentId is required.' });
+                }
+                const result = await this.sessionService.triggerAgentLogin(agentId);
+                return res.json(result);
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not trigger login.' });
+            }
+        });
+        this.app.post('/api/first-run/check-agent', (req, res) => {
+            try {
+                const { agentId } = req.body || {};
+                if (!agentId || typeof agentId !== 'string') {
+                    return res.status(400).json({ error: 'agentId is required.' });
+                }
+                return res.json(this.sessionService.checkAgentReady(agentId));
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not check agent.' });
+            }
+        });
         // Hub-launch helper - starts an AiHubServer for the chosen project and
         // opens the user's browser. v2 (#355) replaces the in-process spawn with
         // a durable launcher binary that survives independently.

package/dist/src/first-run/session-service.js

@@ -257,8 +257,11 @@ class FirstRunSessionService {
         if (/ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|getaddrinfo|network/i.test(detail)) {
             return "Couldn't reach the FRAIM registry. Check your internet connection (or if you're testing locally, that the local FRAIM server is running) and click Retry.";
         }
+        if (/EPERM|EACCES|permission denied/i.test(detail)) {
+            return 'A security tool (Windows Defender, antivirus, or IT policy) may be locking files in the install folder. Try disabling real-time scanning for the ~/.fraim directory, then click Retry.';
+        }
         if (/Global FRAIM setup not found/i.test(detail)) {
-            return 'FRAIM\'s global config is missing. This usually means the agent step didn\'t complete cleanly — go back and re-run the AI agent row.';
+            return 'FRAIM\'s global config is missing. This usually means the agent step didn\'t complete cleanly — go back and re-run the AI agent row.';
         }
         return undefined;
     }
@@ -286,7 +289,7 @@ class FirstRunSessionService {
         }
         else {
             gitRow.status = 'pending';
-            gitRow.verb = "we'll install";
+            gitRow.verb = 'optional — only needed for code delivery workflows';
         }
         const fraimRow = this.getRow('fraim');
         if (commandVersion('npx') !== null) {
@@ -496,22 +499,19 @@ class FirstRunSessionService {
     }
     async runGitRow() {
         const row = this.getRow('git');
-        const ver = commandVersion('git');
+        const ver = commandVersion('git') || (this.fakeMode ? 'git version 2.45' : null);
         if (ver) {
             row.status = 'ok';
             row.verb = `${ver} installed`;
             this.persist();
             return this.respond(`git detected (${ver}).`, true);
         }
-        if (this.fakeMode) {
-            row.status = 'ok';
-            row.verb = 'git version 2.45 installed';
-            this.persist();
-            return this.respond('Fake-mode git ok.', true);
-        }
-        this.setRowError(row, 'Verifying git installation', 'git --version returned a non-zero exit code or no output.\n\nOn macOS, run `xcode-select --install` to install the Command Line Developer Tools, then retry. On Windows, install Git for Windows from https://git-scm.com/download/win.', [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
+        // git is optional — non-technical users and non-code workflows don't need it.
+        // Mark ok so the wizard is not blocked; the verb makes the situation clear.
+        row.status = 'ok';
+        row.verb = 'not installed — optional, only needed for code delivery';
         this.persist();
-        return this.respond('git not detected.', false);
+        return this.respond('git not found — continuing without it. Install git later if you plan to do code delivery work.', true);
     }
     async runFraimRow() {
         const row = this.getRow('fraim');
@@ -544,10 +544,10 @@ class FirstRunSessionService {
             await installSlashCommands();
             await installGlobalRules();
             row.status = 'ok';
-            row.verb = 'Ready.';
+            row.verb = 'Ready — open a new terminal before running fraim commands.';
             delete row.streamOutput;
             this.persist();
-            return this.respond('FRAIM is ready.', true);
+            return this.respond('FRAIM is ready. Open a new terminal window so your PATH update takes effect before running fraim commands.', true);
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : 'Unknown error';
@@ -574,6 +574,15 @@ class FirstRunSessionService {
             this.persist();
             return this.respond('AI Employee recruiting deferred.', true);
         }
+        if (this.fakeMode === 'agent-install-fails') {
+            this.setRowError(row, 'Checking for installed AI Employees and configuring one for this project', this.fakeStderr, [
+                { id: 'retry', label: 'Retry', variant: 'primary' },
+                { id: 'alternative', label: 'Try alternative', variant: 'secondary' },
+                { id: 'skip', label: 'Skip and continue', variant: 'ghost' },
+            ]);
+            this.persist();
+            return this.respond('AI Employee recruiting failed.', false);
+        }
         this.updateAgentSummaryRow();
         this.persist();
         const count = this.state.setupResult?.detectedSurfaceCount || 0;
@@ -623,11 +632,130 @@ class FirstRunSessionService {
      * leave the user typing a command. The single-file launcher binary in v2
      * (#355) replaces this in-process spawn with a durable tray-icon launcher.
      */
+    async installAgent(agentId) {
+        const option = findAgentOption(agentId);
+        if (!option) {
+            return { ok: false, message: `Unknown agent: ${agentId}` };
+        }
+        if (this.fakeMode) {
+            return {
+                ok: true,
+                message: `${option.label} installed successfully.`,
+                needsLogin: true,
+                loginCommand: option.loginCommand,
+                loginHint: `Sign in to ${option.label} to activate it.`,
+            };
+        }
+        try {
+            const prefix = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
+            fs_1.default.mkdirSync(prefix, { recursive: true });
+            await runProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+            const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
+            if (detectedIDEs.length > 0) {
+                await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, {}, detectedIDEs.map((ide) => ide.name), {});
+            }
+            appendInstallLog(`agent-installed ${agentId}`);
+            return {
+                ok: true,
+                message: `${option.label} installed successfully.`,
+                needsLogin: true,
+                loginCommand: option.loginCommand,
+                loginHint: `Sign in to ${option.label} to activate it. A terminal window will open with the sign-in command — complete sign-in there, then return here and click "Check if Ready".`,
+            };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'Unknown error';
+            appendInstallLog(`agent-install-failed ${agentId} ${detail}`);
+            return { ok: false, message: `Failed to install ${option.label}: ${detail}` };
+        }
+    }
+    async triggerAgentLogin(agentId) {
+        const option = findAgentOption(agentId);
+        if (!option) {
+            return { ok: false, message: `Unknown agent: ${agentId}` };
+        }
+        if (this.fakeMode) {
+            return { ok: true, message: `${option.label} login triggered (fake-mode).` };
+        }
+        try {
+            this.openTerminalWithCommand(option.loginCommand);
+            appendInstallLog(`agent-login-triggered ${agentId}`);
+            return {
+                ok: true,
+                message: `A terminal window opened with the ${option.label} sign-in command. Complete sign-in there, then return here.`,
+            };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                ok: false,
+                message: `Could not open a terminal automatically: ${detail}. Run \`${option.loginCommand}\` in a terminal to sign in.`,
+            };
+        }
+    }
+    checkAgentReady(agentId) {
+        const option = findAgentOption(agentId);
+        if (!option) {
+            return { ok: false, ready: false, message: `Unknown agent: ${agentId}` };
+        }
+        if (this.fakeMode) {
+            return { ok: true, ready: true, message: `${option.label} is ready (fake-mode).` };
+        }
+        const ver = commandVersion(option.launchCommand);
+        if (ver) {
+            this.updateAgentSummaryRow();
+            this.persist();
+            return { ok: true, ready: true, message: `${option.label} is ready.` };
+        }
+        return {
+            ok: true,
+            ready: false,
+            message: `${option.label} is not detected yet. Make sure sign-in is complete and try again.`,
+        };
+    }
+    openTerminalWithCommand(command) {
+        if (process.platform === 'win32') {
+            (0, child_process_1.spawn)('cmd.exe', ['/c', 'start', 'cmd.exe', '/k', command], { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+        if (process.platform === 'darwin') {
+            const script = `tell application "Terminal" to do script "${command.replace(/"/g, '\\"')}"`;
+            (0, child_process_1.spawn)('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+        const linux = [
+            ['gnome-terminal', ['--', 'bash', '-c', `${command}; exec bash`]],
+            ['xterm', ['-e', `bash -c '${command}; exec bash'`]],
+            ['konsole', ['--noclose', '-e', 'bash', '-c', command]],
+            ['x-terminal-emulator', ['-e', `bash -c '${command}; exec bash'`]],
+        ];
+        for (const [term, args] of linux) {
+            if ((0, child_process_1.spawnSync)('which', [term], { encoding: 'utf8' }).status === 0) {
+                (0, child_process_1.spawn)(term, args, { detached: true, stdio: 'ignore' }).unref();
+                return;
+            }
+        }
+    }
     async openHub() {
         if (this.fakeMode) {
-            // Tests don't actually want a Hub server running — just confirm intent.
+            // Tests don't actually want a Hub server running — just confirm intent.
             return { ok: true, message: 'Fake-mode Hub open requested.', hubUrl: 'http://127.0.0.1:0/ai-hub/?firstRun=true' };
         }
+        // Require at least one Hub-compatible CLI to be installed (binary on PATH)
+        // OR fully IDE-configured. Accept freshly-installed binaries even before
+        // their IDE config files exist (created on first run / login).
+        const hubCompatibleBinaries = ['claude', 'codex'];
+        const hubCompatibleIds = new Set(['claude-code', 'codex']);
+        const surfaces = buildConfiguredSurfaces();
+        const hasConfiguredCli = surfaces.some((s) => hubCompatibleIds.has(s.id));
+        const hasInstalledCli = hubCompatibleBinaries.some((cmd) => commandVersion(cmd) !== null);
+        if (!hasConfiguredCli && !hasInstalledCli) {
+            return {
+                ok: false,
+                needsAgentSetup: true,
+                message: "No AI agent (Claude Code or Codex) found on this machine. Let's install one first.",
+            };
+        }
         try {
             const { AiHubServer, findAvailablePort } = await Promise.resolve().then(() => __importStar(require('../ai-hub/server')));
             const port = await findAvailablePort(43091);

package/dist/src/first-run/types.js

@@ -58,7 +58,7 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
 function createInitialRows() {
     return [
         { id: 'node', label: 'Node.js', status: 'pending', verb: "we'll install" },
-        { id: 'git', label: 'git', status: 'pending', verb: "we'll install" },
+        { id: 'git', label: 'git', status: 'pending', verb: "we'll install", optional: true },
         { id: 'fraim', label: 'FRAIM', status: 'pending', verb: "we'll set up FRAIM" },
         { id: 'agent', label: 'AI Employees', status: 'pending', verb: "we'll check for AI Employees" },
     ];
@@ -73,14 +73,16 @@ function createInitialRows() {
  * - "Set up FRAIM": no rows ok yet.
  */
 function derivePrimaryButtonLabel(rows) {
-    const allOk = rows.every((row) => row.status === 'ok');
+    // Optional rows (e.g. git) never block wizard progression.
+    const required = rows.filter((row) => !row.optional);
+    const allOk = required.every((row) => row.status === 'ok');
     if (allOk)
         return 'Get Started';
-    // Skip-path: every row is ok-or-manual-required — nothing left for the wizard.
-    if (rows.every((row) => row.status === 'ok' || row.status === 'manual-required')) {
+    // Skip-path: every required row is ok-or-manual-required — nothing left for the wizard.
+    if (required.every((row) => row.status === 'ok' || row.status === 'manual-required')) {
         return 'Get Started';
     }
-    if (rows.some((row) => row.status === 'ok'))
+    if (required.some((row) => row.status === 'ok'))
         return 'Continue';
     return 'Set up FRAIM';
 }

package/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework - Smart Entry Point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.134",
+  "version": "2.0.136",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {

package/public/ai-hub/index.html

@@ -159,6 +159,7 @@
             <span class="employee-label">Employee:</span>
             <select id="employee-select" class="employee-select"></select>
           </div>
+          <div id="agent-install-panel"></div>
         </div>
         <div class="modal-footer">
           <span class="left">You can coach the employee with more detail after they start.</span>

package/public/ai-hub/script.js

@@ -40,7 +40,7 @@ function gatherElements() {
     'cancel1', 'next1', 'back2', 'start',
     'job-search', 'job-catalog', 'job-pick-status',
     'picked-name', 'picked-desc', 'instructions',
-    'employee-select',
+    'employee-select', 'agent-install-panel',
     // Issue #347 additions: tracker, template picker, totals.
     'tracker', 'tracker-rows', 'tracker-note',
     'template-picker-btn', 'template-popover',
@@ -891,6 +891,153 @@ function renderEmployeeSelect() {
     if (state.selectedEmployeeId === emp.id) opt.selected = true;
     els['employee-select'].appendChild(opt);
   }
+  renderAgentInstallPanel();
+}
+
+// ---------------------------------------------------------------------------
+// Agent install panel — shown in Step 2 for unavailable agents
+// ---------------------------------------------------------------------------
+
+// Per-agent install state tracked within the modal session.
+const agentInstallState = {};
+
+function renderAgentInstallPanel() {
+  const panel = els['agent-install-panel'];
+  if (!panel) return;
+  panel.innerHTML = '';
+
+  const employees = state.bootstrap?.employees || [];
+  const unavailable = employees.filter((e) => !e.available);
+  if (unavailable.length === 0) return;
+
+  const heading = document.createElement('div');
+  heading.className = 'install-panel-heading';
+  heading.textContent = 'Install missing agents';
+  panel.appendChild(heading);
+
+  for (const emp of unavailable) {
+    const row = document.createElement('div');
+    row.className = 'install-row';
+    row.id = `install-row-${emp.id}`;
+
+    const label = document.createElement('span');
+    label.className = 'install-label';
+    label.textContent = emp.label;
+    row.appendChild(label);
+
+    const status = document.createElement('span');
+    status.className = 'install-status';
+    status.id = `install-status-${emp.id}`;
+    status.textContent = agentInstallState[emp.id]?.statusText || '';
+    row.appendChild(status);
+
+    const btn = document.createElement('button');
+    btn.className = 'secondary small';
+    btn.id = `install-btn-${emp.id}`;
+    btn.dataset.hubId = emp.id;
+
+    const st = agentInstallState[emp.id] || {};
+    if (!st.phase) {
+      btn.textContent = `Install ${emp.label}`;
+      btn.addEventListener('click', () => startAgentInstall(emp.id));
+    } else if (st.phase === 'installing') {
+      btn.textContent = 'Installing…';
+      btn.disabled = true;
+    } else if (st.phase === 'needs-login') {
+      btn.textContent = 'Sign In';
+      btn.addEventListener('click', () => triggerAgentLogin(emp.id));
+    } else if (st.phase === 'login-triggered') {
+      const checkBtn = document.createElement('button');
+      checkBtn.className = 'secondary small';
+      checkBtn.textContent = 'Check if Ready';
+      checkBtn.addEventListener('click', () => checkAgentReady(emp.id));
+      row.appendChild(checkBtn);
+
+      const skipBtn = document.createElement('button');
+      skipBtn.className = 'ghost small';
+      skipBtn.textContent = 'Skip for now';
+      skipBtn.style.marginLeft = '6px';
+      skipBtn.addEventListener('click', () => {
+        delete agentInstallState[emp.id];
+        renderAgentInstallPanel();
+      });
+      row.appendChild(skipBtn);
+      panel.appendChild(row);
+      continue;
+    } else if (st.phase === 'ready') {
+      btn.textContent = '✓ Ready';
+      btn.disabled = true;
+      btn.style.color = 'var(--accent)';
+    } else if (st.phase === 'error') {
+      btn.textContent = 'Retry';
+      btn.addEventListener('click', () => startAgentInstall(emp.id));
+    }
+
+    row.appendChild(btn);
+    panel.appendChild(row);
+  }
+}
+
+function setInstallState(hubId, phase, statusText) {
+  agentInstallState[hubId] = { phase, statusText: statusText || '' };
+  renderAgentInstallPanel();
+}
+
+async function startAgentInstall(hubId) {
+  setInstallState(hubId, 'installing', 'Installing…');
+  try {
+    const result = await requestJson('/api/ai-hub/install-agent', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ hubId }),
+    });
+    if (result.ok) {
+      setInstallState(hubId, 'needs-login', result.loginHint || 'Installed. Sign in to activate.');
+    } else {
+      setInstallState(hubId, 'error', result.message || 'Install failed.');
+    }
+  } catch (err) {
+    setInstallState(hubId, 'error', err.message || 'Install failed.');
+  }
+}
+
+async function triggerAgentLogin(hubId) {
+  try {
+    const result = await requestJson('/api/ai-hub/trigger-agent-login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ hubId }),
+    });
+    setInstallState(hubId, 'login-triggered', result.message || 'Sign-in terminal opened.');
+  } catch (err) {
+    setInstallState(hubId, 'error', err.message || 'Could not open terminal.');
+  }
+}
+
+async function checkAgentReady(hubId) {
+  try {
+    const result = await requestJson('/api/ai-hub/check-agent', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ hubId }),
+    });
+    if (result.ready) {
+      setInstallState(hubId, 'ready', `${result.message}`);
+      await refreshEmployees();
+    } else {
+      setInstallState(hubId, 'login-triggered', result.message || 'Not ready yet — complete sign-in and try again.');
+    }
+  } catch (err) {
+    setInstallState(hubId, 'error', err.message || 'Check failed.');
+  }
+}
+
+async function refreshEmployees() {
+  try {
+    const bootstrap = await requestJson(`/api/ai-hub/bootstrap?projectPath=${encodeURIComponent(state.projectPath)}`);
+    state.bootstrap = bootstrap;
+    renderEmployeeSelect();
+  } catch { /* best-effort */ }
 }
 
 // ---------------------------------------------------------------------------
@@ -937,6 +1084,7 @@ function deriveTitle(jobTitle, instructions) {
 const FRAIM_INVOCATION_SYMBOL = {
   codex: '$fraim',
   claude: '/fraim',
+  gemini: '/fraim',
 };
 
 function fraimInvocationFor(employeeId, jobId, kind) {
@@ -956,6 +1104,13 @@ function buildAgentMessage(employeeId, jobId, kind, instructions, stubPath) {
   const stub = (kind === 'start' && stubPath) ? `\n[Job stub: ${stubPath}]` : '';
   const trimmed = (instructions || '').trim();
   if (!trimmed) return `${invocation}${stub}`;
+  // For continue turns, applyTemplateInvocation already writes the full
+  // FRAIM invocation (e.g. "/fraim follow-your-mentor") into the textarea.
+  // If the text already starts with a known FRAIM symbol, don't prepend again.
+  if (kind === 'continue') {
+    const knownSymbols = Object.values(FRAIM_INVOCATION_SYMBOL);
+    if (knownSymbols.some((s) => trimmed.startsWith(s))) return trimmed;
+  }
   return `${invocation}${stub}\n\n${trimmed}`;
 }
 

package/public/ai-hub/styles.css

@@ -662,6 +662,27 @@ button { font: inherit; cursor: pointer; }
 }
 .employee-select:focus { outline: none; border-color: var(--accent); }
 
+/* Agent install panel */
+#agent-install-panel { margin-top: 10px; }
+.install-panel-heading {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: .04em;
+  margin-bottom: 6px;
+}
+.install-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 0;
+  font-size: 13px;
+}
+.install-label { font-weight: 500; min-width: 90px; }
+.install-status { color: var(--muted); flex: 1; font-size: 12px; }
+button.small { padding: 4px 10px; font-size: 12px; }
+
 @media (max-width: 820px) {
   /* Single-column reflow — the rigid 100vh layout doesn't make sense at
      mobile width because the rail stacks above the conversation. Let the

package/public/first-run/script.js

@@ -243,46 +243,72 @@
     PRIMARY_BUTTON.style.display = 'none';
     setHeader('Recruit AI Employees', 'Choose how you want to add AI Employees to this machine.');
 
-    const options = [
-      { title: 'Claude Code', desc: 'Install Claude Code and connect it to FRAIM.' },
-      { title: 'Codex', desc: 'Install Codex and connect it to FRAIM.' },
-      { title: 'Gemini CLI', desc: 'Install Gemini CLI and connect it to FRAIM.' },
-      { title: 'Bring Your Own Agent', desc: 'Install Cursor, Windsurf, Kiro, VS Code, or another supported AI tool.' },
+    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' },
     ];
 
-    for (const option of options) {
+    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 = option.title;
+      title.textContent = opt.label;
       const desc = document.createElement('p');
       desc.className = 'card-desc';
-      desc.textContent = option.desc;
+      desc.textContent = AGENT_DESCS[opt.id] || ('Install ' + opt.label + ' and connect it to FRAIM.');
       card.appendChild(title);
       card.appendChild(desc);
 
-      if (option.title === 'Bring Your Own Agent') {
-        const note = document.createElement('p');
-        note.className = 'card-desc';
-        note.textContent = 'When you are done installing your agent, run:';
-        card.appendChild(note);
-        const cmd = document.createElement('div');
-        cmd.className = 'cmd-block';
-        cmd.textContent = 'npx fraim add-ide';
-        card.appendChild(cmd);
-      }
+      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';
+    continueBtn.textContent = 'Continue without AI Agent';
     continueBtn.addEventListener('click', async () => {
       try {
         const ideData = await api('/api/first-run/ide-commands');
@@ -295,6 +321,161 @@
     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 = '';
@@ -342,8 +523,13 @@
         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');
@@ -431,6 +617,10 @@
       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');