faf-mcp 1.3.1 → 2.0.0

package/dist/src/handlers/tools.js

@@ -36,7 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FafToolHandler = void 0;
 const fileHandler_1 = require("./fileHandler");
 const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
+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 version_1 = require("../version");
@@ -46,105 +47,200 @@ class FafToolHandler {
     constructor(engineAdapter) {
         this.engineAdapter = engineAdapter;
     }
+    /**
+     * Get the project path - uses explicit path if provided, otherwise returns current context
+     * If an explicit path is provided, it also sets the session context for subsequent calls
+     */
+    getProjectPath(explicitPath) {
+        if (explicitPath) {
+            // Expand tilde
+            const expandedPath = explicitPath.startsWith('~')
+                ? pathModule.join(os.homedir(), explicitPath.slice(1))
+                : explicitPath;
+            // Resolve to absolute path
+            const resolvedPath = pathModule.resolve(expandedPath);
+            // If it's a file path, get the directory
+            const projectDir = fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()
+                ? pathModule.dirname(resolvedPath)
+                : resolvedPath;
+            // Set as the new session context
+            if (fs.existsSync(projectDir)) {
+                this.engineAdapter.setWorkingDirectory(projectDir);
+            }
+            return projectDir;
+        }
+        return this.engineAdapter.getWorkingDirectory();
+    }
     async listTools() {
         return {
             tools: [
                 {
                     name: 'faf_about',
-                    description: 'Learn what .faf format is - THE JPEG for AI 🧡⚡️',
+                    description: 'Learn what .faf format is - project DNA for AI 🧡⚡️',
+                    annotations: {
+                        title: 'About FAF',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_what',
-                    description: 'What is .faf format? Quick explanation of THE JPEG for AI 🧡⚡️',
+                    description: 'What is .faf format? Quick explanation of project DNA for AI 🧡⚡️',
+                    annotations: {
+                        title: 'What is FAF',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_status',
-                    description: 'Check if your project has project.faf (THE JPEG for AI) - Shows AI-readability status 🧡⚡️',
+                    description: 'Check if your project has project.faf (project DNA for AI) - Shows AI-readability status 🧡⚡️',
+                    annotations: {
+                        title: 'Project Status',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
-                        properties: {},
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_score',
-                    description: 'Calculate your project\'s AI-readability from project.faf (THE JPEG for AI) - F1-inspired metrics! 🧡⚡️',
+                    description: 'Calculate your project\'s AI-readability from project.faf (project DNA for AI) - F1-inspired metrics! 🧡⚡️',
+                    annotations: {
+                        title: 'AI-Readiness Score',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            details: { type: 'boolean', description: 'Include detailed breakdown and improvement suggestions' }
+                            details: { type: 'boolean', description: 'Include detailed breakdown and improvement suggestions' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_init',
-                    description: 'Create project.faf (THE JPEG for AI) - Makes your project instantly AI-readable 🧡⚡️. Use Projects convention (~/Projects/[name]/project.faf) by default. Run faf_guide for path resolution rules.',
+                    description: 'Create project.faf (project DNA for AI) - Makes your project instantly AI-readable 🧡⚡️. Just enter path or project name. Examples: ~/Projects/my-app, my-app, /full/path/to/project',
+                    annotations: {
+                        title: 'Initialize .faf',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            force: { type: 'boolean', description: 'Force reinitialize existing FAF context' },
-                            directory: { type: 'string', description: 'Project directory path (supports ~ tilde expansion). Creates directory if it doesn\'t exist.' },
-                            path: { type: 'string', description: 'Alias for directory parameter' },
-                            projectName: { type: 'string', description: 'Project name for path inference (used with Projects convention)' }
+                            path: {
+                                type: 'string',
+                                description: 'Project path or name. Smart resolution: "my-app" finds ~/Projects/my-app OR ~/Code/my-app. Full paths like ~/Projects/app or /Users/me/code/app work too. Omit to use current directory.'
+                            },
+                            force: { type: 'boolean', description: 'Overwrite existing project.faf if it exists' }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_trust',
-                    description: 'Validate project.faf integrity - Trust metrics for THE JPEG for AI 🧡⚡️',
+                    description: 'Validate project.faf integrity - Trust metrics for project DNA for AI 🧡⚡️',
+                    annotations: {
+                        title: 'Trust Score',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_sync',
-                    description: 'Sync project.faf (THE JPEG for AI) with CLAUDE.md - Bi-directional context 🧡⚡️',
+                    description: 'Sync project.faf (project DNA for AI) with CLAUDE.md - Bi-directional context 🧡⚡️',
+                    annotations: {
+                        title: 'Sync .faf to CLAUDE.md',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
-                        properties: {},
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_enhance',
-                    description: 'Enhance project.faf (THE JPEG for AI) with AI optimization - SPEEDY AI you can TRUST! 🧡⚡️',
+                    description: 'Enhance project.faf (project DNA for AI) with AI optimization - SPEEDY AI you can TRUST! 🧡⚡️',
+                    annotations: {
+                        title: 'Enhance .faf',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
                             model: { type: 'string', description: 'Target AI model: claude|chatgpt|gemini|universal (default: claude)' },
                             focus: { type: 'string', description: 'Enhancement focus: claude-optimal|human-context|ai-instructions|completeness' },
                             consensus: { type: 'boolean', description: 'Build consensus from multiple AI models' },
-                            dryRun: { type: 'boolean', description: 'Preview enhancement without applying changes' }
+                            dryRun: { type: 'boolean', description: 'Preview enhancement without applying changes' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_bi_sync',
-                    description: 'Platform-aware sync: project.faf to .cursorrules, .clinerules, .windsurfrules, CLAUDE.md',
+                    description: 'Bi-directional sync between project.faf and CLAUDE.md. v4.5.0: Also sync to AGENTS.md, .cursorrules, GEMINI.md!',
+                    annotations: {
+                        title: 'Bi-directional Sync',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
                             auto: { type: 'boolean', description: 'Enable automatic synchronization' },
                             watch: { type: 'boolean', description: 'Start real-time file watching for changes' },
                             force: { type: 'boolean', description: 'Force overwrite conflicting changes' },
-                            target: {
-                                type: 'string',
-                                enum: ['auto', '.clinerules', '.cursorrules', '.windsurfrules', 'CLAUDE.md', 'all'],
-                                description: 'Sync target: auto (detect existing), specific platform, or all'
-                            }
+                            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' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_clear',
                     description: 'Clear caches, temporary files, and reset FAF state for a fresh start',
+                    annotations: {
+                        title: 'Clear .faf Data',
+                        readOnlyHint: false,
+                        destructiveHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -153,19 +249,31 @@ class FafToolHandler {
                             backups: { type: 'boolean', description: 'Clear backup files only' },
                             all: { type: 'boolean', description: 'Clear everything (default)' }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_debug',
                     description: 'Debug Claude FAF MCP environment - show working directory, permissions, and FAF CLI status',
+                    annotations: {
+                        title: 'Debug Info',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_read',
                     description: 'Read content from any file on the local filesystem',
+                    annotations: {
+                        title: 'Read .faf File',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -175,11 +283,18 @@ class FafToolHandler {
                             }
                         },
                         required: ['path'],
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_write',
                     description: 'Write content to any file on the local filesystem',
+                    annotations: {
+                        title: 'Write .faf File',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -193,11 +308,17 @@ class FafToolHandler {
                             }
                         },
                         required: ['path', 'content'],
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_list',
                     description: 'List directories and discover projects with project.faf files - Essential for FAF discovery workflow',
+                    annotations: {
+                        title: 'List .faf Files',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -221,19 +342,31 @@ class FafToolHandler {
                             }
                         },
                         required: ['path'],
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_chat',
                     description: '🗣️ Natural language project.faf generation - Ask 6W questions (Who/What/Why/Where/When/How) to build complete human context 🧡⚡️',
+                    annotations: {
+                        title: 'Chat about FAF',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_friday',
                     description: '🎉 Friday Features - Chrome Extension detection, fuzzy matching & more! 🧡⚡️',
+                    annotations: {
+                        title: 'Fun FAF Facts',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -242,16 +375,315 @@ class FafToolHandler {
                                 description: 'Test fuzzy matching with typos like "raect" or "chr ext"'
                             }
                         },
+                        additionalProperties: false
                     }
                 },
                 {
                     name: 'faf_guide',
                     description: 'FAF MCP usage guide for Claude Desktop - Projects convention, path resolution, and UX patterns',
+                    annotations: {
+                        title: 'Usage Guide',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
                     inputSchema: {
                         type: 'object',
                         properties: {},
+                        additionalProperties: false
                     }
-                }
+                },
+                {
+                    name: 'faf_readme',
+                    description: '📖 Extract 6 Ws (Who/What/Why/Where/When/How) from README.md into human_context - Smart pattern matching 🧡⚡️',
+                    annotations: {
+                        title: 'Extract from README',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            apply: { type: 'boolean', description: 'Apply extracted content to project.faf (default: preview only)' },
+                            force: { type: 'boolean', description: 'Overwrite existing human_context values (default: only fill empty slots)' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_human_add',
+                    description: '🧡 Add a human_context field (who/what/why/where/when/how) - Non-interactive for MCP 🧡⚡️',
+                    annotations: {
+                        title: 'Add Human Context',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            field: {
+                                type: 'string',
+                                enum: ['who', 'what', 'why', 'where', 'when', 'how'],
+                                description: 'The 6 W field to set'
+                            },
+                            value: { type: 'string', description: 'The value to set for the field' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        required: ['field', 'value'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_check',
+                    description: '🔍 Quality inspection for human_context fields + field protection - Shows empty/generic/good/excellent ratings 🧡⚡️',
+                    annotations: {
+                        title: 'Check .faf Health',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            protect: { type: 'boolean', description: 'Lock good/excellent fields from being overwritten' },
+                            unlock: { type: 'boolean', description: 'Remove all field protections' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_context',
+                    description: '📂 Set or view active project context - Path is remembered for subsequent faf_ calls 🧡⚡️',
+                    annotations: {
+                        title: 'View Context',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Set active project path. If omitted, shows current context.' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_go',
+                    description: '🎯 Guided interview to Gold Code - Claude asks questions till you hit 100%! Returns questions for missing fields, then apply answers to reach Gold Code 🧡⚡️',
+                    annotations: {
+                        title: 'Guided Setup',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
+                            answers: {
+                                type: 'object',
+                                description: 'Answers to apply. Keys are field paths (e.g., "project.goal", "human_context.why"), values are the answers. If provided, applies answers and returns new score.',
+                                additionalProperties: { type: 'string' }
+                            }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_auto',
+                    description: '🏎️ ONE COMMAND TO RULE THEM ALL - Zero to Championship AI context instantly! Runs init + sync + formats + bi-sync + score in one go 🧡⚡️',
+                    annotations: {
+                        title: 'Auto-detect Context',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
+                            force: { type: 'boolean', description: 'Force overwrite existing files' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_dna',
+                    description: '🧬 Show your FAF DNA journey - See your evolution from birth to championship (22% → 85% → 99%) 🧡⚡️',
+                    annotations: {
+                        title: 'View Project DNA',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_formats',
+                    description: '😽 TURBO-CAT format discovery - Discovers all formats in your project (154+ validated types!) and fills stack slots 🧡⚡️',
+                    annotations: {
+                        title: 'List Formats',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
+                            json: { type: 'boolean', description: 'Return results as JSON' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_quick',
+                    description: '⚡ Lightning-fast .faf creation - One-liner format: "name, description, language, framework, hosting" 🧡⚡️',
+                    annotations: {
+                        title: 'Quick Create',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
+                            input: { type: 'string', description: 'Quick input: "project-name, description, language, framework, hosting" (minimum: name, description)' },
+                            force: { type: 'boolean', description: 'Force overwrite existing .faf file' }
+                        },
+                        required: ['input'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_doctor',
+                    description: '🏥 Health check for your .faf setup - Diagnose and fix common issues 🧡⚡️',
+                    annotations: {
+                        title: 'Diagnose Issues',
+                        readOnlyHint: true,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        additionalProperties: false
+                    }
+                },
+                // ============================================================================
+                // v4.5.0 INTEROP TOOLS
+                // ============================================================================
+                {
+                    name: 'faf_agents',
+                    description: 'Import/Export/Sync between AGENTS.md (OpenAI/Codex) and project.faf - AI interop!',
+                    annotations: {
+                        title: 'Sync AGENTS.md',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    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' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        required: ['action'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_cursor',
+                    description: 'Import/Export/Sync between .cursorrules (Cursor IDE) and project.faf - AI interop!',
+                    annotations: {
+                        title: 'Sync .cursorrules',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    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' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        required: ['action'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_gemini',
+                    description: 'Import/Export/Sync between GEMINI.md (Google Gemini CLI) and project.faf - AI interop!',
+                    annotations: {
+                        title: 'Sync GEMINI.md',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    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' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        required: ['action'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_conductor',
+                    description: 'Import/Export between conductor/ directory (Google Conductor) and project.faf - AI interop!',
+                    annotations: {
+                        title: 'Sync Conductor',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    inputSchema: {
+                        type: 'object',
+                        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' },
+                            path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        },
+                        required: ['action'],
+                        additionalProperties: false
+                    }
+                },
+                {
+                    name: 'faf_git',
+                    description: 'Generate project.faf from any GitHub repo URL - 1-click context extraction!',
+                    annotations: {
+                        title: 'Extract from GitHub',
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        openWorldHint: false
+                    },
+                    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.' }
+                        },
+                        required: ['url'],
+                        additionalProperties: false
+                    }
+                },
             ]
         };
     }
@@ -283,8 +715,15 @@ class FafToolHandler {
                 return await this.handleFafAbout(args);
             case 'faf_what':
                 return await this.handleFafWhat(args);
-            case 'faf_read':
-                return await fileHandler_1.fileHandlers.faf_read(args);
+            case 'faf_read': {
+                // Handle faf_read specially to set context when reading project.faf files
+                const readResult = await fileHandler_1.fileHandlers.faf_read(args);
+                // If reading a project.faf file, set the session context
+                if (args?.path && (args.path.includes('project.faf') || args.path.endsWith('.faf'))) {
+                    this.getProjectPath(args.path);
+                }
+                return readResult;
+            }
             case 'faf_chat':
                 return await this.handleFafChat(args);
             case 'faf_friday':
@@ -295,13 +734,44 @@ class FafToolHandler {
                 return await this.handleFafList(args);
             case 'faf_guide':
                 return await this.handleFafGuide(args);
+            case 'faf_readme':
+                return await this.handleFafReadme(args);
+            case 'faf_human_add':
+                return await this.handleFafHumanAdd(args);
+            case 'faf_check':
+                return await this.handleFafCheck(args);
+            case 'faf_context':
+                return await this.handleFafContext(args);
+            case 'faf_go':
+                return await this.handleFafGo(args);
+            case 'faf_auto':
+                return await this.handleFafAuto(args);
+            case 'faf_dna':
+                return await this.handleFafDna(args);
+            case 'faf_formats':
+                return await this.handleFafFormats(args);
+            case 'faf_quick':
+                return await this.handleFafQuick(args);
+            case 'faf_doctor':
+                return await this.handleFafDoctor(args);
+            // v4.5.0 Interop tools
+            case 'faf_agents':
+                return await this.handleFafAgents(args);
+            case 'faf_cursor':
+                return await this.handleFafCursor(args);
+            case 'faf_gemini':
+                return await this.handleFafGemini(args);
+            case 'faf_conductor':
+                return await this.handleFafConductor(args);
+            case 'faf_git':
+                return await this.handleFafGit(args);
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
     }
-    async handleFafStatus(_args) {
+    async handleFafStatus(args) {
         // Native implementation - no CLI needed!
-        const cwd = this.engineAdapter.getWorkingDirectory();
+        const cwd = this.getProjectPath(args?.path);
         try {
             const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
             if (!fafResult) {
@@ -335,8 +805,8 @@ class FafToolHandler {
         try {
             const fs = await import('fs').then(m => m.promises);
             const path = await import('path');
-            // Get current working directory from engine adapter (smart detection)
-            const cwd = this.engineAdapter.getWorkingDirectory();
+            // Get current working directory - uses path param or session context
+            const cwd = this.getProjectPath(args?.path);
             // Score calculation components
             let score = 0;
             const details = [];
@@ -405,44 +875,40 @@ class FafToolHandler {
                     output += `\n💡 Note: 🍊 Big Orange is a BADGE awarded separately for excellence beyond metrics.`;
                 }
             }
-            else if (score >= 99) {
-                // Maximum technical score
-                output = `📊 FAF SCORE: 99%\n⚡ Maximum Technical\n🏁 Claude grants 100%\n\n`;
-                if (args?.details) {
-                    output += details.join('\n');
-                    output += `\n\n💡 Only Claude can grant the final 1% for perfect collaboration!`;
-                }
-            }
             else {
-                // Regular score
-                const percentage = Math.min(score, 99);
+                // Regular score - FAF standard tiers
+                const percentage = Math.min(score, 100);
                 let rating = '';
                 let emoji = '';
-                if (percentage >= 90) {
-                    rating = 'Excellent';
-                    emoji = '🏆';
+                if (percentage >= 99) {
+                    rating = 'Gold';
+                    emoji = '🥇';
+                }
+                else if (percentage >= 95) {
+                    rating = 'Silver';
+                    emoji = '🥈';
                 }
-                else if (percentage >= 80) {
-                    rating = 'Very Good';
-                    emoji = '⭐';
+                else if (percentage >= 85) {
+                    rating = 'Bronze';
+                    emoji = '🥉';
                 }
                 else if (percentage >= 70) {
-                    rating = 'Good';
-                    emoji = '✨';
+                    rating = 'Green';
+                    emoji = '🟢';
                 }
-                else if (percentage >= 60) {
-                    rating = 'Improving';
-                    emoji = '📈';
+                else if (percentage >= 55) {
+                    rating = 'Yellow';
+                    emoji = '🟡';
                 }
                 else {
-                    rating = 'Getting Started';
-                    emoji = '🚀';
+                    rating = 'Red';
+                    emoji = '🔴';
                 }
                 // The 3-line killer display
-                output = `📊 FAF SCORE: ${percentage}%\n${emoji} ${rating}\n🏁 AI-Ready: ${percentage >= 70 ? 'Yes' : 'Building'}\n`;
+                output = `📊 FAF SCORE: ${percentage}%\n${emoji} ${rating}\n🏁 AI-Ready: ${percentage >= 85 ? 'Yes' : 'Building'}\n`;
                 if (args?.details) {
                     output += `\n${details.join('\n')}`;
-                    if (percentage < 99) {
+                    if (percentage < 100) {
                         output += `\n\n💡 Tips to improve:\n`;
                         if (!hasFaf)
                             output += `- Create .faf file with project context\n`;
@@ -473,43 +939,18 @@ class FafToolHandler {
         }
     }
     async handleFafInit(args) {
-        // Native implementation - creates project.faf with Projects convention!
+        // Native implementation - creates project.faf with Pomelli-simple path resolution!
         try {
-            // Determine project path using Projects convention or explicit path
-            let targetDir;
-            let projectName;
-            // Accept both 'directory' (legacy) and 'path' (new)
-            const explicitPath = args?.path || args?.directory;
-            if (explicitPath) {
-                // User explicit path always wins
-                // Expand tilde (~) to home directory
-                const expandedPath = explicitPath.startsWith('~')
-                    ? path.join(require('os').homedir(), explicitPath.slice(1))
-                    : explicitPath;
-                targetDir = path.resolve(expandedPath);
-                projectName = path.basename(targetDir);
-                // Ensure directory exists
-                if (!fs.existsSync(targetDir)) {
-                    fs.mkdirSync(targetDir, { recursive: true });
-                }
-            }
-            else if (args?.projectName) {
-                // Use Projects convention with provided name
-                (0, path_resolver_1.ensureProjectsDirectory)();
-                const resolution = (0, path_resolver_1.resolveProjectPath)(args.projectName);
-                targetDir = resolution.projectPath;
-                projectName = resolution.projectName;
-                // Ensure project directory exists
-                if (!fs.existsSync(targetDir)) {
-                    fs.mkdirSync(targetDir, { recursive: true });
-                }
-            }
-            else {
-                // Use current working directory (legacy behavior)
-                targetDir = this.engineAdapter.getWorkingDirectory();
-                projectName = path.basename(targetDir);
+            // Use smart path resolution (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)) {
+                fs.mkdirSync(targetDir, { recursive: true });
             }
-            const fafPath = path.join(targetDir, 'project.faf');
             // Check if any FAF file exists and force flag
             const existingFaf = await (0, faf_file_finder_js_1.findFafFile)(targetDir);
             if (existingFaf && !args?.force) {
@@ -538,8 +979,7 @@ class FafToolHandler {
                 projectData = (0, fuzzy_detector_1.applyIntelFriday)(projectData);
             }
             // Create enhanced .faf content
-            const fafContent = `# USE>FAF - call FAF-MCP (or faf/cli)
-# FAF - Foundational AI Context
+            const fafContent = `# FAF - Foundational AI Context
 project: ${projectData.project}
 type: ${projectData.project_type}${chromeDetection.detected ? ' 🎯' : ''}
 context: I⚡🍊
@@ -568,10 +1008,15 @@ build: ${projectData.build}
 package_manager: ${projectData.package_manager}` : ''}
 `;
             fs.writeFileSync(fafPath, fafContent);
+            // Pomelli-style success confirmation with path resolution info
+            const pathConfirmation = (0, path_resolver_1.formatPathConfirmation)(resolution);
+            const sourceExplanation = resolution.source === 'user-name'
+                ? `\n\n💡 Smart resolution: "${userInput}" → ${targetDir}`
+                : '';
             return {
                 content: [{
                         type: 'text',
-                        text: `🚀 Claude FAF Initialization:\n\n✅ Created project.faf in ${targetDir}\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}"` : ''}`
+                        text: `🚀 Claude FAF Initialization:\n\n✅ Created project.faf\n\n${pathConfirmation}${sourceExplanation}\n\n🍊 Vitamin Context activated!\n⚡ FAFFLESS AI ready!${chromeDetection.detected ? '\n\n🎯 Friday Feature: Chrome Extension detected!\n📈 Auto-filled 7 slots for 90%+ score!' : ''}${chromeDetection.corrected ? `\n📝 Auto-corrected: "${args?.description}" → "${chromeDetection.corrected}"` : ''}\n\n🏁 Next steps:\n  • Run faf_score for AI-readiness score\n  • Run faf_sync to create CLAUDE.md\n  • Run faf_enhance to improve context`
                     }]
             };
         }
@@ -606,7 +1051,11 @@ package_manager: ${projectData.package_manager}` : ''}
                 }]
         };
     }
-    async handleFafSync(_args) {
+    async handleFafSync(args) {
+        // Set project context if path provided
+        if (args?.path) {
+            this.getProjectPath(args.path);
+        }
         const result = await this.engineAdapter.callEngine('sync');
         if (!result.success) {
             return {
@@ -628,6 +1077,10 @@ package_manager: ${projectData.package_manager}` : ''}
         };
     }
     async handleFafEnhance(args) {
+        // Set project context if path provided
+        if (args?.path) {
+            this.getProjectPath(args.path);
+        }
         const enhanceArgs = [];
         // Default to Claude optimization if no model specified
         const model = args?.model || 'claude';
@@ -653,7 +1106,7 @@ package_manager: ${projectData.package_manager}` : ''}
         }
         const output = typeof result.data === 'string'
             ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
+            : result.data?.message || result.data?.output || JSON.stringify(result.data, null, 2);
         return {
             content: [{
                     type: 'text',
@@ -662,6 +1115,10 @@ package_manager: ${projectData.package_manager}` : ''}
         };
     }
     async handleFafBiSync(args) {
+        // Set project context if path provided
+        if (args?.path) {
+            this.getProjectPath(args.path);
+        }
         const biSyncArgs = [];
         if (args?.auto) {
             biSyncArgs.push('--auto');
@@ -672,9 +1129,6 @@ package_manager: ${projectData.package_manager}` : ''}
         if (args?.force) {
             biSyncArgs.push('--force');
         }
-        if (args?.target) {
-            biSyncArgs.push(`--target=${args.target}`);
-        }
         const result = await this.engineAdapter.callEngine('bi-sync', biSyncArgs);
         if (!result.success) {
             return {
@@ -740,7 +1194,7 @@ package_manager: ${projectData.package_manager}` : ''}
             npm: 'https://www.npmjs.com/package/claude-faf-mcp'
         };
         const aboutText = `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🤖 .faf = THE JPEG for AI
+🤖 .faf = project DNA for AI
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 WHAT IS .FAF?
@@ -773,7 +1227,7 @@ HOW IT WORKS:
         };
     }
     async handleFafWhat(_args) {
-        const whatText = `.faf = THE JPEG for AI
+        const whatText = `.faf = project DNA for AI
 
 WHAT: .faf = Foundational AI-context Format
       (The dot means it's a file format, like .jpg or .pdf)
@@ -800,7 +1254,7 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
             const path = await import('path');
             const { exec } = await import('child_process');
             const { promisify } = await import('util');
-            const execAsync = promisify(exec);
+            const _execAsync = promisify(exec);
             const cwd = this.engineAdapter.getWorkingDirectory();
             const debugInfo = {
                 workingDirectory: cwd,
@@ -1032,7 +1486,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             const showHidden = args?.showHidden || false;
             // Expand tilde
             const expandedPath = targetPath.startsWith('~')
-                ? path.join(require('os').homedir(), targetPath.slice(1))
+                ? path.join(os.homedir(), targetPath.slice(1))
                 : targetPath;
             const resolvedPath = path.resolve(expandedPath);
             // Check if directory exists
@@ -1137,6 +1591,1553 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             };
         }
     }
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // NEW: Human Context Tools (v3.2.0 parity)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    async handleFafReadme(args) {
+        try {
+            const path = await import('path');
+            const cwd = this.getProjectPath(args?.path);
+            // Find README.md
+            const readmePath = path.join(cwd, 'README.md');
+            if (!fs.existsSync(readmePath)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `📖 FAF README Extraction:\n\n❌ No README.md found in ${cwd}\n💡 Create a README.md first`
+                        }],
+                    isError: true
+                };
+            }
+            // Find project.faf
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (!fafResult) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `📖 FAF README Extraction:\n\n❌ No project.faf found in ${cwd}\n💡 Run faf_init first`
+                        }],
+                    isError: true
+                };
+            }
+            // Read README content
+            const readmeContent = fs.readFileSync(readmePath, 'utf-8');
+            // Extract 6 Ws using simple pattern matching
+            const extracted = this.extractSixWsFromReadme(readmeContent);
+            if (!args?.apply) {
+                // Preview mode
+                let output = `📖 FAF README Extraction (Preview)\n\n`;
+                output += `Found in README.md:\n`;
+                for (const [field, value] of Object.entries(extracted)) {
+                    if (value) {
+                        output += `  ${field.toUpperCase()}: ${value}\n`;
+                    }
+                }
+                output += `\n💡 Use apply: true to save to project.faf`;
+                return { content: [{ type: 'text', text: output }] };
+            }
+            // Apply mode - update project.faf
+            const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
+            const yaml = await import('yaml');
+            const fafData = yaml.parse(fafContent) || {};
+            if (!fafData.human_context) {
+                fafData.human_context = {};
+            }
+            let appliedCount = 0;
+            for (const [field, value] of Object.entries(extracted)) {
+                if (value) {
+                    const existingValue = fafData.human_context[field];
+                    if (!existingValue || args?.force) {
+                        fafData.human_context[field] = value;
+                        appliedCount++;
+                    }
+                }
+            }
+            fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `📖 FAF README Extraction:\n\n✅ Applied ${appliedCount} field(s) to human_context\n📁 Updated: ${fafResult.filename}`
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `📖 FAF README Extraction:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    extractSixWsFromReadme(content) {
+        const result = {
+            who: null, what: null, why: null, where: null, when: null, how: null
+        };
+        // WHAT: First paragraph after title
+        const whatMatch = content.match(/^#\s+[^\n]+\n+(?:\*\*[^*]+\*\*\n+)?([A-Z][^#\n]{30,})/m);
+        if (whatMatch)
+            result.what = whatMatch[1].trim().substring(0, 200);
+        // WHO: Look for "team", "company", "by", "for"
+        const whoMatch = content.match(/(?:built by|created by|maintained by|for|team)\s+([^\n.]{10,50})/i);
+        if (whoMatch)
+            result.who = whoMatch[1].trim();
+        // WHY: Look for "because", "to", benefits
+        const whyMatch = content.match(/(?:because|to help|enables|allows|makes it)\s+([^\n.]{15,100})/i);
+        if (whyMatch)
+            result.why = whyMatch[1].trim();
+        // WHERE: Look for deployment/runtime mentions
+        const whereMatch = content.match(/(?:runs on|deployed to|works with|for)\s+(browser|server|edge|npm|cargo|cloud|local)/i);
+        if (whereMatch)
+            result.where = whereMatch[0].trim();
+        // WHEN: Look for version, date
+        const whenMatch = content.match(/(?:version|v)\s*(\d+\.\d+(?:\.\d+)?)/i);
+        if (whenMatch)
+            result.when = `v${whenMatch[1]}`;
+        // HOW: Look for install/run commands
+        const howMatch = content.match(/(?:npm install|cargo|pip install|brew install)\s+[^\n]+/i);
+        if (howMatch)
+            result.how = howMatch[0].trim();
+        return result;
+    }
+    async handleFafHumanAdd(args) {
+        try {
+            const { field, value } = args;
+            if (!field || !value) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🧡 FAF Human Set:\n\n❌ Both field and value are required\n💡 Example: field="who", value="Development team"`
+                        }],
+                    isError: true
+                };
+            }
+            const validFields = ['who', 'what', 'why', 'where', 'when', 'how'];
+            if (!validFields.includes(field)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🧡 FAF Human Set:\n\n❌ Invalid field: ${field}\n💡 Valid fields: ${validFields.join(', ')}`
+                        }],
+                    isError: true
+                };
+            }
+            const cwd = this.getProjectPath(args?.path);
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (!fafResult) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🧡 FAF Human Add:\n\n❌ No project.faf found in ${cwd}\n💡 Run faf_init first`
+                        }],
+                    isError: true
+                };
+            }
+            const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
+            const yaml = await import('yaml');
+            const fafData = yaml.parse(fafContent) || {};
+            if (!fafData.human_context) {
+                fafData.human_context = {};
+            }
+            fafData.human_context[field] = value;
+            fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🧡 FAF Human Set:\n\n✅ Set ${field.toUpperCase()} = "${value}"\n📁 Updated: ${fafResult.filename}`
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `🧡 FAF Human Set:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafCheck(args) {
+        try {
+            const cwd = this.getProjectPath(args?.path);
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (!fafResult) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🔍 FAF Check:\n\n❌ No project.faf found in ${cwd}\n💡 Run faf_init first`
+                        }],
+                    isError: true
+                };
+            }
+            const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
+            const yaml = await import('yaml');
+            const fafData = yaml.parse(fafContent) || {};
+            const humanContext = fafData.human_context || {};
+            const protectedFields = fafData._protected_fields || [];
+            const fields = ['who', 'what', 'why', 'where', 'when', 'how'];
+            // Handle --unlock
+            if (args?.unlock) {
+                fafData._protected_fields = [];
+                fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🔓 FAF Check:\n\n✅ All fields unlocked\n📁 Updated: ${fafResult.filename}`
+                        }]
+                };
+            }
+            // Assess quality
+            const assessField = (value) => {
+                if (!value || value.trim() === '')
+                    return 'empty';
+                if (value.length < 10)
+                    return 'generic';
+                if (value.length > 20)
+                    return 'good';
+                return 'generic';
+            };
+            const qualities = {};
+            for (const field of fields) {
+                qualities[field] = assessField(humanContext[field]);
+            }
+            // Handle --protect
+            if (args?.protect) {
+                const toProtect = fields.filter(f => qualities[f] === 'good' || qualities[f] === 'excellent');
+                if (toProtect.length === 0) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `🔒 FAF Check:\n\n⚠️ No fields qualify for protection (need good or excellent quality)`
+                            }]
+                    };
+                }
+                fafData._protected_fields = [...new Set([...protectedFields, ...toProtect])];
+                fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🔒 FAF Check:\n\n✅ Protected ${toProtect.length} field(s): ${toProtect.join(', ')}\n📁 Updated: ${fafResult.filename}`
+                        }]
+                };
+            }
+            // Default: show quality report
+            const icons = {
+                empty: '⬜', generic: '🟡', good: '🟢', excellent: '💎'
+            };
+            let output = `🔍 FAF Human Context Quality\n\n`;
+            for (const field of fields) {
+                const q = qualities[field];
+                const locked = protectedFields.includes(field) ? '🔒' : '  ';
+                const value = humanContext[field] || '(empty)';
+                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 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`;
+            }
+            if (emptyCount > 0) {
+                output += `\n💡 Use faf_readme or faf_human_add to fill empty slots`;
+            }
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `🔍 FAF Check:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafContext(args) {
+        try {
+            if (args?.path) {
+                // Set the new context
+                const newPath = this.getProjectPath(args.path);
+                const fafResult = await (0, faf_file_finder_js_1.findFafFile)(newPath);
+                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`
+                        }]
+                };
+            }
+            else {
+                // Show current context
+                const currentPath = this.engineAdapter.getWorkingDirectory();
+                const fafResult = await (0, faf_file_finder_js_1.findFafFile)(currentPath);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `📂 FAF Current Context:\n\n📁 Active project: ${currentPath}\n${fafResult ? `✅ project.faf: ${fafResult.filename}` : '⚠️ No project.faf found'}\n\n💡 Use path parameter to change context`
+                        }]
+                };
+            }
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `📂 FAF Context:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    /**
+     * faf_go - Guided interview to Gold Code
+     *
+     * Two-phase operation:
+     * 1. Without answers: Returns questions for missing fields
+     * 2. With answers: Applies answers to .faf file and returns new score
+     */
+    async handleFafGo(args) {
+        const yaml = await import('yaml');
+        const cwd = this.getProjectPath(args?.path);
+        try {
+            // Find .faf file
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (!fafResult) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                needsInit: true,
+                                context: 'faf_go',
+                                message: 'No project.faf found. Run faf_init first to create project DNA.',
+                                suggestion: 'Use faf_init to create project.faf, then use faf_go to reach Gold Code.'
+                            }, null, 2)
+                        }]
+                };
+            }
+            const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
+            const fafData = yaml.parse(fafContent) || {};
+            // Question registry - maps field paths to questions
+            const QUESTION_REGISTRY = {
+                'project.goal': {
+                    question: 'What does this project do? (one sentence)',
+                    header: 'Goal',
+                    type: 'text',
+                    required: true
+                },
+                'project.name': {
+                    question: 'What is the name of this project?',
+                    header: 'Name',
+                    type: 'text',
+                    required: true
+                },
+                'project.main_language': {
+                    question: 'What is the primary programming language?',
+                    header: 'Language',
+                    type: 'select',
+                    required: true,
+                    options: [
+                        { label: 'TypeScript', value: 'TypeScript', description: 'JavaScript with types' },
+                        { label: 'JavaScript', value: 'JavaScript', description: 'Vanilla JS or Node.js' },
+                        { label: 'Python', value: 'Python', description: 'Python 3.x' },
+                        { label: 'Rust', value: 'Rust', description: 'Systems programming' },
+                        { label: 'Go', value: 'Go', description: 'Golang' },
+                        { label: 'Other', value: 'Other', description: 'Specify manually' }
+                    ]
+                },
+                'human_context.why': {
+                    question: 'Why does this project exist? (motivation)',
+                    header: 'Why',
+                    type: 'text',
+                    required: true
+                },
+                'human_context.who': {
+                    question: 'Who uses this project? (target audience)',
+                    header: 'Who',
+                    type: 'text',
+                    required: false
+                },
+                'human_context.what': {
+                    question: 'What problem does this solve?',
+                    header: 'What',
+                    type: 'text',
+                    required: false
+                },
+                'human_context.where': {
+                    question: 'Where does this run? (environment)',
+                    header: 'Where',
+                    type: 'text',
+                    required: false
+                },
+                'human_context.when': {
+                    question: 'When was this started or what phase is it in?',
+                    header: 'When',
+                    type: 'text',
+                    required: false
+                },
+                'human_context.how': {
+                    question: 'How should AI assist with this project?',
+                    header: 'How',
+                    type: 'text',
+                    required: false
+                },
+                'stack.frontend': {
+                    question: 'What frontend framework do you use?',
+                    header: 'Frontend',
+                    type: 'select',
+                    required: false,
+                    options: [
+                        { label: 'React', value: 'React', description: 'React.js' },
+                        { label: 'Vue', value: 'Vue', description: 'Vue.js' },
+                        { label: 'Svelte', value: 'Svelte', description: 'Svelte/SvelteKit' },
+                        { label: 'Next.js', value: 'Next.js', description: 'React framework' },
+                        { label: 'None', value: 'None', description: 'No frontend' },
+                        { label: 'Other', value: 'Other', description: 'Specify manually' }
+                    ]
+                },
+                'stack.backend': {
+                    question: 'What backend framework do you use?',
+                    header: 'Backend',
+                    type: 'select',
+                    required: false,
+                    options: [
+                        { label: 'Express', value: 'Express', description: 'Node.js Express' },
+                        { label: 'Fastify', value: 'Fastify', description: 'Node.js Fastify' },
+                        { label: 'Django', value: 'Django', description: 'Python Django' },
+                        { label: 'FastAPI', value: 'FastAPI', description: 'Python FastAPI' },
+                        { label: 'None', value: 'None', description: 'No backend' },
+                        { label: 'Other', value: 'Other', description: 'Specify manually' }
+                    ]
+                },
+                'stack.database': {
+                    question: 'What database do you use?',
+                    header: 'Database',
+                    type: 'select',
+                    required: false,
+                    options: [
+                        { label: 'PostgreSQL', value: 'PostgreSQL', description: 'Relational database' },
+                        { label: 'MongoDB', value: 'MongoDB', description: 'Document database' },
+                        { label: 'SQLite', value: 'SQLite', description: 'File-based database' },
+                        { label: 'Supabase', value: 'Supabase', description: 'Postgres + auth' },
+                        { label: 'None', value: 'None', description: 'No database' },
+                        { label: 'Other', value: 'Other', description: 'Specify manually' }
+                    ]
+                },
+                'stack.hosting': {
+                    question: 'Where is this hosted/deployed?',
+                    header: 'Hosting',
+                    type: 'select',
+                    required: false,
+                    options: [
+                        { label: 'Vercel', value: 'Vercel', description: 'Frontend/serverless' },
+                        { label: 'AWS', value: 'AWS', description: 'Amazon Web Services' },
+                        { label: 'Cloudflare', value: 'Cloudflare', description: 'Workers/Pages' },
+                        { label: 'Railway', value: 'Railway', description: 'App hosting' },
+                        { label: 'Local only', value: 'Local', description: 'Not deployed' },
+                        { label: 'Other', value: 'Other', description: 'Specify manually' }
+                    ]
+                }
+            };
+            // Priority order for questions
+            const priorityOrder = [
+                'project.goal',
+                'human_context.why',
+                'human_context.who',
+                'human_context.what',
+                'project.name',
+                'project.main_language',
+                'stack.database',
+                'stack.hosting',
+                'stack.frontend',
+                'stack.backend',
+                'human_context.where',
+                'human_context.when',
+                'human_context.how'
+            ];
+            // Helper to get nested value
+            const getNestedValue = (obj, path) => {
+                const parts = path.split('.');
+                let value = obj;
+                for (const part of parts) {
+                    if (value && typeof value === 'object' && part in value) {
+                        value = value[part];
+                    }
+                    else {
+                        return undefined;
+                    }
+                }
+                return value;
+            };
+            // Helper to set nested value
+            const setNestedValue = (obj, path, value) => {
+                const parts = path.split('.');
+                let current = obj;
+                for (let i = 0; i < parts.length - 1; i++) {
+                    const part = parts[i];
+                    if (!(part in current)) {
+                        current[part] = {};
+                    }
+                    current = current[part];
+                }
+                current[parts[parts.length - 1]] = value;
+            };
+            // Check if value is empty/placeholder
+            const isEmpty = (value) => {
+                return value === undefined ||
+                    value === null ||
+                    value === '' ||
+                    value === 'Unknown' ||
+                    value === 'TBD' ||
+                    value === 'None' ||
+                    (typeof value === 'string' && value.toLowerCase().includes('placeholder'));
+            };
+            // PHASE 2: Apply answers if provided
+            if (args?.answers && typeof args.answers === 'object') {
+                const answers = args.answers;
+                let appliedCount = 0;
+                for (const [fieldPath, answer] of Object.entries(answers)) {
+                    if (answer && answer.trim()) {
+                        setNestedValue(fafData, fieldPath, answer.trim());
+                        appliedCount++;
+                    }
+                }
+                // Write updated file
+                fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
+                // Calculate new score (simple count-based)
+                const totalFields = Object.keys(QUESTION_REGISTRY).length;
+                const filledFields = Object.keys(QUESTION_REGISTRY).filter(field => !isEmpty(getNestedValue(fafData, field))).length;
+                const newScore = Math.round((filledFields / totalFields) * 100);
+                const celebration = newScore >= 100 ? '🏆 GOLD CODE ACHIEVED!' :
+                    newScore >= 85 ? '🥇 Championship grade!' :
+                        newScore >= 70 ? '🥈 Great progress!' : '📈 Keep going!';
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🎯 FAF Go - Answers Applied!\n\n✅ Updated ${appliedCount} field(s) in ${fafResult.filename}\n📊 New Score: ${newScore}%\n${celebration}\n\n${newScore < 100 ? '💡 Run faf_go again to continue to Gold Code!' : '✨ Your AI now has complete context!'}`
+                        }]
+                };
+            }
+            // PHASE 1: Analyze and return questions
+            const missingFields = [];
+            for (const fieldPath of Object.keys(QUESTION_REGISTRY)) {
+                const value = getNestedValue(fafData, fieldPath);
+                if (isEmpty(value)) {
+                    missingFields.push(fieldPath);
+                }
+            }
+            // Calculate current score
+            const totalFields = Object.keys(QUESTION_REGISTRY).length;
+            const filledFields = totalFields - missingFields.length;
+            const currentScore = Math.round((filledFields / totalFields) * 100);
+            // Already at 100%?
+            if (currentScore >= 100) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                complete: true,
+                                score: 100,
+                                message: '🏆 GOLD CODE ACHIEVED! Your project has 100% AI-Readiness.',
+                                context: 'faf_go'
+                            }, null, 2)
+                        }]
+                };
+            }
+            // No missing fields but score < 100? Content quality issue
+            if (missingFields.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                score: currentScore,
+                                message: `Score is ${currentScore}%. All fields filled but content may need enhancement.`,
+                                suggestion: 'Use faf_enhance to improve content quality.',
+                                context: 'faf_go'
+                            }, null, 2)
+                        }]
+                };
+            }
+            // Sort by priority
+            const prioritizedFields = missingFields.sort((a, b) => {
+                const aIdx = priorityOrder.indexOf(a);
+                const bIdx = priorityOrder.indexOf(b);
+                if (aIdx === -1)
+                    return 1;
+                if (bIdx === -1)
+                    return -1;
+                return aIdx - bIdx;
+            });
+            // Build questions
+            const questions = prioritizedFields.map(field => {
+                const reg = QUESTION_REGISTRY[field];
+                return {
+                    field,
+                    question: reg.question,
+                    header: reg.header,
+                    type: reg.type,
+                    required: reg.required,
+                    options: reg.options
+                };
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            needsInput: true,
+                            context: 'faf_go - guided path to Gold Code',
+                            currentScore,
+                            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.'
+                        }, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `🎯 FAF Go:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    /**
+     * faf_auto - ONE COMMAND TO RULE THEM ALL
+     * Zero to Championship in one command
+     * Runs: init + formats + sync + bi-sync + score
+     */
+    async handleFafAuto(args) {
+        const startTime = Date.now();
+        const cwd = this.getProjectPath(args?.path);
+        const yaml = await import('yaml');
+        const path = await import('path');
+        try {
+            const steps = [];
+            let currentScore = 0;
+            // Step 1: Check/Create .faf file
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            let fafPath;
+            if (!fafResult) {
+                // Create .faf file
+                const projectName = path.basename(cwd);
+                fafPath = path.join(cwd, 'project.faf');
+                const initFafContent = `# FAF - Foundational AI Context
+project: ${projectName}
+type: auto-detected
+context: I⚡🍊
+generated: ${new Date().toISOString()}
+version: ${version_1.VERSION}
+
+# Quick Context
+working_directory: ${cwd}
+initialized_by: claude-faf-mcp-auto
+vitamin_context: true
+faffless: true
+`;
+                fs.writeFileSync(fafPath, initFafContent);
+                steps.push('✅ Created project.faf');
+            }
+            else {
+                fafPath = fafResult.path;
+                steps.push(`✅ Found ${fafResult.filename}`);
+            }
+            // Get initial score
+            const fafContent = fs.readFileSync(fafPath, 'utf-8');
+            const fafData = yaml.parse(fafContent) || {};
+            currentScore = this.calculateSimpleScore(fafData);
+            // Step 2: Run TURBO-CAT format discovery
+            const formatsResult = await this.discoverFormatsInternal(cwd);
+            if (formatsResult.discoveredFormats.length > 0) {
+                // Apply slot fills to .faf
+                if (!fafData.stack)
+                    fafData.stack = {};
+                for (const [key, value] of Object.entries(formatsResult.slotFillRecommendations)) {
+                    if (!fafData.stack[key] || fafData.stack[key] === 'None') {
+                        fafData.stack[key] = value;
+                    }
+                }
+                if (formatsResult.stackSignature) {
+                    fafData.stack_signature = formatsResult.stackSignature;
+                }
+                fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
+                steps.push(`✅ TURBO-CAT discovered ${formatsResult.discoveredFormats.length} formats`);
+            }
+            else {
+                steps.push('⚠️ No additional formats detected');
+            }
+            // Step 3: Extract human context from README
+            const readmePath = path.join(cwd, 'README.md');
+            if (fs.existsSync(readmePath)) {
+                const readmeContent = fs.readFileSync(readmePath, 'utf-8');
+                const extracted = this.extractSixWsFromReadme(readmeContent);
+                if (!fafData.human_context)
+                    fafData.human_context = {};
+                let extractedCount = 0;
+                for (const [field, value] of Object.entries(extracted)) {
+                    if (value && !fafData.human_context[field]) {
+                        fafData.human_context[field] = value;
+                        extractedCount++;
+                    }
+                }
+                if (extractedCount > 0) {
+                    fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
+                    steps.push(`✅ Extracted ${extractedCount} human context fields from README`);
+                }
+            }
+            // Step 4: Create/Update CLAUDE.md (bi-sync)
+            const claudePath = path.join(cwd, 'CLAUDE.md');
+            if (!fs.existsSync(claudePath)) {
+                const claudeContent = `# 🏎️ CLAUDE.md - AI Telemetry Link
+
+## Project: ${fafData.project || path.basename(cwd)}
+**Championship-Grade Project DNA Foundation**
+
+### 🎯 Project Mission
+${fafData.human_context?.why || fafData.project?.goal || 'AI-ready project context'}
+
+### 🏗️ Architecture Overview
+${fafData.stack_signature || 'Auto-detected stack'}
+
+---
+
+**STATUS: BI-SYNC ACTIVE 🔗**
+*Last Sync: ${new Date().toISOString()}*
+*Sync Engine: FAF Auto*
+`;
+                fs.writeFileSync(claudePath, claudeContent);
+                steps.push('✅ Created CLAUDE.md');
+            }
+            else {
+                steps.push('✅ CLAUDE.md already exists');
+            }
+            // Step 5: Calculate final score
+            const updatedContent = fs.readFileSync(fafPath, 'utf-8');
+            const updatedData = yaml.parse(updatedContent) || {};
+            const newScore = this.calculateSimpleScore(updatedData);
+            const scoreDelta = newScore - currentScore;
+            // Calculate elapsed time
+            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`;
+            output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
+            output += steps.join('\n') + '\n\n';
+            output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+            output += `⏱️ Completed in ${elapsed}s\n`;
+            output += `📊 Before: ${currentScore}% | After: ${newScore}% ${deltaDisplay}\n`;
+            output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
+            if (newScore >= 99) {
+                output += `🏆 CHAMPIONSHIP ACHIEVED! Your AI has complete context.\n`;
+            }
+            else if (newScore >= 85) {
+                output += `🥇 Elite level! ${100 - newScore}% to perfection.\n`;
+            }
+            else if (newScore >= 70) {
+                output += `🥈 Great progress! Run faf_go to reach championship.\n`;
+            }
+            else {
+                output += `🚀 Good start! Run faf_go for guided improvement.\n`;
+            }
+            output += `\n💡 Next: faf_score --details | faf_go | faf_enhance`;
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                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%)
+     */
+    async handleFafDna(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const path = await import('path');
+        try {
+            const dnaPath = path.join(cwd, '.faf-dna');
+            // Check if DNA file exists
+            if (!fs.existsSync(dnaPath)) {
+                // No DNA yet - check if .faf exists
+                const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+                if (!fafResult) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `🧬 FAF DNA Journey\n\n❌ No FAF DNA found\n💡 Run faf_auto to start your journey!`
+                            }]
+                    };
+                }
+                // .faf exists but no DNA - create initial DNA
+                const yaml = await import('yaml');
+                const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
+                const fafData = yaml.parse(fafContent) || {};
+                const currentScore = this.calculateSimpleScore(fafData);
+                const dna = {
+                    birthCertificate: {
+                        born: new Date().toISOString(),
+                        birthDNA: currentScore,
+                        birthDNASource: 'auto',
+                        authenticated: false,
+                        certificate: `FAF-${new Date().getFullYear()}-${path.basename(cwd).toUpperCase().slice(0, 8)}-${Math.random().toString(36).slice(2, 6).toUpperCase()}`
+                    },
+                    current: {
+                        score: currentScore,
+                        version: 'v1.0.0',
+                        lastSync: new Date().toISOString()
+                    },
+                    milestones: [
+                        { type: 'birth', score: currentScore, date: new Date().toISOString(), version: 'v1.0.0' }
+                    ],
+                    format: 'faf-dna-v1'
+                };
+                fs.writeFileSync(dnaPath, JSON.stringify(dna, null, 2));
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🧬 FAF DNA Journey\n\n🐣 Birth Certificate Created!\n\n📊 Birth DNA: ${currentScore}%\n📅 Born: ${new Date().toISOString().split('T')[0]}\n🎫 Certificate: ${dna.birthCertificate.certificate}\n\n💡 Your journey begins here! Run faf_auto or faf_go to grow.`
+                        }]
+                };
+            }
+            // Load existing DNA
+            const dnaContent = fs.readFileSync(dnaPath, 'utf-8');
+            const dna = JSON.parse(dnaContent);
+            // Build journey string
+            const birthScore = dna.birthCertificate?.birthDNA || 0;
+            const currentScore = dna.current?.score || 0;
+            const milestones = dna.milestones || [];
+            // Find key milestones
+            const _birth = milestones.find((m) => m.type === 'birth');
+            const peak = milestones.find((m) => m.type === 'peak');
+            const championship = milestones.find((m) => m.type === 'championship');
+            const elite = milestones.find((m) => m.type === 'elite');
+            // Build compact journey
+            let journey = `${birthScore}%`;
+            if (championship && championship.score !== birthScore) {
+                journey += ` → ${championship.score}%`;
+            }
+            if (elite && (!championship || elite.score !== championship.score)) {
+                journey += ` → ${elite.score}%`;
+            }
+            if (peak) {
+                journey += ` → ${peak.score}%`;
+                if (currentScore < peak.score) {
+                    journey += ` ← ${currentScore}%`;
+                }
+            }
+            else if (currentScore !== birthScore) {
+                journey += ` → ${currentScore}%`;
+            }
+            // Calculate stats
+            const birthDate = new Date(dna.birthCertificate?.born || Date.now());
+            const daysActive = Math.floor((Date.now() - birthDate.getTime()) / (1000 * 60 * 60 * 24));
+            const totalGrowth = currentScore - birthScore;
+            let output = `🧬 YOUR FAF DNA\n\n`;
+            output += `   ${journey}\n\n`;
+            output += `═══════════════════════════════════════════════════\n\n`;
+            output += `📊 QUICK STATS\n`;
+            output += `   Born: ${birthDate.toISOString().split('T')[0]}\n`;
+            output += `   Days Active: ${daysActive}\n`;
+            output += `   Total Growth: +${totalGrowth}%\n`;
+            if (dna.birthCertificate?.authenticated) {
+                output += `   ✅ Authenticated: ${dna.birthCertificate.certificate}\n`;
+            }
+            else {
+                output += `   ⚠️ Not authenticated\n`;
+            }
+            output += `\n🧬 MILESTONES\n`;
+            const milestoneIcons = {
+                birth: '🐣', first_save: '💾', doubled: '2️⃣',
+                championship: '🏆', elite: '⭐', peak: '🏔️', perfect: '💎'
+            };
+            for (const m of milestones) {
+                const icon = milestoneIcons[m.type] || '📍';
+                const isCurrent = m.score === currentScore;
+                output += `   ${icon} ${m.type}: ${m.score}%${isCurrent ? ' ← You are here!' : ''}\n`;
+            }
+            output += `\n═══════════════════════════════════════════════════\n`;
+            // Motivational message
+            if (totalGrowth > 70) {
+                output += `🚀 Incredible journey! You've transformed your AI context!\n`;
+            }
+            else if (totalGrowth > 50) {
+                output += `📈 Great progress! Your context is evolving beautifully.\n`;
+            }
+            else if (totalGrowth > 0) {
+                output += `🌱 Your journey has begun. Every step counts!\n`;
+            }
+            else {
+                output += `🐣 Just born! Your growth story starts now.\n`;
+            }
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `🧬 FAF DNA:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    /**
+     * faf_formats - TURBO-CAT format discovery
+     * Discovers all formats in the project
+     */
+    async handleFafFormats(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const startTime = Date.now();
+        try {
+            const analysis = await this.discoverFormatsInternal(cwd);
+            const elapsed = Date.now() - startTime;
+            if (args?.json) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(analysis, null, 2)
+                        }]
+                };
+            }
+            // Format human-readable output
+            let output = `😽 TURBO-CAT™ Format Discovery v2.0.0\n`;
+            output += `═══════════════════════════════════════════════════\n\n`;
+            output += `✅ Found ${analysis.discoveredFormats.length} formats in ${elapsed}ms!\n\n`;
+            output += `📋 Discovered Formats (A-Z):\n`;
+            const sorted = [...analysis.discoveredFormats].sort((a, b) => a.fileName.localeCompare(b.fileName));
+            for (const format of sorted) {
+                output += `  ✅ ${format.fileName}\n`;
+            }
+            output += `\n💡 Stack Signature: ${analysis.stackSignature}\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)) {
+                    output += `  • ${key}: ${value}\n`;
+                }
+                output += `\n`;
+            }
+            output += `───────────────────────────────────────────────────\n`;
+            output += `😽 TURBO-CAT™: "I detected ${analysis.discoveredFormats.length} formats and made your stack PURRR!"\n`;
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `😽 TURBO-CAT:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    /**
+     * Internal helper: Discover formats in a directory (TURBO-CAT logic)
+     */
+    async discoverFormatsInternal(projectDir) {
+        const path = await import('path');
+        // Known format files and their categories
+        const KNOWN_FORMATS = {
+            'package.json': { category: 'package-manager', priority: 35 },
+            'tsconfig.json': { category: 'typescript-config', priority: 30 },
+            'Cargo.toml': { category: 'package-manager', priority: 35 },
+            'pyproject.toml': { category: 'package-manager', priority: 35 },
+            'requirements.txt': { category: 'package-manager', priority: 25 },
+            'go.mod': { category: 'package-manager', priority: 35 },
+            'pom.xml': { category: 'package-manager', priority: 35 },
+            'README.md': { category: 'documentation', priority: 20 },
+            'CLAUDE.md': { category: 'ai-context', priority: 40 },
+            'project.faf': { category: 'faf-context', priority: 45 },
+            '.faf': { category: 'faf-context', priority: 45 },
+            'Dockerfile': { category: 'docker', priority: 25 },
+            'docker-compose.yml': { category: 'docker', priority: 25 },
+            'vercel.json': { category: 'deployment', priority: 20 },
+            'netlify.toml': { category: 'deployment', priority: 20 },
+            '.eslintrc.json': { category: 'linting', priority: 15 },
+            '.prettierrc': { category: 'linting', priority: 15 },
+            'jest.config.js': { category: 'testing', priority: 20 },
+            'vitest.config.ts': { category: 'testing', priority: 20 },
+            'svelte.config.js': { category: 'framework', priority: 30 },
+            'next.config.js': { category: 'framework', priority: 30 },
+            'vite.config.ts': { category: 'build', priority: 25 },
+            'webpack.config.js': { category: 'build', priority: 25 },
+            '.github': { category: 'ci-cd', priority: 20 },
+            'manifest.json': { category: 'chrome-extension', priority: 35 }
+        };
+        const discoveredFormats = [];
+        let totalIntelligenceScore = 0;
+        const slotFillRecommendations = {};
+        const extractedContext = {};
+        // Scan directory
+        try {
+            const files = fs.readdirSync(projectDir);
+            for (const file of files) {
+                if (KNOWN_FORMATS[file]) {
+                    const format = KNOWN_FORMATS[file];
+                    discoveredFormats.push({
+                        fileName: file,
+                        category: format.category,
+                        priority: format.priority
+                    });
+                    totalIntelligenceScore += format.priority;
+                }
+            }
+            // Extract intelligence from package.json
+            const pkgPath = path.join(projectDir, 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                const pkgContent = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                const allDeps = { ...pkgContent.dependencies, ...pkgContent.devDependencies };
+                extractedContext.projectName = pkgContent.name;
+                extractedContext.projectDescription = pkgContent.description;
+                // Detect frameworks and fill slots
+                if (allDeps['typescript'] || allDeps['@types/node']) {
+                    slotFillRecommendations['mainLanguage'] = 'TypeScript';
+                }
+                if (allDeps['react'] || allDeps['next']) {
+                    slotFillRecommendations['frontend'] = allDeps['next'] ? 'Next.js' : 'React';
+                }
+                if (allDeps['vue'] || allDeps['nuxt']) {
+                    slotFillRecommendations['frontend'] = allDeps['nuxt'] ? 'Nuxt' : 'Vue';
+                }
+                if (allDeps['svelte'] || allDeps['@sveltejs/kit']) {
+                    slotFillRecommendations['frontend'] = allDeps['@sveltejs/kit'] ? 'SvelteKit' : 'Svelte';
+                }
+                if (allDeps['express']) {
+                    slotFillRecommendations['backend'] = 'Express';
+                }
+                if (allDeps['fastify']) {
+                    slotFillRecommendations['backend'] = 'Fastify';
+                }
+                if (allDeps['vite']) {
+                    slotFillRecommendations['build'] = 'Vite';
+                }
+                if (allDeps['jest'] || allDeps['vitest']) {
+                    slotFillRecommendations['testing'] = allDeps['vitest'] ? 'Vitest' : 'Jest';
+                }
+            }
+            // Check for deployment indicators
+            if (fs.existsSync(path.join(projectDir, 'vercel.json'))) {
+                slotFillRecommendations['hosting'] = 'Vercel';
+            }
+            else if (fs.existsSync(path.join(projectDir, 'netlify.toml'))) {
+                slotFillRecommendations['hosting'] = 'Netlify';
+            }
+        }
+        catch (error) {
+            // Ignore errors, return empty results
+        }
+        // Generate stack signature
+        const parts = [];
+        if (slotFillRecommendations['mainLanguage'])
+            parts.push(slotFillRecommendations['mainLanguage'].toLowerCase());
+        if (slotFillRecommendations['frontend'])
+            parts.push(slotFillRecommendations['frontend'].toLowerCase());
+        const stackSignature = parts.length > 0 ? parts.join('-') : 'unknown-stack';
+        return {
+            discoveredFormats,
+            totalIntelligenceScore,
+            stackSignature,
+            slotFillRecommendations,
+            extractedContext
+        };
+    }
+    /**
+     * Internal helper: Calculate simple score from .faf data
+     */
+    calculateSimpleScore(fafData) {
+        let score = 0;
+        const maxScore = 100;
+        // Project section (30 points)
+        if (fafData.project)
+            score += 15;
+        if (fafData.project?.goal || fafData.description)
+            score += 15;
+        // Human context (30 points)
+        const humanContext = fafData.human_context || {};
+        const wFields = ['who', 'what', 'why', 'where', 'when', 'how'];
+        const filledW = wFields.filter(f => humanContext[f] && humanContext[f] !== 'null').length;
+        score += Math.round((filledW / wFields.length) * 30);
+        // Stack section (20 points)
+        const stack = fafData.stack || {};
+        const stackFields = ['frontend', 'backend', 'database', 'hosting', 'build'];
+        const filledStack = stackFields.filter(f => stack[f] && stack[f] !== 'None').length;
+        score += Math.round((filledStack / stackFields.length) * 20);
+        // Files exist bonus (20 points)
+        if (fafData.initialized_by || fafData.generated)
+            score += 10;
+        if (fafData.stack_signature)
+            score += 10;
+        return Math.min(score, maxScore);
+    }
+    /**
+     * faf_quick - Lightning-fast .faf creation
+     * One-liner format: "name, description, language, framework, hosting"
+     */
+    async handleFafQuick(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const path = await import('path');
+        const yaml = await import('yaml');
+        const startTime = Date.now();
+        try {
+            const input = args?.input;
+            if (!input || typeof input !== 'string') {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `⚡ FAF Quick
+
+Usage: Provide a comma-separated string:
+  "project-name, description, language, framework, hosting"
+
+Examples:
+  "my-app, e-commerce platform, typescript, react, vercel"
+  "api-service, REST API for mobile app, python, fastapi, aws"
+  "cli-tool, developer productivity tool, go"
+
+Minimum: name and description. Rest is auto-detected!`
+                        }]
+                };
+            }
+            // Parse the quick input
+            const parts = input.split(',').map((s) => s.trim());
+            if (parts.length < 2) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `⚡ FAF Quick: Need at least: project-name, description
+
+Got: "${input}"
+
+Example: "my-app, e-commerce platform"`
+                        }],
+                    isError: true
+                };
+            }
+            const projectName = parts[0] || 'my-project';
+            const projectGoal = parts[1] || 'Build amazing software';
+            const mainLanguage = parts[2] || 'TypeScript';
+            const framework = parts[3] || 'none';
+            const hosting = parts[4] || 'cloud';
+            // Check if .faf exists
+            const fafPath = path.join(cwd, 'project.faf');
+            if (fs.existsSync(fafPath) && !args?.force) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `⚡ FAF Quick
+
+⚠️ project.faf already exists at: ${fafPath}
+
+Use force: true to overwrite, or use faf_enhance to modify.`
+                        }]
+                };
+            }
+            // Detect project type from inputs
+            const projectType = this.detectProjectTypeFromQuick(projectGoal, framework, mainLanguage);
+            // Build .faf content
+            const fafData = {
+                project: {
+                    name: projectName,
+                    goal: projectGoal,
+                    main_language: mainLanguage
+                },
+                type: projectType,
+                generated: new Date().toISOString(),
+                version: version_1.VERSION,
+                initialized_by: 'claude-faf-mcp-quick'
+            };
+            if (framework && framework !== 'none') {
+                fafData.stack = { frontend: framework };
+            }
+            if (hosting && hosting !== 'cloud') {
+                if (!fafData.stack)
+                    fafData.stack = {};
+                fafData.stack.hosting = hosting;
+            }
+            // Write the file
+            fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
+            const elapsed = Date.now() - startTime;
+            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`;
+            output += `📍 Type: ${projectType}\n\n`;
+            output += `✅ Created: ${fafPath}\n\n`;
+            output += `Next steps:\n`;
+            output += `  • faf_score - Check AI-readiness\n`;
+            output += `  • faf_enhance - Improve context\n`;
+            output += `  • faf_go - Guided interview to 100%`;
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `⚡ FAF Quick:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    /**
+     * Helper: Detect project type from quick input
+     */
+    detectProjectTypeFromQuick(goal, framework, language) {
+        const fw = framework?.toLowerCase() || '';
+        const lang = language?.toLowerCase() || '';
+        const g = goal?.toLowerCase() || '';
+        // Framework-based detection
+        if (fw.includes('react') || fw.includes('next'))
+            return 'react';
+        if (fw.includes('vue') || fw.includes('nuxt'))
+            return 'vue';
+        if (fw.includes('svelte') || fw.includes('kit'))
+            return 'svelte';
+        if (fw.includes('angular'))
+            return 'angular';
+        if (fw.includes('fastapi'))
+            return 'python-fastapi';
+        if (fw.includes('django'))
+            return 'python-django';
+        if (fw.includes('flask'))
+            return 'python-flask';
+        if (fw.includes('express'))
+            return 'node-api';
+        // Goal-based detection
+        if (g.includes('chrome extension') || g.includes('browser extension'))
+            return 'chrome-extension';
+        if (g.includes('api') || g.includes('backend'))
+            return 'node-api';
+        if (g.includes('cli') || g.includes('command'))
+            return 'cli-tool';
+        if (g.includes('library') || g.includes('package'))
+            return 'library';
+        if (g.includes('mcp') || g.includes('model context'))
+            return 'mcp-server';
+        // Language-based fallback
+        if (lang.includes('python'))
+            return 'python';
+        if (lang.includes('go'))
+            return 'golang';
+        if (lang.includes('rust'))
+            return 'rust';
+        if (lang.includes('typescript'))
+            return 'typescript';
+        return 'general';
+    }
+    /**
+     * faf_doctor - Health check for .faf setup
+     * Diagnose and fix common issues
+     */
+    async handleFafDoctor(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const path = await import('path');
+        const yaml = await import('yaml');
+        try {
+            const results = [];
+            // Check 1: MCP Version
+            results.push({
+                status: 'ok',
+                message: `claude-faf-mcp version: ${version_1.VERSION}`
+            });
+            // Check 2: .faf file exists
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (!fafResult) {
+                results.push({
+                    status: 'error',
+                    message: 'No .faf file found',
+                    fix: 'Run: faf_init, faf_quick, or faf_auto to create one'
+                });
+            }
+            else {
+                results.push({
+                    status: 'ok',
+                    message: `Found .faf at: ${fafResult.path}`
+                });
+                // Check 3: .faf file validity
+                try {
+                    const content = fs.readFileSync(fafResult.path, 'utf-8');
+                    const fafData = yaml.parse(content);
+                    if (!fafData) {
+                        results.push({
+                            status: 'error',
+                            message: '.faf file is empty',
+                            fix: 'Run: faf_init with force option to regenerate'
+                        });
+                    }
+                    else {
+                        // Check for required fields
+                        const missingFields = [];
+                        if (!fafData.project?.name && !fafData.project)
+                            missingFields.push('project.name');
+                        if (!fafData.project?.goal)
+                            missingFields.push('project.goal');
+                        if (missingFields.length > 0) {
+                            results.push({
+                                status: 'warning',
+                                message: `Missing important fields: ${missingFields.join(', ')}`,
+                                fix: 'Run: faf_enhance or faf_go to add missing info'
+                            });
+                        }
+                        else {
+                            results.push({
+                                status: 'ok',
+                                message: '.faf structure is valid'
+                            });
+                        }
+                        // Check 4: Score
+                        const score = this.calculateSimpleScore(fafData);
+                        if (score < 30) {
+                            results.push({
+                                status: 'error',
+                                message: `Score too low: ${score}%`,
+                                fix: 'Run: faf_enhance or faf_go to improve context'
+                            });
+                        }
+                        else if (score < 70) {
+                            results.push({
+                                status: 'warning',
+                                message: `Score could be better: ${score}%`,
+                                fix: 'Target 70%+ for championship AI context'
+                            });
+                        }
+                        else {
+                            results.push({
+                                status: 'ok',
+                                message: `Great score: ${score}%`
+                            });
+                        }
+                    }
+                }
+                catch {
+                    results.push({
+                        status: 'error',
+                        message: '.faf file is corrupted or invalid YAML',
+                        fix: 'Run: faf_init with force option to regenerate'
+                    });
+                }
+            }
+            // Check 5: CLAUDE.md exists
+            const claudePath = path.join(cwd, 'CLAUDE.md');
+            if (!fs.existsSync(claudePath)) {
+                results.push({
+                    status: 'warning',
+                    message: 'No CLAUDE.md file',
+                    fix: 'Run: faf_auto or faf_bi_sync to create bi-directional sync'
+                });
+            }
+            else {
+                results.push({
+                    status: 'ok',
+                    message: 'CLAUDE.md found (bi-sync ready)'
+                });
+            }
+            // Check 6: Project detection
+            const packageJsonPath = path.join(cwd, 'package.json');
+            const requirementsPath = path.join(cwd, 'requirements.txt');
+            const goModPath = path.join(cwd, 'go.mod');
+            const cargoPath = path.join(cwd, 'Cargo.toml');
+            if (fs.existsSync(packageJsonPath)) {
+                results.push({
+                    status: 'ok',
+                    message: 'Node.js/JavaScript project detected'
+                });
+            }
+            else if (fs.existsSync(requirementsPath)) {
+                results.push({
+                    status: 'ok',
+                    message: 'Python project detected'
+                });
+            }
+            else if (fs.existsSync(goModPath)) {
+                results.push({
+                    status: 'ok',
+                    message: 'Go project detected'
+                });
+            }
+            else if (fs.existsSync(cargoPath)) {
+                results.push({
+                    status: 'ok',
+                    message: 'Rust project detected'
+                });
+            }
+            else {
+                results.push({
+                    status: 'warning',
+                    message: 'No standard project files detected',
+                    fix: 'FAF works best with package.json, requirements.txt, go.mod, or Cargo.toml'
+                });
+            }
+            // Build output
+            let output = `🏥 FAF Doctor - Health Check\n`;
+            output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
+            let hasErrors = false;
+            let hasWarnings = false;
+            for (const result of results) {
+                const icon = result.status === 'ok' ? '✅' :
+                    result.status === 'warning' ? '⚠️' : '❌';
+                output += `${icon} ${result.message}\n`;
+                if (result.fix) {
+                    output += `   💡 ${result.fix}\n`;
+                }
+                if (result.status === 'error')
+                    hasErrors = true;
+                if (result.status === 'warning')
+                    hasWarnings = true;
+            }
+            output += `\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
+            if (!hasErrors && !hasWarnings) {
+                output += `🏆 Perfect health! Your FAF setup is championship-ready!`;
+            }
+            else if (!hasErrors) {
+                output += `🎯 Good health with minor improvements suggested.`;
+            }
+            else {
+                output += `⚠️ Issues detected. Follow the fixes above.`;
+            }
+            return { content: [{ type: 'text', text: output }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `🏥 FAF Doctor:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    // ============================================================================
+    // v4.5.0 INTEROP HANDLERS
+    // ============================================================================
+    async handleFafAgents(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const action = args?.action || 'sync';
+        try {
+            const result = await this.engineAdapter.callEngine('agents', [
+                cwd,
+                `--action=${action}`,
+                ...(args?.force ? ['--force'] : []),
+                ...(args?.merge ? ['--merge'] : []),
+            ]);
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: `AGENTS.md ${action}:\n\n❌ ${result.error}` }],
+                    isError: true
+                };
+            }
+            const data = result.data;
+            return {
+                content: [{ type: 'text', text: `AGENTS.md ${action}:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `AGENTS.md ${action}:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafCursor(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const action = args?.action || 'sync';
+        try {
+            const result = await this.engineAdapter.callEngine('cursor', [
+                cwd,
+                `--action=${action}`,
+                ...(args?.force ? ['--force'] : []),
+                ...(args?.merge ? ['--merge'] : []),
+            ]);
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: `.cursorrules ${action}:\n\n❌ ${result.error}` }],
+                    isError: true
+                };
+            }
+            const data = result.data;
+            return {
+                content: [{ type: 'text', text: `.cursorrules ${action}:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `.cursorrules ${action}:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafGemini(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const action = args?.action || 'sync';
+        try {
+            const result = await this.engineAdapter.callEngine('gemini', [
+                cwd,
+                `--action=${action}`,
+                ...(args?.force ? ['--force'] : []),
+                ...(args?.merge ? ['--merge'] : []),
+            ]);
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: `GEMINI.md ${action}:\n\n❌ ${result.error}` }],
+                    isError: true
+                };
+            }
+            const data = result.data;
+            return {
+                content: [{ type: 'text', text: `GEMINI.md ${action}:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `GEMINI.md ${action}:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafConductor(args) {
+        const cwd = this.getProjectPath(args?.path);
+        const action = args?.action || 'import';
+        try {
+            const result = await this.engineAdapter.callEngine('conductor', [
+                cwd,
+                `--action=${action}`,
+                ...(args?.force ? ['--force'] : []),
+                ...(args?.merge ? ['--merge'] : []),
+            ]);
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: `Conductor ${action}:\n\n❌ ${result.error}` }],
+                    isError: true
+                };
+            }
+            const data = result.data;
+            return {
+                content: [{ type: 'text', text: `Conductor ${action}:\n\n✅ ${data?.message || 'Done'}\n⏱️ ${result.duration}ms` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Conductor ${action}:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
+    async handleFafGit(args) {
+        const url = args?.url;
+        if (!url) {
+            return {
+                content: [{ type: 'text', text: 'faf_git: Missing required parameter "url"' }],
+                isError: true
+            };
+        }
+        const outputPath = args?.path ? this.getProjectPath(args.path) : undefined;
+        try {
+            const result = await this.engineAdapter.callEngine('git', [
+                url,
+                ...(outputPath ? [outputPath] : []),
+            ]);
+            if (!result.success) {
+                return {
+                    content: [{ type: 'text', text: `GitHub Context:\n\n❌ ${result.error}` }],
+                    isError: true
+                };
+            }
+            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)
+            if (!outputPath && data?.data?.fafContent) {
+                output += `\n\n--- Generated project.faf ---\n${data.data.fafContent}`;
+            }
+            return {
+                content: [{ type: 'text', text: output }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `GitHub Context:\n\n❌ Error: ${error.message}` }],
+                isError: true
+            };
+        }
+    }
 }
 exports.FafToolHandler = FafToolHandler;
 //# sourceMappingURL=tools.js.map