@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

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,
@@ -805,38 +135,35 @@ export const PROJECT_TYPES = {
     document: 3,
 };
 // ─────────────────────────────────────────────────────────────────────────────
-// Type Compatibility (CANONICAL SOURCE)
+// Type Compatibility (AUTO-GENERATED + CURATED OVERRIDES)
 // ─────────────────────────────────────────────────────────────────────────────
-// This is the canonical, user-facing documentation of type compatibility.
+// Base rules (reflexive, ANY compatibility) are auto-generated from proto.
+// Curated overrides document specific incompatibilities and conversion notes.
 //
-// SOURCE: ema-repos/protos/service/workflows/v1/well_known.proto
-// SYNC: TODO - Add to catalog-sync.yml workflow for automatic updates
+// Regenerate base: npm run generate:type-compatibility
+// Source: protos/service/workflows/v1/values.proto → values_pb.ts → well-known-types.ts
 //
 // 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
 // ─────────────────────────────────────────────────────────────────────────────
-export const TYPE_COMPATIBILITY = [
-    // Chat conversation compatibility
-    { sourceType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: true },
+import { BASE_TYPE_COMPATIBILITY } from "../sdk/generated/well-known-types.js";
+const CURATED_OVERRIDES = [
+    // Chat conversation → other types
     { 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_CHAT_CONVERSATION", targetType: "WELL_KNOWN_TYPE_SEARCH_RESULT", compatible: false, note: "Search takes query string, not conversation" },
+    // Text with sources → other types
     { 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_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 },
-    { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_ANY", compatible: true },
+    { sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", targetType: "WELL_KNOWN_TYPE_SEARCH_RESULT", compatible: false, note: "Text is not a search result" },
+    // Search result → other types
+    { 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" },
+    { sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: false, note: "Search result is not a conversation" },
+    // Document → other types
     { 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 },
+    { sourceType: "WELL_KNOWN_TYPE_DOCUMENT", targetType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION", compatible: false, note: "Document is not a conversation" },
+];
+export const TYPE_COMPATIBILITY = [
+    ...BASE_TYPE_COMPATIBILITY,
+    ...CURATED_OVERRIDES,
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 // Workflow Patterns
@@ -919,8 +246,8 @@ 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",
@@ -929,9 +256,9 @@ export const WORKFLOW_PATTERNS = [
             "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",
         ],
     },
@@ -1047,7 +374,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 },
@@ -1092,7 +419,7 @@ export const COMMON_MISTAKES = [
     { 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_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" },
@@ -1107,597 +434,9 @@ export const DEBUG_CHECKLIST = [
     { step: 10, action: "Validate Types", description: "Are all connections type-compatible?" },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
-// Guidance Topics
+// Re-exports: Guidance Topics (from knowledge-guidance-topics.ts)
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Guidance topics for workflow building.
- *
- * status field indicates confidence level:
- * - "verified": Based on platform mechanics, tested behavior
- * - "experimental": Best practice suggestions, needs validation
- *
- * Experimental guidance uses softer language (consider, may, typically)
- * to avoid biasing LLMs toward unverified patterns.
- */
-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.",
-        status: "verified",
-        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.",
-        status: "verified",
-        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_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 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",
-        ],
-    },
-    "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.",
-        status: "verified",
-        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 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" +
-            "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",
-            "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)",
-            "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",
-        ],
-    },
-    "hitl-policy": {
-        title: "HITL Policy (When to Use)",
-        content: "HITL is OPTIONAL. Default is auto-proceed without approval gates. Only add HITL when explicitly requested by user.",
-        status: "verified",
-        examples: [
-            "User says 'add email' → Ask about recipient/trigger, NOT about approval",
-            "User says 'with approval' or 'confirm before sending' → Add HITL",
-            "User says 'auto' or 'directly' → Skip HITL discussion entirely",
-        ],
-        criticalRules: [
-            "DEFAULT: Proceed WITHOUT approval gate unless explicitly requested",
-            "Add HITL only when: user says 'confirm before', 'approval required', 'human review'",
-            "Skip HITL when: user says 'auto', 'directly', 'no approval', or specifies direct flow",
-            "If ambiguous: ASK 'Should [action] require approval, or auto-proceed?'",
-            "NEVER auto-add HITL based on action type alone",
-            "INFO severity issues = 'Consider this', not 'Must fix'",
-        ],
-    },
-    "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.",
-        status: "verified",
-        examples: [
-            "search (local) + live_web_search → combine_search_results → respond_for_external_actions",
-            "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.",
-        status: "verified",
-        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.",
-        status: "verified",
-        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.",
-        status: "verified",
-        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.",
-        status: "verified",
-        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.",
-        status: "verified",
-        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",
-        ],
-    },
-    "workflow-structure": {
-        title: "Workflow Structure Best Practices",
-        content: "Suggested pattern: Conversation Summarizer → Entity Extractor → JSON Mapper → Downstream Consumers. Extract once, pass outputs onward. This may help ensure client context is available before knowledge base searches.",
-        status: "experimental",
-        examples: [
-            "Consider: trigger → summarizer → extractor → json_mapper → [search, routing, responses]",
-            "Consider: Single extraction node feeds JSON mapper, which distributes to multiple consumers",
-            "May cause issues: Multiple extraction nodes extracting same data from same input",
-            "May cause issues: KB search before extraction (can't use client context)",
-        ],
-        criticalRules: [
-            "Consider extracting entities once, then passing structured data via JSON mapper",
-            "Extraction before KB search may help if search needs client context",
-            "JSON mapper output (output_json) can feed downstream nodes that need structured context",
-            "Duplicate extraction nodes may cause redundancy - consider single extractor pattern",
-        ],
-    },
-    "search-node-timing": {
-        title: "Knowledge Base Search Node Timing and Usage",
-        content: "Search nodes execute based on their input connections. Early search (after summarizer) typically sees only conversation summary. Late search (after JSON mapper) may be able to use client context. Consider multiple search nodes if you need both generic and context-aware retrieval.",
-        status: "experimental",
-        examples: [
-            "Early search: trigger → summarizer → knowledge_search_1 (typically sees only summary)",
-            "Late search: trigger → summarizer → extractor → json_mapper → knowledge_search_2 (may access client context)",
-            "Template search: json_mapper → fixed_response (query builder) → template_search (may use client context)",
-            "Dual search pattern: Early generic search + late context-aware search (consider for comprehensive results)",
-        ],
-        criticalRules: [
-            "Search nodes typically only see data from their input connections",
-            "Early search (before extraction) may provide generic retrieval",
-            "Late search (after JSON mapper) may be able to incorporate client context",
-            "Consider placing template search after JSON mapper if client context is needed",
-            "Multiple search nodes may be useful for different purposes (generic vs context-aware)",
-        ],
-    },
-    "node-execution-conditions": {
-        title: "When Nodes Execute (Execution Conditions)",
-        content: "Nodes execute based on: 1) Input connections (data must flow in), 2) runIf conditions (must evaluate to true), 3) trigger_when conditions (for HITL/conditional nodes). Nodes without valid input paths or with false runIf conditions will NOT execute.",
-        status: "verified",
-        examples: [
-            "Orphan node: No input connection from trigger → node never executes",
-            "runIf false: Node has input but runIf condition evaluates false → node skipped",
-            "Missing category edge: Categorizer output not connected → downstream nodes never receive category",
-            "Dead end: Node executes but output not connected → data lost, no response to user",
-        ],
-        criticalRules: [
-            "Every node MUST have a path from trigger (or be reachable via runIf conditions)",
-            "runIf conditions use: lhs (actionOutput reference), operator (1=equals), rhs (enumValue or value)",
-            "If runIf evaluates false, node is skipped (doesn't execute)",
-            "Nodes without input connections are 'orphans' and never execute",
-            "Categorizer nodes need downstream nodes with runIf conditions for each category",
-            "Check execution flow: trigger → [conditional paths] → response → WORKFLOW_OUTPUT",
-        ],
-    },
-    "array-preservation": {
-        title: "Array Preservation in Workflows",
-        content: "Arrays from entity extraction may be flattened or truncated in some cases. Consider explicit configuration if array structure matters. Needs validation.",
-        status: "experimental",
-        examples: [
-            "Consider: Entity extraction schema: { 'participants': { 'type': 'array', 'items': 'string' } }",
-            "Consider: JSON mapper - preserve arrays rather than flattening",
-            "May occur: Without array config, arrays may return only first element",
-            "For multiple recipients: Consider array in to_email or iterator pattern",
-        ],
-        criticalRules: [
-            "Consider defining array types explicitly in extraction schema",
-            "JSON mapper may need explicit array mapping configuration",
-            "Test array handling with actual workflow to verify behavior",
-            "This guidance needs validation - behavior may vary by node type",
-        ],
-    },
-    "search-filtering": {
-        title: "Search Filtering Considerations",
-        content: "Consider combining semantic query + structured filters. Security filters (tenant_id/client_id) are typically important for isolation. Needs validation with actual platform behavior.",
-        status: "experimental",
-        examples: [
-            "Consider: semantic query + tenant_id filter + path_prefix filter",
-            "Consider: Fallback to broader search if filtered results are empty",
-            "May cause issues: Only filename/path filter without semantic query",
-            "May cause issues: Over-filtering from uncertain extraction",
-        ],
-        criticalRules: [
-            "Consider combining semantic query + structured filters",
-            "Security filters (tenant_id/client_id) are typically needed for isolation",
-            "Path/filename filters may help narrow scope but verify behavior",
-            "If filtered search returns few results, consider broader fallback",
-            "Test actual filter behavior - this guidance needs validation",
-        ],
-    },
-    "fallback-response-inputs": {
-        title: "Fallback Response Input Considerations",
-        content: "Fallback responses may benefit from full conversation context rather than just summarized query. Consider what context the fallback handler needs. Needs validation.",
-        status: "experimental",
-        examples: [
-            "Consider: trigger.chat_conversation → fallback.query (full context)",
-            "Consider: Include routing context in fallback inputs",
-            "May cause issues: Only summarized_conversation may lose user wording",
-        ],
-        criticalRules: [
-            "Consider what context fallback handler needs",
-            "Full conversation may provide better context than summary alone",
-            "Include routing context if helpful for fallback logic",
-            "Test actual fallback behavior - this guidance needs validation",
-        ],
-    },
-    "separate-vs-merged-inputs": {
-        title: "Separate vs Merged Inputs Consideration",
-        content: "Consider keeping separate inputs for different data sources. named_inputs_* may help provide semantic clarity. Needs validation.",
-        status: "experimental",
-        examples: [
-            "Consider: named_inputs_Conversation + named_inputs_Templates for clarity",
-            "Consider: Separate inputs may help agent reason over each source",
-            "May cause issues: Merging all into single input may lose structure",
-        ],
-        criticalRules: [
-            "Consider separate named_inputs_* for different data sources",
-            "Separate inputs may provide semantic clarity",
-            "Test actual behavior - this guidance needs validation",
-        ],
-    },
-    "folder-path-filtering": {
-        title: "Folder Path Filtering Consideration",
-        content: "Path filtering may help narrow search scope. Consider combining with semantic query. Verify actual platform support for path filters.",
-        status: "experimental",
-        examples: [
-            "Consider: path_prefix filter + semantic query",
-            "May help: Normalized paths for consistent filtering",
-            "May cause issues: Exact path matching (can be brittle)",
-        ],
-        criticalRules: [
-            "Consider combining path filters with semantic query",
-            "Verify path filter support in actual platform",
-            "Test actual behavior - this guidance needs validation",
-        ],
-    },
-    "automated-extraction-json": {
-        title: "Extraction and JSON Mapping Pattern",
-        content: "Consider extraction → JSON mapper pattern for structured data flow. This may help reduce redundant extraction. Needs validation.",
-        status: "experimental",
-        examples: [
-            "Consider: trigger → summarizer → extractor → json_mapper → consumers",
-            "Consider: JSON mapper to normalize extracted values",
-            "May help: Single extraction point rather than multiple",
-        ],
-        criticalRules: [
-            "Consider single extraction point with JSON mapper distribution",
-            "Extraction schema configuration may help structure output",
-            "Test actual behavior - this guidance needs validation",
-        ],
-    },
-    "when-filters-necessary": {
-        title: "Filter Necessity Considerations",
-        content: "Security/tenant isolation filters are typically important. Verify what filtering your storage layer provides. Needs validation with actual platform.",
-        status: "experimental",
-        examples: [
-            "Consider: tenant_id/client_id filters for security isolation",
-            "Consider: Whether storage layer already enforces isolation",
-            "May cause issues: Relying only on document annotations for isolation",
-        ],
-        criticalRules: [
-            "Consider security filters for tenant/client isolation",
-            "Verify what isolation your storage layer provides",
-            "Test actual behavior - this guidance needs validation",
-        ],
-    },
-    "filter-query-guidance": {
-        title: "Filter vs Query Considerations",
-        content: "Consider filters when user references specific documents or folders. Consider semantic queries when user describes topics. Both may be useful together. Needs validation.",
-        status: "experimental",
-        examples: [
-            "Consider filters: User names specific doc or references folder",
-            "Consider query: User describes topic or intent",
-            "Consider both: Broad filters + semantic query",
-        ],
-        criticalRules: [
-            "Consider filters when user references specific documents",
-            "Consider semantic queries when user describes topics",
-            "Combining both may improve results - test actual behavior",
-            "This guidance needs validation with actual platform",
-        ],
-    },
-    "node-selection": {
-        title: "Node Selection Guide: When to Use What",
-        status: "verified",
-        content: `Choose the RIGHT node type for each task. Using wrong nodes wastes compute, increases latency, and reduces quality.
-
-## Decision Tree
-
-### Q1: Do you need EXTERNAL KNOWLEDGE?
-- YES → Use search node first, then generation
-- NO → Skip search, use generation or transform
-
-### Q2: Do you need AI REASONING/GENERATION?
-- YES → Use LLM-based node
-- NO → Use transform node (json_mapper, fixed_response)
-
-### Q3: What KIND of generation?
-- 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
-
-### Q4: Do you need STRUCTURED DATA extraction?
-- YES → entity_extraction (NOT call_llm!)
-- NO → Continue with generation
-
-## Node Cost/Latency
-
-| Node | LLM Calls | Latency | Use When |
-|------|-----------|---------|----------|
-| 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_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_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_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_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",
-            "Use custom_agent when task requires role context + multi-step reasoning",
-            "Use document_synthesis only when you need search-plan-search-synthesize pattern",
-        ],
-    },
-    "llm-node-selection": {
-        title: "LLM Node Selection: Which One to Use",
-        status: "verified",
-        content: `Different LLM nodes serve different purposes. Choose based on your needs:
-
-## 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
-
-## call_llm
-- **Best for**: Custom text generation with instructions
-- **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_for_external_actions)
-
-## custom_agent
-- **Best for**: Complex tasks requiring role + instructions
-- **Input**: Role instructions + task instructions + named_inputs
-- **Output**: Structured or free-form response (use output_fields for structured)
-- **When**: Multi-step reasoning, persona-based responses, tool-like behavior
-- **NOT for**: Simple generation (overkill)
-- **CRITICAL**: When outputting JSON for json_mapper, use output_fields to define keys
-
-## document_synthesis
-- **Best for**: Multi-source research with planning
-- **Input**: User request + search results
-- **Output**: Synthesized document
-- **When**: Need to search → plan → search again → synthesize
-- **NOT for**: Simple KB lookup (too heavy)`,
-        examples: [
-            "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_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_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)",
-        ],
-    },
-    "search-vs-no-search": {
-        title: "When to Search vs Direct Generation",
-        status: "verified",
-        content: `Not every request needs KB search. Search adds latency and can introduce irrelevant context.
-
-## SEARCH when:
-- User asks factual question about domain knowledge
-- Request references specific documents/data
-- Response accuracy depends on up-to-date information
-- User asks about policies, procedures, product details
-
-## DON'T SEARCH when:
-- User needs help with task (drafting, formatting)
-- Response is conversational/procedural
-- Information is already in context (extracted entities)
-- User asks general questions (time, greeting)`,
-        examples: [
-            "✅ Search: 'What is our return policy?' - needs KB",
-            "✅ Search: 'Tell me about client Thompson' - needs client data",
-            "❌ Don't search: 'Can you draft an email?' - procedural",
-            "❌ Don't search: 'Format this as a table' - transform",
-            "❌ Don't search: 'Hello, how are you?' - greeting",
-        ],
-        criticalRules: [
-            "Search is NOT free - adds 0.5-2s latency per search",
-            "Search can introduce noise if results aren't relevant",
-            "Fallback/greeting responses often don't need search",
-            "Task-based requests (draft, format, summarize) usually don't need search",
-            "Use categorizer to route search vs no-search paths",
-            "If entity extraction already has the data, don't search for it again",
-        ],
-    },
-    "custom-agent-json-output": {
-        title: "custom_agent + json_mapper Pattern",
-        status: "verified",
-        content: `When using custom_agent to generate JSON that will be parsed by json_mapper, you MUST properly configure output_fields or use strict prompting.
-
-## The Problem
-
-Without explicit output_fields, custom_agent returns JSON as a string blob in response_with_sources.
-The json_mapper may fail to extract fields correctly, or output gets misformatted.
-
-## Solution A: Define output_fields (RECOMMENDED)
-
-Use output_fields with extraction columns matching your JSON keys:
-
-\`\`\`json
-{
-  "name": "email_gen",
-  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "custom_agent" }, "version": "v1" },
-  "inputs": {
-    "task_instructions": { "inline": { "wellKnown": { "textWithSources": { 
-      "text": "Generate notification email with To, Subject, and Body fields.",
-      "sources": [] 
-    }}}},
-    "output_fields": {
-      "inline": { "array": { "values": [
-        { "wellKnown": { "extractionColumn": { "id": "To", "name": "To", "dataType": 1 }}},
-        { "wellKnown": { "extractionColumn": { "id": "Subject", "name": "Subject", "dataType": 1 }}},
-        { "wellKnown": { "extractionColumn": { "id": "Body", "name": "Body", "dataType": 1 }}}
-      ]}}
-    }
-  }
-}
-\`\`\`
-
-## Solution B: Strict Prompting + json_mapper
-
-If not using output_fields, instruct LLM to output RAW JSON only:
-
-\`\`\`
-task_instructions: "Output ONLY the JSON object, no markdown. Format: {\\"To\\": \\"...\\", \\"Subject\\": \\"...\\", \\"Body\\": \\"...\\"}"
-\`\`\`
-
-Then wire to json_mapper with matching pathIndices:
-\`\`\`json
-{
-  "json_mapper_config": {
-    "inline": { "wellKnown": { "jsonMapperConfig": {
-      "rules": [
-        { "fieldName": "to", "pathIndices": [{"stringIndex": "To"}], "type": 3 },
-        { "fieldName": "subject", "pathIndices": [{"stringIndex": "Subject"}], "type": 3 },
-        { "fieldName": "body", "pathIndices": [{"stringIndex": "Body"}], "type": 3 }
-      ]
-    }}}
-  }
-}
-\`\`\`
-
-## Wiring json_mapper to fixed_response
-
-json_mapper outputs go to output_json. Use fixed_response template variables:
-
-\`\`\`json
-{
-  "name": "fmt_to",
-  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "fixed_response" }, "version": "v1" },
-  "inputs": {
-    "template": { "inline": { "wellKnown": { "textWithSources": { "text": "{{to}}", "sources": [] }}}},
-    "custom_data": { "actionOutput": { "actionName": "json_map", "output": "output_json" }}
-  }
-}
-\`\`\``,
-        examples: [
-            "Generate email → custom_agent(output_fields=[To,Subject,Body]) → send_email_agent",
-            "Generate email → custom_agent(strict prompt) → json_mapper → fixed_response({{to}}) → send_email_agent",
-            "❌ custom_agent without output_fields → json_mapper fails to parse",
-            "❌ json_mapper output wired directly to send_email_agent → type mismatch (need fixed_response)",
-        ],
-        criticalRules: [
-            "custom_agent + json_mapper: ALWAYS use output_fields OR strict 'ONLY JSON' prompt",
-            "json_mapper outputs to output_json - use fixed_response with {{fieldName}} template",
-            "send_email_agent inputs require TEXT_WITH_SOURCES - use fixed_response to format",
-            "If json_mapper fails to extract: check if LLM is wrapping JSON in markdown (```json)",
-            "pathIndices must EXACTLY match JSON keys (case-sensitive)",
-            "Default values in json_mapper rules prevent null errors",
-        ],
-    },
-};
+export { GUIDANCE_TOPICS } from "./knowledge-guidance-topics.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper Functions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1731,105 +470,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_for_external_actions");
-    }
-    // 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_for_external_actions") && !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
@@ -2044,7 +716,7 @@ export { DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT,
  *
  * SOURCE: ema-repos/ema/docs/workflow-architecture-handoff.md (lines 85-200, constraint checklist 153-167)
  * STATUS: Can be auto-generated from source doc
- * TODO: Add to catalog-sync.yml workflow for automatic updates
+ * SYNC: Candidate for catalog-sync.yml automation (see .context/core/guides/source-repos.md)
  *
  * See .context/core/guides/source-repos.md for sync details
  */