@lexq/cli 0.1.40 → 0.1.42

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 63 tools to any MCP-compatible AI client.
+The CLI also doubles as an **MCP server** — run `lexq serve --mcp` to expose 75 tools to any MCP-compatible AI client.
 
 This file tells you how to use the CLI as an AI agent.
 
@@ -30,14 +30,14 @@ lexq auth whoami
 
 Detailed documentation lives in the `skills/` directory. **Read the relevant skill before executing commands.**
 
-| Skill          | File                              | What it covers                                                    |
-|----------------|-----------------------------------|-------------------------------------------------------------------|
-| **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, 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)                           |
+| Skill          | File                              | What it covers                                                                           |
+|----------------|-----------------------------------|------------------------------------------------------------------------------------------|
+| **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, Impact Simulation, compare                                                      |
+| **Execution**  | `skills/lexq-execution/SKILL.md`  | History, stats, failure logs, provenance, replay, latency profile, deployment monitoring |
+| **Recipes**    | `skills/lexq-recipes/SKILL.md`    | End-to-end workflows (copy-paste ready)                                                  |
 
 ## Agent Rules
 
@@ -48,27 +48,28 @@ Detailed documentation lives in the `skills/` directory. **Read the relevant ski
 5. **Use `--format json` for parsing.** This is the default. Don't change it.
 6. **Copy full UUIDs from output.** Never guess or truncate IDs.
 7. **Memo is required for all deploy operations.** `publish`, `live`, `rollback`, `undeploy` — every one needs `--memo`.
-8. **For deployment lifecycle notifications use webhook subscriptions, not integrations.** Integrations fire on rule
-   match; webhook subscriptions fire on platform events (VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED).
-9. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.
+8. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.
 
-## Complete Command Inventory (67 commands)
+## Complete Command Inventory
 
 ```
 lexq auth login|logout|whoami
 lexq status
 lexq serve --mcp                                              # MCP stdio server mode
-lexq groups list|get|create|update|delete
+lexq groups list|get|create|update|delete|reorder
 lexq groups ab-test start|stop|adjust
 lexq versions list|get|create|update|delete|clone
 lexq rules list|get|create|update|delete|reorder|toggle
-lexq facts list|create|update|delete|action-metadata
-lexq deploy publish|live|rollback|undeploy|history|detail|overview|deployable|diff
+lexq facts list|create|update|delete|action-metadata|unregistered
+lexq domain-templates list|preview|apply
+lexq deploy publish|live|rollback|undeploy|history|detail|overview|deployable|diff|schedule|unschedule|schedules
 lexq analytics dry-run|dry-run-compare|requirements
 lexq analytics simulation start|status|list|cancel|export
 lexq analytics dataset upload|template
+lexq profile <groupId>
 lexq history list|get|stats
-lexq integrations list|get|save|delete|config-spec
+lexq replay decision|start|list|get|cancel
+lexq provenance get|reveal-audits
 lexq logs list|get|action|bulk-action
 lexq webhook-subscriptions list|get|save|delete|test
 ```
@@ -77,7 +78,7 @@ lexq webhook-subscriptions list|get|save|delete|test
 
 ```bash
 # 1. Create group
-GROUP=$(lexq groups create --json '{"name":"my-policy","priority":0}')
+GROUP=$(lexq groups create --json '{"name":"my-policy"}')
 GID=$(echo $GROUP | jq -r '.id')
 
 # 2. Create version
@@ -90,13 +91,12 @@ lexq facts create --key age --name "User Age" --type NUMBER
 # 4. Add rule
 lexq rules create --group-id $GID --version-id $VID --json '{
   "name": "Adult Check",
-  "priority": 0,
   "condition": {"type":"SINGLE","field":"age","operator":"GREATER_THAN_OR_EQUAL","value":18,"valueType":"NUMBER"},
-  "actions": [{"type":"SET_FACT","parameters":{"key":"is_adult","value":"true"}}]
+  "actions": [{"type":"SET_FACT","parameters":{"targetVar":"is_adult","value":true}}]
 }'
 
 # 5. Test
-lexq analytics dry-run --version-id $VID --debug --mock --json '{"facts":{"age":25}}'
+lexq analytics dry-run --version-id $VID --debug --json '{"facts":{"age":25}}'
 
 # 6. Deploy
 lexq deploy publish --group-id $GID --version-id $VID --memo "v1"
@@ -112,7 +112,7 @@ Webhook subscriptions fire on platform events — separate from rule-level webho
 lexq webhook-subscriptions save --json '{
   "name": "Slack Deploy Notifications",
   "webhookUrl": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
-  "subscribedEvents": ["VERSION_PUBLISHED", "DEPLOYED", "ROLLED_BACK", "UNDEPLOYED"],
+  "subscribedEvents": ["VERSION_PUBLISHED", "DEPLOYED", "ROLLED_BACK", "UNDEPLOYED", "DEPLOY_SCHEDULED"],
   "payloadFormat": "SLACK"
 }'
 
@@ -142,16 +142,18 @@ Connect via:
 - **Cloud:** `https://mcp.lexq.io` (OAuth 2.1)
 - **Local stdio:** `npx @lexq/cli serve --mcp`
 
-63 tools mirror the CLI command inventory.
+75 tools mirror the CLI command inventory.
 
 ## Troubleshooting
 
-| Problem                      | Solution                                                                 |
-|------------------------------|--------------------------------------------------------------------------|
-| `Not authenticated`          | Run `lexq auth login`                                                    |
-| `ENTITY_NOT_FOUND`           | Verify the ID exists via the corresponding `list` command                |
-| `CANNOT_MODIFY`              | Version is not DRAFT. Clone it: `lexq versions clone`                    |
-| `EMPTY_RULES`                | Add at least one rule before publishing                                  |
-| `ACTIVATION_CONFIG_MISMATCH` | All groups in the same activationGroup must share the same mode/strategy |
-| `WH_URL_INVALID`             | Webhook URL must be HTTPS and return 2xx for a POST                      |
-| Network error                | Check `lexq status` for API health                                       |
+| Problem                     | Solution                                                            |
+|-----------------------------|---------------------------------------------------------------------|
+| `Not authenticated`         | Run `lexq auth login`                                               |
+| `P-` error on get/update    | Verify the ID exists via the corresponding `list` command           |
+| Version is not DRAFT        | Clone it: `lexq versions clone`                                     |
+| Publish rejected, 0 rules   | Add at least one rule before publishing                             |
+| `activationGroup` mismatch  | All groups in the same activationGroup must share mode and strategy |
+| `WH-` error on subscription | Webhook URL must be HTTPS and return 2xx for a POST                 |
+| Network error               | Check `lexq status` for API health                                  |
+
+`errorCode` is of the form `<domain>-<number>` (`P-002`, `ACT-016`). See `lexq-shared/SKILL.md` for the prefix table.

package/CONTEXT.md

@@ -11,6 +11,8 @@ simulation, deploy to production, and execute via REST API — all without modif
 - A/B testing for rule versions
 - Git-style versioning with full audit trail
 - Platform event webhooks for deployment lifecycle notifications
+- Decision Replay — re-evaluate past decisions against a candidate version
+- Decision Provenance — deterministic "why" for every recorded decision
 
 ## Architecture
 
@@ -49,14 +51,11 @@ Tenant
  ├── PolicyGroup (ACTIVE | DISABLED | ARCHIVED)
  │    ├── PolicyVersion (DRAFT → ACTIVE → ARCHIVED | EXPIRED)
  │    │    └── PolicyRule (condition + actions, priority-ordered)
- │    ├── PolicyDeployment (PUBLISH | DEPLOY | ROLLBACK | UNDEPLOY)
+ │    ├── PolicyDeployment (DEPLOY | ROLLBACK | UNDEPLOY)
  │    └── A/B Test (testVersionId + trafficRate)
  │
  ├── FactDefinition (key, type, displayName — shared across all groups)
  │
