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

package/commands/explain/README.md

@@ -257,6 +257,22 @@ today's path/verb/args split and script-vs-structured gate:
   `/interface/wifi/dashboard` and `/system/dashboard` are `inspect` only: the
   trees carry them, the manual publishes no menu entry for them.
 
+  **Source refresh (accepted 2026-10-30).** The CLI Reference added
+  `compare-versions`, a version-comparison widget page with no `**Type:**`
+  entry. `llms.txt` lists it as a page and the sitemap serves it as a category
+  URL, so it aborted the parser and would have aborted the orphan-dir check.
+  It joins `index` as a hand-audited non-command slug, excluded from both
+  inventories. The CLI Reference moves from 1,099 pages / 1,106 entries to
+  1,109 / 1,116; the inspect pins and the 636-menu union are unchanged. The
+  catalog grows from 1,166 to 1,176 paths: 1,005 `both`, 67 `inspect`, 104
+  `published`. It adds 10 paths and removes none, with no kind change and no
+  provenance loss. The additions are `/app/settings/remove-certificate`, three
+  `/system/resource/hardware` commands (`power-cycle`, `power-reset`,
+  `reset-overcurrent`), and `/interface/wifi/easymesh` with five children. The
+  three `/cmr/client` gate strings drop `!powerpc`. easymesh is published with
+  no gate and is in no CHR tree through 7.26beta3, so the unexplained residue
+  grows from `/root/terminal` alone to seven paths.
+
 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
@@ -3007,6 +3023,202 @@ a process boundary. A B5 rename is therefore a visible break here rather than a
 silent one — which is the point of settling the vocabulary before an external
 consumer commits to it.
 
