@thinger-io/cli-core 0.4.2 → 0.5.0

package/lib/mcp/catalog.js

@@ -30,6 +30,11 @@ import { inputError } from '../errors.js';
  *
  * A type without `id` is a single resource of its parent (get / update on
  * the path itself).
+ *
+ * The tools locate a record with `ids`: its own id and its parents', each
+ * under its name (`{"device": "boiler", "property": "setpoint"}`). The name
+ * is the REST placeholder, the one the server uses in bodies and events as
+ * well (`rule` for an alarm rule, `type` for an asset type).
  */
 
 /**
@@ -43,16 +48,31 @@ import { inputError } from '../errors.js';
  * @property {'v1' | 'v2' | 'v3'} [version]  When it differs from the type's.
  * @property {Record<string, string>} [query]  Fixed query parameters (the caller's are added).
  * @property {string[]} [bodyFromRecord]  Without a `body`, send these fields of the saved record.
+ * @property {boolean} [readOnly]  Changes nothing: served in read-only mode.
+ * @property {boolean} [bodyRequired]  Refused without a body, before any request.
+ * @property {boolean} [confirm]  High impact: without body.confirm true it only answers
+ *   what it would do (or asks the user, when the client can).
+ * @property {Example[]} [examples]  Ready-to-send calls, shown by resource_describe.
  * @property {string} description
  *
+ * @typedef {object} Example
+ * @property {string} tool  Bare tool name: resource_list, resource_call…
+ * @property {Record<string, any>} arguments
+ * @property {string} does
+ *
  * @typedef {object} ResourceType
  * @property {string} description  One line, shown in the catalog summary.
  * @property {'v1' | 'v2' | 'v3'} version
  * @property {string} path         Collection path, relative to the parent item or the account.
  * @property {string} [parent]     Type this one hangs off.
- * @property {string | string[]} [id]  Name of the item id (or names, for ids in several segments).
+ * @property {string} [id]       Name of the item id in the REST path (its placeholder), which
+ *   is also the record's id field.
  * @property {string[]} [bodyId]   Body fields `create` copies the id into, when they differ
  *   from the id names; empty when the server generates the id.
+ * @property {{ field?: string, from?: 'key' | 'value' }} [recordId]  Where a listed or read
+ *   record carries its own id: a field (default: the id field), the key of a map answer
+ *   (`from: 'key'`), or the value itself in a list of strings (`from: 'value'`).
+ * @property {Example[]} [examples]  Ready-to-send calls, shown by resource_describe.
  * @property {Partial<Record<Verb, string>>} ops  Allowed verbs → server operationId.
  * @property {boolean} [upsert]    Created with PUT on the item path, so `create` needs the id.
  * @property {string} [notes]      Longer guidance returned by `resource_describe`.
@@ -74,13 +94,13 @@ const PROPERTY_NOTES =
     'Properties hold any JSON `value`. Create with body {property, name?, description?, value}; update replaces the value ({value}), while update with merge: true patches it (JSON merge of objects).';
 
 const PROFILE_NOTES =
-    'Product profile entries are keyed by name: create stores the entry under `id` (PUT), replacing what was there; update keeps the fields left out (the MCP sends the saved entry with yours over it).';
+    'Product profile entries are keyed by name: create stores the entry under `id` (PUT), replacing what was there; update keeps the fields left out (the saved entry is sent with yours over it).';
 
 /** Where profile listeners (buckets, properties) take their data from. */
 const LISTENER_SOURCE =
     'data.source is one of: "resource" (poll a device resource: {resource, update: "interval"|"event", interval, magnitude: "second"|"minute"|"hour"…}), "resource_stream" ({resource_stream}), "product_stream" ({product_stream, product?}), "topic" ({topic}, MQTT), "event" ({event, filter?}). Optional: data.payload_type ("template_payload" with data.payload such as "{{payload}}", "source_payload" to keep the payload as is, "source_event", "none") and data.payload_function (a function of the product code).';
 
