@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/dist/mcp/server.js

@@ -25,2135 +25,61 @@ 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";
+import { fingerprintPersona } 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";
+// V2 Tools
+import { generateTools } from "./tools.js";
+import { handlePersona } from "./handlers/persona/index.js";
+import { handleEnv } from "./handlers/env/index.js";
+import { handleAction } from "./handlers/action/index.js";
+import { handleTemplate } from "./handlers/template/index.js";
+import { handleKnowledge } from "./handlers/knowledge/index.js";
+import { handleReference } from "./handlers/reference/index.js";
 // Import extracted handlers
 import { handleWorkflow } from "./handlers/workflow/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";
 // 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 (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();
+const toolHandlers = {
     // ═══════════════════════════════════════════════════════════════════════════
-    // CONSOLIDATED TOOLS (Unix CLI pattern) - 9 tools replace 45
+    // V2 TOOLS — LLM-optimized interface
     // ═══════════════════════════════════════════════════════════════════════════
     env: async () => {
         return handleEnv({}, () => getAvailableEnvironments().map(e => ({
@@ -2417,41 +343,165 @@ 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);
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
+// Standalone sync implementation functions
+// (Used by the V2 sync adapter below)
+// ─────────────────────────────────────────────────────────────────────────────
+async function syncRunImpl(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) };
+    }
+}
+async function syncInfoImpl(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();
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // 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;
+// while routing to the extracted handler implementations.
 // Workflow tool: MCP provides data (get) and executes (deploy). LLM does all thinking.
 toolHandlers.workflow = async (args) => {
     const normalizedArgs = { ...(args ?? {}) };
@@ -2644,14 +694,14 @@ toolHandlers.sync = async (args) => {
     const identifier = normalizedArgs.identifier; // deprecated alias
     const idOrIdentifier = id ?? identifier;
     if (mode === "config") {
-        return legacySyncInfo({ include_options: true });
+        return syncInfoImpl({ 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 });
+            return syncInfoImpl({ list_synced: true, master_env: normalizedArgs.master_env, env });
         }
         if (idOrIdentifier) {
             if (!env)
@@ -2659,7 +709,7 @@ toolHandlers.sync = async (args) => {
             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 });
+                return syncInfoImpl({ persona_id: identifierToResolve, env });
             }
             // Name lookup: resolve to ID in env, then reuse persona_id path
             const client = createClient(env);
@@ -2667,16 +717,16 @@ toolHandlers.sync = async (args) => {
             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 });
+            return syncInfoImpl({ persona_id: match.id, env });
         }
         // Default: overall sync status/config summary
-        return legacySyncInfo({ include_options: normalizedArgs.include_options === true });
+        return syncInfoImpl({ 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({
+    return syncRunImpl({
         identifier: idOrIdentifier,
         target_env: target,
         source_env: source,
@@ -2829,7 +879,7 @@ toolHandlers.demo = async (args) => {
             if (!source || !output || !entity) {
                 throw new Error('demo(mode="consolidate") requires: source, output, entity');
             }
-            return legacyConsolidateDemoData({
+            return handleConsolidateDemoData({
                 source_dir: source,
                 output_dir: output,
                 entity_type: entity,
@@ -2842,7 +892,7 @@ toolHandlers.demo = async (args) => {
             const entity = String(normalizedArgs.entity ?? "");
             if (!entity)
                 throw new Error('demo(mode="generate") requires: entity');
-            return legacyGenerateDemoDocument({
+            return handleGenerateDemoDocument({
                 entity_type: entity,
                 data: normalizedArgs.data ?? {},
                 related_data: normalizedArgs.related ?? {},
@@ -2851,7 +901,7 @@ toolHandlers.demo = async (args) => {
             });
         }
         case "validate": {
-            return legacyValidateDemoDocument({
+            return handleValidateDemoDocument({
                 file_path: normalizedArgs.file,
                 content: normalizedArgs.content,
             });
@@ -2860,7 +910,7 @@ toolHandlers.demo = async (args) => {
             const entity = String(normalizedArgs.entity ?? "");
             if (!entity)
                 throw new Error('demo(mode="template") requires: entity');
-            return legacyGetDemoDataTemplate({
+            return handleGetDemoDataTemplate({
                 entity_type: entity,
                 include_example: normalizedArgs.include_example,
             });
@@ -2869,7 +919,6 @@ toolHandlers.demo = async (args) => {
             throw new Error(`Unknown demo mode: ${mode}`);
     }
 };
-// generateEntityDocument moved to handlers/demo/index.js
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2919,6 +968,9 @@ function determineOperation(toolName, args) {
             return "status";
         return "preview";
     }
+    if (toolName === "toolkit_feedback") {
+        return args.method ? String(args.method) : "submit";
+    }
     return toolName;
 }
 // ─────────────────────────────────────────────────────────────────────────────
@@ -2936,7 +988,10 @@ export async function startMcpServer() {
         },
         // Server instructions - injected into client's system prompt
         // Single source of truth from guidance module
-        instructions: generateServerInstructions(),
+        instructions: generateServerInstructions({
+            version: TOOLKIT_VERSION,
+            commit: TOOLKIT_COMMIT,
+        }),
     });
     // ─────────────────────────────────────────────────────────────────────────
     // Tool Handlers
@@ -2951,11 +1006,17 @@ export async function startMcpServer() {
                 isError: true,
             };
         }
+        const startMs = Date.now();
         try {
             const argsObj = (args ?? {});
             const result = await handler(argsObj);
+            const elapsedMs = Date.now() - startMs;
             // Determine operation type for contextual tips
             const operation = determineOperation(name, argsObj);
+            // Passive telemetry: record successful tool call (fire-and-forget)
+            if (name !== "toolkit_feedback") {
+                recordTelemetry({ type: "tool_call", tool: name, op: operation, ok: true, ms: elapsedMs }).catch(() => { });
+            }
             // Get contextual tip based on operation and result
             const tip = getContextualTip({
                 operation,
@@ -2981,8 +1042,21 @@ export async function startMcpServer() {
             };
         }
         catch (error) {
+            const elapsedMs = Date.now() - startMs;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const argsObj = (args ?? {});
+            const operation = determineOperation(name, argsObj);
+            // Passive telemetry: record failed tool call (fire-and-forget)
+            if (name !== "toolkit_feedback") {
+                recordTelemetry({ type: "error", tool: name, op: operation, ok: false, error_message: errorMessage, ms: elapsedMs }).catch(() => { });
+            }
+            // Solicit feedback on errors
+            const errorResponse = {
+                error: errorMessage,
+                _feedback_welcome: `If this error was unclear or unhelpful, please report it: toolkit_feedback(method="submit", category="error_unclear", tool="${name}", operation="${operation}", message="<describe what was confusing>")`,
+            };
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }) }],
+                content: [{ type: "text", text: JSON.stringify(errorResponse) }],
                 isError: true,
             };
         }
@@ -3034,6 +1108,8 @@ export async function startMcpServer() {
     });
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
+        // Passive telemetry: record resource fetch (fire-and-forget)
+        recordTelemetry({ type: "resource_fetch", resource_uri: uri, ok: true }).catch(() => { });
         const result = await resourceRegistry.read(uri);
         if (isResourceError(result)) {
             throw new Error(`${result.code}: ${result.message}`);
@@ -3050,11 +1126,12 @@ export async function startMcpServer() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // Log startup with version and commit info
+    // Log startup with version, commit, and tool count
     const buildInfo = TOOLKIT_COMMIT
         ? `${TOOLKIT_VERSION} (${TOOLKIT_COMMIT})`
         : TOOLKIT_VERSION;
-    console.error(`Ema MCP Server started: ${TOOLKIT_NAME}@${buildInfo}`);
+    const toolCount = TOOLS.length;
+    console.error(`Ema MCP Server started: ${TOOLKIT_NAME}@${buildInfo} | ${toolCount} tools`);
 }
 // CLI support: allow --help to exit (used by build:verify)
 const argv = process.argv.slice(2);