@ema.co/mcp-toolkit 2026.2.5 → 2026.2.13

package/.context/public/guides/workflow-builder-patterns.md

@@ -0,0 +1,708 @@
+---
+title: "Workflow Builder Patterns & Node Reference"
+date: 2026-02-05
+audience: MCP users, workflow builders, auto-builder agents
+---
+
+# Workflow Builder Patterns & Node Reference
+
+Practical reference for building Ema workflows. Covers input/output semantics for each node type,
+data types flowing between nodes, entity extraction best practices, and common wiring patterns.
+
+Extracted from real auto-builder sessions and validated against platform behavior.
+
+---
+
+## Data Types Between Nodes
+
+Four core data types flow between workflow nodes:
+
+| Type               | Code Constant                       | Description                                       | Example                                        |
+| ------------------ | ----------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
+| **Plain Text**     | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` | Text with optional citation metadata              | User's message, LLM response, formatted output |
+| **Conversation**   | `WELL_KNOWN_TYPE_CHAT_CONVERSATION` | Structured message history (role + content pairs) | Full chat thread for context                   |
+| **Search Results** | `WELL_KNOWN_TYPE_SEARCH_RESULT`     | Retrieved document chunks with citations          | KB search results with source metadata         |
+| **Enum**           | `WELL_KNOWN_TYPE_ENUM`              | Category/classification signal for routing        | `category::Schedule Appointment`               |
+| **Document**       | `WELL_KNOWN_TYPE_DOCUMENT`          | Uploaded file content                             | PDF, DOCX for extraction                       |
+| **Any**            | `WELL_KNOWN_TYPE_ANY`               | Untyped — needs intermediary for type-safe wiring | entity_extraction output                       |
+
+**Critical rule**: Types are NOT interchangeable. `CHAT_CONVERSATION` into a `TEXT_WITH_SOURCES` input
+causes type mismatch errors. Use converter nodes (`conversation_to_search_query`) when needed.
+
+---
+
+## Input Semantics by Context
+
+The same input name means different things depending on the node:
+
+| Input Name       | In Search Nodes        | In Respond Nodes          | In Extract Nodes       | In Categorizers                 |
+| ---------------- | ---------------------- | ------------------------- | ---------------------- | ------------------------------- |
+| `query`          | Search term to look up | User's question to answer | Source text to analyze | N/A                             |
+| `conversation`   | N/A                    | N/A (use named_inputs)    | N/A                    | Full history for classification |
+| `trigger_when`   | N/A                    | "Should I run?"           | "Should I run?"        | N/A                             |
+| `named_inputs_*` | N/A                    | Additional context        | Additional context     | N/A                             |
+
+**Universal mental model:**
+
+- `query` = "What should I process?"
+- `conversation` = "What's the full context?"
+- `trigger_when` = "Should I run at all?"
+- `named_inputs_*` = "Extra context" (search results, current message, etc.)
+
+---
+
+## Node Type Reference
+
+### Chat Trigger (`chat_trigger`)
+
+|                |                                                                           |
+| -------------- | ------------------------------------------------------------------------- |
+| **Purpose**    | Entry point for chat workflows                                            |
+| **Inputs**     | None (system event)                                                       |
+| **Outputs**    | `user_query` (TEXT_WITH_SOURCES), `chat_conversation` (CHAT_CONVERSATION) |
+| **Pairs with** | Intent routers, search nodes, LLM nodes                                   |
+
+### Intent Router (`chat_categorizer`)
+
+|                |                                                                           |
+| -------------- | ------------------------------------------------------------------------- |
+| **Purpose**    | Classify conversation into intent categories for routing                  |
+| **Inputs**     | `conversation` (CHAT_CONVERSATION) — must be full history, NOT user_query |
+| **Outputs**    | `category` (ENUM) — one per configured category                           |
+| **Pairs with** | Multiple gated respond/action nodes, fallback                             |
+| **Critical**   | Always include Fallback category. Every category needs a handler.         |
+
+### Knowledge Search (`search/v2`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Retrieve relevant documents from uploaded knowledge base                      |
+| **Inputs**     | `query` (TEXT_WITH_SOURCES), `datastore_configs` (from widget)                |
+| **Outputs**    | `search_results` (SEARCH_RESULT)                                              |
+| **Pairs with** | Respond nodes (for grounded answers), extract nodes (for grounded extraction) |
+| **Critical**   | NOT an LLM node — do NOT include `model_config`. Data must be uploaded first. |
+
+### Respond (call_llm, respond_with_sources)
+
+|                |                                                                                                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Purpose**    | Generate natural language response using LLM                                                                                                       |
+| **Inputs**     | `query` (TEXT_WITH_SOURCES), `named_inputs_Conversation` (CHAT_CONVERSATION), `named_inputs_Search_Results` (SEARCH_RESULT), `trigger_when` (ENUM) |
+| **Outputs**    | `response_with_sources` (TEXT_WITH_SOURCES)                                                                                                        |
+| **Pairs with** | Search nodes (for RAG), categorizers (for gating), WORKFLOW_OUTPUT                                                                                 |
+| **Critical**   | Must wire to WORKFLOW_OUTPUT or response is silently lost                                                                                          |
+
+### Extract (call_llm configured for extraction)
+
+|                |                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------ |
+| **Purpose**    | Extract specific entities (emails, dates, IDs) from text                                               |
+| **Inputs**     | `query` (TEXT_WITH_SOURCES), `named_inputs_Current_Message` (TEXT_WITH_SOURCES), `trigger_when` (ENUM) |
+| **Outputs**    | Extracted data (TEXT_WITH_SOURCES)                                                                     |
+| **Pairs with** | External actions, json_mapper, send_email                                                              |
+| **Critical**   | Scope inputs tightly — use only `user_query` unless entity spans multiple turns                        |
+
+### Fixed Response (`fixed_response`)
+
+|                |                                                                             |
+| -------------- | --------------------------------------------------------------------------- |
+| **Purpose**    | Return a static predefined message (fallback, compliance notice)            |
+| **Inputs**     | `trigger_when` (ENUM), `named_inputs_*` for template variables              |
+| **Outputs**    | `fixed_response_with_sources` (TEXT_WITH_SOURCES)                           |
+| **Pairs with** | Categorizers (as fallback), type conversion (template with `{{variables}}`) |
+
+### External Action Caller (`external_action_caller`)
+
+|                |                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------- |
+| **Purpose**    | Call external APIs/tools (ServiceNow, Salesforce, calendars)                        |
+| **Inputs**     | `query` (TEXT_WITH_SOURCES), `conversation` (CHAT_CONVERSATION), tool configuration |
+| **Outputs**    | `tool_execution_result` (TEXT_WITH_SOURCES)                                         |
+| **Pairs with** | Entity extractors (for parameters), respond nodes (for result formatting)           |
+
+### Document Trigger (`document_trigger`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Entry point for dashboard workflows (file upload per row)                     |
+| **Inputs**     | None (system event — triggered when a row is created/file uploaded)           |
+| **Outputs**    | `document_content` (DOCUMENT — uploaded file), `row_data` (ANY — column values) |
+| **Pairs with** | entity_extraction_with_documents, call_llm, search                            |
+| **Critical**   | Dashboard personas only. Each row triggers one workflow execution.            |
+
+### Send Email Agent (`send_email_agent`)
+
+|                |                                                                                        |
+| -------------- | -------------------------------------------------------------------------------------- |
+| **Purpose**    | Send email with specified recipient, subject, and body                                 |
+| **Inputs**     | `email_to` (TEXT_WITH_SOURCES), `email_subject` (TEXT_WITH_SOURCES), `email_body` (TEXT_WITH_SOURCES) |
+| **Outputs**    | `confirmation` (TEXT_WITH_SOURCES — send result)                                       |
+| **Pairs with** | fixed_response (for type conversion), json_mapper (field extraction)                   |
+| **Critical**   | Inputs must be TEXT_WITH_SOURCES — use intermediary chain from ANY-typed sources. Enable HITL via `disable_human_interaction: false` for approval. |
+
+### Live Web Search (`live_web_search`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Real-time web search for current information                                  |
+| **Inputs**     | `query` (TEXT_WITH_SOURCES)                                                   |
+| **Outputs**    | `web_search_results` (SEARCH_RESULT)                                          |
+| **Pairs with** | combine_search_results (to merge with KB search), respond nodes               |
+| **Critical**   | No data upload needed (searches the web). Use for current events, external info not in KB. |
+
+### Combine Search Results (`combine_search_results`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Merge results from multiple search sources with deduplication                 |
+| **Inputs**     | `search_results_1` (SEARCH_RESULT), `search_results_2` (SEARCH_RESULT)       |
+| **Outputs**    | `combined_results` (SEARCH_RESULT)                                            |
+| **Pairs with** | search/v2 + live_web_search, or any two search sources                        |
+
+### Conversation to Search Query (`conversation_to_search_query`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Convert multi-turn conversation to a search-optimized query                   |
+| **Inputs**     | `conversation` (CHAT_CONVERSATION)                                            |
+| **Outputs**    | `summarized_conversation` (TEXT_WITH_SOURCES)                                 |
+| **Pairs with** | search/v2 (provides search query from conversation context)                   |
+| **Critical**   | Required for multi-turn chat search. Direct CHAT_CONVERSATION → search causes type mismatch. |
+
+### Response Validator (`response_validator`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Validate LLM output against quality/compliance criteria                       |
+| **Inputs**     | `reference_query` (TEXT_WITH_SOURCES), `response_to_validate` (TEXT_WITH_SOURCES) |
+| **Outputs**    | `abstain_reason` (TEXT_WITH_SOURCES — reason for rejection, empty if valid)   |
+| **Pairs with** | call_llm (validates output), abstain_action (handles rejection)               |
+
+### Abstain Action (`abstain_action`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Provide a safe decline response when AI should not answer                     |
+| **Inputs**     | `abstain_reason` (TEXT_WITH_SOURCES — from response_validator)                |
+| **Outputs**    | `abstain_reason` (TEXT_WITH_SOURCES — decline message)                        |
+| **Pairs with** | response_validator (receives rejection reason)                                |
+
+### Rule Validation with Documents (`rule_validation_with_documents`)
+
+|                |                                                                               |
+| -------------- | ----------------------------------------------------------------------------- |
+| **Purpose**    | Check extracted data against business rules (compliance, thresholds)          |
+| **Inputs**     | `primary_docs` (DOCUMENT), `map_of_extracted_columns` (ANY)                  |
+| **Outputs**    | `ruleset_output` (ANY — validation results)                                  |
+| **Pairs with** | entity_extraction (provides data to check), call_llm (summarizes results)    |
+| **Critical**   | Rules configured in UI settings panel, not via workflow_def inputs.           |
+
+### Entity Extraction with Documents (`entity_extraction_with_documents`)
+
+|                |                                                                                                     |
+| -------------- | --------------------------------------------------------------------------------------------------- |
+| **Purpose**    | Extract structured entities grounded in provided documents                                          |
+| **Inputs**     | `documents` (DOCUMENT), extraction column config                                                    |
+| **Outputs**    | `extraction_columns` (ANY — structured extraction results, needs intermediary for type-safe wiring) |
+| **Pairs with** | json_mapper (field extraction), rule_validation (compliance), send_email (via intermediary)         |
+| **Critical**   | Output type is ANY — needs intermediary before send_email inputs                                    |
+
+### JSON Mapper (`json_mapper`)
+
+|                |                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| **Purpose**    | Extract specific fields from JSON/structured data into individual outputs                   |
+| **Inputs**     | `input_json` (ANY), mapping rules                                                           |
+| **Outputs**    | `output_json` per mapped field                                                              |
+| **Pairs with** | entity_extraction (field extraction), fixed_response (type conversion to TEXT_WITH_SOURCES) |
+
+---
+
+## Entity Extraction Best Practices
+
+Ranked by reliability:
+
+### 1. json_mapper with Schema (Best for known fields)
+
+One-step extraction when you know the exact fields and types.
+
+```
+entity_extraction → json_mapper(rules=[{fieldName: "email", path: "email_address"}])
+```
+
+### 2. entity_extraction_with_documents (Best for grounded extraction)
+
+When extracted values MUST come from provided documents (not hallucinated).
+
+```
+document_trigger → entity_extraction_with_documents(extraction_columns=[...])
+```
+
+### 3. Two-step: Extract then Normalize
+
+When you need high recall first, then strict formatting.
+
+```
+call_llm(extract) → json_mapper(normalize dates, format phones, dedupe)
+```
+
+### 4. call_llm with Extraction Prompt (Most flexible)
+
+When extraction logic is complex or requires reasoning.
+
+```
+call_llm(prompt="Extract the patient email from this message")
+```
+
+**Validation rule**: For critical fields (emails, phone numbers, order IDs), add deterministic
+validation as a separate step — regex/rules via `rule_validation_with_documents` or `response_validator`.
+
+**Scoping rule**: Pass only the minimum context needed:
+
+- Extracting from current message? Use `trigger.user_query` only
+- Extracting from documents? Use search results or uploaded docs
+- Entity might span multiple turns? Include conversation history
+
+---
+
+## Common Wiring Patterns
+
+### Intent Routing with Shared Search
+
+Search runs once, results shared across all gated respond nodes:
+
+```
+chat_trigger ─┬─→ chat_categorizer
+              │
+              └─→ search ─→ [results shared to all respond nodes]
+                            ├─→ respond_A (runIf: category==A) ─→ WORKFLOW_OUTPUT
+                            ├─→ respond_B (runIf: category==B) ─→ WORKFLOW_OUTPUT
+                            └─→ fallback (runIf: category==Fallback) ─→ WORKFLOW_OUTPUT
+```
+
+**Critical**: ALL respond branches must wire to WORKFLOW_OUTPUT.
+
+### Consolidated Intent Response
+
+Single respond node handles all intents, reducing duplication:
+
+```
+chat_trigger ─┬─→ chat_categorizer ─→ call_llm.named_inputs_Intent
+              ├─→ search ─→ call_llm.named_inputs_Search_Results
+              └─→ call_llm.query
+                  call_llm.response ─→ WORKFLOW_OUTPUT (runIf: != Fallback)
+                  fallback ─→ WORKFLOW_OUTPUT (runIf: == Fallback)
+```
+
+**Use when**: All intents share similar prompts, search sources, and safety constraints.
+
+### Externalized Instructions via KB
+
+Instructions live in uploaded documents, not hardcoded prompts:
+
+```
+Upload: "Scheduling Policy.pdf", "Tone Guide.pdf" to KB
+                                ↓
+chat_trigger → conversation_to_search_query → search → respond_with_sources → WORKFLOW_OUTPUT
+               (converts CHAT_CONVERSATION    (retrieves instructions   (grounded response
+                to TEXT_WITH_SOURCES query)     + knowledge docs)        with citations)
+```
+
+**Benefit**: Change behavior by updating documents, not workflow structure.
+
+---
+
+## Extraction Chain: entity_extraction → json_mapper → fixed_response
+
+When extracting structured data from documents and using it downstream (e.g., sending an email), nodes must be chained in a specific order due to type constraints.
+
+### The Chain
+
+```
+entity_extraction_with_documents → json_mapper → fixed_response → send_email_agent
+         (ANY output)           (field decomposition)  (type conversion)  (TEXT_WITH_SOURCES inputs)
+```
+
+**Why this order?**
+
+1. **entity_extraction** outputs `ANY` type (structured JSON) -- cannot be wired directly to send_email inputs which expect `TEXT_WITH_SOURCES`
+2. **json_mapper** decomposes the structured JSON into individual fields -- still `ANY` type per field
+3. **fixed_response** converts each field to `TEXT_WITH_SOURCES` using template variables (`{{to}}`, `{{subject}}`)
+4. **send_email_agent** receives properly typed `TEXT_WITH_SOURCES` inputs
+
+### Wiring Detail
+
+```
+entity_extraction.extraction_columns → json_mapper.input_json
+json_mapper.output_json → fixed_response_to.named_inputs_Extracted_Data   (template: "{{to}}")
+json_mapper.output_json → fixed_response_subj.named_inputs_Extracted_Data (template: "{{subject}}")
+json_mapper.output_json → fixed_response_body.named_inputs_Extracted_Data (template: "{{body}}")
+fixed_response_to.response → send_email_agent.email_to
+fixed_response_subj.response → send_email_agent.email_subject
+fixed_response_body.response → send_email_agent.email_body
+```
+
+You need one `fixed_response` per email field (to, subject, body).
+
+### When to Use json_mapper vs entity_extraction
+
+| Scenario | Use | Why |
+|---|---|---|
+| Extract from uploaded documents | `entity_extraction_with_documents` | Grounded in source documents, structured schema |
+| Decompose structured JSON into fields | `json_mapper` | Field-level access from ANY-typed data |
+| Extract from conversation text | `call_llm` with extraction prompt | Flexible, handles reasoning |
+| Format fields for typed inputs | `fixed_response` with template | Converts ANY → TEXT_WITH_SOURCES |
+
+### Alternative: custom_agent → json_mapper
+
+When using `custom_agent` instead of `entity_extraction`, you **must** configure `output_fields` or use strict JSON-only prompting. Without this, `custom_agent` returns JSON as a string blob in `response_with_sources`, and `json_mapper` fails to parse it.
+
+**Recommended**: Define `output_fields` on custom_agent (same extraction column format as entity_extraction).
+
+See `ema://rules/json-output-patterns` for the full custom_agent + json_mapper pattern.
+
+---
+
+## Search Configuration
+
+### search/v2 vs search/v0
+
+Always use **search/v2** (not deprecated search/v0). The key difference is `datastore_configs` input.
+
+### datastore_configs Wiring
+
+The `datastore_configs` input connects search to the persona's uploaded data sources via widget configuration:
+
+```json
+"datastore_configs": {
+  "multiBinding": {
+    "elements": [{
+      "widgetConfig": { "widgetName": "fileUpload" }
+    }]
+  }
+}
+```
+
+- `widgetName` maps to the persona widget that holds data sources
+- Default widget: `fileUpload` (standard KB upload widget)
+- For personas with multiple upload widgets: use the specific widget name (e.g., `v822`, `upload1`)
+
+### Search Input Rules
+
+| Input Source | When to Use | Why |
+|---|---|---|
+| `trigger.user_query` | Simple single-turn search | Direct text query |
+| `conversation_to_search_query.summarized_conversation` | Multi-turn chat | Converts conversation history to search-optimized query |
+| `trigger.chat_conversation` | **Never for search** | Wrong type (CHAT_CONVERSATION vs TEXT_WITH_SOURCES) |
+
+### Multi-Source Search
+
+Combine local KB search with web search using `combine_search_results`:
+
+```
+conversation_to_search_query ─┬─→ search (local KB)
+                              └─→ live_web_search (real-time web)
+                                    ├─→ combine_search_results.search_results_1
+                                    └─→ combine_search_results.search_results_2
+                                          → respond_with_sources.search_results
+```
+
+### Critical: Upload Data Before Deploying Search Workflows
+
+Search returns empty results without uploaded documents. Always:
+1. Upload: `persona(id='...', data={method:'upload', path:'/path/to/doc.pdf'})`
+2. Verify: `persona(id='...', data={method:'stats'})` → check `success` count > 0
+3. Then deploy the workflow
+
+---
+
+## LLM Node Configuration (call_llm)
+
+### named_inputs Convention
+
+`call_llm` accepts additional context via `named_inputs` using the suffix pattern `named_inputs_<Descriptive_Name>`:
+
+| Named Input | Type | Purpose |
+|---|---|---|
+| `named_inputs_Search_Results` | SEARCH_RESULT | KB search results for RAG |
+| `named_inputs_Conversation` | CHAT_CONVERSATION | Full conversation history |
+| `named_inputs_Intent` | ENUM | Detected category from categorizer |
+| `named_inputs_Current_Message` | TEXT_WITH_SOURCES | Current user message for extraction |
+| `named_inputs_Tool_Result` | TEXT_WITH_SOURCES | External action output |
+
+`named_inputs` accepts **ANY** type -- this is how you pass CHAT_CONVERSATION and SEARCH_RESULT into LLM nodes.
+
+### Temperature Guidelines
+
+| Use Case | Temperature | Why |
+|---|---|---|
+| Document generation | 0.3-0.5 | Consistent formatting, predictable output |
+| Entity extraction | 0.0-0.3 | Accuracy over creativity |
+| General Q&A / chat | 0.5-0.7 | Balanced creativity and accuracy |
+| Creative writing | 0.7-1.0 | More varied, creative output |
+
+### Avoiding Duplicate LLM Nodes
+
+If multiple `call_llm` nodes share the same inputs (query, search_results, conversation) and differ only by `trigger_when` gate, **consolidate** them:
+
+1. Remove duplicate respond nodes
+2. Create one `call_llm` that always runs (or runs when not Fallback)
+3. Wire `categorizer.category → call_llm.named_inputs_Intent`
+4. Update prompt: "Based on the detected intent ({{Intent}}), respond accordingly"
+5. Wire single `call_llm.response_with_sources → WORKFLOW_OUTPUT`
+
+Keep separate nodes **only** when intents require different tools, search sources, or safety constraints.
+
+### Scoping Extraction Inputs
+
+When using `call_llm` for entity extraction, scope inputs tightly:
+
+- Extracting from current message? → `trigger.user_query` only
+- Extracting from documents? → `search.search_results` (intentional)
+- Entity might span multiple turns? → Include `chat_conversation`
+
+Passing full search_results to extraction prompts causes hallucinated entities from irrelevant context.
+
+---
+
+## Categorizer Patterns
+
+### Basic Rules
+
+- **Input**: `chat_categorizer` MUST receive `chat_conversation` (not `user_query`) for accurate multi-turn classification
+- **Fallback**: ALWAYS include a Fallback category
+- **Handlers**: Every category must have at least one node with a matching `runIf` condition
+- **typeArguments**: Categorizer must have `typeArguments.categories` pointing to the enum type -- empty `typeArguments` causes deploy failure
+
+### runIf Condition Format
+
+```json
+{
+  "lhs": {
+    "actionOutput": { "actionName": "chat_categorizer", "output": "category" },
+    "autoDetectedBinding": false
+  },
+  "operator": 1,
+  "rhs": {
+    "inline": { "enumValue": "Market_Impact" },
+    "autoDetectedBinding": false
+  }
+}
+```
+
+**Important**: Use `category` as the output name and compare to `enumValue` directly. Do NOT use `category_<Name>` format.
+
+### runIf Operator Values
+
+| Operator | Meaning | Use Case |
+|---|---|---|
+| `1` | Equals (`==`) | Route to handler when category matches |
+| `2` | Not equals (`!=`) | Run for all categories except one (e.g., `!= Fallback`) |
+
+For OR conditions (e.g., "run for Sales OR General"), use operator `2` with Fallback: `category != Fallback` -- this runs the node for all non-fallback categories.
+
+### Defining enumTypes
+
+Categories must be defined in the `workflow_def.enumTypes` array:
+
+```json
+"enumTypes": [{
+  "name": { "name": "intent_categories", "namespaces": [] },
+  "options": [
+    { "name": "Sales", "description": "Sales inquiries and product questions" },
+    { "name": "Support", "description": "Technical support and ticket creation" },
+    { "name": "General", "description": "General questions" },
+    { "name": "Fallback", "description": "Unclear or unmatched intents" }
+  ]
+}]
+```
+
+Then the categorizer's `typeArguments` references this enum:
+
+```json
+"typeArguments": {
+  "categories": {
+    "enumType": { "name": { "name": "intent_categories", "namespaces": [] } },
+    "isList": false
+  }
+}
+```
+
+### text_categorizer vs chat_categorizer
+
+| Categorizer | Input Type | When to Use |
+|---|---|---|
+| `chat_categorizer` | CHAT_CONVERSATION | Routing conversations (most common) |
+| `text_categorizer/v1` | named_inputs (multiBinding) | Routing based on text content, not conversation |
+
+`text_categorizer/v0` is deprecated -- use v1 with `named_inputs`.
+
+### Nested Categorizers
+
+For complex routing with sub-intents, chain categorizers:
+
+```
+chat_categorizer (Level 1: HR, IT, General, Fallback)
+  └─→ text_categorizer (Level 2 for HR: Benefits, Leave, Payroll, Fallback)
+```
+
+Use clear precedence -- first categorizer routes broadly, second categorizer handles sub-intent.
+
+---
+
+## Error Handling & Validation Patterns
+
+### response_validator + abstain_action
+
+For guardrails on LLM output:
+
+```
+call_llm.response → response_validator ─→ abstain_action (if validation fails)
+                                        └─→ WORKFLOW_OUTPUT (if validation passes)
+```
+
+- `response_validator` checks generated response against reference query for quality/compliance
+- `abstain_action` provides a safe decline message when AI should not answer
+
+### Graceful Degradation
+
+When search returns no results or external APIs fail:
+
+```
+search → call_llm (runIf: search has results)
+         fixed_response (runIf: search empty) → "I don't have enough information to answer that."
+```
+
+### Choosing the Right Validator
+
+| Validator | Input Type | Use Case |
+|---|---|---|
+| `response_validator` | TEXT_WITH_SOURCES | Validate LLM-generated text (quality, compliance, hallucination) |
+| `rule_validation_with_documents` | ANY | Validate extracted data against business rules (thresholds, required fields) |
+
+For **extraction workflows**, use `rule_validation_with_documents` since it accepts ANY-typed extraction output directly. `response_validator` only works with TEXT_WITH_SOURCES (LLM responses), so you'd need the full intermediary chain (json_mapper → fixed_response) before it.
+
+### rule_validation_with_documents
+
+For business rule compliance checking:
+
+```
+entity_extraction → rule_validation_with_documents → call_llm (summarize results)
+```
+
+Rules are configured in the UI settings panel, not via `workflow_def` inputs.
+
+---
+
+## HITL (Human-in-the-Loop) Patterns
+
+### How HITL Works
+
+HITL is a **flag on specific action nodes**, NOT a standalone workflow node.
+
+```json
+{
+  "name": "send_email",
+  "action": { "name": "send_email_agent" },
+  "disable_human_interaction": false
+}
+```
+
+**Counter-intuitive naming:**
+- `disable_human_interaction: false` → HITL **ON** (requires approval)
+- `disable_human_interaction: true` → HITL **OFF** (auto-proceeds)
+- Omitted → defaults to false (HITL ON)
+
+### When to Enable HITL
+
+| Action | Enable HITL? | Why |
+|---|---|---|
+| `send_email_agent` | Yes, if user requests approval | External communication |
+| `external_action_caller` | Yes, for destructive operations | Side effects (create ticket, update CRM) |
+| `call_llm` | Usually no | No external side effects |
+| `search` | No | Read-only operation |
+
+### Legacy general_hitl Nodes
+
+Existing workflows may have standalone `general_hitl` nodes -- these still function, but **do not add new ones**. Use the flag pattern instead.
+
+---
+
+## Dashboard Output Columns
+
+For dashboard personas, every workflow output mapped in `resultMappings` becomes a column in the dashboard UI.
+
+### resultMappings Example
+
+```json
+"results": {
+  "entity_extraction.recipient_email": {
+    "actionName": "entity_extraction",
+    "outputName": "recipient_email"
+  },
+  "entity_extraction.subject_line": {
+    "actionName": "entity_extraction",
+    "outputName": "subject_line"
+  },
+  "entity_extraction.amount": {
+    "actionName": "entity_extraction",
+    "outputName": "amount"
+  }
+}
+```
+
+Each entry creates one visible dashboard column. The key (e.g., `entity_extraction.recipient_email`) becomes the column display name.
+
+### Key Rules
+
+- **Missing mapping = invisible column**: If you forget to map an output, it won't appear in the dashboard
+- **Column ordering**: Determined by the order of entries in `results` JSON. To reorder: remove all entries, re-add in desired order
+- **Input columns**: Come from `document_trigger` -- `document_content` for files, `row_data` for text/number inputs
+
+### Wiring document_trigger to entity_extraction
+
+```
+document_trigger.document_content → entity_extraction_with_documents.documents
+```
+
+For additional column data from the dashboard row:
+```
+document_trigger.row_data → call_llm.named_inputs_Row_Data
+```
+
+See `.context/public/guides/dashboard-operations.md` for full dashboard column details including nested structures.
+
+## Extraction Column Groups (Nested Structures)
+
+Entity extraction supports grouped/nested columns using `dataType: 5` (OBJECT). A group column has sub-columns defined in `value.objectValue.values`. This appears in the UI as a parent with expandable children.
+
+See `ema://rules/extraction-column-format` for the full API shape including nested examples.
+
+## Anti-Pattern Quick Reference
+
+| Anti-Pattern                     | Symptom                                              | Fix                                                        |
+| -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| Partial output wiring            | Some intents return no response                      | Wire ALL gated respond nodes to WORKFLOW_OUTPUT            |
+| Duplicate identical LLM nodes    | Multiple nodes with same inputs, different gates     | Consolidate to one node + category as named_input          |
+| Overscoped extraction            | Extractions hallucinate entities from search results | Scope to `user_query` only                                 |
+| Hardcoded instructions           | Must redeploy workflow to change behavior            | Upload instructions as KB documents                        |
+| Missing fallback                 | Unrecognized intents silently fail                   | Always include Fallback category                           |
+| Text content as email recipient  | Email sends fail or go to garbage addresses          | Use entity_extraction → json_mapper → fixed_response chain |
+| Missing dashboard output columns | Node output not visible in dashboard                 | Add resultMapping entry for every desired output column    |
+| Wrong column order in dashboard  | Columns appear in unexpected order                   | Remove and re-add resultMappings in desired order          |
+| entity_extraction direct to email | Type mismatch (ANY vs TEXT_WITH_SOURCES)             | Use json_mapper + fixed_response intermediary chain        |
+| json_mapper without upstream data | json_mapper receives no structured input             | Wire from entity_extraction, custom_agent, or other JSON source |
+| Search without uploaded data      | Search returns empty results                         | Upload documents before deploying search workflows         |
+| Redundant search nodes            | Multiple searches with same query                    | Single search node, share results via named_inputs         |
+| Sequential LLM calls              | Unnecessary latency and incoherence                  | Single call_llm with comprehensive instructions            |
+| Categorizer without typeArguments | Deploy failure                                       | Add typeArguments.categories pointing to enumType          |
+
+---
+
+## References
+
+- `src/mcp/domain/validation-rules.ts` — Anti-pattern definitions
+- `src/mcp/domain/structural-rules.ts` — Structural invariants
+- `src/mcp/knowledge.ts` — Workflow patterns and agent catalog
+- `.context/public/guides/email-patterns.md` — Email wiring patterns
+- `.context/public/guides/dashboard-operations.md` — Dashboard-specific patterns