- ├── Integration (WEBHOOK | COUPON | POINT | NOTIFICATION | CRM | MESSENGER)
- │                — fires on rule match (per-rule configured)
- │
  └── WebhookSubscription (subscribedEvents + webhookUrl + payloadFormat)
       — fires on platform events (deployment lifecycle)
 ```
@@ -83,7 +82,9 @@ Tenant
 ### Condition Operators
 
 `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `CONTAINS`, `IN`,
-`NOT_IN`
+`NOT_IN`, `HAS_ANY`, `HAS_ALL`, `HAS_NONE`
+
+`HAS_*` are for LIST-typed facts only. `IN` / `NOT_IN` are their mirror — scalar fact, list value.
 
 ### Value Types
 
@@ -91,7 +92,7 @@ Tenant
 
 ### Action Types
 
-`MUTATE_FACT`, `INCREMENT_FACT`, `EMIT_EVENT`, `BLOCK`, `EMIT_NOTIFICATION`, `EMIT_WEBHOOK`, `SET_FACT`, `ADD_TAG`
+`MUTATE_FACT`, `SET_FACT`, `BLOCK`
 
 ### Conflict Resolution Modes
 
@@ -99,12 +100,13 @@ Tenant
 
 ### Conflict Resolution Strategies
 
-`FIRST_MATCH`, `HIGHEST_PRIORITY`, `MAX_BENEFIT`
+`HIGHEST_PRIORITY`
 
 ### Deployment Types
 
-`PUBLISH` (DRAFT → ACTIVE), `DEPLOY` (ACTIVE → live traffic), `ROLLBACK` (revert to previous), `UNDEPLOY` (remove from
-live)
+`DEPLOY` (ACTIVE → live traffic), `ROLLBACK` (revert to previous), `UNDEPLOY` (remove from live)
+
+Publishing (DRAFT → ACTIVE) is a qualification event, not a deployment — it has no `DeploymentType`.
 
 ### Execution Statuses
 
@@ -116,51 +118,43 @@ live)
 
 ### Decision Statuses
 
-`SELECTED`, `NO_MATCH`, `NOT_SELECTED`, `BLOCKED_MUTEX`, `LOST_PRIORITY`, `DROPPED_LIMIT`, `ERROR`
+`SELECTED`, `NO_MATCH`, `BLOCKED`, `ERROR`
+
+`BLOCKED` means the rule matched but lost conflict resolution — the round and reason are in `reasonCode` (
+`MUTEX_PRIORITY_LOST`, `GROUP_LIMIT_REACHED`, …). It is unrelated to the `BLOCK` action, whose rule stays `SELECTED`.
+
+`NOT_SELECTED` exists in the enum but the engine never produces it (reserved for effective-date filtering, not yet
+implemented).
 
 ### Platform Event Types (for webhook subscriptions)
 
-`VERSION_PUBLISHED`, `DEPLOYED`, `ROLLED_BACK`, `UNDEPLOYED`
+`VERSION_PUBLISHED`, `DEPLOYED`, `ROLLED_BACK`, `UNDEPLOYED`, `DEPLOY_SCHEDULED`, `DEPLOY_SCHEDULE_CANCELED`
 
 ### Webhook Payload Formats
 
 `GENERIC` (full JSON payload), `SLACK` (`{"text": "..."}` simplified)
 
-## Integration vs Webhook Subscription
-
-Two distinct webhook mechanisms — do not confuse them:
-
-| Concern       | **Integration** (WEBHOOK type)             | **WebhookSubscription**                           |
-|---------------|--------------------------------------------|---------------------------------------------------|
-| When it fires | Rule match during execution                | Platform event (publish/deploy/rollback/undeploy) |
-| Configured at | Per-rule action                            | Per-tenant subscription                           |
-| Payload       | Rule-defined template                      | Standard platform event schema                    |
-| Use case      | "Notify when VIP makes a purchase"         | "Notify Slack when a policy is deployed"          |
-| Signing       | Optional (HMAC via Integration.credential) | Optional HMAC-SHA256 via `secret`                 |
-| Formats       | Free-form (any)                            | GENERIC or SLACK                                  |
-
 ## Glossary
 
