@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/commands/mcp.js

@@ -4,12 +4,15 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode } from '../utils/output.js';
+import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { deviceHistoryStore } from '../mcp/device-history.js';
+import { queryDeviceHistory } from '../devices/history-query.js';
+import { aggregateDeviceHistory, ALL_AGG_FNS, MAX_SAMPLE_CAP, } from '../devices/history-agg.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
@@ -32,7 +35,7 @@ export function createSwitchBotMcpServer(options) {
     const eventManager = options?.eventManager;
     const server = new McpServer({
         name: 'switchbot',
-        version: '2.0.0',
+        version: VERSION,
     }, {
         capabilities: { tools: {}, resources: {} },
         instructions: `SwitchBot is an IoT smart home brand by Wonderlabs, Inc. This MCP server controls physical devices \
@@ -59,7 +62,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('list_devices', {
         title: 'List all devices on the account',
         description: 'Fetch the complete inventory of physical devices and IR remotes on this SwitchBot account. Refreshes the local metadata cache and groups devices by type. Use this as the bootstrap call to discover available deviceIds. Devices without enableCloudService cannot receive commands via API. IR remotes depend on a Hub for connectivity.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             deviceList: z.array(z.object({
                 deviceId: z.string(),
@@ -94,9 +98,10 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('get_device_status', {
         title: 'Get live status for a device',
         description: 'Query the real-time status payload for a physical device. IR remotes have no status channel and will error.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
-        },
+        }).strict(),
         outputSchema: {
             status: z.object({
                 deviceId: z.string().optional(),
@@ -118,10 +123,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         description: 'Return device state history recorded from MQTT events (persisted to ~/.switchbot/device-history/). ' +
             'No API call — zero quota cost. Use when you need recent historical readings or want to avoid a live API call. ' +
             'Omit deviceId to list all devices with stored history.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().optional().describe('Device MAC address (deviceId). Omit to list all devices with history.'),
             limit: z.number().int().min(1).max(100).optional().describe('Max history entries to return (default 20, max 100)'),
-        },
+        }).strict(),
         outputSchema: {
             deviceId: z.string().optional(),
             latest: z.unknown().optional(),
@@ -146,11 +152,54 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             structuredContent: result,
         };
     });
+    // ---- query_device_history --------------------------------------------------
+    server.registerTool('query_device_history', {
+        title: 'Query time-ranged device history',
+        description: 'Return records from the append-only JSONL history (~/.switchbot/device-history/<deviceId>.jsonl) ' +
+            'filtered by a relative duration (since) or absolute ISO-8601 range (from/to). ' +
+            'No API call — zero quota cost. Use for trend questions like "how many times did this switch turn on last week".',
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
+            deviceId: z.string().describe('Device ID to query'),
+            since: z.string().optional().describe('Relative window ending now, e.g. "30s", "15m", "1h", "7d". Mutually exclusive with from/to.'),
+            from: z.string().optional().describe('Range start (ISO-8601).'),
+            to: z.string().optional().describe('Range end (ISO-8601).'),
+            fields: z.array(z.string()).optional().describe('Project these payload fields; omit for the full payload.'),
+            limit: z.number().int().min(1).max(10000).optional().describe('Max records to return (default 1000).'),
+        }).strict(),
+        outputSchema: {
+            deviceId: z.string(),
+            count: z.number().int(),
+            records: z.array(z.object({
+                t: z.string(),
+                topic: z.string(),
+                deviceType: z.string().optional(),
+                payload: z.unknown(),
+            })),
+        },
+    }, async ({ deviceId, since, from, to, fields, limit }) => {
+        if (since && (from || to)) {
+            return mcpError('usage', 2, '--since is mutually exclusive with --from/--to.');
+        }
+        try {
+            const records = await queryDeviceHistory(deviceId, { since, from, to, fields, limit });
+            const result = { deviceId, count: records.length, records };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'history query failed';
+            return mcpError('usage', 2, msg);
+        }
+    });
     // ---- send_command ---------------------------------------------------------
     server.registerTool('send_command', {
         title: 'Send a control command to a device',
         description: 'Execute a control command on a device (turnOn, setColor, startClean, unlock, openDoor, createKey, etc.). Destructive commands (Smart Lock unlock, Garage Door open, Keypad createKey/deleteKey) require confirm:true to proceed; otherwise rejected. Commands are validated offline against the device catalog. Use idempotencyKey to safely deduplicate retries within 60 seconds.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'action' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
             command: z.string().describe('Command name, case-sensitive (e.g. turnOn, setColor, unlock)'),
             parameter: z
@@ -167,15 +216,52 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 .optional()
                 .default(false)
                 .describe('Required true for destructive commands (unlock, garage open, createKey, ...)'),
-        },
+            idempotencyKey: z
+                .string()
+                .optional()
+                .describe('Deduplication key — repeat calls with the same key within 60s replay the first result (adds replayed:true). Same key + different (command, parameter) within 60s returns an idempotency_conflict guard error.'),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe('When true, do not call the API — return { ok:true, dryRun:true, wouldSend:{...} } instead.'),
+        }).strict(),
         outputSchema: {
             ok: z.literal(true),
-            command: z.string(),
-            deviceId: z.string(),
-            result: z.unknown().describe('API response body from SwitchBot'),
+            command: z.string().optional(),
+            deviceId: z.string().optional(),
+            result: z.unknown().optional().describe('API response body from SwitchBot (absent on dryRun)'),
+            verification: z
+                .object({
+                verifiable: z.boolean(),
+                reason: z.string(),
+                suggestedFollowup: z.string(),
+            })
+                .optional()
+                .describe('Present when the target is an IR device. IR is unidirectional — agents should treat the success as "signal sent" not "state changed".'),
+            dryRun: z.literal(true).optional().describe('Present when dryRun:true was requested'),
+            wouldSend: z.object({
+                deviceId: z.string(),
+                command: z.string(),
+                parameter: z.unknown(),
+                commandType: z.string(),
+            }).optional().describe('The request shape that would have been POSTed (present when dryRun:true)'),
         },
-    }, async ({ deviceId, command, parameter, commandType, confirm }) => {
+    }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        // dryRun early-return — no API call, no validation against live device list
+        if (dryRun) {
+            const wouldSend = {
+                deviceId,
+                command,
+                parameter: parameter ?? 'default',
+                commandType: effectiveType,
+            };
+            const structured = { ok: true, dryRun: true, wouldSend };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
         // Resolve the device's catalog type via cache or a fresh lookup so we
         // can evaluate destructive/validation without an extra round-trip if
         // the cache is warm.
@@ -217,8 +303,33 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         if (!validation.ok) {
             return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
         }
-        const result = await executeCommand(deviceId, command, parameter, effectiveType);
+        let result;
+        try {
+            result = await executeCommand(deviceId, command, parameter, effectiveType, undefined, {
+                idempotencyKey,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'IdempotencyConflictError') {
+                return mcpError('guard', 2, err.message, {
+                    hint: 'Use a fresh idempotencyKey, or wait for the prior key to expire (60s TTL).',
+                    context: {
+                        existingShape: err.existingShape,
+                        newShape: err.newShape,
+                    },
+                });
+            }
+            throw err;
+        }
+        const isIr = getCachedDevice(deviceId)?.category === 'ir';
         const structured = { ok: true, command, deviceId, result };
+        if (isIr) {
+            structured.verification = {
+                verifiable: false,
+                reason: 'IR transmission is unidirectional; no receipt acknowledgment is possible.',
+                suggestedFollowup: 'Confirm visible change manually or via a paired state sensor.',
+            };
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
             structuredContent: structured,
@@ -228,14 +339,31 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('run_scene', {
         title: 'Execute a manual scene',
         description: 'Execute a manual SwitchBot scene by its sceneId (from list_scenes).',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'action' },
+        inputSchema: z.object({
             sceneId: z.string().describe('Scene ID from list_scenes'),
-        },
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe('When true, do not call the API — return { ok:true, dryRun:true, wouldSend:{...} } instead.'),
+        }).strict(),
         outputSchema: {
             ok: z.literal(true),
-            sceneId: z.string(),
+            sceneId: z.string().optional(),
+            dryRun: z.literal(true).optional().describe('Present when dryRun:true was requested'),
+            wouldSend: z.object({
+                sceneId: z.string(),
+            }).optional().describe('The request shape that would have been POSTed (present when dryRun:true)'),
         },
-    }, async ({ sceneId }) => {
+    }, async ({ sceneId, dryRun }) => {
+        if (dryRun) {
+            const wouldSend = { sceneId };
+            const structured = { ok: true, dryRun: true, wouldSend };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
         await executeScene(sceneId);
         const structured = { ok: true, sceneId };
         return {
@@ -247,7 +375,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('list_scenes', {
         title: 'List all manual scenes',
         description: 'Fetch all manual scenes configured in the SwitchBot app.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             scenes: z.array(z.object({ sceneId: z.string(), sceneName: z.string() })),
         },
@@ -262,10 +391,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('search_catalog', {
         title: 'Search the offline device catalog',
         description: 'Search the built-in device catalog by type name or alias. Returns matching entries with their commands, roles, destructive flags, and status fields. No API call.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             query: z.string().describe('Search query (matches type and aliases, case-insensitive). Use empty string to list all.'),
             limit: z.number().int().min(1).max(100).optional().default(20).describe('Max entries returned (default 20)'),
-        },
+        }).strict(),
         outputSchema: {
             results: z.array(z.object({
                 type: z.string(),
@@ -297,10 +427,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     server.registerTool('describe_device', {
         title: 'Describe a specific device',
         description: 'Resolve a deviceId to its metadata + catalog entry + suggested safe actions. Pass live:true to also fetch real-time status values.',
-        inputSchema: {
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({
             deviceId: z.string().describe('Device ID from list_devices'),
             live: z.boolean().optional().default(false).describe('Also fetch live /status values (costs 1 extra API call)'),
-        },
+        }).strict(),
         outputSchema: {
             device: z.object({
                 device: z.object({ deviceId: z.string(), deviceName: z.string() }).passthrough(),
@@ -338,11 +469,45 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             throw err;
         }
     });
+    // ---- aggregate_device_history --------------------------------------------
+    server.registerTool('aggregate_device_history', {
+        title: 'Aggregate device history',
+        description: 'Bucketed statistics (count/min/max/avg/sum/p50/p95) over JSONL-recorded device history. Read-only; no network calls.',
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z
+            .object({
+            deviceId: z.string().min(1),
+            since: z.string().optional(),
+            from: z.string().optional(),
+            to: z.string().optional(),
+            metrics: z.array(z.string().min(1)).min(1),
+            aggs: z.array(z.enum(ALL_AGG_FNS)).optional(),
+            bucket: z.string().optional(),
+            maxBucketSamples: z.number().int().positive().max(MAX_SAMPLE_CAP).optional(),
+        })
+            .strict(),
+    }, async (args) => {
+        const opts = {
+            since: args.since,
+            from: args.from,
+            to: args.to,
+            metrics: args.metrics,
+            aggs: args.aggs,
+            bucket: args.bucket,
+            maxBucketSamples: args.maxBucketSamples,
+        };
+        const res = await aggregateDeviceHistory(args.deviceId, opts);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(res, null, 2) }],
+            structuredContent: res,
+        };
+    });
     // ---- account_overview ---------------------------------------------------
     server.registerTool('account_overview', {
         title: 'Bootstrap account overview',
         description: 'Get a complete account snapshot: devices, scenes, quota usage, cache status, and MQTT connection state. Use this for cold-start initialization or periodic health checks.',
-        inputSchema: {},
+        _meta: { agentSafetyTier: 'read' },
+        inputSchema: z.object({}).strict(),
         outputSchema: {
             version: z.string(),
             schemaVersion: z.string(),
@@ -393,7 +558,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         const cacheInfo = describeCache();
         const quota = todayUsage();
         const overview = {
-            version: '2.0.0',
+            version: VERSION,
             schemaVersion: '1.1',
             devices: deviceList.deviceList.map(toMcpDeviceListShape),
             infraredRemotes: deviceList.infraredRemoteList.map(toMcpIrDeviceShape),
@@ -454,15 +619,18 @@ export function registerMcpCommand(program) {
         .command('mcp')
         .description('Run as a Model Context Protocol server so AI agents can call SwitchBot tools')
         .addHelpText('after', `
-The MCP server exposes eight tools:
-  - list_devices          fetch all physical + IR devices
-  - get_device_status     live status for a physical device
-  - send_command          control a device (destructive commands need confirm:true)
-  - list_scenes           list all manual scenes
-  - run_scene             execute a manual scene
-  - search_catalog        offline catalog search by type/alias
-  - describe_device       metadata + commands + (optionally) live status for one device
-  - account_overview      single cold-start snapshot: devices + scenes + quota + cache + MQTT state
+The MCP server exposes eleven tools:
+  - list_devices            fetch all physical + IR devices
+  - get_device_status       live status for a physical device
+  - send_command            control a device (destructive commands need confirm:true)
+  - list_scenes             list all manual scenes
+  - run_scene               execute a manual scene
+  - search_catalog          offline catalog search by type/alias
+  - describe_device         metadata + commands + (optionally) live status for one device
+  - account_overview        single cold-start snapshot: devices + scenes + quota + cache + MQTT state
+  - 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
 
 Resource (read-only):
   - switchbot://events    snapshot of recent MQTT shadow events from the ring buffer
@@ -571,7 +739,7 @@ Inspect locally:
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
                             ok: true,
-                            version: '2.0.0',
+                            version: VERSION,
                             pid: process.pid,
                             uptimeSec: Math.floor(process.uptime()),
                         }));
