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

package/dist/sdk/workflow-transformer.js

@@ -655,345 +655,3 @@ Return ONLY the modified WorkflowSpec JSON, no explanation needed:
 \`\`\`json
 `;
 }
-/**
- * @deprecated MCP should not parse natural language - the Agent IS the LLM.
- * Use agent reasoning instead. Will be removed in future version.
- *
- * Parse natural language intent into deterministic operations.
- * Returns operations that can be executed directly, or indicates LLM is needed.
- */
-export function parseIntent(input, spec) {
-    const ops = [];
-    const lowerInput = input.toLowerCase();
-    const nodeIds = spec.nodes.map(n => n.id);
-    // ─────────────────────────────────────────────────────────────────────────
-    // REMOVE NODE: "remove node X", "delete X", "remove X"
-    // ─────────────────────────────────────────────────────────────────────────
-    if (lowerInput.includes("remove") || lowerInput.includes("delete")) {
-        // Strategy 1: Exact node ID in input
-        for (const nodeId of nodeIds) {
-            if (input.includes(nodeId)) {
-                ops.push({ type: "remove", nodeId });
-            }
-        }
-        // Strategy 2: "remove the node X" pattern
-        if (ops.length === 0) {
-            const match = input.match(/(?:remove|delete)\s+(?:the\s+)?node\s+["']?([a-zA-Z0-9_]+)["']?/i);
-            if (match) {
-                const nodeId = nodeIds.find(id => id.toLowerCase() === match[1].toLowerCase());
-                if (nodeId) {
-                    ops.push({ type: "remove", nodeId });
-                }
-            }
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // RENAME NODE: "rename X to Y", "change displayName of X to Y"
-    // ─────────────────────────────────────────────────────────────────────────
-    if (lowerInput.includes("rename") || lowerInput.includes("displayname")) {
-        const match = input.match(/(?:rename|change\s+displayName\s+of)\s+["']?([a-zA-Z0-9_]+)["']?\s+to\s+["']?([^"'\n]+)["']?/i);
-        if (match) {
-            const nodeId = nodeIds.find(id => id.toLowerCase() === match[1].toLowerCase());
-            if (nodeId) {
-                ops.push({ type: "rename", nodeId, newDisplayName: match[2].trim() });
-            }
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // ADD RUNIF: "add runIf to X when Y.Z equals V"
-    // ─────────────────────────────────────────────────────────────────────────
-    if (lowerInput.includes("runif") || lowerInput.includes("conditional") ||
-        (lowerInput.includes("only run") && lowerInput.includes("when"))) {
-        // Pattern: "add runIf to NODE when SOURCE.OUTPUT equals VALUE"
-        const match = input.match(/(?:add\s+)?runIf\s+to\s+["']?([a-zA-Z0-9_]+)["']?\s+when\s+["']?([a-zA-Z0-9_]+)["']?\.["']?([a-zA-Z0-9_]+)["']?\s+(?:equals?|==|eq)\s+["']?([^"'\n]+)["']?/i);
-        if (match) {
-            const nodeId = nodeIds.find(id => id.toLowerCase() === match[1].toLowerCase());
-            const sourceAction = nodeIds.find(id => id.toLowerCase() === match[2].toLowerCase());
-            if (nodeId && sourceAction) {
-                ops.push({
-                    type: "add_runif",
-                    nodeId,
-                    condition: {
-                        sourceAction,
-                        sourceOutput: match[3],
-                        operator: "eq",
-                        value: match[4].trim(),
-                    },
-                });
-            }
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────
-    // ADD TO RESULTS: "add X to results", "include X in output"
-    // ─────────────────────────────────────────────────────────────────────────
-    if (lowerInput.includes("add") && (lowerInput.includes("result") || lowerInput.includes("output"))) {
-        for (const nodeId of nodeIds) {
-            if (input.includes(nodeId)) {
-                // Determine output name based on node type
-                const node = spec.nodes.find(n => n.id === nodeId);
-                const output = node?.actionType === "search" ? "search_results" : "response_with_sources";
-                ops.push({ type: "add_to_results", nodeId, output });
-            }
-        }
-    }
-    // If we found deterministic ops, return them
-    if (ops.length > 0) {
-        return { ops, needs_llm: false };
-    }
-    // Otherwise, this needs LLM for complex interpretation
-    return {
-        ops: [],
-        needs_llm: true,
-        reason: "Could not parse deterministic operations from input. LLM interpretation needed."
-    };
-}
-/**
- * @deprecated MCP should not apply operations - the Agent builds workflow_spec.
- * Will be removed in future version.
- *
- * Apply deterministic modifications to a WorkflowSpec.
- */
-export function applyOperations(spec, ops) {
-    // Deep clone to avoid mutations
-    const newSpec = JSON.parse(JSON.stringify(spec));
-    const changes = [];
-    const errors = [];
-    for (const op of ops) {
-        switch (op.type) {
-            case "remove": {
-                const idx = newSpec.nodes.findIndex(n => n.id === op.nodeId);
-                if (idx >= 0) {
-                    newSpec.nodes.splice(idx, 1);
-                    // Also remove from resultMappings
-                    newSpec.resultMappings = newSpec.resultMappings.filter(rm => rm.nodeId !== op.nodeId);
-                    // Clean up any references in other nodes' inputs - REMOVE them, don't just warn
-                    for (const node of newSpec.nodes) {
-                        if (node.inputs) {
-                            for (const [key, binding] of Object.entries(node.inputs)) {
-                                if (binding.actionName === op.nodeId) {
-                                    // Remove the dangling reference to prevent API errors
-                                    delete node.inputs[key];
-                                    errors.push(`Warning: Removed dangling reference ${node.id}.${key} → ${op.nodeId}`);
-                                }
-                                // Also check namedInputs for dangling refs
-                                if (binding.namedInputs) {
-                                    const originalLen = binding.namedInputs.length;
-                                    binding.namedInputs = binding.namedInputs.filter(ni => ni.binding?.actionName !== op.nodeId);
-                                    if (binding.namedInputs.length < originalLen) {
-                                        errors.push(`Warning: Removed dangling namedInput reference in ${node.id}.${key} → ${op.nodeId}`);
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    changes.push(`Removed node: ${op.nodeId}`);
-                }
-                else {
-                    errors.push(`Node not found: ${op.nodeId}`);
-                }
-                break;
-            }
-            case "rename": {
-                const node = newSpec.nodes.find(n => n.id === op.nodeId);
-                if (node) {
-                    const oldName = node.displayName;
-                    node.displayName = op.newDisplayName;
-                    changes.push(`Renamed ${op.nodeId}: "${oldName}" → "${op.newDisplayName}"`);
-                }
-                else {
-                    errors.push(`Node not found: ${op.nodeId}`);
-                }
-                break;
-            }
-            case "add_runif": {
-                const node = newSpec.nodes.find(n => n.id === op.nodeId);
-                if (node) {
-                    node.runIf = op.condition;
-                    changes.push(`Added runIf to ${op.nodeId}: when ${op.condition.sourceAction}.${op.condition.sourceOutput} ${op.condition.operator} "${op.condition.value}"`);
-                }
-                else {
-                    errors.push(`Node not found: ${op.nodeId}`);
-                }
-                break;
-            }
-            case "remove_runif": {
-                const node = newSpec.nodes.find(n => n.id === op.nodeId);
-                if (node) {
-                    delete node.runIf;
-                    changes.push(`Removed runIf from ${op.nodeId}`);
-                }
-                else {
-                    errors.push(`Node not found: ${op.nodeId}`);
-                }
-                break;
-            }
-            case "add_to_results": {
-                const exists = newSpec.resultMappings.some(rm => rm.nodeId === op.nodeId);
-                if (!exists) {
-                    newSpec.resultMappings.push({ nodeId: op.nodeId, output: op.output });
-                    changes.push(`Added ${op.nodeId}.${op.output} to results`);
-                }
-                else {
-                    changes.push(`${op.nodeId} already in results`);
-                }
-                break;
-            }
-            case "remove_from_results": {
-                const idx = newSpec.resultMappings.findIndex(rm => rm.nodeId === op.nodeId);
-                if (idx >= 0) {
-                    newSpec.resultMappings.splice(idx, 1);
-                    changes.push(`Removed ${op.nodeId} from results`);
-                }
-                break;
-            }
-        }
-    }
-    return { spec: newSpec, changes, errors };
-}
-/**
- * Directly patch a workflow_def without recompilation.
- * This preserves ALL original fields and only modifies what's necessary.
- *
- * Use this for simple operations like remove/rename that don't need full recompile.
- */
-function patchWorkflowDef(workflowDef, ops) {
-    const patched = JSON.parse(JSON.stringify(workflowDef));
-    const actions = patched.actions;
-    const results = patched.results;
-    const changes = [];
-    const errors = [];
-    for (const op of ops) {
-        switch (op.type) {
-            case "remove": {
-                const idx = actions.findIndex((a) => a.name === op.nodeId);
-                if (idx >= 0) {
-                    actions.splice(idx, 1);
-                    changes.push(`Removed node: ${op.nodeId}`);
-                    // Remove from results
-                    for (const key of Object.keys(results)) {
-                        if (results[key].actionName === op.nodeId) {
-                            delete results[key];
-                            changes.push(`Removed result mapping: ${key}`);
-                        }
-                    }
-                    // Clean up dangling input references
-                    for (const action of actions) {
-                        const inputs = action.inputs;
-                        if (inputs) {
-                            for (const [inputKey, inputVal] of Object.entries(inputs)) {
-                                const actionOutput = inputVal.actionOutput;
-                                if (actionOutput?.actionName === op.nodeId) {
-                                    delete inputs[inputKey];
-                                    errors.push(`Warning: Removed dangling reference ${action.name}.${inputKey} → ${op.nodeId}`);
-                                }
-                            }
-                        }
-                    }
-                }
-                else {
-                    errors.push(`Node not found: ${op.nodeId}`);
-                }
-                break;
-            }
-            case "rename": {
-                const action = actions.find((a) => a.name === op.nodeId);
-                if (action) {
-                    const displaySettings = action.displaySettings;
-                    if (displaySettings) {
-                        displaySettings.displayName = op.newDisplayName;
-                        changes.push(`Renamed ${op.nodeId} to "${op.newDisplayName}"`);
-                    }
-                }
-                else {
-                    errors.push(`Node not found for rename: ${op.nodeId}`);
-                }
-                break;
-            }
-            // For other operations, we'd need full recompile
-            default:
-                errors.push(`Direct patch not supported for operation: ${op.type}`);
-        }
-    }
-    return { workflow_def: patched, changes, errors };
-}
-/**
- * @deprecated MCP should not transform from intent - the Agent builds workflow_spec.
- * The agent uses analyze to get current spec, reasons about changes, and calls
- * update with the new workflow_spec it built.
- * Will be removed in future version.
- *
- * Transform a workflow based on natural language intent.
- *
- * @param workflowDef - The existing workflow_def JSON
- * @param input - Natural language modification request
- * @param personaType - The persona type (voice, chat, dashboard)
- * @returns IntentTransformResult with modified workflow or LLM prompt
- */
-export function transformWorkflowFromIntent(workflowDef, input, personaType = "chat") {
-    // Step 1: Decompile to spec (for parsing)
-    const spec = decompileWorkflow(workflowDef, personaType);
-    // Step 2: Parse intent into operations
-    const { ops, needs_llm, reason } = parseIntent(input, spec);
-    if (needs_llm) {
-        // Complex modification - return LLM prompt
-        return {
-            success: false,
-            needs_llm: true,
-            llm_prompt: createModificationPrompt(spec, input),
-            changes: [],
-            errors: [reason || "LLM interpretation needed"],
-        };
-    }
-    // Step 3: Check if we can use direct patching (simpler, preserves all fields)
-    const simpleOps = ["remove", "rename"];
-    const allSimple = ops.every(op => simpleOps.includes(op.type));
-    if (allSimple && ops.length > 0) {
-        // Use direct patching - no recompilation needed
-        const { workflow_def, changes, errors } = patchWorkflowDef(workflowDef, ops);
-        if (errors.some(e => !e.startsWith("Warning"))) {
-            return {
-                success: false,
-                workflow_def,
-                changes,
-                errors,
-            };
-        }
-        return {
-            success: true,
-            workflow_def,
-            changes,
-            errors,
-        };
-    }
-    // Step 4: Complex operations - use full decompile → transform → compile
-    const { spec: modifiedSpec, changes, errors } = applyOperations(spec, ops);
-    if (errors.some(e => !e.startsWith("Warning"))) {
-        return {
-            success: false,
-            spec: modifiedSpec,
-            changes,
-            errors,
-        };
-    }
-    // Step 5: Compile back to workflow_def
-    try {
-        const compiled = compileWorkflow(modifiedSpec);
-        // Preserve original workflowName
-        compiled.workflow_def.workflowName = workflowDef.workflowName;
-        return {
-            success: true,
-            spec: modifiedSpec,
-            workflow_def: compiled.workflow_def,
-            changes,
-            errors,
-        };
-    }
-    catch (e) {
-        return {
-            success: false,
-            spec: modifiedSpec,
-            changes,
-            errors: [...errors, `Compilation failed: ${e instanceof Error ? e.message : String(e)}`],
-        };
-    }
-}

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

@@ -28,15 +28,23 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). A
 | `reference` | Envs, actions, templates, patterns, concepts, guidance | No (flag-based) |
 | `sync` | Sync across environments | **YES** |
 
+### `workflow` tool (get/deploy only)
+
+| Mode | Purpose |
+|------|---------|
+| `get` | Returns workflow_def, schema, examples for LLM |
+| `deploy` | Deploys LLM-generated workflow_def |
+
+**LLM does all thinking** (analyze, compare, generate). MCP only provides data and executes.
+
 ### Deprecated tools (still work, show warnings)
 
 | Tool | Status | Use Instead |
 |------|--------|-------------|
-| `workflow` | Deprecated | `persona` |
 | `knowledge` | Deprecated | `data` |
 | `demo` | Deprecated | `data` + `persona` |
 
-> **Tip**: For new code, use `persona`, `data`, `sync`. Deprecated tools route internally to new ones.
+> **Tip**: For new code, use `persona`, `data`, `workflow`, `sync`.
 
 ## ⚠️ THE KEY INSIGHT: ONE CALL
 
@@ -102,21 +110,19 @@ persona(
 persona(mode="get", id="abc-123")
 
 // Modify config in ONE call
-persona(mode="update", id="abc-123", proto_config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
+persona(mode="update", id="abc-123", config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
 ```
 
-### Analyze/Review an AI Employee
+### Get workflow data (for LLM to analyze/modify)
 
 ```typescript
-persona(mode="get", id="abc-123")                         // Get persona
-persona(mode="get", id="abc-123", include_workflow=true)  // Include full workflow
+workflow(mode="get", persona_id="abc-123")  // Returns workflow_def, schema, examples
 ```
 
-### Optimize (auto-fix issues)
+The LLM then analyzes/modifies the workflow and deploys:
 
 ```typescript
-persona(mode="update", id="abc-123", optimize=true)                  // Preview fixes
-persona(mode="update", id="abc-123", optimize=true, preview=false)   // Apply fixes
+workflow(mode="deploy", persona_id="abc-123", workflow_def={...})  // Deploy LLM's result
 ```
 
 ### Upload / manage knowledge base documents
@@ -212,7 +218,7 @@ knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source
 persona(mode="version_create", id="My Bot", message="Before adding HITL")
 
 // Make changes...
-persona(mode="update", id="abc", proto_config={...})
+persona(mode="update", id="abc", config={...})
 
 // If something breaks - restore
 persona(mode="version_list", id="My Bot")
@@ -241,7 +247,7 @@ persona(mode="create", from="Voice AI Starter", name="My Bot", input="...", prev
 
 **Update config:**
 ```typescript
-persona(mode="update", id="abc", proto_config={widgets: [{...}]})
+persona(mode="update", id="abc", config={widgets: [{...}]})
 ```
 
 **Clone:**
@@ -249,34 +255,12 @@ persona(mode="update", id="abc", proto_config={widgets: [{...}]})
 persona(mode="clone", from="source-id", name="My Copy", include_data=true)
 ```
 
-**Compare:**
-```typescript
-persona(mode="compare", id="abc", compare_to="def")
-```
-
 **Sanitize (two-step process):**
 ```typescript
 persona(id="abc", sanitize=true)  // Step 1: Preview - identify PII
 persona(id="abc", sanitize=true, sanitize_examples=["Acme"], preview=false)  // Step 2: Apply
 ```
 
-**Analyze (recommended):**
-```typescript
-persona(mode="analyze", id="abc")                           // All aspects
-persona(mode="analyze", id="abc", include=["workflow"])     // Workflow only
-persona(mode="analyze", id="abc", include=["workflow", "config", "data"])
-```
-
-**Analyze + auto-fix:**
-```typescript
-persona(mode="analyze", id="abc", fix=true)
-```
-
-**Legacy (deprecated, use mode="analyze" instead):**
-```typescript
-persona(id="abc", optimize=true)    // Routes to workflow tool internally
-```
-
 **Intent (qualification for complex requests):**
 ```typescript
 // GREENFIELD: New persona creation
@@ -299,7 +283,7 @@ Returns:
 - `status: "needs_qualification"` → `questions` to answer before proceeding  
 - `status: "needs_llm"` → `llm_prompt` to send to LLM for IntentSpec generation
 
-For brownfield, combine with `mode="analyze"` to get current state, then use intent to qualify the change.
+For brownfield, use `workflow(mode="get")` to fetch current state, then use intent to qualify the change.
 
 **Templates:**
 ```typescript
@@ -396,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
@@ -456,19 +454,50 @@ Start with:
 - `ema://catalog/templates` (persona templates - dynamic)
 - `ema://rules/anti-patterns` (what NOT to do)
 
-## Auto-Fix Capabilities
+## Workflow Generation (LLM Does the Work)
+
+**MCP provides data and schema. LLM generates workflow_def.**
+
+```typescript
+// 1. Get current workflow + schema (includes deprecation_warnings!)
+result = workflow(mode="get", persona_id="abc")
+// 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 (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
+```
 
-The `persona(mode="update", id="...", optimize=true)` can automatically fix common issues:
+**Deprecated (DO NOT USE):**
+```
+search/v0 → Use search/v2
+respond_with_sources → Use respond_for_external_actions
+call_llm/v0 → Use call_llm/v2
+```
 
-| Issue | Severity | Auto-Fix? | Action |
-|-------|----------|-----------|--------|
-| `orphan` | warning | ✅ | Removes unreachable nodes |
-| `dead_end` | critical | ✅ | Adds results mapping |
-| `missing_workflow_output` | critical | ✅ | Adds results mapping |
-| `wrong_input_source` (email_to) | warning | ✅ | Adds entity_extraction |
-| `missing_fallback` | critical | ✅ | Adds Fallback category |
-| `type_mismatch` | critical | ✅ | Rewires to compatible source |
-| `cycle` | critical | ❌ | Requires manual restructuring |
+**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",
+  "version": "2026.1.27-10",
   "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,7 @@
     "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",
     "generate:templates": "tsx scripts/generate-templates.ts",