@lexq/cli 3.0.0 → 3.0.2

package/AGENTS.md

@@ -46,7 +46,7 @@ Detailed documentation lives in the `skills/` directory. **Read the relevant ski
 2. **Always dry-run before publishing.** Run `lexq analytics dry-run` to validate.
 3. **Never modify a non-DRAFT version.** Check version status first. Clone if needed.
 4. **Always check facts before creating rules.** Run `lexq facts list` to know available keys and types.
-5. **Use `--format json` for parsing.** This is the default. Don't change it.
+5. **Leave `--format` at its default, `json`, and parse the output.** A command that writes a file chooses the file's format with `--as`, not `--format`.
 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. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.
@@ -175,8 +175,6 @@ The MCP toolset mirrors the CLI command inventory one-to-one.
 
 - CLI commands and MCP tools stay in lock-step — a new command lands with its MCP tool in the same PR, sharing
   the single api-client layer.
-- The hosted MCP server consumes this package from npm. Publish (`v*` tag) **before** redeploying it — CI cannot
-  catch that ordering.
 - 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.

package/CONTEXT.md

@@ -26,7 +26,7 @@ simulation, deploy to production, and execute via REST API — all without modif
 └─────────────────────────────────────────────────────┘
                          │
                          ▼
-              api.lexq.io (ALB, path-routed)
+                    api.lexq.io
                          │
           ┌──────────────┴──────────────┐
           ▼                             ▼
@@ -38,8 +38,7 @@ simulation, deploy to production, and execute via REST API — all without modif
                   LexQ Policy Engine
 ```
 
-The CLI exclusively calls the Partner API. Execution requests (runtime rule evaluation) use a separate path-routed
-endpoint.
+The CLI calls only the Partner API. Your service evaluates rules through the Execution API.
 
 **Partner Base URL:** `https://api.lexq.io/api/v1/partners`
 **Execution Base URL:** `https://api.lexq.io/api/v1/execution`
@@ -77,7 +76,7 @@ Tenant
 | `DRAFT`    | Editable. Rules can be added/modified.                   |
 | `ACTIVE`   | Published. Locked — no modifications allowed.            |
 | `ARCHIVED` | Superseded by a newer version.                           |
-| `EXPIRED`  | Past `effectiveTo` date. Auto-transitioned by scheduler. |
+| `EXPIRED`  | Past its `effectiveTo` date.                             |
 
 ### Condition Operators
 
@@ -123,8 +122,7 @@ Publishing (DRAFT → ACTIVE) is a qualification event, not a deployment — it
 `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).
+`NOT_SELECTED` is part of the enum but is not returned today.
 
 ### Platform Event Types (for webhook subscriptions)
 
@@ -153,7 +151,7 @@ implemented).
 | **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.                                                                        |
+| **Snapshot Hash**        | A fingerprint of a version's rules, recorded at deployment and used to check that the deployed rules did not change.                                           |
 | **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`). |

package/README.md

@@ -224,13 +224,15 @@ lexq webhook-subscriptions list | get | save | delete | test
 
 | Flag                     | Description                                |
 |--------------------------|--------------------------------------------|
-| `--format <json\|table>` | Output format (default: `json`)            |
+| `--format <json\|table>` | How results are printed (default: `json`)  |
 | `--api-key <key>`        | Override stored API key                    |
 | `--base-url <url>`       | Override API base URL                      |
 | `--dry-run`              | Preview the HTTP request without executing |
 | `--verbose`              | Show request/response details              |
 | `--no-color`             | Disable colored output                     |
 
+`--format` only changes how results are printed. A command that writes a file, such as `lexq facts export`, chooses the file's format with `--as csv` or `--as json`.
+
 ## Configuration
 
 Config is stored at `~/.lexq/config.json`:

package/dist/index.js

@@ -184,6 +184,14 @@ async function apiRequestWithMeta(method, path, options = {}) {
 
 // src/lib/output.ts
 import Table from "cli-table3";
+import { InvalidArgumentError } from "commander";
+var OUTPUT_FORMATS = ["json", "table"];
+function parseOutputFormat(value) {
+  if (OUTPUT_FORMATS.includes(value)) return value;
+  throw new InvalidArgumentError(
+    `Use ${OUTPUT_FORMATS.join(" or ")}. The format of an exported file is chosen with --as.`
+  );
+}
 function printJson(data) {
   console.log(stringifyJson(data, 2));
 }
@@ -394,6 +402,7 @@ var PURGE_AFTER_DAYS = 30;
 var DESCRIPTION_MAX_LENGTH = 255;
 var COMMIT_MESSAGE_MAX_LENGTH = 500;
 var SCHEDULE_TICK_MAX_MILLIS = 6e4;
+var MAX_DRY_RUN_EVALUATIONS_PER_MINUTE = 60;
 
 // src/commands/groups.ts
 import "commander";
@@ -784,7 +793,8 @@ function registerVersionCommands(program) {
 
         A version is an immutable snapshot of rules within a policy group.
 
-        Lifecycle: DRAFT → ACTIVE (publish) → ARCHIVED (superseded) | EXPIRED (past effectiveTo)
+        Lifecycle: DRAFT → ACTIVE (publish) → EXPIRED (past effectiveTo)
+        A version stays ACTIVE after a newer version goes live, so you can roll back to it.
 
         Commands:
           list      List versions for a group
@@ -1346,6 +1356,7 @@ function escapeUnsafe(json) {
 
 // src/lib/export.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+import { extname } from "path";
 var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
 function parseFormat(value) {
   if (typeof value === "string" && EXPORT_FORMATS.includes(value)) {
@@ -1355,6 +1366,25 @@ function parseFormat(value) {
     `Unsupported export format: ${String(value)}. Use ${EXPORT_FORMATS.join(" or ")}.`
   );
 }
+function fileFormat(command) {
+  const opts = command.opts();
+  const format = parseFormat(opts.as);
+  const extension = typeof opts.output === "string" ? extname(opts.output).slice(1).toLowerCase() : "";
+  let root = command;
+  while (root.parent) root = root.parent;
+  if (EXPORT_FORMATS.includes(extension)) {
+    if (extension !== format) {
+      console.error(
+        `Note: ${opts.output} will hold ${format}. Pass --as ${extension} to write ${extension}.`
+      );
+    }
+  } else if (root.getOptionValueSource("format") === "cli" && command.getOptionValueSource("as") !== "cli") {
+    console.error(
+      `Note: --format sets how results are printed, not the file. This file is ${format}; choose ${EXPORT_FORMATS.join(" or ")} with --as.`
+    );
+  }
+  return format;
+}
 async function runExport(path, format, options) {
   const { output, params, ...clientOptions } = options;
   const body = await apiRequest("GET", path, {
@@ -1510,7 +1540,7 @@ ${data.length} unregistered`);
                       STRING types take --allowed-values. NUMBER types take all three.
                       BOOLEAN takes none — it has only two values to begin with.
                       For list types the value domain applies to each element.
-                      Leave them out for no value domain, which is how facts behaved before.
+                      Leave them out for no value domain.
       `
   ).action(async (opts) => {
     try {
@@ -1621,10 +1651,10 @@ ${warning}
           $ lexq facts export --as json --output facts.json
           $ lexq facts export --keyword user --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport("schema/facts/export", parseFormat(opts.as), {
+      await runExport("schema/facts/export", fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -2072,8 +2102,8 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
     "after",
     dedent7`
 
-        The version must be ACTIVE with a future effective start date; the system
-        deploys it automatically at that time (within one scheduler tick, ≤${SCHEDULE_TICK_MAX_MILLIS / 1e3}s).
+        The version must be ACTIVE with a future effective start date; it is
+        deployed automatically within ${SCHEDULE_TICK_MAX_MILLIS / 1e3} seconds after that time.
         That time is the version's effectiveFrom, set on the DRAFT before publishing;
         this command takes no time of its own.
         One pending schedule per group. Manual deploy/rollback/undeploy, starting
@@ -2208,13 +2238,13 @@ import "commander";
 import dedent8 from "dedent";
 
 // src/lib/dataset-upload.ts
-import { extname } from "path";
+import { extname as extname2 } from "path";
 var DATASET_CONTENT_TYPES = {
   ".csv": "text/csv",
   ".json": "application/json"
 };
 function datasetContentType(filename) {
-  return DATASET_CONTENT_TYPES[extname(filename).toLowerCase()];
+  return DATASET_CONTENT_TYPES[extname2(filename).toLowerCase()];
 }
 function uploadDataset(bytes, filename, options) {
   const form = new FormData();
@@ -2226,6 +2256,9 @@ function uploadDataset(bytes, filename, options) {
   });
 }
 
+// src/lib/dry-run-limit.ts
+var DRY_RUN_LIMIT_NOTE = `Not billed and not counted toward the plan's usage. Dry runs, dry run compares, and single-decision replays share a limit of ${MAX_DRY_RUN_EVALUATIONS_PER_MINUTE} evaluations per minute for each organization; a compare counts as two. Past the limit, a call fails with 429 (C-007); wait a minute before trying again.`;
+
 // src/commands/analytics.ts
 function registerAnalyticsCommands(program) {
   const analytics = program.command("analytics").description("Dry run, simulation, and requirements").addHelpText(
@@ -2255,6 +2288,8 @@ function registerAnalyticsCommands(program) {
           $ lexq analytics dry-run --version-id <vid> --file test-input.json
 
         The request body must include a "facts" object. Use --debug for execution traces
+
+        ${DRY_RUN_LIMIT_NOTE}
       `
   ).action(async (opts) => {
     try {
@@ -2293,6 +2328,8 @@ function registerAnalyticsCommands(program) {
             }'
 
         Shows side-by-side which rules matched and what actions fired for each version.
+
+        ${DRY_RUN_LIMIT_NOTE}
       `
   ).action(async (opts) => {
     try {
@@ -2604,10 +2641,10 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq analytics simulation export --id <simId> --as csv --output results.csv
           $ lexq analytics simulation export --id <simId> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport(`analytics/simulations/${opts.id}/export`, parseFormat(opts.as), {
+      await runExport(`analytics/simulations/${opts.id}/export`, fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -2666,7 +2703,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --output template.csv
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
       const config = loadConfig();
@@ -2675,7 +2712,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       if (!apiKey) {
         throw new Error('Not authenticated. Run "lexq auth login" first.');
       }
-      const fmt = parseFormat(opts.as);
+      const fmt = fileFormat(command);
       const url = new URL(
         `analytics/groups/${opts.groupId}/versions/${opts.versionId}/dataset-template`,
         baseUrl.endsWith("/") ? baseUrl : baseUrl + "/"
@@ -2749,7 +2786,7 @@ function registerProfileCommands(program) {
         per-rule p50s within the group. Absolute ms thresholds are intentionally
         not supported. Each percentile is withheld (–) unless n×(1−q) ≥ ${TAIL_MIN_OBS} —
         p50 from n ≥ ${PERCENTILE_MIN_N.p50}, p95 from n ≥ ${PERCENTILE_MIN_N.p95}, p99 from n ≥ ${PERCENTILE_MIN_N.p99}. TOTAL is recorded
-        on every call, rule detail from a deterministic ${PROFILE_SAMPLE_PERMILLE / 10}% sample.
+        on every call, rule detail from a ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls.
 
         Examples:
           $ lexq profile <groupId>
@@ -2807,7 +2844,9 @@ function registerProfileCommands(program) {
         console.log(`baseline ${b.phase.padEnd(9)}: ${base}`);
       }
       if (data.droppedRows > 0) {
-        console.log(`\u26A0 droppedRows=${data.droppedRows} (corrupt histogram rows skipped)`);
+        console.log(
+          `\u26A0 droppedRows=${data.droppedRows} (some samples could not be read and are not included)`
+        );
       }
       printTable(
         ["Rule", "Phase", "n", "p50(ms)", "p95(ms)", "p99(ms)", "\xD7base", "Flagged"],
@@ -3007,8 +3046,10 @@ function registerReplayCommands(program) {
     "after",
     dedent11`
 
-        Free of charge (TPS throttle only). Returns decisionChanged, effect
-        changes, fired rules on both sides, and a determinism verdict.
+        Returns decisionChanged, effect changes, fired rules on both sides,
+        and a determinism verdict.
+
+        ${DRY_RUN_LIMIT_NOTE}
 
         Example:
           $ lexq replay decision --trace-id <tid> --version-id <vid>
@@ -3129,8 +3170,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
     "after",
     dedent11`
 
-        Only COMPLETED jobs can be exported. A running job has no full result yet, and a
-        partial one reads as the whole thing on the receiving end.
+        Only COMPLETED jobs can be exported.
 
         The two formats carry different things. CSV holds the effect blast radius, whose
         columns are fixed. JSON holds the changed samples and action parameters, which
@@ -3140,10 +3180,10 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
           $ lexq replay export --id <jobId> --as csv --output blast-radius.csv
           $ lexq replay export --id <jobId> --as json
       `
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
     try {
       const globalOpts = program.opts();
-      await runExport(`replay/jobs/${opts.id}/export`, parseFormat(opts.as), {
+      await runExport(`replay/jobs/${opts.id}/export`, fileFormat(command), {
         apiKey: globalOpts.apiKey,
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
@@ -3264,7 +3304,7 @@ function registerLogCommands(program) {
     "after",
     dedent13`
 
-        System failure logs (DLQ) for background tasks — platform event webhooks and scheduled deployments.
+        Failure logs for platform event webhooks and scheduled deployments that failed.
 
         Commands:
           list         List failure logs with filters
@@ -3684,7 +3724,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       annotations: READ_ONLY,
       description: dedent15`
-        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           inputFacts        — normalized input facts
@@ -3713,7 +3753,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run Compare",
       annotations: READ_ONLY,
       description: dedent15`
-        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        Compare dry run results between two versions using the same input facts. Useful for validating changes. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           resultA / resultB — full DryRunResponse for each version
@@ -3753,8 +3793,9 @@ function registerAnalyticsTools(server, callApi) {
       description: dedent15`
         Start an Impact Simulation against historical, uploaded, or inline data.
 
-        Starting checks the plan's simulation usage limit. The records a simulation processes
-        count toward that usage when it completes or is canceled.
+        Every record a simulation processes counts toward the plan's simulation usage, including
+        records processed before a cancel. When the plan's limit is reached, a new simulation
+        cannot start.
 
         dataset.type and dataset.source are BOTH required, and must be paired:
           HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd, whole days
@@ -3863,7 +3904,7 @@ function registerAnalyticsTools(server, callApi) {
       annotations: ADDITIVE,
       description: dedent15`
         Upload inline CSV or JSON content as a simulation dataset.
-        The content is uploaded to S3 and a path is returned in the "path" field.
+        The content is stored as a dataset, and its path is returned in the "path" field.
 
         To use the returned path in lexq_simulation_start, set:
           dataset: { "type": "UPLOADED", "source": "S3_BUCKET", "path": "<returned path>" }
@@ -4657,7 +4698,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Schedule Deployment",
       annotations: DESTRUCTIVE,
-      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. A scheduled deployment uses exactly the rules that were scheduled; if they do not match when it runs, it fails with HASH_MISMATCH and nothing is deployed.",
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
         versionId: z8.string().uuid().describe("ACTIVE version ID with a future effective start date"),
@@ -4785,7 +4826,7 @@ function registerProfileTools(server, callApi) {
     {
       title: "Group Latency Profile",
       annotations: READ_ONLY,
-      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99} \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a deterministic ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
+      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cacheState (HIT = calls on a version already prepared for execution, MISS = calls that had to prepare the version first and run slower), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99} \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
       inputSchema: z9.object({
         groupId: z9.string().uuid().describe("Policy group ID"),
         versionId: z9.string().uuid().optional().describe("Version to inspect (default: live version)"),
@@ -4830,7 +4871,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Replay a Decision",
       annotations: READ_ONLY,
-      description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
+      description: `Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous. ${DRY_RUN_LIMIT_NOTE} A replay sends no webhook, notification, or event: rule actions produce no outward effects.`,
       inputSchema: z10.object({
         traceId: z10.string().describe("Trace ID of the past execution to replay"),
         candidateVersionId: z10.string().uuid().describe("Version to re-evaluate against")
@@ -4885,7 +4926,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Cancel Replay Job",
       annotations: DESTRUCTIVE,
-      description: "Cooperatively cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
+      description: "Cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
       inputSchema: z10.object({
         jobId: z10.string().describe("Replay job ID")
       })
@@ -4897,7 +4938,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Export Replay Result",
       annotations: READ_ONLY,
-      description: `Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
+      description: `Export a COMPLETED window replay job; a job that has not completed is rejected. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
       inputSchema: z10.object({
         jobId: z10.string().describe("Replay job ID"),
         format: z10.enum(EXPORT_FORMATS).default("json").describe("Export format")
@@ -5428,9 +5469,14 @@ function createCli() {
   const program = new Command();
   program.name("lexq").description(
     "Command-line interface for the LexQ Decision Operations Platform. Manage policies, run Impact Simulation, and deploy from your terminal."
-  ).version(getVersion2(), "-V, --version").option("--format <format>", "Output format: json or table", "json").option("--api-key <key>", "Override stored API key").option(
+  ).version(getVersion2(), "-V, --version").option(
+    "--format <format>",
+    `How results are printed: ${OUTPUT_FORMATS.join(" or ")}`,
+    parseOutputFormat,
+    "json"
+  ).option("--api-key <key>", "Override stored API key").option(
     "--base-url <url>",
-    "Override API base URL \u2014 must include the API prefix, e.g. http://localhost:8080/api/v1/partners"
+    "Override API base URL \u2014 must include the API prefix, e.g. https://api.lexq.io/api/v1/partners"
   ).option("--dry-run", "Preview the HTTP request without executing").option("--verbose", "Show request/response details").option("--no-color", "Disable colored output");
   registerAuthCommands(program);
   registerStatusCommand(program);

package/dist/mcp/register.d.ts

@@ -20,8 +20,8 @@ interface McpToolResult {
  * Function signature for making API calls.
  * Injected into tool registration functions for testability and reuse.
  *
- * - lexq-cli (stdio): uses createCallApiFromConfig() — reads ~/.lexq/config.json
- * - lexq-mcp (HTTP):  uses createApiCaller(apiKey) — Bearer token from request
+ * - lexq serve --mcp (stdio): createCallApiFromConfig() reads ~/.lexq/config.json.
+ * - A host serving these tools over HTTP passes its own CallApi.
  */
 type CallApi = (method: string, path: string, opts?: {
     body?: unknown;
@@ -37,8 +37,8 @@ declare function paginationParams(page?: number, size?: number): Record<string,
  * Builds a salient, actionable warning from a response's meta when it reports facts that
  * rules reference but the schema does not define. Returns null when there is nothing to warn.
  *
- * Shared by both CallApi implementations (CLI stdio here, lexq-mcp HTTP via @lexq/cli/mcp)
- * so the agent-facing text is identical on every surface. The backend only populates
+ * Shared by every CallApi (the stdio server here, and any host through @lexq/cli/mcp) so the
+ * agent-facing text is identical on every surface. The API only populates
  * meta.unregisteredFacts on rule create/update, so this only ever fires there.
  */
 declare function formatUnregisteredFactWarning(meta: unknown): string | null;
@@ -84,7 +84,8 @@ declare const isLosslessNumber: (value: unknown) => value is LosslessNumber;
  * Registers all MCP tools on the given server.
  *
  * @param server - McpServer instance
- * @param callApi - API caller function (config-based for CLI, Bearer-based for HTTP)
+ * @param callApi - how tool calls reach the LexQ API. The stdio server builds one from
+ *   ~/.lexq/config.json; a host passes its own.
  */
 declare function registerAllTools(server: McpServer, callApi: CallApi): void;
 /**

package/dist/mcp/register.js

@@ -219,6 +219,7 @@ var STATS_DEFAULT_WINDOW_DAYS = 30;
 var STATS_MAX_WINDOW_DAYS = 31;
 var FAILURE_LOG_LOOKBACK_DAYS = 7;
 var PURGE_AFTER_DAYS = 30;
+var MAX_DRY_RUN_EVALUATIONS_PER_MINUTE = 60;
 
 // src/mcp/tools/groups.ts
 function registerGroupTools(server, callApi) {
@@ -652,6 +653,7 @@ var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/lib/export.ts
 import { writeFileSync as writeFileSync2 } from "fs";
+import { extname } from "path";
 var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
 
 // src/mcp/tools/facts.ts
@@ -863,7 +865,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Schedule Deployment",
       annotations: DESTRUCTIVE,
-      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. A scheduled deployment uses exactly the rules that were scheduled; if they do not match when it runs, it fails with HASH_MISMATCH and nothing is deployed.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("ACTIVE version ID with a future effective start date"),
@@ -977,6 +979,11 @@ function registerDeployTools(server, callApi) {
 // src/mcp/tools/analytics.ts
 import { z as z7 } from "zod";
 import dedent3 from "dedent";
+
+// src/lib/dry-run-limit.ts
+var DRY_RUN_LIMIT_NOTE = `Not billed and not counted toward the plan's usage. Dry runs, dry run compares, and single-decision replays share a limit of ${MAX_DRY_RUN_EVALUATIONS_PER_MINUTE} evaluations per minute for each organization; a compare counts as two. Past the limit, a call fails with 429 (C-007); wait a minute before trying again.`;
+
+// src/mcp/tools/analytics.ts
 function datasetBlock(path) {
   const dataset = { type: "UPLOADED", source: "S3_BUCKET", path };
   return {
@@ -991,7 +998,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run",
       annotations: READ_ONLY,
       description: dedent3`
-        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           inputFacts        — normalized input facts
@@ -1020,7 +1027,7 @@ function registerAnalyticsTools(server, callApi) {
       title: "Dry Run Compare",
       annotations: READ_ONLY,
       description: dedent3`
-        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        Compare dry run results between two versions using the same input facts. Useful for validating changes. ${DRY_RUN_LIMIT_NOTE}
         
         Returns:
           resultA / resultB — full DryRunResponse for each version
@@ -1060,8 +1067,9 @@ function registerAnalyticsTools(server, callApi) {
       description: dedent3`
         Start an Impact Simulation against historical, uploaded, or inline data.
 
-        Starting checks the plan's simulation usage limit. The records a simulation processes
-        count toward that usage when it completes or is canceled.
+        Every record a simulation processes counts toward the plan's simulation usage, including
+        records processed before a cancel. When the plan's limit is reached, a new simulation
+        cannot start.
 
         dataset.type and dataset.source are BOTH required, and must be paired:
           HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd, whole days
@@ -1170,7 +1178,7 @@ function registerAnalyticsTools(server, callApi) {
       annotations: ADDITIVE,
       description: dedent3`
         Upload inline CSV or JSON content as a simulation dataset.
-        The content is uploaded to S3 and a path is returned in the "path" field.
+        The content is stored as a dataset, and its path is returned in the "path" field.
 
         To use the returned path in lexq_simulation_start, set:
           dataset: { "type": "UPLOADED", "source": "S3_BUCKET", "path": "<returned path>" }
@@ -1250,7 +1258,7 @@ function registerProfileTools(server, callApi) {
     {
       title: "Group Latency Profile",
       annotations: READ_ONLY,
-      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99} \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a deterministic ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
+      description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cacheState (HIT = calls on a version already prepared for execution, MISS = calls that had to prepare the version first and run slower), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99} \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
         versionId: z8.string().uuid().optional().describe("Version to inspect (default: live version)"),
@@ -1295,7 +1303,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Replay a Decision",
       annotations: READ_ONLY,
-      description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
+      description: `Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous. ${DRY_RUN_LIMIT_NOTE} A replay sends no webhook, notification, or event: rule actions produce no outward effects.`,
       inputSchema: z9.object({
         traceId: z9.string().describe("Trace ID of the past execution to replay"),
         candidateVersionId: z9.string().uuid().describe("Version to re-evaluate against")
@@ -1350,7 +1358,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Cancel Replay Job",
       annotations: DESTRUCTIVE,
-      description: "Cooperatively cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
+      description: "Cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID")
       })
@@ -1362,7 +1370,7 @@ function registerReplayTools(server, callApi) {
     {
       title: "Export Replay Result",
       annotations: READ_ONLY,
-      description: `Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
+      description: `Export a COMPLETED window replay job; a job that has not completed is rejected. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID"),
         format: z9.enum(EXPORT_FORMATS).default("json").describe("Export format")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "mcpName": "io.lexq/lexq",
   "description": "The Decision Operations Platform for engineering teams",
   "type": "module",
@@ -47,6 +47,7 @@
     "test:rollback": "pnpm build && node tests/rollback.mjs",
     "test:dataset-upload": "pnpm build && node tests/dataset-upload.mjs",
     "test:export-limit": "pnpm build && node tests/export-limit.mjs",
+    "test:format-options": "pnpm build && node tests/format-options.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",
     "format": "prettier --write \"src/**/*.ts\"",

package/skills/lexq-execution/SKILL.md

@@ -81,8 +81,7 @@ Use stats to monitor:
 
 ## 2. Failure Logs
 
-Failure logs are a dead-letter record for background tasks that failed after the request returned.
-Two task types exist:
+Failure logs record background tasks that failed. Two task types exist:
 
 | Task type              | What failed                                                      |
 |------------------------|------------------------------------------------------------------|
@@ -171,12 +170,12 @@ lexq deploy schedules --format table
 lexq deploy unschedule --group-id <gid> --force
 ```
 
-One pending schedule per group. The scheduler deploys within one tick (≤60s) of the effective
-start. A manual deploy, rollback, undeploy, A/B test start, or group archive **cancels** the
-pending schedule — the cancellation reason is recorded in the schedule ledger.
+One pending schedule per group. A scheduled deployment goes live within 60 seconds after its
+effective start. A manual deploy, rollback, undeploy, A/B test start, or group archive **cancels**
+the pending schedule, and the schedule's `canceledReason` says which one.
 
-The snapshot hash is sealed at scheduling time. If the version changes before the effective start,
-the scheduled deploy fails with `HASH_MISMATCH` rather than deploying something unexpected.
+A scheduled deployment uses exactly the rules that were scheduled. If they do not match when it
+runs, it fails with `HASH_MISMATCH` and nothing is deployed.
 
 ## 4. Decision Provenance
 
@@ -226,9 +225,8 @@ lexq replay export --id <jobId> --as csv --output blast-radius.csv
 Replay reports whether the outcome is `DETERMINISTIC` or `REPLAY_MAY_DIFFER` — the latter when the
 original execution depended on values the replay cannot reproduce.
 
-Only a `COMPLETED` job can be exported; a running one has no full result yet, and a partial one reads
-as the whole thing on the receiving end. The two formats answer different questions — CSV carries the
-effect blast radius, whose columns are fixed, and JSON carries the changed samples and action
+Only a `COMPLETED` job can be exported. The two formats answer different questions — CSV carries
+the effect blast radius, whose columns are fixed, and JSON carries the changed samples and action
 parameters, which nest and whose keys differ per tenant.
 
 ## 6. Latency Profile
@@ -249,8 +247,9 @@ lexq profile <groupId> --version-id <vid> --cache MISS \
 `--from` / `--to` are ISO-8601 **instants** here (`2026-07-01T00:00:00Z`), unlike `replay start`
 which takes `yyyy-MM-dd` days in the organization time zone.
 
-`p50` / `p95` / `p99` are `null` when the sample is under 100 — the engine reports insufficient
-data rather than inventing a number. `n` is always present.
+`p50` / `p95` / `p99` are `null` until the sample is large enough to show them, and the engine
+never estimates a withheld one. `lexq profile --help` lists the thresholds, and `n` is always
+present. A rule whose sample is under 100 is never flagged.
 
 ## Agent Monitoring Workflow
 

package/skills/lexq-groups/SKILL.md

@@ -152,12 +152,7 @@ tables of `lexq deploy history`, `deploy schedules`, `history list`, and
 **Constraint:** All groups sharing the same `activationGroup` **must** use identical
 `activationMode` and `activationStrategy`. The API rejects mismatches with a `P-` error.
 
-Groups are selected by the order you set, not by comparing action values. `FIRST_MATCH` and
-`MAX_BENEFIT` were removed on 2026-08-01 — the former resolved identically to
-`HIGHEST_PRIORITY` (candidates are evaluated in priority order, so "first match" *is* "lowest
-priority number"), and the latter compared post-action values as scores, which made a 20%
-discount lose to a 10% discount. The engine cannot know which direction is "better" for your
-domain.
+Groups are selected by the priority order you set, not by comparing action values.
 
 ### Example: Exclusive Discount Groups
 
@@ -187,9 +182,8 @@ Split traffic between the current live version and a test version.
 
 ### Traffic Identity Key
 
-**Every execution request has to carry `context.trafficKey`.** That value is what the split is
-computed from: the server hashes it together with the group ID and assigns the request to a
-bucket, so the same key value always reaches the same version for that group.
+**Every execution request has to carry `context.trafficKey`.** That value decides the split: the
+same key value always reaches the same version for that group.
 
 Send it in `context`, not in `facts`. Routing never reads `facts`.
 
@@ -202,11 +196,10 @@ Send it in `context`, not in `facts`. Routing never reads `facts`.
 
 If the key is missing or empty, no request is ever assigned to the test version. The test still
 reports as running and execution logs keep accumulating, so **the failure does not surface in the
-response** — only a server-side warning records it. This is the most common reason a test sits
-at 0%.
+response**. This is the most common reason a test sits at 0%.
 
 Pick a value that is stable per experiment unit (a customer ID, a merchant ID, a session ID) and
-opaque — the whole `context` object is stored on the execution ledger, so send a hash or a
+opaque — the whole `context` object is stored in execution history, so send a hash or a
 surrogate key rather than an email address. A value that changes every request, such as a request
 ID, scatters one user across both versions and destroys the comparison.
 

package/skills/lexq-recipes/SKILL.md

@@ -376,11 +376,10 @@ live but from a newer deployment. Start again from step 1.
 
 **Goal:** Check for pending failures and find their cause.
 
-Failure logs are a dead-letter record for background tasks — platform event webhooks and scheduled
-deployments. There is no retry action: the engine does not re-execute a failed task on request.
-Fix the cause at the source (webhook endpoint, version state). The CLI can read failure logs but
-cannot resolve or ignore them: an organization admin does that in the console, under
-Management → Failure Logs (https://console.lexq.io/management/failure-logs).
+Failure logs record platform event webhooks and scheduled deployments that failed. There is no
+retry action; fix the cause at the source (webhook endpoint, version state). The CLI can read
+failure logs but cannot resolve or ignore them: an organization admin does that in the console,
+under Management → Failure Logs (https://console.lexq.io/management/failure-logs).
 
 ```bash
 # 1. List pending failures

package/skills/lexq-shared/SKILL.md

@@ -72,16 +72,19 @@ Every command accepts these flags:
 
 | Flag                     | Description                                | Default                               |
 |--------------------------|--------------------------------------------|---------------------------------------|
-| `--format <json\|table>` | Output format                              | `json`                                |
+| `--format <json\|table>` | How results are printed                    | `json`                                |
 | `--api-key <key>`        | Override stored API key                    | from config                           |
 | `--base-url <url>`       | Override API base URL                      | `https://api.lexq.io/api/v1/partners` |
 | `--dry-run`              | Preview the HTTP request without executing | off                                   |
 | `--verbose`              | Show request/response details              | off                                   |
 | `--no-color`             | Disable colored output                     | off                                   |
 
-**Agent best practice:** Always use `--format json` (the default). Parse JSON output programmatically. Use
+**Agent best practice:** Leave `--format` at its default, `json`, and parse the output programmatically. Use
 `--format table` only when displaying to humans.
 
+`--format` does not change a file. The commands that write one (`facts export`, `analytics simulation export`,
+`replay export`, `analytics dataset template`) choose its format with `--as csv` or `--as json`.
+
 ## Command Groups
 
 | Group                   | Commands                                                                                                                   | Description                     |
@@ -105,7 +108,7 @@ Every command accepts these flags:
 
 ## Pagination
 
-All list endpoints return a `PageResponse`:
+All list endpoints return one page of results:
 
 ```json
 {

package/skills/lexq-simulation/SKILL.md

@@ -197,7 +197,7 @@ Each code says **who fixes it**.
 
 `CONDITION_VALUE_TYPE_INVALID` is worth escalating. The right-hand side of a condition belongs
 to the rule, not to your request, so changing the payload will not help — the rule fails the
-same way for every caller. It also got past the check that is supposed to reject it on save.
+same way for every caller.
 
 A rule from another group referencing facts you did not send yields `FACT_NOT_PROVIDED` — this
 is normal, not an error.
@@ -263,7 +263,7 @@ lexq analytics dataset template \
 
 # 2. Upload dataset
 lexq analytics dataset upload --file ./my-data.csv
-# → path: datasets/<tenantId>/a1b2c3d4e5f6.csv
+# → returns a path. Pass it to simulation start unchanged.
 
 # 3. Start simulation with uploaded path
 lexq analytics simulation start --json '{