fraim-framework 2.0.153 → 2.0.159

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -11,14 +11,37 @@ exports.buildLearningContextSection = buildLearningContextSection;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-const LEARNINGS_REL = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/learnings').replace(/\/$/, '');
+const REPO_LEARNINGS_REL = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/learnings').replace(/\/$/, '');
 const DEFAULT_THRESHOLD = 3.0;
 const AGING_HORIZON_DAYS = 7;
 const MAX_ENTRIES_SCANNED = 200;
 const BACKLOG_MIN = 5;
 const OLDEST_AGE_DAYS_TRIGGER = 3;
-function getLearningsBase(workspaceRoot) {
-    return (0, path_1.join)(workspaceRoot, LEARNINGS_REL);
+function getLearningRoots(workspaceRoot) {
+    return {
+        globalPersonalBase: (0, project_fraim_paths_1.getConfiguredPortableLearningsDir)(workspaceRoot),
+        globalPersonalDisplayBase: (0, project_fraim_paths_1.getConfiguredPortableLearningsDisplayPath)(workspaceRoot),
+        repoLearningsBase: (0, project_fraim_paths_1.getWorkspaceLearningsDir)(workspaceRoot)
+    };
+}
+function resolvePersonalLearningFile(repoBase, globalBase, globalDisplayBase, fileName) {
+    const repoPath = (0, path_1.join)(repoBase, fileName);
+    if ((0, fs_1.existsSync)(repoPath)) {
+        return {
+            present: true,
+            path: repoPath,
+            displayPath: `${REPO_LEARNINGS_REL}/${fileName}`
+        };
+    }
+    const globalPath = (0, path_1.join)(globalBase, fileName);
+    if ((0, fs_1.existsSync)(globalPath)) {
+        return {
+            present: true,
+            path: globalPath,
+            displayPath: `${globalDisplayBase.replace(/\/$/, '')}/${fileName}`
+        };
+    }
+    return { present: false, path: globalPath, displayPath: `${globalDisplayBase.replace(/\/$/, '')}/${fileName}` };
 }
 function buildUserIdCandidates(userId) {
     const candidates = new Set();
@@ -40,7 +63,7 @@ function countMatchingFilesByPrefix(dirPath, matcher) {
         return 0;
     }
 }
-function collectAvailableUserPrefixes(workspaceRoot, learningsBase) {
+function collectAvailableUserPrefixes(workspaceRoot, personalRoots) {
     const prefixes = new Set();
     const collect = (dirPath, extractor) => {
         if (!(0, fs_1.existsSync)(dirPath))
@@ -56,13 +79,15 @@ function collectAvailableUserPrefixes(workspaceRoot, learningsBase) {
             // Ignore unreadable directories.
         }
     };
-    collect(learningsBase, (fileName) => {
-        if (!fileName.endsWith('.md') || fileName.startsWith('org-'))
-            return null;
-        const match = fileName.match(/^(.*?)-(preferences|manager-coaching|mistake-patterns)\.md$/);
-        return match ? match[1] : null;
-    });
-    collect((0, path_1.join)(learningsBase, 'raw'), (fileName) => {
+    for (const personalRoot of personalRoots) {
+        collect(personalRoot, (fileName) => {
+            if (!fileName.endsWith('.md') || fileName.startsWith('org-'))
+                return null;
+            const match = fileName.match(/^(.*?)-(preferences|manager-coaching|mistake-patterns|validated-patterns)\.md$/);
+            return match ? match[1] : null;
+        });
+    }
+    collect((0, path_1.join)(personalRoots[0], 'raw'), (fileName) => {
         const match = fileName.match(/^(.*?)-\d{4}-\d{2}-\d{2}-.*\.md$/);
         return match ? match[1] : null;
     });
@@ -72,16 +97,20 @@ function collectAvailableUserPrefixes(workspaceRoot, learningsBase) {
     });
     return prefixes;
 }
-function resolveLearningUserId(workspaceRoot, userId) {
-    const learningsBase = getLearningsBase(workspaceRoot);
+function resolveLearningUserId(workspaceRoot, userId, roots) {
     const candidates = buildUserIdCandidates(userId);
     let bestCandidate = candidates[0] || userId;
     let bestScore = -1;
     for (const candidate of candidates) {
-        const score = ((0, fs_1.existsSync)((0, path_1.join)(learningsBase, `${candidate}-preferences.md`)) ? 1 : 0) +
-            ((0, fs_1.existsSync)((0, path_1.join)(learningsBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
-            ((0, fs_1.existsSync)((0, path_1.join)(learningsBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
-            countMatchingFilesByPrefix((0, path_1.join)(learningsBase, 'raw'), (fileName) => fileName.startsWith(`${candidate}-`)) +
+        const score = ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.globalPersonalBase, `${candidate}-validated-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-preferences.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-manager-coaching.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-mistake-patterns.md`)) ? 1 : 0) +
+            ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, `${candidate}-validated-patterns.md`)) ? 1 : 0) +
+            countMatchingFilesByPrefix((0, path_1.join)(roots.repoLearningsBase, 'raw'), (fileName) => fileName.startsWith(`${candidate}-`)) +
             countMatchingFilesByPrefix((0, path_1.join)(workspaceRoot, 'docs', 'retrospectives'), (fileName) => fileName.startsWith(`${candidate}-`) && fileName.endsWith('.md'));
         if (score > bestScore) {
             bestCandidate = candidate;
@@ -90,7 +119,7 @@ function resolveLearningUserId(workspaceRoot, userId) {
     }
     if (bestScore > 0)
         return bestCandidate;
-    const availablePrefixes = collectAvailableUserPrefixes(workspaceRoot, learningsBase);
+    const availablePrefixes = collectAvailableUserPrefixes(workspaceRoot, [roots.repoLearningsBase, roots.globalPersonalBase]);
     if (availablePrefixes.size === 1) {
         return Array.from(availablePrefixes)[0];
     }
@@ -242,7 +271,7 @@ function isUnsynthesizedRetrospective(filePath) {
 }
 /** Oldest mtime-age in days across this user's L0 signals. 0 if none. */
 function computeOldestL0AgeDays(workspaceRoot, userId) {
-    const learningsBase = getLearningsBase(workspaceRoot);
+    const learningsBase = (0, project_fraim_paths_1.getWorkspaceLearningsDir)(workspaceRoot);
     const now = Date.now();
     let oldest = 0;
     const consider = (filePath) => {
@@ -287,31 +316,27 @@ function computeOldestL0AgeDays(workspaceRoot, userId) {
     return oldest;
 }
 function buildLearningContextSection(workspaceRoot, userId, forJob) {
-    const learningsBase = getLearningsBase(workspaceRoot);
-    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId);
+    const roots = getLearningRoots(workspaceRoot);
+    const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     const threshold = getScoreThreshold(workspaceRoot);
-    const l2MistakePath = (0, path_1.join)(learningsBase, 'org-mistake-patterns.md');
-    const l2PrefPath = (0, path_1.join)(learningsBase, 'org-preferences.md');
-    const l2CoachPath = (0, path_1.join)(learningsBase, 'org-manager-coaching.md');
-    const l2ValidatedPath = (0, path_1.join)(learningsBase, 'org-validated-patterns.md');
+    const l2MistakePath = (0, path_1.join)(roots.repoLearningsBase, 'org-mistake-patterns.md');
+    const l2PrefPath = (0, path_1.join)(roots.repoLearningsBase, 'org-preferences.md');
+    const l2CoachPath = (0, path_1.join)(roots.repoLearningsBase, 'org-manager-coaching.md');
+    const l2ValidatedPath = (0, path_1.join)(roots.repoLearningsBase, 'org-validated-patterns.md');
     const l2MistakePresent = (0, fs_1.existsSync)(l2MistakePath);
     const l2PrefPresent = (0, fs_1.existsSync)(l2PrefPath);
     const l2CoachPresent = (0, fs_1.existsSync)(l2CoachPath);
     const l2ValidatedPresent = (0, fs_1.existsSync)(l2ValidatedPath);
     const l2MistakeStats = l2MistakePresent ? scanMistakePatternFile(l2MistakePath, threshold, 'mistake-patterns') : null;
     const l2ValidatedStats = l2ValidatedPresent ? scanMistakePatternFile(l2ValidatedPath, threshold, 'validated-patterns') : null;
-    const l1MistakePath = (0, path_1.join)(learningsBase, `${resolvedUserId}-mistake-patterns.md`);
-    const l1PrefPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-preferences.md`);
-    const l1CoachPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-manager-coaching.md`);
-    const l1ValidatedPath = (0, path_1.join)(learningsBase, `${resolvedUserId}-validated-patterns.md`);
-    const l1MistakePresent = (0, fs_1.existsSync)(l1MistakePath);
-    const l1PrefPresent = (0, fs_1.existsSync)(l1PrefPath);
-    const l1CoachPresent = (0, fs_1.existsSync)(l1CoachPath);
-    const l1ValidatedPresent = (0, fs_1.existsSync)(l1ValidatedPath);
-    const l1MistakeStats = l1MistakePresent ? scanMistakePatternFile(l1MistakePath, threshold, 'mistake-patterns') : null;
-    const l1ValidatedStats = l1ValidatedPresent ? scanMistakePatternFile(l1ValidatedPath, threshold, 'validated-patterns') : null;
+    const l1Mistake = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-mistake-patterns.md`);
+    const l1Pref = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-preferences.md`);
+    const l1Coach = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-manager-coaching.md`);
+    const l1Validated = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-validated-patterns.md`);
+    const l1MistakeStats = l1Mistake.present ? scanMistakePatternFile(l1Mistake.path, threshold, 'mistake-patterns') : null;
+    const l1ValidatedStats = l1Validated.present ? scanMistakePatternFile(l1Validated.path, threshold, 'validated-patterns') : null;
     let l0CoachingCount = 0;
-    const rawPath = (0, path_1.join)(learningsBase, 'raw');
+    const rawPath = (0, path_1.join)(roots.repoLearningsBase, 'raw');
     if ((0, fs_1.existsSync)(rawPath)) {
         try {
             l0CoachingCount = (0, fs_1.readdirSync)(rawPath).filter(f => f.startsWith(`${resolvedUserId}-`)).length;
@@ -333,7 +358,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
         }
     }
     const hasL2 = l2MistakePresent || l2PrefPresent || l2CoachPresent || l2ValidatedPresent;
-    const hasL1 = l1MistakePresent || l1PrefPresent || l1CoachPresent || l1ValidatedPresent;
+    const hasL1 = l1Mistake.present || l1Pref.present || l1Coach.present || l1Validated.present;
     const hasContent = hasL2 || hasL1 || l0CoachingCount > 0 || l0RetroCount > 0;
     if (!hasContent)
         return '';
@@ -343,13 +368,13 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     if (hasL2) {
         section += '### L2 - Org patterns\n';
         if (l2MistakePresent)
-            section += `\`${LEARNINGS_REL}/org-mistake-patterns.md\`  (entries above score threshold)\n`;
+            section += `\`${REPO_LEARNINGS_REL}/org-mistake-patterns.md\`  (entries above score threshold)\n`;
         if (l2PrefPresent)
-            section += `\`${LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
+            section += `\`${REPO_LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
         if (l2CoachPresent)
-            section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (manager-facing; all entries)\n`;
+            section += `\`${REPO_LEARNINGS_REL}/org-manager-coaching.md\`  (manager-facing; all entries)\n`;
         if (l2ValidatedPresent)
-            section += `\`${LEARNINGS_REL}/org-validated-patterns.md\`  (entries above score threshold)\n`;
+            section += `\`${REPO_LEARNINGS_REL}/org-validated-patterns.md\`  (entries above score threshold)\n`;
         const l2DormantTotal = (l2MistakeStats?.dormant || 0) + (l2ValidatedStats?.dormant || 0);
         if (l2DormantTotal > 0) {
             section += `Dormant: ${l2DormantTotal} org pattern${l2DormantTotal !== 1 ? 's' : ''} below threshold\n`;
@@ -358,14 +383,14 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     }
     if (hasL1) {
         section += '### L1 - Your patterns\n';
-        if (l1PrefPresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-preferences.md\`  (all entries)\n`;
-        if (l1CoachPresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (manager-facing; all entries)\n`;
-        if (l1MistakePresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-mistake-patterns.md\`  (entries above score threshold)\n`;
-        if (l1ValidatedPresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-validated-patterns.md\`  (entries above score threshold)\n`;
+        if (l1Pref.present)
+            section += `\`${l1Pref.displayPath}\`  (all entries)\n`;
+        if (l1Coach.present)
+            section += `\`${l1Coach.displayPath}\`  (manager-facing; all entries)\n`;
+        if (l1Mistake.present)
+            section += `\`${l1Mistake.displayPath}\`  (entries above score threshold)\n`;
+        if (l1Validated.present)
+            section += `\`${l1Validated.displayPath}\`  (entries above score threshold)\n`;
         const l1DormantTotal = (l1MistakeStats?.dormant || 0) + (l1ValidatedStats?.dormant || 0);
         if (l1DormantTotal > 0) {
             section += `Dormant: ${l1DormantTotal} personal pattern${l1DormantTotal !== 1 ? 's' : ''} below threshold\n`;
@@ -375,7 +400,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     if (l0CoachingCount > 0 || l0RetroCount > 0) {
         section += '### L0 - Your unprocessed signals\n';
         if (l0CoachingCount > 0) {
-            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
+            section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${REPO_LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
         }
         if (l0RetroCount > 0) {
             section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with unsynthesized or missing \`synthesized\` frontmatter\n`;
@@ -389,7 +414,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     if (forJob) {
         if (hasL2 || hasL1) {
             section += 'Use the relevant patterns and preferences in this job.\n';
-            if (l1CoachPresent || l2CoachPresent) {
+            if (l1Coach.present || l2CoachPresent) {
                 section += 'Treat manager-coaching as feedback for how the manager should continue or improve managing AI, not as agent instruction.\n';
             }
         }
@@ -401,7 +426,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     }
     else {
         section += 'Use this synthesized learning context throughout the session.\n';
-        if (l1CoachPresent || l2CoachPresent) {
+        if (l1Coach.present || l2CoachPresent) {
             section += 'Manager-coaching entries are manager-facing feedback, not instructions for the AI to follow.\n';
         }
         if (backlogTriggered) {

package/dist/src/local-mcp-server/stdio-server.js

@@ -14,6 +14,39 @@
  *    (PR or Conversation from ~/.fraim/config.json). Delivery phases live
  *    server-side in the workflow; the proxy just fills in mode-specific content.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -380,6 +413,8 @@ class FraimLocalMCPServer {
         this.otlpServer = null;
         this.isShutdown = false;
         this.mentoringResponseCache = null;
+        this.connectSyncInFlight = null;
+        this.latestConnectSyncWarning = null;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -554,6 +589,125 @@ class FraimLocalMCPServer {
             }
         }
     }
+    getConnectSyncMaxAgeMs() {
+        const raw = process.env.FRAIM_SYNC_ON_CONNECT_MAX_AGE_MS;
+        if (!raw)
+            return FraimLocalMCPServer.DEFAULT_CONNECT_SYNC_MAX_AGE_MS;
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed) || parsed < 0) {
+            return FraimLocalMCPServer.DEFAULT_CONNECT_SYNC_MAX_AGE_MS;
+        }
+        return Math.floor(parsed);
+    }
+    shouldUseLocalSyncTarget() {
+        if (process.env.FRAIM_LOCAL_SYNC === '1') {
+            return true;
+        }
+        try {
+            const parsed = new URL(this.remoteUrl);
+            return parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '::1';
+        }
+        catch {
+            return false;
+        }
+    }
+    getLocalCatalogMetadataPath(projectRoot) {
+        return (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot), FraimLocalMCPServer.CONNECT_SYNC_METADATA_PATH);
+    }
+    readLocalCatalogMetadata(projectRoot) {
+        const metadataPath = this.getLocalCatalogMetadataPath(projectRoot);
+        if (!(0, fs_1.existsSync)(metadataPath)) {
+            return null;
+        }
+        try {
+            return JSON.parse((0, fs_1.readFileSync)(metadataPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    writeLocalCatalogMetadata(projectRoot) {
+        const metadataPath = this.getLocalCatalogMetadataPath(projectRoot);
+        const metadata = {
+            localVersion: this.localVersion,
+            mode: this.shouldUseLocalSyncTarget() ? 'local' : 'remote',
+            remoteUrl: this.remoteUrl,
+            syncedAt: new Date().toISOString()
+        };
+        (0, fs_1.writeFileSync)(metadataPath, JSON.stringify(metadata, null, 2), 'utf8');
+    }
+    getLocalCatalogSyncReason(projectRoot) {
+        const catalogRoots = [
+            (0, path_1.join)(projectRoot, 'fraim', 'ai-employee', 'jobs'),
+            (0, path_1.join)(projectRoot, 'fraim', 'ai-manager', 'jobs')
+        ];
+        if (catalogRoots.some((catalogRoot) => !(0, fs_1.existsSync)(catalogRoot))) {
+            return 'local job catalog is missing';
+        }
+        const metadata = this.readLocalCatalogMetadata(projectRoot);
+        if (!metadata) {
+            return 'local catalog has no freshness metadata';
+        }
+        if (metadata.localVersion !== this.localVersion) {
+            return `local catalog was synced by FRAIM ${metadata.localVersion}`;
+        }
+        const syncedAtMs = Date.parse(metadata.syncedAt);
+        if (!Number.isFinite(syncedAtMs)) {
+            return 'local catalog has invalid freshness metadata';
+        }
+        const maxAgeMs = this.getConnectSyncMaxAgeMs();
+        if (Date.now() - syncedAtMs > maxAgeMs) {
+            return `local catalog is older than ${maxAgeMs}ms`;
+        }
+        return null;
+    }
+    async performLocalCatalogSync(projectRoot) {
+        const { runSync } = await Promise.resolve().then(() => __importStar(require('../cli/commands/sync')));
+        await runSync({
+            projectRoot,
+            skipUpdates: true,
+            local: this.shouldUseLocalSyncTarget(),
+            failHard: 'throw'
+        });
+        this.writeLocalCatalogMetadata(projectRoot);
+    }
+    async ensureFreshLocalCatalogOnConnect(requestId) {
+        if (process.env.FRAIM_DISABLE_SYNC_ON_CONNECT === '1') {
+            this.latestConnectSyncWarning = null;
+            return;
+        }
+        if (this.connectSyncInFlight) {
+            await this.connectSyncInFlight;
+            return;
+        }
+        this.connectSyncInFlight = (async () => {
+            const projectRoot = this.findProjectRoot();
+            this.latestConnectSyncWarning = null;
+            if (!projectRoot || !(0, project_fraim_paths_1.workspaceFraimExists)(projectRoot)) {
+                return;
+            }
+            const reason = this.getLocalCatalogSyncReason(projectRoot);
+            if (!reason) {
+                return;
+            }
+            this.log(`[req:${requestId}] Refreshing local FRAIM catalog before fraim_connect because ${reason}`);
+            try {
+                await this.performLocalCatalogSync(projectRoot);
+                this.log(`[req:${requestId}] Local FRAIM catalog refresh complete`);
+            }
+            catch (error) {
+                const message = error?.message || String(error);
+                this.latestConnectSyncWarning = `Local FRAIM catalog refresh failed: ${message}. Discovery will fall back to remote FRAIM tools until sync succeeds.`;
+                this.logError(`[req:${requestId}] ${this.latestConnectSyncWarning}`);
+            }
+        })();
+        try {
+            await this.connectSyncInFlight;
+        }
+        finally {
+            this.connectSyncInFlight = null;
+        }
+    }
     /**
      * Automatically detect machine information
      */
@@ -1025,6 +1179,7 @@ class FraimLocalMCPServer {
         if (toolName === 'fraim_connect' && !finalizedResponse.error) {
             const text = finalizedResponse.result?.content?.[0]?.text;
             if (typeof text === 'string') {
+                let responseText = text;
                 const emailMatch = text.match(/Your identity for this session: \*\*([^*]+)\*\*/);
                 if (emailMatch) {
                     const userEmail = emailMatch[1].trim();
@@ -1034,10 +1189,14 @@ class FraimLocalMCPServer {
                     const workspaceRoot = this.findProjectRoot() || process.cwd();
                     const learningSection = (0, learning_context_builder_js_1.buildLearningContextSection)(workspaceRoot, userEmail, false);
                     if (learningSection) {
-                        finalizedResponse.result.content[0].text = text + learningSection;
+                        responseText += learningSection;
                         this.log(`[req:${requestId}] Injected learning context for ${userEmail} from ${workspaceRoot}`);
                     }
                 }
+                if (this.latestConnectSyncWarning) {
+                    responseText += `\n\n## Local Catalog\n${this.latestConnectSyncWarning}`;
+                }
+                finalizedResponse.result.content[0].text = responseText;
             }
         }
         // 4. After get_fraim_job succeeds, inject learning context with job-focus frame.
@@ -1461,6 +1620,7 @@ class FraimLocalMCPServer {
             // Special handling for fraim_connect - automatically inject machine and repo info
             if (request.method === 'tools/call' && request.params?.name === 'fraim_connect') {
                 this.log(`[req:${requestId}] Intercepting fraim_connect to inject machine/repo info`);
+                await this.ensureFreshLocalCatalogOnConnect(requestId);
                 const args = request.params.arguments || {};
                 // REQUIRED: Auto-detect and inject machine info
                 const detectedMachine = this.detectMachineInfo();
@@ -1755,9 +1915,7 @@ class FraimLocalMCPServer {
                             this.log(`✅ Local override found for get_fraim_job: ${name}`);
                             let responseText = overview.overview;
                             if (!overview.isSimple) {
-                                const phaseAuthority = await mentor.getPhaseAuthorityContent();
-                                if (phaseAuthority)
-                                    responseText = `${phaseAuthority}\n\n---\n\n${responseText}`;
+                                responseText = `${mentor.getCompactPhaseAuthority()}\n\n${responseText}`;
                                 responseText += `\n\n---\n\n**This job has phases.** Use \`seekMentoring\` to get phase-specific instructions.`;
                             }
                             // Inject local learning context for job requests (RFC 177).
@@ -1778,25 +1936,64 @@ class FraimLocalMCPServer {
                     }
                 }
             }
-            // DISCOVERY AGGREGATION: Merge local and remote jobs
             if (toolName === 'list_fraim_jobs') {
                 const response = await this._doProxyToRemote(request, requestId);
                 if (!response.error && response.result?.content?.[0]?.text) {
                     try {
-                        const resolver = this.getRegistryResolver(requestSessionId);
-                        const localItems = await resolver.listItems('job');
-                        if (localItems.length > 0) {
-                            this.log(`📦 Aggregating ${localItems.length} local jobs into remote response`);
+                        const projectRoot = this.findProjectRoot();
+                        const uniqueLocalItems = new Map();
+                        if (projectRoot) {
+                            const personalizedJobsDir = (0, path_1.join)(projectRoot, 'fraim', 'personalized-employee', 'jobs');
+                            if ((0, fs_1.existsSync)(personalizedJobsDir)) {
+                                const collectLocalJobPaths = (dir, currentRel = '') => {
+                                    const results = [];
+                                    const entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+                                    for (const entry of entries) {
+                                        const rel = currentRel ? `${currentRel}/${entry.name}` : entry.name;
+                                        const full = (0, path_1.join)(dir, entry.name);
+                                        if (entry.isDirectory()) {
+                                            results.push(...collectLocalJobPaths(full, rel));
+                                        }
+                                        else if (entry.isFile() && entry.name.endsWith('.md')) {
+                                            results.push(rel);
+                                        }
+                                    }
+                                    return results;
+                                };
+                                const localJobPaths = collectLocalJobPaths(personalizedJobsDir);
+                                for (const relPath of localJobPaths) {
+                                    const normalizedName = relPath.split('/').pop()?.replace(/\.md$/, '').trim() || '';
+                                    if (!normalizedName || uniqueLocalItems.has(normalizedName)) {
+                                        continue;
+                                    }
+                                    const category = relPath.includes('/')
+                                        ? relPath.split('/').slice(0, -1).join('/') || 'personalized-employee'
+                                        : 'personalized-employee';
+                                    uniqueLocalItems.set(normalizedName, {
+                                        name: normalizedName,
+                                        path: relPath,
+                                        category
+                                    });
+                                }
+                            }
+                        }
+                        if (uniqueLocalItems.size > 0) {
+                            const sortedLocalItems = Array.from(uniqueLocalItems.values())
+                                .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
                             let combinedText = response.result.content[0].text;
-                            combinedText += `\n\n## Local & Personalized Jobs (${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)()})\n\n`;
-                            for (const item of localItems) {
-                                combinedText += `- **${item.name}**: ${item.description || '(No description available)'}\n`;
+                            combinedText += `\n\n## Local Personalized Jobs (${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/jobs/')})\n`;
+                            combinedText += 'These local jobs override catalog jobs of the same name when you call `get_fraim_job`.\n';
+                            for (const item of sortedLocalItems) {
+                                const categorySuffix = item.category && item.category !== 'personalized-employee'
+                                    ? ` (${item.category})`
+                                    : '';
+                                combinedText += `- **${item.name}**${categorySuffix}\n`;
                             }
                             response.result.content[0].text = combinedText;
                         }
                     }
                     catch (error) {
-                        this.log(`⚠️ Discovery aggregation failed: ${error.message}`);
+                        this.log(`⚠️ Local personalized job listing failed: ${error.message}`);
                     }
                 }
                 return response;
@@ -2128,6 +2325,8 @@ FraimLocalMCPServer.AGENT_RESOLUTION_NOTICE = [
 ].join('\n');
 FraimLocalMCPServer.FALLBACK_ALERT_MARKER = 'PROXY_FALLBACK_ALERT';
 FraimLocalMCPServer.SESSION_HEADER = 'x-fraim-session-id';
+FraimLocalMCPServer.CONNECT_SYNC_METADATA_PATH = '.sync-metadata.json';
+FraimLocalMCPServer.DEFAULT_CONNECT_SYNC_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 // Start server if run directly
 if (require.main === module) {
     const server = new FraimLocalMCPServer();

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.153",
+  "version": "2.0.159",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
-  "bin": "./bin/fraim.js",
+  "bin": {
+    "fraim-framework": "bin/fraim.js"
+  },
   "scripts": {
     "dev": "tsx --watch src/fraim-mcp-server.ts > server.log 2>&1",
     "dev:prod": "npm run build && node dist/src/fraim-mcp-server.js > server.log 2>&1",
-    "build": "tsx scripts/build-fraim-config-schema-template.ts && npm run typecheck:scripts && tsc && npm run build:stubs && npm run build:fraim-brain && node scripts/copy-registry.js && npm run validate:registry && npm run validate:fraim-pro-assets && tsx scripts/validate-purity.ts",
+    "build": "tsx scripts/build-fraim-config-schema-template.ts && npm run typecheck:scripts && tsc && npm run build:stubs && npm run build:fraim-brain && node scripts/copy-registry.js && npm run validate:registry && npm run validate:fraim-pro-assets && npm run validate:employee-catalog && tsx scripts/validate-purity.ts",
     "build:stubs": "tsx scripts/build-stub-registry.ts",
     "build:fraim-brain": "node scripts/generate-fraim-brain.js",
     "test-all": "npm run test && npm run test:isolated && npm run test:ui",
@@ -21,6 +23,8 @@
     "test:ui": "playwright test --workers=1",
     "test:ui:headed": "playwright test --headed --workers=1",
     "hub:desktop": "npm run build && electron dist/src/ai-hub/desktop-main.js",
+    "hub:dev": "tsx scripts/start-hub-dev.ts",
+    "firstrun:dev": "tsx scripts/start-firstrun-dev.ts",
     "start:fraim": "tsx src/fraim-mcp-server.ts",
     "dev:fraim": "tsx --watch src/fraim-mcp-server.ts",
     "serve:website": "node fraim-pro/serve.js",
@@ -45,6 +49,7 @@
     "validate:registry-references": "tsx scripts/validate-registry-references.ts",
     "validate:brain-mapping": "tsx scripts/validate-brain-mapping.ts",
     "validate:fraim-pro-assets": "tsx scripts/validate-fraim-pro-assets.ts",
+    "validate:employee-catalog": "tsx scripts/validate-employee-catalog.ts",
     "validate:jobs": "tsx scripts/validate-jobs.ts",
     "validate:platform-agnostic": "tsx scripts/validate-platform-agnostic.ts",
     "validate:skills": "tsx scripts/validate-skills.ts",