@ema.co/mcp-toolkit 2026.2.23 → 2026.2.27

package/dist/mcp/handlers/data/index.js

@@ -191,8 +191,8 @@ export async function handleData(args, client, readFile) {
             }
             if (filePath) {
                 // File upload - use provided readFile or fall back to fs
+                let fileContent;
                 try {
-                    let fileContent;
                     if (readFile) {
                         fileContent = await readFile(filePath);
                     }
@@ -200,25 +200,84 @@ export async function handleData(args, client, readFile) {
                         const fs = await import("fs/promises");
                         fileContent = await fs.readFile(filePath);
                     }
-                    const path = await import("path");
-                    const filename = path.basename(filePath);
-                    const result = await client.uploadDataSource(personaId, fileContent, filename, {
-                        widgetName: widgetName, // Pass through widget_name for doc gen personas
+                }
+                catch (error) {
+                    return { error: `Failed to read file: ${error instanceof Error ? error.message : String(error)}` };
+                }
+                const path = await import("path");
+                const filename = path.basename(filePath);
+                const effectiveWidgetName = widgetName ?? "fileUpload";
+                let result;
+                try {
+                    result = await client.uploadDataSource(personaId, fileContent, filename, {
+                        widgetName: effectiveWidgetName,
                     });
-                    return {
-                        method: "upload",
-                        persona_id: personaId,
-                        path: filePath,
-                        widget_name: widgetName ?? "fileUpload",
-                        ...result,
-                        _warning: "IMPORTANT: Uploaded documents will NOT be used unless your workflow has a search node (search/v2).",
-                        _next_step: `Verify workflow has search: workflow(mode='get', persona_id='${personaId}') → check for search node. If missing, add one.`,
-                        _validation: "Deploy will BLOCK if you have documents but no search node in your workflow.",
-                    };
                 }
                 catch (error) {
                     return { error: `Failed to upload file: ${error instanceof Error ? error.message : String(error)}` };
                 }
+                // Auto-create the widget in proto_config if it doesn't exist yet.
+                // The upload API stores the file under the given widget_name/tags, but the
+                // widget entry in proto_config is what makes it searchable from a workflow.
+                // Flow from HAR: POST /api/v2/upload/files → update_persona adds widget entry.
+                const existingWidgets = (protoConfig?.widgets ?? []);
+                const widgetAlreadyExists = existingWidgets.some(w => w.name === effectiveWidgetName);
+                let widgetCreated = false;
+                if (!widgetAlreadyExists) {
+                    const newWidget = {
+                        name: effectiveWidgetName,
+                        type: 3,
+                        title: effectiveWidgetName,
+                        editable: true,
+                        fileUpload: {
+                            localFiles: [],
+                            tags: [effectiveWidgetName],
+                            useChunking: true,
+                            mergeFiles: [],
+                            transforms: [],
+                            fileTagMappings: [],
+                            acceptedMimeTypes: [],
+                        },
+                        subtitle: "",
+                        required: false,
+                        subProjectType: 0,
+                    };
+                    const updatedProtoConfig = {
+                        ...(protoConfig ?? {}),
+                        widgets: [...existingWidgets, newWidget],
+                    };
+                    try {
+                        await client.updateAiEmployee({
+                            persona_id: personaId,
+                            proto_config: updatedProtoConfig,
+                            workflow: persona?.workflow_def,
+                        });
+                        widgetCreated = true;
+                    }
+                    catch (widgetError) {
+                        return {
+                            method: "upload",
+                            persona_id: personaId,
+                            path: filePath,
+                            uploaded: true,
+                            widget_created: false,
+                            ...result,
+                            error: `File uploaded successfully but widget registration failed: ${widgetError instanceof Error ? widgetError.message : String(widgetError)}`,
+                            _tip: "The file is stored. Retry the upload with the same path — it will re-attempt widget creation.",
+                        };
+                    }
+                }
+                return {
+                    method: "upload",
+                    persona_id: personaId,
+                    path: filePath,
+                    widget_name: effectiveWidgetName,
+                    widget_created: widgetCreated,
+                    ...result,
+                    _warning: "IMPORTANT: Uploaded documents will NOT be used unless your workflow has a search node (search/v2).",
+                    _next_step: `Verify workflow has search: workflow(mode='get', persona_id='${personaId}') → check for search node wired to widget '${effectiveWidgetName}'. If missing, add one.`,
+                    _validation: "Deploy will BLOCK if you have documents but no search node in your workflow.",
+                };
             }
             else if (items && items.length > 0) {
                 // Dashboard row upload (LLM-generated content or file attachments)

package/dist/mcp/handlers/persona/update.js

@@ -412,15 +412,41 @@ export async function handleUpdate(args, client) {
             hint: "Set preview=false to deploy these changes",
         };
     }
+    // Determine the state to set:
+    // - "ready" when deploying a workflow OR when explicitly enabling the persona
+    // - "inactive" when explicitly disabling the persona
+    // This matches the behavior of the Ema frontend
+    let stateToSet;
+    if (args.enabled === true) {
+        stateToSet = "ready";
+    }
+    else if (args.enabled === false) {
+        stateToSet = "inactive";
+    }
+    else if (workflowToSet) {
+        // Deploying a workflow implies activating the persona
+        stateToSet = "ready";
+    }
+    const updateRequest = {
+        persona_id: persona.id,
+        name: args.name,
+        description: args.description,
+        proto_config: mergedProtoConfig,
+        workflow: workflowToSet,
+        enabled_by_user: typeof args.enabled === "boolean" ? args.enabled : undefined,
+        ...(stateToSet ? { state: stateToSet } : {}),
+    };
+    // Debug: log what we're sending
+    console.error("[persona/update] Sending to API:", JSON.stringify({
+        persona_id: updateRequest.persona_id,
+        enabled_by_user: updateRequest.enabled_by_user,
+        state: updateRequest.state,
+        has_workflow: !!updateRequest.workflow,
+        has_proto_config: !!updateRequest.proto_config,
+    }));
     try {
-        await client.updateAiEmployee({
-            persona_id: persona.id,
-            name: args.name,
-            description: args.description,
-            proto_config: mergedProtoConfig,
-            workflow: workflowToSet,
-            enabled_by_user: typeof args.enabled === "boolean" ? args.enabled : undefined,
-        });
+        const apiResponse = await client.updateAiEmployee(updateRequest);
+        console.error("[persona/update] API response:", JSON.stringify(apiResponse));
     }
     catch (apiErr) {
         // Return structured error consistent with other handlers

package/dist/mcp/handlers/reference/index.js

@@ -187,24 +187,23 @@ export async function handleReference(args, context) {
     // type="patterns" - Workflow patterns
     // ─────────────────────────────────────────────────────────────────────────
     if (type === "patterns") {
-        // Get specific pattern
+        // Get specific pattern by name
         if (args.pattern) {
-            const patternName = args.pattern;
-            const pattern = WORKFLOW_PATTERNS[patternName];
+            const pattern = WORKFLOW_PATTERNS.find(p => p.name === args.pattern);
             if (!pattern) {
-                return { error: `Pattern not found: ${args.pattern}` };
+                return { error: `Pattern not found: ${args.pattern}`, available: WORKFLOW_PATTERNS.map(p => p.name) };
             }
             return pattern;
         }
-        // List patterns
-        let patterns = Object.entries(WORKFLOW_PATTERNS);
+        // List patterns (optionally filtered by persona_type)
+        let patterns = [...WORKFLOW_PATTERNS];
         if (args.persona_type) {
-            patterns = patterns.filter(([_, p]) => !p.personaType || p.personaType === args.persona_type);
+            patterns = patterns.filter(p => !p.personaType || p.personaType === args.persona_type);
         }
         return {
             count: patterns.length,
-            patterns: patterns.map(([name, p]) => ({
-                name,
+            patterns: patterns.map(p => ({
+                name: p.name,
                 description: p.description,
                 use_case: p.useCase,
                 persona_type: p.personaType,
@@ -321,8 +320,16 @@ export async function handleReference(args, context) {
                     tags: ["support", "voice", "chat"],
                     description: "Tier 1 customer support automation",
                 },
+                {
+                    id: "finance-dunning",
+                    name: "Finance - Automated Dunning",
+                    domain: "finance",
+                    personas: 2,
+                    tags: ["finance", "ar", "dunning", "collections", "receivables"],
+                    description: "AR dunning assistant: balance inquiries, payment links, disputes, payment plans, escalation.",
+                },
             ],
-            count: 3,
+            count: 4,
             _tip: "Use reference(demo_kit=\"finance-ap\") to get full kit details",
         };
     }
@@ -370,7 +377,23 @@ export async function handleReference(args, context) {
                 _tip: "Use persona(method=\"analyze\", id=\"...\") to analyze each persona's workflow",
             };
         }
-        return { error: `Demo kit not found: ${kitId}`, available: ["finance-ap", "sales-sdr", "support-tier1"] };
+        if (kitId === "finance-dunning") {
+            return {
+                id: "finance-dunning",
+                name: "Finance - Automated Dunning",
+                version: "1.0.0",
+                domain: "finance",
+                tags: ["finance", "ar", "dunning", "collections", "receivables", "billing"],
+                description: "AR dunning assistant: balance inquiries, payment links, disputes, payment plans, escalation. Chat or voice.",
+                intents: ["balance_inquiry", "payment_made", "dispute", "payment_plan", "how_to_pay", "escalate", "Fallback"],
+                persona_types: ["chat", "voice"],
+                demo_script: "docs/demos/finance-dunning.md",
+                design_doc: ".context/core/designs/2026-02-23-finance-automated-dunning.md",
+                scenario_id: "finance-dunning",
+                _tip: "Use demo(mode=\"kit\", persona_id=\"<id>\", scenario=\"finance-dunning\") to generate KB docs and demo script for a dunning persona",
+            };
+        }
+        return { error: `Demo kit not found: ${kitId}`, available: ["finance-ap", "finance-dunning", "sales-sdr", "support-tier1"] };
     }
     // ─────────────────────────────────────────────────────────────────────────
     // tags=true - Get tagging taxonomy

package/dist/mcp/handlers/workflow/adapter.js

@@ -10,6 +10,7 @@ import { fingerprintPersona } from "../../../sync.js";
 import { createVersionStorage } from "../../../sync/version-storage.js";
 import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
 import { handleWorkflow } from "./index.js";
+import { handleWorkflowOptimize } from "./optimize.js";
 export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName) {
     const normalizedArgs = { ...(args ?? {}) };
     const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
@@ -152,21 +153,23 @@ export async function handleWorkflowAdapter(args, createClient, getDefaultEnvNam
             }
             return deployResult;
         }
+        case "optimize": {
+            return handleWorkflowOptimize(normalizedArgs, client);
+        }
         case "analyze":
         case "compare":
         case "compile":
-        case "optimize":
         case "generate": {
             return {
                 error: `Mode "${mode}" removed - LLM does this thinking`,
                 hint: "Use workflow(mode='get') to fetch data, then analyze/generate in your reasoning. Deploy with workflow(mode='deploy').",
-                valid_modes: ["get", "validate", "deploy"],
+                valid_modes: ["get", "validate", "deploy", "optimize"],
             };
         }
         default: {
             return {
-                error: `Mode required. Valid modes: get, validate, deploy`,
-                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def.",
+                error: `Mode required. Valid modes: get, validate, deploy, optimize`,
+                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def. workflow(mode='optimize') runs structural graph optimization.",
                 example: `workflow(mode="get", persona_id="...")`,
             };
         }

package/dist/mcp/handlers/workflow/deploy.js

@@ -233,6 +233,9 @@ export async function handleWorkflowDeploy(args, client) {
             persona_id: personaId,
             workflow: sanitizedWorkflow,
             proto_config: protoConfigToUse,
+            // Set state to "ready" to activate the persona after deployment
+            // This matches the behavior of the Ema frontend
+            state: "ready",
         });
         // ═══════════════════════════════════════════════════════════════════════════
         // CRITICAL: Check for silent deployment failure

package/dist/mcp/handlers/workflow/optimize.js

@@ -64,11 +64,11 @@ export async function handleWorkflowOptimize(args, client) {
         // Core result
         modified: result.modified,
         workflow_def: result.workflowDef,
-        // What was done
+        // What was done (includes pass number and flow_context for each change)
         applied_transforms: result.appliedTransforms.length > 0
             ? result.appliedTransforms
             : undefined,
-        // What the LLM should review
+        // What the LLM should review manually
         advisories: result.advisories.length > 0
             ? result.advisories
             : undefined,
@@ -76,15 +76,19 @@ export async function handleWorkflowOptimize(args, client) {
         metrics: result.metrics,
         // Post-optimization validation
         validation: result.validation,
+        // Compact edge-list of the final workflow (trigger → nodes → outputs)
+        flow_diagram: result.flow_diagram,
         // Guidance
         _tip: result.modified
             ? "Optimization applied transforms. Review the changes, then deploy with: workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={...})"
             : result.advisories.length > 0
                 ? "No auto-transforms applied, but advisories found. Review them and modify the workflow_def manually if needed."
                 : "Workflow is already optimal. No changes needed.",
-        _next_step: result.modified
-            ? "workflow(mode='get', persona_id='...') to get fresh fingerprint, then workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={optimized_workflow_def})"
-            : undefined,
+        _next_step: result.modified && personaId
+            ? `workflow(mode='get', persona_id='${personaId}') to get fresh fingerprint, then workflow(mode='deploy', persona_id='${personaId}', base_fingerprint='<fingerprint>', workflow_def={optimized_workflow_def})`
+            : result.modified
+                ? "Deploy the optimized workflow_def with: workflow(mode='deploy', persona_id='<target>', base_fingerprint='<fingerprint>', workflow_def={optimized_workflow_def})"
+                : undefined,
     };
     return response;
 }

package/dist/mcp/handlers/workflow/validation.js

@@ -14,6 +14,7 @@
  * 2. Semantic validation (logic) - catches wiring/reference errors
  * 3. Best practices (warnings) - non-blocking suggestions
  */
+import { ConnectError, Code } from "@connectrpc/connect";
 import { validateWorkflowDefSchema } from "../../domain/workflow-def-schema.js";
 // Re-export schema validation for use by other handlers
 export { validateWorkflowDefSchema };
@@ -248,6 +249,7 @@ export async function validateSearchDataSourceConsistency(workflowDef, personaId
     // Try to get data source stats for each widget used by search nodes (at least one must have indexed data)
     let dataSourceStats = null;
     let lastError;
+    let isPermissionError = false;
     for (const widgetName of widgetNames) {
         try {
             const stats = await client.getDataSourceAggregates(personaId, widgetName);
@@ -261,13 +263,27 @@ export async function validateSearchDataSourceConsistency(workflowDef, personaId
         }
         catch (err) {
             lastError = err;
+            // Check for permission/auth errors - these should block, not warn
+            if (err instanceof ConnectError) {
+                if (err.code === Code.PermissionDenied || err.code === Code.Unauthenticated) {
+                    isPermissionError = true;
+                }
+            }
         }
     }
-    if (!dataSourceStats && lastError) {
-        console.error(`[validation] Could not verify data sources for ${personaId}`, lastError);
-    }
-    // If we couldn't get stats, allow through but warn (don't block on API errors)
+    // If we couldn't get stats, skip validation with appropriate warning
     if (!dataSourceStats) {
+        if (isPermissionError) {
+            const errorMsg = lastError instanceof ConnectError ? lastError.rawMessage : String(lastError);
+            // Permission to getDataSourceAggregates != permission to updateAiEmployee
+            // Skip validation but warn - don't block activation
+            return {
+                valid: true,
+                _warning: `Could not verify data source consistency - permission denied for data source API (${errorMsg}). Skipping this validation.`,
+                validation_skipped: "search_data_source_consistency_permission",
+            };
+        }
+        // Other errors (network, etc.) - also skip with warning
         return {
             valid: true,
             _warning: "Could not verify data source consistency - API error. Proceed with caution.",

package/dist/mcp/knowledge.js

@@ -183,6 +183,11 @@ export const WORKFLOW_PATTERNS = [
             "respond_for_external_actions.response → WORKFLOW_OUTPUT",
         ],
         useCase: "FAQ bot, documentation assistant, policy lookup",
+        antiPatterns: [
+            "Using call_llm instead of respond_for_external_actions (loses citation and conversation awareness)",
+            "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)",
+        ],
     },
     {
         name: "intent-routing",
@@ -223,6 +228,11 @@ export const WORKFLOW_PATTERNS = [
             "respond_for_external_actions.response → WORKFLOW_OUTPUT",
         ],
         useCase: "Research assistant needing both internal docs and current web info",
+        antiPatterns: [
+            "Using web search as the primary/only data source (slower, less reliable, uncontrolled content)",
+            "Not wiring combine_search_results.combined_results to response node (combined results go unused)",
+            "Forgetting to upload internal KB documents (search returns empty, only web results used)",
+        ],
     },
     {
         name: "tool-calling",
@@ -241,17 +251,20 @@ export const WORKFLOW_PATTERNS = [
         antiPatterns: [
             "Creating duplicate records on follow-up questions",
             "Not checking conversation history before actions",
+            "Forgetting voice-specific widgets (conversationSettings, voiceSettings, callSettings, vadSettings)",
+            "external_action_caller does NOT support HITL — cannot gate tool calls with human approval",
         ],
     },
     {
         name: "hitl-approval",
         personaType: "chat",
         description: "Human-in-the-loop approval — enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL)",
-        nodes: ["chat_trigger", "send_email_agent (with HITL flag)", "respond_for_external_actions"],
+        nodes: ["chat_trigger", "entity_extraction_with_documents", "send_email_agent", "respond_for_external_actions"],
         connections: [
-            "chat_trigger.user_query → external_action_caller.query",
-            "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 → entity_extraction_with_documents.query",
+            "chat_trigger.chat_conversation → entity_extraction_with_documents.conversation",
+            "entity_extraction_with_documents.extraction_columns → send_email_agent (HITL flag enabled: disable_human_interaction: false)",
+            "send_email_agent.confirmation → 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",
@@ -260,6 +273,8 @@ export const WORKFLOW_PATTERNS = [
         antiPatterns: [
             "Adding general_hitl as a standalone node (it is NOT deployable)",
             "Not wiring conversation context to response node",
+            "Using external_action_caller for HITL — it does NOT support the HITL flag",
+            "Only send_email_agent and entity_extraction_with_documents support HITL (disable_human_interaction: false)",
         ],
     },
     {
@@ -272,31 +287,38 @@ export const WORKFLOW_PATTERNS = [
             "entity_extraction_with_documents.extraction_columns → rule_validation_with_documents.map_of_extracted_columns",
             "workflowInput.document-mmf2 → rule_validation_with_documents.primary_docs",
             "rule_validation_with_documents.ruleset_output → call_llm.named_inputs_Validation_Results",
-            "entity_extraction_node.extraction_columns → results (dot-notation key)",
-            "rule_validation_node.ruleset_output → results (dot-notation key)",
-            "call_llm.llm_output → results (dot-notation key)",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+            "rule_validation_with_documents.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
+            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_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 for context)",
+            "Using a single call_llm without passing validation results (analysis lacks validation context)",
+        ],
     },
     {
         name: "dashboard-email-notification",
         personaType: "dashboard",
-        description: "Document upload → extraction → email notification (with intermediary for type conversion)",
-        nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "fixed_response", "send_email_agent", "call_llm"],
+        description: "Document upload → extraction → email notification (with intermediary for type conversion). Production workflows often add a body generator (call_llm/custom_agent) and dual send paths (auto + HITL) with CC config.",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "fixed_response", "call_llm (body generator)", "send_email_agent"],
         connections: [
             "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
             "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
             "json_mapper.output_json → fixed_response.named_inputs_Extracted_Data (template: '{{to}}', '{{subject}}', etc.)",
             "fixed_response.response → send_email_agent.email_to (one fixed_response per email field)",
-            "send_email_agent.confirmation → call_llm.named_inputs_Email_Result",
-            "entity_extraction_node.extraction_columns → results (dot-notation key)",
-            "call_llm.llm_output → results (dot-notation key)",
+            "entity_extraction_with_documents.extraction_columns → call_llm.named_inputs_Extracted_Data (for body generation)",
+            "call_llm.llm_output → send_email_agent.email_body (LLM-generated body)",
+            "send_email_agent.confirmation → results (dot-notation: '<nodeId>.confirmation')",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
         ],
-        useCase: "Invoice receipt notification, contract alerts, document-triggered emails",
+        useCase: "Invoice receipt notification, contract alerts, document-triggered emails, payment confirmations",
         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",
             "Enable HITL flag on send_email_agent (disable_human_interaction: false) if approval needed",
+            "For CC/BCC: extract additional recipients via entity_extraction columns, route through separate fixed_response nodes",
         ],
     },
     {
@@ -314,6 +336,11 @@ export const WORKFLOW_PATTERNS = [
             "response_validator.abstain_reason → [conditional: if invalid] → abstain_action → WORKFLOW_OUTPUT",
         ],
         useCase: "Regulated industries, compliance-sensitive responses",
+        antiPatterns: [
+            "Not connecting both response and abstain paths to WORKFLOW_OUTPUT",
+            "Using guardrails without search results (validator has nothing to check against)",
+            "Skipping the abstain_action fallback (invalid responses return nothing to user)",
+        ],
     },
     {
         name: "externalized-instructions",
@@ -357,6 +384,140 @@ export const WORKFLOW_PATTERNS = [
             "Not gating fallback separately (fixed_response should handle fallback, not the LLM)",
         ],
     },
+    // ─── Composite Dashboard Patterns (from FX2 production analysis) ──────────
+    {
+        name: "multi-phase-validation",
+        personaType: "dashboard",
+        description: "Document upload → extraction → N sequential rule_validation_with_documents phases. Each phase checks a different concern (format → compliance → cross-reference) and feeds its output to the next. All phase outputs mapped to dashboard columns for per-phase visibility.",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_phase_1", "rule_validation_phase_2", "rule_validation_phase_3", "call_llm"],
+        connections: [
+            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → rule_validation_phase_1.map_of_extracted_columns",
+            "workflowInput.document-mmf2 → rule_validation_phase_1.primary_docs",
+            "rule_validation_phase_1.ruleset_output → rule_validation_phase_2.map_of_extracted_columns",
+            "workflowInput.document-mmf2 → rule_validation_phase_2.primary_docs",
+            "rule_validation_phase_2.ruleset_output → rule_validation_phase_3.map_of_extracted_columns",
+            "workflowInput.document-mmf2 → rule_validation_phase_3.primary_docs",
+            "rule_validation_phase_3.ruleset_output → call_llm.named_inputs_Final_Validation",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+            "rule_validation_phase_1.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
+            "rule_validation_phase_2.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
+            "rule_validation_phase_3.ruleset_output → results (dot-notation: '<nodeId>.ruleset_output')",
+            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_output')",
+        ],
+        useCase: "Invoice processing with multi-step validation (format → compliance → PO matching), regulatory document review, dunning letter compliance checks",
+        antiPatterns: [
+            "Running all validation rules in a single phase (loses granularity, hard to debug which phase failed)",
+            "Not passing primary_docs to each validation phase (validator needs original documents for context)",
+            "Forgetting to map intermediate phase outputs to results (dashboard won't show per-phase status)",
+        ],
+    },
+    {
+        name: "confidence-dual-path",
+        personaType: "dashboard",
+        description: "Dashboard: after extraction and validation, fork into AUTO path (send_email_agent without HITL) and ESCALATE path (send_email_agent with HITL enabled). A confidence/risk score from validation determines which path fires via runIf conditions.",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "rule_validation_with_documents", "call_llm (confidence scorer)", "send_email_auto (no HITL)", "send_email_escalate (HITL enabled)"],
+        connections: [
+            "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",
+            "rule_validation_with_documents.ruleset_output → call_llm.named_inputs_Validation_Results",
+            "call_llm.llm_output → send_email_auto (runIf: validation_status == PASS)",
+            "call_llm.llm_output → send_email_escalate (runIf: validation_status != PASS)",
+            "send_email_auto.confirmation → results (dot-notation: '<nodeId>.confirmation')",
+            "send_email_escalate.confirmation → results (dot-notation: '<nodeId>.confirmation')",
+            "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: "AP invoice processing (clean invoices auto-process, exceptions need human review), dunning workflows (high-confidence auto-send, ambiguous escalate), contract approvals",
+        antiPatterns: [
+            "Using a single send_email_agent for both paths (loses ability to gate high-risk sends separately)",
+            "Not having the ESCALATE path (all documents auto-process with no human oversight for edge cases)",
+            "Hardcoding threshold in node config — use validation rules output to drive the routing decision",
+            "Forgetting to use intermediary (json_mapper + fixed_response) between extraction and send_email inputs",
+        ],
+    },
+    {
+        name: "document-intake-resolution",
+        personaType: "dashboard",
+        description: "Dashboard: full document intake pipeline — extract entities → convert/normalize → search knowledge base for matching records → LLM resolves/reconciles against master data. The resolution chain ensures extracted entities are validated against existing records before downstream processing.",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "json_mapper", "search", "call_llm (resolver)"],
+        connections: [
+            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → json_mapper.input_json",
+            "json_mapper.output_json → search.query (lookup extracted entity in KB)",
+            "search.search_results → call_llm.named_inputs_Matching_Records",
+            "entity_extraction_with_documents.extraction_columns → call_llm.named_inputs_Extracted_Data",
+            "call_llm.llm_output → results (dot-notation: '<nodeId>.llm_output' — resolution status + matched record)",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+        ],
+        useCase: "Invoice vendor matching against vendor master, contract party resolution, employee onboarding verification against HR records, PO line-item matching",
+        antiPatterns: [
+            "Skipping the search/resolution step (extracted data goes unvalidated against master data)",
+            "Using entity_extraction output directly as the resolved entity (extraction ≠ resolution)",
+            "Not handling 'no match found' case in the resolver LLM (must surface unresolved items)",
+        ],
+    },
+    {
+        name: "hitl-decision-form",
+        personaType: "dashboard",
+        description: "Dashboard: use entity_extraction_with_documents with HITL flag as a human review/decision form — presenting processed data for human verification or correction before downstream actions. The extraction columns define the form fields the reviewer sees and can modify.",
+        nodes: ["document_trigger", "entity_extraction_with_documents (processing)", "call_llm (prepare review)", "entity_extraction_with_documents (HITL review form)", "send_email_agent"],
+        connections: [
+            "workflowInput.document-mmf2 → entity_extraction_processing.documents",
+            "entity_extraction_processing.extraction_columns → call_llm.named_inputs_Extracted_Data",
+            "call_llm.llm_output → entity_extraction_review.named_inputs_Summary (HITL enabled)",
+            "entity_extraction_review.extraction_columns → send_email_agent (human-verified data)",
+            "entity_extraction_review.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+        ],
+        useCase: "Invoice approval where reviewer corrects extracted amounts before payment, contract review where legal team verifies extracted terms, compliance review with sign-off",
+        antiPatterns: [
+            "Using general_hitl (NOT deployable) — use HITL flag on entity_extraction_with_documents",
+            "Confusing extraction-for-processing with extraction-as-review-form (different roles, different column configs)",
+            "Not passing processed data to the review form's named_inputs (reviewer sees empty form)",
+        ],
+    },
+    {
+        name: "document-generation-pipeline",
+        personaType: "dashboard",
+        description: "Dashboard: generate formatted documents from processed data — extraction → LLM drafts content → generate_document creates formatted output (PDF) → send_email_agent delivers as attachment.",
+        nodes: ["document_trigger", "entity_extraction_with_documents", "call_llm (content drafter)", "generate_document", "send_email_agent"],
+        connections: [
+            "workflowInput.document-mmf2 → entity_extraction_with_documents.documents",
+            "entity_extraction_with_documents.extraction_columns → 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",
+            "send_email_agent.confirmation → results (dot-notation: '<nodeId>.confirmation')",
+            "entity_extraction_with_documents.extraction_columns → results (dot-notation: '<nodeId>.extraction_columns')",
+        ],
+        useCase: "Dunning letter generation, invoice creation from PO data, compliance report generation, customer correspondence, welcome packets",
+        antiPatterns: [
+            "Putting the full template in call_llm instructions (use data source templates for strict regulatory formats)",
+            "Skipping generate_document and sending raw LLM text as attachment (no formatting, no PDF)",
+            "Not including extracted entity data in the LLM's named_inputs (generated document lacks specifics)",
+        ],
+    },
+    // ─── Voice Patterns ──────────────────────────────────────────────────────
+    {
+        name: "voice-kb-search",
+        personaType: "voice",
+        description: "Voice AI with knowledge base search only — no external actions or side effects. Clean 4-node pattern for informational help desks. Requires voice-specific widgets.",
+        nodes: ["chat_trigger", "conversation_to_search_query", "search", "respond_for_external_actions"],
+        connections: [
+            "chat_trigger.chat_conversation → conversation_to_search_query.conversation",
+            "conversation_to_search_query.summarized_conversation → search.query",
+            "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",
+        ],
+        useCase: "FX rate inquiries, policy Q&A hotline, product information line, internal help desk for common questions",
+        antiPatterns: [
+            "Adding external_action_caller when no side effects are needed (over-engineering)",
+            "Using call_llm instead of respond_for_external_actions (loses citation and conversation awareness)",
+            "Forgetting voice-specific widgets (conversationSettings, voiceSettings, callSettings, vadSettings)",
+        ],
+    },
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 // Qualifying Questions