@thinremote/thinr-cli 1.5.0 → 1.6.1

package/docs/guides/thinremote-playbooks.md

@@ -10,9 +10,9 @@ Tool names below omit the `thinr_` prefix.
 
 ## Authoring flow
 
-A saved playbook is a resource of type `product_playbook`, with the product
-as parent and its name as id; validating, running and rolling it out are
-its actions (`resource_call`).
+A saved playbook is a resource of type `product_playbook`, ids
+`{"product", "playbook"}` (its name); validating, running and rolling it
+out are its actions (`resource_call`).
 
 1. `resource_describe` type `product_playbook` once: its `playbook_format`
    is the full schema (document, `vars`, step fields, every action with its
@@ -24,15 +24,17 @@ its actions (`resource_call`).
    saved if invalid; it writes `playbooks/<name>.yaml` in the product storage
    and registers it in the `playbooks` product property). Change it later
    with `resource_update`.
-4. Try it on one device: action `run` with the playbook's `id` and
+4. Try it on one device: action `run` with the playbook in `ids.playbook` and
    `body.device`, first with `dry_run: true` (the resolved plan, no device
    contacted), then `check: true` (contacts the device read-only: each step
    says changed / unchanged / unknown), then for real.
 5. Roll it out: action `rollout` (below).
 
-For a one-off run that is not worth saving, action `run` without `id` takes
-the YAML in `body.content`, with the same `dry_run` and `check`; it targets
-`body.device`, `body.devices`, `body.group` or every device of the product.
+For a one-off run that is not worth saving, action `run` without
+`ids.playbook` takes the YAML in `body.content`, with the same `dry_run`
+and `check`; it targets `body.device`, `body.devices`, `body.group` or every
+device of the product (`body.all`). On several devices it answers its
+targets first, and runs with `confirm: true` in the body.
 
 `resource_list` and `resource_get` show what a product has (`get` includes
 the YAML); `resource_delete` removes one (index entry, then file).
@@ -111,17 +113,19 @@ inside its local folder (`THINR_MCP_LOCAL_DIR`, or where it started).
 
 ## Rolling out
 
-Action `rollout` (`resource_call` type `product_playbook`, the playbook's
-`id`) runs a saved playbook on every matching device of the product, in batches of `body.batch_size` (default 5). A batch finishes before
+Action `rollout` (`resource_call` type `product_playbook`, the playbook in
+`ids.playbook`) runs a saved playbook on every matching device of the product, in batches of `body.batch_size` (default 5). A batch finishes before
 the next starts; after each one the cumulative failure rate is compared
 with `body.failure_threshold` (default 10 %), and reaching it stops the rollout
 without touching the remaining devices. Narrow the targets with `group` or
 `filter`; offline devices are skipped unless `include_offline`. `dry_run`
 lists the plan and the devices; `check` reports what would change.
+Without `dry_run` or `check` it answers that plan first: show it to the
+user and call again with `confirm: true` in the body once they agree.
 
 Each rollout writes a report to `playbooks/runs/<timestamp>-<name>-<user>.json`
-in the product storage (read it with `storage_file_read`, storage named like
-the product): resolved variables, per-device outcome, and why it stopped if
+in the product storage (read it with `resource_get` type `storage_file`,
+ids `{"storage": <the product's id>, "file": "playbooks/runs/…"}`): resolved variables, per-device outcome, and why it stopped if
 it did. A rollout that stops does not undo the devices it already changed:
 write files to a temporary path and `move` them into place, so a device is
 never left with half a change.

package/docs/guides/thinremote-scripts.md

@@ -3,23 +3,24 @@
 A script turns an operation (read a sensor, rotate a log, run a backup,
 collect a health report) into a **resource**: something with a name and an
 input/output shape that tools, dashboards and other devices can call. Use one
-instead of `thinr_device_exec` whenever the operation will be repeated.
+instead of the `exec` action whenever the operation will be repeated.
 
 Both kinds are resource types: `resource_list` / `_get` / `_create` /
