@lexq/cli 2.1.1 → 3.0.0

package/dist/mcp/register.js

@@ -12,6 +12,135 @@ var server_info_default = {
   ]
 };
 
+// src/lib/console.ts
+var CONSOLE_URL = "https://console.lexq.io";
+var FAILURE_LOG_CONSOLE_NOTE = `Logs can be read here but not resolved or ignored. An organization admin does that in the LexQ console: Management \u2192 Failure Logs (${CONSOLE_URL}/management/failure-logs).`;
+
+// src/lib/config.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_DIR = join(homedir(), ".lexq");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+// src/lib/lossless-json.ts
+import {
+  LosslessNumber,
+  isSafeNumber,
+  parse as losslessParse,
+  stringify as losslessStringify
+} from "lossless-json";
+var survivesDoubleRoundTrip = (literal) => isSafeNumber(literal);
+var parseNumber = (value) => survivesDoubleRoundTrip(value) ? parseFloat(value) : new LosslessNumber(value);
+var parseJson = (text) => losslessParse(text, void 0, parseNumber);
+var stringifyJson = (value, space) => losslessStringify(value, void 0, space);
+var isLosslessNumber = (value) => value instanceof LosslessNumber;
+
+// src/lib/api-client.ts
+var ApiError = class extends Error {
+  constructor(statusCode, errorCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.name = "ApiError";
+  }
+  statusCode;
+  errorCode;
+};
+
+// src/lib/value-domain-warning.ts
+function formatValueDomainMismatchWarning(meta) {
+  const mismatch = meta?.valueDomainMismatch;
+  if (!mismatch || !Array.isArray(mismatch.versions) || mismatch.versions.length === 0) return null;
+  const n = mismatch.totalRuleCount;
+  const subject = n === 1 ? "1 rule compares" : `${n} rules compare`;
+  const lines = [
+    `\u26A0 ${subject} ${mismatch.factKey} with values the new value domain does not accept. The update was still saved.`
+  ];
+  for (const version of mismatch.versions) {
+    lines.push(...versionLines(mismatch.factKey, version));
+  }
+  return lines.join("\n");
+}
+function versionLines(factKey, version) {
+  const draft = version.versionStatus === "DRAFT";
+  const lines = [
+    `  ${quoted(version.groupName)} v${version.versionNo}, ${draft ? "draft" : "deployed"} (groupId ${version.groupId}, versionId ${version.versionId})`,
+    draft ? "    Dry runs of this draft already reject calls that send these values (P-052), and live calls will too once it is published and deployed. Saving one of these rules again is refused (P-051) until each listed condition is edited or removed; first check whether each one is still needed." : "    Calls to it are checked against the fact definitions captured when it was published, so this change does not affect them. A version cloned from it carries these rules; fix them in the clone before publishing it."
+  ];
+  for (const rule of version.rules) {
+    const conditions = rule.conditions.map(
+      (c) => `${factKey} ${c.operator} ${escapeUnsafe(stringifyJson(c.value) ?? String(c.value))}`
+    ).join("; ");
+    lines.push(`    \u2022 ${quoted(rule.ruleName)} (ruleId ${rule.ruleId}): ${conditions}`);
+  }
+  const hidden = version.ruleCount - version.rules.length;
+  if (hidden > 0) {
+    lines.push(`    \u2026 and ${hidden} more rule${hidden === 1 ? "" : "s"} in this version.`);
+  }
+  return lines;
+}
+function quoted(name) {
+  return escapeUnsafe(stringifyJson(String(name)) ?? '""');
+}
+var UNSAFE = /[\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+function escapeUnsafe(json) {
+  return json.replace(UNSAFE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+// src/mcp/tools/_shared.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  openWorldHint: false
+};
+var ADDITIVE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: false
+};
+var DESTRUCTIVE = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
+function paginationParams(page, size) {
+  const params = {};
+  if (page !== void 0) params.page = String(page);
+  if (size !== void 0) params.size = String(size);
+  return params;
+}
+var MAX_EXPORT_CHARS = 1e5;
+var formatCount = (count) => count.toLocaleString("en-US");
+var EXPORT_LIMIT_NOTE = `An export longer than ${formatCount(MAX_EXPORT_CHARS)} characters is refused.`;
+function limitExport(result, command, narrower) {
+  if (result.isError) return result;
+  const length = result.content.reduce((sum, block) => sum + block.text.length, 0);
+  if (length <= MAX_EXPORT_CHARS) return result;
+  const text = [
+    `The export is ${formatCount(length)} characters long, and this tool returns at most ${formatCount(MAX_EXPORT_CHARS)}.`,
+    narrower,
+    `To get the whole file, download it from the LexQ console (${CONSOLE_URL}) or with \`${command}\`.`
+  ].filter(Boolean).join(" ");
+  return { content: [{ type: "text", text }], isError: true };
+}
+function formatUnregisteredFactWarning(meta) {
+  const facts = meta?.unregisteredFacts ?? [];
+  if (facts.length === 0) return null;
+  const lines = facts.map((f) => {
+    if (f.inferredType) {
+      return `  \u2022 ${f.key} (${f.inferredType}) \u2014 register: lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: "${f.inferredType}" })`;
+    }
+    const choices = f.candidateTypes?.join(" | ") ?? "STRING | NUMBER | BOOLEAN";
+    return `  \u2022 ${f.key} (ambiguous) \u2014 pick a type (${choices}), then lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: <chosen> })`;
+  });
+  return [
+    `\u26A0 The saved rule references ${facts.length} fact(s) not defined in the schema. The rule was saved, but the engine does not check request values for these keys against a type or value domain, and lexq_requirements lists them with type UNKNOWN.`,
+    ...lines,
+    `Register them before the version is published to have those values checked, or call lexq_facts_unregistered to review the version's full list.`
+  ].join("\n");
+}
+
 // src/mcp/tools/status.ts
 import { z } from "zod";
 function registerStatusTools(server, callApi) {
@@ -19,7 +148,7 @@ function registerStatusTools(server, callApi) {
     "lexq_whoami",
     {
       title: "Who Am I",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       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({})
     },
@@ -54,7 +183,6 @@ var SimulationStatus = ["PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELED"]
 var SimulationMetricType = ["COUNT", "SUM", "AVG"];
 var ExportFormat = ["CSV", "JSON"];
 var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
-var FailureAction = ["IGNORE", "RESOLVE"];
 var TaskType = ["PLATFORM_WEBHOOK", "SCHEDULED_DEPLOYMENT"];
 var PlatformEventType = [
   "VERSION_PUBLISHED",
@@ -98,7 +226,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_list",
     {
       title: "List Policy Groups",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List policy groups (tenant-wide, priority ASC). Deleted groups are not included.",
       inputSchema: z2.object({})
     },
@@ -108,7 +236,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_get",
     {
       title: "Get Policy Group",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get a single policy group by ID. Its currentVersionId and currentDeploymentId are what lexq_deploy_rollback expects, and previousVersionName is the version a rollback restores.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -120,7 +248,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_create",
     {
       title: "Create Policy Group",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       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)"),
@@ -151,7 +279,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_update",
     {
       title: "Update Policy Group",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Update a policy group. Only provided fields are updated; omitted fields remain unchanged. A deleted group cannot be updated (409 P-059).",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
@@ -176,7 +304,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_delete",
     {
       title: "Delete Policy Group",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: `Delete (archive) a policy group. A deployed group cannot be deleted (P-020); undeploy it first with lexq_deploy_undeploy, which also ends a running A/B test. This cannot be undone. The group no longer appears in lexq_groups_list and its name can be reused right away. Calls that change it (settings, versions, rules, starting an A/B test, publish, deploy, rollback, scheduling a deployment) return 409 P-059. If it was ever executed, deployed, or replayed, it is kept for audit; otherwise it is permanently deleted after ${PURGE_AFTER_DAYS} days.`,
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -188,7 +316,7 @@ function registerGroupTools(server, callApi) {
     "lexq_groups_reorder",
     {
       title: "Reorder Policy Groups",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Reorder policy groups by priority. Priority is tenant-wide and flat (1...N continuous); array index 0 = priority 1 (highest precedence). activationGroup is not affected \u2014 this only changes priority.",
       inputSchema: z2.object({
         groupIds: z2.array(z2.string().uuid()).describe("Group IDs in desired priority order (index 0 = priority 1)")
@@ -206,8 +334,8 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_start",
     {
       title: "Start A/B Test",
-      annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate. The challenger must be a published version of the same group; a version from another group is rejected with P-016. The split is computed from context.trafficKey on each execution request; requests that omit it never reach the challenger and the test stays at 0%.",
+      annotations: DESTRUCTIVE,
+      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate. The challenger must be a published version of the same group; a version from another group is rejected with P-016. The split is computed from context.trafficKey on each execution request; requests that omit it never reach the challenger and the test stays at 0%. Starting cancels the group's pending scheduled deployment. Starting while a test is already running replaces its challenger and traffic rate.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
         testVersionId: z2.string().uuid().describe("Challenger version ID. Must be a published version of this group"),
@@ -222,7 +350,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_stop",
     {
       title: "Stop A/B Test",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Stop a running A/B test. All traffic is restored to the control (current) version.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID")
@@ -234,7 +362,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_adjust",
     {
       title: "Adjust A/B Test",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Adjust traffic rate of a running A/B test.",
       inputSchema: z2.object({
         groupId: z2.string().uuid().describe("Policy group ID"),
@@ -250,102 +378,6 @@ function registerGroupTools(server, callApi) {
 // src/mcp/tools/versions.ts
 import { z as z3 } from "zod";
 
-// src/lib/config.ts
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-var CONFIG_DIR = join(homedir(), ".lexq");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
-
-// src/lib/lossless-json.ts
-import {
-  LosslessNumber,
-  isSafeNumber,
-  parse as losslessParse,
-  stringify as losslessStringify
-} from "lossless-json";
-var survivesDoubleRoundTrip = (literal) => isSafeNumber(literal);
-var parseNumber = (value) => survivesDoubleRoundTrip(value) ? parseFloat(value) : new LosslessNumber(value);
-var parseJson = (text) => losslessParse(text, void 0, parseNumber);
-var stringifyJson = (value, space) => losslessStringify(value, void 0, space);
-var isLosslessNumber = (value) => value instanceof LosslessNumber;
-
-// src/lib/api-client.ts
-var ApiError = class extends Error {
-  constructor(statusCode, errorCode, message) {
-    super(message);
-    this.statusCode = statusCode;
-    this.errorCode = errorCode;
-    this.name = "ApiError";
-  }
-  statusCode;
-  errorCode;
-};
-
-// src/lib/value-domain-warning.ts
-function formatValueDomainMismatchWarning(meta) {
-  const mismatch = meta?.valueDomainMismatch;
-  if (!mismatch || !Array.isArray(mismatch.versions) || mismatch.versions.length === 0) return null;
-  const n = mismatch.totalRuleCount;
-  const subject = n === 1 ? "1 rule compares" : `${n} rules compare`;
-  const lines = [
-    `\u26A0 ${subject} ${mismatch.factKey} with values the new value domain does not accept. The update was still saved.`
-  ];
-  for (const version of mismatch.versions) {
-    lines.push(...versionLines(mismatch.factKey, version));
-  }
-  return lines.join("\n");
-}
-function versionLines(factKey, version) {
-  const draft = version.versionStatus === "DRAFT";
-  const lines = [
-    `  ${quoted(version.groupName)} v${version.versionNo}, ${draft ? "draft" : "deployed"} (groupId ${version.groupId}, versionId ${version.versionId})`,
-    draft ? "    Dry runs of this draft already reject calls that send these values (P-052), and live calls will too once it is published and deployed. Saving one of these rules again is refused (P-051) until each listed condition is edited or removed; first check whether each one is still needed." : "    Calls to it are checked against the fact definitions captured when it was published, so this change does not affect them. A version cloned from it carries these rules; fix them in the clone before publishing it."
-  ];
-  for (const rule of version.rules) {
-    const conditions = rule.conditions.map(
-      (c) => `${factKey} ${c.operator} ${escapeUnsafe(stringifyJson(c.value) ?? String(c.value))}`
-    ).join("; ");
-    lines.push(`    \u2022 ${quoted(rule.ruleName)} (ruleId ${rule.ruleId}): ${conditions}`);
-  }
-  const hidden = version.ruleCount - version.rules.length;
-  if (hidden > 0) {
-    lines.push(`    \u2026 and ${hidden} more rule${hidden === 1 ? "" : "s"} in this version.`);
-  }
-  return lines;
-}
-function quoted(name) {
-  return escapeUnsafe(stringifyJson(String(name)) ?? '""');
-}
-var UNSAFE = /[\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
-function escapeUnsafe(json) {
-  return json.replace(UNSAFE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
-}
-
-// src/mcp/tools/_shared.ts
-function paginationParams(page, size) {
-  const params = {};
-  if (page !== void 0) params.page = String(page);
-  if (size !== void 0) params.size = String(size);
-  return params;
-}
-function formatUnregisteredFactWarning(meta) {
-  const facts = meta?.unregisteredFacts ?? [];
-  if (facts.length === 0) return null;
-  const lines = facts.map((f) => {
-    if (f.inferredType) {
-      return `  \u2022 ${f.key} (${f.inferredType}) \u2014 register: lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: "${f.inferredType}" })`;
-    }
-    const choices = f.candidateTypes?.join(" | ") ?? "STRING | NUMBER | BOOLEAN";
-    return `  \u2022 ${f.key} (ambiguous) \u2014 pick a type (${choices}), then lexq_facts_create({ key: "${f.key}", name: "${f.suggestedName}", type: <chosen> })`;
-  });
-  return [
-    `\u26A0 The saved rule references ${facts.length} fact(s) not defined in the schema. The rule was saved \u2014 this does not block \u2014 but undefined facts skip type validation and the dry-run requirements analyzer.`,
-    ...lines,
-    `Register them now so the rule validates as intended, or call lexq_facts_unregistered to review the version's full list.`
-  ].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.`;
@@ -360,7 +392,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_list",
     {
       title: "List Policy Versions",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List all versions of a policy group.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -376,7 +408,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_get",
     {
       title: "Get Policy Version",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get a single version by ID, including its rules and fact requirements.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -389,7 +421,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_create",
     {
       title: "Create Policy Version",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       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"),
@@ -404,7 +436,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_update",
     {
       title: "Update Policy Version",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       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"),
@@ -412,7 +444,9 @@ function registerVersionTools(server, callApi) {
         commitMessage: z3.string().optional().describe("New commit message"),
         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."),
+        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.")
       })
     },
@@ -422,7 +456,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_delete",
     {
       title: "Delete Policy Version",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Delete a DRAFT version. Only DRAFT versions can be deleted.",
       inputSchema: z3.object({
         groupId: z3.string().uuid().describe("Policy group ID"),
@@ -435,7 +469,7 @@ function registerVersionTools(server, callApi) {
     "lexq_versions_clone",
     {
       title: "Clone Policy Version",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       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"),
@@ -459,7 +493,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_list",
     {
       title: "List Rules",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List all rules in a version (priority ASC). Returns summary with conditionSummary and actionSummary.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -472,7 +506,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_get",
     {
       title: "Get Rule Detail",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get full rule detail including condition tree and action definitions.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -486,87 +520,39 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_create",
     {
       title: "Create Rule",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       description: dedent`
-        Create a rule in a DRAFT version. Requires name, condition tree, and actions array. priority is auto-assigned (appended last); use lexq_rules_reorder to change order.
+        Create a rule in a DRAFT version. It goes last in priority order; lexq_rules_reorder changes the order.
 
-        Before creating rules with new fact keys, call lexq_facts_list to check existing facts.
-        If a required key is missing, ask the user to confirm the type, isRequired, and description
-        before calling lexq_facts_create — registering facts enables type validation, Console UI
-        autocomplete, and the dry-run requirements analyzer.
-
-        An action's targetVar (SET_FACT, MUTATE_FACT) must be a registered fact. Saving or
-        publishing a rule whose targetVar is not registered fails with ACT-032, so register it
-        with lexq_facts_create first. Keys a rule only reads (condition fields, refVar) may stay
-        unregistered.
-
-        After saving, lexq_facts_unregistered lists any keys this version references but has not
-        defined (non-blocking, version-wide) — use it to decide what to register.
+        An action's targetVar must be a registered fact (ACT-032 otherwise). Keys a rule only reads (condition fields, refVar) may stay unregistered.
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: ${oneOf(LogicalOperator)}, children: [...] }
         Value types: ${ValueType.join(", ")}
-        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.
+        Limits: ${MAX_CONDITIONS_PER_RULE} SINGLE conditions per rule (GROUP nodes do not count), ${MAX_CONDITION_DEPTH} levels of nesting below the root, ${MAX_RULES_PER_VERSION} rules per version.
 
-        Operators are constrained by the LEFT fact's type (from lexq_facts_list). Using one outside
-        its type is rejected by the server — check the fact type before choosing an operator.
-        - STRING fact:       EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
-        - NUMBER fact:       EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
-        - BOOLEAN fact:      EQUALS, NOT_EQUALS
-        - LIST_* fact:       HAS_ANY, HAS_ALL, HAS_NONE (only these)
-
-        HAS_* query list-typed facts. Value is always an array whose element type matches the fact:
-        - HAS_ANY: fact has at least one of the given values
-        - HAS_ALL: fact has all of the given values
-        - HAS_NONE: fact has none of the given values
+        Operators that work on each fact type:
+        - STRING: EQUALS, NOT_EQUALS, CONTAINS (substring), IN, NOT_IN
+        - NUMBER: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+        - BOOLEAN: EQUALS, NOT_EQUALS
+        - LIST_STRING, LIST_NUMBER: HAS_ANY, HAS_ALL, HAS_NONE
+        IN and NOT_IN test whether the fact's value is in the array. HAS_ANY, HAS_ALL and HAS_NONE match when the fact's list holds at least one, all, or none of the array's values. The array holds values of the fact's type, or for a list fact, of its element type.
         Example: { "type": "SINGLE", "field": "userTags", "operator": "HAS_ANY", "value": ["VIP","GOLD"], "valueType": "LIST_STRING" }
 
-        Do NOT use CONTAINS on a list fact — CONTAINS is substring match on STRING facts only.
-        IN is the mirror of HAS_*: IN takes a scalar fact with a list value; HAS_* takes lists on both sides.
-
         Actions: [{ type, parameters }]
+        - MUTATE_FACT: { targetVar, operator: ${oneOf(MutateOperator)}, method: ${oneOf(CalculationMethod)}, operand: number, refVar?, rounding? }
+          Reads and writes targetVar. The request must send it (P-015 otherwise), and it must hold a number when the action runs. operand may be negative, and a percent may be over 100.
+                    AMOUNT                  PERCENTAGE (base = refVar, or targetVar when omitted)
+            ASSIGN  targetVar = operand     targetVar = base × operand/100
+            ADD     targetVar += operand    targetVar += base × operand/100
+            SUB     targetVar -= operand    targetVar -= base × operand/100
+            MUL     targetVar *= operand    targetVar *= (operand/100 + 1)
+            DIV     targetVar /= operand    invalid
+          refVar is allowed only with PERCENTAGE and ASSIGN, ADD or SUB. DIV with AMOUNT needs a nonzero operand.
+          rounding: { scale: integer (0..${MAX_ROUNDING_SCALE}), mode?: ${oneOf(RoundingPolicy)} }. mode defaults to HALF_UP. Without rounding, the result keeps full precision.
+        - SET_FACT: { targetVar, value: string|number|boolean }. The request does not have to send targetVar.
+        - BLOCK: { reason? } sets isBlocked to true and blockReason to the reason, or "Policy Violation" without one. It does not stop later actions or rules; the caller enforces the block. Only BLOCK writes these two keys: a SET_FACT or MUTATE_FACT targeting either is rejected (ACT-033).
 
-        Action parameter schemas:
-        - MUTATE_FACT: { targetVar: string, operator: ${oneOf(MutateOperator)}, method: ${oneOf(CalculationMethod)}, operand: number, refVar?: string, rounding?: RoundingOption }
-          targetVar is the fact this action reads and writes. It must be a registered fact
-          (ACT-032 otherwise), and the request must send it (P-015 otherwise). Its value must be
-          a number when the action runs.
-          A missing required fact throws (no 0 default).
-          operand is the arithmetic operand; the unit is dictated by method (percent when
-          PERCENTAGE, absolute amount when AMOUNT). Ranges are not constrained — negative values
-          and >100 percentages are valid (refunds, surcharges).
-          refVar is the base for percentage calculation and is OPTIONAL — omit it to use targetVar
-          itself. It is only meaningful in PERCENTAGE × {ASSIGN, ADD, SUB}; specifying it in any
-          other cell is an error. Use it when the base differs from the target, e.g.
-          "points += orderTotal × 5%" → { targetVar: "points", refVar: "orderTotal",
-          operator: "ADD", method: "PERCENTAGE", operand: 5 }.
-          operator × method matrix:
-            ASSIGN  targetVar = operand              | targetVar = refVar × operand/100
-            ADD     targetVar += operand             | targetVar += refVar × operand/100
-            SUB     targetVar -= operand             | targetVar -= refVar × operand/100
-            MUL     targetVar *= operand             | targetVar *= (operand/100 + 1)
-            DIV     targetVar /= operand             | invalid
-          Constraints: DIV + PERCENTAGE is invalid (use MUL with the inverse). DIV + AMOUNT
-          requires operand !== 0.
-        - SET_FACT: { targetVar: string, value: string|number|boolean } targetVar must be a
-          registered fact (ACT-032 otherwise). The request does not have to send it: SET_FACT is
-          the only action whose targetVar may be absent from the input facts. MUTATE_FACT requires
-          its target to be present in the input facts.
-        - BLOCK: { reason?: string } Records a rejection decision. It does NOT halt rule execution —
-          subsequent actions and subsequent winning rules still run. Enforcement is the caller's
-          responsibility; the decision surfaces as isBlocked (true) and blockReason (reason, or
-          "Policy Violation" when omitted).
-          Only BLOCK writes those two keys: saving or publishing a rule whose SET_FACT or
-          MUTATE_FACT targets either one fails with ACT-033.
-
-        Evaluation order: every rule's condition is checked against the input facts before any
-        action runs, so a condition never sees a value an action writes in the same request. Then
-        the actions of the winning rules run in priority order. Each action works on the values
-        the actions before it left, in its own rule or an earlier one. To test a value an action
-        writes, send that value as an input fact in a second request. If a rule should run
-        whenever another one does, put its actions in that rule instead.
-
-        RoundingOption (optional, MUTATE_FACT only): { scale: integer (0..${MAX_ROUNDING_SCALE}), mode?: ${oneOf(RoundingPolicy)} } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
+        Every condition is checked against the input facts before any action runs, so a condition never sees a value an action writes in the same request. The winning rules' actions then run in priority order, each on the values the actions before it left.
       `,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -585,7 +571,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_update",
     {
       title: "Update Rule",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       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. Saving re-checks every action in the rule, including ones you did not change, and fails with ACT-032 if any action's targetVar is not a registered fact.`,
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -607,28 +593,21 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_delete",
     {
       title: "Delete Rule",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Delete a rule from a DRAFT version.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
         versionId: z4.string().uuid().describe("Version ID"),
-        ruleId: z4.string().uuid().describe("Rule ID"),
-        force: z4.boolean().default(false).describe("Skip confirmation (for the last rule in a version)")
+        ruleId: z4.string().uuid().describe("Rule ID")
       })
     },
-    async ({ groupId, versionId, ruleId, force }) => {
-      const params = {};
-      if (force) params.force = "true";
-      return callApi("DELETE", `policy-groups/${groupId}/versions/${versionId}/rules/${ruleId}`, {
-        params
-      });
-    }
+    async ({ groupId, versionId, ruleId }) => callApi("DELETE", `policy-groups/${groupId}/versions/${versionId}/rules/${ruleId}`)
   );
   server.registerTool(
     "lexq_rules_reorder",
     {
       title: "Reorder Rules",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Reorder rules by specifying rule IDs in desired order. Priorities are assigned 1...N (1-based, continuous); array index 0 = priority 1 (highest precedence).",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -650,7 +629,7 @@ function registerRuleTools(server, callApi) {
     "lexq_rules_toggle",
     {
       title: "Toggle Rule",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Enable or disable a rule without deleting it.",
       inputSchema: z4.object({
         groupId: z4.string().uuid().describe("Policy group ID"),
@@ -677,13 +656,14 @@ var EXPORT_FORMATS = ExportFormat.map((name) => name.toLowerCase()).sort();
 
 // src/mcp/tools/facts.ts
 var VALUE_TYPES = ValueType;
+var IS_REQUIRED_NOTE = "isRequired is stored on the definition only; the engine does not read it.";
 function registerFactTools(server, callApi) {
   server.registerTool(
     "lexq_facts_list",
     {
       title: "List Fact Definitions",
-      annotations: { readOnlyHint: true },
-      description: "List all fact definitions (input variable schema). Shows key, type, required, and PII status. Always check this before creating rules.",
+      annotations: READ_ONLY,
+      description: `List all fact definitions (input variable schema): key, name, type, description, PII and system flags, and value domain. ${IS_REQUIRED_NOTE}`,
       inputSchema: z5.object({
         page: z5.number().int().min(0).default(0).describe("Page number"),
         size: z5.number().int().min(1).max(100).default(20).describe("Page size"),
@@ -700,14 +680,14 @@ function registerFactTools(server, callApi) {
     "lexq_facts_create",
     {
       title: "Create Fact Definition",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       description: `Register a new input variable. Key starts with a letter, then letters, numbers, and underscores (e.g. paymentAmount). Casing is not enforced. Types: ${VALUE_TYPES.join(", ")}.`,
       inputSchema: z5.object({
         key: z5.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
         name: z5.string().describe("Display name"),
         type: z5.enum(VALUE_TYPES).describe("Value type"),
         description: z5.string().optional().describe("Description"),
-        isRequired: z5.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
+        isRequired: z5.boolean().default(false).describe(IS_REQUIRED_NOTE),
         isPii: z5.boolean().default(false).describe(
           "Mark as PII \u2014 masked on every read surface, revealable only in the console (audited)"
         ),
@@ -728,7 +708,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Rules in deleted groups do not count. Only the fields you send are changed. System facts (isBlocked, blockReason) accept changes to name, description, PII, and the value domain; isRequired is ignored, and their type cannot change (FD-003).",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID"),
@@ -737,7 +717,7 @@ function registerFactTools(server, callApi) {
         type: z5.enum(VALUE_TYPES).optional().describe(
           "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule outside a deleted group references the fact."
         ),
-        isRequired: z5.boolean().optional().describe("Required flag"),
+        isRequired: z5.boolean().optional().describe(IS_REQUIRED_NOTE),
         isPii: z5.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)"),
         valueDomain: z5.object({
           allowedValues: z5.array(z5.union([z5.string(), z5.number()])).optional().describe(
@@ -756,7 +736,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Rules in deleted groups do not count. Remove the references first.",
       inputSchema: z5.object({
         factId: z5.string().uuid().describe("Fact definition ID")
@@ -768,7 +748,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_action_metadata",
     {
       title: "Get Action Runtime Fact Metadata",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Retrieve runtime fact requirements per Action type. For each Action, shows which input facts must be present in the execution payload \u2014 e.g. MUTATE_FACT always requires its targetVar fact, plus refVar when one is specified. The factRequired flag describes the FACT, not the parameter: refVar is an optional parameter, but if you specify it the named fact must exist. A required fact absent at runtime throws \u2014 the engine never defaults to 0. These facts must be sent in the request (P-015 otherwise), even when an earlier action in the same rule writes them. SET_FACT requires no input fact: it is the only action whose targetVar the request does not have to send, and that targetVar must be a registered fact (ACT-032). Static data, safe to cache in-session.",
       inputSchema: z5.object({})
     },
@@ -778,8 +758,8 @@ function registerFactTools(server, callApi) {
     "lexq_facts_unregistered",
     {
       title: "List Unregistered Facts",
-      annotations: { readOnlyHint: true },
-      description: "List facts referenced by a version's rules but not yet defined (read-only). Keys that rules only read do not block publish/deploy; a rule whose action targetVar is not a registered fact is rejected at save and publish with ACT-032. 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.",
+      annotations: READ_ONLY,
+      description: "List facts referenced by a version's rules but not yet defined (read-only). Keys that rules only read do not block publish/deploy; a rule whose action targetVar is not a registered fact is rejected at save and publish with ACT-032. Version-wide: covers every rule in the version. Each entry carries the inferred type, suggested name, and where it is referenced (condition/action). Registering one with lexq_facts_create before the version is published makes the engine check request values for it against its type (P-060) and any value domain (P-052).",
       inputSchema: z5.object({
         groupId: z5.string().uuid().describe("Policy group ID"),
         versionId: z5.string().uuid().describe("Version ID")
@@ -791,16 +771,20 @@ function registerFactTools(server, callApi) {
     "lexq_facts_export",
     {
       title: "Export Fact Catalog",
-      annotations: { readOnlyHint: true },
-      description: "Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet; JSON matches the shape that batch create accepts, so it can be fed straight back in, which is why it leaves out the fields that endpoint does not take. Returns the file contents as text.",
+      annotations: READ_ONLY,
+      description: `Export the fact catalog. The two formats carry different things: CSV is the catalog as it stands, system facts included, for reading in a spreadsheet, without value domains; JSON lists each definition with only the fields a new definition takes (key, name, type, description, isRequired, isPii, valueDomain), without IDs. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
       inputSchema: z5.object({
         format: z5.enum(EXPORT_FORMATS).default("csv").describe("Export format"),
         keyword: z5.string().optional().describe("Filter by key or name")
       })
     },
-    async ({ format, keyword }) => callApi("GET", "schema/facts/export", {
-      params: keyword ? { format, keyword } : { format }
-    })
+    async ({ format, keyword }) => limitExport(
+      await callApi("GET", "schema/facts/export", {
+        params: keyword ? { format, keyword } : { format }
+      }),
+      `lexq facts export --as ${format} --output <file>`,
+      "Pass keyword to export fewer facts."
+    )
   );
 }
 
@@ -812,7 +796,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_publish",
     {
       title: "Publish Version",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: DESTRUCTIVE,
       description: `Publish a DRAFT version (DRAFT \u2192 ACTIVE). Locks the version from further edits. Must have at least one rule. Undefined facts that rules only read do not block publishing; call lexq_facts_unregistered first to review them. Publishing fails if an action's targetVar is not a registered fact (ACT-032), 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"),
@@ -826,7 +810,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_live",
     {
       title: "Deploy to Live",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       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"),
@@ -842,7 +826,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_rollback",
     {
       title: "Rollback Deployment",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: dedent2`
         Roll the group back to the version that was live before the current one. Call lexq_groups_get first: currentVersionName is live now, previousVersionName is what a rollback restores, and a rollback is rejected while canRollback is false. A rollback needs a previous version that is still ACTIVE and whose effective end has not passed (P-058).
 
@@ -863,7 +847,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_undeploy",
     {
       title: "Undeploy",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Remove the live version from traffic. The version stays ACTIVE but no longer serves requests.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID"),
@@ -878,7 +862,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_schedule",
     {
       title: "Schedule Deployment",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: DESTRUCTIVE,
       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"),
@@ -894,7 +878,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_unschedule",
     {
       title: "Cancel Scheduled Deployment",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Cancel the pending scheduled deployment for a group. The version itself is not affected. Fails with P-039 if no pending schedule exists.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID")
@@ -906,7 +890,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_schedules",
     {
       title: "List Scheduled Deployments",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: `List scheduled deployments across all groups (all statuses: ${DeploymentScheduleStatus.join(", ")}), newest first.`,
       inputSchema: z6.object({
         page: z6.number().int().min(0).default(0).describe("Page number"),
@@ -919,7 +903,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_history",
     {
       title: "Deployment History",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List deployment history across all groups.",
       inputSchema: z6.object({
         page: z6.number().int().min(0).default(0).describe("Page number"),
@@ -943,7 +927,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_detail",
     {
       title: "Deployment Detail",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get detailed info about a specific deployment including snapshot hash and integrity check.",
       inputSchema: z6.object({
         deploymentId: z6.string().uuid().describe("Deployment ID")
@@ -955,7 +939,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_overview",
     {
       title: "Deployment Overview",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Show current deployment status of all groups \u2014 which version is live, last deployment type, and deployer. Each group also carries currentDeploymentId, previousVersionName (the version a rollback restores) and canRollback, as in lexq_groups_get.",
       inputSchema: z6.object({})
     },
@@ -965,7 +949,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_deployable",
     {
       title: "List Deployable Versions",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List ACTIVE (published) versions that can be deployed for a group. Use this to find which versions are available before calling deploy live.",
       inputSchema: z6.object({
         groupId: z6.string().uuid().describe("Policy group ID")
@@ -977,7 +961,7 @@ function registerDeployTools(server, callApi) {
     "lexq_deploy_diff",
     {
       title: "Deployment Diff",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Compare rule snapshots between two versions. Shows added, removed, and modified rules. Useful for reviewing changes before deploying a new version.",
       inputSchema: z6.object({
         baseVersionId: z6.string().uuid().describe("Base version ID (typically the current live)"),
@@ -1005,7 +989,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run",
     {
       title: "Dry Run",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: dedent3`
         Execute a single dry run against a version. Tests how rules evaluate given input facts without side effects.
         
@@ -1016,8 +1000,7 @@ function registerAnalyticsTools(server, callApi) {
           executionTraces   — per-rule match status
           decisionTraces    — per-rule decision (SELECTED / NO_MATCH / BLOCKED / etc.)
         
-        Example input: { "facts": { "paymentAmount": 100000, "customerTier": "VIP" } }
-        Always dry-run before publishing to validate rule behavior.`,
+        Example input: { "facts": { "paymentAmount": 100000, "customerTier": "VIP" } }`,
       inputSchema: z7.object({
         versionId: z7.string().uuid().describe("Policy version ID to test against"),
         facts: z7.string().describe('JSON string of facts object, e.g. {"paymentAmount":100000}'),
@@ -1035,7 +1018,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dry_run_compare",
     {
       title: "Dry Run Compare",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: dedent3`
         Compare dry run results between two versions using the same input facts. Useful for validating changes.
         
@@ -1060,7 +1043,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_requirements",
     {
       title: "Analyze Requirements",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Analyze which input facts a version requires. Returns required keys, types, and an example request body.",
       inputSchema: z7.object({
         groupId: z7.string().uuid().describe("Policy group ID"),
@@ -1073,10 +1056,13 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_start",
     {
       title: "Start Simulation",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: DESTRUCTIVE,
       description: dedent3`
         Start an Impact Simulation against historical, uploaded, or inline data.
 
+        Starting checks the plan's simulation usage limit. The records a simulation processes
+        count toward that usage when it completes or is canceled.
+
         dataset.type and dataset.source are BOTH required, and must be paired:
           HISTORICAL → source EXECUTION_LOGS, with dataset.from / dataset.to (yyyy-MM-dd, whole days
                        in the organization time zone, both inclusive)
@@ -1117,7 +1103,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_status",
     {
       title: "Simulation Status",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get simulation status and results. Poll until status is COMPLETED or FAILED.",
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID")
@@ -1129,7 +1115,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_list",
     {
       title: "List Simulations",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List simulation history with optional filters.",
       inputSchema: z7.object({
         page: z7.number().int().min(0).default(0).describe("Page number"),
@@ -1151,7 +1137,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_cancel",
     {
       title: "Cancel Simulation",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Cancel a running or pending simulation.",
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID")
@@ -1163,22 +1149,25 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_simulation_export",
     {
       title: "Export Simulation",
-      annotations: { readOnlyHint: true },
-      description: "Export simulation results as JSON or CSV. Returns the raw data.",
+      annotations: READ_ONLY,
+      description: `Export simulation results as JSON or CSV. Returns the raw data. ${EXPORT_LIMIT_NOTE}`,
       inputSchema: z7.object({
         simulationId: z7.string().uuid().describe("Simulation ID"),
         format: z7.enum(EXPORT_FORMATS).default("json").describe("Export format")
       })
     },
-    async ({ simulationId, format }) => callApi("GET", `analytics/simulations/${simulationId}/export`, {
-      params: { format }
-    })
+    async ({ simulationId, format }) => limitExport(
+      await callApi("GET", `analytics/simulations/${simulationId}/export`, {
+        params: { format }
+      }),
+      `lexq analytics simulation export --id ${simulationId} --as ${format} --output <file>`
+    )
   );
   server.registerTool(
     "lexq_dataset_upload",
     {
       title: "Upload Dataset",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       description: dedent3`
         Upload inline CSV or JSON content as a simulation dataset.
         The content is uploaded to S3 and a path is returned in the "path" field.
@@ -1221,7 +1210,7 @@ function registerAnalyticsTools(server, callApi) {
     "lexq_dataset_template",
     {
       title: "Download Dataset Template",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Generate a sample CSV or JSON template based on the required facts of a version. Use this to understand the expected data format before uploading a dataset.",
       inputSchema: z7.object({
         groupId: z7.string().uuid().describe("Policy group ID"),
@@ -1260,7 +1249,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_overview",
     {
       title: "Group Latency Profile",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Per-rule latency profile of a policy group over a time window: group TOTAL distribution split by cache state (HIT = compiled ruleset cache hit, MISS = deep-load + compile), a per-rule CONDITION/ACTION percentile table, and slow-rule flags. " + RELATIVE_THRESHOLD + ` Every percentile is accompanied by its sample count n; a percentile is withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 needs n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99} \u2014 display gate, separate from the n \u2265 ${MIN_SAMPLES} judgment gate). Baselines report INSUFFICIENT_COHORT when fewer than ${MIN_COHORT_SIZE} rules qualify. Rule detail comes from a deterministic ${PROFILE_SAMPLE_PERMILLE / 10}% sample of calls; TOTAL is recorded for every call. Defaults: last ${PROFILE_DEFAULT_WINDOW_HOURS}h, live version, cacheState HIT.`,
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
@@ -1280,7 +1269,7 @@ function registerProfileTools(server, callApi) {
     "lexq_profile_rule",
     {
       title: "Rule Latency Detail",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: `Single-rule latency detail: merged phase \xD7 cacheState distributions plus a per-window time series (${LATENCY_WINDOW_MILLIS / 1e3}s windows). Missing windows are genuine gaps \u2014 never interpolated. Series points carry each window's own values; percentiles in merged distributions are withheld (null) unless n\xD7(1\u2212q) \u2265 ${TAIL_MIN_OBS} (p50 n \u2265 ${PERCENTILE_MIN_N.p50}, p95 n \u2265 ${PERCENTILE_MIN_N.p95}, p99 n \u2265 ${PERCENTILE_MIN_N.p99}). ` + RELATIVE_THRESHOLD,
       inputSchema: z8.object({
         groupId: z8.string().uuid().describe("Policy group ID"),
@@ -1305,7 +1294,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_decision",
     {
       title: "Replay a Decision",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Re-evaluate a past execution (traceId) against a candidate version and return the decision diff (decisionChanged, effect changes, fired rules) plus a determinism verdict. Synchronous and free of charge (TPS throttle only). A replay sends no webhook, notification, or event: rule actions produce no outward effects.",
       inputSchema: z9.object({
         traceId: z9.string().describe("Trace ID of the past execution to replay"),
@@ -1318,7 +1307,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_start",
     {
       title: "Start Window Replay (Blast Radius)",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: DESTRUCTIVE,
       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"),
@@ -1335,7 +1324,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_status",
     {
       title: "Get Replay Job Status",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Poll a window replay job. RUNNING shows progress 0\u2013100; COMPLETED fills summary and changedSamples; FAILED carries errorMessage. capped=true means the window exceeded the sample cap and only part was replayed.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID from lexq_replay_start")
@@ -1347,7 +1336,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_list",
     {
       title: "List Replay Jobs",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List window replay job history (reverse-chronological). Lightweight items \u2014 use lexq_replay_status for summary and changed samples.",
       inputSchema: z9.object({
         page: z9.number().int().min(0).default(0).describe("Page number"),
@@ -1360,7 +1349,7 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_cancel",
     {
       title: "Cancel Replay Job",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Cooperatively cancel a PENDING or RUNNING window replay job. Other states are rejected. VIEWER role cannot cancel.",
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID")
@@ -1372,14 +1361,17 @@ function registerReplayTools(server, callApi) {
     "lexq_replay_export",
     {
       title: "Export Replay Result",
-      annotations: { readOnlyHint: true },
-      description: "Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text.",
+      annotations: READ_ONLY,
+      description: `Export a COMPLETED window replay job. A running job is rejected \u2014 a partial result reads as the whole thing on the receiving end. The two formats carry different things: CSV holds the effect blast radius, whose columns are fixed; JSON holds the changed samples and action parameters, which nest and whose keys differ per tenant. JSON is not a superset of CSV. Returns the file contents as text. ${EXPORT_LIMIT_NOTE}`,
       inputSchema: z9.object({
         jobId: z9.string().describe("Replay job ID"),
         format: z9.enum(EXPORT_FORMATS).default("json").describe("Export format")
       })
     },
-    async ({ jobId, format }) => callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } })
+    async ({ jobId, format }) => limitExport(
+      await callApi("GET", `replay/jobs/${jobId}/export`, { params: { format } }),
+      `lexq replay export --id ${jobId} --as ${format} --output <file>`
+    )
   );
 }
 
@@ -1390,7 +1382,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_list",
     {
       title: "List Execution History",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List policy execution history. Shows trace ID, group, version, status, match result, and latency.",
       inputSchema: z10.object({
         page: z10.number().int().min(0).default(0).describe("Page number"),
@@ -1418,7 +1410,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_get",
     {
       title: "Get Execution Detail",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get full execution detail including inputFacts, mutatedFacts, generatedVariables, executionTraces, and decisionTraces.",
       inputSchema: z10.object({
         traceId: z10.string().describe("Trace ID from execution history")
@@ -1430,7 +1422,7 @@ function registerHistoryTools(server, callApi) {
     "lexq_history_stats",
     {
       title: "Execution Statistics",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       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"),
@@ -1455,7 +1447,7 @@ function registerProvenanceTools(server, callApi) {
     "lexq_provenance_get",
     {
       title: "Get Decision Provenance",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get the lineage of a single decision: what was decided, deterministic why per rule, input facts (PII facts are masked as \u2022\u2022\u2022\u2022\u2022\u2022 with maskedKeys listing them \u2014 values are revealable only in the console, audited), the authored/published/deployed responsibility chain, and the rule snapshot fingerprint.",
       inputSchema: z11.object({
         traceId: z11.string().describe("Trace ID of the execution")
@@ -1467,7 +1459,7 @@ function registerProvenanceTools(server, callApi) {
     "lexq_pii_reveals_list",
     {
       title: "List PII Reveal Audits",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List the PII reveal audit ledger \u2014 who revealed which fact of which trace, and when. Metadata only; revealed values are never stored or returned. Use for monthly access-log inspection and SIEM collection.",
       inputSchema: z11.object({
         page: z11.number().int().min(0).default(0).describe("Page number"),
@@ -1493,24 +1485,13 @@ function registerProvenanceTools(server, callApi) {
 
 // src/mcp/tools/logs.ts
 import { z as z12 } from "zod";
-
-// src/lib/enum-notes.ts
-function withNotes(notes) {
-  return Object.entries(notes).map(([value, note]) => note ? `${value} (${note})` : value);
-}
-
-// src/mcp/tools/logs.ts
-var ACTION_NOTES = {
-  RESOLVE: "mark as manually fixed",
-  IGNORE: "skip intentionally"
-};
 function registerLogTools(server, callApi) {
   server.registerTool(
     "lexq_logs_list",
     {
       title: "List Failure Logs",
-      annotations: { readOnlyHint: true },
-      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.`,
+      annotations: READ_ONLY,
+      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. ${FAILURE_LOG_CONSOLE_NOTE}`,
       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"),
@@ -1535,48 +1516,25 @@ function registerLogTools(server, callApi) {
     "lexq_logs_get",
     {
       title: "Get Failure Log",
-      annotations: { readOnlyHint: true },
-      description: "Get failure log detail by ID.",
+      annotations: READ_ONLY,
+      description: `Get failure log detail by ID. ${FAILURE_LOG_CONSOLE_NOTE}`,
       inputSchema: z12.object({
         logId: z12.string().uuid().describe("Failure log ID")
       })
     },
     async ({ logId }) => callApi("GET", `failure-logs/${logId}`)
   );
-  server.registerTool(
-    "lexq_logs_action",
-    {
-      title: "Process Failure Log",
-      annotations: { readOnlyHint: false, destructiveHint: false },
-      description: `Process a single failure log: ${withNotes(ACTION_NOTES).join(" or ")}.`,
-      inputSchema: z12.object({
-        logId: z12.string().uuid().describe("Failure log ID"),
-        action: z12.enum(FailureAction).describe("Action to take")
-      })
-    },
-    async ({ logId, action }) => callApi("POST", `failure-logs/${logId}/actions`, {
-      params: { action }
-    })
-  );
-  server.registerTool(
-    "lexq_logs_bulk_action",
-    {
-      title: "Bulk Process Failure Logs",
-      annotations: { readOnlyHint: false, destructiveHint: false },
-      description: "Process multiple failure logs at once. Provide an array of log IDs and the action.",
-      inputSchema: z12.object({
-        logIds: z12.array(z12.string().uuid()).describe("Array of failure log IDs"),
-        action: z12.enum(FailureAction).describe("Action to apply to all logs")
-      })
-    },
-    async ({ logIds, action }) => callApi("POST", "failure-logs/bulk-actions", {
-      body: { logIds, action }
-    })
-  );
 }
 
 // src/mcp/tools/webhook-subscriptions.ts
 import { z as z13 } from "zod";
+
+// src/lib/enum-notes.ts
+function withNotes(notes) {
+  return Object.entries(notes).map(([value, note]) => note ? `${value} (${note})` : value);
+}
+
+// src/mcp/tools/webhook-subscriptions.ts
 var FORMAT_NOTES = {
   GENERIC: "full JSON",
   SLACK: '{"text": "..."}'
@@ -1586,7 +1544,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_list",
     {
       title: "List Webhook Subscriptions",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List platform event webhook subscriptions. These receive deployment lifecycle notifications: publish, deploy, rollback, and undeploy, plus a deployment being scheduled or a schedule being canceled.",
       inputSchema: z13.object({
         page: z13.number().int().min(0).default(0).describe("Page number"),
@@ -1602,7 +1560,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_get",
     {
       title: "Get Webhook Subscription",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Get webhook subscription detail by ID.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -1614,7 +1572,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_save",
     {
       title: "Save Webhook Subscription",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: { ...DESTRUCTIVE, openWorldHint: true },
       description: `Create or update a webhook subscription. Omit id to create, provide id to update. Events: ${PlatformEventType.join(", ")}. Formats: ${withNotes(FORMAT_NOTES).join(", ")}.`,
       inputSchema: z13.object({
         id: z13.string().uuid().optional().describe("Subscription ID (omit to create, provide to update)"),
@@ -1632,7 +1590,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_delete",
     {
       title: "Delete Webhook Subscription",
-      annotations: { readOnlyHint: false, destructiveHint: true },
+      annotations: DESTRUCTIVE,
       description: "Delete a webhook subscription by ID.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -1644,7 +1602,7 @@ function registerWebhookSubscriptionTools(server, callApi) {
     "lexq_webhook_subscriptions_test",
     {
       title: "Test Webhook Subscription",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: { ...DESTRUCTIVE, openWorldHint: true },
       description: "Send a test event to verify webhook connectivity. Returns the HTTP status code and success/failure message.",
       inputSchema: z13.object({
         id: z13.string().uuid().describe("Webhook subscription ID")
@@ -1661,7 +1619,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_list",
     {
       title: "List Domain Templates",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "List all domain templates. A domain template is a starter pack of fact definitions and sample rules for a common decision, such as checkout pricing (ECOMMERCE) or transfer approval (FINTECH). Each entry reports its key, whether it can be applied (isAvailable), and how many facts and sample rules it provisions. Call this before preview or apply to see which templates exist.",
       inputSchema: z14.object({})
     },
@@ -1671,7 +1629,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_preview",
     {
       title: "Preview Domain Template",
-      annotations: { readOnlyHint: true },
+      annotations: READ_ONLY,
       description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers (an input with a value domain carries its allowed values or range), the sample rules it creates with a description of each, and an apply plan. This is a read-only dry run; nothing is created. factConflicts lists keys this tenant already has with a different type, or with different allowed values or a different range on an input fact. While it is not empty, apply fails with P-061 and creates nothing: delete those facts or change them to match the template, then apply. plan is null for a template that cannot be applied yet.",
       inputSchema: z14.object({
         template: z14.string().describe(
@@ -1685,7 +1643,7 @@ function registerDomainTemplateTools(server, callApi) {
     "lexq_domain_templates_apply",
     {
       title: "Apply Domain Template",
-      annotations: { readOnlyHint: false, destructiveHint: false },
+      annotations: ADDITIVE,
       description: "Apply a domain template to the current tenant. Creates the template's fact definitions and a new policy group pre-populated with its sample rules as a DRAFT version. Apply never overwrites existing schema: a key that already exists with the same definition is kept as it is. Run lexq_domain_templates_preview first. If its factConflicts is not empty, apply fails with P-061 and creates nothing until those facts are deleted or changed to match the template. A template whose isAvailable is false cannot be applied.",
       inputSchema: z14.object({
         template: z14.string().describe("Domain template key to apply (e.g. ECOMMERCE)."),
@@ -1720,10 +1678,18 @@ function registerAllTools(server, callApi) {
   registerWebhookSubscriptionTools(server, callApi);
 }
 var SERVER_INFO = { name: "lexq", ...server_info_default };
+var SERVER_INSTRUCTIONS = [
+  "LexQ evaluates business rules: a policy group holds versions, a version holds rules, and rules read input facts.",
+  "- Date filters (yyyy-MM-dd) are whole days in the organization's time zone, not UTC. Call lexq_whoami for tenantTimezone before working out the current date or a date range.",
+  "- Before creating rules, call lexq_facts_list to see which facts exist and their types. When a rule needs a fact that is not defined, confirm its type and description with the user before calling lexq_facts_create.",
+  "- Before lexq_deploy_publish, run lexq_dry_run on the version with representative facts. A published version cannot go back to draft.",
+  `- For anything these tools cannot do, point the user to the LexQ console at ${CONSOLE_URL}.`
+].join("\n");
 export {
   ApiError,
   LosslessNumber,
   SERVER_INFO,
+  SERVER_INSTRUCTIONS,
   formatUnregisteredFactWarning,
   formatValueDomainMismatchWarning,
   isLosslessNumber,