faf-mcp 2.3.1 → 3.0.1

package/dist/src/handlers/tools.js

@@ -38,7 +38,6 @@ const fileHandler_1 = require("./fileHandler");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const pathModule = __importStar(require("path"));
-const fuzzy_detector_1 = require("../utils/fuzzy-detector");
 const faf_file_finder_js_1 = require("../utils/faf-file-finder.js");
 const safe_path_1 = require("../utils/safe-path");
 const version_1 = require("../version");
@@ -49,12 +48,12 @@ const path_resolver_1 = require("../utils/path-resolver");
 // scoring or the tier ladder here — that's exactly the drift v2.1.0 set out
 // to kill across the surface; v2.1.1 closes the loop on the active handler.
 //
-// Imported via ../utils/faf-cli-bridge.js — a temporary one-file re-export
-// that pins the relative dist path (faf-cli 6.7.1's `bun` exports condition
-// resolves to a non-shipped src/, breaking the test runner). Both Node and
-// Bun load the same compiled module through the bridge. Bridge is removable
-// once faf-cli drops the bad `bun` condition. See the bridge header for full
-// rationale and the linked tracked issue.
+// Imported via ../utils/faf-cli-bridge.js — a one-file re-export that pins
+// the relative dist path. It began as a workaround for faf-cli 6.7.1's `bun`
+// exports condition (pointed at a non-shipped src/); 6.8.0 dropped it and
+// 7.12.0 exports only `types`/`default`. Node and Bun load the same compiled
+// module through the bridge, which stays for the CJS-to-ESM load and
+// bundledFafCliVersion()'s path-walk. See the bridge header for the rationale.
 const faf_cli_bridge_js_1 = require("../utils/faf-cli-bridge.js");
 const turbocat_bridge_js_1 = require("../faf-core/extract/turbocat-bridge.js");
 /**
@@ -66,8 +65,8 @@ const turbocat_bridge_js_1 = require("../faf-core/extract/turbocat-bridge.js");
  * the 40%-MIN rule means one weak tool on the surface caps the whole server.
  *
  * Spine mirrors claude-faf-mcp's proven-A Core; the interop quad
- * (faf_bi_sync + faf_agents/faf_cursor/faf_gemini) is this edition's identity —
- * the Cursor / IDE multi-format sync — where CFM carries memory tools instead.
+ * (faf_claude + faf_agents/faf_cursor/faf_gemini) is this edition's identity —
+ * the Cursor / IDE multi-format write — where CFM carries memory tools instead.
  * See PLANET-FAF/strategy/claude-faf-mcp-core-tier-glama-a-2026-06-17.md.
  */
 const CORE_TOOLS = new Set([
@@ -75,7 +74,7 @@ const CORE_TOOLS = new Set([
     'faf_init', 'faf_auto', 'faf_go', 'faf_score', 'faf_doctor',
     'faf_sync', 'faf_context', 'faf_trust', 'faf_about',
     // IDE-edition interop — the differentiator
-    'faf_bi_sync', 'faf_agents', 'faf_cursor', 'faf_gemini',
+    'faf_claude', 'faf_agents', 'faf_cursor', 'faf_gemini',
     // Craft-grade utility
     'faf_check', 'faf_git',
 ]);
@@ -206,9 +205,9 @@ class FafToolHandler {
             },
             {
                 name: 'faf_sync',
-                description: 'Sync a project.faf with CLAUDE.md so the two stay aligned. Returns what was written. Use this for the single CLAUDE.md target; use faf_bi_sync to fan out to AGENTS.md, .cursorrules, and GEMINI.md as well.',
+                description: 'Reconcile project.faf with what the repo manifests say now (package.json name, description, framework dependencies). Dry-run by default: reports the fields that would change. Pass apply:true to write them into project.faf. Does not touch CLAUDE.md — use faf_claude for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md.',
                 annotations: {
-                    title: 'Sync .faf to CLAUDE.md',
+                    title: 'Reconcile .faf with repo manifests',
                     readOnlyHint: false,
                     destructiveHint: false,
                     openWorldHint: false
@@ -216,16 +215,17 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
+                        apply: { type: 'boolean', description: 'Write the detected changes into project.faf (default: dry-run report only)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     additionalProperties: false
                 }
             },
             {
-                name: 'faf_bi_sync',
-                description: 'Bi-directionally sync a project.faf with CLAUDE.md and, with the format flags or all, also AGENTS.md, .cursorrules, and GEMINI.md. Returns the formats written and any conflicts. Use this to keep every AI tool context file aligned from the single .faf source.',
+                name: 'faf_claude',
+                description: 'Write CLAUDE.md from project.faf (one direction: .faf → CLAUDE.md) and, with the format flags or all, also AGENTS.md, .cursorrules and GEMINI.md. Content outside the faf-managed block is preserved. Returns the files written. Use this to keep every AI tool\'s context file current from one source. (Named faf_bi_sync before 3.0.1; that name still works.)',
                 annotations: {
-                    title: 'Bi-directional Sync',
+                    title: 'Write CLAUDE.md and IDE formats from .faf',
                     readOnlyHint: false,
                     destructiveHint: false,
                     openWorldHint: false
@@ -233,13 +233,10 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        auto: { type: 'boolean', description: 'Enable automatic synchronization' },
-                        watch: { type: 'boolean', description: 'Start real-time file watching for changes' },
-                        force: { type: 'boolean', description: 'Force overwrite conflicting changes' },
-                        agents: { type: 'boolean', description: 'Also sync to AGENTS.md (OpenAI/Codex format)' },
-                        cursor: { type: 'boolean', description: 'Also sync to .cursorrules (Cursor IDE format)' },
-                        gemini: { type: 'boolean', description: 'Also sync to GEMINI.md (Google Gemini format)' },
-                        all: { type: 'boolean', description: 'Sync to ALL formats: CLAUDE.md + AGENTS.md + .cursorrules + GEMINI.md' },
+                        agents: { type: 'boolean', description: 'Also write AGENTS.md (OpenAI/Codex format)' },
+                        cursor: { type: 'boolean', description: 'Also write .cursorrules (Cursor IDE format)' },
+                        gemini: { type: 'boolean', description: 'Also write GEMINI.md (Google Gemini format)' },
+                        all: { type: 'boolean', description: 'Write ALL formats: CLAUDE.md + AGENTS.md + .cursorrules + GEMINI.md' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     additionalProperties: false
@@ -247,7 +244,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_clear',
-                description: 'Clear caches, temporary files, and reset FAF state for a fresh start',
+                description: 'Remove the ~/.faf-cli-cache directory left by older faf-mcp versions. This version persists nothing outside your project files.',
                 annotations: {
                     title: 'Clear .faf Data',
                     readOnlyHint: false,
@@ -257,17 +254,15 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        cache: { type: 'boolean', description: 'Clear trust cache only' },
-                        todos: { type: 'boolean', description: 'Clear todo lists only' },
-                        backups: { type: 'boolean', description: 'Clear backup files only' },
-                        all: { type: 'boolean', description: 'Clear everything (default)' }
+                        cache: { type: 'boolean', description: 'Remove ~/.faf-cli-cache (written by faf-mcp < 3.0)' },
+                        all: { type: 'boolean', description: 'Remove everything older versions persisted (default; today that is the cache)' }
                     },
                     additionalProperties: false
                 }
             },
             {
                 name: 'faf_debug',
-                description: 'Debug faf-mcp environment - show working directory, permissions, and FAF CLI status',
+                description: 'Debug faf-mcp environment - show working directory, write permissions, the bundled faf-cli version, and whether a project.faf is present',
                 annotations: {
                     title: 'Debug Info',
                     readOnlyHint: true,
@@ -476,7 +471,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_auto',
-                description: 'Run the full setup pipeline in one call — init, stack detection, sync, bi-sync, and score — taking a project from no context to a complete project.faf. Returns the final AI-readiness score and what was created. Use this as the fast path on a fresh project; use the individual tools when you need finer control.',
+                description: 'Run the full setup pipeline in one call — init, stack detection, sync, CLAUDE.md, and score — taking a project from no context to a complete project.faf. Returns the final AI-readiness score and what was created. Use this as the fast path on a fresh project; use the individual tools when you need finer control.',
                 annotations: {
                     title: 'Auto-detect Context',
                     readOnlyHint: false,
@@ -486,15 +481,17 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
-                        force: { type: 'boolean', description: 'Force overwrite existing files' }
+                        path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        // `force` used to be declared here; handleFafAuto never read it.
+                        // faf_auto merges into an existing project.faf non-destructively
+                        // and there is no overwrite mode to switch on.
                     },
                     additionalProperties: false
                 }
             },
             {
                 name: 'faf_dna',
-                description: 'Show your FAF DNA journey - See your evolution from birth to championship (22% 85% 99%)',
+                description: 'Show your FAF DNA journey — the score evolution of this project.faf from birth to today (e.g. 22% → 85% → 100%)',
                 annotations: {
                     title: 'View Project DNA',
                     readOnlyHint: true,
@@ -562,11 +559,11 @@ class FafToolHandler {
                 }
             },
             // ============================================================================
-            // v4.5.0 INTEROP TOOLS
+            // INTEROP TOOLS — landed in faf-mcp 2.0.0 (The Interop MCP for Context); ported from faf-cli 4.5.0 via claude-faf-mcp 4.5.0
             // ============================================================================
             {
                 name: 'faf_agents',
-                description: 'Import, export, or sync context between AGENTS.md (the OpenAI/Codex convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement from one source.',
+                description: 'Import AGENTS.md (the OpenAI/Codex convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement from one source.',
                 annotations: {
                     title: 'Sync AGENTS.md',
                     readOnlyHint: false,
@@ -576,7 +573,7 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (AGENTS.md -> .faf), export (.faf -> AGENTS.md), sync (bidirectional)' },
+                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (AGENTS.md -> .faf; merge:true writes it into project.faf), export (.faf -> AGENTS.md), sync (re-writes AGENTS.md from .faf; export with force)' },
                         force: { type: 'boolean', description: 'Force overwrite existing files' },
                         merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
@@ -587,7 +584,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_cursor',
-                description: 'Import, export, or sync context between .cursorrules (the Cursor IDE convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep Cursor rules and your .faf in agreement from one source.',
+                description: 'Import .cursorrules (the Cursor IDE convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep Cursor rules and your .faf in agreement from one source.',
                 annotations: {
                     title: 'Sync .cursorrules',
                     readOnlyHint: false,
@@ -597,7 +594,7 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (.cursorrules -> .faf), export (.faf -> .cursorrules), sync (bidirectional)' },
+                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (.cursorrules -> .faf; merge:true writes it into project.faf), export (.faf -> .cursorrules), sync (re-writes .cursorrules from .faf; export with force)' },
                         force: { type: 'boolean', description: 'Force overwrite existing files' },
                         merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
@@ -608,7 +605,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_gemini',
-                description: 'Import, export, or sync context between GEMINI.md (the Google Gemini CLI convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep a Gemini context file and your .faf in agreement from one source.',
+                description: 'Import GEMINI.md (the Google Gemini CLI convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep a Gemini context file and your .faf in agreement from one source.',
                 annotations: {
                     title: 'Sync GEMINI.md',
                     readOnlyHint: false,
@@ -618,7 +615,7 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (GEMINI.md -> .faf), export (.faf -> GEMINI.md), sync (bidirectional)' },
+                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (GEMINI.md -> .faf; merge:true writes it into project.faf), export (.faf -> GEMINI.md), sync (re-writes GEMINI.md from .faf; export with force)' },
                         force: { type: 'boolean', description: 'Force overwrite existing files' },
                         merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
@@ -650,7 +647,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_git',
-                description: 'Generate a project.faf from any public GitHub repository URL — fetches the repo and extracts its stack and context. Returns the generated .faf. Use this to bootstrap context for a project you have the URL for but not cloned locally.',
+                description: 'Author a project.faf from any public GitHub repository URL — fetches the repo and extracts its stack and context. Returns the authored .faf. Use this to bootstrap context for a project you have the URL for but not cloned locally.',
                 annotations: {
                     title: 'Extract from GitHub',
                     readOnlyHint: false,
@@ -661,7 +658,7 @@ class FafToolHandler {
                     type: 'object',
                     properties: {
                         url: { type: 'string', description: 'GitHub repository URL (e.g., https://github.com/owner/repo or owner/repo)' },
-                        path: { type: 'string', description: 'Output directory for generated project.faf. If omitted, returns content without writing.' }
+                        path: { type: 'string', description: 'Output directory for the authored project.faf. If omitted, returns content without writing.' }
                     },
                     required: ['url'],
                     additionalProperties: false
@@ -691,8 +688,9 @@ class FafToolHandler {
                     return await this.handleFafTrust(args);
                 case 'faf_sync':
                     return await this.handleFafSync(args);
-                case 'faf_bi_sync':
-                    return await this.handleFafBiSync(args);
+                case 'faf_bi_sync': // pre-3.0.1 name: still callable, never listed
+                case 'faf_claude':
+                    return await this.handleFafClaude(args);
                 case 'faf_clear':
                     return await this.handleFafClear(args);
                 case 'faf_debug':
@@ -738,7 +736,7 @@ class FafToolHandler {
                     return await this.handleFafQuick(args);
                 case 'faf_doctor':
                     return await this.handleFafDoctor(args);
-                // v4.5.0 Interop tools
+                // Interop tools (faf-mcp 2.0.0; ported from faf-cli 4.5.0 via claude-faf-mcp 4.5.0)
                 case 'faf_agents':
                     return await this.handleFafAgents(args);
                 case 'faf_cursor':
@@ -771,7 +769,7 @@ class FafToolHandler {
                 return {
                     content: [{
                             type: 'text',
-                            text: `🤖 Claude FAF Project Status:\n\n❌ No FAF file found in ${cwd}\n💡 Run faf_init to create project.faf`
+                            text: `🤖 FAF Project Status:\n\n❌ No FAF file found in ${cwd}\n💡 Run faf_init to create project.faf`
                         }]
                 };
             }
@@ -780,7 +778,7 @@ class FafToolHandler {
             return {
                 content: [{
                         type: 'text',
-                        text: `🤖 Claude FAF Project Status:\n\n✅ ${fafResult.filename} found in ${cwd}\n\nContent preview:\n${lines.join('\n')}`
+                        text: `🤖 FAF Project Status:\n\n✅ ${fafResult.filename} found in ${cwd}\n\nContent preview:\n${lines.join('\n')}`
                     }]
             };
         }
@@ -788,7 +786,7 @@ class FafToolHandler {
             return {
                 content: [{
                         type: 'text',
-                        text: `🤖 Claude FAF Project Status:\n\n❌ Error: ${error.message}`
+                        text: `🤖 FAF Project Status:\n\n❌ Error: ${error.message}`
                     }],
                 isError: true
             };
@@ -851,7 +849,7 @@ class FafToolHandler {
                         text: `FAF SCORE: 0/100 (0%)  ○ INVALID\n\n` +
                             `\`${fafPath}\` couldn't be parsed as a valid .faf YAML:\n` +
                             `  ${error?.message ?? String(error)}\n\n` +
-                            `Re-run \`faf_init\` to regenerate a valid file.`,
+                            `Re-run \`faf_init\` with force: true to write a fresh, valid file.`,
                     },
                 ],
                 isError: true,
@@ -868,7 +866,7 @@ class FafToolHandler {
         // Headline carries both `/100` AND `(%)` so multiple matchers stay happy.
         let output = `FAF SCORE: ${score}/100 (${score}%)  ${tierDisplay}\n` +
             `${progressBar} ${score}%\n` +
-            `${result.populated}/${result.total} slots populated` +
+            `${result.populated}/${result.active} slots populated` +
             (nextTierDisplay ? `  ·  next: ${nextTierDisplay}` : '  ·  top tier') +
             `\n\n` +
             `Scored by faf-cli — the same context your AI reads.`;
@@ -900,13 +898,19 @@ class FafToolHandler {
         };
     }
     async handleFafInit(args) {
-        // Native implementation - creates project.faf with Pomelli-simple path resolution!
+        // faf_init is `faf init`: the same exported faf-cli steps the CLI command
+        // runs (assembleFreshFaf detects the folder → writeFaf → readFafRaw →
+        // scoreFafYaml), on the folder the path resolves to. Until 3.0.1 this
+        // wrote its own legacy template (no format version, `project:` as a
+        // plain string) that scored 0% whatever the folder held, failed faf_trust and
+        // crashed faf_go. Two steps of `faf init` are not exported by faf-cli
+        // 7.12 and are not repeated here: the home/root refusal and the
+        // .faf-dna birth record (faf_dna writes that on its first call).
         try {
-            // Use smart path resolution (supports "my-app", "~/Projects/my-app", "/full/path")
+            // Path resolution unchanged (supports "my-app", "~/Projects/my-app", "/full/path")
             const userInput = args?.path;
             const resolution = (0, path_resolver_1.resolveProjectPath)(userInput);
             const targetDir = resolution.projectPath;
-            const projectName = resolution.projectName;
             const fafPath = resolution.fafFilePath;
             // Ensure project directory exists
             if (!fs.existsSync(targetDir)) {
@@ -918,57 +922,16 @@ class FafToolHandler {
                 return {
                     content: [{
                             type: 'text',
-                            text: `🚀 Claude FAF Initialization:\n\n⚠️ ${existingFaf.filename} already exists in ${targetDir}\n💡 Use force: true to overwrite`
+                            text: `🚀 FAF Initialization:\n\n⚠️ ${existingFaf.filename} already exists in ${targetDir}\n💡 Use force: true to overwrite`
                         }]
                 };
             }
-            // Check project type with fuzzy detection (Friday Feature!)
-            const projectDescription = args?.description || '';
-            // Detect Chrome Extension with fuzzy matching
-            const chromeDetection = fuzzy_detector_1.FuzzyDetector.detectChromeExtension(projectDescription);
-            const projectType = fuzzy_detector_1.FuzzyDetector.detectProjectType(projectDescription);
-            // Build project data with Intel-Friday auto-fill!
-            let projectData = {
-                project: projectName,
-                project_type: projectType,
-                description: projectDescription,
-                generated: new Date().toISOString(),
-                version: version_1.VERSION
-            };
-            // Apply Intel-Friday: Auto-fill Chrome Extension slots for 90%+ score!
-            if (chromeDetection.detected) {
-                projectData = (0, fuzzy_detector_1.applyIntelFriday)(projectData);
-            }
-            // Create enhanced .faf content
-            const fafContent = `# FAF - Foundational AI Context
-project: ${projectData.project}
-type: ${projectData.project_type}${chromeDetection.detected ? ' 🎯' : ''}
-context: I⚡🍊
-generated: ${projectData.generated}
-version: ${projectData.version}
-${chromeDetection.corrected ? `# Auto-corrected: "${args?.description}" → "${chromeDetection.corrected}"` : ''}
-
-# The Formula
-human_input: Your project files
-multiplier: FAF Context
-output: Championship Performance
-
-# Quick Context
-working_directory: ${targetDir}
-initialized_by: faf-mcp${projectData._friday_feature ? `\nfriday_feature: ${projectData._friday_feature}` : ''}
-vitamin_context: true
-faffless: true
-
-${chromeDetection.detected ? `# Chrome Extension Auto-Fill (90%+ Score!)
-runtime: ${projectData.runtime}
-hosting: ${projectData.hosting}
-api_type: ${projectData.api_type}
-backend: ${projectData.backend}
-database: ${projectData.database}
-build: ${projectData.build}
-package_manager: ${projectData.package_manager}` : ''}
-`;
-            fs.writeFileSync(fafPath, fafContent);
+            const { assembleFreshFaf, writeFaf, readFafRaw, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+            writeFaf(fafPath, assembleFreshFaf(targetDir));
+            const score = scoreFafYaml(readFafRaw(fafPath));
+            // Like `cd` + `faf init`: the new project becomes the current one, so the
+            // next steps printed below (faf_score, faf_claude, faf_go) act on it.
+            this.engineAdapter.setWorkingDirectory(targetDir);
             // Pomelli-style success confirmation with path resolution info
             const pathConfirmation = (0, path_resolver_1.formatPathConfirmation)(resolution);
             const sourceExplanation = resolution.source === 'user-name'
@@ -977,7 +940,7 @@ package_manager: ${projectData.package_manager}` : ''}
             return {
                 content: [{
                         type: 'text',
-                        text: `🚀 Claude FAF Initialization:\n\n✅ Created project.faf\n\n${pathConfirmation}${sourceExplanation}\n\n🍊 Vitamin Context activated!\n⚡ FAFFLESS AI ready!${chromeDetection.detected ? '\n\n🎯 Friday Feature: Chrome Extension detected!\n📈 Auto-filled 7 slots for 90%+ score!' : ''}${chromeDetection.corrected ? `\n📝 Auto-corrected: "${args?.description}" → "${chromeDetection.corrected}"` : ''}\n\n🏁 Next steps:\n  • Run faf_score for AI-readiness score\n  • Run faf_sync to create CLAUDE.md\n  • Run faf_enhance to improve context`
+                        text: `🚀 FAF Initialization:\n\n✅ Created project.faf\n📊 ${score.score}/100 (${score.populated}/${score.active} slots populated) — ${score.tier.name}\n\n${pathConfirmation}${sourceExplanation}\n\n🍊 Vitamin Context activated!\n⚡ FAFFLESS AI ready!\n\n🏁 Next steps:\n  • Run faf_score for AI-readiness score\n  • Run faf_claude to write CLAUDE.md\n  • Run faf_go to fill the gaps`
                     }]
             };
         }
@@ -985,31 +948,71 @@ package_manager: ${projectData.package_manager}` : ''}
             return {
                 content: [{
                         type: 'text',
-                        text: `🚀 Claude FAF Initialization:\n\n❌ Error: ${error.message}`
+                        text: `🚀 FAF Initialization:\n\n❌ Error: ${error.message}`
                     }],
                 isError: true
             };
         }
     }
+    /**
+     * v3.0: was `this.engineAdapter.callEngine('trust')` — no bundled 'trust'
+     * branch exists in engine-adapter.ts, so this fell straight through to
+     * the ambient-PATH shell-out fallback (`which faf`, then execAsync).
+     * faf-cli itself has no `trust` subcommand at all — on any host where an
+     * unrelated `faf`-named binary sits first on PATH (verified live on this
+     * machine: Rust "FAFb"), this either hard-errors on an "unrecognized
+     * subcommand" or, worse, silently "succeeds" with that tool's own output.
+     * Rewired onto the bundled faf-cli bridge — bundled faf-cli only, never
+     * ambient PATH — composing `validateFaf` (structural integrity) +
+     * `scoreFafYaml` (trust metrics) directly, matching the tool's own
+     * description ("structural integrity and field consistency... trust
+     * metrics"). No CLI subcommand to shell out to even exists for this.
+     */
     async handleFafTrust(_args) {
-        const result = await this.engineAdapter.callEngine('trust');
-        if (!result.success) {
+        const cwd = this.getProjectPath();
+        const { findFafFile: findFaf, readFaf, readFafRaw, validateFaf, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+        const fafPath = findFaf(cwd);
+        if (!fafPath) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🔒 FAF Trust Validation:\n\n❌ No .faf found in ${cwd}\n💡 Run faf_init to create one — then faf_trust reports real trust metrics.`
+                    }]
+            };
+        }
+        let raw;
+        let data;
+        try {
+            raw = readFafRaw(fafPath);
+            data = readFaf(fafPath);
+        }
+        catch (error) {
             return {
                 content: [{
                         type: 'text',
-                        text: `🔒 Claude FAF Trust Validation:\n\nFailed to check trust: ${result.error}`
+                        text: `🔒 FAF Trust Validation:\n\n❌ Could not read ${fafPath}: ${error?.message ?? String(error)}`
                     }],
                 isError: true
             };
         }
-        const output = typeof result.data === 'string'
-            ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
+        const validation = validateFaf(data);
+        let output = validation.valid
+            ? `✅ Structurally sound — no malformed, missing, or contradictory fields found.`
+            : `❌ ${validation.errors.length} issue${validation.errors.length === 1 ? '' : 's'} found:\n` +
+                validation.errors.map((e) => `   • ${e}`).join('\n');
+        try {
+            const score = scoreFafYaml(raw);
+            output += `\n\n📊 ${score.score}/100 (${score.populated}/${score.active} slots populated) — ${score.tier.name}`;
+        }
+        catch {
+            // Score is a bonus signal here; a validation-only result is still honest.
+        }
         return {
             content: [{
                     type: 'text',
-                    text: `🔒 Claude FAF Trust Validation:\n\n${output}`
-                }]
+                    text: `🔒 FAF Trust Validation:\n\n${output}`
+                }],
+            isError: !validation.valid
         };
     }
     async handleFafSync(args) {
@@ -1017,12 +1020,14 @@ package_manager: ${projectData.package_manager}` : ''}
         if (args?.path) {
             this.getProjectPath(args.path);
         }
-        const result = await this.engineAdapter.callEngine('sync');
+        // `apply` maps to the bundled sync command's --auto; without it the
+        // command only reports what would change.
+        const result = await this.engineAdapter.callEngine('sync', args?.apply ? ['--auto'] : []);
         if (!result.success) {
             return {
                 content: [{
                         type: 'text',
-                        text: `🔄 Claude FAF Sync:\n\nFailed to sync: ${result.error}`
+                        text: `🔄 FAF Sync:\n\nFailed to sync: ${result.error}`
                     }],
                 isError: true
             };
@@ -1033,31 +1038,39 @@ package_manager: ${projectData.package_manager}` : ''}
         return {
             content: [{
                     type: 'text',
-                    text: `🔄 Claude FAF Sync:\n\n${output}`
+                    text: `🔄 FAF Sync:\n\n${output}`
                 }]
         };
     }
-    async handleFafBiSync(args) {
+    async handleFafClaude(args) {
         // Set project context if path provided
         if (args?.path) {
             this.getProjectPath(args.path);
         }
-        const biSyncArgs = [];
-        if (args?.auto) {
-            biSyncArgs.push('--auto');
+        // auto / watch / force used to be declared here too; none of them was
+        // ever read by the command, so the schema no longer promises them.
+        const claudeArgs = [];
+        // v3.0 fix: the tool's own schema advertises agents/cursor/gemini/all,
+        // but before 3.0 they were never forwarded to the engine adapter —
+        // the tool silently ignored them and only ever wrote CLAUDE.md.
+        if (args?.agents) {
+            claudeArgs.push('--agents');
+        }
+        if (args?.cursor) {
+            claudeArgs.push('--cursor');
         }
-        if (args?.watch) {
-            biSyncArgs.push('--watch');
+        if (args?.gemini) {
+            claudeArgs.push('--gemini');
         }
-        if (args?.force) {
-            biSyncArgs.push('--force');
+        if (args?.all) {
+            claudeArgs.push('--all');
         }
-        const result = await this.engineAdapter.callEngine('bi-sync', biSyncArgs);
+        const result = await this.engineAdapter.callEngine('claude', claudeArgs);
         if (!result.success) {
             return {
                 content: [{
                         type: 'text',
-                        text: `🔗 Claude FAF Bi-Sync:\n\nFailed to bi-sync: ${result.error}`
+                        text: `🔗 FAF → CLAUDE.md:\n\nCould not write CLAUDE.md: ${result.error}`
                     }],
                 isError: true
             };
@@ -1068,41 +1081,50 @@ package_manager: ${projectData.package_manager}` : ''}
         return {
             content: [{
                     type: 'text',
-                    text: `🔗 Claude FAF Bi-Sync:\n\n${output}`
+                    text: `🔗 FAF → CLAUDE.md:\n\n${output}`
                 }]
         };
     }
+    /**
+     * v3.0: was `this.engineAdapter.callEngine('clear', clearArgs)` — no
+     * bundled 'clear' branch exists in engine-adapter.ts, so this fell
+     * straight through to the ambient-PATH shell-out fallback. Worse: even
+     * when a real faf-cli WAS first on PATH, its actual `clear` subcommand
+     * only clears `faf-git-*` temp directories from the OS tmpdir (see
+     * ~/FAF/cli/src/commands/clear.ts) — entirely unrelated to this tool's
+     * own cache/todos/backups semantics. There was never a correct backing
+     * implementation for this tool's contract, on any PATH.
+     *
+     * Rewired as a genuinely local operation — no CLI dependency, bundled or
+     * ambient, at all. `cache` clears the one real cache path this codebase
+     * writes (~/.faf-cli-cache, faf-core/utils/technical-credit.ts). The
+     * schema used to advertise `todos` and `backups` as well; no persisted todo
+     * list or backup-file store exists anywhere in faf-mcp, so those flags are
+     * gone rather than answered with a made-up "cleared".
+     */
     async handleFafClear(args) {
-        const clearArgs = [];
-        if (args?.cache) {
-            clearArgs.push('--cache');
-        }
-        if (args?.todos) {
-            clearArgs.push('--todos');
-        }
-        if (args?.backups) {
-            clearArgs.push('--backups');
-        }
-        if (args?.all || (!args?.cache && !args?.todos && !args?.backups)) {
-            clearArgs.push('--all');
-        }
-        const result = await this.engineAdapter.callEngine('clear', clearArgs);
-        if (!result.success) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `🧹 Claude FAF Clear:\n\nFailed to clear: ${result.error}`
-                    }],
-                isError: true
-            };
+        const wantCache = !!args?.cache;
+        const wantAll = !!args?.all || !wantCache;
+        const lines = [];
+        if (wantCache || wantAll) {
+            // HOME/USERPROFILE first (Node's own os.homedir() precedence; Bun's ignores a
+            // runtime override) so a test can redirect the home dir instead of
+            // deleting from the developer's real one.
+            const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+            const cacheDir = pathModule.join(home, '.faf-cli-cache');
+            const creditCache = pathModule.join(cacheDir, 'technical-credit.json');
+            if (fs.existsSync(creditCache)) {
+                fs.rmSync(creditCache, { force: true });
+                lines.push(`✅ cache: cleared ${creditCache}`);
+            }
+            else {
+                lines.push('✅ cache: nothing to clear');
+            }
         }
-        const output = typeof result.data === 'string'
-            ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
         return {
             content: [{
                     type: 'text',
-                    text: `🧹 Claude FAF Clear:\n\n${output}`
+                    text: `🧹 FAF Clear:\n\n${lines.join('\n')}`
                 }]
         };
     }
@@ -1131,7 +1153,7 @@ WHAT IS .FAF?
 • The dot (.) means it's a file format!
 
 🧡 Trust: Context verified
-⚡️ Speed: Generated in <29ms
+⚡️ Speed: Authored in <29ms
 SPEEDY AI you can TRUST!
 
 Version ${packageInfo.version}
@@ -1142,10 +1164,10 @@ Just like JPEG makes images universal,
 HOW IT WORKS:
 1. Drop a file or paste the path
 2. Create .faf (Foundational AI-context Format)
-3. Talk to Claude to bi-sync it
+3. Ask your AI to run faf_claude
 4. You're done⚡
 
-🩵 You just made Claude Happy
+🩵 You just made your AI happy
 🧡⚡️ SPEEDY AI you can TRUST!`;
         return {
             content: [{
@@ -1164,7 +1186,7 @@ WHY:  Just like JPEG makes images viewable everywhere,
       .faf makes projects understandable by AI.
 
 HOW:  Run 'faf' on any project to create one.
-      Run 'faf_score' to check AI-readiness (target: 99%).
+      Run 'faf_score' to check AI-readiness (target: 100%).
 
 REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
 
@@ -1180,18 +1202,15 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
         try {
             const fs = await import('fs');
             const path = await import('path');
-            const { exec } = await import('child_process');
-            const { promisify } = await import('util');
-            const _execAsync = promisify(exec);
             const cwd = this.engineAdapter.getWorkingDirectory();
             const debugInfo = {
                 workingDirectory: cwd,
                 canWrite: false,
-                fafCliPath: null,
-                fafVersion: null,
+                // Every tool runs on the faf-cli bundled in node_modules — report
+                // that, not whatever `which faf` happens to find on PATH.
+                fafVersion: (0, faf_cli_bridge_js_1.bundledFafCliVersion)(),
                 permissions: {},
                 enginePath: this.engineAdapter.getEnginePath(),
-                pathEnv: process.env.PATH?.split(':') || []
             };
             // Check write permissions
             try {
@@ -1203,21 +1222,6 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
             catch (error) {
                 debugInfo.permissions.writeError = error instanceof Error ? error.message : String(error);
             }
-            // Check FAF CLI availability using championship auto-detection
-            try {
-                const cliInfo = this.engineAdapter.getCliInfo();
-                if (cliInfo.detected && cliInfo.path) {
-                    debugInfo.fafCliPath = cliInfo.path;
-                    debugInfo.fafVersion = cliInfo.version || null;
-                }
-                else {
-                    debugInfo.fafCliPath = null;
-                    debugInfo.fafVersion = null;
-                }
-            }
-            catch (error) {
-                debugInfo.permissions.fafError = error instanceof Error ? error.message : String(error);
-            }
             // Check for existing FAF file (v1.2.0: project.faf, *.faf, or .faf)
             const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
             const hasFaf = fafResult !== null;
@@ -1226,15 +1230,12 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
 📂 Working Directory: ${debugInfo.workingDirectory}
 ✏️ Write Permissions: ${debugInfo.canWrite ? '✅ Yes' : '❌ No'}
 ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeError}\n` : ''}🤖 FAF Engine Path: ${debugInfo.enginePath}
-🏎️ FAF CLI Path: ${debugInfo.fafCliPath || '❌ Not found'}
-📋 FAF Version: ${debugInfo.fafVersion || 'Unknown'}
-${debugInfo.permissions.fafError ? `   FAF Error: ${debugInfo.permissions.fafError}\n` : ''}📄 FAF File: ${hasFaf ? `✅ ${fafResult.filename} exists` : '❌ Not found (run faf_init)'}
-🛤️ System PATH: ${debugInfo.pathEnv.slice(0, 3).join(', ')}${debugInfo.pathEnv.length > 3 ? '...' : ''}
+📋 faf-cli (bundled): ${debugInfo.fafVersion ? `v${debugInfo.fafVersion}` : '❌ not found in node_modules — reinstall faf-mcp'}
+📄 FAF File: ${hasFaf ? `✅ ${fafResult.filename} exists` : '❌ Not found (run faf_init)'}
 
 💡 Quick Start:
-   1. If FAF CLI not found: npm install -g faf-cli
-   2. If .faf file missing: use faf_init tool
-   3. For optimization: use faf_enhance tool with model="claude"
+   1. If .faf file missing: use faf_init or faf_auto
+   2. To check AI-readiness: use faf_score
 `;
             return {
                 content: [{
@@ -1247,7 +1248,7 @@ ${debugInfo.permissions.fafError ? `   FAF Error: ${debugInfo.permissions.fafErr
             return {
                 content: [{
                         type: 'text',
-                        text: `🔍 Claude FAF Debug Failed: ${error instanceof Error ? error.message : String(error)}`
+                        text: `🔍 faf-mcp Debug Failed: ${error instanceof Error ? error.message : String(error)}`
                     }],
                 isError: true
             };
@@ -1299,7 +1300,6 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
 **Extensions:**
 - \`new\` - force overwrite existing
 - \`full\` - detailed output
-- \`bi\` - bi-directional sync
 
 ## UX Rules
 1. **Don't offer option menus** - just solve it
@@ -1459,7 +1459,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
         }
     }
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    // NEW: Human Context Tools (v3.2.0 parity)
+    // Human Context Tools (parity with faf-cli v3.2.0)
     // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     async handleFafReadme(args) {
         try {
@@ -1686,7 +1686,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             }
             // Default: show quality report
             const icons = {
-                empty: '⬜', generic: '🟡', good: '🟢', excellent: '💎'
+                empty: '⬜', generic: '◻️', good: '◼️', excellent: '💎'
             };
             let output = `🔍 FAF Human Context Quality\n\n`;
             for (const field of fields) {
@@ -1780,7 +1780,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             // they're SOURCED by Turbo-Cat (faf-cli's separate STACK_INTERVIEW if ever
             // needed), never asked of a human. (Decision: single-source the 8-Q 6Ws
             // Interview, wolfejam 2026-06-10 — language is not on the human side.)
-            const { SIX_WS_INTERVIEW } = await faf_cli_bridge_js_1.fafCli;
+            const { SIX_WS_INTERVIEW, isPlaceholder, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
             const QUESTION_REGISTRY = Object.fromEntries(SIX_WS_INTERVIEW.map((q) => [q.path, q]));
             // Priority order for questions
             const priorityOrder = [
@@ -1825,16 +1825,18 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 }
                 current[parts[parts.length - 1]] = value;
             };
-            // Check if value is empty/placeholder
-            const isEmpty = (value) => {
-                return value === undefined ||
-                    value === null ||
-                    value === '' ||
-                    value === 'Unknown' ||
-                    value === 'TBD' ||
-                    value === 'None' ||
-                    (typeof value === 'string' && value.toLowerCase().includes('placeholder'));
-            };
+            // Empty = what the scorer calls empty. faf-cli's isPlaceholder is the one
+            // rule the kernel scores by; a local list ('TBD', 'Unknown', ...) drifted
+            // from it in both directions and made faf_go's numbers disagree with
+            // faf_score on the same file. slotignored is inactive, never asked.
+            const isEmpty = (value) => isPlaceholder(value) && value !== 'slotignored';
+            // One score function, period: the real scorer on the real bytes.
+            const scoreOf = (raw) => scoreFafYaml(raw).score;
+            const tierLabel = (score) => score >= 100 ? '✪ Trophy — 100% AI-Readiness' :
+                score >= 99 ? '★ Gold' :
+                    score >= 95 ? '◆ Silver' :
+                        score >= 85 ? '◇ Bronze — production ready' :
+                            score >= 70 ? '● Green — solid foundation' : '📈 Keep going!';
             // PHASE 2: Apply answers if provided
             if (args?.answers && typeof args.answers === 'object') {
                 const answers = args.answers;
@@ -1845,15 +1847,10 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                         appliedCount++;
                     }
                 }
-                // Write updated file
+                // Write updated file, then score the bytes that were written.
                 fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
-                // Calculate new score (simple count-based)
-                const totalFields = Object.keys(QUESTION_REGISTRY).length;
-                const filledFields = Object.keys(QUESTION_REGISTRY).filter(field => !isEmpty(getNestedValue(fafData, field))).length;
-                const newScore = Math.round((filledFields / totalFields) * 100);
-                const celebration = newScore >= 100 ? '🏆 GOLD CODE ACHIEVED!' :
-                    newScore >= 85 ? '🥇 Championship grade!' :
-                        newScore >= 70 ? '🥈 Great progress!' : '📈 Keep going!';
+                const newScore = scoreOf(fs.readFileSync(fafResult.path, 'utf-8'));
+                const celebration = tierLabel(newScore);
                 return {
                     content: [{
                             type: 'text',
@@ -1864,12 +1861,10 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             // PHASE 1: Analyze and return questions — the canonical 6Ws (SIX_WS_INTERVIEW),
             // scoped to slots that are empty AND active (slotignored is never asked).
             const missingFields = SIX_WS_INTERVIEW
-                .filter((q) => { const v = getNestedValue(fafData, q.path); return v !== 'slotignored' && isEmpty(v); })
+                .filter((q) => isEmpty(getNestedValue(fafData, q.path)))
                 .map((q) => q.path);
-            // Calculate current score
-            const totalFields = Object.keys(QUESTION_REGISTRY).length;
-            const filledFields = totalFields - missingFields.length;
-            const currentScore = Math.round((filledFields / totalFields) * 100);
+            // Current score — the same number faf_score reports for this file.
+            const currentScore = scoreOf(fafContent);
             // Already at 100%?
             if (currentScore >= 100) {
                 return {
@@ -1878,7 +1873,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                             text: JSON.stringify({
                                 complete: true,
                                 score: 100,
-                                message: '🏆 GOLD CODE ACHIEVED! Your project has 100% AI-Readiness.',
+                                message: '✪ GOLD CODE ACHIEVED! Your project has 100% AI-Readiness.',
                                 context: 'faf_go'
                             }, null, 2)
                         }]
@@ -1892,7 +1887,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                             text: JSON.stringify({
                                 score: currentScore,
                                 message: `Score is ${currentScore}%. All fields filled but content may need enhancement.`,
-                                suggestion: 'Use faf_enhance to improve content quality.',
+                                suggestion: 'Use faf_go or faf_human_add to improve content quality.',
                                 context: 'faf_go'
                             }, null, 2)
                         }]
@@ -1945,120 +1940,52 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
     /**
      * faf_auto - ONE COMMAND TO RULE THEM ALL
      * Zero to Championship in one command
-     * Runs: init + formats + sync + bi-sync + score
+     *
+     * v3.0: composes faf-cli's own `faf auto` chain — `updateExistingFaf` on an
+     * existing file, `assembleFreshFaf` on a new one, `writeFaf` for the bytes,
+     * `renderClaudeMd`/`writeClaudeMd` for CLAUDE.md — plus the same
+     * `scoreFafYaml` faf_score reads. Previously this handler ran a bespoke
+     * bootstrap template plus a local `calculateSimpleScore` pseudo-scorer,
+     * which could (and did) report a different score than faf_score for the
+     * identical file in the same server run. NEVER reimplement detection or
+     * scoring here — compose faf-cli, exactly like faf_score/faf_formats do.
      */
     async handleFafAuto(args) {
         const startTime = Date.now();
         const cwd = this.getProjectPath(args?.path);
-        const yaml = await import('yaml');
         const path = await import('path');
         try {
             const steps = [];
-            let currentScore = 0;
-            // Step 1: Check/Create .faf file
-            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            const { findFafFile: findFaf, readFaf, readFafRaw, scoreFafYaml, assembleFreshFaf, updateExistingFaf, writeFaf, renderClaudeMd, writeClaudeMd, } = await faf_cli_bridge_js_1.fafCli;
+            // Step 1: locate any existing .faf and its real "before" score.
+            const existingPath = findFaf(cwd);
+            const beforeScore = existingPath ? scoreFafYaml(readFafRaw(existingPath)).score : 0;
+            steps.push(existingPath ? `✅ Found ${path.basename(existingPath)}` : '✅ Will create project.faf');
+            // Step 2: exactly what faf-cli's own `faf auto` does — an existing file
+            // is updated with updateExistingFaf (existing values win; interrogated →
+            // detected → Turbo-Cat → Relentless fill the empties), a new one is
+            // assembled with assembleFreshFaf — and written with faf-cli's writer,
+            // so the bytes match `faf auto` (no runtime `_meta` block, same layout).
             let fafPath;
-            if (!fafResult) {
-                // Create .faf file
-                const projectName = path.basename(cwd);
-                fafPath = path.join(cwd, 'project.faf');
-                const initFafContent = `# FAF - Foundational AI Context
-project: ${projectName}
-type: auto-detected
-context: I⚡🍊
-generated: ${new Date().toISOString()}
-version: ${version_1.VERSION}
-
-# Quick Context
-working_directory: ${cwd}
-initialized_by: faf-mcp-auto
-vitamin_context: true
-faffless: true
-`;
-                fs.writeFileSync(fafPath, initFafContent);
-                steps.push('✅ Created project.faf');
+            if (existingPath) {
+                fafPath = existingPath;
+                writeFaf(fafPath, updateExistingFaf(cwd, readFaf(existingPath)));
+                steps.push('✅ Merged fresh facts into existing project.faf (existing values preserved)');
             }
             else {
-                fafPath = fafResult.path;
-                steps.push(`✅ Found ${fafResult.filename}`);
-            }
-            // Get initial score
-            const fafContent = fs.readFileSync(fafPath, 'utf-8');
-            const fafData = yaml.parse(fafContent) || {};
-            currentScore = this.calculateSimpleScore(fafData);
-            // Step 2: Run TURBO-CAT format discovery — composed from faf-cli's engine.
-            const formatsResult = await (0, turbocat_bridge_js_1.composedTurboCat)(cwd);
-            if (formatsResult && formatsResult.discoveredFormats.length > 0) {
-                // Apply slot fills to .faf. turboCatSlots routes them into the correct
-                // .faf sections; fill the stack section (main_language lives under
-                // project, which is a string here) — clean keys, no noise.
-                const slots = await (0, turbocat_bridge_js_1.composedTurboCatSlots)(cwd);
-                if (!fafData.stack)
-                    fafData.stack = {};
-                for (const [key, value] of Object.entries(slots?.stack ?? {})) {
-                    if (!fafData.stack[key] || fafData.stack[key] === 'None') {
-                        fafData.stack[key] = value;
-                    }
-                }
-                if (formatsResult.stackSignature) {
-                    fafData.stack_signature = formatsResult.stackSignature;
-                }
-                fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
-                steps.push(`✅ TURBO-CAT discovered ${formatsResult.discoveredFormats.length} formats`);
-            }
-            else {
-                steps.push('⚠️ No additional formats detected');
-            }
-            // Step 3: Extract human context from README
-            const readmePath = path.join(cwd, 'README.md');
-            if (fs.existsSync(readmePath)) {
-                const readmeContent = fs.readFileSync(readmePath, 'utf-8');
-                const extracted = this.extractSixWsFromReadme(readmeContent);
-                if (!fafData.human_context)
-                    fafData.human_context = {};
-                let extractedCount = 0;
-                for (const [field, value] of Object.entries(extracted)) {
-                    if (value && !fafData.human_context[field]) {
-                        fafData.human_context[field] = value;
-                        extractedCount++;
-                    }
-                }
-                if (extractedCount > 0) {
-                    fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
-                    steps.push(`✅ Extracted ${extractedCount} human context fields from README`);
-                }
-            }
-            // Step 4: Create/Update CLAUDE.md (bi-sync)
-            const claudePath = path.join(cwd, 'CLAUDE.md');
-            if (!fs.existsSync(claudePath)) {
-                const claudeContent = `# 🏎️ CLAUDE.md - AI Telemetry Link
-
-## Project: ${fafData.project || path.basename(cwd)}
-**Championship-Grade Project DNA Foundation**
-
-### 🎯 Project Mission
-${fafData.human_context?.why || fafData.project?.goal || 'AI-ready project context'}
-
-### 🏗️ Architecture Overview
-${fafData.stack_signature || 'Auto-detected stack'}
-
----
-
-**STATUS: BI-SYNC ACTIVE 🔗**
-*Last Sync: ${new Date().toISOString()}*
-*Sync Engine: FAF Auto*
-`;
-                fs.writeFileSync(claudePath, claudeContent);
-                steps.push('✅ Created CLAUDE.md');
-            }
-            else {
-                steps.push('✅ CLAUDE.md already exists');
+                fafPath = path.join(cwd, 'project.faf');
+                writeFaf(fafPath, assembleFreshFaf(cwd));
+                steps.push('✅ Created project.faf');
             }
-            // Step 5: Calculate final score
-            const updatedContent = fs.readFileSync(fafPath, 'utf-8');
-            const updatedData = yaml.parse(updatedContent) || {};
-            const newScore = this.calculateSimpleScore(updatedData);
-            const scoreDelta = newScore - currentScore;
+            // Step 3: CLAUDE.md — faf-cli's render of the file just written (the
+            // same bytes `faf sync` writes), injected non-destructively.
+            const claudeExisted = fs.existsSync(path.join(cwd, 'CLAUDE.md'));
+            writeClaudeMd(cwd, renderClaudeMd(readFaf(fafPath)));
+            steps.push(claudeExisted ? '✅ Updated CLAUDE.md (faf-managed block)' : '✅ Created CLAUDE.md');
+            // Step 4: final score — same real scorer faf_score reads, on the file
+            // just written. By construction this can never disagree with faf_score.
+            const newScore = scoreFafYaml(readFafRaw(fafPath)).score;
+            const scoreDelta = newScore - beforeScore;
             // Calculate elapsed time
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             // Format output
@@ -2068,21 +1995,27 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             output += steps.join('\n') + '\n\n';
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
             output += `⏱️ Completed in ${elapsed}s\n`;
-            output += `📊 Before: ${currentScore}% | After: ${newScore}% ${deltaDisplay}\n`;
+            output += `📊 Before: ${beforeScore}% | After: ${newScore}% ${deltaDisplay}\n`;
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
-            if (newScore >= 99) {
-                output += `🏆 CHAMPIONSHIP ACHIEVED! Your AI has complete context.\n`;
+            if (newScore >= 100) {
+                output += `✪ TROPHY — 100% AI-Readiness. Your AI has complete context.\n`;
+            }
+            else if (newScore >= 99) {
+                output += `★ Gold — 1% to Trophy. Run faf_go to finish.\n`;
+            }
+            else if (newScore >= 95) {
+                output += `◆ Silver — ${100 - newScore}% to Trophy.\n`;
             }
             else if (newScore >= 85) {
-                output += `🥇 Elite level! ${100 - newScore}% to perfection.\n`;
+                output += `◇ Bronze — production ready. ${100 - newScore}% to Trophy.\n`;
             }
             else if (newScore >= 70) {
-                output += `🥈 Great progress! Run faf_go to reach championship.\n`;
+                output += `● Green — solid foundation. Run faf_go to climb tiers.\n`;
             }
             else {
                 output += `🚀 Good start! Run faf_go for guided improvement.\n`;
             }
-            output += `\n💡 Next: faf_score --details | faf_go | faf_enhance`;
+            output += `\n💡 Next: faf_score | faf_go | faf_claude`;
             return { content: [{ type: 'text', text: output }] };
         }
         catch (error) {
@@ -2094,7 +2027,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
     }
     /**
      * faf_dna - Show your FAF DNA journey
-     * Displays evolution from birth to current (22% → 85% → 99%)
+     * Displays the score evolution from birth to today (e.g. 22% → 85% → 100%)
      */
     async handleFafDna(args) {
         const cwd = this.getProjectPath(args?.path);
@@ -2113,11 +2046,10 @@ ${fafData.stack_signature || 'Auto-detected stack'}
                             }]
                     };
                 }
-                // .faf exists but no DNA - create initial DNA
-                const yaml = await import('yaml');
-                const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
-                const fafData = yaml.parse(fafContent) || {};
-                const currentScore = this.calculateSimpleScore(fafData);
+                // .faf exists but no DNA - create initial DNA. Real scorer — same
+                // one faf_score reads — never a local pseudo-score (v3.0 fix).
+                const { readFafRaw, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                const currentScore = scoreFafYaml(readFafRaw(fafResult.path)).score;
                 const dna = {
                     birthCertificate: {
                         born: new Date().toISOString(),
@@ -2149,8 +2081,24 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             const dna = JSON.parse(dnaContent);
             // Build journey string
             const birthScore = dna.birthCertificate?.birthDNA || 0;
-            const currentScore = dna.current?.score || 0;
+            let currentScore = dna.current?.score || 0;
             const milestones = dna.milestones || [];
+            dna.milestones = milestones;
+            // "Current" is the live score of the file on disk, not whatever was
+            // stored last time. Nothing else records growth into .faf-dna, so this
+            // is where the journey gets its next point.
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (fafResult) {
+                const { readFafRaw, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                const live = scoreFafYaml(readFafRaw(fafResult.path)).score;
+                if (live !== currentScore) {
+                    const now = new Date().toISOString();
+                    dna.current = { ...(dna.current ?? {}), score: live, lastSync: now };
+                    milestones.push({ type: 'sync', score: live, date: now, version: dna.current.version ?? 'v1.0.0' });
+                    fs.writeFileSync(dnaPath, JSON.stringify(dna, null, 2));
+                    currentScore = live;
+                }
+            }
             // Find key milestones
             const _birth = milestones.find((m) => m.type === 'birth');
             const peak = milestones.find((m) => m.type === 'peak');
@@ -2192,8 +2140,8 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             }
             output += `\n🧬 MILESTONES\n`;
             const milestoneIcons = {
-                birth: '🐣', first_save: '💾', doubled: '2️⃣',
-                championship: '🏆', elite: '⭐', peak: '🏔️', perfect: '💎'
+                birth: '🐣', first_save: '💾', doubled: '2️⃣', sync: '🔄',
+                championship: '✪', elite: '⭐', peak: '🏔️', perfect: '💎'
             };
             for (const m of milestones) {
                 const icon = milestoneIcons[m.type] || '📍';
@@ -2242,7 +2190,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
                 };
             }
             // Format human-readable output
-            let output = `😽 TURBO-CAT™ Format Discovery v2.0.0\n`;
+            let output = `😽 TURBO-CAT™ Format Discovery\n`;
             output += `═══════════════════════════════════════════════════\n\n`;
             output += `✅ Found ${analysis.discoveredFormats.length} formats in ${elapsed}ms!\n\n`;
             output += `📋 Discovered Formats (A-Z):\n`;
@@ -2251,7 +2199,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
                 output += `  ✅ ${format.fileName}\n`;
             }
             output += `\n💡 Stack Signature: ${analysis.stackSignature}\n`;
-            output += `🏆 Intelligence Score: ${analysis.totalIntelligenceScore}\n\n`;
+            output += `🧠 Intelligence Score: ${analysis.totalIntelligenceScore}\n\n`;
             if (Object.keys(analysis.slotFillRecommendations).length > 0) {
                 output += `📊 Recommended Slot Fills:\n`;
                 for (const [key, value] of Object.entries(analysis.slotFillRecommendations)) {
@@ -2271,33 +2219,6 @@ ${fafData.stack_signature || 'Auto-detected stack'}
         }
     }
     /**
-     * Internal helper: Calculate simple score from .faf data
-     */
-    calculateSimpleScore(fafData) {
-        let score = 0;
-        const maxScore = 100;
-        // Project section (30 points)
-        if (fafData.project)
-            score += 15;
-        if (fafData.project?.goal || fafData.description)
-            score += 15;
-        // Human context (30 points)
-        const humanContext = fafData.human_context || {};
-        const wFields = ['who', 'what', 'why', 'where', 'when', 'how'];
-        const filledW = wFields.filter(f => humanContext[f] && humanContext[f] !== 'null').length;
-        score += Math.round((filledW / wFields.length) * 30);
-        // Stack section (20 points)
-        const stack = fafData.stack || {};
-        const stackFields = ['frontend', 'backend', 'database', 'hosting', 'build'];
-        const filledStack = stackFields.filter(f => stack[f] && stack[f] !== 'None').length;
-        score += Math.round((filledStack / stackFields.length) * 20);
-        // Files exist bonus (20 points)
-        if (fafData.initialized_by || fafData.generated)
-            score += 10;
-        if (fafData.stack_signature)
-            score += 10;
-        return Math.min(score, maxScore);
-    }
     /**
      * faf_quick - Lightning-fast .faf creation
      * One-liner format: "name, description, language, framework, hosting"
@@ -2357,7 +2278,7 @@ Example: "my-app, e-commerce platform"`
 
 ⚠️ project.faf already exists at: ${fafPath}
 
-Use force: true to overwrite, or use faf_enhance to modify.`
+Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
                         }]
                 };
             }
@@ -2394,7 +2315,6 @@ Use force: true to overwrite, or use faf_enhance to modify.`
             output += `✅ Created: ${fafPath}\n\n`;
             output += `Next steps:\n`;
             output += `  • faf_score - Check AI-readiness\n`;
-            output += `  • faf_enhance - Improve context\n`;
             output += `  • faf_go - Guided interview to 100%`;
             return { content: [{ type: 'text', text: output }] };
         }
@@ -2488,7 +2408,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                         results.push({
                             status: 'error',
                             message: '.faf file is empty',
-                            fix: 'Run: faf_init with force option to regenerate'
+                            fix: 'Run: faf_init with force option to rewrite it'
                         });
                     }
                     else {
@@ -2502,7 +2422,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                             results.push({
                                 status: 'warning',
                                 message: `Missing important fields: ${missingFields.join(', ')}`,
-                                fix: 'Run: faf_enhance or faf_go to add missing info'
+                                fix: 'Run: faf_go to add missing info'
                             });
                         }
                         else {
@@ -2511,26 +2431,31 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                                 message: '.faf structure is valid'
                             });
                         }
-                        // Check 4: Score
-                        const score = this.calculateSimpleScore(fafData);
+                        // Check 4: Score — real scorer (same one faf_score reads), never
+                        // a local pseudo-score (v3.0 fix). Slot breakdown included so
+                        // faf_doctor's "score could be better" fix advice is actionable.
+                        const { scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                        const scoreResult = scoreFafYaml(content);
+                        const score = scoreResult.score;
+                        const slotSummary = `${scoreResult.populated}/${scoreResult.active} slots populated`;
                         if (score < 30) {
                             results.push({
                                 status: 'error',
-                                message: `Score too low: ${score}%`,
-                                fix: 'Run: faf_enhance or faf_go to improve context'
+                                message: `Score too low: ${score}% (${slotSummary})`,
+                                fix: 'Run: faf_go to improve context'
                             });
                         }
                         else if (score < 70) {
                             results.push({
                                 status: 'warning',
-                                message: `Score could be better: ${score}%`,
+                                message: `Score could be better: ${score}% (${slotSummary})`,
                                 fix: 'Target 70%+ for championship AI context'
                             });
                         }
                         else {
                             results.push({
                                 status: 'ok',
-                                message: `Great score: ${score}%`
+                                message: `Great score: ${score}% (${slotSummary})`
                             });
                         }
                     }
@@ -2539,7 +2464,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                     results.push({
                         status: 'error',
                         message: '.faf file is corrupted or invalid YAML',
-                        fix: 'Run: faf_init with force option to regenerate'
+                        fix: 'Run: faf_init with force option to rewrite it'
                     });
                 }
             }
@@ -2549,13 +2474,13 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                 results.push({
                     status: 'warning',
                     message: 'No CLAUDE.md file',
-                    fix: 'Run: faf_auto or faf_bi_sync to create bi-directional sync'
+                    fix: 'Run: faf_auto or faf_claude to write CLAUDE.md'
                 });
             }
             else {
                 results.push({
                     status: 'ok',
-                    message: 'CLAUDE.md found (bi-sync ready)'
+                    message: 'CLAUDE.md found'
                 });
             }
             // Check 6: Project detection
@@ -2613,7 +2538,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
             }
             output += `\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
             if (!hasErrors && !hasWarnings) {
-                output += `🏆 Perfect health! Your FAF setup is championship-ready!`;
+                output += `✅ Perfect health! Your FAF setup is championship-ready!`;
             }
             else if (!hasErrors) {
                 output += `🎯 Good health with minor improvements suggested.`;
@@ -2631,7 +2556,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
         }
     }
     // ============================================================================
-    // v4.5.0 INTEROP HANDLERS
+    // INTEROP HANDLERS (faf-mcp 2.0.0; ported from faf-cli 4.5.0 via claude-faf-mcp 4.5.0)
     // ============================================================================
     async handleFafAgents(args) {
         const cwd = this.getProjectPath(args?.path);
@@ -2769,7 +2694,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
             let output = `GitHub Context:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms`;
             // Include generated .faf content if no output path (preview mode)
             if (!outputPath && data?.data?.fafContent) {
-                output += `\n\n--- Generated project.faf ---\n${data.data.fafContent}`;
+                output += `\n\n--- Authored project.faf ---\n${data.data.fafContent}`;
             }
             return {
                 content: [{ type: 'text', text: output }]