@tikoci/centrs 0.1.9-next.23 → 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"`.
 
@@ -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
@@ -959,3 +985,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,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

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`):
@@ -302,6 +302,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 +375,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`

package/docs/CLI.md

@@ -15,7 +15,7 @@ implemented flags live in each command's `commands/<name>/README.md`.
 | [`api`](#api) | Structured RouterOS API passthrough (gh-api style) over REST or native API. |
 | [`transfer`](#transfer) | Copy files to/from a RouterOS device and manage device files (rest/native/sftp). |
 | [`terminal`](#terminal) | Open an interactive RouterOS console (ssh or mac-telnet). |
-| [`explain`](#explain) | Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics. |
+| [`explain`](#explain) | Analyze RouterOS input offline or add read-only device evidence from one router. |
 | [`devices`](#devices) | Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB. |
 | [`discover`](#discover) | Discover RouterOS neighbors over MNDP and optionally save them into the CDB. |
 | [`btest`](#btest) | Run MikroTik's bandwidth test as a client or server (peer measurement). |
@@ -220,18 +220,32 @@ Usage: centrs terminal <router> [flags] | centrs terminal --host <host> [flags]
 
 ## explain
 
-Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics.
+Analyze RouterOS input offline or add read-only device evidence from one router.
 
 ```text
-Usage: centrs explain '<input>' [flags]
+Usage: centrs explain [<router>] '<input>' [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
+| `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<router>` it is the target (no CDB lookup); with one it overrides the resolved host. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username. Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--insecure` |  | Accept a self-signed `api-ssl`/REST TLS cert. Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--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). |
+| `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
+| `-p` | `<secret>` | Alias for --password. |
+| `--quickchr` | `<name>` | Resolve one running quickchr VM by name. |
 | `--file` | `<path>` | Read the input from a file instead of the positional (`-` reads stdin). Piped stdin is used automatically when no input positional is given. |
 | `--fail-on` | &lt;error\|warning\|never&gt; | Exit 2 when the verdict reaches this severity. Default `error`; an ambiguous or unknown statement is a warning, never an error. |
-| `--complete` |  | Continuation candidates at the cursor. Live evidence — offline emits a tip and enumerates nothing. |
-| `--schema` |  | Path enumeration (verbs, args, types, enums). Live evidence — offline emits a tip and enumerates nothing. |
+| `--complete` |  | Candidates at the cursor: menus and verbs, argument names, or values. Live evidence — offline emits a tip and enumerates nothing. |
+| `--schema` |  | Describe the path at the cursor: a menu's verbs and submenus, a command's arguments, `print`'s proplist. Live evidence — offline emits a tip and enumerates nothing. |
+| `--cursor` | `<byte>` | UTF-8 byte offset for --complete/--schema. Default: the end of the input. |
+| `--full` |  | Lift --complete/--schema sizing to its safety ceiling (1024 names, 128 expansion probes). |
 | `--curl` |  | Render a ready-to-edit REST curl for statements covered by a runtime-tested mapping rule. |
 | `--tokens` |  | Emit the total, gapless token partition behind `data.tokens[]` (every byte not claimed by an analyzer is `unclassified`). |
 | `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |

package/docs/CONSTITUTION.md

@@ -73,15 +73,20 @@ gate passed keeps `passed`. When something stopped the gate before it gave a
 verdict (a `transport/*` or `auth/*` failure, a device error that is not a
 gate answer, or a refusal before the gate ran), `result` and the
 `syntax`/`semantic` summaries are absent. Each stage the gate did not reach is
-then `skipped` with `reason: "not reached: <error.code>"` (GH#435). On an
-`execute` rejection, `syntax: true` survives only for a name-level refusal (an
-unknown attribute in a structured command). Any other device or offline
-refusal is `syntax: false`, and `semantic` is then absent (`not-applicable` for
-script input), because the name-level check was never asked. `api`'s
-structured requests run no `:parse`, so their `syntax: false` means "not run",
-even on success. That overload is part of the review below. This is an
-interim shape: the validation meta across commands is reviewed again with live
-`explain` (#236).
+then `skipped` with `reason: "not reached: <error.code>"` (GH#435).
+
+The flat `syntax` / `semantic` fields summarize `stages[]`, and each is present
+**only when a stage gave that verdict** (#535). Absent means no stage was
+asked, never "passed" and never "failed". So `--validate=false` carries
+neither. A script has no `semantic` field, because it has no names to check,
+and `api`'s structured requests have no `syntax` field, because they run no
+`:parse`. On a rejection, `syntax: true` with `semantic: false` is a
+name-level refusal (an unknown attribute in a structured command). A `:parse`
+or offline refusal is `syntax: false` with no `semantic`. Every gated success
+reports its `stages[]`, retrieve and transfer included. `explain` is not a
+gate, because it never runs the input: its `meta.validation` is
+`{ enabled: false }` with no `result`, offline and live, and its verdict is
+`data.verdict`.
 
 `--validate=false` disables **both** stages — one flag, one meaning. A bypass
 that covered only the device stage would leave a caller stranded behind a

package/docs/MATRIX.md

@@ -40,7 +40,7 @@ their command-specific evidence contracts.
 | devices  | —             | —             | —             | —             | —             | —             | —             | —                |
 | discover | —             | —             | —             | —             | —             | `CHR-passed`  | —             | —                |
 | check    | `designed`    | `designed`    | `designed`    | `designed`    | `not-started` | `not-started` | `not-started` | `not-started`    |
-| explain  | `designed`    | `designed`    | —             | —             | —             | —             | —             | —                |
+| explain  | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —             | —                |
 | settings | —             | —             | —             | —             | —             | —             | —             | —                |
 
 ## Status pointers
@@ -101,10 +101,14 @@ and implementation sequencing in the linked issues.
   `winbox-terminal` stay `not-started`. Its per-host fan-out is the machinery the
   IP-scan discovery (#149) will iterate; the L2-default timing evidence (#136) is
   recorded in the README before the cells advance past `designed`.
-- `explain`'s two `designed` protocol cells are the future live probes
-  (`/console/inspect` + `:parse`, #236). The live grammar
-  (`explain <router> '<input>'`) is parsed and refused with
-  `usage/not-implemented`, never degraded to an offline run. Offline analysis
+- `explain`'s two `CHR-passed` protocol cells are the whole live capability
+  (#236). `explain <router> '<input>'` collects read-only `:parse`, highlight
+  and child argument-name evidence (#491), and `--schema`/`--complete` describe
+  paths and complete at a cursor (#492). Live value types (#225) fill
+  `observedType` from visible `:parse` conversions and `schemaType` from
+  argument `syntax`. Examples 7–16, 19, 24, 48 and 52–53 pass on REST and
+  native API in `test/integration/explain-live*.test.ts`, on stable 7.24.5 and
+  long-term 7.23.8. `runtimeAcceptance` stays `not-proven`. Offline analysis
   has its own capability entry below. The generated structure tables
   `src/explain/menus.ts` and `src/explain/catalog.ts` keep analysis offline;
   their ownership and regeneration contracts live in `commands/explain/README.md`.
@@ -182,16 +186,25 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
+Live `explain` (#236) is `CHR-passed` on REST and native API: the #491
+foundation, #492's describe and completion facets, and #225's live value types,
+with every applicable example green on stable and long-term CHR. Issue #90
+owns the remaining sequencing, including #507 context grounding.
+
 **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
+published offline readings honest (#350, #211; complete), give the result a
+statement tree (#497; complete), then the live probe foundation (#491;
+complete). Those probes grounded #351, #358 and #371 (complete), #492
+added the describe/completion facets, and #225 the live value types. The
+closeout of #236 promoted both live cells (complete). 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
+**The CMR track is paused** (maintainer decision 2026-10-16; held for the
+7.26beta caller-policy fix — #527 now carries direct 7.26beta3 evidence that a
+restricted caller is refused, with the first refusing release still
+unbracketed). 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
@@ -222,11 +235,11 @@ order agreed on [#236](https://github.com/tikoci/centrs/issues/236):
 2. **Done** — front the `execute` / `api` device preflight with the offline
    analyzer (#354). The gate is now two-stage; the contract is in
    [`docs/CONSTITUTION.md` → Validation is the product](CONSTITUTION.md#validation-is-the-product).
-3. **Next** — **live `explain` (#236)**, as stage two of a gate that now exists.
-   Start with [the #90 task index](https://github.com/tikoci/centrs/issues/90),
-   then follow [`commands/explain/README.md`](../commands/explain/README.md) and
-   the live examples in
-   [`commands/explain/examples.md`](../commands/explain/examples.md).
+3. **Done** — **live `explain` (#236)**, as stage two of a gate that now exists.
+   The contract is [`commands/explain/README.md`](../commands/explain/README.md)
+   and the live examples in
+   [`commands/explain/examples.md`](../commands/explain/examples.md);
+   [#90](https://github.com/tikoci/centrs/issues/90) indexes what follows.
 
 The offline baseline stays `verified`: #264 closed the measured token vocabulary
 and #322 closed the final bounded-execution gap, including the public depth-axis
@@ -235,17 +248,17 @@ guard.
 The live pass is the device-backed cross-check on the offline result, not a
 replacement for it. It adds read-only `/console/inspect` and `:parse` evidence,
 the describe/completion facets, and the live `observedType`/`schemaType`
-producers owned with #225. REST and native-api cells advance only when their
+producers (#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 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, #342 and #498 are complete: the
+non-authoritative `.scratch/` citation cleanup. Issues #350 (the broad
+optional `=`), #351 (a relative submenu brace read as a command operand)
+and #355 (`'` is not a RouterOS token) are complete. A submenu block after a navigation statement
+(`/ip⏎address { … }`) keeps the pre-#351 reading; see
+`commands/explain/README.md`. #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