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

package/dist/sdk/ema-client.js

@@ -166,6 +166,17 @@ export class EmaClientV2 {
                 // Copy namespace from existing workflow
                 workflow = { ...workflow, workflowName: existingWfName };
             }
+            else {
+                // Generate a valid namespace for personas without existing workflows
+                // Format: ["ema", "personas", "<persona_id>"] with name "workflow"
+                const generatedWfName = {
+                    name: {
+                        namespaces: ["ema", "personas", personaId],
+                        name: "workflow",
+                    },
+                };
+                workflow = { ...workflow, workflowName: generatedWfName };
+            }
         }
         const result = await api.updatePersona({
             client: this.restClient,
@@ -287,6 +298,178 @@ export class EmaClientV2 {
         const personas = await this.listPersonas();
         return personas.filter(p => this.getSyncMetadata(p) !== null);
     }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // File Upload/Delete - REST API (not yet in OpenAPI spec)
+    // These are hand-written until the OpenAPI spec is updated
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Upload a file to an AI Employee's knowledge base.
+     * API endpoint: POST /api/v2/upload/files (multipart/form-data)
+     */
+    async uploadDataSource(personaId, fileContent, filename, opts) {
+        const widgetName = opts?.widgetName ?? "fileUpload";
+        const tags = opts?.tags ?? widgetName;
+        const mimeType = opts?.mimeType ?? this.detectMimeType(filename);
+        // Build multipart form data manually
+        const boundary = `----EmaUploadBoundary${Date.now()}`;
+        const parts = [];
+        // persona_id field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="persona_id"\r\n\r\n${personaId}`);
+        // widget_name field
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="widget_name"\r\n\r\n${widgetName}`);
+        // tags field (required by API, defaults to widget_name)
+        parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="tags"\r\n\r\n${tags}`);
+        // Build the file part
+        const filePart = [
+            `--${boundary}`,
+            `Content-Disposition: form-data; name="file"; filename="${filename}"`,
+            `Content-Type: ${mimeType}`,
+            "",
+            "", // Content will be appended as binary
+        ].join("\r\n");
+        // Combine everything
+        const headerBuffer = Buffer.from(parts.join("\r\n") + "\r\n" + filePart);
+        const fileBuffer = Buffer.isBuffer(fileContent) ? fileContent : Buffer.from(fileContent);
+        const footerBuffer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const bodyBuffer = Buffer.concat([headerBuffer, fileBuffer, footerBuffer]);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 60_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                    "X-Persona-Id": personaId,
+                },
+                body: bodyBuffer,
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `uploadDataSource failed (${this.env.name})`,
+                });
+            }
+            const result = await resp.json();
+            return {
+                fileId: result.file_id ?? result.id ?? "",
+                status: result.status ?? "uploaded",
+                filename: filename,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Delete a data source file from an AI Employee's knowledge base.
+     * API endpoint: DELETE /api/v2/upload/files/{file_id}
+     */
+    async deleteDataSource(personaId, fileId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/v2/upload/files/${fileId}?persona_id=${personaId}`, {
+                method: "DELETE",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                    "X-Persona-Id": personaId,
+                },
+                signal: controller.signal,
+            });
+            if (!resp.ok && resp.status !== 404) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `deleteDataSource failed (${this.env.name})`,
+                });
+            }
+            return { success: true, fileId };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Delete a persona
+     * API endpoint: DELETE /api/personas/{persona_id}
+     */
+    async deletePersona(personaId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const resp = await fetch(`${this.env.baseUrl.replace(/\/$/, "")}/api/personas/${personaId}`, {
+                method: "DELETE",
+                headers: {
+                    Authorization: `Bearer ${this.env.bearerToken}`,
+                },
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                const errorBody = await resp.text();
+                throw new EmaApiError({
+                    statusCode: resp.status,
+                    body: errorBody,
+                    message: `deletePersona failed (${this.env.name})`,
+                });
+            }
+            return { success: true };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Wait for data replication to complete (polling helper)
+     */
+    async waitForReplication(requestId, personaId, opts) {
+        const timeout = opts?.timeoutMs ?? 60_000;
+        const interval = opts?.pollIntervalMs ?? 2_000;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const result = await this.getReplicationStatus(requestId);
+            if (result.status === 2 /* COMPLETED */) {
+                return { status: "completed" };
+            }
+            if (result.status === 3 /* FAILED */) {
+                return {
+                    status: "failed",
+                    failedReason: result.failedReason || "Unknown error"
+                };
+            }
+            await new Promise(resolve => setTimeout(resolve, interval));
+        }
+        return { status: "timeout" };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /** Detect MIME type from filename extension */
+    detectMimeType(filename) {
+        const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+        const mimeTypes = {
+            'pdf': 'application/pdf',
+            'txt': 'text/plain',
+            'csv': 'text/csv',
+            'json': 'application/json',
+            'xml': 'application/xml',
+            'html': 'text/html',
+            'md': 'text/markdown',
+            'doc': 'application/msword',
+            'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            'xls': 'application/vnd.ms-excel',
+            'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            'png': 'image/png',
+            'jpg': 'image/jpeg',
+            'jpeg': 'image/jpeg',
+            'gif': 'image/gif',
+        };
+        return mimeTypes[ext] ?? 'application/octet-stream';
+    }
 }
 // Default export for convenience
 export default EmaClientV2;

package/dist/sdk/generated/deprecated-actions.js

@@ -0,0 +1,171 @@
+/**
+ * Auto-generated deprecated actions list from ema repository.
+ *
+ * PRIMARY SOURCE: API via client.listActions() where deprecated === true
+ * This file is FALLBACK only when API is unavailable.
+ *
+ * Generated at: 2026-01-26T00:00:00.000Z
+ * Source: manual (pending first GH Actions sync)
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:deprecated-actions
+ */
+/**
+ * Deprecated actions with known replacements.
+ * Use the replacement action instead.
+ */
+export const DEPRECATED_ACTIONS_WITH_REPLACEMENT = [
+    {
+        action: "search",
+        version: "v0",
+        replacement: "search",
+        replacementVersion: "v2",
+        migrationNotes: "v2 requires datastore_configs input (mandatory)",
+        source: "registered_actions.py",
+    },
+    {
+        action: "web_search",
+        version: "v0",
+        replacement: "live_web_search or ai_web_search",
+        migrationNotes: "Split into two specialized actions",
+        source: "registered_actions.py",
+    },
+    {
+        action: "call_llm",
+        version: "v0",
+        replacement: "call_llm",
+        replacementVersion: "v2",
+        migrationNotes: "v2 uses meta_respond_v2",
+        source: "registered_actions.py",
+    },
+    {
+        action: "combine_external_action_and_search_results",
+        version: "v0",
+        replacement: "respond_for_external_actions",
+        migrationNotes: "Migration in progress",
+        source: "registered_actions.py",
+    },
+    {
+        action: "human_collaboration",
+        version: "v0",
+        replacement: "general_hitl",
+        migrationNotes: "More flexible HITL patterns",
+        source: "registered_actions.py",
+    },
+    {
+        action: "fixed_response",
+        version: "v0",
+        replacement: "fixed_response",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "custom_agent",
+        version: "v0",
+        replacement: "custom_agent",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "json_mapper",
+        version: "v0",
+        replacement: "json_mapper",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "rule_validation_with_documents",
+        version: "v0",
+        replacement: "rule_validation_with_documents",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "text_categorizer",
+        version: "v0",
+        replacement: "text_categorizer",
+        replacementVersion: "v1",
+        source: "registered_actions.py",
+    },
+    {
+        action: "respond_with_sources",
+        version: "v0",
+        replacement: "respond_for_external_actions",
+        migrationNotes: "Better tool result handling",
+        source: "registered_actions.py",
+    },
+];
+/**
+ * Deprecated actions without documented replacements.
+ * These are typically internal actions or superseded functionality.
+ */
+export const DEPRECATED_ACTIONS_NO_REPLACEMENT = [
+    { action: "meta_respond", version: "all", environment: "all", migrationNotes: "Internal LLM response - do not use directly", source: "system_agents" },
+    { action: "meta_respond_v2", version: "all", environment: "all", migrationNotes: "Internal LLM response - do not use directly", source: "system_agents" },
+    { action: "ticket_respond_with_sources", version: "all", environment: "all", source: "system_agents" },
+    { action: "text_with_sources_translation", version: "all", environment: "all", source: "system_agents" },
+    { action: "document_categorizer", version: "all", environment: "all", source: "system_agents" },
+    { action: "document_metasearch", version: "all", environment: "all", source: "system_agents" },
+    { action: "combine_search_results", version: "all", environment: "all", source: "system_agents" },
+    { action: "combine_text_with_sources", version: "all", environment: "all", source: "system_agents" },
+    { action: "develop_outline", version: "all", environment: "all", source: "system_agents" },
+    { action: "generate_document_using_outline", version: "all", environment: "all", source: "system_agents" },
+    { action: "write_document", version: "all", environment: "all", source: "system_agents" },
+    { action: "external_action_caller_v1", version: "all", environment: "dev", migrationNotes: "Use external_action_caller v0", source: "system_agents" },
+    { action: "ticket_thread_sink", version: "all", environment: "dev", source: "system_agents" },
+    { action: "call_llm_v1", version: "all", environment: "all", migrationNotes: "Use call_llm v2", source: "system_agents" },
+];
+/**
+ * All deprecated actions combined.
+ */
+export const ALL_DEPRECATED_ACTIONS = [
+    ...DEPRECATED_ACTIONS_WITH_REPLACEMENT,
+    ...DEPRECATED_ACTIONS_NO_REPLACEMENT,
+];
+/**
+ * Deprecated agent types (legacy).
+ */
+export const DEPRECATED_AGENT_TYPES = [
+    "VISUALIZE_DATA",
+    "VISUALIZE_DATA_FOLLOWUP",
+    "PARSE_DELIMITED_FILES",
+    "GITHUB_DEMO",
+    "GITHUB_FOLLOWUP",
+    "RULES_VALIDATOR_AGENT",
+    "SUBJECT_RULE_VALIDATOR_AGENT",
+    "PRIOR_AUTHORISATION_AGENT",
+    "CHATBOT_AGENT",
+    "DEMO_PROPOSAL_MANAGEMENT_AGENT",
+    "GENERALISED_RULE_VALIDATION_AGENT",
+];
+/**
+ * Quick lookup map: "action/version" -> replacement info
+ */
+export const DEPRECATED_ACTIONS_MAP = {
+    "search/v0": { replacement: "search/v2", notes: "v2 requires datastore_configs input (mandatory)" },
+    "web_search/v0": { replacement: "live_web_search or ai_web_search", notes: "Split into two specialized actions" },
+    "call_llm/v0": { replacement: "call_llm/v2", notes: "v2 uses meta_respond_v2" },
+    "combine_external_action_and_search_results/v0": { replacement: "respond_for_external_actions", notes: "Migration in progress" },
+    "human_collaboration/v0": { replacement: "general_hitl", notes: "More flexible HITL patterns" },
+    "fixed_response/v0": { replacement: "fixed_response/v1" },
+    "custom_agent/v0": { replacement: "custom_agent/v1" },
+    "json_mapper/v0": { replacement: "json_mapper/v1" },
+    "rule_validation_with_documents/v0": { replacement: "rule_validation_with_documents/v1" },
+    "text_categorizer/v0": { replacement: "text_categorizer/v1" },
+    "respond_with_sources/v0": { replacement: "respond_for_external_actions", notes: "Better tool result handling" },
+    "meta_respond/all": { notes: "Internal LLM response - do not use directly" },
+    "meta_respond_v2/all": { notes: "Internal LLM response - do not use directly" },
+    "external_action_caller_v1/all": { notes: "Use external_action_caller v0" },
+    "call_llm_v1/all": { notes: "Use call_llm v2" },
+};
+/**
+ * Check if an action is deprecated.
+ */
+export function isActionDeprecated(actionName, version = "v0") {
+    return `${actionName}/${version}` in DEPRECATED_ACTIONS_MAP;
+}
+/**
+ * Get replacement for a deprecated action.
+ */
+export function getActionReplacement(actionName, version = "v0") {
+    return DEPRECATED_ACTIONS_MAP[`${actionName}/${version}`];
+}

package/dist/sdk/generated/template-fallbacks.js

@@ -0,0 +1,123 @@
+/**
+ * Auto-generated fallback templates from proto definitions.
+ *
+ * These are used ONLY when the API is unavailable.
+ * The API templates (getPersonaTemplates()) are the source of truth.
+ *
+ * Generated at: 2026-01-25T21:51:05.018Z
+ *
+ * DO NOT EDIT MANUALLY - regenerate with: npm run generate:templates
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Voice AI persona config template (fallback).
+ *
+ * Fields derived from proto definitions:
+ * - VoicebotConversationSettingsWidget
+ * - VoicebotVoiceSettingsWidget
+ * - VoicebotCallSettingsWidget
+ * - VoicebotVADSettingsWidget
+ * - VoicebotDataStorageSettingsWidget
+ */
+export const VOICE_TEMPLATE_FALLBACK = {
+    "conversationSettings": {
+        "name": "{AI Name}",
+        "welcomeMessage": "Hello, thank you for calling {Company}. This is {AI Name}. How can I help you today?",
+        "speechCharacteristics": "Keep tone friendly and concise. Use brief pauses between sentences.",
+        "identityAndPurpose": "You are {AI Name}, an AI assistant for {Company}. Your responsibilities: 1) {Task 1} 2) {Task 2}",
+        "hangupInstructions": "End the call when: The caller explicitly says goodbye, or confirms they have no more questions.",
+        "takeActionInstructions": "</Case 1>\\n{Action Name}\\n\\nTrigger When: {Condition}\\n\\nIntent for tool call: \"{Intent}\"\\n\\nRequired parameters: { \"{param}\": \"\" }\\n</Case 1>",
+        "systemPrompt": "Tool Calling Instructions: Always collect required parameters before calling tools. Confirm with caller before executing.",
+        "waitMessage": "One moment while I look that up for you...",
+        "formFillingInstructions": "When collecting information, ask one question at a time. Confirm values before proceeding.",
+        "transferCallInstructions": "Transfer when: The caller explicitly requests a human agent, or the issue is beyond AI capabilities."
+    },
+    "voiceSettings": {
+        "languageHints": [
+            "en-US"
+        ],
+        "voiceModel": "default"
+    },
+    "callSettings": {
+        "enableCallForwarding": false,
+        "callForwardingNumber": "",
+        "enableSpamCallPrevention": true,
+        "enableDisconnectCall": false
+    },
+    "vadSettings": {
+        "turnTimeout": 3,
+        "silenceEndCallTimeout": 30,
+        "maxConversationDuration": 600
+    },
+    "dataStorageSettings": {
+        "storeAudioRecording": true,
+        "storeTranscripts": true,
+        "storeAgentTranscript": true
+    }
+};
+/**
+ * Field documentation for LLM consumption.
+ * Use this when generating prompts about config structure.
+ */
+export const VOICE_TEMPLATE_FIELD_DOCS = `
+## Voice AI Persona Configuration Fields
+
+### Conversation Settings
+  - name: Name for the Voicebot Agent that will be spoken
+  - welcomeMessage: Message spoken when call connects
+  - speechCharacteristics: Instructions on how voicebot should speak
+  - identityAndPurpose: What the voicebot is for and tools it has access to
+  - hangupInstructions: When to end the call
+  - takeActionInstructions: Instructions on what actions takeAction can perform
+  - systemPrompt: Instructions on how to respond to user, handle tools
+  - waitMessage: Message when tool is taking time to execute
+  - formFillingInstructions: How to collect form data conversationally
+  - transferCallInstructions: When to transfer to human agent
+
+### Voice Settings
+  - languageHints: BCP47 language codes for speech recognition
+  - voiceModel: Voice model ID
+
+### Call Settings
+  - enableCallForwarding: Enable call forwarding
+  - callForwardingNumber: Number to forward calls to
+  - enableSpamCallPrevention: Enable spam call prevention
+  - enableDisconnectCall: Enable disconnect call
+
+### VAD Settings
+  - turnTimeout: Seconds to wait for caller to finish speaking
+  - silenceEndCallTimeout: Seconds of silence before ending call
+  - maxConversationDuration: Maximum call length in seconds
+
+### Data Storage Settings
+  - storeAudioRecording: Store audio recordings
+  - storeTranscripts: Store call transcripts
+  - storeAgentTranscript: Store agent transcript
+`;
+/**
+ * Get template fallback by type.
+ * Returns undefined if type is not supported.
+ */
+export function getTemplateFallback(type) {
+    switch (type) {
+        case "voice":
+            return { ...VOICE_TEMPLATE_FALLBACK };
+        case "chat":
+            // TODO: Generate from chat proto definitions
+            return undefined;
+        case "dashboard":
+            // TODO: Generate from dashboard proto definitions
+            return undefined;
+    }
+}
+/**
+ * Get field documentation by type.
+ */
+export function getTemplateFieldDocs(type) {
+    switch (type) {
+        case "voice":
+            return VOICE_TEMPLATE_FIELD_DOCS;
+        default:
+            return undefined;
+    }
+}

package/dist/sdk/guidance.js

@@ -82,8 +82,10 @@ await persona({ id: "abc", update: { workflow_spec: spec } }); // Then deploy`,
         do: "For content changes: 1) Get workflow with persona(include_workflow=true), " +
             "2) Edit the node's stringValue in the JSON, 3) Deploy with workflow(mode='deploy', workflow_def={...})",
         dont: "Use workflow(mode='modify') for content changes - it will silently return 0 changes.",
-        example: `// STRUCTURAL change (supported)
-workflow({ mode: "modify", persona_id: "abc", input: "Add HITL before email" })
+        example: `// STRUCTURAL change (supported via structured operations)
+persona({ mode: "modify", id: "abc", operations: [
+  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }}
+]})
 
 // CONTENT change (requires manual edit)
 const p = await persona({ id: "abc", include_workflow: true });