-| Term                     | Definition                                                                                                                           |
-|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| **Policy Group**         | Top-level container for rule versions. Controls deployment lifecycle, conflict resolution, and A/B testing.                          |
-| **Policy Version**       | An immutable snapshot of rules. Only DRAFT versions can be modified.                                                                 |
-| **Policy Rule**          | A condition → actions pair. Evaluated in priority order within a version.                                                            |
-| **Fact**                 | An input variable passed during execution. Declared via Fact Definitions with key, type, and name.                                   |
-| **Fact Definition**      | Schema declaration for a fact — its key (snake_case), value type, display name, and description.                                     |
-| **Dry Run**              | Single-input test execution. Returns which rules matched, what actions would fire, and decision traces.                              |
-| **Simulation**           | Batch test replaying historical executions against a version. Compares with a baseline.                                              |
-| **Activation Group**     | A logical grouping of Policy Groups for cross-group conflict resolution.                                                             |
-| **Mutex Group**          | A logical grouping of Policy Rules within a version for intra-version conflict resolution.                                           |
-| **Deployment**           | The act of putting an ACTIVE version into production to receive traffic.                                                             |
-| **Rollback**             | Reverting to the previously deployed version. Creates a new deployment record.                                                       |
-| **Undeploy**             | Removing a group from live traffic. No version serves requests until re-deployed.                                                    |
-| **A/B Test**             | Splitting traffic between the current live version and a test version by percentage.                                                 |
-| **Execution Trace**      | Per-rule evaluation result showing whether the condition matched and what actions were generated.                                    |
-| **Decision Trace**       | Final disposition of a rule after conflict resolution (SELECTED, BLOCKED_MUTEX, etc.).                                               |
-| **Snapshot Hash**        | SHA-256 hash of a version's rule snapshot at deployment time. Used to verify integrity.                                              |
-| **Traffic Rate**         | Percentage (0–100) of traffic routed to the A/B test version.                                                                        |
-| **Integration**          | An external service binding (WEBHOOK, COUPON, POINT, NOTIFICATION, CRM, MESSENGER) referenced by rule actions. Fires per rule match. |
-| **Webhook Subscription** | A platform event listener — receives notifications on deployment lifecycle events. Tenant-level, independent from Integrations.      |
-| **Platform Event**       | A lifecycle event emitted by the engine itself (VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED).                               |
-| **Failure Log**          | A record of a background task failure (webhook delivery, coupon issuance, etc.) available for retry/resolve/ignore.                  |
+| Term                     | Definition                                                                                                                                                     |
+|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Policy Group**         | Top-level container for rule versions. Controls deployment lifecycle, conflict resolution, and A/B testing.                                                    |
+| **Policy Version**       | An immutable snapshot of rules. Only DRAFT versions can be modified.                                                                                           |
+| **Policy Rule**          | A condition → actions pair. Evaluated in priority order within a version.                                                                                      |
+| **Fact**                 | An input variable passed during execution. Declared via Fact Definitions with key, type, and name.                                                             |
+| **Fact Definition**      | Schema declaration for a fact — its key (snake_case), value type, display name, and description.                                                               |
+| **Dry Run**              | Single-input test execution. Returns which rules matched, what actions would fire, and decision traces.                                                        |
+| **Simulation**           | Batch test replaying historical executions against a version. Compares with a baseline.                                                                        |
+| **Activation Group**     | A logical grouping of Policy Groups for cross-group conflict resolution.                                                                                       |
+| **Mutex Group**          | A logical grouping of Policy Rules within a version for intra-version conflict resolution.                                                                     |
+| **Deployment**           | The act of putting an ACTIVE version into production to receive traffic.                                                                                       |
+| **Rollback**             | Reverting to the previously deployed version. Creates a new deployment record.                                                                                 |
+| **Undeploy**             | Removing a group from live traffic. No version serves requests until re-deployed.                                                                              |
+| **A/B Test**             | Splitting traffic between the current live version and a test version by percentage.                                                                           |
+| **Execution Trace**      | Per-rule evaluation result showing whether the condition matched and what actions were generated.                                                              |
+| **Decision Trace**       | Final disposition of a rule after conflict resolution (`SELECTED`, `BLOCKED`, …), with a `reasonCode` explaining why.                                          |
+| **Snapshot Hash**        | SHA-256 hash of a version's rule snapshot at deployment time. Used to verify integrity.                                                                        |
+| **Traffic Rate**         | Percentage (1–99) of traffic routed to the A/B test version.                                                                                                   |
+| **Webhook Subscription** | A platform event listener — receives notifications on deployment lifecycle events. Tenant-level.                                                               |
+| **Platform Event**       | A lifecycle event emitted by the engine itself (`VERSION_PUBLISHED`, `DEPLOYED`, `ROLLED_BACK`, `UNDEPLOYED`, `DEPLOY_SCHEDULED`, `DEPLOY_SCHEDULE_CANCELED`). |
+| **Failure Log**          | A record of a background task failure (platform webhook delivery, scheduled deployment). Mark as `RESOLVE` or `IGNORE` — there is no retry.                    |