@@ -581,7 +749,7 @@ Inspect locally:
                         const state = eventManager.getState();
                         const ready = state !== 'failed' && state !== 'disabled';
                         const status = ready ? 200 : 503;
-                        const body = { ready, version: '2.0.0', mqtt: state };
+                        const body = { ready, version: VERSION, mqtt: state };
                         if (!ready)
                             body.reason = state === 'disabled' ? 'mqtt disabled' : 'mqtt failed';
                         res.writeHead(status, { 'Content-Type': 'application/json' });

package/dist/commands/plan.js

@@ -182,7 +182,12 @@ Workflow:
         .command('schema')
         .description('Print the JSON Schema for the plan format')
         .action(() => {
-        printJson(PLAN_JSON_SCHEMA);
+        printJson({
+            ...PLAN_JSON_SCHEMA,
+            agentNotes: {
+                deviceNameStrategy: "Plan step `deviceName` fields are resolved with the `require-unique` strategy (same default as `devices command`). Plans that expect a specific device should pin `deviceId` instead.",
+            },
+        });
     });
     plan
         .command('validate')

package/dist/commands/quota.js

@@ -11,17 +11,19 @@ is a best-effort mirror of the SwitchBot 10,000/day limit — it does not
 include requests made outside this CLI (mobile app, other scripts).
 
 Subcommands:
-  status   Show today's usage and the last 7 days
+  status   Show today's usage and the last 7 days (alias: show)
   reset    Delete the local counter file
 
 Examples:
   $ switchbot quota status
+  $ switchbot quota show            # alias of 'status'
   $ switchbot quota status --json
   $ switchbot quota reset
 `);
     quota
         .command('status')
-        .description("Show today's usage and the last 7 days")
+        .alias('show')
+        .description("Show today's usage and the last 7 days (alias: show)")
         .action(() => {
         const usage = todayUsage();
         const history = loadQuota();

package/dist/commands/scenes.js

@@ -1,4 +1,4 @@
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, StructuredUsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 export function registerScenesCommand(program) {
@@ -59,4 +59,46 @@ Example:
             handleError(error);
         }
     });
+    // switchbot scenes describe <sceneId>
+    scenes
+        .command('describe')
+        .description('Show metadata for a scene by its ID (SwitchBot API v1.1 does not expose step detail)')
+        .argument('<sceneId>', 'Scene ID from "scenes list"')
+        .addHelpText('after', `
+Note: SwitchBot API v1.1 does not return scene step detail. Only the scene name is available.
+
+Example:
+  $ switchbot scenes describe T12345678
+`)
+        .action(async (sceneId) => {
+        try {
+            const sceneList = await fetchScenes();
+            const found = sceneList.find((s) => s.sceneId === sceneId);
+            if (!found) {
+                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
+                    error: 'scene_not_found',
+                    sceneId,
+                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
+                });
+            }
+            const result = {
+                sceneId: found.sceneId,
+                sceneName: found.sceneName,
+                stepCount: null,
+                note: 'SwitchBot API v1.1 does not expose scene steps — displayed name only',
+            };
+            if (isJsonMode()) {
+                printJson(result);
+            }
+            else {
+                console.log(`sceneId:   ${result.sceneId}`);
+                console.log(`sceneName: ${result.sceneName}`);
+                console.log(`stepCount: (not available)`);
+                console.log(`note:      ${result.note}`);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/schema.js

@@ -1,6 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
+import { loadCache } from '../devices/cache.js';
 function toSchemaEntry(e) {
     return {
         type: e.type,
@@ -24,6 +25,30 @@ function toSchemaCommand(c) {
         ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
     };
 }
+function toCompactEntry(e) {
+    return {
+        type: e.type,
+        category: e.category,
+        role: e.role ?? null,
+        readOnly: e.readOnly ?? false,
+        commands: e.commands.map((c) => ({
+            command: c.command,
+            parameter: c.parameter,
+            commandType: (c.commandType ?? 'command'),
+            idempotent: Boolean(c.idempotent),
+            destructive: Boolean(c.destructive),
+        })),
+        statusFields: e.statusFields ?? [],
+    };
+}
+function projectFields(entry, fields) {
+    const out = {};
+    for (const f of fields) {
+        if (f in entry)
+            out[f] = entry[f];
+    }
+    return out;
+}
 export function registerSchemaCommand(program) {
     const ROLES = ['lighting', 'security', 'sensor', 'climate', 'media', 'cleaning', 'curtain', 'fan', 'power', 'hub', 'other'];
     const CATEGORIES = ['physical', 'ir'];
@@ -32,20 +57,41 @@ export function registerSchemaCommand(program) {
         .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
     schema
         .command('export')
-        .description('Print the full catalog as structured JSON (one object per type)')
+        .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 — 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'))
         .addHelpText('after', `
 Output is always JSON (this command ignores --format). The output is a
 catalog export — not a formal JSON Schema standard document — 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 --type Bot | jq '.types[0].commands'