-`_update` / `_delete` with type `device_script` (parent the device) or
-`product_script` (parent the product), the file name as id.
+`_update` / `_delete` with type `device_script` (ids
+`{"device", "script"}`) or `product_script` (ids `{"product", "script"}`),
+the file name as `ids.script` (or as `name` in the body of a create).
 
 Tool names below omit the `thinr_` prefix.
 
 ## Device scripts or product scripts
 
-|             | Device script                         | Product script                                      |
-| ----------- | ------------------------------------- | --------------------------------------------------- |
-| Lives in    | the device: `<agent base>/scripts/`   | the product's file storage: `scripts/`              |
-| Reaches     | that device                           | every device of the product, current and future     |
-| Changing it | one write per device                  | one write, effective on the next call everywhere    |
-| Type        | `device_script`, parent the device    | `product_script`, parent the product                |
-| Called with | `device_resource_call` on that device | `device_resource_call` on any device of the product |
+|             | Device script                               | Product script                                        |
+| ----------- | ------------------------------------------- | ----------------------------------------------------- |
+| Lives in    | the device: `<agent base>/scripts/`         | the product's file storage: `scripts/`                |
+| Reaches     | that device                                 | every device of the product, current and future       |
+| Changing it | one write per device                        | one write, effective on the next call everywhere      |
+| Type        | `device_script`, ids `{"device", "script"}` | `product_script`, ids `{"product", "script"}`         |
+| Called with | `device_resource` `call` on that device     | `device_resource` `call` on any device of the product |
 
 Prefer **product scripts** for fleets: the code is downloaded on each call,
 so there is nothing to deploy and no drift between devices. Use a device

package/docs/guides/thinremote.md

@@ -5,12 +5,18 @@ Thinger.io server. Each machine runs **thinr-agent**, which connects to the
 server as a device and lets you operate it remotely: files, commands,
 scripts, monitoring, logs.
 
-Almost everything is a **resource type** behind the generic tools
-`resource_list` / `_get` / `_create` / `_update` / `_delete` and
-`resource_call` (its actions), described by `resource_describe`: the
-server's types (device, product, bucket, property, token, alarm…; read the
-server's `concepts` guide with `doc_read`) and ThinRemote's, below. The one
-tool of its own is `device_exec`, for shell commands.
+Everything is a **resource type** behind eight tools: `resource_list` /
+`_get` / `_create` / `_update` / `_delete` / `_clone` and `resource_call`
+(its actions), described by `resource_describe`: the server's types
+(device, product, bucket, property, token, alarm…; read the server's
+`concepts` guide with `resource_get` type `doc`, ids `{"doc": "concepts"}`),
+data and files (`bucket_data`, `storage_file`, `device_resource`) and
+ThinRemote's, below. Shell commands are the `exec` action of type `device`.
+
+Each call names the record with `ids`, one key per level:
+`{"device": "gw_1"}`, `{"device": "gw_1", "path": "/etc/hosts"}`,
+`{"product": "gateways", "playbook": "app-config"}`. The records the tools
+answer carry their `ids`: pass them back as they are.
 
 Tool names below omit the `thinr_` prefix.
 
@@ -26,20 +32,20 @@ to system paths.
 
 What the agent offers, and how to reach it:
 
-| Need                                        | How                                                                                                                             |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Run a shell command                         | `device_exec` with `device` (output and exit code; `timeout` in s)                                                              |
-| List a folder                               | `resource_list` type `device_fs`, parent the device, `filter: {"path": "/var/log"}`                                             |
-| Read a file                                 | `resource_get` type `device_fs`, parent the device, id the path                                                                 |
-| Write a file / create a folder              | `resource_create` (or `_update`) type `device_fs`, body `{"content": "…"}` / `{"type": "directory"}`                            |
-| Delete a file or folder                     | `resource_delete` type `device_fs`                                                                                              |
-| Move, or copy binaries from/to this machine | `resource_call` type `device_fs`, action `move`, `push` or `pull`                                                               |
-| CPU, memory, disk, network, load: now       | `device_resource_call` resource `monitoring`                                                                                    |
-| The same, as history                        | `bucket_data_read` bucket `monitoring` with `device` (fields such as `cpu.usage`, `memory.usage`, `disk.root.usage`, `load.1m`) |
-| A reusable, typed operation on one device   | type `device_script` (see `thinremote-scripts`)                                                                                 |
-| Call what the agent or a script exposes     | `device_resource_list`, `device_resource_call`                                                                                  |
-| Update the agent                            | `resource_call` type `device`, action `agent_update`, body `{"action": "check"}` or `{"action": "apply"}`                       |
-| Install the agent on a new machine          | `resource_call` type `device`, action `agent_install` (a shell one-liner; no id)                                                |
+| Need                                        | How                                                                                                                                                                |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Run a shell command                         | `resource_call` type `device`, action `exec`, ids `{"device"}`, body `{"command": "…"}` (output and exit code)                                                     |
+| List a folder                               | `resource_list` type `device_fs`, ids `{"device"}`, `filter: {"path": "/var/log"}`                                                                                 |
+| Read a file                                 | `resource_get` type `device_fs`, ids `{"device", "path"}`                                                                                                          |
+| Write a file / create a folder              | `resource_create` (or `_update`) type `device_fs`, body `{"content": "…"}` / `{"type": "directory"}`                                                               |
+| Delete a file or folder                     | `resource_delete` type `device_fs`                                                                                                                                 |
+| Move, or copy binaries from/to this machine | `resource_call` type `device_fs`, action `move`, `push` or `pull`                                                                                                  |
+| CPU, memory, disk, network, load: now       | `resource_call` type `device_resource`, action `call`, ids `{"device", "resource": "monitoring"}`                                                                  |
+| The same, as history                        | `resource_list` type `bucket_data`, ids `{"bucket": "monitoring"}`, filter `{"device"}` (fields such as `cpu.usage`, `memory.usage`, `disk.root.usage`, `load.1m`) |
+| A reusable, typed operation on one device   | type `device_script` (see `thinremote-scripts`)                                                                                                                    |
+| Call what the agent or a script exposes     | `resource_list` type `device_resource`; `resource_call` type `device_resource`, action `call`                                                                      |
+| Update the agent                            | `resource_call` type `device`, action `agent_update`, body `{"action": "check"}` or `{"action": "apply"}`                                                          |
+| Install the agent on a new machine          | `resource_call` type `device`, action `agent_install` (a shell one-liner; no ids)                                                                                  |
 
 Paths are absolute on the device. `/` on its own lists the agent's working
 directory (normally the root, reported as `fs_base_path`); nothing is
@@ -56,18 +62,20 @@ products are created with `resource_create` type `product` and come with
 `config.type: "thinremote"` and a `monitoring` bucket that stores each
 device's `monitoring` resource every 60 s (the history above; a device of
 another kind of product has no history unless its product gets that bucket). On top of the
-server's product, ThinRemote keeps these types, all with the product as
-parent:
+server's product, ThinRemote keeps these, all under the product (ids
+`{"product", …}`):
 
-| Type                 | What it is                                                                    | Where it lives                                                             | Guide                     |
-| -------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
-| `product_script`     | Code run on any device of the product, kept in one place                      | file storage named like the product, `scripts/`; one product API resource  | `thinremote-scripts`      |
-| `product_playbook`   | Ordered steps rolled out across devices; actions `validate`, `run`, `rollout` | same storage, `playbooks/<name>.yaml`, indexed in the `playbooks` property | `thinremote-playbooks`    |
-| `product_metric`     | Metrics for thinr's terminal dashboard                                        | `dashboard_metrics` product property                                       | `thinremote-metrics-logs` |
-| `product_log_source` | Log sources for thinr (dashboard, `thinr device logs`)                        | `logs` product property                                                    | `thinremote-metrics-logs` |
+| Type or property                       | What it is                                                                    | Where it lives                                                             | Guide                     |
+| -------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `product_script` (ids.script)          | Code run on any device of the product, kept in one place                      | file storage named like the product, `scripts/`; one product API resource  | `thinremote-scripts`      |
+| `product_playbook` (ids.playbook)      | Ordered steps rolled out across devices; actions `validate`, `run`, `rollout` | same storage, `playbooks/<name>.yaml`, indexed in the `playbooks` property | `thinremote-playbooks`    |
+| `product_property` `dashboard_metrics` | Metrics for thinr's terminal dashboard (an array, written whole)              | that product property                                                      | `thinremote-metrics-logs` |
+| `product_property` `logs`              | Log sources for thinr (dashboard, `thinr device logs`; written whole)         | that product property                                                      | `thinremote-metrics-logs` |
 
