@tikoci/centrs 0.1.2 → 0.1.3

package/docs/MATRIX.md

@@ -30,137 +30,62 @@ 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`    |
 | 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`.
+- `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 +94,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.) |
+| ts-api | `CHR-passed` | `src/index.ts` | Root TypeScript library surface; everything else adapts it. |
 | 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. |
+| 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 +108,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 +126,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

@@ -50,7 +50,8 @@ Codes are slash-namespaced `family/slug`. The families and where they originate:
 - `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/settings/consequential-value.md

@@ -0,0 +1,26 @@
+# `settings/consequential-value`
+
+`settings set` accepted a syntactically valid value with a real, non-obvious consequence (e.g. a global --insecure default, or a transfer-via value gated elsewhere).
+
+## Fix
+
+This is a warning, not a failure — the envelope is still `ok: true` and the
+value is written. `centrs settings set` emits it for exactly two keys today
+(the `warn` callback on the matching `SettingsKeyDef` in `src/settings.ts`):
+
+- `insecure` set to any truthy spelling (`true`, `yes`, `on`, `1`) makes
+  every command run without an explicit `--insecure`/`--no-insecure`
+  override trust RouterOS's self-signed TLS certificate or unknown SSH host
+  key globally, not just for one invocation. See the `insecure` row in
+  `commands/settings/README.md`'s "Known settings keys" table.
+- `transfer-via` set to `ftp` is accepted here — `ftp` is a syntactically
+  valid `CENTRS_TRANSFER_VIA` value — but `transfer` still rejects it at
+  call time with [`settings/unsafe-protocol-blocked`](unsafe-protocol-blocked.md)
+  unless `ALLOW_UNSAFE_PROTOCOLS` also includes `ftp`. The warning exists so
+  the write doesn't silently look like it "worked" when the value won't
+  actually take effect anywhere else yet.
+
+There is nothing to fix in the sense of retrying with different input — the
+value you asked for was written as requested. Run `centrs settings set
+insecure false` or pick a different `transfer-via` value if the consequence
+wasn't intended. See example 24 in `commands/settings/examples.md`.

package/docs/errors/settings/invalid-boolean.md

@@ -4,6 +4,24 @@ A boolean-like setting received a non-boolean value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-boolean`.
+`centrs settings set <attr> <value>` throws this for the three boolean-typed
+managed keys — `mcp-allow-adhoc`, `validate`, `insecure` — when `<value>`
+isn't one of the spellings the shared parser (`parseBoolean` in
+`src/resolver/settings.ts`) accepts: `true`/`false`, `yes`/`no`, `on`/`off`,
+or `1`/`0`, case-insensitively. Anything else — `maybe`, `2`, an empty
+string — fails with a remediation listing the accepted spellings.
+
+This isn't a `settings`-only rule: `parseBoolean` backs every `CENTRS_*`
+boolean setting across the app, so the same error and message shape appears
+whenever any command resolves a boolean env var to an unrecognized value,
+not just through `settings set`.
+
+One canonicalization detail worth knowing even though it isn't what triggers
+this error: once a boolean value *does* validate, `settings set` always
+writes the canonical `1` or `0` to `centrs.env`, never `true`/`false` —
+`CENTRS_MCP_ALLOW_ADHOC`'s reader in `src/mcp/config.ts` checks the literal
+string `"1"` rather than reusing `parseBoolean`, so writing `1`/`0`
+uniformly is what satisfies every reader. Retry `set` with one of the
+accepted spellings above; see
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-format.md

@@ -4,6 +4,21 @@ An unsupported output format was requested.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-format`.
+`centrs settings set format <value>` throws this when `<value>` isn't one of
+`text`, `json`, or `yaml` — the same `{text, json, yaml}` set every
+command's own `--format` flag (and `CENTRS_FORMAT`) validates against
+(`retrieveOutputFormats` and its `execute`/`transfer`/`api` counterparts).
+`centrs settings set format xml` is the canonical trigger; see example 14 in
+`commands/settings/examples.md`. A failed `set` never partially writes — the
+file is unchanged.
+
+`format` is the one managed key without a single universal built-in
+default: `retrieve`/`execute`/`transfer` default to `text`, but `api`
+defaults to `json`. Because of that, `centrs settings print`/`get format`
+can't report one scalar default when the key is unset — it reports a
+`perCommandDefault` map (`{ retrieve: "text", execute: "text", transfer:
+"text", api: "json" }`) instead, so this is the one key where "unset" looks
+different in the output shape than every other key.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for
+where `format` sits in the resolver chain once a value is set.

package/docs/errors/settings/invalid-integer.md

