@lexq/cli 1.0.0 → 1.0.2

package/dist/index.js

@@ -269,7 +269,7 @@ function registerAuthCommands(program) {
 
         Example:
           $ lexq auth whoami
-          { "tenantId": "abc-123", "userId": "...", "role": "ADMIN", "apiKey": "lexq_us_****abcd" }
+          { "tenantId": "abc-123", "userId": "...", "role": "ADMIN", "tenantTimezone": "Asia/Seoul", "apiKey": "lexq_us_****abcd" }
       `
   ).action(async () => {
     try {
@@ -310,9 +310,10 @@ function registerStatusCommand(program) {
 
         Example:
           $ lexq status
-          { "status": "ok", "latencyMs": 142, "tenantId": "abc-123", "role": "ADMIN" }
+          { "status": "ok", "latencyMs": 142, "tenantId": "abc-123", "role": "ADMIN", "tenantTimezone": "Asia/Seoul" }
 
         Use this to verify your API key is valid and the LexQ API is reachable.
+        tenantTimezone is the zone every yyyy-MM-dd date option is read in.
       `
   ).action(async () => {
     const globalOpts = program.opts();
@@ -326,7 +327,8 @@ function registerStatusCommand(program) {
         status: "ok",
         latencyMs: Date.now() - startTime,
         tenantId: info.tenantId,
-        role: info.role
+        role: info.role,
+        tenantTimezone: info.tenantTimezone
       });
     } catch (error) {
       printError(error);
@@ -347,10 +349,32 @@ var SLOW_MULTIPLIER = 10;
 var MIN_SAMPLES = 100;
 var MIN_COHORT_SIZE = 3;
 var PROFILE_DEFAULT_WINDOW_HOURS = 24;
+var MAX_GROUPS_PER_TENANT = 20;
+var MAX_DRAFT_VERSIONS_PER_GROUP = 20;
+var MAX_RULES_PER_VERSION = 100;
+var MAX_CONDITIONS_PER_RULE = 25;
+var MAX_CONDITION_DEPTH = 10;
+var MAX_SNAPSHOT_BYTES = 131072;
 
 // src/commands/groups.ts
 import "commander";
 import dedent3 from "dedent";
+
+// src/lib/dates.ts
+var ORG_DAY = "yyyy-MM-dd, a whole calendar day in the organization time zone (tenantTimezone in whoami), not UTC";
+var START_DAY = `Start date, ${ORG_DAY}. Inclusive.`;
+var END_DAY = `End date, ${ORG_DAY}. Inclusive: the whole day counts.`;
+var WINDOW_START_DAY = `Window start date, ${ORG_DAY}. Inclusive.`;
+var WINDOW_END_DAY = `Window end date, ${ORG_DAY}. Inclusive: the whole day counts.`;
+var INSTANT = "ISO-8601 instant with Z or an offset, e.g. 2026-10-01T00:00:00Z or 2026-10-01T09:00:00+09:00. A bare date or a time without an offset is rejected.";
+var STATS_DEFAULT_WINDOW_DAYS = 30;
+var STATS_MAX_WINDOW_DAYS = 31;
+var FAILURE_LOG_LOOKBACK_DAYS = 7;
+function utcMinute(instant) {
+  return instant ? `${new Date(instant).toISOString().substring(0, 16)}Z` : "\u2013";
+}
+
+// src/commands/groups.ts
 function registerGroupCommands(program) {
   const groups = program.command("groups").description("Manage policy groups").addHelpText(
     "after",
@@ -390,7 +414,7 @@ function registerGroupCommands(program) {
             g.status,
             String(g.priority),
             g.currentVersionName ?? "\u2013",
-            g.updatedAt.substring(0, 10)
+            utcMinute(g.updatedAt)
           ]),
           { truncate: 24 }
         );
@@ -708,7 +732,7 @@ function registerVersionCommands(program) {
             v.status,
             v.commitMessage ?? "\u2013",
             v.snapshotHash ? v.snapshotHash.substring(0, 8) : "\u2013",
-            v.createdAt.substring(0, 10)
+            utcMinute(v.createdAt)
           ]),
           { truncate: 24 }
         );
@@ -741,7 +765,7 @@ ${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)").addHelpText(
+  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 <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent4`
 
@@ -756,8 +780,8 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
         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)
+          effectiveFrom    instant     Start of effective period (optional, with Z or an offset)
+          effectiveTo      instant     End of effective period (optional, auto-expires)
       `
   ).action(async (opts) => {
     try {
@@ -780,12 +804,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)").addHelpText(
+  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 <instant>", `Effective start, ${INSTANT}`).option("--effective-to <instant>", `Effective end, ${INSTANT}`).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.
 
+        An omitted --commit-message keeps its value, but --effective-from and --effective-to
+        are replaced together: one you omit is cleared. To keep the effective window, pass
+        both current values (read them with lexq versions get).
+
         Example:
           $ lexq versions update --group-id <gid> --id <vid> --commit-message "Updated rules"
       `
@@ -1736,7 +1764,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: 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_DAY).option("--end-date <date>", END_DAY).option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
     "after",
     dedent7`
 
@@ -1768,7 +1796,7 @@ function registerDeployCommands(program) {
             d.policyGroupName,
             d.versionNo != null ? `v${d.versionNo}` : "\u2013",
             d.deployedByName,
-            d.deployedAt.substring(0, 16)
+            utcMinute(d.deployedAt)
           ]),
           { truncate: 20 }
         );
