@ema.co/mcp-toolkit 2026.1.26-4 → 2026.1.27

package/dist/sdk/knowledge.js

@@ -1,11 +1,27 @@
 /**
- * Auto Builder Knowledge Base
+ * Ema Platform Knowledge Base
  *
- * Structured knowledge about Ema Auto Builder and AI Employee platform for MCP exposure.
- * Sources:
- * - Ema User Guide documentation
- * - Platform best practices
- * - Validated patterns from production workflows
+ * This file contains TWO types of content:
+ *
+ * 1. AUTO-GENERATED (API Fallbacks)
+ *    - AGENT_CATALOG, WIDGET_CATALOG, TYPE_COMPATIBILITY
+ *    - Generated from source repos via scheduled workflows
+ *    - Used as fallbacks when API unavailable
+ *    - TODO: Move to src/sdk/generated/ and import here
+ *
+ * 2. CURATED KNOWLEDGE (Human-Maintained)
+ *    - PLATFORM_CONCEPTS, WORKFLOW_PATTERNS, GUIDANCE_TOPICS, etc.
+ *    - Source repos are INPUT, not law
+ *    - Optimized for customer-facing MCP users
+ *    - Updated via knowledge scanning workflow + human review
+ *
+ * Input Sources (for curated content):
+ * - ema-repos/ema/docs/ - Platform documentation
+ * - ema-repos/ema/workflow_actions/documentation/ - Agent docs
+ * - ema-repos/protos/ - Type definitions
+ * - Support cases and real-world usage patterns
+ *
+ * See: .ctx/docs/source-repos.md for full architecture
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Platform Concepts (from Ema User Guide)
@@ -718,19 +734,66 @@ export const AGENT_CATALOG = [
 // ─────────────────────────────────────────────────────────────────────────────
 // Widget Reference
 // ─────────────────────────────────────────────────────────────────────────────
+// ═══════════════════════════════════════════════════════════════════════════════════
+// WIDGET_CATALOG (NO API ALTERNATIVE - Intentionally Static)
+// ═══════════════════════════════════════════════════════════════════════════════════
+// 
+// WHY STATIC: There is no API endpoint to list widget definitions. Widget metadata
+// lives in persona template YAML files and is not exposed via the API.
+//
+// RUNTIME ALTERNATIVE: For a specific persona, fetch widgets dynamically via:
+//   persona(id="...", include_workflow=true) → proto_config.widgets[].name
+//
+// SOURCE: ema-repos/ema/ema_backend/db/system_values/persona_templates/prod/*.yaml
+// SYNC: Manual - run knowledge scan workflow to detect template changes
+// 
+// TECHNICAL NOTES:
+// - Widget 'id' is the WidgetType enum value from protos
+// - Widget 'name' is assigned per-template (e.g., "upload", "upload1", "upload2")
+// - Proto 'case' values represent TYPE discriminators, not widget names
+// 
+// See .ctx/docs/source-repos.md for full sync instructions
+// ═══════════════════════════════════════════════════════════════════════════════════
 export const WIDGET_CATALOG = [
+    // ═══════════════════════════════════════════════════════════════════════════
     // Voice AI Widgets
-    { id: 38, name: "voiceSettings", description: "Language hints, voice model selection", requiredFor: ["voice"], fields: ["languageHints", "voiceModel"] },
-    { id: 39, name: "conversationSettings", description: "Identity, purpose, action instructions, hangup rules - core persona configuration", requiredFor: ["voice"], fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions", "transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"] },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SOURCE: voicebot_ai_employee.yaml
+    // LAST VERIFIED: 2026-01-27
+    { id: 38, name: "voiceSettings", description: "Language hints, voice model selection (title: 'Voice and language')", requiredFor: ["voice"], fields: ["languageHints", "voiceModel"] },
+    { id: 39, name: "conversationSettings", description: "Identity, purpose, action instructions, hangup rules (title: 'Conversational behavior')", requiredFor: ["voice"], fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions", "transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"] },
     { id: 43, name: "vadSettings", description: "Voice activity detection settings", requiredFor: ["voice"], fields: ["turnTimeout", "silenceEndCallTimeout", "maxConversationDuration"] },
     { id: 42, name: "dataStorageSettings", description: "Audio/transcript recording settings", requiredFor: ["voice"], fields: ["storeAudioRecording", "storeTranscripts", "storeAgentTranscript"] },
+    { id: 41, name: "callSettings", description: "Call forwarding, spam prevention settings", requiredFor: ["voice"], fields: ["enableCallForwarding", "callForwardingNumber", "enableSpamCallPrevention"] },
+    { id: 44, name: "voicebotPhoneNumber", description: "Phone number configuration (title: 'Phone numbers')", requiredFor: ["voice"], fields: ["phoneNumber"] },
+    { id: 40, name: "voicebotFeedbackCollection", description: "Post-call feedback collection (title: 'Feedback collection')", requiredFor: ["voice"], fields: [] },
+    // ═══════════════════════════════════════════════════════════════════════════
     // Chat AI Widgets
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SOURCE: TBD - need to verify from chat template
     { id: 28, name: "chatbotSdkConfig", description: "Chat widget configuration and theming", requiredFor: ["chat"], fields: ["theme", "position", "initialMessage"] },
     { id: 33, name: "feedbackMessage", description: "Feedback collection settings", requiredFor: ["chat"], fields: ["enabled", "prompt"] },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Document Generation Widgets
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SOURCE: ema-repos/ema/ema_backend/db/system_values/persona_templates/prod/document_proposal_manager.yaml
+    // NOTE: Widget names are defined per-template. These are from Document Proposal Manager.
+    //       To sync: see .ctx/docs/source-repos.md
+    // LAST VERIFIED: 2026-01-27 from document_proposal_manager.yaml
+    { id: 3, name: "upload", description: "Content Repository - gold standard company docs (title: 'Content Repository')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
+    { id: 3, name: "upload1", description: "Service Line Documents - business unit specific content (title: 'Service Line Documents')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
+    { id: 3, name: "upload2", description: "Style Guide - formatting and tone guide (title: 'Style Guide')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
+    { id: 29, name: "fileTagging0", description: "File tagging configuration (title: 'Set Tags')", requiredFor: ["document"], fields: ["tagTypes", "fileTagMappings"] },
+    { id: 5, name: "answerFormat0", description: "Proposal instructions - format, tone, language (title: 'Proposal Instructions')", requiredFor: ["document"], fields: ["textValue"] },
+    { id: 16, name: "sectionConfigWidget", description: "Section categories with instructions (title: 'Section Categories')", requiredFor: ["document"], fields: ["sections"] },
+    // ═══════════════════════════════════════════════════════════════════════════
     // Common Widgets (all types)
-    { id: 3, name: "fileUpload", description: "Document upload configuration", requiredFor: ["voice", "chat", "dashboard"], fields: ["allowedTypes", "maxSize"] },
-    { id: 6, name: "fusionModel", description: "EmaFusion model selection (GPT-4, Claude, etc.)", requiredFor: ["voice", "chat", "dashboard"], fields: ["allModels", "selectedModels"] },
-    { id: 8, name: "dataProtection", description: "PII redaction settings", requiredFor: ["voice", "chat", "dashboard"], fields: ["protectedClasses"] },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // These appear across multiple template types
+    { id: 3, name: "fileUpload", description: "Default document upload (KB files, title: 'Data sources')", requiredFor: ["voice", "chat", "dashboard"], fields: ["allowedTypes", "maxSize"], uploadTarget: true },
+    { id: 6, name: "fusionModel", description: "EmaFusion model selection (GPT-4, Claude, etc., title: 'EmaFusion™ model')", requiredFor: ["voice", "chat", "dashboard", "document"], fields: ["allModels", "selectedModels"] },
+    { id: 8, name: "dataProtection", description: "PII redaction settings", requiredFor: ["voice", "chat", "dashboard", "document"], fields: ["protectedClasses"] },
+    { id: 9, name: "copyrightCheck", description: "Copyright infringement checker (title: 'Copyright Checker')", requiredFor: ["document"], fields: [] },
 ];
 // Project type mapping
 export const PROJECT_TYPES = {
@@ -740,7 +803,18 @@ export const PROJECT_TYPES = {
     document: 3,
 };
 // ─────────────────────────────────────────────────────────────────────────────
-// Type Compatibility
+// Type Compatibility (CANONICAL SOURCE)
+// ─────────────────────────────────────────────────────────────────────────────
+// This is the canonical, user-facing documentation of type compatibility.
+//
+// SOURCE: ema-repos/protos/service/workflows/v1/well_known.proto
+// SYNC: TODO - Add to catalog-sync.yml workflow for automatic updates
+//
+// Other type compatibility definitions serve different purposes:
+// - INTENT_TYPE_ROUTING (workflow-intent.ts) - routing logic during intent processing
+// - SCHEMA_TYPE_COMPATIBILITY (action-schema-parser.ts) - input name matching for validation
+//
+// See .ctx/docs/source-repos.md for full architecture
 // ─────────────────────────────────────────────────────────────────────────────
 export const TYPE_COMPATIBILITY = [
     // Chat conversation compatibility
@@ -1461,6 +1535,13 @@ export function getAgentByName(actionName) {
 export function getWidgetsForPersonaType(type) {
     return WIDGET_CATALOG.filter(w => w.requiredFor.includes(type));
 }
+/**
+ * Get widgets that accept file uploads for a persona type.
+ * Use these widget names with data(method="upload", widget_name="...").
+ */
+export function getUploadWidgetsForPersonaType(type) {
+    return WIDGET_CATALOG.filter(w => w.requiredFor.includes(type) && w.uploadTarget);
+}
 export function checkTypeCompatibility(sourceType, targetType) {
     return TYPE_COMPATIBILITY.find(t => t.sourceType === sourceType && t.targetType === targetType);
 }
@@ -1702,570 +1783,6 @@ export function parseWorkflowDef(workflowDef) {
     }
     return nodes;
 }
