@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/commands/retrieve/README.md

@@ -262,13 +262,19 @@ target only: a fan-out selector fails `usage/fanout-not-supported`. Follow is
 filtered with the same `--query`/`--filter` grammar as a one-shot read (#397).
 
 **What each line means.** Every line is one envelope; read
-`meta.operation.stream`:
+`meta.operation.stream`. Only `started`, `synced` and `summary` carry the full
+`meta` (target, settings, validation, request, auth). A `frame` line carries
+only `meta.operation` (`kind`, `objectCount`, `stream`), because the rest is
+the same on every line. An error line is a full error envelope: the one line
+of a follow that fails before it starts (resolution, validation, a
+non-followable menu, a non-native transport), and a failed `summary`
+([constitution](../../docs/CONSTITUTION.md#result-envelope)).
 
 | `kind` | When | `data` | Fields |
 | ------ | ---- | ------ | ------ |
-| `frame` | One row change | the row (`upsert`), `null` (`removed`) | `index`, `phase` (`snapshot`/`live`), `change` (`upsert`/`removed`), `id`, `source` (`print`/`listen`/`sweep`/`membership`) |
+| `frame` | One row change | the row (`upsert`), `null` (`removed`) | `index`, `observedAt`, `phase` (`snapshot`/`live`), `change` (`upsert`/`removed`), `id`, `source` (`print`/`listen`/`sweep`/`membership`) |
+| `started` | First, once validation passed | `null` | — (`tips` carries any advice) |
 | `synced` | Once, after the snapshot | `null` | `rows`: rows held at that point |
-| `notice` | First, only when there is advice | `null` | — (`tips` carries it) |
 | `summary` | Last, exactly once | the counts | `stopReason`, `frames`, `snapshot`, `changes`, `sweeps`, `synced`, `durationMs` |
 
 - **Bootstrap (A1).** centrs starts the `listen`, then the `print`, on one
@@ -279,6 +285,11 @@ filtered with the same `--query`/`--filter` grammar as a one-shot read (#397).
   order resurrects deleted rows (#396 round 3). `synced` means the bootstrap
   was processed. It is not an atomic snapshot, a full event history, or
   routing convergence.
+- **`observedAt`** (ISO 8601, host clock) is when centrs received the reply
+  the frame is built from: the `listen` change, the snapshot row, the
+  membership read or the sweep. A bootstrap change replayed after the
+  snapshot keeps its arrival time, so `observedAt` is not ordered by `index`.
+  A slow reader does not move it.
 - **`upsert`** carries the latest full row; replace what you hold for `id`.
   **`removed`** carries `data: null`; drop `id`. The row identity is always
   `meta.operation.stream.id`, even when `--attributes` leaves `.id` out of
@@ -297,8 +308,8 @@ filtered with the same `--query`/`--filter` grammar as a one-shot read (#397).
   sweep only checks membership: it does not repair a missed field update or
   report rows `listen` never announced. `--sweep` needs a unit (`10s`,
   `500ms`); a bare number fails `settings/invalid-timeout`, as for `--sample`.
-  `--sweep 0` turns it off, with a notice tip saying view-menu removals will
-  not be reported.
+  `--sweep 0` turns it off, with a tip on `started` saying view-menu removals
+  will not be reported.
 - **What `listen` never reports.** Hot counters (`rx-byte`, firewall
   `bytes`/`packets`) and some protocol state (BFD sessions accept `listen` but
   stay silent). The follow is correct but quiet there; `--sample` (below)
@@ -320,7 +331,8 @@ filtered with the same `--query`/`--filter` grammar as a one-shot read (#397).
   indefinitely or postpone the first sweep and live `--count`. This may
   coalesce more changes than unfiltered A1 replay.
   The filtered sweep also detects silent exits from a predicate (e.g. a
-  decreasing address-list `timeout`). It does not discover silent entries or
+  decreasing address-list `timeout`), reported as `removed` with
+  `source: "sweep"`. It does not discover silent entries or
   repair silent field updates: use `--sample` for such state. With `--sweep 0`,
   silent exits remain held until a listen notification arrives.
 - **Projection.** `--attribute(s)` projects `data`; centrs still asks RouterOS
@@ -346,9 +358,11 @@ new snapshot. `--sweep` without `--follow`, and `--count` or `--duration`
 without `--follow` or `--sample`, fail `usage/conflicting-flags`.
 
 **Format.** Under `--follow`, `json`, `yaml` and `ndjson` all print one compact
-envelope per line (as `api --stream` does); `text` prints one short row per
-line. Every envelope, errors included, goes to stdout, and the exit code is
-nonzero for any failure, even after rows. Without `--follow`,
+envelope per line (as `api --stream` does), errors included, on stdout.
+`text` prints one short row per `frame` on stdout; the `started` tips, the
+`synced` and summary lines, warnings and errors go to stderr, since text
+stdout is data ([constitution](../../docs/CONSTITUTION.md#result-envelope)).
+The exit code is nonzero for any failure, even after rows. Without `--follow`,
 `--format ndjson` prints the ordinary envelope as one compact line; it never
 starts a follow.
 
@@ -387,10 +401,13 @@ stays available as `api <router> <menu>/print -X POST -f interval=1s --stream`
 (`commands/api/README.md`).
 
 **What each line means.** Every line is one envelope; read
-`meta.operation.stream`:
+`meta.operation.stream`. `started` and `summary` carry the full `meta`; a
+`sample` line carries only `meta.operation` (`kind`, `objectCount`, `stream`),
+as a follow `frame` does:
 
 | `kind` | When | `data` | Fields |
 | ------ | ---- | ------ | ------ |
+| `started` | First, once validation passed | `null` | — |
 | `sample` | One complete read | the whole read: a row array (list), the record (singleton), or the bare value (one `--attribute` on a singleton) | `index` (1-based), `at` (when the read was sent, host clock, ISO 8601), `readMs` |
 | `summary` | Last, exactly once | the counts | `stopReason`, `samples`, `durationMs` |
 
@@ -415,9 +432,9 @@ carrying the partial `samples` count; there is no retry. `--list-attributes`, `-
 `--sweep` conflict with `--sample` (`usage/conflicting-flags`).
 
 **Format.** As for `--follow`: `json`, `yaml` and `ndjson` print one compact
-envelope per line, and `text` prints `index`, `at` and the data on one line.
-Every envelope, errors included, goes to stdout; the exit code is nonzero for
-any failure, even after samples.
+envelope per line, errors included, on stdout. `text` prints `index`, `at` and
+the data on one stdout line per sample, and the summary, warnings and errors
+on stderr. The exit code is nonzero for any failure, even after samples.
 
 Recipes (bounded, so an agent can run them unattended):
 
@@ -513,7 +530,8 @@ retrieve-specific behavior on top of the shared engine:
   `transport/connection-closed` (REST 5xx is mapped to
   `transport/connection-closed`). It does **not** retry `routeros/*`,
   `validation/*`, `auth/*`, `cdb/*`, `target/*`, timeouts, DNS, TLS, or refused
-  connections.
+  connections. (`execute` and `api` share this engine but never replay a write
+  that was sent.)
 
 ## Definition of done
 

package/commands/retrieve/examples.md

@@ -434,7 +434,9 @@ centrs retrieve $A /ip/address --follow --duration 3s --port $API_PORT --usernam
 Every line parses as an envelope. Frames before `synced` have
 `phase: "snapshot"` and `source: "print"`; exactly one `synced`; the last line
 is the summary with `stopReason: "duration-elapsed"`, `synced: true`,
-`changes: 0`. Every frame carries `meta.operation.stream.id`.
+`changes: 0`. Every frame carries `meta.operation.stream.id` and an ISO 8601
+`observedAt`, and no other meta; `synced` and the summary carry the full
+`meta` (`target`, `via`, `settings`, …).
 
 ### FL2. A live change, and `--count` that ignores the snapshot
 
@@ -454,7 +456,8 @@ centrs retrieve $A /ip/address --follow --sweep 0 --count 1 --duration 15s --por
 
 After `synced`, remove an address that existed before the follow. One `live`
 `removed` frame, `source: "listen"`, `data: null`. `--sweep 0` keeps the sweep
-out of the race, and its `tip/follow-sweep-off` notice is the first line.
+out of the race, and its `tip/follow-sweep-off` tip rides the first line,
+`started`.
 
 ### FL4. A removal RouterOS does not send (view menu → sweep)
 
@@ -529,9 +532,10 @@ centrs retrieve $R /ip/address --sample 1s --count 3 --username $U --password $P
 centrs retrieve $A /ip/address --via native-api --sample 1s --count 3 --port $API_PORT --username $U --password $P --json
 ```
 
-Each run prints three `sample` lines (`index` 1–3, `data` a row array) and a
-summary with `stopReason: "count-reached"`, `samples: 3`. Consecutive `at`
-values are at least one second apart. `meta.via` is the transport used.
+Each run prints `started`, three `sample` lines (`index` 1–3, `data` a row
+array) and a summary with `stopReason: "count-reached"`, `samples: 3`.
+Consecutive `at` values are at least one second apart. The `started` line's
+`meta.via` is the transport used.
 
 ### SA2. Counters `listen` never reports
 
@@ -687,7 +691,7 @@ centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT -
 
 The harness adds a row with a 10-second timeout. A sweep removes it from the
 selected set as its remaining timeout crosses 8 seconds, with
-`source: "membership"`; the row still exists in an unfiltered read.
+`source: "sweep"`; the row still exists in an unfiltered read.
 
 ### FQ4. CLI alias and predicate validation
 

package/commands/transfer/examples.md

@@ -463,6 +463,15 @@ centrs transfer --group no-such-group list --via rest --cdb-file $CDB --json
 `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
 `warnings` include `cdb/empty-group`. Exit `0`.
 
+A write verb (`upload`, `remove`, `mkdir`, `copy`) over the same group is an
+outer error, with or without `--yes` (#460):
+
+```bash
+centrs transfer --group no-such-group remove fanout-test.txt --via rest --cdb-file $CDB --yes --json
+```
+
+`ok: false`, `error.code` `cdb/empty-group`. Exit `1`.
+
 ### F3. `--where` device-class selector (subset)
 
 ```bash

package/docs/CLI.md

@@ -51,8 +51,8 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 | `--all-attributes` |  | Request the RouterOS detail/all-attributes shape. |
 | `--list-attributes / --list` |  | List inspect-derived attributes without running the data call. |
 | `--query / --filter` | `<expr>` | Row filter written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`), run on the router as an API query; repeatable, AND-ed. No `~` or `in`. |
-| `--follow` |  | Keep the menu's rows current over native-api `listen`: snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only. |
-| `--sample` | `<interval>` | Read the menu again every interval (with a unit, e.g. `5s`): one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api. |
+| `--follow` |  | Keep the menu's rows current over native-api `listen`: a `started` line, snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only. |
+| `--sample` | `<interval>` | Read the menu again every interval (with a unit, e.g. `5s`): a `started` line, one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api. |
 | `--wait` | `<deadline>` | Wait for a successful read or a condition until this overall deadline, with a unit (e.g. `2m`). Retries refused, closed, reset and timed-out connections and a down or unreachable host; other errors fail at once. One final envelope; single target. |
 | `--until` | `<expr>` | With --wait: succeed when any selected row matches this --query grammar predicate; repeatable, AND-ed. Returns the matching rows. Already true succeeds on the initial read. |
 | `--until-empty` |  | With --wait: succeed on a completed read with zero rows selected by --query. Silence and failed reads never satisfy it. |
@@ -66,7 +66,7 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
 | `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
 | `--validate / --no-validate` |  | Enable or disable inspect-backed preflight validation. |
-| `--verbose` |  | Show resolved setting sources in text output. |
+| `--verbose` |  | Show resolved setting sources in text output, on stderr. |
 
 ## execute
 
@@ -87,6 +87,8 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--default` |  | Select the reserved `__default__` record. |
 | `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
 | `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--cmr` |  | Run on CMR clients through their controller: the `<target>` is the controller (RouterOS 7.26beta1+, `cmr` package). Needs `--labels`; native-api or rest-api only. |
+| `--labels` | `<expr>` | With `--cmr`: RouterOS label expression selecting clients (comma list; plain = OR, `+` AND, `-` AND NOT, `all`). |
 | `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<target>` it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
@@ -102,8 +104,8 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--max-results` | `<bytes>` | Fail if the rendered envelope exceeds this byte budget. |
 | `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
 | `--json` |  | Shortcut for `--format json`. |
-| `--verbose` |  | Include additional context in text output. |
-| `--` |  | End centrs option parsing: every following token is the literal RouterOS command, even flag-shaped ones (e.g. `-- /interface print where disabled=yes`). |
+| `--verbose` |  | Include additional context in text output, on stderr. |
+| `--` |  | End centrs option parsing: every following token is the literal RouterOS command (e.g. `-- /interface print where disabled=yes`). Put centrs flags before it; one of execute's own long flags after it is refused as `usage/flag-after-separator`. |
 
 ## api
 
@@ -124,7 +126,7 @@ Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <en
 | `--attribute / --proplist` | `<a,b>` | Property projection → `.proplist`. |
 | `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`. |
 | `--yes` |  | Confirm a mutating (non-read) request in non-interactive runs. |
-| `--stream` |  | Stream the command's native replies (`!re` rows and `!empty`) as NDJSON, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it. |
+| `--stream` |  | Stream the command's native replies (`!re` rows and `!empty`) as NDJSON: a `started` line, a line per reply, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it. |
 | `--count` | `<n>` | Stop a `--stream` after N `!re` rows; `!empty` replies do not count (not the device count= argument). |
 | `--duration` | `<dur>` | Stop a `--stream` after this wall-clock window (e.g. `5s`). |
 | `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
@@ -148,7 +150,7 @@ Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <en
 | `--validate / --no-validate` |  | Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted). |
 | `--format` | &lt;json\|ndjson\|yaml\|text&gt; | Output format. Defaults to json for api; `CENTRS_FORMAT` overrides. |
 | `--json` |  | Shortcut for `--format json`. |
-| `--verbose` |  | Include additional context in text output. |
+| `--verbose` |  | Include additional context in text output, on stderr. |
 
 ## transfer
 
@@ -188,7 +190,7 @@ Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
 | `--validate / --no-validate` |  | Enable or disable the existence-probe preflight. |
-| `--verbose` |  | Show the resolved transport in text output. |
+| `--verbose` |  | Show the resolved transport in text output, on stderr. |
 
 ## terminal
 

package/docs/CONSTITUTION.md

@@ -177,8 +177,29 @@ Notes:
   lossless rule applies to **stdout** only: **stderr** carries progress and
   interactive prompts (discover scan progress, write/ambiguity confirmation) and
   is exempt — use it sparingly, since most operations are fast.
+- **Text stdout is data** (#470). In text mode a single-target `execute`,
+  `api`, `retrieve` or `transfer` writes only `data` (or its error) to stdout.
+  The notes around it go to stderr: the `--verbose` header first, then one
+  `warning [<code>]: <message>` line per warning, then the `Tips:` footer, on
+  success and on failure alike. `transport/provider-trust` is left out of text
+  because it rides every quickchr run over TLS or SSH. `--json` keeps
+  everything, `api --raw` stays a bare payload, and fan-out text is a report,
+  not data, so it keeps its warnings on stdout. A text stream writes only its
+  data rows (`frame`, `sample`) to stdout; its `started`, `synced` and
+  `summary` lines, tips, warnings and errors go to stderr (#473).
 - `data` is the only field whose *shape* varies by command. Everything else —
   including `warnings` and `tips` — is invariant in shape; only contents differ.
+- **Shared meta is written once** (#461, #462). A fan-out target's
+  `meta.settings` keeps only the keys whose source differs from the outer
+  `meta.settings`, and its `meta.operation` drops `request` and `auth` when
+  they equal the outer operation's. When every target agrees on `auth`, or
+  on a setting the outer `meta.settings` lacks, it moves to the outer
+  envelope. A reader takes the target's value, else
+  the outer one (`expandFanoutTarget`). A stream (`retrieve --follow`,
+  `retrieve --sample`, `api --stream`) opens with a `started` line that
+  carries the full meta and any request advice in `tips`, and ends with a
+  full-meta `summary` (`--follow`'s `synced` is full too). The data lines
+  between (`frame`, `sample`) carry only `meta.operation` (#473).
 
 ## Error model
 
@@ -304,12 +325,16 @@ Fan-out output is the locked **`FanoutData`** envelope: `data = { summary, targe
 is an inner `ok:false` envelope (output, not metadata). `targets[]` is reassembled
 in resolved record order, not completion order, so repeated runs diff cleanly. The
 **process exit code** is granular and uniform across fan-out commands: `0` every
-target ok (or an empty selection), `2` partial (some ok, some failed), `1`
-orchestration error or every target failed.
+target ok (or an empty selection for a read), `2` partial (some ok, some
+failed), `1` orchestration error or every target failed. An empty selection is
+a warning for a read and an orchestration error for a write, `--yes` or not,
+so a mistyped selector never passes for a successful bulk write (#460).
 
 A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across a
 selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing
-the error names the blast radius (how many routers). The separate **`--force`**
+the error names the blast radius (how many routers). A write that was **sent** is
+never retried, because it may already have run; it fails with the warning
+`transport/write-outcome-unknown` instead (#448). The separate **`--force`**
 gate is scoped to destructive **`devices` CDB mutations** (e.g. `devices remove`
 across a group), not RouterOS writes. `terminal`, `api --stream`,
 `retrieve --follow` and `retrieve --sample` are single-session, not fan-out
@@ -365,6 +390,32 @@ single host/port: that shape is the contract quickchr's descriptor and TikTOML's
 exists to prevent. A `--via` whose service key a provider does not supply is a
 typed unsupported-provider error, never a silent fallback.
 
+#### Controller-mediated selection (CMR)
+
+A **CMR controller** (RouterOS 7.26beta1+) is a third kind of source: a live
+inventory whose members centrs never dials. `execute <controller> --cmr
+--labels <expr>` (#450) resolves the **controller** as an ordinary single
+target, and only its credentials are used. RouterOS's label expression selects
+the members, and the command runs on each through the controller's
+`run-script`. Normative:
+
+- CMR is a selection source, **not a protocol**. `--via` pins the controller
+  transport, and a CMR failure never falls back to dialing a client.
+- A member is bound by the controller's row id, never by its display name. A
+  result that cannot be bound to the member it was validated on is not run, or
+  is reported as an unknown outcome.
+- Validation runs **on each client** (`:parse` through CMR) and must be complete
+  before it counts. A client that fails validation is never sent the command,
+  and an incomplete selection runs nothing.
+- A CMR dispatch is **never retried**. A timeout, cancellation or lost call
+  after sending is `cmr/outcome-unknown`, because the client script may still
+  be running.
+- CMR mode is not on MCP until delegated authorization is designed (#449).
+  Registering a controller must not authorize its clients.
+
+The contract and its device evidence are in
+[`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr).
+
 ### MCP surface: the CDB is the allowlist
 
 The MCP frontend (`commands/mcp/`) is an adapter over this core, not a new set of

package/docs/MATRIX.md

@@ -56,6 +56,11 @@ and implementation sequencing in the linked issues.
 - `retrieve`, `api`, `execute`, and `transfer` share the target-selection and
   fan-out contracts from `docs/CONSTITUTION.md`; command-specific boundaries and
   evidence are in their command READMEs and integration tests.
+- `execute --cmr` (#450) is not a grid column: CMR is a selection source, and
+  its controller transports are the `execute` rest-api/native-api cells.
+  CMR1–CMR7 and CMR10–CMR14 pass on a 7.26beta1 CHR lab over both, and
+  CMR8–CMR9 over native-api (`test/integration/execute-cmr.test.ts`). CMR0 (a
+  router without CMR) runs on the channel's CHR in `execute.test.ts`.
 - There is no `update` command. RouterOS CLI-shaped writes ride `execute`; the
   structured operation surface is `api`.
 - `api --stream` absorbs the former `stream`/`tail` surface; native-api stream
@@ -177,15 +182,27 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**First: the native-api / NDJSON line** (maintainer decision on
+**First: the CMR track** (maintainer decision 2026-10-12 on
+[#441](https://github.com/tikoci/centrs/issues/441)). Done: `execute --cmr`
+(#450), which runs one validated command on CMR clients through their
+controller. The contract is in
+[`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr),
+with examples CMR0–CMR15. Also done: the fleet blast-radius gate for
+controller fleet commands run with plain `execute` or `api` (#453), with
+examples CMR16–CMR18 and api CMR1. The feature map of CMR against centrs is
+on #441 (2026-10-13). Next is the read-only slice of #449 (a `devices` view
+of members and a default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
+Live `explain` resumes after this.
+
+**The native-api / NDJSON line** (maintainer decision on
 [#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
 field poll with `sleep` where a native follow would answer. In order:
 (1) done: #402, literal `api --stream` with `!empty` frames and
 `--format ndjson`; (2) done: `retrieve --follow` (#396, unfiltered);
 (3) done: `retrieve --sample`; (4) #397: one-shot `retrieve --query` done,
 filtered `--follow` done; #364 (`--wait`/`--until`, same grammar) done;
-(5) #398 and #401. Each slice's contract lives in its command
-README. Live `explain` (below) resumes after this line.
+(5) #398 and #401 remain open. Each slice's contract lives in its command
+README.
 
 **Tightening validation as a whole** is the next track, in the three-step
 order agreed on [#236](https://github.com/tikoci/centrs/issues/236):

package/docs/errors/cdb/empty-group.md

@@ -2,8 +2,24 @@
 
 The named CDB group contains no records.
 
+## Typical trigger
+
+A fan-out selected only by `--group` (no other selector) whose group matched
+no record: a misspelled or case-mismatched group name, or a group whose last
+member was removed.
+
+- For a **read**, it is a warning on an `ok: true` fan-out envelope with
+  `summary { total: 0, ok: 0, failed: 0 }` and exit code 0.
+- For a **write-shaped** fan-out (`execute` write, a mutating `api` method,
+  `transfer upload|remove|mkdir|copy`) it is an outer error (`ok: false`, exit
+  code 1), with or without `--yes`. `context.write` is `true`.
+
+Any other empty selection (`--where`, `--all`, positionals, mixed) is
+[`cdb/empty-selection`](empty-selection.md).
+
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `cdb/empty-group`.
+Run `centrs devices groups` to see the groups that exist and their member
+counts, then re-run with the right name. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Target selection) for the
+selector grammar.

package/docs/errors/cdb/empty-selection.md

@@ -5,9 +5,15 @@ The target selection matched no CDB records.
 ## Fix
 
 A fan-out selection involving `--where` / `--all` / `--default` / positionals (on
-its own or mixed with `--group`) resolved to zero targets. This is reported as a
-warning on an `ok: true` fan-out envelope with `summary { total: 0, ok: 0, failed:
-0 }`, not a hard failure — there was simply nothing to run.
+its own or mixed with `--group`) resolved to zero targets.
+
+- For a **read**, it is a warning on an `ok: true` fan-out envelope with
+  `summary { total: 0, ok: 0, failed: 0 }` and exit code 0: there was simply
+  nothing to read.
+- For a **write-shaped** fan-out (`execute` write, a mutating `api` method,
+  `transfer upload|remove|mkdir|copy`) it is an outer error (`ok: false`, exit
+  code 1), with or without `--yes`, so a mistyped selector does not look like
+  a successful bulk write. `context.write` is `true`.
 
 A **group-only** empty (bare `--group`, no other selector) is reported as
 [`cdb/empty-group`](empty-group.md) instead, naming the group that matched nothing;

package/docs/errors/cmr/caller-policy-not-enforced.md

@@ -0,0 +1,46 @@
+# `cmr/caller-policy-not-enforced`
+
+A warning on `execute --cmr`, and on `/cmr/device/run-script` or
+`/cmr/device/reboot` run directly with `execute` or `api`: the controller login
+lacks a policy that the command runs with on the clients, and RouterOS does
+not check it. The login does not limit what a CMR command can change.
+
+## Typical trigger
+
+A write through `--cmr` with a controller login whose group lacks `write`,
+`test` or `reboot`, such as a "reader" account given to an agent. CMR runs
+every `run-script` script on each selected client with `read`, `write`,
+`test` and `reboot`, the controller's own row included. On 7.26beta1,
+RouterOS checked only that the caller had `read` and `api`. These results
+come from the CHR reproduction on #456 (REST, two-CHR lab, 2026-10-13); the
+same `run-script` write was seen on real hardware, and the integration test
+re-proves it (CMR15 in `commands/execute/examples.md`):
+
+| Controller login | Direct write or reboot | Through CMR |
+| --- | --- | --- |
+| `read,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to a client and rebooted it |
+| `read,test,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to the controller's own row; `/cmr/device/reboot` rebooted a client |
+
+MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) this is fixed for 7.26beta2: a `read` group will not
+be allowed to do it. That has not been checked on a beta2 build yet. centrs
+still warns on any version, because the warning reads the login's policy, not
+the RouterOS version. On a build that refuses the write, the members fail
+instead and the warning only says what the login lacks.
+
+`context` names the login (`username`, `group`), the policies it lacks
+(`missing`) and the ones the command runs with (`runsWith`): `read`, `write`,
+`test` and `reboot` for `run-script`, and `reboot` for `/cmr/device/reboot`.
+centrs reads the policy once per run, from the login's own `/user` row and
+`/user/group`, and only for a write. When that read fails (for example a
+RADIUS login with no `/user` row) there is no warning. Other fleet commands
+(`/cmr/device/upgrade`, `pair`, the rule menus) were not measured, so they
+carry no such warning.
+
+## Fix
+
+Nothing failed; this is information. Do not treat a controller login as
+read-only once the `cmr` package is installed (on 7.26beta1 at least). The
+gates that hold are centrs' own: pass `--yes` only when you intend the write
+on every selected client, and over MCP keep the controller's record at
+`mcp=ro` (the default), which refuses CMR fleet commands outright. Give an
+agent a login on the controller only if it may change every paired device.

package/docs/errors/cmr/cancelled.md

@@ -0,0 +1,15 @@
+# `cmr/cancelled`
+
+The operation was cancelled before the command was sent to this CMR client, so
+nothing ran on it.
+
+## Typical trigger
+
+The caller aborted (Ctrl-C, or an `AbortSignal` in the library) during
+preflight or before this member's dispatch. Members that had already been sent
+the command are reported as [`cmr/outcome-unknown`](./outcome-unknown.md)
+instead, because cancelling does not stop a client script that has started.
+
+## Fix
+
+Re-run when ready.

package/docs/errors/cmr/client-disconnected.md

@@ -0,0 +1,19 @@
+# `cmr/client-disconnected`
+
+CMR skipped the client because it is not connected to the controller. The
+command was **not** sent to it.
+
+## Typical trigger
+
+The controller answered `run-script` for this client with status `skipped` and
+output `disconnected`. The client is down, unpaired, or cannot reach the
+controller on TCP/54321. A client that has just gone down may instead stall
+until the controller notices; that case surfaces as
+[`cmr/validation-incomplete`](./validation-incomplete.md) or
+[`cmr/outcome-unknown`](./outcome-unknown.md).
+
+## Fix
+
+- On the client, `/cmr/client print` should show `status: paired,connected`.
+- Check its route and firewall towards the controller (TCP/54321).
+- Re-run once it reconnects; the other members' results are unaffected.

package/docs/errors/cmr/client-script-not-validated.md

@@ -0,0 +1,22 @@
+# `cmr/client-script-not-validated`
+
+A warning: a caller-addressed `/cmr/device/run-script`, sent through `api` or
+plain `execute`, passed validation **as a controller request**. The `script=`
+it carries was not validated on any CMR client.
+
+## Typical trigger
+
+```sh
+centrs api ctl /cmr/device/run-script -X POST -f labels=all -f 'script=…' --yes
+centrs execute ctl --yes -- '/cmr/device/run-script labels=all script="…"'
+```
+
+`/console/inspect` on the controller checks `labels=` and `script=` as
+arguments. To the controller's `:parse`, the script is an opaque string, so a
+`passed` gate says nothing about whether each client accepts it.
+
+## Fix
+
+Use `centrs execute <controller> --cmr --labels <expr> -- '<command>'`. It runs
+`:parse` on every selected client through CMR and sends the command only to the
+clients that accepted it.

package/docs/errors/cmr/console-only.md

@@ -0,0 +1,29 @@
+# `cmr/console-only`
+
+The command is one of CMR's interactive console views, so centrs refused it
+before running it.
+
+## Typical trigger
+
+`/cmr/device/dashboard` through `execute` or `api`. On RouterOS 7.26beta1:
+
+- over the **native API** it closed the API session;
+- over **REST** it never returned, and every other REST request to the
+  controller then waited 10–30 s until it timed out.
+
+A plain path, abbreviated or not (`/cmr/dev/dash`), is refused before any
+connection opens. Every other spelling is found in the controller's `:parse`
+return during validation, which resolves it to one invocation: console
+spacing, a relative menu change (`/cmr/device; dashboard`), a `:do`/`:if`
+block, a `[...]` substitution, or an `api POST /execute` script. Strings and
+comments that only spell the words are not refused.
+
+With `--validate=false` there is no `:parse` return, so only the plain path is
+refused.
+
+## Fix
+
+- Open the dashboard in WinBox 4 or WebFig, or run it in
+  `centrs terminal <controller>`.
+- For the data behind it, read the menus directly: `centrs retrieve
+  <controller> /cmr/device`, `/cmr/alert` or `/cmr/upgrade/job`.

package/docs/errors/cmr/empty-selection.md

@@ -0,0 +1,33 @@
+# `cmr/empty-selection`
+
+The `--labels` expression of `execute --cmr` matched no device in the
+controller's `/cmr/device` inventory, so nothing ran.
+
+- For a **read**, it is a warning: `ok: true` with an empty selection and exit
+  code 0, the same as an empty CDB group. A collector that polls a sometimes
+  empty label stays quiet.
+- For a **write-shaped** command it is an error (`ok: false`, exit code 1),
+  with or without `--yes`, so a misspelled label does not look like a
+  successful bulk write. RouterOS refuses an empty selection the same way
+  (`no devices selected`). `context.write` is `true`.
+
+The same code is a **warning** on a CMR fleet command run directly with
+`execute` or `api`, such as `/cmr/vlan/add labels=EDGE` or
+`/cmr/device/reboot labels=Edge`: by the controller's inventory now, its
+selection reaches no device. RouterOS refuses an empty selection for a
+`/cmr/device` command itself; it accepts a rule whose labels match nothing,
+and the rule applies to devices that get the label later.
+
+## Typical trigger
+
+- A misspelled label. RouterOS label names are case-sensitive, and an unknown
+  label is accepted silently rather than rejected.
+- A missing comma: `labels=office+ap` is one label named `office+ap`; use
+  `office,+ap`.
+- Every matching device was removed from the controller.
+
+## Fix
+
+Check the labels on the controller (`/cmr/device print` shows `labels` and
+`auto-labels`) and re-run. `--labels all` selects every device, including the
+controller.

package/docs/errors/cmr/membership-changed.md

@@ -0,0 +1,20 @@
+# `cmr/membership-changed`
+
+The CMR client was validated, but before the command was dispatched it changed
+or left the selection. The command was **not** sent to it.
+
+## Typical trigger
+
+- The client's labels changed, so `numbers=<id> labels=<expr>` at dispatch
+  selected nothing (`failure: no devices selected`).
+- Its `/cmr/device` row disappeared, or its `ids` key changed, between the
+  validation pass and dispatch. centrs re-reads the inventory just before
+  each member's own call, after any write prompt, so a client replaced
+  while the prompt or the fan-out queue waited is caught here. A validation
+  result belongs to the key it ran on, so it is not reused for a different one,
+  and a replacement row is never adopted.
+
+## Fix
+
+Re-run. centrs validates the current selection again and only sends the
+command to clients that passed validation in that run.

package/docs/errors/cmr/not-a-controller.md

@@ -0,0 +1,26 @@
+# `cmr/not-a-controller`
+
+`execute --cmr` was pointed at a router that does not answer `/cmr/device`, so
+it is not a CMR controller.
+
+centrs then reads the target's version. RouterOS older than 7.26beta1, where
+CMR does not exist, is reported as `routeros/version-unsupported` instead. This
+error means the version has CMR (or could not be read), and `context.version`
+says which.
+
+## Typical trigger
+
+- The optional `cmr` package is not installed. Clients only have the built-in
+  `/cmr/client`; the controller needs the package.
+- The target is a CMR *client*, not its controller. `context.controllerIdentity`
+  and `context.controllerAddress` then name the controller it is paired to.
+
+Only a missing menu raises this: native API reports `no such command prefix`,
+REST `no such command or directory (cmr)`. Any other failure reading
+`/cmr/device`, such as a permissions error, is reported unchanged.
+
+## Fix
+
+Point the command at the controller: the router with the `cmr` package and
+`/cmr set enabled=yes`. Its `/cmr/device print` lists the clients `--labels`
+selects from.