@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/commands/transfer/README.md

@@ -118,6 +118,15 @@ past 60 KB) rather than quietly switching to sftp. `scp`, `fetch`, and `ftp` are
 explicit-only; `ftp` additionally requires `ALLOW_UNSAFE_PROTOCOLS=ftp` because
 it is cleartext.
 
+**File contents are bytes on `rest`/`native`.** RouterOS carries `/file`
+contents as raw bytes on both wires — REST puts bytes 0x80–0xff unescaped in the
+JSON string, so the body is not UTF-8 — and stores the UTF-8 encoding of every
+JSON code point it receives (CHR 7.23.7 + 7.24.5, #404). So the `/file`
+`get`/`read`/`set` calls run in the adapters' `binary` mode: each byte is one
+string code unit (Node `Buffer` latin1 — not WHATWG `TextDecoder("latin1")`,
+which is windows-1252), and a file name in those calls is sent as its UTF-8
+bytes. Every other command stays UTF-8 text.
+
 > Future methods documented so callers know the capability exists, behind an
 > explicit `--via`: `/system/smb` (not enabled by default) and `rose-storage`
 > (`rsync`/`nfs`/`nvme-over-tcp`/`iscsi`, needs `rose-storage.npk`).
@@ -158,16 +167,25 @@ Implemented flags are generated from the CLI metadata into
 [`docs/CLI.md` → transfer](../../docs/CLI.md#transfer); this file does not
 duplicate that table. Behavior notes the generated reference cannot carry:
 
-- `--force`/`--overwrite` applies to the destination side (the local file for
-  `download`, the remote file for `upload`); the default refuses an existing
-  target with `usage/target-exists` (see *Validation*).
+- `--force`/`--overwrite` skips the existing-**device**-destination check of
+  `upload`, `mkdir` and `copy`, which by default refuse an existing target
+  with `usage/target-exists` (see *Validation*). `upload` then overwrites the
+  file; `mkdir` and `copy` still run as RouterOS's own `/file` commands.
+  `download` replaces an existing **local** file without `--force`, as
+  `curl -o` and `scp` do (#406). The local file is written only after the
+  whole remote read completes and, under the default `--verify size`, matches
+  the device's size, so a failed read or a size mismatch leaves an existing
+  file untouched. The write itself is not atomic: a local write that fails
+  part-way can leave the file truncated.
 - `--verify` details and the sftp size caveat are in *Integrity*.
 - `--timeout`: `rest`/`native` are per-request ≤ 60000 ms (a chunked read is
   many short requests, each capped); `sftp` accepts longer for a single large
   transfer.
 - `--ssh-key` is the same `sshKey` setting as `terminal`/`execute`
   (`CENTRS_SSH_KEY`, CDB `ssh-key=`); when unset, the ssh-agent /
-  `~/.ssh/config` is used. See `commands/terminal/README.md`.
+  `~/.ssh/config` is used. A selected key adds `IdentitiesOnly=yes` to exclude
+  unrelated agent keys; explicit OpenSSH `IdentityFile` entries still apply.
+  See `commands/terminal/README.md`.
 - `--insecure` adds a `transport/insecure-trust` warning (constitution:
   transport trust).
 - `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
@@ -201,6 +219,12 @@ single-target. On the top-level `upload`/`download` alias the verb is fixed, so
 its positionals are paths — positional fan-out targets are not expressible there;
 fan-out comes from a selector flag.
 
+In the verb form, the `--host` **flag** with no positional before the verb is the
+single target (`transfer --host 192.0.2.10 list`), with no CDB lookup.
+`CENTRS_HOST` never stands in for `<router>`. The `upload`/`download` aliases
+still read their first positional as the target, since their optional second
+path makes a count ambiguous.
+
 Two transfer-specific rules:
 
 - **`download` fan-out requires `--out-dir <dir>`.** N devices cannot share one
@@ -261,11 +285,15 @@ success, per-target results live in `data.targets`.
 ## Validation
 
 `transfer` validates what it can locally first — conflicting flags
-(`usage/conflicting-flags`), a missing local source on `upload`, a `--via rest`
+(`usage/conflicting-flags`), a missing local source on `upload`, a `download`
+destination whose parent directory is missing or that is itself a directory
+(`input/local-destination`; centrs does not create directories), a `--via rest`
 upload that exceeds 60 KB (`transport/unsupported-operation`). The
-**refuse-overwrite** guard is a real precondition probe, not a local check:
-unless `--force`, centrs `stat`s the destination (SFTP `stat`, or `/file/print`
-for the REST family) and fails with `usage/target-exists` if it is already there.
+**refuse-overwrite** guard protects device files and is a real precondition
+probe, not a local check: unless `--force`, centrs `stat`s the device
+destination (SFTP `stat`, or `/file/print` for the REST family) and fails with
+`usage/target-exists` if it is already there. A `download` overwrites its local
+destination (see *Flags*).
 This is the "validate before write" gate applied to files — see constitution:
 validation is the product.
 
@@ -274,6 +302,20 @@ gate as in `retrieve` / `execute`; RouterOS's own menu errors (missing remote
 file, permission denied) map to `routeros/*`, and SFTP/SCP/fetch errors map to
 `transport/*` and `auth/*`.
 
+A failure **after** target resolution keeps what resolution found: the error
+envelope carries the resolved `meta.target` (host, port, identity, sources),
+`meta.via`, the setting sources in `meta.settings`, and `meta.operation`
+(including `auth.username` / `auth.passwordProvided` — provenance, never the
+secret). This holds for single-target runs and for each fan-out member. A
+failure before resolution (bad shape, unknown target) keeps only
+`meta.target.input`. An sftp `auth/failed` with a resolved password adds
+`tip/sftp-password-not-used`, plus `tip/transfer-password-transport` unless the
+upload is known to exceed the rest/native write cap — advice only, never a
+fallback across a pinned `--via` (examples S7–S9). Only OpenSSH's pre-login
+refusal is `auth/failed`: a user whose group lacks `write` logs in and gets
+`routeros/command-failed` for upload/mkdir/remove, and one lacking `ftp` gets
+`routeros/session-closed` (SSH disconnect reason 7) — example S9.
+
 **Error codes reuse existing namespaces — `transfer` adds no namespace of its
 own.** Everything specific to transfer fits `usage/*` (`usage/target-exists`),
 `transport/*` (`transport/unsupported-operation` for the REST 60 KB write cap,
@@ -342,7 +384,11 @@ done rule. The first coded pass targets `rest`/`native` (no SSH dependency);
   / [User](https://help.mikrotik.com/docs/spaces/ROS/pages/8978504/User) pages:
   **by default** a user cannot password-auth over SSH once an SSH key is set for it
   (`/ip/ssh password-authentication=yes-if-no-key`, the default — settable to
-  `yes` to allow both), so key auth is the normal path; and `strong-crypto=yes`
+  `yes` to allow both; CHR-grounded on 7.23.8 and 7.24.5 by
+  `test/integration/ssh-auth-policy.test.ts`). centrs's batch sftp runs
+  `BatchMode=yes` and never sends a password at all — it authenticates with the
+  selected key or the host OpenSSH configuration/agent — so key auth is the
+  only sftp path regardless of that policy; and `strong-crypto=yes`
   disables ssh-rsa/SHA1, so the client must offer ed25519 / rsa-sha2-256 (the host
   OpenSSH negotiates this natively). The SSH file path is the SFTP **subsystem**
   (a real file protocol), not exec-driven scp; on-device `copy`

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. |
@@ -234,7 +242,7 @@ Usage: centrs explain '<input>' [flags]
 Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
 
 ```text
-Usage: centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]
+Usage: centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]
 ```
 
 | Flag | Value | Description |

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
@@ -84,8 +100,10 @@ validator, with CHR evidence.
   `expected`. Rejection forms are `(evl bad parameter <name> (line N column M)
   /path)`, `(<%% bad command name <name> (line N column M) …)`, and the
   line-anchored `expected … (line N column M)` (spellings: `expected end of
-  command`, `expected command name`, `expected input value`) / `syntax error
-  (line N column M)`. That text rides the **HTTP-200 `ret` value** (REST,
+  command`, `expected command name`, `expected input value`), `missing … (line
+  N column M)` (`missing closing brace`, `missing value for where`; GH#375) and
+  `syntax error (line N column M)`. Every bare form is anchored at a line start
+  with the position suffix, because an accepted return can echo those words. That text rides the **HTTP-200 `ret` value** (REST,
   `as-string`), the native `as-string` `ret`, and the console's printed output
   alike — so a single `:put [:parse ...]` covers both the syntax and the
   **unknown-attribute** gate on every transport. centrs sends `as-string` and now
@@ -276,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
@@ -290,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
@@ -370,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 |
@@ -398,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
@@ -430,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
 
@@ -535,8 +557,10 @@ as bibliography entries in `GLOSSARY.txt` — e.g. `netmiko`,
 ### Canonicalizer ownership
 
 centrs owns the **script-vs-structured execution gate** — the load-bearing
-discriminator for which validation runs and whether the write-confirmation prompt
-fires; widening what counts as `structured` is a product regression. The shared,
+discriminator for validation and transport shape; widening what counts as
+`structured` is a product regression. Write confirmation is a separate,
+fail-closed safety predicate over the original CLI string: falling back to raw
+script transport must never turn a write into a read. The shared,
 pure command canonicalizer that `rosetta` / `lsp-routeros-ts` publish is for
 canonicalization only, never the structured-mode predicate. The gate contract,
 its pinning test, and the parser-vendoring preconditions are documented in
@@ -546,5 +570,6 @@ its pinning test, and the parser-vendoring preconditions are documented in
 Richer schema-free analysis must distinguish **ambiguous** (multiple plausible
 readings) from **unknown** (no safe reading) and abstain in both cases rather than
 inventing a command, path, symbol class, or transport mapping. These explain-only
-verdicts never widen or reinterpret the execution gate's `mode` or `writeShaped`
-decision.
+verdicts never widen or reinterpret the execution gate's `mode`. The execution
+safety predicate remains deliberately conservative and independent of richer
+explain-only inference.

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/*`)