@lexq/cli 0.1.53 → 0.1.55

package/AGENTS.md

@@ -61,7 +61,7 @@ lexq groups list|get|create|update|delete|reorder
 lexq groups ab-test start|stop|adjust
 lexq versions list|get|create|update|delete|clone
 lexq rules list|get|create|update|delete|reorder|toggle
-lexq facts list|create|update|delete|action-metadata|unregistered
+lexq facts list|create|update|delete|export|action-metadata|unregistered
 lexq domain-templates list|preview|apply
 lexq deploy publish|live|rollback|undeploy|history|detail|overview|deployable|diff|schedule|unschedule|schedules
 lexq analytics dry-run|dry-run-compare|requirements
@@ -69,7 +69,7 @@ lexq analytics simulation start|status|list|cancel|export
 lexq analytics dataset upload|template
 lexq profile <groupId>
 lexq history list|get|stats
-lexq replay decision|start|list|get|cancel
+lexq replay decision|start|list|get|cancel|export
 lexq provenance get|reveal-audits
 lexq logs list|get|action|bulk-action
 lexq webhook-subscriptions list|get|save|delete|test
@@ -129,8 +129,9 @@ Place this file in the project root. The IDE will auto-discover it.
 
 ### Claude Code
 
-Reads this file via the root `CLAUDE.md` pointer. No separate context file — this document and `skills/` are the whole
-guide.
+Reads this file through the root `CLAUDE.md`, which is a one-line import rather than a copy. There is no
+Claude-specific document to keep in sync. The CLI guide is this file plus `skills/`; `CONTEXT.md` covers platform
+architecture separately and ships alongside.
 
 ### Gemini CLI
 

package/dist/index.js

@@ -111,6 +111,12 @@ async function doFetch(method, path, options) {
   }
   return response;
 }
+function isFileResponse(response) {
+  const disposition = response.headers.get("content-disposition") ?? "";
+  if (disposition.toLowerCase().includes("attachment")) return true;
+  const contentType = response.headers.get("content-type") ?? "";
+  return contentType.includes("text/csv") || contentType.includes("application/octet-stream");
+}
 function assertOk(response, json) {
   if (!response.ok || json.result !== "SUCCESS") {
     throw new ApiError(
@@ -126,10 +132,10 @@ async function apiRequest(method, path, options = {}) {
 }
 async function apiRequestWithMeta(method, path, options = {}) {
   const response = await doFetch(method, path, options);
-  const contentType = response.headers.get("content-type") ?? "";
-  if (contentType.includes("text/csv") || contentType.includes("application/octet-stream")) {
-    return { data: response, meta: null };
+  if (isFileResponse(response)) {
+    return { data: await response.text(), meta: null };
   }
+  const contentType = response.headers.get("content-type") ?? "";
   if (response.status === 204 || contentType === "") {
     return { data: void 0, meta: null };
   }
@@ -1164,6 +1170,33 @@ ${data.length} total`);
 // src/commands/facts.ts
 import "commander";
 import dedent6 from "dedent";
+
+// src/lib/export.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+function parseFormat(value) {
+  if (value === "csv" || value === "json") return value;
+  throw new Error(`Unsupported export format: ${String(value)}. Use csv or json.`);
+}
+async function runExport(path, format, options) {
+  const { output, params, ...clientOptions } = options;
+  const body = await apiRequest("GET", path, {
+    ...clientOptions,
+    params: { ...params, format }
+  });
+  if (typeof body !== "string") {
+    throw new Error(
+      `Export did not return a file (${path}). Re-run with --verbose to see the response headers.`
+    );
+  }
+  if (output) {
+    writeFileSync2(output, body, "utf-8");
+    console.log(`\u2713 Exported to ${output}`);
+    return;
+  }
+  process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+}
+
+// src/commands/facts.ts
 function registerFactCommands(program) {
   const facts = program.command("facts").description("Manage fact definitions (schema)").addHelpText(
     "after",
@@ -1360,6 +1393,36 @@ ${data.length} unregistered`);
       process.exit(1);
     }
   });
+  facts.command("export").description("Export the fact catalog").option("--as <fmt>", "Exported file format: csv or json", "csv").option("--keyword <keyword>", "Filter by key or name").option("--output <path>", "Output file path").addHelpText(
+    "after",
+    dedent6`
+
+        The two formats carry different things. CSV is the catalog as it stands, system
+        facts included, for reading in a spreadsheet. JSON matches the shape that
+        batch create accepts, so it can be fed straight back in — which is why it leaves
+        out the fields that endpoint does not take.
+
+        Examples:
+          $ lexq facts export --output facts.csv
+          $ lexq facts export --as json --output facts.json
+          $ lexq facts export --keyword user --as json
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      await runExport("schema/facts/export", parseFormat(opts.as), {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose,
+        output: opts.output,
+        params: opts.keyword ? { keyword: opts.keyword } : void 0
+      });
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
   facts.command("action-metadata").description("Get action runtime fact metadata").addHelpText(
     "after",
     dedent6`
@@ -1843,7 +1906,7 @@ async function warnUnregisteredFacts(globalOpts, groupId, versionId) {
 }
 
 // src/commands/analytics.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
 import "commander";
 import dedent8 from "dedent";
 function registerAnalyticsCommands(program) {
@@ -2191,38 +2254,30 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  sim.command("export").description("Export simulation results").requiredOption("--id <simulationId>", "Simulation ID").option("--format <fmt>", "Export format: csv or json", "json").option("--output <path>", "Output file path").addHelpText(
+  sim.command("export").description("Export simulation results").requiredOption("--id <simulationId>", "Simulation ID").option("--as <fmt>", "Exported file format: csv or json", "json").option("--output <path>", "Output file path").addHelpText(
     "after",
     dedent8`
 
         Only COMPLETED simulations can be exported.
 
         Examples:
-          $ lexq analytics simulation export --id <simId> --format csv --output results.csv
-          $ lexq analytics simulation export --id <simId> --format json
+          $ lexq analytics simulation export --id <simId> --as csv --output results.csv
+          $ lexq analytics simulation export --id <simId> --as json
       `
   ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
-      const exportFormat = opts.format === "csv" ? "csv" : "json";
-      const response = await apiRequest(
-        "GET",
+      await runExport(
         `analytics/simulations/${opts.id}/export`,
+        parseFormat(opts.as),
         {
           apiKey: globalOpts.apiKey,
           baseUrl: globalOpts.baseUrl,
           dryRun: globalOpts.dryRun,
           verbose: globalOpts.verbose,
-          params: { format: exportFormat }
+          output: opts.output
         }
       );
-      if (opts.output) {
-        const text = typeof response === "string" ? response : stringifyJson(response, 2) ?? "";
-        writeFileSync2(opts.output, text, "utf-8");
-        console.log(`\u2713 Exported to ${opts.output}`);
-      } else {
-        printJson(response);
-      }
     } catch (error) {
       printError(error);
       process.exit(1);
@@ -2293,7 +2348,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  dataset.command("template").description("Download a dataset template based on version requirements").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").option("--format <fmt>", "Template format: csv or json", "csv").option("--output <path>", "Output file path").addHelpText(
+  dataset.command("template").description("Download a dataset template based on version requirements").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").option("--as <fmt>", "Template file format: csv or json", "csv").option("--output <path>", "Output file path").addHelpText(
     "after",
     dedent8`
 
@@ -2301,7 +2356,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
         Examples:
           $ lexq analytics dataset template --group-id <gid> --version-id <vid> --output template.csv
-          $ lexq analytics dataset template --group-id <gid> --version-id <vid> --format json
+          $ lexq analytics dataset template --group-id <gid> --version-id <vid> --as json
       `
   ).action(async (opts) => {
     try {
@@ -2312,7 +2367,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 = opts.format === "json" ? "json" : "csv";
+      const fmt = parseFormat(opts.as);
       const url = new URL(
         `analytics/groups/${opts.groupId}/versions/${opts.versionId}/dataset-template`,
         baseUrl.endsWith("/") ? baseUrl : baseUrl + "/"
@@ -2326,7 +2381,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       }
       const text = await response.text();
       if (opts.output) {
-        writeFileSync2(opts.output, text, "utf-8");
+        writeFileSync3(opts.output, text, "utf-8");
         console.log(`\u2713 Template saved to ${opts.output}`);
       } else {
         console.log(text);
@@ -2359,6 +2414,7 @@ import "commander";
 import dedent9 from "dedent";
 
 // src/types/enums.ts
+var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
 var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
 var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
 var ProfileCacheState = ["HIT", "MISS"];
@@ -2765,6 +2821,36 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
+  replay.command("export").description("Export the result of a completed replay job").requiredOption("--id <jobId>", "Replay job ID").option("--as <fmt>", "Exported file format: csv or json", "json").option("--output <path>", "Output file path").addHelpText(
+    "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.
+
+        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.
+
+        Examples:
+          $ lexq replay export --id <jobId> --as csv --output blast-radius.csv
+          $ lexq replay export --id <jobId> --as json
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      await runExport(`replay/jobs/${opts.id}/export`, parseFormat(opts.as), {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose,
+        output: opts.output
+      });
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/provenance.ts
@@ -3722,6 +3808,7 @@ import { z as z4 } from "zod";
 var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/mcp/tools/facts.ts
+var VALUE_TYPES = ValueType;
 function registerFactTools(server, callApi) {
   server.registerTool(
     "lexq_facts_list",
@@ -3748,7 +3835,7 @@ function registerFactTools(server, callApi) {
       inputSchema: {
         key: z4.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
         name: z4.string().describe("Display name"),
-        type: z4.enum(["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"]).describe("Value type"),
+        type: z4.enum(VALUE_TYPES).describe("Value type"),
         description: z4.string().optional().describe("Description"),
         isRequired: z4.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
         isPii: z4.boolean().default(false).describe(
@@ -3762,11 +3849,14 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      description: "Update a fact definition. Key and type cannot be changed. Only provided fields are updated. System facts only allow name, description, and PII changes.",
+      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.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID"),
         name: z4.string().optional().describe("Display name"),
         description: z4.string().optional().describe("Description"),
+        type: z4.enum(VALUE_TYPES).optional().describe(
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+        ),
         isRequired: z4.boolean().optional().describe("Required flag"),
         isPii: z4.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)")
       }
@@ -3777,7 +3867,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
-      description: "Delete a fact definition. System facts cannot be deleted.",
+      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.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID")
       }
@@ -3805,6 +3895,20 @@ function registerFactTools(server, callApi) {
     },
     async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
   );
+  server.registerTool(
+    "lexq_facts_export",
+    {
+      title: "Export Fact Catalog",
+      description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
+      inputSchema: {
+        format: z4.enum(["csv", "json"]).default("csv").describe("Export format"),
+        keyword: z4.string().optional().describe("Filter by key or name")
+      }
+    },
+    async ({ format, keyword }) => callApi("GET", "schema/facts/export", {
+      params: keyword ? { format, keyword } : { format }
+    })
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -4318,6 +4422,18 @@ function registerReplayTools(server, callApi) {
     },
     async ({ jobId }) => callApi("POST", `replay/jobs/${jobId}/cancel`)
   );
+  server.registerTool(
+    "lexq_replay_export",
+    {
+      title: "Export Replay Result",
+      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.",
+      inputSchema: {
+        jobId: z8.string().describe("Replay job ID"),
+        format: z8.enum(["json", "csv"]).default("json").describe("Export format")
+      }
+    },
+    async ({ jobId, format }) => callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } })
+  );
 }
 
 // src/mcp/tools/history.ts

package/dist/mcp/register.js

@@ -15,6 +15,7 @@ function registerStatusTools(server, callApi) {
 import { z } from "zod";
 
 // src/types/enums.ts
+var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
 var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
 var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
 var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
@@ -514,6 +515,7 @@ import { z as z4 } from "zod";
 var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/mcp/tools/facts.ts
+var VALUE_TYPES = ValueType;
 function registerFactTools(server, callApi) {
   server.registerTool(
     "lexq_facts_list",
@@ -540,7 +542,7 @@ function registerFactTools(server, callApi) {
       inputSchema: {
         key: z4.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
         name: z4.string().describe("Display name"),
-        type: z4.enum(["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"]).describe("Value type"),
+        type: z4.enum(VALUE_TYPES).describe("Value type"),
         description: z4.string().optional().describe("Description"),
         isRequired: z4.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
         isPii: z4.boolean().default(false).describe(
@@ -554,11 +556,14 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      description: "Update a fact definition. Key and type cannot be changed. Only provided fields are updated. System facts only allow name, description, and PII changes.",
+      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.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID"),
         name: z4.string().optional().describe("Display name"),
         description: z4.string().optional().describe("Description"),
+        type: z4.enum(VALUE_TYPES).optional().describe(
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+        ),
         isRequired: z4.boolean().optional().describe("Required flag"),
         isPii: z4.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)")
       }
@@ -569,7 +574,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
-      description: "Delete a fact definition. System facts cannot be deleted.",
+      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.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID")
       }
@@ -597,6 +602,20 @@ function registerFactTools(server, callApi) {
     },
     async ({ groupId, versionId }) => callApi("GET", `policy-groups/${groupId}/versions/${versionId}/unregistered-facts`)
   );
+  server.registerTool(
+    "lexq_facts_export",
+    {
+      title: "Export Fact Catalog",
+      description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
+      inputSchema: {
+        format: z4.enum(["csv", "json"]).default("csv").describe("Export format"),
+        keyword: z4.string().optional().describe("Filter by key or name")
+      }
+    },
+    async ({ format, keyword }) => callApi("GET", "schema/facts/export", {
+      params: keyword ? { format, keyword } : { format }
+    })
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -1110,6 +1129,18 @@ function registerReplayTools(server, callApi) {
     },
     async ({ jobId }) => callApi("POST", `replay/jobs/${jobId}/cancel`)
   );
+  server.registerTool(
+    "lexq_replay_export",
+    {
+      title: "Export Replay Result",
+      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.",
+      inputSchema: {
+        jobId: z8.string().describe("Replay job ID"),
+        format: z8.enum(["json", "csv"]).default("json").describe("Export format")
+      }
+    },
+    async ({ jobId, format }) => callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } })
+  );
 }
 
 // src/mcp/tools/history.ts

package/package.json

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

package/skills/lexq-execution/SKILL.md

@@ -218,11 +218,19 @@ lexq replay start --version-id <candidateVid> --from 2025-01-01 --to 2025-01-31
 lexq replay get --id <jobId>
 lexq replay list
 lexq replay cancel --id <jobId>
+
+# Export a finished job
+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
+parameters, which nest and whose keys differ per tenant.
+
 ## 6. Latency Profile
 
 Per-rule latency distribution for a policy group.

package/skills/lexq-shared/SKILL.md

@@ -141,7 +141,7 @@ Prefixes you will encounter through the CLI:
 | `A-`   | Auth                  | Invalid or missing API key                     |
 | `P-`   | Policy group/version  | Not found, wrong lifecycle state, already live |
 | `ACT-` | Action parameters     | Missing or invalid action parameter            |
-| `FD-`  | Fact definitions      | Duplicate key, system fact immutable           |
+| `FD-`  | Fact definitions      | Duplicate key, system fact immutable, fact still referenced by rules |
 | `AN-`  | Analytics             | Dry-run or simulation failure                  |
 | `FL-`  | Failure logs          | Log not found                                  |
 | `WH-`  | Webhook subscriptions | Invalid URL, delivery failure                  |

package/skills/lexq-simulation/SKILL.md

@@ -250,7 +250,7 @@ lexq analytics simulation start --json '{
 ```bash
 # 1. Download template (optional)
 lexq analytics dataset template \
-  --group-id <gid> --version-id <vid> --format csv --output template.csv
+  --group-id <gid> --version-id <vid> --as csv --output template.csv
 
 # 2. Upload dataset
 lexq analytics dataset upload --file ./my-data.csv
@@ -304,8 +304,8 @@ lexq analytics simulation cancel --id <simulationId> --force
 ### Export Results
 
 ```bash
-lexq analytics simulation export --id <simulationId> --format json
-lexq analytics simulation export --id <simulationId> --format csv --output results.csv
+lexq analytics simulation export --id <simulationId> --as json
+lexq analytics simulation export --id <simulationId> --as csv --output results.csv
 ```
 
 ## Simulation Response (COMPLETED)