@tikoci/centrs 0.1.3 → 0.1.6

package/commands/api/examples.md

@@ -155,7 +155,23 @@ centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --use
 ```
 
 Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
-`meta.validation.semantic=not-applicable` (script, not a path).
+`meta.validation.semantic=not-applicable` (script, not a path) and
+`meta.validation.stages` is `offline: passed` then `device: skipped`.
+
+### 16b. The `/execute` script is gated offline (GH#354)
+
+Until GH#354 the script-mode carve-out meant this surface ran **no** preflight at
+all. The offline analyzer is the whole stage-1 gate here, and it opens no
+connection — the unreachable port proves it.
+
+```bash
+centrs api 127.0.0.1:1 execute -X POST -f script=':put [' --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`, `error.context.surface="api /execute"`,
+`error.context.span={"start":5,"end":6}`, and **not** a `transport/*` code.
+`meta.validation.stages` is `offline: failed` then `device: skipped`.
 
 ### 17. `--via rest-api --listen` is rejected
 
@@ -209,6 +225,20 @@ proplist). Combining an id with `--query`/`--proplist` folds the id into the RES
 matching the native `?.id=` read. (Plain id-only reads still use the `GET …/$ID`
 URL form; see example 5's re-read.)
 
+### 22. `--raw --validate=true` still runs the gate (#154)
+
+```bash
+centrs api $R ip/no-such-menu --raw --validate=true --username $U --password $P
+```
+
+`--raw` only **defaults** `--validate` to false, so an explicit `--validate=true`
+wins and the `/console/inspect` preflight runs. The rejection comes back in the
+`--raw` error shape, not the envelope: stdout empty, stderr a compact
+`{"code":"validation/unknown-path","message":…}`, nonzero exit, and no `data`
+key. Contrast example 13, where bare `--raw` skips the preflight entirely. This
+pair is how you tell a RouterOS rejection from a centrs bug while staying on the
+bare-passthrough surface.
+
 ## native-api (`--via native-api`)
 
 The same contract over the binary API. Validation still runs through
@@ -426,3 +456,18 @@ The reserved record is a credential fallback, not a connectable router, so its o
 target fails deterministically: inner `ok:false` with
 `error.code=target/unresolved` (never a `transport/dns` attempt on `"__default__"`).
 `data.summary = { total: 1, ok: 0, failed: 1 }`. Exit code 1 (every target failed).
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth
+come from the live descriptor (see `commands/retrieve/examples.md` Q-series).
+Covered by `test/integration/quickchr-target.test.ts`.
+
+### Q1. GET against a quickchr target
+
+```bash
+centrs api --quickchr $NAME system/resource --json
+```
+
+Envelope: `ok: true`, `data` is the resource object,
+`meta.target.source.kind=provider`.

package/commands/btest/README.md

@@ -80,38 +80,27 @@ centrs btest server [--authenticate[=false]] [--user U] [--password P] \
 
 ## Flags
 
-### `btest client <router>`
-
-| Flag | RouterOS analog / default | Notes |
-| ---- | ------------------------- | ----- |
-| `--protocol <udp\|tcp>` | `protocol`, default `udp` | UDP measures raw throughput + loss; TCP measures goodput. |
-| `--direction <receive\|transmit\|both>` | `direction`, default `receive` | `receive` = download (server→client), `transmit` = upload. |
-| `--duration <dur>` | `duration` | Bounds the run; reuses `parseDuration`. Omit for open-ended (Ctrl-C). |
-| `--interval <dur>` | `interval`, default `1s` | Report cadence (`20ms`..`5s`). One report frame per interval. |
-| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. centrs opens the negotiated extra connections (join format grounded against RouterOS 7.23.1) so throughput aggregates across streams. **Authenticated (EC-SRP5) sessions stay single-stream** — the post-auth token is not captured — and emit a `routeros/btest-connection-count-single-stream` warning. |
-| `--local-udp-tx-size <n>` | `local-udp-tx-size` (28..64000) | **UDP only.** Client→server packet size. |
-| `--remote-udp-tx-size <n>` | `remote-udp-tx-size` (28..64000) | **UDP only.** Server→client packet size. |
-| `--local-tx-speed <bps>` | `local-tx-speed` | Cap on client→server rate (bits/sec). |
-| `--remote-tx-speed <bps>` | `remote-tx-speed` | Cap on server→client rate (bits/sec). |
-| `--random-data` | `random-data`, default off | Incompressible payload (defeats link compression; CPU-heavier). |
-| `--user` / `--password` | `user` / `password` | Fall back to CDB / `CENTRS_*`. Required when the server has `authenticate=yes`. |
-| `--port <n>` | — (default `2000`) | Control port override. |
-| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = live human reports; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
-| `--csv` | — | Shortcut for `--format csv`. |
-
-### `btest server`
-
-| Flag | RouterOS analog / default | Notes |
-| ---- | ------------------------- | ----- |
-| `--authenticate[=false]` | `authenticate`, **default `true`** | Require EC-SRP5 auth; `--authenticate=false` accepts anonymous clients. |
-| `--user` / `--password` | — | The accepted credential when `authenticate=true` (v1: one user). Falls back to `CENTRS_*`. |
-| `--bind <addr>` | **centrs-only** | Listen address; **default `127.0.0.1`**. Use `0.0.0.0` to expose on the LAN. |
-| `--port <n>` | — (default `2000`) | Control-connection port. |
-| `--allocate-udp-ports-from <n>` | `allocate-udp-ports-from` | Base of the UDP data-port range; default `2001` (just above the TCP/2000 control port). |
-| `--max-sessions <n>` | `max-sessions` (1..1000), default `100` | Concurrent test cap; further clients get `routeros/btest-too-many-sessions`. |
-| `--duration <dur>` | — | Optional auto-stop; otherwise runs until Ctrl-C. |
-| `--format <text\|csv\|json\|yaml>` | — (default `text`) | `text` = human session log; `csv` = streaming CSV records; `json`/`yaml` = final summary envelope. |
-| `--csv` | — | Shortcut for `--format csv`. |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → btest](../../docs/CLI.md#btest) — one table for both
+subcommands, with `(client)`/`(server)` markers scoping each flag; "did you
+mean?" hints are scoped to the active mode. This file does not duplicate that
+table. Behavior notes the generated reference cannot carry:
+
+- Flag names mirror the RouterOS analogs verbatim (`protocol`, `direction`,
+  `local-udp-tx-size`, `connection-count`, `authenticate`,
+  `allocate-udp-ports-from`, …); centrs-only additions are `--bind`, `--port`,
+  the shared `--format`/`--csv`, and the CDB credential flags.
+- `--direction receive` = download (server→client), `transmit` = upload.
+- `--connection-count` is TCP-only; **authenticated (EC-SRP5) sessions stay
+  single-stream** — the post-auth token is not captured — and emit a
+  `routeros/btest-connection-count-single-stream` warning (see Open
+  questions).
+- `--user`/`--password` fall back to CDB / `CENTRS_*`; required when the
+  server has `authenticate=yes`. On the server they are the accepted
+  credential (v1: one user).
+- Option ranges (`28..64000` UDP sizes, `1..255` connections, `20ms..5s`
+  interval, `1..1000` sessions) are validated before any socket opens (see
+  Errors).
 
 ## How it works
 

package/commands/check/README.md

@@ -197,6 +197,11 @@ triggered/enrichment checks; `--fast` suppresses progressive triggers.
 
 ## Flags
 
+The whole command is spec-tier (`designed` — nothing is implemented yet), so
+this table is the design, not a reference; once `check` lands, its
+implemented flags will be generated into `docs/CLI.md` like every other
+command's.
+
 | Flag | Behavior |
 | ---- | -------- |
 | `--preset <name>` | `reach` / `health` (default) / `exposure` / `full`. |
@@ -243,7 +248,7 @@ RouterOS commands vary by version and arch, so a check must not blow up on a
 device that lacks the path it reads. `resource` runs first and yields the **live**
 version / arch / board; the orchestrator pre-flights each remaining check's
 `requires` paths against that live value (falling back to the stored
-`routeros_version` derived fact, or one batched `/console/inspect` when neither is
+`version` derived fact, or one batched `/console/inspect` when neither is
 conclusive), and marks an unsupported check `ran:false` with
 `skipReason:"unsupported-on-<version>"` — a graceful skip, not a raw protocol
 error. Grounding is offline-first against restraml's historic `inspect.json`

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

@@ -16,11 +16,26 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 - 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 runs **offline first, then on the device** (see constitution:
+  validation; GH#354). Stage 1 is the corpus-gated analyzer over the exact
+  command string, with no connection: a syntax fault is rejected with a byte
+  span in `error.context.span` and the adapter is never dialed, and
+  `meta.validation.stages[]` then shows the device stage `skipped`. Stage 1
+  cannot see an unknown attribute — it has no per-menu schema — so stage 2 is
+  not optional.
+- Stage 2 is itself two gates (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 request=child` / server re-validation semantic
+  checks are separate. Command-level `request=completion` is deliberately not
+  used: it hangs REST and closes native API on RouterOS 7.12.2 (GH#343), while
+  `child` returns the complete argument-name set immediately.
+  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`
@@ -67,13 +82,33 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   terminal width, so each transport handles width differently. **mac-telnet** is
   the only one that negotiates a size: `src/protocols/mac-telnet-console.ts`
   answers the device's terminal-size probe with a deliberately tall/wide screen,
-  so captured columns are neither wrapped nor paginated. **SSH execute** runs
-  *without* a pseudo-tty (`src/protocols/ssh.ts`), so RouterOS emits no
-  terminal-wrapped output to begin with — there is nothing to negotiate.
-  **REST/native-api** are not consoles, so terminal width never applies (they
-  return structured records, or a string `ret` for script-mode). There is
-  therefore no per-call `--width` knob today — an explicit width override is
-  deferred until a concrete need appears.
+  so captured columns are neither paginated nor wrapped *at the negotiated
+  width*. **SSH execute** runs *without* a pseudo-tty (`src/protocols/ssh.ts`),
+  so no width is negotiated at all. **REST/native-api** are not consoles, so a
+  terminal width never applies (they return structured records, or a string
+  `ret` for script-mode). There is therefore no per-call `--width` knob today —
+  an explicit width override is deferred until a concrete need appears.
+- **A device-side wrap that no width negotiation reaches (GH#352).** Declaring a
+  width is not sufficient, because RouterOS can wrap for reasons that are not
+  about width. On 7.23.6 / 7.24.3 / 7.25beta4 a settings menu with exactly one
+  property prints its value **one character per line**: `/system/identity/print`
+  returns `name: C` / `H` / `R` where 7.24.2 returns `name: CHR`. Measured on
+  stock CHR, the wrap is identical over REST `POST /rest/execute`, over
+  `ssh user@host "<cmd>"`, and over the mac-telnet console — including the
+  mac-telnet reader that has already answered the size probe with 512 columns,
+  and the ssh client that negotiates nothing. The console login modifiers
+  (`+c512w200h`, `+ct`, `+e`) do not change it, and it is not proportional to
+  the value's length. Every multi-property `print` is unaffected on the same
+  build, as is `:put [/system/identity/get name]`.
+
+  Consequence for this command: `data.ret` carries the device's console text
+  **verbatim**, wrap included — centrs cannot tell a layout newline from
+  content, and inventing a de-wrapper would corrupt legitimate output. Callers
+  that need a value rather than a rendering should read it structurally
+  (`retrieve`, or `api`) or ask the device for the scalar
+  (`:put [<menu>/get <property>]`). The integration examples compare identities
+  with `print` column wrapping collapsed for this reason — see
+  `collapsePrintWrapping` in `test/integration/chr.ts`.
 - Attribute values pass through **verbatim** — centrs does not guess types or
   coerce them (RouterOS REST tolerates string values; the native API is
   all-strings). Unlike `jo`-style KV builders, there is no per-value
@@ -102,30 +137,31 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 
 ## 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.  |
-| `--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. |
-| `--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. |
+| `--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
 
@@ -174,6 +210,11 @@ many tokens):
 - `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
@@ -213,7 +254,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
@@ -243,7 +284,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

@@ -62,16 +62,18 @@ 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 ...]`
+### 5. Syntax reject before the write round-trip
 
 Malformed CLI is rejected by the syntax gate before semantic validation or the
 write round-trip.
@@ -80,9 +82,16 @@ write round-trip.
 centrs execute $R '/ip/address/add address="unterminated interface=ether1' --via rest-api --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string from `:put [:parse ...]`, `meta.via=rest-api`,
-and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=rest-api`, and
+no address is added.
+
+**Which stage rejects it changed in GH#354.** This input is now caught by the
+*offline* stage, so `error.context.validationStage="offline"`,
+`error.cause="explain/canonicalizer/unterminated-string"`,
+`error.context.span={"start":24,"end":54}`, and the device is never contacted —
+see V1–V3 below. It reached `:put [:parse ...]` before that. The code, the
+`meta.via`, and the no-mutation guarantee are unchanged, which is why the
+assertion in `test/integration/execute.test.ts` still reads `validation/syntax`.
 
 ### 6. Semantic reject that `:parse` accepts
 
@@ -95,7 +104,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.
@@ -200,14 +209,16 @@ centrs execute $A "/ip/address/remove numbers=$ID" --via native-api --port $API_
 Envelope: `ok: true`, `meta.via=native-api`. A subsequent retrieve of
 `/ip/address` does not contain `$ID`.
 
-### 15. Native syntax reject from `:parse`
+### 15. Native syntax reject
 
 ```bash
 centrs execute $A '/ip/address/add address="unterminated interface=ether1' --via native-api --port $API_PORT --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string, `meta.via=native-api`, and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=native-api`, and
+no address is added. The native twin of example 5, and it moved the same way:
+the offline stage rejects this input now, so the verdict no longer depends on
+the transport at all.
 
 ### 16. Native semantic reject after clean parse
 
@@ -283,6 +294,10 @@ 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`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### 21. Write (add) over mac-telnet
 
 ```bash
@@ -327,6 +342,10 @@ Envelope: `ok: true`, `meta.via=ssh`, `data.ret` is the cleaned console output a
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over ssh`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### S2. Multi-line read returns cleaned, column-aligned output
 
 ```bash
@@ -354,6 +373,61 @@ 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.
 
+## Offline gate (stage 1)
+
+Validation runs offline before it runs on the device
+([`docs/CONSTITUTION.md` → Validation is the product](../../docs/CONSTITUTION.md#validation-is-the-product),
+GH#354). These two prove the stage exists and that a stage-1 rejection reaches no
+router. Run by `test/integration/execute.test.ts`.
+
+### V1. Offline reject, with the device stage never asked
+
+`:put [` is an unclosed bracket. The old local quote preflight counted quotes
+only, so this used to cost a full round trip to be told no; the analyzer rejects
+it with a byte span before anything is dialed.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`,
+`error.context.span={"start":5,"end":6}`,
+`error.context.diagnostics[0].code="explain/canonicalizer/unclosed"`,
+`error.position` absent (the offline byte offset is never dressed up as a
+RouterOS-reported one), `meta.validation.source` is the offline analyzer, and
+`meta.validation.stages` is `offline: failed` followed by `device: skipped`.
+
+### V2. The same rejection with no reachable router at all
+
+The proof that stage 1 opens no connection: point the same command at a port
+nothing is listening on. A gate that dialed first would report a
+`transport/*` error or hang until the timeout.
+
+```bash
+centrs execute 127.0.0.1:1 ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: identical to V1 — `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"` — and **not** a `transport/*` code.
+
+### V3. `--validate=false` disables the offline stage too
+
+One flag, one meaning. The escape hatch has to reach stage 1, or a caller hitting
+an analyzer defect would have no way past it. RouterOS then rejects the command
+itself on the run.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json --validate=false
+```
+
+Envelope: `ok: false`, `error.code=routeros/request-failed` with RouterOS's own
+`syntax error (line 1 column 7)` in the summary — the **device** rejecting it, not
+centrs — plus `meta.validation.enabled=false`, `meta.validation.result="skipped"`,
+and `meta.validation.stages` listing **both** stages as `skipped`. A gated
+surface always reports every stage, so a consumer reading `stages` never has to
+special-case the disabled shape.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar
@@ -435,3 +509,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).