@ema.co/mcp-toolkit 2026.2.23 → 2026.2.24

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/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/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/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)" },
@@ -704,9 +704,9 @@ persona(
                         type: "number",
                         description: "Max results to return (for method=conversations)",
                     },
-                    offset: {
-                        type: "number",
-                        description: "Pagination offset (for method=conversations)",
+                    pagination_token: {
+                        type: "string",
+                        description: "Pagination token from previous response (for method=conversations)",
                     },
                     channel: {
                         type: "string",

package/dist/sdk/generated/api-client/client/client.gen.js

@@ -1,7 +1,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
-import { createSseClient } from '../core/serverSentEvents.gen';
-import { getValidRequestBody } from '../core/utils.gen';
-import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from './utils.gen';
+import { createSseClient } from '../core/serverSentEvents.gen.js';
+import { getValidRequestBody } from '../core/utils.gen.js';
+import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from './utils.gen.js';
 export const createClient = (config = {}) => {
     let _config = mergeConfigs(createConfig(), config);
     const getConfig = () => ({ ..._config });

package/dist/sdk/generated/api-client/client/index.js

@@ -1,6 +1,6 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen';
-export { buildClientParams } from '../core/params.gen';
-export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
-export { createClient } from './client.gen';
-export { createConfig, mergeHeaders } from './utils.gen';
+export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen.js';
+export { buildClientParams } from '../core/params.gen.js';
+export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen.js';
+export { createClient } from './client.gen.js';
+export { createConfig, mergeHeaders } from './utils.gen.js';

package/dist/sdk/generated/api-client/client/utils.gen.js

@@ -1,8 +1,8 @@
 // This file is auto-generated by @hey-api/openapi-ts
-import { getAuthToken } from '../core/auth.gen';
-import { jsonBodySerializer } from '../core/bodySerializer.gen';
-import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from '../core/pathSerializer.gen';
-import { getUrl } from '../core/utils.gen';
+import { getAuthToken } from '../core/auth.gen.js';
+import { jsonBodySerializer } from '../core/bodySerializer.gen.js';
+import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from '../core/pathSerializer.gen.js';
+import { getUrl } from '../core/utils.gen.js';
 export const createQuerySerializer = ({ parameters = {}, ...args } = {}) => {
     const querySerializer = (queryParams) => {
         const search = [];

package/dist/sdk/generated/api-client/client.gen.js

@@ -1,3 +1,3 @@
 // This file is auto-generated by @hey-api/openapi-ts
-import { createClient, createConfig } from './client';
+import { createClient, createConfig } from './client/index.js';
 export const client = createClient(createConfig({ baseUrl: 'https://api.ema.co' }));

package/dist/sdk/generated/api-client/core/utils.gen.js

@@ -1,5 +1,5 @@
 // This file is auto-generated by @hey-api/openapi-ts
-import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from './pathSerializer.gen';
+import { serializeArrayParam, serializeObjectParam, serializePrimitiveParam, } from './pathSerializer.gen.js';
 export const PATH_PARAM_RE = /\{[^{}]+\}/g;
 export const defaultPathSerializer = ({ path, url: _url }) => {
     let url = _url;

package/dist/sdk/generated/api-client/index.js

@@ -1,2 +1,2 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { archiveProjectById, createChatbotConversation, createConversation, createDocument, createPersona, createPersonaTemplate, createProject, createProjectTemplate, deleteConversation, deletePersona, deletePersonaTemplate, deleteProjectTemplate, editChartSnippet, emailActionImage, emailActionLink, emailActionUnsubscribe, fetchTicketUpdates, getChatbotConfig, getChatHistory, getConversationMessages, getConversationMessagesPaginated, getDefaultPersonaTemplateAccessSettingsForTenant, getLinkedInAuthUrl, getLogoUploadUrl, getMailLoginUrlForPersona, getPersonaAccessLevelById, getPersonaById, getPersonaTemplateById, getProjectById, getProjectsForPersona, getProjectTemplateByPersonaId, getWelcomeMessage, grantPersonaTemplateAccess, healthBasicCheck, healthCheck, importPersona, linkedinAccountNotification, linkedinActionLink, listAllPersonaTemplates, listAvailablePhoneNumbers, listConversations, listConversationsForPersona, listConversationsPaginated, listPersonas, listPersonaTemplates, listPersonaTemplatesPost, listSavedSnippets, metrics, processWebPrompt, provisionPhoneNumber, regenerateDocument, retrieveDocument, revokePersonaTemplateAccess, saveSnippet, sendChatMessage, sendChatMessageAsync, setDefaultPersonaTemplateAccessSetting, setPersonaTemplateAccessSettingsForNewSubTenant, streamChatbotConversationsCsv, triggerProjectWorkflow, unsaveSnippet, updateConversationDisplayName, updateDataUploadStatus, updateDocument, updateMessageFeedback, updatePersona, updatePersonaTemplate, updateProject, updateProjectTemplate, uploadLogo, verifyLogoUpload } from './sdk.gen';
+export { archiveProjectById, createChatbotConversation, createConversation, createDocument, createPersona, createPersonaTemplate, createProject, createProjectTemplate, deleteConversation, deletePersona, deletePersonaTemplate, deleteProjectTemplate, editChartSnippet, emailActionImage, emailActionLink, emailActionUnsubscribe, fetchTicketUpdates, getChatbotConfig, getChatHistory, getConversationMessages, getConversationMessagesPaginated, getDefaultPersonaTemplateAccessSettingsForTenant, getLinkedInAuthUrl, getLogoUploadUrl, getMailLoginUrlForPersona, getPersonaAccessLevelById, getPersonaById, getPersonaTemplateById, getProjectById, getProjectsForPersona, getProjectTemplateByPersonaId, getWelcomeMessage, grantPersonaTemplateAccess, healthBasicCheck, healthCheck, importPersona, linkedinAccountNotification, linkedinActionLink, listAllPersonaTemplates, listAvailablePhoneNumbers, listConversations, listConversationsForPersona, listConversationsPaginated, listPersonas, listPersonaTemplates, listPersonaTemplatesPost, listSavedSnippets, metrics, processWebPrompt, provisionPhoneNumber, regenerateDocument, retrieveDocument, revokePersonaTemplateAccess, saveSnippet, sendChatMessage, sendChatMessageAsync, setDefaultPersonaTemplateAccessSetting, setPersonaTemplateAccessSettingsForNewSubTenant, streamChatbotConversationsCsv, triggerProjectWorkflow, unsaveSnippet, updateConversationDisplayName, updateDataUploadStatus, updateDocument, updateMessageFeedback, updatePersona, updatePersonaTemplate, updateProject, updateProjectTemplate, uploadLogo, verifyLogoUpload } from './sdk.gen.js';