@lexq/cli 0.1.22 → 0.1.25

package/AGENTS.md

@@ -7,7 +7,7 @@
 LexQ CLI (`@lexq/cli`, binary: `lexq`) manages a policy execution engine. Policies are business rules (if-then) that
 evaluate input facts and produce actions (discounts, blocks, notifications, etc.).
 
-The CLI also doubles as an **MCP server** — run `lexq serve --mcp` to expose 62 tools to any MCP-compatible AI client.
+The CLI also doubles as an **MCP server** — run `lexq serve --mcp` to expose 63 tools to any MCP-compatible AI client.
 
 This file tells you how to use the CLI as an AI agent.
 
@@ -35,7 +35,7 @@ Detailed documentation lives in the `skills/` directory. **Read the relevant ski
 | **Shared**     | `skills/lexq-shared/SKILL.md`     | Core concepts, auth, workflow, error codes. **Read first.**       |
 | **Groups**     | `skills/lexq-groups/SKILL.md`     | Policy groups, conflict resolution, A/B testing                   |
 | **Rules**      | `skills/lexq-rules/SKILL.md`      | Condition syntax, action types, mutex, examples                   |
-| **Simulation** | `skills/lexq-simulation/SKILL.md` | Dry run, batch simulation, compare                                |
+| **Simulation** | `skills/lexq-simulation/SKILL.md` | Dry run, Impact Simulation, compare                               |
 | **Execution**  | `skills/lexq-execution/SKILL.md`  | History, stats, failure logs, integrations, webhook subscriptions |
 | **Recipes**    | `skills/lexq-recipes/SKILL.md`    | End-to-end workflows (copy-paste ready)                           |
 
@@ -142,7 +142,7 @@ Connect via:
 - **Cloud:** `https://mcp.lexq.io` (OAuth 2.1)
 - **Local stdio:** `npx @lexq/cli serve --mcp`
 
-62 tools mirror the CLI command inventory.
+63 tools mirror the CLI command inventory.
 
 ## Troubleshooting
 

package/CONTEXT.md

@@ -7,7 +7,7 @@ simulation, deploy to production, and execute via REST API — all without modif
 
 **Core differentiators:**
 
-- Pre-deploy simulation against real data
+- Impact Simulation against real data
 - A/B testing for rule versions
 - Git-style versioning with full audit trail
 - Platform event webhooks for deployment lifecycle notifications
@@ -91,7 +91,7 @@ Tenant
 
 ### Action Types
 
-`DISCOUNT`, `POINT`, `COUPON_ISSUE`, `BLOCK`, `NOTIFICATION`, `WEBHOOK`, `SET_FACT`, `ADD_TAG`
+`MUTATE_FACT`, `INCREMENT_FACT`, `EMIT_EVENT`, `BLOCK`, `EMIT_NOTIFICATION`, `EMIT_WEBHOOK`, `SET_FACT`, `ADD_TAG`
 
 ### Conflict Resolution Modes
 

package/README.md

@@ -1,8 +1,8 @@
 # LexQ CLI
 
-> **The decision platform for engineering teams.**
+> **The Decision Operations Platform for engineering teams.**
 > CLI and MCP server for [LexQ](https://lexq.io) — move business rules out of
-> your deploy pipeline, prove every change with simulation, and ship without
+> your deploy pipeline, prove every change with Impact Simulation, and ship without
 > a git push.
 
 **[Website](https://lexq.io)** · **[Docs](https://docs.lexq.io)** · **[Console](https://console.lexq.io)**
@@ -24,7 +24,7 @@ that changes weekly shouldn't live in code that ships quarterly.
 
 **LexQ separates the two.** Rules live outside your application. You change
 them in a visual console or through this CLI. You prove every change with
-batch simulation against real execution data. You deploy without touching
+Impact Simulation against real execution data. You deploy without touching
 your codebase.
 
 Every decision leaves a full audit trace.
@@ -71,8 +71,14 @@ lexq rules create --group-id <GROUP_ID> --version-id <VERSION_ID> --json '{
     "valueType": "STRING"
   },
   "actions": [{
-    "type": "DISCOUNT",
-    "parameters": {"method":"PERCENTAGE","rate":10,"refVar":"payment_amount"}
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "method": "PERCENTAGE",
+      "rate": 10,
+      "refVar": "payment_amount",
+      "operator": "SUB",
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
   }]
 }'
 
@@ -176,7 +182,7 @@ skills/
 ├── lexq-shared/SKILL.md       Core concepts, auth, workflow
 ├── lexq-groups/SKILL.md       Policy groups, conflict resolution, A/B testing
 ├── lexq-rules/SKILL.md        Condition syntax, action types, mutex
-├── lexq-simulation/SKILL.md   Dry run, batch simulation, compare
+├── lexq-simulation/SKILL.md   Dry run, Impact Simulation, compare
 ├── lexq-execution/SKILL.md    Execution history, stats, failure logs
 └── lexq-recipes/SKILL.md      End-to-end recipes
 

package/dist/index.js

@@ -3296,7 +3296,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_action_metadata",
     {
       title: "Get Action Runtime Fact Metadata",
-      description: "Retrieve runtime Facts metadata for each Action type. Shows which Facts are required as input, produced as output, or consumed at runtime by each Action (DISCOUNT, SEND_SMS, ADD_TAG, SET_FACT, etc.). Use this BEFORE designing rules to understand which Action produces which output variables (e.g., DISCOUNT produces last_discount_amount). Data is static and changes only on engine deployment \u2014 safe to cache in-session.",
+      description: "Retrieve runtime Facts metadata for each Action type. Shows which Facts are required as input, produced as output, or consumed at runtime by each Action (MUTATE_FACT, INCREMENT_FACT, EMIT_EVENT, BLOCK, EMIT_NOTIFICATION, EMIT_WEBHOOK, SET_FACT, ADD_TAG). Use this BEFORE designing rules to understand which Action mutates which fact (e.g., MUTATE_FACT mutates the refVar fact and auto-generates {fact_name}__delta in generatedVariables). Data is static and changes only on engine deployment \u2014 safe to cache in-session.",
       inputSchema: {}
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -3447,8 +3447,8 @@ function registerAnalyticsTools(server, callApi) {
         
         Returns:
           inputFacts        — normalized input facts
-          mutatedFacts      — input facts changed by rule actions (e.g. DISCOUNT mutates payment_amount)
-          generatedVariables — new variables created by rules (e.g. last_discount_amount)
+          mutatedFacts      — input facts changed by rule actions (e.g. MUTATE_FACT mutates payment_amount)
+          generatedVariables — system-generated values; every fact in mutatedFacts gets a paired {fact_name}__delta key (signed difference)
           executionTraces   — per-rule match status
           decisionTraces    — per-rule decision (SELECTED / NO_MATCH / BLOCKED / etc.)
         
@@ -3509,7 +3509,7 @@ function registerAnalyticsTools(server, callApi) {
     {
       title: "Start Simulation",
       description: dedent14`
-        Start a batch simulation against historical or uploaded data.
+        Start an Impact Simulation against historical or uploaded data.
 
         dataset.type: "HISTORICAL" or "UPLOADED"
         dataset.source (when HISTORICAL): "EXECUTION_LOGS"
@@ -3667,7 +3667,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_get",
     {
       title: "Get Execution Detail",
-      description: "Get full execution detail including request facts, result traces, and decision traces.",
+      description: "Get full execution detail including inputFacts, mutatedFacts, generatedVariables, executionTraces, and decisionTraces.",
       inputSchema: {
         traceId: z7.string().describe("Trace ID from execution history")
       }
@@ -3910,6 +3910,51 @@ function registerWebhookSubscriptionTools(server, callApi) {
   );
 }
 
+// src/mcp/tools/domain-templates.ts
+import { z as z11 } from "zod";
+function registerDomainTemplateTools(server, callApi) {
+  server.registerTool(
+    "lexq_domain_templates_list",
+    {
+      title: "List Domain Templates",
+      description: "List all domain templates. A domain template is a curated, industry-specific starter pack of fact definitions and sample rules (e.g. ECOMMERCE). Each entry reports its key, status (ACTIVE or COMING_SOON), and a summary of what it provisions. Call this before preview or apply to discover which templates can currently be applied.",
+      inputSchema: {}
+    },
+    async () => callApi("GET", "domain-templates")
+  );
+  server.registerTool(
+    "lexq_domain_templates_preview",
+    {
+      title: "Preview Domain Template",
+      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers, the sample rules it creates, and an apply plan. This is a read-only dry run \u2014 nothing is created. Only ACTIVE templates can be previewed.",
+      inputSchema: {
+        template: z11.string().describe(
+          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see available keys \u2014 currently only ECOMMERCE is ACTIVE."
+        )
+      }
+    },
+    async ({ template }) => callApi("GET", `domain-templates/${template}/preview`)
+  );
+  server.registerTool(
+    "lexq_domain_templates_apply",
+    {
+      title: "Apply Domain Template",
+      description: "Apply a domain template to the current tenant. Creates the template's fact definitions and a new policy group pre-populated with its sample rules as a DRAFT version. Existing facts are skipped \u2014 apply is additive and never overwrites existing schema. Run lexq_domain_templates_preview first to review what will be created. Only ACTIVE templates can be applied.",
+      inputSchema: {
+        template: z11.string().describe("Domain template key to apply (e.g. ECOMMERCE)."),
+        customName: z11.string().optional().describe(
+          "Optional custom name for the policy group that gets created. If omitted, the template's default name is used."
+        )
+      }
+    },
+    async ({ template, customName }) => {
+      const body = {};
+      if (customName !== void 0) body.customName = customName;
+      return callApi("POST", `domain-templates/${template}/apply`, { body });
+    }
+  );
+}
+
 // src/mcp/register.ts
 function registerAllTools(server, callApi) {
   registerStatusTools(server, callApi);
@@ -3922,6 +3967,7 @@ function registerAllTools(server, callApi) {
   registerHistoryTools(server, callApi);
   registerIntegrationTools(server, callApi);
   registerLogTools(server, callApi);
+  registerDomainTemplateTools(server, callApi);
   registerWebhookSubscriptionTools(server, callApi);
 }
 
@@ -3979,6 +4025,137 @@ function registerServeCommand(program) {
   });
 }
 
+// src/commands/domain-templates.ts
+import "commander";
+import dedent16 from "dedent";
+function registerDomainTemplateCommands(program) {
+  const templates = program.command("domain-templates").description("Browse and apply domain templates").addHelpText(
+    "after",
+    dedent16`
+
+        A domain template is an industry-specific starter pack of fact
+        definitions and sample rules. Applying one provisions a ready-to-use
+        policy group so you start from a working baseline instead of an
+        empty schema.
+
+        Commands:
+          list      List available domain templates
+          preview   Preview the facts and rules a template provisions
+          apply     Apply a template to the current tenant
+
+        Workflow: list → preview → apply
+        Currently available: ECOMMERCE  (FINTECH, SAAS — coming soon)
+      `
+  );
+  templates.command("list").description("List available domain templates").action(async () => {
+    try {
+      const globalOpts = program.opts();
+      const format = globalOpts.format ?? "json";
+      const data = await apiRequest("GET", "domain-templates", {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
+      });
+      if (format === "table") {
+        printTable(
+          ["Template", "Name", "Facts", "Rules", "Available"],
+          data.map((t) => [
+            t.template,
+            t.displayName,
+            String(t.factCount),
+            String(t.ruleCount),
+            t.isAvailable ? "\u2713" : "\u2013"
+          ]),
+          { truncate: 32 }
+        );
+      } else {
+        printJson(data);
+      }
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  templates.command("preview").description("Preview what a domain template provisions").requiredOption("--template <key>", "Domain template key (e.g. ECOMMERCE)").addHelpText(
+    "after",
+    dedent16`
+
+        Read-only dry run — shows the fact definitions and sample rules the
+        template will create. Nothing is provisioned.
+
+        Example:
+          $ lexq domain-templates preview --template ECOMMERCE
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const data = await apiRequest(
+        "GET",
+        `domain-templates/${opts.template}/preview`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose
+        }
+      );
+      printJson(data);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  templates.command("apply").description("Apply a domain template to the current tenant").requiredOption("--template <key>", "Domain template key (e.g. ECOMMERCE)").option("--name <n>", "Custom name for the policy group that gets created").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent16`
+
+        Creates the template's fact definitions and a new DRAFT policy group
+        populated with its sample rules. Existing facts are skipped — apply is
+        additive and never overwrites your schema.
+
+        Run "preview" first to review what will be created.
+
+        Example:
+          $ lexq domain-templates apply --template ECOMMERCE
+          $ lexq domain-templates apply --template ECOMMERCE --name "My Store Policy"
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      if (!opts.force) {
+        const { createInterface: createInterface2 } = await import("readline/promises");
+        const rl = createInterface2({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(
+          `Apply domain template ${opts.template} to the current tenant? [y/N] `
+        );
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Cancelled.");
+          return;
+        }
+      }
+      const body = {};
+      if (opts.name) body.customName = opts.name;
+      const data = await apiRequest(
+        "POST",
+        `domain-templates/${opts.template}/apply`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          body
+        }
+      );
+      printJson(data);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+}
+
 // src/cli.ts
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 function getVersion2() {
@@ -3991,13 +4168,16 @@ function getVersion2() {
 }
 function createCli() {
   const program = new Command();
-  program.name("lexq").description("LexQ CLI \u2014 manage policies, simulate rules, and deploy from the terminal.").version(getVersion2(), "-V, --version").option("--format <format>", "Output format: json or table", "json").option("--api-key <key>", "Override stored API key").option("--base-url <url>", "Override API base URL").option("--dry-run", "Preview the HTTP request without executing").option("--verbose", "Show request/response details").option("--no-color", "Disable colored output");
+  program.name("lexq").description(
+    "Command-line interface for the LexQ Decision Operations Platform. Manage policies, run Impact Simulation, and deploy from your terminal."
+  ).version(getVersion2(), "-V, --version").option("--format <format>", "Output format: json or table", "json").option("--api-key <key>", "Override stored API key").option("--base-url <url>", "Override API base URL").option("--dry-run", "Preview the HTTP request without executing").option("--verbose", "Show request/response details").option("--no-color", "Disable colored output");
   registerAuthCommands(program);
   registerStatusCommand(program);
   registerGroupCommands(program);
   registerVersionCommands(program);
   registerRuleCommands(program);
   registerFactCommands(program);
+  registerDomainTemplateCommands(program);
   registerDeployCommands(program);
   registerAnalyticsCommands(program);
   registerHistoryCommands(program);

package/dist/mcp/register.d.ts

@@ -27,7 +27,7 @@ type CallApi = (method: string, path: string, opts?: {
 declare function paginationParams(page?: number, size?: number): Record<string, string>;
 
 /**
- * Registers all 62 MCP tools on the given server.
+ * Registers all 66 MCP tools on the given server.
  *
  * @param server - McpServer instance
  * @param callApi - API caller function (config-based for CLI, Bearer-based for HTTP)

package/dist/mcp/register.js

@@ -465,7 +465,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_action_metadata",
     {
       title: "Get Action Runtime Fact Metadata",
-      description: "Retrieve runtime Facts metadata for each Action type. Shows which Facts are required as input, produced as output, or consumed at runtime by each Action (DISCOUNT, SEND_SMS, ADD_TAG, SET_FACT, etc.). Use this BEFORE designing rules to understand which Action produces which output variables (e.g., DISCOUNT produces last_discount_amount). Data is static and changes only on engine deployment \u2014 safe to cache in-session.",
+      description: "Retrieve runtime Facts metadata for each Action type. Shows which Facts are required as input, produced as output, or consumed at runtime by each Action (MUTATE_FACT, INCREMENT_FACT, EMIT_EVENT, BLOCK, EMIT_NOTIFICATION, EMIT_WEBHOOK, SET_FACT, ADD_TAG). Use this BEFORE designing rules to understand which Action mutates which fact (e.g., MUTATE_FACT mutates the refVar fact and auto-generates {fact_name}__delta in generatedVariables). Data is static and changes only on engine deployment \u2014 safe to cache in-session.",
       inputSchema: {}
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -616,8 +616,8 @@ function registerAnalyticsTools(server, callApi) {
         
         Returns:
           inputFacts        — normalized input facts
-          mutatedFacts      — input facts changed by rule actions (e.g. DISCOUNT mutates payment_amount)
-          generatedVariables — new variables created by rules (e.g. last_discount_amount)
+          mutatedFacts      — input facts changed by rule actions (e.g. MUTATE_FACT mutates payment_amount)
+          generatedVariables — system-generated values; every fact in mutatedFacts gets a paired {fact_name}__delta key (signed difference)
           executionTraces   — per-rule match status
           decisionTraces    — per-rule decision (SELECTED / NO_MATCH / BLOCKED / etc.)
         
@@ -678,7 +678,7 @@ function registerAnalyticsTools(server, callApi) {
     {
       title: "Start Simulation",
       description: dedent2`
-        Start a batch simulation against historical or uploaded data.
+        Start an Impact Simulation against historical or uploaded data.
 
         dataset.type: "HISTORICAL" or "UPLOADED"
         dataset.source (when HISTORICAL): "EXECUTION_LOGS"
@@ -836,7 +836,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_get",
     {
       title: "Get Execution Detail",
-      description: "Get full execution detail including request facts, result traces, and decision traces.",
+      description: "Get full execution detail including inputFacts, mutatedFacts, generatedVariables, executionTraces, and decisionTraces.",
       inputSchema: {
         traceId: z7.string().describe("Trace ID from execution history")
       }
@@ -1109,6 +1109,51 @@ function registerWebhookSubscriptionTools(server, callApi) {
   );
 }
 
+// src/mcp/tools/domain-templates.ts
+import { z as z11 } from "zod";
+function registerDomainTemplateTools(server, callApi) {
+  server.registerTool(
+    "lexq_domain_templates_list",
+    {
+      title: "List Domain Templates",
+      description: "List all domain templates. A domain template is a curated, industry-specific starter pack of fact definitions and sample rules (e.g. ECOMMERCE). Each entry reports its key, status (ACTIVE or COMING_SOON), and a summary of what it provisions. Call this before preview or apply to discover which templates can currently be applied.",
+      inputSchema: {}
+    },
+    async () => callApi("GET", "domain-templates")
+  );
+  server.registerTool(
+    "lexq_domain_templates_preview",
+    {
+      title: "Preview Domain Template",
+      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers, the sample rules it creates, and an apply plan. This is a read-only dry run \u2014 nothing is created. Only ACTIVE templates can be previewed.",
+      inputSchema: {
+        template: z11.string().describe(
+          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see available keys \u2014 currently only ECOMMERCE is ACTIVE."
+        )
+      }
+    },
+    async ({ template }) => callApi("GET", `domain-templates/${template}/preview`)
+  );
+  server.registerTool(
+    "lexq_domain_templates_apply",
+    {
+      title: "Apply Domain Template",
+      description: "Apply a domain template to the current tenant. Creates the template's fact definitions and a new policy group pre-populated with its sample rules as a DRAFT version. Existing facts are skipped \u2014 apply is additive and never overwrites existing schema. Run lexq_domain_templates_preview first to review what will be created. Only ACTIVE templates can be applied.",
+      inputSchema: {
+        template: z11.string().describe("Domain template key to apply (e.g. ECOMMERCE)."),
+        customName: z11.string().optional().describe(
+          "Optional custom name for the policy group that gets created. If omitted, the template's default name is used."
+        )
+      }
+    },
+    async ({ template, customName }) => {
+      const body = {};
+      if (customName !== void 0) body.customName = customName;
+      return callApi("POST", `domain-templates/${template}/apply`, { body });
+    }
+  );
+}
+
 // src/mcp/register.ts
 function registerAllTools(server, callApi) {
   registerStatusTools(server, callApi);
@@ -1121,6 +1166,7 @@ function registerAllTools(server, callApi) {
   registerHistoryTools(server, callApi);
   registerIntegrationTools(server, callApi);
   registerLogTools(server, callApi);
+  registerDomainTemplateTools(server, callApi);
   registerWebhookSubscriptionTools(server, callApi);
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.22",
+  "version": "0.1.25",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -23,6 +23,14 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
   "keywords": [
     "lexq",
     "rule-engine",
@@ -43,6 +51,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "packageManager": "pnpm@10.28.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
     "cli-table3": "^0.6.5",
@@ -60,12 +69,5 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.24.0"
-  },
-  "scripts": {
-    "dev": "tsup --watch",
-    "build": "tsup",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js"
   }
-}
+}

package/skills/lexq-execution/SKILL.md

@@ -4,7 +4,8 @@
 
 ## Overview
 
-Once policies are deployed, the engine evaluates incoming facts against live rules. This skill covers **observing** production behavior: execution history, statistics, failure logs, and integrations.
+Once policies are deployed, the engine evaluates incoming facts against live rules. This skill covers **observing**
+production behavior: execution history, statistics, failure logs, and integrations.
 
 ## 1. Execution History
 
@@ -16,23 +17,23 @@ lexq history list --page 0 --size 20
 
 Filter options:
 
-| Flag | Description | Example |
-|---|---|---|
-| `--trace-id <id>` | Filter by trace ID | `--trace-id abc123` |
-| `--group-id <id>` | Filter by policy group | `--group-id <gid>` |
-| `--version-id <id>` | Filter by version | `--version-id <vid>` |
-| `--status <status>` | Filter by status | `--status SUCCESS` |
-| `--start-date <date>` | Start date (ISO) | `--start-date 2025-01-01` |
-| `--end-date <date>` | End date (ISO) | `--end-date 2025-01-31` |
+| Flag                  | Description            | Example                   |
+|-----------------------|------------------------|---------------------------|
+| `--trace-id <id>`     | Filter by trace ID     | `--trace-id abc123`       |
+| `--group-id <id>`     | Filter by policy group | `--group-id <gid>`        |
+| `--version-id <id>`   | Filter by version      | `--version-id <vid>`      |
+| `--status <status>`   | Filter by status       | `--status SUCCESS`        |
+| `--start-date <date>` | Start date (ISO)       | `--start-date 2025-01-01` |
+| `--end-date <date>`   | End date (ISO)         | `--end-date 2025-01-31`   |
 
 ### Execution Statuses
 
-| Status | Meaning |
-|---|---|
-| `SUCCESS` | At least one rule matched and actions executed |
-| `NO_MATCH` | No rules matched the input facts |
-| `ERROR` | Engine error during evaluation |
-| `TIMEOUT` | Execution exceeded time limit |
+| Status     | Meaning                                        |
+|------------|------------------------------------------------|
+| `SUCCESS`  | At least one rule matched and actions executed |
+| `NO_MATCH` | No rules matched the input facts               |
+| `ERROR`    | Engine error during evaluation                 |
+| `TIMEOUT`  | Execution exceeded time limit                  |
 
 ### Get Execution Detail
 
@@ -40,7 +41,7 @@ Filter options:
 lexq history get --id <executionId>
 ```
 
-Returns full detail including `requestFacts`, `resultTraces`, and `decisionTraces`.
+Returns full detail including `inputFacts`, `executionTraces`, and `decisionTraces`.
 
 ### Execution Statistics
 
@@ -62,6 +63,7 @@ Returns KPI summary:
 ```
 
 Use stats to monitor:
+
 - **Success rate** — should be close to 1.0 for well-configured policies
 - **Average latency** — should be single-digit ms under normal load
 - **No-match count** — high values may indicate missing rules or incomplete fact definitions
@@ -78,14 +80,14 @@ lexq logs list --page 0 --size 20
 
 Filter options:
 
-| Flag | Description | Values |
-|---|---|---|
-| `--category <cat>` | Task category | `INTEGRATION`, `INTERNAL` |
-| `--task-type <type>` | Task type | `COUPON_ISSUE`, `POINT_EARN`, `NOTIFICATION_SEND`, `WEBHOOK_EXECUTE` |
-| `--status <status>` | Log status | `PENDING`, `RESOLVED`, `IGNORED` |
-| `--keyword <kw>` | Search in refId, refSubId, errorMessage | any string |
-| `--start-date <date>` | Start date (ISO) | `2025-01-01` |
-| `--end-date <date>` | End date (ISO) | `2025-01-31` |
+| Flag                  | Description                             | Values                                                               |
+|-----------------------|-----------------------------------------|----------------------------------------------------------------------|
+| `--category <cat>`    | Task category                           | `INTEGRATION`, `INTERNAL`                                            |
+| `--task-type <type>`  | Task type                               | `COUPON_ISSUE`, `POINT_EARN`, `NOTIFICATION_SEND`, `WEBHOOK_EXECUTE` |
+| `--status <status>`   | Log status                              | `PENDING`, `RESOLVED`, `IGNORED`                                     |
+| `--keyword <kw>`      | Search in refId, refSubId, errorMessage | any string                                                           |
+| `--start-date <date>` | Start date (ISO)                        | `2025-01-01`                                                         |
+| `--end-date <date>`   | End date (ISO)                          | `2025-01-31`                                                         |
 
 ### Get Failure Log Detail
 

package/skills/lexq-recipes/SKILL.md

@@ -35,8 +35,14 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     "valueType": "NUMBER"
   },
   "actions": [{
-    "type": "DISCOUNT",
-    "parameters": { "method": "PERCENTAGE", "rate": 20, "refVar": "payment_amount" }
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 20,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
   }]
 }'
 
@@ -52,8 +58,14 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     ]
   },
   "actions": [{
-    "type": "DISCOUNT",
-    "parameters": { "method": "PERCENTAGE", "rate": 10, "refVar": "payment_amount" }
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 10,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
   }]
 }'
 
