@tikoci/centrs 0.1.3 → 0.1.6

package/GLOSSARY.txt

@@ -93,9 +93,12 @@ cwd
 datagram
 davidanson
 DDNS
+dialable # an endpoint a client can actually connect to (advertised AND reachable)
 defconf
 demux
 demuxes
+desync # a highlight stream whose token count != input length, so classes line up against the wrong characters
+desynced
 dogtail
 donny
 dotenv
@@ -125,6 +128,8 @@ keystream
 KSA
 KVM
 LDTP
+LFS # Git Large File Storage. The pinned corpus blob is NOT stored through it,
+    # which is why a plain raw.githubusercontent GET returns the real bytes.
 librouteros # <https://github.com/haakonnessjoen/librouteros-api>
 LLDP
 lsp-routeros-ts
@@ -144,10 +149,12 @@ npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
 PII # Personally Identifiable Information
+PON # passive optical network; RouterOS /interface/ethernet/pon menu
 POV
 PRGA
 proplist
 pywinauto
+QKD # quantum key distribution; RouterOS IPsec/keymat-provider vocabulary
 QML
 qll # CodeQL library file extension (.qll), e.g. CleartextLoggingCustomizations.qll
 qmljsdebugger
@@ -163,6 +170,7 @@ rosetta
 routeros
 routeros-skills
 rsc # RouterOS script / export file extension (.rsc)
+rstp # Rapid Spanning Tree Protocol; a RouterOS `protocol-mode=` value on /interface/bridge
 SARIF # Static Analysis Results Interchange Format; CodeQL's code-scanning analysis download format
 scp
 scriptability
@@ -206,6 +214,7 @@ webproxy
 WinAppDriver
 winbox
 Wireshark
+workstream
 workstreams
 XCUI
 XDG
@@ -269,6 +278,9 @@ choco
 coderabbit
 coderabbitai
 
+# GitHub account Codex review threads are authored under (see pr-review-bots).
+mobileskyfi
+
 # centrs domain vocabulary
 # %identity: the device /system/identity; a centrs CDB comment *lookup key*
 #   (`identity=`) used to resolve `<router>`. Human handle, deliberately may
@@ -370,6 +382,20 @@ CSI
 SIGWINCH
 # evl: RouterOS :parse renders a parsed command as "(evl ...)" on the console.
 evl
+# putmessage/globalname: RouterOS :parse IL statement heads — ":put x" echoes back
+# as "(evl /putmessage=x)", ":global n v" as "(evl /globalname=$n;value=v)" (GH#230).
+putmessage
+globalname
+# localname/setnote/runnumber: more of the same head rendering, quoted verbatim as
+# evidence for the missing-separator rule (GH#311). ":put [:parse …]" joins the IL
+# array with NO separator, so the path and its first argument run together —
+# ":local a v" is "(evl /localname=$a;value=v)", "/system/note set note=hello" is
+# "(evl /system/note/setnote=hello)", "/system/script/run /ip/route" is
+# "(evl /system/script/runnumber=/ip/route)". Artefacts of the rendering, not
+# RouterOS argument names; kept unsplit because the quote must match the bytes.
+localname
+setnote
+runnumber
 # unconfigured: a freshly-flashed RouterOS device with no IP — the mac-telnet use case.
 unconfigured
 unwired
@@ -397,6 +423,7 @@ Weierstrass
 # ndjson: newline-delimited JSON; the stream / btest output contract (one envelope per line).
 ndjson
 # allocate-udp-ports-from: /tool/bandwidth-server base of the UDP data-port range.
+allocate-udp-ports-from
 # srp5: the "5" suffix of EC-SRP5 (the MikroTik EC-SRP variant).
 srp5
 # SRV: the server-endpoint test variable in commands/btest/examples.md.
@@ -505,3 +532,228 @@ sfo
 ele
 GPX
 Geolocation
