fraim 2.0.134 → 2.0.135

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/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

@@ -210,16 +210,26 @@ 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 };
     });
 }
@@ -275,7 +285,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 +312,7 @@ class AiHubServer {
             categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath),
             jobs,
             managerTemplates,
-            employees: this.hostRuntime.detectEmployees(),
+            employees,
             activeRun,
         };
     }

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.135",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {

package/public/ai-hub/script.js

@@ -956,6 +956,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/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');