@@ -1830,7 +1858,7 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
             d.groupName,
             d.groupStatus,
             d.currentVersionName ?? "\u2013",
-            d.lastDeployedAt?.substring(0, 16) ?? "\u2013"
+            utcMinute(d.lastDeployedAt)
           ])
         );
       } else {
@@ -1897,6 +1925,8 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
 
         The version must be ACTIVE with a future effective start date; the system
         deploys it automatically at that time (within one scheduler tick, ≤60s).
+        That time is the version's effectiveFrom, set on the DRAFT before publishing;
+        this command takes no time of its own.
         One pending schedule per group. Manual deploy/rollback/undeploy, starting
         an A/B test, or archiving the group cancels the pending schedule.
 
@@ -1988,9 +2018,9 @@ ${data.totalElements} total \xB7 page ${data.pageNo + 1}/${data.totalPages}`);
             s.status,
             s.policyGroupName ?? s.policyGroupId.substring(0, 8),
             s.versionNo != null ? `v${s.versionNo}` : "\u2013",
-            s.scheduledFor.substring(0, 16),
+            utcMinute(s.scheduledFor),
             s.scheduledByName,
-            s.status === "EXECUTED" ? s.executedAt?.substring(0, 16) ?? "\u2013" : s.status === "CANCELED" ? s.canceledReason ?? "\u2013" : s.status === "FAILED" ? s.failedReason ?? "\u2013" : "\u2013"
+            s.status === "EXECUTED" ? utcMinute(s.executedAt) : s.status === "CANCELED" ? s.canceledReason ?? "\u2013" : s.status === "FAILED" ? s.failedReason ?? "\u2013" : "\u2013"
           ]),
           { truncate: 20 }
         );
@@ -2193,6 +2223,7 @@ function registerAnalyticsCommands(program) {
             
         Dataset types: HISTORICAL, UPLOADED, MANUAL
         Dataset sources: EXECUTION_LOGS, S3_BUCKET, REQUEST_BODY
+        HISTORICAL from / to are yyyy-MM-dd, whole days in the organization time zone, both inclusive.
       `
   ).action(async (opts) => {
     try {
@@ -2309,7 +2340,7 @@ function registerAnalyticsCommands(program) {
       process.exit(1);
     }
   });
-  sim.command("list").description("List simulation history").option("--status <status>", "Filter by status (PENDING, RUNNING, COMPLETED, FAILED, CANCELED)").option("--from <date>", "Start date (yyyy-MM-dd)").option("--to <date>", "End date (yyyy-MM-dd)").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
+  sim.command("list").description("List simulation history").option("--status <status>", "Filter by status (PENDING, RUNNING, COMPLETED, FAILED, CANCELED)").option("--from <date>", START_DAY).option("--to <date>", END_DAY).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";
@@ -2338,7 +2369,7 @@ function registerAnalyticsCommands(program) {
             s.status,
             `${s.matchRate.toFixed(1)}%`,
             String(s.totalRecords),
-            s.createdAt.substring(0, 16)
+            utcMinute(s.createdAt)
           ]),
           { truncate: 20 }
         );
@@ -2659,7 +2690,7 @@ function registerHistoryCommands(program) {
         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(
+  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_DAY).option("--end-date <date>", END_DAY).option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
     "after",
     dedent10`
 
@@ -2699,7 +2730,7 @@ function registerHistoryCommands(program) {
             h.status,
             h.isMatched ? "\u2713" : "\u2717",
             `${h.latencyMs}ms`,
-            h.createdAt.substring(0, 16)
+            utcMinute(h.createdAt)
           ]),
           { truncate: 20 }
         );
@@ -2739,15 +2770,19 @@ ${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)").addHelpText(
+  history.command("stats").description("Get execution statistics").option("--group-id <groupId>", "Filter by policy group").option("--start-date <date>", START_DAY).option("--end-date <date>", END_DAY).addHelpText(
     "after",
     dedent10`
 
         Shows total executions, success/no-match/failure counts, success rate, and avg latency.
 
+        Without dates the window is the last ${STATS_DEFAULT_WINDOW_DAYS} days through today, in the organization
+        time zone. At most ${STATS_MAX_WINDOW_DAYS} days per call; a longer range is rejected with AN-039.
+        --start-date alone runs through today.
+
         Example:
           $ lexq history stats --format table
-          $ lexq history stats --group-id <gid> --start-date 2026-04-01
+          $ lexq history stats --group-id <gid> --start-date 2026-04-01 --end-date 2026-04-30
       `
   ).action(async (opts) => {
     try {
@@ -2834,7 +2869,7 @@ function registerReplayCommands(program) {
       process.exit(1);
     }
   });
-  replay.command("start").description("Submit a window replay job (blast radius)").requiredOption("--version-id <versionId>", "Candidate version to re-evaluate against").requiredOption("--from <date>", "Window start date (yyyy-MM-dd)").requiredOption("--to <date>", "Window end date (yyyy-MM-dd)").option("--max-records <number>", `Sample cap (hard cap ${REPLAY_WINDOW_MAX_RECORDS / 1e3}k)`).addHelpText(
+  replay.command("start").description("Submit a window replay job (blast radius)").requiredOption("--version-id <versionId>", "Candidate version to re-evaluate against").requiredOption("--from <date>", WINDOW_START_DAY).requiredOption("--to <date>", WINDOW_END_DAY).option("--max-records <number>", `Sample cap (hard cap ${REPLAY_WINDOW_MAX_RECORDS / 1e3}k)`).addHelpText(
     "after",
     dedent11`
 
@@ -2878,7 +2913,7 @@ function registerReplayCommands(program) {
       });
       if (format === "table") {
         printTable(
-          ["Job", "Version", "Window", "Status", "Progress", "Changed", "At"],
+          ["Job", "Version", "Window (org time zone)", "Status", "Progress", "Changed", "At"],
           data.content.map((j) => [
             j.jobId.substring(0, 12),
             j.candidateVersionName ?? "\u2013",
@@ -2886,7 +2921,7 @@ function registerReplayCommands(program) {
             j.status,
             `${j.progress}%`,
             `${j.changedCount}${j.capped ? " (capped)" : ""}`,
-            j.createdAt.substring(0, 16)
+            utcMinute(j.createdAt)
           ]),
           { truncate: 24 }
         );
@@ -2992,7 +3027,7 @@ function registerProvenanceCommands(program) {
       process.exit(1);
     }
   });
-  provenance.command("reveal-audits").description("List PII reveal audits (who revealed what, when)").option("--trace-id <traceId>", "Filter by trace ID (exact)").option("--fact-key <factKey>", "Filter by fact key (partial, case-insensitive)").option("--revealed-by <operatorId>", "Filter by operator ID (exact)").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(
+  provenance.command("reveal-audits").description("List PII reveal audits (who revealed what, when)").option("--trace-id <traceId>", "Filter by trace ID (exact)").option("--fact-key <factKey>", "Filter by fact key (partial, case-insensitive)").option("--revealed-by <operatorId>", "Filter by operator ID (exact)").option("--start-date <date>", START_DAY).option("--end-date <date>", END_DAY).option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
     "after",
     dedent12`
 
@@ -3026,7 +3061,7 @@ function registerProvenanceCommands(program) {
         printTable(
           ["Revealed At", "By", "Fact Key", "Trace"],
           data.content.map((a) => [
-            a.revealedAt.substring(0, 16),
+            utcMinute(a.revealedAt),
             a.revealedByName,
             a.factKey,
             a.traceId.substring(0, 12)
@@ -3064,10 +3099,13 @@ function registerLogCommands(program) {
         Statuses: PENDING (needs attention), RESOLVED, IGNORED
       `
   );
-  logs.command("list").description("List failure logs").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(
+  logs.command("list").description("List failure logs").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_DAY).option("--end-date <date>", END_DAY).option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").addHelpText(
     "after",
     dedent13`
 
+        Without dates the window is ${FAILURE_LOG_LOOKBACK_DAYS} days back through today, in the organization
+        time zone. Pass --start-date to look further back.
+
         Examples:
           $ lexq logs list --status PENDING --format table
           $ lexq logs list --task-type PLATFORM_WEBHOOK
@@ -3098,7 +3136,7 @@ function registerLogCommands(program) {
             l.taskType,
             l.status,
             l.errorMessage?.substring(0, 24) ?? "\u2013",
-            l.createdAt.substring(0, 16)
+            utcMinute(l.createdAt)
           ]),
           { truncate: 24 }
         );
@@ -3496,7 +3534,7 @@ function registerStatusTools(server, callApi) {
     {
       title: "Who Am I",
       annotations: { readOnlyHint: true },
-      description: "Show current authentication info (tenant ID, user ID, role).",
+      description: 'Show current authentication info (tenant ID, user ID, role) and tenantTimezone, the organization time zone that every yyyy-MM-dd date filter uses. Work out "today" or "yesterday" in that zone, not in UTC.',
       inputSchema: z.object({})
     },
     async () => callApi("GET", "whoami")
@@ -3533,7 +3571,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "Create Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Create a new policy group. Requires name. Priority is auto-assigned (appended last, tenant-wide); use lexq_groups_reorder to change order. Optionally set conflict resolution, activation group, and description. Policy groups that share an activationGroup form a cluster and must share the same activationMode / activationStrategy / executionLimit; executionLimit is how many of those groups run, not how many rules.",
+      description: `Create a new policy group. Requires name. Priority is auto-assigned (appended last, tenant-wide); use lexq_groups_reorder to change order. Optionally set conflict resolution, activation group, and description. Policy groups that share an activationGroup form a cluster and must share the same activationMode / activationStrategy / executionLimit; executionLimit is how many of those groups run, not how many rules. A tenant can have at most ${MAX_GROUPS_PER_TENANT} groups that are not ARCHIVED; archive groups you no longer use to free a slot.`,
       inputSchema: z2.object({
         name: z2.string().describe("Group name (unique among non-ARCHIVED)"),
         description: z2.string().optional().describe("Group description"),
@@ -3690,12 +3728,12 @@ function registerVersionTools(server, callApi) {
     {
       title: "Create Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range.",
+      description: `Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range. A group can hold at most ${MAX_DRAFT_VERSIONS_PER_GROUP} DRAFT versions at a time; published versions do not count. Publish or delete drafts to make room.`,
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         commitMessage: z3.string().optional().describe("Commit message describing this version"),
-        effectiveFrom: z3.string().optional().describe("Effective start date (ISO 8601)"),
-        effectiveTo: z3.string().optional().describe("Effective end date (ISO 8601)")
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT}`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT}`)
       })
     },
     async ({ groupId, ...body }) => callApi("POST", `policy-groups/${groupId}/versions`, { body })
@@ -3705,13 +3743,13 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. Only provided fields are changed.",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe("New effective start date"),
-        effectiveTo: z3.string().optional().describe("New effective end date")
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -3734,7 +3772,7 @@ function registerVersionTools(server, callApi) {
     {
       title: "Clone Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Clone an existing version to create a new DRAFT. Useful when the source version is already published.",
+      description: `Clone an existing version to create a new DRAFT. Useful when the source version is already published. The new DRAFT counts toward the limit of ${MAX_DRAFT_VERSIONS_PER_GROUP} DRAFT versions per group, and a source with more than ${MAX_RULES_PER_VERSION} rules cannot be cloned.`,
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Source version ID to clone")
@@ -3797,7 +3835,9 @@ function registerRuleTools(server, callApi) {
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
         Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
-        
+        Limits: a condition tree may hold at most ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes; GROUP nodes do not count)
+        and nest at most ${MAX_CONDITION_DEPTH} levels below the root. A version holds at most ${MAX_RULES_PER_VERSION} rules.
+
         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
@@ -3863,7 +3903,7 @@ function registerRuleTools(server, callApi) {
     {
       title: "Update Rule",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update an existing rule in a DRAFT version. Only provided fields are changed.",
+      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root.`,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
         versionId: z4.string().uuid().describe("Version ID"),
@@ -4085,7 +4125,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them.",
+      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -4145,7 +4185,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Schedule Deployment",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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).",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("ACTIVE version ID with a future effective start date"),
@@ -4192,8 +4232,8 @@ function registerDeployTools(server, callApi) {
         size: z6.number().int().min(1).max(100).default(20).describe("Page size"),
         groupId: z6.string().uuid().optional().describe("Filter by group ID"),
         types: z6.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
-        startDate: z6.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z6.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z6.string().optional().describe(START_DAY),
+        endDate: z6.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, groupId, types, startDate, endDate }) => {
@@ -4337,7 +4377,8 @@ function registerAnalyticsTools(server, callApi) {
         Start an Impact Simulation against historical, uploaded, or inline data.
 
         dataset.type and dataset.source are BOTH required, and must be paired:
-          HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd)
+          HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd, whole days
+                       in the organization time zone, both inclusive)
           UPLOADED   → source S3_BUCKET,      with dataset.path (the path returned by lexq_dataset_upload)
           MANUAL     → source REQUEST_BODY,   with dataset.manualData (array of fact records)
 
@@ -4392,8 +4433,8 @@ function registerAnalyticsTools(server, callApi) {
         page: z7.number().int().min(0).default(0).describe("Page number"),
         size: z7.number().int().min(1).max(100).default(20).describe("Page size"),
         status: z7.enum(["PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELED"]).optional().describe("Filter by status"),
-        from: z7.string().optional().describe("Start date (yyyy-MM-dd)"),
-        to: z7.string().optional().describe("End date (yyyy-MM-dd)")
+        from: z7.string().optional().describe(START_DAY),
+        to: z7.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, status, from, to }) => {
@@ -4571,8 +4612,8 @@ function registerReplayTools(server, callApi) {
       description: "Submit an async job that replays a date window of past executions against a candidate version and measures the blast radius (how many decisions change). Billed per replayed record (REPLAY metric); VIEWER role cannot submit. Poll with lexq_replay_status.",
       inputSchema: z9.object({
         candidateVersionId: z9.string().uuid().describe("Version to re-evaluate against"),
-        from: z9.string().describe("Window start date (yyyy-MM-dd)"),
-        to: z9.string().describe("Window end date (yyyy-MM-dd)"),
+        from: z9.string().describe(WINDOW_START_DAY),
+        to: z9.string().describe(WINDOW_END_DAY),
         maxRecords: z9.number().int().min(1).optional().describe(
           `Sample cap (server default applies; hard cap ${REPLAY_WINDOW_MAX_RECORDS / 1e3}k)`
         )
@@ -4648,8 +4689,8 @@ function registerHistoryTools(server, callApi) {
         groupId: z10.string().uuid().optional().describe("Filter by policy group"),
         versionId: z10.string().uuid().optional().describe("Filter by version"),
         status: z10.enum(["SUCCESS", "NO_MATCH", "ERROR", "TIMEOUT"]).optional().describe("Filter by execution status"),
-        startDate: z10.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z10.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z10.string().optional().describe(START_DAY),
+        endDate: z10.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, traceId, groupId, versionId, status, startDate, endDate }) => {
@@ -4680,11 +4721,11 @@ function registerHistoryTools(server, callApi) {
     {
       title: "Execution Statistics",
       annotations: { readOnlyHint: true },
-      description: "Get execution KPIs: total executions, success/failure counts, success rate, and average latency.",
+      description: `Get execution KPIs: total executions, success/failure counts, success rate, and average latency. Without dates the window is the last ${STATS_DEFAULT_WINDOW_DAYS} days through today, in the organization time zone. At most ${STATS_MAX_WINDOW_DAYS} days per call; a longer range is rejected with AN-039. startDate alone runs through today.`,
       inputSchema: z10.object({
         groupId: z10.string().uuid().optional().describe("Filter by policy group"),
-        startDate: z10.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z10.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z10.string().optional().describe(START_DAY),
+        endDate: z10.string().optional().describe(END_DAY)
       })
     },
     async ({ groupId, startDate, endDate }) => {
@@ -4724,8 +4765,8 @@ function registerProvenanceTools(server, callApi) {
         traceId: z11.string().optional().describe("Filter by trace ID (exact match)"),
         revealedBy: z11.string().optional().describe("Filter by operator ID (exact match)"),
         factKey: z11.string().optional().describe("Filter by fact key (partial match, case-insensitive)"),
-        startDate: z11.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z11.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z11.string().optional().describe(START_DAY),
+        endDate: z11.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, traceId, revealedBy, factKey, startDate, endDate }) => {
@@ -4748,15 +4789,15 @@ function registerLogTools(server, callApi) {
     {
       title: "List Failure Logs",
       annotations: { readOnlyHint: true },
-      description: "List system failure logs from background tasks (platform event webhooks, scheduled deployments).",
+      description: `List system failure logs from background tasks (platform event webhooks, scheduled deployments). Without dates the window is ${FAILURE_LOG_LOOKBACK_DAYS} days back through today, in the organization time zone; pass startDate to look further back.`,
       inputSchema: z12.object({
         page: z12.number().int().min(0).default(0).describe("Page number"),
         size: z12.number().int().min(1).max(100).default(20).describe("Page size"),
         taskType: z12.enum(TaskType).optional().describe("Task type"),
         status: z12.enum(FailureStatus).optional().describe("Log status"),
         keyword: z12.string().optional().describe("Search in refId, refSubId, errorMessage"),
-        startDate: z12.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z12.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z12.string().optional().describe(START_DAY),
+        endDate: z12.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, taskType, status, keyword, startDate, endDate }) => {

package/dist/mcp/register.js

@@ -6,7 +6,7 @@ function registerStatusTools(server, callApi) {
     {
       title: "Who Am I",
       annotations: { readOnlyHint: true },
-      description: "Show current authentication info (tenant ID, user ID, role).",
+      description: 'Show current authentication info (tenant ID, user ID, role) and tenantTimezone, the organization time zone that every yyyy-MM-dd date filter uses. Work out "today" or "yesterday" in that zone, not in UTC.',
       inputSchema: z.object({})
     },
     async () => callApi("GET", "whoami")
@@ -34,6 +34,23 @@ var PlatformEventType = [
 ];
 var WebhookPayloadFormat = ["GENERIC", "SLACK"];
 
+// src/types/constants.ts
+var MAX_ROUNDING_SCALE = 34;
+var REPLAY_WINDOW_MAX_RECORDS = 5e4;
+var PROFILE_SAMPLE_PERMILLE = 10;
+var LATENCY_WINDOW_MILLIS = 6e4;
+var TAIL_MIN_OBS = 3;
+var SLOW_MULTIPLIER = 10;
+var MIN_SAMPLES = 100;
+var MIN_COHORT_SIZE = 3;
+var PROFILE_DEFAULT_WINDOW_HOURS = 24;
+var MAX_GROUPS_PER_TENANT = 20;
+var MAX_DRAFT_VERSIONS_PER_GROUP = 20;
+var MAX_RULES_PER_VERSION = 100;
+var MAX_CONDITIONS_PER_RULE = 25;
+var MAX_CONDITION_DEPTH = 10;
+var MAX_SNAPSHOT_BYTES = 131072;
+
 // src/mcp/tools/groups.ts
 function registerGroupTools(server, callApi) {
   server.registerTool(
@@ -63,7 +80,7 @@ function registerGroupTools(server, callApi) {
     {
       title: "Create Policy Group",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Create a new policy group. Requires name. Priority is auto-assigned (appended last, tenant-wide); use lexq_groups_reorder to change order. Optionally set conflict resolution, activation group, and description. Policy groups that share an activationGroup form a cluster and must share the same activationMode / activationStrategy / executionLimit; executionLimit is how many of those groups run, not how many rules.",
+      description: `Create a new policy group. Requires name. Priority is auto-assigned (appended last, tenant-wide); use lexq_groups_reorder to change order. Optionally set conflict resolution, activation group, and description. Policy groups that share an activationGroup form a cluster and must share the same activationMode / activationStrategy / executionLimit; executionLimit is how many of those groups run, not how many rules. A tenant can have at most ${MAX_GROUPS_PER_TENANT} groups that are not ARCHIVED; archive groups you no longer use to free a slot.`,
       inputSchema: z2.object({
         name: z2.string().describe("Group name (unique among non-ARCHIVED)"),
         description: z2.string().optional().describe("Group description"),
@@ -242,6 +259,17 @@ function formatUnregisteredFactWarning(meta) {
   ].join("\n");
 }
 
+// src/lib/dates.ts
+var ORG_DAY = "yyyy-MM-dd, a whole calendar day in the organization time zone (tenantTimezone in whoami), not UTC";
+var START_DAY = `Start date, ${ORG_DAY}. Inclusive.`;
+var END_DAY = `End date, ${ORG_DAY}. Inclusive: the whole day counts.`;
+var WINDOW_START_DAY = `Window start date, ${ORG_DAY}. Inclusive.`;
+var WINDOW_END_DAY = `Window end date, ${ORG_DAY}. Inclusive: the whole day counts.`;
+var INSTANT = "ISO-8601 instant with Z or an offset, e.g. 2026-10-01T00:00:00Z or 2026-10-01T09:00:00+09:00. A bare date or a time without an offset is rejected.";
+var STATS_DEFAULT_WINDOW_DAYS = 30;
+var STATS_MAX_WINDOW_DAYS = 31;
+var FAILURE_LOG_LOOKBACK_DAYS = 7;
+
 // src/mcp/tools/versions.ts
 function registerVersionTools(server, callApi) {
   server.registerTool(
@@ -278,12 +306,12 @@ function registerVersionTools(server, callApi) {
     {
       title: "Create Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range.",
+      description: `Create a new DRAFT version in a policy group. Optionally provide a commit message and effective date range. A group can hold at most ${MAX_DRAFT_VERSIONS_PER_GROUP} DRAFT versions at a time; published versions do not count. Publish or delete drafts to make room.`,
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         commitMessage: z3.string().optional().describe("Commit message describing this version"),
-        effectiveFrom: z3.string().optional().describe("Effective start date (ISO 8601)"),
-        effectiveTo: z3.string().optional().describe("Effective end date (ISO 8601)")
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT}`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT}`)
       })
     },
     async ({ groupId, ...body }) => callApi("POST", `policy-groups/${groupId}/versions`, { body })
@@ -293,13 +321,13 @@ function registerVersionTools(server, callApi) {
     {
       title: "Update Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update a DRAFT version. Only DRAFT versions can be modified. Only provided fields are changed.",
+      description: "Update a DRAFT version. Only DRAFT versions can be modified. An omitted commitMessage keeps its value, but effectiveFrom and effectiveTo are replaced together: one you omit is cleared. To keep the effective window, send both current values (read them with lexq_versions_get).",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Version ID"),
         commitMessage: z3.string().optional().describe("New commit message"),
-        effectiveFrom: z3.string().optional().describe("New effective start date"),
-        effectiveTo: z3.string().optional().describe("New effective end date")
+        effectiveFrom: z3.string().optional().describe(`Effective start, ${INSTANT} Omit it and the start is cleared.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it and the end is cleared.`)
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -322,7 +350,7 @@ function registerVersionTools(server, callApi) {
     {
       title: "Clone Policy Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Clone an existing version to create a new DRAFT. Useful when the source version is already published.",
+      description: `Clone an existing version to create a new DRAFT. Useful when the source version is already published. The new DRAFT counts toward the limit of ${MAX_DRAFT_VERSIONS_PER_GROUP} DRAFT versions per group, and a source with more than ${MAX_RULES_PER_VERSION} rules cannot be cloned.`,
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
         versionId: z3.string().uuid().describe("Source version ID to clone")
@@ -336,17 +364,6 @@ function registerVersionTools(server, callApi) {
   );
 }
 
-// src/types/constants.ts
-var MAX_ROUNDING_SCALE = 34;
-var REPLAY_WINDOW_MAX_RECORDS = 5e4;
-var PROFILE_SAMPLE_PERMILLE = 10;
-var LATENCY_WINDOW_MILLIS = 6e4;
-var TAIL_MIN_OBS = 3;
-var SLOW_MULTIPLIER = 10;
-var MIN_SAMPLES = 100;
-var MIN_COHORT_SIZE = 3;
-var PROFILE_DEFAULT_WINDOW_HOURS = 24;
-
 // src/mcp/tools/rules.ts
 import { z as z4 } from "zod";
 import dedent from "dedent";
@@ -396,7 +413,9 @@ function registerRuleTools(server, callApi) {
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
         Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
-        
+        Limits: a condition tree may hold at most ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes; GROUP nodes do not count)
+        and nest at most ${MAX_CONDITION_DEPTH} levels below the root. A version holds at most ${MAX_RULES_PER_VERSION} rules.
+
         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
@@ -462,7 +481,7 @@ function registerRuleTools(server, callApi) {
     {
       title: "Update Rule",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Update an existing rule in a DRAFT version. Only provided fields are changed.",
+      description: `Update an existing rule in a DRAFT version. Only provided fields are changed. A new condition tree must stay within ${MAX_CONDITIONS_PER_RULE} conditions (SINGLE nodes) and ${MAX_CONDITION_DEPTH} levels of nesting below the root.`,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
         versionId: z4.string().uuid().describe("Version ID"),
@@ -688,7 +707,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Publish Version",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them.",
+      description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts referenced by rules do not block publishing (INV-4); call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -748,7 +767,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Schedule Deployment",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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).",
+      description: "Schedule an ACTIVE version with a future effective start date to auto-deploy at that time (Scheduled Deployment). The time is the version's effectiveFrom, set on the DRAFT before publishing; this call takes no time of its own. One pending schedule per group; manual deploy/rollback/undeploy, starting an A/B test, or archiving the group cancels it. The snapshot hash is sealed at scheduling and re-verified at execution (fail-closed).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("ACTIVE version ID with a future effective start date"),
@@ -795,8 +814,8 @@ function registerDeployTools(server, callApi) {
         size: z6.number().int().min(1).max(100).default(20).describe("Page size"),
         groupId: z6.string().uuid().optional().describe("Filter by group ID"),
         types: z6.string().optional().describe("Filter by deployment types (comma-separated: DEPLOY,ROLLBACK,UNDEPLOY)"),
-        startDate: z6.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z6.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z6.string().optional().describe(START_DAY),
+        endDate: z6.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, groupId, types, startDate, endDate }) => {
@@ -940,7 +959,8 @@ function registerAnalyticsTools(server, callApi) {
         Start an Impact Simulation against historical, uploaded, or inline data.
 
         dataset.type and dataset.source are BOTH required, and must be paired:
-          HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd)
+          HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd, whole days
+                       in the organization time zone, both inclusive)
           UPLOADED   → source S3_BUCKET,      with dataset.path (the path returned by lexq_dataset_upload)
           MANUAL     → source REQUEST_BODY,   with dataset.manualData (array of fact records)
 
@@ -995,8 +1015,8 @@ function registerAnalyticsTools(server, callApi) {
         page: z7.number().int().min(0).default(0).describe("Page number"),
         size: z7.number().int().min(1).max(100).default(20).describe("Page size"),
         status: z7.enum(["PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELED"]).optional().describe("Filter by status"),
-        from: z7.string().optional().describe("Start date (yyyy-MM-dd)"),
-        to: z7.string().optional().describe("End date (yyyy-MM-dd)")
+        from: z7.string().optional().describe(START_DAY),
+        to: z7.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, status, from, to }) => {
@@ -1174,8 +1194,8 @@ function registerReplayTools(server, callApi) {
       description: "Submit an async job that replays a date window of past executions against a candidate version and measures the blast radius (how many decisions change). Billed per replayed record (REPLAY metric); VIEWER role cannot submit. Poll with lexq_replay_status.",
       inputSchema: z9.object({
         candidateVersionId: z9.string().uuid().describe("Version to re-evaluate against"),
-        from: z9.string().describe("Window start date (yyyy-MM-dd)"),
-        to: z9.string().describe("Window end date (yyyy-MM-dd)"),
+        from: z9.string().describe(WINDOW_START_DAY),
+        to: z9.string().describe(WINDOW_END_DAY),
         maxRecords: z9.number().int().min(1).optional().describe(
           `Sample cap (server default applies; hard cap ${REPLAY_WINDOW_MAX_RECORDS / 1e3}k)`
         )
@@ -1251,8 +1271,8 @@ function registerHistoryTools(server, callApi) {
         groupId: z10.string().uuid().optional().describe("Filter by policy group"),
         versionId: z10.string().uuid().optional().describe("Filter by version"),
         status: z10.enum(["SUCCESS", "NO_MATCH", "ERROR", "TIMEOUT"]).optional().describe("Filter by execution status"),
-        startDate: z10.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z10.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z10.string().optional().describe(START_DAY),
+        endDate: z10.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, traceId, groupId, versionId, status, startDate, endDate }) => {
@@ -1283,11 +1303,11 @@ function registerHistoryTools(server, callApi) {
     {
       title: "Execution Statistics",
       annotations: { readOnlyHint: true },
-      description: "Get execution KPIs: total executions, success/failure counts, success rate, and average latency.",
+      description: `Get execution KPIs: total executions, success/failure counts, success rate, and average latency. Without dates the window is the last ${STATS_DEFAULT_WINDOW_DAYS} days through today, in the organization time zone. At most ${STATS_MAX_WINDOW_DAYS} days per call; a longer range is rejected with AN-039. startDate alone runs through today.`,
       inputSchema: z10.object({
         groupId: z10.string().uuid().optional().describe("Filter by policy group"),
-        startDate: z10.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z10.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z10.string().optional().describe(START_DAY),
+        endDate: z10.string().optional().describe(END_DAY)
       })
     },
     async ({ groupId, startDate, endDate }) => {
@@ -1327,8 +1347,8 @@ function registerProvenanceTools(server, callApi) {
         traceId: z11.string().optional().describe("Filter by trace ID (exact match)"),
         revealedBy: z11.string().optional().describe("Filter by operator ID (exact match)"),
         factKey: z11.string().optional().describe("Filter by fact key (partial match, case-insensitive)"),
-        startDate: z11.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z11.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z11.string().optional().describe(START_DAY),
+        endDate: z11.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, traceId, revealedBy, factKey, startDate, endDate }) => {
@@ -1351,15 +1371,15 @@ function registerLogTools(server, callApi) {
     {
       title: "List Failure Logs",
       annotations: { readOnlyHint: true },
-      description: "List system failure logs from background tasks (platform event webhooks, scheduled deployments).",
+      description: `List system failure logs from background tasks (platform event webhooks, scheduled deployments). Without dates the window is ${FAILURE_LOG_LOOKBACK_DAYS} days back through today, in the organization time zone; pass startDate to look further back.`,
       inputSchema: z12.object({
         page: z12.number().int().min(0).default(0).describe("Page number"),
         size: z12.number().int().min(1).max(100).default(20).describe("Page size"),
         taskType: z12.enum(TaskType).optional().describe("Task type"),
         status: z12.enum(FailureStatus).optional().describe("Log status"),
         keyword: z12.string().optional().describe("Search in refId, refSubId, errorMessage"),
-        startDate: z12.string().optional().describe("Start date (yyyy-MM-dd)"),
-        endDate: z12.string().optional().describe("End date (yyyy-MM-dd)")
+        startDate: z12.string().optional().describe(START_DAY),
+        endDate: z12.string().optional().describe(END_DAY)
       })
     },
     async ({ page, size, taskType, status, keyword, startDate, endDate }) => {

package/package.json

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

package/skills/lexq-execution/SKILL.md

@@ -23,8 +23,11 @@ Filter options:
 | `--group-id <id>`     | Filter by policy group | `--group-id <gid>`        |
 | `--version-id <id>`   | Filter by version      | `--version-id <vid>`      |
 | `--status <status>`   | Filter by status       | `--status SUCCESS`        |
-| `--start-date <date>` | Start date (ISO)       | `--start-date 2025-01-01` |
-| `--end-date <date>`   | End date (ISO)         | `--end-date 2025-01-31`   |
+| `--start-date <date>` | First day, inclusive   | `--start-date 2025-01-01` |
+| `--end-date <date>`   | Last day, inclusive    | `--end-date 2025-01-31`   |
+
+Dates are `yyyy-MM-dd`, whole days in the organization time zone (`tenantTimezone` in
+`lexq auth whoami`), not UTC.
 
 ### Execution Statuses
 
@@ -53,6 +56,10 @@ Returns full detail including `inputFacts`, `executionTraces`, and `decisionTrac
 lexq history stats
 ```
 
+Without dates the window is the last 30 days through today, in the organization time zone. At most
+31 days per call; a longer range is rejected with `AN-039`. `--start-date` alone runs through
+today.
+
 Returns KPI summary:
 
 ```json
@@ -98,8 +105,12 @@ Filter options:
 | `--task-type <type>`  | Task type                               | `PLATFORM_WEBHOOK`, `SCHEDULED_DEPLOYMENT` |
 | `--status <status>`   | Log status                              | `PENDING`, `RESOLVED`, `IGNORED`           |
 | `--keyword <kw>`      | Search in refId, refSubId, errorMessage | any string                                 |
-| `--start-date <date>` | Start date (ISO)                        | `2025-01-01`                               |
-| `--end-date <date>`   | End date (ISO)                          | `2025-01-31`                               |
+| `--start-date <date>` | First day, inclusive                    | `2025-01-01`                               |
+| `--end-date <date>`   | Last day, inclusive                     | `2025-01-31`                               |
+
+Without dates the list covers 7 days back through today, in the organization time zone. A failure
+older than that is left out even while it is still `PENDING`. Pass an earlier `--start-date` to
+see it.
 
 ### Get Failure Log Detail
 
@@ -247,7 +258,7 @@ lexq profile <groupId> --version <vid> --cache MISS \
 ```
 
 `--from` / `--to` are ISO-8601 **instants** here (`2026-07-01T00:00:00Z`), unlike `replay start`
-which takes `yyyy-MM-dd` dates.
+which takes `yyyy-MM-dd` days in the organization time zone.
 
 `p50` / `p95` / `p99` are `null` when the sample is under 100 — the engine reports insufficient
 data rather than inventing a number. `n` is always present.
@@ -264,7 +275,7 @@ lexq history list --status ERROR --page 0 --size 10
 # 3. For a specific bad decision, get the deterministic why
 lexq provenance get --trace-id <traceId>
 
-# 4. Check for system failures
+# 4. Check for system failures (covers 7 days back by default; add --start-date for older ones)
 lexq logs list --status PENDING --page 0 --size 10
 
 # 5. Inspect and mark

package/skills/lexq-recipes/SKILL.md

@@ -390,6 +390,10 @@ lexq logs bulk-action --ids "id4,id5" --action IGNORE
 lexq logs list --status PENDING --page 0 --size 10
 ```
 
+Without `--start-date`, `logs list` covers 7 days back through today, in the organization time
+zone. An empty list in step 5 means there is no PENDING failure in that window, not that there is
+none at all. Add an earlier `--start-date` to steps 1 and 5 to see older ones.
+
 `RESOLVE` and `IGNORE` differ only in intent — both remove the log from PENDING. Use `RESOLVE`
 when the underlying problem was fixed, `IGNORE` when it does not need fixing.
 

package/skills/lexq-shared/SKILL.md

@@ -153,7 +153,12 @@ Prefixes you will encounter through the CLI:
 1. **Fact keys start with a letter,** then letters, numbers, and underscores. Casing is yours to
    choose and keys are case-sensitive. These docs use `camelCase`: `paymentAmount`, `customerTier`.
 2. **IDs are UUIDs.** Always copy the full ID from list/create output — do not guess.
-3. **Dates use ISO 8601.** Example: `2025-01-01T00:00:00Z`. Time zone is UTC.
+3. **Dates come in two shapes.** A date filter (`--start-date`, `--end-date`, `--from` / `--to` on
+   `replay start` and `simulation list`) takes `yyyy-MM-dd` and means a whole calendar day in the
+   organization time zone, not UTC. `lexq auth whoami` shows that zone as `tenantTimezone`. An
+   instant (`--effective-from`, `--effective-to`, `--from` / `--to` on `profile`) takes ISO 8601
+   with `Z` or an offset: `2026-10-01T00:00:00Z` or `2026-10-01T09:00:00+09:00`. Tables print
+   times in UTC with a trailing `Z`.
 4. **JSON bodies via `--json`.** Most create/update commands accept `--json '<body>'` for the request body.
 5. **File input via `--file`.** `analytics dry-run`, `dry-run-compare`, `simulation start` accept
    `--file path/to/body.json` as an alternative to `--json`. `analytics dataset upload` requires

package/skills/lexq-simulation/SKILL.md

@@ -251,6 +251,9 @@ lexq analytics simulation start --json '{
 | `MANUAL`     | `REQUEST_BODY`   | Provide `manualData` array in the request |
 | `UPLOADED`   | `S3_BUCKET`      | Reference an uploaded dataset by `path`   |
 
+`HISTORICAL` takes `from` / `to` as `yyyy-MM-dd`, whole days in the organization time zone, both
+inclusive.
+
 ### File Upload Dataset
 
 ```bash