@@ -4,6 +4,21 @@ An integer setting received a non-integer or out-of-range value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-integer`.
+`centrs settings set max-results <value>` and `centrs settings set port
+<value>` both throw this when `<value>` fails the shared positive-integer
+rule (`resolveOptionalIntegerSetting` in `src/resolver/settings.ts`):
+`Number.isInteger(n) && n > 0`. `0`, negative numbers (`-1`), and
+non-numeric strings (`abc`) are all rejected the same way — `centrs settings
+set max-results 0` is the canonical trigger (example 20 in
+`commands/settings/examples.md`).
+
+This validator isn't specific to `settings` — `resolveOptionalIntegerSetting`
+is the shared helper every `CENTRS_*` integer setting resolves through
+(`max-results`, `port`, and any future integer key), so the same code and
+message shape appear whenever an integer env var, CLI flag, or `centrs.env`
+line resolves to a non-positive or non-numeric value anywhere in the app,
+not only through `settings set`.
+
+A failed `set` never partially writes; re-run with a positive integer. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-timeout.md

@@ -4,6 +4,23 @@ A timeout setting received an invalid value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-timeout`.
+`centrs settings set timeout <value>` throws this when `<value>` doesn't
+match the shared duration grammar (`parseDuration` in
+`src/resolver/settings.ts`): a bare integer (milliseconds) or an integer
+with a `ms`/`s`/`m` suffix — `500ms`, `5s`, `1m`. Anything else, like
+`not-a-duration` (example 22 in `commands/settings/examples.md`), fails.
+`settings.ts` layers one more rule on top for `timeout` specifically: even a
+syntactically valid duration that parses to `0` is rejected — a zero timeout
+isn't a meaningful value to set.
+
+Like the other typed-value codes here, this isn't `settings`-exclusive:
+`parseDuration` backs `CENTRS_TIMEOUT` and every command's own `--timeout`
+flag, so the same failure shape shows up anywhere a duration string is
+resolved, not just through `settings set`.
+
+One write detail worth knowing: `settings set timeout` writes the
+**canonical parsed milliseconds**, not the raw suffixed string you typed —
+`centrs settings set timeout 5s` writes `CENTRS_TIMEOUT=5000` to
+`centrs.env`, not `CENTRS_TIMEOUT=5s`. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-via.md

@@ -4,6 +4,25 @@ An unsupported protocol identifier was supplied to --via.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-via`.
+This one code covers two different value sets, because `settings` reuses it
+for two different keys. `centrs settings set via <value>` requires one of
+the protocol identifiers in `plannedProtocols` (`src/protocols/index.ts`):
+`rest-api`, `native-api`, `ssh`, `snmp`, `mndp`, `mac-telnet`, `romon`,
+`winbox-terminal` — `centrs settings set via carrier-pigeon` is the
+canonical trigger (example 21 in `commands/settings/examples.md`).
+`centrs settings set transfer-via <value>` reuses the same error code but
+validates against a completely different set: `auto`, `rest`/`rest-api`,
+`native`/`native-api`, `sftp`, `scp`, `fetch`, `ftp`. Unlike `CENTRS_VIA`,
+which has a per-device `via=` comment-kv counterpart, `CENTRS_TRANSFER_VIA`
+has none — `transfer` reads only the env var.
+
+The same validation backs `retrieve`/`execute`/`api`'s own `--via` flag more
+broadly, so the identical code and message shape appear there too, not only
+through `settings set`.
+
+`transfer-via ftp` is syntactically valid against the `transfer-via` set
+above — it does **not** trigger this error — but it does trigger a separate
+warning, [`settings/consequential-value`](consequential-value.md), because
+`transfer` still rejects `ftp` at call time unless `ALLOW_UNSAFE_PROTOCOLS`
+also opts in. See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Protocol
+selection) for the full `via` vocabulary.

package/docs/errors/settings/reserved-key.md

@@ -0,0 +1,29 @@
+# `settings/reserved-key`
+
+`settings set`/`reset` refused a credential-shaped or self-referential CENTRS_* key.
+
+## Fix
+
+`centrs settings set <attr> <value>` and `centrs settings reset <attr>` refuse
+five keys outright: `password`, `username`, `cdb-password`, `skip-env-file`,
+and `run-fast-integration` (the `settingsRefusedKeys` list in
+`src/settings.ts`). Each is refused for a different reason, not a blanket
+policy: `password`/`username` are credential-shaped and belong on the
+`__default__` CDB record — run `centrs devices add __default__ --user …
+--password …` instead of duplicating a secret into a second, unencrypted
+file. `cdb-password` is the CDB's own decrypt password; writing it beside the
+encrypted CDB it unlocks would defeat the encryption, so pass
+`--cdb-password` per invocation or export `CENTRS_CDB_PASSWORD` in the
+calling shell instead. `skip-env-file` is self-referential — a line in
+`centrs.env` that says "ignore this file" is a no-op by construction, since
+the file has to be read to find it. `run-fast-integration` is a CI/test
+signal `bun run test:integration` sets, never a human preference.
+
+`settings get`/`settings print` still work read-only on all five keys — this
+error is specific to the write path (`set`/`reset`). A read of `cdb-password`
+or `password` redacts the value rather than refusing outright; see
+[`settings/unknown-key`](unknown-key.md) for the different case of a token
+that isn't a recognized setting at all. See examples 17 and 29 in
+`commands/settings/examples.md`, and
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Identity and CDB) for why
+credentials route through `devices` rather than `centrs.env`.

package/docs/errors/settings/skip-env-file-active.md

@@ -0,0 +1,25 @@
+# `settings/skip-env-file-active`
+
+`settings print` ran under --skip-env-file; the shown centrs.env values would not apply to other commands run in the same environment.
+
+## Fix
+
+This is an informational warning, not a failure — `centrs settings print`
+still returns `ok: true` with the file's real contents. It appears only when
+`--skip-env-file` (or `CENTRS_SKIP_ENV_FILE`) was active on that same
+`print` invocation, as a reminder that the flag doesn't apply to `settings`
+itself: `settings` always reads and writes the real `centrs.env` file
+regardless of `--skip-env-file`, since inspecting/editing the file is this
+command's whole job (see the module doc comment at the top of
+`src/settings.ts`).
+
+What the warning is actually flagging is every *other* command: if
+`--skip-env-file`/`CENTRS_SKIP_ENV_FILE` is also active when you run
+`retrieve`/`execute`/`transfer`/`api` in that same shell or environment,
+those commands' resolvers skip loading `centrs.env` as a settings source —
+so the values `print` just showed you would not apply there. There's
+nothing to fix; either drop `--skip-env-file` if you want other commands to
+see these values, or ignore the warning if the isolation is intentional. See
+example 6 in `commands/settings/examples.md`, and
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+the config tier fits into the precedence ladder.