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

package/commands/explain/examples.md

@@ -1,15 +1,12 @@
 # explain — examples
 
-Each numbered example is an executable spec. Once `explain` is implemented,
-offline examples run under `test/unit/explain.test.ts` and live examples under
-`test/integration/explain.test.ts` (rest-api) and
-`test/integration/native-api-explain.test.ts` (native-api) against a CHR booted by
-`@tikoci/quickchr` — one named test per example (example N ↔ named test N); a
-named test may carry several assertions. The offline examples are **green**
-as of #202c-2, including 1, 2, 6 and 23's `transport`/`--curl` assertions.
-The live examples are still the **target**:
-those cells are `designed`, and flag and field names track the ratified surface
-in `README.md`.
+Each numbered example is an executable spec. Offline examples run under the
+named unit/fixture suites. Live foundation examples 11, 12, 16, 24 and 48 run
+under `test/integration/explain-live.test.ts`, and describe/completion examples
+7–10, 13–15 and 19 under `test/integration/explain-live-facets.test.ts`, on REST
+and native API with a CHR booted by `@tikoci/quickchr`. Live types 52–53 run
+under `test/integration/explain-live-types.test.ts`. All of them pass on stable
+7.24.5 and long-term 7.23.8, so both protocol cells are `CHR-passed` (#236).
 
 A letter-suffixed example (`1b`, `4b`, `18b`) is the **counterpart** of the number it
 follows: the same question with the other answer, added where implementing the
@@ -151,10 +148,10 @@ renders no curl.
 centrs explain $R /ip/address -u $U -p $P --schema --json
 ```
 
-`data.schema.verbs` lists the verbs available at `/ip/address` (`add`, `set`,
-`remove`, `print`, …), each with an arg count or a drill-down hint rather than
-the full arg expansion; facts cite `live-inspect` evidence stamped with the
-CHR's RouterOS version.
+`data.schema.node` is `menu`, and `data.schema.verbs` lists the verbs at
+`/ip/address` (`add`, `set`, `remove`, `print`, …). Each carries its argument
+count from one more `child` probe rather than the full argument expansion.
+Facts cite `live-inspect` evidence stamped with the CHR's RouterOS version.
 
 ### 8. Describe a verb: its arguments
 
@@ -162,8 +159,9 @@ CHR's RouterOS version.
 centrs explain $R /ip/address/set -u $U -p $P --schema --json
 ```
 
-`data.schema` enumerates the settable arguments of `set` (`address`,
-`interface`, `disabled`, …) with types where the device reports them.
+`data.schema.arguments` enumerates the settable arguments of `set` (`address`,
+`interface`, `disabled`, …). Each has its argument-level `syntax` rows where the
+device reports them (`address`: `A.B.C.D (IP address)`).
 
 ### 9. Describe print: the proplist special case
 
@@ -171,10 +169,12 @@ centrs explain $R /ip/address/set -u $U -p $P --schema --json
 centrs explain $R /ip/address/print -u $U -p $P --schema --json
 ```
 
-`data.schema` returns the `.proplist` value set — what the output *can*
-contain — rather than treating `print` like a plain verb. The grounded probe is
+`data.schema.proplist` returns the `.proplist` value set — what the output
+*can* contain — besides `print`'s own arguments. The grounded probe is
 `completion input="/ip/address/print proplist="` (dot-free console spelling),
-filtered to rows with `show=true`; each returned fact cites that live evidence.
+filtered to rows with `show=true`; it cites that live evidence. A singleton
+settings menu (`/ip/dns/print`) offers no proplist names, so
+`get value-name=` answers with `source: "get-value-name"`.
 
 ### 10. Smart sizing truncates with counts, `--full` lifts it
 
@@ -182,9 +182,11 @@ filtered to rows with `show=true`; each returned fact cites that live evidence.
 centrs explain $R /ip -u $U -p $P --schema --json
 ```
 
-The `/ip` subtree is large: `data.schema.truncated` is `true`, counts are
-reported in place of the full expansion, and a warning/hint names the
-narrower query (or `--full`) that expands it.
+The `/ip` subtree is large (31 children, past the 16-probe default):
+`data.schema.truncated` is `true`, the names are listed with `counts` but not
+expanded, and `tip/explain-schema-truncated` names the narrower inputs in
+`data.schema.next` or `--full`. With `--full`, every submenu carries its verb
+and menu counts.
 
 ### 11. Spans and the error byte (centrs vocabulary)
 
@@ -192,9 +194,21 @@ narrower query (or `--full`) that expands it.
 centrs explain $R '/ip/address add address=bogus interface=' -u $U -p $P --json
 ```
 
-`data.spans` classify the input byte-by-byte using the **centrs** span
-vocabulary (not raw RouterOS highlight classes); the first hard error's byte
-offset appears in a diagnostic citing `live-inspect` evidence.
+`data.spans` includes device-derived spans in the **centrs** vocabulary,
+citing `live-inspect` evidence. On CHR 7.24.5, this original example produces
+no parse rejection or highlight error: `address=bogus` is not value-validated,
+and the trailing empty argument is omitted from the parse output. Keep it as
+a probe-limit control, not a promised syntax error.
+
+A confirmed hard-error control is:
+
+```bash
+centrs explain $R '/ip/route add dst-address=10.9.0.0/16 blackhole=yes' -u $U -p $P --json
+```
+
+On CHR 7.24.5, highlight reports byte 47 and parse reports line 1 column 48.
+The test asserts that source-located diagnostic separately from runtime
+acceptance; the original input remains a control on both transports.
 
 ### 12. Structure via :parse
 
@@ -213,8 +227,14 @@ here over rest-api; example 24 asserts the same readout over native API using
 centrs explain $R '/ip/address add comm' -u $U -p $P --complete --json
 ```
 
-`data.completion` includes `comment` as a completing candidate for the
-partial word `comm` — a valid partial, no unknown-word diagnostic.
+`data.completion` is `context: "argument-name"` with `comment` as a
+`partial` candidate replacing bytes 16–20. No canonicalizer diagnostic calls
+`comm` unknown. The device still rejects the input as written: `:parse` and
+the highlight `error` both name byte 16. So pass `--fail-on never` when only
+the candidates matter. `--cursor 20` gives the same answer inside a longer
+input. The same candidate comes back for a relative path after `;`
+(`/ip { :put 1; address add comm`), and `where comm` completes `comment` as a
+`variable`.
 
 ### 14. Completion: complete argument name, no value yet
 
@@ -222,9 +242,10 @@ partial word `comm` — a valid partial, no unknown-word diagnostic.
 centrs explain $R '/ip/address add comment' -u $U -p $P --complete --json
 ```
 
-The candidate set marks `comment` as a complete argument name expecting a
-value (`=` continuation) — distinct from example 13's partial match and from
-an unknown word.
+The candidate set marks `comment` as `match: "exact"` with `takesValue: true`,
+because the device offers `=` at the cursor. That is distinct from example 13's
+partial match and from an unknown word. The flag `/interface print detail` is
+exact with `takesValue: false`.
 
 ### 15. Completion: value position
 
@@ -233,9 +254,11 @@ centrs explain $R '/ip/firewall/filter add chain=' -u $U -p $P --complete --json
 ```
 
 With the input ending in `=`, candidates are **values** for `chain`
-(`forward`, `input`, `output` — labeled as observed, never a closed set). For
-a free-form argument like `comment=`, the same probe yields type info (string)
-rather than candidates.
+(`forward`, `input`, `output` — observed from the completion probe, never a closed set). For
+a free-form argument like `comment=`, the same probe yields no candidates and
+`data.completion.syntax` carries `string value`. An unclosed substitution
+(`:local x [/ip/address add interface=`) still completes, from the device's
+own path runs.
 
 ### 16. Runtime acceptance is never claimed
 
@@ -343,9 +366,9 @@ curated read verb; before the command axis this document abstained.
 centrs explain $R '/ip/route' -u $U -p $P --json
 ```
 
-`/console/inspect` completion and highlight agree that the terminal token is a
-`dir`; the first statement is `resolution: "resolved"`, `kind: "menu"`, and
-has no runnable transport rendering. The evidence entry is version-stamped and
+The highlight classes every byte `dir`, and with `--schema` the `child` self
+row says `menu`; the first statement is `resolution: "resolved"`,
+`kind: "menu"`, and has no runnable transport rendering. The evidence entry is version-stamped and
 the probe never executes the path. Since #207 the offline reading (example 18b)
 already says the same thing from the generated table, so what the live probe
 adds here is **provenance and a version stamp**, not the answer — and it is the
@@ -452,7 +475,8 @@ full MAC spelling carry `["array"]`, `["time"]`, `["id"]`, and `["mac"]`.
 is `str` while the CLI Reference declares `mac-address` as `macAddr`. Each hint
 fact cites canonicalizer evidence with
 `basis: "heuristic"`; no record has `observedType` or `schemaType`, because
-offline analysis has neither live parser output nor an argument schema. A hint
+offline analysis has neither live parser output nor an argument schema
+(examples 52 and 53 are the live counterparts). A hint
 is not a diagnostic and does not change `data.verdict` or
 `runtimeAcceptance: "not-proven"`.
 
@@ -768,10 +792,12 @@ 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.
+segment (`down={ :beep }` for `down-script`) is accepted on the device too, and
+offline warns `possible-script-body-abbreviation` there instead of rejecting
+(#525): every word is a prefix of some `<word>-script`, so telling it from
+`comment={ :beep }` needs the command's argument list, and the device decides.
+The tradeoff is deliberate — `comment={ :beep }`, which the device rejects,
+carries the same warning — and `data.verdict` stays `warn`, never `pass`.
 
 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
@@ -862,7 +888,14 @@ 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.
+a value byte in an argument. The envelope also carries
+`tip/explain-pasted-prompt` offering the stripped `/ip address print` as
+repair text (never applied). A `/menu>` prompt such as
+`/interface/lte> monitor lte1` keeps a `warn` abstention with the same tip
+shape, offering `monitor lte1` typed at `/interface/lte`. The manual's
+in-menu prompt `[admin@MikroTik] /ip/address> add …` fails the same way and
+offers `add …` typed at `/ip/address`; a HotLock `>>` is stripped with the
+prompt.
 
 ### 41. A named comparison brace inside a `[find where …]` is rejected
 
@@ -959,3 +992,127 @@ 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.
+
+### 48. Safe argument discovery distinguishes spaced arguments from flags
+
+```bash
+centrs explain $R '/interface set ether1 name x' -u $U -p $P --json
+centrs explain $R '/interface print detail without-paging' -u $U -p $P --json
+```
+
+`data.live.arguments[]` cites command-level child evidence and statement `s0`.
+The first result includes `name`, the second includes `detail`. Both parse;
+only `name x` gets the device's obsolete-syntax warning. An unknown argument
+control (`/interface set ether1 definitely-unknown-491=x`) carries the shared
+parse classifier's rejection. No command-level completion is requested.
+
+The integration controls also explain a write-shaped identity change and a
+substitution without executing either, verify identity before/after, exercise
+CLI stdin and quickchr resolution, and skip oversized highlight without
+submitting a prefix. Parse/hash/normalization evidence preserves the Unicode
+byte coordinates. Run on long-term as well as stable before changing these
+claims. Sanitized captures can be regenerated with `CENTRS_EXPLAIN_CAPTURE`
+pointing at an ignored output file when running the integration suite.
+
+### 49. `?`, a backtick and a second `=` need quotes
+
+```bash
+centrs explain '/tool/fetch url=http://x/a?b=c' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/unquoted-reserved-byte`
+at the `?`. The device answers `expected end of command (line 1 column 27)`,
+the same byte. A backtick is rejected the same way, in a value, a
+positional, a `where`, a `find`, an array and an expression. A second `=` in
+a menu command's argument is rejected at that `=`. So `name=a=b` and a bare
+base64 key ending in `=` both fail. The value's property parser never takes
+these bytes: `regexp=a?b` and `secret=abc==` are rejected too. In a menu
+command's argument name, the device reports from the name's first byte
+(`/ip/address/add a?b=1` at the `a`). `url="http://x/a?b=c"`,
+`where comment=a=b`, `[find comment=a=b]`, `{a=b}` and `# a?b` pass.
+`:put a=b` abstains: 7.24.5 reads it as a named argument and 7.23.8 rejects
+the `=`.
+
+### 50. A non-ASCII character outside a string is rejected
+
+```bash
+centrs explain ':put $café' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/unquoted-non-ascii` over
+the `é`. The device answers `expected end of command (line 1 column 10)`, at
+the `é`'s first byte. RouterOS reads only ASCII outside a string. A bare
+value (`name=router-café`, `name=🛰`), a reference, a path (`/systemé`), a
+verb, an argument name, a `where` value, an array and an expression are all
+rejected. So are pasted non-breaking spaces, curly quotes and ellipses. A
+declared name (`:local café`) keeps its `invalid-name` error. Strings and
+comments carry any byte: `:put "café"`, `:local "café" 1`, `$"café"`,
+`name="router-🚀"`, `# café` and a multi-line string pass. The informational
+`non-ascii` fact is still published beside the error, and a leading BOM is
+not read as part of the first word.
+
+### 51. A brace after a submenu opens a block at any depth
+
+```bash
+centrs explain '/ip { address { print {1;2} } }' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-command-brace` at
+the inner `{`. The device answers `expected end of command (line 1 column 23)`,
+the same byte. `address {` inside `/ip { … }` is a block over `/ip/address`,
+so `data.structure.statements` reads `/ip`, `/ip/address` and
+`/ip/address print`, and the `{1;2}` is the operand of `print`.
+
+The device reads a brace after a menu word as statements whatever the body
+holds, at any depth. A body offline cannot resolve abstains with
+`unresolved-statement` instead of failing as an array:
+`/ip { address { 1;2 } }` (the device says `bad command name 1`) and
+`/ip { address { zzznotamenu { print } } }` (`syntax error`) both give `warn`,
+as `/ip/address { 1;2 }` and `/ip { zzznotamenu { print } }` do.
+`/ip { address { print } }` and `/ip { firewall { filter { print } } }` pass.
+The menu must be known from the source alone, so a block after a navigation
+statement (`/ip⏎address { … }`), an abbreviation (`addr {`) and a digit-led
+menu (`6to4 {`) keep the older reading.
+
+### 52. A live call observes a type only where the device converts a literal
+
+```bash
+centrs explain $R ':local x 2.2; :set x "2.2"; :local z (1,0x10,2.2); :local t 200ms; :local i *1; :local y yes' -u $U -p $P --json
+```
+
+This is example 26's input against a target. The bare `2.2` gains
+`facts.observedType: { value: "ip", rendered: "2.0.0.2" }`, `200ms` gains
+`time` (`00:00:00.200`) and `yes` gains `bool` (`true`). Of the array's
+members, `0x10` is `num` (`16`) and `2.2` is `ip`, while `1` renders unchanged
+and gets nothing. The quoted `"2.2"` and the id `*1` also get nothing, because
+an unchanged rendering proves no type: `:parse` prints a string unquoted. The
+`shapeHints` are untouched, and no record has `schemaType`, because no value
+here is a menu command's argument.
+
+A scripting directive's named argument is an operand too:
+`:for i from=0x10 to=20 do={:put $i}` gives `from` the fact `num` (`16`), and
+`to=20` renders unchanged and gets nothing. A NAME slot is a variable, never a
+value: in `:local yes 2` and `:local name=no value=yes`, the names `yes` and
+`no` get nothing (the device renders `name=$yes`, `name=$no`), while
+`value=yes` is `bool`.
+
+Each fact cites one `:parse` evidence entry per context (operands, members)
+with `facet: "types"` and `basis: "derived"`. The probe re-parses each literal
+alone, as `:local vN <lit>` or `:local vN {<lit>}`; the analyzed input and
+the literals are never evaluated, and no `:typeof` is sent.
+
+### 53. A live call normalizes each argument's declared type
+
+```bash
+centrs explain $R '/ip/dns/set servers=1.1.1.1,8.8.8.8; /ip/route/add gateway=2.2 dist=2 comment=abc; /ip/firewall/filter/add chain=input dst-port=80,443 protocol=tcp disabled=yes' -u $U -p $P --json
+```
+
+Each `name=value` gains `facts.schemaType` from one argument-level `syntax`
+probe. `servers` is `{ values: ["ip", "ip6", "enum"], declared:
+"Address[@VRF]" }`, and `gateway` is `ip`, `ip6`, `enum`. `dist` resolves as
+the unique prefix of `distance` and is `num`. `comment` is `str`. `chain` is
+`enum` plus `str`, since custom chains are legal. `dst-port` is `num` with
+`list: true`. `disabled` gets nothing, because the device declares a boolean
+with a blank row. No menu argument gets `observedType`: its own parser
+converts it, which is the schema's slot. The text output prints
+`observed=ip(2.0.0.2)` and `schema=ip|ip6|enum` on the value rows.

package/commands/retrieve/README.md

@@ -87,12 +87,32 @@ alternatives in the error envelope.
 `failed` when the gate refuses: `validation/*`, or `--query` on a singleton.
 It is absent when a `transport/*`, `auth/*`, `routeros/*` or `internal/*` error
 stopped inspect from answering; the device stage then says `not reached`
-(examples 12 and 16b; 16c is the `passed` case). With `--validate=false` it
-is `{enabled: false, source: "disabled"}`.
+(examples 12 and 16b; 16c is the `passed` case). The same holds for a
+`wait/*` error from a `--wait` whose gate never settled, and for
+`--sample` / `--follow` cancelled before the gate ran. That last case has no
+error code, so its reason is `not reached: interrupted` (#537). With
+`--validate=false` it is `{enabled: false, source: "disabled"}`.
 
 If `--all-attributes` is combined with `--attribute(s)`, fail with
 `usage/conflicting-flags` *before* hitting the network.
 
+A read only ever dispatches a `print`/`get`, on every transport and even with
+`--validate=false`: that flag skips command validation, not the read/write
+split (#586). Each path segment must be a RouterOS menu name — letters,
+digits and hyphens (case folds), the grammar of every dir and command in the
+7.9–7.26 tree — or the read fails with `input/invalid-routeros-path` before
+resolution. Before this check, a `#` or `?` cut the appended `/print` off the
+REST URL, so `retrieve '/system/reboot#' --no-validate --attribute uptime`
+posted `/rest/system/reboot` and rebooted CHR 7.24.5. A well-formed command
+path is safe: RouterOS answers `POST /rest/system/reboot/print` (and a `GET` of
+a command) with "no such command", and native API answers
+`/system/reboot/print` the same way (CHR 7.24.5). Under the REST adapter, a
+second guard refuses any request path containing `?`, `#`, `\`, a control
+character, or a `.`/`..` segment (including the percent-encoded `%2e%2e` and
+`.%2E` forms, which the URL parser also collapses) for every command. RouterOS
+does not decode percent-escapes in REST paths, so nothing else changes the
+target.
+
 SNMP validation is separate from RouterOS `/console/inspect`: OIDs and MIB
 names must resolve through the MIB cache before any SNMP request is sent.
 
@@ -147,6 +167,14 @@ handling.
 }
 ```
 
+Projection rule: the bare value is about the attribute *count*, not the flag
+spelling. On a singleton, exactly one projected attribute — `--attribute x`
+or `--attributes x` alike — returns the bare value (`data` is the scalar,
+not an object); two or more return an object with those keys. On a list, any
+projection returns an array of objects, even a single attribute. Unprojected
+reads return the full object (singleton) or the row array (list). (Examples
+5–6, 20, N5–N6 pin every cell of this table.)
+
 `--max-bytes` / `--max-rows` truncation populates
 `meta.truncated = { returned, total, totalBytes }` and keeps `ok: true` with a
 warning entry — it is not an error. (Earlier text said a byte overflow returns an
@@ -513,7 +541,11 @@ stays the single-target envelope; a selector flag or a second positional target
 switches to fan-out. `--quickchr <name>` (the named-live-provider) behaves like a
 lone positional: one flag stays single-target, repeating it fans out, and mixing
 it with positionals or CDB selectors is `usage/conflicting-flags` (constitution:
-resolution providers). The `--host` **flag** with no `<router>` positional
+resolution providers). When several CDB records share one `<router>` (the
+same address saved under two users), `--match user=<name>` (or
+`target=<addr>`, or a record type) picks one, as on `devices show`; it is
+single-target only (see
+[devices → Ambiguity](../devices/README.md#ambiguity), #583). The `--host` **flag** with no `<router>` positional
 (`retrieve --host http://192.0.2.10:8080 /system/resource`) is a single target
 too: no CDB lookup, so auth comes from flags, env or config. `CENTRS_HOST` never
 stands in for `<router>`.

package/commands/retrieve/examples.md

@@ -22,7 +22,8 @@ centrs retrieve $R /system/resource --username $U --password $P --json
 ```
 
 Envelope: `ok: true`, `data` is an object, `meta.via=rest-api`,
-`meta.validation.source=/console/inspect`.
+`meta.validation.source=/console/inspect`, and `meta.validation.stages` is the
+one `device: passed` stage (#535).
 
 ### 2. /system/identity
 
@@ -70,6 +71,10 @@ centrs retrieve $R /interface --attributes name,type --username $U --password $P
 
 Envelope: `data` is an array of objects each containing only `name` and `type`.
 
+A single attribute (`--attributes name`) keeps the array shape: an array of
+single-key objects. On a singleton, one item via either flag returns the bare
+value (example 5) — the rule is the count, not the flag.
+
 ### 7. --all-attributes (RouterOS details=true)
 
 ```bash
@@ -121,6 +126,18 @@ available.
 centrs retrieve $R /not/a/real/path --username $U --password $P --json
 ```
 
+`/system/routerboard` earns a targeted remediation instead of the generic
+one: the menu exists only on MikroTik hardware, so its absence on CHR and
+x86 systems is expected rather than a typo, and the remediation points at
+`/system/license` for the device's license ID (`system-id` on CHR,
+`software-id` on x86 — a projected attribute would fail on one platform or
+the other, so the example reads the whole object).
+
+```bash
+centrs retrieve $R /system/routerboard --username $U --password $P --json
+centrs retrieve $R /system/license --username $U --password $P --json
+```
+
 ### 11. Unknown attribute
 
 `validation/unknown-attribute` with suggestions.
@@ -129,6 +146,43 @@ centrs retrieve $R /not/a/real/path --username $U --password $P --json
 centrs retrieve $R /system/resource --attribute bogus --username $U --password $P --json
 ```
 
+## Read paths dispatch only reads (#586)
+
+A read sends only a `print`/`get`, even with `--validate=false`. Covered by
+the CHR test `test/integration/read-path-guard.test.ts` (RP1–RP2, over REST
+and native-api, for `retrieve` and `api`; the router's uptime must never go
+backwards) and the offline grammar and REST-guard tests in
+`test/unit/menu-path.test.ts` (RP3).
+
+### RP1. A `#` or `?` in the path is refused before dispatch
+
+```bash
+centrs retrieve $R '/system/reboot#' --no-validate --attribute uptime --username $U --password $P --json
+centrs api $R '/system/reboot?' --validate=false --attribute uptime --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=input/invalid-routeros-path`,
+`error.context.invalidSegments` names the bad segment, and nothing is sent.
+Before #586 the first line posted `/rest/system/reboot` and rebooted the CHR.
+
+### RP2. A well-formed command path is RouterOS's refusal, not a dispatch
+
+```bash
+centrs retrieve $R /system/reboot --no-validate --username $U --password $P --json
+centrs retrieve $R /system/reset-configuration --no-validate --attribute uptime --username $U --password $P --json
+```
+
+Envelope: `ok: false` with a `routeros/*` code. RouterOS answers
+`<command>/print` and a `GET` of a command with "no such command", so the
+appended `/print` is the guarantee once the path cannot cut it off.
+
+### RP3. Menu-name grammar and the REST URL guard
+
+Path segments are letters, digits and hyphens (case folds:
+`/IP/Address` is accepted). Under every REST caller, a request path with
+`?`, `#`, `\`, a control character or a `.`/`..` segment (including
+`%2e%2e` and `.%2E`) fails `input/invalid-routeros-path` before `fetch`.
+
 ## Transport / error contract
 
 ### 12. Bad credentials
@@ -362,6 +416,10 @@ centrs retrieve $A /interface --attributes name,type --via native-api --port $AP
 
 `data` is an array of objects each containing only `name` and `type`.
 
+A single attribute (`--attributes name`) keeps the array shape here too: an
+array of single-key objects. On a singleton, one item via either flag returns
+the bare value (N5) — the rule is the count, not the flag.
+
 ### N7. `--all-attributes` (native `print detail`)
 
 ```bash
@@ -380,6 +438,14 @@ centrs retrieve $A /system/resource --list-attributes --via native-api --port $A
 centrs retrieve $A /not/a/real/path --via native-api --port $API_PORT --username $U --password $P
 ```
 
+`/system/routerboard` on CHR earns the targeted remediation (no routerboard
+outside MikroTik hardware; read `/system/license` for the license ID
+instead), same as example 10.
+
+```bash
+centrs retrieve $A /system/routerboard --via native-api --port $API_PORT --username $U --password $P
+```
+
 ### N10. Unknown attribute → `validation/unknown-attribute`
 
 ```bash
@@ -792,3 +858,50 @@ centrs retrieve $R /interface --until name=missing --wait 500ms --username $U --
 One envelope goes to stdout, with `stopReason: "deadline-elapsed"`; exit 1.
 No intermediate sample frames are printed. Unit anchors cover slow validation,
 unfinished reads, cancellation and narrow retry classification.
+
+## Record selection (`--match`, #583)
+
+Covered by the named tests `MA1`–`MA3` in `test/integration/cdb-match.test.ts`
+on disposable CHR; MA4 is the offline contract in the `MA4.` tests of
+`test/unit/cdb-match.test.ts`, which drive `retrieve`/`api` through the CLI. `$CDB` holds
+two `ipAdmin` records for the same target `$R`: user `$U` with a deliberately
+wrong password, and a `read`-group user `reader` with its real password.
+The same selector works on `execute`, `api`, `transfer`, `terminal` and
+`btest client`.
+
+### MA1. Two records for one target are ambiguous
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --json
+```
+
+Envelope: `ok: false`, `error.code=identity/ambiguous`, `context.matches`
+lists both records, and the remediation names `--match user=<name>`.
+
+### MA2. `--match user=` picks the record and its credentials
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --match user=reader --json
+centrs execute $R /system/identity/print --cdb-file $CDB --match user=reader --json
+centrs api $R system/identity --cdb-file $CDB --match user=reader --json
+```
+
+Each is `ok: true` with `meta.target.recordIndex=1`. With
+`--match user=$U` instead, each fails `transport/auth-failed`: the decoy's
+wrong password went on the wire, so the selection is real.
+
+### MA3. A selector that matches nothing
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --match user=nobody --json
+```
+
+Envelope: `ok: false`, `error.code=identity/no-match`.
+
+### MA4. `--match` is single-target and never ignored
+
+With a fan-out selection (`--group`, `--where`, `--all`, several
+positionals) or `--quickchr`, `--match` is `usage/conflicting-flags`. When no
+CDB record is in play (no CDB file, an unregistered literal host, a
+`__default__`-only fallback) it is `identity/no-match`, never a silent
+literal-host read.

package/commands/transfer/README.md

@@ -96,7 +96,7 @@ size-aware. Grounding: [Files](https://help.mikrotik.com/docs/spaces/ROS/pages/2
 | `rest` / `native` | rest-api / native-api | small via `/file/get … contents` (**≤ 60 KB**); **large via chunked `/file/read offset chunk-size≤32768`** | **`/file/set contents=` ≤ 60 KB only** — no chunked write |
 | `sftp` (default secure) | ssh | any size | any size |
 | `scp` | ssh | any size | any size |
-| `fetch` *(deferred)* | rest-api/native-api + inbound HTTP | router PUTs to centrs (`upload=yes http-method=put src-path=…`) | router GETs from centrs (`url=http://centrs/… dst-path=…`) |
+| `fetch` *(deferred, upload-only)* | rest-api/native-api + inbound HTTP | chunked `/file/read` (router PUT fails: `only [s]ftp modes support upload`, #548) | router GETs from centrs (`url=http://centrs/… dst-path=…`) |
 | `ftp` *(gated)* | ftp | any size | any size |
 
 Auto-selection (no `--via`):
@@ -118,6 +118,31 @@ past 60 KB) rather than quietly switching to sftp. `scp`, `fetch`, and `ftp` are
 explicit-only; `ftp` additionally requires `ALLOW_UNSAFE_PROTOCOLS=ftp` because
 it is cleartext.
 
+The method resolves `--via` → `CENTRS_TRANSFER_VIA` → the CDB record's `via=`
+preference → config → auto ([constitution: settings](../../docs/CONSTITUTION.md)).
+A record's `via=` names a *transport* (shared with `execute`), so transfer maps
+it to a method (#591):
+
+| CDB / `--via` transport name | Transfer method |
+| --- | --- |
+| `ssh` | `sftp` |
+| `rest-api` (also `--via rest`) | `rest` |
+| `native-api` (also `--via native`) | `native` |
+| `mac-telnet`, `romon`, `winbox-terminal`, `snmp`, `mndp`, `btest` | none — `settings/invalid-via` |
+
+`--via ssh` (and `CENTRS_TRANSFER_VIA=ssh`) is accepted as an alias of
+`sftp`. A record whose `via=` cannot carry files fails `settings/invalid-via`
+naming the record, rather than being ignored; pass `--via sftp|rest|native`
+for that transfer. A record `via=` holds a transport id: method names
+(`sftp`, `rest`, `ftp`) and unknown values are rejected when the record is
+read (`cdb/invalid-option` warning) and leave the method on auto. A record
+preference is a setting, not an auto hop: a `via=rest-api` record uploading
+more than 60 KB fails `transport/unsupported-operation` like a pinned
+`--via rest` does, and the remediation names the record. The endpoint and
+credentials still come from the same record; the mapping never selects a
+different one. A record's `port=` travels with a `--via` pin, so if the
+record's port belongs to another service, point `--port` at the pinned one.
+
 **File contents are bytes on `rest`/`native`.** RouterOS carries `/file`
 contents as raw bytes on both wires — REST puts bytes 0x80–0xff unescaped in the
 JSON string, so the body is not UTF-8 — and stores the UTF-8 encoding of every
@@ -302,6 +327,10 @@ gate as in `retrieve` / `execute`; RouterOS's own menu errors (missing remote
 file, permission denied) map to `routeros/*`, and SFTP/SCP/fetch errors map to
 `transport/*` and `auth/*`.
 
+`meta.validation` reports that existence probe as one `device` stage. `list`
+runs no probe, so it is not a gate: its `meta.validation` is
+`{ enabled: false }`, on success and on failure (#535).
+
 A failure **after** target resolution keeps what resolution found: the error
 envelope carries the resolved `meta.target` (host, port, identity, sources),
 `meta.via`, the setting sources in `meta.settings`, and `meta.operation`
@@ -371,9 +400,9 @@ done rule. The first coded pass targets `rest`/`native` (no SSH dependency);
   (random URL token, bound to the interface facing the router) and drives the
   router with `/tool/fetch` over `rest`/`native`. **upload**: serve the local
   file, `fetch url=http://<advertise>/<token> dst-path=<remote>` → router GETs.
-  **download**: `fetch upload=yes http-method=put url=http://<advertise>/<token>
-  src-path=<remote>` → router PUTs to centrs (`http-method` any since 7.21;
-  binary REST serialization fixed 7.17). Open questions: advertise-host
+  **download** stays on chunked `/file/read`: router PUTs fail with `only
+  [s]ftp modes support upload` (#548), and HTTP `http-data` caps at 60000
+  bytes, so the PUT half cannot carry files. Open questions: advertise-host
   auto-detection behind NAT, HTTP-vs-HTTPS + `check-certificate`, and whether to
   add fetch's `user`/`password` on top of the URL token.
 - **ssh** — `sftp` is **built** (`src/protocols/sftp.ts`, host OpenSSH `sftp`