@ema.co/mcp-toolkit 2026.2.5 → 2026.2.19

package/LICENSE

@@ -1,21 +1,29 @@
-MIT License
-
-Copyright (c) 2024-2025 Ema Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Ema Unlimited, Inc.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-----------------------------------------------------------------------
+
+This software is offered under a dual-licensing model.
+
+You may use this software under the terms of the GNU Affero General
+Public License (AGPL) v3, or you may obtain a commercial license
+from Ema Unlimited, Inc.
+
+For commercial licensing inquiries, contact:
+
+legal@ema.co or steven.poitras@ema.co

package/README.md

@@ -76,7 +76,8 @@ Then reload: `source ~/.zshrc`
 }
 ```
 
-> **Important**: 
+> **Important**:
+>
 > - Use `@latest` to always get the newest version (npx caches aggressively without it)
 > - The `-y` flag auto-confirms the npx install prompt
 > - Use `${env:VAR_NAME}` syntax to reference shell environment variables
@@ -119,6 +120,7 @@ Then reload: `source ~/.zshrc`
 ### 4. Verify It Works
 
 Ask your AI assistant:
+
 - "List ema environments" - should show your configured environments
 - "List personas in demo" - should show AI Employees
 
@@ -172,15 +174,16 @@ export EMA_DEV_BEARER_TOKEN="..."    # → creates "dev" environment
 ```
 
 **Default Environment**:
+
 - Set explicitly: `export EMA_ENV_NAME="demo"`
 - Or auto-detected from available credentials
 
 **Well-known URLs** (automatic):
 
-| Environment | URL |
-|-------------|-----|
-| `prod` | `https://api.ema.co` |
-| `<env>` | `https://api.<env>.ema.co` |
+| Environment | URL                        |
+| ----------- | -------------------------- |
+| `prod`      | `https://api.ema.co`       |
+| `<env>`     | `https://api.<env>.ema.co` |
 
 ### Config File (Advanced)
 
@@ -202,26 +205,33 @@ environments:
 
 ## MCP Tools
 
-| Tool | Purpose |
-|------|---------|
-| `persona` | **Primary**: AI Employee management (create/clone/modify/analyze/sanitize/optimize) |
-| `data` | **v2**: Simplified data management (list/upload/delete/sanitize/embedding) |
+| Tool        | Purpose                                                                             |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `persona`   | **Primary**: AI Employee management (create/clone/modify/analyze/sanitize/optimize) |
+| `data`      | **v2**: Simplified data management (list/upload/delete/sanitize/embedding)          |
 | `reference` | **v2**: All reference info (envs, actions, templates, patterns, concepts, guidance) |
-| `sync` | Sync across environments |
-| `knowledge` | Data sources (legacy, use `data`) |
-| `action` | Agent lookup (legacy, use `reference(type="actions")`) |
-| `template` | Patterns (legacy, use `reference`) |
-| `env` | Environments (legacy, use `reference(type="envs")`) |
-| `demo` | Demo/RAG document utilities |
+| `sync`      | Sync across environments                                                            |
+| `knowledge` | Data sources (legacy, use `data`)                                                   |
+| `action`    | Agent lookup (legacy, use `reference(type="actions")`)                              |
+| `template`  | Patterns (legacy, use `reference`)                                                  |
+| `env`       | Environments (legacy, use `reference(type="envs")`)                                 |
+| `demo`      | Demo/RAG document utilities                                                         |
 
 ### Common Workflows
 
 **Create new AI Employee:**
+
 ```typescript
-persona(input="IT helpdesk with KB search", type="chat", name="IT Support", preview=false)
+persona(
+  (input = "IT helpdesk with KB search"),
+  (type = "chat"),
+  (name = "IT Support"),
+  (preview = false),
+);
 ```
 
 **Modify existing AI Employee (LLM-Driven):**
+
 ```typescript
 // Step 1: Get current workflow
 workflow(mode="get", persona_id="abc-123")
@@ -239,22 +249,23 @@ workflow(mode="deploy", persona_id="abc-123", base_fingerprint="<fingerprint>",
 ```
 
 **Get reference info:**
