@tikoci/centrs 0.1.1 → 0.1.3

package/commands/devices/examples.md

@@ -486,3 +486,151 @@ Each alias produces the same envelope as its canonical verb — `meta.operation`
 reports the canonical command (`list`/`show`/`remove`), never the alias. An
 unknown verb still errors with `input/invalid-command`, and the error lists the
 canonical verbs plus the accepted aliases.
+
+## Location / GPS
+
+Slice 1 of issue #146: `lat`/`lon`/`altitude`/`altitude-type` are recognized
+comment-kv facts (see `README.md`, Location / GPS) — stored, queryable via
+`--where`, and returned as a `location` block in `devices show`/`list` output.
+Coordinate order is **lat-first everywhere**: `--gps <lat>,<lon>[,…]`.
+
+### 42. `add --gps` sets lat/lon/altitude; `show` returns a `location` block
+
+```bash
+centrs devices add 198.51.100.40 --user admin --password p \
+  --gps 37.7749,-122.4194,16 --cdb-file $CDB
+```
+
+`ok: true`. Re-reading via `show` returns
+`data.entry.location = { lat: 37.7749, lon: -122.4194, altitude: 16, altitudeType: "MSL" }`
+(the 3-part `--gps` form defaults the missing altitude-type to `MSL`).
+
+### 43. Discrete `--lat`/`--lon` round-trip the same way as `--gps`
+
+```bash
+centrs devices set 192.0.2.5 --lat 51.5072 --lon -0.1276 --cdb-file $CDB
+```
+
+`ok: true`. `devices show 192.0.2.5` returns
+`data.entry.location = { lat: 51.5072, lon: -0.1276 }` (no `altitude` key —
+altitude was never set on this record).
+
+### 44. `--altitude` alone defaults `altitudeType` to `MSL` in the envelope
+
+```bash
+centrs devices set 192.0.2.6 --lat 48.8566 --lon 2.3522 --altitude 35 \
+  --cdb-file $CDB
+```
+
+`ok: true`. `altitude-type` was never written to the comment (only
+`--altitude` was passed), but `devices show 192.0.2.6` still returns
+`data.entry.location.altitudeType = "MSL"` — the metadata-only default applied
+at read time (`deviceLocation` in `src/resolver/geo.ts`).
+
+### 45. Setting `lat` without `lon` errors with `input/incomplete-gps`
+
+```bash
+centrs devices set 198.51.100.1 --lat 10 --cdb-file $CDB
+```
+
+Errors with `input/incomplete-gps` (target `198.51.100.1` carries no prior
+`lon`). No write; no backup written.
+
+### 46. An out-of-range `--lat` errors with `input/invalid-coordinate`
+
+```bash
+centrs devices set 192.0.2.5 --lat 200 --lon 0 --cdb-file $CDB
+```
+
+Errors with `input/invalid-coordinate`. No write; no backup written.
+
+### 47. An invalid `--altitude-type` errors with `input/invalid-altitude`
+
+```bash
+centrs devices set 192.0.2.5 --lat 10 --lon 10 --altitude-type wgs84 \
+  --cdb-file $CDB
+```
+
+Errors with `input/invalid-altitude`. No write; no backup written.
+
+### 48. Alias flags canonicalize to the stored key; no more `cdb/unknown-option`
+
+```bash
+centrs devices set 192.0.2.5 --latitude 10 --lng 20 --cdb-file $CDB
+```
+
+`ok: true`, **no** `cdb/unknown-option` warning — `--latitude`/`--lng` are
+canonicalized to `lat`/`lon` in one place (`canonicalizeGeoKey`,
+`src/resolver/geo.ts`) before storage. `devices show 192.0.2.5` returns
+`data.entry.comment` containing `lat=10` and `lon=20` (the canonical keys), and
+`data.entry.location = { lat: 10, lon: 20 }`.
+
+### 49. `list --where lat=<verbatim>` matches the exact stored string
+
+```bash
+centrs devices list --where lat=37.774900 --cdb-file $CDB
+```
+
+`ok: true`; matches only the record whose stored `lat` fact is the exact
+string `37.774900` (values are stored verbatim as typed, never reformatted —
+see `README.md`, Location / GPS). `--where lat=37.7749` (numerically equal,
+reformatted) matches nothing.
+
+## Geo query (`list --near` / `list --bbox`)
+
+`--near`/`--bbox` filter `devices list` by device GPS (great-circle radius or a
+lat-first bounding box). Coordinates are lat-first everywhere (see `README.md`,
+Location / GPS); a geo-less device carries no location and is silently excluded.
+The same predicates ride the shared fan-out grammar on every non-terminal
+command (`execute`/`retrieve`/`api`/`transfer`) — see `docs/CONSTITUTION.md`
+(Target selection).
+
+### 50. `list --near <lat>,<lon>,<radius>` selects in-radius devices
+
+`192.0.2.5` is in San Francisco and `192.0.2.6` in New York (set via `--gps`);
+the other records carry no GPS.
+
+```bash
+centrs devices list --near 37.7749,-122.4194,50km --cdb-file $CDB
+```
+
+`ok: true`; `data` holds only `192.0.2.5`. New York is ~4100 km away (outside the
+50 km radius) and the geo-less records never match. The radius unit is one of
+`m`/`km`/`mi`/`ft`; a bare number is kilometers.
+
+### 51. `list --bbox <south>,<west>,<north>,<east>` selects devices in the box
+
+```bash
+centrs devices list --bbox 37.70,-122.52,37.83,-122.35 --cdb-file $CDB
+```
+
+`ok: true`; `data` holds only the device whose GPS falls inside the lat-first
+box (edges inclusive). The box must satisfy `south <= north` and `west <= east`
+(no antimeridian wrap), else `input/invalid-bbox`.
+
+### 52. `--near`/`--bbox` are `list`-only
+
+```bash
+centrs devices set 192.0.2.5 --near 37.7749,-122.4194,50km --cdb-file $CDB
+```
+
+Errors with `input/invalid-command`: `--where`/`--near`/`--bbox` *select*
+records for `list`; `add`/`set` name the `<target>` directly. Store GPS with
+`--gps`/`--lat`/`--lon` instead.
+
+### 53. An unrelated `set` on a record with a lone `lat` does not fail
+
+The lat/lon pairing check fires only when the write actually touches a
+coordinate. A record that already carries a lone `lat` (e.g. a hand-edited or
+imported comment) can still take unrelated updates.
+
+```bash
+centrs devices add 203.0.113.7 --user u --password p \
+  --comment "lat=37.7749" --cdb-file $CDB
+centrs devices set 203.0.113.7 timeout=5000 --cdb-file $CDB
+```
+
+Both succeed: the `add` stores the freeform comment verbatim, and the later
+`set timeout=5000` does **not** raise `input/incomplete-gps` even though the
+record's GPS pair is incomplete. Touching `lat`/`lon` (e.g. `set lat=…`) would
+re-enable the pairing check.

