fraim-framework 2.0.36 → 2.0.37

package/dist/registry/scripts/performance/profile-server.js

@@ -0,0 +1,390 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fraim_config_1 = require("../fraim-config");
+const azureConfig = fraim_config_1.fraimConfig.azure;
+const CONFIGS = {
+    prod: {
+        env: 'prod',
+        appName: azureConfig.prodAppName,
+        resourceGroup: azureConfig.prodResourceGroup
+    },
+    preprod: {
+        env: 'preprod',
+        appName: azureConfig.preprodAppName,
+        resourceGroup: azureConfig.preprodResourceGroup
+    },
+    local: {
+        env: 'local',
+        appName: azureConfig.localAppName,
+        resourceGroup: azureConfig.localResourceGroup
+    }
+};
+async function main() {
+    const args = process.argv.slice(2);
+    let config = CONFIGS.local;
+    const includeLogs = args.includes('--logs');
+    if (args.includes('--prod'))
+        config = CONFIGS.prod;
+    else if (args.includes('--preprod'))
+        config = CONFIGS.preprod;
+    else if (args.includes('--local')) {
+        console.log('🔍 Running in local mode (log analysis only)');
+        config = CONFIGS.local;
+    }
+    else {
+        console.log('⚠️ No environment specified.');
+        console.log('Usage: npx tsx <this-script> [--prod|--preprod|--local] [--logs]');
+        return;
+    }
+    console.log(`\n🚀 Starting Profiling for Environment: ${config.env.toUpperCase()}`);
+    // 1. Infrastructure (Step 1)
+    if (config.env !== 'local') {
+        try {
+            console.log('\n--- ☁️ Step 1: Server Resource Analysis (Plan Level) ---');
+            // Get App Service Plan ID
+            const planId = (0, child_process_1.execSync)(`az webapp show --name ${config.appName} --resource-group ${config.resourceGroup} --query "appServicePlanId" -o tsv`).toString().trim();
+            console.log(`Plan ID: ${planId.split('/').pop()}`);
+            // 1a. Overall Metric (Plan Level)
+            // Get last 5 minutes of CPU/Memory
+            console.log(`> Fetching Plan Metrics (Last 5m)...`);
+            const metricCmd = `az monitor metrics list --resource "${planId}" --metrics CpuPercentage MemoryPercentage --interval PT1M --query "value[].{name:name.value, average:timeseries[0].data[-1].average}" -o json`;
+            try {
+                const metrics = JSON.parse((0, child_process_1.execSync)(metricCmd).toString());
+                metrics.forEach((m) => {
+                    console.log(`${m.name}: ${m.average != null ? m.average.toFixed(2) + '%' : 'N/A'}`);
+                });
+            }
+            catch (e) {
+                console.log(`⚠️ Could not fetch plan metrics: ${e.message.split('\n')[0]}`);
+            }
+            // Prepare for API calls
+            // Get Access Token explicitly
+            const token = (0, child_process_1.execSync)('az account get-access-token --resource https://management.azure.com/ --query accessToken -o tsv').toString().trim();
+            const axios = (await Promise.resolve().then(() => __importStar(require('axios')))).default;
+            // --- 1.5: App Level Metrics (CpuTime) ---
+            try {
+                console.log(`\n> Fetching App Metrics (Last 5m) for ${config.appName}...`);
+                const subscriptionId = (0, child_process_1.execSync)(`az account show --query id -o tsv`).toString().trim();
+                const siteResourceId = `/subscriptions/${subscriptionId}/resourceGroups/${config.resourceGroup}/providers/Microsoft.Web/sites/${config.appName}`;
+                const appResponse = await axios.get(`https://management.azure.com${siteResourceId}/providers/microsoft.insights/metrics?api-version=2018-01-01&metricnames=CpuTime&timespan=PT5M&aggregation=Total`, { headers: { Authorization: `Bearer ${token}` } });
+                if (appResponse.data && appResponse.data.value) {
+                    appResponse.data.value.forEach((m) => {
+                        const val = (m.timeseries[0]?.data[0]?.total);
+                        const displayVal = val !== undefined ? val.toFixed(2) : 'N/A';
+                        console.log(`${m.name.value}: ${displayVal}s (Total over 5m)`);
+                    });
+                }
+            }
+            catch (e) {
+                console.log(`⚠️ Could not fetch app metrics: ${e.message}`);
+            }
+            // 2. Process Metrics (Step 2)
+            console.log(`\n--- ⚙️ Step 2: Per-Process Resource Analysis (Kudu) ---`);
+            try {
+                // Token and axios already fetched above
+                const response = await axios.get(`https://${config.appName}.scm.azurewebsites.net/api/processes`, {
+                    headers: { Authorization: `Bearer ${token}` }
+                });
+                const processes = response.data;
+                // Shared diagnostics state
+                let memInfoOutput = '';
+                let psOutput = '';
+                let psLines = [];
+                // Use Kudu Command API to run 'top' remotely
+                try {
+                    const topCmd = {
+                        command: "top -b -d 3 -n 2",
+                        dir: "/home"
+                    };
+                    const cmdRes = await axios.post(`https://${config.appName}.scm.azurewebsites.net/api/command`, topCmd, {
+                        headers: { Authorization: `Bearer ${token}` },
+                        timeout: 25000
+                    });
+                    if (cmdRes.data && cmdRes.data.Output) {
+                        const lines = cmdRes.data.Output.split('\n');
+                        // --- Trace System Summary ---
+                        console.log('System Summary (from top):');
+                        let summaryLinesCount = 0;
+                        for (const line of lines) {
+                            if (line.trim() && summaryLinesCount < 5) {
+                                console.log(`  ${line.trim()}`);
+                                summaryLinesCount++;
+                            }
+                        }
+                        // --- Deep Dive: Missing Memory Investigation ---
+                        console.log(`\n> Investigating "Invisible" Memory Usage...`);
+                        try {
+                            const dfCmd = { command: "df -h | grep -E 'tmpfs|shm'", dir: "/home" };
+                            const dfRes = await axios.post(`https://${config.appName}.scm.azurewebsites.net/api/command`, dfCmd, { headers: { Authorization: `Bearer ${token}` } });
+                            console.log('  [Tmpfs/Shm Usage]:');
+                            console.log(dfRes.data.Output ? '  ' + dfRes.data.Output.replace(/\n/g, '\n  ').trim() : '  (No output)');
+                            const memInfoCmd = { command: "cat /proc/meminfo | grep -E 'MemTotal|MemFree|MemAvailable|SwapTotal|SwapFree|Shmem|Slab|SUnreclaim|Buffers|Cached|AnonPages|Committed_AS'", dir: "/home" };
+                            const memRes = await axios.post(`https://${config.appName}.scm.azurewebsites.net/api/command`, memInfoCmd, { headers: { Authorization: `Bearer ${token}` } });
+                            memInfoOutput = memRes.data.Output || '';
+                            console.log('  [Detailed MemInfo]:');
+                            console.log(memInfoOutput ? '  ' + memInfoOutput.replace(/\n/g, '\n  ').trim() : '  (No output)');
+                            console.log('\n  [Searching for Swap/VM Hogs in /proc...]:');
+                            const swapHogCmd = {
+                                command: "for f in /proc/[0-9]*/status; do grep -E '^(Name|Pid|VmSwap|VmSize)' $f 2>/dev/null | tr '\n' ' ' && echo ''; done | sort -k6 -rn | head -n 10",
+                                dir: "/home"
+                            };
+                            const swapRes = await axios.post(`https://${config.appName}.scm.azurewebsites.net/api/command`, swapHogCmd, { headers: { Authorization: `Bearer ${token}` } });
+                            console.log('  (Format: Name, Pid, VmSize, VmSwap)');
+                            console.log(swapRes.data.Output ? '  ' + swapRes.data.Output.replace(/\n/g, '\n  ').trim() : '  (No output)');
+                        }
+                        catch (e) {
+                            console.log(`  Could not inspect storage/meminfo: ${e.message}`);
+                        }
+                        let currentSnapshot = [];
+                        let foundHeader = false;
+                        let cpuColIndex = -1;
+                        let memColIndex = -1;
+                        let cmdColIndex = -1;
+                        for (const line of lines) {
+                            const trimmed = line.trim();
+                            if (!trimmed)
+                                continue;
+                            if (trimmed.includes('PID') && trimmed.includes('COMMAND')) {
+                                foundHeader = true;
+                                currentSnapshot = [];
+                                const headers = trimmed.split(/\s+/);
+                                cpuColIndex = headers.indexOf('%CPU');
+                                if (cpuColIndex === -1)
+                                    cpuColIndex = headers.indexOf('CPU%');
+                                memColIndex = headers.indexOf('%MEM');
+                                if (memColIndex === -1)
+                                    memColIndex = headers.indexOf('MEM%');
+                                cmdColIndex = headers.indexOf('COMMAND');
+                                continue;
+                            }
+                            if (foundHeader && cpuColIndex >= 0) {
+                                const parts = trimmed.split(/\s+/);
+                                if (parts.length >= 9) {
+                                    const pid = parts[0];
+                                    const cpuStr = parts[cpuColIndex];
+                                    const memStr = parts[memColIndex];
+                                    const cmd = parts.slice(cmdColIndex).join(' ');
+                                    const state = parts[7] || '?';
+                                    const time = parts[10] || '?';
+                                    const cpuVal = parseFloat(cpuStr);
+                                    const memVal = parseFloat(memStr);
+                                    if (!isNaN(parseInt(pid))) {
+                                        currentSnapshot.push({ pid, cmd, cpuStr, memStr, cpuVal, memVal, state, time });
+                                    }
+                                }
+                            }
+                        }
+                        if (currentSnapshot.length === 0) {
+                            console.log('(No processes found or parsing failed)');
+                        }
+                        else {
+                            console.log(`\n--- Cross-Referencing Memory Hogs (ps aux) ---`);
+                            try {
+                                const psRes = await axios.post(`https://${config.appName}.scm.azurewebsites.net/api/command`, { command: "ps aux", dir: "/home" }, { headers: { Authorization: `Bearer ${token}` } });
+                                psOutput = psRes.data.Output || '';
+                                console.log(`PID\tVSZ\tRSS\tCOMMAND`);
+                                console.log(`---\t---\t---\t-------`);
+                                psLines = psOutput.split('\n').filter((l) => l.includes(' '));
+                                psLines.slice(1, 10).forEach((l) => {
+                                    const p = l.trim().split(/\s+/);
+                                    if (p.length > 10) {
+                                        console.log(`${p[1]}\t${(parseInt(p[4]) / 1024).toFixed(0)}M\t${(parseInt(p[5]) / 1024).toFixed(0)}M\t${p.slice(10).join(' ').padEnd(30).slice(0, 30)}`);
+                                    }
+                                });
+                            }
+                            catch (e) {
+                                console.log(`  Could not fetch ps aux: ${e.message}`);
+                            }
+                            console.log(`\n--- Top Processes by CPU (top delta) ---`);
+                            console.log(`PID\tSTATE\tTIME+\t%CPU\t%MEM\tCOMMAND`);
+                            console.log(`---\t-----\t-----\t----\t----\t-------`);
+                            currentSnapshot.sort((a, b) => b.cpuVal - a.cpuVal);
+                            currentSnapshot.slice(0, 5).forEach(p => {
+                                console.log(`${p.pid}\t${p.state}\t${p.time}\t${p.cpuStr}%\t${p.memStr}%\t${p.cmd.padEnd(20).slice(0, 20)}`);
+                            });
+                            console.log(`\n--- 🧠 Step 4: Automated Diagnosis ---`);
+                            try {
+                                let healthy = true;
+                                if (memInfoOutput.includes('SwapTotal')) {
+                                    const swapTotal = parseInt(memInfoOutput.match(/SwapTotal:\s+(\d+)/)?.[1] || '0');
+                                    const swapFree = parseInt(memInfoOutput.match(/SwapFree:\s+(\d+)/)?.[1] || '0');
+                                    if (swapTotal > 0) {
+                                        const swapUsedPct = ((swapTotal - swapFree) / swapTotal) * 100;
+                                        if (swapUsedPct > 95) {
+                                            console.log(`❌ [CRITICAL] Swap Death detected (${swapUsedPct.toFixed(1)}% used).`);
+                                            healthy = false;
+                                        }
+                                    }
+                                }
+                                const hasApp = psOutput.includes('server.js') || psOutput.includes('orchestrator.ts');
+                                if (!hasApp) {
+                                    console.log(`❌ [CRITICAL] Application process 'server.js' NOT FOUND in ps aux.`);
+                                    healthy = false;
+                                }
+                                const kuduHog = currentSnapshot.find(p => p.pid === '851' && p.memVal > 20);
+                                if (kuduHog) {
+                                    console.log(`⚠️ [WARNING] Kudu (Azure Agent) is consuming ${kuduHog.memStr}% of physical RAM.`);
+                                    healthy = false;
+                                }
+                                const pm2Hogs = psLines.filter((l) => l.includes('God Daemon'));
+                                if (pm2Hogs.length > 1) {
+                                    console.log(`⚠️ [WARNING] Multiple PM2 God Daemons detected (${pm2Hogs.length}). Potential resource conflict.`);
+                                    healthy = false;
+                                }
+                                if (healthy) {
+                                    console.log(`✅ No obvious infrastructure bottlenecks detected.`);
+                                }
+                                else {
+                                    console.log(`\nRECOMMENDED ACTIONS:`);
+                                    console.log(`1. Restart the Web App to clear Swap and kill rogue agents.`);
+                                    console.log(`2. Consider upgrading the App Service Plan (B1 -> P1v3) for more RAM.`);
+                                }
+                            }
+                            catch (e) {
+                                console.log(`  Could not perform automated diagnosis: ${e.message}`);
+                            }
+                        }
+                    }
+                    else {
+                        console.log('Debug: Unexpected response format:', cmdRes.data);
+                    }
+                }
+                catch (err) {
+                    console.log(`⚠️ 'top' failed via Kudu: ${err.message}`);
+                }
+            }
+            catch (e) {
+                console.log(`⚠️ Could not fetch process metrics: ${e.message}`);
+            }
+        }
+        catch (error) {
+            console.error('❌ Failed to fetch infrastructure metrics:', error.message);
+        }
+    }
+    // 3. Log Analysis (Step 3)
+    if (includeLogs || config.env === 'local') {
+        console.log('\n--- 📝 Step 3: Log Analysis ---');
+        let logContent = '';
+        if (config.env !== 'local') {
+            try {
+                console.log('> Downloading recent logs from Azure...');
+                const fraimTmp = path.join(os.homedir(), '.fraim', 'tmp');
+                if (!fs.existsSync(fraimTmp))
+                    fs.mkdirSync(fraimTmp, { recursive: true });
+                const tempDir = fs.mkdtempSync(path.join(fraimTmp, `${fraim_config_1.fraimConfig.personaName.toLowerCase()}-logs-`));
+                const zipPath = path.join(tempDir, 'logs.zip');
+                (0, child_process_1.execSync)(`az webapp log download --name ${config.appName} --resource-group ${config.resourceGroup} --log-file "${zipPath}"`);
+                const originalCwd = process.cwd();
+                try {
+                    process.chdir(tempDir);
+                    try {
+                        (0, child_process_1.execSync)(`unzip -o logs.zip`);
+                    }
+                    catch (e) {
+                        try {
+                            (0, child_process_1.execSync)(`powershell -command "Expand-Archive -Path 'logs.zip' -DestinationPath '.' -Force"`);
+                        }
+                        catch (p) { }
+                    }
+                    process.chdir(originalCwd);
+                }
+                catch (e) {
+                    process.chdir(originalCwd);
+                }
+                const findLogFile = (dir) => {
+                    const files = fs.readdirSync(dir);
+                    for (const file of files) {
+                        const fullPath = path.join(dir, file);
+                        const stat = fs.statSync(fullPath);
+                        if (stat.isDirectory()) {
+                            const found = findLogFile(fullPath);
+                            if (found)
+                                return found;
+                        }
+                        else if (file.endsWith('_default_docker.log')) {
+                            return fullPath;
+                        }
+                    }
+                    return null;
+                };
+                const dockerLog = findLogFile(tempDir);
+                if (dockerLog)
+                    logContent = fs.readFileSync(dockerLog, 'utf-8');
+            }
+            catch (error) {
+                console.error('❌ Failed to download logs:', error.message);
+            }
+        }
+        else {
+            const localLogPath = path.join(process.cwd(), 'test.log');
+            if (fs.existsSync(localLogPath))
+                logContent = fs.readFileSync(localLogPath, 'utf-8');
+        }
+        if (logContent) {
+            analyzeLogs(logContent);
+        }
+    }
+}
+function analyzeLogs(content) {
+    const lines = content.split('\n');
+    let indexChecks = 0, decryptions = 0, dbConnections = 0, rssMemory = 0;
+    const indexPattern = /Ensured unique index/;
+    const decryptPattern = /Token decrypted/;
+    const dbConnPattern = /Database connection successful/;
+    const memoryPattern = /RSS: (\d+) MB/;
+    for (const line of lines) {
+        if (indexPattern.test(line))
+            indexChecks++;
+        if (decryptPattern.test(line))
+            decryptions++;
+        if (dbConnPattern.test(line))
+            dbConnections++;
+        const memMatch = line.match(memoryPattern);
+        if (memMatch)
+            rssMemory = Math.max(rssMemory, parseInt(memMatch[1]));
+    }
+    console.log('\n--- 📊 Operation Frequency ---');
+    console.log(`Ensured Unique Index: ${indexChecks}`);
+    console.log(`Token Decryptions:    ${decryptions}`);
+    console.log(`DB Connections:       ${dbConnections}`);
+    if (rssMemory > 0)
+        console.log(`Max RSS Detected: ${rssMemory} MB`);
+}
+main().catch(console.error);

