@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

package/dist/mcp/knowledge.js

@@ -135,37 +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:
 // - 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
@@ -436,596 +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 — ONLY entity_extraction_with_documents and send_email_agent support it. " +
-            "external_action_caller does NOT support HITL. general_hitl is NOT deployable (appears in catalogs but cannot be deployed). " +
-            "When the user requests approval, enable the HITL flag on send_email_agent or entity_extraction_with_documents. " +
-            "The platform handles the approval UI and routing automatically.\n\n" +
-            "JSON format: Set `disable_human_interaction: false` (or omit — default is false = HITL enabled) on the action node " +
-            "in workflow_def.actions[]. To DISABLE HITL, set `disable_human_interaction: true`. " +
-            "Note the counter-intuitive naming: false = HITL ON, true = HITL OFF.",
-        status: "verified",
-        examples: [
-            "User wants email approval → enable HITL flag on send_email_agent",
-            "User wants extraction review → enable HITL flag on entity_extraction_with_documents",
-            "JSON: { name: 'send_email', action: { name: 'send_email_agent' }, disable_human_interaction: false, ... } → HITL ENABLED",
-            "JSON: { name: 'respond', action: { name: 'call_llm' }, disable_human_interaction: true, ... } → HITL DISABLED (auto-proceed)",
-        ],
-        criticalRules: [
-            "general_hitl is NOT deployable — do NOT add it to any workflow",
-            "HITL is ONLY supported on: entity_extraction_with_documents and send_email_agent",
-            "external_action_caller does NOT support HITL despite appearing in older guidance",
-            "JSON field: `disable_human_interaction` (boolean) on the action node — false=HITL on, true=HITL off",
-            "When user says 'with approval': set disable_human_interaction: false on send_email_agent or entity_extraction_with_documents",
-        ],
-    },
-    "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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1305,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
  */