@tikoci/centrs 0.1.9-next.0 → 0.1.9-next.22

package/commands/execute/README.md

@@ -47,12 +47,23 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   write-shaped operation. In script mode every command head in a statement
   (the statement start and each `[…]` or `{…}` body) must be a read: its verb
   is the first word past the known menu prefix, so `/ip address print` is a
-  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
-  execution through `:execute` are write-shaped too, and so is any command
-  carrying `file=`: RouterOS redirects command output into a device file, so
-  `/ip/address/export file=address` creates `address.rsc` and
-  `/file/print file=test` creates `test.txt` even though `export` and `print`
-  are read verbs. The shared
+  read and `/user expire-password print` is not (examples W3). Script
+  directives that only output, branch or compute a value are reads, including
+  the pure functions `:serialize`, `:deserialize`, `:convert`, `:delay`,
+  `:find`, `:timestamp`, `:rndnum`/`:rndstr` and the `:to*` converters, and the
+  `{…}`-bodied `:retry` and `:time` (example W4, #458). The absolute
+  `/serialize` spelling counts too; a bare `serialize` keeps the menu-verb rule,
+  because after navigation it could name a menu command. RouterOS runs only a
+  `{…}` block in a script-typed argument, so every body is visible to the gate.
+  Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, as are `:global`, `:set`
+  and `:parse`, and so is any command carrying `file=` or `file-name=`
+  (including argument prefixes such as `fi=` and `file-n=`, and the spaced
+  `file-name value` spelling under print/export/serialize, example W5):
+  RouterOS redirects output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc`,
+  `/file/print file=test` creates `test.txt` and `:serialize … file-name=x`
+  creates `x`, even though `export`, `print` and `:serialize` are reads. The shared
   `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
@@ -180,7 +191,9 @@ duplicate that table. Behavior notes the generated reference cannot carry:
 - `--` — use it when the command contains tokens that would otherwise be
   claimed as centrs flags; otherwise the command must be quoted as a single
   argument. In fan-out, positional targets come BEFORE `--` and the command
-  AFTER it (see **Target selection**).
+  AFTER it (see **Target selection**). centrs flags go before `--` too: one of
+  execute's own long flags after it (a trailing `--json`) is refused before
+  dialing as `usage/flag-after-separator`, with the corrected line (#459).
 
 ### Designed, not implemented
 
@@ -296,8 +309,12 @@ when the target is itself a CMR client.
   selects the controller. CDB selectors (`--group`/`--where`/`--all`/
   `--default`/geo), several targets, and `--via mac-telnet|ssh` are
   `usage/conflicting-flags`. `--labels` without `--cmr` is refused the same way.
-  Labels that no device has are accepted silently by RouterOS; an empty
-  selection is `ok: true` with the warning `cmr/empty-selection`. A device's
+  Labels that no device has are accepted silently by RouterOS. An empty
+  selection is `ok: true` with the warning `cmr/empty-selection` for a read,
+  and the outer error `cmr/empty-selection` for a write-shaped command, with
+  or without `--yes` (#460), as RouterOS refuses it (`no devices selected`). A
+  mistyped label then exits 1 instead of looking like a successful bulk write.
+  A device's
   identity selects it only while the controller's `/cmr auto-labels` includes
   `identity` (the default `all` does). On 7.26beta1, after `auto-labels=version`
   a client's row still *showed* its identity label but no longer matched it.
@@ -336,16 +353,33 @@ when the target is itself a CMR client.
 - **Write gate:** one `--yes`/TTY confirmation, naming how many clients will run
   it, how many were excluded, and through which controller. Clients that failed
   validation are never sent the command.
+- **The controller login is not the limit (#456).** On 7.26beta1, RouterOS
+  does not check the caller's policy against a CMR script. `run-script`
+  needed only `read` + `api` on the controller login, and
+  `/cmr/device/reboot` only `read` + `test` + `api`. A login refused a direct
+  write (`not enough permissions (9)`) still wrote to clients and to the
+  controller's own row through `run-script`, and rebooted a client through
+  both. So a "reader" login on a 7.26beta1 controller is not read-only, and
+  centrs' write gate (and `mcp=ro` on MCP) is the only gate. MikroTik
+  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; that is not yet
+  checked on a beta2 build. For a write,
+  centrs reads the login's own `/user` row and `/user/group` once (both are
+  readable with just `read` + `api`). When the login lacks `write`, `test` or
+  `reboot`, the result and the confirmation error carry
+  `cmr/caller-policy-not-enforced` naming what it lacks. A failed read only
+  loses the warning.
 - **Dispatch:** one call per validated member, sending the input unchanged with
   `timeout=` set from `--timeout` (capped at 55 s, under CMR's ~60 s per-call
   ceiling). Every call pins `strategy=parallel fail-policy=continue
   freeze-frame-interval=20ms`. **Never retried.**
 - **Outcomes** are a `FanoutData` envelope in inventory order, with exit codes
-  0/2/1. Each member's `meta.target.cmr` carries `{controller, id, deviceKey,
-  address}`. `success` → `data.ret` holds the client's output; a clipped
+  0/2/1. The outer `meta.target` is the controller, and the settings,
+  request and login every member shares are written once on the outer
+  envelope ([constitution](../../docs/CONSTITUTION.md#result-envelope)). Each
+  member's `meta.target.cmr` carries `{id, deviceKey, address}`. `success` → `data.ret` holds the client's output; a clipped
   output adds `cmr/output-truncated` and `meta.truncated`. `--max-results`
   applies per member, as in plain execute fan-out: a member whose rendered
-  envelope exceeds it (UTF-8 bytes) becomes `input/max-results-exceeded`, and
+  envelope (with its full meta, as it would render alone) exceeds it (UTF-8 bytes) becomes `input/max-results-exceeded`, and
   that error says the command already ran (`context.dispatched: true`). A `failed` runtime
   error maps through the usual `routeros/*` table. `skipped` →
   `cmr/client-disconnected`.
@@ -366,8 +400,15 @@ when the target is itself a CMR client.
 - **Validation metadata** reports what ran: `source: ":put [:parse ...] via cmr
   run-script"`, the same claim the console gate makes. There is no client
   `/console/inspect` stage.
-- **Not on MCP** until delegated authorization is designed (#449). `retrieve
-  --cmr` is deferred (#441).
+- **No progress stream.** `run-script` returns a client's output only when its
+  script ends, and no `/cmr` menu records a running script. To watch a long
+  CMR job, follow what it changes on a client:
+  `centrs retrieve <client> /ip/address --follow` while
+  `execute <controller> --cmr` adds addresses. That only works when the client
+  can also be reached directly; otherwise re-run a read through `--cmr`.
+- **Not on MCP** until delegated authorization is designed (#449). That design
+  must not assume RouterOS refuses a fleet write for a `!write` login (see
+  above). `retrieve --cmr` is deferred (#441).
 
 `/cmr/device/dashboard` is an interactive console view, refused as
 `cmr/console-only`. A plain path, abbreviated or not (`/cmr/dev/dash`), is
@@ -382,6 +423,59 @@ Calling `/cmr/device/run-script` yourself, through `api` or plain `execute`,
 validates only the controller request. The envelope then carries the warning
 `cmr/client-script-not-validated`.
 
+### Fleet commands run directly (#453)
+
+A controller's fleet commands are one request to one router that act on many
+devices: `/cmr/device/{reboot,upgrade,pair,run-script}`,
+`/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`, and `add`, `set`,
+`remove`, `enable` or `disable` on `/cmr/vlan`, `/cmr/wifi`,
+`/cmr/wifi/radio` and `/cmr/upgrade`. They are write-shaped, so they need
+`--yes`. Before that gate, plain `execute` (and `api`) reads the controller's
+`/cmr/device` inventory, read-only, and resolves which rows the command
+reaches, where it can (see "Not resolved" below). The command still runs
+exactly as typed.
+
+- **The gate names the reach.** The prompt and the `usage/confirmation-required`
+  summary say how many CMR devices the command reaches and whether the
+  controller's own row (`controller=true`) is one of them. `error.context.cmr`
+  has `devices`, `connected`, `controllerIncluded`, `identities` and
+  `inventory`.
+- **How the selection is resolved.** `numbers` matches a row's `.id` or
+  identity. `labels` follows the manual's rules over the row's `labels` and
+  `auto-labels`: plain labels are OR, `+label` must match, `-label` excludes,
+  `all` selects every row, and an expression with only exclusions starts from
+  every row. On a 7.26beta1 lab this matched the device's own selection
+  (a `run-script` probe per row) for every expression tried; the lab test
+  re-checks it (CMR-D9). It is the controller's current view: a disconnected
+  device's `auto-labels` can be stale. `/cmr/upgrade/trigger` reaches the rows
+  whose `upgrade-rule` it names. A rule's `set`, `remove`, `enable` or
+  `disable` reads the rule's own `labels`; a `set` that changes `labels`
+  reaches the old and the new devices. WiFi band labels (`+2ghz`, `+5ghz`,
+  `+6ghz`) pick radios, not devices, so they are left out.
+- **Warnings, with or without `--yes`:**
+  - `cmr/selection-includes-controller`: the selection includes the
+    controller's own row (`labels=all` does, per the manual).
+  - `cmr/rule-selects-every-device`: a rule command with no device `labels`
+    (for `/cmr/vlan`, no `port-labels` either). The manual warns that such a
+    VLAN rule provisions every port of every connected device, the controller
+    included, and cuts the fleet's management access.
+  - `cmr/empty-selection`: by the controller's inventory now, nothing is
+    selected. RouterOS refuses this for a `/cmr/device` command; it accepts
+    a rule whose labels match nothing.
+  - `cmr/caller-policy-not-enforced` for `run-script` and `reboot`, as for
+    `--cmr` above (#456).
+- **Not resolved:** an abbreviated selector argument (`lab=all`),
+  `--via ssh` or `mac-telnet`, `/cmr/upgrade/job/run-next` (a job's devices
+  are not in the inventory), and a failed read. The gate still names the
+  fleet command and says why its reach is unknown, for example `would reach
+  the CMR devices it selects through controller ctl (not resolved: an upgrade
+  job's devices are not in the inventory)`, and `error.context.cmr` has
+  `unresolved` instead of the counts. A failed read never blocks the command,
+  and after a transport or login failure the policy read is skipped. Two
+  cases are not recognized as fleet commands at all and keep the plain
+  wording: script-shaped input (a positional id or `[find …]`) and CDB fan-out
+  to several controllers, which has its own gate.
+
 ## mac-telnet L2 validation
 
 Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s

package/commands/execute/examples.md

@@ -573,6 +573,47 @@ argument happens to be `print`, so it returns `usage/confirmation-required`.
 Every command head in a statement is checked, including `[…]` and `do={…}`
 bodies.
 
+### W4. Pure script functions are reads; an output file is not (#458)
+
+```bash
+centrs execute $R ':put [:serialize to=json [/system/resource/print as-value]]' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true` without `--yes`; `data.ret` parses as JSON whose
+`version` is the router's. `:delay`, `:convert`, `:deserialize`, `:find`,
+`:timestamp`, `:rndnum`, `:rndstr`, the `:to*` converters, `:retry` and `:time` are reads
+too; any command inside their arguments or `{…}` bodies is still checked.
+RouterOS runs only a `{…}` block in a script-typed argument and refuses a quoted
+string there, so no body hides in text. `:serialize … file-name=centrs-w4`
+creates a device file, so it returns `usage/confirmation-required`, as `file=`
+does under a read verb. `:global`, `:set`, `:execute` and `:parse` stay writes.
+
+### W5. Abbreviated output-file arguments keep the write gate
+
+```bash
+centrs execute $R '/system identity export fi=centrs-w5' --via rest-api --username $U --password $P </dev/null
+centrs execute $R ':serialize to=json value=1 file-n=centrs-w5.json' --via rest-api --username $U --password $P </dev/null
+```
+
+Both return `usage/confirmation-required` and create no file. The same
+commands with `--yes` pass validation and create `centrs-w5.rsc` and
+`centrs-w5.json`, respectively. Native API has the same result. Through
+`centrs_execute`, an `mcp=ro` record returns `cdb/write-not-permitted` with or
+without `confirm: true`, and creates no file.
+
+RouterOS also accepts `fi "centrs-w5"` and `file-n "centrs-w5.json"`, without
+`=`. They keep the same confirmation and MCP policy gates, including when
+serialize's file argument follows a nested value expression.
+
+`test/integration/execute-write-gate.test.ts` proves the refusal, absence and
+confirmed creation. The export control runs on the selected channel; the
+serialize control pins CHR 7.26beta1, where its file output was reproduced.
+The export uses CLI script spelling: structured attribute validation requires
+full argument names and rejects `fi` as `validation/unknown-attribute`.
+This is a grounding version, not an introduction boundary. Unknown or
+ambiguous output-file prefixes stay write-shaped until the device resolves
+them.
+
 ### R1. A post-validation `/execute` rejection fails the overall envelope
 
 ```bash
@@ -622,6 +663,16 @@ centrs execute --group no-such-group --via rest-api --cdb-file $CDB --json -- /s
 `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
 `warnings` include `cdb/empty-group`. Exit `0`.
 
+The same group with a write is an outer error, with or without `--yes`, so a
+misspelled group cannot pass for a successful bulk write (#460):
+
+```bash
+centrs execute --group no-such-group --via rest-api --cdb-file $CDB --yes --json -- '/system/identity/set name=x'
+```
+
+`ok: false`, `error.code` `cdb/empty-group`, `error.context.write` `true`.
+Exit `1`. Nothing is dialed.
+
 ### F3. `--where` device-class selector (subset)
 
 ```bash
@@ -763,7 +814,7 @@ transport.
 ### Q3. Repeated `--quickchr` fans out; an unknown machine is an inner failure
 
 ```bash
-centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
+centrs execute --quickchr $NAME --quickchr no-such-machine --json -- ':put 1'
 ```
 
 Envelope: outer `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`;
@@ -775,9 +826,9 @@ the unknown machine's inner error is `quickchr/machine-not-found`. Exit code 2
 `test/integration/execute-cmr.test.ts` runs these on a two-CHR CMR lab
 (`test/integration/cmr-lab.ts`): `$CTL` is a 7.26beta1 controller with the
 `cmr` package, paired with one client over a socket link. Examples CMR1–CMR7
-and CMR10–CMR14 run over **both** `--via native-api` and `--via rest-api` to
+and CMR10–CMR18 run over **both** `--via native-api` and `--via rest-api` to
 the controller, with validation on. The same test first asserts the device
-behaviour the design depends on (CMR-D1–D8 in the test file).
+behaviour the design depends on (CMR-D1–D9 in the test file).
 
 ### CMR0. A router without CMR
 
@@ -856,6 +907,16 @@ centrs execute --quickchr $CTL --cmr --labels no-such-label -- ':put x'
 `ok: true`, `data.summary.total` is 0, warning `cmr/empty-selection`, exit
 code 0.
 
+The same labels with a write are an outer error, with or without `--yes`, as
+RouterOS itself refuses an empty selection (#460):
+
+```bash
+centrs execute --quickchr $CTL --cmr --labels no-such-label --yes -- '/system/note/set note="x"'
+```
+
+`ok: false`, `error.code` `cmr/empty-selection`, `error.context.write` `true`,
+exit code 1. No note changes.
+
 ### CMR8. CLI exit code for a mixed result
 
 CMR2 through `runCli` exits `2`.
@@ -920,6 +981,21 @@ centrs execute --quickchr <client> --cmr --labels all -- ':put x'
 `cmr/not-a-controller`: the client runs 7.26beta1 but has no `cmr` package.
 `context.controllerIdentity` names the controller it is paired to.
 
+### CMR15. A controller login without `write` or `reboot`
+
+The controller has a group with `read,test,api,rest-api,!write,!reboot,!sensitive,!policy`
+and a user `$READER` in it. That login cannot write on the controller
+directly, but:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --cmr --labels <client> --yes -- '/system/note/set note="<marker>"'
+```
+
+The target is `ok`, the client's note reads `<marker>`, and the envelope warns
+`cmr/caller-policy-not-enforced` with `context.missing` `["write", "reboot"]`:
+CMR ran the script with `read,write,test,reboot` (#456). The same write as the
+lab's admin login has no such warning.
+
 ### CMR13. The dashboard behind a relative menu change
 
 ```bash
@@ -931,3 +1007,42 @@ The first is `cmr/console-only`: the controller's `:parse` resolves it to
 `/cmr/device/;(evl /cmr/device/dashboard)`, so it is refused before it runs.
 The second is `ok` with `data.ret` `CMR device dashboard`: a string that spells
 the words is not a command.
+
+### CMR16. A fleet command names the devices it reaches (#453)
+
+```bash
+centrs execute --quickchr $CTL -- '/cmr/device/reboot labels=all'
+```
+
+Without `--yes` (no TTY) this is `usage/confirmation-required`. Its summary
+says it would reach 2 CMR devices, the controller itself among them, and
+`error.context.cmr` is `{devices: 2, controllerIncluded: true}` with both
+identities. The envelope warns `cmr/selection-includes-controller`.
+Nothing reboots.
+
+### CMR17. A rule with no labels
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/add vlan-ids=4001 disabled=yes comment=<marker>'
+```
+
+`ok: true` with the warning `cmr/rule-selects-every-device`: the rule has no
+`labels` and no `port-labels`. It is added disabled, so nothing is
+provisioned. Removing it by its `.id` warns the same way, read from the rule:
+
+```bash
+centrs execute --quickchr $CTL --yes -- '/cmr/vlan/remove numbers=<id>'
+```
+
+### CMR18. `run-script` called directly by a login without `write` or `reboot`
+
+With CMR15's restricted login:
+
+```bash
+centrs execute 127.0.0.1 --port $API --username $READER --password $PW --yes -- '/cmr/device/run-script labels=<client> script=":put centrs-cmr18"'
+```
+
+`ok: true`, with the warnings `cmr/caller-policy-not-enforced`
+(`context.missing` `["write", "reboot"]`) and
+`cmr/client-script-not-validated`. The same command as the lab's admin login
+has neither the policy warning nor `cmr/selection-includes-controller`.

package/commands/explain/README.md

@@ -392,7 +392,8 @@ bare menu path. The positional grammar stays **target-first like every other
 router-taking command** (amended in PR review — the shared resolver/selection
 helpers assume it): one positional means offline and it *is* the input; two
 positionals mean live with the router first; `--` is accepted before the
-input; **`--file` replaces the input positional in either form**, so with it
+input, and one of explain's own long flags after it is refused as
+`usage/flag-after-separator` (#459); **`--file` replaces the input positional in either form**, so with it
 every positional is a target. Adding a
 router therefore never reinterprets a previously valid offline invocation.
 

package/commands/mcp/README.md

@@ -178,6 +178,17 @@ MCP server applies it as a hard allowlist:
   regardless of `confirm`; a local CDB mutation through `centrs_devices` or
   `centrs_discover` `save` fails with `usage/confirmation-required` unless
   explicitly confirmed.
+- **`mcp=ro` does not rest on RouterOS policy.** On a 7.26beta1 CMR
+  controller, a login without `write` or `reboot` wrote to a client and to the
+  controller's own row through `/cmr/device/run-script`, and rebooted a client
+  through `run-script` and `/cmr/device/reboot`. That is the CHR reproduction
+  on #456; the integration test re-proves the `run-script` write (CMR15).
+  MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 will refuse this for a `read` group, but
+  centrs' classification does not depend on it: every CMR fleet command
+  (`run-script`, `reboot`, `upgrade`, `pair`, `/cmr/upgrade/trigger`, …) is
+  write-shaped over every path, pinned by `test/unit/write-gate-tables.test.ts`,
+  and `mcp=ro` refuses them whatever the controller login's group is. Any
+  future MCP route to CMR clients (#449) must keep that assumption.
 - **`--allow-adhoc-targets`** (off by default) is reserved for one-off lab/power
   user flows. Current RouterOS-facing tools expose no inline host+credential
   schema, so the CDB allowlist remains the only active target source.

package/commands/mcp/examples.md

@@ -131,6 +131,12 @@ With `$NAME` registered `mcp=ro` (default):
 Envelope: `ok: false`, `error.code = "cdb/write-not-permitted"`. The router is not
 mutated even though `confirm` is true — the CDB policy is authoritative.
 
+Output-file arguments count as writes even when abbreviated:
+`:serialize to=json value=1 file-n=out.json` and
+`/system identity export fi=out` are refused with or without `confirm`.
+The CHR refusal and file read-back controls are
+[execute example W5](../execute/examples.md#w5-abbreviated-output-file-arguments-keep-the-write-gate).
+
 ### 8. Write against an `mcp=rw` target succeeds with `confirm: true`
 
 With `$NAME` registered `mcp=rw`:

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):
 

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
 
@@ -104,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
 
@@ -126,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. |
@@ -150,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
 
@@ -190,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