@@ -92,8 +94,42 @@ const wf = p.workflow_def;
 wf.actions[2].inputs.data.stringValue = JSON.stringify(newData);
 await workflow({ mode: "deploy", persona_id: "abc", workflow_def: wf });`,
         antiExample: `// This will silently fail - content change via modify
-workflow({ mode: "modify", persona_id: "abc", input: "Change customer data to commission data" })`,
-        related: ["workflow-spec-not-def"],
+persona({ mode: "modify", id: "abc", operations: [...] })  // for content changes`,
+        related: ["workflow-spec-not-def", "llm-driven-modifications"],
+    },
+    {
+        id: "llm-driven-modifications",
+        level: "critical",
+        category: "workflow",
+        title: "LLM-Driven Workflow Modifications",
+        applies: "When modifying workflows structurally",
+        description: "The MCP does NOT parse natural language for modifications. YOU (the Agent/LLM) must build structured operations. " +
+            "Call persona(mode='modify') first to get workflow context, then build operations array.",
+        do: "1) Get context: persona(mode='modify', id='...') returns current_nodes, available_actions, example_operations. " +
+            "2) Build structured operations array. 3) Execute: persona(mode='modify', id='...', operations=[...])",
+        dont: "Pass natural language strings expecting MCP to parse them into operations.",
+        example: `// Step 1: Get context (returns current_nodes, available_actions, examples)
+const ctx = await persona({ mode: "modify", id: "abc" });
+
+// Step 2: YOU build structured operations based on user intent
+const operations = [
+  { 
+    type: "insert",
+    insert: { 
+      action_type: "hitl",
+      display_name: "Email Approval",
+      insert_before: "send_email_node",
+      add_runif_to_downstream: true
+    }
+  }
+];
+
+// Step 3: Execute
+await persona({ mode: "modify", id: "abc", operations });`,
+        antiExample: `// DON'T: Pass natural language expecting MCP to understand it
+await persona({ mode: "modify", id: "abc", input: "add approval before email" })
+// The MCP will NOT parse this - it returns context instead`,
+        related: ["workflow-modification-scope", "analyze-before-modify"],
     },
     // ─────────────────────────────────────────────────────────────────────────
     // Important: Should Follow
