@thinremote/thinr-cli 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## [1.6.1] - 2026-10-31
+
+### Fixed
+
+- `thinr device tcp|tls|http -p` is described as what it is: the port
+  of the relay on the server (random between 50000 and 51000 by default),
+  not a local port.
+- From `@thinger-io/cli-core` 0.5.1: the browser login on a server that does
+  not know the CLI's OAuth client says so and offers username and password
+  or a token, and the host `update_settings` action is described as the
+  merge the server does.
+- Requires `@thinger-io/cli-core` 0.5.1.
+
+## [1.6.0] - 2026-10-27
+
+Every command follows one grammar, the one of `@thinger-io/cli-core` 0.5.0
+shared with the `thinger` CLI, noun first:
+`thinr <noun> [<noun>…] <verb> [<parent ids>…] [<id>] [options]`. Nouns
+nest under their parent (`device property`, `product metric`), ids are
+positional and named after their noun (`<device>`, `<product>`), and the
+options keep one meaning everywhere (`-j` JSON, `-s` a body field, `-f` one
+field of the answer, `-o` a file, `-y` no questions). Several commands of
+1.5 change form: see the table below. The old forms are gone, not aliased.
+
+The MCP server serves eight tools instead of 24: `thinr_resource_*` reach
+everything by `type`, records are addressed with `ids`, and the shell
+command is the `exec` action of type `device`. The old tool names and the
+`parent`/`id` arguments are gone, not aliased: see the second table below.
+
+### Added
+
+- `thinr agent check <device>` and `thinr agent update <device>`, and
+  `thinr agent update --all` for the whole fleet (with the options of the
+  old `fleet upgrade`: `-p`, `-g`, `--batch-size`, `--no-canary`,
+  `--continue-on-error`, `--dry-run`, `-y`).
+- From `@thinger-io/cli-core` 0.5.0: commands for every resource type
+  (`list|get|create|update|delete|clone|describe`, `set` on every kind of
+  property, the type's actions), `thinr api <path>`,
+  `thinr bucket write|export`, `thinr storage file list|upload|download|delete`,
+  `thinr device send|overview`, `thinr device resource list|call`,
+  `thinr product apply --from`, `thinr product profile api call`,
+  `thinr plugin call`; `--search`, `--filter`, `--count` and `--index` on
+  `device list`, `product list` and `bucket list`; `thinr doc list|get`.
+- MCP: `resource_describe` shows each type's ids, actions, permissions and
+  ready-to-send examples; `exec` on several devices, playbook runs on
+  several devices and rollouts answer their targets first and run with
+  `confirm: true` (or ask through the client when it supports it);
+  `thinr mcp --read-only` (or `THINR_MCP_READ_ONLY=1`) serves only what
+  reads. The product properties `logs` and `dashboard_metrics` are checked
+  before they are written, and `resource_describe` type `product_property`
+  shows their shape.
+
+### Changed (breaking)
+
+| 1.5                                                     | 1.6                                                         |
+| ------------------------------------------------------- | ----------------------------------------------------------- |
+| `thinr device list <pattern>`                           | `thinr device list --search <text>`                         |
+| `thinr device info <device>`                            | `thinr device get <device>`                                 |
+| `thinr device property <device>`                        | `thinr device property list <device>`                       |
+| `thinr device property <device> <prop>`                 | `thinr device property get <device> <property>`             |
+| `thinr device property-set <device> <p> <v>`            | `thinr device property set <device> <property> <value>`     |
+| `thinr device resource <device>`                        | `thinr device resource list <device>`                       |
+| `thinr device resource <device> <r> -i k=v`             | `thinr device resource call <device> <resource> -s k=v`     |
+| `thinr device update check <device>`                    | `thinr agent check <device>`                                |
+| `thinr device update apply <device>`                    | `thinr agent update <device>`                               |
+| `thinr fleet upgrade [options]`                         | `thinr agent update --all [options]`                        |
+| `thinr product info <product>`                          | `thinr product get <product>`                               |
+| `thinr product property-list <product>`                 | `thinr product property list <product>`                     |
+| `thinr product property-get <product> <p>`              | `thinr product property get <product> <property>`           |
+| `thinr product property-set <product> <p> <v>`          | `thinr product property set <product> <property> <value>`   |
+| `thinr product property-delete <product> <p>`           | `thinr product property delete <product> <property> -y`     |
+| `thinr product property <product> <prop>` (fan-out)     | `thinr product device-property <product> <property>`        |
+| `thinr product resource <product> <r> -i k=v` (fan-out) | `thinr product device-resource <product> <resource> -s k=v` |
+| `thinr product metric-list <product>`                   | `thinr product metric list <product>`                       |
+| `thinr product metric-set <product> <name>`             | `thinr product metric set <product> <name>`                 |
+| `thinr product metric-delete <product> <name>`          | `thinr product metric delete <product> <name>`              |
+| `thinr product logs add <product> <name>`               | `thinr product logs create <product> <name>`                |
+| `thinr product logs show <product> <name>`              | `thinr product logs get <product> <name>`                   |
+| `thinr product logs remove\|rm <product> <name>`        | `thinr product logs delete <product> <name>`                |
+
+- `thinr fleet` is gone: `agent update --all` took its only command.
+- `device property get` and `product property get` print the property
+  record, with its value under `value`: `-f` paths start there
+  (`-f value.setpoint` where 1.5 took `-f setpoint`). `product property
+  delete` asks unless `-y`.
+- `product metric delete`, `product logs delete` and
+  `product playbook delete` ask for confirmation too: scripts pass `-y`.
+- `device resource call` and `product device-resource` take their input
+  from `--from <file>` and `-s, --set key=value` (`-i` is gone); `-s`
+  values are parsed as JSON when they are.
+- `product metric set` takes `-j, --json` (it took only `--json`).
+- The help groups the root commands as Resources, Administration,
+  Configuration, Integration and Operations, and the verbs of a noun as
+  Records, Data, Actions and Subresources, before thinr's own groups.
+- The MCP tools (the commands keep their forms and `-j` outputs):
+
+| 1.5 tool                                             | 1.6 call                                                                                            |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `thinr_resource_* parent "gw_1" id "/etc/hosts"`      | `thinr_resource_* ids {"device": "gw_1", "path": "/etc/hosts"}`                                     |
+| `thinr_device_exec device` …                          | `thinr_resource_call type "device" action "exec" ids {device} body {command, …}`                    |
+| `thinr_device_exec devices\|product\|group\|all` …     | `thinr_resource_call type "device" action "exec" body {command, devices\|product\|group\|all, …}`     |
+| `type "device_script"` / `"product_script"` id        | ids `{device, script}` / `{product, script}` (body `name` on create)                                |
+| `type "product_playbook"` id                          | ids `{product, playbook}`                                                                           |
+| `type "product_metric"`                               | `type "product_property"` ids `{product, property: "dashboard_metrics"}`, the whole array as value  |
+| `type "product_log_source"`                           | `type "product_property"` ids `{product, property: "logs"}`, `{sources, default}` as value          |
+| `thinr_bucket_data_read` / `_write`                   | `thinr_resource_list` / `_create` `type "bucket_data" ids {bucket}`                                 |
+| `thinr_device_resource_list` / `_call`                | `thinr_resource_list type "device_resource"` / `_call action "call" ids {device, resource}`         |
+| `thinr_storage_file_*`                                | `thinr_resource_* type "storage_file" ids {storage, file}`                                          |
+| `thinr_doc_read`, `thinr_profile_list`                | `thinr_resource_get type "doc" ids {doc}`, `thinr_resource_list type "profile"`                     |
+| `thinr_dashboard_*`, `thinr_plugin_call`, `thinr_product_resource_call`, `thinr_device_data_send`, `thinr_device_overview` | `thinr_resource_call` actions `dashboard` `init\|dev\|publish`, `plugin` `call`, `product_profile_api` `call`, `device` `send`, `device` `overview` |
+
+- Requires `@thinger-io/cli-core` 0.5.0.
+
 ## [1.5.0] - 2026-10-16
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ Two operating modes:
 
 - **CLI** — interactive or scripted device management from a shell.
 - **MCP server** — a stdio [Model Context Protocol][mcp] server that
-  exposes the same operations as 24 typed tools for AI clients like
+  exposes the same operations as eight resource tools for AI clients like
   Claude Code, Claude Desktop and Cursor.
 
 Both modes share the same auth, profiles, and device API layer, so
@@ -28,8 +28,9 @@ task at hand.
 - [Global options and environment variables](#global-options-and-environment-variables)
 - [Part 1 — CLI](#part-1--cli)
     - [JSON output](#json-output)
-    - [`thinr device <action> [<deviceId>]`](#thinr-device-action-deviceid)
-    - [`thinr product <action> <productId>`](#thinr-product-action-productid)
+    - [`thinr device`](#thinr-device)
+    - [`thinr product`](#thinr-product)
+    - [`thinr agent`](#thinr-agent)
     - [`thinr playbook <action>`](#thinr-playbook-action)
     - [`thinr profile`](#thinr-profile)
     - [`thinr logout`](#thinr-logout)
@@ -95,13 +96,18 @@ These apply to every subcommand:
 
 ## Part 1 — CLI
 
-All device- and product-scoped actions follow a **subcommand-first**
-shape: the action comes before the target id, matching patterns like
-`kubectl describe pod <name>` or `git remote add <name> <url>`.
+Every command follows one grammar, shared with the `thinger` CLI: nouns
+first, then a verb, then the ids from the outermost to the innermost, then
+the options (`thinr device property get <device> <property>`). Records
+take the same verbs everywhere (`list`, `get`, `create`, `update`,
+`delete`, `clone`, `set`, `describe`), a body comes from `--from <file>`
+and `-s, --set key=value`, and `-j, --json` gives the JSON envelope below.
+`thinr --help` lists the nouns; `thinr <noun> --help` their verbs.
 
 ```
-thinr device <action>  <deviceId>  [args…] [options]
-thinr product <action> <productId> [args…] [options]
+thinr device <verb> <device> [args…] [options]
+thinr product <verb> <product> [args…] [options]
+thinr device property <verb> <device> <property> [options]
 ```
 
 ### JSON output
@@ -138,35 +144,33 @@ don't change their behaviour — they don't produce a discrete result.
 `exec` buffers stdout/stderr when `--json` is set and emits a single
 envelope on exit.
 
-### `thinr device <action> [<deviceId>]`
+### `thinr device`
 
-Most actions take a `<deviceId>` as their first positional. The `list`
-action is the exception — it operates on the fleet, with an optional
-`<pattern>` to filter results.
+Most verbs take a `<device>` as their first positional; `list` works on
+the whole account.
 
 #### `list`
 
-List every device visible to the active profile, or filter with a
-case-insensitive regex (matched against device id and name on the
-server side):
+List every device visible to the active profile, or search and filter
+them on the server:
 
 ```bash
-thinr device list                    # every device
-thinr device list supermicro         # only ids/names containing "supermicro"
-thinr device list "^revpi|jetson"    # regex alternation works too
-thinr device list --json             # JSON envelope with the raw API records
+thinr device list                              # every device
+thinr device list --search supermicro          # ids/names containing "supermicro"
+thinr device list --filter product=my-product  # filters are repeatable
+thinr device list --json                       # JSON envelope with the raw API records
 ```
 
 Combine with the global `-u, --user` flag for admin impersonation.
 
-#### Records — `info` / `create` / `delete` / `set-product`
+#### Records — `get` / `create` / `update` / `delete` / `set-product`
 
 ```bash
-thinr device info <deviceId>                       # server record as JSON
-thinr device create <deviceId> [-t Generic|MQTT|HTTP|Virtual|Subdevice] [-p product]
-thinr device delete <deviceId> [-y]
-thinr device set-product <deviceId> <productId>    # "" to unassign
-thinr device property-set <deviceId> <property> <json>
+thinr device get <device>                          # server record as JSON (-f <path> for one field)
+thinr device create <device> [-t Generic|MQTT|HTTP|Virtual|Subdevice] [-p product] [-n name]
+thinr device update <device> -s name="Boiler 1"
+thinr device delete <device> [-y]
+thinr device set-product <device> <product>        # "" to unassign
 ```
 
 `create` generates random credentials for Generic/MQTT devices unless
@@ -177,7 +181,7 @@ thinr device property-set <deviceId> <property> <json>
 Open an interactive terminal on the device:
 
 ```bash
-thinr device console <deviceId>
+thinr device console <device>
 ```
 
 #### Proxies — `tcp` / `tls` / `http`
@@ -186,9 +190,9 @@ Create a TCP, TLS, or HTTP proxy to a remote endpoint reachable from
 the device:
 
 ```bash
-thinr device tcp  <deviceId> [target] [options]
-thinr device tls  <deviceId> [target] [options]
-thinr device http <deviceId> [target] [options]
+thinr device tcp  <device> [target] [options]
+thinr device tls  <device> [target] [options]
+thinr device http <device> [target] [options]
 ```
 
 `target` is the remote address and port on the device side. Defaults
@@ -216,24 +220,24 @@ thinr device http RevPi20679 http://192.168.1.45:8080
 #### `status`
 
 ```bash
-thinr device status <deviceId> [-j, --json]
+thinr device status <device> [-j, --json]
 ```
 
 Returns the device's connection stats (uptime, tx/rx, last-seen).
 
 #### `property`
 
-List every property of a device, or read one by id:
+The properties of a device are records of their own:
 
 ```bash
-thinr device property <deviceId>                                # list
-thinr device property <deviceId> <propertyId> [options]         # read
+thinr device property list <device>
+thinr device property get  <device> <property> [-f value.threshold]
+thinr device property set  <device> <property> '{"threshold": 30}'   # created when missing
+thinr device property delete <device> <property> [-y]
 ```
 
-Options:
-
-- `-j, --json`: Output as JSON
-- `-f, --field <path>`: Extract a sub-field via dot path (`-f data.value`)
+`-f, --field <path>` prints one field of the record: the value of a
+property is under `value`.
 
 #### `resource`
 
@@ -241,22 +245,21 @@ List the resources exposed by the device (with their `in`/`out`
 schemas when advertised), or call one:
 
 ```bash
-thinr device resource <deviceId>                                # list
-thinr device resource <deviceId> <resourceId> [options]         # call
+thinr device resource list <device>
+thinr device resource call <device> <resource>                 # read its output
+thinr device resource call <device> <resource> -s value=true   # run it with an input
 ```
 
-Options:
-
-- `-i, --input <key=value>`: Resource input (repeatable)
-- `-j, --json`: Output as JSON
-- `-f, --field <path>`: Extract a sub-field from the result (dot path)
+`call` takes the input from `--from <file>` (`-` for stdin) and
+`-s, --set key=value` (repeatable, values parsed as JSON when they are),
+and prints the answer, or one field of it with `-f, --field <path>`.
 
 #### `exec`
 
 Run a shell command on the device and stream stdout/stderr back:
 
 ```bash
-thinr device exec <deviceId> "<command>" [options]
+thinr device exec <device> "<command>" [options]
 ```
 
 Options:
@@ -267,28 +270,18 @@ Options:
 
 The process exits with the remote command's exit code.
 
-#### `update`
-
-Check for or apply an agent update on the device:
-
-```bash
-thinr device update check <deviceId> [options]
-thinr device update apply <deviceId> [options]
-```
-
-Options:
+### `thinr product`
 
-- `--channel <name>`: Update channel (default: `latest`)
-- `-j, --json`: Output as JSON
+Besides its records (`list`, `get`, `create`, `update`, `delete`,
+`export`, `apply`, `profile`…), a product fans operations out across
+every device that belongs to it.
 
-### `thinr product <action> <productId>`
+#### `device-property`
 
-Fan out an operation across every device that belongs to a product.
-
-#### `property`
+Read a property on every device of the product:
 
 ```bash
-thinr product property <productId> <propertyId> [options]
+thinr product device-property <product> <property> [options]
 ```
 
 Options:
@@ -299,10 +292,12 @@ Options:
 - `-a, --all`: Include offline devices (default: only active)
 - `-g, --group <group>`: Filter devices by asset group
 
-#### `resource`
+#### `device-resource`
+
+Call a resource on every active device of the product:
 
 ```bash
-thinr product resource <productId> <resource> [options]
+thinr product device-resource <product> <resource> [options]
 ```
 
 Options:
@@ -310,10 +305,28 @@ Options:
 - `-j, --json`: Output as JSON (`results[]` array, same shape as above)
 - `-f, --field <path>`: Extract a sub-field from each result (dot path)
 - `-g, --group <group>`: Filter devices by asset group
-- `-i, --input <key=value>`: Resource input (repeatable)
+- `--from <file>`, `-s, --set <key=value>`: Resource input (`-s` is
+  repeatable)
 
-Offline devices are skipped for `resource` — the server would reject
-the call anyway.
+Offline devices are skipped for `device-resource` — the server would
+reject the call anyway.
+
+#### `metric` and `logs`
+
+What thinr's terminal dashboard shows for the devices of a product:
+
+```bash
+thinr product metric list   <product>
+thinr product metric set    <product> <name> [options]
+thinr product metric delete <product> <name> [-y]
+
+thinr product logs presets                         # patterns shipped with thinr
+thinr product logs list        <product>
+thinr product logs get         <product> <name>
+thinr product logs create      <product> <name> [options]
+thinr product logs delete      <product> <name> [-y]
+thinr product logs set-default <product> <name>
+```
 
 #### `exec`
 
@@ -322,7 +335,7 @@ product and report a per-device status table plus each device's
 output:
 
 ```bash
-thinr product exec <productId> <command...> [options]
+thinr product exec <product> <command...> [options]
 ```
 
 Options:
@@ -349,9 +362,9 @@ thinr product exec my-product "apt-get -y upgrade" -c 5 --timeout 600
 thinr product exec my-product "systemctl restart agent" -g staging
 ```
 
-Also exposed to MCP clients as `thinr_device_exec` with `product` (and
-`group`), so agents run a fleet operation with a single call instead of
-looping per device.
+Also exposed to MCP clients as the `exec` action of type `device` with
+body `product` (and `group`), so agents run a fleet operation with a
+single call instead of looping per device.
 
 #### `playbook`
 
@@ -359,11 +372,11 @@ Manage playbooks stored on a product and run them against one device
 or the whole fleet:
 
 ```bash
-thinr product playbook list     <productId> [--json]
-thinr product playbook upload   <productId> <name> [file] [--description <text>] [--skip-validation] [--json]
-thinr product playbook download <productId> <name> [-o <file>] [--json]
-thinr product playbook delete   <productId> <name> [--json]
-thinr product playbook run      <productId> <name> (--device <id> | --fleet) [options]
+thinr product playbook list     <product> [--json]
+thinr product playbook upload   <product> <name> [file] [--description <text>] [--skip-validation] [--json]
+thinr product playbook download <product> <name> [-o <file>] [--json]
+thinr product playbook delete   <product> <name> [-y] [--json]
+thinr product playbook run      <product> <name> (--device <id> | --fleet) [options]
 ```
 
 `upload` reads the YAML from a file, or from stdin when the path is
@@ -400,6 +413,28 @@ Each fleet rollout writes a persistent JSON report to
 storage, capturing resolved variables, per-device outcomes, and any
 abort reason.
 
+### `thinr agent`
+
+The ThinRemote agent running on the devices: check whether a device has a
+newer release, and update one device or the whole fleet.
+
+```bash
+thinr agent check  <device> [--channel latest] [-j]
+thinr agent update <device> [--channel latest] [-j]
+thinr agent update --all [-p <product>] [-g <group>] [options]
+```
+
+`update --all` updates every outdated device: a canary first, then in
+batches. Options (only with `--all`):
+
+- `-p, --product <id>`, `-g, --group <id>` — narrow the fleet.
+- `--batch-size <n>` — devices updated in parallel once the canary
+  passes (default: 5).
+- `--no-canary` — everything in batches from the start.
+- `--continue-on-error` — keep rolling after a batch failure.
+- `--dry-run` — list what would be updated, without updating it.
+- `-y, --yes` — no confirmation (required in non-interactive shells).
+
 ### `thinr playbook <action>`
 
 Run or validate a local playbook YAML file (not stored on a product).
@@ -447,7 +482,7 @@ active profile; `--server`, `--username` and `--token` skip the prompts.
 ## Part 2 — MCP server
 
 `thinr` ships an [MCP][mcp] server for AI clients (Claude Code, Claude
-Desktop, Cursor and any other MCP host): 24 tools that reach everything the
+Desktop, Cursor and any other MCP host): eight tools that reach everything the
 CLI does, through the same API, with stable schemas and one error contract.
 
 ### Starting the server
@@ -465,37 +500,47 @@ device of any configured environment without a restart.
 ### Tools
 
 thinr is built on [`@thinger-io/cli-core`][cli-core], the core it shares
-with the `thinger` CLI, and serves its 23 generic tools with the `thinr_`
-prefix plus one of its own:
-
-| Tools                                                                                                                                                                       | What for                                                                                                                                                                                                |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `thinr_resource_describe`, `_list`, `_get`, `_create`, `_update`, `_delete`, `_clone`, `_call`                                                                              | Every resource type: the server's and ThinRemote's (below), and their actions                                                                                                                           |
-| `thinr_device_resource_list`, `thinr_device_resource_call`                                                                                                                  | What a connected device exposes: agent resources (`monitoring`, `cmd`…) and its scripts                                                                                                                 |
-| `thinr_bucket_data_read`, `thinr_bucket_data_write`                                                                                                                         | Time series, monitoring history included (bucket `monitoring`)                                                                                                                                          |
-| `thinr_storage_file_*`, `thinr_dashboard_init` / `_dev` / `_publish`, `thinr_plugin_call`, `thinr_product_resource_call`, `thinr_device_data_send`, `thinr_device_overview` | Storages, web dashboards (create, develop against the server, publish), plugins, product APIs, HTTP devices, account usage                                                                              |
-| `thinr_doc_read`, `thinr_profile_list`                                                                                                                                      | Guides for agents (`thinremote`, `thinremote-scripts`, `thinremote-playbooks`, `thinremote-metrics-logs`, and the platform's: `concepts`, `product-code`, `server-admin`, `dashboard-sdk`) and profiles |
-| `thinr_device_exec`                                                                                                                                                         | A shell command on one device, or on several at once (`devices`, `product`, `group`, `all`)                                                                                                             |
-
-ThinRemote adds its own resource types to the generic tools, so they are
-listed, read, written and deleted like a device or a token:
-
-| Type                 | Parent  | What it is                                                                     | Actions (`thinr_resource_call`) |
-| -------------------- | ------- | ------------------------------------------------------------------------------ | ------------------------------- |
-| `device_fs`          | device  | Files and folders of the device (id: the path)                                 | `move`, `push`, `pull`          |
-| `device_script`      | device  | Scripts of the agent, each a resource of the device                            |                                 |
-| `product_script`     | product | Scripts run on any device of the product, kept once in its storage             |                                 |
-| `product_metric`     | product | Metrics of thinr's terminal dashboard                                          |                                 |
-| `product_log_source` | product | Log sources an operator streams from a device                                  |                                 |
-| `product_playbook`   | product | Playbooks: YAML steps validated, tried on one device and rolled out in batches | `validate`, `run`, `rollout`    |
-
-and two actions to the server's `device` type: `agent_update` (check for or
-install a new agent) and `agent_install` (the command that installs the
-agent on a new machine). Live monitoring is the device resource
-`monitoring`; its history, the bucket `monitoring`.
-
-Full input schemas come with the standard MCP `tools/list`, and
-`thinr_resource_describe` gives each type's fields and actions.
+with the `thinger` CLI, and serves its eight tools with the `thinr_`
+prefix: `thinr_resource_describe`, `_list`, `_get`, `_create`, `_update`,
+`_delete`, `_clone` and `_call` (actions). Each takes a `type` and the
+record's `ids`, one key per level (`{"device": "gw_1"}`,
+`{"device": "gw_1", "path": "/etc/hosts"}`,
+`{"product": "gateways", "playbook": "app-config"}`); the records they
+answer carry their ids.
+
+| Types                                                                  | What for                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The server's (`device`, `product`, `bucket`, `token`, `alarm_rule`…)   | Every resource of the account and their actions                                                                                                                                                                     |
+| `device_resource` (list; action `call`)                                | What a connected device exposes: agent resources (`monitoring`, `cmd`…) and its scripts                                                                                                                             |
+| `bucket_data` (list reads, create writes)                              | Time series, monitoring history included (bucket `monitoring`)                                                                                                                                                      |
+| `storage_file`; `dashboard` actions `init` / `dev` / `publish`; others | Storages, web dashboards (create, develop against the server, publish), plugins (`plugin` `call`), product APIs (`product_profile_api` `call`), HTTP devices (`device` `send`), account usage (`device` `overview`) |
+| `doc`, `profile`                                                       | Guides for agents (`thinremote`, `thinremote-scripts`, `thinremote-playbooks`, `thinremote-metrics-logs`, and the platform's: `concepts`, `product-code`, `server-admin`, `dashboard-sdk`) and profiles             |
+
+ThinRemote adds its own resource types, listed, read, written and deleted
+like a device or a token:
+
+| Type               | ids                   | What it is                                                                     | Actions (`thinr_resource_call`) |
+| ------------------ | --------------------- | ------------------------------------------------------------------------------ | ------------------------------- |
+| `device_fs`        | `device`, `path`      | Files and folders of the device                                                | `move`, `push`, `pull`          |
+| `device_script`    | `device`, `script`    | Scripts of the agent, each a resource of the device                            |                                 |
+| `product_script`   | `product`, `script`   | Scripts run on any device of the product, kept once in its storage             |                                 |
+| `product_playbook` | `product`, `playbook` | Playbooks: YAML steps validated, tried on one device and rolled out in batches | `validate`, `run`, `rollout`    |
+
+and three actions to the server's `device` type: `exec` (a shell command
+on one device, `ids.device`, or on several at once: body `devices`,
+`product`, `group`, `all`), `agent_update` (check for or install a new
+agent) and `agent_install` (the command that installs the agent on a new
+machine). Live monitoring is the device resource `monitoring`; its
+history, the bucket `monitoring`. The fleet metrics and log sources of
+thinr's terminal dashboard are the product properties `dashboard_metrics`
+and `logs`, checked before they are written.
+
+`exec` on several devices, playbook runs on several devices and rollouts
+answer their targets first and run with `confirm: true` (clients that
+support elicitation ask the user instead). `thinr mcp --read-only` (or
+`THINR_MCP_READ_ONLY=1`) serves only what reads. Full input schemas come
+with the standard MCP `tools/list`, and `thinr_resource_describe` gives
+each type's ids, fields, actions and examples.
 
 [cli-core]: https://github.com/thinger-io/thinger-cli-core
 
@@ -513,15 +558,16 @@ writing YAML by hand:
 2. **Draft and validate.** Write the YAML and call `thinr_resource_call`
    type `product_playbook`, action `validate`, with it in `body.content`;
    fix what it reports until it is clean.
-3. **Save.** `thinr_resource_create` type `product_playbook`, parent the
-   product, id a short name, body `{content}`. It is validated again and
-   nothing is saved if invalid.
-4. **Pre-flight on one device.** Action `run` with the playbook's id and
+3. **Save.** `thinr_resource_create` type `product_playbook`, ids
+   `{"product", "playbook": <a short name>}`, body `{content}`. It is
+   validated again and nothing is saved if invalid.
+4. **Pre-flight on one device.** Action `run` with `ids.playbook` and
    `body.device`, with `dry_run: true` or `check: true` for a read-only
    preview, then for real.
 5. **Roll out.** Action `rollout` runs it across the fleet in batches with a
    failure-rate stop, and writes a report to `playbooks/runs/` in the
-   product storage.
+   product storage. It answers its plan first and runs with
+   `confirm: true` once the user agrees.
 
 Example prompt:
 
@@ -537,10 +583,10 @@ A second message like "looks good, roll it out to staging" maps to the
 ### Per-call controls
 
 - **`profile`**: optional on every tool. Uses another configured server for
-  that call only; `thinr_profile_list` lists them.
+  that call only; `thinr_resource_list` type `profile` lists them.
 - **`user`**: optional admin impersonation; defaults to the profile's user.
-- Devices are named per call (`device`, or `parent` for a device's
-  resources): list them with `thinr_resource_list` type `device`.
+- Devices are named per call (`ids.device`): list them with
+  `thinr_resource_list` type `device`.
 
 ### Integrating with Claude Code
 
@@ -611,16 +657,17 @@ Use `thinr profile use <name>` to change the persisted default, or
 ```
 thinr-cli/
 ├── bin/           # CLI entry point (thinr)
-├── commands/      # ThinRemote subcommands (agent, fleet, playbooks…)
+├── commands/      # ThinRemote subcommands (agent, device, product, playbooks…)
 ├── lib/           # ThinRemote modules: identity, device-api, proxy,
 │                  # console, playbooks, product scripts, MCP tools…
 ├── package.json
 └── README.md
 ```
 
-The generic part — API client, auth, profiles, REST helpers, the generic
-commands (login, logout, profile, device list/info/property/resource,
-product list/property-\_, bucket) and the generic MCP tools — comes from
+The generic part — API client, auth, profiles, REST helpers, the command
+grammar, the generic commands (login, logout, profile, api, the records of
+every resource type, device resource, bucket, storage…) and the generic MCP
+tools — comes from
 [@thinger-io/cli-core](https://github.com/thinger-io/cli-core), shared
 with the `thinger` CLI. `lib/identity.js` is what makes it `thinr`: names,
 `~/.config/thinr-cli`, `THINR\__`, the OAuth client and the product