fraim 2.0.207 → 2.0.209

package/bin/fraim.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 try {
   require('../dist/src/cli/fraim.js');

package/dist/src/cli/commands/test-mcp.js

@@ -0,0 +1,171 @@
+"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.testMCPCommand = exports.runTestMCP = void 0;
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ide_detector_1 = require("../setup/ide-detector");
+const script_sync_utils_1 = require("../utils/script-sync-utils");
+const testIDEConfig = async (ide) => {
+    const result = {
+        ide: ide.name,
+        configExists: false,
+        configValid: false,
+        mcpServers: [],
+        errors: []
+    };
+    const configPath = (0, ide_detector_1.expandPath)(ide.configPath);
+    if (!fs_1.default.existsSync(configPath)) {
+        result.errors.push('Config file does not exist');
+        return result;
+    }
+    result.configExists = true;
+    try {
+        if (ide.configFormat === 'json') {
+            const configContent = fs_1.default.readFileSync(configPath, 'utf8');
+            const config = JSON.parse(configContent);
+            const servers = ide.configType === 'vscode' ? config.servers : config.mcpServers;
+            if (servers) {
+                result.configValid = true;
+                result.mcpServers = Object.keys(servers);
+            }
+            else {
+                const expectedKey = ide.configType === 'vscode' ? 'servers' : 'mcpServers';
+                result.errors.push(`No ${expectedKey} section found`);
+            }
+        }
+        else if (ide.configFormat === 'toml') {
+            const configContent = fs_1.default.readFileSync(configPath, 'utf8');
+            // Simple TOML parsing for MCP servers
+            const serverMatches = configContent.match(/\[mcp_servers\.(\w+)\]/g);
+            if (serverMatches) {
+                result.configValid = true;
+                result.mcpServers = serverMatches.map(match => match.replace(/\[mcp_servers\.(\w+)\]/, '$1'));
+            }
+            else {
+                result.errors.push('No mcp_servers sections found');
+            }
+        }
+    }
+    catch (error) {
+        result.errors.push(`Failed to parse config: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    return result;
+};
+const checkGlobalSetup = () => {
+    const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
+    return fs_1.default.existsSync(globalConfigPath);
+};
+const runTestMCP = async () => {
+    console.log(chalk_1.default.blue('🔍 Testing MCP configuration...\n'));
+    // Check global setup
+    if (!checkGlobalSetup()) {
+        console.log(chalk_1.default.red('❌ Global FRAIM setup not found.'));
+        console.log(chalk_1.default.yellow('Please run: fraim setup --key=<your-fraim-key>'));
+        return;
+    }
+    console.log(chalk_1.default.green('✅ Global FRAIM setup found'));
+    // Detect IDEs
+    const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
+    if (detectedIDEs.length === 0) {
+        console.log(chalk_1.default.yellow('⚠️ No supported IDEs detected.'));
+        return;
+    }
+    console.log(chalk_1.default.blue(`\n🔍 Testing ${detectedIDEs.length} detected IDEs...\n`));
+    const results = await Promise.all(detectedIDEs.map(ide => testIDEConfig(ide)));
+    let totalConfigured = 0;
+    let totalWithFRAIM = 0;
+    for (const result of results) {
+        console.log(chalk_1.default.white(`📱 ${result.ide}`));
+        if (!result.configExists) {
+            console.log(chalk_1.default.red('   ❌ No MCP config found'));
+            console.log(chalk_1.default.gray(`   💡 Run: fraim setup --ide=${result.ide.toLowerCase()}`));
+        }
+        else if (!result.configValid) {
+            console.log(chalk_1.default.yellow('   ⚠️ Config exists but invalid'));
+            result.errors.forEach(error => {
+                console.log(chalk_1.default.red(`   ❌ ${error}`));
+            });
+        }
+        else {
+            totalConfigured++;
+            console.log(chalk_1.default.green(`   ✅ MCP config valid (${result.mcpServers.length} servers)`));
+            // Check for essential servers
+            const { BASE_MCP_SERVERS } = await Promise.resolve().then(() => __importStar(require('../mcp/mcp-server-registry')));
+            const essentialServers = BASE_MCP_SERVERS.map(s => s.id); // fraim, git, playwright
+            const hasEssential = essentialServers.filter(server => result.mcpServers.includes(server));
+            if (hasEssential.includes('fraim')) {
+                totalWithFRAIM++;
+                console.log(chalk_1.default.green('   ✅ FRAIM server configured'));
+            }
+            else {
+                console.log(chalk_1.default.yellow('   ⚠️ FRAIM server missing'));
+            }
+            if (hasEssential.length > 1) {
+                console.log(chalk_1.default.green(`   ✅ ${hasEssential.length - 1} additional servers: ${hasEssential.filter(s => s !== 'fraim').join(', ')}`));
+            }
+            const missingEssential = essentialServers.filter(server => !result.mcpServers.includes(server));
+            if (missingEssential.length > 0) {
+                console.log(chalk_1.default.yellow(`   ⚠️ Missing servers: ${missingEssential.join(', ')}`));
+            }
+        }
+        console.log(); // Empty line
+    }
+    // Summary
+    console.log(chalk_1.default.blue('📊 Summary:'));
+    console.log(chalk_1.default.green(`   ✅ ${totalConfigured}/${detectedIDEs.length} IDEs have valid MCP configs`));
+    console.log(chalk_1.default.green(`   ✅ ${totalWithFRAIM}/${detectedIDEs.length} IDEs have FRAIM configured`));
+    if (totalWithFRAIM === 0) {
+        console.log(chalk_1.default.red('\n❌ No IDEs have FRAIM configured!'));
+        console.log(chalk_1.default.yellow('💡 Run: fraim setup --key=<your-fraim-key>'));
+    }
+    else if (totalWithFRAIM < detectedIDEs.length) {
+        console.log(chalk_1.default.yellow(`\n⚠️ ${detectedIDEs.length - totalWithFRAIM} IDEs missing FRAIM configuration`));
+        console.log(chalk_1.default.yellow('💡 Run: fraim setup to configure remaining IDEs'));
+    }
+    else {
+        console.log(chalk_1.default.green('\n🎉 All detected IDEs have FRAIM configured!'));
+        console.log(chalk_1.default.blue('💡 Try running: fraim init-project in any project'));
+    }
+};
+exports.runTestMCP = runTestMCP;
+exports.testMCPCommand = new commander_1.Command('test-mcp')
+    .description('Test MCP server configurations for all detected IDEs')
+    .action(exports.runTestMCP);

package/dist/src/cli/setup/first-run.js

@@ -0,0 +1,242 @@
+"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.runFirstRunExperience = void 0;
+const prompts_1 = __importDefault(require("prompts"));
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const script_sync_utils_1 = require("../utils/script-sync-utils");
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const loadGlobalConfig = () => {
+    const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
+    if (!fs_1.default.existsSync(globalConfigPath)) {
+        return null;
+    }
+    try {
+        const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
+        return {
+            fraimKey: config.apiKey,
+            githubToken: config.githubToken
+        };
+    }
+    catch (e) {
+        return null;
+    }
+};
+const checkMCPConfigurations = () => {
+    const sources = [];
+    // Check Kiro MCP config
+    const kiroConfigPath = path_1.default.join(os_1.default.homedir(), '.kiro', 'settings', 'mcp.json');
+    if (fs_1.default.existsSync(kiroConfigPath)) {
+        try {
+            const kiroConfig = JSON.parse(fs_1.default.readFileSync(kiroConfigPath, 'utf8'));
+            if (kiroConfig.mcpServers?.fraim) {
+                sources.push('Kiro');
+            }
+        }
+        catch (e) {
+            // Ignore parsing errors
+        }
+    }
+    // Check Claude Desktop / Cowork config
+    const claudeConfigPath = path_1.default.join(os_1.default.homedir(), 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+    if (fs_1.default.existsSync(claudeConfigPath)) {
+        try {
+            const claudeConfig = JSON.parse(fs_1.default.readFileSync(claudeConfigPath, 'utf8'));
+            if (claudeConfig.mcpServers?.fraim) {
+                sources.push('Claude Desktop / Cowork');
+            }
+        }
+        catch (e) {
+            // Ignore parsing errors
+        }
+    }
+    // Check macOS Claude Desktop / Cowork config path
+    const claudeMacPath = path_1.default.join(os_1.default.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    if (fs_1.default.existsSync(claudeMacPath)) {
+        try {
+            const claudeConfig = JSON.parse(fs_1.default.readFileSync(claudeMacPath, 'utf8'));
+            if (claudeConfig.mcpServers?.fraim) {
+                sources.push('Claude Desktop / Cowork (macOS)');
+            }
+        }
+        catch (e) {
+            // Ignore parsing errors
+        }
+    }
+    // Check VS Code MCP config (uses "servers" key)
+    const vscodePaths = [
+        path_1.default.join(os_1.default.homedir(), 'AppData', 'Roaming', 'Code', 'User', 'mcp.json'),
+        path_1.default.join(os_1.default.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json'),
+        path_1.default.join(os_1.default.homedir(), '.config', 'Code', 'User', 'mcp.json')
+    ];
+    for (const vscodePath of vscodePaths) {
+        if (fs_1.default.existsSync(vscodePath)) {
+            try {
+                const vscodeConfig = JSON.parse(fs_1.default.readFileSync(vscodePath, 'utf8'));
+                if (vscodeConfig.servers?.fraim) {
+                    sources.push('VSCode');
+                    break;
+                }
+            }
+            catch (e) {
+                // Ignore parsing errors
+            }
+        }
+    }
+    return {
+        found: sources.length > 0,
+        sources
+    };
+};
+const runFirstRunExperience = async () => {
+    // Skip interactive setup in CI/Test environments
+    if (process.env.CI === 'true' || process.env.TEST_MODE === 'true') {
+        console.log(chalk_1.default.yellow('ℹ️  Skipping interactive first-run experience (CI/TEST_MODE detected)'));
+        return;
+    }
+    console.log(chalk_1.default.blue('\n👋 Welcome to FRAIM! Let\'s get you set up.\n'));
+    // Check for existing configuration
+    const globalConfig = loadGlobalConfig();
+    const mcpCheck = checkMCPConfigurations();
+    if (globalConfig && globalConfig.fraimKey) {
+        console.log(chalk_1.default.green('✅ Found existing FRAIM configuration'));
+        if (mcpCheck.found) {
+            console.log(chalk_1.default.green(`✅ Found FRAIM MCP configuration in: ${mcpCheck.sources.join(', ')}`));
+            console.log(chalk_1.default.blue('🎉 You\'re all set! FRAIM is ready to use.\n'));
+        }
+        else {
+            console.log(chalk_1.default.yellow('⚠️  FRAIM key found but no MCP configuration detected.'));
+            console.log(chalk_1.default.cyan('💡 Consider running "fraim add-ide" to configure your IDE.\n'));
+        }
+    }
+    else if (mcpCheck.found) {
+        console.log(chalk_1.default.green(`✅ Found FRAIM MCP configuration in: ${mcpCheck.sources.join(', ')}`));
+        console.log(chalk_1.default.yellow('⚠️  But no global FRAIM configuration found.'));
+        console.log(chalk_1.default.cyan('💡 Your MCP setup looks good! Skipping key setup.\n'));
+    }
+    else {
+        // No existing configuration found - ask for FRAIM key
+        console.log(chalk_1.default.yellow('🔍 No existing FRAIM configuration detected.\n'));
+        let response;
+        try {
+            response = await (0, prompts_1.default)({
+                type: 'text',
+                name: 'fraimKey',
+                message: 'Do you have a FRAIM key? (Input key or press Enter to skip)',
+                validate: (value) => true // Optional input
+            });
+        }
+        catch (e) {
+            console.warn(chalk_1.default.yellow('\n⚠️  Interactive prompts experienced an issue. Skipping setup.\n'));
+            return;
+        }
+        if (response.fraimKey && response.fraimKey.trim().length > 0) {
+            const key = response.fraimKey.trim();
+            console.log(chalk_1.default.green('\n✅ Key received.'));
+            console.log(chalk_1.default.yellow('\nPlease add the following to your IDE\'s MCP config (e.g. claude_desktop_config.json):'));
+            const mcpConfig = {
+                mcpServers: {
+                    fraim: {
+                        serverUrl: "https://fraim.wellnessatwork.me",
+                        headers: {
+                            "x-api-key": key
+                        }
+                    }
+                }
+            };
+            console.log(chalk_1.default.cyan(JSON.stringify(mcpConfig, null, 2)));
+            console.log('\n');
+        }
+        else {
+            console.log(chalk_1.default.yellow('\nℹ️  If you need a key, please email sid.mathur@gmail.com to request one.\n'));
+        }
+    }
+    // 2. Ask about Architecture Document
+    const archResponse = await (0, prompts_1.default)({
+        type: 'confirm',
+        name: 'hasArchDoc',
+        message: 'Do you have an architecture document for this project?',
+        initial: false
+    });
+    if (!archResponse.hasArchDoc) {
+        console.log(chalk_1.default.yellow('\n💡 To create an architecture document, please ask your IDE Agent:'));
+        console.log(chalk_1.default.cyan('  "Run the bootstrap/create-architecture workflow"'));
+        console.log(chalk_1.default.gray('  (This ensures your agent understands your codebase structure)\n'));
+    }
+    else {
+        const pathResponse = await (0, prompts_1.default)({
+            type: 'text',
+            name: 'archDocPath',
+            message: 'Please provide the relative path to your architecture document:',
+            initial: 'docs/architecture.md',
+            validate: (value) => value.length > 0 ? true : 'Path cannot be empty'
+        });
+        if (pathResponse.archDocPath) {
+            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+            const path = await Promise.resolve().then(() => __importStar(require('path')));
+            const resolvedPath = path.resolve(process.cwd(), pathResponse.archDocPath);
+            if (fs.existsSync(resolvedPath)) {
+                try {
+                    const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(process.cwd());
+                    if (fs.existsSync(configPath)) {
+                        const configContent = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                        if (!configContent.customizations)
+                            configContent.customizations = {};
+                        configContent.customizations.architectureDoc = pathResponse.archDocPath;
+                        fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+                        console.log(chalk_1.default.green(`\n✅ Linked architecture document: ${pathResponse.archDocPath}`));
+                    }
+                    else {
+                        console.log(chalk_1.default.red(`\n❌ ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')} not found. Could not save preference.`));
+                    }
+                }
+                catch (e) {
+                    console.error(chalk_1.default.red('\n❌ Failed to update config:'), e);
+                }
+            }
+            else {
+                console.log(chalk_1.default.yellow(`\n⚠️  File not found at ${pathResponse.archDocPath}. We'll skip linking it for now.`));
+            }
+        }
+    }
+    console.log(chalk_1.default.green(`\n✅ Jobs are installed in ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-employee/jobs')} and ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-manager/jobs')}.\n`));
+};
+exports.runFirstRunExperience = runFirstRunExperience;

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -56,17 +56,20 @@ function buildDeferredToolBootstrapSection(profile) {
 function buildFraimInvocationBody(profile = 'none') {
     return `Follow this process:
 
-${buildDeferredToolBootstrapSection(profile)}1. **If the user did not specify a FRAIM job or topic**:
+${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
+   Use this process only when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job. For ordinary requests, answer or work normally; do not scan FRAIM stubs first.
+
+2. **If the user did not specify a FRAIM job or topic after activation**:
    If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
-2. **Find the match**:
-   Match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no job matches, try a likely FRAIM skill with \`get_fraim_file({ path: "skills/<likely-category>/<argument>.md" })\` and confirm the match with the user.
+3. **Find the match**:
+   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification. Do not pick the nearest catalog job.
 
-3. **Load the full content**:
+4. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.
    - For skills, use the content returned by \`get_fraim_file(...)\`.
 
-4. **Execute**:
+5. **Execute**:
    - For jobs, follow the phased instructions and use \`seekMentoring\` when the job requires phase transitions.
    - For skills, apply the skill steps directly to the user's current context.
 `;

package/dist/src/cli/utils/agent-adapters.js

@@ -69,8 +69,12 @@ This repository uses FRAIM.
 - Skills under \`${employeeSkillsPath}/\` are reusable capabilities that jobs compose.
 - Rules under \`${employeeRulesPath}/\` are always-on constraints and conventions.
 - Repo-specific overrides and learning artifacts live under \`${personalizedRootPath}/\` and take precedence over synced baseline content.
-- Before acting on any user request, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections to match the request to the right job.
+- Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.
+- For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.
+- If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly.
+- When FRAIM routing is active but the job is not exact, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections before using catalog tools.
 - Once you identify the relevant job, call \`get_fraim_job({ job: "<job-name>" })\` to get the full phased instructions.
+- If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.
 - For deeper capability detail, call \`get_fraim_file({ path: "skills/<category>/<skill-name>.md" })\` or \`get_fraim_file({ path: "rules/<category>/<rule-name>.md" })\`.
 - Read \`${projectRulesPath}\` if it exists before doing work.
 - When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
@@ -91,7 +95,11 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 - FRAIM skills are reusable capabilities jobs compose.
 - FRAIM rules are always-on constraints and conventions.
 - Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
-- Use the stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.
+- For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.
+- If the user names an exact FRAIM job, fetch that full job directly with FRAIM MCP tools.
+- When FRAIM routing is active but the job is not exact, use local stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.
 - **Job stubs are for discovery only.** Never execute a job from stub content - always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const fraimReadme = `# FRAIM Catalog
@@ -104,7 +112,7 @@ This directory is the repository-visible FRAIM surface.
 - \`ai-employee/rules/\`: rule stubs
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
-Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools.
+When FRAIM routing is active and no exact FRAIM job is named, use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.
 `;
     const vscodePrompt = `# FRAIM
 

package/dist/src/core/config-writer.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFraimConfigRaw = readFraimConfigRaw;
+exports.mergeFraimConfig = mergeFraimConfig;
+exports.writeFraimConfigUpdate = writeFraimConfigUpdate;
+exports.writeFraimConfig = writeFraimConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_loader_1 = require("./config-loader");
+const types_1 = require("./types");
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepMerge(baseValue, updateValue) {
+    if (updateValue === undefined) {
+        return baseValue;
+    }
+    if (Array.isArray(updateValue)) {
+        return [...updateValue];
+    }
+    if (!isPlainObject(updateValue)) {
+        return updateValue;
+    }
+    const baseObject = isPlainObject(baseValue) ? baseValue : {};
+    const merged = { ...baseObject };
+    for (const [key, value] of Object.entries(updateValue)) {
+        merged[key] = deepMerge(baseObject[key], value);
+    }
+    return merged;
+}
+function ensureWritableFraimConfigShape(rawConfig) {
+    const config = { ...rawConfig };
+    if (typeof config.version !== 'string' || config.version.trim().length === 0) {
+        config.version = types_1.DEFAULT_FRAIM_CONFIG.version;
+    }
+    const projectConfig = isPlainObject(config.project) ? config.project : {};
+    config.project = {
+        ...types_1.DEFAULT_FRAIM_CONFIG.project,
+        ...projectConfig
+    };
+    const customizationsConfig = isPlainObject(config.customizations) ? config.customizations : {};
+    config.customizations = {
+        ...types_1.DEFAULT_FRAIM_CONFIG.customizations,
+        ...customizationsConfig
+    };
+    return config;
+}
+function readFraimConfigRaw(configPath) {
+    if (!(0, fs_1.existsSync)(configPath)) {
+        return {};
+    }
+    const parsed = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    if (!isPlainObject(parsed)) {
+        throw new Error('FRAIM config must contain a JSON object at the top level.');
+    }
+    return parsed;
+}
+function mergeFraimConfig(existingRawConfig, update) {
+    const rawConfig = ensureWritableFraimConfigShape(deepMerge(existingRawConfig, update));
+    return {
+        config: (0, config_loader_1.normalizeFraimConfig)(rawConfig),
+        created: Object.keys(existingRawConfig).length === 0,
+        rawConfig
+    };
+}
+function writeFraimConfigUpdate(configPath, update) {
+    const existingRawConfig = readFraimConfigRaw(configPath);
+    const result = mergeFraimConfig(existingRawConfig, update);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(configPath), { recursive: true });
+    (0, fs_1.writeFileSync)(configPath, JSON.stringify(result.rawConfig, null, 2));
+    return result;
+}
+function writeFraimConfig(configPath, config) {
+    return writeFraimConfigUpdate(configPath, config);
+}

package/dist/src/core/utils/job-aliases.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPRECATED_FRAIM_JOB_NAMES = void 0;
+exports.resolveFraimJobName = resolveFraimJobName;
+exports.isListableFraimJob = isListableFraimJob;
+const DEPRECATED_TO_CANONICAL_JOB_MAP = {
+    'learn-and-scale': 'upskill-employee',
+    'model-behavior': 'upskill-employee',
+    'promote-learning': 'upskill-employee',
+    'refine-jobs': 'upskill-employee',
+    'refine-skills': 'upskill-employee'
+};
+const DIRECT_JOB_ALIASES = {
+    'sleep on learnings': 'sleep-on-learnings'
+};
+exports.DEPRECATED_FRAIM_JOB_NAMES = new Set(Object.keys(DEPRECATED_TO_CANONICAL_JOB_MAP));
+function normalizeJobLookupInput(input) {
+    return input.trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+function resolveFraimJobName(input) {
+    const normalizedJobName = normalizeJobLookupInput(input);
+    const directAliasTarget = DIRECT_JOB_ALIASES[input.trim().toLowerCase()];
+    if (directAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: directAliasTarget
+        };
+    }
+    const deprecatedAliasTarget = DEPRECATED_TO_CANONICAL_JOB_MAP[normalizedJobName];
+    if (deprecatedAliasTarget) {
+        return {
+            requestedJobName: input,
+            normalizedJobName,
+            canonicalJobName: deprecatedAliasTarget,
+            deprecatedAliasTarget
+        };
+    }
+    return {
+        requestedJobName: input,
+        normalizedJobName,
+        canonicalJobName: normalizedJobName
+    };
+}
+function isListableFraimJob(jobName) {
+    return !exports.DEPRECATED_FRAIM_JOB_NAMES.has(normalizeJobLookupInput(jobName));
+}