@tikoci/centrs 0.1.0

package/commands/devices/examples.md

@@ -0,0 +1,488 @@
+# devices — examples
+
+Each numbered example is an executable spec. `devices` performs no network
+IO, so its integration tests run against a fixture CDB rather than a live
+CHR. The fixtures are built in-test from the known CDB primitives and written
+into a temporary directory at runtime (open and encrypted, encrypted password
+`centrs-test`); there are no checked-in `.cdb` files. See
+`test/integration/devices.test.ts`.
+
+Writes operate on a copy of the fixture per test; the source bytes are never
+mutated in place. `$CDB` is the per-test path.
+
+> The decided `devices` redesign is fully implemented and exercised below:
+> lookup-key resolution (`identity=`/`mac=`/`ip=`, examples 32–34), the broadened
+> `--match` selectors (`user=`/`target=`, examples 6/35/36), the symmetric
+> `add`/`set` model (`edit` reserved for the interactive editor, example 37), the
+> `(target, user)` record identity (example 36), the `--profile-none`/
+> `--profile-own` sentinels (example 38), the `tips[]` channel (example 40), and
+> the CLI verb aliases (example 41). The `__default__` fallback record is
+> resolver-level (unit-tested in `test/unit/resolver.test.ts`). Do not reconcile
+> the README back to these examples; reconcile forward.
+
+## list
+
+### 1. List all targets
+
+```bash
+centrs devices list --cdb-file $CDB
+```
+
+Envelope: `ok: true`, `data` is an array of `{ target, recordType, group?,
+user, sources }`. No `meta.timing.request`.
+
+### 2. List a single group
+
+```bash
+centrs devices list --cdb-file $CDB --group prod-edge
+```
+
+`data` contains only members whose `group="prod-edge"`. Empty array is a
+valid success.
+
+### 3. List with no CDB present
+
+```bash
+centrs devices list --cdb-file /tmp/does-not-exist.cdb
+```
+
+Errors with `cdb/not-found`. `details_url` populated.
+
+## show
+
+### 4. Show by exact target
+
+```bash
+centrs devices show 192.0.2.5 --cdb-file $CDB
+```
+
+`data` is one entry. `meta.target.sources` maps every resolved field to
+`cdb` or `default`. `meta.target.cdbRecordIndex` is the entry's index.
+
+### 5. Show ambiguous target (non-TTY)
+
+The CDB holds two entries with the same `target` (`2001:db8::5`) — the same
+host saved once as an `ipAdmin` record and once as an `ipUser` record. With no
+disambiguator and no interactive prompt available, `show` refuses to guess.
+
+```bash
+centrs devices show 2001:db8::5 --cdb-file $CDB </dev/null
+```
+
+`identity/ambiguous`. `error.context.matches` is an array of
+`{ cdbRecordIndex, target, recordType }`, one per colliding entry.
+
+### 6. Show with --match disambiguation
+
+`--match <record-type>` selects among duplicate targets by record type (one of
+the `winBoxCdbRecordType` names: `ipAdmin`, `ipUser`, `macTarget`, …).
+
+```bash
+centrs devices show 2001:db8::5 --cdb-file $CDB --match ipUser
+```
+
+`ok: true`. The returned entry is the `ipUser` record; `meta.target.resolvedTarget`
+is `2001:db8::5`. A `--match` token that names no colliding entry errors with
+`identity/no-match`; an unknown record-type token errors with `input/invalid-match`.
+
+### 7. Show --explain dumps raw record
+
+```bash
+centrs devices show 192.0.2.5 --cdb-file $CDB --explain
+```
+
+`data.record` is the raw `WinBoxCdbRecord` (tag/marker/tcode/value). Useful
+for diagnosing unknown-field preservation.
+
+## groups
+
+### 8. List distinct groups with counts
+
+```bash
+centrs devices groups --cdb-file $CDB
+```
+
+`data` is an array of `{ group: string, members: number }`, sorted by name.
+
+### 9. Groups --members expands to membership
+
+```bash
+centrs devices groups --cdb-file $CDB --members
+```
+
+`data` is an array of `{ group, members: [{ target, recordType }] }`.
+
+## add
+
+### 10. Add an ipAdmin entry
+
+```bash
+centrs devices add 198.51.100.10 --user admin --password secret \
+  --group prod-edge --comment "site=NYC via=ssh" --cdb-file $CDB
+```
+
+Envelope: `ok: true`. Re-reading the CDB shows the entry. Backup file
+`$CDB.bak.<iso8601>` exists.
+
+### 11. Add the same (target, user) without --force
+
+Record identity is `(target, user)`, so a collision requires the **same user**
+(`192.0.2.5` is saved under `admin`).
+
+```bash
+centrs devices add 192.0.2.5 --user admin --password other --cdb-file $CDB
+```
+
+Errors with `cdb/already-exists`. No file mutation. No backup written.
+
+### 12. Replace the same (target, user) with --force
+
+```bash
+centrs devices add 192.0.2.5 --user admin --password new --force --cdb-file $CDB
+```
+
+`ok: true`. Backup written. The previous entry's unknown fields are
+preserved on the replacement record; `meta.warnings` contains a
+`cdb/unknown-field` entry listing the preserved tags.
+
+### 13. Add against encrypted CDB without password
+
+```bash
+centrs devices add 198.51.100.20 --user u --password p \
+  --cdb-file $CDB_ENCRYPTED
+```
+
+Errors with `cdb/password-required` (load fails before any mutation).
+
+### 14. Add against encrypted CDB with password
+
+```bash
+centrs devices add 198.51.100.20 --user u --password p \
+  --cdb-file $CDB_ENCRYPTED --cdb-password centrs-test
+```
+
+`ok: true`. The write layer decrypts → mutates → re-encrypts under the same
+password with a fresh salt, then atomically renames over the original. The
+backup (`.bak.<timestamp>`) is the verbatim prior ciphertext.
+
+## set (first-class fields)
+
+`set` modifies an existing record. First-class fields change via flags; comment
+override/lookup keys change via `k=v` positionals (next section). `add` takes the
+same flags + positionals — the only difference is existence (`add` creates,
+`set` requires the record to exist).
+
+### 15. Set credentials (first-class fields)
+
+```bash
+centrs devices set 192.0.2.5 --user admin2 --password new --cdb-file $CDB
+```
+
+`ok: true`. Other fields (group, profile, comment, unknowns) unchanged.
+
+### 16. Set a missing target
+
+```bash
+centrs devices set 203.0.113.1 --user x --password y --cdb-file $CDB
+```
+
+Errors with `cdb/not-found-target`.
+
+## set (comment kv-soup)
+
+### 17. Set a recognized override
+
+```bash
+centrs devices set 192.0.2.5 via=ssh validate=false --cdb-file $CDB
+```
+
+`ok: true`. Re-running `devices show 192.0.2.5` shows
+`meta.target.sources.via = "comment-kv"`.
+
+### 18. Set a key that maps to a first-class CDB field
+
+```bash
+centrs devices set 192.0.2.5 user=hacker --cdb-file $CDB
+```
+
+Errors with `cdb/reserved-key` listing the forbidden keys
+(`user`, `password`, `group`, `profile`, `session`).
+
+### 19. Set unknown key (lenient)
+
+```bash
+centrs devices set 192.0.2.5 future=maybe --cdb-file $CDB
+```
+
+`ok: true` with `cdb/unknown-option` warning. The token is written to
+`comment` verbatim.
+
+### 20. Set unknown key with --strict
+
+```bash
+centrs devices set 192.0.2.5 future=maybe --strict --cdb-file $CDB
+```
+
+Errors with `cdb/unknown-option`. No write.
+
+### 21. Set value with spaces (quoting)
+
+```bash
+centrs devices set 192.0.2.5 'note="rack 7 row B"' --cdb-file $CDB
+```
+
+`ok: true`. Re-reading parses the value back as `rack 7 row B` (one token).
+
+## remove
+
+### 22. Remove a single entry
+
+```bash
+centrs devices remove 192.0.2.5 --cdb-file $CDB
+```
+
+`ok: true`. Backup written. Subsequent `devices show` returns
+`cdb/not-found-target`.
+
+### 23. Remove unknown target
+
+```bash
+centrs devices remove 203.0.113.99 --cdb-file $CDB
+```
+
+`cdb/not-found-target`. No backup written.
+
+## Provenance and overrides
+
+### 24. CLI overrides comment-kv
+
+CDB entry has `via=ssh` in its comment. CLI passes `--via rest-api`.
+
+```bash
+centrs devices show 192.0.2.5 --via rest-api --cdb-file $CDB
+```
+
+`meta.target.via = "rest-api"`, `meta.target.sources.via = "cli"`.
+`meta.warnings` includes `cdb/override-applied`.
+
+### 25. Env overrides comment-kv but loses to CLI
+
+```bash
+CENTRS_VIA=native-api centrs devices show 192.0.2.5 \
+  --via rest-api --cdb-file $CDB
+```
+
+`meta.target.via = "rest-api"`, `meta.target.sources.via = "cli"`.
+
+## Fanout (resolved here, executed by other commands)
+
+`devices` itself doesn't fan out — these tests assert the resolver behavior
+that other commands consume.
+
+### 26. Group expansion is deterministic
+
+```bash
+centrs devices list --group prod-edge --cdb-file $CDB --format json
+```
+
+The order of resolved members matches CDB record order. This deterministic
+ordering is canonical across centrs: fanout consumers reassemble their `data`
+array in this same resolved order (not completion order) so repeated runs
+produce stable diffs.
+
+### 27. Unknown group
+
+```bash
+centrs devices list --group does-not-exist --cdb-file $CDB
+```
+
+`ok: true`, `data: []`, `meta.warnings` includes `cdb/empty-group`.
+
+### 28. Mixed positional + group dedupe (assertion via `devices show`)
+
+The resolver's de-dupe rule: positional targets that are also group members
+appear once. Exercised through a downstream command's test once `retrieve`
+gains multi-target support; tracked here so the rule is anchored.
+
+## Encrypted CDB read
+
+### 29. Read encrypted CDB with password
+
+```bash
+centrs devices list --cdb-file $CDB_ENCRYPTED --cdb-password centrs-test
+```
+
+`ok: true`. `meta.settings.cdbFile.kind = "cli"`,
+`meta.settings.cdbPassword.kind = "cli"`.
+
+### 30. Wrong password
+
+```bash
+centrs devices list --cdb-file $CDB_ENCRYPTED --cdb-password wrong
+```
+
+`cdb/decrypt-failed`. `error.cause` includes the decoder's detected magic
+mismatch.
+
+## Discovery provenance
+
+### 31. MNDP-discovered entries are marked as discovered
+
+`discover --save` writes CDB records that `devices list` surfaces
+with `group="discovered"` and `source=mndp` in comment-kv metadata.
+
+```bash
+centrs devices list --cdb-file $CDB --group discovered
+```
+
+`ok: true`; each member reports CDB provenance and discovery metadata.
+
+## Lookup-key resolution
+
+`<router>` resolves against the `target` field **and** the `identity=` / `mac=` /
+`ip=` comment lookup keys (see `README.md`, Identity model). MAC values compare
+case- and separator-insensitively. These run against a dedicated lookup fixture
+(`$CDB_LOOKUP`): one `ipAdmin` record `192.0.2.60` with
+`comment="identity=edge1 mac=AA:BB:CC:DD:EE:11"`, and one `macTarget` record
+`AA:BB:CC:DD:EE:22` with `comment="identity=edge2 ip=192.0.2.61"`.
+
+### 32. Resolve by the identity= lookup key
+
+```bash
+centrs devices show edge1 --cdb-file $CDB_LOOKUP
+```
+
+`ok: true`. The resolved entry's `target` is `192.0.2.60`;
+`meta.target.identity` is `edge1`.
+
+### 33. Resolve by the mac= lookup key (case/separator-insensitive)
+
+```bash
+centrs devices show aa-bb-cc-dd-ee-11 --cdb-file $CDB_LOOKUP
+```
+
+`ok: true`. Resolves the same `192.0.2.60` record even though the typed MAC uses
+dashes and lower case.
+
+### 34. Resolve by the ip= lookup key
+
+```bash
+centrs devices show 192.0.2.61 --cdb-file $CDB_LOOKUP
+```
+
+`ok: true`. Resolves the `AA:BB:CC:DD:EE:22` record; `meta.target.identity` is
+`edge2`.
+
+### 35. A duplicated identity= is ambiguous; --match user= pins it
+
+A second fixture (`$CDB_DUP_IDENTITY`) holds two distinct hosts that share
+`identity=dup` (the deliberately non-unique identity case).
+
+```bash
+centrs devices show dup --cdb-file $CDB_DUP_IDENTITY </dev/null
+```
+
+`identity/ambiguous`; `error.context.matches` lists both records (with `user`).
+
+```bash
+centrs devices show dup --match user=ops --cdb-file $CDB_DUP_IDENTITY
+```
+
+`ok: true`; selects the `ops` record. `--match target=<addr>` and
+`--match <record-type>` are the other selectors.
+
+## (target, user) identity
+
+### 36. The same address under a different user coexists
+
+`192.0.2.5` is saved under `admin`. Adding it under a different user is a new
+record, not a collision.
+
+```bash
+centrs devices add 192.0.2.5 --user ops --password ops-pw --cdb-file $CDB
+```
+
+`ok: true`, `data.replaced: false`. The CDB now holds two records for
+`192.0.2.5`, so the bare address is ambiguous:
+
+```bash
+centrs devices show 192.0.2.5 --cdb-file $CDB </dev/null
+```
+
+`identity/ambiguous`. `centrs devices show 192.0.2.5 --match user=ops` resolves
+the new record; `--match user=admin` the original.
+
+## edit (reserved for the interactive editor)
+
+### 37. `edit` reports usage/not-implemented
+
+```bash
+centrs devices edit 192.0.2.5 --cdb-file $CDB
+```
+
+Errors with `usage/not-implemented`. The interactive (clack/TUI) editor is not
+built yet; use `set` for non-interactive field and metadata changes.
+
+## Profile sentinels
+
+### 38. Write the `<none>` / `<own>` profile sentinels
+
+```bash
+centrs devices set 192.0.2.5 --profile-none --cdb-file $CDB
+```
+
+`ok: true`; the record's `profile` becomes `<none>`. `--profile-own` writes
+`<own>`; `--profile <name>` writes a named profile. The three are mutually
+exclusive (passing more than one is a usage error).
+
+## Symmetric add (fields + k=v)
+
+### 39. Add with bare k=v positionals
+
+```bash
+centrs devices add 198.51.100.30 --user admin --password p \
+  identity=spare via=ssh --cdb-file $CDB
+```
+
+`ok: true`. The record's comment carries `identity=spare via=ssh`, so the device
+is then resolvable as `spare`. A first-class field written as a positional
+(`user=x`) is refused with `cdb/reserved-key` — use the `--user` flag.
+
+## Tips
+
+Tips are advice, not anomalies (see `docs/CONSTITUTION.md`, Result envelope).
+They ride the top-level `tips[]` channel, always present (`[]` when empty),
+and render in text mode under a `Tips:` footer.
+
+### 40. An empty registry suggests adding a device
+
+```bash
+centrs devices list --cdb-file $EMPTY_CDB
+```
+
+`ok: true`, `data: []`, and `tips` carries a `tip/no-devices` entry (with a
+`fix`). `--json` includes the same `tips[]` array. `devices show` on a record
+with no stored password emits `tip/credentials-missing` unless a `__default__`
+record supplies fallback creds.
+
+## Verb aliases
+
+The RouterOS-muscle-memory aliases (`commands/AGENTS.md`, Verb vocabulary)
+resolve silently to the canonical verb: `print`→`list`, `get`→`show`,
+`rm`/`delete`→`remove`. Canonical names still win in help text and the usage
+line; aliases are a CLI input affordance only (the MCP `op` enum and the API
+functions stay canonical-only).
+
+### 41. Aliases resolve to the canonical verb
+
+```bash
+centrs devices print --cdb-file $CDB                 # = list
+centrs devices get 192.0.2.5 --cdb-file $CDB         # = show
+centrs devices rm 192.0.2.5 --cdb-file $CDB          # = remove
+centrs devices delete 192.0.2.5 --cdb-file $CDB      # = remove
+```
+
+Each alias produces the same envelope as its canonical verb — `meta.operation`
+reports the canonical command (`list`/`show`/`remove`), never the alias. An
+unknown verb still errors with `input/invalid-command`, and the error lists the
+canonical verbs plus the accepted aliases.

