@tikoci/centrs 0.1.2 → 0.1.4

package/commands/retrieve/README.md

@@ -1,5 +1,9 @@
 # retrieve
 
+Status: `CHR-passed` over `rest-api` and `native-api`, including multi-target
+fan-out (see **Target selection**). `snmp` is `not-started`. Matches
+`docs/MATRIX.md`.
+
 Read RouterOS state. RouterOS menu reads model `<path>/<verb>` where the verb
 is `print`-style (`print`, `get`, and async POST-shaped reads as they're
 added). SNMP reads use `retrieve <router> snmp <oid|MIB name>` and resolve
@@ -39,33 +43,32 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 
 ## Flags
 
-| Flag                                | Behavior                                                                                  |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → retrieve](../../docs/CLI.md#retrieve); this file does not
+duplicate that table. Behavior notes the generated reference cannot carry:
+
+- `--format json` (shortcut `--json`): set `CENTRS_FORMAT=json` to make the
+  structured envelope the default. `--format yaml` renders the same envelope.
+- `--port`: native-api defaults to 8728; `--port 8729` selects TLS `api-ssl`.
+- `--query`/`--filter` are RouterOS **row** filters and always return an
+  array (see Synopsis); `--where` filters *which devices* fan out, not rows.
+- `--all-attributes` conflicts with `--attribute(s)` (see Validation).
+- `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
+  (0.4.5+, optional dependency) descriptor, bypassing CDB/env resolution for
+  those fields.
+
+### Designed, not implemented
+
+Spec-tier flags with no implementation yet — today they fail as unknown flags:
+
+| Flag                                | Designed behavior                                                                          |
 | ----------------------------------- | ----------------------------------------------------------------------------------------- |
-| `--attribute <name>`                | Project a single attribute. Repeatable, or comma-separated.                               |
-| `--attributes <a,b,c>`              | Alias for `--attribute` with comma-separated input.                                       |
-| `--all-attributes`                  | Equivalent to RouterOS `details=true`. Mutually exclusive with `--attribute(s)`.          |
-| `--list-attributes` (alias `--list`) | Return the available attribute names for the path. No `print`/`get` is run.              |
 | `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is `api … --stream`. See constitution: protocol selection. |
-| `--query <expr>`                    | RouterOS-side **row** filter (maps to `.query`), repeatable; returns matching rows as an **array**. This is how you read one row by name (`--query name=ether1`). **Not Implemented** yet — returns `validation/not-implemented`. |
-| `--filter <expr>`                   | RouterOS row filter; same `.query` mapping and not-implemented handling as `--query`.       |
-| `--where <attr>=<value>`            | Device-class selector: fan out across CDB records whose stored fact/comment-kv matches (e.g. `--where board=RB5009`). Repeatable (AND). Filters *which devices*, not RouterOS rows. See constitution: target selection. |
-| `--max-bytes <n>`                   | Byte budget for the rendered payload. If the response would exceed it, centrs truncates to fit, keeps `ok: true`, and adds a warning + `meta.truncated`. Not an error. (Renamed from `--max-results`; the legacy flag still parses until the code split lands.) |
+| `--max-bytes <n>`                   | Byte budget for the rendered payload. If the response would exceed it, centrs truncates to fit, keeps `ok: true`, and adds a warning + `meta.truncated`. Not an error. (Will replace the implemented `--max-results`, which fails instead of truncating.) |
 | `--max-rows <n>`                    | Maximum row count for list reads. Excess rows are clipped; `ok: true` with a warning + `meta.truncated`.                                    |
-| `--format text` (default)           | Human-readable rendering (default). Errors print `[code] summary` + `Fix:` lines. |
-| `--format json` (alias `--json`)    | Structured JSON envelope (set `CENTRS_FORMAT=json` to make it the default).               |
-| `--format yaml` (alias `--yaml`)    | YAML rendering of the same envelope.                                                      |
-| `--resolve <none\|arp>`             | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.             |
-| `--via <protocol>`                  | Pin the transport (`rest-api` default, or `native-api`). No silent downgrade. See constitution: protocol selection. |
-| `--validate=false`                  | Escape hatch; default is `true`. See constitution: validation is the product.             |
-| `--timeout <ms>`                    | Request timeout. REST: ≤ 60000. native-api allows longer.                                 |
-| `--username` (alias `--user`, `-u`) / `--password` | Override CDB-resolved or env credentials.                                                 |
-| `--host <host\|url>`                 | Override the resolved host or base URL for the target.                                     |
-| `--port <n>`                        | Override the transport port. native-api defaults to 8728 (TLS api-ssl when `--port 8729`).|
-| `--cdb-file` / `--cdb-password`     | Override CDB file location / decrypt password.                                            |
+| `--yaml`                            | Shortcut for `--format yaml`.                                                             |
 | `--ros-version <version>`           | SNMP MIB lookup only: pin the MikroTik MIB version to cache/download.                     |
 | `--ros-channel <channel>`           | SNMP MIB lookup only: `stable`, `long-term`, `testing`, or `development`; default `stable`. |
-| `--group <name>`                    | Fan out across every CDB target in WinBox group `<name>`. Repeatable, and combinable with `<router>` positionals plus `--all`/`--default`; the union is de-duped by CDB record index. See **Group fanout**. |
-| `--concurrency <n>`                 | Max in-flight targets during fanout (integer ≥ 1). Defaults are transport-aware: `rest-api` 8, `native-api` 4. Rejected with `usage/invalid-concurrency` otherwise. |
 
 ## Validation
 
@@ -137,55 +140,36 @@ warning entry — it is not an error. (Earlier text said a byte overflow returns
 *error* with the needed size; superseded — truncation is an `ok: true` footnote so
 partial data stays usable.)
 
-## Group fanout
-
-`--group <name>` loads the CDB once, expands every matching WinBox record in
-that group, de-dupes by CDB record index, and runs the same per-target retrieve
-pipeline for each target. Per the shared target-selector grammar, `--group` is
-repeatable and combines freely with one or more `<router>` positionals, `--all`
-(every CDB record), and `--default` (the `__default__` record); the union is
-de-duped by CDB record index. (Earlier drafts made `--group` mutually exclusive
-with a positional — superseded by the liberal selector model.)
-
-Fanout output is one outer envelope whose `ok` reports orchestration success:
-`ok: false` is reserved for failures before reliable per-target results exist
-(for example invalid flags or CDB decrypt failure). Per-target success/failure
-is data, not metadata:
-
-```ts
-{
-  ok: true,
-  data: {
-    summary: { total: 2, ok: 1, failed: 1 },
-    targets: [
-      { ok: true, data: { ... }, meta: { target: { recordIndex: 0 }, ... } },
-      { ok: false, error: { code: "transport/connection-refused", ... }, meta: { target: { recordIndex: 1 }, ... } }
-    ]
-  },
-  warnings: [],
-  meta: {
-    target: {},
-    via: "rest-api", // null if inner targets disagree on protocol
-    settings: { ... },
-    operation: {
-      kind: "fanout",
-      group: "prod-edge",
-      concurrency: 8,
-      summary: { total: 2, ok: 1, failed: 1 },
-      request: { path: "/system/resource", validate: true, format: "json", ... }
-    }
-  }
-}
-```
-
-An empty or unknown group is `ok: true` with
-`data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`, and a
-`cdb/empty-group` warning. Validation runs per target because RouterOS schemas
-can differ by version. Fanout retries each target up to two times only for
-`transport/network` and `transport/connection-closed`; REST 5xx failures are
-mapped to `transport/connection-closed`. It does not retry `routeros/*`,
-`validation/*`, `auth/*`, `cdb/*`, `target/*`, timeouts, DNS, TLS, or refused
-connections.
+## Target selection
+
+retrieve fans out over the **shared target-selection grammar** — multiple
+`<router>` positionals, repeatable `--group`/`--where`, the geo selectors
+`--near`/`--bbox`, `--all`, and `--default`, combined as a set and de-duped by
+CDB record index. The grammar, the locked `FanoutData`
+envelope (`data = { summary, targets[] }`, outer `ok` = orchestration success,
+per-target failure is an inner `ok:false`), the record-order reassembly, and the
+granular **0/2/1 exit code** are all normative in
+[`docs/CONSTITUTION.md` → Target selection grammar](../../docs/CONSTITUTION.md#target-selection-grammar).
+The boundary is intent-keyed: a plain single-positional `retrieve <router> <path>`
+stays the single-target envelope; a selector flag or a second positional target
+switches to fan-out. `--quickchr <name>` (the named-live-provider) behaves like a
+lone positional: one flag stays single-target, repeating it fans out, and mixing
+it with positionals or CDB selectors is `usage/conflicting-flags` (constitution:
+resolution providers).
+
+retrieve-specific behavior on top of the shared engine:
+
+- The CDB is loaded + decrypted **once** for the whole fan-out; each target is
+  then resolved and **validated independently**, because RouterOS schemas can
+  differ by version (`/console/inspect` runs per target).
+- An empty or unknown selection is `ok: true` with
+  `data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`, a
+  `cdb/empty-group` / `cdb/empty-selection` warning, and exit `0`.
+- Each target retries up to two times **only** for `transport/network` and
+  `transport/connection-closed` (REST 5xx is mapped to
+  `transport/connection-closed`). It does **not** retry `routeros/*`,
+  `validation/*`, `auth/*`, `cdb/*`, `target/*`, timeouts, DNS, TLS, or refused
+  connections.
 
 ## Definition of done
 

package/commands/retrieve/examples.md

@@ -162,15 +162,16 @@ Call succeeds with a `cdb/password-not-needed` warning in `meta.warnings`.
 centrs retrieve $R /system/resource --cdb-file $CDB --cdb-password ignored --json
 ```
 
-## Group fanout
+## Target selection (fan-out)
 
-These are exercised by `test/integration/fanout-retrieve.test.ts` when CHR
-integration is enabled.
+These exercise the shared target-selection grammar
+([`docs/CONSTITUTION.md` → Target selection grammar](../../docs/CONSTITUTION.md#target-selection-grammar)).
+`test/integration/fanout-retrieve.test.ts` runs them when CHR integration is
+enabled. `$CDB` contains two records in group `fanout-chr`: record 0 is the live
+CHR (comment fact `role=edge`) and record 1 is an unreachable REST URL (comment
+fact `role=core`).
 
-### F1. Group fanout with one inner success and one inner failure
-
-`$CDB` contains two records in group `fanout-chr`: record 0 is the live CHR and
-record 1 is an unreachable REST URL.
+### F1. Group fan-out with one inner success and one inner failure
 
 ```bash
 centrs retrieve --group fanout-chr /system/resource --cdb-file $CDB --json
@@ -179,7 +180,7 @@ centrs retrieve --group fanout-chr /system/resource --cdb-file $CDB --json
 Outer envelope: `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`,
 `data.targets` is ordered by CDB `recordIndex`, and `meta.operation.kind` is
 `fanout`. The unreachable target is an inner `ok: false` envelope with
-`transport/connection-refused`.
+`transport/connection-refused`. Process exit `2` (partial).
 
 ### F2. Empty / unknown group
 
@@ -188,7 +189,37 @@ centrs retrieve --group no-such-group /system/resource --cdb-file $CDB --json
 ```
 
 Envelope: `ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
-`data.targets = []`, and warnings include `cdb/empty-group`.
+`data.targets = []`, and warnings include `cdb/empty-group`. Exit `0`.
+
+### F3. `--where` device-class selector (subset)
+
+```bash
+centrs retrieve --where role=edge /system/resource --cdb-file $CDB --json
+```
+
+`--where` matches the raw comment fact, selecting only record 0:
+`data.summary = { total: 1, ok: 1, failed: 0 }`,
+`meta.operation.selection.where = ["role=edge"]`, exit `0`.
+
+### F4. `--all` (every CDB record)
+
+```bash
+centrs retrieve --all /system/resource --cdb-file $CDB --json
+```
+
+`--all` fans across every record (excluding `__default__`) — here both, so
+`data.summary = { total: 2, ok: 1, failed: 1 }`,
+`meta.operation.selection.all = true`, exit `2`.
+
+### F5. Multiple positional targets (ad-hoc literals)
+
+```bash
+centrs retrieve $REACHABLE_URL $UNREACHABLE_URL /system/resource --username $U --password $P --json
+```
+
+More than one positional target is fan-out mode without any selector flag. With
+no `--cdb-file`, both are ad-hoc literals, labeled by `meta.target.input` with no
+`recordIndex`: `data.summary = { total: 2, ok: 1, failed: 1 }`, exit `2`.
 
 ## Format
 
@@ -304,3 +335,19 @@ centrs retrieve $A /system/resource --attribute bogus-attr --via native-api --po
 ```bash
 centrs retrieve $A /system/resource --via native-api --port $API_PORT --username wrong --password wrong
 ```
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR
+(`quickchr list`). No `$R`/`$U`/`$P` — host/port/auth come from the live
+descriptor. Covered by `test/integration/quickchr-target.test.ts`.
+
+### Q1. `--quickchr <name>` resolves the VM's REST endpoint
+
+```bash
+centrs retrieve --quickchr $NAME /system/resource --json
+```
+
+Envelope: `ok: true`, `meta.via=rest-api` (normal default; quickchr does not
+change protocol selection), `meta.target.source.kind=provider`,
+`meta.target.identity=$NAME`, no `recordIndex` (the CDB was never consulted).

package/commands/settings/README.md

@@ -3,49 +3,198 @@
 Read and write centrs's own settings — the global `centrs.env` preferences and
 the `__default__` fallback record — and run first-time setup.
 
-Status: `designed`. This file describes intent and flags; no implementation yet.
+Status: `CHR-passed` for the surface described by `examples.md` (fixture-backed
+integration tests — `settings` performs no network IO, so no CHR is needed).
 See `docs/MATRIX.md` for the cell state. `settings` is the front-end to the
 settings the constitution defines (Settings precedence: the `centrs.env` config
 file at tier 2; `__default__` fallback creds): it does not invent new settings,
-only edits the ones already specified.
+only edits the ones already specified. The interactive first-time-setup flow
+(bare `centrs settings` under a TTY) remains a deferred later slice — see
+"Surface" below.
 
 ## Why
 
 centrs deliberately has no store of its own for *inventory* — that is the CDB.
-But it does have **global, centrs-only preferences** (default discovery window,
-default `--format`, concurrency, …) that have no per-device home, and a
+But it does have **global, centrs-only preferences** (default output format,
+default result limit, MCP toggles, …) that have no per-device home, and a
 **`__default__` fallback record** for credentials. Today both are hand-edited
 (`centrs.env`, or `devices add __default__`). `settings` makes that ergonomic and
 is where onboarding flows steer the user.
 
+(Considered and declined: folding `centrs.env` into the future TikTOML device
+format, #137. TikTOML's locked scope is inventory — devices/groups/links,
+credential-by-reference — and stays that way; see the research posted on #137
+for the reasoning. `centrs.env` stays a standalone file.)
+
+## Scope boundary: which `CENTRS_*` keys `settings` manages
+
+Not every `CENTRS_*` env var belongs to `settings`. Two groups, and the split
+matters for what `get`/`set`/`print`/`reset` accept:
+
+1. **Managed — full `settings` support.** Every `CENTRS_*` var that a real
+   command currently reads, validated with the same rules the consuming code
+   already applies (the shared `parseBoolean`/`parseDuration`, a command's own
+   enum, `resolveOptionalIntegerSetting`, …), gets full `get`/`set`/`print`/
+   `reset`. This includes both tool-behavior keys (`format`, `max-results`,
+   `cdb-file`, `resolve`, `mcp-allow-adhoc`) and keys that also have a
+   per-device CDB comment-kv counterpart (`via`, `validate`, `timeout`,
+   `port`, `ssh-key`, `insecure`) — an earlier draft of this README tried to
+   split those into a second, "unmanaged" tier on the theory that
+   `settings` "has no visibility into device context." That theory didn't
+   hold up: writing `CENTRS_VIA=ssh` to `centrs.env` is mechanically
+   identical to writing `CENTRS_FORMAT=json` — a context-free line write —
+   and the existing precedence ladder already places the file **below**
+   comment-kv (constitution: tier 2 < tier 3), so a device's own `via=`
+   override always wins regardless of how the global default was set.
+   There's no real distinction left to justify treating these keys worse.
+   See the table below for validation per key, including which ones also
+   have a comment-kv form (informational — it doesn't change how `settings`
+   treats them).
+2. **Refused — must not be written by `settings`.** Credential-shaped or
+   self-referential keys. `settings set`/`settings reset` on any of these is
+   a hard `settings/reserved-key` error with a remediation pointer:
+
+   | Key | Why refused | Use instead |
+   | --- | --- | --- |
+   | `CENTRS_PASSWORD`, `CENTRS_USERNAME` | Default credentials belong to the `__default__` CDB record, which routes through the `devices` write layer and is redacted from structured output (constitution: identity and CDB). A parallel copy in a plaintext file is a second source of truth for the same secret, one that is never redacted. | `centrs devices add __default__ --user … --password …` |
+   | `CENTRS_CDB_PASSWORD` | This is the CDB's own decryption password. Storing it beside an *encrypted* CDB in a plaintext sibling file defeats the encryption. Security-sensitive surface per `SECURITY.md`. | Pass `--cdb-password` per invocation, export the env var in the calling shell, or use `Bun.secret()` once available — never persist to `centrs.env`. |
+   | `CENTRS_SKIP_ENV_FILE` | Self-referential: it means "don't load `centrs.env`." Writing it *into* `centrs.env` is a no-op by construction (a file that says "ignore me" is never read to find out). | Export it in the shell or pass `--skip-env-file` per call. |
+   | `CENTRS_RUN_FAST_INTEGRATION` | A CI/test signal, not a user preference. | N/A — set by `bun run test:integration`, never by a human. |
+
+   `settings get`/`settings print` on a refused key still works as read-only
+   inspection, **except the value itself**: `CENTRS_PASSWORD` and
+   `CENTRS_CDB_PASSWORD` are always shown as `"(redacted)"` (with an `isSet`
+   boolean instead of the value) regardless of whether the real secret came
+   from the process environment or — despite `set` refusing to write it —
+   was hand-added to the file directly. `settings` cannot stop a human from
+   editing `centrs.env` with a text editor, so the redaction has to be a
+   read-time defense, not just a write-time refusal. `CENTRS_USERNAME` is
+   refused-on-write (it belongs on the `__default__` record, not for secrecy
+   reasons) but is not secret and is shown in full on read.
+
+## Known settings keys
+
+| Key | Type | Built-in default | Comment-kv counterpart? | Notes |
+| --- | --- | --- | --- | --- |
+| `CENTRS_FORMAT` | enum: `text`\|`json`\|`yaml` | Varies **per command** (`api` defaults `json`; `retrieve`/`execute`/`transfer` default `text`) | No | See "Precedence and what `print`/`get` can actually report" below — `print` cannot show one universal current format. |
+| `CENTRS_CDB_FILE` | path | `~/.config/tikoci/winbox.cdb` (`defaultCdbPath`) | No | Existence is not checked at `settings set` time — pre-configuring a path before the file exists is valid. |
+| `CENTRS_MAX_RESULTS` | positive integer | command-specific (`retrieve`, `execute`) | No | `settings/invalid-integer` on a non-positive or non-integer value (`resolveOptionalIntegerSetting` rules). |
+| `CENTRS_RESOLVE` | enum: `none`\|`arp` | `none` | No | Governs MAC→IP fallback resolution (`src/resolver/mac.ts`, `parseResolvePolicy`). |
+| `CENTRS_MCP_ALLOW_ADHOC` | boolean | `false` | No | Currently gates a **not-yet-built** MCP feature (`src/mcp/config.ts` docstring: "reserved for future work, not yet honored"). Safe to expose in `settings` ahead of the feature — `print` should annotate it `(reserved, not yet active)`. **Its reader checks only the literal string `"1"`** (`test/unit/mcp-config.test.ts`: `"true"` → false), not the shared boolean parser — see the canonicalization rule below. |
+| `CENTRS_VIA` | enum: `rest-api`\|`native-api`\|`ssh`\|`snmp`\|`mndp`\|`mac-telnet`\|`romon`\|`winbox-terminal` | `rest-api` (per `retrieve`; other commands vary the same way `format` does) | Yes — `via=` | `settings/invalid-via` on an unrecognized value. |
+| `CENTRS_VALIDATE` | boolean | `true` | Yes — `validate=` | `settings/invalid-boolean`. |
+| `CENTRS_TIMEOUT` | duration (`500ms`, `5s`, `1m`, or bare ms) | command-specific | Yes — `timeout=` | `settings/invalid-timeout` (`parseDuration` rules). |
+| `CENTRS_PORT` | positive integer | protocol-default (no built-in default; unset falls through to the transport's own port) | Yes — `port=` | `settings/invalid-integer`. |
+| `CENTRS_SSH_KEY` | path | unset | Yes — `ssh-key=` | Path only, never key material — matches the per-device form's own rule. Non-blank check only; existence isn't checked at set time. |
+| `CENTRS_INSECURE` | boolean | `false` | Yes — `insecure=` | Accept RouterOS's self-signed TLS cert. `settings set` should still surface a one-line reminder of what it does (`meta.warnings`), since it's a security-relevant toggle even though it's fully validated like any other boolean key. |
+| `CENTRS_TRANSFER_VIA` | enum: `auto`\|`rest`/`rest-api`\|`native`/`native-api`\|`sftp`\|`scp`\|`fetch`\|`ftp` | `auto` | **No** — `transfer` reads only the env var (`src/transfer.ts`, `selectTransferMethod`); there is no `transfer-via=` comment-kv key today. | `scp`/`fetch` currently error `not-implemented`; `ftp` is blocked unless `ALLOW_UNSAFE_PROTOCOLS` opts in — `settings set transfer-via ftp` should surface that same warning rather than silently accepting a value that will fail at call time. |
+| `CENTRS_HOST` | string | unset (falls back to the target positional) | No (comment-kv has `target`/lookup keys, not a `host` override) | An unusual thing to default globally — most calls pass an explicit target — but it's a real, coded env var, so `settings` exposes it rather than editorializing. Non-blank check only. |
+
+**Boolean write canonicalization:** `settings set <bool-key> <value>` accepts
+any spelling the shared `parseBoolean` recognizes (`true`/`false`, `yes`/`no`,
+`on`/`off`, `1`/`0`) as *input*, but always **writes the canonical `1` or
+`0`** to the file, never `true`/`false`. This is driven by
+`CENTRS_MCP_ALLOW_ADHOC`'s strict `=== "1"` reader (a locked, tested
+behavior — changing it is out of scope here) — writing `1`/`0` uniformly
+satisfies that reader *and* is valid input to every `parseBoolean`-based
+reader, so one write rule works for both without touching `mcp/config.ts` or
+its test.
+
+*Devices/README.md note:* its comment-kv override-key table does not
+currently list `insecure`, even though `commentKvAllowlist`
+(`src/resolver/comment-kv.ts`) does. That's a pre-existing doc/code drift in
+`devices`' own spec, unrelated to `settings` — flagging it here since this
+research surfaced it, not fixing it in this file.
+
+### Not yet wired — exclude from v1
+
+`CENTRS_CONCURRENCY`, `CENTRS_DISCOVER_TIMEOUT`, and `CENTRS_CHECK_IGNORE` are
+named in this file's earlier prose and in the constitution's example list, but
+**no command in `src/` currently reads them**:
+
+- Fan-out concurrency is `--concurrency` plus a hardcoded transport-aware
+  default (REST 8, native-api 4) — there is no env var read anywhere in
+  `src/*-fanout.ts`.
+- `discover` reads only `--timeout` / `DISCOVER_DEFAULT_TIMEOUT_MS` — no
+  `CENTRS_DISCOVER_TIMEOUT` read exists.
+- `CENTRS_CHECK_IGNORE` belongs to `check`, which is itself only `designed`
+  (not coded).
+
+Shipping `settings set concurrency 8` today would silently do nothing —
+succeed, persist a line, and never affect a single fan-out call. That's a
+worse UX than not offering the key. **Recommendation: drop these three from
+the v1 `settings` vocabulary entirely** (not even `get`-able) until the
+consuming command actually reads the env var; add them back to the table
+above in the same change that wires the read. This is a real prerequisite,
+not a documentation nit — pursuing it here would either ship a lying command
+or block #135 on unrelated fan-out/discover changes.
+
 ## Surface
 
 ```text
 centrs settings                                # interactive setup (TTY)
-centrs settings print [<attr>]                 # show resolved settings + sources
+centrs settings print [<attr>] [--all] [--cdb-file <path>] [--cdb-password <pw>]
 centrs settings get <attr>                     # read one value
 centrs settings set <attr> <value>             # write one value to centrs.env
 centrs settings reset [<attr>]                 # clear one/all back to built-in default
 ```
 
-- **Interactive (`centrs settings`, TTY):** prompts (clack-style, like
-  `@tikoci/quickchr`) to optionally collect a default `user`/`password` (written
-  to the `__default__` record so a fresh CDB "starts useful"), confirm/update
-  global preferences, and report where the `centrs.env` lives. Non-TTY runs of
-  bare `settings` print the resolved settings instead of prompting.
+- **Interactive (`centrs settings`, TTY) — deferred later slice, not built.**
+  Eventually: prompts (clack-style, like `@tikoci/quickchr`) to optionally
+  collect a default `user`/`password` (written to the `__default__` record so
+  a fresh CDB "starts useful"), confirm/update global preferences, and report
+  where the `centrs.env` lives. **Implementation prerequisite:** centrs has no
+  prompt-library dependency today (`package.json` lists only `zod` and the MCP
+  SDK) — this slice needs one added (`@clack/prompts`, matching the
+  `@tikoci/quickchr` reference). Until it ships, bare `centrs settings`
+  behaves identically to `settings print` **regardless of TTY** — matching
+  the issue's own phasing, which explicitly said not to block the
+  non-interactive surface (built below) on this later slice.
 - **Non-interactive (`set`/`get`/`reset`/`print`):** scriptable edits to
-  `centrs.env`. `print` shows each resolved setting with its winning source
-  (`default` / `centrs.env` / `env` / `cli`), mirroring `meta.settings`.
+  `centrs.env`. Exit code `0` on success, `1` on a validation/refusal error —
+  matching the plain (non-fan-out) CLI error convention already used
+  elsewhere (`src/cli/api.ts`'s `exitCode`), never a bare non-zero without an
+  envelope. `settings` has no fan-out surface, so the constitution's `2`
+  ("partial" fan-out result) never applies here.
+- **Agent-facing:** every subcommand emits the standard envelope
+  (`ok`/`data`/`meta`/`error`) regardless of TTY — `--format json` is
+  honored on `settings` itself exactly like every other command, so an agent
+  never needs a TTY-detection special case to consume it.
+- **`--cdb-file <path>` / `--cdb-password <pw>`** (on `print` only): scope
+  which CDB `print` probes for the `__default__` record summary (see
+  "`__default__` boundary" in the examples). These are **not** settings
+  precedence sources — they don't participate in the `default`/`config`/`env`
+  vocabulary below, because they're not resolving a `CENTRS_*` value at all;
+  they're a one-off read of a different file, reported alongside settings.
+  Absent, they fall back to the normal `CENTRS_CDB_FILE`/`CENTRS_CDB_PASSWORD`
+  resolution (built-in path / env — never `centrs.env`, since `CDB_PASSWORD`
+  is refused there).
 - Credentials collected for `__default__` route through the `devices` write
   layer (the only CDB writer) and are redacted from any structured output.
 
+### `--all`
+
+`print`'s default view lists only the keys `settings` recognizes (the table
+above). `--all` additionally lists every other `CENTRS_*=` line literally
+present in the file — a foreign var a user added for their own shell use, a
+typo of a real key, or (redacted) a refused credential key someone hand-added
+despite `set` refusing to write it — each tagged `(unrecognized)`. This keeps
+the default output focused on what `settings` actually understands while
+still making `print --all` the honest "what's actually in this file" dump for
+debugging.
+
 ## Boundaries
 
 - `settings` edits **global** preferences (`centrs.env`) and the **`__default__`**
   record only. Per-device settings stay in `devices` (CDB comment-kv).
 - It writes no RouterOS device; it is local-only, like `devices`.
 - `--skip-env-file` / `CENTRS_SKIP_ENV_FILE=1` makes a run ignore `centrs.env`
-  (tests, dev-agent usage); `settings` still reports what *would* apply.
+  **for every other command's precedence resolution**. It does not affect
+  `settings` itself: `settings` always reads and writes the real file
+  regardless of this flag, since inspecting/editing the file *is* its job. A
+  `settings print` run under `--skip-env-file` should still show the file's
+  contents, with a one-line note that the flag is active and other commands
+  in this same invocation environment would not see them.
 
 ## Onboarding
 
@@ -55,15 +204,130 @@ creds) and `centrs devices discover` (populate the registry). See
 `commands/discover/README.md` (save-implied `devices discover`) and
 `docs/CONSTITUTION.md` (Default-device record).
 
-## Settings keys
+## Settings keys: file format and write strategy
 
 `centrs.env` holds **canonical `CENTRS_*=value` lines** — identical to the
 environment-variable spellings, prefix included (`CENTRS_FORMAT=json`,
-`CENTRS_DISCOVER_TIMEOUT=15s`, `CENTRS_CONCURRENCY=8`). One vocabulary across
-file / env / CLI: the file *is* "just default env vars," so `set -a && source
-centrs.env` works and the loader applies each key as a default **only when the
-same `CENTRS_*` is not already in the process environment** (it never injects
-into `process.env`). `settings set <attr>` accepts the setting name with or
-without the prefix for convenience but always writes the canonical prefixed
-line. It is **user-global only** — the single XDG path above; there is no
-project-local config file discovered from the working directory.
+`CENTRS_MAX_RESULTS=500`). One vocabulary across file / env / CLI: the file
+*is* "just default env vars," so `set -a && source centrs.env` works and the
+loader applies each key as a default **only when the same `CENTRS_*` is not
+already in the process environment** (it never injects into `process.env`).
+`settings set <attr>` accepts the setting name with or without the prefix, and
+in kebab-case or SCREAMING_SNAKE (`format`, `FORMAT`, `centrs_format`,
+`CENTRS_FORMAT` all resolve to the same key), but always **writes** the
+canonical `CENTRS_FORMAT=` line. It is **user-global only** — the single XDG
+path above; there is no project-local config file discovered from the working
+directory.
+
+**The `config` precedence layer** — `src/resolver/config-file.ts` resolves
+`${XDG_CONFIG_HOME:-~/.config}/tikoci/centrs.env` (injectable `env` map,
+mirroring `defaultCdbPath`) and `loadEnvFileDefaults()` parses it into a flat
+`Record<string, string>`. `resolveStringSetting`/`resolveBooleanSetting`/
+`resolveOptionalIntegerSetting` (`src/resolver/settings.ts`) each take this as
+a `config` argument, checked *between* `comment-kv` and the built-in default,
+producing `{ value, source: { kind: "config", key: "CENTRS_FORMAT" } }` — a
+genuine new layer, not a value folded into the existing `defaultValue`
+parameter (which would have reported it with `source: "default"`, losing
+provenance). Every command that resolves a managed key (`retrieve`, `execute`,
+`api`, `transfer`, `terminal`, plus `resolveCdb`/`expandCdbSelection` for
+`CENTRS_CDB_FILE` and `mcp/config.ts` for `CENTRS_CDB_FILE`/
+`CENTRS_MCP_ALLOW_ADHOC`) threads this `config` argument through, so a value
+set via `centrs settings set` actually takes effect everywhere, not just in
+`settings print`'s own report. `CENTRS_USERNAME`/`CENTRS_PASSWORD`/
+`CENTRS_CDB_PASSWORD` deliberately never read this tier, even if hand-added to
+the file — a stronger defense than read-time redaction alone, since a
+hand-edited credential line then cannot function as a live source. Fan-out
+via-pinning guards (`retrieve`/`execute`/`api`) also deliberately exclude
+`config` — a `centrs.env` default is the weakest precedence tier and must not
+override a per-device comment-kv `via=` across a mixed fan-out.
+
+Write strategy (new; the current file is silent on this):
+
+- **Preserve unrecognized content.** A hand-edited `centrs.env` may carry
+  blank lines, `#` comments, or foreign (non-`CENTRS_*`) lines. `set`/`reset`
+  parse-modify-write, touching only the matched line; everything else
+  round-trips byte-for-byte, mirroring the CDB's "unknown fields preserved
+  verbatim" principle (`commands/devices/README.md`).
+- **`reset <attr>` deletes the line, never blanks it.** A blank
+  `CENTRS_FORMAT=` line is *not* equivalent to "unset" for a file meant to be
+  bash-`source`-able — sourcing it would set the shell variable to an empty
+  string, which most shells and centrs's own `env[KEY] !== undefined` check
+  both treat as "set." Deleting the line entirely is the only way `reset`
+  actually restores the built-in default. (This is the one place `settings`
+  must **not** copy the CDB comment-kv convention, where an empty value
+  removes the token — that convention is safe there because centrs parses
+  comment-kv itself; it would be a correctness bug here.)
+- **`reset` with no `<attr>` removes every managed-key line** this file
+  currently holds, leaving unrecognized lines and all comments/blank lines
+  untouched, and reports `data.cleared: [...]` listing what it removed. No
+  confirmation gate — the blast radius is one local file, not N routers, and
+  every value is recoverable by re-running `settings set`.
+- **Atomic write:** write to a temp file in the same directory, `fsync`, then
+  `rename()` over the original — same pattern as the CDB write layer, scaled
+  down (a single `.bak` copy is enough; this file has no multi-KB record set
+  to protect, and a user can always re-type a couple of lines, but a crash
+  mid-write must never corrupt a file other shells `source`).
+- **First write creates the directory.** `${XDG_CONFIG_HOME:-~/.config}/tikoci/`
+  may not exist yet on a fresh machine; `set` creates it (and the file) rather
+  than erroring.
+
+## Precedence and what `print`/`get` can actually report
+
+The constitution's five-tier precedence (`default < config < comment-kv < env
+< cli`) is a **per-call** resolution — it needs a specific command invocation
+(which CDB record matched, which CLI flags were passed) to produce a `cli` or
+`cdb`/`comment-kv` source. A bare `centrs settings print` has no such call
+context: there is no target, no command, no CLI flags being resolved. So for
+each key, `print`/`get` can only ever report one of three sources —
+`default` (built-in, nothing set), `config` (this file has a line for it —
+the same `SettingSourceKind` every other command's `meta.settings` will use
+once the loader above exists), or `env` (the real process environment
+currently has the var set, which would shadow whatever the file says). It
+should **not** claim `cli` or `comment-kv` sources — those require a call
+`settings` never makes.
+
+For `CENTRS_FORMAT` specifically: because each command defines its own
+built-in default (`api`: `json`; others: `text`) independently
+(`retrieveOutputFormats`/`apiOutputFormats`/`executeOutputFormats`/
+`transferOutputFormats` are four separate `const` arrays that currently all
+happen to agree on the same three values), `print` should show the
+`config`/`env` value if set, and when unset show **all** per-command
+defaults rather than a single misleading "default: text" — e.g. `default:
+text (api: json)`.
+
+## Testability
+
+`settings` is fixture-testable the same way `devices` is: `defaultSettingsPath`
+(`src/resolver/config-file.ts`) takes an injectable
+`env: Record<string, string | undefined>` map and reads `XDG_CONFIG_HOME`
+from it (falling back to `HOME`, then `os.homedir()`) — mirroring
+`defaultCdbPath`'s pattern. `test/integration/settings.test.ts` sets
+`XDG_CONFIG_HOME` to a per-test temp directory (exactly like `$CDB` in the
+`devices` fixtures), so no test ever touches a real user's
+`~/.config/tikoci/centrs.env`.
+
+## Error and warning codes
+
+Per the contributor contract in `docs/errors/README.md`, every code below has
+a catalog entry (`src/core/error-catalog.ts`) and a `docs/errors/<code>.md`
+page:
+
+- `settings/reserved-key` — `set`/`reset` refused a credential or
+  self-referential key (see Scope boundary table).
+- `settings/unknown-key` — `get`/`set` received a token that is not a
+  recognized `CENTRS_*`-shaped name at all — e.g. a typo. (Not needed for
+  reads via `print --all`, which tags-and-shows rather than rejecting.)
+- `settings/consequential-value` — a non-fatal `set` warning (resolves the
+  former open question below) for exactly two keys: `insecure=true` and
+  `transfer-via=ftp`. `meta.warnings`, not an interactive confirm — a confirm
+  prompt in non-TTY mode isn't meaningful and would break scripting.
+- `settings/skip-env-file-active` — a non-fatal `print` warning noting that
+  `--skip-env-file` is active for this invocation only; `settings` itself
+  always reads the real file regardless.
+- `internal/settings-failed` — generic internal-error fallback, left as an
+  unenriched stub matching the sibling `internal/devices-failed`.
+- `settings/invalid-boolean`, `settings/invalid-integer`,
+  `settings/invalid-timeout`, `settings/invalid-via`, `settings/invalid-format`,
+  `settings/unsafe-protocol-blocked` (referenced by the `consequential-value`
+  warning for `transfer-via=ftp`) already existed in the catalog (shared with
+  other commands' resolvers) and apply unchanged here.