@lexq/cli 0.1.18 → 0.1.20

package/dist/mcp/register.d.ts

@@ -27,7 +27,7 @@ type CallApi = (method: string, path: string, opts?: {
 declare function paginationParams(page?: number, size?: number): Record<string, string>;
 
 /**
- * Registers all 55 MCP tools on the given server.
+ * Registers all 62 MCP tools on the given server.
  *
  * @param server - McpServer instance
  * @param callApi - API caller function (config-based for CLI, Bearer-based for HTTP)

package/dist/mcp/register.js

@@ -89,7 +89,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_update",
     {
       title: "Update Policy Group",
-      description: "Update a policy group. This is a full replacement \u2014 omitted optional fields will be set to null on the server.",
+      description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged.",
       inputSchema: {
         groupId: z.string().uuid().describe("Policy group ID"),
         name: z.string().optional().describe("New name"),
@@ -186,10 +186,10 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_create",
     {
       title: "Create Policy Version",
-      description: "Create a new DRAFT version in a policy group. Provide a commit message and optional effective date range.",
+      description: "Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range.",
       inputSchema: {
         groupId: z2.string().uuid().describe("Policy group ID"),
-        commitMessage: z2.string().describe("Commit message describing this version"),
+        commitMessage: z2.string().optional().describe("Commit message describing this version"),
         effectiveFrom: z2.string().optional().describe("Effective start date (ISO 8601)"),
         effectiveTo: z2.string().optional().describe("Effective end date (ISO 8601)")
       }
@@ -200,7 +200,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_update",
     {
       title: "Update Policy Version",
-      description: "Update a DRAFT version. Only DRAFT versions can be modified.",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. Only provided fields are changed.",
       inputSchema: {
         groupId: z2.string().uuid().describe("Policy group ID"),
         versionId: z2.string().uuid().describe("Version ID"),
@@ -243,6 +243,7 @@ function registerVersionTools(server, callApi) {
 
 // src/mcp/tools/rules.ts
 import { z as z3 } from "zod";
+import dedent from "dedent";
 function registerRuleTools(server, callApi) {
   server.registerTool(
     "lexq_rules_list",
@@ -277,32 +278,34 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_create",
     {
       title: "Create Rule",
-      description: `Create a rule in a DRAFT version. Requires name, priority, condition tree, and actions array.
+      description: dedent`
+        Create a rule in a DRAFT version. Requires name, priority, condition tree, and actions array.
 
-      Before creating rules with new fact keys, call lexq_facts_list to check existing facts.
-      If a required key is missing, ask the user to confirm the type, isRequired, and description
-      before calling lexq_facts_create \u2014 registering facts enables type validation, Console UI
-      autocomplete, and the dry-run requirements analyzer.
+        Before creating rules with new fact keys, call lexq_facts_list to check existing facts.
+        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.
 
-      Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
-      Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
-      Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
+        Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
+        Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
+        Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
 
-      Actions: [{ type, parameters }]
+        Actions: [{ type, parameters }]
 
-      Action parameter schemas:
-      - DISCOUNT: { refVar: string, method: "PERCENTAGE"|"AMOUNT", rate?: number (when PERCENTAGE), value?: number (when AMOUNT) }
-      - POINT: { refVar: string, targetVar: string, method: "PERCENTAGE"|"AMOUNT", rate?: number (when PERCENTAGE), value?: number (when AMOUNT), integrationId: uuid }
-      - COUPON_ISSUE: { couponId: string, integrationId: uuid }
-      - BLOCK: { reason: string }
-      - NOTIFICATION: { channel: "SMS"|"EMAIL"|"PUSH", targetVar: string, templateId: string, integrationId: uuid }
-      - WEBHOOK: { url: string, method: "POST", payloadTemplate?: object } payloadTemplate is optional. Without it, all facts are sent as-is. With it, the object is sent as the HTTP body with {{variables}} replaced at execution time. Variables: {{fact.xxx}}, {{output.xxx}}, {{timestamp}}, {{ruleName}}, {{groupName}}, {{versionNo}}, {{xxx}} (shorthand).
-        Platform examples:
-          Slack: { "text": "Rule {{ruleName}} fired \u2014 {{fact.customer_tier}}" }
-          Discord: { "content": "Rule {{ruleName}} fired \u2014 {{fact.customer_tier}}" }
-          Generic: { "event": "rule_matched", "rule": "{{ruleName}}", "amount": "{{output.payment_amount}}" }
-      - SET_FACT: { key: string, value: string|number|boolean }
-      - ADD_TAG: { tag: string, targetVar: string }`,
+        Action parameter schemas:
+        - DISCOUNT: { refVar: string, method: "PERCENTAGE"|"AMOUNT", rate?: number (when PERCENTAGE), value?: number (when AMOUNT) }
+        - POINT: { refVar: string, targetVar: string, method: "PERCENTAGE"|"AMOUNT", rate?: number (when PERCENTAGE), value?: number (when AMOUNT), integrationId: uuid }
+        - COUPON_ISSUE: { couponId: string, integrationId: uuid }
+        - BLOCK: { reason: string }
+        - NOTIFICATION: { channel: "SMS"|"EMAIL"|"PUSH", targetVar: string, templateId: string, integrationId: uuid }
+        - WEBHOOK: { url: string, method: "POST", payloadTemplate?: object } payloadTemplate is optional. Without it, all facts are sent as-is. With it, the object is sent as the HTTP body with {{variables}} replaced at execution time. Variables: {{fact.xxx}}, {{output.xxx}}, {{timestamp}}, {{ruleName}}, {{groupName}}, {{versionNo}}, {{xxx}} (shorthand).
+          Platform examples:
+            Slack: { "text": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
+            Discord: { "content": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
+            Generic: { "event": "rule_matched", "rule": "{{ruleName}}", "amount": "{{output.payment_amount}}" }
+        - SET_FACT: { key: string, value: string|number|boolean }
+        - ADD_TAG: { tag: string, targetVar: string }
+      `,
       inputSchema: {
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
@@ -435,12 +438,12 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      description: "Update a fact definition. Key and type cannot be changed. System facts only allow name and description changes.",
+      description: "Update a fact definition. Key and type cannot be changed. Only provided fields are updated. System facts only allow name and description changes.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID"),
-        name: z4.string().describe("Display name"),
+        name: z4.string().optional().describe("Display name"),
         description: z4.string().optional().describe("Description"),
-        isRequired: z4.boolean().describe("Required flag")
+        isRequired: z4.boolean().optional().describe("Required flag")
       }
     },
     async ({ factId, ...body }) => callApi("PUT", `schema/facts/${factId}`, { body })
@@ -456,6 +459,15 @@ function registerFactTools(server, callApi) {
     },
     async ({ factId }) => callApi("DELETE", `schema/facts/${factId}`)
   );
+  server.registerTool(
+    "lexq_facts_action_metadata",
+    {
+      title: "Get Action Runtime Fact Metadata",
+      description: "Retrieve runtime Facts metadata for each Action type. Shows which Facts are required as input, produced as output, or consumed at runtime by each Action (DISCOUNT, SEND_SMS, ADD_TAG, SET_FACT, etc.). Use this BEFORE designing rules to understand which Action produces which output variables (e.g., DISCOUNT produces last_discount_amount). Data is static and changes only on engine deployment \u2014 safe to cache in-session.",
+      inputSchema: {}
+    },
+    async () => callApi("GET", "schema/action-metadata")
+  );
 }
 
 // src/mcp/tools/deploy.ts
@@ -469,7 +481,7 @@ function registerDeployTools(server, callApi) {
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to publish"),
-        memo: z5.string().min(1).describe("Publish Deployment memo (required)")
+        memo: z5.string().min(1).describe("Publish memo (required)")
       }
     },
     async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/versions/${versionId}/publish`, { body: { memo } })
@@ -482,7 +494,7 @@ function registerDeployTools(server, callApi) {
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
-        memo: z5.string().min(1).describe("Live Deployment memo (required)")
+        memo: z5.string().min(1).describe("Deployment memo (required)")
       }
     },
     async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/deploy`, {
@@ -496,7 +508,7 @@ function registerDeployTools(server, callApi) {
       description: "Rollback to the previous deployed version. Only available if there is a previous version.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
-        memo: z5.string().default("").describe("Rollback reason")
+        memo: z5.string().min(1).describe("Rollback reason (required)")
       }
     },
     async ({ groupId, memo }) => callApi("POST", `policy-groups/${groupId}/rollback`, {
@@ -510,7 +522,7 @@ function registerDeployTools(server, callApi) {
       description: "Remove the live version from traffic. The version stays ACTIVE but no longer serves requests.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
-        memo: z5.string().default("").describe("Undeploy reason")
+        memo: z5.string().min(1).describe("Undeploy reason (required)")
       }
     },
     async ({ groupId, memo }) => callApi("POST", `policy-groups/${groupId}/undeploy`, {
@@ -526,13 +538,19 @@ function registerDeployTools(server, callApi) {
         page: z5.number().int().min(0).default(0).describe("Page number"),
         size: z5.number().int().min(1).max(100).default(20).describe("Page size"),
         groupId: z5.string().uuid().optional().describe("Filter by group ID"),
-        type: z5.enum(["PUBLISH", "DEPLOY", "ROLLBACK", "UNDEPLOY"]).optional().describe("Filter by deployment type")
+        types: z5.string().optional().describe(
+          "Filter by deployment types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
+        ),
+        startDate: z5.string().optional().describe("Start date (yyyy-MM-dd)"),
+        endDate: z5.string().optional().describe("End date (yyyy-MM-dd)")
       }
     },
-    async ({ page, size, groupId, type }) => {
+    async ({ page, size, groupId, types, startDate, endDate }) => {
       const params = paginationParams(page, size);
       if (groupId) params.groupId = groupId;
-      if (type) params.type = type;
+      if (types) params.types = types;
+      if (startDate) params.startDate = startDate;
+      if (endDate) params.endDate = endDate;
       return callApi("GET", "deployments", { params });
     }
   );
@@ -556,18 +574,53 @@ function registerDeployTools(server, callApi) {
     },
     async () => callApi("GET", "deployments/overview")
   );
+  server.registerTool(
+    "lexq_deploy_deployable",
+    {
+      title: "List Deployable Versions",
+      description: "List ACTIVE (published) versions that can be deployed for a group. Use this to find which versions are available before calling deploy live.",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID")
+      }
+    },
+    async ({ groupId }) => callApi("GET", `deployments/groups/${groupId}/deployable-versions`)
+  );
+  server.registerTool(
+    "lexq_deploy_diff",
+    {
+      title: "Deployment Diff",
+      description: "Compare rule snapshots between two versions. Shows added, removed, and modified rules. Useful for reviewing changes before deploying a new version.",
+      inputSchema: {
+        baseVersionId: z5.string().uuid().describe("Base version ID (typically the current live)"),
+        targetVersionId: z5.string().uuid().describe("Target version ID (the one you want to deploy)")
+      }
+    },
+    async ({ baseVersionId, targetVersionId }) => callApi("GET", "deployments/diff", {
+      params: { baseVersionId, targetVersionId }
+    })
+  );
 }
 
 // src/mcp/tools/analytics.ts
 import { z as z6 } from "zod";
+import dedent2 from "dedent";
 function registerAnalyticsTools(server, callApi) {
   server.registerTool(
     "lexq_dry_run",
     {
       title: "Dry Run",
-      description: `Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
-      Example input: { "facts": { "payment_amount": 100000, "customer_tier": "VIP" } }
-      Always dry-run before publishing to validate rule behavior.`,
+      description: dedent2`
+        Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
+        
+        Returns:
+          inputFacts        — normalized input facts
+          mutatedFacts      — input facts changed by rule actions (e.g. DISCOUNT mutates payment_amount)
+          generatedVariables — new variables created by rules (e.g. last_discount_amount)
+          executionTraces   — per-rule match status
+          decisionTraces    — per-rule decision (SELECTED / BLOCKED_MUTEX / etc.)
+        
+        Example input: { "facts": { "payment_amount": 100000, "customer_tier": "VIP" } }
+        Always dry-run before publishing to validate rule behavior.`,
       inputSchema: {
         versionId: z6.string().uuid().describe("Policy version ID to test against"),
         facts: z6.string().describe('JSON string of facts object, e.g. {"payment_amount":100000}'),
@@ -586,7 +639,13 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run_compare",
     {
       title: "Dry Run Compare",
-      description: "Compare dry run results between two versions using the same input facts. Useful for validating changes.",
+      description: dedent2`
+        Compare dry run results between two versions using the same input facts. Useful for validating changes.
+        
+        Returns:
+          resultA / resultB — full DryRunResponse for each version
+          diff.mutatedDiff   — changes in mutatedFacts between A and B (key → {before, after})
+          diff.generatedDiff — changes in generatedVariables between A and B`,
       inputSchema: {
         versionIdA: z6.string().uuid().describe("Baseline version ID"),
         versionIdB: z6.string().uuid().describe("Candidate version ID"),
@@ -616,21 +675,23 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_start",
     {
       title: "Start Simulation",
-      description: `Start a batch simulation against historical or uploaded data.
-      
-      dataset.type: "HISTORICAL" or "UPLOADED"
-      dataset.source (when HISTORICAL): "EXECUTION_LOGS"
-      dataset.from / dataset.to: date range (yyyy-MM-dd, when HISTORICAL)
-      options.maxRecords: number (max 100000, default 10000)
-      options.baselinePolicyVersionId: uuid (optional, for comparison)
-      options.includeRuleStats: boolean
-      
-      Example body:
-      {
-        "policyVersionId": "<uuid>",
-        "dataset": { "type": "HISTORICAL", "source": "EXECUTION_LOGS", "from": "2025-01-01", "to": "2025-01-31" },
-        "options": { "baselinePolicyVersionId": "<uuid>", "includeRuleStats": true, "maxRecords": 10000 }
-      }`,
+      description: dedent2`
+        Start a batch simulation against historical or uploaded data.
+
+        dataset.type: "HISTORICAL" or "UPLOADED"
+        dataset.source (when HISTORICAL): "EXECUTION_LOGS"
+        dataset.from / dataset.to: date range (yyyy-MM-dd, when HISTORICAL)
+        options.maxRecords: number (max 100000, default 10000)
+        options.baselinePolicyVersionId: uuid (optional, for comparison)
+        options.includeRuleStats: boolean
+
+        Example body:
+        {
+          "policyVersionId": "<uuid>",
+          "dataset": { "type": "HISTORICAL", "source": "EXECUTION_LOGS", "from": "2025-01-01", "to": "2025-01-31" },
+          "options": { "baselinePolicyVersionId": "<uuid>", "includeRuleStats": true, "maxRecords": 10000 }
+        }
+      `,
       inputSchema: {
         body: z6.string().describe("JSON string of SimulationRequest")
       }
@@ -701,16 +762,18 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dataset_upload",
     {
       title: "Upload Dataset",
-      description: `Upload inline CSV or JSON content as a simulation dataset.
-      The content is uploaded to S3 and a path is returned.
-      Use this path in simulation start with dataset type UPLOADED.
-      
-      CSV example:
-      user_id,payment_amount
-      user_001,150000
-      user_002,50000
-      
-      JSON example: [{"user_id":"user_001","payment_amount":150000}, {"user_id":"user_002","payment_amount":50000}]`,
+      description: dedent2`
+        Upload inline CSV or JSON content as a simulation dataset.
+        The content is uploaded to S3 and a path is returned.
+        Use this path in simulation start with dataset type UPLOADED.
+
+        CSV example:
+        user_id,payment_amount
+        user_001,150000
+        user_002,50000
+
+        JSON example: [{"user_id":"user_001","payment_amount":150000}, {"user_id":"user_002","payment_amount":50000}]
+      `,
       inputSchema: {
         content: z6.string().describe("CSV or JSON content as string"),
         filename: z6.string().default("dataset.csv").describe("Filename with extension (.csv or .json)")
@@ -893,8 +956,16 @@ var TaskType = [
   "WEBHOOK_EXECUTE",
   // Internal
   "IMAGE_PROCESSING",
-  "DAILY_SETTLEMENT"
+  "DAILY_SETTLEMENT",
+  "PLATFORM_WEBHOOK"
 ];
+var PlatformEventType = [
+  "VERSION_PUBLISHED",
+  "DEPLOYED",
+  "ROLLED_BACK",
+  "UNDEPLOYED"
+];
+var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
 // src/mcp/tools/logs.ts
 function registerLogTools(server, callApi) {
@@ -940,14 +1011,14 @@ function registerLogTools(server, callApi) {
     "lexq_logs_action",
     {
       title: "Process Failure Log",
-      description: "Process a single failure log: RETRY, RESOLVE, or IGNORE.",
+      description: "Process a single failure log: RETRY (re-execute with original payload), RESOLVE (mark as manually fixed), or IGNORE (skip intentionally).",
       inputSchema: {
         logId: z9.string().uuid().describe("Failure log ID"),
         action: z9.enum(FailureAction).describe("Action to take")
       }
     },
     async ({ logId, action }) => callApi("POST", `failure-logs/${logId}/actions`, {
-      body: { action }
+      params: { action }
     })
   );
   server.registerTool(
@@ -966,6 +1037,76 @@ function registerLogTools(server, callApi) {
   );
 }
 
+// src/mcp/tools/webhook-subscriptions.ts
+import { z as z10 } from "zod";
+function registerWebhookSubscriptionTools(server, callApi) {
+  server.registerTool(
+    "lexq_webhook_subscriptions_list",
+    {
+      title: "List Webhook Subscriptions",
+      description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications (publish, deploy, rollback, undeploy).",
+      inputSchema: {
+        page: z10.number().int().min(0).default(0).describe("Page number"),
+        size: z10.number().int().min(1).max(100).default(20).describe("Page size")
+      }
+    },
+    async ({ page, size }) => {
+      const params = paginationParams(page, size);
+      return callApi("GET", "webhook-subscriptions", { params });
+    }
+  );
+  server.registerTool(
+    "lexq_webhook_subscriptions_get",
+    {
+      title: "Get Webhook Subscription",
+      description: "Get webhook subscription detail by ID.",
+      inputSchema: {
+        id: z10.string().uuid().describe("Webhook subscription ID")
+      }
+    },
+    async ({ id }) => callApi("GET", `webhook-subscriptions/${id}`)
+  );
+  server.registerTool(
+    "lexq_webhook_subscriptions_save",
+    {
+      title: "Save Webhook Subscription",
+      description: 'Create or update a webhook subscription. Omit id to create, provide id to update. Events: VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED. Formats: GENERIC (full JSON), SLACK ({"text": "..."}).',
+      inputSchema: {
+        id: z10.string().uuid().optional().describe("Subscription ID (omit to create, provide to update)"),
+        name: z10.string().min(1).describe("Subscription name (unique per tenant)"),
+        webhookUrl: z10.string().url().describe("Webhook endpoint URL"),
+        subscribedEvents: z10.array(z10.enum(PlatformEventType)).min(1).describe("Events to subscribe to"),
+        payloadFormat: z10.enum(WebhookPayloadFormat).optional().default("GENERIC").describe("Payload format"),
+        secret: z10.string().optional().describe("HMAC-SHA256 signing secret"),
+        isActive: z10.boolean().optional().default(true).describe("Whether the subscription is active")
+      }
+    },
+    async ({ ...body }) => callApi("POST", "webhook-subscriptions", { body })
+  );
+  server.registerTool(
+    "lexq_webhook_subscriptions_delete",
+    {
+      title: "Delete Webhook Subscription",
+      description: "Delete a webhook subscription by ID.",
+      inputSchema: {
+        id: z10.string().uuid().describe("Webhook subscription ID")
+      }
+    },
+    async ({ id }) => callApi("DELETE", `webhook-subscriptions/${id}`)
+  );
+  server.registerTool(
+    "lexq_webhook_subscriptions_test",
+    {
+      title: "Test Webhook Subscription",
+      description: "Send a test event to verify webhook connectivity. Returns the HTTP status code and success/failure message.",
+      inputSchema: {
+        id: z10.string().uuid().describe("Webhook subscription ID")
+      }
+    },
+    async ({ id }) => callApi("POST", `webhook-subscriptions/${id}/test`)
+  );
+}
+
 // src/mcp/register.ts
 function registerAllTools(server, callApi) {
   registerStatusTools(server, callApi);
@@ -978,6 +1119,7 @@ function registerAllTools(server, callApi) {
   registerHistoryTools(server, callApi);
   registerIntegrationTools(server, callApi);
   registerLogTools(server, callApi);
+  registerWebhookSubscriptionTools(server, callApi);
 }
 export {
   paginationParams,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -47,12 +47,14 @@
     "@modelcontextprotocol/sdk": "^1.28.0",
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
+    "dedent": "^1.7.2",
     "ora": "^8.2.0",
     "prettier": "^3.8.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^9.20.0",
+    "@types/dedent": "^0.7.2",
     "@types/node": "^22.12.0",
     "eslint": "^10.2.0",
     "tsup": "^8.5.1",

package/skills/lexq-shared/SKILL.md

@@ -4,7 +4,9 @@
 
 ## What is LexQ?
 
-LexQ is a **policy execution engine**. Customers define business rules (conditions → actions), deploy them to production, and execute them via API — all without touching application code. Core differentiators are **pre-deploy simulation** and **A/B testing** for rule versions.
+LexQ is a **policy execution engine**. Customers define business rules (conditions → actions), deploy them to
+production, and execute them via API — all without touching application code. Core differentiators are **pre-deploy
+simulation** and **A/B testing** for rule versions.
 
 ## Authentication
 
@@ -20,22 +22,22 @@ lexq auth whoami
 The API key is passed as `X-API-KEY` header on every request. You can also override per-command:
 
 ```bash
-lexq groups list --api-key lxk_override_key
+lexq groups list --api-key sk_live_override_key
 ```
 
 **Base URL:** `https://api.lexq.io/api/v1/partners` (default). Override with `--base-url`.
 
 ## Core Concepts
 
-| Concept | Description | Analogy |
-|---|---|---|
-| **Policy Group** | A container for rule versions. Has a lifecycle status (ACTIVE / DISABLED / ARCHIVED). | Git repository |
-| **Policy Version** | A snapshot of rules within a group. Follows DRAFT → ACTIVE → ARCHIVED lifecycle. | Git branch / commit |
-| **Policy Rule** | A condition + actions pair within a version. Evaluated in priority order. | if-then statement |
-| **Fact Definition** | Input schema — declares available variables and their types (STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER). | Function parameter |
-| **Deployment** | Promotes a PUBLISHED version to live traffic. Supports rollback. | Production release |
-| **Dry Run** | Tests a single input against a DRAFT or ACTIVE version without side effects. | Unit test |
-| **Simulation** | Batch-tests a version against historical execution data. Compares with a baseline. | Integration test suite |
+| Concept             | Description                                                                                                      | Analogy                |
+|---------------------|------------------------------------------------------------------------------------------------------------------|------------------------|
+| **Policy Group**    | A container for rule versions. Has a lifecycle status (ACTIVE / DISABLED / ARCHIVED).                            | Git repository         |
+| **Policy Version**  | A snapshot of rules within a group. Follows DRAFT → ACTIVE → ARCHIVED lifecycle.                                 | Git branch / commit    |
+| **Policy Rule**     | A condition + actions pair within a version. Evaluated in priority order.                                        | if-then statement      |
+| **Fact Definition** | Input schema — declares available variables and their types (STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER). | Function parameter     |
+| **Deployment**      | Promotes a PUBLISHED version to live traffic. Supports rollback.                                                 | Production release     |
+| **Dry Run**         | Tests a single input against a DRAFT or ACTIVE version without side effects.                                     | Unit test              |
+| **Simulation**      | Batch-tests a version against historical execution data. Compares with a baseline.                               | Integration test suite |
 
 ## Standard Workflow
 
@@ -64,32 +66,33 @@ This is the typical lifecycle. **Always follow this order:**
 
 Every command accepts these flags:
 
-| Flag | Description | Default |
-|---|---|---|
-| `--format <json\|table>` | Output format | `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 |
+| Flag                     | Description                                | Default                               |
+|--------------------------|--------------------------------------------|---------------------------------------|
+| `--format <json\|table>` | Output format                              | `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 `--format table` only when displaying to humans.
+**Agent best practice:** Always use `--format json` (the default). Parse JSON output programmatically. Use
+`--format table` only when displaying to humans.
 
 ## Command Groups
 
-| Group | Commands | Description |
-|---|---|---|
-| `auth` | `login`, `logout`, `whoami` | Authentication |
-| `status` | (root) | API health check |
-| `groups` | `list`, `get`, `create`, `update`, `delete` + `ab-test start\|stop\|adjust` | Policy group CRUD + A/B testing |
-| `versions` | `list`, `get`, `create`, `update`, `delete`, `clone` | Version CRUD |
-| `rules` | `list`, `get`, `create`, `update`, `delete`, `reorder`, `toggle` | Rule CRUD |
-| `facts` | `list`, `create`, `update`, `delete` | Fact definition CRUD |
-| `deploy` | `publish`, `live`, `rollback`, `undeploy`, `history`, `detail`, `overview` | Deployment lifecycle |
-| `analytics` | `dry-run`, `dry-run-compare`, `requirements`, `simulation start/status/list/cancel/export` | Testing & analysis |
-| `history` | `list`, `get`, `stats` | Execution history |
-| `integrations` | `list`, `get`, `save`, `delete`, `config-spec` | External integrations |
-| `logs` | `list`, `get`, `action`, `bulk-action` | Failure log management |
+| Group          | Commands                                                                                   | Description                     |
+|----------------|--------------------------------------------------------------------------------------------|---------------------------------|
+| `auth`         | `login`, `logout`, `whoami`                                                                | Authentication                  |
+| `status`       | (root)                                                                                     | API health check                |
+| `groups`       | `list`, `get`, `create`, `update`, `delete` + `ab-test start\|stop\|adjust`                | Policy group CRUD + A/B testing |
+| `versions`     | `list`, `get`, `create`, `update`, `delete`, `clone`                                       | Version CRUD                    |
+| `rules`        | `list`, `get`, `create`, `update`, `delete`, `reorder`, `toggle`                           | Rule CRUD                       |
+| `facts`        | `list`, `create`, `update`, `delete`                                                       | Fact definition CRUD            |
+| `deploy`       | `publish`, `live`, `rollback`, `undeploy`, `history`, `detail`, `overview`                 | Deployment lifecycle            |
+| `analytics`    | `dry-run`, `dry-run-compare`, `requirements`, `simulation start/status/list/cancel/export` | Testing & analysis              |
+| `history`      | `list`, `get`, `stats`                                                                     | Execution history               |
+| `integrations` | `list`, `get`, `save`, `delete`, `config-spec`                                             | External integrations           |
+| `logs`         | `list`, `get`, `action`, `bulk-action`                                                     | Failure log management          |
 
 ## Pagination
 
@@ -97,7 +100,9 @@ All list endpoints return a `PageResponse`:
 
 ```json
 {
-  "content": [...],
+  "content": [
+    ...
+  ],
   "totalElements": 42,
   "totalPages": 3,
   "pageNo": 0,
@@ -121,13 +126,13 @@ API errors return:
 
 **Common error codes and what to do:**
 
-| Code | Meaning | Action |
-|---|---|---|
-| `ENTITY_NOT_FOUND` | Resource doesn't exist | Verify the ID. Run the corresponding `list` command. |
-| `INVALID_INPUT` | Validation failed | Check required fields. Run `lexq analytics requirements` for fact requirements. |
-| `CANNOT_MODIFY` | Version is not DRAFT | Clone the version to create a new DRAFT: `lexq versions clone` |
-| `EMPTY_RULES` | Publish attempted with 0 rules | Add at least one rule before publishing. |
-| `UNAUTHORIZED` | Invalid or missing API key | Run `lexq auth login` with a valid key. |
+| Code               | Meaning                        | Action                                                                          |
+|--------------------|--------------------------------|---------------------------------------------------------------------------------|
+| `ENTITY_NOT_FOUND` | Resource doesn't exist         | Verify the ID. Run the corresponding `list` command.                            |
+| `INVALID_INPUT`    | Validation failed              | Check required fields. Run `lexq analytics requirements` for fact requirements. |
+| `CANNOT_MODIFY`    | Version is not DRAFT           | Clone the version to create a new DRAFT: `lexq versions clone`                  |
+| `EMPTY_RULES`      | Publish attempted with 0 rules | Add at least one rule before publishing.                                        |
+| `UNAUTHORIZED`     | Invalid or missing API key     | Run `lexq auth login` with a valid key.                                         |
 
 ## Important Conventions
 
@@ -136,4 +141,5 @@ API errors return:
 3. **Dates use ISO 8601.** Example: `2025-01-01T00:00:00Z`. Time zone is UTC.
 4. **JSON bodies via `--json`.** Most create/update commands accept `--json '<body>'` for the request body.
 5. **File input via `--file`.** Analytics commands accept `--file path/to/body.json` as an alternative to `--json`.
-6. **Confirmation prompts.** Destructive operations (delete, cancel, undeploy) prompt for confirmation. Use `--force` to skip in automation.
+6. **Confirmation prompts.** Destructive operations (delete, cancel, undeploy) prompt for confirmation. Use `--force` to
+   skip in automation.