@tikoci/centrs 0.1.0

package/commands/terminal/examples.md

@@ -0,0 +1,144 @@
+# terminal — examples
+
+Each numbered example is an executable spec. The integration test under
+`test/integration/terminal-mac-telnet.test.ts` runs the CHR-testable examples
+(T1–T3) against a CHR booted by `@tikoci/quickchr` over a real L2 path, driving
+the **real `centrs terminal` binary** through the subprocess harness
+(`test/integration/cli-process.ts`) pointed at the L2 bridge's UDP relay — the
+same transport the `execute / mac-telnet` command path uses.
+
+`terminal` is a **raw passthrough**, not an enveloped command: device terminal
+bytes stream to **stdout**, and any error/summary goes to **stderr** (so the two
+never interleave — the same split as `transfer download -`). On a clean session
+close the exit code is `0`; a pre-stream failure (bad transport, auth, no route)
+emits the standard error envelope on stderr and exits `1`.
+
+Two input modes, chosen by whether stdin is a TTY:
+
+- **Interactive** (stdin is a TTY): raw-mode stdin → the session, device output →
+  stdout, the real terminal size is reported to the device, and `SIGWINCH`
+  forwards resizes. This is the human path; it is described in T4 and verified by
+  hand (a piped test cannot be a TTY).
+- **Batch** (stdin is a pipe/file): bytes are forwarded as typed and the session
+  closes when stdin reaches EOF (after a short output drain). This is what the
+  harness drives — pipe a command in, read the device's response off stdout.
+
+Conventions (provided by the harness):
+
+- `$MAC` is the CHR target interface MAC; `$U` / `$P` are MAC-Telnet credentials.
+- `$HOST` / `$UDP` point the UDP transport at the loopback L2 bridge
+  (`--host 127.0.0.1 --port <bridge udpPort>`), exactly as the `execute /
+  mac-telnet` command-path test does. A real call omits these and lets the
+  adapter discover the L2 route.
+
+## CHR-tested (T1–T3)
+
+### T1. Run a command over a MAC-Telnet terminal (batch relay)
+
+Pipe a CLI line into the terminal; the device's response appears on stdout.
+
+```bash
+printf '/system/identity/print\n' | centrs terminal $MAC --via mac-telnet --host $HOST --port $UDP --username $U --password $P
+```
+
+stdout contains the device identity (cross-checked against REST). Exit code `0`.
+
+### T2. `--via rest-api` has no terminal capability
+
+```bash
+centrs terminal $MAC --via rest-api --username $U --password $P
+```
+
+Envelope on stderr: `ok: false`, `error.code="transport/capability-unsupported"`.
+Exit code `1`. No bytes on stdout.
+
+### T3. `--via native-api` has no terminal capability
+
+```bash
+centrs terminal $MAC --via native-api --username $U --password $P
+```
+
+Same contract as T2: `transport/capability-unsupported` on stderr, exit `1`.
+
+## Interactive (verified by hand, not in CI)
+
+### T4. Open an interactive console to a MAC
+
+```bash
+centrs terminal $MAC --username $U --password $P
+```
+
+A MAC target with no `--via` selects `mac-telnet` (the L2 default). stdin goes
+into raw mode; keystrokes reach the device and its output paints stdout. The real
+terminal rows/cols are reported to the console (so it neither wraps nor paginates)
+and a window resize forwards via `SIGWINCH`. `Ctrl-D` / session end exits `0`.
+
+## ssh (`--via ssh`)
+
+`terminal / ssh` execs the **host `ssh`** with inherited stdio: RouterOS grants no
+pseudo-tty, but `ssh user@host` opens the interactive console and the OS relays it
+(the no-PTY stream is already clean — no screen emulation). centrs's value is
+resolving the target/key/trust and building the argv; the interactive TTY, raw
+mode, and signals are the inherited terminal's. A **host target defaults to ssh**
+(a MAC target defaults to mac-telnet). Because the session is interactive, the
+terminal argv omits `BatchMode=yes` (the batch sftp/execute clients keep it), so
+the host `ssh` may prompt on the TTY for an encrypted key's passphrase or a
+password — centrs does not forward `--password`, since OpenSSH takes no password
+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
+analog of T4** (a piped subprocess stdin cannot be a TTY), not in CI.
+
+### TS1. Run a command over an SSH terminal (batch relay)
+
+```bash
+printf '/system/identity/print\n/quit\n' | centrs terminal 127.0.0.1 --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure
+```
+
+stdout contains the device identity (cross-checked against REST). centrs returns
+ssh's exit code (a no-PTY console closed by EOF can exit non-zero — that is the
+device/ssh's result, not a centrs failure; a clean `/quit` from a real TTY exits
+`0`).
+
+### TS2. `--via rest-api` has no terminal capability
+
+```bash
+centrs terminal 127.0.0.1 --via rest-api --username $U --password $P
+```
+
+Envelope on stderr: `ok: false`, `error.code="transport/capability-unsupported"`,
+exit `1` — same gate as mac-telnet's T2/T3, evaluated before any connection.
+
+### TS3. Open an interactive console over SSH (verified by hand, not in CI)
+
+```bash
+centrs terminal 192.0.2.10 --username $U --ssh-key $KEY
+```
+
+A host target with no `--via` selects `ssh`. The inherited terminal hands the
+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.
+
+## 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,
+fails before reaching any router — so it is **not** a numbered CHR integration
+example. It is covered by the network-free smoke tier
+(`test/integration/cli-smoke.test.ts`, JG-01) and `test/unit/{terminal,mac}.test.ts`.
+
+```bash
+centrs terminal aa:bb:cc:dd:ee:ff --via ssh --username $U --json
+```
+
+A MAC pinned to the IP transport needs an IP. With no matching CDB record and the
+default `--resolve none`, the envelope on stderr is `ok: false`,
+`error.code="target/mac-unresolved"`, exit `1` — and the remediation leads with
+`--via mac-telnet` (reach it over L2, no IP needed). `--resolve arp` opts into the
+host ARP cache instead; a miss is `target/mac-not-in-arp`. centrs never resolves a
+MAC over ARP, or swaps to another transport, on its own (see
+`commands/terminal/README.md` → *MAC target over SSH*).