@@ -68,17 +80,23 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     "valueType": "NUMBER"
   },
   "actions": [{
-    "type": "DISCOUNT",
-    "parameters": { "method": "PERCENTAGE", "rate": 5, "refVar": "payment_amount" }
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 5,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
   }]
 }'
 
 # 5. Validate
 lexq analytics dry-run --version-id <vid> --debug --mock --json '{"facts":{"payment_amount":600000}}'
-# Expected: 20% discount → 120000
+# Expected: mutatedFacts.payment_amount = 480000, generatedVariables.payment_amount__delta = -120000
 
 lexq analytics dry-run --version-id <vid> --debug --mock --json '{"facts":{"payment_amount":200000}}'
-# Expected: 10% discount → 20000
+# Expected: mutatedFacts.payment_amount = 180000, generatedVariables.payment_amount__delta = -20000
 
 # 6. Deploy
 lexq deploy publish --group-id <gid> --version-id <vid> --memo "Tiered discount v1"
@@ -160,8 +178,14 @@ lexq versions clone --group-id <gid> --version-id <v1id>
 # 2. Update the discount rule in v2
 lexq rules update --group-id <gid> --version-id <v2id> --id <ruleId> --json '{
   "actions": [{
-    "type": "DISCOUNT",
-    "parameters": { "method": "PERCENTAGE", "rate": 15, "refVar": "payment_amount" }
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 15,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
   }]
 }'
 