package/README.md

@@ -59,7 +59,7 @@ lexq domain-templates apply --template ECOMMERCE
 # Returns: policyGroupId, policyVersionId, factsCreated, rulesCreated
 
 # 4. Test a rule against your data before shipping
-lexq analytics dry-run --version-id <VERSION_ID> --debug --mock \
+lexq analytics dry-run --version-id <VERSION_ID> --debug \
   --json '{"facts":{"loyalty_tier":"PLATINUM","purchase_subtotal_usd":150}}'
 
 # 5. Deploy
@@ -159,7 +159,7 @@ skills/
 ├── 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, Impact Simulation, compare
-├── lexq-execution/SKILL.md    Execution history, stats, failure logs
+├── lexq-execution/SKILL.md    History, stats, failure logs, provenance, replay, latency profile
 └── lexq-recipes/SKILL.md      End-to-end recipes
 
 .claude/CLAUDE.md              Claude Code project context
@@ -181,19 +181,21 @@ node_modules/@lexq/cli/CONTEXT.md
 lexq auth                  login | logout | whoami
 lexq status                API health check
 lexq serve                 Run as MCP stdio server (--mcp)
-lexq groups                list | get | create | update | delete
+lexq groups                list | get | create | update | delete | reorder
 lexq groups ab-test        start | stop | adjust
 lexq versions              list | get | create | update | delete | clone
 lexq rules                 list | get | create | update | delete | reorder | toggle
-lexq facts                 list | create | update | delete | action-metadata
+lexq facts                 list | create | update | delete | action-metadata | unregistered
 lexq domain-templates      list | preview | apply
-lexq deploy                publish | live | rollback | undeploy | history | detail | overview | deployable | diff
+lexq deploy                publish | live | rollback | undeploy | history | detail | overview | deployable | diff | schedule | unschedule | schedules
 lexq analytics             dry-run | dry-run-compare | requirements
 lexq analytics simulation  start | status | list | cancel | export
 lexq analytics dataset     upload | template
+lexq profile               <groupId> — per-rule latency profile
 lexq history               list | get | stats
-lexq integrations          list | get | save | delete | config-spec
+lexq replay                decision | start | list | get | cancel
 lexq logs                  list | get | action | bulk-action
+lexq provenance            get | reveal-audits
 lexq webhook-subscriptions list | get | save | delete | test
 ```