@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/.context/public/guides/ema-user-guide.md

@@ -98,7 +98,7 @@ audience: public
 |------------|---------|
 | `chat_categorizer` | Classifies user intent |
 | `search` | Retrieves relevant documents |
-| `respond_for_external_actions` | Generates answer with citations using search/tool results |
+| `respond_for_external_actions` | Explains external_action_caller results in conversation context |
 | `external_action_caller` | Invokes external APIs/tools |
 | `call_llm` | Custom LLM response generation |
 | `generate_document` | Creates Word/PDF documents |
@@ -661,12 +661,13 @@ outputs:
 Generate answers using LLMs.
 
 ```yaml
-# Response Generation Example
-name: "respond_for_external_actions"
-action: "actions.emainternal.respond_for_external_actions"
+# Response Generation Example (most common: call_llm with named_inputs)
+name: "respond"
+action: "actions.emainternal.call_llm"
 inputs:
   query: "{{trigger.user_query}}"
-  external_action_result: "{{search.search_results}}"
+  named_inputs_Search_Results: "{{search.search_results}}"
+  named_inputs_Conversation: "{{trigger.chat_conversation}}"
   user_instructions: |
     You are an HR assistant. Answer questions using only
     the provided documents. Cite your sources.
@@ -1112,7 +1113,7 @@ When an AI Employee isn't working correctly:
 # Graceful degradation example
 runIf:
   condition: "{{search.search_results.length}} > 0"
-  onTrue: "respond_for_external_actions"
+  onTrue: "respond"
   onFalse: "fallback_response"
 
 # Fallback configuration

package/.context/public/guides/mcp-tools-guide.md

@@ -3,6 +3,7 @@ title: "Ema MCP Tools Guide"
 date: 2026-02-13
 audience: public
 ---
+
 # Ema MCP Tools Guide
 
 This MCP server is intentionally designed for **LLM + agent ergonomics**:
@@ -23,14 +24,14 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). A
 
 ## The tool set (6 public tools)
 
-| Tool | Purpose | Key Parameter |
-|------|---------|---------------|
-| `persona` | AI Employee management (CRUD, data, snapshots, sanitization) | `method` (required) |
-| `catalog` | Browse platform catalog (actions, templates, widgets, voices, patterns, concepts) | `method` + `type` (required) |
-| `workflow` | Get workflow data, validate, deploy LLM-generated workflows, optimize | `mode` (required) |
-| `sync` | Sync personas between environments | `method` (required) |
-| `env` | List available environments | No params |
-| `toolkit_feedback` | Submit feedback about the toolkit | `method` (required) |
+| Tool               | Purpose                                                                           | Key Parameter                |
+| ------------------ | --------------------------------------------------------------------------------- | ---------------------------- |
+| `persona`          | AI Employee management (CRUD, data, snapshots, sanitization)                      | `method` (required)          |
+| `catalog`          | Browse platform catalog (actions, templates, widgets, voices, patterns, concepts) | `method` + `type` (required) |
+| `workflow`         | Get workflow data, validate, deploy LLM-generated workflows, optimize             | `mode` (required)            |
+| `sync`             | Sync personas between environments                                                | `method` (required)          |
+| `env`              | List available environments                                                       | No params                    |
+| `toolkit_feedback` | Submit feedback about the toolkit                                                 | `method` (required)          |
 
 **LLM does all thinking** (analyze, compare, generate). MCP only provides data and executes.
 
@@ -106,6 +107,7 @@ persona(method="create", from="source-id", name="Demo Clone", actions=["standard
 ```
 
 **Available aliases:**
+
 - `"copy-data"` - Copy data from source
 - `"copy-and-sanitize"` - Copy then sanitize
 - `"standard-demo-setup"` - Copy, sanitize, snapshot
