@ema.co/mcp-toolkit 2026.2.23-2 → 2026.2.24

package/dist/mcp/demo-generator.js

@@ -301,6 +301,134 @@ export const DEMO_SCENARIOS = {
             },
         ],
     },
+    "finance-dunning": {
+        id: "finance-dunning",
+        name: "Finance Automated Dunning",
+        description: "AR dunning assistant: balance inquiries, payment links, disputes, payment plans, and escalation",
+        persona_types: ["chat", "voice"],
+        tags: ["finance", "ar", "dunning", "collections", "receivables", "billing"],
+        intents: [
+            {
+                name: "balance_inquiry",
+                description: "What do I owe? Current balance and aging",
+                example_questions: ["What's my balance?", "Do I have any overdue invoices?", "What do I owe?"],
+            },
+            {
+                name: "payment_made",
+                description: "Customer says they already paid",
+                example_questions: ["I paid last week", "I already sent the wire", "Check your records"],
+            },
+            {
+                name: "dispute",
+                description: "Dispute invoice or amount",
+                example_questions: ["This invoice is wrong", "We never received that order", "I'm disputing this charge"],
+            },
+            {
+                name: "payment_plan",
+                description: "Request installments or extension",
+                example_questions: ["Can I pay in two installments?", "I need 30 more days", "Can we set up a payment plan?"],
+            },
+            {
+                name: "how_to_pay",
+                description: "How to pay or payment link",
+                example_questions: ["How do I pay?", "Where's the payment link?", "What payment methods do you accept?"],
+            },
+            {
+                name: "escalate",
+                description: "Request to speak to a person",
+                example_questions: ["I want to talk to someone", "Transfer me to collections", "I need to speak to AR"],
+            },
+            {
+                name: "Fallback",
+                description: "Anything else",
+                example_questions: ["What's the weather?", "Tell me about your company"],
+            },
+        ],
+        entities: [
+            {
+                type: "customer",
+                count: 3,
+                template: {
+                    id: "CUST-AR-{{id}}",
+                    name: "{{name}}",
+                    email: "{{email}}",
+                    payment_terms_days: 30,
+                    payment_plan_active: false,
+                },
+            },
+            {
+                type: "invoice",
+                count: 3,
+                template: {
+                    invoice_id: "INV-{{id}}",
+                    customer_id: "CUST-AR-{{cust}}",
+                    amount_due: "{{amount}}",
+                    due_date: "{{due_date}}",
+                    days_past_due: "{{days}}",
+                    dunning_level: "{{level}}",
+                    payment_link: "{{payment_link}}",
+                },
+            },
+            {
+                type: "dunning_policy",
+                count: 1,
+                template: {
+                    reminder_1_days: "1-7",
+                    reminder_2_days: "8-14",
+                    final_notice_days: "15-30",
+                    escalation_days: "31+",
+                    payment_plan_note: "Payment plan requests are reviewed by AR within 1 business day.",
+                },
+            },
+        ],
+        qa_pairs: [
+            {
+                phase: "intro",
+                question: "Hi, I have a question about my invoice.",
+                answer_template: "Hi! I'm here to help with your invoice and payment questions. I can look up your balance, share the payment link, or help with a dispute or payment plan request. What would you like to do?",
+                intent: "balance_inquiry",
+            },
+            {
+                phase: "main",
+                question: "What do I owe?",
+                answer_template: "Your current balance is {{amount_due}} (invoice {{invoice_id}}, due {{due_date}}). You can pay here: {{payment_link}}. If you need a payment plan or have already paid, tell me and I'll help.",
+                intent: "balance_inquiry",
+                required_entity_type: "invoice",
+            },
+            {
+                phase: "main",
+                question: "How do I pay?",
+                answer_template: "You can pay online using this link: {{payment_link}}. We accept major credit cards and ACH. If you've already paid, please have your payment reference or date ready and I can help verify.",
+                intent: "how_to_pay",
+                required_entity_type: "invoice",
+            },
+            {
+                phase: "main",
+                question: "I already paid last week.",
+                answer_template: "Thanks for letting us know. Our AR team will verify the payment. Can you share the payment reference number or the date you paid? We'll follow up if anything doesn't match.",
+                intent: "payment_made",
+            },
+            {
+                phase: "advanced",
+                question: "This invoice is wrong.",
+                answer_template: "I'm sorry to hear that. I'm not able to adjust invoices here. I've escalated this to our AR team—they'll contact you to resolve the dispute. You should hear back within 1 business day.",
+                intent: "dispute",
+            },
+            {
+                phase: "advanced",
+                question: "Can I pay in two installments?",
+                answer_template: "Payment plan requests are reviewed by our AR team. I've submitted your request; someone will get back to you within 1 business day with options.",
+                intent: "payment_plan",
+                required_entity_type: "dunning_policy",
+            },
+            {
+                phase: "closing",
+                question: "I want to talk to someone.",
+                answer_template: "No problem. I've requested that our AR team contact you. You should hear from someone within 1 business day. Is there anything else I can help with in the meantime?",
+                intent: "escalate",
+            },
+        ],
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Sample Entity Data
@@ -473,6 +601,55 @@ export const SAMPLE_ENTITIES = {
             manager: "Bob Director",
         },
     ],