package/commands/execute/README.md

@@ -6,8 +6,9 @@ CLI-shaped commands — there is no separate `update` command.
 
 Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 `docs/MATRIX.md` and `commands/execute/examples.md`, examples 1–11 over REST,
-12–18 over the native API, 19–21 over mac-telnet, and S1–S4 over ssh, green via
-`bun run test:integration`). `romon` and `winbox-terminal` remain
+12–19 over the native API, 20–22 over mac-telnet, and S1–S4 over ssh, green via
+`bun run test:integration`), including multi-target fan-out (see **Target
+selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 `not-started`. SNMP is retrieve-only and rejects `execute`.
 
 ## Intent
@@ -52,6 +53,12 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
   else passes its `detail`/body plus the HTTP status through
   `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
   a hand-rolled `routeros/*` table on the REST side.
+- **Run-time fault mapping — later (JG-28).** `mapRouterOsError`'s table covers
+  the faults seen so far; a known gap is errors that *pass* `:parse`/validation
+  but fail at **run time** (a syntactically valid command the router rejects when
+  executed). `tikoci/vscode-tikbook` has an error-string mapping for these worth
+  porting into `src/core/routeros-errors.ts`. Background research, not yet
+  scheduled — captured here so it isn't lost (no GitHub issue by design).
 - Output is *string*-shaped for script-mode; richer parsing is a future
   concern. The envelope must still distinguish RouterOS errors from successful
   runs (a 200 with a RouterOS error string is still an error — see
@@ -111,8 +118,14 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 | `--yes`                         | Confirm write-shaped add/set/remove commands in non-interactive runs.                  |
 | `--max-bytes <n>`               | Byte budget for the rendered envelope; excess output is truncated with a warning + `meta.truncated` (not an error), matching `retrieve`. (Renamed from `--max-results`.) |
 | `--format <text\|json\|yaml>`   | Output format (alias `--json`). Defaults to `text`; `CENTRS_FORMAT` sets the default.  |
+| `--group <name>`                | Run across every CDB record in WinBox group `<name>`. Repeatable, combinable with `<target>` positionals plus `--where`/`--all`/`--default`; de-duped by record index. See **Target selection**. |
 | `--where <attr>=<value>`        | Device-class selector — run across every CDB record whose stored fact/comment-kv matches (e.g. `--where board=RB5009 /system/package/check-for-updates`). Repeatable (AND). See constitution: target selection. |
-| `--`                            | End-of-options marker. Every token after `--` is taken as the literal RouterOS command, even flag-shaped ones — e.g. `centrs execute $R -- /interface print where disabled=yes`. Use it when the command contains tokens that would otherwise be claimed as centrs flags; otherwise the command must be quoted as a single argument. |
+| `--all`                         | Run across every CDB record (excludes the reserved `__default__`). See **Target selection**. |
+| `--default`                     | Select the reserved `__default__` record. See **Target selection**. |
+| `--near <lat>,<lon>,<radius>`   | Geo selector — run across CDB records whose GPS is within the great-circle radius (units `m`/`km`/`mi`/`ft`; bare = km). Lat-first. Union predicate; geo-less devices never match. See **Target selection**. |
+| `--bbox <south>,<west>,<north>,<east>` | Geo selector — run across CDB records whose GPS is inside the lat-first bounding box. Union predicate. See **Target selection**. |
+| `--concurrency <n>`             | Max in-flight targets during fan-out (integer ≥ 1). Transport-aware default: `rest-api` 8, others 4. |
+| `--`                            | End-of-options marker. Every token after `--` is taken as the literal RouterOS command, even flag-shaped ones — e.g. `centrs execute $R -- /interface print where disabled=yes`. In fan-out, positional targets come BEFORE `--` and the command AFTER it (`centrs execute r1 r2 -- /system/reboot`). Use it when the command contains tokens that would otherwise be claimed as centrs flags; otherwise the command must be quoted as a single argument. |
 
 ## SSH key selection
 
@@ -141,6 +154,34 @@ contents, and any inline key material are always sensitive and must be listed in
 redacted only if the caller marks them sensitive or the error couples them with
 key material.
 
+## Target selection
+
+`execute` runs the **same** RouterOS command across a multi-target selection over
+the shared grammar (multiple `<target>` 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).
+
+execute's positional **boundary is `--`** (it differs from `api`/`retrieve`,
+whose last positional is the operation arg, because an execute command is itself
+many tokens):
+
+- `execute r1 r2 -- /system/reboot` — targets `[r1, r2]` before `--`, command
+  after. **More than one positional target requires `--`.**
+- `execute --group prod /system/resource/print` — selector-only: targets come
+  from the selector and every positional is the command (no `--` needed).
+- `execute r1 /system/resource/print` — a single positional target with no
+  selector stays **single-target** (legacy split: first positional is the target,
+  the rest is the command), never `FanoutData`.
+
+Because `execute` is the primary **write** path, a write-shaped fan-out
+(add/set/remove) is gated by **`--yes`**, confirmed **once** up front; without it
+the error names the blast radius (how many routers). Write-ness is determined from
+the command alone (`canonicalizeExecuteCommand` + `isWriteShaped`), so the gate
+fires before any target is dialed. Per-target validation still runs because
+RouterOS schemas can differ by version.
+
 ## mac-telnet L2 validation
 
 Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s
@@ -156,7 +197,7 @@ macOS needs `SO_REUSEPORT`; mcast works on Linux/CI). Grounding: quickchr
 
 `execute / mac-telnet` is now **`CHR-passed`** end to end over real L2 against
 stock CHR 7.23.1 (`test/integration/mac-telnet-console.test.ts` +
-`mactelnet-l2-bridge.ts`, examples 19–21): `executeEnvelope` resolves a MAC
+`mactelnet-l2-bridge.ts`, examples 20–22): `executeEnvelope` resolves a MAC
 target, the `MacTelnetAdapter` opens a `MacTelnetConsole` over a UDP datagram
 transport, and reads, writes (REST-verified), and validation-rejects all work.
 
@@ -195,9 +236,9 @@ Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
 ## Open shape questions
 
 - ~~How to expose multi-line / async / progress output~~ — **resolved:**
-  open-ended follow/streaming reads are the separate read-only `stream` verb
-  (NDJSON stream of envelopes; see `commands/stream/README.md`). `execute` stays
-  single-shot read/write; it does not grow a follow mode.
+  open-ended follow/streaming reads are `api … --stream` (NDJSON stream of
+  envelopes; see `commands/api/README.md`). `execute` stays single-shot
+  read/write; it does not grow a follow mode.
 - ~~Whether `--strict` should reject "succeeded with stderr-like content."~~ —
   **decided:** `--strict` promotes any warning on an otherwise-successful run to
   `ok: false` (nonzero exit), like `-Werror`; the default stays lenient

package/commands/execute/examples.md

@@ -2,8 +2,8 @@
 
 Each numbered example is an executable spec, run against a CHR 7.23 router booted
 by `@tikoci/quickchr`: `test/integration/execute.test.ts` covers examples 1–11
-over REST and 12–18 over the native API; `test/integration/mac-telnet-console.test.ts`
-covers examples 19–21 over mac-telnet (real L2 via the `socket-connect` bridge).
+over REST and 12–19 over the native API; `test/integration/mac-telnet-console.test.ts`
+covers examples 20–22 over mac-telnet (real L2 via the `socket-connect` bridge).
 If a line here is not exercised by a test, the test file is wrong; if a line
 passes only with `validate=false`, the **implementation** is wrong (see
 `docs/CONSTITUTION.md`).
@@ -242,6 +242,23 @@ centrs execute $A '/ip/address/add address=198.51.100.23/32 interface=ether1 com
 Envelope: `ok: false`, `error.code=usage/confirmation-required`,
 `meta.via=native-api`, no validation command is sent, and no address is added.
 
+### 19. Script-mode command runs through `/execute` with `as-string` (parity with REST)
+
+A non-path-shaped console expression over native-api falls through to
+`/execute` the same way REST does (example 4), instead of being refused.
+`as-string` makes native `/execute` block and return the captured output
+rather than scheduling a background job and returning only its id.
+
+```bash
+centrs execute $A ':put [/system/identity/get name]' --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data.ret` is a string containing the CHR identity (same
+shape and cross-transport value as example 4 over REST), `meta.via=native-api`,
+and `meta.validation.syntax=true`. Regression coverage for the bug where the
+native adapter sent `/execute` without `as-string`, silently discarding
+captured output.
+
 ## mac-telnet (`--via mac-telnet`)
 
 Layer-2 execute over the RouterOS interactive console (UDP/20561). `$MAC` is the
@@ -252,11 +269,11 @@ is a **single console `:put [:parse …]`** — it reports both `syntax error` a
 at once (no `/console/inspect` table parsing). The console opens through a
 first-login license screen (auto-answered) and a ~10s terminal-negotiation stall;
 **a successful write prints nothing** over the console (no `.id`/`ret`, unlike
-REST/native). Examples 19–21 are green via `bun run test:integration`
+REST/native). Examples 20–22 are green via `bun run test:integration`
 (`test/integration/mac-telnet-console.test.ts`, CHR 7.23.1) over the real L2
 bridge; the console reader is also exercised directly in the same test.
 
-### 19. Read a command over mac-telnet
+### 20. Read a command over mac-telnet
 
 ```bash
 centrs execute $MAC '/system/identity/print' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P
@@ -266,7 +283,7 @@ Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is the console output an
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over mac-telnet`.
 
-### 20. Write (add) over mac-telnet
+### 21. Write (add) over mac-telnet
 
 ```bash
 centrs execute $MAC '/ip/address/add address=198.51.100.40/32 interface=ether1' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P --yes
@@ -276,7 +293,7 @@ Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is empty (a successful
 console write prints nothing — there is no `.id` to return). A subsequent REST
 read of `/ip/address` shows `198.51.100.40`.
 
-### 21. Validation rejects an unknown attribute over mac-telnet
+### 22. Validation rejects an unknown attribute over mac-telnet
 
 ```bash
 centrs execute $MAC '/ip/address/add address=198.51.100.41/32 interface=ether1 no-such-arg=x' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P --yes
@@ -337,6 +354,73 @@ centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.51/32 interface=eth
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`, `meta.via=ssh`,
 and no address is added — the console `:parse` gate catches `bogus` pre-mutation.
 
+## 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/execute-fanout.test.ts` when CHR integration is enabled.
+`$CDB` has two records in group `fanout-chr`: record 0 is the live CHR (comment
+fact `role=edge`) and record 1 is an unreachable REST URL (`role=core`). Note the
+execute `--` boundary: targets/selectors come before it, the command after.
+
+### F1. Group fan-out of a read command
+
+```bash
+centrs execute --group fanout-chr --via rest-api --cdb-file $CDB --json -- /system/resource/print
+```
+
+`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` (`transport/connection-refused`). Process exit `2`.
+
+### F2. Empty / unknown group
+
+```bash
+centrs execute --group no-such-group --via rest-api --cdb-file $CDB --json -- /system/resource/print
+```
+
+`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 execute --where role=edge --via rest-api --cdb-file $CDB --json -- /system/resource/print
+```
+
+Selects 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 execute --all --via rest-api --cdb-file $CDB --json -- /system/resource/print
+```
+
+`data.summary = { total: 2, ok: 1, failed: 1 }`,
+`meta.operation.selection.all = true`, exit `2`.
+
+### F5. Write-shaped fan-out without `--yes` is refused (blast radius)
+
+```bash
+centrs execute --group fanout-chr --via rest-api --cdb-file $CDB --json -- /system/identity/set name=fanout-blast
+```
+
+A write-shaped 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 mutated. Add `--yes` to fan the write out.
+
+### F6. Multiple positional targets (ad-hoc literals) before `--`
+
+```bash
+centrs execute $REACHABLE_URL $UNREACHABLE_URL --via rest-api --username $U --password $P --json -- /system/resource/print
+```
+
+More than one positional target is fan-out mode (the `--` separates them from the
+command). 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`.
+
 ## Protocol selection notes
 
 For an unresolved MAC target, execute auto-selection defaults to mac-telnet

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
@@ -45,7 +49,7 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 | `--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 the separate `stream` verb. See constitution: protocol selection. |
+| `--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. |
@@ -64,7 +68,11 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 | `--cdb-file` / `--cdb-password`     | Override CDB file location / decrypt password.                                            |
 | `--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**. |
+| `--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 **Target selection**. |
+| `--all`                             | Fan out across every CDB record (excludes the reserved `__default__`). See **Target selection**. |
+| `--default`                         | Select the reserved `__default__` record. See **Target selection**. |
+| `--near <lat>,<lon>,<radius>`       | Geo selector: fan out across CDB records whose GPS is within the great-circle radius (units `m`/`km`/`mi`/`ft`; bare = km). Lat-first. Union predicate; geo-less devices never match. See **Target selection**. |
+| `--bbox <south>,<west>,<north>,<east>` | Geo selector: fan out across CDB records whose GPS is inside the lat-first bounding box. Union predicate. See **Target selection**. |
 | `--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 +145,33 @@ 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.
+
+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