+unparseable
+Unparseable
+versionless
+
+# explain canonicalizer (phase-0 lab #185, commands/explain) vocabulary.
+#   SUT: "system under test" — the phase-0 lab's throwaway parser, scored
+#   against a `:parse` IL / highlight oracle; the ratified behavior is what the
+#   production modules under src/explain promote. CJK: the Chinese/Japanese/
+#   Korean Unicode range, used as a non-ASCII coordinate/segmentation fixture.
+#   pathresolve / blocktree: the Q3-Q4 / Q2 lab probe names, carried into the
+#   src/explain module + fixture names. klass: `class` is reserved, so the
+#   resolution feature-class field is `klass`. tostr / tostrvalue: the RouterOS
+#   `:tostr` directive and its IL-lowered form `/tostrvalue`. eworm: a corpus
+#   script author (eworm/*.rsc) cited as grounding for scope-name findings.
+#   rextended: another corpus script author, cited for the Q14 nested-bracket
+#   ambient-context case (a user function establishes no menu). ppp: the RouterOS
+#   /ppp menu, in the Q14 corner proving a `$` inside a `~` FILTER argument does
+#   not make the menu unreadable. strfind: a corpus user function in that corner.
+#   verbsplit: the Q6 verb/menu-boundary lab probe name, carried into the
+#   src/explain module + fixture names. myvar: the RouterOS example variable in
+#   the Q6 `:global myvar` collision corner (a positional operand indistinguishable
+#   from a sub-menu offline).
+#   failclosed: the ratified Q16 navigation arm name (the two arms that priced it
+#   stayed in the lab). notadirective: the Q16 fixture's deliberately unseen root
+#   directive, pinning that an unknown directive abstains rather than reading as
+#   harmless control flow.
+#   RouterOS root cmds (scripting directives) enumerated from /console/inspect and
+#   frozen in src/explain/write.ts as the closed ROOT_CMDS vocabulary — jobname,
+#   rndnum, rndstr, tobool, tocrlf, toid, toip, tolf, tonsec, tonum, totime.
+#   lte: the RouterOS /interface lte menu, cited in the Q16 long-tail-verb corner.
+#   dyn: the `$dyn` variable in the Q14 cascade corners — a dynamic-headed
+#   statement, which is context-NEUTRAL and must not poison the menu context.
+#   symbols (Q13): cls — the resolved variable-class field on a symbol occurrence
+#   (`class` is reserved, same reason as klass). sigilled: written with the `$`
+#   sigil, the schema-free tell that separates a variable from a directive or a
+#   menu-path segment. ERRVAR: the `:onerror NAME` error-variable slot (S18).
+#   unmodeled / distinguisher: the closure-scope finding — the lab left the rule
+#   unmodeled because a depth counter has no scope identity, and the statement
+#   head is the only distinguisher between a function `do={}` and a control-flow
+#   one. Corner variable names quoted from the device probes and corpus scripts:
+#   vlanid, vlanbytes, ipprefix, octive (the `$octive-1` name-vs-operator case),
+#   lppp (the device documentation's own `variable-undefined` example).
+#   lookback: the backward scan that decides whether a `{` follows `do=`; it must
+#   accept exactly the escapes the forward walker does, or the two disagree about
+#   where the argument name ends and a function body stops being a closure.
+#   tangentsoft: the maintainer/site (tangentsoft.com/mikrotik) behind the third
+#   corpus collection — 35 genuine `/export show-sensitive terse` device captures
+#   imported for the #203 genre census, and the corpus's only wholly-terse
+#   export stratum.
+SUT
+CJK
+parseil # lsp-routeros-ts corpus table of captured `:parse` IL, per script per RouterOS version
+pathresolve
+blocktree
+klass
+tostr
+tostrvalue
+eworm
+rextended
+tangentsoft
+ppp
+strfind
+verbsplit
+myvar
+failclosed
+notadirective
+jobname
+rndnum
+rndstr
+tobool
+tocrlf
+toid
+toip
+tolf
+tonsec
+tonum
+totime
+lte
+dyn
+cls
+sigilled
+ERRVAR
+unmodeled
+distinguisher
+vlanid
+vlanbytes
+ipprefix
+octive
+lppp
+lookback
+
+# RouterOS menu vocabulary reached by the explain menu table (#207).
+# The generated table itself (src/explain/menus.ts) is cspell-ignored; these are
+# the terms that also appear in hand-written prose and tests.
+# %cliref: docs-derived RouterOS command reference in rosetta
+#   (experiments/cliref.db). A second opinion on node types, NOT a source for
+#   the menu table: its paths interleave the docs slug with the CLI path.
+cliref
+hotspot
+igmp
+ipfix
+keymat
+pmp
+pptp
+sstp
+wlan
+zerotier
+cuu # `/terminal cuu` (cursor up) — a RouterOS command that reads as a bare menu path, so the table refuses it (#210)
+
+# Hardware-gated RouterOS surfaces named when explaining why a published path is
+# absent from a CHR-derived inspect tree (#228). No CHR carries these.
+FDB # forwarding database — `/interface/ethernet/switch/{unicast,multicast,reserved}-fdb`, switch-chip only
+MSRP # Stream Reservation Protocol (TSN) — `/interface/bridge/msrp`, gated by `conditions: MSRP_ENABLE`
+PTP # Precision Time Protocol — `/system/ptp`, gated by `syscap: ptp`
+syscap # a CLI-Reference applicability gate naming the hardware/system capability a path requires (`poe`, `lcd`, `multiswitch`, `nochr`)
+
+# explain ANALYSIS/ORACLE vocabulary — not RouterOS menu names. These name the
+# lab's measurement machinery and the properties it measures, and belong apart
+# from the menu block above even though both arrived with the explain work.
+importability # whether a document RouterOS emitted can be re-imported (#203 oracle level L2)
+menuctx # the IL (`:parse`) statement type for menu navigation, as against `cmd` — the native nav-vs-command oracle (#210)
+
+# #202c-1 argument-lexer vocabulary: one analysis term, plus the RouterOS names
+# that appear verbatim in the corpus lines `test/unit/explain-args.test.ts`
+# fixtures. The corpus lines are real forum scripts and are quoted rather than
+# paraphrased, so their spellings are data, not prose.
+renderable # of a statement: covered by a tested REST mapping rule, so `--curl` may render it (#202c-2)
+wifiwave # `/interface wifiwave2` — the pre-7.13 RouterOS wifi menu, renamed `wifi` (drift the corpus carries)
+nomaster # from a corpus line where two arguments ran together (`disabled=nomaster-interface=wifi1`); pinned as the first-`=`-splits case
+CAINFO # `AT#CAINFO?` — an LTE modem AT command in a corpus `/interface/lte/at-chat` line
+vzwinternet # Verizon LTE APN name, from a corpus `/interface lte apn add` line
+rtr # short device name in an explain test input
+
+
+# #228 path-catalog vocabulary: the CLI-Reference definition-module segments the
+# alias allowlist maps away, the published gate values, and the prose terms used
+# to describe the union. The generated table itself is cspell-ignored.
+chancfg # caps-man definition module for `/caps-man/channel` — a doc spelling, not a CLI path
+dpathcfg # caps-man definition module for `/caps-man/datapath`
+ifaceactual # caps-man definition module for `/caps-man/actual-interface-configuration`
+ratescfg # caps-man definition module for `/caps-man/rates`
+remoteap # caps-man definition module for `/caps-man/remote-cap`
+seccfg # caps-man definition module for `/caps-man/security`
+ifaces # CLI-Reference definition module for `/tool/graphing/interface`
+datapath # `/caps-man/datapath` — the real CLI menu behind `dpathcfg`
+easymesh # `/interface/wifi/easymesh` — the doc spelling of `/interface/wifi/wps-push-button`
+wps # Wi-Fi Protected Setup — `/interface/wifi/wps-push-button`
+qos # switch-chip quality of service — `/interface/ethernet/switch/qos`, a real menu segment R1 must never drop
+qca # Qualcomm Atheros — the `wireless-qca` package gate
+multiswitch # syscap gate: more than one switch chip
+oldswitch # syscap gate: the pre-Prestera switch-chip menu shape
+smips # RouterOS architecture (single-core MIPS), named in `conditions:` gates
+mmips # RouterOS architecture (multi-core MIPS), named in `conditions:` gates
+CRS # MikroTik Cloud Router Switch — carries the switch-chip menus no CHR has
+CCR # MikroTik Cloud Core Router
+superlinear # growth faster than linear, used for resolveDocument wall-clock on separator-free input (#248)
+superlinearity # the property a growth-ratio guard bounds; `superlinear+` is NOT usable here, cspell's compound form forbids the bare word (#313)
+stmts # `explainCommand` corpus measurement: statement count (shorthand for `statements`)
+argCandidates # `explainCommand` corpus measurement: arg-bearing candidates
+argReadable # `explainCommand` corpus measurement: readable statements
+ungated # of a published path: carrying no package/conditions/syscap that would explain its absence from a tree
+unioned # of the two sources: merged with per-entry provenance rather than flattened
+unioning # the act of the above
+greppable # of a generated table: one entry per line, so `grep` finds a path
+apos # the `&apos;` XML entity, decoded by the CLI-Reference parser
+
+# #285 CLI-Reference reshape vocabulary: the second published inventory, and the
+# gate values on the paths that publish twice.
+llms # `llms.txt` — MikroTik's published page inventory; the only one listing the `<dir>/<basename>` leaf a branching menu's own entry lives on, so discovery is the union of it and the sitemap
+musicswitch # syscap gate: the Marvell-era switch-chip menu shape — one half of the `/interface/ethernet/switch` pair published under two gates
+rbswitch # syscap gate: the RouterBOARD switch-chip menu shape — the other half of that pair
+prestera # Marvell Prestera switch chip — named in the `crs_prestera` syscap gate on `/interface/ethernet/switch/qos`
+xfrm # `/interface/xfrm` — the IPsec transform interface, device-confirmed by the pinned 7.25beta3 trees and published by the CLI Reference
+btrfs # the Linux B-tree filesystem, a `/disk/btrfs/...` menu on RouterOS 7.20+
+
+# #255 operator-axis vocabulary: the device-grounded operator surface.
+arities # plural of arity — the operand counts an operator accepted, which is what separates `(> 1)` (deferred expression) from `(2 > 1)` (comparison)
+typeofvalue # RouterOS IL renders `[:typeof $x]` as `/typeofvalue=$x` — the directive and its argument name run together with no separator
+juxt # short for juxtaposition — the unnamed ` (  a b)` node RouterOS builds for space-separated paren contents; used in ids like `any-juxt`
+punct # short for punctuation — the shape class for a candidate spelling made of symbol bytes, as opposed to a word; used in the `bogus-punct` control id
+gapless # of a token partition: every byte in [0, input.bytes) belongs to exactly one token, sorted by start, no gaps (#289 B1)
+SCIP # Source Code Intelligence Protocol — the symbol-identity axis for `data.tokens[]`'s later vocabulary (#264 B5)
+unclassified # the provisional token class for a byte no analyzer claims; a first-class answer in the gapless partition (#289 B1)
+
+# #290 B2 operator-fill test vocabulary
+xand
+andx
+alnum
+wpa # `security.authentication-types=wpa2-psk` — a wifi argument name whose interior dot the operator fill must not read as concatenation
+psk # pre-shared key — the value half of the same grounded `wpa2-psk` example
+
+# #293 B2 arg-fill vocabulary
+retag # B5 may retag the `=` separator from the provisional `arg` class without moving byte coverage
+
+# #239 S2 flow-sensitive symbol→value
+occ # short for occurrence — local variable in symbol-values flow analysis
+vid # short for valueId — result-local value occurrence identifier (v0, v1)
+idx # short for index — loop/event index in flow merging
+mis # prefix in mis-linking — hyphenated in comments for symbol-values guard
+
+# #313 offline performance vocabulary
+JIT # just-in-time compiler — warmed before either half of the growth-ratio timing so the two sizes are compared in the same compilation state
+
+# #317 statement-ownership index vocabulary
+laminarity # the property of a set of spans in which every pair is nested or disjoint, never crossing — what makes the shortest containing span reachable by a parent walk
+
+# #264 B4 / #263 device-agreement vocabulary
+unprojected # of a byte whose offline/device class PAIR the declared projection does not cover, so it can neither agree nor disagree: an offline class that deliberately maps to no RouterOS `highlight` class, or a device class this build has never seen (#264 B4)
+
+# #324 / #325 offline-reading vocabulary. Both words are corpus data: they are
+# quoted from the two slice scripts the device-agreement report names as the
+# exemplars of the cells these fixes empty, so their spellings must match the
+# bytes the device saw.
+ytkids # an address-list name in the corpus line `/ip/firewall/address-list name=ytkids timeout=1h` — the #324 exemplar
+apikey # a local variable in the corpus line `apikey-len=$([:len $apikey])` — the `$(…)` interpolation #325 deliberately leaves unreached
+
+# #312 offline-entry boundary vocabulary
+dgram # Node's `node:dgram` UDP socket module — reached by `mac-telnet`, and one of the builtins that made the old `explain` import graph unusable outside Bun; named in the boundary gate's allowlist rationale
+
+# #347 / #348 offline false-reject controls. Both words are deliberate
+# NON-words: each is the rejected half of a CHR-confirmed accepted/rejected
+# pair, so its spelling is load-bearing and must not be "corrected".
+elsy # the misspelled `else` in `:if (1=1) do={…} elsy {…}` — rejected as `expected end of command` on CHR 7.21.5/7.23.5/7.24.2/7.25beta3, which is what proves the bare-brace `else {` acceptance is a real device fact and not a probe artifact (#347)
+prnt # a misspelt `print` verb — `/ip/address/prnt` is the offline analyzer's ABSTENTION fixture (`verdict: warn`, not `fail`), which is what proves the two-stage validation gate passes an abstention through to the device rather than refusing it (#354)
+zzznotamenu # a menu name no RouterOS build has — `/ip { zzznotamenu { print } }` is a `syntax error` on device, so menu-scope resolution is schema-dependent and a catalog MISS must abstain rather than accept (#348)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TIKOCI GitHub Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,12 +4,21 @@
 CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
 RouterOS devices through a regularized, validated interface.
 
