fraim 2.0.105 → 2.0.106

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

@@ -602,6 +602,26 @@ const runSetup = async (options) => {
             console.log(chalk_1.default.gray('   You can update them manually with: fraim add-ide <ide-name>\n'));
         }
     }
+    // Sync user-level FRAIM artifacts (always, on both initial and update)
+    try {
+        const { syncUserLevelArtifacts } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+        console.log(chalk_1.default.blue('\n📦 Syncing user-level FRAIM content...'));
+        await syncUserLevelArtifacts();
+    }
+    catch (e) {
+        console.log(chalk_1.default.yellow(`⚠️  User-level content sync encountered issues: ${e.message}`));
+        console.log(chalk_1.default.gray('   You can sync later with: fraim sync --global'));
+    }
+    // Install IDE slash commands and global rules
+    try {
+        const { installSlashCommands, installGlobalRules } = await Promise.resolve().then(() => __importStar(require('../setup/ide-global-integration')));
+        console.log(chalk_1.default.blue('\n🔗 Installing IDE integrations...'));
+        await installSlashCommands();
+        await installGlobalRules();
+    }
+    catch (e) {
+        console.log(chalk_1.default.yellow(`⚠️  IDE integration encountered issues: ${e.message}`));
+    }
     // Auto-run project init if we're in a git repo (only on initial setup)
     if (!isUpdate) {
         if ((0, platform_detection_1.isGitRepository)()) {

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

@@ -84,6 +84,20 @@ function updateVersionInConfig(fraimDir) {
     }
 }
 const runSync = async (options) => {
+    // Handle --global flag: sync to user-level ~/.fraim/ instead of project
+    if (options.global) {
+        console.log(chalk_1.default.blue('Syncing FRAIM content to user-level directory (~/.fraim/)...'));
+        try {
+            const { syncUserLevelArtifacts } = await Promise.resolve().then(() => __importStar(require('../setup/user-level-sync')));
+            await syncUserLevelArtifacts();
+            console.log(chalk_1.default.green('\n✅ User-level FRAIM content sync complete.'));
+        }
+        catch (error) {
+            console.error(chalk_1.default.red(`User-level sync failed: ${error.message}`));
+            process.exit(1);
+        }
+        return;
+    }
     const projectRoot = process.cwd();
     const config = (0, config_loader_1.loadFraimConfig)();
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
@@ -171,4 +185,5 @@ exports.syncCommand = new commander_1.Command('sync')
     .option('-f, --force', 'Force sync even if digest matches')
     .option('--skip-updates', 'Skip checking for CLI updates (legacy)')
     .option('--local', 'Sync from local development server (port derived from git branch)')
+    .option('--global', 'Sync user-level FRAIM content (~/.fraim/) instead of project')
     .action(exports.runSync);

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

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installSlashCommands = installSlashCommands;
+exports.installGlobalRules = installGlobalRules;
+/**
+ * IDE Global Integration
+ *
+ * Installs FRAIM slash commands and global rules into user-level IDE
+ * configuration directories. These enable FRAIM to be discoverable
+ * in any project without requiring fraim init-project.
+ *
+ * Part of: User-Level FRAIM Artifacts with Local Shadow Semantics
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const chalk_1 = __importDefault(require("chalk"));
+const FRAIM_SLASH_COMMAND_CONTENT = `The user wants to run FRAIM. The requested job or topic is: $ARGUMENTS
+
+Follow this process:
+
+1. **If no argument was given** (the line above ends with ": "): call \`list_fraim_jobs()\` to discover available jobs. List each by name and its Intent line. Ask the user which job they want to run, then proceed to step 2.
+
+2. **Find the match**: from the list returned by \`list_fraim_jobs()\`, find the job whose name matches or closely resembles the argument. If no job matches, search for a matching skill by calling \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` — try common categories like \`engineering/\`, \`marketing/\`, \`business/\`, \`product-management/\`, \`ai-tools/\`. Confirm the match with the user.
+
+3. **Load the full content**:
+   - For jobs: call \`get_fraim_job({ job: "<matched-job-name>" })\` — never execute from stub content.
+   - For skills: the content from \`get_fraim_file\` is the full skill. Use it directly.
+
+4. **Execute**: for jobs, follow the phased instructions returned by \`get_fraim_job\`, using \`seekMentoring\` at phase transitions where indicated. For skills, apply the skill steps to the user's current context.
+`;
+const FRAIM_CURSOR_RULES_CONTENT = `# FRAIM Rules
+
+This workspace uses FRAIM (Framework for Rigor-based AI Management).
+
+## Discovery
+- Before acting on any user request, check if a FRAIM job matches the intent.
+- Call \`list_fraim_jobs()\` to discover available jobs.
+- Call \`get_fraim_job({ job: "<job-name>" })\` to get full phased instructions.
+
+## Execution
+- Jobs are FRAIM's primary execution units — structured, multi-phase workflows.
+- Skills are reusable capabilities that jobs compose.
+- Rules are always-on constraints and conventions.
+- Follow phased instructions and use \`seekMentoring\` at phase transitions.
+
+## Principles
+- Never execute from job stubs — always load full instructions via MCP.
+- Follow the constitution: integrity, correctness, contribution, completeness.
+`;
+/**
+ * Install the FRAIM slash command for Claude Code at the user level.
+ * Writes to ~/.claude/commands/fraim.md.
+ * Does NOT overwrite if the file already exists.
+ *
+ * @param homeDir - Override for home directory (for testing)
+ */
+async function installSlashCommands(homeDir) {
+    const home = homeDir || os_1.default.homedir();
+    const claudeDir = path_1.default.join(home, '.claude');
+    // Only install if Claude Code is installed (indicated by .claude/ existing)
+    if (!fs_1.default.existsSync(claudeDir)) {
+        return;
+    }
+    const commandsDir = path_1.default.join(claudeDir, 'commands');
+    const slashCommandPath = path_1.default.join(commandsDir, 'fraim.md');
+    // Do not overwrite existing file
+    if (fs_1.default.existsSync(slashCommandPath)) {
+        console.log(chalk_1.default.gray('   Claude slash command already exists — skipping'));
+        return;
+    }
+    fs_1.default.mkdirSync(commandsDir, { recursive: true });
+    fs_1.default.writeFileSync(slashCommandPath, FRAIM_SLASH_COMMAND_CONTENT, 'utf8');
+    console.log(chalk_1.default.green('   ✅ Installed Claude slash command (~/.claude/commands/fraim.md)'));
+}
+/**
+ * Install FRAIM global rules/instructions for supported IDEs.
+ * Supports: Cursor, Codex, Windsurf, Kiro
+ * Does NOT overwrite if files already exist.
+ *
+ * @param homeDir - Override for home directory (for testing)
+ */
+async function installGlobalRules(homeDir) {
+    const home = homeDir || os_1.default.homedir();
+    // Cursor: ~/.cursor/rules/fraim-rules.md
+    const cursorDir = path_1.default.join(home, '.cursor');
+    if (fs_1.default.existsSync(cursorDir)) {
+        installRuleFile(path_1.default.join(cursorDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Cursor global rules (~/.cursor/rules/fraim-rules.md)');
+    }
+    // Codex: ~/.codex/instructions.md
+    const codexDir = path_1.default.join(home, '.codex');
+    if (fs_1.default.existsSync(codexDir)) {
+        installRuleFile(path_1.default.join(codexDir, 'instructions.md'), FRAIM_CURSOR_RULES_CONTENT, 'Codex global instructions (~/.codex/instructions.md)');
+    }
+    // Windsurf: ~/.codeium/windsurf/rules/fraim-rules.md
+    const windsurfDir = path_1.default.join(home, '.codeium', 'windsurf');
+    if (fs_1.default.existsSync(windsurfDir)) {
+        installRuleFile(path_1.default.join(windsurfDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Windsurf global rules (~/.codeium/windsurf/rules/fraim-rules.md)');
+    }
+    // Kiro: ~/.kiro/rules/fraim-rules.md
+    const kiroDir = path_1.default.join(home, '.kiro');
+    if (fs_1.default.existsSync(kiroDir)) {
+        installRuleFile(path_1.default.join(kiroDir, 'rules', 'fraim-rules.md'), FRAIM_CURSOR_RULES_CONTENT, 'Kiro global rules (~/.kiro/rules/fraim-rules.md)');
+    }
+}
+/**
+ * Install a rule file if it doesn't already exist.
+ */
+function installRuleFile(filePath, content, displayName) {
+    if (fs_1.default.existsSync(filePath)) {
+        console.log(chalk_1.default.gray(`   ${displayName.split('(')[0].trim()} already exist — skipping`));
+        return;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, content, 'utf8');
+    console.log(chalk_1.default.green(`   ✅ Installed ${displayName}`));
+}

package/dist/src/cli/setup/user-level-sync.js

@@ -0,0 +1,139 @@
+"use strict";
+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 };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureUserLevelDirectories = ensureUserLevelDirectories;
+exports.syncUserLevelArtifacts = syncUserLevelArtifacts;
+/**
+ * User-Level FRAIM Artifact Sync
+ *
+ * Syncs jobs, skills, rules, and docs stubs from the remote FRAIM server
+ * to the user-level ~/.fraim/ directory. This makes FRAIM discoverable
+ * everywhere without requiring fraim init-project.
+ *
+ * Part of: User-Level FRAIM Artifacts with Local Shadow Semantics
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const script_sync_utils_1 = require("../utils/script-sync-utils");
+/**
+ * Ensure the user-level FRAIM directory structure exists for content sync.
+ * Creates directories for synced content and personalized overrides.
+ */
+function ensureUserLevelDirectories(userFraimDir) {
+    const baseDir = userFraimDir || (0, script_sync_utils_1.getUserFraimDir)();
+    const dirs = [
+        path_1.default.join(baseDir, 'ai-employee', 'jobs'),
+        path_1.default.join(baseDir, 'ai-employee', 'skills'),
+        path_1.default.join(baseDir, 'ai-employee', 'rules'),
+        path_1.default.join(baseDir, 'ai-manager', 'jobs'),
+        path_1.default.join(baseDir, 'personalized-employee', 'jobs'),
+        path_1.default.join(baseDir, 'personalized-employee', 'skills'),
+        path_1.default.join(baseDir, 'personalized-employee', 'rules'),
+        path_1.default.join(baseDir, 'personalized-employee', 'learnings'),
+        path_1.default.join(baseDir, 'docs'),
+    ];
+    for (const dir of dirs) {
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+    }
+}
+/**
+ * Sync FRAIM artifacts (jobs, skills, rules, docs) from the remote server
+ * to the user-level ~/.fraim/ directory.
+ *
+ * Uses the same remote sync endpoint as project-level sync, but writes
+ * content directly to the user-level directory structure instead of under
+ * a project's fraim/ subdirectory.
+ *
+ * @param userFraimDir - Override for the target directory (for testing)
+ */
+async function syncUserLevelArtifacts(userFraimDir) {
+    const baseDir = userFraimDir || (0, script_sync_utils_1.getUserFraimDir)();
+    console.log(chalk_1.default.blue('📦 Syncing FRAIM content to user-level directory...'));
+    console.log(chalk_1.default.gray(`   Target: ${baseDir}`));
+    // Ensure directory structure exists
+    ensureUserLevelDirectories(baseDir);
+    // Try to sync from remote. If this fails (no network, no key),
+    // we still have the directory structure in place.
+    try {
+        const { syncFromRemote } = await Promise.resolve().then(() => __importStar(require('../utils/remote-sync')));
+        const apiKey = loadApiKeyFromConfig(baseDir);
+        if (!apiKey) {
+            console.log(chalk_1.default.yellow('⚠️  No API key found. User-level content sync skipped.'));
+            console.log(chalk_1.default.gray('   Directory structure created. Content will sync on next fraim sync --global.'));
+            return;
+        }
+        const result = await syncFromRemote({
+            apiKey,
+            projectRoot: baseDir,
+            targetIsUserLevel: true,
+            skipUpdates: true
+        });
+        if (result.success) {
+            console.log(chalk_1.default.green(`✅ Synced ${result.employeeJobsSynced} ai-employee jobs, ` +
+                `${result.managerJobsSynced} ai-manager jobs, ` +
+                `${result.skillsSynced} skills, ${result.rulesSynced} rules, ` +
+                `${result.scriptsSynced} scripts, and ${result.docsSynced} docs to ~/.fraim/`));
+        }
+        else {
+            console.log(chalk_1.default.yellow(`⚠️  User-level content sync failed: ${result.error}`));
+            console.log(chalk_1.default.gray('   Directory structure created. Content will sync on next fraim sync --global.'));
+        }
+    }
+    catch (error) {
+        console.log(chalk_1.default.yellow(`⚠️  User-level content sync failed: ${error.message}`));
+        console.log(chalk_1.default.gray('   Directory structure created. Content will sync on next fraim sync --global.'));
+    }
+}
+/**
+ * Load API key from the user-level config file.
+ */
+function loadApiKeyFromConfig(userFraimDir) {
+    const configPath = path_1.default.join(userFraimDir, 'config.json');
+    if (!fs_1.default.existsSync(configPath))
+        return undefined;
+    try {
+        const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        return config.apiKey;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -135,8 +135,17 @@ async function syncFromRemote(options) {
                 error: 'No files received'
             };
         }
-        const lockTargets = getSyncedContentLockTargets(options.projectRoot);
-        if (shouldLockSyncedContent()) {
+        // Helper: resolve path within the FRAIM content directory.
+        // For user-level sync, write directly to projectRoot (which IS ~/.fraim/).
+        // For project-level sync, use getWorkspaceFraimPath which prepends 'fraim/'.
+        const resolveFraimPath = (...parts) => {
+            if (options.targetIsUserLevel) {
+                return (0, path_1.join)(options.projectRoot, ...parts);
+            }
+            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, ...parts);
+        };
+        const lockTargets = options.targetIsUserLevel ? [] : getSyncedContentLockTargets(options.projectRoot);
+        if (!options.targetIsUserLevel && shouldLockSyncedContent()) {
             // If previous sync locked these paths read-only, temporarily unlock before cleanup/write.
             for (const target of lockTargets) {
                 setFileWriteLockRecursively(target, false);
@@ -146,7 +155,7 @@ async function syncFromRemote(options) {
         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, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'jobs');
+        const employeeJobsDir = resolveFraimPath('ai-employee', 'jobs');
         if (!(0, fs_1.existsSync)(employeeJobsDir)) {
             (0, fs_1.mkdirSync)(employeeJobsDir, { recursive: true });
         }
@@ -166,7 +175,7 @@ async function syncFromRemote(options) {
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/jobs/${relPath}`)}`));
         }
         // Sync ai-manager job stubs to fraim/ai-manager/jobs/
-        const managerJobsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-manager', 'jobs');
+        const managerJobsDir = resolveFraimPath('ai-manager', 'jobs');
         if (!(0, fs_1.existsSync)(managerJobsDir)) {
             (0, fs_1.mkdirSync)(managerJobsDir, { recursive: true });
         }
@@ -187,7 +196,7 @@ async function syncFromRemote(options) {
         }
         // Sync skill STUBS to fraim/ai-employee/skills/
         const skillFiles = files.filter(f => f.type === 'skill');
-        const skillsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'skills');
+        const skillsDir = resolveFraimPath('ai-employee', 'skills');
         if (!(0, fs_1.existsSync)(skillsDir)) {
             (0, fs_1.mkdirSync)(skillsDir, { recursive: true });
         }
@@ -207,7 +216,7 @@ async function syncFromRemote(options) {
         }
         // Sync rule STUBS to fraim/ai-employee/rules/
         const ruleFiles = files.filter(f => f.type === 'rule');
-        const rulesDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'rules');
+        const rulesDir = resolveFraimPath('ai-employee', 'rules');
         if (!(0, fs_1.existsSync)(rulesDir)) {
             (0, fs_1.mkdirSync)(rulesDir, { recursive: true });
         }
@@ -246,7 +255,7 @@ async function syncFromRemote(options) {
         }
         // Sync docs to fraim/docs/
         const docsFiles = files.filter(f => f.type === 'docs');
-        const docsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'docs');
+        const docsDir = resolveFraimPath('docs');
         if (!(0, fs_1.existsSync)(docsDir)) {
             (0, fs_1.mkdirSync)(docsDir, { recursive: true });
         }
@@ -260,7 +269,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`docs/${file.path}`)}`));
         }
-        if (shouldLockSyncedContent()) {
+        if (!options.targetIsUserLevel && shouldLockSyncedContent()) {
             for (const target of lockTargets) {
                 setFileWriteLockRecursively(target, true);
             }

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

@@ -49,10 +49,22 @@ const project_fraim_paths_1 = require("./project-fraim-paths");
 class LocalRegistryResolver {
     constructor(options) {
         this.workspaceRoot = options.workspaceRoot;
+        this.effectiveFraimDir = options.effectiveFraimDir;
         this.remoteContentResolver = options.remoteContentResolver;
         this.parser = new inheritance_parser_1.InheritanceParser(options.maxDepth);
         this.shouldFilter = options.shouldFilter;
     }
+    /**
+     * Get a path within the effective FRAIM directory.
+     * When effectiveFraimDir is set (user-level mode), joins directly with that dir.
+     * Otherwise, uses the standard getWorkspaceFraimPath which prepends 'fraim/'.
+     */
+    getFraimPath(...parts) {
+        if (this.effectiveFraimDir) {
+            return (0, path_1.join)(this.effectiveFraimDir, ...parts);
+        }
+        return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, ...parts);
+    }
     /**
      * Check if a local override exists for the given path
      */
@@ -72,7 +84,7 @@ class LocalRegistryResolver {
             if (this.hasLocalOverride(literal))
                 return literal;
             // Deep search
-            const fullBaseDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', dir);
+            const fullBaseDir = this.getFraimPath('personalized-employee', dir);
             const found = this.searchFileRecursively(fullBaseDir, baseName);
             if (found) {
                 // Convert absolute back to relative
@@ -116,7 +128,7 @@ class LocalRegistryResolver {
         const normalized = path.replace(/\\/g, '/').replace(/^\/+/, '');
         // Personal overrides are in fraim/personalized-employee/
         // We don't need a redundant 'registry/' subfolder here as the path already includes type (e.g. jobs/)
-        return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', normalized);
+        return this.getFraimPath('personalized-employee', normalized);
     }
     /**
      * Get the full path to a locally synced FRAIM file when available.
@@ -132,18 +144,18 @@ class LocalRegistryResolver {
             if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
                 const role = parts[1];
                 const subPath = parts.slice(2).join('/');
-                return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'workflows', subPath);
+                return this.getFraimPath(role, 'workflows', subPath);
             }
             // Fallback: Try ai-employee and ai-manager if no role prefix
             const subPath = normalizedPath.substring('workflows/'.length);
-            const employeePath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'workflows', subPath);
+            const employeePath = this.getFraimPath('ai-employee', 'workflows', subPath);
             if (fs.existsSync(employeePath))
                 return employeePath;
-            const managerPath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-manager', 'workflows', subPath);
+            const managerPath = this.getFraimPath('ai-manager', 'workflows', subPath);
             if (fs.existsSync(managerPath))
                 return managerPath;
             // Fallback for non-role-prefixed direct workspace paths
-            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, normalizedPath);
+            return this.getFraimPath(normalizedPath);
         }
         // 2. Jobs: jobs/[role]/path -> fraim/[role]/jobs/path
         if (normalizedPath.startsWith('jobs/')) {
@@ -151,18 +163,18 @@ class LocalRegistryResolver {
             if (parts.length >= 3 && (parts[1] === 'ai-employee' || parts[1] === 'ai-manager')) {
                 const role = parts[1];
                 const subPath = parts.slice(2).join('/');
-                return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'jobs', subPath);
+                return this.getFraimPath(role, 'jobs', subPath);
             }
             // Fallback: Try ai-employee and ai-manager if no role prefix
             const subPath = normalizedPath.substring('jobs/'.length);
-            const employeePath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'jobs', subPath);
+            const employeePath = this.getFraimPath('ai-employee', 'jobs', subPath);
             if (fs.existsSync(employeePath))
                 return employeePath;
-            const managerPath = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-manager', 'jobs', subPath);
+            const managerPath = this.getFraimPath('ai-manager', 'jobs', subPath);
             if (fs.existsSync(managerPath))
                 return managerPath;
             // Fallback
-            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, normalizedPath);
+            return this.getFraimPath(normalizedPath);
         }
         // 3. Rules: [role]/rules/path -> fraim/[role]/rules/path
         if (normalizedPath.includes('/rules/')) {
@@ -170,16 +182,16 @@ class LocalRegistryResolver {
             // Extract the part after "rules/"
             const rulesIdx = normalizedPath.indexOf('rules/');
             const subPath = normalizedPath.substring(rulesIdx + 'rules/'.length);
-            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, role, 'rules', subPath);
+            return this.getFraimPath(role, 'rules', subPath);
         }
         // 4. Skills: skills/path -> fraim/ai-employee/skills/path (default to ai-employee)
         if (normalizedPath.startsWith('skills/')) {
             const subPath = normalizedPath.substring('skills/'.length);
-            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', 'skills', subPath);
+            return this.getFraimPath('ai-employee', 'skills', subPath);
         }
         // 5. Rules: rules/path -> fraim/ai-employee/rules/path (default to ai-employee)
         if (normalizedPath.startsWith('rules/')) {
-            return (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'ai-employee', normalizedPath);
+            return this.getFraimPath('ai-employee', normalizedPath);
         }
         return null;
     }
@@ -580,7 +592,7 @@ class LocalRegistryResolver {
         const items = [];
         const dirs = ['jobs'];
         for (const dir of dirs) {
-            const localDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(this.workspaceRoot, 'personalized-employee', dir);
+            const localDir = this.getFraimPath('personalized-employee', dir);
             if (fs.existsSync(localDir)) {
                 const relPaths = this.collectLocalMarkdownPaths(localDir);
                 for (const rel of relPaths) {

package/dist/src/core/utils/project-fraim-paths.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WORKSPACE_SYNCED_CONTENT_DIRS = exports.WORKSPACE_FRAIM_DIRNAME = void 0;
 exports.getWorkspaceFraimDir = getWorkspaceFraimDir;
@@ -6,8 +9,11 @@ exports.workspaceFraimExists = workspaceFraimExists;
 exports.getWorkspaceConfigPath = getWorkspaceConfigPath;
 exports.getWorkspaceFraimPath = getWorkspaceFraimPath;
 exports.getWorkspaceFraimDisplayPath = getWorkspaceFraimDisplayPath;
+exports.getUserFraimDirPath = getUserFraimDirPath;
+exports.getEffectiveFraimDir = getEffectiveFraimDir;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const os_1 = __importDefault(require("os"));
 exports.WORKSPACE_FRAIM_DIRNAME = 'fraim';
 exports.WORKSPACE_SYNCED_CONTENT_DIRS = [
     'workflows',
@@ -36,3 +42,34 @@ function getWorkspaceFraimDisplayPath(relativePath = '') {
         ? `${exports.WORKSPACE_FRAIM_DIRNAME}/${normalized}`
         : `${exports.WORKSPACE_FRAIM_DIRNAME}/`;
 }
+/**
+ * Get the user-level FRAIM directory (~/.fraim/).
+ * Can be overridden with FRAIM_USER_DIR env var for testing.
+ */
+function getUserFraimDirPath() {
+    return process.env.FRAIM_USER_DIR || (0, path_1.join)(os_1.default.homedir(), '.fraim');
+}
+/**
+ * Determine the effective FRAIM content root directory.
+ *
+ * Shadow semantics: if the project has a local fraim/ directory, it completely
+ * shadows the user-level ~/.fraim/ — no mixing, no layering.
+ *
+ * @param projectRoot - The project/workspace root directory
+ * @param userFraimDir - Optional override for the user-level dir (for testing)
+ * @returns The effective fraim content root directory path, or '' if neither exists
+ */
+function getEffectiveFraimDir(projectRoot = process.cwd(), userFraimDir) {
+    // 1. Check for project-level fraim/ directory
+    const projectFraimDir = getWorkspaceFraimDir(projectRoot);
+    if ((0, fs_1.existsSync)(projectFraimDir)) {
+        return projectFraimDir;
+    }
+    // 2. Fall back to user-level ~/.fraim/
+    const userDir = userFraimDir || getUserFraimDirPath();
+    if ((0, fs_1.existsSync)(userDir)) {
+        return userDir;
+    }
+    // 3. Neither exists
+    return '';
+}

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

@@ -1216,8 +1216,16 @@ class FraimLocalMCPServer {
     getRegistryResolver(requestSessionId) {
         const projectRoot = this.findProjectRoot();
         this.log(`🔍 getRegistryResolver: projectRoot = ${projectRoot}`);
-        if (!projectRoot) {
-            this.log('⚠️ No project root found, override resolution disabled');
+        // Determine effective FRAIM dir using shadow semantics
+        const { getEffectiveFraimDir } = require('../core/utils/project-fraim-paths');
+        const effectiveFraimDir = projectRoot
+            ? getEffectiveFraimDir(projectRoot)
+            : getEffectiveFraimDir(process.cwd());
+        if (effectiveFraimDir) {
+            this.log(`📂 Effective FRAIM dir: ${effectiveFraimDir}`);
+        }
+        if (!projectRoot && !effectiveFraimDir) {
+            this.log('⚠️ No project root or user-level FRAIM found, override resolution disabled');
             // Return a resolver that always falls back to remote
             return new local_registry_resolver_1.LocalRegistryResolver({
                 workspaceRoot: process.cwd(),
@@ -1228,8 +1236,15 @@ class FraimLocalMCPServer {
             });
         }
         else {
+            // Determine if we need effectiveFraimDir override.
+            // If the effective dir is user-level (~/.fraim/), it's NOT under projectRoot/fraim/,
+            // so we pass it as effectiveFraimDir to bypass the getWorkspaceFraimPath logic.
+            const workspaceRoot = projectRoot || process.cwd();
+            const projectFraimDir = projectRoot ? (0, path_1.join)(projectRoot, 'fraim') : '';
+            const needsEffectiveDirOverride = effectiveFraimDir && effectiveFraimDir !== projectFraimDir;
             return new local_registry_resolver_1.LocalRegistryResolver({
-                workspaceRoot: projectRoot,
+                workspaceRoot,
+                ...(needsEffectiveDirOverride ? { effectiveFraimDir } : {}),
                 shouldFilter: (content) => this.isStub(content),
                 remoteContentResolver: async (path) => {
                     // Fetch parent content from remote for inheritance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.105",
+  "version": "2.0.106",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {