@lexq/cli 0.1.18 → 0.1.20

package/dist/index.js

@@ -10,6 +10,7 @@ import { dirname as dirname2, join as join3 } from "path";
 import "commander";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
+import dedent from "dedent";
 
 // src/lib/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
@@ -165,8 +166,32 @@ function printError(error) {
 
 // src/commands/auth.ts
 function registerAuthCommands(program) {
-  const auth = program.command("auth").description("Manage authentication");
-  auth.command("login").description("Authenticate with your LexQ API key").action(async () => {
+  const auth = program.command("auth").description("Manage authentication").addHelpText(
+    "after",
+    dedent`
+
+        Commands:
+          login     Save your API key locally
+          logout    Remove stored credentials
+          whoami    Verify authentication and show account info
+
+        Getting Started:
+          1. Get your API key from the LexQ Console (Settings → API Keys)
+          2. Run: lexq auth login
+          3. Verify: lexq auth whoami
+      `
+  );
+  auth.command("login").description("Authenticate with your LexQ API key").addHelpText(
+    "after",
+    dedent`
+
+        Example:
+          $ lexq auth login
+          Enter your API Key: sk_live_****
+
+          ✓ API key saved to ~/.lexq/config.json
+      `
+  ).action(async () => {
     try {
       const rl = createInterface({ input: stdin, output: stdout });
       const apiKey = await rl.question("Enter your API Key: ");
@@ -187,22 +212,35 @@ function registerAuthCommands(program) {
     deleteConfig();
     console.log("\u2713 Credentials removed.");
   });
-  auth.command("whoami").description("Show current authentication info").action(async () => {
+  auth.command("whoami").description("Show current authentication info").addHelpText(
+    "after",
+    dedent`
+
+        Example:
+          $ lexq auth whoami
+          { "tenantId": "abc-123", "userId": "...", "role": "ADMIN", "apiKey": "sk_live_****abcd" }
+      `
+  ).action(async () => {
     try {
+      const globalOpts = program.opts();
       const config = loadConfig();
-      if (!config.apiKey) {
+      const apiKey = globalOpts.apiKey ?? config.apiKey;
+      const baseUrl = globalOpts.baseUrl ?? config.baseUrl;
+      if (!apiKey) {
         console.error('Not authenticated. Run "lexq auth login" first.');
         process.exit(1);
       }
       const info = await apiRequest("GET", "whoami", {
-        apiKey: config.apiKey,
-        baseUrl: config.baseUrl
+        apiKey,
+        baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
       });
-      const masked = config.apiKey.length > 8 ? config.apiKey.substring(0, 4) + "****" + config.apiKey.substring(config.apiKey.length - 4) : "****";
+      const masked = apiKey.length > 8 ? apiKey.substring(0, 4) + "****" + apiKey.substring(apiKey.length - 4) : "****";
       printJson({
         ...info,
         apiKey: masked,
-        baseUrl: config.baseUrl
+        baseUrl
       });
     } catch (error) {
       printError(error);
@@ -213,8 +251,19 @@ function registerAuthCommands(program) {
 
 // src/commands/status.ts
 import "commander";
+import dedent2 from "dedent";
 function registerStatusCommand(program) {
-  program.command("status").description("Check API connectivity and authentication").action(async () => {
+  program.command("status").description("Check API connectivity and authentication").addHelpText(
+    "after",
+    dedent2`
+
+        Example:
+          $ lexq status
+          { "status": "ok", "latencyMs": 142, "tenantId": "abc-123", "role": "ADMIN" }
+
+        Use this to verify your API key is valid and the LexQ API is reachable.
+      `
+  ).action(async () => {
     const globalOpts = program.opts();
     const startTime = Date.now();
     try {
@@ -237,8 +286,26 @@ function registerStatusCommand(program) {
 
 // src/commands/groups.ts
 import "commander";
+import dedent3 from "dedent";
 function registerGroupCommands(program) {
-  const groups = program.command("groups").description("Manage policy groups");
+  const groups = program.command("groups").description("Manage policy groups").addHelpText(
+    "after",
+    dedent3`
+
+        A policy group is the top-level container for rule versions.
+        It controls deployment lifecycle, conflict resolution, and A/B testing.
+
+        Commands:
+          list        List all policy groups
+          get         Get group detail by ID
+          create      Create a new group
+          update      Update group settings
+          delete      Archive a group
+          ab-test     Manage A/B tests (start, stop, adjust)
+
+        Statuses: ACTIVE, DISABLED (emergency stop), ARCHIVED (soft delete)
+      `
+  );
   groups.command("list").description("List all policy groups").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
     try {
       const globalOpts = program.opts();
@@ -288,7 +355,28 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  groups.command("create").description("Create a new policy group").requiredOption("--json <body>", "Request body as JSON string").action(async (opts) => {
+  groups.command("create").description("Create a new policy group").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent3`
+
+        Example:
+          $ lexq groups create --json '{
+              "name": "Payment Policy",
+              "description": "Rules for payment processing",
+              "priority": 0
+            }'
+
+        Fields:
+          name                string    Group name (required, unique per tenant)
+          description         string    Description (optional, max 255 chars)
+          priority            number    Execution priority — lower runs first (required, min 0)
+          activationGroup     string    Cross-group conflict resolution key (optional)
+          activationMode      string    NONE | EXCLUSIVE | MAX_N  [default: NONE]
+          activationStrategy  string    FIRST_MATCH | HIGHEST_PRIORITY | MAX_BENEFIT  [default: FIRST_MATCH]
+          executionLimit      number    Max rules to fire in MAX_N mode (optional)
+          status              string    ACTIVE | DISABLED  [default: ACTIVE]
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
@@ -305,7 +393,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  groups.command("update").description("Update a policy group").requiredOption("--id <groupId>", "Policy group ID").requiredOption("--json <body>", "Request body as JSON string").action(async (opts) => {
+  groups.command("update").description("Update a policy group").requiredOption("--id <groupId>", "Policy group ID").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent3`
+
+        Example:
+          $ lexq groups update --id <groupId> --json '{"description": "Updated", "priority": 1}'
+
+        All fields are optional — only provided fields are updated.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
@@ -322,7 +419,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  groups.command("delete").description("Delete a policy group").requiredOption("--id <groupId>", "Policy group ID").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  groups.command("delete").description("Delete a policy group").requiredOption("--id <groupId>", "Policy group ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent3`
+
+        This archives the group (soft delete). Use --force to skip the confirmation prompt.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -347,8 +450,31 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  const abTest = groups.command("ab-test").description("A/B test management");
-  abTest.command("start").description("Start an A/B test").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Challenger version ID").requiredOption("--traffic-rate <rate>", "Traffic rate for challenger (1-99)").action(async (opts) => {
+  const abTest = groups.command("ab-test").description("A/B test management").addHelpText(
+    "after",
+    dedent3`
+
+        Split traffic between the current live version and a challenger version.
+
+        Commands:
+          start     Start an A/B test with a challenger version
+          stop      Stop the test and revert to 100% live version
+          adjust    Change the traffic percentage
+
+        The traffic rate (1-99) determines what percentage goes to the challenger.
+        The remaining traffic continues to the current live version.
+      `
+  );
+  abTest.command("start").description("Start an A/B test").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Challenger version ID").requiredOption("--traffic-rate <rate>", "Traffic rate for challenger (1-99)").addHelpText(
+    "after",
+    dedent3`
+
+        Example:
+          $ lexq groups ab-test start --group-id <gid> --version-id <vid> --traffic-rate 20
+
+          Routes 20% of traffic to the challenger version, 80% to the current live version.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = {
@@ -397,7 +523,14 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  abTest.command("adjust").description("Adjust A/B test traffic rate").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--traffic-rate <rate>", "New traffic rate (1-99)").action(async (opts) => {
+  abTest.command("adjust").description("Adjust A/B test traffic rate").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--traffic-rate <rate>", "New traffic rate (1-99)").addHelpText(
+    "after",
+    dedent3`
+
+        Example:
+          $ lexq groups ab-test adjust --group-id <gid> --traffic-rate 50
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = {
@@ -424,8 +557,27 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
 // src/commands/versions.ts
 import "commander";
+import dedent4 from "dedent";
 function registerVersionCommands(program) {
-  const versions = program.command("versions").description("Manage policy versions");
+  const versions = program.command("versions").description("Manage policy versions").addHelpText(
+    "after",
+    dedent4`
+
+        A version is an immutable snapshot of rules within a policy group.
+
+        Lifecycle: DRAFT → ACTIVE (publish) → ARCHIVED (superseded) | EXPIRED (past effectiveTo)
+
+        Commands:
+          list      List versions for a group
+          get       Get version detail
+          create    Create a new DRAFT version
+          update    Update DRAFT version metadata
+          delete    Delete a DRAFT version
+          clone     Duplicate a version (creates a new DRAFT with same rules)
+
+        Only DRAFT versions can be modified. Published versions are locked.
+      `
+  );
   versions.command("list").description("List versions for a policy group").requiredOption("--group-id <groupId>", "Policy group ID").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
     try {
       const globalOpts = program.opts();
@@ -483,7 +635,25 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("create").description("Create a new draft version").requiredOption("--group-id <groupId>", "Policy group ID").option("--commit-message <message>", "Commit message").option("--effective-from <date>", "Effective from (ISO datetime)").option("--effective-to <date>", "Effective to (ISO datetime)").option("--json <body>", "Full request body as JSON (overrides other options)").action(async (opts) => {
+  versions.command("create").description("Create a new draft version").requiredOption("--group-id <groupId>", "Policy group ID").option("--commit-message <message>", "Commit message").option("--effective-from <date>", "Effective from (ISO datetime)").option("--effective-to <date>", "Effective to (ISO datetime)").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+    "after",
+    dedent4`
+
+        Examples:
+          $ lexq versions create --group-id <gid> --commit-message "Initial version"
+
+          $ lexq versions create --group-id <gid> --json '{
+              "commitMessage": "Seasonal promo",
+              "effectiveFrom": "2026-06-01T00:00:00Z",
+              "effectiveTo": "2026-08-31T23:59:59Z"
+            }'
+
+        Fields:
+          commitMessage    string      Version description (optional, max 255 chars)
+          effectiveFrom    datetime    Start of effective period (optional, ISO-8601)
+          effectiveTo      datetime    End of effective period (optional, auto-expires)
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = opts.json ? JSON.parse(opts.json) : buildCreateBody(opts);
@@ -504,7 +674,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <date>", "Effective from (ISO datetime)").option("--effective-to <date>", "Effective to (ISO datetime)").option("--json <body>", "Full request body as JSON (overrides other options)").action(async (opts) => {
+  versions.command("update").description("Update a draft version metadata").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--commit-message <message>", "Commit message").option("--effective-from <date>", "Effective from (ISO datetime)").option("--effective-to <date>", "Effective to (ISO datetime)").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+    "after",
+    dedent4`
+
+        Only DRAFT versions can be updated. Published (ACTIVE) versions are immutable.
+
+        Example:
+          $ lexq versions update --group-id <gid> --id <vid> --commit-message "Updated rules"
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = opts.json ? JSON.parse(opts.json) : buildUpdateBody(opts);
@@ -525,7 +704,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("delete").description("Delete a policy version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  versions.command("delete").description("Delete a policy version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Policy version ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent4`
+
+        Only DRAFT versions can be deleted. Use --force to skip confirmation.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -550,7 +735,17 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  versions.command("clone").description("Clone (duplicate) a policy version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Source version ID to clone").action(async (opts) => {
+  versions.command("clone").description("Clone (duplicate) a policy version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--id <versionId>", "Source version ID to clone").addHelpText(
+    "after",
+    dedent4`
+
+        Creates a new DRAFT version with all rules copied from the source.
+        Use this to iterate on a published version without modifying it.
+
+        Example:
+          $ lexq versions clone --group-id <gid> --id <source-vid>
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest(
@@ -587,8 +782,27 @@ function buildUpdateBody(opts) {
 
 // src/commands/rules.ts
 import "commander";
+import dedent5 from "dedent";
 function registerRuleCommands(program) {
-  const rules = program.command("rules").description("Manage policy rules");
+  const rules = program.command("rules").description("Manage policy rules").addHelpText(
+    "after",
+    dedent5`
+
+        Rules define condition → action pairs within a version.
+        They are evaluated in priority order (lower number = higher priority).
+
+        Commands:
+          list      List rules in a version
+          get       Get rule detail
+          create    Add a new rule to a DRAFT version
+          update    Modify a rule in a DRAFT version
+          delete    Remove a rule from a DRAFT version
+          reorder   Change rule priorities (drag & drop equivalent)
+          toggle    Enable or disable a rule
+
+        Only DRAFT versions allow rule modifications.
+      `
+  );
   rules.command("list").description("List rules for a policy version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
     try {
       const globalOpts = program.opts();
@@ -646,7 +860,41 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  rules.command("create").description("Create a new rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--json <body>", "Request body as JSON string").action(async (opts) => {
+  rules.command("create").description("Create a new rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent5`
+
+        Example:
+          $ lexq rules create --group-id <gid> --version-id <vid> --json '{
+              "name": "VIP 20% Discount",
+              "priority": 0,
+              "condition": {
+                "type": "SINGLE",
+                "field": "customer_tier",
+                "operator": "EQUALS",
+                "value": "VIP",
+                "valueType": "STRING"
+              },
+              "actions": [
+                { "type": "DISCOUNT", "parameters": { "method": "PERCENTAGE", "rate": 20, "refVar": "payment_amount" } }
+              ]
+            }'
+
+        Condition Operators:
+          EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL,
+          LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
+
+        Action Types:
+          DISCOUNT, POINT, COUPON_ISSUE, BLOCK, NOTIFICATION, WEBHOOK, SET_FACT, ADD_TAG
+
+        Value Types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
+
+        Mutex (optional — rule-level conflict resolution):
+          mutexGroup       string    Logical grouping key (e.g., "best-discount")
+          mutexMode        string    NONE | EXCLUSIVE  [default: NONE]
+          mutexStrategy    string    FIRST_MATCH | HIGHEST_PRIORITY | MAX_BENEFIT
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
@@ -667,7 +915,21 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  rules.command("update").description("Update a rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--id <ruleId>", "Rule ID").requiredOption("--json <body>", "Request body as JSON string").action(async (opts) => {
+  rules.command("update").description("Update a rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--id <ruleId>", "Rule ID").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent5`
+
+        Same fields as create. Only DRAFT versions can be modified.
+
+        Example:
+          $ lexq rules update --group-id <gid> --version-id <vid> --id <rid> --json '{
+              "name": "VIP 25% Discount",
+              "actions": [
+                { "type": "DISCOUNT", "parameters": { "method": "PERCENTAGE", "rate": 25, "refVar": "payment_amount" } }
+              ]
+            }'
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
@@ -717,7 +979,18 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  rules.command("reorder").description("Reorder rules by priority (drag & drop equivalent)").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--rule-ids <ids>", "Comma-separated rule IDs in desired order").action(async (opts) => {
+  rules.command("reorder").description("Reorder rules by priority (drag & drop equivalent)").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--rule-ids <ids>", "Comma-separated rule IDs in desired order").addHelpText(
+    "after",
+    dedent5`
+
+        Assigns priority 0, 1, 2, ... to rules in the order given.
+
+        Example:
+          $ lexq rules reorder --group-id <gid> --version-id <vid> --rule-ids "id3,id1,id2"
+
+          Result: id3 → priority 0, id1 → priority 1, id2 → priority 2
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const ruleIds = opts.ruleIds.split(",").map((id) => id.trim());
@@ -744,7 +1017,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  rules.command("toggle").description("Enable or disable a rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--id <ruleId>", "Rule ID").requiredOption("--enabled <boolean>", "true or false").action(async (opts) => {
+  rules.command("toggle").description("Enable or disable a rule").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").requiredOption("--id <ruleId>", "Rule ID").requiredOption("--enabled <boolean>", "true or false").addHelpText(
+    "after",
+    dedent5`
+
+        Disabled rules are skipped during execution without deleting them.
+
+        Example:
+          $ lexq rules toggle --group-id <gid> --version-id <vid> --id <rid> --enabled false
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const isEnabled = opts.enabled === "true";
@@ -769,16 +1051,30 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
 // src/commands/facts.ts
 import "commander";
+import dedent6 from "dedent";
 function registerFactCommands(program) {
-  const facts = program.command("facts").description("Manage fact definitions (schema)");
+  const facts = program.command("facts").description("Manage fact definitions (schema)").addHelpText(
+    "after",
+    dedent6`
+
+        Facts are input variables passed during policy execution.
+        Define them here so rules can reference them in conditions and actions.
+
+        Commands:
+          list             List all fact definitions
+          create           Register a new fact
+          update           Update fact metadata
+          delete           Remove a fact definition
+          action-metadata  Show action runtime fact metadata
+
+        System facts (payment_amount, user_id, etc.) are auto-created and immutable.
+      `
+  );
   facts.command("list").description("List fact definitions").option("--keyword <keyword>", "Filter by keyword").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.keyword) params.keyword = opts.keyword;
       const data = await apiRequest("GET", "schema/facts", {
         apiKey: globalOpts.apiKey,
@@ -810,7 +1106,26 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  facts.command("create").description("Create a new fact definition").option("--key <key>", "Fact key (lowercase, underscores)").option("--name <name>", "Display name").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--description <desc>", "Description").option("--required", "Mark as required", false).option("--json <body>", "Full request body as JSON (overrides other options)").action(async (opts) => {
+  facts.command("create").description("Create a new fact definition").option("--key <key>", "Fact key (lowercase, underscores)").option("--name <n>", "Display name").option("--type <type>", "Value type: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER").option("--description <desc>", "Description").option("--required", "Mark as required", false).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+    "after",
+    dedent6`
+
+        Examples:
+          $ lexq facts create --key customer_tier --name "Customer Tier" --type STRING
+          $ lexq facts create --key order_total --name "Order Total" --type NUMBER --required
+
+          $ lexq facts create --json '{
+              "key": "user_region",
+              "name": "User Region",
+              "type": "STRING",
+              "description": "ISO country code",
+              "isRequired": false
+            }'
+
+        Value Types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
+        Key Format:  lowercase letters, numbers, underscores only (e.g., payment_amount)
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = opts.json ? JSON.parse(opts.json) : buildCreateBody2(opts);
@@ -827,7 +1142,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  facts.command("update").description("Update a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--name <name>", "Display name").option("--description <desc>", "Description").option("--required", "Mark as required").option("--no-required", "Mark as not required").option("--json <body>", "Full request body as JSON (overrides other options)").action(async (opts) => {
+  facts.command("update").description("Update a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--name <n>", "Display name").option("--description <desc>", "Description").option("--required", "Mark as required").option("--no-required", "Mark as not required").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
+    "after",
+    dedent6`
+
+        System facts cannot be modified. Only display name, description, and required flag can be changed.
+
+        Example:
+          $ lexq facts update --id <factId> --name "Updated Name" --required
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = opts.json ? JSON.parse(opts.json) : buildUpdateBody2(opts);
@@ -844,7 +1168,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  facts.command("delete").description("Delete a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  facts.command("delete").description("Delete a fact definition").requiredOption("--id <factId>", "Fact definition ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent6`
+
+        System facts cannot be deleted. Use --force to skip the confirmation prompt.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -869,7 +1199,14 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  facts.command("action-metadata").description("Get action runtime fact metadata").action(async () => {
+  facts.command("action-metadata").description("Get action runtime fact metadata").addHelpText(
+    "after",
+    dedent6`
+
+        Shows which facts are automatically created by each action type at runtime.
+        Useful for understanding what output variables are available after rule execution.
+      `
+  ).action(async () => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest("GET", "schema/action-metadata", {
@@ -886,9 +1223,8 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
   });
 }
 function buildCreateBody2(opts) {
-  if (!opts.key || !opts.name || !opts.type) {
+  if (!opts.key || !opts.name || !opts.type)
     throw new Error("--key, --name, and --type are required (or use --json).");
-  }
   const body = {
     key: opts.key,
     name: opts.name,
@@ -908,9 +1244,39 @@ function buildUpdateBody2(opts) {
 
 // src/commands/deploy.ts
 import "commander";
+import dedent7 from "dedent";
 function registerDeployCommands(program) {
-  const deploy = program.command("deploy").description("Deployment lifecycle and history");
-  deploy.command("publish").description("Publish a DRAFT version (DRAFT \u2192 ACTIVE)").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to publish").requiredOption("--memo <memo>", "Publish Deployment memo").action(async (opts) => {
+  const deploy = program.command("deploy").description("Deployment lifecycle and history").addHelpText(
+    "after",
+    dedent7`
+
+        Lifecycle: Publish (DRAFT→ACTIVE) → Deploy (ACTIVE→LIVE) → Rollback / Undeploy
+
+        Commands:
+          publish     Lock a DRAFT version (DRAFT → ACTIVE)
+          live        Push an ACTIVE version to production traffic
+          rollback    Revert to the previous deployed version
+          undeploy    Remove the live version (stops all traffic)
+          history     List deployment history with filters
+          detail      Get deployment detail with integrity check
+          overview    Show all groups' deployment status at a glance
+          deployable  List ACTIVE versions available for deployment
+          diff        Compare rule snapshots between two versions
+
+        Always dry-run before publishing. Cannot deploy a DRAFT — publish first.
+      `
+  );
+  deploy.command("publish").description("Publish a DRAFT version (DRAFT \u2192 ACTIVE)").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to publish").requiredOption("--memo <memo>", "Publish Deployment memo").addHelpText(
+    "after",
+    dedent7`
+
+        Locks the version permanently. Rules cannot be modified after publishing.
+        A snapshot hash is generated for integrity verification.
+
+        Example:
+          $ lexq deploy publish --group-id <gid> --version-id <vid> --memo "Validated via dry-run"
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       await apiRequest(
@@ -930,7 +1296,16 @@ function registerDeployCommands(program) {
       process.exit(1);
     }
   });
-  deploy.command("live").description("Deploy an ACTIVE version to live traffic").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to deploy").requiredOption("--memo <memo>", "Live Deployment memo").action(async (opts) => {
+  deploy.command("live").description("Deploy an ACTIVE version to live traffic").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to deploy").requiredOption("--memo <memo>", "Live Deployment memo").addHelpText(
+    "after",
+    dedent7`
+
+        Takes effect immediately. The version starts receiving production traffic.
+
+        Example:
+          $ lexq deploy live --group-id <gid> --version-id <vid> --memo "Go live — v3"
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       await apiRequest("POST", `policy-groups/${opts.groupId}/deploy`, {
@@ -946,7 +1321,17 @@ function registerDeployCommands(program) {
       process.exit(1);
     }
   });
-  deploy.command("rollback").description("Rollback to the previous deployed version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--memo <memo>", "Rollback reason").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  deploy.command("rollback").description("Rollback to the previous deployed version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--memo <memo>", "Rollback reason").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent7`
+
+        Reverts to the version that was live before the current one.
+        Only available if the previous version is still ACTIVE.
+
+        Example:
+          $ lexq deploy rollback --group-id <gid> --memo "High error rate" --force
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -972,7 +1357,16 @@ function registerDeployCommands(program) {
       process.exit(1);
     }
   });
-  deploy.command("undeploy").description("Remove the live version from a group").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--memo <memo>", "Undeploy reason").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  deploy.command("undeploy").description("Remove the live version from a group").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--memo <memo>", "Undeploy reason").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent7`
+
+        Stops all traffic processing for this group until a new version is deployed.
+
+        Example:
+          $ lexq deploy undeploy --group-id <gid> --memo "Maintenance window" --force
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -1001,14 +1395,18 @@ function registerDeployCommands(program) {
   deploy.command("history").description("List deployment history").option("--group-id <groupId>", "Filter by policy group").option(
     "--types <types>",
     "Filter by types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-  ).option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
+  ).option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+    "after",
+    dedent7`
+
+        Example:
+          $ lexq deploy history --group-id <gid> --types DEPLOY,ROLLBACK --format table
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.groupId) params.groupId = opts.groupId;
       if (opts.types) params.types = opts.types;
       if (opts.startDate) params.startDate = opts.startDate;
@@ -1043,7 +1441,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  deploy.command("detail").description("Get deployment detail").requiredOption("--id <deploymentId>", "Deployment ID").action(async (opts) => {
+  deploy.command("detail").description("Get deployment detail").requiredOption("--id <deploymentId>", "Deployment ID").addHelpText(
+    "after",
+    dedent7`
+
+        Includes snapshot hash and integrity check (hashValid field).
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest("GET", `deployments/${opts.id}`, {
@@ -1058,7 +1462,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  deploy.command("overview").description("Show deployment status overview for all groups").action(async () => {
+  deploy.command("overview").description("Show deployment status overview for all groups").addHelpText(
+    "after",
+    dedent7`
+
+        Shows which version is live for each group, who deployed it, and when.
+
+        Example:
+          $ lexq deploy overview --format table
+      `
+  ).action(async () => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
@@ -1087,7 +1500,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  deploy.command("deployable").description("List deployable (ACTIVE) versions for a group").requiredOption("--group-id <groupId>", "Policy group ID").action(async (opts) => {
+  deploy.command("deployable").description("List deployable (ACTIVE) versions for a group").requiredOption("--group-id <groupId>", "Policy group ID").addHelpText(
+    "after",
+    dedent7`
+
+        Shows ACTIVE versions that can be deployed. Only published versions appear here.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest(
@@ -1106,7 +1525,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  deploy.command("diff").description("Compare snapshot diff between two versions").requiredOption("--base <versionId>", "Base version ID").requiredOption("--target <versionId>", "Target version ID").action(async (opts) => {
+  deploy.command("diff").description("Compare snapshot diff between two versions").requiredOption("--base <versionId>", "Base version ID").requiredOption("--target <versionId>", "Target version ID").addHelpText(
+    "after",
+    dedent7`
+
+        Shows added, removed, and modified rules between two versions.
+
+        Example:
+          $ lexq deploy diff --base <v1-id> --target <v2-id>
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest("GET", "deployments/diff", {
@@ -1114,10 +1542,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
         baseUrl: globalOpts.baseUrl,
         dryRun: globalOpts.dryRun,
         verbose: globalOpts.verbose,
-        params: {
-          baseVersionId: opts.base,
-          targetVersionId: opts.target
-        }
+        params: { baseVersionId: opts.base, targetVersionId: opts.target }
       });
       printJson(data);
     } catch (error) {
@@ -1130,9 +1555,38 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 // src/commands/analytics.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import "commander";
+import dedent8 from "dedent";
 function registerAnalyticsCommands(program) {
-  const analytics = program.command("analytics").description("Dry run, simulation, and requirements");
-  analytics.command("dry-run").description("Execute a single dry run against a version").requiredOption("--version-id <versionId>", "Policy version ID").option("--json <body>", "Request body as JSON string").option("--file <path>", "Read request body from a JSON file").option("--debug", "Include debug traces", false).option("--mock", "Mock external calls", false).action(async (opts) => {
+  const analytics = program.command("analytics").description("Dry run, simulation, and requirements").addHelpText(
+    "after",
+    dedent8`
+
+        Test and validate rules before deploying to production.
+
+        Commands:
+          dry-run          Test a single input against a version
+          dry-run-compare  Compare results between two versions
+          requirements     Show required input facts for a version
+          simulation       Batch test against historical data (start, status, list, cancel, export)
+          dataset          Upload datasets and download templates
+
+        Workflow: facts check → dry-run → publish → simulation → deploy
+      `
+  );
+  analytics.command("dry-run").description("Execute a single dry run against a version").requiredOption("--version-id <versionId>", "Policy version ID").option("--json <body>", "Request body as JSON string").option("--file <path>", "Read request body from a JSON file").option("--debug", "Include debug traces", false).option("--mock", "Mock external calls", false).addHelpText(
+    "after",
+    dedent8`
+
+        Examples:
+          $ lexq analytics dry-run --version-id <vid> --debug --mock \\
+              --json '{"facts": {"payment_amount": 150000, "customer_tier": "VIP"}}'
+
+          $ lexq analytics dry-run --version-id <vid> --file test-input.json
+
+        The request body must include a "facts" object. Use --debug for execution traces
+        and --mock to skip external service calls (webhooks, coupons, etc.).
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = resolveBody(opts);
@@ -1158,7 +1612,20 @@ function registerAnalyticsCommands(program) {
       process.exit(1);
     }
   });
-  analytics.command("dry-run-compare").description("Compare dry run results between two versions").option("--json <body>", "Request body as JSON string").option("--file <path>", "Read request body from a JSON file").action(async (opts) => {
+  analytics.command("dry-run-compare").description("Compare dry run results between two versions").option("--json <body>", "Request body as JSON string").option("--file <path>", "Read request body from a JSON file").addHelpText(
+    "after",
+    dedent8`
+
+        Example:
+          $ lexq analytics dry-run-compare --json '{
+              "versionIdA": "<version-a-id>",
+              "versionIdB": "<version-b-id>",
+              "facts": {"payment_amount": 100000, "customer_tier": "VIP"}
+            }'
+
+        Shows side-by-side which rules matched and what actions fired for each version.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = resolveBody(opts);
@@ -1180,7 +1647,16 @@ function registerAnalyticsCommands(program) {
       process.exit(1);
     }
   });
-  analytics.command("requirements").description("Analyze required input facts for a version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").action(async (opts) => {
+  analytics.command("requirements").description("Analyze required input facts for a version").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Policy version ID").addHelpText(
+    "after",
+    dedent8`
+
+        Shows all facts referenced in conditions and actions, along with an example request body.
+
+        Example:
+          $ lexq analytics requirements --group-id <gid> --version-id <vid> --format table
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
@@ -1215,8 +1691,44 @@ function registerAnalyticsCommands(program) {
       process.exit(1);
     }
   });
-  const sim = analytics.command("simulation").description("Manage batch simulations");
-  sim.command("start").description("Start a new batch simulation").requiredOption("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").action(async (opts) => {
+  const sim = analytics.command("simulation").description("Manage batch simulations").addHelpText(
+    "after",
+    dedent8`
+
+        Batch-test a version against historical data or uploaded datasets.
+
+        Commands:
+          start     Start a new simulation
+          status    Check progress and results
+          list      List simulation history
+          cancel    Cancel a running simulation
+          export    Export results as CSV or JSON
+
+        Simulations always mock external calls. Use --format table for summary view.
+      `
+  );
+  sim.command("start").description("Start a new batch simulation").requiredOption("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
+    "after",
+    dedent8`
+
+        Example:
+          $ lexq analytics simulation start --json '{
+              "policyVersionId": "<vid>",
+              "dataset": {
+                "type": "EXECUTION_LOG",
+                "source": "RECENT",
+                "maxRecords": 1000
+              },
+              "options": {
+                "baselinePolicyVersionId": "<baseline-vid>",
+                "includeRuleStats": true
+              }
+            }'
+
+        Dataset types: EXECUTION_LOG, MANUAL
+        Dataset sources: RECENT, DATE_RANGE, MANUAL
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = resolveBody(opts);
@@ -1234,7 +1746,16 @@ function registerAnalyticsCommands(program) {
       process.exit(1);
     }
   });
-  sim.command("status").description("Get simulation status and results").requiredOption("--id <simulationId>", "Simulation ID").action(async (opts) => {
+  sim.command("status").description("Get simulation status and results").requiredOption("--id <simulationId>", "Simulation ID").addHelpText(
+    "after",
+    dedent8`
+
+        Shows progress, match rate, metric comparison (if baseline set), and per-rule stats.
+
+        Example:
+          $ lexq analytics simulation status --id <simId> --format table
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
@@ -1314,10 +1835,7 @@ function registerAnalyticsCommands(program) {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.status) params.status = opts.status;
       if (opts.from) params.from = opts.from;
       if (opts.to) params.to = opts.to;
@@ -1356,7 +1874,13 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  sim.command("cancel").description("Cancel a running simulation").requiredOption("--id <simulationId>", "Simulation ID").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  sim.command("cancel").description("Cancel a running simulation").requiredOption("--id <simulationId>", "Simulation ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent8`
+
+        Only PENDING or RUNNING simulations can be cancelled.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -1381,7 +1905,17 @@ ${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").action(async (opts) => {
+  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(
+    "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
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const exportFormat = opts.format === "csv" ? "csv" : "json";
@@ -1408,8 +1942,26 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  const dataset = analytics.command("dataset").description("Upload datasets and download templates");
-  dataset.command("upload").description("Upload a CSV or JSON file as a simulation dataset").requiredOption("--file <path>", "Path to CSV or JSON file").action(async (opts) => {
+  const dataset = analytics.command("dataset").description("Upload datasets and download templates").addHelpText(
+    "after",
+    dedent8`
+
+        Commands:
+          upload    Upload a CSV or JSON file as a simulation dataset
+          template  Download a dataset template based on version requirements
+      `
+  );
+  dataset.command("upload").description("Upload a CSV or JSON file as a simulation dataset").requiredOption("--file <path>", "Path to CSV or JSON file").addHelpText(
+    "after",
+    dedent8`
+
+        Supported formats: CSV (with header row), JSON (array of objects).
+        Use "dataset template" to generate a correctly formatted template.
+
+        Example:
+          $ lexq analytics dataset upload --file transactions.csv
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const config = loadConfig();
@@ -1455,7 +2007,17 @@ ${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").action(async (opts) => {
+  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(
+    "after",
+    dedent8`
+
+        Generates a template with all required fact columns pre-filled.
+
+        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
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const config = loadConfig();
@@ -1502,16 +2064,35 @@ function resolveBody(opts) {
 
 // src/commands/history.ts
 import "commander";
+import dedent9 from "dedent";
 function registerHistoryCommands(program) {
-  const history = program.command("history").description("Execution history");
-  history.command("list").description("List execution history").option("--trace-id <traceId>", "Filter by trace ID").option("--group-id <groupId>", "Filter by policy group").option("--version-id <versionId>", "Filter by version").option("--status <status>", "Filter by status (SUCCESS, NO_MATCH, ERROR, TIMEOUT)").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
+  const history = program.command("history").description("Execution history").addHelpText(
+    "after",
+    dedent9`
+
+        View and analyze policy execution logs from production traffic.
+
+        Commands:
+          list    List execution history with filters
+          get     Get full execution detail (request facts, traces, decisions)
+          stats   Aggregate statistics (success rate, latency, counts)
+
+        Statuses: SUCCESS, NO_MATCH, ERROR, TIMEOUT
+      `
+  );
+  history.command("list").description("List execution history").option("--trace-id <traceId>", "Filter by trace ID").option("--group-id <groupId>", "Filter by policy group").option("--version-id <versionId>", "Filter by version").option("--status <status>", "Filter by status (SUCCESS, NO_MATCH, ERROR, TIMEOUT)").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+    "after",
+    dedent9`
+
+        Examples:
+          $ lexq history list --status ERROR --format table
+          $ lexq history list --group-id <gid> --start-date 2026-04-01 --end-date 2026-04-15
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.traceId) params.traceId = opts.traceId;
       if (opts.groupId) params.policyGroupId = opts.groupId;
       if (opts.versionId) params.versionId = opts.versionId;
@@ -1553,7 +2134,14 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  history.command("get").description("Get execution detail").requiredOption("--id <traceId>", "Trace ID").action(async (opts) => {
+  history.command("get").description("Get execution detail").requiredOption("--id <traceId>", "Trace ID").addHelpText(
+    "after",
+    dedent9`
+
+        Returns the full execution detail including request facts, result traces,
+        and decision traces (SELECTED, BLOCKED_MUTEX, LOST_PRIORITY, etc.).
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest(
@@ -1572,7 +2160,17 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  history.command("stats").description("Get execution statistics").option("--group-id <groupId>", "Filter by policy group").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").action(async (opts) => {
+  history.command("stats").description("Get execution statistics").option("--group-id <groupId>", "Filter by policy group").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").addHelpText(
+    "after",
+    dedent9`
+
+        Shows total executions, success/no-match/failure counts, success rate, and avg latency.
+
+        Example:
+          $ lexq history stats --format table
+          $ lexq history stats --group-id <gid> --start-date 2026-04-01
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
@@ -1613,8 +2211,25 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
 // src/commands/integrations.ts
 import "commander";
+import dedent10 from "dedent";
 function registerIntegrationCommands(program) {
-  const integrations = program.command("integrations").description("Manage external integrations");
+  const integrations = program.command("integrations").description("Manage external integrations").addHelpText(
+    "after",
+    dedent10`
+
+        Integrations connect rule actions to external services (webhooks, coupons,
+        points, notifications, CRM, messengers).
+
+        Commands:
+          list         List all integrations
+          get          Get integration detail
+          save         Create or update an integration
+          delete       Delete an integration
+          config-spec  Show required configuration fields per type
+
+        Types: COUPON, POINT, NOTIFICATION, CRM, MESSENGER, WEBHOOK
+      `
+  );
   integrations.command("list").description("List integrations").option(
     "--type <type>",
     "Filter by type (COUPON, POINT, NOTIFICATION, CRM, MESSENGER, WEBHOOK)"
@@ -1622,10 +2237,7 @@ function registerIntegrationCommands(program) {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.type) params.type = opts.type;
       const data = await apiRequest("GET", "integrations", {
         apiKey: globalOpts.apiKey,
@@ -1671,7 +2283,40 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  integrations.command("save").description("Create or update an integration").requiredOption("--json <body>", "Request body as JSON string").action(async (opts) => {
+  integrations.command("save").description("Create or update an integration").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent10`
+
+        Examples:
+          # Create
+          $ lexq integrations save --json '{
+              "type": "WEBHOOK",
+              "name": "Order Processing",
+              "baseUrl": "https://api.example.com/webhooks/orders",
+              "isActive": true
+            }'
+
+          # Update (provide id)
+          $ lexq integrations save --json '{
+              "id": "<existing-id>",
+              "type": "WEBHOOK",
+              "name": "Order Processing (v2)",
+              "baseUrl": "https://api.example.com/v2/webhooks/orders",
+              "isActive": true
+            }'
+
+        Fields:
+          id                 string    Provide to update, omit to create
+          type               string    COUPON | POINT | NOTIFICATION | CRM | MESSENGER | WEBHOOK (required)
+          name               string    Integration name (required, unique per tenant)
+          baseUrl            string    Base URL of the external service (required)
+          credential         string    API key or token (optional, write-only)
+          additionalConfig   object    Extra config key-value pairs (optional)
+          isActive           boolean   Enable/disable  [default: true]
+
+        Use "lexq integrations config-spec" to see required fields per type.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const body = JSON.parse(opts.json);
@@ -1688,7 +2333,14 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  integrations.command("delete").description("Delete an integration").requiredOption("--id <integrationId>", "Integration ID").option("--force", "Skip confirmation prompt").action(async (opts) => {
+  integrations.command("delete").description("Delete an integration").requiredOption("--id <integrationId>", "Integration ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent10`
+
+        Rules referencing this integration will fail at execution time.
+        Use --force to skip confirmation.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       if (!opts.force) {
@@ -1713,7 +2365,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  integrations.command("config-spec").description("Get integration configuration field specs").action(async () => {
+  integrations.command("config-spec").description("Get integration configuration field specs").addHelpText(
+    "after",
+    dedent10`
+
+        Shows required and optional configuration fields for each integration type.
+
+        Example:
+          $ lexq integrations config-spec
+      `
+  ).action(async () => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest("GET", "integrations/config-spec", {
@@ -1732,6 +2393,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
 // src/commands/logs.ts
 import "commander";
+import dedent11 from "dedent";
 
 // src/types/enums.ts
 var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
@@ -1750,20 +2412,50 @@ 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/commands/logs.ts
 function registerLogCommands(program) {
-  const logs = program.command("logs").description("Failure logs");
-  logs.command("list").description("List failure logs").option("--category <category>", "Filter by category (INTEGRATION, INTERNAL)").option("--task-type <taskType>", `Filter by task type (${TaskType.join(", ")})`).option("--status <status>", "Filter by status (PENDING, RESOLVED, IGNORED)").option("--keyword <keyword>", "Search keyword").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
+  const logs = program.command("logs").description("Failure logs").addHelpText(
+    "after",
+    dedent11`
+
+        System failure logs (DLQ) for background tasks — webhook calls, coupon issuance,
+        point operations, notifications, and platform event webhooks.
+
+        Commands:
+          list         List failure logs with filters
+          get          Get failure log detail (includes payload for retry)
+          action       Process a single log (RETRY, IGNORE, RESOLVE)
+          bulk-action  Process multiple logs at once
+
+        Statuses: PENDING (needs attention), RESOLVED, IGNORED
+        Categories: INTEGRATION (external), INTERNAL (system)
+      `
+  );
+  logs.command("list").description("List failure logs").option("--category <category>", "Filter by category (INTEGRATION, INTERNAL)").option("--task-type <taskType>", `Filter by task type (${TaskType.join(", ")})`).option("--status <status>", "Filter by status (PENDING, RESOLVED, IGNORED)").option("--keyword <keyword>", "Search keyword").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+    "after",
+    dedent11`
+
+        Examples:
+          $ lexq logs list --status PENDING --format table
+          $ lexq logs list --task-type PLATFORM_WEBHOOK --category INTERNAL
+          $ lexq logs list --keyword "timeout" --start-date 2026-04-01
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const format = globalOpts.format ?? "json";
-      const params = {
-        page: opts.page,
-        size: opts.size
-      };
+      const params = { page: opts.page, size: opts.size };
       if (opts.category) params.category = opts.category;
       if (opts.taskType) params.taskType = opts.taskType;
       if (opts.status) params.status = opts.status;
@@ -1801,7 +2493,14 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  logs.command("get").description("Get failure log detail").requiredOption("--id <logId>", "Log ID").action(async (opts) => {
+  logs.command("get").description("Get failure log detail").requiredOption("--id <logId>", "Log ID").addHelpText(
+    "after",
+    dedent11`
+
+        Includes the full payload that was used for the failed operation.
+        Use this to inspect what went wrong before deciding to RETRY or RESOLVE.
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest("GET", `failure-logs/${opts.id}`, {
@@ -1816,7 +2515,19 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  logs.command("action").description("Process a failure log action (RETRY, IGNORE, RESOLVE)").requiredOption("--id <logId>", "Log ID").requiredOption("--action <action>", "Action: RETRY, IGNORE, or RESOLVE").action(async (opts) => {
+  logs.command("action").description("Process a failure log action (RETRY, IGNORE, RESOLVE)").requiredOption("--id <logId>", "Log ID").requiredOption("--action <action>", "Action: RETRY, IGNORE, or RESOLVE").addHelpText(
+    "after",
+    dedent11`
+
+        Actions:
+          RETRY    Re-execute the failed operation with the original payload
+          IGNORE   Mark as intentionally skipped (won't appear in PENDING)
+          RESOLVE  Mark as manually resolved (e.g., fixed via external system)
+
+        Example:
+          $ lexq logs action --id <logId> --action RETRY
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const data = await apiRequest(
@@ -1836,7 +2547,16 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
-  logs.command("bulk-action").description("Bulk process failure logs").requiredOption("--ids <logIds>", "Comma-separated log IDs").requiredOption("--action <action>", "Action: RETRY, IGNORE, or RESOLVE").action(async (opts) => {
+  logs.command("bulk-action").description("Bulk process failure logs").requiredOption("--ids <logIds>", "Comma-separated log IDs").requiredOption("--action <action>", "Action: RETRY, IGNORE, or RESOLVE").addHelpText(
+    "after",
+    dedent11`
+
+        Processes each log individually. Failures are skipped with a warning.
+
+        Example:
+          $ lexq logs bulk-action --ids "id1,id2,id3" --action RESOLVE
+      `
+  ).action(async (opts) => {
     try {
       const globalOpts = program.opts();
       const logIds = opts.ids.split(",").map((id) => id.trim());
@@ -1855,8 +2575,212 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
   });
 }
 
+// src/commands/webhook-subscriptions.ts
+import "commander";
+import dedent12 from "dedent";
+function registerWebhookSubscriptionCommands(program) {
+  const webhooks = program.command("webhook-subscriptions").description("Manage platform event webhook subscriptions").addHelpText(
+    "after",
+    dedent12`
+
+        Receive notifications when deployment lifecycle events occur
+        (publish, deploy, rollback, undeploy).
+
+        Commands:
+          list      List all webhook subscriptions
+          get       Get subscription detail
+          save      Create or update a subscription
+          delete    Delete a subscription
+          test      Send a test event to verify connectivity
+
+        This is separate from Integrations (rule action webhooks).
+        Webhook subscriptions are for platform-level event notifications.
+      `
+  );
+  webhooks.command("list").description("List webhook subscriptions").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const format = globalOpts.format ?? "json";
+      const data = await apiRequest(
+        "GET",
+        "webhook-subscriptions",
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          params: { page: opts.page, size: opts.size }
+        }
+      );
+      if (format === "table") {
+        printTable(
+          ["ID", "Name", "Events", "Format", "Active"],
+          data.content.map((s) => [
+            s.id.substring(0, 8),
+            s.name,
+            s.subscribedEvents.join(", "),
+            s.payloadFormat,
+            s.isActive ? "\u2713" : "\u2717"
+          ]),
+          { truncate: 32 }
+        );
+        console.log(`
+${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
+      } else {
+        printJson(data);
+      }
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  webhooks.command("get").description("Get webhook subscription detail").requiredOption("--id <subscriptionId>", "Subscription ID").action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const data = await apiRequest(
+        "GET",
+        `webhook-subscriptions/${opts.id}`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose
+        }
+      );
+      printJson(data);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  webhooks.command("save").description("Create or update a webhook subscription").requiredOption("--json <body>", "Request body as JSON string").addHelpText(
+    "after",
+    dedent12`
+
+        Examples:
+          # Create (Slack format)
+          $ lexq webhook-subscriptions save --json '{
+              "name": "Deploy Alert",
+              "webhookUrl": "https://hooks.slack.com/services/...",
+              "subscribedEvents": ["DEPLOYED", "ROLLED_BACK"],
+              "payloadFormat": "SLACK"
+            }'
+
+          # Update (provide id)
+          $ lexq webhook-subscriptions save --json '{
+              "id": "<existing-id>",
+              "name": "Deploy Alert",
+              "webhookUrl": "https://hooks.slack.com/services/...",
+              "subscribedEvents": ["VERSION_PUBLISHED", "DEPLOYED", "ROLLED_BACK", "UNDEPLOYED"],
+              "payloadFormat": "SLACK",
+              "secret": "my-hmac-secret"
+            }'
+
+        Fields:
+          name                string      Subscription name (required, unique per tenant)
+          webhookUrl          string      Webhook endpoint URL (required)
+          subscribedEvents    string[]    VERSION_PUBLISHED, DEPLOYED, ROLLED_BACK, UNDEPLOYED
+          payloadFormat       string      GENERIC (full JSON) or SLACK ({"text":"..."})  [default: GENERIC]
+          secret              string      HMAC-SHA256 signing secret (optional)
+          isActive            boolean     Enable/disable (optional)  [default: true]
+          id                  string      Provide to update, omit to create
+
+        When secret is set, an X-LexQ-Signature header (sha256=hex) is sent for verification.
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const body = JSON.parse(opts.json);
+      const data = await apiRequest(
+        "POST",
+        "webhook-subscriptions",
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          body
+        }
+      );
+      printJson(data);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  webhooks.command("delete").description("Delete a webhook subscription").requiredOption("--id <subscriptionId>", "Subscription ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent12`
+
+        Use --force to skip the confirmation prompt.
+
+        Example:
+          $ lexq webhook-subscriptions delete --id <id> --force
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      if (!opts.force) {
+        const { createInterface: createInterface2 } = await import("readline/promises");
+        const rl = createInterface2({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(`Delete webhook subscription ${opts.id}? [y/N] `);
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Cancelled.");
+          return;
+        }
+      }
+      await apiRequest("DELETE", `webhook-subscriptions/${opts.id}`, {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
+      });
+      console.log(`\u2713 Webhook subscription ${opts.id} deleted.`);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  webhooks.command("test").description("Send a test event to verify webhook connectivity").requiredOption("--id <subscriptionId>", "Subscription ID").addHelpText(
+    "after",
+    dedent12`
+
+        Sends a test event to the webhook URL and reports the HTTP status code.
+        Does not record failures in the failure log.
+
+        The response includes:
+          statusCode     HTTP status code returned by the webhook endpoint
+          success        true if 2xx response received
+          message        human-readable status message
+
+        Example:
+          $ lexq webhook-subscriptions test --id <id>
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const data = await apiRequest(
+        "POST",
+        `webhook-subscriptions/${opts.id}/test`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose
+        }
+      );
+      printJson(data);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+}
+
 // src/commands/serve.ts
 import "commander";
+import dedent15 from "dedent";
 
 // src/mcp/server.ts
 import { readFileSync as readFileSync3 } from "fs";
@@ -1996,7 +2920,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"),
@@ -2093,10 +3017,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)")
       }
@@ -2107,7 +3031,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"),
@@ -2150,6 +3074,7 @@ function registerVersionTools(server, callApi) {
 
 // src/mcp/tools/rules.ts
 import { z as z3 } from "zod";
+import dedent13 from "dedent";
 function registerRuleTools(server, callApi) {
   server.registerTool(
     "lexq_rules_list",
@@ -2184,32 +3109,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.
-
-      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.
-
-      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 }]
-
-      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 }`,
+      description: dedent13`
+        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 — 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
+
+        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 — {{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"),
@@ -2342,12 +3269,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 })
@@ -2363,6 +3290,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
@@ -2376,7 +3312,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 } })
@@ -2389,7 +3325,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`, {
@@ -2403,7 +3339,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`, {
@@ -2417,7 +3353,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`, {
@@ -2433,13 +3369,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 });
     }
   );
@@ -2463,18 +3405,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 dedent14 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: dedent14`
+        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}'),
@@ -2493,7 +3470,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: dedent14`
+        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"),
@@ -2523,21 +3506,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: dedent14`
+        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")
       }
@@ -2608,16 +3593,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: dedent14`
+        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)")
@@ -2825,14 +3812,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(
@@ -2851,6 +3838,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);
@@ -2863,6 +3920,7 @@ function registerAllTools(server, callApi) {
   registerHistoryTools(server, callApi);
   registerIntegrationTools(server, callApi);
   registerLogTools(server, callApi);
+  registerWebhookSubscriptionTools(server, callApi);
 }
 
 // src/mcp/server.ts
@@ -2888,7 +3946,27 @@ async function startMcpServer() {
 
 // src/commands/serve.ts
 function registerServeCommand(program) {
-  program.command("serve").description("Start LexQ as a server for AI agent integrations").option("--mcp", "Start as MCP (Model Context Protocol) server over stdio").action(async (opts) => {
+  program.command("serve").description("Start LexQ as a server for AI agent integrations").option("--mcp", "Start as MCP (Model Context Protocol) server over stdio").addHelpText(
+    "after",
+    dedent15`
+
+        Example:
+          $ lexq serve --mcp
+
+          Starts a stdio MCP server that exposes 60 tools for policy management.
+          Used by Claude Desktop, Claude.ai, Cursor, and other MCP-compatible clients.
+
+        Claude Desktop config (~/.claude/claude_desktop_config.json):
+          {
+            "mcpServers": {
+              "lexq": {
+                "command": "npx",
+                "args": ["-y", "@lexq/cli", "serve", "--mcp"]
+              }
+            }
+          }
+      `
+  ).action(async (opts) => {
     if (!opts.mcp) {
       console.error(
         "Error: --mcp flag is required.\nUsage: lexq serve --mcp\n\nStarts a stdio MCP server for Claude Desktop, Claude.ai, Gemini, etc."
@@ -2923,6 +4001,7 @@ function createCli() {
   registerHistoryCommands(program);
   registerIntegrationCommands(program);
   registerLogCommands(program);
+  registerWebhookSubscriptionCommands(program);
   registerServeCommand(program);
   return program;
 }