-Preview builds are published on npm. To inspect the CLI without installing it:
+Preview builds are published on npm. To try the current offline analyzer without
+installing centrs or connecting to a router:
 
 ```bash
-bunx @tikoci/centrs --help
+bunx @tikoci/centrs@next explain '/ip/address print' --json
 ```
 
+Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI. The
+explicit `@next` matters: `0.1.x` preview releases do not move npm's `latest`
+tag.
+
+The full flag reference for every command is generated from the CLI metadata
+into [`docs/CLI.md`](docs/CLI.md); per-command behavior lives in
+`commands/<name>/README.md`.
+
 It is a **friendly conduit**, not a high-level configuration abstraction. It
 helps humans and agents reach RouterOS over the right protocol, with the right
 credentials and ports, and validates RouterOS-shaped commands before running
@@ -17,9 +26,12 @@ them. It does **not** hide RouterOS behind helpers like `createVlanOnBridge()`
 — you still speak RouterOS. Validation and structured diagnostics are the
 product; without them this would just be a worse `curl`.
 
-> **Status:** early npm preview, active development. `@tikoci/centrs` is
-> published on npm, but command flags and envelopes may still change before a
-> stable release. Check current dist-tags with
+> **Status:** early npm preview under active development. It is not
+> production-ready: expect bugs and breaking changes before 1.0, and exercise
+> router-writing workflows on lab or disposable targets first. Offline
+> `explain` does not contact a router, but its analysis is intentionally
+> conservative and never proves that RouterOS will accept a command at runtime.
+> Check current dist-tags with
 > `npm view @tikoci/centrs dist-tags --json`. The library, device registry, and
 > first MCP server phases are CHR-verified; the CLI is wired (`coded`);
 > encrypted-CDB writes are still blocked, and the TUI/proxy frontends are planned.
