@tikoci/centrs 0.1.2 → 0.1.4

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/discover/README.md

@@ -53,17 +53,11 @@ tested without a router (crafted packet fixtures + a loopback socket).
 
 ## Flags and defaults
 
-| Flag             | Default       | Meaning                                              |
-| ---------------- | ------------- | ---------------------------------------------------- |
-| `--timeout`      | `15s`         | Listen window before results are returned. First refresh is sent immediately. |
-| `--save`         | off           | Persist discovered neighbors into the CDB.           |
-| `--group`        | `discovered`  | First-class CDB group assigned to saved entries.     |
-| `--port`         | `5678`        | UDP port to bind for MNDP.                            |
-| `--cdb-file`     | resolved CDB  | CDB path override for `--save`.                      |
-| `--cdb-password` | env/none      | Decrypt an encrypted CDB; also used to re-encrypt on `--save`. |
-| `--format`       | `text`        | `text`, `json`, or `yaml`; renders the same envelope. |
-
-`--save` without `--timeout` uses the default 15s window.
+Implemented flags (with their defaults) are generated from the CLI metadata
+into [`docs/CLI.md` → discover](../../docs/CLI.md#discover); this file does
+not duplicate that table. The first refresh is sent immediately, so the
+`--timeout` listen window (default 15s) bounds the wait, and `--save` without
+`--timeout` uses the same default window.
 
 Bare `centrs discover` is **read-only** — it returns the envelope and never
 writes the (WinBox-shared) CDB; `--save` is the explicit opt-in. When it finds

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
@@ -15,11 +16,17 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 - Mirror RouterOS `execute` semantics. Input is a CLI string; output is
   console-shaped text (or structured records for path+verb writes) wrapped in
   the standard envelope. This includes write-shaped add/set/remove.
-- Validation is two-stage (see constitution: validation): `:put [:parse
-  "<cmd>"]` is a **syntax** gate only — it does not catch unknown attributes or
-  bad values. Semantic validation needs `/console/inspect` or the server's own
-  re-validation on the write round-trip. A clean parse is necessary, not
-  sufficient.
+- Validation is two-stage (see constitution: validation; grounded on CHR 7.23.3,
+  GH#230): a single `:put [:parse "<cmd>"]` covers both the syntax and the
+  unknown-attribute (name-level) gate on **every** transport — `:parse` never
+  throws; its return value's printed form (`(evl …)` / `(evl bad parameter …)` /
+  `(<%% bad command name …)`) is read from the REST/native `ret` *and* the
+  console output. That check is necessary, not sufficient: value-type errors pass
+  it, and the `/console/inspect` / server re-validation semantic checks are
+  separate.
+  The outer RouterOS string literal escapes backslash, quote, and dollar so
+  validation parses the caller's exact command rather than expanding variables
+  in the wrapper.
 - centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
   `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
   whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
@@ -101,24 +108,31 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 
 ## Flags
 
-| Flag                            | Behavior                                                                              |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → execute](../../docs/CLI.md#execute); this file does not
+duplicate that table. Behavior notes the generated reference cannot carry:
+
+- `--validate` is transport-appropriate but now one gate on every transport —
+  a single `:put [:parse ...]` that is read as a value (GH#230): REST/native
+  read the `ret` text (HTTP 200 / `as-string`); mac-telnet and ssh read the
+  console's printed value.
+- `--format` defaults to `text`; `CENTRS_FORMAT` sets the default.
+- `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
+  (0.4.5+, optional dependency) descriptor, bypassing CDB/env resolution for
+  those fields.
+- `--` — 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. In fan-out, positional targets come BEFORE `--` and the command
+  AFTER it (see **Target selection**).
+
+### Designed, not implemented
+
+Spec-tier flags with no implementation yet — today they fail as unknown flags:
+
+| Flag                            | Designed behavior                                                                      |
 | ------------------------------- | ------------------------------------------------------------------------------------- |
-| `--via <protocol>`              | Pin the transport (`native-api`, `rest-api`, `ssh`, or `mac-telnet`). No silent downgrade. A bare MAC target defaults to `mac-telnet`. |
-| `--host <host\|url>`            | Override the resolved host or base URL for the target.                                 |
-| `--port <n>`                    | Override the resolved management port.                                                 |
-| `--username` (alias `--user`, `-u`) / `--password` | RouterOS credentials; fall back to `CENTRS_USERNAME` / `CENTRS_PASSWORD`.              |
-| `--ssh-key <path>`              | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the ssh-agent. |
-| `--insecure`                    | Accept a new SSH host key (`--via ssh`) or a self-signed `api-ssl` TLS cert. Default verifies. |
-| `--cdb-file` / `--cdb-password` | Read target credentials from (and decrypt) a WinBox CDB file.                          |
-| `--resolve <none\|arp>`         | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.          |
-| `--timeout <duration>`          | Per-request timeout. REST: ≤ 60s; other transports may allow longer.                  |
-| `--validate[=false]`            | Run transport-appropriate preflight validation before execution (default `true`): REST/native use `:parse` + `/console/inspect`; mac-telnet and ssh use a single console `:parse` (covers syntax + unknown-attribute). |
 | `--strict`                      | Treat any warning on a successful run as an error (`ok: false`, nonzero exit), like `-Werror`. Default is lenient (`ok: true` + `warnings`). |
-| `--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.  |
-| `--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. |
+| `--max-bytes <n>`               | Byte budget for the rendered envelope; excess output is truncated with a warning + `meta.truncated` (not an error), matching `retrieve`. (Will replace the implemented `--max-results`, which fails instead of truncating.) |
 
 ## SSH key selection
 
@@ -147,6 +161,39 @@ 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`.
+- `execute --quickchr lab /system/resource/print` — the quickchr
+  named-live-provider claims the target slots like a selector (positionals are
+  the command; no `--` needed). One `--quickchr` stays single-target; repeating
+  it fans out; mixing it with positionals or CDB selectors is
+  `usage/conflicting-flags` (constitution: resolution providers).
+
+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
@@ -162,7 +209,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.
 
@@ -178,7 +225,7 @@ How it is wired:
   `transport/capability-unsupported` (mac-telnet is execute/terminal only).
 - **Validation is one console `:parse`.** Over the console, `:put [:parse "<cmd>"]`
   prints both `syntax error` and `bad parameter <name>`, so a single gate covers
-  syntax **and** the unknown-attribute (semantic) check — no `/console/inspect`
+  syntax **and** the unknown-attribute (name-level) check — no `/console/inspect`
   table parsing. Maps to `validation/syntax` / `validation/unknown-attribute`,
   same codes as REST/native (see `docs/CONSTITUTION.md`, validation).
 - **Auth (grounded):** MTWEI is required; a stock device offers a 16-byte MD5 salt
@@ -208,7 +255,7 @@ Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
   **decided:** `--strict` promotes any warning on an otherwise-successful run to
   `ok: false` (nonzero exit), like `-Werror`; the default stays lenient
   (`ok: true` with the warning in the `warnings` channel). Tracked code
-  follow-up; the flag is in the table above.
+  follow-up; the flag is under **Designed, not implemented** above.
 
 These are deferred refinements to the already-grounded single-shot envelope,
 not blockers for the `rest-api`/`native-api` cells.

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`).
@@ -62,14 +62,16 @@ The command is a script-shaped console expression, not a slash path plus verb,
 so REST must use the `/rest/execute` fallback.
 
 ```bash
-centrs execute $R ':put [/system/identity/get name]' --via rest-api --username $U --password $P
+centrs execute $R ':local a true; :if ($a = true) do={:put [/system/identity/get name]}' --via rest-api --username $U --password $P
 ```
 
 Envelope: `ok: true`, `data` is string-shaped (`data.output` or `data.ret`) and
 contains the CHR identity name, `meta.via=rest-api`, and
 `meta.validation.syntax=true`. `meta.validation.semantic` is absent or marked
 `not-applicable` because `/console/inspect` validates path-shaped commands, not
-arbitrary script expressions.
+arbitrary script expressions. The `$a` variable must survive the validation
+wrapper: if that outer string expands it before `:parse`, this example fails even
+though RouterOS accepts the original command.
 
 ### 5. Syntax reject from `:put [:parse ...]`
 
@@ -95,7 +97,7 @@ centrs execute $R '/ip/address/add address=198.51.100.11/32 interface=ether1 no-
 ```
 
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
-`error.cause.attribute="no-such-arg"` (or equivalent structured field),
+`error.context.parameter="no-such-arg"`,
 `meta.validation.syntax=true`, `meta.validation.source=/console/inspect`, and
 no address is added. This example is the product claim: syntax validation and
 semantic validation are separate gates.
@@ -242,6 +244,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 +271,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 +285,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 +295,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 +356,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
@@ -351,3 +437,39 @@ Envelope: `meta.via=mac-telnet` when `$MAC` is not resolved from CDB and no
 `--host`/`--port`). If the caller wants IP-level REST or native API execution,
 they must opt into MAC-to-IP resolution (`--resolve arp` + `--via …`) before
 protocol selection.
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth
+come from the live descriptor — the CDB, `CENTRS_HOST`-style env, and the
+`__default__` ladder are bypassed for those fields. Covered by
+`test/integration/quickchr-target.test.ts`.
+
+### Q1. Run a command on a quickchr target (native API default)
+
+```bash
+centrs execute --quickchr $NAME ':put [/system/identity/get name]' --json
+```
+
+Envelope: `ok: true`, `meta.via=native-api` (execute's normal default),
+`meta.target.source.kind=provider`, `meta.target.identity=$NAME`.
+
+### Q2. A `--via` the descriptor does not forward → `quickchr/unsupported-via`
+
+```bash
+centrs execute --quickchr $NAME ':put 1' --via mac-telnet --json
+```
+
+Envelope: `ok: false`, `error.code=quickchr/unsupported-via` — quickchr v1
+forwards `rest-api`/`native-api`/`ssh` only; centrs never falls back to another
+transport.
+
+### Q3. Repeated `--quickchr` fans out; an unknown machine is an inner failure
+
+```bash
+centrs execute --quickchr $NAME --quickchr no-such-machine -- ':put 1' --json
+```
+
+Envelope: outer `ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`;
+the unknown machine's inner error is `quickchr/machine-not-found`. Exit code 2
+(partial).