@@ -162,7 +198,7 @@ const details = await persona({ id: list.personas[0].id });`,
         example: `// Useful resources:
 // ema://catalog/agents-summary - Action catalog
 // ema://rules/anti-patterns - Common mistakes
-// ema://templates/voice-ai/config - Voice AI template
+// ema://catalog/persona-templates - Live API templates
 // ema://docs/usage-guide - Comprehensive guide`,
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -186,7 +222,7 @@ persona({ id: "abc", env: "prod" })  // production`,
 export const TOOL_GUIDANCE = {
     persona: {
         toolName: "persona",
-        quickTip: "Use analyze=true before modifying. Use preview=true before deploying.",
+        quickTip: "Use analyze=true before modifying. Use preview=true before deploying. Build structured operations for modify.",
         operations: [
             {
                 name: "List all",
@@ -204,9 +240,14 @@ export const TOOL_GUIDANCE = {
                 example: 'persona(id="abc", analyze=true)',
             },
             {
-                name: "Update",
-                description: "Modify workflow using workflow_spec",
-                example: 'persona(id="abc", update={workflow_spec: {...}})',
+                name: "Get modify context",
+                description: "Get current_nodes, available_actions for building operations",
+                example: 'persona(mode="modify", id="abc")',
+            },
+            {
+                name: "Execute modify",
+                description: "Apply structured operations (insert/remove/rewire)",
+                example: 'persona(mode="modify", id="abc", operations=[...])',
             },
             {
                 name: "Create",
@@ -218,11 +259,13 @@ export const TOOL_GUIDANCE = {
             list: "Get details: persona(id='<id>')",
             get: "Analyze: persona(id='...', analyze=true)",
             analyze: "Review issues, build workflow_spec, then update",
-            update: "Verify: persona(id='...') to confirm changes",
+            modify_context: "Build operations array, then execute with operations=[...]",
+            modify_execute: "Verify: persona(id='...') to confirm changes",
             create: "Configure: persona(id='<new_id>', update={...})",
         },
         commonMistakes: [
-            "Modifying without analyzing first",
+            "Passing natural language to modify mode (MCP doesn't parse NL)",
+            "Modifying without getting context first",
             "Deploying without preview",
             "Using raw workflow_def instead of workflow_spec",
             "Forgetting Fallback in categorizers",
@@ -231,6 +274,7 @@ export const TOOL_GUIDANCE = {
             "analyze-before-modify",
             "preview-before-deploy",
             "workflow-spec-not-def",
+            "llm-driven-modifications",
         ],
     },
     catalog: {
@@ -361,6 +405,16 @@ ${critical.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 ## Important
 ${important.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 
+## LLM-Driven Architecture (CRITICAL)
+The MCP does NOT parse natural language for workflow modifications.
+**YOU (the Agent) must build structured operations:**
+
+1. Get context: \`persona(mode="modify", id="...")\` → returns current_nodes, available_actions
+2. Build operations array based on user intent
+3. Execute: \`persona(mode="modify", id="...", operations=[...])\`
+
+Example operations: insert, remove, rewire, update_config
+
 ## Resources
 - \`ema://docs/usage-guide\` - Complete guide
 - \`ema://catalog/agents-summary\` - Action catalog

package/dist/sdk/index.js

@@ -22,7 +22,9 @@ export { StateStore } from "./state.js";
 // Auto Builder Knowledge Base
 export { 
 // Catalogs & References
-AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, 
+AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, 
+// VOICE_PERSONA_TEMPLATE removed - use getTemplateFallback("voice") from generated/template-fallbacks.ts
+PROJECT_TYPES, 
 // Helper Functions
 getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
 // Workflow Analysis Functions