-/**
- * Build an adjacency list from workflow nodes
- */
-function buildAdjacencyList(nodes) {
-    const adj = new Map();
-    // Initialize all nodes
-    for (const node of nodes) {
-        if (!adj.has(node.id)) {
-            adj.set(node.id, new Set());
-        }
-    }
-    // Build edges from incoming_edges (reverse direction for adjacency)
-    for (const node of nodes) {
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                const sourceId = edge.source_node_id;
-                if (!adj.has(sourceId)) {
-                    adj.set(sourceId, new Set());
-                }
-                adj.get(sourceId).add(node.id);
-            }
-        }
-    }
-    return adj;
-}
-/**
- * Detect cycles in the workflow graph using DFS
- */
-function detectCycles(nodes) {
-    const issues = [];
-    const adj = buildAdjacencyList(nodes);
-    const visited = new Set();
-    const recStack = new Set();
-    const cycleNodes = [];
-    function dfs(nodeId, path) {
-        visited.add(nodeId);
-        recStack.add(nodeId);
-        const neighbors = adj.get(nodeId) ?? new Set();
-        for (const neighbor of neighbors) {
-            if (!visited.has(neighbor)) {
-                if (dfs(neighbor, [...path, nodeId])) {
-                    return true;
-                }
-            }
-            else if (recStack.has(neighbor)) {
-                // Found cycle
-                const cycleStart = path.indexOf(neighbor);
-                if (cycleStart >= 0) {
-                    cycleNodes.push(...path.slice(cycleStart), nodeId);
-                }
-                else {
-                    cycleNodes.push(neighbor, nodeId);
-                }
-                return true;
-            }
-        }
-        recStack.delete(nodeId);
-        return false;
-    }
-    for (const node of nodes) {
-        if (!visited.has(node.id)) {
-            if (dfs(node.id, [])) {
-                issues.push({
-                    type: "cycle",
-                    severity: "critical",
-                    nodes: [...new Set(cycleNodes)],
-                    auto_fixable: false, // Cycles require manual restructuring
-                    reason: `Circular dependency detected: ${cycleNodes.join(" → ")}`,
-                });
-                break; // One cycle is enough to report
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Find nodes that consume outputs from a given node (have incoming_edges from it)
- */
-function findNodeConsumers(nodeId, nodes) {
-    const consumers = [];
-    for (const n of nodes) {
-        if (n.incoming_edges) {
-            for (const edge of n.incoming_edges) {
-                if (edge.source_node_id === nodeId) {
-                    consumers.push(n.id);
-                    break; // Only count each consumer once
-                }
-            }
-        }
-    }
-    return consumers;
-}
-/**
- * Detect orphan nodes (not reachable from trigger)
- * Also tracks dependent nodes for cascading fix
- */
-function detectOrphanNodes(nodes) {
-    const issues = [];
-    const adj = buildAdjacencyList(nodes);
-    // Find trigger node
-    const triggerNode = nodes.find(n => n.action_name?.includes("trigger") ||
-        n.id === "trigger" ||
-        (n.id && n.id.includes("trigger")));
-    if (!triggerNode) {
-        return []; // Can't detect orphans without trigger
-    }
-    // BFS from trigger
-    const reachable = new Set();
-    const queue = [triggerNode.id];
-    reachable.add(triggerNode.id);
-    while (queue.length > 0) {
-        const current = queue.shift();
-        const neighbors = adj.get(current) ?? new Set();
-        for (const neighbor of neighbors) {
-            if (!reachable.has(neighbor)) {
-                reachable.add(neighbor);
-                queue.push(neighbor);
-            }
-        }
-    }
-    // Find unreachable nodes and their consumers
-    for (const node of nodes) {
-        if (!reachable.has(node.id) && node.id !== "WORKFLOW_OUTPUT") {
-            const consumers = findNodeConsumers(node.id, nodes);
-            // Filter to only reachable consumers (we'll fix their dangling refs)
-            const reachableConsumers = consumers.filter(c => reachable.has(c));
-            issues.push({
-                type: "orphan",
-                severity: "warning",
-                node: node.id,
-                dependent_nodes: reachableConsumers.length > 0 ? reachableConsumers : undefined,
-                auto_fixable: true, // Always fixable - we remove node AND clean up dangling refs
-                reason: reachableConsumers.length > 0
-                    ? `Node "${node.id}" is not reachable from trigger. Removing will also clean dangling refs in: ${reachableConsumers.join(", ")}`
-                    : `Node "${node.id}" is not reachable from trigger`,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect dead-end nodes (nodes that don't lead to WORKFLOW_OUTPUT)
- */
-function detectDeadEnds(nodes) {
-    const issues = [];
-    // Build reverse adjacency (target -> sources)
-    const reverseAdj = new Map();
-    for (const node of nodes) {
-        if (!reverseAdj.has(node.id)) {
-            reverseAdj.set(node.id, new Set());
-        }
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                if (!reverseAdj.has(edge.source_node_id)) {
-                    reverseAdj.set(edge.source_node_id, new Set());
-                }
-                reverseAdj.get(node.id).add(edge.source_node_id);
-            }
-        }
-    }
-    // Find WORKFLOW_OUTPUT or nodes that connect to it
-    const outputNode = nodes.find(n => n.id === "WORKFLOW_OUTPUT" ||
-        n.action_name === "WorkflowOutputSink");
-    if (!outputNode) {
-        issues.push({
-            type: "missing_workflow_output",
-            severity: "critical",
-            auto_fixable: true, // Can add results mapping for Voice AI
-            reason: "No WORKFLOW_OUTPUT node found - workflow responses won't reach user",
-        });
-        return issues;
-    }
-    // BFS backwards from WORKFLOW_OUTPUT to find all nodes that can reach it
-    const canReachOutput = new Set();
-    const queue = [outputNode.id];
-    canReachOutput.add(outputNode.id);
-    // Also add nodes that have edges TO WORKFLOW_OUTPUT
-    for (const node of nodes) {
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                if (node.id === outputNode.id) {
-                    canReachOutput.add(edge.source_node_id);
-                    queue.push(edge.source_node_id);
-                }
-            }
-        }
-    }
-    // Continue BFS
-    while (queue.length > 0) {
-        const current = queue.shift();
-        const sources = reverseAdj.get(current) ?? new Set();
-        for (const source of sources) {
-            if (!canReachOutput.has(source)) {
-                canReachOutput.add(source);
-                queue.push(source);
-            }
-        }
-    }
-    // Find leaf nodes (no outgoing edges) that can't reach output
-    const adj = buildAdjacencyList(nodes);
-    for (const node of nodes) {
-        const neighbors = adj.get(node.id) ?? new Set();
-        if (neighbors.size === 0 &&
-            node.id !== outputNode.id &&
-            !node.id?.includes("trigger") &&
-            !canReachOutput.has(node.id)) {
-            issues.push({
-                type: "dead_end",
-                severity: "critical",
-                node: node.id,
-                missing: "WORKFLOW_OUTPUT connection",
-                auto_fixable: true, // Can add results mapping or edge
-                reason: `Node "${node.id}" doesn't lead to WORKFLOW_OUTPUT - responses won't reach user`,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect nodes whose outputs are not consumed by any other node
- * This catches anti-patterns like "combine_search_results but output not used"
- */
-function detectUnusedOutputs(nodes, workflowDef) {
-    const issues = [];
-    // Build set of all consumed node outputs
-    const consumedOutputs = new Set(); // Format: "nodeId.outputName"
-    for (const node of nodes) {
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                consumedOutputs.add(`${edge.source_node_id}.${edge.source_output}`);
-                // Also mark node as having at least one output consumed
-                consumedOutputs.add(`${edge.source_node_id}.*`);
-            }
-        }
-    }
-    // Check results mapping - outputs that go to WORKFLOW_OUTPUT are consumed
-    const def = workflowDef;
-    const results = def?.results;
-    if (results) {
-        for (const [, result] of Object.entries(results)) {
-            if (result?.actionName) {
-                consumedOutputs.add(`${result.actionName}.${result.outputName ?? "*"}`);
-                consumedOutputs.add(`${result.actionName}.*`);
-            }
-        }
-    }
-    // Nodes that produce output but should have downstream consumers
-    // Especially combiners, generators, and transformers
-    const NODES_THAT_PRODUCE_OUTPUT = [
-        "combine_search_results",
-        "personalized_content_generator",
-        "generate_document",
-        "json_mapper",
-        "entity_extraction",
-        "entity_extraction_with_documents",
-        "conversation_summarizer",
-        "custom_agent",
-        "creative_ideation_agent",
-        "response_validator",
-    ];
-    for (const node of nodes) {
-        const actionName = node.action_name?.toLowerCase()?.replace(/_/g, "") ?? "";
-        const nodeId = node.id ?? "";
-        const nodeIdNormalized = nodeId.toLowerCase().replace(/_/g, "");
-        // Skip trigger and output nodes
-        if (nodeId.includes("trigger") || nodeId === "WORKFLOW_OUTPUT") {
-            continue;
-        }
-        // Check if this is a node that should have its output consumed
-        // Normalize both sides by removing underscores for comparison
-        const shouldHaveOutputConsumed = NODES_THAT_PRODUCE_OUTPUT.some(name => {
-            const normalized = name.replace(/_/g, "");
-            return actionName.includes(normalized) || nodeIdNormalized.includes(normalized);
-        });
-        if (shouldHaveOutputConsumed) {
-            // Check if any output from this node is consumed
-            const isConsumed = consumedOutputs.has(`${nodeId}.*`);
-            if (!isConsumed) {
-                // Determine what the expected output would be
-                let expectedOutput = "output";
-                if (actionName.includes("combine")) {
-                    expectedOutput = "combined_results";
-                }
-                else if (actionName.includes("generate_document") || nodeId.toLowerCase().includes("generate_document")) {
-                    expectedOutput = "document_link";
-                }
-                else if (actionName.includes("entity_extraction") || nodeId.toLowerCase().includes("entity")) {
-                    expectedOutput = "extracted_entities";
-                }
-                else if (actionName.includes("json_mapper") || nodeId.toLowerCase().includes("mapper")) {
-                    expectedOutput = "mapped_output";
-                }
-                else if (actionName.includes("content_generator") || nodeId.toLowerCase().includes("content")) {
-                    expectedOutput = "generated_content";
-                }
-                issues.push({
-                    type: "unused_output",
-                    severity: "warning",
-                    node: nodeId,
-                    current: expectedOutput,
-                    auto_fixable: false, // Requires understanding intent to wire correctly
-                    reason: `Node "${nodeId}" produces output "${expectedOutput}" but it's not consumed by any downstream node. This node is doing work that goes nowhere.`,
-                });
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Detect categorizer issues (missing fallback, missing category edges)
- */
-function detectCategorizerIssues(nodes) {
-    const issues = [];
-    const categorizers = nodes.filter(n => n.action_name?.includes("categorizer") ||
-        n.id?.includes("categorizer") ||
-        n.id?.includes("classifier"));
-    for (const categorizer of categorizers) {
-        // Check if there are any outgoing edges (category routes)
-        const adj = buildAdjacencyList(nodes);
-        const outgoing = adj.get(categorizer.id) ?? new Set();
-        if (outgoing.size === 0) {
-            issues.push({
-                type: "missing_category_edge",
-                severity: "critical",
-                node: categorizer.id,
-                auto_fixable: false, // Requires defining categories and handlers
-                reason: `Categorizer "${categorizer.id}" has no outgoing category edges - routing won't work`,
-            });
-        }
-        // Check for Fallback - multiple ways to configure:
-        // 1. default_category input set to a fallback-like value
-        // 2. Outgoing edges with "fallback" in the source_output
-        // 3. Category handlers wired to fallback output
-        let hasFallback = false;
-        // Check default_category input (most common way to set fallback)
-        const params = categorizer.parameters;
-        if (params?.default_category) {
-            const defaultCat = params.default_category;
-            const defaultValue = defaultCat?.inline?.enumValue?.toLowerCase() || "";
-            if (defaultValue && ["fallback", "other", "general", "unknown", "default"].includes(defaultValue)) {
-                hasFallback = true;
-            }
-        }
-        // Also check for edges with fallback in the name
-        if (!hasFallback) {
-            for (const node of nodes) {
-                if (node.incoming_edges) {
-                    for (const edge of node.incoming_edges) {
-                        if (edge.source_node_id === categorizer.id &&
-                            (edge.source_output?.toLowerCase().includes("fallback"))) {
-                            hasFallback = true;
-                            break;
-                        }
-                    }
-                }
-                if (hasFallback)
-                    break;
-            }
-        }
-        if (!hasFallback && outgoing.size > 0) {
-            issues.push({
-                type: "missing_fallback",
-                severity: "critical",
-                node: categorizer.id,
-                auto_fixable: true, // Can add Fallback category to enumType
-                reason: `Categorizer "${categorizer.id}" appears to be missing a Fallback category`,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect HITL issues (missing success or failure paths)
- */
-function detectHitlIssues(nodes) {
-    const issues = [];
-    const hitlNodes = nodes.filter(n => n.action_name?.includes("hitl") ||
-        n.action_name?.includes("human_collaboration") ||
-        n.id?.includes("hitl") ||
-        n.id?.includes("approval"));
-    for (const hitl of hitlNodes) {
-        let hasSuccess = false;
-        let hasFailure = false;
-        // Look for edges from this HITL node (direct input connections)
-        for (const node of nodes) {
-            if (node.incoming_edges) {
-                for (const edge of node.incoming_edges) {
-                    if (edge.source_node_id === hitl.id) {
-                        const output = edge.source_output?.toLowerCase() ?? "";
-                        if (output.includes("success")) {
-                            hasSuccess = true;
-                        }
-                        if (output.includes("fail")) {
-                            hasFailure = true;
-                        }
-                    }
-                }
-            }
-            // Also check runIf conditions (conditional execution pattern)
-            // This handles workflows that use runIf instead of direct edges
-            // Pattern: runIf.lhs.actionOutput.actionName === hitl.id && runIf.rhs.enumValue contains "Success"/"Failure"
-            if (node.runIf && typeof node.runIf === "object") {
-                const runIf = node.runIf;
-                const lhs = runIf.lhs;
-                const rhs = runIf.rhs;
-                if (lhs?.actionOutput) {
-                    const actionOutput = lhs.actionOutput;
-                    if (actionOutput.actionName === hitl.id) {
-                        // This node has a runIf condition referencing the HITL node
-                        const rhsValue = rhs?.inline?.enumValue ?? "";
-                        const rhsLower = rhsValue.toLowerCase();
-                        if (rhsLower.includes("success")) {
-                            hasSuccess = true;
-                        }
-                        if (rhsLower.includes("fail")) {
-                            hasFailure = true;
-                        }
-                    }
-                }
-            }
-        }
-        if (!hasSuccess && !hasFailure) {
-            issues.push({
-                type: "incomplete_hitl",
-                severity: "critical",
-                node: hitl.id,
-                missing: "both success and failure paths",
-                auto_fixable: false, // Requires defining response handlers
-                reason: `HITL node "${hitl.id}" missing both success AND failure paths`,
-            });
-        }
-        else if (!hasSuccess) {
-            issues.push({
-                type: "incomplete_hitl",
-                severity: "critical",
-                node: hitl.id,
-                missing: "success_path",
-                auto_fixable: false, // Requires defining success response
-                reason: `HITL node "${hitl.id}" missing success path`,
-            });
-        }
-        else if (!hasFailure) {
-            issues.push({
-                type: "incomplete_hitl",
-                severity: "critical",
-                node: hitl.id,
-                missing: "failure_path",
-                auto_fixable: false, // Requires defining failure response
-                reason: `HITL node "${hitl.id}" missing failure path`,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect wrong input source issues (e.g., user_query for categorizer instead of chat_conversation)
- */
-function detectWrongInputSource(nodes) {
-    const issues = [];
-    for (const node of nodes) {
-        const actionName = node.action_name ?? node.id;
-        // Use the shared validation rules (single source of truth)
-        const rule = findInputSourceRule(actionName);
-        if (!rule)
-            continue;
-        // For send_email nodes, the rule only applies to email_to/recipient inputs
-        // Other inputs (subject, body) can legitimately use LLM/text outputs
-        const isEmailNode = actionName.includes("email") || actionName.includes("send_email");
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                const sourceOutput = edge.source_output?.toLowerCase() ?? "";
-                const targetInput = edge.target_input?.toLowerCase() ?? "";
-                // For email nodes, only check the email_to/recipient input, not all inputs
-                if (isEmailNode) {
-                    const isRecipientInput = targetInput.includes("email_to") ||
-                        targetInput.includes("to_email") ||
-                        targetInput.includes("recipient") ||
-                        targetInput.includes("to_address");
-                    if (!isRecipientInput)
-                        continue; // Skip non-recipient inputs for email nodes
-                }
-                // Check if source is in the allowlist (skip if explicitly allowed)
-                const allowlist = rule.allowlist ?? [];
-                if (allowlist.length > 0) {
-                    const isAllowed = allowlist.some(allowed => sourceOutput.includes(allowed.toLowerCase().replace(/_/g, "")) ||
-                        sourceOutput.replace(/_/g, "").includes(allowed.toLowerCase().replace(/_/g, "")));
-                    if (isAllowed)
-                        continue;
-                }
-                // Check if using an avoided input
-                for (const avoid of rule.avoid) {
-                    if (sourceOutput.includes(avoid.toLowerCase()) ||
-                        (targetInput.includes("query") && sourceOutput.includes("chat_conversation"))) {
-                        issues.push({
-                            type: "wrong_input_source",
-                            severity: rule.severity,
-                            node: node.id,
-                            current: sourceOutput,
-                            recommended: rule.recommended,
-                            reason: rule.reason,
-                            recommendation: rule.fix,
-                            auto_fixable: true, // Can rebind to correct source
-                        });
-                    }
-                }
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Detect email-specific issues:
- * 1. Email recipient from text output (should be entity_extraction)
- * 2. Email without HITL confirmation
- * 3. Missing entity_extraction before email
- */
-function detectEmailIssues(nodes) {
-    const issues = [];
-    // NOTE: We don't flag email input sources as errors since the backend accepts
-    // TEXT_WITH_SOURCES for email_to. The UI type system is the source of truth.
-    // Common valid pattern: entity_extraction → fixed_response('{{email}}') → send_email
-    // Find email sending nodes
-    const emailNodes = nodes.filter(n => n.action_name?.includes("send_email") ||
-        n.action_name?.includes("email_agent") ||
-        n.id?.toLowerCase().includes("send_email"));
-    // Find HITL nodes
-    const hitlNodes = nodes.filter(n => n.action_name?.includes("hitl") ||
-        n.action_name?.includes("human_collaboration") ||
-        n.id?.toLowerCase().includes("hitl") ||
-        n.id?.toLowerCase().includes("approval"));
-    for (const emailNode of emailNodes) {
-        // Email input validation removed - backend accepts what UI allows
-        // The UI type system enforces compatibility at connection time
-        // Check 3: Is there HITL confirmation before email?
-        // Check if any HITL node's output leads to this email node
-        let hasHitlUpstream = false;
-        if (emailNode.incoming_edges) {
-            for (const edge of emailNode.incoming_edges) {
-                const sourceNode = nodes.find(n => n.id === edge.source_node_id);
-                if (sourceNode && (sourceNode.action_name?.includes("hitl") ||
-                    sourceNode.id?.toLowerCase().includes("hitl"))) {
-                    hasHitlUpstream = true;
-                    break;
-                }
-            }
-        }
-        // Also check runIf for HITL Success
-        const hasHitlRunIf = emailNode.runIf &&
-            typeof emailNode.runIf === "object" &&
-            JSON.stringify(emailNode.runIf).toLowerCase().includes("hitl");
-        if (!hasHitlUpstream && !hasHitlRunIf && hitlNodes.length === 0) {
-            issues.push({
-                type: "side_effect_without_hitl",
-                severity: "info", // Changed from warning - HITL is optional, not required
-                node: emailNode.id,
-                auto_fixable: false,
-                reason: `NOTE: Email node "${emailNode.id}" has no HITL confirmation. ` +
-                    `Consider adding HITL if approval is desired before sending. ` +
-                    `(HITL can be added later via workflow(mode="extend") with "add approval before email".)`,
-            });
-        }
-    }
-    return issues;
-}
 /**
  * Validate all edge connections for type compatibility
  */
@@ -2336,1368 +1853,6 @@ export function validateWorkflowConnections(workflowDef) {
     }
     return validations;
 }
-/**
- * Detect performance issues (redundant searches, consolidation opportunities)
- *
- * This checks for:
- * 1. Multiple search nodes using the same query source - should consolidate
- * 2. Conditional searches that could be a single search with filtered results
- * 3. Sequential operations that could run in parallel
- */
-function detectPerformanceIssues(nodes) {
-    const issues = [];
-    // Find all search nodes
-    const searchNodes = nodes.filter(n => n.action_name?.includes("search") ||
-        n.id?.includes("search"));
-    if (searchNodes.length <= 1) {
-        return issues; // No consolidation opportunity with 0-1 search nodes
-    }
-    // Group search nodes by their query source
-    const searchesByQuerySource = new Map();
-    for (const search of searchNodes) {
-        // Find the query input edge
-        const queryEdge = search.incoming_edges?.find(e => e.target_input?.toLowerCase().includes("query"));
-        if (queryEdge) {
-            const querySource = `${queryEdge.source_node_id}.${queryEdge.source_output}`;
-            const existing = searchesByQuerySource.get(querySource) ?? [];
-            existing.push(search);
-            searchesByQuerySource.set(querySource, existing);
-        }
-    }
-    // Check for redundant searches (same query source)
-    for (const [querySource, searches] of searchesByQuerySource) {
-        if (searches.length > 1) {
-            // Check if these are conditional (runIf) searches
-            const conditionalSearches = searches.filter(s => 
-            // Check if node has runIf condition (indicates branch-specific execution)
-            s.id?.includes("client_update") ||
-                s.id?.includes("client_review") ||
-                s.id?.includes("market_impact") ||
-                s.id?.includes("_1") || s.id?.includes("_2") || s.id?.includes("_3"));
-            if (conditionalSearches.length > 1) {
-                // Multiple conditional searches with same query = consolidation opportunity
-                issues.push({
-                    type: "redundant_search",
-                    severity: "warning",
-                    nodes: searches.map(s => s.id),
-                    query_source: querySource,
-                    reason: `${searches.length} search nodes all use the same query source (${querySource}). Consider consolidating into a single search - only one branch executes at a time, so multiple searches add complexity without benefit.`,
-                    recommendation: "Replace multiple conditional searches with a single search node. Pass results to all response nodes via named_inputs. This reduces workflow complexity and maintenance burden.",
-                });
-            }
-            else {
-                // Non-conditional redundant searches (actual duplicates)
-                issues.push({
-                    type: "redundant_search",
-                    severity: "info",
-                    nodes: searches.map(s => s.id),
-                    query_source: querySource,
-                    reason: `${searches.length} search nodes share query source (${querySource}). Verify these are intentionally different (e.g., different file filters) or consolidate.`,
-                    recommendation: "If searches have different file filters, consider using a single search with broader filters and letting the LLM filter relevant results.",
-                });
-            }
-        }
-    }
-    // Check for sequential searches that could parallelize
-    for (const search of searchNodes) {
-        // Find nodes that depend on this search
-        const dependentSearches = searchNodes.filter(s => s.id !== search.id &&
-            s.incoming_edges?.some(e => e.source_node_id === search.id));
-        if (dependentSearches.length > 0) {
-            issues.push({
-                type: "sequential_search",
-                severity: "info",
-                node: search.id,
-                dependent_nodes: dependentSearches.map(s => s.id),
-                reason: `Search "${search.id}" has dependent searches that run sequentially. If searches are independent, they could run in parallel.`,
-                recommendation: "Review if sequential dependency is necessary. Independent searches should branch from the same source to enable parallel execution.",
-            });
-        }
-    }
-    // Check for multiple LLM calls that could consolidate
-    const llmNodes = nodes.filter(n => n.action_name?.includes("call_llm") ||
-        n.action_name?.includes("respond") ||
-        n.id?.includes("respond"));
-    // Group LLM nodes by their search input source
-    const llmsBySearchSource = new Map();
-    for (const llm of llmNodes) {
-        const searchInputEdge = llm.incoming_edges?.find(e => e.source_output?.toLowerCase().includes("search_result"));
-        if (searchInputEdge) {
-            const source = searchInputEdge.source_node_id;
-            const existing = llmsBySearchSource.get(source) ?? [];
-            existing.push(llm);
-            llmsBySearchSource.set(source, existing);
-        }
-    }
-    // Report if multiple LLM nodes use same search results
-    for (const [searchSource, llms] of llmsBySearchSource) {
-        if (llms.length > 1) {
-            // This is often OK (conditional responses based on categorizer)
-            // Only flag if they're not conditional
-            const nonConditionalCount = llms.filter(l => !l.id?.includes("update") &&
-                !l.id?.includes("review") &&
-                !l.id?.includes("impact") &&
-                !l.id?.includes("fallback")).length;
-            if (nonConditionalCount > 1) {
-                issues.push({
-                    type: "duplicate_llm_processing",
-                    severity: "info",
-                    nodes: llms.map(l => l.id),
-                    search_source: searchSource,
-                    reason: `Multiple LLM nodes process results from "${searchSource}". Consider consolidating if they produce similar outputs.`,
-                    recommendation: "Use a single call_llm with comprehensive instructions instead of multiple calls. This produces more coherent responses.",
-                });
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Detect all workflow issues
- */
-/**
- * Detect malformed runIf conditions
- *
- * Common mistake: using "category_<Name>" as output and comparing to "true"
- * Correct format: output="category", compare to enumValue="<Name>"
- */
-function detectMalformedRunIf(workflowDef) {
-    const issues = [];
-    const def = workflowDef;
-    if (!def)
-        return issues;
-    const actions = def.actions;
-    if (!actions)
-        return issues;
-    for (const action of actions) {
-        const runIf = action.runIf;
-        if (!runIf)
-            continue;
-        const lhs = runIf.lhs;
-        const rhs = runIf.rhs;
-        if (!lhs || !rhs)
-            continue;
-        const actionOutput = lhs.actionOutput;
-        if (!actionOutput)
-            continue;
-        const output = String(actionOutput.output ?? "");
-        const inlineRhs = rhs.inline;
-        const enumValue = String(inlineRhs?.enumValue ?? "");
-        // Detect malformed pattern: output="category_<Name>" compared to enumValue="true"
-        if (output.startsWith("category_") && (enumValue === "true" || enumValue === "false")) {
-            // Extract the category name from the malformed output
-            const categoryName = output.replace(/^category_/, "");
-            issues.push({
-                type: "malformed_runif",
-                severity: "critical",
-                node: String(action.name ?? ""),
-                current: `output="${output}" compared to enumValue="${enumValue}"`,
-                recommended: `output="category" compared to enumValue="${categoryName}"`,
-                reason: `Malformed runIf condition: comparing "${output}" to "${enumValue}" won't work. The categorizer output is "category", not "category_<Name>".`,
-                auto_fixable: true,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect unused categories - categories defined in enumType but with no handler
- * This causes SILENT FAILURES where requests match the category but nothing executes
- */
-function detectUnusedCategories(nodes, workflowDef) {
-    const issues = [];
-    const def = workflowDef;
-    if (!def)
-        return issues;
-    const enumTypes = def.enumTypes;
-    const actions = def.actions;
-    if (!enumTypes || !actions)
-        return issues;
-    // Find all categorizer nodes
-    const categorizers = nodes.filter(n => n.action_name === "chat_categorizer" ||
-        n.action_name === "intent_classifier");
-    for (const categorizer of categorizers) {
-        // Find the enumType for this categorizer using typeArguments reference (robust)
-        // The action's typeArguments.categories.enumType points to the correct enumType
-        const categorizerAction = actions.find(a => a.name === categorizer.id);
-        const typeArgs = categorizerAction?.typeArguments;
-        const enumTypeRefName = typeArgs?.categories?.enumType?.name?.name;
-        const enumType = enumTypes.find(e => {
-            const name = e.name;
-            const innerName = name?.name;
-            const nameStr = String(innerName?.name ?? name?.name ?? "");
-            // Match by typeArguments reference (preferred) or by categorizer ID (fallback)
-            // DO NOT use generic "enumType" fallback - that causes cross-categorizer pollution
-            return (enumTypeRefName && nameStr === enumTypeRefName) || nameStr.includes(categorizer.id);
-        });
-        if (!enumType)
-            continue;
-        const options = enumType.options;
-        if (!options)
-            continue;
-        // Get all defined categories
-        const definedCategories = options.map(o => String(o.name ?? "")).filter(n => n.length > 0);
-        // Find which categories have handlers (via runIf conditions)
-        const handledCategories = new Set();
-        for (const action of actions) {
-            const runIf = action.runIf;
-            if (!runIf)
-                continue;
-            const lhs = runIf.lhs;
-            const actionOutput = lhs?.actionOutput;
-            // Check if this runIf references our categorizer
-            if (actionOutput?.actionName === categorizer.id) {
-                const rhs = runIf.rhs;
-                const inline = rhs?.inline;
-                const enumValue = String(inline?.enumValue ?? "");
-                if (enumValue) {
-                    handledCategories.add(enumValue);
-                }
-            }
-        }
-        // Check for config-based routing (document_synthesis with Config.tasks pattern)
-        // Find Config.tasks keys from fixed_response nodes
-        const configTaskKeys = new Set();
-        for (const action of actions) {
-            const actionInfo = action.action;
-            const actionName = actionInfo?.name;
-            if (actionName?.name !== "fixed_response")
-                continue;
-            const inputs = action.inputs;
-            const template = inputs?.template;
-            const inline = template?.inline;
-            const wellKnown = inline?.wellKnown;
-            const textWithSources = wellKnown?.textWithSources;
-            const text = String(textWithSources?.text ?? "");
-            try {
-                if (text.includes('"tasks"')) {
-                    const config = JSON.parse(text);
-                    const tasks = config.tasks;
-                    if (tasks) {
-                        for (const taskKey of Object.keys(tasks)) {
-                            configTaskKeys.add(taskKey);
-                        }
-                    }
-                }
-            }
-            catch {
-                // Not JSON, skip
-            }
-        }
-        // Check if category is passed to any downstream node (including via named_inputs)
-        // Use flexible string matching to handle any JSON formatting
-        let usesConfigBasedRouting = false;
-        for (const action of actions) {
-            const inputs = action.inputs;
-            if (!inputs)
-                continue;
-            // Check regular inputs and named_inputs for reference to categorizer's category output
-            const inputStr = JSON.stringify(inputs).replace(/\s+/g, "");
-            const categorizerRef = `"actionName":"${categorizer.id}"`.replace(/\s+/g, "");
-            const categoryOutput = `"output":"category"`.replace(/\s+/g, "");
-            if (inputStr.includes(categorizerRef) && inputStr.includes(categoryOutput)) {
-                // This action references the categorizer's category output
-                const actionInfo = action.action;
-                const actionName = actionInfo?.name;
-                const actionType = String(actionName?.name ?? "");
-                // If it's a synthesis/generation node and we have config tasks, it's config-based routing
-                if (["document_synthesis", "call_llm", "custom_agent"].includes(actionType) && configTaskKeys.size > 0) {
-                    usesConfigBasedRouting = true;
-                }
-            }
-        }
-        // If we have config tasks defined, assume config-based routing even if not explicitly detected
-        // This handles cases where the config might be in an orphan node but still used at runtime
-        if (configTaskKeys.size > 0 && !usesConfigBasedRouting) {
-            // Check if any downstream node is a document_synthesis or custom_agent
-            for (const node of nodes) {
-                if (node.action_name === "document_synthesis" || node.action_name === "custom_agent") {
-                    usesConfigBasedRouting = true;
-                    break;
-                }
-            }
-        }
-        // Find unused categories
-        const unusedCategories = definedCategories.filter(c => !handledCategories.has(c));
-        for (const category of unusedCategories) {
-            // Skip Fallback - already detected by missing_fallback
-            if (category === "Fallback")
-                continue;
-            // If using config-based routing, check if category has a task
-            if (usesConfigBasedRouting) {
-                if (!configTaskKeys.has(category)) {
-                    issues.push({
-                        type: "unused_category",
-                        severity: "critical",
-                        node: categorizer.id,
-                        category,
-                        categories: Array.from(configTaskKeys),
-                        auto_fixable: false,
-                        reason: `Category "${category}" is defined but has NO TASK in Config.tasks. ` +
-                            `Requests matching this category will SILENTLY FAIL - the workflow looks for Config.tasks["${category}"] which doesn't exist. ` +
-                            `Config has tasks for: ${Array.from(configTaskKeys).join(", ")}. ` +
-                            `Either add "${category}" to Config.tasks, or remove the category from the enum.`,
-                    });
-                }
-            }
-            else {
-                // No config-based routing - need explicit runIf handler
-                issues.push({
-                    type: "unused_category",
-                    severity: "critical",
-                    node: categorizer.id,
-                    category,
-                    categories: unusedCategories,
-                    auto_fixable: false,
-                    reason: `Category "${category}" is defined in ${categorizer.display_name || categorizer.id} but has NO HANDLER. ` +
-                        `Requests matching this category will SILENTLY FAIL - no response sent to user. ` +
-                        `Either add a node with runIf condition for "${category}", add to Config.tasks, or remove the category.`,
-                });
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Detect category name mismatches - e.g., SEND_EMAIL in enum vs SEND_COMMUNICATION in config
- */
-function detectCategoryNameMismatches(nodes, workflowDef) {
-    const issues = [];
-    const def = workflowDef;
-    if (!def)
-        return issues;
-    const enumTypes = def.enumTypes;
-    const actions = def.actions;
-    if (!enumTypes || !actions)
-        return issues;
-    // Find fixed_response nodes that might contain config with tasks
-    const configNodes = actions.filter(a => {
-        const actionInfo = a.action;
-        const actionName = actionInfo?.name;
-        return actionName?.name === "fixed_response";
-    });
-    for (const configNode of configNodes) {
-        // Try to extract config content
-        const inputs = configNode.inputs;
-        const template = inputs?.template;
-        const inline = template?.inline;
-        const wellKnown = inline?.wellKnown;
-        const textWithSources = wellKnown?.textWithSources;
-        const text = String(textWithSources?.text ?? "");
-        // Try to parse as JSON to find tasks object
-        try {
-            if (text.includes('"tasks"')) {
-                const config = JSON.parse(text);
-                const tasks = config.tasks;
-                if (!tasks)
-                    continue;
-                const taskNames = new Set(Object.keys(tasks));
-                // Compare with enum categories
-                for (const enumType of enumTypes) {
-                    const options = enumType.options;
-                    if (!options)
-                        continue;
-                    const enumCategories = options.map(o => String(o.name ?? "")).filter(n => n.length > 0);
-                    // Find similar but not exact matches
-                    for (const enumCat of enumCategories) {
-                        if (enumCat === "Fallback")
-                            continue;
-                        // Check for name mismatches (similar but different)
-                        const normalizedEnum = enumCat.toLowerCase().replace(/_/g, "");
-                        for (const taskName of taskNames) {
-                            const normalizedTask = taskName.toLowerCase().replace(/_/g, "");
-                            // Similar names but not exact match
-                            if (normalizedEnum !== normalizedTask &&
-                                (normalizedEnum.includes(normalizedTask.slice(0, 4)) ||
-                                    normalizedTask.includes(normalizedEnum.slice(0, 4)))) {
-                                // Check if it's actually a mismatch (enum not in tasks)
-                                if (!taskNames.has(enumCat)) {
-                                    issues.push({
-                                        type: "category_name_mismatch",
-                                        severity: "critical",
-                                        node: String(configNode.name ?? "config"),
-                                        category: enumCat,
-                                        config_key: taskName,
-                                        auto_fixable: true,
-                                        reason: `Category name mismatch: Enum has "${enumCat}" but Config.tasks has "${taskName}". ` +
-                                            `This routing will FAIL because Config.tasks["${enumCat}"] doesn't exist. ` +
-                                            `Either rename the enum category to "${taskName}" or add "${enumCat}" to Config.tasks.`,
-                                    });
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        catch {
-            // Not JSON config, skip
-        }
-    }
-    return issues;
-}
-/**
- * Detect late categorizer placement - categorizer should be early to avoid wasted processing
- */
-function detectLateCategorizer(nodes) {
-    const issues = [];
-    const categorizers = nodes.filter(n => n.action_name === "chat_categorizer" ||
-        n.action_name === "intent_classifier");
-    // Heavy processing nodes
-    const heavyNodes = new Set(["call_llm", "custom_agent", "document_synthesis", "search", "knowledge_search"]);
-    for (const categorizer of categorizers) {
-        // Find all nodes upstream of this categorizer
-        const upstreamHeavy = [];
-        const visited = new Set();
-        function findUpstream(nodeId) {
-            if (visited.has(nodeId))
-                return;
-            visited.add(nodeId);
-            const node = nodes.find(n => n.id === nodeId);
-            if (!node?.incoming_edges)
-                return;
-            for (const edge of node.incoming_edges) {
-                const sourceNode = nodes.find(n => n.id === edge.source_node_id);
-                if (sourceNode) {
-                    if (heavyNodes.has(sourceNode.action_name || "")) {
-                        upstreamHeavy.push(sourceNode.display_name || sourceNode.id);
-                    }
-                    findUpstream(sourceNode.id);
-                }
-            }
-        }
-        findUpstream(categorizer.id);
-        if (upstreamHeavy.length > 0) {
-            issues.push({
-                type: "late_categorizer",
-                severity: "warning",
-                node: categorizer.id,
-                nodes: upstreamHeavy,
-                auto_fixable: false,
-                reason: `Categorizer "${categorizer.display_name || categorizer.id}" runs AFTER heavy processing: ${upstreamHeavy.join(", ")}. ` +
-                    `This wastes compute - all that processing happens even for simple requests. ` +
-                    `RECOMMENDATION: Move categorizer earlier in the flow. Categorize FIRST, then process only the relevant branch.`,
-            });
-        }
-    }
-    return issues;
-}
-/**
- * Detect excessive LLM calls per execution path
- */
-function detectExcessiveLLMCalls(nodes) {
-    const issues = [];
-    const trigger = nodes.find(n => n.action_name === "trigger" || n.id === "trigger");
-    if (!trigger)
-        return issues;
-    const llmNodes = new Set(["call_llm", "custom_agent", "document_synthesis"]);
-    // Build adjacency list
-    const adj = new Map();
-    for (const node of nodes) {
-        adj.set(node.id, new Set());
-    }
-    for (const node of nodes) {
-        if (node.incoming_edges) {
-            for (const edge of node.incoming_edges) {
-                adj.get(edge.source_node_id)?.add(node.id);
-            }
-        }
-    }
-    // Find all paths from trigger and count LLMs
-    const pathsWithHighLLMCount = [];
-    function dfs(nodeId, path, llmCount) {
-        const node = nodes.find(n => n.id === nodeId);
-        const newPath = [...path, nodeId];
-        const newLLMCount = llmCount + (node && llmNodes.has(node.action_name || "") ? 1 : 0);
-        const neighbors = adj.get(nodeId) || new Set();
-        if (neighbors.size === 0) {
-            // End of path
-            if (newLLMCount > 3) {
-                pathsWithHighLLMCount.push({ path: newPath, llm_count: newLLMCount });
-            }
-            return;
-        }
-        // Limit depth to avoid infinite loops
-        if (newPath.length > 15)
-            return;
-        for (const neighbor of neighbors) {
-            if (!path.includes(neighbor)) {
-                dfs(neighbor, newPath, newLLMCount);
-            }
-        }
-    }
-    dfs(trigger.id, [], 0);
-    // Report worst paths
-    pathsWithHighLLMCount.sort((a, b) => b.llm_count - a.llm_count);
-    for (const { path, llm_count } of pathsWithHighLLMCount.slice(0, 3)) {
-        const llmNodesInPath = path.filter(p => {
-            const node = nodes.find(n => n.id === p);
-            return node && llmNodes.has(node.action_name || "");
-        });
-        issues.push({
-            type: "excessive_llm_calls",
-            severity: llm_count > 5 ? "warning" : "info",
-            nodes: llmNodesInPath,
-            llm_count,
-            path,
-            auto_fixable: false,
-            reason: `Execution path has ${llm_count} LLM calls: ${llmNodesInPath.join(" → ")}. ` +
-                `Each LLM call adds 1-3 seconds latency. Users typically wait max 5-8 seconds. ` +
-                `RECOMMENDATION: Consolidate LLM calls, parallelize where possible, or cache repeated lookups.`,
-        });
-    }
-    return issues;
-}
-/**
- * Detect suboptimal node choices - using heavy nodes where lighter ones suffice
- */
-function detectSuboptimalNodeChoices(nodes) {
-    const issues = [];
-    for (const node of nodes) {
-        const actionName = node.action_name || "";
-        const displayName = node.display_name || node.id;
-        // Check for document_synthesis when respond_with_sources might suffice
-        if (actionName === "document_synthesis") {
-            // Check if it has simple inputs (not complex multi-source)
-            const hasSearchInput = node.incoming_edges?.some(e => e.source_output?.includes("search_results"));
-            const hasMultipleSearchInputs = (node.incoming_edges?.filter(e => e.source_output?.includes("search_results")) || []).length > 1;
-            if (hasSearchInput && !hasMultipleSearchInputs) {
-                issues.push({
-                    type: "suboptimal_node_choice",
-                    severity: "info",
-                    node: node.id,
-                    actual_node: "document_synthesis",
-                    recommended_node: "respond_with_sources or call_llm",
-                    use_case: "single search source",
-                    reason: `"${displayName}" uses document_synthesis (2-5 LLM calls) but only has one search source. ` +
-                        `Consider using respond_with_sources (1 call) for simple Q&A, or call_llm with named_inputs for custom generation. ` +
-                        `document_synthesis is best for multi-source research with search-plan-search patterns.`,
-                });
-            }
-        }
-        // Check for call_llm/custom_agent that might be doing extraction
-        if (["call_llm", "custom_agent"].includes(actionName)) {
-            // Look for JSON extraction patterns in instructions
-            const inputStr = JSON.stringify(node.incoming_edges || []);
-            const nodeId = node.id.toLowerCase();
-            const display = displayName.toLowerCase();
-            // Check if this looks like an extraction node
-            if (nodeId.includes("extract") ||
-                display.includes("extract") ||
-                nodeId.includes("parse") ||
-                display.includes("parse")) {
-                issues.push({
-                    type: "suboptimal_node_choice",
-                    severity: "warning",
-                    node: node.id,
-                    actual_node: actionName,
-                    recommended_node: "entity_extraction",
-                    use_case: "structured data extraction",
-                    reason: `"${displayName}" appears to be doing extraction but uses ${actionName}. ` +
-                        `Use entity_extraction instead - it's optimized for structured data, provides typed output, ` +
-                        `and is more reliable for extracting specific fields (names, emails, dates, amounts).`,
-                });
-            }
-        }
-        // Check for LLM nodes that might be doing simple transforms
-        if (["call_llm", "custom_agent", "document_synthesis"].includes(actionName)) {
-            const display = displayName.toLowerCase();
-            const nodeId = node.id.toLowerCase();
-            // Check if it looks like a simple formatter/transformer
-            if ((display.includes("format") && !display.includes("information")) ||
-                display.includes("convert") ||
-                display.includes("template") ||
-                nodeId.includes("formatter") ||
-                nodeId.includes("converter")) {
-                issues.push({
-                    type: "suboptimal_node_choice",
-                    severity: "info",
-                    node: node.id,
-                    actual_node: actionName,
-                    recommended_node: "json_mapper or fixed_response",
-                    use_case: "formatting/transformation",
-                    reason: `"${displayName}" might be doing simple formatting with ${actionName} (LLM-based). ` +
-                        `If this is just data transformation without reasoning, consider json_mapper (no LLM, <100ms) ` +
-                        `or fixed_response with template variables (no LLM, <50ms).`,
-                });
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Detect unnecessary search nodes (search before simple tasks that don't need KB)
- */
-function detectUnnecessarySearch(nodes) {
-    const issues = [];
-    // Find search nodes
-    const searchNodes = nodes.filter(n => n.action_name === "search" ||
-        n.action_name === "knowledge_search");
-    // Check what consumes each search
-    for (const searchNode of searchNodes) {
-        // Find downstream consumers
-        const consumers = nodes.filter(n => n.incoming_edges?.some(e => e.source_node_id === searchNode.id));
-        // Check if downstream is just fallback/greeting
-        for (const consumer of consumers) {
-            const consumerName = (consumer.display_name || consumer.id).toLowerCase();
-            if (consumerName.includes("fallback") ||
-                consumerName.includes("greeting") ||
-                consumerName.includes("clarif")) {
-                issues.push({
-                    type: "unnecessary_search",
-                    severity: "info",
-                    node: searchNode.id,
-                    reason: `Search "${searchNode.display_name || searchNode.id}" feeds into "${consumer.display_name || consumer.id}" (fallback/greeting). ` +
-                        `Fallback responses typically don't need KB search - they're about clarification, not retrieval. ` +
-                        `Consider removing search from fallback path to reduce latency.`,
-                });
-            }
-        }
-    }
-    return issues;
-}
-export function detectWorkflowIssues(workflowDef) {
-    const nodes = parseWorkflowDef(workflowDef);
-    if (nodes.length === 0) {
-        return [{
-                type: "orphan",
-                severity: "critical",
-                reason: "No workflow nodes found - workflow definition may be empty or invalid format",
-            }];
-    }
-    let issues = [
-        ...detectCycles(nodes),
-        ...detectOrphanNodes(nodes),
-        ...detectDeadEnds(nodes),
-        ...detectUnusedOutputs(nodes, workflowDef),
-        ...detectCategorizerIssues(nodes),
-        ...detectHitlIssues(nodes),
-        ...detectWrongInputSource(nodes),
-        ...detectEmailIssues(nodes),
-        ...detectPerformanceIssues(nodes),
-        ...detectMalformedRunIf(workflowDef),
-        // NEW: Category/routing structure issues
-        ...detectUnusedCategories(nodes, workflowDef),
-        ...detectCategoryNameMismatches(nodes, workflowDef),
-        ...detectLateCategorizer(nodes),
-        ...detectExcessiveLLMCalls(nodes),
-        // NEW: Node selection issues
-        ...detectSuboptimalNodeChoices(nodes),
-        ...detectUnnecessarySearch(nodes),
-    ];
-    // Add type mismatch issues from connection validation
-    const connections = validateWorkflowConnections(workflowDef);
-    for (const conn of connections) {
-        if (!conn.compatible) {
-            issues.push({
-                type: "type_mismatch",
-                severity: "critical",
-                source: `${conn.source_node}.${conn.source_output}`,
-                target: `${conn.target_node}.${conn.target_input}`,
-                expected: conn.target_type,
-                got: conn.source_type,
-                reason: conn.note ?? `Type mismatch: ${conn.source_type} → ${conn.target_type}`,
-            });
-        }
-    }
-    // Filter out false positives for Voice AI workflows
-    const def = workflowDef;
-    if (def) {
-        const results = def.results;
-        const actions = def.actions;
-        // If workflow has results mapping, it's Voice AI - WORKFLOW_OUTPUT is not required
-        if (results && Object.keys(results).length > 0) {
-            issues = issues.filter(i => i.type !== "missing_workflow_output");
-        }
-        // Check if categorizers use runIf pattern (valid alternative to explicit edges)
-        if (actions) {
-            const categorizerIssues = issues.filter(i => i.type === "missing_category_edge");
-            for (const catIssue of categorizerIssues) {
-                const categorizerName = catIssue.node;
-                // Count nodes that have runIf referencing this categorizer
-                const nodesUsingCategorizer = actions.filter(a => {
-                    const runIf = a.runIf;
-                    if (!runIf?.lhs)
-                        return false;
-                    const lhs = runIf.lhs;
-                    const actionOutput = lhs.actionOutput;
-                    return actionOutput?.actionName === categorizerName;
-                });
-                // If there are nodes with runIf conditions using this categorizer, it's valid
-                if (nodesUsingCategorizer.length > 0) {
-                    issues = issues.filter(i => !(i.type === "missing_category_edge" && i.node === categorizerName));
-                }
-            }
-        }
-    }
-    return issues;
-}
-/**
- * Analyze a workflow comprehensively
- */
-export function analyzeWorkflow(workflowDef, metadata) {
-    const nodes = parseWorkflowDef(workflowDef);
-    const issues = detectWorkflowIssues(workflowDef);
-    // Count edges
-    let totalEdges = 0;
-    for (const node of nodes) {
-        totalEdges += node.incoming_edges?.length ?? 0;
-    }
-    // Check for trigger
-    const hasTrigger = nodes.some(n => n.action_name?.includes("trigger") ||
-        n.id === "trigger" ||
-        n.id?.includes("trigger"));
-    // Check for WORKFLOW_OUTPUT
-    const hasWorkflowOutput = nodes.some(n => n.id === "WORKFLOW_OUTPUT" ||
-        n.action_name === "WorkflowOutputSink");
-    // Count categorizers
-    const categorizersCount = nodes.filter(n => n.action_name?.includes("categorizer") ||
-        n.id?.includes("categorizer") ||
-        n.id?.includes("classifier")).length;
-    // Count HITL nodes
-    const hitlNodesCount = nodes.filter(n => n.action_name?.includes("hitl") ||
-        n.action_name?.includes("human_collaboration") ||
-        n.id?.includes("hitl") ||
-        n.id?.includes("approval")).length;
-    // Summarize issues by severity
-    const issueSummary = {
-        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 {
-        ...metadata,
-        summary: {
-            total_nodes: nodes.length,
-            total_edges: totalEdges,
-            has_trigger: hasTrigger,
-            has_workflow_output: hasWorkflowOutput,
-            categorizers_count: categorizersCount,
-            hitl_nodes_count: hitlNodesCount,
-        },
-        issues,
-        issue_summary: issueSummary,
-        validation_passed: issueSummary.critical === 0,
-    };
-}
-/**
- * Suggest fixes for detected workflow issues
- */
-export function suggestWorkflowFixes(issues) {
-    const fixes = [];
-    for (const issue of issues) {
-        let fix = null;
-        switch (issue.type) {
-            case "missing_fallback":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add Fallback category to categorizer "${issue.node}"`,
-                    after: `# Add to enumType.options for ${issue.node}:
-- name: "Fallback"
-  description: "Default for unclear or ambiguous requests"
-  examples:
-    - "Hello"
-    - "Help"
-    - "I'm not sure"
-
-# Add edge for Fallback category:
-- source_node: ${issue.node}
-  source_output: category_Fallback
-  target_node: fallback_handler
-  target_input: trigger_when`,
-                    validation: "Verify categorizer has Fallback in enumType.options AND has outgoing edge for category_Fallback",
-                };
-                break;
-            case "incomplete_hitl":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add ${issue.missing} for HITL node "${issue.node}"`,
-                    after: `# Add ${issue.missing === "success_path" ? "success" : issue.missing === "failure_path" ? "failure" : "both"} handler(s):
-${issue.missing?.includes("success") || issue.missing?.includes("both") ? `
-- name: "${issue.node}_success_response"
-  runIf:
-    lhs:
-      actionOutput:
-        actionName: "${issue.node}"
-        output: "hitl_status"
-      autoDetectedBinding: false
-    operator: 1  # OPERATOR_EQ
-    rhs:
-      inline:
-        enumValue: "HITL Success"
-      autoDetectedBinding: false
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "call_llm"
-  # Connect to WORKFLOW_OUTPUT` : ""}
-${issue.missing?.includes("failure") || issue.missing?.includes("both") ? `
-- name: "${issue.node}_failure_response"
-  runIf:
-    lhs:
-      actionOutput:
-        actionName: "${issue.node}"
-        output: "hitl_status"
-      autoDetectedBinding: false
-    operator: 1  # OPERATOR_EQ
-    rhs:
-      inline:
-        enumValue: "HITL Failure"
-      autoDetectedBinding: false
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "call_llm"
-  # Connect to WORKFLOW_OUTPUT` : ""}`,
-                    validation: "Verify both 'hitl_status_HITL Success' and 'hitl_status_HITL Failure' (with space, not underscore) have handler nodes and connect to WORKFLOW_OUTPUT",
-                };
-                break;
-            case "dead_end":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Connect "${issue.node}" to WORKFLOW_OUTPUT`,
-                    after: `# Add edge from ${issue.node} to WORKFLOW_OUTPUT:
-- source_node: ${issue.node}
-  source_output: response_with_sources  # or appropriate output
-  target_node: WORKFLOW_OUTPUT
-  target_input: ${issue.node}.response_with_sources`,
-                    validation: "Verify node's output is mapped to WORKFLOW_OUTPUT",
-                };
-                break;
-            case "type_mismatch":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Fix type mismatch: ${issue.source} → ${issue.target}`,
-                    before: `# Current: ${issue.source} (${issue.got}) → ${issue.target} (${issue.expected})`,
-                    after: issue.got === "WELL_KNOWN_TYPE_CHAT_CONVERSATION" && issue.expected === "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES"
-                        ? `# Insert conversation_to_search_query between source and target:
-- name: "summarizer"
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "conversation_to_search_query"
-  inputs:
-    conversation:
-      actionOutput:
-        actionName: "[source_trigger]"
-        output: "chat_conversation"
-
-# Then update target to use summarizer output:
-- target input should reference summarizer.summarized_conversation`
-                        : `# Either:
-# 1. Use an intermediate conversion node
-# 2. Connect to a named_inputs_* (accepts ANY type)
-# 3. Use a different source output that matches the expected type`,
-                    validation: `Verify source output type (${issue.got}) matches target input type (${issue.expected})`,
-                };
-                break;
-            case "wrong_input_source":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Change input for "${issue.node}" from ${issue.current} to ${issue.recommended}`,
-                    before: `# Current: using ${issue.current}`,
-                    after: `# Update incoming edge to use ${issue.recommended}:
-- source_node: trigger  # or appropriate source
-  source_output: ${issue.recommended}
-  target_node: ${issue.node}
-  target_input: ${issue.recommended === "chat_conversation" ? "conversation" : "query"}`,
-                    validation: `Verify ${issue.node} receives ${issue.recommended} - ${issue.reason}`,
-                };
-                break;
-            case "missing_category_edge":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add outgoing category edges for categorizer "${issue.node}"`,
-                    after: `# Add edges for each category in the categorizer:
-# For each category in enumType.options, add:
-- source_node: ${issue.node}
-  source_output: category_<CategoryName>
-  target_node: <handler_for_category>
-  target_input: trigger_when
-
-# Example categories: Product_Info, Support, Sales, Fallback`,
-                    validation: "Verify each category in enumType.options has a corresponding outgoing edge",
-                };
-                break;
-            case "orphan":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Connect orphan node "${issue.node}" to workflow`,
-                    after: `# Option 1: Connect as target of a categorizer:
-- source_node: <categorizer>
-  source_output: category_<SomeCategory>
-  target_node: ${issue.node}
-  target_input: trigger_when
-
-# Option 2: Remove the node if no longer needed`,
-                    validation: "Verify node is reachable from trigger via edges",
-                };
-                break;
-            case "unused_output":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Connect output of "${issue.node}" to downstream consumer or remove the node`,
-                    after: `# The node "${issue.node}" produces "${issue.current}" but nothing uses it.
-# 
-# Option 1: Connect output to a downstream node that needs it:
-- node: <downstream_node>
-  inputs:
-    <input_name>:
-      actionOutput:
-        actionName: ${issue.node}
-        output: ${issue.current}
-
-# Option 2: If using combine_search_results, connect to respond_with_sources:
-# NOTE: respond_with_sources.search_results expects SEARCH_RESULT type
-# combined_results is TEXT_WITH_SOURCES - use original search output OR named_inputs
-- node: respond_with_sources
-  inputs:
-    search_results:
-      actionOutput:
-        actionName: <original_search_node>  # NOT ${issue.node}
-        output: search_results
-    named_inputs:  # Add combined for context
-      multiBinding:
-        elements:
-          - namedBinding:
-              name: combined_context
-              value:
-                actionOutput:
-                  actionName: ${issue.node}
-                  output: ${issue.current}
-
-# Option 3: Remove the node if not needed:
-# Delete the "${issue.node}" action from the workflow`,
-                    validation: `Verify "${issue.node}.${issue.current}" is consumed by a downstream node or WORKFLOW_OUTPUT`,
-                };
-                break;
-            case "unsafe_email_recipient":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Use entity_extraction to get email address instead of text content`,
-                    before: `# WRONG: Connecting text output to email recipient
-- node: ${issue.node}
-  inputs:
-    email_to:
-      actionOutput:
-        actionName: ${issue.source}
-        output: ${issue.current}  # ❌ This is TEXT, not an email address!`,
-                    after: `# CORRECT: Extract email address via entity_extraction
-# Step 1: Add entity_extraction node to extract email from conversation
-- name: extract_email
-  action:
-    name:
-      namespaces: ["agents"]
-      name: entity_extraction
-  inputs:
-    text:
-      actionOutput:
-        actionName: trigger
-        output: chat_conversation
-  displaySettings:
-    displayName: "Extract Email Address"
-  # Configure extraction schema for email
-  parameters:
-    extraction_schema:
-      email_address:
-        type: string
-        required: true
-      recipient_name:
-        type: string
-        required: false
-
-# Step 2: Add HITL to confirm before sending
-- name: confirm_email
-  action:
-    name:
-      namespaces: ["agents"]
-      name: hitl
-  inputs:
-    request_text:
-      actionOutput:
-        actionName: extract_email
-        output: extracted_entities
-  displaySettings:
-    displayName: "Confirm Email Recipient"
-
-# Step 3: Send email ONLY after HITL approval with extracted email
-- name: ${issue.node}
-  action:
-    name:
-      namespaces: ["agents"]
-      name: send_email_agent
-  inputs:
-    email_to:
-      actionOutput:
-        actionName: extract_email
-        output: email_address  # ✅ Structured email from extraction
-    email_body:
-      actionOutput:
-        actionName: ${issue.source}
-        output: ${issue.current}  # Text content is fine for body
-  runIf:
-    enum:
-      enumType: HITL_STATUS
-      enumValue: "HITL Success"`,
-                    validation: "Verify email_to receives output from entity_extraction.email_address, not text content",
-                };
-                break;
-            case "missing_entity_extraction":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add entity_extraction upstream of email node to extract structured data`,
-                    after: `# Add entity_extraction before email to extract required fields
-- name: extract_email_data
-  action:
-    name:
-      namespaces: ["agents"]
-      name: entity_extraction
-  inputs:
-    text:
-      actionOutput:
-        actionName: trigger
-        output: chat_conversation
-  displaySettings:
-    displayName: "Extract Email Data"
-  # Define what to extract
-  parameters:
-    extraction_schema:
-      email_address:
-        type: string
-        required: true
-        description: "Recipient email address"
-      subject:
-        type: string
-        required: false
-        description: "Email subject line"
-      recipient_name:
-        type: string
-        required: false
-
-# Then connect extracted data to email node:
-- node: ${issue.node}
-  inputs:
-    email_to:
-      actionOutput:
-        actionName: extract_email_data
-        output: email_address`,
-                    validation: "Verify entity_extraction exists upstream of email node",
-                };
-                break;
-            case "side_effect_without_hitl":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add HITL confirmation before executing action with side effects`,
-                    after: `# Add HITL node before ${issue.node} to confirm with user
-- name: confirm_before_send
-  action:
-    name:
-      namespaces: ["agents"]
-      name: hitl
-  inputs:
-    request_text:
-      constant:
-        value: "Please confirm you want to proceed with this action."
-  displaySettings:
-    displayName: "Confirm Before Sending"
-
-# Update ${issue.node} to only run after HITL approval
-- name: ${issue.node}
-  # ... existing config ...
-  runIf:
-    enum:
-      enumType: HITL_STATUS
-      enumValue: "HITL Success"
-
-# Add failure handling (IMPORTANT: don't leave HITL incomplete)
-- name: cancelled_response
-  action:
-    name:
-      namespaces: ["generation"]
-      name: call_llm
-  inputs:
-    query:
-      constant:
-        value: "The action was cancelled by the user."
-  runIf:
-    enum:
-      enumType: HITL_STATUS
-      enumValue: "HITL Failure"`,
-                    validation: "Verify HITL node exists before action and both success/failure paths are handled",
-                };
-                break;
-            case "cycle":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Remove circular dependency in: ${issue.nodes?.join(" → ")}`,
-                    after: `# Identify and remove the edge creating the cycle.
-# The cycle involves: ${issue.nodes?.join(", ")}
-# 
-# Common solutions:
-# 1. Remove the back-edge (edge pointing to earlier node)
-# 2. Restructure to use proper exit conditions
-# 3. Use a separate node for the "loop back" case that terminates properly`,
-                    validation: "Verify no circular paths exist in the workflow graph",
-                };
-                break;
-            case "missing_workflow_output":
-                fix = {
-                    issue_type: issue.type,
-                    description: "Add WORKFLOW_OUTPUT node and connect all response paths",
-                    after: `# Add WORKFLOW_OUTPUT node:
-- id: WORKFLOW_OUTPUT
-  action_name: WorkflowOutputSink
-  incoming_edges: []
-
-# Connect all response nodes to it:
-# For each response/call_llm node that produces final output:
-- source_node: <response_node>
-  source_output: response_with_sources
-  target_node: WORKFLOW_OUTPUT
-  target_input: <response_node>.response_with_sources`,
-                    validation: "Verify WORKFLOW_OUTPUT exists and all terminal response nodes connect to it",
-                };
-                break;
-            // Performance optimization fixes
-            case "redundant_search":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Consolidate ${issue.nodes?.length ?? 0} redundant search nodes into a single search`,
-                    before: `# Current: ${issue.nodes?.length ?? 0} separate search nodes, all using ${issue.query_source}
-# Nodes: ${issue.nodes?.join(", ")}`,
-                    after: `# RECOMMENDED: Replace multiple searches with a single consolidated search:
-
-- name: "knowledge_search"
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "search"
-  inputs:
-    query:
-      actionOutput:
-        actionName: "${issue.query_source?.split(".")[0] ?? "conversation_summarizer"}"
-        output: "${issue.query_source?.split(".")[1] ?? "summarized_conversation"}"
-    # Remove file_name_filters to search all files
-    # OR use broad filters that cover all needed data
-    max_extractive_segment_count:
-      inline:
-        wellKnown:
-          int64Value: "25"  # Increase to get comprehensive results
-
-# Then update ALL response nodes to use this single search:
-- name: "respond_client_update"  # and other response nodes
-  inputs:
-    named_inputs:
-      multiBinding:
-        elements:
-          - namedBinding:
-              name: "Search Results"
-              value:
-                actionOutput:
-                  actionName: "knowledge_search"
-                  output: "search_results"`,
-                    validation: "Verify single search provides sufficient results for all response branches",
-                };
-                break;
-            case "sequential_search":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Parallelize sequential searches starting from "${issue.node}"`,
-                    before: `# Current: Sequential execution
-# ${issue.node} → ${issue.dependent_nodes?.join(" → ")}`,
-                    after: `# RECOMMENDED: Run independent searches in parallel by branching from same source:
-
-# Instead of:
-#   search_1 → search_2 → search_3
-#
-# Use:
-#   ┌─> search_1 ─┐
-#   │             │
-# source ─> search_2 ─> combine_search_results
-#   │             │
-#   └─> search_3 ─┘
-
-# If searches need different inputs, ensure they branch from the categorizer
-# or conversation_summarizer rather than depending on each other.`,
-                    validation: "Verify searches don't actually depend on each other's results",
-                };
-                break;
-            case "duplicate_llm_processing":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Consider consolidating ${issue.nodes?.length ?? 0} LLM nodes processing "${issue.search_source}"`,
-                    before: `# Current: ${issue.nodes?.length ?? 0} LLM nodes all process results from ${issue.search_source}
-# Nodes: ${issue.nodes?.join(", ")}`,
-                    after: `# OPTION 1: If these are conditional responses (different intents), keep as-is
-# This is the CORRECT pattern for categorizer-based routing
-
-# OPTION 2: If these produce similar outputs, consolidate into one:
-- name: "unified_response"
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "call_llm"
-  inputs:
-    query:
-      actionOutput:
-        actionName: "trigger"
-        output: "user_query"
-    named_inputs:
-      multiBinding:
-        elements:
-          - namedBinding:
-              name: "Search Results"
-              value:
-                actionOutput:
-                  actionName: "${issue.search_source}"
-                  output: "search_results"
-    instructions:
-      inline:
-        wellKnown:
-          stringValue: "Comprehensive instructions that handle all response types..."`,
-                    validation: "Verify consolidation doesn't lose intent-specific response quality",
-                };
-                break;
-            // NEW: Category/routing structure fixes
-            case "unused_category":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Add handler for unused category "${issue.category}"`,
-                    after: `# CRITICAL: Category "${issue.category}" has NO HANDLER - requests will SILENTLY FAIL!
-# 
-# OPTION 1: Add a handler node with runIf condition:
-- name: "${issue.category?.toLowerCase().replace(/_/g, "_")}_handler"
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]
-      name: "call_llm"
-  runIf:
-    lhs:
-      actionOutput:
-        actionName: "${issue.node}"
-        output: "category"
-    operator: 1  # EQUALS
-    rhs:
-      inline:
-        enumValue: "${issue.category}"
-  inputs:
-    # ... configure LLM for this category ...
-  displaySettings:
-    displayName: "${issue.category} Handler"
-
-# OPTION 2: Add to Config.tasks if using config-based routing:
-# In your fixed_response config node, add:
-"tasks": {
-  "${issue.category}": "Task instructions for handling ${issue.category} requests..."
-}
-
-# OPTION 3: Remove the category if not needed:
-# Delete "${issue.category}" from enumType.options`,
-                    validation: `Verify "${issue.category}" has a handler (runIf condition or Config.tasks entry)`,
-                };
-                break;
-            case "category_name_mismatch":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Fix category name mismatch: "${issue.category}" vs "${issue.config_key}"`,
-                    before: `# PROBLEM: Enum defines "${issue.category}" but Config.tasks has "${issue.config_key}"
-# The workflow looks for Config.tasks["${issue.category}"] which doesn't exist!`,
-                    after: `# OPTION 1: Rename the enum category to match config:
-# In enumType.options, change:
-- name: "${issue.category}"  # OLD
-+ name: "${issue.config_key}"  # NEW (matches Config.tasks)
-
-# OPTION 2: Add the missing key to Config.tasks:
-# In your fixed_response config, add:
-"tasks": {
-  "${issue.category}": "... task instructions ..."  # ADD THIS
-}
-
-# OPTION 3: If both names should exist, add both to Config.tasks:
-"tasks": {
-  "${issue.config_key}": "...",  # existing
-  "${issue.category}": "..."      # add alias or separate task
-}`,
-                    validation: `Verify enum category name matches Config.tasks key exactly`,
-                };
-                break;
-            case "late_categorizer":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Move categorizer "${issue.node}" earlier in the workflow`,
-                    before: `# PROBLEM: Heavy processing runs BEFORE categorization
-# Nodes before categorizer: ${issue.nodes?.join(", ")}
-# This wastes compute for ALL requests, not just the branch that needs it.`,
-                    after: `# RECOMMENDED STRUCTURE: Categorize FIRST, process LATE
-# 
-# ✅ EFFICIENT:
-# trigger → categorizer → [branch A: search + LLM]
-#                       → [branch B: search + LLM]  
-#                       → [branch C: just LLM]
-#
-# ❌ WASTEFUL:
-# trigger → summarize → search → categorizer → [branches]
-#         (ALL requests pay this cost!)
-#
-# TO FIX:
-# 1. Move summarization/search to AFTER categorizer, inside each branch
-# 2. OR use a lightweight "pre-categorizer" that only needs trigger.user_query
-# 
-# Minimal categorizer pattern:
-- name: "intent_classifier"
-  action:
-    name:
-      namespaces: ["actions", "emainternal"]  
-      name: "chat_categorizer"
-  inputs:
-    conversation:
-      actionOutput:
-        actionName: "trigger"
-        output: "chat_conversation"  # Light input, no heavy processing
-    # Optional: provide examples in custom_data for better accuracy`,
-                    validation: `Verify categorizer runs early with minimal upstream processing`,
-                };
-                break;
-            case "excessive_llm_calls":
-                fix = {
-                    issue_type: issue.type,
-                    description: `Reduce LLM calls from ${issue.llm_count} to ≤3 per request`,
-                    before: `# Current path has ${issue.llm_count} LLM calls: ${issue.nodes?.join(" → ")}
-# Each call adds 1-3 seconds. Total: ${(issue.llm_count ?? 0) * 2}+ seconds worst case.
-# Users typically abandon after 5-8 seconds.`,
-                    after: `# STRATEGIES TO REDUCE LLM CALLS:
-#
-# 1. CONSOLIDATE: Merge multiple LLM tasks into one
-#    Instead of: summarize → extract → respond (3 calls)
-#    Use: single call_llm with combined instructions
-#
-# 2. PARALLELIZE: Run independent LLMs simultaneously
-#    Instead of: A → B → C (sequential)
-#    Use: [A, B, C in parallel] → combine (1 effective wait)
-#
-# 3. ELIMINATE: Remove unnecessary LLM steps
-#    - Use json_mapper instead of LLM for simple transformations
-#    - Use fixed_response for static content
-#    - Use entity_extraction (1 call) instead of custom_agent (1 call)
-#
-# 4. CACHE: Reuse results across requests
-#    - Pre-compute common responses
-#    - Store client summaries in knowledge base
-#
-# RECOMMENDED: Max 3 LLM calls per request
-# - 1x categorizer/extraction (optional, can use rules)
-# - 1x main processing (search + reasoning)  
-# - 1x response formatting (if needed)`,
-                    validation: `Verify critical paths have ≤3 LLM calls total`,
-                };
-                break;
-        }
-        if (fix) {
-            fixes.push(fix);
-        }
-    }
-    return fixes;
-}
 // ─────────────────────────────────────────────────────────────────────────────
 // Deprecated Actions Registry (GENERATED - DO NOT EDIT)
 // 
@@ -3712,6 +1867,12 @@ export { DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT,
 /**
  * Constraints that must be satisfied for a workflow to be enabled.
  * These are checked by the Ema backend when attempting to enable a persona.
+ *
+ * SOURCE: ema-repos/ema/docs/workflow-architecture-handoff.md (lines 85-200, constraint checklist 153-167)
+ * STATUS: Can be auto-generated from source doc
+ * TODO: Add to catalog-sync.yml workflow for automatic updates
+ *
+ * See .ctx/docs/source-repos.md for sync details
  */
 export const WORKFLOW_ENABLING_CONSTRAINTS = [
     {