+## Topic checks and related live reads (#493, design — no implementation)
+
+This section is the bounded design #493 asks for. It proposes shapes, ownership,
+and acceptance gates; **no topic check, special-command rule, or contextual
+read ships with it**. Each check needs its own accepted/rejected CHR controls
+and committed evidence before an implementation slice lands, and every new
+RouterOS semantic claim is grounded then — not here. The three examples below
+are **SYNTHETIC shape illustrations, not device claims**: they show the envelope
+a check would produce, with invented content, so reviewers can judge the
+contract without mistaking illustration for evidence.
+
+**Ownership: one rule table, three consumers.** Fact and check definitions live
+in one module beside the analyzer (sibling of `src/explain/write.ts`, which is
+the precedent: an explain-only inference over the shipped structure). The
+CLI renders it, the library returns it, and the MCP adapter reshapes the same
+object — no copies of rule logic per surface. Checks evaluate against the
+**statement tree** (`structure.statements[]` ids plus `parent`/`owner` links),
+never against byte containment: a finding anchors to a statement id and its
+span, so a reordered document moves the finding with its statement.
+
+**Findings reuse the shipped envelope — no new finding object.** A check emits
+what explain already emits: an `ExplainDiagnostic` (`code`, `severity`,
+`message`, `span`, `ev`) for the finding, the `ExplainEvidence` entry it cites
+(`id`, `source`, `probe`, `basis`, `outcome`, `statementIds`) for how it was
+decided and which statement it anchors to, and a `tip` (`code`, `message`,
+`fix`) for the next step. Codes follow `explain/<source>/<slug>`, with the
+check family as the slug prefix (`topic-…`, `special-command-…`). Topic
+findings are `info`: like the pasted-prompt tip, advice never moves
+`data.verdict`, which stays the validity answer. A check that should raise the
+verdict is a separate, explicitly decided change, not a default. Certainty is
+the cited evidence's `basis` — `heuristic` for a ratified rule over the
+offline structure (the `containsWrite` precedent), `derived` once it rests on
+live responses — so how sure a finding is reads from the same field as every
+other explain fact.
+
+**What is decided where.** Source-only: structural facts the canonicalizer
+already proves (unresolved statements, write-shape, symbol bindings). Live
+schema: what a menu accepts (argument names, enums) — only `--schema` /
+`--complete` against a named router, never a bundled snapshot (decision 3).
+Device observations: current state (`print` rows) — only through an explicitly
+requested contextual read (below). Partial script input is never treated as
+final device state, and a finding never grants execution permission: advice
+and the execution gate are separate answers, and a lost read response is
+reported as a failed read, never as a successful execution.
+
+**Contextual reads are opt-in and bounded.** The default offline entry stays
+network-free; naming a router does not authorize reads. A contextual read
+fires only under an explicit flag (name TBD, e.g. `--with-print`), one bounded
+`print` per confidently resolved menu, projected and truncated, each reported
+independently with its read command, time, projection, and truncation — so an
+agent can distinguish current observed state from the proposed script. The
+target is the envelope's `meta.target`, not a per-read field. Deduplication is by (statement id, resolved path): two
+statements in one menu share one read, and a failed read fails alone. The
+read is a validated centrs `retrieve` on the resolved path — never the user's
+`[find]`, expression, or analyzed script executed to get context.
+
+**Secrets follow the existing redaction contract.** Related reads ride the
+redaction paths from #359: secret-bearing menus and verbose file output are
+high-risk surfaces, so a contextual read defaults to a non-sensitive
+projection, names its projection explicitly, and never exports key material
+into advice artifacts or logs. A check whose finding would need a sensitive
+field states that need in its definition and is refused without an explicit
+sensitivity opt-in — no automatic sensitive exports.
+
+**Shape 1 — a grounded topic finding (synthetic illustration).**
+Input `SYNTHETIC-1` (illustrative only):
+`/ip service set telnet disabled=no` — a statement the analyzer resolves with
+id `s0`, span 0–34. A management-plane topic check (definition owned beside
+the analyzer, evaluated against `s0`) adds one diagnostic, the evidence entry
+it cites, and a tip; the ids and the check's `probe` name are invented. A
+partial envelope — only the fields the finding adds or reads are shown:
+
+```json
+{
+  "data": {
+    "verdict": "pass",
+    "diagnostics": [
+      {
+        "code": "explain/canonicalizer/topic-plaintext-management-service",
+        "severity": "info",
+        "message": "This enables telnet, a plaintext management service.",
+        "span": { "start": 0, "end": 34 },
+        "ev": "e10"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "e10",
+        "source": "canonicalizer",
+        "probe": "topicPlaintextManagementService",
+        "basis": "heuristic",
+        "outcome": "ok",
+        "statementIds": ["s0"]
+      }
+    ]
+  },
+  "tips": [
+    {
+      "code": "tip/explain-topic-plaintext-management-service",
+      "message": "Telnet sends credentials in clear text.",
+      "fix": "Disable the plaintext service or restrict it to a management address list."
+    }
+  ]
+}
+```
+
+The verdict stays `pass`; probe outcome and `runtimeAcceptance` are untouched —
+the finding does not claim the router accepted anything.
+
+**Shape 2 — a special-command fact (synthetic illustration).** #363 records
+the real cases (deferred there, not duplicated here); the shape is Shape 1's,
+with the `special-command-` slug family and a consequence, not a
+configuration judgement. Illustrative only:
+
+```json
+{
+  "code": "explain/canonicalizer/special-command-connection-loss",
+  "severity": "info",
+  "message": "This command can drop the session that runs it.",
+  "span": { "start": 64, "end": 79 },
+  "ev": "e11"
+}
+```
+
+`e11` cites `statementIds: ["s2"]`, and the paired tip's `fix` says to run it
+from a path that survives the change.
+
+No isolated device-mode table ships first (the #363 deferral stands); a
+special-command fact names its consequence and its evidence, nothing more.
+
+**Shape 3 — an explicitly requested contextual read (synthetic illustration).**
+Input (illustrative): `/ip address add address=198.51.100.1/32 interface=ether1`
+with an explicit `--with-print`-style opt-in. The read follows the live
+argument-name precedent (`data.live.arguments[]` cites a `live-inspect`
+evidence entry): one evidence entry per read, and the rows in `data.live`
+citing it, independent of the analysis verdict. A partial `data` object —
+`evidence` is `data.evidence`, `live` is `data.live`:
+
+```json
+{
+  "evidence": [
+    {
+      "id": "e12",
+      "source": "live-read",
+      "probe": "print",
+      "basis": "direct",
+      "outcome": "ok",
+      "version": "SYNTHETIC-version",
+      "observedAt": "SYNTHETIC-timestamp",
+      "statementIds": ["s0"],
+      "path": "/ip/address",
+      "projection": ["address", "interface", "disabled"],
+      "truncation": { "returned": 3, "total": 12 }
+    }
+  ],
+  "live": {
+    "reads": [
+      {
+        "ev": "e12",
+        "path": "/ip/address",
+        "statementIds": ["s0"],
+        "rows": [
+          { "address": "192.0.2.1/24", "interface": "ether1", "disabled": "false" },
+          { "address": "198.51.100.2/24", "interface": "ether2", "disabled": "false" },
+          { "address": "203.0.113.1/24", "interface": "bridge", "disabled": "true" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The target is the envelope's existing `meta.target`, not a per-read field.
+Three additions are proposed, not shipped: the `live-read` evidence source,
+the `projection` and `truncation` evidence fields, and `data.live.reads[]`.
+Originating statement and path, time, projection, and truncation are all
+present, so observed state cannot be mistaken for the proposed script. A
+failed read reports its `outcome` with `reason`/`errorCode` and fails alone.
+
+**Acceptance controls and dependencies before implementation slices.**
+
+- Each check ships with accepted/rejected CHR controls and committed evidence;
+  synthetic shapes above are replaced by measured rows, never promoted as-is.
+- Controls assert statement-id anchoring (finding moves with its statement),
+  verdict independence (a finding leaves `data.verdict` unchanged), the cited
+  evidence's `basis`, and read independence (one failed read does not fail
+  the analysis or sibling reads).
+- A check that needs a sensitive field is refused without the sensitivity
+  opt-in; the redaction contract is asserted, not assumed.
+- Dependencies: published offline readings stay honest (#211, #350, #351,
+  #358, #371); live path/argument/probe facts come from #236; live value
+  types are distinct evidence (#225); the MCP result migration is separate
+  (#223); text stdout/stderr routing is unchanged (#477); device-mode
+  provisioning stays in #95. No new plugin DSL or framework is preselected —
+  existing `warnings`/`tips` and explain diagnostics are reused where they fit.
+
 ## Non-goals
 
 - No LSP server in centrs — the LSP is a consumer the library must support,
@@ -3272,14 +3484,22 @@ a missing mandatory value, and a name collision. That was verified rather than
 assumed — each blocker statement was replayed through `:put [:parse …]` and
 `/console/inspect request=highlight` on both versions and **accepted every
 time**, with controls (`no-such-attr=`, an unterminated string, a nonexistent
-menu) correctly rejected. So these results carry **no** implication about
+menu) correctly rejected by `:parse`. `highlight` is the weaker of the two: it
+marks only the nonexistent menu with an `error` class, reading the bad
+attribute as `obj-inactive` and the unterminated string as ordinary tokens, so
+the controls' rejection rests on `:parse`. So these results carry **no** implication about
 whether `explain` can parse the forms, and they do not license claims about the
 export styles in general: the captures come from one synthetic configuration on
 CHR, which has a single NIC and no switch or wireless hardware, so its defconf
 and its available menus differ from any real device's. Treat the provenance
 label as **L1-emitted, L2-refuted for these captures on CHR**. Harness and
-per-document results: `.scratch/explain-lab-q203-import-verify.ts`;
-validity check: `.scratch/q203-blocker-validity.ts`.
+per-document results: the q203 import-verify lab (history — see #203; its
+scripts and corpora were never promoted, so the counts above rest on those
+lab captures). Validity check: `bun run explain:probe:import-blocker-validity`
+(promoted from the q203 lab for #272; replays the four blockers plus the
+three rejecting controls through `:parse` and `highlight` on a disposable
+CHR per version; re-run on 7.23.2 and 7.24rc2 for #568, 6/6 and 7/7 rows
+agree).
 
 **Non-blocking / deferred (not ratification-gating):** Q5 expression depth, Q7
 tokenizer corners, Q9 potential-command taxonomy, Q12 span-vocabulary draft —

package/commands/explain/examples.md

@@ -888,7 +888,14 @@ centrs explain '[admin@MikroTik] > /ip address print' --json
 `data.verdict` is `fail` with `explain/canonicalizer/invalid-at-sign` at the
 `@`. The device answers `syntax error (line 1 column 7)`, the same byte. This
 is a pasted console prompt. `:put a@b` and `comment=a@b` pass, because a `@` is
-a value byte in an argument.
+a value byte in an argument. The envelope also carries
+`tip/explain-pasted-prompt` offering the stripped `/ip address print` as
+repair text (never applied). A `/menu>` prompt such as
+`/interface/lte> monitor lte1` keeps a `warn` abstention with the same tip
+shape, offering `monitor lte1` typed at `/interface/lte`. The manual's
+in-menu prompt `[admin@MikroTik] /ip/address> add …` fails the same way and
+offers `add …` typed at `/ip/address`; a HotLock `>>` is stripped with the
+prompt.
 
 ### 41. A named comparison brace inside a `[find where …]` is rejected
 

package/commands/retrieve/README.md

@@ -96,6 +96,23 @@ error code, so its reason is `not reached: interrupted` (#537). With
 If `--all-attributes` is combined with `--attribute(s)`, fail with
 `usage/conflicting-flags` *before* hitting the network.
 
+A read only ever dispatches a `print`/`get`, on every transport and even with
+`--validate=false`: that flag skips command validation, not the read/write
+split (#586). Each path segment must be a RouterOS menu name — letters,
+digits and hyphens (case folds), the grammar of every dir and command in the
+7.9–7.26 tree — or the read fails with `input/invalid-routeros-path` before
+resolution. Before this check, a `#` or `?` 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. A well-formed command
+path is safe: RouterOS answers `POST /rest/system/reboot/print` (and a `GET` of
+a command) with "no such command", and native API answers
+`/system/reboot/print` the same way (CHR 7.24.5). Under the REST adapter, a
+second guard refuses any request path containing `?`, `#`, `\`, a control
+character, or a `.`/`..` segment (including the percent-encoded `%2e%2e` and
+`.%2E` forms, which the URL parser also collapses) for every command. RouterOS
+does not decode percent-escapes in REST paths, so nothing else changes the
+target.
+
 SNMP validation is separate from RouterOS `/console/inspect`: OIDs and MIB
 names must resolve through the MIB cache before any SNMP request is sent.
 
@@ -524,7 +541,11 @@ stays the single-target envelope; a selector flag or a second positional target
 switches to fan-out. `--quickchr <name>` (the named-live-provider) behaves like a
 lone positional: one flag stays single-target, repeating it fans out, and mixing
 it with positionals or CDB selectors is `usage/conflicting-flags` (constitution:
-resolution providers). The `--host` **flag** with no `<router>` positional
+resolution providers). When several CDB records share one `<router>` (the
+same address saved under two users), `--match user=<name>` (or
+`target=<addr>`, or a record type) picks one, as on `devices show`; it is
+single-target only (see
+[devices → Ambiguity](../devices/README.md#ambiguity), #583). The `--host` **flag** with no `<router>` positional
 (`retrieve --host http://192.0.2.10:8080 /system/resource`) is a single target
 too: no CDB lookup, so auth comes from flags, env or config. `CENTRS_HOST` never
 stands in for `<router>`.

package/commands/retrieve/examples.md

@@ -146,6 +146,43 @@ centrs retrieve $R /system/license --username $U --password $P --json
 centrs retrieve $R /system/resource --attribute bogus --username $U --password $P --json
 ```
 
+## Read paths dispatch only reads (#586)
+
+A read sends only a `print`/`get`, even with `--validate=false`. Covered by
+the CHR test `test/integration/read-path-guard.test.ts` (RP1–RP2, over REST
+and native-api, for `retrieve` and `api`; the router's uptime must never go
+backwards) and the offline grammar and REST-guard tests in
+`test/unit/menu-path.test.ts` (RP3).
+
+### RP1. A `#` or `?` in the path is refused before dispatch
+
+```bash
+centrs retrieve $R '/system/reboot#' --no-validate --attribute uptime --username $U --password $P --json
+centrs api $R '/system/reboot?' --validate=false --attribute uptime --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=input/invalid-routeros-path`,
+`error.context.invalidSegments` names the bad segment, and nothing is sent.
+Before #586 the first line posted `/rest/system/reboot` and rebooted the CHR.
+
+### RP2. A well-formed command path is RouterOS's refusal, not a dispatch
+
+```bash
+centrs retrieve $R /system/reboot --no-validate --username $U --password $P --json
+centrs retrieve $R /system/reset-configuration --no-validate --attribute uptime --username $U --password $P --json
+```
+
+Envelope: `ok: false` with a `routeros/*` code. RouterOS answers
+`<command>/print` and a `GET` of a command with "no such command", so the
+appended `/print` is the guarantee once the path cannot cut it off.
+
+### RP3. Menu-name grammar and the REST URL guard
+
+Path segments are letters, digits and hyphens (case folds:
+`/IP/Address` is accepted). Under every REST caller, a request path with
+`?`, `#`, `\`, a control character or a `.`/`..` segment (including
+`%2e%2e` and `.%2E`) fails `input/invalid-routeros-path` before `fetch`.
+
 ## Transport / error contract
 
 ### 12. Bad credentials
@@ -821,3 +858,50 @@ centrs retrieve $R /interface --until name=missing --wait 500ms --username $U --
 One envelope goes to stdout, with `stopReason: "deadline-elapsed"`; exit 1.
 No intermediate sample frames are printed. Unit anchors cover slow validation,
 unfinished reads, cancellation and narrow retry classification.
+
+## Record selection (`--match`, #583)
+
+Covered by the named tests `MA1`–`MA3` in `test/integration/cdb-match.test.ts`
+on disposable CHR; MA4 is the offline contract in the `MA4.` tests of
+`test/unit/cdb-match.test.ts`, which drive `retrieve`/`api` through the CLI. `$CDB` holds
+two `ipAdmin` records for the same target `$R`: user `$U` with a deliberately
+wrong password, and a `read`-group user `reader` with its real password.
+The same selector works on `execute`, `api`, `transfer`, `terminal` and
+`btest client`.
+
+### MA1. Two records for one target are ambiguous
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --json
+```
+
+Envelope: `ok: false`, `error.code=identity/ambiguous`, `context.matches`
+lists both records, and the remediation names `--match user=<name>`.
+
+### MA2. `--match user=` picks the record and its credentials
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --match user=reader --json
+centrs execute $R /system/identity/print --cdb-file $CDB --match user=reader --json
+centrs api $R system/identity --cdb-file $CDB --match user=reader --json
+```
+
+Each is `ok: true` with `meta.target.recordIndex=1`. With
+`--match user=$U` instead, each fails `transport/auth-failed`: the decoy's
+wrong password went on the wire, so the selection is real.
+
+### MA3. A selector that matches nothing
+
+```bash
+centrs retrieve $R /system/identity --cdb-file $CDB --match user=nobody --json
+```
+
+Envelope: `ok: false`, `error.code=identity/no-match`.
+
+### MA4. `--match` is single-target and never ignored
+
+With a fan-out selection (`--group`, `--where`, `--all`, several
+positionals) or `--quickchr`, `--match` is `usage/conflicting-flags`. When no
+CDB record is in play (no CDB file, an unregistered literal host, a
+`__default__`-only fallback) it is `identity/no-match`, never a silent
+literal-host read.

package/commands/transfer/README.md

@@ -118,6 +118,31 @@ past 60 KB) rather than quietly switching to sftp. `scp`, `fetch`, and `ftp` are
 explicit-only; `ftp` additionally requires `ALLOW_UNSAFE_PROTOCOLS=ftp` because
 it is cleartext.
 
+The method resolves `--via` → `CENTRS_TRANSFER_VIA` → the CDB record's `via=`
+preference → config → auto ([constitution: settings](../../docs/CONSTITUTION.md)).
+A record's `via=` names a *transport* (shared with `execute`), so transfer maps
+it to a method (#591):
+
+| CDB / `--via` transport name | Transfer method |
+| --- | --- |
+| `ssh` | `sftp` |
+| `rest-api` (also `--via rest`) | `rest` |
+| `native-api` (also `--via native`) | `native` |
+| `mac-telnet`, `romon`, `winbox-terminal`, `snmp`, `mndp`, `btest` | none — `settings/invalid-via` |
+
+`--via ssh` (and `CENTRS_TRANSFER_VIA=ssh`) is accepted as an alias of
+`sftp`. A record whose `via=` cannot carry files fails `settings/invalid-via`
+naming the record, rather than being ignored; pass `--via sftp|rest|native`
+for that transfer. A record `via=` holds a transport id: method names
+(`sftp`, `rest`, `ftp`) and unknown values are rejected when the record is
+read (`cdb/invalid-option` warning) and leave the method on auto. A record
+preference is a setting, not an auto hop: a `via=rest-api` record uploading
+more than 60 KB fails `transport/unsupported-operation` like a pinned
+`--via rest` does, and the remediation names the record. The endpoint and
+credentials still come from the same record; the mapping never selects a
+different one. A record's `port=` travels with a `--via` pin, so if the
+record's port belongs to another service, point `--port` at the pinned one.
+
 **File contents are bytes on `rest`/`native`.** RouterOS carries `/file`
 contents as raw bytes on both wires — REST puts bytes 0x80–0xff unescaped in the
 JSON string, so the body is not UTF-8 — and stores the UTF-8 encoding of every

package/commands/transfer/examples.md

@@ -569,3 +569,49 @@ list succeeds over sftp: `meta.via=sftp`, `meta.target.source.kind=provider`,
 handed over) carried as a provider-sourced `sshKey`. Otherwise the envelope is
 `ok: false` with `error.code=quickchr/unsupported-via` and exit code 1 — a
 typed gate, **never** a password prompt and never a silent fallback to REST.
+
+## CDB record `via=` (#591)
+
+A record's `via=` names a transport, shared with `execute`; transfer maps it
+to a method (`ssh`→`sftp`, `rest-api`→`rest`, `native-api`→`native`). `$CDB`
+holds one record for `127.0.0.1` whose comment is
+`via=ssh port=$SSH_PORT ssh-key=$KEY insecure=true`; the key is imported as
+in the sftp section. C1–C2 are covered by
+`test/integration/transfer-cdb-via.test.ts`; C3–C4 are offline error
+contracts covered by `test/unit/transfer.test.ts`
+(`resolveTransferRequest takes the CDB record's via=`).
+
+### C1. A `via=ssh` record runs execute over ssh and transfer over sftp
+
+```bash
+centrs execute 127.0.0.1 --cdb-file $CDB /system/identity/print --json
+centrs transfer 127.0.0.1 --cdb-file $CDB upload $SRC centrs-591.txt --json
+```
+
+Both `ok: true` with `meta.via="ssh"`, and no `--via` on either. The
+transfer's `meta.settings.via` is `{kind: "comment-kv", key: "record:0:via"}`.
+
+### C2. Download from the same record, with and without `--via sftp`
+
+```bash
+centrs transfer 127.0.0.1 --cdb-file $CDB download centrs-591.txt $TMP/c2-auto.txt --json
+centrs transfer 127.0.0.1 --cdb-file $CDB --via sftp download centrs-591.txt $TMP/c2-sftp.txt --json
+```
+
+Both `ok: true`, `meta.via="ssh"`; each file is byte-identical to `$SRC`.
+`--via ssh` is accepted as the same method as `--via sftp`.
+
+### C3. A record transport that cannot carry files
+
+A record with `via=mac-telnet` (or `romon`, `snmp`, `winbox-terminal`,
+`mndp`, `btest`) and no `--via`: `ok: false`, `error.code=settings/invalid-via`,
+`error.context.source="record:N:via"`, and the remediation suggests
+`--via sftp`, `--via rest` or `--via native`. An explicit `--via` wins over
+the record and the transfer proceeds.
+
+### C4. A `via=rest-api` record does not auto-hop a large upload
+
+A `via=rest-api` record uploading more than 60 KB with no `--via`:
+`ok: false`, `error.code=transport/unsupported-operation`, nothing sent. The
+remediation names `record:N:via` and suggests `--via sftp`, matching a
+pinned `--via rest`.

package/docs/CLI.md

@@ -64,6 +64,7 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 | `--max-results` | `<bytes>` | Fail instead of printing output larger than the given byte budget. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
 | `--validate / --no-validate` |  | Enable or disable inspect-backed preflight validation. |
 | `--verbose` |  | Show resolved setting sources in text output, on stderr. |
@@ -97,6 +98,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--insecure` |  | Disable SSH host-key verification (`--via ssh`: accepts changed/impersonated keys, not just new) or accept a self-signed `api-ssl` TLS cert. Default verifies. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
 | `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
 | `--validate / --no-validate` |  | Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted). |
