@thinremote/thinr-cli 1.3.4 → 1.4.0

package/docs/guides/thinremote-metrics-logs.md

@@ -0,0 +1,59 @@
+# ThinRemote fleet metrics and log sources
+
+Two per-product settings for operating a fleet from **thinr**: the metrics
+its terminal dashboard (`thinr` with no arguments) shows for a product, and
+the log sources an operator can stream from a device (in that dashboard or
+with `thinr device logs`). Today only thinr reads them; they are not the web
+console's dashboards (for those, see the server's `dashboard-sdk` guide and
+`thinr_dashboard_publish`). Both live on the server as product properties,
+so the devices need nothing and other clients could reuse them.
+
+Tool names below omit the `thinr_` prefix.
+
+## Metrics
+
+A metric is a value thinr's dashboard asks every device of the product for,
+and combines across the fleet: free disk, connected clients, service version…
+They live in the `dashboard_metrics` product property; edit them as the
+resource type `product_metric` (parent the product, id the metric's name:
+`resource_list`, `_get`, `_create`, `_update`, `_delete`), not by writing the
+property by hand.
+
+Fields of a metric:
+
+| Field           | Meaning                                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `name`          | Stable id (letters, digits, `_`, `-`): the resource id                                                   |
+| `label`         | Title in the panel                                                                                       |
+| `resource`      | Product API resource called on each device, usually a product script                                     |
+| `field`         | Dot path to the value in the response (`disk.used_pct`); omit for scalar responses                       |
+| `aggregation`   | `sum`, `avg`, `max`, `min` (numeric), `count` (devices reporting a value), `top`, `distribution`, `none` |
+| `visualization` | `kpi` (default: value and its age), `sparkline` (value and recent trend), `bar`, `list`                  |
+| `interval`      | Refresh in seconds (≥ 1); 0 or omitted relays only what devices push                                     |
+| `unit`          | Display suffix (`%`, `devices`)                                                                          |
+
+Recipe: write a product script that prints the value as JSON (see
+`thinremote-scripts`), check it with `device_resource_call` on one device,
+then register the metric pointing at the script's resource name.
+
+## Log sources
+
+A log source is a named shell command the agent streams when an operator
+opens a device's logs in thinr (`journalctl -f`, `docker logs -f app`,
+`tail -F /var/log/nginx/access.log`). They live in the `logs` product
+property; without it, products show a single `system` source running
+journalctl (listed with `fallback: true`). They are the resource type
+`product_log_source`, parent the product, id the source's name.
+
+- `resource_create`: a source by `name` (≤ 32 chars, letters, digits,
+  `_`, `-`; up to 32 sources). The `command` is stored and run as is.
+  `default: true` makes it the one shown first (and the one
+  `thinr device logs` uses without `--source`).
+- Structured rendering: add a `preset` (`resource_describe` type
+  `product_log_source` lists them:
+  journalctl, spdlog, nginx…) or your own `pattern`, a regex with named
+  groups `time`, `level` and `msg`. With a `level` group, operators can filter
+  by severity. `preset` and `pattern` are mutually exclusive.
+- `resource_update` with `{"default": true}` picks the default;
+  `resource_delete` drops a source (removing the last one deletes the
+  property, back to the fallback).

package/docs/guides/thinremote-playbooks.md

