@tikoci/centrs 0.1.2 → 0.1.4

package/docs/CLI.md

@@ -0,0 +1,353 @@
+# centrs CLI reference
+
+<!-- GENERATED FILE — do not edit. Regenerate with `bun run docs:cli`. -->
+<!-- Source of truth: the CliCommandMetadata objects in src/cli/*.ts -->
+
+Every flag below is generated from the same metadata that renders
+`centrs <command> --help`; CI fails when this file and the metadata drift
+(`bun run docs:cli --check`). Behavior, examples, and designed-but-not-yet
+implemented flags live in each command's `commands/<name>/README.md`.
+
+| Command | Summary |
+| ------- | ------- |
+| [`retrieve`](#retrieve) | Read RouterOS values through the shared core using the selected protocol. |
+| [`execute`](#execute) | Run a RouterOS read or write command via native API, REST, or mac-telnet. |
+| [`api`](#api) | Structured RouterOS API passthrough (gh-api style) over REST or native API. |
+| [`transfer`](#transfer) | Copy files to/from a RouterOS device and manage device files (rest/native/sftp). |
+| [`terminal`](#terminal) | Open an interactive RouterOS console (ssh or mac-telnet). |
+| [`explain`](#explain) | Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics. |
+| [`devices`](#devices) | Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB. |
+| [`discover`](#discover) | Discover RouterOS neighbors over MNDP and optionally save them into the CDB. |
+| [`btest`](#btest) | Run MikroTik's bandwidth test as a client or server (peer measurement). |
+| [`mcp`](#mcp) | Start the centrs MCP server (stdio) — scoped RouterOS tools gated by the CDB allowlist. |
+| [`settings`](#settings) | Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record. |
+
+## retrieve
+
+Read RouterOS values through the shared core using the selected protocol.
+
+```text
+Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<protocol>` | Pin the protocol selector. Defaults to `rest-api` for retrieve. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--timeout` | &lt;ms\|5s&gt; | Operation timeout. REST currently rejects values above 60s. |
+| `--attribute` | `<name>` | Project one attribute. May be repeated. |
+| `--attributes` | `<a,b>` | Project a comma-separated attribute list. |
+| `--all-attributes` |  | Request the RouterOS detail/all-attributes shape. |
+| `--list-attributes / --list` |  | List inspect-derived attributes without running the data call. |
+| `--query / --filter` | `<expr>` | RouterOS-side row filter (maps to `.query`). Not implemented yet — returns `validation/not-implemented`. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--max-results` | `<bytes>` | Fail instead of printing output larger than the given byte budget. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--validate / --no-validate` |  | Enable or disable inspect-backed preflight validation. |
+| `--verbose` |  | Show resolved setting sources in text output. |
+
+## execute
+
+Run a RouterOS read or write command via native API, REST, or mac-telnet.
+
+```text
+Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --group <name> <command> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | &lt;native-api\|rest-api\|mac-telnet&gt; | Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--ssh-key` | `<path>` | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the `ssh-agent`. |
+| `--insecure` |  | Disable SSH host-key verification (`--via ssh`: accepts changed/impersonated keys, not just new) or accept a self-signed `api-ssl` TLS cert. Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
+| `--validate / --no-validate` |  | Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted). |
+| `--yes` |  | Confirm write-shaped add/set/remove commands in non-interactive runs. |
+| `--max-results` | `<bytes>` | Fail if the rendered envelope exceeds this byte budget. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--verbose` |  | Include additional context in text output. |
+| `--` |  | End centrs option parsing: every following token is the literal RouterOS command, even flag-shaped ones (e.g. `-- /interface print where disabled=yes`). |
+
+## api
+
+Structured RouterOS API passthrough (gh-api style) over REST or native API.
+
+```text
+Usage: centrs api <router> <endpoint> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `-X / --method` | `<verb>` | HTTP method, default GET (case-insensitive). GET→print, PUT→add, PATCH→set, DELETE→remove, POST→run. |
+| `-f / --field` | `<key=value>` | Body field, repeatable; assembled into the JSON body (verbatim string values). |
+| `-d / --data` | `<json>` | Raw JSON request body. Conflicts with `-f` / `--input`. |
+| `--input` | &lt;file\|-&gt; | Read the raw JSON body from a file or stdin (`-`). |
+| `--query / --filter` | `<expr>` | RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name. |
+| `--raw-query` | `<word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions. |
+| `--attribute / --proplist` | `<a,b>` | Property projection → `.proplist`. |
+| `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does not imply `--yes`. |
+| `--yes` |  | Confirm a mutating (non-read) request in non-interactive runs. |
+| `--stream / --listen` |  | Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope. |
+| `--count` | `<n>` | Stop a `--stream` after N change frames. |
+| `--duration` | `<dur>` | Stop a `--stream` after this wall-clock window (e.g. `5s`). |
+| `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username. Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--insecure` |  | Accept a self-signed `api-ssl`/REST TLS cert. Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
+| `--validate / --no-validate` |  | Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted). |
+| `--format` | &lt;json\|yaml\|text&gt; | Output format. Defaults to json for api; `CENTRS_FORMAT` overrides. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--verbose` |  | Include additional context in text output. |
+
+## transfer
+
+Copy files to/from a RouterOS device and manage device files (rest/native/sftp).
+
+```text
+Usage: centrs transfer <router> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction. |
+| `--ssh-key` | `<path>` | sftp only: explicit private-key path. Falls back to CENTRS_SSH_KEY / the ssh-agent. |
+| `--insecure` |  | Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies. |
+| `--force / --overwrite` |  | Replace an existing destination. Default refuses it. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--out-dir` | `<dir>` | `download` fan-out only: write one file per target into `<dir>`, named by CDB identity. Required when downloading across a selection. |
+| `--yes` |  | Confirm a mutating fan-out (upload/remove/mkdir/copy) across multiple routers in non-interactive runs. |
+| `--verify / --no-verify` | &lt;size\|checksum\|off&gt; | Post-transfer integrity check. Default size; `--no-verify` skips. |
+| `--type` | &lt;file\|directory\|disk\|package&gt; | list filter: RouterOS /file row type. |
+| `--name` | `<glob>` | list filter: file-name glob. |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
+| `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |
+| `--timeout` | &lt;ms\|5s&gt; | Operation timeout. REST rejects values above 60s. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format. Defaults to text; --json / --yaml shortcuts. |
+| `--json` |  | Shortcut for --format json. |
+| `--yaml` |  | Shortcut for --format yaml. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--validate / --no-validate` |  | Enable or disable the existence-probe preflight. |
+| `--verbose` |  | Show the resolved transport in text output. |
+
+## terminal
+
+Open an interactive RouterOS console (ssh or mac-telnet).
+
+```text
+Usage: centrs terminal <router> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<method>` | Transport: `ssh` (host target, default) or `mac-telnet` (MAC target, default for a MAC). rest/native have no terminal capability. |
+| `--host` | `<host>` | Override the target host (ssh) / UDP delivery host (mac-telnet, default L2 broadcast). |
+| `--port` | `<port>` | Override the port: ssh default 22, mac-telnet default 20561. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
+| `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |
+| `--source-mac` | `<mac>` | mac-telnet: explicit in-packet source MAC (overrides egress resolution). |
+| `--ssh-key` | `<path>` | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the `ssh-agent`. |
+| `--insecure` |  | `--via ssh`: disable host-key verification (accepts changed/impersonated keys). Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | `--via ssh` only: turn a MAC target into an IP. CDB-first; `arp` opts into the host ARP cache (default none). The mac-telnet default ignores it. |
+| `--format` | &lt;text\|json\|yaml&gt; | Error-envelope format on failure. --json / --yaml shortcuts. |
+| `--json` |  | Shortcut for --format json. |
+| `--yaml` |  | Shortcut for --format yaml. |
+| `--verbose` |  | Verbose error output. |
+
+## explain
+
+Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics.
+
+```text
+Usage: centrs explain '<input>' [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--file` | `<path>` | Read the input from a file instead of the positional (`-` reads stdin). Piped stdin is used automatically when no input positional is given. |
+| `--fail-on` | &lt;error\|warning\|never&gt; | Exit 2 when the verdict reaches this severity. Default `error`; an ambiguous or unknown statement is a warning, never an error. |
+| `--complete` |  | Continuation candidates at the cursor. Live evidence — offline emits a tip and enumerates nothing. |
+| `--schema` |  | Path enumeration (verbs, args, types, enums). Live evidence — offline emits a tip and enumerates nothing. |
+| `--curl` |  | Render a ready-to-edit REST curl for statements covered by a runtime-tested mapping rule. |
+| `--tokens` |  | Emit the total, gapless token partition behind `data.tokens[]` (provisional `class` until #264 B5: every byte not claimed by an analyzer is `unclassified`). |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--yaml` |  | Shortcut for `--format yaml`. |
+| `--verbose` |  | Verbose error output. |
+
+## devices
+
+Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
+
+```text
+Usage: centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes. |
+| `--via` | `<protocol>` | Resolve and report the protocol source for provenance examples; no network IO is performed. |
+| `--group` | `<name>` | `list` filter / `add`,`edit` first-class group field for the target entry. |
+| `--where` | `<attr=value>` | `list` only — repeatable device-class filter over CDB facts (AND-combined), e.g. `--where lat=37.7749`. |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | `list` only — GPS filter: devices within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | `list` only — GPS filter: devices inside the lat-first bounding box. |
+| `--members` |  | `groups` only — expand each group's membership. |
+| `--explain` |  | `show` only — include the raw `WinBoxCdbRecord` in `data.record`. |
+| `--match` | &lt;user=…\|target=…\|record-type&gt; | `show` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token. |
+| `--user` | `<name>` | `add`,`set` — first-class CDB user field. |
+| `--password` | `<secret>` | `add`,`set` — first-class CDB password field. |
+| `--profile` | `<name>` | `add`,`set` — named WinBox profile (Workspace). |
+| `--profile-none` |  | `add`,`set` — write the WinBox `<none>` profile sentinel. |
+| `--profile-own` |  | `add`,`set` — write the WinBox `<own>` profile sentinel. |
+| `--session` | `<name>` | `add`,`set` — first-class CDB session field. |
+| `--comment` | `<text>` | `add` only — base free-form comment (may include kv-soup). |
+| `--record-type` | &lt;macTarget\|ipAdmin\|ipUser\|romonNeighbor\|romonTarget&gt; | `add` only — record type (default `ipAdmin`). |
+| `--lat / --latitude` | `<deg>` | `add`,`set` — latitude in decimal degrees (-90..90); a comment-kv fact, paired with --lon. |
+| `--lon / --lng / --longitude / --long` | `<deg>` | `add`,`set` — longitude in decimal degrees (-180..180); a comment-kv fact, paired with --lat. |
+| `--altitude / --alt / --ele / --elevation` | `<meters>` | `add`,`set` — altitude in meters (may be negative); a comment-kv fact. |
+| `--altitude-type / --alt-type` | &lt;MSL\|AGL&gt; | `add`,`set` — vertical datum for --altitude (default MSL); case-insensitive. |
+| `--gps` | `<lat>`,`<lon>`[,`<altitude>`[,`<altitude-type>`]] | `add`,`set` — combined lat,lon[,altitude[,altitude-type]] convenience (lat-first; missing altitude-type defaults MSL). |
+| `--force` |  | `add` only — overwrite the existing (target, user) entry. |
+| `--strict` |  | `add`,`set` — reject unknown comment kv keys instead of warning. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+## discover
+
+Discover RouterOS neighbors over MNDP and optionally save them into the CDB.
+
+```text
+Usage: centrs discover [--timeout 15s] [--save] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--timeout` | &lt;ms\|15s&gt; | Listen window before results are returned. Default 15s. |
+| `--save` |  | Persist discovered neighbors into the CDB (`group=discovered`, `source=mndp`). |
+| `--group` | `<name>` | `--save` group for new entries. Default `discovered`. |
+| `--port` | `<port>` | UDP port to bind for MNDP. Default 5678. |
+| `--cdb-file` | `<path>` | `--save` CDB path override (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | `--save` password for an encrypted CDB. Used to decrypt the existing CDB and re-encrypt on write. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+## btest
+
+Run MikroTik's bandwidth test as a client or server (peer measurement).
+
+```text
+Usage: centrs btest <client <router>|server> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--protocol` | &lt;udp\|tcp&gt; | (client) Transport. Default udp. |
+| `--direction` | &lt;receive\|transmit\|both&gt; | (client) Test direction. Default receive. |
+| `--duration` | `<dur>` | Bound the run (e.g. 15s). Omit for open-ended (Ctrl-C). |
+| `--interval` | `<dur>` | Report cadence (20ms..5s). Default 1s. |
+| `--connection-count` | `<n>` | (client, TCP only) Parallel TCP data connections (1..255). |
+| `--local-udp-tx-size` | `<n>` | (client, UDP only) Client→server packet size (28..64000). |
+| `--remote-udp-tx-size` | `<n>` | (client, UDP only) Server→client packet size (28..64000). |
+| `--local-tx-speed` | `<bps>` | (client) Cap on client→server rate (e.g. 100M). |
+| `--remote-tx-speed` | `<bps>` | (client) Cap on server→client rate (e.g. 100M). |
+| `--random-data` |  | (client) Incompressible payload. |
+| `--nat-mode` |  | (client, UDP only) Originate an outbound datagram first so server→client data can traverse NAT. Automatic when the test receives. |
+| `--authenticate / --no-authenticate` |  | (server) Require EC-SRP5 auth. Default true; `--authenticate=false` also accepted. |
+| `--bind` | `<addr>` | (server) Listen address. Default 127.0.0.1. |
+| `--allocate-udp-ports-from` | `<n>` | (server) Base of the UDP data-port range. Default 2001. |
+| `--max-sessions` | `<n>` | (server) Concurrent test cap (1..1000). Default 100. |
+| `--user / --username / -u` | `<name>` | Credential (aliases --username, -u; falls back to CDB / CENTRS_USERNAME). |
+| `--password` | `<secret>` | Credential (falls back to CDB / CENTRS_PASSWORD). |
+| `--port` | `<port>` | Control port. Default 2000. |
+| `--cdb-file` | `<path>` | (client) Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | (client) Decrypt an encrypted WinBox CDB file. |
+| `--format` | &lt;text\|csv\|json\|yaml&gt; | Output format. Default text. |
+| `--csv` |  | Shortcut for `--format csv`. |
+
+## mcp
+
+Start the centrs MCP server (stdio) — scoped RouterOS tools gated by the CDB allowlist.
+
+```text
+Usage: centrs mcp [start] [--cdb-file <path>] [--allow-adhoc-targets]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--cdb-file` | `<path>` | CDB allowlist path (default `~/.config/tikoci/winbox.cdb`, or CENTRS_CDB_FILE). |
+| `--cdb-password` | `<password>` | Decrypt password for an encrypted CDB (or CENTRS_CDB_PASSWORD). |
+| `--allow-adhoc-targets` |  | Reserved unsafe escape hatch for future inline targets; current tools still use CDB-only targets. |
+| `--help` |  | Show this help. |
+
+## settings
+
+Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record.
+
+```text
+Usage: centrs settings [print|get|set|reset] [args] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--all` |  | `print` only — also list unrecognized CENTRS_* lines found in the file. |
+| `--cdb-file` | `<path>` | `print` only — CDB to probe for the `__default__` record summary (falls back to normal CDB resolution; never centrs.env). |
+| `--cdb-password` | `<secret>` | `print` only — decrypt password for the probed CDB. |
+| `--skip-env-file` |  | `print` only — note that other commands in this environment would not see centrs.env (settings itself always reads the real file). |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--help` |  | Show this help. |

package/docs/CONSTITUTION.md

@@ -37,21 +37,29 @@ re-validate-server-side. Validation is not optional polish.
   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).
+  a semantic gate. Grounded on CHR 7.23.3 (GH#230), **`:parse` never throws** —
+  it returns a script value whose printed form carries the verdict. For a bare
+  menu path a clean parse prints `(evl /canonical/path)` with abbreviations
+  expanded; for script-shaped input (e.g. `:put …`, `:global …`, `where …`) the
+  accepted return echoes the script body and may contain arbitrary text such as
+  `expected`. Rejection forms are `(evl bad parameter <name> (line N column M)
+  /path)`, `(<%% bad command name <name> (line N column M) …)`, and the
+  line-anchored `expected … (line N column M)` (spellings: `expected end of
+  command`, `expected command name`, `expected input value`) / `syntax error
+  (line N column M)`. That text rides the **HTTP-200 `ret` value** (REST,
+  `as-string`), the native `as-string` `ret`, and the console's printed output
+  alike — so a single `:put [:parse ...]` covers both the syntax and the
+  **unknown-attribute** gate on every transport. centrs sends `as-string` and now
+  reads the `ret`/printed value (the previous gate ignored it, so it rejected
+  nothing). Because the accepted return echoes the body, the matcher must anchor
+  on the diagnostic shape (the `(<%%` wrapper, or a trailing `(line N column M)`)
+  and never on a bare English word — `expected` is also a real
+  `/ip/firewall/connection` field name.
+  That unknown-attribute check is **name-level only**: `:parse` does not validate
+  parameter *values* (`/ip/address/add address=not-an-ip` parses clean). So a
+  clean parse is necessary, not sufficient, and value-type plus the remaining
+  semantic validation stay distinct steps — `/console/inspect` or the server's
+  own re-validation on the write round-trip.
 - **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
@@ -221,24 +229,82 @@ must round-trip through the same envelope.
 
 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 a single-session `api --stream` follow are not fan-out surfaces and reject
-N>1 with `usage/fanout-not-supported`.
+`--all` (every CDB record, **excluding** the reserved `__default__` record),
+`--default` (the `__default__` record), and repeatable `--where <attr>=<value>` —
+a **device-class** selector that matches CDB-stored facts/comment-kv **plus core
+record fields** (`target`/`identity`/`group`/`mac`; core fields win so a comment
+token cannot spoof them), AND-combined across repeats. A call is in **fan-out
+mode** when any selector flag is present **or** more than one positional target is
+given; a plain single-positional call stays single-target. The union is
+**de-duped by CDB record index** (ad-hoc literal targets by host) and run through
+the same per-target pipeline.
+
+Fan-out output is the locked **`FanoutData`** envelope: `data = { summary, targets[]
+}`, where the outer `ok` reports **orchestration** success and a per-target failure
+is an inner `ok:false` envelope (output, not metadata). `targets[]` is reassembled
+in resolved record order, not completion order, so repeated runs diff cleanly. The
+**process exit code** is granular and uniform across fan-out commands: `0` every
+target ok (or an empty selection), `2` partial (some ok, some failed), `1`
+orchestration error or every target failed.
+
+A multi-target **RouterOS write** (e.g. `execute` / `api` add/set/remove across a
+selection) is gated by **`--yes`**, confirmed **once** up front; when it is missing
+the error names the blast radius (how many routers). The separate **`--force`**
+gate is scoped to destructive **`devices` CDB mutations** (e.g. `devices remove`
+across a group), not RouterOS writes. `terminal` and single-session `stream` /
+`api --stream` are not fan-out surfaces and reject N>1 with
+`usage/fanout-not-supported`; `api --raw` is rejected in fan-out mode with
+`usage/conflicting-flags` (it strips the per-target envelope).
 
 `--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.
+response. Two layers, two flag families. `--near <lat>,<lon>,<radius>` and
+`--bbox <south>,<west>,<north>,<east>` are geo union predicates over device GPS
+(**lat-first, decimal degrees**; radius units `m`/`km`/`mi`/`ft`, bare = km);
+geo-less devices never match. They join the same union — a device matches when it
+falls in `--near`'s radius **or** `--bbox`.
 
 `--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.
 
+#### Resolution providers
+
+Target resolution has **two independent axes**, and centrs keeps them separate so
+the resolver is generalized **once**, not per source (the umbrella plan is #174):
+
+- **Axis A — selection** ("which devices"): the target-selection grammar above.
+- **Axis B — connection-fact origin** ("where host/port/auth for a member come
+  from"): what a resolved member yields. Today: a **CDB record** or an ad-hoc
+  **literal** (+ the `__default__` ladder). Tomorrow: a live descriptor or an
+  inventory entry.
+
+Sources fall into two kinds, and the distinction is normative:
+
+- **Selector-source** — participates in the Axis-A grammar. **CDB** (now), and
+  **TikTOML** next (#137). Multiple selector-sources union into one selection;
+  the split-brain precedence between them is #137's problem, not resolved here.
+- **Named-live-provider** — addressed *only* by an explicit named flag, **never**
+  matched by a selector; fanned out by repeating the flag. Because it owns an
+  **ephemeral** endpoint it also **bypasses** the settings/`__default__` ladder and
+  **conflicts** with `--host`/`--port`/`--username`/`--password`/`--ssh-key`. These
+  are properties of *live/ephemeral* providers, not of any one provider. **quickchr**
+  (`--quickchr <name>`, #134) is the first. A named-live-provider selection is
+  **exclusive** (v1): mixing it with `<router>` positionals or selector flags is
+  `usage/conflicting-flags` — one flag stays single-target, repeating it fans
+  out. Relaxing exclusivity later is additive.
+
+Connection facts resolve into one neutral **per-service endpoint map**
+(`src/resolver/service-endpoint.ts`: `via → ServiceEndpoint`, each carrying
+availability, host, port, TLS, auth, and provenance). A **selector-source** is the
+*degenerate single-endpoint* case — one record materialized lazily once `--via` is
+known. A **named-live-provider** populates the map directly, since it genuinely
+exposes different facts per transport. Providers must **not** be flattened to a
+single host/port: that shape is the contract quickchr's descriptor and TikTOML's
+`services` block both map onto, and flattening it forces exactly the re-plumb #174
+exists to prevent. A `--via` whose service key a provider does not supply is a
+typed unsupported-provider error, never a silent fallback.
+
 ### MCP surface: the CDB is the allowlist
 
 The MCP frontend (`commands/mcp/`) is an adapter over this core, not a new set of
@@ -281,7 +347,11 @@ Rules:
 - **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.
+  reported in `meta.warnings` with its reason. For `api`'s fan-out path, this
+  and "Validation is the product" above are also checked structurally by
+  CodeQL (`.github/codeql-house-rules/missing-required-gate.ql` —
+  `apiFanout` must call `assertApiProtocolSupported`/`validateApiRequestShape`;
+  scoped to `apiFanout` only today).
 - **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
@@ -415,3 +485,9 @@ 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`).
+
+Richer schema-free analysis must distinguish **ambiguous** (multiple plausible
+readings) from **unknown** (no safe reading) and abstain in both cases rather than
+inventing a command, path, symbol class, or transport mapping. These explain-only
+verdicts never widen or reinterpret the execution gate's `mode` or `writeShaped`
+decision.