package/dist/scripts/build-stub-registry.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env tsx
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStubRegistry = buildStubRegistry;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const stub_generator_1 = require("../src/utils/stub-generator");
+/**
+ * Build script to generate stub-only registry for npm package
+ *
+ * This creates a minimal registry containing:
+ * - Pre-generated workflow stubs (for IDE discoverability)
+ * - Scripts (for local execution)
+ *
+ * Excludes:
+ * - Complete workflows (served by MCP server)
+ * - Templates (served by MCP server)
+ * - Rules (served by MCP server)
+ */
+const SOURCE_REGISTRY = path_1.default.join(__dirname, '..', 'registry');
+const STUB_REGISTRY = path_1.default.join(__dirname, '..', 'registry', 'stubs');
+async function buildStubRegistry() {
+    console.log('🔨 Building stub-only registry for npm package...');
+    // Clean existing stubs directory
+    if (fs_1.default.existsSync(STUB_REGISTRY)) {
+        fs_1.default.rmSync(STUB_REGISTRY, { recursive: true, force: true });
+    }
+    // Create stubs directory structure
+    fs_1.default.mkdirSync(STUB_REGISTRY, { recursive: true });
+    // Generate workflow stubs
+    await generateWorkflowStubs();
+    console.log('✅ Stub registry build complete!');
+}
+async function generateWorkflowStubs() {
+    const workflowsSourceDir = path_1.default.join(SOURCE_REGISTRY, 'workflows');
+    const workflowsStubDir = path_1.default.join(STUB_REGISTRY, 'workflows');
+    if (!fs_1.default.existsSync(workflowsSourceDir)) {
+        console.warn('⚠️ No workflows directory found in source registry');
+        return;
+    }
+    console.log('📝 Generating workflow stubs...');
+    // Get all workflow files recursively
+    const workflowFiles = getAllWorkflowFiles(workflowsSourceDir);
+    let stubCount = 0;
+    for (const workflowFile of workflowFiles) {
+        try {
+            // Read complete workflow
+            const content = fs_1.default.readFileSync(workflowFile.fullPath, 'utf8');
+            // Parse intent and principles
+            const { intent, principles } = (0, stub_generator_1.parseRegistryWorkflow)(content);
+            // Generate stub
+            const workflowName = path_1.default.basename(workflowFile.name, '.md');
+            const stub = (0, stub_generator_1.generateWorkflowStub)(workflowName, workflowFile.relativePath, intent, principles);
+            // Create target directory structure
+            const targetDir = path_1.default.join(workflowsStubDir, path_1.default.dirname(workflowFile.relativePath));
+            if (!fs_1.default.existsSync(targetDir)) {
+                fs_1.default.mkdirSync(targetDir, { recursive: true });
+            }
+            // Write stub file
+            const stubPath = path_1.default.join(workflowsStubDir, workflowFile.relativePath);
+            fs_1.default.writeFileSync(stubPath, stub);
+            stubCount++;
+            console.log(`  ✓ ${workflowFile.relativePath}`);
+        }
+        catch (error) {
+            console.error(`  ❌ Failed to generate stub for ${workflowFile.relativePath}:`, error);
+        }
+    }
+    console.log(`📝 Generated ${stubCount} workflow stubs`);
+}
+function getAllWorkflowFiles(dir, baseDir = dir) {
+    const files = [];
+    if (!fs_1.default.existsSync(dir)) {
+        return files;
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip certain directories
+            if (entry.name.includes('Issue ') || entry.name.includes('Master')) {
+                continue;
+            }
+            // Recursively process subdirectories
+            files.push(...getAllWorkflowFiles(fullPath, baseDir));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            // Add markdown files
+            const relativePath = path_1.default.relative(baseDir, fullPath);
+            files.push({
+                name: entry.name,
+                fullPath,
+                relativePath: relativePath.replace(/\\/g, '/') // Normalize path separators
+            });
+        }
+    }
+    return files;
+}
+// Run the build if this script is executed directly
+if (require.main === module) {
+    buildStubRegistry().catch(error => {
+        console.error('❌ Build failed:', error);
+        process.exit(1);
+    });
+}

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

