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

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"`.
 
@@ -483,7 +507,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 +725,387 @@ 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, 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
+`/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.
+
+### 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,8 +87,11 @@ 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.
@@ -147,6 +150,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

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.
@@ -362,6 +379,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 +401,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