@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/dist/mcp/resources.js

@@ -33,6 +33,7 @@ const __dirname = dirname(__filename);
 import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG, ALL_DEPRECATED_ACTIONS, DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT, WORKFLOW_ENABLING_CONSTRAINTS, MINIMUM_VIABLE_WORKFLOWS, } from "./knowledge.js";
 import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "./domain/validation-rules.js";
 import { STRUCTURAL_INVARIANTS } from "./domain/structural-rules.js";
+import { mineConstraints, formatConstraintReport } from "./domain/proto-constraints.js";
 import { EmaClient } from "../sdk/client.js";
 import { APISchemaRegistry } from "./domain/workflow-validator.js";
 import { loadConfigFromJsonEnv, loadConfigOptional, resolveBearerToken, getEnvByName, getMasterEnv, } from "../sdk/config.js";
@@ -231,6 +232,17 @@ const DYNAMIC_RESOURCES = [
         mimeType: "text/markdown",
         generate: async () => generateBestPracticesChecklist(),
     },
+    // Field Constraints - Mined from proto definitions
+    {
+        uri: "ema://docs/field-constraints",
+        name: "docs/field-constraints",
+        description: "Proto field constraints: immutable fields, read-only fields, creation-only fields, conditional fields. Mined from proto definitions.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            const report = mineConstraints();
+            return formatConstraintReport(report);
+        },
+    },
     // Deprecated Actions - API-first with fallback
     {
         uri: "ema://rules/deprecated-actions",
@@ -373,11 +385,20 @@ const DYNAMIC_RESOURCES = [
                 }
                 md += "\n";
             }
-            md += "## Critical Rule: WORKFLOW_OUTPUT\n\n";
-            md += "**Every workflow must have a `results.WORKFLOW_OUTPUT` that maps to an action output.**\n\n";
+            md += "## Critical Rule: results Mapping\n\n";
+            md += "**Every workflow must have a `results` map connecting action outputs to the persona's output.**\n\n";
+            md += "### Chat / Voice Personas\n\n";
+            md += "Use `WORKFLOW_OUTPUT` as the key — this is the response shown to the user:\n\n";
             md += "```json\n";
             md += '{\n  "results": {\n    "WORKFLOW_OUTPUT": {\n      "actionName": "respond_node",\n      "outputName": "response_with_sources"\n    }\n  }\n}\n';
-            md += "```\n";
+            md += "```\n\n";
+            md += "Multiple response nodes (e.g., one per categorizer branch) can all map to `WORKFLOW_OUTPUT` — only the one that executes via `runIf` will produce output.\n\n";
+            md += "### Dashboard Personas\n\n";
+            md += "Use `<actionName>.<outputName>` dot-notation keys — each key becomes a column in the dashboard:\n\n";
+            md += "```json\n";
+            md += '{\n  "results": {\n    "entity_extraction_node.extraction_columns": {\n      "actionName": "entity_extraction_node",\n      "outputName": "extraction_columns"\n    },\n    "rule_validation_node.ruleset_output": {\n      "actionName": "rule_validation_node",\n      "outputName": "ruleset_output"\n    }\n  }\n}\n';
+            md += "```\n\n";
+            md += "Common dashboard result outputs: `extraction_columns`, `ruleset_output`, `llm_output`.\n";
             return md;
         },
     },
