faf-mcp 3.0.0 → 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,7 +205,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_sync',
-                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_bi_sync for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md.',
+                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: 'Reconcile .faf with repo manifests',
                     readOnlyHint: false,
@@ -223,10 +222,10 @@ class FafToolHandler {
                 }
             },
             {
-                name: 'faf_bi_sync',
-                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.',
+                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: 'Sync .faf to CLAUDE.md and IDE formats',
+                    title: 'Write CLAUDE.md and IDE formats from .faf',
                     readOnlyHint: false,
                     destructiveHint: false,
                     openWorldHint: false
@@ -234,10 +233,10 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        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
@@ -472,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,
@@ -492,7 +491,7 @@ class FafToolHandler {
             },
             {
                 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,
@@ -560,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,
@@ -574,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.' }
@@ -585,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,
@@ -595,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.' }
@@ -606,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,
@@ -616,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.' }
@@ -648,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,
@@ -659,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
@@ -689,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':
@@ -736,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':
@@ -769,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`
                         }]
                 };
             }
@@ -778,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')}`
                     }]
             };
         }
@@ -786,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
             };
@@ -849,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,
@@ -898,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)) {
@@ -916,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'
@@ -975,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_bi_sync to create CLAUDE.md\n  • Run faf_go to fill the gaps`
+                        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`
                     }]
             };
         }
@@ -983,7 +948,7 @@ 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
             };
@@ -1011,7 +976,7 @@ package_manager: ${projectData.package_manager}` : ''}
             return {
                 content: [{
                         type: 'text',
-                        text: `🔒 Claude FAF Trust Validation:\n\n❌ No .faf found in ${cwd}\n💡 Run faf_init to create one — then faf_trust reports real trust metrics.`
+                        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.`
                     }]
             };
         }
@@ -1025,7 +990,7 @@ package_manager: ${projectData.package_manager}` : ''}
             return {
                 content: [{
                         type: 'text',
-                        text: `🔒 Claude FAF Trust Validation:\n\n❌ Could not read ${fafPath}: ${error?.message ?? String(error)}`
+                        text: `🔒 FAF Trust Validation:\n\n❌ Could not read ${fafPath}: ${error?.message ?? String(error)}`
                     }],
                 isError: true
             };
@@ -1045,7 +1010,7 @@ package_manager: ${projectData.package_manager}` : ''}
         return {
             content: [{
                     type: 'text',
-                    text: `🔒 Claude FAF Trust Validation:\n\n${output}`
+                    text: `🔒 FAF Trust Validation:\n\n${output}`
                 }],
             isError: !validation.valid
         };
@@ -1062,7 +1027,7 @@ package_manager: ${projectData.package_manager}` : ''}
             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
             };
@@ -1073,39 +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);
         }
         // auto / watch / force used to be declared here too; none of them was
-        // ever read by syncBiDirectional, so the schema no longer promises them.
-        const biSyncArgs = [];
+        // 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 they were never forwarded to engine-adapter's bi-sync dispatch —
-        // faf_bi_sync silently ignored them and only ever wrote CLAUDE.md.
+        // 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) {
-            biSyncArgs.push('--agents');
+            claudeArgs.push('--agents');
         }
         if (args?.cursor) {
-            biSyncArgs.push('--cursor');
+            claudeArgs.push('--cursor');
         }
         if (args?.gemini) {
-            biSyncArgs.push('--gemini');
+            claudeArgs.push('--gemini');
         }
         if (args?.all) {
-            biSyncArgs.push('--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
             };
@@ -1116,7 +1081,7 @@ package_manager: ${projectData.package_manager}` : ''}
         return {
             content: [{
                     type: 'text',
-                    text: `🔗 Claude FAF Bi-Sync:\n\n${output}`
+                    text: `🔗 FAF → CLAUDE.md:\n\n${output}`
                 }]
         };
     }
@@ -1159,7 +1124,7 @@ package_manager: ${projectData.package_manager}` : ''}
         return {
             content: [{
                     type: 'text',
-                    text: `🧹 Claude FAF Clear:\n\n${lines.join('\n')}`
+                    text: `🧹 FAF Clear:\n\n${lines.join('\n')}`
                 }]
         };
     }
@@ -1188,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}
@@ -1199,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: [{
@@ -1221,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!
 
@@ -1283,7 +1248,7 @@ ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeErr
             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
             };
@@ -1335,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
@@ -1495,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 {
@@ -1722,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) {
@@ -1909,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)
                         }]
@@ -2033,19 +1997,25 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             output += `⏱️ Completed in ${elapsed}s\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 | faf_go | faf_bi_sync`;
+            output += `\n💡 Next: faf_score | faf_go | faf_claude`;
             return { content: [{ type: 'text', text: output }] };
         }
         catch (error) {
@@ -2057,7 +2027,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
     }
     /**
      * 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);
@@ -2171,7 +2141,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             output += `\n🧬 MILESTONES\n`;
             const milestoneIcons = {
                 birth: '🐣', first_save: '💾', doubled: '2️⃣', sync: '🔄',
-                championship: '🏆', elite: '⭐', peak: '🏔️', perfect: '💎'
+                championship: '✪', elite: '⭐', peak: '🏔️', perfect: '💎'
             };
             for (const m of milestones) {
                 const icon = milestoneIcons[m.type] || '📍';
@@ -2220,7 +2190,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 };
             }
             // 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`;
@@ -2229,7 +2199,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 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)) {
@@ -2438,7 +2408,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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 {
@@ -2494,7 +2464,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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'
                     });
                 }
             }
@@ -2504,13 +2474,13 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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
@@ -2568,7 +2538,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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.`;
@@ -2586,7 +2556,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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);
@@ -2724,7 +2694,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add 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 }]