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

package/dist/mcp/tools.js

@@ -76,8 +76,8 @@ ${LIMITATIONS.map(l => `- ${l}`).join("\n")}
 ## Data Operations (sub-resource, requires id)
 - \`persona(id="abc", data={method:"list"})\` - list data items
 - \`persona(id="abc", data={method:"stats"})\` - get file counts by status (total, pending, success, failed)
-- \`persona(id="abc", data={method:"upload", path:"/file.pdf"})\` - upload file
-- \`persona(id="abc", data={method:"upload", items:[{...}]})\` - upload LLM-generated content
+- \`persona(id="abc", data={method:"upload", path:"/file.pdf"})\` - upload file to knowledge base
+- \`persona(id="abc", data={method:"upload", items:[{...}]})\` - create dashboard rows with data
 - \`persona(id="abc", data={method:"copy", from:"source-id"})\` - copy from another persona
 - \`persona(id="abc", data={method:"copy", from:"src", sanitize:true})\` - copy with PII masking
 - \`persona(id="abc", data={method:"replicate", from:"source-id"})\` - replicate by reference (no copy, fast)
@@ -88,7 +88,20 @@ ${LIMITATIONS.map(l => `- ${l}`).join("\n")}
 - \`persona(id="abc", data={method:"regenerate", document_id:"doc-123", project_id:"proj-456", selection:"intro", query:"make it shorter"})\` - modify document section
 - \`persona(id="abc", data={method:"replace", document_id:"doc-123", project_id:"proj-456", content:"new content"})\` - replace entire document content
 
-Note: For documents, \`replace\` is full content replacement (no partial update). For dashboard fixed inputs, use upload with existing row context.
+### Dashboard Row Upload with Files
+Create dashboard rows with file attachments (triggers workflow execution):
+\`\`\`
+persona(id="abc", data={
+  method: "upload",
+  items: [{
+    "Input Document": { file: "/path/to/invoice.pdf" },
+    "Customer Name": "Acme Corp"
+  }]
+})
+\`\`\`
+Item values support: strings, numbers, booleans, file attachments ({ file: "path" }), or inline documents ({ contents: "...", mime_type: "..." }).
+
+Note: \`path\` uploads to knowledge base (Chat personas). \`items\` creates dashboard rows (Dashboard personas).
 
 ## Action Composition (post-operation actions)
 Use \`actions\` array for multi-step operations instead of flag parameters.
@@ -127,8 +140,8 @@ persona(
                     // === EXPLICIT METHOD (required) ===
                     method: {
                         type: "string",
-                        enum: ["list", "get", "create", "update", "delete", "analyze", "sanitize", "schema", "snapshot", "history", "restore", "compare"],
-                        description: "Operation to perform (required unless using data sub-resource)"
+                        enum: ["list", "get", "create", "update", "delete", "sanitize", "schema", "snapshot", "history", "restore"],
+                        description: "Operation to perform. LLM does analysis/comparison - use 'get' to retrieve data, then reason about it."
                     },
                     // === Identity ===
                     id: {
@@ -197,11 +210,6 @@ persona(
                         type: "string",
                         description: "Version to restore, e.g. 'v3' (for method=restore)"
                     },
-                    // === Compare params (for method=compare) ===
-                    to: {
-                        type: "string",
-                        description: "Persona ID or snapshot to compare to (for method=compare)"
-                    },
                     // === Data sub-resource ===
                     data: {
                         type: "object",
@@ -229,11 +237,17 @@ persona(
                             },
                             wait: { type: "boolean", description: "Wait for replication to complete (for method=replicate, default: true)" },
                             // upload params
-                            path: { type: "string", description: "File path to upload (for method=upload)" },
-                            content: {
+                            path: { type: "string", description: "File path to upload to knowledge base (for method=upload)" },
+                            items: {
                                 type: "array",
                                 items: { type: "object" },
-                                description: "Content array - LLM-generated (for method=upload)"
+                                description: "Dashboard rows to create. Each object maps column names to values. Values can be: strings, numbers, booleans, file attachments { file: '/path' }, or inline docs { contents: '...', mime_type: '...' }"
+                            },
+                            // widget_name - for targeting specific widgets in upload or filtering stats
+                            // 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."
                             },
                             // delete params
                             file_id: { type: "string", description: "File/item ID to delete (for method=delete)" },
@@ -241,8 +255,6 @@ persona(
                             enabled: { type: "boolean", description: "Enable/disable embeddings (for method=embed)" },
                             // search params
                             query: { type: "string", description: "Search query (for method=search)" },
-                            // stats params
-                            widget_name: { type: "string", description: "Filter by widget name (for method=stats)" },
                         },
                         required: ["method"],
                     },
@@ -359,76 +371,47 @@ persona(
             },
         },
         // ═══════════════════════════════════════════════════════════════════════════
-        // 3. WORKFLOW - Complex workflow generation (separate from persona modifications)
+        // 3. WORKFLOW - Data retrieval and deployment ONLY (LLM does all thinking)
         // ═══════════════════════════════════════════════════════════════════════════
         {
             name: "workflow",
-            description: `Generate, analyze, or compile complex multi-node workflows.
-
-Use this for COMPLEX workflows (categorizers, multi-path routing, entity extraction chains).
-For SIMPLE modifications to existing personas, use persona(method="update", input="...") instead.
+            description: `Get workflow data or deploy LLM-generated workflows.
 
-## Generate (from requirements)
-- \`workflow(mode="generate", input="Voice AI for support with routing")\` - new workflow
-- \`workflow(mode="generate", input="...", persona_id="abc")\` - with widget context from existing persona
-- Returns \`llm_prompt\` for complex workflows - includes available widgets if persona_id provided
-- Returns \`available_widgets\` array showing what widget names to use in bindings
+**MCP provides data. LLM does the thinking.**
 
-## Analyze (existing workflow)
-- \`workflow(mode="analyze", persona_id="abc")\` - detect issues, get WorkflowSpec
+## Get (return data for LLM to work with)
+- \`workflow(mode="get", persona_id="abc")\` - returns workflow_def, schema, patterns, widgets
+- LLM analyzes, compares, and generates workflows using this data
 
-## Compile (spec to def)
-- \`workflow(mode="compile", workflow_spec={...})\` - convert WorkflowSpec to workflow_def
+## Deploy (execute LLM's result)
+- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - deploy LLM-generated workflow
 
-## Deploy (to persona)
-- \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - apply workflow to persona
-
-**Workflow for complex creation:**
-1. \`workflow(mode="generate", input="...", persona_id="abc")\` → get llm_prompt + available_widgets
-2. Use LLM to generate WorkflowSpec (use widget names from available_widgets)
-3. \`workflow(mode="compile", workflow_spec={...})\` → get workflow_def
-4. \`persona(method="update", id="abc", workflow_def={...})\` → deploy
-
-**IMPORTANT**: Workflows reference widgets by name (widgetName). Pass persona_id to get available widget names.`,
+**Workflow for creation:**
+1. \`workflow(mode="get", persona_id="abc")\` → get schema, patterns, current workflow
+2. LLM generates workflow_def (LLM does the work)
+3. \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` → MCP deploys`,
             inputSchema: {
                 type: "object",
                 properties: {
                     mode: {
                         type: "string",
-                        enum: ["generate", "analyze", "compile", "deploy", "optimize"],
-                        description: "Operation to perform",
-                    },
-                    input: {
-                        type: "string",
-                        description: "Natural language requirements (for mode=generate)",
+                        enum: ["get", "deploy"],
+                        description: "get = return data for LLM, deploy = execute LLM's workflow_def",
                     },
                     persona_id: {
                         type: "string",
-                        description: "Persona ID (for mode=analyze, deploy, optimize)",
-                    },
-                    workflow_spec: {
-                        type: "object",
-                        description: "WorkflowSpec object (for mode=compile)",
+                        description: "Persona ID (required)",
                     },
                     workflow_def: {
                         type: "object",
-                        description: "workflow_def JSON (for mode=deploy)",
-                    },
-                    type: {
-                        type: "string",
-                        enum: ["voice", "chat", "dashboard"],
-                        description: "Persona type (for mode=generate)",
-                    },
-                    preview: {
-                        type: "boolean",
-                        description: "Preview without deploying (default: true)",
+                        description: "workflow_def JSON (for mode=deploy) - LLM generates this",
                     },
                     env: {
                         type: "string",
                         description: envDescription,
                     },
                 },
-                required: ["mode"],
+                required: ["mode", "persona_id"],
             },
         },
         // ═══════════════════════════════════════════════════════════════════════════

package/dist/sdk/action-schema-parser.js

@@ -343,10 +343,16 @@ export function generateSchemaBundle(config) {
 // Type Compatibility Matrix
 // ============================================================================
 /**
- * Type compatibility rules for workflow validation
+ * Schema validation type compatibility - maps well-known types to compatible input names.
+ * Used by isTypeCompatible() for workflow validation.
+ *
+ * NOTE: This is SEPARATE from knowledge.ts TYPE_COMPATIBILITY which is user-facing documentation.
+ * This focuses on input NAME matching for schema validation.
+ *
+ * Canonical type documentation: src/sdk/knowledge.ts → TYPE_COMPATIBILITY
  */
-export const TYPE_COMPATIBILITY = {
-    // What inputs can accept each type
+export const SCHEMA_TYPE_COMPATIBILITY = {
+    // What input names can accept each type
     WELL_KNOWN_TYPE_CHAT_CONVERSATION: ["conversation", "chat_conversation"],
     WELL_KNOWN_TYPE_TEXT_WITH_SOURCES: ["query", "text", "user_query", "input"],
     WELL_KNOWN_TYPE_SEARCH_RESULT: ["search_results", "results"],
@@ -368,8 +374,8 @@ export function isTypeCompatible(sourceType, targetType, targetInputName) {
     if (targetInputName?.startsWith("named_inputs"))
         return true;
     // Check explicit compatibility
-    if (sourceType && TYPE_COMPATIBILITY[sourceType]) {
-        const compatible = TYPE_COMPATIBILITY[sourceType];
+    if (sourceType && SCHEMA_TYPE_COMPATIBILITY[sourceType]) {
+        const compatible = SCHEMA_TYPE_COMPATIBILITY[sourceType];
         if (compatible.includes("*"))
             return true;
         if (targetInputName && compatible.some((c) => targetInputName.includes(c)))

package/dist/sdk/client.js

@@ -17,7 +17,7 @@
  * const client = new EmaClientV2(env);
  * ```
  *