package/commands/transfer/README.md

@@ -0,0 +1,315 @@
+# transfer
+
+Copy files to and from a RouterOS device, and manage device files.
+
+Status (agrees with `docs/MATRIX.md`): `CHR-passed` for `rest-api` / `native-api`
+and for `ssh`/**sftp** (`src/transfer.ts`, `src/cli/transfer.ts`,
+`src/protocols/sftp.ts`). `test/integration/transfer.test.ts` is green against a
+real CHR 7.23.1 (110 assertions): the rest + native round-trip, list + filters,
+validate-before-write, device file management (mkdir/copy/remove), leading-slash
+normalization, the >60 KB REST-write rejection, the error contract, the
+stdin/stdout/default-local forms (examples 8–10, driven through the real CLI
+binary via the subprocess harness `test/integration/cli-process.ts`), the native
+`N1`–`N4` mirror, the sftp `S1`–`S5` round-trip (key-auth, the >60 KB upload REST
+cannot do, list/mkdir/remove), and example 17 (chunked REST read of an
+sftp-seeded >60 KB file) — confirming the `/file`
+`get`/`set`/`add`/`copy`/`remove` wire shapes and the SFTP subsystem on real
+RouterOS. Unit coverage is `test/unit/transfer.test.ts`. **sftp** is the first SSH
+consumer — a self-contained SFTP transfer client over the host OpenSSH `sftp`
+subsystem. `scp` and `fetch` are **designed but deferred** past this pass.
+
+## Intent
+
+`transfer` is centrs's file verb. Direction is explicit in the sub-verb —
+`upload` is host → device (the WinBox "upload files" direction), `download` is
+device → host. It honors the same `<router>` resolution, credentials, envelope,
+and settings as every other command (see [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md)
+for identity/CDB resolution and the result envelope). Large transfers are exempt
+from the REST 60 s timeout cap because they do not ride a single REST request.
+
+centrs does not pick one method for you and hope; it picks the **cheapest method
+that can carry this file in this direction**, reports the choice in
+`meta.via`, and never silently crosses an explicit `--via`. See *Method
+selection*.
+
+## Synopsis
+
+```text
+centrs transfer <router> upload   <local> [<remote>] [flags]
+centrs transfer <router> download <remote> [<local>] [flags]
+centrs transfer <router> list     [<path>] [flags]
+centrs transfer <router> remove   <remote> [flags]
+centrs transfer <router> mkdir    <remote> [flags]
+centrs transfer <router> copy     <remote-src> <remote-dst> [flags]   # on-device
+```
+
+- `<router>` — IP, DNS, MAC, or CDB-resolved name. See constitution: identity.
+- `<local>` — a host path, or `-` for stdin (`upload`) / stdout (`download`), so
+  `transfer` composes in shell pipelines. If omitted, `download` writes the
+  remote basename into the current directory.
+- `<remote>` — a RouterOS file path (e.g. `flash/fw.rsc`). If omitted on
+  `upload`, centrs uses the **local basename**. *(Planned: prefer the device's
+  `flash` disk — `flash/<basename>` — when one is present.)*
+- Remote paths match RouterOS exactly — no path rewriting. RouterOS file names
+  carry **no leading slash** (`/file/print` shows `flash/fw.rsc`), but the
+  `/file/add name=/flash/…` form *accepts* one, so centrs accepts a leading `/`
+  for ergonomics and **normalizes it away** to the canonical no-slash form used
+  on the wire (REST `/file` keys and SFTP paths both want it stripped).
+  `flash/fw.rsc` and `/flash/fw.rsc` are the same target.
+- Reboot-persistence: on devices that have a `flash` disk, anything stored
+  **outside** `flash/` lives on a RAM disk and is lost on reboot — so prefer an
+  explicit `flash/…` remote on such devices. CHR has no `flash` disk —
+  everything persists. *(Planned: detect a `type=disk name=flash` row to default
+  omitted uploads into `flash/` and warn on an explicit non-`flash/` path;
+  centrs never silently relocates an explicit path.)*
+
+`list` is thin sugar over `retrieve <router> /file` (a `/file/print` menu read),
+rendered for humans (human-readable sizes, `flash/` tree, `.npk` package
+metadata). For RouterOS-side row queries beyond `--type` / `--name`, use
+`retrieve /file --query` directly.
+
+### Top-level shortcuts
+
+`upload` and `download` are also promoted to **top-level command aliases** for the
+two highest-frequency operations, so the router stays the first positional:
+
+```text
+centrs upload   <router> <local> [<remote>] [flags]   →  centrs transfer <router> upload   <local> [<remote>]
+centrs download <router> <remote> [<local>] [flags]   →  centrs transfer <router> download <remote> [<local>]
+```
+
+They are pure aliases (identical flags, envelope, and validation); help and docs
+show the canonical `transfer …` form, and the shared "did you mean?" / level-aware
+help applies. Only `upload`/`download` are promoted — `list`/`remove`/`mkdir`/
+`copy` stay under `transfer` because those verbs would be ambiguous at the top
+level (every command can list or remove something).
+
+## Method selection
+
+The RouterOS file plumbing is asymmetric, so the default is direction- and
+size-aware. Grounding: [Files](https://help.mikrotik.com/docs/spaces/ROS/pages/2555971/Files),
+[Fetch](https://help.mikrotik.com/docs/spaces/ROS/pages/8978514/Fetch).
+
+| Method (`--via`) | Grid transport | download (device → host) | upload (host → device) |
+| ---------------- | -------------- | ------------------------ | ---------------------- |
+| `rest` / `native` | rest-api / native-api | small via `/file/get … contents` (**≤ 60 KB**); **large via chunked `/file/read offset chunk-size≤32768`** | **`/file/set contents=` ≤ 60 KB only** — no chunked write |
+| `sftp` (default secure) | ssh | any size | any size |
+| `scp` | ssh | any size | any size |
+| `fetch` *(deferred)* | rest-api/native-api + inbound HTTP | router PUTs to centrs (`upload=yes http-method=put src-path=…`) | router GETs from centrs (`url=http://centrs/… dst-path=…`) |
+| `ftp` *(gated)* | ftp | any size | any size |
+
+Auto-selection (no `--via`):
+
+- **download** — `rest`/`native` for everything (chunked `/file/read` scales to
+  any size with no SSH service required); fall back to `sftp` only if the REST
+  family is unreachable.
+- **upload ≤ 60 KB** — `rest`/`native` (`/file/set contents`); one round trip, no
+  SSH needed.
+- **upload > 60 KB** — `sftp`. The REST family cannot write past 60 KB, and
+  `fetch` is the only REST-family way to push a large file without SSH — but it
+  needs inbound reachability we can't assume, so it is **explicit-only** (see
+  below), never auto-selected.
+
+Every auto hop is reported in `meta.warnings` with its reason. An explicit
+`--via` is never silently downgraded: if you pin `--via rest` and ask to upload a
+2 MB file, centrs fails with `transport/unsupported-operation` (REST cannot write
+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.
+
+> 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`).
+
+### SFTP vs SCP (why sftp is the SSH default)
+
+RouterOS supports both over its SSH server, and MikroTik documents both — their
+container guides use `sftp admin@<router>` to push/pull config files
+([example 1](https://help.mikrotik.com/docs/spaces/ROS/pages/172294200/Container%2B-%2Bfreeradius%2Bserver),
+[example 2](https://help.mikrotik.com/docs/spaces/ROS/pages/169246787/Container%2B-%2Bmosquitto%2BMQTT%2Bserver)),
+while the [CHR-ProxMox guide](https://help.mikrotik.com/docs/spaces/ROS/pages/48660553/CHR%2BProxMox%2Binstallation)
+uses `scp`. centrs makes **sftp the default and the primary investment**; `scp`
+is an explicit `--via scp` escape hatch. The reason is capability, not taste:
+
+- **SFTP is a real protocol** — `stat`, `readdir`, partial reads/writes, `mkdir`,
+  `remove`, `rename`. Those are exactly what centrs's feature set needs: the
+  validate-before-write existence check (`stat` the target) and the
+  `list`/`remove`/`mkdir` verbs all fall out of SFTP. (`--verify size` is still
+  supported over sftp — it just trusts the SFTP transfer guarantee rather than
+  re-reading a settled size, since RouterOS's `ls -l` has no reliable size column;
+  see *Integrity*.)
+- **SCP is a dumb byte-stream** — no stat, no listing, no existence check; it just
+  blasts bytes and truncates on collision. An `--via scp` upload therefore
+  **cannot do the existence check itself** and would need a side-channel REST/SFTP
+  `stat` anyway — so `--via scp` skips the refuse-overwrite guard unless REST is
+  also reachable, and `--verify` degrades to `off` (warned). scp buys only a
+  marginally lighter single-file stream, irrelevant under the CHR 1 Mb/s cap.
+- **Direction of the ecosystem** — OpenSSH deprecated the legacy SCP wire protocol
+  (9.0, 2022); modern `scp` rides SFTP underneath, so the reliable SSH file channel
+  is the **SFTP subsystem**, not an exec-driven copy. (RouterOS's SSH server has no
+  pseudo-tty, but a single-line `ssh user@host "<command>"` *does* run and return
+  clean output — that path drives `execute / ssh`, see `commands/execute/README.md`;
+  it is not a file-transfer channel.)
+
+## Flags
+
+| Flag | Behavior |
+| ---- | -------- |
+| `--via <method>` | Pin the method: `sftp` (built; secure default for large transfers), `rest`, `native`, or `scp` *(deferred)* / `fetch` *(deferred)* / `ftp` *(gated)*. No silent downgrade. See *Method selection* and constitution: protocol selection. |
+| `--force` (alias `--overwrite`) | Replace an existing target. Default **refuses** an existing target with `usage/target-exists` (mirrors how `add` refuses an existing record). Applies to the destination side: the local file for `download`, the remote file for `upload`. |
+| `--verify <size\|checksum\|off>` | Post-transfer integrity check. Default `size` (compare the byte count centrs sent/received against the settled `/file` size). `off` (alias `--no-verify`) skips it. See *Integrity*. |
+| `--type <file\|directory\|disk\|package>` | `list` only: filter by `/file` row type. |
+| `--name <glob>` | `list` only: filter by file name glob. |
+| `--out-dir <dir>` | `download` fanout only *(deferred — fanout not built yet)*: write one file per target into `<dir>` (named by CDB target), since N devices cannot share one local path. |
+| `--advertise-host <host>` / `--advertise-port <n>` / `--bind <addr>` | `fetch` only *(deferred)*: the host/IP/port centrs advertises in the fetch URL and the local bind address. Default: auto-detect the local IP on the route to the router; ephemeral port; single-use random URL token. |
+| `--resolve <none\|arp>` | *(deferred — not parsed yet)* Resolve a MAC-address target to an IP via the host ARP cache. Default `none`. |
+| `--format text` (default) | Human summary: method, bytes, duration, verified. Errors print `[code] summary` + `Fix:` lines. |
+| `--format json` (alias `--json`) / `--format yaml` (alias `--yaml`) | Structured envelope. `CENTRS_FORMAT=json` makes JSON the default. |
+| `--validate=false` | Escape hatch; default `true`. See constitution: validation is the product. |
+| `--timeout <ms>` | Request timeout. `rest`/`native` per-request ≤ 60000 (a chunked read is many short requests, each capped); `sftp`/`scp`/`fetch` accept longer for a single large transfer. |
+| `--username` / `--password` | Override CDB-resolved or env credentials. |
+| `--host <host\|url>` / `--port <n>` | Override the resolved host / transport port. |
+| `--ssh-key <path>` | `sftp` (and future `scp`): explicit private-key path. 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`. |
+| `--insecure` | Accept a self-signed TLS cert (`https`/`api-ssl`) or a new SSH host key (TOFU). Default verifies; see constitution: transport trust. Adds a `transport/insecure-trust` warning. |
+| `--cdb-file` / `--cdb-password` | Override CDB file location / decrypt password. |
+| `--group <name>` / `--where <attr>=<value>` / `--all` / `--default` / `--concurrency <n>` | *(deferred — fanout not built for `transfer` yet)* Fan out across CDB targets (e.g. push one firmware file to a fleet). Same selector grammar and per-target envelope as `retrieve` (constitution: target selection). `download` fanout requires `--out-dir`; `remove`/`mkdir`/`copy`/`upload` fan out directly. |
+
+## Integrity
+
+`--verify size` (default) over `rest`/`native` reads the settled `/file` size
+after the transfer and compares it to the byte count centrs moved. Over **sftp**,
+RouterOS's `ls -l` reports no reliable byte size (CHR 7.23.1), so `--verify size`
+instead trusts the SFTP transfer guarantee — a partial `put`/`get` errors — rather
+than re-reading a size. Two RouterOS facts shape the `/file`-size path:
+
+- **NAND write-back** delays the flush up to ~40 s on some devices, so the size
+  may read short immediately after an upload. centrs does a single post-write
+  `/file/print` size probe today. *(Planned: a brief poll/retry to absorb the
+  write-back window before declaring a mismatch.)*
+- **Transparent compression**: the `/file` menu reports the *uncompressed* size
+  (compression only shows up in `/system/resource` free space), so size-compare
+  against the uncompressed byte count we sent stays valid.
+
+A confirmed shortfall (clear truncation after the poll window) is
+`transport/incomplete-transfer`. `--verify checksum` is stronger but only where
+RouterOS exposes a usable digest; otherwise it degrades to `size` with a warning.
+
+## Output shape
+
+The downloaded/uploaded bytes go to disk (or stdout for `download -`); the
+envelope carries transfer *metadata*, not file contents.
+
+```ts
+{
+  ok: true,
+  data: {
+    op: "upload",                 // upload | download | list | remove | mkdir | copy
+    remote: "flash/fw.rsc",
+    local: "./fw.rsc",            // null for list/remove/mkdir/copy
+    bytes: 1048576,
+    verified: "size",             // size | checksum | off
+    durationMs: 1840
+  },
+  warnings: [],                   // e.g. auto-method hops, insecure-trust
+  meta: { target, via: "ssh", settings, validation, timing }  // via is the grid transport: rest-api | native-api | ssh
+}
+```
+
+`list` returns `data` as the `/file` row array (same shape as
+`retrieve /file`). Fanout returns the shared one-outer-envelope form documented
+in `commands/retrieve/README.md` (Group fanout): `ok` reports orchestration
+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`
+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.
+This is the "validate before write" gate applied to files — see constitution:
+validation is the product.
+
+The `/file` menu path is fixed, so there is no `/console/inspect` path/attribute
+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/*`.
+
+**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,
+`transport/incomplete-transfer` for a verified shortfall, `transport/unreachable`
+for fetch inbound-reachability), `routeros/*`, `auth/*`, and `validation/*`. A new
+code is only justified where the *semantics* are genuinely file-transfer-specific
+and not already expressible in those namespaces.
+
+## Decided (2026-06-10)
+
+- **Verbs are `upload` / `download` / `list`** (+ `remove` / `mkdir` / `copy` for
+  device file management). Direction is explicit in the sub-verb; `upload` =
+  host → device per WinBox wording. **`copy` needs RouterOS ≥ 7.23beta2**:
+  server-side copy rides the REST `/file/copy` endpoint, first seen in 7.23beta2;
+  earlier RouterOS (e.g. 7.21.x long-term) returns `no such command` (the
+  integration test gates the `copy` example on the running version).
+- **Method selection is size/direction-aware** (table above), superseding the
+  earlier "sftp is always the default" decision. REST/native carry small writes
+  and all reads (reads scale via chunked `/file/read`); sftp carries large
+  uploads. This updates the constitution's protocol-selection row.
+- **sftp is the SSH default, scp is `--via scp` only** — sftp's `stat`/`readdir`/
+  partial ops are what enable the existence check, `--verify`, and
+  `list`/`remove`/`mkdir`; scp can't do those and degrades the overwrite guard and
+  `--verify`. See *SFTP vs SCP*.
+- **Remote paths match RouterOS** (no rewriting); a leading `/` is accepted but
+  normalized away to the canonical no-slash wire form. The omitted-`<remote>`
+  default uses `flash/` on devices that have a flash disk.
+- **`upload` / `download` are also top-level command aliases** (`centrs upload
+  <router> …`), the only sub-verbs promoted to the top level.
+- **Error codes reuse existing namespaces** — no `transfer/*` namespace; new codes
+  only where the semantics are genuinely transfer-specific.
+- **`fetch` (centrs-as-HTTP-server + `/tool/fetch`) is explicit-only and
+  deferred** — designed here, built after sftp + REST land. It is the only
+  REST-family way to push a > 60 KB file without SSH, but needs inbound
+  reachability (router → centrs), so it is never auto-selected.
+- **v1 includes** device file management (`remove`/`mkdir`/`copy`), integrity
+  verification (`--verify`), and stdout/stdin piping (`-`). **Directory /
+  recursive transfer is a later phase.**
+- **CI proof is a small-file round-trip**, not a throughput stress test — the
+  free CHR license caps throughput at 1 Mb/s.
+
+## Definition of done
+
+`CHR-passed` only when every line in `examples.md` runs green against a real CHR
+through `bun run test:integration` (one example ↔ one assertion). Disabling
+validation to reach green is forbidden. See `docs/CONSTITUTION.md` for the full
+done rule. The first coded pass targets `rest`/`native` (no SSH dependency);
+`sftp`/`scp` advance with the SSH transport; `fetch` and `ftp` follow.
+
+## Notes for future cells
+
+- **fetch design (deferred).** centrs starts an ephemeral single-use HTTP server
+  (random URL token, bound to the interface facing the router) and drives the
+  router with `/tool/fetch` over `rest`/`native`. **upload**: serve the local
+  file, `fetch url=http://<advertise>/<token> dst-path=<remote>` → router GETs.
+  **download**: `fetch upload=yes http-method=put url=http://<advertise>/<token>
+  src-path=<remote>` → router PUTs to centrs (`http-method` any since 7.21;
+  binary REST serialization fixed 7.17). Open questions: advertise-host
+  auto-detection behind NAT, HTTP-vs-HTTPS + `check-certificate`, and whether to
+  add fetch's `user`/`password` on top of the URL token.
+- **ssh** — `sftp` is **built** (`src/protocols/sftp.ts`, host OpenSSH `sftp`
+  subsystem; `scp` is the deferred follow-on). The host SSH client owns
+  host-key/agent/algorithm negotiation; the centrs-side trust knob is the unified
+  `--insecure` (constitution: transport trust). Two RouterOS auth facts transfer
+  inherits, grounded on the [SSH](https://help.mikrotik.com/docs/spaces/ROS/pages/132350014/SSH)
+  / [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`
+  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`
+  has no SFTP primitive and stays on rest/native (`--via sftp copy` →
+  `transport/unsupported-operation`). See `commands/terminal/README.md` (RouterOS
+  SSH surface) for the full device-side option alignment.
+- **list ↔ retrieve** — `transfer list` is sugar over `retrieve /file`; keep the
+  read logic in one place.