-Creating one that already exists fails (update it instead), and updating one
-that does not exist fails too, as with the server's types.
+Creating a script or playbook that already exists fails (update it
+instead), and updating one that does not exist fails too, as with the
+server's types. The two product properties are checked before they are
+written: `resource_describe` type `product_property` shows their shape.
 
 Deleting a product with `resource_delete` also deletes its file storage (its
 scripts and playbooks).
@@ -78,17 +86,19 @@ Devices join a product when they are created with `product`, with
 
 ## Fleet operations
 
-| Need                                       | How                                                                                                     |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| Same command on many devices, once         | `device_exec` with `devices`, `product` (and `group`) or `all: true`; `dry_run` lists the targets first |
-| Same file on every device                  | a playbook with a `write` step (to a temporary file, then `move`), rolled out                           |
-| A repeatable, versioned change with checks | a playbook: action `run` on one device, then action `rollout`                                           |
-| A value from every device                  | a product script + `device_resource_call` per device, or a metric                                       |
-| Which devices are online                   | `resource_list` type `device` with `filter: {"product": "<id>"}`                                        |
-| Fleet health at a glance                   | `bucket_data_read` bucket `monitoring` without `device`, `group_by` device                              |
+| Need                                       | How                                                                                                                                       |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Same command on many devices, once         | `resource_call` type `device`, action `exec`, no ids, body `devices`, `product` (and `group`) or `all: true`; `dry_run` lists the targets |
+| Same file on every device                  | a playbook with a `write` step (to a temporary file, then `move`), rolled out                                                             |
+| A repeatable, versioned change with checks | a playbook: action `run` on one device, then action `rollout`                                                                             |
+| A value from every device                  | a product script + `device_resource` `call` per device, or a metric                                                                       |
+| Which devices are online                   | `resource_list` type `device` with `filter: {"product": "<id>"}`                                                                          |
+| Fleet health at a glance                   | `resource_list` type `bucket_data`, ids `{"bucket": "monitoring"}`, filter `{"group_by": "device"}`                                       |
 
 Offline devices are skipped unless asked (`include_offline`). Commands on
-several devices and rollouts act at once: confirm with the user first.
+several devices, playbook runs on several devices and rollouts answer
+their targets first: show them to the user and call again with
+`confirm: true` in the body once they agree.
 
 ## Recipes
 
@@ -100,8 +110,9 @@ command on the machine → the device appears (autoprovisioned or created) →
 
 **Expose a health check for the whole fleet.** Write it once as a product
 script (`resource_create` type `product_script`, output-only, JSON on
-stdout) → call it on a device with `device_resource_call` to check it →
-register a metric over it (`resource_create` type `product_metric`) so
+stdout) → call it on a device (`resource_call` type `device_resource`,
+action `call`) to check it → add a metric over it to the product property
+`dashboard_metrics` (read it, append, `resource_update` the whole array) so
 thinr's dashboard aggregates it across the fleet.
 
 **Change a config file on every machine, safely.** `resource_describe` type
@@ -111,6 +122,6 @@ action `run` on one device with `check: true`, then for real → action
 `rollout` with a small `batch_size`.
 
 **Investigate one machine.** `resource_get` type `device` (agent info) →