@@ -538,9 +559,358 @@ When generating or fixing workflow_def that includes \`entity_extraction_with_do
 - **Within the same extraction_columns array**, every column must have a **unique \`id\`**. Duplicate \`id\` values in one array are invalid.
 - Different actions can reuse the same id strings (e.g. \`event_extraction\` has \`col1\`..\`col6\`, \`validation_results\` has \`col1\`..\`col10\`) — each action has its own array.
 
-## Object / nested columns
+## dataType Reference (PrimitiveType enum)
+
+| Value | Type | Description |
+|-------|------|-------------|
+| 0 | UNKNOWN | Unspecified (avoid) |
+| 1 | STRING | Text values (default) |
+| 2 | NUMBER | Numeric values |
+| 3 | BOOLEAN | True/false values |
+| 4 | ARRAY | Array of repeated values (use with \`arrayElementType\`) |
+| 5 | OBJECT | Grouped/nested structure (contains sub-columns via \`value.objectValue\`) |
+| 6 | DATE | Date values (use with \`formattingOptions.dateFormat\`) |
+| 7 | DOCUMENT_VERSION_ID | Reference to a document version |
+
+**Note on enums:** To create an enumerated column, use \`dataType: 1\` (STRING) with \`isEnum: true\` and populate \`possibleValues\`.
+
+## Object / Grouped Columns (dataType: 5)
+
+Use \`dataType: 5\` to create a **Group** column with sub-columns (nested structure). In the UI, this appears as a parent column with expandable sub-columns.
+
+The sub-columns are defined as a nested array in the column's \`value.objectValue.values\`. Each sub-column is a **bare \`ExtractionColumn\`** (no \`wellKnown\` wrapper — that wrapper only appears at the top-level \`extraction_columns.inline.array.values[]\`).
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "address",
+      "name": "Address",
+      "description": "Structured address fields",
+      "dataType": 5,
+      "value": {
+        "objectValue": {
+          "values": [
+            {
+              "id": "street",
+              "name": "Street Name",
+              "description": "Street name",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "city",
+              "name": "City",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "postal_code",
+              "name": "Postal Code",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            }
+          ]
+        }
+      },
+      "arrayElementType": {
+        "id": "address",
+        "name": "Address",
+        "dataType": 5,
+        "detailedDescription": "",
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      },
+      "detailedDescription": "",
+      "isEnum": false,
+      "possibleValues": [],
+      "dependencies": [],
+      "fileSources": [],
+      "auxiliarySources": []
+    }
+  }
+}
+\`\`\`
+
+**Key rules for grouped columns:**
+- Parent column uses \`dataType: 5\` (OBJECT)
+- Sub-columns live in \`value.objectValue.values\` as **bare ExtractionColumn objects** (no \`wellKnown\` wrapper)
+- Each sub-column needs its own unique \`id\` within the group
+- Sub-columns can themselves be groups (nested groups) up to the nesting depth limit
+- The UI shows the parent as a collapsible group header with sub-columns underneath
+- **Auto-populated \`arrayElementType\`:** The API may auto-populate a sparse \`arrayElementType\` on OBJECT columns (with \`id\`, \`name\`, \`dataType: 5\` but NO sub-columns). This is normal — include it when copying from a working persona but it is not required when creating new columns.
+
+**Default field pattern:** Live API data always includes these fields on every column, even when empty. Include them for consistency:
+\`\`\`
+"detailedDescription": "", "isEnum": false, "possibleValues": [],
+"dependencies": [], "fileSources": [], "auxiliarySources": []
+\`\`\`
+
+**IMPORTANT — wellKnown wrapping rules:**
+- \`extraction_columns.inline.array.values[]\` = \`Value\` proto type → each entry needs \`{ "wellKnown": { "extractionColumn": {...} } }\`
+- \`objectValue.values[]\` inside a column = \`ExtractionColumn[]\` proto type → bare \`{ "id": "...", "name": "...", "dataType": ... }\`
+- \`arrayElementType\` = \`ExtractionColumn\` proto type → bare \`{ "dataType": ..., ... }\`
 
-- For object-type columns (e.g. \`dataType: 5\`), use \`value.objectValue.values\` with nested \`extractionColumn\` entries. Each nested entry also needs unique \`id\` within that nested list.
+## Multi-Value / Array Columns (dataType: 4)
+
+Use \`dataType: 4\` (ARRAY) with \`arrayElementType\` to extract **repeated values** from a document (e.g., multiple phone numbers, a list of names).
+
+The \`arrayElementType\` field is a bare \`ExtractionColumn\` (no \`wellKnown\` wrapper). It typically includes \`id\` and \`name\` (often repeating the parent's values) plus the element \`dataType\`.
+
+### Simple Array (repeated scalar values)
+
+Extract multiple values of the same primitive type (e.g., list of invoice IDs):
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "invoice_ids",
+      "name": "Invoice(s)",
+      "description": "Invoice IDs as a list",
+      "dataType": 4,
+      "arrayElementType": {
+        "id": "invoice_ids",
+        "name": "Invoice(s)",
+        "description": "Single invoice ID like INV-2024-1423",
+        "dataType": 1,
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      }
+    }
+  }
+}
+\`\`\`
+
+### Array of Objects (repeated grouped values)
+
+Extract multiple structured items (e.g., line items from an invoice). Combine \`dataType: 4\` with an \`arrayElementType\` of \`dataType: 5\` (OBJECT). Sub-columns inside \`objectValue.values\` are **bare ExtractionColumn objects** (no \`wellKnown\` wrapper):
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "line_items",
+      "name": "Items",
+      "description": "All line items from the invoice",
+      "dataType": 4,
+      "value": {
+        "objectValue": {
+          "values": [
+            {
+              "id": "item_name",
+              "name": "Item Name",
+              "dataType": 1,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "quantity",
+              "name": "Quantity",
+              "dataType": 2,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "unit_price",
+              "name": "Unit Price",
+              "dataType": 2,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            }
+          ]
+        }
+      },
+      "arrayElementType": {
+        "id": "line_items",
+        "name": "Items",
+        "dataType": 5,
+        "value": {
+          "objectValue": {
+            "values": [
+              {
+                "id": "item_name",
+                "name": "Item Name",
+                "dataType": 1,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              },
+              {
+                "id": "quantity",
+                "name": "Quantity",
+                "dataType": 2,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              },
+              {
+                "id": "unit_price",
+                "name": "Unit Price",
+                "dataType": 2,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              }
+            ]
+          }
+        },
+        "description": "",
+        "detailedDescription": "",
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      },
+      "detailedDescription": "",
+      "isEnum": false,
+      "possibleValues": [],
+      "dependencies": [],
+      "fileSources": [],
+      "auxiliarySources": []
+    }
+  }
+}
+\`\`\`
+
+**Key rules for array columns:**
+- Parent column uses \`dataType: 4\` (ARRAY)
+- \`arrayElementType\` is a bare \`ExtractionColumn\` (no \`wellKnown\` wrapper) — repeats the parent's \`id\` and \`name\`, plus the element \`dataType\`
+- For simple arrays: \`arrayElementType.dataType\` = scalar type (1=STRING, 2=NUMBER, etc.)
+- For arrays of objects: \`arrayElementType.dataType: 5\` with \`value.objectValue.values\` containing bare sub-columns
+- **Dual storage pattern:** For array-of-objects, the sub-columns appear in BOTH \`value.objectValue.values\` (on the parent) AND \`arrayElementType.value.objectValue.values\`. Both sets must match. The \`arrayElementType\` is the canonical schema; the parent \`value.objectValue\` may be auto-populated by the API.
+- Sub-columns inside \`objectValue.values\` are bare ExtractionColumn objects (no \`wellKnown\` wrapper)
+- The UI labels this as "Multi Value" — in the API, it maps to \`dataType: 4\` + \`arrayElementType\`
+- **There is no \`isMultiValue\` API field** — that is a UI-only label. Always use \`dataType: 4\` + \`arrayElementType\` in workflow_def.
+
+## Creation-Time Constraints
+
+**IMPORTANT:** The following extraction column properties are set at creation time and **cannot be changed** after the column exists:
+
+| Property | Constraint |
+|----------|-----------|
+| \`dataType\` | Cannot change after creation (e.g., STRING to ARRAY) |
+| \`arrayElementType\` | Cannot change after creation; defines the array element schema |
+| \`value.objectValue\` structure | Sub-column schema is fixed at creation |
+
+To change these properties, you must **delete the column and recreate it** with the new settings.
+
+Other properties (\`name\`, \`description\`, \`possibleValues\`, \`formattingOptions\`) can be updated after creation.
+
+## Enum Columns
+
+To create a column with a fixed set of allowed values, use \`dataType: 1\` (STRING) with \`isEnum: true\` and \`possibleValues\`:
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "priority",
+      "name": "Priority",
+      "description": "Task priority level",
+      "dataType": 1,
+      "isEnum": true,
+      "possibleValues": [
+        { "value": { "stringValue": "High", "case": "stringValue" } },
+        { "value": { "stringValue": "Medium", "case": "stringValue" } },
+        { "value": { "stringValue": "Low", "case": "stringValue" } }
+      ]
+    }
+  }
+}
+\`\`\`
+
+## Document Input Wiring (Dashboard Personas)
+
+Dashboard extraction workflows receive documents through one of two patterns:
+
+### Pattern 1: workflowInput (preferred for newer workflows)
+
+\`\`\`json
+"workflowInputs": {
+  "document-mmf2": {
+    "type": { "arrayType": { "wellKnownType": 5, "isList": false }, "isList": false },
+    "displayName": "Document"
+  }
+}
+\`\`\`
+
+Then in the extraction node:
+\`\`\`json
+"documents": { "workflowInput": { "inputName": "document-mmf2" } }
+\`\`\`
+
+### Pattern 2: trigger output (older workflows)
+
+\`\`\`json
+"documents": { "actionOutput": { "actionName": "trigger", "output": "user_query" } }
+\`\`\`
+
+Note: The output name \`user_query\` is used for documents in older \`document_trigger\` workflows — despite the misleading name, it carries the uploaded document content.
+
+## Extraction Node Options
+
+### disableHumanInteraction
+
+Set to \`true\` to skip the human-in-the-loop review step for extraction results. Default is \`false\` (HITL enabled):
+
+\`\`\`json
+{
+  "name": "entity_extraction_node",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "entity_extraction_with_documents" }, "version": "v0" },
+  "inputs": { ... },
+  "disableHumanInteraction": true
+}
+\`\`\`
 
 ## How to Use
 
@@ -696,16 +1066,20 @@ Chat workflows that process \`chat_conversation\` through search, extraction, or
 \`\`\`
 chat_trigger.chat_conversation → conversation_to_search_query.conversation
 conversation_to_search_query.summarized_conversation → search.query
-search.search_results → respond_with_sources.search_results
-chat_trigger.user_query → respond_with_sources.query
-respond_with_sources.response_with_sources → WORKFLOW_OUTPUT
+search.search_results → respond_for_external_actions.external_action_result
+chat_trigger.user_query → respond_for_external_actions.query
+chat_trigger.chat_conversation → respond_for_external_actions.conversation
+respond_for_external_actions.response → WORKFLOW_OUTPUT
 \`\`\`
 
+> **Note**: \`respond_with_sources/v0\` is DEPRECATED. Use \`respond_for_external_actions\` for all new workflows (search results, tool results, or any context-aware response).
+
 ### Pattern 2: Tool/Action + Respond
 \`\`\`
 chat_trigger.chat_conversation → external_action_caller.conversation
 external_action_caller.tool_execution_result → respond_for_external_actions.external_action_result
 chat_trigger.user_query → respond_for_external_actions.query
+chat_trigger.chat_conversation → respond_for_external_actions.conversation
 respond_for_external_actions.response → WORKFLOW_OUTPUT
 \`\`\`
 
@@ -732,16 +1106,18 @@ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT
 
 ## Key Insight
 
-\`respond_with_sources\` and \`respond_for_external_actions\` are **conversation-aware by design** — they automatically incorporate conversation context when processing the \`query\` input from \`chat_trigger.user_query\`. Generic \`call_llm\` does not.
+\`respond_for_external_actions\` is **conversation-aware by design** — it incorporates conversation context via its \`conversation\` input. Generic \`call_llm\` does not — you must manually wire \`chat_conversation\` via \`named_inputs\`.
+
+> **Deprecated**: \`respond_with_sources/v0\` — use \`respond_for_external_actions\` for all new workflows.
 
 ## When to Use Each Response Node
 
 | Scenario | Response Node | Why |
 |----------|---------------|-----|
-| KB/document Q&A | \`respond_with_sources\` | Handles SEARCH_RESULT type, adds citations |
+| KB/document Q&A | \`respond_for_external_actions\` | Handles search results, conversation-aware |
 | Tool/API results | \`respond_for_external_actions\` | Explains tool results in conversation context |
-| Complex multi-step reasoning | \`call_llm\` + named_inputs with chat_conversation | Full control but requires manual history wiring |
-| Static/template response | \`fixed_response\` | No LLM needed, just template + variables |
+| Complex multi-step reasoning | \`call_llm/v2\` + named_inputs with chat_conversation | Full control but requires manual history wiring |
+| Static/template response | \`fixed_response/v1\` | No LLM needed, just template + variables |
 `;
         },
     },