package/commands/discover/README.md

@@ -0,0 +1,170 @@
+# discover
+
+Discover RouterOS neighbors over MNDP and optionally save them into the CDB.
+
+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.
+
+## Synopsis
+
+```text
+centrs discover [--timeout 15s] [--save] [--group discovered] \
+                [--port 5678] [--cdb-file <path>] [--cdb-password <secret>] \
+                [--format text|json|yaml]
+```
+
+## Intent
+
+- MNDP is the first discovery source. It is a passive hint source, not
+  authoritative inventory.
+- `--save` writes discovered targets into the configured CDB with provenance
+  metadata in comment kv-soup and default `group=discovered`.
+- Saved records preserve enough metadata for later resolution: MAC, advertised
+  identity, platform, RouterOS version when present, source, and discovery
+  timestamp.
+- Discovery never supplies credentials. A later `retrieve`, `execute`, or
+  `devices set` must still resolve credentials from CDB, env, CLI, or prompt.
+
+## How it works
+
+MNDP is UDP broadcast on port `5678`; each RouterOS interface answers a refresh
+with a TLV-encoded announcement (MAC, identity, version, platform, board,
+uptime, software-id, interface, IPv4/IPv6). `discover`:
+
+1. Binds a UDP socket (default `0.0.0.0:5678`) with address/port reuse so
+   it can coexist with other MNDP listeners when the platform permits it.
+2. Broadcasts a refresh request **immediately**, then every 5s, and listens for
+   the `--timeout` window. Sending the first refresh up front (rather than after
+   the initial 5s tick) is what makes a short default window viable: responders
+   reply within a round-trip instead of waiting for their own ~60s passive cycle.
+3. Decodes each datagram with the pure codec in `src/data/mndp.ts`, tolerating
+   unknown TLV types and ignoring malformed datagrams and its own refresh echo.
+4. Stores neighbors in an in-memory TTL cache keyed by MAC.
+5. Returns a canonical envelope whose `data.neighbors` is sorted by MAC.
+
+The codec is pure and the socket layer is thin and injectable, so both are
+tested without a router (crafted packet fixtures + a loopback socket).
+
+## Flags and defaults
+
+| Flag             | Default       | Meaning                                              |
+| ---------------- | ------------- | ---------------------------------------------------- |
+| `--timeout`      | `15s`         | Listen window before results are returned. First refresh is sent immediately. |
+| `--save`         | off           | Persist discovered neighbors into the CDB.           |
+| `--group`        | `discovered`  | First-class CDB group assigned to saved entries.     |
+| `--port`         | `5678`        | UDP port to bind for MNDP.                            |
+| `--cdb-file`     | resolved CDB  | CDB path override for `--save`.                      |
+| `--cdb-password` | env/none      | Decrypt an encrypted CDB; also used to re-encrypt on `--save`. |
+| `--format`       | `text`        | `text`, `json`, or `yaml`; renders the same envelope. |
+
+`--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
+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
+paths write through the `devices` atomic write layer, so "devices is the only
+writer" holds.
+
+## MNDP cache shape and TTL policy
+
+(Answers the former matrix open question.)
+
+- **Shape:** an in-memory `MndpCache` (`src/data/mndp-cache.ts`) keyed by the
+  lower-cased MAC address. MAC-less announcements fall back to a synthetic
+  `noaddr:<identity>:<interface>` key. Each entry records the latest decoded
+  neighbor plus `firstSeenAt` / `lastSeenAt` epoch-ms timestamps. The cache is
+  process-local only — the CDB stays the single durable datastore.
+- **TTL:** entries expire `180s` (three ~60s announce cycles) after they were
+  last seen. Three cycles tolerates a couple of dropped broadcasts before a
+  still-present neighbor is forgotten. Re-observing a neighbor refreshes
+  `lastSeenAt` and keeps `firstSeenAt`. The clock is injectable for
+  deterministic tests.
+
+## `--save` provenance and de-dupe
+
+- **Target:** a neighbor's CDB target is its advertised IPv4 when present
+  (record type `ipAdmin`), else its MAC (record type `macTarget`). One record
+  per device — the connectable address — not a MAC record plus an IP record.
+- **Lookup keys:** the identifiers that are *not* the target are written as
+  comment lookup keys so the device resolves by any of them (see
+  `commands/devices/README.md`, Identity model): `identity=<advertised
+  identity>` always, and `mac=` when the target is the IP. The advertised
+  identity is therefore usable directly — `centrs retrieve <identity> …` — even
+  though it is duplicative across factory-default devices.
+- **Provenance:** the comment also carries the allowlisted `source=mndp` token
+  plus a free-form, parenthesized detail (`discovered <iso> via MNDP (platform:
+  …; board: …; version: …; interface: …; software-id: …)`). The detail is inert
+  so it preserves provenance without emitting `cdb/unknown-option` warnings.
+- **Group:** new entries get `group=discovered` (override with `--group`).
+- **De-dupe rule:** keyed on the **MAC**, which MNDP always carries and which is
+  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.
+- **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
+  ciphertext. Reading an encrypted CDB stays supported.
+- **No auto-deletion / aging.** centrs never removes or rewrites a CDB record it
+  did not just create in this run. Discovered records age via their discovery /
+  `updated=` timestamp, and staleness is surfaced as a **tip** ("N discovered
+  entries are >30d old"), never an automatic delete — deleting records from a
+  WinBox-shared file unprompted is unsafe.
+
+## Errors
+
+- `mndp/listen-failed` — the UDP bind failed (`EADDRINUSE`, e.g. WinBox holds
+  5678 without compatible port sharing; or `EACCES`). Remediation: stop the
+  holder, or pass a different `--port`.
+- `mndp/malformed` — the pure codec rejects a structurally invalid packet
+  (too-short header or a TLV length that overruns the buffer). The listener
+  ignores such datagrams rather than failing the whole scan.
+
+## L2 validation policy
+
+Decided (2026-06-06), wired and proven (2026-06-07): the real-L2 integration
+path for MNDP 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. A small host shim
+(`test/integration/mndp-l2-bridge.ts`) bridges that frame stream to centrs's
+UDP/5678 listener — lifting the UDP/5678 payload out of each frame and
+re-delivering it to the **unmodified** `discover()`/`listenMndp` path, and
+injecting MNDP refresh frames back over the same TCP connection so RouterOS
+answers within a round-trip — a real L2 path with no root and no native
+raw-frame helper, while REST/native-API keep a separate user-mode NIC with
+hostfwd. centrs runs with `sendRefresh: false` here (its own broadcast cannot
+reach the guest through the bridge, so the shim does the L2 injection; the
+refresh-send path stays covered by the loopback unit test). 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`.
+
+`test/integration/discover.test.ts` exercises this end to end on RouterOS CHR
+7.23.1: it boots `["user", { type: "socket-connect", port }]`, captures a real
+MNDP announcement, decodes it with centrs's codec, cross-checks
+`identity`/`platform`/`board`/`version`/`mac` against REST, and `--save`s a
+`macTarget`/`group=discovered`/`source=mndp` record (examples 1, 2, 4). It runs
+under `bun run test:integration` (gated by `CENTRS_RUN_FAST_INTEGRATION`). The
+network-independent examples (3 port-in-use, 5 custom group, 6 de-dupe, 7
+encrypted CDB) are CDB/bind logic that is identical regardless of where the
+neighbor came from, so they stay validated by `test/unit/discover.test.ts`
+against a loopback socket and crafted fixtures.
+
+Live-router finding worth carrying into mac-telnet: MNDP's board TLV (type 12)
+advertises the short board id (`CHR`), while REST `/system/resource` `board-name`
+is the verbose hardware string (`CHR QEMU Standard PC (i440FX + PIIX, 1996)`)
+that *begins with* it — so cross-checks must use `startsWith`, not equality. The
+same `socket-connect` bridge (with its frame-injection write-back) is the L2
+harness the mac-telnet execute/terminal cells will reuse.