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

package/CHANGELOG.md

@@ -17,6 +17,18 @@ 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`.
@@ -92,6 +104,16 @@ 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
 
@@ -201,6 +223,35 @@ 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
@@ -277,6 +328,12 @@ part of this section.
   `: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

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)

package/README.md

@@ -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.
 

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,

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:

package/commands/devices/examples.md

@@ -651,7 +651,7 @@ centrs devices add 192.0.2.1 --user robot-reader --cdb-file ./lab/winbox.cdb --j
 ```
 
 Creates missing parent directories and an empty open CDB with mode `0600`.
-`data` is `{ cdbFile, created: true, recordCount: 0 }`. The `add` then succeeds.
+`data` is `{ cdbFile, created: true, encrypted: false, recordCount: 0 }`. The `add` then succeeds.
 
 ### 55. `init` never clobbers
 
@@ -660,8 +660,63 @@ centrs devices init --cdb-file ./lab/winbox.cdb --json
 ```
 
 On an existing, readable CDB: `ok: true`, `data.created: false`,
+`data.encrypted` reports the actual encryption mode,
 `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`.
+
+### 56. Initialize encrypted from the start
+
+```bash
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices init --encrypt --cdb-file ./prod.cdb --json
+```
+
+Creates a complete encrypted empty CDB with mode `0600`; subsequent loads require
+that password. `data.encrypted` is `true`. Re-running verifies the password
+and reports `created: false`, `encrypted: true`.
+Test: `centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 57. Convert a lab CDB to encrypted
+
+```bash
+centrs devices init --cdb-file ./lab.cdb
+centrs devices add 192.0.2.1 --user reader --cdb-file ./lab.cdb
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices encrypt --cdb-file ./lab.cdb --json
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices list --cdb-file ./lab.cdb --json
+```
+
+Conversion reports `encrypted: true`, `changed: true`, `recordCount: 1`, and
+`backupPath`. Records survive a password-protected reload; loading without a
+password fails. All backups remain, including the plaintext pre-conversion file;
+`cdb/plaintext-backups` warns explicitly. Repeating with the same password returns
+`changed: false`; a wrong password fails without writing. Without `--json`,
+text reports conversion or verified unchanged, the record count, and the
+plaintext snapshot path when created; the warning remains visible.
+Test: `centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 58. Encryption intent fails closed
+
+`init --encrypt` and `encrypt` refuse a missing or empty CDB password before
+creating anything. `init --encrypt` refuses an existing open CDB without changing
+it. `--encrypt` on other subcommands and positional targets on `encrypt` are
+invalid commands. Record, selection, and provenance flags (`--user`, `--group`,
+`--password`, `--via`, …) on `init`/`encrypt`, and `--no-backup` on anything but
+`encrypt`, are `input/invalid-command` rather than silently ignored. Test:
+`centrs devices encryption (#558)` in `test/integration/devices.test.ts`.
+
+### 59. Convert without a plaintext snapshot
+
+```bash
+centrs devices init --cdb-file ./lab-fresh.cdb
+centrs devices add 192.0.2.1 --user reader --cdb-file ./lab-fresh.cdb
+CENTRS_CDB_PASSWORD="$CDB_SECRET" centrs devices encrypt --no-backup --cdb-file ./lab-fresh.cdb --json
+```
+
+A fresh path, so it does not depend on example 57 having already converted
+`./lab.cdb`. Conversion reports `changed: true`, `recordCount: 1`, and no
+`backupPath`, and no new `.bak.*` file appears. The backup the `add` wrote
+is retained, so
+`cdb/plaintext-backups` still warns. Test: `centrs devices encryption (#558)`
+in `test/integration/devices.test.ts`.

package/commands/execute/README.md

@@ -529,6 +529,17 @@ How it is wired:
   but rejects the MD5 proof, so centrs advertises MTWEI (`src/protocols/mtwei.ts`)
   by default. `END_AUTH` ≠ success (a failed login emits `END_AUTH` then "Login
   failed" + `END`) → `transport/auth-failed`.
+- **MTWEI hash encoding (grounded, #565):** RouterOS hashes shared `z` and the
+  REDP1 loop seed minimal-length; `haakonnessjoen/MAC-Telnet`'s `mtwei.c` pads
+  both to 32 bytes. When they differ, the padded proof fails. On CHR 7.25 over
+  the L2 harness (2026-10-31): short-`z` logins accepted the minimal proof 8 of
+  8 and rejected the padded proof 1 of 1 (about 700 logins). The `z` edge hits
+  about 1 in 256 logins. The REDP1 edge depends on the salt RouterOS generates
+  at each password change, about 1 in 317 changes; it fails every login until
+  the next change. A password-rotation scan over raw handshakes to PASSSALT
+  found divergent salts, and on one the minimal proof was accepted 3 of 3 while
+  the padded proof was rejected 3 of 3, all with a clean 32-byte `z` to isolate
+  the edge. The shared core is `src/protocols/ec-srp5.ts`.
 - **Console quirks to know:** a successful write **prints no output** (no `.id`,
   unlike REST/native — `data.ret` is empty on a successful add); and there is a
   ~10s terminal-negotiation stall on every login (a latency cost, not a