faf-mcp 3.0.0 → 3.0.2

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',
 ]);
@@ -192,7 +191,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_trust',
-                description: 'Validate a project.faf for structural integrity and field consistency. Returns trust metrics flagging malformed, missing, or contradictory data. Use this to confirm the context is sound before relying on it or syncing it to other formats.',
+                description: 'Validate a project.faf\'s required fields (faf_version, project.name) and about.* block with faf-cli\'s validator, and report its real score.',
                 annotations: {
                     title: 'Trust Score',
                     readOnlyHint: true,
@@ -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
@@ -245,7 +244,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_clear',
-                description: 'Remove the ~/.faf-cli-cache directory left by older faf-mcp versions. This version persists nothing outside your project files.',
+                description: 'Remove ~/.faf-cli-cache/technical-credit.json, the cache file left by faf-mcp versions before 3.0. Other files in ~/.faf-cli-cache are left in place.',
                 annotations: {
                     title: 'Clear .faf Data',
                     readOnlyHint: false,
@@ -255,8 +254,8 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        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)' }
+                        cache: { type: 'boolean', description: 'Remove ~/.faf-cli-cache/technical-credit.json (written by faf-mcp < 3.0)' },
+                        all: { type: 'boolean', description: 'Remove everything older versions left behind (default; today that is technical-credit.json)' }
                     },
                     additionalProperties: false
                 }
