@ema.co/mcp-toolkit 2026.1.26-4 → 2026.1.27

package/dist/sdk/workflow-fixer.js

@@ -1,379 +1,48 @@
 /**
  * Workflow Fixer (SDK)
  *
- * Self-contained auto-detection and fixing of workflow issues.
- * Call autoFixWorkflow() with just a workflow_def for one-call fixing.
+ * DEPRECATED: This module used detectWorkflowIssues which has been removed.
  *
- * Automatically fixes:
- * - Orphan node removal
- * - Email recipient rewiring to entity_extraction
- * - Missing fallback addition
- * - Multiple responder detection
- * - Ungated responder detection
+ * The LLM should analyze workflows using rules from:
+ * - ema://rules/anti-patterns
+ * - ema://rules/input-sources
+ * - ema://rules/optimizations
  *
- * NOTE: This is DIFFERENT from server.ts applyWorkflowFixes():
+ * And then make structured modifications via:
+ * - workflow(mode="deploy", workflow_def={...})
+ * - persona(mode="update", operations=[...])
  *
- * - autoFixWorkflow() (HERE): Self-contained, auto-detects issues, no persona
- *   context needed. Best for SDK consumers who want autonomous fixing.
- *
- * - applyWorkflowFixes() (MCP): Takes pre-detected issues AND persona for
- *   Voice AI specific fixes (results mapping, HITL paths). Used by MCP handlers.
- *
- * These are COMPLEMENTARY, not duplicates. Use autoFixWorkflow() for SDK usage,
- * use applyWorkflowFixes() when you have persona context and pre-analyzed issues.
+ * This file is kept for backwards compatibility with minimal functionality.
  */
-import { detectWorkflowIssues } from "./knowledge.js";
-import { detectMultipleResponders } from "./workflow-execution-analyzer.js";
 // ═══════════════════════════════════════════════════════════════════════════
-// FIX FUNCTIONS
+// DEPRECATED FUNCTIONS (no-ops)
 // ═══════════════════════════════════════════════════════════════════════════
 /**
- * Remove orphan nodes (respecting protected nodes used by other fixes)
- */
-function fixOrphanNodes(workflowDef, issues, protectedNodes) {
-    const fixes = [];
-    const orphanIssues = issues.filter(i => i.type === 'orphan');
-    if (orphanIssues.length === 0)
-        return { def: workflowDef, fixes };
-    // Get actions array (Ema format)
-    const actions = (workflowDef.actions || workflowDef.nodes || []);
-    const nodesToRemove = new Set();
-    for (const issue of orphanIssues) {
-        const nodeName = issue.node;
-        if (!nodeName)
-            continue;
-        if (protectedNodes.has(nodeName)) {
-            fixes.push({
-                applied: false,
-                issueType: 'orphan',
-                nodeName,
-                description: `Skipped - node used by another fix`,
-            });
-            continue;
-        }
-        nodesToRemove.add(nodeName);
-        fixes.push({
-            applied: true,
-            issueType: 'orphan',
-            nodeName,
-            description: `Removed orphan node "${nodeName}"`,
-            change: 'removed',
-        });
-    }
-    const filteredActions = actions.filter((a) => {
-        const action = a;
-        return !nodesToRemove.has(action.name || '');
-    });
-    const key = workflowDef.actions ? 'actions' : 'nodes';
-    return {
-        def: { ...workflowDef, [key]: filteredActions },
-        fixes,
-    };
-}
-/**
- * Generate a unique node ID with random suffix
- */
-function generateNodeId(prefix) {
-    const suffix = Math.random().toString(36).substring(2, 8);
-    return `${prefix}_${suffix}`;
-}
-/**
- * Create a convert_to_text action node
- * This bridges EXTRACTION_COLUMN → TEXT_WITH_SOURCES
- */
-function createConvertToTextNode(nodeId, sourceActionName, sourceOutput, displayName) {
-    return {
-        name: nodeId,
-        action: {
-            name: { namespaces: ['actions', 'emainternal'], name: 'convert_to_text' },
-            version: 'v0',
-        },
-        inputs: {
-            named_inputs: {
-                inline: {
-                    array: {
-                        values: [{
-                                named: {
-                                    name: 'email_address',
-                                    value: {
-                                        actionOutput: {
-                                            actionName: sourceActionName,
-                                            output: sourceOutput,
-                                        },
-                                    },
-                                    description: 'Email address from entity extraction',
-                                },
-                            }],
-                    },
-                },
-            },
-        },
-        displaySettings: {
-            displayName,
-            description: 'Convert extraction output to text for email',
-            coordinates: { x: 600, y: 300 },
-            showConfig: 0,
-        },
-        typeArguments: {},
-        tools: [],
-        disableHumanInteraction: true,
-    };
-}
-/**
- * Find email column name from entity_extraction node configuration
- */
-function findEmailColumnName(extractionNode) {
-    const inputs = extractionNode.inputs;
-    if (!inputs)
-        return undefined;
-    const extractionColumnsInput = inputs.extraction_columns;
-    const columns = extractionColumnsInput?.inline?.array?.values || [];
-    for (const col of columns) {
-        const name = col.wellKnown?.extractionColumn?.name?.toLowerCase() || '';
-        if (name.includes('email') || name.includes('mail')) {
-            return col.wellKnown?.extractionColumn?.name;
-        }
-    }
-    return undefined;
-}
-/**
- * Fix wrong email recipient sources by inserting convert_to_text nodes
+ * DEPRECATED: Auto-fix workflow issues.
+ *
+ * This function now returns the workflow unchanged with a deprecation warning.
+ * Use LLM analysis with ema://rules/* instead.
  */