+
 ```typescript
-catalog(type="actions", id="send_email")      // Get action details
-catalog(type="templates")                     // List templates
+catalog((type = "actions"), (id = "send_email")); // Get action details
+catalog((type = "templates")); // List templates
 ```
 
 ## Dynamic Resources
 
-| Resource | Purpose |
-|----------|---------|
-| `ema://catalog/agents` | Live action catalog from API |
-| `ema://catalog/templates` | Persona templates from API |
-| `ema://catalog/patterns` | Workflow patterns |
-| `ema://docs/usage-guide` | Complete usage guide (generated) |
-| `ema://guidance/rules` | Structured rules as JSON |
-| `ema://guidance/cursor-rule` | Export as Cursor .mdc rule |
-| `ema://guidance/server-instructions` | Server instructions text |
+| Resource                             | Purpose                          |
+| ------------------------------------ | -------------------------------- |
+| `ema://catalog/agents`               | Live action catalog from API     |
+| `ema://catalog/templates`            | Persona templates from API       |
+| `ema://catalog/patterns`             | Workflow patterns                |
+| `ema://docs/usage-guide`             | Complete usage guide (generated) |
+| `ema://guidance/rules`               | Structured rules as JSON         |
+| `ema://guidance/cursor-rule`         | Export as Cursor .mdc rule       |
+| `ema://guidance/server-instructions` | Server instructions text         |
 
 ---
 
@@ -263,6 +274,7 @@ catalog(type="templates")                     // List templates
 The MCP is fully self-contained—no external configuration files needed.
 
 **How it works:**
+
 - Server instructions are injected on MCP init (system prompt)
 - Tools include usage tips in their descriptions
 - Responses include `_tip` and `_next_step` fields with contextual guidance
@@ -270,6 +282,7 @@ The MCP is fully self-contained—no external configuration files needed.
 - `persona(..., analyze=true)` includes workflow_guidance with state-specific tips
 
 **For other services:**
+
 - Read `ema://guidance/rules` (JSON) for programmatic consumption
 - Read `ema://docs/usage-guide` (markdown) for documentation
 - Read `ema://guidance/cursor-rule` (.mdc) for IDE integration
@@ -321,14 +334,14 @@ const actions = await client.listActions();
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `EMA_BEARER_TOKEN` | Default bearer token |
+| Variable                 | Description                                               |
+| ------------------------ | --------------------------------------------------------- |
+| `EMA_BEARER_TOKEN`       | Default bearer token                                      |
 | `EMA_<ENV>_BEARER_TOKEN` | Token for specific environment (PROD, DEMO, DEV, STAGING) |
-| `EMA_API_KEY` | API key (auto-exchanges for JWT) |
-| `EMA_<ENV>_API_KEY` | API key for specific environment |
-| `EMA_ENV_NAME` | Default environment name |
-| `EMA_AGENT_SYNC_CONFIG` | Path to config file |
+| `EMA_API_KEY`            | API key (auto-exchanges for JWT)                          |
+| `EMA_<ENV>_API_KEY`      | API key for specific environment                          |
+| `EMA_ENV_NAME`           | Default environment name                                  |
+| `EMA_AGENT_SYNC_CONFIG`  | Path to config file                                       |
 
 ---
 
@@ -346,6 +359,7 @@ The token isn't set or isn't being passed to the MCP server:
 ### "Invalid API key" error
 
 You're using a bearer token (JWT) with an `_API_KEY` variable name:
+
 - Rename `EMA_X_API_KEY` to `EMA_X_BEARER_TOKEN`
 
 ### Only some environments detected
@@ -375,4 +389,13 @@ Some Cursor versions have issues with env var expansion. Workaround: paste token
 
 ## License
 
-MIT - see [LICENSE](LICENSE)
+This project is dual-licensed:
+
+- **AGPLv3** for open-source use
+- **Commercial license** for proprietary, hosted, or closed-source use
+
+If you intend to run this software in production, expose it over a
+network, or integrate it into a proprietary system, you must either
+comply with AGPLv3 or obtain a commercial license.
+
+See `LICENSE` and `LICENSE-COMMERCIAL.md` for details.

package/dist/mcp/domain/loop-detection.js

