ema-mcp-toolkit 0.2.0

package/dist/mcp/prompts.js

@@ -0,0 +1,1753 @@
+/**
+ * MCP Prompts Registry
+ *
+ * Provides structured prompts for common Ema workflows.
+ *
+ * Prompts are designed to:
+ * - Have clear input schemas with validation
+ * - Reference MCP tools for data fetching
+ * - Produce deterministic, structured outputs
+ * - Not rely on hidden knowledge
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const PROMPTS = {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Clarification & Requirements Gathering
+    // ─────────────────────────────────────────────────────────────────────────
+    requirements_clarify: {
+        definition: {
+            name: "requirements_clarify",
+            description: "Analyze workflow requirements for ambiguity and generate targeted clarification questions. Use before generation/extension when requirements are unclear.",
+            arguments: [
+                {
+                    name: "input",
+                    description: "The natural language requirements or modification request",
+                    required: true,
+                },
+                {
+                    name: "context",
+                    description: "Context type: 'greenfield' (new workflow), 'brownfield' (extend existing), 'optimize' (improve existing)",
+                    required: false,
+                },
+                {
+                    name: "persona_id",
+                    description: "Existing persona ID if brownfield/optimize context",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Analyze the following requirements and determine if clarification is needed before proceeding.
+
+**Input**: ${args.input}
+**Context**: ${args.context || "unknown"}
+${args.persona_id ? `**Existing Persona**: ${args.persona_id}` : ""}
+
+## Clarification Analysis Framework
+
+### Step 1: Parse the Request
+Identify what the user is asking for:
+- **Action Type**: Create new / Extend existing / Optimize / Analyze
+- **Scope**: Single intent / Multi-intent / Full workflow
+- **Specificity**: Vague / Partially specified / Detailed
+
+### Step 2: Check for Required Information
+
+#### For ALL requests, verify:
+| Dimension | Status | Missing Info |
+|-----------|--------|--------------|
+| **Goal/Purpose** | ✓/✗ | What should this accomplish? |
+| **Target Users** | ✓/✗ | Who will interact with this? |
+| **Success Criteria** | ✓/✗ | How do we know it's working? |
+
+#### For GREENFIELD (new workflow):
+| Dimension | Status | Missing Info |
+|-----------|--------|--------------|
+| **Persona Type** | ✓/✗ | Voice, Chat, or Dashboard? |
+| **Primary Intents** | ✓/✗ | What queries should it handle? |
+| **Data Sources** | ✓/✗ | Knowledge base, web search, APIs? |
+| **External Tools** | ✓/✗ | ServiceNow, Salesforce, email? |
+| **Routing Logic** | ✓/✗ | How to handle different intents? |
+| **HITL Requirements** | ✓/✗ | When is human approval needed? |
+| **Fallback Handling** | ✓/✗ | What if no match? |
+
+#### For BROWNFIELD (extend existing):
+| Dimension | Status | Missing Info |
+|-----------|--------|--------------|
+| **Preserve vs Replace** | ✓/✗ | Keep existing intents or modify? |
+| **Integration Points** | ✓/✗ | Where do new features connect? |
+| **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:
+1. **Vague terms**: "better", "smarter", "improved" - what specifically?
+2. **Implicit assumptions**: What does the user assume you know?
+3. **Missing actors**: Who does what in the workflow?
+4. **Undefined triggers**: When does this happen?
+5. **Unclear outputs**: What should the result look like?
+6. **Scope creep**: Multiple unrelated features bundled together
+
+### Step 4: Generate Clarification Questions
+
+Based on gaps identified, generate **targeted questions**:
+
+#### Question Format:
+\`\`\`
+Q: [Specific question]
+Context: [Why this matters]
+Options: [If applicable, provide choices]
+Default: [Reasonable default if user doesn't answer]
+\`\`\`
+
+#### Question Categories:
+
+**Intent & Purpose**:
+- What is the primary goal of this workflow/feature?
+- What problem does this solve for users?
+- How will success be measured?
+
+**User & Interaction**:
+- Who are the users? (internal, external, both)
+- What triggers this workflow? (voice call, chat, scheduled)
+- What should the user experience be like?
+
+**Data & Integration**:
+- What data sources should be searched?
+- What external systems need to be called?
+- What information should be extracted/captured?
+
+**Logic & Flow**:
+- How should different scenarios be handled?
+- When should humans be involved?
+- What happens if [edge case]?
+
+**Constraints**:
+- Are there intents/paths that must NOT change?
+- Are there security/compliance requirements?
+- What's the timeline/urgency?
+
+### Step 5: Decision Output
+
+Based on analysis, output ONE of:
+
+#### A) PROCEED - Requirements are clear
+\`\`\`json
+{
+  "status": "clear",
+  "confidence": "high|medium",
+  "summary": "Brief summary of understood requirements",
+  "inferred_defaults": ["List any assumptions made"],
+  "next_action": "workflow(mode='generate'|'extend'|'optimize', ...)"
+}
+\`\`\`
+
+#### B) CLARIFY - Need more information
+\`\`\`json
+{
+  "status": "needs_clarification",
+  "confidence": "low",
+  "understood": ["What IS clear"],
+  "questions": [
+    {
+      "id": "q1",
+      "question": "...",
+      "context": "...",
+      "options": ["opt1", "opt2"],
+      "default": "opt1",
+      "priority": "required|recommended|nice-to-have"
+    }
+  ],
+  "can_proceed_with_defaults": true|false,
+  "partial_next_action": "If can proceed, what would be called"
+}
+\`\`\`
+
+#### C) DECOMPOSE - Request too complex
+\`\`\`json
+{
+  "status": "needs_decomposition",
+  "reason": "Why this is too complex for one request",
+  "suggested_phases": [
+    {"phase": 1, "scope": "...", "description": "..."},
+    {"phase": 2, "scope": "...", "description": "..."}
+  ],
+  "start_with": "Recommended first phase"
+}
+\`\`\`
+
+## Output Requirements
+
+1. **Always show your analysis** - Don't just ask questions, show what you understood
+2. **Prioritize questions** - Required > Recommended > Nice-to-have
+3. **Provide defaults** - User can accept defaults to proceed faster
+4. **Be specific** - "What email should be sent?" not "Tell me more"
+5. **Limit questions** - Max 5 required questions, don't overwhelm`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // AI Employee Generation
+    // ─────────────────────────────────────────────────────────────────────────
+    ai_employee_generate: {
+        definition: {
+            name: "ai_employee_generate",
+            description: "Generate a complete AI Employee workflow prompt from requirements. Guides through qualifying questions, agent selection, and prompt generation.",
+            arguments: [
+                {
+                    name: "use_case",
+                    description: "Description of what the AI Employee should do (e.g., 'IT helpdesk that creates ServiceNow tickets')",
+                    required: true,
+                },
+                {
+                    name: "persona_type",
+                    description: "Type of AI Employee: 'voice', 'chat', or 'dashboard'",
+                    required: true,
+                },
+                {
+                    name: "intents",
+                    description: "Comma-separated list of intent categories the AI should recognize (optional, will be inferred if not provided)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Generate a complete AI Employee for the following use case:
+
+**Use Case**: ${args.use_case}
+**Persona Type**: ${args.persona_type}
+${args.intents ? `**Intent Categories**: ${args.intents}` : ""}
+
+## Instructions
+
+Follow this MCP-enhanced generation workflow using the **consolidated tools**:
+\`template\`, \`action\`, \`workflow\`, \`persona\`, \`knowledge\`, \`reference\`, \`sync\`.
+
+### Step 1: Gather Requirements
+First, call \`template(questions=true)\` to get structured qualifying questions.
+If persona_type is "voice", also call \`template(questions=true, category="Voice")\`.
+
+Verify you have answers for:
+- AI Type: ${args.persona_type}
+- Intents: ${args.intents || "(to be determined)"}
+- Data Sources: (ask if not clear from use case)
+- Actions: (ask if not clear from use case)
+- Approvals/HITL: (ask if external actions involved)
+
+### Step 2: Select Pattern + Agents
+Call \`action(suggest="${args.use_case}")\` to get recommended agents and a suggested workflow pattern.
+Then call \`template(pattern=<suggested_pattern>)\` to fetch the pattern template.
+
+### Step 3: Get Agent Details
+For each agent in the workflow, call \`action(id=<agent_name>, include_docs=true)\` to get:
+- Inputs and outputs
+- Critical rules
+- Type compatibility requirements
+
+### Step 4: Generate Prompt
+Using the template from Step 2 and agent details from Step 3, generate:
+
+1. **workflow-prompt.md** - Auto Builder prompt with:
+   - Explicit node definitions
+   - Explicit connections
+   - Results mapping to WORKFLOW_OUTPUT
+   - Validation assertions
+
+2. **persona-config.json** - ${args.persona_type === "voice" ? "Voice settings (welcomeMessage, identityAndPurpose, takeActionInstructions, hangupInstructions)" : args.persona_type === "chat" ? "Chat settings (chatbotSdkConfig, feedbackMessage)" : "Dashboard settings (inputSchema, batchSettings)"}
+
+### Step 5: Validate
+Call \`reference(validate_prompt=<generated_prompt>)\` to check for:
+- Missing Fallback category
+- Type mismatches
+- Incomplete categorizer routing
+- Missing WORKFLOW_OUTPUT mapping
+
+Call \`reference(mistakes=true)\` for final verification.
+
+## Output Format
+
+Produce a folder structure:
+\`\`\`
+{persona-name}/
+├── README.md           # Deployment guide
+├── workflow-prompt.md  # Auto Builder prompt
+├── persona-config.json # ${args.persona_type} settings
+└── docs/              # Knowledge base (if needed)
+\`\`\`
+
+Now begin by calling the MCP tools to gather the necessary information.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Workflow Review
+    // ─────────────────────────────────────────────────────────────────────────
+    workflow_review: {
+        definition: {
+            name: "workflow_review",
+            description: "Review an existing AI Employee workflow for issues, detect problems (loops, deadlocks, type mismatches), and propose fixes.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID of the AI Employee to review",
+                    required: true,
+                },
+                {
+                    name: "env",
+                    description: "Environment to fetch from (default: demo). Options: demo, dev, staging",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Review the workflow for AI Employee: ${args.persona_id}
+Environment: ${args.env || "demo"}
+
+## Instructions
+
+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 2: Analyze (Issues + Connections + Fixes + Metrics)
+Call \`workflow(mode="analyze", persona_id="${args.persona_id}", env="${args.env || "demo"}")\`.
+
+### 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"}")\`.
+
+## Output Format
+
+\`\`\`markdown
+## Workflow Review: {Persona Name}
+
+**Environment**: ${args.env || "demo"}
+**Persona ID**: ${args.persona_id}
+**Review Date**: {date}
+
+### Summary
+
+| Category | Status | Issues |
+|----------|--------|--------|
+| Graph Structure | ✅/⚠️/❌ | {count} |
+| Routing | ✅/⚠️/❌ | {count} |
+| Type Compatibility | ✅/⚠️/❌ | {count} |
+| HITL Patterns | ✅/⚠️/❌ | {count} |
+
+### Critical Issues (Must Fix)
+{list with location, impact, fix}
+
+### Warnings (Should Fix)
+{list with location, impact, fix}
+
+### Proposed Fixes
+{Before/After YAML for each fix}
+
+### Next Steps
+1. [ ] Apply critical fixes
+2. [ ] Test in simulator
+3. [ ] Validate all paths work
+\`\`\`
+
+Now begin by fetching the workflow.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Debug Workflow
+    // ─────────────────────────────────────────────────────────────────────────
+    workflow_debug: {
+        definition: {
+            name: "workflow_debug",
+            description: "Debug workflow issues with step-by-step guidance based on symptoms.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID of the AI Employee with issues",
+                    required: true,
+                },
+                {
+                    name: "symptoms",
+                    description: "Description of the problem (e.g., 'responses are empty', 'categorizer not routing correctly', 'HITL approval breaks')",
+                    required: true,
+                },
+                {
+                    name: "env",
+                    description: "Environment (default: demo)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Debug workflow issues for AI Employee: ${args.persona_id}
+
+**Symptoms**: ${args.symptoms}
+**Environment**: ${args.env || "demo"}
+
+## Instructions
+
+### Step 1: Get Debug Checklist
+Call \`reference(checklist=true)\` to get the systematic debugging guide.
+
+### Step 2: Fetch Workflow
+Call \`persona(id="${args.persona_id}", include_workflow=true, env="${args.env || "demo"}")\`.
+
+### Step 3: Analyze Based on Symptoms
+
+Based on the symptoms "${args.symptoms}", focus on:
+
+${args.symptoms.toLowerCase().includes("empty") || args.symptoms.toLowerCase().includes("no response") ? `
+**Empty/No Response Issues:**
+- Check if all paths reach WORKFLOW_OUTPUT
+- Verify results mapping is correct
+- Look for dead-end nodes
+- Check if categorizer has edges for all categories
+` : ""}
+${args.symptoms.toLowerCase().includes("categoriz") || args.symptoms.toLowerCase().includes("routing") || args.symptoms.toLowerCase().includes("intent") ? `
+**Categorizer/Routing Issues:**
+- Check categorizer input source (must be chat_conversation, NOT user_query)
+- Verify all categories have outgoing edges
+- Check for missing Fallback category
+- Verify category names match exactly in edges
+` : ""}
+${args.symptoms.toLowerCase().includes("hitl") || args.symptoms.toLowerCase().includes("approval") ? `
+**HITL/Approval Issues:**
+- Check both success AND failure paths exist
+- Verify 'hitl_status_HITL Success' and 'hitl_status_HITL Failure' edges (note: space, not underscore)
+- Check if HITL node receives correct inputs
+- Unlike regular categorizers, HITL has NO Fallback category
+` : ""}
+${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
+- 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:**
+- Check for circular dependencies in edges
+- Look for nodes that reference themselves
+- 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 5: Propose Fix
+Based on findings, provide specific fix with before/after configuration.
+
+## Output Format
+
+\`\`\`markdown
+## Debug Report: {Persona Name}
+
+### Symptoms
+${args.symptoms}
+
+### Root Cause
+{explanation of what's causing the issue}
+
+### Diagnosis
+{step-by-step what was found}
+
+### Fix
+
+**Before:**
+\`\`\`yaml
+{problematic configuration}
+\`\`\`
+
+**After:**
+\`\`\`yaml
+{fixed configuration}
+\`\`\`
+
+### Verification Steps
+1. Apply the fix
+2. {specific test to verify}
+3. {additional validation}
+\`\`\`
+
+Now begin debugging.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Sync Persona
+    // ─────────────────────────────────────────────────────────────────────────
+    persona_sync: {
+        definition: {
+            name: "persona_sync",
+            description: "Sync an AI Employee from source to target environment with change detection.",
+            arguments: [
+                {
+                    name: "persona_name",
+                    description: "Name of the AI Employee to sync",
+                    required: true,
+                },
+                {
+                    name: "target_env",
+                    description: "Target environment (e.g., 'dev', 'staging')",
+                    required: true,
+                },
+                {
+                    name: "source_env",
+                    description: "Source environment (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "dry_run",
+                    description: "If 'true', simulate without making changes (default: false)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Sync AI Employee "${args.persona_name}" to ${args.target_env}
+
+**Source**: ${args.source_env || "demo"}
+**Target**: ${args.target_env}
+**Dry Run**: ${args.dry_run === "true" ? "Yes" : "No"}
+
+## Instructions
+
+### Step 1: Verify Source Exists
+Call \`persona(id="${args.persona_name}", env="${args.source_env || "demo"}")\` to verify the AI Employee exists and to retrieve its ID.
+
+### Step 2: Check Sync Status
+Call \`sync(mode="status", id="${args.persona_name}", env="${args.target_env}")\` to see whether the target environment already has a synced copy and what it’s synced from.
+
+### Step 3: Preview Changes (if not dry run)
+Run a dry-run sync to preview:
+\`sync(id="${args.persona_name}", source="${args.source_env || "demo"}", target="${args.target_env}", dry_run=true)\`
+
+### Step 4: Execute Sync
+Call \`sync(id="${args.persona_name}", source="${args.source_env || "demo"}", target="${args.target_env}", dry_run=${args.dry_run === "true"})\`.
+
+### Step 5: Verify (if not dry run)
+After sync, call \`sync(mode="status", id="${args.persona_name}", env="${args.target_env}")\` to verify the sync metadata/tag was applied.
+
+## Output Format
+
+\`\`\`markdown
+## Sync Report: ${args.persona_name}
+
+| Field | Value |
+|-------|-------|
+| Source | ${args.source_env || "demo"} |
+| Target | ${args.target_env} |
+| Status | {Created/Updated/No Changes} |
+| Dry Run | ${args.dry_run === "true" ? "Yes" : "No"} |
+
+### Changes
+{list of changes made or would be made}
+
+### Sync Tag
+\`\`\`
+<!-- synced_from:${args.source_env || "demo"}/{source_id} -->
+\`\`\`
+\`\`\`
+
+Now begin the sync process.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Compare Personas
+    // ─────────────────────────────────────────────────────────────────────────
+    persona_compare: {
+        definition: {
+            name: "persona_compare",
+            description: "Compare two AI Employees to see differences in configuration and workflow.",
+            arguments: [
+                {
+                    name: "persona_id_1",
+                    description: "ID of the first AI Employee",
+                    required: true,
+                },
+                {
+                    name: "persona_id_2",
+                    description: "ID of the second AI Employee",
+                    required: true,
+                },
+                {
+                    name: "env_1",
+                    description: "Environment for first persona (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "env_2",
+                    description: "Environment for second persona (default: same as env_1)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Compare two AI Employees:
+
+**Persona 1**: ${args.persona_id_1} (${args.env_1 || "demo"})
+**Persona 2**: ${args.persona_id_2} (${args.env_2 || args.env_1 || "demo"})
+
+## Instructions
+
+### Step 1: Fetch Both Personas
+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 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.
+
+## Output Format
+
+\`\`\`markdown
+## Comparison Report
+
+### Personas
+
+| Field | Persona 1 | Persona 2 |
+|-------|-----------|-----------|
+| Name | {name1} | {name2} |
+| Environment | ${args.env_1 || "demo"} | ${args.env_2 || args.env_1 || "demo"} |
+| Status | {status1} | {status2} |
+| Trigger Type | {trigger1} | {trigger2} |
+
+### Configuration Differences
+{list of field differences}
+
+### Workflow Differences
+{structural changes: nodes added/removed/modified, edges changed}
+
+### Recommendations
+{which version is preferred and why}
+\`\`\`
+
+Now begin the comparison.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Validate Prompt
+    // ─────────────────────────────────────────────────────────────────────────
+    prompt_validate: {
+        definition: {
+            name: "prompt_validate",
+            description: "Validate an Auto Builder workflow prompt for common errors before submission.",
+            arguments: [
+                {
+                    name: "prompt",
+                    description: "The Auto Builder prompt text to validate",
+                    required: true,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Validate this Auto Builder prompt:
+
+\`\`\`
+${args.prompt}
+\`\`\`
+
+## Instructions
+
+### Step 1: Run Validation
+Call \`reference(validate_prompt=<the_prompt>)\` to check for:
+- Missing Fallback category
+- Type mismatches in connections
+- Incomplete categorizer routing
+- Missing WORKFLOW_OUTPUT mapping
+- HITL without both success/failure paths
+
+### Step 2: Check Common Mistakes
+Call \`reference(mistakes=true)\` and verify the prompt doesn't have:
+1. Missing Fallback category
+2. Missing HITL on sensitive actions
+3. Wrong input sources (user_query vs chat_conversation)
+4. Duplicate record creation on follow-ups
+
+### Step 3: Verify Type Compatibility
+For each connection in the prompt, verify types are compatible:
+- chat_trigger.chat_conversation → chat_categorizer.conversation ✓
+- chat_trigger.user_query → search.query ✓
+- search.search_results → respond_with_sources.search_results ✓
+
+## Output Format
+
+\`\`\`markdown
+## Validation Report
+
+### Overall Status: ✅ PASS / ⚠️ WARNINGS / ❌ FAIL
+
+### Issues Found
+
+#### Critical (Must Fix)
+{list or "None"}
+
+#### Warnings (Should Fix)
+{list or "None"}
+
+#### Suggestions (Optional)
+{list or "None"}
+
+### Type Compatibility Check
+| Connection | Status |
+|------------|--------|
+{table of connections and their status}
+
+### Recommendations
+{specific fixes if issues found}
+\`\`\`
+
+Now run the validation.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Onboard to Toolkit
+    // ─────────────────────────────────────────────────────────────────────────
+    toolkit_onboard: {
+        definition: {
+            name: "toolkit_onboard",
+            description: "Get started with the Ema MCP Toolkit. Provides setup instructions, available tools, and common workflows.",
+            arguments: [],
+        },
+        render: () => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Help me get started with the Ema MCP Toolkit.
+
+## Instructions
+
+### Step 1: Read the README
+Fetch the resource \`ema://docs/readme\` to understand the toolkit overview.
+
+### Step 2: List Available Environments
+Call \`env()\` to see configured environments.
+
+### Step 3: Explore Platform Concepts
+Call \`reference(concepts=true)\` to understand key terminology:
+- AI Employee (Persona)
+- Action (Agent)
+- Workflow
+- HITL
+- Sync Tags
+
+### Step 4: Show Key Workflows
+
+Provide examples of common tasks:
+
+1. **List AI Employees**: \`persona(all=true, env="demo")\`
+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")\`
+
+## Output Format
+
+\`\`\`markdown
+# Ema MCP Toolkit Quickstart
+
+## Setup Complete ✓
+
+| Environment | Status |
+|-------------|--------|
+{table of environments}
+
+## Key Concepts
+
+{brief explanation of each concept}
+
+## Common Commands
+
+### Browse AI Employees
+\`\`\`
+persona(all=true, env="demo")
+persona(query="support", env="demo")
+\`\`\`
+
+### Generate New AI Employee
+Use the \`generate_ai_employee\` prompt with:
+- use_case: what it should do
+- persona_type: voice/chat/dashboard
+
+### Review Existing Workflow
+Use the \`review_workflow\` prompt with:
+- persona_id: the ID to review
+- env: environment
+
+### Sync Across Environments
+Use the \`sync_persona\` prompt with:
+- persona_name: name to sync
+- target_env: destination
+
+## Next Steps
+
+1. Try listing AI Employees in demo
+2. Pick one and review its workflow
+3. Generate a new AI Employee for your use case
+\`\`\`
+
+Now provide the onboarding guide.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Create Voice AI
+    // ─────────────────────────────────────────────────────────────────────────
+    persona_create_voice: {
+        definition: {
+            name: "persona_create_voice",
+            description: "Create a Voice AI Employee with conversation settings, tool calling, and voice configuration.",
+            arguments: [
+                {
+                    name: "name",
+                    description: "Name for the Voice AI (e.g., 'IT Support Assistant')",
+                    required: true,
+                },
+                {
+                    name: "purpose",
+                    description: "What the Voice AI should do (e.g., 'Help employees reset passwords and create IT tickets')",
+                    required: true,
+                },
+                {
+                    name: "intents",
+                    description: "Comma-separated intent categories (e.g., 'Password Reset, Create Ticket, Check Status')",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Create a Voice AI Employee:
+
+**Name**: ${args.name}
+**Purpose**: ${args.purpose}
+${args.intents ? `**Intents**: ${args.intents}` : ""}
+
+## Instructions
+
+### Step 1: Read Templates (Resources)
+Read these resources to get templates and reference data:
+- \`ema://templates/voice-ai/config\` - Voice AI persona configuration template
+- \`ema://templates/voice-ai/workflow-prompt\` - Auto Builder prompt template with safeguards
+- \`ema://templates/voice-ai/readme\` - Deployment guide template
+- \`ema://catalog/agents-summary\` - Available agents for workflow composition
+
+### Step 2: Read Validation Rules (Resources)
+Read these resources to ensure correct workflow design:
+- \`ema://rules/input-sources\` - Which agent inputs accept which data types
+- \`ema://rules/anti-patterns\` - Common mistakes to avoid
+
+### Step 3: Get Agent Recommendations (Tool)
+Call \`action(suggest="${args.purpose}")\` for recommended agents and pattern.
+
+### Step 4: Get Voice-Specific Guidance (Tool)
+Call \`template(questions=true, category="Voice")\` for Voice AI specific requirements.
+Call \`reference(guidance="voice-tool-calling")\` for tool calling rules:
+1. Collect all parameters before calling tool
+2. Wait for response before next tool
+3. Never mention tool names to caller
+4. Handle delays with "Just a moment..."
+
+### Step 5: Generate Output
+Using the templates from Step 1 and guidance from Steps 3-4, generate:
+
+**Folder structure:**
+\`\`\`
+${args.name.toLowerCase().replace(/\s+/g, "-")}/
+├── README.md              # Deployment guide (based on ema://templates/voice-ai/readme)
+├── workflow-prompt.md     # Auto Builder prompt (based on ema://templates/voice-ai/workflow-prompt)
+├── persona-config.json    # Voice settings (based on ema://templates/voice-ai/config)
+└── proto-config.json      # Full API config
+\`\`\`
+
+### Step 6: Validate
+Call \`reference(validate_prompt=<generated_prompt>)\` to verify the prompt.
+
+Now begin by reading the resources, then proceed with generation.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Create Chat AI
+    // ─────────────────────────────────────────────────────────────────────────
+    persona_create_chat: {
+        definition: {
+            name: "persona_create_chat",
+            description: "Create a Chat AI Employee with knowledge base search and web widget.",
+            arguments: [
+                {
+                    name: "name",
+                    description: "Name for the Chat AI (e.g., 'Product FAQ Bot')",
+                    required: true,
+                },
+                {
+                    name: "purpose",
+                    description: "What the Chat AI should do (e.g., 'Answer questions about products from documentation')",
+                    required: true,
+                },
+                {
+                    name: "data_sources",
+                    description: "Comma-separated data sources (e.g., 'Product docs, FAQ pages, Help articles')",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Create a Chat AI Employee:
+
+**Name**: ${args.name}
+**Purpose**: ${args.purpose}
+${args.data_sources ? `**Data Sources**: ${args.data_sources}` : ""}
+
+## Instructions
+
+### Step 1: Read Templates (Resources)
+Read these resources to get templates and reference data:
+- \`ema://templates/chat-ai/config\` - Chat AI persona configuration template
+- \`ema://templates/chat-ai/readme\` - Deployment guide template
+- \`ema://catalog/agents-summary\` - Available agents for workflow composition
+- \`ema://catalog/patterns\` - Common workflow patterns
+
+### Step 2: Read Validation Rules (Resources)
+Read these resources to ensure correct workflow design:
+- \`ema://rules/input-sources\` - Which agent inputs accept which data types
+- \`ema://rules/anti-patterns\` - Common mistakes to avoid
+
+### Step 3: Get Agent Recommendations (Tool)
+Call \`action(suggest="${args.purpose}")\` for recommended agents and pattern.
+
+### Step 4: Get Guidance (Tool)
+Call \`reference(guidance="conversation-vs-query")\` to understand:
+- When to use user_query vs chat_conversation
+- Search input requirements
+
+### Step 5: Generate Output
+Using the templates from Step 1 and guidance from Steps 3-4, generate:
+
+**Folder structure:**
+\`\`\`
+${args.name.toLowerCase().replace(/\s+/g, "-")}/
+├── README.md              # Deployment guide (based on ema://templates/chat-ai/readme)
+├── workflow-prompt.md     # Auto Builder prompt
+├── persona-config.json    # Chat settings (based on ema://templates/chat-ai/config)
+└── docs/                  # Knowledge base documents
+    └── _metadata.json
+\`\`\`
+
+### Step 6: Validate
+Call \`reference(validate_prompt=<generated_prompt>)\` to verify the prompt.
+
+Now begin by reading the resources, then proceed with generation.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Direct Workflow Generation (Bypasses Auto Builder)
+    // ─────────────────────────────────────────────────────────────────────────
+    workflow_generate: {
+        definition: {
+            name: "workflow_generate",
+            description: "Generate a complete workflow_def and proto_config directly, bypassing Auto Builder. Produces ready-to-deploy JSON configurations.",
+            arguments: [
+                {
+                    name: "name",
+                    description: "Name for the AI Employee",
+                    required: true,
+                },
+                {
+                    name: "description",
+                    description: "What the AI Employee does",
+                    required: true,
+                },
+                {
+                    name: "persona_type",
+                    description: "Type: 'voice', 'chat', or 'dashboard'",
+                    required: true,
+                },
+                {
+                    name: "pattern",
+                    description: "Workflow pattern: 'kb_search' (FAQ/docs), 'intent_routing' (multi-intent), 'tool_calling' (external actions)",
+                    required: true,
+                },
+                {
+                    name: "intents",
+                    description: "For intent_routing: comma-separated intent names with handler type, e.g., 'Search:search,Help:llm,Transfer:fixed'",
+                    required: false,
+                },
+                {
+                    name: "tools",
+                    description: "For tool_calling: comma-separated tool names with namespace, e.g., 'Create_Ticket:service_now,Send_Email:outlook'",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Generate a complete workflow configuration for: ${args.name}
+
+**Description**: ${args.description}
+**Persona Type**: ${args.persona_type}
+**Pattern**: ${args.pattern}
+${args.intents ? `**Intents**: ${args.intents}` : ""}
+${args.tools ? `**Tools**: ${args.tools}` : ""}
+
+## Instructions
+
+Generate deployment-ready JSON using the consolidated \`workflow\` tool (local compiler):
+
+### Step 1: Generate workflow_def + proto_config (Direct / Deterministic)
+Call:
+\`workflow(input=<requirements>, type="${args.persona_type}", use_autobuilder=false)\`
+
+Where \`<requirements>\` includes:
+- Name: ${args.name}
+- Description: ${args.description}
+- Pattern hint: ${args.pattern}
+${args.intents ? `- Intents: ${args.intents}` : ""}
+${args.tools ? `- Tools: ${args.tools}` : ""}
+
+If the tool returns \`status="needs_input"\`, ask the missing questions, then call \`workflow(...)\` again with the additional details.
+
+### Step 2: (Optional) Validate the generated workflow
+Call \`workflow(mode="analyze", workflow_def=<workflow_def>)\` and fix any critical issues before deploying.
+
+### Step 3: Deploy (Optional)
+If you already have a persona, deploy directly:
+\`workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>)\`
+
+If you need to create one first:
+\`persona(mode="create", name="${args.name}", type="${args.persona_type}")\`
+then deploy as above.
+
+## Output Format
+
+Provide the final configurations in this format:
+
+\`\`\`json
+// workflow_def.json
+{workflow_def}
+\`\`\`
+
+\`\`\`json
+// proto_config.json
+{proto_config}
+\`\`\`
+
+Now generate by calling \`workflow(input=<requirements>, type="${args.persona_type}", use_autobuilder=false)\`.`,
+                },
+            },
+        ],
+    },
+    workflow_deploy: {
+        definition: {
+            name: "workflow_deploy",
+            description: "Deploy a generated workflow to an Ema environment. Takes workflow_def and proto_config and creates/updates an AI Employee.",
+            arguments: [
+                {
+                    name: "name",
+                    description: "Name for the AI Employee",
+                    required: true,
+                },
+                {
+                    name: "env",
+                    description: "Target environment (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "update_existing",
+                    description: "If 'true', update existing AI Employee with same name instead of creating new",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Deploy workflow configuration for: ${args.name}
+
+**Target Environment**: ${args.env || "demo"}
+**Update Existing**: ${args.update_existing === "true" ? "Yes" : "No (create new)"}
+
+## Instructions
+
+### Pre-Deploy Checklist
+
+Before deploying, ensure you have:
+1. ✅ Generated workflow_def using workflow_generate prompt
+2. ✅ Generated proto_config/persona settings
+3. ✅ Validated the workflow (no critical issues)
+
+### Step 1: Check for Existing
+
+${args.update_existing === "true" ? `
+Call \`persona(id="${args.name}", env="${args.env || "demo"}")\`
+to find the existing AI Employee (and capture its persona ID).
+` : `
+Call \`persona(query="${args.name}", env="${args.env || "demo"}")\`
+to check whether an AI Employee with this name already exists (and capture the persona ID if present).
+`}
+
+### Step 2: Create or Update
+
+${args.update_existing === "true" ? `
+If not found, create it:
+\`persona(mode="create", name="${args.name}", type="chat", env="${args.env || "demo"}")\`
+` : `
+Create a new AI Employee:
+\`persona(mode="create", name="${args.name}", type="chat", env="${args.env || "demo"}")\`
+`}
+
+### Step 3: Configure Workflow
+
+Deploy the workflow via MCP:
+\`workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>, env="${args.env || "demo"}")\`
+
+### Step 4: Test
+
+After deployment:
+1. Open the AI Employee in simulator
+2. Test each intent/path
+3. Verify responses are correct
+4. Check HITL flows work (if applicable)
+
+### Step 5: Activate
+
+Once tested:
+1. Call \`persona(id="<persona_id>", mode="update", enabled=true, env="${args.env || "demo"}")\`
+2. Monitor initial conversations
+3. Iterate based on feedback
+
+## Deployment Summary
+
+Provide a deployment summary including:
+- AI Employee ID (if created/updated)
+- Environment
+- Workflow configuration details
+- Test results
+- Next steps
+
+Now proceed with deployment.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Workflow Understanding & Extension
+    // ─────────────────────────────────────────────────────────────────────────
+    workflow_explain: {
+        definition: {
+            name: "workflow_explain",
+            description: "Analyze and explain a workflow's purpose, logic, data flow, and outputs. Essential for understanding intent before making modifications.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID of the AI Employee to explain (use with env)",
+                    required: false,
+                },
+                {
+                    name: "workflow_def",
+                    description: "Raw workflow_def JSON to explain (alternative to persona_id)",
+                    required: false,
+                },
+                {
+                    name: "env",
+                    description: "Environment: 'demo', 'staging', 'prod' (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "depth",
+                    description: "Analysis depth: 'summary', 'detailed', 'full' (default: detailed)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Analyze and explain the following workflow comprehensively.
+
+${args.persona_id ? `**Persona ID**: ${args.persona_id}` : ""}
+${args.env ? `**Environment**: ${args.env}` : ""}
+${args.depth ? `**Analysis Depth**: ${args.depth}` : "**Analysis Depth**: detailed"}
+${args.workflow_def ? `**Workflow Definition**: Provided inline` : ""}
+
+## Instructions
+
+${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"}")\`
+` : ""}
+
+## Required Analysis Sections
+
+### 1. PURPOSE & GOALS
+Explain the workflow's primary purpose:
+- **What problem does it solve?** (e.g., "Handles IT support requests via voice")
+- **Who is the target user?** (e.g., "Employees seeking IT help")
+- **What outcomes does it produce?** (e.g., "Creates tickets, provides answers")
+- **Business value**: Why does this workflow exist?
+
+### 2. INTENT CLASSIFICATION
+Identify and explain the routing logic:
+- **Categories/Intents**: List all categories the chat_categorizer handles
+- **Trigger conditions**: What phrases/conditions route to each intent?
+- **Fallback handling**: How are unmatched queries handled?
+
+### 3. DATA FLOW ANALYSIS
+Map how data moves through the workflow:
+- **Input sources**: Where data enters (trigger, user_query, chat_conversation)
+- **Transformations**: How data is processed (search, LLM, extraction)
+- **Output destinations**: Where results go (responses, external systems)
+
+Create a simplified flow diagram:
+\`\`\`
+trigger → categorizer → [branch based on intent]
+                      ├→ search → respond_with_sources
+                      ├→ tool_caller → confirmation
+                      └→ fallback → escalation
+\`\`\`
+
+### 4. NODE ANALYSIS
+For each action node, explain:
+- **Purpose**: What this node does
+- **Inputs**: What data it receives and from where
+- **Outputs**: What it produces
+- **Dependencies**: What must run before it
+
+### 5. EXTERNAL INTEGRATIONS
+Identify external systems:
+- **Tools**: List external_action_caller tools (e.g., ServiceNow, Salesforce)
+- **Data sources**: Knowledge bases, web search, APIs
+- **Output channels**: Email, notifications, ticket systems
+
+### 6. LOGIC & DECISION POINTS
+Explain conditional logic:
+- **Routing decisions**: How categorizer routes to different paths
+- **Conditional branches**: Any switch/if logic
+- **HITL gates**: Where human intervention is required
+- **Validation checks**: Data validation before actions
+
+### 7. OUTPUTS & RESULTS
+What the workflow produces:
+- **Primary output**: Main response to user
+- **Side effects**: Tickets created, emails sent, etc.
+- **Success criteria**: How to know workflow succeeded
+
+### 8. OPTIMIZATION OPPORTUNITIES
+Based on analysis, identify:
+- **Redundancies**: Duplicate processing, unnecessary nodes
+- **Type mismatches**: Input/output type conflicts
+- **Missing error handling**: Unhandled edge cases
+- **Performance concerns**: Sequential operations that could parallelize
+
+## Output Format
+
+Provide a structured explanation that can be used to:
+1. Onboard new developers to understand the workflow
+2. Guide modifications and extensions
+3. Inform optimization decisions
+4. Document the system for stakeholders
+
+Include a one-paragraph executive summary at the start.`,
+                },
+            },
+        ],
+    },
+    workflow_extend: {
+        definition: {
+            name: "workflow_extend",
+            description: "Extend an existing workflow with new capabilities while preserving existing logic. Guides through understanding current state, planning additions, and implementing changes.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID of the AI Employee to extend",
+                    required: true,
+                },
+                {
+                    name: "requirements",
+                    description: "Description of new capabilities to add",
+                    required: true,
+                },
+                {
+                    name: "env",
+                    description: "Environment: 'demo', 'staging', 'prod' (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "preserve_intents",
+                    description: "Comma-separated list of intents that must not be modified",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Extend an existing AI Employee workflow with new capabilities.
+
+**Persona ID**: ${args.persona_id}
+**Environment**: ${args.env || "demo"}
+**New Requirements**:
+${args.requirements}
+${args.preserve_intents ? `**Protected Intents**: ${args.preserve_intents}` : ""}
+
+## Phase 0: Clarification Checkpoint
+
+**BEFORE proceeding, analyze the requirements for clarity:**
+
+### Requirement Clarity Checklist:
+| Aspect | Clear? | If Unclear, Ask |
+|--------|--------|-----------------|
+| **What to add** | ✓/✗ | "What specific capability should be added?" |
+| **Where it connects** | ✓/✗ | "Should this run before/after/parallel to existing logic?" |
+| **Trigger conditions** | ✓/✗ | "When should this new feature activate?" |
+| **Data requirements** | ✓/✗ | "What data does this need? From where?" |
+| **Output expectations** | ✓/✗ | "What should the result look like?" |
+| **Preservation rules** | ✓/✗ | "Which existing paths must remain unchanged?" |
+
+### If requirements are UNCLEAR:
+Ask clarification questions BEFORE fetching the workflow:
+\`\`\`
+Questions to resolve:
+1. [Most critical missing info]
+2. [Second priority]
+3. [Nice to have]
+
+Defaults I'll use if you don't specify:
+- [Default 1]
+- [Default 2]
+
+Reply with answers, or say "proceed with defaults"
+\`\`\`
+
+### If requirements are CLEAR:
+Proceed to Phase 1.
+
+---
+
+## Phase 1: Understand Current State
+
+### 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"}")
+\`\`\`
+
+### Step 1.2: Document Existing Logic
+Before making changes, document:
+- **Current intents**: List all categories and their handlers
+- **Data flow**: How data moves trigger → response
+- **External integrations**: Tools, APIs, data sources
+- **Output structure**: What the workflow produces
+
+### Step 1.3: Identify Impact Points
+Based on the requirements, identify:
+- **New nodes needed**: What actions to add
+- **Existing nodes affected**: What needs modification
+- **New intents/categories**: Routing changes
+- **New data sources**: Additional inputs needed
+
+### Step 1.4: Clarification Round 2 (Post-Analysis)
+After understanding the existing workflow, check if NEW questions arise:
+- Does the request conflict with existing logic?
+- Are there dependencies that weren't obvious?
+- Is the scope larger than initially understood?
+
+If new ambiguities found, pause and clarify before Phase 2.
+
+---
+
+## Phase 2: Plan Extensions
+
+### Step 2.1: Gap Analysis
+Compare current state to requirements:
+| Requirement | Current State | Gap | Solution |
+|-------------|--------------|-----|----------|
+| [requirement 1] | [exists/missing] | [what's missing] | [how to add] |
+
+### Step 2.2: Agent Selection
+For each new capability, identify the right agent:
+\`action(mode="recommend", capability="<required_capability>")\`
+
+Common agents for extensions:
+- **text_categorizer**: Actor/role identification
+- **entity_extraction_with_documents**: Extract structured data
+- **json_mapper**: Transform data structures
+- **live_web_search**: Real-time data
+- **combine_search_results**: Merge multiple sources
+- **personalized_content_generator**: Rich content generation
+- **custom_agent**: Complex logic with custom prompts
+- **send_email_agent**: Email notifications
+- **call_llm**: Flexible LLM processing
+
+### Step 2.3: Design Data Flow
+For new capabilities:
+1. **Inputs**: What data they need
+2. **Processing**: What transformations occur
+3. **Outputs**: What they produce
+4. **Connections**: How they connect to existing nodes
+
+## Phase 3: Implement Extensions
+
+### Step 3.1: Preserve Existing Logic
+${args.preserve_intents ? `
+**CRITICAL**: Do NOT modify these intents: ${args.preserve_intents}
+
+These handlers must remain unchanged:
+- Keep their categorizer conditions
+- Keep their node connections
+- Keep their output mappings
+` : `
+Review existing intents and preserve:
+- Working routing logic
+- Validated data flows
+- Tested integrations
+`}
+
+### Step 3.2: Add New Capabilities
+For each new requirement:
+
+1. **Add nodes**: Insert new action nodes with proper:
+   - Unique names (e.g., \`actor_identifier\`, \`entity_extractor\`)
+   - Correct action types from the agent catalog
+   - Input bindings from existing nodes or trigger
+
+2. **Update routing**: Modify categorizer to include new categories:
+   - Add category definitions
+   - Define routing conditions
+   - Add example phrases
+
+3. **Connect data flow**: Wire inputs/outputs:
+   - Use \`actionOutput\` bindings
+   - Use \`multiBinding\` for multiple inputs
+   - Use \`named_inputs\` for additional context
+
+### Step 3.3: Generate Extended Workflow
+\`\`\`
+workflow(
+  persona_id="${args.persona_id}",
+  mode="generate",
+  input="<detailed requirements with current workflow context>",
+  env="${args.env || "demo"}"
+)
+\`\`\`
+
+## Phase 4: Validate & Deploy
+
+### Step 4.1: Analyze Changes
+\`workflow(persona_id="${args.persona_id}", mode="analyze")\`
+
+Verify:
+- [ ] No type mismatches
+- [ ] No broken connections
+- [ ] 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.3: Deploy
+\`workflow(persona_id="${args.persona_id}", mode="deploy", workflow_def=<extended_workflow>)\`
+
+## Extension Patterns
+
+### Pattern: Add Actor Identification
+\`\`\`
+trigger → text_categorizer(actor) → [client|advisor|unknown]
+                                   ├→ known_actor → continue_flow
+                                   └→ unknown → call_llm(identify) → validate
+\`\`\`
+
+### Pattern: Add Entity Extraction
+\`\`\`
+trigger → entity_extraction_with_documents → json_mapper → downstream_nodes
+\`\`\`
+
+### Pattern: Add Parallel Search
+\`\`\`
+trigger → [parallel]
+          ├→ search(kb)
+          └→ live_web_search
+          combine_search_results → respond
+\`\`\`
+
+### Pattern: Add Email Notification
+\`\`\`
+response_node → fixed_response(email_parts) → send_email_agent
+\`\`\`
+
+### Pattern: Add Multi-Branch Merger
+\`\`\`
+categorizer → [intent_a, intent_b, intent_c]
+              ↓
+           call_llm(merger) → unified_response
+\`\`\`
+
+## Output Requirements
+
+Provide:
+1. **Extension Plan**: Detailed steps for each new capability
+2. **Node Additions**: Specific nodes to add with configurations
+3. **Routing Changes**: Updated categorizer categories
+4. **Data Flow Diagram**: Visual representation of extended workflow
+5. **Validation Checklist**: Tests for new and existing functionality
+6. **Deployment Commands**: Ready-to-execute MCP commands`,
+                },
+            },
+        ],
+    },
+    workflow_analyze_intent: {
+        definition: {
+            name: "workflow_analyze_intent",
+            description: "Deep analysis of workflow intent, goals, and business logic. Use before optimization to understand the 'why' behind the workflow structure.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID of the AI Employee to analyze",
+                    required: true,
+                },
+                {
+                    name: "env",
+                    description: "Environment: 'demo', 'staging', 'prod' (default: demo)",
+                    required: false,
+                },
+                {
+                    name: "focus",
+                    description: "Focus area: 'routing', 'data_flow', 'integrations', 'outputs', 'all' (default: all)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Perform deep intent analysis on a workflow to understand its purpose and business logic.
+
+**Persona ID**: ${args.persona_id}
+**Environment**: ${args.env || "demo"}
+**Focus Area**: ${args.focus || "all"}
+
+## 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"}")
+\`\`\`
+
+## Step 2: Intent Analysis Framework
+
+### Business Intent Layer
+Answer these questions:
+1. **Primary Mission**: What is this AI Employee's main job?
+2. **User Journey**: What experience should users have?
+3. **Success Metrics**: How do we measure this workflow working?
+4. **Failure Modes**: What happens when things go wrong?
+
+### Functional Intent Layer
+For each major path in the workflow:
+1. **Trigger Condition**: What initiates this path?
+2. **Processing Goal**: What transformation happens?
+3. **Expected Outcome**: What should result?
+4. **Side Effects**: What else happens (tickets, emails, logs)?
+
+### Technical Intent Layer
+For each node:
+1. **Why this agent?**: Why was this specific action type chosen?
+2. **Data requirements**: What inputs are essential vs optional?
+3. **Output usage**: Where does this node's output go?
+4. **Error handling**: What happens if this node fails?
+
+## Step 3: Intent Mapping
+
+Create an intent map:
+\`\`\`
+WORKFLOW: [Name]
+├── GOAL: [Primary business goal]
+├── USERS: [Target user types]
+├── INTENTS:
+│   ├── [Intent 1]: [Business purpose]
+│   │   └── PATH: trigger → [nodes] → [outcome]
+│   ├── [Intent 2]: [Business purpose]
+│   │   └── PATH: trigger → [nodes] → [outcome]
+│   └── [Fallback]: [How unmatched handled]
+├── INTEGRATIONS:
+│   ├── [System 1]: [Why integrated]
+│   └── [System 2]: [Why integrated]
+└── OUTPUTS:
+    ├── [Output 1]: [Purpose]
+    └── [Output 2]: [Purpose]
+\`\`\`
+
+## Step 4: Logic Analysis
+
+### Decision Points
+For each categorizer/router:
+- **Decision criteria**: How does it decide?
+- **Category definitions**: What defines each category?
+- **Edge cases**: What about ambiguous inputs?
+
+### Data Transformations
+For each processing node:
+- **Input shape**: What structure enters?
+- **Transformation logic**: What changes?
+- **Output shape**: What structure exits?
+
+### Integration Logic
+For each external call:
+- **When triggered**: Under what conditions?
+- **What data sent**: What information flows out?
+- **What data received**: What comes back?
+- **How used**: Where does the response go?
+
+## Step 5: Optimization Insights
+
+Based on intent analysis, identify:
+
+### Alignment Issues
+- Nodes that don't serve clear intent
+- Redundant processing
+- Missing error paths
+
+### Enhancement Opportunities
+- Intents that could be added
+- Data that could be captured
+- Outputs that could be enriched
+
+### Structural Improvements
+- Parallel processing opportunities
+- Caching opportunities
+- Simplification possibilities
+
+## Output Format
+
+Provide:
+1. **Executive Summary**: 2-3 sentence overview
+2. **Intent Map**: Visual hierarchy of goals/intents/paths
+3. **Logic Explanation**: Natural language description of how it works
+4. **Decision Tree**: How routing decisions are made
+5. **Optimization Recommendations**: Improvements aligned with intent
+6. **Questions for Stakeholders**: Clarifications needed for better optimization`,
+                },
+            },
+        ],
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt Registry
+// ─────────────────────────────────────────────────────────────────────────────
+export class PromptRegistry {
+    /**
+     * List all available prompts
+     */
+    list() {
+        return Object.values(PROMPTS).map((p) => p.definition);
+    }
+    /**
+     * Get a rendered prompt by name with arguments
+     */
+    get(name, args = {}) {
+        const prompt = PROMPTS[name];
+        if (!prompt) {
+            return {
+                code: "NOT_FOUND",
+                message: `Prompt not found: ${name}. Use prompts/list to see available prompts.`,
+            };
+        }
+        // Validate required arguments
+        for (const arg of prompt.definition.arguments) {
+            if (arg.required && !args[arg.name]) {
+                return {
+                    code: "MISSING_REQUIRED_ARG",
+                    message: `Missing required argument: ${arg.name}`,
+                };
+            }
+        }
+        // Render the prompt
+        const messages = prompt.render(args);
+        return {
+            description: prompt.definition.description,
+            messages,
+        };
+    }
+}
+// Helper to check if result is an error
+export function isPromptError(result) {
+    return "code" in result;
+}