@ema.co/mcp-toolkit 2026.3.24 → 2026.3.25-2

package/dist/mcp/guidance/middleware.js

@@ -0,0 +1,193 @@
+/**
+ * Dynamic Contextual Guidance Middleware
+ *
+ * Post-processes every MCP tool response to inject error-aware guidance.
+ *
+ * Resolution order:
+ *   1. Live DE search (errors only — semantic match on error context)
+ *   2. DE cache (shape-based key match + wildcards)
+ *   3. Universal defaults (always available)
+ *
+ * Handler-set hints are never overwritten.
+ *
+ * Template variables in guidance strings are resolved from the result context:
+ *   {tool}, {method}, {count}, {unfiltered_count}, {persona_id}, {env}, {profile}, {error}
+ */
+import { classifyResult } from "./classify.js";
+import { getDefaultGuidance } from "./defaults.js";
+/** Shapes that trigger a live DE search for contextual error guidance. */
+const ERROR_SHAPES = new Set([
+    "error", "error_400", "error_500", "error_validation", "deploy_failed",
+]);
+/**
+ * Enrich an MCP tool response with contextual guidance.
+ *
+ * Call this after the handler returns, before other hint injection layers.
+ * Only injects fields the handler didn't already set.
+ *
+ * For error responses, queries DE live with the error context to find
+ * relevant solutions — including agent-published fixes for similar errors.
+ */
+export async function enrichWithGuidance(result, ctx, cache, searchFn) {
+    const shape = classifyResult(result, ctx.unfilteredCount ?? result._unfiltered_count);
+    const method = ctx.method ?? "default";
+    // 1. Live DE search for errors — contextual, semantic match
+    let liveHints;
+    if (ERROR_SHAPES.has(shape) && searchFn) {
+        liveHints = await searchDeForGuidance(ctx, shape, searchFn);
+    }
+    // 2. DE cache — exact + wildcard key match
+    const cacheAtom = cache?.getContextualGuidance(ctx.tool, method, shape);
+    const cacheHints = cacheAtom?.hints;
+    // 3. Universal defaults (always available)
+    const defaultHints = getDefaultGuidance(shape, ctx);
+    // Merge: live DE > cache > defaults. Handler wins over all.
+    const merged = mergeHints(defaultHints, mergeHints(cacheHints ?? {}, liveHints));
+    // Resolve template variables
+    const resolved = resolveTemplates(merged, ctx);
+    // Inject — never overwrite what the handler already set
+    for (const [field, value] of Object.entries(resolved)) {
+        if (value != null && !(field in result)) {
+            result[field] = value;
+        }
+    }
+    // Clean up internal fields
+    delete result._unfiltered_count;
+    delete result._result_shape;
+}
+/**
+ * Build a contextual search query from the error and request, then
+ * search DE for relevant guidance (including agent-published solutions).
+ */
+async function searchDeForGuidance(ctx, shape, searchFn) {
+    // Build a query that aligns with how guidance atoms are written:
+    // tool + method + key error terms + shape
+    const error = String(ctx.result.error ?? "");
+    const errorTerms = extractErrorTerms(error);
+    const query = [
+        ctx.tool,
+        ctx.method ?? "",
+        shape,
+        errorTerms,
+    ].filter(Boolean).join(" ");
+    try {
+        const results = await searchFn(query, { limit: 3 });
+        if (!results.length)
+            return undefined;
+        return extractHintsFromSearchResults(results);
+    }
+    catch {
+        // Live search must never break tool dispatch
+        return undefined;
+    }
+}
+/**
+ * Extract actionable terms from an error message for DE search.
+ * Strips noise (HTTP codes, generic text) and keeps specific identifiers.
+ */
+function extractErrorTerms(error) {
+    // Extract field names, action names, input names from error messages
+    // e.g., "Missing inputs: patient_scheduling_agent.named_inputs[Current_Request]"
+    //   → "named_inputs Current_Request"
+    // e.g., "invalid_inputs action_name: scheduling_prompt_builder input_name: named_inputs_User_Query"
+    //   → "invalid_inputs scheduling_prompt_builder named_inputs_User_Query"
+    const terms = [];
+    // Extract named identifiers: action_name: "X", input_name: "Y"
+    const namedMatches = error.matchAll(/(?:action_name|input_name|output_name):\s*"?(\w+)"?/g);
+    for (const m of namedMatches)
+        terms.push(m[1]);
+    // Extract bracket references: named_inputs[X]
+    const bracketMatches = error.matchAll(/(\w+)\[(\w+)\]/g);
+    for (const m of bracketMatches) {
+        terms.push(m[1]); // e.g., "named_inputs"
+        terms.push(m[2]); // e.g., "Current_Request"
+    }
+    // Extract key error keywords
+    const keywords = [
+        "named_inputs", "extraction_columns", "typeArguments", "namedResults",
+        "workflowName", "namespaces", "type_mismatch", "invalid_inputs",
+        "missing_inputs", "deprecated", "circular",
+    ];
+    for (const kw of keywords) {
+        if (error.toLowerCase().includes(kw.toLowerCase())) {
+            terms.push(kw);
+        }
+    }
+    // Deduplicate
+    return [...new Set(terms)].join(" ");
+}
+/**
+ * Extract guidance hints from DE search results.
+ * Looks for structData fields matching hint field names,
+ * or falls back to using content as _tip.
+ */
+function extractHintsFromSearchResults(results) {
+    const hints = {};
+    for (const r of results) {
+        const sd = r.structData ?? {};
+        // Try typed_json first (structured guidance atoms)
+        const typedJson = sd.typed_json;
+        if (typedJson) {
+            try {
+                const data = JSON.parse(typedJson);
+                if (data.hints) {
+                    return mergeHints(hints, data.hints);
+                }
+            }
+            catch { /* not a guidance atom */ }
+        }
+        // Fall back: use summary/description as tip, content as debug step
+        if (!hints._tip && (sd.summary || sd.description)) {
+            hints._tip = String(sd.summary ?? sd.description);
+        }
+        if (!hints._next_step && sd.next_step) {
+            hints._next_step = String(sd.next_step);
+        }
+        if (r.content && !hints._debug_steps) {
+            // Truncate long content to a useful snippet
+            const snippet = r.content.slice(0, 500);
+            hints._debug_steps = [snippet];
+        }
+    }
+    return hints;
+}
+/**
+ * Merge two hint objects. `override` fields take precedence over `base`.
+ */
+function mergeHints(base, override) {
+    if (!override)
+        return { ...base };
+    return {
+        _next_step: override._next_step ?? base._next_step,
+        _required_next_steps: override._required_next_steps ?? base._required_next_steps,
+        _warning: override._warning ?? base._warning,
+        _tip: override._tip ?? base._tip,
+        _likely_causes: override._likely_causes ?? base._likely_causes,
+        _debug_steps: override._debug_steps ?? base._debug_steps,
+    };
+}
+/**
+ * Resolve {variable} placeholders in hint strings using result context.
+ */
+function resolveTemplates(hints, ctx) {
+    const vars = {
+        tool: ctx.tool,
+        method: ctx.method ?? "default",
+        count: String(ctx.result.count ?? ""),
+        unfiltered_count: String(ctx.unfilteredCount ?? ctx.result._unfiltered_count ?? ""),
+        persona_id: String(ctx.result.persona_id ?? ctx.args.persona_id ?? ctx.args.id ?? ""),
+        env: ctx.env ?? "",
+        profile: ctx.profile ?? "",
+        error: String(ctx.result.error ?? ""),
+    };
+    const resolve = (s) => s.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
+    const resolveArray = (arr) => arr.map(resolve);
+    return {
+        _next_step: hints._next_step ? resolve(hints._next_step) : undefined,
+        _required_next_steps: hints._required_next_steps ? resolveArray(hints._required_next_steps) : undefined,
+        _warning: hints._warning ? resolve(hints._warning) : undefined,
+        _tip: hints._tip ? resolve(hints._tip) : undefined,
+        _likely_causes: hints._likely_causes ? resolveArray(hints._likely_causes) : undefined,
+        _debug_steps: hints._debug_steps ? resolveArray(hints._debug_steps) : undefined,
+    };
+}

