@lexq/cli 0.1.39 → 0.1.41

package/skills/lexq-rules/SKILL.md

@@ -4,15 +4,18 @@
 
 ## 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 — **lower number wins**, and priorities are 1-based (1 is highest). When a rule's condition
+matches the input facts, its actions fire.
+
+`priority` is assigned by the server, not by you. New rules are appended last. Use
+`lexq rules reorder` to change the order.
 
 ## Rule Structure
 
 ```json
 {
   "name": "VIP 10% Discount",
-  "priority": 0,
   "condition": {
     ...
   },
@@ -21,7 +24,7 @@ When a rule's condition matches the input facts, its actions fire.
   ],
   "mutexGroup": null,
   "mutexMode": "NONE",
-  "mutexStrategy": "FIRST_MATCH",
+  "mutexStrategy": "HIGHEST_PRIORITY",
   "mutexLimit": null,
   "isEnabled": true
 }
@@ -70,17 +73,53 @@ 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 |
+Operators are constrained by the **left fact's type**. Using one outside its type is rejected
+by the server — check `lexq facts list` before choosing.
+
+| Fact type                     | Allowed operators                                                                                                  |
+|-------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| `STRING`                      | `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `IN`, `NOT_IN`                                                                 |
+| `NUMBER`                      | `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `IN`, `NOT_IN` |
+| `BOOLEAN`                     | `EQUALS`, `NOT_EQUALS`                                                                                             |
+| `LIST_STRING` / `LIST_NUMBER` | `HAS_ANY`, `HAS_ALL`, `HAS_NONE`                                                                                   |
+
+| Operator                                                                      | Description                                                | `value` |
+|-------------------------------------------------------------------------------|------------------------------------------------------------|---------|
+| `EQUALS` / `NOT_EQUALS`                                                       | Exact match / negation                                     | scalar  |
+| `GREATER_THAN` / `GREATER_THAN_OR_EQUAL` / `LESS_THAN` / `LESS_THAN_OR_EQUAL` | Numeric comparison                                         | scalar  |
+| `CONTAINS`                                                                    | **Substring** match on a STRING fact — not list membership | scalar  |
+| `IN` / `NOT_IN`                                                               | Scalar fact is (not) in the given list                     | array   |
+| `HAS_ANY`                                                                     | List fact has **at least one** of the given values         | array   |
+| `HAS_ALL`                                                                     | List fact has **all** of the given values                  | array   |
+| `HAS_NONE`                                                                    | List fact has **none** of the given values                 | array   |
+
+**`IN` vs `HAS_*` — mirrors of each other.** This is the most common mistake here:
+
+```json
+// scalar fact, list value
+{
+  "field": "region",
+  "operator": "IN",
+  "value": [
+    "KR",
+    "JP"
+  ],
+  "valueType": "LIST_STRING"
+}
+
+// list fact, list value
+{
+  "field": "user_tags",
+  "operator": "HAS_ANY",
+  "value": [
+    "VIP",
+    "GOLD"
+  ],
+  "valueType": "LIST_STRING"
+}
+```
+
+Do **not** use `CONTAINS` on a list fact — that idiom works in some rule engines but is rejected here.
 
 ### Value Types
 
@@ -139,16 +178,71 @@ 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                                                                                      |
-|---------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| `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`                                                                                               |
+| Type          | Description                                | Key Parameters                                                       |
+|---------------|--------------------------------------------|----------------------------------------------------------------------|
+| `MUTATE_FACT` | Arithmetic change to a numeric fact        | `targetVar`, `operator`, `method`, `operand`, `refVar?`, `rounding?` |
+| `SET_FACT`    | Assign a literal value — creates if absent | `targetVar`, `value`                                                 |
+| `BLOCK`       | Record a rejection decision                | `reason`                                                             |
+
+### `MUTATE_FACT` parameters
+
+| Parameter   | Required | Meaning                                                                       |
+|-------------|----------|-------------------------------------------------------------------------------|
+| `targetVar` | always   | The fact this action **reads and writes**. Must already exist as a number.    |
+| `operator`  | always   | `ASSIGN` \| `ADD` \| `SUB` \| `MUL` \| `DIV`                                  |
+| `method`    | always   | `PERCENTAGE` \| `AMOUNT` — dictates the unit of `operand`                     |
+| `operand`   | always   | The arithmetic operand. Percent when PERCENTAGE, absolute amount when AMOUNT. |
+| `refVar`    | optional | Base for percentage calculation. Omit to use `targetVar` itself.              |
+| `rounding`  | optional | `{ scale: 0..16, mode?: HALF_UP \| ... }`. Omit for lossless full precision.  |
+
+**operator × method matrix**
+
+| operator | `AMOUNT`               | `PERCENTAGE`                        |
+|----------|------------------------|-------------------------------------|
+| `ASSIGN` | `targetVar = operand`  | `targetVar = refVar × operand/100`  |
+| `ADD`    | `targetVar += operand` | `targetVar += refVar × operand/100` |
+| `SUB`    | `targetVar -= operand` | `targetVar -= refVar × operand/100` |
+| `MUL`    | `targetVar *= operand` | `targetVar *= (operand/100 + 1)`    |
+| `DIV`    | `targetVar /= operand` | **invalid**                         |
+
+`DIV` + `PERCENTAGE` is rejected — use `MUL` with the inverse. `DIV` + `AMOUNT` requires
+`operand !== 0`.
+
+**`refVar` is only meaningful in `PERCENTAGE` × {`ASSIGN`, `ADD`, `SUB`}.** Specifying it in any
+other cell is an error, not a silent no-op. `AMOUNT` has no base concept, and `MUL` × `PERCENTAGE`
+is a multiplier shorthand that does not read a base.
+
+Use `refVar` when the base differs from the target:
+
+```json
+{
+  "type": "MUTATE_FACT",
+  "parameters": {
+    "targetVar": "loyalty_point",
+    "refVar": "order_total",
+    "operator": "ADD",
+    "method": "PERCENTAGE",
+    "operand": 5
+  }
+}
+```
+
+`loyalty_point += order_total × 5%` — two different facts. Omitting `refVar` would compute
+`loyalty_point += loyalty_point × 5%` instead.
+
+**Ranges are not constrained.** Negative operands and percentages above 100 are valid — refunds
+(`-5`), surcharges (`150`), risk scores, and game points all need them.
+
+### `SET_FACT` vs `MUTATE_FACT`
+
+`SET_FACT` creates the fact if it does not exist. `MUTATE_FACT` requires the target to already be
+present as a number and throws otherwise. "Make something that wasn't there" is `SET_FACT`'s job.
+
+### `BLOCK` does not halt execution
+
+`BLOCK` records a rejection decision by writing the `is_blocked` fact. Subsequent actions in the
+same rule and subsequent winning rules still run. Enforcement is the caller's responsibility —
+read `is_blocked` from the response.
 
 ### Action Example: 10% Discount via MUTATE_FACT
 
@@ -159,10 +253,10 @@ Reduces `payment_amount` by 10%. `__delta` is auto-generated in `generatedVariab
 {
   "type": "MUTATE_FACT",
   "parameters": {
-    "refVar": "payment_amount",
+    "targetVar": "payment_amount",
     "method": "PERCENTAGE",
     "operator": "SUB",
-    "rate": 10,
+    "operand": 10,
     "rounding": {
       "mode": "HALF_UP",
       "scale": 0
@@ -177,8 +271,7 @@ Reduces `payment_amount` by 10%. `__delta` is auto-generated in `generatedVariab
 {
   "type": "BLOCK",
   "parameters": {
-    "reason": "Suspected fraud",
-    "code": "FRAUD_DETECTED"
+    "reason": "Suspected fraud"
   }
 }
 ```
@@ -204,7 +297,6 @@ lexq rules get --group-id <gid> --version-id <vid> --id <ruleId>
 ```bash
 lexq rules create --group-id <gid> --version-id <vid> --json '{
   "name": "VIP 10% Discount",
-  "priority": 0,
   "condition": {
     "type": "GROUP",
     "operator": "AND",
@@ -217,10 +309,10 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
     {
       "type": "MUTATE_FACT",
       "parameters": {
-        "refVar": "payment_amount",
+        "targetVar": "payment_amount",
         "method": "PERCENTAGE",
         "operator": "SUB",
-        "rate": 10,
+        "operand": 10,
         "rounding": { "mode": "HALF_UP", "scale": 0 }
       }
     }
@@ -238,10 +330,10 @@ lexq rules update --group-id <gid> --version-id <vid> --id <ruleId> --json '{
     {
       "type": "MUTATE_FACT",
       "parameters": {
-        "refVar": "payment_amount",
+        "targetVar": "payment_amount",
         "method": "PERCENTAGE",
         "operator": "SUB",
-        "rate": 15,
+        "operand": 15,
         "rounding": { "mode": "HALF_UP", "scale": 0 }
       }
     }
@@ -258,7 +350,8 @@ lexq rules delete --group-id <gid> --version-id <vid> --id <ruleId> --force
 
 ### Reorder Rules
 
-Pass rule IDs in desired priority order (index 0 = highest priority):
+Pass rule IDs in desired order. The server assigns priority 1, 2, 3, … — the first ID becomes
+priority 1 (highest):
 
 ```bash
 lexq rules reorder --group-id <gid> --version-id <vid> \
@@ -278,26 +371,44 @@ 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 fire. Omit it and the server sets 2. |
 
 ```bash
 lexq rules create --group-id <gid> --version-id <vid> --json '{
   "name": "Discount A",
-  "priority": 0,
   "mutexGroup": "discounts",
   "mutexMode": "EXCLUSIVE",
   "mutexStrategy": "HIGHEST_PRIORITY",
   "condition": { ... },
   "actions": [ ... ]
 }'
+
+# Top two of the group fire
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Stackable Promo A",
+  "mutexGroup": "promos",
+  "mutexMode": "MAX_N",
+  "mutexLimit": 2,
+  "mutexStrategy": "HIGHEST_PRIORITY",
+  "condition": { ... },
+  "actions": [ ... ]
+}'
 ```
 
 **Constraint:** All rules in the same `mutexGroup` must use identical `mutexMode` and `mutexStrategy`.
 
+**`mutexGroup` is what turns mutex on.** Sending `mutexMode` without a `mutexGroup` is silently normalized to `NONE` —
+there is no group to be exclusive within. Conversely, setting a `mutexGroup` without a `mutexMode` defaults to
+`EXCLUSIVE`.
+
+`mutexStrategy` currently accepts only `HIGHEST_PRIORITY` — the rule with the lowest priority
+number in the group wins. `mutexMode: MAX_N` requires `mutexLimit`; omit it and the server
+sets 2.
+
 ## Pre-Create Checklist
 
 Before creating rules, always:
@@ -305,4 +416,5 @@ Before creating rules, always:
 1. **Check available facts:** `lexq facts list`
 2. **Confirm the version is DRAFT:** `lexq versions get --group-id <gid> --id <vid>` → status must be `DRAFT`
 3. **Use exact fact keys** from the fact definitions (snake_case, case-sensitive)
-4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+5. **Match the operator to the fact type** — list-typed facts accept only `HAS_ANY` / `HAS_ALL` / `HAS_NONE`

package/skills/lexq-shared/SKILL.md

@@ -35,7 +35,7 @@ lexq groups list --api-key lexq_us_override_key
 | **Policy Version**  | A snapshot of rules within a group. Follows DRAFT → ACTIVE → ARCHIVED lifecycle.                                 | Git branch / commit    |
 | **Policy Rule**     | A condition + actions pair within a version. Evaluated in priority order.                                        | if-then statement      |
 | **Fact Definition** | Input schema — declares available variables and their types (STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER). | Function parameter     |
-| **Deployment**      | Promotes a PUBLISHED version to live traffic. Supports rollback.                                                 | Production release     |
+| **Deployment**      | Promotes an ACTIVE version to live traffic. Supports rollback and scheduled arming.                              | Production release     |
 | **Dry Run**         | Tests a single input against a DRAFT or ACTIVE version without side effects.                                     | Unit test              |
 | **Simulation**      | Batch-tests a version against historical execution data. Compares with a baseline.                               | Integration test suite |
 
@@ -50,15 +50,15 @@ This is the typical lifecycle. **Always follow this order:**
 4. lexq rules create           → Add rules with conditions + actions
 5. lexq analytics dry-run      → Test with sample facts (validate before publish)
 6. lexq deploy publish         → DRAFT → ACTIVE (locks the version)
-7. lexq deploy live            → Deploy ACTIVE version to production
-8. lexq analytics simulation   → Run batch comparison against baseline (optional)
+7. lexq analytics simulation   → Batch-test against historical data with a baseline (optional)
+8. lexq deploy live            → Deploy ACTIVE version to production
 ```
 
 ### Critical Ordering Constraints
 
 - **Cannot create rules without a DRAFT version.** Create the version first.
 - **Cannot publish without at least one rule.** Add rules before publishing.
-- **Cannot modify a published version.** Clone it to create a new DRAFT if changes are needed.
+  **Cannot modify an ACTIVE version.** Clone it to create a new DRAFT if changes are needed.
 - **Cannot deploy a DRAFT version.** Must publish first (DRAFT → ACTIVE).
 - **Always run `lexq analytics dry-run` before publishing.** This is your safety net.
 
@@ -80,19 +80,24 @@ Every command accepts these flags:
 
 ## Command Groups
 
-| Group          | Commands                                                                                   | Description                     |
-|----------------|--------------------------------------------------------------------------------------------|---------------------------------|
-| `auth`         | `login`, `logout`, `whoami`                                                                | Authentication                  |
-| `status`       | (root)                                                                                     | API health check                |
-| `groups`       | `list`, `get`, `create`, `update`, `delete` + `ab-test start\|stop\|adjust`                | Policy group CRUD + A/B testing |
-| `versions`     | `list`, `get`, `create`, `update`, `delete`, `clone`                                       | Version CRUD                    |
-| `rules`        | `list`, `get`, `create`, `update`, `delete`, `reorder`, `toggle`                           | Rule CRUD                       |
-| `facts`        | `list`, `create`, `update`, `delete`                                                       | Fact definition CRUD            |
-| `deploy`       | `publish`, `live`, `rollback`, `undeploy`, `history`, `detail`, `overview`                 | Deployment lifecycle            |
-| `analytics`    | `dry-run`, `dry-run-compare`, `requirements`, `simulation start/status/list/cancel/export` | Testing & analysis              |
-| `history`      | `list`, `get`, `stats`                                                                     | Execution history               |
-| `integrations` | `list`, `get`, `save`, `delete`, `config-spec`                                             | External integrations           |
-| `logs`         | `list`, `get`, `action`, `bulk-action`                                                     | Failure log management          |
+| Group                   | Commands                                                                                                                   | Description                     |
+|-------------------------|----------------------------------------------------------------------------------------------------------------------------|---------------------------------|
+| `auth`                  | `login`, `logout`, `whoami`                                                                                                | Authentication                  |
+| `status`                | (root)                                                                                                                     | API health check                |
+| `groups`                | `list`, `get`, `create`, `update`, `delete`, `reorder` + `ab-test start\|stop\|adjust`                                     | Policy group CRUD + A/B testing |
+| `versions`              | `list`, `get`, `create`, `update`, `delete`, `clone`                                                                       | Version CRUD                    |
+| `rules`                 | `list`, `get`, `create`, `update`, `delete`, `reorder`, `toggle`                                                           | Rule CRUD                       |
+| `facts`                 | `list`, `create`, `update`, `delete`                                                                                       | Fact definition CRUD            |
+| `domain-templates`      | `list`, `preview`, `apply`                                                                                                 | Industry starter packs          |
+| `deploy`                | `publish`, `live`, `rollback`, `undeploy`, `history`, `detail`, `overview`, `schedule`, `unschedule`, `schedules`          | Deployment lifecycle            |
+| `analytics`             | `dry-run`, `dry-run-compare`, `requirements`, `simulation start\|status\|list\|cancel\|export`, `dataset upload\|template` | Testing & analysis              |
+| `profile`               | (root, takes `<groupId>`)                                                                                                  | Per-rule latency profile        |
+| `history`               | `list`, `get`, `stats`                                                                                                     | Execution history               |
+| `replay`                | `decision`, `start`, `list`, `get`, `cancel`                                                                               | Decision replay                 |
+| `provenance`            | `get`, `reveal-audits`                                                                                                     | Decision provenance + PII audit |
+| `logs`                  | `list`, `get`, `action`, `bulk-action`                                                                                     | Failure log management          |
+| `webhook-subscriptions` | `list`, `get`, `save`, `delete`, `test`                                                                                    | Platform event webhooks         |
+| `serve`                 | `--mcp`                                                                                                                    | MCP server over stdio           |
 
 ## Pagination
 
@@ -120,19 +125,27 @@ API errors return:
 {
   "result": "ERROR",
   "message": "Policy version not found.",
-  "code": "ENTITY_NOT_FOUND"
+  "errorCode": "P-002"
 }
 ```
 
-**Common error codes and what to do:**
+`errorCode` is a stable identifier of the form `<domain>-<number>`. `message` is the
+human-readable explanation and is localized by `Accept-Language`. **Branch on `errorCode`, never
+on `message`.**
 
-| Code               | Meaning                        | Action                                                                          |
-|--------------------|--------------------------------|---------------------------------------------------------------------------------|
-| `ENTITY_NOT_FOUND` | Resource doesn't exist         | Verify the ID. Run the corresponding `list` command.                            |
-| `INVALID_INPUT`    | Validation failed              | Check required fields. Run `lexq analytics requirements` for fact requirements. |
-| `CANNOT_MODIFY`    | Version is not DRAFT           | Clone the version to create a new DRAFT: `lexq versions clone`                  |
-| `EMPTY_RULES`      | Publish attempted with 0 rules | Add at least one rule before publishing.                                        |
-| `UNAUTHORIZED`     | Invalid or missing API key     | Run `lexq auth login` with a valid key.                                         |
+Prefixes you will encounter through the CLI:
+
+| Prefix | Domain                | Example cause                                  |
+|--------|-----------------------|------------------------------------------------|
+| `C-`   | Common validation     | Malformed or missing request field             |
+| `A-`   | Auth                  | Invalid or missing API key                     |
+| `P-`   | Policy group/version  | Not found, wrong lifecycle state, already live |
+| `ACT-` | Action parameters     | Missing or invalid action parameter            |
+| `FD-`  | Fact definitions      | Duplicate key, system fact immutable           |
+| `AN-`  | Analytics             | Dry-run or simulation failure                  |
+| `FL-`  | Failure logs          | Log not found                                  |
+| `WH-`  | Webhook subscriptions | Invalid URL, delivery failure                  |
+| `I-`   | Idempotency           | Duplicate idempotency key                      |
 
 ## Important Conventions
 
@@ -140,6 +153,13 @@ API errors return:
 2. **IDs are UUIDs.** Always copy the full ID from list/create output — do not guess.
 3. **Dates use ISO 8601.** Example: `2025-01-01T00:00:00Z`. Time zone is UTC.
 4. **JSON bodies via `--json`.** Most create/update commands accept `--json '<body>'` for the request body.
-5. **File input via `--file`.** Analytics commands accept `--file path/to/body.json` as an alternative to `--json`.
+5. **File input via `--file`.** `analytics dry-run`, `dry-run-compare`, `simulation start` accept
+   `--file path/to/body.json` as an alternative to `--json`. `analytics dataset upload` requires
+   `--file` (CSV or JSON). `simulation export` and `dataset template` write output with `--output`.
 6. **Confirmation prompts.** Destructive operations (delete, cancel, undeploy) prompt for confirmation. Use `--force` to
-   skip in automation.
+   skip in automation.
+
+## Skill Formatting
+
+Catalog-style skills (`lexq-recipes`) separate independent items with `---`. Narrative skills do
+not use it at all. Never mix both in one file.

package/skills/lexq-simulation/SKILL.md

@@ -78,17 +78,19 @@ lexq analytics dry-run --version-id <vid> --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`
+### Recommended: Always Use `--debug`
 
 ```bash
-lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+lexq analytics dry-run --version-id <vid> --debug --json '{
   "facts": { "payment_amount": 150000, "customer_tier": "VIP" }
 }'
 ```
 
+Dry run has no side effects — actions only mutate the fact map in memory. There is nothing
+external to mock.
+
 ### Response Structure
 
 ```json
@@ -111,7 +113,7 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
         "ruleId": "...",
         "ruleName": "VIP 10% Discount",
         "matched": true,
-        "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
+        "matchExpression": "(customer_tier == 'VIP') && (payment_amount >= 100000)",
         "generatedActions": [
           {
             "type": "MUTATE_FACT",
@@ -143,26 +145,51 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
 
 ### 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                      |
+Each trace carries a `status` (what happened) and a `reasonCode` (why).
+
+| Status     | Meaning                                                                         |
+|------------|---------------------------------------------------------------------------------|
+| `SELECTED` | Rule matched and its actions fired                                              |
+| `NO_MATCH` | Condition did not match, or could not be evaluated                              |
+| `BLOCKED`  | Matched but lost conflict resolution — see `reasonCode` for which round and why |
+| `ERROR`    | Action execution failed                                                         |
+
+`BLOCKED` is unrelated to the `BLOCK` action. A `BLOCK` action writes the `is_blocked` fact and its own rule stays
+`SELECTED`; `BLOCKED` means the rule was dropped by activation-group or mutex competition.
 
 ### Reading Reason Codes
 
 | Code                  | Meaning                                                  |
 |-----------------------|----------------------------------------------------------|
 | `FINAL_WINNER`        | Successfully executed                                    |
-| `CONDITION_MISMATCH`  | Input facts didn't satisfy the condition                 |
+| `CONDITION_MISMATCH`  | Condition not satisfied, or could not be evaluated       |
 | `MUTEX_PRIORITY_LOST` | Another rule in the same mutex group had higher priority |
 | `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired                    |
+| `GROUP_PRIORITY_LOST` | Another group in the same activation group won           |
 | `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached                         |
-| `ACTION_ERROR`        | Action execution failed (e.g., webhook timeout)          |
+| `ACTION_ERROR`        | Action execution failed (e.g. required fact absent)      |
+| `ENGINE_ERROR`        | Internal engine failure                                  |
+
+A version outside its effective date range is filtered **before** evaluation — no trace is produced for it at all. If a
+rule you expect never appears in `decisionTraces`, check the version's `effectiveFrom` / `effectiveTo` with
+`lexq versions get`.
+
+#### `reasonDetail` on unevaluable conditions
+
+`CONDITION_MISMATCH` covers two different things, distinguished by `reasonDetail`:
+
+- **empty** — the condition was evaluated and did not match
+- **`Evaluation error: <code>`** — the condition could not be evaluated at all
+
+| Code                    | Meaning                                                            |
+|-------------------------|--------------------------------------------------------------------|
+| `FACT_NOT_PROVIDED`     | The rule references a fact absent from the request                 |
+| `FACT_TYPE_MISMATCH`    | The fact's runtime type does not match the condition               |
+| `UNSUPPORTED_FACT_TYPE` | Operator not valid for the fact's type (e.g. `CONTAINS` on a list) |
+| `MALFORMED_RULE`        | The stored rule is structurally invalid                            |
+
+A rule from another group referencing facts you did not send yields `FACT_NOT_PROVIDED` — this
+is normal, not an error.
 
 ## 3. Dry Run Compare
 
@@ -218,19 +245,19 @@ lexq analytics simulation start --json '{
 ```bash
 # 1. Download template (optional)
 lexq analytics dataset template \
-  --group-id  --version-id  --format csv --output template.csv
+  --group-id <gid> --version-id <vid> --format csv --output template.csv
 
 # 2. Upload dataset
 lexq analytics dataset upload --file ./my-data.csv
-# → path: datasets//a1b2c3d4e5f6.csv
+# → path: datasets/<tenantId>/a1b2c3d4e5f6.csv
 
 # 3. Start simulation with uploaded path
 lexq analytics simulation start --json '{
-  "policyVersionId": "",
+  "policyVersionId": "<vid>",
   "dataset": {
     "type": "UPLOADED",
     "source": "S3_BUCKET",
-    "path": "datasets//a1b2c3d4e5f6.csv"
+    "path": "<path returned by dataset upload>"
   },
   "options": { "includeRuleStats": true, "maxRecords": 10000 }
 }'
@@ -239,13 +266,6 @@ lexq analytics simulation start --json '{
 **CSV format:** Header row with fact keys, data rows with values. Types auto-detected.
 **JSON format:** Array of objects `[{"key": "value"}, ...]`
 
-### MCP — Dataset Tools
-
-```
-lexq_dataset_template  → Get sample CSV/JSON based on version's required facts
-lexq_dataset_upload    → Upload inline CSV/JSON content to S3, returns path
-```
-
 ### Check Status (Poll)
 
 ```bash
@@ -332,7 +352,7 @@ lexq analytics simulation export --id <simulationId> --format csv --output resul
 lexq analytics requirements --group-id <gid> --version-id <vid>
 
 # 2. Dry-run with representative inputs
-lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+lexq analytics dry-run --version-id <vid> --debug --json '{
   "facts": { "payment_amount": 150000, "customer_tier": "VIP" }
 }'