@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/dist/mcp/knowledge.js

@@ -1,19 +1,14 @@
 /**
  * Ema Platform Knowledge Base
  *
- * This file contains TWO types of content:
+ * Curated knowledge constants, patterns, and helper functions.
+ * Types are in ./knowledge-types.ts
+ * Auto-generated catalogs are in ../sdk/generated/
  *
- * 1. AUTO-GENERATED (API Fallbacks)
- *    - AGENT_CATALOG, WIDGET_CATALOG, TYPE_COMPATIBILITY
- *    - Generated from source repos via scheduled workflows
- *    - Used as fallbacks when API unavailable
- *    - TODO: Move to src/sdk/generated/ and import here
- *
- * 2. CURATED KNOWLEDGE (Human-Maintained)
- *    - PLATFORM_CONCEPTS, WORKFLOW_PATTERNS, GUIDANCE_TOPICS, etc.
- *    - Source repos are INPUT, not law
- *    - Optimized for customer-facing MCP users
- *    - Updated via knowledge scanning workflow + human review
+ * Content:
+ * - PLATFORM_CONCEPTS, WORKFLOW_PATTERNS, GUIDANCE_TOPICS, etc. (human-maintained)
+ * - Helper functions (getAgentsByCategory, suggestAgentsForUseCase, etc.)
+ * - Workflow analysis functions (parseWorkflowDef, validateWorkflowConnections)
  *
  * Input Sources (for curated content):
  * - ema-repos/ema/docs/ - Platform documentation
@@ -24,6 +19,13 @@
  * See: .context/core/guides/source-repos.md for full architecture
  */
 // ─────────────────────────────────────────────────────────────────────────────