@@ -145,6 +147,7 @@ Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <en
 | `--insecure` |  | Accept a self-signed `api-ssl`/REST TLS cert. Default verifies. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
 | `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
 | `--validate / --no-validate` |  | Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted). |
@@ -162,7 +165,7 @@ Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
-| `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction. |
+| `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers; `ssh` is an alias); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction, after a CDB record's `via=` (ssh→sftp). |
 | `--ssh-key` | `<path>` | sftp only: explicit private-key path. Falls back to CENTRS_SSH_KEY / the ssh-agent. |
 | `--insecure` |  | Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies. |
 | `--force / --overwrite` |  | Skip the existing-destination check on the device for `upload`/`mkdir`/`copy` (`upload` then overwrites). Default refuses an existing target. `download` always replaces the local file. |
@@ -189,6 +192,7 @@ Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download
 | `--yaml` |  | Shortcut for --format yaml. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--validate / --no-validate` |  | Enable or disable the existence-probe preflight. |
 | `--verbose` |  | Show the resolved transport in text output, on stderr. |
 
@@ -212,6 +216,7 @@ Usage: centrs terminal <router> [flags] | centrs terminal --host <host> [flags]
 | `--insecure` |  | `--via ssh`: disable host-key verification (accepts changed/impersonated keys). Default verifies. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--resolve` | &lt;none\|arp&gt; | `--via ssh` only: turn a MAC target into an IP. CDB-first; `arp` opts into the host ARP cache (default none). The mac-telnet default ignores it. |
 | `--format` | &lt;text\|json\|yaml&gt; | Error-envelope format on failure. --json / --yaml shortcuts. |
 | `--json` |  | Shortcut for --format json. |
@@ -258,13 +263,15 @@ Usage: centrs explain [<router>] '<input>' [flags]
 Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
 
 ```text
