@tikoci/centrs 0.1.7 → 0.1.8

package/commands/transfer/examples.md

@@ -15,7 +15,10 @@ Conventions (provided by the harness):
 - `$A` is `<host>` and `$API_PORT` is the native-API port (`chr.ports.api`) for
   `--via native-api`.
 - `$SRC` is a small local text file (~2 KB) the harness creates; `$TMP` is a
-  scratch directory for downloads. `$BIG` is a local file **larger than 60 KB**.
+  scratch directory for downloads. `$BIG` is a local file **larger than 60 KB**:
+  every byte value, then deterministic noise, with a UTF-8 `€` straddling each
+  32 KiB `/file/read` chunk boundary. `$BIN` is the same shape at exactly 60 KB,
+  the largest the `/file/set` write cap allows.
 - Device-side paths are **bare** (a CHR has no `flash` disk, so everything
   persists for the session); the harness removes `centrs-*` test files between
   runs. The CHR free license caps throughput at 1 Mb/s, so fixtures stay small —
@@ -77,6 +80,15 @@ centrs transfer $R list --name 'centrs-*' --username $U --password $P --json
 
 Envelope: every row's `name` matches the glob; `centrs-up.txt` is present.
 
+### H1. `--host` stands in for `<router>` (#428)
+
+```bash
+centrs transfer --host $R list --username $U --password $P --json
+```
+
+`ok: true`, with `data` the device's file list. Nothing comes before the verb,
+so `--host` is the target and there is no CDB lookup.
+
 ## Validate before write
 
 ### 6. Refuse overwrite without `--force`
@@ -202,8 +214,8 @@ centrs transfer $R download centrs-big.bin $TMP/big.bin --username $U --password
 ```
 
 Envelope: `ok: true`, `meta.via="rest-api"`, `data.bytes` equals the seeded size
-(>60 KB). `$TMP/big.bin` is byte-identical to the seed — proving the chunked read
-reassembles correctly across `/file/read` calls.
+(>60 KB). `$TMP/big.bin` has the seed's sha256 — proving the chunked read
+reassembles correctly across `/file/read` calls and keeps every byte value.
 
 ## Error / transport contract
 
@@ -284,14 +296,46 @@ centrs transfer $A upload $BIG centrs-too-big.txt --via native-api --port $API_P
 
 Envelope: `ok: false`, `error.code="transport/unsupported-operation"`.
 
+## Binary contents (#404)
+
+A size check cannot see a same-length substitution, so these compare sha256.
+
+### B1. Binary round-trip over REST
+
+```bash
+centrs transfer $R upload $BIN centrs-bin-rest.bin --username $U --password $P --json
+centrs transfer $R download centrs-bin-rest.bin $TMP/bin-rest.bin --username $U --password $P --json
+```
+
+Upload envelope: `data.bytes=60000`, `data.verified="size"`. `$TMP/bin-rest.bin`
+has the sha256 of `$BIN`.
+
+### B2. Binary round-trip over native-api
+
+```bash
+centrs transfer $A upload $BIN centrs-bin-nv.bin --via native-api --port $API_PORT --username $U --password $P --json
+centrs transfer $A download centrs-bin-nv.bin $TMP/bin-nv.bin --via native-api --port $API_PORT --username $U --password $P --json
+```
+
+Same as B1.
+
+### B3. Chunked binary read over native-api
+
+```bash
+centrs transfer $A download centrs-big.bin $TMP/nv-big.bin --via native-api --port $API_PORT --username $U --password $P --json
+```
+
+Runs after S3 seeds `centrs-big.bin`. `$TMP/nv-big.bin` has the sha256 of `$BIG`.
+
 ## ssh (`--via sftp`)
 
 The first SSH consumer: a key-authenticated SFTP round-trip over the host OpenSSH
 `sftp` subsystem. The harness generates an ed25519 keypair, imports the public
 half to the CHR user (`/user ssh-keys import`), and drives `--via sftp --ssh-key`
 against the CHR's forwarded SSH port; `--insecure` accepts the ephemeral host key
-(default is `accept-new` trust-on-first-use). RouterOS refuses password login once
-a key is set, and centrs's sftp runs `BatchMode=yes`, so key auth is the path.
+(default is `accept-new` trust-on-first-use). centrs's sftp runs `BatchMode=yes`
+and never sends a password, so key auth is the only path (S7); RouterOS's own
+password policy is a separate fact (S8).
 
 ### S1. sftp upload (host → device)
 
@@ -315,8 +359,9 @@ centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $U --ssh-key $K
 centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $U --ssh-key $KEY --insecure upload $BIG centrs-big.bin --json
 ```
 
