fraim-framework 2.0.100 → 2.0.102

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/setup.js

@@ -594,7 +594,7 @@ const runSetup = async (options) => {
     console.log(chalk_1.default.cyan('\n📝 For future projects:'));
     console.log(chalk_1.default.cyan('   1. cd into any project directory'));
     console.log(chalk_1.default.cyan('   2. Run: fraim init-project'));
-    console.log(chalk_1.default.cyan('   3. Tell your AI agent: "Onboard this project"'));
+    console.log(chalk_1.default.cyan('   3. Ask your AI agent: "FRAIM was just installed. Read the FRAIM docs, explain what it can do for me, then run project-onboarding."'));
     if (mode === 'integrated') {
         const allProviderIds = await (0, provider_registry_1.getAllProviderIds)();
         const unconfiguredProviders = allProviderIds.filter(id => !tokens[id]);

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/agent-adapters.js

@@ -10,6 +10,7 @@ const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const START_MARKER = '<!-- FRAIM_AGENT_ADAPTER_START -->';
 const END_MARKER = '<!-- FRAIM_AGENT_ADAPTER_END -->';
 const CURSOR_RULE_PATH = path_1.default.join('.cursor', 'rules', 'fraim.mdc');
+const CLAUDE_FRAIM_COMMAND_PATH = path_1.default.join('.claude', 'commands', 'fraim.md');
 const CURSOR_FRONTMATTER = `---
 description: FRAIM discovery and execution contract
 alwaysApply: true
@@ -59,9 +60,13 @@ This repository uses FRAIM.
 - Skills under \`${employeeSkillsPath}/\` are reusable capabilities that jobs compose.
 - Rules under \`${employeeRulesPath}/\` are always-on constraints and conventions.
 - Repo-specific overrides and learning artifacts live under \`${personalizedRootPath}/\` and take precedence over synced baseline content.
-- Use stub filenames and summaries to discover what to invoke. Once you identify a relevant job, call \`get_fraim_job({ job: "<job-name>" })\`.
+- Before acting on any user request, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections to match the request to the right job.
+- Once you identify the relevant job, call \`get_fraim_job({ job: "<job-name>" })\` to get the full phased instructions.
 - For deeper capability detail, call \`get_fraim_file({ path: "skills/<category>/<skill-name>.md" })\` or \`get_fraim_file({ path: "rules/<category>/<rule-name>.md" })\`.
 - Read \`${projectRulesPath}\` if it exists before doing work.
+
+> [!IMPORTANT]
+> **Job stubs are for discovery only.** When a user @mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
 `);
     const cursorManagedBody = buildManagedSection(`
 Use FRAIM as the repo's execution framework.
@@ -72,6 +77,7 @@ Use FRAIM as the repo's execution framework.
 - Rules are always-on constraints.
 - Repo-specific overrides and learnings under \`${personalizedRootPath}/\` take precedence.
 - Choose a relevant job from the stubs, then call \`get_fraim_job(...)\` for the full phased instructions.
+- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const copilotBody = buildManagedSection(`
 ## FRAIM
@@ -82,6 +88,7 @@ Use FRAIM as the repo's execution framework.
 - FRAIM rules are always-on constraints and conventions.
 - Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
 - Use the stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- **Job stubs are for discovery only.** Never execute a job from stub content — always call \`get_fraim_job({ job: "<job-name>" })\` first.
 `);
     const fraimReadme = `# FRAIM Catalog
 
@@ -94,13 +101,26 @@ This directory is the repository-visible FRAIM surface.
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
 Use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools.
+`;
+    const claudeCommand = `The user wants to run FRAIM. The requested job or topic is: $ARGUMENTS
+
+Follow this process:
+
+1. **If no argument was given** (the line above ends with ": "): scan all stub files under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\`. List each by filename and its Intent line. Ask the user which job they want to run, then proceed to step 2.
+
+2. **Find the job**: search \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` for a stub whose filename (without \`.md\`) matches or closely resembles the argument. Read the stub's Intent/Outcome to confirm it matches what the user wants.
+
+3. **Load the full job**: call \`get_fraim_job({ job: "<matched-job-name>" })\` — never execute from stub content.
+
+4. **Execute**: follow the phased instructions returned by \`get_fraim_job\`, using \`seekMentoring\` at phase transitions where indicated.
 `;
     return [
         { path: 'AGENTS.md', content: markdownBody },
         { path: 'CLAUDE.md', content: markdownBody },
         { path: path_1.default.join('.github', 'copilot-instructions.md'), content: copilotBody },
         { path: CURSOR_RULE_PATH, content: cursorManagedBody },
-        { path: path_1.default.join(project_fraim_paths_1.WORKSPACE_FRAIM_DIRNAME, 'README.md'), content: fraimReadme }
+        { path: path_1.default.join(project_fraim_paths_1.WORKSPACE_FRAIM_DIRNAME, 'README.md'), content: fraimReadme },
+        { path: CLAUDE_FRAIM_COMMAND_PATH, content: claudeCommand }
     ];
 }
 function ensureAgentAdapterFiles(projectRoot) {
@@ -114,7 +134,7 @@ function ensureAgentAdapterFiles(projectRoot) {
         const existing = fs_1.default.existsSync(fullPath) ? fs_1.default.readFileSync(fullPath, 'utf8') : '';
         const next = file.path === CURSOR_RULE_PATH
             ? mergeCursorRule(existing, file.content)
-            : file.path.endsWith('README.md')
+            : file.path.endsWith('README.md') || file.path === CLAUDE_FRAIM_COMMAND_PATH
                 ? file.content
                 : mergeManagedSection(existing, file.content);
         if (existing !== next) {

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/cli/utils/version-utils.js

@@ -10,12 +10,11 @@ function getFraimVersion() {
     // Try reliable paths to find package.json relative to this file
     // locally: src/cli/utils/version-utils.ts -> package.json is ../../../package.json
     // dist: dist/src/cli/utils/version-utils.js -> package.json is ../../../../package.json
-    const possiblePaths = [
-        path_1.default.join(__dirname, '../../../package.json'), // Local dev (src)
-        path_1.default.join(__dirname, '../../../../package.json'), // Dist (dist/src)
-        path_1.default.join(process.cwd(), 'package.json') // Fallback to CWD
-    ];
-    for (const pkgPath of possiblePaths) {
+    // Traverse up from __dirname until we find fraim-framework's package.json.
+    // Fixed relative paths break when npx cache layouts differ across OS/npm versions.
+    let dir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path_1.default.join(dir, 'package.json');
         if (fs_1.default.existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf-8'));
@@ -27,6 +26,10 @@ function getFraimVersion() {
                 // Ignore parsing errors
             }
         }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break; // Reached filesystem root
+        dir = parent;
     }
-    return '1.0.0'; // Fallback
+    return 'unknown'; // Do not return a fake version — unknown is safer than misleading
 }

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 = {};
         }