@ema.co/mcp-toolkit 2026.2.19 → 2026.2.23

package/dist/mcp/resources.js

@@ -21,23 +21,19 @@
  * - Path traversal is blocked
  * - Secret patterns are detected and blocked
  * - Only ema:// URI scheme is supported
+ *
+ * Module structure:
+ * - resources.ts (this file): Registry, types, security, static resources
+ * - resources-dynamic.ts: DYNAMIC_RESOURCES array + fetching helpers
+ * - resources-validation.ts: Validation rules generators
  */
 import * as fs from "fs";
 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 knowledge catalogs for dynamic resources
-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 { EmaClient } from "../sdk/client.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 dynamic resources and helpers
+import { DYNAMIC_RESOURCES, getActionByName } from "./resources-dynamic.js";
+// Re-export from split modules so external imports don't break
+export { DYNAMIC_RESOURCES, getActionByName } from "./resources-dynamic.js";
+export { generateValidationRulesForLLM, generateBestPracticesChecklist } from "./resources-validation.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Security Utilities
 // ─────────────────────────────────────────────────────────────────────────────
@@ -67,2325 +63,75 @@ const SECRET_PATTERNS = [
 const BLOCKED_FILES = [
     ".env",
     ".env.local",
-    ".env.development",
-    ".env.production",
-    ".env.test",
-    "secrets.yaml",
-    "secrets.json",
-    ".npmrc",
-    ".pypirc",
-    "id_rsa",
-    "id_ed25519",
-    "*.pem",
-    "*.key",
-];
-function containsSecrets(content) {
-    return SECRET_PATTERNS.some((pattern) => pattern.test(content));
-}
-function isBlockedFile(filename) {
-    const basename = path.basename(filename);
-    return BLOCKED_FILES.some((blocked) => {
-        if (blocked.startsWith("*")) {
-            return basename.endsWith(blocked.slice(1));
-        }
-        return basename === blocked;
-    });
-}
-function hasPathTraversal(uriPath) {
-    return uriPath.includes("..") || uriPath.includes("//");
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Resource Registry
-// ─────────────────────────────────────────────────────────────────────────────
-// Allowlisted resource mappings: uri -> relative file path
-// Only includes files that ACTUALLY exist in this repo (not symlinked)
-// and are useful for MCP consumers
-const RESOURCE_MAP = {
-    // Core Documentation (public guides)
-    "ema://docs/getting-started": {
-        path: ".context/public/guides/mcp-tools-guide.md",
-        description: "Quick start guide: first steps, key concepts, essential rules, common operations",
-        mimeType: "text/markdown",
-    },
-    "ema://docs/readme": {
-        path: "README.md",
-        description: "Ema Toolkit overview: MCP tools, prompts, resources, CLI usage, SDK API, configuration",
-        mimeType: "text/markdown",
-    },
-    "ema://docs/ema-user-guide": {
-        path: ".context/public/guides/ema-user-guide.md",
-        description: "Ema Platform guide: concepts (AI Employees, Workflows, Agents), glossary, architecture, examples, troubleshooting",
-        mimeType: "text/markdown",
-    },
-    "ema://docs/mcp-tools-guide": {
-        path: ".context/public/guides/mcp-tools-guide.md",
-        description: "MCP tools usage guide: tool categories, best practices, example call sequences, workflow review patterns",
-        mimeType: "text/markdown",
-    },
-    // Templates - REMOVED (file-backed templates removed in favor of API + generated fallbacks)
-    // Use: client.getPersonaTemplates() for live API templates
-    // Use: getTemplateFallback("voice") from sdk/generated/template-fallbacks.ts for offline fallbacks
-    // See: ema://catalog/persona-templates for dynamic API-backed template listing
-    // DEPRECATED: Use ema://docs/usage-guide (dynamic) instead
-    // This static resource is kept for backwards compatibility but now generates from guidance module
-};
-// Legacy alias - redirect to dynamic resource
-const LEGACY_STATIC_REDIRECTS = {
-    "ema://rules/mcp-usage": "ema://docs/usage-guide",
-};
-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.
-
-## 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
+    ".env.development",
+    ".env.production",
+    ".env.test",
+    "secrets.yaml",
+    "secrets.json",
+    ".npmrc",
+    ".pypirc",
+    "id_rsa",
+    "id_ed25519",
+    "*.pem",
+    "*.key",
+];
+function containsSecrets(content) {
+    return SECRET_PATTERNS.some((pattern) => pattern.test(content));
 }
-\`\`\`
-
-### 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
+function isBlockedFile(filename) {
+    const basename = path.basename(filename);
+    return BLOCKED_FILES.some((blocked) => {
+        if (blocked.startsWith("*")) {
+            return basename.endsWith(blocked.slice(1));
+        }
+        return basename === blocked;
+    });
 }
-\`\`\`
-
-### Action Name Format
-\`\`\`json
-{
-  "action": {
-    "name": { "namespaces": ["actions", "emainternal"], "name": "call_llm" },
-    "version": "v2"
-  }
+function hasPathTraversal(uriPath) {
+    return uriPath.includes("..") || uriPath.includes("//");
 }
-\`\`\`
-**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)",
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource Registry
+// ─────────────────────────────────────────────────────────────────────────────
+// Allowlisted resource mappings: uri -> relative file path
+// Only includes files that ACTUALLY exist in this repo (not symlinked)
+// and are useful for MCP consumers
+const RESOURCE_MAP = {
+    // Core Documentation (public guides)
+    "ema://docs/getting-started": {
+        path: ".context/public/guides/mcp-tools-guide.md",
+        description: "Quick start guide: first steps, key concepts, essential rules, common operations",
         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();
-        },
+    "ema://docs/readme": {
+        path: "README.md",
+        description: "Ema Toolkit overview: MCP tools, prompts, resources, CLI usage, SDK API, configuration",
+        mimeType: "text/markdown",
     },
-    {
-        uri: "ema://guidance/cursor-rule",
-        name: "guidance/cursor-rule",
-        description: "Guidance exported as Cursor .mdc rule format - for IDE integration",
+    "ema://docs/ema-user-guide": {
+        path: ".context/public/guides/ema-user-guide.md",
+        description: "Ema Platform guide: concepts (AI Employees, Workflows, Agents), glossary, architecture, examples, troubleshooting",
         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();
-        },
+    "ema://docs/mcp-tools-guide": {
+        path: ".context/public/guides/mcp-tools-guide.md",
+        description: "MCP tools usage guide: tool categories, best practices, example call sequences, workflow review patterns",
+        mimeType: "text/markdown",
     },
-];
-// ─────────────────────────────────────────────────────────────────────────────
-// 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 EmaClient(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;
-    }
-}
+    // Templates - REMOVED (file-backed templates removed in favor of API + generated fallbacks)
+    // Use: client.getPersonaTemplates() for live API templates
+    // Use: getTemplateFallback("voice") from sdk/generated/template-fallbacks.ts for offline fallbacks
+    // See: ema://catalog/persona-templates for dynamic API-backed template listing
+    // DEPRECATED: Use ema://docs/usage-guide (dynamic) instead
+    // This static resource is kept for backwards compatibility but now generates from guidance module
+};
+// Legacy alias - redirect to dynamic resource
+const LEGACY_STATIC_REDIRECTS = {
+    "ema://rules/mcp-usage": "ema://docs/usage-guide",
+};
 // ─────────────────────────────────────────────────────────────────────────────
-// Dynamic Persona Templates (API-first)
+// Workspace Root
 // ─────────────────────────────────────────────────────────────────────────────
-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,
-    };
-}
 // Get workspace root - use centralized path resolution
 // EMA_WORKSPACE_ROOT env var can override for testing
 import { getToolkitRoot } from "../sdk/paths.js";
@@ -2395,6 +141,9 @@ function getWorkspaceRoot() {
     }
     return getToolkitRoot();
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// ResourceRegistry Class
+// ─────────────────────────────────────────────────────────────────────────────
 export class ResourceRegistry {
     workspaceRoot;
     constructor(workspaceRoot) {
@@ -2636,409 +385,8 @@ To read a resource, use the \`resources/read\` endpoint:
     }
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// Validation Rules Generator
+// Helpers
 // ─────────────────────────────────────────────────────────────────────────────
-/**
- * Generate validation rules in LLM-friendly Markdown format.
- * Includes rules from Go validator: required outputs, multiple writers, response/abstain, category hierarchy.
- */
-function generateValidationRulesForLLM() {
-    return `# Workflow Validation Rules
-
-> **Use these rules DURING workflow generation to avoid errors proactively.**
-
-These rules are extracted from the Go validator's static validation logic. Follow them when generating or modifying workflows.
-
-## Rule 1: Required Output on All Paths
-
-**Rule ID**: \`required_output_all_paths\`  
-**Severity**: Critical  
-**Applies To**: Named results, execution paths
-
-### Logic
-
-**Algorithm**: Enumerate all execution paths. For each path, check if all named results are produced.
-
-**Steps**:
-1. Enumerate all paths from trigger to completion
-2. For each path, collect all outputs produced
-3. For each named result, check if it's in path outputs
-4. If missing on any path → error
-
-**Complexity**: O(P * R) where P = paths, R = named results
-
-### Rules
-
-**Constraint**: Every execution path must produce all named results.
-
-**Why**: Named results are contract guarantees. If a path doesn't produce a required output, the contract is violated.
-
-### Examples
-
-**Bad Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing_branch", "search"],
-  "named_result": "response_with_sources",
-  "produces": []  // Missing response
-}
-\`\`\`
-
-**Why Bad**: Path ends without producing required output.
-
-**Good Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing_branch", "search", "respond_for_external_actions"],
-  "named_result": "response",
-  "produces": ["response"]  // ✅ Produced
-}
-\`\`\`
-
-**Why Good**: All paths produce required output.
-
-### Remediation
-
-**How to Fix**:
-1. Identify the path missing the output
-2. Add a node that produces the required output
-3. Connect the node's output to WORKFLOW_OUTPUT
-
-**Common Fixes**:
-- Add \`respond_for_external_actions\` node after search
-- Add \`call_llm\` node for text generation
-- Add \`fixed_response\` for static responses
-
-**Prevention** (During Generation):
-- Always ensure every categorizer branch has a response node
-- Check that all paths end with nodes connected to WORKFLOW_OUTPUT
-- Verify resultMappings include all required outputs
-
----
-
-## Rule 2: Single Writer Per Output
-
-**Rule ID**: \`single_writer_per_output\`  
-**Severity**: Critical  
-**Applies To**: Named results, execution paths
-
-### Logic
-
-**Algorithm**: For each named result, count how many nodes produce it on each path.
-
-**Steps**:
-1. For each named result
-2. For each execution path
-3. Count nodes that produce this result
-4. If count > 1 on any path → error
-
-### Rules
-
-**Constraint**: A single named result can only have one producer per execution path.
-
-**Why**: Multiple producers on the same path cause ambiguity about which value to use.
-
-### Examples
-
-**Bad Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing"],
-  "named_result": "response_with_sources",
-  "producers": ["respond_billing", "respond_general"]  // ❌ Two producers
-}
-\`\`\`
-
-**Why Bad**: Two nodes produce the same output on the same path.
-
-**Good Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing"],
-  "named_result": "response_with_sources",
-  "producers": ["respond_billing"]  // ✅ Single producer
-}
-\`\`\`
-
-**Why Good**: Only one node produces the output.
-
-### Remediation
-
-**How to Fix**:
-1. Identify which nodes produce the same output
-2. Remove one producer or use different named results
-3. Ensure only one node produces each named result per path
-
-**Prevention** (During Generation):
-- Use mutually exclusive runIf conditions to gate responders
-- Ensure only one response node executes per category branch
-
----
-
-## Rule 3: Response or Abstain Required
-
-**Rule ID**: \`response_or_abstain_required\`  
-**Severity**: Critical  
-**Applies To**: Execution paths
-
-### Logic
-
-**Algorithm**: For each execution path, check if it produces a response or has an abstain reason.
-
-**Steps**:
-1. For each completed path
-2. Check if path produces any response output
-3. Check if path has abstain reason
-4. If neither → error
-
-### Rules
-
-**Constraint**: Every execution path must either produce a user-visible response or explicitly abstain with a reason.
-
-**Why**: Users expect responses. Paths that don't respond and don't explain why create poor UX.
-
-### Examples
-
-**Bad Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing", "search"],
-  "has_response": false,
-  "has_abstain": false  // ❌ Neither
-}
-\`\`\`
-
-**Why Bad**: Path ends without response or abstain reason.
-
-**Good Pattern**:
-\`\`\`json
-{
-  "path": ["trigger", "categorizer", "billing", "search", "respond_for_external_actions"],
-  "has_response": true  // ✅ Has response
-}
-\`\`\`
-
-**Why Good**: Path produces a response.
-
-### Remediation
-
-**How to Fix**:
-1. Add a response node to the path, OR
-2. Add an abstain reason to the workflow configuration
-
-**Prevention** (During Generation):
-- Always add response nodes to every categorizer branch
-- If a path shouldn't respond, document why with abstain reason
-
----
-
-## Rule 4: Category Hierarchy Valid
-
-**Rule ID**: \`category_hierarchy_valid\`  
-**Severity**: Critical  
-**Applies To**: Categorizers
-
-### Logic
-
-**Algorithm**: Validate categorizer structure and category definitions.
-
-**Steps**:
-1. Check categorizer has Fallback category
-2. Check category hierarchy rules (TBD - need Go validator analysis)
-3. Validate category → handler mapping
-
-### Rules
-
-**Constraint**: Categorizers must have proper structure and hierarchy.
-
-**Why**: Invalid category structure causes routing failures.
-
-### Examples
-
-**Bad Pattern**:
-\`\`\`json
-{
-  "categorizer": {
-    "categories": ["Billing", "Technical"]  // ❌ No Fallback
-  }
-}
-\`\`\`
-
-**Why Bad**: Missing Fallback category means unrecognized intents have no handler.
-
-**Good Pattern**:
-\`\`\`json
-{
-  "categorizer": {
-    "categories": ["Billing", "Technical", "Fallback"]  // ✅ Has Fallback
-  }
-}
-\`\`\`
-
-**Why Good**: All intents have a handler.
-
-### Remediation
-
-**How to Fix**:
-1. Add Fallback category to categorizer
-2. Ensure each category has a handler node
-3. Validate category hierarchy (TBD)
-
-**Prevention** (During Generation):
-- Always include Fallback category
-- Ensure every category has at least one handler node
-
----
-
-## Self-Check Checklist
-
-After generating or modifying a workflow, verify:
-
-- [ ] All paths produce all named results
-- [ ] No multiple writers on same path
-- [ ] Every path has response or abstain
-- [ ] Category hierarchy is valid
-- [ ] Categorizer has Fallback category
-- [ ] All categories have handler nodes
-
----
-
-## Reference
-
-- **Source**: workflow-engine/pkg/engine/validator.go
-- **Error Types**: RESULT_ERROR_TYPE_REQUIRED_OUTPUT_NOT_PRODUCED, RESULT_ERROR_TYPE_MULTIPLE_WRITERS, RESULT_ERROR_TYPE_MISSING_RESPONSE_OR_ABSTAIN_REASON, RESULT_ERROR_TYPE_CATEGORY_HIERARCHY_VIOLATION
-- **Validation Tool**: Use \`workflow(mode="validate")\` to validate workflows
-`;
-}
-/**
- * Generate best practices checklist from SDK rules.
- * SINGLE SOURCE OF TRUTH - all best practices come from:
- * - ANTI_PATTERNS (validation-rules.ts)
- * - STRUCTURAL_INVARIANTS (structural-rules.ts)
- * - INPUT_SOURCE_RULES (validation-rules.ts)
- * - OPTIMIZATION_RULES (validation-rules.ts)
- */
-function generateBestPracticesChecklist() {
-    // Group anti-patterns by severity
-    const criticalAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "critical");
-    const warningAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "warning");
-    const infoAntiPatterns = ANTI_PATTERNS.filter(ap => ap.severity === "info");
-    // Group structural invariants by severity
-    const criticalInvariants = STRUCTURAL_INVARIANTS.filter(inv => inv.severity === "critical");
-    const warningInvariants = STRUCTURAL_INVARIANTS.filter(inv => inv.severity === "warning");
-    return `# Workflow Best Practices Checklist
-
-> **Auto-generated from SDK rules** - This is the single source of truth.
-> Check this BEFORE deploying any workflow.
-
-## 🛑 CRITICAL (Must Fix Before Deploy)
-
-### Anti-Patterns to Avoid
-
-${criticalAntiPatterns.map(ap => `
-#### ${ap.name}
-
-**Pattern**: ${ap.pattern}
-
-**Problem**: ${ap.problem}
-
-**Solution**: ${ap.solution}
-
-**Detection**: \`${ap.detection.condition}\`
-`).join("\n---\n")}
-
-### Structural Requirements
-
-${criticalInvariants.map(inv => `
-- **${inv.name}**: ${inv.rule}
-  - Violation: ${inv.violation}
-  - Fix: ${inv.fix}
-`).join("")}
-
----
-
-## ⚠️ WARNINGS (Should Fix)
-
-### Anti-Patterns
-
-${warningAntiPatterns.map(ap => `
-- **${ap.name}**: ${ap.problem}
-  - Solution: ${ap.solution}
-`).join("")}
-
-### Structural Warnings
-
-${warningInvariants.map(inv => `
-- **${inv.name}**: ${inv.rule}
-  - Fix: ${inv.fix}
-`).join("")}
-
----
-
-## 📋 SUGGESTIONS (Good to Have)
-
-${infoAntiPatterns.map(ap => `
-- **${ap.name}**: ${ap.problem}
-  - Recommendation: ${ap.solution}
-`).join("")}
-
----
-
-## Input Source Rules
-
-| Action | Recommended Input | Avoid | Why |
-|--------|-------------------|-------|-----|
-${INPUT_SOURCE_RULES.filter(r => r.severity === "critical").map(r => `| \`${r.actionPattern}\` | \`${r.recommended}\` | ${r.avoid.join(", ") || "-"} | ${r.reason.slice(0, 60)}... |`).join("\n")}
-
----
-
-## Performance Optimizations
-
-${OPTIMIZATION_RULES.map(opt => `
-### ${opt.name} (${opt.priority})
-
-- **Current State**: ${opt.currentState}
-- **Recommendation**: ${opt.recommendation}
-- **Benefit**: ${opt.benefit}
-`).join("")}
-
----
-
-## Quick Checklist
-
-Before deploying, verify:
-
-### Critical
-- [ ] Response nodes receive \`chat_conversation\` (prevents repeated questions)
-- [ ] Email recipients from \`entity_extraction\` (not text outputs)
-- [ ] Categorizers have Fallback category
-- [ ] HITL has both success AND failure paths
-- [ ] All paths reach WORKFLOW_OUTPUT
-- [ ] No circular dependencies
-
-### Recommended
-- [ ] \`max_tokens\` set on call_llm nodes
-- [ ] No orphan nodes (unused/disconnected)
-- [ ] No redundant search nodes
-- [ ] Search nodes have data sources uploaded
-
----
-
-## Related Resources
-
-- \`ema://rules/anti-patterns\` - Full anti-pattern definitions (JSON)
-- \`ema://rules/input-sources\` - Input source rules (JSON)
-- \`ema://rules/extraction-column-format\` - extraction_columns API shape (entity_extraction nodes)
-- \`ema://rules/json-output-patterns\` - custom_agent + json_mapper pattern
-- \`ema://rules/chat-response-wiring\` - Chat response node wiring (avoid duplicate responses)
-- \`ema://rules/email-input-wiring\` - Email input wiring (json_mapper/fixed_response patterns)
-- \`ema://docs/workflow-node-reference\` - Per-node I/O types, categorizer patterns, LLM config
-- \`ema://rules/structural-invariants\` - Structural rules (JSON)
-- \`ema://rules/optimizations\` - Optimization rules (JSON)
-- \`ema://validation/rules\` - Go validator rules reference
-`;
-}
-// Helper to check if result is an error
 export function isResourceError(result) {
     return "code" in result;
 }