@@ -0,0 +1,133 @@
+# ThinRemote playbooks
+
+A playbook is a YAML document with ordered steps the agent executes on each
+device: write a file, run a command, install a script, restart a service…
+It is the safe way to change many machines: validated before it runs,
+testable on one device, rolled out in batches with a failure threshold, and
+recorded.
+
+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`).
+
+1. `resource_describe` type `product_playbook` once: its `playbook_format`
+   is the full schema (document, `vars`, step fields, every action with its
+   parameters, the `when` syntax). Write against it.
+2. Draft the YAML, then action `validate` with the YAML in `body.content`,
+   and fix what it reports. Repeat until it is clean.
+3. Save it: `resource_create` type `product_playbook`, body
+   `{"content": "<yaml>", "description"?: "…"}` (validated again: nothing is
+   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
+   `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.
+
+`resource_list` and `resource_get` show what a product has (`get` includes
+the YAML); `resource_delete` removes one (index entry, then file).
+
+## Document
+
+```yaml
+name: nginx-config
+description: Deploy nginx.conf and reload
+target:
+    product: web_gateways # or devices: [gw1, gw2]; group: madrid narrows
+    concurrency: 10 # parallel devices (action run)
+    fail_fast: false
+vars:
+    port:
+        default: 8080
+        type: number
+        description: Listening port
+    release:
+        type: string
+        required: true # must be given at run time
+steps:
+    - name: Write config to a temp file
+      action: write
+      path: /tmp/nginx.conf
+      content: |
+          server { listen {{ port }}; }
+    - name: Check it
+      action: exec
+      command: nginx -t -c /tmp/nginx.conf
+      register: check
+    - name: Move it into place
+      action: move
+      source: /tmp/nginx.conf
+      destination: /etc/nginx/nginx.conf
+      overwrite: true
+      when: check.ok
+    - name: Reload
+      action: exec
+      command: systemctl reload nginx
+```
+
+- `vars`: plain (`port: 8080`) or extended (`default`, `type` string |
+  number | boolean | object, `description`, `overridable: false` for
+  internal ones, `required: true`). Used in any parameter as `{{ name }}`.
+  Overrides passed at run time (`vars`) are validated against the declared
+  type; unknown, non-overridable or missing required ones are errors, and
+  they never change the stored playbook.
+- Step fields: `name`, `action`, the action's parameters, and optionally
+  `when` (skip unless true), `register` (expose `{ ok, result | error,
+duration_ms }` to later steps), `pause_after` (seconds).
+- `when` syntax: `==`, `!=`, `>`, `<`, `>=`, `<=`, `and`, `or`, `not`,
+  parentheses, quoted strings, numbers, `true` / `false` / `null`, dotted
+  paths (`check.ok`, `agent.version`).
+
+Actions:
+
+| Action                             | Required                | Optional                    | Does                                                       |
+| ---------------------------------- | ----------------------- | --------------------------- | ---------------------------------------------------------- |
+| `exec`                             | `command`               | `timeout`                   | runs a shell command; non-zero exit fails the step         |
+| `write`                            | `path`, `content`       |                             | writes inline content                                      |
+| `push` / `pull`                    | `source`, `destination` |                             | copies a file from / to the machine running the playbook   |
+| `mkdir`                            | `path`                  |                             | creates a directory                                        |
+| `move`                             | `source`, `destination` | `overwrite`                 | moves; write to a temp file then `move` for atomic deploys |
+| `delete`                           | `path`                  | `recursive`                 | deletes                                                    |
+| `property_set`                     | `property`, `value`     |                             | sets a device property                                     |
+| `resource`                         | `resource`              | `inputs`                    | calls a device resource                                    |
+| `script_install` / `script_delete` | `name`                  | `content` or `content_file` | installs or removes a device script                        |
+| `update`                           | `op`                    | `channel`                   | checks for or applies an agent update                      |
+| `sleep`                            | `seconds`               |                             | waits                                                      |
+
+Run from the MCP server, `push`, `pull` and `content_file` only reach files
+inside its local folder (`THINR_MCP_LOCAL_DIR`, or where it started).
+
+`check` cannot predict `exec` or `resource` steps: they report `unknown`.
+
+## 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
+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.
+
+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
+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.
+
+Writing the same file to every device is a playbook too: a `write` step
+(and a `move`), rolled out.
+
+Rollouts change real machines: confirm with the user, test on one device
+first, and start with small batches.

package/docs/guides/thinremote-scripts.md

