@tikoci/centrs 0.1.0

package/commands/btest/examples.md

@@ -0,0 +1,190 @@
+# btest — examples
+
+Each numbered example is an executable spec. btest is a peer protocol (no router
+*command* is run), so the examples are validated by two peers — matching the
+matrix's honest grounding split (`docs/MATRIX.md`, "Peer measurement (`btest`)"):
+
+- **Gated `CHR-passed` (server cell): CHR client → centrs server** — examples
+  **1–3** are the asserted set. `@tikoci/quickchr` boots a CHR; its
+  `/tool/bandwidth-test` dials the host at the SLIRP gateway `$GW` (`10.0.2.2`)
+  where the centrs server listens on `--bind 0.0.0.0`. No hostfwd (guest→host).
+  Gated UDP coverage is **transmit** (guest-originated, so SLIRP NATs it cleanly);
+  UDP **receive/both** through SLIRP is a non-asserting smoke cycle (README, Open
+  questions). `test/integration/btest.test.ts` drives the CHR side with
+  centrs's already-`CHR-passed` `execute`/REST path and cross-checks throughput /
+  loss / direction against the CHR's own `/tool/bandwidth-test` status output
+  (CHR 7.23.1, `bun run test:integration`). Examples **4** (wrong-credentials) and
+  **5** (multi-connection TCP) are **designed but not yet gated** — the auth-reject
+  path is covered by the loopback unit test, and the multi-stream fan-out is a
+  documented follow-up — so they are not part of the asserted run.
+- **Gated `CHR-passed` (client cell): centrs client → CHR bandwidth-server** —
+  examples **6** (TCP receive) and **8** (EC-SRP5 client role + wrong-password
+  reject) are *also* asserted directly against a real RouterOS
+  `/tool/bandwidth-server`, over a host→guest `tcp:2000` forward
+  (`test/integration/btest-client.test.ts`, CHR 7.23.1). This is what makes the
+  **client** cell `CHR-passed`: centrs's EC-SRP5 **client proof** is verified by
+  RouterOS's own server verifier. TCP only — the EC-SRP5 example is run over TCP
+  receive here (the loopback variant below uses UDP); UDP client→server stays
+  loopback (README, Open questions).
+- **Unit / loopback (client cell + codec)** — examples 6–10. centrs client ↔
+  centrs server on `127.0.0.1` with injected sockets; the EC-SRP5 both-roles math
+  and the pre-socket option-grammar rejects (`test/unit/btest.test.ts`). These are
+  deterministic and need no router, and remain the fast backstop under the gated
+  client-cell coverage above.
+
+`btest.exe` (via wine) is **not** in this example set: it cannot run in CI, so it
+is a **coding-time grounding aid** only — run by hand against the centrs client and
+server while developing the EC-SRP5 framing and server verifier — not a gated
+example or integration test.
+
+`$GW` is `10.0.2.2` (the host as seen from the CHR). `$U` / `$P` are the
+credentials shared by the centrs server and the CHR client. `$SRV` is the centrs
+server endpoint a client dials (the loopback server in unit tests). The real
+`~/.config/tikoci/winbox.cdb` is never touched.
+
+Output formats under test (see `README.md`, Output): `text` (default, live human
+reports), `--csv` (streaming CSV records), and `--format json` (a single summary
+envelope at completion, with `data.sessions[]` for the server / `data.reports[]`
+for the client). The examples below assert on `json` (the structured summary) or
+`csv` (the stream); `text` is the human render of the same data.
+
+## CHR client → centrs server (gated; server cell)
+
+These examples show the **`centrs btest server`** command and the result it
+produces; `test/integration/btest.test.ts` separately drives the CHR's
+`/tool/bandwidth-test` against `$GW`.
+
+### 1. Unauthenticated TCP receive
+
+```bash
+centrs btest server --authenticate=false --bind 0.0.0.0 --duration 20s --format json
+```
+
+While the server runs, the CHR executes `/tool/bandwidth-test $GW protocol=tcp
+direction=receive duration=10s`. At completion the **summary envelope** is
+`ok: true`, `meta.via: "btest"`, with `data.sessions[0]` =
+`{ client, protocol: "tcp", direction: "transmit", user: "" }` (the server
+transmits on the client's `receive`) and a non-zero aggregate tx rate;
+`data.stopReason: "duration-elapsed"`. The server's measured tx is within
+tolerance of the CHR's reported `rx-total-average`.
+
+### 2. Unauthenticated UDP transmit (CSV stream)
+
+```bash
+centrs btest server --authenticate=false --bind 0.0.0.0 --duration 20s --csv
+```
+
+CHR runs `/tool/bandwidth-test $GW protocol=udp direction=transmit
+local-udp-tx-size=1000 duration=10s` — client→server, which the guest originates,
+so SLIRP NATs the UDP flow to the host cleanly. stdout is a CSV stream: a header
+row then one record per session event, with at least one row carrying
+`protocol=udp`, `direction=receive` (the server receives the client's transmit),
+non-zero `rx_bps`, and a populated `lost_packets` column. UDP data rode the
+allocated ports (`allocate-udp-ports-from` base). UDP **receive/both** (server→guest)
+is gated behind the SLIRP smoke test and is not asserted here yet.
+
+### 3. EC-SRP5-authenticated TCP receive
+
+```bash
+centrs btest server --authenticate --user $U --password $P --bind 0.0.0.0 --duration 20s --format json
+```
+
+CHR runs `/tool/bandwidth-test $GW protocol=tcp direction=receive user=$U
+password=$P duration=10s`. The EC-SRP5 **server role** verifies the client proof;
+the summary `data.sessions[0]` carries `user: "$U"`, `protocol: "tcp"`,
+`direction: "transmit"` (server transmits on the client's `receive`), `ok: true`,
+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).
+
+### 4. Wrong credentials are rejected
+
+> *Designed, not yet gated* — the auth-reject path is asserted by the loopback
+> unit test (example 8's mismatched-password case); this CHR variant is a
+> documented follow-up.
+
+```bash
+centrs btest server --authenticate --user $U --password $P --bind 0.0.0.0 --duration 20s --format json
+```
+
+CHR runs `/tool/bandwidth-test $GW user=$U password=wrong …`. The server keeps
+listening and finishes its run, so the summary is `ok: true` but `warnings[]`
+contains a `transport/auth-failed` entry (the EC-SRP5 proof did not verify) and
+`data.sessions` is empty — no session opened, no throughput. The CHR side reports
+an authentication failure.
+
+### 5. Multi-connection TCP transmit
+
+> *Designed, not yet gated* — the server's parallel-stream fan-out for
+> `connection-count > 1` is not built yet (the session token is negotiated, but
+> secondary TCP joins are not served). Documented follow-up; not part of the
+> asserted run.
+
+```bash
+centrs btest server --authenticate=false --bind 0.0.0.0 --duration 20s --format json
+```
+
+CHR runs `/tool/bandwidth-test $GW protocol=tcp direction=transmit
+connection-count=4 duration=10s`. The intended summary `data.sessions[0]` shows
+`protocol: "tcp"`, `direction: "receive"` (server receives the client's
+`transmit`) and `connectionCount: 4`; the server accepts the parallel TCP data
+connections and the aggregate goodput is non-zero. Will confirm `connection-count`
+is honored end to end once the fan-out lands.
+
+## centrs client ↔ centrs server loopback (unit; client cell + codec)
+
+### 6. Client TCP receive against a centrs server
+
+```bash
+centrs btest client $SRV --protocol tcp --direction receive --duration 3s --format json
+```
+
+With a centrs server on `$SRV` (`127.0.0.1:2000` in-test, `--authenticate=false`),
+the summary envelope is `ok: true`, `meta.via: "btest"`, with `data.reports[]`
+holding the per-`interval` samples (each carrying `rxBps` / `rxAvgBps`,
+`direction: "receive"`) and aggregate `rxTotalAvgBps`; `data.stopReason:
+"duration-elapsed"`.
+
+### 7. Client UDP both directions (CSV stream)
+
+```bash
+centrs btest client $SRV --protocol udp --direction both --local-udp-tx-size 1000 --remote-udp-tx-size 1000 --duration 3s --csv
+```
+
+stdout is a CSV stream: a header then one row per `--interval` report, each with
+non-zero `tx_bps` and `rx_bps`, a `lost_packets` column, and non-zero per-interval
+`tx_bytes`/`rx_bytes`. Proves the client drives the same codec the CHR validated in
+examples 1–3, and exercises the streaming CSV path.
+
+### 8. EC-SRP5 handshake, client and server roles
+
+```bash
+centrs btest client $SRV --protocol udp --direction receive --user $U --password $P --duration 3s --format json
+```
+
+Against a centrs server started with `--authenticate --user $U --password $P`, the
+client's EC-SRP5 proof verifies against the server's verifier: `ok: true`,
+throughput non-zero. A run with a mismatched `--password` instead returns
+`ok: false`, `error.code = "transport/auth-failed"`, and no throughput. Exercises
+both EC-SRP5 roles in one process without a router.
+
+### 9. Option-grammar reject: `connection-count` with UDP
+
+```bash
+centrs btest client $SRV --protocol udp --connection-count 4
+```
+
+`ok: false`, `error.code = "validation/option"`,
+`error.context.option = "connection-count"`, and **no socket is opened**.
+`connection-count` applies only to `protocol=tcp`. This is the product claim: btest
+validates its option grammar before touching the network, with no `:parse` step.
+
+### 10. Option-grammar reject: out-of-range UDP size
+
+```bash
+centrs btest client $SRV --protocol udp --local-udp-tx-size 99999
+```
+
+`ok: false`, `error.code = "validation/option"` (UDP size must be `28..64000`), no
+socket opened. The same gate rejects `connection-count` outside `1..255`,
+`interval` outside `20ms..5s`, and (server) `max-sessions` outside `1..1000`.

package/commands/check/README.md

@@ -0,0 +1,59 @@
+# check
+
+Probe a router and report which management paths are usable.
+
+Status: `not-started`. This file is a stub.
+
+## Intent
+
+- TCP reachability per protocol (rest-api, native-api, ssh).
+- Auth check on whichever protocols answered.
+- Optional `--via` to limit the probe surface.
+- L2 probing (mac-telnet reachability / ARP) is **opt-in, off by default** —
+  enabled by a MAC target, `--via mac-telnet`, or `--l2`. It needs L2 adjacency
+  and is slower, so IP-level probing (rest/native/ssh) stays the default.
+- Output is the [standard envelope](../../docs/CONSTITUTION.md#result-envelope);
+  `data` is a per-protocol probe result map.
+- `--fix` (opt-in, write-shaped): once `check` has authenticated over *one*
+  protocol, it reads the live device and writes back through the `devices` layer
+  (the only CDB writer), gated like any write (`--yes` / `confirm`). It refreshes
+  two things in one authenticated pass:
+  - **Connection metadata** — most usefully ports. Reached over MAC/mac-telnet,
+    it reads `/ip/service` to learn the real REST/native-API ports and writes
+    `port=` into the record's comment-kv so later calls connect directly.
+  - **Derived facts** — `board`, `version`, `software-id`, plus the `updated=`
+    stamp, from the same session (the same keys `devices add/set --check` and
+    `discover --save` populate). These stay queryable-but-stale facts that never
+    override a live read (see `commands/devices/README.md`, Derived facts).
+
+  `--fix` is **always explicit**, never implicit; plain `check` (no `--fix`) is a
+  pure read-only probe that writes nothing.
+
+## Default service ports (grounding)
+
+centrs assumes RouterOS defaults when a port is not overridden (CDB `port=` /
+`--port`). Default `/ip/service` ports: `ftp` 21, `ssh` 22, `telnet` 23,
+`www` 80 (often moved, e.g. 7080), `www-ssl` 443, `winbox` 8291, `api` 8728,
+`api-ssl` 8729. (native API rides `api`/`api-ssl`; REST rides `www`/`www-ssl`.)
+
+Once `check` (or any command) has authenticated access over *one* protocol, it
+can read the live service map to discover non-default ports for *other*
+protocols — e.g. reach a box over SSH, then learn the REST port without the user
+specifying it, and "upgrade" the connection:
+
+```routeros
+:put [:serialize to=json options=json.pretty \
+  [ip/service/print detail as-value where !dynamic ]]
+```
+
+## Open questions
+
+- `--fix` scope **decided** (above): connection metadata (ports) **plus** the
+  derived facts (`board`/`version`/`software-id`/`updated=`), refreshed in one
+  authenticated pass through the `devices` write layer; always explicit opt-in,
+  never implicit. Plain `check` stays a read-only probe that writes nothing.
+- L2 probing opt-in **decided** (Intent above): off by default; enabled by a MAC
+  target, `--via mac-telnet`, or `--l2`.
+
+Defer until `retrieve` is `CHR-passed`. `check` overlaps with discovery and is
+easier to design once name resolution lands.

package/commands/devices/README.md

@@ -0,0 +1,405 @@
+# devices
+
+List, inspect, and edit RouterOS targets known to centrs. `devices` is the
+user-facing surface over the device registry described in
+`docs/CONSTITUTION.md`. It is the only command that may *write* to the CDB.
+
+Status: `CHR-passed` for the surface described by `examples.md`. The read subset
+(`list`/`show`/`groups`) and the CDB mutation surface (`add`/`edit`/`set`/
+`remove`), ambiguity / `--match`, and the provenance/override examples are green
+via `bun run test:integration` (`test/integration/devices.test.ts`,
+fixture-backed — `devices` does no network IO, so its evidence is the
+integration run, not a booted CHR). Encrypted-CDB **writes** round-trip through
+decrypt → mutate → re-encrypt under the loaded password; encrypted **reads**
+work with `--cdb-password`. See `docs/MATRIX.md` for the matrix row.
+
+The redesign this README describes is now implemented: the `identity`/`mac`/`ip`
+comment lookup keys and broadened `--match` selectors (`user=`/`target=`), the
+`identity` field rename (was `name`), the symmetric `add`/`set` model (`edit`
+reserved for a future interactive editor), the `(target, user)` record identity,
+the `--profile-none`/`--profile-own` sentinels, the `__default__` fallback
+record, and the top-level `tips[]` channel are all live (examples 10–16, 32–40;
+`__default__` is resolver-level, unit-tested in `test/unit/resolver.test.ts`).
+Treat this README as the spec, `docs/MATRIX.md` as the implemented status.
+
+`devices` does not use a transport in the protocol sense and does not contact a
+RouterOS device in phase 1. Its sources are:
+
+- explicit CLI input,
+- environment variables (`CENTRS_*`),
+- the CDB at `~/.config/tikoci/winbox.cdb` (resolved under `$HOME`, not
+  `$XDG_CONFIG_HOME`; override with `--cdb-file` / `CENTRS_CDB_FILE`; if
+  encrypted, decrypt with `--cdb-password` / `CENTRS_CDB_PASSWORD`, or
+  `Bun.secret()` on the CLI when that lands),
+- local ARP cache for MAC → IP resolution when explicitly enabled,
+- (later) the MNDP cache and `dude.db` import via `tikoci/donny`.
+
+## Identity model
+
+The CDB record's natural identity is the **(target, user)** pair, matching
+WinBox: saving the same address under a different user creates a second record,
+not an update. The `target` is the connectable literal WinBox/REST/native use,
+and is one of:
+
+- an IPv4 address (`192.0.2.5`, optionally `host:port`),
+- an IPv6 address (`2001:db8::5`, optionally `[2001:db8::5]:port`),
+- a MAC (`AA:BB:CC:DD:EE:FF`, case-insensitive, separators normalized),
+- a DNS name (`edge1.lan`).
+
+WinBox has no separate "name" field, so a human handle is overlaid in the
+comment as **lookup keys** (constitution: identity and CDB). centrs resolves
+`<router>` against the `target` field **and** these comment-kv keys:
+
+| Lookup key  | Meaning                                                                 |
+| ----------- | ---------------------------------------------------------------------- |
+| `identity=` | The device `/system/identity`. Human handle; deliberately may repeat. |
+| `mac=`      | A MAC, when `target` is an IP/DNS name rather than the MAC.            |
+| `ip=`       | An IP, when `target` is an identity/DNS name rather than the IP.       |
+
+Whichever identifiers are not the `target` ride the comment as lookup keys, so
+one record is resolvable by identity **or** IP **or** MAC **or** DNS-name
+regardless of which is stored as `target`. These three keys are the *only*
+sanctioned exception to "the comment is free text"; every other token stays
+inert. (Earlier drafts said "the comment is not a lookup key" — superseded.)
+
+When `<router>` matches an entry (by `target` or a lookup key), credentials and
+other CDB-resident fields load from that entry. If nothing matches, the call
+still proceeds but `--username` / `--password` (or `CENTRS_USERNAME` /
+`CENTRS_PASSWORD`, or a `__default__` record) become mandatory.
+
+### Ambiguity
+
+Because identity is `(target, user)`, one address legitimately maps to several
+records — the same host saved under two users, or `ipAdmin` + `ipUser` for one
+host. That is not an error in itself; it only becomes ambiguous when `<router>`
+alone cannot pick one (the caller named an address that several records share,
+or a duplicated `identity=`):
+
+- **TTY:** centrs prompts interactively, listing the matches and asking which
+  to use.
+- **Non-TTY:** centrs errors with `identity/ambiguous`. The error envelope
+  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.
+
+`--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
+when it actually selected between candidates.
+
+## Comment kv-soup (per-device overrides)
+
+The CDB `comment` field is free text. centrs additionally parses tokens
+shaped like `key=value` out of it. Recognized keys (allowlist) fall in two
+groups: **lookup keys** affect how `<router>` resolves (see "Identity model");
+**override keys** are per-device defaults for centrs settings.
+
+| Key        | Group    | Effect                                                                  |
+| ---------- | -------- | ---------------------------------------------------------------------- |
+| `identity` | lookup   | Device `/system/identity`; a resolvable handle. May repeat across records. |
+| `mac`      | lookup   | A MAC, when `target` is not the MAC.                                    |
+| `ip`       | lookup   | An IP, when `target` is not the IP.                                     |
+| `via`      | override | Default transport for this device (`rest-api`, `native-api`, `ssh`, …). |
+| `validate` | override | `true` / `false`. `false` is the escape hatch; CLI overrides.           |
+| `timeout`  | override | Default request timeout in ms. Per-transport caps still apply.          |
+| `port`     | override | Non-default transport port. Omitted when equal to the protocol default. |
+| `ssh-key`  | override | Per-device private key file path for SSH transports.                    |
+| `source`   | override | Provenance marker for discovered/imported records (`mndp`, `dude`, …).  |
+| `mcp`      | override | MCP write policy for this device: `ro` (default) or `rw`. See `commands/mcp/`. |
+
+Rules:
+
+- First-class CDB fields (`user`, `password`, `group`, `profile`, `session`)
+  must **not** appear in the kv-soup — they already have CDB tags. This has two
+  distinct outcomes by path: a reserved token found while *parsing* an existing
+  comment is inert and only warns `cdb/reserved-option` (centrs won't act on it,
+  but won't reject a hand-written comment); explicitly passing one as a `devices
+  set` positional (`user=x`) is a hard `cdb/reserved-key` error, because you are
+  asking centrs to *write* it — use the dedicated flag (`--user`) instead.
+- `ssh-key` stores a path only, never private key material. Key contents belong
+  in the user's filesystem / SSH agent and are always treated as sensitive if an
+  error needs to mention them. It joins the comment-kv allowlist *with* the SSH
+  transport (see `commands/terminal/README.md`), not before — a key path with no
+  working SSH transport is the kind of half-feature we avoid.
+- Unknown keys → `cdb/unknown-option` warning. The call still succeeds.
+- Tokens are shell-word tokenized. Values with spaces require double quotes
+  (`"…"`), with `\"` and `\\` escapes. `=` inside a quoted value is literal.
+- 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.
+- `commentMirror` is kept in sync with `comment` on every write.
+
+Precedence (lowest → highest): built-in defaults → project config →
+comment-kv → env (`CENTRS_*`) → CLI flag / API arg. `meta.settings` reports
+the winner and source per setting.
+
+### Derived facts (queryable, may be stale)
+
+Beyond lookup keys and setting overrides, a record may carry **derived facts**
+learned from a probe — `board`, `version`, `software-id` (from MNDP or `check`),
+plus an `updated=<iso>` stamp marking when they were last refreshed. These are
+*facts, not settings*: they are queryable/selectable (e.g. `--where board=RB5009`
+to fan a command across a device class) but must **never override a live read**,
+and they can go stale. `devices add`/`set --check` and `check --fix` refresh them
+from a live device; `discover --save` seeds them. `software-id` is a
+**verification** key
+("is this still the same box?"), not a resolution key (you don't type it to reach
+a device); `license-id` is convenience metadata to match by hand against
+MikroTik's CHR licensing page. The `--where` selector plus this derived-fact
+allowlist are the planned home for "operate on a class of devices," distinct from
+`group`. (Promoting these keys to the comment-kv allowlist is a tracked code
+follow-up.)
+
+## Groups
+
+Groups are CDB-native: each entry's `group` field is a single string. There
+is no group-definition record. A group is the set of all entries whose
+`group` value matches by exact, case-sensitive string compare. An entry with
+`group=""` belongs to no group.
+
+`--group <G>` on any command resolves to the membership set and fans out.
+`discover --save` writes MNDP records with `group=discovered`
+unless the caller supplies another group.
+
+### Promotion (discovered → managed)
+
+There is no `promote` verb. Moving one device out of `group=discovered` and
+giving it credentials is `devices set <t> --new-group prod --user … --password
+…`. A **bulk** promotion (a whole discovered class at once) is the same call with
+a target selector picking the records:
+
+```bash
+devices set --group discovered --new-group prod \
+  --user admin --password … --force
+```
+
+`--group` (and `--where`/`--all`/positionals) always **selects** which records to
+modify; `--new-group` always **writes** the group field. The two are distinct
+flags, so there is no select-vs-set overload — this resolves the former wrinkle.
+(Code follow-up: the CLI still overloads `--group` as the `add`/`set` field
+setter today; `examples.md` reflects that current flag until the `--new-group`
+split lands.)
+
+## Fanout (multi-target invocations)
+
+Any command may receive multiple positional targets, one or more `--group`
+flags, `--all`, `--default`, and/or `--where <attr>=<value>` (device-class) — see
+`docs/CONSTITUTION.md` (Target selection grammar). The resolved member set is
+de-duplicated by CDB record index.
+
+- Each member runs in parallel up to `--concurrency` (default
+  `max(1, floor(os.cpus().length / 2))`).
+- `--fail-fast` aborts pending members on the first failure.
+- The outer envelope's `data` is an array of inner envelopes, one per member,
+  in the resolved member order (CDB record index — see `devices` group
+  expansion), not completion order, so repeated runs produce stable diffs.
+  Members still execute in parallel and may *complete* out of order; progress
+  is surfaced via `meta`, but the `data` array is always reassembled in the
+  deterministic resolved order. `ok` of the outer envelope is `true` iff every
+  inner envelope is `ok: true`.
+- Commands that are not safe to fan out (e.g. `terminal`) reject N > 1 with
+  `usage/fanout-not-supported`.
+
+## Subcommands
+
+```text
+centrs devices list [--group G] [--format json|yaml|text]
+centrs devices show <target> [--explain] [--via <protocol>] [--match <type>]
+centrs devices groups [--members]
+centrs devices discover [--timeout 15s] [--group G]      # = discover --save (save implied)
+centrs devices add <target> [--user U] [--password P] [--new-group G]
+                             [--profile P|--profile-none|--profile-own]
+                             [--session S] [--comment "text k=v"]
+                             [--record-type ipAdmin|ipUser|macTarget|...]
+centrs devices set  <selector…> [--user U] [--password P] [--new-group G]
+                             [--profile P|--profile-none|--profile-own]
+                             [--session S] [k=v ...]
+centrs devices remove <selector…>
+centrs devices edit <target>            # future: clack/TUI wizard
+```
+
+`add` and `set` are deliberately symmetric: both take the same first-class
+flags and the same `k=v` comment tokens. The only difference is existence —
+`add` creates (and refuses an existing target), `set` modifies (and refuses a
+missing target). `edit` is reserved for a future interactive wizard (the
+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`.
+
+- `list` (alias `print`) shows resolved targets, their record type, group, and
+  a one-line provenance summary. No network IO.
+- `show` (alias `get`) returns a single resolved target with the full per-field
+  source map in `meta.target`. `--explain` adds the raw CDB record dump under
+  `data.record`; `--via <protocol>` reports the protocol that would be selected
+  for the target without connecting.
+- `groups` lists distinct non-empty group strings with member counts.
+  `--members` expands to the full membership per group.
+- `discover` runs MNDP discovery with `--save` **implied** (you invoked the
+  registry surface, so you mean to populate it) — equivalent to `centrs discover
+  --save` with the same `group=discovered` / `source=mndp` provenance. It is the
+  natural onboarding step and where centrs steers toward setting fallback
+  credentials (`__default__`). See `commands/discover/README.md`. Still routes
+  through the atomic write layer below, so `devices` remains the only writer.
+- `add` creates a record from first-class flags + comment tokens. Against an
+  existing `(target, user)` it errors `cdb/already-exists` unless `--force`
+  overwrites; the same `target` under a *different* `--user` is a new record,
+  not a collision.
+- `set` modifies existing record(s). First-class fields change via flags
+  (`--user`, `--password`, `--new-group`, `--profile[-none|-own]`, `--session`);
+  comment lookup/override keys change via `k=v` positionals. **Which** records to
+  modify is the target selector — positionals, `--group`, `--where`, `--all`
+  (constitution: target selection) — so `--group` here *selects* and
+  `--new-group` *writes* the group field (no overload). Against a missing target
+  it errors `cdb/not-found-target`; a multi-record `set` needs `--force`. Writing
+  a first-class field name as a `k=v` positional (e.g. `user=x`) stays refused
+  with `cdb/reserved-key` — the flag is the only path. Unknown comment keys warn
+  (`cdb/unknown-option`), or error under `--strict`.
+- `remove` (aliases `rm`, `delete`) removes a single entry. Group-wide deletes
+  (`--group G`) require `--force` (writes are large).
+
+`--profile <name>` sets a named WinBox profile; `--profile-none` /
+`--profile-own` write the WinBox sentinels `<none>` / `<own>`. `profile` and
+`session` are **preserved for WinBox compatibility only** — centrs round-trips
+them and lets you edit them, but never acts on them itself. Unset, `profile`
+defaults to `<none>` (or is inherited from the `__default__` record).
+
+Grounding: `profile` is WinBox's "Workspace" (a saved window layout). `<none>`
+means start with a clean/empty layout; `<own>` means reuse the last session's
+layout *for that router* (per-router, not global). Both are meaningless to
+centrs's headless use, which is exactly why they are preserve-only.
+
+## Default device (`__default__`)
+
+A reserved record (`target=__default__`) holds global fallback creds + comment
+overrides for any device whose own record leaves them unset. Create/edit it like
+any other record (`devices add __default__ --user admin --password …`); WinBox
+can edit it too. Precedence is per-field: args → env → device record →
+`__default__` → built-in default (constitution: identity and CDB).
+
+- `devices list` shows it; tag it `group=default` for clarity if you like.
+- On the CLI/API it can supply creds even for a target with no CDB record. On
+  **MCP** it never widens the allowlist — an unregistered target is still
+  rejected; `__default__` only fills missing creds for a registered device.
+
+## CDB write strategy
+
+All writes go through one helper (`writeWinBoxCdb`) that:
+
+1. Snapshots the current file to `winbox.cdb.bak.<timestamp>` beside it (the
+   timestamp is a filesystem-safe, lexicographically-sortable ISO variant).
+2. Keeps the last 5 backups, deletes older ones.
+3. Builds the new record set with unknown fields preserved verbatim (see
+   below).
+4. Writes to `winbox.cdb.tmp.<pid>.<rand>` in the same directory and `fsync`s
+   it (then best-effort `fsync`s the directory).
+5. `rename()`s over the original (atomic on POSIX), so a crash never leaves a
+   partially-written CDB.
+
+Encrypted CDBs: the write layer decrypts on load, mutates the open record set,
+then re-encrypts with the same password loaded from settings before the atomic
+rename. A fresh salt is rolled on every write; the backup is the verbatim prior
+ciphertext.
+
+Refusals:
+
+- Writing to an encrypted CDB without `--cdb-password` /
+  `CENTRS_CDB_PASSWORD` still fails earlier at load with
+  `cdb/password-required`.
+- Writing to an unencrypted CDB with `--cdb-password` succeeds with the
+  existing `cdb/password-not-needed` warning. centrs does **not** silently
+  upgrade the file to encrypted.
+
+### Unknown CDB fields
+
+The current decoder knows tags 1–4, 6, 8, 9, 11, 12 and a fixed set of tcodes.
+WinBox writes additional fields (RoMON IPv6 addresses, future settings) that
+must round-trip.
+
+- On read: any field with an unknown tag is kept verbatim on
+  `WinBoxCdbRecord.fields`. A field with an unknown tcode is captured as a
+  `rawTail` field — its `value` is a `Uint8Array` carrying the remainder of
+  the record (its own bytes plus any subsequent fields) verbatim, since the
+  decoder cannot know the value length without the schema.
+- On write: known fields are re-encoded normally. A `rawTail` field is
+  emitted as its header (tag, marker, tcode) followed by `value` as raw
+  bytes. This round-trips WinBox-authored records that contain unknown
+  tcodes byte-for-byte. `devices add/edit/set/remove` will emit a
+  `cdb/unknown-field` warning when it preserves a record that carries
+  `rawTail` fields, listing the affected tags.
+
+## Envelope shape (target provenance)
+
+Every centrs envelope (not just `devices show`) carries:
+
+```ts
+meta.target = {
+  target: "edge1.lan",          // what the user typed, normalized
+  resolvedTarget: "edge1.lan",  // what we connect to (post DNS, post --match)
+  addressFamily: "ipv4" | "ipv6" | "mac" | "dns",
+  mac?: "AA:BB:CC:DD:EE:FF",
+  user: "admin",
+  group?: "prod-edge",
+  via: "rest-api",
+  cdbRecordIndex?: 7,           // index into CDB record array, if any
+  sources: {
+    user: "cdb",
+    password: "cdb",
+    via: "comment-kv",
+    validate: "cli",
+    timeout: "default",
+    // …per resolved setting
+  }
+}
+```
+
+For fanout calls, each inner envelope carries its own `meta.target`. The
+outer envelope's `meta.target` is replaced with `meta.targets` (the resolved
+member list and the group(s) that expanded into it).
+
+## Open questions (remaining work beyond the current `CHR-passed`)
+
+`devices` is `CHR-passed` for the currently-implemented reads and writes against
+both unencrypted and encrypted CDBs. The comment-kv *grammar* is settled — see
+"Comment kv-soup" above and `test/unit/comment-kv.test.ts`. The decided redesign
+(lookup keys, identity rename, symmetric `add`/`set`, `(target, user)` identity,
+profile sentinels, `__default__`, `tips[]`) is now implemented; what remains:
+
+**Still genuinely open:**
+
+| Question | Affects | Notes |
+| --- | --- | --- |
+| ARP resolver test scheme | retrieve / execute when target is a MAC | Need deterministic fixtures per OS plus one live same-L2 proof before relying on ARP in integration. |
+
+When an item ships with CHR examples, fold it into the matrix and delete the row.
+
+## Residual risks
+
+- **Encrypted-CDB writes have not been verified against WinBox.** centrs
+  decrypts → mutates → re-encrypts with a fresh salt, and the bytes round-trip
+  through centrs' own decoder. The "open in WinBox after a centrs write"
+  manual proof still needs to happen; until then, treat encrypted writes as
+  centrs-only and keep the backup the write layer leaves behind.
+- **Unknown-tcode preservation is opaque past the first unknown tcode.** The
+  decoder captures one `rawTail` blob; fields that follow the unknown tcode
+  inside the same record are kept inside that blob and cannot be surfaced
+  one-by-one. Acceptable for round-trip writes (the bytes survive); not
+  sufficient if a future cell needs to expose those individual fields.
+- **MAC → IP without CDB.** Resolver order is CDB first, then local ARP when
+  the caller opts into IP-level access. For `execute`, an unresolved MAC
+  defaults to mac-telnet instead. MNDP arrives through `discover --save` and
+  records provenance under `group=discovered`; it is not authoritative
+  inventory.
+- **Comment kv-soup collisions with human prose.** Users may have existing
+  comments that contain `=` for non-kv reasons. The parser must require a
+  bare-word key with no leading whitespace inside the token and treat
+  free-form text outside `key=value` tokens as inert.
+
+## Notes for future cells
+
+- `devices` proper has no transport, but several flags on other commands
+  depend on its resolver (`--group`, `--match`, `--prefer-family`,
+  multi-target positionals). Those flags ship with their host command, not
+  with `devices`.
+- `dude.db` import lives in `tikoci/donny` and feeds the resolver via the
+  same envelope as the CDB. Provenance source label: `dude`.
+- The `centrs check` command will reuse the resolver and add a network probe;
+  `devices` itself stays RouterOS-IO-free.