@@ -205,10 +229,11 @@ lexq versions create --group-id <gid> --json '{"commitMessage": "Points program
 
 lexq facts create --key purchase_amount --name "Purchase Amount" --type NUMBER --required
 lexq facts create --key is_first_purchase --name "First Purchase" --type BOOLEAN
+lexq facts create --key total_points --name "Total Points" --type NUMBER
 
-# Double points for first purchase
+# Bonus points for first purchase (fixed 200)
 lexq rules create --group-id <gid> --version-id <vid> --json '{
-  "name": "First Purchase Double Points",
+  "name": "First Purchase Bonus Points",
   "priority": 0,
   "condition": {
     "type": "SINGLE",
@@ -218,12 +243,30 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     "valueType": "BOOLEAN"
   },
   "actions": [
-    { "type": "POINT", "parameters": { "amount": 200, "pointType": "BONUS" } },
-    { "type": "NOTIFICATION", "parameters": { "channel": "PUSH", "template": "welcome_points" } }
+    {
+      "type": "INCREMENT_FACT",
+      "parameters": {
+        "targetVar": "total_points",
+        "method": "AMOUNT",
+        "value": 200,
+        "rounding": { "mode": "HALF_UP", "scale": 0 }
+      }
+    },
+    {
+      "type": "EMIT_NOTIFICATION",
+      "parameters": {
+        "integrationId": "<notification-integration-uuid>",
+        "target": "user_id",
+        "notificationPayload": {
+          "channel": "PUSH",
+          "templateId": "welcome_points"
+        }
+      }
+    }
   ]
 }'
 