-`device_resource_call` resource `monitoring` → `device_exec` for specifics →
+`device_resource` `call` of `monitoring` → the `exec` action for specifics →
 `resource_get` type `device_fs` for log files, or the product's log sources
 with `thinr device logs`.

package/lib/agent-releases.js

@@ -5,7 +5,7 @@
  * `https://get.thinremote.io/<channel>.json`. Same file the agent itself
  * polls to decide whether a self-update is available — keeping a single
  * source of truth between what the CLI offers and what a device would
- * actually download if the user ran `thinr device update apply`.
+ * actually download if the user ran `thinr agent update`.
  *
  * Why a dedicated module: the TUI hook (`useLatestAgentVersion`) needed
  * React-aware polling, the CLI just wants a one-shot fetch. Sharing the

package/lib/cli.js

@@ -0,0 +1,172 @@
+// @ts-check
+import figlet from 'figlet';
+import { authenticate } from '@thinger-io/cli-core/auth';
+import { configExists } from '@thinger-io/cli-core/config';
+import { accent, info } from '@thinger-io/cli-core/format';
+import { mcpInstructions } from './identity.js';
+import { resourceHooks } from './mcp/resource-hooks.js';
+import { resourceActions, resourceTypes } from './mcp/resource-types.js';
+import { guides } from './guides.js';
+import { registerDeviceCommands } from '../commands/device/index.js';
+import { registerProductCommands } from '../commands/product/index.js';
+import { agentCommand } from '../commands/agent/index.js';
+import { playbookCommand } from '../commands/playbook/index.js';
+import { runDashboard } from '../commands/dashboard.js';
+
+/**
+ * What thinr adds to the CLI of @thinger-io/cli-core: its commands, MCP
+ * tools, resource types and guides. `bin/thinr.js` runs it with runCli;
+ * the tests build the same tree with buildProgram.
+ */
+
+function displayBanner() {
+    console.log(accent(figlet.textSync('thinr-cli', { horizontalLayout: 'full' })));
+    console.log(info('Thin Remote CLI - Remote management for IoT devices'));
+    console.log();
+}
+
+/**
+ * Exceptions of thinr's commands to the grammar of cli-core
+ * (`checkGrammar`): the verbs of a remote shell and file system, its
+ * groups, and the options it published with another meaning.
+ *
+ * @type {import('@thinger-io/cli-core/commands/grammar').GrammarExceptions}
+ */
+export const grammarExceptions = {
+    root: ['agent', 'playbook'],
+    verbs: [
+        // Remote access and execution.
+        'tcp',
+        'tls',
+        'http',
+        'console',
+        'exec',
+        'status',
+        'logs',
+        // Files of a device (`read` and `write` are verbs already).
+        'ls',
+        'mkdir',
+        'rm',
+        'mv',
+        'push',
+        'pull',
+        // Agent, fan-outs, playbooks and log sources.
+        'check',
+        'device-property',
+        'device-resource',
+        'run',
+        'validate',
+        'set-default',
+        'presets',
+    ],
+    shorts: {
+        'device logs': { '-f': '--follow' },
+        'device mv': { '-f': '--force' },
+        'product mv': { '-f': '--force' },
+    },
+    skip: {
+        // Interactive sessions.
+        'device console': ['json'],
+        'device tcp': ['json'],
+        'device tls': ['json'],
+        'device http': ['json'],
+        // A file written on the device, a log source, an agent update: not JSON bodies.
+        'device write': ['body'],
+        'product logs create': ['body'],
+        'agent update': ['body'],
+        // Entries of a product property: short lists.
+        'product logs list': ['list'],
+        'product metric list': ['list'],
+        'product playbook list': ['list'],
+        // The presets ship with thinr: they belong to no product.
+        'product logs presets': ['parents'],
+    },
+};
+
+/** @type {Omit<Parameters<typeof import('@thinger-io/cli-core/cli').runCli>[0], 'version'>} */
+export const cliOptions = {
+    resourceHooks,
+    resourceTypes,
+    resourceActions,
+    docs: guides,
+    mcpInstructions,
+    argumentHelp: {
+        byCommand: {
+            'device tcp': { target: 'Port on the device, or host:port (default: 22)' },
+            'device tls': { target: 'Port on the device, or host:port (default: 443)' },
+            'device http': { target: 'Port on the device, or host:port (default: 80)' },
+            'device exec': { command: 'Command to run on the device' },
+            'device ls': { path: 'Folder on the device (default: /)' },
+            'device read': { path: 'File on the device' },
+            'device write': {
+                path: 'File on the device',
+                content: 'What to write (default: stdin)',
+            },
+            'device mkdir': { path: 'Folder to create on the device' },
+            'device rm': { path: 'File or folder to delete on the device' },
+            'device mv': { source: 'Path on the device', destination: 'New path on the device' },
+            'device push': {
+                'local-path': 'Local file or folder',
+                'remote-path': 'Where on the device',
+            },
+            'device pull': {
+                'remote-path': 'File or folder on the device',
+                'local-path': 'Where to save it',
+            },
+            'product exec': { command: 'Command to run on every device' },
+            'product mkdir': { path: 'Folder to create on every device' },
+            'product rm': { path: 'File or folder to delete on every device' },
+            'product mv': { source: 'Path on the devices', destination: 'New path on the devices' },
+            'product push': {
+                'local-path': 'Local file or folder',
+                'remote-path': 'Where on every device',
+            },
+            'product device-property': { property: 'Property to read on every device' },
+            'product device-resource': { resource: 'Resource to call on every device' },
+            'product metric set': { name: 'Name of the metric' },
+            'product metric delete': { name: 'Name of the metric' },
+            'product logs get': { name: 'Name of the log source' },
+            'product logs create': { name: 'Name of the log source' },
+            'product logs delete': { name: 'Name of the log source' },
+            'product logs set-default': { name: 'Name of the log source' },
+            'product playbook upload': {
+                name: 'Name of the playbook',
+                file: 'YAML file (default: stdin)',
+            },
+            'product playbook download': { name: 'Name of the playbook' },
+            'product playbook delete': { name: 'Name of the playbook' },
+            'product playbook run': { name: 'Name of the playbook' },
+            'playbook run': { file: 'Playbook file (YAML)' },
+            'playbook validate': { file: 'Playbook file (YAML)' },
+        },
+    },
+    register(program, groups) {
+        registerDeviceCommands(groups.device);
+        registerProductCommands(groups.product);
+        agentCommand(program);
+        playbookCommand(program);
+
+        const originalHelp = program.help;
+        /** @type {any} */ (program).help = function (cb) {
+            displayBanner();
+            return originalHelp.call(this, cb);
+        };
+    },
+    // Just `thinr`: launch the dashboard when running interactively (signing
+    // in first if there is no profile yet). Non-TTY contexts (pipes,
+    // scripts, `thinr | cat`) fall back to `--help` so they get something
+    // useful instead of an Ink crash.
+    async onNoCommand(program) {
+        if (!process.stdout.isTTY) program.help();
+        if (!configExists()) {
+            displayBanner();
+            try {
+                await authenticate();
+            } catch (error) {
+                console.error(`Configuration error: ${error.message}`);
+                process.exit(1);
+            }
+        }
+        await runDashboard();
+    },
+};