+// Re-exports: Auto-Generated Catalogs (from sdk/generated/)
+// ─────────────────────────────────────────────────────────────────────────────
+export { AGENT_CATALOG } from "../sdk/generated/agent-catalog.js";
+import { AGENT_CATALOG } from "../sdk/generated/agent-catalog.js";
+export { WIDGET_CATALOG } from "../sdk/generated/widget-catalog.js";
+import { WIDGET_CATALOG } from "../sdk/generated/widget-catalog.js";
+// ─────────────────────────────────────────────────────────────────────────────
 // Platform Concepts (from Ema User Guide)
 // ─────────────────────────────────────────────────────────────────────────────
 export const PLATFORM_CONCEPTS = [
@@ -66,8 +68,8 @@ export const PLATFORM_CONCEPTS = [
         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.",
+        relatedTerms: ["entity_extraction_with_documents", "send_email_agent"],
+        commonConfusions: "HITL is ONLY supported on entity_extraction_with_documents and send_email_agent. general_hitl is NOT deployable. external_action_caller does NOT support HITL.",
     },
     {
         term: "Connector",
@@ -125,678 +127,6 @@ then route to "update ticket" instead of "create ticket"`,
         },
     },
 };
-// ─────────────────────────────────────────────────────────────────────────────
-// 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)",
-            "Handler nodes use runIf conditions to route by category",
-            "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). Use version v2 (search/v2) which requires datastore_configs input. search/v0 is deprecated.",
-        inputs: [
-            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Search query" },
-            { name: "datastore_configs", type: "WELL_KNOWN_TYPE_ANY", required: false, description: "Datastore configuration (v2). Wired from persona widget config." },
-        ],
-        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. Always use search/v2 (not deprecated search/v0).",
-        whenNotToUse: "For real-time web content — use live_web_search or ai_web_search instead",
-        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_TEXT_WITH_SOURCES", required: true, description: "Recipient email address - use fixed_response with {{email}} template" },
-            { 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: [
-            "email_to requires TEXT_WITH_SOURCES type - use fixed_response with {{email}} template populated from entity_extraction",
-            "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 or search_results directly to email_to",
-        ],
-        example: "entity_extraction → fixed_response('{{email}}') → send_email.email_to (CORRECT pattern)",
-    },
-    // 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. Rules are configured through the node's settings panel (UI), not via workflow_def inputs. Each rule has a name and description. Output mode is Pass/Fail per rule.",
-        inputs: [
-            { name: "primary_docs", type: "WELL_KNOWN_TYPE_DOCUMENT", required: true, description: "Primary documents to validate against" },
-            { name: "map_of_extracted_columns", type: "WELL_KNOWN_TYPE_ANY", required: true, description: "Extracted data from entity_extraction to validate" },
-        ],
-        outputs: [
-            { name: "ruleset_output", type: "WELL_KNOWN_TYPE_ANY", description: "Pass/Fail results per rule with explanations" },
-        ],
-        whenToUse: "For compliance checks, business rule validation, threshold checking. Rules (e.g., 'Required Fields', 'Data Variance') are defined in the node's UI settings — the LLM only needs to wire inputs/outputs correctly.",
-    },
-    // Human Collaboration
-    // NOTE: general_hitl as a standalone workflow node is NOT currently recommended.
-    // HITL is implemented as a FLAG on specific agents (e.g., send_email_agent, external_action_caller).
-    // Kept here for reference when analyzing existing workflows that may use it.
-    {
-        actionName: "general_hitl",
-        displayName: "Human Collaboration (NOT RECOMMENDED — use agent flags instead)",
-        category: "collaboration",
-        description: "DEPRECATED for new workflows. HITL approval is now a flag on specific agents (send_email_agent, external_action_caller), not a separate workflow node. Do NOT add general_hitl nodes to new workflows.",
-        inputs: [
-            { name: "query", type: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", required: true, description: "Context for review" },
-        ],
-        outputs: [
-            { 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: [
-            "DO NOT use general_hitl in new workflows — use HITL flags on the agent that needs approval instead",
-            "If user asks for approval: enable the HITL flag on the relevant agent (e.g., send_email_agent, external_action_caller)",
-            "Existing workflows with general_hitl nodes will still function — no migration required",
-            "If you encounter general_hitl in an existing workflow: leave it, but don't add new ones",
-        ],
-        whenToUse: "DO NOT USE for new workflows. HITL is a flag on agents, not a standalone node.",
-        example: "For approval: enable HITL flag on send_email_agent or external_action_caller",
-    },
-    // 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
-// ─────────────────────────────────────────────────────────────────────────────
-// ═══════════════════════════════════════════════════════════════════════════════════
-// WIDGET_CATALOG (NO API ALTERNATIVE - Intentionally Static)
-// ═══════════════════════════════════════════════════════════════════════════════════
-// 
-// WHY STATIC: There is no API endpoint to list widget definitions. Widget metadata
-// lives in persona template YAML files and is not exposed via the API.
-//
-// RUNTIME ALTERNATIVE: For a specific persona, fetch widgets dynamically via:
-//   persona(id="...", include_workflow=true) → proto_config.widgets[].name
-//
-// SOURCE: ema-repos/ema/ema_backend/db/system_values/persona_templates/prod/*.yaml
-// SYNC: Manual - run knowledge scan workflow to detect template changes
-// 
-// TECHNICAL NOTES:
-// - Widget 'id' is the WidgetType enum value from protos
-// - Widget 'name' is assigned per-template (e.g., "upload", "upload1", "upload2")
-// - Proto 'case' values represent TYPE discriminators, not widget names
-// 
-// See .context/core/guides/source-repos.md for full sync instructions
-// ═══════════════════════════════════════════════════════════════════════════════════
-export const WIDGET_CATALOG = [
-    // ═══════════════════════════════════════════════════════════════════════════
-    // Voice AI Widgets
-    // ═══════════════════════════════════════════════════════════════════════════
-    // SOURCE: voicebot_ai_employee.yaml
-    // LAST VERIFIED: 2026-01-27
-    { id: 38, name: "voiceSettings", description: "Language hints, voice model selection (title: 'Voice and language')", requiredFor: ["voice"], fields: ["languageHints", "voiceModel"] },
-    { id: 39, name: "conversationSettings", description: "Identity, purpose, action instructions, hangup rules (title: 'Conversational behavior')", requiredFor: ["voice"], fields: ["welcomeMessage", "identityAndPurpose", "takeActionInstructions", "hangupInstructions", "transferCallInstructions", "speechCharacteristics", "systemPrompt", "formFillingInstructions", "waitMessage"] },
-    { id: 43, name: "vadSettings", description: "Voice activity detection settings", requiredFor: ["voice"], fields: ["turnTimeout", "silenceEndCallTimeout", "maxConversationDuration"] },
-    { id: 42, name: "dataStorageSettings", description: "Audio/transcript recording settings", requiredFor: ["voice"], fields: ["storeAudioRecording", "storeTranscripts", "storeAgentTranscript"] },
-    { id: 41, name: "callSettings", description: "Call forwarding, spam prevention settings", requiredFor: ["voice"], fields: ["enableCallForwarding", "callForwardingNumber", "enableSpamCallPrevention"] },
-    { id: 44, name: "voicebotPhoneNumber", description: "Phone number configuration (title: 'Phone numbers')", requiredFor: ["voice"], fields: ["phoneNumber"] },
-    { id: 40, name: "voicebotFeedbackCollection", description: "Post-call feedback collection (title: 'Feedback collection')", requiredFor: ["voice"], fields: [] },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // Chat AI Widgets
-    // ═══════════════════════════════════════════════════════════════════════════
-    // SOURCE: TBD - need to verify from chat template
-    { id: 28, name: "chatbotSdkConfig", description: "Chat widget configuration and theming", requiredFor: ["chat"], fields: ["theme", "position", "initialMessage"] },
-    { id: 33, name: "feedbackMessage", description: "Feedback collection settings", requiredFor: ["chat"], fields: ["enabled", "prompt"] },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // Document Generation Widgets
-    // ═══════════════════════════════════════════════════════════════════════════
-    // SOURCE: ema-repos/ema/ema_backend/db/system_values/persona_templates/prod/document_proposal_manager.yaml
-    // NOTE: Widget names are defined per-template. These are from Document Proposal Manager.
-    //       To sync: see .context/core/guides/source-repos.md
-    // LAST VERIFIED: 2026-01-27 from document_proposal_manager.yaml
-    { id: 3, name: "upload", description: "Content Repository - gold standard company docs (title: 'Content Repository')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
-    { id: 3, name: "upload1", description: "Service Line Documents - business unit specific content (title: 'Service Line Documents')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
-    { id: 3, name: "upload2", description: "Style Guide - formatting and tone guide (title: 'Style Guide')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
-    { id: 29, name: "fileTagging0", description: "File tagging configuration (title: 'Set Tags')", requiredFor: ["document"], fields: ["tagTypes", "fileTagMappings"] },
-    { id: 5, name: "answerFormat0", description: "Proposal instructions - format, tone, language (title: 'Proposal Instructions')", requiredFor: ["document"], fields: ["textValue"] },
-    { id: 16, name: "sectionConfigWidget", description: "Section categories with instructions (title: 'Section Categories')", requiredFor: ["document"], fields: ["sections"] },
-    // ═══════════════════════════════════════════════════════════════════════════
-    // Common Widgets (all types)
-    // ═══════════════════════════════════════════════════════════════════════════
-    // These appear across multiple template types
-    { id: 3, name: "fileUpload", description: "Default document upload (KB files, title: 'Data sources')", requiredFor: ["voice", "chat", "dashboard"], fields: ["allowedTypes", "maxSize"], uploadTarget: true },
-    { id: 6, name: "fusionModel", description: "EmaFusion model selection (GPT-4, Claude, etc., title: 'EmaFusion™ model')", requiredFor: ["voice", "chat", "dashboard", "document"], fields: ["allModels", "selectedModels"] },
-    { id: 8, name: "dataProtection", description: "PII redaction settings", requiredFor: ["voice", "chat", "dashboard", "document"], fields: ["protectedClasses"] },
-    { id: 9, name: "copyrightCheck", description: "Copyright infringement checker (title: 'Copyright Checker')", requiredFor: ["document"], fields: [] },
-];
 // Project type mapping
 export const PROJECT_TYPES = {
     voice: 5,
@@ -813,7 +143,6 @@ export const PROJECT_TYPES = {
 // SYNC: TODO - Add to catalog-sync.yml workflow for automatic updates
 //
 // Other type compatibility definitions serve different purposes:
-// - INTENT_TYPE_ROUTING (workflow-intent.ts) - routing logic during intent processing
 // - SCHEMA_TYPE_COMPATIBILITY (action-schema-parser.ts) - input name matching for validation
 //
 // See .context/core/guides/source-repos.md for full architecture
@@ -829,7 +158,7 @@ export const TYPE_COMPATIBILITY = [
     { 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_TEXT_WITH_SOURCES", compatible: false, note: "Use respond_for_external_actions (or call_llm.named_inputs) 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 },
@@ -846,13 +175,14 @@ 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"],
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
         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",
+            "search.search_results → respond_for_external_actions.external_action_result",
+            "chat_trigger.user_query → respond_for_external_actions.query",
+            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
+            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
         ],
         useCase: "FAQ bot, documentation assistant, policy lookup",
     },
@@ -874,22 +204,25 @@ export const WORKFLOW_PATTERNS = [
             "Missing Fallback category",
             "Categories without outgoing edges",
             "Not all paths leading to WORKFLOW_OUTPUT",
+            "Only one gated respond node wired to WORKFLOW_OUTPUT while others are silently lost",
+            "Duplicate identical call_llm nodes differing only by trigger_when — consolidate into one with category as named_input",
         ],
     },
     {
         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"],
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "live_web_search", "combine_search_results", "respond_for_external_actions"],
         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",
+            "combine_search_results.combined_results → respond_for_external_actions.external_action_result",
+            "chat_trigger.user_query → respond_for_external_actions.query",
+            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
+            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
         ],
         useCase: "Research assistant needing both internal docs and current web info",
     },
@@ -915,32 +248,35 @@ export const WORKFLOW_PATTERNS = [
     {
         name: "hitl-approval",
         personaType: "chat",
-        description: "Human-in-the-loop approval — use HITL flags on agents, NOT a standalone general_hitl node",
-        nodes: ["chat_trigger", "external_action_caller (with HITL flag)", "respond_for_external_actions"],
+        description: "Human-in-the-loop approval — enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL)",
+        nodes: ["chat_trigger", "send_email_agent (with HITL flag)", "respond_for_external_actions"],
         connections: [
             "chat_trigger.user_query → external_action_caller.query",
             "chat_trigger.chat_conversation → external_action_caller.conversation",
             "external_action_caller.tool_execution_result → respond_for_external_actions.external_action_result",
             "chat_trigger.user_query → respond_for_external_actions.query",
+            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
             "respond_for_external_actions.response → WORKFLOW_OUTPUT",
         ],
-        useCase: "High-value transactions, sensitive operations — enable HITL flag on the agent",
+        useCase: "High-value transactions, sensitive operations — enable HITL flag on send_email_agent or entity_extraction_with_documents",
         antiPatterns: [
-            "Adding general_hitl as a standalone node (use agent HITL flags instead)",
+            "Adding general_hitl as a standalone node (it is NOT deployable)",
             "Not wiring conversation context to response node",
         ],
     },
     {
         name: "document-processing",
         personaType: "dashboard",
-        description: "Document upload → extraction → validation → response",
+        description: "Document upload → extraction → validation → analysis (results as dashboard columns)",
         nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_with_documents", "call_llm"],
         connections: [
-            "document_trigger.user_query → entity_extraction_with_documents.documents",
+            "workflowInput.document-mmf2 → 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",
+            "workflowInput.document-mmf2 → 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",
+            "entity_extraction_node.extraction_columns → results (dot-notation key)",
+            "rule_validation_node.ruleset_output → results (dot-notation key)",
+            "call_llm.llm_output → results (dot-notation key)",
         ],
         useCase: "Invoice processing, contract analysis, compliance checking",
     },
@@ -950,12 +286,13 @@ export const WORKFLOW_PATTERNS = [
         description: "Document upload → extraction → email notification (with intermediary for type conversion)",
         nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "fixed_response", "send_email_agent", "call_llm"],
         connections: [
-            "document_trigger.user_query → entity_extraction_with_documents.documents",
+            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
             "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
             "json_mapper.output_json → fixed_response.named_inputs_Extracted_Data (template: '{{to}}', '{{subject}}', etc.)",
             "fixed_response.response → send_email_agent.email_to (one fixed_response per email field)",
             "send_email_agent.confirmation → call_llm.named_inputs_Email_Result",
-            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
+            "entity_extraction_node.extraction_columns → results (dot-notation key)",
+            "call_llm.llm_output → results (dot-notation key)",
         ],
         useCase: "Invoice receipt notification, contract alerts, document-triggered emails",
         antiPatterns: [
@@ -968,17 +305,60 @@ export const WORKFLOW_PATTERNS = [
         name: "guardrails-pattern",
         personaType: "chat",
         description: "Response generation with validation guardrails",
-        nodes: ["chat_trigger", "search", "respond_with_sources", "response_validator", "abstain_action"],
+        nodes: ["chat_trigger", "search", "respond_for_external_actions", "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",
+            "search.search_results → respond_for_external_actions.external_action_result",
+            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
+            "respond_for_external_actions.response → 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",
     },
+    {
+        name: "externalized-instructions",
+        personaType: "chat",
+        description: "Dynamic instructions fetched from knowledge base instead of hardcoded in node prompts. Upload instruction documents (policies, tone guides, procedures) to KB and let search retrieve them at runtime.",
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
+        connections: [
+            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
+            "conversation_to_search_query.summarized_conversation → search.query",
+            "search.search_results → respond_for_external_actions.external_action_result (instructions + knowledge combined)",
+            "chat_trigger.user_query → respond_for_external_actions.query",
+            "chat_trigger.chat_conversation → respond_for_external_actions.conversation",
+            "respond_for_external_actions.response → WORKFLOW_OUTPUT",
+        ],
+        useCase: "When instructions change frequently, when multiple teams maintain different policies, when A/B testing response styles",
+        antiPatterns: [
+            "Hardcoding all instructions in node prompt (requires workflow redeploy to change behavior)",
+            "Not connecting search results to extraction nodes that also need instructions",
+            "Mixing instruction documents with knowledge documents without clear separation",
+        ],
+    },
+    {
+        name: "consolidated-intent-routing",
+        personaType: "chat",
+        description: "Single respond node handles all intents by receiving the category as a named_input. Reduces duplication vs. having separate respond nodes per intent.",
+        nodes: ["chat_trigger", "chat_categorizer", "search", "call_llm", "fixed_response"],
+        connections: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "chat_trigger.user_query → search.query (always runs, not gated)",
+            "chat_categorizer.category → call_llm.named_inputs_Intent",
+            "search.search_results → call_llm.named_inputs_Search_Results",
+            "chat_trigger.chat_conversation → call_llm.named_inputs_Conversation",
+            "chat_trigger.user_query → call_llm.query",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT (runIf: category != Fallback)",
+            "fixed_response.response → WORKFLOW_OUTPUT (runIf: category == Fallback)",
+        ],
+        useCase: "Multi-intent assistant where all intents share similar response style, search sources, and safety constraints",
+        antiPatterns: [
+            "Using this when intents need different tools or actions (use separate nodes instead)",
+            "Forgetting to pass the category as named_input (LLM won't know which intent to address)",
+            "Not gating fallback separately (fixed_response should handle fallback, not the LLM)",
+        ],
+    },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 // Qualifying Questions
@@ -996,7 +376,7 @@ export const QUALIFYING_QUESTIONS = [
     { 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: "Enable HITL flag on the relevant agent (send_email_agent, external_action_caller)", required: false },
+    { category: "Actions", question: "Which actions require human approval?", whyItMatters: "Enable HITL flag on the relevant agent (only entity_extraction_with_documents and send_email_agent support HITL)", 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 },
@@ -1039,9 +419,9 @@ export const COMMON_MISTAKES = [
     { 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" },
     { mistake: "Using workflow_def instead of workflow in updates", problem: "API accepts request but changes silently don't persist", solution: "Use 'workflow' field (not 'workflow_def') in updateAiEmployee(). GET returns workflow_def, UPDATE expects workflow." },
-    { mistake: "Chat workflow without chat-aware response node", problem: "Duplicate/repetitive responses — LLM re-asks questions already answered, loses multi-turn context", solution: "Use respond_with_sources (for search) or respond_for_external_actions (for tools) instead of generic call_llm. If using call_llm, wire chat_conversation into named_inputs." },
+    { mistake: "Chat workflow without chat-aware response node", problem: "Duplicate/repetitive responses — LLM re-asks questions already answered, loses multi-turn context", solution: "Use respond_for_external_actions (for search results or tool results) instead of generic call_llm. If using call_llm, wire chat_conversation into named_inputs." },
     { mistake: "Wiring entity_extraction directly to send_email inputs", problem: "Type mismatch — entity_extraction outputs ANY type, email inputs need TEXT_WITH_SOURCES. Results in corrupted email addresses or deploy errors.", solution: "Use intermediary: entity_extraction → json_mapper → fixed_response({{field}}) → send_email. Or use custom_agent with output_fields=[To,Subject,Body]." },
-    { mistake: "Adding general_hitl as a standalone workflow node", problem: "general_hitl as a standalone node is not currently recommended. It may have backend issues and adds workflow complexity.", solution: "Enable the HITL flag on the agent that performs the action (e.g., send_email_agent, external_action_caller). The agent handles approval flow internally. Revisit if general_hitl is re-enabled as standalone." },
+    { mistake: "Adding general_hitl as a standalone workflow node", problem: "general_hitl is NOT deployable — it appears in catalogs but cannot be deployed. Deploying it will fail.", solution: "Enable the HITL flag on the agent that performs the action. Only entity_extraction_with_documents and send_email_agent support HITL (disable_human_interaction: false). external_action_caller does NOT support HITL." },
 ];
 export const DEBUG_CHECKLIST = [
     { step: 1, action: "Check Status", description: "Is the AI Employee active/ready?", apiField: "status" },
@@ -1092,13 +472,13 @@ export const GUIDANCE_TOPICS = {
         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 → respond_for_external_actions.external_action_result (SEARCH_RESULT → ANY)",
             "❌ 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",
+            "SEARCH_RESULT compatible with respond_for_external_actions.external_action_result or named_inputs (respond_with_sources/v0 is deprecated)",
             "call_llm.named_inputs accepts ANY type",
             "Use conversation_to_search_query to convert CHAT_CONVERSATION → TEXT_WITH_SOURCES",
         ],
@@ -1117,27 +497,26 @@ export const GUIDANCE_TOPICS = {
     },
     "hitl-patterns": {
         title: "Human-in-the-Loop Patterns",
-        content: "HITL is implemented as a FLAG on specific agents, NOT as a standalone general_hitl workflow node. " +
-            "When the user requests approval for an action, enable the HITL flag on the relevant agent " +
-            "(e.g., send_email_agent, external_action_caller). The platform handles the approval UI and routing automatically. " +
-            "Do NOT add general_hitl nodes to new workflows.\n\n" +
+        content: "HITL is implemented as a FLAG on specific agents — ONLY entity_extraction_with_documents and send_email_agent support it. " +
+            "external_action_caller does NOT support HITL. general_hitl is NOT deployable (appears in catalogs but cannot be deployed). " +
+            "When the user requests approval, enable the HITL flag on send_email_agent or entity_extraction_with_documents. " +
+            "The platform handles the approval UI and routing automatically.\n\n" +
             "JSON format: Set `disable_human_interaction: false` (or omit — default is false = HITL enabled) on the action node " +
             "in workflow_def.actions[]. To DISABLE HITL, set `disable_human_interaction: true`. " +
             "Note the counter-intuitive naming: false = HITL ON, true = HITL OFF.",
         status: "verified",
         examples: [
             "User wants email approval → enable HITL flag on send_email_agent",
-            "User wants action approval → enable HITL flag on external_action_caller",
-            "Existing workflow has general_hitl → leave it (still functions), but don't add new ones",
+            "User wants extraction review → enable HITL flag on entity_extraction_with_documents",
             "JSON: { name: 'send_email', action: { name: 'send_email_agent' }, disable_human_interaction: false, ... } → HITL ENABLED",
             "JSON: { name: 'respond', action: { name: 'call_llm' }, disable_human_interaction: true, ... } → HITL DISABLED (auto-proceed)",
         ],
         criticalRules: [
-            "DO NOT use general_hitl as a standalone node in new workflows",
-            "HITL = flag on the agent that needs approval (send_email_agent, external_action_caller)",
+            "general_hitl is NOT deployable — do NOT add it to any workflow",
+            "HITL is ONLY supported on: entity_extraction_with_documents and send_email_agent",
+            "external_action_caller does NOT support HITL despite appearing in older guidance",
             "JSON field: `disable_human_interaction` (boolean) on the action node — false=HITL on, true=HITL off",
-            "If you encounter existing general_hitl nodes: they still work, no migration needed",
-            "When user says 'with approval': set disable_human_interaction: false on the relevant action node",
+            "When user says 'with approval': set disable_human_interaction: false on send_email_agent or entity_extraction_with_documents",
         ],
     },
     "hitl-policy": {
@@ -1163,7 +542,7 @@ export const GUIDANCE_TOPICS = {
         content: "For comprehensive answers, combine local search with web search. Use combine_search_results to merge and deduplicate.",
         status: "verified",
         examples: [
-            "search (local) + live_web_search → combine_search_results → respond_with_sources",
+            "search (local) + live_web_search → combine_search_results → respond_for_external_actions",
             "For cross-document linking: entity_extraction → knowledge_graph_generator → document_synthesis",
         ],
         criticalRules: [
@@ -1438,7 +817,7 @@ export const GUIDANCE_TOPICS = {
 - NO → Use transform node (json_mapper, fixed_response)
 
 ### Q3: What KIND of generation?
-- Simple Q&A with citations → respond_with_sources
+- Simple Q&A with citations → respond_for_external_actions
 - Custom generation → call_llm
 - Complex multi-step reasoning → custom_agent
 - Search + synthesize in one → document_synthesis
@@ -1454,23 +833,23 @@ export const GUIDANCE_TOPICS = {
 | fixed_response | 0 | <50ms | Static content, config, templates |
 | json_mapper | 0 | <100ms | Transform JSON without reasoning |
 | entity_extraction | 1 | 1-2s | Extract structured data |
-| respond_with_sources | 1 | 2-4s | Simple search + response |
+| respond_for_external_actions | 1 | 2-4s | Search + response (conversation-aware) |
 | call_llm | 1 | 2-4s | Custom generation |
 | custom_agent | 1-3 | 3-8s | Complex reasoning |
 | document_synthesis | 2-5 | 5-15s | Multi-search + synthesis |`,
         examples: [
             "✅ Static template → fixed_response (0 LLM calls)",
             "✅ Extract client_name, email → entity_extraction (1 LLM call, typed output)",
-            "✅ Simple KB Q&A → respond_with_sources (1 LLM call)",
+            "✅ Simple KB Q&A → respond_for_external_actions (1 LLM call, conversation-aware)",
             "✅ Custom email generation → call_llm with search results in named_inputs",
             "❌ Using call_llm to extract JSON → Use entity_extraction instead",
-            "❌ Using document_synthesis for simple Q&A → Use respond_with_sources",
+            "❌ Using document_synthesis for simple Q&A → Use respond_for_external_actions",
             "❌ Using custom_agent for static response → Use fixed_response",
         ],
         criticalRules: [
             "NEVER use LLM for transforms that json_mapper can do",
             "NEVER use call_llm for structured extraction - use entity_extraction",
-            "NEVER use document_synthesis when respond_with_sources suffices",
+            "NEVER use document_synthesis when respond_for_external_actions suffices",
             "ALWAYS use fixed_response for static content (templates, config, help text)",
             "Use entity_extraction for typed, reliable structured data",
             "Use call_llm when you need custom instructions or reasoning",
@@ -1483,9 +862,9 @@ export const GUIDANCE_TOPICS = {
         status: "verified",
         content: `Different LLM nodes serve different purposes. Choose based on your needs:
 
-## respond_with_sources
-- **Best for**: Simple Q&A with KB citations
-- **Input**: Search results (SEARCH_RESULT type)
+## respond_for_external_actions (replaces deprecated respond_with_sources)
+- **Best for**: Simple Q&A with KB citations, tool result explanation
+- **Input**: Search results or tool results via external_action_result
 - **Output**: Response with source citations
 - **When**: User asks question, you search KB, return answer
 - **NOT for**: Custom generation, complex reasoning
@@ -1495,7 +874,7 @@ export const GUIDANCE_TOPICS = {
 - **Input**: Query + optional search/context via named_inputs
 - **Output**: Generated text
 - **When**: Need custom prompts, specific format, controlled generation
-- **NOT for**: Simple Q&A (use respond_with_sources)
+- **NOT for**: Simple Q&A (use respond_for_external_actions)
 
 ## custom_agent
 - **Best for**: Complex tasks requiring role + instructions
@@ -1512,17 +891,17 @@ export const GUIDANCE_TOPICS = {
 - **When**: Need to search → plan → search again → synthesize
 - **NOT for**: Simple KB lookup (too heavy)`,
         examples: [
-            "User asks 'What is our refund policy?' → respond_with_sources",
+            "User asks 'What is our refund policy?' → respond_for_external_actions",
             "Need to generate email with specific template → call_llm",
             "Need to analyze portfolio and recommend actions → custom_agent",
             "Need to research topic across multiple sources → document_synthesis",
         ],
         criticalRules: [
-            "respond_with_sources: 1 LLM call, simple Q&A, requires SEARCH_RESULT input",
+            "respond_for_external_actions: 1 LLM call, simple Q&A or tool results, conversation-aware",
             "call_llm: 1 LLM call, custom generation, accepts named_inputs",
             "custom_agent: 1-3 LLM calls, complex reasoning, has role context",
             "document_synthesis: 2-5 LLM calls, heavy, only for research tasks",
-            "Default to respond_with_sources for KB Q&A",
+            "Default to respond_for_external_actions for KB Q&A",
             "Upgrade to call_llm when you need custom instructions",
             "Upgrade to custom_agent for complex reasoning",
             "Use document_synthesis sparingly (latency expensive)",
@@ -1680,105 +1059,38 @@ export function getConceptByTerm(term) {
         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);
+    const queryTokens = useCase
+        .toLowerCase()
+        .split(/[\s,;:.\-/|]+/)
+        .filter(t => t.length > 1);
+    if (queryTokens.length === 0)
+        return [];
+    const scored = AGENT_CATALOG.map(agent => {
+        let score = 0;
+        const searchableFields = [
+            agent.actionName,
+            agent.displayName,
+            agent.category,
+            agent.description,
+            agent.whenToUse,
+            agent.whenNotToUse ?? "",
+            ...agent.inputs.map(i => `${i.name} ${i.type}`),
+            ...agent.outputs.map(o => `${o.name} ${o.type}`),
+        ].map(f => f.toLowerCase());
+        for (const token of queryTokens) {
+            for (const field of searchableFields) {
+                if (field.includes(token)) {
+                    score++;
+                    break;
+                }
             }
         }
-    };
-    // 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 — general_hitl is NOT recommended as a standalone node.
-    // HITL is a flag on agents. Don't suggest adding general_hitl nodes.
-    // If user wants approval, the agent should enable HITL flags on relevant agents.
-    // 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,
-    };
+        return { agent, score };
+    });
+    return scored
+        .filter(s => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map(s => s.agent);
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Workflow Analysis Functions