@lexq/cli 1.1.3 → 1.1.5

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
 

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
@@ -3939,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).
       `,
@@ -4104,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"),
@@ -4144,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")
@@ -5000,7 +5012,7 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "List Domain Templates",
       annotations: { readOnlyHint: true },
-      description: "List all domain templates. A domain template is a curated, industry-specific starter pack of fact definitions and sample rules (e.g. ECOMMERCE). Each entry reports its key, status (ACTIVE or COMING_SOON), and a summary of what it provisions. Call this before preview or apply to discover which templates can currently be applied.",
+      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({})
     },
     async () => callApi("GET", "domain-templates")
@@ -5010,10 +5022,10 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "Preview Domain Template",
       annotations: { readOnlyHint: true },
-      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers, the sample rules it creates, and an apply plan. This is a read-only dry run \u2014 nothing is created. Only ACTIVE templates can be previewed.",
+      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers (an input with a constraint 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(
-          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see available keys \u2014 currently only ECOMMERCE is ACTIVE."
+          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see the keys."
         )
       })
     },
@@ -5024,7 +5036,7 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "Apply Domain Template",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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. Existing facts are skipped \u2014 apply is additive and never overwrites existing schema. Run lexq_domain_templates_preview first to review what will be created. Only ACTIVE templates can be applied.",
+      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)."),
         customName: z14.string().optional().describe(
@@ -5141,7 +5153,7 @@ function registerDomainTemplateCommands(program) {
           apply     Apply a template to the current tenant
 
         Workflow: list → preview → apply
-        Currently available: ECOMMERCE  (FINTECH, SAAS — coming soon)
+        Run "list" to see every template and whether it can be applied.
       `
   );
   templates.command("list").description("List available domain templates").action(async () => {
@@ -5208,10 +5220,12 @@ function registerDomainTemplateCommands(program) {
     dedent18`
 
         Creates the template's fact definitions and a new DRAFT policy group
-        populated with its sample rules. Existing facts are skipped — apply is
-        additive and never overwrites your schema.
+        populated with its sample rules. A fact that already exists with the
+        same definition is kept as it is, so apply never overwrites your schema.
 
-        Run "preview" first to review what will be created.
+        Run "preview" first to review what will be created. If it lists
+        factConflicts, apply fails with P-061 and creates nothing: delete those
+        facts or change them to match the template first.
 
         Example:
           $ lexq domain-templates apply --template ECOMMERCE

package/dist/mcp/register.js

@@ -483,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).
       `,
@@ -652,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"),
@@ -692,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")
@@ -1548,7 +1558,7 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "List Domain Templates",
       annotations: { readOnlyHint: true },
-      description: "List all domain templates. A domain template is a curated, industry-specific starter pack of fact definitions and sample rules (e.g. ECOMMERCE). Each entry reports its key, status (ACTIVE or COMING_SOON), and a summary of what it provisions. Call this before preview or apply to discover which templates can currently be applied.",
+      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({})
     },
     async () => callApi("GET", "domain-templates")
@@ -1558,10 +1568,10 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "Preview Domain Template",
       annotations: { readOnlyHint: true },
-      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers, the sample rules it creates, and an apply plan. This is a read-only dry run \u2014 nothing is created. Only ACTIVE templates can be previewed.",
+      description: "Preview exactly what a domain template will provision before applying it: the fact definitions it registers (an input with a constraint 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(
-          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see available keys \u2014 currently only ECOMMERCE is ACTIVE."
+          "Domain template key (e.g. ECOMMERCE). Use lexq_domain_templates_list to see the keys."
         )
       })
     },
@@ -1572,7 +1582,7 @@ function registerDomainTemplateTools(server, callApi) {
     {
       title: "Apply Domain Template",
       annotations: { readOnlyHint: false, destructiveHint: false },
-      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. Existing facts are skipped \u2014 apply is additive and never overwrites existing schema. Run lexq_domain_templates_preview first to review what will be created. Only ACTIVE templates can be applied.",
+      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)."),
         customName: z14.string().optional().describe(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "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