@@ -35,8 +47,10 @@ product; without them this would just be a worse `curl`.
   SSH / MAC-Telnet / RoMON / WinBox Terminal for interactive and L2 execute;
   MNDP for discovery. centrs picks the protocol for you (and lets you pin one
   with `via=` or `--via`).
-- **Commands:** every command resolves a *target* — a router you name on the
-  CLI — to a real address, credentials, and a protocol, then runs.
+- **Commands:** every router-facing command resolves a *target* — a router you
+  name on the CLI — to a real address, credentials, and a protocol, then runs.
+  (Local commands — `devices`, `settings`, `discover`, and `explain`'s offline
+  mode — need no router.)
 
 | Command    | Purpose |
 | ---------- | ------- |
@@ -45,6 +59,7 @@ product; without them this would just be a worse `curl`.
 | `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Open-ended follow is `api … --stream` (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
 | `check`    | Probe reachability and management protocol availability. |
+| `explain`  | Analyze a RouterOS command before running it: canonical form, syntax diagnostics, and what is valid at a path. Offline analysis runs today; the live-device probes are designed. |
 | `devices`  | View and maintain the CDB-backed device registry (the only writer). |
 | `discover` | Discover MNDP neighbors and optionally save them into the CDB. |
 | `settings` | Manage centrs's own settings (`centrs.env`, `__default__`) and run first-time setup. |
@@ -163,7 +178,9 @@ and the comment grammar — lives in `commands/devices/README.md` and
 
 The load-bearing contract — envelope shape, error model, protocol selection,
 settings precedence, and the "done" definition — lives in
-`docs/CONSTITUTION.md`. The command×protocol status grid is `docs/MATRIX.md`.
+`docs/CONSTITUTION.md`. Capability status and the selected work track,
+including the command×protocol grid and offline analysis, live in
+`docs/MATRIX.md`.
 
 ## Repository layout
 
@@ -172,19 +189,21 @@ code and authority docs live.
 
 - **`docs/CONSTITUTION.md`** — load-bearing rules (validation, envelope, error
   model, settings precedence, identity/CDB, protocol selection, done).
-- **`docs/MATRIX.md`** — command×protocol grid; the only status surface.
+- **`docs/MATRIX.md`** — capability status and the selected work track (the
+  command×protocol grid plus offline analysis and frontend surfaces); the
+  only status surface.
 - **`commands/<name>/`** — per-command README and executable examples.
 - **`src/`** — Bun/TypeScript source.
 - **`test/`** — unit and CHR-backed integration tests.
 
-There is no `docs/specs/`, no `work/`, no roadmap doc. The matrix is the
-roadmap.
+There is no `docs/specs/`, no `work/`, no roadmap doc. The matrix and the
+GitHub issues it links are the roadmap.
 
 ## Development
 
 Requirements:
 
-- Bun 1.3.11 or newer (CI pinned to 1.3.13; Bun 2.x not yet validated).
+- Bun 1.3.11 or newer (CI pinned to 1.3.14; Bun 2.x not yet validated).
 - Git.
 - For integration tests: QEMU plus `@tikoci/quickchr` (handles CHR image
   download and boot).
@@ -204,6 +223,19 @@ Generated API docs through TypeDoc:
 bun run build:doc:api
 ```
 
