fraim-framework 2.0.100 → 2.0.101

package/README.md

@@ -8,7 +8,7 @@ Current "vibe coding" frameworks are great at getting from idea to prototype. Th
 
 AI agents are like brilliant but inexperienced developers. They need:
 • Clear guardrails to prevent costly mistakes
-• Structured workflows to avoid chaos
+• Structured jobs, skills, and rules to avoid chaos
 • Evidence-based validation (not "looks good" claims)
 • Learning systems to improve over time
 • Balance between determinism and creativity
@@ -23,7 +23,7 @@ FRAIM transforms you from a solo developer into an AI manager orchestrating mult
 
 **Real Results:**
 • Dramatic reduction in AI-generated code that needs rework
-• Faster delivery through structured workflows
+• Faster delivery through structured jobs
 • Higher test coverage through mandatory evidence collection
 • Zero agent conflicts through phase-based coordination
 
@@ -44,11 +44,11 @@ R - Retrospectives: Continuous learning from experience
 
 | **Human Development** | **AI Agent Development** | **FRAIM Solution** |
 |----------------------|-------------------------|-------------------|
-| **Code Reviews** | Random quality checks | Structured review workflows with evidence requirements |
+| **Code Reviews** | Random quality checks | Structured review jobs with evidence requirements |
 | **Testing Standards** | "Looks good" claims | Mandatory test evidence with failure reproduction |
 | **Team Coordination** | Agent conflicts and overlaps | Phase-based isolation with clear handoffs |
 | **Learning Culture** | Repeated mistakes | Retrospective-driven improvement system |
-| **Process Discipline** | Ad-hoc approaches | Proven workflows and deterministic scripts from real projects |
+| **Process Discipline** | Ad-hoc approaches | Proven jobs, skills, and deterministic scripts from real projects |
 | **Quality Gates** | Unreliable outcomes | Deterministic validation with rollback capabilities |
 
 
@@ -133,7 +133,7 @@ R - Retrospectives: Continuous learning from experience
 
 #### 🔄 **Merge Requirements & Branch Safety** 
 **Problem**: Agents accidentally overwrite master branch or create merge conflicts
-**Solution**: Mandatory rebase workflows with conflict resolution patterns
+**Solution**: Mandatory rebase discipline with conflict resolution patterns
 ```bash
 # Before: Force pushes that destroy other work
 # After: Rebase-on-master with force-with-lease for safety
@@ -159,7 +159,7 @@ R - Retrospectives: Continuous learning from experience
 ## 🚀 **Proven Benefits from Real Projects**
 
 - **Dramatic reduction** in AI-generated code that needs rework through evidence-based validation
-- **Faster delivery** through structured workflows and clear handoffs
+- **Faster delivery** through structured jobs and clear handoffs
 - **Higher test coverage** through mandatory testing guidelines and evidence collection
 - **Zero agent conflicts** through phase-based isolation and coordination
 - **Complete accountability** - agents fix their own mistakes with evidence
@@ -248,7 +248,7 @@ fraim setup --key=<your-fraim-key>
 
 The setup command supports three modes:
 
-**Conversational Mode**: AI workflows only, no platform integration required
+**Conversational Mode**: FRAIM job guidance only, no platform integration required
 ```bash
 fraim setup --key=<your-fraim-key>
 # Select "Conversational Mode" when prompted
@@ -299,19 +299,41 @@ fraim doctor --test-mcp            # Test MCP server connections
 fraim doctor                        # Diagnose configuration issues
 
 # Sync and maintenance
-fraim sync                          # Sync latest workflows and rules
+fraim sync                          # Sync latest jobs, skills, rules, and templates
 ```
 
 **💡 Pro Tip**: Use `fraim add-ide` when you install a new IDE after initial setup. It reuses your existing FRAIM and platform tokens, making it much faster than running full setup again.
 
+### **Which Job Should I Run?**
+
+FRAIM's primary execution unit is a **job**. Jobs define the phased path. Skills and rules support the job; they are not the thing you "run" first.
+
+Use these defaults:
+- `feature-specification` when the request is still fuzzy or needs clarified requirements, UX, or acceptance criteria.
+- `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
+- `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
+- `test-execution` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
+- `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
+- `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
+- `implementation-design-review` when you need to verify the code matches the approved technical design.
+- `issue-retrospective` after the work is complete and you want durable learnings captured.
+
+Typical path for a larger feature:
+- `feature-specification` -> `technical-design` -> `feature-implementation` -> review job -> `issue-retrospective`
+
+Typical path for a small bug fix:
+- `feature-implementation` -> review job if needed -> `issue-retrospective`
+
+Once FRAIM is connected in your IDE, ask your agent to `list FRAIM jobs` or name the specific job directly, for example: `Run the feature-implementation job for issue #123`.
+
 ### **🧩 Personalized Jobs, Skills, and Rules**
 
-Project-specific customization now lives under `.fraim/personalized-employee/`.
+Project-specific customization now lives under `fraim/personalized-employee/`.
 
 Recommended layout:
 
 ```text
-.fraim/
+fraim/
   personalized-employee/
     jobs/
     skills/
@@ -327,12 +349,12 @@ fraim override --copy rules/engineering/architecture-standards.md
 ```
 
 Guidance:
-- Put phased job customizations in `.fraim/personalized-employee/jobs/...`
-- Put reusable local capability snippets in `.fraim/personalized-employee/skills/...`
-- Put broad team conventions in `.fraim/personalized-employee/rules/...`
-- Put local deliverable tweaks in `.fraim/personalized-employee/templates/...`
-- Do not edit synced content under `.fraim/ai-employee/` or `.fraim/ai-manager/`; `fraim sync` will overwrite it
-- Legacy `.fraim/overrides/` is still read for compatibility, but new work should go in `.fraim/personalized-employee/`
+- Put phased job customizations in `fraim/personalized-employee/jobs/...`
+- Put reusable local capability snippets in `fraim/personalized-employee/skills/...`
+- Put broad team conventions in `fraim/personalized-employee/rules/...`
+- Put local deliverable tweaks in `fraim/personalized-employee/templates/...`
+- Do not edit synced content under `fraim/ai-employee/` or `fraim/ai-manager/`; `fraim sync` will overwrite it
+- Legacy `.fraim/overrides/` is still read for compatibility, but new work should go in `fraim/personalized-employee/`
 
 ### **🔧 Jira Integration Setup**
 
@@ -382,7 +404,7 @@ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json  # For Clau
 ## 🌟 **Why FRAIM is the Future**
 
 ### **1. Proven in Production**
-Every rule, workflow, and pattern has been tested in real projects. This isn't theoretical—it's battle-tested.
+Every rule, job, skill, and pattern has been tested in real projects. This isn't theoretical—it is battle-tested.
 
 ### **2. Enterprise Discipline**
 The same rigor you'd apply to managing human developers, applied to AI agents.

package/bin/fraim.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework CLI Entry Point

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

@@ -266,8 +266,12 @@ const runInitProject = async () => {
             (0, project_bootstrap_1.recordPathStatus)(result, (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(dir), false);
         }
     });
-    if ((0, fraim_gitignore_1.ensureFraimSyncedContentIgnored)(projectRoot)) {
-        console.log(chalk_1.default.green('Updated .gitignore FRAIM managed block'));
+    const ignoreUpdate = (0, fraim_gitignore_1.ensureFraimSyncedContentLocallyExcluded)(projectRoot);
+    if (ignoreUpdate.gitInfoExcludeUpdated) {
+        console.log(chalk_1.default.green('Updated .git/info/exclude FRAIM managed block'));
+    }
+    if (ignoreUpdate.gitignoreUpdated) {
+        console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
     }
     const detection = (0, platform_detection_1.detectPlatformFromGit)();
     if (detection.provider === 'github') {

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

@@ -46,6 +46,7 @@ const version_utils_1 = require("../utils/version-utils");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
 const git_utils_1 = require("../../core/utils/git-utils");
 const agent_adapters_1 = require("../utils/agent-adapters");
+const fraim_gitignore_1 = require("../utils/fraim-gitignore");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 /**
  * Load API key from user-level config (~/.fraim/config.json)
@@ -86,6 +87,15 @@ const runSync = async (options) => {
     const projectRoot = process.cwd();
     const config = (0, config_loader_1.loadFraimConfig)();
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectRoot);
+    const refreshLocalIgnoreConfig = () => {
+        const ignoreUpdate = (0, fraim_gitignore_1.ensureFraimSyncedContentLocallyExcluded)(projectRoot);
+        if (ignoreUpdate.gitInfoExcludeUpdated) {
+            console.log(chalk_1.default.green('Updated .git/info/exclude FRAIM managed block'));
+        }
+        if (ignoreUpdate.gitignoreUpdated) {
+            console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
+        }
+    };
     const isNpx = process.env.npm_config_prefix === undefined || process.env.npm_lifecycle_event === 'npx';
     const isGlobal = !isNpx && (process.env.npm_config_global === 'true' || process.env.npm_config_prefix);
     if (isGlobal && !options.skipUpdates) {
@@ -106,6 +116,7 @@ const runSync = async (options) => {
         if (result.success) {
             console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from local server`));
             updateVersionInConfig(fraimDir);
+            refreshLocalIgnoreConfig();
             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(', ')}`));
@@ -148,6 +159,7 @@ const runSync = async (options) => {
     }
     console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from remote`));
     updateVersionInConfig(fraimDir);
+    refreshLocalIgnoreConfig();
     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/services/device-flow-service.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceFlowService = void 0;
+const axios_1 = __importDefault(require("axios"));
+const chalk_1 = __importDefault(require("chalk"));
+class DeviceFlowService {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Start the Device Flow Login
+     */
+    async login() {
+        console.log(chalk_1.default.blue('\n🔗 Starting Authentication...'));
+        try {
+            // 1. Request device and user codes
+            const deviceCode = await this.requestDeviceCode();
+            console.log(chalk_1.default.yellow('\nACTION REQUIRED:'));
+            console.log(`1. Go to: ${chalk_1.default.cyan.underline(deviceCode.verification_uri)}`);
+            console.log(`2. Enter the code: ${chalk_1.default.bold.green(deviceCode.user_code)}`);
+            console.log(chalk_1.default.gray(`\nWaiting for authorization (expires in ${Math.floor(deviceCode.expires_in / 60)} minutes)...`));
+            // 2. Poll for the access token
+            const token = await this.pollForToken(deviceCode.device_code, deviceCode.interval);
+            console.log(chalk_1.default.green('\n✅ Authentication Successful!'));
+            return token;
+        }
+        catch (error) {
+            console.error(chalk_1.default.red(`\n❌ Authentication failed: ${error.message}`));
+            throw error;
+        }
+    }
+    async requestDeviceCode() {
+        const response = await axios_1.default.post(this.config.authUrl, {
+            client_id: this.config.clientId,
+            scope: this.config.scope
+        }, {
+            headers: { Accept: 'application/json' }
+        });
+        return response.data;
+    }
+    async pollForToken(deviceCode, interval) {
+        let currentInterval = interval * 1000;
+        return new Promise((resolve, reject) => {
+            const poll = async () => {
+                try {
+                    const response = await axios_1.default.post(this.config.tokenUrl, {
+                        client_id: this.config.clientId,
+                        device_code: deviceCode,
+                        grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+                    }, {
+                        headers: { Accept: 'application/json' }
+                    });
+                    if (response.data.access_token) {
+                        resolve(response.data.access_token);
+                        return;
+                    }
+                    if (response.data.error) {
+                        const error = response.data.error;
+                        if (error === 'authorization_pending') {
+                            // Keep polling
+                            setTimeout(poll, currentInterval);
+                        }
+                        else if (error === 'slow_down') {
+                            currentInterval += 5000;
+                            setTimeout(poll, currentInterval);
+                        }
+                        else {
+                            reject(new Error(response.data.error_description || error));
+                        }
+                    }
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            setTimeout(poll, currentInterval);
+        });
+    }
+}
+exports.DeviceFlowService = DeviceFlowService;

package/dist/src/cli/utils/fraim-gitignore.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureFraimSyncedContentIgnored = exports.FRAIM_SYNC_GITIGNORE_ENTRIES = exports.FRAIM_SYNC_GITIGNORE_END = exports.FRAIM_SYNC_GITIGNORE_START = void 0;
+exports.ensureFraimSyncedContentLocallyExcluded = exports.removeFraimSyncedContentGitignoreBlock = exports.FRAIM_SYNC_GITIGNORE_ENTRIES = exports.FRAIM_SYNC_GITIGNORE_END = exports.FRAIM_SYNC_GITIGNORE_START = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 exports.FRAIM_SYNC_GITIGNORE_START = '# BEGIN FRAIM SYNCED CONTENT';
@@ -14,27 +14,78 @@ exports.FRAIM_SYNC_GITIGNORE_ENTRIES = [
     'fraim/docs/',
 ];
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const ensureFraimSyncedContentIgnored = (projectRoot) => {
-    const gitignorePath = path_1.default.join(projectRoot, '.gitignore');
-    const existingRaw = fs_1.default.existsSync(gitignorePath)
-        ? fs_1.default.readFileSync(gitignorePath, 'utf8')
-        : '';
-    const newline = existingRaw.includes('\r\n') ? '\r\n' : '\n';
-    const normalized = existingRaw.replace(/\r\n/g, '\n');
-    const managedBlock = `${exports.FRAIM_SYNC_GITIGNORE_START}\n${exports.FRAIM_SYNC_GITIGNORE_ENTRIES.join('\n')}\n${exports.FRAIM_SYNC_GITIGNORE_END}`;
-    const blockPattern = new RegExp(`\\n?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_START)}[\\s\\S]*?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_END)}\\n?`, 'm');
-    const withoutManagedBlock = normalized.replace(blockPattern, '\n').trimEnd();
+const managedBlockPattern = new RegExp(`\\n?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_START)}[\\s\\S]*?${escapeRegExp(exports.FRAIM_SYNC_GITIGNORE_END)}\\n?`, 'm');
+function buildManagedBlock() {
+    return `${exports.FRAIM_SYNC_GITIGNORE_START}\n${exports.FRAIM_SYNC_GITIGNORE_ENTRIES.join('\n')}\n${exports.FRAIM_SYNC_GITIGNORE_END}`;
+}
+function normalizeWithoutManagedBlock(raw) {
+    const normalized = raw.replace(/\r\n/g, '\n');
+    const withoutManagedBlock = normalized.replace(managedBlockPattern, '\n').trimEnd();
     const cleaned = withoutManagedBlock
         .replace(/\n{3,}/g, '\n\n')
         .replace(/^\n+/, '')
         .trimEnd();
+    return cleaned;
+}
+function resolveGitInfoExcludePath(projectRoot) {
+    const gitPath = path_1.default.join(projectRoot, '.git');
+    if (!fs_1.default.existsSync(gitPath)) {
+        return null;
+    }
+    if (fs_1.default.statSync(gitPath).isDirectory()) {
+        return path_1.default.join(gitPath, 'info', 'exclude');
+    }
+    const gitPointer = fs_1.default.readFileSync(gitPath, 'utf8');
+    const match = gitPointer.match(/^gitdir:\s*(.+)\s*$/im);
+    if (!match) {
+        return null;
+    }
+    const gitDir = path_1.default.isAbsolute(match[1])
+        ? match[1]
+        : path_1.default.resolve(projectRoot, match[1]);
+    return path_1.default.join(gitDir, 'info', 'exclude');
+}
+const removeFraimSyncedContentGitignoreBlock = (projectRoot) => {
+    const gitignorePath = path_1.default.join(projectRoot, '.gitignore');
+    if (!fs_1.default.existsSync(gitignorePath)) {
+        return false;
+    }
+    const existingRaw = fs_1.default.readFileSync(gitignorePath, 'utf8');
+    const normalized = existingRaw.replace(/\r\n/g, '\n');
+    const cleaned = normalizeWithoutManagedBlock(existingRaw);
+    if (cleaned === normalized.trimEnd()) {
+        return false;
+    }
+    const newline = existingRaw.includes('\r\n') ? '\r\n' : '\n';
+    const next = cleaned.length > 0 ? `${cleaned}\n` : '';
+    fs_1.default.writeFileSync(gitignorePath, next.replace(/\n/g, newline), 'utf8');
+    return true;
+};
+exports.removeFraimSyncedContentGitignoreBlock = removeFraimSyncedContentGitignoreBlock;
+const ensureFraimSyncedContentLocallyExcluded = (projectRoot) => {
+    const gitignoreUpdated = (0, exports.removeFraimSyncedContentGitignoreBlock)(projectRoot);
+    const excludePath = resolveGitInfoExcludePath(projectRoot);
+    if (!excludePath) {
+        return { gitignoreUpdated, gitInfoExcludeUpdated: false };
+    }
+    const infoDir = path_1.default.dirname(excludePath);
+    if (!fs_1.default.existsSync(infoDir)) {
+        fs_1.default.mkdirSync(infoDir, { recursive: true });
+    }
+    const existingRaw = fs_1.default.existsSync(excludePath)
+        ? fs_1.default.readFileSync(excludePath, 'utf8')
+        : '';
+    const normalized = existingRaw.replace(/\r\n/g, '\n');
+    const cleaned = normalizeWithoutManagedBlock(existingRaw);
+    const managedBlock = buildManagedBlock();
     const next = cleaned.length > 0
         ? `${cleaned}\n\n${managedBlock}\n`
         : `${managedBlock}\n`;
     if (next !== normalized) {
-        fs_1.default.writeFileSync(gitignorePath, next.replace(/\n/g, newline), 'utf8');
-        return true;
+        const newline = existingRaw.includes('\r\n') ? '\r\n' : '\n';
+        fs_1.default.writeFileSync(excludePath, next.replace(/\n/g, newline), 'utf8');
+        return { gitignoreUpdated, gitInfoExcludeUpdated: true };
     }
-    return false;
+    return { gitignoreUpdated, gitInfoExcludeUpdated: false };
 };
-exports.ensureFraimSyncedContentIgnored = ensureFraimSyncedContentIgnored;
+exports.ensureFraimSyncedContentLocallyExcluded = ensureFraimSyncedContentLocallyExcluded;

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

@@ -11,6 +11,20 @@ exports.getRepositoryInfo = getRepositoryInfo;
 const fs_1 = require("fs");
 const types_1 = require("./types");
 const project_fraim_paths_1 = require("./utils/project-fraim-paths");
+function normalizeCustomerCommunication(config) {
+    const current = config?.['customer-communication'];
+    if (!current || typeof current !== 'object')
+        return undefined;
+    return {
+        productName: current.productName,
+        productUrl: current.productUrl,
+        senderDisplayName: current.senderDisplayName,
+        senderEmail: current.senderEmail,
+        senderReplyTo: current.senderReplyTo,
+        newsletterAudienceProvider: current.newsletterAudienceProvider,
+        deliveryProvider: current.deliveryProvider
+    };
+}
 function normalizeFraimConfig(config) {
     // Handle backward compatibility and migration
     const mergedConfig = {
@@ -52,6 +66,10 @@ function normalizeFraimConfig(config) {
     if (config.competitors && typeof config.competitors === 'object') {
         mergedConfig.competitors = config.competitors;
     }
+    const customerCommunication = normalizeCustomerCommunication(config);
+    if (customerCommunication) {
+        mergedConfig.customerCommunication = customerCommunication;
+    }
     return mergedConfig;
 }
 /**

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

@@ -90,6 +90,11 @@ function migrateLegacyProjectFraimDir(projectRoot = process.cwd()) {
     for (const entry of MIGRATABLE_LEGACY_ENTRIES) {
         moveOrMergePath(path_1.default.join(legacyDirPath, entry), path_1.default.join(workspaceDirPath, entry), entry, result);
     }
+    // Handle learned-skills -> personalized-employee/skills mapping
+    const legacyLearnedSkillsPath = path_1.default.join(legacyDirPath, 'learned-skills');
+    if (fs_1.default.existsSync(legacyLearnedSkillsPath)) {
+        moveOrMergePath(legacyLearnedSkillsPath, path_1.default.join(workspaceDirPath, 'personalized-employee', 'skills'), 'learned-skills', result);
+    }
     for (const entry of PRUNABLE_LEGACY_SYNCED_ENTRIES) {
         const legacyEntryPath = path_1.default.join(legacyDirPath, entry);
         if (!fs_1.default.existsSync(legacyEntryPath)) {
@@ -98,6 +103,13 @@ function migrateLegacyProjectFraimDir(projectRoot = process.cwd()) {
         fs_1.default.rmSync(legacyEntryPath, { recursive: true, force: true });
         result.prunedLegacyPaths.push(entry);
     }
+    // Final check for entries that are neither migratable nor prunable
+    const remainingEntries = fs_1.default.readdirSync(legacyDirPath);
+    const coreEntries = [...MIGRATABLE_LEGACY_ENTRIES, ...PRUNABLE_LEGACY_SYNCED_ENTRIES, 'learned-skills'];
+    const unknownEntries = remainingEntries.filter(e => !coreEntries.includes(e));
+    if (unknownEntries.length > 0) {
+        result.conflictPaths.push(...unknownEntries);
+    }
     result.legacyDirReadyForDeletion = result.conflictPaths.length === 0 && isDirectoryEmpty(legacyDirPath);
     return result;
 }

package/dist/src/core/utils/workflow-parser.js

@@ -5,13 +5,15 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 class WorkflowParser {
     static extractMetadataBlock(content) {
-        const frontmatterMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+        // Allow leading comments and whitespace before frontmatter
+        const frontmatterMatch = content.match(/^[\s\S]*?---\r?\n([\s\S]+?)\r?\n---/);
         if (frontmatterMatch) {
             try {
+                const startIndex = frontmatterMatch.index || 0;
                 return {
                     state: 'valid',
                     metadata: JSON.parse(frontmatterMatch[1]),
-                    bodyStartIndex: frontmatterMatch[0].length
+                    bodyStartIndex: startIndex + frontmatterMatch[0].length
                 };
             }
             catch {
@@ -107,7 +109,7 @@ class WorkflowParser {
             overview = contentAfterMetadata;
         }
         const phases = new Map();
-        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s*/im);
         if (!metadata.phases) {
             metadata.phases = {};
         }

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

@@ -81,7 +81,12 @@ class FraimTemplateEngine {
         return this.userEmail;
     }
     substituteTemplates(content) {
+        return this.substituteTemplatesWithNotices(content).content;
+    }
+    substituteTemplatesWithNotices(content) {
         let result = content;
+        const notices = [];
+        const blockingRequirements = [];
         // Substitute {{proxy.user.email}} with the email captured from fraim_connect
         if (this.userEmail) {
             result = result.replace(/\{\{proxy\.user\.email\}\}/g, this.userEmail);
@@ -103,22 +108,17 @@ class FraimTemplateEngine {
             return match;
         });
         // First, substitute config variables with fallback support.
-        // Fallbacks must work even when local config is unavailable.
-        result = result.replace(/\{\{proxy\.config\.([^}|]+)(?:\s*\|\s*"([^"]+)")?\}\}/g, (match, path, fallback) => {
-            try {
-                if (this.config) {
-                    const value = (0, object_utils_1.getNestedValue)(this.config, path.trim());
-                    if (value !== undefined) {
-                        return typeof value === 'object'
-                            ? JSON.stringify(value)
-                            : String(value);
-                    }
-                }
-                return fallback !== undefined ? fallback : match;
-            }
-            catch (error) {
-                return fallback !== undefined ? fallback : match;
-            }
+        // Supported forms:
+        //   {{proxy.config.path}}
+        //   {{proxy.config.path | "fallback"}}
+        //   {{proxy.config.path | INFORM | "fallback behavior"}}
+        //   {{proxy.config.path | NO_OP | "fallback behavior"}}
+        //   {{proxy.config.path | REQUIRE | "fallback behavior"}}
+        // Note: \s* tolerates optional whitespace inside {{...}} (e.g. from remote server formatting).
+        // This must match the same set of templates that rewriteProxyTokensInText can rewrite,
+        // so that config templates are always resolved here rather than falling through to the fallback rewriter.
+        result = result.replace(/\{\{\s*proxy\.config\.([^}]+?)\s*\}\}/g, (match, expression) => {
+            return this.resolveConfigTemplate(match, expression, notices, blockingRequirements);
         });
         // Second, substitute {{proxy.delivery.*}} templates
         const deliveryValues = this.loadDeliveryTemplates();
@@ -130,7 +130,130 @@ class FraimTemplateEngine {
         }
         // Third, substitute platform-specific action templates
         result = this.substitutePlatformActions(result);
-        return result;
+        return {
+            content: result,
+            notices,
+            blockingRequirements
+        };
+    }
+    resolveConfigTemplate(originalMatch, expression, notices, blockingRequirements) {
+        const segments = this.splitTemplateSegments(expression);
+        if (segments.length === 0)
+            return originalMatch;
+        const path = segments[0].trim();
+        const remainder = segments.slice(1).map(segment => segment.trim()).filter(Boolean);
+        let action = null;
+        let fallback;
+        if (remainder.length === 1) {
+            fallback = this.parseQuotedTemplateValue(remainder[0]);
+            if (fallback === undefined)
+                return originalMatch;
+        }
+        else if (remainder.length === 2) {
+            const candidateAction = remainder[0].toUpperCase();
+            if (!FraimTemplateEngine.CONFIG_TEMPLATE_ACTIONS.has(candidateAction)) {
+                return originalMatch;
+            }
+            fallback = this.parseQuotedTemplateValue(remainder[1]);
+            if (fallback === undefined)
+                return originalMatch;
+            action = candidateAction;
+        }
+        else if (remainder.length > 0) {
+            return originalMatch;
+        }
+        try {
+            if (this.config) {
+                const value = (0, object_utils_1.getNestedValue)(this.config, path);
+                if (value !== undefined) {
+                    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+                }
+            }
+            if (fallback === undefined) {
+                return originalMatch;
+            }
+            if (action === null || action === 'NO_OP') {
+                return fallback;
+            }
+            if (action === 'REQUIRE') {
+                blockingRequirements.push(this.buildMissingConfigNotice(path, action));
+            }
+            else {
+                notices.push(this.buildMissingConfigNotice(path, action));
+            }
+            return fallback;
+        }
+        catch (error) {
+            if (fallback === undefined) {
+                return originalMatch;
+            }
+            if (action === null || action === 'NO_OP') {
+                return fallback;
+            }
+            if (action === 'REQUIRE') {
+                blockingRequirements.push(this.buildMissingConfigNotice(path, action));
+            }
+            else {
+                notices.push(this.buildMissingConfigNotice(path, action));
+            }
+            return fallback;
+        }
+    }
+    splitTemplateSegments(expression) {
+        const segments = [];
+        let current = '';
+        let inQuotes = false;
+        for (let i = 0; i < expression.length; i += 1) {
+            const char = expression[i];
+            const prev = i > 0 ? expression[i - 1] : '';
+            if (char === '"' && prev !== '\\') {
+                inQuotes = !inQuotes;
+                current += char;
+                continue;
+            }
+            if (char === '|' && !inQuotes) {
+                segments.push(current);
+                current = '';
+                continue;
+            }
+            current += char;
+        }
+        segments.push(current);
+        return segments;
+    }
+    parseQuotedTemplateValue(segment) {
+        const trimmed = segment.trim();
+        if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    buildMissingConfigNotice(path, action) {
+        const metadata = FraimTemplateEngine.CONFIG_CONTEXT_METADATA[path];
+        const label = metadata?.label || `config value \`${path}\``;
+        const onboardingHint = metadata?.onboardingHint || `provide \`${path}\` in \`fraim/config.json\``;
+        if (action === 'REQUIRE') {
+            return {
+                action,
+                path,
+                message: `${this.capitalizeFirst(label)} is required for this task but is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint} before continuing.`
+            };
+        }
+        return {
+            action,
+            path,
+            message: `${this.capitalizeFirst(label)} is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint}.`
+        };
+    }
+    capitalizeFirst(value) {
+        if (!value)
+            return value;
+        return value.charAt(0).toUpperCase() + value.slice(1);
     }
     loadDeliveryTemplates() {
         if (this.deliveryTemplatesCache)
@@ -235,6 +358,25 @@ class FraimTemplateEngine {
     }
 }
 exports.FraimTemplateEngine = FraimTemplateEngine;
+FraimTemplateEngine.CONFIG_TEMPLATE_ACTIONS = new Set(['INFORM', 'NO_OP', 'REQUIRE']);
+FraimTemplateEngine.CONFIG_CONTEXT_METADATA = {
+    'customizations.architectureDoc': {
+        label: 'project-specific architecture document',
+        onboardingHint: 'provide the architecture document path in `fraim/config.json`'
+    },
+    'customizations.designSystem.path': {
+        label: 'project-specific design system',
+        onboardingHint: 'provide the design system path in `fraim/config.json`'
+    },
+    compliance: {
+        label: 'project compliance configuration',
+        onboardingHint: 'record the project compliance requirements in `fraim/config.json`'
+    },
+    'compliance.regulations': {
+        label: 'project compliance regulations',
+        onboardingHint: 'record the applicable compliance regulations in `fraim/config.json`'
+    }
+};
 FraimTemplateEngine.PROXY_ACTION_PREFIX = 'proxy.action.';
 FraimTemplateEngine.ISSUE_ACTIONS = new Set([
     'get_issue',
@@ -798,6 +940,11 @@ class FraimLocalMCPServer {
             await this.ensureProviderTemplatesAvailable(processedResponse, requestSessionId);
             processedResponse = this.processResponse(processedResponse);
         }
+        const blockingResponse = this.failForMissingRequiredConfig(processedResponse);
+        if (blockingResponse) {
+            return blockingResponse;
+        }
+        processedResponse = this.prependMissingConfigNotices(processedResponse);
         return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
     }
     async resolveIncludesInResponse(response, requestSessionId, requestId) {
@@ -856,12 +1003,11 @@ class FraimLocalMCPServer {
                         // personalized-employee/ takes priority; when remote fails, resolver falls back to synced/cached content
                         const resolved = await resolver.resolveFile(registryPath).catch(() => null);
                         if (resolved?.content) {
-                            const substitutedContent = this.substituteTemplates(resolved.content);
                             const newResponse = {
                                 ...response,
                                 result: {
                                     ...response.result,
-                                    content: [{ type: 'text', text: substitutedContent }]
+                                    content: [{ type: 'text', text: resolved.content }]
                                 }
                             };
                             delete newResponse.error;
@@ -925,12 +1071,24 @@ class FraimLocalMCPServer {
         const tokens = new Set();
         const rewritten = text.replace(/\{\{\s*proxy\.([^}]+?)\s*\}\}/g, (_match, proxyPath) => {
             const normalized = proxyPath.trim();
+            // proxy.config.* must never reach here — substituteTemplatesWithNotices resolves all of
+            // them (with config values or fallback text). If one slips through it is a bug; strip it
+            // and log rather than rewriting to {{agent.config.*}} which confuses the agent (issue #210).
+            if (normalized.startsWith('config.')) {
+                this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] BUG: unresolved proxy.${normalized} survived processResponse — stripping`);
+                return '';
+            }
             tokens.add(`proxy.${normalized}`);
             return `{{agent.${normalized}}}`;
         });
-        if (tokens.size === 0) {
+        // If nothing changed at all, return early (no allocation, no notice).
+        if (rewritten === text) {
             return { text, tokens: [] };
         }
+        // Only prepend the agent-resolution notice when there are actual agent tokens to resolve.
+        if (tokens.size === 0) {
+            return { text: rewritten, tokens: [] };
+        }
         const hasResolutionNotice = rewritten.includes('## Agent Resolution Needed');
         const finalText = hasResolutionNotice
             ? rewritten
@@ -970,6 +1128,84 @@ class FraimLocalMCPServer {
     substituteTemplates(content) {
         return this.ensureEngine().substituteTemplates(content);
     }
+    prependMissingConfigNotices(response) {
+        if (!response.result?.content || !Array.isArray(response.result.content)) {
+            return response;
+        }
+        const contentBlocks = response.result.content;
+        const firstTextIndex = contentBlocks.findIndex((block) => block?.type === 'text' && typeof block.text === 'string');
+        if (firstTextIndex === -1) {
+            return response;
+        }
+        const existingText = contentBlocks[firstTextIndex].text;
+        const notices = response.result.__proxyMissingConfigNotices;
+        if (!notices || notices.length === 0) {
+            return response;
+        }
+        const uniqueNotices = [];
+        const seen = new Set();
+        for (const notice of notices) {
+            const key = `${notice.action}:${notice.path}:${notice.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            uniqueNotices.push(notice);
+        }
+        if (uniqueNotices.length === 0) {
+            return response;
+        }
+        const noticeLines = ['## Missing Project Context'];
+        for (const notice of uniqueNotices) {
+            noticeLines.push(`- ${notice.message}`);
+        }
+        const prefix = `${noticeLines.join('\n')}\n\n---\n\n`;
+        const transformedContent = contentBlocks.map((block, index) => {
+            if (index !== firstTextIndex)
+                return block;
+            return {
+                ...block,
+                text: prefix + existingText
+            };
+        });
+        const { __proxyMissingConfigNotices, ...restResult } = response.result;
+        return {
+            ...response,
+            result: {
+                ...restResult,
+                content: transformedContent
+            }
+        };
+    }
+    failForMissingRequiredConfig(response) {
+        const requirements = response.result?.__proxyMissingConfigRequirements;
+        if (!requirements || requirements.length === 0) {
+            return null;
+        }
+        const uniqueRequirements = [];
+        const seen = new Set();
+        for (const requirement of requirements) {
+            const key = `${requirement.action}:${requirement.path}:${requirement.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            uniqueRequirements.push(requirement);
+        }
+        const messageLines = ['Required project context is missing:'];
+        for (const requirement of uniqueRequirements) {
+            messageLines.push(`- ${requirement.message}`);
+        }
+        return {
+            jsonrpc: response.jsonrpc,
+            id: response.id ?? null,
+            error: {
+                code: -32003,
+                message: messageLines.join('\n'),
+                data: {
+                    missingConfigPaths: uniqueRequirements.map((requirement) => requirement.path)
+                }
+            }
+        };
+    }
     /**
      * Initialize the LocalRegistryResolver for override resolution
      */
@@ -1057,10 +1293,15 @@ class FraimLocalMCPServer {
     processResponse(response) {
         if (!response.result)
             return response;
+        const notices = [];
+        const blockingRequirements = [];
         // Recursively substitute templates in all string values
         const processValue = (value) => {
             if (typeof value === 'string') {
-                return this.substituteTemplates(value);
+                const substitution = this.ensureEngine().substituteTemplatesWithNotices(value);
+                notices.push(...substitution.notices);
+                blockingRequirements.push(...substitution.blockingRequirements);
+                return substitution.content;
             }
             else if (Array.isArray(value)) {
                 return value.map(processValue);
@@ -1074,14 +1315,25 @@ class FraimLocalMCPServer {
             }
             return value;
         };
+        const processedResult = processValue(response.result);
+        if (notices.length > 0 && processedResult && typeof processedResult === 'object') {
+            processedResult.__proxyMissingConfigNotices = notices;
+        }
+        if (blockingRequirements.length > 0 && processedResult && typeof processedResult === 'object') {
+            processedResult.__proxyMissingConfigRequirements = blockingRequirements;
+        }
         return {
             ...response,
-            result: processValue(response.result)
+            result: processedResult
         };
     }
     applyAgentFallbackForUnresolvedProxy(response) {
         if (!response.result)
             return response;
+        // Rewrite any unresolved {{proxy.*}} placeholders to {{agent.*}} so the agent can
+        // handle them. proxy.config.* is excluded inside rewriteProxyTokensInText — those
+        // must have been fully resolved by substituteTemplatesWithNotices; any that survive
+        // are bugs and get stripped with a log warning rather than rewritten.
         const rewritten = this.rewriteUnresolvedProxyPlaceholders(response.result);
         if (rewritten.tokens.length > 0) {
             this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] Rewrote unresolved proxy placeholders to agent placeholders: ${rewritten.tokens.join(', ')}`);
@@ -1249,7 +1501,30 @@ class FraimLocalMCPServer {
             // Resolve templates in the outgoing request so the remote server 
             // only ever sees finalized values.
             const stringifiedRequest = JSON.stringify(request);
-            const resolvedRequestStr = this.substituteTemplates(stringifiedRequest);
+            const requestSubstitution = this.ensureEngine().substituteTemplatesWithNotices(stringifiedRequest);
+            if (requestSubstitution.blockingRequirements.length > 0) {
+                const uniqueRequirements = [];
+                const seen = new Set();
+                for (const requirement of requestSubstitution.blockingRequirements) {
+                    const key = `${requirement.action}:${requirement.path}:${requirement.message}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    uniqueRequirements.push(requirement);
+                }
+                return {
+                    jsonrpc: '2.0',
+                    id: request.id,
+                    error: {
+                        code: -32003,
+                        message: ['Required project context is missing:', ...uniqueRequirements.map((requirement) => `- ${requirement.message}`)].join('\n'),
+                        data: {
+                            missingConfigPaths: uniqueRequirements.map((requirement) => requirement.path)
+                        }
+                    }
+                };
+            }
+            const resolvedRequestStr = requestSubstitution.content;
             const finalRequest = JSON.parse(resolvedRequestStr);
             const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, finalRequest, {
                 headers,

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

@@ -10,8 +10,8 @@ const axios_1 = __importDefault(require("axios"));
 // The server will override this with the correct ID from the authenticated API key.
 const PLACEHOLDER_API_KEY_ID = new mongodb_1.ObjectId('000000000000000000000000');
 /**
- * Usage event collector for local MCP proxy
- * Collects usage events and batches them for upload
+ * UsageCollector is responsible for collecting usage events from MCP tools
+ * and formatting them for the analytics system.
  */
 class UsageCollector {
     constructor() {
@@ -53,19 +53,24 @@ class UsageCollector {
             return;
         }
         // Extract useful args for analytics
-        const analyticsArgs = this.extractAnalyticsArgs(toolName, args);
+        const analyticsArgs = this.extractAnalyticsArgs(toolName, args) || {};
+        // Ensure category from path parsing is included in args
+        if (parsed.category && !analyticsArgs.category) {
+            analyticsArgs.category = parsed.category;
+        }
         const event = {
             type: parsed.type,
             name: parsed.name,
             // Use set apiKeyId if available, otherwise a placeholder.
-            // The server will override this with the correct value from the auth token.
+            // The server will override this with the correct ID from the authenticated API key.
             apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
             sessionId,
             success,
-            args: analyticsArgs
+            category: parsed.category,
+            args: Object.keys(analyticsArgs).length > 0 ? analyticsArgs : undefined
         };
         this.events.push(event);
-        const successMsg = `[UsageCollector] ✅ Collected event: ${parsed.type}/${parsed.name} (session: ${sessionId}, queue: ${this.events.length})`;
+        const successMsg = `[UsageCollector] ✅ Collected event: ${parsed.type}/${parsed.name} (category: ${parsed.category || 'none'}, session: ${sessionId}, queue: ${this.events.length})`;
         console.error(successMsg);
         // Also log to stderr for better visibility in main logs
         process.stderr.write(successMsg + '\n');
@@ -73,10 +78,11 @@ class UsageCollector {
     /**
      * Collect usage event directly (for backward compatibility with tests)
      */
-    collectEvent(type, name, sessionId, success = true, args) {
+    collectEvent(type, name, sessionId, success = true, args, category) {
         const event = {
             type,
             name,
+            category,
             // Use set apiKeyId if available, otherwise a placeholder.
             // The server will override this with the correct value from the auth token.
             apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
@@ -138,16 +144,18 @@ class UsageCollector {
     parseMCPCall(toolName, args) {
         switch (toolName) {
             case 'get_fraim_job':
-                return { type: 'job', name: args.job || 'unknown' };
+                const jobPath = args.job || 'unknown';
+                const parsedJob = this.parseComponentName(jobPath);
+                return parsedJob || { type: 'job', name: jobPath };
             case 'get_fraim_file':
                 if (args.path) {
-                    return UsageCollector.parseComponentName(args.path);
+                    return this.parseComponentName(args.path);
                 }
                 return null;
             case 'seekMentoring':
-                return { type: 'mentoring', name: UsageCollector.resolveMentoringJobName(args) };
+                return { type: 'mentoring', name: UsageCollector.resolveMentoringJobName(args), category: 'mentoring' };
             case 'list_fraim_jobs':
-                return { type: 'job', name: 'list' };
+                return { type: 'job', name: 'list', category: 'none' };
             case 'fraim_connect':
                 return { type: 'session', name: 'connect' };
             default:
@@ -226,37 +234,47 @@ class UsageCollector {
     /**
      * Parse component name from file path
      */
-    static parseComponentName(path) {
-        // Normalize path to have leading slash for consistent regex matching
-        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-        // Match skills files: /skills/category/skill-name.md
-        if (normalizedPath.includes('/skills/')) {
-            const skillMatch = normalizedPath.match(/\/skills\/[^/]+\/([^/]+)\.md$/);
-            if (skillMatch) {
-                return { type: 'skill', name: skillMatch[1] };
-            }
+    parseComponentName(path) {
+        if (!path || typeof path !== 'string')
+            return null;
+        // Clean path: handle backslashes, optional 'registry/' prefix
+        let cleanPath = path.replace(/\\/g, '/');
+        cleanPath = cleanPath.replace(/^(registry\/)/, '');
+        if (cleanPath.startsWith('/'))
+            cleanPath = cleanPath.substring(1);
+        const parts = cleanPath.split('/');
+        const fileName = parts[parts.length - 1];
+        // If it doesn't end in .md, it might still be a job name (e.g. from get_fraim_job)
+        if (!fileName.endsWith('.md')) {
+            return null;
         }
-        // Match job files: /jobs/category/subcategory/job-name.md
-        if (normalizedPath.includes('/jobs/')) {
-            const jobMatch = normalizedPath.match(/\/jobs\/[^/]+\/[^/]+\/([^/]+)\.md$/);
-            if (jobMatch) {
-                return { type: 'job', name: jobMatch[1] };
-            }
+        const name = fileName.replace(/\.md$/, '');
+        const typeStr = parts[0];
+        // Match skills files
+        if (typeStr === 'skills') {
+            // Structure: skills/category/name.md or skills/name.md
+            // Category is the directory immediately following 'skills'
+            const category = parts.length > 2 ? parts[1] : undefined;
+            return { type: 'skill', name, category };
         }
-        // Match rule files: /rules/category/rule-name.md
-        if (normalizedPath.includes('/rules/')) {
-            const ruleMatch = normalizedPath.match(/\/rules\/[^/]+\/([^/]+)\.md$/);
-            if (ruleMatch) {
-                return { type: 'rule', name: ruleMatch[1] };
+        // Match job files
+        if (typeStr === 'jobs') {
+            // Structure: jobs/ai-employee/category/name.md
+            // Or: jobs/category/name.md
+            let category;
+            if (parts[1] === 'ai-employee' || parts[1] === 'ai-manager' || parts[1] === 'personalized-employee') {
+                category = parts[2]; // e.g. jobs/ai-employee/product-building/job.md -> product-building
+            }
+            else if (parts.length > 2) {
+                category = parts[1]; // e.g. jobs/legal/job.md -> legal
             }
+            return { type: 'job', name, category };
         }
-        // For other paths that don't match the expected patterns, 
-        // we'll classify them as 'job' type with a generic name
-        // This ensures we track usage even for non-standard paths
-        const fileName = normalizedPath.split('/').pop();
-        if (fileName && fileName.endsWith('.md')) {
-            const baseName = fileName.replace(/\.md$/, '');
-            return { type: 'job', name: baseName };
+        // Match rule files (already defined in UsageEventType)
+        if (typeStr === 'rules') {
+            // Structure: rules/category/name.md or rules/name.md
+            const category = parts.length > 2 ? parts[1] : undefined;
+            return { type: 'rule', name, category };
         }
         return null;
     }

package/index.js

@@ -1,85 +1,85 @@
-#!/usr/bin/env node
-
-/**
- * FRAIM Framework - Smart Entry Point
- * This file handles both production (dist/) and development (src/) environments.
- */
-
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-
-/**
- * Runs the CLI using either the compiled JS or the source TS via tsx
- */
-function runCLI() {
-    const distPath = path.join(__dirname, 'dist', 'src', 'cli', 'fraim.js');
-    const srcPath = path.join(__dirname, 'src', 'cli', 'fraim.ts');
-
-    // 1. Check if we have a compiled version (Production / CI)
-    if (fs.existsSync(distPath)) {
-        require(distPath);
-        return;
-    }
-
-    // 2. Explicitly fail in production if dist/ is missing
-    if (process.env.NODE_ENV === 'production') {
-        console.error('❌ FRAIM Error: Production build (dist/) not found.');
-        console.error('In production environments, you must run the compiled version.');
-        console.error(`Expected: ${distPath}`);
-        process.exit(1);
-    }
-
-    // 3. Fallback to source version using tsx (Development)
-    if (fs.existsSync(srcPath)) {
-        // We use spawnSync to run tsx so we don't have to require it in memory
-        // if it's not needed, and it handles the process arguments correctly.
-        // 
-        // IMPORTANT FIX: Directory names with spaces and dashes (e.g., "FRAIM - Issue 166")
-        // cause argument parsing issues on Windows when shell: true is used.
-        // Without quoting, a path like "C:\...\FRAIM - Issue 166\src\cli\fraim.ts" gets
-        // split into multiple arguments, with the dash interpreted as a command flag,
-        // resulting in "error: unknown command '-'".
-        // 
-        // Solution: On Windows with shell: true, quote paths containing spaces.
-        // On Unix with shell: false, pass the path unquoted (spawnSync handles it correctly).
-        const isWindows = process.platform === 'win32';
-
-        // On Windows with shell, quote paths with spaces to prevent shell misinterpretation
-        // On Unix without shell, pass path as-is (spawnSync handles spaces correctly)
-        const processedSrcPath = (isWindows && srcPath.includes(' '))
-            ? `"${srcPath}"`
-            : srcPath;
-
-        const result = spawnSync(
-            'npx',
-            ['tsx', processedSrcPath, ...process.argv.slice(2)],
-            {
-                stdio: 'inherit',
-                shell: isWindows, // Windows needs shell for npx, Unix doesn't
-                windowsHide: true
-            }
-        );
-        process.exit(result.status || 0);
-    }
-
-    console.error('❌ FRAIM Error: Could not find CLI entry point.');
-    console.error('Expected one of:');
-    console.error(` - ${distPath}`);
-    console.error(` - ${srcPath}`);
-    process.exit(1);
-}
-
-// Global programmatic exports
-module.exports = {
-    FRAIM_INFO: {
-        name: 'FRAIM',
-        version: '2.0.98',
-        repository: 'https://github.com/mathursrus/FRAIM'
-    }
-};
-
-// If this file is run directly (via npx or global link), run the CLI
-if (require.main === module) {
-    runCLI();
+#!/usr/bin/env node
+
+/**
+ * FRAIM Framework - Smart Entry Point
+ * This file handles both production (dist/) and development (src/) environments.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+/**
+ * Runs the CLI using either the compiled JS or the source TS via tsx
+ */
+function runCLI() {
+    const distPath = path.join(__dirname, 'dist', 'src', 'cli', 'fraim.js');
+    const srcPath = path.join(__dirname, 'src', 'cli', 'fraim.ts');
+
+    // 1. Check if we have a compiled version (Production / CI)
+    if (fs.existsSync(distPath)) {
+        require(distPath);
+        return;
+    }
+
+    // 2. Explicitly fail in production if dist/ is missing
+    if (process.env.NODE_ENV === 'production') {
+        console.error('❌ FRAIM Error: Production build (dist/) not found.');
+        console.error('In production environments, you must run the compiled version.');
+        console.error(`Expected: ${distPath}`);
+        process.exit(1);
+    }
+
+    // 3. Fallback to source version using tsx (Development)
+    if (fs.existsSync(srcPath)) {
+        // We use spawnSync to run tsx so we don't have to require it in memory
+        // if it's not needed, and it handles the process arguments correctly.
+        // 
+        // IMPORTANT FIX: Directory names with spaces and dashes (e.g., "FRAIM - Issue 166")
+        // cause argument parsing issues on Windows when shell: true is used.
+        // Without quoting, a path like "C:\...\FRAIM - Issue 166\src\cli\fraim.ts" gets
+        // split into multiple arguments, with the dash interpreted as a command flag,
+        // resulting in "error: unknown command '-'".
+        // 
+        // Solution: On Windows with shell: true, quote paths containing spaces.
+        // On Unix with shell: false, pass the path unquoted (spawnSync handles it correctly).
+        const isWindows = process.platform === 'win32';
+
+        // On Windows with shell, quote paths with spaces to prevent shell misinterpretation
+        // On Unix without shell, pass path as-is (spawnSync handles spaces correctly)
+        const processedSrcPath = (isWindows && srcPath.includes(' '))
+            ? `"${srcPath}"`
+            : srcPath;
+
+        const result = spawnSync(
+            'npx',
+            ['tsx', processedSrcPath, ...process.argv.slice(2)],
+            {
+                stdio: 'inherit',
+                shell: isWindows, // Windows needs shell for npx, Unix doesn't
+                windowsHide: true
+            }
+        );
+        process.exit(result.status || 0);
+    }
+
+    console.error('❌ FRAIM Error: Could not find CLI entry point.');
+    console.error('Expected one of:');
+    console.error(` - ${distPath}`);
+    console.error(` - ${srcPath}`);
+    process.exit(1);
+}
+
+// Global programmatic exports
+module.exports = {
+    FRAIM_INFO: {
+        name: 'FRAIM',
+        version: '2.0.98',
+        repository: 'https://github.com/mathursrus/FRAIM'
+    }
+};
+
+// If this file is run directly (via npx or global link), run the CLI
+if (require.main === module) {
+    runCLI();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.100",
+  "version": "2.0.101",
   "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": {
@@ -16,9 +16,10 @@
     "test-all": "npm run test && npm run test:isolated && npm run test:ui",
     "test": "node scripts/test-with-server.js",
     "test:isolated": "npx tsx --test --test-reporter=spec tests/isolated/test-*.ts",
-    "test:smoke": "node scripts/test-with-server.js tests/test-*.ts --tags=smoke",
+    "test:smoke": "node scripts/test-with-server.js --tags=smoke",
     "test:stripe": "node scripts/test-with-server.js tests/test-stripe-payment-complete.ts",
     "test:stripe:ui": "playwright test tests/ui/test-payment-ui.spec.ts",
+    "test:perf": "node scripts/test-with-server.js tests/performance/analytics-perf.ts",
     "test:ui": "playwright test",
     "test:ui:headed": "playwright test --headed",
     "start:fraim": "tsx src/fraim-mcp-server.ts",
@@ -26,6 +27,7 @@
     "serve:website": "node fraim-pro/serve.js",
     "watch:fraimlogs": "tsx scripts/watch-fraim-logs.ts > prodlogs.log 2>&1",
     "manage-keys": "tsx scripts/fraim/manage-keys.ts",
+    "manage-teams": "tsx scripts/fraim/manage-teams.ts",
     "partner-discounts": "tsx scripts/fraim/manage-partner-discounts.ts",
     "fix-key": "tsx scripts/fraim/fix-expired-key.ts",
     "setup-stripe-webhook": "tsx scripts/fraim/setup-stripe-webhook.ts",
@@ -89,6 +91,7 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/node": "^20.0.0",
+    "@types/node-fetch": "^2.6.13",
     "@types/prompts": "^2.4.9",
     "@types/semver": "^7.7.1",
     "fast-glob": "^3.3.3",
@@ -119,6 +122,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@octokit/rest": "^22.0.1",
     "adm-zip": "^0.5.16",
     "axios": "^1.7.0",
     "chalk": "4.1.2",
@@ -128,6 +132,7 @@
     "express": "^5.2.1",
     "mongodb": "^7.0.0",
     "node-edge-tts": "^1.2.10",
+    "nodemailer": "^8.0.3",
     "prompts": "^2.4.2",
     "resend": "^6.9.3",
     "semver": "^7.7.4",