@tikoci/centrs 0.1.7 → 0.1.8

package/commands/retrieve/examples.md

@@ -139,6 +139,9 @@ centrs retrieve $R /system/resource --attribute bogus --username $U --password $
 centrs retrieve $R /system/resource --username wrong --password wrong --json
 ```
 
+`meta.validation` has no `result`. Its one stage is `device: skipped` with
+`reason: "not reached: transport/auth-failed"` (GH#435).
+
 ### 13. Unreachable host
 
 `transport/connection-refused` (not the more general `transport/network`).
@@ -147,6 +150,10 @@ centrs retrieve $R /system/resource --username wrong --password wrong --json
 centrs retrieve 127.0.0.1:1 /system/resource --username $U --password $P --json
 ```
 
+The envelope still carries the resolved endpoint: `meta.via="rest-api"`,
+`meta.target.host`/`port`/`baseUrl`, and `meta.settings` with the source of
+each setting (#433).
+
 ### 14. REST timeout ceiling
 
 `--timeout 70000` against `--via rest-api` is rejected up front with
@@ -174,6 +181,41 @@ Call succeeds with a `cdb/password-not-needed` warning in `meta.warnings`.
 centrs retrieve $R /system/resource --cdb-file $CDB --cdb-password ignored --json
 ```
 
+### 16b. A refused transport still names what resolution found (#433)
+
+`$CLOSED` is a loopback port with nothing listening.
+
+```bash
+centrs retrieve $R /system/resource --cdb-file $CDB --port $CLOSED --json
+```
+
+Exit 1, `transport/connection-refused`. `meta.via="rest-api"`, and
+`meta.target` has the CDB record's host, `port=$CLOSED`, `recordIndex=0` and
+`source.kind="cdb"`. `meta.settings.port={kind:"cli",key:"port"}` and
+`meta.settings.username`/`password` have `kind:"cdb"`.
+`meta.operation.auth.passwordProvided=true`. The password itself appears
+nowhere. `meta.validation` has no `result`; its device stage is `skipped` with
+`reason: "not reached: transport/connection-refused"` (GH#435).
+
+### 16c. The gate passed, then a later step failed (GH#435)
+
+```bash
+centrs retrieve $R /system/resource --max-results 10 --username $U --password $P --json
+```
+
+Exit 1, `input/max-results-exceeded`. The read was validated and ran, and the
+answer was larger than the byte budget. `meta.validation.result="passed"`,
+because the gate did pass.
+
+### H1. `--host` stands in for `<target>` (#428)
+
+```bash
+centrs retrieve --host $R /system/identity --username $U --password $P --json
+```
+
+`ok: true`, with `data.name` the router's identity. The lone positional is the
+path, and there is no CDB lookup.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar
@@ -245,11 +287,13 @@ outputs round-trip to the same JS value.
 centrs retrieve $R /system/resource --format yaml --username $U --password $P
 ```
 
-## Out-of-scope (must surface as not-implemented)
+## Row filters
 
-### 18. --query
+### 18. --query with a regex
 
-Returns `validation/not-implemented` immediately.
+A regex has no RouterOS API query word, so it fails
+`input/unsupported-query` before anything is read. The full `--query`
+contract is in the **Query** section below.
 
 ```bash
 centrs retrieve $R /ip/address --query 'address~"192"' --username $U --password $P --json
@@ -257,10 +301,10 @@ centrs retrieve $R /ip/address --query 'address~"192"' --username $U --password
 
 ### 19. --filter
 
-Same handling as `--query`.
+`--filter` is `--query`: the router filters, and every returned row matches.
 
 ```bash
-centrs retrieve $R /ip/address --filter 'disabled=no' --username $U --password $P --json
+centrs retrieve $R /interface --filter 'type=ether' --username $U --password $P --json
 ```
 
 ## native-api (`--via native-api`)
@@ -371,3 +415,376 @@ centrs retrieve --quickchr $NAME /system/resource --json
 Envelope: `ok: true`, `meta.via=rest-api` (normal default; quickchr does not
 change protocol selection), `meta.target.source.kind=provider`,
 `meta.target.identity=$NAME`, no `recordIndex` (the CDB was never consulted).
+
+## Follow (`--follow`, #396)
+
+Contract: [README → Follow](README.md#follow---follow). `$A`/`$API_PORT` as in
+the native-api section; `--via` is left unset because `--follow` infers
+native-api. Covered by `test/integration/retrieve-follow.test.ts`; the engine
+orderings a CHR cannot produce on demand (A1 replay, the sweep's
+changed-since-sent exclusion, overflow) are pinned in
+`test/unit/retrieve-follow.test.ts`.
+
+### FL1. Bootstrap: snapshot frames, one `synced`, a summary
+
+```bash
+centrs retrieve $A /ip/address --follow --duration 3s --port $API_PORT --username $U --password $P --json
+```
+
+Every line parses as an envelope. Frames before `synced` have
+`phase: "snapshot"` and `source: "print"`; exactly one `synced`; the last line
+is the summary with `stopReason: "duration-elapsed"`, `synced: true`,
+`changes: 0`. Every frame carries `meta.operation.stream.id`.
+
+### FL2. A live change, and `--count` that ignores the snapshot
+
+```bash
+centrs retrieve $A /ip/address --follow --count 1 --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+After `synced`, add an address. The follow ends with `stopReason:
+"count-reached"` after exactly one `live` `upsert` frame from `listen`, however
+many snapshot frames came first.
+
+### FL3. A removal RouterOS sends
+
+```bash
+centrs retrieve $A /ip/address --follow --sweep 0 --count 1 --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+After `synced`, remove an address that existed before the follow. One `live`
+`removed` frame, `source: "listen"`, `data: null`. `--sweep 0` keeps the sweep
+out of the race, and its `tip/follow-sweep-off` notice is the first line.
+
+### FL4. A removal RouterOS does not send (view menu → sweep)
+
+```bash
+centrs retrieve $A /interface/bridge --follow --sweep 1s --duration 15s --port $API_PORT --username $U --password $P --json
+```
+
+Create a bridge after `synced`, then remove it. Its `upsert` comes from
+`listen`; its removal comes from the sweep (`source: "sweep"`), because
+`/interface/<type>` never sends `.dead`.
+
+### FL5. `--attributes` projects `data`, identity stays in meta
+
+```bash
+centrs retrieve $A /ip/address --follow --attributes address --duration 3s --port $API_PORT --username $U --password $P --json
+```
+
+Every snapshot frame's `data` has only `address`; `meta.operation.stream.id`
+still names the row.
+
+### FL6. A menu RouterOS cannot follow
+
+```bash
+centrs retrieve $A /system/resource --follow --port $API_PORT --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `validation/not-followable`, exit 1. No summary.
+
+### FL7. A pinned REST transport
+
+```bash
+centrs retrieve $R /ip/address --via rest-api --follow --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `transport/capability-unsupported`. No polling
+fallback.
+
+### FL8. NDJSON is readable before the process exits; Ctrl-C ends it cleanly
+
+```bash
+centrs retrieve $A /ip/address --follow --format ndjson --port $API_PORT --username $U --password $P
+```
+
+Run as a subprocess. The first frame line parses while the process is still
+running; after `SIGINT` the last line is a successful summary with
+`stopReason: "interrupted"`, and the exit code is 0.
+
+### FL9. A1 and the sweep under churn (regression harness)
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --follow --sweep 200ms --duration 8s --port $API_PORT --username $U --password $P --json
+```
+
+A second connection updates, adds and removes address-list rows while the
+follow bootstraps and runs. Applying every line in order must equal a fresh
+`print` taken after the churn settles: no stale value, no resurrected row, no
+row removed by a sweep while it still exists. #396 round 3 measured 0 errors
+over about 14.7k writes with this bootstrap; arrival-order merging failed the
+same harness.
+
+## Sample (`--sample`)
+
+Contract: [README → Sample](README.md#sample---sample). `$R` and `$A`/`$API_PORT`
+as above. Covered by `test/integration/retrieve-sample.test.ts`; cadence, the
+in-flight read at a stop, and the flag rules are pinned in
+`test/unit/retrieve-sample.test.ts`.
+
+### SA1. Three samples, one interval apart, on either transport
+
+```bash
+centrs retrieve $R /ip/address --sample 1s --count 3 --username $U --password $P --json
+centrs retrieve $A /ip/address --via native-api --sample 1s --count 3 --port $API_PORT --username $U --password $P --json
+```
+
+Each run prints three `sample` lines (`index` 1–3, `data` a row array) and a
+summary with `stopReason: "count-reached"`, `samples: 3`. Consecutive `at`
+values are at least one second apart. `meta.via` is the transport used.
+
+### SA2. Counters `listen` never reports
+
+```bash
+centrs retrieve $A /interface --via native-api --attributes name,rx-byte --sample 1s --count 3 --port $API_PORT --username $U --password $P --json
+```
+
+Every row has only `name` and `rx-byte`. `ether1`'s `rx-byte` in the third
+sample is higher than in the first, since the test's own API traffic arrives
+on `ether1`.
+
+### SA3. A singleton with one `--attribute`
+
+```bash
+centrs retrieve $R /system/resource --attribute uptime --sample 1s --count 2 --username $U --password $P --json
+```
+
+Each sample's `data` is the bare `uptime` string, and the two differ.
+
+### SA4. A removal is absence in the next sample
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --sample 500ms --count 2 --port $API_PORT --username $U --password $P --json
+```
+
+Add an address-list row before the run and remove it after the first sample.
+The first sample's rows include its `.id`; the second sample's do not.
+
+### SA5. `--follow` and `--sample` are exclusive
+
+```bash
+centrs retrieve $R /ip/address --sample 1s --follow --username $U --password $P --json
+```
+
+One envelope: `ok: false`, `usage/conflicting-flags`, exit 1. No summary.
+
+### SA6. NDJSON is readable before the process exits; Ctrl-C ends it cleanly
+
+```bash
+centrs retrieve $A /system/resource --via native-api --sample 1s --format ndjson --port $API_PORT --username $U --password $P
+```
+
+Run as a subprocess. The first `sample` line parses while the process is still
+running; after `SIGINT` the last line is a successful summary with
+`stopReason: "interrupted"`, and the exit code is 0.
+
+## Query (`--query`, #397)
+
+Contract: [README → Query](README.md#query---query). `$R` and `$A`/`$API_PORT`
+as above. Covered by `test/integration/retrieve-query.test.ts`, which seeds
+address-list, VLAN and firewall-filter rows; the grammar and compiled words are
+pinned in `test/unit/query.test.ts`.
+
+### QY1. The same rows as RouterOS's `find where`
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query 'comment and !disabled' --username $U --password $P --json
+centrs retrieve $A /interface/vlan --via native-api --query 'vlan-id>10 and vlan-id<100 or disabled' --port $API_PORT --username $U --password $P --json
+```
+
+For each of 58 expressions across three menus (equality, `!=`, numeric
+ordering, ordering on a property some rows lack, quoted values and their escapes, bare booleans, bare "is set" names, `and`/`or`
+precedence, parentheses, `!(…)`), the `.id`s returned over both transports
+equal the ids `:put [<menu> find where <expression>]` prints on the same
+router.
+
+### QY2. Where the query and the CLI differ, as documented
+
+```bash
+centrs retrieve $R /ip/firewall/filter --query 'dst-port=80' --username $U --password $P --json
+centrs retrieve $R /ip/firewall/address-list --query 'list=qa-397 and address>192.0.2.9' --username $U --password $P --json
+```
+
+The first returns the rule whose `dst-port` is `"80"`, although
+`find where dst-port=80` selects nothing on CHR 7.23.7/7.24.5 (the CLI reads
+`80` as a number). On CHR 7.25beta3, 7.25beta5, 7.25rc1 and 7.26beta1 the CLI
+also selects that rule. The test covers the same split for `protocol=tcp`
+and checks API query results over both transports. The second compares
+`address` as text, so `192.0.2.10` is not above `192.0.2.9`.
+
+### QY3. `--filter` and repeated `--query` are AND-ed
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --filter list=qa-397 --query comment --query '!disabled' --attributes address --username $U --password $P --json
+```
+
+`data` is exactly `[{ "address": "192.0.2.9" }]`.
+
+### QY4. A regex fails before anything is sent
+
+```bash
+centrs retrieve $R /interface --query 'name~"^ether"' --username $U --password $P --json
+```
+
+`ok: false`, `input/unsupported-query`, exit 1.
+
+### QY5. A misspelled property fails validation
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --query 'lists=qa-397' --port $API_PORT --username $U --password $P --json
+```
+
+`validation/unknown-attribute`. Without the check RouterOS would answer with
+no rows and no error.
+
+### QY6. A singleton has no rows to filter
+
+```bash
+centrs retrieve $R /system/identity --query 'name=MikroTik' --username $U --password $P --json
+```
+
+`usage/conflicting-flags`.
+
+### QY7. `--sample` reads the filtered rows each time
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query 'list=qa-397 and disabled' --sample 500ms --count 2 --username $U --password $P --json
+```
+
+Both samples hold only the disabled `qa-397` row.
+
+## Filtered follow
+
+Covered by `test/integration/retrieve-filtered-follow.test.ts` (FQ1–FQ5).
+The harness seeds address-list rows and changes them while following, with
+validation enabled. `$A`/`$API_PORT` are the native-API target as above.
+
+### FQ1. Projection and both membership directions
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq1' --query 'comment=a and !disabled' --attributes address --count 2 --duration 10s --json
+```
+
+Initially only the matching row appears. Changing its comment out of the
+predicate emits a `removed` frame with `source: "membership"`; changing an
+excluded row into it emits an `upsert` with the same source. `data` contains
+only `address`, while identity remains in meta.
+
+### FQ2. Minimal deletion frames
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq1 and comment=a' --sweep 0 --count 1 --duration 10s --json
+```
+
+Deleting an excluded row emits nothing; deleting the held row emits one
+`removed` with `source: "listen"`. Predicate fields are absent from `.dead`.
+
+### FQ3. Silent predicate exit
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --via native-api --port $API_PORT --username $U --password $P --follow --query 'list=fq3 and timeout>8s' --sweep 200ms --count 1 --duration 6s --json
+```
+
+The harness adds a row with a 10-second timeout. A sweep removes it from the
+selected set as its remaining timeout crosses 8 seconds, with
+`source: "membership"`; the row still exists in an unfiltered read.
+
+### FQ4. CLI alias and predicate validation
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --filter list=fq3 --attributes address --duration 500ms --json
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --query lits=fq3 --json
+```
+
+The first emits projected snapshot rows and `synced`. The typo in the second
+fails `validation/unknown-attribute` before listen starts.
+
+### FQ5. Filtered bootstrap and live churn
+
+```bash
+centrs retrieve $A /ip/firewall/address-list --port $API_PORT --username $U --password $P --follow --query 'list=fq5 and comment=in' --attributes address --sweep 200ms --duration 6s --json
+```
+
+The harness changes membership during bootstrap and live operation, then
+deletes rows. Applying all frames yields exactly the ids and projected rows
+of a fresh filtered print after churn settles. Deterministic delayed-reply,
+delete, cancellation and sustained-write bootstrap orderings are anchored in
+`retrieve-follow.test.ts`; newer versions cannot starve `synced`, sweeps or
+live `--count`.
+
+## Readiness and conditions
+
+Covered by `test/integration/retrieve-wait.test.ts` (WT1–WT7) on disposable
+CHR, with validation enabled over REST and native-api. `$R` and
+`$A`/`$API_PORT` are the targets as above.
+
+### WT1. Readiness and already-true any-match
+
+```bash
+centrs retrieve $R /system/resource --wait 5s --username $U --password $P --json
+centrs retrieve $A /interface --via native-api --port $API_PORT --query name=ether1 --until '!disabled and mtu>=1500' --attributes name --wait 5s --username $U --password $P --json
+```
+
+Each succeeds with one attempt and one observation. The second returns only
+`[{ "name": "ether1" }]`, with `stopReason: "condition-met"`.
+
+### WT2. Wait for a row to match
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query list=wait-364 --until comment=ready --attributes address --wait 10s --sample 100ms --username $U --password $P --json
+```
+
+The harness adds a matching row after the wait starts. The waiter returns its
+projected address, with more than one completed observation. The same test
+runs over native-api.
+
+### WT3. Drop to zero and already empty
+
+```bash
+centrs retrieve $R /ip/firewall/address-list --query list=wait-364 --until-empty --wait 10s --sample 100ms --username $U --password $P --json
+```
+
+The harness removes the selected row after the wait starts; `data: []`,
+`stopReason: "condition-met"`. Repeating the wait on the now-empty selection
+succeeds on its first completed observation.
+
+### WT4. Condition expiry and fail-fast faults
+
+```bash
+centrs retrieve $R /interface --until name=missing --wait 500ms --sample 100ms --username $U --password $P --json
+centrs retrieve $R /interface --until unknown-property=yes --wait 5s --username $U --password $P --json
+```
+
+The first fails `wait/deadline-exceeded`, `stopReason: "deadline-elapsed"`.
+The second fails `validation/unknown-attribute` in one attempt. Incorrect
+credentials also fail in one attempt; singleton `--until-empty` is refused.
+
+### WT5. Real reboot readiness
+
+```bash
+centrs retrieve $R /system/resource --wait 60s --timeout 2s --sample 500ms --username $U --password $P --json
+```
+
+The harness reboots the CHR and starts this call while its services are down.
+The waiter succeeds with multiple attempts and exactly one completed data
+observation, without an external retry loop.
+
+### WT6. OSPF reaches Full
+
+```bash
+centrs retrieve $A /routing/ospf/neighbor --via native-api --port $API_PORT --until state=Full --wait 40s --sample 200ms --username $U --password $P --json
+```
+
+Two disposable CHRs share a point-to-point Ethernet link. After configuring
+OSPF, the waiter returns a neighbor whose state is `Full`. A REST wait on
+the established adjacency succeeds on its initial observation.
+
+### WT7. CLI failure is one final envelope
+
+```bash
+centrs retrieve $R /interface --until name=missing --wait 500ms --username $U --password $P --json
+```
+
+One envelope goes to stdout, with `stopReason: "deadline-elapsed"`; exit 1.
+No intermediate sample frames are printed. Unit anchors cover slow validation,
+unfinished reads, cancellation and narrow retry classification.

package/commands/terminal/README.md

@@ -6,10 +6,13 @@ Open an interactive RouterOS console.
 flag (`--group` / `--where` / `--all` / `--default` / `--concurrency`) is rejected
 with `usage/fanout-not-supported` — open a console to one router at a time; use
 `execute` / `api` for multi-target commands. See `docs/CONSTITUTION.md`
-(Target selection grammar).
+(Target selection grammar). With no `<router>`, the `--host` **flag** is the
+target (`terminal --host 192.0.2.10` opens an ssh console; no CDB lookup).
+`CENTRS_HOST` never stands in for `<router>`. mac-telnet still needs a MAC
+`<router>`, since its `--host` is only the UDP delivery endpoint.
 
 Status: `terminal / mac-telnet` **and** `terminal / ssh` are both **`CHR-passed`**
-(see `docs/MATRIX.md` and `examples.md` T1–T3 / TS1–TS2). The two transports take
+(see `docs/MATRIX.md` and `examples.md` T1–T3 / TS1–TS2, TS4). The two transports take
 different paths: **mac-telnet** is the in-process raw passthrough over
 `MacTelnetConsole.attachInteractive`; **ssh** execs the host `ssh` with inherited
 stdio (RouterOS grants no PTY, but `ssh user@host` opens the console and the OS
@@ -73,6 +76,12 @@ CLI/API. When no key is set, terminal delegates identity selection to system
 `ssh` config and the SSH agent; `--ssh-key` is an explicit override and must not
 silently merge with a conflicting CDB/env key.
 
+A selected key from any settings source adds `IdentitiesOnly=yes` alongside
+`-i`, preventing unrelated agent identities from authenticating instead. The
+agent can still sign for the selected key. OpenSSH continues to honor explicit
+`IdentityFile` entries in its config; this does not isolate the user's SSH
+configuration. The same selection applies to execute and SFTP.
+
 Unlike the batch sftp/execute clients, the **interactive** `terminal / ssh` argv
 omits `BatchMode=yes` (`interactive: true` in `sshCommonOptions`), so the host
 `ssh` can prompt on the inherited TTY for an encrypted key's passphrase or a
@@ -86,8 +95,9 @@ longer open for the file path: **host-key verification** rides the unified
 a changed key → `transport/host-key-mismatch`; `--insecure` →
 `StrictHostKeyChecking=no` — see `docs/CONSTITUTION.md`, Transport trust);
 **agent vs explicit-key** interplay and **algorithm negotiation** are delegated to
-the host OpenSSH (`-i <ssh-key>` when set, else the agent / `~/.ssh/config`). The
-MAC-on-file-but-SSH-pinned case is settled (see *MAC target over SSH* above):
+the host OpenSSH (`-i <ssh-key> -o IdentitiesOnly=yes` when set, else the agent /
+`~/.ssh/config`). The MAC-on-file-but-SSH-pinned case is settled (see *MAC target
+over SSH* above):
 centrs resolves a MAC for `--via ssh` CDB-first, then tips `--via mac-telnet` —
 it does **not** silently fall back to L2 (constitution: a pinned `--via` is never
 swapped). The no-pseudo-tty console reader is likewise resolved — a CHR spike

package/commands/terminal/examples.md

@@ -91,9 +91,10 @@ on the argv.
 
 Harness inputs (from `test/integration/terminal-ssh.test.ts`): `$SSH_PORT` is
 `chr.sshPort` (passed via `--port`), and `$KEY` is the ephemeral private key the
-test mints with `ssh-keygen -f <tmp>/id` and passes via `--ssh-key`. **TS1–TS2 are
-the CHR-tested set** (green via `bun run test:integration`, CHR 7.23.1) — the
-matrix's `CHR-passed` claim rests on them. **TS3 is the interactive hand-verified
+test mints with `ssh-keygen -f <tmp>/id` and passes via `--ssh-key`. **TS1, TS2,
+TS4 and TS5 are the CHR-tested set**. The matrix's `CHR-passed` claim rests on
+TS1, TS2 and TS4. TS1, TS2 and TS5 run in `test/integration/terminal-ssh.test.ts`; TS4 runs in the shared
+`test/integration/ssh-identity.test.ts`. **TS3 is the interactive hand-verified
 analog of T4** (a piped subprocess stdin cannot be a TTY), not in CI.
 
 ### TS1. Run a command over an SSH terminal (batch relay)
@@ -130,6 +131,24 @@ RouterOS console to the user; `/quit` (or `Ctrl-D`) ends the session. RouterOS's
 no-PTY limitation applies (e.g. multi-line brace blocks are not supported over
 SSH — see the SSH page); single-line commands work.
 
+### TS4. A rejected selected key cannot authenticate through another agent identity
+
+The shared [SSH identity example S5](../execute/examples.md#s5-an-explicit-rejected-key-cannot-fall-back-to-an-unrelated-agent-key)
+checks the real terminal relay against CHR with a private agent and prompts
+disabled. The rejected key preserves OpenSSH's nonzero exit and
+`Permission denied`; selecting the trusted key or leaving the key unset
+returns the device identity. Covered by `test/integration/ssh-identity.test.ts`.
+
+### TS5. `--host` stands in for `<router>` (#428)
+
+```bash
+printf '/system/identity/print\n/quit\n' | centrs terminal --host 127.0.0.1 --port $SSH_PORT --username $U --ssh-key $KEY --insecure
+```
+
+There's no `<router>` and no `--via`. The host-only target selects ssh, as a
+host `<router>` does, with no CDB lookup. stdout contains the device identity,
+checked as in TS1.
+
 ## MAC target over `--via ssh` resolution (behavior note — not a numbered CHR example)
 
 This path resolves a MAC to an IP and, on the unresolved / no-opt-in branch,

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`