@tikoci/centrs 0.1.2 → 0.1.4

package/docs/MATRIX.md

@@ -30,137 +30,99 @@ A cell advances only with the matching evidence in the same change.
 | transfer | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —                |
 | devices  | —             | —             | —             | —             | —             | —             | —             | —                |
 | discover | —             | —             | —             | —             | —             | `CHR-passed`  | —             | —                |
-| check    | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started`    |
+| check    | `designed`    | `designed`    | `designed`    | `designed`    | `not-started` | `not-started` | `not-started` | `not-started`    |
+| explain  | `designed`    | `designed`    | —             | —             | —             | —             | —             | —                |
 | settings | —             | —             | —             | —             | —             | —             | —             | —                |
 
-`devices` does not use a transport in the protocol sense, so its grid row stays
-`—`; its cell state is `CHR-passed`. `devices` performs no network IO, so that
-evidence is a fixture-backed `bun run test:integration` run
-(`test/integration/devices.test.ts`, every example in
-`commands/devices/examples.md`) against an in-test CDB (open + encrypted), not a
-booted CHR. The implemented surface (read subset, CDB mutation, lookup-key
-resolution, `(target, user)` identity, ambiguity / `--match`, profile sentinels,
-verb aliases, `__default__`, `tips[]`, provenance/override) and the one open item
-(ARP test scheme) are documented in `commands/devices/README.md`.
-
-`discover` is `CHR-passed`: the MNDP codec (`src/data/mndp.ts`), the TTL neighbor
-cache (`src/data/mndp-cache.ts`), the UDP listener, and `discover --save`
-(through `devices`' atomic write layer) live in `src/discover.ts`. The real-L2
-receive/decode/save path is green on RouterOS CHR 7.23.1 via
-`test/integration/discover.test.ts` (the quickchr `socket-connect` L2 bridge,
-`test/integration/mndp-l2-bridge.ts`; examples 1, 2, 4); the network-independent
-codec/cache/listener/`--save` paths stay unit-tested (examples 3, 5, 6, 7). The
-wire format, the de-dupe rule (`target`-keyed today, MAC-keyed is the decided
-target), TTL/timeout defaults, the live board-TLV finding (short board id vs the
-verbose REST `board-name`), and the L2 validation policy are documented in
-`commands/discover/README.md`.
-
-There is no `update` command: `execute` is the single read/write surface for
-RouterOS *CLI-shaped* add/set/remove, and `retrieve` stays read-only. The `api`
-command is the structured one-command-per-operation surface (the verb trichotomy
-in `commands/api/README.md`); it can also write. See `docs/CONSTITUTION.md`
-(protocol selection).
-
-`api` is `CHR-passed` for `rest-api` and `native-api` (single-target): endpoint
-normalization, the method→verb map, the `/console/inspect` gate, write
-confirmation, `.query`/`.proplist`, `-f`/`-d`/`--input` bodies, `--raw`,
-`/execute` script-run (`=as-string=` for sync output on both transports), and
-open-ended `--stream` follow (native-api only — `NativeApiSession.listen()` +
-`/cancel`, NDJSON envelope frames with a terminating summary; `--via rest-api
---stream` errors `transport/capability-unsupported`), green on CHR 7.23.1 via
-`test/integration/api.test.ts` + `api-native.test.ts` + `api-listen.test.ts`.
-Still deferred (own phase): multi-target fan-out (`--stream` is single-session).
-
-`api` **absorbs** the former `stream` command (folded — no separate row): the
-read-only follow surface is `api <router> <endpoint> --stream` (alias `--listen`;
-the `/listen` endpoint form infers it), native-api only, since REST's 60s cap
-cannot follow. `centrs stream`/`centrs tail` now error with a pointer to
-`api --stream`.
-
-`transfer` is `CHR-passed` for `rest-api`/`native-api` and for **sftp** (the
-`ssh` column's first method): `src/transfer.ts` + `src/cli/transfer.ts`
-(size/direction-aware method selection, leading-slash normalization, the
-`print`-probe existence guard, `--verify`) over the shared `FileBackend` seam,
-with the SFTP client in `src/protocols/sftp.ts` (host OpenSSH `sftp` subsystem;
-`scp` deferred). `test/integration/transfer.test.ts` is green on real CHR 7.23.1
-(110 assertions): the rest + native round-trip, the native `N1`–`N4` mirror, the
-sftp `S1`–`S5` round-trip, the stdin/stdout forms via the subprocess harness
-(examples 8–10), and example 17 (chunked REST read of an sftp-seeded >60 KB file).
-The method-selection grammar, the SFTP-vs-SCP rationale, the `--verify` behavior
-(sftp trusts the transfer guarantee; rest/native re-read the `/file` size), and the
-deferred `scp`/`fetch`/`ftp` methods are documented in
-`commands/transfer/README.md`.
-
-`execute / ssh` is `CHR-passed` (the second SSH consumer): a per-command batch
-client (`SshExecClient` in `src/protocols/ssh.ts` — one `ssh user@host "<cmd>"`
-per command, sharing `sftp.ts`'s host-`ssh` plumbing) behind the `SshExecAdapter`
-console transport (execute-only, like mac-telnet; structured reads/inspect
-unsupported). It reuses the mac-telnet `:put [:parse …]` gate verbatim. Green via
-`test/integration/execute-ssh.test.ts` (S1–S4) + `test/unit/ssh.test.ts`; the
-no-PTY / clean-output / `:parse` wire grounding lives in the `src/protocols/ssh.ts`
-header and `commands/execute/README.md`.
-
-`terminal / ssh` is `CHR-passed` (the third and last SSH consumer): it execs the
-host `ssh` with inherited stdio (`buildSshTerminalArgv` in `src/terminal.ts`,
-reusing `sshCommonOptions`) and lets the OS relay RouterOS's already-clean no-PTY
-console — no screen emulation. No `-t` is passed (`-tt` hangs RouterOS);
-`runTerminal` returns `ssh`'s exit code. A host target defaults to ssh, a MAC
-target to mac-telnet. Green via `test/integration/terminal-ssh.test.ts` (TS1/TS2),
-with argv unit-tested in `test/unit/terminal.test.ts`. **All three SSH cells
-(transfer/execute/terminal) are `CHR-passed`.** The no-PTY / exit-code semantics are documented in
-`src/terminal.ts`; the no-multi-line-brace limitation is in
-`commands/terminal/README.md`.
-
-`fetch` (centrs-as-HTTP-server + `/tool/fetch`) is a **deferred, explicit-only
-method within the rest-api/native-api cells**, not a grid column — it needs
-inbound reachability (router → centrs) so it is never auto-selected.
-
-`settings` is `designed` and transport-less (like `devices`), so its grid row
-stays `—`. `commands/settings/README.md` describes the `centrs.env` + `__default__`
-front-end (interactive first-time setup plus `settings get/set/reset/print`); no
-code yet.
-
-### Transport-base readiness (below the command grid)
+## Status pointers
+
+Detailed command contracts live in `commands/<name>/README.md`; example evidence
+lives in `commands/<name>/examples.md` and the named integration tests. Keep this
+section short enough that the grid remains the status surface.
+
+- `devices` is transport-less, so its row stays `—`; command state is
+  `CHR-passed` by fixture-backed integration tests in `test/integration/devices.test.ts`.
+- `settings` is transport-less, so its row stays `—`; command state is
+  `CHR-passed` by fixture-backed integration tests in `test/integration/settings.test.ts`.
+- `retrieve`, `api`, `execute`, and `transfer` share the target-selection and
+  fan-out contracts from `docs/CONSTITUTION.md`; command-specific boundaries and
+  evidence are in their command READMEs and integration tests.
+- There is no `update` command. RouterOS CLI-shaped writes ride `execute`; the
+  structured operation surface is `api`.
+- `api --stream` absorbs the former `stream`/`tail` surface; native-api stream
+  details are in `commands/api/README.md` and `src/protocols/native-api.ts`.
+- `discover / mndp` is grounded by `commands/discover/README.md`,
+  `src/data/mndp.ts`, `src/data/mndp-cache.ts`, and
+  `test/integration/discover.test.ts`.
+- `check` is `designed` (`commands/check/README.md`): a reach + health battery
+  whose reads ride the execute-capable transports (rest-api/native-api/ssh/
+  mac-telnet), so those four cells are `designed`; `snmp` and `romon`/
+  `winbox-terminal` stay `not-started`. Its per-host fan-out is the machinery the
+  IP-scan discovery (#149) will iterate; the L2-default timing evidence (#136) is
+  recorded in the README before the cells advance past `designed`.
+- `explain` is `designed` (`commands/explain/README.md`): the explain →
+  validate → run knowledge tier — canonical structure, LSP-like
+  spans/diagnostics, transport classification (api-able vs execute, `curl`
+  rendering), and live schema/completion facts. Its offline mode is the
+  canonicalizer only and opens no protocol connection (evidence is
+  unit/fixture tests); the
+  live probes (`/console/inspect` + `:parse`) ride rest-api/native-api, so
+  those two cells are `designed`. The surface was decided in the 2026-07-19
+  design round (#90) and the spec is **ratified** on the phase-0 grounding
+  lab (#185, ratification PR #187). Phase 0.5 has since promoted the ratified
+  lab logic into the library — `src/explain/{segment,blocks,coordinates,defects,
+  pathresolve,verbsplit,write,symbols,menus,verbs,args,values,brace-slots}.ts`
+  with frozen fixtures under `test/fixtures/explain/` — and phase 1 has composed
+  them into one analysis and envelope in `src/explain.ts` (`explainCommand` /
+  `explainEnvelope`, #202a). **`centrs explain '<input>'` is a real command as
+  of #202b** (`src/cli/explain.ts`), and #202c adds statement argument reading,
+  the closed Q8 transport classifier, equivalent centrs invocations, and
+  opt-in `--curl`. All offline examples, including 1, 2, 6 and 23, run green in
+  `test/unit/explain.test.ts`. The row nonetheless stays `designed`: offline
+  mode occupies no protocol cell, and the two `designed` cells are the live
+  `/console/inspect` + `:parse` probes, which are phase 2. The live grammar
+  (`explain <router> '<input>'`) is parsed and refused with
+  `usage/not-implemented` rather than degraded to an offline run. Cells advance
+  only when the live probes land and their examples run green per the done rule.
+  `src/explain/menus.ts` and `src/explain/catalog.ts` are the **generated**
+  files in that set — the RouterOS menu-vs-command table (#207, from pinned
+  restraml typed trees) and the path catalog (#228, those trees unioned with
+  MikroTik's published CLI Reference, carrying kind, per-entry provenance and
+  the published applicability gate). Regenerate with `bun run explain:menus` /
+  `bun run explain:catalog`; both are drift-checked in QA. They keep the offline
+  analyzer offline; do not hand-edit them. The catalog's **command axis is read**
+  by `pathresolve.ts`, `verbsplit.ts` and `write.ts` (#228 step 2); #235 also
+  reads its menu/settings kind, unioned with `menus.ts` behind
+  `src/explain/is-known-menu.ts`, for both a context-applied relative bare path
+  and an absolute one. Both changes are inside the offline canonicalizer, so
+  this grid is unchanged by them.
+- `transfer / ssh` means the SFTP-backed transfer method. Deferred file-transfer
+  methods such as `scp`, `fetch`, and `ftp` are tracked in
+  `commands/transfer/README.md`; `fetch` is not a grid column.
+- SSH grounding for `execute` and `terminal` lives in
+  `commands/execute/README.md`, `commands/terminal/README.md`,
+  `src/protocols/ssh.ts`, `src/protocols/sftp.ts`, and `src/terminal.ts`.
+- MAC-Telnet grounding for `execute` and `terminal` lives in
+  `commands/execute/README.md`, `commands/terminal/README.md`, and the
+  `src/protocols/mac-telnet*.ts` module headers.
+- Transport wire-format and delivery caveats belong in `src/protocols/*.ts`
+  module headers. Do not expand this file with per-packet or per-router findings.
+
+Beyond the grid: post-`CHR-passed` hardening, ergonomics, and research work is
+tracked in GitHub issues (`dry-july` and successors). Those issues may point back
+to this matrix for current status, but they are not additional cell states.
+
+### Transport-base readiness
 
 The grid above tracks command cells. The transports those cells ride are
 implemented and grounded in their `src/protocols/*.ts` **module headers** — the
-single home for wire-format, auth, and delivery facts (one fact, one place).
-Status here is terse; the module header carries the detail.
-
-- **native-api** (`src/protocols/native-api.ts`): word/sentence codec, streaming
-  reader, login (post-6.43 plaintext + legacy MD5 challenge), tagged command
-  multiplexing, typed error mapping. Live cell status is in the grid (`retrieve`,
-  `execute`, and `transfer` over `native-api` are all `CHR-passed`). Covered by
-  `test/unit/native-api.test.ts`, `test/integration/native-api.test.ts`
-  (transport), and `test/integration/native-api-retrieve.test.ts` (command).
-- **mac-telnet** (`src/protocols/mac-telnet.ts` + `mtwei.ts` +
-  `mac-telnet-console.ts` + `MacTelnetAdapter` in `adapter.ts`): packet/control
-  codec, session state machine, both auth methods (classic MD5 + MTWEI EC-SRP),
-  the interactive-console reader, and the UDP datagram transport with route
-  discovery. The deep findings — auth (MTWEI-required / MD5-refused /
-  `END_AUTH`≠success), console (ANSI terminal-size probe, ~10s prime stall,
-  one-time license gate, `:put [:parse]` syntax+semantic gate, silent writes),
-  reliability (byte-counter retransmit + empty-ACK keepalive), and the
-  real-device UDP-delivery facts (real egress MAC required; broadcast-only reply;
-  per-NIC directed-broadcast reach via `discoverMacTelnetRoute`; bind `0.0.0.0`)
-  — are documented in those module headers. Two cells are `CHR-passed`:
-  - **`execute / mac-telnet`**: `executeEnvelope` (resolver → `MacTelnetAdapter` →
-    UDP transport) runs reads, REST-verified writes, and the validation-reject
-    path. Green via `test/integration/mac-telnet-console.test.ts` (examples
-    19–21); transport/auth alone via `test/integration/mac-telnet.test.ts` (MTWEI
-    login + MD5 refusal). Unit: `test/unit/{mtwei,mac-telnet,mac-telnet-console}.test.ts`.
-  - **`terminal / mac-telnet`**: the interactive relay over the same console
-    reader (`MacTelnetConsole.attachInteractive`), orchestrated in
-    `src/terminal.ts` over an injectable `TerminalIo`, reusing the execute
-    resolver and the shared `resolveMacTelnetRoute`. Green via
-    `test/integration/terminal-mac-telnet.test.ts` (T1–T3) driving the real
-    `centrs terminal` binary through the subprocess harness.
-  - **Evidence caveat:** the CHR integration runs over the quickchr
-    `socket-connect` **L2 bridge** (`test/integration/mactelnet-l2-bridge.ts`), so
-    the real `createUdpMacTelnetTransport` egress/broadcast path is *not* exercised
-    in CI — the RB1100AHx4 / RouterOS 7.24beta1 real-device run grounded the
-    UDP-delivery facts (and caught the synthetic-source-MAC break). A full-TTY
-    `terminal` test (real PTY via `script(1)`/node-pty) is likewise deferred.
+single home for wire-format, auth, and delivery facts.
+
+| Transport | Status pointer |
+| --------- | -------------- |
+| native-api | Used by `retrieve`, `api`, `execute`, and `transfer`; wire facts in `src/protocols/native-api.ts`. |
+| ssh / sftp | Used by `transfer`, `execute`, and `terminal`; facts in `src/protocols/ssh.ts`, `src/protocols/sftp.ts`, and `src/terminal.ts`. |
+| mac-telnet | Used by `execute` and `terminal`; facts in `src/protocols/mac-telnet.ts`, `src/protocols/mac-telnet-console.ts`, `src/protocols/mtwei.ts`, and `src/protocols/adapter.ts`. |
 
 ### Frontend surfaces (orthogonal to the command grid)
 
@@ -169,9 +131,9 @@ core and carry their own state, tracked here:
 
 | Surface | State | Spec | Notes |
 | ------- | ----- | ---- | ----- |
-| ts-api | `CHR-passed` | `src/index.ts` | Root **TypeScript library** surface; everything else adapts it. (Renamed from `api (TS)` to avoid colliding with the `api` **command** row in the grid above — the command is a verb, this is the library.) |
-| cli | `coded` | `src/cli/` | `retrieve`/`execute`/`transfer`/`terminal`/`devices`/`discover`/`btest` wired. |
-| mcp | `CHR-passed` | `commands/mcp/` | Scoped-verb stdio MCP server; CDB-as-allowlist safety model. Phase 1 (explain/validate/retrieve/execute, resources) plus first Phase 2 CDB mutation (`centrs_devices add`) green on CHR 7.23 via `test/integration/mcp.test.ts`, including gated write execution. |
+| ts-api | `CHR-passed` | `src/index.ts` | Root TypeScript library surface; everything else adapts it. |
+| cli | `coded` | `src/cli/` | Every command in `cliCommands` (`src/cli.ts`) is wired: `retrieve`/`execute`/`api`/`transfer`/`terminal`/`explain`/`devices`/`discover`/`btest`/`mcp`/`settings`, plus the `upload`/`download` shortcuts. |
+| mcp | `CHR-passed` | `commands/mcp/` | Scoped-verb stdio MCP server; details in `commands/mcp/README.md` and `test/integration/mcp.test.ts`. |
 | tui | `not-started` | `src/tui.ts` | Stub. |
 | proxy | `not-started` | `src/webproxy.ts` | Stub. |
 
@@ -183,46 +145,17 @@ are documented in `commands/mcp/README.md` and `commands/mcp/examples.md`.
 
 ### Peer measurement (`btest`) — orthogonal to the command grid
 
-`btest` is the MikroTik **bandwidth test** (peer measurement, TCP/UDP port 2000)
-— *not* a RouterOS-command transport, so it sits outside the command×protocol
-grid as its own capability axis (`measure` in `src/protocols/index.ts`), exempt
-from the `:parse` / `/console/inspect` gate. v1 scope (decided with the user):
-**both** client and server, **EC-SRP5 + unauthenticated**, **TCP and UDP** (legacy
-pre-6.43 double-MD5 is out of scope).
+`btest` is the MikroTik bandwidth test (peer measurement, TCP/UDP port 2000),
+not a RouterOS-command transport. It sits outside the command×protocol grid as
+its own capability axis and is exempt from the RouterOS command-validation gate.
 
 | Mode           | State        | Evidence |
 | -------------- | ------------ | -------- |
-| btest / server | `CHR-passed` | CHR `/tool/bandwidth-test` client → centrs server (TCP+UDP, unauth + EC-SRP5), CHR 7.23.1, `test/integration/btest.test.ts`. |
-| btest / client | `CHR-passed` | centrs client → CHR `/tool/bandwidth-server` over a host→guest `tcp:2000` forward — unauth + **EC-SRP5 client proof verified by real RouterOS** + wrong-pass reject (TCP receive), CHR 7.23.1, `test/integration/btest-client.test.ts`; plus client↔server loopback (`test/unit/btest-*.test.ts`). |
-
-The wire codec, the EC-SRP5 session/handshake (shared core byte-identical with
-mac-telnet's MTWEI, plus the net-new server role), the TCP/UDP data engines, the
-orchestrator + CLI, and the honest grounding caveat (the server gets direct CHR
-evidence over the QEMU SLIRP gateway `10.0.2.2`; the client gets direct CHR
-evidence over a host→guest `tcp:2000` forward (the forward carries TCP; UDP rides
-the guest→host gateway instead, below); UDP-receive was
-previously a soft smoke test because the SLIRP reverse path was believed to block
-real validation and a `connect()` socket filter was silently dropping all received
-datagrams — RouterOS sends UDP data **from a different source port** than the
-negotiated `serverUdpPort`, so the BSD receive filter rejected every packet;
-fixed by removing `connect()` and addressing sends explicitly, validated against
-a real RouterOS device at 163–203 Mbps receive and 104 Mbps bidirectional, and
-**CI now gates UDP client receive/both** — the server→client return rides the
-guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`), needing no UDP forward and no
-quickchr change (#88 closed; the `connect()` filter fix in #86 is what enabled it);
-TCP
-`connection-count` reaches the server's command packet (#84) and centrs opens the
-negotiated extra TCP data connections — multi-connection **fan-out** (#87),
-grounded byte-for-byte against RouterOS 7.23.1 (secondary join
-`[token:u16 BE][0x02][0 …]`) and CHR-gated for the realized fan-out
-(`activeConnections == count`; no throughput-rise assertion — the SLIRP loopback is
-bandwidth-bound); authenticated sessions stay single-stream (warned); TCP
-`direction=both` demuxes the server's
-interleaved status frames so the client paces its TX from feedback and does not
-starve server→client RX (#85 fixed); the Windows unit tier skips UDP-loopback
-tests (#69); NDJSON is not adopted) are
-documented in `commands/btest/README.md` and the `src/protocols/btest.ts`,
-`src/protocols/btest-session.ts`, and `src/protocols/ec-srp5.ts` module headers.
+| btest / server | `CHR-passed` | `test/integration/btest.test.ts`; details in `commands/btest/README.md`. |
+| btest / client | `CHR-passed` | `test/integration/btest-client.test.ts`; details in `commands/btest/README.md`. |
+
+Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
+`src/protocols/btest*.ts` / `src/protocols/ec-srp5.ts` module headers.
 
 ## Priority order
 
@@ -230,18 +163,18 @@ Do not start a later item until the earlier cell or dependency checkpoint has
 matching evidence. The grid above is the live status; per-item detail lives in
 the linked `commands/<name>/`.
 
-1. **retrieve / rest-api** — `CHR-passed`. The shakedown for everything else (`commands/retrieve/`).
+1. **retrieve / rest-api** — `CHR-passed` (`commands/retrieve/`).
 2. **CDB resolution + metadata overrides** — `CHR-passed` (`commands/devices/`).
-3. **CDB groups + fanout** — `CHR-passed` (`commands/devices/`, Fanout).
-4. **execute / native-api + rest-api** — `CHR-passed` (`commands/execute/`). The single write path; there is no `update`.
+3. **CDB groups + fan-out** — `CHR-passed` (`commands/devices/`, fan-out core).
+4. **execute / native-api + rest-api** — `CHR-passed` (`commands/execute/`).
 5. **devices** (CDB mutation + provenance) — `CHR-passed` (`commands/devices/`).
 6. **retrieve / snmp** — `not-started` (future: SNMP OID/MIB reads + MikroTik MIB cache).
-7. **ssh** for transfer/execute/terminal — **all three `CHR-passed`** (landed transfer-first; the `transfer`/`execute`/`terminal` READMEs + `src/protocols/ssh.ts` and `src/protocols/sftp.ts`).
-8. **mac-telnet** for execute/terminal — both `CHR-passed` (`src/protocols/mac-telnet.ts` + `src/protocols/mac-telnet-console.ts`). Optional polish: the ~10s prime-latency fix and a full-TTY terminal test under a real PTY.
+7. **ssh** for transfer/execute/terminal — all three `CHR-passed`.
+8. **mac-telnet** for execute/terminal — both `CHR-passed`.
 9. **RoMON / WinBox Terminal for execute** — `not-started` (see Open questions).
 10. **discover / mndp** — `CHR-passed` (`commands/discover/`).
-11. **MCP, TUI, proxy** — frontends over the stable core. **MCP** is `CHR-passed` for Phase 1 + the first Phase 2 CDB mutation (`commands/mcp/`); next small step is the device-free `centrs mcp --list-tools` manifest dump (bench token-footprint measurement). MCP stays **stdio-only** (HTTP is the proxy's job). **TUI / proxy** `not-started`.
-12. **btest (peer measurement)** — server **and** client both `CHR-passed` (`commands/btest/`). Own protocol axis; shares EC-SRP5 with mac-telnet, so it can proceed in parallel.
+11. **MCP, TUI, proxy** — MCP `CHR-passed`; TUI/proxy `not-started`.
+12. **btest (peer measurement)** — server and client both `CHR-passed`.
 
 ## Open questions (decisions needed before the affected cell can advance)
 

package/docs/errors/README.md

@@ -47,10 +47,14 @@ Codes are slash-namespaced `family/slug`. The families and where they originate:
 - `input/*` — malformed caller input (paths, MACs, arguments).
 - `internal/*` — centrs bugs / unreachable states.
 - `mndp/*` — MNDP wire codec and listener (`src/data/mndp.ts`).
+- `quickchr/*` — the quickchr named-live-provider (`--quickchr <name>`): optional
+  package availability, descriptor version support, and machine lookup/liveness
+  (`src/resolver/quickchr-provider.ts`).
 - `routeros/*` — RouterOS-surfaced faults mapped by the grounded vocabulary in
   `src/core/routeros-errors.ts` (REST `detail` and native-api `!trap`, identical
   on CHR 7.23).
-- `settings/*` — settings/value parsing (`src/resolver/settings.ts`).
+- `settings/*` — settings/value parsing (`src/resolver/settings.ts`) and the
+  `centrs settings` command's own registry/refusal rules (`src/settings.ts`).
 - `target/*` — turning a `<router>` into a transport endpoint.
 - `transport/*` — connection, TLS, DNS, and timeout plumbing.
 - `usage/*` — how a command was invoked (arity, conflicting flags, confirmation).

package/docs/errors/cdb/empty-selection.md

@@ -0,0 +1,19 @@
+# `cdb/empty-selection`
+
+The target selection matched no CDB records.
+
+## Fix
+
+A fan-out selection involving `--where` / `--all` / `--default` / positionals (on
+its own or mixed with `--group`) resolved to zero targets. This is reported as a
+warning on an `ok: true` fan-out envelope with `summary { total: 0, ok: 0, failed:
+0 }`, not a hard failure — there was simply nothing to run.
+
+A **group-only** empty (bare `--group`, no other selector) is reported as
+[`cdb/empty-group`](empty-group.md) instead, naming the group that matched nothing;
+this page covers every other empty selection.
+
+Check the selector: run `centrs devices list` (and `centrs devices groups`) to see
+the registered records, groups, and the facts a `--where <attr>=<value>` can match.
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Target selection) for the
+selector grammar.

package/docs/errors/input/incomplete-gps.md

@@ -0,0 +1,9 @@
+# `input/incomplete-gps`
+
+lat/lon (or a --gps tuple) were not given as a complete pair.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/incomplete-gps`.

package/docs/errors/input/invalid-altitude.md

@@ -0,0 +1,9 @@
+# `input/invalid-altitude`
+
+The altitude is not a number, or altitude-type is not MSL/AGL.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-altitude`.

package/docs/errors/input/invalid-bbox.md

@@ -0,0 +1,9 @@
+# `input/invalid-bbox`
+
+The --bbox is not four lat-first corners with south<=north and west<=east.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-bbox`.

package/docs/errors/input/invalid-coordinate.md

@@ -0,0 +1,9 @@
+# `input/invalid-coordinate`
+
+The latitude or longitude is not a number in its valid range.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-coordinate`.

package/docs/errors/input/invalid-radius.md

@@ -0,0 +1,9 @@
+# `input/invalid-radius`
+
+The --near radius is not a number with an optional m/km/mi/ft suffix.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-radius`.

package/docs/errors/internal/settings-failed.md

@@ -0,0 +1,9 @@
+# `internal/settings-failed`
+
+The settings command failed with an unexpected internal error.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/settings-failed`.

package/docs/errors/quickchr/machine-not-found.md

@@ -0,0 +1,22 @@
+# `quickchr/machine-not-found`
+
+No quickchr machine is registered under the name passed to `--quickchr <name>`.
+
+## Typical trigger
+
+The name does not match any machine quickchr knows about — a typo, a machine
+that was never created, or one that has been removed. centrs raises this both
+when `QuickCHR.get(name)` returns nothing and when the descriptor call reports
+quickchr's own `MACHINE_NOT_FOUND`.
+
+## Fix
+
+- List the registered machines with `quickchr list` and pass an existing name.
+- Create/start the machine first if it does not exist yet (`quickchr start
+  <name>`).
+- Names are exact — check for typos and case.
+
+If the machine exists but is not running, you will see
+[`quickchr/machine-stopped`](./machine-stopped.md) instead.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.

package/docs/errors/quickchr/machine-stopped.md

@@ -0,0 +1,20 @@
+# `quickchr/machine-stopped`
+
+The named quickchr machine exists but is not running, so it has no live
+connection facts (host, forwarded ports, credentials) for centrs to dial.
+
+## Typical trigger
+
+`--quickchr <name>` named a real machine, but its VM is stopped. quickchr only
+knows the forwarded loopback ports and running-state auth while the machine is
+up, so a stopped machine cannot yield a `ServiceEndpointMap`.
+
+## Fix
+
+- Start it: `quickchr start <name>`, then retry `--quickchr <name>`.
+- Confirm state with `quickchr list` / `quickchr inspect <name>`.
+
+This is a per-target failure: in a fan-out over several `--quickchr` targets,
+one stopped machine fails only its own row, not the whole run.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.

package/docs/errors/quickchr/package-unavailable.md

@@ -0,0 +1,27 @@
+# `quickchr/package-unavailable`
+
+The optional `@tikoci/quickchr` package is not installed, so a `--quickchr
+<name>` target cannot be resolved into connection facts.
+
+## Typical trigger
+
+You passed `--quickchr <name>` (or otherwise resolved a quickchr target) in an
+install that does not have `@tikoci/quickchr`. centrs declares it as an
+**optional dependency** and loads it through a runtime import, so a normal
+install without it works for every non-quickchr path and only fails here.
+
+## Fix
+
+- Install the package: `bun add @tikoci/quickchr` (0.4.5+ — 0.4.4 introduced
+  the descriptor v1 API but advertises dead TLS endpoints on a stock CHR;
+  see quickchr#95).
+- Or bypass quickchr entirely and target the device directly with `--host`
+  (plus `--username`/`--password`/`--ssh-key` or a CDB record).
+
+This code is raised **only** when the module is genuinely not found. An
+installed package that throws while loading reports
+[`quickchr/unsupported`](./unsupported.md) instead, so the two are never
+confused.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+the named-live-provider contract.

package/docs/errors/quickchr/unsupported-via.md

@@ -0,0 +1,35 @@
+# `quickchr/unsupported-via`
+
+The quickchr machine resolved fine, but the chosen `--via` has no usable
+service on it. The descriptor is per-service; centrs reads exactly the
+endpoint for the chosen protocol and never falls back to another transport.
+
+## Typical trigger
+
+Any of:
+
+- The `--via` is a protocol the descriptor does not forward. quickchr v1
+  forwards `rest-api`, `native-api`, and `ssh` only — `mac-telnet`, `romon`,
+  `btest`, and `winbox-terminal` are never available on a quickchr target.
+- The service exists but quickchr marked it `available: false` (the error
+  carries the provider's `unavailableReason`).
+- `--via ssh` (or `transfer --via sftp`/`scp`): the SSH endpoint reports no
+  batch-capable auth mode (`batchModes` is empty), so a non-interactive
+  handoff is impossible. centrs fails typed here rather than prompt for a
+  password or silently pick another transport.
+
+## Fix
+
+- Pick one of the machine's live services; the error's `availableServices`
+  context lists them (typically `--via rest-api` / `--via native-api` /
+  `--via ssh`).
+- For the SSH/sftp gate, verify key-based login works from quickchr's side
+  (`quickchr ssh <name>`); once quickchr has a verified key, the descriptor
+  advertises `private-key` in `batchModes` and centrs will use it.
+- If the machine should be forwarding the service but is not, inspect it with
+  `quickchr inspect <name>`.
+- To use a transport quickchr does not forward, target the device directly
+  (`--host`/CDB record) instead of `--quickchr`.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+why a provider's missing service is a typed error, never a silent fallback.

package/docs/errors/quickchr/unsupported.md

@@ -0,0 +1,35 @@
+# `quickchr/unsupported`
+
+The installed `@tikoci/quickchr` cannot give centrs a usable descriptor: it is
+too old to expose the descriptor API, it failed to load, or it emitted a
+descriptor centrs cannot read.
+
+## Typical trigger
+
+Any of:
+
+- The installed quickchr predates the `QuickCHR.get(name).descriptor()` API
+  (before 0.4.4), so the descriptor entry point is missing.
+- The package is installed but throws while loading (a broken/partial install),
+  which is a real fault — distinct from
+  [`quickchr/package-unavailable`](./package-unavailable.md), which means "not
+  installed at all".
+- The descriptor is malformed or pre-v1: no numeric `descriptorVersion`, no
+  `services` map, or missing `name`/`version`/`arch`. centrs rejects it rather
+  than crash on a later field access or silently treat `services` as empty
+  (which would hide a provider contract violation).
+- The descriptor version is **newer** than centrs supports
+  (`descriptorVersion` > 1); a newer quickchr speaks a schema this centrs
+  predates.
+
+## Fix
+
+- Upgrade quickchr to a release that emits descriptor v1: `bun add
+  @tikoci/quickchr` (0.4.5+ — 0.4.4 has the API but a descriptor endpoint
+  bug, quickchr#95).
+- If the descriptor looks wrong, inspect the machine directly with `quickchr
+  inspect <name>` — it may be in a transient state.
+- If the descriptor is newer than centrs supports, upgrade centrs.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+the descriptor contract and the supported version boundary.

package/docs/errors/routeros/version-unsupported.md

@@ -0,0 +1,26 @@
+# `routeros/version-unsupported`
+
+The device's RouterOS version does not provide the operation this command
+needs. centrs pre-flighted the generated command against the device's known
+version (a live read, or the stored CDB `version=` fact) and refused it before
+touching the router, instead of letting the device return a raw protocol
+error.
+
+Distinct from `routeros/unsupported-capability`, where the chosen *protocol*
+cannot carry the operation at all regardless of device version.
+
+## Context fields
+
+- `capability` — stable slug of the missing operation.
+- `version` — the device version that was checked.
+- `versionSource` — `live`, `cdb-fact`, or `caller`. A `cdb-fact` version is
+  stale-by-nature; it was recorded by `discover --save` or `devices --check`.
+- `supported` — the version windows where RouterOS provides the operation
+  (inclusive `min`, optional exclusive `maxExclusive` for backport windows).
+
+## Fix
+
+Upgrade RouterOS to one of the versions listed in `supported`. If the device
+was already upgraded and the check used a stale stored fact
+(`versionSource: "cdb-fact"`), refresh the record's `version=` comment fact
+and retry.