@tikoci/centrs 0.1.0

package/commands/discover/examples.md

@@ -0,0 +1,98 @@
+# discover — examples
+
+Each numbered example is an executable spec. `discover` listens on a UDP
+socket; MNDP needs a real layer-2 broadcast segment, which a `user`-mode SLIRP
+CHR cannot carry. The L2 fabric now comes from a second `socket-connect` NIC
+plus a host bridge (`README.md`, L2 validation policy). Examples are validated
+by:
+
+- **real L2 against CHR** — examples 1 (passive discover + neighbor fields), 2
+  (scan packet-count meta), and 4 (`--save` into a CDB): a CHR boots with a
+  `socket-connect` NIC and `test/integration/discover.test.ts` runs the
+  unmodified `discover()` path against a genuine RouterOS announcement,
+  cross-checked against REST (CHR 7.23.1, `bun run test:integration`);
+- the pure codec against crafted packet fixtures
+  (`test/unit/mndp.test.ts`),
+- the TTL cache with an injected clock (`test/unit/mndp-cache.test.ts`),
+- the UDP listener over a loopback socket and the `--save` / port-in-use /
+  custom-group / de-dupe / encrypted-CDB paths (examples 3, 5, 6, 7) against an
+  ignored, per-test CDB path in the working tree (`test/unit/discover.test.ts`).
+
+`$CDB` is a per-test CDB path; the real `~/.config/tikoci/winbox.cdb` is never
+touched.
+
+## discover
+
+### 1. Passive discover with the default window
+
+```bash
+centrs discover
+```
+
+Listens for the default `15s`, broadcasting an immediate refresh then every 5s. Envelope:
+`ok: true`, `meta.via: "mndp"`, `data` is `{ count, neighbors }` with
+`neighbors` sorted by MAC. Each neighbor carries `mac`, optional `identity`,
+`version`, `platform`, `board`, `uptimeSeconds`, `softwareId`,
+`interfaceName`, `ipv4`, `ipv6`, plus `firstSeenAt` / `lastSeenAt`.
+
+### 2. Short scan with JSON output
+
+```bash
+centrs discover --timeout 5s --format json
+```
+
+`meta.operation.timeoutMs` is `5000`; `meta.operation.packetsReceived`,
+`packetsDecoded`, and `packetsRejected` summarize the scan. The JSON envelope
+is the lossless representation the text format renders.
+
+### 3. Bind a non-default port
+
+```bash
+centrs discover --port 5678
+```
+
+Binding a port already held (e.g. by WinBox, without `SO_REUSEPORT`) errors
+with `mndp/listen-failed` and an actionable remediation.
+
+## discover --save
+
+### 4. Save discovered neighbors into the CDB
+
+```bash
+centrs discover --save --cdb-file $CDB
+```
+
+New neighbors are added through the `devices` atomic write path with
+`group=discovered`. Each saved comment contains the `source=mndp` kv token and
+free-form provenance (`identity:`, `board:`, `version:`, `mac:`, …).
+`meta.operation.saved` reports `{ group, added, skipped, records }`.
+
+### 5. Save with a custom group
+
+```bash
+centrs discover --save --group lab --cdb-file $CDB
+```
+
+New entries get `group=lab` instead of `discovered`.
+
+### 6. De-dupe against existing records
+
+```bash
+centrs discover --save --cdb-file $CDB
+```
+
+A neighbor whose target (IPv4, else MAC) already names a CDB entry is skipped,
+never overwritten. The skip is reported in
+`meta.operation.saved.records[].action = "skipped-existing"`; hand-curated
+records win.
+
+### 7. Save against an encrypted CDB
+
+```bash
+centrs discover --save --cdb-file $ENC_CDB --cdb-password centrs-test
+```
+
+`ok: true`. The write layer decrypts the CDB under the supplied password,
+appends new neighbors, and re-encrypts with a fresh salt before the atomic
+rename. The `.bak.<timestamp>` beside the CDB is the verbatim prior
+ciphertext.

package/commands/execute/README.md