@@ -0,0 +1,115 @@
+# ThinRemote scripts
+
+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.
+
+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.
+
+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 |
+
+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
+script for something specific to one machine.
+
+The resource name is the file name without extension: `scripts/backup.sh` is
+the resource `backup`. The extension is kept only for editor highlighting.
+
+Scripts run with the agent's privileges, root for a system install:
+installing one grants permanent remote execution of that code. Treat it like
+adding a service.
+
+## Product scripts
+
+Creating one (`resource_create` type `product_script`, body `{content, input?, output?}`)
+does everything needed: it creates the
+product's storage if missing, writes the `index.js` wrapper the first time,
+links it as the product's code, uploads the script and creates or updates
+the product API resource, so the script is callable at once. The product must
+exist (`resource_create` type `product`).
+
+How a call works: the product API resource targets the agent's `cmd`
+resource; the product code reads the script from the storage, sends it with
+the caller's input on stdin, and parses stdout as JSON (`parse_stdout`). A
+non-zero exit returns `{error, retcode}`; invalid JSON returns
+`{error: "invalid JSON in stdout", stdout}`.
+
+Contract:
+
+- Any executable source. With a shebang (`#!/usr/bin/env python3`,
+  `#!/bin/bash`…) it runs with that interpreter; without one it runs through
+  the shell (pipes, redirects and `&&` work).
+- The object the caller sends arrives on **stdin** as JSON: parse it with
+  `jq`, `json.load`, `JSON.parse`.
+- With `output` true (the default), **stdout must be valid JSON**: the
+  resource returns the decoded object.
+
+Choose the resource shape with `input` and `output`:
+
+| Shape            | `input`            | `output` | Example          | Console shows                         |
+| ---------------- | ------------------ | -------- | ---------------- | ------------------------------------- |
+| output only      | omit               | true     | stats, status    | the output                            |
+| input and output | `{field: default}` | true     | transform, query | an input form and the output          |
+| input only       | `{field: default}` | false    | notify, log      | an input form; the call replies empty |
+| run              | omit               | false    | ping, restart    | a button                              |
+
+`input` maps field names (`^[A-Za-z_][A-Za-z0-9_]*$`) to default values
+(string, number or boolean), e.g. `{"threshold": 80, "label": "warm"}`: the
+console renders typed fields and callers may override each one. Omit it for
+a free-form payload passed to stdin as is.
+
+Example, output only (`scripts/disk.sh`):
+
+```sh
+#!/bin/bash
+df -P / | awk 'NR==2 {printf "{\"used_pct\": %d, \"avail_kb\": %d}\n", $5, $4}'
+```
+
+Example, input and output (`scripts/ping.py`, `input: {"host": "8.8.8.8"}`):
+
+```python
+#!/usr/bin/env python3
+import json, subprocess, sys
+host = json.load(sys.stdin).get("host", "8.8.8.8")
+ok = subprocess.run(["ping", "-c", "1", "-W", "2", host], capture_output=True).returncode == 0
+print(json.dumps({"host": host, "reachable": ok}))
+```
+
+## Device scripts
+
+Creating one (`resource_create` type `device_script`, body `{content}`)
+writes the file in the agent's scripts folder, makes it executable and
+reloads the scripts extension (`$scripts/reload`), so the resource is
+callable at once. `resource_list` shows each script with the schema it
+describes; `resource_get` adds its source.
+
+Contract:
+
+- Executable with a shebang.
+- Called with `--describe`, it prints a JSON object with `input` and/or
+  `output` sample objects, e.g. `{"input": {"path": ""}, "output": {"size": 0}}`:
+  that becomes the resource's schema.
+- Called normally, the input object arrives on stdin as JSON; stdout is
+  parsed as JSON. An object's keys become the output fields; any other value
+  appears under `output`. A non-zero exit is an error.
+
+## Writing JSON safely
+
+Build JSON with a tool, never by pasting values into a string: a hostname or
+a log line with a quote or a backslash breaks it. Use `jq -n --arg v "$x"
+'{v: $v}'`, or Python's `json.dumps`. Output landing under `output` (device
+scripts) or an `invalid JSON` error (product scripts) means the JSON was
+malformed.

package/docs/guides/thinremote.md

