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

package/commands/explain/examples.md

@@ -483,7 +483,8 @@ REST body; the comment text is never rendered as an operand.
 
 The CHR assertion grounds the wider placement rule on the requested RouterOS
 channel via `/console/inspect request=highlight` plus `:parse`: unquoted `#`
-inside brace arrays and parenthesized expressions is a hard error; the first
+inside brace arrays and parenthesized expressions is a hard error, except at
+column 0 inside an array (example 37); the first
 non-space `#` in `do`, `else`, `foreach do`, and `on-event` bodies that are
 themselves in a statement context is a comment — the same `do={ # c` nested
 inside an array is an array and `#` is an error (placement table, #249), while
@@ -700,3 +701,261 @@ envelope would otherwise have to derive the name/value boundary from
 The same command also shows the two `=` bytes staying apart: the one in
 `($x = 1)` is a comparison and comes back `operator`, decided by fill order
 rather than by a scan for the byte.
+
+### 33. A space for the `=` is not an empty argument list
+
+```bash
+centrs explain '/ip/firewall/layer7-protocol add comment "something" regexp 1.1' --json
+```
+
+RouterOS accepts this as `comment="something" regexp=1.1`: `:parse` lowers both
+spellings to the same IL, and `highlight` marks each gap `syntax-obsolete`.
+Which word is an argument name is per-command schema, so offline publishes
+neither reading. The statement stays `resolved` on
+`/ip/firewall/layer7-protocol add`, `command.args` is absent, `arguments.read`
+is `false` with a `why` naming `` `comment "something"` ``, and
+`transport.classification` stays `"unknown"`.
+
+`data.verdict` is `warn`, with one
+`explain/canonicalizer/possible-spaced-argument` **warning** per pair,
+spanning `comment "something"` and `regexp 1.1`. Each says to write the `=`.
+The warning needs a value that cannot be a flag: `/interface set ether1 name x`
+also abstains but does not warn, because `/interface print detail
+without-paging` is the same shape and is two flags
+(`detail=true;without-paging=true`). The `=` spelling still reads both
+arguments, and a script body may drop its `=` too:
+`/system/script add name=beep source { :beep }` is the `source={ :beep }` body,
+not an invalid brace.
+
+### 34. An unlisted bare path does not become a menu
+
+```bash
+centrs explain $'/terminal/cuu\nprint\nadd name=x' --json
+```
+
+`/terminal/cuu` is a no-argument command that neither the menu table nor the
+command catalog lists. `/ip fire conn` has the same shape and is navigation:
+RouterOS accepts abbreviated menus. CHR 7.24.5 `:parse` confirms both, so a
+table miss cannot decide between a menu and a command.
+
+The first statement stays `ambiguous`. The two after it are `unknown`
+(`context lost to an earlier unreadable statement`, `contextCertain: false`),
+with no `command` and no `transport`, where they used to resolve to an
+invented `/terminal/cuu/print` and `/terminal/cuu/add`. On the device they are
+`bad command name print` and `bad command name add` at the root.
+`structure.containsWrite` is `unknown` and `data.verdict` is `warn`. A known
+absolute navigation recovers the context: in
+`/terminal/cuu`, `/ip address`, `print`, the last statement resolves to `print`
+at `/ip/address` again.
+
+### 35. A brace after a command is its argument, not a menu block
+
+```bash
+centrs explain '/system/script add name beep source { :beep }' --json
+```
+
+`/menu { … }` opens a menu block only when the words before the brace name a
+menu. Here `add` is a command, so the brace is the value of `source` with the
+`=` left out. CHR 7.22.1 and 7.24.5 `:parse` give the same IL as
+`source={ :beep }`.
+
+`data.structure.statements` has one statement, `/system/script add`, whose
+span covers the whole input. `:beep` is no longer published as a second
+top-level statement, which RouterOS never runs. `data.verdict` is `warn`, from
+the `possible-spaced-argument` diagnostic on `source { :beep }`.
+
+RouterOS accepts any unique prefix of an argument name. An abbreviation that
+can only stand for a script-valued name keeps its body in either spelling:
+`sour { :beep }`, `down-scr { :beep }` and `o={ :beep }` lower to `source=`,
+`down-script=` and `on-event=` on CHR 7.24.5 and 7.23.8. Abbreviating the first
+segment (`down={ :beep }` for `down-script`) is accepted on the device too, but
+offline still reports `invalid-command-brace`. Every word is a prefix of some
+`<word>-script`, so telling it from `comment={ :beep }` needs the command's
+argument list.
+
+A brace straight after a command is a device error, and offline now reports it.
+`/system/script add { :beep }`, `/ip/route/print {1;2}` and
+`/system/reboot { :beep }` each get `invalid-command-brace` and `data.verdict`
+`fail`. A run that names no command still opens a block, so
+`/system script { print }` is navigation to `/system/script` followed by
+`print`.
+
+### 36. A brace in a `where` clause is an array value
+
+```bash
+centrs explain '/ip address print where interface in {"ether1";"ether2"}' --json
+```
+
+A `where` clause is expression context, so the brace is the array operand of
+`in`. CHR 7.24.5 and 7.23.8 `:parse` lower it to
+`(in $interface ether1;ether2)`. `data.verdict` is `pass`, so `centrs execute`
+runs this read. Before #502 its offline stage refused it with
+`invalid-command-brace`. `data.values.occurrences` holds the array and its two
+string members, the same three records as
+`where interface in ("ether1","ether2")`.
+
+The brace is also a value after `~`, `<`, `>`, `<=` and `>=`, on the left of an
+operator (`where {"ether1"} in interface`), and after `!interface=` or `"a"=`.
+
+After `<name>=`, `<name>!=` or `<name>==`, spaced or not, the device reads the
+value with that property's parser and rejects the brace. Two examples are
+`where interface={"ether1"}` (`expected interface value`) and
+`where disabled={"y"}` (`expected yes or no`). Offline keeps
+`invalid-command-brace` at the `{` there. The device does this only for a
+property the menu knows: `where foo-bar={"y"}` parses. Offline cannot tell
+property names apart without a per-menu list, so it reports that one too.
+
+### 37. A column-0 `#` line inside an array is a comment
+
+```bash
+centrs explain ':local z {a=1;
+# c
+b=2}' --json
+```
+
+`data.verdict` is `pass`. `data.spans` holds a `comment` span over `# c`, and
+`data.values.occurrences` holds the array and its two members `a` and `b`. CHR
+7.24.5 and 7.22.1 `:parse` lower it to `value=a=1;b=2`. Before #503, offline
+failed it with `invalid-hash` at the `#`.
+
+The rule holds at any depth (`{a={⏎# c⏎1}}`) and in argument values
+(`:foreach i in={1;⏎# c⏎2} do={:put $i}`). It needs column 0: an indented `#`
+(`{a=1;⏎  # c⏎b=2}`), and one after `{`, a value or `;` on the same line, keep
+`invalid-hash` at the `#`. A `#` directly inside `( … )` stays an error too. A
+comment-only array, `:local z {⏎# c⏎}`, fails like `:local z {}`: both are empty
+arrays, which the device rejects (#511, example 38).
+
+### 38. An empty array value and a misplaced `;` are rejected
+
+```bash
+centrs explain ':local z {}' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/empty-group` over `{}`. CHR
+7.24.5 and 7.23.8 `:parse` answer `syntax error (line 1 column 12)`, the byte
+after the brace. The same holds for `:put {}`, `:return {}`, `[:len {}]` and
+`:foreach i in={} do={…}`. A nested `{}` (`{1;{}}`), one in parentheses
+(`({})`), `where … in {}` and a body (`do={}`, `:execute {}`) parse and pass.
+
+`:local z {1⏎;2}` fails with `misplaced-separator` at the `;`: a `;` needs an
+element before it on its line. `{1;}` and `{1⏎2}` pass.
+
+### 39. An expression with a missing operand is rejected
+
+```bash
+centrs explain ':put (1 +)' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/missing-operand` at the
+`+`. The device answers `syntax error (line 1 column 11)`, at the `)`. `()`
+fails with `empty-group`, and `(1; 2)` and `(1⏎+ 2)` fail with
+`misplaced-separator`. `(1 2)`, `(- 1)` and `(1 + -2)` pass. Inside a query,
+`where (comment=+)` passes: the device reads that value with the property's
+parser.
+
+### 40. A `@` in a command word is rejected
+
+```bash
+centrs explain '[admin@MikroTik] > /ip address print' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-at-sign` at the
+`@`. The device answers `syntax error (line 1 column 7)`, the same byte. This
+is a pasted console prompt. `:put a@b` and `comment=a@b` pass, because a `@` is
+a value byte in an argument.
+
+### 41. A named comparison brace inside a `[find where …]` is rejected
+
+```bash
+centrs explain ':put [/ip address find where interface={"x"}]' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-command-brace` at
+the `{`, as at the top level (example 36). The device answers
+`expected interface value (line 1 column 40)`. `where (interface={"x"})` fails
+the same way, and `[find where interface in {"x"}]` passes.
+
+### 42. A stray top-level `}` ends the script, and the rest is discarded
+
+```bash
+centrs explain ':put 1};:put 2' --json
+```
+
+`data.verdict` is `warn` with `explain/canonicalizer/discarded-close` over the
+`}` and everything after it. CHR 7.24.5 and 7.23.8 accept the script and lower
+it to `(evl /putmessage=1)`: the device stops reading at a `}` or `]` that closes
+nothing at the top level, so `:put 2` never runs and
+`/system identity set name=a}` sets `a`. `data.structure` reads only the
+prefix. A stray close inside an open group (`:put (1})`, `{:put 1]}`) and any
+stray `)` are still rejections and still fail with `unbalanced-close`. The
+execute gate refuses this warning (`commands/execute/examples.md` V9).
+
+### 43. A variable name is letters and digits
+
+```bash
+centrs explain ':local a_b 1' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-name` at the `_`.
+The device answers `expected end of command (line 1 column 9)`, the same byte.
+`:global`, `:set`, `:for` and `:foreach` read the name the same way, and
+`:local $a` and `:local (a)` fail at their first byte. `:local "a_b"`,
+`:local 1a`, `:foreach a,b in={1} do={}` and `:local name=x value=1` pass.
+
+### 44. A `$` must start a variable
+
+```bash
+centrs explain ':put "a$ b"' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/bad-string-variable` over
+the `$` and the space after it. The device answers `syntax error (line 1 column 9)`, at the space. Outside
+a string, `:put $_` fails with `invalid-variable` the same way. `"$v_x"` (which
+is `$v` then `_x`), `"\$ x"`, `"$(1)"` and `$"a b"` pass. `"a$"` also passes,
+although the device rejects it: it reads `$"` as the start of a quoted name, and
+offline's string scanners end the string there, so offline abstains.
+
+### 45. Nothing may be glued to a closed token
+
+```bash
+centrs explain ':if (true) do={:put 1}else={:put 2}' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/glued-token` at the `e`.
+The device answers `expected end of command (line 1 column 23)`. The same rule
+rejects `:put "a"b`, `$v.b`, `(1)(2)`, `[:len a]b`, `src-address=$v/24` and a
+bare word run into a `"`, `$` or bracket (`:put a"b"`, `name=a$v`). Inside
+`where` and `find`, and inside a group, the rule does not apply (`where
+comment="a"b` and `("a"b)` parse). A command argument whose property parser
+takes the glued part also passes: `dst-address-list=!"my list"` and
+`dst-port=80,"443"`.
+
+### 46. Statement ids and source ownership
+
+```bash
+centrs explain ':if (true) do={ :foreach i in={1;2} do={ :put $i } } else={ :put 0 }; :put 3' --json
+```
+
+The statements keep discovery order and have ids `s0` through `s4`.
+The `foreach` (`s1`) has `parent: "s0"`; its `put` (`s2`) has `parent: "s1"`;
+the `else` body's `put` (`s3`) has `parent: "s0"`. The final `put` (`s4`) has
+no parent. The published `do` and `else` blocks both have `owner: "s0"`;
+`s1` and `s2` share `block: 0`, and `s3` has `block: 1`. A `[find]` inside a
+body names that body's statement as its `owner`. Links describe source
+ownership; binding and execution-context claims remain separate (#507).
+
+### 47. A stored script stays opaque
+
+```bash
+centrs explain '/system/script/add name=proof source={ :local x 1; :put $x }; :put 2' --json
+```
+
+Only the installing command (`s0`) and final `put` (`s1`) appear in
+`statements[]`; neither has a parent, and `blocks[]` stays empty. The deferred
+body's local and `put` are not exposed as statements. Scheduler `on-event=`
+and Netwatch `down-script=` have the same structural boundary.
+
+The CHR controls in `test/integration/explain-structure.test.ts` parse the
+scope examples and compare stored-script creation, explicit `run`, and an
+immediate `:do` body. Those are test operations on disposable CHR; explain
+itself never executes the analyzed input.

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
 

package/docs/CONSTITUTION.md

@@ -58,6 +58,10 @@ is unsafe the offline stage is what keeps the gate from degrading to nothing. A
 clean offline pass is **necessary, never sufficient** — `explain` publishes
 `runtimeAcceptance: "not-proven"` for exactly this reason. An offline `warn` is
 an ABSTENTION and passes through to the device stage; only a `fail` rejects.
+The one exception is `discarded-close`: a stray top-level `}` or `]` that the
+device accepts and then silently stops reading at (#504). It is a warning,
+because nothing is rejected, and the gate refuses it by code
+(`src/offline-gate.ts`), because the device would run a different script.
 
 `meta.validation.stages[]` reports what each stage concluded, including a stage
 that was skipped and why. A reader must always be able to tell "the device
@@ -177,8 +181,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,8 +329,10 @@ 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

package/docs/MATRIX.md

@@ -182,16 +182,26 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**First: the CMR track** (maintainer decision 2026-10-12 on
-[#441](https://github.com/tikoci/centrs/issues/441)). Done: `execute --cmr`
+**First: `explain`** (maintainer decision 2026-10-16 on
+[#90](https://github.com/tikoci/centrs/issues/90)). In order: make the
+published offline readings honest (#350, #211), give the result a statement
+tree, then the live probe foundation (#491). Then use those probes to
+ground #351, #358 and #371, and finish live (#492 → #236 closeout). The
+plan, and what is deliberately out of this run, is the 2026-10-16 plan
+comment on #90. It is step 3 of the validation track below.
+
+**The CMR track is paused until RouterOS 7.26beta2** (maintainer decision
+2026-10-16). It was first from the 2026-10-12 decision 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–CMR14. The CMR-vs-centrs feature map is on #441
-(2026-10-13). Next, in order: the fleet blast-radius gate for controller fleet
-commands (#453), then #449's read-only slice (a `devices` view of members and a
-default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
-Live `explain` resumes after this.
+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). When it resumes, 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).
 
 **The native-api / NDJSON line** (maintainer decision on
 [#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
@@ -229,16 +239,19 @@ producers owned with #225. REST and native-api cells advance only when their
 applicable examples pass on CHR via `bun run test:integration`.
 
 Open offline follow-ups remain explicit but do not reopen the verified baseline.
-Issue #211 retains the fail-closed unlisted-path decision; #272 owns
+Issue #211 made an unlisted absolute bare path abstain (rule F, R14); rule
+P's closed-world reading is still not adopted (#372). #272 owns
 non-authoritative `.scratch/` citation cleanup. #350 (the broad optional `=`,
 schema-dependent and so belonging to step 3), #351 (an unresolvable menu that
 abstains at 2-deep nesting but hard-fails at 3-deep) and #355 (`'` is not a
 RouterOS token — a false ACCEPT the corpus join cannot see) are bounded analyzer
-defects that step 2 now surfaces through the `execute`/`api` gate. #336 and #342 are complete: the
-corpus is repinned to three *complete* builds (long-term 7.23.5, stable 7.24.2,
-development 7.25beta3), and the operator sweep and highlight slice are re-swept
-onto those same builds — plus 7.21.5 retained as an age anchor — so the operator
-axis and the token partition are scored on the same firmware. The #335
+defects that step 2 now surfaces through the `execute`/`api` gate. #336, #342 and #498 are complete: the
+corpus is pinned to schema 5, with one recorded session per release channel
+(long-term 7.23.8, stable 7.24.5, testing 7.25rc2, development 7.26beta1) read
+through `scripts/corpus-db.ts`. The highlight slice is cut from those sessions
+and gated in CI, and the operator sweep is re-run on the same builds — plus
+7.21.5 retained as an age anchor — so the operator axis and the token partition
+are scored on the same firmware. The #335
 source refresh pins both architectures of those versions beside the 7.10.2 /
 7.16 history anchors and accepts the current CLI-Reference drift. Issue #223 is
 a separate MCP response migration. If live evidence finds a wrong offline