@@ -0,0 +1,97 @@
+/**
+ * Loop Detection for Workflow Graphs
+ *
+ * Extracted from workflow-execution-analyzer.ts — only the parts
+ * used by live validation code (detectLoops + LoopInfo).
+ */
+import { parseWorkflowDef } from "../knowledge.js";
+function buildGraphMaps(nodes) {
+    const forward = new Map();
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        nodeMap.set(node.id, node);
+        forward.set(node.id, new Set());
+    }
+    for (const node of nodes) {
+        if (node.incoming_edges) {
+            for (const edge of node.incoming_edges) {
+                const sourceId = edge.source_node_id;
+                forward.get(sourceId)?.add(node.id);
+            }
+        }
+    }
+    return { forward, nodeMap };
+}
+export function detectLoops(workflowDef) {
+    const nodes = parseWorkflowDef(workflowDef);
+    const loops = [];
+    const { forward, nodeMap } = buildGraphMaps(nodes);
+    const visited = new Set();
+    const recursionStack = new Set();
+    const path = [];
+    function dfs(nodeId) {
+        visited.add(nodeId);
+        recursionStack.add(nodeId);
+        path.push(nodeId);
+        for (const neighbor of (forward.get(nodeId) || [])) {
+            if (!visited.has(neighbor)) {
+                if (dfs(neighbor))
+                    return true;
+            }
+            else if (recursionStack.has(neighbor)) {
+                const cycleStart = path.indexOf(neighbor);
+                const cyclePath = path.slice(cycleStart);
+                cyclePath.push(neighbor);
+                loops.push({
+                    type: 'circular_dependency',
+                    nodes: cyclePath,
+                    description: `Circular dependency: ${cyclePath.join(' → ')}`,
+                    severity: 'critical',
+                    fixSuggestion: `Break the cycle by removing one edge.`,
+                });
+                return true;
+            }
+        }
+        path.pop();
+        recursionStack.delete(nodeId);
+        return false;
+    }
+    const trigger = nodes.find(n => n.action_name === 'trigger' || n.id === 'trigger');
+    if (trigger)
+        dfs(trigger.id);
+    for (const node of nodes) {
+        if (!visited.has(node.id))
+            dfs(node.id);
+    }
+    // Detect categorizer routing back to upstream (re-entry)
+    for (const node of nodes) {
+        if (node.action_name === 'chat_categorizer') {
+            const downstream = forward.get(node.id) || new Set();
+            const upstream = new Set();
+            function findUpstream(nId, depth = 0) {
+                if (depth > 20)
+                    return;
+                const nodeInfo = nodeMap.get(nId);
+                if (!nodeInfo?.incoming_edges)
+                    return;
+                for (const edge of nodeInfo.incoming_edges) {
+                    upstream.add(edge.source_node_id);
+                    findUpstream(edge.source_node_id, depth + 1);
+                }
+            }
+            findUpstream(node.id);
+            for (const downNode of downstream) {
+                if (upstream.has(downNode)) {
+                    loops.push({
+                        type: 'reentry_loop',
+                        nodes: [node.id, downNode],
+                        description: `Categorizer "${node.display_name || node.id}" routes to "${downNode}" which is upstream - can cause re-processing`,
+                        severity: 'warning',
+                        fixSuggestion: `Add state tracking or one-time-execution gate to prevent re-processing.`,
+                    });
+                }
+            }
+        }
+    }
+    return loops;
+}

package/dist/mcp/domain/proto-constraints.js

