fraim-framework 2.0.84 → 2.0.85

package/bin/fraim-mcp.js

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

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

@@ -159,7 +159,7 @@ const runInitProject = async () => {
         fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log(chalk_1.default.green('Created .fraim/config.json'));
     }
-    ['workflows'].forEach((dir) => {
+    ['workflows', 'ai-employee/jobs', 'ai-employee/skills', 'ai-manager/jobs', 'personalized-employee'].forEach((dir) => {
         const dirPath = path_1.default.join(fraimDir, dir);
         if (!fs_1.default.existsSync(dirPath)) {
             fs_1.default.mkdirSync(dirPath, { recursive: true });

package/dist/src/cli/commands/list-overridable.js

@@ -16,7 +16,8 @@ exports.listOverridableCommand = new commander_1.Command('list-overridable')
     const projectRoot = process.cwd();
     const fraimDir = path_1.default.join(projectRoot, '.fraim');
     const configPath = path_1.default.join(fraimDir, 'config.json');
-    const overridesDir = path_1.default.join(fraimDir, 'overrides');
+    const personalizedDir = path_1.default.join(fraimDir, 'personalized-employee');
+    const legacyOverridesDir = path_1.default.join(fraimDir, 'overrides');
     // Validate .fraim directory exists
     if (!fs_1.default.existsSync(fraimDir)) {
         console.log(chalk_1.default.red('❌ .fraim/ directory not found. Run "fraim setup" or "fraim init-project" first.'));
@@ -42,20 +43,23 @@ exports.listOverridableCommand = new commander_1.Command('list-overridable')
     console.log(chalk_1.default.blue('📋 Overridable FRAIM Registry Paths:\n'));
     // Get list of existing overrides
     const existingOverrides = new Set();
-    if (fs_1.default.existsSync(overridesDir)) {
-        const scanDir = (dir, base = '') => {
-            const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const relativePath = path_1.default.join(base, entry.name);
-                if (entry.isDirectory()) {
-                    scanDir(path_1.default.join(dir, entry.name), relativePath);
-                }
-                else {
-                    existingOverrides.add(relativePath.replace(/\\/g, '/'));
-                }
+    const scanDir = (dir, base = '') => {
+        const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = path_1.default.join(base, entry.name);
+            if (entry.isDirectory()) {
+                scanDir(path_1.default.join(dir, entry.name), relativePath);
             }
-        };
-        scanDir(overridesDir);
+            else {
+                existingOverrides.add(relativePath.replace(/\\/g, '/'));
+            }
+        }
+    };
+    if (fs_1.default.existsSync(personalizedDir)) {
+        scanDir(personalizedDir);
+    }
+    if (fs_1.default.existsSync(legacyOverridesDir)) {
+        scanDir(legacyOverridesDir);
     }
     // Handle --rules flag
     if (options.rules) {
@@ -197,6 +201,6 @@ exports.listOverridableCommand = new commander_1.Command('list-overridable')
         console.log(chalk_1.default.gray('  • Use "fraim override <path> --copy" to copy current content'));
         console.log(chalk_1.default.gray('  • Use --job-category <category> to see category-specific items'));
         console.log(chalk_1.default.gray('  • Use --rules to see all overridable rules'));
-        console.log(chalk_1.default.gray('  • Overrides are stored in .fraim/overrides/'));
+        console.log(chalk_1.default.gray('  • Overrides are stored in .fraim/personalized-employee/'));
     }
 });

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

@@ -39,8 +39,8 @@ exports.overrideCommand = new commander_1.Command('override')
         console.log(chalk_1.default.red('❌ Must specify either --inherit or --copy.'));
         process.exit(1);
     }
-    // Create overrides directory structure
-    const overridePath = path_1.default.join(fraimDir, 'overrides', registryPath);
+    // Create personalized override directory structure
+    const overridePath = path_1.default.join(fraimDir, 'personalized-employee', registryPath);
     const overrideDir = path_1.default.dirname(overridePath);
     if (!fs_1.default.existsSync(overrideDir)) {
         fs_1.default.mkdirSync(overrideDir, { recursive: true });
@@ -124,6 +124,13 @@ exports.overrideCommand = new commander_1.Command('override')
                 toolName = 'get_fraim_workflow';
                 toolArgs = { workflow: workflowName };
             }
+            else if (registryPath.startsWith('jobs/')) {
+                // e.g., "jobs/product-building/feature-specification.md" -> "feature-specification"
+                const parts = registryPath.split('/');
+                const jobName = parts[parts.length - 1].replace('.md', '');
+                toolName = 'get_fraim_job';
+                toolArgs = { job: jobName };
+            }
             else {
                 toolName = 'get_fraim_file';
                 toolArgs = { path: registryPath };

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

@@ -63,6 +63,24 @@ function loadUserApiKey() {
         return undefined;
     }
 }
+function updateVersionInConfig(fraimDir) {
+    const configPath = path_1.default.join(fraimDir, 'config.json');
+    if (!fs_1.default.existsSync(configPath)) {
+        return;
+    }
+    try {
+        const currentConfig = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        const newVersion = (0, version_utils_1.getFraimVersion)();
+        if (currentConfig.version !== newVersion) {
+            currentConfig.version = newVersion;
+            fs_1.default.writeFileSync(configPath, JSON.stringify(currentConfig, null, 2));
+            console.log(chalk_1.default.green(`✅ Updated FRAIM version to ${newVersion} in config.`));
+        }
+    }
+    catch (e) {
+        console.warn(chalk_1.default.yellow('⚠️ Could not update version in config.json.'));
+    }
+}
 const runSync = async (options) => {
     const projectRoot = process.cwd();
     const config = (0, config_loader_1.loadFraimConfig)();
@@ -88,7 +106,8 @@ const runSync = async (options) => {
             skipUpdates: true
         });
         if (result.success) {
-            console.log(chalk_1.default.green(`✅ Successfully synced ${result.workflowsSynced} workflows, ${result.scriptsSynced} scripts, ${result.coachingSynced} coaching files, and ${result.docsSynced} docs from local server`));
+            console.log(chalk_1.default.green(`✅ Successfully synced ${result.workflowsSynced} workflows, ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
+            updateVersionInConfig(fraimDir);
             return;
         }
         console.error(chalk_1.default.red(`❌ Local sync failed: ${result.error}`));
@@ -96,12 +115,18 @@ const runSync = async (options) => {
         process.exit(1);
     }
     // Path 2: Remote sync with API key
-    const apiKey = loadUserApiKey() || config.apiKey || process.env.FRAIM_API_KEY;
+    let apiKey = loadUserApiKey() || config.apiKey || process.env.FRAIM_API_KEY;
     if (!apiKey) {
-        console.error(chalk_1.default.red('❌ No API key configured. Cannot sync.'));
-        console.error(chalk_1.default.yellow('💡 Set FRAIM_API_KEY in your environment, or add apiKey to ~/.fraim/config.json or .fraim/config.json'));
-        console.error(chalk_1.default.yellow('💡 Or use --local to sync from a locally running FRAIM server.'));
-        process.exit(1);
+        if (process.env.TEST_MODE === 'true') {
+            console.log(chalk_1.default.yellow('⚠️ TEST_MODE: No API key configured. Using test placeholder key.'));
+            apiKey = 'test-mode-key';
+        }
+        else {
+            console.error(chalk_1.default.red('❌ No API key configured. Cannot sync.'));
+            console.error(chalk_1.default.yellow('💡 Set FRAIM_API_KEY in your environment, or add apiKey to ~/.fraim/config.json or .fraim/config.json'));
+            console.error(chalk_1.default.yellow('💡 Or use --local to sync from a locally running FRAIM server.'));
+            process.exit(1);
+        }
     }
     console.log(chalk_1.default.blue('🔄 Syncing FRAIM workflows from remote server...'));
     const result = await syncFromRemote({
@@ -115,27 +140,13 @@ const runSync = async (options) => {
         console.error(chalk_1.default.yellow('💡 Check your API key and network connection.'));
         if (process.env.TEST_MODE === 'true') {
             console.log(chalk_1.default.yellow('⚠️ TEST_MODE: Continuing without remote sync (server may be unavailable).'));
+            updateVersionInConfig(fraimDir);
             return;
         }
         process.exit(1);
     }
-    console.log(chalk_1.default.green(`✅ Successfully synced ${result.workflowsSynced} workflows, ${result.scriptsSynced} scripts, ${result.coachingSynced} coaching files, and ${result.docsSynced} docs from remote`));
-    // Update version in config.json
-    const configPath = path_1.default.join(fraimDir, 'config.json');
-    if (fs_1.default.existsSync(configPath)) {
-        try {
-            const currentConfig = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
-            const newVersion = (0, version_utils_1.getFraimVersion)();
-            if (currentConfig.version !== newVersion) {
-                currentConfig.version = newVersion;
-                fs_1.default.writeFileSync(configPath, JSON.stringify(currentConfig, null, 2));
-                console.log(chalk_1.default.green(`✅ Updated FRAIM version to ${newVersion} in config.`));
-            }
-        }
-        catch (e) {
-            console.warn(chalk_1.default.yellow('⚠️ Could not update version in config.json.'));
-        }
-    }
+    console.log(chalk_1.default.green(`✅ Successfully synced ${result.workflowsSynced} workflows, ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from remote`));
+    updateVersionInConfig(fraimDir);
 };
 exports.runSync = runSync;
 async function checkAndUpdateCLI() {

package/dist/src/cli/doctor/checks/workflow-checks.js

@@ -166,8 +166,9 @@ function checkOverrideSyntaxValid() {
         category: 'workflows',
         critical: false,
         run: async () => {
-            const overridesDir = path_1.default.join(process.cwd(), '.fraim', 'overrides');
-            if (!fs_1.default.existsSync(overridesDir)) {
+            const personalizedDir = path_1.default.join(process.cwd(), '.fraim', 'personalized-employee');
+            const legacyOverridesDir = path_1.default.join(process.cwd(), '.fraim', 'overrides');
+            if (!fs_1.default.existsSync(personalizedDir) && !fs_1.default.existsSync(legacyOverridesDir)) {
                 return {
                     status: 'passed',
                     message: 'No overrides (not required)',
@@ -192,10 +193,17 @@ function checkOverrideSyntaxValid() {
                         }
                     }
                 };
-                scanDir(overridesDir);
+                if (fs_1.default.existsSync(personalizedDir)) {
+                    scanDir(personalizedDir);
+                }
+                if (fs_1.default.existsSync(legacyOverridesDir)) {
+                    scanDir(legacyOverridesDir);
+                }
                 // Validate each override
                 for (const override of overrides) {
-                    const overridePath = path_1.default.join(overridesDir, override);
+                    const primaryPath = path_1.default.join(personalizedDir, override);
+                    const legacyPath = path_1.default.join(legacyOverridesDir, override);
+                    const overridePath = fs_1.default.existsSync(primaryPath) ? primaryPath : legacyPath;
                     const content = fs_1.default.readFileSync(overridePath, 'utf-8');
                     const parseResult = parser.parse(content);
                     if (parseResult.hasImports) {

package/dist/src/cli/utils/remote-sync.js

@@ -27,8 +27,11 @@ async function syncFromRemote(options) {
         return {
             success: false,
             workflowsSynced: 0,
+            employeeJobsSynced: 0,
+            managerJobsSynced: 0,
+            skillsSynced: 0,
+            rulesSynced: 0,
             scriptsSynced: 0,
-            coachingSynced: 0,
             docsSynced: 0,
             error: 'FRAIM_API_KEY not set'
         };
@@ -49,8 +52,11 @@ async function syncFromRemote(options) {
             return {
                 success: false,
                 workflowsSynced: 0,
+                employeeJobsSynced: 0,
+                managerJobsSynced: 0,
+                skillsSynced: 0,
+                rulesSynced: 0,
                 scriptsSynced: 0,
-                coachingSynced: 0,
                 docsSynced: 0,
                 error: 'No files received'
             };
@@ -73,6 +79,72 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
             console.log(chalk_1.default.gray(`  + ${file.path}`));
         }
+        // Sync job stubs to role-specific folders under .fraim
+        const allJobFiles = files.filter(f => f.type === 'job');
+        const managerJobFiles = allJobFiles.filter(f => f.path.startsWith('ai-manager/'));
+        const jobFiles = allJobFiles.filter(f => !f.path.startsWith('ai-manager/'));
+        const employeeJobsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'jobs');
+        if (!(0, fs_1.existsSync)(employeeJobsDir)) {
+            (0, fs_1.mkdirSync)(employeeJobsDir, { recursive: true });
+        }
+        cleanDirectory(employeeJobsDir);
+        for (const file of jobFiles) {
+            const filePath = (0, path_1.join)(employeeJobsDir, file.path);
+            const fileDir = (0, path_1.dirname)(filePath);
+            if (!(0, fs_1.existsSync)(fileDir)) {
+                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+            console.log(chalk_1.default.gray(`  + ai-employee/jobs/${file.path}`));
+        }
+        // Sync ai-manager job stubs to .fraim/ai-manager/jobs/
+        const managerJobsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-manager', 'jobs');
+        if (!(0, fs_1.existsSync)(managerJobsDir)) {
+            (0, fs_1.mkdirSync)(managerJobsDir, { recursive: true });
+        }
+        cleanDirectory(managerJobsDir);
+        for (const file of managerJobFiles) {
+            const managerRelativePath = file.path.replace(/^ai-manager\//, '');
+            const filePath = (0, path_1.join)(managerJobsDir, managerRelativePath);
+            const fileDir = (0, path_1.dirname)(filePath);
+            if (!(0, fs_1.existsSync)(fileDir)) {
+                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+            console.log(chalk_1.default.gray(`  + ai-manager/jobs/${managerRelativePath}`));
+        }
+        // Sync full skill files to .fraim/ai-employee/skills/
+        const skillFiles = files.filter(f => f.type === 'skill');
+        const skillsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'skills');
+        if (!(0, fs_1.existsSync)(skillsDir)) {
+            (0, fs_1.mkdirSync)(skillsDir, { recursive: true });
+        }
+        cleanDirectory(skillsDir);
+        for (const file of skillFiles) {
+            const filePath = (0, path_1.join)(skillsDir, file.path);
+            const fileDir = (0, path_1.dirname)(filePath);
+            if (!(0, fs_1.existsSync)(fileDir)) {
+                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+            console.log(chalk_1.default.gray(`  + ai-employee/skills/${file.path}`));
+        }
+        // Sync full rule files to .fraim/ai-employee/rules/
+        const ruleFiles = files.filter(f => f.type === 'rule');
+        const rulesDir = (0, path_1.join)(options.projectRoot, '.fraim', 'ai-employee', 'rules');
+        if (!(0, fs_1.existsSync)(rulesDir)) {
+            (0, fs_1.mkdirSync)(rulesDir, { recursive: true });
+        }
+        cleanDirectory(rulesDir);
+        for (const file of ruleFiles) {
+            const filePath = (0, path_1.join)(rulesDir, file.path);
+            const fileDir = (0, path_1.dirname)(filePath);
+            if (!(0, fs_1.existsSync)(fileDir)) {
+                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+            }
+            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+            console.log(chalk_1.default.gray(`  + ai-employee/rules/${file.path}`));
+        }
         // Sync scripts to user directory
         const scriptFiles = files.filter(f => f.type === 'script');
         const userDir = (0, script_sync_utils_1.getUserFraimDir)();
@@ -92,22 +164,6 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
             console.log(chalk_1.default.gray(`  + ${file.path}`));
         }
-        // Sync coaching files to .fraim/coaching-moments/
-        const coachingFiles = files.filter(f => f.type === 'coaching');
-        const coachingDir = (0, path_1.join)(options.projectRoot, '.fraim', 'coaching-moments');
-        if (!(0, fs_1.existsSync)(coachingDir)) {
-            (0, fs_1.mkdirSync)(coachingDir, { recursive: true });
-        }
-        cleanDirectory(coachingDir);
-        for (const file of coachingFiles) {
-            const filePath = (0, path_1.join)(coachingDir, file.path);
-            const fileDir = (0, path_1.dirname)(filePath);
-            if (!(0, fs_1.existsSync)(fileDir)) {
-                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
-            }
-            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
-            console.log(chalk_1.default.gray(`  + coaching-moments/${file.path}`));
-        }
         // Sync docs to .fraim/docs/
         const docsFiles = files.filter(f => f.type === 'docs');
         const docsDir = (0, path_1.join)(options.projectRoot, '.fraim', 'docs');
@@ -124,12 +180,14 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
             console.log(chalk_1.default.gray(`  + docs/${file.path}`));
         }
-        console.log(chalk_1.default.green(`\n✅ Synced ${workflowFiles.length} workflows, ${scriptFiles.length} scripts, ${coachingFiles.length} coaching files, and ${docsFiles.length} docs from remote`));
         return {
             success: true,
             workflowsSynced: workflowFiles.length,
+            employeeJobsSynced: jobFiles.length,
+            managerJobsSynced: managerJobFiles.length,
+            skillsSynced: skillFiles.length,
+            rulesSynced: ruleFiles.length,
             scriptsSynced: scriptFiles.length,
-            coachingSynced: coachingFiles.length,
             docsSynced: docsFiles.length
         };
     }
@@ -138,8 +196,11 @@ async function syncFromRemote(options) {
         return {
             success: false,
             workflowsSynced: 0,
+            employeeJobsSynced: 0,
+            managerJobsSynced: 0,
+            skillsSynced: 0,
+            rulesSynced: 0,
             scriptsSynced: 0,
-            coachingSynced: 0,
             docsSynced: 0,
             error: error.message
         };

package/dist/src/core/utils/local-registry-resolver.js

@@ -20,22 +20,54 @@ class LocalRegistryResolver {
      * Check if a local override exists for the given path
      */
     hasLocalOverride(path) {
-        const overridePath = this.getOverridePath(path);
-        const exists = (0, fs_1.existsSync)(overridePath);
-        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> ${overridePath} -> ${exists}`);
+        const primaryPath = this.getOverridePath(path);
+        const legacyPath = this.getLegacyOverridePath(path);
+        const exists = (0, fs_1.existsSync)(primaryPath) || (0, fs_1.existsSync)(legacyPath);
+        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> primary: ${primaryPath}, legacy: ${legacyPath}, exists: ${exists}`);
         return exists;
     }
+    /**
+     * Check if a locally synced skill/rule file exists for the given registry path.
+     */
+    hasSyncedLocalFile(path) {
+        const syncedPath = this.getSyncedFilePath(path);
+        return !!syncedPath && (0, fs_1.existsSync)(syncedPath);
+    }
     /**
      * Get the full path to a local override file
      */
     getOverridePath(path) {
+        return (0, path_1.join)(this.workspaceRoot, '.fraim/personalized-employee', path);
+    }
+    /**
+     * Get the full path to a legacy local override file.
+     * Kept for backward compatibility while migrating to personalized-employee.
+     */
+    getLegacyOverridePath(path) {
         return (0, path_1.join)(this.workspaceRoot, '.fraim/overrides', path);
     }
+    /**
+     * Get the full path to a locally synced FRAIM file when available.
+     * Skills and rules are synced under role-based folders:
+     * - skills/* -> .fraim/ai-employee/skills/*
+     * - rules/*  -> .fraim/ai-employee/rules/*
+     */
+    getSyncedFilePath(path) {
+        const normalizedPath = path.replace(/\\/g, '/').replace(/^\/+/, '');
+        if (normalizedPath.startsWith('skills/')) {
+            return (0, path_1.join)(this.workspaceRoot, '.fraim/ai-employee', normalizedPath);
+        }
+        if (normalizedPath.startsWith('rules/')) {
+            return (0, path_1.join)(this.workspaceRoot, '.fraim/ai-employee', normalizedPath);
+        }
+        return null;
+    }
     /**
      * Read local override file content
      */
     readLocalOverride(path) {
-        const overridePath = this.getOverridePath(path);
+        const primaryPath = this.getOverridePath(path);
+        const overridePath = (0, fs_1.existsSync)(primaryPath) ? primaryPath : this.getLegacyOverridePath(path);
         try {
             return (0, fs_1.readFileSync)(overridePath, 'utf-8');
         }
@@ -43,6 +75,37 @@ class LocalRegistryResolver {
             throw new Error(`Failed to read local override: ${path}. ${error.message}`);
         }
     }
+    /**
+     * Read locally synced skill/rule file content.
+     */
+    readSyncedLocalFile(path) {
+        const syncedPath = this.getSyncedFilePath(path);
+        if (!syncedPath || !(0, fs_1.existsSync)(syncedPath)) {
+            return null;
+        }
+        try {
+            return (0, fs_1.readFileSync)(syncedPath, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    stripMcpHeader(content) {
+        const trimmed = content.trimStart();
+        if (!trimmed.startsWith('#')) {
+            return content;
+        }
+        const separator = '\n---\n';
+        const separatorIndex = content.indexOf(separator);
+        if (separatorIndex === -1) {
+            return content;
+        }
+        const headerBlock = content.slice(0, separatorIndex);
+        if (!headerBlock.includes('** Path:**')) {
+            return content;
+        }
+        return content.slice(separatorIndex + separator.length).trimStart();
+    }
     /**
      * Resolve inheritance in local override content
      */
@@ -86,20 +149,32 @@ class LocalRegistryResolver {
      * Resolve a registry file request
      *
      * Resolution order:
-     * 1. Check for local override in .fraim/overrides/
-     * 2. If found, read and resolve inheritance
-     * 3. If not found, fetch from remote
+     * 1. Check for local override in .fraim/personalized-employee/
+     * 2. Fallback to .fraim/overrides/ (legacy)
+     * 3. If found, read and resolve inheritance
+     * 4. If not found, fetch from remote
      *
      * @param path - Registry path (e.g., "workflows/product-building/spec.md")
      * @returns Resolved file with metadata
      */
-    async resolveFile(path) {
+    async resolveFile(path, options = {}) {
         console.error(`[LocalRegistryResolver] ===== resolveFile called for: ${path} =====`);
+        const includeMetadata = options.includeMetadata ?? true;
+        const stripMcpHeader = options.stripMcpHeader ?? false;
         // Check for local override
         if (!this.hasLocalOverride(path)) {
+            const syncedLocalContent = this.readSyncedLocalFile(path);
+            if (syncedLocalContent !== null) {
+                return {
+                    content: syncedLocalContent,
+                    source: 'local',
+                    inherited: false
+                };
+            }
             // No override, fetch from remote
             try {
-                const content = await this.remoteContentResolver(path);
+                const rawContent = await this.remoteContentResolver(path);
+                const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
                 return {
                     content,
                     source: 'remote',
@@ -118,7 +193,8 @@ class LocalRegistryResolver {
         catch (error) {
             // If local read fails, fall back to remote
             console.warn(`Local override read failed, falling back to remote: ${path}`);
-            const content = await this.remoteContentResolver(path);
+            const rawContent = await this.remoteContentResolver(path);
+            const content = stripMcpHeader ? this.stripMcpHeader(rawContent) : rawContent;
             return {
                 content,
                 source: 'remote',
@@ -154,12 +230,93 @@ class LocalRegistryResolver {
             imports: resolved.imports.length > 0 ? resolved.imports : undefined
         };
         // Add metadata comment
-        const metadata = this.generateMetadata(result);
-        if (metadata) {
-            result.metadata = metadata;
-            result.content = metadata + result.content;
+        if (includeMetadata) {
+            const metadata = this.generateMetadata(result);
+            if (metadata) {
+                result.metadata = metadata;
+                result.content = metadata + result.content;
+            }
         }
         return result;
     }
+    sanitizeIncludePath(path) {
+        const trimmed = path.trim().replace(/\\/g, '/');
+        if (!trimmed)
+            return null;
+        if (trimmed.includes('..'))
+            return null;
+        if (trimmed.startsWith('/'))
+            return null;
+        if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed))
+            return null;
+        return trimmed;
+    }
+    async resolveIncludesInternal(content, options) {
+        if (options.depth >= options.maxDepth) {
+            return content;
+        }
+        const includePattern = /\{\{include:([^}]+)\}\}/g;
+        const matches = Array.from(content.matchAll(includePattern));
+        if (matches.length === 0) {
+            return content;
+        }
+        const resolvedByPath = new Map();
+        for (const match of matches) {
+            const includePath = this.sanitizeIncludePath(match[1]);
+            if (!includePath)
+                continue;
+            if (resolvedByPath.has(includePath))
+                continue;
+            if (options.cache.has(includePath)) {
+                resolvedByPath.set(includePath, options.cache.get(includePath));
+                continue;
+            }
+            if (options.stack.has(includePath)) {
+                continue;
+            }
+            try {
+                options.stack.add(includePath);
+                const resolved = await this.resolveFile(includePath, {
+                    includeMetadata: false,
+                    stripMcpHeader: true
+                });
+                const resolvedContent = await this.resolveIncludesInternal(resolved.content, {
+                    depth: options.depth + 1,
+                    maxDepth: options.maxDepth,
+                    stack: options.stack,
+                    cache: options.cache
+                });
+                options.cache.set(includePath, resolvedContent);
+                resolvedByPath.set(includePath, resolvedContent);
+            }
+            catch (error) {
+                console.warn(`Failed to resolve include ${includePath}: ${error.message}`);
+            }
+            finally {
+                options.stack.delete(includePath);
+            }
+        }
+        return content.replace(includePattern, (fullMatch, includeRef) => {
+            const includePath = this.sanitizeIncludePath(includeRef);
+            if (!includePath)
+                return fullMatch;
+            return resolvedByPath.get(includePath) ?? fullMatch;
+        });
+    }
+    /**
+     * Resolve {{include:path}} directives using local override precedence:
+     * 1. .fraim/personalized-employee/
+     * 2. .fraim/overrides/ (legacy)
+     * 3. remote resolver
+     */
+    async resolveIncludes(content, maxDepth = LocalRegistryResolver.MAX_INCLUDE_DEPTH) {
+        return this.resolveIncludesInternal(content, {
+            depth: 0,
+            maxDepth,
+            stack: new Set(),
+            cache: new Map()
+        });
+    }
 }
 exports.LocalRegistryResolver = LocalRegistryResolver;
+LocalRegistryResolver.MAX_INCLUDE_DEPTH = 10;

package/dist/src/core/utils/stub-generator.js

@@ -2,6 +2,48 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateWorkflowStub = generateWorkflowStub;
 exports.parseRegistryWorkflow = parseRegistryWorkflow;
+exports.generateJobStub = generateJobStub;
+exports.generateSkillStub = generateSkillStub;
+exports.generateRuleStub = generateRuleStub;
+exports.parseRegistryJob = parseRegistryJob;
+exports.parseRegistrySkill = parseRegistrySkill;
+exports.parseRegistryRule = parseRegistryRule;
+function extractSection(content, headingPatterns) {
+    for (const heading of headingPatterns) {
+        const pattern = new RegExp(`(?:^|\\n)#{2,3}\\s*${heading}\\s*\\n([\\s\\S]*?)(?=\\n#{2,3}\\s|$)`, 'i');
+        const match = content.match(pattern);
+        if (match?.[1]) {
+            const section = match[1].trim();
+            if (section.length > 0)
+                return section;
+        }
+    }
+    return null;
+}
+function extractLeadParagraph(content) {
+    const withoutFrontmatter = content.replace(/^---[\s\S]*?---\s*/m, '');
+    const lines = withoutFrontmatter.split(/\r?\n/);
+    const paragraphLines = [];
+    let started = false;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!started) {
+            if (!line || line.startsWith('#'))
+                continue;
+            if (line.startsWith('-') || /^\d+\./.test(line))
+                continue;
+            started = true;
+        }
+        if (!line)
+            break;
+        if (line.startsWith('#'))
+            break;
+        paragraphLines.push(line);
+    }
+    if (paragraphLines.length === 0)
+        return null;
+    return paragraphLines.join(' ').trim();
+}
 /**
  * Generates a lightweight markdown stub for a workflow.
  * These stubs are committed to the user's repo for discoverability.
@@ -33,3 +75,100 @@ function parseRegistryWorkflow(content) {
         : [];
     return { intent, principles };
 }
+/**
+ * Coaching stubs are discoverability artifacts and should be resolved with get_fraim_file.
+ */
+function generateJobStub(jobName, _jobPath, intent, outcome) {
+    return `# FRAIM Job: ${jobName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
+> This stub is for discoverability only. The actual job has multiple phases with
+> detailed steps, validation criteria, and required skills.
+>
+> To get full phase-by-phase instructions, call:
+> \`get_fraim_job({ job: "${jobName}" })\`
+>
+> Then follow all phases using \`seekMentoring\` at each phase transition.
+`;
+}
+/**
+ * Generates a lightweight markdown stub for a skill.
+ */
+function generateSkillStub(skillName, skillPath, intent, outcome) {
+    return `# FRAIM Skill: ${skillName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a skill stub for discoverability.
+> To retrieve the complete skill instructions, call:
+> \`get_fraim_file({ path: "skills/${skillPath}" })\`
+`;
+}
+/**
+ * Generates a lightweight markdown stub for a rule.
+ */
+function generateRuleStub(ruleName, rulePath, intent, outcome) {
+    return `# FRAIM Rule: ${ruleName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a rule stub for discoverability.
+> To retrieve the complete rule instructions, call:
+> \`get_fraim_file({ path: "rules/${rulePath}" })\`
+`;
+}
+/**
+ * Parses a job file from the registry to extract its intent and outcome for the stub.
+ */
+function parseRegistryJob(content) {
+    const intentMatch = content.match(/##\s*intent\s+([\s\S]*?)(?=\n##|$)/i);
+    const outcomeMatch = content.match(/##\s*outcome\s+([\s\S]*?)(?=\n##|$)/i);
+    const intent = intentMatch ? intentMatch[1].trim() : 'No intent defined.';
+    const outcome = outcomeMatch ? outcomeMatch[1].trim() : 'No outcome defined.';
+    return { intent, outcome };
+}
+/**
+ * Parses a skill file from the registry to extract intent and expected outcome for stubs.
+ */
+function parseRegistrySkill(content) {
+    const intent = extractSection(content, ['intent', 'skill intent']) ||
+        extractLeadParagraph(content) ||
+        'Apply the skill correctly using the provided inputs and constraints.';
+    const outcome = extractSection(content, ['outcome', 'expected behavior', 'skill output']) ||
+        'Produce the expected skill output while following skill guardrails.';
+    return { intent, outcome };
+}
+/**
+ * Parses a rule file from the registry to extract intent and expected behavior for stubs.
+ */
+function parseRegistryRule(content) {
+    const intent = extractSection(content, ['intent']) ||
+        extractLeadParagraph(content) ||
+        'Follow this rule when executing related FRAIM workflows and jobs.';
+    const outcome = extractSection(content, ['outcome', 'expected behavior', 'principles']) ||
+        'Consistently apply this rule throughout execution.';
+    return { intent, outcome };
+}

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

@@ -790,6 +790,45 @@ class FraimLocalMCPServer {
         }
         return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
     }
+    shouldResolveIncludes(toolName) {
+        return toolName === 'get_fraim_workflow' ||
+            toolName === 'get_fraim_job' ||
+            toolName === 'get_fraim_file' ||
+            toolName === 'seekMentoring';
+    }
+    async resolveIncludesInResponse(response, requestSessionId) {
+        if (!response.result?.content || !Array.isArray(response.result.content)) {
+            return response;
+        }
+        const resolver = this.getRegistryResolver(requestSessionId);
+        const transformedContent = [];
+        for (const block of response.result.content) {
+            if (block?.type !== 'text' || typeof block.text !== 'string') {
+                transformedContent.push(block);
+                continue;
+            }
+            const resolvedText = await resolver.resolveIncludes(block.text);
+            transformedContent.push({
+                ...block,
+                text: resolvedText
+            });
+        }
+        return {
+            ...response,
+            result: {
+                ...response.result,
+                content: transformedContent
+            }
+        };
+    }
+    async finalizeToolResponse(request, response, requestSessionId) {
+        let finalizedResponse = response;
+        const toolName = request.params?.name;
+        if (request.method === 'tools/call' && typeof toolName === 'string' && this.shouldResolveIncludes(toolName)) {
+            finalizedResponse = await this.resolveIncludesInResponse(finalizedResponse, requestSessionId);
+        }
+        return this.processResponseWithHydration(finalizedResponse, requestSessionId);
+    }
     rewriteProxyTokensInText(text) {
         const tokens = new Set();
         const rewritten = text.replace(/\{\{\s*proxy\.([^}]+?)\s*\}\}/g, (_match, proxyPath) => {
@@ -861,35 +900,19 @@ class FraimLocalMCPServer {
                 remoteContentResolver: async (path) => {
                     // Fetch parent content from remote for inheritance
                     this.log(`🔄 Remote content resolver: fetching ${path}`);
-                    let request;
-                    if (path.startsWith('workflows/')) {
-                        // Extract workflow name from path: workflows/category/name.md -> name
-                        const pathParts = path.replace('workflows/', '').replace('.md', '').split('/');
-                        const workflowName = pathParts[pathParts.length - 1]; // Get last part (name)
-                        this.log(`🔄 Fetching workflow: ${workflowName}`);
-                        request = {
-                            jsonrpc: '2.0',
-                            id: (0, crypto_1.randomUUID)(),
-                            method: 'tools/call',
-                            params: {
-                                name: 'get_fraim_workflow',
-                                arguments: { workflow: workflowName }
-                            }
-                        };
-                    }
-                    else {
-                        // For non-workflow files (templates, rules, etc.), use get_fraim_file
-                        this.log(`🔄 Fetching file: ${path}`);
-                        request = {
-                            jsonrpc: '2.0',
-                            id: (0, crypto_1.randomUUID)(),
-                            method: 'tools/call',
-                            params: {
-                                name: 'get_fraim_file',
-                                arguments: { path }
+                    this.log(`🔄 Fetching raw file content: ${path}`);
+                    const request = {
+                        jsonrpc: '2.0',
+                        id: (0, crypto_1.randomUUID)(),
+                        method: 'tools/call',
+                        params: {
+                            name: 'get_fraim_file',
+                            arguments: {
+                                path,
+                                _internalRaw: true
                             }
-                        };
-                    }
+                        }
+                    };
                     this.applyRequestSessionId(request, requestSessionId);
                     const response = await this.proxyToRemote(request);
                     if (response.error) {
@@ -943,6 +966,38 @@ class FraimLocalMCPServer {
         // Default to product-building for unknown workflows
         return 'product-building';
     }
+    /**
+     * Find local override path for a job name by scanning override roots.
+     * Returns a registry-style path like jobs/<category>/<name>.md when found.
+     */
+    findJobOverridePath(jobName) {
+        const projectRoot = this.findProjectRoot();
+        if (!projectRoot)
+            return null;
+        const candidates = [
+            (0, path_1.join)(projectRoot, '.fraim', 'personalized-employee', 'jobs'),
+            (0, path_1.join)(projectRoot, '.fraim', 'overrides', 'jobs')
+        ];
+        for (const jobsRoot of candidates) {
+            if (!(0, fs_1.existsSync)(jobsRoot))
+                continue;
+            try {
+                const categories = (0, fs_1.readdirSync)(jobsRoot, { withFileTypes: true })
+                    .filter(entry => entry.isDirectory())
+                    .map(entry => entry.name);
+                for (const category of categories) {
+                    const jobFilePath = (0, path_1.join)(jobsRoot, category, `${jobName}.md`);
+                    if ((0, fs_1.existsSync)(jobFilePath)) {
+                        return `jobs/${category}/${jobName}.md`;
+                    }
+                }
+            }
+            catch {
+                // Best effort scan only.
+            }
+        }
+        return null;
+    }
     /**
      * Process template substitution in MCP response
      */
@@ -1305,7 +1360,7 @@ class FraimLocalMCPServer {
             }
             // Proxy initialize to remote server first
             const response = await this.proxyToRemote(request);
-            const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
+            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
             // After successful initialization, load config
             if (!processedResponse.error) {
                 // Load config immediately for compatibility, then request roots so
@@ -1318,9 +1373,10 @@ class FraimLocalMCPServer {
             this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
             return processedResponse;
         }
-        // Intercept get_fraim_workflow and get_fraim_file for override resolution
+        // Intercept get_fraim_workflow, get_fraim_job, and get_fraim_file for override resolution
         if (request.method === 'tools/call' &&
             (request.params?.name === 'get_fraim_workflow' ||
+                request.params?.name === 'get_fraim_job' ||
                 request.params?.name === 'get_fraim_file')) {
             try {
                 const toolName = request.params.name;
@@ -1359,7 +1415,41 @@ class FraimLocalMCPServer {
                                 }
                             };
                             // Apply template substitution
-                            const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
+                            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
+                            this.log(`📤 ${request.method} → OK`);
+                            return processedResponse;
+                        }
+                    }
+                }
+                else if (toolName === 'get_fraim_job') {
+                    const jobName = args.job;
+                    if (!jobName) {
+                        this.log('⚠️ No job name provided in get_fraim_job');
+                    }
+                    else {
+                        // Determine job path by scanning local override roots.
+                        requestedPath = this.findJobOverridePath(jobName) || `jobs/product-building/${jobName}.md`;
+                        this.log(`🔍 Checking for override: ${requestedPath}`);
+                        const resolver = this.getRegistryResolver(requestSessionId);
+                        const hasOverride = resolver.hasLocalOverride(requestedPath);
+                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
+                        if (hasOverride) {
+                            this.log(`✅ Local override found: ${requestedPath}`);
+                            const resolved = await resolver.resolveFile(requestedPath);
+                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                            const response = {
+                                jsonrpc: '2.0',
+                                id: request.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: resolved.content
+                                        }
+                                    ]
+                                }
+                            };
+                            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
                             this.log(`📤 ${request.method} → OK`);
                             return processedResponse;
                         }
@@ -1378,6 +1468,27 @@ class FraimLocalMCPServer {
                         else {
                             this.log(`🔍 Checking for override: ${requestedPath}`);
                             const resolver = this.getRegistryResolver(requestSessionId);
+                            const isLocalFirstSyncedPath = requestedPath.startsWith('skills/') || requestedPath.startsWith('rules/');
+                            if (isLocalFirstSyncedPath && resolver.hasSyncedLocalFile(requestedPath)) {
+                                this.log(`✅ Synced local file found: ${requestedPath}`);
+                                const resolved = await resolver.resolveFile(requestedPath, { includeMetadata: false });
+                                this.log(`📝 Synced local file resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                                const response = {
+                                    jsonrpc: '2.0',
+                                    id: request.id,
+                                    result: {
+                                        content: [
+                                            {
+                                                type: 'text',
+                                                text: resolved.content
+                                            }
+                                        ]
+                                    }
+                                };
+                                const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
+                                this.log(`📤 ${request.method} → OK`);
+                                return processedResponse;
+                            }
                             const hasOverride = resolver.hasLocalOverride(requestedPath);
                             this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
                             if (hasOverride) {
@@ -1398,7 +1509,7 @@ class FraimLocalMCPServer {
                                     }
                                 };
                                 // Apply template substitution
-                                const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
+                                const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
                                 this.log(`📤 ${request.method} → OK`);
                                 return processedResponse;
                             }
@@ -1414,7 +1525,7 @@ class FraimLocalMCPServer {
         }
         // Proxy to remote server
         const response = await this.proxyToRemote(request);
-        const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
+        const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
         this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
         return processedResponse;
     }

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.84",
+  "version": "2.0.85",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "test-all": "npm run test && npm run test:isolated && npm run test:ui",
     "test": "node scripts/test-with-server.js",
     "test:isolated": "npx tsx --test --test-reporter=spec tests/isolated/test-*.ts",
+    "test:smoke": "node scripts/test-with-server.js tests/test-*.ts --tags=smoke",
     "test:ui": "playwright test",
     "test:ui:headed": "playwright test --headed",
     "start:fraim": "tsx src/fraim-mcp-server.ts",