-# Standard points (1 point per 1000 KRW)
+# Standard points: 0.1% of purchase_amount = 1 point per 1000 KRW
 lexq rules create --group-id <gid> --version-id <vid> --json '{
   "name": "Standard Purchase Points",
   "priority": 1,
@@ -235,7 +278,16 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     "valueType": "NUMBER"
   },
   "actions": [
-    { "type": "SET_FACT", "parameters": { "key": "points_earned", "value": "purchase_amount / 1000" } }
+    {
+      "type": "INCREMENT_FACT",
+      "parameters": {
+        "targetVar": "total_points",
+        "refVar": "purchase_amount",
+        "method": "PERCENTAGE",
+        "rate": 0.1,
+        "rounding": { "mode": "FLOOR", "scale": 0 }
+      }
+    }
   ]
 }'
 ```
@@ -267,7 +319,17 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     "valueType": "NUMBER"
   },
   "actions": [
-    { "type": "WEBHOOK", "parameters": { "url": "https://api.example.com/webhooks/orders", "method": "POST" } },
+    {
+      "type": "EMIT_WEBHOOK",
+      "parameters": {
+        "url": "https://api.example.com/webhooks/orders",
+        "payloadTemplate": {
+          "event": "rule_matched",
+          "rule": "{{ruleName}}",
+          "amount": "{{output.order_total}}"
+        }
+      }
+    },
     { "type": "ADD_TAG", "parameters": { "tag": "large_order" } }
   ]
 }'
@@ -289,7 +351,16 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
   "condition": {
     "type": "SINGLE", "field": "customer_tier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING"
   },
-  "actions": [{ "type": "DISCOUNT", "parameters": { "method": "PERCENTAGE", "rate": 20, "refVar": "payment_amount" } }]
+  "actions": [{
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 20,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
+  }]
 }'
 
 lexq rules create --group-id <gid> --version-id <vid> --json '{
@@ -301,7 +372,16 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
   "condition": {
     "type": "SINGLE", "field": "payment_amount", "operator": "GREATER_THAN_OR_EQUAL", "value": 50000, "valueType": "NUMBER"
   },
-  "actions": [{ "type": "DISCOUNT", "parameters": { "method": "PERCENTAGE", "rate": 15, "refVar": "payment_amount" } }]
+  "actions": [{
+    "type": "MUTATE_FACT",
+    "parameters": {
+      "refVar": "payment_amount",
+      "method": "PERCENTAGE",
+      "operator": "SUB",
+      "rate": 15,
+      "rounding": { "mode": "HALF_UP", "scale": 0 }
+    }
+  }]
 }'
 
 # If a VIP customer pays 50000+, only the 20% VIP discount fires (priority 0 wins).
@@ -322,7 +402,16 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
   "condition": {
     "type": "SINGLE", "field": "user_region", "operator": "IN", "value": ["KR"], "valueType": "LIST_STRING"
   },
-  "actions": [{ "type": "COUPON_ISSUE", "parameters": { "couponId": "KR_WELCOME_2025", "expiryDays": 30 } }]
+  "actions": [{
+    "type": "EMIT_EVENT",
+    "parameters": {
+      "integrationId": "<coupon-integration-uuid>",
+      "eventPayload": {
+        "couponId": "KR_WELCOME_2025",
+        "expiryDays": 30
+      }
+    }
+  }]
 }'
 
 lexq rules create --group-id <gid> --version-id <vid> --json '{
@@ -331,7 +420,16 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
   "condition": {
     "type": "SINGLE", "field": "user_region", "operator": "IN", "value": ["US"], "valueType": "LIST_STRING"
   },
-  "actions": [{ "type": "COUPON_ISSUE", "parameters": { "couponId": "US_WELCOME_2025", "expiryDays": 14 } }]
+  "actions": [{
+    "type": "EMIT_EVENT",
+    "parameters": {
+      "integrationId": "<coupon-integration-uuid>",
+      "eventPayload": {
+        "couponId": "US_WELCOME_2025",
+        "expiryDays": 14
+      }
+    }
+  }]
 }'
 ```
 

