@tikoci/centrs 0.1.0

package/commands/mcp/README.md

@@ -0,0 +1,260 @@
+# mcp
+
+The MCP frontend: an [Model Context Protocol](https://modelcontextprotocol.io)
+server that exposes the centrs core to AI agents through a **small, scoped set of
+verbs** over the same canonicalize → validate → run path the CLI/API use. It is
+not a per-command tool firehose.
+
+Status: `CHR-passed` (Phase 1 + first Phase 2 CDB mutation). The stdio server
+(`src/mcp/server.ts`, `tools.ts`, `safety.ts`, `resources.ts`, `config.ts`) is
+built and the examples below (1–10) run green against CHR 7.23 via
+`test/integration/mcp.test.ts`, including the gated `mcp=rw` + `confirm:true`
+RouterOS write and in-band CDB registration through `centrs_devices add`.
+`src/mcp.ts` is the runtime barrel (`@tikoci/centrs/mcp`); `docs/MATRIX.md` is
+the authoritative status.
+
+Run it:
+
+```bash
+bunx @tikoci/centrs mcp           # stdio transport (default)
+centrs mcp                        # same, when installed
+centrs mcp start                  # explicit verb; equivalent to the above
+```
+
+Bun is required (centrs uses Bun APIs and the bun-native CDB codec), as with
+`@tikoci/rosetta`.
+
+## Client install snippets
+
+For an MCP client that accepts JSON server config, use `bunx` directly:
+
+```json
+{
+  "mcpServers": {
+    "centrs": {
+      "command": "bunx",
+      "args": ["@tikoci/centrs", "mcp"],
+      "env": {
+        "CENTRS_CDB_FILE": "/absolute/path/to/winbox.cdb"
+      }
+    }
+  }
+}
+```
+
+If `centrs` is already installed on `PATH`, the equivalent command is:
+
+```json
+{
+  "mcpServers": {
+    "centrs": {
+      "command": "centrs",
+      "args": ["mcp"],
+      "env": {
+        "CENTRS_CDB_FILE": "/absolute/path/to/winbox.cdb"
+      }
+    }
+  }
+}
+```
+
+Use `CENTRS_CDB_PASSWORD` to read or write an encrypted CDB. The write layer
+decrypts under the loaded password, mutates the record set, and re-encrypts with
+a fresh salt before the atomic rename. Prefer an unencrypted throwaway CDB for
+bench harnesses and CI.
+
+## Why a scoped surface (grounding)
+
+`~/GitHub/bench-routeros-tools` (`REPORT.md`, `docs/REPORT_LIVE_CHR.md`)
+benchmarked RouterOS agent support. Load-bearing findings that shape this design:
+
+- **Never expose one tool per RouterOS command.** A 166-tool execution MCP costs
+  ~28K always-on tokens and, even free, is ambiguous to select (36/166 tools
+  match a task; the correct tool is a clear top-3 pick only 62% of the time;
+  destructive tools sit lexically next to safe ones). The recommendation is a
+  *handful of verbs* over a canonical `{path, verb, args}`, gated by validation.
+- **explain → validate → run split.** A cheap, safe knowledge/validation tier
+  gates a thin runner. centrs already has this shape internally.
+- **The parse scheme catches parser-level truth that schema-inspect can miss.** In
+  the bench, `/console/inspect` accepted a command form the real console parser
+  rejected. RouterOS 7.23 no longer reproduces that exact `blackhole=yes` case,
+  but the lesson stands: schema-presence is not parser-acceptance.
+  `:put [:parse "<cmd>"]` runs the real parser, and centrs runs **both** `:parse`
+  and `/console/inspect`, so the MCP exposes validation as a first-class
+  **dry-run** tool (`centrs_validate`) that never mutates.
+- **Stateful intents need device-validate-before-apply.** Gold using
+  `interface=ether2` fails on a CHR exposing only `ether1`. Pair `execute` with
+  cheap readback (`retrieve`).
+
+## Intent
+
+- One MCP tool per centrs **verb**, not per RouterOS command. Each tool is a thin
+  adapter over the existing core function and returns the standard envelope
+  (`{ ok, data?, warnings?, error?, meta }`) as JSON text content — the same
+  shape the CLI renders (constitution: result envelope; invariant: one settings
+  vocabulary across API/CLI/MCP/TUI/proxy).
+- Validation is the product here too: `validate=true` by default, lead with
+  `:parse`, never disable to make a call pass (constitution: validation).
+- The MCP server is an adapter over the root TypeScript API; it adds no new
+  RouterOS semantics, only the MCP transport, the tool schemas, and the
+  CDB-backed safety boundary below.
+
+## Tools
+
+| Tool | Core mapping | Reads/Writes | Target source |
+| ---- | ------------ | ------------ | ------------- |
+| `centrs_explain` | `canonicalizeExecuteCommand` | offline, none | none (string only) |
+| `centrs_validate` | execute validation only (`:parse` + `/console/inspect`), **no run** | read-only | CDB |
+| `centrs_retrieve` | `retrieve` / `retrieveGroup` | read-only | CDB |
+| `centrs_execute` | `execute` | read or write | CDB |
+| `centrs_devices` | `devices` (`list`/`show`/`groups`/`add`/`edit`/`set`/`remove`) | CDB read/write | CDB file |
+| `centrs_discover` | `discover` (`listen` + optional `save`) | local read; `save` writes CDB | n/a |
+
+- `centrs_explain` is the only tool that needs no CDB and no device — it
+  canonicalizes a CLI string to `{ path, verb, args, mode, writeShaped }` so an
+  agent can plan before touching anything. centrs owns the script-vs-structured
+  gate (constitution: canonicalizer ownership); the MCP must not widen what
+  counts as `structured`.
+- `centrs_validate` is the headline distilled from the bench: a dry-run that runs
+  the real parser plus schema inspection against a registered target and returns
+  the validation envelope **without executing**. Use it to reject schema-invalid
+  commands before any write.
+- `centrs_retrieve` mirrors `retrieve`, including attribute projection,
+  `listAttributes`, and `group` fanout.
+- `centrs_execute` mirrors `execute`. Read-shaped commands run subject only to
+  CDB membership; write-shaped add/set/remove are gated by the CDB policy below.
+  Its MCP `destructiveHint` is **conservative — always `true`**, even though the
+  tool also serves read-shaped commands: a single execute tool cannot vary the
+  static annotation by argument, so it advertises the worst case and lets the
+  canonicalizer's write-shape check + the CDB `mcp=rw`/`confirm` gates do the real
+  enforcement. Agents that route purely on read-only commands should prefer
+  `centrs_retrieve` (truly `readOnlyHint`).
+- `centrs_devices` is the in-band way to inspect and grow the allowlist:
+  `list`/`show`/`groups` are read-only; `add`/`set`/`remove` mutate the active CDB
+  and require `confirm: true`. `edit` is reserved for the future interactive
+  editor and returns `usage/not-implemented` (use `set` to modify a record). MCP
+  device envelopes redact saved passwords and expose only `passwordSet`.
+- `centrs_discover` mirrors `discover`: it listens for MNDP neighbors, returns
+  the standard discovery envelope, and can persist found neighbors into the
+  active CDB with `save: true` + `confirm: true`. Saved records use the same
+  provenance/group behavior as the CLI and no RouterOS credentials are returned.
+
+## Safety model — the CDB is the allowlist
+
+The authorization boundary is the WinBox CDB (constitution: identity and CDB),
+which is already centrs's device registry **and** native credential store. The
+MCP server applies it as a hard allowlist:
+
+- **Targets resolve through the CDB only** — by name, MAC, or `group`. Inline
+  ad-hoc `host` + `username` + `password` are **rejected by default** with
+  `cdb/target-not-registered`, whose `fix` points at `centrs_devices add`. An
+  agent therefore cannot reach an arbitrary router with arbitrary credentials.
+- **CDB source** follows the constitution: default
+  `~/.config/tikoci/winbox.cdb`, overridden by `CENTRS_CDB_FILE` / `--cdb-file`,
+  or a freshly created CDB the operator hands the server at start. An encrypted
+  CDB is decrypted with `--cdb-password` (or `CENTRS_CDB_PASSWORD`). With no CDB,
+  the server still serves `centrs_explain` (offline); CDB mutations require a
+  loadable CDB file.
+- **Credentials live in the CDB and are never returned by MCP.** `centrs_devices
+  add`/`edit` may write credentials into the active CDB, but tool results and
+  resources redact saved passwords and expose only `passwordSet`.
+- **Per-device RouterOS read/write policy lives in the CDB.** A device is
+  writable only when its record opts in via the comment-kv key `mcp=rw` (default
+  `ro`). Reads are allowed for any registered device. Write-shaped
+  `centrs_execute` calls require the resolved target to be `mcp=rw`; `mcp` joins
+  the comment-kv allowlist (`src/resolver/comment-kv.ts`) and, per the
+  constitution, must round-trip through env/CLI/API as well as CDB.
+- **Per-call `confirm: true`** stays as a belt-and-suspenders for write-shaped
+  calls (the non-TTY analogue of the CLI's `--yes`). A RouterOS write attempt
+  against an `mcp=ro` target fails with typed `cdb/write-not-permitted`
+  regardless of `confirm`; a local CDB mutation through `centrs_devices` or
+  `centrs_discover` `save` fails with `usage/confirmation-required` unless
+  explicitly confirmed.
+- **`--allow-adhoc-targets`** (off by default) is reserved for one-off lab/power
+  user flows. Current RouterOS-facing tools expose no inline host+credential
+  schema, so the CDB allowlist remains the only active target source.
+
+This makes the safety story declarative and auditable: *what the agent may touch*
+and *whether it may write* are both data in a file the operator controls, not
+flags buried in a prompt.
+
+## Resources
+
+The server publishes two read-only MCP **resources** and points its
+`instructions` at them so a client discovers them without guessing:
+
+- `centrs://devices` — the known devices in the active CDB (the allowlist
+  itself): target, group, user, record type, and the resolved `mcp` write policy
+  per record. No passwords. This is how an agent learns what it may act on.
+- `centrs://errors` — the centrs error-code catalog: each known `family/code`
+  with its stable details URL (`https://tikoci.github.io/centrs/errors/<code>`),
+  including the MCP-specific `cdb/target-not-registered` and
+  `cdb/write-not-permitted`. Lets an agent resolve an envelope error without a
+  round-trip.
+
+## Transports
+
+- **stdio is the only MCP transport.** It matches the common local MCP client
+  model and keeps the agent boundary on the operator's machine.
+- **HTTP is the proxy surface's job, not the MCP server's.** Remote/HTTP access
+  to CDB-gated RouterOS lives in `src/webproxy.ts` (the `centrs-proxy` surface),
+  which fronts the same CDB. The MCP server deliberately grows no HTTP/TLS
+  listener of its own, so there is one place that owns network exposure.
+
+## Future work
+
+- **Manifest dump for benchmarking (`centrs mcp --list-tools`).** A device-free
+  command that prints the registered tool + resource schemas and the server
+  `instructions` as JSON, so a harness can measure centrs's always-on context
+  cost the same way `bench-routeros-tools` counts mikrotik-mcp's 166 schemas —
+  without booting a CHR. Pairs with the stable example IDs already mapped in
+  `examples.md` (example N ↔ one assertion in `test/integration/mcp.test.ts`) so
+  the bench can cite per-trap results. Requested by the bench review
+  (`~/GitHub/bench-routeros-tools/docs/AGENTIC_FUTURES.md` → "benchmark centrs as
+  the realized scoped-execution tier").
+- **`__default__` fallback-credentials CDB record** is now a **core** concept,
+  not MCP-specific — see `docs/CONSTITUTION.md` (Default-device record) and
+  `commands/devices/README.md`. It supplies fallback creds/metadata for a device
+  whose own record leaves them unset (precedence args → ENV → device →
+  `__default__` → built-in). MCP-specific rule: `__default__` **never widens the
+  allowlist** — an unregistered target is still rejected; `__default__` only
+  fills missing creds for an already-registered device (see the safety model
+  above). Implementation lands with packaging (Phase 4).
+- **MikroTik docs enrichment.** `centrs_explain` may later annotate a canonical
+  `{path, verb}` with a link into MikroTik's new Docusaurus manual at
+  <https://manual.mikrotik.com> (CLI/API reference, still WIP upstream). This is
+  an independent, optional reference — centrs does not depend on rosetta or any
+  other MCP for its canonicalization.
+
+## Open shape questions
+
+These are resolved for the current design and recorded here for provenance:
+
+- **HTTP transport** → owned by the proxy surface, not MCP (resolved).
+- **Doc context** → centrs logic only; `manual.mikrotik.com` is a future,
+  optional enrichment source (resolved).
+- **Resources vs tools** → ship both `centrs://devices` and `centrs://errors` as
+  resources, advertised via server instructions (resolved).
+
+These refinements sit on top of the grounded surface above; none blocks the
+Phase 1 stdio read/validate cells.
+
+## CHR test shape
+
+Per the done definition, MCP cells advance only with CHR evidence. The
+integration test (`test/integration/mcp.test.ts`) boots a CHR via
+`@tikoci/quickchr`, registers it in a throwaway CDB to exercise the allowlist
+boundary, starts the server, and drives it with an in-process MCP client over
+stdio. It asserts, at minimum:
+
+- an unregistered target is rejected (`cdb/target-not-registered`);
+- `centrs_validate` accepts parser-valid command text and rejects
+  schema-invalid attributes without executing;
+- `centrs_retrieve` returns structured records;
+- `centrs_execute` (read-shaped) runs and returns the envelope;
+- a write against an `mcp=ro` target is refused (`cdb/write-not-permitted`) and
+  the same write against an `mcp=rw` target succeeds with `confirm: true`;
+- `centrs_devices add` writes a new record into the throwaway CDB and returns no
+  saved password material.
+
+Each example in `commands/mcp/examples.md` maps to one such assertion.

package/commands/mcp/examples.md

@@ -0,0 +1,158 @@
+# mcp — examples
+
+Each numbered example is an executable spec for the MCP surface. The integration
+test `test/integration/mcp.test.ts` boots a CHR 7.23 router with
+`@tikoci/quickchr`, registers it in a throwaway CDB, starts the centrs MCP server
+over stdio, and drives it with an in-process MCP client. Each example below maps
+to one assertion. 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`).
+
+These examples are MCP **tool calls** (JSON `params.arguments`), not shell
+commands. `$NAME` is the CDB name the harness assigns the booted CHR; `$U` / `$P`
+are CHR credentials stored in the CDB record for RouterOS actions. Example 10
+also writes credentials into the throwaway CDB through `centrs_devices add`, but
+MCP never returns saved password material. The result is the standard centrs
+envelope returned as the tool's JSON text content.
+
+## Phase 1 — read + validate (stdio)
+
+### 1. `centrs_explain` canonicalizes offline (no CDB, no device)
+
+```json
+{ "name": "centrs_explain",
+  "arguments": { "command": "/ip/route/add dst-address=10.99.0.0/24 blackhole=yes" } }
+```
+
+Envelope: `ok: true`, `data.path = "/ip/route"`, `data.verb = "add"`,
+`data.mode = "structured"`, `data.writeShaped = true`, `data.args` includes
+`dst-address` and `blackhole`. No network or CDB access occurs.
+
+### 2. Unregistered target is rejected (CDB is the allowlist)
+
+```json
+{ "name": "centrs_retrieve",
+  "arguments": { "target": "192.0.2.1", "path": "/system/resource" } }
+```
+
+Envelope: `ok: false`, `error.code = "cdb/target-not-registered"`, and
+`error.fix`/`remediation` names `centrs_devices add`. No connection is attempted.
+RouterOS-facing MCP tools accept only a CDB `target` (name/MAC/URL) — there is
+no inline `host`/`username`/`password` executor parameter, so RouterOS actions
+use credentials already stored in the CDB.
+
+### 3. `centrs_validate` accepts the bare `blackhole` flag
+
+```json
+{ "name": "centrs_validate",
+  "arguments": { "target": "$NAME",
+                 "command": "/ip/route/add dst-address=10.99.0.0/24 blackhole" } }
+```
+
+Envelope: `ok: true`, `meta.validation.source` includes `:put [:parse]` (the
+RouterOS parser accepted the bare flag), and **no route is created** (dry-run
+only — a follow-up `centrs_retrieve` of `/ip/route` shows no `10.99.0.0/24`). A
+bare flag like `blackhole` routes through script-mode `:parse`, so the
+`/console/inspect` semantic gate does not apply here — `:parse` is the gate that
+matters for the bench gold-bug in example 4.
+
+### 4. `centrs_validate` rejects a schema-invalid command (the dual gate)
+
+```json
+{ "name": "centrs_validate",
+  "arguments": { "target": "$NAME",
+                 "command": "/ip/route/add dst-address=10.99.0.0/24 nonexistentattr=1" } }
+```
+
+Envelope: `ok: false`, `error.code = "validation/unknown-attribute"` — the
+`/console/inspect` semantic gate rejects the unknown attribute and **no route is
+created**. This proves the validate tool fails closed on bad input.
+
+> Bench note: the bench's original gold-bug command
+> `/ip/route/add dst-address=10.99.0.0/24 blackhole=yes` (where `/console/inspect`
+> accepted a value the console `:parse` rejected) does **not** reproduce on
+> RouterOS 7.23 — the device parser now accepts `blackhole=yes`. centrs still runs
+> **both** gates (`:parse` + `/console/inspect`) so the stricter of the two wins
+> whenever a version does reject it; this example asserts the still-true,
+> version-robust behavior (unknown-attribute rejection) instead.
+
+### 5. `centrs_retrieve` returns structured records
+
+```json
+{ "name": "centrs_retrieve",
+  "arguments": { "target": "$NAME", "path": "/system/resource",
+                 "attributes": ["version", "board-name"] } }
+```
+
+Envelope: `ok: true`, `data` is a single object carrying `version` and
+`board-name` (the `/system/resource` menu is a single record, not a list),
+`meta.via = "rest-api"`.
+
+### 6. `centrs_execute` runs a read-shaped command
+
+```json
+{ "name": "centrs_execute",
+  "arguments": { "target": "$NAME", "command": "/system/identity/print" } }
+```
+
+Envelope: `ok: true`, `meta.operation.request.write = false`, and
+`meta.validation` shows the parse gate ran.
+
+## CHR-verified gated writes
+
+### 7. Write against an `mcp=ro` target is refused
+
+With `$NAME` registered `mcp=ro` (default):
+
+```json
+{ "name": "centrs_execute",
+  "arguments": { "target": "$NAME",
+                 "command": "/ip/address/add address=198.51.100.10/32 interface=ether1",
+                 "confirm": true } }
+```
+
+Envelope: `ok: false`, `error.code = "cdb/write-not-permitted"`. The router is not
+mutated even though `confirm` is true — the CDB policy is authoritative.
+
+### 8. Write against an `mcp=rw` target succeeds with `confirm: true`
+
+With `$NAME` registered `mcp=rw`:
+
+```json
+{ "name": "centrs_execute",
+  "arguments": { "target": "$NAME",
+                 "command": "/ip/address/add address=198.51.100.10/32 interface=ether1 comment=centrs-mcp",
+                 "confirm": true } }
+```
+
+Envelope: `ok: true`, `data.ret` matches `/^\*[0-9A-F]+$/`,
+`meta.operation.request.write = true`, `meta.validation.source` includes both
+`:parse` and `/console/inspect`.
+
+### 9. Write without `confirm` on an `mcp=rw` target fails closed
+
+```json
+{ "name": "centrs_execute",
+  "arguments": { "target": "$NAME",
+                 "command": "/ip/address/remove [find comment=centrs-mcp]" } }
+```
+
+Envelope: `ok: false`, `error.code = "usage/confirmation-required"`; the address
+added in example 8 still exists. (Cleanup runs with `confirm: true`.)
+
+## CHR-verified CDB mutations
+
+### 10. `centrs_devices add` grows the allowlist in-band
+
+```json
+{ "name": "centrs_devices",
+  "arguments": { "op": "add", "target": "lab-edge",
+                 "user": "$U", "password": "$P",
+                 "comment": "mcp=ro",
+                 "confirm": true } }
+```
+
+Envelope: `ok: true`, the CDB now resolves `lab-edge`, `data.entry.password` is
+absent, and `data.entry.passwordSet` reports whether a password was saved. A
+subsequent `centrs_devices show` for `lab-edge` succeeds. This uses the
+throwaway CDB; no real device is contacted by the registration itself.

package/commands/retrieve/README.md

@@ -0,0 +1,209 @@
+# retrieve
+
+Read RouterOS state. RouterOS menu reads model `<path>/<verb>` where the verb
+is `print`-style (`print`, `get`, and async POST-shaped reads as they're
+added). SNMP reads use `retrieve <router> snmp <oid|MIB name>` and resolve
+names through a MikroTik MIB cache downloaded from mikrotik.com.
+
+> "POST-shaped reads" are RouterOS menu reads that require a request body
+> (e.g. paged or query-driven `print`) and are therefore issued as REST `POST`
+> rather than `GET`. centrs identifies them from the command tree and routes
+> them accordingly as they're added.
+
+Structured formats return an array of records, or — with `--attribute` — a
+value or row of values wrapped in the standard envelope
+(`docs/CONSTITUTION.md`). The default `text` format renders data and errors for
+humans.
+
+## Synopsis
+
+```text
+centrs retrieve <router> <path>[/<shortcut>] [flags]
+centrs retrieve <router> snmp <oid|MIB name> [flags]
+```
+
+- `<router>` — IP, DNS, MAC, or CDB-resolved name. See constitution: identity.
+- `<path>` — RouterOS path beginning with `/`, e.g. `/ip/address`. The verb is
+  inferred (`print` for list paths, `get` for singletons like
+  `/system/resource`). If the unnamed arg does not start with `/`, it is a
+  reserved shortcut — currently none are defined; future examples include
+  `defconf` → `/system/default-configuration/get`.
+- Reading one row by name is **flag-only** (there is no row positional):
+  `--query name=ether1` filters RouterOS rows and returns an **array**; the
+  caller takes the match. `--query`/`--filter` always return an array — there is
+  no singleton-by-name shape. (Decided: the old `<.id|name>` positional is
+  dropped.)
+- `snmp <oid|MIB name>` — planned retrieve-only SNMP form. OIDs are used
+  directly; MIB names are resolved from the cached MikroTik MIB that matches
+  the selected RouterOS version/channel once that cache is implemented.
+
+## Flags
+
+| Flag                                | Behavior                                                                                  |
+| ----------------------------------- | ----------------------------------------------------------------------------------------- |
+| `--attribute <name>`                | Project a single attribute. Repeatable, or comma-separated.                               |
+| `--attributes <a,b,c>`              | Alias for `--attribute` with comma-separated input.                                       |
+| `--all-attributes`                  | Equivalent to RouterOS `details=true`. Mutually exclusive with `--attribute(s)`.          |
+| `--list-attributes` (alias `--list`) | Return the available attribute names for the path. No `print`/`get` is run.              |
+| `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is the separate `stream` verb. See constitution: protocol selection. |
+| `--query <expr>`                    | RouterOS-side **row** filter (maps to `.query`), repeatable; returns matching rows as an **array**. This is how you read one row by name (`--query name=ether1`). **Not Implemented** yet — returns `validation/not-implemented`. |
+| `--filter <expr>`                   | RouterOS row filter; same `.query` mapping and not-implemented handling as `--query`.       |
+| `--where <attr>=<value>`            | Device-class selector: fan out across CDB records whose stored fact/comment-kv matches (e.g. `--where board=RB5009`). Repeatable (AND). Filters *which devices*, not RouterOS rows. See constitution: target selection. |
+| `--max-bytes <n>`                   | Byte budget for the rendered payload. If the response would exceed it, centrs truncates to fit, keeps `ok: true`, and adds a warning + `meta.truncated`. Not an error. (Renamed from `--max-results`; the legacy flag still parses until the code split lands.) |
+| `--max-rows <n>`                    | Maximum row count for list reads. Excess rows are clipped; `ok: true` with a warning + `meta.truncated`.                                    |
+| `--format text` (default)           | Human-readable rendering (default). Errors print `[code] summary` + `Fix:` lines. |
+| `--format json` (alias `--json`)    | Structured JSON envelope (set `CENTRS_FORMAT=json` to make it the default).               |
+| `--format yaml` (alias `--yaml`)    | YAML rendering of the same envelope.                                                      |
+| `--resolve <none\|arp>`             | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.             |
+| `--via <protocol>`                  | Pin the transport (`rest-api` default, or `native-api`). No silent downgrade. See constitution: protocol selection. |
+| `--validate=false`                  | Escape hatch; default is `true`. See constitution: validation is the product.             |
+| `--timeout <ms>`                    | Request timeout. REST: ≤ 60000. native-api allows longer.                                 |
+| `--username` (alias `--user`, `-u`) / `--password` | Override CDB-resolved or env credentials.                                                 |
+| `--host <host\|url>`                 | Override the resolved host or base URL for the target.                                     |
+| `--port <n>`                        | Override the transport port. native-api defaults to 8728 (TLS api-ssl when `--port 8729`).|
+| `--cdb-file` / `--cdb-password`     | Override CDB file location / decrypt password.                                            |
+| `--ros-version <version>`           | SNMP MIB lookup only: pin the MikroTik MIB version to cache/download.                     |
+| `--ros-channel <channel>`           | SNMP MIB lookup only: `stable`, `long-term`, `testing`, or `development`; default `stable`. |
+| `--group <name>`                    | Fan out across every CDB target in WinBox group `<name>`. Repeatable, and combinable with `<router>` positionals plus `--all`/`--default`; the union is de-duped by CDB record index. See **Group fanout**. |
+| `--concurrency <n>`                 | Max in-flight targets during fanout (integer ≥ 1). Defaults are transport-aware: `rest-api` 8, `native-api` 4. Rejected with `usage/invalid-concurrency` otherwise. |
+
+## Validation
+
+Default validator: `/console/inspect request=syntax path=<comma-joined>,print`
+(or `,get` for singleton paths). Validator must reject unknown paths and
+unknown attributes with `validation/*` codes that include the inspect-suggested
+alternatives in the error envelope.
+
+If `--all-attributes` is combined with `--attribute(s)`, fail with
+`usage/conflicting-flags` *before* hitting the network.
+
+SNMP validation is separate from RouterOS `/console/inspect`: OIDs and MIB
+names must resolve through the MIB cache before any SNMP request is sent.
+
+## SNMP MIB cache policy
+
+Signed off (2026-06-06): cache MikroTik MIBs under the XDG cache root,
+`${XDG_CACHE_HOME:-~/.cache}/tikoci/snmp-mibs`, not beside the CDB. The cache is
+derived data; deleting it must never remove inventory or credentials. Use one
+subdirectory per exact RouterOS version, for example
+`routeros/7.23/mikrotik.mib`, plus metadata containing source URL, ETag,
+Last-Modified, SHA-256, fetched-at, and the channel (if a channel resolved it).
+
+Version selection for MIB-name lookup is deterministic. `--ros-version` wins and
+downloads `https://download.mikrotik.com/routeros/<version>/mikrotik.mib`.
+Otherwise `--ros-channel` (default `stable`) is resolved through
+`https://upgrade.mikrotik.com/routeros/NEWESTa7.<channel>` and that exact version
+is used. If target metadata already carries a RouterOS version from a trusted
+source, it may supply the default version, but the SNMP path must not make an
+extra REST/native call merely to discover a version.
+
+Invalidation is by exact version plus HTTP validators. A missing version cache is
+downloaded before lookup; an existing cache is reused offline. When online, a
+cache older than 24h is revalidated with ETag/Last-Modified and replaced
+atomically if MikroTik republishes the file. Channel pointers are short-lived:
+re-resolve the channel after 24h, then use the cache for the resulting exact
+version.
+
+Offline behavior is intentionally conservative. Numeric OIDs do not require the
+MIB cache and proceed normally. MIB-name lookup succeeds only when the selected
+exact version is already cached; if not, fail before SNMP I/O with
+`snmp/mib-cache-miss` and a fix that tells the caller to go online once or pass a
+cached `--ros-version`. Do not silently fall back to a different version's MIB.
+
+RouterOS grounding: MikroTik documents SNMP as retrieve/write-capable but centrs
+uses it as retrieve-only; the same page points users to the MikroTik MIB download
+surface. The per-version `mikrotik.mib` URL under `download.mikrotik.com` has
+been verified for current stable/development versions, but treating it as the
+long-term canonical URL is an assumption until the implementation has fallback
+handling.
+
+## Output shape
+
+```ts
+{
+  ok: true,
+  data: [ { ".id": "*1", address: "192.0.2.1/24", ... }, ... ],   // array of rows
+  // or for singletons (e.g. /system/resource):
+  // data: { uptime: "...", "cpu-load": 7, ... },
+  // or for --attribute:
+  // data: "192.0.2.1/24",       // single value
+  meta: { target, via, settings, validation, timing }
+}
+```
+
+`--max-bytes` / `--max-rows` truncation populates
+`meta.truncated = { returned, total, totalBytes }` and keeps `ok: true` with a
+warning entry — it is not an error. (Earlier text said a byte overflow returns an
+*error* with the needed size; superseded — truncation is an `ok: true` footnote so
+partial data stays usable.)
+
+## Group fanout
+
+`--group <name>` loads the CDB once, expands every matching WinBox record in
+that group, de-dupes by CDB record index, and runs the same per-target retrieve
+pipeline for each target. Per the shared target-selector grammar, `--group` is
+repeatable and combines freely with one or more `<router>` positionals, `--all`
+(every CDB record), and `--default` (the `__default__` record); the union is
+de-duped by CDB record index. (Earlier drafts made `--group` mutually exclusive
+with a positional — superseded by the liberal selector model.)
+
+Fanout output is one outer envelope whose `ok` reports orchestration success:
+`ok: false` is reserved for failures before reliable per-target results exist
+(for example invalid flags or CDB decrypt failure). Per-target success/failure
+is data, not metadata:
+
+```ts
+{
+  ok: true,
+  data: {
+    summary: { total: 2, ok: 1, failed: 1 },
+    targets: [
+      { ok: true, data: { ... }, meta: { target: { recordIndex: 0 }, ... } },
+      { ok: false, error: { code: "transport/connection-refused", ... }, meta: { target: { recordIndex: 1 }, ... } }
+    ]
+  },
+  warnings: [],
+  meta: {
+    target: {},
+    via: "rest-api", // null if inner targets disagree on protocol
+    settings: { ... },
+    operation: {
+      kind: "fanout",
+      group: "prod-edge",
+      concurrency: 8,
+      summary: { total: 2, ok: 1, failed: 1 },
+      request: { path: "/system/resource", validate: true, format: "json", ... }
+    }
+  }
+}
+```
+
+An empty or unknown group is `ok: true` with
+`data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`, and a
+`cdb/empty-group` warning. Validation runs per target because RouterOS schemas
+can differ by version. Fanout retries each target up to two times only for
+`transport/network` and `transport/connection-closed`; REST 5xx failures are
+mapped to `transport/connection-closed`. It does not retry `routeros/*`,
+`validation/*`, `auth/*`, `cdb/*`, `target/*`, timeouts, DNS, TLS, or refused
+connections.
+
+## Definition of done
+
+This command is `CHR-passed` only when every line in `examples.md` runs green
+against a real CHR through `bun run test:integration`. Disabling validation to
+reach green is forbidden. See `docs/CONSTITUTION.md` for the full done rule.
+
+## Notes for future cells
+
+- **native-api** — implemented for retrieve (`--via native-api`, `CHR-passed`;
+  see `examples.md` N1–N11 and `test/integration/native-api-retrieve.test.ts`).
+  Validation still runs through `/console/inspect` (issued as a native-API
+  command). Attribute values arrive as strings because the binary API carries
+  no JSON scalar types; the envelope shape is otherwise identical to REST.
+- **snmp** — retrieve-only OID/MIB reads. It does not validate through
+  `/console/inspect` and does not execute RouterOS CLI.
+- **ssh / mac-telnet / romon / winbox-terminal** — execute surfaces, not
+  retrieve surfaces.
+- **tips** — when a `<router>` fails to resolve against an empty CDB, retrieve
+  emits the same `tip/no-devices` advice as `devices list`, steering toward
+  `centrs devices discover` and `centrs settings`.