@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/knowledge.js

@@ -0,0 +1,2780 @@
+/**
+ * Auto Builder Knowledge Base
+ *
+ * Structured knowledge about Ema Auto Builder and AI Employee platform for MCP exposure.
+ * Sources:
+ * - .cursor/rules/platforms/ema-auto-builder/
+ * - Ema User Guide documentation
+ * - Platform best practices
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Platform Concepts (from Ema User Guide)
+// ─────────────────────────────────────────────────────────────────────────────
+export const PLATFORM_CONCEPTS = [
+    {
+        term: "AI Employee",
+        definition: "A fully configured, deployable autonomous agent with identity, role, capabilities, knowledge, integrations, and access controls. Think of it as a digital team member.",
+        aliases: ["Persona", "AI Agent"],
+        relatedTerms: ["Workflow", "Agent", "Trigger"],
+        examples: ["HR Support AI", "Customer Service AI", "Document Processing AI"],
+        commonConfusions: "An AI Employee CONTAINS agents. Agents are individual capabilities; AI Employees are the complete packages.",
+    },
+    {
+        term: "Workflow",
+        definition: "A sequence of agents/actions orchestrated to complete a task. Defines the processing logic of an AI Employee.",
+        aliases: ["Process", "Flow"],
+        relatedTerms: ["Agent", "Trigger", "Edge"],
+        commonConfusions: "Workflow describes backend logic (what agents, how they connect). Persona configuration describes frontend behavior (how the AI talks).",
+    },
+    {
+        term: "Agent",
+        definition: "A specialized capability within a workflow (search, respond, classify, etc.). Individual skills that an AI Employee uses.",
+        aliases: ["Action", "Node", "Skill"],
+        relatedTerms: ["Workflow", "AI Employee"],
+        examples: ["Knowledge Search", "Intent Classifier", "Response Generator", "Entity Extractor"],
+    },
+    {
+        term: "Action",
+        definition: "A discrete operation an agent can perform. Platform's term for individual operations.",
+        aliases: ["Tool", "Step", "Operation"],
+        relatedTerms: ["Agent", "External Action", "Connector"],
+        commonConfusions: "Action, Tool, and Step can refer to the same thing depending on context!",
+    },
+    {
+        term: "Trigger",
+        definition: "What initiates a workflow execution. The entry point for AI Employee interactions.",
+        aliases: ["Entry Point", "Initiator"],
+        examples: ["chat_trigger", "voice_trigger", "document_trigger", "email_trigger", "scheduled_trigger"],
+    },
+    {
+        term: "HITL",
+        definition: "Human-in-the-Loop. An approval/verification step where a human reviews before the workflow continues.",
+        aliases: ["Human Collaboration", "Approval Step", "Review Step"],
+        relatedTerms: ["general_hitl"],
+        commonConfusions: "HITL nodes MUST have both success AND failure paths defined.",
+    },
+    {
+        term: "Connector",
+        definition: "A pre-built integration that enables agents to interact with external enterprise systems.",
+        aliases: ["Integration", "Tool", "External Action"],
+        examples: ["ServiceNow connector", "Salesforce connector", "Workday connector", "Email connector"],
+    },
+    {
+        term: "EmaFusion",
+        definition: "Routes queries to optimal models from 100+ LLMs for best results.",
+        relatedTerms: ["fusionModel", "Model Selection"],
+    },
+    {
+        term: "GWE",
+        definition: "Generative Workflow Engine - Builds workflows from natural language prompts via the Auto Builder.",
+        aliases: ["Generative Workflow Engine", "Auto Builder Engine"],
+    },
+    {
+        term: "Agent Mesh",
+        definition: "Network of specialized agents working together as a team collaboration pattern.",
+        relatedTerms: ["AI Employee", "Workflow"],
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow Execution Model (Critical Knowledge)
+// ─────────────────────────────────────────────────────────────────────────────
+export const WORKFLOW_EXECUTION_MODEL = {
+    criticalRule: "Each user_query (user message) triggers a NEW workflow execution. The workflow runs ONCE per user message, not once per conversation.",
+    implications: [
+        "Each subsequent question is its own user_query that invokes the workflow again",
+        "chat_conversation accumulates across executions, but each execution starts fresh",
+        "Avoid duplicate actions - check context before performing actions",
+        "Use conversation history to understand what actions were already taken",
+        "Use runIf conditions to skip redundant operations based on conversation state",
+    ],
+    antiPattern: {
+        description: "Creating duplicate records on follow-up questions",
+        bad: `User: "Create a ticket for my laptop issue" → Workflow creates ticket ✓
+User: "Add my phone number to it" → Workflow runs again - might create ANOTHER ticket ✗`,
+        good: `Use chat_conversation to detect if a ticket was already created in this conversation,
+then route to "update ticket" instead of "create ticket"`,
+    },
+    triggerOutputs: {
+        chat_conversation: {
+            scope: "All history - complete conversation from start",
+            useCase: "When you need full context and don't want to lose any information",
+        },
+        user_query: {
+            scope: "Last message only - just the current question",
+            useCase: "Simple queries where history doesn't matter",
+        },
+        conversation_summarizer: {
+            scope: "Configurable - specify how many turns/how far back",
+            useCase: "When you need to limit context window or summarize long conversations",
+        },
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Agent Catalog
+// ─────────────────────────────────────────────────────────────────────────────
+export const AGENT_CATALOG = [
+    // Triggers
+    {
+        actionName: "chat_trigger",
+        displayName: "Chat Trigger",
+        category: "trigger",
+        description: "Entry point for chat-based interactions. Outputs both conversation history and current query.",
+        inputs: [],
+        outputs: [
+            { name: "chat_conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", description: "Full conversation history from start" },
+            { name: "user_query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Current user message only" },
+        ],
+        whenToUse: "Starting point for any chat or voice AI workflow",
+        criticalRules: [
+            "Each user message triggers a NEW workflow execution",
+            "chat_conversation accumulates; user_query is current message only",
+        ],
+    },
+    {
+        actionName: "document_trigger",
+        displayName: "Document Trigger",
+        category: "trigger",
+        description: "Entry point for document processing workflows triggered by file upload.",
+        inputs: [],
+        outputs: [
+            { name: "user_query", type: "WELL_KNOWN_TYPE_DOCUMENT", description: "Uploaded document(s)" },
+        ],
+        whenToUse: "When workflow is triggered by document upload for processing/extraction",
+    },
+    {
+        actionName: "voice_trigger",
+        displayName: "Voice Trigger",
+        category: "trigger",
+        description: "Entry point for voice/phone call interactions.",
+        inputs: [],
+        outputs: [
+            { name: "chat_conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", description: "Voice conversation history" },
+            { name: "user_query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Current utterance" },
+        ],
+        whenToUse: "Voice AI employees handling phone calls",
+    },
+    // Routing / Classification
+    {
+        actionName: "chat_categorizer",
+        displayName: "Intent Classifier",
+        category: "routing",
+        description: "Classifies user intent into predefined categories for routing. First routing node after trigger.",
+        inputs: [
+            { name: "conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", required: true, description: "Chat conversation to classify" },
+        ],
+        outputs: [
+            { name: "category", type: "WELL_KNOWN_TYPE_ENUM", description: "Outputs the matched category enum value (e.g., 'Client_Update', 'Fallback')" },
+        ],
+        criticalRules: [
+            "MUST have at least one outgoing edge",
+            "runIf condition: compare 'output: category' to 'enumValue: <CategoryName>' (NOT category_<name> format)",
+            "Target input MUST be: trigger_when",
+            "ALWAYS include a Fallback category",
+            "Create a runIf condition for EACH category or routing fails",
+            "You MUST create a handler for EACH category",
+        ],
+        whenToUse: "When you need to route chat conversations to different processing paths based on intent",
+        whenNotToUse: "Simple single-path workflows that don't need routing",
+        example: "Categories: [Market_Impact, Client_Lookup, Compliance_Check, Fallback]",
+    },
+    {
+        actionName: "text_categorizer",
+        displayName: "Text Categorizer",
+        category: "routing",
+        description: "Classifies text content (not conversation) into categories.",
+        inputs: [
+            { name: "text", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Text to classify" },
+        ],
+        outputs: [
+            { name: "category", type: "WELL_KNOWN_TYPE_ENUM", description: "Classification result" },
+        ],
+        criticalRules: [
+            "Same rules as chat_categorizer: must have Fallback, edges for each category",
+        ],
+        whenToUse: "When routing based on text content rather than full conversation history",
+    },
+    {
+        actionName: "document_categorizer",
+        displayName: "Document Categorizer",
+        category: "routing",
+        description: "Classifies documents into categories for routing.",
+        inputs: [
+            { name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to classify" },
+        ],
+        outputs: [
+            { name: "category", type: "WELL_KNOWN_TYPE_ENUM", description: "Document classification" },
+        ],
+        whenToUse: "When routing based on document type or content",
+    },
+    {
+        actionName: "conversation_to_search_query",
+        displayName: "Conversation Summarizer",
+        category: "routing",
+        description: "Converts conversation history to a search query. Configurable turn count.",
+        inputs: [
+            { name: "conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", required: true, description: "Conversation to summarize" },
+        ],
+        outputs: [
+            { name: "summarized_conversation", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Distilled search query" },
+        ],
+        whenToUse: "Before search nodes when you have chat_conversation but need TEXT_WITH_SOURCES. Also for managing long conversation context windows.",
+        whenNotToUse: "When trigger.user_query is sufficient for simple queries",
+        criticalRules: [
+            "May still be needed WITH chat_conversation for downstream agents requiring specific format",
+            "Use to reduce conversation size due to LLM context window limits",
+        ],
+    },
+    // Search & Retrieval
+    {
+        actionName: "search",
+        displayName: "File Search / Knowledge Search",
+        category: "search",
+        description: "Searches uploaded documents/knowledge base using hybrid search (keyword + vector).",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Search query" },
+        ],
+        outputs: [
+            { name: "search_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Matching passages with sources and citations" },
+        ],
+        whenToUse: "When searching static uploaded documents or internal knowledge base",
+        example: "FAQ lookup, policy search, documentation assistant",
+    },
+    {
+        actionName: "live_web_search",
+        displayName: "Live Web Search / Deep Web Search",
+        category: "search",
+        description: "Real-time web search for external information not in knowledge base.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Search query" },
+        ],
+        outputs: [
+            { name: "web_search_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Web search results" },
+        ],
+        whenToUse: "When you need real-time external information not in the knowledge base",
+        example: "Current events, live data, external research",
+    },
+    {
+        actionName: "combine_search_results",
+        displayName: "Combine Search Results",
+        category: "search",
+        description: "Merges results from multiple search sources with deduplication.",
+        inputs: [
+            { name: "search_results_1", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "First result set" },
+            { name: "search_results_2", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "Second result set" },
+        ],
+        outputs: [
+            { name: "combined_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Merged, deduplicated results" },
+        ],
+        criticalRules: [
+            "AVOID using unless necessary - prefer combine_and_rerank_search_results or call_llm with named_inputs",
+            "combine_and_rerank_search_results provides intelligent relevance ranking",
+            "call_llm with named_inputs allows prompt-based ranking control",
+        ],
+        whenToUse: "When combining local + web search, or multiple knowledge bases",
+        whenNotToUse: "When you need intelligent ranking - use combine_and_rerank_search_results instead",
+    },
+    {
+        actionName: "combine_and_rerank_search_results",
+        displayName: "Rerank Search Results",
+        category: "search",
+        description: "Combines and reranks search results by relevance.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Original query for relevance scoring" },
+            { name: "search_results_lists", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "Results to rerank" },
+        ],
+        outputs: [
+            { name: "reranked_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Reranked results" },
+        ],
+        whenToUse: "When you need to prioritize results by relevance after combining multiple sources",
+    },
+    {
+        actionName: "document_metasearch",
+        displayName: "Document Metasearch",
+        category: "search",
+        description: "Searches across document metadata.",
+        inputs: [
+            { name: "template", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Search template" },
+        ],
+        outputs: [
+            { name: "document_metasearch_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", description: "Metadata search results" },
+        ],
+        whenToUse: "When searching by document metadata rather than content",
+    },
+    // Generation & Response
+    {
+        actionName: "call_llm",
+        displayName: "Respond",
+        category: "generation",
+        description: "Generates response using LLM with custom instructions. Accepts ANY type via named_inputs. Also used for LLM templating.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "User query" },
+            { name: "named_inputs", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "Additional context (use named_inputs_<Name> suffix)" },
+        ],
+        outputs: [
+            { name: "response_with_sources", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Generated response" },
+        ],
+        whenToUse: "When you need custom response generation, content synthesis, or LLM templating for documents",
+        whenNotToUse: "For strict regulatory formats requiring pixel-perfect layouts - use template engine instead",
+        criticalRules: [
+            "named_inputs accepts ANY type - use for tool results, search results, etc.",
+            "Use suffix pattern: named_inputs_<Descriptive_Name>",
+            "LLM TEMPLATING: Include structured section headers (## Section) in prompt - let LLM determine appropriate sections based on content",
+            "For document generation: Set temperature 0.3-0.5 for consistent formatting",
+            "Use structured prompts with clear formatting rules and examples",
+        ],
+        example: "named_inputs_Market_Context, named_inputs_Client_Data | " +
+            "LLM Template prompt: 'Generate structured content with clear ## section headers, organized by themes'",
+    },
+    {
+        actionName: "generate_document",
+        displayName: "Generate Document",
+        category: "generation",
+        description: "Converts markdown content to formatted document (.docx). Use after call_llm for document generation workflows.",
+        inputs: [
+            { name: "markdown_file_contents", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Well-structured markdown to convert" },
+            { name: "template", type: "WELL_KNOWN_TYPE_DOCUMENT", required: false, description: "Optional template from data source for styling" },
+        ],
+        outputs: [
+            { name: "document_link", type: "WELL_KNOWN_TYPE_DOCUMENT", description: "Link to generated document" },
+        ],
+        whenToUse: "When converting LLM-generated markdown to professional document format",
+        criticalRules: [
+            "Ensure input markdown has clear headers (## Section) and structure",
+            "For email attachment: use named_inputs (not attachment_links) due to DOCUMENT type",
+            "Chain pattern: call_llm (content generation) → generate_document → send_email (via named_inputs)",
+            "Optional: Add CSS/styling in markdown for professional formatting",
+        ],
+        example: "detailed_content (call_llm) → generate_doc → send_email.named_inputs_Attachment",
+    },
+    {
+        actionName: "respond_with_sources",
+        displayName: "Respond using Search Results",
+        category: "generation",
+        description: "Generates response grounded in search results with citations.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "User query" },
+            { name: "search_results", type: "WELL_KNOWN_TYPE_SEARCH_RESULT", required: true, description: "Search results to ground response" },
+        ],
+        outputs: [
+            { name: "response_with_sources", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Response with citations" },
+        ],
+        whenToUse: "When you want responses grounded in specific search results with source citations",
+        criticalRules: [
+            "Enable use_citation_based_filtering for trust",
+            "Implement confidence thresholds for quality control",
+        ],
+    },
+    {
+        actionName: "respond_for_external_actions",
+        displayName: "Respond using Tool Result",
+        category: "generation",
+        description: "Generates response explaining external tool/action results.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Original query" },
+            { name: "external_action_result", type: "WELL_KNOWN_TYPE_ANY", required: true, description: "Tool execution result" },
+        ],
+        outputs: [
+            { name: "response", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Human-friendly explanation" },
+        ],
+        whenToUse: "After external_action_caller to explain results to user",
+    },
+    {
+        actionName: "fixed_response",
+        displayName: "Fixed Response",
+        category: "generation",
+        description: "Returns a static/template response with {{variable}} substitution. No LLM call.",
+        inputs: [
+            { name: "named_inputs", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "Variables to substitute into template (use named_inputs_<Variable_Name>)" },
+            { name: "extracted_variables", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "JSON key-value pairs for variable substitution" },
+            { name: "fixed_response", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Template with {{variable_name}} placeholders" },
+        ],
+        outputs: [
+            { name: "fixed_response_with_sources", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Response with variables substituted" },
+        ],
+        whenToUse: "For short, structured messages with variables: confirmations, acknowledgments, simple notifications",
+        whenNotToUse: "For complex templates - use data source templates with generate_document or fill_document_template instead",
+        criticalRules: [
+            "Use {{variable_name}} syntax for dynamic content (case-sensitive)",
+            "named_inputs takes precedence over extracted_variables when same variable name exists",
+            "Keep templates SHORT - for long emails/documents use data source templates",
+            "Variables must match exactly including case",
+        ],
+        example: "Template: 'Dear {{Customer_Name}}, your order {{Order_ID}} has been {{Status}}.' " +
+            "→ Connect entity_extraction.customer_name to named_inputs_Customer_Name",
+    },
+    {
+        actionName: "send_email_agent",
+        displayName: "Send Email",
+        category: "external",
+        description: "Sends email via configured email provider.",
+        inputs: [
+            { name: "email_to", type: "WELL_KNOWN_TYPE_ANY", required: true, description: "Recipient email address - MUST be from entity_extraction" },
+            { name: "email_subject", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "Email subject line" },
+            { name: "email_body", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Email body content" },
+            { name: "attachment_links", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: false, description: "Document links to attach (use named_inputs for DOCUMENT type)" },
+        ],
+        outputs: [
+            { name: "send_status", type: "WELL_KNOWN_TYPE_ANY", description: "Send confirmation" },
+        ],
+        whenToUse: "When you need to send email after user confirmation",
+        criticalRules: [
+            "CRITICAL: email_to MUST be from entity_extraction.email_address - NOT from text outputs",
+            "ALWAYS use HITL confirmation before sending (runIf: 'HITL Success')",
+            "For attachments with DOCUMENT type, use named_inputs instead of attachment_links",
+            "Never connect summarized_conversation, response_with_sources, or search_results to email_to",
+        ],
+        example: "entity_extraction.email_address → send_email.email_to (CORRECT) | " +
+            "summarized_conversation → send_email.email_to (WRONG - this is text, not an email address)",
+    },
+    // External Actions
+    {
+        actionName: "external_action_caller",
+        displayName: "External Tool Caller / Intelligent Actions",
+        category: "external",
+        description: "Calls external APIs/tools (ServiceNow, Salesforce, Workday, etc.).",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Context for tool call" },
+            { name: "conversation", type: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", required: false, description: "Conversation history" },
+        ],
+        outputs: [
+            { name: "tool_execution_result", type: "WELL_KNOWN_TYPE_ANY", description: "Tool execution result" },
+        ],
+        whenToUse: "When you need to call external systems (create ticket, send email, lookup CRM, update records)",
+        criticalRules: [
+            "Check conversation history before creating records to avoid duplicates",
+            "Use HITL for actions with external side effects",
+        ],
+        example: "ServiceNow ticket creation, Salesforce record update, Email sending",
+    },
+    // Entity & Rule Processing
+    {
+        actionName: "entity_extraction_with_documents",
+        displayName: "Entity Extraction",
+        category: "entity",
+        description: "Extracts structured entities from documents for cross-document linking or API calls.",
+        inputs: [
+            { name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to extract from" },
+            { name: "extraction_columns", type: "WELL_KNOWN_TYPE_ANY", required: true, description: "Schema defining what to extract" },
+        ],
+        outputs: [
+            { name: "extraction_columns", type: "WELL_KNOWN_TYPE_ANY", description: "Extracted structured data" },
+        ],
+        criticalRules: [
+            "Works on DOCUMENTS, not text",
+            "Requires schema definition for extraction columns",
+        ],
+        whenToUse: "When you need structured data extraction for cross-document linking, API calls, or audit trails with citations",
+        whenNotToUse: "For simple conversational queries—use LLM resolution instead",
+    },
+    {
+        actionName: "rule_validation_with_documents",
+        displayName: "Rule Validation",
+        category: "validation",
+        description: "Validates extracted data against business rules.",
+        inputs: [
+            { name: "primary_docs", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Primary documents" },
+            { name: "map_of_extracted_columns", type: "WELL_KNOWN_TYPE_ANY", required: true, description: "Extracted data to validate" },
+        ],
+        outputs: [
+            { name: "ruleset_output", type: "WELL_KNOWN_TYPE_ANY", description: "Validation results" },
+        ],
+        whenToUse: "For compliance checks, business rule validation, threshold checking",
+    },
+    // Human Collaboration
+    {
+        actionName: "general_hitl",
+        displayName: "Human Collaboration",
+        category: "collaboration",
+        description: "Routes for human review/approval. Critical for sensitive actions. Special categorizer with fixed categories.",
+        inputs: [
+            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Context for review" },
+        ],
+        outputs: [
+            // NOTE: Edge source_output uses space: "hitl_status_HITL Success" (not underscore)
+            // The runIf enumValue also uses space: "HITL Success" / "HITL Failure"
+            { name: "hitl_status_HITL Success", type: "WELL_KNOWN_TYPE_ANY", description: "Human approved path" },
+            { name: "hitl_status_HITL Failure", type: "WELL_KNOWN_TYPE_ANY", description: "Human rejected path" },
+        ],
+        criticalRules: [
+            "MUST have both 'hitl_status_HITL Success' AND 'hitl_status_HITL Failure' paths (note: space, not underscore)",
+            "Both paths must lead to valid response nodes and WORKFLOW_OUTPUT",
+            "Missing HITL on sensitive actions = unintended actions taken",
+            "Unlike regular categorizers, NO Fallback category - only Success/Failure",
+            "Connect HITL outputs to downstream node's trigger_when input",
+        ],
+        whenToUse: "For high-impact actions requiring human oversight, any action with external side effects",
+        example: "source_output: 'hitl_status_HITL Success' → target_input: 'trigger_when'",
+    },
+    // Validation & Guardrails
+    {
+        actionName: "response_validator",
+        displayName: "Response Validator",
+        category: "validation",
+        description: "Validates LLM output against criteria. Guardrail for response quality.",
+        inputs: [
+            { name: "reference_query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Original query" },
+            { name: "response_to_validate", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Response to check" },
+        ],
+        outputs: [
+            { name: "abstain_reason", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Reason if validation fails" },
+        ],
+        whenToUse: "For guardrails, compliance checking on generated responses, quality control",
+    },
+    {
+        actionName: "abstain_action",
+        displayName: "Abstain from Answering",
+        category: "validation",
+        description: "Declines to answer when appropriate. Graceful handling of out-of-scope queries.",
+        inputs: [
+            { name: "abstain_reason", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Why abstaining" },
+        ],
+        outputs: [
+            { name: "abstain_reason", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Abstention message" },
+        ],
+        whenToUse: "When the AI should explicitly decline to answer or redirect",
+    },
+    // Sentiment & Analysis
+    {
+        actionName: "sentiment_analyzer",
+        displayName: "Sentiment Analyzer",
+        category: "analytics",
+        description: "Analyzes sentiment/emotion in user input.",
+        inputs: [
+            { name: "text", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Text to analyze" },
+        ],
+        outputs: [
+            { name: "sentiment", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Sentiment analysis" },
+        ],
+        whenToUse: "When you need to gauge user emotion for routing or response tone adjustment",
+    },
+    // Domain Agents - Finance
+    {
+        actionName: "financial_risk_assessor",
+        displayName: "Financial Risk Assessor",
+        category: "finance",
+        description: "Analyzes financial risk factors for investment/credit decisions.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Risk query" }],
+        outputs: [{ name: "risk_assessment", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Risk analysis" }],
+        whenToUse: "Financial services: portfolio risk, credit assessment, exposure analysis",
+    },
+    {
+        actionName: "financial_statement_analyzer",
+        displayName: "Financial Statement Analyzer",
+        category: "finance",
+        description: "Analyzes financial statements and reports.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Financial documents" }],
+        outputs: [{ name: "analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Financial analysis" }],
+        whenToUse: "Analyzing P&L, balance sheets, annual reports",
+    },
+    {
+        actionName: "tax_advisor",
+        displayName: "Tax Advisor",
+        category: "finance",
+        description: "Provides tax-related guidance and analysis.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Tax question" }],
+        outputs: [{ name: "tax_advice", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Tax guidance" }],
+        whenToUse: "Tax planning, compliance questions, deduction analysis",
+    },
+    {
+        actionName: "audit_evidence_verifier",
+        displayName: "Audit Evidence Verifier",
+        category: "finance",
+        description: "Verifies audit evidence and documentation.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Audit documents" }],
+        outputs: [{ name: "verification", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Verification results" }],
+        whenToUse: "Audit support, evidence verification, compliance documentation",
+    },
+    // Domain Agents - Healthcare
+    {
+        actionName: "medical_record_summarizer",
+        displayName: "Medical Record Summarizer",
+        category: "healthcare",
+        description: "Summarizes medical records and patient history.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Medical records" }],
+        outputs: [{ name: "summary", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Record summary" }],
+        whenToUse: "Healthcare: summarizing patient records, medical history, clinical notes",
+    },
+    {
+        actionName: "medical_research_assistant",
+        displayName: "Medical Research Assistant",
+        category: "healthcare",
+        description: "Assists with medical research queries.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Research query" }],
+        outputs: [{ name: "research", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Research findings" }],
+        whenToUse: "Medical research, literature review, clinical guidance",
+    },
+    {
+        actionName: "insurance_claim_summarizer",
+        displayName: "Insurance Claim Summarizer",
+        category: "healthcare",
+        description: "Summarizes insurance claims and documentation.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Claim documents" }],
+        outputs: [{ name: "summary", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Claim summary" }],
+        whenToUse: "Insurance processing, claim analysis",
+    },
+    // Domain Agents - Legal
+    {
+        actionName: "compliance_document_analyzer",
+        displayName: "Compliance Document Analyzer",
+        category: "legal",
+        description: "Analyzes documents for compliance issues.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to analyze" }],
+        outputs: [{ name: "compliance_findings", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Compliance analysis" }],
+        whenToUse: "Regulatory compliance, contract review, policy compliance",
+    },
+    {
+        actionName: "legal_expert",
+        displayName: "Legal Expert",
+        category: "legal",
+        description: "Provides legal analysis and guidance.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Legal question" }],
+        outputs: [{ name: "legal_analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Legal guidance" }],
+        whenToUse: "Legal research, contract analysis, regulatory questions",
+    },
+    {
+        actionName: "information_redacter",
+        displayName: "Information Redacter",
+        category: "legal",
+        description: "Redacts sensitive information from documents.",
+        inputs: [{ name: "documents", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Documents to redact" }],
+        outputs: [{ name: "redacted", type: "WELL_KNOWN_TYPE_DOCUMENT", description: "Redacted documents" }],
+        whenToUse: "Privacy compliance, document sanitization",
+    },
+    // Domain Agents - IT/Security
+    {
+        actionName: "phishing_email_detector",
+        displayName: "Phishing Email Detector",
+        category: "it_security",
+        description: "Detects phishing attempts in emails.",
+        inputs: [{ name: "email_content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Email to analyze" }],
+        outputs: [{ name: "detection_result", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Phishing analysis" }],
+        whenToUse: "Email security, security operations",
+    },
+    {
+        actionName: "cybersecurity_expert",
+        displayName: "Cybersecurity Expert",
+        category: "it_security",
+        description: "Provides cybersecurity analysis and guidance.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Security query" }],
+        outputs: [{ name: "security_analysis", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Security guidance" }],
+        whenToUse: "Security incident analysis, vulnerability assessment",
+    },
+    {
+        actionName: "technical_support",
+        displayName: "Technical Support",
+        category: "it_security",
+        description: "Provides IT technical support guidance.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Support query" }],
+        outputs: [{ name: "support_response", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Technical guidance" }],
+        whenToUse: "IT helpdesk, troubleshooting, technical guidance",
+    },
+    // Domain Agents - Sales
+    {
+        actionName: "sales_intelligence",
+        displayName: "Sales Intelligence",
+        category: "sales",
+        description: "Provides sales insights and account intelligence.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Sales query" }],
+        outputs: [{ name: "intelligence", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Sales insights" }],
+        whenToUse: "Account research, competitive analysis, opportunity assessment",
+    },
+    {
+        actionName: "email_writer",
+        displayName: "Email Writer",
+        category: "sales",
+        description: "Generates professional email content.",
+        inputs: [{ name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Email context" }],
+        outputs: [{ name: "email", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Generated email" }],
+        whenToUse: "Sales outreach, customer communication, follow-ups",
+    },
+    // Formatting Agents
+    {
+        actionName: "json_formatter",
+        displayName: "JSON Formatter",
+        category: "formatting",
+        description: "Formats output as JSON.",
+        inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content to format" }],
+        outputs: [{ name: "json", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "JSON formatted output" }],
+        whenToUse: "When structured JSON output is required",
+    },
+    {
+        actionName: "json_extractor",
+        displayName: "JSON Extractor",
+        category: "formatting",
+        description: "Extracts JSON from LLM output.",
+        inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content containing JSON" }],
+        outputs: [{ name: "extracted_json", type: "WELL_KNOWN_TYPE_ANY", description: "Extracted JSON object" }],
+        whenToUse: "When you need to parse JSON from LLM responses",
+    },
+    {
+        actionName: "markdown_formatter",
+        displayName: "Markdown Formatter",
+        category: "formatting",
+        description: "Formats output as Markdown.",
+        inputs: [{ name: "content", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Content to format" }],
+        outputs: [{ name: "markdown", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", description: "Markdown formatted output" }],
+        whenToUse: "When rich text formatting is needed",
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Widget Reference
+// ─────────────────────────────────────────────────────────────────────────────
+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"] },
+    { 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"] },
+    // Chat AI Widgets
+    { 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"] },
+    // 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"] },
+];
+// Project type mapping
+export const PROJECT_TYPES = {
+    voice: 5,
+    chat: 4,
+    dashboard: 2,
+    document: 3,
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Compatibility
+// ─────────────────────────────────────────────────────────────────────────────
+export const TYPE_COMPATIBILITY = [
+    // Chat conversation compatibility
+    { sourceType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use conversation_to_search_query to convert" },
+    { sourceType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true, note: "call_llm.named_inputs accepts ANY" },
+    // Text with sources compatibility
+    { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: false, note: "Cannot convert text to conversation" },
+    // Search result compatibility
+    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_SEARCH_RESULT", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use respond_with_sources instead of call_llm for search results" },
+    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true, note: "call_llm.named_inputs accepts ANY" },
+    // Document compatibility
+    { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_DOCUMENT", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", compatible: false, note: "Use entity_extraction or document-specific agents" },
+    // Any type compatibility
+    { sourceType: "WELL_KNOWN_TYPE_ANY", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow Patterns
+// ─────────────────────────────────────────────────────────────────────────────
+export const WORKFLOW_PATTERNS = [
+    {
+        name: "simple-kb-search",
+        personaType: "chat",
+        description: "Basic knowledge base Q&A with search and response",
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_with_sources"],
+        connections: [
+            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
+            "conversation_to_search_query.summarized_conversation → search.query",
+            "search.search_results → respond_with_sources.search_results",
+            "chat_trigger.user_query → respond_with_sources.query",
+            "respond_with_sources.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "FAQ bot, documentation assistant, policy lookup",
+    },
+    {
+        name: "intent-routing",
+        personaType: "chat",
+        description: "Route conversations to different handlers based on intent classification",
+        nodes: ["chat_trigger", "chat_categorizer", "handler_per_category", "fallback_response"],
+        connections: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "chat_categorizer.category_<Category1> → handler_1.trigger_when",
+            "chat_categorizer.category_<Category2> → handler_2.trigger_when",
+            "chat_categorizer.category_Fallback → fallback_response.trigger_when",
+            "handler_*.response → WORKFLOW_OUTPUT",
+            "fallback_response.response → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Multi-purpose assistant with distinct capabilities (HR + IT + General)",
+        antiPatterns: [
+            "Missing Fallback category",
+            "Categories without outgoing edges",
+            "Not all paths leading to WORKFLOW_OUTPUT",
+        ],
+    },
+    {
+        name: "multi-source-search",
+        personaType: "chat",
+        description: "Combine local and web search for comprehensive answers",
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "live_web_search", "combine_search_results", "respond_with_sources"],
+        connections: [
+            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
+            "conversation_to_search_query.summarized_conversation → search.query",
+            "conversation_to_search_query.summarized_conversation → live_web_search.query",
+            "search.search_results → combine_search_results.search_results_1",
+            "live_web_search.web_search_results → combine_search_results.search_results_2",
+            "combine_search_results.combined_results → respond_with_sources.search_results",
+            "chat_trigger.user_query → respond_with_sources.query",
+            "respond_with_sources.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Research assistant needing both internal docs and current web info",
+    },
+    {
+        name: "tool-calling",
+        personaType: "voice",
+        description: "Voice AI that calls external tools (ServiceNow, Salesforce, CRM)",
+        nodes: ["chat_trigger", "chat_categorizer", "external_action_caller", "call_llm"],
+        connections: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "chat_categorizer.category_<Action> → external_action_caller.trigger_when",
+            "chat_trigger.chat_conversation → external_action_caller.conversation",
+            "external_action_caller.tool_execution_result → call_llm.named_inputs_Tool_Result",
+            "chat_trigger.user_query → call_llm.query",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "IT helpdesk, customer service with ticketing, CRM operations",
+        antiPatterns: [
+            "Creating duplicate records on follow-up questions",
+            "Not checking conversation history before actions",
+        ],
+    },
+    {
+        name: "hitl-approval",
+        personaType: "chat",
+        description: "Human-in-the-loop approval workflow for sensitive actions",
+        nodes: ["chat_trigger", "external_action_caller", "general_hitl", "call_llm_approved", "call_llm_rejected"],
+        connections: [
+            "chat_trigger.user_query → external_action_caller.query",
+            "external_action_caller.tool_execution_result → general_hitl.query",
+            "general_hitl.'hitl_status_HITL Success' → call_llm_approved.trigger_when",
+            "general_hitl.'hitl_status_HITL Failure' → call_llm_rejected.trigger_when",
+            "call_llm_approved.response → WORKFLOW_OUTPUT",
+            "call_llm_rejected.response → WORKFLOW_OUTPUT",
+        ],
+        useCase: "High-value transactions, sensitive operations, escalation paths",
+        antiPatterns: [
+            "Missing either success or failure path",
+            "Not terminating both paths at WORKFLOW_OUTPUT",
+        ],
+    },
+    {
+        name: "document-processing",
+        personaType: "dashboard",
+        description: "Document upload → extraction → validation → response",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_with_documents", "call_llm"],
+        connections: [
+            "document_trigger.user_query → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → rule_validation_with_documents.map_of_extracted_columns",
+            "document_trigger.user_query → rule_validation_with_documents.primary_docs",
+            "rule_validation_with_documents.ruleset_output → call_llm.named_inputs_Validation_Results",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Invoice processing, contract analysis, compliance checking",
+    },
+    {
+        name: "guardrails-pattern",
+        personaType: "chat",
+        description: "Response generation with validation guardrails",
+        nodes: ["chat_trigger", "search", "respond_with_sources", "response_validator", "abstain_action"],
+        connections: [
+            "chat_trigger.user_query → search.query",
+            "search.search_results → respond_with_sources.search_results",
+            "respond_with_sources.response_with_sources → response_validator.response_to_validate",
+            "chat_trigger.user_query → response_validator.reference_query",
+            "response_validator.abstain_reason → [conditional: if valid] → WORKFLOW_OUTPUT",
+            "response_validator.abstain_reason → [conditional: if invalid] → abstain_action → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Regulated industries, compliance-sensitive responses",
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Qualifying Questions
+// ─────────────────────────────────────────────────────────────────────────────
+export const QUALIFYING_QUESTIONS = [
+    // Round 1: Core Context (Always ask first)
+    { category: "AI Type", question: "Is this a Voice AI, Chat AI, or Dashboard AI?", whyItMatters: "Determines trigger type, persona settings, UI widgets, and project type", required: true },
+    { category: "AI Type", question: "What triggers the workflow? (phone call, chat message, document upload, email, scheduled)", whyItMatters: "Affects chat_trigger vs document_trigger vs voice_trigger configuration", required: true },
+    { category: "Intent", question: "What are the main intents/categories the AI should recognize? (list 3-5 plus Fallback)", whyItMatters: "Required for chat_categorizer categories and routing logic", required: true },
+    { category: "Intent", question: "What should happen for each category?", whyItMatters: "Determines branching logic and agent paths for each intent", required: true },
+    { category: "Data", question: "What data sources does the AI need to access? (files, APIs, databases, knowledge bases)", whyItMatters: "Determines which search/lookup agents to use", required: true },
+    // Round 2: Workflow Details
+    { category: "Data", question: "Are the data sources static files or live APIs?", whyItMatters: "Static = search agent, Live = external_action_caller", required: false },
+    { category: "Data", question: "What specific fields/entities need to be extracted from queries?", whyItMatters: "May need entity_extraction or conversation_to_search_query", required: false },
+    { category: "Data", question: "Are there multiple data sources that need to be correlated?", whyItMatters: "Requires cross-document linking strategy and combine_search_results", required: false },
+    { category: "Actions", question: "What external tools/APIs should the AI call? (ServiceNow, Salesforce, Workday, etc.)", whyItMatters: "Configures external_action_caller tools and connectors", required: false },
+    { category: "Actions", question: "What actions can the AI perform? (create ticket, send email, update record)", whyItMatters: "Lists available tools and determines action scope", required: false },
+    { category: "Actions", question: "Which actions require human approval?", whyItMatters: "Requires general_hitl with success/failure paths", required: false },
+    { category: "Validation", question: "What validations must be performed? (compliance, rules, thresholds)", whyItMatters: "May need rule_validation_with_documents or response_validator", required: false },
+    { category: "Output", question: "What should the success response look like?", whyItMatters: "Determines call_llm output formatting and response structure", required: true },
+    { category: "Output", question: "What should the error/exception response look like?", whyItMatters: "Needs explicit error handling paths and fallback responses", required: false },
+    { category: "Output", question: "Should responses include citations/sources?", whyItMatters: "Enable use_citation_based_filtering for trust", required: false },
+    // Round 3: Voice AI Specific
+    { category: "Voice", question: "What is the welcome message when the call connects?", whyItMatters: "Required for welcomeMessage persona field", required: false },
+    { category: "Voice", question: "What should the AI's identity and purpose be?", whyItMatters: "Required for identityAndPurpose - defines role and responsibilities", required: false },
+    { category: "Voice", question: "What actions can the voice AI perform? (with trigger conditions and parameters)", whyItMatters: "Required for takeActionInstructions in </Case N> format", required: false },
+    { category: "Voice", question: "When should the AI hang up?", whyItMatters: "Required for hangupInstructions", required: false },
+    { category: "Voice", question: "When should the call transfer to a human?", whyItMatters: "Required for transferCallInstructions", required: false },
+    { category: "Voice", question: "What is the wait message while processing?", whyItMatters: "Required for waitMessage - keeps caller informed during delays", required: false },
+    { category: "Voice", question: "Any speech characteristics? (pace, tone, pronunciation rules)", whyItMatters: "Affects speechCharacteristics for natural conversation", required: false },
+    // Guardrails
+    { category: "Guardrails", question: "What should the AI NEVER do?", whyItMatters: "Defines guardrails, abstain conditions, and out-of-scope handling", required: false },
+    { category: "Guardrails", question: "What PII/sensitive data handling is required?", whyItMatters: "Affects data_protection_config and protectedClasses", required: false },
+    { category: "Guardrails", question: "Are there compliance requirements? (regulations, policies)", whyItMatters: "May need response_validator or compliance_document_analyzer", required: false },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Voice AI Templates
+// ─────────────────────────────────────────────────────────────────────────────
+export const VOICE_PERSONA_TEMPLATE = {
+    welcomeMessage: "Hello, thank you for calling {Company}. This is {AI Name}. How can I help you today?",
+    identityAndPurpose: `You are {AI Name}, a Voice AI assistant for {Company}.
+
+Primary responsibility: {Main purpose}
+
+Your responsibilities:
+1. {Responsibility 1}
+2. {Responsibility 2}
+3. {Responsibility 3}
+
+Rules:
+- {Rule 1}
+- {Rule 2}
+- Always be professional and helpful
+- Never provide information you're not certain about`,
+    takeActionInstructions: `</Case 1>
+{Action 1 Name}
+
+Trigger When:
+{Condition that triggers this action}
+
+Intent for tool call: "{Tool Intent Name}"
+
+Required parameters:
+{ "{param1}": "", "{param2}": "" }
+</Case 1>
+
+</Case 2>
+{Action 2 Name}
+
+Trigger When:
+{Condition that triggers this action}
+
+Intent for tool call: "{Tool Intent Name}"
+
+Required parameters:
+{ "{param1}": "" }
+</Case 2>`,
+    hangupInstructions: `End the call when:
+- The caller explicitly says goodbye or asks to hang up
+- The caller confirms they have no more questions
+- {Additional hangup conditions}
+
+Before ending:
+- Confirm all issues are resolved
+- Offer any follow-up information
+- Thank the caller`,
+    transferCallInstructions: `Transfer the call when:
+- The caller explicitly requests a human agent
+- The issue is beyond AI capabilities
+- {Complex scenario requiring human}
+
+Before transferring:
+- Inform the caller you're transferring them
+- Summarize the issue for the human agent`,
+    speechCharacteristics: `**Conversational Style:**
+- Keep responses brief (2-3 sentences per turn)
+- Use warm, professional tone
+- Speak clearly at moderate pace
+
+**Natural Speech:**
+- Use brief pauses between sentences
+- Acknowledge with 'I understand', 'Of course', 'Certainly'
+- Avoid robotic language
+
+**TTS Pronunciation Rules:**
+- Spell out IDs: 'A-B-C-1-2-3'
+- Pause between numbers: 'Your code is... 1... 2... 3... 4'
+- {Domain-specific pronunciation rules}`,
+    systemPrompt: `Tool Calling Instructions:
+
+1. Always collect ALL required parameters before calling a tool
+2. Confirm parameter values with the caller before executing
+3. Wait for tool response before calling another tool
+4. NEVER mention tool names to the user
+5. NEVER guess parameter values - always ask
+6. Use plain language: "Let me look that up" not "Calling the API"
+7. Handle delays with wait message: "One moment while I check..."
+8. Handle errors gracefully, offer alternatives`,
+    waitMessage: "One moment while I look that up for you...",
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Common Mistakes & Debugging
+// ─────────────────────────────────────────────────────────────────────────────
+export const COMMON_MISTAKES = [
+    { mistake: "Not testing with edge cases", problem: "Unexpected failures in production", solution: "Test with empty inputs, long inputs, multilingual inputs" },
+    { mistake: "Overloading workflows", problem: "Slow execution, timeouts", solution: "Keep workflows focused; split complex ones into multiple AI Employees" },
+    { mistake: "Missing HITL on sensitive actions", problem: "Unintended actions taken with external side effects", solution: "Add HITL for any action with external side effects" },
+    { mistake: "Vague agent instructions", problem: "Inconsistent responses", solution: "Be specific about tone, format, boundaries in instructions" },
+    { mistake: "Not citing sources", problem: "Trust issues with users", solution: "Enable use_citation_based_filtering" },
+    { mistake: "Ignoring confidence scores", problem: "Bad answers served confidently", solution: "Implement confidence thresholds and abstain when uncertain" },
+    { mistake: "Creating duplicate records on follow-ups", problem: "Multiple tickets/records for same issue", solution: "Check chat_conversation for existing records before creating new ones" },
+    { mistake: "Missing Fallback category", problem: "Workflow validation fails, unhandled intents", solution: "ALWAYS include Fallback category in every categorizer" },
+    { mistake: "Type mismatches in connections", problem: "Validation errors, runtime failures", solution: "Check type compatibility: use conversation_to_search_query when needed" },
+    { mistake: "Not mapping to WORKFLOW_OUTPUT", problem: "Responses don't reach user", solution: "Ensure ALL paths terminate at WORKFLOW_OUTPUT" },
+];
+export const DEBUG_CHECKLIST = [
+    { step: 1, action: "Check Status", description: "Is the AI Employee active/ready?", apiField: "status" },
+    { step: 2, action: "Review Trigger", description: "Is the trigger correctly configured?", apiField: "trigger_type" },
+    { step: 3, action: "Trace Execution", description: "Where does the workflow fail? Check execution logs" },
+    { step: 4, action: "Inspect Inputs", description: "Are inputs reaching agents correctly?" },
+    { step: 5, action: "Check Integrations", description: "Are connectors authenticated and working?" },
+    { step: 6, action: "Review Logs", description: "What errors appear in execution trace?" },
+    { step: 7, action: "Test Isolation", description: "Does the agent work in isolation?" },
+    { step: 8, action: "Verify Categorizer", description: "Does categorizer have all category edges including Fallback?" },
+    { step: 9, action: "Check WORKFLOW_OUTPUT", description: "Do all paths lead to WORKFLOW_OUTPUT?" },
+    { step: 10, action: "Validate Types", description: "Are all connections type-compatible?" },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Guidance Topics
+// ─────────────────────────────────────────────────────────────────────────────
+export const GUIDANCE_TOPICS = {
+    "categorizer-routing": {
+        title: "Categorizer Routing Best Practices",
+        content: "Every categorizer must have runIf conditions for each category. The runIf compares output 'category' to enumValue. Always include Fallback.",
+        examples: [
+            "runIf: {lhs: {actionOutput: {actionName: 'chat_categorizer', output: 'category'}, autoDetectedBinding: false}, operator: 1, rhs: {inline: {enumValue: 'Market_Impact'}, autoDetectedBinding: false}}",
+            "runIf: {lhs: {actionOutput: {actionName: 'chat_categorizer', output: 'category'}, autoDetectedBinding: false}, operator: 1, rhs: {inline: {enumValue: 'Fallback'}, autoDetectedBinding: false}}",
+        ],
+        criticalRules: [
+            "MUST have runIf condition for each category",
+            "runIf format: output='category', operator=1 (numeric), enumValue='<CategoryName>'",
+            "DO NOT use 'category_<Name>' as output - use 'category' and compare to enum value",
+            "ALWAYS include Fallback category",
+            "Create handler node with runIf for EACH category",
+        ],
+    },
+    "type-compatibility": {
+        title: "Type Compatibility Rules",
+        content: "Auto Builder validates type compatibility. Common mistake: connecting chat_conversation directly to search.query.",
+        examples: [
+            "✅ trigger.user_query → search.query (TEXT_WITH_SOURCES → TEXT_WITH_SOURCES)",
+            "❌ trigger.chat_conversation → search.query (CHAT_CONVERSATION ≠ TEXT_WITH_SOURCES)",
+            "✅ search.search_results → respond_with_sources.search_results (SEARCH_RESULT → SEARCH_RESULT)",
+            "❌ search.search_results → call_llm.query (SEARCH_RESULT ≠ TEXT_WITH_SOURCES)",
+            "✅ search.search_results → call_llm.named_inputs_* (SEARCH_RESULT → ANY)",
+        ],
+        criticalRules: [
+            "CHAT_CONVERSATION only compatible with chat_categorizer.conversation",
+            "SEARCH_RESULT only compatible with respond_with_sources.search_results or named_inputs",
+            "call_llm.named_inputs accepts ANY type",
+            "Use conversation_to_search_query to convert CHAT_CONVERSATION → TEXT_WITH_SOURCES",
+        ],
+    },
+    "named-inputs": {
+        title: "Named Inputs Pattern",
+        content: "When connecting to call_llm.named_inputs, use suffix: named_inputs_<Descriptive_Name>. The name appears as a label in the workflow UI.",
+        examples: [
+            "named_inputs_Market_Context",
+            "named_inputs_Client_Data",
+            "named_inputs_Tool_Result",
+            "named_inputs_Web_Search_Results",
+            "named_inputs_Validation_Output",
+        ],
+    },
+    "hitl-patterns": {
+        title: "Human-in-the-Loop Patterns",
+        content: "HITL nodes MUST have both success and failure paths. Both paths must lead to valid response nodes and terminate at WORKFLOW_OUTPUT. NOTE: Output names use SPACE not underscore: 'HITL Success' not 'HITL_Success'.",
+        examples: [
+            "general_hitl.'hitl_status_HITL Success' → approved_response.trigger_when",
+            "general_hitl.'hitl_status_HITL Failure' → rejected_response.trigger_when",
+        ],
+        criticalRules: [
+            "MUST define 'hitl_status_HITL Success' path (note: space, not underscore)",
+            "MUST define 'hitl_status_HITL Failure' path (note: space, not underscore)",
+            "Both paths must terminate at WORKFLOW_OUTPUT",
+            "Use for any action with external side effects",
+            "Unlike regular categorizers, NO Fallback category",
+        ],
+    },
+    "multi-source-search": {
+        title: "Multi-Source Search Architecture",
+        content: "For comprehensive answers, combine local search with web search. Use combine_search_results to merge and deduplicate.",
+        examples: [
+            "search (local) + live_web_search → combine_search_results → respond_with_sources",
+            "For cross-document linking: entity_extraction → knowledge_graph_generator → document_synthesis",
+        ],
+        criticalRules: [
+            "Use entity extraction when cross-document linking is needed",
+            "Use LLM resolution for single conversational queries",
+            "Entity extraction requires schema definition",
+        ],
+    },
+    "voice-tool-calling": {
+        title: "Voice AI Tool Calling Rules",
+        content: "Voice AI has specific rules for tool calling to ensure natural conversation flow.",
+        criticalRules: [
+            "Collect ALL required parameters before calling a tool",
+            "Wait for response before calling another tool",
+            "NEVER mention tool names to the user",
+            "NEVER guess parameter values - ask the user",
+            "Use plain language: 'Let me look that up' not 'Calling search API'",
+            "Handle delays with waitMessage: 'One moment while I check...'",
+            "Handle errors gracefully, offer alternatives",
+        ],
+    },
+    "guardrails": {
+        title: "Implementing Guardrails",
+        content: "Use response_validator to check LLM output before sending to user. Use abstain_action when the AI should decline to answer.",
+        examples: [
+            "call_llm → response_validator → (valid) → WORKFLOW_OUTPUT",
+            "call_llm → response_validator → (invalid) → abstain_action → WORKFLOW_OUTPUT",
+        ],
+        criticalRules: [
+            "Enable use_citation_based_filtering for trust",
+            "Implement confidence thresholds",
+            "Define clear abstain conditions",
+        ],
+    },
+    "output-mapping": {
+        title: "Output Mapping to WORKFLOW_OUTPUT",
+        content: "ALL paths must eventually lead to WORKFLOW_OUTPUT. Every response node should have an edge to WORKFLOW_OUTPUT.",
+        examples: [
+            "respond_market.response_with_sources → WORKFLOW_OUTPUT",
+            "fallback_response.response_with_sources → WORKFLOW_OUTPUT",
+            "approved_response.response → WORKFLOW_OUTPUT",
+            "rejected_response.response → WORKFLOW_OUTPUT",
+        ],
+    },
+    "workflow-execution": {
+        title: "Workflow Execution Model",
+        content: "CRITICAL: Each user_query triggers a NEW workflow execution. The workflow runs ONCE per user message, not once per conversation.",
+        examples: [
+            "❌ User: 'Create ticket' → creates ticket; User: 'Add my phone' → creates ANOTHER ticket",
+            "✅ Check chat_conversation for existing ticket, route to 'update' instead of 'create'",
+        ],
+        criticalRules: [
+            "Each user message triggers new workflow execution",
+            "chat_conversation accumulates; user_query is current message only",
+            "Check context before creating records to avoid duplicates",
+            "Use runIf conditions to skip redundant operations",
+        ],
+    },
+    "conversation-vs-query": {
+        title: "Conversation vs Query Usage",
+        content: "Use user_query for current message, chat_conversation for full history, conversation_summarizer for controlled context.",
+        examples: [
+            "user_query: Simple queries where history doesn't matter",
+            "chat_conversation: When you need full context",
+            "conversation_summarizer: Long conversations, context window management",
+        ],
+        criticalRules: [
+            "user_query = current message only (TEXT_WITH_SOURCES)",
+            "chat_conversation = all history (CHAT_CONVERSATION)",
+            "conversation_summarizer may still be needed for downstream agent format requirements",
+        ],
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Functions
+// ─────────────────────────────────────────────────────────────────────────────
+export function getAgentsByCategory(category) {
+    return AGENT_CATALOG.filter(a => a.category === category);
+}
+export function getAgentByName(actionName) {
+    return AGENT_CATALOG.find(a => a.actionName === actionName || a.actionName === actionName.toLowerCase());
+}
+export function getWidgetsForPersonaType(type) {
+    return WIDGET_CATALOG.filter(w => w.requiredFor.includes(type));
+}
+export function checkTypeCompatibility(sourceType, targetType) {
+    return TYPE_COMPATIBILITY.find(t => t.sourceType === sourceType && t.targetType === targetType);
+}
+export function getQualifyingQuestionsByCategory(category) {
+    return QUALIFYING_QUESTIONS.filter(q => q.category.toLowerCase() === category.toLowerCase());
+}
+export function getRequiredQualifyingQuestions() {
+    return QUALIFYING_QUESTIONS.filter(q => q.required);
+}
+export function getConceptByTerm(term) {
+    return PLATFORM_CONCEPTS.find(c => c.term.toLowerCase() === term.toLowerCase() ||
+        c.aliases?.some(a => a.toLowerCase() === term.toLowerCase()));
+}
+export function suggestAgentsForUseCase(useCase) {
+    const keywords = useCase.toLowerCase();
+    const suggestions = [];
+    const added = new Set();
+    const addIfNotPresent = (name) => {
+        if (!added.has(name)) {
+            const agent = getAgentByName(name);
+            if (agent) {
+                suggestions.push(agent);
+                added.add(name);
+            }
+        }
+    };
+    // Always include trigger
+    addIfNotPresent("chat_trigger");
+    // Routing
+    if (keywords.includes("intent") || keywords.includes("route") || keywords.includes("categor") || keywords.includes("multi") || keywords.includes("different")) {
+        addIfNotPresent("chat_categorizer");
+    }
+    // Search
+    if (keywords.includes("search") || keywords.includes("document") || keywords.includes("knowledge") || keywords.includes("faq") || keywords.includes("lookup") || keywords.includes("find")) {
+        addIfNotPresent("conversation_to_search_query");
+        addIfNotPresent("search");
+        addIfNotPresent("respond_with_sources");
+    }
+    // Web search
+    if (keywords.includes("web") || keywords.includes("real-time") || keywords.includes("current") || keywords.includes("live")) {
+        addIfNotPresent("live_web_search");
+        if (added.has("search")) {
+            addIfNotPresent("combine_search_results");
+        }
+    }
+    // External tools
+    if (keywords.includes("ticket") || keywords.includes("servicenow") || keywords.includes("salesforce") || keywords.includes("api") || keywords.includes("create") || keywords.includes("update") || keywords.includes("crm") || keywords.includes("email")) {
+        addIfNotPresent("external_action_caller");
+    }
+    // HITL
+    if (keywords.includes("approval") || keywords.includes("review") || keywords.includes("human") || keywords.includes("sensitive") || keywords.includes("verify")) {
+        addIfNotPresent("general_hitl");
+    }
+    // Compliance/Validation
+    if (keywords.includes("compliance") || keywords.includes("validate") || keywords.includes("rule") || keywords.includes("guardrail")) {
+        addIfNotPresent("response_validator");
+    }
+    // Entity extraction
+    if (keywords.includes("extract") || keywords.includes("entity") || keywords.includes("structure")) {
+        addIfNotPresent("entity_extraction_with_documents");
+    }
+    // Voice specific
+    if (keywords.includes("voice") || keywords.includes("phone") || keywords.includes("call")) {
+        suggestions[0] = getAgentByName("voice_trigger") || suggestions[0];
+    }
+    // Document processing
+    if (keywords.includes("document") || keywords.includes("upload") || keywords.includes("process") || keywords.includes("invoice") || keywords.includes("contract")) {
+        if (!added.has("chat_trigger")) {
+            suggestions[0] = getAgentByName("document_trigger") || suggestions[0];
+        }
+        addIfNotPresent("entity_extraction_with_documents");
+    }
+    // Default response if no response agent added
+    if (!added.has("respond_with_sources") && !added.has("call_llm")) {
+        addIfNotPresent("call_llm");
+    }
+    return suggestions;
+}
+export function validateWorkflowPrompt(prompt) {
+    const lowerPrompt = prompt.toLowerCase();
+    const issues = [];
+    const warnings = [];
+    // Check for categorizer without fallback
+    if ((lowerPrompt.includes("categoriz") || lowerPrompt.includes("classif") || lowerPrompt.includes("route")) &&
+        !lowerPrompt.includes("fallback")) {
+        issues.push("Missing Fallback category - every categorizer MUST have a Fallback");
+    }
+    // Check for HITL without both paths
+    if (lowerPrompt.includes("hitl") || lowerPrompt.includes("human collaboration") || lowerPrompt.includes("approval")) {
+        if (!lowerPrompt.includes("success") || !lowerPrompt.includes("fail")) {
+            issues.push("HITL node requires both success AND failure paths");
+        }
+    }
+    // Check for output mapping
+    if (!lowerPrompt.includes("workflow_output") && !lowerPrompt.includes("output")) {
+        warnings.push("No explicit WORKFLOW_OUTPUT mapping found - ensure all paths lead to output");
+    }
+    // Check for trigger
+    if (!lowerPrompt.includes("trigger") && !lowerPrompt.includes("chat") && !lowerPrompt.includes("voice") && !lowerPrompt.includes("document")) {
+        issues.push("No trigger type specified - include chat_trigger, voice_trigger, or document_trigger");
+    }
+    // Check for common type issues
+    if (lowerPrompt.includes("chat_conversation") && lowerPrompt.includes("search.query")) {
+        warnings.push("Potential type mismatch: chat_conversation → search.query. Use conversation_to_search_query first.");
+    }
+    // Check for persona type
+    if (!lowerPrompt.includes("voice ai") && !lowerPrompt.includes("chat ai") && !lowerPrompt.includes("dashboard ai") && !lowerPrompt.includes("persona type")) {
+        warnings.push("No persona type specified - should specify Voice AI, Chat AI, or Dashboard AI");
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+        warnings,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow Analysis Functions
+// ─────────────────────────────────────────────────────────────────────────────
+// Import validation rules from single source of truth
+import { INPUT_SOURCE_RULES as VALIDATION_INPUT_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES, findInputSourceRule, findAntiPatternByIssueType, generateMarkdownDocumentation, exportRulesAsJSON, } from "./validation-rules.js";
+// Re-export for consumers who want access to rules
+export { VALIDATION_INPUT_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES, findInputSourceRule, findAntiPatternByIssueType, generateMarkdownDocumentation, exportRulesAsJSON, };
+/**
+ * Parse a workflow_def object (from persona.workflow_def) into normalized nodes
+ * Supports multiple formats:
+ * - Ema format: { actions: [...], results: {...} }
+ * - Generic format: { nodes: [...] }
+ * - Object format: { nodeId: { action_name: ..., incoming_edges: [...] } }
+ */
+export function parseWorkflowDef(workflowDef) {
+    if (!workflowDef || typeof workflowDef !== "object") {
+        return [];
+    }
+    const nodes = [];
+    const def = workflowDef;
+    // Handle Ema format: { actions: [...] } - This is the primary format from Ema platform
+    if (Array.isArray(def.actions)) {
+        for (const action of def.actions) {
+            if (action && typeof action === "object") {
+                // Ema action structure:
+                // { name: "nodeId", action: { name: { namespaces: [...], name: "action_name" } }, inputs: {...}, displaySettings: {...} }
+                const actionName = action.name;
+                const actionDef = action.action;
+                const actionType = actionDef?.name;
+                const displaySettings = action.displaySettings;
+                // Extract action type name (handles nested { namespaces: [], name: "..." } format)
+                let actionTypeName;
+                if (typeof actionType === "string") {
+                    actionTypeName = actionType;
+                }
+                else if (actionType && typeof actionType === "object") {
+                    actionTypeName = actionType.name;
+                }
+                // Convert Ema inputs to incoming_edges format
+                const inputs = action.inputs;
+                const incomingEdges = [];
+                if (inputs) {
+                    for (const [inputName, inputValue] of Object.entries(inputs)) {
+                        if (inputValue && typeof inputValue === "object") {
+                            const inputObj = inputValue;
+                            // Handle actionOutput reference
+                            if (inputObj.actionOutput) {
+                                const actionOutput = inputObj.actionOutput;
+                                incomingEdges.push({
+                                    source_node_id: actionOutput.actionName,
+                                    source_output: actionOutput.output,
+                                    target_input: inputName,
+                                });
+                            }
+                            // Handle multiBinding (multiple inputs)
+                            if (inputObj.multiBinding) {
+                                const multiBinding = inputObj.multiBinding;
+                                const elements = multiBinding.elements;
+                                if (elements) {
+                                    for (const elem of elements) {
+                                        if (elem.namedBinding) {
+                                            const namedBinding = elem.namedBinding;
+                                            const value = namedBinding.value;
+                                            if (value?.actionOutput) {
+                                                const actionOutput = value.actionOutput;
+                                                incomingEdges.push({
+                                                    source_node_id: actionOutput.actionName,
+                                                    source_output: actionOutput.output,
+                                                    target_input: `${inputName}_${namedBinding.name}`,
+                                                });
+                                            }
+                                        }
+                                        else if (elem.actionOutput) {
+                                            const actionOutput = elem.actionOutput;
+                                            incomingEdges.push({
+                                                source_node_id: actionOutput.actionName,
+                                                source_output: actionOutput.output,
+                                                target_input: inputName,
+                                            });
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                nodes.push({
+                    id: actionName,
+                    action_name: actionTypeName,
+                    display_name: displaySettings?.displayName,
+                    incoming_edges: incomingEdges.length > 0 ? incomingEdges : undefined,
+                    parameters: action.inputs,
+                    runIf: action.runIf,
+                });
+            }
+        }
+        return nodes;
+    }
+    // Handle generic array of nodes format: { nodes: [...] }
+    if (Array.isArray(def.nodes)) {
+        for (const node of def.nodes) {
+            if (node && typeof node === "object") {
+                nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+    // Handle object format where keys are node IDs
+    for (const [key, value] of Object.entries(def)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const nodeObj = value;
+            // Check if this looks like a node (has action_name or incoming_edges)
+            if (nodeObj.action_name || nodeObj.incoming_edges || nodeObj.action) {
+                nodes.push({
+                    id: key,
+                    action_name: nodeObj.action_name ?? nodeObj.action?.name,
+                    display_name: nodeObj.display_name,
+                    incoming_edges: nodeObj.incoming_edges,
+                    parameters: nodeObj.parameters,
+                    runIf: nodeObj.runIf,
+                });
+            }
+        }
+    }
+    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)],
+                    reason: `Circular dependency detected: ${cycleNodes.join(" → ")}`,
+                });
+                break; // One cycle is enough to report
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Detect orphan nodes (not reachable from trigger)
+ */
+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
+    for (const node of nodes) {
+        if (!reachable.has(node.id) && node.id !== "WORKFLOW_OUTPUT") {
+            issues.push({
+                type: "orphan",
+                severity: "warning",
+                node: node.id,
+                reason: `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",
+            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",
+                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,
+                    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,
+                reason: `Categorizer "${categorizer.id}" has no outgoing category edges - routing won't work`,
+            });
+        }
+        // Check for Fallback - look for edges or enumType options
+        let hasFallback = false;
+        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 && outgoing.size > 0) {
+            issues.push({
+                type: "missing_fallback",
+                severity: "critical",
+                node: categorizer.id,
+                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
+        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;
+                        }
+                    }
+                }
+            }
+        }
+        if (!hasSuccess && !hasFailure) {
+            issues.push({
+                type: "incomplete_hitl",
+                severity: "critical",
+                node: hitl.id,
+                missing: "both success and failure paths",
+                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",
+                reason: `HITL node "${hitl.id}" missing success path`,
+            });
+        }
+        else if (!hasFailure) {
+            issues.push({
+                type: "incomplete_hitl",
+                severity: "critical",
+                node: hitl.id,
+                missing: "failure_path",
+                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;
+        if (node.incoming_edges) {
+            for (const edge of node.incoming_edges) {
+                const sourceOutput = edge.source_output?.toLowerCase() ?? "";
+                const targetInput = edge.target_input?.toLowerCase() ?? "";
+                // 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,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    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 = [];
+    // Text outputs that should NEVER be connected to email_to
+    const INVALID_EMAIL_SOURCES = [
+        "summarized_conversation",
+        "response_with_sources",
+        "search_results",
+        "combined_results",
+        "generated_content",
+        "text_with_sources",
+        "user_query",
+        "chat_conversation",
+    ];
+    // 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") ||
+        n.id?.toLowerCase().includes("email"));
+    // Find entity extraction nodes
+    const entityExtractionNodes = nodes.filter(n => n.action_name?.includes("entity_extraction") ||
+        n.id?.toLowerCase().includes("entity_extraction") ||
+        n.id?.toLowerCase().includes("extract"));
+    // 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) {
+        // Check 1: Is email_to connected to invalid text source?
+        if (emailNode.incoming_edges) {
+            for (const edge of emailNode.incoming_edges) {
+                const targetInput = edge.target_input?.toLowerCase() ?? "";
+                const sourceOutput = edge.source_output?.toLowerCase() ?? "";
+                // Check if this is the email_to input
+                if (targetInput.includes("email_to") || targetInput.includes("recipient") || targetInput.includes("to_address")) {
+                    // Check if source is a text output (INVALID for email addresses)
+                    const isInvalidSource = INVALID_EMAIL_SOURCES.some(invalid => sourceOutput.includes(invalid.toLowerCase().replace(/_/g, "")) ||
+                        sourceOutput.replace(/_/g, "").includes(invalid.toLowerCase().replace(/_/g, "")));
+                    if (isInvalidSource) {
+                        issues.push({
+                            type: "unsafe_email_recipient",
+                            severity: "critical",
+                            node: emailNode.id,
+                            source: edge.source_node_id,
+                            current: sourceOutput,
+                            recommended: "entity_extraction.email_address",
+                            reason: `Email recipient "${targetInput}" is connected to "${sourceOutput}" which is TEXT content, not an email address. ` +
+                                `This will cause emails to fail or send to invalid addresses. ` +
+                                `Use entity_extraction to extract the email address from conversation.`,
+                        });
+                    }
+                }
+            }
+        }
+        // Check 2: Is there entity_extraction upstream of this email node?
+        const hasEntityExtraction = entityExtractionNodes.length > 0;
+        if (!hasEntityExtraction) {
+            issues.push({
+                type: "missing_entity_extraction",
+                severity: "warning",
+                node: emailNode.id,
+                reason: `Email node "${emailNode.id}" has no entity_extraction upstream. ` +
+                    `Best practice: Use entity_extraction to extract recipient email, subject, and other required fields from conversation. ` +
+                    `This ensures structured data extraction instead of passing raw text.`,
+            });
+        }
+        // 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: "warning",
+                node: emailNode.id,
+                reason: `Email node "${emailNode.id}" has no HITL confirmation upstream. ` +
+                    `Emails are high-impact actions with external side effects. ` +
+                    `Best practice: Add HITL node before send_email to confirm recipient and content with user.`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Validate all edge connections for type compatibility
+ */
+export function validateWorkflowConnections(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const validations = [];
+    for (const node of nodes) {
+        if (!node.incoming_edges)
+            continue;
+        for (const edge of node.incoming_edges) {
+            const sourceNode = nodes.find(n => n.id === edge.source_node_id);
+            const validation = {
+                edge_id: `${edge.source_node_id}.${edge.source_output} → ${node.id}.${edge.target_input}`,
+                source_node: edge.source_node_id,
+                source_output: edge.source_output,
+                target_node: node.id,
+                target_input: edge.target_input,
+                compatible: true, // Default to true, validate below
+            };
+            // Determine types from output/input names
+            const sourceOutput = edge.source_output?.toLowerCase() ?? "";
+            const targetInput = edge.target_input?.toLowerCase() ?? "";
+            // Infer types from naming conventions
+            if (sourceOutput.includes("chat_conversation")) {
+                validation.source_type = "WELL_KNOWN_TYPE_CHAT_CONVERSATION";
+            }
+            else if (sourceOutput.includes("search_result")) {
+                validation.source_type = "WELL_KNOWN_TYPE_SEARCH_RESULT";
+            }
+            else if (sourceOutput.includes("document")) {
+                validation.source_type = "WELL_KNOWN_TYPE_DOCUMENT";
+            }
+            else {
+                validation.source_type = "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES";
+            }
+            // Check named_inputs FIRST - they accept ANY type
+            // This must come before "conversation" check since named_inputs_conversation contains both
+            if (targetInput.includes("named_input")) {
+                validation.target_type = "WELL_KNOWN_TYPE_ANY";
+            }
+            else if (targetInput.includes("conversation")) {
+                validation.target_type = "WELL_KNOWN_TYPE_CHAT_CONVERSATION";
+            }
+            else if (targetInput.includes("search_result")) {
+                validation.target_type = "WELL_KNOWN_TYPE_SEARCH_RESULT";
+            }
+            else if (targetInput.includes("document")) {
+                validation.target_type = "WELL_KNOWN_TYPE_DOCUMENT";
+            }
+            else {
+                validation.target_type = "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES";
+            }
+            // Check compatibility
+            if (validation.source_type && validation.target_type) {
+                const compat = checkTypeCompatibility(validation.source_type, validation.target_type);
+                if (compat) {
+                    validation.compatible = compat.compatible;
+                    validation.note = compat.note;
+                }
+                else if (validation.source_type !== validation.target_type &&
+                    validation.target_type !== "WELL_KNOWN_TYPE_ANY") {
+                    validation.compatible = false;
+                    validation.note = `Type mismatch: ${validation.source_type} → ${validation.target_type}`;
+                }
+            }
+            validations.push(validation);
+        }
+    }
+    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;
+}
+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),
+    ];
+    // 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;
+        }
+        if (fix) {
+            fixes.push(fix);
+        }
+    }
+    return fixes;
+}