package/skills/lexq-rules/SKILL.md

@@ -4,7 +4,8 @@
 
 ## Overview
 
-A **Policy Rule** is a condition → actions pair within a version. Rules are evaluated in priority order (0 = highest). When a rule's condition matches the input facts, its actions fire.
+A **Policy Rule** is a condition → actions pair within a version. Rules are evaluated in priority order (0 = highest).
+When a rule's condition matches the input facts, its actions fire.
 
 ## Rule Structure
 
@@ -12,8 +13,12 @@ A **Policy Rule** is a condition → actions pair within a version. Rules are ev
 {
   "name": "VIP 10% Discount",
   "priority": 0,
-  "condition": { ... },
-  "actions": [ ... ],
+  "condition": {
+    ...
+  },
+  "actions": [
+    ...
+  ],
   "mutexGroup": null,
   "mutexMode": "NONE",
   "mutexStrategy": "FIRST_MATCH",
@@ -65,27 +70,27 @@ Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
 
 ### Operators
 
-| Operator | Types | Description |
-|---|---|---|
-| `EQUALS` | all | Exact match |
-| `NOT_EQUALS` | all | Negation |
-| `GREATER_THAN` | NUMBER | `>` |
-| `GREATER_THAN_OR_EQUAL` | NUMBER | `>=` |
-| `LESS_THAN` | NUMBER | `<` |
-| `LESS_THAN_OR_EQUAL` | NUMBER | `<=` |
-| `CONTAINS` | STRING | Substring match |
-| `IN` | STRING, NUMBER | Value is in the provided list |
-| `NOT_IN` | STRING, NUMBER | Value is not in the provided list |
+| Operator                | Types          | Description                       |
+|-------------------------|----------------|-----------------------------------|
+| `EQUALS`                | all            | Exact match                       |
+| `NOT_EQUALS`            | all            | Negation                          |
+| `GREATER_THAN`          | NUMBER         | `>`                               |
+| `GREATER_THAN_OR_EQUAL` | NUMBER         | `>=`                              |
+| `LESS_THAN`             | NUMBER         | `<`                               |
+| `LESS_THAN_OR_EQUAL`    | NUMBER         | `<=`                              |
+| `CONTAINS`              | STRING         | Substring match                   |
+| `IN`                    | STRING, NUMBER | Value is in the provided list     |
+| `NOT_IN`                | STRING, NUMBER | Value is not in the provided list |
 
 ### Value Types
 
-| Type | JSON Value | Example |
-|---|---|---|
-| `STRING` | `"string"` | `"VIP"` |
-| `NUMBER` | `number` | `100000` |
-| `BOOLEAN` | `true/false` | `true` |
-| `LIST_STRING` | `["a","b"]` | `["KR","US"]` |
-| `LIST_NUMBER` | `[1,2]` | `[10000, 20000]` |
+| Type          | JSON Value   | Example          |
+|---------------|--------------|------------------|
+| `STRING`      | `"string"`   | `"VIP"`          |
+| `NUMBER`      | `number`     | `100000`         |
+| `BOOLEAN`     | `true/false` | `true`           |
+| `LIST_STRING` | `["a","b"]`  | `["KR","US"]`    |
+| `LIST_NUMBER` | `[1,2]`      | `[10000, 20000]` |
 
 ### Nested Conditions Example
 
@@ -100,12 +105,31 @@ Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
       "type": "GROUP",
       "operator": "AND",
       "children": [
-        { "type": "SINGLE", "field": "customer_tier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
-        { "type": "SINGLE", "field": "payment_amount", "operator": "GREATER_THAN_OR_EQUAL", "value": 100000, "valueType": "NUMBER" }
+        {
+          "type": "SINGLE",
+          "field": "customer_tier",
+          "operator": "EQUALS",
+          "value": "VIP",
+          "valueType": "STRING"
+        },
+        {
+          "type": "SINGLE",
+          "field": "payment_amount",
+          "operator": "GREATER_THAN_OR_EQUAL",
+          "value": 100000,
+          "valueType": "NUMBER"
+        }
       ]
     },
     {
-      "type": "SINGLE", "field": "region", "operator": "IN", "value": ["KR", "JP"], "valueType": "LIST_STRING"
+      "type": "SINGLE",
+      "field": "region",
+      "operator": "IN",
+      "value": [
+        "KR",
+        "JP"
+      ],
+      "valueType": "LIST_STRING"
     }
   ]
 }
@@ -115,26 +139,34 @@ Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
 
 Each rule can have multiple actions. Actions fire sequentially.
 
-| Type | Description | Key Parameters |
-|---|---|---|
-| `DISCOUNT` | Apply a discount | `method` (PERCENTAGE/FIXED), `rate`, `refVar` |
-| `POINT` | Award points | `amount`, `pointType` |
-| `COUPON_ISSUE` | Issue a coupon | `couponId`, `expiryDays` |
-| `BLOCK` | Block the transaction | `reason`, `code` |
-| `NOTIFICATION` | Send notification | `channel`, `template` |
-| `WEBHOOK` | Call external URL | `url`, `method`, `headers`, `body` |
-| `SET_FACT` | Set an output variable | `key`, `value` |
-| `ADD_TAG` | Add a tag to the result | `tag` |
+| Type                | Description                                              | Key Parameters                                                                                      |
+|---------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `MUTATE_FACT`       | Mutate a fact value (arithmetic)                         | `refVar`, `method` (PERCENTAGE/AMOUNT), `operator` (ADD/SUB/MUL/DIV), `rate` or `value`, `rounding` |
+| `INCREMENT_FACT`    | Increment a fact (cumulative add)                        | `targetVar`, `refVar`, `method`, `value` or `rate`, `rounding`                                      |
+| `EMIT_EVENT`        | Emit an event to an external integration (coupons, etc.) | `integrationId`, `eventPayload` (Map)                                                               |
+| `BLOCK`             | Block the transaction                                    | `reason`, `code`                                                                                    |
+| `EMIT_NOTIFICATION` | Send a notification                                      | `integrationId`, `target`, `notificationPayload` (Map)                                              |
+| `EMIT_WEBHOOK`      | Call an external URL                                     | `url`, `payloadTemplate`                                                                            |
+| `SET_FACT`          | Set a fact value (literal assignment)                    | `key`, `value`                                                                                      |
+| `ADD_TAG`           | Add a tag to the result                                  | `tag`                                                                                               |
 