+The `explain` censuses measure a RouterOS script corpus that lives in
+[`tikoci/lsp-routeros-ts`](https://github.com/tikoci/lsp-routeros-ts), not in
+this repo. `scripts/corpus-pin.json` records which snapshot centrs measures
+against — a commit plus the blob's sha256 — and `corpus:fetch` downloads and
+verifies it. A sibling `lsp-routeros-ts` checkout is used when present, and the
+censuses print the source and hash they used:
+
+```bash
+bun run corpus:fetch          # download the pinned snapshot, verify its sha256
+bun run explain:corpus-census # genre census (#203)
+bun run explain:value-census  # value-surface census (#225)
+```
+
 ## Done definition (short version)
 
 A feature is done when every line in `commands/<name>/examples.md` is green on

package/commands/AGENTS.md

@@ -3,9 +3,16 @@
 Each `commands/<name>/` holds the **executable spec** for one command:
 
 - `README.md` — intent, flags, behavior. The "designed" tier.
-- `examples.md` — numbered, runnable examples. Each example is one assertion in
-  the matching `test/integration/<name>.test.ts`; example N ↔ assertion N. This
-  is what `CHR-passed` is measured against.
+- `examples.md` — numbered, runnable examples mapped to named tests:
+  example N ↔ named test N. Live examples require CHR integration; offline
+  examples use the unit/fixture tests named by the command — a named test may
+  carry several assertions. Verification follows `docs/CONSTITUTION.md` →
+  Done definition.
+
+**Implemented** flags are generated from `CliCommandMetadata` into
+`docs/CLI.md` (`bun run docs:cli`; drift-gated in CI) — a command README keeps
+behavior prose plus a "Designed, not implemented" table for spec-only flags,
+never a duplicate table of implemented flags.
 
 Do not restate the constitution here or in a command README — link to
 `docs/CONSTITUTION.md` for envelope, errors, settings precedence, target
@@ -14,12 +21,14 @@ keys, ambiguity, `__default__`, comment-kv allowlist, write strategy) lives in
 `commands/devices/README.md` — the registry command owns it; the constitution
 keeps only the identity/CDB principle. A command file covers only what is
 specific to that command. `docs/MATRIX.md` is the only status surface; a
