@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/CHANGELOG.md

@@ -17,6 +17,41 @@ part of this section.
 
 ### Added
 
+- `explain` offers a non-applied repair tip for pasted console prompts
+  (#370, #567, #578), including `[user@host] /menu>` and HotLock `>>` forms.
+  The candidate preserves command separators and names the menu context;
+  multiline repairs render as fenced code. The original analysis stays intact.
+- `--match user=<name>|target=<addr>|<record-type>` on `retrieve`, `execute`,
+  `api`, `transfer`, `terminal` and `btest client` picks one of several CDB
+  records saved for the same `<router>` (#583), as `devices show --match`
+  does. One address saved under two users was `identity/ambiguous` on every
+  command, and the error named a `--match` they rejected. The flag is
+  single-target: with a fan-out selection or `--quickchr` it is
+  `usage/conflicting-flags`, and with no CDB record in play it is
+  `identity/no-match` rather than ignored.
+- **Live `explain` over rest-api + native-api is `CHR-passed`** (#236).
+  Examples 7–16, 19, 24, 48 and 52–53 pass on both transports on stable
+  7.24.5 and long-term 7.23.8. `runtimeAcceptance` stays `not-proven`.
+- `explain <router> '<input>'` and `explainLiveEnvelope()` add read-only parse,
+  highlight and command-argument evidence over REST/native API. Probe outcomes,
+  byte coverage and provenance remain explicit; analyzed input never executes (#491).
+- Live `explain` fills the two live value facts (#225). `observedType` names a
+  type only where the device visibly converts a bare scripting literal
+  (`2.2` → `2.0.0.2` is `ip`, `0x10` → `16` is `num`), read from an escaped
+  `:parse` of the literal alone; an unchanged rendering abstains, and no
+  `:typeof` is sent. `schemaType` normalizes the argument's live `syntax`
+  declaration into leaf types (`gateway` → `ip`, `ip6`, `enum`), with the
+  device's own term in `declared`. Menu arguments are never observed, and
+  `op` has no producer.
+- Live `explain --schema` describes the path at the cursor: a menu's verbs and
+  submenus with counts, a command's arguments with their declared syntax, and
+  `print`'s proplist. `--complete [--cursor <byte>]` returns menu, verb,
+  argument-name, `where` variable or value candidates. They are the device's
+  own input completion at the cursor, cited by `ev`; declared names and
+  syntax stay in `--schema`. `--full` lifts the sizing limits up to a safety
+  ceiling.
+  Only probe shapes that answer on RouterOS 7.12.2 and 7.20.8 are sent (#492).
+
 - `centrs --version` / `-V` prints the package version alone; `--json` (or
   `--format json|yaml`) returns an envelope with `data.version` (#463).
 - `execute --cmr` warns `cmr/caller-policy-not-enforced` when a write runs
@@ -69,9 +104,47 @@ part of this section.
   client, its controller.
 - `execute --cmr` accepts a command that opens with a relative menu change
   (`/system; identity/print`); its `:parse` return was read as incomplete.
+- CDB encryption lifecycle (#558). `devices init --encrypt` creates an
+  encrypted empty CDB; `devices encrypt` converts an existing open CDB in place
+  with a fresh salt, keeping its records, unknown fields, and file mode. Both
+  need a non-empty `--cdb-password` / `CENTRS_CDB_PASSWORD`; a password alone
+  still never converts. Conversion keeps every backup and writes a plaintext
+  snapshot unless `--no-backup` is passed. It warns with `cdb/plaintext-backups`.
+  An already-encrypted file is verified and left unchanged. Library:
+  `initCdb({ encrypt })`, `encryptCdb({ skipBackup })`. `init` results now
+  include `encrypted`. `init` and `encrypt` refuse flags they would otherwise
+  ignore (`--user`, `--group`, `--via`, …) with `input/invalid-command`.
 
 ### Changed
 
+- **Breaking:** permission and edge-auth failures get their own error codes
+  (#541). Three codes change for `--json` and library readers:
+  - A REST policy refusal (HTTP 500 `not enough permissions (9)` or `std
+    failure: not allowed (9)`): `transport/connection-closed` →
+    `routeros/permission-denied`. It is a deterministic router answer, so it
+    is never retried and no longer carries
+    `transport/write-outcome-unknown`.
+  - A native-API `not enough permissions (9)` trap: `routeros/api-trap` →
+    `routeros/permission-denied`. Retrieve's path probe and live explain's
+    child probe surface it instead of reading "path doesn't exist".
+  - A 401/403 from a layer in front of RouterOS (auth proxy, tunnel edge,
+    WAF): `transport/auth-failed` → `transport/edge-auth-failed`, with the
+    challenge scheme, server, content type and `cf-ray` presence as context
+    (no secrets). RouterOS's own 401 — JSON `{"error":401,...}`, measured on
+    CHR 7.12.1, 7.16.2, 7.23.8, 7.25, 7.26beta1 and 7.26beta3 — stays
+    `transport/auth-failed`.
+- **`meta.validation` success shapes (#535).** This is a breaking change for
+  `--json` readers of the flat fields. `syntax` and `semantic` are now present
+  only when a gate stage gave that verdict; absent means no stage was asked.
+  - `api` structured requests (no `:parse`) drop `syntax: false`.
+  - Script input drops `semantic: "not-applicable"`; the value is gone from
+    the type.
+  - `--validate=false` drops both fields on `execute` and `api`.
+  - `retrieve`, `transfer` and `api` structured successes now report
+    `stages[]`. `transfer list` runs no existence probe, so it reports
+    `{ enabled: false }` instead of claiming one.
+  - `explain` reports `meta.validation: { enabled: false }` with no `result`
+    in all three cases (offline, live, error); it is not a gate.
 - Text stdout is data (#470). In text mode, single-target `execute`, `api`,
   `retrieve` and `transfer` write only the result to stdout. Everything else
   goes to **stderr** on success and on failure: the `--verbose` header, one
@@ -150,6 +223,42 @@ part of this section.
 
 ### Fixed
 
+- **`retrieve` and `api` can no longer send a non-read** (#586). A `#` or
+  `?` in the path cut the appended `/print` off the REST URL, so
+  `retrieve '/system/reboot#' --no-validate --attribute uptime` posted
+  `/rest/system/reboot` and rebooted CHR 7.24.5 without `--yes`; `api` with a
+  projection did the same. Both now require every path segment to be a
+  RouterOS menu name (letters, digits, hyphens; case folds) on every
+  transport, even with `--validate=false`, failing
+  `input/invalid-routeros-path` before resolution. The REST adapter also
+  refuses any request path containing `?`, `#`, `\`, control characters or a
+  dot segment (including `%2e%2e`), for every command. Reported by
+  routeros-muse.
+- `devices set <target> key=` removes the comment token instead of storing an
+  empty value, as documented (#590). Removing an absent token is a no-op;
+  `--password ""` still clears the password, and bare `password=`/`user=`
+  stay `cdb/reserved-key`.
+- `transfer` honors a CDB record's `via=` preference (#591). A record with
+  `via=ssh` drove `execute` over SSH but transfer ignored it and needed
+  `--via sftp`. Transfer now maps the record's transport to a method
+  (`ssh`→`sftp`, `rest-api`→`rest`, `native-api`→`native`) after `--via` and
+  `CENTRS_TRANSFER_VIA`, and accepts `--via ssh` as an alias of `sftp`. A
+  record transport that cannot carry files fails `settings/invalid-via`
+  naming the record; a record-pinned REST upload over 60 KB names the record
+  in its `transport/unsupported-operation` remediation.
+- The `explain` catalog generator skips the CLI Reference's new
+  `compare-versions` widget page (2026-10-30). The page carries no command
+  entry, and it aborted the catalog drift report. The refreshed catalog adds
+  10 published paths (`/interface/wifi/easymesh/*`,
+  `/app/settings/remove-certificate`, three `/system/resource/hardware`
+  commands), and the `/cmr/client` gates drop `!powerpc`.
+- `retrieve --sample`, `--follow` and `--wait` no longer report a validation
+  verdict the gate never gave (#537). A cancellation before the gate ran now
+  reports the device stage `not reached` (`interrupted` for `--sample` and
+  `--follow`, `wait/interrupted` for `--wait`) instead of
+  `{enabled: true, result: "skipped"}`. A `--wait` cancelled after retried,
+  unanswered attempts no longer reports `result: "failed"`. With validation
+  off, all three report `{enabled: false, source: "disabled"}`.
 - Abbreviated output-file arguments (`fi=`, `file-n=`), and the spaced
   `file-name value` form under print/export/serialize, require write
   confirmation in `execute`, including inside scripts, and are refused for
@@ -181,6 +290,56 @@ part of this section.
   a native API login. A write that failed after it was sent, in single-target
   or fan-out mode, carries the new warning `transport/write-outcome-unknown`,
   because it may have run. Reads keep the retry.
+- A bare known-menu path (`/system/identity`) reads as a read in `execute`,
+  not `usage/confirmation-required` (#543). It still answers nothing, so the
+  envelope steers to `/print` / `retrieve` with `tip/execute-bare-menu-path`.
+  Unknown paths, known-mutator verbs, and any attribute or query stay gated.
+- `retrieve /system/routerboard` on a router without the menu (CHR) names the
+  workaround: the `validation/unknown-path` remediation points at
+  `/system/license --attributes system-id` instead of the generic text (#545).
+- `execute` warns when a multi-statement write is refused for permission after
+  earlier statements may have run (#549). Such a refusal carries
+  `transport/write-outcome-unknown` alongside `routeros/permission-denied`,
+  counting statements inside executed `:if`/`:for`/`:foreach`/`:while`/`:do`/`:retry`/`:onerror` scopes and
+  command substitutions (`[…]`) as well as top-level ones; a `/menu { … }`
+  prefix is navigation, not a statement. Single refused statements, including
+  `remove [find …]` and one wrapped in a menu block, stay silent. The refusal itself
+  now surfaces as the error instead of `ok:true`: `/execute` answers HTTP 200
+  with `not enough permissions (9) (…; line N)` as the last `ret` line after
+  earlier statements' output (CHR 7.25, both transports).
+- The offline gate no longer hard-rejects first-segment script-body
+  abbreviations it cannot prove (#525). `down={ :beep }`, accepted on device
+  as `down-script=`, warns `explain/canonicalizer/possible-script-body-abbreviation` and
+  reaches device validation instead of failing with `invalid-command-brace`. Bodies
+  opening with one bare command word or after a comment line warn too, and
+  the brace reads as a body for every reader, and whitespace after the `=`
+  (`down= { :beep }`) warns like the glued spelling. A bare word followed by
+  `;`-separated members keeps its error, as do the other array-content
+  braces (`comment= {1;2}` included), the space-for-`=` spelling
+  (`comment { :beep }`), positional braces, root directive slots
+  (`:put x={…}`), and `where`; `comment={ :beep }` deliberately warns though
+  the device rejects it.
+- Native-API traps classify authentication by sentence, never trap text
+  (#540). Only a trap on `/login` is `transport/auth-failed`; a later command
+  rejected with login-like text (`/user/add name=-2` answering `invalid user
+  name`) is `routeros/command-failed`, agreeing with REST.
+- `explain` symbols declare the value of named `name=`/`counter=` spellings in
+  any argument order (#533). `:local name=no` declares `no`, and
+  `:for from=1 counter=i to=2` binds `i`, so later `$` references link;
+  previously the argument name was declared and a reordered `counter=` left
+  `$i` unbound.
+- EC-SRP5 hashes shared `z` and the REDP1 loop seed minimal-length, as
+  RouterOS does (#565). centrs padded both to 32 bytes, following `mtwei.c`.
+  As a result, about 1 in 256 MAC-Telnet logins failed on a short `z`. On
+  both MAC-Telnet and btest, every login failed for an account whose salt hit
+  the REDP1 edge, about 1 in 317 password changes. btest's `z`-only workaround
+  (#516) is replaced by the shared fix.
+- mac-telnet with an explicit directed-broadcast `--host` (`192.168.74.255`)
+  sends the owning interface's real MAC (#546, #547). On Linux, `connect()` to
+  a broadcast reports `0.0.0.0`, so the session fell back to a synthetic
+  source MAC, which hardware ignores: a 30 s timeout on an RB1100Dx4 running
+  7.26beta3. On that unit a real MAC gets a reply in ~0.35 s and a synthetic
+  one none. CHR answers both, so the CHR suite never saw it.
 
 ### Maintenance
 
@@ -200,6 +359,10 @@ part of this section.
   (Security tab), and locally with `bun run lint:actions` (#266). Its first
   run found two `${{ … }}` expansions inside shell scripts, in `lab.yaml` and
   `qa.yaml`; both now go through `env:`.
+- The unit tier no longer reads the developer's `~/.config/tikoci` state
+  (settings, CDB) (#550, #557). A `bunfig.toml` preload sandboxes `HOME` and
+  `XDG_CONFIG_HOME`, so a real and a fake home give the same result. Ambient
+  `CENTRS_*` variables are still read.
 
 ## 0.1.8 — 2026-10-12
 

package/GLOSSARY.txt

@@ -94,6 +94,7 @@ cwd
 datagram
 davidanson
 DDNS
+dsv # `:serialize to=dsv` delimiter-separated-values format (RouterOS 7.x); the #374 comma-value control pins offline acceptance of a `delimiter=,` value
 dialable # an endpoint a client can actually connect to (advertised AND reachable)
 defconf
 demux
@@ -116,6 +117,7 @@ fat-chr
 figcaption
 FlaUI
 frontends
+frontmatter # YAML metadata block at the top of a Markdown file (e.g. instruction applyTo headers)
 haakonnessjoen
 Hammerspoon
 HMAC
@@ -373,6 +375,8 @@ underflows
 Werror
 
 # MTWEI / EC-SRP vocabulary (src/protocols/mtwei.ts, mac-telnet auth)
+# libucrypto: RouterOS's shared cryptography library; EC-SRP5 encoding source.
+libucrypto
 # docrypto: mtwei.c's client EC-SRP proof function (mtwei_docrypto), ported to TS.
 docrypto
 # redp: REDP1 (IEEE P1363.2) random-point derivation used in the MTWEI tangle.
@@ -721,8 +725,11 @@ 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`
+easymesh # `/interface/wifi/easymesh` — once a doc spelling of `/interface/wifi/wps-push-button`; published as its own ungated menu since 2026-10-30, in no CHR tree through 7.26beta3
 wps # Wi-Fi Protected Setup — `/interface/wifi/wps-push-button`
+bss # Wi-Fi basic service set — `/interface/wifi/easymesh/bss`
+dpp # Wi-Fi Device Provisioning Protocol — `/interface/wifi/easymesh/dpp-trigger`
+overcurrent # `/system/resource/hardware/reset-overcurrent`, gated by syscap `usb-hub`
 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
@@ -807,6 +814,7 @@ zzznotamenu # a menu name no RouterOS build has — `/ip { zzznotamenu { print }
 # #361 absent-menu controls. Deliberate NON-words: each names a path no RouterOS
 # build has, or quotes a published gate verbatim, so the spelling is load-bearing.
 nosuch # a top-level menu no RouterOS build has — `/nosuch` is `bad command name nosuch` on CHR 7.23.7, the `validation/unknown-path` control (#361)
+nosuchcmd # a root command no RouterOS build has — `:local varID [nosuchcmd where name=x]` is `bad command name nosuchcmd (line 1 column 15)` on CHR 7.25 and 7.23.8, the #374 unknown-command control
 nosuchmenu # a submenu no RouterOS build has — `/ip/nosuchmenu/print` is `syntax error (line 1 column 15)` on CHR 7.23.7, pointing at the `/` after it (#361)
 nosuchverb # a command no RouterOS build has under a real menu — `/ip/address/nosuchverb` is `bad command name nosuchverb` on CHR 7.23.7 (#361)
 qqq # the second segment of the parse-oracle row `/zzz qqq print`, captured on CHR 7.23.3 (GH#230)
@@ -821,3 +829,17 @@ apptraffic # two paths new in 7.26beta1 with different published gates: the `/to
 rle # the corpus's `highlight-rle-v1` response encoding: each highlight stream stored as run-length `[class, count]` pairs, decoded by `decodeHighlightRuns` in scripts/corpus-db.ts (#498)
 removenumbers # the IL head `/ip/firewall/address-list/removenumbers=…` that `remove [find …]` renders as, quoted verbatim in the bracket-`=` corroboration test (#498)
 vscod # the last segment of a corpus path the forum importer truncated at its slug limit (`…-editors-like-vscod/post-0014-snippet-02.rsc`); cited as the path, so the spelling must match the corpus row (#498)
+
+# #358/#371 unquoted-byte controls. Deliberate NON-words: each puts a non-ASCII
+# byte where RouterOS reads only ASCII, so the spelling is the probe.
+systemé # `/systemé/identity print` — a non-ASCII byte in a path, `expected command name` at the `é` on CHR 7.24.5/7.23.8 (#371)
+printé # `/system/identity printé` — a non-ASCII byte in a verb, rejected at the `é` (#371)
+namé # `/system/identity/set namé=x` — a non-ASCII byte in a menu command's argument name, rejected at the name's first byte (#371)
+addré # `/ip/address/add addré=1` — as `namé`: the device reports the argument name's first byte, not the `é` (#371)
+caf # the ASCII prefix the device reads of `café` before the `é`: `:put "a$café"` is `$caf` then `é` (#371)
+
+# #225 live value types: CLI Reference `Type` cell spellings the schema vocabulary maps.
+iface # the CLI Reference type `iface_enum`: an argument that names an interface, which `schemaType` calls `name` (#225)
+ubit # the CLI Reference type `ubit (…)`: a set of listed bits, e.g. `ubit (pap, chap, mschap1, mschap2)`, a list of `enum` (#225)
+forcounter # the IL head `/forcounter=$i;…` that `:for i …` renders as; quoted verbatim in the #225 directive-argument probe test (#225)
+foreachcounter # the IL head `/foreachcounter=$i;…` that `:foreach i …` renders as, in any `counter=` order; quoted verbatim in the #533 reorder test (#533)

package/README.md

@@ -1,8 +1,8 @@
 # centrs
 
 `centrs` is the tikoci RouterOS interaction hub: a Bun/TypeScript library and
-CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
-RouterOS devices through a regularized, validated interface.
+CLI (with an MCP server; 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:
@@ -40,7 +40,8 @@ product; without them this would just be a worse `curl`.
 > 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.
+> encrypted-CDB reads and writes are supported, 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.
 
@@ -49,9 +50,10 @@ product; without them this would just be a worse `curl`.
 - **Frontends:** TypeScript API, CLI, MCP server (Phase 1 + first Phase 2 CDB
   mutation `CHR-passed` — see `commands/mcp/`), TUI and HTTP proxy/daemon
   (future).
-- **Protocols:** REST API (preferred), native API, and SNMP for reads;
-  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
+- **Protocols:** REST API and native API for reads and writes; SSH / MAC-Telnet
+  for execution and interactive terminals; SFTP for file transfer; MNDP for
+  discovery; bandwidth test for peer measurement. SNMP, RoMON and WinBox
+  Terminal are planned. centrs picks the protocol for you (and lets you pin one
   with `via=` or `--via`).
 - **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.
@@ -60,12 +62,14 @@ product; without them this would just be a worse `curl`.
 
 | Command    | Purpose |
 | ---------- | ------- |
-| `retrieve` | Read RouterOS state over REST/native API and SNMP OID/MIB values. `--follow` keeps a menu's rows current over native API (snapshot, then a line per change; NDJSON); `--sample <interval>` re-reads it on a timer for counters; `--query` filters on the router with the `print where` grammar; `--wait` retries until a read succeeds (or an optional `--until` condition holds), up to a deadline. |
+| `retrieve` | Read RouterOS state over REST/native API. `--follow` keeps a menu's rows current over native API (snapshot, then a line per change; NDJSON); `--sample <interval>` re-reads it on a timer for counters; `--query` filters on the router with the `print where` grammar; `--wait` retries until a read succeeds (or an optional `--until` condition holds), up to a deadline. SNMP OID/MIB reads are planned. |
 | `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. Follow changes with `api … <menu>/listen`; `--stream` streams any command's replies (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
+| `transfer` | Upload, download and manage device files over REST/native API or SFTP; `upload` and `download` are shortcuts. |
+| `btest`    | Run a MikroTik bandwidth-test client or server over TCP/UDP. |
 | `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. |
+| `explain`  | Analyze RouterOS source offline, or add read-only device evidence over REST/native API, including path schemas, completion candidates and value types. Runtime acceptance remains unproven. |
 | `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. |
@@ -168,18 +172,24 @@ so you can always see *why* a given port or transport was chosen.
 
 `devices` is the only command that writes the CDB, and it does so safely
 (timestamped backup, atomic rename, unknown WinBox fields preserved verbatim).
-Encrypted-CDB **reads** work with `--cdb-password` / `CENTRS_CDB_PASSWORD`;
-encrypted **writes** are currently blocked pending a verified WinBox round-trip.
+Encrypted-CDB reads and writes work with `--cdb-password` /
+`CENTRS_CDB_PASSWORD`; writes decrypt, mutate and re-encrypt with a fresh salt.
+`devices init --encrypt` creates an encrypted registry, and `devices encrypt`
+explicitly converts an existing open CDB. Conversion retains existing backups
+and warns that plaintext copies remain. The manual WinBox round-trip is still
+pending; see the per-command contract for the current evidence and limits.
 The full contract — identity resolution, ambiguity handling, write strategy,
 and the comment grammar — lives in `commands/devices/README.md` and
 `docs/CONSTITUTION.md` (Identity and CDB).
 
 ## The result envelope, validation, and errors
 
-- **Validation is on by default** (`validate=true`). Reads are checked through
-  `/console/inspect`; CLI-shaped `execute` commands through `[:parse]`. Set
-  `validate=false` (per device or per call) only as a deliberate escape hatch.
-- **Every call returns one envelope:** `{ ok, data?, warnings?, error?, meta }`,
+- **Validation is on by default** (`validate=true`). CLI-shaped `execute` and
+  `api /execute` scripts pass the offline analyzer before device validation.
+  Reads are checked through `/console/inspect`; CLI-shaped commands through
+  `[:parse]`. Set `validate=false` (per device or per call) only as a deliberate
+  escape hatch.
+- **Every call returns one envelope:** `{ ok, data?, warnings, tips, error?, meta }`,
   with provenance and source-of-truth reporting in `meta`.
 - **Errors are typed values**, not thrown strings, with slash-namespaced codes
   (`routeros/…`, `transport/…`, `validation/…`, `cdb/…`) and a `details_url`
@@ -250,7 +260,9 @@ 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
-real CHR via `bun run test:integration`. Code existing is not done. Unit tests
-passing is not done. Full rule:
-`.github/instructions/done-definition.instructions.md`.
+Live capabilities require every applicable example in `commands/<name>/examples.md`
+green on real CHR via `bun run test:integration`. Offline analysis requires its
+command README's full baseline acceptance criteria, including committed
+CHR-grounded semantic evidence. The fixture-backed `devices` and `settings`
+integration suites retain their command-specific contracts. Full rule:
+[`docs/CONSTITUTION.md` → Done definition](docs/CONSTITUTION.md#done-definition).

package/commands/api/AGENTS.md

@@ -87,8 +87,9 @@ stack-language access without centrs modelling the whole query grammar.
 
 ## CONFIRMED ON CHR (Phase 0 grounding spikes — CHR 7.23.1, 2026-06-29)
 
-Probes: scratchpad `api-grounding-spike.ts` (listen/CRUD/execute) and
-`api-grounding-spike2.ts` (duration/monitor + query forms + inspect path). Raw
+Probes (phase-0 lab history, not runnable methods): `api-grounding-spike.ts`
+(listen/CRUD/execute) and `api-grounding-spike2.ts` (duration/monitor + query
+forms + inspect path). Raw
 native codec for the listen probe; `fetch` for REST; `connectNativeApi().talk()`
 for native.
 
@@ -184,7 +185,7 @@ green on CHR 7.23.1.
   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"`.
+  is a CLI string ⇒ no `meta.validation.semantic` field (#535).
 
 ## CONFIRMED ON CHR (RouterOS 7.12.2 compatibility — GH#343, 2026-09-14)
 
@@ -197,6 +198,23 @@ green on CHR 7.23.1.
   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.
+- **Command-level `request=syntax` is unsafe too, on 7.12.2 and 7.20.8** (#492,
+  2026-10-19, reproduced on a fresh boot of each).
+  - REST: `syntax` with `path=` set to a command (`ip,address,set`,
+    `system,identity,set`, `ip,route,add`, `interface,print`) got no answer
+    within 12 s, 5 of 5 times. The `child` controls queued behind it timed out
+    until the handler recovered about 30 s later.
+  - Native API closed the connection.
+  - The same syntax requests at a menu (`ip,address`) or an argument
+    (`ip,address,set,address`, `put,message`, `do,command`) answered in about
+    25 ms. 7.23.8 and 7.24.5 answer every shape.
+  - restraml's crawlers send `syntax` to `arg` nodes only, so `inspect.json`
+    never exercised the hanging shape.
+  - Input-based `completion` (`input="/ip/address add comm"`) answered at every
+    position tried on both builds, including scripting keywords and `do={`
+    bodies on 7.20.8.
+  - Explain's `--schema`/`--complete` therefore send `syntax` for argument
+    paths and `completion` with `input=` only.
 
 ## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
 

package/commands/api/README.md

@@ -51,7 +51,14 @@ centrs api <router> <endpoint> [flags]
   segment (`ip/address/*1`) addresses one row for GET/PATCH/DELETE; PUT and
   POST reject it with `input/invalid-path`. A trailing `/listen` segment is
   the menu's `listen` command, which implies `--stream` + `--via native-api`
-  and requires GET (`ip/address/*1/listen` follows one row).
+  and requires GET (`ip/address/*1/listen` follows one row). After that
+  normalization every menu segment must be a RouterOS menu name (letters,
+  digits, hyphens; case folds), or the request fails with
+  `input/invalid-routeros-path` before any transport is chosen, whatever
+  `--validate` says. A `#` or `?` once cut `/print` off a projected GET's
+  REST URL and posted the bare command (`/system/reboot#` rebooted CHR 7.24.5,
+  #586); the grammar and retrieve's REST guard are described in
+  [retrieve → Validation](../retrieve/README.md#validation).
 
 The HTTP method (`-X`, default `GET`) is honored **literally** against RouterOS's
 REST mapping — `GET`→print/get, **`PUT`→add**, `PATCH`→set, `DELETE`→remove,
@@ -114,7 +121,9 @@ vs `--query` distinction.
   before they were sent, keep the `transport/network` /
   `transport/connection-closed` retry. A mutating request that failed after it
   was sent carries the warning `transport/write-outcome-unknown`, in single-target
-  and fan-out mode alike.
+  and fan-out mode alike. A multi-statement `/execute` script refused with
+  `routeros/permission-denied` carries the same warning (#549); a single
+  refused statement, and a refused structured request, stay silent.
 - **`--stream` (or a `/listen` endpoint) is single-session** → `usage/fanout-not-supported` in
   fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
   fan-out mode (per-target envelopes can't be bare).
@@ -134,7 +143,8 @@ 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 structured inspect is `not-applicable` (`meta.validation.semantic`). It
+  so structured inspect does not apply and `meta.validation.semantic` is
+  absent. 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.
@@ -148,10 +158,11 @@ gate is `/console/inspect` — **not** `:put [:parse]`:
   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
-  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.
+  unlisted-path decision. `meta.validation.stages[]` reports the offline stage
+  `skipped` with that reason, on success and on a `validation/*` rejection
+  alike, so the breakdown never implies an analysis that did not run. On
+  success the device stage is `passed`, `semantic` is `true`, and there is no
+  `syntax` field, because no `:parse` ran (#535).
 
 `--validate=false` skips **both** stages of the preflight — one flag, one meaning
 (constitution: validation); RouterOS still re-validates writes server-side.

package/commands/api/examples.md

@@ -156,7 +156,7 @@ 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.syntax=true` with no `semantic` field (script, not a path) and
 `meta.validation.stages` is `offline: passed` then live `device: passed` from
 `:put [:parse ...]`.
 

package/commands/btest/README.md

@@ -139,6 +139,15 @@ is net-new — `mtwei.ts` only implements the client. A bad proof (or a client t
 will not offer EC-SRP5 against an `authenticate=yes` server) maps to
 `transport/auth-failed`. Legacy pre-6.43 double-MD5 is out of scope for v1.
 
+The shared core hashes minimal-length big-endian integers in the REDP1 loop
+and for shared-point `z`; public keys and the REDP1 input keep their fixed
+32-byte X encoding (#565). The distinction is grounded in RouterOS
+`libucrypto.so` 6.49.23/7.25 and `tikoci/m2ir`'s live WinBox discriminators.
+`test/fixtures/ec-srp5.json` pins calculated regression transcripts;
+`test/integration/ec-srp5.test.ts` forces the encoding edges against a real
+CHR btest client, including a short `z` and a leading-zero REDP1 input
+(confirmed on CHR 7.23.8 and 7.25).
+
 ## Output
 
 btest runs over time, so it emits **live records** during the run plus a final

package/commands/btest/examples.md

@@ -99,6 +99,13 @@ and non-zero throughput. This is the example that exercises the net-new
 server-side EC-SRP5 verifier against real RouterOS (TCP keeps the gated path off
 the SLIRP UDP-reverse-NAT question).
 
+`test/integration/ec-srp5.test.ts` also exercises this exchange with chosen
+test salts and ephemeral scalars, one edge per pass: a short REDP1 loop hash
+input, a REDP1 input whose leading zero must stay, and that input again with a
+forced short shared `z`. RouterOS's client proof must match the minimal-length
+derivation. This discriminator stops at the
+proof; the normal btest suites cover completed sessions and throughput (#565).
+
 ### 4. Wrong credentials are rejected
 
 > *Designed, not yet gated* — the auth-reject path is asserted by the loopback

package/commands/devices/README.md

@@ -89,6 +89,17 @@ or a duplicated `identity=`):
   lists all matching entries (by `cdbRecordIndex`, `target`, `user`, and
   `recordType`). The caller pins the choice with `--match` by `user`
   (`--match user=admin`), by record-type (`--match ipUser`), or by exact target.
+  `--match` takes the same selector on `devices show`/`set`/`remove` and on
+  every command that resolves a `<router>` from the CDB: `retrieve`,
+  `execute`, `api`, `transfer`, `terminal` and `btest client` (#583). It is a
+  single-target flag: with a fan-out selection or `--quickchr` it is
+  `usage/conflicting-flags`, and when no CDB record is in play (no CDB, an
+  unregistered literal host, a `__default__`-only fallback, or `--host`
+  without `<router>`) it fails `identity/no-match` rather than being ignored.
+  With no target at all (no `<router>`, no `--host`) the CLI still reports
+  the missing-target usage error first.
+  An ambiguous positional inside a fan-out names the single-target
+  `--match` re-run, since the fan-out itself refuses the flag.
 
 `--prefer-family=ipv4|ipv6` is a non-interactive way to break v4/v6 ties
 deterministically; with it set, no prompt is raised. It emits a warning
@@ -141,6 +152,15 @@ Rules:
 - An **empty value removes** the token: `devices set <t> via=` deletes the `via`
   override (matching the internal upsert/remove model in `comment-kv.ts`). There
   is no current need to store a literally-empty value; revisit if one arises.
+  Removing a token that is already absent is a no-op success — the comment is
+  left byte-for-byte identical.
+- First-class fields have their own empty-value rules, distinct from token
+  removal: `--password ""` clears the stored password (and its saved-password
+  flag); `--user ""` writes an empty user. Bare `user=` / `password=` /
+  `group=` / `profile=` / `session=` positionals never reach those fields —
+  they are refused with `cdb/reserved-key` — so comment-token removal (`key=`
+  deletes the token) and credential clearing (`--password ""` empties the
+  password) are deliberately different operations.
 - `commentMirror` is kept in sync with `comment` on every write.
 
 Precedence (lowest → highest): built-in defaults → user config file
@@ -340,7 +360,8 @@ runs produce stable diffs.
 ## Subcommands
 
 ```text
-centrs devices init                     # create an empty CDB at the resolved path
+centrs devices init [--encrypt]         # create an empty CDB at the resolved path
+centrs devices encrypt [--no-backup]    # explicitly encrypt an existing open CDB
 centrs devices list [--group G] [--where attr=value]
                     [--near lat,lon,radius] [--bbox south,west,north,east]
                     [--format json|yaml|text]
@@ -370,9 +391,11 @@ 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`,
+- `init` creates an empty CDB (open by default, encrypted with `--encrypt`)
+  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
+  It never overwrites: on an existing, readable CDB matching the encryption
+  requirement 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`.
@@ -437,6 +460,52 @@ can edit it too. Precedence is per-field: args → env → device record →
   **MCP** it never widens the allowlist — an unregistered target is still
   rejected; `__default__` only fills missing creds for a registered device.
 
+## CDB encryption lifecycle (#558)
+
+Start encrypted with `devices init --encrypt`, or start open for a lab and run
+`devices encrypt` when moving to production. Both require a non-empty
+`--cdb-password` / `CENTRS_CDB_PASSWORD`. A password alone does not change the
+mode of initialization or ordinary writes. The library exports
+`initCdb({ encrypt: true, cdbPassword, cdbFile })` and
+`encryptCdb({ cdbPassword, cdbFile })`; both use the shared settings precedence.
+
+Encrypted initialization keeps atomic no-clobber creation and mode `0600`.
+Initialization returns `data.encrypted` for both newly created and existing
+files. Competing encrypted initializers with different passwords fail closed:
+the loser gets `cdb/decrypt-failed` when it cannot unlock the winner's file.
+An existing open CDB refuses `init --encrypt`; conversion must be explicit.
+An existing encrypted CDB is verified with the supplied password and left alone.
+Conversion requires an existing readable CDB, preserves its records and unknown
+fields, uses a fresh salt and atomic replacement, and keeps its file mode.
+`data` reports `cdbFile`, `encrypted: true`, `changed`, `recordCount`, and the
+new `backupPath` when conversion occurred. Default text output reports
+`encrypted` or `verified encrypted ... (unchanged)`, the record count, and
+the backup path when created, followed by the plaintext-backup warning.
+Already-encrypted conversion verifies
+the password and returns `changed: false` without rewriting or rotating it.
+
+**Backups remain sensitive.** Conversion retains every existing backup and
+creates a plaintext snapshot of the original; it does not run backup retention.
+The `cdb/plaintext-backups` warning accompanies conversion, including no-op runs:
+only the active file is protected. Handle backups according to your own retention
+policy; centrs neither encrypts nor deletes them during conversion. Subsequent
+ordinary writes still use the normal five-backup retention below.
+`--no-backup` (library: `skipBackup: true`) skips the new plaintext snapshot, so
+no fresh plaintext copy is written; earlier backups are still retained and the
+warning still applies to them. Without the snapshot, a forgotten password cannot
+be recovered.
+
+`init` and `encrypt` act on the CDB file, not on records: they accept only
+`--cdb-file`, `--cdb-password`, `--format`/`--json`, plus `--encrypt` (`init`)
+or `--no-backup` (`encrypt`). Any other flag is `input/invalid-command`
+instead of being silently ignored.
+
+Close WinBox and other CDB writers before conversion. If they share this path,
+they must reopen it using the CDB password; a stale writer can overwrite the
+conversion. Atomic replacement does not provide concurrent-writer transactions
+(#581). Password rotation and decryption are outside this slice. WinBox manual
+interoperability verification remains open (see Residual risks).
+
 ## CDB write strategy
 
 All writes go through one helper (`writeWinBoxCdb`) that: