@ema.co/mcp-toolkit 1.4.3 → 1.5.0

package/dist/sdk/knowledge.js

@@ -1171,6 +1171,348 @@ export const GUIDANCE_TOPICS = {
             "conversation_summarizer may still be needed for downstream agent format requirements",
         ],
     },
+    "workflow-structure": {
+        title: "Workflow Structure Best Practices",
+        content: "Recommended pattern: Conversation Summarizer → Entity Extractor → JSON Mapper → Downstream Consumers. Extract once, pass outputs onward. This ensures client context is available before knowledge base searches.",
+        examples: [
+            "✅ Good: trigger → summarizer → extractor → json_mapper → [search, routing, responses]",
+            "✅ Good: Single extraction node feeds JSON mapper, which distributes to multiple consumers",
+            "❌ Bad: Multiple extraction nodes extracting same data from same input",
+            "❌ Bad: KB search before extraction (can't use client context)",
+        ],
+        criticalRules: [
+            "Extract entities ONCE, then pass structured data via JSON mapper",
+            "Place extraction BEFORE knowledge base searches that need client context",
+            "JSON mapper output (output_json) should feed downstream nodes that need structured context",
+            "Avoid duplicate extraction nodes - use single extractor → JSON mapper pattern",
+            "Early KB search only sees summarized conversation, not extracted client details",
+        ],
+    },
+    "search-node-timing": {
+        title: "Knowledge Base Search Node Timing and Usage",
+        content: "Search nodes execute based on their input connections. Early search (after summarizer) only sees conversation summary. Late search (after JSON mapper) can use client context. Use multiple search nodes if you need both generic and context-aware retrieval.",
+        examples: [
+            "Early search: trigger → summarizer → knowledge_search_1 (sees only summary, no client context)",
+            "Late search: trigger → summarizer → extractor → json_mapper → knowledge_search_2 (can use client_id, client_name from output_json)",
+            "Template search: json_mapper → fixed_response (query builder) → template_search (uses client context in query)",
+            "Dual search pattern: Early generic search + late context-aware search for comprehensive results",
+        ],
+        criticalRules: [
+            "Search nodes only see data from their input connections - check what flows into query input",
+            "Early search (before extraction) = generic retrieval, may miss client-specific docs",
+            "Late search (after JSON mapper) = can incorporate client context into query or filters",
+            "Template search should run AFTER JSON mapper to use client context",
+            "If search needs client details, it MUST run after entity extraction + JSON mapping",
+            "Multiple search nodes are valid if they serve different purposes (generic vs context-aware)",
+        ],
+    },
+    "node-execution-conditions": {
+        title: "When Nodes Execute (Execution Conditions)",
+        content: "Nodes execute based on: 1) Input connections (data must flow in), 2) runIf conditions (must evaluate to true), 3) trigger_when conditions (for HITL/conditional nodes). Nodes without valid input paths or with false runIf conditions will NOT execute.",
+        examples: [
+            "Orphan node: No input connection from trigger → node never executes",
+            "runIf false: Node has input but runIf condition evaluates false → node skipped",
+            "Missing category edge: Categorizer output not connected → downstream nodes never receive category",
+            "Dead end: Node executes but output not connected → data lost, no response to user",
+        ],
+        criticalRules: [
+            "Every node MUST have a path from trigger (or be reachable via runIf conditions)",
+            "runIf conditions use: lhs (actionOutput reference), operator (1=equals), rhs (enumValue or value)",
+            "If runIf evaluates false, node is skipped (doesn't execute)",
+            "Nodes without input connections are 'orphans' and never execute",
+            "Categorizer nodes need downstream nodes with runIf conditions for each category",
+            "Check execution flow: trigger → [conditional paths] → response → WORKFLOW_OUTPUT",
+            "Use workflow(mode='analyze', include=['execution_flow']) to detect execution issues",
+        ],
+    },
+    "array-preservation": {
+        title: "Array Preservation in Workflows",
+        content: "Arrays from entity extraction may be flattened or truncated unless explicitly configured. JSON mappers must preserve array structure. Downstream nodes need array-aware handling for multi-value operations (e.g., multiple email recipients).",
+        examples: [
+            "✅ Entity extraction schema: { 'participants': { 'type': 'array', 'items': 'string' } }",
+            "✅ JSON mapper: Map participants → participants (preserve as array, not first element)",
+            "❌ Without array config: participants[] may return only first element or serialize as string",
+            "⚠️ Send email with multiple recipients: Use array in to_email OR iterator node for individual sends",
+        ],
+        criticalRules: [
+            "Entity extraction MUST define array types in schema: { 'field': { 'type': 'array', 'items': 'string' } }",
+            "JSON mapper MUST explicitly map arrays (not flatten to first element)",
+            "Arrays like participants[], topics[], recipients[] require explicit array type preservation",
+            "Downstream nodes consuming arrays must handle array input (e.g., to_email accepts array OR use iterator)",
+            "Without proper array config, arrays may: flatten to first element, serialize as string, or truncate",
+            "For email to multiple recipients: configure to_email as array OR add iterator node before send_email",
+            "Check extraction schema, JSON mapper mappings, and downstream node array handling",
+        ],
+    },
+    "search-filtering": {
+        title: "Search Filtering Best Practices",
+        content: "Use BOTH semantic query + structured filters (filename/path/metadata). Filter-first when you have reliable context, but never rely on filename/path alone unless doing known-item lookup. Always include security filters (tenant_id/client_id).",
+        examples: [
+            "✅ Best: semantic query + tenant_id filter + path_prefix filter + doc_type filter",
+            "✅ Fallback: If filtered search returns < N results, rerun without path/filename filters (keep security filters)",
+            "❌ Bad: Only filename/path filter without semantic query (misses relevant docs)",
+            "❌ Bad: Over-filtering from uncertain extraction (causes 'no results' and hallucination risk)",
+        ],
+        criticalRules: [
+            "ALWAYS use semantic query + structured filters together (not either/or)",
+            "Security trimming is mandatory: always filter by tenant_id/client_id and enforce ACLs",
+            "Filter-first approach: use filters when you have reliable extracted context (high confidence)",
+            "Never rely on path/filename filters alone unless user explicitly provided exact name",
+            "Prefer prefix/path filters over exact filename (exact matching is brittle)",
+            "If filtered search returns too few results, fallback to query-only (keeping security filters)",
+            "For templates: filter by category, language, channel, brand/client; then semantic query within filtered set",
+            "Treat extracted entities as probabilistic - only apply restrictive filters if confidence is high",
+            "Index normalized paths, path_prefixes, file_name, tenant_id, doc_type, ACL principals",
+        ],
+    },
+    "fallback-response-inputs": {
+        title: "Fallback Response Input Best Practices",
+        content: "Fallback responses should use full conversation + routing context, NOT just summarized query. Summary removes exact phrasing, tone, and last user message - exactly what fallback needs for clarifying questions.",
+        examples: [
+            "✅ Good: trigger.chat_conversation → fallback.query + routing category + JSON context in named_inputs",
+            "✅ Good: Build fallback context JSON merging: router category + caller status + extracted JSON + summary",
+            "❌ Bad: Only summarized_conversation → fallback.query (loses user wording, causes generic responses)",
+            "⚠️ Optional: Conditional RAG-on-fallback if summary looks like factual question",
+        ],
+        criticalRules: [
+            "Fallback query should use trigger.chat_conversation (full conversation), not just summary",
+            "Include routing context: why it fell back (router category) + caller identification status",
+            "Include extracted JSON context (json_mapper output) so fallback knows what was extracted",
+            "Keep summary as secondary context (in named_inputs), not primary query",
+            "Fallback prompt should explain: 'You are in fallback; ask clarifying question or explain limitations'",
+            "Optional: Add conditional RAG-on-fallback if router category suggests factual question",
+            "Don't automatically run heavy RAG in fallback (fallback is often about clarification, not retrieval)",
+        ],
+    },
+    "separate-vs-merged-inputs": {
+        title: "Separate vs Merged Inputs for Multi-Source Data",
+        content: "Keep separate inputs for semantic clarity and flexible processing. Use named_inputs_* for multi-source data (conversation, templates, client data). Only merge if you need to perform a single operation (like keyword search) on combined text.",
+        examples: [
+            "✅ Good: agent receives named_inputs_Conversation + named_inputs_Templates + named_inputs_ClientData",
+            "✅ Good: Separate inputs allow agent to reason over templates independently from conversation",
+            "❌ Bad: Merging all into single input loses semantic structure and processing flexibility",
+            "⚠️ Merge only if: performing single operation (keyword search) on combined text",
+        ],
+        criticalRules: [
+            "Use separate named_inputs_* for different data sources (conversation, templates, client data)",
+            "Separate inputs provide semantic clarity: agent knows 'this is conversation' vs 'these are templates'",
+            "Separate inputs enable flexible processing: agent can reason over each source independently",
+            "Template selection benefits from separate inputs: agent can choose/apply template dynamically",
+            "Only merge inputs if performing single operation (like keyword search) on combined text",
+            "Ensure all relevant data sources are connected: client RAG results, templates, conversation context",
+        ],
+    },
+    "folder-path-filtering": {
+        title: "Folder Path Filtering in Search",
+        content: "You can filter on folder paths, but should combine with semantic query. Use path_prefix filters (not exact paths) for flexibility. Always combine with tenant_id/client_id security filters and semantic query.",
+        examples: [
+            "✅ Good: path_prefix = /Clients/Acme/Renewals/2026/ + semantic query + tenant_id filter",
+            "✅ Good: Index normalized paths, path_prefixes for fast 'startsWith' filtering",
+            "❌ Bad: Exact path matching (brittle - versions, spacing, extensions)",
+            "❌ Bad: Path filter without semantic query (misses relevant docs in other folders)",
+        ],
+        criticalRules: [
+            "Folder path filtering should ALWAYS be combined with semantic query (not used alone)",
+            "Use path_prefix filters (not exact paths) for flexibility and version tolerance",
+            "Index normalized paths (lowercased, consistent separators) + path_prefixes",
+            "Always combine path filters with security filters (tenant_id/client_id) and semantic query",
+            "Path filters are probabilistic - only apply if extracted context has high confidence",
+            "If path-filtered search returns too few results, fallback to query-only (keeping security filters)",
+            "Path filters help narrow scope but semantic query ensures relevance",
+        ],
+    },
+    "automated-extraction-json": {
+        title: "Automating Extraction and JSON Mapping",
+        content: "The extraction → JSON mapper pattern can be automated when following best practices. Use single extraction node → JSON mapper → multiple downstream consumers. Configure extraction schema with array types, then map to normalized JSON structure for consistent downstream access.",
+        examples: [
+            "✅ Automated pattern: trigger → summarizer → extractor → json_mapper → [search, routing, responses]",
+            "✅ JSON mapper normalizes: client_name, client_id, doc_type, template_type, filter fields",
+            "✅ Add retrieval-ready fields: client_folder_prefix, template_folder_prefix, filter_strength",
+            "❌ Manual: Multiple extraction nodes extracting same data from same input",
+        ],
+        criticalRules: [
+            "Extract ONCE per conversation, then pass structured data via JSON mapper to all consumers",
+            "Configure extraction schema with explicit array types: { 'field': { 'type': 'array', 'items': 'string' } }",
+            "JSON mapper should normalize values: canonical client name, canonical doc_type, derived filter fields",
+            "Add retrieval-specific fields to JSON: client_folder_prefix, doc_type_keywords, template_folder_prefix",
+            "Include confidence hints: use_client_filter, use_template_filter, filter_strength (none|broad|narrow)",
+            "Downstream nodes consume json_mapper.output_json as custom_data - no need to re-extract",
+            "This pattern enables automated filter construction, query building, and context passing",
+        ],
+    },
+    "when-filters-necessary": {
+        title: "When Filters Are Necessary vs Optional",
+        content: "Filters are necessary for security/isolation unless your storage layer already enforces per-id/tenant access control. Internal document annotations (like id=123 in text) don't prevent cross-id retrieval. Always filter by tenant_id/client_id for security. Path/filename filters are optional for precision but should have fallback.",
+        examples: [
+            "✅ Necessary: tenant_id/client_id filters (security/isolation) - always required",
+            "✅ Optional but recommended: path_prefix filters when you have reliable extracted context",
+            "❌ Not sufficient: Internal document annotations alone (id=123 in text) - still need filters",
+            "⚠️ Skip only if: Separate index/collection per id/tenant OR enforced server-side ACL filtering",
+        ],
+        criticalRules: [
+            "ALWAYS filter by tenant_id/client_id for security/isolation (unless storage enforces it)",
+            "Internal document annotations (id in text) don't prevent cross-id retrieval - still need filters",
+            "Path/filename filters are optional for precision but should have semantic query fallback",
+            "You can skip workflow-level filtering ONLY if storage/retrieval layer guarantees isolation",
+            "Separate index per id/tenant OR enforced metadata/ACL filtering at query time = can skip",
+            "Best practice: Use filters even with annotations - they provide explicit, reliable isolation",
+            "Progressive relaxation: strict filters → broad filters → no filters (keep security filters)",
+        ],
+    },
+    "filter-query-guidance": {
+        title: "Filter vs Query: When to Use Each",
+        content: "Use filters when user intent implies known document scope and being wrong is costly. Use semantic queries when user describes a topic but not a specific file. Use both when you have reliable scope plus a topical question. Filters reduce noise; queries capture meaning. Best practice: filter-first when reliable context, but never rely on filename/path alone.",
+        examples: [
+            "✅ Use filters: User names specific doc ('the MSA', 'SOW 2024-01'), references folder ('in HR policies'), extracted strong entities (client_name, project_name)",
+            "✅ Use query: User describes topic ('How do we handle SOC2?'), intent ('Draft follow-up email'), weak/ambiguous entities",
+            "✅ Use both: Filter to Clients/Acme/ + query 'termination for convenience notice period'",
+            "❌ Filters alone: Only for known-item lookup (user names exact file) - still include short query",
+        ],
+        criticalRules: [
+            "Filters: Best when user names specific doc, references folder, or extracted entities are strong",
+            "Semantic queries: Best when user describes topic/intent, entities are weak/ambiguous",
+            "Use both: Apply broad filters (client folder, doc type) + semantic query for best results",
+            "Progressive relaxation: strict filters → broad filters → query-only (keep security filters)",
+            "Confidence thresholds: Apply restrictive filters only when confidence is high (>=0.75)",
+            "Fallback strategy: If filtered search returns < N results, rerun without path/filename filters",
+            "Never rely on filename/path filters alone unless doing known-item lookup",
+            "Security filters (tenant_id/client_id) are mandatory - never drop these",
+        ],
+    },
+    "node-selection": {
+        title: "Node Selection Guide: When to Use What",
+        content: `Choose the RIGHT node type for each task. Using wrong nodes wastes compute, increases latency, and reduces quality.
+
+## Decision Tree
+
+### Q1: Do you need EXTERNAL KNOWLEDGE?
+- YES → Use search node first, then generation
+- NO → Skip search, use generation or transform
+
+### Q2: Do you need AI REASONING/GENERATION?
+- YES → Use LLM-based node
+- NO → Use transform node (json_mapper, fixed_response)
+
+### Q3: What KIND of generation?
+- Simple Q&A with citations → respond_with_sources
+- Custom generation → call_llm
+- Complex multi-step reasoning → custom_agent
+- Search + synthesize in one → document_synthesis
+
+### Q4: Do you need STRUCTURED DATA extraction?
+- YES → entity_extraction (NOT call_llm!)
+- NO → Continue with generation
+
+## Node Cost/Latency
+
+| Node | LLM Calls | Latency | Use When |
+|------|-----------|---------|----------|
+| fixed_response | 0 | <50ms | Static content, config, templates |
+| json_mapper | 0 | <100ms | Transform JSON without reasoning |
+| entity_extraction | 1 | 1-2s | Extract structured data |
+| respond_with_sources | 1 | 2-4s | Simple search + response |
+| call_llm | 1 | 2-4s | Custom generation |
+| custom_agent | 1-3 | 3-8s | Complex reasoning |
+| document_synthesis | 2-5 | 5-15s | Multi-search + synthesis |`,
+        examples: [
+            "✅ Static template → fixed_response (0 LLM calls)",
+            "✅ Extract client_name, email → entity_extraction (1 LLM call, typed output)",
+            "✅ Simple KB Q&A → respond_with_sources (1 LLM call)",
+            "✅ Custom email generation → call_llm with search results in named_inputs",
+            "❌ Using call_llm to extract JSON → Use entity_extraction instead",
+            "❌ Using document_synthesis for simple Q&A → Use respond_with_sources",
+            "❌ Using custom_agent for static response → Use fixed_response",
+        ],
+        criticalRules: [
+            "NEVER use LLM for transforms that json_mapper can do",
+            "NEVER use call_llm for structured extraction - use entity_extraction",
+            "NEVER use document_synthesis when respond_with_sources suffices",
+            "ALWAYS use fixed_response for static content (templates, config, help text)",
+            "Use entity_extraction for typed, reliable structured data",
+            "Use call_llm when you need custom instructions or reasoning",
+            "Use custom_agent when task requires role context + multi-step reasoning",
+            "Use document_synthesis only when you need search-plan-search-synthesize pattern",
+        ],
+    },
+    "llm-node-selection": {
+        title: "LLM Node Selection: Which One to Use",
+        content: `Different LLM nodes serve different purposes. Choose based on your needs:
+
+## respond_with_sources
+- **Best for**: Simple Q&A with KB citations
+- **Input**: Search results (SEARCH_RESULT type)
+- **Output**: Response with source citations
+- **When**: User asks question, you search KB, return answer
+- **NOT for**: Custom generation, complex reasoning
+
+## call_llm
+- **Best for**: Custom text generation with instructions
+- **Input**: Query + optional search/context via named_inputs
+- **Output**: Generated text
+- **When**: Need custom prompts, specific format, controlled generation
+- **NOT for**: Simple Q&A (use respond_with_sources)
+
+## custom_agent
+- **Best for**: Complex tasks requiring role + instructions
+- **Input**: Role instructions + task instructions + named_inputs
+- **Output**: Structured or free-form response
+- **When**: Multi-step reasoning, persona-based responses, tool-like behavior
+- **NOT for**: Simple generation (overkill)
+
+## document_synthesis
+- **Best for**: Multi-source research with planning
+- **Input**: User request + search results
+- **Output**: Synthesized document
+- **When**: Need to search → plan → search again → synthesize
+- **NOT for**: Simple KB lookup (too heavy)`,
+        examples: [
+            "User asks 'What is our refund policy?' → respond_with_sources",
+            "Need to generate email with specific template → call_llm",
+            "Need to analyze portfolio and recommend actions → custom_agent",
+            "Need to research topic across multiple sources → document_synthesis",
+        ],
+        criticalRules: [
+            "respond_with_sources: 1 LLM call, simple Q&A, requires SEARCH_RESULT input",
+            "call_llm: 1 LLM call, custom generation, accepts named_inputs",
+            "custom_agent: 1-3 LLM calls, complex reasoning, has role context",
+            "document_synthesis: 2-5 LLM calls, heavy, only for research tasks",
+            "Default to respond_with_sources for KB Q&A",
+            "Upgrade to call_llm when you need custom instructions",
+            "Upgrade to custom_agent for complex reasoning",
+            "Use document_synthesis sparingly (latency expensive)",
+        ],
+    },
+    "search-vs-no-search": {
+        title: "When to Search vs Direct Generation",
+        content: `Not every request needs KB search. Search adds latency and can introduce irrelevant context.
+
+## SEARCH when:
+- User asks factual question about domain knowledge
+- Request references specific documents/data
+- Response accuracy depends on up-to-date information
+- User asks about policies, procedures, product details
+
+## DON'T SEARCH when:
+- User needs help with task (drafting, formatting)
+- Response is conversational/procedural
+- Information is already in context (extracted entities)
+- User asks general questions (time, greeting)`,
+        examples: [
+            "✅ Search: 'What is our return policy?' - needs KB",
+            "✅ Search: 'Tell me about client Thompson' - needs client data",
+            "❌ Don't search: 'Can you draft an email?' - procedural",
+            "❌ Don't search: 'Format this as a table' - transform",
+            "❌ Don't search: 'Hello, how are you?' - greeting",
+        ],
+        criticalRules: [
+            "Search is NOT free - adds 0.5-2s latency per search",
+            "Search can introduce noise if results aren't relevant",
+            "Fallback/greeting responses often don't need search",
+            "Task-based requests (draft, format, summarize) usually don't need search",
+            "Use categorizer to route search vs no-search paths",
+            "If entity extraction already has the data, don't search for it again",
+        ],
+    },
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Helper Functions
@@ -2211,6 +2553,457 @@ function detectMalformedRunIf(workflowDef) {
     }
     return issues;
 }
