@ema.co/mcp-toolkit 2026.1.29-9 → 2026.2.5

package/.context/public/guides/mcp-tools-guide.md

@@ -510,9 +510,11 @@ call_llm/v0 → Use call_llm/v2
 
 | Scenario | Default | How to Add HITL |
 |----------|---------|-----------------|
-| Send email | ❌ No HITL | `persona(mode="update", id="...", input="add approval before sending")` |
-| External API | ❌ No HITL | Request explicitly in input |
-| Create records | ❌ No HITL | Request explicitly in input |
+| Send email | ❌ No HITL | Get workflow → add general_hitl node before email → deploy |
+| External API | ❌ No HITL | Get workflow → add general_hitl node → deploy |
+| Create records | ❌ No HITL | Get workflow → add general_hitl node → deploy |
+
+**Pattern:** `workflow(mode="get")` → modify workflow_def → `workflow(mode="deploy")`
 
 ## Auto Builder Prompt Length Limits
 

package/README.md

@@ -223,27 +223,25 @@ persona(input="IT helpdesk with KB search", type="chat", name="IT Support", prev
 
 **Modify existing AI Employee (LLM-Driven):**
 ```typescript
-// Step 1: Get workflow context
-persona(mode="modify", id="abc-123")
-// Returns: current_nodes, available_actions, example_operations
-
-// Step 2: Build and execute structured operations
-persona(mode="modify", id="abc-123", operations=[
-  { type: "insert", insert: { action_type: "hitl", insert_before: "send_email" }},
-  { type: "remove", remove: { nodes: ["unused_node"] }}
-], preview=true)
-```
+// Step 1: Get current workflow
+workflow(mode="get", persona_id="abc-123")
+// Returns: workflow_def, schema, guidance, fingerprint
 
-**Fix issues automatically:**
-```typescript
-persona(id="abc-123", optimize=true, preview=false)
+// Step 2: LLM modifies the workflow_def JSON
+// (add nodes, remove nodes, rewire connections)
+
+// Step 3: Deploy modified workflow
+// IMPORTANT: pass base_fingerprint from the get() response to prevent overwriting out-of-band changes
+workflow(mode="deploy", persona_id="abc-123", base_fingerprint="<fingerprint>", workflow_def={...})
+
+// If the workflow_def is large (near transport limits), deploy from a file instead:
+// workflow(mode="deploy", persona_id="abc-123", base_fingerprint="<fingerprint>", workflow_def_path="/path/to/wf.json")
 ```
 
 **Get reference info:**
 ```typescript
-reference(type="envs")                          // List environments
-reference(type="actions", id="send_email")      // Get action details
-reference(type="patterns", pattern="intent-routing")  // Get pattern
+catalog(type="actions", id="send_email")      // Get action details
+catalog(type="templates")                     // List templates
 ```
 
 ## Dynamic Resources
@@ -276,7 +274,7 @@ The MCP is fully self-contained—no external configuration files needed.
 - Read `ema://docs/usage-guide` (markdown) for documentation
 - Read `ema://guidance/cursor-rule` (.mdc) for IDE integration
 
-All guidance flows from a single source (`src/sdk/guidance.ts`).
+All guidance flows from a single source (`src/mcp/guidance.ts`).
 
 ---
 

package/dist/cli/index.js

@@ -12,7 +12,7 @@
  */
 import { loadConfig } from "../sdk/config.js";
 import { EmaClient } from "../sdk/client.js";
-import { SyncSDK } from "../sdk/sync.js";
+import { SyncSDK } from "../sync/sdk.js";
 function printUsage() {
     console.log(`
 Ema Agent Sync CLI

package/dist/{sdk → mcp}/autobuilder.js

@@ -274,7 +274,7 @@ export function generateAutobuilderPrompt(description, personaType) {
             prompt += "- Use external_action_caller or send_email_agent as needed\n";
         }
         if (hasHITL) {
-            prompt += "- Include general_hitl with success/failure paths\n";
+            prompt += "- Enable HITL flag on agents that need approval (do NOT add standalone general_hitl nodes)\n";
         }
         prompt += `- ${config.outputNote}\n`;
     }

package/dist/mcp/domain/dashboard.js

@@ -0,0 +1,224 @@
+/**
+ * Dashboard Domain Logic
+ *
+ * Business logic for dashboard operations including:
+ * - Sanitization of PII in column values
+ * - Nested data transformation with sanitization
+ * - Validation helpers
+ *
+ * Note: Pure format translation (without sanitization) is in SDK's columnValueToInput().
+ */
+import { columnValueToInput } from "../../sdk/ema-client.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Sanitization
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Sanitization session for PII replacement.
+ * Maintains consistent replacements across multiple values.
+ */
+export class SanitizationSession {
+    replacements = new Map();
+    counters = {};
+    /**
+     * Get or create a replacement for a detected PII value.
+     * Returns consistent replacements for the same value.
+     */
+    getOrCreateReplacement(value, type) {
+        const existing = this.replacements.get(value);
+        if (existing)
+            return existing;
+        this.counters[type] = (this.counters[type] ?? 0) + 1;
+        const replacement = `[${type.toUpperCase()}_${this.counters[type]}]`;
+        this.replacements.set(value, replacement);
+        return replacement;
+    }
+    /** Get all replacements made in this session */
+    getReplacements() {
+        return new Map(this.replacements);
+    }
+}
+/**
+ * Detect PII patterns in text using regex.
+ */
+export function detectPiiPatterns(text) {
+    const detected = [];
+    // Email pattern
+    const emailRegex = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+    for (const match of text.matchAll(emailRegex)) {
+        detected.push({ value: match[0], type: "email" });
+    }
+    // Phone pattern (various formats)
+    const phoneRegex = /\b(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}\b/g;
+    for (const match of text.matchAll(phoneRegex)) {
+        detected.push({ value: match[0], type: "phone" });
+    }
+    return detected;
+}
+/**
+ * Sanitize a string value by replacing detected PII.
+ */
+export function sanitizeString(value, session, additionalPatterns) {
+    let result = value;
+    // Pattern-based sanitization
+    const detected = detectPiiPatterns(result);
+    for (const entity of detected) {
+        const replacement = session.getOrCreateReplacement(entity.value, entity.type);
+        result = result.split(entity.value).join(replacement);
+    }
+    // User-provided patterns
+    if (additionalPatterns) {
+        for (const pattern of additionalPatterns) {
+            if (result.includes(pattern)) {
+                const replacement = session.getOrCreateReplacement(pattern, "custom");
+                result = result.split(pattern).join(replacement);
+            }
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Column Value Conversion with Sanitization
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Convert a column value to DashboardInput with optional sanitization.
+ *
+ * This wraps the SDK's pure conversion function and adds sanitization.
+ * Use this in MCP handlers when sanitization is needed.
+ *
+ * @param name - The column/field name
+ * @param value - The column value from API response
+ * @param session - Sanitization session (null to skip sanitization)
+ * @param additionalPatterns - Additional strings to sanitize
+ * @returns DashboardInput for upload, or null if value is empty/unsupported
+ */
+export function columnValueToInputWithSanitization(name, value, session, additionalPatterns) {
+    if (!value)
+        return null;
+    // If no sanitization needed, delegate to SDK
+    if (!session) {
+        return columnValueToInput(name, value);
+    }
+    // Handle string value with sanitization
+    if (value.stringValue !== undefined) {
+        const sanitized = sanitizeString(value.stringValue, session, additionalPatterns);
+        return { name, string_value: sanitized };
+    }
+    // Handle number value (no sanitization needed)
+    if (value.numberValue !== undefined) {
+        return { name, number_value: value.numberValue };
+    }
+    // Handle boolean value (no sanitization needed)
+    if (value.booleanValue !== undefined) {
+        return { name, boolean_value: value.booleanValue };
+    }
+    // Handle array value (recursively with sanitization)
+    if (value.arrayValue) {
+        const elements = value.arrayValue.arrayValues ?? [];
+        if (elements.length === 0)
+            return null;
+        const arrayInputs = [];
+        for (const elem of elements) {
+            const converted = columnValueToInputWithSanitization("element", elem, session, additionalPatterns);
+            if (converted)
+                arrayInputs.push(converted);
+        }
+        return arrayInputs.length > 0 ? { name, array_value: arrayInputs } : null;
+    }
+    // Handle object value (recursively with sanitization)
+    if (value.objectValue) {
+        const objectVals = value.objectValue.objectValues ?? {};
+        const keys = Object.keys(objectVals);
+        if (keys.length === 0)
+            return null;
+        const objectInput = {};
+        for (const key of keys) {
+            const converted = columnValueToInputWithSanitization(key, objectVals[key], session, additionalPatterns);
+            if (converted)
+                objectInput[key] = converted;
+        }
+        return Object.keys(objectInput).length > 0 ? { name, object_value: objectInput } : null;
+    }
+    // Unsupported types - delegate to SDK (will return null)
+    return columnValueToInput(name, value);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Nested Data Validation
+// ─────────────────────────────────────────────────────────────────────────────
+/** Maximum array elements to prevent oversized payloads */
+export const MAX_ARRAY_ELEMENTS = 1000;
+/** Maximum nesting depth for arrays/objects */
+export const MAX_NESTING_DEPTH = 3;
+/**
+ * Validate nested data structure.
+ * Returns errors/warnings for issues found.
+ */
+export function validateNestedData(value, schemaType, path = "", depth = 0) {
+    const errors = [];
+    // Check nesting depth
+    if (depth > MAX_NESTING_DEPTH) {
+        errors.push({
+            path,
+            message: `Nesting depth exceeds maximum of ${MAX_NESTING_DEPTH}`,
+            severity: "error",
+        });
+        return errors;
+    }
+    // Validate based on schema type
+    if (schemaType === "COLUMN_TYPE_ARRAY" || schemaType === "ARRAY") {
+        if (!Array.isArray(value)) {
+            errors.push({
+                path,
+                message: `Expected array for ARRAY column, got ${typeof value}`,
+                severity: "error",
+            });
+        }
+        else if (value.length > MAX_ARRAY_ELEMENTS) {
+            errors.push({
+                path,
+                message: `Array has ${value.length} elements, exceeds maximum of ${MAX_ARRAY_ELEMENTS}`,
+                severity: "error",
+            });
+        }
+    }
+    else if (schemaType === "COLUMN_TYPE_OBJECT" || schemaType === "OBJECT") {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            errors.push({
+                path,
+                message: `Expected object for OBJECT column, got ${Array.isArray(value) ? "array" : typeof value}`,
+                severity: "error",
+            });
+        }
+    }
+    else if (schemaType === "COLUMN_TYPE_STRING" || schemaType === "STRING") {
+        if (typeof value !== "string") {
+            if (Array.isArray(value)) {
+                errors.push({
+                    path,
+                    message: `Column expects scalar STRING value, got array. Did you mean to use an ARRAY column?`,
+                    severity: "error",
+                });
+            }
+            else if (typeof value === "object" && value !== null) {
+                errors.push({
+                    path,
+                    message: `Column expects scalar STRING value, got object. Did you mean to use an OBJECT column?`,
+                    severity: "error",
+                });
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Check if a value contains nested data (array or object).
+ */
+export function hasNestedData(value) {
+    if (Array.isArray(value))
+        return true;
+    if (typeof value === "object" && value !== null) {
+        // Check if it looks like a nested structure vs a simple object
+        const keys = Object.keys(value);
+        return keys.some(k => !["name", "string_value", "number_value", "boolean_value", "document_value"].includes(k));
+    }
+    return false;
+}

package/dist/{sdk → mcp/domain}/generation-schema.js

@@ -7,7 +7,7 @@
  * The auto-builder sends ~70K tokens of documentation per request.
  * This schema reduces that to ~5K tokens of actionable constraints.
  */
-import { AGENT_CATALOG } from "./knowledge.js";
+import { AGENT_CATALOG } from "../knowledge.js";
 import { INPUT_SOURCE_RULES } from "./validation-rules.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Schema Generation

package/dist/{sdk → mcp/domain}/intent-architect.js

@@ -34,7 +34,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
-import { getResourcePath } from "./paths.js";
+import { getResourcePath } from "../../sdk/paths.js";
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -54,8 +54,8 @@ export function loadGateConfig(forceReload = false) {
     }
     // Try multiple paths (works in both src and dist)
     const possiblePaths = [
-        path.resolve(__dirname, "../../resources/config/gates.json"),
         path.resolve(__dirname, "../../../resources/config/gates.json"),
+        path.resolve(__dirname, "../../../../resources/config/gates.json"),
         getResourcePath("resources/config/gates.json"),
     ];
     for (const configPath of possiblePaths) {
@@ -131,7 +131,7 @@ let _cachedPrompt = null;
 export function getIntentArchitectPrompt() {
     if (_cachedPrompt)
         return _cachedPrompt;
-    const promptPath = path.join(__dirname, "../prompts/intent-architect.md");
+    const promptPath = path.join(__dirname, "../../prompts/intent-architect.md");
     try {
         _cachedPrompt = fs.readFileSync(promptPath, "utf-8");
         return _cachedPrompt;

package/dist/{sdk → mcp/domain}/structural-rules.js

@@ -129,6 +129,25 @@ export const STRUCTURAL_INVARIANTS = [
         fix: "Use entity_extraction to extract email_address, then connect to to_email",
         severity: "critical",
     },
+    {
+        id: "inline_type_format",
+        name: "Inline Values Must Use Correct Type Format",
+        rule: "When providing inline values, the format must match the expected input type. " +
+            "stringValue → STRING, textWithSources → TEXT_WITH_SOURCES, enumValue → ENUM. " +
+            "These are NOT interchangeable - the Go workflow engine validates types at deploy time.",
+        violation: "Node input expects TEXT_WITH_SOURCES but inline uses { wellKnown: { stringValue: '...' } } (STRING type)",
+        fix: "Change to { wellKnown: { textWithSources: { text: '...', sources: [], resultConfidence: 0, toolSources: [], resultType: 0 } } }",
+        severity: "critical",
+    },
+    {
+        id: "named_inputs_binding_format",
+        name: "Named Inputs Must Use multiBinding Format",
+        rule: "The named_inputs field in workflow_def requires protobuf-compatible multiBinding.elements[].namedBinding structure. " +
+            "Plain objects or arrays will cause deploy failure.",
+        violation: "named_inputs: { key: value } or named_inputs: [{ name: 'key', value: ... }]",
+        fix: "Use: { multiBinding: { elements: [{ namedBinding: { name: 'key', value: <binding>, description: '', isOptional: false }, autoDetectedBinding: false }] }, autoDetectedBinding: false }",
+        severity: "critical",
+    },
     {
         id: "no_redundant_classifiers",
         name: "No Redundant Classifiers",
@@ -313,6 +332,25 @@ BEFORE finalizing any workflow modification, verify these rules:
 
 10. **Both Paths Required**: general_hitl needs handlers for both approval AND rejection.
 
+### Raw workflow_def Format Rules (CRITICAL)
+
+11. **Inline Type Format** (wrong format → HTTP 500 with no error details):
+   | Input Expects | Inline Format |
+   |---------------|---------------|
+   | STRING | \`{ wellKnown: { stringValue: "..." } }\` |
+   | TEXT_WITH_SOURCES | \`{ wellKnown: { textWithSources: { text: "...", sources: [], resultConfidence: 0, toolSources: [], resultType: 0 } } }\` |
+   | ENUM | \`{ enumValue: "CategoryName" }\` |
+
+   **WARNING**: STRING ≠ TEXT_WITH_SOURCES. Wrong format → HTTP 500 with no error details.
+
+12. **named_inputs Format**: Must use \`multiBinding.elements[].namedBinding\` structure (protobuf JSON format). Plain objects or arrays cause deploy failure.
+
+13. **Action Namespaces**: Must be \`["actions", "emainternal"]\`, not empty \`[]\`. Empty namespaces cause deploy failure.
+
+14. **Categorizer typeArguments**: Categorizers require \`typeArguments.categories\` pointing to an enumType. Empty \`typeArguments: {}\` causes deploy failure.
+
+15. **Dashboard Document Upload Order**: For dashboard personas, documents must be uploaded AFTER the persona is enabled. The workflow must be active to process input documents. Order: create → deploy workflow → enable → upload documents.
+
 ### Self-Check Checklist
 
 After generating/modifying a workflow, verify:
@@ -325,6 +363,11 @@ After generating/modifying a workflow, verify:
 - [ ] Response nodes are mutually exclusive (gated by runIf)
 - [ ] Email recipients come from entity_extraction
 - [ ] No circular dependencies
+- [ ] Inline values use correct type format (stringValue vs textWithSources)
+- [ ] named_inputs uses multiBinding.elements[].namedBinding format
+- [ ] Action namespaces are ["actions", "emainternal"], not empty []
+- [ ] Categorizers have typeArguments.categories pointing to enumType
+- [ ] Dashboard personas: enable persona BEFORE uploading documents
 `;
 export const GRAPH_ANALYSIS_RULES = [
     // ═══════════════════════════════════════════════════════════════════════════

package/dist/{sdk → mcp/domain}/validation-rules.js

@@ -32,11 +32,17 @@ export const INPUT_SOURCE_RULES = [
     },
     {
         actionPattern: "text_categorizer",
-        recommended: "user_query",
-        avoid: ["chat_conversation"],
-        reason: "text_categorizer expects TEXT_WITH_SOURCES, not CHAT_CONVERSATION. Use chat_categorizer instead for conversations.",
+        recommended: "named_inputs (v1) or user_query (v0 deprecated)",
+        avoid: ["chat_conversation", "stringValue for categorization_instructions"],
+        reason: "text_categorizer/v1 uses named_inputs (multiBinding format) for input context. " +
+            "categorization_instructions must be TEXT_WITH_SOURCES (textWithSources), not STRING (stringValue). " +
+            "v0 is DEPRECATED - use v1 with named_inputs. " +
+            "For conversation routing, use chat_categorizer instead.",
         severity: "critical",
-        fix: "Use chat_categorizer for conversation routing, or use user_query/summarized_conversation for text_categorizer",
+        fix: "Use text_categorizer/v1 with: named_inputs (multiBinding format), " +
+            "categorization_instructions (textWithSources inline), " +
+            "typeArguments.categories pointing to enumType, " +
+            "and ensure enumType has Fallback category",
     },
     {
         actionPattern: "respond_with_sources",
@@ -126,12 +132,13 @@ export const ANTI_PATTERNS = [
     {
         id: "email-without-validation",
         name: "Email Without Input Validation",
-        pattern: "send_email_agent without entity_extraction and HITL confirmation",
+        pattern: "send_email_agent without entity_extraction to validate recipient data",
         problem: "Sending emails without extracting and validating recipient data risks sending to wrong people or with wrong content. Emails are high-impact actions with external side effects.",
-        solution: "Always: 1) Extract required fields (email_address, subject) via entity_extraction, 2) Validate completeness via categorizer, 3) Ask user if missing, 4) Confirm via HITL before sending.",
+        solution: "Always: 1) Extract required fields (email_address, subject) via entity_extraction, 2) Validate completeness via categorizer, 3) Ask user if missing. " +
+            "For approval: enable the HITL flag on send_email_agent (do NOT add a standalone general_hitl node).",
         detection: {
-            issueType: "incomplete_hitl",
-            condition: "send_email_agent without preceding entity_extraction AND hitl nodes",
+            issueType: "incomplete_email_validation",
+            condition: "send_email_agent without preceding entity_extraction node to extract/validate recipient data",
         },
         severity: "critical",
     },
@@ -188,12 +195,15 @@ export const ANTI_PATTERNS = [
         name: "Incomplete HITL Paths",
         pattern: "HITL with only success path",
         problem: "Rejected requests have no handling, leaving users without response.",
-        solution: "ALWAYS implement both success AND failure paths for general_hitl.",
+        solution: "If workflow already has general_hitl node: ALWAYS implement both success AND failure paths. For NEW workflows: use HITL flag on the agent instead of standalone general_hitl nodes (see hitl-patterns guidance).",
         detection: {
             issueType: "incomplete_hitl",
             condition: "HITL node missing 'hitl_status_HITL Success' or 'hitl_status_HITL Failure' edge (note: space, not underscore)",
         },
         severity: "critical",
+        // TODO: Revisit if general_hitl is re-enabled as a standalone node.
+        // Currently HITL is a flag on agents (send_email_agent, external_action_caller).
+        // This anti-pattern still fires for existing workflows that use general_hitl.
     },
     {
         id: "orphan-nodes",
@@ -317,6 +327,83 @@ export const ANTI_PATTERNS = [
         },
         severity: "critical",
     },
+    {
+        id: "type-mismatch-inline",
+        name: "Inline Type Mismatch",
+        pattern: "Using stringValue inline where TEXT_WITH_SOURCES input expected, or vice versa",
+        problem: "The Go workflow engine validates type compatibility at deploy time. " +
+            "stringValue (STRING type) is NOT interchangeable with textWithSources (TEXT_WITH_SOURCES type). " +
+            "Mismatches cause HTTP 500 with no error details.",
+        solution: "Match inline value format to expected input type:\n" +
+            "- STRING input → { inline: { wellKnown: { stringValue: '...' } } }\n" +
+            "- TEXT_WITH_SOURCES input → { inline: { wellKnown: { textWithSources: { text: '...', sources: [], resultConfidence: 0, toolSources: [], resultType: 0 } } } }\n" +
+            "- ENUM input → { inline: { enumValue: 'CategoryName' } }",
+        detection: {
+            issueType: "type_mismatch_inline",
+            condition: "Inline value format doesn't match expected input type",
+        },
+        severity: "critical",
+    },
+    {
+        id: "wrong-named-inputs-format",
+        name: "Wrong named_inputs Format",
+        pattern: "Using plain objects or arrays for named_inputs instead of multiBinding format",
+        problem: "named_inputs expects protobuf-compatible multiBinding.elements[].namedBinding structure. " +
+            "Plain JSON objects cause deploy failure (HTTP 500).",
+        solution: "Use the correct multiBinding format:\n" +
+            '{ "multiBinding": { "elements": [{ "namedBinding": { "name": "key", "value": <binding>, "description": "", "isOptional": false }, "autoDetectedBinding": false }] }, "autoDetectedBinding": false }',
+        detection: {
+            issueType: "wrong_named_inputs_format",
+            condition: "named_inputs value is not a multiBinding structure",
+        },
+        severity: "critical",
+    },
+    {
+        id: "categorizer-missing-type-arguments",
+        name: "Categorizer Missing typeArguments",
+        pattern: "text_categorizer or chat_categorizer with empty typeArguments ({})",
+        problem: "Categorizers require typeArguments.categories pointing to the enum type. " +
+            "Empty typeArguments causes deploy failure.",
+        solution: "Add typeArguments:\n" +
+            '{ "typeArguments": { "categories": { "enumType": { "name": { "name": "my_enum", "namespaces": [] } }, "isList": false } } }\n' +
+            "And ensure a matching enumType exists in workflow_def.enumTypes[].",
+        detection: {
+            issueType: "categorizer_missing_type_arguments",
+            condition: "Categorizer node has empty typeArguments or missing categories key",
+        },
+        severity: "critical",
+    },
+    {
+        id: "empty-action-namespaces",
+        name: "Empty Action Namespaces",
+        pattern: "Action with namespaces: [] instead of proper namespace path",
+        problem: "Actions require namespaces: ['actions', 'emainternal']. " +
+            "Empty namespaces cause deploy failure.",
+        solution: "Use the correct namespace format:\n" +
+            '{ "action": { "name": { "namespaces": ["actions", "emainternal"], "name": "call_llm" }, "version": "v2" } }',
+        detection: {
+            issueType: "empty_action_namespaces",
+            condition: "Action has empty namespaces array []",
+        },
+        severity: "critical",
+    },
+    {
+        id: "dashboard-upload-before-enable",
+        name: "Dashboard Documents Uploaded Before Persona Enabled",
+        pattern: "Uploading input documents to a dashboard persona before the persona is enabled",
+        problem: "For dashboard personas, the workflow must be active (persona enabled) before uploading input documents. " +
+            "If documents are uploaded before enabling, the workflow isn't active to process them and the upload will fail.",
+        solution: "Follow this order:\n" +
+            "1. Create persona\n" +
+            "2. Deploy workflow: workflow(mode='deploy', persona_id='...', workflow_def={...})\n" +
+            "3. Enable persona (activate it)\n" +
+            "4. Upload documents: persona(id='...', data={method:'upload', items:[...]})",
+        detection: {
+            issueType: "dashboard_upload_before_enable",
+            condition: "Dashboard persona receives document upload while persona is not enabled/active",
+        },
+        severity: "critical",
+    },
     {
         id: "dashboard-input-columns",
         name: "Dashboard Input Columns From Trigger Outputs",
@@ -349,6 +436,64 @@ export const ANTI_PATTERNS = [
         },
         severity: "critical",
     },
+    {
+        id: "chat-conversation-without-chat-response",
+        name: "Chat Conversation Not Wired to Chat Response Node",
+        pattern: "Chat workflow where chat_conversation is consumed by processing nodes but never wired to a chat-aware response node (respond_with_sources or respond_for_external_actions)",
+        problem: "When chat_conversation is processed by nodes like entity_extraction, call_llm, or search, " +
+            "but the final response is generated by a generic call_llm (not a chat-aware response node), " +
+            "the response node lacks conversation history context. This causes:\n" +
+            "1. Duplicate/repetitive responses — the LLM re-asks questions already answered in conversation\n" +
+            "2. Lost context — follow-up messages lose prior context\n" +
+            "3. Hallucinated greetings — the LLM generates its own greeting instead of continuing the conversation\n\n" +
+            "The chat-aware response nodes (respond_with_sources, respond_for_external_actions) are specifically " +
+            "designed to handle conversation history and produce contextually appropriate responses.",
+        solution: "Wire chat_conversation through to a chat-aware response node:\n" +
+            "• For search-based responses: use respond_with_sources (takes query + search_results)\n" +
+            "• For tool/action results: use respond_for_external_actions (takes query + external_action_result)\n" +
+            "• If using call_llm as responder: wire chat_conversation into named_inputs so the LLM sees full history\n\n" +
+            "Correct patterns:\n" +
+            "  chat_trigger → search → respond_with_sources → WORKFLOW_OUTPUT\n" +
+            "  chat_trigger → external_action_caller → respond_for_external_actions → WORKFLOW_OUTPUT\n" +
+            "  chat_trigger → call_llm(named_inputs includes chat_conversation) → WORKFLOW_OUTPUT\n\n" +
+            "Anti-patterns:\n" +
+            "  ❌ chat_trigger → search → call_llm (no conversation context) → WORKFLOW_OUTPUT\n" +
+            "  ❌ chat_trigger → entity_extraction → call_llm (stateless) → WORKFLOW_OUTPUT",
+        detection: {
+            issueType: "chat_conversation_not_wired_to_response",
+            condition: "Chat workflow (chat_trigger) where terminal response node is call_llm without chat_conversation in named_inputs, " +
+                "and respond_with_sources / respond_for_external_actions are not used",
+        },
+        severity: "critical",
+    },
+    {
+        id: "entity-extraction-direct-to-email",
+        name: "Entity Extraction Wired Directly to Email Inputs",
+        pattern: "entity_extraction outputs connected directly to send_email_agent.email_to, email_subject, or email_body",
+        problem: "entity_extraction outputs are typed as WELL_KNOWN_TYPE_ANY (structured extraction results), " +
+            "but send_email_agent inputs (email_to, email_subject, email_body) require WELL_KNOWN_TYPE_TEXT_WITH_SOURCES. " +
+            "Direct wiring causes type mismatch errors or corrupted email fields.\n\n" +
+            "Additionally, entity_extraction outputs may contain multiple extracted values in a structured format — " +
+            "wiring the entire output to email_to would send an object/JSON as the recipient address, not a clean email string.",
+        solution: "Use intermediary nodes to extract and format individual fields:\n\n" +
+            "Pattern A — json_mapper + fixed_response (recommended for multiple fields):\n" +
+            "  entity_extraction → json_mapper (extract 'to', 'subject', 'body') → fixed_response({{to}}) → send_email_agent.email_to\n" +
+            "  Same json_mapper → fixed_response({{subject}}) → send_email_agent.email_subject\n" +
+            "  Same json_mapper → fixed_response({{body}}) → send_email_agent.email_body\n\n" +
+            "Pattern B — custom_agent with output_fields (simpler for LLM-generated content):\n" +
+            "  custom_agent(output_fields=[To,Subject,Body]) → send_email_agent\n" +
+            "  (custom_agent with output_fields produces individual TEXT_WITH_SOURCES outputs)\n\n" +
+            "Pattern C — fixed_response with template variables (for simple extraction):\n" +
+            "  entity_extraction → fixed_response(template='{{email_address}}', custom_data=entity_extraction) → send_email_agent.email_to\n\n" +
+            "Key principle: send_email_agent inputs need TEXT_WITH_SOURCES — always use fixed_response or " +
+            "custom_agent(output_fields) as the adapter between extraction results and email fields.",
+        detection: {
+            issueType: "entity_extraction_direct_to_email",
+            condition: "entity_extraction output connected directly to send_email_agent.email_to, email_subject, or email_body " +
+                "without an intermediary json_mapper/fixed_response/custom_agent node",
+        },
+        severity: "critical",
+    },
 ];
 export const OPTIMIZATION_RULES = [
     {