@@ -123,6 +125,7 @@ persona(method="sanitize", id="abc", examples=["Acme Corp", "john@example.com"],
 ```
 
 **Sanitization Notes:**
+
 - **Two-step process**: First call returns preview with `items_needing_review` count. Second call applies with `apply=true`
 - **Auto-detects**: emails, phones, SSNs, credit cards (by issuer prefix), API keys, JWTs
 - **NOT detected by default**: UUIDs (typically system IDs like `template_id`, `persona_id`)
@@ -180,6 +183,7 @@ persona(method="restore", id="abc", version="v3")
 Valid methods: `list`, `get`, `create`, `update`, `delete`, `sanitize`, `schema`, `snapshot`, `history`, `restore`
 
 **List/Get:**
+
 ```
 persona(method="list")
 persona(method="list", query="support", status="active")
@@ -189,6 +193,7 @@ persona(method="get", id="abc", include_fingerprint=true)  // for stale-state pr
 ```
 
 **Create:**
+
 ```
 persona(method="create", name="My Bot", type="voice")
 persona(method="create", name="My Bot", from="Voice AI Starter")  // from template
@@ -196,22 +201,26 @@ persona(method="create", name="My Bot", from="source-persona-id")  // clone
 ```
 
 **Update config:**
+
 ```
 persona(method="update", id="abc", base_fingerprint="...", config={widgets: [{...}]})
 ```
 
 **Delete:**
+
 ```
 persona(method="delete", id="abc", confirm=true)
 ```
 
 **Sanitize (two-step process):**
+
 ```
 persona(method="sanitize", id="abc")  // Step 1: Preview - identify PII
 persona(method="sanitize", id="abc", examples=["Acme"], apply=true)  // Step 2: Apply
 ```
 
 **Version management:**
+
 ```
 persona(method="snapshot", id="abc", message="Before update")
 persona(method="history", id="abc")
@@ -219,11 +228,13 @@ persona(method="restore", id="abc", version="v2")
 ```
 
 **Schema:**
+
 ```
 persona(method="schema", id="abc")  // Get input schema (dashboard columns, types)
 ```
 
 **Data sub-resource (requires id):**
+
 ```
 persona(id="abc", data={method:"list"})
 persona(id="abc", data={method:"stats"})
@@ -247,6 +258,7 @@ persona(id="abc", data={method:"search", query:"pricing"})
 > **For other templates:** Call `persona(method="get", id="abc", include_workflow=true)` and inspect `proto_config.widgets[].name` to find the exact widget names.
 
 **Replicate (copy by reference - fast, no file transfer):**
+
 ```
 persona(id="target-id", data={method:"replicate", from:"source-id"})
 persona(id="target-id", data={method:"replicate", from:"source-id", widget_mappings:[{source_widget:"docs", target_widget:"documents"}]})
@@ -336,10 +348,15 @@ Valid methods: `submit`, `list`, `analyze`
 toolkit_feedback(method="submit", category="gap", message="Missing docs on extraction columns")
 toolkit_feedback(method="submit", category="confusion", message="...", tool="workflow")
 toolkit_feedback(method="submit", category="success", message="Workflow deploy guidance was clear")
+toolkit_feedback(method="submit", category="probe_response", message="<answer>", context="<probe.id>")
 toolkit_feedback(method="list")
 toolkit_feedback(method="analyze")
 ```
 
+Tool responses may include a `_probe` field with a targeted question. Respond using `category="probe_response"` with the probe's `id` as `context`.
+
+Feedback is collected locally and periodically uploaded as coalesced digests to improve the toolkit globally. Set `EMA_FEEDBACK_DISABLED=1` to opt out.
+
 ## Resources (read-first)
 
 Start with:
@@ -376,18 +393,21 @@ workflow(mode="deploy", persona_id="abc", base_fingerprint="...", workflow_def={
 3. **NEVER** copy workflow patterns from existing personas (they may use deprecated actions!)
 
 **Correct workflow pattern:**
+
 ```
-chat_trigger -> search/v2 -> respond_for_external_actions -> WORKFLOW_OUTPUT
+chat_trigger -> search/v2 -> call_llm (via named_inputs_Search_Results) -> WORKFLOW_OUTPUT
 ```
 
 **Deprecated (DO NOT USE):**
+
 ```
 search/v0 -> Use search/v2
-respond_with_sources/v0 -> Use respond_for_external_actions
+respond_with_sources/v0 -> Use call_llm with named_inputs (for KB Q&A)
 call_llm/v0 -> Use call_llm/v2
 ```
 
 **Common issues to check when generating:**
+
 - Missing `WORKFLOW_OUTPUT` in results
 - Missing Fallback category in categorizers
 - Orphan nodes not connected to output
@@ -400,13 +420,14 @@ call_llm/v0 -> Use call_llm/v2
 
 HITL is a **flag on specific action nodes**, not a standalone workflow node. Set `disable_human_interaction: false` on the node that needs approval.
 
-| Scenario | Default | How to Add HITL |
-|----------|---------|-----------------|
-| Send email | No HITL | Set `disable_human_interaction: false` on `send_email_agent` node |
-| External API | No HITL | Set `disable_human_interaction: false` on `external_action_caller` node |
-| Create records | No HITL | Set `disable_human_interaction: false` on the action node |
+| Scenario       | Default | How to Add HITL                                                         |
+| -------------- | ------- | ----------------------------------------------------------------------- |
+| Send email     | No HITL | Set `disable_human_interaction: false` on `send_email_agent` node       |
+| External API   | No HITL | Set `disable_human_interaction: false` on `external_action_caller` node |
+| Create records | No HITL | Set `disable_human_interaction: false` on the action node               |
 
 **Counter-intuitive naming:**
+
 - `disable_human_interaction: false` -> HITL **ON** (requires approval)
 - `disable_human_interaction: true` -> HITL **OFF** (auto-proceeds)
 
@@ -419,6 +440,7 @@ HITL is a **flag on specific action nodes**, not a standalone workflow node. Set
 Auto Builder has strict prompt length limits (~2500 chars).
 
 ### Good Prompt Format
+
 ```text
 Voice AI for [use case]. Supports [capabilities].
 
@@ -433,6 +455,7 @@ Rules:
 ```
 
 ### Bad Prompt Format (Times Out)
+
 - Narrative descriptions with multiple paragraphs
 - Example conversations embedded in prompt
 - Prompts > 2500 characters
@@ -441,11 +464,11 @@ Rules:
 
 These tool names still work for backwards compatibility but are not exposed in the tool list. Use the current equivalents instead.
 
-| Deprecated Tool | Use Instead |
-|----------------|-------------|
-| `knowledge` | `persona(id=..., data={method:...})` |
-| `demo` | `persona` + data sub-resource |
-| `data` | `persona(id=..., data={method:...})` |
-| `action` | `catalog(method=..., type="actions")` |
-| `template` | `catalog(method=..., type="templates")` |
-| `reference` | `catalog(method=..., type=...)` |
+| Deprecated Tool | Use Instead                             |
+| --------------- | --------------------------------------- |
+| `knowledge`     | `persona(id=..., data={method:...})`    |
+| `demo`          | `persona` + data sub-resource           |
+| `data`          | `persona(id=..., data={method:...})`    |
+| `action`        | `catalog(method=..., type="actions")`   |
+| `template`      | `catalog(method=..., type="templates")` |
+| `reference`     | `catalog(method=..., type=...)`         |

package/dist/config/index.js

@@ -0,0 +1,11 @@
+/**
+ * Central Configuration — Single Source of Truth
+ *
+ * Declarative workflow patterns and related config data.
+ * TypeScript code imports from this module; docs/rules reference these files.
+ *
+ * Current scope: WORKFLOW_PATTERNS (intent-first workflow shapes).
+ * Action definitions live in src/sdk/generated/agent-catalog.ts.
+ * Future: QUALIFYING_QUESTIONS, COMMON_MISTAKES may migrate here.
+ */
+export { WORKFLOW_PATTERNS } from "./workflow-patterns.js";

package/dist/config/workflow-patterns.js

@@ -0,0 +1,361 @@
+/**
+ * Workflow Patterns — Central Config (SINGLE SOURCE OF TRUTH)
+ *
+ * Intent-first patterns: describe WHAT you want to accomplish, then list
+ * action OPTIONS per stage. Never prescribe a single action for a stage.
+ *
+ * RULES:
+ * - respond_for_external_actions is ONLY for external_action_caller results
+ * - search output can feed ANY downstream node (call_llm, custom_agent, etc.)
+ * - call_llm is the most common post-search node (89% of production personas)
+ * - Production data trumps theoretical patterns
+ *
+ * Referenced by: knowledge.ts, resources-dynamic.ts, CLAUDE.md, SKILL.md
+ * When updating: `npm run build && npm test` — no other files need manual sync.
+ */
+export const WORKFLOW_PATTERNS = [
+    // ─── Chat Patterns ──────────────────────────────────────────────────────
+    {
+        name: "search-and-respond",
+        personaType: "chat",
+        description: "Search knowledge base and respond to the user. The most common chat pattern.",
+        intent: "Look up information in a knowledge base and answer the user's question",
+        shape: [
+            { stage: "trigger", purpose: "Entry point for user message", actionOptions: ["chat_trigger"] },
+            { stage: "refine", purpose: "Convert conversation to search query (optional, for multi-turn)", actionOptions: ["conversation_to_search_query"], notes: "Optional — use when chat_conversation needs to become a focused query" },
+            { stage: "retrieve", purpose: "Search uploaded documents or knowledge base", actionOptions: ["search"], notes: "Single search node handles multiple datastores via datastore_configs" },
+            { stage: "respond", purpose: "Generate response from search results", actionOptions: ["call_llm", "custom_agent", "respond_with_sources", "document_synthesis"], notes: "call_llm with named_inputs_Search_Results is the dominant production pattern (89%). respond_with_sources adds automatic citations. custom_agent for specialized behavior." },
+            { stage: "output", purpose: "Return response to user", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
+            "conversation_to_search_query.summarized_conversation → search.query",
+            "search.search_results → call_llm.named_inputs_Search_Results",
+            "chat_trigger.user_query → call_llm.query",
+            "chat_trigger.chat_conversation → call_llm.named_inputs_Conversation",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "FAQ bot, documentation assistant, policy lookup, knowledge base Q&A",
+        antiPatterns: [
+            "Wiring search.search_results to respond_for_external_actions (that node is only for external_action_caller results)",
+            "Connecting chat_conversation directly to search.query (type mismatch — use conversation_to_search_query)",
+            "Forgetting to upload data sources to the persona (search returns empty results)",
+        ],
+        flexPoints: [
+            "respond stage can be any generation node — choice depends on whether you need citations, custom behavior, or simple LLM response",
+            "refine stage is optional — for single-turn, trigger.user_query can go directly to search.query",
+            "search output can feed ANY downstream node that accepts search_results or named_inputs",
+        ],
+    },
+    {
+        name: "intent-routing",
+        personaType: "chat",
+        description: "Route conversations to different handlers based on intent classification",
+        intent: "Classify what the user wants and route to the appropriate handler",
+        shape: [
+            { stage: "trigger", purpose: "Entry point for user message", actionOptions: ["chat_trigger"] },
+            { stage: "classify", purpose: "Determine user intent", actionOptions: ["chat_categorizer"], notes: "MUST include a Fallback category" },
+            { stage: "handle", purpose: "Process each intent differently", actionOptions: ["call_llm", "search", "external_action_caller", "fixed_response", "custom_agent"], notes: "Each category gets its own handler via runIf conditions" },
+            { stage: "output", purpose: "Return response to user", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "handler_1 (runIf: categorizer.category == Category1)",
+            "handler_2 (runIf: categorizer.category == Category2)",
+            "fallback_response (runIf: categorizer.category == Fallback)",
+            "handler_*.response → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Multi-purpose assistant with distinct capabilities (HR + IT + General)",
+        antiPatterns: [
+            "Missing Fallback category",
+            "Categories without outgoing edges",
+            "Not all paths leading to WORKFLOW_OUTPUT",
+            "Only one gated respond node wired to WORKFLOW_OUTPUT while others are silently lost",
+        ],
+    },
+    {
+        name: "tool-calling",
+        personaType: "chat",
+        description: "Call external tools (APIs) and explain results to user",
+        intent: "Execute actions in external systems and communicate the outcome",
+        shape: [
+            { stage: "trigger", purpose: "Entry point", actionOptions: ["chat_trigger"] },
+            { stage: "classify", purpose: "Route to appropriate tool (optional)", actionOptions: ["chat_categorizer"], notes: "Optional if only one tool" },
+            { stage: "act", purpose: "Call external API", actionOptions: ["external_action_caller"], notes: "Requires tools array configuration" },
+            { stage: "respond", purpose: "Explain tool results to user", actionOptions: ["call_llm", "respond_for_external_actions"], notes: "respond_for_external_actions is designed for this — explaining external tool results. call_llm also works via named_inputs." },
+            { stage: "output", purpose: "Return response", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "external_action_caller (runIf: categorizer.category == <Action>)",
+            "chat_trigger.chat_conversation → external_action_caller.conversation",
+            "external_action_caller.tool_execution_result → call_llm.named_inputs_Tool_Result",
+            "chat_trigger.user_query → call_llm.query",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT",
+        ],
+        useCase: "IT helpdesk with ticketing, CRM operations, customer service with tools",
+        antiPatterns: [
+            "Creating duplicate records on follow-up questions",
+            "Not checking conversation history before actions",
+            "external_action_caller does NOT support HITL — cannot gate tool calls with human approval",
+        ],
+    },
+    {
+        name: "search-then-process",
+        personaType: "chat",
+        description: "Look up context, then use it N ways downstream (extraction, routing, email, doc gen)",
+        intent: "Retrieve relevant context from knowledge base and use it to drive multiple downstream actions",
+        shape: [
+            { stage: "trigger", purpose: "Entry point", actionOptions: ["chat_trigger"] },
+            { stage: "retrieve", purpose: "Get relevant context", actionOptions: ["search", "live_web_search"] },
+            { stage: "reason", purpose: "Process retrieved context with LLM", actionOptions: ["call_llm", "custom_agent"], notes: "LLM acts as intermediary processor, not just responder" },
+            { stage: "act", purpose: "Downstream action based on reasoning", actionOptions: ["entity_extraction_with_documents", "text_categorizer", "external_action_caller", "send_email_agent", "document_synthesis", "generate_document"], notes: "Most common: extraction (65% of multi-hop chains), routing, or action" },
+            { stage: "output", purpose: "Return result", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "search.search_results → call_llm.named_inputs_Context",
+            "call_llm.response_with_sources → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → WORKFLOW_OUTPUT",
+        ],
+        useCase: "Research assistant, data gathering + processing, context-driven automation",
+        flexPoints: [
+            "The 'act' stage can be anything — the search+reason stages provide context for whatever comes next",
+            "Multiple downstream actions can run in parallel or sequence",
+        ],
+    },
+    {
+        name: "consolidated-intent-routing",
+        personaType: "chat",
+        description: "Single respond node handles all intents by receiving the category as a named_input",
+        intent: "Route intents but consolidate response generation into one node to reduce duplication",
+        shape: [
+            { stage: "trigger", purpose: "Entry point", actionOptions: ["chat_trigger"] },
+            { stage: "classify", purpose: "Determine intent", actionOptions: ["chat_categorizer"] },
+            { stage: "retrieve", purpose: "Search (always runs, not gated)", actionOptions: ["search"] },
+            { stage: "respond", purpose: "Single LLM with category as named_input", actionOptions: ["call_llm"], notes: "Pass category as named_inputs_Intent so LLM knows which intent to address" },
+            { stage: "fallback", purpose: "Handle unknown intents", actionOptions: ["fixed_response"] },
+            { stage: "output", purpose: "Return response", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "chat_trigger.chat_conversation → chat_categorizer.conversation",
+            "chat_trigger.user_query → search.query (always runs, not gated)",
+            "chat_categorizer.category → call_llm.named_inputs_Intent",
+            "search.search_results → call_llm.named_inputs_Search_Results",
+            "call_llm.response_with_sources → WORKFLOW_OUTPUT (runIf: category != Fallback)",
+            "fixed_response.response → WORKFLOW_OUTPUT (runIf: category == Fallback)",
+        ],
+        useCase: "Multi-intent assistant where all intents share similar response style and search sources",
+        antiPatterns: [
+            "Using this when intents need different tools or actions (use separate nodes instead)",
+            "Forgetting to pass the category as named_input (LLM won't know which intent to address)",
+        ],
+    },
+    {
+        name: "human-approval",
+        personaType: "chat",
+        description: "Pause workflow for human review/approval before executing side effects",
+        intent: "Get human confirmation or input before performing actions with real-world consequences",
+        shape: [
+            { stage: "trigger", purpose: "Entry point", actionOptions: ["chat_trigger"] },
+            { stage: "prepare", purpose: "Gather context for review", actionOptions: ["search", "call_llm", "entity_extraction_with_documents"] },
+            { stage: "review", purpose: "Human review checkpoint", actionOptions: ["general_hitl"], notes: "Conversational mode: define success/failure criteria. Standard Form: structured approval fields. Custom Form: external approval UI." },
+            { stage: "act-on-success", purpose: "Execute action after approval (runIf: HITL Success)", actionOptions: ["send_email_agent", "external_action_caller", "call_llm"] },
+            { stage: "handle-failure", purpose: "Handle rejection (runIf: HITL Failure)", actionOptions: ["call_llm", "fixed_response"] },
+            { stage: "output", purpose: "Return result", actionOptions: ["WORKFLOW_OUTPUT"] },
+        ],
+        exampleWiring: [
+            "search.search_results → call_llm.named_inputs_Context",
+            "call_llm.response_with_sources → general_hitl.named_inputs_Draft",
+            "chat_trigger.chat_conversation → general_hitl.conversation",
+            "general_hitl → send_email_agent (runIf: status == 'HITL Success')",
+            "general_hitl → fixed_response (runIf: status == 'HITL Failure')",
+        ],
+        useCase: "Email approval before sending, content review, transaction confirmation, data correction",
+        antiPatterns: [
+            "Not defining clear success/failure criteria (categorizer defaults to Continue indefinitely)",
+            "Setting max_exchanges too low for complex reviews (causes premature HITL Failure)",
+            "Not handling the HITL Failure path (user rejection goes nowhere)",
+            "Using send_email_agent's HITL flag when you need dialogue — use general_hitl's Conversational mode instead",
+        ],
+        flexPoints: [
+            "send_email_agent and entity_extraction_with_documents also have built-in HITL flags (simpler yes/no)",
+            "general_hitl Conversational mode allows multi-turn dialogue with the reviewer",
+            "Standard Form mode collects structured data without needing entity_extraction",
+        ],
+    },
+    // ─── Dashboard Patterns ─────────────────────────────────────────────────
+    {
+        name: "document-processing",
+        personaType: "dashboard",
+        description: "Document upload, extraction, validation, and analysis (results as dashboard columns)",
+        intent: "Extract structured data from uploaded documents and optionally validate it",
+        shape: [
+            { stage: "trigger", purpose: "Document upload triggers workflow", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract structured data", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "validate", purpose: "Validate against business rules (optional)", actionOptions: ["rule_validation_with_documents"], notes: "Rules configured in UI, not workflow_def" },
+            { stage: "analyze", purpose: "Additional LLM analysis (optional)", actionOptions: ["call_llm", "custom_agent"] },
+            { stage: "results", purpose: "Map outputs to dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → rule_validation_with_documents.map_of_extracted_columns",
+            "workflowInput.document-mmf2 → rule_validation_with_documents.primary_docs",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+            "rule_validation_with_documents.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
+        ],
+        useCase: "Invoice processing, contract analysis, compliance checking",
+        antiPatterns: [
+            "Not mapping extraction/validation outputs to results (dashboard columns won't appear)",
+            "Missing primary_docs on rule_validation_with_documents (validator needs original documents)",
+        ],
+    },
+    {
+        name: "dashboard-email-notification",
+        personaType: "dashboard",
+        description: "Extract data from documents and send email notifications with type conversion intermediaries",
+        intent: "Process uploaded documents and send email alerts based on extracted data",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract structured data", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "convert", purpose: "Convert extracted data to email-compatible types", actionOptions: ["json_mapper", "fixed_response"], notes: "Type intermediary: entity_extraction outputs ANY, email requires TEXT_WITH_SOURCES" },
+            { stage: "compose", purpose: "Generate email body (optional)", actionOptions: ["call_llm", "custom_agent", "fixed_response"] },
+            { stage: "send", purpose: "Send email", actionOptions: ["send_email_agent"], notes: "Enable HITL flag if approval needed" },
+            { stage: "results", purpose: "Map to dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
+            "json_mapper.output_json → fixed_response.named_inputs_Extracted_Data",
+            "fixed_response.response → send_email_agent.email_to",
+            "call_llm.llm_output → send_email_agent.email_body",
+        ],
+        useCase: "Invoice receipt notification, contract alerts, document-triggered emails",
+        antiPatterns: [
+            "DO NOT wire entity_extraction directly to send_email — type mismatch (ANY vs TEXT_WITH_SOURCES)",
+            "Use json_mapper + fixed_response as intermediary for type conversion",
+        ],
+    },
+    {
+        name: "multi-phase-validation",
+        personaType: "dashboard",
+        description: "Sequential validation phases on extracted data, each checking a different concern",
+        intent: "Apply multiple layers of validation rules to extracted document data",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract entities", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "validate-n", purpose: "Sequential validation phases", actionOptions: ["rule_validation_with_documents"], notes: "Each phase checks a different concern (format → compliance → cross-reference)" },
+            { stage: "summarize", purpose: "Final analysis", actionOptions: ["call_llm"] },
+            { stage: "results", purpose: "Per-phase dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "entity_extraction → validation_phase_1 → validation_phase_2 → validation_phase_3 → call_llm",
+            "Each phase: .ruleset_output → next_phase.map_of_extracted_columns",
+            "All phases: .ruleset_output → results (dot-notation)",
+        ],
+        useCase: "Invoice processing with multi-step validation, regulatory document review",
+        antiPatterns: [
+            "Running all rules in a single phase (loses granularity)",
+            "Not passing primary_docs to each validation phase",
+        ],
+    },
+    {
+        name: "confidence-dual-path",
+        personaType: "dashboard",
+        description: "Fork into auto-process and escalate paths based on confidence/risk score",
+        intent: "Automatically handle high-confidence items while escalating uncertain ones for human review",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract data", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "validate", purpose: "Score confidence", actionOptions: ["rule_validation_with_documents", "call_llm"] },
+            { stage: "auto-path", purpose: "Process high-confidence items", actionOptions: ["send_email_agent"], notes: "No HITL, runs automatically" },
+            { stage: "escalate-path", purpose: "Route low-confidence for review", actionOptions: ["send_email_agent"], notes: "HITL enabled (disable_human_interaction: false)" },
+            { stage: "results", purpose: "Dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "call_llm.llm_output → send_email_auto (runIf: validation_status == PASS)",
+            "call_llm.llm_output → send_email_escalate (runIf: validation_status != PASS)",
+        ],
+        useCase: "AP invoice processing, dunning workflows, contract approvals",
+        antiPatterns: [
+            "Using a single send_email for both paths (loses ability to gate high-risk sends)",
+            "Hardcoding threshold — use validation rules output to drive routing",
+        ],
+    },
+    {
+        name: "document-intake-resolution",
+        personaType: "dashboard",
+        description: "Extract entities, search for matching records in KB, resolve/reconcile with master data",
+        intent: "Validate extracted entities against existing records before downstream processing",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract entities", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "convert", purpose: "Normalize for search", actionOptions: ["json_mapper"] },
+            { stage: "lookup", purpose: "Find matching records", actionOptions: ["search"] },
+            { stage: "resolve", purpose: "Reconcile extracted vs master data", actionOptions: ["call_llm", "custom_agent"] },
+            { stage: "results", purpose: "Resolution status + matched record", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "entity_extraction → json_mapper → search.query",
+            "search.search_results → call_llm.named_inputs_Matching_Records",
+            "entity_extraction.extraction_columns → call_llm.named_inputs_Extracted_Data",
+        ],
+        useCase: "Invoice vendor matching, contract party resolution, employee verification against HR records",
+        antiPatterns: [
+            "Skipping the search/resolution step (extracted data goes unvalidated)",
+            "Not handling 'no match found' case in resolver LLM",
+        ],
+    },
+    {
+        name: "hitl-decision-form",
+        personaType: "dashboard",
+        description: "Present processed data as a human review form before downstream actions",
+        intent: "Get human verification or correction of extracted data before acting on it",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Initial data extraction", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "prepare", purpose: "Prepare data for review", actionOptions: ["call_llm", "custom_agent"] },
+            { stage: "review", purpose: "Human review / approval", actionOptions: ["general_hitl", "entity_extraction_with_documents"], notes: "general_hitl (Human Collaboration Agent): Conversational mode for dialogue-based approval, Standard Form for structured fields, Custom Form for external URL. entity_extraction_with_documents with HITL flag: columns define editable form fields." },
+            { stage: "act", purpose: "Act on reviewed data (branch on HITL Success/Failure)", actionOptions: ["send_email_agent", "external_action_caller", "call_llm"] },
+            { stage: "results", purpose: "Dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "entity_extraction_processing → call_llm → general_hitl.named_inputs_Summary",
+            "general_hitl.human_collaboration_status → send_email (runIf: status == 'HITL Success')",
+            "general_hitl.summarized_conversation → call_llm.named_inputs_Review_Notes",
+        ],
+        useCase: "Invoice approval, contract review, compliance sign-off, content approval",
+        antiPatterns: [
+            "Not passing processed data to review node's named_inputs (reviewer sees no context)",
+            "Forgetting to handle HITL Failure path (rejected items should be logged or routed)",
+        ],
+    },
+    {
+        name: "document-generation-pipeline",
+        personaType: "dashboard",
+        description: "Generate formatted documents from processed data and optionally deliver via email",
+        intent: "Create professional documents (PDF/DOCX) from extracted data and deliver them",
+        shape: [
+            { stage: "trigger", purpose: "Document upload", actionOptions: ["document_trigger"] },
+            { stage: "extract", purpose: "Extract data", actionOptions: ["entity_extraction_with_documents"] },
+            { stage: "draft", purpose: "Generate content with LLM", actionOptions: ["call_llm", "custom_agent"] },
+            { stage: "format", purpose: "Convert to formatted document", actionOptions: ["generate_document"] },
+            { stage: "deliver", purpose: "Send via email (optional)", actionOptions: ["send_email_agent"], notes: "Use named_inputs for DOCUMENT type attachments" },
+            { stage: "results", purpose: "Dashboard columns", actionOptions: ["results (dot-notation)"] },
+        ],
+        exampleWiring: [
+            "entity_extraction → call_llm.named_inputs_Extracted_Data",
+            "call_llm.llm_output → generate_document.markdown_file_contents",
+            "generate_document.document_link → send_email_agent.named_inputs_Attachment",
+        ],
+        useCase: "Dunning letter generation, invoice creation, compliance reports, customer correspondence",
+        antiPatterns: [
+            "Skipping generate_document and sending raw LLM text (no formatting, no PDF)",
+            "Putting full template in call_llm instructions (use data source templates for regulatory formats)",
+        ],
+    },
+    // ─── Voice Patterns ─────────────────────────────────────────────────────
+    // Voice patterns share the same shapes as chat patterns but with voice_trigger
+    // and voice-specific widget requirements (conversationSettings, voiceSettings, etc.)
+    // Rather than duplicating patterns, note that any chat pattern can be adapted for
+    // voice by: (1) using voice_trigger, (2) adding voice widgets, (3) keeping response
+    // latency low (avoid long chains).
+];

package/dist/mcp/autobuilder.js

@@ -268,13 +268,13 @@ export function generateAutobuilderPrompt(description, personaType) {
             prompt += "- Use chat_categorizer with Fallback category\n";
         }
         if (hasKBSearch) {
-            prompt += "- Use search for KB, respond_with_sources for answers\n";
+            prompt += "- Use search for KB, call_llm with named_inputs_Search_Results for answers\n";
         }
         if (hasExternalAction && !hasHITL) {
             prompt += "- Use external_action_caller or send_email_agent as needed\n";
         }
         if (hasHITL) {
-            prompt += "- Enable HITL flag on agents that need approval (do NOT add standalone general_hitl nodes)\n";
+            prompt += "- For simple approval: enable HITL flag on send_email_agent/entity_extraction_with_documents. For rich dialogue: use general_hitl (Human Collaboration Agent)\n";
         }
         prompt += `- ${config.outputNote}\n`;
     }