+/**
+ * Detect unused categories - categories defined in enumType but with no handler
+ * This causes SILENT FAILURES where requests match the category but nothing executes
+ */
+function detectUnusedCategories(nodes, workflowDef) {
+    const issues = [];
+    const def = workflowDef;
+    if (!def)
+        return issues;
+    const enumTypes = def.enumTypes;
+    const actions = def.actions;
+    if (!enumTypes || !actions)
+        return issues;
+    // Find all categorizer nodes
+    const categorizers = nodes.filter(n => n.action_name === "chat_categorizer" ||
+        n.action_name === "intent_classifier");
+    for (const categorizer of categorizers) {
+        // Find the enumType for this categorizer
+        const enumTypeName = categorizer.id + "_enumType";
+        const enumType = enumTypes.find(e => {
+            const name = e.name;
+            const innerName = name?.name;
+            const nameStr = String(innerName?.name ?? name?.name ?? "");
+            return nameStr.includes(categorizer.id) || nameStr.includes("enumType");
+        });
+        if (!enumType)
+            continue;
+        const options = enumType.options;
+        if (!options)
+            continue;
+        // Get all defined categories
+        const definedCategories = options.map(o => String(o.name ?? "")).filter(n => n.length > 0);
+        // Find which categories have handlers (via runIf conditions)
+        const handledCategories = new Set();
+        for (const action of actions) {
+            const runIf = action.runIf;
+            if (!runIf)
+                continue;
+            const lhs = runIf.lhs;
+            const actionOutput = lhs?.actionOutput;
+            // Check if this runIf references our categorizer
+            if (actionOutput?.actionName === categorizer.id) {
+                const rhs = runIf.rhs;
+                const inline = rhs?.inline;
+                const enumValue = String(inline?.enumValue ?? "");
+                if (enumValue) {
+                    handledCategories.add(enumValue);
+                }
+            }
+        }
+        // Check for config-based routing (document_synthesis with Config.tasks pattern)
+        // Find Config.tasks keys from fixed_response nodes
+        const configTaskKeys = new Set();
+        for (const action of actions) {
+            const actionInfo = action.action;
+            const actionName = actionInfo?.name;
+            if (actionName?.name !== "fixed_response")
+                continue;
+            const inputs = action.inputs;
+            const template = inputs?.template;
+            const inline = template?.inline;
+            const wellKnown = inline?.wellKnown;
+            const textWithSources = wellKnown?.textWithSources;
+            const text = String(textWithSources?.text ?? "");
+            try {
+                if (text.includes('"tasks"')) {
+                    const config = JSON.parse(text);
+                    const tasks = config.tasks;
+                    if (tasks) {
+                        for (const taskKey of Object.keys(tasks)) {
+                            configTaskKeys.add(taskKey);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Not JSON, skip
+            }
+        }
+        // Check if category is passed to any downstream node (including via named_inputs)
+        // Use flexible string matching to handle any JSON formatting
+        let usesConfigBasedRouting = false;
+        for (const action of actions) {
+            const inputs = action.inputs;
+            if (!inputs)
+                continue;
+            // Check regular inputs and named_inputs for reference to categorizer's category output
+            const inputStr = JSON.stringify(inputs).replace(/\s+/g, "");
+            const categorizerRef = `"actionName":"${categorizer.id}"`.replace(/\s+/g, "");
+            const categoryOutput = `"output":"category"`.replace(/\s+/g, "");
+            if (inputStr.includes(categorizerRef) && inputStr.includes(categoryOutput)) {
+                // This action references the categorizer's category output
+                const actionInfo = action.action;
+                const actionName = actionInfo?.name;
+                const actionType = String(actionName?.name ?? "");
+                // If it's a synthesis/generation node and we have config tasks, it's config-based routing
+                if (["document_synthesis", "call_llm", "custom_agent"].includes(actionType) && configTaskKeys.size > 0) {
+                    usesConfigBasedRouting = true;
+                }
+            }
+        }
+        // If we have config tasks defined, assume config-based routing even if not explicitly detected
+        // This handles cases where the config might be in an orphan node but still used at runtime
+        if (configTaskKeys.size > 0 && !usesConfigBasedRouting) {
+            // Check if any downstream node is a document_synthesis or custom_agent
+            for (const node of nodes) {
+                if (node.action_name === "document_synthesis" || node.action_name === "custom_agent") {
+                    usesConfigBasedRouting = true;
+                    break;
+                }
+            }
+        }
+        // Find unused categories
+        const unusedCategories = definedCategories.filter(c => !handledCategories.has(c));
+        for (const category of unusedCategories) {
+            // Skip Fallback - already detected by missing_fallback
+            if (category === "Fallback")
+                continue;
+            // If using config-based routing, check if category has a task
+            if (usesConfigBasedRouting) {
+                if (!configTaskKeys.has(category)) {
+                    issues.push({
+                        type: "unused_category",
+                        severity: "critical",
+                        node: categorizer.id,
+                        category,
+                        categories: Array.from(configTaskKeys),
+                        auto_fixable: false,
+                        reason: `Category "${category}" is defined but has NO TASK in Config.tasks. ` +
+                            `Requests matching this category will SILENTLY FAIL - the workflow looks for Config.tasks["${category}"] which doesn't exist. ` +
+                            `Config has tasks for: ${Array.from(configTaskKeys).join(", ")}. ` +
+                            `Either add "${category}" to Config.tasks, or remove the category from the enum.`,
+                    });
+                }
+            }
+            else {
+                // No config-based routing - need explicit runIf handler
+                issues.push({
+                    type: "unused_category",
+                    severity: "critical",
+                    node: categorizer.id,
+                    category,
+                    categories: unusedCategories,
+                    auto_fixable: false,
+                    reason: `Category "${category}" is defined in ${categorizer.display_name || categorizer.id} but has NO HANDLER. ` +
+                        `Requests matching this category will SILENTLY FAIL - no response sent to user. ` +
+                        `Either add a node with runIf condition for "${category}", add to Config.tasks, or remove the category.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Detect category name mismatches - e.g., SEND_EMAIL in enum vs SEND_COMMUNICATION in config
+ */
+function detectCategoryNameMismatches(nodes, workflowDef) {
+    const issues = [];
+    const def = workflowDef;
+    if (!def)
+        return issues;
+    const enumTypes = def.enumTypes;
+    const actions = def.actions;
+    if (!enumTypes || !actions)
+        return issues;
+    // Find fixed_response nodes that might contain config with tasks
+    const configNodes = actions.filter(a => {
+        const actionInfo = a.action;
+        const actionName = actionInfo?.name;
+        return actionName?.name === "fixed_response";
+    });
+    for (const configNode of configNodes) {
+        // Try to extract config content
+        const inputs = configNode.inputs;
+        const template = inputs?.template;
+        const inline = template?.inline;
+        const wellKnown = inline?.wellKnown;
+        const textWithSources = wellKnown?.textWithSources;
+        const text = String(textWithSources?.text ?? "");
+        // Try to parse as JSON to find tasks object
+        try {
+            if (text.includes('"tasks"')) {
+                const config = JSON.parse(text);
+                const tasks = config.tasks;
+                if (!tasks)
+                    continue;
+                const taskNames = new Set(Object.keys(tasks));
+                // Compare with enum categories
+                for (const enumType of enumTypes) {
+                    const options = enumType.options;
+                    if (!options)
+                        continue;
+                    const enumCategories = options.map(o => String(o.name ?? "")).filter(n => n.length > 0);
+                    // Find similar but not exact matches
+                    for (const enumCat of enumCategories) {
+                        if (enumCat === "Fallback")
+                            continue;
+                        // Check for name mismatches (similar but different)
+                        const normalizedEnum = enumCat.toLowerCase().replace(/_/g, "");
+                        for (const taskName of taskNames) {
+                            const normalizedTask = taskName.toLowerCase().replace(/_/g, "");
+                            // Similar names but not exact match
+                            if (normalizedEnum !== normalizedTask &&
+                                (normalizedEnum.includes(normalizedTask.slice(0, 4)) ||
+                                    normalizedTask.includes(normalizedEnum.slice(0, 4)))) {
+                                // Check if it's actually a mismatch (enum not in tasks)
+                                if (!taskNames.has(enumCat)) {
+                                    issues.push({
+                                        type: "category_name_mismatch",
+                                        severity: "critical",
+                                        node: String(configNode.name ?? "config"),
+                                        category: enumCat,
+                                        config_key: taskName,
+                                        auto_fixable: true,
+                                        reason: `Category name mismatch: Enum has "${enumCat}" but Config.tasks has "${taskName}". ` +
+                                            `This routing will FAIL because Config.tasks["${enumCat}"] doesn't exist. ` +
+                                            `Either rename the enum category to "${taskName}" or add "${enumCat}" to Config.tasks.`,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Not JSON config, skip
+        }
+    }
+    return issues;
+}
+/**
+ * Detect late categorizer placement - categorizer should be early to avoid wasted processing
+ */
+function detectLateCategorizer(nodes) {
+    const issues = [];
+    const categorizers = nodes.filter(n => n.action_name === "chat_categorizer" ||
+        n.action_name === "intent_classifier");
+    // Heavy processing nodes
+    const heavyNodes = new Set(["call_llm", "custom_agent", "document_synthesis", "search", "knowledge_search"]);
+    for (const categorizer of categorizers) {
+        // Find all nodes upstream of this categorizer
+        const upstreamHeavy = [];
+        const visited = new Set();
+        function findUpstream(nodeId) {
+            if (visited.has(nodeId))
+                return;
+            visited.add(nodeId);
+            const node = nodes.find(n => n.id === nodeId);
+            if (!node?.incoming_edges)
+                return;
+            for (const edge of node.incoming_edges) {
+                const sourceNode = nodes.find(n => n.id === edge.source_node_id);
+                if (sourceNode) {
+                    if (heavyNodes.has(sourceNode.action_name || "")) {
+                        upstreamHeavy.push(sourceNode.display_name || sourceNode.id);
+                    }
+                    findUpstream(sourceNode.id);
+                }
+            }
+        }
+        findUpstream(categorizer.id);
+        if (upstreamHeavy.length > 0) {
+            issues.push({
+                type: "late_categorizer",
+                severity: "warning",
+                node: categorizer.id,
+                nodes: upstreamHeavy,
+                auto_fixable: false,
+                reason: `Categorizer "${categorizer.display_name || categorizer.id}" runs AFTER heavy processing: ${upstreamHeavy.join(", ")}. ` +
+                    `This wastes compute - all that processing happens even for simple requests. ` +
+                    `RECOMMENDATION: Move categorizer earlier in the flow. Categorize FIRST, then process only the relevant branch.`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Detect excessive LLM calls per execution path
+ */
+function detectExcessiveLLMCalls(nodes) {
+    const issues = [];
+    const trigger = nodes.find(n => n.action_name === "trigger" || n.id === "trigger");
+    if (!trigger)
+        return issues;
+    const llmNodes = new Set(["call_llm", "custom_agent", "document_synthesis"]);
+    // Build adjacency list
+    const adj = new Map();
+    for (const node of nodes) {
+        adj.set(node.id, new Set());
+    }
+    for (const node of nodes) {
+        if (node.incoming_edges) {
+            for (const edge of node.incoming_edges) {
+                adj.get(edge.source_node_id)?.add(node.id);
+            }
+        }
+    }
+    // Find all paths from trigger and count LLMs
+    const pathsWithHighLLMCount = [];
+    function dfs(nodeId, path, llmCount) {
+        const node = nodes.find(n => n.id === nodeId);
+        const newPath = [...path, nodeId];
+        const newLLMCount = llmCount + (node && llmNodes.has(node.action_name || "") ? 1 : 0);
+        const neighbors = adj.get(nodeId) || new Set();
+        if (neighbors.size === 0) {
+            // End of path
+            if (newLLMCount > 3) {
+                pathsWithHighLLMCount.push({ path: newPath, llm_count: newLLMCount });
+            }
+            return;
+        }
+        // Limit depth to avoid infinite loops
+        if (newPath.length > 15)
+            return;
+        for (const neighbor of neighbors) {
+            if (!path.includes(neighbor)) {
+                dfs(neighbor, newPath, newLLMCount);
+            }
+        }
+    }
+    dfs(trigger.id, [], 0);
+    // Report worst paths
+    pathsWithHighLLMCount.sort((a, b) => b.llm_count - a.llm_count);
+    for (const { path, llm_count } of pathsWithHighLLMCount.slice(0, 3)) {
+        const llmNodesInPath = path.filter(p => {
+            const node = nodes.find(n => n.id === p);
+            return node && llmNodes.has(node.action_name || "");
+        });
+        issues.push({
+            type: "excessive_llm_calls",
+            severity: llm_count > 5 ? "warning" : "info",
+            nodes: llmNodesInPath,
+            llm_count,
+            path,
+            auto_fixable: false,
+            reason: `Execution path has ${llm_count} LLM calls: ${llmNodesInPath.join(" → ")}. ` +
+                `Each LLM call adds 1-3 seconds latency. Users typically wait max 5-8 seconds. ` +
+                `RECOMMENDATION: Consolidate LLM calls, parallelize where possible, or cache repeated lookups.`,
+        });
+    }
+    return issues;
+}
+/**
+ * Detect suboptimal node choices - using heavy nodes where lighter ones suffice
+ */
+function detectSuboptimalNodeChoices(nodes) {
+    const issues = [];
+    for (const node of nodes) {
+        const actionName = node.action_name || "";
+        const displayName = node.display_name || node.id;
+        // Check for document_synthesis when respond_with_sources might suffice
+        if (actionName === "document_synthesis") {
+            // Check if it has simple inputs (not complex multi-source)
+            const hasSearchInput = node.incoming_edges?.some(e => e.source_output?.includes("search_results"));
+            const hasMultipleSearchInputs = (node.incoming_edges?.filter(e => e.source_output?.includes("search_results")) || []).length > 1;
+            if (hasSearchInput && !hasMultipleSearchInputs) {
+                issues.push({
+                    type: "suboptimal_node_choice",
+                    severity: "info",
+                    node: node.id,
+                    actual_node: "document_synthesis",
+                    recommended_node: "respond_with_sources or call_llm",
+                    use_case: "single search source",
+                    reason: `"${displayName}" uses document_synthesis (2-5 LLM calls) but only has one search source. ` +
+                        `Consider using respond_with_sources (1 call) for simple Q&A, or call_llm with named_inputs for custom generation. ` +
+                        `document_synthesis is best for multi-source research with search-plan-search patterns.`,
+                });
+            }
+        }
+        // Check for call_llm/custom_agent that might be doing extraction
+        if (["call_llm", "custom_agent"].includes(actionName)) {
+            // Look for JSON extraction patterns in instructions
+            const inputStr = JSON.stringify(node.incoming_edges || []);
+            const nodeId = node.id.toLowerCase();
+            const display = displayName.toLowerCase();
+            // Check if this looks like an extraction node
+            if (nodeId.includes("extract") ||
+                display.includes("extract") ||
+                nodeId.includes("parse") ||
+                display.includes("parse")) {
+                issues.push({
+                    type: "suboptimal_node_choice",
+                    severity: "warning",
+                    node: node.id,
+                    actual_node: actionName,
+                    recommended_node: "entity_extraction",
+                    use_case: "structured data extraction",
+                    reason: `"${displayName}" appears to be doing extraction but uses ${actionName}. ` +
+                        `Use entity_extraction instead - it's optimized for structured data, provides typed output, ` +
+                        `and is more reliable for extracting specific fields (names, emails, dates, amounts).`,
+                });
+            }
+        }
+        // Check for LLM nodes that might be doing simple transforms
+        if (["call_llm", "custom_agent", "document_synthesis"].includes(actionName)) {
+            const display = displayName.toLowerCase();
+            const nodeId = node.id.toLowerCase();
+            // Check if it looks like a simple formatter/transformer
+            if ((display.includes("format") && !display.includes("information")) ||
+                display.includes("convert") ||
+                display.includes("template") ||
+                nodeId.includes("formatter") ||
+                nodeId.includes("converter")) {
+                issues.push({
+                    type: "suboptimal_node_choice",
+                    severity: "info",
+                    node: node.id,
+                    actual_node: actionName,
+                    recommended_node: "json_mapper or fixed_response",
+                    use_case: "formatting/transformation",
+                    reason: `"${displayName}" might be doing simple formatting with ${actionName} (LLM-based). ` +
+                        `If this is just data transformation without reasoning, consider json_mapper (no LLM, <100ms) ` +
+                        `or fixed_response with template variables (no LLM, <50ms).`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Detect unnecessary search nodes (search before simple tasks that don't need KB)
+ */
+function detectUnnecessarySearch(nodes) {
+    const issues = [];
+    // Find search nodes
+    const searchNodes = nodes.filter(n => n.action_name === "search" ||
+        n.action_name === "knowledge_search");
+    // Check what consumes each search
+    for (const searchNode of searchNodes) {
+        // Find downstream consumers
+        const consumers = nodes.filter(n => n.incoming_edges?.some(e => e.source_node_id === searchNode.id));
+        // Check if downstream is just fallback/greeting
+        for (const consumer of consumers) {
+            const consumerName = (consumer.display_name || consumer.id).toLowerCase();
+            if (consumerName.includes("fallback") ||
+                consumerName.includes("greeting") ||
+                consumerName.includes("clarif")) {
+                issues.push({
+                    type: "unnecessary_search",
+                    severity: "info",
+                    node: searchNode.id,
+                    reason: `Search "${searchNode.display_name || searchNode.id}" feeds into "${consumer.display_name || consumer.id}" (fallback/greeting). ` +
+                        `Fallback responses typically don't need KB search - they're about clarification, not retrieval. ` +
+                        `Consider removing search from fallback path to reduce latency.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
 export function detectWorkflowIssues(workflowDef) {
     const nodes = parseWorkflowDef(workflowDef);
     if (nodes.length === 0) {
@@ -2231,6 +3024,14 @@ export function detectWorkflowIssues(workflowDef) {
         ...detectEmailIssues(nodes),
         ...detectPerformanceIssues(nodes),
         ...detectMalformedRunIf(workflowDef),
+        // NEW: Category/routing structure issues
+        ...detectUnusedCategories(nodes, workflowDef),
+        ...detectCategoryNameMismatches(nodes, workflowDef),
+        ...detectLateCategorizer(nodes),
+        ...detectExcessiveLLMCalls(nodes),
+        // NEW: Node selection issues
+        ...detectSuboptimalNodeChoices(nodes),
+        ...detectUnnecessarySearch(nodes),
     ];
     // Add type mismatch issues from connection validation
     const connections = validateWorkflowConnections(workflowDef);
@@ -2805,6 +3606,139 @@ ${issue.missing?.includes("failure") || issue.missing?.includes("both") ? `
                     validation: "Verify consolidation doesn't lose intent-specific response quality",
                 };
                 break;
+            // NEW: Category/routing structure fixes
+            case "unused_category":
+                fix = {
+                    issue_type: issue.type,
+                    description: `Add handler for unused category "${issue.category}"`,
+                    after: `# CRITICAL: Category "${issue.category}" has NO HANDLER - requests will SILENTLY FAIL!
+# 
+# OPTION 1: Add a handler node with runIf condition:
+- name: "${issue.category?.toLowerCase().replace(/_/g, "_")}_handler"
+  action:
+    name:
+      namespaces: ["actions", "emainternal"]
+      name: "call_llm"
+  runIf:
+    lhs:
+      actionOutput:
+        actionName: "${issue.node}"
+        output: "category"
+    operator: 1  # EQUALS
+    rhs:
+      inline:
+        enumValue: "${issue.category}"
+  inputs:
+    # ... configure LLM for this category ...
+  displaySettings:
+    displayName: "${issue.category} Handler"
+
+# OPTION 2: Add to Config.tasks if using config-based routing:
+# In your fixed_response config node, add:
+"tasks": {
+  "${issue.category}": "Task instructions for handling ${issue.category} requests..."
+}
+
+# OPTION 3: Remove the category if not needed:
+# Delete "${issue.category}" from enumType.options`,
+                    validation: `Verify "${issue.category}" has a handler (runIf condition or Config.tasks entry)`,
+                };
+                break;
+            case "category_name_mismatch":
+                fix = {
+                    issue_type: issue.type,
+                    description: `Fix category name mismatch: "${issue.category}" vs "${issue.config_key}"`,
+                    before: `# PROBLEM: Enum defines "${issue.category}" but Config.tasks has "${issue.config_key}"
+# The workflow looks for Config.tasks["${issue.category}"] which doesn't exist!`,
+                    after: `# OPTION 1: Rename the enum category to match config:
+# In enumType.options, change:
+- name: "${issue.category}"  # OLD
++ name: "${issue.config_key}"  # NEW (matches Config.tasks)
+
+# OPTION 2: Add the missing key to Config.tasks:
+# In your fixed_response config, add:
+"tasks": {
+  "${issue.category}": "... task instructions ..."  # ADD THIS
+}
+
+# OPTION 3: If both names should exist, add both to Config.tasks:
+"tasks": {
+  "${issue.config_key}": "...",  # existing
+  "${issue.category}": "..."      # add alias or separate task
+}`,
+                    validation: `Verify enum category name matches Config.tasks key exactly`,
+                };
+                break;
+            case "late_categorizer":
+                fix = {
+                    issue_type: issue.type,
+                    description: `Move categorizer "${issue.node}" earlier in the workflow`,
+                    before: `# PROBLEM: Heavy processing runs BEFORE categorization
+# Nodes before categorizer: ${issue.nodes?.join(", ")}
+# This wastes compute for ALL requests, not just the branch that needs it.`,
+                    after: `# RECOMMENDED STRUCTURE: Categorize FIRST, process LATE
+# 
+# ✅ EFFICIENT:
+# trigger → categorizer → [branch A: search + LLM]
+#                       → [branch B: search + LLM]  
+#                       → [branch C: just LLM]
+#
+# ❌ WASTEFUL:
+# trigger → summarize → search → categorizer → [branches]
+#         (ALL requests pay this cost!)
+#
+# TO FIX:
+# 1. Move summarization/search to AFTER categorizer, inside each branch
+# 2. OR use a lightweight "pre-categorizer" that only needs trigger.user_query
+# 
+# Minimal categorizer pattern:
+- name: "intent_classifier"
+  action:
+    name:
+      namespaces: ["actions", "emainternal"]  
+      name: "chat_categorizer"
+  inputs:
+    conversation:
+      actionOutput:
+        actionName: "trigger"
+        output: "chat_conversation"  # Light input, no heavy processing
+    # Optional: provide examples in custom_data for better accuracy`,
+                    validation: `Verify categorizer runs early with minimal upstream processing`,
+                };
+                break;
+            case "excessive_llm_calls":
+                fix = {
+                    issue_type: issue.type,
+                    description: `Reduce LLM calls from ${issue.llm_count} to ≤3 per request`,
+                    before: `# Current path has ${issue.llm_count} LLM calls: ${issue.nodes?.join(" → ")}
+# Each call adds 1-3 seconds. Total: ${(issue.llm_count ?? 0) * 2}+ seconds worst case.
+# Users typically abandon after 5-8 seconds.`,
+                    after: `# STRATEGIES TO REDUCE LLM CALLS:
+#
+# 1. CONSOLIDATE: Merge multiple LLM tasks into one
+#    Instead of: summarize → extract → respond (3 calls)
+#    Use: single call_llm with combined instructions
+#
+# 2. PARALLELIZE: Run independent LLMs simultaneously
+#    Instead of: A → B → C (sequential)
+#    Use: [A, B, C in parallel] → combine (1 effective wait)
+#
+# 3. ELIMINATE: Remove unnecessary LLM steps
+#    - Use json_mapper instead of LLM for simple transformations
+#    - Use fixed_response for static content
+#    - Use entity_extraction (1 call) instead of custom_agent (1 call)
+#
+# 4. CACHE: Reuse results across requests
+#    - Pre-compute common responses
+#    - Store client summaries in knowledge base
+#
+# RECOMMENDED: Max 3 LLM calls per request
+# - 1x categorizer/extraction (optional, can use rules)
+# - 1x main processing (search + reasoning)  
+# - 1x response formatting (if needed)`,
+                    validation: `Verify critical paths have ≤3 LLM calls total`,
+                };
+                break;
         }
         if (fix) {
             fixes.push(fix);