-README's "Status" line must agree with it.
+README's "Status" line must agree with it. GitHub issues track the tasks and
+dependencies within the selected capability; they do not replace its status.
 
 ## Verb vocabulary
 
 Commands are centrs **verbs** (`retrieve`, `execute`, `api`, `devices`,
-`discover`, `check`, `terminal`, `settings`), never one tool per RouterOS command. Open-ended follow
+`discover`, `check`, `explain`, `terminal`, `settings`), never one tool per
+RouterOS command. Open-ended follow
 is folded into `api --stream` (no separate `stream` verb). Sub-verbs and their
 aliases are canonical across CLI / API / MCP:
 

package/commands/api/AGENTS.md

@@ -183,11 +183,23 @@ green on CHR 7.23.1.
   not `print`/`get`), so it is a `POST` and **write-classed** → needs `--yes`.
 - **CONFIRMED — the inspect gate over both transports.** Path existence
   (`request=child` empty ⇒ `validation/unknown-path`) and add/set attribute
-  validity (`request=child`+`completion` ⇒ `validation/unknown-attribute`) fire
+  validity (`request=child` ⇒ `validation/unknown-attribute`) fire
   identically over rest-api and native-api, **before** any write — no `:put
   [:parse]` involved (api input is a path, not a CLI string). A `/execute` script
   is a CLI string ⇒ `meta.validation.semantic = "not-applicable"`.
 
