fraim-framework 2.0.126 → 2.0.128

package/dist/src/cli/doctor/checks/ide-config-checks.js

@@ -60,6 +60,8 @@ function checkMCPConfigsExist() {
             let existCount = 0;
             let missingCount = 0;
             const missing = [];
+            const bootstrapableMissing = [];
+            const blockingMissing = [];
             for (const ide of installedIDEs) {
                 const configPath = (0, ide_detector_1.expandPath)(ide.configPath);
                 if (fs_1.default.existsSync(configPath)) {
@@ -68,6 +70,12 @@ function checkMCPConfigsExist() {
                 else {
                     missingCount++;
                     missing.push(ide.name);
+                    if (ide.supportsConfigBootstrap) {
+                        bootstrapableMissing.push(ide.name);
+                    }
+                    else {
+                        blockingMissing.push(ide.name);
+                    }
                 }
             }
             if (missingCount === 0) {
@@ -86,11 +94,21 @@ function checkMCPConfigsExist() {
                     details: { existCount, missingCount, missing }
                 };
             }
+            if (blockingMissing.length === 0 && bootstrapableMissing.length > 0) {
+                return {
+                    status: 'warning',
+                    message: `Detected IDEs still need initial MCP config bootstrap: ${bootstrapableMissing.join(', ')}`,
+                    suggestion: 'Run fraim add-ide to create the initial MCP configuration',
+                    command: 'fraim add-ide',
+                    details: { missingCount, missing, bootstrapableMissing }
+                };
+            }
             return {
                 status: 'error',
-                message: 'No MCP configs found',
+                message: `No MCP configs found for detected IDEs: ${blockingMissing.join(', ')}`,
                 suggestion: 'Run fraim add-ide to configure MCP servers',
-                command: 'fraim add-ide'
+                command: 'fraim add-ide',
+                details: { missingCount, missing, blockingMissing, bootstrapableMissing }
             };
         }
     };

package/dist/src/cli/fraim.js

@@ -51,6 +51,7 @@ const login_1 = require("./commands/login");
 const mcp_1 = require("./commands/mcp");
 const migrate_project_fraim_1 = require("./commands/migrate-project-fraim");
 const hub_1 = require("./commands/hub");
+const first_run_1 = require("./commands/first-run");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
@@ -91,6 +92,7 @@ program.addCommand(login_1.loginCommand);
 program.addCommand(mcp_1.mcpCommand);
 program.addCommand(migrate_project_fraim_1.migrateProjectFraimCommand);
 program.addCommand(hub_1.hubCommand);
+program.addCommand(first_run_1.firstRunCommand);
 // Wait for async command initialization before parsing
 (async () => {
     // Import the initialization promise from setup command

package/dist/src/cli/mcp/ide-formats.js

@@ -2,7 +2,7 @@
 // IDE Format Adapters - transform logical server structure to IDE-specific formats
 // Uses the centralized registry to determine server types
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IDE_FORMATS = exports.CodexFormat = exports.WindsurfFormat = exports.ClaudeCodeFormat = exports.ClaudeFormat = exports.VSCodeFormat = exports.KiroFormat = exports.StandardFormat = void 0;
+exports.IDE_FORMATS = exports.CodexFormat = exports.WindsurfFormat = exports.ClaudeCodeFormat = exports.ClaudeFormat = exports.GeminiCliFormat = exports.VSCodeFormat = exports.KiroFormat = exports.StandardFormat = void 0;
 exports.getIDEFormat = getIDEFormat;
 const mcp_server_registry_1 = require("./mcp-server-registry");
 const provider_registry_1 = require("../providers/provider-registry");
@@ -93,6 +93,33 @@ class VSCodeFormat {
     }
 }
 exports.VSCodeFormat = VSCodeFormat;
+class GeminiCliFormat {
+    constructor() {
+        this.name = 'gemini-cli';
+    }
+    transform(servers) {
+        const mcpServers = {};
+        for (const [key, server] of servers) {
+            if (server.url) {
+                mcpServers[key] = {
+                    ...(server.type === 'sse'
+                        ? { url: server.url }
+                        : { httpUrl: server.httpUrl || server.url }),
+                    ...(server.headers && { headers: server.headers })
+                };
+            }
+            else {
+                mcpServers[key] = {
+                    command: server.command,
+                    ...(server.args && { args: server.args }),
+                    ...(server.env && { env: server.env })
+                };
+            }
+        }
+        return { mcpServers };
+    }
+}
+exports.GeminiCliFormat = GeminiCliFormat;
 // Claude Desktop format (excludes provider servers - Issue #132)
 class ClaudeFormat {
     constructor() {
@@ -230,6 +257,7 @@ exports.IDE_FORMATS = {
     standard: new StandardFormat(),
     kiro: new KiroFormat(),
     vscode: new VSCodeFormat(),
+    'gemini-cli': new GeminiCliFormat(),
     claude: new ClaudeFormat(),
     'claude-code': new ClaudeCodeFormat(),
     windsurf: new WindsurfFormat(),

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -85,6 +85,7 @@ function buildHTTPServer(mcpConfig, token) {
     }
     const authHeader = mcpConfig.authHeaderTemplate?.replace('{token}', token) || `Bearer ${token}`;
     return {
+        type: 'http',
         url: mcpConfig.url,
         headers: {
             Authorization: authHeader

package/dist/src/cli/setup/auto-mcp-setup.js

@@ -252,9 +252,9 @@ const configureIDEMCP = async (ide, fraimKey, tokenInput, providerConfigs) => {
 const autoConfigureMCP = async (fraimKey, tokenInput, selectedIDEs, providerConfigs) => {
     const tokens = normalizePlatformTokens(tokenInput);
     const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
-    if (detectedIDEs.length === 0) {
+    if (detectedIDEs.length === 0 && (!selectedIDEs || selectedIDEs.length === 0)) {
         console.log(chalk_1.default.yellow('⚠️ No supported IDEs detected.'));
-        console.log(chalk_1.default.gray('Supported IDEs: Claude, Antigravity, Kiro, Cursor, VSCode, Codex, Windsurf'));
+        console.log(chalk_1.default.gray('Supported IDEs: Claude, Claude Code, Antigravity, Gemini CLI, Kiro, Cursor, VSCode, Codex, Windsurf'));
         console.log(chalk_1.default.blue('\n💡 You can install an IDE and run setup again later.'));
         console.log(chalk_1.default.gray('   Or continue with manual MCP configuration.'));
         if (process.env.FRAIM_NON_INTERACTIVE) {
@@ -275,13 +275,19 @@ const autoConfigureMCP = async (fraimKey, tokenInput, selectedIDEs, providerConf
     }
     let idesToConfigure;
     if (selectedIDEs && selectedIDEs.length > 0) {
-        // Use command line specified IDEs
-        idesToConfigure = detectedIDEs.filter(ide => selectedIDEs.some(selected => ide.name.toLowerCase().includes(selected.toLowerCase())));
+        idesToConfigure = detectedIDEs.filter((ide) => selectedIDEs.some((selected) => ide.name.toLowerCase().includes(selected.toLowerCase())));
         if (idesToConfigure.length === 0) {
-            console.log(chalk_1.default.yellow(`⚠️ No IDEs found matching: ${selectedIDEs.join(', ')}`));
-            console.log(chalk_1.default.gray('Available IDEs:'));
-            detectedIDEs.forEach(ide => console.log(chalk_1.default.gray(`   • ${ide.name}`)));
-            return;
+            idesToConfigure = (0, ide_detector_1.getAllSupportedIDEs)().filter((ide) => selectedIDEs.some((selected) => {
+                const normalized = selected.toLowerCase();
+                return ide.name.toLowerCase().includes(normalized)
+                    || ide.aliases?.some((alias) => alias.includes(normalized));
+            }));
+            if (idesToConfigure.length === 0) {
+                console.log(chalk_1.default.yellow(`⚠️ No IDEs found matching: ${selectedIDEs.join(', ')}`));
+                console.log(chalk_1.default.gray('Available IDEs:'));
+                detectedIDEs.forEach((ide) => console.log(chalk_1.default.gray(`   • ${ide.name}`)));
+                return;
+            }
         }
     }
     else {

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

@@ -7,6 +7,7 @@ exports.expandPath = exports.findIDEByName = exports.getAllSupportedIDEs = expor
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
 const expandPath = (filePath) => {
     if (filePath.startsWith('~/')) {
         return path_1.default.join(os_1.default.homedir(), filePath.slice(2));
@@ -17,6 +18,12 @@ exports.expandPath = expandPath;
 const checkMultiplePaths = (paths) => {
     return paths.some(p => fs_1.default.existsSync(expandPath(p)));
 };
+const availableByVersionProbe = (command) => {
+    const result = process.platform === 'win32'
+        ? (0, child_process_1.spawnSync)('cmd.exe', ['/d', '/s', '/c', `${command} --version`], { encoding: 'utf8', timeout: 1500 })
+        : (0, child_process_1.spawnSync)(command, ['--version'], { encoding: 'utf8', timeout: 1500 });
+    return result.status === 0;
+};
 const detectClaude = () => {
     const paths = [
         '~/.claude.json',
@@ -54,6 +61,15 @@ const detectWindsurf = () => {
     ];
     return checkMultiplePaths(paths);
 };
+const detectGeminiCli = () => {
+    const paths = [
+        '~/.gemini/settings.json',
+        '~/.gemini',
+        '~/AppData/Roaming/gemini/settings.json',
+        '~/.config/gemini/settings.json'
+    ];
+    return checkMultiplePaths(paths) || availableByVersionProbe('gemini');
+};
 exports.IDE_CONFIGS = [
     {
         name: 'Claude Code',
@@ -90,6 +106,21 @@ exports.IDE_CONFIGS = [
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.gemini/antigravity')),
         description: 'Google Gemini Antigravity IDE'
     },
+    {
+        name: 'Gemini CLI',
+        configPath: '~/.gemini/settings.json',
+        configFormat: 'json',
+        configType: 'gemini-cli',
+        invocationProfile: 'gemini-command',
+        detectMethod: detectGeminiCli,
+        supportsConfigBootstrap: true,
+        aliases: ['gemini', 'gemini-cli', 'gemini cli'],
+        alternativePaths: [
+            '~/AppData/Roaming/gemini/settings.json',
+            '~/.config/gemini/settings.json'
+        ],
+        description: 'Google Gemini CLI local settings'
+    },
     {
         name: 'Kiro',
         configPath: '~/.kiro/settings/mcp.json',
@@ -186,6 +217,6 @@ const findIDEByName = (name) => {
     const normalized = name.toLowerCase();
     return exports.IDE_CONFIGS.find(ide => ide.name.toLowerCase().includes(normalized) ||
         normalized.includes(ide.name.toLowerCase()) ||
-        ide.aliases?.some(alias => alias.includes(normalized) || normalized.includes(alias)));
+        ide.aliases?.some(alias => alias.toLowerCase().includes(normalized) || normalized.includes(alias.toLowerCase())));
 };
 exports.findIDEByName = findIDEByName;

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

@@ -36,7 +36,7 @@ async function installSlashCommands(homeDir) {
 }
 /**
  * Install FRAIM invocation artifacts for non-Claude IDEs.
- * Supports: Cursor, Codex, Windsurf, Kiro
+ * Supports: Cursor, Codex, Gemini CLI, Windsurf, Kiro
  * Does not overwrite existing files.
  */
 async function installGlobalRules(homeDir) {
@@ -49,6 +49,10 @@ async function installGlobalRules(homeDir) {
     if (fs_1.default.existsSync(codexDir)) {
         installFileIfMissing(path_1.default.join(codexDir, 'skills', 'fraim', 'SKILL.md'), (0, ide_invocation_surfaces_1.buildCodexSkillContent)(), 'Codex FRAIM skill (~/.codex/skills/fraim/SKILL.md)');
     }
+    const geminiDir = path_1.default.join(home, '.gemini');
+    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 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.buildGeminiCommandContent = buildGeminiCommandContent;
 exports.describeInvocationSurface = describeInvocationSurface;
 exports.FRAIM_LAUNCH_PHRASE = 'Use FRAIM for <job or task>';
 exports.CURSOR_MDC_FRONTMATTER = `---
@@ -107,6 +108,17 @@ function buildKiroCommandContent() {
 
 ${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
+function escapeTomlMultiline(value) {
+    return value.replace(/"""/g, '\\"""');
+}
+function buildGeminiCommandContent() {
+    return `description = "Discover and execute FRAIM jobs and skills"
+prompt = """
+# FRAIM
+
+${escapeTomlMultiline(buildFraimInvocationBody('generic-tool-discovery'))}
+"""`;
+}
 function describeInvocationSurface(ideName, invocationProfile) {
     switch (invocationProfile) {
         case 'claude-slash':
@@ -125,6 +137,8 @@ function describeInvocationSurface(ideName, invocationProfile) {
             return `${ideName}: /fraim`;
         case 'kiro-hashtag':
             return `${ideName}: #fraim`;
+        case 'gemini-command':
+            return `${ideName}: /fraim`;
         case 'instructions-only':
         default:
             return `${ideName}: natural language`;

package/dist/src/cli/setup/mcp-config-generator.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateMCPConfig = exports.generateWindsurfMCPServers = exports.generateVSCodeMCPServers = exports.generateCodexMCPServers = exports.generateKiroMCPServers = exports.generateClaudeCodeMCPServers = exports.generateClaudeMCPServers = exports.generateStandardMCPServers = exports.mergeTomlMCPServers = exports.extractTomlMcpServerBlock = void 0;
+exports.generateMCPConfig = exports.generateWindsurfMCPServers = exports.generateGeminiCliMCPServers = exports.generateVSCodeMCPServers = exports.generateCodexMCPServers = exports.generateKiroMCPServers = exports.generateClaudeCodeMCPServers = exports.generateClaudeMCPServers = exports.generateStandardMCPServers = exports.mergeTomlMCPServers = exports.extractTomlMcpServerBlock = void 0;
 const mcp_server_builder_1 = require("../mcp/mcp-server-builder");
 const ide_formats_1 = require("../mcp/ide-formats");
 const normalizeTokens = (tokenInput) => {
@@ -160,6 +160,15 @@ const generateVSCodeMCPServers = async (fraimKey, tokenInput, providerConfigs) =
     return format.transform(builder.getServers());
 };
 exports.generateVSCodeMCPServers = generateVSCodeMCPServers;
+const generateGeminiCliMCPServers = async (fraimKey, tokenInput, providerConfigs) => {
+    const tokens = normalizeTokens(tokenInput);
+    const builder = new mcp_server_builder_1.MCPServerBuilder();
+    builder.addBaseServers(fraimKey);
+    await addProviderServers(builder, tokens, providerConfigs);
+    const format = (0, ide_formats_1.getIDEFormat)('gemini-cli');
+    return format.transform(builder.getServers());
+};
+exports.generateGeminiCliMCPServers = generateGeminiCliMCPServers;
 const generateWindsurfMCPServers = async (fraimKey, tokenInput, providerConfigs) => {
     const tokens = normalizeTokens(tokenInput);
     const builder = new mcp_server_builder_1.MCPServerBuilder();
@@ -181,6 +190,8 @@ const generateMCPConfig = async (configType, fraimKey, tokenInput, providerConfi
             return await (0, exports.generateKiroMCPServers)(fraimKey, tokenInput, providerConfigs);
         case 'vscode':
             return await (0, exports.generateVSCodeMCPServers)(fraimKey, tokenInput, providerConfigs);
+        case 'gemini-cli':
+            return await (0, exports.generateGeminiCliMCPServers)(fraimKey, tokenInput, providerConfigs);
         case 'codex':
             return await (0, exports.generateCodexMCPServers)(fraimKey, tokenInput, providerConfigs);
         case 'windsurf':

package/dist/src/cli/utils/agent-adapters.js

@@ -15,6 +15,8 @@ const CLAUDE_FRAIM_COMMAND_PATH = path_1.default.join('.claude', 'commands', 'fr
 const CLAUDE_FRAIM_SKILL_PATH = path_1.default.join('.claude', 'skills', 'fraim', 'SKILL.md');
 const VSCODE_FRAIM_PROMPT_PATH = path_1.default.join('.github', 'prompts', 'fraim.prompt.md');
 const CODEX_FRAIM_SKILL_PATH = path_1.default.join('.codex', 'skills', 'fraim', 'SKILL.md');
+const GEMINI_FRAIM_COMMAND_PATH = path_1.default.join('.gemini', 'commands', 'fraim.toml');
+const GEMINI_PROJECT_INSTRUCTIONS_PATH = path_1.default.join('.gemini', 'GEMINI.md');
 const WINDSURF_FRAIM_COMMAND_PATH = path_1.default.join('.windsurf', 'commands', 'fraim.md');
 const KIRO_FRAIM_COMMAND_PATH = path_1.default.join('.kiro', 'commands', 'fraim.md');
 function buildManagedSection(body) {
@@ -102,6 +104,10 @@ Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then
     const vscodePrompt = `# FRAIM
 
 ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}`;
+    const geminiProjectInstructions = `# Gemini Project Instructions
+
+@../AGENTS.md
+`;
     return [
         { path: 'AGENTS.md', content: markdownBody },
         { path: 'CLAUDE.md', content: markdownBody },
@@ -112,6 +118,8 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
         { path: CLAUDE_FRAIM_SKILL_PATH, content: (0, ide_invocation_surfaces_1.buildClaudeSkillContent)() },
         { path: CLAUDE_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildClaudeCommandShimContent)() },
         { path: CODEX_FRAIM_SKILL_PATH, content: (0, ide_invocation_surfaces_1.buildCodexSkillContent)() },
+        { path: GEMINI_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildGeminiCommandContent)() },
+        { path: GEMINI_PROJECT_INSTRUCTIONS_PATH, content: geminiProjectInstructions },
         { path: WINDSURF_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildWindsurfCommandContent)() },
         { path: KIRO_FRAIM_COMMAND_PATH, content: (0, ide_invocation_surfaces_1.buildKiroCommandContent)() }
     ];
@@ -132,6 +140,8 @@ function ensureAgentAdapterFiles(projectRoot) {
                 || file.path === CLAUDE_FRAIM_SKILL_PATH
                 || file.path === CLAUDE_FRAIM_COMMAND_PATH
                 || file.path === CODEX_FRAIM_SKILL_PATH
+                || file.path === GEMINI_FRAIM_COMMAND_PATH
+                || file.path === GEMINI_PROJECT_INSTRUCTIONS_PATH
                 || file.path === WINDSURF_FRAIM_COMMAND_PATH
                 || file.path === KIRO_FRAIM_COMMAND_PATH
                 ? file.content

package/dist/src/core/utils/git-utils.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExplicitLocalRepoPath = isExplicitLocalRepoPath;
 exports.getPort = getPort;
 exports.determineDatabaseName = determineDatabaseName;
 exports.getCurrentGitBranch = getCurrentGitBranch;
@@ -19,6 +20,18 @@ function extractLocalFolderLabel(rawPath) {
     const candidate = parts[parts.length - 1];
     return candidate || undefined;
 }
+function isExplicitLocalRepoPath(repoUrl) {
+    if (!repoUrl || typeof repoUrl !== 'string') {
+        return false;
+    }
+    const trimmed = repoUrl.trim();
+    return (trimmed.startsWith('/') ||
+        trimmed.startsWith('\\') ||
+        /^[a-zA-Z]:[\\/]/.test(trimmed) ||
+        trimmed.startsWith('./') ||
+        trimmed.startsWith('../') ||
+        trimmed.startsWith('file://'));
+}
 /**
  * Gets a unique port based on the current git branch name (if it's an issue branch)
  * Default to 15302 if not on an issue branch
@@ -119,12 +132,7 @@ function sanitizeRepoIdentifier(repoUrl) {
     }
     const trimmed = repoUrl.trim();
     // Convert local paths to just the folder name for privacy-safe workspace labeling.
-    if (trimmed.startsWith('/') ||
-        trimmed.startsWith('\\') ||
-        /^[a-zA-Z]:[\\/]/.test(trimmed) ||
-        trimmed.startsWith('./') ||
-        trimmed.startsWith('../') ||
-        trimmed.startsWith('file://')) {
+    if (isExplicitLocalRepoPath(trimmed)) {
         return extractLocalFolderLabel(trimmed);
     }
     // Normalize GitHub/GitLab SSH and HTTPS URLs

package/dist/src/first-run/install-state.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInitialFirstRunState = createInitialFirstRunState;
+exports.loadFirstRunState = loadFirstRunState;
+exports.saveFirstRunState = saveFirstRunState;
+exports.clearFirstRunState = clearFirstRunState;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
+const types_1 = require("./types");
+function getStatePath() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'install-state.json');
+}
+function ensureUserDir() {
+    fs_1.default.mkdirSync((0, script_sync_utils_1.getUserFraimDir)(), { recursive: true });
+}
+function maskInstallKey(key) {
+    const normalized = key.trim();
+    if (normalized.length <= 8) {
+        return '<redacted>';
+    }
+    return `${normalized.slice(0, 4)}...${normalized.slice(-4)}`;
+}
+function createInitialFirstRunState(key) {
+    const now = new Date().toISOString();
+    return {
+        version: 2,
+        installKeyRef: maskInstallKey(key),
+        platform: process.platform,
+        agentId: 'claude-code',
+        rows: (0, types_1.createInitialRows)(),
+        resourcesUrl: types_1.FIRST_RUN_RESOURCES_URL,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function loadFirstRunState() {
+    const statePath = getStatePath();
+    if (!fs_1.default.existsSync(statePath)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs_1.default.readFileSync(statePath, 'utf8'));
+        // Reject persisted v1 state — schema changed materially in #352 v1.
+        if (state.version !== 2) {
+            return null;
+        }
+        if (typeof state.installKeyRef === 'string' && !state.installKeyRef.includes('...')) {
+            state.installKeyRef = maskInstallKey(state.installKeyRef);
+        }
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+function saveFirstRunState(state) {
+    ensureUserDir();
+    state.updatedAt = new Date().toISOString();
+    fs_1.default.writeFileSync(getStatePath(), JSON.stringify(state, null, 2));
+}
+function clearFirstRunState() {
+    const statePath = getStatePath();
+    if (fs_1.default.existsSync(statePath)) {
+        fs_1.default.unlinkSync(statePath);
+    }
+}

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

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirstRunServer = void 0;
+const express_1 = __importDefault(require("express"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const session_service_1 = require("./session-service");
+function resolveFirstRunPublicDir() {
+    const candidates = [
+        path_1.default.resolve(process.cwd(), 'public/first-run'),
+        path_1.default.resolve(__dirname, '..', '..', 'public/first-run'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'public/first-run'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error('Could not locate public/first-run assets.');
+}
+function pickProjectPath() {
+    if (process.platform === 'win32') {
+        const script = [
+            'Add-Type -AssemblyName System.Windows.Forms',
+            '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.ShowNewFolderButton = $true',
+            'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
+            '  Write-Output $dialog.SelectedPath',
+            '}',
+        ].join('; ');
+        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-Command', script], {
+            encoding: 'utf8',
+        });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    }
+    if (process.platform === 'darwin') {
+        const result = (0, child_process_1.spawnSync)('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'], {
+            encoding: 'utf8',
+        });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    }
+    const result = (0, child_process_1.spawnSync)('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'], {
+        encoding: 'utf8',
+    });
+    return result.status === 0 ? result.stdout.trim() || null : null;
+}
+function isCanonicalRowId(value) {
+    return typeof value === 'string' && session_service_1.FIRST_RUN_ROW_IDS.includes(value);
+}
+class FirstRunServer {
+    constructor(options) {
+        this.app = (0, express_1.default)();
+        this.sessionService = options.sessionService;
+        this.finishPromise = new Promise((resolve) => {
+            this.finishResolver = resolve;
+        });
+        this.app.use(express_1.default.json());
+        this.app.use('/api/first-run', (req, res, next) => {
+            if (req.method === 'GET') {
+                return next();
+            }
+            const requestToken = req.header('x-fraim-first-run-token');
+            if (requestToken !== this.sessionService.getRequestToken()) {
+                return res.status(403).json({ error: 'Invalid first-run session token.' });
+            }
+            return next();
+        });
+        this.app.use('/first-run', express_1.default.static(resolveFirstRunPublicDir()));
+        this.app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', service: 'fraim-first-run' });
+        });
+        this.registerRoutes();
+    }
+    async start(port) {
+        await new Promise((resolve, reject) => {
+            this.httpServer = this.app.listen(port, '127.0.0.1');
+            this.httpServer.once('listening', () => resolve());
+            this.httpServer.once('error', (error) => reject(error));
+        });
+    }
+    async waitForFinish() {
+        await this.finishPromise;
+    }
+    async stop() {
+        if (!this.httpServer) {
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            this.httpServer.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+        this.httpServer = undefined;
+    }
+    registerRoutes() {
+        this.app.get('/api/first-run/session', (_req, res) => {
+            res.json(this.sessionService.getSession());
+        });
+        this.app.post('/api/first-run/rows/:rowId/run', async (req, res) => {
+            const { rowId } = req.params;
+            if (!isCanonicalRowId(rowId)) {
+                return res.status(400).json({ error: `Unknown row id: ${rowId}` });
+            }
+            try {
+                const result = await this.sessionService.runRow(rowId, req.body || {});
+                return res.json(result);
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not run row.' });
+            }
+        });
+        this.app.post('/api/first-run/agent/change', (req, res) => {
+            try {
+                return res.json(this.sessionService.changeAgent(req.body || {}));
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not change agent.' });
+            }
+        });
+        this.app.post('/api/first-run/project-path/pick', (_req, res) => {
+            try {
+                const selectedPath = pickProjectPath();
+                if (!selectedPath) {
+                    return res.status(204).end();
+                }
+                return res.json({ path: selectedPath });
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open the folder picker.' });
+            }
+        });
+        this.app.post('/api/first-run/finish', (_req, res) => {
+            const result = this.sessionService.finish();
+            this.finishResolver?.();
+            return res.json(result);
+        });
+        // 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.
+        this.app.post('/api/first-run/open-hub', async (_req, res) => {
+            try {
+                return res.json(await this.sessionService.openHub());
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open Hub.' });
+            }
+        });
+    }
+}
+exports.FirstRunServer = FirstRunServer;