-Usage: centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]
+Usage: centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args] [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
+| `--encrypt` |  | `init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB. |
+| `--no-backup` |  | `encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered. |
 | `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
-| `--cdb-password` | `<secret>` | Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes. |
+| `--cdb-password` | `<secret>` | Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used for `init --encrypt`, `encrypt`, and to re-encrypt on writes. |
 | `--via` | `<protocol>` | Resolve and report the protocol source for provenance examples; no network IO is performed. |
 | `--group` | `<name>` | `list` filter / `add`,`edit` first-class group field for the target entry. |
 | `--where` | `<attr=value>` | `list` only — repeatable device-class filter over CDB facts (AND-combined), e.g. `--where lat=37.7749`. |
@@ -340,6 +347,7 @@ Usage: centrs btest <client <router>|server> [flags]
 | `--port` | `<port>` | Control port. Default 2000. |
 | `--cdb-file` | `<path>` | (client) Read target credentials from a WinBox CDB file. |
 | `--cdb-password` | `<password>` | (client) Decrypt an encrypted WinBox CDB file. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | (client) Pick one of several CDB records saved for `<router>` (as `devices show --match`); `btest server` rejects it. |
 | `--format` | &lt;text\|csv\|json\|yaml&gt; | Output format. Default text. |
 | `--csv` |  | Shortcut for `--format csv`. |
 

package/docs/MATRIX.md

@@ -189,7 +189,9 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 Live `explain` (#236) is `CHR-passed` on REST and native API: the #491
 foundation, #492's describe and completion facets, and #225's live value types,
 with every applicable example green on stable and long-term CHR. Issue #90
-owns the remaining sequencing, including #507 context grounding.
+owns the remaining sequencing, including #507's context surface. Its bounded
+submission matrix is grounded (#574); context selection and binding behavior
+remain follow-up work.
 
 **First: `explain`** (maintainer decision 2026-10-16 on
 [#90](https://github.com/tikoci/centrs/issues/90)). In order: make the
@@ -253,8 +255,8 @@ applicable examples pass on CHR via `bun run test:integration`.
 
 Open offline follow-ups remain explicit but do not reopen the verified baseline.
 Issue #211 made an unlisted absolute bare path abstain (rule F, R14); rule
-P's closed-world reading is still not adopted (#372). #272 owns
-non-authoritative `.scratch/` citation cleanup. Issues #350 (the broad
+P's closed-world reading is still not adopted (#372). The non-authoritative
+scratch citation cleanup is complete (#272, shipped in #568). Issues #350 (the broad
 optional `=`), #351 (a relative submenu brace read as a command operand)
 and #355 (`'` is not a RouterOS token) are complete. A submenu block after a navigation statement
 (`/ip⏎address { … }`) keeps the pre-#351 reading; see

package/docs/errors/cdb/encrypt-failed.md

@@ -0,0 +1,10 @@
+# `cdb/encrypt-failed`
+
+The existing CDB could not be rewritten with encryption.
+
+## Fix
+
+Check directory permissions and available disk space, then retry
+`centrs devices encrypt`. Preserve the original file and any timestamped backups
+before recovery. A failed write may already have created a plaintext backup;
+encryption does not protect that backup.

package/docs/errors/cdb/password-required.md

@@ -1,9 +1,10 @@
 # `cdb/password-required`
 
-The CDB is encrypted; a --cdb-password is required to read it.
+A CDB password is required for decryption or explicit encryption.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `cdb/password-required`.
+Pass `--cdb-password` or set `CENTRS_CDB_PASSWORD` to the CDB password.
+`devices init --encrypt` and `devices encrypt` require a non-empty password,
+even when the file is currently open. A password alone never implicitly
+converts an existing open CDB; use `devices encrypt` explicitly.

package/docs/errors/cdb/plaintext-backups.md

@@ -0,0 +1,11 @@
+# `cdb/plaintext-backups`
+
+CDB backups may still contain plaintext credentials after encryption.
+
+## Fix
+
+Apply your own secure backup and retention policy to the `.bak.*` files beside
+the CDB. `devices encrypt` protects only the active CDB and retains every backup,
+including the plaintext snapshot created during conversion. It does not encrypt
+or delete old copies. This warning also accompanies already-encrypted no-op runs,
+since prior backup protection cannot be inferred from the active file.