-const PROFILE_API_NOTES = `${PROFILE_NOTES} An API resource is a REST endpoint added to every device of the product and dispatched by the server: {enabled, request: {data: {target, payload_type?, payload?, payload_function?, ...}}, response: {data: {payload_type, source?, payload?, payload_function?}}}. request.data.target is one of: "resource" ({resource}: a device resource), "resource_stream" ({resource_stream}; defaults to the API resource name), "product_stream" ({product, product_stream}), "property" ({property}), "function" ({function}: product code), "endpoint_call" ({endpoint}), "plugin_endpoint" ({plugin, path}), "topic" ({topic}), "none". Payload types: "template_payload" (default; data.payload is a template such as "{{payload}}"), "source_payload" (forward the body), "source_event" (the whole event), "none". response.data {payload_type: "none"} is fire-and-forget; "source_payload" returns the target's answer. Example: {"enabled": true, "request": {"data": {"target": "resource_stream", "resource_stream": "backup_complete", "payload_type": "source_payload"}}, "response": {"data": {"payload_type": "none"}}}. Called by device ({tool:device_resource_call} on a device of the product), or for the product as a whole with {tool:product_resource_call}, which needs "device_id_resolver": "<function of the product code>" in the entry to find each payload's device. A resource computed by code (target "function") also needs response {"source": "request_response", "payload_type": "source_payload"} to return the value; this is how Virtual devices get data ({tool:doc_read} id "product-code").`;
+const PROFILE_API_NOTES = `${PROFILE_NOTES} An API resource is a REST endpoint added to every device of the product and dispatched by the server: {enabled, request: {data: {target, payload_type?, payload?, payload_function?, ...}}, response: {data: {payload_type, source?, payload?, payload_function?}}}. request.data.target is one of: "resource" ({resource}: a device resource), "resource_stream" ({resource_stream}; defaults to the API resource name), "product_stream" ({product, product_stream}), "property" ({property}), "function" ({function}: product code), "endpoint_call" ({endpoint}), "plugin_endpoint" ({plugin, path}), "topic" ({topic}), "none". Payload types: "template_payload" (default; data.payload is a template such as "{{payload}}"), "source_payload" (forward the body), "source_event" (the whole event), "none". response.data {payload_type: "none"} is fire-and-forget; "source_payload" returns the target's answer. Example: {"enabled": true, "request": {"data": {"target": "resource_stream", "resource_stream": "backup_complete", "payload_type": "source_payload"}}, "response": {"data": {"payload_type": "none"}}}. Called by device ({op:device_resource.call} on a device of the product), or for the product as a whole with {op:product_profile_api.call}, which needs "device_id_resolver": "<function of the product code>" in the entry to find each payload's device. A resource computed by code (target "function") also needs response {"source": "request_response", "payload_type": "source_payload"} to return the value; this is how Virtual devices get data ({op:doc.get} ids {"doc": "product-code"}).`;
 
 const PROFILE_BUCKET_NOTES = `${PROFILE_NOTES} A profile bucket stores, for each device of the product, the samples of a data source; the bucket itself is created on the first sample. Shape: {enabled, name, description, backend: "mongodb" (default) or "influxdb", data: {source, ...}, retention?: {period, unit: "minutes"|"hours"|"days"|"months"|"years"}, tags?: []}. ${LISTENER_SOURCE} Unless the bucket name has "{{device}}", samples get "device" and "group" tags, so one bucket holds the whole fleet. Sampling a resource needs data {"source": "resource", "resource", "update": "interval", "interval", "magnitude", "payload": "{{payload}}"} (or "payload_type": "source_payload"), which stores the value as it comes; the default template payload with no "payload" writes nothing. Deleting the entry stops recording but keeps the bucket and its data. Example: {"enabled": true, "name": "backups", "backend": "mongodb", "data": {"source": "resource_stream", "resource_stream": "backup_complete", "payload_type": "source_payload"}, "retention": {"period": 1, "unit": "years"}}.`;
 
@@ -103,16 +123,38 @@ export const CATALOG = {
             clone: 'Device_Clone',
             projects: 'Device_UpdateProjects',
         },