@@ -53,20 +53,20 @@ exports.doctorCommand = new commander_1.Command('doctor')
     // 4. Check registry & sync status
     const digestPath = path_1.default.join(fraimDir, '.digest');
     // Try 4 levels up (dist/src/cli/commands -> root)
-    let registryPath = path_1.default.join(__dirname, '../../../../registry');
+    let registryPath = path_1.default.join(__dirname, '../../../../registry/stubs');
     if (!fs_1.default.existsSync(registryPath)) {
         // Try 3 levels up (src/cli/commands -> root)
-        registryPath = path_1.default.join(__dirname, '../../../registry');
+        registryPath = path_1.default.join(__dirname, '../../../registry/stubs');
     }
     // Fallback for local development if running from within the framework repo itself (and CWD is root)
     if (!fs_1.default.existsSync(registryPath)) {
-        registryPath = path_1.default.join(projectRoot, 'registry');
+        registryPath = path_1.default.join(projectRoot, 'registry/stubs');
     }
     if (!fs_1.default.existsSync(registryPath)) {
-        console.log(chalk_1.default.yellow('⚠️ Could not locate framework registry. (Expected in node_modules/@fraim/framework/registry)'));
+        console.log(chalk_1.default.yellow('⚠️ Could not locate framework stub registry. (Expected in node_modules/@fraim/framework/registry/stubs)'));
     }
     else {
-        console.log(chalk_1.default.green('✅ Framework registry found.'));
+        console.log(chalk_1.default.green('✅ Framework stub registry found.'));
         const currentDigest = await (0, digest_utils_1.generateDigest)(registryPath);
         const existingDigest = fs_1.default.existsSync(digestPath) ? fs_1.default.readFileSync(digestPath, 'utf8') : '';
         if (currentDigest !== existingDigest) {

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

@@ -9,7 +9,6 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const digest_utils_1 = require("../../utils/digest-utils");
-const stub_generator_1 = require("../../utils/stub-generator");
 const config_loader_1 = require("../../fraim/config-loader");
 const version_utils_1 = require("../../utils/version-utils");
 const script_sync_utils_1 = require("../../utils/script-sync-utils");
@@ -20,20 +19,20 @@ const runSync = async (options) => {
     const workflowsRelativePath = config.customizations?.workflowsPath || '.fraim/workflows';
     const workflowsDir = path_1.default.resolve(projectRoot, workflowsRelativePath);
     const digestPath = path_1.default.join(fraimDir, '.digest');
-    // In a real npm package, registry would be in node_modules/@fraim/framework/registry
+    // In npm package, stubs are in node_modules/@fraim/framework/registry/stubs/workflows
     // We need to handle both "running from source" (src/cli/commands) and "running from dist" (dist/src/cli/commands)
     // Try 4 levels up (dist/src/cli/commands -> root)
-    let registryPath = path_1.default.join(__dirname, '../../../../registry');
+    let registryPath = path_1.default.join(__dirname, '../../../../registry/stubs');
     if (!fs_1.default.existsSync(registryPath)) {
         // Try 3 levels up (src/cli/commands -> root)
-        registryPath = path_1.default.join(__dirname, '../../../registry');
+        registryPath = path_1.default.join(__dirname, '../../../registry/stubs');
     }
     // Fallback for local development if running from within the framework repo itself
     if (!fs_1.default.existsSync(registryPath)) {
-        registryPath = path_1.default.join(projectRoot, 'registry');
+        registryPath = path_1.default.join(projectRoot, 'registry/stubs');
     }
     if (!fs_1.default.existsSync(registryPath)) {
-        console.error(chalk_1.default.red('❌ Registry not found. Ensure @fraim/framework is installed.'));
+        console.error(chalk_1.default.red('❌ Stub registry not found. Ensure @fraim/framework is installed and built.'));
         process.exit(1);
     }
     if (!fs_1.default.existsSync(workflowsDir)) {
@@ -64,10 +63,10 @@ const runSync = async (options) => {
     else {
         const registryWorkflowsPath = path_1.default.join(registryPath, 'workflows');
         if (!fs_1.default.existsSync(registryWorkflowsPath)) {
-            console.log(chalk_1.default.yellow('⚠️ No workflows found in registry.'));
+            console.log(chalk_1.default.yellow('⚠️ No workflow stubs found in registry.'));
         }
         else {
-            // Get all workflows from registry (recursive)
+            // Get all workflow stubs from registry (recursive)
             const getFiles = (dir) => {
                 const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
                 const files = entries
@@ -80,13 +79,12 @@ const runSync = async (options) => {
                 return files;
             };
             const registryFiles = getFiles(registryWorkflowsPath);
-            const generatedStubs = [];
+            const copiedStubs = [];
             for (const file of registryFiles) {
-                const content = fs_1.default.readFileSync(file, 'utf8');
-                const { intent, principles } = (0, stub_generator_1.parseRegistryWorkflow)(content);
+                // These are already stubs, just copy them directly
                 const fileName = path_1.default.basename(file);
                 const workflowName = fileName.replace('.md', '');
-                // Calculate relative path from registry/workflows to preserve structure
+                // Calculate relative path from registry/stubs/workflows to preserve structure
                 const relativePath = path_1.default.relative(registryWorkflowsPath, file);
                 const relativeDir = path_1.default.dirname(relativePath);
                 // Ensure target directory exists
@@ -94,10 +92,11 @@ const runSync = async (options) => {
                 if (!fs_1.default.existsSync(targetDir)) {
                     fs_1.default.mkdirSync(targetDir, { recursive: true });
                 }
-                const stubContent = (0, stub_generator_1.generateWorkflowStub)(workflowName, file, intent, principles);
+                // Copy stub file directly
+                const stubContent = fs_1.default.readFileSync(file, 'utf8');
                 const stubPath = path_1.default.join(targetDir, fileName);
                 fs_1.default.writeFileSync(stubPath, stubContent);
-                generatedStubs.push(relativePath); // Store relative path for cleanup tracking
+                copiedStubs.push(relativePath); // Store relative path for cleanup tracking
                 console.log(chalk_1.default.gray(`  + ${workflowName} (${relativeDir === '.' ? 'root' : relativeDir})`));
             }
             // Cleanup stubs that no longer exist in registry
@@ -119,8 +118,8 @@ const runSync = async (options) => {
             for (const stub of localStubs) {
                 // standardise path separators for comparison
                 const normalizedStub = stub.replace(/\\/g, '/');
-                const normalizedGenerated = generatedStubs.map(s => s.replace(/\\/g, '/'));
-                if (!normalizedGenerated.includes(normalizedStub)) {
+                const normalizedCopied = copiedStubs.map(s => s.replace(/\\/g, '/'));
+                if (!normalizedCopied.includes(normalizedStub)) {
                     fs_1.default.unlinkSync(path_1.default.join(workflowsDir, stub));
                     console.log(chalk_1.default.yellow(`  - ${stub} (removed from registry)`));
                     // Cleanup empty directories
@@ -134,13 +133,28 @@ const runSync = async (options) => {
                 }
             }
             fs_1.default.writeFileSync(digestPath, currentDigest);
-            console.log(chalk_1.default.green(`\n✅ Workflow sync complete. Generated ${generatedStubs.length} stubs.`));
+            console.log(chalk_1.default.green(`\n✅ Workflow sync complete. Copied ${copiedStubs.length} stubs.`));
         }
     }
     // Always sync scripts, regardless of workflow sync status
     console.log(chalk_1.default.blue('\n🔄 Syncing FRAIM scripts to user directory...'));
-    const syncResult = (0, script_sync_utils_1.syncScriptsToUserDirectory)(registryPath);
-    const cleanedScriptCount = (0, script_sync_utils_1.cleanupObsoleteUserScripts)(registryPath);
+    // Scripts are packaged separately from stubs, find the correct registry path
+    // Try 4 levels up (dist/src/cli/commands -> root)
+    let scriptsRegistryPath = path_1.default.join(__dirname, '../../../../registry');
+    if (!fs_1.default.existsSync(path_1.default.join(scriptsRegistryPath, 'scripts'))) {
+        // Try 3 levels up (src/cli/commands -> root)
+        scriptsRegistryPath = path_1.default.join(__dirname, '../../../registry');
+    }
+    // Fallback for local development if running from within the framework repo itself
+    if (!fs_1.default.existsSync(path_1.default.join(scriptsRegistryPath, 'scripts'))) {
+        scriptsRegistryPath = path_1.default.join(projectRoot, 'registry');
+    }
+    if (!fs_1.default.existsSync(path_1.default.join(scriptsRegistryPath, 'scripts'))) {
+        console.error(chalk_1.default.red('❌ Scripts registry not found. Ensure @fraim/framework is installed and built.'));
+        process.exit(1);
+    }
+    const syncResult = (0, script_sync_utils_1.syncScriptsToUserDirectory)(scriptsRegistryPath);
+    const cleanedScriptCount = (0, script_sync_utils_1.cleanupObsoleteUserScripts)(scriptsRegistryPath);
     if (syncResult.synced > 0 || cleanedScriptCount > 0) {
         console.log(chalk_1.default.green(`✅ Script sync complete. Updated ${syncResult.synced} scripts, removed ${cleanedScriptCount} obsolete scripts.`));
     }