package/dist/mcp/guidance/types.js

@@ -0,0 +1,7 @@
+/**
+ * Dynamic Contextual Guidance — Type Definitions
+ *
+ * Result shapes, guidance atoms, and context types used by the
+ * guidance middleware to inject error-aware hints into every MCP response.
+ */
+export {};

package/dist/mcp/guidance.js

@@ -72,9 +72,10 @@ ${important.map((r) => `- **${r.title}**: ${r.do}`).join("\n")}
 
 ## Workflow Modification Flow
 The LLM generates the full workflow_def. MCP provides data and executes.
-For workflow_def format details, see \`ema://rules/workflow-constraints\` and \`ema://docs/field-constraints\`.
+For workflow_def format details, search \`knowledge("workflow constraints")\` and \`knowledge("field constraints")\`.
 
 ${toolSections}## Resources
+Use \`knowledge("topic")\` to search for any concept. These resources are also available for direct access:
 ${resourceList}
 
 ## Feedback Welcome
@@ -115,13 +116,15 @@ function generateDecisionFlow(tools) {
         const deployWorkflow = opExample("workflow", "Deploy");
         sections.push(`**Creating a new AI Employee?**
 1. \`${listTemplates}\` → browse templates, pick one (template_id is REQUIRED)
-2. \`knowledge("search and respond pattern")\` → learn the correct workflow pattern
+2. \`knowledge("workflow patterns for <your use case>")\` → learn the correct workflow pattern
 3. \`${createPersona}\` → creates persona
-4. \`${getWorkflow}\` → get starter workflow + generation schema + fingerprint
-5. Build a complete workflow_def using the generation schema + knowledge patterns
+4. \`${getWorkflow}\` → get starter workflow + generation schema (FULL input/output specs from API) + fingerprint
+5. Build a complete workflow_def using the generation schema — it shows ALL required inputs per action
 6. Upload data sources if needed — \`persona(id="<new_id>", data={method:"upload", path:"/path/to/doc.pdf"})\`
-7. \`${deployWorkflow}\`
-**A persona without a deployed workflow is useless.** Template starters are incomplete — you MUST build and deploy a real workflow.`);
+7. \`workflow(mode="validate", persona_id="...", workflow_def={...})\` → catch errors BEFORE deploying
+8. \`${deployWorkflow}\`
+**A persona without a deployed workflow is useless.** Template starters are incomplete — you MUST build and deploy a real workflow.
+**If deployment fails:** search \`knowledge("workflow deploy <error keywords>")\` for solutions. Do NOT retry with the same workflow_def.`);
     }
     // Modify workflow
     if (tools.workflow) {
@@ -129,8 +132,9 @@ function generateDecisionFlow(tools) {
         const deploy = opExample("workflow", "Deploy");
         sections.push(`**Modifying an existing AI Employee's workflow?**
 1. \`${get}\` → get current workflow_def + schema + fingerprint
-2. LLM modifies the workflow_def JSON
-3. \`${deploy}\``);
+2. LLM modifies the workflow_def JSON (use the returned workflow_def as format reference)
+3. \`workflow(mode="validate", persona_id="...", workflow_def={...})\` → catch errors before deploying
+4. \`${deploy}\``);
     }
     // Explore
     if (tools.persona) {

package/dist/mcp/handlers/data/index.js

@@ -321,7 +321,7 @@ export async function handleData(args, client, readFile) {
                                     "Fix the following issues:",
                                     ...validationErrors.map(e => `  - ${e.field}: ${e.message}`),
                                     "",
-                                    "See ema://rules/nested-data-format for proper nested data structure.",
+                                    "Search knowledge(\"nested data format\") for proper nested data structure.",
                                 ],
                             };
                         }