+    invoice: [
+        {
+            id: "INV-2025-001234",
+            invoice_id: "INV-2025-001234",
+            customer_id: "CUST-AR-001",
+            amount_due: 12500.0,
+            currency: "USD",
+            due_date: "2025-01-20",
+            days_past_due: 34,
+            dunning_level: 3,
+            payment_link: "https://pay.example.com/INV-2025-001234",
+            line_items_summary: "Subscription Q1 2025",
+        },
+        {
+            id: "INV-2025-005678",
+            invoice_id: "INV-2025-005678",
+            customer_id: "CUST-AR-002",
+            amount_due: 4850.0,
+            currency: "USD",
+            due_date: "2025-02-01",
+            days_past_due: 22,
+            dunning_level: 3,
+            payment_link: "https://pay.example.com/INV-2025-005678",
+            line_items_summary: "Professional services February 2025",
+        },
+        {
+            id: "INV-2025-009999",
+            invoice_id: "INV-2025-009999",
+            customer_id: "CUST-AR-003",
+            amount_due: 899.0,
+            currency: "USD",
+            due_date: "2025-02-15",
+            days_past_due: 8,
+            dunning_level: 2,
+            payment_link: "https://pay.example.com/INV-2025-009999",
+            line_items_summary: "Monthly license March 2025",
+        },
+    ],
+    dunning_policy: [
+        {
+            id: "dunning-policy",
+            name: "Dunning Policy",
+            reminder_1_days: "1-7",
+            reminder_2_days: "8-14",
+            final_notice_days: "15-30",
+            escalation_days: "31+",
+            payment_plan_note: "Payment plan requests are reviewed by AR within 1 business day. Do not send reminders to customers on active payment plans.",
+        },
+    ],
     benefit: [
         {
             id: "BEN-001",

package/dist/mcp/domain/validation-rules.js

@@ -68,6 +68,19 @@ export const INPUT_SOURCE_RULES = [
         severity: "warning",
         fix: "Use user_query for query, pass chat_conversation via named_inputs if needed",
     },
+    // Rule validation inputs
+    {
+        actionPattern: "rule_validation_with_documents",
+        recommended: "entity_extraction.extraction_columns for map_of_extracted_columns, workflowInput.document for primary_docs",
+        avoid: ["omitting primary_docs", "wiring phases in parallel instead of sequentially"],
+        reason: "rule_validation_with_documents requires both extracted columns and original documents. " +
+            "primary_docs gives the validator context from the original document. " +
+            "When chaining multiple validation phases, wire them sequentially (phase1.ruleset_output → phase2.map_of_extracted_columns) " +
+            "so each phase builds on prior validation results.",
+        severity: "critical",
+        fix: "Wire entity_extraction.extraction_columns → rule_validation.map_of_extracted_columns AND " +
+            "workflowInput.document → rule_validation.primary_docs. For multi-phase: chain sequentially, not in parallel.",
+    },
     // Email-specific rules - GUIDANCE ONLY (not hard backend constraints)
     // NOTE: Backend accepts TEXT_WITH_SOURCES for email_to, so this is soft guidance
     // The correct pattern is: entity_extraction → fixed_response with {{email}} template → send_email

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/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/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

package/dist/mcp/resources-dynamic.js

@@ -1523,8 +1523,13 @@ persona(method="update", id="<ID>", config={widgets: [...]})
 
 ### 6. Upload Knowledge
 \`\`\`
+# Default widget ('fileUpload') — exists on every chat/voice persona
 persona(id="<ID>", data={method:"upload", path:"your-data.txt"})
+
+# Custom widget — auto-created in proto_config on first upload (widget_created: true in response)
+persona(id="<ID>", data={method:"upload", path:"policies.pdf", widget_name:"policies"})
 \`\`\`
+Wire any custom widget to a search node: \`search/v2\` → \`datastore_configs\` → \`widgetConfig: { widgetName: "<widget_name>" }\`.
 
 ## Hard Requirements
 

package/dist/mcp/tools.js

@@ -278,7 +278,7 @@ persona(
                             // Especially important for Document Generation personas with multiple upload widgets
                             widget_name: {
                                 type: "string",
-                                description: "Target widget for upload OR filter for stats. For Document Proposal Manager: 'upload' (Content Repository), 'upload1' (Service Line Docs), 'upload2' (Style Guide). Default: 'fileUpload'. See catalog(type='widgets') for reference."
+                                description: "Target widget for upload OR filter for stats. Default: 'fileUpload'. If the named widget doesn't exist in the persona's proto_config, it is auto-created (type 3, fileUpload). Use a custom name to create a second knowledge base alongside the default one. For Document Proposal Manager: 'upload' (Content Repository), 'upload1' (Service Line Docs), 'upload2' (Style Guide). See catalog(type='widgets') for reference."
                             },
                             // delete params
                             file_id: { type: "string", description: "File/item ID to delete (for method=delete)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.2.23-2",
+  "version": "2026.2.24",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",