fraim-framework 2.0.126 → 2.0.127

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

@@ -12,6 +12,7 @@ const net_1 = __importDefault(require("net"));
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
 const catalog_1 = require("./catalog");
+const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
 const preferences_1 = require("./preferences");
 class AiHubRunRegistry {
@@ -25,6 +26,9 @@ class AiHubRunRegistry {
     get(runId) {
         return this.runs.get(runId);
     }
+    all() {
+        return [...this.runs.values()];
+    }
     create(run, child) {
         this.runs.set(run.id, run);
         this.children.set(run.id, child);
@@ -35,14 +39,190 @@ class AiHubRunRegistry {
         if (!run) {
             throw new Error(`Run ${runId} not found`);
         }
+        const priorStatus = run.status;
         updater(run);
-        run.updatedAt = new Date().toISOString();
+        const now = new Date().toISOString();
+        // Issue #347: when status flipped, accumulate the previous status's
+        // duration into the appropriate working/waiting bucket. lastStatusChangeAt
+        // is the wall-clock timestamp of the most recent flip; on the first
+        // call it falls back to createdAt.
+        if (run.status !== priorStatus) {
+            const lastAt = run.lastStatusChangeAt || run.createdAt;
+            const elapsedMs = Date.parse(now) - Date.parse(lastAt);
+            if (Number.isFinite(elapsedMs) && elapsedMs > 0) {
+                run.totals = run.totals || emptyTotals();
+                if (priorStatus === 'running') {
+                    run.totals.workingDurationMs += elapsedMs;
+                }
+                else {
+                    run.totals.waitingDurationMs += elapsedMs;
+                }
+            }
+            run.lastStatusChangeAt = now;
+        }
+        run.updatedAt = now;
         return run;
     }
     dispose(runId) {
         this.children.delete(runId);
     }
 }
+function emptyTotals() {
+    return {
+        totalDurationMs: 0,
+        workingDurationMs: 0,
+        waitingDurationMs: 0,
+        tokenTotals: {
+            inputTokens: null,
+            outputTokens: null,
+            costUsd: null,
+            // Issue #347: Hub server cannot read tokenSnapshot from the local
+            // proxy in-process. Cross-process attribution is a follow-up;
+            // until then, every Hub-driven run reports unavailable. The Hub UI
+            // renders "—" per spec R4.6.
+            coverage: 'unavailable',
+        },
+    };
+}
+// Issue #347 — apply per-turn usage from the host stream into the
+// run's tokenTotals. Idempotent on the same turn (we replace, not add)
+// because Codex's `turn.completed.usage` is cumulative, not delta.
+// When the host doesn't emit costUsd directly (Codex), we compute it
+// from the captured agent identity via the price table.
+function applyUsageSignal(run, usage) {
+    run.totals = run.totals || emptyTotals();
+    const tt = run.totals.tokenTotals;
+    // Total input tokens (for the user-facing display) = non-cached + cached.
+    // Cumulative across the whole run on both hosts; take max to guard
+    // against any out-of-order delivery.
+    const totalInput = usage.nonCachedInputTokens + usage.cachedInputTokens;
+    tt.inputTokens = Math.max(tt.inputTokens || 0, totalInput);
+    tt.outputTokens = Math.max(tt.outputTokens || 0, usage.outputTokens);
+    // Cost: prefer the host's own number (Claude). For hosts that don't
+    // emit it (Codex), compute from the captured agent identity + price
+    // table. If neither source applies, leave costUsd null and coverage
+    // stays 'partial'.
+    let computedCost = null;
+    if (typeof usage.costUsd === 'number') {
+        computedCost = usage.costUsd;
+    }
+    else if (run.agentName && run.agentModel) {
+        const price = (0, agent_token_prices_1.lookupPrice)(run.agentName.toLowerCase(), run.agentModel.toLowerCase());
+        if (price) {
+            computedCost =
+                (usage.nonCachedInputTokens / 1_000_000) * price.inputPerMTok +
+                    (usage.cachedInputTokens / 1_000_000) * price.cacheReadPerMTok +
+                    (usage.cacheCreationTokens / 1_000_000) * price.cacheCreationPerMTok +
+                    (usage.outputTokens / 1_000_000) * price.outputPerMTok;
+        }
+    }
+    if (computedCost !== null) {
+        tt.costUsd = Math.max(tt.costUsd || 0, computedCost);
+        tt.coverage = 'complete';
+    }
+    else if (tt.coverage !== 'complete') {
+        tt.coverage = 'partial';
+    }
+}
+// Issue #347 — capture agent identity from the host stream's fraim_connect
+// call. Used downstream by applyUsageSignal to compute cost via the price
+// table when the host does not emit costUsd directly.
+function applyAgentIdentitySignal(run, identity) {
+    run.agentName = identity.agentName;
+    run.agentModel = identity.agentModel;
+}
+// Apply a parsed seekMentoring tool-use signal from the host stream to
+// the run state. Returns the updated currentPhase.
+function applySeekMentoringSignal(run, signal) {
+    // Issue #347: filter cross-job pollution. The agent may call
+    // seekMentoring for jobs OTHER than the one this run is tracking
+    // (e.g., consulting `organizational-learning-synthesis` mid-run).
+    // Only apply signals whose jobId/jobName matches this run's jobId.
+    // Match against either field because the agent passes both and they
+    // typically agree, but defenses are cheap.
+    const targetJobId = run.jobId;
+    const callJobId = signal.jobId || signal.jobName;
+    if (callJobId && targetJobId && callJobId !== targetJobId)
+        return;
+    // Discriminant signals are routing hints only — they don't move the
+    // tracker, but they do change which phase id will be considered
+    // reachable next time stages are derived. Persist on the run.
+    if (signal.phaseId === '__discriminant__') {
+        if (signal.discriminant)
+            run.runDiscriminant = signal.discriminant;
+        return;
+    }
+    if (signal.discriminant)
+        run.runDiscriminant = signal.discriminant;
+    // The seekMentoring workflow uses `currentPhase: "starting"` as a
+    // sentinel for the very first call ("give me phase 1 instructions").
+    // It is not an actual phase id — skip it so the tracker doesn't
+    // render an extra "starting" stage at the end of the path.
+    if (signal.phaseId === 'starting')
+        return;
+    run.phaseHistory = run.phaseHistory || [];
+    const existing = run.phaseHistory.find((entry) => entry.phaseId === signal.phaseId);
+    if (existing) {
+        existing.latestStatus = signal.phaseStatus;
+        if (signal.findingsText)
+            existing.latestText = signal.findingsText;
+    }
+    else {
+        const entry = {
+            phaseId: signal.phaseId,
+            enteredAt: new Date().toISOString(),
+            latestStatus: signal.phaseStatus,
+            latestText: signal.findingsText || null,
+        };
+        run.phaseHistory.push(entry);
+    }
+    run.currentPhase = signal.phaseId;
+}
+// Build the stage list for a run. Combines the FSM's reachable path with
+// any phases the run has actually visited (in case the run took an
+// onFailure back-edge into a phase the simple onSuccess walk wouldn't
+// surface). Each stage is marked done / current / upcoming based on
+// whether it precedes / matches / follows the current phase along the
+// rendered order.
+function deriveStages(run, projectPath) {
+    const declaredPath = (0, catalog_1.loadJobPhases)(run.jobId, projectPath, run.runDiscriminant || 'feature');
+    if (declaredPath.length === 0)
+        return [];
+    // Merge in any visited phase that's not on the declared path BUT is
+    // declared in the job's frontmatter (e.g., a phase reached via an
+    // onFailure back-edge that the simple onSuccess walk didn't surface).
+    // Skip the 'starting' sentinel, the __discriminant__ marker, and any
+    // phase id NOT in the frontmatter — that last filter prevents
+    // cross-job pollution from showing up on the tracker.
+    const allDeclared = (0, catalog_1.loadAllJobPhaseIds)(run.jobId, projectPath);
+    const visited = (run.phaseHistory || []).map((entry) => entry.phaseId);
+    const known = new Set(declaredPath.map((p) => p.id));
+    for (const visitedId of visited) {
+        if (visitedId === 'starting' || visitedId === '__discriminant__')
+            continue;
+        if (!allDeclared.has(visitedId))
+            continue;
+        if (!known.has(visitedId)) {
+            declaredPath.push({ id: visitedId, label: (0, catalog_1.labelForPhaseId)(visitedId, run.jobId, projectPath) });
+            known.add(visitedId);
+        }
+    }
+    const currentIndex = run.currentPhase
+        ? declaredPath.findIndex((p) => p.id === run.currentPhase)
+        : -1;
+    return declaredPath.map((phase, index) => {
+        let state;
+        if (currentIndex < 0)
+            state = 'upcoming';
+        else if (index < currentIndex)
+            state = 'done';
+        else if (index === currentIndex)
+            state = 'current';
+        else
+            state = 'upcoming';
+        return { phaseId: phase.id, label: phase.label, state };
+    });
+}
 function ensureDirectoryPath(projectPath) {
     const trimmed = (projectPath || '').trim();
     if (!trimmed) {
@@ -99,15 +279,20 @@ class AiHubServer {
         const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
         const jobs = (0, catalog_1.discoverEmployeeJobs)(normalizedProjectPath);
         const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath);
+        // Issue #347: enrich the activeRun the same way GET /runs/:id does
+        // so the bootstrap surface (used on first paint) carries stages and
+        // live totals — not just the raw run state.
+        const latest = this.runRegistry.listLatest();
+        const activeRun = latest ? this.enrichRunForResponse(latest) : undefined;
         return {
-            title: 'Visa AI Hub',
+            title: 'AI Hub',
             project,
             preferences,
-            categories: (0, catalog_1.getAiHubCategories)(),
+            categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath),
             jobs,
             managerTemplates,
             employees: this.hostRuntime.detectEmployees(),
-            activeRun: this.runRegistry.listLatest(),
+            activeRun,
         };
     }
     registerRoutes() {
@@ -148,16 +333,22 @@ class AiHubServer {
                 if (!employee?.available) {
                     throw new Error(`${employee?.label || 'Selected employee'} is not available on this machine.`);
                 }
+                const startTimestamp = new Date().toISOString();
                 const run = {
                     id: (0, crypto_1.randomUUID)(),
                     jobId,
                     hostId,
                     projectPath,
                     status: 'running',
-                    createdAt: new Date().toISOString(),
-                    updatedAt: new Date().toISOString(),
+                    createdAt: startTimestamp,
+                    updatedAt: startTimestamp,
                     messages: [(0, hosts_1.createHubMessage)('manager', message)],
                     events: [(0, hosts_1.createHubEvent)('system', `Starting ${hostId} in ${projectPath}`)],
+                    // Issue #347 — seed phase + totals state on creation.
+                    currentPhase: null,
+                    phaseHistory: [],
+                    totals: emptyTotals(),
+                    lastStatusChangeAt: startTimestamp,
                 };
                 this.runRegistry.create(run, {});
                 const child = this.hostRuntime.startRun(hostId, projectPath, message, {
@@ -169,6 +360,12 @@ class AiHubServer {
                                 current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
                             if (event.raw)
                                 current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.seekMentoring)
+                                applySeekMentoringSignal(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
                         });
                     },
                     onExit: (exitCode) => {
@@ -188,7 +385,7 @@ class AiHubServer {
                     employeeId: hostId,
                     recentJobIds: existingPreferences.recentJobIds,
                 }, jobId);
-                res.status(201).json(run);
+                res.status(201).json(this.enrichRunForResponse(run));
             }
             catch (error) {
                 res.status(400).json({ error: error instanceof Error ? error.message : 'Could not start run.' });
@@ -221,6 +418,12 @@ class AiHubServer {
                                 current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
                             if (event.raw)
                                 current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.seekMentoring)
+                                applySeekMentoringSignal(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
                         });
                     },
                     onExit: (exitCode) => {
@@ -233,7 +436,8 @@ class AiHubServer {
                     },
                 });
                 this.runRegistry.create(run, child);
-                res.json(this.runRegistry.get(run.id));
+                const refreshed = this.runRegistry.get(run.id);
+                res.json(refreshed ? this.enrichRunForResponse(refreshed) : refreshed);
             }
             catch (error) {
                 res.status(400).json({ error: error instanceof Error ? error.message : 'Could not continue run.' });
@@ -244,9 +448,51 @@ class AiHubServer {
             if (!run) {
                 return res.status(404).json({ error: 'Run not found.' });
             }
-            return res.json(run);
+            return res.json(this.enrichRunForResponse(run));
         });
     }