package/dist/mcp/handlers/debug/index.js

@@ -10,8 +10,9 @@ export async function handleDebug(args, client) {
     if (!method) {
         return {
             error: "Missing required parameter: method",
-            available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
-            _tip: "Start with debug(method='conversations', persona_id='...') to list audit conversations.",
+            available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "workflow_runs", "search"],
+            _tip: "Start with debug(method='conversations', persona_id='...') for chat/voice personas, " +
+                "or debug(method='workflow_runs', persona_id='...') for dashboard personas.",
         };
     }
     switch (method) {
@@ -23,6 +24,8 @@ export async function handleDebug(args, client) {
             return handleShowWork(args, client);
         case "action_detail":
             return handleActionDetail(args, client);
+        case "workflow_runs":
+            return handleWorkflowRuns(args, client);
         case "search":
             try {
                 return await handleSearch(args, client);
@@ -36,7 +39,7 @@ export async function handleDebug(args, client) {
         default:
             return {
                 error: `Unknown method: ${method}`,
-                available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "search"],
+                available_methods: ["conversations", "conversation_detail", "show_work", "action_detail", "workflow_runs", "search"],
             };
     }
 }
@@ -97,21 +100,36 @@ async function handleConversationDetail(args, client) {
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         const isNotFound = msg.includes("not_found") || msg.includes("NOT_FOUND") || msg.includes("not found");
+        if (isNotFound && personaId) {
+            // Auto-route: treat the ID as a workflow_run_id and try show_work
+            try {
+                const showWorkResponse = await client.getWorkflowLevelDebugLog(conversationId, personaId);
+                const formatted = formatShowWork(showWorkResponse, conversationId, personaId);
+                return {
+                    ...formatted,
+                    _auto_routed: true,
+                    _note: `"${conversationId}" was not a conversation — auto-routed to show_work as workflow_run_id.`,
+                };
+            }
+            catch { /* fall through to the original not-found error */ }
+        }
         if (isNotFound) {
             return {
                 error: `Conversation not found: ${conversationId}`,
-                _tip: "If this ID came from a debug URL or dashboard, it may be a workflow_run_id (not a conversation_id). " +
-                    "Try: debug(method='show_work', persona_id='...', workflow_run_id='" + conversationId + "')",
+                _tip: personaId
+                    ? `Auto-routing to show_work also failed. Verify the ID is correct.`
+                    : "If this ID came from a dashboard, it may be a workflow_run_id. " +
+                        "Try: debug(method='show_work', persona_id='...', workflow_run_id='" + conversationId + "')",
             };
         }
         throw error;
     }
 }
 async function handleShowWork(args, client) {
-    const workflowRunId = args.workflow_run_id;
+    const workflowRunId = (args.workflow_run_id ?? args.conversation_id);
     const personaId = args.persona_id;
     if (!workflowRunId) {
-        return { error: "Missing required parameter: workflow_run_id" };
+        return { error: "Missing required parameter: workflow_run_id (or conversation_id)" };
     }
     if (!personaId) {
         return {
@@ -144,6 +162,61 @@ async function handleActionDetail(args, client) {
     const response = await client.getActionLevelShowWorkLog(actionName, workflowRunId, personaId);
     return formatActionDetail(response, workflowRunId, actionName);
 }
+async function handleWorkflowRuns(args, client) {
+    const personaId = args.persona_id;
+    if (!personaId) {
+        return { error: "Missing required parameter: persona_id" };
+    }
+    const limit = typeof args.limit === "number" ? args.limit : 20;
+    // Get persona to find dashboard ID
+    let persona = null;
+    try {
+        persona = await client.getPersonaById(personaId);
+    }
+    catch {
+        return {
+            error: `Could not fetch persona: ${personaId}`,
+            _tip: "Check that persona_id is valid and you have access.",
+        };
+    }
+    const dashboardId = persona?.workflow_dashboard_id;
+    if (!dashboardId) {
+        return {
+            error: "This persona is not a dashboard persona (no workflow_dashboard_id).",
+            _tip: "For chat/voice personas, use debug(method='conversations', persona_id='...') instead.",
+        };
+    }
+    try {
+        const rowsResponse = await client.getDashboardRows(dashboardId, personaId, { limit });
+        const rows = (rowsResponse?.rows ?? []);
+        const runs = rows.map((row) => {
+            const id = row.id ?? row.row_id ?? "";
+            const status = row.status ?? row.state ?? "unknown";
+            const createdAt = row.created_at ?? row.createdAt ?? "";
+            const workflowRunId = row.workflow_run_id ?? row.workflowRunId ?? id;
+            return { row_id: id, workflow_run_id: workflowRunId, status, created_at: createdAt };
+        });
+        return {
+            persona_id: personaId,
+            dashboard_id: dashboardId,
+            count: runs.length,
+            workflow_runs: runs,
+            _tip: runs.length > 0
+                ? `Found ${runs.length} workflow run(s). Drill into a run: debug(method='show_work', persona_id='${personaId}', workflow_run_id='<id>')`
+                : "No workflow runs found. Upload data or trigger a run first.",
+            _next_step: runs.length > 0
+                ? `debug(method='show_work', persona_id='${personaId}', workflow_run_id='${runs[0].workflow_run_id}')`
+                : undefined,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            error: `Failed to fetch dashboard rows: ${msg}`,
+            _tip: "The dashboard API may require specific permissions. Check your access.",
+        };
+    }
+}
 async function handleSearch(args, client) {
     const personaId = args.persona_id;
     const query = args.query;

package/dist/mcp/handlers/env/index.js

@@ -167,14 +167,14 @@ function handleList(getEnvironments, toolkit) {
             workflow: [
                 "1. List personas: persona(method=\"list\")",
                 "2. Get workflow data: workflow(mode=\"get\", persona_id=\"...\")",
-                "3. Analyze workflow: Fetch ema://rules/anti-patterns and check workflow_def against rules",
+                "3. Analyze workflow: Search knowledge(\"workflow anti-patterns\") and check workflow_def against rules",
                 "4. Deploy workflow: workflow(mode=\"deploy\", persona_id=\"...\", workflow_def={...})",
             ],
             critical_rules: criticalRules,
             resources: [
-                "ema://docs/usage-guide - Complete guide",
-                "ema://catalog/agents-summary - Action catalog",
-                "ema://guidance/rules - Structured rules (JSON)",
+                "knowledge(\"usage guide\") - Complete guide",
+                "knowledge(\"action catalog\") - Available actions",
+                "knowledge(\"workflow rules\") - Structured rules",
             ],
             prompts: [
                 "toolkit_onboard - Comprehensive getting started",

package/dist/mcp/handlers/feedback/coalesce.js

@@ -22,7 +22,10 @@ export function buildDigest(entries, clientId, toolkitVersion, sessionId) {
     for (const entry of entries) {
         switch (entry.kind) {
             case "feedback":
-                feedbackEntries.push(entry.data);
+                // Exclude integration test entries from digests sent to GCS
+                if (entry.data.context !== "integration_test") {
+                    feedbackEntries.push(entry.data);
+                }
                 break;
             case "telemetry":
                 telemetryEntries.push(entry.data);

package/dist/mcp/handlers/feedback/index.js

@@ -81,9 +81,21 @@ async function handleSubmit(args) {
     }
     // Wire up knowledge_ref from top-level param into context/quality_data
     let context = args.context ? truncate(String(args.context), MAX_CONTEXT_LENGTH) : undefined;
-    let qualityData = (category === "quality" || category === "correction") && args.quality_data
-        ? args.quality_data
-        : undefined;
+    let qualityData;
+    if ((category === "quality" || category === "correction") && args.quality_data) {
+        const raw = args.quality_data;
+        if (typeof raw === "string") {
+            try {
+                qualityData = JSON.parse(raw);
+            }
+            catch {
+                qualityData = undefined;
+            }
+        }
+        else if (typeof raw === "object" && raw !== null) {
+            qualityData = raw;
+        }
+    }
     const knowledgeRef = args.knowledge_ref ? String(args.knowledge_ref) : undefined;
     if (knowledgeRef) {
         // Inject into context for universal correlation

package/dist/mcp/handlers/feedback/store.js

@@ -272,8 +272,10 @@ export async function listTelemetry(options, rootOverride) {
  */
 export async function analyzeFeedback(rootOverride) {
     const dir = await ensureFeedbackDir(rootOverride);
-    const feedback = await readJsonl(join(dir, FEEDBACK_FILE));
+    const allFeedback = await readJsonl(join(dir, FEEDBACK_FILE));
     const telemetry = await readJsonl(join(dir, TELEMETRY_FILE));
+    // Exclude integration test entries from analysis
+    const feedback = allFeedback.filter((e) => e.context !== "integration_test");
     // Category breakdown
     const categoryBreakdown = {};
     for (const entry of feedback) {
@@ -319,7 +321,7 @@ export async function analyzeFeedback(rootOverride) {
     }
     // High-severity items
     const highSeverity = feedback.filter((e) => e.severity === "high");
-    // Actionable items
+    // Actionable items — deduplicated by (category, message_prefix, tool)
     const actionableItems = [];
     // Tools with high error rates
     for (const [tool, usage] of Object.entries(toolUsage)) {
@@ -328,16 +330,34 @@ export async function analyzeFeedback(rootOverride) {
             actionableItems.push(`Tool "${tool}" has ${Math.round(errorRate * 100)}% error rate (${usage.errors}/${usage.total}) - investigate error handling and documentation`);
         }
     }
-    // Gaps are high-priority feedback
-    const gaps = feedback.filter((e) => e.category === "gap");
-    for (const gap of gaps) {
-        actionableItems.push(`Documentation gap: ${gap.message}${gap.tool ? ` (tool: ${gap.tool})` : ""}`);
-    }
-    // Confusion items suggest unclear docs
-    const confusions = feedback.filter((e) => e.category === "confusion");
-    for (const confusion of confusions) {
-        actionableItems.push(`Unclear guidance: ${confusion.message}${confusion.tool ? ` (tool: ${confusion.tool})` : ""}`);
-    }
+    // Gaps and confusions — deduplicate by (message_prefix, tool) to avoid flooding
+    const isTestFeedback = (e) => {
+        const ref = e.quality_data?.knowledge_ref ?? "";
+        const ctx = e.context ?? "";
+        return ref.startsWith("test:") || ctx.includes("knowledge_ref:test:");
+    };
+    const deduplicateEntries = (entries, label) => {
+        const seen = new Map();
+        for (const e of entries) {
+            if (isTestFeedback(e))
+                continue;
+            const prefix = e.message.length > 120 ? e.message.slice(0, 120) : e.message;
+            const key = `${prefix}|${e.tool ?? ""}`;
+            const existing = seen.get(key);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                seen.set(key, { message: e.message, tool: e.tool, count: 1 });
+            }
+        }
+        for (const { message, tool, count } of seen.values()) {
+            const suffix = count > 1 ? ` (x${count})` : "";
+            actionableItems.push(`${label}: ${message}${tool ? ` (tool: ${tool})` : ""}${suffix}`);
+        }
+    };
+    deduplicateEntries(feedback.filter((e) => e.category === "gap"), "Documentation gap");
+    deduplicateEntries(feedback.filter((e) => e.category === "confusion"), "Unclear guidance");
     // Graph-correlated insights: group feedback by knowledge_ref
     const graphCorrelations = {};
     for (const entry of feedback) {

package/dist/mcp/handlers/template/crud.js

@@ -4,6 +4,7 @@
  * Routes template CRUD methods to the appropriate SDK calls.
  * Follows the handler pattern from debug/index.ts.
  */
+import { normalizeTriggerType } from "../utils.js";
 const METHODS = ["list", "get", "create", "update", "delete"];
 /**
  * Map friendly type names to PersonaTriggerTypeEnum values.
@@ -72,21 +73,18 @@ async function handleList(args, client) {
     }
     const type = args.type;
     if (type) {
-        // Map friendly type names to trigger_type values
-        const typeMap = {
-            voice: "VOICEBOT_AI_EMPLOYEE",
-            chat: "CHATBOT",
-            dashboard: "DOCUMENT_TRIGGER",
-        };
-        const triggerType = typeMap[type.toLowerCase()] ?? type;
-        filtered = filtered.filter((t) => t.trigger_type === triggerType);
+        const target = type.toLowerCase();
+        filtered = filtered.filter((t) => {
+            const normalized = normalizeTriggerType(t.trigger_type);
+            return normalized === target;
+        });
     }
     const category = args.category;
     if (category) {
         const c = category.toLowerCase();
         filtered = filtered.filter((t) => t.category?.toLowerCase() === c);
     }
-    return {
+    const result = {
         count: filtered.length,
         templates: filtered.map((t) => ({
             id: t.id,
@@ -94,9 +92,28 @@ async function handleList(args, client) {
             description: t.description,
             category: t.category,
             trigger_type: t.trigger_type,
+            type: normalizeTriggerType(t.trigger_type),
             has_project_template: t.has_project_template,
         })),
     };
+    // Layer 2: always provide guidance — especially on 0 results
+    if (filtered.length === 0 && templates.length > 0) {
+        const availableTypes = [...new Set(templates
+                .map((t) => normalizeTriggerType(t.trigger_type))
+                .filter(Boolean))];
+        result._warning = `${templates.length} templates exist but none match your filters.`;
+        result._tip = `Available types: ${availableTypes.join(", ")}. Try template(method='list') without filters to see all.`;
+        result._next_step = "template(method='list')";
+    }
+    else if (filtered.length === 0 && templates.length === 0) {
+        result._warning = "No templates found in this tenant.";
+        result._tip = "This tenant may not have templates provisioned. Try a different profile or use knowledge('templates') to search DE.";
+        result._next_step = "knowledge('persona templates')";
+    }
+    else {
+        result._next_step = "Get details: template(method='get', id='<id>')";
+    }
+    return result;
 }
 async function handleGet(args, client) {
     const id = args.id;

package/dist/mcp/handlers/workflow/adapter.js

@@ -10,7 +10,7 @@ import { fingerprintPersona } from "../../../sync.js";
 import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 import { handleWorkflow } from "./index.js";
 import { handleWorkflowOptimize } from "./optimize.js";
-export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName) {
+export async function handleWorkflowAdapter(args, createClient, getDefaultEnvName, cache) {
     const normalizedArgs = { ...(args ?? {}) };
     const personaId = normalizedArgs.persona_id ? String(normalizedArgs.persona_id) : undefined;
     let workflowDef = normalizedArgs.workflow_def;
@@ -66,7 +66,7 @@ export async function handleWorkflowAdapter(args, createClient, getDefaultEnvNam
                 mode: "get",
                 persona_id: personaId,
                 env: normalizedArgs.env,
-            }, client, () => undefined);
+            }, client, () => undefined, cache);
         }
         case "validate": {
             return handleWorkflow({

package/dist/mcp/handlers/workflow/deploy.js

@@ -436,26 +436,26 @@ export async function handleWorkflowDeploy(args, client) {
                 errorResult._likely_causes = [
                     "Type mismatch: An input binding has incompatible type (e.g., STRING where TEXT_WITH_SOURCES expected). The API does NOT say which input — you must check each one.",
                     "Missing typeArguments: Categorizer node missing typeArguments.categories pointing to enumType",
-                    "Invalid named_inputs format: Must use multiBinding.elements[].namedBinding structure — see ema://rules/named-inputs-format",
-                    "Wrong extraction_columns format: Must use array.values[{ wellKnown.extractionColumn: { id, name, dataType } }] — see ema://rules/extraction-column-format",
-                    "namedResults type mismatch: The type declared in namedResults (e.g. WELL_KNOWN_TYPE_ANY) must match the producer's actual output type. entity_extraction outputs aggregate 'extraction_columns', NOT individual columns.",
-                    "Empty namespaces: Action names require namespaces: ['actions', 'emainternal']",
+                    "Invalid named_inputs format: Must use multiBinding.elements[].namedBinding structure — search knowledge(\"named inputs format\") for correct structure",
+                    "Wrong extraction_columns format: Must use array.values[{ wellKnown.extractionColumn: { id, name, dataType } }] — search knowledge(\"extraction columns format\")",
+                    "namedResults type mismatch: The type declared in namedResults must match the producer's actual output type. entity_extraction outputs aggregate 'extraction_columns', NOT individual columns.",
+                    "Empty namespaces: Action names and enumTypes require non-empty namespaces: ['actions', 'emainternal']",
                     "Deprecated action: Using a deprecated action version (e.g., text_categorizer/v0)",
-                    `widgetConfig binding error: ${MODEL_CONFIG.inputName} must use ${JSON.stringify(widgetBinding(MODEL_CONFIG))} — see ema://rules/widget-config-format`,
+                    `widgetConfig binding error: ${MODEL_CONFIG.inputName} must use ${JSON.stringify(widgetBinding(MODEL_CONFIG))} — search knowledge('widget config format')`,
                 ];
                 errorResult._debug_steps = [
-                    "1. Compare your workflow_def against a WORKING one: workflow(mode='get', persona_id='<similar_persona>')",
-                    "2. Check EACH input binding type — TEXT_WITH_SOURCES ≠ STRING ≠ JSON_VALUE (the API won't tell you which is wrong)",
-                    "3. Verify named_inputs uses multiBinding format: ema://rules/named-inputs-format",
-                    "4. Verify extraction_columns format: ema://rules/extraction-column-format (includes output wiring)",
-                    "5. Check action namespaces are ['actions', 'emainternal'], not empty []",
-                    "6. Verify categorizer nodes have typeArguments.categories pointing to a valid enumType",
-                    "7. Check namedResults producers: each MUST have BOTH 'actionName' AND 'outputName' — missing actionName causes HTTP 500",
-                    "8. Check namedResults producers use correct outputName ('extraction_columns' for entity_extraction, NOT individual column names)",
-                    "9. Verify action versions are non-deprecated: knowledge(\"id=<action_name>\")",
+                    "1. Search for solutions: knowledge(\"workflow deploy 500 <error_keywords>\") — other agents may have solved this",
+                    "2. Compare your workflow_def against a WORKING one: workflow(mode='get', persona_id='<similar_persona>')",
+                    "3. Check EACH input binding type — TEXT_WITH_SOURCES ≠ STRING ≠ JSON_VALUE (the API won't tell you which is wrong)",
+                    "4. Verify named_inputs format: knowledge(\"named inputs format\") for correct multiBinding structure",
+                    "5. Verify extraction_columns format: knowledge(\"extraction columns format\") for correct structure",
+                    "6. Check action namespaces are ['actions', 'emainternal'], not empty []",
+                    "7. Verify categorizer nodes have typeArguments.categories pointing to a valid enumType",
+                    "8. Check namedResults producers: each MUST have BOTH 'actionName' AND 'outputName' — missing actionName causes HTTP 500",
+                    "9. Verify action versions: knowledge(\"deprecated actions\") to check for deprecated versions",
                 ];
                 errorResult._next_step =
-                    "The API error lacks detail — compare your workflow_def against a working one: workflow(mode='get', persona_id='<same_or_similar_persona>'). Key resources: ema://rules/named-inputs-format, ema://rules/extraction-column-format, ema://rules/widget-config-format, ema://rules/ruleset-format.";
+                    "Search knowledge(\"workflow deploy 500\") for known solutions, then compare your workflow_def against a working one: workflow(mode='get', persona_id='<same_or_similar_persona>').";
             }
         }
         return errorResult;