@tikoci/centrs 0.1.2 → 0.1.3

package/commands/settings/examples.md

@@ -0,0 +1,408 @@
+# settings — examples
+
+Each numbered example is an executable spec, in the same style as
+`commands/devices/examples.md`. `settings` performs no network IO, so its
+integration tests run against a fixture `centrs.env` rather than a live CHR.
+
+`$SETTINGS_DIR` is a per-test temporary directory passed as `XDG_CONFIG_HOME`
+for the invocation, so the resolved file is `$SETTINGS_DIR/tikoci/centrs.env`
+— there is no checked-in fixture file; each test starts from either an absent
+file or one written in-test. This mirrors `$CDB` in the `devices` fixtures.
+Some examples also reference `$CDB` (a fixture WinBox CDB, built the same way
+as `devices`' fixtures) to exercise the `__default__` boundary between the two
+files.
+
+Every example below is a named test in `test/integration/settings.test.ts`
+("example N: ..."), green via `bun run test:integration:settings`.
+
+## print
+
+### 1. Print with no file present
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print
+```
+
+No `centrs.env` exists yet. `data` lists every settings-managed key with
+`source: { kind: "default", key: <attr> }`. For `format`, since the built-in
+default varies per command, `data.format = { value: null, source: { kind:
+"default", key: "format" }, perCommandDefault: { retrieve: "text", execute:
+"text", transfer: "text", api: "json" } }` instead of a single scalar.
+
+### 2. Print after a value is set
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print
+```
+
+`data.format = { value: "json", source: { kind: "config", key:
+"CENTRS_FORMAT" } }`. No `perCommandDefault` block once an override exists —
+the file's value applies uniformly.
+
+### 3. Print --all surfaces unrecognized lines
+
+The fixture file has a hand-added `# my note` comment and a
+`CENTRS_QUUX=5s` line (not a real key) before any `set` call in this test.
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --all
+```
+
+`data` includes an `unrecognized` array: `[{ key: "CENTRS_QUUX", value:
+"5s" }]`, tagged `(unrecognized)`. Bare `print` (no `--all`) from the same
+fixture omits it entirely — it isn't a key `settings` knows, managed or
+refused.
+
+### 4. Print a single attribute
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print max-results
+```
+
+`data` contains only the `max-results` entry, not the full set.
+
+### 5. Real env overrides the file
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR CENTRS_FORMAT=yaml centrs settings print format
+```
+
+The file (from example 2) holds `CENTRS_FORMAT=json`, but the real process
+environment wins per precedence: `data.format = { value: "yaml", source: {
+kind: "env", key: "CENTRS_FORMAT" } }`.
+
+### 6. Print under --skip-env-file still shows the file
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --skip-env-file
+```
+
+`ok: true`. Values and sources are unchanged from example 2 — `settings`
+itself always reads the real file. `meta.warnings` includes a note that
+`--skip-env-file` is active and other commands run in this same environment
+would not see these values.
+
+## get
+
+### 7. Get a key with no override and a per-command default
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get format
+```
+
+Fresh file. `data.value = null`, `data.source = { kind: "default", key:
+"format" }`, `data.perCommandDefault` populated as in example 1 above. This
+is `get`'s one deliberate exception to "returns one value" — there truly
+isn't one until an override exists.
+
+### 8. Get after set returns the resolved value
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set max-results 250
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get max-results
+```
+
+`data = { value: 250, source: { kind: "config", key: "CENTRS_MAX_RESULTS" } }`.
+
+### 9. Get an unknown key
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get totally-bogus-key
+```
+
+Errors `settings/unknown-key` — the token isn't a recognized `CENTRS_*`-shaped
+name at all (not a typo close enough to suggest, not a plausible env name).
+`details_url` populated.
+
+### 10. Get a credential-shaped key redacts the value
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR CENTRS_CDB_PASSWORD=hunter2 centrs settings get cdb-password
+```
+
+`ok: true` — read-only inspection is allowed even for refused-on-write keys
+(see README Scope boundary). `data = { value: "(redacted)", isSet: true,
+source: { kind: "env", key: "CENTRS_CDB_PASSWORD" } }`. The literal secret
+`hunter2` must not appear anywhere in the envelope, including
+`meta`/`error.context` on any code path — this example exists specifically to
+pin that.
+
+### 11. Get a key that also has a per-device comment-kv form
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set via ssh
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get via
+```
+
+`ok: true`. `data = { value: "ssh", source: { kind: "config", key:
+"CENTRS_VIA" } }` — fully validated and managed like any other key (see
+README: there is no second-class "unmanaged" tier). `tips` (the envelope's
+existing informational channel, not `warnings`) carries a
+`tip/comment-kv-may-override` entry noting that a device's own `via=`
+comment-kv override, if set, takes precedence over this global default —
+since `settings` has no target/device context here, it cannot say whether
+any specific device actually has one.
+
+## set
+
+### 12. Set a known key (happy path)
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+```
+
+`ok: true`. `data = { key: "format", previous: null, value: "json" }`. Reading
+the file directly shows a single `CENTRS_FORMAT=json` line.
+
+### 13. Prefix and case are normalized on input, canonical on write
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set CENTRS_MAX_RESULTS 250
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set max-results 250
+```
+
+Both calls resolve to the same key and produce the identical
+`CENTRS_MAX_RESULTS=250` line — the second call is a no-op mutation (file
+unchanged, `data.previous == data.value == 250`, still `ok: true`).
+
+### 14. Set an invalid value for a typed key
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format xml
+```
+
+Errors `settings/invalid-format` (the shared `{text, json, yaml}` union — see
+README). No file mutation; a failed `set` never partially writes.
+
+### 15. First write creates the directory and file
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR/does-not-exist-yet centrs settings set format text
+```
+
+`ok: true`. `$SETTINGS_DIR/does-not-exist-yet/tikoci/` is created, along with
+`centrs.env` inside it.
+
+### 16. Set preserves unrelated file content
+
+Fixture file (written in-test, not via `settings`) contains:
+
+```env
+# personal note, keep me
+CENTRS_VIA=ssh
+CENTRS_FORMAT=text
+```
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+```
+
+Re-reading the file shows the comment and the `CENTRS_VIA=ssh` line
+byte-for-byte unchanged; only the `CENTRS_FORMAT` line's value changed to
+`json`. (`via` is a fully managed key too — this example is about `set` only
+touching the one line it was asked to touch, not about `via` being
+second-class.)
+
+### 17. Set a refused credential key
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set cdb-password hunter2
+```
+
+Errors `settings/reserved-key`. `remediation` points at `--cdb-password` /
+`CENTRS_CDB_PASSWORD` / `Bun.secret()`. No file mutation — re-reading the
+file (or a fresh `print`) shows no `CENTRS_CDB_PASSWORD` line was written.
+The literal value `hunter2` does not appear anywhere in the error envelope.
+
+### 18. Set a comment-kv-shadowed key is a normal validated write
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set validate false
+```
+
+`ok: true`. `data = { key: "validate", previous: null, value: false }`. No
+warning — `validate` is validated with the same `parseBoolean` rule as any
+other boolean key; the fact that a device's own `validate=` comment-kv can
+override it per-device is normal precedence layering, not a reason to treat
+this write differently from `set format json`.
+
+### 19. Set an unrecognized key name
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set totally-bogus-key value
+```
+
+Errors `settings/unknown-key`, same as `get` (example 9). No file mutation.
+
+### 20. Set a typed integer key out of range
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set max-results 0
+```
+
+Errors `settings/invalid-integer` (positive-integer rule, matching
+`resolveOptionalIntegerSetting`'s existing validation used elsewhere). `-1`
+and non-numeric input (`abc`) behave the same.
+
+### 21. Set an invalid protocol identifier
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set via carrier-pigeon
+```
+
+Errors `settings/invalid-via` — same enum and code `retrieve.ts` already uses
+for `--via`/`CENTRS_VIA` (`rest-api`, `native-api`, `ssh`, `snmp`, `mndp`,
+`mac-telnet`, `romon`, `winbox-terminal`). No file mutation.
+
+### 22. Set an invalid duration
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set timeout not-a-duration
+```
+
+Errors `settings/invalid-timeout` (`parseDuration` rules: bare milliseconds
+or a `ms`/`s`/`m` suffix). No file mutation.
+
+### 23. Boolean values are written in canonical 1/0 form
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set mcp-allow-adhoc true
+```
+
+`ok: true`. Reading the file directly shows `CENTRS_MCP_ALLOW_ADHOC=1`, not
+`=true` — `settings` accepted the `parseBoolean`-recognized spelling `true`
+as input but always writes the canonical `1`/`0` (see README: this is
+required because `src/mcp/config.ts` checks the literal string `"1"`, not the
+shared boolean parser). `settings get mcp-allow-adhoc` afterward returns
+`{ value: true, source: { kind: "config", ... } }` — `get` still returns a
+real boolean, only the on-disk serialization is canonicalized.
+
+### 24. A value that will fail later still gets a warning now
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set transfer-via ftp
+```
+
+`ok: true` — `ftp` is a recognized `CENTRS_TRANSFER_VIA` value syntactically,
+so `set` writes it. `meta.warnings` contains a note that `transfer` will
+currently reject `ftp` at call time unless `ALLOW_UNSAFE_PROTOCOLS` includes
+it (`settings/unsafe-protocol-blocked`, `src/transfer.ts`) — `settings` warns
+rather than silently accepting a value it knows will not work, without
+duplicating `transfer`'s own runtime gate.
+
+### 25. Re-setting the same value is idempotent
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+```
+
+Both calls return `ok: true`; the second reports `data.previous ==
+data.value`. The file has exactly one `CENTRS_FORMAT=` line afterward, not
+two.
+
+## reset
+
+### 26. Reset removes the line, not just its value
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings set format json
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings reset format
+```
+
+`ok: true`. The `CENTRS_FORMAT=` line is **absent** from the file afterward —
+not present with an empty value (see README: an empty value would be
+"set to empty string" for a bash-sourced file, not "unset"). A follow-up
+`settings get format` shows `source: { kind: "default" }` again, matching
+example 7.
+
+### 27. Reset on a key that was never set is a no-op success
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings reset max-results
+```
+
+Fresh file, `CENTRS_MAX_RESULTS` never written. `ok: true`,
+`data.wasSet: false` — resetting nothing is not an error.
+
+### 28. Reset with no attribute clears every managed key, leaves the rest
+
+Fixture file:
+
+```env
+# keep me
+SOME_OTHER_VAR=untouched
+CENTRS_FORMAT=json
+CENTRS_MAX_RESULTS=250
+CENTRS_VIA=ssh
+```
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings reset
+```
+
+`ok: true`. `data.cleared = ["format", "max-results", "via"]` — all three
+recognized keys, `via` included, since it's fully managed like the others.
+Re-reading the file shows the comment and `SOME_OTHER_VAR=untouched`
+unchanged; the three managed lines are gone. No confirmation was required
+(see README: local-file blast radius, always recoverable via `set`).
+
+### 29. Reset also refuses credential keys
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings reset cdb-password
+```
+
+Errors `settings/reserved-key`, same family as `set` (example 17) — `reset`
+is a mutating verb and refuses the same key list.
+
+## Interactive / non-TTY
+
+### 30. Bare `settings` under non-TTY behaves like `print`
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings </dev/null
+```
+
+`ok: true`, identical shape to `settings print` (example 1/2 depending on
+fixture state). No prompt is emitted and the call does not hang.
+
+The interactive TTY flow (clack-style prompts collecting `__default__`
+credentials and confirming preferences) is explicitly deferred — see the
+README's "later slice" note and its `@clack/prompts` dependency prerequisite.
+It has no example here because a genuine TTY session isn't exercisable in the
+fixture-backed integration tier (the same reason `devices` has no interactive
+example either, only the `</dev/null` disambiguation case). When that slice
+ships, its examples land as a new numbered range appended here, not inserted
+into the middle of this list.
+
+## `__default__` boundary
+
+### 31. Print reports `__default__` presence without leaking secrets
+
+Fixture CDB `$CDB` has a `__default__` record with `user=admin` and a
+password set.
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --cdb-file $CDB
+```
+
+`ok: true`. `data.defaultDevice = { configured: true, user: "admin",
+passwordSet: true }` — the password value itself never appears. This is the
+one place `settings print` reaches into the CDB rather than `centrs.env`;
+`--cdb-file` here is a probe-only flag (see README Surface), not a settings
+precedence source. It's read-only (no CDB mutation), matching the README's
+"the `__default__` record only" boundary.
+
+### 32. Print with no `__default__` record
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --cdb-file /tmp/does-not-exist.cdb
+```
+
+`ok: true` (a missing/absent CDB is not an error for `settings`, unlike
+`devices list` in devices' example 3 — `settings` degrades to "no default
+device configured" rather than `cdb/not-found`, since reporting settings
+should not require a CDB to exist at all). `data.defaultDevice = {
+configured: false }`.

package/commands/terminal/README.md

@@ -2,6 +2,12 @@
 
 Open an interactive RouterOS console.
 
+`terminal` is **single-session**: it is not a fan-out surface. A target-selection
+flag (`--group` / `--where` / `--all` / `--default` / `--concurrency`) is rejected
+with `usage/fanout-not-supported` — open a console to one router at a time; use
+`execute` / `api` for multi-target commands. See `docs/CONSTITUTION.md`
+(Target selection grammar).
+
 Status: `terminal / mac-telnet` **and** `terminal / ssh` are both **`CHR-passed`**
 (see `docs/MATRIX.md` and `examples.md` T1–T3 / TS1–TS2). The two transports take
 different paths: **mac-telnet** is the in-process raw passthrough over

package/commands/transfer/README.md

@@ -17,6 +17,7 @@ sftp-seeded >60 KB file) — confirming the `/file`
 RouterOS. Unit coverage is `test/unit/transfer.test.ts`. **sftp** is the first SSH
 consumer — a self-contained SFTP transfer client over the host OpenSSH `sftp`
 subsystem. `scp` and `fetch` are **designed but deferred** past this pass.
+Multi-target fan-out is built (see **Target selection**, examples F1–F5).
 
 ## Intent
 
@@ -160,7 +161,8 @@ is an explicit `--via scp` escape hatch. The reason is capability, not taste:
 | `--verify <size\|checksum\|off>` | Post-transfer integrity check. Default `size` (compare the byte count centrs sent/received against the settled `/file` size). `off` (alias `--no-verify`) skips it. See *Integrity*. |
 | `--type <file\|directory\|disk\|package>` | `list` only: filter by `/file` row type. |
 | `--name <glob>` | `list` only: filter by file name glob. |
-| `--out-dir <dir>` | `download` fanout only *(deferred — fanout not built yet)*: write one file per target into `<dir>` (named by CDB target), since N devices cannot share one local path. |
+| `--out-dir <dir>` | `download` fan-out only: write one file per target into `<dir>` (named by CDB identity, collision-safe, keeping the remote extension), since N devices cannot share one local path. **Required** for a `download` across a selection. See **Target selection**. |
+| `--yes` | Confirm a mutating fan-out (`upload`/`remove`/`mkdir`/`copy`) across multiple routers in non-interactive runs (confirmed once up front). See **Target selection**. |
 | `--advertise-host <host>` / `--advertise-port <n>` / `--bind <addr>` | `fetch` only *(deferred)*: the host/IP/port centrs advertises in the fetch URL and the local bind address. Default: auto-detect the local IP on the route to the router; ephemeral port; single-use random URL token. |
 | `--resolve <none\|arp>` | *(deferred — not parsed yet)* Resolve a MAC-address target to an IP via the host ARP cache. Default `none`. |
 | `--format text` (default) | Human summary: method, bytes, duration, verified. Errors print `[code] summary` + `Fix:` lines. |
@@ -172,7 +174,35 @@ is an explicit `--via scp` escape hatch. The reason is capability, not taste:
 | `--ssh-key <path>` | `sftp` (and future `scp`): explicit private-key path. Same `sshKey` setting as `terminal`/`execute` (`CENTRS_SSH_KEY`, CDB `ssh-key=`). When unset, the ssh-agent / `~/.ssh/config` is used. See `commands/terminal/README.md`. |
 | `--insecure` | Accept a self-signed TLS cert (`https`/`api-ssl`) or a new SSH host key (TOFU). Default verifies; see constitution: transport trust. Adds a `transport/insecure-trust` warning. |
 | `--cdb-file` / `--cdb-password` | Override CDB file location / decrypt password. |
-| `--group <name>` / `--where <attr>=<value>` / `--all` / `--default` / `--concurrency <n>` | *(deferred — fanout not built for `transfer` yet)* Fan out across CDB targets (e.g. push one firmware file to a fleet). Same selector grammar and per-target envelope as `retrieve` (constitution: target selection). `download` fanout requires `--out-dir`; `remove`/`mkdir`/`copy`/`upload` fan out directly. |
+| `--group <name>` / `--where <attr>=<value>` / `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>` / `--all` / `--default` / `--concurrency <n>` | Fan out across CDB targets (e.g. push one firmware file to a fleet). Same selector grammar and per-target envelope as `retrieve`/`execute` (constitution: target selection). `--near`/`--bbox` select by device GPS (lat-first). `download` fan-out requires `--out-dir`; `remove`/`mkdir`/`copy`/`upload` fan out directly and are `--yes`-gated. See **Target selection**. |
+
+## Target selection
+
+`transfer` runs the **same** verb across a multi-target selection over the shared
+grammar (multiple `<router>` positionals, repeatable `--group`/`--where`, the geo
+selectors `--near`/`--bbox`, `--all`, `--default`). The grammar, the locked
+`FanoutData` envelope, the record-order
+reassembly, and the granular **0/2/1 exit code** are normative in
+[`docs/CONSTITUTION.md` → Target selection grammar](../../docs/CONSTITUTION.md#target-selection-grammar).
+
+The positional **boundary is the verb keyword** (`upload`/`download`/`list`/
+`remove`/`mkdir`/`copy` or an alias): positionals **before** it are fan-out
+targets, the verb and its paths follow (`transfer r1 r2 download /flash/log.txt
+--out-dir ./logs`). A single positional target with no selector stays
+single-target. On the top-level `upload`/`download` alias the verb is fixed, so
+its positionals are paths — positional fan-out targets are not expressible there;
+fan-out comes from a selector flag.
+
+Two transfer-specific rules:
+
+- **`download` fan-out requires `--out-dir <dir>`.** N devices cannot share one
+  local path, so each target's file is written into the directory, named by its
+  CDB identity (collision-safe — same-label targets are disambiguated by record
+  index — and keeping the remote file's extension). Each inner envelope records
+  its per-target local path.
+- **`upload`/`remove`/`mkdir`/`copy` are device writes**, so a fan-out of them is
+  gated by **`--yes`**, confirmed once up front; without it the error names the
+  blast radius (how many routers). `download`/`list` only read the device.
 
 ## Integrity
 

package/commands/transfer/examples.md

@@ -336,6 +336,72 @@ centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $U --ssh-key $K
 Both `ok: true`. On-device `copy` has no SFTP primitive — `--via sftp copy` returns
 `transport/unsupported-operation` (it stays on rest/native).
 
+## Target selection (fan-out)
+
+These exercise the shared target-selection grammar
+([`docs/CONSTITUTION.md` → Target selection grammar](../../docs/CONSTITUTION.md#target-selection-grammar)),
+run by `test/integration/transfer-fanout.test.ts`. `$CDB` has two records in group
+`fanout-chr`: record 0 is the live CHR (comment fact `role=edge`, seeded with
+`fanout-test.txt`) and record 1 is an unreachable REST URL (`role=core`). Note the
+**verb-keyword boundary**: targets/selectors precede the verb.
+
+### F1. Group fan-out of a read verb (`list`)
+
+```bash
+centrs transfer --group fanout-chr list --via rest --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`, targets ordered by
+`recordIndex`, `meta.operation.kind = fanout`; the unreachable target is an inner
+`ok: false`. Exit `2`.
+
+### F2. Empty / unknown group
+
+```bash
+centrs transfer --group no-such-group list --via rest --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`,
+`warnings` include `cdb/empty-group`. Exit `0`.
+
+### F3. `--where` device-class selector (subset)
+
+```bash
+centrs transfer --where role=edge list --via rest --cdb-file $CDB --json
+```
+
+Selects only record 0: `data.summary = { total: 1, ok: 1, failed: 0 }`,
+`meta.operation.selection.where = ["role=edge"]`, exit `0`.
+
+### F4. `download` fan-out into `--out-dir`
+
+```bash
+centrs transfer --group fanout-chr download fanout-test.txt --out-dir ./downloads --via rest --cdb-file $CDB --json
+```
+
+Each reachable target writes one file into `./downloads`, named by its CDB identity
+(collision-safe, keeping the remote extension). `data.summary = { total: 2, ok: 1,
+failed: 1 }`, exit `2`; the ok target's inner `data.local` is the written path.
+
+### F5. Mutating fan-out (`remove`) without `--yes` is refused
+
+```bash
+centrs transfer --group fanout-chr remove fanout-test.txt --via rest --cdb-file $CDB --json
+```
+
+A mutating fan-out is gated once up front: `ok: false`,
+`error.code = usage/confirmation-required`, the summary names the blast radius
+(`2 router(s)`), exit `1`. Nothing is removed. Add `--yes` to fan the write out.
+
+### F6. `download` fan-out without `--out-dir` is refused
+
+```bash
+centrs transfer --group fanout-chr download fanout-test.txt --via rest --cdb-file $CDB --json
+```
+
+N devices cannot share one local path: `ok: false`,
+`error.code = usage/conflicting-flags`, exit `1`. Pass `--out-dir <dir>`.
+
 ## Pending transports (contract defined; flips when the transport lands)
 
 ### P2. `--via scp` (follow-on pass after sftp)

package/docs/CONSTITUTION.md

@@ -221,19 +221,40 @@ must round-trip through the same envelope.
 
 One grammar across every non-terminal command. A call selects targets from any
 mix of: `<router>` positionals (one or more), repeatable `--group <name>`,
-`--all` (every CDB record), `--default` (the `__default__` record), and
-repeatable `--where <attr>=<value>` — a **device-class** selector that matches
-CDB-stored facts/comment-kv (e.g. `--where board=RB5009`), AND-combined across
-repeats. The union is **de-duped by CDB record index** and run through the same
-per-target pipeline; the `data` array is reassembled in resolved record order,
-not completion order, so repeated runs diff cleanly. Destructive multi-target
-operations (e.g. `devices remove` across a group) require `--force`. `terminal`
-and a single-session `api --stream` follow are not fan-out surfaces and reject
-N>1 with `usage/fanout-not-supported`.
+`--all` (every CDB record, **excluding** the reserved `__default__` record),
+`--default` (the `__default__` record), and repeatable `--where <attr>=<value>` —
+a **device-class** selector that matches CDB-stored facts/comment-kv **plus core
+record fields** (`target`/`identity`/`group`/`mac`; core fields win so a comment
+token cannot spoof them), AND-combined across repeats. A call is in **fan-out
+mode** when any selector flag is present **or** more than one positional target is
+given; a plain single-positional call stays single-target. The union is
+**de-duped by CDB record index** (ad-hoc literal targets by host) and run through
+the same per-target pipeline.
+
+Fan-out output is the locked **`FanoutData`** envelope: `data = { summary, targets[]
+}`, where the outer `ok` reports **orchestration** success and a per-target failure
+is an inner `ok:false` envelope (output, not metadata). `targets[]` is reassembled
+in resolved record order, not completion order, so repeated runs diff cleanly. The
+**process exit code** is granular and uniform across fan-out commands: `0` every
+target ok (or an empty selection), `2` partial (some ok, some failed), `1`
+orchestration error or every target failed.
+
+A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across a
+selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing
+the error names the blast radius (how many routers). The separate **`--force`**
+gate is scoped to destructive **`devices` CDB mutations** (e.g. `devices remove`
+across a group), not RouterOS writes. `terminal` and single-session `stream` /
+`api --stream` are not fan-out surfaces and reject N>1 with
+`usage/fanout-not-supported`; `api --raw` is rejected in fan-out mode with
+`usage/conflicting-flags` (it strips the per-target envelope).
 
 `--where` filters *which devices* by CDB-stored facts; keep it distinct from
 `retrieve`/`execute`'s `--query`/`--filter`, which filter *RouterOS rows* in the
-response. Two layers, two flag families.
+response. Two layers, two flag families. `--near <lat>,<lon>,<radius>` and
+`--bbox <south>,<west>,<north>,<east>` are geo union predicates over device GPS
+(**lat-first, decimal degrees**; radius units `m`/`km`/`mi`/`ft`, bare = km);
+geo-less devices never match. They join the same union — a device matches when it
+falls in `--near`'s radius **or** `--bbox`.
 
 `--group` is purely a **selector** in this grammar; the group *field* is written
 by a distinct `--new-group` flag on `devices add`/`set`, so record selection and
@@ -281,7 +302,11 @@ Rules:
 - **Never silently downgrade across `--via`.** If the caller pinned a transport
   that cannot do the operation, error out with a `transport/*` code.
   Auto-selection (no `--via`) may downgrade *within* the table, but every hop is
-  reported in `meta.warnings` with its reason.
+  reported in `meta.warnings` with its reason. For `api`'s fan-out path, this
+  and "Validation is the product" above are also checked structurally by
+  CodeQL (`.github/codeql-house-rules/missing-required-gate.ql` —
+  `apiFanout` must call `assertApiProtocolSupported`/`validateApiRequestShape`;
+  scoped to `apiFanout` only today).
 - **Execute vs retrieve surfaces:** native-api, rest-api, ssh, mac-telnet (and
   later RoMON / WinBox Terminal) are execute surfaces; SNMP is **retrieve-only**.
   mac-telnet is the default execute path for an unresolved-MAC target — IP-level