@switchbot/openapi-cli 3.3.3 → 3.4.1

package/dist/index.js

@@ -989,8 +989,8 @@ var require_command = __commonJS({
     init_cjs_shim();
     var EventEmitter = __require("node:events").EventEmitter;
     var childProcess = __require("node:child_process");
-    var path28 = __require("node:path");
-    var fs31 = __require("node:fs");
+    var path29 = __require("node:path");
+    var fs33 = __require("node:fs");
     var process4 = __require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1922,11 +1922,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path28.resolve(baseDir, baseName);
-          if (fs31.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path28.extname(baseName))) return void 0;
+          const localBin = path29.resolve(baseDir, baseName);
+          if (fs33.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path29.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs31.existsSync(`${localBin}${ext}`)
+            (ext) => fs33.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -1938,21 +1938,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs31.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs33.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path28.resolve(
-            path28.dirname(resolvedScriptPath),
+          executableDir = path29.resolve(
+            path29.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path28.basename(
+            const legacyName = path29.basename(
               this._scriptPath,
-              path28.extname(this._scriptPath)
+              path29.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -1963,7 +1963,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path28.extname(executableFile));
+        launchWithNode = sourceExt.includes(path29.extname(executableFile));
         let proc;
         if (process4.platform !== "win32") {
           if (launchWithNode) {
@@ -2803,7 +2803,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path28.basename(filename, path28.extname(filename));
+        this._name = path29.basename(filename, path29.extname(filename));
         return this;
       }
       /**
@@ -2817,9 +2817,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path29) {
-        if (path29 === void 0) return this._executableDir;
-        this._executableDir = path29;
+      executableDir(path30) {
+        if (path30 === void 0) return this._executableDir;
+        this._executableDir = path30;
         return this;
       }
       /**
@@ -4340,7 +4340,7 @@ var require_supports_colors = __commonJS({
   "node_modules/@colors/colors/lib/system/supports-colors.js"(exports, module) {
     "use strict";
     init_cjs_shim();
-    var os25 = __require("os");
+    var os26 = __require("os");
     var hasFlag2 = require_has_flag();
     var env2 = process.env;
     var forceColor = void 0;
@@ -4378,7 +4378,7 @@ var require_supports_colors = __commonJS({
       }
       var min = forceColor ? 1 : 0;
       if (process.platform === "win32") {
-        var osRelease = os25.release().split(".");
+        var osRelease = os26.release().split(".");
         if (Number(process.versions.node.split(".")[0]) >= 8 && Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
           return Number(osRelease[2]) >= 14931 ? 3 : 2;
         }
@@ -7221,7 +7221,7 @@ function emitJsonError(errorPayload) {
 function emitStreamHeader(opts) {
   console.log(
     JSON.stringify({
-      schemaVersion: SCHEMA_VERSION,
+      schemaVersion: opts.schemaVersion ?? SCHEMA_VERSION,
       stream: true,
       eventKind: opts.eventKind,
       cadence: opts.cadence
@@ -7531,7 +7531,7 @@ var init_output = __esm({
     init_source();
     init_client();
     init_flags();
-    SCHEMA_VERSION = "1.1";
+    SCHEMA_VERSION = "1.2";
     ASCII_BORDER_CHARS = {
       top: "-",
       "top-mid": "+",
@@ -8676,6 +8676,18 @@ function writeAudit(entry) {
   } catch {
   }
 }
+function writeEvaluateTrace(record2, filePath) {
+  const file2 = filePath ?? resolveAuditPath();
+  if (!file2) return;
+  const dir = path8.dirname(file2);
+  try {
+    if (!fs8.existsSync(dir)) {
+      fs8.mkdirSync(dir, { recursive: true });
+    }
+    fs8.appendFileSync(file2, JSON.stringify({ auditVersion: AUDIT_VERSION, ...record2 }) + "\n");
+  } catch {
+  }
+}
 function readAudit(file2) {
   if (!fs8.existsSync(file2)) return [];
   const raw = fs8.readFileSync(file2, "utf-8");
@@ -9428,17 +9440,17 @@ var require_visit = __commonJS({
     visit.BREAK = BREAK;
     visit.SKIP = SKIP;
     visit.REMOVE = REMOVE;
-    function visit_(key, node, visitor, path28) {
-      const ctrl = callVisitor(key, node, visitor, path28);
+    function visit_(key, node, visitor, path29) {
+      const ctrl = callVisitor(key, node, visitor, path29);
       if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
-        replaceNode(key, path28, ctrl);
-        return visit_(key, ctrl, visitor, path28);
+        replaceNode(key, path29, ctrl);
+        return visit_(key, ctrl, visitor, path29);
       }
       if (typeof ctrl !== "symbol") {
         if (identity.isCollection(node)) {
-          path28 = Object.freeze(path28.concat(node));
+          path29 = Object.freeze(path29.concat(node));
           for (let i = 0; i < node.items.length; ++i) {
-            const ci = visit_(i, node.items[i], visitor, path28);
+            const ci = visit_(i, node.items[i], visitor, path29);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -9449,13 +9461,13 @@ var require_visit = __commonJS({
             }
           }
         } else if (identity.isPair(node)) {
-          path28 = Object.freeze(path28.concat(node));
-          const ck = visit_("key", node.key, visitor, path28);
+          path29 = Object.freeze(path29.concat(node));
+          const ck = visit_("key", node.key, visitor, path29);
           if (ck === BREAK)
             return BREAK;
           else if (ck === REMOVE)
             node.key = null;
-          const cv = visit_("value", node.value, visitor, path28);
+          const cv = visit_("value", node.value, visitor, path29);
           if (cv === BREAK)
             return BREAK;
           else if (cv === REMOVE)
@@ -9476,17 +9488,17 @@ var require_visit = __commonJS({
     visitAsync.BREAK = BREAK;
     visitAsync.SKIP = SKIP;
     visitAsync.REMOVE = REMOVE;
-    async function visitAsync_(key, node, visitor, path28) {
-      const ctrl = await callVisitor(key, node, visitor, path28);
+    async function visitAsync_(key, node, visitor, path29) {
+      const ctrl = await callVisitor(key, node, visitor, path29);
       if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
-        replaceNode(key, path28, ctrl);
-        return visitAsync_(key, ctrl, visitor, path28);
+        replaceNode(key, path29, ctrl);
+        return visitAsync_(key, ctrl, visitor, path29);
       }
       if (typeof ctrl !== "symbol") {
         if (identity.isCollection(node)) {
-          path28 = Object.freeze(path28.concat(node));
+          path29 = Object.freeze(path29.concat(node));
           for (let i = 0; i < node.items.length; ++i) {
-            const ci = await visitAsync_(i, node.items[i], visitor, path28);
+            const ci = await visitAsync_(i, node.items[i], visitor, path29);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -9497,13 +9509,13 @@ var require_visit = __commonJS({
             }
           }
         } else if (identity.isPair(node)) {
-          path28 = Object.freeze(path28.concat(node));
-          const ck = await visitAsync_("key", node.key, visitor, path28);
+          path29 = Object.freeze(path29.concat(node));
+          const ck = await visitAsync_("key", node.key, visitor, path29);
           if (ck === BREAK)
             return BREAK;
           else if (ck === REMOVE)
             node.key = null;
-          const cv = await visitAsync_("value", node.value, visitor, path28);
+          const cv = await visitAsync_("value", node.value, visitor, path29);
           if (cv === BREAK)
             return BREAK;
           else if (cv === REMOVE)
@@ -9530,23 +9542,23 @@ var require_visit = __commonJS({
       }
       return visitor;
     }
-    function callVisitor(key, node, visitor, path28) {
+    function callVisitor(key, node, visitor, path29) {
       if (typeof visitor === "function")
-        return visitor(key, node, path28);
+        return visitor(key, node, path29);
       if (identity.isMap(node))
-        return visitor.Map?.(key, node, path28);
+        return visitor.Map?.(key, node, path29);
       if (identity.isSeq(node))
-        return visitor.Seq?.(key, node, path28);
+        return visitor.Seq?.(key, node, path29);
       if (identity.isPair(node))
-        return visitor.Pair?.(key, node, path28);
+        return visitor.Pair?.(key, node, path29);
       if (identity.isScalar(node))
-        return visitor.Scalar?.(key, node, path28);
+        return visitor.Scalar?.(key, node, path29);
       if (identity.isAlias(node))
-        return visitor.Alias?.(key, node, path28);
+        return visitor.Alias?.(key, node, path29);
       return void 0;
     }
-    function replaceNode(key, path28, node) {
-      const parent = path28[path28.length - 1];
+    function replaceNode(key, path29, node) {
+      const parent = path29[path29.length - 1];
       if (identity.isCollection(parent)) {
         parent.items[key] = node;
       } else if (identity.isPair(parent)) {
@@ -10163,10 +10175,10 @@ var require_Collection = __commonJS({
     var createNode = require_createNode();
     var identity = require_identity();
     var Node = require_Node();
-    function collectionFromPath(schema2, path28, value) {
+    function collectionFromPath(schema2, path29, value) {
       let v2 = value;
-      for (let i = path28.length - 1; i >= 0; --i) {
-        const k2 = path28[i];
+      for (let i = path29.length - 1; i >= 0; --i) {
+        const k2 = path29[i];
         if (typeof k2 === "number" && Number.isInteger(k2) && k2 >= 0) {
           const a = [];
           a[k2] = v2;
@@ -10185,7 +10197,7 @@ var require_Collection = __commonJS({
         sourceObjects: /* @__PURE__ */ new Map()
       });
     }
-    var isEmptyPath = (path28) => path28 == null || typeof path28 === "object" && !!path28[Symbol.iterator]().next().done;
+    var isEmptyPath = (path29) => path29 == null || typeof path29 === "object" && !!path29[Symbol.iterator]().next().done;
     var Collection = class extends Node.NodeBase {
       constructor(type2, schema2) {
         super(type2);
@@ -10215,11 +10227,11 @@ var require_Collection = __commonJS({
        * be a Pair instance or a `{ key, value }` object, which may not have a key
        * that already exists in the map.
        */
-      addIn(path28, value) {
-        if (isEmptyPath(path28))
+      addIn(path29, value) {
+        if (isEmptyPath(path29))
           this.add(value);
         else {
-          const [key, ...rest] = path28;
+          const [key, ...rest] = path29;
           const node = this.get(key, true);
           if (identity.isCollection(node))
             node.addIn(rest, value);
@@ -10233,8 +10245,8 @@ var require_Collection = __commonJS({
        * Removes a value from the collection.
        * @returns `true` if the item was found and removed.
        */
-      deleteIn(path28) {
-        const [key, ...rest] = path28;
+      deleteIn(path29) {
+        const [key, ...rest] = path29;
         if (rest.length === 0)
           return this.delete(key);
         const node = this.get(key, true);
@@ -10248,8 +10260,8 @@ var require_Collection = __commonJS({
        * scalar values from their surrounding node; to disable set `keepScalar` to
        * `true` (collections are always returned intact).
        */
-      getIn(path28, keepScalar) {
-        const [key, ...rest] = path28;
+      getIn(path29, keepScalar) {
+        const [key, ...rest] = path29;
         const node = this.get(key, true);
         if (rest.length === 0)
           return !keepScalar && identity.isScalar(node) ? node.value : node;
@@ -10267,8 +10279,8 @@ var require_Collection = __commonJS({
       /**
        * Checks if the collection includes a value with the key `key`.
        */
-      hasIn(path28) {
-        const [key, ...rest] = path28;
+      hasIn(path29) {
+        const [key, ...rest] = path29;
         if (rest.length === 0)
           return this.has(key);
         const node = this.get(key, true);
@@ -10278,8 +10290,8 @@ var require_Collection = __commonJS({
        * Sets a value in this collection. For `!!set`, `value` needs to be a
        * boolean to add/remove the item from the set.
        */
-      setIn(path28, value) {
-        const [key, ...rest] = path28;
+      setIn(path29, value) {
+        const [key, ...rest] = path29;
         if (rest.length === 0) {
           this.set(key, value);
         } else {
@@ -12826,9 +12838,9 @@ var require_Document = __commonJS({
           this.contents.add(value);
       }
       /** Adds a value to the document. */
-      addIn(path28, value) {
+      addIn(path29, value) {
         if (assertCollection(this.contents))
-          this.contents.addIn(path28, value);
+          this.contents.addIn(path29, value);
       }
       /**
        * Create a new `Alias` node, ensuring that the target `node` has the required anchor.
@@ -12903,14 +12915,14 @@ var require_Document = __commonJS({
        * Removes a value from the document.
        * @returns `true` if the item was found and removed.
        */
-      deleteIn(path28) {
-        if (Collection.isEmptyPath(path28)) {
+      deleteIn(path29) {
+        if (Collection.isEmptyPath(path29)) {
           if (this.contents == null)
             return false;
           this.contents = null;
           return true;
         }
-        return assertCollection(this.contents) ? this.contents.deleteIn(path28) : false;
+        return assertCollection(this.contents) ? this.contents.deleteIn(path29) : false;
       }
       /**
        * Returns item at `key`, or `undefined` if not found. By default unwraps
@@ -12925,10 +12937,10 @@ var require_Document = __commonJS({
        * scalar values from their surrounding node; to disable set `keepScalar` to
        * `true` (collections are always returned intact).
        */
-      getIn(path28, keepScalar) {
-        if (Collection.isEmptyPath(path28))
+      getIn(path29, keepScalar) {
+        if (Collection.isEmptyPath(path29))
           return !keepScalar && identity.isScalar(this.contents) ? this.contents.value : this.contents;
-        return identity.isCollection(this.contents) ? this.contents.getIn(path28, keepScalar) : void 0;
+        return identity.isCollection(this.contents) ? this.contents.getIn(path29, keepScalar) : void 0;
       }
       /**
        * Checks if the document includes a value with the key `key`.
@@ -12939,10 +12951,10 @@ var require_Document = __commonJS({
       /**
        * Checks if the document includes a value at `path`.
        */
-      hasIn(path28) {
-        if (Collection.isEmptyPath(path28))
+      hasIn(path29) {
+        if (Collection.isEmptyPath(path29))
           return this.contents !== void 0;
-        return identity.isCollection(this.contents) ? this.contents.hasIn(path28) : false;
+        return identity.isCollection(this.contents) ? this.contents.hasIn(path29) : false;
       }
       /**
        * Sets a value in this document. For `!!set`, `value` needs to be a
@@ -12959,13 +12971,13 @@ var require_Document = __commonJS({
        * Sets a value in this document. For `!!set`, `value` needs to be a
        * boolean to add/remove the item from the set.
        */
-      setIn(path28, value) {
-        if (Collection.isEmptyPath(path28)) {
+      setIn(path29, value) {
+        if (Collection.isEmptyPath(path29)) {
           this.contents = value;
         } else if (this.contents == null) {
-          this.contents = Collection.collectionFromPath(this.schema, Array.from(path28), value);
+          this.contents = Collection.collectionFromPath(this.schema, Array.from(path29), value);
         } else if (assertCollection(this.contents)) {
-          this.contents.setIn(path28, value);
+          this.contents.setIn(path29, value);
         }
       }
       /**
@@ -14942,9 +14954,9 @@ var require_cst_visit = __commonJS({
     visit.BREAK = BREAK;
     visit.SKIP = SKIP;
     visit.REMOVE = REMOVE;
-    visit.itemAtPath = (cst, path28) => {
+    visit.itemAtPath = (cst, path29) => {
       let item = cst;
-      for (const [field, index] of path28) {
+      for (const [field, index] of path29) {
         const tok = item?.[field];
         if (tok && "items" in tok) {
           item = tok.items[index];
@@ -14953,23 +14965,23 @@ var require_cst_visit = __commonJS({
       }
       return item;
     };
-    visit.parentCollection = (cst, path28) => {
-      const parent = visit.itemAtPath(cst, path28.slice(0, -1));
-      const field = path28[path28.length - 1][0];
+    visit.parentCollection = (cst, path29) => {
+      const parent = visit.itemAtPath(cst, path29.slice(0, -1));
+      const field = path29[path29.length - 1][0];
       const coll = parent?.[field];
       if (coll && "items" in coll)
         return coll;
       throw new Error("Parent collection not found");
     };
-    function _visit(path28, item, visitor) {
-      let ctrl = visitor(item, path28);
+    function _visit(path29, item, visitor) {
+      let ctrl = visitor(item, path29);
       if (typeof ctrl === "symbol")
         return ctrl;
       for (const field of ["key", "value"]) {
         const token = item[field];
         if (token && "items" in token) {
           for (let i = 0; i < token.items.length; ++i) {
-            const ci = _visit(Object.freeze(path28.concat([[field, i]])), token.items[i], visitor);
+            const ci = _visit(Object.freeze(path29.concat([[field, i]])), token.items[i], visitor);
             if (typeof ci === "number")
               i = ci - 1;
             else if (ci === BREAK)
@@ -14980,10 +14992,10 @@ var require_cst_visit = __commonJS({
             }
           }
           if (typeof ctrl === "function" && field === "key")
-            ctrl = ctrl(item, path28);
+            ctrl = ctrl(item, path29);
         }
       }
-      return typeof ctrl === "function" ? ctrl(item, path28) : ctrl;
+      return typeof ctrl === "function" ? ctrl(item, path29) : ctrl;
     }
     exports.visit = visit;
   }
@@ -16272,14 +16284,14 @@ var require_parser = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs31 = this.flowScalar(this.type);
+              const fs33 = this.flowScalar(this.type);
               if (atNextItem || it.value) {
-                map3.items.push({ start, key: fs31, sep: [] });
+                map3.items.push({ start, key: fs33, sep: [] });
                 this.onKeyLine = true;
               } else if (it.sep) {
-                this.stack.push(fs31);
+                this.stack.push(fs33);
               } else {
-                Object.assign(it, { key: fs31, sep: [] });
+                Object.assign(it, { key: fs33, sep: [] });
                 this.onKeyLine = true;
               }
               return;
@@ -16407,13 +16419,13 @@ var require_parser = __commonJS({
             case "scalar":
             case "single-quoted-scalar":
             case "double-quoted-scalar": {
-              const fs31 = this.flowScalar(this.type);
+              const fs33 = this.flowScalar(this.type);
               if (!it || it.value)
-                fc.items.push({ start: [], key: fs31, sep: [] });
+                fc.items.push({ start: [], key: fs33, sep: [] });
               else if (it.sep)
-                this.stack.push(fs31);
+                this.stack.push(fs33);
               else
-                Object.assign(it, { key: fs31, sep: [] });
+                Object.assign(it, { key: fs33, sep: [] });
               return;
             }
             case "flow-map-end":
@@ -16724,6 +16736,14 @@ var require_dist = __commonJS({
 });
 
 // src/policy/load.ts
+var load_exports = {};
+__export(load_exports, {
+  DEFAULT_POLICY_PATH: () => DEFAULT_POLICY_PATH,
+  PolicyFileNotFoundError: () => PolicyFileNotFoundError,
+  PolicyYamlParseError: () => PolicyYamlParseError,
+  loadPolicyFile: () => loadPolicyFile,
+  resolvePolicyPath: () => resolvePolicyPath
+});
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -20004,8 +20024,8 @@ var require_utils2 = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path28) {
-      let input = path28;
+    function removeDotSegments(path29) {
+      let input = path29;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -20205,8 +20225,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path28, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path28 && path28 !== "/" ? path28 : void 0;
+        const [path29, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path29 && path29 !== "/" ? path29 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -24010,6 +24030,9 @@ function isAnyCondition(c) {
 function isNotCondition(c) {
   return c.not !== void 0 && !Array.isArray(c.not);
 }
+function isLlmCondition(c) {
+  return c.llm !== void 0 && typeof c.llm === "object";
+}
 var init_types = __esm({
   "src/rules/types.ts"() {
     "use strict";
@@ -24293,7 +24316,7 @@ function locateError(doc, lineCounter, err) {
   return { line: pos.line, col: pos.col };
 }
 function humanMessage(err) {
-  const path28 = err.instancePath || "(root)";
+  const path29 = err.instancePath || "(root)";
   switch (err.keyword) {
     case "required":
       return `missing required property "${err.params.missingProperty}"`;
@@ -24301,21 +24324,21 @@ function humanMessage(err) {
       return `unknown property "${err.params.additionalProperty}"`;
     case "dependentRequired": {
       const { property, missingProperty } = err.params;
-      const parent = path28 === "(root)" ? "" : `${path28}: `;
+      const parent = path29 === "(root)" ? "" : `${path29}: `;
       return `${parent}when "${property}" is set, "${missingProperty}" is also required`;
     }
     case "pattern":
-      return `${path28} does not match pattern ${err.params.pattern}`;
+      return `${path29} does not match pattern ${err.params.pattern}`;
     case "const":
-      return `${path28} must be exactly ${JSON.stringify(err.params.allowedValue)}`;
+      return `${path29} must be exactly ${JSON.stringify(err.params.allowedValue)}`;
     case "enum":
-      return `${path28} must be one of ${JSON.stringify(err.params.allowedValues)}`;
+      return `${path29} must be one of ${JSON.stringify(err.params.allowedValues)}`;
     case "type":
-      return `${path28} must be ${err.params.type}`;
+      return `${path29} must be ${err.params.type}`;
     case "not":
-      return `${path28} is not allowed here`;
+      return `${path29} is not allowed here`;
     default:
-      return `${path28} ${err.message ?? "is invalid"}`;
+      return `${path29} ${err.message ?? "is invalid"}`;
   }
 }
 function hintFor(err) {
@@ -24371,8 +24394,8 @@ function escapeJsonPointerSegment(segment) {
 function isPlausibleDeviceId(value) {
   return HEX_MAC_DEVICE_ID_RE.test(value) || HYPHENATED_DEVICE_ID_RE.test(value);
 }
-function hasErrorAtPath(errors, path28) {
-  return errors.some((err) => err.path === path28);
+function hasErrorAtPath(errors, path29) {
+  return errors.some((err) => err.path === path29);
 }
 function resolvePolicyDeviceRef(raw, aliases) {
   if (!raw) return { ok: false, reason: "missing-device" };
@@ -24395,25 +24418,25 @@ function isDeviceStateConditionLike(value) {
   const candidate = value;
   return typeof candidate.device === "string" && typeof candidate.field === "string" && typeof candidate.op === "string";
 }
-function collectConditionDeviceRefs(condition, path28) {
+function collectConditionDeviceRefs(condition, path29) {
   if (!condition || typeof condition !== "object" || Array.isArray(condition)) return [];
   const out = [];
   if (isDeviceStateConditionLike(condition)) {
-    out.push({ path: `${path28}/device`, ref: condition.device });
+    out.push({ path: `${path29}/device`, ref: condition.device });
   }
   const candidate = condition;
   if (Array.isArray(candidate.all)) {
     for (let i = 0; i < candidate.all.length; i++) {
-      out.push(...collectConditionDeviceRefs(candidate.all[i], `${path28}/all/${i}`));
+      out.push(...collectConditionDeviceRefs(candidate.all[i], `${path29}/all/${i}`));
     }
   }
   if (Array.isArray(candidate.any)) {
     for (let i = 0; i < candidate.any.length; i++) {
-      out.push(...collectConditionDeviceRefs(candidate.any[i], `${path28}/any/${i}`));
+      out.push(...collectConditionDeviceRefs(candidate.any[i], `${path29}/any/${i}`));
     }
   }
   if (candidate.not !== void 0) {
-    out.push(...collectConditionDeviceRefs(candidate.not, `${path28}/not`));
+    out.push(...collectConditionDeviceRefs(candidate.not, `${path29}/not`));
   }
   return out;
 }
@@ -24460,12 +24483,12 @@ function collectOfflineSemanticErrors(loaded, existingErrors) {
   const out = [];
   const aliases = collectAliasMap(data);
   for (const [aliasName, deviceId] of Object.entries(aliases)) {
-    const path28 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
-    if (hasErrorAtPath(existingErrors, path28)) continue;
+    const path29 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
+    if (hasErrorAtPath(existingErrors, path29)) continue;
     if (isPlausibleDeviceId(deviceId)) continue;
-    const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path28);
+    const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path29);
     out.push({
-      path: path28,
+      path: path29,
       line,
       col,
       keyword: "alias-device-id",
@@ -24599,12 +24622,12 @@ function validateLoadedPolicyAgainstInventory(loaded, inventory) {
     inventoryById.set(remote.deviceId, { typeName: remote.remoteType });
   }
   for (const [aliasName, deviceId] of Object.entries(aliases)) {
-    const path28 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
-    if (hasErrorAtPath(errors, path28)) continue;
+    const path29 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
+    if (hasErrorAtPath(errors, path29)) continue;
     if (!inventoryById.has(deviceId)) {
-      const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path28);
+      const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path29);
       errors.push({
-        path: path28,
+        path: path29,
         line,
         col,
         keyword: "alias-live-device-not-found",
@@ -24668,10 +24691,10 @@ function validateLoadedPolicyAgainstInventory(loaded, inventory) {
         if (!effectiveDeviceId) continue;
         const target = inventoryById.get(effectiveDeviceId);
         if (!target) {
-          const path28 = typeof action?.device === "string" ? devicePath : commandPath;
-          const { line: line2, col: col2 } = locateInstancePath(loaded.doc, loaded.lineCounter, path28);
+          const path29 = typeof action?.device === "string" ? devicePath : commandPath;
+          const { line: line2, col: col2 } = locateInstancePath(loaded.doc, loaded.lineCounter, path29);
           errors.push({
-            path: path28,
+            path: path29,
             line: line2,
             col: col2,
             keyword: "rule-live-device-not-found",
@@ -24850,6 +24873,70 @@ var init_openai = __esm({
         if (!content) throw new Error("OpenAI returned empty content");
         return content.replace(/^```ya?ml\n?/i, "").replace(/\n?```\s*$/i, "").trim();
       }
+      async decide(prompt2, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        const body = JSON.stringify({
+          model: this.model,
+          max_tokens: 256,
+          tools: [{
+            type: "function",
+            function: {
+              name: "decide",
+              description: "Return a boolean pass/fail decision with a brief reason.",
+              parameters: {
+                type: "object",
+                properties: {
+                  pass: { type: "boolean", description: "true if the condition passes, false otherwise." },
+                  reason: { type: "string", description: "Brief reason (\u2264200 chars)." }
+                },
+                required: ["pass", "reason"]
+              }
+            }
+          }],
+          tool_choice: { type: "function", function: { name: "decide" } },
+          messages: [{ role: "user", content: prompt2 }]
+        });
+        const parsed = new URL(`${this.baseUrl}/v1/chat/completions`);
+        const isHttps = parsed.protocol === "https:";
+        const responseBody = await new Promise((resolve2, reject) => {
+          const req = (isHttps ? https : http).request(
+            {
+              hostname: parsed.hostname,
+              port: parsed.port || (isHttps ? 443 : 80),
+              path: parsed.pathname,
+              method: "POST",
+              headers: {
+                "Authorization": `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(body)
+              },
+              timeout: timeoutMs
+            },
+            (res) => {
+              const chunks = [];
+              res.on("data", (c) => chunks.push(c));
+              res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf-8");
+                if (res.statusCode !== void 0 && res.statusCode >= 400) {
+                  reject(new Error(`OpenAI API error ${res.statusCode}: ${text.slice(0, 200)}`));
+                } else {
+                  resolve2(text);
+                }
+              });
+            }
+          );
+          req.on("error", reject);
+          req.on("timeout", () => req.destroy(new Error("LLM request timeout")));
+          req.write(body);
+          req.end();
+        });
+        const json3 = JSON.parse(responseBody);
+        const toolCall = json3.choices?.[0]?.message?.tool_calls?.find((tc) => tc.function.name === "decide");
+        if (!toolCall) throw new Error("OpenAI decide: no tool call in response");
+        const args = JSON.parse(toolCall.function.arguments);
+        if (typeof args.pass !== "boolean") throw new Error("OpenAI decide: malformed function-call response");
+        return { pass: args.pass, reason: String(args.reason ?? "").slice(0, 200) };
+      }
     };
   }
 });
@@ -24920,6 +25007,66 @@ var init_anthropic = __esm({
         if (!content) throw new Error("Anthropic returned empty content");
         return content.replace(/^```ya?ml\n?/i, "").replace(/\n?```\s*$/i, "").trim();
       }
+      async decide(prompt2, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        const body = JSON.stringify({
+          model: this.model,
+          max_tokens: 256,
+          tools: [{
+            name: "decide",
+            description: "Return a boolean pass/fail decision with a brief reason.",
+            input_schema: {
+              type: "object",
+              properties: {
+                pass: { type: "boolean", description: "true if the condition passes, false otherwise." },
+                reason: { type: "string", description: "Brief reason (\u2264200 chars)." }
+              },
+              required: ["pass", "reason"]
+            }
+          }],
+          tool_choice: { type: "tool", name: "decide" },
+          messages: [{ role: "user", content: prompt2 }]
+        });
+        const responseBody = await new Promise((resolve2, reject) => {
+          const req = https2.request(
+            {
+              hostname: "api.anthropic.com",
+              port: 443,
+              path: "/v1/messages",
+              method: "POST",
+              headers: {
+                "x-api-key": this.apiKey,
+                "anthropic-version": "2023-06-01",
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(body)
+              },
+              timeout: timeoutMs
+            },
+            (res) => {
+              const chunks = [];
+              res.on("data", (c) => chunks.push(c));
+              res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf-8");
+                if (res.statusCode !== void 0 && res.statusCode >= 400) {
+                  reject(new Error(`Anthropic API error ${res.statusCode}: ${text.slice(0, 200)}`));
+                } else {
+                  resolve2(text);
+                }
+              });
+            }
+          );
+          req.on("error", reject);
+          req.on("timeout", () => req.destroy(new Error("LLM request timeout")));
+          req.write(body);
+          req.end();
+        });
+        const json3 = JSON.parse(responseBody);
+        const toolUse = json3.content?.find((c) => c.type === "tool_use" && c.name === "decide");
+        if (!toolUse?.input || typeof toolUse.input.pass !== "boolean") {
+          throw new Error("Anthropic decide: malformed tool-use response");
+        }
+        return { pass: toolUse.input.pass, reason: String(toolUse.input.reason ?? "").slice(0, 200) };
+      }
     };
   }
 });
@@ -25086,8 +25233,10 @@ function matchesMqttTrigger(trigger, event, resolvedTriggerDeviceId) {
 async function evaluateConditions(conditions, now, ctx = {}) {
   const result = { matched: true, failures: [], unsupported: [] };
   if (!conditions || conditions.length === 0) return result;
+  const evaluated = [];
   for (const c of conditions) {
     const sub = await evaluateSingle(c, now, ctx);
+    evaluated.push({ c, sub });
     if (!sub.matched) {
       result.matched = false;
       result.failures.push(...sub.failures);
@@ -25096,6 +25245,13 @@ async function evaluateConditions(conditions, now, ctx = {}) {
     if (!sub.matched && result.unsupported.length > 0) {
     }
   }
+  if (ctx.trace) {
+    for (const { c, sub } of evaluated) {
+      if (!isLlmCondition(c)) {
+        pushConditionTrace(ctx.trace, c, sub);
+      }
+    }
+  }
   return result;
 }
 async function evaluateSingle(c, now, ctx) {
@@ -25157,6 +25313,29 @@ async function evaluateSingle(c, now, ctx) {
       return fail(`device_state ${c.device}.${c.field}: fetch failed \u2014 ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  if (isLlmCondition(c)) {
+    if (!ctx.llmEvaluator || !ctx.event) {
+      return {
+        matched: false,
+        failures: [],
+        unsupported: [{ keyword: "llm", hint: "llm condition requires an LlmConditionEvaluator and event in context." }]
+      };
+    }
+    try {
+      const res = await ctx.llmEvaluator.evaluate(
+        c.llm,
+        { event: ctx.event },
+        ctx.ruleVersion ?? "unknown",
+        ctx.globalLlmMaxCallsPerHour
+      );
+      if (ctx.trace) {
+        ctx.trace.push({ kind: "llm", config: res.traceFields, passed: res.pass });
+      }
+      return res.pass ? ok : fail(`llm condition returned false: ${res.traceFields.reason}`);
+    } catch (err) {
+      return fail(`llm condition error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   return {
     matched: false,
     failures: [],
@@ -25216,6 +25395,28 @@ function formatValue(v2) {
   if (typeof v2 === "string") return JSON.stringify(v2);
   return String(v2);
 }
+function conditionKind(c) {
+  if (isAllCondition(c)) return "all";
+  if (isAnyCondition(c)) return "any";
+  if (isNotCondition(c)) return "not";
+  if (isTimeBetween(c)) return "time_between";
+  if (isDeviceState(c)) return "device_state";
+  if (isLlmCondition(c)) return "llm";
+  return "unknown";
+}
+function conditionConfig(c) {
+  if (isTimeBetween(c)) return c.time_between;
+  if (isDeviceState(c)) return { device: c.device, field: c.field, op: c.op, value: c.value };
+  if (isLlmCondition(c)) return { prompt: c.llm.prompt.slice(0, 80) };
+  return void 0;
+}
+function pushConditionTrace(trace, c, sub) {
+  trace.push({
+    kind: conditionKind(c),
+    config: conditionConfig(c),
+    passed: sub.unsupported.length > 0 ? false : sub.matched
+  });
+}
 var EVENT_CLASSIFIERS;
 var init_matcher = __esm({
   "src/rules/matcher.ts"() {
@@ -26529,6 +26730,85 @@ var init_notify = __esm({
   }
 });
 
+// src/rules/trace.ts
+import { createHash as createHash3 } from "node:crypto";
+function shouldWriteTrace(mode, event, decision) {
+  if (mode === "off") return false;
+  if (mode === "full") return true;
+  if (HIGH_FREQ_EVENTS.has(event.event) && decision === "blocked-by-condition") return false;
+  return true;
+}
+function deepSortedJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(deepSortedJson).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k2) => JSON.stringify(k2) + ":" + deepSortedJson(obj[k2])).join(",") + "}";
+}
+function canonicalizeRule(rule) {
+  return deepSortedJson(rule);
+}
+function ruleVersion(rule) {
+  return createHash3("sha256").update(canonicalizeRule(rule)).digest("hex").slice(0, 8);
+}
+function filterTraceRecords(lines, opts = {}) {
+  const sinceMs = opts.since ? new Date(opts.since).getTime() : void 0;
+  const results = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (entry.kind !== "rule-evaluate") continue;
+    if (opts.fireId && entry.fireId !== opts.fireId) continue;
+    if (opts.ruleName && entry.rule.name !== opts.ruleName) continue;
+    if (sinceMs !== void 0 && new Date(entry.t).getTime() < sinceMs) continue;
+    if (opts.noFireOnly && (entry.decision === "fire" || entry.decision === "dry")) continue;
+    results.push(entry);
+  }
+  return results;
+}
+var HIGH_FREQ_EVENTS, TraceBuilder;
+var init_trace = __esm({
+  "src/rules/trace.ts"() {
+    "use strict";
+    init_cjs_shim();
+    HIGH_FREQ_EVENTS = /* @__PURE__ */ new Set([
+      "device.shadow",
+      "motion.detected",
+      "motion.cleared"
+    ]);
+    TraceBuilder = class {
+      conditions = [];
+      startMs;
+      constructor() {
+        this.startMs = Date.now();
+      }
+      push(entry) {
+        this.conditions.push(entry);
+      }
+      build(rule, event, fireId, decision) {
+        return {
+          t: (/* @__PURE__ */ new Date()).toISOString(),
+          kind: "rule-evaluate",
+          rule: { name: rule.name, version: ruleVersion(rule) },
+          trigger: { source: event.source, event: event.event, deviceId: event.deviceId },
+          fireId,
+          conditions: [...this.conditions],
+          decision,
+          evaluationMs: Date.now() - this.startMs
+        };
+      }
+    };
+  }
+});
+
 // src/rules/engine.ts
 var engine_exports = {};
 __export(engine_exports, {
@@ -26721,6 +27001,44 @@ function lintRules(automation) {
         });
       }
     }
+    for (const c of r.conditions ?? []) {
+      if (!isLlmCondition(c)) continue;
+      const llm = c.llm;
+      if (!llm.provider || llm.provider === "auto") {
+        if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY && !process.env.LLM_API_KEY) {
+          issues.push({
+            rule: r.name,
+            severity: "error",
+            code: "condition-llm-no-provider",
+            message: 'llm condition uses provider "auto" but no LLM API key env var is set (ANTHROPIC_API_KEY, OPENAI_API_KEY, or LLM_API_KEY).'
+          });
+        }
+      }
+      if (isMqttTrigger(r.when) && HIGH_FREQ_EVENTS.has(r.when.event) && !llm.cache_ttl) {
+        issues.push({
+          rule: r.name,
+          severity: "warning",
+          code: "condition-llm-no-cache-ttl-high-freq",
+          message: `llm condition on high-frequency event "${r.when.event}" without explicit cache_ttl \u2014 consider setting cache_ttl to reduce LLM calls.`
+        });
+      }
+      if (llm.budget?.max_calls_per_hour === 0) {
+        issues.push({
+          rule: r.name,
+          severity: "warning",
+          code: "condition-llm-budget-zero",
+          message: "llm condition budget.max_calls_per_hour is 0 \u2014 condition will always take the on_error path."
+        });
+      }
+      if (llm.on_error === "pass") {
+        issues.push({
+          rule: r.name,
+          severity: "warning",
+          code: "condition-llm-on-error-pass",
+          message: 'llm condition on_error is "pass" \u2014 the condition will silently pass when the LLM is unavailable or over-budget.'
+        });
+      }
+    }
     const enabled = r.enabled !== false;
     const hasError = issues.some((i) => i.severity === "error");
     const hasUnsupported = issues.some((i) => i.code === "trigger-unsupported");
@@ -26749,6 +27067,7 @@ var init_engine = __esm({
     init_notify();
     init_croner();
     init_audit();
+    init_trace();
     RulesEngine = class {
       opts;
       rules;
@@ -27079,6 +27398,13 @@ var init_engine = __esm({
       }
       async dispatchRule(rule, event) {
         const fireId = randomUUID4();
+        const traceMode = this.opts.automation?.audit?.evaluate_trace ?? "sampled";
+        const trace = new TraceBuilder();
+        const emitTrace = (decision) => {
+          if (shouldWriteTrace(traceMode, event, decision)) {
+            writeEvaluateTrace(trace.build(rule, event, fireId, decision));
+          }
+        };
         const statusCache = /* @__PURE__ */ new Map();
         const baseFetcher = this.opts.statusFetcher ?? ((id) => fetchDeviceStatus(id, this.opts.httpClient));
         const fetchStatus = (deviceId) => {
@@ -27090,7 +27416,8 @@ var init_engine = __esm({
         };
         const cond = await evaluateConditions(rule.conditions, event.t, {
           aliases: this.aliases,
-          fetchStatus
+          fetchStatus,
+          trace
         });
         if (!cond.matched) {
           const hasHysteresis = rule.hysteresis ?? rule.requires_stable_for;
@@ -27099,6 +27426,7 @@ var init_engine = __esm({
             this.hysteresisFirstSeen.delete(hysteresisKey);
           }
           if (cond.unsupported.length > 0) {
+            emitTrace("error");
             writeAudit({
               t: event.t.toISOString(),
               kind: "rule-fire",
@@ -27121,6 +27449,7 @@ var init_engine = __esm({
             return;
           }
           this.stats.conditionsFailed++;
+          emitTrace("blocked-by-condition");
           this.opts.onFire?.({ ruleName: rule.name, fireId, status: "conditions-failed", deviceId: event.deviceId, reason: cond.failures.join("; ") });
           return;
         }
@@ -27130,6 +27459,7 @@ var init_engine = __esm({
         const check2 = this.throttle.check(rule.name, effectiveMaxPerMs, event.t.getTime(), throttleKey, dedupeWindowMs);
         if (!check2.allowed) {
           this.stats.throttled++;
+          emitTrace("throttled");
           writeAudit({
             t: event.t.toISOString(),
             kind: "rule-throttled",
@@ -27157,6 +27487,7 @@ var init_engine = __esm({
           const now = event.t.getTime();
           if (firstSeen === void 0) {
             this.hysteresisFirstSeen.set(hysteresisKey, now);
+            emitTrace("throttled");
             writeAudit({
               t: event.t.toISOString(),
               kind: "rule-throttled",
@@ -27172,6 +27503,7 @@ var init_engine = __esm({
             return;
           }
           if (now - firstSeen < hysteresisMs) {
+            emitTrace("throttled");
             writeAudit({
               t: event.t.toISOString(),
               kind: "rule-throttled",
@@ -27192,6 +27524,7 @@ var init_engine = __esm({
           const countCheck = this.throttle.checkMaxFirings(rule.name, rule.maxFiringsPerHour, 36e5, event.t.getTime(), event.deviceId);
           if (!countCheck.allowed) {
             this.stats.throttled++;
+            emitTrace("throttled");
             writeAudit({
               t: event.t.toISOString(),
               kind: "rule-throttled",
@@ -27218,6 +27551,7 @@ var init_engine = __esm({
               const deviceStatus = await fetchStatus(targetId);
               const powerState = deviceStatus["powerState"];
               if (verb === "turnOn" && powerState === "on" || verb === "turnOff" && powerState === "off") {
+                emitTrace("throttled");
                 writeAudit({
                   t: event.t.toISOString(),
                   kind: "rule-throttled",
@@ -27269,6 +27603,8 @@ var init_engine = __esm({
           if (!result.ok && (action.on_error ?? "continue") === "stop") break;
         }
         if (fired) {
+          const decision = allDry ? "dry" : "fire";
+          emitTrace(decision);
           if (allDry) this.stats.dryFires++;
           else this.stats.fires++;
           this.throttle.record(rule.name, event.t.getTime(), throttleKey);
@@ -27870,6 +28206,8 @@ var init_capabilities = __esm({
       "rules summary": READ_LOCAL,
       "rules last-fired": READ_LOCAL,
       "rules explain": READ_LOCAL,
+      "rules trace-explain": READ_LOCAL,
+      "rules simulate": READ_LOCAL,
       "schema export": READ_LOCAL,
       "scenes list": READ_REMOTE,
       "scenes execute": ACTION_REMOTE,
@@ -27958,8 +28296,21 @@ function commandToJson(cmd, opts = {}) {
 }
 function resolveTargetCommand(root, argv) {
   let cmd = root;
+  const rootOptions = root.options;
+  let consumeNext = false;
   for (const token of argv) {
-    if (token.startsWith("-")) continue;
+    if (consumeNext) {
+      consumeNext = false;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      if (!token.includes("=")) {
+        const localOpts = cmd.options;
+        const opt = localOpts.find((o) => o.short === token || o.long === token) || rootOptions.find((o) => o.short === token || o.long === token);
+        if (opt && (opt.required || opt.optional)) consumeNext = true;
+      }
+      continue;
+    }
     const sub = cmd.commands.find(
       (c) => c.name() === token || c.aliases().includes(token)
     );
@@ -31425,6 +31776,26 @@ function buildRelaySetMode(opts) {
   }
   return `${ch};${modeInt}`;
 }
+function buildBrightnessSet(opts) {
+  if (!opts.brightness) throw new UsageError("--brightness is required (1-100)");
+  const b2 = parseInt(opts.brightness, 10);
+  if (!Number.isFinite(b2) || b2 < 1 || b2 > 100) {
+    throw new UsageError(`--brightness must be an integer between 1 and 100 (got "${opts.brightness}")`);
+  }
+  return String(b2);
+}
+function buildColorSet(opts) {
+  if (!opts.color) throw new UsageError('--color is required (e.g. "255:0:0", "#FF0000", "red")');
+  const result = validateSetColor(opts.color);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.color;
+}
+function buildColorTemperatureSet(opts) {
+  if (!opts.colorTemp) throw new UsageError("--color-temp is required (2700-6500)");
+  const result = validateSetColorTemperature(opts.colorTemp);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.colorTemp;
+}
 function validateParameter(deviceType, command, raw) {
   if (!deviceType) return { ok: true };
   if (deviceType === "Air Conditioner" && command === "setAll") {
@@ -31445,7 +31816,7 @@ function validateParameter(deviceType, command, raw) {
   if (command === "setColor" && isColorDevice(deviceType)) {
     return validateSetColor(raw);
   }
-  if (command === "setColorTemperature" && isColorDevice(deviceType)) {
+  if (command === "setColorTemperature" && isBrightnessDevice(deviceType)) {
     return validateSetColorTemperature(raw);
   }
   return { ok: true };
@@ -31454,7 +31825,12 @@ function isBrightnessDevice(deviceType) {
   return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Dimmer" || deviceType === "Fill Light";
 }
 function isColorDevice(deviceType) {
-  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+}
+function isLightingCommandSupported(deviceType, command) {
+  if (command === "setBrightness" || command === "setColorTemperature") return isBrightnessDevice(deviceType);
+  if (command === "setColor") return isColorDevice(deviceType);
+  return false;
 }
 function validateSetBrightness(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
@@ -32585,10 +32961,11 @@ init_arg_parsers();
 init_output();
 init_cache();
 init_devices();
+init_catalog();
 init_flags();
 init_client();
 function registerExpandCommand(devices) {
-  devices.command("expand").description("Send a command with semantic flags instead of raw positional parameters").argument("[deviceId]", 'Target device ID from "devices list" (or use --name)').argument("[command]", "Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)").option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--temp <celsius>", "AC setAll: temperature in Celsius (16-30)", intArg("--temp", { min: 16, max: 30 })).option("--mode <mode>", "AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary", stringArg("--mode")).option("--fan <speed>", "AC setAll: fan speed auto|low|mid|high", stringArg("--fan")).option("--power <state>", "AC setAll: on|off", stringArg("--power")).option("--position <percent>", "Curtain setPosition: 0-100 (0=open, 100=closed)", intArg("--position", { min: 0, max: 100 })).option("--direction <dir>", "Blind Tilt setPosition: up|down", stringArg("--direction")).option("--angle <percent>", "Blind Tilt setPosition: 0-100 (0=closed, 100=open)", intArg("--angle", { min: 0, max: 100 })).option("--channel <n>", "Relay Switch 2 setMode: channel 1 or 2", intArg("--channel", { min: 1, max: 2 })).option("--yes", "Confirm destructive commands").addHelpText("after", `
+  devices.command("expand").description("Send a command with semantic flags instead of raw positional parameters").argument("[deviceId]", 'Target device ID from "devices list" (or use --name)').argument("[command]", "Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2), setBrightness/setColor/setColorTemperature (lighting)").option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--temp <celsius>", "AC setAll: temperature in Celsius (16-30)", intArg("--temp", { min: 16, max: 30 })).option("--mode <mode>", "AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary", stringArg("--mode")).option("--fan <speed>", "AC setAll: fan speed auto|low|mid|high", stringArg("--fan")).option("--power <state>", "AC setAll: on|off", stringArg("--power")).option("--position <percent>", "Curtain setPosition: 0-100 (0=open, 100=closed)", intArg("--position", { min: 0, max: 100 })).option("--direction <dir>", "Blind Tilt setPosition: up|down", stringArg("--direction")).option("--angle <percent>", "Blind Tilt setPosition: 0-100 (0=closed, 100=open)", intArg("--angle", { min: 0, max: 100 })).option("--channel <n>", "Relay Switch 2 setMode: channel 1 or 2", intArg("--channel", { min: 1, max: 2 })).option("--brightness <percent>", "setBrightness: 1-100 percent", intArg("--brightness", { min: 1, max: 100 })).option("--color <value>", "setColor: R:G:B, #RRGGBB, or named color (red, blue, etc.)", stringArg("--color")).option("--color-temp <kelvin>", "setColorTemperature: 2700-6500 Kelvin", intArg("--color-temp", { min: 2700, max: 6500 })).option("--yes", "Confirm destructive commands").addHelpText("after", `
 Translates semantic flags into the wire parameter format, then sends the command.
 
 Supported expansions:
@@ -32609,12 +32986,25 @@ Supported expansions:
     --channel 1 --mode edge  \u2192  "1;1"
     --mode values: toggle (0) | edge (1) | detached (2) | momentary (3)
 
+  Color Bulb / Strip Light / Ceiling Light \u2014 setBrightness
+    --brightness 80  \u2192  "80"
+
+  Color Bulb / Strip Light / Floor Lamp \u2014 setColor
+    --color "255:0:0"  \u2192  "255:0:0"
+    --color "#FF0000"  \u2192  "255:0:0"
+    --color red        \u2192  "255:0:0"
+
+  Color Bulb / Strip Light / Ceiling Light \u2014 setColorTemperature
+    --color-temp 4000  \u2192  "4000"
+
 Examples:
-  $ switchbot devices expand <acId>      setAll       --temp 26 --mode cool --fan low --power on
-  $ switchbot devices expand <curtainId> setPosition  --position 50 --mode silent
-  $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
-  $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
-  $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
+  $ switchbot devices expand <acId>      setAll               --temp 26 --mode cool --fan low --power on
+  $ switchbot devices expand <curtainId> setPosition          --position 50 --mode silent
+  $ switchbot devices expand <blindId>   setPosition          --direction up --angle 50
+  $ switchbot devices expand <relayId>   setMode              --channel 1 --mode edge
+  $ switchbot devices expand <stripId>   setBrightness        --brightness 80
+  $ switchbot devices expand <bulbId>    setColor             --color "#FF0000"
+  $ switchbot devices expand <bulbId>    setColorTemperature  --color-temp 4000
   $ switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 `).action(async (deviceIdArg, commandArg, options) => {
     let deviceId = "";
@@ -32632,12 +33022,22 @@ Examples:
         category: options.nameCategory,
         room: options.nameRoom
       });
-      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode).");
+      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode, setBrightness, setColor, setColorTemperature).");
       command = effectiveCommand;
       const cached2 = getCachedDevice(deviceId);
       const deviceType = cached2?.type ?? "";
       let parameter;
       if (command === "setAll") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this is an Air Conditioner.`
+          );
+        }
+        if (deviceType !== "Air Conditioner") {
+          throw new UsageError(
+            `"setAll" is only supported on Air Conditioner devices, but "${cached2.type}" was found.`
+          );
+        }
         parameter = buildAcSetAll(options);
       } else if (command === "setPosition") {
         if (!cached2) {
@@ -32645,13 +33045,56 @@ Examples:
             `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' knows whether this is a Curtain or a Blind Tilt.`
           );
         }
+        const positionTypes = ["Curtain", "Curtain 3", "Roller Shade", "Blind Tilt"];
+        if (!positionTypes.some((t) => deviceType.startsWith(t))) {
+          throw new UsageError(
+            `"setPosition" is only supported on Curtain, Roller Shade, and Blind Tilt devices, but "${cached2.type}" was found.`
+          );
+        }
         const isBlind = deviceType.startsWith("Blind Tilt");
-        parameter = isBlind ? buildBlindTiltSetPosition(options) : buildCurtainSetPosition(options);
+        const isRollerShade = deviceType.startsWith("Roller Shade");
+        if (isBlind) {
+          parameter = buildBlindTiltSetPosition(options);
+        } else if (isRollerShade) {
+          if (!options.position) throw new UsageError("--position is required (0-100)");
+          parameter = options.position;
+        } else {
+          parameter = buildCurtainSetPosition(options);
+        }
       } else if (command === "setMode" && deviceType.startsWith("Relay Switch")) {
         parameter = buildRelaySetMode(options);
+      } else if (command === "setBrightness" || command === "setColor" || command === "setColorTemperature") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device "${deviceId}" is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this device supports ${command}.`
+          );
+        }
+        const catalogResult = findCatalogEntry(cached2.type);
+        const catalogEntry = Array.isArray(catalogResult) ? catalogResult[0] : catalogResult;
+        const supportedHint = command === "setColor" ? "Color Bulb, Strip Light, Floor Lamp, and similar RGB lighting devices" : "Color Bulb, Strip Light, Ceiling Light, Floor Lamp, and similar lighting devices";
+        if (catalogEntry !== null) {
+          if (!catalogEntry.commands.some((c) => c.command === command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        } else {
+          if (!isLightingCommandSupported(cached2.type, command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        }
+        if (command === "setBrightness") {
+          parameter = buildBrightnessSet(options);
+        } else if (command === "setColor") {
+          parameter = buildColorSet(options);
+        } else {
+          parameter = buildColorTemperatureSet(options);
+        }
       } else {
         throw new UsageError(
-          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Use 'switchbot devices command' to send raw parameters instead.`
+          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Supported: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch), setBrightness/setColor/setColorTemperature (lighting). Use 'switchbot devices command' to send raw parameters instead.`
         );
       }
       if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, "command")) {
@@ -33064,7 +33507,7 @@ Examples:
         const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
         const fetchedAt2 = (/* @__PURE__ */ new Date()).toISOString();
         const batch = results.map(
-          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
+          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
         );
         const batchFmt = resolveFormat();
         if (isJsonMode() || batchFmt === "json") {
@@ -33076,7 +33519,7 @@ Examples:
         } else {
           const rawFields = resolveFields();
           for (const entry of batch) {
-            const { deviceId: deviceId2, ok, error: error48, _fetchedAt: ts, ...status } = entry;
+            const { deviceId: deviceId2, ok, error: error48, fetchedAt: ts, ...status } = entry;
             console.log(`
 \u2500\u2500\u2500 ${String(deviceId2)} \u2500\u2500\u2500`);
             if (!ok) {
@@ -33102,11 +33545,11 @@ Examples:
       const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
       const fmt = resolveFormat();
       if (fmt === "json" && process.argv.includes("--json")) {
-        printJson({ ...body, _fetchedAt: fetchedAt });
+        printJson({ ...body, fetchedAt });
         return;
       }
       if (fmt !== "table") {
-        const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+        const statusWithTs = { ...body, fetchedAt };
         const allHeaders = Object.keys(statusWithTs);
         const allRows = [Object.values(statusWithTs)];
         const rawFields = resolveFields();
@@ -33435,7 +33878,7 @@ Examples:
       const joinedMatch = findCatalogEntry(joined);
       if (joinedMatch && !Array.isArray(joinedMatch)) {
         if (isJsonMode()) {
-          printJson(normalizeCatalogForJson(joinedMatch));
+          printJson([normalizeCatalogForJson(joinedMatch)]);
         } else {
           renderCatalogEntry(joinedMatch);
         }
@@ -35224,10 +35667,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema2) {
   return mergeDefs(schema2._zod.def);
 }
-function getElementAtPath(obj, path28) {
-  if (!path28)
+function getElementAtPath(obj, path29) {
+  if (!path29)
     return obj;
-  return path28.reduce((acc, key) => acc?.[key], obj);
+  return path29.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -35610,11 +36053,11 @@ function aborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path28, issues) {
+function prefixIssues(path29, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path28);
+    iss.path.unshift(path29);
     return iss;
   });
 }
@@ -35797,7 +36240,7 @@ function formatError2(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path28 = []) => {
+  const processError = (error49, path29 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -35807,7 +36250,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path28, ...issue2.path];
+        const fullpath = [...path29, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -35839,8 +36282,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path28 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path28) {
+  const path29 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path29) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -47895,13 +48338,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path28 = ref.slice(1).split("/").filter(Boolean);
-  if (path28.length === 0) {
+  const path29 = ref.slice(1).split("/").filter(Boolean);
+  if (path29.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path28[0] === defsKey) {
-    const key = path28[1];
+  if (path29[0] === defsKey) {
+    const key = path29[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -48334,9 +48777,9 @@ var logLevel = process.env.LOG_LEVEL || "warn";
 var logFormat = process.env.LOG_FORMAT || "json";
 var pinoConfig = {
   level: logLevel,
-  transport: logFormat === "pretty" ? { target: "pino-pretty" } : void 0
+  transport: logFormat === "pretty" ? { target: "pino-pretty", options: { destination: 2 } } : void 0
 };
-var log = pino(pinoConfig);
+var log = logFormat === "pretty" ? pino(pinoConfig) : pino(pinoConfig, pino.destination(2));
 
 // src/mcp/device-history.ts
 init_cjs_shim();
@@ -50027,6 +50470,282 @@ function addRuleToPolicyFile(opts) {
   return { ...result, written: false };
 }
 
+// src/rules/explain.ts
+init_cjs_shim();
+init_trace();
+import fs16 from "node:fs";
+function loadTraceRecords(auditFile, opts = {}) {
+  if (!fs16.existsSync(auditFile)) return [];
+  const lines = fs16.readFileSync(auditFile, "utf-8").split(/\r?\n/);
+  return filterTraceRecords(lines, opts);
+}
+function loadRelatedAudit(auditFile, fireId) {
+  if (!fs16.existsSync(auditFile)) return [];
+  const raw = fs16.readFileSync(auditFile, "utf-8");
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const entry = JSON.parse(trimmed);
+      const entryFireId = entry.rule?.fireId ?? entry["fireId"];
+      if (entryFireId === fireId) out.push(entry);
+    } catch {
+    }
+  }
+  return out;
+}
+function conditionSymbol(passed) {
+  if (passed === true) return "\u2713";
+  if (passed === false) return "\u2717";
+  return "\xB7";
+}
+function conditionSummary(c) {
+  if (c.passed === null) {
+    return `\xB7 ${c.kind} \u2192 not evaluated (short-circuited)`;
+  }
+  const sym = conditionSymbol(c.passed);
+  let detail = c.kind;
+  if (c.config !== void 0) {
+    if (Array.isArray(c.config)) {
+      detail += ` ${c.config.join("\u2013")}`;
+    } else if (c.config && typeof c.config === "object") {
+      const cfg = c.config;
+      if ("device" in cfg) {
+        detail += ` ${cfg["device"]}.${cfg["field"]} ${cfg["op"]} ${JSON.stringify(cfg["value"])}`;
+      }
+    }
+  }
+  const status = c.passed ? "passed" : "failed";
+  return `  ${sym} ${detail.padEnd(36)} \u2192 ${status}`;
+}
+function formatTimestamp(iso) {
+  const d = new Date(iso);
+  return `${d.toISOString().slice(0, 10)} ${d.toISOString().slice(11, 19)}`;
+}
+function formatExplainText(record2, relatedAudit) {
+  const lines = [];
+  lines.push(`Rule: ${record2.rule.name}  (version ${record2.rule.version})`);
+  lines.push(`Evaluated: ${formatTimestamp(record2.t)} (${record2.evaluationMs}ms)`);
+  const triggerDevice = record2.trigger.deviceId ? ` on ${record2.trigger.deviceId}` : "";
+  lines.push(`Trigger: ${record2.trigger.source} ${record2.trigger.event}${triggerDevice}`);
+  lines.push("");
+  if (record2.conditions.length > 0) {
+    lines.push("Conditions (evaluated in order):");
+    for (const c of record2.conditions) {
+      lines.push(conditionSummary(c));
+    }
+    lines.push("");
+  }
+  lines.push(`Decision: ${record2.decision}`);
+  lines.push("");
+  lines.push(`Related fireId: ${record2.fireId}`);
+  const nonEval = relatedAudit.filter(
+    (e) => e["kind"] !== "rule-evaluate"
+  );
+  if (nonEval.length > 0) {
+    lines.push(`Audit trail (${nonEval.length} record${nonEval.length === 1 ? "" : "s"}):`);
+    for (const e of nonEval) {
+      const ts = formatTimestamp(e.t);
+      lines.push(`  ${e.kind.padEnd(20)} ${ts}`);
+    }
+  } else {
+    lines.push(`Audit trail: (no related records${record2.decision === "blocked-by-condition" ? " \u2014 rule did not fire" : ""})`);
+  }
+  return lines.join("\n");
+}
+function formatExplainJson(record2, relatedAudit) {
+  return JSON.stringify({ trace: record2, relatedAudit }, null, 2);
+}
+
+// src/rules/simulate.ts
+init_cjs_shim();
+init_matcher();
+init_throttle();
+init_trace();
+init_trace();
+init_matcher();
+import fs17 from "node:fs";
+import path14 from "node:path";
+import os13 from "node:os";
+import { randomUUID as randomUUID5 } from "node:crypto";
+var HOUR_MS = 60 * 60 * 1e3;
+var DEVICE_HISTORY_DIR = path14.join(os13.homedir(), ".switchbot", "device-history");
+async function simulateRule(opts) {
+  const { rule, aliases = {}, liveLlm = false } = opts;
+  const rv = ruleVersion(rule);
+  const events = loadSourceEvents(opts);
+  const windowStart = events.length > 0 ? new Date(Math.min(...events.map((e) => e.t.getTime()))) : new Date(Date.now() - 24 * HOUR_MS);
+  const windowEnd = events.length > 0 ? new Date(Math.max(...events.map((e) => e.t.getTime()))) : /* @__PURE__ */ new Date();
+  const counts = { wouldFire: 0, blocked: 0, throttled: 0, errored: 0, skippedLlm: 0 };
+  const blockReasons = /* @__PURE__ */ new Map();
+  const sampleFires = [];
+  const traces = [];
+  const throttle = new ThrottleGate();
+  const cooldownMs = rule.cooldown ? parseMaxPerMs(rule.cooldown) : null;
+  const throttleMs = rule.throttle ? parseMaxPerMs(rule.throttle.max_per) : null;
+  const effectiveWindowMs = cooldownMs ?? throttleMs;
+  for (const event of events) {
+    const fireId = randomUUID5();
+    const nowMs = event.t.getTime();
+    if (rule.when.source === "mqtt") {
+      const resolvedDevice = rule.when.device ? aliases[rule.when.device] ?? rule.when.device : void 0;
+      if (!matchesMqttTrigger(rule.when, event, resolvedDevice)) continue;
+    }
+    const hasLlm = (rule.conditions ?? []).some((c) => c["llm"] !== void 0);
+    if (hasLlm && !liveLlm) {
+      counts.skippedLlm++;
+      const fireEvent = {
+        t: event.t.toISOString(),
+        fireId,
+        deviceId: event.deviceId,
+        decision: "skipped-llm"
+      };
+      sampleFires.push(fireEvent);
+      continue;
+    }
+    if (effectiveWindowMs !== null) {
+      const check2 = throttle.check(rule.name, effectiveWindowMs, nowMs, event.deviceId);
+      if (!check2.allowed) {
+        counts.throttled++;
+        const fireEvent = {
+          t: event.t.toISOString(),
+          fireId,
+          deviceId: event.deviceId,
+          decision: "throttled"
+        };
+        sampleFires.push(fireEvent);
+        continue;
+      }
+    }
+    const statusFetcher = buildStatusFetcher(event.t);
+    let condResult;
+    try {
+      condResult = await evaluateConditions(rule.conditions, event.t, {
+        aliases,
+        fetchStatus: statusFetcher,
+        event,
+        ruleVersion: rv
+      });
+    } catch (err) {
+      counts.errored++;
+      sampleFires.push({ t: event.t.toISOString(), fireId, deviceId: event.deviceId, decision: "error", reason: String(err) });
+      continue;
+    }
+    if (!condResult.matched) {
+      counts.blocked++;
+      const reason = condResult.failures[0] ?? "unknown";
+      blockReasons.set(reason, (blockReasons.get(reason) ?? 0) + 1);
+      sampleFires.push({ t: event.t.toISOString(), fireId, deviceId: event.deviceId, decision: "blocked-by-condition", reason });
+    } else {
+      counts.wouldFire++;
+      throttle.record(rule.name, nowMs, event.deviceId);
+      sampleFires.push({ t: event.t.toISOString(), fireId, deviceId: event.deviceId, decision: "would-fire" });
+    }
+  }
+  let topBlockReason;
+  let topBlockCount;
+  if (blockReasons.size > 0) {
+    let max = 0;
+    for (const [reason, count] of blockReasons) {
+      if (count > max) {
+        max = count;
+        topBlockReason = reason;
+        topBlockCount = count;
+      }
+    }
+  }
+  return {
+    ruleName: rule.name,
+    ruleVersion: rv,
+    windowStart,
+    windowEnd,
+    sourceEventCount: events.length,
+    wouldFire: counts.wouldFire,
+    blockedByCondition: counts.blocked,
+    throttled: counts.throttled,
+    errored: counts.errored,
+    skippedLlm: counts.skippedLlm,
+    topBlockReason,
+    topBlockCount,
+    sampleFires: sampleFires.slice(0, 20),
+    traces
+  };
+}
+function loadSourceEvents(opts) {
+  if (opts.against) {
+    if (!fs17.existsSync(opts.against)) return [];
+    const lines2 = fs17.readFileSync(opts.against, "utf-8").split(/\r?\n/);
+    const events = [];
+    for (const line of lines2) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const raw = JSON.parse(trimmed);
+        events.push({
+          source: raw["source"] ?? "mqtt",
+          event: String(raw["event"] ?? "device.shadow"),
+          t: new Date(String(raw["t"] ?? (/* @__PURE__ */ new Date()).toISOString())),
+          deviceId: raw["deviceId"],
+          payload: raw["payload"]
+        });
+      } catch {
+      }
+    }
+    return events;
+  }
+  const auditLog = opts.auditLog;
+  if (!auditLog || !fs17.existsSync(auditLog)) return [];
+  const sinceMs = opts.since ? parseSince(opts.since) : Date.now() - 24 * HOUR_MS;
+  const sinceIso = new Date(sinceMs).toISOString();
+  const lines = fs17.readFileSync(auditLog, "utf-8").split(/\r?\n/);
+  const traceRecords = filterTraceRecords(lines, {
+    ruleName: opts.rule.name,
+    since: sinceIso
+  });
+  return traceRecords.map((r) => ({
+    source: r.trigger.source,
+    event: r.trigger.event,
+    t: new Date(r.t),
+    deviceId: r.trigger.deviceId
+  }));
+}
+function parseSince(since) {
+  if (since.includes("T") || since.includes("-")) {
+    const d = new Date(since);
+    if (!isNaN(d.getTime())) return d.getTime();
+  }
+  const m2 = /^(\d+)([smhd])$/.exec(since.trim());
+  if (m2) {
+    const n = parseInt(m2[1], 10);
+    const unit = m2[2];
+    const unitMs = unit === "s" ? 1e3 : unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5;
+    return Date.now() - n * unitMs;
+  }
+  return Date.now() - 24 * HOUR_MS;
+}
+function buildStatusFetcher(asOf) {
+  return async (deviceId) => {
+    const histFile = path14.join(DEVICE_HISTORY_DIR, `${deviceId}.jsonl`);
+    if (!fs17.existsSync(histFile)) return {};
+    const lines = fs17.readFileSync(histFile, "utf-8").split(/\r?\n/);
+    const asOfMs = asOf.getTime();
+    let best;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const entry = JSON.parse(trimmed);
+        const entryT = new Date(String(entry["t"] ?? 0)).getTime();
+        if (entryT <= asOfMs) best = entry;
+        else break;
+      } catch {
+      }
+    }
+    return best ?? {};
+  };
+}
+
 // src/commands/mcp.ts
 init_audit();
 init_flags();
@@ -50045,13 +50764,13 @@ function collectPolicyDiff(left, right, at, out, limit) {
     const maxLen = Math.max(left.length, right.length);
     for (let i = 0; i < maxLen; i++) {
       if (out.length >= limit) return;
-      const path28 = `${at}[${i}]`;
+      const path29 = `${at}[${i}]`;
       if (i >= left.length) {
-        out.push({ path: path28, kind: "added", after: right[i] });
+        out.push({ path: path29, kind: "added", after: right[i] });
       } else if (i >= right.length) {
-        out.push({ path: path28, kind: "removed", before: left[i] });
+        out.push({ path: path29, kind: "removed", before: left[i] });
       } else {
-        collectPolicyDiff(left[i], right[i], path28, out, limit);
+        collectPolicyDiff(left[i], right[i], path29, out, limit);
       }
     }
     return;
@@ -50060,15 +50779,15 @@ function collectPolicyDiff(left, right, at, out, limit) {
     const keys = /* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)]);
     for (const key of [...keys].sort()) {
       if (out.length >= limit) return;
-      const path28 = at === "$" ? `$.${key}` : `${at}.${key}`;
+      const path29 = at === "$" ? `$.${key}` : `${at}.${key}`;
       const leftHas = Object.prototype.hasOwnProperty.call(left, key);
       const rightHas = Object.prototype.hasOwnProperty.call(right, key);
       if (!leftHas && rightHas) {
-        out.push({ path: path28, kind: "added", after: right[key] });
+        out.push({ path: path29, kind: "added", after: right[key] });
       } else if (leftHas && !rightHas) {
-        out.push({ path: path28, kind: "removed", before: left[key] });
+        out.push({ path: path29, kind: "removed", before: left[key] });
       } else {
-        collectPolicyDiff(left[key], right[key], path28, out, limit);
+        collectPolicyDiff(left[key], right[key], path29, out, limit);
       }
     }
     return;
@@ -50121,8 +50840,8 @@ function diffPolicyValues(leftDoc, rightDoc, leftSource, rightSource, maxChanges
 // src/commands/mcp.ts
 init_embedded_assets();
 import { dirname as pathDirname, join as pathJoin } from "node:path";
-import os13 from "node:os";
-import fs16 from "node:fs";
+import os14 from "node:os";
+import fs18 from "node:fs";
 var LATEST_SUPPORTED_VERSION = SUPPORTED_POLICY_SCHEMA_VERSIONS[SUPPORTED_POLICY_SCHEMA_VERSIONS.length - 1];
 function mcpError(kind, code, message, options) {
   const obj = { code, kind, message };
@@ -50151,7 +50870,7 @@ function apiErrorToMcpError(err) {
     retryAfterMs: payload.retryAfterMs
   });
 }
-var DEFAULT_AUDIT_LOG_FILE = pathJoin(os13.homedir(), ".switchbot", "audit.log");
+var DEFAULT_AUDIT_LOG_FILE = pathJoin(os14.homedir(), ".switchbot", "audit.log");
 function resolveAuditRange(opts) {
   if (opts.since && (opts.from || opts.to)) {
     throw new Error("--since is mutually exclusive with --from/--to.");
@@ -51080,15 +51799,15 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
     async ({ path: pathArg, force }) => {
       const policyPath = resolvePolicyPath({ flag: pathArg });
       const doForce = force === true;
-      if (fs16.existsSync(policyPath) && !doForce) {
+      if (fs18.existsSync(policyPath) && !doForce) {
         return mcpError("guard", 5, `refusing to overwrite existing policy at ${policyPath}`, {
           hint: "pass force=true to overwrite, or choose a different path",
           context: { policyPath }
         });
       }
       const template = readPolicyExampleYaml();
-      fs16.mkdirSync(pathDirname(policyPath), { recursive: true });
-      fs16.writeFileSync(policyPath, template, { encoding: "utf-8" });
+      fs18.mkdirSync(pathDirname(policyPath), { recursive: true });
+      fs18.writeFileSync(policyPath, template, { encoding: "utf-8" });
       const structured = {
         policyPath,
         schemaVersion: CURRENT_POLICY_SCHEMA_VERSION,
@@ -51275,7 +51994,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
       let leftSource = "";
       let rightSource = "";
       try {
-        leftSource = fs16.readFileSync(left_path, "utf-8");
+        leftSource = fs18.readFileSync(left_path, "utf-8");
       } catch (err) {
         if (err?.code === "ENOENT") {
           return mcpError("usage", 2, `policy file not found: ${left_path}`, {
@@ -51285,7 +52004,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
         return mcpError("runtime", 1, `failed to read ${left_path}: ${String(err)}`);
       }
       try {
-        rightSource = fs16.readFileSync(right_path, "utf-8");
+        rightSource = fs18.readFileSync(right_path, "utf-8");
       } catch (err) {
         if (err?.code === "ENOENT") {
           return mcpError("usage", 2, `policy file not found: ${right_path}`, {
@@ -51725,6 +52444,130 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
       }
     }
   );
+  server.registerTool(
+    "rules_explain",
+    {
+      title: "Show why a rule evaluation fired or was blocked",
+      description: 'Read rule-evaluate trace records from the audit log and format them for inspection. Pass fire_id to explain a specific evaluation; or pass rule_name with last:true for the most recent evaluation; or pass rule_name + since for a window. Returns trace records only when automation.audit.evaluate_trace is "sampled" or "full".',
+      _meta: { agentSafetyTier: "read" },
+      inputSchema: external_exports.object({
+        fire_id: external_exports.string().optional().describe("Specific fireId to explain."),
+        rule_name: external_exports.string().optional().describe("Filter to this rule name."),
+        since: external_exports.string().optional().describe("Duration string (e.g. 1h, 7d) \u2014 show evaluations in this window."),
+        last: external_exports.boolean().optional().describe("Return only the most recent evaluation (requires rule_name)."),
+        audit_log: external_exports.string().optional().describe(`Audit log path (default: ${pathJoin(os14.homedir(), ".switchbot", "audit.log")}).`)
+      }).strict(),
+      outputSchema: {
+        records: external_exports.array(external_exports.unknown()).describe("Array of trace + relatedAudit objects."),
+        count: external_exports.number().describe("Number of trace records returned.")
+      }
+    },
+    async ({ fire_id, rule_name, since, last, audit_log }) => {
+      const DEFAULT_AUDIT_PATH4 = pathJoin(os14.homedir(), ".switchbot", "audit.log");
+      const auditFile = audit_log ?? DEFAULT_AUDIT_PATH4;
+      const sinceIso = since ? new Date(Date.now() - (parseDurationToMs(since) ?? 0)).toISOString() : void 0;
+      let records = loadTraceRecords(auditFile, {
+        fireId: fire_id,
+        ruleName: rule_name,
+        since: sinceIso
+      });
+      if (records.length === 0) {
+        return {
+          content: [{ type: "text", text: 'No rule-evaluate trace records found. Check that automation.audit.evaluate_trace is "sampled" or "full".' }],
+          structuredContent: { records: [], count: 0 }
+        };
+      }
+      if (last) {
+        records = [records[records.length - 1]];
+      }
+      const output = records.map((record2) => {
+        const related = loadRelatedAudit(auditFile, record2.fireId);
+        return JSON.parse(formatExplainJson(record2, related));
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        structuredContent: { records: output, count: output.length }
+      };
+    }
+  );
+  server.registerTool(
+    "rules_simulate",
+    {
+      title: "Simulate a rule against historical events",
+      description: "Replay historical events from the audit log or a JSONL file against a rule definition and report would-fire / blocked-by-condition / throttled outcomes. Useful for validating a new or modified rule before deployment. Pass rule_yaml to test an unpublished rule, or rule_name + policy_path to test a deployed rule.",
+      _meta: { agentSafetyTier: "read" },
+      inputSchema: external_exports.object({
+        rule_yaml: external_exports.string().optional().describe("Standalone rule YAML (takes precedence over policy_path + rule_name)."),
+        policy_path: external_exports.string().optional().describe("Path to policy.yaml (defaults to ~/.switchbot/policy.yaml)."),
+        rule_name: external_exports.string().optional().describe("Name of the rule in policy.yaml to simulate."),
+        since: external_exports.string().optional().describe("Replay events from this window (e.g. 7d, 24h)."),
+        against: external_exports.string().optional().describe("JSONL file path of EngineEvent objects to replay."),
+        live_llm: external_exports.boolean().optional().describe("Allow live LLM calls for llm conditions (default: skip and report as would-call)."),
+        audit_log: external_exports.string().optional().describe(`Audit log path (default: ${pathJoin(os14.homedir(), ".switchbot", "audit.log")}).`)
+      }).strict(),
+      outputSchema: {
+        report: external_exports.unknown().describe("SimulateReport object.")
+      }
+    },
+    async ({ rule_yaml, policy_path, rule_name, since, against, live_llm, audit_log }) => {
+      const DEFAULT_AUDIT_PATH4 = pathJoin(os14.homedir(), ".switchbot", "audit.log");
+      const auditFile = audit_log ?? DEFAULT_AUDIT_PATH4;
+      let rule;
+      if (rule_yaml) {
+        try {
+          rule = (0, import_yaml7.parse)(rule_yaml);
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to parse rule_yaml: ${String(err)}` }],
+            structuredContent: { report: null }
+          };
+        }
+      } else if (policy_path || rule_name) {
+        const { loadPolicyFile: loadPolicyFile2 } = await Promise.resolve().then(() => (init_load(), load_exports));
+        const policyFile = policy_path ?? pathJoin(os14.homedir(), ".switchbot", "policy.yaml");
+        try {
+          const policy = loadPolicyFile2(policyFile);
+          const data = policy.data ?? {};
+          const found = data.automation?.rules?.find((r) => r.name === rule_name);
+          if (!found) {
+            return {
+              content: [{ type: "text", text: `Rule "${rule_name}" not found in ${policyFile}.` }],
+              structuredContent: { report: null }
+            };
+          }
+          rule = found;
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to load policy: ${String(err)}` }],
+            structuredContent: { report: null }
+          };
+        }
+      } else {
+        return {
+          content: [{ type: "text", text: "Provide rule_yaml or (policy_path + rule_name) to specify the rule to simulate." }],
+          structuredContent: { report: null }
+        };
+      }
+      try {
+        const report = await simulateRule({
+          rule,
+          since,
+          against,
+          auditLog: auditFile,
+          liveLlm: live_llm ?? false
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+          structuredContent: { report }
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Simulate error: ${String(err)}` }],
+          structuredContent: { report: null }
+        };
+      }
+    }
+  );
   server.registerTool(
     "policy_add_rule",
     {
@@ -51775,12 +52618,27 @@ function listRegisteredTools(server) {
   if (!internal._registeredTools) return [];
   return Object.keys(internal._registeredTools).sort();
 }
+function listRegisteredToolsWithMeta(server) {
+  const internal = server;
+  if (!internal._registeredTools) return [];
+  return Object.entries(internal._registeredTools).sort(([a], [b2]) => a.localeCompare(b2)).map(([name, reg]) => {
+    const entry = { name };
+    if (reg.description) entry.description = reg.description;
+    if (reg.inputSchema) {
+      try {
+        entry.inputSchema = external_exports.toJSONSchema(reg.inputSchema);
+      } catch {
+      }
+    }
+    return entry;
+  });
+}
 function listRegisteredResources() {
   return ["switchbot://events"];
 }
 function printMcpToolDirectory() {
   const server = createSwitchBotMcpServer();
-  const tools = listRegisteredTools(server).map((name) => ({ name }));
+  const tools = listRegisteredToolsWithMeta(server);
   const resources = listRegisteredResources().map((uri) => ({ uri }));
   if (isJsonMode()) {
     printJson({ tools, resources });
@@ -51788,7 +52646,8 @@ function printMcpToolDirectory() {
   }
   console.log("Tools:");
   for (const tool of tools) {
-    console.log(`  ${tool.name}`);
+    const desc = tool.description ? ` \u2014 ${tool.description.slice(0, 80)}` : "";
+    console.log(`  ${tool.name}${desc}`);
   }
   console.log("");
   console.log("Resources:");
@@ -51800,7 +52659,7 @@ Total: ${tools.length} tool(s), ${resources.length} resource(s)`);
 }
 function registerMcpCommand(program3) {
   const mcp = program3.command("mcp").description("Run as a Model Context Protocol server so AI agents can call SwitchBot tools").addHelpText("after", `
-  The MCP server exposes twenty-one tools:
+  The MCP server exposes twenty-four tools:
   - list_devices            fetch all physical + IR devices
   - get_device_status       live status for a physical device
   - send_command            control a device (destructive commands need confirm:true)
@@ -51823,6 +52682,8 @@ function registerMcpCommand(program3) {
   - audit_stats             aggregate audit counts by kind/result/device/rule
   - rule_notifications      query rule notify action delivery history
   - rules_suggest           draft an automation rule YAML from intent (heuristic, no LLM)
+  - rules_explain           show why a rule evaluation fired or was blocked
+  - rules_simulate          simulate a rule against historical events
   - policy_add_rule         append a rule into automation.rules[] in policy.yaml
 
 Resource (read-only):
@@ -51995,7 +52856,7 @@ process_uptime_seconds ${Math.floor(process.uptime())}
           }
           if (profile) {
             const envCredsPresent = !!(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
-            if (!envCredsPresent && !fs16.existsSync(profileFilePath(profile))) {
+            if (!envCredsPresent && !fs18.existsSync(profileFilePath(profile))) {
               res.writeHead(401, { "Content-Type": "application/json" });
               res.end(JSON.stringify({
                 jsonrpc: "2.0",
@@ -52265,7 +53126,7 @@ Examples:
           throw new UsageError(`"${match.type}" exists in the effective catalog but not in source "${source}".`);
         }
         if (isJsonMode()) {
-          printJson(picked);
+          printJson([picked]);
           return;
         }
         renderEntry(picked);
@@ -52631,18 +53492,18 @@ var StdoutSink = class {
 
 // src/sinks/file.ts
 init_cjs_shim();
-import fs17 from "node:fs";
-import path14 from "node:path";
+import fs19 from "node:fs";
+import path15 from "node:path";
 var FileSink = class {
   filePath;
   constructor(filePath) {
-    this.filePath = path14.resolve(filePath);
-    const dir = path14.dirname(this.filePath);
-    if (!fs17.existsSync(dir)) fs17.mkdirSync(dir, { recursive: true });
+    this.filePath = path15.resolve(filePath);
+    const dir = path15.dirname(this.filePath);
+    if (!fs19.existsSync(dir)) fs19.mkdirSync(dir, { recursive: true });
   }
   async write(event) {
     try {
-      fs17.appendFileSync(this.filePath, JSON.stringify(event) + "\n", { encoding: "utf-8" });
+      fs19.appendFileSync(this.filePath, JSON.stringify(event) + "\n", { encoding: "utf-8" });
     } catch {
     }
   }
@@ -53007,7 +53868,7 @@ Examples:
       let matchedCount = 0;
       const ac = new AbortController();
       const forTimer = forMs !== null && forMs > 0 ? setTimeout(() => ac.abort(), forMs) : null;
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       await new Promise((resolve2, reject) => {
         let server = null;
         try {
@@ -53159,7 +54020,7 @@ Examples:
       if (!isJsonMode()) {
         console.error("Fetching MQTT credentials from SwitchBot service\u2026");
       }
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       if (isJsonMode()) {
         const sessionStartAt = (/* @__PURE__ */ new Date()).toISOString();
         emitJsonStreamRecord({
@@ -53311,9 +54172,9 @@ init_catalog();
 init_config();
 init_cache();
 init_quota();
-import fs20 from "node:fs";
-import os16 from "node:os";
-import path17 from "node:path";
+import fs22 from "node:fs";
+import os17 from "node:os";
+import path18 from "node:path";
 import { execSync } from "node:child_process";
 
 // src/commands/agent-bootstrap.ts
@@ -53549,38 +54410,38 @@ init_request_context();
 
 // src/lib/daemon-state.ts
 init_cjs_shim();
-import fs18 from "node:fs";
-import os14 from "node:os";
-import path15 from "node:path";
+import fs20 from "node:fs";
+import os15 from "node:os";
+import path16 from "node:path";
 function getStateDir() {
-  return path15.join(os14.homedir(), ".switchbot");
+  return path16.join(os15.homedir(), ".switchbot");
 }
 function getDaemonPidFile() {
-  return path15.join(getStateDir(), "daemon.pid");
+  return path16.join(getStateDir(), "daemon.pid");
 }
 function getDaemonLogFile() {
-  return path15.join(getStateDir(), "daemon.log");
+  return path16.join(getStateDir(), "daemon.log");
 }
 function getDaemonStateFile() {
-  return path15.join(getStateDir(), "daemon.state.json");
+  return path16.join(getStateDir(), "daemon.state.json");
 }
 function getHealthzPidFile() {
-  return path15.join(getStateDir(), "healthz.pid");
+  return path16.join(getStateDir(), "healthz.pid");
 }
 var DAEMON_PID_FILE = getDaemonPidFile();
 var DAEMON_LOG_FILE = getDaemonLogFile();
 var DAEMON_STATE_FILE = getDaemonStateFile();
 var HEALTHZ_PID_FILE = getHealthzPidFile();
 function ensureStateDir() {
-  fs18.mkdirSync(getStateDir(), { recursive: true, mode: 448 });
+  fs20.mkdirSync(getStateDir(), { recursive: true, mode: 448 });
 }
 function writeDaemonState(state) {
   ensureStateDir();
-  fs18.writeFileSync(getDaemonStateFile(), JSON.stringify(state, null, 2), { mode: 384 });
+  fs20.writeFileSync(getDaemonStateFile(), JSON.stringify(state, null, 2), { mode: 384 });
 }
 function readDaemonState() {
   try {
-    const raw = fs18.readFileSync(getDaemonStateFile(), "utf-8");
+    const raw = fs20.readFileSync(getDaemonStateFile(), "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -53589,26 +54450,26 @@ function readDaemonState() {
 
 // src/rules/pid-file.ts
 init_cjs_shim();
-import fs19 from "node:fs";
-import os15 from "node:os";
-import path16 from "node:path";
-var DEFAULT_DIR = path16.join(os15.homedir(), ".switchbot");
+import fs21 from "node:fs";
+import os16 from "node:os";
+import path17 from "node:path";
+var DEFAULT_DIR = path17.join(os16.homedir(), ".switchbot");
 function getDefaultPidFilePaths() {
   return {
     dir: DEFAULT_DIR,
-    pidFile: path16.join(DEFAULT_DIR, "rules.pid"),
-    reloadFile: path16.join(DEFAULT_DIR, "rules.reload")
+    pidFile: path17.join(DEFAULT_DIR, "rules.pid"),
+    reloadFile: path17.join(DEFAULT_DIR, "rules.reload")
   };
 }
 function writePidFile(pidFile, pid = process.pid) {
-  const dir = path16.dirname(pidFile);
-  fs19.mkdirSync(dir, { recursive: true, mode: 448 });
-  fs19.writeFileSync(pidFile, `${pid}
+  const dir = path17.dirname(pidFile);
+  fs21.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs21.writeFileSync(pidFile, `${pid}
 `, { mode: 384 });
 }
 function readPidFile(pidFile) {
   try {
-    const raw = fs19.readFileSync(pidFile, "utf-8").trim();
+    const raw = fs21.readFileSync(pidFile, "utf-8").trim();
     const n = Number(raw);
     return Number.isInteger(n) && n > 0 ? n : null;
   } catch {
@@ -53618,20 +54479,20 @@ function readPidFile(pidFile) {
 function clearPidFile(pidFile, pid = process.pid) {
   try {
     const existing = readPidFile(pidFile);
-    if (existing === pid) fs19.unlinkSync(pidFile);
+    if (existing === pid) fs21.unlinkSync(pidFile);
   } catch {
   }
 }
 function writeReloadSentinel(reloadFile) {
-  const dir = path16.dirname(reloadFile);
-  fs19.mkdirSync(dir, { recursive: true, mode: 448 });
-  fs19.writeFileSync(reloadFile, `${Date.now()}
+  const dir = path17.dirname(reloadFile);
+  fs21.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs21.writeFileSync(reloadFile, `${Date.now()}
 `, { mode: 384 });
 }
 function consumeReloadSentinel(reloadFile) {
   try {
-    if (!fs19.existsSync(reloadFile)) return false;
-    fs19.unlinkSync(reloadFile);
+    if (!fs21.existsSync(reloadFile)) return false;
+    fs21.unlinkSync(reloadFile);
     return true;
   } catch {
     return false;
@@ -53702,7 +54563,7 @@ async function checkCredentials() {
     };
   }
   const file2 = configFilePath();
-  if (!fs20.existsSync(file2)) {
+  if (!fs22.existsSync(file2)) {
     return {
       name: "credentials",
       status: "fail",
@@ -53717,7 +54578,7 @@ async function checkCredentials() {
     };
   }
   try {
-    const raw = fs20.readFileSync(file2, "utf-8");
+    const raw = fs22.readFileSync(file2, "utf-8");
     const cfg = JSON.parse(raw);
     if (!cfg.token || !cfg.secret) {
       return {
@@ -53764,8 +54625,8 @@ async function checkCredentials() {
   }
 }
 function checkProfiles() {
-  const dir = path17.join(os16.homedir(), ".switchbot", "profiles");
-  if (!fs20.existsSync(dir)) {
+  const dir = path18.join(os17.homedir(), ".switchbot", "profiles");
+  if (!fs22.existsSync(dir)) {
     return { name: "profiles", status: "ok", detail: "no profile dir (default profile only)" };
   }
   const profiles = listProfiles();
@@ -53872,8 +54733,8 @@ function checkCache() {
   }
 }
 function checkQuotaFile() {
-  const p2 = path17.join(os16.homedir(), ".switchbot", "quota.json");
-  if (!fs20.existsSync(p2)) {
+  const p2 = path18.join(os17.homedir(), ".switchbot", "quota.json");
+  if (!fs22.existsSync(p2)) {
     return {
       name: "quota",
       status: "ok",
@@ -53886,7 +54747,7 @@ function checkQuotaFile() {
     };
   }
   try {
-    const raw = fs20.readFileSync(p2, "utf-8");
+    const raw = fs22.readFileSync(p2, "utf-8");
     JSON.parse(raw);
   } catch {
     return {
@@ -53966,8 +54827,8 @@ function checkInventoryConsistency() {
   };
 }
 function checkAudit() {
-  const p2 = path17.join(os16.homedir(), ".switchbot", "audit.log");
-  if (!fs20.existsSync(p2)) {
+  const p2 = path18.join(os17.homedir(), ".switchbot", "audit.log");
+  if (!fs22.existsSync(p2)) {
     return {
       name: "audit",
       status: "ok",
@@ -53979,7 +54840,7 @@ function checkAudit() {
     };
   }
   try {
-    const raw = fs20.readFileSync(p2, "utf-8");
+    const raw = fs22.readFileSync(p2, "utf-8");
     const since = Date.now() - 24 * 60 * 60 * 1e3;
     const recent = [];
     let total = 0;
@@ -54179,7 +55040,7 @@ function checkPathDiscoverability() {
   let npmBinDir = null;
   try {
     const prefix = execSync("npm prefix -g", { timeout: 4e3, encoding: "utf-8" }).trim();
-    npmBinDir = isWindows ? prefix : path17.join(prefix, "bin");
+    npmBinDir = isWindows ? prefix : path18.join(prefix, "bin");
   } catch {
   }
   let binaryOnPath = false;
@@ -54209,7 +55070,7 @@ function checkPathDiscoverability() {
     };
   }
   const currentPath = process.env.PATH ?? "";
-  const missingSegment = npmBinDir && !currentPath.split(path17.delimiter).includes(npmBinDir) ? npmBinDir : null;
+  const missingSegment = npmBinDir && !currentPath.split(path18.delimiter).includes(npmBinDir) ? npmBinDir : null;
   const currentShell = detectShellFlavor();
   const shellFix = buildPathFix(currentShell, missingSegment, npmBinDir);
   return {
@@ -54310,9 +55171,9 @@ function checkMqtt() {
     };
   }
   const file2 = configFilePath();
-  if (fs20.existsSync(file2)) {
+  if (fs22.existsSync(file2)) {
     try {
-      const cfg = JSON.parse(fs20.readFileSync(file2, "utf-8"));
+      const cfg = JSON.parse(fs22.readFileSync(file2, "utf-8"));
       if (cfg.token && cfg.secret) {
         return {
           name: "mqtt",
@@ -54339,9 +55200,9 @@ async function checkMqttProbe() {
     creds = { token, secret };
   } else {
     const file2 = configFilePath();
-    if (fs20.existsSync(file2)) {
+    if (fs22.existsSync(file2)) {
       try {
-        const cfg = JSON.parse(fs20.readFileSync(file2, "utf-8"));
+        const cfg = JSON.parse(fs22.readFileSync(file2, "utf-8"));
         if (cfg.token && cfg.secret) {
           creds = { token: cfg.token, secret: cfg.secret };
         }
@@ -54435,10 +55296,12 @@ function checkNotifyConnectivity() {
     return { name: "notify-connectivity", status: "ok", detail: { present: false, message: "policy file could not be loaded" } };
   }
   const policy = loaded.data;
-  const rules = policy?.automation?.rules ?? [];
+  const rawRules = policy?.automation?.rules;
+  const rules = Array.isArray(rawRules) ? rawRules : [];
   const webhookUrls = [];
   for (const rule of rules) {
-    for (const action of rule.then ?? []) {
+    const then = rule.then;
+    for (const action of Array.isArray(then) ? then : []) {
       if (action.type === "notify" && (action.channel === "webhook" || action.channel === "openclaw") && action.to) {
         webhookUrls.push(action.to);
       }
@@ -54727,7 +55590,7 @@ function runSchemaExport(options) {
       payload.resources = RESOURCE_CATALOG;
       payload.cliAddedFields = [
         {
-          field: "_fetchedAt",
+          field: "fetchedAt",
           appliesTo: ["devices status", "devices describe"],
           type: "string (ISO-8601)",
           description: "CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API."
@@ -54790,7 +55653,7 @@ Common top-level fields:
   schemaVersion             CLI schema version (stable for agent contracts)
   data.version              Catalog schema version
   data.types                Array of SchemaEntry (or CompactSchemaEntry with --compact)
-  data._fetchedAt           CLI-added; present on live-query responses ('devices status'),
+  data.fetchedAt            CLI-added; present on live-query responses ('devices status'),
                             not on this offline export.
 
 Examples:
@@ -54812,9 +55675,9 @@ init_arg_parsers();
 init_output();
 init_audit();
 init_devices();
-import path18 from "node:path";
-import os17 from "node:os";
-var DEFAULT_AUDIT = path18.join(os17.homedir(), ".switchbot", "audit.log");
+import path19 from "node:path";
+import os18 from "node:os";
+var DEFAULT_AUDIT = path19.join(os18.homedir(), ".switchbot", "audit.log");
 function registerHistoryCommand(program3) {
   const history = program3.command("history").description("View and replay SwitchBot commands recorded via --audit-log").addHelpText("after", `
 Every 'devices command' run with --audit-log is appended as JSONL to the
@@ -55672,9 +56535,9 @@ init_load();
 init_validate();
 init_types();
 init_engine();
-import fs22 from "node:fs";
-import os19 from "node:os";
-import path20 from "node:path";
+import fs24 from "node:fs";
+import os20 from "node:os";
+import path21 from "node:path";
 
 // src/rules/conflict-analyzer.ts
 init_cjs_shim();
@@ -55693,9 +56556,9 @@ var OPPOSING_PAIRS = [
   ["volumeUp", "volumeDown"],
   ["fanSpeedUp", "fanSpeedDown"]
 ];
-var HIGH_FREQ_EVENTS = ["device.shadow", "*"];
+var HIGH_FREQ_EVENTS2 = ["device.shadow", "*"];
 function isHighFreqEvent(event) {
-  return HIGH_FREQ_EVENTS.includes(event);
+  return HIGH_FREQ_EVENTS2.includes(event);
 }
 function commandsAreOpposing(a, b2) {
   for (const [x2, y] of OPPOSING_PAIRS) {
@@ -55837,9 +56700,9 @@ init_client2();
 
 // src/rules/webhook-token.ts
 init_cjs_shim();
-import fs21 from "node:fs";
-import os18 from "node:os";
-import path19 from "node:path";
+import fs23 from "node:fs";
+import os19 from "node:os";
+import path20 from "node:path";
 import { randomBytes } from "node:crypto";
 var ENV_TOKEN = "SWITCHBOT_WEBHOOK_TOKEN";
 var DEFAULT_FILE = ".switchbot/webhook-token";
@@ -55847,7 +56710,7 @@ var WebhookTokenStore = class {
   filePath;
   envLookup;
   constructor(opts = {}) {
-    this.filePath = opts.filePath ?? path19.join(os18.homedir(), DEFAULT_FILE);
+    this.filePath = opts.filePath ?? path20.join(os19.homedir(), DEFAULT_FILE);
     this.envLookup = opts.envLookup ?? (() => process.env[ENV_TOKEN]);
   }
   /**
@@ -55871,7 +56734,7 @@ var WebhookTokenStore = class {
    */
   readFromDisk() {
     try {
-      const raw = fs21.readFileSync(this.filePath, "utf-8").trim();
+      const raw = fs23.readFileSync(this.filePath, "utf-8").trim();
       return raw.length > 0 ? raw : null;
     } catch (err) {
       if (err.code === "ENOENT") return null;
@@ -55888,12 +56751,12 @@ var WebhookTokenStore = class {
     return this.filePath;
   }
   writeToDisk(token) {
-    const dir = path19.dirname(this.filePath);
-    fs21.mkdirSync(dir, { recursive: true });
-    fs21.writeFileSync(this.filePath, `${token}
+    const dir = path20.dirname(this.filePath);
+    fs23.mkdirSync(dir, { recursive: true });
+    fs23.writeFileSync(this.filePath, `${token}
 `, { mode: 384 });
     try {
-      fs21.chmodSync(this.filePath, 384);
+      fs23.chmodSync(this.filePath, 384);
     } catch {
     }
   }
@@ -55978,18 +56841,18 @@ function aggregateRuleAudits(entries) {
 }
 
 // src/commands/rules.ts
-var DEFAULT_AUDIT_PATH2 = path20.join(os19.homedir(), ".switchbot", "audit.log");
+var DEFAULT_AUDIT_PATH2 = path21.join(os20.homedir(), ".switchbot", "audit.log");
 function loadAutomation(policyPathFlag) {
-  const path28 = resolvePolicyPath({ flag: policyPathFlag });
+  const path29 = resolvePolicyPath({ flag: policyPathFlag });
   let loaded;
   try {
-    loaded = loadPolicyFile(path28);
+    loaded = loadPolicyFile(path29);
   } catch (err) {
     if (err instanceof PolicyFileNotFoundError) {
       exitWithError({
         code: 2,
         kind: "usage",
-        message: `policy file not found: ${path28}`,
+        message: `policy file not found: ${path29}`,
         extra: { subKind: "file-not-found" }
       });
     }
@@ -55997,7 +56860,7 @@ function loadAutomation(policyPathFlag) {
       exitWithError({
         code: 3,
         kind: "runtime",
-        message: `YAML parse error in ${path28}: ${err.message}`,
+        message: `YAML parse error in ${path29}: ${err.message}`,
         extra: { subKind: "yaml-parse", errors: err.yamlErrors }
       });
     }
@@ -56009,7 +56872,7 @@ function loadAutomation(policyPathFlag) {
       code: 4,
       kind: "runtime",
       message: "policy file failed schema validation. Run `switchbot policy validate` for details.",
-      extra: { subKind: "invalid-policy", path: path28 }
+      extra: { subKind: "invalid-policy", path: path29 }
     });
   }
   const data = loaded.data ?? {};
@@ -56023,7 +56886,7 @@ function loadAutomation(policyPathFlag) {
   }
   const rawQH = data.quiet_hours;
   const quietHours = rawQH && typeof rawQH.start === "string" && typeof rawQH.end === "string" ? { start: rawQH.start, end: rawQH.end } : null;
-  return { path: path28, automation, aliases, schemaVersion: result.schemaVersion, quietHours };
+  return { path: path29, automation, aliases, schemaVersion: result.schemaVersion, quietHours };
 }
 function describeTrigger(rule) {
   const t = rule.when;
@@ -56101,13 +56964,12 @@ function registerRun(rules) {
     const loaded = loadAutomation(pathArg);
     if (!loaded) return;
     if (loaded.automation?.enabled !== true) {
-      const msg = "automation.enabled is not true \u2014 nothing to run.";
-      if (isJsonMode()) {
-        printJson({ kind: "control", controlKind: "disabled", message: msg });
-      } else {
-        console.error(msg);
-      }
-      process.exit(0);
+      exitWithError({
+        code: 1,
+        kind: "runtime",
+        message: "automation.enabled is not true \u2014 set it to true in your policy file to start the daemon.",
+        hint: "Set automation.enabled: true in your policy file, then re-run."
+      });
     }
     const lint = lintRules(loaded.automation);
     if (!lint.valid) {
@@ -56287,7 +57149,7 @@ function registerTail(rules) {
   rules.command("tail").description("Stream rule-* entries from the audit log.").option("--file <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2})`).option("--since <duration>", "Only entries newer than this window (e.g. 1h, 30m, 7d).").option("--rule <name>", "Filter to a single rule name.").option("-f, --follow", "Keep the process open and stream new lines as they arrive.").action(async (opts) => {
     const file2 = opts.file ?? DEFAULT_AUDIT_PATH2;
     const sinceMs = resolveSinceMs(opts.since);
-    const existing = fs22.existsSync(file2) ? readAudit(file2) : [];
+    const existing = fs24.existsSync(file2) ? readAudit(file2) : [];
     const filtered = filterRuleAudits(existing, { sinceMs, ruleName: opts.rule });
     if (isJsonMode()) {
       for (const e of filtered) console.log(JSON.stringify(e));
@@ -56299,7 +57161,7 @@ function registerTail(rules) {
       for (const e of filtered) console.log(formatAuditLine(e));
     }
     if (!opts.follow) return;
-    let offset = fs22.existsSync(file2) ? fs22.statSync(file2).size : 0;
+    let offset = fs24.existsSync(file2) ? fs24.statSync(file2).size : 0;
     let buffer = "";
     const emit = (line) => {
       const trimmed = line.trim();
@@ -56316,21 +57178,21 @@ function registerTail(rules) {
       else console.log(formatAuditLine(entry));
     };
     const poll = setInterval(() => {
-      if (!fs22.existsSync(file2)) return;
-      const size = fs22.statSync(file2).size;
+      if (!fs24.existsSync(file2)) return;
+      const size = fs24.statSync(file2).size;
       if (size < offset) {
         offset = 0;
         buffer = "";
       }
       if (size === offset) return;
-      const fd = fs22.openSync(file2, "r");
+      const fd = fs24.openSync(file2, "r");
       try {
         const chunk = Buffer.alloc(size - offset);
-        fs22.readSync(fd, chunk, 0, chunk.length, offset);
+        fs24.readSync(fd, chunk, 0, chunk.length, offset);
         offset = size;
         buffer += chunk.toString("utf-8");
       } finally {
-        fs22.closeSync(fd);
+        fs24.closeSync(fd);
       }
       let newline = buffer.indexOf("\n");
       while (newline !== -1) {
@@ -56370,7 +57232,7 @@ function formatReplayTable(report) {
 function registerReplay(rules) {
   rules.command("replay").description("Aggregate rule-* audit entries per rule (fire/throttle/error counts).").option("--file <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2})`).option("--since <duration>", "Only entries newer than this window (e.g. 1h, 7d).").option("--rule <name>", "Filter to a single rule name.").action((opts) => {
     const file2 = opts.file ?? DEFAULT_AUDIT_PATH2;
-    const entries = fs22.existsSync(file2) ? readAudit(file2) : [];
+    const entries = fs24.existsSync(file2) ? readAudit(file2) : [];
     const sinceMs = resolveSinceMs(opts.since);
     const filtered = filterRuleAudits(entries, {
       sinceMs,
@@ -56490,7 +57352,7 @@ function registerSuggest(rules) {
         for (const w2 of warnings) process.stderr.write(`warning: ${w2}
 `);
         if (opts.out) {
-          fs22.writeFileSync(opts.out, ruleYaml, "utf8");
+          fs24.writeFileSync(opts.out, ruleYaml, "utf8");
           if (!isJsonMode()) console.log(`\u2713 rule YAML written to ${opts.out}`);
         } else if (isJsonMode()) {
           printJson({ rule, rule_yaml: ruleYaml, warnings });
@@ -56565,7 +57427,7 @@ overall: ${overall ? "ok" : "issues found"}`);
 function registerSummary(rules) {
   rules.command("summary").description("Aggregate rule-* audit entries per rule over a time window (fires, throttled, errors).").option("--file <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2})`).option("--since <duration>", "Only entries newer than this window (default: 24h). E.g. 1h, 7d.").option("--rule <name>", "Filter to a single rule name.").action((opts) => {
     const file2 = opts.file ?? DEFAULT_AUDIT_PATH2;
-    const entries = fs22.existsSync(file2) ? readAudit(file2) : [];
+    const entries = fs24.existsSync(file2) ? readAudit(file2) : [];
     const sinceMs = resolveSinceMs(opts.since ?? "24h");
     const filtered = filterRuleAudits(entries, { sinceMs, ruleName: opts.rule });
     const report = aggregateRuleAudits(filtered);
@@ -56596,7 +57458,7 @@ function registerLastFired(rules) {
   rules.command("last-fired").description("Show the N most recently fired rule-fire entries from the audit log.").option("--file <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2})`).option("--rule <name>", "Filter to a single rule name.").option("-n <count>", "Number of entries to show (default: 10).", (v2) => Number.parseInt(v2, 10)).action((opts) => {
     const file2 = opts.file ?? DEFAULT_AUDIT_PATH2;
     const n = opts.n ?? 10;
-    const entries = fs22.existsSync(file2) ? readAudit(file2) : [];
+    const entries = fs24.existsSync(file2) ? readAudit(file2) : [];
     const fires = filterRuleAudits(entries, {
       ruleName: opts.rule,
       kinds: ["rule-fire", "rule-fire-dry"]
@@ -56638,7 +57500,7 @@ function registerExplain(rules) {
       return;
     }
     const auditFile = opts.file ?? DEFAULT_AUDIT_PATH2;
-    const entries = fs22.existsSync(auditFile) ? readAudit(auditFile) : [];
+    const entries = fs24.existsSync(auditFile) ? readAudit(auditFile) : [];
     const fires = filterRuleAudits(entries, { ruleName: name, kinds: ["rule-fire", "rule-fire-dry"] });
     const lastFired = fires.length > 0 ? fires[fires.length - 1].t : null;
     const detail = {
@@ -56675,6 +57537,115 @@ function registerExplain(rules) {
     console.log(`last fired:            ${detail.lastFired ?? "(never)"}`);
   });
 }
+function registerTraceExplain(rules) {
+  rules.command("trace-explain [fireId]").description("Show why a rule evaluation fired or was blocked (reads rule-evaluate trace records).").option("--rule <name>", "Filter to a specific rule name.").option("--last", "Show the most recent evaluation for the rule (requires --rule).").option("--since <duration>", "Show evaluations in this window (e.g. 1h, 7d).").option("--all", "Include evaluations that fired (default: show all evaluations).").option("--file <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2}).`).action(
+    (fireIdArg, opts) => {
+      const auditFile = opts.file ?? DEFAULT_AUDIT_PATH2;
+      if (!fs24.existsSync(auditFile)) {
+        exitWithError({ code: 1, kind: "usage", message: `Audit log not found: ${auditFile}. Make sure trace recording is enabled (automation.audit.evaluate_trace: sampled or full).` });
+        return;
+      }
+      const sinceIso = opts.since ? new Date(Date.now() - (parseDurationToMs2(opts.since) ?? 0)).toISOString() : void 0;
+      let records = loadTraceRecords(auditFile, {
+        fireId: fireIdArg,
+        ruleName: opts.rule,
+        since: sinceIso
+      });
+      if (records.length === 0) {
+        const hint = 'Check that automation.audit.evaluate_trace is set to "sampled" or "full".';
+        exitWithError({ code: 1, kind: "usage", message: `No rule-evaluate trace records found. ${hint}` });
+        return;
+      }
+      if (opts.last) {
+        records = [records[records.length - 1]];
+      }
+      for (const record2 of records) {
+        const related = loadRelatedAudit(auditFile, record2.fireId);
+        if (isJsonMode()) {
+          console.log(formatExplainJson(record2, related));
+        } else {
+          console.log(formatExplainText(record2, related));
+          if (records.length > 1) console.log("---");
+        }
+      }
+    }
+  );
+}
+function registerSimulate(rules) {
+  rules.command("simulate <rule-or-policy>").description("Replay historical events against a rule and report would-fire / blocked outcomes.").option("--rule <name>", "Rule name to simulate (when <rule-or-policy> is a policy file).").option("--since <duration>", "Replay events from this window (e.g. 7d, 24h).").option("--against <file>", "Replay from a JSONL file of EngineEvent objects instead of the audit log.").option("--live-llm", "Allow live LLM calls for llm conditions (default: mark as would-call).").option("--audit-log <path>", `Audit log path (default ${DEFAULT_AUDIT_PATH2}).`).option("--report-out <path>", "Write the full JSON report to this file.").action(
+    async (ruleOrPolicy, opts) => {
+      let rule;
+      const auditLog = opts.auditLog ?? DEFAULT_AUDIT_PATH2;
+      if (!fs24.existsSync(ruleOrPolicy)) {
+        exitWithError({ code: 2, kind: "usage", message: `File not found: ${ruleOrPolicy}` });
+        return;
+      }
+      let parsed;
+      try {
+        const { parse: yamlParse5 } = await Promise.resolve().then(() => __toESM(require_dist(), 1));
+        parsed = yamlParse5(fs24.readFileSync(ruleOrPolicy, "utf-8"));
+      } catch {
+        exitWithError({ code: 2, kind: "usage", message: `Could not parse YAML file: ${ruleOrPolicy}` });
+        return;
+      }
+      const asRule = parsed;
+      if (asRule["name"] && asRule["when"] && asRule["then"]) {
+        rule = asRule;
+      } else {
+        const automation = loadAutomation(ruleOrPolicy);
+        if (!automation) return;
+        const ruleName = opts.rule;
+        if (!ruleName) {
+          exitWithError({ code: 1, kind: "usage", message: "Use --rule <name> to specify which rule to simulate from the policy file." });
+          return;
+        }
+        rule = automation.automation?.rules?.find((r) => r.name === ruleName);
+        if (!rule) {
+          exitWithError({ code: 1, kind: "usage", message: `Rule "${ruleName}" not found in policy file.` });
+          return;
+        }
+      }
+      try {
+        const report = await simulateRule({
+          rule,
+          since: opts.since,
+          against: opts.against,
+          auditLog,
+          liveLlm: opts.liveLlm ?? false
+        });
+        if (opts.reportOut) {
+          fs24.writeFileSync(opts.reportOut, JSON.stringify(report, null, 2));
+          console.log(`Report written to ${opts.reportOut}`);
+        }
+        if (isJsonMode()) {
+          printJson(report);
+        } else {
+          console.log(`Rule: ${report.ruleName}  (version ${report.ruleVersion})`);
+          console.log(`Window: ${report.windowStart.toISOString()} \u2192 ${report.windowEnd.toISOString()}`);
+          console.log(`Source events: ${report.sourceEventCount}`);
+          console.log("");
+          console.log(`  Would fire:          ${report.wouldFire}`);
+          console.log(`  Blocked by condition:${report.blockedByCondition}`);
+          console.log(`  Throttled:           ${report.throttled}`);
+          console.log(`  Errored:             ${report.errored}`);
+          if (report.skippedLlm > 0) {
+            console.log(`  Skipped (llm):       ${report.skippedLlm} (use --live-llm to evaluate)`);
+          }
+          if (report.topBlockReason && report.topBlockCount !== void 0) {
+            const total = report.blockedByCondition;
+            const pct = total > 0 ? Math.round(report.topBlockCount / total * 100) : 0;
+            if (pct >= 80) {
+              console.log("");
+              console.log(`Top block reason (${pct}%): ${report.topBlockReason}`);
+            }
+          }
+        }
+      } catch (err) {
+        handleError(err);
+      }
+    }
+  );
+}
 function registerRulesCommand(program3) {
   const rules = program3.command("rules").description("Run, list, and lint automation rules declared in policy.yaml (v0.2, preview).").addHelpText(
     "after",
@@ -56722,6 +57693,8 @@ Exit codes (lint):
   registerDoctor(rules);
   registerSummary(rules);
   registerLastFired(rules);
+  registerTraceExplain(rules);
+  registerSimulate(rules);
   registerWebhookRotateToken(rules);
   registerWebhookShowToken(rules);
 }
@@ -56732,9 +57705,9 @@ init_output();
 init_arg_parsers();
 init_request_context();
 init_keychain();
-import fs23 from "node:fs";
-import path21 from "node:path";
-import os20 from "node:os";
+import fs25 from "node:fs";
+import path22 from "node:path";
+import os21 from "node:os";
 import readline5 from "node:readline";
 function activeProfile() {
   return getActiveProfile() ?? "default";
@@ -56780,7 +57753,7 @@ async function promptSecret2(question) {
   });
 }
 function readStdinFile(filePath) {
-  if (!fs23.existsSync(filePath)) {
+  if (!fs25.existsSync(filePath)) {
     exitWithError({
       code: 2,
       kind: "usage",
@@ -56789,7 +57762,7 @@ function readStdinFile(filePath) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(fs23.readFileSync(filePath, "utf-8"));
+    parsed = JSON.parse(fs25.readFileSync(filePath, "utf-8"));
   } catch (err) {
     exitWithError({
       code: 2,
@@ -56819,10 +57792,10 @@ function cleanupMigratedSourceFile(sourceFile, parsed) {
   delete next.token;
   delete next.secret;
   if (Object.keys(next).length === 0) {
-    fs23.unlinkSync(sourceFile);
+    fs25.unlinkSync(sourceFile);
     return "deleted";
   }
-  fs23.writeFileSync(sourceFile, JSON.stringify(next, null, 2), { mode: 384 });
+  fs25.writeFileSync(sourceFile, JSON.stringify(next, null, 2), { mode: 384 });
   return "scrubbed";
 }
 function registerAuthCommand(program3) {
@@ -56953,8 +57926,8 @@ function registerAuthCommand(program3) {
         message: `backend "${store.name}" is not writable on this machine`
       });
     }
-    const sourceFile = profile === "default" ? path21.join(os20.homedir(), ".switchbot", "config.json") : path21.join(os20.homedir(), ".switchbot", "profiles", `${profile}.json`);
-    if (!fs23.existsSync(sourceFile)) {
+    const sourceFile = profile === "default" ? path22.join(os21.homedir(), ".switchbot", "config.json") : path22.join(os21.homedir(), ".switchbot", "profiles", `${profile}.json`);
+    if (!fs25.existsSync(sourceFile)) {
       exitWithError({
         code: 2,
         kind: "usage",
@@ -56964,7 +57937,7 @@ function registerAuthCommand(program3) {
     }
     let parsed;
     try {
-      const raw = JSON.parse(fs23.readFileSync(sourceFile, "utf-8"));
+      const raw = JSON.parse(fs25.readFileSync(sourceFile, "utf-8"));
       if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("expected a JSON object");
       }
@@ -57026,8 +57999,8 @@ function registerAuthCommand(program3) {
 init_cjs_shim();
 init_esm();
 init_load();
-import fs26 from "node:fs";
-import path24 from "node:path";
+import fs28 from "node:fs";
+import path25 from "node:path";
 
 // src/install/steps.ts
 init_cjs_shim();
@@ -57079,9 +58052,9 @@ init_cjs_shim();
 init_load();
 init_validate();
 init_keychain();
-import fs24 from "node:fs";
-import path22 from "node:path";
-import os21 from "node:os";
+import fs26 from "node:fs";
+import path23 from "node:path";
+import os22 from "node:os";
 function parseMajor(version2) {
   const m2 = /^v?(\d+)\./.exec(version2);
   if (!m2) return null;
@@ -57171,10 +58144,10 @@ async function checkKeychain2() {
   }
 }
 function checkHomeDirWritable() {
-  const home = os21.homedir();
-  const switchbotDir = path22.join(home, ".switchbot");
+  const home = os22.homedir();
+  const switchbotDir = path23.join(home, ".switchbot");
   try {
-    const homeStat = fs24.statSync(home);
+    const homeStat = fs26.statSync(home);
     if (!homeStat.isDirectory()) {
       return {
         name: "home",
@@ -57183,8 +58156,8 @@ function checkHomeDirWritable() {
         hint: "check your HOME/USERPROFILE environment configuration"
       };
     }
-    if (fs24.existsSync(switchbotDir)) {
-      const sbStat = fs24.statSync(switchbotDir);
+    if (fs26.existsSync(switchbotDir)) {
+      const sbStat = fs26.statSync(switchbotDir);
       if (!sbStat.isDirectory()) {
         return {
           name: "home",
@@ -57193,10 +58166,10 @@ function checkHomeDirWritable() {
           hint: "move the file aside and re-run install"
         };
       }
-      fs24.accessSync(switchbotDir, fs24.constants.W_OK);
+      fs26.accessSync(switchbotDir, fs26.constants.W_OK);
       return { name: "home", status: "ok", message: `writable: ${switchbotDir}` };
     }
-    fs24.accessSync(home, fs24.constants.W_OK);
+    fs26.accessSync(home, fs26.constants.W_OK);
     return { name: "home", status: "ok", message: `writable: ${home}` };
   } catch (err) {
     return {
@@ -57210,8 +58183,8 @@ function checkHomeDirWritable() {
 function nearestExistingPath(target) {
   let cur = target;
   while (true) {
-    if (fs24.existsSync(cur)) return cur;
-    const parent = path22.dirname(cur);
+    if (fs26.existsSync(cur)) return cur;
+    const parent = path23.dirname(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -57219,8 +58192,8 @@ function nearestExistingPath(target) {
 function checkAgentSkillDirWritable(opts) {
   const shouldCheck = opts.agent === "claude-code" && (opts.expectSkillLink ?? true);
   if (!shouldCheck) return null;
-  const home = os21.homedir();
-  const target = path22.join(home, ".claude", "skills");
+  const home = os22.homedir();
+  const target = path23.join(home, ".claude", "skills");
   try {
     const existing = nearestExistingPath(target);
     if (!existing) {
@@ -57231,7 +58204,7 @@ function checkAgentSkillDirWritable(opts) {
         hint: "check your home directory path and permissions"
       };
     }
-    const stat = fs24.statSync(existing);
+    const stat = fs26.statSync(existing);
     if (!stat.isDirectory()) {
       return {
         name: "agent-skills-dir",
@@ -57240,7 +58213,7 @@ function checkAgentSkillDirWritable(opts) {
         hint: "move the blocking file aside and re-run install"
       };
     }
-    fs24.accessSync(existing, fs24.constants.W_OK);
+    fs26.accessSync(existing, fs26.constants.W_OK);
     return { name: "agent-skills-dir", status: "ok", message: `writable: ${target}` };
   } catch (err) {
     return {
@@ -57265,9 +58238,9 @@ async function runPreflight(options = {}) {
 
 // src/install/default-steps.ts
 init_cjs_shim();
-import fs25 from "node:fs";
-import path23 from "node:path";
-import os22 from "node:os";
+import fs27 from "node:fs";
+import path24 from "node:path";
+import os23 from "node:os";
 import { spawnSync } from "node:child_process";
 init_keychain();
 function stepPromptCredentials() {
@@ -57342,15 +58315,15 @@ function stepScaffoldPolicy() {
       const r = ctx.policyScaffoldResult;
       if (!r || r.skipped) return;
       try {
-        fs25.unlinkSync(r.policyPath);
+        fs27.unlinkSync(r.policyPath);
       } catch {
       }
     }
   };
 }
-function skillLinkPathFor(agent, home = os22.homedir()) {
+function skillLinkPathFor(agent, home = os23.homedir()) {
   if (agent === "claude-code") {
-    return path23.join(home, ".claude", "skills", "switchbot");
+    return path24.join(home, ".claude", "skills", "switchbot");
   }
   return null;
 }
@@ -57364,11 +58337,11 @@ function stepSymlinkSkill(opts = {}) {
         ctx.skillRecipePrinted = true;
         return;
       }
-      const target = path23.resolve(ctx.skillPath);
-      if (!fs25.existsSync(target)) {
+      const target = path24.resolve(ctx.skillPath);
+      if (!fs27.existsSync(target)) {
         throw new Error(`--skill-path does not exist: ${target}`);
       }
-      const stat = fs25.statSync(target);
+      const stat = fs27.statSync(target);
       if (!stat.isDirectory()) {
         throw new Error(`--skill-path is not a directory: ${target}`);
       }
@@ -57377,17 +58350,17 @@ function stepSymlinkSkill(opts = {}) {
         ctx.skillRecipePrinted = true;
         return;
       }
-      if (!opts.force && !fs25.existsSync(path23.join(target, "SKILL.md"))) {
+      if (!opts.force && !fs27.existsSync(path24.join(target, "SKILL.md"))) {
         throw new Error(
           `${target} does not look like a skill (no SKILL.md at the root). Pass --force if you really mean to link this directory.`
         );
       }
-      if (fs25.existsSync(linkPath)) {
-        const st = fs25.lstatSync(linkPath);
+      if (fs27.existsSync(linkPath)) {
+        const st = fs27.lstatSync(linkPath);
         if (st.isSymbolicLink()) {
           let existingTarget = null;
           try {
-            existingTarget = path23.resolve(path23.dirname(linkPath), fs25.readlinkSync(linkPath));
+            existingTarget = path24.resolve(path24.dirname(linkPath), fs27.readlinkSync(linkPath));
           } catch {
             existingTarget = null;
           }
@@ -57401,23 +58374,23 @@ function stepSymlinkSkill(opts = {}) {
               `${linkPath} already links to ${existingTarget ?? "(unreadable)"}; pass --force to replace it, or run \`switchbot uninstall\` first.`
             );
           }
-          fs25.unlinkSync(linkPath);
+          fs27.unlinkSync(linkPath);
         } else {
           throw new Error(
             `${linkPath} exists and is not a symlink; refusing to clobber (move it aside and re-run)`
           );
         }
       }
-      fs25.mkdirSync(path23.dirname(linkPath), { recursive: true });
+      fs27.mkdirSync(path24.dirname(linkPath), { recursive: true });
       const linkType = process.platform === "win32" ? "junction" : "dir";
-      fs25.symlinkSync(target, linkPath, linkType);
+      fs27.symlinkSync(target, linkPath, linkType);
       ctx.skillLinkPath = linkPath;
       ctx.skillLinkCreated = true;
     },
     undo(ctx) {
       if (!ctx.skillLinkCreated || !ctx.skillLinkPath) return;
       try {
-        fs25.unlinkSync(ctx.skillLinkPath);
+        fs27.unlinkSync(ctx.skillLinkPath);
       } catch {
       }
     }
@@ -57560,8 +58533,8 @@ Examples:
     const agent = parseAgent(opts.agent);
     const profile = getActiveProfile() ?? "default";
     const skip = parseSkipList(opts.skip);
-    const skillPath = opts.skillPath ? path24.resolve(opts.skillPath) : void 0;
-    const tokenFile = opts.tokenFile ? path24.resolve(opts.tokenFile) : void 0;
+    const skillPath = opts.skillPath ? path25.resolve(opts.skillPath) : void 0;
+    const tokenFile = opts.tokenFile ? path25.resolve(opts.tokenFile) : void 0;
     const force = Boolean(opts.force);
     const verify = Boolean(opts.verify);
     const globalOpts = command.parent?.opts() ?? {};
@@ -57605,7 +58578,7 @@ Examples:
     const report = await runInstall(steps, { context: ctx });
     if (report.ok && tokenFile) {
       try {
-        fs26.unlinkSync(tokenFile);
+        fs28.unlinkSync(tokenFile);
       } catch {
       }
     }
@@ -57664,7 +58637,7 @@ Examples:
 init_cjs_shim();
 init_esm();
 init_load();
-import fs27 from "node:fs";
+import fs29 from "node:fs";
 import readline6 from "node:readline";
 init_keychain();
 init_output();
@@ -57729,10 +58702,10 @@ Examples:
         action: "remove-skill-link",
         detail: skillLink,
         run: async () => {
-          if (!fs27.existsSync(skillLink)) {
+          if (!fs29.existsSync(skillLink)) {
             return { action: "remove-skill-link", status: "absent", detail: skillLink };
           }
-          const stat = fs27.lstatSync(skillLink);
+          const stat = fs29.lstatSync(skillLink);
           if (!stat.isSymbolicLink()) {
             return {
               action: "remove-skill-link",
@@ -57743,7 +58716,7 @@ Examples:
           const ok = yes ? true : await prompt(`Remove skill link ${skillLink}?`, true);
           if (!ok) return { action: "remove-skill-link", status: "skipped", detail: skillLink };
           try {
-            fs27.unlinkSync(skillLink);
+            fs29.unlinkSync(skillLink);
             return { action: "remove-skill-link", status: "removed", detail: skillLink };
           } catch (err) {
             return {
@@ -57798,13 +58771,13 @@ Examples:
             detail: "pass --remove-policy to delete policy.yaml"
           };
         }
-        if (!fs27.existsSync(policyPath)) {
+        if (!fs29.existsSync(policyPath)) {
           return { action: "remove-policy", status: "absent", detail: policyPath };
         }
         const ok = yes ? true : await prompt(`Delete policy file ${policyPath}?`, false);
         if (!ok) return { action: "remove-policy", status: "skipped", detail: policyPath };
         try {
-          fs27.unlinkSync(policyPath);
+          fs29.unlinkSync(policyPath);
           return { action: "remove-policy", status: "removed", detail: policyPath };
         } catch (err) {
           return {
@@ -57867,9 +58840,9 @@ init_request_context();
 init_output();
 init_flags();
 import { spawn as spawn4, spawnSync as spawnSync2 } from "node:child_process";
-import fs28 from "node:fs";
-import os23 from "node:os";
-import path25 from "node:path";
+import fs30 from "node:fs";
+import os24 from "node:os";
+import path26 from "node:path";
 var DEFAULT_OPENCLAW_URL = "http://localhost:18789";
 function resolveStatusSyncRuntime(options) {
   if (!tryLoadConfig()) {
@@ -58003,14 +58976,14 @@ async function probeStatusSyncStart(options = {}) {
   };
 }
 function resolveStatusSyncPaths(explicitStateDir) {
-  const stateDir = path25.resolve(
-    explicitStateDir ?? process.env.SWITCHBOT_STATUS_SYNC_HOME ?? path25.join(os23.homedir(), ".switchbot", "status-sync")
+  const stateDir = path26.resolve(
+    explicitStateDir ?? process.env.SWITCHBOT_STATUS_SYNC_HOME ?? path26.join(os24.homedir(), ".switchbot", "status-sync")
   );
   return {
     stateDir,
-    stateFile: path25.join(stateDir, "state.json"),
-    stdoutLog: path25.join(stateDir, "stdout.log"),
-    stderrLog: path25.join(stateDir, "stderr.log")
+    stateFile: path26.join(stateDir, "state.json"),
+    stdoutLog: path26.join(stateDir, "stdout.log"),
+    stderrLog: path26.join(stateDir, "stderr.log")
   };
 }
 function buildStatusSyncChildArgs(options) {
@@ -58018,11 +58991,11 @@ function buildStatusSyncChildArgs(options) {
   if (!scriptPath) {
     throw new Error("Cannot determine the current CLI entrypoint path.");
   }
-  const args = [path25.resolve(scriptPath)];
+  const args = [path26.resolve(scriptPath)];
   const configPath = getConfigPath();
   const profile = getActiveProfile();
   if (configPath) {
-    args.push("--config", path25.resolve(configPath));
+    args.push("--config", path26.resolve(configPath));
   } else if (profile) {
     args.push("--profile", profile);
   }
@@ -58043,7 +59016,7 @@ function buildStatusSyncChildArgs(options) {
 }
 function safeUnlink(filePath) {
   try {
-    fs28.unlinkSync(filePath);
+    fs30.unlinkSync(filePath);
   } catch {
   }
 }
@@ -58058,9 +59031,9 @@ function isProcessRunning(pid) {
   }
 }
 function readStateFile(paths) {
-  if (!fs28.existsSync(paths.stateFile)) return null;
+  if (!fs30.existsSync(paths.stateFile)) return null;
   try {
-    const raw = JSON.parse(fs28.readFileSync(paths.stateFile, "utf-8"));
+    const raw = JSON.parse(fs30.readFileSync(paths.stateFile, "utf-8"));
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
       safeUnlink(paths.stateFile);
       return null;
@@ -58179,14 +59152,14 @@ function startStatusSync(options = {}) {
     }
     stopStatusSync({ stateDir: paths.stateDir });
   }
-  fs28.mkdirSync(paths.stateDir, { recursive: true });
+  fs30.mkdirSync(paths.stateDir, { recursive: true });
   const configPath = getConfigPath();
   const command = buildStatusSyncChildArgs(runtime);
   let stdoutFd = null;
   let stderrFd = null;
   try {
-    stdoutFd = fs28.openSync(paths.stdoutLog, "a");
-    stderrFd = fs28.openSync(paths.stderrLog, "a");
+    stdoutFd = fs30.openSync(paths.stdoutLog, "a");
+    stderrFd = fs30.openSync(paths.stderrLog, "a");
     const child = spawn4(process.execPath, command, {
       detached: true,
       stdio: ["ignore", stdoutFd, stderrFd],
@@ -58204,16 +59177,16 @@ function startStatusSync(options = {}) {
       openclawUrl: runtime.openclawUrl,
       openclawModel: runtime.openclawModel,
       topic: runtime.topic ?? null,
-      configPath: configPath ? path25.resolve(configPath) : null,
+      configPath: configPath ? path26.resolve(configPath) : null,
       profile: configPath ? null : getActiveProfile() ?? null,
       stdoutLog: paths.stdoutLog,
       stderrLog: paths.stderrLog
     };
-    fs28.writeFileSync(paths.stateFile, JSON.stringify(state, null, 2), { mode: 384 });
+    fs30.writeFileSync(paths.stateFile, JSON.stringify(state, null, 2), { mode: 384 });
     return toStatus(paths, state, true);
   } finally {
-    if (stdoutFd !== null) fs28.closeSync(stdoutFd);
-    if (stderrFd !== null) fs28.closeSync(stderrFd);
+    if (stdoutFd !== null) fs30.closeSync(stdoutFd);
+    if (stderrFd !== null) fs30.closeSync(stderrFd);
   }
 }
 async function runStatusSyncForeground(options = {}) {
@@ -58360,10 +59333,10 @@ init_cjs_shim();
 init_quota();
 init_audit();
 init_client();
-import fs29 from "node:fs";
-import os24 from "node:os";
-import path26 from "node:path";
-var DEFAULT_AUDIT_PATH3 = path26.join(os24.homedir(), ".switchbot", "audit.log");
+import fs31 from "node:fs";
+import os25 from "node:os";
+import path27 from "node:path";
+var DEFAULT_AUDIT_PATH3 = path27.join(os25.homedir(), ".switchbot", "audit.log");
 var AUDIT_ERROR_WINDOW_MS = 24 * 60 * 60 * 1e3;
 function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
   const now = /* @__PURE__ */ new Date();
@@ -58384,7 +59357,7 @@ function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
     status: pct >= 90 ? "critical" : pct >= 70 ? "warn" : "ok"
   };
   let auditHealth;
-  if (!fs29.existsSync(auditPath)) {
+  if (!fs31.existsSync(auditPath)) {
     auditHealth = { present: false, recentErrors: 0, recentTotal: 0, errorRatePercent: 0, status: "ok" };
   } else {
     const entries = readAudit(auditPath);
@@ -58654,8 +59627,8 @@ function registerUpgradeCheckCommand(program3) {
 init_cjs_shim();
 init_output();
 import { spawn as spawn5 } from "node:child_process";
-import fs30 from "node:fs";
-import path27 from "node:path";
+import fs32 from "node:fs";
+import path28 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 init_arg_parsers();
 init_source();
@@ -58717,7 +59690,7 @@ function persistState(partial2) {
 }
 function readLastLines(filePath, n = 20) {
   try {
-    const content = fs30.readFileSync(filePath, "utf-8");
+    const content = fs32.readFileSync(filePath, "utf-8");
     const lines = content.split("\n");
     return lines.slice(Math.max(0, lines.length - n)).join("\n").trim();
   } catch {
@@ -58807,10 +59780,10 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       }
     }
     const thisFile = fileURLToPath3(import.meta.url);
-    const cliEntry = path27.resolve(path27.dirname(thisFile), "..", "index.js");
+    const cliEntry = path28.basename(thisFile) === "index.js" ? thisFile : path28.resolve(path28.dirname(thisFile), "..", "index.js");
     const args = ["rules", "run"];
     if (opts.policy) args.push(opts.policy);
-    fs30.mkdirSync(path27.dirname(DAEMON_PID_FILE), { recursive: true, mode: 448 });
+    fs32.mkdirSync(path28.dirname(DAEMON_PID_FILE), { recursive: true, mode: 448 });
     persistState({
       status: "starting",
       pid: null,
@@ -58822,14 +59795,14 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       healthzPid: null,
       healthzPidFile: HEALTHZ_PID_FILE
     });
-    const logFd = fs30.openSync(DAEMON_LOG_FILE, "a");
+    const logFd = fs32.openSync(DAEMON_LOG_FILE, "a");
     const child = spawn5(process.execPath, [cliEntry, ...args], {
       detached: true,
       stdio: ["ignore", logFd, logFd],
       env: { ...process.env }
     });
     child.unref();
-    fs30.closeSync(logFd);
+    fs32.closeSync(logFd);
     await probeLiveness({
       child,
       delayMs: 300,
@@ -58852,14 +59825,14 @@ The daemon reads the same policy file as \`switchbot rules run\`.
     let healthzPort = opts.healthzPort ? Number.parseInt(opts.healthzPort, 10) : null;
     if (healthzPort !== null) {
       const healthArgs = ["health", "serve", "--port", String(healthzPort)];
-      const healthLogFd = fs30.openSync(DAEMON_LOG_FILE, "a");
+      const healthLogFd = fs32.openSync(DAEMON_LOG_FILE, "a");
       const healthChild = spawn5(process.execPath, [cliEntry, ...healthArgs], {
         detached: true,
         stdio: ["ignore", healthLogFd, healthLogFd],
         env: { ...process.env }
       });
       healthChild.unref();
-      fs30.closeSync(healthLogFd);
+      fs32.closeSync(healthLogFd);
       if (healthChild.pid) {
         const healthAlive = await probeLiveness({ child: healthChild, delayMs: 200, fatal: false });
         if (healthAlive) {
@@ -58922,11 +59895,11 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       });
     }
     try {
-      fs30.unlinkSync(DAEMON_PID_FILE);
+      fs32.unlinkSync(DAEMON_PID_FILE);
     } catch {
     }
     try {
-      fs30.unlinkSync(HEALTHZ_PID_FILE);
+      fs32.unlinkSync(HEALTHZ_PID_FILE);
     } catch {
     }
     persistState({
@@ -59164,17 +60137,32 @@ try {
 } catch (err) {
   if (err instanceof CommanderError) {
     if (err.code === "commander.helpDisplayed") {
+      const helpRequested = process.argv.includes("--help") || process.argv.includes("-h") || process.argv.includes("help");
+      if (helpRequested) {
+        if (isJsonMode()) {
+          const target = resolveTargetCommand(program2, process.argv.slice(2));
+          printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        }
+        process.exit(0);
+      }
       if (isJsonMode()) {
         const target = resolveTargetCommand(program2, process.argv.slice(2));
-        printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        const usefulMessage = subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+        emitJsonError({ code: 2, kind: "usage", message: usefulMessage });
       }
-      process.exit(0);
+      process.exit(2);
     }
     if (err.code === "commander.version") {
       process.exit(0);
     }
     if (isJsonMode()) {
-      emitJsonError({ code: 2, kind: "usage", message: err.message });
+      const errorMessage = err.code === "commander.help" ? (() => {
+        const target = resolveTargetCommand(program2, process.argv.slice(2));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        return subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+      })() : err.message;
+      emitJsonError({ code: 2, kind: "usage", message: errorMessage });
     }
     process.exit(2);
   }