-        notes: '`type` defaults to Generic (IOTMP). Generic and MQTT devices authenticate with `credentials`: when creating one without them, credentials are generated and returned once (the server stores them hashed). HTTP devices send data through {tool:device_data_send}; assign a product with update {product} ("" unassigns). Virtual devices have no hardware: every resource comes from their product\'s API (product code can compute it), and they need a `location` property ({lat, lon}) to appear on maps, or they are placed by their IP. Native geofences (Thinger 7.4 and later): a `geofences` property on the device, or inherited from its asset type, group or product, holds a GeoJSON FeatureCollection ([lon, lat]; Polygon, or Point with properties.radius in meters; properties.onEnter / onExit name an endpoint or ""). Every change of the device `location` emits device_geofence_event (with geofence_id, geofence_properties, product, asset_type, asset_group): store it with a product profile bucket or flow whose source is that event. See the Geofences section of {tool:doc_read} id "concepts". A new Virtual device shows disconnected in the create answer and connects a moment later.',
+        notes: '`type` defaults to Generic (IOTMP). Generic and MQTT devices authenticate with `credentials`: when creating one without them, credentials are generated and returned once (the server stores them hashed). HTTP devices send data with their send action ({op:device.send}); assign a product with update {product} ("" unassigns). Virtual devices have no hardware: every resource comes from their product\'s API (product code can compute it), and they need a `location` property ({lat, lon}) to appear on maps, or they are placed by their IP. Native geofences (Thinger 7.4 and later): a `geofences` property on the device, or inherited from its asset type, group or product, holds a GeoJSON FeatureCollection ([lon, lat]; Polygon, or Point with properties.radius in meters; properties.onEnter / onExit name an endpoint or ""). Every change of the device `location` emits device_geofence_event (with geofence_id, geofence_properties, product, asset_type, asset_group): store it with a product profile bucket or flow whose source is that event. See the Geofences section of the guide {op:doc.get} ids {"doc": "concepts"}. A new Virtual device shows disconnected in the create answer and connects a moment later.',
         actions: {
             stats: {
                 op: 'Device_ReadStatistics',
+                readOnly: true,
                 method: 'get',
                 path: 'stats',
                 version: 'v3',
                 description:
                     'Usage over the last 30 days, per day: traffic and calls (empty when the server does not record usage).',
             },
+            send: {
+                op: 'Device_CallCallbackData',
+                method: 'post',
+                path: 'callback/data',
+                version: 'v3',
+                bodyRequired: true,
+                description:
+                    'Send `body` as an HTTP device would: the server runs its callback (write a bucket, set a property, call an endpoint; see type device_callback) and answers what it configures.',
+                examples: [
+                    {
+                        tool: 'resource_call',
+                        arguments: {
+                            type: 'device',
+                            action: 'send',
+                            ids: { device: 'boiler' },
+                            body: { temperature: 21.5 },
+                        },
+                        does: 'Send a reading as the HTTP device boiler; its callback stores or forwards it.',
+                    },
+                ],
+            },
         },
     },
     product: {
@@ -121,6 +163,7 @@ export const CATALOG = {
         version: 'v1',
         path: 'products',
         id: 'product',
+        recordId: { field: 'product' },
         ops: {
             list: 'Product_List',
             create: 'Product_Create',
@@ -134,6 +177,7 @@ export const CATALOG = {
         actions: {
             export: {
                 op: 'Product_Export',
+                readOnly: true,
                 method: 'get',
                 path: 'export',
                 description:
@@ -143,7 +187,7 @@ export const CATALOG = {
     },
     bucket: {
         description:
-            'Data buckets (time series). Data is read and written with {tool:bucket_data_read} / {tool:bucket_data_write}.',
+            'Data buckets (time series). Their data is type bucket_data: {op:bucket_data.list} reads it, {op:bucket_data.create} writes samples.',
         version: 'v1',
         path: 'buckets',
         id: 'bucket',
@@ -162,18 +206,18 @@ export const CATALOG = {
                 method: 'post',
                 path: 'imports',
                 description:
-                    'Load records from a .csv already in a file storage (upload it with {tool:storage_file_write}) into an existing bucket: body {source: "storage", storage, file}. Header row; ";" separated if the header has one, "," otherwise. The time column (ts, date or timestamp) takes unix MILLISECONDS (seconds are misread as ms) or ISO 8601, always taken as UTC. Other cells become numbers when they parse, text otherwise; empty and "null" are left out. Columns named like a bucket tag (config.tags) are stored as that tag: a device column in a bucket tagged `device` (product buckets are) makes the records readable per device. Writes straight to the backend (MongoDB or InfluxDB, not DynamoDB), with no rate limit and no bucket_write events; answers {"progress": N}, a percentage (100 when done; the MCP shows only the last line). The way to load history in bulk: {tool:bucket_data_write} is one sample per call and rate limited.',
+                    'Load records from a .csv already in a file storage (upload it with {op:storage_file.create}) into an existing bucket: body {source: "storage", storage, file}. Header row; ";" separated if the header has one, "," otherwise. The time column (ts, date or timestamp) takes unix MILLISECONDS (seconds are misread as ms) or ISO 8601, always taken as UTC. Other cells become numbers when they parse, text otherwise; empty and "null" are left out. Columns named like a bucket tag (config.tags) are stored as that tag: a device column in a bucket tagged `device` (product buckets are) makes the records readable per device. Writes straight to the backend (MongoDB or InfluxDB, not DynamoDB), with no rate limit and no bucket_write events; answers {"progress": N}, a percentage (100 when done; only the last line is shown). The way to load history in bulk: {op:bucket_data.create} is rate limited.',
             },
         },
     },
     dashboard: {
         description:
-            'Dashboards: HTML apps on the dashboard SDK, published with {tool:dashboard_publish} (widget layouts are legacy).',
+            'Dashboards: HTML apps on the dashboard SDK, published with {op:dashboard.publish} (widget layouts are legacy).',
         version: 'v1',
         path: 'dashboards',
         id: 'dashboard',
         sdk: true,
-        notes: 'Build dashboards as HTML apps that use the dashboard SDK (source "url", the page at `url`): {tool:dashboard_publish} uploads the app and points the dashboard at it. Start it with {tool:dashboard_init} (a TypeScript project on the npm package @thinger-io/dashboard-sdk), develop it on its own dev server with {tool:dashboard_dev} (a link that opens the local app against this server, in the context you pick), and publish it once it works. Widget layouts (source "widgets") are legacy, made in the console editor: read them, do not create new ones. The SDK reference is under `sdk`; its types come with the package (node_modules/@thinger-io/dashboard-sdk). A per-device, product, asset type, asset group or project dashboard is the "dashboard" property of that resource instead ({tool:dashboard_publish} with `to: [{type, id}]`).',
+        notes: 'Build dashboards as HTML apps that use the dashboard SDK (source "url", the page at `url`): {op:dashboard.publish} uploads the app and points the dashboard at it. Start it with {op:dashboard.init} (a TypeScript project on the npm package @thinger-io/dashboard-sdk), develop it on its own dev server with {op:dashboard.dev} (a link that opens the local app against this server, in the context you pick), and publish it once it works. Widget layouts (source "widgets") are legacy, made in the console editor: read them, do not create new ones. The SDK reference is under `sdk`; its types come with the package (node_modules/@thinger-io/dashboard-sdk). A per-device, product, asset type, asset group or project dashboard is the "dashboard" property of that resource instead ({op:dashboard.publish} with body.to: [{type, id}]).',
         ops: {
             list: 'Dashboard_List',
             create: 'Dashboard_Create',
@@ -211,7 +255,7 @@ export const CATALOG = {
         notes: 'Every endpoint needs `config`, even type "virtual" (a no-op receiver for tests and alarm notifications): {"endpoint": "…", "name": "…", "type": "virtual", "config": {}}.',
     },
     storage: {
-        description: 'File storages (their files are handled with the storage_file_* tools).',
+        description: 'File storages; their files are type storage_file.',
         version: 'v1',
         path: 'storages',
         id: 'storage',
@@ -275,6 +319,21 @@ export const CATALOG = {
         version: 'v1',
         path: 'tokens',
         id: 'token',
+        examples: [
+            {
+                tool: 'resource_create',
+                arguments: {
+                    type: 'token',
+                    ids: { token: 'readonly_dashboard' },
+                    body: {
+                        name: 'Read-only dashboard',
+                        allow: { Device: { '*': ['List*', 'Read*'] }, Bucket: { '*': ['Read*'] } },
+                        expire: '30d',
+                    },
+                },
+                does: 'A token that reads devices and buckets and expires in 30 days.',
+            },
+        ],
         ops: {
             list: 'Token_List',
             create: 'Token_Create',
@@ -300,18 +359,31 @@ export const CATALOG = {
             clone: 'Alarm_CloneRule',
             projects: 'Alarm_UpdateRuleProjects',
         },
-        notes: 'Condition values are strings ("30", not 30: a number never matches) and only enabled devices are evaluated. A device_property source projects fields of the property document, so its fields are `value.<field>` (fields ["value.level"], condition field "battery.value.level"; "level" alone yields null and every device is skipped). The document also has `modified` and `created` (unix ms, UTC): fields ["modified"] with condition field `ts() - battery.modified` above "3600000" flags a property not updated for an hour. A condition value can name a field of another source of the same device ("limits.value.max_depth_m"): per-device thresholds, inherited from asset type, group or product; sources, conditions and confirmations are in {tool:doc_read} id "concepts" (Alarms). Try a rule before saving it with its test_rule / test_source / test_notification actions ({tool:resource_call}).',
+        notes: 'Condition values are strings ("30", not 30: a number never matches) and only enabled devices are evaluated. A device_property source projects fields of the property document, so its fields are `value.<field>` (fields ["value.level"], condition field "battery.value.level"; "level" alone yields null and every device is skipped). The document also has `modified` and `created` (unix ms, UTC): fields ["modified"] with condition field `ts() - battery.modified` above "3600000" flags a property not updated for an hour. A condition value can name a field of another source of the same device ("limits.value.max_depth_m"): per-device thresholds, inherited from asset type, group or product; sources, conditions and confirmations are in {op:doc.get} ids {"doc": "concepts"} (Alarms). Try a rule before saving it with its test_rule / test_source / test_notification actions ({tool:resource_call}).',
         actions: {
             test_rule: {
                 op: 'Alarm_TestRuleTest-rule',
+                readOnly: true,
                 method: 'post',
                 path: 'test-rule',
                 bodyFromRecord: ['name', 'description', 'enabled', 'config'],
                 description:
                     'Evaluate a whole rule without raising alarms or notifying: `body` is the rule as it would be saved ({name, enabled, config}), and the rule id may not exist yet. Without `body`, it tests the saved rule.',
+                examples: [
+                    {
+                        tool: 'resource_call',
+                        arguments: {
+                            type: 'alarm_rule',
+                            action: 'test_rule',
+                            ids: { rule: 'high_temp' },
+                        },
+                        does: 'Evaluate the saved rule high_temp now, without raising alarms.',
+                    },
+                ],
             },
             test_source: {
                 op: 'Alarm_TestRuleSourceTest-source',
+                readOnly: true,
                 method: 'post',
                 path: 'test-source',
                 description:
@@ -319,6 +391,7 @@ export const CATALOG = {
             },
             test_notification: {
                 op: 'Alarm_TestRuleNotificationTest-notification',
+                confirm: true,
                 method: 'post',
                 path: 'test-notification',
                 description:
@@ -332,6 +405,7 @@ export const CATALOG = {
         version: 'v1',
         path: 'alarms/instances',
         id: 'instance',
+        recordId: { field: 'instance' },
         ops: {
             list: 'Alarm_ListInstances',
             get: 'Alarm_ReadInstanceConfig',
@@ -342,6 +416,7 @@ export const CATALOG = {
         actions: {
             stats: {
                 op: 'Alarm_ReadInstanceStats',
+                readOnly: true,
                 method: 'get',
                 path: 'stats',
                 on: 'collection',
@@ -417,10 +492,11 @@ export const CATALOG = {
 
     plugin: {
         description:
-            'Plugins installed on the account: containers that add features (integrations, apps); their API is reached with plugin_call.',
+            'Plugins installed on the account: containers that add features (integrations, apps); their API is reached with {op:plugin.call}.',
         version: 'v1',
         path: 'plugins',
         id: 'plugin',
+        recordId: { field: 'name' },
         ops: { list: 'Plugin_List', get: 'Plugin_ReadInfo' },
         listQuery: { filter: 'installed' },
         listWhole: true,
@@ -460,6 +536,7 @@ export const CATALOG = {
             },
             remove: {
                 op: 'Plugin_ManageState',
+                confirm: true,
                 method: 'post',
                 path: '',
                 query: { action: 'remove' },
@@ -503,6 +580,7 @@ export const CATALOG = {
             },
             kill: {
                 op: 'Plugin_ManageState',
+                confirm: true,
                 method: 'post',
                 path: '',
                 query: { action: 'kill' },
@@ -548,6 +626,7 @@ export const CATALOG = {
         scope: 'server',
         path: 'hosts',
         id: 'host',
+        recordId: { field: 'host' },
         ops: {
             list: 'Host_List',
             create: 'Host_Create',
@@ -555,10 +634,11 @@ export const CATALOG = {
             update: 'Host_Update',
             delete: 'Host_Delete',
         },
-        notes: 'update_settings is a JSON merge over the host\'s custom settings and only takes effect after the restart action, which drops every connection: plan both with the user. Ports are strings. Read {tool:doc_read} id "server-admin" first. read_settings leaves out some keys (limits of accounts, brands, domains and members, database, plugins, rate limiter); {tool:resource_get} of the host shows the effective ones in current_settings. On cloud instances (license "cloud" in /v1/server/version) the subscription manages those limits, database, plugins, rate limiter and http_server.hosts: changing them answers 403 naming the path; tell the user it depends on their plan.',
+        notes: 'update_settings is a JSON merge over the host\'s custom settings and only takes effect after the restart action, which drops every connection: plan both with the user. Ports are strings. Read {op:doc.get} ids {"doc": "server-admin"} first. read_settings leaves out some keys (limits of accounts, brands, domains and members, database, plugins, rate limiter); {tool:resource_get} of the host shows the effective ones in current_settings. On cloud instances (license "cloud" in /v1/server/version) the subscription manages those limits, database, plugins, rate limiter and http_server.hosts: changing them answers 403 naming the path; tell the user it depends on their plan.',
         actions: {
             logs: {
                 op: 'Host_ReadLogs',
+                readOnly: true,
                 method: 'get',
                 path: 'logs',
                 description:
@@ -566,6 +646,7 @@ export const CATALOG = {
             },
             restart: {
                 op: 'Host_UpdateStateRestart',
+                confirm: true,
                 method: 'post',
                 path: 'restart',
                 description:
@@ -573,12 +654,14 @@ export const CATALOG = {
             },
             read_settings: {
                 op: 'Host_ReadSettings',
+                readOnly: true,
                 method: 'get',
                 path: 'settings',
                 description: 'Read the host settings.',
             },
             update_settings: {
                 op: 'Host_UpdateSettings',
+                confirm: true,
                 method: 'put',
                 path: 'settings',
                 description:
@@ -608,7 +691,7 @@ export const CATALOG = {
                     'Check that the domain resolves to this server (after the user configures its DNS).',
             },
         },
-        notes: 'A domain is usable once it resolves to this server (an A/AAAA record with its IP, or a CNAME to its current hostname) with port 80 reachable, and the verify action succeeds (it gets the certificate; a failure says why: DNS, invalid suffix…). Ask the user to set up the DNS record, then verify. A brand with the same domain then gives it its look: {tool:doc_read} id "server-admin" has the whole flow.',
+        notes: 'A domain is usable once it resolves to this server (an A/AAAA record with its IP, or a CNAME to its current hostname) with port 80 reachable, and the verify action succeeds (it gets the certificate; a failure says why: DNS, invalid suffix…). Ask the user to set up the DNS record, then verify. A brand with the same domain then gives it its look: {op:doc.get} ids {"doc": "server-admin"} has the whole flow.',
     },
     brand: {
         description: 'Brands: the look (and email) of the console on a domain.',
@@ -616,7 +699,7 @@ export const CATALOG = {
         scope: 'server',
         path: 'brands',
         id: 'brand',
-        notes: 'Change a brand with {tool:resource_update} and merge: true (JSON merge of config and email; null removes a key; logos are kept). Without merge the whole brand is replaced and logos missing from it are deleted: only send complete objects. Logos and images go as data URLs (png or webp); to keep one in a full update, send back its /brand/images/… URL. The email settings are the brand\'s `email` field; test them with the test_email action (sent to the admin calling). For the whole domain + brand setup read {tool:doc_read} id "server-admin". Reading a brand that does not exist returns defaults (only config.accounts), not an error: a real brand has the `brand` field.',
+        notes: 'Change a brand with {tool:resource_update} and merge: true (JSON merge of config and email; null removes a key; logos are kept). Without merge the whole brand is replaced and logos missing from it are deleted: only send complete objects. Logos and images go as data URLs (png or webp); to keep one in a full update, send back its /brand/images/… URL. The email settings are the brand\'s `email` field; test them with the test_email action (sent to the admin calling). For the whole domain + brand setup read {op:doc.get} ids {"doc": "server-admin"}. Reading a brand that does not exist returns defaults (only config.accounts), not an error: a real brand has the `brand` field.',
         ops: {
             list: 'Brand_List',
             create: 'Brand_Create',
@@ -663,7 +746,7 @@ export const CATALOG = {
             update: 'IdentityProvider_Update',
             delete: 'IdentityProvider_Delete',
         },
-        notes: 'Client secrets belong to the user: ask for them, never invent or echo them back. The server allows them only when accounts.limits.identity_providers.max_count is raised (host settings, then restart). See {tool:doc_read} id "server-admin".',
+        notes: 'Client secrets belong to the user: ask for them, never invent or echo them back. The server allows them only when accounts.limits.identity_providers.max_count is raised (host settings, then restart). See {op:doc.get} ids {"doc": "server-admin"}.',
     },
     proxy: {
         description: 'Proxies: services the server exposes through its own address.',
@@ -720,6 +803,7 @@ export const CATALOG = {
         parent: 'device',
         path: 'tokens',
         id: 'token',
+        recordId: { field: 'token' },
         bodyId: [],
         ops: {
             list: 'Device_ListTokens',
@@ -734,14 +818,16 @@ export const CATALOG = {
         parent: 'device',
         path: 'buckets',
         id: 'bucket',
+        recordId: { field: 'bucket' },
         ops: { list: 'Device_ListBuckets' },
     },
     device_bucket_tag: {
-        description: 'Tags of a device bucket (parent: "<device>/<bucket>").',
+        description: 'Tags of a device bucket.',
         version: 'v3',
         parent: 'device_bucket',
         path: 'tags',
         id: 'tag',
+        recordId: { from: 'value' },
         ops: { list: 'Device_ListBucketTags', get: 'Device_ReadBucketTag' },
     },
     device_service: {
@@ -750,6 +836,7 @@ export const CATALOG = {
         parent: 'device',
         path: 'services',
         id: 'service',
+        recordId: { field: 'service' },
         ops: { list: 'Device_ListServices', get: 'Device_ReadService' },
     },
     device_callback: {
@@ -786,6 +873,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/api',
         id: 'resource',
+        recordId: { from: 'key' },
         upsert: true,
         ops: {
             list: 'Product_ReadProfile',
@@ -798,6 +886,7 @@ export const CATALOG = {
         actions: {
             replace_all: {
                 op: 'Product_UpdateProfile',
+                confirm: true,
                 method: 'put',
                 path: '',
                 on: 'collection',
@@ -812,6 +901,30 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/buckets',
         id: 'resource',
+        examples: [
+            {
+                tool: 'resource_create',
+                arguments: {
+                    type: 'product_profile_bucket',
+                    ids: { product: 'boiler_kit', resource: 'telemetry' },
+                    body: {
+                        name: 'Telemetry',
+                        enabled: true,
+                        data: {
+                            source: 'resource',
+                            resource: 'telemetry',
+                            update: 'interval',
+                            interval: 60,
+                            magnitude: 'second',
+                            payload_type: 'source_payload',
+                        },
+                    },
+                },
+                does: 'A bucket per device of the product, fed from its resource telemetry every 60 s.',
+            },
+        ],
+
+        recordId: { from: 'key' },
         upsert: true,
         ops: {
             list: 'Product_ReadProfile',
@@ -824,6 +937,7 @@ export const CATALOG = {
         actions: {
             replace_all: {
                 op: 'Product_UpdateProfile',
+                confirm: true,
                 method: 'put',
                 path: '',
                 on: 'collection',
@@ -838,6 +952,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/properties',
         id: 'resource',
+        recordId: { from: 'key' },
         upsert: true,
         ops: {
             list: 'Product_ReadProfile',
@@ -850,6 +965,7 @@ export const CATALOG = {
         actions: {
             replace_all: {
                 op: 'Product_UpdateProfile',
+                confirm: true,
                 method: 'put',
                 path: '',
                 on: 'collection',
@@ -864,6 +980,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/autoprovisions',
         id: 'resource',
+        recordId: { from: 'key' },
         upsert: true,
         ops: {
             list: 'Product_ReadProfile',
@@ -876,6 +993,7 @@ export const CATALOG = {
         actions: {
             replace_all: {
                 op: 'Product_UpdateProfile',
+                confirm: true,
                 method: 'put',
                 path: '',
                 on: 'collection',
@@ -890,6 +1008,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/flows',
         id: 'resource',
+        recordId: { from: 'key' },
         upsert: true,
         ops: {
             list: 'Product_ReadProfile',
@@ -902,6 +1021,7 @@ export const CATALOG = {
         actions: {
             replace_all: {
                 op: 'Product_UpdateProfile',
+                confirm: true,
                 method: 'put',
                 path: '',
                 on: 'collection',
@@ -916,7 +1036,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'profile/code',
         ops: { get: 'Product_ReadProfileCode', update: 'Product_UpdateProfileCode' },
-        notes: 'Update with {code: "<JavaScript>", storage: ""}, or {storage: "<id>"} to load <storage>/index.js, or {storage, path: "<folder>"} to load <storage>/<folder>/index.js, with that folder\'s node_modules (one storage can hold the dashboard in app/ and each product\'s code in code/<product>/). Update again after editing the file. Functions are synchronous globals (`function name(arg) {…}`) that the profile calls by name: API targets, payload_function, device_id_resolver. `Date` runs in UTC: for local hours use Intl.DateTimeFormat with a timeZone (it follows daylight saving). Read {tool:doc_read} id "product-code" before writing it.',
+        notes: 'Update with {code: "<JavaScript>", storage: ""}, or {storage: "<id>"} to load <storage>/index.js, or {storage, path: "<folder>"} to load <storage>/<folder>/index.js, with that folder\'s node_modules (one storage can hold the dashboard in app/ and each product\'s code in code/<product>/). Update again after editing the file. Functions are synchronous globals (`function name(arg) {…}`) that the profile calls by name: API targets, payload_function, device_id_resolver. `Date` runs in UTC: for local hours use Intl.DateTimeFormat with a timeZone (it follows daylight saving). Read {op:doc.get} ids {"doc": "product-code"} before writing it.',
     },
     product_service: {
         description: 'Services a product exposes on its devices.',
@@ -924,6 +1044,7 @@ export const CATALOG = {
         parent: 'product',
         path: 'services',
         id: 'service',
+        recordId: { field: 'service' },
         upsert: true,
         ops: {
             list: 'Product_ReadServices',
@@ -941,6 +1062,7 @@ export const CATALOG = {
         parent: 'bucket',
         path: 'tags',
         id: 'tag',
+        recordId: { from: 'value' },
         ops: { list: 'Bucket_ListTags', get: 'Bucket_ReadTag' },
     },
     bucket_export: {
@@ -949,6 +1071,7 @@ export const CATALOG = {
         parent: 'bucket',
         path: 'exports',
         id: 'file',
+        recordId: { field: 'file' },
         bodyId: [],
         ops: {
             list: 'Bucket_ListExports',
@@ -1094,69 +1217,151 @@ export function idNames(type) {
     return type.id === undefined ? [] : [type.id].flat();
 }
 
-/** How a type's ids are written: `<device>`. */
-export function idHint(name) {
-    return idNames(CATALOG[name])
-        .map((n) => `<${n}>`)
-        .join('/');
+/** Name of a type's own id in `ids`: the REST placeholder. */
+export function idKey(name) {
+    const type = CATALOG[name];
+    return type?.id === undefined ? undefined : String(type.id);
 }
 
-/** How the parent of a type is written: `<device>/<bucket>`. */
-export function parentHint(name) {
-    return ancestry(name).map(idHint).join('/');
+/**
+ * @typedef {object} IdLevel
+ * @property {string} type   The type this id belongs to (the record's, or a parent's).
+ * @property {string} key    Its name in `ids`.
+ */
+
+/**
+ * The ids that locate a record of a type, outermost parent first, its own
+ * last (single records have only their parents'). `local` are the types a
+ * CLI adds, which may hang off the catalog's or off each other.
+ *
+ * @param {string} name
+ * @param {Record<string, { id?: string, parent?: string }>} [local]
+ * @returns {IdLevel[]}
+ */
+export function idLevels(name, local = {}) {
+    /** @type {IdLevel[]} */
+    const levels = [];
+    for (let t = name; t;) {
+        const mine = Object.hasOwn(local, t) ? local[t] : undefined;
+        const spec = mine ?? CATALOG[t];
+        if (!spec) break;
+        const key = mine ? mine.id : idKey(t);
+        if (key) levels.unshift({ type: t, key });
+        t = spec.parent;
+    }
+    return levels;
+}
+
+/** Names of a type's ids, outermost first: `device_bucket_tag` → [device, bucket, tag]. */
+export const idKeys = (name, local) => idLevels(name, local).map((l) => l.key);
+
+/** "a", "a and b", "a, b and c". */
+export const listed = (words) =>
+    words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`;
+
+// eslint-disable-next-line no-control-regex -- control characters are what it looks for
+const CONTROL = /[\x00-\x1f]/;
+
+/**
+ * One id: a non-empty string (a number becomes one), never `.` or `..`
+ * (the URL would resolve them: `..` would point at the parent) or with
+ * control characters.
+ */
+function idValue(key, value) {
+    if (typeof value === 'number' && Number.isFinite(value)) value = String(value);
+    if (
+        typeof value !== 'string' ||
+        !value ||
+        value === '.' ||
+        value === '..' ||
+        CONTROL.test(value)
+    ) {
+        throw inputError(`ids.${key}: invalid id ${JSON.stringify(value)}`);
+    }
+    return value;
 }
 
 /**
- * Split a `a/b` reference into exactly `count` non-empty segments.
+ * Check the `ids` a call gives for a type: every parent's, and its own as
+ * `own` says (required, optional or forbidden).
  *
- * @param {unknown} value
- * @param {number} count
- * @param {string} what  Argument name and expected shape, for the error.
+ * @param {string} name
+ * @param {unknown} ids
+ * @param {{
+ *   own?: 'required' | 'optional' | 'forbidden',
+ *   forbidden?: (key: string) => string,
+ *   missing?: (key: string) => string,
+ *   local?: Record<string, { id?: string, parent?: string }>,
+ * }} [opts]  `forbidden` and `missing` word the errors about the own id.
+ * @returns {{ levels: string[], own?: string, ids: Record<string, string> }}
+ *   The parents' ids outermost first, the own id, and every id by its name.
  */
-function segments(value, count, what) {
-    if (count === 0) return [];
-    const parts = value === undefined || value === null ? [] : String(value).split('/');
-    if (parts.length !== count || parts.some((p) => !p)) {
-        throw inputError(`${what} is required`);
+export function resolveIds(name, ids, { own = 'required', forbidden, missing, local = {} } = {}) {
+    if (ids === undefined || ids === null) ids = {};
+    if (typeof ids !== 'object' || Array.isArray(ids)) {
+        throw inputError('ids must be an object of ids by name: {"device": "boiler"}');
     }
-    return parts;
+    const all = idLevels(name, local);
+    const single = Object.hasOwn(local, name) ? !local[name].id : idKey(name) === undefined;
+    const parents = single ? all : all.slice(0, -1);
+    const mine = single ? undefined : all.at(-1);
+    const names = new Set(all.map((l) => l.key));
+    const unknown = Object.keys(ids).filter((k) => !names.has(k));
+    if (unknown.length) {
+        const keys = all.map((l) => l.key);
+        throw inputError(
+            `${name} takes ${keys.length ? `ids ${listed(keys)}` : 'no ids'}; unknown: ${unknown.join(', ')}`,
+        );
+    }
+    const valueOf = (/** @type {IdLevel} */ l) => {
+        const value = ids[l.key];
+        return value === undefined || value === null ? undefined : idValue(l.key, value);
+    };
+    /** @type {Record<string, string>} */
+    const out = {};
+    const levels = parents.map((l) => {
+        const value = valueOf(l);
+        if (value === undefined) throw inputError(`missing ${l.key}: the ${l.type}'s id`);
+        return (out[l.key] = value);
+    });
+    let ownId;
+    if (mine) {
+        ownId = valueOf(mine);
+        if (ownId !== undefined && own === 'forbidden') {
+            throw inputError(forbidden?.(mine.key) ?? `leave ${mine.key} out of ids`);
+        }
+        if (ownId === undefined && own === 'required') {
+            throw inputError(missing?.(mine.key) ?? `missing ${mine.key}: the ${name}'s id`);
+        }
+        if (ownId !== undefined) out[mine.key] = ownId;
+    }
+    return { levels, ...(ownId !== undefined ? { own: ownId } : {}), ids: out };
 }
 
 /**
  * The path of a type's collection or item, from the outermost ancestor
- * down: the real URL (ids escaped, the account from lib/paths.js), or the
- * OpenAPI template the tests and `resource_describe` match (ids as `{}`).
+ * down: the real URL (ids escaped, a "/" in one too, the account from
+ * lib/paths.js), or the OpenAPI template the tests and `resource_describe`
+ * match (ids as `{}`).
  *
  * @param {string} name
  * @param {{ on: 'collection' | 'item', suffix?: string, version?: string }} at
- * @param {{ parent?: string, id?: string, user?: string | null }} args
+ * @param {{ levels?: string[], own?: string, user?: string | null }} where  As resolveIds gives.
  * @param {boolean} template
  */
-function locate(name, at, { parent, id, user } = {}, template = false) {
+function locate(name, at, { levels = [], own, user } = {}, template = false) {
     const type = CATALOG[name];
     const version = at.version || type.version;
-    const chain = ancestry(name);
-    const parentIds = template
-        ? []
-        : segments(
-              parent,
-              chain.reduce((n, t) => n + idNames(CATALOG[t]).length, 0),
-              `parent (${parentHint(name)})`,
-          );
     const seg = (value) => (template ? '{}' : encodeURIComponent(value));
 
     let path = '';
-    for (const t of chain) {
+    let i = 0;
+    for (const t of ancestry(name)) {
         path += `/${CATALOG[t].path}`;
-        for (const _ of idNames(CATALOG[t])) path += `/${seg(parentIds.shift())}`;
+        if (CATALOG[t].id !== undefined) path += `/${seg(levels[i++])}`;
     }
     path += `/${type.path}`;
-    if (at.on === 'item' && idNames(type).length) {
-        const ids = template
-            ? idNames(type).map(() => '{}')
-            : segments(id, idNames(type).length, `id (${idHint(name)})`);
-        path += ids.map((i) => `/${template ? i : encodeURIComponent(i)}`).join('');
-    }
+    if (at.on === 'item' && type.id !== undefined) path += `/${seg(own)}`;
     if (at.suffix) path += `/${at.suffix}`;
 
     // Server-wide types (users, hosts, domains…) hang off /v{N}, not off an account.
@@ -1185,19 +1390,37 @@ function verbTarget(type, verb) {
 }
 
 /**
- * Resolve the request a verb maps to.
+ * Resolve the request a verb maps to, its `ids` checked: an item takes
+ * every id, a collection only its parents'.
  *
  * @param {string} name  Catalog type.
  * @param {Verb} verb
- * @param {{ parent?: string, id?: string, user?: string | null }} [args]
+ * @param {{ ids?: Record<string, any>, user?: string | null }} [args]
  * @returns {{ method: string, url: string }}
  */
-export function requestFor(name, verb, args = {}) {
+export function requestFor(name, verb, { ids, user } = {}) {
     const type = CATALOG[name];
     if (!type) throw inputError(`Unknown type "${name}"`);
     if (!(verb in type.ops)) throw inputError(`Type "${name}" does not support ${verb}`);
     const { method, at } = verbTarget(type, verb);
-    return { method, url: locate(name, at, args) };
+    const where = resolveIds(
+        name,
+        ids,
+        at.on === 'item'
+            ? {
+                  own: 'required',
+                  // An upsert create: the entry is stored under that name.
+                  missing:
+                      verb === 'create'
+                          ? (key) => `missing ${key}: the entry's name (it is stored under it)`
+                          : undefined,
+              }
+            : {
+                  own: 'forbidden',
+                  forbidden: (key) => `${verb} takes no ${key}: leave it out of ids`,
+              },
+    );
+    return { method, url: locate(name, at, { ...where, user }) };
 }
 
 /**
@@ -1213,13 +1436,14 @@ export function templateFor(name, verb) {
 }
 
 /**
- * Resolve the request of a type's action (verify a domain, restart a host…).
+ * Resolve the request of a type's action (verify a domain, restart a host…),
+ * its `ids` checked as requestFor does.
  *
  * @param {string} name
  * @param {string} action
- * @param {{ parent?: string, id?: string, user?: string | null }} [args]
+ * @param {{ ids?: Record<string, any>, user?: string | null }} [args]
  */
-export function actionRequest(name, action, args = {}) {
+export function actionRequest(name, action, { ids, user } = {}) {
     const type = CATALOG[name];
     if (!type) throw inputError(`Unknown type "${name}"`);
     const spec = type.actions?.[action];
@@ -1229,7 +1453,21 @@ export function actionRequest(name, action, args = {}) {
             `Type "${name}" has no action "${action}"${known.length ? ` (it has: ${known.join(', ')})` : ''}`,
         );
     }
-    return { method: spec.method, url: locate(name, actionAt(spec), args), query: spec.query };
+    const where = resolveIds(
+        name,
+        ids,
+        spec.on === 'collection'
+            ? {
+                  own: 'forbidden',
+                  forbidden: (key) => `${action} acts on every ${name}: leave ${key} out of ids`,
+              }
+            : {},
+    );
+    return {
+        method: spec.method,
+        url: locate(name, actionAt(spec), { ...where, user }),
+        query: spec.query,
+    };
 }
 
 /** OpenAPI template of an action, like templateFor. */