-### Action Example: 10% Percentage Discount
+### Action Example: 10% Discount via MUTATE_FACT
+
+Reduces `payment_amount` by 10%. `__delta` is auto-generated in `generatedVariables` (e.g.,
+`payment_amount__delta: -10000` for a 100,000 input).
 
 ```json
 {
-  "type": "DISCOUNT",
+  "type": "MUTATE_FACT",
   "parameters": {
+    "refVar": "payment_amount",
     "method": "PERCENTAGE",
+    "operator": "SUB",
     "rate": 10,
-    "refVar": "payment_amount"
+    "rounding": {
+      "mode": "HALF_UP",
+      "scale": 0
+    }
   }
 }
 ```
@@ -183,8 +215,14 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
   },
   "actions": [
     {
-      "type": "DISCOUNT",
-      "parameters": { "method": "PERCENTAGE", "rate": 10, "refVar": "payment_amount" }
+      "type": "MUTATE_FACT",
+      "parameters": {
+        "refVar": "payment_amount",
+        "method": "PERCENTAGE",
+        "operator": "SUB",
+        "rate": 10,
+        "rounding": { "mode": "HALF_UP", "scale": 0 }
+      }
     }
   ],
   "isEnabled": true
@@ -198,8 +236,14 @@ lexq rules update --group-id <gid> --version-id <vid> --id <ruleId> --json '{
   "name": "VIP 15% Discount",
   "actions": [
     {
-      "type": "DISCOUNT",
-      "parameters": { "method": "PERCENTAGE", "rate": 15, "refVar": "payment_amount" }
+      "type": "MUTATE_FACT",
+      "parameters": {
+        "refVar": "payment_amount",
+        "method": "PERCENTAGE",
+        "operator": "SUB",
+        "rate": 15,
+        "rounding": { "mode": "HALF_UP", "scale": 0 }
+      }
     }
   ]
 }'
@@ -234,11 +278,11 @@ lexq rules toggle --group-id <gid> --version-id <vid> --id <ruleId> --enabled fa
 
 Within a single version, rules can belong to a `mutexGroup` to limit how many fire.
 
