@tikoci/centrs 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -8,6 +8,104 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.4 — 2026-08-31
+
+Preview release. `@tikoci/centrs@0.1.4` on npm's `next` tag.
+
+### Added
+
+- **Offline `explain` is now a real CLI and library surface.** It analyzes
+  RouterOS commands and scripts without a router, CDB, or network connection,
+  returning canonical structure, diagnostics, write-shape and transport
+  classification, optional `curl` rendering, symbols, value-shape hints, and a
+  gapless token partition. Try it with
+  `bunx @tikoci/centrs@next explain '/ip/address print' --json`.
+- **Generated RouterOS structure evidence.** Pinned inspect trees and
+  MikroTik's published CLI Reference now help distinguish known menus from
+  commands while preserving the fail-closed rule: missing catalog entries never
+  become rejections, schema claims, or runtime-acceptance claims.
+- **Named quickchr targets.** Router-facing commands can resolve an ephemeral
+  quickchr instance with `--quickchr <name>` through the shared target-provider
+  path.
+
+### Changed
+
+- **Offline analysis is substantially more precise and robust.** Grounded
+  handling now covers RouterOS comments, escapes, operators, arrays, value
+  shapes, path context, and flow-sensitive symbol-to-value references; bounded
+  traversal and shared statement indexes keep large inputs near-linear.
+- **Release and QA coverage is broader.** Recency-aware RouterOS channel
+  selection, long-term-version expectations, generated-artifact drift checks,
+  corpus gates, and faster local Git gates make the published preview easier to
+  reproduce and audit.
+
+### Fixed
+
+- **Validation now reads RouterOS `:parse` results instead of accepting the
+  transport round-trip alone**, and retrieve errors retain the rejected
+  parameter. Parser, catalog, cross-platform QA, and MAC-Telnet edge cases were
+  also hardened.
+- **The npm package now carries the MIT license text.**
+
+## 0.1.3 — 2026-07-06
+
+Patch release. `@tikoci/centrs@0.1.3`.
+
+### Added
+
+- **`api` command over rest-api + native-api is `CHR-passed`.** `centrs api`
+  brings a `gh api`-style structured passthrough to both transports, and folds
+  the old standalone `stream` command into `api --stream` (native-api only,
+  `--listen` alias): a `NativeApiSession.listen()` reader with `/cancel`
+  support emits NDJSON frames plus a run summary. Grounded against real CHR
+  7.23.1.
+- **Multi-target fan-out is uniform across `api`, `retrieve`, `execute`, and
+  `transfer`.** A shared `expandCdbSelection` + `runFanout` + `fanoutExitCode`
+  core (extracted once, consumed by all four commands) lets any command take a
+  CDB selector and run over every matching device. The positional boundary
+  that ends the selector differs per command (final positional for
+  `api`/`retrieve`, `--` for `execute`, the verb keyword for `transfer`);
+  `terminal` and `api --stream` explicitly reject `N > 1` selections since
+  neither has a sane multi-target framing.
+- **`settings` command (`print` / `get` / `set` / `reset`).** A managed-key
+  registry for the real `CENTRS_*` environment keys backs an atomic
+  `centrs.env` writer: `set` validates per key, canonicalizes booleans to
+  `1`/`0` on disk, warns (never blocks) on consequential values
+  (`insecure=true`, `transfer-via=ftp`), and never partially writes on a
+  validation failure; `reset` deletes the managed line rather than blanking it
+  (a blank value would itself mean "set to empty" for a bash-sourced file) and
+  leaves foreign lines/comments untouched. Bare `centrs settings` behaves like
+  `print` regardless of TTY. Four new error/warning codes
+  (`settings/reserved-key`, `settings/unknown-key`,
+  `settings/consequential-value`, `settings/skip-env-file-active`) plus
+  `internal/settings-failed`, all cataloged. `CHR-passed` via 32
+  fixture-backed integration examples.
+- **Device GPS: lat/lon/altitude storage + `--near` / `--bbox` geo
+  predicates.** `centrs devices` now stores GPS coordinates per device
+  (lat-first ordering, chosen so agents guess the field order correctly) and
+  supports proximity
+  (`--near`) and bounding-box (`--bbox`) selection predicates. `CHR-passed`
+  via fixture-backed integration coverage.
+- **Registry⇄MATRIX drift guard + "did you mean?" flag errors.** A CI-checked
+  guard keeps the command/protocol registry and `docs/MATRIX.md` from
+  silently drifting apart; unrecognized CLI flags now suggest the closest
+  known flag instead of a bare rejection.
+- **GitHub Pages: published API reference + error catalog.** `typedoc` output
+  and the generated error-code catalog now publish to GitHub Pages on push.
+
+### Fixed
+
+- **Windows unit-test portability for `settings` and MNDP.** Path-separator
+  and related platform assumptions in the `settings` and MNDP unit suites are
+  now Windows-safe (#170).
+- **A real CodeQL-caught ReDoS in the device GPS geo-predicate parser**, fixed
+  rather than suppressed.
+
+### Changed
+
+- **CodeQL house-rules pack promoted to the default run**, alongside CodeRabbit
+  review-tone tuning and a reduced GitHub-checks timeout (15 → 7 minutes).
+
 ## 0.1.2 — 2026-06-26
 
 Patch release. `@tikoci/centrs@0.1.2`.

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
@@ -139,6 +144,7 @@ MNDP
 NAND # NAND flash memory; write-back caches file writes up to ~40s on some MikroTik boards
 netmiko # [Multi-vendor library to simplify Paramiko SSH connections to network devices](https://github.com/ktbyers/netmiko)
 netwatch
+nullglob # bash shopt that makes an unmatched glob expand to zero words instead of the literal pattern
 npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
@@ -148,6 +154,7 @@ PRGA
 proplist
 pywinauto
 QML
+qll # CodeQL library file extension (.qll), e.g. CleartextLoggingCustomizations.qll
 qmljsdebugger
 quickchr
 RAML
@@ -161,12 +168,16 @@ 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
 scriptable
+shopt # bash builtin for toggling shell options (e.g. nullglob)
 Sikuli
 SikuliX
 skillcheck
+startswith # jq builtin filter that tests whether a string begins with a given prefix
 SNMP
 SPI
 SRP
@@ -184,6 +195,7 @@ TIKOCI
 tiktui
 TLV
 traceroute
+tostring # jq builtin filter that renders a value as its JSON string representation
 tsc
 tzsp
 TZSP
@@ -200,6 +212,7 @@ webproxy
 WinAppDriver
 winbox
 Wireshark
+workstream
 workstreams
 XCUI
 XDG
@@ -263,6 +276,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
@@ -364,6 +380,10 @@ 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
 # unconfigured: a freshly-flashed RouterOS device with no IP — the mac-telnet use case.
 unconfigured
 unwired
@@ -391,6 +411,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.
@@ -434,3 +455,266 @@ toarray
 # Logic shorthand ("if and only if") used in api write-gate doc comments; cspell's
 # markdown dictionary knows it but the TypeScript one does not.
 iff
+
+# GitHub Pages build vocabulary (scripts/build-pages-site.ts, pages.yaml)
+# typedoc/pandoc: the API-reference generator and the markdown->HTML converter
+#   the Pages build chains together. gfm: GitHub-Flavored Markdown, pandoc's
+#   input format for the error pages. larr: the "&larr;" left-arrow HTML entity
+#   in the back-to-docs link. nojekyll: the marker file that disables GitHub
+#   Pages' Jekyll processing for an Actions-deployed artifact. extensionless:
+#   describes the `details_url` contract (docs/errors/README.md) — no `.html`.
+typedoc
+pandoc
+gfm
+larr
+nojekyll
+extensionless
+# nothrow: Bun Shell's `$` method to disable throwing on a non-zero exit
+# (scripts/agent-check.ts), so the caller can inspect output either way.
+nothrow
+
+# check-command spec vocabulary (commands/check/README.md, examples.md)
+# TikTOML: centrs-owned readable device-inventory format (#137); check's
+#   metadata feeds it. routerboard: RouterBOARD firmware/hardware menu
+#   (/system/routerboard). rscmd: the tikbook RouterOS command-notebook file
+#   extension (.rscmd), the format the check spec was grounded against.
+TikTOML
+routerboard
+rscmd
+# RTT: round-trip time, the host->router connect-latency reach signal. tojson: the
+#   /system/script helper (:serialize to=json) the batched execute reads reuse.
+#   qrcode: the /ip/cloud vpn-wireguard-client-config-qrcode field token (redacted
+#   by the cloud check, referenced when documenting redaction).
+RTT
+tojson
+qrcode
+
+# Device GPS vocabulary (issue #146, commands/devices/README.md "Location /
+# GPS", src/resolver/geo.ts). MSL/AGL: the two supported altitude-type vertical
+#   datums (mean sea level / above ground level); stored case-insensitively but
+#   normalized to upper case. EPSG: the geodetic coordinate-reference-system
+#   registry (EPSG:4326 = WGS84 lat/lon), cited for the lat-first ordering
+#   rationale. bbox: the --bbox geo selector (bounding box). wgs: WGS84, the
+#   geodetic datum GPS coordinates use; appears only as a deliberately-invalid
+#   --altitude-type value in tests/examples. antimeridian: the 180° meridian a
+#   --bbox may not cross in v1. GEOSEARCH: the Redis command whose m/km/mi/ft
+#   radius-unit vocabulary --near borrows. IUGG: the geodesy union whose mean
+#   Earth radius the haversine uses. SFO/OAK: airports used as a known-distance
+#   haversine fixture in tests. ele/GPX: `ele` is GPX's altitude element, kept as
+#   an input alias for `altitude` (GPX = the GPS Exchange Format). Geolocation:
+#   the W3C Geolocation API, cited (with ISO 6709 / EPSG / IETF geo:) for why
+#   `altitude` — not `elevation` — is the canonical field name.
+MSL
+msl
+AGL
+agl
+Agl
+EPSG
+bbox
+wgs
+antimeridian
+GEOSEARCH
+IUGG
+SFO
+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)
+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, and the one published path with no gate anywhere in its ancestry to explain its absence from a CHR tree
+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

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,6 +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 try the current offline analyzer without
+installing centrs or connecting to a router:
+
+```bash
+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
@@ -11,9 +26,15 @@ 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 and in active development. 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.
+> **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.
 > `docs/MATRIX.md` is the single source of truth for what works today — treat
 > anything not green there as not-yet-shipped.
 
@@ -26,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 |
 | ---------- | ------- |
@@ -36,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. |
@@ -104,16 +128,23 @@ CDB tags, and `devices set` refuses to put them there. Unknown keys produce a
 `cdb/unknown-option` warning and are ignored, so a stray `=` in human prose
 never breaks anything.
 
-Settings resolve lowest-to-highest: **built-in defaults → project config →
-comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every result envelope
-reports which source won each setting under `meta.settings`, so you can always
-see *why* a given port or transport was chosen.
+Settings resolve lowest-to-highest: **built-in defaults → user config file
+(`centrs.env`) → comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every
+result envelope reports which source won each setting under `meta.settings`,
+so you can always see *why* a given port or transport was chosen.
 
 ### Groups, discovery, and the MCP allowlist all ride on the CDB
 
 - **Groups** are CDB-native: an entry's `group` field is just a string, and
   `--group prod-edge` fans a single command out to every entry that shares it.
-  There is no separate group-definition file.
+  There is no separate group-definition file. Groups are one selector in a
+  **uniform fan-out grammar** shared by `api`, `retrieve`, `execute`, and
+  `transfer`: mix `<router>` positionals, repeatable `--group`/`--where
+  <attr>=<value>`, `--all`, and `--default` (de-duped by CDB record index). Every
+  fan-out returns the locked `FanoutData` envelope (per-target results, not
+  metadata) with a granular exit code (`0` all ok / `2` partial / `1` all failed);
+  a multi-target write is gated once by `--yes` naming the blast radius. See
+  `docs/CONSTITUTION.md` (Target selection grammar).
 - **Discovery** writes back into the CDB: `discover --save` records MNDP
   neighbors as new entries tagged `group=discovered` with a `source=mndp`
   marker — hints to curate, not authoritative inventory.
@@ -168,7 +199,7 @@ roadmap.
 
 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).
@@ -188,6 +219,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/SECURITY.md

@@ -14,14 +14,14 @@ Please include the affected files or workflow, reproduction details, and impact.
 
 The repository's [Security tab](https://github.com/tikoci/centrs/security) is the live source of current alerts and advisories. This section describes *what* checks run and *why*, so the doc stays meaningful even when the badge is at 0.
 
-- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality). Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
-- **Code Quality (AI findings, preview)** — intended to be enabled in GitHub. [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract.
+- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality) plus a small custom pack, [`.github/codeql-house-rules/`](.github/codeql-house-rules/), that structurally checks a handful of repo-specific invariants (currently: `apiFanout` must call its named protocol/validation gates) — see `.github/instructions/github-security-quality.instructions.md` for scope and the verify-before-promote discipline for adding more rules there. Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
+- **Code Quality (AI findings, preview)** — confirmed active in GitHub as of 2026-07-03 (not just "intended"; see [issue #166](https://github.com/tikoci/centrs/issues/166)). [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract. Side effect: GitHub's own Code Quality scan runs in parallel with our Advanced Setup and posts a same-named `Analyze (javascript-typescript)` check, so PR checks lists show it twice — cosmetic, tracked in #166, not a required check either way (see issue #118).
 - **Dependency review** — not enabled. GitHub dependency review follows dependency-graph ecosystem support, and this Bun-only repository currently does not have a supported lockfile for that gate.
 - **Dependabot security updates** — enabled and configured in [`.github/dependabot.yaml`](.github/dependabot.yaml).
 - **Secret scanning** — enabled in GitHub, with push protection.
 - **Private vulnerability reporting** — enabled via GitHub Security Advisories.
 
-Some GitHub Security tab data, especially Code Quality AI findings, is not currently available through stable unauthenticated APIs. Human review in the GitHub UI remains part of the security workflow.
+Some GitHub Security tab data, especially Code Quality AI findings, is not reachable through the default workflow `GITHUB_TOKEN` (`repos/{owner}/{repo}/code-quality/findings` 403s there even with `security-events: read`) — it does respond with an elevated/owner-scoped token, but no findings have been recorded yet to confirm the response shape end-to-end (see #166). Human review in the GitHub UI remains part of the security workflow until that's wired up.
 
 ## Supported versions
 

package/commands/AGENTS.md

@@ -7,6 +7,11 @@ Each `commands/<name>/` holds the **executable spec** for one command:
   the matching `test/integration/<name>.test.ts`; example N ↔ assertion N. This
   is what `CHR-passed` is measured against.
 
+**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
 selection, and protocol selection. The identity/CDB **resolution depth** (lookup
@@ -19,7 +24,8 @@ README's "Status" line must agree with it.
 ## 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: