@tikoci/centrs 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -6,7 +6,114 @@ The product evolves as a stream of changes; there are no alpha gates.
 Per-feature status is tracked in `docs/MATRIX.md`. Use this file for
 documenting cross-cutting shifts that affect contributors and consumers.
 
-## Unreleased
+## 0.1.7 — 2026-09-27
+
+### Added
+
+- **`centrs devices init` creates an empty CDB, `git init`-style (#376).**
+  Bootstrapping a device book previously meant conjuring the file some other
+  way. `centrs devices init [--cdb-file PATH]` (or `CENTRS_CDB_FILE`, or the
+  default path) creates the parent directories and an exclusive `0600` file.
+  **It never clobbers**, so a bootstrap script may run it unconditionally: an
+  existing readable CDB succeeds with a `cdb/file-exists` warning and nothing
+  is written. An existing file that fails to load (`cdb/parse-failed`,
+  `cdb/password-required`) reports that error and is left untouched, and a
+  location that cannot be written fails with the new `cdb/create-failed`. CLI
+  and library (`initCdb`) only; not exposed on the MCP devices tool.
+
+- **`devices list` reports the lookup keys it matches on (#378).** Rows now
+  carry `identity` / `mac` / `ip` when the comment sets them, with
+  `comment-kv` provenance in `sources`, and the text table gains an `IDENTITY`
+  column. `comment` itself stays `show`-only.
+
+### Fixed
+
+- **Write-shaped commands now require confirmation, on every transport
+  (#365, #366).** Write authorization was entangled with script-vs-structured
+  transport selection, so several shapes reached a device without passing the
+  `--yes` gate: selectors, positional ids, non-CRUD verbs, root mutators,
+  indirect execution and relative menu writes. Authorization is now decided
+  independently of how the command is carried. Read spellings are unaffected —
+  the verb is the first known verb among the path's last segment and the bare
+  words following the path token, so `/system identity print` and
+  `:put [/system identity get name]` stay reads, while a statement with no
+  recognizable verb still fails closed. Caller-addressed API `/execute` script
+  strings additionally run offline analysis, then live `:parse`, then execute;
+  structured API requests remain on `/console/inspect`. This advances the
+  synchronous half of #154 without closing it — caller-controlled `file=`,
+  `as-string` and async job-id semantics remain open there.
+
+- **RouterOS rejections returned inside a successful transport envelope are no
+  longer read as success.** `/execute` can answer 200 while the device's own
+  text says it refused. Those are now classified as runtime failures, with the
+  passed validation-stage history preserved so the envelope still shows what
+  each stage concluded.
+
+- **Device-stage validation missed RouterOS's bare `missing …` diagnostics
+  (#375).** `classifyParseResult` matched `syntax error`, `bad command name`
+  and `expected …` from `:put [:parse …]`, but not `missing closing brace` or
+  `missing value for where` — so the device stage reported those rejections as
+  a pass and the command ran. `/ip/address/find where=` passes offline, which
+  made the device classifier its only gate. Replaying every bare diagnostic in
+  the pinned corpus across 7.20.8 → 7.25beta3 finds exactly seven heads, and
+  the two `missing …` forms were the only misses; both are now recognized, with
+  the device's own position in `error.context.detail`. Echoed script text is
+  still not a verdict.
+
+- **A stream's `/cancel` acknowledgement is now bounded (#385).** `api
+  --stream` stopped by `--duration` or Ctrl-C sent `/cancel` and then waited
+  with no bound, so a connected router that never answered held the CLI open
+  forever — `backend.close()` in the outer `finally` was unreachable while that
+  wait was pending. The wait is now bounded by the request `--timeout`, the
+  same bound as every other reply wait; past it the listen ends locally and the
+  session closes. The summary keeps its real `stopReason` and adds a
+  `transport/cancel-unacknowledged` **warning**, so the outcome never claims an
+  acknowledgement that did not arrive. A cooperating router is unchanged.
+
+- **`retrieve --attributes` rejected real singleton properties (#377).**
+  `isKnownSingletonPath` knew only `/system/resource` and `/system/identity`,
+  so every other singleton (`/tool/romon`, `/system/routerboard`, `/ip/dns`, …)
+  was inspected as a list menu. `print,proplist` comes back empty on a
+  singleton, so validation fell back to `print`'s own flags (`as-value`,
+  `file`, `interval`, …) and offered those as the attribute list. The singleton
+  bit now comes from the device: a singleton's `get` takes only `value-name`,
+  while a list menu's `get` also takes `number`. The hardcoded pair survives
+  only as the `--validate=false` fallback, which skips inspect. Costs one extra
+  `request=child` for a menu that has `get`.
+
+- **Completion candidates mixed help text and syntax rows into property names
+  (#380).** `extractCompletionNames` read `completion`/`name`/`value`/`text`
+  from every row, so the help string ("DNS cache size in kB") and the
+  `show: "false"` syntax rows (`[`, `(`, `$`, `"`, `*`, `<value>`) were offered
+  as attributes — which is why `--attributes '$'` passed validation. Rows carry
+  only `completion`/`offset`/`preference`/`show`/`style`/`text`/`type` on every
+  build recorded 7.9.2 → 7.25beta3, so `name`/`value` never matched anything.
+  On CHR 7.23.7, `show: "true"` is exactly the property set. The exported
+  `InspectCompletionItem` drops the never-present `name`/`value` and adds
+  `show`/`style`/`offset`/`preference`.
+
+- **An unparseable `<router>` crashed instead of reporting (#381).**
+  `parseHostCandidate` passed the target straight to `new URL` — the only
+  `new URL` on user input in `src/` — so with the default CDB, `quickchr:NAME`,
+  `a b` or `bad:host:name` failed every command with a `TypeError: Invalid URL`
+  surfaced as `internal/unhandled`. It now raises `input/invalid-target` and
+  names the valid target forms; a `quickchr:NAME` guess is told to use
+  `--quickchr NAME`. With an explicit CDB the same input already stopped at a
+  classified `cdb/not-found-target`, so that path is unchanged.
+
+### Changed
+
+- **The pinned restraml inspect trees advance to the live channel builds.** The
+  pins named "current stable" and "next beta" while pointing a patch behind
+  both: stable 7.24.2 → 7.24.4 and development 7.25beta3 → 7.25beta5. History
+  anchors 7.10.2 and 7.16 are untouched and both current versions stay
+  architecture-paired. The refresh is structurally a no-op — the inspect union
+  holds at 617 menus and the catalog at 1,120 paths, with no path added or
+  removed and no kind change. What moved is current-only publication: the CLI
+  Reference grew 1,053 → 1,055 pages (1,060 → 1,062 entries) and now documents
+  `/interface/ethernet/pon` and `/ip/ssh/known-hosts`, so both move `inspect` →
+  `both` (961 `both`, 65 `inspect`, 94 `published`). Zero
+  navigation-vs-command contradictions, unchanged.
 
 ## 0.1.6 — 2026-09-15
 

package/README.md

@@ -11,9 +11,13 @@ installing centrs or connecting to a router:
 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.
+Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI. Since
+0.1.6 the dist-tag follows standard SemVer semantics rather than the old
+even/odd-minor rule: a plain version (`0.1.6`) publishes to `latest` and carries
+`next` forward with it, while a pre-release suffix (`0.1.7-next.0`) publishes to
+`next` only and never moves `latest`. So `@next` is the leading edge and can
+equal `@latest` between cuts — `npm view @tikoci/centrs dist-tags` is the
+authority.
 
 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
@@ -58,7 +62,7 @@ product; without them this would just be a worse `curl`.
 | `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
 | `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. |
+| `check`    | Probe reachability and management protocol availability. **Designed, not implemented** — see `docs/MATRIX.md`. |
 | `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. |

package/commands/api/README.md

@@ -112,15 +112,18 @@ gate is `/console/inspect` — **not** `:put [:parse]`:
   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. 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.
+  so structured inspect is `not-applicable` (`meta.validation.semantic`). It
+  follows the CLI-string pipeline instead: offline analysis, then live
+  `:put [:parse ...]`, then run. An offline rejection is still a byte span with
+  no connection; an offline pass or abstention continues to the device stage.
+  `meta.validation.stages[]` reports both decisions. A missing or blank `script`
+  is still `input/invalid-command`, not a syntax rejection. Validation passing
+  is not the run succeeding: `as-string` makes the console's own text the reply
+  body, so a runtime rejection arrives as an HTTP-200 `ret`. `/execute` output
+  is normalized through the same grounded result table `execute` uses, so
+  `no such item` fails the envelope with a `routeros/*` code while the stages
+  stay `passed`. Ordinary output that merely contains a fault string is
+  unaffected — the result matchers are anchored, not substring.
 - 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
@@ -186,7 +189,15 @@ RouterOS produces multi-frame output two ways, and `api` treats them differently
   deletion's `.dead=true` flag is preserved); the stream ends with a summary
   envelope (`data.stopReason` ∈ `count-reached`/`duration-elapsed`/`interrupted`/
   `transport-error`, plus `frames` and `durationMs`). `--duration`/`--count`
-  bound it; Ctrl-C stops and still emits the summary. `--via rest-api --stream` →
+  bound it; Ctrl-C stops and still emits the summary. The `--duration` window
+  starts once validation is done, so it excludes validation (and the connect and
+  login validation needs). With `--no-validate`, connect and login happen inside
+  the window. Stopping on `--duration` or Ctrl-C sends RouterOS `/cancel`, and
+  centrs waits up to `--timeout` for the router to acknowledge it. A router that
+  never does gets its session closed locally, and the summary carries a
+  `transport/cancel-unacknowledged` warning (#385). Reaching `--count` sends
+  `/cancel` best-effort and closes the session without waiting, so it never
+  carries that warning (examples L5). `--via rest-api --stream` →
   `transport/capability-unsupported`. The exit code reflects whether the stream
   *started* cleanly, not whether every frame was `ok`.
 

package/commands/api/examples.md

@@ -156,7 +156,8 @@ centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --use
 
 Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
 `meta.validation.semantic=not-applicable` (script, not a path) and
-`meta.validation.stages` is `offline: passed` then `device: skipped`.
+`meta.validation.stages` is `offline: passed` then live `device: passed` from
+`:put [:parse ...]`.
 
 ### 16b. The `/execute` script is gated offline (GH#354)
 
@@ -173,6 +174,31 @@ Envelope: `ok: false`, `error.code=validation/syntax`,
 `error.context.span={"start":5,"end":6}`, and **not** a `transport/*` code.
 `meta.validation.stages` is `offline: failed` then `device: skipped`.
 
+### 16c. Offline pass continues to live `:parse`
+
+```bash
+centrs api $R execute -X POST -f script='/ip/address/add no-such-arg=x' --username $U --password $P --yes
+```
+
+Envelope: `ok: false` with a device validation code
+(`validation/unknown-attribute`, or `validation/syntax` on older RouterOS), and
+`meta.validation.stages` is `offline: passed` then `device: failed`. Offline
+acceptance remains `runtimeAcceptance: not-proven`; it never suppresses the live
+stage.
+
+### 16d. A runtime rejection in `/execute` output is not `ok: true`
+
+```bash
+centrs api $R execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`. `as-string` makes
+the console's own text the reply body, so RouterOS carries this rejection in an
+HTTP-200 `ret`; the validation gate stays `passed` because it did pass — the
+command was rejected at run, not at validation. Ordinary output that merely
+mentions a fault string (`:put "status: no such item appears in help"`) stays
+`ok: true`.
+
 ### 17. `--via rest-api --listen` is rejected
 
 ```bash
@@ -308,7 +334,28 @@ stdout is the bare rest-style array (string values); exit code 0.
 centrs api $A execute -X POST -f script=':put [/system/identity/get name]' --via native-api --port $API_PORT --username $U --password $P --yes
 ```
 
-Envelope: `ok: true`, `data` contains the CHR identity.
+Envelope: `ok: true`, `data` contains the CHR identity and validation reports
+offline plus live `:parse` stages passed.
+
+### N8b. Native `/execute` also rejects at live `:parse`
+
+```bash
+centrs api $A execute -X POST -f script='/ip/address/add no-such-arg=x' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`; the accepted version-specific validation code is
+`validation/unknown-attribute` or `validation/syntax`, with stages
+`offline: passed`, `device: failed`.
+
+### N8c. Native `/execute` runtime rejection fails the envelope
+
+```bash
+centrs api $A execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, with the validation
+stages still `passed` — the same normalization as REST, since both adapters
+surface the `as-string` console text as `data`.
 
 ## listen / `--stream` (native-api only)
 
@@ -356,6 +403,27 @@ centrs api $A ip/address --stream --duration 2s --via native-api --port $API_POR
 With no change during the window, the stream ends after ~2 s with a summary
 envelope whose `data.stopReason=duration-elapsed`. Exit code 0.
 
+### L5. A router that ignores `/cancel` cannot hold the process open
+
+```bash
+centrs api $A ip/address --stream --duration 200ms --timeout 1s --via native-api --port $API_PORT --username $U --password $P
+```
+
+A stream stopped by `--duration` or Ctrl-C sends `/cancel` and waits up to
+`--timeout` for the router's acknowledgement (the interrupted `!trap` and
+`!done`). If none arrives, centrs closes the session itself. The summary still
+reports its stop reason (`duration-elapsed` or `interrupted`), exit code is 0,
+and `warnings` carries `transport/cancel-unacknowledged`. A router that answers
+inside the window gets no warning. `--count` sends `/cancel` without waiting,
+so it exits at once and never warns (#385).
+
+RouterOS on CHR always acknowledges `/cancel`, so this example runs against a
+loopback native-API peer that ignores it, as a real CLI process:
+`test/integration/api-stream-cancel.test.ts` covers `--duration`, SIGINT,
+`--count` and the cooperative control. The session-level cases (silent peer,
+chatty peer, trap without `!done`, close after cancel) are in
+`test/unit/native-api.test.ts`.
+
 ## fanout (multi-target, F…)
 
 These run against a CDB fixture with two records sharing group `$G`: record 0 is

package/commands/devices/README.md

@@ -332,6 +332,7 @@ runs produce stable diffs.
 ## Subcommands
 
 ```text
+centrs devices init                     # create an empty CDB at the resolved path
 centrs devices list [--group G] [--where attr=value]
                     [--near lat,lon,radius] [--bbox south,west,north,east]
                     [--format json|yaml|text]
@@ -361,8 +362,16 @@ clack-style prompt used by `@tikoci/quickchr`); it is **not** a separate
 field-editing verb, and invoking it today returns `usage/not-implemented`. There
 is no `update`.
 
+- `init` creates an empty open CDB at the resolved path (`--cdb-file`,
+  `CENTRS_CDB_FILE`, or the default), with parent directories and mode `0600`.
+  It never overwrites: on an existing, readable CDB it succeeds with a
+  `cdb/file-exists` warning and writes nothing. An explicit path is created only
+  by `init`; every other subcommand reports `cdb/not-found` for it (typo
+  protection), and that error names `init`.
 - `list` (alias `print`) shows resolved targets, their record type, group, and
-  a one-line provenance summary. No network IO. `--where attr=value`
+  a one-line provenance summary. Each row carries the `identity=`/`mac=`/`ip=`
+  lookup keys it resolves by (when set), so one call maps names to records. No
+  network IO. `--where attr=value`
   (repeatable, AND-combined) filters by CDB-stored facts/comment-kv plus core
   record fields (`target`/`group`/`identity`/`mac`) — e.g. `--where
   lat=37.7749`. `--near lat,lon,radius` and `--bbox south,west,north,east`

package/commands/devices/examples.md

@@ -29,7 +29,8 @@ centrs devices list --cdb-file $CDB
 ```
 
 Envelope: `ok: true`, `data` is an array of `{ target, recordType, group?,
-user, sources }`. No `meta.timing.request`.
+user, identity?, mac?, ip?, sources }` — the lookup keys appear only when the
+record's comment sets them. No `meta.timing.request`.
 
 ### 2. List a single group
 
@@ -46,7 +47,8 @@ valid success.
 centrs devices list --cdb-file /tmp/does-not-exist.cdb
 ```
 
-Errors with `cdb/not-found`. `details_url` populated.
+Errors with `cdb/not-found`. `details_url` populated. The remediation names
+`centrs devices init --cdb-file <path>` (example 54).
 
 ## show
 
@@ -634,3 +636,32 @@ Both succeed: the `add` stores the freeform comment verbatim, and the later
 `set timeout=5000` does **not** raise `input/incomplete-gps` even though the
 record's GPS pair is incomplete. Touching `lat`/`lon` (e.g. `set lat=…`) would
 re-enable the pairing check.
+
+## init
+
+`init` is the explicit way to start a CDB at a path you choose (#376). Reads
+and mutations never create an explicit `--cdb-file`/`CENTRS_CDB_FILE`; only the
+default path is created implicitly on first run.
+
+### 54. Start a repo-local CDB
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+centrs devices add 192.0.2.1 --user robot-reader --cdb-file ./lab/winbox.cdb --json
+```
+
+Creates missing parent directories and an empty open CDB with mode `0600`.
+`data` is `{ cdbFile, created: true, recordCount: 0 }`. The `add` then succeeds.
+
+### 55. `init` never clobbers
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+```
+
+On an existing, readable CDB: `ok: true`, `data.created: false`,
+`data.recordCount` is the current count, and a `cdb/file-exists` warning says
+nothing was written. As with `git init`, re-running is safe. An existing file that
+does not load fails with that load error (`cdb/parse-failed`,
+`cdb/password-required`) and is left untouched. A location that cannot be
+written fails with `cdb/create-failed`.

package/commands/execute/README.md

@@ -1,7 +1,7 @@
 # execute
 
 Run a RouterOS CLI command and return its (semi-structured) output. `execute`
-is the single read/write surface for RouterOS add/set/remove and other
+is the single read/write surface for RouterOS configuration and operational
 CLI-shaped commands — there is no separate `update` command.
 
 Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
@@ -15,7 +15,8 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 
 - Mirror RouterOS `execute` semantics. Input is a CLI string; output is
   console-shaped text (or structured records for path+verb writes) wrapped in
-  the standard envelope. This includes write-shaped add/set/remove.
+  the standard envelope. This includes selector-, positional-id-, and
+  non-CRUD-shaped writes.
 - Validation runs **offline first, then on the device** (see constitution:
   validation; GH#354). Stage 1 is the corpus-gated analyzer over the exact
   command string, with no connection: a syntax fault is rejected with a byte
@@ -27,8 +28,10 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   GH#230): a single `:put [:parse "<cmd>"]` covers both the syntax and the
   unknown-attribute (name-level) gate on **every** transport — `:parse` never
   throws; its return value's printed form (`(evl …)` / `(evl bad parameter …)` /
-  `(<%% bad command name …)`) is read from the REST/native `ret` *and* the
-  console output. That check is necessary, not sufficient: value-type errors pass
+  `(<%% bad command name …)`, or a bare line-anchored `syntax error` /
+  `expected …` / `missing … (line N column M)`, examples V4) is read from the
+  REST/native `ret` *and* the console output. An accepted return can echo
+  those words, so only the anchored forms reject. That check is necessary, not sufficient: value-type errors pass
   it, and the `/console/inspect request=child` / server re-validation semantic
   checks are separate. Command-level `request=completion` is deliberately not
   used: it hangs REST and closes native API on RouterOS 7.12.2 (GH#343), while
@@ -36,9 +39,21 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   The outer RouterOS string literal escapes backslash, quote, and dollar so
   validation parses the caller's exact command rather than expanding variables
   in the wrapper.
-- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
-  `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
-  whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
+- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` in
+  `src/execute.ts`): it decides which validation and transport path runs.
+  `isWriteShaped` is deliberately independent: script fallback for `[find]`, a
+  positional id, or other non-`key=value` input never bypasses confirmation.
+  Known read verbs are allowlisted; an unknown menu verb fails closed as a
+  write-shaped operation. In script mode every command head in a statement
+  (the statement start and each `[…]` or `{…}` body) must be a read: its verb
+  is the first word past the known menu prefix, so `/ip address print` is a
+  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, and so is any command
+  carrying `file=`: RouterOS redirects command output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc` and
+  `/file/print file=test` creates `test.txt` even though `export` and `print`
+  are read verbs. The shared
+  `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
   `test/unit/execute-canonicalize-contract.test.ts`; the parser-vendoring
@@ -68,12 +83,11 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   else passes its `detail`/body plus the HTTP status through
   `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
   a hand-rolled `routeros/*` table on the REST side.
-- **Run-time fault mapping — later (JG-28).** `mapRouterOsError`'s table covers
-  the faults seen so far; a known gap is errors that *pass* `:parse`/validation
-  but fail at **run time** (a syntactically valid command the router rejects when
-  executed). `tikoci/vscode-tikbook` has an error-string mapping for these worth
-  porting into `src/core/routeros-errors.ts`. Background research, not yet
-  scheduled — captured here so it isn't lost (no GitHub issue by design).
+- **Run-time fault mapping.** A successful transport can still carry a RouterOS
+  rejection in `/execute`'s `ret`. Result detection lives beside the grounded
+  mappings in `src/core/routeros-errors.ts`, uses anchored result shapes so
+  ordinary output containing error-like prose remains output, and preserves a
+  passed validation history while failing the overall envelope.
 - Output is *string*-shaped for script-mode; richer parsing is a future
   concern. The envelope must still distinguish RouterOS errors from successful
   runs (a 200 with a RouterOS error string is still an error — see
@@ -216,8 +230,8 @@ many tokens):
   it fans out; mixing it with positionals or CDB selectors is
   `usage/conflicting-flags` (constitution: resolution providers).
 
-Because `execute` is the primary **write** path, a write-shaped fan-out
-(add/set/remove) is gated by **`--yes`**, confirmed **once** up front; without it
+Because `execute` is the primary **write** path, a write-shaped fan-out is gated
+by **`--yes`**, confirmed **once** up front; without it
 the error names the blast radius (how many routers). Write-ness is determined from
 the command alone (`canonicalizeExecuteCommand` + `isWriteShaped`), so the gate
 fires before any target is dialed. Per-target validation still runs because

package/commands/execute/examples.md

@@ -428,6 +428,95 @@ and `meta.validation.stages` listing **both** stages as `skipped`. A gated
 surface always reports every stage, so a consumer reading `stages` never has to
 special-case the disabled shape.
 
+### V4. A device-only `missing …` rejection is still a rejection
+
+The offline stage passes `/ip/address/find where=`: an empty `where` is not a
+structural fault it can see. RouterOS's `:parse` returns
+`missing value for where (line 1 column 24)` (CHR 7.24.4), a bare diagnostic
+like `syntax error`, so the device stage must reject it (GH#375). Before that
+fix the classifier only knew `syntax error`, `bad command name` and
+`expected …`, so it reported this reply as a pass and the command ran.
+
+```bash
+centrs execute $R '/ip/address/find where=' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`, `error.context.detail`
+is RouterOS's own `missing value for where (line 1 column 24)`,
+`error.position={"line":1,"column":24}`, and `meta.validation.stages` is
+`offline: passed` followed by `device: failed`.
+
+CHR 7.24.4 controls, via `:put [:parse "…"]`: `find where` without `=` parses
+(IL). `print where=` is rejected differently (`expected end of command`, at
+`where`). An unclosed bare `{` block or menu block (`/ip address {` then
+newlines) returns `missing closing brace (line 3 column 1)`, while an unclosed
+`do={` returns `expected closing brace`. Offline analysis usually catches the
+unclosed-brace cases first.
+
+## Write authorization and returned runtime faults
+
+These regressions are transport-independent and run in
+`test/integration/execute.test.ts` (with MCP's selector form also covered by
+`test/integration/mcp.test.ts`).
+
+### W1. Script-mode selector and positional writes still require confirmation
+
+```bash
+centrs execute $R '/ip/address/remove [find comment=centrs-write-gate]' --via rest-api --username $U --password $P </dev/null
+```
+
+The same contract holds for `/ip/address/remove *1`. Both stay script-mode so
+RouterOS receives the raw selector/id syntax, but the independent safety gate
+returns `usage/confirmation-required` before validation or mutation.
+
+### W2. Non-CRUD mutation verbs still require confirmation
+
+```bash
+centrs execute $R '/ip/address/disable numbers=*1' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`; the address
+remains enabled. Unknown RouterOS menu verbs also fail closed as write-shaped.
+Root mutators such as `/import` and indirect execution through `:execute` use
+the same gate.
+
+### W3. Space-separated menu reads run without confirmation
+
+```bash
+centrs execute $R '/system identity print' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true`. The space-separated spelling puts menu segments and the
+verb in bare words, so the gate walks the known menu prefix and reads the first
+word past it as the verb. `/ip address print where …` and
+`:put [/system identity get name]` are reads the same way. The walk is also what
+keeps an unlearned command gated: `/user expire-password print` names
+`expire-password`, a published command outside both verb allowlists, whose
+argument happens to be `print`, so it returns `usage/confirmation-required`.
+Every command head in a statement is checked, including `[…]` and `do={…}`
+bodies.
+
+### R1. A post-validation `/execute` rejection fails the overall envelope
+
+```bash
+centrs execute $R '/ip/service/set www-ssl certificate=nope' --via rest-api --username $U --password $P --yes --json
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, exit `1`, while
+`meta.validation.result="passed"` and both stages remain `passed`: the rejection
+happened at run time, after the scoped checks completed. The same result is
+asserted over native API.
+
+### R2. Error-like prose remains ordinary script output
+
+```bash
+centrs execute $R ':put "status: no such item appears in ordinary output"' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: true`. Returned-text classification uses anchored grounded
+shapes; it does not fail arbitrary output merely because it contains an error
+phrase.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar

package/commands/explain/README.md

@@ -172,7 +172,7 @@ today's path/verb/args split and script-vs-structured gate:
   The *container* half of that pair is since decidable. `src/explain/menus.ts`
   (#207) bakes only the menu-vs-command node type — not a schema — and it is
   version-less because the pinned trees show no `dir`↔`cmd` flip across
-  7.10.2 → 7.25beta3 or across architectures. So `/ip/route` now resolves as
+  7.10.2 → 7.25beta5 or across architectures. So `/ip/route` now resolves as
   `navigation` (#210). The floor is unmoved: the table is deliberately
   incomplete, absence from it decides nothing, and every rule above it still
   refuses rather than guesses.
@@ -221,6 +221,17 @@ today's path/verb/args split and script-vs-structured gate:
   coherent generated catalog has 1,120 paths: 959 `both`, 67 `inspect`, and 94
   `published`; it still reports zero navigation-vs-command contradictions.
 
+  **Source refresh (accepted 2026-09-27).** The two current pins advance to the
+  channels then live — stable 7.24.2 → 7.24.4 and development 7.25beta3 →
+  7.25beta5 — both still architecture-paired, both history anchors untouched.
+  The refresh is a structural no-op: the inspect union holds at 617 menus and
+  the catalog at 1,120 paths, with no path added or removed and no kind change.
+  What moved is current-only publication: the CLI Reference grows from 1,053
+  pages / 1,060 entries to 1,055 / 1,062, which documents
+  `/interface/ethernet/pon` and `/ip/ssh/known-hosts` for the first time and so
+  moves both from `inspect` to `both` — 961 `both`, 65 `inspect`, 94
+  `published`. Zero navigation-vs-command contradictions, unchanged.
+
 There are real unknowns in how far offline parsing can go (expression
 grammar, scope fidelity vs `:parse`, `[]`-nesting corner cases). Grounding
 those unknowns was **phase 0** (#185); its findings are folded in throughout

package/commands/mcp/README.md

@@ -125,7 +125,8 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 - `centrs_retrieve` mirrors `retrieve`, including attribute projection,
   `listAttributes`, and `group` fanout.
 - `centrs_execute` mirrors `execute`. Read-shaped commands run subject only to
-  CDB membership; write-shaped add/set/remove are gated by the CDB policy below.
+  CDB membership; every write-shaped command is gated by the CDB policy below,
+  including selector/positional script forms and non-CRUD mutation verbs.
   Its MCP `destructiveHint` is **conservative — always `true`**, even though the
   tool also serves read-shaped commands: a single execute tool cannot vary the
   static annotation by argument, so it advertises the worst case and lets the

package/commands/retrieve/examples.md

@@ -84,6 +84,18 @@ Rejected before any network call, with `usage/conflicting-flags`.
 centrs retrieve $R /system/resource --attribute uptime --all-attributes --username $U --password $P --json
 ```
 
+### 20. Comma-list --attributes on any singleton
+
+Singletons are recognized from `/console/inspect` — their `get` takes no
+`number` argument — so every singleton validates against its `get value-name`
+properties, not against `print`'s flags (#377).
+
+```bash
+centrs retrieve $R /tool/romon --attributes enabled,id --username $U --password $P --json
+```
+
+Envelope: `data` is an object containing only `enabled` and `id`.
+
 ## --list-attributes
 
 ### 9. List attributes for a path
@@ -336,6 +348,14 @@ centrs retrieve $A /system/resource --attribute bogus-attr --via native-api --po
 centrs retrieve $A /system/resource --via native-api --port $API_PORT --username wrong --password wrong
 ```
 
+### N12. Singleton `--attributes` projection (#377)
+
+```bash
+centrs retrieve $A /tool/romon --attributes enabled,id --via native-api --port $API_PORT --username $U --password $P
+```
+
+`data` is an object containing only `enabled` and `id`.
+
 ## quickchr targets (#134)
 
 `$NAME` is the machine name of a running quickchr-managed CHR

package/docs/CLI.md

@@ -234,7 +234,7 @@ Usage: centrs explain '<input>' [flags]
 Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
 
 ```text
-Usage: centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]
+Usage: centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]
 ```
 
 | Flag | Value | Description |