@switchbot/openapi-cli 3.0.0 → 3.1.0

package/README.md

@@ -64,6 +64,8 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
   - [`plan`](#plan--declarative-batch-operations)
   - [`mcp`](#mcp--model-context-protocol-server)
   - [`doctor`](#doctor--self-check)
+  - [`health`](#health--runtime-health-report)
+  - [`upgrade-check`](#upgrade-check--version-check)
   - [`quota`](#quota--api-request-counter)
   - [`history`](#history--audit-log)
   - [`catalog`](#catalog--device-type-catalog)
@@ -92,7 +94,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 1765 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 1856 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -275,7 +277,7 @@ executes for you. Supported triggers: **MQTT** (device events),
 Supported conditions: `time_between` (quiet hours) and `device_state`
 (live API check with per-tick dedup). Every fire is recorded in
 `~/.switchbot/audit.log`. `rules run` is long-running; use
-`rules reload` to hot-reload policy without dropping listeners.
+`daemon start` / `daemon reload` for the managed background mode.
 
 ```bash
 # 1. Author rules under `automation.rules`. See examples/policies/automation.yaml
@@ -285,16 +287,37 @@ Supported conditions: `time_between` (quiet hours) and `device_state`
 switchbot rules lint                       # exit 0 valid, 1 error
 switchbot rules list --json | jq .         # structured summary
 
-# 3. Run the engine. --dry-run overrides every rule into audit-only mode;
+# 3. Inspect a single rule in full detail (trigger, conditions, actions,
+#    cooldown, hysteresis, maxFiringsPerHour, suppressIfAlreadyDesired, last fired).
+switchbot rules explain "motion on"
+switchbot rules explain "motion on" --json
+
+# 4. Run the engine. --dry-run overrides every rule into audit-only mode;
 #    --max-firings bounds a demo session.
 switchbot rules run --dry-run --max-firings 5
 
-# 4. Edit policy.yaml in another shell, then hot-reload without restart.
-switchbot rules reload                     # SIGHUP on Unix, sentinel file on Windows
+# 5. Edit policy.yaml in another shell, then hot-reload without restart.
+switchbot daemon reload                    # managed daemon reload
 
-# 5. Review recorded fires.
+# 6. Review recorded fires.
 switchbot rules tail --follow              # stream rule-* audit lines
 switchbot rules replay --since 1h --json   # per-rule fires/dries/throttled/errors
+switchbot rules summary                    # aggregate fires/errors per rule (24h window)
+switchbot rules last-fired -n 20           # 20 most recent fire entries
+
+# 7. Conflict and health analysis.
+switchbot rules conflicts                  # opposing actions, high-frequency MQTT,
+                                           # destructive commands, quiet-hours gaps
+switchbot rules doctor --json              # lint + conflicts combined; exit 0 when clean
+```
+
+When `quiet_hours` is configured in `policy.yaml`, `rules conflicts` additionally flags event-driven (MQTT / webhook) rules that lack a `time_between` condition — they would fire uninhibited during the quiet window. The hint in each finding includes a ready-to-paste `time_between` condition to add.
+
+Webhook trigger token management:
+
+```bash
+switchbot rules webhook-rotate-token       # rotate the bearer token for webhook triggers
+switchbot rules webhook-show-token         # print current token (creates one if absent)
 ```
 
 See [`docs/design/phase4-rules.md`](./docs/design/phase4-rules.md) for
@@ -356,6 +379,12 @@ switchbot devices command ABC123 turnOn --dry-run
 switchbot config set-token <token> <secret>   # Save to ~/.switchbot/config.json
 switchbot config show                          # Print current source + masked secret
 switchbot config list-profiles                 # List saved profiles
+
+# Print (or write) the recommended AI-agent profile template
+switchbot config agent-profile                 # print to stdout
+switchbot config agent-profile --write         # write to ~/.switchbot/profiles/agent.json (mode 0600)
+switchbot config agent-profile --write --force # overwrite if it already exists
+switchbot config agent-profile --json          # structured JSON envelope
 ```
 
 ### `devices` — list, status, control
@@ -551,6 +580,10 @@ skipped devices appear under `summary.skipped` with `skippedReason:'offline'`.
 ```bash
 switchbot scenes list                 # Columns: sceneId, sceneName
 switchbot scenes execute <sceneId>
+
+# One-shot summary: risk profile, execution hint, estimated commands
+switchbot scenes explain <sceneId>
+switchbot scenes explain <sceneId> --json
 ```
 
 ### `webhook` — receive device events over HTTP
@@ -743,15 +776,18 @@ switchbot plan validate plan.json
 # Preview — mutations skipped, GETs still execute
 switchbot --dry-run plan run plan.json
 
-# Run — pass --yes to allow destructive steps
-switchbot plan run plan.json --yes
+# Save / review / approve / execute for destructive plans
+switchbot plan save plan.json
+switchbot plan review <planId>
+switchbot plan approve <planId>
+switchbot plan execute <planId>
 switchbot plan run plan.json --continue-on-error
 
 # Run with per-step TTY confirmation for destructive steps (human-in-the-loop)
 switchbot plan run plan.json --require-approval
 ```
 
-A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. `--require-approval` prompts for each destructive step individually, letting you approve or reject without re-running the whole plan. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
+A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. `plan run` is the preview/direct path, but destructive steps are blocked by default and should go through `plan save` → `plan review` → `plan approve` → `plan execute`. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
 
 ### `devices watch` — poll status
 
@@ -792,6 +828,56 @@ switchbot doctor --json
 
 Runs local checks (Node version, credentials, profiles, catalog, cache, quota, clock, MQTT, policy, MCP) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). Use this to diagnose connectivity or config issues before running automation.
 
+`--json` output includes `maturityScore` (0–100) and `maturityLabel` (`production-ready` / `mostly-ready` / `needs-work` / `not-ready`) to give an at-a-glance readiness rating:
+
+```bash
+switchbot doctor --json | jq '{score: .data.maturityScore, label: .data.maturityLabel}'
+```
+
+Pass `--fix --yes` to auto-apply safe fixes (e.g. clear stale cache entries) without a prompt.
+
+### `health` — runtime health report
+
+```bash
+# One-shot report: quota, audit error rate, circuit-breaker state
+switchbot health check
+switchbot health check --prometheus      # Prometheus text format
+switchbot health check --json
+
+# Start a long-running HTTP server with /healthz and /metrics
+switchbot health serve                   # default port 3100, bind 127.0.0.1
+switchbot health serve --port 8080
+switchbot health serve --json            # print {"status":"listening",...} on start
+```
+
+`/healthz` returns a JSON health report (HTTP 200 when `ok`/`degraded`, 503 when circuit is open).
+`/metrics` returns Prometheus text metrics (`switchbot_quota_used_total`, `switchbot_circuit_open`, …).
+Port conflicts are reported immediately with a clear hint to choose a different port via `--port`.
+
+### `upgrade-check` — version check
+
+```bash
+switchbot upgrade-check                      # human output; exits 1 when update available
+switchbot upgrade-check --json               # structured JSON output
+switchbot upgrade-check --timeout 5000       # custom registry timeout (ms)
+```
+
+Queries the npm registry for the latest published version and compares it against the running version.
+`--json` output:
+
+```json
+{
+  "current": "3.2.1",
+  "latest": "4.0.0",
+  "upToDate": false,
+  "updateAvailable": true,
+  "breakingChange": true,
+  "installCommand": "npm install -g @switchbot/openapi-cli@4.0.0"
+}
+```
+
+`breakingChange` is `true` when the latest major version is higher than the current — useful for agents or CI that need to distinguish breaking upgrades from patch releases.
+
 ### `quota` — API request counter
 
 ```bash
@@ -876,6 +962,11 @@ switchbot policy validate --no-snippet             # plain error list, no source
 
 # Report the schema version the file declares
 switchbot policy migrate
+
+# Snapshot and restore the active policy
+switchbot policy backup                            # write timestamped backup alongside policy file
+switchbot policy backup --out ./backups/           # custom destination directory
+switchbot policy restore <backup-file>             # overwrite active policy from backup (auto-backups first)
 ```
 
 Path resolution order: positional `[path]` > `SWITCHBOT_POLICY_PATH` env var > default policy path.
@@ -1005,7 +1096,7 @@ npm install
 
 npm run dev -- <args>       # Run from TypeScript sources via tsx
 npm run build               # Compile to dist/
-npm test                    # Run the Vitest suite (1765 tests)
+npm test                    # Run the Vitest suite (1856 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -1045,6 +1136,8 @@ src/
 │   ├── webhook-listener.ts # HTTP listener (bearer token, localhost-only)
 │   ├── pid-file.ts       # Hot-reload via SIGHUP or sentinel file
 │   ├── audit-query.ts    # Audit log filtering + aggregation
+│   ├── conflict-analyzer.ts # Static conflict detection (opposing actions,
+│   │                     #   high-freq MQTT, destructive cmds, quiet-hours gaps)
 │   ├── suggest.ts        # Heuristic-based rule YAML generation
 │   └── types.ts          # Shared rule/trigger/condition/action types
 ├── status-sync/
@@ -1060,8 +1153,11 @@ src/
 │   ├── device-meta.ts    # `devices meta` — local aliases / hide flags
 │   ├── install.ts        # `switchbot install` / `uninstall`
 │   ├── policy.ts         # `policy validate/new/migrate/diff/add-rule`
-│   ├── rules.ts          # `rules suggest/lint/list/run/reload/tail/replay`
+│   ├── rules.ts          # `rules suggest/lint/list/explain/run/reload/tail/replay/
+│   │                     #   conflicts/doctor/summary/last-fired/webhook-*`
 │   ├── scenes.ts
+│   ├── health.ts         # `health check/serve` — report + HTTP endpoints
+│   ├── upgrade-check.ts  # `upgrade-check` — npm registry version check
 │   ├── status-sync.ts    # `status-sync run/start/stop/status`
 │   ├── webhook.ts
 │   ├── watch.ts          # `devices watch <deviceId>`
@@ -1082,7 +1178,7 @@ src/
     ├── format.ts         # renderRows / filterFields / output-format dispatch
     ├── audit.ts          # JSONL audit log writer
     └── quota.ts          # Local daily-quota counter
-tests/                    # Vitest suite (1765 tests, mocked axios, no network)
+tests/                    # Vitest suite (1856 tests, mocked axios, no network)
 ```
 
 ### Release flow

package/dist/api/client.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { buildAuthHeaders } from '../auth.js';
 import { loadConfig } from '../config.js';
 import { isVerbose, isDryRun, getTimeout, getRetryOn429, getRetryOn5xx, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
-import { nextRetryDelayMs, sleep } from '../utils/retry.js';
+import { nextRetryDelayMs, sleep, CircuitBreaker, CircuitOpenError } from '../utils/retry.js';
 import { recordRequest, checkDailyCap } from '../utils/quota.js';
 import { readProfileMeta } from '../config.js';
 import { getActiveProfile } from '../lib/request-context.js';
@@ -40,6 +40,17 @@ export class DryRunSignal extends Error {
         this.name = 'DryRunSignal';
     }
 }
+/**
+ * Module-level circuit breaker for the SwitchBot API. Shared across all
+ * client instances in the process. Opens after 5 consecutive 5xx / network
+ * errors; resets to half-open after 60 s.
+ * Exported for health-check inspection.
+ */
+export const apiCircuitBreaker = new CircuitBreaker('switchbot-api', {
+    failureThreshold: 5,
+    resetTimeoutMs: 60_000,
+});
+export { CircuitOpenError };
 export function createClient() {
     const { token, secret } = loadConfig();
     const verbose = isVerbose();
@@ -57,6 +68,8 @@ export function createClient() {
     });
     // Inject auth headers; optionally log the request; short-circuit on --dry-run.
     client.interceptors.request.use((config) => {
+        // Circuit breaker check — fail fast when the API is consistently down.
+        apiCircuitBreaker.checkAndAllow();
         // Pre-flight cap check: refuse the call before it touches the network.
         if (dailyCap) {
             const check = checkDailyCap(dailyCap);
@@ -110,6 +123,8 @@ export function createClient() {
                 `API error code: ${data.statusCode}`;
             throw new ApiError(msg, data.statusCode);
         }
+        // Successful HTTP response — record for circuit breaker.
+        apiCircuitBreaker.recordSuccess();
         return response;
     }, (error) => {
         if (error instanceof DryRunSignal)
@@ -131,6 +146,8 @@ export function createClient() {
                         return sleep(delay).then(() => client.request(config));
                     }
                 }
+                // Network-level failure — record for circuit breaker.
+                apiCircuitBreaker.recordFailure();
                 throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: isIdempotentRead });
             }
             const status = error.response?.status;
@@ -165,6 +182,11 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
+            // Record 5xx and network errors for circuit breaker. 4xx errors are
+            // expected business responses — don't count toward circuit threshold.
+            if (status === undefined || status >= 500) {
+                apiCircuitBreaker.recordFailure();
+            }
             // P8: quota already recorded in the request interceptor before
             // dispatch — no extra bookkeeping needed here on the error path.
             // Timeouts, DNS failures, 5xx, and exhausted retries all counted

package/dist/commands/batch.js

@@ -6,6 +6,7 @@ import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js'
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
 import { getCachedTypeMap, getCachedDevice, loadStatusCache } from '../devices/cache.js';
+import { allowsDirectDestructiveExecution, destructiveExecutionHint } from '../lib/destructive-mode.js';
 const DEFAULT_CONCURRENCY = 5;
 const COMMAND_TYPES = ['command', 'customize'];
 /**
@@ -98,7 +99,7 @@ export function registerBatchCommand(devices) {
         .option('--stagger <ms>', 'Fixed delay between task starts in ms (default 0 = random 20-60ms jitter)', intArg('--stagger', { min: 0 }), '0')
         .option('--plan', '[DEPRECATED, use --emit-plan] With --dry-run: emit a plan JSON document instead of executing anything')
         .option('--emit-plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
-        .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
+        .option('--yes', 'Allow destructive commands only from an explicit dev profile')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
         .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key-prefix'))
@@ -134,7 +135,8 @@ Planning:
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
-  Keypad createKey/deleteKey) are blocked by default. Pass --yes to override.
+  Keypad createKey/deleteKey) are blocked by default. Use the reviewed plan
+  flow instead of direct execution.
   --dry-run intercepts every POST and reports the intended calls without
   hitting the API.
 
@@ -142,7 +144,7 @@ Examples:
   $ switchbot devices batch turnOff --filter 'type~=Light,family=home'
   $ switchbot devices batch turnOn --ids ID1,ID2,ID3
   $ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
-  $ switchbot devices batch unlock --filter 'type=Smart Lock' --yes
+  $ switchbot devices batch unlock --filter 'type=Smart Lock' --dry-run --emit-plan
 `)
         .action(async (cmd, parameter, options, commandObj) => {
         // Trailing "-" sentinel selects stdin mode.
@@ -234,10 +236,24 @@ Examples:
                 code: 2,
                 kind: 'guard',
                 message: `Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes: ${deviceIds.join(', ')}`,
-                hint: 'Re-issue the call with --yes to proceed.',
+                hint: 'Re-issue the call with --yes only from an explicit dev profile, or use the reviewed plan flow.',
                 context: { command: cmd, deviceIds },
             });
         }
+        if (blockedForDestructive.length > 0 && options.yes && !allowsDirectDestructiveExecution()) {
+            exitWithError({
+                code: 2,
+                kind: 'guard',
+                message: `Direct destructive execution is disabled for batch command "${cmd}".`,
+                hint: destructiveExecutionHint(),
+                context: {
+                    command: cmd,
+                    blockedCount: blockedForDestructive.length,
+                    deviceIds: blockedForDestructive.map((item) => item.deviceId),
+                    requiredWorkflow: 'plan-approval',
+                },
+            });
+        }
         // parameter may be a JSON object string; mirror the single-command action.
         let parsedParam = parameter ?? 'default';
         if (parameter) {

package/dist/commands/capabilities.js

@@ -28,6 +28,16 @@ const AGENT_GUIDE = {
         action: 'Mutates device or cloud state but is reversible and routine (turnOn, setColor).',
         destructive: 'Hard to reverse / physical-world side effects (unlock, garage open, delete key). Requires explicit user confirmation.',
     },
+    riskLevels: {
+        low: 'Read-only or non-mutating. Safe to call autonomously.',
+        medium: 'Mutates state (action tier). Prefer `plan` workflow. Reversible.',
+        high: 'Destructive / hard-to-reverse. Must go through review-before-execute. Direct --yes execution is reserved for explicit dev profiles.',
+    },
+    recommendedModes: {
+        direct: 'May be called directly without a plan step.',
+        plan: 'Prefer batching in a plan for traceability and dry-run support.',
+        'review-before-execute': 'Must be reviewed/approved before execution. Use `plan save`, `plan review`, `plan approve`, then `plan execute`.',
+    },
     verifiability: {
         local: 'Result is fully verifiable from the CLI return value itself.',
         deviceConfirmed: 'Device returns an ack with an observable state field.',
@@ -35,55 +45,128 @@ const AGENT_GUIDE = {
         none: 'No feedback — e.g. IR transmission. Pair with an external sensor to confirm.',
     },
 };
+function deriveRiskMeta(meta) {
+    const riskLevel = meta.agentSafetyTier === 'destructive' ? 'high'
+        : meta.agentSafetyTier === 'action' ? 'medium' : 'low';
+    return {
+        riskLevel,
+        requiresConfirmation: meta.agentSafetyTier === 'destructive',
+        supportsDryRun: meta.mutating,
+        idempotencyHint: meta.idempotencySupported ? 'safe' : meta.mutating ? 'non-idempotent' : 'safe',
+        recommendedMode: meta.agentSafetyTier === 'destructive' ? 'review-before-execute'
+            : meta.agentSafetyTier === 'action' ? 'plan' : 'direct',
+    };
+}
+function meta(mutating, consumesQuota, idempotencySupported, agentSafetyTier, verifiability, typicalLatencyMs) {
+    return { mutating, consumesQuota, idempotencySupported, agentSafetyTier, verifiability, typicalLatencyMs };
+}
+const READ_LOCAL = meta(false, false, false, 'read', 'local', 20);
+const READ_REMOTE = meta(false, true, false, 'read', 'local', 500);
+const ACTION_LOCAL = meta(true, false, false, 'action', 'local', 20);
+const ACTION_REMOTE = meta(true, true, false, 'action', 'deviceDependent', 900);
+const ACTION_REMOTE_IDEMPOTENT = meta(true, true, true, 'action', 'deviceDependent', 900);
+const DESTRUCTIVE_LOCAL = meta(true, false, false, 'destructive', 'local', 20);
+const DESTRUCTIVE_REMOTE = meta(true, true, false, 'destructive', 'deviceDependent', 1200);
+const READ_NONE = meta(false, false, false, 'read', 'none', 50);
 const COMMAND_META = {
-    // devices: reads
-    'devices list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
-    'devices status': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'devices describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
-    'devices types': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'devices commands': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'devices watch': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    // devices meta (local metadata — no quota, no API call)
-    'devices meta set': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta get': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta list': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    // devices: actions
-    'devices command': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 800 },
-    'devices batch': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1200 },
-    // scenes
-    'scenes list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'scenes execute': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1500 },
-    'scenes describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    // webhook
-    'webhook setup': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 500 },
-    'webhook query': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'webhook delete': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 500 },
-    // quota
-    'quota status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'quota show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'quota reset': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 10 },
-    // doctor / schema / capabilities / catalog / config / cache / events / history / plan
-    'doctor': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 900 },
-    'schema export': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'capabilities': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
-    'catalog': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
-    'config set-token': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 5 },
-    'config show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'config list-profiles': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'cache status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'cache clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    'events mqtt-tail': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'history show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'history replay': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1000 },
-    'history range': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 50 },
-    'history stats': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'history aggregate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 80 },
-    'plan run': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 2000 },
-    'plan validate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'plan schema': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'completion': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'mcp serve': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'agent-bootstrap': READ_LOCAL,
+    'auth keychain describe': READ_LOCAL,
+    'auth keychain get': READ_LOCAL,
+    'auth keychain set': DESTRUCTIVE_LOCAL,
+    'auth keychain delete': DESTRUCTIVE_LOCAL,
+    'auth keychain migrate': DESTRUCTIVE_LOCAL,
+    'cache show': READ_LOCAL,
+    'cache clear': ACTION_LOCAL,
+    'capabilities': READ_LOCAL,
+    'catalog path': READ_LOCAL,
+    'catalog show': READ_LOCAL,
+    'catalog search': READ_LOCAL,
+    'catalog diff': READ_LOCAL,
+    'catalog refresh': ACTION_LOCAL,
+    'completion': READ_LOCAL,
+    'config set-token': DESTRUCTIVE_LOCAL,
+    'config show': READ_LOCAL,
+    'config list-profiles': READ_LOCAL,
+    'config agent-profile': ACTION_LOCAL,
+    'daemon start': ACTION_LOCAL,
+    'daemon stop': ACTION_LOCAL,
+    'daemon status': READ_LOCAL,
+    'daemon reload': ACTION_LOCAL,
+    'devices list': READ_REMOTE,
+    'devices status': READ_REMOTE,
+    'devices command': ACTION_REMOTE_IDEMPOTENT,
+    'devices types': READ_LOCAL,
+    'devices commands': READ_LOCAL,
+    'devices describe': READ_REMOTE,
+    'devices batch': ACTION_REMOTE_IDEMPOTENT,
+    'devices watch': READ_REMOTE,
+    'devices explain': READ_LOCAL,
+    'devices expand': READ_LOCAL,
+    'devices meta set': ACTION_LOCAL,
+    'devices meta get': READ_LOCAL,
+    'devices meta list': READ_LOCAL,
+    'devices meta clear': ACTION_LOCAL,
+    'doctor': READ_LOCAL,
+    'events tail': READ_NONE,
+    'events mqtt-tail': READ_REMOTE,
+    'health check': READ_LOCAL,
+    'health serve': READ_LOCAL,
+    'history show': READ_LOCAL,
+    'history replay': ACTION_REMOTE_IDEMPOTENT,
+    'history range': READ_LOCAL,
+    'history stats': READ_LOCAL,
+    'history verify': READ_LOCAL,
+    'history aggregate': READ_LOCAL,
+    'install': ACTION_LOCAL,
+    'mcp serve': READ_LOCAL,
+    'plan schema': READ_LOCAL,
+    'plan validate': READ_LOCAL,
+    'plan suggest': READ_LOCAL,
+    'plan run': ACTION_REMOTE_IDEMPOTENT,
+    'plan save': ACTION_LOCAL,
+    'plan list': READ_LOCAL,
+    'plan review': READ_LOCAL,
+    'plan approve': DESTRUCTIVE_LOCAL,
+    'plan execute': DESTRUCTIVE_REMOTE,
+    'policy validate': READ_LOCAL,
+    'policy new': ACTION_LOCAL,
+    'policy migrate': ACTION_LOCAL,
+    'policy diff': READ_LOCAL,
+    'policy add-rule': ACTION_LOCAL,
+    'policy backup': READ_LOCAL,
+    'policy restore': DESTRUCTIVE_LOCAL,
+    'quota status': READ_LOCAL,
+    'quota reset': ACTION_LOCAL,
+    'rules suggest': READ_LOCAL,
+    'rules lint': READ_LOCAL,
+    'rules list': READ_LOCAL,
+    'rules run': ACTION_REMOTE,
+    'rules reload': ACTION_LOCAL,
+    'rules tail': READ_LOCAL,
+    'rules replay': READ_LOCAL,
+    'rules webhook-rotate-token': DESTRUCTIVE_LOCAL,
+    'rules webhook-show-token': DESTRUCTIVE_LOCAL,
+    'rules conflicts': READ_LOCAL,
+    'rules doctor': READ_LOCAL,
+    'rules summary': READ_LOCAL,
+    'rules last-fired': READ_LOCAL,
+    'schema export': READ_LOCAL,
+    'scenes list': READ_REMOTE,
+    'scenes execute': ACTION_REMOTE,
+    'scenes describe': READ_REMOTE,
+    'scenes validate': READ_REMOTE,
+    'scenes simulate': READ_REMOTE,
+    'scenes explain': READ_REMOTE,
+    'status-sync run': ACTION_REMOTE,
+    'status-sync start': ACTION_LOCAL,
+    'status-sync stop': ACTION_LOCAL,
+    'status-sync status': READ_LOCAL,
+    'uninstall': ACTION_LOCAL,
+    'upgrade-check': READ_REMOTE,
+    'webhook setup': ACTION_REMOTE,
+    'webhook query': READ_REMOTE,
+    'webhook update': ACTION_REMOTE,
+    'webhook delete': DESTRUCTIVE_REMOTE,
 };
 function metaFor(command) {
     return COMMAND_META[command] ?? null;
@@ -110,27 +193,30 @@ const IDEMPOTENCY_CONTRACT = {
     scope: 'Process-local. Replay + conflict apply within a single long-lived process (MCP session, devices batch, plan run, history replay). Independent CLI invocations do NOT share cache — each fresh `node` process starts empty.',
     mcp: 'MCP send_command accepts the same idempotencyKey field with identical semantics.',
 };
+function enumerateLeafNames(program, prefix = '') {
+    const out = [];
+    for (const cmd of program.commands) {
+        const full = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+        if (cmd.commands.length === 0)
+            out.push(full);
+        else
+            out.push(...enumerateLeafNames(cmd, full));
+    }
+    return out;
+}
+function validateCommandMetaCoverage(program) {
+    const leaves = enumerateLeafNames(program);
+    return leaves.filter((leaf) => !COMMAND_META[leaf]).sort().map((leaf) => `missing:${leaf}`);
+}
 function enumerateLeaves(program, prefix = '') {
     const out = [];
     for (const cmd of program.commands) {
         const full = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
         if (cmd.commands.length === 0) {
             const meta = metaFor(full);
-            if (meta) {
-                out.push({ name: full, ...meta });
-            }
-            else {
-                // Unknown leaf → default to read-safe with a warning flag so agents notice.
-                out.push({
-                    name: full,
-                    mutating: false,
-                    consumesQuota: false,
-                    idempotencySupported: false,
-                    agentSafetyTier: 'read',
-                    verifiability: 'local',
-                    typicalLatencyMs: 50,
-                });
-            }
+            if (!meta)
+                throw new Error(`capabilities metadata missing for leaf command "${full}"`);
+            out.push({ name: full, ...meta, ...deriveRiskMeta(meta) });
         }
         else {
             out.push(...enumerateLeaves(cmd, full));
@@ -157,6 +243,10 @@ export function registerCapabilitiesCommand(program) {
         .option('--surface <s>', 'Restrict surfaces block to one of: cli, mcp, plan, mqtt, all (default: all)', enumArg('--surface', SURFACES))
         .option('--project <csv>', 'Project top-level fields (e.g. --project identity,commands,agentGuide)', stringArg('--project'))
         .action((opts) => {
+        const coverageIssues = validateCommandMetaCoverage(program);
+        if (coverageIssues.length > 0) {
+            throw new Error(`capabilities metadata coverage error: ${coverageIssues.join(', ')}`);
+        }
         const compact = Boolean(opts.minimal || opts.compact);
         const catalog = getEffectiveCatalog();
         const leaves = enumerateLeaves(program);
@@ -246,8 +336,8 @@ export function registerCapabilitiesCommand(program) {
             // Flat command → meta map keyed by full command path. Published in
             // addition to the tree (where every leaf `subcommands[*]` already
             // carries the same fields via spread) so agents can do O(1) lookup
-            // without walking the tree.
-            commandMeta: COMMAND_META,
+            // without walking the tree. Includes derived risk metadata fields.
+            commandMeta: Object.fromEntries(Object.entries(COMMAND_META).map(([k, v]) => [k, { ...v, ...deriveRiskMeta(v) }])),
             ...(globalFlags ? { globalFlags } : {}),
             catalog: {
                 typeCount: catalog.length,