@ema.co/mcp-toolkit 2026.1.27 → 2026.1.28-2

package/dist/mcp/resources.js

@@ -100,9 +100,9 @@ function hasPathTraversal(uriPath) {
 // Only includes files that ACTUALLY exist in this repo (not symlinked)
 // and are useful for MCP consumers
 const RESOURCE_MAP = {
-    // Core Documentation (files that exist in this repo)
+    // Core Documentation (public guides)
     "ema://docs/getting-started": {
-        path: "docs/mcp-tools-guide.md",
+        path: ".context/public/guides/mcp-tools-guide.md",
         description: "Quick start guide: first steps, key concepts, essential rules, common operations",
         mimeType: "text/markdown",
     },
@@ -112,12 +112,12 @@ const RESOURCE_MAP = {
         mimeType: "text/markdown",
     },
     "ema://docs/ema-user-guide": {
-        path: "docs/ema-user-guide.md",
+        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: "docs/mcp-tools-guide.md",
+        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",
     },
@@ -216,6 +216,13 @@ const DYNAMIC_RESOURCES = [
         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(),
+    },
     // Deprecated Actions - API-first with fallback
     {
         uri: "ema://rules/deprecated-actions",
@@ -1140,6 +1147,281 @@ To read a resource, use the \`resources/read\` endpoint:
         };
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation Rules Generator
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 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_with_sources"],
+  "named_result": "response_with_sources",
+  "produces": ["response_with_sources"]  // ✅ 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_with_sources\` 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_with_sources"],
+  "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
+`;
+}
 // Helper to check if result is an error
 export function isResourceError(result) {
     return "code" in result;

package/dist/mcp/server.js

@@ -4231,6 +4231,19 @@ toolHandlers.workflow = async (args) => {
                 env: normalizedArgs.env,
             }, client, () => undefined);
         }
+        case "validate": {
+            // Static validation with path enumeration
+            return handleWorkflow({
+                mode: "validate",
+                persona_id: personaId,
+                workflow_def: normalizedArgs.workflow_def,
+                workflow_spec: normalizedArgs.workflow_spec,
+                validation_type: normalizedArgs.validation_type,
+                max_paths: normalizedArgs.max_paths,
+                timeout_ms: normalizedArgs.timeout_ms,
+                env: normalizedArgs.env,
+            }, client, () => undefined);
+        }
         case "deploy": {
             if (!personaId) {
                 return { error: 'persona_id is required for workflow(mode="deploy")' };
@@ -4283,14 +4296,14 @@ toolHandlers.workflow = async (args) => {
             return {
                 error: `Mode "${mode}" removed - LLM does this thinking`,
                 hint: "Use workflow(mode='get') to fetch data, then analyze/generate in your reasoning. Deploy with workflow(mode='deploy').",
-                valid_modes: ["get", "deploy"],
+                valid_modes: ["get", "validate", "deploy"],
             };
         }
         default: {
             // No mode or unknown mode - require explicit mode
             return {
-                error: `Mode required. Valid modes: get, deploy`,
-                hint: "workflow(mode='get') returns data for LLM. workflow(mode='deploy') executes LLM's workflow_def.",
+                error: `Mode required. Valid modes: get, validate, deploy`,
+                hint: "workflow(mode='get') returns data for LLM. workflow(mode='validate') validates specs. workflow(mode='deploy') executes LLM's workflow_def.",
                 example: `workflow(mode="get", persona_id="...")`,
             };
         }

package/dist/mcp/tools.js

@@ -12,10 +12,8 @@
  * - ALL operations require explicit `method` or `mode` parameter
  * - LLM interprets intent and chooses operation, MCP executes
  * - No inference from parameter presence
- * - Tool descriptions are AUTO-GENERATED from workflow-operations.ts
  */
 import { TOOL_GUIDANCE } from "../sdk/guidance.js";
-import { generateInputDescription, SUPPORTED_OPERATIONS, LIMITATIONS } from "./workflow-operations.js";
 /**
  * Generate the v2 tool set
  */
@@ -45,12 +43,11 @@ export function generateTools(envNames, defaultEnv) {
 
 ## Update
 - \`persona(method="update", id="abc", config={...})\` - update config
-- \`persona(method="update", id="abc", input="...")\` - INCREMENTAL workflow changes:
-${SUPPORTED_OPERATIONS.map(op => `  - "${op.example}" (${op.name})`).join("\n")}
+- \`persona(method="update", id="abc", input="...")\` - INCREMENTAL workflow changes (returns context for Agent to build operations)
+- \`persona(method="update", id="abc", operations=[...])\` - structured operations (Agent-built)
 - \`persona(method="update", id="abc", workflow_spec={...})\` - rewire/remove only (cannot add nodes)
 
-**NOT supported via input** (clone from existing persona instead):
-${LIMITATIONS.map(l => `- ${l}`).join("\n")}
+**For complex workflows**: Use \`workflow(mode="generate", input="...")\` or structured \`operations\` array.
 
 ## Delete
 - \`persona(method="delete", id="abc", confirm=true)\` - delete persona
@@ -174,7 +171,7 @@ persona(
                     },
                     input: {
                         type: "string",
-                        description: generateInputDescription(),
+                        description: "Incremental workflow changes. Returns workflow context for Agent to build structured operations. For complex multi-node workflows, use workflow(mode='generate') or structured operations array.",
                     },
                     // === Update params (for method=update) ===
                     config: {
@@ -383,20 +380,27 @@ persona(
 - \`workflow(mode="get", persona_id="abc")\` - returns workflow_def, schema, patterns, widgets
 - LLM analyzes, compares, and generates workflows using this data
 
+## Validate (static validation with path enumeration)
+- \`workflow(mode="validate", persona_id="abc")\` - validate existing workflow
+- \`workflow(mode="validate", workflow_spec={...})\` - validate workflow spec directly
+- Returns enhanced errors: what is wrong, why, how to fix
+- Validates: required outputs on all paths, multiple writers, response/abstain, category hierarchy
+
 ## Deploy (execute LLM's result)
 - \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` - deploy LLM-generated workflow
 
 **Workflow for creation:**
 1. \`workflow(mode="get", persona_id="abc")\` → get schema, patterns, current workflow
 2. LLM generates workflow_def (LLM does the work)
-3. \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` → MCP deploys`,
+3. \`workflow(mode="validate", workflow_spec={...})\` → validate before deploying (optional but recommended)
+4. \`workflow(mode="deploy", persona_id="abc", workflow_def={...})\` → MCP deploys`,
             inputSchema: {
                 type: "object",
                 properties: {
                     mode: {
                         type: "string",
-                        enum: ["get", "deploy"],
-                        description: "get = return data for LLM, deploy = execute LLM's workflow_def",
+                        enum: ["get", "deploy", "validate"],
+                        description: "get = return data for LLM, validate = static validation with path enumeration, deploy = execute LLM's workflow_def",
                     },
                     persona_id: {
                         type: "string",
@@ -406,12 +410,29 @@ persona(
                         type: "object",
                         description: "workflow_def JSON (for mode=deploy) - LLM generates this",
                     },
+                    workflow_spec: {
+                        type: "object",
+                        description: "workflow_spec (for mode=validate) - workflow in spec format",
+                    },
+                    validation_type: {
+                        type: "string",
+                        enum: ["static", "paths", "named_results", "all"],
+                        description: "Validation type (for mode=validate). Default: 'all'",
+                    },
+                    max_paths: {
+                        type: "number",
+                        description: "Maximum paths to enumerate (for mode=validate). Default: 1000",
+                    },
+                    timeout_ms: {
+                        type: "number",
+                        description: "Timeout in milliseconds (for mode=validate). Default: 100",
+                    },
                     env: {
                         type: "string",
                         description: envDescription,
                     },
                 },
-                required: ["mode", "persona_id"],
+                required: ["mode"],
             },
         },
         // ═══════════════════════════════════════════════════════════════════════════

package/dist/sdk/client.js

@@ -17,7 +17,7 @@
  * const client = new EmaClientV2(env);
  * ```
  *
- * See .ctx/docs/lessons-learned.md for migration guidance.
+ * See .context/core/guides/lessons-learned.md for migration guidance.
  */
 import { GrpcClient } from "./grpc-client.js";
 import { toJson } from "@bufbuild/protobuf";
@@ -793,8 +793,10 @@ export class EmaClient {
      * Get data source aggregates (file counts by status).
      *
      * Uses typed gRPC client for proto-based calls.
+     * Falls back to counting files from listDataSourceFiles if aggregates API returns zeros.
      */
     async getDataSourceAggregates(personaId, widgetName = "fileUpload") {
+        // Try aggregates API first
         try {
             const response = await this.grpcClient.getContentNodeAggregates(personaId, widgetName);
             // Find the aggregate for the requested widget
@@ -803,16 +805,41 @@ export class EmaClient {
             const pending = counts?.pending ?? 0;
             const success = counts?.success ?? 0;
             const failed = counts?.failed ?? 0;
-            return {
-                total: pending + success + failed,
-                pending,
-                success,
-                failed,
-                widgetName,
-            };
+            const total = pending + success + failed;
+            // If we got data, return it
+            if (total > 0) {
+                return { total, pending, success, failed, widgetName };
+            }
+        }
+        catch {
+            // Aggregates API failed, fall through to fallback
+        }
+        // FALLBACK: Count files directly from listDataSourceFiles
+        // This handles cases where aggregates API returns zeros but files exist
+        try {
+            const result = await this.listDataSourceFiles(personaId, { widgetName });
+            const files = result.files;
+            if (files.length > 0) {
+                let pending = 0;
+                let success = 0;
+                let failed = 0;
+                for (const file of files) {
+                    const status = (file.status ?? "").toLowerCase();
+                    if (status === "success" || status === "completed" || status === "indexed") {
+                        success++;
+                    }
+                    else if (status === "failed" || status === "error") {
+                        failed++;
+                    }
+                    else {
+                        pending++; // pending, processing, or unknown
+                    }
+                }
+                return { total: files.length, pending, success, failed, widgetName };
+            }
         }
         catch {
-            // Fall through to return empty
+            // Fallback also failed
         }
         return { total: 0, pending: 0, success: 0, failed: 0, widgetName };
     }

package/dist/sdk/ema-client.js

@@ -98,11 +98,39 @@ export class EmaClientV2 {
     // ─────────────────────────────────────────────────────────────────────────────
     /**
      * List all personas for the current tenant
+     *
+     * Automatically fetches all pages to return complete list.
+     * The API supports pagination via query params (page_num, page_size).
+     *
+     * @param opts.pageSize - Items per page (default: 1000)
+     * @returns All personas for the tenant
      */
-    async listPersonas() {
-        const result = await api.listPersonas({ client: this.restClient });
-        const response = result.data;
-        return response?.personas ?? [];
+    async listPersonas(opts) {
+        const pageSize = opts?.pageSize ?? 1000;
+        const allPersonas = [];
+        let pageNum = 1;
+        let hasMore = true;
+        while (hasMore) {
+            // Make request with pagination query params
+            // The OpenAPI-generated client doesn't expose these, so we use the underlying client
+            const url = `/api/personas/get_personas_for_tenant?page_num=${pageNum}&page_size=${pageSize}&include_persona_group_details=true`;
+            const response = await this.restClient.get({
+                url,
+                security: [{ scheme: 'bearer', type: 'http' }],
+            });
+            const data = response.data;
+            const personas = data?.personas ?? [];
+            allPersonas.push(...personas);
+            // Check if there are more pages
+            const total = data?.total ?? personas.length;
+            if (allPersonas.length >= total || personas.length < pageSize) {
+                hasMore = false;
+            }
+            else {
+                pageNum++;
+            }
+        }
+        return allPersonas;
     }
     /** Alias for listPersonas */
     async getPersonasForTenant() {

package/dist/sdk/index.js

@@ -40,7 +40,9 @@ buildVoiceConfig, buildChatConfig, } from "./workflow-generator.js";
 // Action Registry (API-driven action/template definitions)
 export { ActionRegistry, ensureActionRegistry, parseActionDefinition, parseTemplateDefinition, } from "./action-registry.js";
 // Workflow Intent (Normalization layer)
-export { parseInput, validateIntent, intentToSpec, detectInputType, parseNaturalLanguage, parsePartialSpec, 
+export { parseInput, validateIntent, intentToSpec, detectInputType, 
+// parseNaturalLanguage removed - violates LLM-driven architecture
+parsePartialSpec, 
 // LLM-driven generation
 needsLLMGeneration, generateWorkflow, parseWorkflowSpecFromLLM, } from "./workflow-intent.js";
 // Workflow Validator (API-driven validation)

package/dist/sdk/knowledge.js

@@ -21,7 +21,7 @@
  * - ema-repos/protos/ - Type definitions
  * - Support cases and real-world usage patterns
  *
- * See: .ctx/docs/source-repos.md for full architecture
+ * See: .context/core/guides/source-repos.md for full architecture
  */
 // ─────────────────────────────────────────────────────────────────────────────
 // Platform Concepts (from Ema User Guide)
@@ -752,7 +752,7 @@ export const AGENT_CATALOG = [
 // - Widget 'name' is assigned per-template (e.g., "upload", "upload1", "upload2")
 // - Proto 'case' values represent TYPE discriminators, not widget names
 // 
-// See .ctx/docs/source-repos.md for full sync instructions
+// See .context/core/guides/source-repos.md for full sync instructions
 // ═══════════════════════════════════════════════════════════════════════════════════
 export const WIDGET_CATALOG = [
     // ═══════════════════════════════════════════════════════════════════════════
@@ -778,7 +778,7 @@ export const WIDGET_CATALOG = [
     // ═══════════════════════════════════════════════════════════════════════════
     // SOURCE: ema-repos/ema/ema_backend/db/system_values/persona_templates/prod/document_proposal_manager.yaml
     // NOTE: Widget names are defined per-template. These are from Document Proposal Manager.
-    //       To sync: see .ctx/docs/source-repos.md
+    //       To sync: see .context/core/guides/source-repos.md
     // LAST VERIFIED: 2026-01-27 from document_proposal_manager.yaml
     { id: 3, name: "upload", description: "Content Repository - gold standard company docs (title: 'Content Repository')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
     { id: 3, name: "upload1", description: "Service Line Documents - business unit specific content (title: 'Service Line Documents')", requiredFor: ["document"], fields: ["tags"], uploadTarget: true },
@@ -814,7 +814,7 @@ export const PROJECT_TYPES = {
 // - INTENT_TYPE_ROUTING (workflow-intent.ts) - routing logic during intent processing
 // - SCHEMA_TYPE_COMPATIBILITY (action-schema-parser.ts) - input name matching for validation
 //
-// See .ctx/docs/source-repos.md for full architecture
+// See .context/core/guides/source-repos.md for full architecture
 // ─────────────────────────────────────────────────────────────────────────────
 export const TYPE_COMPATIBILITY = [
     // Chat conversation compatibility
@@ -1872,7 +1872,7 @@ export { DEPRECATED_ACTIONS_WITH_REPLACEMENT, DEPRECATED_ACTIONS_NO_REPLACEMENT,
  * STATUS: Can be auto-generated from source doc
  * TODO: Add to catalog-sync.yml workflow for automatic updates
  *
- * See .ctx/docs/source-repos.md for sync details
+ * See .context/core/guides/source-repos.md for sync details
  */
 export const WORKFLOW_ENABLING_CONSTRAINTS = [
     {