@tikoci/centrs 0.1.0 → 0.1.2

package/commands/api/examples.md

@@ -0,0 +1,325 @@
+# api — examples
+
+Each numbered example is an executable spec, asserted by CHR integration tests
+(booted by `@tikoci/quickchr`): `test/integration/api.test.ts` (rest-api
+examples), `test/integration/api-native.test.ts` (native-api examples, N…), and
+`test/integration/api-listen.test.ts` (streaming examples, L…), with example N ↔
+assertion N. 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`](../../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`). `$U` / `$P` are CHR
+credentials provided by the harness. `$ID` is the `.id` returned by the preceding
+add in the same transport section. All write-shaped examples pass `--yes`.
+
+## rest-api (`--via rest-api`, the default)
+
+### 1. GET a list
+
+```bash
+centrs api $R ip/address --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is an array of rest-style records,
+`meta.via=rest-api`, `meta.validation.source` includes `/console/inspect request=child`.
+
+### 2. Endpoint normalization variants resolve to one path
+
+```bash
+centrs api $R "/rest/ip/address" --username $U --password $P
+centrs api $R "rest/ip/address" --username $U --password $P
+centrs api $R "ip address" --username $U --password $P
+```
+
+Each resolves to the same canonical path; `meta.request.path == "/ip/address"`
+and the `data` array matches example 1.
+
+### 3. GET a singleton
+
+```bash
+centrs api $R system/resource --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a single object (not an array) with `uptime`,
+`version`, etc.
+
+### 4. PUT add (RouterOS create; documents the PUT≠POST trap)
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.10/32 -f interface=ether1 -f comment=centrs-api-rest --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` matches `/^\*[0-9A-F]+$/`, `meta.via=rest-api`.
+A subsequent GET of `/ip/address` contains the new row.
+
+### 5. PATCH set by id-in-path
+
+```bash
+centrs api $R ip/address/$ID -X PATCH -f comment=centrs-api-rest-set --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; re-reading `ip/address/$ID` shows the new comment.
+
+### 6. DELETE remove by id-in-path
+
+```bash
+centrs api $R ip/address/$ID -X DELETE --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; a subsequent GET of `/ip/address` does not contain `$ID`.
+
+### 7. Raw JSON body with `-d`
+
+```bash
+centrs api $R ip/address -X PUT -d '{"address":"198.51.100.11/32","interface":"ether1"}' --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### 8. Body from stdin with `--input -`
+
+```bash
+echo '{"address":"198.51.100.12/32","interface":"ether1"}' | centrs api $R ip/address -X PUT --input - --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### 9. Server-side filter with `--query`
+
+```bash
+centrs api $R interface --query type=ether --username $U --password $P
+```
+
+Envelope: `ok: true`, every returned record has `type=ether`; the request carried
+a REST `.query` (not client-side filtering).
+
+### 10. Projection with `--proplist`
+
+```bash
+centrs api $R ip/address --proplist address,interface --username $U --password $P
+```
+
+Envelope: `ok: true`, each record has only the requested properties (plus `.id`).
+
+### 11. Validation rejects an unknown attribute before the write
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.13/32 -f interface=ether1 -f no-such-arg=x --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
+`meta.validation.source=/console/inspect`, and no address is added.
+
+### 12. Validation rejects an unknown path
+
+```bash
+centrs api $R ip/no-such-menu --username $U --password $P
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-path`, no request issued.
+
+### 13. `--raw` success prints the bare RouterOS body
+
+```bash
+centrs api $R ip/address --raw --username $U --password $P
+```
+
+stdout is the bare RouterOS JSON array (no `meta`/`warnings`); validation is
+skipped; exit code 0.
+
+### 14. `--raw` RouterOS error → stderr + nonzero exit
+
+```bash
+centrs api $R ip/address -X PUT -f address=not-an-ip -f interface=ether1 --raw --username $U --password $P --yes
+```
+
+stdout is empty; stderr carries the RouterOS error payload as JSON; exit code is
+nonzero.
+
+### 15. Mutating + non-TTY + no `--yes` is refused
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.14/32 -f interface=ether1 --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`, no request
+issued, no address added. (Holds under `--raw` too.)
+
+### 16. POST run a console command via `/rest/execute`
+
+```bash
+centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
+`meta.validation.semantic=not-applicable` (script, not a path).
+
+### 17. `--via rest-api --listen` is rejected
+
+```bash
+centrs api $R ip/address --listen --via rest-api --username $U --password $P
+```
+
+Envelope: `ok: false`, `error.code=transport/capability-unsupported` (REST cannot
+follow); no silent open-ended poll.
+
+### 18. `--query` not-equal maps to a negated stack word
+
+```bash
+centrs api $R interface --query type!=ether --username $U --password $P
+```
+
+Envelope: `ok: true`, no returned record has `type=ether`; the request carried
+REST `.query` words `["type=ether","#!"]` (eq then NOT-top).
+
+### 19. `--raw-query` expresses OR
+
+```bash
+centrs api $R interface --raw-query type=ether --raw-query type=loopback --raw-query '#|' --username $U --password $P
+```
+
+Envelope: `ok: true`, returns the union of `ether` and `loopback` interfaces; the
+raw words are passed through verbatim as `.query` (REST) / `?` words (native).
+
+### 20. Bounded `duration=` command returns a `.section` array (not a stream)
+
+```bash
+centrs api $R interface/monitor-traffic -X POST -f interface=ether1 -f duration=5s --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` is an **array** of `.section`-keyed records (one per
+~second), `meta.via=rest-api`. This is an ordinary bounded call — no `--listen`,
+no NDJSON. `monitor-traffic` is a command (not `print`/`get`), so it is a
+`POST` and write-classed (needs `--yes`); centrs never relaxes that to read-only.
+(REST bounds it at the 60 s cap; native has no cap.)
+
+### 21. GET one row by id together with `--proplist`
+
+```bash
+centrs api $R ip/address/$ID --proplist address --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a **single object** (not an array) carrying only
+the projected property `address` (RouterOS omits `.id` unless it is in the
+proplist). Combining an id with `--query`/`--proplist` folds the id into the REST
+`.query` (`.id=$ID`) and rides a `POST …/print`, then unwraps the one row —
+matching the native `?.id=` read. (Plain id-only reads still use the `GET …/$ID`
+URL form; see example 5's re-read.)
+
+## native-api (`--via native-api`)
+
+The same contract over the binary API. Validation still runs through
+`/console/inspect`, issued as native commands. Values are strings.
+
+### N1. GET a list
+
+```bash
+centrs api $A interface -X GET --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is an array of rest-style records (string values),
+`meta.via=native-api`.
+
+### N2. PUT add (returns `.id`)
+
+```bash
+centrs api $A ip/address -X PUT -f address=198.51.100.20/32 -f interface=ether1 --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### N3. PATCH set by id (id → `=.id=` word)
+
+```bash
+centrs api $A ip/address/$ID -X PATCH -f comment=centrs-api-native-set --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; re-reading shows the new comment.
+
+### N4. DELETE remove by id (id → `=.id=` word)
+
+```bash
+centrs api $A ip/address/$ID -X DELETE --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; the row is gone.
+
+### N5. GET one by id (→ `print ?.id=`)
+
+```bash
+centrs api $A ip/address/$ID2 -X GET --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a single object whose `.id` is `$ID2`.
+
+### N6. Validation rejects an unknown attribute over native
+
+```bash
+centrs api $A ip/address -X PUT -f address=198.51.100.21/32 -f interface=ether1 -f no-such-arg=x --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`, no row added —
+caught by the inspect gate, not a native `!trap`.
+
+### N7. `--raw` over native
+
+```bash
+centrs api $A interface --raw --via native-api --port $API_PORT --username $U --password $P
+```
+
+stdout is the bare rest-style array (string values); exit code 0.
+
+### N8. POST run a console command via native `/execute`
+
+```bash
+centrs api $A execute -X POST -f script=':put [/system/identity/get name]' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` contains the CHR identity.
+
+## listen / `--stream` (native-api only)
+
+Open-ended follow. `--stream` is the primary flag; `--listen` is an accepted
+alias and a trailing `/listen` endpoint segment infers it. Output is NDJSON: one
+envelope per change frame, then a terminating summary envelope.
+
+### L1. `--stream` streams a change as an NDJSON frame, then a summary
+
+```bash
+centrs api $A ip/address --stream --count 1 --via native-api --port $API_PORT --username $U --password $P
+```
+
+While listening, the harness adds an address over REST. stdout is NDJSON: at least
+one envelope frame for the new row (`meta.operation.stream.kind=frame`), then a
+final summary envelope (`meta.operation.stream.kind=summary`,
+`data.stopReason=count-reached`, `data.frames>=1`). Exit code 0 (stream started
+cleanly).
+
+### L2. A deletion frame carries `.dead`
+
+```bash
+centrs api $A ip/address --stream --duration 3s --via native-api --port $API_PORT --username $U --password $P
+```
+
+The harness removes a pre-seeded address; an emitted frame's record carries
+`.dead=true` (a minimal `{ ".id", ".dead" }` record, per the CHR-grounded
+`commands/api/AGENTS.md`).
+
+### L3. `/listen` endpoint infers native + streaming
+
+```bash
+centrs api $A "ip/address/listen" --count 1 --port $API_PORT --username $U --password $P
+```
+
+No `--stream` / `--via` given; the `/listen` endpoint infers `--stream` and
+`--via native-api` (`meta.via=native-api`). Same NDJSON shape as L1.
+
+### L4. Bounded `--duration` reports its stop reason
+
+```bash
+centrs api $A ip/address --stream --duration 2s --via native-api --port $API_PORT --username $U --password $P
+```
+
+With no change during the window, the stream ends after ~2 s with a summary
+envelope whose `data.stopReason=duration-elapsed`. Exit code 0.

package/commands/btest/README.md

@@ -17,7 +17,10 @@ on the centrs **server**; `test/integration/btest-client.test.ts` runs the centr
 **client** against a real RouterOS `/tool/bandwidth-server` over a host→guest
 `tcp:2000` forward — unauthenticated TCP receive, an **EC-SRP5 client proof
 verified by RouterOS's own verifier**, and a wrong-password reject. TCP
-multi-connection (`connection-count > 1`) data fan-out is a follow-up. See
+multi-connection (`connection-count > 1`) data fan-out is implemented for
+unauthenticated tests (the client joins the negotiated extra connections; the join
+format is grounded against RouterOS 7.23.1); authenticated sessions stay
+single-stream. See
 `docs/MATRIX.md` ("Peer measurement (`btest`)") for the cell states — that is the
 only status surface. v1 scope: **both** modes (client + server), **EC-SRP5 +
 unauthenticated** auth, **TCP and UDP** tests. Legacy pre-6.43 double-MD5 is out of
@@ -85,7 +88,7 @@ centrs btest server [--authenticate[=false]] [--user U] [--password P] \
 | `--direction <receive\|transmit\|both>` | `direction`, default `receive` | `receive` = download (server→client), `transmit` = upload. |
 | `--duration <dur>` | `duration` | Bounds the run; reuses `parseDuration`. Omit for open-ended (Ctrl-C). |
 | `--interval <dur>` | `interval`, default `1s` | Report cadence (`20ms`..`5s`). One report frame per interval. |
-| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. |
+| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. centrs opens the negotiated extra connections (join format grounded against RouterOS 7.23.1) so throughput aggregates across streams. **Authenticated (EC-SRP5) sessions stay single-stream** — the post-auth token is not captured — and emit a `routeros/btest-connection-count-single-stream` warning. |
 | `--local-udp-tx-size <n>` | `local-udp-tx-size` (28..64000) | **UDP only.** Client→server packet size. |
 | `--remote-udp-tx-size <n>` | `remote-udp-tx-size` (28..64000) | **UDP only.** Server→client packet size. |
 | `--local-tx-speed <bps>` | `local-tx-speed` | Cap on client→server rate (bits/sec). |
@@ -120,10 +123,20 @@ test, data then flows on the server's allocated UDP ports
 from sequence gaps. For a TCP test, the bulk data rides `connection-count` TCP
 connections and goodput is measured on the data stream (TCP/IP headers excluded,
 matching RouterOS accounting). For multi-connection TCP the server's OK response
-carries a 2-byte **session token**; the extra connections reconnect and present
-that token to join the same test (no re-auth). Throughput and CPU are exchanged
+carries a 2-byte **session token**; the client opens `connection-count − 1`
+additional connections, each presenting a 16-byte join `[token:u16 BE][0x02][0 …]`
+(grounded against RouterOS 7.23.1, direction-independent) to join the same test
+without re-auth, and drives them into the shared counters so throughput aggregates.
+Throughput and CPU are exchanged
 once per `interval` as a 12-byte **status message** on the TCP channel
-(`[0x07][0x80|cpu][00 00][seq u32 LE][bytesReceived u32 LE]`).
+(`[0x07][0x80|cpu][00 00][seq u32 LE][bytesReceived u32 LE]`). The receiver of a
+transmit (server for `transmit`, both peers for `both`) sends this so the
+transmitter paces from the peer's `bytesReceived`. For `direction=both` the
+status frames are **interleaved into the bulk data stream** (no length framing),
+so the client demuxes them out of its receive loop by their structural marker —
+without that feedback the client's TX saturates the link and starves
+server→client RX. RouterOS clears the CPU high bit the centrs client sets, so the
+marker matches on the two reserved zero bytes, not the high bit.
 
 ### Authentication (EC-SRP5)
 
@@ -141,7 +154,7 @@ will not offer EC-SRP5 against an `authenticate=yes` server) maps to
 
 btest runs over time, so it emits **live records** during the run plus a final
 **summary**. v1 keeps the formats simple and **defers a broader JSON-streaming
-decision** — it does *not* adopt the `stream` command's NDJSON-stream-of-envelopes
+decision** — it does *not* adopt `api --stream`'s NDJSON-stream-of-envelopes
 contract yet (see Open questions):
 
 - **`text`** (default) — human-readable live reports during the run
@@ -214,10 +227,11 @@ Decided with the user. Both cells have direct gated `CHR-passed` evidence:
   maps onto the guest bandwidth server on 2000 (the same SLIRP inbound path that
   already carries REST/SSH — no firewall change). The centrs client dials
   `127.0.0.1:<host port>` and proves **TCP receive**, unauth and **EC-SRP5** (its
-  client proof verified by RouterOS's real server verifier), plus a wrong-password
-  reject. **TCP only** — UDP would need the server's datagrams to traverse SLIRP
-  back to the host, which this forward does not provide, so UDP client→server stays
-  loopback/transitive.
+  client proof verified by RouterOS's real server verifier), a wrong-password
+  reject, **TCP multi-connection fan-out** (`connection-count=4`), and **UDP
+  receive/both**. The UDP server→client return needs no UDP forward: it rides the
+  guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`, the same path the server cell
+  uses), which works because the client socket is left unconnected (#86, #88).
 
 The fast/deterministic backstop under both is **centrs client ↔ centrs server
 loopback** (`127.0.0.1`, injected sockets) covering the full client↔server matrix,
@@ -226,32 +240,43 @@ EC-SRP5 both roles, and the option-grammar rejects.
 while implementing the EC-SRP5 framing and the server-side verifier; it is **not**
 an integration test (it cannot run in CI) and **not** part of the long-term plan.
 
-**Honest grounding caveat:** both cells are now directly CHR-passed. The remaining
-transitive-only paths are **UDP client→CHR-server** (the SLIRP reverse-NAT path the
-TCP forward does not cover) and TCP **multi-connection** fan-out — both deferred,
-not yet gated.
+**Honest grounding caveat:** both cells are now directly CHR-passed, **including
+TCP multi-connection fan-out** — `test/integration/btest-client.test.ts` gates a
+centrs client opening `connection-count=4` against a real RouterOS
+`/tool/bandwidth-server`; RouterOS accepts all 3 secondary joins and data flows on
+every connection (`activeConnections: 4`). The *throughput increase* multiple
+streams give is a WAN/latency property and is not observable over the near-zero-
+latency SLIRP loopback, so the gate asserts the fan-out, not a higher number (the
+per-connection drive is asserted deterministically by the loopback unit test).
+**UDP client receive/both is now CHR-gated too** — the server→client return rides
+the guest→host SLIRP gateway, no UDP forward needed (#88). The remaining fan-out
+edge is **authenticated** multi-connection (capturing the EC-SRP5 post-auth token),
+still single-stream.
 
 ## Open questions
 
-- **JSON streaming is deliberately deferred.** btest does not adopt the `stream`
-  command's NDJSON-stream-of-envelopes contract yet; v1 streams `text` / `csv` and
-  returns a single summary envelope for `json` / `yaml`. Revisit a streaming-JSON
-  shape — ideally shared with `stream` — once that contract is settled.
-- **UDP receive/both through SLIRP is unproven.** Before the integration suite
-  relies on server→guest UDP, a **one-shot CHR smoke test** must confirm the path
-  works — i.e. that the RouterOS client originates an initial UDP/NAT probe that
-  opens the SLIRP reverse mapping. Until then the gated UDP coverage is
-  **transmit** (guest→host); TCP already covers both directions.
-- **UDP client→CHR-server and TCP multi-connection are not yet gated.** The direct
-  client→CHR-server gate (`test/integration/btest-client.test.ts`) is **TCP only**;
-  a UDP variant needs the server's datagrams to traverse SLIRP back to the host
-  (the reverse-NAT path), and `connection-count > 1` needs the parallel-stream
-  fan-out. Both remain loopback/transitive until gated. `btest.exe` (wine) is the
-  coding-time grounding peer, not CI.
+- **JSON streaming is deliberately deferred.** btest does not adopt
+  `api --stream`'s NDJSON-stream-of-envelopes contract yet; v1 streams `text` /
+  `csv` and returns a single summary envelope for `json` / `yaml`. Revisit a
+  streaming-JSON shape — ideally shared with `api --stream` — once it has settled.
+- **UDP client receive/both is gated (#88).** The client cell
+  (`test/integration/btest-client.test.ts`) lands real UDP server→client throughput:
+  the return rides the guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`), needing
+  no UDP forward and no quickchr change — it works because the client socket is left
+  unconnected (#86).
+- **Only the server-cell host→guest UDP direction stays unproven.** The server cell
+  gates UDP *transmit* (guest→host, which SLIRP NATs cleanly); the reverse (centrs
+  server → CHR client, host→guest) would need a UDP hostfwd for the data ports, so it
+  is not yet asserted. `btest.exe` (wine) is the coding-time grounding peer, not CI.
+- **Authenticated multi-connection stays single-stream.** Fan-out negotiates the
+  session token from the unauthenticated OK; capturing the EC-SRP5 post-auth token
+  to fan out authenticated tests is a follow-up (#103). centrs warns
+  (`routeros/btest-connection-count-single-stream`) when the realized connection
+  count falls short of the request. The **server-side** secondary-accept is its own
+  follow-up (#100).
 
 ## Out of scope (v1)
 
-Legacy pre-6.43 double-MD5 auth; a UDP client→CHR-server gated test (TCP is gated;
-UDP needs SLIRP reverse-NAT); the ≥3-router "test-through" topology RouterOS
+Legacy pre-6.43 double-MD5 auth; the ≥3-router "test-through" topology RouterOS
 recommends for measuring a *transit* device (centrs is an endpoint peer); TUI/proxy
 btest frontends (later, over the stable core).

package/commands/btest/examples.md

@@ -15,17 +15,19 @@ matrix's honest grounding split (`docs/MATRIX.md`, "Peer measurement (`btest`)")
   loss / direction against the CHR's own `/tool/bandwidth-test` status output
   (CHR 7.23.1, `bun run test:integration`). Examples **4** (wrong-credentials) and
   **5** (multi-connection TCP) are **designed but not yet gated** — the auth-reject
-  path is covered by the loopback unit test, and the multi-stream fan-out is a
-  documented follow-up — so they are not part of the asserted run.
+  path is covered by the loopback unit test, and example 5 is the **server-side**
+  secondary-accept (distinct from the now-gated **client** fan-out in example 11),
+  still a documented follow-up — so they are not part of the asserted run.
 - **Gated `CHR-passed` (client cell): centrs client → CHR bandwidth-server** —
   examples **6** (TCP receive) and **8** (EC-SRP5 client role + wrong-password
   reject) are *also* asserted directly against a real RouterOS
   `/tool/bandwidth-server`, over a host→guest `tcp:2000` forward
   (`test/integration/btest-client.test.ts`, CHR 7.23.1). This is what makes the
   **client** cell `CHR-passed`: centrs's EC-SRP5 **client proof** is verified by
-  RouterOS's own server verifier. TCP only — the EC-SRP5 example is run over TCP
-  receive here (the loopback variant below uses UDP); UDP client→server stays
-  loopback (README, Open questions).
+  RouterOS's own server verifier. Example **11** (TCP **multi-connection**
+  fan-out), a TCP `direction=both` #85 regression guard, and **UDP receive/both**
+  (#88 — the server→client return over the guest→host SLIRP gateway) are gated in
+  the same suite.
 - **Unit / loopback (client cell + codec)** — examples 6–10. centrs client ↔
   centrs server on `127.0.0.1` with injected sockets; the EC-SRP5 both-roles math
   and the pre-socket option-grammar rejects (`test/unit/btest.test.ts`). These are
@@ -113,12 +115,13 @@ contains a `transport/auth-failed` entry (the EC-SRP5 proof did not verify) and
 `data.sessions` is empty — no session opened, no throughput. The CHR side reports
 an authentication failure.
 
-### 5. Multi-connection TCP transmit
+### 5. Multi-connection TCP transmit (server-side accept)
 
-> *Designed, not yet gated* — the server's parallel-stream fan-out for
-> `connection-count > 1` is not built yet (the session token is negotiated, but
-> secondary TCP joins are not served). Documented follow-up; not part of the
-> asserted run.
+> *Designed, not yet gated* — this is the **server-side** fan-out: centrs's
+> `btest server` accepting parallel secondary joins from a client. The session
+> token is negotiated but centrs's server does not yet serve secondary TCP joins.
+> Distinct from the **client** fan-out (example 11), which **is** implemented and
+> gated. Tracked as a follow-up (#100); not part of the asserted run.
 
 ```bash
 centrs btest server --authenticate=false --bind 0.0.0.0 --duration 20s --format json
@@ -188,3 +191,25 @@ centrs btest client $SRV --protocol udp --local-udp-tx-size 99999
 `ok: false`, `error.code = "validation/option"` (UDP size must be `28..64000`), no
 socket opened. The same gate rejects `connection-count` outside `1..255`,
 `interval` outside `20ms..5s`, and (server) `max-sessions` outside `1..1000`.
+
+## centrs client TCP multi-connection (gated; client cell)
+
+### 11. Multi-connection TCP receive fan-out
+
+```bash
+centrs btest client <router> --protocol tcp --direction receive --connection-count 4 --duration 4s --format json
+```
+
+Against a real RouterOS `/tool/bandwidth-server` (`authenticate=no`), centrs reads
+the session token from the primary's OK and opens the 3 extra TCP data
+connections, each presenting the grounded join `[token:u16 BE][0x02][0 …]`. The
+summary is `ok: true` with `data.activeConnections: 4` and non-zero aggregate
+throughput — real RouterOS accepted all 3 secondary joins and data flowed on every
+connection (the per-connection drive is also asserted deterministically by the
+loopback unit test). The *throughput increase* multiple streams provide is a
+high-latency/WAN-link property and is **not** observable over the near-zero-latency
+SLIRP loopback (a single TCP stream already saturates it), so the gate asserts the
+fan-out itself, not a higher number. Gated in
+`test/integration/btest-client.test.ts` (CHR 7.23.1). An **authenticated**
+`--connection-count > 1` run instead stays single-stream (`activeConnections: 1`)
+and carries a `routeros/btest-connection-count-single-stream` warning.

package/commands/devices/README.md

@@ -403,3 +403,29 @@ When an item ships with CHR examples, fold it into the matrix and delete the row
   same envelope as the CDB. Provenance source label: `dude`.
 - The `centrs check` command will reuse the resolver and add a network probe;
   `devices` itself stays RouterOS-IO-free.
+
+### Missing-target guidance (and the MCP/proxy follow-up)
+
+When a command that takes a `<router>` is called without one, the **CLI** turns
+the bare usage error into a registry-aware tip (shared helper
+`src/cli/missing-target.ts`): it reads the CDB best-effort and emits either
+`tip/select-target` (lists a few saved handles to pass — identity over target) or
+`tip/no-devices` (→ `centrs discover --save`) when the registry is empty. The
+read is unencrypted-only and the CDB **password never threads into the tip path**,
+so an encrypted registry falls back to generic guidance.
+
+This guidance is currently **CLI-shaped on purpose** and is *not* yet wired into
+the MCP/proxy frontends — that is deferred spec/review work. Two boundaries
+should shape it when it lands, because the registry's role differs per frontend:
+
+- The `tip/*` envelope channel is shared-core, but the specific remediation
+  *strings* (`centrs devices list`, `centrs discover --save`) are CLI verbs and
+  must **not** be emitted verbatim by MCP/proxy. Each frontend phrases the
+  next-step in its own vocabulary.
+- On **MCP**, targets come from the **CDB allowlist**, not free-text `<router>`
+  (constitution: MCP surface). An unregistered/empty target is
+  `cdb/target-not-registered`, and the `centrs://devices` resource already
+  enumerates the allowlisted targets — so the MCP equivalent of "what can I
+  pass?" is "read the `centrs://devices` resource / register a device first,"
+  not "run discover." The **proxy** fronts the same CDB and should mirror the MCP
+  framing, not the CLI's `discover --save` nudge.

package/commands/discover/README.md

@@ -6,10 +6,10 @@ Status: `CHR-passed` (see `docs/MATRIX.md`). The MNDP codec, TTL cache, UDP
 listener, and `discover --save` are implemented; the real-L2 receive/decode/save
 path is green against RouterOS CHR 7.23.1 via `test/integration/discover.test.ts`
 (socket-connect bridge), and the network-independent paths stay unit-tested. The
-matrix remains the only status surface. The `identity=`/`mac=` lookup-key writing and
-MAC-keyed de-dupe described below are the decided target; the current `--save`
-de-dupes on `target` and keeps identity/MAC in the inert detail — that gap moves
-with the `devices` lookup-key work.
+matrix remains the only status surface. `--save` now writes the `identity=`/`mac=`
+lookup keys and de-dupes on the MAC (both described below), so a discovered
+device resolves by its advertised identity, IP, or MAC — not just the stored
+`target`.
 
 ## Synopsis
 
@@ -66,7 +66,14 @@ tested without a router (crafted packet fixtures + a loopback socket).
 `--save` without `--timeout` uses the default 15s window.
 
 Bare `centrs discover` is **read-only** — it returns the envelope and never
-writes the (WinBox-shared) CDB; `--save` is the explicit opt-in. The registry
+writes the (WinBox-shared) CDB; `--save` is the explicit opt-in. When it finds
+neighbors but was not given `--save`, the envelope carries a `tip/discover-save`
+pointer so the read-only run advertises how to persist the result. In the
+human-facing text format on an interactive terminal (TTY) `discover` also prints
+a one-line "listening…" progress note to **stderr** so the listen window does not
+look like a hang; `--format json|yaml` and piped/redirected runs stay silent
+(stderr is exempt from the lossless-stdout rule — see
+[`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md), Result envelope). The registry
 surface `centrs devices discover` is the inverse: invoking `devices` means you
 intend to populate it, so **`--save` is implied** there, and it is the home for
 the "set default credentials so centrs starts useful" onboarding nudge. Both
@@ -108,9 +115,11 @@ writer" holds.
   globally unique — `identity` is *not* the de-dupe key, because factory-default
   devices all report `MikroTik`. A neighbor whose MAC already names a CDB entry
   (as the `target` of a `macTarget` record or as a `mac=` lookup key on any
-  record) is **skipped, never overwritten** — hand-curated records win. Only
-  genuinely new devices are added. Writes reuse the `devices` atomic write path
-  (`addDevice`); the CDB is reloaded between writes so each add sees prior ones.
+  record) is **skipped, never overwritten** — hand-curated records win. A
+  neighbor whose IP `target` already names an entry is likewise skipped, so a
+  curated record is never clobbered. Only genuinely new devices are added. Writes
+  reuse the `devices` atomic write path (`addDevice`); the CDB is reloaded between
+  writes so each add sees prior ones.
 - **Encrypted CDBs:** `--save` against an encrypted CDB decrypts the file under
   the loaded password, appends new neighbors, and re-encrypts with a fresh salt
   before the atomic rename. The backup beside the CDB is the verbatim prior

package/commands/discover/examples.md

@@ -63,9 +63,11 @@ 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 }`.
+`group=discovered`. Each saved comment carries the `source=mndp` kv token, the
+`identity=`/`mac=` **lookup keys** (so the device resolves by its advertised
+identity, IP, or MAC), and a free-form parenthesized detail (`board:`,
+`version:`, `interface:`, `software-id:`). `meta.operation.saved` reports
+`{ group, added, skipped, records }`.
 
 ### 5. Save with a custom group
 
@@ -81,8 +83,11 @@ New entries get `group=lab` instead of `discovered`.
 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
+A neighbor whose **MAC** already names a CDB entry — as a `macTarget` record's
+target or a `mac=` lookup key on any record (and likewise any record sharing the
+neighbor's IP target) — is skipped, never overwritten. MAC is the de-dupe key
+because it is globally unique and always advertised; `identity` is not, since
+factory-default devices all report `MikroTik`. The skip is reported in
 `meta.operation.saved.records[].action = "skipped-existing"`; hand-curated
 records win.