@lexq/cli 1.1.0 → 1.1.2

package/AGENTS.md

@@ -5,7 +5,7 @@
 ## What is this?
 
 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.).
+evaluate input facts and produce actions: change a number such as a discount, set a fact, or record a rejection.
 
 The CLI also doubles as an **MCP server** — run `lexq serve --mcp` to expose the full command inventory as MCP tools to
 any MCP-compatible AI client.
@@ -106,7 +106,7 @@ lexq deploy live --group-id $GID --version-id $VID --memo "Initial deploy"
 
 ## Example: Subscribe to Deployment Notifications
 
-Webhook subscriptions fire on platform events — separate from rule-level webhooks.
+Webhook subscriptions fire on deployment lifecycle events.
 
 ```bash
 # Subscribe to Slack for deployment events

package/CONTEXT.md

@@ -64,11 +64,11 @@ Tenant
 
 ### Policy Group Status
 
-| Value      | Description                        |
-|------------|------------------------------------|
-| `ACTIVE`   | Normal operation                   |
-| `DISABLED` | Execution blocked (emergency stop) |
-| `ARCHIVED` | Permanently removed                |
+| Value      | Description                                                                                                         |
+|------------|---------------------------------------------------------------------------------------------------------------------|
+| `ACTIVE`   | Normal operation                                                                                                    |
+| `DISABLED` | Production execution rejected (`P-009`); dry run, simulation, and replay still work                                 |
+| `ARCHIVED` | Deleted. Kept for audit if it was ever executed, deployed, or replayed; otherwise permanently deleted after 30 days |
 
 ### Policy Version Status
 

package/README.md

@@ -48,7 +48,7 @@ Requires **Node.js 22+**.
 ```bash
 # 1. Authenticate
 lexq auth login
-# Enter your API key (create one at console.lexq.io → Management → API Keys)
+# Enter your API key (create one with the Manage scope at console.lexq.io → Management → API Keys)
 
 # 2. Verify
 lexq auth whoami

package/dist/index.js

@@ -163,6 +163,10 @@ import Table from "cli-table3";
 function printJson(data) {
   console.log(stringifyJson(data, 2));
 }
+function groupLabel(name, archivedAt, fallback = "\u2013") {
+  const label = name ?? fallback;
+  return archivedAt ? `(deleted) ${label}` : label;
+}
 function printTable(headers, rows, options) {
   const table = new Table({
     head: headers,
@@ -227,7 +231,8 @@ function registerAuthCommands(program) {
           whoami    Verify authentication and show account info
 
         Getting Started:
-          1. Get your API key from the LexQ Console (Settings → API Keys)
+          1. Create an API key with the Manage scope in the LexQ Console (Management → API Keys).
+             An "Execute only" key is for the execution API and does not work with this CLI.
           2. Run: lexq auth login
           3. Verify: lexq auth whoami
       `
@@ -269,7 +274,7 @@ function registerAuthCommands(program) {
 
         Example:
           $ lexq auth whoami
-          { "tenantId": "abc-123", "userId": "...", "role": "ADMIN", "tenantTimezone": "Asia/Seoul", "apiKey": "lexq_us_****abcd" }
+          { "tenantId": "abc-123", "userId": "...", "role": "API_ADMIN", "tenantTimezone": "Asia/Seoul", "apiKey": "lexq****abcd", "baseUrl": "https://api.lexq.io/api/v1/partners" }
       `
   ).action(async () => {
     try {
@@ -310,7 +315,7 @@ function registerStatusCommand(program) {
 
         Example:
           $ lexq status
-          { "status": "ok", "latencyMs": 142, "tenantId": "abc-123", "role": "ADMIN", "tenantTimezone": "Asia/Seoul" }
+          { "status": "ok", "latencyMs": 142, "tenantId": "abc-123", "role": "API_ADMIN", "tenantTimezone": "Asia/Seoul" }
 
         Use this to verify your API key is valid and the LexQ API is reachable.
         tenantTimezone is the zone every yyyy-MM-dd date option is read in.
@@ -342,6 +347,8 @@ var MAX_ROUNDING_SCALE = 34;
 var MIN_TRAFFIC_RATE = 1;
 var MAX_TRAFFIC_RATE = 99;
 var REPLAY_WINDOW_MAX_RECORDS = 5e4;
+var DEFAULT_SIMULATION_RECORDS = 1e3;
+var MAX_SIMULATION_RECORDS = 1e5;
 var PROFILE_SAMPLE_PERMILLE = 10;
 var LATENCY_WINDOW_MILLIS = 6e4;
 var TAIL_MIN_OBS = 3;
@@ -384,18 +391,21 @@ function registerGroupCommands(program) {
         It controls deployment lifecycle, conflict resolution, and A/B testing.
 
         Commands:
-          list        List all policy groups
+          list        List policy groups (deleted groups are not included)
           get         Get group detail by ID
           create      Create a new group
           update      Update group settings
-          reorder     Change group priorities (drag & drag equivalent)
+          reorder     Change group priorities (drag & drop equivalent)
           delete      Archive a group
           ab-test     Manage A/B tests (start, stop, adjust)
 
-        Statuses: ACTIVE, DISABLED (emergency stop), ARCHIVED (soft delete)
+        Statuses: ACTIVE, DISABLED, ARCHIVED
+          DISABLED stops production execution (403 P-009) and keeps the deployed version and any A/B test.
+          Dry run, simulation, and replay still work. Set ACTIVE to resume.
+          ARCHIVED means deleted. Only 'lexq groups delete' sets it, and it cannot be undone.
       `
   );
-  groups.command("list").description("List all policy groups").action(async () => {
+  groups.command("list").description("List policy groups (deleted groups are not included)").action(async () => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
@@ -490,6 +500,7 @@ ${data.length} total`);
           $ lexq groups update --id <groupId> --json '{"description": "Updated", "status": "DISABLED"}'
 
         All fields are optional — only provided fields are updated. priority is not settable here — use 'lexq groups reorder'.
+        A deleted group cannot be updated (409 P-059).
       `
   ).action(async (opts) => {
     try {
@@ -512,7 +523,15 @@ ${data.length} total`);
     "after",
     dedent3`
 
-        This archives the group (soft delete). Use --force to skip the confirmation prompt.
+        A deployed group cannot be deleted (P-020). Undeploy it first, which also ends a running A/B test.
+
+        A deleted group no longer appears in 'lexq groups list', and its name can be reused right away.
+        It cannot be restored, and calls that change it (settings, versions, rules, starting an A/B
+        test, publish, deploy, rollback, scheduling a deployment) return 409 P-059. If it was ever
+        executed, deployed, or replayed, it is kept for audit; otherwise it is permanently deleted
+        after 30 days.
+
+        Use --force to skip the confirmation prompt.
       `
   ).action(async (opts) => {
     try {
@@ -1328,7 +1347,9 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
     dedent6`
 
         Facts used in a version's rules that have no definition yet (read-only).
-        Does not block publish/deploy — register them to enable validation.
+        Keys a rule only reads do not block publish/deploy; register them to enable
+        validation. A SET_FACT or MUTATE_FACT targetVar must already be registered:
+        saving or publishing fails with ACT-032 otherwise.
 
         Example:
           $ lexq facts unregistered --group-id <gid> --version-id <vid> --format table
@@ -1799,7 +1820,7 @@ function registerDeployCommands(program) {
           data.content.map((d) => [
             d.id.substring(0, 8),
             d.deploymentType,
-            d.policyGroupName,
+            groupLabel(d.policyGroupName, d.policyGroupArchivedAt),
             d.versionNo != null ? `v${d.versionNo}` : "\u2013",
             d.deployedByName,
             utcMinute(d.deployedAt)
@@ -2022,7 +2043,11 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           ["Status", "Group", "Version", "Scheduled For", "By", "Result"],
           data.content.map((s) => [
             s.status,
-            s.policyGroupName ?? s.policyGroupId.substring(0, 8),
+            groupLabel(
+              s.policyGroupName,
+              s.policyGroupArchivedAt,
+              s.policyGroupId.substring(0, 8)
+            ),
             s.versionNo != null ? `v${s.versionNo}` : "\u2013",
             utcMinute(s.scheduledFor),
             s.scheduledByName,
@@ -2375,7 +2400,7 @@ function registerAnalyticsCommands(program) {
           ["ID", "Group", "Target", "Status", "Match", "Records", "Created"],
           data.content.map((s) => [
             s.simulationId.substring(0, 8),
-            s.policyGroupName,
+            groupLabel(s.policyGroupName, s.policyGroupArchivedAt),
             s.targetVersionName ?? "\u2013",
             s.status,
             `${s.matchRate.toFixed(1)}%`,
@@ -2736,12 +2761,12 @@ function registerHistoryCommands(program) {
           ["Trace", "Group", "Version", "Status", "Matched", "Latency", "At"],
           data.content.map((h) => [
             h.traceId.substring(0, 12),
-            h.policyGroupName ?? "\u2013",
+            groupLabel(h.policyGroupName, h.policyGroupArchivedAt),
             h.policyVersionNo != null ? `v${h.policyVersionNo}` : "\u2013",
             h.status,
             h.isMatched ? "\u2713" : "\u2717",
             `${h.latencyMs}ms`,
-            utcMinute(h.createdAt)
+            utcMinute(h.executedAt)
           ]),
           { truncate: 20 }
         );
@@ -3250,8 +3275,8 @@ function registerWebhookSubscriptionCommands(program) {
     "after",
     dedent14`
 
-        Receive notifications when deployment lifecycle events occur
-        (publish, deploy, rollback, undeploy).
+        Receive notifications for deployment lifecycle events: publish, deploy, rollback, and
+        undeploy, plus a deployment being scheduled or a schedule being canceled.
 
         Commands:
           list      List all webhook subscriptions
@@ -3260,8 +3285,8 @@ function registerWebhookSubscriptionCommands(program) {
           delete    Delete a subscription
           test      Send a test event to verify connectivity
 
-        This is separate from Integrations (rule action webhooks).
-        Webhook subscriptions are for platform-level event notifications.
+        Rule actions never call external systems. These subscriptions are how LexQ pushes deployment
+        events to you.
       `
   );
   webhooks.command("list").description("List webhook subscriptions").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
@@ -3346,7 +3371,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
         Fields:
           name                string      Subscription name (required, unique per tenant)
           webhookUrl          string      Webhook endpoint URL (required)
-          subscribedEvents    string[]    VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED
+          subscribedEvents    string[]    ${PlatformEventType.join(", ")}
           payloadFormat       string      GENERIC (full JSON) or SLACK ({"text":"..."})  [default: GENERIC]
           secret              string      HMAC-SHA256 signing secret (optional)
           isActive            boolean     Enable/disable (optional)  [default: true]
@@ -3560,7 +3585,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "List Policy Groups",
       annotations: { readOnlyHint: true },
-      description: "List all policy groups (tenant-wide, priority ASC).",
+      description: "List policy groups (tenant-wide, priority ASC). Deleted groups are not included.",
       inputSchema: z2.object({})
     },
     async () => callApi("GET", "policy-groups")
@@ -3613,12 +3638,14 @@ function registerGroupTools(server, callApi) {
     {
       title: "Update Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged.",
+      description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged. A deleted group cannot be updated (409 P-059).",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
         name: z2.string().optional().describe("New name"),
         description: z2.string().optional().describe("New description"),
-        status: z2.enum(["ACTIVE", "DISABLED"]).optional().describe("Status (DISABLED = emergency stop)"),
+        status: z2.enum(["ACTIVE", "DISABLED"]).optional().describe(
+          "DISABLED stops production execution of this group: execution calls return 403 (P-009), and a composite call that includes the group is rejected in full. The deployed version and any A/B test are kept, and dry run, Impact Simulation, and Decision Replay keep working, so a fix can be verified before setting ACTIVE again. To go back to the previous version, use lexq_deploy_rollback. To take the version out of production, use lexq_deploy_undeploy."
+        ),
         activationGroup: z2.string().optional().describe(
           "Activation group (Execution Group) cluster key. Policy groups sharing this key compete, and group priority picks the winners."
         ),
@@ -3636,7 +3663,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "Delete Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Archive a policy group. Only non-live groups can be deleted. This is irreversible.",
+      description: "Delete (archive) a policy group. A deployed group cannot be deleted (P-020); undeploy it first with lexq_deploy_undeploy, which also ends a running A/B test. This cannot be undone. The group no longer appears in lexq_groups_list and its name can be reused right away. Calls that change it (settings, versions, rules, starting an A/B test, publish, deploy, rollback, scheduling a deployment) return 409 P-059. If it was ever executed, deployed, or replayed, it is kept for audit; otherwise it is permanently deleted after 30 days.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
       })
@@ -3842,7 +3869,12 @@ function registerRuleTools(server, callApi) {
         If a required key is missing, ask the user to confirm the type, isRequired, and description
         before calling lexq_facts_create — registering facts enables type validation, Console UI
         autocomplete, and the dry-run requirements analyzer.
-        
+
+        An action's targetVar (SET_FACT, MUTATE_FACT) must be a registered fact. Saving or
+        publishing a rule whose targetVar is not registered fails with ACT-032, so register it
+        with lexq_facts_create first. Keys a rule only reads (condition fields, refVar) may stay
+        unregistered.
+
         After saving, lexq_facts_unregistered lists any keys this version references but has not
         defined (non-blocking, version-wide) — use it to decide what to register.
 
@@ -3871,8 +3903,9 @@ function registerRuleTools(server, callApi) {
 
         Action parameter schemas:
         - MUTATE_FACT: { targetVar: string, operator: "ASSIGN"|"ADD"|"SUB"|"MUL"|"DIV", method: "PERCENTAGE"|"AMOUNT", operand: number, refVar?: string, rounding?: RoundingOption }
-          targetVar is the fact this action reads and writes. It must exist in facts at execution
-          time as a number — supplied as an input fact or written by a prior action in this rule.
+          targetVar is the fact this action reads and writes. It must be a registered fact
+          (ACT-032 otherwise), and the request must send it (P-015 otherwise). Its value must be
+          a number when the action runs.
           A missing required fact throws (no 0 default).
           operand is the arithmetic operand; the unit is dictated by method (percent when
           PERCENTAGE, absolute amount when AMOUNT). Ranges are not constrained — negative values
@@ -3890,8 +3923,10 @@ function registerRuleTools(server, callApi) {
             DIV     targetVar /= operand             | invalid
           Constraints: DIV + PERCENTAGE is invalid (use MUL with the inverse). DIV + AMOUNT
           requires operand !== 0.
-        - SET_FACT: { targetVar: string, value: string|number|boolean } Creates the fact if absent
-          — this is the only action that does. MUTATE_FACT requires the target to already exist.
+        - SET_FACT: { targetVar: string, value: string|number|boolean } targetVar must be a
+          registered fact (ACT-032 otherwise). The request does not have to send it: SET_FACT is
+          the only action that can write a key absent from the input facts. MUTATE_FACT requires
+          its target to be present in the input facts.
         - BLOCK: { reason: string } Records a rejection decision. It does NOT halt rule execution —
           subsequent actions and subsequent winning rules still run. Enforcement is the caller's
           responsibility; the decision surfaces as the isBlocked fact.
@@ -3916,7 +3951,7 @@ function registerRuleTools(server, callApi) {
     {
       title: "Update Rule",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root.`,
+      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root. Saving re-checks every action in the rule, including ones you did not change, and fails with ACT-032 if any action's targetVar is not a registered fact.`,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
         versionId: z4.string().uuid().describe("Version ID"),
@@ -4055,13 +4090,13 @@ function registerFactTools(server, callApi) {
     {
       title: "Update Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Only the fields you send are changed. System facts accept name, description, and PII only.",
+      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Rules in deleted groups do not count. Only the fields you send are changed. System facts accept name, description, and PII only.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID"),
         name: z5.string().optional().describe("Display name"),
         description: z5.string().optional().describe("Description"),
         type: z5.enum(VALUE_TYPES).optional().describe(
-          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule outside a deleted group references the fact."
         ),
         isRequired: z5.boolean().optional().describe("Required flag"),
         isPii: z5.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)"),
@@ -4083,7 +4118,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Delete Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Remove the references first.",
+      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Rules in deleted groups do not count. Remove the references first.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID")
       })
@@ -4095,7 +4130,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Get Action Runtime Fact Metadata",
       annotations: { readOnlyHint: true },
-      description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. Facts are supplied as input or written by a prior action in the same rule; only SET_FACT creates a fact from nothing. Static data, safe to cache in-session.",
+      description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. These facts must be sent in the request (P-015 otherwise), even when an earlier action in the same rule writes them. SET_FACT requires no input fact: it is the only action that can write a key the request did not send, and its targetVar must be a registered fact (ACT-032). Static data, safe to cache in-session.",
       inputSchema: z5.object({})
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -4105,7 +4140,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only). Keys that rules only read do not block publish/deploy; a rule whose action targetVar is not a registered fact is rejected at save and publish with ACT-032. Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -4138,7 +4173,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
+      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts that rules only read do not block publishing; call lexq_facts_unregistered first to review them. Publishing fails if an action's targetVar is not a registered fact (ACT-032), if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -4395,7 +4430,8 @@ function registerAnalyticsTools(server, callApi) {
           UPLOADED   → source S3_BUCKET,      with dataset.path (the path returned by lexq_dataset_upload)
           MANUAL     → source REQUEST_BODY,   with dataset.manualData (array of fact records)
 
-        options.maxRecords: number (max 100000, default 10000)
+        options.maxRecords: number (max ${MAX_SIMULATION_RECORDS}). When omitted, HISTORICAL and UPLOADED run at
+          most ${DEFAULT_SIMULATION_RECORDS} records and MANUAL runs every record sent.
         options.baselinePolicyVersionId: uuid (optional, for baseline comparison)
         options.includeRuleStats: boolean
         options.metricConfig: optional — omit for plain execution count. To aggregate a fact, pass
@@ -4875,7 +4911,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     {
       title: "List Webhook Subscriptions",
       annotations: { readOnlyHint: true },
-      description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications (publish, deploy, rollback, undeploy).",
+      description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications: publish, deploy, rollback, and undeploy, plus a deployment being scheduled or a schedule being canceled.",
       inputSchema: z13.object({
         page: z13.number().int().min(0).default(0).describe("Page number"),
         size: z13.number().int().min(1).max(100).default(20).describe("Page size")
@@ -4903,7 +4939,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     {
       title: "Save Webhook Subscription",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: 'Create or update a webhook subscription. Omit id to create, provide id to update. Events: VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).',
+      description: `Create or update a webhook subscription. Omit id to create, provide id to update. Events: ${PlatformEventType.join(", ")}. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).`,
       inputSchema: z13.object({
         id: z13.string().uuid().optional().describe("Subscription ID (omit to create, provide to update)"),
         name: z13.string().min(1).describe("Subscription name (unique per tenant)"),

package/dist/mcp/register.js

@@ -37,6 +37,8 @@ var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 // src/types/constants.ts
 var MAX_ROUNDING_SCALE = 34;
 var REPLAY_WINDOW_MAX_RECORDS = 5e4;
+var DEFAULT_SIMULATION_RECORDS = 1e3;
+var MAX_SIMULATION_RECORDS = 1e5;
 var PROFILE_SAMPLE_PERMILLE = 10;
 var LATENCY_WINDOW_MILLIS = 6e4;
 var TAIL_MIN_OBS = 3;
@@ -58,7 +60,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "List Policy Groups",
       annotations: { readOnlyHint: true },
-      description: "List all policy groups (tenant-wide, priority ASC).",
+      description: "List policy groups (tenant-wide, priority ASC). Deleted groups are not included.",
       inputSchema: z2.object({})
     },
     async () => callApi("GET", "policy-groups")
@@ -111,12 +113,14 @@ function registerGroupTools(server, callApi) {
     {
       title: "Update Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged.",
+      description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged. A deleted group cannot be updated (409 P-059).",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
         name: z2.string().optional().describe("New name"),
         description: z2.string().optional().describe("New description"),
-        status: z2.enum(["ACTIVE", "DISABLED"]).optional().describe("Status (DISABLED = emergency stop)"),
+        status: z2.enum(["ACTIVE", "DISABLED"]).optional().describe(
+          "DISABLED stops production execution of this group: execution calls return 403 (P-009), and a composite call that includes the group is rejected in full. The deployed version and any A/B test are kept, and dry run, Impact Simulation, and Decision Replay keep working, so a fix can be verified before setting ACTIVE again. To go back to the previous version, use lexq_deploy_rollback. To take the version out of production, use lexq_deploy_undeploy."
+        ),
         activationGroup: z2.string().optional().describe(
           "Activation group (Execution Group) cluster key. Policy groups sharing this key compete, and group priority picks the winners."
         ),
@@ -134,7 +138,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "Delete Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Archive a policy group. Only non-live groups can be deleted. This is irreversible.",
+      description: "Delete (archive) a policy group. A deployed group cannot be deleted (P-020); undeploy it first with lexq_deploy_undeploy, which also ends a running A/B test. This cannot be undone. The group no longer appears in lexq_groups_list and its name can be reused right away. Calls that change it (settings, versions, rules, starting an A/B test, publish, deploy, rollback, scheduling a deployment) return 409 P-059. If it was ever executed, deployed, or replayed, it is kept for audit; otherwise it is permanently deleted after 30 days.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
       })
@@ -409,7 +413,12 @@ function registerRuleTools(server, callApi) {
         If a required key is missing, ask the user to confirm the type, isRequired, and description
         before calling lexq_facts_create — registering facts enables type validation, Console UI
         autocomplete, and the dry-run requirements analyzer.
-        
+
+        An action's targetVar (SET_FACT, MUTATE_FACT) must be a registered fact. Saving or
+        publishing a rule whose targetVar is not registered fails with ACT-032, so register it
+        with lexq_facts_create first. Keys a rule only reads (condition fields, refVar) may stay
+        unregistered.
+
         After saving, lexq_facts_unregistered lists any keys this version references but has not
         defined (non-blocking, version-wide) — use it to decide what to register.
 
@@ -438,8 +447,9 @@ function registerRuleTools(server, callApi) {
 
         Action parameter schemas:
         - MUTATE_FACT: { targetVar: string, operator: "ASSIGN"|"ADD"|"SUB"|"MUL"|"DIV", method: "PERCENTAGE"|"AMOUNT", operand: number, refVar?: string, rounding?: RoundingOption }
-          targetVar is the fact this action reads and writes. It must exist in facts at execution
-          time as a number — supplied as an input fact or written by a prior action in this rule.
+          targetVar is the fact this action reads and writes. It must be a registered fact
+          (ACT-032 otherwise), and the request must send it (P-015 otherwise). Its value must be
+          a number when the action runs.
           A missing required fact throws (no 0 default).
           operand is the arithmetic operand; the unit is dictated by method (percent when
           PERCENTAGE, absolute amount when AMOUNT). Ranges are not constrained — negative values
@@ -457,8 +467,10 @@ function registerRuleTools(server, callApi) {
             DIV     targetVar /= operand             | invalid
           Constraints: DIV + PERCENTAGE is invalid (use MUL with the inverse). DIV + AMOUNT
           requires operand !== 0.
-        - SET_FACT: { targetVar: string, value: string|number|boolean } Creates the fact if absent
-          — this is the only action that does. MUTATE_FACT requires the target to already exist.
+        - SET_FACT: { targetVar: string, value: string|number|boolean } targetVar must be a
+          registered fact (ACT-032 otherwise). The request does not have to send it: SET_FACT is
+          the only action that can write a key absent from the input facts. MUTATE_FACT requires
+          its target to be present in the input facts.
         - BLOCK: { reason: string } Records a rejection decision. It does NOT halt rule execution —
           subsequent actions and subsequent winning rules still run. Enforcement is the caller's
           responsibility; the decision surfaces as the isBlocked fact.
@@ -483,7 +495,7 @@ function registerRuleTools(server, callApi) {
     {
       title: "Update Rule",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root.`,
+      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root. Saving re-checks every action in the rule, including ones you did not change, and fails with ACT-032 if any action's targetVar is not a registered fact.`,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
         versionId: z4.string().uuid().describe("Version ID"),
@@ -626,13 +638,13 @@ function registerFactTools(server, callApi) {
     {
       title: "Update Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Only the fields you send are changed. System facts accept name, description, and PII only.",
+      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Rules in deleted groups do not count. Only the fields you send are changed. System facts accept name, description, and PII only.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID"),
         name: z5.string().optional().describe("Display name"),
         description: z5.string().optional().describe("Description"),
         type: z5.enum(VALUE_TYPES).optional().describe(
-          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule outside a deleted group references the fact."
         ),
         isRequired: z5.boolean().optional().describe("Required flag"),
         isPii: z5.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)"),
@@ -654,7 +666,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Delete Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Remove the references first.",
+      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Rules in deleted groups do not count. Remove the references first.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID")
       })
@@ -666,7 +678,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Get Action Runtime Fact Metadata",
       annotations: { readOnlyHint: true },
-      description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. Facts are supplied as input or written by a prior action in the same rule; only SET_FACT creates a fact from nothing. Static data, safe to cache in-session.",
+      description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. These facts must be sent in the request (P-015 otherwise), even when an earlier action in the same rule writes them. SET_FACT requires no input fact: it is the only action that can write a key the request did not send, and its targetVar must be a registered fact (ACT-032). Static data, safe to cache in-session.",
       inputSchema: z5.object({})
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -676,7 +688,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only). Keys that rules only read do not block publish/deploy; a rule whose action targetVar is not a registered fact is rejected at save and publish with ACT-032. Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -709,7 +721,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
+      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts that rules only read do not block publishing; call lexq_facts_unregistered first to review them. Publishing fails if an action's targetVar is not a registered fact (ACT-032), if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -966,7 +978,8 @@ function registerAnalyticsTools(server, callApi) {
           UPLOADED   → source S3_BUCKET,      with dataset.path (the path returned by lexq_dataset_upload)
           MANUAL     → source REQUEST_BODY,   with dataset.manualData (array of fact records)
 
-        options.maxRecords: number (max 100000, default 10000)
+        options.maxRecords: number (max ${MAX_SIMULATION_RECORDS}). When omitted, HISTORICAL and UPLOADED run at
+          most ${DEFAULT_SIMULATION_RECORDS} records and MANUAL runs every record sent.
         options.baselinePolicyVersionId: uuid (optional, for baseline comparison)
         options.includeRuleStats: boolean
         options.metricConfig: optional — omit for plain execution count. To aggregate a fact, pass
@@ -1446,7 +1459,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     {
       title: "List Webhook Subscriptions",
       annotations: { readOnlyHint: true },
-      description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications (publish, deploy, rollback, undeploy).",
+      description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications: publish, deploy, rollback, and undeploy, plus a deployment being scheduled or a schedule being canceled.",
       inputSchema: z13.object({
         page: z13.number().int().min(0).default(0).describe("Page number"),
         size: z13.number().int().min(1).max(100).default(20).describe("Page size")
@@ -1474,7 +1487,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     {
       title: "Save Webhook Subscription",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: 'Create or update a webhook subscription. Omit id to create, provide id to update. Events: VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).',
+      description: `Create or update a webhook subscription. Omit id to create, provide id to update. Events: ${PlatformEventType.join(", ")}. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).`,
       inputSchema: z13.object({
         id: z13.string().uuid().optional().describe("Subscription ID (omit to create, provide to update)"),
         name: z13.string().min(1).describe("Subscription name (unique per tenant)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "mcpName": "io.lexq/lexq",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",

package/skills/lexq-groups/SKILL.md

@@ -17,9 +17,24 @@ controls conflict resolution when multiple groups interact.
 | `DISABLED` | `ARCHIVED` | **no**                            |
 
 - **ACTIVE** — executions are processed.
-- **DISABLED** — all executions are blocked. Use for emergency stop.
+- **DISABLED** — production execution stops. Execution calls return `P-009` (403), and a composite call that includes
+  the group is rejected in full. The live version and any A/B test are kept, and dry run, Impact Simulation, and
+  Decision Replay keep working, so you can verify a fix before setting `ACTIVE` again.
 - **ARCHIVED** — removed from execution. Reached only through `lexq groups delete`, not by setting `status` directly.
 
+### Disable, Roll Back, or Undeploy?
+
+| Situation                                                             | Use                    | Callers get                                                            |
+|-----------------------------------------------------------------------|------------------------|------------------------------------------------------------------------|
+| The previously deployed version is correct                            | `lexq deploy rollback` | Decisions from the previous version                                    |
+| This version has to leave production                                  | `lexq deploy undeploy` | `P-019` (400). Composite calls skip the group. A running A/B test ends |
+| Stop now without knowing the cause, then resume with the same version | `status: DISABLED`     | `P-009` (403). Composite calls that include the group are rejected     |
+
+Do not disable a group for a planned end, such as a promotion with a known end date. Set the version's `effectiveTo`
+instead. When that time passes, the group switches to its newest `ACTIVE` version that is still in effect, or is
+undeployed if there is none. Composite calls keep working either way. A disabled group rejects every composite call
+that includes it.
+
 ## CRUD Commands
 
 ### List Groups
@@ -93,20 +108,31 @@ lexq groups delete --id <groupId>
 lexq groups delete --id <groupId> --force
 ```
 
-**`delete` archives — it does not erase.** The group becomes `ARCHIVED` and stops executing;
-versions, rules, and history are retained for audit. Deleting an already-archived group is a
-no-op.
+**`delete` archives — it does not erase right away.** The group becomes `ARCHIVED` and stops
+executing. If it was ever executed, deployed, or replayed, it is kept for audit, along with its
+versions and rules. Otherwise it is permanently deleted after 30 days, together with its
+versions, rules, simulations, and schedules. Deleting an already-archived group is a no-op.
 
-Two conditions block it:
-
-| Condition              | What to do first                                    |
-|------------------------|-----------------------------------------------------|
-| The group is deployed  | `lexq deploy undeploy --group-id <gid>`             |
-| An A/B test is running | `lexq groups ab-test stop --group-id <gid> --force` |
+A deployed group cannot be deleted (`P-020`). Undeploy it first with
+`lexq deploy undeploy --group-id <gid> --memo "<reason>"`, which also ends a running A/B test.
 
 Archiving cancels any pending scheduled deployment and closes the priority gap — remaining groups
 are renumbered 1…N.
 
+A deleted group no longer appears in `lexq groups list` and cannot be restored or changed.
+Changing its settings, versions, or rules, starting an A/B test, and publishing, deploying,
+rolling back, or scheduling a deployment all return `409` `P-059`. To start over, create a new
+group.
+
+**The name can be reused right away.** Records keep the group's ID and the name it had, so after
+a new group takes the name, deployment history, scheduled deployments, execution history,
+simulations, and replays can list two groups under that name. These records carry
+`policyGroupArchivedAt`, the time the group was deleted (`null` if it has not been). In the
+tables of `lexq deploy history`, `deploy schedules`, `history list`, and
+`analytics simulation list` (`--format table`), a deleted group's name shows as
+`(deleted) <name>`. To see one group's deployments or executions only, pass its ID to
+`lexq deploy history --group-id` or `lexq history list --group-id`.
+
 ## Conflict Resolution
 
 ### Activation Mode (across groups in the same `activationGroup`)
@@ -246,4 +272,5 @@ lets you reuse the existing group instead of handling the error.
 lexq groups update --id <groupId> --json '{"status": "DISABLED"}'
 ```
 
-This immediately stops all executions for the group. No undeploy needed.
+This immediately stops production execution for the group. Dry run, Impact Simulation, and Decision Replay keep
+working. No undeploy needed.

package/skills/lexq-recipes/SKILL.md

@@ -480,8 +480,10 @@ lexq analytics dry-run --version-id <vid> --debug --json '{
 
 **Notes**
 
-- `SET_FACT` creates the fact if it does not exist. `MUTATE_FACT` requires the target to already
-  be present — that is the division of labor between them.
+- Register a `SET_FACT` target before saving the rule, as the step above does. A rule whose
+  `targetVar` is not a registered fact is rejected with `ACT-032`.
+- At execution, `SET_FACT` writes the key even when the request did not send it. `MUTATE_FACT`
+  requires the request to send its target. That is the division of labor between them.
 - Flags appear in `generatedVariables` in the response. `SET_FACT` produces no `__delta` because
   it is an assignment, not an arithmetic change.
 - Segment on a `LIST_STRING` fact with `HAS_ANY` / `HAS_ALL` / `HAS_NONE`, not `CONTAINS`.

package/skills/lexq-rules/SKILL.md

@@ -181,14 +181,14 @@ Each rule can have multiple actions. Actions fire sequentially.
 | 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`                                                 |
+| `SET_FACT`    | Assign a literal value to a registered fact | `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.    |
+| `targetVar` | always   | The fact this action **reads and writes**. Must be registered and present as a number at execution. |
 | `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. |
@@ -235,8 +235,15 @@ Use `refVar` when the base differs from the target:
 
 ### `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.
+Both actions write to `targetVar`, and it must be a **registered fact**. Saving or publishing a
+rule whose `targetVar` is not registered fails with `ACT-032`; register it with
+`lexq facts create` first. Keys a rule only reads (condition fields, `refVar`) may stay
+unregistered.
+
+At execution, they differ in what the request must send. `SET_FACT` writes the value even when
+the request did not send the key. `MUTATE_FACT` requires the request to send the target (`P-015`
+otherwise), and the target's value must be a number when the action runs. "Write something the
+request didn't send" is `SET_FACT`'s job.
 
 ### `BLOCK` does not halt execution
 

package/skills/lexq-shared/SKILL.md

@@ -19,6 +19,9 @@ lexq auth login
 lexq auth whoami
 ```
 
+Create the key with the **Manage** scope in the Console (Management → API Keys). An **Execute only** key is
+for calling the execution API from your application and does not work with this CLI.
+
 The API key is passed as `X-API-KEY` header on every request. You can also override per-command:
 
 ```bash