-Envelope: `ok: true`. This is also the seed for example 17 (the same file then
-reads back over REST via chunked `/file/read`).
+Envelope: `ok: true`. An sftp download of it has the sha256 of `$BIG`. This is
+also the seed for examples 17 and B3 (the same file then reads back over REST and
+native-api via chunked `/file/read`).
 
 ### S4. list over sftp
 
@@ -336,6 +381,60 @@ centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $U --ssh-key $K
 Both `ok: true`. On-device `copy` has no SFTP primitive — `--via sftp copy` returns
 `transport/unsupported-operation` (it stays on rest/native).
 
+### S6. A rejected selected key fails despite a trusted agent identity
+
+The shared [SSH identity example S5](../execute/examples.md#s5-an-explicit-rejected-key-cannot-fall-back-to-an-unrelated-agent-key)
+runs a real SFTP list with an untrusted `--ssh-key` and a trusted key in a
+private agent. It fails with `auth/failed`; selecting the trusted key or leaving
+the key unset succeeds. Covered by `test/integration/ssh-identity.test.ts`.
+
+### S7. A resolved password does not authenticate batch sftp
+
+`$PW_USER` has a password, no SSH key, and the default
+`password-authentication=yes-if-no-key`; a plain OpenSSH password login as that
+user succeeds. The host OpenSSH runs with an empty config and no agent.
+
+```bash
+centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $PW_USER --password $PW_PASS --insecure list --json
+```
+
+Exit 1. Envelope: `ok: false`, `error.code="auth/failed"`,
+`error.context.sshKeySelected=false`, and the resolved meta — `meta.via="ssh"`,
+`meta.target.host`/`port`, `meta.settings.password={kind:"cli",key:"password"}`,
+`meta.operation.auth={username:$PW_USER,passwordProvided:true}`. `tips` is
+`tip/sftp-password-not-used` then `tip/transfer-password-transport`; text output
+lists the same tips. The password appears nowhere in either output.
+
+### S8. RouterOS password policy, and the key path that works
+
+After `/user ssh-keys import` installs `$KEY.pub` for `$PW_USER`, the plain
+OpenSSH password login is refused (`Permission denied`), and:
+
+```bash
+centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $PW_USER --ssh-key $KEY --insecure list --json
+```
+
+Envelope: `ok: true`. With `/ip ssh set password-authentication=yes`, the
+password login succeeds again with the key still installed.
+
+### S9. Group policy refusals are not auth failures
+
+Each user holds the installed `$KEY`, and a password is passed too:
+
+```bash
+centrs transfer 127.0.0.1 --via sftp --port $SSH_PORT --username $USER_NO_WRITE --password $PW_PASS --ssh-key $KEY --insecure upload $SRC centrs-391.txt --json
+```
+
+| User's group policy | Verb | `error.code` |
+| ------------------- | ---- | ------------ |
+| `ssh,ftp,read` (no `write`) | `upload`, `mkdir` | `routeros/command-failed`, `tips: []` |
+| `ssh,read,write` (no `ftp`) | `list` | `routeros/session-closed` (SSH disconnect reason 7) |
+| `ftp,read,write` (no `ssh`) | `list` | `auth/failed` |
+
+Only OpenSSH's pre-login `Permission denied (publickey…)` is `auth/failed`; a
+bare `Permission denied` after login is a policy refusal, so no password tips
+are attached. S7–S9 are covered by `test/integration/ssh-auth-policy.test.ts`.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar

package/docs/CLI.md

@@ -27,12 +27,12 @@ implemented flags live in each command's `commands/<name>/README.md`.
 Read RouterOS values through the shared core using the selected protocol.
 
 ```text
-Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]
+Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --host <host|url> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
-| `--via` | `<protocol>` | Pin the protocol selector. Defaults to `rest-api` for retrieve. |
+| `--via` | `<protocol>` | Pin the protocol selector. Defaults to `rest-api` for retrieve (`--sample` included), and to `native-api` under `--follow`. |
 | `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
 | `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
 | `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
@@ -41,17 +41,25 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 | `--default` |  | Select the reserved `__default__` record. |
 | `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
 | `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
-| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<target>` it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
 | `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
-| `--timeout` | &lt;ms\|5s&gt; | Operation timeout. REST currently rejects values above 60s. |
+| `--timeout` | &lt;ms\|5s&gt; | Per-request timeout, separate from --wait's overall deadline. REST currently rejects values above 60s. |
 | `--attribute` | `<name>` | Project one attribute. May be repeated. |
 | `--attributes` | `<a,b>` | Project a comma-separated attribute list. |
 | `--all-attributes` |  | Request the RouterOS detail/all-attributes shape. |
 | `--list-attributes / --list` |  | List inspect-derived attributes without running the data call. |
-| `--query / --filter` | `<expr>` | RouterOS-side row filter (maps to `.query`). Not implemented yet — returns `validation/not-implemented`. |
-| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
+| `--query / --filter` | `<expr>` | Row filter written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`), run on the router as an API query; repeatable, AND-ed. No `~` or `in`. |
+| `--follow` |  | Keep the menu's rows current over native-api `listen`: snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only. |
+| `--sample` | `<interval>` | Read the menu again every interval (with a unit, e.g. `5s`): one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api. |
+| `--wait` | `<deadline>` | Wait for a successful read or a condition until this overall deadline, with a unit (e.g. `2m`). Retries refused, closed, reset and timed-out connections and a down or unreachable host; other errors fail at once. One final envelope; single target. |
+| `--until` | `<expr>` | With --wait: succeed when any selected row matches this --query grammar predicate; repeatable, AND-ed. Returns the matching rows. Already true succeeds on the initial read. |
+| `--until-empty` |  | With --wait: succeed on a completed read with zero rows selected by --query. Silence and failed reads never satisfy it. |
+| `--sweep` | `<duration>` | `--follow` only: how often a membership sweep finds removals RouterOS does not send, including silent exits from --query. Needs a unit; default `10s`; `0` turns it off. |
+| `--count` | `<n>` | `--follow`: stop after N live changes (snapshot frames and `synced` do not count). `--sample`: stop after N samples. |
+| `--duration` | `<duration>` | `--follow`/`--sample`: stop after this wall-clock window (e.g. `30s`), counted from the end of validation. |
+| `--format` | &lt;text\|json\|yaml\|ndjson&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. `ndjson` prints each envelope as one compact line. |
 | `--json` |  | Shortcut for `--format json`. |
 | `--max-results` | `<bytes>` | Fail instead of printing output larger than the given byte budget. |
 | `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
@@ -65,7 +73,7 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 Run a RouterOS read or write command via native API, REST, or mac-telnet.
 
 ```text
-Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --group <name> <command> [flags]
+Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --host <host|url> [--] <command> [flags] | centrs execute --group <name> <command> [flags]
 ```
 
 | Flag | Value | Description |
@@ -79,7 +87,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--default` |  | Select the reserved `__default__` record. |
 | `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
 | `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
-| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<target>` it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
 | `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
@@ -102,7 +110,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 Structured RouterOS API passthrough (gh-api style) over REST or native API.
 
 ```text
-Usage: centrs api <router> <endpoint> [flags]
+Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <endpoint> [flags]
 ```
 
 | Flag | Value | Description |
@@ -111,13 +119,13 @@ Usage: centrs api <router> <endpoint> [flags]
 | `-f / --field` | `<key=value>` | Body field, repeatable; assembled into the JSON body (verbatim string values). |
 | `-d / --data` | `<json>` | Raw JSON request body. Conflicts with `-f` / `--input`. |
 | `--input` | &lt;file\|-&gt; | Read the raw JSON body from a file or stdin (`-`). |
-| `--query / --filter` | `<expr>` | RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name. |
-| `--raw-query` | `<word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions. |
+| `--query / --filter` | `<expr>` | Row filter written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`), sent as query words; repeatable, AND-ed. No `~` or `in`. |
+| `--raw-query` | `<word>` | Verbatim RouterOS query word (repeatable), e.g. has-property `name`, absence `-name`, or stack ops `#\|` `#&` `#!`. |
 | `--attribute / --proplist` | `<a,b>` | Property projection → `.proplist`. |
 | `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`. |
 | `--yes` |  | Confirm a mutating (non-read) request in non-interactive runs. |
-| `--stream / --listen` |  | Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope. |
-| `--count` | `<n>` | Stop a `--stream` after N change frames. |
+| `--stream` |  | Stream the command's native replies (`!re` rows and `!empty`) as NDJSON, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it. |
+| `--count` | `<n>` | Stop a `--stream` after N `!re` rows; `!empty` replies do not count (not the device count= argument). |
 | `--duration` | `<dur>` | Stop a `--stream` after this wall-clock window (e.g. `5s`). |
 | `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
 | `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
@@ -128,7 +136,7 @@ Usage: centrs api <router> <endpoint> [flags]
 | `--default` |  | Select the reserved `__default__` record. |
 | `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
 | `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
-| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<router>` it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username. Falls back to `CENTRS_USERNAME`. |
 | `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
@@ -138,7 +146,7 @@ Usage: centrs api <router> <endpoint> [flags]
 | `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
 | `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
 | `--validate / --no-validate` |  | Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted). |