+    // Issue #347 — assemble the read-side projection of a run. Stages are
+    // derived from job frontmatter + visited phases; totalDurationMs ticks
+    // forward while the run is still running so the UI's totals line
+    // updates each poll without the server having to rewrite the run on
+    // every tick.
+    enrichRunForResponse(run) {
+        const stages = deriveStages(run, run.projectPath);
+        const now = Date.now();
+        const created = Date.parse(run.createdAt);
+        const updated = Date.parse(run.updatedAt);
+        const liveTotalMs = run.status === 'running'
+            ? Math.max(0, now - created)
+            : Math.max(0, updated - created);
+        const baseTotals = run.totals || emptyTotals();
+        // While the run is still in its current status (not yet flipped), the
+        // current bucket needs to include the in-flight delta since the last
+        // flip. Compute it here so the client sees a smoothly increasing
+        // working/waiting figure instead of frozen counters between flips.
+        const lastFlipMs = run.lastStatusChangeAt
+            ? Date.parse(run.lastStatusChangeAt)
+            : created;
+        const inflightMs = Math.max(0, now - lastFlipMs);
+        const liveTotals = {
+            totalDurationMs: liveTotalMs,
+            workingDurationMs: baseTotals.workingDurationMs + (run.status === 'running' ? inflightMs : 0),
+            waitingDurationMs: baseTotals.waitingDurationMs + (run.status !== 'running' ? inflightMs : 0),
+            tokenTotals: baseTotals.tokenTotals,
+        };
+        // Defensive cap: working + waiting should never exceed total. Trim
+        // the trailing bucket if rounding pushes us past.
+        const sum = liveTotals.workingDurationMs + liveTotals.waitingDurationMs;
+        if (sum > liveTotalMs) {
+            const overflow = sum - liveTotalMs;
+            if (run.status === 'running') {
+                liveTotals.workingDurationMs = Math.max(0, liveTotals.workingDurationMs - overflow);
+            }
+            else {
+                liveTotals.waitingDurationMs = Math.max(0, liveTotals.waitingDurationMs - overflow);
+            }
+        }
+        return { ...run, stages, totals: liveTotals };
+    }
 }
 exports.AiHubServer = AiHubServer;
 async function findAvailablePort(preferredPort) {

package/dist/src/cli/commands/add-ide.js

@@ -187,7 +187,7 @@ const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
         }
     }
     if (ide.configFormat === 'toml') {
-        // Handle TOML format (e.g., Codex, Zed)
+        // Handle TOML format (e.g., Codex)
         let existingTomlContent = '';
         if (fs_1.default.existsSync(configPath)) {
             existingTomlContent = fs_1.default.readFileSync(configPath, 'utf8');
@@ -270,6 +270,7 @@ const listSupportedIDEs = () => {
     console.log(chalk_1.default.yellow('💡 Use "fraim add-ide --ide <name>" to configure a specific IDE'));
     console.log(chalk_1.default.yellow('   Example: fraim add-ide --ide claude-code'));
     console.log(chalk_1.default.yellow('   Anthropic aliases: claude, claude-code, claude-desktop, claude-cowork'));
+    console.log(chalk_1.default.yellow('   Gemini aliases: gemini, gemini-cli, gemini cli'));
 };
 const promptForIDESelection = async (availableIDEs, tokens) => {
     console.log(chalk_1.default.green(`✅ Found ${availableIDEs.length} IDEs that can be configured:\n`));
@@ -357,7 +358,7 @@ const runAddIDE = async (options) => {
     const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
     if (detectedIDEs.length === 0) {
         console.log(chalk_1.default.yellow('⚠️ No supported IDEs detected on your system.'));
-        console.log(chalk_1.default.gray('Supported IDEs: Claude, Claude Code, 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💡 Install an IDE and run this command again.'));
         return;
     }
@@ -435,7 +436,7 @@ const runAddIDE = async (options) => {
 exports.runAddIDE = runAddIDE;
 exports.addIDECommand = new commander_1.Command('add-ide')
     .description('Add FRAIM configuration to additional IDEs')
-    .option('--ide <name>', 'Configure specific IDE (claude, claude-code, claude-desktop, claude-cowork, antigravity, kiro, cursor, vscode, codex, windsurf)')
+    .option('--ide <name>', 'Configure specific IDE (claude, claude-code, claude-desktop, claude-cowork, antigravity, gemini, gemini-cli, kiro, cursor, vscode, codex, windsurf)')
     .option('--all', 'Configure all detected IDEs')
     .option('--list', 'List all supported IDEs and their detection status')
     .action(exports.runAddIDE);

package/dist/src/cli/commands/first-run.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstRunCommand = exports.runFirstRun = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const child_process_1 = require("child_process");
+const server_1 = require("../../first-run/server");
+const session_service_1 = require("../../first-run/session-service");
+const server_2 = require("../../ai-hub/server");
+function openBrowser(url) {
+    try {
+        if (process.platform === 'win32') {
+            (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" "${url}"`], { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+        if (process.platform === 'darwin') {
+            (0, child_process_1.spawn)('open', [url], { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+        (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        // Best effort only.
+    }
+}
+const runFirstRun = async (options) => {
+    const key = options.key || process.env.FRAIM_API_KEY || process.env.FRAIM_SETUP_KEY || process.env.FRAIM_INSTALL_KEY;
+    if (!key) {
+        console.log(chalk_1.default.red('FRAIM key is required for first-run.'));
+        process.exit(1);
+    }
+    const sessionService = new session_service_1.FirstRunSessionService({
+        key,
+        headless: options.headless,
+        resume: options.resume,
+        projectRoot: options.projectRoot,
+    });
+    const server = new server_1.FirstRunServer({ sessionService });
+    const port = await (0, server_2.findAvailablePort)(43120);
+    const url = `http://127.0.0.1:${port}/first-run/`;
+    await server.start(port);
+    console.log(chalk_1.default.blue('Starting FRAIM first-run...'));
+    console.log(chalk_1.default.white(`First run available at ${url}`));
+    if (!options.headless) {
+        openBrowser(url);
+    }
+    await server.waitForFinish();
+    await server.stop();
+    console.log(chalk_1.default.green('FRAIM first-run completed.'));
+};
+exports.runFirstRun = runFirstRun;
+exports.firstRunCommand = new commander_1.Command('first-run')
+    .description('Run the guided first-run installer experience')
+    .option('--key <key>', 'FRAIM API key')
+    .option('--resume', 'Resume an interrupted first-run session')
+    .option('--headless', 'Do not attempt to open a browser automatically')
+    .option('--project-root <path>', 'Seed the first-run flow with an explicit project root')
+    .action(exports.runFirstRun);

package/dist/src/cli/commands/hub.js

@@ -63,7 +63,7 @@ function openBrowser(url) {
     child.unref();
 }
 exports.hubCommand = new commander_1.Command('hub')
-    .description('Start the Visa AI Hub local companion for running FRAIM jobs through Codex or Claude Code')
+    .description('Start the AI Hub local companion for running FRAIM jobs through Codex or Claude Code')
     .option('--port <port>', 'Preferred local port for the hub', (value) => Number(value), 43091)
     .option('--project-path <path>', 'Initial project path for job discovery', process.cwd())
     .option('--no-open', 'Do not open the hub after startup')
@@ -78,12 +78,12 @@ exports.hubCommand = new commander_1.Command('hub')
             const server = new server_1.AiHubServer({ projectPath });
             await server.start(port);
             const url = `http://127.0.0.1:${port}/ai-hub/`;
-            console.log(`Visa AI Hub running at ${url}`);
+            console.log(`AI Hub running at ${url}`);
             console.log(`Project path: ${projectPath}`);
             openBrowser(url);
             return;
         }
-        console.log('Visa AI Hub desktop shell launched.');
+        console.log('AI Hub desktop shell launched.');
         console.log(`Project path: ${projectPath}`);
         return;
     }
@@ -91,6 +91,6 @@ exports.hubCommand = new commander_1.Command('hub')
     const server = new server_1.AiHubServer({ projectPath });
     await server.start(port);
     const url = `http://127.0.0.1:${port}/ai-hub/`;
-    console.log(`Visa AI Hub running at ${url}`);
+    console.log(`AI Hub running at ${url}`);
     console.log(`Project path: ${projectPath}`);
 });

package/dist/src/cli/commands/init-project.js

@@ -158,7 +158,7 @@ const createGitHubLabels = (projectRoot) => {
         console.log(chalk_1.default.yellow(`Error reading labels.json: ${error.message}`));
     }
 };
-const runInitProject = async () => {
+const runInitProject = async (options = {}) => {
     console.log(chalk_1.default.blue('Initializing FRAIM project...'));
     const globalSetup = checkGlobalSetup();
     if (!globalSetup.exists) {
@@ -167,7 +167,7 @@ const runInitProject = async () => {
         console.log(chalk_1.default.cyan('   fraim setup'));
         process.exit(1);
     }
-    const projectRoot = process.cwd();
+    const projectRoot = options.projectRoot || process.cwd();
     const fraimDirDisplayPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)();
     const configDisplayPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json');
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
@@ -312,7 +312,7 @@ const runInitProject = async () => {
         result.repositoryDetected = true;
     }
     if (!process.env.FRAIM_SKIP_SYNC) {
-        await (0, sync_1.runSync)({});
+        await (0, sync_1.runSync)({ projectRoot });
         result.syncPerformed = true;
     }
     else {
@@ -338,4 +338,4 @@ const runInitProject = async () => {
 exports.runInitProject = runInitProject;
 exports.initProjectCommand = new commander_1.Command('init-project')
     .description('Initialize FRAIM in the current project (requires global setup)')
-    .action(exports.runInitProject);
+    .action(() => (0, exports.runInitProject)());

package/dist/src/cli/commands/setup.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupCommandInitialization = exports.setupCommand = exports.runSetup = void 0;
+exports.setupCommandInitialization = exports.setupCommand = exports.runSetup = exports.saveGlobalConfig = void 0;
 // Refactored setup.ts - Generic provider system with zero hardcoded provider knowledge
 const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
@@ -244,6 +244,7 @@ const saveGlobalConfig = (fraimKey, mode, tokens, configs) => {
     fs_1.default.writeFileSync(globalConfigPath, JSON.stringify(config, null, 2));
     console.log(chalk_1.default.green('✅ Global FRAIM configuration saved'));
 };
+exports.saveGlobalConfig = saveGlobalConfig;
 // Parse CLI options into generic format using provider registry from server
 // Tokens/config are optional - will prompt if not provided
 const parseLegacyOptions = async (options, fraimKey) => {
@@ -435,7 +436,7 @@ const runSetup = async (options) => {
                     }
                     // Save and configure MCP
                     console.log(chalk_1.default.blue('\n💾 Saving global configuration...'));
-                    saveGlobalConfig(fraimKey, mode, tokens, configs);
+                    (0, exports.saveGlobalConfig)(fraimKey, mode, tokens, configs);
                     console.log(chalk_1.default.blue('\n🔌 Configuring MCP servers...'));
                     const mcpTokens = {};
                     Object.entries(tokens).forEach(([id, token]) => {
@@ -572,7 +573,7 @@ const runSetup = async (options) => {
     }
     // Save global configuration
     console.log(chalk_1.default.blue('💾 Saving global configuration...'));
-    saveGlobalConfig(fraimKey, mode, tokens, configs);
+    (0, exports.saveGlobalConfig)(fraimKey, mode, tokens, configs);
     // Configure MCP servers
     if (!isUpdate) {
         // Initial setup - configure all detected IDEs

package/dist/src/cli/commands/sync.js

@@ -48,6 +48,24 @@ const git_utils_1 = require("../../core/utils/git-utils");
 const agent_adapters_1 = require("../utils/agent-adapters");
 const fraim_gitignore_1 = require("../utils/fraim-gitignore");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+function resolveExplicitLocalSyncUrl() {
+    const candidates = [
+        process.env.FRAIM_TEST_SERVER_URL,
+        process.env.FRAIM_REMOTE_URL,
+    ].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+        try {
+            const parsed = new URL(candidate);
+            if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+                return parsed.origin;
+            }
+        }
+        catch {
+            // Ignore malformed overrides and fall back to the derived loopback URL.
+        }
+    }
+    return undefined;
+}
 /**
  * Load API key from user-level config (~/.fraim/config.json)
  */
@@ -98,7 +116,7 @@ const runSync = async (options) => {
         }
         return;
     }
-    const projectRoot = process.cwd();
+    const projectRoot = options.projectRoot ? path_1.default.resolve(options.projectRoot) : process.cwd();
     const config = (0, config_loader_1.loadFraimConfig)();
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
     const refreshLocalIgnoreConfig = () => {
@@ -121,8 +139,9 @@ const runSync = async (options) => {
     if (options.local) {
         console.log(chalk_1.default.blue('Syncing FRAIM jobs from local server...'));
         const localPort = process.env.FRAIM_MCP_PORT ? parseInt(process.env.FRAIM_MCP_PORT) : (0, git_utils_1.getPort)();
+        const localUrl = resolveExplicitLocalSyncUrl() || `http://localhost:${localPort}`;
         const result = await syncFromRemote({
-            remoteUrl: `http://localhost:${localPort}`,
+            remoteUrl: localUrl,
             apiKey: 'local-dev',
             projectRoot,
             skipUpdates: true

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