@switchbot/openapi-cli 3.2.2 → 3.3.1

package/dist/index.js

@@ -6396,6 +6396,7 @@ var init_prime = __esm({
 import fs2 from "node:fs";
 import path2 from "node:path";
 import os3 from "node:os";
+import { createHash } from "node:crypto";
 function sanitizeOptionalString(v2) {
   if (typeof v2 !== "string") return void 0;
   const trimmed = v2.trim();
@@ -6586,12 +6587,13 @@ function getConfigSummary() {
   }
 }
 function maskCredential(token) {
-  if (token.length <= 8) return "*".repeat(Math.max(4, token.length));
-  return token.slice(0, 4) + "*".repeat(token.length - 8) + token.slice(-4);
+  return `**** [sha256:${fingerprintCredential(token)}]`;
 }
 function maskSecret(secret) {
-  if (secret.length <= 4) return "****";
-  return secret.slice(0, 2) + "*".repeat(secret.length - 4) + secret.slice(-2);
+  return `**** [sha256:${fingerprintCredential(secret)}]`;
+}
+function fingerprintCredential(value) {
+  return createHash("sha256").update(value).digest("hex").slice(-8);
 }
 var init_config = __esm({
   "src/config.ts"() {
@@ -7219,7 +7221,7 @@ function emitJsonError(errorPayload) {
 function emitStreamHeader(opts) {
   console.log(
     JSON.stringify({
-      schemaVersion: "1",
+      schemaVersion: SCHEMA_VERSION,
       stream: true,
       eventKind: opts.eventKind,
       cadence: opts.cadence
@@ -8125,9 +8127,9 @@ var init_catalog = __esm({
         description: "Battery-powered temperature and humidity sensor; read-only, no control commands.",
         role: "sensor",
         readOnly: true,
-        aliases: ["Meter Plus", "MeterPro", "MeterPro(CO2)", "WoIOSensor", "Hub 2"],
+        aliases: ["Meter Plus", "MeterPro", "MeterPro(CO2)", "WoIOSensor"],
         commands: [],
-        statusFields: ["temperature", "humidity", "CO2", "battery", "version"]
+        statusFields: ["temperature", "humidity", "battery", "version"]
       },
       {
         type: "Motion Sensor",
@@ -8157,6 +8159,15 @@ var init_catalog = __esm({
         statusFields: ["battery", "version", "status"]
       },
       // Status-only hub-class devices (no control commands)
+      {
+        type: "Hub 2",
+        category: "physical",
+        description: "Wi-Fi hub with built-in temperature, humidity, and light sensors; bridges BLE devices to the cloud.",
+        role: "hub",
+        readOnly: true,
+        commands: [],
+        statusFields: ["version", "temperature", "humidity", "lightLevel"]
+      },
       {
         type: "Hub Mini",
         category: "physical",
@@ -8192,7 +8203,7 @@ var init_catalog = __esm({
         role: "climate",
         readOnly: true,
         commands: [],
-        statusFields: ["temperature", "humidity", "version"]
+        statusFields: ["battery", "brightness", "moveDetected", "humidity", "temperature", "version"]
       },
       {
         type: "Wallet Finder Card",
@@ -8301,11 +8312,11 @@ var init_catalog = __esm({
 import fs6 from "node:fs";
 import path6 from "node:path";
 import os7 from "node:os";
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 function scopedCacheDir(baseDir) {
   const profile = getActiveProfile();
   if (profile === void 0) return baseDir;
-  const hash2 = createHash("sha256").update(profile).digest("hex").slice(0, 8);
+  const hash2 = createHash2("sha256").update(profile).digest("hex").slice(0, 8);
   const dir = path6.join(baseDir, "cache", hash2);
   if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
   return dir;
@@ -8367,9 +8378,11 @@ function getCachedTypeMap(deviceIds) {
 function updateCacheFromDeviceList(body) {
   const devices = {};
   for (const d of body.deviceList) {
-    if (!d.deviceId || !d.deviceType) continue;
+    if (!d.deviceId) continue;
     devices[d.deviceId] = {
-      type: d.deviceType,
+      // Some real devices omit deviceType entirely (for example AI accessories).
+      // Keep them in cache with an empty type string rather than dropping the row.
+      type: d.deviceType ?? "",
       name: d.deviceName,
       category: "physical",
       hubDeviceId: d.hubDeviceId,
@@ -27172,6 +27185,9 @@ var IdempotencyConflictError = class extends Error {
 function hashKey(key) {
   return crypto2.createHash("sha256").update(key).digest("hex");
 }
+function fingerprintIdempotencyKey(key) {
+  return hashKey(key).slice(0, 12);
+}
 function shapeSignature(command, parameter) {
   let parm;
   try {
@@ -27371,9 +27387,23 @@ var CommandValidationError = class extends Error {
   kind;
   hint;
 };
-async function fetchDeviceList(client) {
+function hasDanglingHubReference(device, isPhysical, deviceList) {
+  if (!isPhysical) return false;
+  const hubDeviceId = device.hubDeviceId;
+  if (!hubDeviceId || hubDeviceId === "000000000000" || hubDeviceId === device.deviceId) return false;
+  return !deviceList.some((d) => d.deviceId === hubDeviceId);
+}
+function describeCatalogNote(deviceId, typeName, isPhysical) {
+  if (isPhysical) {
+    const label2 = typeName || "this device type";
+    return `No built-in catalog entry for ${label2}; raw device metadata is shown. Try \`switchbot devices status ${deviceId}\` for live raw status.`;
+  }
+  const label = typeName || "this IR remote type";
+  return `No built-in catalog entry for ${label}; raw device metadata is shown. Use \`switchbot devices command ${deviceId} "<buttonName>" --type customize\` for custom IR buttons.`;
+}
+async function fetchDeviceList(client, options = {}) {
   const mode = getCacheMode();
-  if (mode.listTtlMs > 0 && isListCacheFresh(mode.listTtlMs)) {
+  if (!options.bypassCache && mode.listTtlMs > 0 && isListCacheFresh(mode.listTtlMs)) {
     const cached2 = loadCache();
     if (cached2) {
       const deviceList = [];
@@ -27383,7 +27413,7 @@ async function fetchDeviceList(client) {
           deviceList.push({
             deviceId,
             deviceName: entry.name,
-            deviceType: entry.type,
+            ...entry.type ? { deviceType: entry.type } : {},
             enableCloudService: entry.enableCloudService ?? true,
             hubDeviceId: entry.hubDeviceId ?? "",
             roomID: entry.roomID,
@@ -27439,6 +27469,7 @@ async function executeCommand(deviceId, cmd, parameter, commandType, client, opt
     parameter,
     commandType,
     dryRun: isDryRun(),
+    ...options?.idempotencyKey ? { idempotencyKeyFingerprint: fingerprintIdempotencyKey(options.idempotencyKey) } : {},
     ...options?.planId ? { planId: options.planId } : {}
   };
   const execute = async () => {
@@ -27451,7 +27482,7 @@ async function executeCommand(deviceId, cmd, parameter, commandType, client, opt
       return res.data.body;
     } catch (err) {
       if (err instanceof Error && err.name === "DryRunSignal") {
-        writeAudit({ ...baseAudit, result: "ok" });
+        writeAudit({ ...baseAudit, result: "dry-run" });
       } else {
         writeAudit({
           ...baseAudit,
@@ -27468,6 +27499,12 @@ async function executeCommand(deviceId, cmd, parameter, commandType, client, opt
     { command: cmd, parameter }
   );
   if (!replayed) return result;
+  writeAudit({
+    ...baseAudit,
+    t: (/* @__PURE__ */ new Date()).toISOString(),
+    result: "ok",
+    replayed: true
+  });
   if (result && typeof result === "object") {
     return { ...result, replayed: true };
   }
@@ -27557,10 +27594,19 @@ function getDestructiveReason(deviceType, cmd, commandType) {
   return spec ? getCommandSafetyReason(spec) : null;
 }
 async function describeDevice(deviceId, options = {}, client) {
-  const body = await fetchDeviceList(client);
-  const { deviceList, infraredRemoteList } = body;
-  const physical = deviceList.find((d) => d.deviceId === deviceId);
-  const ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
+  const mode = getCacheMode();
+  const hadFreshListCache = mode.listTtlMs > 0 && isListCacheFresh(mode.listTtlMs) && loadCache() !== null;
+  let body = await fetchDeviceList(client);
+  let { deviceList, infraredRemoteList } = body;
+  let physical = deviceList.find((d) => d.deviceId === deviceId);
+  let ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
+  if (!physical && !ir && hadFreshListCache) {
+    body = await fetchDeviceList(client, { bypassCache: true });
+    deviceList = body.deviceList;
+    infraredRemoteList = body.infraredRemoteList;
+    physical = deviceList.find((d) => d.deviceId === deviceId);
+    ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
+  }
   if (!physical && !ir) throw new DeviceNotFoundError(deviceId);
   const typeName = physical ? physical.deviceType ?? "" : ir.remoteType;
   const match = typeName ? findCatalogEntry(typeName) : null;
@@ -27589,8 +27635,13 @@ async function describeDevice(deviceId, options = {}, client) {
     statusFields: catalogEntry.statusFields ?? [],
     ...liveStatus !== void 0 ? { liveStatus } : {}
   } : liveStatus !== void 0 ? { liveStatus } : null;
+  const warnings = [];
+  const selectedDevice = physical ?? ir;
+  if (hasDanglingHubReference(selectedDevice, Boolean(physical), deviceList)) {
+    warnings.push(`hubDeviceId ${selectedDevice.hubDeviceId} is not present in the current inventory`);
+  }
   return {
-    device: physical ?? ir,
+    device: selectedDevice,
     isPhysical: Boolean(physical),
     typeName,
     controlType: physical?.controlType ?? ir?.controlType ?? null,
@@ -27598,6 +27649,8 @@ async function describeDevice(deviceId, options = {}, client) {
     capabilities,
     source,
     suggestedActions: catalogEntry ? suggestedActions(catalogEntry) : [],
+    ...catalogEntry ? {} : { catalogNote: describeCatalogNote(deviceId, typeName, Boolean(physical)) },
+    ...warnings.length > 0 ? { warnings } : {},
     inheritedLocation: ir ? buildHubLocationMap(deviceList).get(ir.hubDeviceId) : void 0
   };
 }
@@ -27648,6 +27701,8 @@ function toMcpDescribeShape(r) {
     source: r.source,
     capabilities: r.capabilities,
     suggestedActions: r.suggestedActions,
+    ...r.catalogNote !== void 0 ? { catalogNote: r.catalogNote } : {},
+    ...r.warnings !== void 0 ? { warnings: r.warnings } : {},
     ...r.inheritedLocation !== void 0 ? { inheritedLocation: { family: r.inheritedLocation.family, room: r.inheritedLocation.room } } : {}
   };
 }
@@ -28468,7 +28523,6 @@ Examples:
           idempotencyKey: options.idempotencyKeyPrefix ? `${options.idempotencyKeyPrefix}-${id}` : void 0
         }));
         const planDoc = {
-          schemaVersion: "1.1",
           dryRun: true,
           plan: {
             command: cmd,
@@ -28577,7 +28631,6 @@ Examples:
           skipped: dryRunned.length + preSkipped.length,
           durationMs: Date.now() - startedAt,
           unverifiableCount: succeeded.filter((s2) => getCachedDevice(s2.deviceId)?.category === "ir").length,
-          schemaVersion: "1.1",
           maxConcurrent: concurrency,
           staggerMs,
           ...dryRun ? { dryRun: true } : {}
@@ -28586,10 +28639,25 @@ Examples:
       if (isJsonMode()) {
         printJson(result);
       } else {
-        console.log(
-          `
-Summary: ${result.summary.ok} ok, ${result.summary.failed} failed, ${result.summary.skipped} skipped (${result.summary.durationMs}ms)`
-        );
+        if (dryRunned.length > 0) {
+          console.log(`
+Planned (dry-run): ${dryRunned.length} device(s)`);
+          for (const d of dryRunned) console.log(`  - ${d.deviceId}`);
+        }
+        if (preSkipped.length > 0) {
+          console.log(`
+Skipped (offline): ${preSkipped.length} device(s)`);
+          for (const d of preSkipped) console.log(`  - ${d.deviceId}`);
+        }
+        const parts = [
+          `${result.summary.ok} ok`,
+          `${result.summary.failed} failed`
+        ];
+        if (dryRunned.length > 0) parts.push(`${dryRunned.length} planned`);
+        if (preSkipped.length > 0) parts.push(`${preSkipped.length} skipped_offline`);
+        parts.push(`(${result.summary.durationMs}ms)`);
+        console.log(`
+Summary: ${parts.join(", ")}`);
       }
       if (failed.length > 0) process.exit(1);
     }
@@ -28710,6 +28778,7 @@ function listAllCanonical() {
 
 // src/commands/watch.ts
 var MIN_INTERVAL_MS = 1e3;
+var INITIAL_MODES = ["snapshot", "emit", "skip"];
 function diff(prev, next, fields) {
   const out = {};
   const keys = fields ?? Object.keys(next);
@@ -28726,6 +28795,10 @@ function formatHumanLine(ev) {
   const when = new Date(ev.t).toLocaleTimeString();
   const head = `[${when}] ${ev.deviceId}${ev.type ? ` (${ev.type})` : ""}`;
   if (ev.error) return `${head}: error \u2014 ${ev.error}`;
+  if (ev.snapshot) {
+    const pairs3 = Object.entries(ev.snapshot).map(([k2, v2]) => `${k2}=${JSON.stringify(v2)}`).join(", ");
+    return `${head}: snapshot ${pairs3}`;
+  }
   const keys = Object.keys(ev.changed);
   if (keys.length === 0) return `${head}: no changes`;
   const pairs2 = keys.map((k2) => {
@@ -28751,24 +28824,34 @@ function sleep2(ms, signal) {
   });
 }
 function registerWatchCommand(devices) {
-  devices.command("watch").description("Poll device status on an interval and emit field-level changes (JSONL)").argument("[deviceId...]", "One or more deviceIds to watch (or use --name for one device)").option("--name <query>", "Resolve one device by fuzzy name (combined with any positional IDs)", stringArg("--name")).option(
+  devices.command("watch").description("Poll device status on an interval and emit field-level changes (human table by default; JSONL with --json for agents)").argument("[deviceId...]", "One or more deviceIds to watch (or use --name for one device)").option("--name <query>", "Resolve one device by fuzzy name (combined with any positional IDs)", stringArg("--name")).option(
     "--interval <dur>",
     `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1e3}s)`,
     durationArg("--interval"),
     "30s"
-  ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--for <dur>", 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg("--for")).option("--include-unchanged", "Emit a tick even when no field changed").addHelpText(
+  ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--for <dur>", 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg("--for")).option("--include-unchanged", "Emit a tick even when no field changed").option("--initial <mode>", "How to handle the first poll: snapshot | emit | skip (default: snapshot)", enumArg("--initial", INITIAL_MODES), "snapshot").addHelpText(
     "after",
     `
-Each poll emits one JSON line per deviceId with the shape:
+Default output is a human-readable table of field changes per tick; add --json
+to get one JSON-Lines record per deviceId per tick (the agent-friendly form).
+
+The first poll is configurable:
+  --initial=snapshot  emit one baseline snapshot event, then only diffs
+  --initial=emit      treat the first poll as null -> value changes
+  --initial=skip      record the baseline silently, then only diffs
+
+Subsequent ticks only include fields whose value changed (unless
+--include-unchanged is passed).
+
+Each --json line has the shape:
   { "t": "<ISO>", "tick": <n>, "deviceId": "ID", "type": "Bot",
     "changed": { "power": { "from": "off", "to": "on" } } }
 
-The very first poll has "from": null for every field (seed).
-
 Examples:
   $ switchbot devices watch ABC123 --interval 10s
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
+  # Agent-friendly: one JSONL record per tick, pipeable to jq
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
   $ switchbot devices watch --name "Living Room AC" --interval 10s
 `
@@ -28817,7 +28900,32 @@ Examples:
                 const cached2 = getCachedDevice(id);
                 try {
                   const body = await fetchDeviceStatus(id, client);
-                  const changed = diff(prev.get(id), body, fields);
+                  const previous = prev.get(id);
+                  const baseline = fields ? Object.fromEntries(fields.map((f2) => [f2, body[f2] ?? null])) : body;
+                  if (!prev.has(id)) {
+                    if (options.initial === "skip") {
+                      prev.set(id, body);
+                      return;
+                    }
+                    if (options.initial === "snapshot") {
+                      prev.set(id, body);
+                      const ev2 = {
+                        t,
+                        tick,
+                        deviceId: id,
+                        type: cached2?.type,
+                        changed: {},
+                        snapshot: baseline
+                      };
+                      if (isJsonMode()) {
+                        printJson(ev2);
+                      } else {
+                        console.log(formatHumanLine(ev2));
+                      }
+                      return;
+                    }
+                  }
+                  const changed = diff(previous, body, fields);
                   prev.set(id, body);
                   if (Object.keys(changed).length === 0 && !options.includeUnchanged) {
                     return;
@@ -28892,7 +29000,7 @@ Examples:
     try {
       const wantLive = options.live !== false;
       const desc = await describeDevice(deviceId, { live: wantLive });
-      const warnings = [];
+      const warnings = [...desc.warnings ?? []];
       if (desc.isPhysical && !desc.device.enableCloudService) {
         warnings.push("Cloud service disabled on this device \u2014 commands will fail.");
       }
@@ -28927,6 +29035,7 @@ Examples:
         name: deviceName(desc.device),
         role: desc.catalog?.role ?? null,
         readOnly: desc.catalog?.readOnly ?? false,
+        ...desc.catalogNote ? { catalogNote: desc.catalogNote } : {},
         location,
         liveStatus,
         commands,
@@ -28952,6 +29061,9 @@ function printHuman(r) {
     const loc = [r.location?.family, r.location?.room].filter(Boolean).join(" / ");
     console.log(`location: ${loc}`);
   }
+  if (r.catalogNote) {
+    console.log(`catalog:  ${r.catalogNote}`);
+  }
   if (r.warnings.length) {
     console.log("warnings:");
     for (const w2 of r.warnings) console.log(`  ! ${w2}`);
@@ -28998,7 +29110,7 @@ init_cache();
 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("--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)").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", `
 Translates semantic flags into the wire parameter format, then sends the command.
 
 Supported expansions:
@@ -29036,7 +29148,12 @@ Examples:
         effectiveCommand = deviceIdArg;
         effectiveDeviceIdArg = void 0;
       }
-      deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+      deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name, {
+        strategy: options.nameStrategy ?? "require-unique",
+        type: options.nameType,
+        category: options.nameCategory,
+        room: options.nameRoom
+      });
       if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode).");
       command = effectiveCommand;
       const cached2 = getCachedDevice(deviceId);
@@ -29219,6 +29336,21 @@ var EXPAND_HINTS = {
   "Blind Tilt": { command: "setPosition", flags: "--direction up --angle 50" },
   "Relay Switch 2PM": { command: "setMode", flags: "--channel 1 --mode edge" }
 };
+function annotateStatusPayload(deviceId, body) {
+  const annotated = { ...body };
+  if (Object.keys(body).length === 0) {
+    annotated.supported = false;
+    annotated.note = "this device does not expose cloud status";
+    return annotated;
+  }
+  const cached2 = getCachedDevice(deviceId);
+  const looksLikeMeter = cached2?.type?.toLowerCase().includes("meter") ?? false;
+  const staleZeroReading = looksLikeMeter && !Object.prototype.hasOwnProperty.call(body, "onlineStatus") && body.battery === 0 && body.temperature === 0 && body.humidity === 0;
+  if (staleZeroReading) {
+    annotated.hint = "readings look stale; check batteries or hub connectivity";
+  }
+  return annotated;
+}
 function registerDevicesCommand(program3) {
   const COMMAND_TYPES2 = ["command", "customize"];
   const devices = program3.command("devices").description("Manage and control SwitchBot devices").addHelpText("after", `
@@ -29454,7 +29586,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, ...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") {
@@ -29488,7 +29620,7 @@ Examples:
         category: options.nameCategory,
         room: options.nameRoom
       });
-      const body = await fetchDeviceStatus(deviceId);
+      const body = annotateStatusPayload(deviceId, await fetchDeviceStatus(deviceId));
       const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
       const fmt = resolveFormat();
       if (fmt === "json" && process.argv.includes("--json")) {
@@ -29766,7 +29898,7 @@ ${extra}` : extra;
         if (isJsonMode()) {
           printJson({ dryRun: true, wouldSend });
         } else {
-          console.log(`[dry-run] Would POST devices/${_deviceId}/commands with ${JSON.stringify({ command: _cmd, parameter: _parsedParam, commandType })}`);
+          console.log(`\u25E6 dry-run intercepted for ${_cmd} on ${_deviceId}; see stderr preview for the HTTP request.`);
         }
         return;
       }
@@ -29911,6 +30043,8 @@ Examples:
           capabilities,
           source,
           suggestedActions: picks,
+          ...result.catalogNote ? { catalogNote: result.catalogNote } : {},
+          ...result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {},
           ...expandHint ? { expandHint: { command: expandHint.command, flags: expandHint.flags, example: `switchbot devices expand ${deviceId} ${expandHint.command} ${expandHint.flags}` } } : {}
         });
         return;
@@ -29944,8 +30078,17 @@ Examples:
       }
       const liveStatus = capabilities && "liveStatus" in capabilities ? capabilities.liveStatus : void 0;
       console.log("");
+      if (result.warnings && result.warnings.length > 0) {
+        for (const warning of result.warnings) {
+          console.log(`Warning: ${warning}`);
+        }
+        console.log("");
+      }
       if (!catalog) {
         console.log(`(Type "${typeName}" is not in the built-in catalog \u2014 no command reference available.)`);
+        if (result.catalogNote) {
+          console.log(result.catalogNote);
+        }
         if (isPhysical) {
           console.log(`Try 'switchbot devices status ${deviceId}' to see what this device reports.`);
         } else {
@@ -30029,6 +30172,7 @@ function renderCatalogEntry(entry) {
   if (entry.statusFields && entry.statusFields.length > 0) {
     console.log('\nStatus fields (from "devices status"):');
     console.log("  " + entry.statusFields.join(", "));
+    console.log("  Note: statusFields are advisory; actual fields can vary by firmware and device variant.");
   }
   const expandHint = EXPAND_HINTS[entry.type];
   if (expandHint) {
@@ -45370,16 +45514,30 @@ import { createRequire as createRequire3 } from "node:module";
 
 // src/policy/schema.ts
 init_cjs_shim();
+
+// src/embedded-assets.ts
+init_cjs_shim();
 import { readFileSync as readFileSync2 } from "node:fs";
 import { fileURLToPath } from "node:url";
+function readAsset(relPath) {
+  const resolved = fileURLToPath(new URL(relPath, import.meta.url));
+  return readFileSync2(resolved, "utf-8");
+}
+function readPolicySchemaJson(version2) {
+  return readAsset(`./policy/schema/v${version2}.json`);
+}
+function readPolicyExampleYaml() {
+  return readAsset(`./policy/examples/policy.example.yaml`);
+}
+
+// src/policy/schema.ts
 var SUPPORTED_POLICY_SCHEMA_VERSIONS = ["0.2"];
 var CURRENT_POLICY_SCHEMA_VERSION = "0.2";
 var schemaCache = /* @__PURE__ */ new Map();
 function loadPolicySchema(version2 = CURRENT_POLICY_SCHEMA_VERSION) {
   const cached2 = schemaCache.get(version2);
   if (cached2) return cached2;
-  const url2 = new URL(`./schema/v${version2}.json`, import.meta.url);
-  const raw = readFileSync2(fileURLToPath(url2), "utf-8");
+  const raw = readPolicySchemaJson(version2);
   const parsed = JSON.parse(raw);
   schemaCache.set(version2, parsed);
   return parsed;
@@ -45388,6 +45546,12 @@ function isSupportedPolicySchemaVersion(v2) {
   return typeof v2 === "string" && SUPPORTED_POLICY_SCHEMA_VERSIONS.includes(v2);
 }
 
+// src/policy/validate.ts
+init_catalog();
+
+// src/rules/action.ts
+init_cjs_shim();
+
 // src/rules/destructive.ts
 init_cjs_shim();
 var DESTRUCTIVE_COMMANDS = [
@@ -45421,9 +45585,195 @@ function destructiveVerbOf(cmd) {
   return null;
 }
 
+// src/rules/action.ts
+var DEVICES_COMMAND_RE = /^devices\s+command\s+(\S+)\s+(\S+)(?:\s+(.*))?$/;
+function parseRuleCommand(cmd) {
+  const m2 = DEVICES_COMMAND_RE.exec(cmd.trim());
+  if (!m2) return null;
+  const deviceIdSlot = m2[1];
+  const verb = m2[2];
+  const rest = (m2[3] ?? "").trim();
+  return {
+    deviceIdSlot,
+    verb,
+    parameterTokens: rest.length === 0 ? [] : rest.split(/\s+/)
+  };
+}
+function resolveActionDevice(explicit, slot, aliases) {
+  const candidate = explicit ?? (slot && slot !== "<id>" ? slot : null);
+  if (!candidate) return null;
+  if (aliases[candidate]) return aliases[candidate];
+  return candidate;
+}
+function renderParameter(tokens) {
+  if (tokens.length === 0) return void 0;
+  if (tokens.length === 1) return tokens[0];
+  return tokens.join(":");
+}
+async function executeRuleAction(action, ctx) {
+  const parsed = parseRuleCommand(action.command);
+  if (!parsed) {
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId: "unknown",
+      command: action.command,
+      parameter: null,
+      commandType: "command",
+      dryRun: true,
+      result: "error",
+      error: "unparseable-command",
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        fireId: ctx.fireId,
+        reason: "unparseable-command"
+      }
+    });
+    return { ok: false, error: "unparseable-command", blocked: true };
+  }
+  if (isDestructiveCommand2(action.command)) {
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId: resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases) ?? "unknown",
+      command: action.command,
+      parameter: null,
+      commandType: "command",
+      dryRun: true,
+      result: "error",
+      error: `destructive-verb:${parsed.verb}`,
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        fireId: ctx.fireId,
+        reason: `destructive verb "${parsed.verb}" refused at runtime`
+      }
+    });
+    return { ok: false, error: `destructive-verb:${parsed.verb}`, blocked: true, verb: parsed.verb };
+  }
+  const deviceId = resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases);
+  if (!deviceId || deviceId === "<id>") {
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId: "unknown",
+      command: action.command,
+      parameter: null,
+      commandType: "command",
+      dryRun: true,
+      result: "error",
+      error: "missing-device",
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        fireId: ctx.fireId,
+        reason: "action omitted `device` and command used `<id>` placeholder"
+      }
+    });
+    return { ok: false, error: "missing-device", verb: parsed.verb };
+  }
+  const dryRun = ctx.globalDryRun === true || ctx.rule.dry_run === true;
+  const parameter = renderParameter(parsed.parameterTokens);
+  if (dryRun) {
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire-dry",
+      deviceId,
+      command: parsed.verb,
+      parameter: parameter ?? "default",
+      commandType: "command",
+      dryRun: true,
+      result: "ok",
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        matchedDevice: deviceId,
+        fireId: ctx.fireId
+      }
+    });
+    return { ok: true, dryRun: true, deviceId, verb: parsed.verb };
+  }
+  if (ctx.skipApiCall) {
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId,
+      command: parsed.verb,
+      parameter: parameter ?? "default",
+      commandType: "command",
+      dryRun: false,
+      result: "ok",
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        matchedDevice: deviceId,
+        fireId: ctx.fireId,
+        reason: "api-skipped"
+      }
+    });
+    return { ok: true, deviceId, verb: parsed.verb };
+  }
+  try {
+    await executeCommand(deviceId, parsed.verb, parameter, "command", ctx.httpClient);
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId,
+      command: parsed.verb,
+      parameter: parameter ?? "default",
+      commandType: "command",
+      dryRun: false,
+      result: "ok",
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        matchedDevice: deviceId,
+        fireId: ctx.fireId
+      }
+    });
+    return { ok: true, deviceId, verb: parsed.verb };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    writeAudit({
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      kind: "rule-fire",
+      deviceId,
+      command: parsed.verb,
+      parameter: parameter ?? "default",
+      commandType: "command",
+      dryRun: false,
+      result: "error",
+      error: msg,
+      rule: {
+        name: ctx.rule.name,
+        triggerSource: ctx.rule.when.source,
+        matchedDevice: deviceId,
+        fireId: ctx.fireId
+      }
+    });
+    return { ok: false, error: msg, deviceId, verb: parsed.verb };
+  }
+}
+function extractDeviceIdFromAction(action) {
+  if (action.device) return action.device;
+  const m2 = /\bdevices\s+command\s+(\S+)/.exec(action.command ?? "");
+  return m2 ? m2[1] : null;
+}
+
 // src/policy/validate.ts
 var require4 = createRequire3(import.meta.url);
 var addFormats = require4("ajv-formats");
+var POLICY_VALIDATION_LIMITATIONS = [
+  "Does not resolve aliases against the live device inventory.",
+  "Does not verify commands against the real target device, live capabilities, or current firmware."
+];
+var POLICY_VALIDATION_LIVE_LIMITATIONS = [
+  "Live inventory checks reflect a point-in-time device list snapshot.",
+  "Does not verify commands against live capabilities or current firmware."
+];
+var HEX_MAC_DEVICE_ID_RE = /^[A-Fa-f0-9]{12}(?:-[A-Za-z0-9]{2,16})?$/;
+var HYPHENATED_DEVICE_ID_RE = /^[A-Za-z0-9]{2,32}(?:-[A-Za-z0-9]{2,32}){1,4}$/;
 var validators = /* @__PURE__ */ new Map();
 function getValidator(version2) {
   const cached2 = validators.get(version2);
@@ -45467,6 +45817,13 @@ function getKeyNodeAt(doc, parentSegments, key) {
   const pair = parent.items.find((p2) => (0, import_yaml2.isScalar)(p2.key) && String(p2.key.value) === key);
   return pair?.key ?? null;
 }
+function locateInstancePath(doc, lineCounter, instancePath) {
+  const node = getNodeAt(doc, instancePathToSegments(instancePath));
+  const range = node?.range;
+  if (!range) return {};
+  const pos = lineCounter.linePos(range[0]);
+  return { line: pos.line, col: pos.col };
+}
 function locateError(doc, lineCounter, err) {
   const segments = instancePathToSegments(err.instancePath);
   if (err.keyword === "additionalProperties") {
@@ -45552,6 +45909,8 @@ function unsupportedVersionResult(loaded, declared) {
   return {
     policyPath: loaded.path,
     schemaVersion: CURRENT_POLICY_SCHEMA_VERSION,
+    validationScope: "schema+offline-semantics",
+    limitations: [...POLICY_VALIDATION_LIMITATIONS],
     valid: false,
     errors: [
       {
@@ -45566,6 +45925,58 @@ function unsupportedVersionResult(loaded, declared) {
     ]
   };
 }
+function escapeJsonPointerSegment(segment) {
+  return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function isPlausibleDeviceId(value) {
+  return HEX_MAC_DEVICE_ID_RE.test(value) || HYPHENATED_DEVICE_ID_RE.test(value);
+}
+function hasErrorAtPath(errors, path26) {
+  return errors.some((err) => err.path === path26);
+}
+function resolvePolicyDeviceRef(raw, aliases) {
+  if (!raw) return { ok: false, reason: "missing-device" };
+  if (raw === "<id>") return { ok: false, reason: "missing-device" };
+  if (Object.hasOwn(aliases, raw)) return { ok: true };
+  if (isPlausibleDeviceId(raw)) return { ok: true };
+  return { ok: false, reason: "unknown-device-ref" };
+}
+function collectAliasMap(data) {
+  const aliases = data?.aliases;
+  if (!aliases || typeof aliases !== "object") return {};
+  return Object.fromEntries(
+    Object.entries(aliases).filter(
+      (entry) => typeof entry[0] === "string" && typeof entry[1] === "string"
+    )
+  );
+}
+function isDeviceStateConditionLike(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value;
+  return typeof candidate.device === "string" && typeof candidate.field === "string" && typeof candidate.op === "string";
+}
+function collectConditionDeviceRefs(condition, path26) {
+  if (!condition || typeof condition !== "object" || Array.isArray(condition)) return [];
+  const out = [];
+  if (isDeviceStateConditionLike(condition)) {
+    out.push({ path: `${path26}/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], `${path26}/all/${i}`));
+    }
+  }
+  if (Array.isArray(candidate.any)) {
+    for (let i = 0; i < candidate.any.length; i++) {
+      out.push(...collectConditionDeviceRefs(candidate.any[i], `${path26}/any/${i}`));
+    }
+  }
+  if (candidate.not !== void 0) {
+    out.push(...collectConditionDeviceRefs(candidate.not, `${path26}/not`));
+  }
+  return out;
+}
 function collectDestructiveRuleErrors(loaded) {
   const data = loaded.data;
   const rules = data?.automation?.rules;
@@ -45604,6 +46015,258 @@ function collectDestructiveRuleErrors(loaded) {
   }
   return out;
 }
+function collectOfflineSemanticErrors(loaded, existingErrors) {
+  const data = loaded.data;
+  const out = [];
+  const aliases = collectAliasMap(data);
+  for (const [aliasName, deviceId] of Object.entries(aliases)) {
+    const path26 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
+    if (hasErrorAtPath(existingErrors, path26)) continue;
+    if (isPlausibleDeviceId(deviceId)) continue;
+    const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path26);
+    out.push({
+      path: path26,
+      line,
+      col,
+      keyword: "alias-device-id",
+      message: `alias "${aliasName}" does not point to a plausible SwitchBot deviceId`,
+      hint: "use a deviceId from `switchbot devices list --format=tsv`, e.g. 01-202407090924-26354212 or 28372F4C9C4A",
+      schemaPath: "#/properties/aliases"
+    });
+  }
+  const knownDeviceCommands = new Set(
+    getEffectiveCatalog().flatMap((entry) => entry.commands).filter((spec) => spec.commandType !== "customize").map((spec) => spec.command)
+  );
+  const rules = data?.automation?.rules;
+  if (!Array.isArray(rules)) return out;
+  for (let ri = 0; ri < rules.length; ri++) {
+    const rule = rules[ri];
+    const ruleName = typeof rule?.name === "string" ? rule.name : `#${ri}`;
+    if (typeof rule?.when?.device === "string") {
+      const whenDevicePath = `/automation/rules/${ri}/when/device`;
+      const resolved = resolvePolicyDeviceRef(rule.when.device, aliases);
+      if (!resolved.ok) {
+        const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, whenDevicePath);
+        out.push({
+          path: whenDevicePath,
+          line,
+          col,
+          keyword: resolved.reason ?? "unknown-device-ref",
+          message: `rule "${ruleName}" trigger references unknown device "${rule.when.device}"`,
+          hint: "set `when.device` to a declared alias or a plausible deviceId",
+          schemaPath: "#/properties/automation/properties/rules/items/properties/when/properties/device"
+        });
+      }
+    }
+    const conditions = Array.isArray(rule?.conditions) ? rule.conditions : [];
+    for (let ci = 0; ci < conditions.length; ci++) {
+      for (const ref of collectConditionDeviceRefs(conditions[ci], `/automation/rules/${ri}/conditions/${ci}`)) {
+        const resolved = resolvePolicyDeviceRef(ref.ref, aliases);
+        if (!resolved.ok) {
+          const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, ref.path);
+          out.push({
+            path: ref.path,
+            line,
+            col,
+            keyword: resolved.reason ?? "unknown-device-ref",
+            message: `rule "${ruleName}" condition references unknown device "${ref.ref}"`,
+            hint: "set condition `device` to a declared alias or a plausible deviceId",
+            schemaPath: "#/properties/automation/properties/rules/items/properties/conditions"
+          });
+        }
+      }
+    }
+    const actions = Array.isArray(rule?.then) ? rule.then : [];
+    for (let ai = 0; ai < actions.length; ai++) {
+      const action = actions[ai];
+      const cmd = action?.command;
+      if (typeof cmd !== "string") continue;
+      const commandPath = `/automation/rules/${ri}/then/${ai}/command`;
+      const devicePath = `/automation/rules/${ri}/then/${ai}/device`;
+      const parsed = parseRuleCommand(cmd);
+      if (!parsed) {
+        const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, commandPath);
+        out.push({
+          path: commandPath,
+          line,
+          col,
+          keyword: "rule-unparseable-command",
+          message: `rule "${ruleName}" action #${ai} must use \`devices command <id> <verb> [parameter...]\``,
+          hint: "automation rules currently support only `devices command ...` actions; scenes/webhooks/other subcommands are not executable here",
+          schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/command"
+        });
+        continue;
+      }
+      if (!knownDeviceCommands.has(parsed.verb)) {
+        const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, commandPath);
+        out.push({
+          path: commandPath,
+          line,
+          col,
+          keyword: "rule-unknown-command",
+          message: `rule "${ruleName}" action #${ai} uses unknown device command "${parsed.verb}"`,
+          hint: "check `switchbot devices commands <type>` for valid verbs; this validator only checks offline catalog verbs, not the real target device",
+          schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/command"
+        });
+      }
+      if (typeof action?.device === "string") {
+        const resolved2 = resolvePolicyDeviceRef(action.device, aliases);
+        if (!resolved2.ok) {
+          const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, devicePath);
+          out.push({
+            path: devicePath,
+            line,
+            col,
+            keyword: resolved2.reason ?? "unknown-device-ref",
+            message: `rule "${ruleName}" action #${ai} references unknown device "${action.device}"`,
+            hint: "set `device:` to a declared alias or a plausible deviceId",
+            schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/device"
+          });
+        }
+        continue;
+      }
+      const resolved = resolvePolicyDeviceRef(parsed.deviceIdSlot ?? void 0, aliases);
+      if (!resolved.ok) {
+        const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, commandPath);
+        out.push({
+          path: commandPath,
+          line,
+          col,
+          keyword: resolved.reason ?? "missing-device",
+          message: resolved.reason === "missing-device" ? `rule "${ruleName}" action #${ai} uses \`<id>\` but does not provide \`device:\`` : `rule "${ruleName}" action #${ai} references unknown device "${parsed.deviceIdSlot}"`,
+          hint: resolved.reason === "missing-device" ? "either replace `<id>` with a deviceId/alias or add `device: <alias-or-deviceId>` to the action" : "use a declared alias or a plausible deviceId in the command slot",
+          schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/command"
+        });
+      }
+    }
+  }
+  return out;
+}
+function resolveInventoryDeviceId(raw, aliases) {
+  if (!raw || raw === "<id>") return null;
+  if (Object.hasOwn(aliases, raw)) return aliases[raw];
+  return raw;
+}
+function validateLoadedPolicyAgainstInventory(loaded, inventory) {
+  const base = validateLoadedPolicy(loaded);
+  const errors = [...base.errors];
+  const aliases = collectAliasMap(loaded.data);
+  const inventoryById = /* @__PURE__ */ new Map();
+  for (const device of inventory.deviceList) {
+    inventoryById.set(device.deviceId, { typeName: device.deviceType ?? "" });
+  }
+  for (const remote of inventory.infraredRemoteList) {
+    inventoryById.set(remote.deviceId, { typeName: remote.remoteType });
+  }
+  for (const [aliasName, deviceId] of Object.entries(aliases)) {
+    const path26 = `/aliases/${escapeJsonPointerSegment(aliasName)}`;
+    if (hasErrorAtPath(errors, path26)) continue;
+    if (!inventoryById.has(deviceId)) {
+      const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, path26);
+      errors.push({
+        path: path26,
+        line,
+        col,
+        keyword: "alias-live-device-not-found",
+        message: `alias "${aliasName}" points to deviceId "${deviceId}" which is not present in the current inventory`,
+        hint: "refresh with `switchbot devices list` and confirm the alias target still exists on this account",
+        schemaPath: "#/properties/aliases"
+      });
+    }
+  }
+  const data = loaded.data;
+  const rules = data?.automation?.rules;
+  if (Array.isArray(rules)) {
+    for (let ri = 0; ri < rules.length; ri++) {
+      const rule = rules[ri];
+      const ruleName = typeof rule?.name === "string" ? rule.name : `#${ri}`;
+      if (typeof rule?.when?.device === "string") {
+        const whenDevicePath = `/automation/rules/${ri}/when/device`;
+        const effectiveDeviceId = resolveInventoryDeviceId(rule.when.device, aliases);
+        if (effectiveDeviceId && !inventoryById.has(effectiveDeviceId)) {
+          const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, whenDevicePath);
+          errors.push({
+            path: whenDevicePath,
+            line,
+            col,
+            keyword: "rule-live-device-not-found",
+            message: `rule "${ruleName}" trigger resolves to deviceId "${effectiveDeviceId}" which is not present in the current inventory`,
+            hint: "confirm `when.device` against `switchbot devices list` before relying on this policy",
+            schemaPath: "#/properties/automation/properties/rules/items/properties/when/properties/device"
+          });
+        }
+      }
+      const conditions = Array.isArray(rule?.conditions) ? rule.conditions : [];
+      for (let ci = 0; ci < conditions.length; ci++) {
+        for (const ref of collectConditionDeviceRefs(conditions[ci], `/automation/rules/${ri}/conditions/${ci}`)) {
+          const effectiveDeviceId = resolveInventoryDeviceId(ref.ref, aliases);
+          if (effectiveDeviceId && !inventoryById.has(effectiveDeviceId)) {
+            const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, ref.path);
+            errors.push({
+              path: ref.path,
+              line,
+              col,
+              keyword: "rule-live-device-not-found",
+              message: `rule "${ruleName}" condition resolves to deviceId "${effectiveDeviceId}" which is not present in the current inventory`,
+              hint: "confirm the condition device against `switchbot devices list` before relying on this policy",
+              schemaPath: "#/properties/automation/properties/rules/items/properties/conditions"
+            });
+          }
+        }
+      }
+      const actions = Array.isArray(rule?.then) ? rule.then : [];
+      for (let ai = 0; ai < actions.length; ai++) {
+        const action = actions[ai];
+        const cmd = action?.command;
+        if (typeof cmd !== "string") continue;
+        const parsed = parseRuleCommand(cmd);
+        if (!parsed) continue;
+        const commandPath = `/automation/rules/${ri}/then/${ai}/command`;
+        const devicePath = `/automation/rules/${ri}/then/${ai}/device`;
+        const effectiveRef = typeof action?.device === "string" ? action.device : parsed.deviceIdSlot ?? void 0;
+        const effectiveDeviceId = resolveInventoryDeviceId(effectiveRef, aliases);
+        if (!effectiveDeviceId) continue;
+        const target = inventoryById.get(effectiveDeviceId);
+        if (!target) {
+          const path26 = typeof action?.device === "string" ? devicePath : commandPath;
+          const { line: line2, col: col2 } = locateInstancePath(loaded.doc, loaded.lineCounter, path26);
+          errors.push({
+            path: path26,
+            line: line2,
+            col: col2,
+            keyword: "rule-live-device-not-found",
+            message: `rule "${ruleName}" action #${ai} resolves to deviceId "${effectiveDeviceId}" which is not present in the current inventory`,
+            hint: "confirm the alias/deviceId against `switchbot devices list` before relying on this policy",
+            schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/device"
+          });
+          continue;
+        }
+        const match = target.typeName ? findCatalogEntry(target.typeName) : null;
+        const entry = !match || Array.isArray(match) ? null : match;
+        if (!entry) continue;
+        const supported = entry.commands.filter((spec) => spec.commandType !== "customize").some((spec) => spec.command === parsed.verb);
+        if (supported) continue;
+        const { line, col } = locateInstancePath(loaded.doc, loaded.lineCounter, commandPath);
+        errors.push({
+          path: commandPath,
+          line,
+          col,
+          keyword: "rule-live-unsupported-command",
+          message: `rule "${ruleName}" action #${ai} uses command "${parsed.verb}" but live target "${effectiveDeviceId}" is type "${target.typeName}"`,
+          hint: `supported offline verbs for ${target.typeName}: ${entry.commands.filter((spec) => spec.commandType !== "customize").map((spec) => spec.command).join(", ")}`,
+          schemaPath: "#/properties/automation/properties/rules/items/properties/then/items/properties/command"
+        });
+      }
+    }
+  }
+  return {
+    ...base,
+    validationScope: "schema+offline-semantics+live-inventory",
+    limitations: [...POLICY_VALIDATION_LIVE_LIMITATIONS],
+    valid: errors.length === 0,
+    errors
+  };
+}
 function validateLoadedPolicy(loaded) {
   const declared = readDeclaredVersion(loaded.data);
   if (declared !== void 0 && !isSupportedPolicySchemaVersion(declared)) {
@@ -45630,11 +46293,14 @@ function validateLoadedPolicy(loaded) {
   if (version2 === "0.2") {
     const ruleErrors = collectDestructiveRuleErrors(loaded);
     errors.push(...ruleErrors);
+    errors.push(...collectOfflineSemanticErrors(loaded, errors));
   }
   const valid = ok === true && errors.length === 0;
   return {
     policyPath: loaded.path,
     schemaVersion: version2,
+    validationScope: "schema+offline-semantics",
+    limitations: [...POLICY_VALIDATION_LIMITATIONS],
     valid,
     errors
   };
@@ -45716,6 +46382,15 @@ var COMMAND_KEYWORDS = [
   { pattern: /\bclose\b|\blower\b|\bdown\b/i, command: "close" },
   { pattern: /\bpause\b/i, command: "pause" }
 ];
+function inferCommandFromIntent(intent) {
+  for (const k2 of COMMAND_KEYWORDS) {
+    if (k2.pattern.test(intent)) return k2.command;
+  }
+  return void 0;
+}
+function containsCjk(intent) {
+  return /[\u3400-\u9FFF]/u.test(intent);
+}
 
 // src/lib/plan-store.ts
 init_cjs_shim();
@@ -45921,14 +46596,13 @@ function validatePlan(raw) {
 }
 function suggestPlan(opts) {
   const warnings = [];
-  let command = "";
-  for (const k2 of COMMAND_KEYWORDS) {
-    if (k2.pattern.test(opts.intent)) {
-      command = k2.command;
-      break;
-    }
-  }
+  let command = inferCommandFromIntent(opts.intent) ?? "";
   if (!command) {
+    if (containsCjk(opts.intent)) {
+      throw new UsageError(
+        `Intent "${opts.intent}" contains non-English command text that this heuristic cannot safely infer. Use explicit English command words (turnOn/turnOff/open/close/lock/unlock/press/pause) or author the plan manually.`
+      );
+    }
     command = "turnOn";
     warnings.push(
       `Could not infer command from intent "${opts.intent}" \u2014 defaulted to "turnOn". Edit the generated plan to set the correct command.`
@@ -45977,7 +46651,7 @@ async function executePlanSteps(plan, planId, options) {
   const out = {
     plan,
     results: [],
-    summary: { total: plan.steps.length, ok: 0, error: 0, skipped: 0 }
+    summary: { total: plan.steps.length, ok: 0, error: 0, skipped: 0, dryRun: 0 }
   };
   for (let i = 0; i < plan.steps.length; i++) {
     const step = plan.steps[i];
@@ -46036,8 +46710,8 @@ async function executePlanSteps(plan, planId, options) {
       if (!isJsonMode()) console.log(`  ${idx}. \u2713 ${step.command} on ${resolvedDeviceId}`);
     } catch (err) {
       if (err instanceof Error && err.name === "DryRunSignal") {
-        out.results.push({ step: idx, type: "command", deviceId: resolvedDeviceId, command: step.command, status: "ok" });
-        out.summary.ok++;
+        out.results.push({ step: idx, type: "command", deviceId: resolvedDeviceId, command: step.command, status: "dry-run" });
+        out.summary.dryRun++;
         if (!isJsonMode()) console.log(`  ${idx}. \u25E6 dry-run ${step.command} on ${resolvedDeviceId}`);
         continue;
       }
@@ -46120,25 +46794,29 @@ against the live API without executing any mutations.
     (v2, prev) => [...prev, v2],
     []
   ).option("--out <file>", "Write plan JSON to file instead of stdout").action((opts) => {
-    if (opts.device.length === 0) {
-      console.error("error: at least one --device is required");
-      process.exit(1);
-    }
-    const devices = opts.device.map((ref) => {
-      const cached2 = getCachedDevice(ref);
-      return { id: ref, name: cached2?.name, type: cached2?.type };
-    });
-    const { plan: suggested, warnings } = suggestPlan({ intent: opts.intent, devices });
-    for (const w2 of warnings) process.stderr.write(`warning: ${w2}
+    try {
+      if (opts.device.length === 0) {
+        console.error("error: at least one --device is required");
+        process.exit(1);
+      }
+      const devices = opts.device.map((ref) => {
+        const cached2 = getCachedDevice(ref);
+        return { id: ref, name: cached2?.name, type: cached2?.type };
+      });
+      const { plan: suggested, warnings } = suggestPlan({ intent: opts.intent, devices });
+      for (const w2 of warnings) process.stderr.write(`warning: ${w2}
 `);
-    const json3 = JSON.stringify(suggested, null, 2);
-    if (opts.out) {
-      fs13.writeFileSync(opts.out, json3 + "\n", "utf8");
-      if (!isJsonMode()) console.log(`\u2713 plan written to ${opts.out}`);
-    } else if (isJsonMode()) {
-      printJson({ plan: suggested, warnings });
-    } else {
-      console.log(json3);
+      const json3 = JSON.stringify(suggested, null, 2);
+      if (opts.out) {
+        fs13.writeFileSync(opts.out, json3 + "\n", "utf8");
+        if (!isJsonMode()) console.log(`\u2713 plan written to ${opts.out}`);
+      } else if (isJsonMode()) {
+        printJson({ plan: suggested, warnings });
+      } else {
+        console.log(json3);
+      }
+    } catch (err) {
+      handleError(err);
     }
   });
   plan.command("run").description("Validate + preview/execute a plan. Respects --dry-run; destructive steps require the reviewed plan flow by default").argument("[file]", 'Path to plan.json, or "-" / omit to read stdin').option("--yes", "Authorize destructive commands (e.g. Smart Lock unlock, Garage open)").option("--require-approval", "Prompt for confirmation before each destructive step (TTY only; mutually exclusive with --json)").option("--continue-on-error", "Keep running after a failed step (default: stop at first error)").action(
@@ -46338,6 +47016,13 @@ summary: ok=${ok} error=${error48} skipped=${skipped} total=${out.summary.total}
 // src/rules/suggest.ts
 init_cjs_shim();
 var import_yaml4 = __toESM(require_dist(), 1);
+init_output();
+function buildSuggestedAction(command, deviceId) {
+  if (deviceId) {
+    return { command: `devices command ${deviceId} ${command}` };
+  }
+  return { command: `devices command <id> ${command}` };
+}
 var TRIGGER_KEYWORDS = [
   { pattern: /\bmotion\b|\bdetect/i, trigger: "mqtt", event: "motion.detected" },
   { pattern: /\bdoor\b|\bcontact\b|\bopen.*sensor/i, trigger: "mqtt", event: "contact.opened" },
@@ -46365,8 +47050,12 @@ function inferSchedule(intent, warnings) {
   return "0 8 * * *";
 }
 function inferCommand(intent, warnings) {
-  for (const k2 of COMMAND_KEYWORDS) {
-    if (k2.pattern.test(intent)) return k2.command;
+  const command = inferCommandFromIntent(intent);
+  if (command) return command;
+  if (containsCjk(intent)) {
+    throw new UsageError(
+      `Intent "${intent}" contains non-English command text that this heuristic cannot safely infer. Use explicit English command words (turnOn/turnOff/open/close/lock/unlock/press/pause) or edit the generated rule manually.`
+    );
   }
   warnings.push(
     `Could not infer command from intent "${intent}" \u2014 defaulted to "turnOn". Edit the generated rule to set the correct command.`
@@ -46375,6 +47064,7 @@ function inferCommand(intent, warnings) {
 }
 function suggestRule(opts) {
   const warnings = [];
+  const cjkIntent = containsCjk(opts.intent);
   let triggerSource = opts.trigger;
   let inferredEvent;
   if (!triggerSource) {
@@ -46382,6 +47072,11 @@ function suggestRule(opts) {
     triggerSource = inferred.trigger;
     inferredEvent = inferred.event;
     if (inferredEvent === "device.shadow") {
+      if (cjkIntent) {
+        throw new UsageError(
+          `Intent "${opts.intent}" contains non-English trigger text that this heuristic cannot safely infer. Re-run with --trigger and, for mqtt rules, --event explicitly.`
+        );
+      }
       warnings.push(
         `Could not infer trigger type from intent "${opts.intent}" \u2014 defaulted to mqtt/device.shadow. Set --trigger and --event explicitly.`
       );
@@ -46397,6 +47092,11 @@ function suggestRule(opts) {
     }
     when = mqttTrigger;
   } else if (triggerSource === "cron") {
+    if (cjkIntent && !opts.schedule) {
+      throw new UsageError(
+        `Intent "${opts.intent}" contains non-English scheduling text that this heuristic cannot safely infer. Re-run with --schedule "<cron>" explicitly.`
+      );
+    }
     const schedule = opts.schedule ?? inferSchedule(opts.intent, warnings);
     const cronTrigger = { source: "cron", schedule };
     if (opts.days && opts.days.length > 0) cronTrigger.days = opts.days;
@@ -46406,10 +47106,7 @@ function suggestRule(opts) {
   }
   const command = inferCommand(opts.intent, warnings);
   const actionDevices = triggerSource === "mqtt" && opts.devices && opts.devices.length > 1 ? opts.devices.slice(1) : opts.devices ?? [];
-  const then = actionDevices.length > 0 ? actionDevices.map((d) => ({
-    command: `devices command <id> ${command}`,
-    device: d.id
-  })) : [{ command: `devices command <id> ${command}` }];
+  const then = actionDevices.length > 0 ? actionDevices.map((d) => buildSuggestedAction(command, d.id)) : [buildSuggestedAction(command)];
   const rule = {
     name: opts.intent,
     when,
@@ -46638,7 +47335,6 @@ function diffPolicyValues(leftDoc, rightDoc, leftSource, rightSource, maxChanges
 }
 
 // src/commands/mcp.ts
-import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { dirname as pathDirname, join as pathJoin } from "node:path";
 import os13 from "node:os";
 import fs15 from "node:fs";
@@ -47480,14 +48176,17 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
     "policy_validate",
     {
       title: "Validate a policy.yaml file",
-      description: "Check a policy file against the embedded JSON Schema (supports v0.1 and v0.2). Returns the validation result with per-error line/col and a hint. When no path is given, reads the resolved default (${SWITCHBOT_POLICY_PATH} or ~/.config/openclaw/switchbot/policy.yaml). Use before relying on aliases/quiet_hours/confirmations so the agent never acts on a broken policy.",
+      description: "Check a policy file against the embedded JSON Schema, offline command/device semantics, and local safety guards. By default this stays offline; set live=true to resolve aliases and rule targets against the current account inventory. It still does not verify commands against live capabilities, current firmware, or other runtime-only device behavior. When no path is given, reads the resolved default (${SWITCHBOT_POLICY_PATH} or ~/.config/openclaw/switchbot/policy.yaml). Use before relying on aliases/quiet_hours/confirmations so the agent never acts on a broken policy.",
       _meta: { agentSafetyTier: "read" },
       inputSchema: external_exports.object({
-        path: external_exports.string().optional().describe("Optional policy file path; defaults to the resolved default path")
+        path: external_exports.string().optional().describe("Optional policy file path; defaults to the resolved default path"),
+        live: external_exports.boolean().optional().describe("When true, also resolve aliases and rule targets against the current account inventory")
       }).strict(),
       outputSchema: {
         policyPath: external_exports.string(),
         schemaVersion: external_exports.string(),
+        validationScope: external_exports.string(),
+        limitations: external_exports.array(external_exports.string()),
         present: external_exports.boolean().describe("false when the file does not exist"),
         valid: external_exports.boolean().nullable().describe("null when present=false"),
         errors: external_exports.array(external_exports.object({
@@ -47501,14 +48200,25 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
         })).describe("Empty when valid or when the file is missing")
       }
     },
-    async ({ path: pathArg }) => {
+    async ({ path: pathArg, live }) => {
       const policyPath = resolvePolicyPath({ flag: pathArg });
       try {
         const loaded = loadPolicyFile(policyPath);
-        const result = validateLoadedPolicy(loaded);
+        let result = validateLoadedPolicy(loaded);
+        if (live) {
+          if (!tryLoadConfig()) {
+            return mcpError("runtime", 151, "policy_validate live=true requires configured SwitchBot credentials.", {
+              hint: "Run 'switchbot config set-token' first, or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET."
+            });
+          }
+          const inventory = await fetchDeviceList(void 0, { bypassCache: true });
+          result = validateLoadedPolicyAgainstInventory(loaded, inventory);
+        }
         const structured = {
           policyPath: result.policyPath,
           schemaVersion: result.schemaVersion,
+          validationScope: result.validationScope,
+          limitations: result.limitations,
           present: true,
           valid: result.valid,
           errors: result.errors
@@ -47522,6 +48232,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
           const structured = {
             policyPath,
             schemaVersion: CURRENT_POLICY_SCHEMA_VERSION,
+            validationScope: "schema+offline-semantics",
+            limitations: [
+              "Does not resolve aliases against the live device inventory.",
+              "Does not verify commands against the real target device, live capabilities, or current firmware."
+            ],
             present: false,
             valid: null,
             errors: []
@@ -47535,6 +48250,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
           const structured = {
             policyPath,
             schemaVersion: CURRENT_POLICY_SCHEMA_VERSION,
+            validationScope: "schema+offline-semantics",
+            limitations: [
+              "Does not resolve aliases against the live device inventory.",
+              "Does not verify commands against the real target device, live capabilities, or current firmware."
+            ],
             present: true,
             valid: false,
             errors: err.yamlErrors.map((e) => ({
@@ -47581,8 +48301,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
           context: { policyPath }
         });
       }
-      const templateUrl = new URL("../policy/examples/policy.example.yaml", import.meta.url);
-      const template = fs15.readFileSync(fileURLToPath2(templateUrl), "utf-8");
+      const template = readPolicyExampleYaml();
       fs15.mkdirSync(pathDirname(policyPath), { recursive: true });
       fs15.writeFileSync(policyPath, template, { encoding: "utf-8" });
       const structured = {
@@ -47601,7 +48320,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
     "policy_migrate",
     {
       title: "Migrate a policy file to the latest supported schema",
-      description: `Upgrades the policy file's schema version in place while preserving comments. Safe by default: if the migrated document would fail schema validation, the file is NOT rewritten and the tool returns status="precheck-failed" with the list of errors. Pass dryRun=true to preview without touching the file. Currently the only supported upgrade path is v0.1 \u2192 v0.2.`,
+      description: 'Rewrites a policy file between schema versions this CLI still supports while preserving comments. Safe by default: if the migrated document would fail schema validation, the file is NOT rewritten and the tool returns status="precheck-failed" with the list of errors. Pass dryRun=true to preview without touching the file. This release only supports v0.2, so legacy v0.1 files are reported as unsupported rather than migrated.',
       _meta: { agentSafetyTier: "action" },
       inputSchema: external_exports.object({
         path: external_exports.string().optional().describe("Optional policy file path; defaults to the resolved default path"),
@@ -47671,10 +48390,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
         };
       }
       if (!SUPPORTED_POLICY_SCHEMA_VERSIONS.includes(fileVersion)) {
+        const isLegacy = fileVersion === "0.1";
         const structured2 = {
           ...base,
           status: "unsupported",
-          message: `policy schema v${fileVersion} is not supported (supports: ${SUPPORTED_POLICY_SCHEMA_VERSIONS.join(", ")})`
+          message: isLegacy ? `policy schema v${fileVersion} is legacy and cannot be migrated by this CLI` : `policy schema v${fileVersion} is not supported (supports: ${SUPPORTED_POLICY_SCHEMA_VERSIONS.join(", ")})`
         };
         return {
           content: [{ type: "text", text: JSON.stringify(structured2, null, 2) }],
@@ -48027,7 +48747,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
         kinds: external_exports.array(external_exports.enum(["command", "rule-fire", "rule-fire-dry", "rule-throttled", "rule-webhook-rejected"])).optional().describe("Filter by entry kind."),
         device_id: external_exports.string().optional().describe("Filter by deviceId."),
         rule_name: external_exports.string().optional().describe("Filter by rule.name (rule-engine entries)."),
-        results: external_exports.array(external_exports.enum(["ok", "error"])).optional().describe("Filter by execution result."),
+        results: external_exports.array(external_exports.enum(["ok", "error", "dry-run"])).optional().describe("Filter by execution result."),
         limit: external_exports.number().int().min(1).max(5e3).optional().describe("Max entries returned from the tail of the filtered set (default 200).")
       }).strict(),
       outputSchema: {
@@ -48080,7 +48800,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
         kinds: external_exports.array(external_exports.enum(["command", "rule-fire", "rule-fire-dry", "rule-throttled", "rule-webhook-rejected"])).optional().describe("Filter by entry kind."),
         device_id: external_exports.string().optional().describe("Filter by deviceId."),
         rule_name: external_exports.string().optional().describe("Filter by rule.name (rule-engine entries)."),
-        results: external_exports.array(external_exports.enum(["ok", "error"])).optional().describe("Filter by execution result."),
+        results: external_exports.array(external_exports.enum(["ok", "error", "dry-run"])).optional().describe("Filter by execution result."),
         top_n: external_exports.number().int().min(1).max(100).optional().describe("Number of top device/rule rows to return (default 10).")
       }).strict(),
       outputSchema: {
@@ -48228,6 +48948,29 @@ function listRegisteredTools(server) {
   if (!internal._registeredTools) return [];
   return Object.keys(internal._registeredTools).sort();
 }
+function listRegisteredResources() {
+  return ["switchbot://events"];
+}
+function printMcpToolDirectory() {
+  const server = createSwitchBotMcpServer();
+  const tools = listRegisteredTools(server).map((name) => ({ name }));
+  const resources = listRegisteredResources().map((uri) => ({ uri }));
+  if (isJsonMode()) {
+    printJson({ tools, resources });
+    return;
+  }
+  console.log("Tools:");
+  for (const tool of tools) {
+    console.log(`  ${tool.name}`);
+  }
+  console.log("");
+  console.log("Resources:");
+  for (const resource of resources) {
+    console.log(`  ${resource.uri}`);
+  }
+  console.log(`
+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:
@@ -48242,9 +48985,10 @@ function registerMcpCommand(program3) {
   - get_device_history      fetch raw JSONL history records for a device
   - query_device_history    filter + page history records with field/time predicates
   - aggregate_device_history compute count/min/max/avg/sum/p50/p95 over history records
-  - policy_validate         check policy.yaml against the embedded schema (v0.1 / v0.2)
+  - policy_validate         check policy.yaml against the embedded schema + offline semantics
+                            (set live=true to resolve aliases and rule targets against current inventory)
   - policy_new              scaffold a starter policy.yaml (action \u2014 confirm first)
-  - policy_migrate          upgrade policy.yaml to the latest schema (action \u2014 preserves comments)
+  - policy_migrate          rewrite policy.yaml between currently supported schemas (action \u2014 preserves comments)
   - policy_diff             compare two policy files with structural + line diff output
   - plan_suggest            draft a Plan JSON from intent + device IDs (heuristic, no LLM)
   - plan_run                validate + execute a Plan JSON document
@@ -48276,6 +49020,8 @@ Example Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
 Inspect locally:
   $ npx @modelcontextprotocol/inspector switchbot mcp serve
 `);
+  mcp.command("tools").description("Print the registered MCP tools in human or JSON form").action(() => printMcpToolDirectory());
+  mcp.command("list-tools").description("Alias of `mcp tools`").action(() => printMcpToolDirectory());
   mcp.command("serve").description("Start the MCP server on stdio (default) or HTTP (--port)").option("--port <n>", "Listen on HTTP instead of stdio (Streamable HTTP transport)", intArg("--port", { min: 1, max: 65535 })).option("--bind <host>", "IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)", stringArg("--bind"), "127.0.0.1").option("--auth-token <token>", "Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)", stringArg("--auth-token")).option("--cors-origin <url>", "Allowed CORS origin(s) for HTTP (repeatable)", stringArg("--cors-origin")).option("--rate-limit <n>", "Max requests per minute per profile (default 60)", intArg("--rate-limit", { min: 1 }), "60").addHelpText("after", `
 Examples:
   $ switchbot mcp serve
@@ -48517,6 +49263,42 @@ process_uptime_seconds ${Math.floor(process.uptime())}
 init_cjs_shim();
 init_output();
 init_quota();
+function runQuotaStatus() {
+  const usage = todayUsage();
+  const history = loadQuota();
+  if (isJsonMode()) {
+    printJson({
+      today: {
+        date: usage.date,
+        total: usage.total,
+        remaining: usage.remaining,
+        dailyLimit: DAILY_QUOTA,
+        endpoints: usage.endpoints
+      },
+      history: history.days
+    });
+    return;
+  }
+  console.log(`Today (${usage.date}):`);
+  console.log(`  Requests used:      ${usage.total} / ${DAILY_QUOTA}`);
+  console.log(`  Remaining budget:   ${usage.remaining}`);
+  if (Object.keys(usage.endpoints).length === 0) {
+    console.log("  (no requests recorded yet)");
+  } else {
+    console.log("  Endpoint breakdown:");
+    const entries = Object.entries(usage.endpoints).sort((a, b2) => b2[1] - a[1]);
+    for (const [endpoint, count] of entries) {
+      console.log(`    ${endpoint.padEnd(48)} ${count}`);
+    }
+  }
+  const otherDays = Object.entries(history.days).filter(([d]) => d !== usage.date).sort((a, b2) => b2[0].localeCompare(a[0]));
+  if (otherDays.length > 0) {
+    console.log("\nRecent history:");
+    for (const [date5, bucket] of otherDays) {
+      console.log(`  ${date5}  ${bucket.total}`);
+    }
+  }
+}
 function registerQuotaCommand(program3) {
   const quota = program3.command("quota").description("Inspect and manage the local SwitchBot API request counter").addHelpText("after", `
 Every request the CLI makes is counted locally in ~/.switchbot/quota.json.
@@ -48534,41 +49316,11 @@ Examples:
   $ switchbot quota status --json
   $ switchbot quota reset
 `);
+  quota.action(() => {
+    runQuotaStatus();
+  });
   quota.command("status").alias("show").description("Show today's usage and the last 7 days (alias: show)").action(() => {
-    const usage = todayUsage();
-    const history = loadQuota();
-    if (isJsonMode()) {
-      printJson({
-        today: {
-          date: usage.date,
-          total: usage.total,
-          remaining: usage.remaining,
-          dailyLimit: DAILY_QUOTA,
-          endpoints: usage.endpoints
-        },
-        history: history.days
-      });
-      return;
-    }
-    console.log(`Today (${usage.date}):`);
-    console.log(`  Requests used:      ${usage.total} / ${DAILY_QUOTA}`);
-    console.log(`  Remaining budget:   ${usage.remaining}`);
-    if (Object.keys(usage.endpoints).length === 0) {
-      console.log("  (no requests recorded yet)");
-    } else {
-      console.log("  Endpoint breakdown:");
-      const entries = Object.entries(usage.endpoints).sort((a, b2) => b2[1] - a[1]);
-      for (const [endpoint, count] of entries) {
-        console.log(`    ${endpoint.padEnd(48)} ${count}`);
-      }
-    }
-    const otherDays = Object.entries(history.days).filter(([d]) => d !== usage.date).sort((a, b2) => b2[0].localeCompare(a[0]));
-    if (otherDays.length > 0) {
-      console.log("\nRecent history:");
-      for (const [date5, bucket] of otherDays) {
-        console.log(`  ${date5}  ${bucket.total}`);
-      }
-    }
+    runQuotaStatus();
   });
   quota.command("reset").description("Delete the local quota counter file").action(() => {
     resetQuota();
@@ -48714,40 +49466,61 @@ Total: ${entries.length} device type(s)  (source: ${source})`);
       handleError(error48);
     }
   });
-  catalog.command("search").description("Fuzzy search the effective catalog by type name, alias, role, or command name").argument("<keyword>", "Substring to match (case-insensitive) against type, alias, role, or command").action((keyword) => {
+  catalog.command("search").description("Fuzzy search the effective catalog by type name, alias, role, or command name").argument("<keyword>", "Substring to match (case-insensitive) against type, alias, role, or command").option("--strict", "Only return entries whose type name matches (skip alias/role/command fallbacks)").action((keyword, options) => {
     try {
       const q = keyword.toLowerCase();
       const entries = getEffectiveCatalog();
-      const hits = entries.filter((e) => {
-        if (e.type.toLowerCase().includes(q)) return true;
-        if ((e.role ?? "").toLowerCase().includes(q)) return true;
-        if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q))) return true;
-        if (e.commands.some((c) => c.command.toLowerCase().includes(q))) return true;
-        return false;
-      });
+      const strict = options.strict === true;
+      const hits = [];
+      for (const e of entries) {
+        const matched = [];
+        const typeHit = e.type.toLowerCase().includes(q);
+        const aliasExact = (e.aliases ?? []).some((a) => a.toLowerCase() === q);
+        const aliasSubstr = (e.aliases ?? []).some((a) => a.toLowerCase().includes(q) && a.toLowerCase() !== q);
+        const roleHit = (e.role ?? "").toLowerCase().includes(q);
+        const cmdMatches = e.commands.filter((c) => c.command.toLowerCase().includes(q)).map((c) => c.command);
+        if (typeHit) matched.push("type");
+        if (aliasExact) matched.push("alias");
+        else if (aliasSubstr) matched.push("alias-only");
+        if (roleHit) matched.push("role");
+        if (cmdMatches.length > 0) matched.push(`commands[${cmdMatches.join(",")}]`);
+        if (strict) {
+          if (!typeHit) continue;
+        } else if (matched.length === 0) {
+          continue;
+        }
+        let tier;
+        if (typeHit || aliasExact) tier = 0;
+        else if (roleHit || cmdMatches.length > 0) tier = 1;
+        else tier = 2;
+        hits.push({ entry: e, tier, matched });
+      }
+      hits.sort((a, b2) => a.tier - b2.tier);
       if (isJsonMode()) {
-        printJson({ query: keyword, matches: hits });
+        printJson({
+          query: keyword,
+          strict,
+          matches: hits.map((h) => ({ ...h.entry, _matchedOn: h.matched, _tier: h.tier }))
+        });
         return;
       }
       if (hits.length === 0) {
-        console.log(`No catalog entries match "${keyword}".`);
+        const suffix = strict ? " (strict mode \u2014 try without --strict)" : "";
+        console.log(`No catalog entries match "${keyword}"${suffix}.`);
         return;
       }
       const fmt = resolveFormat();
-      const headers = ["type", "category", "role", "matched"];
-      const rows = hits.map((e) => {
-        const matched = [];
-        if (e.type.toLowerCase().includes(q)) matched.push("type");
-        if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q))) matched.push("alias");
-        if ((e.role ?? "").toLowerCase().includes(q)) matched.push("role");
-        const cmdMatches = e.commands.filter((c) => c.command.toLowerCase().includes(q)).map((c) => c.command);
-        if (cmdMatches.length > 0) matched.push(`commands[${cmdMatches.join(",")}]`);
-        return [e.type, e.category, e.role ?? "\u2014", matched.join(", ") || "\u2014"];
-      });
+      const headers = ["type", "category", "role", "matched_on"];
+      const rows = hits.map((h) => [
+        h.entry.type,
+        h.entry.category,
+        h.entry.role ?? "\u2014",
+        h.matched.join(", ") || "\u2014"
+      ]);
       renderRows(headers, rows, fmt, resolveFields());
       if (fmt === "table") {
         console.log(`
-${hits.length} match${hits.length === 1 ? "" : "es"} for "${keyword}"`);
+${hits.length} match${hits.length === 1 ? "" : "es"} for "${keyword}"${strict ? " (strict)" : ""}`);
       }
     } catch (error48) {
       handleError(error48);
@@ -49252,6 +50025,13 @@ function extractDeviceId(parsed) {
   if (typeof id === "string" && id.length > 0) return id;
   return null;
 }
+function emitJsonStreamRecord(record2) {
+  const { schemaVersion, ...rest } = record2;
+  printJson({
+    payloadVersion: schemaVersion,
+    ...rest
+  });
+}
 function matchFilterDetail(body, clauses) {
   if (!clauses || clauses.length === 0) return { matched: true, matchedKeys: [] };
   if (!body || typeof body !== "object") return { matched: false, matchedKeys: [] };
@@ -49407,7 +50187,7 @@ Examples:
             if (!ev.matched) return;
             matchedCount++;
             if (isJsonMode()) {
-              printJson(ev);
+              emitJsonStreamRecord(ev);
             } else {
               const when = new Date(ev.t).toLocaleTimeString();
               console.log(`[${when}] ${ev.remote} ${ev.path} ${JSON.stringify(ev.body)}`);
@@ -49554,7 +50334,7 @@ Examples:
       if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
       if (isJsonMode()) {
         const sessionStartAt = (/* @__PURE__ */ new Date()).toISOString();
-        printJson({
+        emitJsonStreamRecord({
           schemaVersion: EVENTS_SCHEMA_VERSION,
           source: "mqtt",
           kind: "control",
@@ -49606,7 +50386,7 @@ Examples:
             payload: parsed
           };
           if (isJsonMode()) {
-            printJson(record2);
+            emitJsonStreamRecord(record2);
           } else {
             console.log(JSON.stringify(record2));
           }
@@ -49638,7 +50418,7 @@ Examples:
           at
         };
         if (isJsonMode()) {
-          printJson(ctl);
+          emitJsonStreamRecord(ctl);
         } else {
           console.log(JSON.stringify(ctl));
         }
@@ -49905,6 +50685,33 @@ Examples:
 
 // src/commands/doctor.ts
 init_catalog();
+
+// src/version-notes.ts
+init_cjs_shim();
+var RELEASE_METADATA = [];
+function semverParts(v2) {
+  const [maj, min, pat] = v2.replace(/-.*$/, "").split(".").map((n) => Number.parseInt(n, 10));
+  return [maj ?? 0, min ?? 0, pat ?? 0];
+}
+function semverCompare(a, b2) {
+  const [aMaj, aMin, aPat] = semverParts(a);
+  const [bMaj, bMin, bPat] = semverParts(b2);
+  if (aMaj !== bMaj) return aMaj < bMaj ? -1 : 1;
+  if (aMin !== bMin) return aMin < bMin ? -1 : 1;
+  if (aPat !== bPat) return aPat < bPat ? -1 : 1;
+  const aPre = a.includes("-");
+  const bPre = b2.includes("-");
+  if (aPre === bPre) return 0;
+  return aPre ? -1 : 1;
+}
+function findBreakingChangeBetween(current, latest) {
+  return RELEASE_METADATA.filter((m2) => m2.breaking && semverCompare(m2.version, current) > 0 && semverCompare(m2.version, latest) <= 0).sort((a, b2) => semverCompare(a.version, b2.version))[0] ?? null;
+}
+function getReleaseMetadata(version2) {
+  return RELEASE_METADATA.find((m2) => m2.version === version2) ?? null;
+}
+
+// src/commands/doctor.ts
 init_keychain();
 init_request_context();
 
@@ -50290,6 +51097,42 @@ function checkCatalogSchema() {
     }
   };
 }
+function checkInventoryConsistency() {
+  const cache2 = loadCache();
+  if (!cache2) {
+    return {
+      name: "inventory",
+      status: "ok",
+      detail: "no local inventory cache \u2014 run 'switchbot devices list' to enable hub-reference checks"
+    };
+  }
+  const dangling = Object.entries(cache2.devices).filter(([, device]) => device.category === "physical").filter(([deviceId, device]) => {
+    const hubDeviceId = device.hubDeviceId;
+    return Boolean(
+      hubDeviceId && hubDeviceId !== "000000000000" && hubDeviceId !== deviceId && !cache2.devices[hubDeviceId]
+    );
+  }).map(([deviceId, device]) => ({
+    deviceId,
+    deviceName: device.name,
+    hubDeviceId: device.hubDeviceId,
+    deviceType: device.type
+  }));
+  if (dangling.length === 0) {
+    return {
+      name: "inventory",
+      status: "ok",
+      detail: `inventory graph consistent across ${Object.keys(cache2.devices).length} cached devices`
+    };
+  }
+  return {
+    name: "inventory",
+    status: "warn",
+    detail: {
+      message: `${dangling.length} device(s) reference a hubDeviceId that is not present in the current inventory`,
+      dangling: dangling.slice(0, 10)
+    }
+  };
+}
 function checkAudit() {
   const p2 = path15.join(os16.homedir(), ".switchbot", "audit.log");
   if (!fs19.existsSync(p2)) {
@@ -50728,6 +51571,26 @@ function checkMcp() {
     };
   }
 }
+function checkReleaseNotes() {
+  const meta4 = getReleaseMetadata(VERSION);
+  if (!meta4 || !meta4.breaking) {
+    return {
+      name: "release-notes",
+      status: "ok",
+      detail: { version: VERSION, message: "no known breaking-change notice for the current release" }
+    };
+  }
+  return {
+    name: "release-notes",
+    status: "warn",
+    detail: {
+      version: VERSION,
+      breaking: true,
+      message: meta4.summary,
+      hint: "If you have scripts pinned to 3.2.x JSON output, update them before rolling this release wider."
+    }
+  };
+}
 var CHECK_REGISTRY = [
   { name: "node", description: "Node.js version compatibility", run: () => checkNodeVersion() },
   { name: "path", description: "switchbot binary reachable on PATH", run: () => checkPathDiscoverability() },
@@ -50736,6 +51599,7 @@ var CHECK_REGISTRY = [
   { name: "profiles", description: "profile definitions valid", run: () => checkProfiles() },
   { name: "catalog", description: "catalog loads", run: () => checkCatalog() },
   { name: "catalog-schema", description: "catalog vs agent-bootstrap version aligned", run: () => checkCatalogSchema() },
+  { name: "inventory", description: "cached inventory graph consistency (hubDeviceId references)", run: () => checkInventoryConsistency() },
   { name: "cache", description: "device cache state", run: () => checkCache() },
   { name: "quota", description: "API quota headroom", run: () => checkQuotaFile() },
   { name: "clock", description: "system clock skew", run: () => checkClockSkew() },
@@ -50745,6 +51609,7 @@ var CHECK_REGISTRY = [
     run: ({ probe }) => probe ? checkMqttProbe() : checkMqtt()
   },
   { name: "mcp", description: "MCP server instantiable + tool count", run: () => checkMcp() },
+  { name: "release-notes", description: "current release breaking-change notice", run: () => checkReleaseNotes() },
   { name: "policy", description: "policy.yaml present + schema-valid (if configured)", run: () => checkPolicy() },
   { name: "audit", description: "recent command errors (last 24h)", run: () => checkAudit() },
   { name: "daemon", description: "daemon state file + runtime status", run: () => checkDaemon() },
@@ -50949,88 +51814,50 @@ function projectFields2(entry, fields) {
   }
   return out;
 }
-function registerSchemaCommand(program3) {
-  const ROLES = ["lighting", "security", "sensor", "climate", "media", "cleaning", "curtain", "fan", "power", "hub", "other"];
-  const CATEGORIES = ["physical", "ir"];
-  const schema2 = program3.command("schema").description("Export the SwitchBot device catalog as structured JSON (for AI agent prompts / tooling)");
-  schema2.command("export").description("Print the catalog as structured JSON (one object per type)").option("--type <type>", 'Restrict to a single device type (e.g. "Strip Light")', stringArg("--type")).option("--types <csv>", "Restrict to multiple device types (comma-separated)", stringArg("--types")).option("--role <role>", "Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other", enumArg("--role", ROLES)).option("--category <cat>", 'Restrict to "physical" or "ir"', enumArg("--category", CATEGORIES)).option("--compact", "Drop descriptions/aliases/example params \u2014 emit ~60% smaller payload. Useful for agent prompts.").option("--used", 'Restrict to device types present in the local devices cache (run "devices list" first)').option("--project <csv>", "Project per-type fields (e.g. --project type,commands,statusFields)", stringArg("--project")).option("--capabilities", "Annotate each device type with CLI command safety metadata (agentSafetyTier, mutating, consumesQuota)").addHelpText("after", `
-Output is always JSON (this command ignores --format). The output is a
-catalog export \u2014 not a formal JSON Schema standard document \u2014 suitable for
-pre-baking LLM prompts or regenerating docs when the catalog changes.
-
-Size tips:
-  --compact --used          Smallest realistic payload for a given account
-                            (< 15 KB on most accounts).
-  --fields type,commands    Strip statusFields / role / etc. when only
-                            commands are needed.
-  --type + --compact        Inspect one type with minimum footprint.
-
-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'),
-                            not on this offline export.
-
-Examples:
-  $ switchbot schema export > catalog.json
-  $ switchbot schema export --compact --used | wc -c   # small prompt-ready payload
-  $ switchbot schema export --type Bot | jq '.data.types[0].commands'
-  $ switchbot schema export --types "Bot,Curtain,Color Bulb"
-  $ switchbot schema export --role lighting | jq '[.data.types[].type]'
-  $ switchbot schema export --role security --category physical
-  $ switchbot schema export --project type,commands,statusFields
-`).action(async (options) => {
-    const catalog = getEffectiveCatalog();
-    let filtered = catalog;
-    if (options.type) {
-      const q = options.type.toLowerCase();
-      filtered = filtered.filter(
-        (e) => e.type.toLowerCase() === q || (e.aliases ?? []).some((a) => a.toLowerCase() === q)
+function runSchemaExport(options) {
+  const catalog = getEffectiveCatalog();
+  let filtered = catalog;
+  if (options.type) {
+    const q = options.type.toLowerCase();
+    filtered = filtered.filter(
+      (e) => e.type.toLowerCase() === q || (e.aliases ?? []).some((a) => a.toLowerCase() === q)
+    );
+  }
+  if (options.types) {
+    const set3 = new Set(options.types.split(",").map((s2) => s2.trim().toLowerCase()).filter(Boolean));
+    filtered = filtered.filter(
+      (e) => set3.has(e.type.toLowerCase()) || (e.aliases ?? []).some((a) => set3.has(a.toLowerCase()))
+    );
+  }
+  if (options.role) {
+    const q = options.role.toLowerCase();
+    filtered = filtered.filter((e) => (e.role ?? "other") === q);
+  }
+  if (options.category) {
+    const q = options.category.toLowerCase();
+    filtered = filtered.filter((e) => e.category === q);
+  }
+  if (options.used) {
+    const cache2 = loadCache();
+    if (cache2) {
+      const usedTypes = new Set(
+        Object.values(cache2.devices).map((d) => d.type.toLowerCase())
       );
-    }
-    if (options.types) {
-      const set3 = new Set(options.types.split(",").map((s2) => s2.trim().toLowerCase()).filter(Boolean));
       filtered = filtered.filter(
-        (e) => set3.has(e.type.toLowerCase()) || (e.aliases ?? []).some((a) => set3.has(a.toLowerCase()))
-      );
-    }
-    if (options.role) {
-      const q = options.role.toLowerCase();
-      filtered = filtered.filter((e) => (e.role ?? "other") === q);
-    }
-    if (options.category) {
-      const q = options.category.toLowerCase();
-      filtered = filtered.filter((e) => e.category === q);
-    }
-    if (options.used) {
-      const cache2 = loadCache();
-      if (cache2) {
-        const usedTypes = new Set(
-          Object.values(cache2.devices).map((d) => d.type.toLowerCase())
-        );
-        filtered = filtered.filter(
-          (e) => usedTypes.has(e.type.toLowerCase()) || (e.aliases ?? []).some((a) => usedTypes.has(a.toLowerCase()))
-        );
-      } else {
-        filtered = [];
-      }
-    }
-    const mapped = options.compact ? filtered.map(toCompactEntry) : filtered.map(toSchemaEntry);
-    const projected = options.project ? mapped.map(
-      (e) => projectFields2(e, options.project.split(",").map((s2) => s2.trim()).filter(Boolean))
-    ) : mapped;
-    let finalTypes = projected;
-    if (options.capabilities) {
-      const { COMMAND_META: COMMAND_META2 } = await Promise.resolve().then(() => (init_capabilities(), capabilities_exports));
-      const devicesMeta = Object.fromEntries(
-        Object.entries(COMMAND_META2).filter(([k2]) => k2.startsWith("devices "))
+        (e) => usedTypes.has(e.type.toLowerCase()) || (e.aliases ?? []).some((a) => usedTypes.has(a.toLowerCase()))
       );
-      finalTypes = finalTypes.map((e) => ({ ...e, commandsMeta: devicesMeta }));
+    } else {
+      filtered = [];
     }
+  }
+  const mapped = options.compact ? filtered.map(toCompactEntry) : filtered.map(toSchemaEntry);
+  const projected = options.project ? mapped.map(
+    (e) => projectFields2(e, options.project.split(",").map((s2) => s2.trim()).filter(Boolean))
+  ) : mapped;
+  const finish = (finalTypes2) => {
     const payload = {
       version: "1.0",
-      types: finalTypes
+      types: finalTypes2
     };
     if (!options.compact) {
       payload.generatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -51063,6 +51890,56 @@ Examples:
       ];
     }
     printJson(payload);
+  };
+  const finalTypes = projected;
+  if (options.capabilities) {
+    return Promise.resolve().then(() => (init_capabilities(), capabilities_exports)).then(({ COMMAND_META: COMMAND_META2 }) => {
+      const devicesMeta = Object.fromEntries(
+        Object.entries(COMMAND_META2).filter(([k2]) => k2.startsWith("devices "))
+      );
+      finish(finalTypes.map((e) => ({ ...e, commandsMeta: devicesMeta })));
+    });
+  }
+  finish(finalTypes);
+}
+function registerSchemaCommand(program3) {
+  const ROLES = ["lighting", "security", "sensor", "climate", "media", "cleaning", "curtain", "fan", "power", "hub", "other"];
+  const CATEGORIES = ["physical", "ir"];
+  const schema2 = program3.command("schema").description("Export the SwitchBot device catalog as structured JSON (for AI agent prompts / tooling)").option("--type <type>", 'Restrict to a single device type (e.g. "Strip Light")', stringArg("--type")).option("--types <csv>", "Restrict to multiple device types (comma-separated)", stringArg("--types")).option("--role <role>", "Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other", enumArg("--role", ROLES)).option("--category <cat>", 'Restrict to "physical" or "ir"', enumArg("--category", CATEGORIES)).option("--compact", "Drop descriptions/aliases/example params \u2014 emit ~60% smaller payload. Useful for agent prompts.").option("--used", 'Restrict to device types present in the local devices cache (run "devices list" first)').option("--project <csv>", "Project per-type fields (e.g. --project type,commands,statusFields)", stringArg("--project")).option("--capabilities", "Annotate each device type with CLI command safety metadata (agentSafetyTier, mutating, consumesQuota)");
+  schema2.action(async (options) => {
+    await runSchemaExport(options);
+  });
+  schema2.command("export").description("Print the catalog as structured JSON (one object per type)").addHelpText("after", `
+Output is always JSON (this command ignores --format). The output is a
+catalog export \u2014 not a formal JSON Schema standard document \u2014 suitable for
+pre-baking LLM prompts or regenerating docs when the catalog changes.
+\`statusFields\` are advisory offline hints; actual live status can differ by
+firmware and device variant.
+
+Size tips:
+  --compact --used          Smallest realistic payload for a given account
+                            (< 15 KB on most accounts).
+  --fields type,commands    Strip statusFields / role / etc. when only
+                            commands are needed.
+  --type + --compact        Inspect one type with minimum footprint.
+
+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'),
+                            not on this offline export.
+
+Examples:
+  $ switchbot schema export > catalog.json
+  $ switchbot schema export --compact --used | wc -c   # small prompt-ready payload
+  $ switchbot schema export --type Bot | jq '.data.types[0].commands'
+  $ switchbot schema export --types "Bot,Curtain,Color Bulb"
+  $ switchbot schema export --role lighting | jq '[.data.types[].type]'
+  $ switchbot schema export --role security --category physical
+  $ switchbot schema export --project type,commands,statusFields
+`).action(async (_options, cmd) => {
+    await runSchemaExport(cmd.optsWithGlobals());
   });
 }
 
@@ -51331,7 +52208,6 @@ var import_yaml8 = __toESM(require_dist(), 1);
 init_output();
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync, mkdirSync, copyFileSync, statSync } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/policy/format.ts
 init_cjs_shim();
@@ -51389,10 +52265,10 @@ function formatValidationResult(result, source, opts = {}) {
 }
 
 // src/commands/policy.ts
+init_config();
 var LATEST_SUPPORTED_VERSION2 = SUPPORTED_POLICY_SCHEMA_VERSIONS[SUPPORTED_POLICY_SCHEMA_VERSIONS.length - 1];
 function readEmbeddedTemplate() {
-  const url2 = new URL("../policy/examples/policy.example.yaml", import.meta.url);
-  return readFileSync3(fileURLToPath3(url2), "utf-8");
+  return readPolicyExampleYaml();
 }
 var PolicyFileExistsError = class extends Error {
   constructor(policyPath) {
@@ -51432,6 +52308,18 @@ function exitPolicyError(kind, message, extra = {}) {
   }
   process.exit(code);
 }
+function validationScopeLine(scope) {
+  if (scope === "schema+offline-semantics+live-inventory") {
+    return "Validation scope: schema + offline semantics + live inventory checks + local safety guards.";
+  }
+  return "Validation scope: schema + offline semantics + local safety guards.";
+}
+function validationNotCheckedLine(scope) {
+  if (scope === "schema+offline-semantics+live-inventory") {
+    return "Not checked: live capabilities, current firmware, and runtime-only device behavior.";
+  }
+  return "Not checked: alias targets against live devices; command support on the real target device, live capabilities, or current firmware.";
+}
 function summarizeChangeValue(v2) {
   if (v2 === null) return "null";
   if (v2 === void 0) return "undefined";
@@ -51450,10 +52338,11 @@ audit log path, and which actions always or never need confirmation.
 Default location: ${DEFAULT_POLICY_PATH}
 
 Subcommands:
-  validate [path]   Check a policy file against the embedded schema
+  validate [path]   Check a policy file against the embedded schema + offline semantics
+                    (add --live to resolve aliases and rule targets against current inventory)
   new [path]        Write a starter policy to the default location (or a given path)
-  migrate [path]    Upgrade a policy file to the latest supported schema
-                    (v${CURRENT_POLICY_SCHEMA_VERSION} \u2192 v${LATEST_SUPPORTED_VERSION2} today; no-op if already current)
+  migrate [path]    Rewrite a policy file between schema versions this CLI still supports
+                    (this build only supports v${CURRENT_POLICY_SCHEMA_VERSION}; legacy v0.1 files cannot be migrated here)
   diff <left> <right>
                     Compare two policy files and print structural + line diff
   add-rule          Append a rule YAML (from stdin) into automation.rules[]
@@ -51482,7 +52371,9 @@ Examples:
   $ switchbot policy diff ./policy.before.yaml ./policy.after.yaml
 `
   );
-  policy.command("validate [path]").description(`Validate a policy.yaml against the embedded v${CURRENT_POLICY_SCHEMA_VERSION} schema`).option("--no-color", "disable ANSI color in human output").option("--no-snippet", "omit the source-line + caret preview").action((pathArg, opts) => {
+  policy.command("validate [path]").description(
+    `Validate a policy.yaml against the embedded v${CURRENT_POLICY_SCHEMA_VERSION} schema, offline semantics, and local safety guards`
+  ).option("--live", "Also resolve aliases and rule target devices against the current account inventory (1 API call)").option("--no-color", "disable ANSI color in human output").option("--no-snippet", "omit the source-line + caret preview").action(async (pathArg, opts) => {
     const policyPath = resolvePolicyPath({ flag: pathArg });
     let loaded;
     try {
@@ -51502,7 +52393,22 @@ Examples:
       }
       exitPolicyError("internal", `unexpected error loading policy: ${String(err)}`);
     }
-    const result = validateLoadedPolicy(loaded);
+    let result = validateLoadedPolicy(loaded);
+    if (opts.live) {
+      if (!tryLoadConfig()) {
+        exitWithError({
+          code: 1,
+          kind: "runtime",
+          message: "policy validate --live requires configured SwitchBot credentials.",
+          extra: {
+            hint: "Run 'switchbot config set-token' first, or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET."
+          }
+        });
+        return;
+      }
+      const inventory = await fetchDeviceList(void 0, { bypassCache: true });
+      result = validateLoadedPolicyAgainstInventory(loaded, inventory);
+    }
     if (isJsonMode()) {
       printJson(result);
       process.exit(result.valid ? 0 : 1);
@@ -51513,10 +52419,13 @@ Examples:
         noSnippet: opts.snippet === false
       })
     );
+    console.log("");
+    console.log(validationScopeLine(result.validationScope));
+    console.log(validationNotCheckedLine(result.validationScope));
     process.exit(result.valid ? 0 : 1);
   });
-  policy.command("new [path]").description("Write a starter policy.yaml (fails if the file exists unless --force)").option("-f, --force", "overwrite an existing policy file").action((pathArg, opts) => {
-    const policyPath = resolvePolicyPath({ flag: pathArg });
+  policy.command("new [path]").description("Write a starter policy.yaml (fails if the file exists unless --force)").option("-o, --output <path>", "write the starter policy to this path (alias of positional [path])").option("-f, --force", "overwrite an existing policy file").action((pathArg, opts) => {
+    const policyPath = resolvePolicyPath({ flag: opts.output ?? pathArg });
     const force = opts.force === true;
     let result;
     try {
@@ -51545,7 +52454,7 @@ Examples:
       console.log(`    2. run \`switchbot policy validate\``);
     }
   });
-  policy.command("migrate [path]").description(`Upgrade a policy file to the latest supported schema (currently v${LATEST_SUPPORTED_VERSION2})`).option("--dry-run", "show what would change without writing the file").option(
+  policy.command("migrate [path]").description(`Rewrite a policy file between schema versions supported by this CLI (currently only v${LATEST_SUPPORTED_VERSION2})`).option("--dry-run", "show what would change without writing the file").option(
     "--to <version>",
     `target schema version (default: ${LATEST_SUPPORTED_VERSION2})`,
     LATEST_SUPPORTED_VERSION2
@@ -51585,8 +52494,9 @@ Examples:
       return;
     }
     if (!SUPPORTED_POLICY_SCHEMA_VERSIONS.includes(fileVersion)) {
-      const message = `policy schema v${fileVersion} is not supported by this CLI (supports: ${SUPPORTED_POLICY_SCHEMA_VERSIONS.join(", ")})`;
-      const hint = "upgrade @switchbot/openapi-cli, or downgrade the policy file to a supported version";
+      const isLegacy = fileVersion === "0.1";
+      const message = isLegacy ? `policy schema v${fileVersion} is legacy and cannot be migrated by this CLI` : `policy schema v${fileVersion} is not supported by this CLI (supports: ${SUPPORTED_POLICY_SCHEMA_VERSIONS.join(", ")})`;
+      const hint = isLegacy ? "use @switchbot/openapi-cli <=2.15 to migrate v0.1 first, then upgrade back to this release" : "upgrade @switchbot/openapi-cli, or downgrade the policy file to a supported version";
       if (isJsonMode())
         emitJsonError({ code: 6, kind: "unsupported-version", ...basePayload, message, hint });
       else {
@@ -52206,183 +53116,6 @@ var ThrottleGate = class {
   }
 };
 
-// src/rules/action.ts
-init_cjs_shim();
-var DEVICES_COMMAND_RE = /^devices\s+command\s+(\S+)\s+(\S+)(?:\s+(.*))?$/;
-function parseRuleCommand(cmd) {
-  const m2 = DEVICES_COMMAND_RE.exec(cmd.trim());
-  if (!m2) return null;
-  const deviceIdSlot = m2[1];
-  const verb = m2[2];
-  const rest = (m2[3] ?? "").trim();
-  return {
-    deviceIdSlot,
-    verb,
-    parameterTokens: rest.length === 0 ? [] : rest.split(/\s+/)
-  };
-}
-function resolveActionDevice(explicit, slot, aliases) {
-  const candidate = explicit ?? (slot && slot !== "<id>" ? slot : null);
-  if (!candidate) return null;
-  if (aliases[candidate]) return aliases[candidate];
-  return candidate;
-}
-function renderParameter(tokens) {
-  if (tokens.length === 0) return void 0;
-  if (tokens.length === 1) return tokens[0];
-  return tokens.join(":");
-}
-async function executeRuleAction(action, ctx) {
-  const parsed = parseRuleCommand(action.command);
-  if (!parsed) {
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId: "unknown",
-      command: action.command,
-      parameter: null,
-      commandType: "command",
-      dryRun: true,
-      result: "error",
-      error: "unparseable-command",
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        fireId: ctx.fireId,
-        reason: "unparseable-command"
-      }
-    });
-    return { ok: false, error: "unparseable-command", blocked: true };
-  }
-  if (isDestructiveCommand2(action.command)) {
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId: resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases) ?? "unknown",
-      command: action.command,
-      parameter: null,
-      commandType: "command",
-      dryRun: true,
-      result: "error",
-      error: `destructive-verb:${parsed.verb}`,
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        fireId: ctx.fireId,
-        reason: `destructive verb "${parsed.verb}" refused at runtime`
-      }
-    });
-    return { ok: false, error: `destructive-verb:${parsed.verb}`, blocked: true, verb: parsed.verb };
-  }
-  const deviceId = resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases);
-  if (!deviceId || deviceId === "<id>") {
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId: "unknown",
-      command: action.command,
-      parameter: null,
-      commandType: "command",
-      dryRun: true,
-      result: "error",
-      error: "missing-device",
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        fireId: ctx.fireId,
-        reason: "action omitted `device` and command used `<id>` placeholder"
-      }
-    });
-    return { ok: false, error: "missing-device", verb: parsed.verb };
-  }
-  const dryRun = ctx.globalDryRun === true || ctx.rule.dry_run === true;
-  const parameter = renderParameter(parsed.parameterTokens);
-  if (dryRun) {
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire-dry",
-      deviceId,
-      command: parsed.verb,
-      parameter: parameter ?? "default",
-      commandType: "command",
-      dryRun: true,
-      result: "ok",
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        matchedDevice: deviceId,
-        fireId: ctx.fireId
-      }
-    });
-    return { ok: true, dryRun: true, deviceId, verb: parsed.verb };
-  }
-  if (ctx.skipApiCall) {
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId,
-      command: parsed.verb,
-      parameter: parameter ?? "default",
-      commandType: "command",
-      dryRun: false,
-      result: "ok",
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        matchedDevice: deviceId,
-        fireId: ctx.fireId,
-        reason: "api-skipped"
-      }
-    });
-    return { ok: true, deviceId, verb: parsed.verb };
-  }
-  try {
-    await executeCommand(deviceId, parsed.verb, parameter, "command", ctx.httpClient);
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId,
-      command: parsed.verb,
-      parameter: parameter ?? "default",
-      commandType: "command",
-      dryRun: false,
-      result: "ok",
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        matchedDevice: deviceId,
-        fireId: ctx.fireId
-      }
-    });
-    return { ok: true, deviceId, verb: parsed.verb };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    writeAudit({
-      t: (/* @__PURE__ */ new Date()).toISOString(),
-      kind: "rule-fire",
-      deviceId,
-      command: parsed.verb,
-      parameter: parameter ?? "default",
-      commandType: "command",
-      dryRun: false,
-      result: "error",
-      error: msg,
-      rule: {
-        name: ctx.rule.name,
-        triggerSource: ctx.rule.when.source,
-        matchedDevice: deviceId,
-        fireId: ctx.fireId
-      }
-    });
-    return { ok: false, error: msg, deviceId, verb: parsed.verb };
-  }
-}
-function extractDeviceIdFromAction(action) {
-  if (action.device) return action.device;
-  const m2 = /\bdevices\s+command\s+(\S+)/.exec(action.command ?? "");
-  return m2 ? m2[1] : null;
-}
-
 // src/rules/cron-scheduler.ts
 init_cjs_shim();
 
@@ -54822,30 +55555,34 @@ function registerSuggest(rules) {
     []
   ).option("--event <type>", "MQTT event name override (e.g. motion.detected)").option("--schedule <cron>", "5-field cron expression override").option("--days <days>", "Weekday filter, comma-separated (e.g. mon,tue,wed,thu,fri)").option("--webhook-path <path>", "Webhook path override (default: /action)").option("--out <file>", "Write YAML to file instead of stdout").action(
     (opts) => {
-      const trigger = opts.trigger;
-      const days = opts.days ? opts.days.split(",").map((d) => d.trim()) : void 0;
-      const devices = opts.device.map((ref) => {
-        const cached2 = getCachedDevice(ref);
-        return { id: ref, name: cached2?.name, type: cached2?.type };
-      });
-      const { rule, ruleYaml, warnings } = suggestRule({
-        intent: opts.intent,
-        trigger,
-        devices,
-        event: opts.event,
-        schedule: opts.schedule,
-        days,
-        webhookPath: opts.webhookPath
-      });
-      for (const w2 of warnings) process.stderr.write(`warning: ${w2}
+      try {
+        const trigger = opts.trigger;
+        const days = opts.days ? opts.days.split(",").map((d) => d.trim()) : void 0;
+        const devices = opts.device.map((ref) => {
+          const cached2 = getCachedDevice(ref);
+          return { id: ref, name: cached2?.name, type: cached2?.type };
+        });
+        const { rule, ruleYaml, warnings } = suggestRule({
+          intent: opts.intent,
+          trigger,
+          devices,
+          event: opts.event,
+          schedule: opts.schedule,
+          days,
+          webhookPath: opts.webhookPath
+        });
+        for (const w2 of warnings) process.stderr.write(`warning: ${w2}
 `);
-      if (opts.out) {
-        fs21.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 });
-      } else {
-        process.stdout.write(ruleYaml);
+        if (opts.out) {
+          fs21.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 });
+        } else {
+          process.stdout.write(ruleYaml);
+        }
+      } catch (err) {
+        handleError(err);
       }
     }
   );
@@ -56221,19 +56958,129 @@ function resolveStatusSyncRuntime(options) {
   }
   const openclawToken = options.openclawToken ?? process.env.OPENCLAW_TOKEN;
   if (!openclawToken) {
-    throw new UsageError("--openclaw-token is required or set OPENCLAW_TOKEN in the environment.");
+    throw new UsageError(
+      [
+        "OpenClaw token missing. Provide one of:",
+        "  1. --openclaw-token <token>",
+        "  2. OPENCLAW_TOKEN=<token> in the environment",
+        "",
+        "The token is issued by your OpenClaw server admin (same token you use for `events mqtt-tail --sink openclaw`).",
+        "After setting it, re-run the command and verify with `switchbot status-sync status`."
+      ].join("\n")
+    );
   }
   const openclawModel = options.openclawModel ?? process.env.OPENCLAW_MODEL;
   if (!openclawModel) {
-    throw new UsageError("--openclaw-model is required or set OPENCLAW_MODEL in the environment.");
+    throw new UsageError(
+      [
+        "OpenClaw model missing. Provide one of:",
+        "  1. --openclaw-model <model>",
+        "  2. OPENCLAW_MODEL=<model> in the environment",
+        "",
+        "The model name maps this CLI to a registered agent/device on the OpenClaw side.",
+        "After setting it, re-run the command and verify with `switchbot status-sync status`."
+      ].join("\n")
+    );
+  }
+  const openclawUrl = options.openclawUrl ?? process.env.OPENCLAW_URL ?? DEFAULT_OPENCLAW_URL;
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(openclawUrl);
+  } catch {
+    throw new UsageError(
+      [
+        `OpenClaw URL is invalid: ${openclawUrl}`,
+        "Provide a full http:// or https:// URL via one of:",
+        "  1. --openclaw-url <url>",
+        "  2. OPENCLAW_URL=<url> in the environment",
+        "",
+        "After fixing it, re-run the command and verify with `switchbot status-sync status`."
+      ].join("\n")
+    );
+  }
+  if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+    throw new UsageError(
+      [
+        `OpenClaw URL must use http:// or https:// (received ${parsedUrl.protocol})`,
+        "Provide a full http:// or https:// URL via one of:",
+        "  1. --openclaw-url <url>",
+        "  2. OPENCLAW_URL=<url> in the environment"
+      ].join("\n")
+    );
   }
   return {
-    openclawUrl: options.openclawUrl ?? process.env.OPENCLAW_URL ?? DEFAULT_OPENCLAW_URL,
+    openclawUrl,
     openclawToken,
     openclawModel,
     ...options.topic ? { topic: options.topic } : {}
   };
 }
+async function probeStatusSyncStart(options = {}) {
+  const runtime = resolveStatusSyncRuntime(options);
+  const config2 = tryLoadConfig();
+  if (!config2) {
+    throw new UsageError(
+      "No credentials found. Run 'switchbot config set-token' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET."
+    );
+  }
+  const { fetchMqttCredential: fetchMqttCredential2 } = await Promise.resolve().then(() => (init_credential(), credential_exports));
+  let mqttBrokerUrl = "";
+  let mqttRegion = "";
+  try {
+    const cred = await fetchMqttCredential2(config2.token, config2.secret);
+    mqttBrokerUrl = cred.brokerUrl;
+    mqttRegion = cred.region;
+  } catch (err) {
+    throw new UsageError(
+      [
+        "SwitchBot MQTT credential probe failed.",
+        `Reason: ${err instanceof Error ? err.message : String(err)}`,
+        "Verify SWITCHBOT_TOKEN / SWITCHBOT_SECRET first, then re-run `switchbot status-sync start --probe`."
+      ].join("\n")
+    );
+  }
+  const probeUrl = `${runtime.openclawUrl.replace(/\/$/, "")}/v1/chat/completions`;
+  let res;
+  try {
+    res = await fetch(probeUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${runtime.openclawToken}`
+      },
+      body: JSON.stringify({
+        model: runtime.openclawModel,
+        messages: [{ role: "user", content: "status-sync probe" }]
+      }),
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch (err) {
+    throw new UsageError(
+      [
+        `OpenClaw probe failed for ${probeUrl}.`,
+        `Reason: ${err instanceof Error ? err.message : String(err)}`,
+        "Check URL reachability, TLS/certificate trust, and whether the OpenClaw server is listening."
+      ].join("\n")
+    );
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const preview = body ? ` \u2014 ${body.slice(0, 200).replace(/\s+/g, " ").trim()}` : "";
+    const hint = res.status === 401 || res.status === 403 ? "OpenClaw rejected the token. Verify --openclaw-token / OPENCLAW_TOKEN against the server admin." : res.status === 404 ? "OpenClaw returned 404 for /v1/chat/completions. Confirm the base URL does not already include that path, and that the server exposes an OpenAI-compatible endpoint." : res.status === 400 || res.status === 422 ? "OpenClaw rejected the request body. The model name may not be registered; verify --openclaw-model / OPENCLAW_MODEL." : res.status >= 500 ? "OpenClaw returned a server error. Retry, and if it persists check the server logs." : "Unexpected status; inspect the response body above for details.";
+    throw new UsageError(
+      [
+        `OpenClaw probe failed for ${probeUrl}.`,
+        `Reason: HTTP ${res.status} ${res.statusText}${preview}`,
+        hint
+      ].join("\n")
+    );
+  }
+  return {
+    openclawUrl: runtime.openclawUrl,
+    mqttBrokerUrl,
+    mqttRegion
+  };
+}
 function resolveStatusSyncPaths(explicitStateDir) {
   const stateDir = path23.resolve(
     explicitStateDir ?? process.env.SWITCHBOT_STATUS_SYNC_HOME ?? path23.join(os23.homedir(), ".switchbot", "status-sync")
@@ -56507,12 +57354,21 @@ Examples:
       handleError(error48);
     }
   });
-  statusSync.command("start").description("Start the background status-sync bridge").option("--openclaw-url <url>", "OpenClaw gateway URL (default: http://localhost:18789)", stringArg("--openclaw-url")).option("--openclaw-token <token>", "Bearer token for OpenClaw (or env OPENCLAW_TOKEN)", stringArg("--openclaw-token")).option("--openclaw-model <id>", "OpenClaw agent model ID to route events to (or env OPENCLAW_MODEL)", stringArg("--openclaw-model")).option("--topic <pattern>", "MQTT topic filter (default: SwitchBot shadow topic from credential)", stringArg("--topic")).option("--state-dir <path>", "Override the status-sync state directory (or env SWITCHBOT_STATUS_SYNC_HOME)", stringArg("--state-dir")).option("--force", "Stop any existing status-sync bridge before starting a new one").addHelpText(
+  statusSync.command("start").description("Start the background status-sync bridge").option("--openclaw-url <url>", "OpenClaw gateway URL (default: http://localhost:18789)", stringArg("--openclaw-url")).option("--openclaw-token <token>", "Bearer token for OpenClaw (or env OPENCLAW_TOKEN)", stringArg("--openclaw-token")).option("--openclaw-model <id>", "OpenClaw agent model ID to route events to (or env OPENCLAW_MODEL)", stringArg("--openclaw-model")).option("--topic <pattern>", "MQTT topic filter (default: SwitchBot shadow topic from credential)", stringArg("--topic")).option("--state-dir <path>", "Override the status-sync state directory (or env SWITCHBOT_STATUS_SYNC_HOME)", stringArg("--state-dir")).option("--force", "Stop any existing status-sync bridge before starting a new one").option("--probe", "Perform online preflight: fetch MQTT credentials and probe the OpenClaw URL before spawning").addHelpText(
     "after",
     `
 Starts a detached child process that runs:
   switchbot status-sync run ...
 
+Local preflight before spawning:
+  - SwitchBot credentials must be configured
+  - OpenClaw token + model must be present
+  - OpenClaw URL must parse as http:// or https://
+
+Optional online preflight with --probe:
+  - fetch MQTT credentials from SwitchBot
+  - perform a short HTTP probe against the OpenClaw URL
+
 State files:
   state.json   process metadata (pid, startedAt, command)
   stdout.log   redirected stdout from the child process
@@ -56523,8 +57379,11 @@ Examples:
   $ OPENCLAW_TOKEN=abc OPENCLAW_MODEL=home-agent switchbot status-sync start
   $ switchbot status-sync start --state-dir ~/.switchbot/custom-status-sync --force
 `
-  ).action((options) => {
+  ).action(async (options) => {
     try {
+      if (options.probe) {
+        await probeStatusSyncStart(options);
+      }
       const status = startStatusSync(options);
       if (isJsonMode()) {
         printJson(status);
@@ -56661,6 +57520,46 @@ function toPrometheusText(report) {
 // src/commands/health.ts
 init_arg_parsers();
 var HEALTHZ_SCHEMA_VERSION = "1.1";
+function runHealthCheck(opts) {
+  const report = getHealthReport(opts.auditLog);
+  if (opts.prometheus) {
+    process.stdout.write(toPrometheusText(report));
+    return;
+  }
+  if (isJsonMode()) {
+    printJson(report);
+    return;
+  }
+  const statusEmoji = report.overall === "ok" ? "\u2713" : report.overall === "degraded" ? "\u26A0" : "\u2717";
+  console.log(`${statusEmoji} overall: ${report.overall}  (${report.generatedAt})`);
+  console.log("");
+  printTable(
+    ["Component", "Status", "Detail"],
+    [
+      [
+        "quota",
+        report.quota.status,
+        `${report.quota.used}/${report.quota.limit} (${report.quota.percentUsed}% used, ${report.quota.remaining} remaining)`
+      ],
+      [
+        "audit",
+        report.audit.status,
+        report.audit.present ? `${report.audit.recentErrors}/${report.audit.recentTotal} errors in 24h (${report.audit.errorRatePercent}%)` : "log not present"
+      ],
+      [
+        "circuit",
+        report.circuit.status,
+        `${report.circuit.name}: ${report.circuit.state} (failures: ${report.circuit.failures})`
+      ],
+      [
+        "process",
+        "ok",
+        `pid ${report.process.pid} \xB7 uptime ${report.process.uptimeSeconds}s \xB7 mem ${report.process.memoryMb}MB`
+      ]
+    ]
+  );
+  if (report.overall !== "ok") process.exit(1);
+}
 function createHealthHandler(auditLogPath) {
   return (req, res) => {
     const url2 = (req.url ?? "/").split("?")[0];
@@ -56680,48 +57579,14 @@ function createHealthHandler(auditLogPath) {
   };
 }
 function registerHealthCommand(program3) {
-  const health = program3.command("health").description("Report process health: quota, audit error rate, circuit breaker state.");
-  health.command("check").description("Print a one-shot health report.").option("--prometheus", "Emit Prometheus text format.").option("--audit-log <path>", "Audit log path (default: ~/.switchbot/audit.log).").action((opts) => {
-    const report = getHealthReport(opts.auditLog);
-    if (opts.prometheus) {
-      process.stdout.write(toPrometheusText(report));
-      return;
-    }
-    if (isJsonMode()) {
-      printJson(report);
-      return;
-    }
-    const statusEmoji = report.overall === "ok" ? "\u2713" : report.overall === "degraded" ? "\u26A0" : "\u2717";
-    console.log(`${statusEmoji} overall: ${report.overall}  (${report.generatedAt})`);
-    console.log("");
-    printTable(
-      ["Component", "Status", "Detail"],
-      [
-        [
-          "quota",
-          report.quota.status,
-          `${report.quota.used}/${report.quota.limit} (${report.quota.percentUsed}% used, ${report.quota.remaining} remaining)`
-        ],
-        [
-          "audit",
-          report.audit.status,
-          report.audit.present ? `${report.audit.recentErrors}/${report.audit.recentTotal} errors in 24h (${report.audit.errorRatePercent}%)` : "log not present"
-        ],
-        [
-          "circuit",
-          report.circuit.status,
-          `${report.circuit.name}: ${report.circuit.state} (failures: ${report.circuit.failures})`
-        ],
-        [
-          "process",
-          "ok",
-          `pid ${report.process.pid} \xB7 uptime ${report.process.uptimeSeconds}s \xB7 mem ${report.process.memoryMb}MB`
-        ]
-      ]
-    );
-    if (report.overall !== "ok") process.exit(1);
+  const health = program3.command("health").description("Report process health: quota, audit error rate, circuit breaker state.").option("--prometheus", "Emit Prometheus text format.").option("--audit-log <path>", "Audit log path (default: ~/.switchbot/audit.log).");
+  health.action((opts) => {
+    runHealthCheck(opts);
+  });
+  health.command("check").description("Print a one-shot health report.").action((_opts, cmd) => {
+    runHealthCheck(cmd.optsWithGlobals());
   });
-  health.command("serve").description("Start an HTTP server exposing /healthz (JSON) and /metrics (Prometheus).").option("--port <n>", "Port to listen on.", intArg("--port"), "3100").option("--host <host>", "Bind address.", "127.0.0.1").option("--audit-log <path>", "Audit log path.").addHelpText("after", `
+  health.command("serve").description("Start an HTTP server exposing /healthz (JSON) and /metrics (Prometheus).").option("--port <n>", "Port to listen on.", intArg("--port"), "3100").option("--host <host>", "Bind address.", "127.0.0.1").addHelpText("after", `
 Endpoints:
   GET /healthz   JSON health report (HTTP 200 ok/degraded, 503 when circuit is open).
   GET /metrics   Prometheus text metrics.
@@ -56729,7 +57594,8 @@ Endpoints:
 Example:
   $ switchbot health serve --port 3100
   $ curl http://127.0.0.1:3100/healthz
-`).action((opts) => {
+`).action((_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
     const port = parseInt(opts.port, 10);
     const handler = createHealthHandler(opts.auditLog);
     const server = http3.createServer(handler);
@@ -56832,12 +57698,17 @@ function registerUpgradeCheckCommand(program3) {
       }
       return;
     }
+    const breakingNotice = findBreakingChangeBetween(VERSION, latestVersion);
     const result = {
       current: VERSION,
       latest: latestVersion,
       upToDate,
       updateAvailable: !upToDate,
-      breakingChange: latestMajor > currentMajor,
+      breakingChange: latestMajor > currentMajor || breakingNotice !== null,
+      ...breakingNotice ? {
+        breakingVersion: breakingNotice.version,
+        breakingSummary: breakingNotice.summary
+      } : {},
       installCommand: upToDate ? null : `npm install -g ${pkgName}@${latestVersion}`
     };
     if (isJsonMode()) {
@@ -56848,6 +57719,9 @@ function registerUpgradeCheckCommand(program3) {
       console.log(`${source_default.green("\u2713")} You are running the latest version (${VERSION}).`);
     } else {
       console.log(`${source_default.yellow("!")} Update available: ${source_default.bold(VERSION)} \u2192 ${source_default.bold(latestVersion)}`);
+      if (breakingNotice) {
+        console.log(source_default.red(`  Breaking change in ${breakingNotice.version}: ${breakingNotice.summary}`));
+      }
       console.log(`  Run: ${source_default.cyan(`npm install -g ${pkgName}@${latestVersion}`)}`);
       process.exit(1);
     }
@@ -56860,7 +57734,7 @@ init_output();
 import { spawn as spawn5 } from "node:child_process";
 import fs29 from "node:fs";
 import path25 from "node:path";
-import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 init_arg_parsers();
 init_source();
 function readDaemonPid() {
@@ -57010,7 +57884,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       } catch {
       }
     }
-    const thisFile = fileURLToPath4(import.meta.url);
+    const thisFile = fileURLToPath2(import.meta.url);
     const cliEntry = path25.resolve(path25.dirname(thisFile), "..", "index.js");
     const args = ["rules", "run"];
     if (opts.policy) args.push(opts.policy);