@lexq/cli 0.1.38 → 0.1.40

package/dist/index.js

@@ -933,9 +933,27 @@ ${data.length} total`);
               ]
             }'
 
-        Condition Operators:
-          EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL,
-          LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
+        Condition Operators (by fact type):
+          STRING        EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+          NUMBER        EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL,
+                        LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+          BOOLEAN       EQUALS, NOT_EQUALS
+          LIST_STRING   HAS_ANY, HAS_ALL, HAS_NONE
+          LIST_NUMBER   HAS_ANY, HAS_ALL, HAS_NONE
+
+          Using an operator outside its fact type is rejected by the server.
+
+        List-typed facts (HAS_*) — the value is always an array:
+          HAS_ANY    fact has at least one of the given values
+          HAS_ALL    fact has all of the given values
+          HAS_NONE   fact has none of the given values
+
+          Example:
+            { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY",
+              "value": ["VIP", "GOLD"], "valueType": "LIST_STRING" }
+
+          CONTAINS is substring match on STRING facts, not list membership.
+          IN is the mirror of HAS_*: scalar fact, list value.
 
         Action Types:
           MUTATE_FACT, INCREMENT_FACT, EMIT_EVENT, BLOCK, EMIT_NOTIFICATION, EMIT_WEBHOOK, SET_FACT, ADD_TAG
@@ -1358,13 +1376,16 @@ function registerDeployCommands(program) {
     "after",
     dedent7`
 
-        Lifecycle: Publish (DRAFT→ACTIVE) → Deploy (ACTIVE→LIVE) → Rollback / Undeploy
+        Lifecycle: Publish (DRAFT→ACTIVE) → Deploy or Schedule (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)
+          schedule    Schedule an ACTIVE version to auto-deploy at its effective start
+          unschedule  Cancel the pending scheduled deployment
+          schedules   List scheduled deployments (all statuses)
           history     List deployment history with filters
           detail      Get deployment detail with integrity check
           overview    Show all groups' deployment status at a glance
@@ -1502,10 +1523,7 @@ function registerDeployCommands(program) {
       process.exit(1);
     }
   });
-  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").addHelpText(
+  deploy.command("history").description("List deployment history").option("--group-id <groupId>", "Filter by policy group").option("--types <types>", "Filter by types (comma-separated: 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").addHelpText(
     "after",
     dedent7`
 
@@ -1660,6 +1678,119 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
       process.exit(1);
     }
   });
+  deploy.command("schedule").description("Schedule an ACTIVE version to auto-deploy at its effective start").requiredOption("--group-id <groupId>", "Policy group ID").requiredOption("--version-id <versionId>", "Version ID to schedule").requiredOption("--memo <memo>", "Schedule memo").addHelpText(
+    "after",
+    dedent7`
+
+        The version must be ACTIVE with a future effective start date; the system
+        deploys it automatically at that time (within one scheduler tick, ≤60s).
+        One pending schedule per group. Manual deploy/rollback/undeploy, starting
+        an A/B test, or archiving the group cancels the pending schedule.
+
+        Example:
+          $ lexq deploy schedule --group-id <gid> --version-id <vid> --memo "Q4 pricing"
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const data = await apiRequest(
+        "POST",
+        `policy-groups/${opts.groupId}/schedule`,
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          body: { versionId: opts.versionId, memo: opts.memo }
+        }
+      );
+      console.log(`\u2713 Scheduled v${data.versionNo ?? "?"} for ${data.scheduledFor}.`);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  deploy.command("unschedule").description("Cancel the pending scheduled deployment for a group").requiredOption("--group-id <groupId>", "Policy group ID").option("--force", "Skip confirmation prompt").addHelpText(
+    "after",
+    dedent7`
+
+        Cancels the PENDING schedule only — the version itself is not affected.
+
+        Example:
+          $ lexq deploy unschedule --group-id <gid> --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(
+          `Cancel the pending scheduled deployment for group ${opts.groupId}? [y/N] `
+        );
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Canceled.");
+          return;
+        }
+      }
+      await apiRequest("DELETE", `policy-groups/${opts.groupId}/schedule`, {
+        apiKey: globalOpts.apiKey,
+        baseUrl: globalOpts.baseUrl,
+        dryRun: globalOpts.dryRun,
+        verbose: globalOpts.verbose
+      });
+      console.log(`\u2713 Scheduled deployment canceled for group ${opts.groupId}.`);
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
+  deploy.command("schedules").description("List scheduled deployments (all statuses, newest first)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
+    "after",
+    dedent7`
+
+        Example:
+          $ lexq deploy schedules --format table
+      `
+  ).action(async (opts) => {
+    try {
+      const globalOpts = program.opts();
+      const format = globalOpts.format ?? "json";
+      const data = await apiRequest(
+        "GET",
+        "policy-groups/schedules",
+        {
+          apiKey: globalOpts.apiKey,
+          baseUrl: globalOpts.baseUrl,
+          dryRun: globalOpts.dryRun,
+          verbose: globalOpts.verbose,
+          params: { page: opts.page, size: opts.size }
+        }
+      );
+      if (format === "table") {
+        printTable(
+          ["Status", "Group", "Version", "Scheduled For", "By", "Result"],
+          data.content.map((s) => [
+            s.status,
+            s.policyGroupName ?? s.policyGroupId.substring(0, 8),
+            s.versionNo != null ? `v${s.versionNo}` : "\u2013",
+            s.scheduledFor.substring(0, 16),
+            s.scheduledByName,
+            s.status === "EXECUTED" ? s.executedAt?.substring(0, 16) ?? "\u2013" : s.status === "CANCELED" ? s.canceledReason ?? "\u2013" : s.status === "FAILED" ? s.failedReason ?? "\u2013" : "\u2013"
+          ]),
+          { truncate: 20 }
+        );
+        console.log(`
+${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
+      } else {
+        printJson(data);
+      }
+    } catch (error) {
+      printError(error);
+      process.exit(1);
+    }
+  });
 }
 async function warnUnregisteredFacts(globalOpts, groupId, versionId) {
   if (globalOpts.dryRun) return;
@@ -2206,13 +2337,16 @@ var TaskType = [
   // Internal
   "IMAGE_PROCESSING",
   "DAILY_SETTLEMENT",
-  "PLATFORM_WEBHOOK"
+  "PLATFORM_WEBHOOK",
+  "SCHEDULED_DEPLOYMENT"
 ];
 var PlatformEventType = [
   "VERSION_PUBLISHED",
   "DEPLOYED",
   "ROLLED_BACK",
-  "UNDEPLOYED"
+  "UNDEPLOYED",
+  "DEPLOY_SCHEDULED",
+  "DEPLOY_SCHEDULE_CANCELED"
 ];
 var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
@@ -3596,8 +3730,23 @@ function registerRuleTools(server, callApi) {
         defined (non-blocking, version-wide) — use it to decide what to register.
 
         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
+        
+        Operators are constrained by the LEFT fact's type (from lexq_facts_list). Using one outside
+        its type is rejected by the server — check the fact type before choosing an operator.
+        - STRING fact:       EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+        - NUMBER fact:       EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+        - BOOLEAN fact:      EQUALS, NOT_EQUALS
+        - LIST_* fact:       HAS_ANY, HAS_ALL, HAS_NONE (only these)
+
+        HAS_* query list-typed facts. Value is always an array whose element type matches the fact:
+        - HAS_ANY: fact has at least one of the given values
+        - HAS_ALL: fact has all of the given values
+        - HAS_NONE: fact has none of the given values
+        Example: { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY", "value": ["VIP","GOLD"], "valueType": "LIST_STRING" }
+
+        Do NOT use CONTAINS on a list fact — CONTAINS is substring match on STRING facts only.
+        IN is the mirror of HAS_*: IN takes a scalar fact with a list value; HAS_* takes lists on both sides.
 
         Actions: [{ type, parameters }]
 
@@ -3606,14 +3755,14 @@ function registerRuleTools(server, callApi) {
         - INCREMENT_FACT: { targetVar: string, method: "PERCENTAGE"|"AMOUNT", refVar?: string (required when PERCENTAGE), rate?: number (when PERCENTAGE), value?: number (when AMOUNT), rounding?: RoundingOption } targetVar (accumulation target) must exist at execution; refVar (PERCENTAGE source) must exist when method is PERCENTAGE. Each is supplied as an input fact or written by a prior action in this rule — a missing required fact throws (no 0 default). Note: external system call (e.g. point system sync) is NOT a primitive responsibility. Compose [INCREMENT_FACT, EMIT_EVENT] chain instead.
         - EMIT_EVENT: { integrationId: uuid, eventPayload: object (Map<string,unknown>, ≥1 entry) } eventPayload is passed through to the integration provider as-is. Domain-specific keys (couponId, ticketId, etc.) are routed by the provider, not validated by the engine.
         - BLOCK: { reason: string }
-        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token). notificationPayload (channel, templateId, body, variables, etc.) is passed through to the provider.
+        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token) and is REQUIRED — the named fact must be present in the request or the action throws. (Contrast with ADD_TAG, where targetVar is an optional write target that is created if absent.)
         - EMIT_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 }
+        - ADD_TAG: { tag: string, targetVar?: string (defaults to "user_tags") } Appends tag to a LIST_STRING fact, creating it if absent. Adding an existing tag is a no-op (idempotent). Read tags back with HAS_ANY / HAS_ALL / HAS_NONE.
         
         RoundingOption (optional, MUTATE_FACT / INCREMENT_FACT only): { scale: integer (0..16), mode?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,
@@ -3817,7 +3966,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
@@ -3856,6 +4005,44 @@ function registerDeployTools(server, callApi) {
       body: { memo }
     })
   );
+  server.registerTool(
+    "lexq_deploy_schedule",
+    {
+      title: "Schedule Deployment",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID"),
+        versionId: z5.string().uuid().describe("ACTIVE version ID with a future effective start date"),
+        memo: z5.string().min(1).describe("Schedule memo (required)")
+      }
+    },
+    async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/schedule`, {
+      body: { versionId, memo }
+    })
+  );
+  server.registerTool(
+    "lexq_deploy_unschedule",
+    {
+      title: "Cancel Scheduled Deployment",
+      description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID")
+      }
+    },
+    async ({ groupId }) => callApi("DELETE", `policy-groups/${groupId}/schedule`)
+  );
+  server.registerTool(
+    "lexq_deploy_schedules",
+    {
+      title: "List Scheduled Deployments",
+      description: "List scheduled deployments across all groups (all statuses: PENDING, EXECUTED, CANCELED, FAILED), newest first.",
+      inputSchema: {
+        page: z5.number().int().min(0).default(0).describe("Page number"),
+        size: z5.number().int().min(1).max(100).default(20).describe("Page size")
+      }
+    },
+    async ({ page, size }) => callApi("GET", "policy-groups/schedules", { params: paginationParams(page, size) })
+  );
   server.registerTool(
     "lexq_deploy_history",
     {
@@ -3865,9 +4052,7 @@ 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"),
-        types: z5.string().optional().describe(
-          "Filter by deployment types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-        ),
+        types: z5.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
         startDate: z5.string().optional().describe("Start date (yyyy-MM-dd)"),
         endDate: z5.string().optional().describe("End date (yyyy-MM-dd)")
       }

package/dist/mcp/register.d.ts

@@ -35,6 +35,12 @@ declare function paginationParams(page?: number, size?: number): Record<string,
  */
 declare function formatUnregisteredFactWarning(meta: unknown): string | null;
 
+declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly errorCode: string | null;
+    constructor(statusCode: number, errorCode: string | null, message: string);
+}
+
 /**
  * Registers all MCP tools on the given server.
  *
@@ -43,4 +49,4 @@ declare function formatUnregisteredFactWarning(meta: unknown): string | null;
  */
 declare function registerAllTools(server: McpServer, callApi: CallApi): void;
 
-export { type CallApi, type McpToolResult, formatUnregisteredFactWarning, paginationParams, registerAllTools };
+export { ApiError, type CallApi, type McpToolResult, formatUnregisteredFactWarning, paginationParams, registerAllTools };

package/dist/mcp/register.js

@@ -154,6 +154,18 @@ import { join } from "path";
 var CONFIG_DIR = join(homedir(), ".lexq");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
+// src/lib/api-client.ts
+var ApiError = class extends Error {
+  constructor(statusCode, errorCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.name = "ApiError";
+  }
+  statusCode;
+  errorCode;
+};
+
 // src/mcp/tools/_shared.ts
 function paginationParams(page, size) {
   const params = {};
@@ -311,8 +323,23 @@ function registerRuleTools(server, callApi) {
         defined (non-blocking, version-wide) — use it to decide what to register.
 
         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
+        
+        Operators are constrained by the LEFT fact's type (from lexq_facts_list). Using one outside
+        its type is rejected by the server — check the fact type before choosing an operator.
+        - STRING fact:       EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+        - NUMBER fact:       EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+        - BOOLEAN fact:      EQUALS, NOT_EQUALS
+        - LIST_* fact:       HAS_ANY, HAS_ALL, HAS_NONE (only these)
+
+        HAS_* query list-typed facts. Value is always an array whose element type matches the fact:
+        - HAS_ANY: fact has at least one of the given values
+        - HAS_ALL: fact has all of the given values
+        - HAS_NONE: fact has none of the given values
+        Example: { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY", "value": ["VIP","GOLD"], "valueType": "LIST_STRING" }
+
+        Do NOT use CONTAINS on a list fact — CONTAINS is substring match on STRING facts only.
+        IN is the mirror of HAS_*: IN takes a scalar fact with a list value; HAS_* takes lists on both sides.
 
         Actions: [{ type, parameters }]
 
@@ -321,14 +348,14 @@ function registerRuleTools(server, callApi) {
         - INCREMENT_FACT: { targetVar: string, method: "PERCENTAGE"|"AMOUNT", refVar?: string (required when PERCENTAGE), rate?: number (when PERCENTAGE), value?: number (when AMOUNT), rounding?: RoundingOption } targetVar (accumulation target) must exist at execution; refVar (PERCENTAGE source) must exist when method is PERCENTAGE. Each is supplied as an input fact or written by a prior action in this rule — a missing required fact throws (no 0 default). Note: external system call (e.g. point system sync) is NOT a primitive responsibility. Compose [INCREMENT_FACT, EMIT_EVENT] chain instead.
         - EMIT_EVENT: { integrationId: uuid, eventPayload: object (Map<string,unknown>, ≥1 entry) } eventPayload is passed through to the integration provider as-is. Domain-specific keys (couponId, ticketId, etc.) are routed by the provider, not validated by the engine.
         - BLOCK: { reason: string }
-        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token). notificationPayload (channel, templateId, body, variables, etc.) is passed through to the provider.
+        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token) and is REQUIRED — the named fact must be present in the request or the action throws. (Contrast with ADD_TAG, where targetVar is an optional write target that is created if absent.)
         - EMIT_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 }
+        - ADD_TAG: { tag: string, targetVar?: string (defaults to "user_tags") } Appends tag to a LIST_STRING fact, creating it if absent. Adding an existing tag is a no-op (idempotent). Read tags back with HAS_ANY / HAS_ALL / HAS_NONE.
         
         RoundingOption (optional, MUTATE_FACT / INCREMENT_FACT only): { scale: integer (0..16), mode?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,
@@ -532,7 +559,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
+      description: "Deploy an ACTIVE (published) version to live traffic. Takes effect immediately. Versions whose effective start date has not arrived are rejected (P-037) \u2014 use lexq_deploy_schedule for those. Undefined facts do not block deployment (INV-4); use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: {
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID to deploy"),
@@ -571,6 +598,44 @@ function registerDeployTools(server, callApi) {
       body: { memo }
     })
   );
+  server.registerTool(
+    "lexq_deploy_schedule",
+    {
+      title: "Schedule Deployment",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID"),
+        versionId: z5.string().uuid().describe("ACTIVE version ID with a future effective start date"),
+        memo: z5.string().min(1).describe("Schedule memo (required)")
+      }
+    },
+    async ({ groupId, versionId, memo }) => callApi("POST", `policy-groups/${groupId}/schedule`, {
+      body: { versionId, memo }
+    })
+  );
+  server.registerTool(
+    "lexq_deploy_unschedule",
+    {
+      title: "Cancel Scheduled Deployment",
+      description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
+      inputSchema: {
+        groupId: z5.string().uuid().describe("Policy group ID")
+      }
+    },
+    async ({ groupId }) => callApi("DELETE", `policy-groups/${groupId}/schedule`)
+  );
+  server.registerTool(
+    "lexq_deploy_schedules",
+    {
+      title: "List Scheduled Deployments",
+      description: "List scheduled deployments across all groups (all statuses: PENDING, EXECUTED, CANCELED, FAILED), newest first.",
+      inputSchema: {
+        page: z5.number().int().min(0).default(0).describe("Page number"),
+        size: z5.number().int().min(1).max(100).default(20).describe("Page size")
+      }
+    },
+    async ({ page, size }) => callApi("GET", "policy-groups/schedules", { params: paginationParams(page, size) })
+  );
   server.registerTool(
     "lexq_deploy_history",
     {
@@ -580,9 +645,7 @@ 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"),
-        types: z5.string().optional().describe(
-          "Filter by deployment types (comma-separated: PUBLISH,DEPLOY,ROLLBACK,UNDEPLOY)"
-        ),
+        types: z5.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
         startDate: z5.string().optional().describe("Start date (yyyy-MM-dd)"),
         endDate: z5.string().optional().describe("End date (yyyy-MM-dd)")
       }
@@ -1182,13 +1245,16 @@ var TaskType = [
   // Internal
   "IMAGE_PROCESSING",
   "DAILY_SETTLEMENT",
-  "PLATFORM_WEBHOOK"
+  "PLATFORM_WEBHOOK",
+  "SCHEDULED_DEPLOYMENT"
 ];
 var PlatformEventType = [
   "VERSION_PUBLISHED",
   "DEPLOYED",
   "ROLLED_BACK",
-  "UNDEPLOYED"
+  "UNDEPLOYED",
+  "DEPLOY_SCHEDULED",
+  "DEPLOY_SCHEDULE_CANCELED"
 ];
 var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
@@ -1396,6 +1462,7 @@ function registerAllTools(server, callApi) {
   registerWebhookSubscriptionTools(server, callApi);
 }
 export {
+  ApiError,
   formatUnregisteredFactWarning,
   paginationParams,
   registerAllTools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -29,7 +29,10 @@
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
-    "prepublishOnly": "pnpm build"
+    "prepublishOnly": "pnpm build",
+    "knip": "knip",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
   },
   "keywords": [
     "lexq",
@@ -57,15 +60,14 @@
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "dedent": "^1.7.2",
-    "ora": "^8.2.0",
-    "prettier": "^3.8.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^9.20.0",
-    "@types/dedent": "^0.7.2",
     "@types/node": "^22.12.0",
     "eslint": "^10.2.0",
+    "knip": "^6.29.0",
+    "prettier": "^3.9.6",
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.24.0"

package/skills/lexq-recipes/SKILL.md

@@ -256,7 +256,7 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
       "type": "EMIT_NOTIFICATION",
       "parameters": {
         "integrationId": "<notification-integration-uuid>",
-        "target": "user_id",
+        "targetVar": "user_id",
         "notificationPayload": {
           "channel": "PUSH",
           "templateId": "welcome_points"
@@ -502,4 +502,73 @@ lexq analytics simulation start --json '{
 
 # 6. If simulation passes, deploy
 lexq deploy live --group-id <gid> --version-id <newVid> --memo "Migration complete"
-```
+```
+
+---
+
+## Recipe 11: Tag-Based Segmentation
+
+**Goal:** Write tags in one rule, branch on them in another.
+
+`user_tags` is a `LIST_STRING` fact seeded automatically for every tenant. `ADD_TAG` appends to
+it; `HAS_ANY` / `HAS_ALL` / `HAS_NONE` read it.
+
+```bash
+# Tags are written by earlier rules (or supplied as input facts).
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Tag High-Value Customers",
+  "condition": {
+    "type": "SINGLE", "field": "lifetime_value", "operator": "GREATER_THAN_OR_EQUAL",
+    "value": 1000000, "valueType": "NUMBER"
+  },
+  "actions": [
+    { "type": "ADD_TAG", "parameters": { "tag": "high_value" } }
+  ]
+}'
+
+# Branch on any one of several tags
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Priority Support for VIP or High Value",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY",
+    "value": ["VIP", "high_value"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "SET_FACT", "parameters": { "key": "support_tier", "value": "PRIORITY" } }]
+}'
+
+# Require every tag
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Beta Feature for Verified VIP",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_ALL",
+    "value": ["VIP", "verified"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "SET_FACT", "parameters": { "key": "beta_enabled", "value": true } }]
+}'
+
+# Exclude tagged users
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Promo Excludes Fraud Review",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_NONE",
+    "value": ["fraud_review", "suspended"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "MUTATE_FACT", "parameters": {
+    "refVar": "payment_amount", "method": "PERCENTAGE", "operator": "SUB", "rate": 5,
+    "rounding": { "mode": "HALF_UP", "scale": 0 }
+  }}]
+}'
+
+# Verify
+lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+  "facts": { "user_tags": ["VIP", "verified"], "payment_amount": 100000, "lifetime_value": 500000 }
+}'
+```
+
+**Notes**
+
+- The `value` is always an array, even for a single tag: `"value": ["VIP"]`.
+- `ADD_TAG` writes to `user_tags` by default. Pass `targetVar` to append to a different `LIST_STRING` fact. The list is
+  created if absent, and re-adding an existing tag is a no-op.
+- An empty array makes `HAS_ALL` and `HAS_NONE` always true — they never look at the fact.
+- Rules fire in priority order, so a tag written by rule 0 is visible to rule 1.

package/skills/lexq-rules/SKILL.md

@@ -70,17 +70,53 @@ Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
 
 ### Operators
 
-| Operator                | Types          | Description                       |
-|-------------------------|----------------|-----------------------------------|
-| `EQUALS`                | all            | Exact match                       |
-| `NOT_EQUALS`            | all            | Negation                          |
-| `GREATER_THAN`          | NUMBER         | `>`                               |
-| `GREATER_THAN_OR_EQUAL` | NUMBER         | `>=`                              |
-| `LESS_THAN`             | NUMBER         | `<`                               |
-| `LESS_THAN_OR_EQUAL`    | NUMBER         | `<=`                              |
-| `CONTAINS`              | STRING         | Substring match                   |
-| `IN`                    | STRING, NUMBER | Value is in the provided list     |
-| `NOT_IN`                | STRING, NUMBER | Value is not in the provided list |
+Operators are constrained by the **left fact's type**. Using one outside its type is rejected
+by the server — check `lexq facts list` before choosing.
+
+| Fact type                     | Allowed operators                                                                                                  |
+|-------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| `STRING`                      | `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `IN`, `NOT_IN`                                                                 |
+| `NUMBER`                      | `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `IN`, `NOT_IN` |
+| `BOOLEAN`                     | `EQUALS`, `NOT_EQUALS`                                                                                             |
+| `LIST_STRING` / `LIST_NUMBER` | `HAS_ANY`, `HAS_ALL`, `HAS_NONE`                                                                                   |
+
+| Operator                                                                      | Description                                                | `value` |
+|-------------------------------------------------------------------------------|------------------------------------------------------------|---------|
+| `EQUALS` / `NOT_EQUALS`                                                       | Exact match / negation                                     | scalar  |
+| `GREATER_THAN` / `GREATER_THAN_OR_EQUAL` / `LESS_THAN` / `LESS_THAN_OR_EQUAL` | Numeric comparison                                         | scalar  |
+| `CONTAINS`                                                                    | **Substring** match on a STRING fact — not list membership | scalar  |
+| `IN` / `NOT_IN`                                                               | Scalar fact is (not) in the given list                     | array   |
+| `HAS_ANY`                                                                     | List fact has **at least one** of the given values         | array   |
+| `HAS_ALL`                                                                     | List fact has **all** of the given values                  | array   |
+| `HAS_NONE`                                                                    | List fact has **none** of the given values                 | array   |
+
+**`IN` vs `HAS_*` — mirrors of each other.** This is the most common mistake here:
+
+```json
+// scalar fact, list value
+{
+  "field": "region",
+  "operator": "IN",
+  "value": [
+    "KR",
+    "JP"
+  ],
+  "valueType": "LIST_STRING"
+}
+
+// list fact, list value
+{
+  "field": "user_tags",
+  "operator": "HAS_ANY",
+  "value": [
+    "VIP",
+    "GOLD"
+  ],
+  "valueType": "LIST_STRING"
+}
+```
+
+Do **not** use `CONTAINS` on a list fact — that idiom works in some rule engines but is rejected here.
 
 ### Value Types
 
@@ -145,10 +181,15 @@ Each rule can have multiple actions. Actions fire sequentially.
 | `INCREMENT_FACT`    | Increment a fact (cumulative add)                        | `targetVar`, `refVar`, `method`, `value` or `rate`, `rounding`                                      |
 | `EMIT_EVENT`        | Emit an event to an external integration (coupons, etc.) | `integrationId`, `eventPayload` (Map)                                                               |
 | `BLOCK`             | Block the transaction                                    | `reason`, `code`                                                                                    |
-| `EMIT_NOTIFICATION` | Send a notification                                      | `integrationId`, `target`, `notificationPayload` (Map)                                              |
+| `EMIT_NOTIFICATION` | Send a notification                                      | `integrationId`, `targetVar`, `notificationPayload` (Map)                                           |
 | `EMIT_WEBHOOK`      | Call an external URL                                     | `url`, `payloadTemplate`                                                                            |
 | `SET_FACT`          | Set a fact value (literal assignment)                    | `key`, `value`                                                                                      |
-| `ADD_TAG`           | Add a tag to the result                                  | `tag`                                                                                               |
+| `ADD_TAG`           | Append a tag to a list fact                              | `tag`, `targetVar` (optional, default `user_tags`)                                                  |
+
+**Two different `targetVar` meanings.** `EMIT_NOTIFICATION.targetVar` is a **read** — it names the
+fact holding the recipient (`phone_number`, `email`, `device_token`), and the action throws if that
+fact is absent from the request. `ADD_TAG.targetVar` is a **write** — the list is created if absent,
+and adding a tag that is already present is a no-op.
 
 ### Action Example: 10% Discount via MUTATE_FACT
 
@@ -305,4 +346,5 @@ Before creating rules, always:
 1. **Check available facts:** `lexq facts list`
 2. **Confirm the version is DRAFT:** `lexq versions get --group-id <gid> --id <vid>` → status must be `DRAFT`
 3. **Use exact fact keys** from the fact definitions (snake_case, case-sensitive)
-4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+5. **Match the operator to the fact type** — list-typed facts accept only `HAS_ANY` / `HAS_ALL` / `HAS_NONE`

package/skills/lexq-simulation/SKILL.md

@@ -111,7 +111,7 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
         "ruleId": "...",
         "ruleName": "VIP 10% Discount",
         "matched": true,
-        "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
+        "matchExpression": "(customer_tier == 'VIP') && (payment_amount >= 100000)",
         "generatedActions": [
           {
             "type": "MUTATE_FACT",
@@ -143,26 +143,46 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
 
 ### Reading Decision Traces
 
-| Status          | Meaning                                     |
-|-----------------|---------------------------------------------|
-| `SELECTED`      | Rule matched and its actions fired          |
-| `NO_MATCH`      | Condition did not match the input           |
-| `NOT_SELECTED`  | Matched but excluded by conflict resolution |
-| `BLOCKED_MUTEX` | Blocked by mutex group constraint           |
-| `LOST_PRIORITY` | Lost to a higher-priority rule              |
-| `DROPPED_LIMIT` | Execution limit reached                     |
-| `ERROR`         | Rule evaluation failed                      |
+Each trace carries a `status` (what happened) and a `reasonCode` (why).
+
+| Status         | Meaning                                            |
+|----------------|----------------------------------------------------|
+| `SELECTED`     | Rule matched and its actions fired                 |
+| `NO_MATCH`     | Condition did not match, or could not be evaluated |
+| `NOT_SELECTED` | Matched but excluded by conflict resolution        |
+| `BLOCKED`      | Blocked by a mutex group or group activation limit |
+| `ERROR`        | Action execution failed                            |
 
 ### Reading Reason Codes
 
-| Code                  | Meaning                                                  |
-|-----------------------|----------------------------------------------------------|
-| `FINAL_WINNER`        | Successfully executed                                    |
-| `CONDITION_MISMATCH`  | Input facts didn't satisfy the condition                 |
-| `MUTEX_PRIORITY_LOST` | Another rule in the same mutex group had higher priority |
-| `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired                    |
-| `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached                         |
-| `ACTION_ERROR`        | Action execution failed (e.g., webhook timeout)          |
+| Code                     | Meaning                                                  |
+|--------------------------|----------------------------------------------------------|
+| `FINAL_WINNER`           | Successfully executed                                    |
+| `CONDITION_MISMATCH`     | Condition not satisfied, or could not be evaluated       |
+| `EFFECTIVE_DATE_INVALID` | Outside the version's effective date range               |
+| `MUTEX_PRIORITY_LOST`    | Another rule in the same mutex group had higher priority |
+| `MUTEX_LIMIT_REACHED`    | Mutex group's max rules already fired                    |
+| `GROUP_PRIORITY_LOST`    | Another group in the same activation group won           |
+| `GROUP_LIMIT_REACHED`    | Group's `executionLimit` reached                         |
+| `ACTION_ERROR`           | Action execution failed (e.g., webhook timeout)          |
+| `ENGINE_ERROR`           | Internal engine failure                                  |
+
+#### `reasonDetail` on unevaluable conditions
+
+`CONDITION_MISMATCH` covers two different things, distinguished by `reasonDetail`:
+
+- **empty** — the condition was evaluated and did not match
+- **`Evaluation error: <code>`** — the condition could not be evaluated at all
+
+| Code                    | Meaning                                                            |
+|-------------------------|--------------------------------------------------------------------|
+| `FACT_NOT_PROVIDED`     | The rule references a fact absent from the request                 |
+| `FACT_TYPE_MISMATCH`    | The fact's runtime type does not match the condition               |
+| `UNSUPPORTED_FACT_TYPE` | Operator not valid for the fact's type (e.g. `CONTAINS` on a list) |
+| `MALFORMED_RULE`        | The stored rule is structurally invalid                            |
+
+A rule from another group referencing facts you did not send yields `FACT_NOT_PROVIDED` — this
+is normal, not an error.
 
 ## 3. Dry Run Compare