@@ -0,0 +1,208 @@
+# execute
+
+Run a RouterOS CLI command and return its (semi-structured) output. `execute`
+is the single read/write surface for RouterOS add/set/remove and other
+CLI-shaped commands — there is no separate `update` command.
+
+Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
+`docs/MATRIX.md` and `commands/execute/examples.md`, examples 1–11 over REST,
+12–18 over the native API, 19–21 over mac-telnet, and S1–S4 over ssh, green via
+`bun run test:integration`). `romon` and `winbox-terminal` remain
+`not-started`. SNMP is retrieve-only and rejects `execute`.
+
+## Intent
+
+- Mirror RouterOS `execute` semantics. Input is a CLI string; output is
+  console-shaped text (or structured records for path+verb writes) wrapped in
+  the standard envelope. This includes write-shaped add/set/remove.
+- Validation is two-stage (see constitution: validation): `:put [:parse
+  "<cmd>"]` is a **syntax** gate only — it does not catch unknown attributes or
+  bad values. Semantic validation needs `/console/inspect` or the server's own
+  re-validation on the write round-trip. A clean parse is necessary, not
+  sufficient.
+- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
+  `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
+  whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
+  canonicalizer is for canonicalization only — never the structured predicate
+  (widening `structured` is a product regression). Pinned by
+  `test/unit/execute-canonicalize-contract.test.ts`; the parser-vendoring
+  preconditions live in the `canonicalizeExecuteCommand` doc-comment.
+- REST adapter prefers structured path-POST when the CLI canonicalizes to
+  path+verb+attrs (`POST /rest/<path>/<verb>` → `{"ret":"<.id>"}`, clean typed
+  errors); falls back to `POST /rest/execute {"script":"<cli>"}` for
+  non-path-shaped console commands.
+- **RouterOS REST verb mapping — the `POST` ≠ `add` trap (surfaced explicitly).**
+  RouterOS REST maps `GET`→print, **`PUT`→add**, `PATCH`→set, `DELETE`→remove,
+  and `POST`→the *universal* "run any console command" method ([REST API → HTTP
+  Methods](https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST%2BAPI#RESTAPI-HTTPMethods)).
+  So the naive REST assumption `POST`=create is **wrong** — `PUT` is RouterOS's
+  create. centrs sidesteps the trap with the explicit verb-in-path form
+  `POST /rest/<path>/<verb>` (e.g. `POST /rest/ip/route/add`): add/set/remove are
+  **named**, never inferred from the HTTP method. The mapping is documented here
+  so the trap is impossible to miss at centrs's `api` surface.
+- native-api adapter issues the same write as a tagged `talk` sentence; its
+  `!trap` strings share one error table with REST `detail`. REST and native
+  classify the same RouterOS fault to the same `routeros/*` code: both feed the
+  router-side fault string through `mapRouterOsError`
+  (`src/core/routeros-errors.ts`). In `RestAdapter.mapHttpFailure`
+  (`src/protocols/adapter.ts`), transport-level HTTP statuses are classified
+  first — 401/403 → `transport/auth-failed`, 5xx → retryable
+  `transport/connection-closed` (kept distinct so the fanout retry allowlist
+  can retry drops without retrying real router rejections) — and everything
+  else passes its `detail`/body plus the HTTP status through
+  `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
+  a hand-rolled `routeros/*` table on the REST side.
+- Output is *string*-shaped for script-mode; richer parsing is a future
+  concern. The envelope must still distinguish RouterOS errors from successful
+  runs (a 200 with a RouterOS error string is still an error — see
+  constitution: error model).
+- **Print width / column wrapping (JG-04).** RouterOS wraps `print` output to the
+  terminal width, so each transport handles width differently. **mac-telnet** is
+  the only one that negotiates a size: `src/protocols/mac-telnet-console.ts`
+  answers the device's terminal-size probe with a deliberately tall/wide screen,
+  so captured columns are neither wrapped nor paginated. **SSH execute** runs
+  *without* a pseudo-tty (`src/protocols/ssh.ts`), so RouterOS emits no
+  terminal-wrapped output to begin with — there is nothing to negotiate.
+  **REST/native-api** are not consoles, so terminal width never applies (they
+  return structured records, or a string `ret` for script-mode). There is
+  therefore no per-call `--width` knob today — an explicit width override is
+  deferred until a concrete need appears.
+- Attribute values pass through **verbatim** — centrs does not guess types or
+  coerce them (RouterOS REST tolerates string values; the native API is
+  all-strings). Unlike `jo`-style KV builders, there is no per-value
+  type-forcing escape, because the device, not centrs, owns value typing.
+- On an empty-CDB resolution failure, execute (like retrieve) emits the
+  `tip/no-devices` tip, steering toward `centrs devices discover` /
+  `centrs settings`.
+- Protocol surfaces are native API, REST, mac-telnet, and SSH. RoMON and
+  WinBox Terminal are later. SNMP is retrieve-only and must reject execute.
+- For a MAC target not resolved from CDB, auto-selection defaults to
+  mac-telnet. Callers that want IP-level execution may opt into ARP-based
+  MAC → IP resolution with `--resolve arp` (plus `--via native-api`/`rest-api`)
+  before protocol selection.
+- When the resolved transport is mac-telnet and **no** username or password is
+  resolved from any source, execute emits a `tip/mac-telnet-no-credentials`
+  pointer: mac-telnet logs in with RouterOS credentials over **MTWEI** (MD5 is
+  refused by current RouterOS), so an empty login is rejected at connect time.
+  It is a tip, not an error — the call is still attempted.
+- Default output is human-readable `text`; pass `--json`/`--format json`
+  (or set `CENTRS_FORMAT=json`) for the structured envelope. Errors always
+  render as `[code] summary` + `Fix:` lines in text mode.
+- CDB comment-kv metadata may provide per-target `via`, `port`, and `ssh-key`
+  overrides; CLI/API arguments still win.
+- RoMON and WinBox Terminal are lower priority than mac-telnet until their
+  validation, tooling, and CI story are grounded.
+
+## Flags
+
+| Flag                            | Behavior                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------- |
+| `--via <protocol>`              | Pin the transport (`native-api`, `rest-api`, `ssh`, or `mac-telnet`). No silent downgrade. A bare MAC target defaults to `mac-telnet`. |
+| `--host <host\|url>`            | Override the resolved host or base URL for the target.                                 |
+| `--port <n>`                    | Override the resolved management port.                                                 |
+| `--username` (alias `--user`, `-u`) / `--password` | RouterOS credentials; fall back to `CENTRS_USERNAME` / `CENTRS_PASSWORD`.              |
+| `--ssh-key <path>`              | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the ssh-agent. |
+| `--insecure`                    | Accept a new SSH host key (`--via ssh`) or a self-signed `api-ssl` TLS cert. Default verifies. |
+| `--cdb-file` / `--cdb-password` | Read target credentials from (and decrypt) a WinBox CDB file.                          |
+| `--resolve <none\|arp>`         | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.          |
+| `--timeout <duration>`          | Per-request timeout. REST: ≤ 60s; other transports may allow longer.                  |
+| `--validate[=false]`            | Run transport-appropriate preflight validation before execution (default `true`): REST/native use `:parse` + `/console/inspect`; mac-telnet and ssh use a single console `:parse` (covers syntax + unknown-attribute). |
+| `--strict`                      | Treat any warning on a successful run as an error (`ok: false`, nonzero exit), like `-Werror`. Default is lenient (`ok: true` + `warnings`). |
+| `--yes`                         | Confirm write-shaped add/set/remove commands in non-interactive runs.                  |
+| `--max-bytes <n>`               | Byte budget for the rendered envelope; excess output is truncated with a warning + `meta.truncated` (not an error), matching `retrieve`. (Renamed from `--max-results`.) |
+| `--format <text\|json\|yaml>`   | Output format (alias `--json`). Defaults to `text`; `CENTRS_FORMAT` sets the default.  |
+| `--where <attr>=<value>`        | Device-class selector — run across every CDB record whose stored fact/comment-kv matches (e.g. `--where board=RB5009 /system/package/check-for-updates`). Repeatable (AND). See constitution: target selection. |
+| `--`                            | End-of-options marker. Every token after `--` is taken as the literal RouterOS command, even flag-shaped ones — e.g. `centrs execute $R -- /interface print where disabled=yes`. Use it when the command contains tokens that would otherwise be claimed as centrs flags; otherwise the command must be quoted as a single argument. |
+
+## SSH key selection
+
+Signed off (settings names): SSH transports use one shared setting, `sshKey`,
+exposed as `--ssh-key <path>`, `CENTRS_SSH_KEY`, and the CDB comment-kv token
+`ssh-key=<path>`. Precedence follows the constitution: defaults → config → CDB
+comment-kv → env → CLI/API. When unset, centrs honors the user's system SSH
+configuration and agent exactly as `ssh` would; setting `--ssh-key` is an
+explicit per-invocation override. The `ssh-key` setting (and `--insecure`) landed
+with the first SSH consumer, `transfer`/sftp; `execute / ssh` (this command) and
+`terminal / ssh` followed as separate transports over the same host-`ssh`
+plumbing (`src/protocols/ssh.ts`) — all three SSH cells are `CHR-passed`.
+
+Over SSH — like mac-telnet — `execute` is a **console transport**: it runs a
+CLI line and returns text (`SshExecClient`, one `ssh user@host "<command>"` per
+command; validation reuses the same `:put [:parse …]` gate), so structured
+path-POST reads and `/console/inspect` are `rest-api`/`native-api`-only. Green via
+`test/integration/execute-ssh.test.ts` (S1–S4); see `src/protocols/ssh.ts` for the
+no-PTY/clean-output grounding.
+
+`ssh-key` stores a private key **path**, never private key material. The resolved
+path may appear in `meta.settings.sshKey` with its source so bug reports can
+explain why a key was selected. Private key contents, passphrases, agent socket
+contents, and any inline key material are always sensitive and must be listed in
+`error.redactable_fields` if they appear in structured error data; key paths are
+redacted only if the caller marks them sensitive or the error couples them with
+key material.
+
+## mac-telnet L2 validation
+
+Decided (2026-06-06): the real-L2 integration path is `@tikoci/quickchr`'s
+host-side L2 capture. The host runs a TCP server and the CHR gets a
+`socket-connect` NIC; QEMU streams every guest Ethernet frame to the host
+length-prefixed (4-byte BE length + raw frame), and **a frame written back is
+injected into the guest — exactly the MAC-Telnet primitive**. Loopback-only,
+cross-platform, no root and no native raw-L2 helper; REST/native-API keep a
+separate user-mode NIC with hostfwd. Prefer `socket-connect` over `socket-mcast`
+(the multicast netdev is broken on macOS — QEMU sets only `SO_REUSEADDR` where
+macOS needs `SO_REUSEPORT`; mcast works on Linux/CI). Grounding: quickchr
+`docs/mndp.md`, `examples/mndp/`, `test/lab/mndp/REPORT.md`.
+
+`execute / mac-telnet` is now **`CHR-passed`** end to end over real L2 against
+stock CHR 7.23.1 (`test/integration/mac-telnet-console.test.ts` +
+`mactelnet-l2-bridge.ts`, examples 19–21): `executeEnvelope` resolves a MAC
+target, the `MacTelnetAdapter` opens a `MacTelnetConsole` over a UDP datagram
+transport, and reads, writes (REST-verified), and validation-rejects all work.
+
+How it is wired:
+
+- **Console transport, not request/response.** mac-telnet drives the RouterOS
+  interactive console (`src/protocols/mac-telnet-console.ts`): it answers the
+  login terminal-size probe, auto-clears the first-login license, syncs on the
+  `[user@identity] >` prompt, emulates the CR/LF screen, and strips the echoed
+  command + trailing prompt to return clean per-command output. The orchestrator
+  runs the **raw CLI line** over the console (no structured path-POST / tagged
+  talk); the `MacTelnetAdapter` reports `retrieve`/`inspect` as
+  `transport/capability-unsupported` (mac-telnet is execute/terminal only).
+- **Validation is one console `:parse`.** Over the console, `:put [:parse "<cmd>"]`
+  prints both `syntax error` and `bad parameter <name>`, so a single gate covers
+  syntax **and** the unknown-attribute (semantic) check — no `/console/inspect`
+  table parsing. Maps to `validation/syntax` / `validation/unknown-attribute`,
+  same codes as REST/native (see `docs/CONSTITUTION.md`, validation).
+- **Auth (grounded):** MTWEI is required; a stock device offers a 16-byte MD5 salt
+  but rejects the MD5 proof, so centrs advertises MTWEI (`src/protocols/mtwei.ts`)
+  by default. `END_AUTH` ≠ success (a failed login emits `END_AUTH` then "Login
+  failed" + `END`) → `transport/auth-failed`.
+- **Console quirks to know:** a successful write **prints no output** (no `.id`,
+  unlike REST/native — `data.ret` is empty on a successful add); and there is a
+  ~10s terminal-negotiation stall on every login (a latency cost, not a
+  correctness issue — see `commands/terminal/README.md` for the optional fix).
+- **Delivery:** the UDP transport sends to `--host`/`--port` (default L2 broadcast
+  `255.255.255.255:20561`); the device replies to our source IP:port, and the
+  in-packet MACs do the addressing. The CHR test points `--host`/`--port` at the
+  loopback L2 bridge.
+
+Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
+`test/unit/execute.test.ts`); callers wanting IP-level execution opt into ARP
+(`--resolve arp` + `--via native-api`/`rest-api`).
+
+## Open shape questions
+
+- ~~How to expose multi-line / async / progress output~~ — **resolved:**
+  open-ended follow/streaming reads are the separate read-only `stream` verb
+  (NDJSON stream of envelopes; see `commands/stream/README.md`). `execute` stays
+  single-shot read/write; it does not grow a follow mode.
+- ~~Whether `--strict` should reject "succeeded with stderr-like content."~~ —
+  **decided:** `--strict` promotes any warning on an otherwise-successful run to
+  `ok: false` (nonzero exit), like `-Werror`; the default stays lenient
+  (`ok: true` with the warning in the `warnings` channel). Tracked code
+  follow-up; the flag is in the table above.
+
+These are deferred refinements to the already-grounded single-shot envelope,
+not blockers for the `rest-api`/`native-api` cells.

package/commands/execute/examples.md

@@ -0,0 +1,353 @@
+# execute — examples
+
+Each numbered example is an executable spec, run against a CHR 7.23 router booted
+by `@tikoci/quickchr`: `test/integration/execute.test.ts` covers examples 1–11
+over REST and 12–18 over the native API; `test/integration/mac-telnet-console.test.ts`
+covers examples 19–21 over mac-telnet (real L2 via the `socket-connect` bridge).
+If a line here is not exercised by a test, the test file is wrong; if a line
+passes only with `validate=false`, the **implementation** is wrong (see
+`docs/CONSTITUTION.md`).
+
+`$R` is `<host>:<rest-port>` resolved by quickchr. `$A` is `<host>` and
+`$API_PORT` is the native API port (`chr.ports.api`). `$MAC` is the device MAC and
+`$MT_HOST`/`$MT_PORT` are the mac-telnet UDP delivery endpoint (the loopback L2
+bridge in CI). `$U` / `$P` are CHR credentials provided by the test harness.
+`$ID` is the `.id` returned by the preceding add example in the same transport
+section.
+
+All write-shaped examples use `--yes` as the explicit non-interactive
+confirmation flag. Without `--yes`, non-TTY writes fail before validation or any
+RouterOS mutation; with a TTY, the CLI prompts before running the write.
+
+## rest-api (`--via rest-api`)
+
+### 1. Add an address with structured path-POST
+
+Must succeed with `validate=true` (default). The CLI canonicalizes the command
+as path `/ip/address`, verb `add`, and attributes `address`, `interface`, and
+`comment`; the REST adapter uses the structured path-command endpoint rather
+than script mode.
+
+```bash
+centrs execute $R '/ip/address/add address=198.51.100.10/32 interface=ether1 comment="centrs-execute-rest"' --via rest-api --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data.ret` is a RouterOS internal id matching `/^\*[0-9A-F]+$/`,
+`data[".id"]` carries the same value for downstream set/remove examples,
+`meta.via=rest-api`, and `meta.validation.source` includes both
+`:put [:parse ...]` and `/console/inspect`.
+
+### 2. Set the address by `.id`
+
+```bash
+centrs execute $R "/ip/address/set numbers=$ID comment=centrs-execute-rest-set" --via rest-api --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` is empty or contains the RouterOS success record,
+`meta.via=rest-api`, and re-reading `/ip/address/$ID` shows
+`comment="centrs-execute-rest-set"`.
+
+### 3. Remove the address by `.id`
+
+```bash
+centrs execute $R "/ip/address/remove numbers=$ID" --via rest-api --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `meta.via=rest-api`. A subsequent retrieve of
+`/ip/address` does not contain `$ID`.
+
+### 4. Run a non-path-shaped console command through `/rest/execute`
+
+The command is a script-shaped console expression, not a slash path plus verb,
+so REST must use the `/rest/execute` fallback.
+
+```bash
+centrs execute $R ':put [/system/identity/get name]' --via rest-api --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is string-shaped (`data.output` or `data.ret`) and
+contains the CHR identity name, `meta.via=rest-api`, and
+`meta.validation.syntax=true`. `meta.validation.semantic` is absent or marked
+`not-applicable` because `/console/inspect` validates path-shaped commands, not
+arbitrary script expressions.
+
+### 5. Syntax reject from `:put [:parse ...]`
+
+Malformed CLI is rejected by the syntax gate before semantic validation or the
+write round-trip.
+
+```bash
+centrs execute $R '/ip/address/add address="unterminated interface=ether1' --via rest-api --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
+the RouterOS parse error string from `:put [:parse ...]`, `meta.via=rest-api`,
+and no address is added.
+
+### 6. Semantic reject that `:parse` accepts
+
+Grounded on CHR 7.23: `:put [:parse "/ip/address/add no-such-arg=x"]` accepts
+unknown attributes, so centrs must not treat a clean parse as semantic success.
+`/console/inspect` rejects the attribute before the write.
+
+```bash
+centrs execute $R '/ip/address/add address=198.51.100.11/32 interface=ether1 no-such-arg=x' --via rest-api --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
+`error.cause.attribute="no-such-arg"` (or equivalent structured field),
+`meta.validation.syntax=true`, `meta.validation.source=/console/inspect`, and
+no address is added. This example is the product claim: syntax validation and
+semantic validation are separate gates.
+
+### 7. RouterOS error on `/rest/execute` HTTP 200
+
+Assumption to verify on CHR 7.23: a script-mode RouterOS `:error` returns HTTP
+200 from `/rest/execute` with a RouterOS failure string in the body. That body is
+still a failed RouterOS result, not successful command output.
+
+```bash
+centrs execute $R ':error "centrs execute fixture trap"' --via rest-api --username $U --password $P
+```
+
+Envelope: `ok: false`, `error.code=routeros/command-failed` (or the more
+specific grounded `routeros/*` mapping for the returned string),
+`error.cause` preserves the original RouterOS string, and `meta.via=rest-api`.
+This uses the same mapping table as native API `!trap` errors.
+
+### 8. Pinned REST has no silent downgrade
+
+`/rest/execute` is required for arbitrary script-shaped commands over REST. If
+that capability is unavailable or disabled, `--via rest-api` must fail instead
+of silently trying native API, SSH, or mac-telnet.
+
+```bash
+centrs execute $R ':put "requires rest execute"' --via rest-api --username $U --password $P
+```
+
+Envelope when REST cannot perform the operation: `ok: false`,
+`error.code` starts with `transport/`, `meta.via=rest-api`, and
+`meta.warnings` does not contain a protocol-downgrade warning. When REST can
+perform it, the command succeeds over REST and still does not downgrade.
+
+### 9. Non-TTY write without `--yes` is refused
+
+```bash
+centrs execute $R '/ip/address/add address=198.51.100.12/32 interface=ether1 comment="missing-confirm"' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`,
+`meta.via=rest-api`, no validation transport call is made, and no address is
+added.
+
+### 10. TTY write prompts before mutation
+
+```bash
+centrs execute $R '/ip/address/add address=198.51.100.13/32 interface=ether1 comment="tty-confirm"' --via rest-api --username $U --password $P
+```
+
+When stdin is a TTY, the CLI prompts for write confirmation. Answering `no` (or
+EOF) returns `ok: false` with `usage/confirmation-required` and no mutation;
+answering `yes` continues to validation and the write, returning the same
+success envelope shape as example 1.
+
+### 11. `--validate=false` probes without preflight gates
+
+This escape hatch skips centrs syntax and semantic preflight validation but does
+not suppress RouterOS errors from the write round-trip.
+
+```bash
+centrs execute $R '/ip/address/add address=198.51.100.14/32 interface=ether1 no-such-arg=x' --via rest-api --username $U --password $P --yes --validate=false
+```
+
+Envelope: `ok: false`, `error.code=routeros/unknown-attribute` (or the grounded
+RouterOS `routeros/*` code for `unknown parameter no-such-arg`),
+`error.cause` preserves the original RouterOS string, `meta.via=rest-api`, and
+`meta.validation.enabled=false`.
+
+## native-api (`--via native-api`)
+
+The same execute contract over the RouterOS binary API. Validation still runs
+through `:put [:parse ...]` and `/console/inspect`, issued as native API
+commands. Attribute values are strings because the binary API does not carry
+JSON scalar types.
+
+### 12. Add an address with native `talk`
+
+```bash
+centrs execute $A '/ip/address/add address=198.51.100.20/32 interface=ether1 comment="centrs-execute-api"' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` (or `data.ret`) is the new RouterOS
+internal id, `meta.via=native-api`, and `meta.validation.source` includes both
+`:put [:parse ...]` and `/console/inspect`.
+
+### 13. Set the native-created address by `.id`
+
+```bash
+centrs execute $A "/ip/address/set numbers=$ID comment=centrs-execute-api-set" --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `meta.via=native-api`, and re-reading `/ip/address/$ID`
+shows `comment="centrs-execute-api-set"`.
+
+### 14. Remove the native-created address by `.id`
+
+```bash
+centrs execute $A "/ip/address/remove numbers=$ID" --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `meta.via=native-api`. A subsequent retrieve of
+`/ip/address` does not contain `$ID`.
+
+### 15. Native syntax reject from `:parse`
+
+```bash
+centrs execute $A '/ip/address/add address="unterminated interface=ether1' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
+the RouterOS parse error string, `meta.via=native-api`, and no address is added.
+
+### 16. Native semantic reject after clean parse
+
+```bash
+centrs execute $A '/ip/address/add address=198.51.100.21/32 interface=ether1 no-such-arg=x' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
+`meta.validation.syntax=true`, `meta.validation.source=/console/inspect`, and
+no address is added. The failure must be classified as validation, not as a
+native API `!trap`, because the semantic gate catches it before the write.
+
+### 17. Native `!trap` uses the shared RouterOS error table
+
+With validation disabled, the unknown attribute reaches RouterOS and native API
+returns a `!trap` message.
+
+```bash
+centrs execute $A '/ip/address/add address=198.51.100.22/32 interface=ether1 no-such-arg=x' --via native-api --port $API_PORT --username $U --password $P --yes --validate=false
+```
+
+Envelope: `ok: false`, `error.code=routeros/unknown-attribute` (the same code as
+REST for the same RouterOS string), `error.cause` preserves the original
+`!trap` message, `meta.via=native-api`, and `meta.validation.enabled=false`.
+
+### 18. Native non-TTY write without `--yes` is refused
+
+```bash
+centrs execute $A '/ip/address/add address=198.51.100.23/32 interface=ether1 comment="api-missing-confirm"' --via native-api --port $API_PORT --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`,
+`meta.via=native-api`, no validation command is sent, and no address is added.
+
+## mac-telnet (`--via mac-telnet`)
+
+Layer-2 execute over the RouterOS interactive console (UDP/20561). `$MAC` is the
+device MAC; `$MT_HOST`/`$MT_PORT` are the UDP delivery endpoint (L2 broadcast in
+the field, the `quickchr` loopback L2 bridge in CI). Validation over mac-telnet
+is a **single console `:put [:parse …]`** — it reports both `syntax error` and
+`bad parameter <name>`, so it covers the syntax *and* the unknown-attribute gate
+at once (no `/console/inspect` table parsing). The console opens through a
+first-login license screen (auto-answered) and a ~10s terminal-negotiation stall;
+**a successful write prints nothing** over the console (no `.id`/`ret`, unlike
+REST/native). Examples 19–21 are green via `bun run test:integration`
+(`test/integration/mac-telnet-console.test.ts`, CHR 7.23.1) over the real L2
+bridge; the console reader is also exercised directly in the same test.
+
+### 19. Read a command over mac-telnet
+
+```bash
+centrs execute $MAC '/system/identity/print' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is the console output and
+contains the device identity (cross-checked against REST). `meta.validation.source`
+is `:put [:parse ...] over mac-telnet`.
+
+### 20. Write (add) over mac-telnet
+
+```bash
+centrs execute $MAC '/ip/address/add address=198.51.100.40/32 interface=ether1' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is empty (a successful
+console write prints nothing — there is no `.id` to return). A subsequent REST
+read of `/ip/address` shows `198.51.100.40`.
+
+### 21. Validation rejects an unknown attribute over mac-telnet
+
+```bash
+centrs execute $MAC '/ip/address/add address=198.51.100.41/32 interface=ether1 no-such-arg=x' --via mac-telnet --host $MT_HOST --port $MT_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
+`meta.via=mac-telnet`, and no address is added — the console `:parse` gate
+catches `no-such-arg` before any mutation.
+
+## ssh (`--via ssh`)
+
+Execute over the RouterOS SSH server using the **host `ssh`** client. RouterOS
+grants no pseudo-tty, but `ssh user@host "<command>"` runs one single-line console
+command and returns **clean** output (no prompt, no ANSI, no echo) — so each
+execute is one `ssh` invocation (a fresh login, like the SFTP batch client), and
+the only post-processing is trimming the console's column padding. Validation is
+the **same single console `:put [:parse …]`** as mac-telnet (over SSH it returns
+the identical `(evl …)` / `bad parameter <name>` strings), so syntax and the
+unknown-attribute gate are covered at once. Key auth is the path (`--ssh-key` /
+agent); `--insecure` accepts the device's host key. `$SSH_PORT` is the SSH port,
+`$KEY` the private key. Examples S1–S4 are green via `bun run test:integration`
+(`test/integration/execute-ssh.test.ts`, CHR 7.23.1).
+
+### S1. Read a command over ssh
+
+```bash
+centrs execute 127.0.0.1 '/system/identity/print' --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure
+```
+
+Envelope: `ok: true`, `meta.via=ssh`, `data.ret` is the cleaned console output and
+contains the device identity (cross-checked against REST). `meta.validation.source`
+is `:put [:parse ...] over ssh`.
+
+### S2. Multi-line read returns cleaned, column-aligned output
+
+```bash
+centrs execute 127.0.0.1 '/system/resource/print' --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure
+```
+
+Envelope: `ok: true`; `data.ret` contains the running RouterOS version (each line
+trimmed of trailing padding, CRLF normalized).
+
+### S3. Write (add) over ssh
+
+```bash
+centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.50/32 interface=ether1' --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure --yes
+```
+
+Envelope: `ok: true`, `meta.via=ssh`, `data.ret` empty (a successful console write
+prints nothing). A subsequent REST read of `/ip/address` shows `198.51.100.50`.
+
+### S4. Validation rejects an unknown attribute over ssh
+
+```bash
+centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.51/32 interface=ether1 bogus=x' --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`, `meta.via=ssh`,
+and no address is added — the console `:parse` gate catches `bogus` pre-mutation.
+
+## Protocol selection notes
+
+For an unresolved MAC target, execute auto-selection defaults to mac-telnet
+rather than ARP-based IP resolution:
+
+```bash
+centrs execute $MAC '/system/identity/set name=chr-via-mac' --username $U --password $P --yes
+```
+
+Envelope: `meta.via=mac-telnet` when `$MAC` is not resolved from CDB and no
+`--via` is pinned (delivery defaults to L2 broadcast; override with
+`--host`/`--port`). If the caller wants IP-level REST or native API execution,
+they must opt into MAC-to-IP resolution (`--resolve arp` + `--via …`) before
+protocol selection.