+## CONFIRMED ON CHR (RouterOS 7.12.2 compatibility — GH#343, 2026-09-14)
+
+- **Command-level `request=completion` is unsafe on 7.12.2.** For
+  `path=system,identity,print`, REST did not answer before the 10 s client
+  timeout and native API closed the connection immediately. Adding
+  `.proplist=completion` did not change either result. The preceding `:parse`
+  and `request=child` controls returned in 1–8 ms on both transports, and
+  `child` contained the complete command argument list. Execute/API attribute
+  validation therefore uses command-level `request=child` only. This does not
+  prohibit argument-level completion probes such as `print,proplist`, which are
+  a separate shape and returned immediately on the same 7.12.2 controls.
+
 ## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
 
 Validated by `test/integration/api-listen.test.ts` (L1–L4) on CHR 7.23.1.

package/commands/api/README.md

@@ -57,24 +57,25 @@ when a bare-collection `POST` carries create-looking fields.
 
 ## Flags
 
-| Flag | Behavior |
-| ---- | -------- |
-| `-X` / `--method <verb>` | HTTP method, default `GET`, case-insensitive. |
-| `-f <key=value>` | String field, repeatable; assembled into the JSON body. Values pass through verbatim (no type-guessing). |
-| `-d` / `--data <json>` | Raw JSON request body. Collides with `-f` → `usage/conflicting-flags`. |
-| `--input <file\|->` | Read the raw JSON body from a file or stdin (`-`). |
-| `--query` / `--filter <expr>` | RouterOS-side row filter, AND-combined, repeatable. `name=value` (eq), `name!=value` (ne), `name>value`/`name<value` (cmp), `name` (has-property). Maps to REST `.query` words / native `?` words. |
-| `--raw-query <word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions — e.g. `--raw-query type=ether --raw-query type=vlan --raw-query '#\|'` (OR). Emitted as-is; the caller owns the stack. |
-| `--attribute` / `--proplist <a,b>` | Property projection → `.proplist`. |
-| `--raw` | Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does **not** imply `--yes`. |
-| `--yes` | Confirm a mutating (non-read) request in non-interactive runs. |
-| `--stream` (alias `--listen`) | Native-api-only open-ended follow → NDJSON stream of envelopes, ending with a summary envelope. Inferred from a `/listen` endpoint. `--via rest-api --stream` errors `transport/capability-unsupported` (REST's 60 s cap cannot follow). |
-| `--duration <dur>` / `--count <n>` | Bound a `--stream`: stop after a wall-clock window / after N frames. |
-| `--validate[=false]` | Default `true`. Gate is `/console/inspect` (see Validation). |
-| `--via <protocol>` | `rest-api` (default) or `native-api`. No silent downgrade. |
-| `--format <json\|yaml\|text>` | Output format. Defaults to `json` for `api` (machine-first); `CENTRS_FORMAT` overrides. Under `--stream`, `json`/`yaml` emit one compact envelope per line (NDJSON); `text` emits a concise row per frame. |
-| `--group <name>` / `--where <attr>=<value>` / `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>` / `--all` / `--default` / `--concurrency <n>` | Multi-target fan-out (see below). Repeatable `--group`/`--where`; `--near`/`--bbox` select by device GPS (lat-first; see constitution: target selection). The union de-dupes by CDB record index. |
-| target/auth | `--host`, `--port`, `--username`/`--user`/`-u`, `--password`, `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve <none\|arp>` — same single-target resolver as `retrieve`/`execute`. |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → api](../../docs/CLI.md#api); this file does not duplicate
+that table, and `api` has no designed-but-unimplemented flags. Behavior notes
+the generated reference cannot carry:
+
+- `-f` values pass through verbatim (no type-guessing); `-d`/`--input`
+  collide with `-f` → `usage/conflicting-flags`.
+- `--query`/`--filter` map to REST `.query` words / native `?` words.
+- `--raw-query` is emitted as-is; the caller owns the stack — e.g.
+  `--raw-query type=ether --raw-query type=vlan --raw-query '#|'` (OR).
+- `--via rest-api --stream` errors `transport/capability-unsupported`
+  (REST's 60 s cap cannot follow).
+- Under `--stream`, `--format json`/`yaml` emit one compact envelope per
+  line (NDJSON); `text` emits a concise row per frame.
+- The target/auth flags (`--host`, `--port`, `--username`, `--password`,
+  `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve`)
+  use the same single-target resolver as `retrieve`/`execute`; `--quickchr`
+  resolves host/port/auth from the live `@tikoci/quickchr` descriptor
+  instead (constitution: resolution providers).
 
 ## Fan-out (multi-target)
 
@@ -98,19 +99,48 @@ vs `--query` distinction.
 
 ## Validation
 
-Default on. Because the input is a structured path (not a CLI string), the gate is
-`/console/inspect` — **not** `:put [:parse]`:
+Default on. Because the input is a structured path (not a CLI string), the device
+gate is `/console/inspect` — **not** `:put [:parse]`:
 
 - Path existence + per-verb attribute validity via `request=child`
   (`validation/unknown-path`, `validation/unknown-attribute`).
-- Value-level advice via `request=completion` (+`input=`) feeding `tips`/`warnings`.
+- **Designed, not implemented:** value-level advice via `request=completion`
+  (+`input=`) feeding `tips`/`warnings`. Whatever implements it must not fall
+  back to `request=completion` at a *command* path (`path=` ending at the verb):
+  that shape hangs REST and closes native API on RouterOS 7.12.2, and no centrs
+  code uses it. Completion at an *argument* path (`print,proplist`, as `retrieve`
+  does) answers normally on the same build. See the 7.12.2 finding in
+  `AGENTS.md` (GH#343).
 - **Carve-out:** a script-shaped `POST /rest/execute` is a CLI string, not a path,
   so the inspect gate is `not-applicable` (`meta.validation.semantic`); RouterOS
-  re-validates on the run.
-
-`--validate=false` (and `--raw`, which implies it) skip the preflight; RouterOS
-still re-validates writes server-side. Disabling validation to make a call pass is
-forbidden (constitution: validation is the product).
+  re-validates on the run. Until GH#354 that carve-out meant the script was sent
+  with *no* preflight at all. It is now gated by the offline stage (constitution:
+  validation) — the same analyzer `explain` publishes, run over the `script`
+  field with no connection, so a syntax fault is a byte span in
+  `error.context.span` instead of a round trip. `meta.validation.stages[]` shows
+  the offline stage `passed` and the device stage `skipped` with its reason. A
+  missing or blank `script` is still `input/invalid-command`, not a syntax
+  rejection.
+- Structured path requests are **not** offline-gated. The input is a path plus a
+  body, not a CLI string, and an offline *path* gate collides with GH#211's
+  unlisted-path decision. On the success path `meta.validation.stages[]` is
+  absent there; on a `validation/*` rejection it is present and reports the
+  offline stage `skipped` with that reason, so the breakdown never implies an
+  analysis that did not run.
+
+`--validate=false` skips **both** stages of the preflight — one flag, one meaning
+(constitution: validation); RouterOS still re-validates writes server-side.
+Disabling validation to make a call pass is forbidden (constitution: validation
+is the product).
+
+`--raw` **defaults** `--validate` to false — it does not override it (GH#154).
+The resolution order is the explicit `--validate` flag, then `--raw`, then
+`CENTRS_VALIDATE` / the CDB comment-kv / config, then the `true` default. So
+`--raw` alone behaves as it always has and behaves the same on every machine
+whatever the environment holds, while `--raw --validate=true` runs the gate and
+reports a rejection in the `--raw` error shape (`{code,message}` on stderr,
+nonzero exit, no `data` key) — which is how you debug `api` when centrs itself is
+the suspect.
 
 ## Write confirmation