@@ -879,6 +1255,221 @@ When you already have a clean extracted value and just need TEXT_WITH_SOURCES wr
         },
     },
     // ─────────────────────────────────────────────────────────────────────────────
+    // Workflow Node Reference - per-node I/O types, semantics, categorizer patterns
+    // Consolidated from .context/public/guides/workflow-builder-patterns.md
+    // ─────────────────────────────────────────────────────────────────────────────
+    {
+        uri: "ema://docs/workflow-node-reference",
+        name: "docs/workflow-node-reference",
+        description: "Complete workflow node reference: per-node I/O types, categorizer patterns (runIf/enumTypes), " +
+            "LLM named_inputs convention, temperature guidelines, data types between nodes",
+        mimeType: "text/markdown",
+        generate: async () => {
+            let md = `# Workflow Node Reference\n\n`;
+            md += `Practical reference for building Ema workflows. Covers per-node I/O semantics, `;
+            md += `categorizer configuration, LLM patterns, and data type compatibility.\n\n`;
+            md += `## Data Types Between Nodes\n\n`;
+            md += `| Type | Code Constant | Description | Example |\n`;
+            md += `|------|---------------|-------------|---------|\n`;
+            md += `| **Plain Text** | \`WELL_KNOWN_TYPE_TEXT_WITH_SOURCES\` | Text with optional citation metadata | User's message, LLM response |\n`;
+            md += `| **Conversation** | \`WELL_KNOWN_TYPE_CHAT_CONVERSATION\` | Structured message history (role + content) | Full chat thread |\n`;
+            md += `| **Search Results** | \`WELL_KNOWN_TYPE_SEARCH_RESULT\` | Retrieved document chunks with citations | KB search results |\n`;
+            md += `| **Enum** | \`WELL_KNOWN_TYPE_ENUM\` | Category/classification signal for routing | \`category::Schedule Appointment\` |\n`;
+            md += `| **Document** | \`WELL_KNOWN_TYPE_DOCUMENT\` | Uploaded file content | PDF, DOCX for extraction |\n`;
+            md += `| **Any** | \`WELL_KNOWN_TYPE_ANY\` | Untyped — needs intermediary for type-safe wiring | entity_extraction output |\n\n`;
+            md += `**Critical**: Types are NOT interchangeable. \`CHAT_CONVERSATION\` into a \`TEXT_WITH_SOURCES\` input causes type mismatch errors. Use converter nodes when needed.\n\n`;
+            md += `---\n\n`;
+            md += `## Input Semantics by Context\n\n`;
+            md += `The same input name means different things depending on the node:\n\n`;
+            md += `| Input Name | In Search Nodes | In Respond Nodes | In Extract Nodes | In Categorizers |\n`;
+            md += `|------------|-----------------|-------------------|-------------------|------------------|\n`;
+            md += `| \`query\` | Search term to look up | User's question to answer | Source text to analyze | N/A |\n`;
+            md += `| \`conversation\` | N/A | N/A (use named_inputs) | N/A | Full history for classification |\n`;
+            md += `| \`trigger_when\` | N/A | "Should I run?" | "Should I run?" | N/A |\n`;
+            md += `| \`named_inputs_*\` | N/A | Additional context | Additional context | N/A |\n\n`;
+            md += `**Mental model:** \`query\` = "What to process?" · \`conversation\` = "Full context" · \`trigger_when\` = "Should I run?" · \`named_inputs_*\` = "Extra context"\n\n`;
+            md += `---\n\n`;
+            md += `## Node Type Reference\n\n`;
+            md += `### chat_trigger\n`;
+            md += `Entry point for chat/voice workflows.\n`;
+            md += `- **Inputs**: None (system event)\n`;
+            md += `- **Outputs**: \`user_query\` (TEXT_WITH_SOURCES), \`chat_conversation\` (CHAT_CONVERSATION)\n`;
+            md += `- **Pairs with**: Intent routers, search nodes, LLM nodes\n\n`;
+            md += `### document_trigger\n`;
+            md += `Entry point for dashboard workflows (file upload per row).\n`;
+            md += `- **Inputs**: None (system event — triggered when row created/file uploaded)\n`;
+            md += `- **Outputs**: \`document_content\` (DOCUMENT), \`row_data\` (ANY — column values)\n`;
+            md += `- **Pairs with**: entity_extraction_with_documents, call_llm, search\n`;
+            md += `- **Critical**: Dashboard personas only. Each row triggers one workflow execution.\n\n`;
+            md += `### chat_categorizer\n`;
+            md += `Classify conversation into intent categories for routing.\n`;
+            md += `- **Inputs**: \`conversation\` (CHAT_CONVERSATION) — must be full history, NOT user_query\n`;
+            md += `- **Outputs**: \`category\` (ENUM) — one per configured category\n`;
+            md += `- **Critical**: Always include Fallback category. Every category needs a handler. Must have \`typeArguments.categories\` pointing to enumType.\n\n`;
+            md += `### text_categorizer/v1\n`;
+            md += `Classify text content (not conversation) for routing.\n`;
+            md += `- **Inputs**: \`named_inputs\` (multiBinding)\n`;
+            md += `- **Outputs**: \`category\` (ENUM)\n`;
+            md += `- **Critical**: \`text_categorizer/v0\` is deprecated — use v1 with \`named_inputs\`.\n\n`;
+            md += `### search/v2\n`;
+            md += `Retrieve relevant documents from uploaded knowledge base.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`datastore_configs\` (from widget)\n`;
+            md += `- **Outputs**: \`search_results\` (SEARCH_RESULT)\n`;
+            md += `- **Critical**: NOT an LLM node — do NOT include \`model_config\`. Data must be uploaded first. \`search/v0\` is deprecated.\n\n`;
+            md += `### conversation_to_search_query\n`;
+            md += `Convert multi-turn conversation to a search-optimized query.\n`;
+            md += `- **Inputs**: \`conversation\` (CHAT_CONVERSATION)\n`;
+            md += `- **Outputs**: \`summarized_conversation\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Required for multi-turn chat search. Direct CHAT_CONVERSATION → search causes type mismatch.\n\n`;
+            md += `### call_llm/v2\n`;
+            md += `Generate natural language response using LLM.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`named_inputs_*\` (ANY — flexible), \`trigger_when\` (ENUM)\n`;
+            md += `- **Outputs**: \`response_with_sources\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Must wire to WORKFLOW_OUTPUT or response is lost. \`call_llm/v0\` is deprecated.\n\n`;
+            md += `### respond_for_external_actions\n`;
+            md += `Generate conversation-aware response from search results or tool outputs.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), \`external_action_result\` (TEXT_WITH_SOURCES/SEARCH_RESULT)\n`;
+            md += `- **Outputs**: \`response\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Replaces deprecated \`respond_with_sources/v0\`. Has built-in citation handling and conversation awareness.\n\n`;
+            md += `### fixed_response/v1\n`;
+            md += `Return a static predefined message.\n`;
+            md += `- **Inputs**: \`trigger_when\` (ENUM), \`named_inputs_*\` for template variables\n`;
+            md += `- **Outputs**: \`fixed_response_with_sources\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Pairs with**: Categorizers (as fallback), type conversion with \`{{variables}}\` templates, send_email_agent\n\n`;
+            md += `### external_action_caller\n`;
+            md += `Call external APIs/tools (ServiceNow, Salesforce, calendars).\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), tool configuration\n`;
+            md += `- **Outputs**: \`tool_execution_result\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Pairs with**: Entity extractors (for parameters), respond nodes (for result formatting)\n\n`;
+            md += `### entity_extraction_with_documents\n`;
+            md += `Extract structured entities grounded in provided documents.\n`;
+            md += `- **Inputs**: \`documents\` (DOCUMENT), extraction column config\n`;
+            md += `- **Outputs**: \`extraction_columns\` (ANY — structured extraction results)\n`;
+            md += `- **Critical**: Output type is ANY — needs intermediary (json_mapper + fixed_response) before send_email inputs.\n`;
+            md += `- See \`ema://rules/extraction-column-format\` for column schema.\n\n`;
+            md += `### send_email_agent\n`;
+            md += `Send email with specified recipient, subject, and body.\n`;
+            md += `- **Inputs**: \`email_to\` (TEXT_WITH_SOURCES), \`email_subject\` (ANY), \`email_body\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`send_status\` (ANY)\n`;
+            md += `- **Critical**: Inputs must be TEXT_WITH_SOURCES — use intermediary chain from ANY-typed sources.\n`;
+            md += `- See \`ema://rules/email-input-wiring\` for wiring patterns.\n\n`;
+            md += `### json_mapper\n`;
+            md += `Extract specific fields from JSON/structured data into individual outputs.\n`;
+            md += `- **Inputs**: \`input_json\` (ANY), mapping rules\n`;
+            md += `- **Outputs**: \`output_json\` per mapped field\n`;
+            md += `- **Pairs with**: entity_extraction (field extraction), fixed_response (type conversion)\n\n`;
+            md += `### rule_validation_with_documents\n`;
+            md += `Check extracted data against business rules (compliance, thresholds).\n`;
+            md += `- **Inputs**: \`primary_docs\` (DOCUMENT), \`map_of_extracted_columns\` (ANY)\n`;
+            md += `- **Outputs**: \`ruleset_output\` (ANY — validation results)\n`;
+            md += `- **Critical**: Rules configured in UI settings panel, not via workflow_def inputs.\n\n`;
+            md += `### live_web_search\n`;
+            md += `Real-time web search for current information.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`web_search_results\` (SEARCH_RESULT)\n`;
+            md += `- **Critical**: No data upload needed (searches the web).\n\n`;
+            md += `### combine_search_results\n`;
+            md += `Merge results from multiple search sources with deduplication.\n`;
+            md += `- **Inputs**: \`search_results_1\` (SEARCH_RESULT), \`search_results_2\` (SEARCH_RESULT)\n`;
+            md += `- **Outputs**: \`combined_results\` (SEARCH_RESULT)\n`;
+            md += `- **Pairs with**: search/v2 + live_web_search, or any two search sources\n`;
+            md += `- **Note**: \`combine_search_results/v0\` is deprecated. For new workflows, prefer \`call_llm\` with multiple \`named_inputs\` to combine search results.\n\n`;
+            md += `### response_validator\n`;
+            md += `Validate LLM output against quality/compliance criteria.\n`;
+            md += `- **Inputs**: \`reference_query\` (TEXT_WITH_SOURCES), \`response_to_validate\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`abstain_reason\` (TEXT_WITH_SOURCES — reason for rejection, empty if valid)\n\n`;
+            md += `### abstain_action\n`;
+            md += `Provide a safe decline response when AI should not answer.\n`;
+            md += `- **Inputs**: \`abstain_reason\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`abstain_reason\` (TEXT_WITH_SOURCES — decline message)\n\n`;
+            md += `---\n\n`;
+            md += `## Categorizer Configuration\n\n`;
+            md += `### Defining enumTypes\n\n`;
+            md += `Categories must be defined in \`workflow_def.enumTypes\`:\n\n`;
+            md += `\`\`\`json\n`;
+            md += `"enumTypes": [{\n`;
+            md += `  "name": { "name": "intent_categories", "namespaces": [] },\n`;
+            md += `  "options": [\n`;
+            md += `    { "name": "Sales", "description": "Sales inquiries" },\n`;
+            md += `    { "name": "Support", "description": "Technical support" },\n`;
+            md += `    { "name": "General", "description": "General questions" },\n`;
+            md += `    { "name": "Fallback", "description": "Unclear or unmatched intents" }\n`;
+            md += `  ]\n`;
+            md += `}]\n`;
+            md += `\`\`\`\n\n`;
+            md += `### typeArguments\n\n`;
+            md += `The categorizer's \`typeArguments\` must reference the enum:\n\n`;
+            md += `\`\`\`json\n`;
+            md += `"typeArguments": {\n`;
+            md += `  "categories": {\n`;
+            md += `    "enumType": { "name": { "name": "intent_categories", "namespaces": [] } },\n`;
+            md += `    "isList": false\n`;
+            md += `  }\n`;
+            md += `}\n`;
+            md += `\`\`\`\n\n`;
+            md += `**Critical**: Empty \`typeArguments\` causes deploy failure.\n\n`;
+            md += `### runIf Condition Format\n\n`;
+            md += `\`\`\`json\n`;
+            md += `{\n`;
+            md += `  "lhs": {\n`;
+            md += `    "actionOutput": { "actionName": "chat_categorizer", "output": "category" },\n`;
+            md += `    "autoDetectedBinding": false\n`;
+            md += `  },\n`;
+            md += `  "operator": 1,\n`;
+            md += `  "rhs": {\n`;
+            md += `    "inline": { "enumValue": "Market_Impact" },\n`;
+            md += `    "autoDetectedBinding": false\n`;
+            md += `  }\n`;
+            md += `}\n`;
+            md += `\`\`\`\n\n`;
+            md += `| Operator | Meaning | Use Case |\n`;
+            md += `|----------|---------|----------|\n`;
+            md += `| \`1\` | Equals (\`==\`) | Route to handler when category matches |\n`;
+            md += `| \`2\` | Not equals (\`!=\`) | Run for all categories except one |\n\n`;
+            md += `For OR conditions (run for Sales OR General), use \`operator: 2\` with Fallback: \`category != Fallback\`.\n\n`;
+            md += `### Nested Categorizers\n\n`;
+            md += `For complex routing, chain categorizers:\n`;
+            md += `\`\`\`\n`;
+            md += `chat_categorizer (Level 1: HR, IT, General, Fallback)\n`;
+            md += `  └─→ text_categorizer (Level 2 for HR: Benefits, Leave, Payroll, Fallback)\n`;
+            md += `\`\`\`\n\n`;
+            md += `---\n\n`;
+            md += `## LLM Configuration (call_llm)\n\n`;
+            md += `### named_inputs Convention\n\n`;
+            md += `\`call_llm\` accepts additional context via suffix pattern \`named_inputs_<Descriptive_Name>\`:\n\n`;
+            md += `| Named Input | Type | Purpose |\n`;
+            md += `|-------------|------|----------|\n`;
+            md += `| \`named_inputs_Search_Results\` | SEARCH_RESULT | KB search results for RAG |\n`;
+            md += `| \`named_inputs_Conversation\` | CHAT_CONVERSATION | Full conversation history |\n`;
+            md += `| \`named_inputs_Intent\` | ENUM | Detected category from categorizer |\n`;
+            md += `| \`named_inputs_Current_Message\` | TEXT_WITH_SOURCES | Current user message |\n`;
+            md += `| \`named_inputs_Tool_Result\` | TEXT_WITH_SOURCES | External action output |\n\n`;
+            md += `\`named_inputs\` accepts **ANY** type — this is how you pass CHAT_CONVERSATION and SEARCH_RESULT into LLM nodes.\n\n`;
+            md += `### Temperature Guidelines\n\n`;
+            md += `| Use Case | Temperature | Why |\n`;
+            md += `|----------|-------------|-----|\n`;
+            md += `| Entity extraction | 0.0-0.3 | Accuracy over creativity |\n`;
+            md += `| Document generation | 0.3-0.5 | Consistent formatting |\n`;
+            md += `| General Q&A / chat | 0.5-0.7 | Balanced creativity and accuracy |\n`;
+            md += `| Creative writing | 0.7-1.0 | More varied output |\n\n`;
+            md += `### Consolidation Rule\n\n`;
+            md += `If multiple \`call_llm\` nodes share the same inputs and differ only by \`trigger_when\` gate, consolidate them:\n`;
+            md += `1. Create one \`call_llm\` that runs when not Fallback\n`;
+            md += `2. Wire \`categorizer.category → call_llm.named_inputs_Intent\`\n`;
+            md += `3. Update prompt: "Based on the detected intent ({{Intent}}), respond accordingly"\n`;
+            md += `4. Keep separate nodes only when intents require different tools, search sources, or safety constraints.\n\n`;
+            md += `---\n\n`;
+            md += `## See Also\n\n`;
+            md += `- \`ema://rules/input-sources\` — Input source validation rules\n`;
+            md += `- \`ema://rules/extraction-column-format\` — Entity extraction column schema\n`;
+            md += `- \`ema://rules/email-input-wiring\` — Email field wiring patterns\n`;
+            md += `- \`ema://rules/json-output-patterns\` — custom_agent + json_mapper patterns\n`;
+            md += `- \`ema://rules/chat-response-wiring\` — Chat response wiring rules\n`;
+            md += `- \`ema://rules/anti-patterns\` — Common workflow anti-patterns\n`;
+            return md;
+        },
+    },
+    // ─────────────────────────────────────────────────────────────────────────────
     // Workflow Requirements & Guidance
     // NOT hardcoded templates - provide requirements and let LLM generate
     // ─────────────────────────────────────────────────────────────────────────────