-| mutexMode | Behavior |
-|---|---|
-| `NONE` | All matching rules fire (default) |
-| `EXCLUSIVE` | Only one rule per mutex group fires |
-| `MAX_N` | Up to `mutexLimit` rules per mutex group fire |
+| mutexMode   | Behavior                                      |
+|-------------|-----------------------------------------------|
+| `NONE`      | All matching rules fire (default)             |
+| `EXCLUSIVE` | Only one rule per mutex group fires           |
+| `MAX_N`     | Up to `mutexLimit` rules per mutex group fire |
 
 ```bash
 lexq rules create --group-id <gid> --version-id <vid> --json '{

package/skills/lexq-simulation/SKILL.md

@@ -6,11 +6,11 @@
 
 LexQ provides three levels of pre-deploy validation:
 
-| Tool | Scope | When to Use |
-|---|---|---|
-| **Dry Run** | Single input | Quick validation of one scenario |
-| **Dry Run Compare** | Single input, two versions | Side-by-side version comparison |
-| **Simulation** | Batch (historical data) | Full regression test before deploy |
+| Tool                | Scope                      | When to Use                        |
+|---------------------|----------------------------|------------------------------------|
+| **Dry Run**         | Single input               | Quick validation of one scenario   |
+| **Dry Run Compare** | Single input, two versions | Side-by-side version comparison    |
+| **Simulation**      | Batch (historical data)    | Full regression test before deploy |
 
 **Golden rule:** Always dry-run before publishing, always simulate before deploying to production.
 
@@ -30,11 +30,29 @@ Response includes:
   "versionId": "...",
   "versionNo": 3,
   "requiredFacts": [
-    { "key": "payment_amount", "type": "NUMBER", "required": true, "usedBy": ["VIP Discount", "Premium Block"] },
-    { "key": "customer_tier", "type": "STRING", "required": true, "usedBy": ["VIP Discount"] }
+    {
+      "key": "payment_amount",
+      "type": "NUMBER",
+      "required": true,
+      "usedBy": [
+        "VIP Discount",
+        "Premium Block"
+      ]
+    },
+    {
+      "key": "customer_tier",
+      "type": "STRING",
+      "required": true,
+      "usedBy": [
+        "VIP Discount"
+      ]
+    }
   ],
   "exampleRequest": {
-    "facts": { "payment_amount": 0, "customer_tier": "" },
+    "facts": {
+      "payment_amount": 0,
+      "customer_tier": ""
+    },
     "context": {}
   }
 }
@@ -57,11 +75,11 @@ lexq analytics dry-run --version-id <vid> --json '{
 
 ### Options
 
-| Flag | Description | Default |
-|---|---|---|
-| `--debug` | Include execution traces (which rules matched, why) | `false` |
-| `--mock` | Mock external calls (webhooks, integrations) | `false` |
-| `--file <path>` | Read request body from file instead of `--json` | — |
+| Flag            | Description                                         | Default |
+|-----------------|-----------------------------------------------------|---------|
+| `--debug`       | Include execution traces (which rules matched, why) | `false` |
+| `--mock`        | Mock external calls (webhooks, integrations)        | `false` |
+| `--file <path>` | Read request body from file instead of `--json`     | —       |
 
 ### Recommended: Always Use `--debug --mock`
 
@@ -75,53 +93,77 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
 
 ```json
 {
-  "outputVariables": { "discount_amount": 15000 },
-  "executionTraces": [
-    {
-      "traceId": "...",
-      "ruleId": "...",
-      "ruleName": "VIP 10% Discount",
-      "matched": true,
-      "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
-      "generatedActions": [ { "type": "DISCOUNT", "parameters": { ... } } ]
-    }
-  ],
-  "decisionTraces": [
-    {
-      "ruleId": "...",
-      "ruleName": "VIP 10% Discount",
-      "status": "SELECTED",
-      "reasonCode": "FINAL_WINNER",
-      "reasonDetail": "..."
-    }
-  ],
-  "latencyMs": 12,
-  "versionNo": 3
+  "result": "SUCCESS",
+  "data": {
+    "inputFacts": {
+      "payment_amount": 150000,
+      "customer_tier": "VIP"
+    },
+    "mutatedFacts": {
+      "payment_amount": 135000,
+      "customer_tier": "VIP"
+    },
+    "generatedVariables": {
+      "payment_amount__delta": -15000
+    },
+    "executionTraces": [
+      {
+        "traceId": "...",
+        "ruleId": "...",
+        "ruleName": "VIP 10% Discount",
+        "matched": true,
+        "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
+        "generatedActions": [
+          {
+            "type": "MUTATE_FACT",
+            "parameters": {
+              ...
+            }
+          }
+        ]
+      }
+    ],
+    "decisionTraces": [
+      {
+        "ruleId": "...",
+        "ruleName": "VIP 10% Discount",
+        "status": "SELECTED",
+        "reasonCode": "FINAL_WINNER",
+        "reasonDetail": "..."
+      }
+    ],
+    "latencyMs": 12,
+    "versionNo": 3
+  }
 }
 ```
 
+- `mutatedFacts` — input facts changed by rule actions (e.g., `MUTATE_FACT` reduces `payment_amount`)
+- `generatedVariables` — for every fact in `mutatedFacts`, a paired `{fact_name}__delta` key is auto-generated with the
+  signed difference (negative = decrease, positive = increase)
+
 ### Reading Decision Traces
 
-| Status | Meaning |
-|---|---|
-| `SELECTED` | Rule matched and its actions fired |
-| `NO_MATCH` | Condition did not match the input |
-| `NOT_SELECTED` | Matched but excluded by conflict resolution |
-| `BLOCKED_MUTEX` | Blocked by mutex group constraint |
-| `LOST_PRIORITY` | Lost to a higher-priority rule |
-| `DROPPED_LIMIT` | Execution limit reached |
-| `ERROR` | Rule evaluation failed |
+| Status          | Meaning                                     |
+|-----------------|---------------------------------------------|
+| `SELECTED`      | Rule matched and its actions fired          |
+| `NO_MATCH`      | Condition did not match the input           |
+| `NOT_SELECTED`  | Matched but excluded by conflict resolution |
+| `BLOCKED_MUTEX` | Blocked by mutex group constraint           |
+| `LOST_PRIORITY` | Lost to a higher-priority rule              |
+| `DROPPED_LIMIT` | Execution limit reached                     |
+| `ERROR`         | Rule evaluation failed                      |
 
 ### Reading Reason Codes
 
-| Code | Meaning |
-|---|---|
-| `FINAL_WINNER` | Successfully executed |
-| `CONDITION_MISMATCH` | Input facts didn't satisfy the condition |
+| Code                  | Meaning                                                  |
+|-----------------------|----------------------------------------------------------|
+| `FINAL_WINNER`        | Successfully executed                                    |
+| `CONDITION_MISMATCH`  | Input facts didn't satisfy the condition                 |
 | `MUTEX_PRIORITY_LOST` | Another rule in the same mutex group had higher priority |
-| `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired |
-| `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached |
-| `ACTION_ERROR` | Action execution failed (e.g., webhook timeout) |
+| `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired                    |
+| `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached                         |
+| `ACTION_ERROR`        | Action execution failed (e.g., webhook timeout)          |
 
 ## 3. Dry Run Compare
 
@@ -137,7 +179,7 @@ lexq analytics dry-run-compare --json '{
 
 Useful for validating that changes in a new version produce expected differences.
 
-## 4. Batch Simulation
+## 4. Impact Simulation
 
 Run a full regression test against historical execution data:
 
@@ -157,7 +199,7 @@ lexq analytics simulation start --json '{
     "maxRecords": 10000,
     "baselinePolicyVersionId": "<currentLiveVersionId>",
     "metricConfig": {
-      "targetVariable": "discount_amount",
+      "targetVariable": "payment_amount__delta",
       "aggregationType": "SUM"
     }
   }
@@ -166,13 +208,14 @@ lexq analytics simulation start --json '{
 
 ### Dataset Types
 
-| Type | Source | Description |
-|---|---|---|
-| `HISTORICAL` | `EXECUTION_LOGS` | Replay past executions from a date range |
-| `MANUAL` | `REQUEST_BODY` | Provide `manualData` array in the request |
-| `UPLOADED` | `S3_BUCKET` | Reference an uploaded dataset by `path` |
+| Type         | Source           | Description                               |
+|--------------|------------------|-------------------------------------------|
+| `HISTORICAL` | `EXECUTION_LOGS` | Replay past executions from a date range  |
+| `MANUAL`     | `REQUEST_BODY`   | Provide `manualData` array in the request |
+| `UPLOADED`   | `S3_BUCKET`      | Reference an uploaded dataset by `path`   |
 
 ### File Upload Dataset
+
 ```bash
 # 1. Download template (optional)
 lexq analytics dataset template \
@@ -212,13 +255,13 @@ lexq analytics simulation status --id <simulationId>
 
 Simulation is async. Poll until `status` is `COMPLETED` or `FAILED`.
 
-| Status | Meaning |
-|---|---|
-| `PENDING` | Queued |
-| `RUNNING` | In progress (`progress` field shows 0–100) |
-| `COMPLETED` | Done — results available |
-| `FAILED` | Error occurred |
-| `CANCELLED` | Manually cancelled |
+| Status      | Meaning                                    |
+|-------------|--------------------------------------------|
+| `PENDING`   | Queued                                     |
+| `RUNNING`   | In progress (`progress` field shows 0–100) |
+| `COMPLETED` | Done — results available                   |
+| `FAILED`    | Error occurred                             |
+| `CANCELLED` | Manually cancelled                         |
 
 ### List Simulations
 
@@ -254,7 +297,7 @@ lexq analytics simulation export --id <simulationId> --format csv --output resul
     "matchRate": 0.85
   },
   "metricSummary": {
-    "targetVariable": "discount_amount",
+    "targetVariable": "payment_amount__delta",
     "aggregationType": "SUM",
     "baselineValue": 5000000,
     "simulatedValue": 4500000,
@@ -273,7 +316,12 @@ lexq analytics simulation export --id <simulationId> --format csv --output resul
     }
   },
   "ruleStats": [
-    { "ruleId": "...", "ruleName": "VIP Discount", "matchedCount": 5000, "metricValue": 3000000 }
+    {
+      "ruleId": "...",
+      "ruleName": "VIP Discount",
+      "matchedCount": 5000,
+      "metricValue": 3000000
+    }
   ]
 }
 ```
@@ -299,7 +347,7 @@ lexq analytics simulation start --json '{
   "options": {
     "baselinePolicyVersionId": "<currentLiveVersionId>",
     "includeRuleStats": true,
-    "metricConfig": { "targetVariable": "discount_amount", "aggregationType": "SUM" }
+    "metricConfig": { "targetVariable": "payment_amount__delta", "aggregationType": "SUM" }
   }
 }'