-function fixWrongInputSource(workflowDef, issues) {
-    const fixes = [];
-    const usedNodes = new Set();
-    const wrongInputIssues = issues.filter(i => i.type === 'wrong_input_source');
-    if (wrongInputIssues.length === 0)
-        return { def: workflowDef, fixes, usedNodes };
-    const actionsSource = workflowDef.actions || workflowDef.nodes || [];
-    const actions = (Array.isArray(actionsSource) ? [...actionsSource] : []);
-    const newNodes = [];
-    // Find entity extraction nodes
-    const entityExtractionNodes = actions.filter((a) => {
-        const action = a;
-        return action.action?.name?.name === 'entity_extraction' ||
-            action.action?.name?.name === 'entity_extraction_with_documents';
-    });
-    const entityExtractionNodeNames = entityExtractionNodes
-        .map((a) => a.name)
-        .filter(Boolean);
-    if (entityExtractionNodeNames.length === 0) {
-        fixes.push({
-            applied: false,
-            issueType: 'wrong_input_source',
-            nodeName: 'N/A',
-            description: `No entity_extraction node found to rewire email to`,
-        });
-        return { def: workflowDef, fixes, usedNodes };
-    }
-    // Track which convert_to_text nodes we've created (to reuse for same source)
-    const converterNodes = new Map(); // "source.output" -> converterId
-    const updatedActions = actions.map((a) => {
-        const action = a;
-        const nodeIssue = wrongInputIssues.find(i => i.node === action.name);
-        if (!nodeIssue)
-            return a;
-        const isEmailNode = ['send_email_agent', 'send_communications_handler'].includes(action.action?.name?.name || '');
-        if (!isEmailNode)
-            return a;
-        const inputs = { ...action.inputs };
-        let anyFixed = false;
-        for (const [inputName, binding] of Object.entries(inputs)) {
-            if (!['to_email', 'email_to', 'recipient'].includes(inputName.toLowerCase()))
-                continue;
-            const b = binding;
-            if (!b.actionOutput?.actionName)
-                continue;
-            const targetExtractionName = entityExtractionNodeNames[0];
-            const targetExtractionNode = entityExtractionNodes.find((n) => n.name === targetExtractionName);
-            // Find the email column name from the extraction node config
-            const emailColumnName = findEmailColumnName(targetExtractionNode) || 'Email';
-            // Create or reuse a convert_to_text node
-            const converterKey = `${targetExtractionName}.${emailColumnName}`;
-            let converterId = converterNodes.get(converterKey);
-            if (!converterId) {
-                converterId = generateNodeId('convert_email');
-                converterNodes.set(converterKey, converterId);
-                // Create the new convert_to_text node
-                const converterNode = createConvertToTextNode(converterId, targetExtractionName, emailColumnName, `Convert ${emailColumnName} to Text`);
-                newNodes.push(converterNode);
-            }
-            // Rewire the email input to use the converter's output
-            inputs[inputName] = {
-                actionOutput: {
-                    actionName: converterId,
-                    output: 'text_with_sources',
-                },
-            };
-            usedNodes.add(targetExtractionName);
-            anyFixed = true;
-            fixes.push({
-                applied: true,
-                issueType: 'wrong_input_source',
-                nodeName: action.name || '',
-                description: `Inserted convert_to_text node and rewired ${inputName}`,
-                change: `${targetExtractionName}.${emailColumnName} → ${converterId} → ${action.name}.${inputName}`,
-            });
-        }
-        if (!anyFixed && Object.keys(inputs).length > 0) {
-            // Only report if we couldn't find any email inputs to fix
-            const emailInputs = Object.keys(inputs).filter(k => ['to_email', 'email_to', 'recipient'].includes(k.toLowerCase()));
-            if (emailInputs.length === 0) {
-                fixes.push({
-                    applied: false,
-                    issueType: 'wrong_input_source',
-                    nodeName: action.name || '',
-                    description: `No standard email input field found to rewire`,
-                });
-            }
-        }
-        return { ...action, inputs };
-    });
-    // Add the new converter nodes to the workflow
-    const allActions = [...updatedActions, ...newNodes];
-    const key = workflowDef.actions ? 'actions' : 'nodes';
+export function autoFixWorkflow(workflowDef) {
     return {
-        def: { ...workflowDef, [key]: allActions },
-        fixes,
-        usedNodes,
+        workflowDef: workflowDef,
+        fixesApplied: [],
+        success: true,
+        warnings: [
+            "DEPRECATED: autoFixWorkflow() no longer auto-fixes issues.",
+            "Use LLM analysis with ema://rules/anti-patterns instead.",
+        ],
     };
 }
 /**
- * Add fallback category to categorizers missing one
- */
-function fixMissingFallback(workflowDef, issues) {
-    const fixes = [];
-    const fallbackIssues = issues.filter(i => i.type === 'missing_fallback');
-    if (fallbackIssues.length === 0)
-        return { def: workflowDef, fixes };
-    const actions = (workflowDef.actions || workflowDef.nodes || []);
-    for (const issue of fallbackIssues) {
-        const categorizer = actions.find((a) => a.name === issue.node);
-        if (!categorizer?.action?.typeArguments?.categories)
-            continue;
-        const categories = categorizer.action.typeArguments.categories;
-        if (categories.some(c => c.toLowerCase() === 'fallback' || c.toLowerCase() === 'other')) {
-            continue;
-        }
-        categorizer.action.typeArguments.categories = [...categories, 'Fallback'];
-        fixes.push({
-            applied: true,
-            issueType: 'missing_fallback',
-            nodeName: issue.node || '',
-            description: `Added "Fallback" category`,
-            change: `categories += "Fallback"`,
-        });
-    }
-    return { def: workflowDef, fixes };
-}
-/**
- * NEW: Fix ungated responders by adding runIf conditions
+ * DEPRECATED: Suggest fixes for workflow issues.
+ *
+ * This function now returns empty results with a deprecation warning.
+ * Use LLM analysis with ema://rules/* instead.
  */
-function fixUngatedResponders(workflowDef, multiResponderIssues) {
-    const fixes = [];
-    const ungatedIssues = multiResponderIssues.filter(i => i.type === 'ungated_responder');
-    if (ungatedIssues.length === 0)
-        return { def: workflowDef, fixes };
-    const actions = (workflowDef.actions || workflowDef.nodes || []);
-    // Find categorizer to use for gating
-    const categorizer = actions.find((a) => {
-        const action = a;
-        return action.action?.name?.name === 'chat_categorizer';
-    });
-    if (!categorizer) {
-        fixes.push({
-            applied: false,
-            issueType: 'ungated_responder',
-            nodeName: 'N/A',
-            description: `No categorizer found to add gating condition from`,
-        });
-        return { def: workflowDef, fixes };
-    }
-    // For now, just report what SHOULD be done
-    for (const issue of ungatedIssues) {
-        for (const nodeId of issue.nodes) {
-            fixes.push({
-                applied: false, // Manual fix recommended
-                issueType: 'ungated_responder',
-                nodeName: nodeId,
-                description: `Should add runIf condition from "${categorizer.name}"`,
-                change: `Add: runIf: { enum: { enumType: "category", enumValue: "<specific_category>" } }`,
-            });
-        }
-    }
-    return { def: workflowDef, fixes };
-}
-// ═══════════════════════════════════════════════════════════════════════════
-// MAIN AUTO-FIX FUNCTION
-// ═══════════════════════════════════════════════════════════════════════════
-export function autoFixWorkflow(workflowDef) {
-    const def = workflowDef;
-    const originalIssues = detectWorkflowIssues(workflowDef);
-    const multiResponderIssues = detectMultipleResponders(workflowDef);
-    const originalIssueCount = originalIssues.length + multiResponderIssues.length;
-    const allFixes = [];
-    const warnings = [];
-    let currentDef = { ...def };
-    // 1. Fix wrong input sources first (protects nodes)
-    const inputSourceResult = fixWrongInputSource(currentDef, originalIssues);
-    currentDef = inputSourceResult.def;
-    allFixes.push(...inputSourceResult.fixes);
-    const protectedNodes = inputSourceResult.usedNodes;
-    // 2. Fix missing fallback
-    const fallbackResult = fixMissingFallback(currentDef, originalIssues);
-    currentDef = fallbackResult.def;
-    allFixes.push(...fallbackResult.fixes);
-    // 3. Fix orphan nodes (respecting protected)
-    const orphanResult = fixOrphanNodes(currentDef, originalIssues, protectedNodes);
-    currentDef = orphanResult.def;
-    allFixes.push(...orphanResult.fixes);
-    // 4. NEW: Report ungated responder fixes needed
-    const ungatedResult = fixUngatedResponders(currentDef, multiResponderIssues);
-    const multipleResponderFixes = ungatedResult.fixes;
-    // Re-detect remaining issues
-    const remainingIssues = detectWorkflowIssues(currentDef);
-    const remainingMultiResponder = detectMultipleResponders(currentDef);
-    const remainingIssueCount = remainingIssues.length + remainingMultiResponder.length;
-    const appliedCount = allFixes.filter(f => f.applied).length;
-    if (multipleResponderFixes.length > 0) {
-        warnings.push(`${multipleResponderFixes.length} ungated responder(s) need manual gating to prevent duplicate responses`);
-    }
+export function suggestFixes(_workflowDef) {
     return {
-        originalIssueCount,
-        fixesApplied: allFixes,
-        remainingIssueCount,
-        workflowDef: currentDef,
-        success: appliedCount > 0,
-        warnings,
-        multipleResponderFixes,
+        standardFixes: [],
+        multiResponderFixes: [],
     };
 }
-/**
- * Suggest fixes without applying (dry run)
- */
-export function suggestFixes(workflowDef) {
-    const issues = detectWorkflowIssues(workflowDef);
-    const multiResponderIssues = detectMultipleResponders(workflowDef);
-    const standardFixes = [];
-    const multiResponderFixes = [];
-    for (const issue of issues) {
-        if (!issue.auto_fixable)
-            continue;
-        standardFixes.push({
-            applied: false,
-            issueType: issue.type,
-            nodeName: issue.node || 'N/A',
-            description: issue.reason || `Fix ${issue.type}`,
-        });
-    }
-    for (const issue of multiResponderIssues) {
-        multiResponderFixes.push({
-            applied: false,
-            issueType: issue.type,
-            nodeName: issue.nodes.join(', '),
-            description: issue.description,
-            change: issue.fixSuggestion,
-        });
-    }
-    return { standardFixes, multiResponderFixes };
-}

package/dist/sdk/workflow-intent.js

@@ -445,9 +445,14 @@ const ACTION_CHAIN_PATTERNS = [
     },
 ];
 /**
- * Type compatibility rules - what outputs can connect to what inputs
+ * Intent routing type compatibility - determines how outputs wire to inputs during intent processing.
+ *
+ * NOTE: This is SEPARATE from knowledge.ts TYPE_COMPATIBILITY which is user-facing documentation.
+ * This focuses on the "can_connect_to" and "use_named_inputs_for" routing logic.
+ *
+ * Canonical type documentation: src/sdk/knowledge.ts → TYPE_COMPATIBILITY
  */
-export const TYPE_COMPATIBILITY = {
+export const INTENT_TYPE_ROUTING = {
     WELL_KNOWN_TYPE_CHAT_CONVERSATION: {
         can_connect_to: ["conversation"],
         use_named_inputs_for: [],
@@ -1312,6 +1317,37 @@ export function summarizeIntentConfidence(confidence) {
 // ─────────────────────────────────────────────────────────────────────────────
 // Intent to Spec Conversion
 // ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generate takeActionInstructions from tools for Voice AI.
+ *
+ * This populates the "Define what actions your AI Employee can perform" section
+ * in the Voice persona config. Format follows the Ema Voice API spec.
+ */
+function generateTakeActionInstructions(tools) {
+    if (!tools || tools.length === 0) {
+        return "";
+    }
+    const cases = tools.map((tool, index) => {
+        const caseNum = index + 1;
+        const toolName = tool.display_name ?? tool.action ?? `Action ${caseNum}`;
+        const triggerCondition = tool.trigger_condition ?? tool.description ?? "Perform this action when requested";
+        // Extract required parameters from tool schema if available
+        const requiredParams = tool.required_inputs ?? [];
+        const paramsObj = requiredParams.length > 0
+            ? `{ ${requiredParams.map(p => `"${p}": ""`).join(", ")} }`
+            : "{ }";
+        return `</Case ${caseNum}>
+${toolName}
+
+Trigger When: ${triggerCondition}
+
+Intent for tool call: "User requests ${toolName.toLowerCase()}"
+
+Required parameters: ${paramsObj}
+</Case ${caseNum}>`;
+    });
+    return cases.join("\n\n");
+}
 export function intentToSpec(intent) {
     const nodes = [];
     const resultMappings = [];
@@ -1463,7 +1499,11 @@ export function intentToSpec(intent) {
         welcomeMessage: intent.voice_config?.welcome_message,
         identityAndPurpose: intent.voice_config?.identity ?? intent.description,
         hangupInstructions: intent.voice_config?.hangup_instructions,
-        // Additional fields can be extracted from intent description in the future
+        transferInstructions: intent.voice_config?.transfer_instructions,
+        waitMessage: intent.voice_config?.wait_message,
+        // Generate takeActionInstructions from tools if not explicitly provided
+        takeActionInstructions: intent.voice_config?.take_action_instructions ??
+            generateTakeActionInstructions(intent.tools),
     } : undefined;
     return {
         name: intent.name,

package/docs/dashboard-operations.md

@@ -93,6 +93,41 @@ persona(id="persona-uuid", data={method:"list"})
 persona(id="persona-uuid", data={method:"schema"})
 ```
 
+### Upload Dashboard Rows with Files
+
+Create new dashboard rows with file attachments (triggers workflow execution):
+
+```javascript
+persona(id="dashboard-uuid", data={
+  method: "upload",
+  items: [
+    {
+      "Input Document": { file: "/path/to/invoice.pdf" },
+      "Customer Name": "Acme Corp",
+      "Amount": 1500.00,
+      "Priority": true
+    }
+  ]
+})
+```
+
+**Supported value types in `items`:**
+
+| Type | Format | Result |
+|------|--------|--------|
+| String | `"value"` | `string_value` |
+| Number | `123.45` | `number_value` |
+| Boolean | `true` | `boolean_value` |
+| File | `{ file: "/path/to/doc.pdf" }` | `document_value` (auto base64) |
+| Inline Doc | `{ contents: "...", mime_type: "text/plain" }` | `document_value` |
+
+**Key differences from knowledge base upload:**
+
+| Operation | Target | Use Case |
+|-----------|--------|----------|
+| `data={method:"upload", path:"..."}` | Knowledge Base | Chat personas, RAG search |
+| `data={method:"upload", items:[...]}` | Dashboard Rows | Dashboard personas, per-row workflow |
+
 ### Legacy Syntax (still works)
 
 ```

package/docs/ema-user-guide.md

@@ -1003,6 +1003,72 @@ tools:
 
 ---
 
+## Workflow Analysis (MCP Users)
+
+When using the MCP toolkit to analyze workflows, the analysis is **LLM-driven** using rule resources.
+
+### Analysis Pattern
+
+```
+1. Get workflow data:     workflow(mode="get", persona_id="...")
+2. Fetch analysis rules:  ema://rules/anti-patterns
+                          ema://rules/structural-invariants
+3. LLM checks workflow against rules
+4. LLM reports issues (MCP does NOT pre-compute)
+```
+
+### Key Resources for Analysis
+
+| Resource | Purpose |
+|----------|---------|
+| `ema://rules/anti-patterns` | Common workflow mistakes (missing fallback, stateless response, etc.) |
+| `ema://rules/structural-invariants` | Hard constraints (no cycles, reachability, WORKFLOW_OUTPUT) |
+| `ema://rules/input-sources` | Which inputs accept which data types |
+| `ema://rules/optimizations` | Performance improvements |
+
+### Voice AI: Automatic Action Instructions
+
+When creating Voice AI personas with tools, `takeActionInstructions` is auto-generated:
+
+```
+// Tools defined in workflow → Auto-generates:
+</Case 1>
+Create Ticket
+
+Trigger When: User reports an issue
+
+Required parameters: { "title": "", "description": "" }
+</Case 1>
+```
+
+### Dashboard: File Attachments in Rows
+
+Dashboard rows can include file attachments via MCP:
+
+```javascript
+persona(id="dashboard-id", data={
+  method: "upload",
+  items: [{
+    "Input Document": { file: "/path/to/invoice.pdf" },
+    "Customer Name": "Acme Corp"
+  }]
+})
+```
+
+### Critical: Data Sources Before Search
+
+Workflows with `search` nodes require documents to be uploaded first:
+
+```
+1. Upload:  persona(id="...", data={method:"upload", path:"/docs/faq.pdf"})
+2. Verify:  persona(id="...", data={method:"stats"})  // success > 0
+3. Deploy:  workflow(mode="deploy", ...)
+```
+
+Without documents, search returns empty results.
+
+---
+
 ## Troubleshooting & Gotchas
 
 ### Common Mistakes

package/docs/mcp-tools-guide.md

@@ -380,6 +380,20 @@ data(persona_id="abc", mode="upload", file="/path/to/file.pdf")
 data(persona_id="abc", mode="delete", file_id="file-123")
 ```
 
+**Upload to specific widget (Document Generation personas):**
+```typescript
+// Document Proposal Manager widget names (verified from template):
+data(persona_id="abc", mode="upload", file="/path/to/company.pdf", widget_name="upload")      // Content Repository
+data(persona_id="abc", mode="upload", file="/path/to/service-line.pdf", widget_name="upload1") // Service Line Documents
+data(persona_id="abc", mode="upload", file="/path/to/style-guide.pdf", widget_name="upload2")  // Style Guide
+```
+
+> **Important for Document Generation (Proposal Writer) personas:** Files must be uploaded to the correct widget to appear in the right repository in the UI. Without `widget_name`, files go to the default `fileUpload` widget which may not be visible in the Configuration tab.
+>
+> **Document Proposal Manager widgets:** `upload` (Content Repository), `upload1` (Service Line Documents), `upload2` (Style Guide)
+>
+> **For other templates:** Call `persona(id="abc", include_workflow=true)` and inspect `proto_config.widgets[].name` to find the exact widget names.
+
 **Generate content (via Document Generation API):**
 ```typescript
 // From a template
@@ -445,22 +459,45 @@ Start with:
 **MCP provides data and schema. LLM generates workflow_def.**
 
 ```typescript
-// 1. Get current workflow + schema
+// 1. Get current workflow + schema (includes deprecation_warnings!)
 result = workflow(mode="get", persona_id="abc")
-// Returns: workflow_def, generation_schema, example_workflow, requirements
+// Returns: workflow_def, generation_schema, example_workflow, requirements, deprecation_warnings
 
 // 2. LLM analyzes and generates new workflow_def
 // (LLM uses schema and examples to build valid workflow)
+// ⚠️ FIX any deprecated actions FIRST - check deprecation_warnings!
 
-// 3. Deploy LLM's result
+// 3. Deploy LLM's result (preview first!)
+workflow(mode="deploy", persona_id="abc", workflow_def={...}, preview=true)
 workflow(mode="deploy", persona_id="abc", workflow_def={...})
 ```
 
+### ⚠️ CRITICAL: Check Deprecated Actions First
+
+**BEFORE generating any workflow:**
+
+1. Check `deprecation_warnings` in `workflow(mode="get")` response
+2. Use `reference(type="actions")` to verify current versions
+3. **NEVER** copy workflow patterns from existing personas (they may use deprecated actions!)
+
+**Correct workflow pattern:**
+```
+chat_trigger → search/v2 → respond_for_external_actions → WORKFLOW_OUTPUT
+```
+
+**Deprecated (DO NOT USE):**
+```
+search/v0 → Use search/v2
+respond_with_sources → Use respond_for_external_actions
+call_llm/v0 → Use call_llm/v2
+```
+
 **Common issues to check when generating:**
 - Missing `WORKFLOW_OUTPUT` in results
 - Missing Fallback category in categorizers
 - Orphan nodes not connected to output
 - Type mismatches between connected nodes
+- **Using deprecated actions** (check deprecation_warnings!)
 
 ## HITL (Human-in-the-Loop) Policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.1.26-4",
+  "version": "2026.1.27",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",
@@ -58,7 +58,6 @@
     "generate:api-client": "npx @hey-api/openapi-ts -i src/sdk/generated/openapi.json -o src/sdk/generated/api-client -c @hey-api/client-fetch",
     "generate:protos": "buf generate ../ema-repos/protos --template buf.gen.yaml",
     "generate:proto-fields": "tsx scripts/generate-proto-fields.ts",
-    "generate:action-schema": "tsx scripts/generate-action-schema.ts",
     "generate:deprecated-actions": "tsx scripts/generate-deprecated-actions.ts",
     "generate:skill": "tsx scripts/generate-skill.ts",
     "generate:skill:check": "tsx scripts/generate-skill.ts --check",