-| `--format` | &lt;json\|yaml\|text&gt; | Output format. Defaults to json for api; `CENTRS_FORMAT` overrides. |
+| `--format` | &lt;json\|ndjson\|yaml\|text&gt; | Output format. Defaults to json for api; `CENTRS_FORMAT` overrides. |
 | `--json` |  | Shortcut for `--format json`. |
 | `--verbose` |  | Include additional context in text output. |
 
@@ -147,7 +155,7 @@ Usage: centrs api <router> <endpoint> [flags]
 Copy files to/from a RouterOS device and manage device files (rest/native/sftp).
 
 ```text
-Usage: centrs transfer <router> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]
+Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]
 ```
 
 | Flag | Value | Description |
@@ -155,7 +163,7 @@ Usage: centrs transfer <router> upload <local> [remote] | download <remote> [loc
 | `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction. |
 | `--ssh-key` | `<path>` | sftp only: explicit private-key path. Falls back to CENTRS_SSH_KEY / the ssh-agent. |
 | `--insecure` |  | Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies. |
-| `--force / --overwrite` |  | Replace an existing destination. Default refuses it. |
+| `--force / --overwrite` |  | Skip the existing-destination check on the device for `upload`/`mkdir`/`copy` (`upload` then overwrites). Default refuses an existing target. `download` always replaces the local file. |
 | `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
 | `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
 | `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
@@ -169,7 +177,7 @@ Usage: centrs transfer <router> upload <local> [remote] | download <remote> [loc
 | `--verify / --no-verify` | &lt;size\|checksum\|off&gt; | Post-transfer integrity check. Default size; `--no-verify` skips. |
 | `--type` | &lt;file\|directory\|disk\|package&gt; | list filter: RouterOS /file row type. |
 | `--name` | `<glob>` | list filter: file-name glob. |
-| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<router>` before the verb it is the target (no CDB lookup); with one it overrides the resolved host. |
 | `--port` | `<port>` | Override the resolved management port. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
 | `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |
@@ -187,13 +195,13 @@ Usage: centrs transfer <router> upload <local> [remote] | download <remote> [loc
 Open an interactive RouterOS console (ssh or mac-telnet).
 
 ```text
-Usage: centrs terminal <router> [flags]
+Usage: centrs terminal <router> [flags] | centrs terminal --host <host> [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
 | `--via` | `<method>` | Transport: `ssh` (host target, default) or `mac-telnet` (MAC target, default for a MAC). rest/native have no terminal capability. |
-| `--host` | `<host>` | Override the target host (ssh) / UDP delivery host (mac-telnet, default L2 broadcast). |
+| `--host` | `<host>` | ssh: the host to dial (the target when no `<router>` is given; no CDB lookup). mac-telnet: the UDP delivery host (default L2 broadcast). |
 | `--port` | `<port>` | Override the port: ssh default 22, mac-telnet default 20561. |
 | `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
 | `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |

package/docs/CONSTITUTION.md

@@ -63,6 +63,22 @@ an ABSTENTION and passes through to the device stage; only a `fail` rejects.
 that was skipped and why. A reader must always be able to tell "the device
 accepted it" from "the device was never asked".
 
+`meta.validation.result` is a verdict, so it is present only when the gate
+produced one. `failed` means the gate refused the request. A failure after the
+gate passed keeps `passed`. When something stopped the gate before it gave a
+verdict (a `transport/*` or `auth/*` failure, a device error that is not a
+gate answer, or a refusal before the gate ran), `result` and the
+`syntax`/`semantic` summaries are absent. Each stage the gate did not reach is
+then `skipped` with `reason: "not reached: <error.code>"` (GH#435). On an
+`execute` rejection, `syntax: true` survives only for a name-level refusal (an
+unknown attribute in a structured command). Any other device or offline
+refusal is `syntax: false`, and `semantic` is then absent (`not-applicable` for
+script input), because the name-level check was never asked. `api`'s
+structured requests run no `:parse`, so their `syntax: false` means "not run",
+even on success. That overload is part of the review below. This is an
+interim shape: the validation meta across commands is reviewed again with live
+`explain` (#236).
+
 `--validate=false` disables **both** stages — one flag, one meaning. A bypass
 that covered only the device stage would leave a caller stranded behind a
 stage-1 defect with no escape at all, and the analyzer is demonstrably wrong in
@@ -278,7 +294,10 @@ token cannot spoof them), AND-combined across repeats. A call is in **fan-out
 mode** when any selector flag is present **or** more than one positional target is
 given; a plain single-positional call stays single-target. The union is
 **de-duped by CDB record index** (ad-hoc literal targets by host) and run through
-the same per-target pipeline.
+the same per-target pipeline. With no `<router>` positional and no selector, the
+`--host` **flag** stands in for the target: a single target with no CDB lookup,
+so no record credential applies. The env var `CENTRS_HOST` never changes how
+positionals split. Each command README states where its `<router>` slot ends.
 
 Fan-out output is the locked **`FanoutData`** envelope: `data = { summary, targets[]
 }`, where the outer `ok` reports **orchestration** success and a per-target failure
@@ -292,9 +311,9 @@ A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across
 selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing
 the error names the blast radius (how many routers). The separate **`--force`**
 gate is scoped to destructive **`devices` CDB mutations** (e.g. `devices remove`
-across a group), not RouterOS writes. `terminal` and single-session `stream` /
-`api --stream` are not fan-out surfaces and reject N>1 with
-`usage/fanout-not-supported`; `api --raw` is rejected in fan-out mode with
+across a group), not RouterOS writes. `terminal`, `api --stream`,
+`retrieve --follow` and `retrieve --sample` are single-session, not fan-out
+surfaces, and reject N>1 with `usage/fanout-not-supported`; `api --raw` is rejected in fan-out mode with
 `usage/conflicting-flags` (it strips the per-target envelope).
 
 `--where` filters *which devices* by CDB-stored facts; keep it distinct from
@@ -372,8 +391,8 @@ Per-operation preferences, downgrade order in parens:
 
 | Operation | Preferred | Downgrade order |
 | --------- | --------- | --------------- |
-| retrieve  | rest-api, native-api; snmp for OID/MIB reads (future) | rest-api, native-api |
-| api       | rest-api, native-api; `--stream` follow native-api only | rest-api, native-api (no silent downgrade) |
+| retrieve  | rest-api, native-api (`--sample` too); snmp for OID/MIB reads (future); `--follow` native-api only | rest-api, native-api (`--follow`: no downgrade) |
+| api       | rest-api, native-api; `--stream` and `/listen` native-api only | rest-api, native-api (no silent downgrade) |
 | execute   | native-api → rest-api → mac-telnet | native-api, rest-api, mac-telnet, ssh, romon, winbox-terminal |
 | terminal  | ssh | mac-telnet (L2 only when ssh fails or MAC given) |
 | transfer  | size/direction-aware: rest-api/native-api for ≤60 KB writes & all reads (chunked), sftp for large uploads | sftp ⇄ rest/native by size; scp · fetch · ftp explicit-only |
@@ -400,7 +419,7 @@ Rules:
 - **`measure` (btest) is explicit-only** — never in the auto-select/downgrade
   chain, never a substitute, and no other command rides it.
 - Per-command selection **depth** lives in the command READMEs: `api`'s
-  `--stream` follow/NDJSON contract and the REST-cannot-follow constraint
+  literal `--stream`/NDJSON contract and the REST-cannot-follow constraint
   (`commands/api/README.md`), `transfer`'s size/direction-aware method
   selection and the explicit-only `scp`/`ftp`/`fetch`
   (`commands/transfer/README.md`), SNMP's MIB-cache
@@ -432,9 +451,10 @@ ecosystem norm* rather than one literal value:
 
 SSH identity selection: the `sshKey` setting (`--ssh-key`/`CENTRS_SSH_KEY`/CDB
 `ssh-key=`) carries a private-key **path only** — never key material; when unset,
-the host SSH agent / `~/.ssh/config` is used. RouterOS refuses password login once
-an SSH key is set for a user (`password-authentication=yes-if-no-key`, the
-default), so key auth is the normal sftp path.
+the host SSH agent / `~/.ssh/config` is used. Batch SSH clients (sftp, `execute
+--via ssh`) run `BatchMode=yes` and never send a password, so key auth is the
+only batch path. Separately, RouterOS refuses SSH password login once a user has
+a key (`/ip/ssh password-authentication=yes-if-no-key`, the default).
 
 ## Done definition
 

package/docs/MATRIX.md

@@ -60,6 +60,33 @@ and implementation sequencing in the linked issues.
   structured operation surface is `api`.
 - `api --stream` absorbs the former `stream`/`tail` surface; native-api stream
   details are in `commands/api/README.md` and `src/protocols/native-api.ts`.
+  #399 extends it to incremental command replies and truthful terminal outcomes.
+  #402 makes it literal: following is the `<menu>/listen` endpoint, every wire
+  reply (`!empty` included) is a line, and what RouterOS will not report
+  (filtered or projected change feeds) is a tip, not a rewrite.
+- `retrieve --follow` (#396) is the stateful follow over native-api: A1
+  bootstrap, `synced`, live frames, and an `.id` sweep for removals RouterOS
+  does not send. Single-target; `CHR-passed` by
+  `test/integration/retrieve-follow.test.ts` (FL1–FL9, 7.23.7 and 7.24.5).
+  Filtered follow (#397) uses device-evaluated changed-id membership, guarded
+  against stale replies; `test/integration/retrieve-filtered-follow.test.ts`
+  covers FQ1–FQ5 on 7.23.8 and 7.24.5, including projected predicates, both membership directions,
+  minimal deletes, silent predicate exits and bootstrap/live churn.
+- `retrieve --sample <interval>` repeats the one-shot read on a timer, one
+  line per complete read, over rest-api or native-api: the answer for counters
+  and state `listen` never reports. RouterOS's `print interval=` was measured
+  and not used (no end-of-tick marker). Single-target; `CHR-passed` by
+  `test/integration/retrieve-sample.test.ts` (SA1–SA6, 7.23.7 and 7.24.5).
+- `retrieve --query` (#397) filters rows on the router with the `print where`
+  grammar, compiled to the API query; `api --query` shares it. One-shot,
+  `--sample` and fan-out; `CHR-passed` by
+  `test/integration/retrieve-query.test.ts` (QY1–QY7, QA1–QA2, 7.23.7 and
+  7.24.5), whose QY1 checks the rows against RouterOS's own `find where`.
+- `retrieve --wait` / `--until` / `--until-empty` (#364) return one bounded
+  readiness/condition result over REST or native-api, with elapsed time,
+  attempts and completed observations. `test/integration/retrieve-wait.test.ts`
+  covers WT1–WT7 on 7.23.8 and 7.24.5, including real reboot readiness and a
+  two-CHR OSPF adjacency.
 - `discover / mndp` is grounded by `commands/discover/README.md`,
   `src/data/mndp.ts`, `src/data/mndp-cache.ts`, and
   `test/integration/discover.test.ts`.
@@ -150,7 +177,17 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**Tightening validation as a whole** is the selected track, in the three-step
+**First: the native-api / NDJSON line** (maintainer decision on
+[#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
+field poll with `sleep` where a native follow would answer. In order:
+(1) done: #402, literal `api --stream` with `!empty` frames and
+`--format ndjson`; (2) done: `retrieve --follow` (#396, unfiltered);
+(3) done: `retrieve --sample`; (4) #397: one-shot `retrieve --query` done,
+filtered `--follow` done; #364 (`--wait`/`--until`, same grammar) done;
+(5) #398 and #401. Each slice's contract lives in its command
+README. Live `explain` (below) resumes after this line.
+
+**Tightening validation as a whole** is the next track, in the three-step
 order agreed on [#236](https://github.com/tikoci/centrs/issues/236):
 
 1. **Done** — fix the offline false rejects so the analyzer can be trusted as a

package/docs/errors/README.md

@@ -59,10 +59,12 @@ Codes are slash-namespaced `family/slug`. The families and where they originate:
 - `transport/*` — connection, TLS, DNS, and timeout plumbing.
 - `usage/*` — how a command was invoked (arity, conflicting flags, confirmation).
 - `validation/*` — the canonicalize → validate gate (`:parse` + `/console/inspect`).
+- `wait/*` — readiness/condition deadlines and cancellation (`retrieveWait`).
 
 The hand-enriched pages (richer trigger strings and remediation) currently are
 the `routeros/*` set produced by `src/core/routeros-errors.ts` and the
-`target/*` MAC-resolution pages; the rest are generated stubs to be enriched as
+`target/*` MAC-resolution pages and `wait/*` deadline/cancellation pages;
+the rest are generated stubs to be enriched as
 each code is grounded.
 
 ## RouterOS-fault mapping (`routeros/*`)

package/docs/errors/input/invalid-query.md

@@ -0,0 +1,36 @@
+# `input/invalid-query`
+
+A `--query` expression does not parse as a `print where` condition.
+
+## When it happens
+
+`retrieve --query` and `api --query` take what you would write after
+`print where`: `name=ether1`, `mtu>=1500 and !dynamic`,
+`(type=ether or type=vlan)`. centrs parses it before anything is sent, then
+runs it on the router as an API query. The error's `context.offset` points at
+the problem in `context.query`.
+
+centrs also refuses spellings that RouterOS reads differently from how they
+look, or does not accept:
+
+- `!name=value` is `(!name)=value` to RouterOS, which matches by accident.
+  Write `!(name=value)` or `name!=value`.
+- `not` is not a RouterOS operator. Use `!`.
+- Conditions separated only by a space. Join them with `and` or `or`.
+- An unquoted `=` inside a value. RouterOS reads `comment=x=yes` as
+  `(comment=x)=yes`, and `comment=x!=y` matches nothing. Quote it:
+  `comment="x=yes"`.
+- A space after the operator (`comment= x`), which RouterOS rejects too.
+- A string escape RouterOS does not have, such as lowercase hex `\0a` (hex is
+  two uppercase digits; `\ff` is `\f` then `f`), or a hex byte above `\7F`,
+  which a UTF-8 query value cannot carry.
+
+A bare name (`disabled`, `comment`) means what it means after `where`: `yes`
+for a boolean and "is set" for anything else. Only the router knows which a
+property is, so with `--validate=false` a bare name fails here too.
+
+## Fix
+
+- Quote values that contain spaces: `comment="uplink a"`.
+- Close every `(` and `"`.
+- Write a boolean out as `disabled=yes` if validation is off.

package/docs/errors/input/local-destination.md

@@ -0,0 +1,20 @@
+# `input/local-destination`
+
+A local download destination cannot be written (missing parent directory, a directory, or no permission).
+
+`transfer download` checks the local destination before it reads anything
+from the device. The parent directory must already exist, because centrs does
+not create directories, and the destination itself must not be a directory.
+A path that cannot be checked at all (no permission on a directory along the
+way, a file used as a directory, a symlink loop) fails the same way. A write
+that still fails afterwards (no permission, the directory removed
+mid-transfer) reports this code too, with the operating-system error as the
+cause.
+
+## Fix
+
+- Create the parent directory first: `mkdir -p DIR`, then retry the download.
+- Name a file, not a directory: `download fw.rsc ./backups/fw.rsc`, not
+  `download fw.rsc ./backups/`.
+- Pass `-` as the local path to write the bytes to stdout instead.
+- For a fan-out download, `--out-dir` must be an existing directory.

package/docs/errors/input/unsupported-query.md

@@ -0,0 +1,19 @@
+# `input/unsupported-query`
+
+A `--query` uses something the RouterOS API query cannot run.
+
+## When it happens
+
+`--query` runs on the router as an API query (native `?` words, REST
+`.query`), and that query language has no regex (`~`), no prefix membership
+(`in`), and no script evaluation. A value starting with `$`, `[` or `{`, or a
+`$` inside a quoted value, would need RouterOS's script evaluator. centrs
+refuses these rather than filtering some other way and calling it a router
+filter.
+
+## Fix
+
+- Read the rows without that condition and filter them yourself.
+- Or run the console form, which returns console text rather than rows:
+  `centrs execute <router> '/ip/address/print where interface~"^ether"'`.
+- For a literal `$` in a quoted value, escape it as `\$`.

package/docs/errors/internal/byte-string.md

@@ -0,0 +1,13 @@
+# `internal/byte-string`
+
+A binary RouterOS word held a character that is not a byte.
+
+## Fix
+
+This is a centrs bug; report it with the command that triggered it.
+
+`transfer` moves `/file` contents over REST and native-api as byte strings,
+one string code unit per byte (#404). A code unit above U+00FF has no single
+byte, so centrs refuses the request before it reaches the router rather than
+silently keeping the low byte. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error contract.

package/docs/errors/settings/invalid-timeout.md

@@ -18,6 +18,12 @@ Like the other typed-value codes here, this isn't `settings`-exclusive:
 flag, so the same failure shape shows up anywhere a duration string is
 resolved, not just through `settings set`.
 
+`retrieve --sample <interval>` and `retrieve --follow --sweep <period>` are
+stricter: the value needs a unit (`5s`, `500ms`, `1m`). `--sample` must be
+above zero; `--sweep 0` is allowed and turns the sweep off. A bare `--sample 5` fails here
+because RouterOS reads `interval=5` as five seconds while centrs reads a bare
+number as milliseconds; pass the unit you mean.
+
 One write detail worth knowing: `settings set timeout` writes the
 **canonical parsed milliseconds**, not the raw suffixed string you typed —
 `centrs settings set timeout 5s` writes `CENTRS_TIMEOUT=5000` to

package/docs/errors/transport/stream-overflow.md

@@ -0,0 +1,21 @@
+# `transport/stream-overflow`
+
+More stream replies were waiting unread than the buffer allows, so centrs ended
+the stream rather than drop any.
+
+## When it happens
+
+`centrs retrieve <router> <menu> --follow` buffers changes between RouterOS and
+the reader, up to 50,000. The buffer fills when the reader stops reading (a
+stalled pipe), or when a burst arrives while a long snapshot is still loading.
+centrs never drops a change silently, because the state you hold would then
+look current while being wrong. It ends the follow with this error instead, as
+the failed summary (`stopReason: "transport-error"`).
+
+## Fix
+
+- The state you built from the lines is stale. Follow again: the new follow
+  starts with a fresh snapshot.
+- Read lines as they arrive. Don't buffer the whole output before processing.
+- For a very busy menu, follow a narrower menu (for example `/interface/vlan`
+  instead of `/interface`).

package/docs/errors/usage/removed-flag.md

@@ -0,0 +1,20 @@
+# `usage/removed-flag`
+
+A flag or request field was removed; the error names its replacement.
+
+## Fix
+
+Run the replacement printed in the error's remediation.
+
+`api --listen` (and the library's `ApiRequest.listen`) is the current case
+(#402). It meant "stream the replies" and also turned a GET of a menu into a
+change subscription. `api` now sends the command as typed:
+
+- To follow changes, request the menu's `listen`:
+  `centrs api <router> ip/address/listen`. A `/listen` endpoint implies
+  `--stream` and native-api.
+- To stream any other command's replies, use `--stream`
+  (`ApiRequest.stream` / `apiStream()` in the library).
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract.