@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

package/dist/mcp/server.js

@@ -24,2138 +24,58 @@ export { TOOLKIT_NAME, TOOLKIT_VERSION, TOOLKIT_COMMIT };
 import { PromptRegistry, isPromptError } from "./prompts.js";
 import { ResourceRegistry, isResourceError } from "./resources.js";
 import { generateServerInstructions, getContextualTip, TOOL_GUIDANCE } from "./guidance.js";
-import { resolveSyncBehavior, loadSyncOptions } from "../sync/sync-options.js";
-import { fingerprintPersona, transformWorkflowForTarget } from "../sync.js";
-// Direct Sync (Config-less) - extracted to handlers/sync/direct.ts
-import { directSyncPersona, directSyncPersonaById, directSyncAll } from "./handlers/sync/direct.js";
-import { createVersionStorage } from "../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../sync/version-policy.js";
-// Auto Builder Knowledge
-import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
-// Workflow Data (LLM does analysis with rules from ema://rules/*)
-validateWorkflowConnections, parseWorkflowDef, } from "./knowledge.js";
-// Template fallbacks (generated from protos, used when API unavailable)
-import { getTemplateFallback, getTemplateFieldDocs, VOICE_TEMPLATE_FALLBACK } from "../sdk/generated/template-fallbacks.js";
-// Workflow Compiler (Template-driven)
-import { compileWorkflow, } from "./domain/workflow-generator.js";
-// V2 Tools (4 tools: persona, catalog, sync, env) - NEW DEFAULT
-import { generateTools, } from "./tools.js";
-import { handleEnv, handlePersona, 
-// handleWorkflow - removed, now using extracted handler from ./handlers/workflow/index.js
-handleAction, 
-// handleData - removed, now using extracted handler from ./handlers/data/index.js
-handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
-// Import extracted handlers
-import { handleWorkflow } from "./handlers/workflow/index.js";
+// V2 Tools
+import { generateTools } from "./tools.js";
+// Handler imports (simple 1-2 line handlers stay inline)
+import { handleEnv } from "./handlers/env/index.js";
+import { handleAction } from "./handlers/action/index.js";
+import { handleTemplate } from "./handlers/template/index.js";
+import { handleReference } from "./handlers/reference/index.js";
 import { handleCatalog } from "./handlers/catalog/index.js";
 import { handleFeedback } from "./handlers/feedback/index.js";
 import { recordTelemetry } from "./handlers/feedback/store.js";
-import { handleConsolidateDemoData, handleGenerateDemoDocument, handleValidateDemoDocument, handleGetDemoDataTemplate, } from "./handlers/demo/index.js";
-// Import from handler utilities (normalizeTriggerType uses generated enum labels)
-import { normalizeTriggerType } from "./handlers/utils.js";
-// Import from SDK proto-config (CANONICAL widget validation and merging)
-import { mergeProtoConfig } from "../sdk/proto-config.js";
-// Workflow Auto-Fix Helpers (extracted to handlers/workflow/fix.ts)
-import { summarizeWorkflow } from "./handlers/workflow/fix.js";
+// V2 adapters (extracted from server.ts — each owns its routing/transformation logic)
+import { handlePersonaAdapter } from "./handlers/persona/adapter.js";
+import { handleWorkflowAdapter } from "./handlers/workflow/adapter.js";
+import { handleSyncAdapter } from "./handlers/sync/adapter.js";
+import { handleDemoAdapter } from "./handlers/demo/adapter.js";
+import { handleDebugAdapter } from "./handlers/debug/adapter.js";
 // Start token initialization in background (non-blocking)
 void initializeApiKeyTokens();
-// Helper to add env parameter to schema - returns Tool-compatible inputSchema
-function withEnvParam(props, required = []) {
-    const envs = getAvailableEnvironments();
-    const envNames = envs.map((e) => e.name);
-    return {
-        type: "object",
-        properties: {
-            ...props,
-            env: {
-                type: "string",
-                description: `Target environment. Available: ${envNames.join(", ")}. Default: ${getDefaultEnvName()}`,
-            },
-        },
-        required,
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Tool Definitions
-// ─────────────────────────────────────────────────────────────────────────────
-//
-// V2 TOOLS (5 tools) - LLM-optimized minimal interface
-//   - env, persona, catalog, workflow, sync
-//   - Defined in: ./tools.ts
-//
-// NAMING CONVENTION:
-// - Tool names are defined as BASE NAMES (e.g., "persona")
-// - MCP clients prefix with "mcp_{server}_" (e.g., "mcp_ema_persona")
-//
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Generate all available tools
- *
- * V2: 5 tools (persona, catalog, workflow, sync, env) - LLM-optimized
- *
- * Why V2:
- * - Minimal tool count optimizes LLM tool selection
- * - Data operations under persona (always persona-scoped)
- * - Catalog consolidates all reference data (actions, templates, etc.)
- * - Clear separation: entity (persona), reference (catalog), operation (sync, workflow)
- */
-function generateAllTools() {
-    const envNames = getAvailableEnvironments().map(e => e.name);
-    const defaultEnv = getDefaultEnvName();
-    return generateTools(envNames, defaultEnv);
-}
-// Generate tools (called once at module load)
-const TOOLS = generateAllTools();
-// ─────────────────────────────────────────────────────────────────────────────
-// ADDITIONAL TOOLS (special-purpose inline tools)
-// These handle specific operations that don't fit the V2 pattern
-// ─────────────────────────────────────────────────────────────────────────────
-const ADDITIONAL_TOOLS = [
-    // NOTE: Tools (persona, catalog, workflow, sync, env) are in ./tools.ts
-    //
-    // Special-purpose tools here:
-    // - compile_workflow - Direct workflow compilation
-    // - Demo data tools - RAG document generation/validation
-    // - Data source tools - Upload/delete/manage knowledge sources
-    // toggle_embedding
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Workflow Compilation - Template-driven, no biased patterns
-    // Read ema://catalog/patterns for pattern references, then construct nodes
-    // ─────────────────────────────────────────────────────────────────────────────
-    {
-        name: "compile_workflow",
-        description: `🔧 Compile workflow from node specification. Template-driven - read \`ema://catalog/patterns\` for pattern templates, construct nodes, then compile.
-
-**Process**:
-1. Read \`ema://catalog/patterns\` for pattern reference
-2. Read \`ema://catalog/agents\` for available actions
-3. Construct nodes array based on requirements
-4. Call compile_workflow with nodes
-5. Use deploy_workflow to deploy result
-
-**Example nodes** (KB search):
-\`\`\`json
-[
-  { "id": "trigger", "action_type": "chat_trigger", "display_name": "Trigger" },
-  { "id": "search", "action_type": "search", "display_name": "Search", "inputs": { "query": { "type": "action_output", "action_name": "trigger", "output": "user_query" } } },
-  { "id": "respond", "action_type": "respond_with_sources", "display_name": "Respond", "inputs": { "search_results": { "type": "action_output", "action_name": "search", "output": "search_results" } } }
-]
-\`\`\``,
-        inputSchema: {
-            type: "object",
-            properties: {
-                name: { type: "string", description: "Workflow name" },
-                description: { type: "string", description: "Workflow description" },
-                persona_type: { type: "string", enum: ["voice", "chat", "dashboard"], description: "AI type" },
-                nodes: {
-                    type: "array",
-                    description: "Node definitions",
-                    items: {
-                        type: "object",
-                        properties: {
-                            id: { type: "string", description: "Node ID" },
-                            action_type: { type: "string", description: "Action type (e.g., chat_trigger, search, respond_with_sources)" },
-                            display_name: { type: "string", description: "Display name" },
-                            description: { type: "string", description: "Optional description" },
-                            inputs: { type: "object", description: "Input bindings (key: input name, value: binding spec)" },
-                            run_if: {
-                                type: "object",
-                                description: "Conditional execution",
-                                properties: {
-                                    source_action: { type: "string" },
-                                    source_output: { type: "string", description: "Output name to check" },
-                                    operator: { type: "string", enum: ["eq", "neq", "gt", "lt", "gte", "lte"], description: "Comparison operator" },
-                                    value: { type: "string", description: "Value to compare against" },
-                                },
-                            },
-                            categories: {
-                                type: "array",
-                                description: "Categories for categorizer nodes",
-                                items: {
-                                    type: "object",
-                                    properties: {
-                                        name: { type: "string", description: "Category name (e.g., 'Password Reset', 'Fallback')" },
-                                        description: { type: "string", description: "When this category triggers" },
-                                        examples: { type: "array", items: { type: "string" }, description: "Example phrases" },
-                                    },
-                                },
-                            },
-                            tools: {
-                                type: "array",
-                                description: "External tools for external_action_caller nodes",
-                                items: {
-                                    type: "object",
-                                    properties: {
-                                        name: { type: "string", description: "Tool name" },
-                                        namespace: { type: "string", description: "Tool namespace" },
-                                    },
-                                },
-                            },
-                            disable_human_interaction: { type: "boolean", description: "If true, disable HITL for this node" },
-                        },
-                        required: ["id", "action_type", "display_name"],
-                    },
-                },
-                result_mappings: {
-                    type: "array",
-                    description: "Which node outputs map to WORKFLOW_OUTPUT",
-                    items: {
-                        type: "object",
-                        properties: {
-                            node_id: { type: "string", description: "Node ID" },
-                            output: { type: "string", description: "Output name from the node" },
-                        },
-                        required: ["node_id", "output"],
-                    },
-                },
-            },
-            required: ["name", "description", "persona_type", "nodes", "result_mappings"],
-        },
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Data Source Management
-    // TODO: Add support for 3rd party data sources (Google Drive, SharePoint, Confluence, etc.)
-    // ─────────────────────────────────────────────────────────────────────────
-    {
-        name: "upload_data_source",
-        description: "Upload a file from the local filesystem to an AI Employee's knowledge base. The file will be available for RAG/search if embedding is enabled. IMPORTANT: Upload data sources BEFORE deploying workflows that reference them.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                persona_id: {
-                    type: "string",
-                    description: "The AI Employee ID to upload the file to",
-                },
-                file_path: {
-                    type: "string",
-                    description: "Absolute path to the file on the local filesystem",
-                },
-                tags: {
-                    type: "string",
-                    description: "Optional tags for categorizing the file (default: 'fileUpload')",
-                },
-                env: {
-                    type: "string",
-                    description: "Target environment. Available: dev, demo, staging. Default: demo",
-                },
-            },
-            required: ["persona_id", "file_path"],
-        },
-    },
-    {
-        name: "delete_data_source",
-        description: "Delete a file from an AI Employee's knowledge base.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                persona_id: {
-                    type: "string",
-                    description: "The AI Employee ID",
-                },
-                file_id: {
-                    type: "string",
-                    description: "The file ID to delete (from list_data_sources)",
-                },
-                env: {
-                    type: "string",
-                    description: "Target environment. Available: dev, demo, staging. Default: demo",
-                },
-            },
-            required: ["persona_id", "file_id"],
-        },
-    },
-    {
-        name: "list_data_sources",
-        description: "List data sources (knowledge base files/documents) configured for an AI Employee, including upload status and file count.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                persona_id: {
-                    type: "string",
-                    description: "The AI Employee ID to list data sources for",
-                },
-                env: {
-                    type: "string",
-                    description: "Target environment. Available: dev, demo, staging. Default: demo",
-                },
-            },
-            required: ["persona_id"],
-        },
-    },
-    {
-        name: "get_embedding_status",
-        description: "Get the embedding/RAG status for an AI Employee's knowledge base.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                persona_id: {
-                    type: "string",
-                    description: "The AI Employee ID",
-                },
-                env: {
-                    type: "string",
-                    description: "Target environment. Available: dev, demo, staging. Default: demo",
-                },
-            },
-            required: ["persona_id"],
-        },
-    },
-    {
-        name: "toggle_embedding",
-        description: "Enable or disable embedding/RAG for an AI Employee's knowledge base. When enabled, uploaded documents are indexed for semantic search.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                persona_id: {
-                    type: "string",
-                    description: "The AI Employee ID",
-                },
-                enabled: {
-                    type: "boolean",
-                    description: "Whether to enable (true) or disable (false) embedding",
-                },
-                env: {
-                    type: "string",
-                    description: "Target environment. Available: dev, demo, staging. Default: demo",
-                },
-            },
-            required: ["persona_id", "enabled"],
-        },
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Unified Workflow Tool
-    // Accepts any input: natural language, partial spec, full spec, or persona_id
-    // Normalizes to WorkflowIntent → validates → generates → deploys
-    // ─────────────────────────────────────────────────────────────────────────
-    {
-        name: "workflow",
-        description: `🔧 UNIFIED workflow tool. Accepts ANY input and normalizes it.
-
-**Input types** (auto-detected):
-- Natural language: "IT helpdesk that creates ServiceNow tickets"
-- Partial spec: { intents: [...], tools: [...] }
-- Full nodes spec: { nodes: [...], result_mappings: [...] }
-- Existing persona: persona_id to analyze/improve
-
-**Process**:
-1. Parse input → WorkflowIntent (normalized representation)
-2. Validate completeness → return questions if incomplete
-3. Generate workflow (local compile or Auto Builder)
-4. Validate output → auto-fix if enabled
-5. Deploy if persona_id provided
-
-**Examples**:
-\`\`\`
-workflow("IT helpdesk bot with KB search")
-workflow({ intents: [{name: "Billing", handler: "search"}], tools: [{namespace: "service_now", action: "Create_Ticket"}] })
-workflow(persona_id, mode="improve")
-\`\`\``,
-        inputSchema: withEnvParam({
-            input: {
-                description: "Natural language description, partial spec object, or full nodes spec",
-            },
-            persona_id: {
-                type: "string",
-                description: "For deployment OR to analyze/improve existing workflow",
-            },
-            mode: {
-                type: "string",
-                enum: ["generate", "improve", "analyze"],
-                description: "generate (default): Create new workflow. improve: Fix existing. analyze: Validate only.",
-            },
-            persona_type: {
-                type: "string",
-                enum: ["voice", "chat", "dashboard"],
-                description: "AI type (default: chat, auto-detected from input)",
-            },
-            use_autobuilder: {
-                type: "boolean",
-                description: "Force Auto Builder for generation (default: auto-decide based on complexity)",
-            },
-            auto_deploy: {
-                type: "boolean",
-                description: "Deploy immediately (default: false - returns preview)",
-            },
-            auto_fix: {
-                type: "boolean",
-                description: "Auto-fix detected issues (default: true)",
-            },
-        }, []),
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Demo Data Management
-    // Tools for consolidating, transforming, and preparing mock data for RAG
-    // ─────────────────────────────────────────────────────────────────────────
-    {
-        name: "consolidate_demo_data",
-        description: `Transform normalized JSON source files into RAG-optimized Markdown documents for Ema knowledge bases.
-
-This tool pre-joins related data (like customers + orders + tickets) into denormalized entity documents that work well with semantic search.
-
-**Why this matters**: RAG systems can't do SQL-style joins at query time. Data relationships must be explicit in the document content.
-
-**Supported patterns**:
-- Entity consolidation (customer with all their orders, tickets, contacts)
-- Product catalogs with cross-references
-- Scenario documents for demos
-
-**Output format**: Markdown files with embedded tables, metadata comments, and narrative summaries optimized for Ema's search agents.`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                source_dir: {
-                    type: "string",
-                    description: "Path to directory containing source JSON files (e.g., './data/source')",
-                },
-                output_dir: {
-                    type: "string",
-                    description: "Path to output directory for generated Markdown files (e.g., './data/knowledge-base')",
-                },
-                entity_type: {
-                    type: "string",
-                    enum: ["customer", "product", "employee", "scenario", "custom"],
-                    description: "Type of entity being consolidated. Determines document structure.",
-                },
-                primary_file: {
-                    type: "string",
-                    description: "Name of the primary JSON file (e.g., 'customers.json')",
-                },
-                joins: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            file: { type: "string", description: "JSON file to join (e.g., 'orders.json')" },
-                            on: { type: "string", description: "Foreign key field (e.g., 'customerId')" },
-                            as: { type: "string", description: "Name for the joined data (e.g., 'orders')" },
-                        },
-                    },
-                    description: "Array of files to join with the primary file",
-                },
-                id_field: {
-                    type: "string",
-                    description: "Field name for the entity ID (default: 'id')",
-                },
-                name_field: {
-                    type: "string",
-                    description: "Field name for the entity name (default: 'name')",
-                },
-                tags: {
-                    type: "string",
-                    description: "Comma-separated tags to include in document metadata",
-                },
-            },
-            required: ["source_dir", "output_dir", "entity_type", "primary_file"],
-        },
-    },
-    {
-        name: "generate_demo_document",
-        description: `Generate a single RAG-optimized Markdown document from provided JSON data.
-
-Use this for:
-- Creating individual entity documents programmatically
-- Testing document formats before batch consolidation
-- Custom document generation with specific data
-
-The output follows Ema's knowledge base best practices with metadata comments, tables, and narrative context.`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_type: {
-                    type: "string",
-                    enum: ["customer", "product", "employee", "scenario", "reference"],
-                    description: "Type of document to generate",
-                },
-                data: {
-                    type: "object",
-                    description: "The entity data as a JSON object",
-                },
-                related_data: {
-                    type: "object",
-                    description: "Related data to include (e.g., { orders: [...], tickets: [...] })",
-                },
-                output_path: {
-                    type: "string",
-                    description: "Optional: Path to save the generated document. If not provided, returns the content.",
-                },
-                tags: {
-                    type: "string",
-                    description: "Comma-separated tags for metadata",
-                },
-            },
-            required: ["entity_type", "data"],
-        },
-    },
-    {
-        name: "validate_demo_document",
-        description: `Validate a Markdown document for RAG optimization and Ema compatibility.
-
-Checks for:
-- Required metadata comments (ema_entity, ema_id, ema_tags)
-- Table formatting
-- Narrative context presence
-- Cross-reference consistency
-- Filename conventions`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                file_path: {
-                    type: "string",
-                    description: "Path to the Markdown file to validate",
-                },
-                content: {
-                    type: "string",
-                    description: "Alternatively, provide the document content directly",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "get_demo_data_template",
-        description: `Get a template for demo data documents based on entity type.
-
-Returns:
-- Source JSON schema (what fields to include)
-- Output Markdown template
-- Best practices for the entity type
-- Example data`,
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity_type: {
-                    type: "string",
-                    enum: ["customer", "product", "employee", "scenario", "reference"],
-                    description: "Type of template to get",
-                },
-                include_example: {
-                    type: "boolean",
-                    description: "Include example data (default: true)",
-                },
-            },
-            required: ["entity_type"],
-        },
-    },
-];
-const toolHandlers = {
-    // Environment Management
-    list_environments: async () => {
-        const envs = getAvailableEnvironments();
-        const defaultEnv = getDefaultEnvName();
-        return {
-            default_environment: defaultEnv,
-            environments: envs.map((e) => ({
-                name: e.name,
-                url: e.baseUrl,
-                is_default: e.name === defaultEnv,
-            })),
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // AI Employee Handlers (Consolidated)
-    // ─────────────────────────────────────────────────────────────────────────
-    get_persona: async (args) => {
-        const client = createClient(args.env);
-        const identifier = String(args.identifier);
-        const includeWorkflow = args.include_workflow === true;
-        const includeFingerprint = args.include_fingerprint === true;
-        // Auto-detect: UUIDs are 36 chars with dashes, otherwise it's a name
-        const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifier);
-        let persona;
-        if (isUUID) {
-            // Fetch by ID - use full fetch if workflow needed, otherwise list
-            if (includeWorkflow || includeFingerprint) {
-                persona = (await client.getPersonaById(identifier)) ?? undefined;
-            }
-            else {
-                const personas = await client.getPersonasForTenant();
-                persona = personas.find((p) => p.id === identifier);
-            }
-        }
-        else {
-            // Fetch by name - always need to list first to find ID
-            const personas = await client.getPersonasForTenant();
-            persona = personas.find((p) => p.name === identifier);
-            // If found and need workflow, fetch full details
-            if (persona && (includeWorkflow || includeFingerprint)) {
-                persona = (await client.getPersonaById(persona.id)) ?? undefined;
-            }
-        }
-        if (!persona) {
-            throw new Error(`AI Employee not found: ${identifier} (searched by ${isUUID ? "ID" : "name"})`);
-        }
-        // Build response
-        const result = {
-            environment: client["env"].name,
-            ai_employee: persona,
-        };
-        // Add fingerprint if requested
-        if (includeFingerprint) {
-            result.fingerprint = fingerprintPersona(persona);
-        }
-        return result;
-    },
-    find_personas: async (args) => {
-        const client = createClient(args.env);
-        let personas = await client.getPersonasForTenant();
-        // Apply filters
-        if (args.query) {
-            const q = String(args.query).toLowerCase();
-            personas = personas.filter((p) => p.name?.toLowerCase().includes(q));
-        }
-        if (args.status) {
-            const f = String(args.status).toLowerCase();
-            personas = personas.filter((p) => p.status?.toLowerCase() === f);
-        }
-        if (args.trigger_type) {
-            const f = String(args.trigger_type).toLowerCase();
-            personas = personas.filter((p) => p.trigger_type?.toLowerCase() === f);
-        }
-        if (args.access_level) {
-            const f = String(args.access_level).toLowerCase();
-            personas = personas.filter((p) => p.access_level?.toLowerCase() === f);
-        }
-        if (typeof args.has_workflow === "boolean") {
-            personas = personas.filter((p) => args.has_workflow ? !!p.workflow_id : !p.workflow_id);
-        }
-        if (typeof args.embedding_enabled === "boolean") {
-            personas = personas.filter((p) => p.embedding_enabled === args.embedding_enabled);
-        }
-        const limit = typeof args.limit === "number" ? args.limit : 50;
-        personas = personas.slice(0, limit);
-        return {
-            environment: client["env"].name,
-            count: personas.length,
-            ai_employees: personas.map((p) => ({
-                id: p.id,
-                name: p.name,
-                description: p.description,
-                status: p.status,
-                template_id: p.template_id ?? p.templateId,
-                workflow_id: p.workflow_id,
-                trigger_type: p.trigger_type,
-                access_level: p.access_level,
-                embedding_enabled: p.embedding_enabled,
-            })),
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // AI Employee CRUD Handlers
-    // ─────────────────────────────────────────────────────────────────────────
-    create_ai_employee: async (args) => {
-        const client = createClient(args.env);
-        // Determine template_id: explicit > dynamic lookup based on persona_type
-        let templateId = args.template_id ? String(args.template_id) : undefined;
-        const sourcePersonaId = args.source_persona_id ? String(args.source_persona_id) : undefined;
-        // If no template_id or source_persona_id, use dynamic template lookup
-        if (!templateId && !sourcePersonaId) {
-            const personaType = args.persona_type ? String(args.persona_type).toLowerCase() : null;
-            if (personaType) {
-                // Dynamic template lookup - templates are tenant-specific
-                const templates = await client.getPersonaTemplates();
-                const matchingTemplate = templates.find(t => normalizeTriggerType(t.trigger_type) === personaType);
-                if (matchingTemplate) {
-                    templateId = matchingTemplate.id;
-                }
-                else {
-                    const availableTypes = [...new Set(templates.map(t => normalizeTriggerType(t.trigger_type)).filter(Boolean))];
-                    throw new Error(`No template found for type "${personaType}". Available types: ${availableTypes.join(", ") || "none"}`);
-                }
-            }
-            else {
-                throw new Error("Must provide template_id, source_persona_id, or persona_type");
-            }
-        }
-        const req = {
-            name: String(args.name),
-            description: args.description ? String(args.description) : undefined,
-            template_id: templateId,
-            source_persona_id: sourcePersonaId,
-            // Note: trigger_type is determined by template, not passed separately
-        };
-        const result = await client.createAiEmployee(req);
-        return {
-            environment: client["env"].name,
-            success: true,
-            persona_id: result.persona_id ?? result.id,
-            status: result.status ?? "created",
-            template_used: templateId,
-        };
-    },
-    update_ai_employee: async (args) => {
-        const client = createClient(args.env);
-        const personaId = String(args.persona_id);
-        // Use getPersonaById for complete data (including full proto_config)
-        const existing = await client.getPersonaById(personaId);
-        if (!existing)
-            throw new Error(`AI Employee not found: ${personaId}`);
-        // Merge proto_config using SDK function (deep merges widgets by name)
-        const mergedProtoConfig = mergeProtoConfig(existing.proto_config, args.proto_config);
-        // Check if user is trying to pass workflow - redirect them to deploy_workflow
-        if (args.workflow) {
-            return {
-                environment: client["env"].name,
-                success: false,
-                error: "workflow_parameter_deprecated",
-                message: "The 'workflow' parameter has been removed from update_ai_employee. " +
-                    "Use workflow(mode='get' → mode='deploy') instead (it provides validation and strict stale-state protection).",
-                suggestion: {
-                    tool: "workflow",
-                    parameters: {
-                        mode: "deploy",
-                        persona_id: personaId,
-                        base_fingerprint: "<fingerprint_from_workflow_get>",
-                        workflow_def: "your_workflow_here",
-                    },
-                },
-            };
-        }
-        // CRITICAL: The Ema API requires workflow to be sent along with proto_config
-        // for proto_config changes to persist. Without workflow, updates silently fail.
-        // GET returns 'workflow_def', UPDATE expects 'workflow' field.
-        const existingWorkflow = (existing.workflow_def ?? existing.workflow);
-        const req = {
-            persona_id: personaId,
-            name: args.name ? String(args.name) : undefined,
-            description: args.description ? String(args.description) : undefined,
-            proto_config: mergedProtoConfig,
-            workflow: existingWorkflow, // Required for proto_config to persist
-            embedding_enabled: typeof args.embedding_enabled === "boolean" ? args.embedding_enabled : undefined,
-            enabled_by_user: typeof args.enabled_by_user === "boolean" ? args.enabled_by_user : undefined,
-        };
-        await client.updateAiEmployee(req);
-        return {
-            environment: client["env"].name,
-            success: true,
-            persona_id: personaId,
-            persona_name: existing.name,
-            updated_fields: {
-                name: !!args.name,
-                description: !!args.description,
-                proto_config: !!args.proto_config,
-                embedding_enabled: typeof args.embedding_enabled === "boolean",
-                enabled_by_user: typeof args.enabled_by_user === "boolean",
-            },
-            note: "For workflow changes, use deploy_workflow which provides validation and auto-fix.",
-        };
-    },
-    deploy_workflow: async (args) => {
-        const client = createClient(args.env);
-        const personaId = String(args.persona_id);
-        const validateFirst = args.validate_first !== false; // default true
-        const autoFix = args.auto_fix === true; // default false
-        const force = args.force === true;
-        const baseFingerprint = args.base_fingerprint;
-        // Get existing persona with full details
-        const persona = await client.getPersonaById(personaId);
-        if (!persona)
-            throw new Error(`AI Employee not found: ${personaId}`);
-        // STRICT: stale-state protection + required snapshot (same safety as workflow tool)
-        const currentFp = fingerprintPersona(persona);
-        if (!force && !baseFingerprint) {
-            return {
-                environment: client["env"].name,
-                success: false,
-                error: "base_fingerprint_required",
-                persona_id: personaId,
-                current_fingerprint: currentFp,
-                message: "base_fingerprint is required for deploy_workflow (stale-state protection). " +
-                    "Re-fetch the latest state and retry.",
-                hint: "Prefer: workflow(mode='get') → workflow(mode='deploy', base_fingerprint='<fingerprint>', ...). " +
-                    "Use force=true only for emergency overrides.",
-            };
-        }
-        if (!force && baseFingerprint && baseFingerprint !== currentFp) {
-            return {
-                environment: client["env"].name,
-                success: false,
-                error: "fingerprint_mismatch",
-                persona_id: personaId,
-                base_fingerprint: baseFingerprint,
-                current_fingerprint: currentFp,
-                message: "Persona changed since you last fetched it (fingerprint mismatch).",
-                hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. " +
-                    "Use force=true only if you intend to overwrite out-of-band changes.",
-            };
-        }
-        // Required pre-deploy snapshot (local)
-        try {
-            const storage = createVersionStorage(process.cwd());
-            const engine = createVersionPolicyEngine(storage);
-            const snap = engine.forceCreateVersion(persona, {
-                environment: client["env"].name,
-                tenant_id: client["env"].name,
-                message: "Pre-deploy snapshot (deploy_workflow)",
-                created_by: "mcp-toolkit",
-            });
-            if (!snap.created || !snap.version) {
-                if (!force) {
-                    return {
-                        environment: client["env"].name,
-                        success: false,
-                        error: "pre_deploy_snapshot_failed",
-                        persona_id: personaId,
-                        details: snap.reason,
-                        hint: "Fix local snapshot storage or retry with force=true for emergency override.",
-                    };
-                }
-            }
-        }
-        catch (e) {
-            if (!force) {
-                return {
-                    environment: client["env"].name,
-                    success: false,
-                    error: "pre_deploy_snapshot_failed",
-                    persona_id: personaId,
-                    details: e instanceof Error ? e.message : String(e),
-                    hint: "Fix local snapshot storage or retry with force=true for emergency override.",
-                };
-            }
-        }
-        let workflowDef = args.workflow_def;
-        const protoConfig = args.proto_config;
-        if (!workflowDef && !protoConfig) {
-            throw new Error("At least one of workflow_def or proto_config must be provided");
-        }
-        // Sanitize workflow_def to prevent server-side crashes
-        if (workflowDef) {
-            // Fix enumTypes - remove entries with empty/missing names (causes server panic)
-            // EnumType structure in proto: { name: { name: { name: "string", namespaces: [] } }, options: [...] }
-            // The backend calls FlattenNamespacedName(enum.Name.Name) which panics if Name.Name is nil
-            const enumTypes = workflowDef.enumTypes;
-            if (Array.isArray(enumTypes)) {
-                const validEnumTypes = enumTypes.filter(e => {
-                    // Navigate the nested structure: e.name.name.name
-                    const outerName = e.name;
-                    const innerName = outerName?.name;
-                    const actualName = innerName?.name;
-                    // Must have the full structure with a non-empty string name
-                    return typeof actualName === "string" && actualName.trim().length > 0;
-                });
-                if (validEnumTypes.length > 0) {
-                    workflowDef.enumTypes = validEnumTypes;
-                }
-                else {
-                    // Remove empty enumTypes entirely
-                    delete workflowDef.enumTypes;
-                }
-            }
-            // Ensure all actions have a 'name' field (node identifier)
-            const actions = workflowDef.actions;
-            if (Array.isArray(actions)) {
-                for (const action of actions) {
-                    // If action has 'actionName' but not 'name', fix it
-                    if (!action.name && action.actionName) {
-                        action.name = action.actionName;
-                    }
-                    // Ensure name is a non-empty string
-                    if (!action.name || (typeof action.name === "string" && action.name.trim().length === 0)) {
-                        // Try to derive from action type
-                        const actionType = action.action;
-                        if (actionType?.name?.name) {
-                            action.name = `${actionType.name.name}_${actions.indexOf(action)}`;
-                        }
-                    }
-                    // CRITICAL: Normalize action structure to include required empty fields
-                    // The backend expects these fields to exist (even if empty) or it may 500
-                    if (action.typeArguments === undefined) {
-                        action.typeArguments = {};
-                    }
-                    if (action.tools === undefined) {
-                        action.tools = [];
-                    }
-                    if (action.disableHumanInteraction === undefined) {
-                        action.disableHumanInteraction = false;
-                    }
-                    // Ensure displaySettings exists and has required structure
-                    if (!action.displaySettings) {
-                        action.displaySettings = {
-                            displayName: String(action.name || ""),
-                            coordinates: { x: 0, y: 0 },
-                            description: "",
-                            showConfig: 0,
-                        };
-                    }
-                    else {
-                        const ds = action.displaySettings;
-                        if (ds.description === undefined)
-                            ds.description = "";
-                        if (ds.showConfig === undefined)
-                            ds.showConfig = 0;
-                    }
-                    // Ensure inputs exists
-                    if (action.inputs === undefined) {
-                        action.inputs = {};
-                    }
-                    // Normalize runIf operator enum: backend proto expects numeric values (e.g. 1),
-                    // but some JSON payloads use string enums (e.g. "OPERATOR_EQ") which can 500.
-                    const runIf = action.runIf;
-                    if (runIf && typeof runIf === "object") {
-                        const op = runIf.operator;
-                        if (typeof op === "string") {
-                            const opMap = {
-                                OPERATOR_EQ: 1,
-                                OPERATOR_NEQ: 2,
-                                OPERATOR_GT: 3,
-                                OPERATOR_GTE: 4,
-                                OPERATOR_LT: 5,
-                                OPERATOR_LTE: 6,
-                                OPERATOR_IN: 7,
-                                OPERATOR_NOT_IN: 8,
-                            };
-                            if (opMap[op] !== undefined)
-                                runIf.operator = opMap[op];
-                        }
-                    }
-                }
-            }
-        }
-        // Get existing workflow info
-        const existingWorkflow = persona.workflow_def;
-        const existingWorkflowId = persona.workflow_id;
-        // Copy missing top-level workflow fields from existing workflow.
-        // Some backends are strict about presence of these keys.
-        if (workflowDef && existingWorkflow) {
-            const copyIfMissing = (k) => {
-                if (workflowDef[k] === undefined && existingWorkflow[k] !== undefined) {
-                    workflowDef[k] = JSON.parse(JSON.stringify(existingWorkflow[k]));
-                }
-            };
-            copyIfMissing("workflowInputs");
-            copyIfMissing("namedResults");
-            copyIfMissing("displayName");
-            copyIfMissing("description");
-            copyIfMissing("namedResultsEditable");
-            copyIfMissing("namedResultsEnabled");
-            copyIfMissing("edges");
-        }
-        // Determine deployment strategy
-        const hasExistingWorkflow = !!existingWorkflowId;
-        let deploymentMethod = hasExistingWorkflow ? "direct_api" : "autobuilder";
-        // === WORKFLOW ID TRANSFORMATION ===
-        // If workflow was generated for a different persona, transform IDs to target persona
-        // (No brownfield merging - we do full workflow replacement)
-        if (workflowDef && hasExistingWorkflow && existingWorkflow) {
-            // Extract source persona ID from incoming workflow (if any)
-            const incomingWfName = workflowDef.workflowName;
-            const sourcePersonaId = incomingWfName?.name?.namespaces?.[2]; // Usually at index 2: ["ema", "templates", "<persona_id>"]
-            if (sourcePersonaId && sourcePersonaId !== personaId) {
-                // Workflow was generated for a different persona - transform IDs
-                workflowDef = transformWorkflowForTarget(workflowDef, sourcePersonaId, personaId);
-            }
-        }
-        else if (workflowDef && hasExistingWorkflow && !existingWorkflow) {
-            // Has workflow_id but no workflow_def (edge case) - construct workflowName from workflow_id
-            // workflow_id format: "ema.templates.<persona_id>.default" or similar
-            const parts = existingWorkflowId.split(".");
-            if (parts.length >= 3) {
-                workflowDef.workflowName = {
-                    name: {
-                        namespaces: parts.slice(0, -1),
-                        name: parts[parts.length - 1],
-                    },
-                };
-            }
-        }
-        // Track fixes applied
-        const appliedFixes = [];
-        let fixAttempted = false;
-        // Validation is now done by backend when workflow is deployed
-        // LLM should use ema://rules/* for pre-validation guidance
-        const validationResults = { valid: true, issues: [] };
-        if (validateFirst && workflowDef) {
-            // DEPRECATED: MCP no longer pre-validates workflows
-            // Backend validation happens on deploy
-            // LLM uses ema://rules/anti-patterns for analysis
-            console.warn("[DEPRECATED] validateFirst is deprecated - backend validates on deploy");
-            if (autoFix) {
-                // Auto-fix is removed - return guidance for LLM
-                return {
-                    environment: client["env"].name,
-                    success: false,
-                    persona_id: personaId,
-                    persona_name: persona.name,
-                    _deprecation_notice: "autoFix is deprecated. Use LLM analysis with ema://rules/* instead.",
-                    _guidance: [
-                        "1. Fetch ema://rules/anti-patterns",
-                        "2. Analyze workflow against rules",
-                        "3. Make structured modifications",
-                        "4. Deploy via workflow(mode='deploy')",
-                    ],
-                    applied_fixes: [],
-                };
-            }
-        }
-        // If validation failed and not forcing, return the issues
-        if (!validationResults.valid) {
-            return {
-                environment: client["env"].name,
-                success: false,
-                persona_id: personaId,
-                persona_name: persona.name,
-                validation_failed: true,
-                issues: validationResults.issues,
-                auto_fix_attempted: fixAttempted,
-                fixes_applied: appliedFixes.filter(f => f.applied),
-                fixes_failed: appliedFixes.filter(f => !f.applied),
-                remaining_issues: validationResults.issues.length,
-                hint: autoFix
-                    ? "Some issues could not be auto-fixed. Review the remaining issues and fix manually, or set validate_first=false to skip validation (not recommended)"
-                    : "Fix the issues above, enable auto_fix=true for automatic fixes, or set validate_first=false to skip validation (not recommended)",
-            };
-        }
-        // Merge proto_config using SDK function (deep merges widgets by name)
-        const mergedProtoConfig = mergeProtoConfig(persona.proto_config, protoConfig);
-        // Auto-fix malformed HITL runIf patterns BEFORE deploy (H1: production-grade fix)
-        // Pattern: "hitl_status_HITL Success" should be output="hitl_status", enumValue="HITL Success"
-        let hitlFixCount = 0;
-        if (workflowDef) {
-            const wfActions = workflowDef.actions ?? [];
-            for (const action of wfActions) {
-                const runIfAction = action.runIf;
-                if (!runIfAction)
-                    continue;
-                const lhsAction = runIfAction.lhs;
-                const rhsAction = runIfAction.rhs;
-                if (lhsAction?.actionOutput && rhsAction?.inline) {
-                    const actionOutputField = lhsAction.actionOutput;
-                    const inlineRhsField = rhsAction.inline;
-                    const outputStr = String(actionOutputField.output ?? "");
-                    // Detect malformed HITL patterns: "hitl_status_HITL Success" or "hitl_status HITL Success"
-                    const hitlPatternMatch = outputStr.match(/^hitl_status[_\s]?(HITL[ _]?(?:Success|Failure))$/i);
-                    if (hitlPatternMatch) {
-                        // Extract and normalize the enum value
-                        let correctedEnumVal = hitlPatternMatch[1].replace(/_/g, " ");
-                        if (correctedEnumVal.toLowerCase().includes("success")) {
-                            correctedEnumVal = "HITL Success";
-                        }
-                        else if (correctedEnumVal.toLowerCase().includes("failure")) {
-                            correctedEnumVal = "HITL Failure";
-                        }
-                        // Apply the fix
-                        actionOutputField.output = "hitl_status";
-                        inlineRhsField.enumValue = correctedEnumVal;
-                        hitlFixCount++;
-                    }
-                }
-            }
-        }
-        // Build update request
-        const req = {
-            persona_id: personaId,
-            proto_config: mergedProtoConfig,
-            workflow: workflowDef,
-        };
-        // Deployment attempt with automatic fallback
-        let deployedVia = "direct_api";
-        let autobuilderResult;
-        if (deploymentMethod === "direct_api") {
-            try {
-                await client.updateAiEmployee(req);
-            }
-            catch (err) {
-                const errorMessage = err instanceof Error ? err.message : String(err);
-                // If direct API fails due to "no existing workflow", try Auto Builder
-                if (errorMessage.includes("Cannot set persona workflow without existing workflow") && workflowDef) {
-                    deploymentMethod = "autobuilder";
-                }
-                else if (errorMessage.includes("Workflow name does not match")) {
-                    // This shouldn't happen with our name sync, but handle gracefully
-                    throw new Error(`Workflow deployment failed: The workflow structure may be incompatible. ` +
-                        `Please use the Ema UI Auto Builder to make changes to this persona's workflow. ` +
-                        `(Technical: ${errorMessage})`);
-                }
-                else if ((errorMessage.toLowerCase().includes("internal server error") || errorMessage.includes("500")) && workflowDef) {
-                    // 500 error - attempt Autobuilder fallback
-                    deploymentMethod = "autobuilder";
-                }
-                else {
-                    // Other API errors - surface clearly
-                    throw new Error(`Workflow deployment failed: ${errorMessage}`);
-                }
-            }
-        }
-        // Auto Builder fallback for personas without existing workflows
-        if (deploymentMethod === "autobuilder" && workflowDef) {
-            try {
-                // Generate a prompt that asks the Auto Builder to deploy this specific workflow
-                const workflowSummary = summarizeWorkflow(workflowDef);
-                const prompt = `Deploy this workflow to the persona. The workflow has the following structure:\n\n${workflowSummary}\n\nPlease create and save this workflow.`;
-                // Use the iterate workflow method which handles Auto Builder discovery
-                autobuilderResult = await client.iterateWorkflow(personaId, prompt, { newConversation: true });
-                deployedVia = "autobuilder";
-                // Also update proto_config if provided (Auto Builder may not handle this)
-                if (protoConfig) {
-                    await client.updateAiEmployee({
-                        persona_id: personaId,
-                        proto_config: mergedProtoConfig,
-                    });
-                }
-            }
-            catch (autoErr) {
-                const autoErrorMessage = autoErr instanceof Error ? autoErr.message : String(autoErr);
-                // If Auto Builder also fails, provide clear guidance
-                if (autoErrorMessage.includes("No Autobuilder persona found")) {
-                    throw new Error(`Cannot deploy workflow: This persona has no existing workflow, and the Ema Auto Builder is not available in this tenant. ` +
-                        `Please contact your Ema administrator to enable the Auto Builder, or create a new persona from a workflow template.`);
-                }
-                throw new Error(`Workflow deployment via Auto Builder failed: ${autoErrorMessage}`);
-            }
-        }
-        // Build success note
-        let successNote = "Workflow deployed successfully. Test in the Ema simulator to verify behavior.";
-        if (deployedVia === "autobuilder") {
-            successNote = "Workflow deployed via Ema Auto Builder. Test in the Ema simulator to verify behavior.";
-        }
-        else if (fixAttempted && appliedFixes.some(f => f.applied)) {
-            successNote = `Workflow deployed successfully with ${appliedFixes.filter(f => f.applied).length} auto-fix(es) applied. Test in the Ema simulator to verify behavior.`;
-        }
-        else if (!workflowDef) {
-            successNote = "Proto config updated successfully.";
-        }
-        return {
-            environment: client["env"].name,
-            success: true,
-            persona_id: personaId,
-            persona_name: persona.name,
-            deployed: {
-                workflow_def: !!workflowDef,
-                proto_config: !!protoConfig,
-            },
-            deployment_method: deployedVia,
-            validation_passed: validationResults.valid,
-            auto_fix_applied: fixAttempted && appliedFixes.some(f => f.applied),
-            fixes_applied: appliedFixes.filter(f => f.applied),
-            autobuilder_response: autobuilderResult?.response,
-            note: successNote,
-        };
-    },
-    optimize_workflow: async (args) => {
-        const client = createClient(args.env);
-        const identifier = args.identifier ? String(args.identifier) : undefined;
-        const targetPersonaId = args.persona_id ? String(args.persona_id) : undefined;
-        const prompt = args.prompt ? String(args.prompt) : undefined;
-        const personaType = args.type ?? "chat";
-        const preview = args.preview === true;
-        // Validate inputs
-        if (!identifier && !targetPersonaId && !prompt) {
-            throw new Error('Provide either: identifier (to fix existing), or persona_id + prompt (to enhance existing)');
-        }
-        let persona = null;
-        let workflowDef;
-        let personaId;
-        let enhancementPrompt = prompt; // Store prompt for enhancement logging
-        // === ALWAYS START BY FETCHING EXISTING WORKFLOW ===
-        // Brownfield: fix existing + apply enhancements from prompt
-        // The prompt describes what to ADD or CHANGE, not a complete replacement
-        const lookupId = identifier ?? targetPersonaId;
-        const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(lookupId);
-        if (isUUID) {
-            persona = await client.getPersonaById(lookupId);
-        }
-        else {
-            // Search by name
-            const personas = await client.getPersonasForTenant();
-            const match = personas.find((p) => p.name?.toLowerCase() === lookupId.toLowerCase() ||
-                p.name?.toLowerCase().includes(lookupId.toLowerCase()));
-            if (match) {
-                persona = await client.getPersonaById(match.id);
-            }
-        }
-        if (!persona) {
-            throw new Error(`AI Employee "${lookupId}" not found. Check the name or ID.`);
-        }
-        personaId = persona.id;
-        workflowDef = persona.workflow_def;
-        if (!workflowDef) {
-            return {
-                success: false,
-                persona: persona.name,
-                status: "⚠️ No Workflow",
-                message: "This AI Employee has no workflow. Use prompt parameter to generate one: optimize_workflow(persona_id=\"...\", prompt=\"description of what it should do\")",
-            };
-        }
-        // DEPRECATED: MCP no longer pre-analyzes workflows
-        // LLM should use ema://rules/* for analysis
-        console.warn("[DEPRECATED] optimize_workflow tool is deprecated - use LLM analysis with ema://rules/*");
-        const nodes = parseWorkflowDef(workflowDef);
-        return {
-            success: true,
-            persona: persona?.name ?? "Unknown",
-            persona_id: personaId,
-            status: "DEPRECATED - use LLM analysis",
-            node_count: nodes.length,
-            workflow_def: workflowDef,
-            _deprecation_notice: {
-                message: "optimize_workflow is deprecated. MCP does not pre-compute issues.",
-                new_workflow: [
-                    "1. Fetch rules: ema://rules/anti-patterns, ema://rules/optimizations",
-                    "2. Apply rules to find issues (LLM does this, not MCP)",
-                    "3. Make structured modifications based on your analysis",
-                    "4. Deploy via workflow(mode='deploy', persona_id='...', workflow_def={...})",
-                ],
-            },
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Action Handlers (Consolidated)
-    // ─────────────────────────────────────────────────────────────────────────
-    get_workflow_action: async (args) => {
-        const client = createClient(args.env);
-        const identifier = String(args.identifier);
-        const actions = await client.listActions();
-        // Try ID first, then name
-        const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifier);
-        let action = isUUID
-            ? actions.find((a) => a.id === identifier)
-            : actions.find((a) => a.name?.toLowerCase() === identifier.toLowerCase());
-        if (!action) {
-            throw new Error(`Action not found: ${identifier} (searched by ${isUUID ? "ID" : "name"})`);
-        }
-        return { environment: client["env"].name, action };
-    },
-    find_workflow_actions: async (args) => {
-        const client = createClient(args.env);
-        // Handle list_categories request
-        if (args.list_categories === true) {
-            const actions = await client.listActions();
-            const categoryMap = new Map();
-            for (const a of actions) {
-                const cat = a.category ?? "uncategorized";
-                categoryMap.set(cat, (categoryMap.get(cat) ?? 0) + 1);
-            }
-            return {
-                environment: client["env"].name,
-                categories: Array.from(categoryMap.entries()).map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count),
-            };
-        }
-        // Handle persona/workflow scope
-        if (args.persona_id) {
-            const personaId = String(args.persona_id);
-            const personas = await client.getPersonasForTenant();
-            const persona = personas.find((p) => p.id === personaId);
-            if (!persona)
-                throw new Error(`AI Employee not found: ${personaId}`);
-            if (!persona.workflow_id) {
-                return {
-                    environment: client["env"].name,
-                    persona_id: personaId,
-                    persona_name: persona.name,
-                    error: "AI Employee has no workflow",
-                    actions: [],
-                };
-            }
-            const actionIds = await client.listActionsFromWorkflow(persona.workflow_id);
-            const allActions = await client.listActions();
-            const actionIdSet = new Set(actionIds);
-            const actions = allActions.filter(a => actionIdSet.has(a.id));
-            return {
-                environment: client["env"].name,
-                persona_id: personaId,
-                persona_name: persona.name,
-                workflow_id: persona.workflow_id,
-                count: actions.length,
-                actions: actions.map((a) => ({
-                    id: a.id, name: a.name, description: a.description,
-                    category: a.category, inputs: a.inputs, outputs: a.outputs,
-                })),
-            };
-        }
-        if (args.workflow_id) {
-            const workflowId = String(args.workflow_id);
-            const actionIds = await client.listActionsFromWorkflow(workflowId);
-            const allActions = await client.listActions();
-            const actionIdSet = new Set(actionIds);
-            const actions = allActions.filter(a => actionIdSet.has(a.id));
-            return {
-                environment: client["env"].name,
-                workflow_id: workflowId,
-                count: actions.length,
-                actions: actions.map((a) => ({
-                    id: a.id, name: a.name, description: a.description,
-                    category: a.category, inputs: a.inputs, outputs: a.outputs,
-                })),
-            };
-        }
-        // Default: search all actions
-        let actions = await client.listActions();
-        if (args.query) {
-            const q = String(args.query).toLowerCase();
-            actions = actions.filter((a) => a.name?.toLowerCase().includes(q));
-        }
-        if (args.category) {
-            const f = String(args.category).toLowerCase();
-            actions = actions.filter((a) => a.category?.toLowerCase() === f);
-        }
-        if (typeof args.enabled === "boolean") {
-            actions = actions.filter((a) => a.enabled === args.enabled);
-        }
-        const limit = typeof args.limit === "number" ? args.limit : 100;
-        actions = actions.slice(0, limit);
-        return {
-            environment: client["env"].name,
-            count: actions.length,
-            actions: actions.map((a) => ({
-                id: a.id, name: a.name, description: a.description,
-                category: a.category, enabled: a.enabled, tags: a.tags,
-            })),
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // ─────────────────────────────────────────────────────────────────────────
-    // Diagnostics & Comparison
-    // ─────────────────────────────────────────────────────────────────────────
-    compare_ai_employees: async (args) => {
-        const env1 = args.env_1 ?? getDefaultEnvName();
-        const env2 = args.env_2 ?? env1;
-        const id1 = String(args.persona_id_1);
-        const id2 = String(args.persona_id_2);
-        const client1 = createClient(env1);
-        const client2 = env1 === env2 ? client1 : createClient(env2);
-        const [p1, p2] = await Promise.all([
-            client1.getPersonaById(id1),
-            client2.getPersonaById(id2),
-        ]);
-        if (!p1)
-            throw new Error(`AI Employee not found: ${id1} in ${env1}`);
-        if (!p2)
-            throw new Error(`AI Employee not found: ${id2} in ${env2}`);
-        const fp1 = fingerprintPersona(p1);
-        const fp2 = fingerprintPersona(p2);
-        const compareFields = ["name", "description", "status", "trigger_type", "access_level", "embedding_enabled", "template_id", "workflow_id"];
-        const differences = [];
-        for (const field of compareFields) {
-            const val1 = p1[field] ?? p1[field === "template_id" ? "templateId" : field];
-            const val2 = p2[field] ?? p2[field === "template_id" ? "templateId" : field];
-            if (JSON.stringify(val1) !== JSON.stringify(val2)) {
-                differences.push({ field, value_1: val1, value_2: val2 });
-            }
-        }
-        if (JSON.stringify(p1.proto_config ?? {}) !== JSON.stringify(p2.proto_config ?? {})) {
-            differences.push({ field: "proto_config", value_1: "(differs)", value_2: "(differs)" });
-        }
-        if (JSON.stringify(p1.welcome_messages ?? {}) !== JSON.stringify(p2.welcome_messages ?? {})) {
-            differences.push({ field: "welcome_messages", value_1: "(differs)", value_2: "(differs)" });
-        }
-        return {
-            persona_1: { id: id1, env: env1, name: p1.name, fingerprint: fp1 },
-            persona_2: { id: id2, env: env2, name: p2.name, fingerprint: fp2 },
-            fingerprints_match: fp1 === fp2,
-            difference_count: differences.length,
-            differences,
-        };
-    },
-    list_ai_employee_templates: async (args) => {
-        const client = createClient(args.env);
-        const personas = await client.getPersonasForTenant();
-        const templateMap = new Map();
-        for (const p of personas) {
-            const templateId = p.template_id ?? p.templateId ?? "unknown";
-            const existing = templateMap.get(templateId) ?? { count: 0, names: [] };
-            existing.count++;
-            if (p.name && existing.names.length < 3)
-                existing.names.push(p.name);
-            templateMap.set(templateId, existing);
-        }
-        const templates = Array.from(templateMap.entries())
-            .map(([template_id, data]) => ({ template_id, usage_count: data.count, examples: data.names }))
-            .sort((a, b) => b.usage_count - a.usage_count);
-        return {
-            environment: client["env"].name,
-            total_ai_employees: personas.length,
-            template_count: templates.length,
-            templates,
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // CONSOLIDATED SYNC HANDLERS
-    // ─────────────────────────────────────────────────────────────────────────
-    sync: async (args) => {
-        const targetEnv = String(args.target_env);
-        const sourceEnv = args.source_env ? String(args.source_env) : getDefaultEnvName();
-        const dryRun = args.dry_run === true;
-        const includeStatus = args.include_status === true;
-        const scope = args.scope === "all" ? "all" : "one";
-        const identifier = args.identifier ? String(args.identifier) : undefined;
-        // Sync all tagged personas
-        if (scope === "all" || !identifier) {
-            const sdk = getSyncSDK();
-            if (sdk) {
-                try {
-                    const result = await sdk.runSync();
-                    return { success: true, mode: "config", ...result };
-                }
-                finally {
-                    sdk.close();
-                }
-            }
-            // Config-less mode
-            try {
-                const result = await directSyncAll({ targetEnv, dryRun });
-                return { success: true, mode: "tags", ...result };
-            }
-            catch (e) {
-                return { success: false, error: e instanceof Error ? e.message : String(e) };
-            }
-        }
-        // Sync single persona
-        const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifier);
-        const behavior = resolveSyncBehavior({
-            personaName: isUUID ? undefined : identifier,
-            targetEnv,
-            overrides: {
-                dry_run: dryRun ? true : undefined,
-                sync_status: includeStatus ? true : undefined,
-            },
-        });
-        try {
-            const result = isUUID
-                ? await directSyncPersonaById({
-                    personaId: identifier,
-                    sourceEnv,
-                    targetEnv,
-                    dryRun: behavior.dry_run,
-                    syncStatus: behavior.sync_status,
-                })
-                : await directSyncPersona({
-                    name: identifier,
-                    sourceEnv,
-                    targetEnv,
-                    dryRun: behavior.dry_run,
-                    syncStatus: behavior.sync_status,
-                });
-            return { ...result, resolved_behavior: behavior };
-        }
-        catch (e) {
-            return { success: false, error: e instanceof Error ? e.message : String(e) };
-        }
-    },
-    sync_info: async (args) => {
-        const client = args.env ? createClient(args.env) : undefined;
-        // Check if persona is synced
-        if (args.persona_id) {
-            if (!client)
-                throw new Error("env required when checking persona sync status");
-            const personaId = String(args.persona_id);
-            const personas = await client.getPersonasForTenant();
-            const persona = personas.find((p) => p.id === personaId);
-            if (!persona)
-                throw new Error(`AI Employee not found: ${personaId}`);
-            const meta = client.getSyncMetadata(persona);
-            return {
-                environment: client["env"].name,
-                persona_id: personaId,
-                persona_name: persona.name,
-                is_synced: !!meta,
-                sync_metadata: meta,
-            };
-        }
-        // Check by persona name
-        if (args.persona_name) {
-            const sdk = getSyncSDK();
-            if (!sdk)
-                return { error: "No sync config found. Set EMA_AGENT_SYNC_CONFIG." };
-            try {
-                const persona = await sdk.getMasterPersonaByName(String(args.persona_name));
-                if (!persona)
-                    return { error: `Persona not found: ${args.persona_name}` };
-                return await sdk.getPersonaSyncStatus(persona.id);
-            }
-            finally {
-                sdk.close();
-            }
-        }
-        // List all synced personas
-        if (args.list_synced === true) {
-            if (!client)
-                throw new Error("env required when listing synced personas");
-            const personas = await client.getPersonasForTenant();
-            const masterEnvFilter = args.master_env ? String(args.master_env).toLowerCase() : undefined;
-            const synced = [];
-            for (const p of personas) {
-                const meta = client.getSyncMetadata(p);
-                if (meta) {
-                    if (masterEnvFilter && meta.master_env.toLowerCase() !== masterEnvFilter)
-                        continue;
-                    synced.push({ persona_id: p.id, persona_name: p.name, sync_metadata: meta });
-                }
-            }
-            return { environment: client["env"].name, count: synced.length, synced_personas: synced };
-        }
-        // Default: return overall sync config/status
-        const sdk = getSyncSDK();
-        const options = args.include_options === true ? loadSyncOptions() : undefined;
-        if (!sdk) {
-            return {
-                configured: false,
-                error: "No sync config found. Set EMA_AGENT_SYNC_CONFIG.",
-                options,
-            };
-        }
-        try {
-            const master = sdk.getMasterEnvironment();
-            const envs = sdk.getEnvironments();
-            const personas = await sdk.listMasterPersonas();
-            return {
-                configured: true,
-                master_environment: { name: master.name, url: master.baseUrl },
-                target_environments: envs.filter((e) => !e.isMaster).map((e) => ({ name: e.name, url: e.baseUrl })),
-                total_personas: personas.length,
-                options,
-            };
-        }
-        finally {
-            sdk.close();
-        }
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Auto Builder Knowledge Handlers
-    // ─────────────────────────────────────────────────────────────────────────────
-    list_auto_builder_agents: async (args) => {
-        const category = args.category;
-        const agents = category ? getAgentsByCategory(category) : AGENT_CATALOG;
-        return {
-            count: agents.length,
-            category: category ?? "all",
-            agents: agents.map(a => ({
-                action_name: a.actionName,
-                display_name: a.displayName,
-                category: a.category,
-                description: a.description,
-                when_to_use: a.whenToUse,
-                inputs: a.inputs.map(i => i.name),
-                outputs: a.outputs.map(o => o.name),
-                has_critical_rules: !!a.criticalRules?.length,
-            })),
-        };
-    },
-    get_auto_builder_agent: async (args) => {
-        const actionName = String(args.action_name);
-        const agent = getAgentByName(actionName);
-        if (!agent) {
-            const available = AGENT_CATALOG.slice(0, 15).map(a => a.actionName);
-            return {
-                error: `Agent not found: ${actionName}`,
-                available_examples: available,
-                hint: "Use list_auto_builder_agents to see all available agents",
-            };
-        }
-        return {
-            action_name: agent.actionName,
-            display_name: agent.displayName,
-            category: agent.category,
-            description: agent.description,
-            inputs: agent.inputs,
-            outputs: agent.outputs,
-            critical_rules: agent.criticalRules ?? [],
-            when_to_use: agent.whenToUse,
-            when_not_to_use: agent.whenNotToUse,
-            example: agent.example,
-        };
-    },
-    suggest_agents_for_use_case: async (args) => {
-        const useCase = String(args.use_case);
-        const suggestions = suggestAgentsForUseCase(useCase);
-        return {
-            use_case: useCase,
-            suggested_agent_count: suggestions.length,
-            suggested_agents: suggestions.map(a => ({
-                action_name: a.actionName,
-                display_name: a.displayName,
-                category: a.category,
-                why: a.whenToUse,
-                inputs: a.inputs.map(i => `${i.name} (${i.type})`),
-                outputs: a.outputs.map(o => `${o.name} (${o.type})`),
-            })),
-            suggested_flow: suggestions.map(a => a.actionName).join(" → "),
-            next_steps: [
-                "Use get_auto_builder_agent to get detailed info on each agent",
-                "Use get_workflow_pattern for a complete template if a pattern matches",
-                "Use get_qualifying_questions to ensure you have all required information",
-            ],
-        };
-    },
-    get_workflow_pattern: async (args) => {
-        const patternName = String(args.pattern_name);
-        const pattern = WORKFLOW_PATTERNS.find(p => p.name === patternName);
-        if (!pattern) {
-            return {
-                error: `Pattern not found: ${patternName}`,
-                available: WORKFLOW_PATTERNS.map(p => ({ name: p.name, description: p.description })),
-            };
-        }
-        return {
-            name: pattern.name,
-            persona_type: pattern.personaType,
-            description: pattern.description,
-            use_case: pattern.useCase,
-            nodes: pattern.nodes,
-            connections: pattern.connections,
-            anti_patterns: pattern.antiPatterns ?? [],
-            implementation_notes: [
-                "Replace * with actual category/handler names",
-                "All paths must lead to WORKFLOW_OUTPUT",
-                "Include Fallback category for categorizers",
-                "Check type compatibility for all connections",
-            ],
-        };
-    },
-    list_workflow_patterns: async (args) => {
-        const personaType = args.persona_type;
-        const patterns = personaType
-            ? WORKFLOW_PATTERNS.filter(p => p.personaType === personaType)
-            : WORKFLOW_PATTERNS;
-        return {
-            count: patterns.length,
-            persona_type_filter: personaType ?? "all",
-            patterns: patterns.map(p => ({
-                name: p.name,
-                persona_type: p.personaType,
-                description: p.description,
-                use_case: p.useCase,
-                node_count: p.nodes.length,
-            })),
-        };
-    },
-    check_type_compatibility: async (args) => {
-        const sourceType = String(args.source_type);
-        const targetType = String(args.target_type);
-        const compat = checkTypeCompatibility(sourceType, targetType);
-        if (!compat) {
-            return {
-                source_type: sourceType,
-                target_type: targetType,
-                compatible: false,
-                note: "No explicit compatibility rule found - likely incompatible",
-                recommendation: "Use an intermediate node to convert types, or check if target accepts WELL_KNOWN_TYPE_ANY",
-            };
-        }
-        return {
-            source_type: sourceType,
-            target_type: targetType,
-            compatible: compat.compatible,
-            note: compat.note,
-            recommendation: compat.compatible
-                ? "These types are compatible for direct connection"
-                : `Incompatible. ${compat.note || "Use an intermediate node to convert types."}`,
-        };
-    },
-    get_widget_reference: async (args) => {
-        const personaType = String(args.persona_type);
-        const widgets = getWidgetsForPersonaType(personaType);
-        const projectType = PROJECT_TYPES[personaType];
-        return {
-            persona_type: personaType,
-            project_type: projectType,
-            widget_count: widgets.length,
-            widgets: widgets.map(w => ({
-                id: w.id,
-                name: w.name,
-                description: w.description,
-                fields: w.fields,
-            })),
-            note: `Project type ${projectType} is used in proto_config for ${personaType} AI Employees`,
-        };
-    },
-    get_qualifying_questions: async (args) => {
-        const category = args.category;
-        const requiredOnly = args.required_only === true;
-        let questions = category
-            ? getQualifyingQuestionsByCategory(category)
-            : QUALIFYING_QUESTIONS;
-        if (requiredOnly) {
-            questions = questions.filter(q => q.required);
-        }
-        const grouped = questions.reduce((acc, q) => {
-            if (!acc[q.category])
-                acc[q.category] = [];
-            acc[q.category].push({ question: q.question, why_it_matters: q.whyItMatters, required: q.required });
-            return acc;
-        }, {});
-        return {
-            total_questions: questions.length,
-            categories: Object.keys(grouped),
-            questions_by_category: grouped,
-            minimum_required: [
-                "AI Type (Voice/Chat/Dashboard)",
-                "2-3 intent categories + Fallback",
-                "1 primary data source or action",
-                "Success output format",
-            ],
-            questioning_rounds: {
-                round_1: "Core Context: AI type, trigger, main intents, data sources",
-                round_2: "Workflow Details: Actions, validations, outputs, approvals",
-                round_3: "Voice/Chat Specifics: Welcome message, hangup conditions (if applicable)",
-            },
-        };
-    },
-    get_voice_persona_template: async () => {
-        // Use generated fallback from proto definitions
-        // In production, prefer API templates via client.getPersonaTemplates()
-        const template = getTemplateFallback("voice");
-        return {
-            template: template || VOICE_TEMPLATE_FALLBACK,
-            field_docs: getTemplateFieldDocs("voice"),
-            required_fields: ["conversationSettings.welcomeMessage", "conversationSettings.identityAndPurpose", "conversationSettings.takeActionInstructions", "conversationSettings.hangupInstructions"],
-            optional_fields: ["conversationSettings.transferCallInstructions", "conversationSettings.speechCharacteristics", "conversationSettings.systemPrompt", "conversationSettings.formFillingInstructions", "conversationSettings.waitMessage"],
-            project_type: PROJECT_TYPES.voice,
-            widget_ids: {
-                voiceSettings: 38,
-                conversationSettings: 39,
-                vadSettings: 43,
-                dataStorageSettings: 42,
-            },
-            _source: "generated_fallback",
-            _note: "This template is auto-generated from proto definitions. For live templates, use client.getPersonaTemplates().",
-        };
-    },
-    validate_workflow_prompt: async (args) => {
-        const prompt = String(args.prompt);
-        const result = validateWorkflowPrompt(prompt);
-        return {
-            valid: result.valid,
-            issue_count: result.issues.length,
-            warning_count: result.warnings.length,
-            issues: result.issues,
-            warnings: result.warnings,
-            recommendations: result.issues.length > 0 ? [
-                "Add Fallback category to all categorizers",
-                "Ensure HITL nodes have both success and failure paths",
-                "Map all response nodes to WORKFLOW_OUTPUT",
-                "Specify persona type (Voice AI, Chat AI, Dashboard AI)",
-                "Check type compatibility for all connections",
-            ] : ["Prompt structure looks valid - verify type compatibility after generation"],
-        };
-    },
-    get_auto_builder_guidance: async (args) => {
-        const topic = String(args.topic);
-        const guidance = GUIDANCE_TOPICS[topic];
-        if (!guidance) {
-            return {
-                error: `Topic not found: ${topic}`,
-                available_topics: Object.keys(GUIDANCE_TOPICS).map(k => ({
-                    topic: k,
-                    title: GUIDANCE_TOPICS[k].title,
-                })),
-            };
-        }
-        return guidance;
-    },
-    get_platform_concept: async (args) => {
-        const term = String(args.term);
-        const concept = getConceptByTerm(term);
-        if (!concept) {
-            return {
-                error: `Concept not found: ${term}`,
-                available_concepts: PLATFORM_CONCEPTS.map(c => c.term),
-                hint: "Try searching for aliases like 'Persona' (AI Employee) or 'Action' (Agent)",
-            };
-        }
-        return {
-            term: concept.term,
-            definition: concept.definition,
-            aliases: concept.aliases ?? [],
-            related_terms: concept.relatedTerms ?? [],
-            examples: concept.examples ?? [],
-            common_confusions: concept.commonConfusions,
-        };
-    },
-    list_platform_concepts: async () => {
-        return {
-            count: PLATFORM_CONCEPTS.length,
-            concepts: PLATFORM_CONCEPTS.map(c => ({
-                term: c.term,
-                definition: c.definition,
-                aliases: c.aliases ?? [],
-            })),
-            key_relationships: [
-                "AI Employee CONTAINS Workflow (processing logic) + Persona (conversational behavior)",
-                "Workflow is made up of Agents/Actions connected by Edges",
-                "Agents use Connectors to interact with external systems",
-                "HITL = Human-in-the-Loop approval/verification step",
-            ],
-        };
-    },
-    get_common_mistakes: async () => {
-        return {
-            count: COMMON_MISTAKES.length,
-            mistakes: COMMON_MISTAKES,
-            top_3_critical: [
-                COMMON_MISTAKES.find(m => m.mistake.includes("Fallback")),
-                COMMON_MISTAKES.find(m => m.mistake.includes("HITL")),
-                COMMON_MISTAKES.find(m => m.mistake.includes("duplicate")),
-            ].filter(Boolean),
-        };
-    },
-    get_debug_checklist: async () => {
-        return {
-            total_steps: DEBUG_CHECKLIST.length,
-            checklist: DEBUG_CHECKLIST,
-            quick_checks: [
-                "Is the AI Employee status 'active' or 'ready'?",
-                "Does the categorizer have all category edges including Fallback?",
-                "Do all paths lead to WORKFLOW_OUTPUT?",
-                "Are all connections type-compatible?",
-            ],
-        };
-    },
-    get_workflow_execution_model: async () => {
-        return {
-            ...WORKFLOW_EXECUTION_MODEL,
-            summary: "Each user message triggers a NEW workflow execution. Use chat_conversation to detect previous actions and avoid duplicates.",
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Workflow Review & Audit Handlers
-    // ─────────────────────────────────────────────────────────────────────────────
-    analyze_workflow: async (args) => {
-        // DEPRECATED: MCP no longer pre-analyzes workflows
-        // LLM should use ema://rules/* for analysis
-        const client = createClient(args.env);
-        const personaId = String(args.persona_id);
-        const persona = await client.getPersonaById(personaId);
-        if (!persona)
-            throw new Error(`AI Employee not found: ${personaId}`);
-        const nodes = persona.workflow_def ? parseWorkflowDef(persona.workflow_def) : [];
-        const connections = persona.workflow_def ? validateWorkflowConnections(persona.workflow_def) : [];
-        return {
-            environment: client["env"].name,
-            persona_id: personaId,
-            persona_name: persona.name,
-            status: "DEPRECATED - use LLM analysis",
-            node_count: nodes.length,
-            workflow_def: persona.workflow_def,
-            connections: connections.map(c => ({
-                edge: c.edge_id,
-                source_type: c.source_type,
-                target_type: c.target_type,
-                compatible: c.compatible,
-            })),
-            _deprecation_notice: {
-                message: "analyze_workflow is deprecated. MCP does not pre-compute issues.",
-                new_workflow: [
-                    "1. Fetch rules: ema://rules/anti-patterns",
-                    "2. Apply rules to find issues (LLM does this, not MCP)",
-                    "3. Report your findings",
-                ],
-            },
-        };
-    },
-    detect_workflow_issues: async (args) => {
-        // DEPRECATED: MCP no longer detects workflow issues
-        // LLM should use ema://rules/* for analysis
-        const workflowDef = args.workflow_def;
-        if (!workflowDef || typeof workflowDef !== "object") {
-            return {
-                error: "Invalid workflow_def - must be an object",
-                hint: "Get workflow_def from get_ai_employee_full(persona_id).ai_employee.workflow_def",
-            };
-        }
-        const nodes = parseWorkflowDef(workflowDef);
-        return {
-            status: "DEPRECATED - use LLM analysis",
-            node_count: nodes.length,
-            nodes: nodes.map(n => ({ id: n.id, action: n.action_name })),
-            _deprecation_notice: {
-                message: "detect_workflow_issues is deprecated. MCP does not pre-compute issues.",
-                new_workflow: [
-                    "1. Fetch rules: ema://rules/anti-patterns",
-                    "2. Apply rules to this workflow (LLM does this)",
-                    "3. Report issues YOU find",
-                ],
-            },
-        };
-    },
-    validate_workflow_connections: async (args) => {
-        const workflowDef = args.workflow_def;
-        if (!workflowDef || typeof workflowDef !== "object") {
-            return {
-                error: "Invalid workflow_def - must be an object",
-                hint: "Get workflow_def from get_ai_employee_full(persona_id).ai_employee.workflow_def",
-            };
-        }
-        const validations = validateWorkflowConnections(workflowDef);
-        const compatible = validations.filter(v => v.compatible);
-        const incompatible = validations.filter(v => !v.compatible);
-        return {
-            total_edges: validations.length,
-            compatible_count: compatible.length,
-            incompatible_count: incompatible.length,
-            all_valid: incompatible.length === 0,
-            validations: validations.map(v => ({
-                edge: v.edge_id,
-                source_type: v.source_type,
-                target_type: v.target_type,
-                compatible: v.compatible,
-                note: v.note,
-            })),
-            incompatible_edges: incompatible.map(v => ({
-                edge: v.edge_id,
-                source_type: v.source_type,
-                target_type: v.target_type,
-                note: v.note,
-                fix_hint: v.source_type === "WELL_KNOWN_TYPE_CHAT_CONVERSATION" && v.target_type === "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES"
-                    ? "Insert conversation_to_search_query between source and target"
-                    : "Use named_inputs (accepts ANY type) or add intermediate conversion node",
-            })),
-        };
-    },
-    suggest_workflow_fixes: async (_args) => {
-        // DEPRECATED: MCP no longer suggests fixes
-        // LLM should reason about fixes using ema://rules/*
-        return {
-            status: "DEPRECATED - use LLM reasoning",
-            _deprecation_notice: {
-                message: "suggest_workflow_fixes is deprecated. LLM should propose fixes.",
-                new_workflow: [
-                    "1. Get workflow: workflow(mode='get', persona_id='...')",
-                    "2. Analyze with ema://rules/anti-patterns",
-                    "3. LLM modifies workflow_def to fix issues",
-                    "4. Deploy: workflow(mode='deploy', persona_id='...', workflow_def={...})",
-                ],
-            },
-        };
-    },
-    compare_workflow_versions: async (args) => {
-        // DEPRECATED: MCP no longer pre-analyzes for comparison
-        // LLM should compare workflows directly
-        const client = createClient(args.env);
-        const idBefore = String(args.persona_id_before);
-        const idAfter = String(args.persona_id_after);
-        const [personaBefore, personaAfter] = await Promise.all([
-            client.getPersonaById(idBefore),
-            client.getPersonaById(idAfter),
-        ]);
-        if (!personaBefore)
-            throw new Error(`AI Employee not found (before): ${idBefore}`);
-        if (!personaAfter)
-            throw new Error(`AI Employee not found (after): ${idAfter}`);
-        const nodesBefore = personaBefore.workflow_def ? parseWorkflowDef(personaBefore.workflow_def) : [];
-        const nodesAfter = personaAfter.workflow_def ? parseWorkflowDef(personaAfter.workflow_def) : [];
-        // Compare fingerprints
-        const fpBefore = personaBefore.workflow_def ? fingerprintPersona(personaBefore) : null;
-        const fpAfter = personaAfter.workflow_def ? fingerprintPersona(personaAfter) : null;
-        return {
-            environment: client["env"].name,
-            status: "DEPRECATED - LLM should compare",
-            before: {
-                persona_id: idBefore,
-                name: personaBefore.name,
-                fingerprint: fpBefore,
-                has_workflow: !!personaBefore.workflow_def,
-                node_count: nodesBefore.length,
-                workflow_def: personaBefore.workflow_def,
-            },
-            after: {
-                persona_id: idAfter,
-                name: personaAfter.name,
-                fingerprint: fpAfter,
-                has_workflow: !!personaAfter.workflow_def,
-                node_count: nodesAfter.length,
-                workflow_def: personaAfter.workflow_def,
-            },
-            comparison: {
-                fingerprints_match: fpBefore === fpAfter,
-                node_count_change: nodesAfter.length - nodesBefore.length,
-            },
-            _deprecation_notice: {
-                message: "compare_workflow_versions is deprecated. LLM should compare workflows directly.",
-                guidance: "Compare the workflow_def objects returned above. Use ema://rules/anti-patterns to check each.",
-            },
-        };
-    },
-    get_workflow_metrics: async (args) => {
-        const client = createClient(args.env);
-        const personaId = String(args.persona_id);
-        const persona = await client.getPersonaById(personaId);
-        if (!persona)
-            throw new Error(`AI Employee not found: ${personaId}`);
-        if (!persona.workflow_def) {
-            return {
-                environment: client["env"].name,
-                persona_id: personaId,
-                persona_name: persona.name,
-                error: "AI Employee has no workflow_def",
-            };
-        }
-        const nodes = parseWorkflowDef(persona.workflow_def);
-        const connections = validateWorkflowConnections(persona.workflow_def);
-        // Calculate basic metrics
-        const totalEdges = nodes.reduce((sum, n) => sum + (n.incoming_edges?.length ?? 0), 0);
-        const avgEdgesPerNode = nodes.length > 0
-            ? (totalEdges / nodes.length).toFixed(2)
-            : 0;
-        // Check for categorizers and HITL
-        const categorizerCount = nodes.filter(n => n.action_name?.includes("categorizer")).length;
-        const hitlCount = nodes.filter(n => n.action_name?.includes("hitl") || n.id?.includes("hitl")).length;
-        const hasTrigger = nodes.some(n => n.action_name === "trigger" || n.id === "trigger");
-        return {
-            environment: client["env"].name,
-            persona_id: personaId,
-            persona_name: persona.name,
-            structure: {
-                total_nodes: nodes.length,
-                total_edges: totalEdges,
-                has_trigger: hasTrigger,
-                connection_count: connections.length,
-            },
-            routing: {
-                categorizers_count: categorizerCount,
-                hitl_nodes_count: hitlCount,
-                has_parallel_branches: categorizerCount > 0,
-            },
-            complexity: {
-                avg_edges_per_node: avgEdgesPerNode,
-                complexity_rating: nodes.length <= 5 ? "simple"
-                    : nodes.length <= 15 ? "moderate"
-                        : "complex",
-            },
-            _note: "Use ema://rules/anti-patterns for quality analysis. MCP no longer pre-computes issues.",
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Workflow Compilation (Template-driven)
-    // ─────────────────────────────────────────────────────────────────────────
-    compile_workflow: async (args) => {
-        const name = String(args.name);
-        const description = String(args.description);
-        const personaType = String(args.persona_type);
-        const rawNodes = args.nodes;
-        const rawResultMappings = args.result_mappings;
-        if (!["voice", "chat", "dashboard"].includes(personaType)) {
-            throw new Error(`Invalid persona_type: ${personaType}. Must be one of: voice, chat, dashboard`);
-        }
-        if (!rawNodes || rawNodes.length === 0) {
-            throw new Error("At least one node is required");
-        }
-        if (!rawResultMappings || rawResultMappings.length === 0) {
-            throw new Error("At least one result_mapping is required to connect outputs to WORKFLOW_OUTPUT");
-        }
-        // Convert raw input spec to internal Node format
-        const nodes = rawNodes.map((rawNode) => {
-            const node = {
-                id: rawNode.id,
-                actionType: rawNode.action_type,
-                displayName: rawNode.display_name,
-                description: rawNode.description,
-                disableHitl: rawNode.disable_hitl,
-            };
-            // Convert inputs
-            if (rawNode.inputs) {
-                node.inputs = {};
-                for (const [key, rawBinding] of Object.entries(rawNode.inputs)) {
-                    const binding = {
-                        type: rawBinding.type,
-                        actionName: rawBinding.action_name,
-                        output: rawBinding.output,
-                        value: rawBinding.value,
-                        widgetName: rawBinding.widget_name,
-                    };
-                    node.inputs[key] = binding;
-                }
-            }
-            // Convert run_if condition
-            if (rawNode.run_if) {
-                node.runIf = {
-                    sourceAction: rawNode.run_if.source_action,
-                    sourceOutput: rawNode.run_if.source_output,
-                    operator: rawNode.run_if.operator,
-                    value: rawNode.run_if.value,
-                };
-            }
-            // Convert categories
-            if (rawNode.categories) {
-                node.categories = rawNode.categories.map((cat) => ({
-                    name: cat.name,
-                    description: cat.description,
-                    examples: cat.examples,
-                }));
-            }
-            // Convert tools
-            if (rawNode.tools) {
-                node.tools = rawNode.tools.map((tool) => ({
-                    name: tool.name,
-                    namespace: tool.namespace,
-                }));
-            }
-            return node;
-        });
-        // Convert result mappings
-        const resultMappings = rawResultMappings.map((rm) => ({
-            nodeId: rm.node_id,
-            output: rm.output,
-        }));
-        // Build the WorkflowSpec
-        const spec = {
-            name,
-            description,
-            personaType,
-            nodes,
-            resultMappings,
-        };
-        // Compile the workflow
-        const result = compileWorkflow(spec);
-        return {
-            success: true,
-            message: `Compiled workflow for ${personaType} AI Employee "${name}" with ${nodes.length} nodes`,
-            workflow_def: result.workflow_def,
-            proto_config: result.proto_config,
-            nodes_compiled: nodes.map((n) => ({ id: n.id, action: n.actionType, display_name: n.displayName })),
-            result_mappings: resultMappings,
-            usage: 'Deploy with: workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>)',
-            _tip: 'Stale-state protection is strict: call workflow(mode="get") immediately before deploy and pass base_fingerprint from the response. For large payloads, use workflow_def_path.',
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Data Source / Embedding Management
-    // Delegates to extracted handler in ./handlers/data/index.js
-    // TODO: Add support for 3rd party data sources (Google Drive, SharePoint, Confluence, etc.)
-    // ─────────────────────────────────────────────────────────────────────────
-    upload_data_source: async (args) => {
-        const client = createClient(args.env);
-        const fs = await import("fs/promises");
-        const { handleData } = await import("./handlers/data/index.js");
-        return handleData({ persona_id: String(args.persona_id), data: { method: "upload", path: String(args.file_path) } }, client, (path) => fs.readFile(path));
-    },
-    delete_data_source: async (args) => {
-        const client = createClient(args.env);
-        const { handleData } = await import("./handlers/data/index.js");
-        return handleData({ persona_id: String(args.persona_id), data: { method: "delete", file_id: String(args.file_id) } }, client);
-    },
-    list_data_sources: async (args) => {
-        const client = createClient(args.env);
-        const { handleData } = await import("./handlers/data/index.js");
-        return handleData({ persona_id: String(args.persona_id), method: "list" }, client);
-    },
-    get_embedding_status: async (args) => {
-        const client = createClient(args.env);
-        const { handleData } = await import("./handlers/data/index.js");
-        return handleData({ persona_id: String(args.persona_id), data: { method: "embedding" } }, client);
-    },
-    toggle_embedding: async (args) => {
-        const client = createClient(args.env);
-        const { handleData } = await import("./handlers/data/index.js");
-        return handleData({ persona_id: String(args.persona_id), data: { method: "embedding", enabled: Boolean(args.enabled) } }, client);
-    },
-    // ─────────────────────────────────────────────────────────────────────────
-    // Demo Data Management Handlers
-    // ─────────────────────────────────────────────────────────────────────────
-    consolidate_demo_data: async (args) => {
-        return handleConsolidateDemoData(args);
-    },
-    generate_demo_document: async (args) => {
-        return handleGenerateDemoDocument(args);
-    },
-    validate_demo_document: async (args) => {
-        return handleValidateDemoDocument(args);
-    },
-    get_demo_data_template: async (args) => {
-        return handleGetDemoDataTemplate(args);
-    },
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// V2 TOOLS (7 tools) - LLM-optimized minimal interface
+//   - env, persona, catalog, workflow, sync, toolkit_feedback, debug
+//   - Defined in: ./tools.ts
+//
+// NAMING CONVENTION:
+// - Tool names are defined as BASE NAMES (e.g., "persona")
+// - MCP clients prefix with "mcp_{server}_" (e.g., "mcp_ema_persona")
+//
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate all available tools
+ *
+ * V2: 7 tools (persona, catalog, workflow, sync, env, toolkit_feedback, debug) - LLM-optimized
+ *
+ * Why V2:
+ * - Minimal tool count optimizes LLM tool selection
+ * - Data operations under persona (always persona-scoped)
+ * - Catalog consolidates all reference data (actions, templates, etc.)
+ * - Clear separation: entity (persona), reference (catalog), operation (sync, workflow)
+ */
+function generateAllTools() {
+    const envNames = getAvailableEnvironments().map(e => e.name);
+    const defaultEnv = getDefaultEnvName();
+    return generateTools(envNames, defaultEnv);
+}
+// Generate tools (called once at module load)
+const TOOLS = generateAllTools();
+const toolHandlers = {
     // ═══════════════════════════════════════════════════════════════════════════
-    // CONSOLIDATED TOOLS (Unix CLI pattern) - 9 tools replace 45
+    // V2 TOOLS — LLM-optimized interface
     // ═══════════════════════════════════════════════════════════════════════════
     env: async () => {
         return handleEnv({}, () => getAvailableEnvironments().map(e => ({
@@ -2164,224 +84,7 @@ const toolHandlers = {
         })), { name: TOOLKIT_NAME, version: TOOLKIT_VERSION, commit: TOOLKIT_COMMIT });
     },
     persona: async (args) => {
-        const targetEnv = args.env ?? getDefaultEnvName();
-        const client = createClient(targetEnv);
-        // Build version context for version management modes
-        const versionContext = {
-            // Store versions in the caller's workspace, not the toolkit install dir.
-            // This must be writable under typical MCP usage (e.g. Cursor workspace).
-            workspaceRoot: process.cwd(),
-            environment: targetEnv,
-            tenant_id: targetEnv, // Use env name as tenant identifier
-        };
-        // ─────────────────────────────────────────────────────────────────────────
-        // V2 Parameter Transformation
-        // Convert v2 structure to v1 mode-based structure for handler compatibility
-        // ─────────────────────────────────────────────────────────────────────────
-        const transformedArgs = { ...args };
-        // ─────────────────────────────────────────────────────────────────────────
-        // Explicit Method API (takes priority over flag-based args)
-        // persona(method="create|get|list|update|delete|sanitize|analyze|compare|clone")
-        // ─────────────────────────────────────────────────────────────────────────
-        if (args.method) {
-            const method = String(args.method);
-            // Map explicit methods to internal modes
-            const methodToMode = {
-                create: "create",
-                get: "get",
-                list: "list",
-                update: "update",
-                delete: "delete",
-                sanitize: "sanitize",
-                analyze: "analyze",
-                compare: "compare",
-                schema: "schema", // get persona input schema (dashboard columns)
-                clone: "create", // clone is create with from
-                snapshot: "version_create",
-                history: "version_list",
-                restore: "version_restore",
-            };
-            const mode = methodToMode[method];
-            if (!mode) {
-                return { error: `Unknown method: ${method}`, valid_methods: Object.keys(methodToMode) };
-            }
-            transformedArgs.mode = mode;
-            delete transformedArgs.method;
-            // Handle action composition if present
-            if (args.actions && Array.isArray(args.actions)) {
-                // Store actions for post-processing after main operation
-                transformedArgs._actions = args.actions;
-                delete transformedArgs.actions;
-            }
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // Flag-based API (legacy compatibility)
-        // ONLY applies when explicit `method` parameter was NOT provided
-        // When method is explicit, flags like sanitize=true are passed through
-        // ─────────────────────────────────────────────────────────────────────────
-        // Guard: Skip flag-based API if explicit method was provided
-        const skipFlagBasedApi = !!args.method;
-        // Create: persona(create={name, type, from, input})
-        if (!skipFlagBasedApi && args.create && typeof args.create === "object") {
-            const create = args.create;
-            transformedArgs.mode = "create";
-            transformedArgs.name = create.name;
-            transformedArgs.type = create.type;
-            transformedArgs.from = create.from;
-            transformedArgs.input = create.input;
-            transformedArgs.preview = create.preview ?? true;
-            delete transformedArgs.create;
-        }
-        // Update: persona(id, update={config, input, workflow_spec})
-        else if (!skipFlagBasedApi && args.update && typeof args.update === "object") {
-            const update = args.update;
-            transformedArgs.mode = "update";
-            transformedArgs.proto_config = update.config;
-            transformedArgs.input = update.input;
-            transformedArgs.workflow_spec = update.workflow_spec;
-            transformedArgs.preview = update.preview ?? false; // Default to deploy, not preview
-            delete transformedArgs.update;
-        }
-        // Delete: persona(id, delete=true)
-        else if (!skipFlagBasedApi && args.delete === true) {
-            transformedArgs.mode = "delete";
-            delete transformedArgs.delete;
-        }
-        // Analyze: persona(id, analyze=true, fix=true)
-        else if (!skipFlagBasedApi && args.analyze === true) {
-            transformedArgs.mode = "analyze";
-            // fix is already in args
-            delete transformedArgs.analyze;
-        }
-        // Sanitize: persona(id, sanitize=true)
-        // ONLY converts to mode="sanitize" when method is NOT explicit
-        // When method="create" + sanitize=true, sanitize is a FLAG for post-creation sanitization
-        else if (!skipFlagBasedApi && args.sanitize === true) {
-            transformedArgs.mode = "sanitize";
-            delete transformedArgs.sanitize;
-        }
-        // Snapshot: persona(id, snapshot="message")
-        else if (!skipFlagBasedApi && typeof args.snapshot === "string") {
-            transformedArgs.mode = "version_create";
-            transformedArgs.message = args.snapshot;
-            delete transformedArgs.snapshot;
-        }
-        // History: persona(id, history=true)
-        else if (!skipFlagBasedApi && args.history === true) {
-            transformedArgs.mode = "version_list";
-            delete transformedArgs.history;
-        }
-        // Restore: persona(id, restore="v3")
-        else if (!skipFlagBasedApi && typeof args.restore === "string") {
-            transformedArgs.mode = "version_restore";
-            transformedArgs.version = args.restore;
-            delete transformedArgs.restore;
-        }
-        // Compare: persona(id, compare="other-id")
-        else if (!skipFlagBasedApi && typeof args.compare === "string") {
-            transformedArgs.mode = "compare";
-            transformedArgs.compare_to = args.compare;
-            delete transformedArgs.compare;
-        }
-        // Data operations: persona(id, data={method:"...", ...})
-        // Supports both explicit method format and legacy flag format
-        else if (args.data && typeof args.data === "object") {
-            const data = args.data;
-            const personaId = args.id;
-            const fs = await import("fs/promises");
-            // EXPLICIT METHOD FORMAT (preferred): data={method:"list/stats/upload/copy/replicate/delete/search/refresh/regenerate/replace"}
-            if (typeof data.method === "string") {
-                // Import the new data handler - pass data object as part of args
-                const { handleData: handleDataNew } = await import("./handlers/data/index.js");
-                return handleDataNew({ persona_id: personaId, env: args.env, data }, client);
-            }
-            // LEGACY FLAG FORMAT (backwards compatibility) - use extracted handler
-            const { handleData: handleDataExtracted } = await import("./handlers/data/index.js");
-            const readFileFn = (path) => fs.readFile(path);
-            if (data.list === true) {
-                return handleDataExtracted({ method: "list", persona_id: personaId, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.upload === "string") {
-                return handleDataExtracted({ method: "upload", persona_id: personaId, data: { path: data.upload }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.delete === "string") {
-                return handleDataExtracted({ method: "delete", persona_id: personaId, data: { file_id: data.delete }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.generate === "string" || data.template) {
-                return handleDataExtracted({
-                    method: "generate",
-                    persona_id: personaId,
-                    data: {
-                        input: data.generate,
-                        from: data.template,
-                        count: data.count,
-                    },
-                    env: args.env
-                }, client, readFileFn);
-            }
-            if (typeof data.embed === "boolean") {
-                return handleDataExtracted({ method: "embedding", persona_id: personaId, data: { enabled: data.embed }, env: args.env }, client, readFileFn);
-            }
-            if (typeof data.search === "string") {
-                return handleKnowledge({ mode: "search", persona_id: personaId, query: data.search, env: args.env }, client, (path) => fs.readFile(path));
-            }
-            return {
-                error: "Unknown data operation",
-                hint: "Use data={method:'list'} format (explicit method)",
-                available_methods: ["list", "stats", "upload", "copy", "replicate", "delete", "search", "refresh", "regenerate", "replace"],
-                legacy_flags: ["list", "upload", "delete", "generate", "embed", "search"],
-            };
-        }
-        // Get: persona(id) with no mutation flags
-        else if (args.id && !transformedArgs.mode) {
-            transformedArgs.mode = "get";
-        }
-        // List: persona() or persona(type, status, query) with no id
-        else if (!args.id && !transformedArgs.mode) {
-            transformedArgs.mode = "list";
-        }
-        // Templates are tenant-specific - don't use hardcoded IDs
-        // The handler will use dynamic template lookup from API
-        const result = await handlePersona(transformedArgs, client, () => undefined, // Dynamic lookup in handler
-        (env) => createClient(env), versionContext);
-        // ─────────────────────────────────────────────────────────────────────────
-        // Action Composition Post-Processing
-        // Execute actions array after main operation completes
-        // ─────────────────────────────────────────────────────────────────────────
-        const actions = transformedArgs._actions;
-        if (actions && actions.length > 0) {
-            // Get the target persona ID from result
-            const resultObj = result;
-            const targetId = resultObj.id ??
-                resultObj.persona_id;
-            const sourceId = args.from;
-            if (!targetId) {
-                return {
-                    ...(typeof result === "object" && result !== null ? result : {}),
-                    _actions_error: "No persona ID available for action execution",
-                };
-            }
-            // Import and execute actions
-            const actionExecutor = await import("./handlers/action-executor.js");
-            const context = {
-                source: sourceId,
-                target: targetId,
-                env: targetEnv,
-                originalArgs: args,
-            };
-            const actionsResult = await actionExecutor.executeActions(actions, context, client);
-            return {
-                ...(typeof result === "object" && result !== null ? result : {}),
-                _actions: actionsResult,
-            };
-        }
-        return result;
-    },
-    // Consolidated workflow handler (replaces legacy inline handler)
-    workflow: async (args) => {
-        const client = createClient(args.env);
-        // Templates are tenant-specific - dynamic lookup in handler
-        return handleWorkflow(args, client, () => undefined);
+        return handlePersonaAdapter(args, createClient, getDefaultEnvName);
     },
     action: async (args) => {
         const client = createClient(args.env);
@@ -2390,12 +93,6 @@ const toolHandlers = {
     template: async (args) => {
         return handleTemplate(args);
     },
-    knowledge: async (args) => {
-        const client = createClient(args.env);
-        const fs = await import("fs/promises");
-        return handleKnowledge(args, client, (path) => fs.readFile(path));
-    },
-    // v2: data is an alias for knowledge with simplified interface
     data: async (args) => {
         const client = createClient(args.env);
         const fs = await import("fs/promises");
@@ -2419,464 +116,30 @@ const toolHandlers = {
             client,
         });
     },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // V2 TOOLS (4 tools: persona, catalog, sync, env)
-    // ═══════════════════════════════════════════════════════════════════════════
     // catalog: Consolidated reference data (actions, templates, widgets, voices, patterns, concepts)
     catalog: async (args) => {
         const client = createClient(args.env);
         return handleCatalog(args, client);
     },
-    // Note: 'sync' handler already exists above - keeping it for full functionality
-    // Note: demo is handled via a consolidated adapter below
     // toolkit_feedback: Agent feedback collection and analysis
     toolkit_feedback: async (args) => {
         return handleFeedback(args);
     },
+    // V2 adapters — routing + transformation extracted to handler files
+    workflow: async (args) => {
+        return handleWorkflowAdapter(args, createClient, getDefaultEnvName);
+    },
+    sync: async (args) => {
+        return handleSyncAdapter(args, createClient, getDefaultEnvName, getSyncSDK);
+    },
+    demo: async (args) => {
+        return handleDemoAdapter(args, createClient);
+    },
+    debug: async (args) => {
+        return handleDebugAdapter(args, createClient, getDefaultEnvName);
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
-// V2 Tool Adapters (contract ↔ implementation)
-// ─────────────────────────────────────────────────────────────────────────────
-//
-// The tool schemas in tools.ts are the public MCP contract.
-// This file still contains proven handlers that we reuse
-// (e.g. deploy_workflow, optimize_workflow, compile_workflow, etc.).
-//
-// These adapters ensure the V2 tool surface behaves as documented,
-// while preserving the existing internal implementations.
-const legacyWorkflowTool = toolHandlers.workflow;
-const legacyDeployWorkflow = toolHandlers.deploy_workflow;
-const legacyOptimizeWorkflow = toolHandlers.optimize_workflow;
-const legacyCompareWorkflowVersions = toolHandlers.compare_workflow_versions;
-const legacyCompileWorkflow = toolHandlers.compile_workflow;
-const legacyDetectWorkflowIssues = toolHandlers.detect_workflow_issues;
-const legacyValidateWorkflowConnections = toolHandlers.validate_workflow_connections;
-const legacySuggestWorkflowFixes = toolHandlers.suggest_workflow_fixes;
-const legacySyncRun = toolHandlers.sync;
-const legacySyncInfo = toolHandlers.sync_info;
-const legacyConsolidateDemoData = toolHandlers.consolidate_demo_data;
-const legacyGenerateDemoDocument = toolHandlers.generate_demo_document;
-const legacyValidateDemoDocument = toolHandlers.validate_demo_document;
-const legacyGetDemoDataTemplate = toolHandlers.get_demo_data_template;
-// Workflow tool: MCP provides data (get) and executes (deploy). LLM does all thinking.
-toolHandlers.workflow = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
-    let workflowDef = normalizedArgs.workflow_def;
-    const workflowDefPath = normalizedArgs.workflow_def_path;
-    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
-    const baseFingerprint = normalizedArgs.base_fingerprint;
-    const force = normalizedArgs.force;
-    // For deploy: resolve workflow_def from file when workflow_def_path is provided (large payloads)
-    // Also handle the common agent mistake: passing {"workflow_def_path": "/path"} as workflow_def
-    // (happens when the agent's tool schema doesn't expose workflow_def_path as a separate param)
-    let effectivePath = workflowDefPath;
-    if (mode === "deploy" && workflowDef && !effectivePath) {
-        const keys = Object.keys(workflowDef);
-        if (keys.length === 1 && keys[0] === "workflow_def_path" && typeof workflowDef.workflow_def_path === "string") {
-            effectivePath = workflowDef.workflow_def_path;
-            workflowDef = undefined;
-        }
-    }
-    if (mode === "deploy" && !workflowDef && effectivePath) {
-        try {
-            // Guardrails: reduce risk of accidental secret exfiltration
-            const path = await import("path");
-            if (!path.isAbsolute(effectivePath)) {
-                return { error: "workflow_def_path must be an absolute path on the MCP server host", path: effectivePath };
-            }
-            if (!effectivePath.toLowerCase().endsWith(".json")) {
-                return { error: "workflow_def_path must point to a .json file", path: effectivePath };
-            }
-            const fs = await import("fs/promises");
-            const stat = await fs.stat(effectivePath);
-            const MAX_WORKFLOW_DEF_BYTES = 1024 * 1024; // 1MB
-            if (stat.size > MAX_WORKFLOW_DEF_BYTES) {
-                return { error: `workflow_def_path file too large (${stat.size} bytes)`, max_bytes: MAX_WORKFLOW_DEF_BYTES, path: effectivePath };
-            }
-            const raw = await fs.readFile(effectivePath, "utf-8");
-            const parsed = JSON.parse(raw);
-            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-                workflowDef = parsed;
-            }
-            else {
-                return { error: "workflow_def_path must point to a JSON object", path: effectivePath };
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return { error: `Failed to read workflow_def from path: ${msg}`, path: effectivePath };
-        }
-    }
-    // Route to handleWorkflow for get/deploy (the only public modes)
-    const client = createClient(normalizedArgs.env);
-    switch (mode) {
-        case "get": {
-            // Return workflow data for LLM to analyze/modify
-            return handleWorkflow({
-                mode: "get",
-                persona_id: personaId,
-                env: normalizedArgs.env,
-            }, client, () => undefined);
-        }
-        case "validate": {
-            // Static validation with path enumeration
-            return handleWorkflow({
-                mode: "validate",
-                persona_id: personaId,
-                workflow_def: normalizedArgs.workflow_def,
-                workflow_spec: normalizedArgs.workflow_spec,
-                validation_type: normalizedArgs.validation_type,
-                max_paths: normalizedArgs.max_paths,
-                timeout_ms: normalizedArgs.timeout_ms,
-                env: normalizedArgs.env,
-            }, client, () => undefined);
-        }
-        case "deploy": {
-            if (!personaId) {
-                return { error: 'persona_id is required for workflow(mode="deploy")' };
-            }
-            // Pre-deploy snapshot + stale-state protection (out-of-band changes)
-            const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
-            let versionCreated;
-            try {
-                const personaBefore = await client.getPersonaById(personaId);
-                if (!personaBefore) {
-                    return { error: `Persona not found: ${personaId}` };
-                }
-                const currentFp = fingerprintPersona(personaBefore);
-                if (!force && !baseFingerprint) {
-                    return {
-                        error: "base_fingerprint is required for workflow deploy (stale-state protection)",
-                        persona_id: personaId,
-                        current_fingerprint: currentFp,
-                        hint: "Run workflow(mode='get', persona_id='...') immediately before deploying and pass fingerprint as base_fingerprint. Use force=true only for emergency overrides.",
-                    };
-                }
-                if (!force && baseFingerprint && baseFingerprint !== currentFp) {
-                    return {
-                        error: "Persona changed since you last fetched it (fingerprint mismatch)",
-                        persona_id: personaId,
-                        base_fingerprint: baseFingerprint,
-                        current_fingerprint: currentFp,
-                        hint: "Re-run workflow(mode='get') to fetch the latest workflow_def, re-apply your edits, then deploy again. Use force=true only if you intend to overwrite out-of-band changes.",
-                    };
-                }
-                const storage = createVersionStorage(process.cwd());
-                const engine = createVersionPolicyEngine(storage);
-                const snap = engine.forceCreateVersion(personaBefore, {
-                    environment: targetEnv,
-                    tenant_id: targetEnv,
-                    message: "Pre-deploy snapshot",
-                    created_by: "mcp-toolkit",
-                });
-                if (!snap.created || !snap.version) {
-                    if (!force) {
-                        return {
-                            error: "Failed to create pre-deploy snapshot (required before deploy)",
-                            persona_id: personaId,
-                            details: snap.reason,
-                            hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
-                        };
-                    }
-                }
-                else {
-                    versionCreated = { id: snap.version.id, version_name: snap.version.version_name };
-                }
-            }
-            catch {
-                // Snapshotting is required unless force=true
-                if (!force) {
-                    return {
-                        error: "Failed to create pre-deploy snapshot (required before deploy)",
-                        persona_id: personaId,
-                        hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
-                    };
-                }
-            }
-            // Route to handleWorkflow deploy
-            const deployResult = await handleWorkflow({
-                mode: "deploy",
-                persona_id: personaId,
-                workflow_def: workflowDef,
-                proto_config: normalizedArgs.proto_config,
-                env: normalizedArgs.env,
-                force: force,
-                strict_validation: normalizedArgs.strict_validation,
-            }, client, () => undefined);
-            // Add version info to result if created
-            if (versionCreated && deployResult && typeof deployResult === "object") {
-                deployResult.version_snapshot = versionCreated;
-            }
-            return deployResult;
-        }
-        // REMOVED modes - LLM does these
-        case "analyze":
-        case "compare":
-        case "compile":
-        case "optimize":
-        case "generate": {
-            return {
-                error: `Mode "${mode}" removed - LLM does this thinking`,
-                hint: "Use workflow(mode='get') to fetch data, then analyze/generate in your reasoning. Deploy with workflow(mode='deploy').",
-                valid_modes: ["get", "validate", "deploy"],
-            };
-        }
-        default: {
-            // No mode or unknown mode - require explicit mode
-            return {
-                error: `Mode required. Valid modes: get, validate, deploy`,
-                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def.",
-                example: `workflow(mode="get", persona_id="...")`,
-            };
-        }
-    }
-};
-// Unify sync modes: run | status | config
-toolHandlers.sync = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    // Tool definition uses "method" (preview/execute/status), but legacy callers use "mode" (run/status/config)
-    const rawMethod = normalizedArgs.method ? String(normalizedArgs.method) : normalizedArgs.mode ? String(normalizedArgs.mode) : "run";
-    // Map tool method values to internal mode values
-    const mode = rawMethod === "preview" ? "run" : rawMethod === "execute" ? "run" : rawMethod;
-    // "preview" implies dry_run
-    if (rawMethod === "preview") {
-        normalizedArgs.dry_run = true;
-    }
-    // Support both old and new arg names
-    const target = (normalizedArgs.target ?? normalizedArgs.target_env);
-    const source = (normalizedArgs.source ?? normalizedArgs.source_env);
-    const id = normalizedArgs.id;
-    const identifier = normalizedArgs.identifier; // deprecated alias
-    const idOrIdentifier = id ?? identifier;
-    if (mode === "config") {
-        return legacySyncInfo({ include_options: true });
-    }
-    if (mode === "status") {
-        const env = normalizedArgs.env;
-        if (normalizedArgs.list_synced === true) {
-            if (!env)
-                throw new Error('env is required for sync(mode="status", list_synced=true)');
-            return legacySyncInfo({ list_synced: true, master_env: normalizedArgs.master_env, env });
-        }
-        if (idOrIdentifier) {
-            if (!env)
-                throw new Error('env is required for sync(mode="status", id="...")');
-            const identifierToResolve = String(idOrIdentifier);
-            const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifierToResolve);
-            if (isUUID) {
-                return legacySyncInfo({ persona_id: identifierToResolve, env });
-            }
-            // Name lookup: resolve to ID in env, then reuse persona_id path
-            const client = createClient(env);
-            const personas = await client.getPersonasForTenant();
-            const match = personas.find((p) => p.name === identifierToResolve);
-            if (!match)
-                throw new Error(`AI Employee not found by name in ${env}: ${identifierToResolve}`);
-            return legacySyncInfo({ persona_id: match.id, env });
-        }
-        // Default: overall sync status/config summary
-        return legacySyncInfo({ include_options: normalizedArgs.include_options === true });
-    }
-    // mode === "run" (default)
-    if (!target) {
-        throw new Error('target (or target_env) is required for sync(mode="run")');
-    }
-    return legacySyncRun({
-        identifier: idOrIdentifier,
-        target_env: target,
-        source_env: source,
-        scope: normalizedArgs.scope,
-        dry_run: normalizedArgs.dry_run,
-        include_status: normalizedArgs.include_status,
-    });
-};
-// Consolidated demo tool: kit | validate_kit | scenarios | consolidate | generate | validate | template
-toolHandlers.demo = async (args) => {
-    const normalizedArgs = { ...(args ?? {}) };
-    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
-    // Deprecation warning - added to all responses
-    const deprecationWarning = {
-        _deprecation: {
-            message: "The 'demo' tool is deprecated. Please use 'data' and 'persona' tools instead.",
-            migration: {
-                "demo(mode='kit')": "persona(from='demo-sales-sdr', include_data=true)",
-                "demo(mode='generate')": "data(mode='generate', from='customer', count=5)",
-                "demo(mode='scenarios')": "data(mode='templates')",
-                "demo(mode='template')": "data(mode='templates', template='customer')",
-            },
-        },
-    };
-    switch (mode) {
-        case "kit": {
-            // Generate complete demo kit for a persona
-            const personaId = String(normalizedArgs.persona_id ?? "");
-            const scenarioId = String(normalizedArgs.scenario ?? "sales-sdr");
-            if (!personaId) {
-                throw new Error('demo(mode="kit") requires: persona_id');
-            }
-            // Import demo generator
-            const { generateDemoKit, DEMO_SCENARIOS, generateDemoScriptMarkdown, validateDemoKit } = await import("./demo-generator.js");
-            // Get scenario
-            const scenario = DEMO_SCENARIOS[scenarioId];
-            if (!scenario) {
-                throw new Error(`Unknown scenario: ${scenarioId}. Available: ${Object.keys(DEMO_SCENARIOS).join(", ")}`);
-            }
-            // Get persona and workflow
-            const client = await createClient(normalizedArgs.env);
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                throw new Error(`Persona not found: ${personaId}`);
-            }
-            const workflowDef = persona.workflow_def || {};
-            const customQA = normalizedArgs.custom_qa;
-            // Generate kit
-            const kit = generateDemoKit(personaId, persona.name || personaId, workflowDef, scenario, customQA);
-            // Generate markdown script
-            const demoScript = generateDemoScriptMarkdown(kit);
-            // Validate
-            const validation = validateDemoKit(kit);
-            return {
-                success: true,
-                persona_id: personaId,
-                persona_name: persona.name,
-                scenario: scenarioId,
-                kit_summary: {
-                    kb_documents: kit.kb_documents.length,
-                    demo_questions: kit.demo_script.length,
-                    fixed_responses: kit.fixed_responses.length,
-                    validation_queries: kit.validation_queries.length,
-                },
-                validation,
-                demo_script_preview: demoScript.slice(0, 2000) + (demoScript.length > 2000 ? "\n\n... (truncated)" : ""),
-                kit,
-                instructions: [
-                    "1. Upload KB documents to the persona's knowledge base",
-                    "2. Review the demo script and practice the questions",
-                    "3. Optionally apply fixed_responses for guaranteed fallbacks",
-                    "4. Run validation queries to verify demo readiness",
-                    "5. Conduct the demo with confidence!",
-                ],
-            };
-        }
-        case "validate_kit": {
-            // Validate a persona's demo readiness
-            const personaId = String(normalizedArgs.persona_id ?? "");
-            if (!personaId) {
-                throw new Error('demo(mode="validate_kit") requires: persona_id');
-            }
-            const { analyzeWorkflowForDemo, DEMO_SCENARIOS } = await import("./demo-generator.js");
-            const client = await createClient(normalizedArgs.env);
-            const persona = await client.getPersonaById(personaId);
-            if (!persona) {
-                throw new Error(`Persona not found: ${personaId}`);
-            }
-            const analysis = analyzeWorkflowForDemo(persona.workflow_def || {});
-            // Check data sources
-            const dataSourcesResult = await client.listDataSourceFiles(personaId);
-            const dataSources = dataSourcesResult.files || [];
-            const hasKnowledgeBase = dataSources.length > 0;
-            const issues = [];
-            if (!hasKnowledgeBase) {
-                issues.push("No knowledge base documents uploaded - RAG search will fail");
-            }
-            if (analysis.intents.length === 0) {
-                issues.push("No categorizer intents detected - workflow may not route correctly");
-            }
-            if (!analysis.has_search) {
-                issues.push("No search nodes detected - cannot retrieve KB data");
-            }
-            // Suggest best scenario
-            let suggestedScenario = "sales-sdr";
-            for (const [id, scenario] of Object.entries(DEMO_SCENARIOS)) {
-                const intentOverlap = scenario.intents.filter(i => analysis.intents.some(ai => ai.toLowerCase().includes(i.name.toLowerCase()))).length;
-                if (intentOverlap > 0) {
-                    suggestedScenario = id;
-                    break;
-                }
-            }
-            return {
-                persona_id: personaId,
-                persona_name: persona.name,
-                ready: issues.length === 0,
-                issues,
-                workflow_analysis: analysis,
-                knowledge_base: {
-                    has_documents: hasKnowledgeBase,
-                    document_count: dataSources.length,
-                },
-                suggested_scenario: suggestedScenario,
-                next_steps: issues.length > 0
-                    ? issues.map((issue, i) => `${i + 1}. Fix: ${issue}`)
-                    : [`Generate demo kit: demo(mode="kit", persona_id="${personaId}", scenario="${suggestedScenario}")`],
-            };
-        }
-        case "scenarios": {
-            // List available demo scenarios
-            const { DEMO_SCENARIOS } = await import("./demo-generator.js");
-            return {
-                scenarios: Object.entries(DEMO_SCENARIOS).map(([id, scenario]) => ({
-                    id,
-                    name: scenario.name,
-                    description: scenario.description,
-                    persona_types: scenario.persona_types,
-                    tags: scenario.tags,
-                    intent_count: scenario.intents.length,
-                    qa_count: scenario.qa_pairs.length,
-                    entity_types: scenario.entities.map(e => e.type),
-                })),
-                usage: 'demo(mode="kit", persona_id="...", scenario="<scenario_id>")',
-            };
-        }
-        case "consolidate": {
-            const source = String(normalizedArgs.source ?? "");
-            const output = String(normalizedArgs.output ?? "");
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!source || !output || !entity) {
-                throw new Error('demo(mode="consolidate") requires: source, output, entity');
-            }
-            return legacyConsolidateDemoData({
-                source_dir: source,
-                output_dir: output,
-                entity_type: entity,
-                primary_file: normalizedArgs.primary ?? `${entity}s.json`,
-                joins: normalizedArgs.joins ?? [],
-                tags: normalizedArgs.tags,
-            });
-        }
-        case "generate": {
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!entity)
-                throw new Error('demo(mode="generate") requires: entity');
-            return legacyGenerateDemoDocument({
-                entity_type: entity,
-                data: normalizedArgs.data ?? {},
-                related_data: normalizedArgs.related ?? {},
-                output_path: normalizedArgs.output,
-                tags: normalizedArgs.tags,
-            });
-        }
-        case "validate": {
-            return legacyValidateDemoDocument({
-                file_path: normalizedArgs.file,
-                content: normalizedArgs.content,
-            });
-        }
-        case "template": {
-            const entity = String(normalizedArgs.entity ?? "");
-            if (!entity)
-                throw new Error('demo(mode="template") requires: entity');
-            return legacyGetDemoDataTemplate({
-                entity_type: entity,
-                include_example: normalizedArgs.include_example,
-            });
-        }
-        default:
-            throw new Error(`Unknown demo mode: ${mode}`);
-    }
-};
-// generateEntityDocument moved to handlers/demo/index.js
-// ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 /**
@@ -2885,24 +148,8 @@ toolHandlers.demo = async (args) => {
  */
 function determineOperation(toolName, args) {
     if (toolName === "persona") {
-        if (args.analyze)
-            return "analyze";
-        if (args.update)
-            return "update";
-        if (args.create)
-            return "create";
-        if (args.delete)
-            return "delete";
-        if (args.snapshot)
-            return "snapshot";
-        if (args.history)
-            return "history";
-        if (args.restore)
-            return "restore";
-        if (args.compare)
-            return "compare";
-        if (args.sanitize)
-            return "sanitize";
+        if (args.method)
+            return String(args.method);
         if (args.data)
             return "data";
         if (args.id)
@@ -2910,24 +157,21 @@ function determineOperation(toolName, args) {
         return "list";
     }
     if (toolName === "catalog") {
-        if (args.id)
-            return "get";
-        if (args.for)
-            return "recommend"; // V2 schema uses 'for' parameter
-        if (args.query)
-            return "search";
+        if (args.method)
+            return String(args.method);
         return "list";
     }
     if (toolName === "sync") {
-        if (args.execute)
-            return "execute";
-        if (args.status)
-            return "status";
+        if (args.method)
+            return String(args.method);
         return "preview";
     }
     if (toolName === "toolkit_feedback") {
         return args.method ? String(args.method) : "submit";
     }
+    if (toolName === "debug") {
+        return args.method ? String(args.method) : "conversations";
+    }
     return toolName;
 }
 // ─────────────────────────────────────────────────────────────────────────────