@lexq/cli 1.1.2 → 1.1.4

package/README.md

@@ -1,7 +1,7 @@
 # LexQ CLI
 
 > **The Decision Operations Platform for engineering teams.**
-> CLI and MCP server for [LexQ](https://lexq.io) — move business rules out of
+> CLI and MCP server for [LexQ](https://lexq.io). Move business rules out of
 > your deploy pipeline, prove every change with Impact Simulation, and ship without
 > a git push.
 
@@ -14,20 +14,17 @@
 
 ## Why LexQ?
 
-Your business rules — pricing, promotions, fee logic, eligibility checks —
-change often. But every change ships through the same PR → review → staging
-→ deploy cycle as your core application code. A one-line discount rule
-takes two weeks.
+Your business rules, such as pricing, promotions, fee logic, and eligibility
+checks, change often. But every change ships through the same PR → review →
+staging → deploy cycle as your core application code, so even a small change
+waits for the next release.
 
-This is an architectural problem, not a process problem. Business logic
-that changes weekly shouldn't live in code that ships quarterly.
+**LexQ keeps those rules out of your code.** Your service calls the LexQ API to
+evaluate them. You change rules in a visual console or through this CLI, test
+each change with Impact Simulation against past executions or a dataset you
+upload, and deploy them without an application release.
 
-**LexQ separates the two.** Rules live outside your application. You change
-them in a visual console or through this CLI. You prove every change with
-Impact Simulation against real execution data. You deploy without touching
-your codebase.
-
-Every decision leaves a full audit trace.
+Every decision leaves a full audit trail.
 
 ## Install
 
@@ -67,19 +64,22 @@ lexq deploy publish --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "v1"
 lexq deploy live --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "Initial deploy"
 ```
 
-## For AI Agents — the Complete Partner API
+## For AI Agents
+
+Claude, Cursor, and other MCP-compatible agents can use the Model Context
+Protocol to manage policy groups, versions, rules, and facts, run simulations
+and replays, deploy versions, and read execution history.
 
-LexQ is designed to be AI-native. The entire policy engine Partner API is
-exposed via Model Context Protocol. Claude, Cursor, and other MCP-compatible
-agents can create, simulate, and deploy rules autonomously, with human approval
-before production.
+Approval happens in your MCP client, which decides which tool calls you confirm.
+The deploy, rollback, and undeploy tools are marked as destructive, so a client
+can ask you before running them.
 
-### Claude.ai (Cloud — no install)
+### Claude.ai (cloud, no install)
 
-1. **Settings → Connectors → Add Custom Integration**
-2. Enter: `https://mcp.lexq.io`
-3. Sign in with your LexQ account and select an API key
-4. Done — the full toolset available in every conversation
+1. **Customize → Connectors → + Add → Add custom connector**
+2. Name it, enter `https://mcp.lexq.io`, and choose **Sign in now**
+3. On the LexQ page that opens, sign in and generate a new API key for MCP, or choose **I already have an API key** and paste an existing one
+4. The tools are now available in every conversation
 
 ### Remote (Streamable HTTP)
 
@@ -170,8 +170,8 @@ keeps working.
 
 ## AI Agent Skills
 
-LexQ CLI ships with **AI Agent Skills** — structured documentation agents
-read to understand *how* to use the tools, not just *what* they are.
+LexQ CLI ships with **AI Agent Skills**: structured documentation that tells
+agents *how* to use each tool.
 
 ```
 skills/
@@ -242,9 +242,9 @@ Config is stored at `~/.lexq/config.json`:
 }
 ```
 
-The file holds an API key in plain text, so it is written `0600` inside a `0700` directory —
-readable by its owner and nobody else on the machine. An install created by an older version
-is repaired on the next save.
+The file holds an API key in plain text. It is saved with mode `0600` inside a `0700`
+directory, so only its owner can read it. If an older version created it with looser
+permissions, the CLI tightens them the next time it saves the file.
 
 ### Environment variables
 
@@ -280,7 +280,7 @@ pnpm enums:check                # Generated enums match the engine contract
 pnpm prose:check                # Numbers and code tables in prose match the contract
 pnpm ab-key:check               # Tool descriptions still name the A/B traffic key
 pnpm surface:check              # Nothing internal reached a public file
-pnpm registry:check             # server.json agrees with package.json
+pnpm registry:check             # server.json agrees with package.json and src/mcp/server-info.json
 pnpm schemas:check              # tools/list matches the recorded snapshot (needs a build)
 pnpm test:fact-key              # Fact key grammar
 pnpm test:decimals              # Metric precision display

package/dist/index.js

@@ -1058,7 +1058,7 @@ ${data.length} total`);
         Action Types:
           MUTATE_FACT   { targetVar, operator, method, operand, refVar?, rounding? }
           SET_FACT      { targetVar, value }
-          BLOCK         { reason }
+          BLOCK         { reason? }
 
           refVar is the percentage base and is optional — omit to use targetVar itself.
           It is only valid in PERCENTAGE × {ASSIGN, ADD, SUB}.
@@ -1302,7 +1302,8 @@ function registerFactCommands(program) {
           delete           Remove a fact definition
           action-metadata  Show action runtime fact metadata
 
-        System facts (userId, userTags) are auto-created.
+        Every tenant starts with userId and userTags, and with the system facts
+        isBlocked and blockReason, which only the BLOCK action writes.
       `
   );
   facts.command("list").description("List fact definitions").option("--keyword <keyword>", "Filter by keyword").option("--page <number>", "Page number", "0").option("--size <number>", "Page size", "20").action(async (opts) => {
@@ -1443,7 +1444,8 @@ ${data.length} unregistered`);
     "after",
     dedent6`
 
-        System facts accept name, description, and the PII flag only.
+        System facts (isBlocked, blockReason) accept changes to name, description, the PII flag,
+        and the value domain. --required is ignored, and the type cannot change (FD-003).
 
         Examples:
           $ lexq facts update --id <factId> --name "Updated Name" --required
@@ -3562,6 +3564,20 @@ function formatUnregisteredFactWarning(meta) {
   ].join("\n");
 }
 
+// src/mcp/server-info.json
+var server_info_default = {
+  title: "LexQ",
+  description: "The Decision Operations Platform for engineering teams",
+  websiteUrl: "https://lexq.io",
+  icons: [
+    {
+      src: "https://lexq.io/logo.png",
+      mimeType: "image/png",
+      sizes: ["1024x1024"]
+    }
+  ]
+};
+
 // src/mcp/tools/status.ts
 import { z } from "zod";
 function registerStatusTools(server, callApi) {
@@ -3925,11 +3941,21 @@ function registerRuleTools(server, callApi) {
           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 that can write a key absent from the input facts. MUTATE_FACT requires
+          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 —
+        - 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 the isBlocked fact.
+          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?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,
@@ -4090,7 +4116,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Update Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      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 accept name, description, and PII only.",
+      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"),
         name: z5.string().optional().describe("Display name"),
@@ -4130,7 +4156,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Get Action Runtime Fact Metadata",
       annotations: { readOnlyHint: true },
-      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 that can write a key the request did not send, and its targetVar must be a registered fact (ACT-032). Static data, safe to cache in-session.",
+      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({})
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -5043,6 +5069,7 @@ function registerAllTools(server, callApi) {
   registerDomainTemplateTools(server, callApi);
   registerWebhookSubscriptionTools(server, callApi);
 }
+var SERVER_INFO = { name: "lexq", ...server_info_default };
 
 // src/mcp/server.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
@@ -5059,7 +5086,7 @@ function startMcpServer() {
   const callApi = createCallApiFromConfig();
   serveStdio(
     () => {
-      const server = new McpServer({ name: "lexq", version });
+      const server = new McpServer({ ...SERVER_INFO, version });
       registerAllTools(server, callApi);
       return server;
     },

package/dist/mcp/register.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/server';
+import { Implementation, McpServer } from '@modelcontextprotocol/server';
 import { LosslessNumber } from 'lossless-json';
 export { LosslessNumber } from 'lossless-json';
 
@@ -63,5 +63,14 @@ declare const isLosslessNumber: (value: unknown) => value is LosslessNumber;
  * @param callApi - API caller function (config-based for CLI, Bearer-based for HTTP)
  */
 declare function registerAllTools(server: McpServer, callApi: CallApi): void;
+/**
+ * How the server introduces itself when a client connects: a title, a description and an
+ * icon the client can show, and a link to its website. A host serving these tools adds its
+ * own version.
+ *
+ * The values are kept in server-info.json rather than here because server.json lists them
+ * again for the MCP Registry, and `pnpm registry:check` has to read both without a build.
+ */
+declare const SERVER_INFO: Omit<Implementation, 'version'>;
 
-export { ApiError, type CallApi, type McpToolResult, formatUnregisteredFactWarning, isLosslessNumber, paginationParams, parseJson, registerAllTools, stringifyJson };
+export { ApiError, type CallApi, type McpToolResult, SERVER_INFO, formatUnregisteredFactWarning, isLosslessNumber, paginationParams, parseJson, registerAllTools, stringifyJson };

package/dist/mcp/register.js

@@ -1,3 +1,17 @@
+// src/mcp/server-info.json
+var server_info_default = {
+  title: "LexQ",
+  description: "The Decision Operations Platform for engineering teams",
+  websiteUrl: "https://lexq.io",
+  icons: [
+    {
+      src: "https://lexq.io/logo.png",
+      mimeType: "image/png",
+      sizes: ["1024x1024"]
+    }
+  ]
+};
+
 // src/mcp/tools/status.ts
 import { z } from "zod";
 function registerStatusTools(server, callApi) {
@@ -469,11 +483,21 @@ function registerRuleTools(server, callApi) {
           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 that can write a key absent from the input facts. MUTATE_FACT requires
+          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 —
+        - 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 the isBlocked fact.
+          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?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,
@@ -638,7 +662,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Update Fact Definition",
       annotations: { readOnlyHint: false, destructiveHint: true },
-      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 accept name, description, and PII only.",
+      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"),
         name: z5.string().optional().describe("Display name"),
@@ -678,7 +702,7 @@ function registerFactTools(server, callApi) {
     {
       title: "Get Action Runtime Fact Metadata",
       annotations: { readOnlyHint: true },
-      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 that can write a key the request did not send, and its targetVar must be a registered fact (ACT-032). Static data, safe to cache in-session.",
+      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({})
     },
     async () => callApi("GET", "schema/action-metadata")
@@ -1591,9 +1615,11 @@ function registerAllTools(server, callApi) {
   registerDomainTemplateTools(server, callApi);
   registerWebhookSubscriptionTools(server, callApi);
 }
+var SERVER_INFO = { name: "lexq", ...server_info_default };
 export {
   ApiError,
   LosslessNumber,
+  SERVER_INFO,
   formatUnregisteredFactWarning,
   isLosslessNumber,
   paginationParams,

package/package.json

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

package/skills/lexq-rules/SKILL.md

@@ -182,7 +182,7 @@ Each rule can have multiple actions. Actions fire sequentially.
 |---------------|--------------------------------------------|----------------------------------------------------------------------|
 | `MUTATE_FACT` | Arithmetic change to a numeric fact        | `targetVar`, `operator`, `method`, `operand`, `refVar?`, `rounding?` |
 | `SET_FACT`    | Assign a literal value to a registered fact | `targetVar`, `value`                                                |
-| `BLOCK`       | Record a rejection decision                | `reason`                                                             |
+| `BLOCK`       | Record a rejection decision                | `reason?`                                                            |
 
 ### `MUTATE_FACT` parameters
 
@@ -247,9 +247,13 @@ request didn't send" is `SET_FACT`'s job.
 
 ### `BLOCK` does not halt execution
 
-`BLOCK` records a rejection decision by writing the `isBlocked` fact. Subsequent actions in the
-same rule and subsequent winning rules still run. Enforcement is the caller's responsibility —
-read `isBlocked` from the response.
+`BLOCK` records a rejection decision by writing `isBlocked` (`true`) and `blockReason` (`reason`,
+or `Policy Violation` when omitted). Subsequent actions in the same rule and subsequent winning
+rules still run. Enforcement is the caller's responsibility — read `isBlocked` from the response.
+
+Only `BLOCK` writes those two keys. Saving or publishing a rule whose `SET_FACT` or
+`MUTATE_FACT` targets either one fails with `ACT-033`. No condition sees what `BLOCK` writes
+in the same request: every condition is checked against the input facts before any action runs.
 
 ### Action Example: 10% Discount via MUTATE_FACT