@@ -925,7 +1516,7 @@ When you already have a clean extracted value and just need TEXT_WITH_SOURCES wr
                     "Use search/v2 (NOT v0) with datastore_configs",
                     "Include Fallback category in every categorizer",
                     "Use respond_for_external_actions (NOT deprecated respond_with_sources)",
-                    "For approval workflows: enable HITL flag on the agent (not a standalone general_hitl node)",
+                    "For approval workflows: enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL). general_hitl is NOT deployable.",
                 ],
                 _next_step: "Call workflow(mode='get', persona_id='...') to get full schema, then generate workflow_def",
             }, null, 2);
@@ -2098,9 +2689,9 @@ These rules are extracted from the Go validator's static validation logic. Follo
 **Good Pattern**:
 \`\`\`json
 {
-  "path": ["trigger", "categorizer", "billing_branch", "search", "respond_with_sources"],
-  "named_result": "response_with_sources",
-  "produces": ["response_with_sources"]  // ✅ Produced
+  "path": ["trigger", "categorizer", "billing_branch", "search", "respond_for_external_actions"],
+  "named_result": "response",
+  "produces": ["response"]  // ✅ Produced
 }
 \`\`\`
 
@@ -2114,7 +2705,7 @@ These rules are extracted from the Go validator's static validation logic. Follo
 3. Connect the node's output to WORKFLOW_OUTPUT
 
 **Common Fixes**:
-- Add \`respond_with_sources\` node after search
+- Add \`respond_for_external_actions\` node after search
 - Add \`call_llm\` node for text generation
 - Add \`fixed_response\` for static responses
 
@@ -2222,7 +2813,7 @@ These rules are extracted from the Go validator's static validation logic. Follo
 **Good Pattern**:
 \`\`\`json
 {
-  "path": ["trigger", "categorizer", "billing", "search", "respond_with_sources"],
+  "path": ["trigger", "categorizer", "billing", "search", "respond_for_external_actions"],
   "has_response": true  // ✅ Has response
 }
 \`\`\`
@@ -2441,6 +3032,7 @@ Before deploying, verify:
 - \`ema://rules/json-output-patterns\` - custom_agent + json_mapper pattern
 - \`ema://rules/chat-response-wiring\` - Chat response node wiring (avoid duplicate responses)
 - \`ema://rules/email-input-wiring\` - Email input wiring (json_mapper/fixed_response patterns)
+- \`ema://docs/workflow-node-reference\` - Per-node I/O types, categorizer patterns, LLM config
 - \`ema://rules/structural-invariants\` - Structural rules (JSON)
 - \`ema://rules/optimizations\` - Optimization rules (JSON)
 - \`ema://validation/rules\` - Go validator rules reference