- * See docs/lessons-learned.md for migration guidance.
+ * See .ctx/docs/lessons-learned.md for migration guidance.
  */
 import { GrpcClient } from "./grpc-client.js";
 import { toJson } from "@bufbuild/protobuf";
@@ -393,27 +393,43 @@ export class EmaClient {
             const existingPersona = await this.getPersonaById(req.persona_id);
             const existingWorkflow = existingPersona?.workflow_def;
             const existingWfName = existingWorkflow?.workflowName;
+            // Deep clone workflow for modifications
+            const fixedWorkflow = JSON.parse(JSON.stringify(req.workflow));
             if (existingWfName?.name) {
-                // Deep clone workflow and fix the namespace
-                const fixedWorkflow = JSON.parse(JSON.stringify(req.workflow));
+                // Copy namespace from existing workflow
                 fixedWorkflow.workflowName = existingWfName;
-                // Also fix results format if needed - API expects "<actionName>.<outputName>" keys
-                const results = fixedWorkflow.results;
-                if (results) {
-                    const fixedResults = {};
-                    for (const [key, value] of Object.entries(results)) {
-                        if (value.actionName && value.outputName) {
-                            const correctKey = `${value.actionName}.${value.outputName}`;
-                            fixedResults[correctKey] = value;
-                        }
-                    }
-                    fixedWorkflow.results = fixedResults;
+                if (opts?.verbose || process.env.EMA_DEBUG) {
+                    console.error("[EmaClient] Copied workflow namespace from existing:", existingWfName.name);
                 }
-                finalReq = { ...req, workflow: fixedWorkflow };
+            }
+            else {
+                // CRITICAL FIX: Generate a valid namespace for personas without existing workflows.
+                // The API requires workflowName to match the persona's namespace format.
+                // Format: ["ema", "personas", "<persona_id>"] with name "workflow"
+                const generatedWfName = {
+                    name: {
+                        namespaces: ["ema", "personas", req.persona_id],
+                        name: "workflow",
+                    },
+                };
+                fixedWorkflow.workflowName = generatedWfName;
                 if (opts?.verbose || process.env.EMA_DEBUG) {
-                    console.error("[EmaClient] Fixed workflow namespace:", existingWfName.name);
+                    console.error("[EmaClient] Generated workflow namespace for new persona:", generatedWfName.name);
                 }
             }
+            // Also fix results format if needed - API expects "<actionName>.<outputName>" keys
+            const results = fixedWorkflow.results;
+            if (results) {
+                const fixedResults = {};
+                for (const [key, value] of Object.entries(results)) {
+                    if (value.actionName && value.outputName) {
+                        const correctKey = `${value.actionName}.${value.outputName}`;
+                        fixedResults[correctKey] = value;
+                    }
+                }
+                fixedWorkflow.results = fixedResults;
+            }
+            finalReq = { ...req, workflow: fixedWorkflow };
         }
         // Debug logging for troubleshooting
         if (opts?.verbose || process.env.EMA_DEBUG) {
@@ -534,10 +550,23 @@ export class EmaClient {
         });
         if (!resp.ok) {
             const body = await resp.text();
+            // Try to extract error details from response
+            let errorDetail = "";
+            try {
+                const parsed = JSON.parse(body);
+                errorDetail = parsed.error || parsed.message || parsed.detail || "";
+            }
+            catch {
+                errorDetail = body.slice(0, 200);
+            }
+            // Build informative error message
+            const message = errorDetail
+                ? `create_ai_employee failed (${this.env.name}): ${errorDetail}`
+                : `create_ai_employee failed (${this.env.name}) - status ${resp.status}`;
             throw new EmaApiError({
                 statusCode: resp.status,
                 body,
-                message: `create_ai_employee failed (${this.env.name})`,
+                message,
             });
         }
         return (await resp.json());

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,

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/guidance.js

@@ -71,30 +71,55 @@ await persona({ id: "abc", update: { workflow_spec: spec } }); // Then deploy`,
   { name: "Fallback", description: "Anything else" }  // Required!
 ]`,
     },
+    {
+        id: "data-sources-before-search",
+        level: "critical",
+        category: "workflow",
+        title: "Upload Data Sources Before Search",
+        applies: "When creating workflows with search/RAG nodes",
+        description: "Workflows with search/v2 nodes require data sources (documents) to be uploaded to the persona. " +
+            "Without documents, search returns empty results and RAG is useless.",
+        do: "1. Upload documents: persona(id='...', data={method:'upload', path:'/path/to/doc.pdf'})\n" +
+            "2. Check status: persona(id='...', data={method:'stats'}) → verify 'success' count > 0\n" +
+            "3. Then deploy workflow with search node",
+        dont: "Deploy search-based workflows before uploading any documents to the knowledge base.",
+        example: `// Upload documents first
+await persona({ id: "abc", data: { method: "upload", path: "/docs/product-faq.pdf" } });
+await persona({ id: "abc", data: { method: "upload", path: "/docs/pricing.pdf" } });
+
+// Check they're indexed
+const stats = await persona({ id: "abc", data: { method: "stats" } });
+// stats.success should be > 0
+
+// Then deploy workflow with search
+await workflow({ mode: "deploy", persona_id: "abc", workflow_def: workflowWithSearch });`,
+        antiExample: `// BAD: Deploy search workflow with no documents
+await workflow({ mode: "deploy", persona_id: "abc", workflow_def: workflowWithSearch });
+// Search will return empty results!`,
+        related: ["analyze-before-modify"],
+    },
     {
         id: "workflow-modification-scope",
         level: "critical",
         category: "workflow",
         title: "Structure vs Content Changes",
         applies: "When modifying workflows",
-        description: "workflow(mode='modify') only supports STRUCTURAL changes (add/remove nodes, rewire connections). " +
+        description: "persona(method='update', input='...') only supports STRUCTURAL changes (add/remove nodes, rewire connections). " +
             "CONTENT changes (fixed_response data, call_llm prompts) require manual workflow_def editing.",
-        do: "For content changes: 1) Get workflow with persona(include_workflow=true), " +
+        do: "For content changes: 1) Get workflow with persona(method='get', id='...'), " +
             "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 via structured operations)
-persona({ mode: "modify", id: "abc", operations: [
-  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }}
-]})
+        dont: "Use update with input for content changes - it will silently return 0 changes.",
+        example: `// STRUCTURAL change (supported via update + input)
+persona({ method: "update", id: "abc", input: "add HITL before send_email" })
 
 // CONTENT change (requires manual edit)
-const p = await persona({ id: "abc", include_workflow: true });
+const p = await persona({ method: "get", id: "abc" });
 const wf = p.workflow_def;
 // Find and edit the fixed_response node's inputs.data.stringValue
 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
-persona({ mode: "modify", id: "abc", operations: [...] })  // for content changes`,
+        antiExample: `// This will silently fail - content change via update
+persona({ method: "update", id: "abc", input: "change the welcome message" })  // for content changes`,
         related: ["workflow-spec-not-def", "llm-driven-modifications"],
     },
     {
@@ -103,15 +128,16 @@ persona({ mode: "modify", id: "abc", operations: [...] })  // for content change
         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
+        description: "Use persona(method='update', input='...') for incremental changes. The MCP routes this to the workflow modify handler. " +
+            "For structured operations, use persona(method='update', operations=[...]).",
+        do: "1) Analyze workflow: persona(method='analyze', id='...') returns workflow_spec and issues. " +
+            "2) Make changes: persona(method='update', id='...', input='add HITL before email') " +
+            "3) Or use structured operations: persona(method='update', id='...', operations=[...])",
+        dont: "Expect operations to work without understanding the current workflow structure first.",
+        example: `// Option 1: Natural language input (routed to modify handler)
+await persona({ method: "update", id: "abc", input: "add HITL approval before send_email" });
+
+// Option 2: Structured operations
 const operations = [
   { 
     type: "insert",
@@ -123,12 +149,10 @@ const operations = [
     }
   }
 ];
-
-// 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`,
+await persona({ method: "update", id: "abc", operations });`,
+        antiExample: `// DON'T: Try to modify without analyzing first
+await persona({ method: "update", id: "abc", operations: [...] })
+// Always analyze the workflow first to understand structure`,
         related: ["workflow-modification-scope", "analyze-before-modify"],
     },
     // ─────────────────────────────────────────────────────────────────────────
@@ -240,14 +264,14 @@ export const TOOL_GUIDANCE = {
                 example: 'persona(id="abc", analyze=true)',
             },
             {
-                name: "Get modify context",
-                description: "Get current_nodes, available_actions for building operations",
-                example: 'persona(mode="modify", id="abc")',
+                name: "Update with input",
+                description: "Incremental workflow changes via natural language",
+                example: 'persona(method="update", id="abc", input="add HITL before email")',
             },
             {
-                name: "Execute modify",
+                name: "Update with operations",
                 description: "Apply structured operations (insert/remove/rewire)",
-                example: 'persona(mode="modify", id="abc", operations=[...])',
+                example: 'persona(method="update", id="abc", operations=[...])',
             },
             {
                 name: "Create",
@@ -406,12 +430,11 @@ ${critical.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 ${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:**
+Use \`persona(method="update", input="...")\` for workflow modifications:
 
-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=[...])\`
+1. Analyze: \`persona(method="analyze", id="...")\` → returns workflow_spec, issues
+2. Update with natural language: \`persona(method="update", id="...", input="add HITL before email")\`
+3. Or use structured operations: \`persona(method="update", id="...", operations=[...])\`
 
 Example operations: insert, remove, rewire, update_config