@@ -0,0 +1,284 @@
+/**
+ * Proto Constraint Miner
+ *
+ * Scans generated proto TypeScript files (`*_pb.ts`) for JSDoc comments
+ * containing constraint language (immutable, read-only, creation-only, etc.)
+ * and produces a structured report of field-level constraints.
+ *
+ * Used by:
+ * - `ema://docs/field-constraints` MCP resource (runtime)
+ * - `scripts/mine-proto-constraints.ts` CLI tool (ad-hoc)
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from "fs";
+import { join, relative, dirname } from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Default location of generated proto files relative to this module
+const DEFAULT_PROTOS_DIR = join(__dirname, "..", "..", "sdk", "generated", "protos");
+// ---------------------------------------------------------------------------
+// Constraint patterns to search for in JSDoc comments
+// ---------------------------------------------------------------------------
+const CONSTRAINT_PATTERNS = [
+    {
+        label: "immutable",
+        pattern: /\bimmutable\b|cannot be (updated|modified|changed|edited|deleted)\b/i,
+    },
+    {
+        label: "creation-only",
+        pattern: /should not be populated in creation|only (set|populated|used) (at|during|on|for) creation\b/i,
+    },
+    {
+        label: "read-only",
+        pattern: /\bread[- ]?only\b|not editable\b|cannot edit\b/i,
+    },
+    {
+        label: "inferred",
+        pattern: /will be inferred\b|automatically (set|populated|filled|computed)\b/i,
+    },
+    {
+        label: "deprecated",
+        pattern: /\[deprecated\s*=\s*true\]|@deprecated\b/i,
+    },
+    {
+        label: "conditional",
+        pattern: /only (set|used|populated|valid) (for|when|if|during)\b/i,
+    },
+    {
+        label: "do-not-populate",
+        pattern: /should not be populated\b|do not (set|populate|fill)\b/i,
+    },
+];
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Walk a directory recursively and yield file paths matching a predicate.
+ */
+function walkFiles(dir, predicate) {
+    const results = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+            results.push(...walkFiles(full, predicate));
+        }
+        else if (predicate(full)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Extract field identity from a `@generated from field:` annotation.
+ *
+ * The annotation format is:
+ *   `@generated from field: <type> <field_name> = <field_number>`
+ * The message context comes from the enclosing `Message<"...">` declaration.
+ */
+function parseGeneratedField(comment) {
+    // Field annotations: `@generated from field: <type> <name> = <number>`
+    const fieldMatch = comment.match(/@generated from field:\s*(?:optional\s+|repeated\s+)?(?:\S+\s+)?(\S+)\s*=\s*\d+/);
+    if (fieldMatch) {
+        const fullPath = fieldMatch[1];
+        const lastDot = fullPath.lastIndexOf(".");
+        if (lastDot > 0) {
+            return {
+                message: fullPath.substring(0, lastDot),
+                field: fullPath.substring(lastDot + 1),
+            };
+        }
+        return { message: "(unknown)", field: fullPath };
+    }
+    // RPC annotations: `@generated from rpc <service>.<method>`
+    const rpcMatch = comment.match(/@generated from rpc\s+(\S+)\.(\w+)/);
+    if (rpcMatch) {
+        return { message: rpcMatch[1], field: rpcMatch[2] };
+    }
+    // Message annotations: `@generated from message <name>`
+    const msgMatch = comment.match(/@generated from message\s+(\S+)/);
+    if (msgMatch) {
+        return { message: msgMatch[1], field: "(message)" };
+    }
+    // Enum value annotations: `@generated from enum value: <name> = <number>`
+    const enumMatch = comment.match(/@generated from enum value:\s+(\S+)\s*=\s*\d+/);
+    if (enumMatch) {
+        const fullPath = enumMatch[1];
+        const lastDot = fullPath.lastIndexOf(".");
+        if (lastDot > 0) {
+            return {
+                message: fullPath.substring(0, lastDot),
+                field: fullPath.substring(lastDot + 1),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Scan a single proto TypeScript file for constraint comments.
+ *
+ * Tracks the enclosing `Message<"...">` declaration to resolve field paths,
+ * since `@generated from field:` only contains `<type> <field_name> = <number>`,
+ * not the full qualified message path.
+ */
+function scanFile(filePath, protosDir) {
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n");
+    const constraints = [];
+    const relPath = relative(protosDir, filePath);
+    // Track the current enclosing message
+    let currentMessage = "(unknown)";
+    const messageContextRe = /Message<"([^"]+)">|@generated from message\s+(\S+)/;
+    let inComment = false;
+    let commentLines = [];
+    let commentStartLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Update message context from non-comment lines
+        if (!inComment) {
+            const msgMatch = line.match(messageContextRe);
+            if (msgMatch) {
+                currentMessage = msgMatch[1] ?? msgMatch[2] ?? currentMessage;
+            }
+        }
+        if (trimmed.startsWith("/**")) {
+            inComment = true;
+            commentLines = [trimmed];
+            commentStartLine = i + 1; // 1-indexed
+        }
+        else if (inComment) {
+            commentLines.push(trimmed);
+            if (trimmed.includes("*/")) {
+                inComment = false;
+                const fullComment = commentLines
+                    .map((l) => l.replace(/^\/?\*+\/?/g, "").trim())
+                    .filter((l) => l.length > 0)
+                    .join(" ");
+                // Update message context from inline comments
+                const inlineMsg = fullComment.match(/@generated from message\s+(\S+)/);
+                if (inlineMsg) {
+                    currentMessage = inlineMsg[1];
+                }
+                // Check against constraint patterns
+                const matchedLabels = [];
+                for (const { label, pattern } of CONSTRAINT_PATTERNS) {
+                    if (pattern.test(fullComment)) {
+                        matchedLabels.push(label);
+                    }
+                }
+                if (matchedLabels.length > 0) {
+                    const parsed = parseGeneratedField(fullComment);
+                    const afterComment = lines.slice(i + 1, i + 5).join(" ");
+                    const parsedAfter = parsed ?? parseGeneratedField(afterComment);
+                    if (parsedAfter) {
+                        const message = parsedAfter.message === "(unknown)"
+                            ? currentMessage
+                            : parsedAfter.message;
+                        constraints.push({
+                            message,
+                            field: parsedAfter.field,
+                            labels: matchedLabels,
+                            comment: fullComment.substring(0, 500),
+                            source: relPath,
+                            line: commentStartLine,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return constraints;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Mine all constraint comments from generated proto TypeScript files.
+ *
+ * @param protosDir - Override the directory to scan (defaults to `src/sdk/generated/protos/`)
+ */
+export function mineConstraints(protosDir) {
+    const dir = protosDir ?? DEFAULT_PROTOS_DIR;
+    if (!existsSync(dir)) {
+        return {
+            generated_at: new Date().toISOString(),
+            total_constraints: 0,
+            by_label: {},
+            constraints: [],
+        };
+    }
+    const files = walkFiles(dir, (f) => f.endsWith("_pb.ts"));
+    const allConstraints = [];
+    for (const file of files) {
+        allConstraints.push(...scanFile(file, dir));
+    }
+    // Sort by message then field for stable output
+    allConstraints.sort((a, b) => a.message === b.message
+        ? a.field.localeCompare(b.field)
+        : a.message.localeCompare(b.message));
+    // Count by label
+    const byLabel = {};
+    for (const c of allConstraints) {
+        for (const label of c.labels) {
+            byLabel[label] = (byLabel[label] ?? 0) + 1;
+        }
+    }
+    return {
+        generated_at: new Date().toISOString(),
+        total_constraints: allConstraints.length,
+        by_label: byLabel,
+        constraints: allConstraints,
+    };
+}
+/**
+ * Format a constraint report as human-readable markdown for the MCP resource.
+ * Filters out deprecated-only entries (those are in `ema://rules/deprecated-actions`).
+ */
+export function formatConstraintReport(report) {
+    // Filter to non-deprecated constraints (or constraints with labels beyond just deprecated)
+    const meaningful = report.constraints.filter((c) => c.labels.length > 1 ||
+        !c.labels.includes("deprecated"));
+    const sections = [
+        `# Proto Field Constraints`,
+        ``,
+        `> Auto-generated from proto definitions. ${meaningful.length} field constraints found (deprecated-only fields filtered out; see \`ema://rules/deprecated-actions\` for those).`,
+        ``,
+        `## Summary`,
+        ``,
+        `| Category | Count | Description |`,
+        `|----------|-------|-------------|`,
+        `| immutable | ${report.by_label["immutable"] ?? 0} | Fields that cannot be updated after creation |`,
+        `| creation-only | ${report.by_label["creation-only"] ?? 0} | Fields that should not be set in creation requests (auto-populated) |`,
+        `| read-only | ${report.by_label["read-only"] ?? 0} | Fields that cannot be edited by users |`,
+        `| inferred | ${report.by_label["inferred"] ?? 0} | Fields automatically computed from other data |`,
+        `| do-not-populate | ${report.by_label["do-not-populate"] ?? 0} | Fields that should not be set by callers |`,
+        `| conditional | ${report.by_label["conditional"] ?? 0} | Fields only used in specific contexts |`,
+        ``,
+    ];
+    // Group by category (excluding deprecated-only)
+    const byCategory = new Map();
+    for (const c of meaningful) {
+        for (const label of c.labels) {
+            if (label === "deprecated")
+                continue;
+            const list = byCategory.get(label) ?? [];
+            list.push(c);
+            byCategory.set(label, list);
+        }
+    }
+    for (const [category, items] of byCategory) {
+        sections.push(`## ${category}`);
+        sections.push(``);
+        for (const item of items) {
+            const labels = item.labels.filter((l) => l !== "deprecated").join(", ");
+            sections.push(`### \`${item.message}.${item.field}\` [${labels}]`);
+            sections.push(``);
+            sections.push(`${item.comment.substring(0, 300)}`);
+            sections.push(``);
+            sections.push(`_Source: ${item.source}:${item.line}_`);
+            sections.push(``);
+        }
+    }
+    return sections.join("\n");
+}

package/dist/mcp/domain/structural-rules.js

@@ -2,9 +2,8 @@
  * Structural Rules for LLM Context
  *
  * These rules encode the validation logic from:
- * - workflow-fixer.ts
- * - workflow-execution-analyzer.ts
  * - knowledge.ts (detectWorkflowIssues)
+ * - loop-detection.ts (cycle detection, extracted from workflow-execution-analyzer.ts)
  *
  * PURPOSE: Feed these to the LLM so it can self-validate during generation/transformation.
  * This is the "teach the LLM the rules" approach vs "fix after the fact".
@@ -105,9 +104,9 @@ export const STRUCTURAL_INVARIANTS = [
     {
         id: "hitl_has_both_paths",
         name: "HITL Must Have Success AND Failure Paths",
-        rule: "A general_hitl node has two outcomes: approval and rejection. Both MUST have downstream handlers.",
+        rule: "Legacy general_hitl nodes (if present) have two outcomes: approval and rejection. Both MUST have downstream handlers. Note: general_hitl is NOT deployable for new workflows — HITL is a flag on entity_extraction_with_documents and send_email_agent only.",
         violation: "HITL 'approval' only has success path - rejections hang",
-        fix: "Add handler for hitl.approval_decision = 'reject' (typically fixed_response with apology)",
+        fix: "For legacy workflows: add handler for hitl.approval_decision = 'reject'. For new workflows: use HITL flag on send_email_agent or entity_extraction_with_documents instead.",
         severity: "critical",
     },
     // ═══════════════════════════════════════════════════════════════════════════
@@ -180,6 +179,14 @@ export const STRUCTURAL_INVARIANTS = [
         fix: "Connect the output to a downstream node, map to WORKFLOW_OUTPUT, or remove the node if unused",
         severity: "warning",
     },
+    {
+        id: "all_gated_responses_wired",
+        name: "All Gated Response Nodes Must Reach Output",
+        rule: "When a categorizer gates multiple response nodes via runIf/trigger_when, EVERY gated response node must have its output mapped to WORKFLOW_OUTPUT. A gated response node that executes but isn't wired to output silently discards its result.",
+        violation: "Categorizer routes to get_respond, schedule_respond, reschedule_respond — but only get_respond.response_with_sources is mapped to WORKFLOW_OUTPUT. Schedule and reschedule responses are silently lost.",
+        fix: "Map ALL gated response node outputs to WORKFLOW_OUTPUT, or consolidate into a single response node that receives the category as a named_input",
+        severity: "critical",
+    },
 ];
 export const EXECUTION_RULES = [
     {
@@ -330,7 +337,7 @@ BEFORE finalizing any workflow modification, verify these rules:
 
 ### HITL Rules
 
-10. **Both Paths Required**: general_hitl needs handlers for both approval AND rejection.
+10. **Both Paths Required**: Legacy general_hitl nodes need handlers for both approval AND rejection. Note: general_hitl is NOT deployable — HITL is a flag on entity_extraction_with_documents and send_email_agent only.
 
 ### Raw workflow_def Format Rules (CRITICAL)