@tikoci/centrs 0.1.1 → 0.1.3

package/commands/check/examples.md

@@ -0,0 +1,390 @@
+# check — examples
+
+Each numbered example is an executable spec. Once `check` is implemented, the
+integration test under `test/integration/check.test.ts` will run the CHR-backed
+examples against a CHR booted by `@tikoci/quickchr`, and the offline examples
+(flag parsing, `--list-checks`, fixture-backed `--save`) will run under
+`test/unit/check.test.ts` — one assertion per example (example N ↔ assertion N).
+Until then these are the **target**: if a line here is not exercised by a test
+when the code lands, the test file is wrong; if a line passes only with
+`--validate=false`, the **implementation** is wrong (see `docs/CONSTITUTION.md`).
+
+These examples are the **target** for `CHR-passed`; the cells are `designed`
+today, so nothing here is green yet.
+
+`$R` is `<host>:<rest-port>` resolved by quickchr. `$U` / `$P` are CHR
+credentials from the harness. Envelope-asserting examples pass `--json`.
+
+## Smart battery (default)
+
+### 1. Bare check runs the smart battery
+
+```bash
+centrs check $R --username $U --password $P --json
+```
+
+Envelope: `ok: true` (a healthy CHR raises warnings/tips at most, not errors),
+`data.checks[]` includes at least `reach`, `services`, `resource`, `cloud`,
+`dns`; each entry has `ran: true` and a `metadata` object. `data.profile`
+carries `board`, `arch`, `version`, `channel`. `meta.via` is the transport the
+battery rode.
+
+### 2. Profile block is populated
+
+```bash
+centrs check $R --username $U --password $P --json
+```
+
+Assert `data.profile.ports` maps `rest-api`/`native-api` to the live
+`/ip/service` ports, and `data.profile.reachable` lists the transports that
+answered. (Shape is additive/non-normative — assert presence, not an exact key
+set.)
+
+### 3. No credentials → reach only, tip for the rest
+
+```bash
+centrs check $R --json
+```
+
+Envelope: `ok: true`; `data.checks[]` has `reach` (`ran: true`) while the health
+checks report `ran: false` with `skipReason` naming missing credentials, and a
+`tip/reach/credentials-needed` is present.
+
+## Selection and presets
+
+### 4. `--preset reach` is the fast slice
+
+```bash
+centrs check $R --username $U --password $P --preset reach --json
+```
+
+Only the `reach` check ran; no health-phase reads were issued. (This is the slice
+`discover`'s IP-scan iterates.)
+
+### 5. `--checks` runs an explicit subset (+ dependencies)
+
+```bash
+centrs check $R --username $U --password $P --checks services,resource --json
+```
+
+`data.checks[]` contains exactly `services` and `resource` (and any `dependsOn`),
+nothing else.
+
+### 6. `--skip` subtracts from the default
+
+```bash
+centrs check $R --username $U --password $P --skip dns --json
+```
+
+The default battery ran except `dns` (absent from `data.checks[]`).
+
+### 7. `--list-checks` explains the catalog (offline)
+
+```bash
+centrs check --list-checks --json
+```
+
+No network IO. `data` lists every registered check with `id`, `title`,
+`description`, `tags`, `phase`, `default`. Exit `0`.
+
+## Findings and reaching green
+
+### 8. A risky service raises a warning
+
+Precondition: telnet is enabled on the CHR (stock CHR 7.23.1 has it enabled;
+if the fixture hardened services first, run `/ip/service enable telnet`).
+
+```bash
+centrs check $R --username $U --password $P --checks services --json
+```
+
+`data.checks[].findings` includes a `check/services/telnet-enabled` warning with
+a `fix`. Top-level `warnings[]` carries the same code (roll-up).
+
+### 9. `--ignore` suppresses a known finding back to green
+
+```bash
+centrs check $R --username $U --password $P --checks services \
+  --ignore check/services/telnet-enabled --json
+```
+
+The warning no longer appears in `findings[]` or `warnings[]`; `ok: true`.
+
+### 10. `--fail-on warning` gates the exit code, not `ok`
+
+```bash
+centrs check $R --username $U --password $P --checks services --fail-on warning --json
+```
+
+With telnet enabled: the run stays **`ok: true`** with the full `data` present and
+`data.verdict = "warn"`, but the process **exit code is `2`** (reachable, over the
+chosen bar). Re-running with `--ignore check/services/telnet-enabled` gives
+`data.verdict = "pass"` and exit `0`. (At the default `--fail-on error` the same
+warning is a footnote — exit `0` — see example 19.)
+
+## Capability pre-flight and transport
+
+### 11. An unsupported path is skipped, not errored
+
+Simulated against a device/version where a check's `requires` path is absent
+(fixture or older CHR).
+
+```bash
+centrs check $R --username $U --password $P --checks routerboard --json
+```
+
+On CHR (no RouterBOARD) `routerboard` reports `ran: false`,
+`skipReason` referencing capability/CHR — `ok` stays `true`, no raw protocol
+error surfaces.
+
+### 12. `--via` pins the transport with no silent downgrade
+
+```bash
+centrs check $R --username $U --password $P --via native-api --json
+```
+
+`meta.via = native-api`; the battery rode native-api. A pin to a transport that
+cannot serve the battery errors with a `transport/*` code (constitution: never
+silently downgrade across `--via`).
+
+### 13. A slow check is bounded by `--check-timeout`
+
+```bash
+centrs check $R --username $U --password $P --checks traffic --check-timeout 2s --json
+```
+
+`traffic` (a ~10 s probe) is cut at 2 s: its entry carries a
+`check/traffic/timed-out` finding and the run still returns rather than hanging.
+
+## Custom check script
+
+### 14. Custom scripts merge as synthetic checks (repeatable, `--yes`-gated)
+
+Two policy scripts, one inline and one from a fixture the test will add (the path
+shown is its planned location), both required to `:put` an
+`{errors,warnings,tips,metadata}` JSON envelope. An unset channel is
+`[:toarray ""]`, which RouterOS serializes as an empty array `[]` (not `[""]`) —
+grounded on CHR 7.24rc1, where three `[:toarray ""]`-initialized channels
+serialized as `[]`:
+
+```bash
+centrs check $R --username $U --password $P --yes --json \
+  --check-script '{:put [:serialize to=json {"errors"=[:toarray ""];"warnings"=[:toarray ""];"tips"=[:toarray ""];"metadata"={"ipv6-disabled"=[/ipv6/settings/get disable-ipv6]}}]}' \
+  --check-script-file test/integration/fixtures/check/policy.rsc
+```
+
+Each merges under its own `check/custom/<n>`. Without `--yes` the run errors
+`usage/confirmation-required` (a custom script is a trusted, possibly-mutating
+path); with it, the envelope carries a `check/custom-script/ran` audit
+warning. A policy `error` in a script sets `data.verdict = "fail"` → exit `2` at
+the default `--fail-on` (the run itself is `ok: true`; the battery is present).
+
+## `--save` (CDB reconcile, fixture-backed)
+
+### 15. `--save` writes the port + derived facts to the CDB
+
+Fixture CDB with a record for `$R` lacking `port=`/derived facts.
+
+```bash
+centrs check $R --username $U --password $P --save --yes --json
+```
+
+The record gains `port=` for the resolved transport (where non-default),
+`board`/`version`/`software-id`, and an `updated=` stamp, through the `devices`
+write layer. RouterOS is unchanged, and the SNMP community is **not** persisted.
+Without `--save`, an identical run writes nothing to the CDB.
+
+## Fan-out
+
+### 16. Fan-out across a group
+
+Fixture CDB group `lab` with two reachable CHRs.
+
+```bash
+centrs check --group lab --json
+```
+
+Locked `FanoutData` envelope (`data = { summary, targets[] }`); `targets[]` in
+record order; exit `0` all-ok, `2` partial, `1` all-failed. A `--save --group lab`
+without `--yes` errors, naming the blast radius.
+
+## Reach signals and redaction
+
+### 17. Reach reports latency and ARP presence
+
+```bash
+centrs check $R --username $U --password $P --preset reach --json
+```
+
+`data.profile` carries a host→router connect latency (RTT, ms) and an ARP-presence
+fact for the target; `data.checks[].reach.metadata` lists the transports that
+answered. No health-phase reads were issued.
+
+### 18. Secrets are redacted from metadata
+
+Precondition: an enabled SNMP community and `/ip/cloud` Back-To-Home on the CHR.
+
+```bash
+centrs check $R --username $U --password $P --checks snmp,cloud --json
+```
+
+`snmp` metadata reports version/scope/count but **omits the community string**;
+`cloud` metadata keeps `dns-name`/`status` but **omits** `vpn-wireguard-client-config`
+and the VPN keys. A full-envelope grep for the community string / WireGuard config
+finds nothing.
+
+## Presets, selection, and progressive control
+
+### 19. Warnings do not fail the run at the default `--fail-on`
+
+Precondition: telnet enabled (as example 8).
+
+```bash
+centrs check $R --username $U --password $P --json
+```
+
+A `services` warning is present, yet exit `0`: at the default `--fail-on error`,
+`data.verdict = "warn"` is a footnote, not a failure. (Contrast example 10, which
+raises the bar to `warning`.)
+
+### 20. `--preset exposure` is a findings rollup, not extra reads
+
+```bash
+centrs check $R --username $U --password $P --preset exposure --json
+```
+
+`data.checks[]` contains only `services`, `certificates`, `snmp` (the preset
+forces its members, including the normally-triggered `certificates`); no other
+check ran and no path outside those three was read.
+
+### 21. `--preset full` runs the opt-off checks
+
+```bash
+centrs check $R --username $U --password $P --preset full --json
+```
+
+`data.checks[]` additionally includes the `default: off` rows — `health`,
+`packages`, `console`, `traffic`, `connections` — each `ran: true`.
+
+### 22. `--deep` forces triggered checks even when their predicate is quiet
+
+```bash
+centrs check $R --username $U --password $P --deep --json
+```
+
+On an idle CHR (CPU low, `www-ssl` fine) `cpu-detail` and `certificates` still
+ran (`ran: true`), where a bare run leaves them untriggered.
+
+### 23. `--fast` suppresses progressive triggers
+
+```bash
+centrs check $R --username $U --password $P --fast --json
+```
+
+No `trig` check appears in `data.checks[]` regardless of what the default battery
+flagged; only cheap default checks ran.
+
+### 24. `--tag` filters to tagged checks
+
+```bash
+centrs check $R --username $U --password $P --tag hardware --json
+```
+
+Only on-by-default checks carrying the `hardware` tag ran (e.g. `resource`,
+`routerboard`); untagged checks are absent. (The tag taxonomy is provisional —
+see README.)
+
+## Suppression
+
+### 25. `--ignore <checkId>` mutes findings but keeps metadata; `--skip` drops the check
+
+```bash
+centrs check $R --username $U --password $P --checks services --ignore services --json
+```
+
+`services` still appears in `data.checks[]` with `metadata` populated, but its
+`findings[]` is empty and nothing rolls up to top-level `warnings[]`. By contrast
+`--skip services` removes the check entirely (no entry, no metadata).
+
+### 26. `CENTRS_CHECK_IGNORE` suppresses via env (precedence)
+
+```bash
+CENTRS_CHECK_IGNORE=check/services/telnet-enabled \
+  centrs check $R --username $U --password $P --checks services --json
+```
+
+Same effect as passing `--ignore check/services/telnet-enabled`; the winning
+suppression source is reported in `meta.settings`. A `--ignore` arg for a
+different code composes on top (both suppressed).
+
+### 27. `--fail-on never` never fails the run
+
+Precondition: a custom script that emits an `error` finding (as in example 14).
+
+```bash
+centrs check $R --username $U --password $P --yes --fail-on never --json \
+  --check-script '{:put [:serialize to=json {"errors"=[:toarray "policy breach"];"warnings"=[:toarray ""];"tips"=[:toarray ""];"metadata"={}}]}'
+```
+
+`data.verdict = "fail"` but exit `0`; the error finding is still reported. This is
+the pure-data-collection mode #149's IP-scan uses.
+
+### 28. Unknown check name → did-you-mean (offline)
+
+<!-- cspell:ignore servces -->
+
+```bash
+centrs check $R --checks servces --username $U --password $P
+```
+
+A `usage/*` error names `servces` as unknown and lists the closest catalog ids
+(`services`) — the shared did-you-mean behavior (constitution / commands help).
+Exit non-zero, no network IO.
+
+## Fan-out and the write gate
+
+### 29. Fan-out reports partial success with exit 2
+
+Fixture CDB group `lab`: one reachable CHR, one unreachable host.
+
+```bash
+centrs check --group lab --json
+```
+
+`FanoutData`: the reachable target's inner envelope is `ok: true`, the unreachable
+one `ok: false` (`transport/*`); outer orchestration `ok: true`, process exit `2`.
+
+### 30. `--save` fan-out requires `--yes`
+
+```bash
+centrs check --group lab --save --json
+```
+
+Without `--yes` it errors before writing, naming the blast radius (how many CDB
+records would change); adding `--yes` reconciles each target's record.
+
+## L2 and MNDP (CHR L2 bridge)
+
+### 31. A bare-MAC target runs the battery over mac-telnet
+
+CHR-gated: needs the `socket-connect` L2 bridge (see `commands/discover/README.md`).
+`$MAC` is the CHR's ether MAC.
+
+```bash
+centrs check $MAC --username $U --password $P --json
+```
+
+With no IP path, the battery rode mac-telnet (`meta.via = mac-telnet`) as one
+consolidated script (Execution model); the health checks are `ran: true`.
+
+### 32. MNDP enrichment survives an auth failure
+
+CHR-gated (L2 bridge). Precondition: wrong password.
+
+```bash
+centrs check $R --username $U --password wrong --json
+```
+
+`reach` still returns `ran: true` and `data.profile` carries MNDP-advertised
+`identity`/`version`/`platform`/`board`; the health checks are `ran: false` (auth
+failed). An auth error finding is surfaced, but the free MNDP facts are not lost.

package/commands/devices/README.md

@@ -89,22 +89,29 @@ when it actually selected between candidates.
 ## Comment kv-soup (per-device overrides)
 
 The CDB `comment` field is free text. centrs additionally parses tokens
-shaped like `key=value` out of it. Recognized keys (allowlist) fall in two
+shaped like `key=value` out of it. Recognized keys (allowlist) fall in three
 groups: **lookup keys** affect how `<router>` resolves (see "Identity model");
-**override keys** are per-device defaults for centrs settings.
-
-| Key        | Group    | Effect                                                                  |
-| ---------- | -------- | ---------------------------------------------------------------------- |
-| `identity` | lookup   | Device `/system/identity`; a resolvable handle. May repeat across records. |
-| `mac`      | lookup   | A MAC, when `target` is not the MAC.                                    |
-| `ip`       | lookup   | An IP, when `target` is not the IP.                                     |
-| `via`      | override | Default transport for this device (`rest-api`, `native-api`, `ssh`, …). |
-| `validate` | override | `true` / `false`. `false` is the escape hatch; CLI overrides.           |
-| `timeout`  | override | Default request timeout in ms. Per-transport caps still apply.          |
-| `port`     | override | Non-default transport port. Omitted when equal to the protocol default. |
-| `ssh-key`  | override | Per-device private key file path for SSH transports.                    |
-| `source`   | override | Provenance marker for discovered/imported records (`mndp`, `dude`, …).  |
-| `mcp`      | override | MCP write policy for this device: `ro` (default) or `rw`. See `commands/mcp/`. |
+**override keys** are per-device defaults for centrs settings; **geo keys**
+(issue #146) are facts, not settings — queryable via `--where` and returned in
+the `location` block (see "Location / GPS" below), but never coerced into
+resolver settings.
+
+| Key             | Group    | Effect                                                                  |
+| --------------- | -------- | ---------------------------------------------------------------------- |
+| `identity`      | lookup   | Device `/system/identity`; a resolvable handle. May repeat across records. |
+| `mac`           | lookup   | A MAC, when `target` is not the MAC.                                    |
+| `ip`            | lookup   | An IP, when `target` is not the IP.                                     |
+| `via`           | override | Default transport for this device (`rest-api`, `native-api`, `ssh`, …). |
+| `validate`      | override | `true` / `false`. `false` is the escape hatch; CLI overrides.           |
+| `timeout`       | override | Default request timeout in ms. Per-transport caps still apply.          |
+| `port`          | override | Non-default transport port. Omitted when equal to the protocol default. |
+| `ssh-key`       | override | Per-device private key file path for SSH transports.                    |
+| `source`        | override | Provenance marker for discovered/imported records (`mndp`, `dude`, …).  |
+| `mcp`           | override | MCP write policy for this device: `ro` (default) or `rw`. See `commands/mcp/`. |
+| `lat`           | geo      | Latitude, decimal degrees (`-90..90`). See "Location / GPS".            |
+| `lon`           | geo      | Longitude, decimal degrees (`-180..180`). Paired with `lat`.             |
+| `altitude`      | geo      | Meters, may be negative. Metadata-only (not a fan-out query predicate). |
+| `altitude-type` | geo      | `MSL`\|`AGL` (default `MSL`). Normalized to upper case for storage.     |
 
 Rules:
 
@@ -128,9 +135,9 @@ Rules:
   is no current need to store a literally-empty value; revisit if one arises.
 - `commentMirror` is kept in sync with `comment` on every write.
 
-Precedence (lowest → highest): built-in defaults → project config →
-comment-kv → env (`CENTRS_*`) → CLI flag / API arg. `meta.settings` reports
-the winner and source per setting.
+Precedence (lowest → highest): built-in defaults → user config file
+(`centrs.env`) → comment-kv → env (`CENTRS_*`) → CLI flag / API arg.
+`meta.settings` reports the winner and source per setting.
 
 ### Derived facts (queryable, may be stale)
 
@@ -147,7 +154,126 @@ a device); `license-id` is convenience metadata to match by hand against
 MikroTik's CHR licensing page. The `--where` selector plus this derived-fact
 allowlist are the planned home for "operate on a class of devices," distinct from
 `group`. (Promoting these keys to the comment-kv allowlist is a tracked code
-follow-up.)
+follow-up; `lat`/`lon`/`altitude`/`altitude-type` — see "Location / GPS" below —
+are the first keys promoted this way, issue #146.)
+
+## Location / GPS
+
+Per-device GPS (issue #146) is a **fact, not a setting**: recognized
+(`devices set lat=…` no longer warns `cdb/unknown-option`), stored, queryable via
+`--where` (exact) and `--near`/`--bbox` (geo), and returned as a `location` block
+in `devices show`/`list` output — but never coerced into resolver settings. This
+section covers storage/flags/validation/envelope; the geo query predicates are in
+"Geo query" below.
+
+### Storage keys
+
+See the comment-kv table above for `lat`/`lon`/`altitude`/`altitude-type`.
+Values are stored **verbatim as typed** (validated, not reformatted), so an
+exact `--where lat=<value>` still matches what was written — `altitude-type` is
+the one exception, since it's a closed two-value enum, so it is normalized to
+upper case (`msl` -> `MSL`) before storage. `lat`/`lon` must be written as a
+pair: setting one without the other, when the other is not already on the
+record, errors `input/incomplete-gps`. Only the pairing rule fires per-write —
+an unrelated `set timeout=…` on a record that already carries a lone `lat` is
+left untouched.
+
+`lat`/`lon`/`altitude` accept **strict decimal** only (optional leading `-`,
+digits, optional dotted fraction); hex (`0x10`), scientific (`1e2`), and values
+that overflow to `Infinity` are rejected with `input/invalid-coordinate` /
+`input/invalid-altitude` even though `Number()` would accept them, because the
+fields are decimal degrees / meters.
+
+GPS validation (range, strict-decimal, pairing, `altitude-type` enum) applies to
+the **setter flags** (`--lat`/`--lon`/`--altitude`/`--gps`) and to **bare `k=v`
+update tokens** (`lat=…`, `lon=…`). It does **not** re-parse arbitrary base
+`--comment` text: `devices add <t> --comment "lat=91"` is a freeform escape hatch
+that stores the comment as-is (such a value simply won't resolve to a `location`
+on read). Use the flags or `k=v` tokens when you want validated GPS.
+
+### Flags
+
+`devices add`/`set` accept:
+
+- `--lat <deg>` (alias `--latitude`)
+- `--lon <deg>` (aliases `--lng`, `--longitude`, `--long`)
+- `--altitude <meters>` (aliases `--alt`, `--ele`, `--elevation`) — `altitude`
+  stays the canonical field (the ISO 6709 / EPSG / IETF `geo:` / W3C-Geolocation
+  term); `ele`/`elevation` are GPX-muscle-memory aliases, not a rename
+- `--altitude-type <MSL|AGL>` (alias `--alt-type`), case-insensitive
+- `--gps <lat>,<lon>[,<altitude>[,<altitude-type>]]` — combined convenience;
+  minimum `--gps <lat>,<lon>`; a missing altitude-type in the 3-part form
+  defaults to `MSL`.
+
+Bare `k=v` positionals also work (`lat=…`, `lon=…`, `altitude=…`,
+`altitude-type=…`), through the same validation as the flags above. Aliases are
+canonicalized to their table form in one place before storage/validation, so
+the canonical key is always what lands in the comment and the envelope; typos
+beyond the alias list are caught by the existing "Did you mean?" flag
+suggester (`closestFlags`/`unknownFlagError`).
+
+Validation errors reuse the `input/` arg-validation family:
+`input/invalid-coordinate` (lat/lon NaN or out of range),
+`input/invalid-altitude` (altitude NaN, or a bad altitude-type), and
+`input/incomplete-gps` (lat/lon not paired, or `--gps` wrong arity).
+
+### Coordinate order is lat-first
+
+`--gps 37.7749,-122.4194` is `lat,lon` — **latitude first, everywhere** —
+matching ISO 6709 / EPSG:4326 authority order (and Google Maps / Leaflet /
+most GPS devices), not GeoJSON's lon-first order. RFC 7946 (GeoJSON) describes
+its own order as the opposite of "most GPS coordinates" and calls swapping them
+"the most common GeoJSON bug"; lat-first is both what an agent guesses from the
+`--gps` name and the standards-backed (ISO 6709) choice. A future GeoJSON
+(lon-first) input path is deliberately out of scope here — it would ride a
+structurally-typed shape (a real GeoJSON object / TikTOML import), never a bare
+CSV.
+
+### Altitude is metadata-only
+
+`altitude`/`altitude-type` are stored and returned in `devices show`/`list`
+output, but are **not** part of any fan-out query predicate — the `--near`/
+`--bbox` geo selectors are 2-D lat/lon only.
+
+### Geo query (`--near` / `--bbox`)
+
+Two geo selectors filter/select by device GPS. On `devices list` they filter the
+listing; on every non-terminal fan-out command (`execute`/`retrieve`/`api`/
+`transfer`) they are union selector terms in the shared target-selection grammar
+(`docs/CONSTITUTION.md`, Target selection). Coordinates are lat-first (above); a
+geo-less device carries no location and is silently excluded (never an error).
+
+- `--near <lat>,<lon>,<radius>` — devices within a great-circle (haversine)
+  radius of the point. `radius` takes a unit suffix `m`/`km`/`mi`/`ft`
+  (case-insensitive); a bare number is kilometers. A malformed/negative radius is
+  `input/invalid-radius`; wrong arity is `input/invalid-command`.
+- `--bbox <south>,<west>,<north>,<east>` — devices inside the axis-aligned box
+  (`minLat,minLon,maxLat,maxLon`, edges inclusive). Requires `south <= north` and
+  `west <= east` (an antimeridian-crossing box is not supported in v1), else
+  `input/invalid-bbox`.
+
+On `devices list`, `--group`/`--where`/`--near`/`--bbox` AND-narrow the listing
+(a filter surface); `--near` and `--bbox` union with each other. In the fan-out
+grammar every selector unions (see the constitution). `--near`/`--bbox` are
+rejected on `add`/`set`/`show`/`remove` with `input/invalid-command` — they
+select, they do not store.
+
+### Envelope
+
+`devices show`/`list` add an optional `location` block to each entry that
+carries a well-formed `lat`+`lon` pair, parsed from the comment facts:
+
+```json
+{ "lat": 37.7749, "lon": -122.4194, "altitude": 16, "altitudeType": "MSL" }
+```
+
+A record with no (or malformed) `lat`/`lon` simply omits `location`.
+
+### Group-level GPS defers to #137
+
+CDB groups are a bare string field on each entry — there is no
+group-definition record to hang a group-level GPS or lat/lon inheritance on.
+That needs TikTOML (#137); not doable in the CDB today.
 
 ## Groups
 
@@ -182,27 +308,33 @@ split lands.)
 ## Fanout (multi-target invocations)
 
 Any command may receive multiple positional targets, one or more `--group`
-flags, `--all`, `--default`, and/or `--where <attr>=<value>` (device-class) — see
-`docs/CONSTITUTION.md` (Target selection grammar). The resolved member set is
-de-duplicated by CDB record index.
-
-- Each member runs in parallel up to `--concurrency` (default
-  `max(1, floor(os.cpus().length / 2))`).
-- `--fail-fast` aborts pending members on the first failure.
-- The outer envelope's `data` is an array of inner envelopes, one per member,
-  in the resolved member order (CDB record index — see `devices` group
-  expansion), not completion order, so repeated runs produce stable diffs.
-  Members still execute in parallel and may *complete* out of order; progress
-  is surfaced via `meta`, but the `data` array is always reassembled in the
-  deterministic resolved order. `ok` of the outer envelope is `true` iff every
-  inner envelope is `ok: true`.
-- Commands that are not safe to fan out (e.g. `terminal`) reject N > 1 with
-  `usage/fanout-not-supported`.
+flags, `--all`, `--default`, `--where <attr>=<value>` (device-class), and/or the
+geo selectors `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>`
+(see "Geo query" above) — see `docs/CONSTITUTION.md` (Target selection grammar).
+The resolved member set is
+de-duplicated by CDB record index (ad-hoc literal targets by host), and members
+are reassembled in record-index order regardless of completion order, so repeated
+runs produce stable diffs.
+
+- Each member runs in parallel up to `--concurrency` (transport-aware defaults:
+  `rest-api` 8, `native-api` 4).
+- Output is the locked `FanoutData` envelope with the granular `0`/`2`/`1` exit
+  code. The envelope shape (outer `ok` = orchestration success; a per-target
+  failure is an inner `ok: false`) and the exit-code contract are defined once in
+  [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md) (Target selection) — not
+  restated here.
+- A multi-target **write** is gated by `--yes`, confirmed once up front (not per
+  target); without it the error/tip names the blast radius (how many routers).
+  `--force` stays scoped to destructive `devices` CDB mutations.
+- Commands that are not safe to fan out (`terminal`, and `api --stream` /
+  `--listen`) reject a multi-target selection with `usage/fanout-not-supported`.
 
 ## Subcommands
 
 ```text
-centrs devices list [--group G] [--format json|yaml|text]
+centrs devices list [--group G] [--where attr=value]
+                    [--near lat,lon,radius] [--bbox south,west,north,east]
+                    [--format json|yaml|text]
 centrs devices show <target> [--explain] [--via <protocol>] [--match <type>]
 centrs devices groups [--members]
 centrs devices discover [--timeout 15s] [--group G]      # = discover --save (save implied)
@@ -210,9 +342,13 @@ centrs devices add <target> [--user U] [--password P] [--new-group G]
                              [--profile P|--profile-none|--profile-own]
                              [--session S] [--comment "text k=v"]
                              [--record-type ipAdmin|ipUser|macTarget|...]
+                             [--gps lat,lon[,altitude[,altitude-type]]]
+                             [--lat D] [--lon D] [--altitude M] [--altitude-type MSL|AGL]
 centrs devices set  <selector…> [--user U] [--password P] [--new-group G]
                              [--profile P|--profile-none|--profile-own]
                              [--session S] [k=v ...]
+                             [--gps lat,lon[,altitude[,altitude-type]]]
+                             [--lat D] [--lon D] [--altitude M] [--altitude-type MSL|AGL]
 centrs devices remove <selector…>
 centrs devices edit <target>            # future: clack/TUI wizard
 ```
@@ -226,7 +362,11 @@ field-editing verb, and invoking it today returns `usage/not-implemented`. There
 is no `update`.
 
 - `list` (alias `print`) shows resolved targets, their record type, group, and
-  a one-line provenance summary. No network IO.
+  a one-line provenance summary. No network IO. `--where attr=value`
+  (repeatable, AND-combined) filters by CDB-stored facts/comment-kv plus core
+  record fields (`target`/`group`/`identity`/`mac`) — e.g. `--where
+  lat=37.7749`. `--near lat,lon,radius` and `--bbox south,west,north,east`
+  filter by device GPS (see "Geo query"). All three are `list`-only.
 - `show` (alias `get`) returns a single resolved target with the full per-field
   source map in `meta.target`. `--explain` adds the raw CDB record dump under
   `data.record`; `--via <protocol>` reports the protocol that would be selected