@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23

package/dist/mcp/resources-dynamic.js

@@ -0,0 +1,2395 @@
+/**
+ * Dynamic MCP Resources
+ *
+ * Contains the DYNAMIC_RESOURCES array (~50 dynamic resource generators)
+ * with their inline markdown templates, plus the dynamic fetching helpers
+ * (API clients, caches, DTO converters) that the generators use.
+ *
+ * Extracted from resources.ts for maintainability.
+ */
+import * as path from "path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+// ESM-compatible __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+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 "./knowledge.js";
+import { INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES } from "./domain/validation-rules.js";
+import { STRUCTURAL_INVARIANTS } from "./domain/structural-rules.js";
+import { mineConstraints, formatConstraintReport } from "./domain/proto-constraints.js";
+import { EmaClientAdapter } from "../sdk/client-adapter.js";
+import { APISchemaRegistry } from "./domain/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";
+import { generateValidationRulesForLLM, generateBestPracticesChecklist } from "./resources-validation.js";
+const DYNAMIC_RESOURCES = [
+    // Agent Catalog - Dynamic list of all workflow agents
+    {
+        uri: "ema://catalog/agents",
+        name: "catalog/agents",
+        description: "Complete agent catalog: all available workflow agents with inputs, outputs, critical rules, and usage guidance",
+        mimeType: "application/json",
+        generate: async (ctx) => JSON.stringify(await getDynamicAgentCatalog({ env: ctx.env }), null, 2),
+    },
+    {
+        uri: "ema://catalog/agents-summary",
+        name: "catalog/agents-summary",
+        description: "Agent catalog summary: agent names, categories, and brief descriptions for quick reference",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            const agents = await getDynamicAgentCatalog({ env: ctx.env });
+            const byCategory = new Map();
+            for (const agent of agents) {
+                const cat = agent.category || "other";
+                if (!byCategory.has(cat))
+                    byCategory.set(cat, []);
+                byCategory.get(cat).push(agent);
+            }
+            let md = "# Ema Agent Catalog\n\n";
+            md += `> ${agents.length} agents available for workflow composition\n\n`;
+            for (const [category, agents] of byCategory) {
+                md += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+                md += "| Agent | Description | Key Inputs | Key Outputs |\n";
+                md += "|-------|-------------|------------|-------------|\n";
+                for (const agent of agents) {
+                    const inputs = agent.inputs?.slice(0, 2).map((i) => i.name).join(", ") || "-";
+                    const outputs = agent.outputs?.slice(0, 2).map((o) => o.name).join(", ") || "-";
+                    md += `| \`${agent.actionName}\` | ${agent.description?.slice(0, 60) || "-"}... | ${inputs} | ${outputs} |\n`;
+                }
+                md += "\n";
+            }
+            return md;
+        },
+    },
+    // Workflow Patterns - Common workflow templates
+    {
+        uri: "ema://catalog/patterns",
+        name: "catalog/patterns",
+        description: "Workflow patterns: common workflow structures (kb-search, intent-routing, tool-calling) with examples",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(WORKFLOW_PATTERNS, null, 2),
+    },
+    // Widget Catalog - UI configuration widgets
+    {
+        uri: "ema://catalog/widgets",
+        name: "catalog/widgets",
+        description: "Widget catalog: proto_config widget types for voice, chat, and dashboard personas",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(WIDGET_CATALOG, null, 2),
+    },
+    // Validation Rules - Input source and anti-pattern rules
+    {
+        uri: "ema://rules/input-sources",
+        name: "rules/input-sources",
+        description: "Input source validation rules: which agent inputs accept which data types (user_query vs chat_conversation)",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(INPUT_SOURCE_RULES, null, 2),
+    },
+    {
+        uri: "ema://rules/anti-patterns",
+        name: "rules/anti-patterns",
+        description: "Anti-patterns to avoid: common workflow mistakes and how to prevent them",
+        mimeType: "application/json",
+        generate: async () => JSON.stringify(ANTI_PATTERNS, null, 2),
+    },
+    {
+        uri: "ema://rules/optimizations",
+        name: "rules/optimizations",
+        description: "Optimization rules: workflow improvements for better performance and reliability",
+        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),
+    },
+    {
+        uri: "ema://validation/rules",
+        name: "validation/rules",
+        description: "Static validation rules: path enumeration, required outputs, multiple writers, response/abstain, category hierarchy. Use these rules DURING workflow generation to avoid errors.",
+        mimeType: "text/markdown",
+        generate: async () => generateValidationRulesForLLM(),
+    },
+    // Best Practices - Auto-generated from SDK rules (SINGLE SOURCE OF TRUTH)
+    {
+        uri: "ema://docs/best-practices",
+        name: "docs/best-practices",
+        description: "Auto-generated best practices checklist from SDK validation rules. Use BEFORE deploying workflows.",
+        mimeType: "text/markdown",
+        generate: async () => generateBestPracticesChecklist(),
+    },
+    // Field Constraints - Mined from proto definitions
+    {
+        uri: "ema://docs/field-constraints",
+        name: "docs/field-constraints",
+        description: "Proto field constraints: immutable fields, read-only fields, creation-only fields, conditional fields. Mined from proto definitions.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            const report = mineConstraints();
+            return formatConstraintReport(report);
+        },
+    },
+    // 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: results Mapping\n\n";
+            md += "**Every workflow must have a `results` map connecting action outputs to the persona's output.**\n\n";
+            md += "### Chat / Voice Personas\n\n";
+            md += "Use `WORKFLOW_OUTPUT` as the key — this is the response shown to the user:\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\n";
+            md += "Multiple response nodes (e.g., one per categorizer branch) can all map to `WORKFLOW_OUTPUT` — only the one that executes via `runIf` will produce output.\n\n";
+            md += "### Dashboard Personas\n\n";
+            md += "Use `<actionName>.<outputName>` dot-notation keys — each key becomes a column in the dashboard:\n\n";
+            md += "```json\n";
+            md += '{\n  "results": {\n    "entity_extraction_node.extraction_columns": {\n      "actionName": "entity_extraction_node",\n      "outputName": "extraction_columns"\n    },\n    "rule_validation_node.ruleset_output": {\n      "actionName": "rule_validation_node",\n      "outputName": "ruleset_output"\n    }\n  }\n}\n';
+            md += "```\n\n";
+            md += "Common dashboard result outputs: `extraction_columns`, `ruleset_output`, `llm_output`.\n";
+            return md;
+        },
+    },
+    // JSON Output Patterns - custom_agent + json_mapper best practices
+    {
+        uri: "ema://rules/json-output-patterns",
+        name: "rules/json-output-patterns",
+        description: "How to properly wire custom_agent JSON output to json_mapper and downstream nodes like send_email_agent",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# custom_agent + json_mapper Pattern
+
+## Problem
+
+When using \`custom_agent\` to generate JSON that will be parsed by \`json_mapper\`, the output can be misformatted if not properly configured.
+
+Without explicit \`output_fields\`, custom_agent returns the entire JSON as a string blob in \`response_with_sources\`, causing json_mapper to fail or produce incorrect results.
+
+## Solution A: Define output_fields (RECOMMENDED)
+
+Use \`output_fields\` with extraction columns matching your JSON keys:
+
+\`\`\`json
+{
+  "name": "email_gen",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "custom_agent" }, "version": "v1" },
+  "inputs": {
+    "task_instructions": { "inline": { "wellKnown": { "textWithSources": { 
+      "text": "Generate notification email with To, Subject, and Body fields.",
+      "sources": [] 
+    }}}},
+    "output_fields": {
+      "inline": { "array": { "values": [
+        { "wellKnown": { "extractionColumn": { "id": "To", "name": "To", "dataType": 1 }}},
+        { "wellKnown": { "extractionColumn": { "id": "Subject", "name": "Subject", "dataType": 1 }}},
+        { "wellKnown": { "extractionColumn": { "id": "Body", "name": "Body", "dataType": 1 }}}
+      ]}}
+    }
+  }
+}
+\`\`\`
+
+## Solution B: Strict Prompting + json_mapper
+
+If not using \`output_fields\`, instruct the LLM to output RAW JSON only (no markdown):
+
+\`\`\`
+task_instructions: "Output ONLY the JSON object, no markdown, no explanation. Format: {\\"To\\": \\"...\\", \\"Subject\\": \\"...\\", \\"Body\\": \\"...\\"}"
+\`\`\`
+
+Then wire to \`json_mapper\` with matching \`pathIndices\`:
+
+\`\`\`json
+{
+  "name": "json_map",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "json_mapper" }, "version": "v1" },
+  "inputs": {
+    "input_json": { "actionOutput": { "actionName": "email_gen", "output": "response_with_sources" }},
+    "json_mapper_config": {
+      "inline": { "wellKnown": { "jsonMapperConfig": {
+        "rules": [
+          { "fieldName": "to", "pathIndices": [{"stringIndex": "To"}], "type": 3, "defaultValue": {"stringValue": ""} },
+          { "fieldName": "subject", "pathIndices": [{"stringIndex": "Subject"}], "type": 3, "defaultValue": {"stringValue": ""} },
+          { "fieldName": "body", "pathIndices": [{"stringIndex": "Body"}], "type": 3, "defaultValue": {"stringValue": ""} }
+        ],
+        "sampleJson": "{\\"To\\": \\"email@example.com\\", \\"Subject\\": \\"Test\\", \\"Body\\": \\"<p>Hi</p>\\"}"
+      }}}
+    }
+  }
+}
+\`\`\`
+
+## Wiring json_mapper to fixed_response
+
+json_mapper outputs extracted fields to \`output_json\`. Use \`fixed_response\` with template variables to convert to \`TEXT_WITH_SOURCES\`:
+
+\`\`\`json
+{
+  "name": "fmt_to",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "fixed_response" }, "version": "v1" },
+  "inputs": {
+    "template": { "inline": { "wellKnown": { "textWithSources": { "text": "{{to}}", "sources": [] }}}},
+    "custom_data": { "actionOutput": { "actionName": "json_map", "output": "output_json" }}
+  }
+}
+\`\`\`
+
+## Complete Email Chain Pattern
+
+\`\`\`
+custom_agent (generates JSON) 
+    → json_mapper (extracts To, Subject, Body)
+    → fixed_response ×3 ({{to}}, {{subject}}, {{body}})
+    → send_email_agent
+\`\`\`
+
+## Critical Rules
+
+| Rule | Why |
+|------|-----|
+| Use \`output_fields\` OR strict "ONLY JSON" prompt | Prevents markdown wrapping |
+| json_mapper outputs to \`output_json\` | Not individual field outputs |
+| Use \`fixed_response\` with \`{{fieldName}}\` template | Converts to TEXT_WITH_SOURCES |
+| \`send_email_agent\` needs TEXT_WITH_SOURCES | Direct json_mapper output = type mismatch |
+| \`pathIndices\` are case-sensitive | Must match JSON keys exactly |
+| Include \`defaultValue\` in rules | Prevents null errors |
+
+## Debugging
+
+If json_mapper fails to extract:
+1. Check if LLM is wrapping JSON in markdown (\\\`\\\`\\\`json ... \\\`\\\`\\\`)
+2. Check pathIndices match actual JSON keys (case-sensitive)
+3. Check custom_agent prompt instructs "ONLY JSON, no markdown"
+4. Add defaultValue to prevent null propagation
+`;
+        },
+    },
+    // Extraction column format - canonical API shape for entity_extraction / extraction_columns
+    {
+        uri: "ema://rules/extraction-column-format",
+        name: "rules/extraction-column-format",
+        description: "Canonical API format for extraction_columns (entity_extraction_with_documents, etc.). Use this shape when generating or fixing workflow_def; do not guess from catalog or local files.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# extraction_columns Format (API Shape)
+
+## Rule
+
+When generating or fixing workflow_def that includes \`entity_extraction_with_documents\` (or similar) nodes, the \`extraction_columns\` input **must** use this exact structure. The API rejects other shapes (e.g. \`extractionColumns.columns[{name, type}]\`).
+
+## Required Shape
+
+\`\`\`json
+"extraction_columns": {
+  "inline": {
+    "array": {
+      "values": [
+        { "wellKnown": { "extractionColumn": { "id": "<column_id>", "name": "<display name>", "description": "<optional>", "dataType": 1 } } },
+        { "wellKnown": { "extractionColumn": { "id": "...", "name": "...", "description": "...", "dataType": 1 } } }
+      ]
+    }
+  }
+}
+\`\`\`
+
+- \`inline.array.values\`: array of column definitions.
+- Each column: \`wellKnown.extractionColumn\` with \`id\`, \`name\`, optional \`description\`, \`dataType\` (1 = string typical).
+- **Do not** use \`extractionColumns.columns\` or \`{ name, type, description }\` only — the API expects the \`array.values\` + \`wellKnown.extractionColumn\` shape.
+
+## id vs name
+
+- **id**: Unique identifier for the column (stable key; used in results/downstream). Can be \`col1\`, \`col5\`, \`service_date\`, or any unique string.
+- **name**: Display/semantic name (LLM uses this to extract values). Can match id or differ (e.g. \`id: "col5"\`, \`name: "service_date"\` is valid).
+- **id and name do not have to match.** Using generic ids (\`col1\`, \`col2\`) with semantic names (\`event_id\`, \`service_date\`) is correct.
+
+## Emoji in Column Names (Dashboard Polish)
+
+Column \`name\` values support **emoji prefixes**, which render as dashboard column headers. This makes dashboards significantly more scannable and visually polished.
+
+\`\`\`json
+{ "wellKnown": { "extractionColumn": { "id": "customer",    "name": "🧑 Customer",     "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "segment",     "name": "🟠 Segment",      "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "balance",     "name": "💰 Balance",      "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "days_past",   "name": "📅 Days Past Due", "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "dispute",     "name": "⚖️ Dispute",      "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "ptp",         "name": "🤝 PTP",          "dataType": 1 } } },
+{ "wellKnown": { "extractionColumn": { "id": "invoices",    "name": "📄 Invoices",     "dataType": 1 } } }
+\`\`\`
+
+**Emoji in cell values**: The extraction \`description\` (instructions) can tell the LLM to prefix extracted values with emoji for visual status indicators. These render in dashboard cells:
+
+- \`"description": "Total outstanding balance. Prefix with ❗ if over $500,000"\`
+- \`"description": "Yes or No. Prefix Yes with 🚫 for active disputes"\`
+- \`"description": "Promise-to-pay date. Prefix with 🤝 if present"\`
+- \`"description": "Pass or Fail. Prefix Pass with ✅ and Fail with ❌"\`
+
+This creates rich, at-a-glance dashboards where status is conveyed by color and symbol without reading every cell.
+
+## Duplicate ids
+
+- **Within the same extraction_columns array**, every column must have a **unique \`id\`**. Duplicate \`id\` values in one array are invalid.
+- Different actions can reuse the same id strings (e.g. \`event_extraction\` has \`col1\`..\`col6\`, \`validation_results\` has \`col1\`..\`col10\`) — each action has its own array.
+
+## dataType Reference (PrimitiveType enum)
+
+| Value | Type | Description |
+|-------|------|-------------|
+| 0 | UNKNOWN | Unspecified (avoid) |
+| 1 | STRING | Text values (default) |
+| 2 | NUMBER | Numeric values |
+| 3 | BOOLEAN | True/false values |
+| 4 | ARRAY | Array of repeated values (use with \`arrayElementType\`) |
+| 5 | OBJECT | Grouped/nested structure (contains sub-columns via \`value.objectValue\`) |
+| 6 | DATE | Date values (use with \`formattingOptions.dateFormat\`) |
+| 7 | DOCUMENT_VERSION_ID | Reference to a document version |
+
+**Note on enums:** To create an enumerated column, use \`dataType: 1\` (STRING) with \`isEnum: true\` and populate \`possibleValues\`.
+
+## Object / Grouped Columns (dataType: 5)
+
+Use \`dataType: 5\` to create a **Group** column with sub-columns (nested structure). In the UI, this appears as a parent column with expandable sub-columns.
+
+The sub-columns are defined as a nested array in the column's \`value.objectValue.values\`. Each sub-column is a **bare \`ExtractionColumn\`** (no \`wellKnown\` wrapper — that wrapper only appears at the top-level \`extraction_columns.inline.array.values[]\`).
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "address",
+      "name": "Address",
+      "description": "Structured address fields",
+      "dataType": 5,
+      "value": {
+        "objectValue": {
+          "values": [
+            {
+              "id": "street",
+              "name": "Street Name",
+              "description": "Street name",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "city",
+              "name": "City",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "postal_code",
+              "name": "Postal Code",
+              "dataType": 1,
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            }
+          ]
+        }
+      },
+      "arrayElementType": {
+        "id": "address",
+        "name": "Address",
+        "dataType": 5,
+        "detailedDescription": "",
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      },
+      "detailedDescription": "",
+      "isEnum": false,
+      "possibleValues": [],
+      "dependencies": [],
+      "fileSources": [],
+      "auxiliarySources": []
+    }
+  }
+}
+\`\`\`
+
+**Key rules for grouped columns:**
+- Parent column uses \`dataType: 5\` (OBJECT)
+- Sub-columns live in \`value.objectValue.values\` as **bare ExtractionColumn objects** (no \`wellKnown\` wrapper)
+- Each sub-column needs its own unique \`id\` within the group
+- Sub-columns can themselves be groups (nested groups) up to the nesting depth limit
+- The UI shows the parent as a collapsible group header with sub-columns underneath
+- **Auto-populated \`arrayElementType\`:** The API may auto-populate a sparse \`arrayElementType\` on OBJECT columns (with \`id\`, \`name\`, \`dataType: 5\` but NO sub-columns). This is normal — include it when copying from a working persona but it is not required when creating new columns.
+
+**Default field pattern:** Live API data always includes these fields on every column, even when empty. Include them for consistency:
+\`\`\`
+"detailedDescription": "", "isEnum": false, "possibleValues": [],
+"dependencies": [], "fileSources": [], "auxiliarySources": []
+\`\`\`
+
+**IMPORTANT — wellKnown wrapping rules:**
+- \`extraction_columns.inline.array.values[]\` = \`Value\` proto type → each entry needs \`{ "wellKnown": { "extractionColumn": {...} } }\`
+- \`objectValue.values[]\` inside a column = \`ExtractionColumn[]\` proto type → bare \`{ "id": "...", "name": "...", "dataType": ... }\`
+- \`arrayElementType\` = \`ExtractionColumn\` proto type → bare \`{ "dataType": ..., ... }\`
+
+## Multi-Value / Array Columns (dataType: 4)
+
+Use \`dataType: 4\` (ARRAY) with \`arrayElementType\` to extract **repeated values** from a document (e.g., multiple phone numbers, a list of names).
+
+The \`arrayElementType\` field is a bare \`ExtractionColumn\` (no \`wellKnown\` wrapper). It typically includes \`id\` and \`name\` (often repeating the parent's values) plus the element \`dataType\`.
+
+### Simple Array (repeated scalar values)
+
+Extract multiple values of the same primitive type (e.g., list of invoice IDs):
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "invoice_ids",
+      "name": "Invoice(s)",
+      "description": "Invoice IDs as a list",
+      "dataType": 4,
+      "arrayElementType": {
+        "id": "invoice_ids",
+        "name": "Invoice(s)",
+        "description": "Single invoice ID like INV-2024-1423",
+        "dataType": 1,
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      }
+    }
+  }
+}
+\`\`\`
+
+### Array of Objects (repeated grouped values)
+
+Extract multiple structured items (e.g., line items from an invoice). Combine \`dataType: 4\` with an \`arrayElementType\` of \`dataType: 5\` (OBJECT). Sub-columns inside \`objectValue.values\` are **bare ExtractionColumn objects** (no \`wellKnown\` wrapper):
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "line_items",
+      "name": "Items",
+      "description": "All line items from the invoice",
+      "dataType": 4,
+      "value": {
+        "objectValue": {
+          "values": [
+            {
+              "id": "item_name",
+              "name": "Item Name",
+              "dataType": 1,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "quantity",
+              "name": "Quantity",
+              "dataType": 2,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            },
+            {
+              "id": "unit_price",
+              "name": "Unit Price",
+              "dataType": 2,
+              "description": "",
+              "detailedDescription": "",
+              "isEnum": false,
+              "possibleValues": [],
+              "dependencies": [],
+              "fileSources": [],
+              "auxiliarySources": []
+            }
+          ]
+        }
+      },
+      "arrayElementType": {
+        "id": "line_items",
+        "name": "Items",
+        "dataType": 5,
+        "value": {
+          "objectValue": {
+            "values": [
+              {
+                "id": "item_name",
+                "name": "Item Name",
+                "dataType": 1,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              },
+              {
+                "id": "quantity",
+                "name": "Quantity",
+                "dataType": 2,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              },
+              {
+                "id": "unit_price",
+                "name": "Unit Price",
+                "dataType": 2,
+                "description": "",
+                "detailedDescription": "",
+                "isEnum": false,
+                "possibleValues": [],
+                "dependencies": [],
+                "fileSources": [],
+                "auxiliarySources": []
+              }
+            ]
+          }
+        },
+        "description": "",
+        "detailedDescription": "",
+        "isEnum": false,
+        "possibleValues": [],
+        "dependencies": [],
+        "fileSources": [],
+        "auxiliarySources": []
+      },
+      "detailedDescription": "",
+      "isEnum": false,
+      "possibleValues": [],
+      "dependencies": [],
+      "fileSources": [],
+      "auxiliarySources": []
+    }
+  }
+}
+\`\`\`
+
+**Key rules for array columns:**
+- Parent column uses \`dataType: 4\` (ARRAY)
+- \`arrayElementType\` is a bare \`ExtractionColumn\` (no \`wellKnown\` wrapper) — repeats the parent's \`id\` and \`name\`, plus the element \`dataType\`
+- For simple arrays: \`arrayElementType.dataType\` = scalar type (1=STRING, 2=NUMBER, etc.)
+- For arrays of objects: \`arrayElementType.dataType: 5\` with \`value.objectValue.values\` containing bare sub-columns
+- **Dual storage pattern:** For array-of-objects, the sub-columns appear in BOTH \`value.objectValue.values\` (on the parent) AND \`arrayElementType.value.objectValue.values\`. Both sets must match. The \`arrayElementType\` is the canonical schema; the parent \`value.objectValue\` may be auto-populated by the API.
+- Sub-columns inside \`objectValue.values\` are bare ExtractionColumn objects (no \`wellKnown\` wrapper)
+- The UI labels this as "Multi Value" — in the API, it maps to \`dataType: 4\` + \`arrayElementType\`
+- **There is no \`isMultiValue\` API field** — that is a UI-only label. Always use \`dataType: 4\` + \`arrayElementType\` in workflow_def.
+
+## Creation-Time Constraints
+
+**IMPORTANT:** The following extraction column properties are set at creation time and **cannot be changed** after the column exists:
+
+| Property | Constraint |
+|----------|-----------|
+| \`dataType\` | Cannot change after creation (e.g., STRING to ARRAY) |
+| \`arrayElementType\` | Cannot change after creation; defines the array element schema |
+| \`value.objectValue\` structure | Sub-column schema is fixed at creation |
+
+To change these properties, you must **delete the column and recreate it** with the new settings.
+
+Other properties (\`name\`, \`description\`, \`possibleValues\`, \`formattingOptions\`) can be updated after creation.
+
+## Enum Columns
+
+To create a column with a fixed set of allowed values, use \`dataType: 1\` (STRING) with \`isEnum: true\` and \`possibleValues\`:
+
+\`\`\`json
+{
+  "wellKnown": {
+    "extractionColumn": {
+      "id": "priority",
+      "name": "Priority",
+      "description": "Task priority level",
+      "dataType": 1,
+      "isEnum": true,
+      "possibleValues": [
+        { "value": { "stringValue": "High", "case": "stringValue" } },
+        { "value": { "stringValue": "Medium", "case": "stringValue" } },
+        { "value": { "stringValue": "Low", "case": "stringValue" } }
+      ]
+    }
+  }
+}
+\`\`\`
+
+## Document Input Wiring (Dashboard Personas)
+
+Dashboard extraction workflows receive documents through one of two patterns:
+
+### Pattern 1: workflowInput (preferred for newer workflows)
+
+\`\`\`json
+"workflowInputs": {
+  "document-mmf2": {
+    "type": { "arrayType": { "wellKnownType": 5, "isList": false }, "isList": false },
+    "displayName": "Document"
+  }
+}
+\`\`\`
+
+Then in the extraction node:
+\`\`\`json
+"documents": { "workflowInput": { "inputName": "document-mmf2" } }
+\`\`\`
+
+### Pattern 2: trigger output (older workflows)
+
+\`\`\`json
+"documents": { "actionOutput": { "actionName": "trigger", "output": "user_query" } }
+\`\`\`
+
+Note: The output name \`user_query\` is used for documents in older \`document_trigger\` workflows — despite the misleading name, it carries the uploaded document content.
+
+## Extraction Node Options
+
+### disableHumanInteraction
+
+Set to \`true\` to skip the human-in-the-loop review step for extraction results. Default is \`false\` (HITL enabled):
+
+\`\`\`json
+{
+  "name": "entity_extraction_node",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "entity_extraction_with_documents" }, "version": "v0" },
+  "inputs": { ... },
+  "disableHumanInteraction": true
+}
+\`\`\`
+
+## How to Use
+
+1. Call \`workflow(mode="get", persona_id="<same or similar persona>")\` and use the returned \`workflow_def\` as your format reference.
+2. For extraction_columns specifically, copy the structure from a working action node in that workflow_def, or use this resource.
+3. Generate or edit workflow_def as text/JSON; do not reverse-engineer from local JSON files.
+
+See also: \`ema://rules/json-output-patterns\` for custom_agent/output_fields (same array.values + wellKnown.extractionColumn pattern).
+`;
+        },
+    },
+    // Nested Data Format - ARRAY and OBJECT column handling
+    {
+        uri: "ema://rules/nested-data-format",
+        name: "rules/nested-data-format",
+        description: "Format guide for nested data structures in dashboard columns (ARRAY and OBJECT types). Use for uploads with sub-tables.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Nested Data Format Guide
+
+## Overview
+
+Dashboard columns can contain nested data structures using \`COLUMN_TYPE_ARRAY\` (8) and \`COLUMN_TYPE_OBJECT\` (9).
+These are used for entity extraction results, line items, and other structured data.
+
+## Column Types
+
+| Type | Enum | Structure | Use Case |
+|------|------|-----------|----------|
+| \`COLUMN_TYPE_ARRAY\` | 8 | \`{ arrayValues: ColumnValue[] }\` | Lists of same-type items (line items, extracted entities) |
+| \`COLUMN_TYPE_OBJECT\` | 9 | \`{ objectValues: { [key]: ColumnValue } }\` | Structured record with named fields |
+
+## DashboardInput Format
+
+When uploading rows with nested data, use this format:
+
+\`\`\`typescript
+// ARRAY column
+{
+  name: "line_items",
+  array_value: [
+    { name: "element", string_value: "Item 1" },
+    { name: "element", number_value: 100 },
+    { name: "element", object_value: { 
+      "product": { name: "product", string_value: "Widget" },
+      "qty": { name: "qty", number_value: 5 }
+    }}
+  ]
+}
+
+// OBJECT column
+{
+  name: "customer_info",
+  object_value: {
+    "name": { name: "name", string_value: "Acme Corp" },
+    "email": { name: "email", string_value: "contact@acme.com" },
+    "orders": { name: "orders", array_value: [...] }  // Nested array
+  }
+}
+\`\`\`
+
+## Schema Information
+
+Dashboard schema includes nested structure details:
+
+\`\`\`typescript
+// For ARRAY columns:
+{
+  columnType: "COLUMN_TYPE_ARRAY",
+  arrayElementType: {
+    columnType: "COLUMN_TYPE_OBJECT",  // or STRING, NUMBER, etc.
+    objectSubColumns: [...]  // If element is OBJECT
+  }
+}
+
+// For OBJECT columns:
+{
+  columnType: "COLUMN_TYPE_OBJECT",
+  objectSubColumns: [
+    { name: "field1", columnType: "COLUMN_TYPE_STRING" },
+    { name: "field2", columnType: "COLUMN_TYPE_NUMBER" },
+  ]
+}
+\`\`\`
+
+## Validation Rules
+
+| Rule | Limit | Error |
+|------|-------|-------|
+| Max array elements | 1000 | \`Array exceeds maximum of 1000 elements\` |
+| Max nesting depth | 3 levels | \`Nesting depth exceeds maximum of 3\` |
+| Type mismatch | - | \`Expected array for ARRAY column, got <type>\` |
+
+## Common Mistakes
+
+### ❌ Scalar value for ARRAY column
+\`\`\`typescript
+// WRONG - passing string where array expected
+{ name: "line_items", string_value: "item1, item2" }
+
+// CORRECT
+{ name: "line_items", array_value: [
+  { name: "element", string_value: "item1" },
+  { name: "element", string_value: "item2" }
+]}
+\`\`\`
+
+### ❌ Array value for STRING column  
+\`\`\`typescript
+// WRONG - passing array where string expected
+{ name: "customer_name", array_value: [...] }
+
+// CORRECT
+{ name: "customer_name", string_value: "Acme Corp" }
+\`\`\`
+
+### ❌ Missing element name
+\`\`\`typescript
+// WRONG - missing name in array element
+{ name: "items", array_value: [{ string_value: "item1" }] }
+
+// CORRECT - always include name
+{ name: "items", array_value: [{ name: "element", string_value: "item1" }] }
+\`\`\`
+
+## Related Resources
+
+- \`ema://rules/extraction-column-format\` - entity_extraction output format
+- \`ema://rules/json-output-patterns\` - custom_agent JSON patterns
+`;
+        },
+    },
+    // Chat Response Wiring - how to avoid duplicate/repetitive responses
+    {
+        uri: "ema://rules/chat-response-wiring",
+        name: "rules/chat-response-wiring",
+        description: "Rules for wiring chat workflows to avoid duplicate or repetitive responses. Chat conversation must flow to chat-aware response nodes.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Chat Response Wiring Rules
+
+## The Problem
+
+Chat workflows that process \`chat_conversation\` through search, extraction, or tool calls **must** wire the results to a **chat-aware response node** — not a generic \`call_llm\`. Without conversation history in the response node, the LLM:
+
+1. **Repeats questions** already answered in prior turns
+2. **Loses context** from multi-turn conversations
+3. **Generates stale greetings** instead of continuing naturally
+
+## Correct Patterns
+
+### Pattern 1: Search + Respond (most common)
+\`\`\`
+chat_trigger.chat_conversation → conversation_to_search_query.conversation
+conversation_to_search_query.summarized_conversation → search.query
+search.search_results → respond_for_external_actions.external_action_result
+chat_trigger.user_query → respond_for_external_actions.query
+chat_trigger.chat_conversation → respond_for_external_actions.conversation
+respond_for_external_actions.response → WORKFLOW_OUTPUT
+\`\`\`
+
+> **Note**: \`respond_with_sources/v0\` is DEPRECATED. Use \`respond_for_external_actions\` for all new workflows (search results, tool results, or any context-aware response).
+
+### Pattern 2: Tool/Action + Respond
+\`\`\`
+chat_trigger.chat_conversation → external_action_caller.conversation
+external_action_caller.tool_execution_result → respond_for_external_actions.external_action_result
+chat_trigger.user_query → respond_for_external_actions.query
+chat_trigger.chat_conversation → respond_for_external_actions.conversation
+respond_for_external_actions.response → WORKFLOW_OUTPUT
+\`\`\`
+
+### Pattern 3: call_llm with Conversation Context (advanced)
+If you must use \`call_llm\` as the terminal responder, you **must** wire \`chat_conversation\` into its \`named_inputs\`:
+\`\`\`
+chat_trigger.chat_conversation → call_llm.named_inputs (key: "conversation_history")
+\`\`\`
+This ensures the LLM sees prior turns.
+
+## Anti-Patterns
+
+### ❌ Stateless call_llm as Responder
+\`\`\`
+chat_trigger → search → call_llm (no conversation) → WORKFLOW_OUTPUT
+\`\`\`
+**Problem**: call_llm only sees search results, not prior conversation. Repeats questions.
+
+### ❌ Entity Extraction → call_llm (no history)
+\`\`\`
+chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT
+\`\`\`
+**Problem**: LLM extracts entities but response node doesn't know what was already discussed.
+
+## Key Insight
+
+\`respond_for_external_actions\` is **conversation-aware by design** — it incorporates conversation context via its \`conversation\` input. Generic \`call_llm\` does not — you must manually wire \`chat_conversation\` via \`named_inputs\`.
+
+> **Deprecated**: \`respond_with_sources/v0\` — use \`respond_for_external_actions\` for all new workflows.
+
+## When to Use Each Response Node
+
+| Scenario | Response Node | Why |
+|----------|---------------|-----|
+| KB/document Q&A | \`respond_for_external_actions\` | Handles search results, conversation-aware |
+| Tool/API results | \`respond_for_external_actions\` | Explains tool results in conversation context |
+| Complex multi-step reasoning | \`call_llm/v2\` + named_inputs with chat_conversation | Full control but requires manual history wiring |
+| Static/template response | \`fixed_response/v1\` | No LLM needed, just template + variables |
+`;
+        },
+    },
+    // Email Input Wiring - how to wire extracted data to email fields
+    {
+        uri: "ema://rules/email-input-wiring",
+        name: "rules/email-input-wiring",
+        description: "Rules for wiring data to send_email_agent inputs. Entity extraction outputs cannot go directly to email fields — use json_mapper/fixed_response intermediaries.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Email Input Wiring Rules
+
+## The Problem
+
+\`send_email_agent\` inputs (\`email_to\`, \`email_subject\`, \`email_body\`) require **TEXT_WITH_SOURCES** type. But entity_extraction outputs are **ANY** type (structured JSON). Direct wiring causes:
+
+1. **Type mismatch errors** at deploy time (HTTP 500)
+2. **Corrupted email addresses** — entire JSON object sent as recipient
+3. **Missing fields** — structured data not properly decomposed into individual fields
+
+## Rule: Always Use Intermediary Nodes
+
+\`\`\`
+❌ WRONG: entity_extraction → send_email_agent.email_to
+❌ WRONG: entity_extraction → send_email_agent.email_subject
+❌ WRONG: call_llm.response → send_email_agent.email_to (sends full text as address)
+
+✅ RIGHT: entity_extraction → json_mapper → fixed_response({{to}}) → send_email_agent.email_to
+✅ RIGHT: custom_agent(output_fields=[To,Subject,Body]) → send_email_agent
+✅ RIGHT: entity_extraction → fixed_response({{email_address}}) → send_email_agent.email_to
+\`\`\`
+
+## Pattern A: json_mapper + fixed_response (Recommended)
+
+Best for decomposing structured extraction results into individual email fields.
+
+### Step 1: Extract fields with json_mapper
+\`\`\`json
+{
+  "name": "extract_fields",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "json_mapper" }, "version": "v1" },
+  "inputs": {
+    "json_input": { "actionOutput": { "actionName": "entity_extraction", "output": "extraction_result" }},
+    "json_mapper_config": {
+      "inline": { "wellKnown": { "jsonMapperConfig": {
+        "rules": [
+          { "fieldName": "to", "pathIndices": [{"stringIndex": "email_address"}], "type": 3 },
+          { "fieldName": "subject", "pathIndices": [{"stringIndex": "subject_line"}], "type": 3 },
+          { "fieldName": "body", "pathIndices": [{"stringIndex": "email_body"}], "type": 3 }
+        ]
+      }}}
+    }
+  }
+}
+\`\`\`
+
+### Step 2: Format each field with fixed_response
+\`\`\`json
+{
+  "name": "fmt_to",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "fixed_response" }, "version": "v1" },
+  "inputs": {
+    "template": { "inline": { "wellKnown": { "textWithSources": { "text": "{{to}}", "sources": [] }}}},
+    "custom_data": { "actionOutput": { "actionName": "extract_fields", "output": "output_json" }}
+  }
+}
+\`\`\`
+
+Repeat for \`fmt_subject\` (using \`{{subject}}\`) and \`fmt_body\` (using \`{{body}}\`).
+
+### Step 3: Wire to send_email_agent
+\`\`\`json
+{
+  "name": "send_email",
+  "inputs": {
+    "email_to": { "actionOutput": { "actionName": "fmt_to", "output": "response" }},
+    "email_subject": { "actionOutput": { "actionName": "fmt_subject", "output": "response" }},
+    "email_body": { "actionOutput": { "actionName": "fmt_body", "output": "response" }}
+  }
+}
+\`\`\`
+
+## Pattern B: custom_agent with output_fields (Simpler)
+
+When the LLM generates email content, use \`custom_agent\` with \`output_fields\` to produce individual TEXT_WITH_SOURCES outputs directly:
+
+\`\`\`json
+{
+  "name": "generate_email",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "custom_agent" }, "version": "v1" },
+  "inputs": {
+    "task_instructions": { "inline": { "wellKnown": { "textWithSources": { "text": "Generate an email with To, Subject, and Body fields.", "sources": [] }}}},
+    "output_fields": {
+      "inline": { "array": { "values": [
+        { "wellKnown": { "extractionColumn": { "id": "To", "name": "To", "dataType": 1 }}},
+        { "wellKnown": { "extractionColumn": { "id": "Subject", "name": "Subject", "dataType": 1 }}},
+        { "wellKnown": { "extractionColumn": { "id": "Body", "name": "Body", "dataType": 1 }}}
+      ]}}
+    }
+  }
+}
+\`\`\`
+
+Each output_field becomes a separate output (e.g., \`generate_email.To\`) that can wire directly to \`send_email_agent\`.
+
+## Pattern C: fixed_response for Simple Template Formatting
+
+When you already have a clean extracted value and just need TEXT_WITH_SOURCES wrapping:
+
+\`\`\`json
+{
+  "name": "fmt_email",
+  "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "fixed_response" }, "version": "v1" },
+  "inputs": {
+    "template": { "inline": { "wellKnown": { "textWithSources": { "text": "{{email_address}}", "sources": [] }}}},
+    "custom_data": { "actionOutput": { "actionName": "entity_extraction", "output": "extraction_result" }}
+  }
+}
+\`\`\`
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| \`entity_extraction → email_to\` | Type mismatch (ANY → TEXT_WITH_SOURCES) | Add json_mapper + fixed_response |
+| \`call_llm.response → email_to\` | Full LLM response as email address | Extract with json_mapper or use output_fields |
+| \`json_mapper → email_to\` | json_mapper outputs JSON_VALUE, not TEXT_WITH_SOURCES | Add fixed_response between json_mapper and email |
+| Missing fixed_response | Type still mismatched | fixed_response converts ANY → TEXT_WITH_SOURCES |
+
+## See Also
+
+- \`ema://rules/anti-patterns\` — includes \`entity-extraction-direct-to-email\` anti-pattern
+- \`ema://rules/extraction-column-format\` — for output_fields structure
+`;
+        },
+    },
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Workflow Node Reference - per-node I/O types, semantics, categorizer patterns
+    // Consolidated from .context/public/guides/workflow-builder-patterns.md
+    // ─────────────────────────────────────────────────────────────────────────────
+    {
+        uri: "ema://docs/workflow-node-reference",
+        name: "docs/workflow-node-reference",
+        description: "Complete workflow node reference: per-node I/O types, categorizer patterns (runIf/enumTypes), " +
+            "LLM named_inputs convention, temperature guidelines, data types between nodes",
+        mimeType: "text/markdown",
+        generate: async () => {
+            let md = `# Workflow Node Reference\n\n`;
+            md += `Practical reference for building Ema workflows. Covers per-node I/O semantics, `;
+            md += `categorizer configuration, LLM patterns, and data type compatibility.\n\n`;
+            md += `## Data Types Between Nodes\n\n`;
+            md += `| Type | Code Constant | Description | Example |\n`;
+            md += `|------|---------------|-------------|---------|\n`;
+            md += `| **Plain Text** | \`WELL_KNOWN_TYPE_TEXT_WITH_SOURCES\` | Text with optional citation metadata | User's message, LLM response |\n`;
+            md += `| **Conversation** | \`WELL_KNOWN_TYPE_CHAT_CONVERSATION\` | Structured message history (role + content) | Full chat thread |\n`;
+            md += `| **Search Results** | \`WELL_KNOWN_TYPE_SEARCH_RESULT\` | Retrieved document chunks with citations | KB search results |\n`;
+            md += `| **Enum** | \`WELL_KNOWN_TYPE_ENUM\` | Category/classification signal for routing | \`category::Schedule Appointment\` |\n`;
+            md += `| **Document** | \`WELL_KNOWN_TYPE_DOCUMENT\` | Uploaded file content | PDF, DOCX for extraction |\n`;
+            md += `| **Any** | \`WELL_KNOWN_TYPE_ANY\` | Untyped — needs intermediary for type-safe wiring | entity_extraction output |\n\n`;
+            md += `**Critical**: Types are NOT interchangeable. \`CHAT_CONVERSATION\` into a \`TEXT_WITH_SOURCES\` input causes type mismatch errors. Use converter nodes when needed.\n\n`;
+            md += `---\n\n`;
+            md += `## Input Semantics by Context\n\n`;
+            md += `The same input name means different things depending on the node:\n\n`;
+            md += `| Input Name | In Search Nodes | In Respond Nodes | In Extract Nodes | In Categorizers |\n`;
+            md += `|------------|-----------------|-------------------|-------------------|------------------|\n`;
+            md += `| \`query\` | Search term to look up | User's question to answer | Source text to analyze | N/A |\n`;
+            md += `| \`conversation\` | N/A | N/A (use named_inputs) | N/A | Full history for classification |\n`;
+            md += `| \`trigger_when\` | N/A | "Should I run?" | "Should I run?" | N/A |\n`;
+            md += `| \`named_inputs_*\` | N/A | Additional context | Additional context | N/A |\n\n`;
+            md += `**Mental model:** \`query\` = "What to process?" · \`conversation\` = "Full context" · \`trigger_when\` = "Should I run?" · \`named_inputs_*\` = "Extra context"\n\n`;
+            md += `---\n\n`;
+            md += `## Node Type Reference\n\n`;
+            md += `### chat_trigger\n`;
+            md += `Entry point for chat/voice workflows.\n`;
+            md += `- **Inputs**: None (system event)\n`;
+            md += `- **Outputs**: \`user_query\` (TEXT_WITH_SOURCES), \`chat_conversation\` (CHAT_CONVERSATION)\n`;
+            md += `- **Pairs with**: Intent routers, search nodes, LLM nodes\n\n`;
+            md += `### document_trigger\n`;
+            md += `Entry point for dashboard workflows (file upload per row).\n`;
+            md += `- **Inputs**: None (system event — triggered when row created/file uploaded)\n`;
+            md += `- **Outputs**: \`document_content\` (DOCUMENT), \`row_data\` (ANY — column values)\n`;
+            md += `- **Pairs with**: entity_extraction_with_documents, call_llm, search\n`;
+            md += `- **Critical**: Dashboard personas only. Each row triggers one workflow execution.\n\n`;
+            md += `### chat_categorizer\n`;
+            md += `Classify conversation into intent categories for routing.\n`;
+            md += `- **Inputs**: \`conversation\` (CHAT_CONVERSATION) — must be full history, NOT user_query\n`;
+            md += `- **Outputs**: \`category\` (ENUM) — one per configured category\n`;
+            md += `- **Critical**: Always include Fallback category. Every category needs a handler. Must have \`typeArguments.categories\` pointing to enumType.\n\n`;
+            md += `### text_categorizer/v1\n`;
+            md += `Classify text content (not conversation) for routing.\n`;
+            md += `- **Inputs**: \`named_inputs\` (multiBinding)\n`;
+            md += `- **Outputs**: \`category\` (ENUM)\n`;
+            md += `- **Critical**: \`text_categorizer/v0\` is deprecated — use v1 with \`named_inputs\`.\n\n`;
+            md += `### search/v2\n`;
+            md += `Retrieve relevant documents from uploaded knowledge base.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`datastore_configs\` (from widget)\n`;
+            md += `- **Outputs**: \`search_results\` (SEARCH_RESULT)\n`;
+            md += `- **Critical**: NOT an LLM node — do NOT include \`model_config\`. Data must be uploaded first. \`search/v0\` is deprecated.\n\n`;
+            md += `### conversation_to_search_query\n`;
+            md += `Convert multi-turn conversation to a search-optimized query.\n`;
+            md += `- **Inputs**: \`conversation\` (CHAT_CONVERSATION)\n`;
+            md += `- **Outputs**: \`summarized_conversation\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Required for multi-turn chat search. Direct CHAT_CONVERSATION → search causes type mismatch.\n\n`;
+            md += `### call_llm/v2\n`;
+            md += `Generate natural language response using LLM.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`named_inputs_*\` (ANY — flexible), \`trigger_when\` (ENUM)\n`;
+            md += `- **Outputs**: \`response_with_sources\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Must wire to WORKFLOW_OUTPUT or response is lost. \`call_llm/v0\` is deprecated.\n\n`;
+            md += `### respond_for_external_actions\n`;
+            md += `Generate conversation-aware response from search results or tool outputs.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), \`external_action_result\` (TEXT_WITH_SOURCES/SEARCH_RESULT)\n`;
+            md += `- **Outputs**: \`response\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Critical**: Replaces deprecated \`respond_with_sources/v0\`. Has built-in citation handling and conversation awareness.\n\n`;
+            md += `### fixed_response/v1\n`;
+            md += `Return a static predefined message.\n`;
+            md += `- **Inputs**: \`trigger_when\` (ENUM), \`named_inputs_*\` for template variables\n`;
+            md += `- **Outputs**: \`fixed_response_with_sources\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Pairs with**: Categorizers (as fallback), type conversion with \`{{variables}}\` templates, send_email_agent\n\n`;
+            md += `### external_action_caller\n`;
+            md += `Call external APIs/tools (ServiceNow, Salesforce, calendars).\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES), \`conversation\` (CHAT_CONVERSATION), tool configuration\n`;
+            md += `- **Outputs**: \`tool_execution_result\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Pairs with**: Entity extractors (for parameters), respond nodes (for result formatting)\n\n`;
+            md += `### entity_extraction_with_documents\n`;
+            md += `Extract structured entities grounded in provided documents.\n`;
+            md += `- **Inputs**: \`documents\` (DOCUMENT), extraction column config\n`;
+            md += `- **Outputs**: \`extraction_columns\` (ANY — structured extraction results)\n`;
+            md += `- **Critical**: Output type is ANY — needs intermediary (json_mapper + fixed_response) before send_email inputs.\n`;
+            md += `- See \`ema://rules/extraction-column-format\` for column schema.\n\n`;
+            md += `### send_email_agent\n`;
+            md += `Send email with specified recipient, subject, and body.\n`;
+            md += `- **Inputs**: \`email_to\` (TEXT_WITH_SOURCES), \`email_subject\` (ANY), \`email_body\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`send_status\` (ANY)\n`;
+            md += `- **Critical**: Inputs must be TEXT_WITH_SOURCES — use intermediary chain from ANY-typed sources.\n`;
+            md += `- See \`ema://rules/email-input-wiring\` for wiring patterns.\n\n`;
+            md += `### json_mapper\n`;
+            md += `Extract specific fields from JSON/structured data into individual outputs.\n`;
+            md += `- **Inputs**: \`input_json\` (ANY), mapping rules\n`;
+            md += `- **Outputs**: \`output_json\` per mapped field\n`;
+            md += `- **Pairs with**: entity_extraction (field extraction), fixed_response (type conversion)\n\n`;
+            md += `### rule_validation_with_documents\n`;
+            md += `Check extracted data against business rules (compliance, thresholds).\n`;
+            md += `- **Inputs**: \`primary_docs\` (DOCUMENT), \`map_of_extracted_columns\` (ANY)\n`;
+            md += `- **Outputs**: \`ruleset_output\` (ANY — validation results)\n`;
+            md += `- **Critical**: Rules configured in UI settings panel, not via workflow_def inputs.\n\n`;
+            md += `### live_web_search\n`;
+            md += `Real-time web search for current information.\n`;
+            md += `- **Inputs**: \`query\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`web_search_results\` (SEARCH_RESULT)\n`;
+            md += `- **Critical**: No data upload needed (searches the web).\n\n`;
+            md += `### combine_search_results\n`;
+            md += `Merge results from multiple search sources with deduplication.\n`;
+            md += `- **Inputs**: \`search_results_1\` (SEARCH_RESULT), \`search_results_2\` (SEARCH_RESULT)\n`;
+            md += `- **Outputs**: \`combined_results\` (SEARCH_RESULT)\n`;
+            md += `- **Pairs with**: search/v2 + live_web_search, or any two search sources\n`;
+            md += `- **Note**: \`combine_search_results/v0\` is deprecated. For new workflows, prefer \`call_llm\` with multiple \`named_inputs\` to combine search results.\n\n`;
+            md += `### response_validator\n`;
+            md += `Validate LLM output against quality/compliance criteria.\n`;
+            md += `- **Inputs**: \`reference_query\` (TEXT_WITH_SOURCES), \`response_to_validate\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`abstain_reason\` (TEXT_WITH_SOURCES — reason for rejection, empty if valid)\n\n`;
+            md += `### abstain_action\n`;
+            md += `Provide a safe decline response when AI should not answer.\n`;
+            md += `- **Inputs**: \`abstain_reason\` (TEXT_WITH_SOURCES)\n`;
+            md += `- **Outputs**: \`abstain_reason\` (TEXT_WITH_SOURCES — decline message)\n\n`;
+            md += `---\n\n`;
+            md += `## Categorizer Configuration\n\n`;
+            md += `### Defining enumTypes\n\n`;
+            md += `Categories must be defined in \`workflow_def.enumTypes\`:\n\n`;
+            md += `\`\`\`json\n`;
+            md += `"enumTypes": [{\n`;
+            md += `  "name": { "name": "intent_categories", "namespaces": [] },\n`;
+            md += `  "options": [\n`;
+            md += `    { "name": "Sales", "description": "Sales inquiries" },\n`;
+            md += `    { "name": "Support", "description": "Technical support" },\n`;
+            md += `    { "name": "General", "description": "General questions" },\n`;
+            md += `    { "name": "Fallback", "description": "Unclear or unmatched intents" }\n`;
+            md += `  ]\n`;
+            md += `}]\n`;
+            md += `\`\`\`\n\n`;
+            md += `### typeArguments\n\n`;
+            md += `The categorizer's \`typeArguments\` must reference the enum:\n\n`;
+            md += `\`\`\`json\n`;
+            md += `"typeArguments": {\n`;
+            md += `  "categories": {\n`;
+            md += `    "enumType": { "name": { "name": "intent_categories", "namespaces": [] } },\n`;
+            md += `    "isList": false\n`;
+            md += `  }\n`;
+            md += `}\n`;
+            md += `\`\`\`\n\n`;
+            md += `**Critical**: Empty \`typeArguments\` causes deploy failure.\n\n`;
+            md += `### runIf Condition Format\n\n`;
+            md += `\`\`\`json\n`;
+            md += `{\n`;
+            md += `  "lhs": {\n`;
+            md += `    "actionOutput": { "actionName": "chat_categorizer", "output": "category" },\n`;
+            md += `    "autoDetectedBinding": false\n`;
+            md += `  },\n`;
+            md += `  "operator": 1,\n`;
+            md += `  "rhs": {\n`;
+            md += `    "inline": { "enumValue": "Market_Impact" },\n`;
+            md += `    "autoDetectedBinding": false\n`;
+            md += `  }\n`;
+            md += `}\n`;
+            md += `\`\`\`\n\n`;
+            md += `| Operator | Meaning | Use Case |\n`;
+            md += `|----------|---------|----------|\n`;
+            md += `| \`1\` | Equals (\`==\`) | Route to handler when category matches |\n`;
+            md += `| \`2\` | Not equals (\`!=\`) | Run for all categories except one |\n\n`;
+            md += `For OR conditions (run for Sales OR General), use \`operator: 2\` with Fallback: \`category != Fallback\`.\n\n`;
+            md += `### Nested Categorizers\n\n`;
+            md += `For complex routing, chain categorizers:\n`;
+            md += `\`\`\`\n`;
+            md += `chat_categorizer (Level 1: HR, IT, General, Fallback)\n`;
+            md += `  └─→ text_categorizer (Level 2 for HR: Benefits, Leave, Payroll, Fallback)\n`;
+            md += `\`\`\`\n\n`;
+            md += `---\n\n`;
+            md += `## LLM Configuration (call_llm)\n\n`;
+            md += `### named_inputs Convention\n\n`;
+            md += `\`call_llm\` accepts additional context via suffix pattern \`named_inputs_<Descriptive_Name>\`:\n\n`;
+            md += `| Named Input | Type | Purpose |\n`;
+            md += `|-------------|------|----------|\n`;
+            md += `| \`named_inputs_Search_Results\` | SEARCH_RESULT | KB search results for RAG |\n`;
+            md += `| \`named_inputs_Conversation\` | CHAT_CONVERSATION | Full conversation history |\n`;
+            md += `| \`named_inputs_Intent\` | ENUM | Detected category from categorizer |\n`;
+            md += `| \`named_inputs_Current_Message\` | TEXT_WITH_SOURCES | Current user message |\n`;
+            md += `| \`named_inputs_Tool_Result\` | TEXT_WITH_SOURCES | External action output |\n\n`;
+            md += `\`named_inputs\` accepts **ANY** type — this is how you pass CHAT_CONVERSATION and SEARCH_RESULT into LLM nodes.\n\n`;
+            md += `### Temperature Guidelines\n\n`;
+            md += `| Use Case | Temperature | Why |\n`;
+            md += `|----------|-------------|-----|\n`;
+            md += `| Entity extraction | 0.0-0.3 | Accuracy over creativity |\n`;
+            md += `| Document generation | 0.3-0.5 | Consistent formatting |\n`;
+            md += `| General Q&A / chat | 0.5-0.7 | Balanced creativity and accuracy |\n`;
+            md += `| Creative writing | 0.7-1.0 | More varied output |\n\n`;
+            md += `### Consolidation Rule\n\n`;
+            md += `If multiple \`call_llm\` nodes share the same inputs and differ only by \`trigger_when\` gate, consolidate them:\n`;
+            md += `1. Create one \`call_llm\` that runs when not Fallback\n`;
+            md += `2. Wire \`categorizer.category → call_llm.named_inputs_Intent\`\n`;
+            md += `3. Update prompt: "Based on the detected intent ({{Intent}}), respond accordingly"\n`;
+            md += `4. Keep separate nodes only when intents require different tools, search sources, or safety constraints.\n\n`;
+            md += `---\n\n`;
+            md += `## See Also\n\n`;
+            md += `- \`ema://rules/input-sources\` — Input source validation rules\n`;
+            md += `- \`ema://rules/extraction-column-format\` — Entity extraction column schema\n`;
+            md += `- \`ema://rules/email-input-wiring\` — Email field wiring patterns\n`;
+            md += `- \`ema://rules/json-output-patterns\` — custom_agent + json_mapper patterns\n`;
+            md += `- \`ema://rules/chat-response-wiring\` — Chat response wiring rules\n`;
+            md += `- \`ema://rules/anti-patterns\` — Common workflow anti-patterns\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 + fingerprint, " +
+                    "2) Generate/modify workflow_def, " +
+                    "3) workflow(mode='deploy', persona_id='...', base_fingerprint='<fingerprint>', workflow_def={...}) " +
+                    "(or workflow_def_path='/path/to/wf.json' for large payloads)",
+                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)",
+                    "For approval workflows: enable HITL flag on send_email_agent or entity_extraction_with_documents (only nodes that support HITL). general_hitl is NOT deployable.",
+                ],
+                _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>", base_fingerprint="<fingerprint>", workflow_def={...})
+\n# For large payloads:\n# workflow(mode="deploy", persona_id="<ID>", base_fingerprint="<fingerprint>", workflow_def_path="/path/to/wf.json")
+\`\`\`
+Use \`workflow(mode="validate", ...)\` before deploy to catch structural/semantic issues.
+
+### 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",
+        name: "catalog/templates",
+        description: "Persona templates from Ema API: pre-configured AI Employee templates (chatbot_starter, voicebot, dashboard, etc.)",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            const templates = await getDynamicPersonaTemplates({ env: ctx.env });
+            if (templates.length > 0) {
+                return JSON.stringify(templates.map(templateDtoToResource), null, 2);
+            }
+            // Fallback when API unavailable - provide guidance
+            return JSON.stringify({
+                _note: "API templates unavailable. Use catalog(method='list', type='templates') tool which connects to API directly, or use template(config='voice|chat|dashboard') for config fallbacks.",
+                fallback_types: ["voice", "chat", "dashboard"],
+                how_to_get: "catalog(method='list', type='templates') or template(config='voice')",
+            }, null, 2);
+        },
+    },
+    {
+        uri: "ema://catalog/templates-summary",
+        name: "catalog/templates-summary",
+        description: "Persona templates summary: template names, categories, and descriptions for quick reference",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            const templates = await getDynamicPersonaTemplates({ env: ctx.env });
+            if (templates.length === 0) {
+                return `# Persona Templates
+
+> API templates not available. Use one of these alternatives:
+
+## Option 1: Use the catalog tool directly
+\`\`\`
+catalog(method="list", type="templates")
+\`\`\`
+This connects to the API and may have different credentials.
+
+## Option 2: Use config fallbacks
+\`\`\`
+template(config="voice")   // Voice AI config template
+template(config="chat")    // Chat AI config template
+template(config="dashboard") // Dashboard AI config template
+\`\`\`
+
+## Option 3: Create from scratch
+\`\`\`
+persona(method="create", name="My AI", type="voice|chat|dashboard")
+\`\`\`
+`;
+            }
+            const byCategory = new Map();
+            for (const t of templates) {
+                const cat = t.category || "GENERAL";
+                if (!byCategory.has(cat))
+                    byCategory.set(cat, []);
+                byCategory.get(cat).push(t);
+            }
+            let md = "# Persona Templates (from API)\n\n";
+            md += `> ${templates.length} templates available for creating AI Employees\n\n`;
+            for (const [category, tpls] of byCategory) {
+                md += `## ${category}\n\n`;
+                md += "| Template | Type | Description |\n";
+                md += "|----------|------|-------------|\n";
+                for (const t of tpls) {
+                    const triggerType = t.trigger_type || "-";
+                    const desc = t.description?.slice(0, 80) || "-";
+                    md += `| \`${t.name}\` | ${triggerType} | ${desc}... |\n`;
+                }
+                md += "\n";
+            }
+            return md;
+        },
+    },
+    // Action Schema - Complete action definitions from ema repo
+    {
+        uri: "ema://schema/actions",
+        name: "schema/actions",
+        description: "Complete action schema: all workflow actions with inputs, outputs, types, and documentation from ema_backend/grpc",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            const schema = await getDynamicActionSchema({ env: ctx.env });
+            return JSON.stringify(schema, null, 2);
+        },
+    },
+    {
+        uri: "ema://schema/actions-summary",
+        name: "schema/actions-summary",
+        description: "Action schema summary: action names, versions, and descriptions for quick reference",
+        mimeType: "text/markdown",
+        generate: async (ctx) => {
+            const schema = await getDynamicActionSchema({ env: ctx.env });
+            if (schema.actions.length === 0) {
+                return "# Action Schema\n\n> No actions loaded. Check API connectivity or bundled schema.\n";
+            }
+            let md = "# Action Schema\n\n";
+            md += `> ${schema.actions.length} actions loaded (source: ${schema.source})\n`;
+            md += `> Version: ${schema.version}\n\n`;
+            const byCategory = new Map();
+            for (const action of schema.actions) {
+                const cat = action.category || "OTHER";
+                if (!byCategory.has(cat))
+                    byCategory.set(cat, []);
+                byCategory.get(cat).push(action);
+            }
+            for (const [category, actions] of byCategory) {
+                md += `## ${category.replace("ACTION_CATEGORY_", "")}\n\n`;
+                md += "| Action | Version | Description | Inputs | Outputs |\n";
+                md += "|--------|---------|-------------|--------|--------|\n";
+                for (const action of actions) {
+                    const inputs = action.inputs?.size || 0;
+                    const outputs = action.outputs?.size || 0;
+                    const desc = action.description?.slice(0, 50) || "-";
+                    md += `| \`${action.name}\` | ${action.version || "v0"} | ${desc}... | ${inputs} | ${outputs} |\n`;
+                }
+                md += "\n";
+            }
+            return md;
+        },
+    },
+    {
+        uri: "ema://schema/action/:name",
+        name: "schema/action",
+        description: "Individual action schema by name (e.g., ema://schema/action/call_llm)",
+        mimeType: "application/json",
+        generate: async (ctx) => {
+            // This is a template - actual resolution happens in getResource
+            return JSON.stringify({ error: "Use specific action name in URI" }, null, 2);
+        },
+    },
+    {
+        uri: "ema://schema/workflow-def",
+        name: "schema/workflow-def",
+        description: "Complete workflow_def schema with examples for Chat, Voice, and Dashboard personas. Essential reference for building workflows.",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Workflow Definition Schema
+
+This document describes the structure of \`workflow_def\` - the JSON format used to deploy AI Employee workflows.
+
+## Two-Level Architecture
+
+1. **WorkflowSpec** (High-level) - What YOU build:
+   - Nodes, inputs, categories, result mappings
+   - Human-readable, easy to reason about
+   - Gets compiled to workflow_def
+
+2. **workflow_def** (Low-level) - What gets deployed:
+   - Compiled JSON structure
+   - Namespaces, action references, edges
+   - Generated by MCP from WorkflowSpec
+
+## WorkflowSpec Structure
+
+\`\`\`typescript
+interface WorkflowSpec {
+  name: string;                    // Workflow display name
+  description: string;             // What it does
+  personaType: "voice" | "chat" | "dashboard";
+  nodes: Node[];                   // Workflow actions
+  resultMappings: ResultMapping[]; // What outputs to return
+}
+
+interface Node {
+  id: string;                      // Unique identifier (e.g., "trigger", "search", "respond")
+  actionType: string;              // Action type (e.g., "chat_trigger", "search", "call_llm")
+  displayName: string;             // Human-readable name
+  description?: string;            // What this node does
+  inputs?: Record<string, InputBinding>;  // Input configuration
+  categories?: Category[];         // For categorizers only
+  tools?: Tool[];                  // For external action callers
+  runIf?: RunIfCondition;          // Conditional execution
+}
+
+interface InputBinding {
+  type: "action_output" | "literal" | "widget_config" | "llm_inferred";
+  actionName?: string;             // Source node ID (for action_output)
+  output?: string;                 // Output name from source
+  value?: any;                     // Static value (for literal)
+  widgetName?: string;             // Widget name (for widget_config)
+}
+
+interface Category {
+  name: string;                    // Category name (e.g., "Sales", "Support", "Fallback")
+  description: string;             // When to route here
+  examples?: string[];             // Example phrases
+}
+
+interface ResultMapping {
+  nodeId: string;                  // Node that produces the output
+  output: string;                  // Output name
+}
+\`\`\`
+
+## Trigger Types by Persona
+
+| Persona Type | Trigger ActionType | Key Outputs |
+|--------------|-------------------|-------------|
+| **Chat** | \`chat_trigger\` | user_query, chat_conversation |
+| **Voice** | \`chat_trigger\` | user_query, chat_conversation |
+| **Dashboard** | \`document_trigger\` | document_content, row_data |
+
+## Example: Chat Persona (KB Search)
+
+\`\`\`json
+{
+  "name": "FAQ Bot",
+  "description": "Answer questions from knowledge base",
+  "personaType": "chat",
+  "nodes": [
+    {
+      "id": "trigger",
+      "actionType": "chat_trigger",
+      "displayName": "Chat Input"
+    },
+    {
+      "id": "search",
+      "actionType": "search",
+      "displayName": "Search Knowledge Base",
+      "inputs": {
+        "query": {
+          "type": "action_output",
+          "actionName": "trigger",
+          "output": "user_query"
+        }
+      }
+    },
+    {
+      "id": "respond",
+      "actionType": "respond_for_external_actions",
+      "displayName": "Generate Response",
+      "inputs": {
+        "search_results": {
+          "type": "action_output",
+          "actionName": "search",
+          "output": "search_results"
+        },
+        "conversation": {
+          "type": "action_output",
+          "actionName": "trigger",
+          "output": "chat_conversation"
+        }
+      }
+    }
+  ],
+  "resultMappings": [
+    { "nodeId": "respond", "output": "response" }
+  ]
+}
+\`\`\`
+
+## Example: Dashboard Persona (Document Extraction)
+
+\`\`\`json
+{
+  "name": "Invoice Processor",
+  "description": "Extract data from invoices",
+  "personaType": "dashboard",
+  "nodes": [
+    {
+      "id": "trigger",
+      "actionType": "document_trigger",
+      "displayName": "Document Input"
+    },
+    {
+      "id": "extract",
+      "actionType": "entity_extraction",
+      "displayName": "Extract Invoice Data",
+      "inputs": {
+        "document": {
+          "type": "action_output",
+          "actionName": "trigger",
+          "output": "document_content"
+        },
+        "extraction_schema": {
+          "type": "literal",
+          "value": {
+            "fields": ["invoice_number", "amount", "date", "vendor"]
+          }
+        }
+      }
+    },
+    {
+      "id": "respond",
+      "actionType": "fixed_response",
+      "displayName": "Return Results",
+      "inputs": {
+        "data": {
+          "type": "action_output",
+          "actionName": "extract",
+          "output": "extracted_entities"
+        }
+      }
+    }
+  ],
+  "resultMappings": [
+    { "nodeId": "respond", "output": "response" }
+  ]
+}
+\`\`\`
+
+## Example: Voice Persona (Intent Routing)
+
+\`\`\`json
+{
+  "name": "IT Support Voice",
+  "description": "Handle IT support calls",
+  "personaType": "voice",
+  "nodes": [
+    {
+      "id": "trigger",
+      "actionType": "chat_trigger",
+      "displayName": "Voice Input"
+    },
+    {
+      "id": "categorize",
+      "actionType": "chat_categorizer",
+      "displayName": "Identify Intent",
+      "inputs": {
+        "conversation": {
+          "type": "action_output",
+          "actionName": "trigger",
+          "output": "chat_conversation"
+        }
+      },
+      "categories": [
+        { "name": "Password Reset", "description": "User needs password help" },
+        { "name": "Create Ticket", "description": "User wants to create a ticket" },
+        { "name": "Fallback", "description": "Anything else" }
+      ]
+    },
+    {
+      "id": "handle_password",
+      "actionType": "call_llm",
+      "displayName": "Password Reset Handler",
+      "runIf": {
+        "sourceAction": "categorize",
+        "sourceOutput": "category",
+        "operator": "eq",
+        "value": "Password Reset"
+      },
+      "inputs": {
+        "prompt": {
+          "type": "literal",
+          "value": "Guide user through password reset process..."
+        }
+      }
+    },
+    {
+      "id": "handle_ticket",
+      "actionType": "external_action_caller",
+      "displayName": "Create ServiceNow Ticket",
+      "runIf": {
+        "sourceAction": "categorize",
+        "sourceOutput": "category",
+        "operator": "eq",
+        "value": "Create Ticket"
+      },
+      "tools": [
+        { "name": "Create_Incident", "namespace": "service_now" }
+      ]
+    },
+    {
+      "id": "handle_fallback",
+      "actionType": "call_llm",
+      "displayName": "General Response",
+      "runIf": {
+        "sourceAction": "categorize",
+        "sourceOutput": "category",
+        "operator": "eq",
+        "value": "Fallback"
+      }
+    }
+  ],
+  "resultMappings": [
+    { "nodeId": "handle_password", "output": "response" },
+    { "nodeId": "handle_ticket", "output": "result" },
+    { "nodeId": "handle_fallback", "output": "response" }
+  ]
+}
+\`\`\`
+
+## Critical Rules
+
+1. **Always include Fallback** - Every categorizer MUST have a Fallback category
+2. **Trigger type matters** - Dashboard uses document_trigger, others use chat_trigger  
+3. **Wire conversations correctly** - Categorizers need chat_conversation, search needs user_query
+4. **Map results** - At least one node must have a resultMapping to WORKFLOW_OUTPUT
+5. **Check deprecated actions** - Always verify against ema://rules/deprecated-actions-summary
+
+## Common Input Bindings
+
+| Source | Type | Example |
+|--------|------|---------|
+| Previous node output | action_output | \`{ type: "action_output", actionName: "search", output: "results" }\` |
+| Static value | literal | \`{ type: "literal", value: "Hello world" }\` |
+| Widget config | widget_config | \`{ type: "widget_config", widgetName: "conversationSettings" }\` |
+| LLM should infer | llm_inferred | \`{ type: "llm_inferred" }\` |
+
+## Deployment Flow
+
+1. Build your WorkflowSpec (structure above)
+2. Call \`workflow(mode="validate", workflow_spec={...})\` to check for errors
+3. Call \`workflow(mode="get", persona_id="...")\` to get the latest fingerprint (stale-state protection)
+4. Call \`workflow(mode="deploy", persona_id="...", base_fingerprint="<fingerprint>", workflow_def={...})\` to deploy
+
+For large payloads, use \`workflow_def_path\` instead of inline \`workflow_def\`.
+
+The MCP compiles your WorkflowSpec into the API's workflow_def format automatically.
+
+## Raw workflow_def Input Binding Formats
+
+When deploying raw workflow_def (not WorkflowSpec), inputs use protobuf-compatible JSON.
+These formats are CRITICAL - wrong formats cause HTTP 500 with no error details.
+
+### Action Output (reference another node's output)
+\`\`\`json
+{
+  "actionOutput": { "actionName": "source_node_name", "output": "output_name" },
+  "autoDetectedBinding": false
+}
+\`\`\`
+
+### Widget Config (reference a proto_config widget)
+\`\`\`json
+{
+  "widgetConfig": { "widgetName": "fusionModel" },
+  "autoDetectedBinding": true
+}
+\`\`\`
+
+### Inline String (STRING type)
+\`\`\`json
+{
+  "inline": { "wellKnown": { "stringValue": "your text here" } },
+  "autoDetectedBinding": false
+}
+\`\`\`
+
+### Inline Text With Sources (TEXT_WITH_SOURCES type)
+\`\`\`json
+{
+  "inline": {
+    "wellKnown": {
+      "textWithSources": {
+        "text": "your text here",
+        "sources": [],
+        "resultConfidence": 0,
+        "toolSources": [],
+        "resultType": 0
+      }
+    }
+  },
+  "autoDetectedBinding": false
+}
+\`\`\`
+**WARNING**: STRING ≠ TEXT_WITH_SOURCES. Using stringValue where textWithSources is expected causes HTTP 500.
+
+### Inline Enum Value
+\`\`\`json
+{
+  "inline": { "enumValue": "CategoryName" },
+  "autoDetectedBinding": false
+}
+\`\`\`
+
+### Named Inputs (multiBinding format - REQUIRED for named_inputs)
+\`\`\`json
+{
+  "multiBinding": {
+    "elements": [
+      {
+        "namedBinding": {
+          "name": "context_key",
+          "value": {
+            "actionOutput": { "actionName": "source_node", "output": "response_with_sources" },
+            "autoDetectedBinding": false
+          },
+          "description": "",
+          "isOptional": false
+        },
+        "autoDetectedBinding": false
+      }
+    ]
+  },
+  "autoDetectedBinding": false
+}
+\`\`\`
+
+### Action Name Format
+\`\`\`json
+{
+  "action": {
+    "name": { "namespaces": ["actions", "emainternal"], "name": "call_llm" },
+    "version": "v2"
+  }
+}
+\`\`\`
+**WARNING**: Empty namespaces [] causes deploy failure. Always use ["actions", "emainternal"].
+
+### text_categorizer/v1 Requirements
+- Uses \`named_inputs\` (multiBinding format), NOT \`text\` input from deprecated v0
+- Requires \`typeArguments.categories\` pointing to an enumType
+- \`categorization_instructions\` input type is TEXT_WITH_SOURCES (use textWithSources, NOT stringValue)
+- Must define matching enumType in workflow_def.enumTypes[] with Fallback category
+`;
+        },
+    },
+    {
+        uri: "ema://schema/workflow-def-json",
+        name: "schema/workflow-def-json",
+        description: "JSON Schema for workflow_def validation. Use for pre-validation before deployment.",
+        mimeType: "application/json",
+        generate: async () => {
+            const { getWorkflowDefSchemaJSON } = await import("./domain/workflow-def-schema.js");
+            return getWorkflowDefSchemaJSON();
+        },
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Guidance Resources - Single source of truth, multiple export formats
+    // ─────────────────────────────────────────────────────────────────────────
+    {
+        uri: "ema://docs/usage-guide",
+        name: "docs/usage-guide",
+        description: "Complete MCP usage guide with rules, patterns, and tool reference (markdown format)",
+        mimeType: "text/markdown",
+        generate: async () => {
+            const { exportAsMarkdown } = await import("./guidance.js");
+            return exportAsMarkdown();
+        },
+    },
+    {
+        uri: "ema://guidance/rules",
+        name: "guidance/rules",
+        description: "Structured guidance rules (JSON) - for programmatic consumption by other services",
+        mimeType: "application/json",
+        generate: async () => {
+            const { exportAsJSON } = await import("./guidance.js");
+            return exportAsJSON();
+        },
+    },
+    {
+        uri: "ema://guidance/cursor-rule",
+        name: "guidance/cursor-rule",
+        description: "Guidance exported as Cursor .mdc rule format - for IDE integration",
+        mimeType: "text/markdown",
+        generate: async () => {
+            const { exportAsCursorRule } = await import("./guidance.js");
+            return exportAsCursorRule();
+        },
+    },
+    {
+        uri: "ema://guidance/server-instructions",
+        name: "guidance/server-instructions",
+        description: "Server instructions (the content injected into MCP init response)",
+        mimeType: "text/plain",
+        generate: async () => {
+            const { generateServerInstructions } = await import("./guidance.js");
+            return generateServerInstructions();
+        },
+    },
+    {
+        uri: "ema://docs/debugging-guide",
+        name: "docs/debugging-guide",
+        description: "Guide for debugging workflow executions — drill-down flow, status meanings, metrics, and common failure patterns",
+        mimeType: "text/markdown",
+        generate: async () => {
+            return `# Debugging Workflow Executions
+
+## Typical Debugging Flow
+
+The debug tool follows a drill-down pattern that mirrors the web UI's Audit tab:
+
+\`\`\`
+1. debug(method="conversations", persona_id="...")
+   → List audit conversations with optional filters (date, channel, rating)
+
+2. debug(method="conversation_detail", conversation_id="...")
+   → See messages with workflow_run_ids linking to execution traces
+
+3. debug(method="show_work", persona_id="...", workflow_run_id="...")
+   → Overview of ALL actions in the workflow run: status, cost, latency, I/O
+
+4. debug(method="action_detail", persona_id="...", workflow_run_id="...", action_name="...")
+   → Deep trace: full inputs/outputs, LLM prompts/responses, steps, HITL rounds
+\`\`\`
+
+Each response includes \`_next_step\` hints to guide you through this flow.
+
+## Action Run Status Values
+
+| Status | Meaning |
+|--------|---------|
+| SUCCESS | Action completed without errors |
+| ERRORED | Action failed — check error_info and steps for details |
+| WARNING | Action completed but with warnings (e.g., partial results) |
+| NOT_RUN | Action was skipped (branch not taken, condition not met) |
+| PAUSED | Action is waiting (e.g., HITL approval pending) |
+
+## Key Metrics
+
+- **llm_call_count**: Number of LLM invocations in the action
+- **llm_cost_usd**: Total LLM cost across all calls (in USD)
+- **llm_latency_ms**: Total LLM processing time
+- **step_count**: Number of execution steps (sub-operations within the action)
+- **hitl_round_count**: Number of human-in-the-loop interaction rounds
+
+## Search
+
+\`debug(method="search", persona_id="...", query="...")\` performs full-text search
+across conversation messages. Useful for finding specific user queries or bot responses.
+
+**Note**: The search method relies on DebuggerService which may not be deployed in all environments.
+If you get a 404 or "unimplemented" error, use the drill-down flow instead (conversations → conversation_detail → show_work).
+
+## Common Failure Patterns
+
+### Empty search results
+- **Symptom**: Search/knowledge action returns no results
+- **Check**: \`show_work\` → look at the search action's inputs (query, data source)
+- **Common cause**: No data sources uploaded, or embedding not completed
+
+### LLM cost spike
+- **Symptom**: High \`llm_cost_usd\` on an action
+- **Check**: \`action_detail\` → examine \`llm_calls[].prompt\` for oversized prompts
+- **Common cause**: Large documents passed as context, excessive search results
+
+### HITL timeout
+- **Symptom**: Action status is PAUSED indefinitely
+- **Check**: \`action_detail\` → look at \`hitl_rounds\` for pending requests
+- **Common cause**: Approval request sent but never responded to
+
+### Missing inputs
+- **Symptom**: Action ERRORED with empty inputs
+- **Check**: \`action_detail\` → examine \`inputs\` array
+- **Common cause**: Upstream action didn't produce expected output, wiring issue
+
+### Wrong response
+- **Symptom**: Bot gives incorrect/irrelevant answer
+- **Check**: Trace the full chain: search inputs → search results → LLM prompt → LLM response
+- **Use**: \`action_detail\` on each action in sequence to find where data goes wrong
+
+## Also Available As Persona Sub-Resource
+
+\`\`\`
+persona(id="abc", debug={method:"conversations"})
+persona(id="abc", debug={method:"show_work", workflow_run_id:"..."})
+persona(id="abc", debug={method:"action_detail", workflow_run_id:"...", action_name:"..."})
+\`\`\`
+`;
+        },
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic fetching helpers (Ema API as source of truth when available)
+// ─────────────────────────────────────────────────────────────────────────────
+function loadAnyConfig() {
+    return (loadConfigFromJsonEnv() ??
+        loadConfigOptional(process.env.EMA_AGENT_SYNC_CONFIG ?? "./config.yaml"));
+}
+function getDefaultEnvNameFromConfig(cfg) {
+    const fromEnv = process.env.EMA_ENV_NAME?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const master = getMasterEnv(cfg);
+    return master?.name ?? cfg.environments[0]?.name ?? "demo";
+}
+const WK_ANY = "WELL_KNOWN_TYPE_ANY";
+function actionDtoToAgentDefinition(a) {
+    // Handle inputs - can be array or object with inputs property
+    const inputsArray = Array.isArray(a.inputs) ? a.inputs : [];
+    const outputsArray = Array.isArray(a.outputs) ? a.outputs : [];
+    return {
+        actionName: a.name ?? a.id,
+        displayName: a.name ?? a.id,
+        category: (a.category ?? "other"),
+        description: a.description ?? "",
+        inputs: inputsArray.map((p) => ({
+            name: p.name ?? "input",
+            type: WK_ANY,
+            required: Boolean(p.required),
+            description: p.description ?? "",
+        })),
+        outputs: outputsArray.map((p) => ({
+            name: p.name ?? "output",
+            type: WK_ANY,
+            description: p.description ?? "",
+        })),
+        whenToUse: "",
+    };
+}
+const clientCache = new Map();
+const agentCatalogCache = new Map();
+function getClientForEnvName(envName) {
+    const cfg = loadAnyConfig();
+    if (!cfg)
+        return null;
+    const effectiveEnv = envName ?? getDefaultEnvNameFromConfig(cfg);
+    const cached = clientCache.get(effectiveEnv);
+    if (cached)
+        return cached;
+    const envCfg = getEnvByName(cfg, effectiveEnv) ?? getEnvByName(cfg, getDefaultEnvNameFromConfig(cfg));
+    if (!envCfg)
+        return null;
+    const env = {
+        name: envCfg.name,
+        baseUrl: envCfg.baseUrl,
+        bearerToken: resolveBearerToken(envCfg.bearerTokenEnv),
+    };
+    const client = new EmaClientAdapter(env);
+    clientCache.set(effectiveEnv, client);
+    return client;
+}
+async function getDynamicAgentCatalog(opts) {
+    const cacheKey = opts.env ?? "";
+    const now = Date.now();
+    const cached = agentCatalogCache.get(cacheKey);
+    if (cached && now - cached.ts < 60_000)
+        return cached.agents;
+    const client = getClientForEnvName(opts.env);
+    if (!client)
+        return AGENT_CATALOG;
+    try {
+        const actions = await client.listActions();
+        const agents = actions
+            .filter((a) => typeof a.name === "string" && a.name.trim().length > 0)
+            .map(actionDtoToAgentDefinition);
+        agentCatalogCache.set(cacheKey, { ts: now, agents });
+        return agents.length > 0 ? agents : AGENT_CATALOG;
+    }
+    catch {
+        return AGENT_CATALOG;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic Persona Templates (API-first)
+// ─────────────────────────────────────────────────────────────────────────────
+const templateCatalogCache = new Map();
+/**
+ * Fetch persona templates from API with caching.
+ * Falls back to empty array if API unavailable (file-backed templates still available via RESOURCE_MAP).
+ */
+async function getDynamicPersonaTemplates(opts) {
+    const cacheKey = opts.env ?? "";
+    const now = Date.now();
+    const cached = templateCatalogCache.get(cacheKey);
+    if (cached && now - cached.ts < 60_000)
+        return cached.templates;
+    const client = getClientForEnvName(opts.env);
+    if (!client)
+        return [];
+    try {
+        const templates = await client.getPersonaTemplates();
+        templateCatalogCache.set(cacheKey, { ts: now, templates });
+        return templates;
+    }
+    catch {
+        return [];
+    }
+}
+const actionSchemaCache = new Map();
+/**
+ * Get action schema with layered loading:
+ * 1. Try bundled schema (resources/action-schema.json)
+ * 2. Augment with live API data if available
+ */
+async function getDynamicActionSchema(opts) {
+    const cacheKey = opts.env ?? "";
+    const now = Date.now();
+    const cached = actionSchemaCache.get(cacheKey);
+    if (cached && now - cached.ts < 60_000)
+        return cached.data;
+    const registry = new APISchemaRegistry();
+    // Try to load from bundled schema first (code source of truth)
+    const bundlePath = path.resolve(__dirname, "../../resources/action-schema.json");
+    try {
+        registry.loadFromBundle(bundlePath);
+    }
+    catch {
+        // Bundle not available - try API
+        const client = getClientForEnvName(opts.env);
+        if (client) {
+            try {
+                await registry.load(client);
+            }
+            catch {
+                // Neither bundle nor API available
+            }
+        }
+    }
+    const response = {
+        version: registry.metadata.version ?? "unknown",
+        source: registry.metadata.source ?? "bundle",
+        actions: registry.getAllActions(),
+    };
+    actionSchemaCache.set(cacheKey, { ts: now, data: response });
+    return response;
+}
+/**
+ * Get a specific action by name from the schema.
+ */
+async function getActionByName(name, env) {
+    const schema = await getDynamicActionSchema({ env });
+    // Find latest version of action
+    const matching = schema.actions.filter(a => a.name === name);
+    if (matching.length === 0)
+        return null;
+    // Return latest version (sort by version desc)
+    return matching.sort((a, b) => (b.version || "v0").localeCompare(a.version || "v0"))[0];
+}
+/**
+ * Convert PersonaTemplateDTO to a simplified format for MCP resources.
+ */
+function templateDtoToResource(t) {
+    return {
+        id: t.id,
+        name: t.name,
+        description: t.description,
+        category: t.category,
+        trigger_type: t.trigger_type,
+        has_project_template: t.has_project_template,
+        // Documentation fields for diagnosis/recommendations
+        about_template: t.about_template, // Rich description of capabilities
+        how_to_use: t.how_to_use, // Step-by-step usage instructions
+        value_prop: t.value_prop, // Value proposition sections
+        additional_content: t.additional_content, // Extra documentation
+        // Include proto_config for full template details
+        proto_config: t.proto_config,
+        // Include workflow_definition if available
+        workflow_definition: t.workflow_definition,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export { DYNAMIC_RESOURCES, getActionByName };