ema-mcp-toolkit 0.2.0

package/dist/mcp/server.js

@@ -0,0 +1,4585 @@
+#!/usr/bin/env node
+/**
+ * MCP (Model Context Protocol) Server for Ema API
+ *
+ * Provides tools for interacting with Ema AI Employees (personas), Actions (agents),
+ * and Persona Synchronization across multiple environments.
+ *
+ * Terminology mapping:
+ * - API: "persona" <-> UI: "AI Employee"
+ * - API: "action"  <-> UI: "Agent"
+ *
+ * Environment Selection:
+ * - Tools accept an optional `env` parameter to target specific environments
+ * - Default environment is set via EMA_ENV_NAME or first in config
+ * - Available environments come from sync config (EMA_AGENT_SYNC_CONFIG)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Prompts and Resources
+import { PromptRegistry, isPromptError } from "./prompts.js";
+import { ResourceRegistry, isResourceError } from "./resources.js";
+import { EmaClient } from "../sdk/client.js";
+import { loadConfigOptional } from "../sdk/config.js";
+import { resolveSyncBehavior, loadSyncOptions } from "../sdk/sync-options.js";
+import { SyncSDK } from "../sdk/sync.js";
+import { fingerprintPersona, transformWorkflowForTarget, getCleanDescription, buildDescriptionWithSyncTag } from "../sync.js";
+import { SYNC_METADATA_KEY } from "../sdk/models.js";
+// Auto Builder Knowledge
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
+// Workflow Analysis
+analyzeWorkflow, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
+// Workflow Compiler (Template-driven)
+import { compileWorkflow, } from "../sdk/workflow-generator.js";
+// Workflow Intent (Normalization layer)
+import { parseInput, intentToSpec, } from "../sdk/workflow-intent.js";
+// Consolidated Tools (Unix CLI pattern) - NEW UNIFIED INTERFACE
+import { generateConsolidatedTools, } from "./tools-consolidated.js";
+// Legacy Tools (backwards compatibility) - DEPRECATED, OFF BY DEFAULT
+import { generateLegacyTools, } from "./tools-legacy.js";
+// Feature flag: Legacy tools are DISABLED by default to prevent LLM confusion
+// Set EMA_ENABLE_LEGACY_TOOLS=true only if you need backwards compatibility
+const ENABLE_LEGACY_TOOLS = process.env.EMA_ENABLE_LEGACY_TOOLS === "true";
+import { handleEnv, handlePersona, handleAction, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Autobuilder Prompt Generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate an optimized Autobuilder prompt from a natural language description.
+ * Uses knowledge of best practices, agent catalog, and workflow patterns.
+ */
+function generateAutobuilderPrompt(description, personaType) {
+    const typeConfig = {
+        voice: {
+            trigger: "voice_trigger",
+            outputNote: "Use results mapping for Voice AI (not WORKFLOW_OUTPUT node)",
+        },
+        chat: {
+            trigger: "chat_trigger",
+            outputNote: "Connect final response to WORKFLOW_OUTPUT node",
+        },
+        dashboard: {
+            trigger: "document_trigger",
+            outputNote: "Process documents and connect to WORKFLOW_OUTPUT",
+        },
+    };
+    const config = typeConfig[personaType] ?? typeConfig.chat;
+    // Detect intents from description
+    const hasIntentRouting = /intent|route|categor|branch|if.*then/i.test(description);
+    const hasKBSearch = /search|knowledge|faq|document|lookup/i.test(description);
+    const hasExternalAction = /servicenow|salesforce|jira|ticket|create|update|api|external/i.test(description);
+    const hasHITL = /approv|human|review|escalat/i.test(description);
+    // Build structured prompt
+    let prompt = `Create a ${personaType} AI Employee workflow for:\n${description}\n\n`;
+    prompt += "Requirements:\n";
+    prompt += `- Trigger: ${config.trigger}\n`;
+    if (hasIntentRouting) {
+        prompt += "- Use chat_categorizer for intent routing with clear category definitions\n";
+        prompt += "- Include a Fallback category for unmatched queries\n";
+        prompt += "- Use runIf conditions to route based on categorizer output\n";
+    }
+    if (hasKBSearch) {
+        prompt += "- Use search_datastore for knowledge base queries\n";
+        prompt += "- Use conversation_to_search_query if multi-turn context needed\n";
+        prompt += "- Use respond_with_sources for answers with citations\n";
+    }
+    if (hasExternalAction) {
+        prompt += "- Use external_action_caller for external system integration\n";
+        if (!hasHITL) {
+            prompt += "- Add HITL approval before executing external actions (safety)\n";
+        }
+    }
+    if (hasHITL) {
+        prompt += "- Include general_hitl for human approval flows\n";
+        prompt += "- Handle both approval and rejection paths\n";
+    }
+    prompt += `- ${config.outputNote}\n`;
+    prompt += "- Ensure all paths lead to a response (no dead ends)\n";
+    prompt += "- Use correct input types: chat_conversation for categorizers, user_query for search\n";
+    return prompt;
+}
+/**
+ * Generate a human-readable summary of a workflow for Auto Builder prompts.
+ * This creates a description the Auto Builder can understand to recreate the workflow.
+ */
+function summarizeWorkflow(workflowDef) {
+    const actions = workflowDef.actions;
+    if (!actions || actions.length === 0) {
+        return "Empty workflow with no actions";
+    }
+    const lines = [];
+    // Count action types
+    const actionTypes = new Map();
+    const nodeNames = [];
+    for (const action of actions) {
+        const actionType = action.actionType;
+        const typeName = actionType?.name?.name ?? "unknown";
+        actionTypes.set(typeName, (actionTypes.get(typeName) ?? 0) + 1);
+        const nodeName = String(action.name ?? "");
+        if (nodeName)
+            nodeNames.push(nodeName);
+    }
+    // Summary header
+    lines.push(`Workflow with ${actions.length} nodes:`);
+    // List action types and counts
+    for (const [type, count] of actionTypes.entries()) {
+        lines.push(`- ${type}: ${count}`);
+    }
+    // List node names
+    if (nodeNames.length > 0) {
+        lines.push(`\nNodes: ${nodeNames.slice(0, 20).join(", ")}${nodeNames.length > 20 ? "..." : ""}`);
+    }
+    // Check for categorizer (indicates intent routing)
+    const hasCategorizer = Array.from(actionTypes.keys()).some(t => t.includes("categorizer"));
+    if (hasCategorizer) {
+        lines.push("\nThis workflow uses intent-based routing with a categorizer.");
+    }
+    // Check for HITL
+    const hasHitl = Array.from(actionTypes.keys()).some(t => t.includes("hitl") || t.includes("general_hitl"));
+    if (hasHitl) {
+        lines.push("This workflow includes human-in-the-loop approval steps.");
+    }
+    // Include raw workflow JSON for Auto Builder to parse
+    lines.push("\n--- Full workflow_def JSON ---");
+    lines.push(JSON.stringify(workflowDef, null, 2));
+    return lines.join("\n");
+}
+/**
+ * Apply automatic fixes to a workflow based on detected issues.
+ * This function attempts to fix common issues like missing WORKFLOW_OUTPUT,
+ * wrong input sources, and other structural problems.
+ */
+function applyWorkflowFixes(workflowDef, issues, persona) {
+    // Deep clone the workflow to avoid mutating the original
+    const fixedWorkflow = JSON.parse(JSON.stringify(workflowDef));
+    const appliedFixes = [];
+    const actions = fixedWorkflow.actions;
+    if (!actions) {
+        return { fixedWorkflow, appliedFixes: [{ issue_type: "unknown", description: "No actions array found in workflow", applied: false }] };
+    }
+    for (const issue of issues) {
+        let fixed = false;
+        let fixDescription = "";
+        let failReason = "";
+        switch (issue.type) {
+            case "missing_workflow_output": {
+                // For Voice AI, WORKFLOW_OUTPUT is handled via results mapping, not a node
+                // Check if results mapping exists
+                const results = fixedWorkflow.results;
+                if (results && Object.keys(results).length > 0) {
+                    // Results mapping exists, this is valid for Voice AI
+                    fixed = true;
+                    fixDescription = "Workflow uses results mapping (valid for Voice AI) - no WORKFLOW_OUTPUT node needed";
+                }
+                else {
+                    // Try to add results mapping for all response nodes
+                    const responseNodes = actions.filter(a => {
+                        const name = String(a.name ?? "");
+                        return name.includes("respond") || name.includes("response");
+                    });
+                    if (responseNodes.length > 0) {
+                        const newResults = {};
+                        for (const respNode of responseNodes) {
+                            const nodeName = String(respNode.name);
+                            newResults[`${nodeName}.response_with_sources`] = {
+                                actionName: nodeName,
+                                outputName: "response_with_sources",
+                            };
+                        }
+                        fixedWorkflow.results = newResults;
+                        fixed = true;
+                        fixDescription = `Added results mapping for ${responseNodes.length} response node(s)`;
+                    }
+                    else {
+                        failReason = "No response nodes found to map to results";
+                    }
+                }
+                break;
+            }
+            case "wrong_input_source": {
+                const targetNode = actions.find(a => String(a.name) === issue.node);
+                if (!targetNode || !targetNode.inputs) {
+                    failReason = `Could not find node "${issue.node}" or its inputs`;
+                    break;
+                }
+                const inputs = targetNode.inputs;
+                const nodeType = String(targetNode.actionType || targetNode.type || "");
+                // CASE 1: Email field needs entity extraction
+                // This requires adding a new node, not just rebinding
+                const isEmailField = issue.reason?.toLowerCase().includes("email") ||
+                    issue.current?.toLowerCase().includes("email_to") ||
+                    (nodeType.includes("send_email") && inputs.email_to);
+                if (isEmailField && inputs.email_to) {
+                    // Check if entity_extraction already exists
+                    let extractorNode = actions.find(a => String(a.actionType || a.type || "").includes("entity_extraction") ||
+                        String(a.name).includes("entity_extract"));
+                    if (!extractorNode) {
+                        // Create entity_extraction node
+                        const extractorName = "entity_extractor_email";
+                        extractorNode = {
+                            name: extractorName,
+                            actionType: "entity_extraction",
+                            inputs: {
+                                conversation: {
+                                    actionOutput: {
+                                        actionName: "trigger",
+                                        output: "chat_conversation",
+                                    },
+                                },
+                                entities_to_extract: {
+                                    literalValue: {
+                                        value: "email_address",
+                                    },
+                                },
+                            },
+                            outputs: ["email_address", "extracted_entities"],
+                        };
+                        actions.push(extractorNode);
+                        // Wire email_to to use extracted email
+                        inputs.email_to = {
+                            actionOutput: {
+                                actionName: extractorName,
+                                output: "email_address",
+                            },
+                        };
+                        fixed = true;
+                        fixDescription = `Added entity_extraction node "${extractorName}" and wired ${issue.node}.email_to to use extracted email_address`;
+                    }
+                    else {
+                        // Extractor exists, just rewire
+                        inputs.email_to = {
+                            actionOutput: {
+                                actionName: String(extractorNode.name),
+                                output: "email_address",
+                            },
+                        };
+                        fixed = true;
+                        fixDescription = `Wired ${issue.node}.email_to to use ${extractorNode.name}.email_address`;
+                    }
+                    break;
+                }
+                // CASE 2: Simple rebinding (conversation/query sources)
+                let inputField;
+                const possibleFields = ["conversation", "query", "input", "text"];
+                for (const field of possibleFields) {
+                    if (inputs[field]) {
+                        inputField = field;
+                        break;
+                    }
+                }
+                if (inputField && inputs[inputField]) {
+                    const inputBinding = inputs[inputField];
+                    if (inputBinding.actionOutput) {
+                        const actionOutput = inputBinding.actionOutput;
+                        // Update to use recommended source
+                        if (issue.recommended === "chat_conversation") {
+                            actionOutput.actionName = "trigger";
+                            actionOutput.output = "chat_conversation";
+                            fixed = true;
+                        }
+                        else if (issue.recommended === "user_query") {
+                            actionOutput.actionName = "trigger";
+                            actionOutput.output = "user_query";
+                            fixed = true;
+                        }
+                        else if (issue.recommended === "summarized_conversation") {
+                            // Check if summarizer exists
+                            const summarizer = actions.find(a => String(a.name).includes("summarizer") ||
+                                String(a.name).includes("conversation_to_search"));
+                            if (summarizer) {
+                                actionOutput.actionName = String(summarizer.name);
+                                actionOutput.output = "summarized_conversation";
+                                fixed = true;
+                            }
+                            else {
+                                failReason = "Recommended summarized_conversation but no summarizer node exists";
+                                break;
+                            }
+                        }
+                        if (fixed) {
+                            fixDescription = `Changed ${issue.node}.${inputField} from ${issue.current} to ${issue.recommended}`;
+                        }
+                    }
+                }
+                else if (!inputField) {
+                    failReason = `Could not find input field (tried: conversation, query, input, text) in node "${issue.node}"`;
+                }
+                if (!fixed && !failReason) {
+                    failReason = `Could not determine how to fix input source for "${issue.node}"`;
+                }
+                break;
+            }
+            case "incomplete_hitl": {
+                // This requires adding new nodes which is complex
+                // Mark as not auto-fixable
+                failReason = "HITL paths require manual configuration of success/failure response nodes";
+                break;
+            }
+            case "missing_category_edge": {
+                // Check if using runIf pattern (valid alternative to edges)
+                const nodesWithRunIf = actions.filter(a => a.runIf !== undefined);
+                const categorizerName = issue.node;
+                const nodesUsingCategorizer = nodesWithRunIf.filter(a => {
+                    const runIf = a.runIf;
+                    if (!runIf?.lhs)
+                        return false;
+                    const lhs = runIf.lhs;
+                    const actionOutput = lhs.actionOutput;
+                    return actionOutput?.actionName === categorizerName;
+                });
+                if (nodesUsingCategorizer.length > 0) {
+                    fixed = true;
+                    fixDescription = `Categorizer "${categorizerName}" uses runIf pattern (${nodesUsingCategorizer.length} conditional nodes) - valid alternative to explicit edges`;
+                }
+                else {
+                    failReason = "Categorizer needs manual configuration of category routing edges";
+                }
+                break;
+            }
+            case "malformed_runif": {
+                // Fix malformed runIf: "category_<Name>" vs "true" -> "category" vs "<Name>"
+                const targetNode = actions.find(a => String(a.name) === issue.node);
+                if (targetNode?.runIf) {
+                    const runIf = targetNode.runIf;
+                    const lhs = runIf.lhs;
+                    const rhs = runIf.rhs;
+                    if (lhs?.actionOutput && rhs?.inline) {
+                        const actionOutput = lhs.actionOutput;
+                        const inlineRhs = rhs.inline;
+                        const output = String(actionOutput.output ?? "");
+                        if (output.startsWith("category_")) {
+                            // Extract category name and fix the format
+                            const categoryName = output.replace(/^category_/, "");
+                            actionOutput.output = "category";
+                            inlineRhs.enumValue = categoryName;
+                            fixed = true;
+                            fixDescription = `Fixed runIf for "${issue.node}": output="category", enumValue="${categoryName}"`;
+                        }
+                    }
+                }
+                if (!fixed) {
+                    failReason = `Could not find node "${issue.node}" or its runIf condition`;
+                }
+                break;
+            }
+            case "orphan": {
+                // Remove orphan nodes
+                const orphanIndex = actions.findIndex(a => String(a.name) === issue.node);
+                if (orphanIndex >= 0) {
+                    actions.splice(orphanIndex, 1);
+                    fixed = true;
+                    fixDescription = `Removed orphan node "${issue.node}" (not connected to workflow)`;
+                }
+                else {
+                    failReason = `Could not find orphan node "${issue.node}" to remove`;
+                }
+                break;
+            }
+            case "redundant_search": {
+                // This is an optimization, not a critical fix - skip auto-fix
+                failReason = "Redundant search is an optimization suggestion - consider consolidating manually";
+                break;
+            }
+            case "type_mismatch": {
+                // Type mismatch fix strategy:
+                // 1. Handle multiBinding inputs - find and fix bindings inside multiBinding
+                // 2. Handle nested named_inputs targets - find binding inside named_inputs.multiBinding
+                // 3. For CHAT_CONVERSATION expected: use trigger.chat_conversation, move old to named_inputs
+                // 4. For SEARCH_RESULT expected: find actual search node output
+                // 5. For DOCUMENT/TEXT_WITH_SOURCES mismatches: move to named_inputs (accepts ANY type)
+                const sourceNode = issue.source?.split(".")[0];
+                const sourceOutput = issue.source?.split(".")[1];
+                const targetNode = issue.target?.split(".")[0];
+                const targetInput = issue.target?.split(".")[1];
+                const expectedType = issue.expected;
+                const gotType = issue.got;
+                if (!sourceNode || !targetNode || !targetInput) {
+                    failReason = "Missing source/target node information";
+                    break;
+                }
+                const targetAction = actions.find(a => String(a.name) === targetNode);
+                if (!targetAction || !targetAction.inputs) {
+                    failReason = `Could not find target node "${targetNode}"`;
+                    break;
+                }
+                const inputs = targetAction.inputs;
+                let inputBinding = inputs[targetInput];
+                let actionOutput;
+                let isNestedInNamedInputs = false;
+                let nestedBindingIndex = -1;
+                // Check for autoDetectedBinding - some bindings use this structure alongside or instead of others
+                if (inputBinding && !inputBinding.actionOutput && inputBinding.autoDetectedBinding) {
+                    const autoBinding = inputBinding.autoDetectedBinding;
+                    if (autoBinding.actionOutput) {
+                        actionOutput = autoBinding.actionOutput;
+                    }
+                }
+                // Check if targetInput is a named_inputs reference (e.g., "named_inputs_conversation")
+                if (!inputBinding && targetInput.startsWith("named_inputs_")) {
+                    const namedInputKey = targetInput.replace("named_inputs_", "");
+                    const namedInputs = inputs.named_inputs;
+                    if (namedInputs?.multiBinding) {
+                        const mb = namedInputs.multiBinding;
+                        if (mb.elements) {
+                            nestedBindingIndex = mb.elements.findIndex(el => el.namedBinding?.name?.toLowerCase() === namedInputKey.toLowerCase());
+                            if (nestedBindingIndex >= 0) {
+                                const namedBinding = mb.elements[nestedBindingIndex].namedBinding;
+                                if (namedBinding?.value?.actionOutput) {
+                                    actionOutput = namedBinding.value.actionOutput;
+                                    isNestedInNamedInputs = true;
+                                    inputBinding = namedBinding.value;
+                                }
+                            }
+                        }
+                    }
+                    // If we couldn't find the binding in multiBinding, the type mismatch for named_inputs
+                    // is actually acceptable since named_inputs accepts ANY type
+                    if (!actionOutput && namedInputs) {
+                        fixed = true;
+                        fixDescription = `${targetNode}.${targetInput} is in named_inputs (accepts any type) - type mismatch is acceptable`;
+                        break;
+                    }
+                }
+                // If direct binding exists, check for actionOutput or multiBinding
+                if (!actionOutput && inputBinding) {
+                    if (inputBinding.actionOutput) {
+                        actionOutput = inputBinding.actionOutput;
+                    }
+                    else if (inputBinding.multiBinding) {
+                        // Handle multiBinding - find the element that references the source node
+                        const mb = inputBinding.multiBinding;
+                        if (mb.elements) {
+                            for (let i = 0; i < mb.elements.length; i++) {
+                                const el = mb.elements[i];
+                                const elActionOutput = el.namedBinding?.value?.actionOutput;
+                                if (elActionOutput && String(elActionOutput.actionName) === sourceNode) {
+                                    actionOutput = elActionOutput;
+                                    nestedBindingIndex = i;
+                                    break;
+                                }
+                            }
+                        }
+                        // Also check if elements have direct actionOutput (not inside namedBinding)
+                        if (!actionOutput && mb.elements) {
+                            for (let i = 0; i < mb.elements.length; i++) {
+                                const el = mb.elements[i];
+                                // Check for actionOutput directly on element
+                                if (el.actionOutput) {
+                                    actionOutput = el.actionOutput;
+                                    nestedBindingIndex = i;
+                                    break;
+                                }
+                            }
+                        }
+                        // If source not found in multiBinding, DON'T mark as fixed - the type mismatch is real
+                        // We need to find and remove/fix the mismatched binding
+                        if (!actionOutput && mb.elements) {
+                            // Find ANY binding that has type mismatch and try to fix it
+                            for (let i = 0; i < mb.elements.length; i++) {
+                                const el = mb.elements[i];
+                                const elActionOutput = el.namedBinding?.value?.actionOutput;
+                                if (elActionOutput) {
+                                    // Use the first actionOutput we find - it's likely the mismatched one
+                                    actionOutput = elActionOutput;
+                                    nestedBindingIndex = i;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+                if (!actionOutput) {
+                    failReason = `No actionOutput binding found for ${targetNode}.${targetInput}`;
+                    break;
+                }
+                // === FIX STRATEGY 1: CHAT_CONVERSATION expected ===
+                // If binding is nested in named_inputs, redirect to trigger.chat_conversation
+                if (expectedType?.includes("CHAT_CONVERSATION")) {
+                    const oldActionName = String(actionOutput.actionName ?? "");
+                    const oldOutput = String(actionOutput.output ?? "");
+                    if (isNestedInNamedInputs) {
+                        // Binding is inside named_inputs - change it to use trigger.chat_conversation
+                        actionOutput.actionName = "trigger";
+                        actionOutput.output = "chat_conversation";
+                        // Rename the named binding to indicate it's now conversation
+                        const namedInputs = inputs.named_inputs;
+                        const mb = namedInputs.multiBinding;
+                        if (mb.elements && nestedBindingIndex >= 0 && mb.elements[nestedBindingIndex]?.namedBinding) {
+                            // Keep the old binding as additional context
+                            mb.elements.push({
+                                namedBinding: {
+                                    name: `${targetInput.replace("named_inputs_", "")}_context`,
+                                    value: { actionOutput: { actionName: oldActionName, output: oldOutput } }
+                                }
+                            });
+                        }
+                        fixed = true;
+                        fixDescription = `Fixed ${targetNode}.${targetInput}: now uses trigger.chat_conversation`;
+                        break;
+                    }
+                    // Standard case: direct binding - change to trigger.chat_conversation
+                    actionOutput.actionName = "trigger";
+                    actionOutput.output = "chat_conversation";
+                    // Add old binding to named_inputs so it's still available
+                    const namedInputs = inputs.named_inputs;
+                    const contextName = targetInput === "conversation" ? "context" : `${targetInput}_context`;
+                    if (namedInputs?.multiBinding) {
+                        // Append to existing multiBinding
+                        const mb = namedInputs.multiBinding;
+                        if (!mb.elements)
+                            mb.elements = [];
+                        mb.elements.push({
+                            namedBinding: {
+                                name: contextName,
+                                value: { actionOutput: { actionName: oldActionName, output: oldOutput } }
+                            }
+                        });
+                    }
+                    else {
+                        // Create new named_inputs with multiBinding
+                        inputs.named_inputs = {
+                            multiBinding: {
+                                elements: [{
+                                        namedBinding: {
+                                            name: contextName,
+                                            value: { actionOutput: { actionName: oldActionName, output: oldOutput } }
+                                        }
+                                    }]
+                            }
+                        };
+                    }
+                    fixed = true;
+                    fixDescription = `Fixed ${targetNode}.${targetInput}: now uses trigger.chat_conversation, old binding moved to named_inputs.${contextName}`;
+                    break;
+                }
+                // === FIX STRATEGY 2: SEARCH_RESULT expected ===
+                // Find an actual search node and use its search_results output
+                if (expectedType?.includes("SEARCH_RESULT") && gotType?.includes("TEXT_WITH_SOURCES")) {
+                    // Find a search node (excluding web_search which has different output)
+                    const searchNode = actions.find(a => {
+                        const name = String(a.name ?? "");
+                        const actionType = a.actionType?.name?.name ?? "";
+                        return (name.includes("search") || actionType.includes("search_datastore"))
+                            && !name.includes("web_search")
+                            && !name.includes("combine");
+                    });
+                    if (searchNode) {
+                        // Change to use search node's output directly
+                        // Don't add old binding to named_inputs - it causes type mismatches
+                        actionOutput.actionName = String(searchNode.name);
+                        actionOutput.output = "search_results";
+                        fixed = true;
+                        fixDescription = `Fixed ${targetNode}.${targetInput}: now uses ${searchNode.name}.search_results`;
+                    }
+                    else {
+                        failReason = `No search_datastore node found to provide SEARCH_RESULT for ${targetNode}`;
+                    }
+                    break;
+                }
+                // === FIX STRATEGY 3: DOCUMENT or other type → remove the mismatched binding ===
+                // Simply remove the bad binding - don't move to named_inputs (causes type mismatches)
+                if (gotType?.includes("DOCUMENT") ||
+                    (expectedType?.includes("TEXT_WITH_SOURCES") && !gotType?.includes("TEXT_WITH_SOURCES"))) {
+                    // If binding is inside multiBinding of the target input, remove the bad element
+                    if (inputBinding?.multiBinding && nestedBindingIndex >= 0) {
+                        const mb = inputBinding.multiBinding;
+                        if (mb.elements && mb.elements.length > 1) {
+                            // Remove the mismatched element, keep others
+                            mb.elements.splice(nestedBindingIndex, 1);
+                            fixed = true;
+                            fixDescription = `Fixed ${targetNode}.${targetInput}: removed mismatched binding from multiBinding`;
+                            break;
+                        }
+                        else if (mb.elements && mb.elements.length === 1) {
+                            // Only one element - remove entire binding
+                            delete inputBinding.multiBinding;
+                        }
+                    }
+                    // Remove the mismatched binding from the typed input entirely
+                    delete inputs[targetInput];
+                    fixed = true;
+                    fixDescription = `Fixed ${targetNode}.${targetInput}: removed mismatched binding (input now unbound)`;
+                    break;
+                }
+                // === FALLBACK: Remove mismatched binding ===
+                // Don't move to named_inputs - it causes type mismatches
+                {
+                    // Remove the mismatched binding entirely
+                    delete inputs[targetInput];
+                    fixed = true;
+                    fixDescription = `Fixed ${targetNode}.${targetInput}: removed mismatched binding (${gotType} → expected ${expectedType})`;
+                }
+                break;
+            }
+            default: {
+                failReason = `Auto-fix not implemented for issue type: ${issue.type}`;
+            }
+        }
+        appliedFixes.push({
+            issue_type: issue.type,
+            description: fixed ? fixDescription : `Could not fix: ${issue.reason}`,
+            applied: fixed,
+            reason: fixed ? undefined : failReason,
+        });
+    }
+    return { fixedWorkflow, appliedFixes };
+}
+// Well-known Ema environments for auto-detection
+const KNOWN_ENVS = {
+    demo: "https://api.demo.ema.co",
+    dev: "https://api.dev.ema.co",
+    staging: "https://api.staging.ema.co",
+    prod: "https://api.ema.co",
+};
+let cachedConfig = null;
+let cachedEnvInfos = null;
+function getConfig() {
+    if (cachedConfig === undefined) {
+        const configPath = process.env.EMA_AGENT_SYNC_CONFIG ?? "./config.yaml";
+        cachedConfig = loadConfigOptional(configPath);
+    }
+    return cachedConfig;
+}
+/**
+ * Detect available environments from:
+ * 1. YAML config file (if present) - full sync support
+ * 2. Environment variables (fallback) - browse-only mode
+ *    - Looks for EMA_<ENV>_BEARER_TOKEN patterns
+ *    - Uses well-known URLs or EMA_<ENV>_BASE_URL
+ */
+function getAvailableEnvironments() {
+    if (cachedEnvInfos)
+        return cachedEnvInfos;
+    // Option 1: From YAML config
+    const cfg = getConfig();
+    if (cfg?.environments?.length) {
+        cachedEnvInfos = cfg.environments.map((e) => ({
+            name: e.name,
+            baseUrl: e.baseUrl,
+            tokenEnvVar: e.bearerTokenEnv,
+        }));
+        return cachedEnvInfos;
+    }
+    // Option 2: Auto-detect from env vars (EMA_<ENV>_BEARER_TOKEN pattern)
+    const detected = [];
+    const tokenPattern = /^EMA_([A-Z]+)_BEARER_TOKEN$/;
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!value)
+            continue;
+        const match = key.match(tokenPattern);
+        if (match) {
+            const envName = match[1].toLowerCase();
+            const baseUrlKey = `EMA_${match[1]}_BASE_URL`;
+            const baseUrl = process.env[baseUrlKey] ?? KNOWN_ENVS[envName] ?? `https://api.${envName}.ema.co`;
+            detected.push({ name: envName, baseUrl, tokenEnvVar: key });
+        }
+    }
+    if (detected.length > 0) {
+        cachedEnvInfos = detected;
+        return cachedEnvInfos;
+    }
+    // Option 3: Single default environment
+    const baseUrl = process.env.EMA_BASE_URL ?? "https://api.demo.ema.co";
+    const envName = process.env.EMA_ENV_NAME ?? "default";
+    cachedEnvInfos = [{
+            name: envName,
+            baseUrl,
+            tokenEnvVar: "EMA_BEARER_TOKEN",
+        }];
+    return cachedEnvInfos;
+}
+function getDefaultEnvName() {
+    const envs = getAvailableEnvironments();
+    // Prefer EMA_ENV_NAME, then first in config
+    const preferred = process.env.EMA_ENV_NAME;
+    if (preferred && envs.some((e) => e.name === preferred)) {
+        return preferred;
+    }
+    return envs[0]?.name ?? "default";
+}
+function createClient(envName) {
+    const targetEnv = envName ?? getDefaultEnvName();
+    const envs = getAvailableEnvironments();
+    const envInfo = envs.find((e) => e.name === targetEnv);
+    if (!envInfo) {
+        const available = envs.map((e) => e.name).join(", ");
+        throw new Error(`Unknown environment: ${targetEnv}. Available: ${available}`);
+    }
+    const token = process.env[envInfo.tokenEnvVar];
+    if (!token) {
+        throw new Error(`Missing token for environment ${targetEnv}. Set ${envInfo.tokenEnvVar}`);
+    }
+    return new EmaClient({
+        name: envInfo.name,
+        baseUrl: envInfo.baseUrl,
+        bearerToken: token,
+    });
+}
+function getSyncSDK() {
+    const cfg = getConfig();
+    if (!cfg)
+        return null;
+    return new SyncSDK(cfg);
+}
+async function directSyncPersona(opts) {
+    const { name, sourceEnv, targetEnv, dryRun, syncStatus } = opts;
+    // Create clients
+    const sourceClient = createClient(sourceEnv);
+    const targetClient = createClient(targetEnv);
+    // Find source persona by name (list doesn't include workflow_def)
+    const sourcePersonas = await sourceClient.getPersonasForTenant();
+    const sourcePersonaFromList = sourcePersonas.find((p) => p.name === name);
+    if (!sourcePersonaFromList) {
+        throw new Error(`Persona not found in ${sourceEnv}: ${name}`);
+    }
+    // Fetch full persona to get workflow_def
+    const sourcePersona = await sourceClient.getPersonaById(sourcePersonaFromList.id);
+    if (!sourcePersona) {
+        throw new Error(`Failed to fetch full persona details: ${sourcePersonaFromList.id}`);
+    }
+    return directSyncPersonaImpl({ sourcePersona, sourceEnv, targetEnv, sourceClient, targetClient, dryRun, syncStatus });
+}
+async function directSyncPersonaById(opts) {
+    const { personaId, sourceEnv, targetEnv, dryRun, syncStatus } = opts;
+    // Create clients
+    const sourceClient = createClient(sourceEnv);
+    const targetClient = createClient(targetEnv);
+    // Get full source persona
+    const sourcePersona = await sourceClient.getPersonaById(personaId);
+    if (!sourcePersona) {
+        throw new Error(`Persona not found in ${sourceEnv}: ${personaId}`);
+    }
+    return directSyncPersonaImpl({ sourcePersona, sourceEnv, targetEnv, sourceClient, targetClient, dryRun, syncStatus });
+}
+async function directSyncPersonaImpl(opts) {
+    const { sourcePersona, sourceEnv, targetEnv, targetClient, dryRun, syncStatus } = opts;
+    // Compute fingerprint
+    const fp = fingerprintPersona(sourcePersona);
+    // Find existing replica in target by sync tag or name
+    let targetPersonaId;
+    let created = false;
+    // First, check by sync tag (most reliable)
+    const syncedResult = await targetClient.findSyncedPersona(sourceEnv, sourcePersona.id);
+    if (syncedResult) {
+        targetPersonaId = syncedResult.persona.id;
+        // Check if fingerprints match - skip if no changes
+        if (syncedResult.syncMetadata.master_fingerprint === fp) {
+            return {
+                success: true,
+                source_env: sourceEnv,
+                target_env: targetEnv,
+                source_persona: { id: sourcePersona.id, name: sourcePersona.name },
+                target_persona: { id: targetPersonaId, name: syncedResult.persona.name, created: false },
+                fingerprint: fp,
+                dry_run: dryRun,
+                error: "Already in sync (fingerprints match)",
+            };
+        }
+    }
+    // Fallback: find by name
+    if (!targetPersonaId && sourcePersona.name) {
+        const targetPersonas = await targetClient.getPersonasForTenant();
+        const byName = targetPersonas.find((p) => p.name === sourcePersona.name);
+        if (byName) {
+            targetPersonaId = byName.id;
+        }
+    }
+    if (dryRun) {
+        return {
+            success: true,
+            source_env: sourceEnv,
+            target_env: targetEnv,
+            source_persona: { id: sourcePersona.id, name: sourcePersona.name },
+            target_persona: targetPersonaId
+                ? { id: targetPersonaId, name: sourcePersona.name, created: false }
+                : undefined,
+            fingerprint: fp,
+            dry_run: true,
+        };
+    }
+    // Build sync metadata
+    const syncMetadata = {
+        master_env: sourceEnv,
+        master_id: sourcePersona.id,
+        synced_at: new Date().toISOString(),
+        master_fingerprint: fp,
+    };
+    // Copy proto_config from source (sync metadata now goes in status_log)
+    const protoConfig = { ...(sourcePersona.proto_config ?? {}) };
+    delete protoConfig[SYNC_METADATA_KEY]; // Clean any legacy sync tags from proto_config
+    if (targetPersonaId) {
+        // Update existing persona
+        // Transform workflow if present
+        let workflow;
+        if (sourcePersona.workflow_def) {
+            workflow = transformWorkflowForTarget(sourcePersona.workflow_def, sourcePersona.id, targetPersonaId);
+        }
+        // Clean source description and add compact sync tag
+        const cleanSourceDesc = getCleanDescription(sourcePersona.description);
+        const descriptionWithTag = buildDescriptionWithSyncTag(cleanSourceDesc, sourceEnv, sourcePersona.id);
+        // Clean proto_config description too
+        const protoConfigClean = {
+            ...protoConfig,
+            description: getCleanDescription(protoConfig.description),
+        };
+        // Update persona with sync tag in description
+        await targetClient.updateAiEmployee({
+            persona_id: targetPersonaId,
+            name: sourcePersona.name,
+            description: descriptionWithTag,
+            proto_config: protoConfigClean,
+            welcome_messages: sourcePersona.welcome_messages,
+            embedding_enabled: sourcePersona.embedding_enabled,
+            workflow,
+            // Optionally sync enabled/disabled status (status can be "ready", "active", "inactive", etc.)
+            ...(syncStatus && { enabled_by_user: sourcePersona.status !== "inactive" }),
+        });
+    }
+    else {
+        // Create new persona
+        const templateId = (sourcePersona.template_id ?? sourcePersona.templateId);
+        if (!templateId) {
+            throw new Error(`Cannot create persona in ${targetEnv}: source has no template_id`);
+        }
+        // Clean source description and add compact sync tag
+        const cleanSourceDescCreate = getCleanDescription(sourcePersona.description);
+        const descriptionWithTagCreate = buildDescriptionWithSyncTag(cleanSourceDescCreate, sourceEnv, sourcePersona.id);
+        // Clean proto_config description
+        const protoConfigCleanCreate = {
+            ...protoConfig,
+            description: getCleanDescription(protoConfig.description),
+        };
+        const createResult = await targetClient.createAiEmployee({
+            name: sourcePersona.name ?? "Unnamed Persona",
+            description: descriptionWithTagCreate,
+            template_id: templateId,
+            proto_config: protoConfigCleanCreate,
+            welcome_messages: sourcePersona.welcome_messages,
+            trigger_type: sourcePersona.trigger_type,
+        });
+        targetPersonaId = createResult.persona_id ?? createResult.id;
+        created = true;
+        // Follow-up: Now that we have target persona ID, sync the workflow
+        if (sourcePersona.workflow_def && targetPersonaId) {
+            const workflow = transformWorkflowForTarget(sourcePersona.workflow_def, sourcePersona.id, targetPersonaId);
+            // Update with transformed workflow
+            await targetClient.updateAiEmployee({
+                persona_id: targetPersonaId,
+                proto_config: protoConfigCleanCreate,
+                workflow,
+            });
+        }
+    }
+    return {
+        success: true,
+        source_env: sourceEnv,
+        target_env: targetEnv,
+        source_persona: { id: sourcePersona.id, name: sourcePersona.name },
+        target_persona: { id: targetPersonaId, name: sourcePersona.name, created },
+        fingerprint: fp,
+    };
+}
+/**
+ * Config-less sync all: find all personas with sync tags in target env and re-sync from source
+ */
+async function directSyncAll(opts) {
+    const { targetEnv, dryRun } = opts;
+    const targetClient = createClient(targetEnv);
+    // Find all personas with sync tags
+    const personas = await targetClient.getPersonasForTenant();
+    const syncedPersonas = [];
+    for (const p of personas) {
+        const meta = targetClient.getSyncMetadata(p);
+        if (meta) {
+            syncedPersonas.push({ persona: p, meta });
+        }
+    }
+    const results = [];
+    const errors = [];
+    let synced = 0;
+    let skipped = 0;
+    for (const { persona, meta } of syncedPersonas) {
+        try {
+            // Get source client for this persona's master env
+            const sourceClient = createClient(meta.master_env);
+            // Fetch full source persona
+            const sourcePersona = await sourceClient.getPersonaById(meta.master_id);
+            if (!sourcePersona) {
+                errors.push(`Source persona not found: ${meta.master_id} in ${meta.master_env}`);
+                continue;
+            }
+            const result = await directSyncPersonaImpl({
+                sourcePersona,
+                sourceEnv: meta.master_env,
+                targetEnv,
+                sourceClient,
+                targetClient,
+                dryRun,
+            });
+            results.push(result);
+            if (result.error?.includes("Already in sync")) {
+                skipped++;
+            }
+            else {
+                synced++;
+            }
+        }
+        catch (e) {
+            errors.push(`${persona.name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return {
+        target_env: targetEnv,
+        scanned: syncedPersonas.length,
+        synced,
+        skipped,
+        errors,
+        results,
+    };
+}
+// 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
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// TOOL STRUCTURE:
+// 1. CONSOLIDATED TOOLS (9 tools) - Unix CLI pattern with flags
+//    - env, persona, workflow, action, template, knowledge, reference, sync, demo
+//    - Defined in: ./tools-consolidated.ts
+//
+// 2. LEGACY TOOLS (40+ tools) - Old separate tools for backwards compatibility  
+//    - Defined in: ./tools-legacy.ts
+//    - Enable with EMA_ENABLE_LEGACY_TOOLS=true
+//
+// NAMING CONVENTION:
+// - Tool names are defined as BASE NAMES (e.g., "persona", "list_ai_employees")
+// - MCP clients prefix with "mcp_{server}_" (e.g., "mcp_ema_persona")
+//
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate all available tools based on configuration
+ *
+ * DEFAULT: Only consolidated tools (9 tools, Unix CLI pattern)
+ * OPTIONAL: Set EMA_ENABLE_LEGACY_TOOLS=true to add deprecated tools
+ *
+ * Why consolidated-only by default:
+ * - Prevents LLM confusion from having multiple tools that do the same thing
+ * - Ensures consistent tool usage patterns
+ * - Reduces context window waste from duplicate tool definitions
+ */
+function generateAllTools() {
+    const envNames = getAvailableEnvironments().map(e => e.name);
+    const defaultEnv = getDefaultEnvName();
+    // Always include consolidated tools (the new unified interface)
+    const consolidatedTools = generateConsolidatedTools(envNames, defaultEnv);
+    // Only include legacy tools if explicitly enabled (for migration period)
+    if (ENABLE_LEGACY_TOOLS) {
+        console.error("[MCP] WARNING: Legacy tools enabled via EMA_ENABLE_LEGACY_TOOLS=true");
+        console.error("[MCP] This is deprecated and will be removed. Migrate to consolidated tools.");
+        const legacyTools = generateLegacyTools(envNames, defaultEnv);
+        // Consolidated tools first (preferred), legacy tools after
+        return [...consolidatedTools, ...legacyTools];
+    }
+    return consolidatedTools;
+}
+// Generate tools (called once at module load)
+const TOOLS = generateAllTools();
+// ─────────────────────────────────────────────────────────────────────────────
+// ADDITIONAL TOOLS (not in consolidated or legacy)
+// These are special-purpose tools that don't fit the standard patterns
+// ─────────────────────────────────────────────────────────────────────────────
+const ADDITIONAL_TOOLS = [
+    // ─────────────────────────────────────────────────────────────────────────
+    // NOTE: Legacy tools (get_persona, find_personas, create_ai_employee, etc.)
+    // have been moved to ./tools-legacy.ts for backwards compatibility.
+    //
+    // Consolidated tools (persona, workflow, action, etc.) are generated from
+    // ./tools-consolidated.ts following Unix CLI patterns.
+    //
+    // Only special-purpose tools remain here:
+    // - "workflow" (unified tool) - experimental, bridges old and new patterns
+    // - Demo data tools - special-purpose data generation
+    // ─────────────────────────────────────────────────────────────────────────
+    // INLINE LEGACY TOOLS REMOVED
+    // All legacy tools (get_workflow_action, find_workflow_actions, compare_ai_employees,
+    // list_ai_employee_templates, sync, sync_info, list_auto_builder_agents, etc.)
+    // have been moved to ./tools-legacy.ts
+    // ─────────────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────────────────
+    // LEGACY INLINE TOOLS REMOVED - See ./tools-legacy.ts
+    // ─────────────────────────────────────────────────────────────────────────────
+    // The following tools have been removed from this file and are now generated
+    // from tools-legacy.ts: list_auto_builder_agents, get_auto_builder_agent,
+    // suggest_agents_for_use_case, get_workflow_pattern, list_workflow_patterns,
+    // check_type_compatibility, get_widget_reference, get_qualifying_questions,
+    // get_voice_persona_template, validate_workflow_prompt, get_auto_builder_guidance,
+    // get_platform_concept, list_platform_concepts, get_common_mistakes,
+    // get_debug_checklist, get_workflow_execution_model, analyze_workflow,
+    // detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes,
+    // compare_workflow_versions, get_workflow_metrics, compile_workflow,
+    // upload_data_source, delete_data_source, list_data_sources, get_embedding_status,
+    // toggle_embedding
+    // ─────────────────────────────────────────────────────────────────────────────
+    // The remaining legacy tools are handled by the LEGACY_TOOL_MAPPING in
+    // tools-consolidated.ts for routing to consolidated handlers.
+    //
+    // INLINE DEFINITIONS REMOVED - They are now in tools-legacy.ts
+    // (analyze_workflow, detect_workflow_issues, validate_workflow_connections, suggest_workflow_fixes)
+    // (compare_workflow_versions, get_workflow_metrics) - moved to tools-legacy.ts
+    // ─────────────────────────────────────────────────────────────────────────────
+    // 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"],
+        },
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONSOLIDATED TOOLS (Unix CLI pattern)
+    // These 9 tools follow Unix conventions: single command with flags
+    // ═══════════════════════════════════════════════════════════════════════════
+    ...generateConsolidatedTools(getAvailableEnvironments().map(e => e.name), getDefaultEnvName()),
+];
+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);
+        // Default template IDs for common persona types
+        const DEFAULT_TEMPLATES = {
+            voice: "00000000-0000-0000-0000-00000000001e", // Voice AI template
+            chat: "00000000-0000-0000-0000-000000000004", // Chat AI template
+            dashboard: "00000000-0000-0000-0000-000000000002", // Dashboard AI template
+        };
+        // Determine template_id: explicit > default 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 default template based on persona_type
+        if (!templateId && !sourcePersonaId) {
+            const personaType = args.persona_type ? String(args.persona_type).toLowerCase() : null;
+            if (personaType && DEFAULT_TEMPLATES[personaType]) {
+                templateId = DEFAULT_TEMPLATES[personaType];
+            }
+            else {
+                throw new Error("Must provide template_id, source_persona_id, or persona_type ('voice', 'chat', 'dashboard')");
+            }
+        }
+        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}`);
+        // Helper to validate widget names
+        const isValidWidget = (w) => {
+            const name = w.name;
+            return typeof name === "string" && name.trim().length > 0;
+        };
+        // Merge proto_config: start with existing, overlay with provided
+        // This ensures we don't lose existing widget configs when updating
+        // Also sanitize existing widgets to remove any with empty names (can happen from UI bugs)
+        let mergedProtoConfig = existing.proto_config ?? {};
+        if (mergedProtoConfig.widgets && Array.isArray(mergedProtoConfig.widgets)) {
+            const sanitizedWidgets = mergedProtoConfig.widgets.filter(isValidWidget);
+            mergedProtoConfig = { ...mergedProtoConfig, widgets: sanitizedWidgets };
+        }
+        if (args.proto_config && typeof args.proto_config === "object") {
+            const providedConfig = args.proto_config;
+            // Deep merge widgets if both exist
+            // Widgets use: name (string like "voiceSettings"), type (number like 38)
+            // Inner configs are stored under a key matching the widget's name (e.g., widget.voiceSettings: {...})
+            const existingWidgetsRaw = mergedProtoConfig.widgets;
+            const newWidgetsRaw = providedConfig.widgets;
+            if (Array.isArray(existingWidgetsRaw) || Array.isArray(newWidgetsRaw)) {
+                // Filter using isValidWidget helper (already defined above)
+                const existingWidgets = (existingWidgetsRaw ?? []).filter(isValidWidget);
+                const newWidgets = (newWidgetsRaw ?? []).filter(isValidWidget);
+                // Merge widgets by 'name' field (e.g., "voiceSettings", "conversationSettings")
+                const widgetMap = new Map();
+                for (const w of existingWidgets) {
+                    const key = String(w.name);
+                    widgetMap.set(key, { ...w });
+                }
+                for (const w of newWidgets) {
+                    const key = String(w.name);
+                    const existingWidget = widgetMap.get(key);
+                    if (existingWidget) {
+                        // Deep merge inner config object (named same as widget's 'name')
+                        // e.g., for widget with name="voiceSettings", merge widget.voiceSettings
+                        const widgetName = String(w.name);
+                        const innerConfig = w[widgetName];
+                        const existingInner = existingWidget[widgetName];
+                        const mergedWidget = {
+                            ...existingWidget,
+                            ...w,
+                        };
+                        // Deep merge the inner config if both exist
+                        if (innerConfig && existingInner) {
+                            mergedWidget[widgetName] = { ...existingInner, ...innerConfig };
+                        }
+                        widgetMap.set(key, mergedWidget);
+                    }
+                    else {
+                        widgetMap.set(key, { ...w });
+                    }
+                }
+                // Only include widgets array if we have valid widgets
+                const mergedWidgets = Array.from(widgetMap.values());
+                if (mergedWidgets.length > 0) {
+                    mergedProtoConfig = { ...mergedProtoConfig, ...providedConfig, widgets: mergedWidgets };
+                }
+                else {
+                    // No valid widgets - exclude the widgets field entirely
+                    const { widgets: _unused, ...restProvidedConfig } = providedConfig;
+                    mergedProtoConfig = { ...mergedProtoConfig, ...restProvidedConfig };
+                }
+            }
+            else {
+                // Simple shallow merge for non-widget fields
+                mergedProtoConfig = { ...mergedProtoConfig, ...providedConfig };
+            }
+        }
+        // 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 deploy_workflow instead - it provides validation, auto-fix, and better error handling for workflow changes.",
+                suggestion: {
+                    tool: "deploy_workflow",
+                    parameters: {
+                        persona_id: personaId,
+                        workflow_def: "your_workflow_here",
+                        validate_first: true,
+                        auto_fix: true,
+                    },
+                },
+            };
+        }
+        const req = {
+            persona_id: personaId,
+            name: args.name ? String(args.name) : undefined,
+            description: args.description ? String(args.description) : undefined,
+            proto_config: mergedProtoConfig,
+            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
+        // Get existing persona with full details
+        const persona = await client.getPersonaById(personaId);
+        if (!persona)
+            throw new Error(`AI Employee not found: ${personaId}`);
+        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";
+        // Transform workflow to match target persona (same approach sync uses)
+        // This ensures workflowName.namespaces contains the correct persona ID
+        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 it
+                workflowDef = transformWorkflowForTarget(workflowDef, sourcePersonaId, personaId);
+            }
+            // CRITICAL: Copy the exact workflowName structure from existing workflow
+            // The API validates that the workflow name matches exactly
+            const existingWfName = existingWorkflow.workflowName;
+            if (existingWfName) {
+                workflowDef.workflowName = JSON.parse(JSON.stringify(existingWfName));
+            }
+        }
+        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;
+        // Validate workflow if requested and provided
+        let validationResults = { valid: true, issues: [] };
+        if (validateFirst && workflowDef) {
+            const analysis = analyzeWorkflow(workflowDef, {
+                persona_id: personaId,
+                persona_name: persona.name ?? "Unknown"
+            });
+            if (!analysis.validation_passed) {
+                validationResults.valid = false;
+                validationResults.issues = analysis.issues ?? [];
+                // Auto-fix if enabled
+                if (autoFix && validationResults.issues.length > 0) {
+                    fixAttempted = true;
+                    const fixResult = applyWorkflowFixes(workflowDef, validationResults.issues, persona);
+                    workflowDef = fixResult.fixedWorkflow;
+                    appliedFixes.push(...fixResult.appliedFixes);
+                    // Re-validate after fixes
+                    const reAnalysis = analyzeWorkflow(workflowDef, {
+                        persona_id: personaId,
+                        persona_name: persona.name ?? "Unknown"
+                    });
+                    validationResults.valid = reAnalysis.validation_passed;
+                    validationResults.issues = reAnalysis.issues ?? [];
+                }
+            }
+        }
+        // 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)",
+            };
+        }
+        // Helper to validate widget names
+        const isValidWidget = (w) => {
+            const name = w.name;
+            return typeof name === "string" && name.trim().length > 0;
+        };
+        // Merge proto_config with existing, preserving widgets
+        // Widgets use: name (string like "voiceSettings"), type (number like 38)
+        // Inner configs are stored under a key matching the widget's name
+        // Also sanitize existing widgets to remove any with empty names (can happen from UI bugs)
+        let mergedProtoConfig = persona.proto_config ?? {};
+        if (mergedProtoConfig.widgets && Array.isArray(mergedProtoConfig.widgets)) {
+            const sanitizedWidgets = mergedProtoConfig.widgets.filter(isValidWidget);
+            mergedProtoConfig = { ...mergedProtoConfig, widgets: sanitizedWidgets };
+        }
+        if (protoConfig) {
+            // Deep merge widgets if both exist
+            const existingWidgetsRaw = mergedProtoConfig.widgets;
+            const newWidgetsRaw = protoConfig.widgets;
+            if (Array.isArray(existingWidgetsRaw) || Array.isArray(newWidgetsRaw)) {
+                // Filter using isValidWidget helper
+                const existingWidgets = (existingWidgetsRaw ?? []).filter(isValidWidget);
+                const newWidgets = (newWidgetsRaw ?? []).filter(isValidWidget);
+                // Merge widgets by 'name' field (e.g., "voiceSettings", "conversationSettings")
+                const widgetMap = new Map();
+                for (const w of existingWidgets) {
+                    const key = String(w.name);
+                    widgetMap.set(key, { ...w });
+                }
+                for (const w of newWidgets) {
+                    const key = String(w.name);
+                    const existingWidget = widgetMap.get(key);
+                    if (existingWidget) {
+                        // Deep merge inner config object (named same as widget's 'name')
+                        const widgetName = String(w.name);
+                        const innerConfig = w[widgetName];
+                        const existingInner = existingWidget[widgetName];
+                        const mergedWidget = {
+                            ...existingWidget,
+                            ...w,
+                        };
+                        // Deep merge the inner config if both exist
+                        if (innerConfig && existingInner) {
+                            mergedWidget[widgetName] = { ...existingInner, ...innerConfig };
+                        }
+                        widgetMap.set(key, mergedWidget);
+                    }
+                    else {
+                        widgetMap.set(key, { ...w });
+                    }
+                }
+                // Only include widgets array if we have valid widgets
+                const mergedWidgets = Array.from(widgetMap.values());
+                if (mergedWidgets.length > 0) {
+                    mergedProtoConfig = { ...mergedProtoConfig, ...protoConfig, widgets: mergedWidgets };
+                }
+                else {
+                    // No valid widgets - exclude the widgets field entirely
+                    const { widgets: _unused, ...restProtoConfig } = protoConfig;
+                    mergedProtoConfig = { ...mergedProtoConfig, ...restProtoConfig };
+                }
+            }
+            else {
+                mergedProtoConfig = { ...mergedProtoConfig, ...protoConfig };
+            }
+        }
+        // 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 {
+                    // 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}`);
+            }
+        }
+        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: deployedVia === "autobuilder"
+                ? "Workflow deployed via Ema Auto Builder (persona had no existing workflow). Test in the Ema simulator to verify behavior."
+                : fixAttempted && appliedFixes.some(f => f.applied)
+                    ? `Workflow deployed successfully with ${appliedFixes.filter(f => f.applied).length} auto-fix(es) applied. Test in the Ema simulator to verify behavior.`
+                    : workflowDef
+                        ? "Workflow deployed successfully. Test in the Ema simulator to verify behavior."
+                        : "Proto config updated successfully.",
+        };
+    },
+    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\")",
+            };
+        }
+        // Step 2: Analyze workflow for issues
+        const analysis = analyzeWorkflow(workflowDef, {
+            persona_id: personaId,
+            persona_name: persona.name ?? "Unknown",
+        });
+        const issues = analysis.issues ?? [];
+        const criticalIssues = issues.filter(i => i.severity === "critical");
+        // If no issues, workflow is healthy
+        if (issues.length === 0) {
+            const result = {
+                success: true,
+                persona: persona.name,
+                status: "✅ Workflow is healthy",
+                nodes: analysis.summary?.total_nodes ?? 0,
+                message: "No issues found - workflow is already optimized!",
+            };
+            // If enhancement prompt was provided, note that it can't be auto-applied
+            if (enhancementPrompt) {
+                result.enhancement_note = `Enhancement requested: "${enhancementPrompt}". Since there are no issues to fix, use the Ema UI Auto Builder to make this change manually.`;
+            }
+            return result;
+        }
+        // Step 3: Apply fixes
+        let fixedWorkflow = workflowDef;
+        const appliedFixes = [];
+        if (issues.length > 0) {
+            const fixResult = applyWorkflowFixes(workflowDef, issues, persona);
+            fixedWorkflow = fixResult.fixedWorkflow;
+            appliedFixes.push(...fixResult.appliedFixes);
+        }
+        // Re-analyze after fixes
+        const postFixAnalysis = analyzeWorkflow(fixedWorkflow, {
+            persona_id: personaId,
+            persona_name: persona.name ?? "Unknown",
+        });
+        const remainingIssues = postFixAnalysis.issues ?? [];
+        const remainingCritical = remainingIssues.filter(i => i.severity === "critical");
+        // If preview mode, show what would happen without deploying
+        if (preview) {
+            const fixedCount = appliedFixes.filter(f => f.applied).length;
+            const failedCount = appliedFixes.filter(f => !f.applied).length;
+            const previewResult = {
+                success: true,
+                persona: persona.name,
+                status: "📋 Preview - Fixes Available",
+                mode: "optimize",
+                nodes: fixedWorkflow.actions?.length ?? 0,
+                found_issues: issues.length,
+                can_fix: fixedCount,
+                cannot_fix: failedCount,
+                ready_to_deploy: remainingCritical.length === 0,
+                issues: issues.length > 0 ? issues.map(i => `${i.severity === "critical" ? "❌" : "⚠️"} ${i.type}: ${i.reason}`) : ["No issues found"],
+                fixes: appliedFixes.length > 0 ? appliedFixes.map(f => `${f.applied ? "✅" : "❌"} ${f.description}`) : [],
+                next_step: remainingCritical.length === 0
+                    ? `Run workflow(persona_id="${personaId}", mode="optimize") without preview to deploy fixes.`
+                    : `${remainingCritical.length} critical issue(s) need manual fix in Ema UI.`,
+            };
+            if (enhancementPrompt) {
+                previewResult.enhancement_note = `Enhancement "${enhancementPrompt}" noted. Auto-fixes will be applied first; use Ema UI Auto Builder for the enhancement.`;
+            }
+            return previewResult;
+        }
+        // Step 4: Deploy if no critical issues remain
+        if (remainingCritical.length > 0) {
+            return {
+                success: false,
+                persona: persona.name,
+                status: "❌ Cannot auto-fix",
+                fixed: appliedFixes.filter(f => f.applied).length,
+                remaining_critical: remainingCritical.length,
+                manual_fixes_needed: remainingCritical.map(i => ({
+                    problem: i.type,
+                    details: i.reason,
+                    fix: i.recommendation,
+                })),
+                message: `${remainingCritical.length} issue(s) need manual fix in the Ema UI Auto Builder.`,
+            };
+        }
+        // Sanitize workflow before deployment
+        // Fix enumTypes - check nested structure
+        const enumTypes = fixedWorkflow.enumTypes;
+        if (Array.isArray(enumTypes)) {
+            const validEnumTypes = enumTypes.filter(e => {
+                const outerName = e.name;
+                const innerName = outerName?.name;
+                const actualName = innerName?.name;
+                return typeof actualName === "string" && actualName.trim().length > 0;
+            });
+            if (validEnumTypes.length > 0) {
+                fixedWorkflow.enumTypes = validEnumTypes;
+            }
+            else {
+                delete fixedWorkflow.enumTypes;
+            }
+        }
+        // Copy workflowName from existing
+        const existingWfName = workflowDef.workflowName;
+        if (existingWfName) {
+            fixedWorkflow.workflowName = JSON.parse(JSON.stringify(existingWfName));
+        }
+        // Merge proto_config (sanitize widgets)
+        const isValidWidget = (w) => {
+            const name = w.name;
+            return typeof name === "string" && name.trim().length > 0;
+        };
+        let mergedProtoConfig = persona.proto_config ?? {};
+        if (mergedProtoConfig.widgets && Array.isArray(mergedProtoConfig.widgets)) {
+            const sanitizedWidgets = mergedProtoConfig.widgets.filter(isValidWidget);
+            mergedProtoConfig = { ...mergedProtoConfig, widgets: sanitizedWidgets };
+        }
+        // Build and send request
+        const req = {
+            persona_id: personaId,
+            proto_config: mergedProtoConfig,
+            workflow: fixedWorkflow,
+        };
+        const actionsArr = fixedWorkflow.actions ?? [];
+        try {
+            await client.updateAiEmployee(req);
+            const fixedCount = appliedFixes.filter(f => f.applied).length;
+            const deployResult = {
+                success: true,
+                persona: persona.name,
+                status: "✅ Optimized & Deployed",
+                mode: "optimized",
+                issues_found: issues.length,
+                issues_fixed: fixedCount,
+                nodes: postFixAnalysis.summary?.total_nodes ?? actionsArr.length,
+                message: fixedCount > 0
+                    ? `Fixed ${fixedCount} issue(s) and deployed!`
+                    : "Deployed successfully!",
+                next_step: "Test in the Ema simulator to verify behavior.",
+            };
+            if (enhancementPrompt) {
+                deployResult.enhancement_note = `Fixes applied. Enhancement "${enhancementPrompt}" requires manual implementation via Ema UI Auto Builder.`;
+            }
+            return deployResult;
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            // Extract EmaApiError body if available
+            const apiBody = err?.body;
+            const statusCode = err?.statusCode;
+            return {
+                success: false,
+                persona: persona.name,
+                status: "❌ Deploy Failed",
+                error: errorMessage,
+                status_code: statusCode,
+                api_response: apiBody ? JSON.parse(apiBody) : undefined,
+                fixes_attempted: appliedFixes.filter(f => f.applied).length,
+                suggestion: "Check the api_response field for the actual backend error.",
+            };
+        }
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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 actions = await client.listActionsFromWorkflow(persona.workflow_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 actions = await client.listActionsFromWorkflow(workflowId);
+            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 () => {
+        return {
+            template: VOICE_PERSONA_TEMPLATE,
+            required_fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions"],
+            optional_fields: ["transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"],
+            project_type: PROJECT_TYPES.voice,
+            widget_ids: {
+                voiceSettings: 38,
+                conversationSettings: 39,
+                vadSettings: 43,
+                dataStorageSettings: 42,
+            },
+            instructions: [
+                "Replace all {placeholder} values with actual content",
+                "takeActionInstructions uses </Case N> format for each action",
+                "speechCharacteristics should include TTS pronunciation rules",
+                "systemPrompt defines tool calling behavior",
+            ],
+        };
+    },
+    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) => {
+        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",
+                recommendation: "This persona may not have a generated workflow. Use Auto Builder to create one.",
+            };
+        }
+        const analysis = analyzeWorkflow(persona.workflow_def, {
+            persona_id: personaId,
+            persona_name: persona.name,
+            environment: client["env"].name,
+        });
+        return {
+            ...analysis,
+            recommendations: analysis.validation_passed
+                ? ["Workflow structure looks valid. Test with sample queries to verify behavior."]
+                : [
+                    "Fix all critical issues before deployment",
+                    ...analysis.issues
+                        .filter(i => i.severity === "critical")
+                        .slice(0, 3)
+                        .map(i => `Priority: ${i.reason}`),
+                    "Use suggest_workflow_fixes to get fix proposals",
+                ],
+        };
+    },
+    detect_workflow_issues: 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 issues = detectWorkflowIssues(workflowDef);
+        const summary = {
+            total: issues.length,
+            critical: issues.filter(i => i.severity === "critical").length,
+            warning: issues.filter(i => i.severity === "warning").length,
+            info: issues.filter(i => i.severity === "info").length,
+        };
+        return {
+            issues,
+            summary,
+            validation_passed: summary.critical === 0,
+            issue_types_found: [...new Set(issues.map(i => i.type))],
+            next_steps: issues.length > 0
+                ? ["Use suggest_workflow_fixes(issues) to get fix proposals"]
+                : ["No issues detected - workflow structure looks valid"],
+        };
+    },
+    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) => {
+        const issues = args.issues;
+        if (!Array.isArray(issues)) {
+            return {
+                error: "Invalid issues array",
+                hint: "Pass issues from detect_workflow_issues or analyze_workflow",
+                example_input: [
+                    { type: "missing_fallback", severity: "critical", node: "intent_classifier", reason: "..." },
+                    { type: "type_mismatch", severity: "critical", source: "trigger.chat_conversation", target: "search.query", reason: "..." },
+                ],
+            };
+        }
+        if (issues.length === 0) {
+            return {
+                message: "No issues to fix",
+                fixes: [],
+            };
+        }
+        const fixes = suggestWorkflowFixes(issues);
+        return {
+            issue_count: issues.length,
+            fix_count: fixes.length,
+            fixes,
+            application_order: [
+                "1. Fix critical issues first (missing_fallback, incomplete_hitl, cycles)",
+                "2. Fix type mismatches (may require adding intermediate nodes)",
+                "3. Address warnings (wrong_input_source, orphan nodes)",
+                "4. Re-run detect_workflow_issues to verify fixes",
+            ],
+        };
+    },
+    compare_workflow_versions: async (args) => {
+        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 analysisBefore = personaBefore.workflow_def
+            ? analyzeWorkflow(personaBefore.workflow_def, { persona_id: idBefore, persona_name: personaBefore.name })
+            : null;
+        const analysisAfter = personaAfter.workflow_def
+            ? analyzeWorkflow(personaAfter.workflow_def, { persona_id: idAfter, persona_name: personaAfter.name })
+            : null;
+        // Compare fingerprints
+        const fpBefore = personaBefore.workflow_def ? fingerprintPersona(personaBefore) : null;
+        const fpAfter = personaAfter.workflow_def ? fingerprintPersona(personaAfter) : null;
+        return {
+            environment: client["env"].name,
+            before: {
+                persona_id: idBefore,
+                name: personaBefore.name,
+                fingerprint: fpBefore,
+                has_workflow: !!personaBefore.workflow_def,
+                node_count: analysisBefore?.summary.total_nodes ?? 0,
+                edge_count: analysisBefore?.summary.total_edges ?? 0,
+                critical_issues: analysisBefore?.issue_summary.critical ?? 0,
+                validation_passed: analysisBefore?.validation_passed ?? false,
+            },
+            after: {
+                persona_id: idAfter,
+                name: personaAfter.name,
+                fingerprint: fpAfter,
+                has_workflow: !!personaAfter.workflow_def,
+                node_count: analysisAfter?.summary.total_nodes ?? 0,
+                edge_count: analysisAfter?.summary.total_edges ?? 0,
+                critical_issues: analysisAfter?.issue_summary.critical ?? 0,
+                validation_passed: analysisAfter?.validation_passed ?? false,
+            },
+            comparison: {
+                fingerprints_match: fpBefore === fpAfter,
+                node_count_change: (analysisAfter?.summary.total_nodes ?? 0) - (analysisBefore?.summary.total_nodes ?? 0),
+                edge_count_change: (analysisAfter?.summary.total_edges ?? 0) - (analysisBefore?.summary.total_edges ?? 0),
+                critical_issues_change: (analysisAfter?.issue_summary.critical ?? 0) - (analysisBefore?.issue_summary.critical ?? 0),
+                validation_improved: !analysisBefore?.validation_passed && (analysisAfter?.validation_passed ?? false),
+                validation_regressed: (analysisBefore?.validation_passed ?? false) && !analysisAfter?.validation_passed,
+            },
+            issues_before: analysisBefore?.issues.slice(0, 5) ?? [],
+            issues_after: analysisAfter?.issues.slice(0, 5) ?? [],
+            recommendations: fpBefore === fpAfter
+                ? ["No workflow changes detected between versions"]
+                : [
+                    analysisAfter?.validation_passed
+                        ? "After version passes validation"
+                        : "After version has validation issues - review before deploying",
+                    (analysisAfter?.issue_summary.critical ?? 0) > (analysisBefore?.issue_summary.critical ?? 0)
+                        ? "Warning: More critical issues in after version"
+                        : (analysisAfter?.issue_summary.critical ?? 0) < (analysisBefore?.issue_summary.critical ?? 0)
+                            ? "Good: Fewer critical issues in after version"
+                            : "Same number of critical issues",
+                ],
+        };
+    },
+    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 analysis = analyzeWorkflow(persona.workflow_def, {
+            persona_id: personaId,
+            persona_name: persona.name,
+            environment: client["env"].name,
+        });
+        // Calculate complexity indicators
+        const avgEdgesPerNode = analysis.summary.total_nodes > 0
+            ? (analysis.summary.total_edges / analysis.summary.total_nodes).toFixed(2)
+            : 0;
+        // Estimate parallel vs sequential
+        const hasParallelBranches = analysis.summary.categorizers_count > 0;
+        return {
+            environment: client["env"].name,
+            persona_id: personaId,
+            persona_name: persona.name,
+            structure: {
+                total_nodes: analysis.summary.total_nodes,
+                total_edges: analysis.summary.total_edges,
+                has_trigger: analysis.summary.has_trigger,
+                has_workflow_output: analysis.summary.has_workflow_output,
+            },
+            routing: {
+                categorizers_count: analysis.summary.categorizers_count,
+                hitl_nodes_count: analysis.summary.hitl_nodes_count,
+                has_parallel_branches: hasParallelBranches,
+            },
+            quality: {
+                validation_passed: analysis.validation_passed,
+                critical_issues: analysis.issue_summary.critical,
+                warnings: analysis.issue_summary.warning,
+            },
+            complexity: {
+                avg_edges_per_node: avgEdgesPerNode,
+                complexity_rating: analysis.summary.total_nodes <= 5 ? "simple"
+                    : analysis.summary.total_nodes <= 15 ? "moderate"
+                        : "complex",
+            },
+            recommendations: [
+                analysis.summary.categorizers_count === 0 && analysis.summary.total_nodes > 3
+                    ? "Consider adding intent routing with chat_categorizer for better user experience"
+                    : null,
+                analysis.summary.hitl_nodes_count === 0
+                    ? "No HITL nodes - consider adding human approval for sensitive actions"
+                    : null,
+                analysis.issue_summary.critical > 0
+                    ? `${analysis.issue_summary.critical} critical issues need attention - use analyze_workflow for details`
+                    : null,
+            ].filter(Boolean),
+        };
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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>)',
+        };
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Data Source / Embedding Management
+    // TODO: Add support for 3rd party data sources (Google Drive, SharePoint, Confluence, etc.)
+    // ─────────────────────────────────────────────────────────────────────────
+    upload_data_source: async (args) => {
+        const client = createClient(args.env);
+        const personaId = String(args.persona_id);
+        const filePath = String(args.file_path);
+        const tags = args.tags ? String(args.tags) : undefined;
+        // Read the file from filesystem
+        const fs = await import("fs/promises");
+        const path = await import("path");
+        // Check if file exists
+        try {
+            await fs.access(filePath);
+        }
+        catch {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const fileContent = await fs.readFile(filePath);
+        const filename = path.basename(filePath);
+        // Upload the file
+        const result = await client.uploadDataSource(personaId, fileContent, filename, { tags });
+        // Get the persona to update status_log
+        const persona = await client.getPersonaById(personaId);
+        if (persona) {
+            const existingStatusLog = persona.status_log ?? {};
+            const fileUploadLog = existingStatusLog.fileUpload ?? [];
+            // Add new file to status log
+            const updatedStatusLog = {
+                ...existingStatusLog,
+                fileUpload: [
+                    ...fileUploadLog,
+                    {
+                        id: result.fileId,
+                        status: "success",
+                        filename: result.filename,
+                        main_comment: "File ingested successfully.",
+                        sub_comments: [],
+                    },
+                ],
+            };
+            // Update persona with new status_log
+            await client.updateAiEmployee({
+                persona_id: personaId,
+                proto_config: persona.proto_config ?? {},
+                status_log: updatedStatusLog,
+            });
+        }
+        return {
+            environment: client["env"].name,
+            success: true,
+            persona_id: personaId,
+            file_id: result.fileId,
+            filename: result.filename,
+            status: result.status,
+            message: `File "${filename}" uploaded successfully`,
+            next_steps: [
+                'Enable RAG: knowledge(persona_id="<persona_id>", mode="toggle", enabled=true)',
+                'Verify upload: knowledge(persona_id="<persona_id>", mode="list")',
+            ],
+        };
+    },
+    delete_data_source: async (args) => {
+        const client = createClient(args.env);
+        const personaId = String(args.persona_id);
+        const fileId = String(args.file_id);
+        const result = await client.deleteDataSource(personaId, fileId);
+        return {
+            environment: client["env"].name,
+            success: result.success,
+            persona_id: personaId,
+            file_id: fileId,
+            message: `Data source file deleted`,
+        };
+    },
+    list_data_sources: async (args) => {
+        const client = createClient(args.env);
+        const personaId = String(args.persona_id);
+        // Get the persona to check its configuration
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            throw new Error(`AI Employee not found: ${personaId}`);
+        }
+        // Extract data source info from proto_config widgets
+        const protoConfig = persona.proto_config;
+        const widgets = (protoConfig?.widgets ?? []);
+        // Find fileUpload widget configuration (use correct field names)
+        const fileUploadWidget = widgets.find((w) => w.name === "fileUpload" || w.type === "FILE_UPLOAD" || w.type === 3);
+        // Extract file count from widget config
+        const fileUploadConfig = fileUploadWidget?.fileUpload;
+        const localFiles = fileUploadConfig?.localFiles;
+        const fileCount = localFiles?.[0]?.numFiles ? parseInt(localFiles[0].numFiles, 10) : 0;
+        // Get status log for upload history
+        const statusLog = persona.status_log;
+        const fileUploadLog = statusLog?.fileUpload ?? [];
+        // Try to get actual file list from API
+        const files = await client.listDataSourceFiles(personaId);
+        return {
+            environment: client["env"].name,
+            persona_id: personaId,
+            persona_name: persona.name,
+            embedding_enabled: persona.embedding_enabled ?? false,
+            file_count: fileCount,
+            files: files.length > 0 ? files : fileUploadLog,
+            use_chunking: fileUploadConfig?.useChunking ?? false,
+            workflow_id: persona.workflow_id,
+            actions: [
+                'Upload: knowledge(persona_id="<persona_id>", mode="upload", file="/path/to/file.pdf")',
+                'Delete: knowledge(persona_id="<persona_id>", mode="delete", file_id="<file_id>")',
+                'Toggle embedding: knowledge(persona_id="<persona_id>", mode="toggle", enabled=true|false)',
+            ],
+        };
+    },
+    get_embedding_status: 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}`);
+        }
+        // Extract RAG-related configuration
+        const protoConfig = persona.proto_config;
+        const widgets = (protoConfig?.widgets ?? []);
+        const fileUploadWidget = widgets.find((w) => w.name === "fileUpload" || w.type === "FILE_UPLOAD" || w.type === 3);
+        const fileUploadConfig = fileUploadWidget?.fileUpload;
+        return {
+            environment: client["env"].name,
+            persona_id: personaId,
+            persona_name: persona.name,
+            embedding_enabled: persona.embedding_enabled ?? false,
+            file_upload_configured: !!fileUploadWidget,
+            use_chunking: fileUploadConfig?.useChunking ?? false,
+            note: persona.embedding_enabled
+                ? "Embedding/RAG is enabled - uploaded documents will be indexed for search"
+                : "Embedding/RAG is disabled - documents will not be indexed",
+        };
+    },
+    toggle_embedding: async (args) => {
+        const client = createClient(args.env);
+        const personaId = String(args.persona_id);
+        const enabled = Boolean(args.enabled);
+        // Get existing persona to preserve other fields
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            throw new Error(`AI Employee not found: ${personaId}`);
+        }
+        // Update embedding status
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            proto_config: persona.proto_config ?? {},
+            embedding_enabled: enabled,
+        });
+        return {
+            environment: client["env"].name,
+            success: true,
+            persona_id: personaId,
+            persona_name: persona.name,
+            embedding_enabled: enabled,
+            message: enabled
+                ? "Embedding/RAG enabled - uploaded documents will be indexed for semantic search"
+                : "Embedding/RAG disabled - documents will not be indexed",
+            next_steps: enabled
+                ? ['Upload documents: knowledge(persona_id="<persona_id>", mode="upload", file="/path/to/file.pdf")']
+                : [],
+        };
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Unified Workflow Handler
+    // ─────────────────────────────────────────────────────────────────────────
+    workflow: async (args) => {
+        const client = createClient(args.env);
+        const personaId = args.persona_id ? String(args.persona_id) : undefined;
+        const mode = args.mode ?? "generate";
+        const useAutobuilder = args.use_autobuilder;
+        const autoDeploy = Boolean(args.auto_deploy);
+        const autoFix = args.auto_fix !== false; // Default true
+        // ─────────────────────────────────────────────────────────────────────────
+        // MODE: IMPROVE - Improve existing workflow
+        // ─────────────────────────────────────────────────────────────────────────
+        if (mode === "improve" && personaId) {
+            const persona = await client.getPersonaById(personaId);
+            if (!persona)
+                throw new Error(`AI Employee not found: ${personaId}`);
+            const currentWorkflow = persona.workflow_def;
+            if (!currentWorkflow)
+                throw new Error(`AI Employee "${persona.name}" has no workflow`);
+            const issues = detectWorkflowIssues(currentWorkflow);
+            if (issues.length === 0) {
+                return {
+                    environment: client["env"].name,
+                    success: true,
+                    status: "no_issues",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    message: "Workflow has no detected issues",
+                };
+            }
+            // Try auto-fix first
+            if (autoFix) {
+                const fixResult = applyWorkflowFixes(currentWorkflow, issues, persona);
+                if (fixResult.appliedFixes.some((f) => f.applied)) {
+                    const newIssues = detectWorkflowIssues(fixResult.fixedWorkflow);
+                    if (autoDeploy) {
+                        await client.updateAiEmployee({
+                            persona_id: personaId,
+                            proto_config: persona.proto_config ?? {},
+                            workflow: fixResult.fixedWorkflow,
+                        });
+                    }
+                    return {
+                        environment: client["env"].name,
+                        success: true,
+                        status: autoDeploy ? "deployed" : "improved",
+                        persona_id: personaId,
+                        persona_name: persona.name,
+                        fixes_applied: fixResult.appliedFixes.filter((f) => f.applied).map((f) => f.description),
+                        issues_before: issues.length,
+                        issues_after: newIssues.length,
+                        deployed: autoDeploy,
+                        workflow_def: autoDeploy ? undefined : fixResult.fixedWorkflow,
+                    };
+                }
+            }
+            return {
+                environment: client["env"].name,
+                success: false,
+                status: "needs_manual_fix",
+                persona_id: personaId,
+                issues,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // MODE: ANALYZE - Analyze only (no generation)
+        // ─────────────────────────────────────────────────────────────────────────
+        if (mode === "analyze" && personaId) {
+            const persona = await client.getPersonaById(personaId);
+            if (!persona)
+                throw new Error(`AI Employee not found: ${personaId}`);
+            const workflowDef = persona.workflow_def;
+            if (!workflowDef) {
+                return {
+                    environment: client["env"].name,
+                    success: true,
+                    status: "no_workflow",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                };
+            }
+            const issues = detectWorkflowIssues(workflowDef);
+            return {
+                environment: client["env"].name,
+                success: true,
+                status: "analyzed",
+                persona_id: personaId,
+                persona_name: persona.name,
+                issues,
+                summary: {
+                    critical: issues.filter((i) => i.severity === "critical").length,
+                    warnings: issues.filter((i) => i.severity === "warning").length,
+                },
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // MODE: GENERATE - Generate new workflow from input
+        // ─────────────────────────────────────────────────────────────────────────
+        const input = args.input;
+        if (!input && !personaId) {
+            return {
+                success: false,
+                status: "missing_input",
+                message: "Provide 'input' (description or spec) or 'persona_id' with mode='improve'",
+            };
+        }
+        // Parse and normalize input
+        const parseResult = parseInput(input);
+        const { intent, input_type, validation } = parseResult;
+        // Override persona_type if provided
+        if (args.persona_type) {
+            intent.persona_type = args.persona_type;
+        }
+        // If validation incomplete, return questions
+        if (!validation.complete) {
+            return {
+                environment: client["env"].name,
+                success: true,
+                status: "needs_input",
+                input_type,
+                parsed_intent: intent,
+                validation,
+                message: "Need more information to generate workflow",
+                questions: validation.questions,
+                suggestions: validation.suggestions,
+            };
+        }
+        // Decide: compile locally vs. use Auto Builder
+        const isSimple = !intent.intents || intent.intents.length <= 2;
+        const shouldUseAutobuilder = useAutobuilder ?? !isSimple;
+        let workflowDef;
+        let generationMethod;
+        if (shouldUseAutobuilder) {
+            // Use Auto Builder
+            const prompt = generateAutobuilderPrompt(intent.description, intent.persona_type);
+            const autobuilderId = await client.findAutobuilderPersona();
+            const conv = await client.createAutobuilderConversation(autobuilderId);
+            const result = await client.chatWithAutobuilder(conv.conversation_id, prompt);
+            if (!result.workflow_def) {
+                return {
+                    environment: client["env"].name,
+                    success: false,
+                    status: "generation_failed",
+                    message: "Auto Builder could not generate workflow. Try being more specific.",
+                    parsed_intent: intent,
+                    autobuilder_response: result.response,
+                };
+            }
+            workflowDef = result.workflow_def;
+            generationMethod = "autobuilder";
+        }
+        else {
+            // Compile locally from intent
+            const spec = intentToSpec(intent);
+            const compiled = compileWorkflow(spec);
+            workflowDef = compiled.workflow_def;
+            generationMethod = "local_compile";
+        }
+        // Validate generated workflow
+        const issues = detectWorkflowIssues(workflowDef);
+        let fixesApplied = [];
+        // Auto-fix if needed
+        if (issues.length > 0 && autoFix) {
+            const mockPersona = { id: personaId ?? "new", name: intent.name };
+            const fixResult = applyWorkflowFixes(workflowDef, issues, mockPersona);
+            if (fixResult.appliedFixes.some((f) => f.applied)) {
+                workflowDef = fixResult.fixedWorkflow;
+                fixesApplied = fixResult.appliedFixes.filter((f) => f.applied).map((f) => f.description);
+            }
+        }
+        const finalIssues = detectWorkflowIssues(workflowDef);
+        // Deploy if requested
+        let deployed = false;
+        if (personaId && autoDeploy) {
+            const persona = await client.getPersonaById(personaId);
+            if (persona) {
+                await client.updateAiEmployee({
+                    persona_id: personaId,
+                    proto_config: persona.proto_config ?? {},
+                    workflow: workflowDef,
+                });
+                deployed = true;
+            }
+        }
+        return {
+            environment: client["env"].name,
+            success: true,
+            status: deployed ? "deployed" : "generated",
+            input_type,
+            generation_method: generationMethod,
+            parsed_intent: intent,
+            validation: {
+                confidence: validation.confidence,
+                suggestions: validation.suggestions,
+            },
+            issues_found: issues.length,
+            auto_fixes: fixesApplied,
+            remaining_issues: finalIssues.length,
+            workflow_def: deployed ? undefined : workflowDef,
+            deployed,
+            persona_id: personaId,
+            next_steps: deployed
+                ? [`Verify: get_persona("${personaId}")`]
+                : personaId
+                    ? [`Deploy: deploy_workflow("${personaId}", workflow_def)`]
+                    : ["Create AI Employee, then deploy workflow"],
+        };
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Demo Data Management Handlers
+    // ─────────────────────────────────────────────────────────────────────────
+    consolidate_demo_data: async (args) => {
+        const fs = await import("fs");
+        const path = await import("path");
+        const sourceDir = String(args.source_dir);
+        const outputDir = String(args.output_dir);
+        const entityType = String(args.entity_type);
+        const primaryFile = String(args.primary_file);
+        const joins = (args.joins ?? []);
+        const idField = String(args.id_field ?? "id");
+        const nameField = String(args.name_field ?? "name");
+        const tags = args.tags ? String(args.tags) : entityType;
+        // Ensure directories exist
+        if (!fs.existsSync(sourceDir)) {
+            throw new Error(`Source directory not found: ${sourceDir}`);
+        }
+        fs.mkdirSync(outputDir, { recursive: true });
+        // Load primary data
+        const primaryPath = path.join(sourceDir, primaryFile);
+        if (!fs.existsSync(primaryPath)) {
+            throw new Error(`Primary file not found: ${primaryPath}`);
+        }
+        const primaryData = JSON.parse(fs.readFileSync(primaryPath, "utf-8"));
+        // Load join data
+        const joinData = {};
+        for (const join of joins) {
+            const joinPath = path.join(sourceDir, join.file);
+            if (fs.existsSync(joinPath)) {
+                joinData[join.as] = JSON.parse(fs.readFileSync(joinPath, "utf-8"));
+            }
+        }
+        // Generate documents
+        const generatedFiles = [];
+        for (const entity of primaryData) {
+            const entityId = String(entity[idField] ?? "unknown");
+            const entityName = String(entity[nameField] ?? entityId);
+            // Collect related data
+            const related = {};
+            for (const join of joins) {
+                const data = joinData[join.as] ?? [];
+                related[join.as] = data.filter((item) => item[join.on] === entityId);
+            }
+            // Generate document content
+            const content = generateEntityDocument(entityType, entity, related, tags);
+            // Write file
+            const sanitizedName = entityName.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+            const sanitizedId = entityId.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+            const filename = `${entityType}_${sanitizedName}_${sanitizedId}.md`;
+            const filePath = path.join(outputDir, filename);
+            fs.writeFileSync(filePath, content);
+            generatedFiles.push(filename);
+        }
+        return {
+            success: true,
+            source_dir: sourceDir,
+            output_dir: outputDir,
+            entity_type: entityType,
+            entities_processed: primaryData.length,
+            files_generated: generatedFiles,
+            next_steps: [
+                `Upload: for each file in ${outputDir}, call knowledge(persona_id="<persona_id>", mode="upload", file="/full/path/to/file.md")`,
+                'Enable RAG: knowledge(persona_id="<persona_id>", mode="toggle", enabled=true)',
+            ],
+        };
+    },
+    generate_demo_document: async (args) => {
+        const fs = await import("fs");
+        const entityType = String(args.entity_type);
+        const data = args.data;
+        const relatedData = (args.related_data ?? {});
+        const outputPath = args.output_path ? String(args.output_path) : undefined;
+        const tags = args.tags ? String(args.tags) : entityType;
+        const content = generateEntityDocument(entityType, data, relatedData, tags);
+        if (outputPath) {
+            fs.writeFileSync(outputPath, content);
+            return {
+                success: true,
+                output_path: outputPath,
+                message: "Document generated and saved",
+            };
+        }
+        return {
+            success: true,
+            content,
+            message: "Document generated (not saved - no output_path provided)",
+        };
+    },
+    validate_demo_document: async (args) => {
+        const fs = await import("fs");
+        let content;
+        if (args.file_path) {
+            if (!fs.existsSync(String(args.file_path))) {
+                throw new Error(`File not found: ${args.file_path}`);
+            }
+            content = fs.readFileSync(String(args.file_path), "utf-8");
+        }
+        else if (args.content) {
+            content = String(args.content);
+        }
+        else {
+            throw new Error("Either file_path or content must be provided");
+        }
+        const issues = [];
+        const suggestions = [];
+        // Check for metadata comments
+        if (!content.includes("<!-- ema_entity:")) {
+            issues.push({ severity: "warning", message: "Missing ema_entity metadata comment" });
+            suggestions.push("Add: <!-- ema_entity: customer | product | employee | scenario -->");
+        }
+        if (!content.includes("<!-- ema_id:")) {
+            issues.push({ severity: "warning", message: "Missing ema_id metadata comment" });
+            suggestions.push("Add: <!-- ema_id: unique-identifier -->");
+        }
+        if (!content.includes("<!-- ema_tags:")) {
+            issues.push({ severity: "info", message: "Missing ema_tags metadata comment" });
+            suggestions.push("Add: <!-- ema_tags: comma, separated, tags -->");
+        }
+        // Check for title
+        if (!content.match(/^# /m)) {
+            issues.push({ severity: "error", message: "Missing document title (# heading)" });
+        }
+        // Check for tables
+        const hasTables = content.includes("|") && content.includes("---");
+        if (!hasTables) {
+            issues.push({ severity: "info", message: "No tables detected - consider adding structured data in table format" });
+        }
+        // Check for narrative content
+        const paragraphCount = content.split(/\n\n/).filter((p) => p.trim().length > 100).length;
+        if (paragraphCount < 1) {
+            issues.push({ severity: "info", message: "Limited narrative content - consider adding relationship summaries for better semantic search" });
+        }
+        // Check filename convention (if file_path provided)
+        if (args.file_path) {
+            const filename = String(args.file_path).split("/").pop() ?? "";
+            if (!filename.match(/^[a-z]+_[a-z0-9_]+\.md$/)) {
+                issues.push({ severity: "info", message: `Filename '${filename}' doesn't follow convention: {entity}_{name}_{id}.md` });
+            }
+        }
+        const criticalCount = issues.filter((i) => i.severity === "error").length;
+        const warningCount = issues.filter((i) => i.severity === "warning").length;
+        return {
+            valid: criticalCount === 0,
+            issues,
+            suggestions,
+            summary: {
+                critical: criticalCount,
+                warnings: warningCount,
+                info: issues.filter((i) => i.severity === "info").length,
+            },
+            recommendation: criticalCount > 0
+                ? "Fix critical issues before uploading"
+                : warningCount > 0
+                    ? "Document is usable but consider addressing warnings"
+                    : "Document follows best practices",
+        };
+    },
+    get_demo_data_template: async (args) => {
+        const entityType = String(args.entity_type);
+        const includeExample = args.include_example !== false;
+        const templates = {
+            customer: {
+                sourceSchema: {
+                    id: "string (required) - Unique customer identifier",
+                    name: "string (required) - Company/customer name",
+                    industry: "string - Industry classification",
+                    tier: "string - Account tier (Enterprise, Mid-Market, SMB)",
+                    accountManager: "string - Assigned account manager",
+                    region: "string - Geographic region",
+                    annualRevenue: "number - Annual revenue",
+                    employeeCount: "string - Employee count range",
+                    contacts: "array - Key contacts [{name, role, email, phone, primary}]",
+                },
+                joinSuggestions: [
+                    { file: "orders.json", on: "customerId", as: "orders" },
+                    { file: "tickets.json", on: "customerId", as: "tickets" },
+                    { file: "notes.json", on: "customerId", as: "notes" },
+                ],
+                outputTemplate: `# Customer: {name}
+
+## Metadata
+<!-- ema_entity: customer -->
+<!-- ema_id: {id} -->
+<!-- ema_tags: {tier}, {industry} -->
+
+## Overview
+| Field | Value |
+|-------|-------|
+| Customer ID | {id} |
+| Company Name | {name} |
+| Industry | {industry} |
+| Account Tier | {tier} |
+
+## Relationship Summary
+[Narrative describing customer relationship, history, and status]
+
+## Orders
+| Order ID | Date | Amount | Status |
+|----------|------|--------|--------|
+[Order rows]
+
+## Support Tickets
+| Ticket ID | Subject | Priority | Status |
+|-----------|---------|----------|--------|
+[Ticket rows]
+
+## Key Contacts
+| Name | Role | Email | Primary |
+|------|------|-------|---------|
+[Contact rows]
+`,
+                bestPractices: [
+                    "Include lifetime value calculation in Overview",
+                    "Add relationship summary with narrative context",
+                    "Include risk indicators for at-risk customers",
+                    "Cross-reference product SKUs in orders",
+                ],
+                example: includeExample ? {
+                    source: {
+                        id: "CUST-001",
+                        name: "Acme Corporation",
+                        industry: "Manufacturing",
+                        tier: "Enterprise",
+                        accountManager: "Sarah Johnson",
+                        contacts: [
+                            { name: "Lisa Park", role: "IT Director", email: "lisa@acme.com", primary: true },
+                        ],
+                    },
+                    related: {
+                        orders: [
+                            { id: "ORD-001", customerId: "CUST-001", date: "2024-01-15", amount: 45000, status: "Delivered" },
+                        ],
+                        tickets: [
+                            { id: "TKT-001", customerId: "CUST-001", subject: "API issue", priority: "High", status: "Open" },
+                        ],
+                    },
+                } : undefined,
+            },
+            product: {
+                sourceSchema: {
+                    sku: "string (required) - Product SKU",
+                    name: "string (required) - Product name",
+                    category: "string - Product category",
+                    price: "number - Unit price",
+                    description: "string - Product description",
+                    specifications: "object - Technical specifications",
+                    compatibility: "array - Compatible product SKUs",
+                    incompatibility: "array - Incompatible product SKUs with reasons",
+                },
+                joinSuggestions: [
+                    { file: "pricing_tiers.json", on: "sku", as: "pricing" },
+                    { file: "customer_purchases.json", on: "sku", as: "customers" },
+                ],
+                outputTemplate: `# Product: {name}
+
+## Metadata
+<!-- ema_entity: product -->
+<!-- ema_id: {sku} -->
+<!-- ema_tags: {category} -->
+
+## Basic Information
+| Field | Value |
+|-------|-------|
+| SKU | {sku} |
+| Name | {name} |
+| Category | {category} |
+| Price | {price} |
+
+## Description
+{description}
+
+## Specifications
+[Technical specs table]
+
+## Compatibility
+| Compatible With | SKU | Notes |
+|-----------------|-----|-------|
+[Compatibility rows]
+
+## Customer Examples
+| Customer | Quantity | Use Case |
+|----------|----------|----------|
+[Customer rows]
+`,
+                bestPractices: [
+                    "Include compatibility matrix",
+                    "Add pricing tiers if applicable",
+                    "Cross-reference customer deployments",
+                    "Include common use cases",
+                ],
+                example: includeExample ? {
+                    source: {
+                        sku: "EWP-100",
+                        name: "Enterprise Widget Pro",
+                        category: "Widgets",
+                        price: 999,
+                        description: "Flagship enterprise widget for mission-critical applications",
+                    },
+                } : undefined,
+            },
+            scenario: {
+                sourceSchema: {
+                    id: "string (required) - Scenario identifier",
+                    name: "string (required) - Scenario name",
+                    description: "string - Scenario overview",
+                    difficulty: "string - Demo difficulty level",
+                    customerContext: "object - Customer data for the scenario",
+                    expectedQueries: "array - Queries the user might ask",
+                    idealResponse: "string - Example ideal AI response",
+                },
+                joinSuggestions: [],
+                outputTemplate: `# Scenario: {name}
+
+## Metadata
+<!-- ema_scenario: {id} -->
+<!-- ema_tags: demo, {difficulty} -->
+
+## Overview
+{description}
+
+## Customer Context
+[Customer details for this scenario]
+
+## Expected Queries
+- "{query1}"
+- "{query2}"
+
+## Ideal Response Pattern
+[How the AI should respond]
+`,
+                bestPractices: [
+                    "Include all context needed to answer expected queries",
+                    "Provide ideal response example",
+                    "List potential edge cases",
+                    "Include escalation triggers",
+                ],
+                example: includeExample ? {
+                    source: {
+                        id: "renewal_high_value",
+                        name: "High-Value Customer Renewal",
+                        description: "Customer up for renewal with competitor evaluation active",
+                        difficulty: "intermediate",
+                    },
+                } : undefined,
+            },
+            employee: {
+                sourceSchema: {
+                    id: "string (required) - Employee ID",
+                    name: "string (required) - Full name",
+                    department: "string - Department",
+                    role: "string - Job title",
+                    manager: "string - Manager name",
+                    email: "string - Email address",
+                    location: "string - Office location",
+                    startDate: "string - Start date",
+                },
+                joinSuggestions: [
+                    { file: "leave_balances.json", on: "employeeId", as: "leave" },
+                    { file: "benefits.json", on: "employeeId", as: "benefits" },
+                ],
+                outputTemplate: `# Employee: {name}
+
+## Metadata
+<!-- ema_entity: employee -->
+<!-- ema_id: {id} -->
+<!-- ema_tags: {department} -->
+
+## Profile
+| Field | Value |
+|-------|-------|
+| Employee ID | {id} |
+| Name | {name} |
+| Department | {department} |
+| Role | {role} |
+| Manager | {manager} |
+
+## Leave Balances
+| Type | Available | Used |
+|------|-----------|------|
+[Leave rows]
+
+## Benefits Enrollment
+| Benefit | Plan | Status |
+|---------|------|--------|
+[Benefits rows]
+`,
+                bestPractices: [
+                    "Include manager hierarchy",
+                    "Add leave balances if HR use case",
+                    "Include benefits enrollment status",
+                    "Consider PII handling requirements",
+                ],
+                example: includeExample ? {
+                    source: {
+                        id: "EMP-001",
+                        name: "Jane Doe",
+                        department: "Engineering",
+                        role: "Senior Engineer",
+                        manager: "John Smith",
+                    },
+                } : undefined,
+            },
+            reference: {
+                sourceSchema: {
+                    category: "string (required) - Reference category",
+                    title: "string (required) - Document title",
+                    content: "string - Main content",
+                    lastUpdated: "string - Last update date",
+                },
+                joinSuggestions: [],
+                outputTemplate: `# {title}
+
+## Metadata
+<!-- ema_doctype: reference -->
+<!-- ema_category: {category} -->
+<!-- ema_last_updated: {lastUpdated} -->
+
+## Content
+{content}
+
+## Related Topics
+[Cross-references to related documents]
+`,
+                bestPractices: [
+                    "Include last updated date",
+                    "Cross-reference related documents",
+                    "Use consistent formatting",
+                    "Add search-friendly summaries",
+                ],
+                example: undefined,
+            },
+        };
+        const template = templates[entityType];
+        if (!template) {
+            throw new Error(`Unknown entity type: ${entityType}. Available: ${Object.keys(templates).join(", ")}`);
+        }
+        return {
+            entity_type: entityType,
+            source_schema: template.sourceSchema,
+            suggested_joins: template.joinSuggestions,
+            output_template: template.outputTemplate,
+            best_practices: template.bestPractices,
+            example: template.example,
+            usage: {
+                consolidate: `demo(mode="consolidate", source="./data/source", output="./data/kb", entity="${entityType}", primary="${entityType}s.json", joins=${JSON.stringify(template.joinSuggestions)})`,
+                generate_single: `demo(mode="generate", entity="${entityType}", data={...}, related={...})`,
+            },
+        };
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // CONSOLIDATED TOOLS (Unix CLI pattern) - 9 tools replace 45
+    // ═══════════════════════════════════════════════════════════════════════════
+    env: async () => {
+        return handleEnv({}, () => getAvailableEnvironments().map(e => ({
+            name: e.name,
+            isDefault: e.name === getDefaultEnvName(),
+        })));
+    },
+    persona: async (args) => {
+        const client = createClient(args.env);
+        const DEFAULT_TEMPLATES = {
+            voice: "00000000-0000-0000-0000-00000000001e",
+            chat: "00000000-0000-0000-0000-000000000004",
+            dashboard: "00000000-0000-0000-0000-000000000002",
+        };
+        return handlePersona(args, client, (type) => DEFAULT_TEMPLATES[type], (env) => createClient(env));
+    },
+    // Note: 'workflow' handler already exists above - consolidated version adds analyze modes
+    // The existing 'workflow' handler is kept for backward compatibility
+    action: async (args) => {
+        const client = createClient(args.env);
+        return handleAction(args, client);
+    },
+    template: async (args) => {
+        return handleTemplate(args);
+    },
+    knowledge: async (args) => {
+        const client = createClient(args.env);
+        const fs = await import("fs/promises");
+        return handleKnowledge(args, client, (path) => fs.readFile(path));
+    },
+    reference: async (args) => {
+        return handleReference(args);
+    },
+    // Note: 'sync' handler already exists above - keeping it for full functionality
+    // Note: demo is handled via a consolidated adapter below
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Consolidated Tool Adapters (contract ↔ implementation)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The tool schemas in tools-consolidated.ts are the public MCP contract.
+// This file still contains a number of proven "legacy" handlers that we reuse
+// (e.g. deploy_workflow, optimize_workflow, compile_workflow, etc.).
+//
+// These adapters ensure the consolidated 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;
+// Unify workflow modes: generate | analyze | deploy | optimize | compare | compile
+toolHandlers.workflow = async (args) => {
+    // Normalize persona type alias: tool schema uses "type", internal uses "persona_type"
+    const normalizedArgs = { ...(args ?? {}) };
+    if (normalizedArgs.persona_type === undefined && normalizedArgs.type !== undefined) {
+        normalizedArgs.persona_type = normalizedArgs.type;
+    }
+    const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
+    const workflowDef = normalizedArgs.workflow_def;
+    const inputProvided = normalizedArgs.input !== undefined;
+    // Normalize mode aliases
+    const rawMode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
+    const mode = rawMode === "improve" ? "optimize" : rawMode;
+    // Default mode selection:
+    // - persona_id + input → optimize (BROWNFIELD: enhance existing workflow)
+    // - persona_id only or workflow_def → analyze (inspect)
+    // - input only → generate (GREENFIELD: create from scratch)
+    // - Otherwise → generate (and prompt for missing info)
+    const effectiveMode = mode ??
+        (personaId && inputProvided ? "optimize" : // BROWNFIELD: existing persona + new requirements
+            workflowDef || personaId ? "analyze" : // Inspect existing
+                "generate"); // GREENFIELD: new workflow
+    switch (effectiveMode) {
+        case "generate": {
+            const result = await legacyWorkflowTool({ ...normalizedArgs, mode: "generate" });
+            // Ensure next_steps point at consolidated tools by default
+            if (result && typeof result === "object") {
+                const obj = result;
+                const persona_id = obj.persona_id ? String(obj.persona_id) : personaId;
+                const deployed = obj.deployed === true;
+                obj.next_steps = deployed
+                    ? persona_id
+                        ? [`Verify: persona(id="${persona_id}", include_workflow=true)`]
+                        : ["Verify the deployed AI Employee in the Ema UI"]
+                    : persona_id
+                        ? [
+                            `Deploy: workflow(mode="deploy", persona_id="${persona_id}", workflow_def=<workflow_def>, proto_config=<proto_config>)`,
+                            `Verify: persona(id="${persona_id}", include_workflow=true)`,
+                        ]
+                        : [
+                            "Create an AI Employee in Ema, then deploy:",
+                            `workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>)`,
+                        ];
+            }
+            return result;
+        }
+        case "analyze": {
+            const include = Array.isArray(normalizedArgs.include)
+                ? normalizedArgs.include.map(String)
+                : ["issues", "connections", "fixes", "metrics"];
+            let wf = workflowDef;
+            let meta;
+            if (!wf && personaId) {
+                const client = createClient(normalizedArgs.env);
+                const persona = await client.getPersonaById(personaId);
+                if (!persona)
+                    throw new Error(`AI Employee not found: ${personaId}`);
+                wf = persona.workflow_def;
+                meta = {
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    environment: client["env"].name,
+                };
+            }
+            if (!wf) {
+                return {
+                    error: "Missing workflow to analyze. Provide persona_id or workflow_def.",
+                    hint: 'Examples: workflow(mode="analyze", persona_id="...") or workflow(mode="analyze", workflow_def={...})',
+                };
+            }
+            const out = { mode: "analyze", ...(meta ?? {}) };
+            // Issues + summary (source of truth)
+            const issuesResult = await legacyDetectWorkflowIssues({ workflow_def: wf });
+            const issues = issuesResult.issues;
+            if (include.includes("issues")) {
+                out.issues = issuesResult.issues;
+                out.issue_summary = issuesResult.summary;
+                out.validation_passed = issuesResult.validation_passed;
+            }
+            if (include.includes("connections")) {
+                out.connections = await legacyValidateWorkflowConnections({ workflow_def: wf });
+            }
+            if (include.includes("fixes")) {
+                out.fixes = Array.isArray(issues) ? await legacySuggestWorkflowFixes({ issues }) : { error: "No issues array available to generate fixes" };
+            }
+            if (include.includes("metrics")) {
+                const actions = wf.actions ?? [];
+                const edges = wf.edges ?? [];
+                out.metrics = {
+                    node_count: Array.isArray(actions) ? actions.length : 0,
+                    edge_count: Array.isArray(edges) ? edges.length : 0,
+                };
+            }
+            return out;
+        }
+        case "deploy": {
+            if (!personaId) {
+                throw new Error('persona_id is required for workflow(mode="deploy")');
+            }
+            const validateFirst = normalizedArgs.validate !== false; // default true
+            const autoFix = normalizedArgs.auto_fix === true; // default false
+            return legacyDeployWorkflow({
+                persona_id: personaId,
+                workflow_def: workflowDef,
+                proto_config: normalizedArgs.proto_config,
+                validate_first: validateFirst,
+                auto_fix: autoFix,
+                env: normalizedArgs.env,
+            });
+        }
+        case "optimize": {
+            // optimize_workflow supports both:
+            // - fix mode: id (name/id) OR persona_id
+            // - generate mode: persona_id + prompt
+            const preview = normalizedArgs.preview === true;
+            const id = normalizedArgs.id ? String(normalizedArgs.id) : undefined;
+            const identifier = normalizedArgs.identifier ? String(normalizedArgs.identifier) : undefined; // deprecated alias
+            const idOrIdentifier = id ?? identifier;
+            // If a natural-language workflow "input" is provided, treat it as a prompt to optimize_workflow.
+            const input = normalizedArgs.input;
+            const prompt = typeof input === "string" ? input : undefined;
+            return legacyOptimizeWorkflow({
+                identifier: idOrIdentifier ?? personaId,
+                persona_id: personaId,
+                prompt,
+                type: normalizedArgs.persona_type,
+                preview,
+                env: normalizedArgs.env,
+            });
+        }
+        case "compare": {
+            if (!personaId) {
+                throw new Error('persona_id is required for workflow(mode="compare")');
+            }
+            const compareTo = normalizedArgs.compare_to ? String(normalizedArgs.compare_to) : undefined;
+            if (!compareTo) {
+                throw new Error('compare_to is required for workflow(mode="compare")');
+            }
+            return legacyCompareWorkflowVersions({
+                persona_id_before: personaId,
+                persona_id_after: compareTo,
+                env: normalizedArgs.env,
+            });
+        }
+        case "compile": {
+            // Compile requires node specs + result mappings.
+            if (!normalizedArgs.name || !normalizedArgs.description) {
+                throw new Error('workflow(mode="compile") requires name and description');
+            }
+            if (!normalizedArgs.persona_type) {
+                throw new Error('workflow(mode="compile") requires persona type via type="voice|chat|dashboard"');
+            }
+            return legacyCompileWorkflow({
+                name: normalizedArgs.name,
+                description: normalizedArgs.description,
+                persona_type: normalizedArgs.persona_type,
+                nodes: normalizedArgs.nodes,
+                result_mappings: normalizedArgs.result_mappings,
+            });
+        }
+        default: {
+            return legacyWorkflowTool({ ...normalizedArgs, mode: effectiveMode });
+        }
+    }
+};
+// Unify sync modes: run | status | config
+toolHandlers.sync = async (args) => {
+    const normalizedArgs = { ...(args ?? {}) };
+    const rawMode = normalizedArgs.mode ? String(normalizedArgs.mode) : "run";
+    const mode = rawMode;
+    // Support both old and new arg names
+    const target = (normalizedArgs.target ?? normalizedArgs.target_env);
+    const source = (normalizedArgs.source ?? normalizedArgs.source_env);
+    const id = normalizedArgs.id;
+    const identifier = normalizedArgs.identifier; // deprecated alias
+    const idOrIdentifier = id ?? identifier;
+    if (mode === "config") {
+        return legacySyncInfo({ include_options: true });
+    }
+    if (mode === "status") {
+        const env = normalizedArgs.env;
+        if (normalizedArgs.list_synced === true) {
+            if (!env)
+                throw new Error('env is required for sync(mode="status", list_synced=true)');
+            return legacySyncInfo({ list_synced: true, master_env: normalizedArgs.master_env, env });
+        }
+        if (idOrIdentifier) {
+            if (!env)
+                throw new Error('env is required for sync(mode="status", id="...")');
+            const identifierToResolve = String(idOrIdentifier);
+            const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(identifierToResolve);
+            if (isUUID) {
+                return legacySyncInfo({ persona_id: identifierToResolve, env });
+            }
+            // Name lookup: resolve to ID in env, then reuse persona_id path
+            const client = createClient(env);
+            const personas = await client.getPersonasForTenant();
+            const match = personas.find((p) => p.name === identifierToResolve);
+            if (!match)
+                throw new Error(`AI Employee not found by name in ${env}: ${identifierToResolve}`);
+            return legacySyncInfo({ persona_id: match.id, env });
+        }
+        // Default: overall sync status/config summary
+        return legacySyncInfo({ include_options: normalizedArgs.include_options === true });
+    }
+    // mode === "run" (default)
+    if (!target) {
+        throw new Error('target (or target_env) is required for sync(mode="run")');
+    }
+    return legacySyncRun({
+        identifier: idOrIdentifier,
+        target_env: target,
+        source_env: source,
+        scope: normalizedArgs.scope,
+        dry_run: normalizedArgs.dry_run,
+        include_status: normalizedArgs.include_status,
+    });
+};
+// Consolidated demo tool: consolidate | generate | validate | template
+toolHandlers.demo = async (args) => {
+    const normalizedArgs = { ...(args ?? {}) };
+    const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
+    switch (mode) {
+        case "consolidate": {
+            const source = String(normalizedArgs.source ?? "");
+            const output = String(normalizedArgs.output ?? "");
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!source || !output || !entity) {
+                throw new Error('demo(mode="consolidate") requires: source, output, entity');
+            }
+            return legacyConsolidateDemoData({
+                source_dir: source,
+                output_dir: output,
+                entity_type: entity,
+                primary_file: normalizedArgs.primary ?? `${entity}s.json`,
+                joins: normalizedArgs.joins ?? [],
+                tags: normalizedArgs.tags,
+            });
+        }
+        case "generate": {
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!entity)
+                throw new Error('demo(mode="generate") requires: entity');
+            return legacyGenerateDemoDocument({
+                entity_type: entity,
+                data: normalizedArgs.data ?? {},
+                related_data: normalizedArgs.related ?? {},
+                output_path: normalizedArgs.output,
+                tags: normalizedArgs.tags,
+            });
+        }
+        case "validate": {
+            return legacyValidateDemoDocument({
+                file_path: normalizedArgs.file,
+                content: normalizedArgs.content,
+            });
+        }
+        case "template": {
+            const entity = String(normalizedArgs.entity ?? "");
+            if (!entity)
+                throw new Error('demo(mode="template") requires: entity');
+            return legacyGetDemoDataTemplate({
+                entity_type: entity,
+                include_example: normalizedArgs.include_example,
+            });
+        }
+        default:
+            throw new Error(`Unknown demo mode: ${mode}`);
+    }
+};
+// Helper function for document generation
+function generateEntityDocument(entityType, entity, related, tags) {
+    const id = String(entity.id ?? entity.sku ?? entity.employeeId ?? "unknown");
+    const name = String(entity.name ?? entity.title ?? id);
+    let content = `# ${entityType.charAt(0).toUpperCase() + entityType.slice(1)}: ${name}
+
+## Metadata
+<!-- ema_entity: ${entityType} -->
+<!-- ema_id: ${id} -->
+<!-- ema_tags: ${tags} -->
+<!-- ema_generated: ${new Date().toISOString().split("T")[0]} -->
+
+## Overview
+| Field | Value |
+|-------|-------|
+`;
+    // Add entity fields to overview table
+    const skipFields = ["contacts", "items", "notes"];
+    for (const [key, value] of Object.entries(entity)) {
+        if (!skipFields.includes(key) && value !== null && value !== undefined && typeof value !== "object") {
+            const displayKey = key.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase());
+            const displayValue = typeof value === "number" && key.toLowerCase().includes("revenue")
+                ? `$${value.toLocaleString()}`
+                : String(value);
+            content += `| ${displayKey} | ${displayValue} |\n`;
+        }
+    }
+    // Add relationship summary
+    const relationshipParts = [];
+    for (const [key, items] of Object.entries(related)) {
+        if (items.length > 0) {
+            relationshipParts.push(`${items.length} ${key}`);
+        }
+    }
+    if (relationshipParts.length > 0) {
+        content += `\n## Relationship Summary\nThis ${entityType} has ${relationshipParts.join(", ")}.\n`;
+    }
+    // Add contacts if present
+    const contacts = entity.contacts;
+    if (contacts && contacts.length > 0) {
+        content += `\n## Key Contacts
+| Name | Role | Email | Primary |
+|------|------|-------|---------|
+`;
+        for (const contact of contacts) {
+            content += `| ${contact.name ?? ""} | ${contact.role ?? ""} | ${contact.email ?? ""} | ${contact.primary ? "Yes" : "No"} |\n`;
+        }
+    }
+    // Add related data sections
+    for (const [key, items] of Object.entries(related)) {
+        if (items.length > 0) {
+            const sectionTitle = key.charAt(0).toUpperCase() + key.slice(1);
+            content += `\n## ${sectionTitle} (${items.length} total)\n`;
+            // Get all unique keys from items
+            const allKeys = new Set();
+            for (const item of items) {
+                const itemObj = item;
+                for (const k of Object.keys(itemObj)) {
+                    if (typeof itemObj[k] !== "object")
+                        allKeys.add(k);
+                }
+            }
+            const keys = Array.from(allKeys).slice(0, 6); // Limit columns
+            // Create table header
+            content += `| ${keys.map((k) => k.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase())).join(" | ")} |\n`;
+            content += `|${keys.map(() => "---").join("|")}|\n`;
+            // Add rows
+            for (const item of items.slice(0, 10)) { // Limit rows
+                const itemObj = item;
+                const values = keys.map((k) => {
+                    const v = itemObj[k];
+                    if (typeof v === "number" && k.toLowerCase().includes("amount")) {
+                        return `$${v.toLocaleString()}`;
+                    }
+                    return String(v ?? "");
+                });
+                content += `| ${values.join(" | ")} |\n`;
+            }
+            if (items.length > 10) {
+                content += `\n*...and ${items.length - 10} more*\n`;
+            }
+        }
+    }
+    return content;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Server Setup
+// ─────────────────────────────────────────────────────────────────────────────
+// Initialize registries
+const promptRegistry = new PromptRegistry();
+const resourceRegistry = new ResourceRegistry();
+export async function startMcpServer() {
+    const server = new Server({ name: "ema", version: "1.0.0" }, {
+        capabilities: {
+            tools: {},
+            prompts: {},
+            resources: {},
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────────────
+    // Tool Handlers
+    // ─────────────────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = toolHandlers[name];
+        if (!handler) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await handler((args ?? {}));
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error instanceof Error ? error.message : String(error) }) }],
+                isError: true,
+            };
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────────────
+    // Prompt Handlers
+    // ─────────────────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        const prompts = promptRegistry.list();
+        return {
+            prompts: prompts.map((p) => ({
+                name: p.name,
+                description: p.description,
+                arguments: p.arguments.map((a) => ({
+                    name: a.name,
+                    description: a.description,
+                    required: a.required,
+                })),
+            })),
+        };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const result = promptRegistry.get(name, args);
+        if (isPromptError(result)) {
+            throw new Error(`${result.code}: ${result.message}`);
+        }
+        return {
+            description: result.description,
+            messages: result.messages.map((m) => ({
+                role: m.role,
+                content: m.content,
+            })),
+        };
+    });
+    // ─────────────────────────────────────────────────────────────────────────
+    // Resource Handlers
+    // ─────────────────────────────────────────────────────────────────────────
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const resources = resourceRegistry.list();
+        return {
+            resources: resources.map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        const result = await resourceRegistry.read(uri);
+        if (isResourceError(result)) {
+            throw new Error(`${result.code}: ${result.message}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: result.uri,
+                    mimeType: result.mimeType,
+                    text: result.text,
+                },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Ema MCP Server started (multi-env) with prompts and resources");
+}
+startMcpServer().catch((error) => {
+    console.error("Failed to start MCP server:", error);
+    process.exit(1);
+});