fraim 2.0.105 → 2.0.108

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)()) {
@@ -613,24 +633,49 @@ const runSetup = async (options) => {
             console.log(chalk_1.default.cyan('   To initialize a project later, cd into a repo and run: fraim init-project'));
         }
     }
-    // Show summary
-    console.log(chalk_1.default.green('\n🎯 Setup complete!'));
-    console.log(chalk_1.default.gray(`   Mode: ${mode}`));
+    // Show mode-aware summary with clear value prop and next steps
+    console.log(chalk_1.default.green('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log(chalk_1.default.green('  FRAIM is ready!'));
+    console.log(chalk_1.default.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log(chalk_1.default.white('\n  FRAIM is an AI management layer that turns you into'));
+    console.log(chalk_1.default.white('  a manager of AI agents. Run multiple agents through'));
+    console.log(chalk_1.default.white('  structured jobs, get manager-style coaching, and build'));
+    console.log(chalk_1.default.white('  a learning loop where agents improve over time.'));
+    console.log(chalk_1.default.gray('\n  60+ jobs across engineering, marketing, fundraising,'));
+    console.log(chalk_1.default.gray('  legal, product, hiring, customer development, and more.'));
+    // Show which IDEs were configured and how to use FRAIM in each
+    const { detectInstalledIDEs: detectIDEs } = await Promise.resolve().then(() => __importStar(require('../setup/ide-detector')));
+    const configuredIDEs = detectIDEs();
+    if (configuredIDEs.length > 0) {
+        const ideNames = configuredIDEs.map(ide => ide.name).join(', ');
+        console.log(chalk_1.default.cyan(`\n  FRAIM is configured for: `) + chalk_1.default.white(ideNames));
+        console.log(chalk_1.default.cyan('\n  Get started — open any of those tools and:'));
+    }
+    else {
+        console.log(chalk_1.default.cyan('\n  Get started — open your AI tool and:'));
+    }
+    // Check if Claude is among configured IDEs
+    const hasClaude = configuredIDEs.some(ide => ide.name.toLowerCase().includes('claude'));
+    if (hasClaude) {
+        console.log(chalk_1.default.white('    /fraim                           ') + chalk_1.default.gray('(Claude Code) Browse all jobs'));
+    }
+    console.log(chalk_1.default.white('    "What can FRAIM help me with?"   ') + chalk_1.default.gray('Works in any AI tool'));
+    console.log(chalk_1.default.gray('\n  Just tell your AI what you need — FRAIM will find the right job.'));
     if (mode !== 'conversational') {
+        console.log(chalk_1.default.cyan('\n  To set up FRAIM in a specific project:'));
+        console.log(chalk_1.default.white('    cd your-project && fraim init-project'));
+        console.log(chalk_1.default.gray('    This enables project-specific customizations,'));
+        console.log(chalk_1.default.gray('    GitHub workflows, and team learning.'));
         const configuredProviders = await Promise.all(Object.keys(tokens).map(async (id) => await (0, provider_registry_1.getProviderDisplayName)(id)));
-        console.log(chalk_1.default.gray(`   Platforms: ${configuredProviders.join(', ') || 'none'}`));
-    }
-    console.log(chalk_1.default.cyan('\n📝 For future projects:'));
-    console.log(chalk_1.default.cyan('   1. cd into any project directory'));
-    console.log(chalk_1.default.cyan('   2. Run: fraim init-project'));
-    console.log(chalk_1.default.cyan('   3. Ask your AI agent: "FRAIM was just installed. Read the FRAIM docs, explain what it can do for me, then run project-onboarding."'));
-    if (mode === 'integrated') {
+        if (configuredProviders.length > 0) {
+            console.log(chalk_1.default.gray(`\n  Platforms: ${configuredProviders.join(', ')}`));
+        }
         const allProviderIds = await (0, provider_registry_1.getAllProviderIds)();
         const unconfiguredProviders = allProviderIds.filter(id => !tokens[id]);
         if (unconfiguredProviders.length > 0) {
-            console.log(chalk_1.default.gray('\n💡 To add more platforms later:'));
+            console.log(chalk_1.default.gray('\n  To add more platforms later:'));
             unconfiguredProviders.forEach(id => {
-                console.log(chalk_1.default.gray(`   fraim setup --${id}`));
+                console.log(chalk_1.default.gray(`    fraim setup --${id}`));
             });
         }
     }

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,127 @@
+"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. Present the results to the user grouped by business function (the server returns jobs organized by category — use those categories as group headings). For each group, list 3-5 of the most impactful jobs with a one-line description.
+
+   After listing, suggest 2-3 starting points based on what seems most relevant:
+   - If in a code repo: suggest jobs from engineering/product-building categories
+   - If no repo context: suggest jobs from marketing, fundraising, or business categories
+
+   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,59 @@
+"use strict";
+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 Setup
+ *
+ * Ensures the user-level ~/.fraim/ directory has the minimal structure needed
+ * for FRAIM to work outside of any project:
+ *
+ * - config.json — auth, mode, tokens (managed by setup.ts)
+ * - scripts/ — locally-executed scripts (synced during any fraim sync)
+ * - personalized-employee/ — user-level overrides and learnings
+ *
+ * Job/skill/rule stubs are NOT synced to user-level. The MCP proxy serves
+ * those on demand via list_fraim_jobs() and get_fraim_job(). Stubs only exist
+ * at project-level (fraim/) where CLAUDE.md tells agents to scan them on disk.
+ *
+ * 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.
+ * Creates personalized-employee dirs for user-level overrides.
+ * Scripts dir is handled by existing script-sync-utils during any fraim sync.
+ */
+function ensureUserLevelDirectories(userFraimDir) {
+    const baseDir = userFraimDir || (0, script_sync_utils_1.getUserFraimDir)();
+    const dirs = [
+        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'),
+    ];
+    for (const dir of dirs) {
+        if (!fs_1.default.existsSync(dir)) {
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        }
+    }
+}
+/**
+ * Set up the user-level FRAIM directory.
+ * Creates the personalized-employee structure so FRAIM works outside any project.
+ *
+ * @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('📦 Setting up user-level FRAIM directory...'));
+    console.log(chalk_1.default.gray(`   Target: ${baseDir}`));
+    ensureUserLevelDirectories(baseDir);
+    console.log(chalk_1.default.green('✅ User-level FRAIM directory ready'));
+}

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.108",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {