@lexq/cli 1.0.1 → 1.1.0

package/AGENTS.md

@@ -180,8 +180,12 @@ The MCP toolset mirrors the CLI command inventory one-to-one.
 - Releasing is two steps, in this order. Raise `version` in package.json inside the pull request, so a reviewer
   sees the number beside the change that justifies it. After it merges, push the matching `v<version>` tag — that
   tag is what publishes. A tag that disagrees with package.json is rejected before anything reaches npm.
-- Pick the number by what breaks. On 0.x a breaking change is a minor bump (0.1 → 0.2), not a patch. Raising the
-  Node floor, a peer dependency major, or any change to what `tools/list` returns is breaking.
+- Pick the number by what breaks. A change is breaking when a call that used to work now fails or does something
+  else. That includes removing or renaming a tool, command, option or parameter, changing a parameter's type,
+  adding a required parameter or making an optional one required, and narrowing the values a parameter accepts.
+  Raising the Node floor or moving a peer dependency to a new major version is breaking too. A breaking change
+  raises the major number. A new tool, command, option or optional parameter raises the minor, and anything else,
+  including a changed description, raises the patch.
 - Gates before commit: `pnpm typecheck` (zero errors), `pnpm lint` (zero warnings), `pnpm test:fact-key`,
   `pnpm test:decimals`.
 - Multi-line CLI help and MCP tool descriptions use `dedent` — template-literal indentation leaks into LLM context.

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);
@@ -357,6 +359,22 @@ 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",
@@ -396,7 +414,7 @@ function registerGroupCommands(program) {
             g.status,
             String(g.priority),
             g.currentVersionName ?? "\u2013",
-            g.updatedAt.substring(0, 10)
+            utcMinute(g.updatedAt)
           ]),
           { truncate: 24 }
         );
@@ -714,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 }
         );
@@ -747,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`
 
@@ -762,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 {
@@ -786,14 +804,18 @@ ${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("--clear-effective-from", "Remove the effective start").option("--clear-effective-to", "Remove the effective end").option("--json <body>", "Full request body as JSON (overrides other options)").addHelpText(
     "after",
     dedent4`
 
         Only DRAFT versions can be updated. Published (ACTIVE) versions are immutable.
 
-        Example:
+        Omitted options keep their current values. To remove an end of the effective
+        window, pass --clear-effective-from or --clear-effective-to instead of a value.
+
+        Examples:
           $ lexq versions update --group-id <gid> --id <vid> --commit-message "Updated rules"
+          $ lexq versions update --group-id <gid> --id <vid> --clear-effective-to
       `
   ).action(async (opts) => {
     try {
@@ -889,6 +911,8 @@ function buildUpdateBody(opts) {
   if (opts.commitMessage) body.commitMessage = opts.commitMessage;
   if (opts.effectiveFrom) body.effectiveFrom = opts.effectiveFrom;
   if (opts.effectiveTo) body.effectiveTo = opts.effectiveTo;
+  if (opts.clearEffectiveFrom) body.clearEffectiveFrom = true;
+  if (opts.clearEffectiveTo) body.clearEffectiveTo = true;
   return body;
 }
 
@@ -1620,6 +1644,7 @@ function registerDeployCommands(program) {
 
         Locks the version permanently. Rules cannot be modified after publishing.
         A snapshot hash is generated for integrity verification.
+        A version whose effective end has already passed cannot be published (P-058).
 
         Example:
           $ lexq deploy publish --group-id <gid> --version-id <vid> --memo "Validated via dry-run"
@@ -1650,6 +1675,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Takes effect immediately. The version starts receiving production traffic.
+        A version whose effective start has not arrived (P-037) or whose effective end
+        has passed (P-058) is rejected.
 
         Example:
           $ lexq deploy live --group-id <gid> --version-id <vid> --memo "Go live — v3"
@@ -1676,7 +1703,8 @@ function registerDeployCommands(program) {
     dedent7`
 
         Reverts to the version that was live before the current one.
-        Only available if the previous version is still ACTIVE.
+        Only available if the previous version is still ACTIVE and its effective end
+        has not passed (P-058).
 
         Example:
           $ lexq deploy rollback --group-id <gid> --memo "High error rate" --force
@@ -1742,7 +1770,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`
 
@@ -1774,7 +1802,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 }
         );
@@ -1836,7 +1864,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 {
@@ -1903,6 +1931,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.
 
@@ -1994,9 +2024,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 }
         );
@@ -2177,7 +2207,7 @@ function registerAnalyticsCommands(program) {
         Use --format table for summary view.
       `
   );
-  sim.command("start").description("Start a new batch simulation").requiredOption("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
+  sim.command("start").description("Start a new batch simulation").option("--json <body>", "Simulation request body as JSON").option("--file <path>", "Read request body from a JSON file").addHelpText(
     "after",
     dedent8`
 
@@ -2196,13 +2226,19 @@ function registerAnalyticsCommands(program) {
                 "maxRecords": 1000
               }
             }'
-            
+
+          $ lexq analytics simulation start --file simulation.json
+
         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 {
       const globalOpts = program.opts();
+      if (!opts.json && !opts.file) {
+        throw new Error("Request body is required. Use --json or --file.");
+      }
       const body = resolveBody(opts);
       const data = await apiRequest("POST", "analytics/simulations", {
         apiKey: globalOpts.apiKey,
@@ -2315,7 +2351,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";
@@ -2344,7 +2380,7 @@ function registerAnalyticsCommands(program) {
             s.status,
             `${s.matchRate.toFixed(1)}%`,
             String(s.totalRecords),
-            s.createdAt.substring(0, 16)
+            utcMinute(s.createdAt)
           ]),
           { truncate: 20 }
         );
@@ -2553,7 +2589,7 @@ function registerProfileCommands(program) {
   program.command("profile <groupId>").description("Per-rule latency profile with relative slow-rule flags").option(
     "--rule <ruleId>",
     `Single-rule detail (distributions + ${LATENCY_WINDOW_MILLIS / 1e3}s window series)`
-  ).option("--version <versionId>", "Version to inspect (default: live version)").option(
+  ).option("--version-id <versionId>", "Version to inspect (default: live version)").option(
     "--from <instant>",
     `Window start, ISO-8601 instant (default: ${PROFILE_DEFAULT_WINDOW_HOURS}h ago)`
   ).option("--to <instant>", "Window end, ISO-8601 instant (default: now)").option("--cache <state>", "Cache dimension for the rule table: HIT | MISS (default: HIT)").addHelpText(
@@ -2569,7 +2605,7 @@ function registerProfileCommands(program) {
         Examples:
           $ lexq profile <groupId>
           $ lexq profile <groupId> --cache MISS --from 2026-07-01T00:00:00Z
-          $ lexq profile <groupId> --rule <ruleId> --version <versionId>
+          $ lexq profile <groupId> --rule <ruleId> --version-id <versionId>
       `
   ).action(async (groupId, opts) => {
     try {
@@ -2579,7 +2615,7 @@ function registerProfileCommands(program) {
         throw new Error(`--cache must be one of: ${ProfileCacheState.join(" | ")}`);
       }
       const params = {};
-      if (opts.version) params.versionId = opts.version;
+      if (opts.versionId) params.versionId = opts.versionId;
       if (opts.from) params.from = opts.from;
       if (opts.to) params.to = opts.to;
       if (opts.cache) params.cacheState = opts.cache;
@@ -2665,7 +2701,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`
 
@@ -2705,7 +2741,7 @@ function registerHistoryCommands(program) {
             h.status,
             h.isMatched ? "\u2713" : "\u2717",
             `${h.latencyMs}ms`,
-            h.createdAt.substring(0, 16)
+            utcMinute(h.createdAt)
           ]),
           { truncate: 20 }
         );
@@ -2745,15 +2781,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 {
@@ -2840,7 +2880,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`
 
@@ -2884,7 +2924,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",
@@ -2892,7 +2932,7 @@ function registerReplayCommands(program) {
             j.status,
             `${j.progress}%`,
             `${j.changedCount}${j.capped ? " (capped)" : ""}`,
-            j.createdAt.substring(0, 16)
+            utcMinute(j.createdAt)
           ]),
           { truncate: 24 }
         );
@@ -2998,7 +3038,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`
 
@@ -3032,7 +3072,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)
@@ -3070,10 +3110,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
@@ -3104,7 +3147,7 @@ function registerLogCommands(program) {
             l.taskType,
             l.status,
             l.errorMessage?.substring(0, 24) ?? "\u2013",
-            l.createdAt.substring(0, 16)
+            utcMinute(l.createdAt)
           ]),
           { truncate: 24 }
         );
@@ -3502,7 +3545,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")
@@ -3700,8 +3743,8 @@ function registerVersionTools(server, callApi) {
       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 })
@@ -3711,13 +3754,15 @@ 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. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       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 to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -4060,7 +4105,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy, INV-4). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -4093,7 +4138,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. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -4107,7 +4152,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      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.",
+      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. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -4123,7 +4168,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")
@@ -4153,7 +4198,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"),
@@ -4200,8 +4245,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 }) => {
@@ -4345,7 +4390,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)
 
@@ -4400,8 +4446,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 }) => {
@@ -4579,8 +4625,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)`
         )
@@ -4656,8 +4702,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 }) => {
@@ -4688,11 +4734,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 }) => {
@@ -4732,8 +4778,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 }) => {
@@ -4756,15 +4802,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")
@@ -259,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(
@@ -299,8 +310,8 @@ function registerVersionTools(server, callApi) {
       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 })
@@ -310,13 +321,15 @@ 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. Omitted fields keep their current values. To remove an end of the effective window, set clearEffectiveFrom or clearEffectiveTo to true instead of sending a value.",
       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 to keep the current start.`),
+        effectiveTo: z3.string().optional().describe(`Effective end, ${INSTANT} Omit it to keep the current end.`),
+        clearEffectiveFrom: z3.boolean().optional().describe("Set to true to remove the effective start. Do not send effectiveFrom with it."),
+        clearEffectiveTo: z3.boolean().optional().describe("Set to true to remove the effective end. Do not send effectiveTo with it.")
       })
     },
     async ({ groupId, versionId, ...body }) => callApi("PUT", `policy-groups/${groupId}/versions/${versionId}`, { body })
@@ -663,7 +676,7 @@ function registerFactTools(server, callApi) {
     {
       title: "List Unregistered Facts",
       annotations: { readOnlyHint: true },
-      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy, INV-4). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
+      description: "List facts referenced by a version's rules but not yet defined (read-only \u2014 does not block publish/deploy). Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Register them with lexq_facts_create to enable type validation and the dry-run requirements analyzer.",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -696,7 +709,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. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB.`,
+      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; call lexq_facts_unregistered first to review them. Publishing fails if the version's compiled rules exceed ${MAX_SNAPSHOT_BYTES / 1024} KB, or if its effective end has already passed (P-058); move the end into the future with lexq_versions_update first.`,
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to publish"),
@@ -710,7 +723,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Deploy to Live",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      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.",
+      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. Versions whose effective end has passed are rejected (P-058). Undefined facts do not block deployment; use lexq_facts_unregistered to review what the version references but has not defined.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         versionId: z6.string().uuid().describe("Version ID to deploy"),
@@ -726,7 +739,7 @@ function registerDeployTools(server, callApi) {
     {
       title: "Rollback Deployment",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      description: "Rollback to the previous deployed version. Only available if there is a previous version.",
+      description: "Rollback to the previous deployed version. Only available if there is a previous version that is still ACTIVE and whose effective end has not passed (P-058).",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
         memo: z6.string().min(1).describe("Rollback reason (required)")
@@ -756,7 +769,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"),
@@ -803,8 +816,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 }) => {
@@ -948,7 +961,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)
 
@@ -1003,8 +1017,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 }) => {
@@ -1182,8 +1196,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)`
         )
@@ -1259,8 +1273,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 }) => {
@@ -1291,11 +1305,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 }) => {
@@ -1335,8 +1349,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 }) => {
@@ -1359,15 +1373,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.1",
+  "version": "1.1.0",
   "mcpName": "io.lexq/lexq",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
@@ -41,6 +41,7 @@
     "test:decimals": "pnpm build && node tests/exact-decimals.mjs",
     "test:fact-key": "node tests/fact-key.mjs",
     "test:export-format": "node tests/export-format.mjs",
+    "test:command-options": "node tests/command-options.mjs",
     "test:value-domain": "pnpm build && node tests/value-domain.mjs",
     "prepublishOnly": "pnpm build",
     "knip": "knip",

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
 
@@ -242,12 +253,12 @@ lexq profile <groupId>
 lexq profile <groupId> --rule <ruleId>
 
 # Defaults: live version, last 24h, cache HIT
-lexq profile <groupId> --version <vid> --cache MISS \
+lexq profile <groupId> --version-id <vid> --cache MISS \
   --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z
 ```
 
 `--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