-  $ switchbot schema export --role lighting | jq '[.types[].type]'
+  $ 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((options) => {
         const catalog = getEffectiveCatalog();
@@ -55,6 +101,11 @@ Examples:
             filtered = filtered.filter((e) => e.type.toLowerCase() === q ||
                 (e.aliases ?? []).some((a) => a.toLowerCase() === q));
         }
+        if (options.types) {
+            const set = new Set(options.types.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean));
+            filtered = filtered.filter((e) => set.has(e.type.toLowerCase()) ||
+                (e.aliases ?? []).some((a) => set.has(a.toLowerCase())));
+        }
         if (options.role) {
             const q = options.role.toLowerCase();
             filtered = filtered.filter((e) => (e.role ?? 'other') === q);
@@ -63,11 +114,56 @@ Examples:
             const q = options.category.toLowerCase();
             filtered = filtered.filter((e) => e.category === q);
         }
+        if (options.used) {
+            const cache = loadCache();
+            if (cache) {
+                const usedTypes = new Set(Object.values(cache.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) => projectFields(e, options.project.split(',').map((s) => s.trim()).filter(Boolean)))
+            : mapped;
         const payload = {
             version: '1.0',
-            generatedAt: new Date().toISOString(),
-            types: filtered.map(toSchemaEntry),
+            types: projected,
         };
+        if (!options.compact) {
+            payload.generatedAt = new Date().toISOString();
+            payload.cliAddedFields = [
+                {
+                    field: '_fetchedAt',
+                    appliesTo: ['devices status', 'devices describe'],
+                    type: 'string (ISO-8601)',
+                    description: 'CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API.',
+                },
+                {
+                    field: 'replayed',
+                    appliesTo: ['devices command (with --idempotency-key)'],
+                    type: 'boolean',
+                    description: 'CLI-synthesized flag — true when the response was served from the idempotency cache instead of re-executing the command.',
+                },
+                {
+                    field: 'verification',
+                    appliesTo: ['devices command'],
+                    type: 'object',
+                    description: 'CLI-synthesized receipt-acknowledgment metadata. For IR devices, verifiable:false signals that no device-side confirmation is possible.',
+                },
+                {
+                    field: 'hints',
+                    appliesTo: ['agent-bootstrap'],
+                    type: 'string[]',
+                    description: 'CLI-synthesized advisory messages for the calling agent. Always emitted; empty array ([]) means no hints to report — never null and not a disabled-field signal.',
+                },
+            ];
+        }
         printJson(payload);
     });
 }