@@ -0,0 +1,116 @@
+# ThinRemote: devices, agent and products
+
+ThinRemote manages fleets of machines (gateways, servers, edge boxes) on a
+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.
+
+Tool names below omit the `thinr_` prefix.
+
+## The device and its agent
+
+A ThinRemote device is a Generic (IOTMP) device whose firmware is the agent.
+The agent runs as an OS user (root for a system install), so what you can do
+on the machine is what that user can do. `resource_get` with type `device`
+adds what the agent reports when it is connected: `agent.system_info`
+(hostname, OS, architecture, user…), `agent.fs_base_path`, and `agent.where`,
+a map of where everything below is. Check them before assuming write access
+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)                                                |
+
+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
+confined to it.
+
+Built-in agent resources (`cmd`, `monitoring`, `system`, `update`, `agent`)
+keep those names: a device script with one of them would hide the real one,
+so creating it is refused unless forced.
+
+## Products: one configuration for a fleet
+
+A product groups the devices of a fleet and holds what they share. ThinRemote
+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:
+
+| 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` |
+
+Creating one that already exists fails (update it instead), and updating one
+that does not exist fails too, as with the server's types.
+
+Deleting a product with `resource_delete` also deletes its file storage (its
+scripts and playbooks).
+
+Devices join a product when they are created with `product`, with
+`resource_update` (`{"product": "<id>"}`), or by autoprovisioning (type
+`product_profile_autoprovision`).
+
+## 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                              |
+
+Offline devices are skipped unless asked (`include_offline`). Commands on
+several devices and rollouts act at once: confirm with the user first.
+
+## Recipes
+
+**Bring a new machine in.** `resource_create` type `product` (if the fleet
+has none) → `resource_call` type `device` action `agent_install` → run the
+command on the machine → the device appears (autoprovisioned or created) →
+`resource_update` its `product` if needed → `resource_get` to confirm
+`agent.system_info`.
+
+**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
+thinr's dashboard aggregates it across the fleet.
+
+**Change a config file on every machine, safely.** `resource_describe` type
+`product_playbook` (the format) → draft a playbook that writes the file and
+restarts the service → action `validate` → `resource_create` to save it →
+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 →
+`resource_get` type `device_fs` for log files, or the product's log sources
+with `thinr device logs`.

package/lib/command-stream.js

@@ -2,7 +2,8 @@
 import WebSocket from 'ws';
 import { randomUUID } from 'crypto';
 import { TIMEOUTS } from './constants.js';
-import { device } from './paths.js';
+import { serverWebSocketURL } from '@thinger-io/cli-core/config';
+import { device } from '@thinger-io/cli-core/paths';
 
 /**
  * One-shot execution of a shell command on a device over the IOTMP
@@ -80,7 +81,7 @@ export class CommandStream {
         const { server, apiUser, deviceId, cmd, timeout } = this.opts;
         const params = new URLSearchParams({ cmd });
         if (timeout && timeout > 0) params.set('timeout', String(timeout));
-        return `wss://${server}${device(apiUser, deviceId)}/resources/${this.resource}?${params}`;
+        return `${serverWebSocketURL(server)}${device(apiUser, deviceId)}/resources/${this.resource}?${params}`;
     }
 
     _openSocket() {

package/lib/console.js

@@ -1,9 +1,9 @@
 import WebSocket from 'ws';
-import { requireConfig } from './config.js';
-import { ensureFreshToken } from './auth.js';
-import api from './api.js';
-import { warning, error as errorStyle } from './format.js';
-import { device } from './paths.js';
+import { requireConfig, serverWebSocketURL } from '@thinger-io/cli-core/config';
+import { ensureFreshToken } from '@thinger-io/cli-core/auth';
+import api from '@thinger-io/cli-core/api';
+import { warning, error as errorStyle } from '@thinger-io/cli-core/format';
+import { device } from '@thinger-io/cli-core/paths';
 
 /**
  * Creates a WebSocket connection to a device terminal. Returns a
@@ -27,7 +27,7 @@ export async function connectToDeviceConsole(deviceId, user) {
     const token = (await ensureFreshToken()) || config.token;
 
     const sessionId = createUUID();
-    const wsUrl = `wss://${config.server}${device(user, deviceId)}/resources/$terminal/${sessionId}?raw=1`;
+    const wsUrl = `${serverWebSocketURL(config.server)}${device(user, deviceId)}/resources/$terminal/${sessionId}?raw=1`;
     const ws = new WebSocket(wsUrl, {
         headers: { Authorization: `Bearer ${token}` },
     });

package/lib/constants.js

@@ -4,21 +4,11 @@
  * Central home for the numeric knobs the CLI scatters otherwise.
  * Keep every "magic number" that has meaning beyond its immediate call
  * site here so we can tune them in one place (and grep for them when
- * debugging a stuck transfer or a missed OAuth poll).
+ * debugging a stuck transfer).
  */
 
 /** Timeouts. All values in ms unless the constant name ends in `_SECONDS`. */
 export const TIMEOUTS = {
-    /** Default axios request timeout for control-plane HTTP calls. */
-    API_DEFAULT_MS: 10_000,
-
-    /**
-     * Refresh a JWT access token this close to (or past) its `exp`
-     * before opening a WebSocket. WS handshakes lack the
-     * refresh-on-401 retry that api.js gives HTTP requests.
-     */
-    TOKEN_EXPIRY_SLACK_MS: 30_000,
-
     /** POSTs to device resources (cmd, update, etc.) — mid-weight calls. */
     DEVICE_RESOURCE_CALL_MS: 30_000,
 
@@ -43,9 +33,6 @@ export const TIMEOUTS = {
      */
     EXEC_EXTRA_GRACE_MS: 5_000,
 
-    /** Hard ceiling for the OAuth device-code flow — 10 minutes. */
-    OAUTH_DEVICE_CODE_MS: 10 * 60 * 1000,
-
     /**
      * Default command timeout (in *seconds*) for user-facing exec
      * flows: CLI `device exec`, `product exec`, playbook `exec`, MCP
@@ -76,8 +63,3 @@ export const PROXY_PORTS = {
     MIN: 50_000,
     MAX: 51_000,
 };
-
-/** OAuth device-flow client identity registered for this CLI. */
-export const OAUTH = {
-    CLIENT_ID: '3b40164d28730e416cbd',
-};

package/lib/dashboard/event-stream.js

@@ -1,9 +1,9 @@
 // @ts-check
 import WebSocket from 'ws';
-import { readConfig } from '../config.js';
-import { refreshToken } from '../auth.js';
+import { readConfig, serverWebSocketURL } from '@thinger-io/cli-core/config';
+import { refreshToken } from '@thinger-io/cli-core/auth';
 import { debugCount, debugLog } from '../debug-log.js';
-import { v2 } from '../paths.js';
+import { v2 } from '@thinger-io/cli-core/paths';
 
 // Single shared websocket to /v2/users/{user}/events. Both fleet
 // monitoring and product metrics live on the same endpoint with the
@@ -109,9 +109,9 @@ class EventStream {
         if (this.disposed) return;
         const config = readConfig();
         if (!config?.server || !config?.token || !config?.username) return;
-        const url = `wss://${config.server}${v2(config.username)}/events?authorization=${config.token}`;
+        const url = `${serverWebSocketURL(config.server)}${v2(config.username)}/events?authorization=${config.token}`;
         debugLog('ws:events', 'connecting', {
-            endpoint: `wss://${config.server}${v2(config.username)}/events`,
+            endpoint: `${serverWebSocketURL(config.server)}${v2(config.username)}/events`,
             pending_subs: this.subs.size,
         });
         const ws = new WebSocket(url);

package/lib/device-api.js

@@ -1,10 +1,10 @@
-import api from './api.js';
-import { requireConfig, resolveUser } from './config.js';
+import api from '@thinger-io/cli-core/api';
+import { requireConfig, resolveUser } from '@thinger-io/cli-core/config';
 import { BYTES, TIMEOUTS } from './constants.js';
 import { CommandStream } from './command-stream.js';
-import { ensureFreshToken, refreshToken } from './auth.js';
+import { ensureFreshToken, refreshToken } from '@thinger-io/cli-core/auth';
 import { Readable } from 'node:stream';
-import { device } from './paths.js';
+import { device } from '@thinger-io/cli-core/paths';
 
 // Directory endpoints on the agent expect a trailing slash so it can
 // distinguish "list this directory" from "read a file with this name".

package/lib/guides.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+/**
+ * The guides thinr ships for agents (served by `thinr_doc_read` 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
+ * descriptions stay short and point here for the how-to.
+ */
+const guide = (name) => new URL(`../docs/guides/${name}.md`, import.meta.url);
+
+export const guides = [
+    {
+        id: 'thinremote',
+        title: 'ThinRemote: devices, agent and products',
+        description:
+            'Start here: what the agent exposes and the tool for each need, what a ThinRemote product holds, fleet operations and recipes.',
+        file: guide('thinremote'),
+    },
+    {
+        id: 'thinremote-scripts',
+        title: 'ThinRemote scripts',
+        description:
+            'Device and product scripts: when to use each, the stdin/stdout JSON contract, resource shapes and examples.',
+        file: guide('thinremote-scripts'),
+    },
+    {
+        id: 'thinremote-playbooks',
+        title: 'ThinRemote playbooks',
+        description:
+            'Write, validate, test on one device and roll out playbooks: document format, variables, actions, batches and reports.',
+        file: guide('thinremote-playbooks'),
+    },
+    {
+        id: 'thinremote-metrics-logs',
+        title: 'ThinRemote fleet metrics and log sources',
+        description:
+            "Per-product metrics and log sources read by thinr's terminal dashboard and `thinr device logs` (not the web console's dashboards): fields, aggregations, presets.",
+        file: guide('thinremote-metrics-logs'),
+    },
+];