@@ -277,9 +276,9 @@ class FafToolHandler {
             },
             {
                 name: 'faf_read',
-                description: 'Read a file within the project root (cwd / FAF_ALLOWED_ROOTS). Paths that escape the project are refused.',
+                description: 'Read a file within the allowed roots (cwd, the OS temp dir, or FAF_ALLOWED_ROOTS). Paths outside them are refused.',
                 annotations: {
-                    title: 'Read .faf File',
+                    title: 'Read Project File',
                     readOnlyHint: true,
                     openWorldHint: false
                 },
@@ -297,11 +296,11 @@ class FafToolHandler {
             },
             {
                 name: 'faf_write',
-                description: 'Write a file within the project root (cwd / FAF_ALLOWED_ROOTS). Paths that escape the project are refused.',
+                description: 'Write a file within the allowed roots (cwd, the OS temp dir, or FAF_ALLOWED_ROOTS). Paths outside them are refused.',
                 annotations: {
-                    title: 'Write .faf File',
+                    title: 'Write Project File',
                     readOnlyHint: false,
-                    destructiveHint: false,
+                    destructiveHint: true,
                     openWorldHint: false
                 },
                 inputSchema: {
@@ -324,7 +323,7 @@ class FafToolHandler {
                 name: 'faf_list',
                 description: 'List directories and discover projects with project.faf files - Essential for FAF discovery workflow',
                 annotations: {
-                    title: 'List .faf Files',
+                    title: 'List Directories',
                     readOnlyHint: true,
                     openWorldHint: false
                 },
@@ -415,7 +414,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_check',
-                description: 'Inspect the human_context fields and rate each empty/generic/good/excellent. Returns the ratings; with protect it locks good/excellent fields from being overwritten, with unlock it releases them. Use this to gauge context quality and guard your best answers.',
+                description: 'Inspect the human_context fields and rate each empty/generic/good. Returns the ratings; with protect it records the good fields in _protected_fields as an advisory list (other tools do not enforce it), with unlock it clears that list. Use this to gauge context quality.',
                 annotations: {
                     title: 'Check .faf Health',
                     readOnlyHint: false,
@@ -425,8 +424,8 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        protect: { type: 'boolean', description: 'Lock good/excellent fields from being overwritten' },
-                        unlock: { type: 'boolean', description: 'Remove all field protections' },
+                        protect: { type: 'boolean', description: 'Record good fields in _protected_fields (advisory; other tools do not enforce it)' },
+                        unlock: { type: 'boolean', description: 'Clear the _protected_fields list' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     additionalProperties: false
@@ -434,7 +433,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_context',
-                description: 'Set or show the active project path that later faf_ calls resolve against. Returns the current context path. Call this once at the start of a session so the other tools target the right project.',
+                description: 'Set or show the active project path that later faf_ project tools resolve against (faf_read and faf_write resolve relative paths against the server\'s working directory instead). Returns the current context path. Call this once at the start of a session so the project tools target the right project.',
                 annotations: {
                     title: 'View Context',
                     readOnlyHint: true,
@@ -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 setup pipeline in one call — init or merge, stack detection, CLAUDE.md, and score — taking a project from no context to a scored project.faf plus CLAUDE.md; faf_go closes the human slots. 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,10 +491,11 @@ class FafToolHandler {
             },
             {
                 name: 'faf_dna',
-                description: 'Show your FAF DNA journey - See your evolution from birth to championship (22% 85% 99%)',
+                description: 'Show and record your FAF DNA journey — the score evolution of this project.faf from birth to today (e.g. 22% → 85% → 100%). Creates .faf-dna on the first call and appends a milestone when the score changes.',
                 annotations: {
                     title: 'View Project DNA',
-                    readOnlyHint: true,
+                    readOnlyHint: false,
+                    destructiveHint: false,
                     openWorldHint: false
                 },
                 inputSchema: {
@@ -508,7 +508,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_formats',
-                description: 'Scan the project for tech-stack signals across 150+ manifest types (package.json, Cargo.toml, pyproject.toml, go.mod, and more) and surface which project.faf stack slots to fill. Returns the detected formats and slot-fill recommendations. Use this to populate the technical context.',
+                description: 'Scan the project for tech-stack signals across 150+ manifest types (package.json, Cargo.toml, pyproject.toml, go.mod, and more). Returns the detected formats, the stack signature and faf-cli\'s slot-fill hints. Use this to see what stack detection finds.',
                 annotations: {
                     title: 'List Formats',
                     readOnlyHint: true,
@@ -545,7 +545,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_doctor',
-                description: 'Diagnose a project.faf setup — report missing files, empty or weak slots, and common configuration issues, each with how to fix it. Returns a prioritized checklist. Use this when your score is low and you need to know why.',
+                description: 'Diagnose a project.faf setup — report missing files, the real score with populated/active slot counts, and common configuration issues, each with a fix. Returns a checklist. Use this when your score is low and you need to know why.',
                 annotations: {
                     title: 'Diagnose Issues',
                     readOnlyHint: true,
@@ -560,11 +560,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,9 +574,9 @@ 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)' },
-                        force: { type: 'boolean', description: 'Force overwrite existing files' },
-                        merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
+                        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: 'Update the faf-managed block in an existing file (content outside it is preserved)' },
+                        merge: { type: 'boolean', description: 'Write the imported data into project.faf (without it, import only reports the section count and writes nothing)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     required: ['action'],
@@ -585,7 +585,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,9 +595,9 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        action: { type: 'string', enum: ['import', 'export', 'sync'], description: 'Action: import (.cursorrules -> .faf), export (.faf -> .cursorrules), sync (bidirectional)' },
-                        force: { type: 'boolean', description: 'Force overwrite existing files' },
-                        merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
+                        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: 'Update the faf-managed block in an existing file (content outside it is preserved)' },
+                        merge: { type: 'boolean', description: 'Write the imported data into project.faf (without it, import only reports the section count and writes nothing)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     required: ['action'],
@@ -606,7 +606,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,9 +616,9 @@ 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)' },
-                        force: { type: 'boolean', description: 'Force overwrite existing files' },
-                        merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
+                        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: 'Update the faf-managed block in an existing file (content outside it is preserved)' },
+                        merge: { type: 'boolean', description: 'Write the imported data into project.faf (without it, import only reports the section count and writes nothing)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     required: ['action'],
@@ -631,7 +631,7 @@ class FafToolHandler {
                 annotations: {
                     title: 'Sync Conductor',
                     readOnlyHint: false,
-                    destructiveHint: false,
+                    destructiveHint: true,
                     openWorldHint: false
                 },
                 inputSchema: {
@@ -639,7 +639,7 @@ class FafToolHandler {
                     properties: {
                         action: { type: 'string', enum: ['import', 'export'], description: 'Action: import (conductor/ -> .faf), export (.faf -> conductor/)' },
                         force: { type: 'boolean', description: 'Force overwrite existing files' },
-                        merge: { type: 'boolean', description: 'Merge imported data with existing .faf instead of replacing' },
+                        merge: { type: 'boolean', description: 'Write the imported data into project.faf (without it, import only reports the section count and writes nothing)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     required: ['action'],
@@ -648,18 +648,19 @@ 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,
-                    destructiveHint: false,
+                    destructiveHint: true,
                     openWorldHint: true
                 },
                 inputSchema: {
                     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.' },
+                        force: { type: 'boolean', description: 'Overwrite an existing project.faf at path (without it, faf_git refuses)' }
                     },
                     required: ['url'],
                     additionalProperties: false
@@ -689,8 +690,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 +738,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 +771,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 +780,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 +788,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
             };
@@ -817,7 +819,7 @@ class FafToolHandler {
         }
         // Strip ANSI from tier indicator (faf-cli emits colored glyphs).
         // eslint-disable-next-line no-control-regex
-        const strip = (s) => s.replace(/\[[0-9;]*m/g, '').trim();
+        const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '').trim();
         let raw;
         try {
             raw = readFafRaw(fafPath);
@@ -849,7 +851,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,
@@ -885,7 +887,7 @@ class FafToolHandler {
             output += `Empty (${emptySlots.length}): ${emptySlots.join(', ') || '(none)'}\n`;
             output += `Ignored (${ignoredSlots.length}): ${ignoredSlots.join(', ') || '(none)'}`;
             if (score < 100 && emptySlots.length > 0) {
-                output += `\n\nTip: fill empty slots or mark them \`slotignored\` to climb tiers. Slot-by-slot detail: \`faf score\` (CLI).`;
+                output += `\n\nTip: fill empty slots or mark them \`slotignored\` to climb tiers.`;
             }
         }
         return {
@@ -898,13 +900,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 +924,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 +942,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 +950,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 +978,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,14 +992,14 @@ 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
             };
         }
         const validation = validateFaf(data);
         let output = validation.valid
-            ? `✅ Structurally sound — no malformed, missing, or contradictory fields found.`
+            ? `✅ Required fields present (faf_version, project.name) — no validation errors.`
             : `❌ ${validation.errors.length} issue${validation.errors.length === 1 ? '' : 's'} found:\n` +
                 validation.errors.map((e) => `   • ${e}`).join('\n');
         try {
@@ -1045,7 +1012,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,61 +1029,72 @@ 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
             };
         }
-        const output = typeof result.data === 'string'
-            ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
+        // A dry run carries the fields it would change: list them by name, so the
+        // agent sees what `apply: true` would write instead of a bare count.
+        const changes = result.data?.changes;
+        const shown = (v) => v === undefined || v === null || v === '' ? '(empty)' : typeof v === 'string' ? v : JSON.stringify(v);
+        const output = Array.isArray(changes) && changes.length > 0
+            ? `${result.data.message}\n` +
+                changes.map((c) => `• ${c.path}: ${shown(c.oldValue)} → ${shown(c.newValue)}`).join('\n')
+            : typeof result.data === 'string'
+                ? result.data
+                : result.data?.output || JSON.stringify(result.data, null, 2);
         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
             };
         }
+        // The command's message (it carries "FAF Score: N%") plus the files it
+        // wrote, one per line — not the raw result object.
+        const filesChanged = Array.isArray(result.data?.filesChanged) ? result.data.filesChanged : [];
         const output = typeof result.data === 'string'
             ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
+            : `${result.data?.message ?? ''}` +
+                (filesChanged.length > 0 ? `\n\nFiles written:\n${filesChanged.map((f) => `• ${f}`).join('\n')}` : '');
         return {
             content: [{
                     type: 'text',
-                    text: `🔗 Claude FAF Bi-Sync:\n\n${output}`
+                    text: `🔗 FAF → CLAUDE.md:\n\n${output}`
                 }]
         };
     }
@@ -1159,7 +1137,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,21 +1166,21 @@ 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}
 
-Just like JPEG makes images universal,
+Just like JPEG makes images portable,
 .faf makes projects AI-readable.
 
 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: [{
@@ -1220,8 +1198,8 @@ WHAT: .faf = Foundational AI-context Format
 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%).
+HOW:  Run faf_init or faf_auto on any project to create one.
+      Run 'faf_score' to check AI-readiness (target: 100%).
 
 REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
 
@@ -1236,7 +1214,6 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
     async handleFafDebug(_args) {
         try {
             const fs = await import('fs');
-            const path = await import('path');
             const cwd = this.engineAdapter.getWorkingDirectory();
             const debugInfo = {
                 workingDirectory: cwd,
@@ -1247,11 +1224,10 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
                 permissions: {},
                 enginePath: this.engineAdapter.getEnginePath(),
             };
-            // Check write permissions
+            // Check write permissions — an access check, never a probe file in the
+            // user's workspace.
             try {
-                const testFile = path.join(cwd, '.claude-faf-test');
-                fs.writeFileSync(testFile, 'test');
-                fs.unlinkSync(testFile);
+                fs.accessSync(cwd, fs.constants.W_OK);
                 debugInfo.canWrite = true;
             }
             catch (error) {
@@ -1263,7 +1239,7 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
             const debugOutput = `🔍 faf-mcp Debug Information:
 
 📂 Working Directory: ${debugInfo.workingDirectory}
-✏️ Write Permissions: ${debugInfo.canWrite ? '✅ Yes' : '❌ No'}
+✏️ Write Permissions: ${debugInfo.canWrite ? '✅ writable' : '❌ not writable'}
 ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeError}\n` : ''}🤖 FAF Engine Path: ${debugInfo.enginePath}
 📋 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)'}
@@ -1283,7 +1259,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
             };
@@ -1319,23 +1295,18 @@ ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeErr
 - Confirm: "Creating at ~/Projects/heritage-club-dubai/"
 
 ## Real Filesystem Only
-- ✅ \`/Users/wolfejam/Projects/my-app/\`
+- ✅ \`~/Projects/my-app/\`
 - ❌ \`/mnt/user-data/\` (container paths)
 - ❌ \`/home/claude/\` (container paths)
 
 ## Commands
-All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
-
-**Core:**
-- \`faf init\` - create FAF (infer path from context)
-- \`faf score\` - show AI-readiness
-- \`faf sync\` - synchronize files
-- \`faf quick\` - rapid FAF creation
-
-**Extensions:**
-- \`new\` - force overwrite existing
-- \`full\` - detailed output
-- \`bi\` - bi-directional sync
+Call these MCP tools:
+- \`faf_init\` (path) - create project.faf (infer path from context)
+- \`faf_auto\` - init or merge, stack detection, CLAUDE.md, and score in one call
+- \`faf_score\` - show AI-readiness
+- \`faf_go\` - guided questions for the human slots, to 100%
+- \`faf_sync\` - reconcile project.faf with package.json (dry-run; \`apply: true\` writes)
+- \`faf_claude\` - write CLAUDE.md from project.faf (\`all: true\` also writes AGENTS.md, .cursorrules, GEMINI.md)
 
 ## UX Rules
 1. **Don't offer option menus** - just solve it
@@ -1495,7 +1466,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 {
@@ -1682,7 +1653,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 return {
                     content: [{
                             type: 'text',
-                            text: `🔓 FAF Check:\n\n✅ All fields unlocked\n📁 Updated: ${fafResult.filename}`
+                            text: `🔓 FAF Check:\n\n✅ Cleared _protected_fields\n📁 Updated: ${fafResult.filename}`
                         }]
                 };
             }
@@ -1700,14 +1671,15 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             for (const field of fields) {
                 qualities[field] = assessField(humanContext[field]);
             }
-            // Handle --protect
+            // Handle --protect. _protected_fields is an advisory list: it is
+            // recorded here and nothing else in faf-mcp reads it.
             if (args?.protect) {
-                const toProtect = fields.filter(f => qualities[f] === 'good' || qualities[f] === 'excellent');
+                const toProtect = fields.filter(f => qualities[f] === 'good');
                 if (toProtect.length === 0) {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `🔒 FAF Check:\n\n⚠️ No fields qualify for protection (need good or excellent quality)`
+                                text: `🔒 FAF Check:\n\n⚠️ No fields rated good — nothing recorded in _protected_fields`
                             }]
                     };
                 }
@@ -1716,13 +1688,13 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 return {
                     content: [{
                             type: 'text',
-                            text: `🔒 FAF Check:\n\n✅ Protected ${toProtect.length} field(s): ${toProtect.join(', ')}\n📁 Updated: ${fafResult.filename}`
+                            text: `🔒 FAF Check:\n\n✅ Recorded ${toProtect.length} field(s) in _protected_fields: ${toProtect.join(', ')}\nℹ️ Advisory only — other tools do not enforce it.\n📁 Updated: ${fafResult.filename}`
                         }]
                 };
             }
             // Default: show quality report
             const icons = {
-                empty: '⬜', generic: '🟡', good: '🟢', excellent: '💎'
+                empty: '⬜', generic: '◻️', good: '◼️'
             };
             let output = `🔍 FAF Human Context Quality\n\n`;
             for (const field of fields) {
@@ -1732,11 +1704,11 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 const displayValue = value.length > 40 ? value.substring(0, 37) + '...' : value;
                 output += `${icons[q]} ${locked} ${field.toUpperCase().padEnd(6)} ${displayValue}\n`;
             }
-            const goodCount = fields.filter(f => qualities[f] === 'good' || qualities[f] === 'excellent').length;
+            const goodCount = fields.filter(f => qualities[f] === 'good').length;
             const emptyCount = fields.filter(f => qualities[f] === 'empty').length;
             output += `\n📊 Quality: ${Math.round((goodCount / fields.length) * 100)}%\n`;
             if (protectedFields.length > 0) {
-                output += `🔒 Protected: ${protectedFields.join(', ')}\n`;
+                output += `🔒 _protected_fields (advisory, not enforced): ${protectedFields.join(', ')}\n`;
             }
             if (emptyCount > 0) {
                 output += `\n💡 Use faf_readme or faf_human_add to fill empty slots`;
@@ -1759,7 +1731,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 return {
                     content: [{
                             type: 'text',
-                            text: `📂 FAF Context Set:\n\n✅ Active project: ${newPath}\n${fafResult ? `✅ project.faf found: ${fafResult.filename}` : '⚠️ No project.faf in this directory'}\n\n💡 Subsequent faf_* calls will use this context`
+                            text: `📂 FAF Context Set:\n\n✅ Active project: ${newPath}\n${fafResult ? `✅ project.faf found: ${fafResult.filename}` : '⚠️ No project.faf in this directory'}\n\n💡 Later faf_ project tools use this context (faf_read / faf_write resolve relative paths against the server's working directory)`
                         }]
                 };
             }
@@ -1909,7 +1881,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)
                         }]
@@ -1961,7 +1933,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                             targetScore: 100,
                             questionsRemaining: questions.length,
                             questions,
-                            instructions: 'Use AskUserQuestion to ask these questions, then call faf_go again with the answers parameter to apply them.'
+                            instructions: 'Ask the user these questions, then call faf_go again with the answers parameter.'
                         }, null, 2)
                     }]
             };
@@ -2026,38 +1998,44 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             // Format output
             const deltaDisplay = scoreDelta > 0 ? `(+${scoreDelta}%)` : scoreDelta < 0 ? `(${scoreDelta}%)` : '(no change)';
-            let output = `🏎️⚡️ FAF AUTO - CHAMPIONSHIP MODE!\n`;
+            let output = `⚡️ FAF AUTO\n`;
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
             output += steps.join('\n') + '\n\n';
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
             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) {
             return {
-                content: [{ type: 'text', text: `🏎️ FAF Auto:\n\n❌ Error: ${error.message}` }],
+                content: [{ type: 'text', text: `⚡️ FAF Auto:\n\n❌ Error: ${error.message}` }],
                 isError: true
             };
         }
     }
     /**
      * 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 +2149,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] || '📍';
@@ -2212,15 +2190,18 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             const analysis = await (0, turbocat_bridge_js_1.turboCatDisplay)(cwd);
             const elapsed = Date.now() - startTime;
             if (args?.json) {
+                // The sum of format priorities is not a FAF score; name it for what
+                // it is so no second "score" reaches clients next to faf_score's.
+                const { totalIntelligenceScore, ...rest } = analysis;
                 return {
                     content: [{
                             type: 'text',
-                            text: JSON.stringify(analysis, null, 2)
+                            text: JSON.stringify({ ...rest, formatPriorityTotal: totalIntelligenceScore }, null, 2)
                         }]
                 };
             }
             // 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`;
@@ -2228,8 +2209,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             for (const format of sorted) {
                 output += `  ✅ ${format.fileName}\n`;
             }
-            output += `\n💡 Stack Signature: ${analysis.stackSignature}\n`;
-            output += `🏆 Intelligence Score: ${analysis.totalIntelligenceScore}\n\n`;
+            output += `\n💡 Stack Signature: ${analysis.stackSignature}\n\n`;
             if (Object.keys(analysis.slotFillRecommendations).length > 0) {
                 output += `📊 Recommended Slot Fills:\n`;
                 for (const [key, value] of Object.entries(analysis.slotFillRecommendations)) {
@@ -2274,7 +2254,7 @@ Examples:
   "api-service, REST API for mobile app, python, fastapi, aws"
   "cli-tool, developer productivity tool, go"
 
-Minimum: name and description. Rest is auto-detected!`
+Minimum: name and description. Rest is optional.`
                         }]
                 };
             }
@@ -2295,7 +2275,8 @@ Example: "my-app, e-commerce platform"`
             }
             const projectName = parts[0] || 'my-project';
             const projectGoal = parts[1] || 'Build amazing software';
-            const mainLanguage = parts[2] || 'TypeScript';
+            // Only what the user gave: no language is written unless they named one.
+            const mainLanguage = parts[2] || undefined;
             const framework = parts[3] || 'none';
             const hosting = parts[4] || 'cloud';
             // Check if .faf exists
@@ -2313,16 +2294,16 @@ Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
                 };
             }
             // Detect project type from inputs
-            const projectType = this.detectProjectTypeFromQuick(projectGoal, framework, mainLanguage);
+            const projectType = this.detectProjectTypeFromQuick(projectGoal, framework, mainLanguage ?? '');
             // Build .faf content
             const fafData = {
+                faf_version: '3.0',
                 project: {
                     name: projectName,
                     goal: projectGoal,
-                    main_language: mainLanguage
+                    ...(mainLanguage ? { main_language: mainLanguage } : {})
                 },
                 type: projectType,
-                generated: new Date().toISOString(),
                 version: version_1.VERSION,
                 initialized_by: 'faf-mcp-quick'
             };
@@ -2340,7 +2321,8 @@ Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
             let output = `⚡ FAF Quick - Created in ${elapsed}ms!\n\n`;
             output += `📦 Project: ${projectName}\n`;
             output += `🎯 Purpose: ${projectGoal}\n`;
-            output += `💻 Stack: ${mainLanguage}${framework !== 'none' ? ` + ${framework}` : ''}\n`;
+            const stackShown = [mainLanguage, framework !== 'none' ? framework : undefined].filter(Boolean).join(' + ');
+            output += `💻 Stack: ${stackShown || '(not given)'}\n`;
             output += `📍 Type: ${projectType}\n\n`;
             output += `✅ Created: ${fafPath}\n\n`;
             output += `Next steps:\n`;
@@ -2438,7 +2420,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 {
@@ -2479,7 +2461,7 @@ Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
                             results.push({
                                 status: 'warning',
                                 message: `Score could be better: ${score}% (${slotSummary})`,
-                                fix: 'Target 70%+ for championship AI context'
+                                fix: 'Run faf_go — the target is 100%'
                             });
                         }
                         else {
@@ -2494,7 +2476,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 +2486,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 +2550,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 — no issues found.`;
             }
             else if (!hasErrors) {
                 output += `🎯 Good health with minor improvements suggested.`;
@@ -2586,7 +2568,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);
@@ -2710,9 +2692,12 @@ Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
         }
         const outputPath = args?.path ? this.getProjectPath(args.path) : undefined;
         try {
+            // --force goes last: the engine reads url and the output path from the
+            // positional args, flags excluded.
             const result = await this.engineAdapter.callEngine('git', [
                 url,
                 ...(outputPath ? [outputPath] : []),
+                ...(args?.force ? ['--force'] : []),
             ]);
             if (!result.success) {
                 return {
@@ -2722,9 +2707,9 @@ Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
             }
             const data = result.data;
             let output = `GitHub Context:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms`;
-            // Include generated .faf content if no output path (preview mode)
+            // Include the authored .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 }]