package/lib/constants.js

@@ -36,7 +36,7 @@ export const TIMEOUTS = {
     /**
      * Default command timeout (in *seconds*) for user-facing exec
      * flows: CLI `device exec`, `product exec`, playbook `exec`, MCP
-     * `thinr_exec`. Callers override when they know better.
+     * device action `exec`. Callers override when they know better.
      */
     DEFAULT_EXEC_SECONDS: 30,
 

package/lib/guides.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 /**
- * The guides thinr ships for agents (served by `thinr_doc_read` and as MCP
+ * The guides thinr ships for agents (served as type `doc` and as MCP
  * resources, next to the server's documentation). They describe what thinr
  * implements on top of the server — the agent, product scripts, playbooks,
  * the product dashboard — so they live and change with this code. Tool

package/lib/identity.js

@@ -68,9 +68,11 @@ export const thinrIdentity = {
 /** Server-level guidance sent to MCP clients on `initialize`. */
 export const mcpInstructions = `Tools to operate ThinRemote fleets: machines running thinr-agent on a Thinger.io server, with the permissions of the token stored in the CLI profile.
 
-- Read the guide first: thinr_doc_read id "thinremote" (the agent, products, which tool for each need, recipes); thinr_doc_read without id lists the rest (scripts, playbooks, metrics and logs) and the platform's guides (concepts, product code, server administration, the dashboard SDK).
-- Almost everything is a resource type behind thinr_resource_list / _get / _create / _update / _delete / _call, described by thinr_resource_describe: the server's (device, product, bucket, token, alarm…) and ThinRemote's: device_fs (a device's files and folders, parent = the device), device_script, product_script, product_metric, product_log_source and product_playbook (parent = the product; actions validate, run and rollout). Actions on devices: agent_update, agent_install (the command that installs the agent).
-- Shell commands: thinr_device_exec, on one device or on several (devices, product, group, all).
-- Monitoring: live with thinr_device_resource_call resource "monitoring"; history with thinr_bucket_data_read bucket "monitoring" (device for one), stored only for devices of products that have that bucket (ThinRemote products do).
-- List before acting to discover ids; never guess them. Fleet changes (thinr_device_exec on several devices, playbook rollouts) and deletes act immediately: confirm with the user first.
-- Every tool takes an optional \`profile\` (another configured server, see thinr_profile_list) and most take \`user\` (another account, admin only).`;
+- Read the guide first: thinr_resource_get type "doc" ids {"doc": "thinremote"} (the agent, products, which type or action for each need, recipes); thinr_resource_list type "doc" lists the rest (scripts, playbooks, metrics and logs) and the platform's guides (concepts, product code, server administration, the dashboard SDK).
+- Everything is a resource type behind eight tools: thinr_resource_list / _get / _create / _update / _delete / _clone and thinr_resource_call (actions), described by thinr_resource_describe: the server's (device, product, bucket, token, alarm…), data and files (bucket_data, storage_file, device_resource) and ThinRemote's: device_fs (a device's files and folders, ids {"device", "path"}), device_script (ids {"device", "script"}), product_script and product_playbook (ids {"product", "script"} and {"product", "playbook"}; playbook actions validate, run and rollout). Actions on devices: exec, agent_update, agent_install (the command that installs the agent). Each type's ids, filter, bodies, actions and ready-to-send examples are in thinr_resource_describe with that type: read it before the first call on a type.
+- A record is located by \`ids\`, one key per level; the records the tools answer carry their ids: pass them back as they are.
+- Shell commands: thinr_resource_call type "device" action "exec", with ids {"device": <id>} for one device, or without ids and body devices, product (and group), group or all for several; body.command; body.dry_run lists the targets first.
+- Monitoring: live with thinr_resource_call type "device_resource" action "call" ids {"device": <device>, "resource": "monitoring"}; history with thinr_resource_list type "bucket_data" ids {"bucket": "monitoring"} (filter {"device": <device>} for one), stored only for devices of products that have that bucket (ThinRemote products do).
+- Fleet metrics and log sources of thinr's terminal dashboard: the product properties "dashboard_metrics" and "logs" (thinr_resource_describe type "product_property" shows their shape).
+- List before acting to discover ids; never guess them. Deletes act immediately: confirm with the user first. Fleet changes (exec on several devices, playbook rollouts and runs on several devices) answer their targets first: show them to the user and repeat the call with confirm: true in the body only if they agree.
+- Every tool takes an optional \`profile\` (another configured server, see thinr_resource_list type "profile") and most take \`user\` (another account, admin only).`;