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

package/dist/mcp/prompts.js

@@ -28,12 +28,12 @@ const PROMPTS = {
                 },
                 {
                     name: "context",
-                    description: "Context type: 'greenfield' (new workflow), 'brownfield' (extend existing), 'optimize' (improve existing)",
+                    description: "Context type: 'greenfield' (new workflow), 'brownfield' (extend existing)",
                     required: false,
                 },
                 {
                     name: "persona_id",
-                    description: "Existing persona ID if brownfield/optimize context",
+                    description: "Existing persona ID if brownfield context",
                     required: false,
                 },
             ],
@@ -53,10 +53,12 @@ ${args.persona_id ? `**Existing Persona**: ${args.persona_id}` : ""}
 
 ### Step 1: Parse the Request
 Identify what the user is asking for:
-- **Action Type**: Create new / Extend existing / Optimize / Analyze
+- **Action Type**: Create new / Extend existing
 - **Scope**: Single intent / Multi-intent / Full workflow
 - **Specificity**: Vague / Partially specified / Detailed
 
+Note: For analysis/optimization, use \`workflow(mode="get")\` then analyze with \`ema://rules/*\` resources.
+
 ### Step 2: Check for Required Information
 
 #### For ALL requests, verify:
@@ -92,13 +94,6 @@ For external side-effect actions (send_email, create_ticket, update_record):
 | **Data Dependencies** | ✓/✗ | What existing data to use? |
 | **Impact Assessment** | ✓/✗ | What might break? |
 
-#### For OPTIMIZE:
-| Dimension | Status | Missing Info |
-|-----------|--------|--------------|
-| **Problem Areas** | ✓/✗ | What's not working? |
-| **Performance Goals** | ✓/✗ | Speed, accuracy, cost? |
-| **Constraints** | ✓/✗ | What can't change? |
-
 ### Step 3: Identify Ambiguities
 
 Look for:
@@ -159,7 +154,7 @@ Based on analysis, output ONE of:
   "confidence": "high|medium",
   "summary": "Brief summary of understood requirements",
   "inferred_defaults": ["List any assumptions made"],
-  "next_action": "workflow(mode='generate'|'extend'|'optimize', ...)"
+  "next_action": "workflow(mode='get'|'deploy', ...)"
 }
 \`\`\`
 
@@ -338,15 +333,19 @@ Environment: ${args.env || "demo"}
 
 Follow this review workflow using the consolidated tools:
 
-### Step 1: Fetch Persona + Workflow
-Call \`persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")\` to fetch the full workflow_def.
+### Step 1: Fetch Workflow Data
+Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` to get the workflow_def, schema, and examples.
 
-### Step 2: Analyze (Issues + Connections + Fixes + Metrics)
-Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}")\`.
+### Step 2: Analyze (YOU do this)
+Review the workflow_def for:
+- Missing WORKFLOW_OUTPUT (required for activation)
+- Missing Fallback category in categorizers
+- Type mismatches between connected nodes
+- Orphan nodes not connected to output
 
-### Step 3: (Optional) Preview Auto-Fixes
-If issues are found and you want a one-click preview of fixes:
-Call \`workflow(mode="optimize", persona_id="${args.persona_id}", preview=true, env="${args.env || "demo"}")\`.
+### Step 3: Propose Fixes
+If issues are found, generate a corrected workflow_def and deploy:
+Call \`workflow(mode="deploy", persona_id="${args.persona_id}", workflow_def={...}, env="${args.env || "demo"}")\`.
 
 ## Output Format
 
@@ -456,9 +455,9 @@ ${args.symptoms.toLowerCase().includes("hitl") || args.symptoms.toLowerCase().in
 ` : ""}
 ${args.symptoms.toLowerCase().includes("type") || args.symptoms.toLowerCase().includes("mismatch") ? `
 **Type Compatibility Issues:**
-- Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}", include=["connections"])\` for an edge-by-edge type check
+- Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` and analyze the workflow_def
+- Check wellKnownType compatibility between connected nodes
 - Common issues: chat_conversation → search (should be user_query)
-- Check wellKnownType compatibility
 ` : ""}
 ${args.symptoms.toLowerCase().includes("loop") || args.symptoms.toLowerCase().includes("infinite") || args.symptoms.toLowerCase().includes("hang") ? `
 **Loop/Hang Issues:**
@@ -467,8 +466,8 @@ ${args.symptoms.toLowerCase().includes("loop") || args.symptoms.toLowerCase().in
 - Verify workflow has proper termination paths
 ` : ""}
 
-### Step 4: Run Issue Detection
-Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` to find issues, connections, suggested fixes, and metrics.
+### Step 4: Review Workflow
+Call \`workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")\` and analyze the workflow_def for issues.
 
 ### Step 5: Propose Fix
 Based on findings, provide specific fix with before/after configuration.
@@ -642,13 +641,15 @@ Call in parallel:
 - \`persona(id="${args.persona_id_1}", include_workflow=true, env="${args.env_1 || "demo"}")\`
 - \`persona(id="${args.persona_id_2}", include_workflow=true, env="${args.env_2 || args.env_1 || "demo"}")\`
 
-### Step 2: Compare
-Call \`persona(id="${args.persona_id_1}", mode="compare", compare_to="${args.persona_id_2}", env="${args.env_1 || "demo"}", compare_env="${args.env_2 || args.env_1 || "demo"}")\`.
+### Step 2: Get Both Personas
+Call \`persona(method="get", id="${args.persona_id_1}", include_workflow=true, env="${args.env_1 || "demo"}")\`
+Call \`persona(method="get", id="${args.persona_id_2}", include_workflow=true, env="${args.env_2 || args.env_1 || "demo"}")\`
 
-### Step 3: Compare Workflows (if both have workflows)
-If both personas are in the same environment, call:
-\`workflow(mode="compare", persona_id="${args.persona_id_1}", compare_to="${args.persona_id_2}", env="${args.env_1 || "demo"}")\`
-to see structural differences.
+### Step 3: Compare (YOU do this)
+Compare the two workflow_def structures:
+- Node differences (added/removed/renamed)
+- Connection differences
+- Configuration differences
 
 ## Output Format
 
@@ -754,8 +755,9 @@ ${args.action === "snapshot" ? `
 1. List versions first to see available:
    \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
 
-2. Compare two versions:
-   \`persona(id="${args.persona_id}", mode="version_compare", v1="${args.version || "v1"}", v2="latest", env="${args.env || "demo"}")\`
+2. Get two versions and compare (YOU compare the results):
+   \`persona(id="${args.persona_id}", mode="version_get", version="${args.version || "v1"}", env="${args.env || "demo"}")\`
+   \`persona(id="${args.persona_id}", mode="version_get", version="latest", env="${args.env || "demo"}")\`
 
 3. Present changes:
    - Fields that changed
@@ -937,7 +939,7 @@ Provide examples of common tasks:
 2. **Search for specific persona**: \`persona(query="support", status="active", env="demo")\`
 3. **Get full persona details**: \`persona(id="xxx", include_workflow=true, env="demo")\`
 4. **Sync a persona**: \`sync(id="my-bot", source="demo", target="dev")\`
-5. **Analyze workflow**: \`workflow(mode="analyze", persona_id="xxx", env="demo")\`
+5. **Get workflow data**: \`workflow(mode="get", persona_id="xxx", env="demo")\` (you analyze the result)
 
 ## Output Format
 
@@ -1027,6 +1029,15 @@ ${args.intents ? `**Intents**: ${args.intents}` : ""}
 
 ## Instructions
 
+### Step 0: Check Deprecated Actions (DO THIS FIRST)
+Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
+
+**Key deprecated actions to avoid:**
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ### Step 1: Get Templates
 Get templates from API or use generated fallbacks:
 - \`template(config="voice")\` - Voice AI persona configuration (API-first with fallback)
@@ -1061,10 +1072,12 @@ ${args.name.toLowerCase().replace(/\s+/g, "-")}/
 └── proto-config.json      # Full API config
 \`\`\`
 
+**IMPORTANT**: Only use non-deprecated actions from Step 0.
+
 ### Step 6: Validate
 Call \`reference(validate_prompt=<generated_prompt>)\` to verify the prompt.
 
-Now begin by reading the resources, then proceed with generation.`,
+Now begin by reading the deprecated actions, then proceed with generation.`,
                 },
             },
         ],
@@ -1107,6 +1120,15 @@ ${args.data_sources ? `**Data Sources**: ${args.data_sources}` : ""}
 
 ## Instructions
 
+### Step 0: Check Deprecated Actions (DO THIS FIRST)
+Fetch \`ema://rules/deprecated-actions-summary\` to know which actions to AVOID.
+
+**Key deprecated actions to avoid:**
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ### Step 1: Get Templates
 Get templates from API or use generated fallbacks:
 - \`template(config="chat")\` - Chat AI persona configuration (API-first with fallback)
@@ -1130,6 +1152,8 @@ Call \`reference(guidance="conversation-vs-query")\` to understand:
 ### Step 5: Generate Output
 Using the templates from Step 1 and guidance from Steps 3-4, generate:
 
+**IMPORTANT**: Only use non-deprecated actions from Step 0.
+
 **Folder structure:**
 \`\`\`
 ${args.name.toLowerCase().replace(/\s+/g, "-")}/
@@ -1183,6 +1207,16 @@ Now begin by reading the resources, then proceed with generation.`,
 **Type**: ${args.type}
 **Description**: ${args.description}
 
+## Step 0: Check Deprecated Actions (DO THIS FIRST)
+
+Fetch \`ema://rules/deprecated-actions-summary\` to see which actions to AVOID.
+
+Common deprecated actions:
+- search/v0 → use search/v2 (requires datastore_configs)
+- respond_with_sources → use respond_for_external_actions
+- call_llm/v0 → use call_llm/v2
+- web_search/v0 → use live_web_search or ai_web_search
+
 ## Step 1: Preview the workflow
 
 \`\`\`
@@ -1193,6 +1227,7 @@ workflow(
 \`\`\`
 
 This returns workflow_def and proto_config. Review them before deploying.
+**Check for any deprecated actions in the generated workflow.**
 
 ## Step 2: Deploy when ready
 
@@ -1213,7 +1248,8 @@ ${args.type === "voice" ? `
 The generated proto_config includes voice settings:
 - welcomeMessage: Generated greeting
 - identityAndPurpose: Generated from description
-- takeActionInstructions, hangupInstructions: Sensible defaults
+- takeActionInstructions: Auto-generated from workflow tools (if tools specified)
+- hangupInstructions: Sensible defaults
 
 These are set automatically but can be customized via proto_config override.
 ` : ""}`,
@@ -1349,8 +1385,7 @@ ${args.workflow_def ? `**Workflow Definition**: Provided inline` : ""}
 ${args.persona_id ? `First, fetch the workflow:
 \`persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")\`
 
-Then analyze it using:
-\`workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")\`
+Then review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, etc.).
 ` : ""}
 
 ## Required Analysis Sections
@@ -1506,10 +1541,11 @@ Proceed to Phase 1.
 
 ### Step 1.1: Fetch and Analyze
 \`\`\`
-persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")
-workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")
+workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")
 \`\`\`
 
+Review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, orphan nodes).
+
 ### Step 1.2: Document Existing Logic
 Before making changes, document:
 - **Current intents**: List all categories and their handlers
@@ -1611,8 +1647,8 @@ workflow(
 
 ## Phase 4: Validate & Deploy
 
-### Step 4.1: Analyze Changes
-\`workflow(persona_id="${args.persona_id}", mode="analyze")\`
+### Step 4.1: Review Changes
+\`workflow(mode="get", persona_id="${args.persona_id}")\` and verify the workflow_def is correct.
 
 Verify:
 - [ ] No type mismatches
@@ -1620,11 +1656,12 @@ Verify:
 - [ ] All new nodes properly linked
 - [ ] Existing functionality preserved
 
-### Step 4.2: Preview Changes
-\`workflow(persona_id="${args.persona_id}", mode="optimize", preview=true)\`
+### Step 4.2: Validate with Rules
+Fetch \`ema://rules/anti-patterns\` and verify no issues.
 
 ### Step 4.3: Deploy
-\`workflow(persona_id="${args.persona_id}", mode="deploy", workflow_def=<extended_workflow>)\`
+\`workflow(persona_id="${args.persona_id}", mode="deploy", workflow_def=<extended_workflow>, preview=true)\`
+Then without preview to commit.
 
 ## Extension Patterns
 
@@ -1709,10 +1746,11 @@ Provide:
 ## Step 1: Fetch Workflow Data
 
 \`\`\`
-persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")
-workflow(persona_id="${args.persona_id}", mode="analyze", env="${args.env || "demo"}")
+workflow(mode="get", persona_id="${args.persona_id}", env="${args.env || "demo"}")
 \`\`\`
 
+Review the workflow_def for issues (missing WORKFLOW_OUTPUT, type mismatches, orphan nodes).
+
 ## Step 2: Intent Analysis Framework
 
 ### Business Intent Layer

package/dist/mcp/resources.js

@@ -30,11 +30,13 @@ import { dirname } from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Import knowledge catalogs for dynamic resources
-import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG } from "../sdk/knowledge.js";
+import { AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG, ALL_DEPRECATED_ACTIONS, DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT, WORKFLOW_ENABLING_CONSTRAINTS, MINIMUM_VIABLE_WORKFLOWS, } from "../sdk/knowledge.js";
 import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "../sdk/validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "../sdk/structural-rules.js";
 import { EmaClient } from "../sdk/client.js";
 import { APISchemaRegistry } from "../sdk/workflow-validator.js";
 import { loadConfigFromJsonEnv, loadConfigOptional, resolveBearerToken, getEnvByName, getMasterEnv, } from "../sdk/config.js";
+import { VOICE_TEMPLATE_FALLBACK, VOICE_TEMPLATE_FIELD_DOCS, } from "../sdk/generated/template-fallbacks.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Security Utilities
 // ─────────────────────────────────────────────────────────────────────────────
@@ -207,6 +209,336 @@ const DYNAMIC_RESOURCES = [
         mimeType: "application/json",
         generate: async () => JSON.stringify(OPTIMIZATION_RULES, null, 2),
     },
+    {
+        uri: "ema://rules/structural-invariants",
+        name: "rules/structural-invariants",
+        description: "Structural invariants: hard constraints that workflows must satisfy (no cycles, reachability, etc.)",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(STRUCTURAL_INVARIANTS, null, 2),
+    },
+    // Deprecated Actions - API-first with fallback
+    {
+        uri: "ema://rules/deprecated-actions",
+        name: "rules/deprecated-actions",
+        description: "Deprecated actions list: actions to avoid in new workflows, with their replacements and migration notes",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            // Try API first using existing client infrastructure
+            let apiDeprecated = [];
+            let source = "fallback";
+            try {
+                const client = getClientForEnvName(ctx.env);
+                if (client) {
+                    const actions = await client.listActions();
+                    apiDeprecated = actions.filter(a => a.deprecated).map(a => a.id);
+                    source = "api";
+                }
+            }
+            catch {
+                // API unavailable, use fallback
+            }
+            // Merge API deprecated with fallback replacement info
+            const result = {
+                _note: "Actions marked deprecated should not be used in new workflows. Use replacements where available.",
+                _source: source,
+                _api_deprecated_count: apiDeprecated.length,
+                // From API (current deprecated status)
+                api_deprecated: apiDeprecated.length > 0 ? apiDeprecated : undefined,
+                // From fallback (includes replacement info)
+                with_replacement: DEPRECATED_ACTIONS_WITH_REPLACEMENT.map(d => ({
+                    action: d.action,
+                    version: d.version,
+                    replacement: d.replacement,
+                    replacement_version: d.replacementVersion,
+                    migration_notes: d.migrationNotes,
+                })),
+                no_replacement: DEPRECATED_ACTIONS_NO_REPLACEMENT.map(d => ({
+                    action: d.action,
+                    version: d.version,
+                    environment: d.environment,
+                    notes: d.migrationNotes,
+                })),
+                _tip: "Check workflow(mode='get') for deprecation_warnings on specific workflows",
+            };
+            return JSON.stringify(result, null, 2);
+        },
+    },
+    {
+        uri: "ema://rules/deprecated-actions-summary",
+        name: "rules/deprecated-actions-summary",
+        description: "Deprecated actions summary: quick reference table of deprecated actions and replacements",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            // Try API first using existing client infrastructure
+            let apiDeprecated = [];
+            let source = "fallback";
+            try {
+                const client = getClientForEnvName(ctx.env);
+                if (client) {
+                    const actions = await client.listActions();
+                    apiDeprecated = actions.filter(a => a.deprecated).map(a => a.id);
+                    source = "api";
+                }
+            }
+            catch {
+                // API unavailable, use fallback
+            }
+            let md = "# Deprecated Actions\n\n";
+            md += "> Do NOT use these actions in new workflows. Use replacements where available.\n\n";
+            md += `> Source: ${source} (${source === "api" ? "live" : "synced 2026-01-26"})\n\n`;
+            if (apiDeprecated.length > 0) {
+                md += "## From API (Current)\n\n";
+                md += "| Action ID | Status |\n";
+                md += "|-----------|--------|\n";
+                for (const id of apiDeprecated) {
+                    md += `| \`${id}\` | DEPRECATED |\n`;
+                }
+                md += "\n";
+            }
+            md += "## Actions with Known Replacements\n\n";
+            md += "| Deprecated Action | Version | Replacement | Notes |\n";
+            md += "|-------------------|---------|-------------|-------|\n";
+            for (const d of DEPRECATED_ACTIONS_WITH_REPLACEMENT) {
+                const repl = Array.isArray(d.replacement) ? d.replacement.join(" or ") : d.replacement;
+                const replVer = d.replacementVersion ? ` ${d.replacementVersion}` : "";
+                md += `| \`${d.action}\` | ${d.version} | \`${repl}\`${replVer} | ${d.migrationNotes || "-"} |\n`;
+            }
+            md += "\n## Actions with No Known Replacement\n\n";
+            md += "| Action | Environment | Notes |\n";
+            md += "|--------|-------------|-------|\n";
+            for (const d of DEPRECATED_ACTIONS_NO_REPLACEMENT) {
+                md += `| \`${d.action}\` | ${d.environment || "all"} | ${d.migrationNotes || "-"} |\n`;
+            }
+            md += `\n**Total Known Deprecated**: ${ALL_DEPRECATED_ACTIONS.length} actions\n`;
+            md += `\n> **Best Practice**: Use \`workflow(mode="get")\` to check for deprecation warnings in specific workflows.\n`;
+            return md;
+        },
+    },
+    // Workflow Enabling Constraints - Requirements for persona activation
+    {
+        uri: "ema://rules/workflow-constraints",
+        name: "rules/workflow-constraints",
+        description: "Workflow enabling constraints: requirements that must be met before a persona can be activated",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify({
+            _note: "These constraints are checked by the Ema backend when enabling a persona.",
+            _source: "ema/ema_backend/db/models/personas_model.py:672-756",
+            _last_synced: "2026-01-26",
+            enabling_constraints: WORKFLOW_ENABLING_CONSTRAINTS,
+            minimum_viable_workflows: MINIMUM_VIABLE_WORKFLOWS,
+        }, null, 2),
+    },
+    {
+        uri: "ema://rules/workflow-constraints-summary",
+        name: "rules/workflow-constraints-summary",
+        description: "Workflow constraints summary: checklist of requirements for enabling a persona",
+        mimeType: "text/markdown",
+        generate: async () => {
+            let md = "# Workflow Enabling Constraints\n\n";
+            md += "> These constraints must be satisfied for a persona to be activated.\n\n";
+            md += "> Source: ema_backend/db/models/personas_model.py (synced 2026-01-26)\n\n";
+            md += "## Required Checks\n\n";
+            md += "| # | Constraint | Error State | Fix |\n";
+            md += "|---|------------|-------------|-----|\n";
+            for (const c of WORKFLOW_ENABLING_CONSTRAINTS) {
+                const critical = c.critical ? "**" : "";
+                md += `| ${c.id} | ${critical}${c.name}${critical} | \`${c.errorState}\` | ${c.fix} |\n`;
+            }
+            md += "\n## Minimum Viable Workflows by Type\n\n";
+            for (const [type, mvw] of Object.entries(MINIMUM_VIABLE_WORKFLOWS)) {
+                md += `### ${type}\n\n`;
+                md += `**Structure**: \`${mvw.exampleStructure}\`\n\n`;
+                md += `- Required nodes: ${mvw.requiredNodes.map(n => `\`${n}\``).join(", ")}\n`;
+                md += `- Required outputs: ${mvw.requiredOutputs.map(o => `\`${o}\``).join(", ")}\n`;
+                if (mvw.requiredWidgets) {
+                    md += `- Required widgets: ${mvw.requiredWidgets.map(w => `\`${w}\``).join(", ")}\n`;
+                }
+                if (mvw.notes) {
+                    md += `- Notes: ${mvw.notes}\n`;
+                }
+                md += "\n";
+            }
+            md += "## Critical Rule: WORKFLOW_OUTPUT\n\n";
+            md += "**Every workflow must have a `results.WORKFLOW_OUTPUT` that maps to an action output.**\n\n";
+            md += "```json\n";
+            md += '{\n  "results": {\n    "WORKFLOW_OUTPUT": {\n      "actionName": "respond_node",\n      "outputName": "response_with_sources"\n    }\n  }\n}\n';
+            md += "```\n";
+            return md;
+        },
+    },
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Workflow Requirements & Guidance
+    // NOT hardcoded templates - provide requirements and let LLM generate
+    // ─────────────────────────────────────────────────────────────────────────────
+    {
+        uri: "ema://templates/voice-ai/requirements",
+        name: "templates/voice-ai/requirements",
+        description: "Voice AI workflow requirements and guidance. Use workflow(mode='get') for schema, then generate workflow_def.",
+        mimeType: "application/json",
+        generate: async () => {
+            return JSON.stringify({
+                _note: "Requirements and guidance for Voice AI workflows. LLM generates workflow_def based on these.",
+                _usage: "1) workflow(mode='get', persona_id='...') for schema, 2) Generate workflow_def, 3) workflow(mode='deploy', ...)",
+                hard_requirements: {
+                    workflow_output: {
+                        rule: "MUST have results.WORKFLOW_OUTPUT mapped to final action output",
+                        example: '{ "results": { "WORKFLOW_OUTPUT": { "actionName": "respond", "outputName": "response" } } }',
+                    },
+                    workflow_name: {
+                        rule: "workflowName MUST be ['ema', 'personas', '<actual_persona_id>']",
+                    },
+                    trigger: {
+                        rule: "Voice AI uses chat_trigger (type CHAT)",
+                        namespace: ["triggers", "emainternal"],
+                    },
+                    response: {
+                        rule: "Must produce a response output that wires to WORKFLOW_OUTPUT",
+                    },
+                },
+                required_widgets: [
+                    { name: "conversationSettings", type: 39, purpose: "Voice identity, welcome message, instructions" },
+                    { name: "voiceSettings", type: 40, purpose: "Language, voice model" },
+                    { name: "callSettings", type: 41, purpose: "Call forwarding, spam prevention" },
+                    { name: "vadSettings", type: 42, purpose: "Voice activity detection, timeouts" },
+                ],
+                common_patterns: {
+                    simple_qa: "chat_trigger → search → respond_for_external_actions → WORKFLOW_OUTPUT",
+                    with_routing: "chat_trigger → chat_categorizer → [branch per intent] → respond → WORKFLOW_OUTPUT",
+                    with_tools: "chat_trigger → categorizer → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT",
+                },
+                best_practices: [
+                    "Use search/v2 (NOT v0) with datastore_configs",
+                    "Include Fallback category in every categorizer",
+                    "Use respond_for_external_actions (NOT deprecated respond_with_sources)",
+                    "Consider general_hitl before actions with side effects",
+                ],
+                _next_step: "Call workflow(mode='get', persona_id='...') to get full schema, then generate workflow_def",
+            }, null, 2);
+        },
+    },
+    {
+        uri: "ema://templates/voice-ai/config",
+        name: "templates/voice-ai/config",
+        description: "Voice AI configuration template (proto_config widgets). Customize values for your use case.",
+        mimeType: "application/json",
+        generate: async () => {
+            const config = {
+                _note: "Voice AI configuration template. Customize values for your use case.",
+                _usage: "persona(method='update', id='<ID>', config={widgets: [<these widgets with your values>]})",
+                widgets: [
+                    {
+                        name: "conversationSettings",
+                        type: 39,
+                        conversationSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.conversationSettings,
+                        },
+                    },
+                    {
+                        name: "voiceSettings",
+                        type: 40,
+                        voiceSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.voiceSettings,
+                        },
+                    },
+                    {
+                        name: "callSettings",
+                        type: 41,
+                        callSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.callSettings,
+                        },
+                    },
+                    {
+                        name: "vadSettings",
+                        type: 42,
+                        vadSettings: {
+                            ...VOICE_TEMPLATE_FALLBACK.vadSettings,
+                        },
+                    },
+                ],
+                field_docs: VOICE_TEMPLATE_FIELD_DOCS,
+            };
+            return JSON.stringify(config, null, 2);
+        },
+    },
+    {
+        uri: "ema://templates/voice-ai/guide",
+        name: "templates/voice-ai/guide",
+        description: "Voice AI creation guide with requirements and step-by-step process",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Voice AI Creation Guide
+
+## Process (Follow This Order)
+
+### 1. Create Persona
+\`\`\`
+persona(method="create", name="Your Voice AI", type="voice")
+\`\`\`
+
+### 2. Get Workflow Schema
+\`\`\`
+workflow(mode="get", persona_id="<ID>")
+\`\`\`
+This returns:
+- Current workflow (if any)
+- Deprecation warnings (fix these first!)
+- Generation schema (agents, constraints)
+- Requirements and guidance
+
+### 3. Generate Workflow
+Using the schema, generate a workflow_def that:
+- Has WORKFLOW_OUTPUT in results
+- Uses non-deprecated actions
+- Follows the flow pattern: trigger → processing → response → OUTPUT
+
+### 4. Deploy Workflow
+\`\`\`
+workflow(mode="deploy", persona_id="<ID>", workflow_def={...}, preview=true)
+\`\`\`
+Always preview first!
+
+### 5. Configure Settings
+\`\`\`
+persona(method="update", id="<ID>", config={widgets: [...]})
+\`\`\`
+
+### 6. Upload Knowledge
+\`\`\`
+persona(id="<ID>", data={method:"upload", path:"your-data.txt"})
+\`\`\`
+
+## Hard Requirements
+
+| Requirement | Why |
+|-------------|-----|
+| WORKFLOW_OUTPUT | Persona cannot be activated without it |
+| workflowName format | API rejects invalid namespaces |
+| Non-deprecated actions | Deprecated actions may fail |
+
+## Check for Deprecated Actions
+
+\`workflow(mode="get")\` returns \`deprecation_warnings\` if any actions are deprecated.
+**Fix these BEFORE deploying.**
+
+## Common Deprecated Actions
+
+| Deprecated | Use Instead |
+|------------|-------------|
+| search/v0 | search/v2 (requires datastore_configs) |
+| respond_with_sources | respond_for_external_actions |
+| call_llm/v0 | call_llm/v2 |
+
+## Anti-Patterns
+
+❌ Cloning random existing persona
+❌ Skipping workflow_def
+❌ Using deprecated actions
+❌ Deploying without preview
+
+${VOICE_TEMPLATE_FIELD_DOCS}
+`;
+        },
+    },
     // Persona Templates - Dynamic from API with fallback
     {
         uri: "ema://catalog/templates",
@@ -798,8 +1130,8 @@ To read a resource, use the \`resources/read\` endpoint:
 | Get input/output compatibility rules | Resource: \`ema://rules/input-sources\` |
 | Get persona templates | Resource: \`ema://catalog/persona-templates\` (API) or Tool: \`template(config="voice")\` |
 | Query live persona data | Tool: \`persona\` |
-| Generate a workflow | Tool: \`workflow\` |
-| Analyze an existing workflow | Tool: \`workflow(mode="analyze")\` |
+| Get workflow data | Tool: \`workflow(mode="get")\` |
+| Deploy workflow | Tool: \`workflow(mode="deploy")\` |
 `;
         return {
             uri: "ema://index/all-resources",