@tikoci/centrs 0.1.9-next.24 → 0.1.9

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>`.
@@ -562,5 +583,5 @@ reach green is forbidden. See `docs/CONSTITUTION.md` for the full done rule.
 - **ssh / mac-telnet / romon / winbox-terminal** — execute surfaces, not
   retrieve surfaces.
 - **tips** — when a `<router>` fails to resolve against an empty CDB, retrieve
-  emits the same `tip/no-devices` advice as `devices list`, steering toward
-  `centrs devices discover` and `centrs settings`.
+  emits `tip/no-devices`, steering toward `centrs discover --save` and
+  `centrs devices add`.

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/settings/README.md

@@ -156,6 +156,12 @@ centrs settings reset [<attr>]                 # clear one/all back to built-in
   elsewhere (`src/cli/api.ts`'s `exitCode`), never a bare non-zero without an
   envelope. `settings` has no fan-out surface, so the constitution's `2`
   ("partial" fan-out result) never applies here.
+- **`get` output:** text mode renders the one entry exactly as `print`
+  renders that key — `key: value [source: kind (key)]` under the canonical
+  attr name, plus any `Tips:` footer (examples.md #33). `get`'s `data` is the
+  bare `{ source, value }` entry, so the JSON/YAML envelope names the key in
+  `meta.operation.attr` (canonical name, whichever spelling was asked for).
+  A blank `<attr>` is refused at parse time as `input/invalid-command`.
 - **Agent-facing:** every subcommand emits the standard envelope
   (`ok`/`data`/`meta`/`error`) regardless of TTY — `--format json` is
   honored on `settings` itself exactly like every other command, so an agent

package/commands/settings/examples.md

@@ -406,3 +406,20 @@ XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --cdb-file /tmp/does-not-exi
 device configured" rather than `cdb/not-found`, since reporting settings
 should not require a CDB to exist at all). `data.defaultDevice = {
 configured: false }`.
+
+## Text output
+
+### 33. Get renders one entry in text mode, like print
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR CENTRS_MAX_RESULTS=7 centrs settings get CENTRS_MAX_RESULTS
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get ssh-key
+```
+
+`ok: true`, exit 0. Text mode prints the single entry as one line in the
+same `key: value [source: kind (key)]` format `print` uses, under the
+canonical attr name whichever spelling was asked for: `max-results: 7
+[source: env (CENTRS_MAX_RESULTS)]`, then `ssh-key: (unset) [source:
+default (ssh-key)]` followed by its `Tips:` footer. `get`'s `data` is the bare
+entry, so the JSON envelope names the key in `meta.operation.attr`. A
+credential-shaped key renders `(redacted)`, never the secret.

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