@tikoci/centrs 0.1.0

package/docs/CONSTITUTION.md

@@ -0,0 +1,417 @@
+# Constitution
+
+The load-bearing rules for `centrs`. Everything else (per-command READMEs, the
+matrix, code, tests) must be consistent with this file. If something here is
+wrong, fix it here first, then propagate. If a rule needs an exception, add the
+exception here — not in scattered prose.
+
+This file is short on purpose. Resist the urge to grow it.
+
+## What centrs is
+
+A typed library, with CLI/MCP/TUI/proxy frontends, that reaches RouterOS over
+multiple protocols and gives the caller **validated** access plus structured,
+actionable diagnostics. The TypeScript API is the root surface; everything else
+is an adapter over it.
+
+The product is *not* "REST/SSH/native API wrappers." The product is
+**validation + structured envelopes + identity resolution** on top of those
+transports. Without those, this is a worse `curl`.
+
+centrs also speaks a small set of MikroTik **peer protocols** that are *not*
+RouterOS-command transports — currently the **bandwidth test** (`btest`), which
+mirrors `/tool/bandwidth-test` and `/tool/bandwidth-server`. This is a
+deliberate, separate capability axis (*measurement*, not "run a validated
+command"): centrs still gives structured envelopes, identity resolution, and
+friendly errors, but the "validate a RouterOS-shaped command" gate below does
+**not** apply to it (see "Validation is the product" and Protocol selection's
+`measure` row).
+
+## Validation is the product
+
+Every RouterOS-shaped call goes through canonicalize → validate → run →
+re-validate-server-side. Validation is not optional polish.
+
+- `retrieve` and other read-shaped calls validate against
+  `/console/inspect request=syntax path=...,print` (path joined by commas) and
+  attribute inspection. The path syntax (commas, no leading slash, last token
+  is the verb) is part of the validator contract.
+- `execute` and other CLI-shaped calls validate with `:put [:parse "..."]` plus
+  a semantic gate. **How `:parse` surfaces an error is transport-specific**
+  (grounded on CHR 7.23.1): `:parse` *does* reject an unknown attribute
+  (`bad parameter <name>`) and malformed CLI (`syntax error`), but over REST that
+  text rides the **HTTP-200 `ret` value** (no error status), and over the
+  **native API** `:put [:parse]` returns an opaque `*NN` handle that reveals
+  nothing at all. centrs's REST/native syntax gate runs `:parse` but does not
+  read the `ret`, so for those transports the unknown-attribute catch comes from
+  the separate **`/console/inspect`** semantic gate (or the server's own
+  write re-validation); the `:parse` round-trip there mainly backstops transport
+  errors and the local quote preflight. Over **mac-telnet** the interactive
+  console *prints* the `:parse` result, so centrs reads it and a single console
+  `:parse` covers both syntax and the unknown-attribute (semantic) gate — no
+  `/console/inspect` table needed. In every case a clean parse is necessary, not
+  sufficient on its own; semantic validation is a distinct, transport-appropriate
+  step (`/console/inspect`, the console `:parse` text, or server re-validation).
+- **Peer-measurement commands (`btest`) are exempt from this gate** — they issue
+  no RouterOS command, so they validate *option-grammar* + the **EC-SRP5** auth
+  exchange instead (the envelope, identity-resolution, and friendly-error
+  contract still hold; only the RouterOS-command gate is absent). The grammar
+  rules are in `commands/btest/README.md`.
+- A failing validator is a real result. Surface it with the structured error
+  envelope below — do not bypass.
+
+There is no `update` verb: generalizing RouterOS add/set/remove into one abstract
+write would need too many heuristics, so writes ride `execute`'s
+canonicalize → validate → run path while `retrieve` stays read-only (see Protocol
+selection).
+
+**Disabling validation to make a call work is forbidden.** If the validator
+rejects something a real router accepts, the validator is wrong; fix the
+validator with CHR evidence. If a feature only passes its integration test
+with `validate=false`, the feature is not done.
+
+The default is `validate=true`. `--validate=false` exists as an escape hatch
+for probing undocumented edges, never as a workaround for a centrs bug.
+
+## Result envelope
+
+Every API/CLI call returns the same shape, regardless of transport:
+
+```ts
+{
+  ok: boolean,                  // true if the operation succeeded end-to-end
+  data?: unknown,               // the payload (array of records, single object, etc.)
+  warnings?: Warning[],         // non-fatal anomalies (stale cache, unused --cdb-password, etc.)
+  tips?: Tip[],                 // advice, not anomalies (no username set, no CDB found, …)
+  error?: CentrsError,          // present iff ok=false
+  meta: {
+    target: { ... },            // resolved target + provenance (where each field came from)
+    via: RouterOsProtocol,      // chosen protocol id
+    settings: { ... },          // settings winners + sources (env / cli / cdb / default)
+    validation?: { ... },       // validator name + result, if validation ran
+    timing?: { ... },           // request/response durations
+    truncated?: { ... },        // populated when --max-bytes/--max-rows clipped output
+  }
+}
+```
+
+Notes:
+
+- "Success with footnotes" is supported: `ok: true` may carry warnings.
+- `warnings` and `tips` are both always present (`[]` when empty) so consumers
+  never branch on existence. They are distinct on purpose: a **warning** is a
+  non-fatal anomaly about *this* result (stale cache, unused `--cdb-password`); a
+  **tip** is advice that is explicitly *not* an error or anomaly (no username
+  set, no CDB found, consider a default device). The "this is not a problem,
+  just a pointer" signal is the whole reason tips are a separate channel rather
+  than folded into warnings. A `Tip` has the same shape as a warning
+  (`{ code, message, fix? }`) with `tip/*` codes and a `details_url`.
+- CLI render must be lossless against the JSON envelope; `--format json` and
+  `--format yaml` are aliases that select serialization, not different shapes.
+  Text mode renders tips under a `Tips:` footer, distinct from warnings. This
+  lossless rule applies to **stdout** only: **stderr** carries progress and
+  interactive prompts (discover scan progress, write/ambiguity confirmation) and
+  is exempt — use it sparingly, since most operations are fast.
+- `data` is the only field whose *shape* varies by command. Everything else —
+  including `warnings` and `tips` — is invariant in shape; only contents differ.
+
+## Error model
+
+Errors are typed values, not thrown strings. Every error has:
+
+- `code` — slash-namespaced, RouterOS-style, no spaces. Example:
+  `routeros/unsupported-path`, `transport/connection-refused`,
+  `validation/unknown-attribute`, `cdb/decrypt-failed`.
+- `message` — one human sentence. No stack trace.
+- `fix` — one human sentence describing the next step the caller should take.
+- `details_url` — pointer to the canonical **per-code** page (the URL scheme is
+  in `docs/errors/README.md`).
+- `cause?` — structured sub-error, when relevant (RouterOS nova error,
+  transport detail). Stack traces and raw exception text are summarized, not
+  embedded raw.
+- `position?` — RouterOS's `(line N column M)` parse location, when the fault
+  carries one (console `:parse` rejections do). `column` is RouterOS's
+  authoritative 1-based **byte** offset — the console is not Unicode-aware — so
+  it is carried verbatim, never re-derived into a character index.
+- `redactable_fields?` — names of fields the bug-report renderer must redact.
+
+Credentials and private key material are always redactable. Private key paths are
+configuration values and may appear in `meta.settings`; redact them only when an
+error also carries sensitive key material or a caller explicitly marks the path
+as sensitive.
+
+The bug-report renderer is invoked **inline** via `--bug-report` on any command —
+there is no separate `bug-report` verb. It re-renders the just-produced envelope
+with `redactable_fields` stripped and each error's `details_url` kept, so a
+shareable report needs no extra capture step (the envelope is already rich enough
+to be the report).
+
+Two error sources must be visually distinguishable:
+
+1. **centrs errors** — bad usage, validator rejection, transport plumbing.
+2. **RouterOS errors** — surfaced by the router (HTTP 4xx/5xx, parse refusal,
+   nova error). Map to a normalized `routeros/*` code, preserving the original
+   string.
+
+RouterOS faults map to a normalized `routeros/*` code (preserving the original
+string) via a CHR-grounded table shared by REST `detail` and native `!trap`
+(`src/core/routeros-errors.ts`). Every error's `details_url` is the stable
+`https://tikoci.github.io/centrs/errors/<code>`. The mapping shape, the
+ground-on-CHR-evidence rule, and the URL-scheme rules live in
+`docs/errors/README.md`.
+
+## Settings precedence
+
+Lowest to highest priority:
+
+1. Built-in defaults
+2. Config file: `${XDG_CONFIG_HOME:-~/.config}/tikoci/centrs.env` — optional
+   dotenv-style `CENTRS_*=value` **global** defaults (centrs-only preferences
+   with no per-device home; **not** an inventory or credential store — per-device
+   settings stay in the CDB). Applied as fallbacks, never injected into
+   `process.env`. The `centrs settings` command is its front-end; the file
+   mechanics, `--skip-env-file`, and the settings-key vocabulary live in
+   `commands/settings/README.md`.
+3. CDB comment-kv metadata
+4. Environment variables (`CENTRS_*`)
+5. CLI flags / API call args
+
+`meta.settings` reports the winning source for each resolved setting.
+
+### Identity and CDB
+
+The `<router>` argument may be an IP, a DNS name, a MAC, or an **identity**
+(the device's `/system/identity`); centrs resolves it through the CDB (then
+through ARP / MNDP-derived metadata as fallbacks, once implemented). Two
+principles are load-bearing:
+
+- **Record identity is the `(target, user)` pair** — matching WinBox, the same
+  address saved under a different user is a second record, not an update.
+  `group` is a flat attribute, never part of the key.
+- **The CDB is both the device datastore and the credential store.** The WinBox
+  CDB file at its well-known location *is* the inventory; there is no separate
+  cache. centrs-specific meaning is overlaid through an allowlist of comment-kv keys —
+  the lookup keys `identity=`/`mac=`/`ip=` (the one sanctioned exception to "the
+  comment is free text") plus override keys like `via`/`port`/`ssh-key`; every
+  other comment token stays inert. **Anything expressible in the CDB must also
+  be expressible via env/CLI/API**, so tests and ad-hoc use never require one.
+  `dude.db` import is out of scope (→ `tikoci/donny`).
+
+The lookup-key grammar, the CDB resolution and ambiguity rules (`--match`,
+`identity/ambiguous`, `--prefer-family`), the comment-kv allowlist, encrypted-CDB
+handling, and the atomic write strategy live in `commands/devices/README.md` —
+`devices` is the registry command and the CDB's only writer.
+
+#### Default-device record (`__default__`)
+
+A reserved CDB record (`target=__default__`) supplies fallback metadata +
+credentials, **per field**, for a resolved device whose own record leaves them
+unset. Precedence is per-field: per-call args → env (`CENTRS_*`) → matched device
+record → `__default__` → built-in default. It is **core** (honored by CLI, API,
+and MCP) and **never widens the MCP allowlist**: on MCP an unregistered target is
+still `cdb/target-not-registered`, and `__default__` only fills *missing* creds
+for an already-registered device. Create/edit it like any record; mechanics and
+examples are in `commands/devices/README.md`.
+
+Group selectors (e.g. `--group prod-edge`) target CDB groups so a single
+`retrieve`/`execute`/etc. fans out to multiple routers. Group output shape
+must round-trip through the same envelope.
+
+#### Target selection grammar
+
+One grammar across every non-terminal command. A call selects targets from any
+mix of: `<router>` positionals (one or more), repeatable `--group <name>`,
+`--all` (every CDB record), `--default` (the `__default__` record), and
+repeatable `--where <attr>=<value>` — a **device-class** selector that matches
+CDB-stored facts/comment-kv (e.g. `--where board=RB5009`), AND-combined across
+repeats. The union is **de-duped by CDB record index** and run through the same
+per-target pipeline; the `data` array is reassembled in resolved record order,
+not completion order, so repeated runs diff cleanly. Destructive multi-target
+operations (e.g. `devices remove` across a group) require `--force`. `terminal`
+and single-session `stream` are not fan-out surfaces and reject N>1 with
+`usage/fanout-not-supported`.
+
+`--where` filters *which devices* by CDB-stored facts; keep it distinct from
+`retrieve`/`execute`'s `--query`/`--filter`, which filter *RouterOS rows* in the
+response. Two layers, two flag families.
+
+`--group` is purely a **selector** in this grammar; the group *field* is written
+by a distinct `--new-group` flag on `devices add`/`set`, so record selection and
+field-setting never collide on one flag.
+
+### MCP surface: the CDB is the allowlist
+
+The MCP frontend (`commands/mcp/`) is an adapter over this core, not a new set of
+RouterOS semantics. Two boundaries are load-bearing:
+
+- **Authorization is the CDB allowlist.** RouterOS-facing tools resolve targets
+  through the CDB only; an unregistered target is rejected
+  (`cdb/target-not-registered`), and `__default__` never widens the allowlist (see
+  Identity and CDB). The off-by-default `--allow-adhoc-targets` flag is reserved
+  for future inline-target flows — today no RouterOS-facing tool exposes an inline
+  host+credential schema, so the CDB allowlist is the only active target source.
+- **Transport is stdio only.** HTTP/remote access is the proxy surface's job
+  (`src/webproxy.ts`), which fronts the same CDB; the MCP server grows no listener
+  of its own. One surface owns network exposure.
+
+The scoped tool surface (verbs mirroring the CLI/API, never one tool per RouterOS
+command), the per-device `mcp=ro|rw` + `confirm: true` write gate, the
+`centrs://devices` / `centrs://errors` resources, and the full safety model are in
+`commands/mcp/README.md`.
+
+## Protocol selection
+
+Per-operation preferences, downgrade order in parens:
+
+| Operation | Preferred | Downgrade order |
+| --------- | --------- | --------------- |
+| retrieve  | rest-api, native-api; snmp for OID/MIB reads (future) | rest-api, native-api |
+| stream    | native-api, ssh | (REST cannot follow — 60s cap; bounded or rejected) |
+| execute   | native-api → rest-api → mac-telnet | native-api, rest-api, mac-telnet, ssh, romon, winbox-terminal |
+| terminal  | ssh | mac-telnet (L2 only when ssh fails or MAC given) |
+| transfer  | size/direction-aware: rest-api/native-api for ≤60 KB writes & all reads (chunked), sftp for large uploads | sftp ⇄ rest/native by size; scp · fetch · ftp explicit-only |
+| discover  | mndp | (not a transport for command operations) |
+| measure   | btest | (explicit-only — no downgrade) |
+
+Rules:
+
+- **Read vs write:** `retrieve` is read-only (rest-api/native-api); `execute` is
+  the read **and** write surface — writes (add/set/remove) ride `execute`, and
+  there is no `update` operation.
+- **Never silently downgrade across `--via`.** If the caller pinned a transport
+  that cannot do the operation, error out with a `transport/*` code.
+  Auto-selection (no `--via`) may downgrade *within* the table, but every hop is
+  reported in `meta.warnings` with its reason.
+- **Execute vs retrieve surfaces:** native-api, rest-api, ssh, mac-telnet (and
+  later RoMON / WinBox Terminal) are execute surfaces; SNMP is **retrieve-only**.
+  mac-telnet is the default execute path for an unresolved-MAC target — IP-level
+  access needs explicit ARP opt-in.
+- **`measure` (btest) is explicit-only** — never in the auto-select/downgrade
+  chain, never a substitute, and no other command rides it.
+- Per-command selection **depth** lives in the command READMEs: `stream`'s
+  follow/NDJSON contract and the REST-cannot-follow constraint
+  (`commands/stream/README.md`), `transfer`'s size/direction-aware method
+  selection and the explicit-only `scp`/`ftp`/`fetch`
+  (`commands/transfer/README.md`), SNMP's MIB-cache
+  (`commands/retrieve/README.md`), and btest's port/auth
+  (`commands/btest/README.md`).
+
+REST-specific constraint: RouterOS REST has a 60-second hard timeout. Do not
+let `--timeout` exceed 60s when `via=rest-api`; reject with a clear error.
+Other transports may accept longer timeouts.
+
+### Transport trust (TLS / SSH host keys)
+
+One opt-out across every transport: `--insecure` (`CENTRS_INSECURE`, CDB
+`insecure=` comment-kv). Default is **verify**; `--insecure` disables peer
+verification and adds a `transport/insecure-trust` warning to the envelope so the
+downgrade is always visible. Because RouterOS ships **self-signed** certificates
+and host keys, the *default posture per transport follows that transport's
+ecosystem norm* rather than one literal value:
+
+- **TLS** (REST `https`, native-api `api-ssl`) **verifies** by default; a
+  self-signed cert fails with `transport/tls-certificate` whose remediation names
+  `--insecure`. (Both transports honor the same knob — previously native-api
+  silently accepted any cert; that is fixed.)
+- **SSH host keys** (sftp/scp) default to **trust-on-first-use**
+  (`StrictHostKeyChecking=accept-new` into the user's `known_hosts`): a new key is
+  accepted, a *changed* key fails with `transport/host-key-mismatch`. `--insecure`
+  disables the check entirely. TOFU is the universal SSH norm, so the SSH default
+  is laxer than the TLS default by design.
+
+SSH identity selection: the `sshKey` setting (`--ssh-key`/`CENTRS_SSH_KEY`/CDB
+`ssh-key=`) carries a private-key **path only** — never key material; when unset,
+the host SSH agent / `~/.ssh/config` is used. RouterOS refuses password login once
+an SSH key is set for a user (`password-authentication=yes-if-no-key`, the
+default), so key auth is the normal sftp path.
+
+## Done definition
+
+A feature is done when its **CHR integration test is green** against a real
+RouterOS CHR booted by `@tikoci/quickchr`. Not when code exists. Not when unit
+tests pass. Not when the spec says so. This is the **normative** done
+definition; `AGENTS.md` and
+`.github/instructions/done-definition.instructions.md` point here (the latter
+carries the Copilot-workflow procedure for satisfying it).
+
+`docs/MATRIX.md` is the single source of truth for *what* is done and defines the
+cell states (`not-started` / `designed` / `coded` / `CHR-passed`). A cell
+advances only with the matching evidence in the same change, and the commit that
+advances it must include the test name and CHR version.
+
+## Boundaries
+
+centrs does:
+
+- Resolve devices/groups from explicit input, env, CDB, MNDP cache.
+- Choose protocols per the table above and configure them.
+- Validate before execute; re-validate server-side immediately before run.
+- Return structured envelopes with provenance and warnings.
+- Use the WinBox CDB at its well-known location as the device datastore and
+  cache; overlay centrs metadata via comment-kv and groups.
+- Speak MikroTik peer-measurement protocols on explicit request — the bandwidth
+  test (`btest`), as both client and server — with the same envelope / identity /
+  error contract (but not the RouterOS-command validation gate).
+
+centrs does not:
+
+- Replace RouterOS syntax with high-level abstractions.
+- Treat passive discovery (MNDP) as authoritative inventory.
+- Run write-shaped operations without an explicit target and validation policy.
+- Make generated output the hand-edited source of truth.
+
+### Network listeners
+
+centrs opens a network listener in exactly two sanctioned places: the **proxy**
+surface (HTTP / remote access; `src/webproxy.ts`) and the **btest server**
+(`centrs btest server`, TCP/UDP port 2000). The btest server is an **explicit,
+foreground, user-invoked** command — not an always-on daemon, and not the proxy.
+It **binds loopback by default** (`--bind` to expose), **requires auth by
+default** (`authenticate=yes`, mirroring RouterOS), and is security-sensitive
+surface: treat credentials as redactable (`SECURITY.md`). The MCP server stays
+stdio-only and grows no listener of its own.
+
+## Invariants
+
+- One settings vocabulary across API/CLI/MCP/TUI/proxy.
+- Friendly, structured errors are part of the API contract — not optional polish.
+- Help text, source reporting, redaction, and bug-report envelopes are
+  shared-core, not per-frontend.
+- Integration tests prefer real CHR via `quickchr` over elaborate mocks when
+  behavior depends on RouterOS.
+- Generated docs are preferred when the source of truth is code, CLI metadata,
+  or schema.
+
+## Adjacent projects (grounding sources)
+
+- `tikoci/rosetta` — RouterOS docs / RAG.
+- `tikoci/restraml` — REST schema and inspect output.
+- `tikoci/m2ir` — protocol IR (WinBox, etc.), and the home for the
+  declarative "schema-as-data" approach to representing protocol internals
+  (consult it when WinBox-terminal / RoMON / heavy protocol work lands, rather
+  than hand-rolling protocol knowledge in centrs). Not an accessible source for
+  the RouterOS error-string vocabulary; ground error mappings on live CHR
+  strings.
+- `tikoci/lsp-routeros-ts` — canonicalization, parse-validation patterns.
+- `tikoci/vscode-tikbook` — peer RouterOS front-end (notebook UX); a source for
+  run-time error-string mapping (faults that pass `:parse` but fail at run).
+- `tikoci/quickchr` — CHR-backed integration test harness.
+
+When one of these owns a question, defer to it instead of restating here.
+
+External reference implementations to compare centrs protocol/transport work
+against (SSH patterns, native-API behavior, CDB format, WinBox framing) are kept
+as bibliography entries in `GLOSSARY.txt` — e.g. `netmiko`,
+`terraform-provider-routeros`, `librouteros-api`, `RouterOS_Tools`,
+`Winbox_Protocol_Dissector`.
+
+### Canonicalizer ownership
+
+centrs owns the **script-vs-structured execution gate** — the load-bearing
+discriminator for which validation runs and whether the write-confirmation prompt
+fires; widening what counts as `structured` is a product regression. The shared,
+pure command canonicalizer that `rosetta` / `lsp-routeros-ts` publish is for
+canonicalization only, never the structured-mode predicate. The gate contract,
+its pinning test, and the parser-vendoring preconditions are documented in
+`commands/execute/README.md` and the `canonicalizeExecuteCommand` doc-comment
+(`src/execute.ts`).

package/docs/MATRIX.md

@@ -0,0 +1,224 @@
+# Matrix
+
+The product is a 2D grid of commands × protocols. This file is the **only**
+source of truth for what is done. No alpha gates, no milestones, no roadmap
+prose.
+
+Pick the highest-priority cell that is not `CHR-passed`. That is the next
+work. See `docs/CONSTITUTION.md` for the cell-state definitions.
+
+## Cell states
+
+| State          | Meaning                                                         |
+| -------------- | --------------------------------------------------------------- |
+| `—`            | Not applicable / out of scope for this protocol                 |
+| `not-started` | No code and no design                                           |
+| `designed`     | `commands/<name>/README.md` describes intent and flags          |
+| `coded`        | Implementation exists in `src/`                                 |
+| `CHR-passed`   | Every example in `commands/<name>/examples.md` is green on CHR  |
+
+A cell advances only with the matching evidence in the same change.
+
+## Grid
+
+| Command  | rest-api      | native-api    | ssh           | mac-telnet    | snmp          | mndp          | romon         | winbox-terminal |
+| -------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ---------------- |
+| retrieve | `CHR-passed`  | `CHR-passed`  | —             | —             | `not-started` | —             | —             | —                |
+| stream   | —             | `designed`    | `designed`    | —             | —             | —             | —             | —                |
+| execute  | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | —             | —             | `not-started` | `not-started`    |
+| terminal | —             | —             | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —                |
+| transfer | `CHR-passed`  | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —                |
+| devices  | —             | —             | —             | —             | —             | —             | —             | —                |
+| discover | —             | —             | —             | —             | —             | `CHR-passed`  | —             | —                |
+| check    | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started` | `not-started`    |
+| settings | —             | —             | —             | —             | —             | —             | —             | —                |
+
+`devices` does not use a transport in the protocol sense, so its grid row stays
+`—`; its cell state is `CHR-passed`. `devices` performs no network IO, so that
+evidence is a fixture-backed `bun run test:integration` run
+(`test/integration/devices.test.ts`, every example in
+`commands/devices/examples.md`) against an in-test CDB (open + encrypted), not a
+booted CHR. The implemented surface (read subset, CDB mutation, lookup-key
+resolution, `(target, user)` identity, ambiguity / `--match`, profile sentinels,
+verb aliases, `__default__`, `tips[]`, provenance/override) and the one open item
+(ARP test scheme) are documented in `commands/devices/README.md`.
+
+`discover` is `CHR-passed`: the MNDP codec (`src/data/mndp.ts`), the TTL neighbor
+cache (`src/data/mndp-cache.ts`), the UDP listener, and `discover --save`
+(through `devices`' atomic write layer) live in `src/discover.ts`. The real-L2
+receive/decode/save path is green on RouterOS CHR 7.23.1 via
+`test/integration/discover.test.ts` (the quickchr `socket-connect` L2 bridge,
+`test/integration/mndp-l2-bridge.ts`; examples 1, 2, 4); the network-independent
+codec/cache/listener/`--save` paths stay unit-tested (examples 3, 5, 6, 7). The
+wire format, the de-dupe rule (`target`-keyed today, MAC-keyed is the decided
+target), TTL/timeout defaults, the live board-TLV finding (short board id vs the
+verbose REST `board-name`), and the L2 validation policy are documented in
+`commands/discover/README.md`.
+
+There is no `update` command: `execute` is the single read/write surface for
+RouterOS add/set/remove, and `retrieve` stays read-only. See
+`docs/CONSTITUTION.md` (protocol selection).
+
+`stream` is `designed` (no code yet): the read-only follow surface (NDJSON
+stream-of-envelopes; native-api/ssh only — REST's 60s cap cannot follow) is
+specified in `commands/stream/README.md`. The native-api streaming reader it will
+consume already exists (`src/protocols/native-api.ts`).
+
+`transfer` is `CHR-passed` for `rest-api`/`native-api` and for **sftp** (the
+`ssh` column's first method): `src/transfer.ts` + `src/cli/transfer.ts`
+(size/direction-aware method selection, leading-slash normalization, the
+`print`-probe existence guard, `--verify`) over the shared `FileBackend` seam,
+with the SFTP client in `src/protocols/sftp.ts` (host OpenSSH `sftp` subsystem;
+`scp` deferred). `test/integration/transfer.test.ts` is green on real CHR 7.23.1
+(110 assertions): the rest + native round-trip, the native `N1`–`N4` mirror, the
+sftp `S1`–`S5` round-trip, the stdin/stdout forms via the subprocess harness
+(examples 8–10), and example 17 (chunked REST read of an sftp-seeded >60 KB file).
+The method-selection grammar, the SFTP-vs-SCP rationale, the `--verify` behavior
+(sftp trusts the transfer guarantee; rest/native re-read the `/file` size), and the
+deferred `scp`/`fetch`/`ftp` methods are documented in
+`commands/transfer/README.md`.
+
+`execute / ssh` is `CHR-passed` (the second SSH consumer): a per-command batch
+client (`SshExecClient` in `src/protocols/ssh.ts` — one `ssh user@host "<cmd>"`
+per command, sharing `sftp.ts`'s host-`ssh` plumbing) behind the `SshExecAdapter`
+console transport (execute-only, like mac-telnet; structured reads/inspect
+unsupported). It reuses the mac-telnet `:put [:parse …]` gate verbatim. Green via
+`test/integration/execute-ssh.test.ts` (S1–S4) + `test/unit/ssh.test.ts`; the
+no-PTY / clean-output / `:parse` wire grounding lives in the `src/protocols/ssh.ts`
+header and `commands/execute/README.md`.
+
+`terminal / ssh` is `CHR-passed` (the third and last SSH consumer): it execs the
+host `ssh` with inherited stdio (`buildSshTerminalArgv` in `src/terminal.ts`,
+reusing `sshCommonOptions`) and lets the OS relay RouterOS's already-clean no-PTY
+console — no screen emulation. No `-t` is passed (`-tt` hangs RouterOS);
+`runTerminal` returns `ssh`'s exit code. A host target defaults to ssh, a MAC
+target to mac-telnet. Green via `test/integration/terminal-ssh.test.ts` (TS1/TS2),
+with argv unit-tested in `test/unit/terminal.test.ts`. **All three SSH cells
+(transfer/execute/terminal) are `CHR-passed`.** The no-PTY / exit-code semantics are documented in
+`src/terminal.ts`; the no-multi-line-brace limitation is in
+`commands/terminal/README.md`.
+
+`fetch` (centrs-as-HTTP-server + `/tool/fetch`) is a **deferred, explicit-only
+method within the rest-api/native-api cells**, not a grid column — it needs
+inbound reachability (router → centrs) so it is never auto-selected.
+
+`settings` is `designed` and transport-less (like `devices`), so its grid row
+stays `—`. `commands/settings/README.md` describes the `centrs.env` + `__default__`
+front-end (interactive first-time setup plus `settings get/set/reset/print`); no
+code yet.
+
+### Transport-base readiness (below the command grid)
+
+The grid above tracks command cells. The transports those cells ride are
+implemented and grounded in their `src/protocols/*.ts` **module headers** — the
+single home for wire-format, auth, and delivery facts (one fact, one place).
+Status here is terse; the module header carries the detail.
+
+- **native-api** (`src/protocols/native-api.ts`): word/sentence codec, streaming
+  reader, login (post-6.43 plaintext + legacy MD5 challenge), tagged command
+  multiplexing, typed error mapping. Live cell status is in the grid (`retrieve`,
+  `execute`, and `transfer` over `native-api` are all `CHR-passed`). Covered by
+  `test/unit/native-api.test.ts`, `test/integration/native-api.test.ts`
+  (transport), and `test/integration/native-api-retrieve.test.ts` (command).
+- **mac-telnet** (`src/protocols/mac-telnet.ts` + `mtwei.ts` +
+  `mac-telnet-console.ts` + `MacTelnetAdapter` in `adapter.ts`): packet/control
+  codec, session state machine, both auth methods (classic MD5 + MTWEI EC-SRP),
+  the interactive-console reader, and the UDP datagram transport with route
+  discovery. The deep findings — auth (MTWEI-required / MD5-refused /
+  `END_AUTH`≠success), console (ANSI terminal-size probe, ~10s prime stall,
+  one-time license gate, `:put [:parse]` syntax+semantic gate, silent writes),
+  reliability (byte-counter retransmit + empty-ACK keepalive), and the
+  real-device UDP-delivery facts (real egress MAC required; broadcast-only reply;
+  per-NIC directed-broadcast reach via `discoverMacTelnetRoute`; bind `0.0.0.0`)
+  — are documented in those module headers. Two cells are `CHR-passed`:
+  - **`execute / mac-telnet`**: `executeEnvelope` (resolver → `MacTelnetAdapter` →
+    UDP transport) runs reads, REST-verified writes, and the validation-reject
+    path. Green via `test/integration/mac-telnet-console.test.ts` (examples
+    19–21); transport/auth alone via `test/integration/mac-telnet.test.ts` (MTWEI
+    login + MD5 refusal). Unit: `test/unit/{mtwei,mac-telnet,mac-telnet-console}.test.ts`.
+  - **`terminal / mac-telnet`**: the interactive relay over the same console
+    reader (`MacTelnetConsole.attachInteractive`), orchestrated in
+    `src/terminal.ts` over an injectable `TerminalIo`, reusing the execute
+    resolver and the shared `resolveMacTelnetRoute`. Green via
+    `test/integration/terminal-mac-telnet.test.ts` (T1–T3) driving the real
+    `centrs terminal` binary through the subprocess harness.
+  - **Evidence caveat:** the CHR integration runs over the quickchr
+    `socket-connect` **L2 bridge** (`test/integration/mactelnet-l2-bridge.ts`), so
+    the real `createUdpMacTelnetTransport` egress/broadcast path is *not* exercised
+    in CI — the RB1100AHx4 / RouterOS 7.24beta1 real-device run grounded the
+    UDP-delivery facts (and caught the synthetic-source-MAC break). A full-TTY
+    `terminal` test (real PTY via `script(1)`/node-pty) is likewise deferred.
+
+### Frontend surfaces (orthogonal to the command grid)
+
+The grid tracks the core (commands × protocols). Frontends are adapters over that
+core and carry their own state, tracked here:
+
+| Surface | State | Spec | Notes |
+| ------- | ----- | ---- | ----- |
+| api (TS) | `CHR-passed` | `src/index.ts` | Root surface; everything else adapts it. |
+| cli | `coded` | `src/cli/` | `retrieve`/`execute`/`transfer`/`terminal`/`devices`/`discover`/`btest` wired. |
+| mcp | `CHR-passed` | `commands/mcp/` | Scoped-verb stdio MCP server; CDB-as-allowlist safety model. Phase 1 (explain/validate/retrieve/execute, resources) plus first Phase 2 CDB mutation (`centrs_devices add`) green on CHR 7.23 via `test/integration/mcp.test.ts`, including gated write execution. |
+| tui | `not-started` | `src/tui.ts` | Stub. |
+| proxy | `not-started` | `src/webproxy.ts` | Stub. |
+
+A surface advances to `CHR-passed` only when every example in its spec
+(`commands/<surface>/examples.md`, where one exists) is green via
+`bun run test:integration`. The `mcp` surface's tool list, CDB-as-allowlist safety
+model, and CHR test shape (examples 1–10, the `mcp=rw` + `confirm:true` write gate)
+are documented in `commands/mcp/README.md` and `commands/mcp/examples.md`.
+
+### Peer measurement (`btest`) — orthogonal to the command grid
+
+`btest` is the MikroTik **bandwidth test** (peer measurement, TCP/UDP port 2000)
+— *not* a RouterOS-command transport, so it sits outside the command×protocol
+grid as its own capability axis (`measure` in `src/protocols/index.ts`), exempt
+from the `:parse` / `/console/inspect` gate. v1 scope (decided with the user):
+**both** client and server, **EC-SRP5 + unauthenticated**, **TCP and UDP** (legacy
+pre-6.43 double-MD5 is out of scope).
+
+| Mode           | State        | Evidence |
+| -------------- | ------------ | -------- |
+| btest / server | `CHR-passed` | CHR `/tool/bandwidth-test` client → centrs server (TCP+UDP, unauth + EC-SRP5), CHR 7.23.1, `test/integration/btest.test.ts`. |
+| btest / client | `CHR-passed` | centrs client → CHR `/tool/bandwidth-server` over a host→guest `tcp:2000` forward — unauth + **EC-SRP5 client proof verified by real RouterOS** + wrong-pass reject (TCP receive), CHR 7.23.1, `test/integration/btest-client.test.ts`; plus client↔server loopback (`test/unit/btest-*.test.ts`). |
+
+The wire codec, the EC-SRP5 session/handshake (shared core byte-identical with
+mac-telnet's MTWEI, plus the net-new server role), the TCP/UDP data engines, the
+orchestrator + CLI, and the honest grounding caveat (the server gets direct CHR
+evidence over the QEMU SLIRP gateway `10.0.2.2`; the client gets direct CHR
+evidence over a host→guest `tcp:2000` forward — TCP only; UDP-receive is a soft
+smoke test and UDP client→CHR-server stays loopback/transitive over the SLIRP
+reverse path; TCP `connection-count > 1` fan-out is deferred; NDJSON is not
+adopted) are documented in `commands/btest/README.md` and the
+`src/protocols/btest.ts`, `src/protocols/btest-session.ts`, and
+`src/protocols/ec-srp5.ts` module headers.
+
+## Priority order
+
+Do not start a later item until the earlier cell or dependency checkpoint has
+matching evidence. The grid above is the live status; per-item detail lives in
+the linked `commands/<name>/`.
+
+1. **retrieve / rest-api** — `CHR-passed`. The shakedown for everything else (`commands/retrieve/`).
+2. **CDB resolution + metadata overrides** — `CHR-passed` (`commands/devices/`).
+3. **CDB groups + fanout** — `CHR-passed` (`commands/devices/`, Fanout).
+4. **execute / native-api + rest-api** — `CHR-passed` (`commands/execute/`). The single write path; there is no `update`.
+5. **devices** (CDB mutation + provenance) — `CHR-passed` (`commands/devices/`).
+6. **retrieve / snmp** — `not-started` (future: SNMP OID/MIB reads + MikroTik MIB cache).
+7. **ssh** for transfer/execute/terminal — **all three `CHR-passed`** (landed transfer-first; the `transfer`/`execute`/`terminal` READMEs + `src/protocols/ssh.ts` and `src/protocols/sftp.ts`).
+8. **mac-telnet** for execute/terminal — both `CHR-passed` (`src/protocols/mac-telnet.ts` + `src/protocols/mac-telnet-console.ts`). Optional polish: the ~10s prime-latency fix and a full-TTY terminal test under a real PTY.
+9. **RoMON / WinBox Terminal for execute** — `not-started` (see Open questions).
+10. **discover / mndp** — `CHR-passed` (`commands/discover/`).
+11. **MCP, TUI, proxy** — frontends over the stable core. **MCP** is `CHR-passed` for Phase 1 + the first Phase 2 CDB mutation (`commands/mcp/`); next small step is the device-free `centrs mcp --list-tools` manifest dump (bench token-footprint measurement). MCP stays **stdio-only** (HTTP is the proxy's job). **TUI / proxy** `not-started`.
+12. **btest (peer measurement)** — server **and** client both `CHR-passed` (`commands/btest/`). Own protocol axis; shares EC-SRP5 with mac-telnet, so it can proceed in parallel.
+
+## Open questions (decisions needed before the affected cell can advance)
+
+| Question | Affects cell | Notes |
+| -------- | ------------ | ----- |
+| RoMON / WinBox Terminal validation and CI | execute / romon, execute / winbox-terminal | Lower priority than mac-telnet; need reference tooling and typed failure mapping before advancing. |
+
+Recently closed (folded into the specs): SNMP MIB-cache policy → `commands/retrieve/README.md`; bug-report rendering (inline `--bug-report` flag, no separate verb) → `docs/CONSTITUTION.md`; L2-in-CI for mac-telnet/MNDP (quickchr `socket-connect` host-side L2 capture; `socket-mcast` is macOS-broken) → `commands/discover/README.md` + `commands/execute/README.md`.
+
+When a question is answered, fold the answer into the relevant
+`commands/<name>/README.md` or `docs/CONSTITUTION.md`, then delete the row.