fraim-framework 2.0.104 → 2.0.106

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

@@ -45,6 +45,7 @@ const path_1 = __importDefault(require("path"));
 const ide_detector_1 = require("../setup/ide-detector");
 const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const codex_local_config_1 = require("../setup/codex-local-config");
+const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
 const mcp_server_registry_1 = require("../mcp/mcp-server-registry");
 const get_provider_client_1 = require("../api/get-provider-client");
@@ -249,6 +250,10 @@ const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
         const status = localResult.created ? 'Created' : localResult.updated ? 'Updated' : 'Verified';
         console.log(chalk_1.default.green(`  ✅ ${status} local ${ide.name} config: ${localResult.path}`));
     }
+    // Enable token telemetry for Claude Code via project-level settings
+    if (ide.configType === 'claude-code') {
+        (0, claude_code_telemetry_1.ensureClaudeCodeTelemetryEnv)();
+    }
 };
 const listSupportedIDEs = () => {
     const allIDEs = (0, ide_detector_1.getAllSupportedIDEs)();

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

@@ -9,6 +9,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const ide_detector_1 = require("../setup/ide-detector");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
@@ -163,6 +164,28 @@ const runAddProvider = async (provider, options) => {
             }
         }
     }
+    // Check prerequisites for the provider's MCP server command
+    const providerDefCheck = await (0, provider_registry_1.getProvider)(provider);
+    if (providerDefCheck?.mcpServer?.type === 'stdio' && providerDefCheck.mcpServer.command && !process.env.FRAIM_SKIP_PREREQ_CHECK) {
+        const cmd = providerDefCheck.mcpServer.command;
+        // Only check non-standard commands (npx/node are assumed to be available)
+        if (!['npx', 'node', 'npm'].includes(cmd)) {
+            try {
+                (0, child_process_1.execSync)(`${cmd} --version`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+            }
+            catch {
+                const installInstructions = {
+                    uvx: 'Install uv first: https://docs.astral.sh/uv/getting-started/installation/\n' +
+                        '   macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh\n' +
+                        '   Windows:    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
+                };
+                console.log(chalk_1.default.red(`\n❌ "${cmd}" is required for ${providerName} but was not found on your system.\n`));
+                console.log(chalk_1.default.yellow(installInstructions[cmd] || `Please install "${cmd}" and try again.`));
+                console.log(chalk_1.default.gray('\nAfter installing, restart your terminal and run this command again.'));
+                process.exit(1);
+            }
+        }
+    }
     // Get credentials using generic prompt system
     try {
         // Build provided tokens/configs from CLI options

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

@@ -16,6 +16,7 @@ const platform_detection_1 = require("../utils/platform-detection");
 const version_utils_1 = require("../utils/version-utils");
 const ide_detector_1 = require("../setup/ide-detector");
 const codex_local_config_1 = require("../setup/codex-local-config");
+const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
 const provider_registry_1 = require("../providers/provider-registry");
 const fraim_gitignore_1 = require("../utils/fraim-gitignore");
 const config_writer_1 = require("../../core/config-writer");
@@ -323,6 +324,11 @@ const runInitProject = async () => {
         const status = codexLocalResult.created ? 'Created' : codexLocalResult.updated ? 'Updated' : 'Verified';
         console.log(chalk_1.default.green(`${status} project Codex config at ${codexLocalResult.path}`));
     }
+    // Enable token telemetry for Claude Code (user-level, applies to all projects)
+    const claudeCodeAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'claude-code');
+    if (claudeCodeAvailable) {
+        (0, claude_code_telemetry_1.ensureClaudeCodeTelemetryEnv)();
+    }
     const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot);
     if (adapterUpdates.length > 0) {
         console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));

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/claude-code-telemetry.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Configures Claude Code user-level settings for FRAIM token telemetry.
+ *
+ * Writes OTel env vars to ~/.claude/settings.json so ALL Claude Code
+ * sessions push metrics to the FRAIM local proxy's OTLP receiver.
+ * User-level so it works across all projects without per-project setup.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureClaudeCodeTelemetryEnv = ensureClaudeCodeTelemetryEnv;
+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 TELEMETRY_ENV = {
+    CLAUDE_CODE_ENABLE_TELEMETRY: '1',
+    OTEL_METRICS_EXPORTER: 'otlp',
+    OTEL_EXPORTER_OTLP_PROTOCOL: 'http/json',
+    OTEL_EXPORTER_OTLP_ENDPOINT: 'http://localhost:4318',
+};
+/**
+ * Ensure Claude Code user-level settings include OTel env vars for token telemetry.
+ * Writes to ~/.claude/settings.json. Merges without overwriting user-set values.
+ */
+function ensureClaudeCodeTelemetryEnv() {
+    const settingsDir = path_1.default.join(os_1.default.homedir(), '.claude');
+    const settingsPath = path_1.default.join(settingsDir, 'settings.json');
+    let settings = {};
+    if (fs_1.default.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs_1.default.readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            // Corrupt file — will overwrite
+        }
+    }
+    else if (!fs_1.default.existsSync(settingsDir)) {
+        fs_1.default.mkdirSync(settingsDir, { recursive: true });
+    }
+    const existingEnv = settings.env || {};
+    let added = 0;
+    for (const [key, value] of Object.entries(TELEMETRY_ENV)) {
+        if (!(key in existingEnv)) {
+            existingEnv[key] = value;
+            added++;
+        }
+    }
+    if (added > 0) {
+        settings.env = existingEnv;
+        fs_1.default.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        console.log(chalk_1.default.green(`  ✅ Enabled token telemetry in ~/.claude/settings.json (${added} env vars)`));
+    }
+    else {
+        console.log(chalk_1.default.gray(`  ⏭️ Token telemetry already configured in ~/.claude/settings.json`));
+    }
+}

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/otlp-metrics-receiver.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * Lightweight OTLP HTTP Metrics Receiver
+ *
+ * Accepts OTLP metric pushes from Claude Code when configured with:
+ *   OTEL_METRICS_EXPORTER=otlp
+ *   OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+ *   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+ *
+ * Multiple Claude Code sessions share one receiver on port 4318.
+ * Snapshots are stored per session ID and queryable via HTTP so any
+ * FRAIM proxy (not just the one that started the receiver) can fetch
+ * its own session's token data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOtlpMetrics = parseOtlpMetrics;
+exports.fetchSnapshot = fetchSnapshot;
+exports.startOtlpReceiver = startOtlpReceiver;
+exports.stopOtlpReceiver = stopOtlpReceiver;
+const http_1 = require("http");
+const DEFAULT_PORT = 4318;
+/** Stored token snapshots keyed by Claude Code session ID */
+const snapshots = new Map();
+/**
+ * Parse OTLP HTTP JSON metrics payload and extract token/cost data.
+ *
+ * OTLP JSON structure:
+ * { resourceMetrics: [{ scopeMetrics: [{ metrics: [{ name, sum: { dataPoints } }] }] }] }
+ */
+function parseOtlpMetrics(body) {
+    if (!body?.resourceMetrics)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheCreationTokens = 0;
+    let costUsd = 0;
+    let claudeSessionId = null;
+    let model = null;
+    let foundTokenMetric = false;
+    for (const rm of body.resourceMetrics) {
+        for (const sm of rm.scopeMetrics || []) {
+            for (const metric of sm.metrics || []) {
+                const dataPoints = metric.sum?.dataPoints || metric.gauge?.dataPoints || [];
+                if (metric.name === 'claude_code.token.usage') {
+                    foundTokenMetric = true;
+                    for (const dp of dataPoints) {
+                        const attrs = parseAttributes(dp.attributes);
+                        const value = Number(dp.asInt ?? dp.asDouble ?? dp.value ?? 0);
+                        switch (attrs['type']) {
+                            case 'input':
+                                inputTokens += value;
+                                break;
+                            case 'output':
+                                outputTokens += value;
+                                break;
+                            case 'cacheRead':
+                                cacheReadTokens += value;
+                                break;
+                            case 'cacheCreation':
+                                cacheCreationTokens += value;
+                                break;
+                        }
+                        claudeSessionId = attrs['session.id'] || claudeSessionId;
+                        model = attrs['model'] || model;
+                    }
+                }
+                if (metric.name === 'claude_code.cost.usage') {
+                    for (const dp of dataPoints) {
+                        const value = Number(dp.asDouble ?? dp.asInt ?? dp.value ?? 0);
+                        costUsd += value;
+                        const attrs = parseAttributes(dp.attributes);
+                        claudeSessionId = attrs['session.id'] || claudeSessionId;
+                    }
+                }
+            }
+        }
+    }
+    if (!foundTokenMetric)
+        return null;
+    return {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheCreationTokens,
+        costUsd,
+        claudeSessionId,
+        model,
+        capturedAt: new Date(),
+    };
+}
+/**
+ * Parse OTLP attribute array into a key-value map.
+ * Attributes come as: [{ key: "name", value: { stringValue: "x" } }, ...]
+ */
+function parseAttributes(attrs) {
+    const result = {};
+    if (!Array.isArray(attrs))
+        return result;
+    for (const attr of attrs) {
+        if (attr.key && attr.value) {
+            result[attr.key] = attr.value.stringValue
+                ?? attr.value.intValue
+                ?? attr.value.doubleValue
+                ?? String(attr.value.value ?? '');
+        }
+    }
+    return result;
+}
+/**
+ * Parse URL query string into key-value pairs.
+ */
+function parseQuery(url) {
+    const idx = url.indexOf('?');
+    if (idx < 0)
+        return {};
+    const params = {};
+    for (const part of url.slice(idx + 1).split('&')) {
+        const [key, val] = part.split('=');
+        if (key)
+            params[decodeURIComponent(key)] = decodeURIComponent(val || '');
+    }
+    return params;
+}
+/**
+ * Handle incoming HTTP requests.
+ */
+function handleRequest(req, res) {
+    const url = req.url || '';
+    const pathname = url.split('?')[0];
+    // OTLP metrics push endpoint
+    if (req.method === 'POST' && pathname === '/v1/metrics') {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk; });
+        req.on('end', () => {
+            try {
+                const parsed = JSON.parse(body);
+                const snapshot = parseOtlpMetrics(parsed);
+                if (snapshot && snapshot.claudeSessionId) {
+                    snapshots.set(snapshot.claudeSessionId, snapshot);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end('{}');
+            }
+            catch {
+                res.writeHead(400);
+                res.end('{"error":"invalid json"}');
+            }
+        });
+        return;
+    }
+    // Query snapshot — used by any FRAIM proxy to fetch token data
+    // ?sessionId=X returns that session's snapshot
+    // ?latest=true returns the most recently updated snapshot
+    if (req.method === 'GET' && pathname === '/v1/snapshot') {
+        const query = parseQuery(url);
+        let snapshot;
+        if (query['sessionId']) {
+            snapshot = snapshots.get(query['sessionId']);
+        }
+        else {
+            // Return most recently captured snapshot across all sessions
+            let latest;
+            for (const s of snapshots.values()) {
+                if (!latest || s.capturedAt > latest.capturedAt) {
+                    latest = s;
+                }
+            }
+            snapshot = latest;
+        }
+        if (snapshot) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(snapshot));
+        }
+        else {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end('{"error":"no snapshot available"}');
+        }
+        return;
+    }
+    // Health check
+    if (req.method === 'GET' && pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            status: 'ok',
+            sessionCount: snapshots.size,
+            sessions: [...snapshots.keys()],
+        }));
+        return;
+    }
+    res.writeHead(404);
+    res.end('');
+}
+/**
+ * Fetch a token snapshot from the OTLP receiver via HTTP.
+ * Works whether this process owns the receiver or another proxy does.
+ *
+ * @param sessionId If provided, fetches that specific session's snapshot.
+ *                  If omitted, fetches the most recently updated snapshot.
+ * @param log Optional logging function
+ */
+async function fetchSnapshot(sessionId, log) {
+    const port = parseInt(process.env.FRAIM_OTLP_PORT || String(DEFAULT_PORT), 10);
+    const query = sessionId ? `?sessionId=${encodeURIComponent(sessionId)}` : '';
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        const resp = await fetch(`http://127.0.0.1:${port}/v1/snapshot${query}`, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        if (data.inputTokens !== undefined) {
+            return {
+                ...data,
+                capturedAt: new Date(data.capturedAt),
+            };
+        }
+        return null;
+    }
+    catch {
+        log?.('OTLP receiver not reachable — no token snapshot available');
+        return null;
+    }
+}
+/**
+ * Start the OTLP metrics receiver HTTP server.
+ * Only one receiver runs per machine — if port is in use, that's fine;
+ * this proxy will query the existing receiver via HTTP.
+ *
+ * @param log Optional logging function
+ * @returns Server info if started, null if port was in use (not an error)
+ */
+function startOtlpReceiver(log) {
+    const port = parseInt(process.env.FRAIM_OTLP_PORT || String(DEFAULT_PORT), 10);
+    try {
+        const server = (0, http_1.createServer)(handleRequest);
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                log?.(`OTLP receiver: port ${port} in use — will query existing receiver via HTTP`);
+            }
+            else {
+                log?.(`OTLP receiver error: ${err.message}`);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            log?.(`OTLP metrics receiver listening on http://127.0.0.1:${port}/v1/metrics`);
+        });
+        return { server, port };
+    }
+    catch (err) {
+        log?.(`Failed to start OTLP receiver: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Stop the OTLP receiver and clear stored snapshots.
+ */
+function stopOtlpReceiver(server) {
+    server.close();
+    snapshots.clear();
+}

package/dist/src/local-mcp-server/prometheus-scraper.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Prometheus Scraper for Claude Code OTel Token Usage Metrics
+ *
+ * Scrapes Claude Code's local Prometheus endpoint to capture cumulative
+ * token usage counters. Returns raw snapshot values — delta computation
+ * happens server-side per architecture constraint 15.2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePrometheusText = parsePrometheusText;
+exports.extractTokenSnapshot = extractTokenSnapshot;
+exports.scrapeTokenSnapshot = scrapeTokenSnapshot;
+/** Candidate Prometheus endpoint ports (OTel SDK defaults) */
+const CANDIDATE_PORTS = [9464, 8888];
+/** Candidate metric names for token usage (OTel dots→underscores, optional suffixes) */
+const TOKEN_METRIC_CANDIDATES = [
+    'claude_code_token_usage_total',
+    'claude_code_token_usage',
+    'claude_code_token_usage_tokens_total',
+    'claude_code_token_usage_tokens',
+];
+/** Candidate metric names for cost usage */
+const COST_METRIC_CANDIDATES = [
+    'claude_code_cost_usage_total',
+    'claude_code_cost_usage',
+    'claude_code_cost_usage_usd_total',
+    'claude_code_cost_usage_usd',
+];
+/**
+ * Parse Prometheus text exposition format into structured metrics.
+ *
+ * Format per line:  metric_name{label1="val1",label2="val2"} value [timestamp]
+ * Lines starting with # are comments (HELP, TYPE). Empty lines are skipped.
+ */
+function parsePrometheusText(text) {
+    const results = [];
+    for (const line of text.split('\n')) {
+        if (line.startsWith('#') || line.trim() === '')
+            continue;
+        // Match: metric_name{labels} value
+        const labeledMatch = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)\{([^}]*)\}\s+([\d.eE+-]+)/);
+        if (labeledMatch) {
+            const [, name, labelsStr, valueStr] = labeledMatch;
+            const labels = {};
+            for (const pair of labelsStr.matchAll(/(\w+)="([^"]*)"/g)) {
+                labels[pair[1]] = pair[2];
+            }
+            results.push({ name, labels, value: parseFloat(valueStr) });
+            continue;
+        }
+        // Match: metric_name value (no labels)
+        const noLabelMatch = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)\s+([\d.eE+-]+)/);
+        if (noLabelMatch) {
+            const [, name, valueStr] = noLabelMatch;
+            results.push({ name, labels: {}, value: parseFloat(valueStr) });
+        }
+    }
+    return results;
+}
+/**
+ * Extract a TokenSnapshot from parsed Prometheus metrics.
+ * Tries multiple candidate metric names for resilience to SDK version changes.
+ */
+function extractTokenSnapshot(metrics) {
+    const snapshot = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        costUsd: 0,
+        claudeSessionId: null,
+        model: null,
+        capturedAt: new Date(),
+    };
+    for (const m of metrics) {
+        if (TOKEN_METRIC_CANDIDATES.includes(m.name)) {
+            const type = m.labels['type'];
+            switch (type) {
+                case 'input':
+                    snapshot.inputTokens = m.value;
+                    break;
+                case 'output':
+                    snapshot.outputTokens = m.value;
+                    break;
+                case 'cacheRead':
+                    snapshot.cacheReadTokens = m.value;
+                    break;
+                case 'cacheCreation':
+                    snapshot.cacheCreationTokens = m.value;
+                    break;
+            }
+            snapshot.claudeSessionId = m.labels['session_id'] || snapshot.claudeSessionId;
+            snapshot.model = m.labels['model'] || snapshot.model;
+        }
+        if (COST_METRIC_CANDIDATES.includes(m.name)) {
+            snapshot.costUsd += m.value;
+            snapshot.claudeSessionId = m.labels['session_id'] || snapshot.claudeSessionId;
+        }
+    }
+    return snapshot;
+}
+/**
+ * Attempt to fetch Prometheus metrics from a candidate endpoint.
+ * Returns response text or null on failure.
+ */
+async function tryFetch(port, timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const resp = await fetch(`http://localhost:${port}/metrics`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (resp.ok) {
+            return await resp.text();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scrape Claude Code's Prometheus endpoint and return a TokenSnapshot.
+ *
+ * Returns null if:
+ * - Prometheus endpoint is not available (OTel not enabled)
+ * - Scrape times out (>2s by default)
+ * - No matching token metrics found
+ *
+ * @param log Optional logging function for debug output
+ */
+async function scrapeTokenSnapshot(log) {
+    const configuredPort = process.env.FRAIM_PROMETHEUS_PORT;
+    const ports = configuredPort ? [parseInt(configuredPort, 10)] : CANDIDATE_PORTS;
+    const timeoutMs = 2000;
+    for (const port of ports) {
+        const text = await tryFetch(port, timeoutMs);
+        if (text && text.includes('#')) {
+            const metrics = parsePrometheusText(text);
+            const snapshot = extractTokenSnapshot(metrics);
+            // Only return if we actually found token metrics
+            if (snapshot.inputTokens > 0 || snapshot.outputTokens > 0) {
+                log?.(`Captured token snapshot from localhost:${port} (input=${snapshot.inputTokens}, output=${snapshot.outputTokens})`);
+                return snapshot;
+            }
+            log?.(`Prometheus endpoint found at localhost:${port} but no token metrics matched`);
+        }
+    }
+    log?.('No Prometheus endpoint available — token snapshot skipped');
+    return null;
+}

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

@@ -31,6 +31,7 @@ const local_registry_resolver_1 = require("../core/utils/local-registry-resolver
 const ai_mentor_1 = require("../core/ai-mentor");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
+const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
 /**
  * Handle template substitution logic separately for better testability
@@ -398,6 +399,7 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
+        this.otlpServer = null;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -415,6 +417,8 @@ class FraimLocalMCPServer {
         // Initialize usage collector
         this.usageCollector = new usage_collector_js_1.UsageCollector();
         this.log('📊 Usage analytics collector initialized');
+        // Start OTLP metrics receiver for Claude Code token telemetry
+        this.otlpServer = (0, otlp_metrics_receiver_js_1.startOtlpReceiver)((msg) => this.log(`📊 ${msg}`));
     }
     /**
      * Load API key from environment variable or user config file
@@ -1212,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(),
@@ -1224,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
@@ -1824,6 +1843,9 @@ class FraimLocalMCPServer {
         const cleanup = () => {
             clearInterval(uploadInterval);
             this.usageCollector.shutdown();
+            if (this.otlpServer?.server) {
+                (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
+            }
         };
         process.stdin.on('data', async (chunk) => {
             buffer += chunk;
@@ -1843,7 +1865,7 @@ class FraimLocalMCPServer {
                             // Only send response if we got one (null means we handled it internally)
                             if (response) {
                                 // Collect usage for all tools/call requests before sending response
-                                this.collectUsageForResponse(message, response);
+                                await this.collectUsageForResponse(message, response);
                                 process.stdout.write(JSON.stringify(response) + '\n');
                             }
                         }
@@ -1900,7 +1922,7 @@ class FraimLocalMCPServer {
     /**
      * Collect usage analytics for tools/call requests
      */
-    collectUsageForResponse(request, response) {
+    async collectUsageForResponse(request, response) {
         // Only collect usage for tools/call requests
         if (request.method !== 'tools/call') {
             return;
@@ -1919,6 +1941,19 @@ class FraimLocalMCPServer {
                 const afterCount = this.usageCollector.getEventCount();
                 if (afterCount > beforeCount) {
                     this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
+                    // Fetch token snapshot from OTLP receiver for seekMentoring calls
+                    if (toolName === 'seekMentoring') {
+                        try {
+                            const snapshot = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(undefined, (msg) => this.log(`📊 ${msg}`));
+                            if (snapshot) {
+                                this.usageCollector.attachTokenSnapshot(snapshot);
+                                this.log(`📊 🔢 Token snapshot attached (input=${snapshot.inputTokens}, output=${snapshot.outputTokens}, session=${snapshot.claudeSessionId})`);
+                            }
+                        }
+                        catch (err) {
+                            this.log(`📊 ⚠️ Token snapshot fetch failed (non-blocking): ${err.message}`);
+                        }
+                    }
                 }
                 else {
                     this.log(`📊 ⚠️ Event not queued - tool may not be tracked: ${toolName}`);

package/dist/src/local-mcp-server/usage-collector.js

@@ -163,6 +163,15 @@ class UsageCollector {
         this.events = [];
         return eventsToUpload;
     }
+    /**
+     * Attach a token snapshot to the most recently queued event.
+     * Used to associate Prometheus-scraped token data with seekMentoring events.
+     */
+    attachTokenSnapshot(snapshot) {
+        if (this.events.length > 0) {
+            this.events[this.events.length - 1].tokenSnapshot = snapshot;
+        }
+    }
     /**
      * Get current event count
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.104",
+  "version": "2.0.106",
   "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": {