@lexq/cli 1.0.2 → 1.1.1

package/AGENTS.md

@@ -180,8 +180,12 @@ The MCP toolset mirrors the CLI command inventory one-to-one.
 - Releasing is two steps, in this order. Raise `version` in package.json inside the pull request, so a reviewer
   sees the number beside the change that justifies it. After it merges, push the matching `v<version>` tag — that
   tag is what publishes. A tag that disagrees with package.json is rejected before anything reaches npm.
-- Pick the number by what breaks. On 0.x a breaking change is a minor bump (0.1 → 0.2), not a patch. Raising the
-  Node floor, a peer dependency major, or any change to what `tools/list` returns is breaking.
+- Pick the number by what breaks. A change is breaking when a call that used to work now fails or does something
+  else. That includes removing or renaming a tool, command, option or parameter, changing a parameter's type,
+  adding a required parameter or making an optional one required, and narrowing the values a parameter accepts.
+  Raising the Node floor or moving a peer dependency to a new major version is breaking too. A breaking change
+  raises the major number. A new tool, command, option or optional parameter raises the minor, and anything else,
+  including a changed description, raises the patch.
 - Gates before commit: `pnpm typecheck` (zero errors), `pnpm lint` (zero warnings), `pnpm test:fact-key`,
   `pnpm test:decimals`.
 - Multi-line CLI help and MCP tool descriptions use `dedent` — template-literal indentation leaks into LLM context.

package/dist/index.js

@@ -804,18 +804,18 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).option("--clear-effective-from", "Remove the effective start").option("--clear-effective-to", "Remove the effective end").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent4`
 
         Only DRAFT versions can be updated. Published (ACTIVE) versions are immutable.
 
-        An omitted --commit-message keeps its value, but --effective-from and --effective-to
-        are replaced together: one you omit is cleared. To keep the effective window, pass
-        both current values (read them with lexq versions get).
+        Omitted options keep their current values. To remove an end of the effective
+        window, pass --clear-effective-from or --clear-effective-to instead of a value.
 
-        Example:
+        Examples:
           $ lexq versions update --group-id <gid> --id <vid> --commit-message "Updated rules"
+          $ lexq versions update --group-id <gid> --id <vid> --clear-effective-to
       `
   ).action(async (opts) => {
     try {
@@ -911,6 +911,8 @@ function buildUpdateBody(opts) {
   if (opts.commitMessage) body.commitMessage = opts.commitMessage;
   if (opts.effectiveFrom) body.effectiveFrom = opts.effectiveFrom;
   if (opts.effectiveTo) body.effectiveTo = opts.effectiveTo;
+  if (opts.clearEffectiveFrom) body.clearEffectiveFrom = true;
+  if (opts.clearEffectiveTo) body.clearEffectiveTo = true;
   return body;
 }
 
@@ -1326,7 +1328,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
@@ -1642,6 +1646,7 @@ function registerDeployCommands(program) {
 
         Locks the version permanently. Rules cannot be modified after publishing.
         A snapshot hash is generated for integrity verification.
+        A version whose effective end has already passed cannot be published (P-058).
 
         Example:
           $ lexq deploy publish --group-id <gid> --version-id <vid> --memo "Validated via dry-run"
@@ -1672,6 +1677,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Takes effect immediately. The version starts receiving production traffic.
+        A version whose effective start has not arrived (P-037) or whose effective end
+        has passed (P-058) is rejected.
 
         Example:
           $ lexq deploy live --group-id <gid> --version-id <vid> --memo "Go live — v3"
@@ -1698,7 +1705,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Reverts to the version that was live before the current one.
-        Only available if the previous version is still ACTIVE.
+        Only available if the previous version is still ACTIVE and its effective end
+        has not passed (P-058).
 
         Example:
           $ lexq deploy rollback --group-id <gid> --memo "High error rate" --force
@@ -2201,7 +2209,7 @@ function registerAnalyticsCommands(program) {
         Use --format table for summary view.
       `
   );
-  sim.command("start").description("Start a new batch simulation").requiredOption("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
+  sim.command("start").description("Start a new batch simulation").option("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
     "after",
     dedent8`
 
@@ -2220,7 +2228,9 @@ function registerAnalyticsCommands(program) {
                 "maxRecords": 1000
               }
             }'
-            
+
+          $ lexq analytics simulation start --file simulation.json
+
         Dataset types: HISTORICAL, UPLOADED, MANUAL
         Dataset sources: EXECUTION_LOGS, S3_BUCKET, REQUEST_BODY
         HISTORICAL from / to are yyyy-MM-dd, whole days in the organization time zone, both inclusive.
@@ -2228,6 +2238,9 @@ function registerAnalyticsCommands(program) {
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
+      if (!opts.json && !opts.file) {
+        throw new Error("Request body is required. Use --json or --file.");
+      }
       const body = resolveBody(opts);
       const data = await apiRequest("POST", "analytics/simulations", {
         apiKey: globalOpts.apiKey,
@@ -2578,7 +2591,7 @@ function registerProfileCommands(program) {
   program.command("profile <groupId>").description("Per-rule latency profile with relative slow-rule flags").option(
     "--rule <ruleId>",
     `Single-rule detail (distributions + ${LATENCY_WINDOW_MILLIS / 1e3}s window series)`
-  ).option("--version <versionId>", "Version to inspect (default: live version)").option(
+  ).option("--version-id <versionId>", "Version to inspect (default: live version)").option(
     "--from <instant>",
     `Window start, ISO-8601 instant (default: ${PROFILE_DEFAULT_WINDOW_HOURS}h ago)`
   ).option("--to <instant>", "Window end, ISO-8601 instant (default: now)").option("--cache <state>", "Cache dimension for the rule table: HIT | MISS (default: HIT)").addHelpText(
@@ -2594,7 +2607,7 @@ function registerProfileCommands(program) {
         Examples:
           $ lexq profile <groupId>
           $ lexq profile <groupId> --cache MISS --from 2026-07-01T00:00:00Z
-          $ lexq profile <groupId> --rule <ruleId> --version <versionId>
+          $ lexq profile <groupId> --rule <ruleId> --version-id <versionId>
       `
   ).action(async (groupId, opts) => {
     try {
@@ -2604,7 +2617,7 @@ function registerProfileCommands(program) {
         throw new Error(`--cache must be one of: ${ProfileCacheState.join(" | ")}`);
       }
       const params = {};
-      if (opts.version) params.versionId = opts.version;
+      if (opts.versionId) params.versionId = opts.versionId;
       if (opts.from) params.from = opts.from;
       if (opts.to) params.to = opts.to;
       if (opts.cache) params.cacheState = opts.cache;
@@ -3743,13 +3756,15 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
-        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -3829,7 +3844,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.
 
@@ -3858,8 +3878,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
@@ -3877,8 +3898,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.
@@ -3903,7 +3926,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"),
@@ -4082,7 +4105,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")
@@ -4092,7 +4115,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, INV-4). 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")
@@ -4125,7 +4148,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 (INV-4); call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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"),
@@ -4139,7 +4162,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -4155,7 +4178,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")

package/dist/mcp/register.js

@@ -321,13 +321,15 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
-        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -407,7 +409,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.
 
@@ -436,8 +443,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
@@ -455,8 +463,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.
@@ -481,7 +491,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"),
@@ -664,7 +674,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")
@@ -674,7 +684,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, INV-4). 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")
@@ -707,7 +717,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 (INV-4); call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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"),
@@ -721,7 +731,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -737,7 +747,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "mcpName": "io.lexq/lexq",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
@@ -41,6 +41,7 @@
     "test:decimals": "pnpm build && node tests/exact-decimals.mjs",
     "test:fact-key": "node tests/fact-key.mjs",
     "test:export-format": "node tests/export-format.mjs",
+    "test:command-options": "node tests/command-options.mjs",
     "test:value-domain": "pnpm build && node tests/value-domain.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",

package/skills/lexq-execution/SKILL.md

@@ -253,7 +253,7 @@ lexq profile <groupId>
 lexq profile <groupId> --rule <ruleId>
 
 # Defaults: live version, last 24h, cache HIT
-lexq profile <groupId> --version <vid> --cache MISS \
+lexq profile <groupId> --version-id <vid> --cache MISS \
   --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z
 ```
 

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