@tikoci/centrs 0.1.9-next.24 → 0.1.9

package/docs/CLI.md

@@ -11,7 +11,7 @@ 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. |
+| [`execute`](#execute) | Run a RouterOS read or write command via native API, REST, SSH, 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). |
@@ -64,13 +64,14 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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, on stderr. |
 
 ## execute
 
-Run a RouterOS read or write command via native API, REST, or mac-telnet.
+Run a RouterOS read or write command via native API, REST, SSH, or mac-telnet.
 
 ```text
 Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --host <host|url> [--] <command> [flags] | centrs execute --group <name> <command> [flags]
@@ -78,7 +79,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 
 | 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. |
+| `--via` | &lt;native-api\|rest-api\|ssh\|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. |
@@ -97,9 +98,10 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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). |
+| `--validate / --no-validate` |  | Run offline analysis, then RouterOS :parse, plus `/console/inspect` for structured commands over native API/REST (default true; `--validate=false` disables both stages). |
 | `--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. |
@@ -145,9 +147,10 @@ Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <en
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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). |
+| `--validate / --no-validate` |  | Validate structured requests with `/console/inspect`; `/execute` scripts run offline analysis, then RouterOS :parse (default true; `--validate=false` disables both stages). |
 | `--format` | &lt;json\|ndjson\|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, on stderr. |
@@ -162,7 +165,7 @@ Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download
 
 | 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. |
+| `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers; `ssh` is an alias); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction, after a CDB record's `via=` (ssh→sftp). |
 | `--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` |  | Skip the existing-destination check on the device for `upload`/`mkdir`/`copy` (`upload` then overwrites). Default refuses an existing target. `download` always replaces the local file. |
@@ -189,6 +192,7 @@ Usage: centrs transfer <router>|--host <host> upload <local> [remote] | download
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--validate / --no-validate` |  | Enable or disable the existence-probe preflight. |
 | `--verbose` |  | Show the resolved transport in text output, on stderr. |
 
@@ -212,6 +216,7 @@ Usage: centrs terminal <router> [flags] | centrs terminal --host <host> [flags]
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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. |
@@ -258,23 +263,27 @@ Usage: centrs explain [<router>] '<input>' [flags]
 Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
 
 ```text
-Usage: centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]
+Usage: centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args] [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
+| `--encrypt` |  | `init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB. |
+| `--no-backup` |  | `encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered. |
 | `--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. |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
 | `--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. |
+| `--group` | `<name>` | `list` filter / `add`,`set` 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. |
+| `--explain` |  | `show` only — include the raw `WinBoxCdbRecord` in `data.record` (its password field reads `<redacted>` unless `--show-password`). |
+| `--match` | &lt;user=…\|target=…\|record-type&gt; | `show`,`set`,`remove` — 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. |
+| `--password-stdin` |  | `add`,`set` — read the record password from stdin (one trailing newline stripped) so it never rides argv. Conflicts with `--password`. |
+| `--show-password` |  | `show`,`add`,`set` — include the record password in cleartext. By default output carries `passwordSet` and withholds the password. |
 | `--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. |
@@ -291,6 +300,38 @@ Usage: centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]
 | `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
 | `--json` |  | Shortcut for `--format json`. |
 
+### devices init
+
+Create an empty CDB at the resolved path; existing readable files are left unchanged.
+
+```text
+Usage: centrs devices init [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--encrypt` |  | `init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB. |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+### devices encrypt
+
+Encrypt an existing CDB in place, or verify an already-encrypted file; existing backups remain unchanged.
+
+```text
+Usage: centrs devices encrypt [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--no-backup` |  | `encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered. |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
+| `--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.
@@ -340,6 +381,7 @@ Usage: centrs btest <client <router>|server> [flags]
 | `--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. |
+| `--match` | &lt;user=name\|target=addr\|record-type&gt; | (client) Pick one of several CDB records saved for `<router>` (as `devices show --match`); `btest server` rejects it. |
 | `--format` | &lt;text\|csv\|json\|yaml&gt; | Output format. Default text. |
 | `--csv` |  | Shortcut for `--format csv`. |
 

package/docs/MATRIX.md

@@ -189,7 +189,9 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 Live `explain` (#236) is `CHR-passed` on REST and native API: the #491
 foundation, #492's describe and completion facets, and #225's live value types,
 with every applicable example green on stable and long-term CHR. Issue #90
-owns the remaining sequencing, including #507 context grounding.
+owns the remaining sequencing, including #507's context surface. Its bounded
+submission matrix is grounded (#574); context selection and binding behavior
+remain follow-up work.
 
 **First: `explain`** (maintainer decision 2026-10-16 on
 [#90](https://github.com/tikoci/centrs/issues/90)). In order: make the
@@ -253,8 +255,8 @@ applicable examples pass on CHR via `bun run test:integration`.
 
 Open offline follow-ups remain explicit but do not reopen the verified baseline.
 Issue #211 made an unlisted absolute bare path abstain (rule F, R14); rule
-P's closed-world reading is still not adopted (#372). #272 owns
-non-authoritative `.scratch/` citation cleanup. Issues #350 (the broad
+P's closed-world reading is still not adopted (#372). The non-authoritative
+scratch citation cleanup is complete (#272, shipped in #568). Issues #350 (the broad
 optional `=`), #351 (a relative submenu brace read as a command operand)
 and #355 (`'` is not a RouterOS token) are complete. A submenu block after a navigation statement
 (`/ip⏎address { … }`) keeps the pre-#351 reading; see

package/docs/errors/cdb/encrypt-failed.md

@@ -0,0 +1,10 @@
+# `cdb/encrypt-failed`
+
+The existing CDB could not be rewritten with encryption.
+
+## Fix
+
+Check directory permissions and available disk space, then retry
+`centrs devices encrypt`. Preserve the original file and any timestamped backups
+before recovery. A failed write may already have created a plaintext backup;
+encryption does not protect that backup.

package/docs/errors/cdb/password-required.md

@@ -1,9 +1,10 @@
 # `cdb/password-required`
 
-The CDB is encrypted; a --cdb-password is required to read it.
+A CDB password is required for decryption or explicit encryption.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `cdb/password-required`.
+Pass `--cdb-password` or set `CENTRS_CDB_PASSWORD` to the CDB password.
+`devices init --encrypt` and `devices encrypt` require a non-empty password,
+even when the file is currently open. A password alone never implicitly
+converts an existing open CDB; use `devices encrypt` explicitly.

package/docs/errors/cdb/plaintext-backups.md

@@ -0,0 +1,11 @@
+# `cdb/plaintext-backups`
+
+CDB backups may still contain plaintext credentials after encryption.
+
+## Fix
+
+Apply your own secure backup and retention policy to the `.bak.*` files beside
+the CDB. `devices encrypt` protects only the active CDB and retains every backup,
+including the plaintext snapshot created during conversion. It does not encrypt
+or delete old copies. This warning also accompanies already-encrypted no-op runs,
+since prior backup protection cannot be inferred from the active file.

package/docs/errors/input/empty-stdin.md

@@ -0,0 +1,27 @@
+# `input/empty-stdin`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) received
+nothing.
+
+`centrs devices add`/`set --password-stdin` strips one trailing newline (`\n`
+or `\r\n`) and refuses what is left if it is empty. An empty pipe is usually a
+mistake — an unset variable, a missing file, a command that printed nothing —
+so it is not treated as "clear the password".
+
+## Fix
+
+Pipe a non-empty value:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices set 192.0.2.5 --password-stdin
+centrs devices set 192.0.2.5 --password-stdin < pw.txt
+```
+
+To clear a stored password on purpose, say so with the argv flag:
+
+```bash
+centrs devices set 192.0.2.5 --password ""
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

package/docs/errors/input/invalid-routeros-path.md

@@ -1,9 +1,31 @@
 # `input/invalid-routeros-path`
 
-The RouterOS path is malformed (it must be slash-prefixed).
+The RouterOS path is malformed: not slash-prefixed, a segment that is not a
+menu name, or characters a REST URL would reinterpret.
+
+## Typical triggers
+
+- A path without a leading slash: `retrieve <router> ip/address`.
+- A `retrieve` or `api` path segment that is not a RouterOS menu name. Menu
+  names are letters, digits and hyphens (case folds) (`/interface/6to4`,
+  `/ip/dhcp-server`). The check runs on every transport and even with
+  `--validate=false`, because a read must only dispatch a read (#586).
+- A REST request path containing `?`, `#`, `\`, a control character, or a
+  `.`/`..` segment, including percent-encoded forms such as `%2e%2e`. The
+  URL parser would turn these into a query, a fragment
+  or a different path, so the request would not reach the path as written.
+  Before this guard, `retrieve '/system/reboot#' --no-validate` posted
+  `/rest/system/reboot`.
+
+`context.path` names the path; `context.invalidSegments` lists the segments
+that failed the menu grammar.
 
 ## Fix
 
+- Write the path as slash-separated menu names: `/ip/address`,
+  `/system/resource`.
+- Select rows with `--query` (for example `--query 'name="a#b"'`), not with
+  characters in the path.
+
 See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `input/invalid-routeros-path`.
+contract.

package/docs/errors/input/invalid-stdin.md

@@ -0,0 +1,28 @@
+# `input/invalid-stdin`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) received
+bytes that are not valid UTF-8 text, or began with a byte-order mark.
+
+`centrs devices add`/`set --password-stdin` strips one trailing newline (`\n`
+or `\r\n`) and decodes the rest as UTF-8. The CDB stores record strings as
+UTF-8 and drops a leading byte-order mark (U+FEFF) when it reads them back, so
+malformed bytes or a BOM would store a credential different from what was
+piped in. centrs refuses instead of guessing. The bytes are never echoed.
+
+## Fix
+
+Pipe the password as plain UTF-8 text:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices set 192.0.2.5 --password-stdin
+```
+
+If the value comes from a file an editor saved with a BOM (common on Windows),
+re-save it as UTF-8 without BOM, or strip the first three bytes:
+
+```bash
+tail -c +4 pw.txt | centrs devices set 192.0.2.5 --password-stdin
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

package/docs/errors/usage/stdin-is-tty.md

@@ -0,0 +1,21 @@
+# `usage/stdin-is-tty`
+
+A flag that reads its value from stdin (e.g. `--password-stdin`) was given
+while stdin is a terminal.
+
+`--password-stdin` exists for automation: the value arrives on fd 0 so it never
+appears in argv or `ps`. centrs does not prompt for it at a terminal — waiting
+on a keyboard with no prompt would look like a hang, and echoing a typed secret
+would defeat the point. Interactive prompting is tracked separately.
+
+## Fix
+
+Pipe or redirect the value:
+
+```bash
+printf '%s' "$ROUTER_PW" | centrs devices add 192.0.2.5 --user admin --password-stdin
+centrs devices add 192.0.2.5 --user admin --password-stdin < pw.txt
+```
+
+See [`commands/devices/README.md`](https://github.com/tikoci/centrs/blob/main/commands/devices/README.md)
+for the record-password channels.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.24",
+	"version": "0.1.9",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -9,21 +9,21 @@
 	},
 	"homepage": "https://github.com/tikoci/centrs#readme",
 	"bugs": "https://github.com/tikoci/centrs/issues",
-	"packageManager": "bun@1.4.2",
+	"packageManager": "bun@1.4.4",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.5.15",
+		"@biomejs/biome": "2.6.3",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
-		"@types/bun": "1.4.2",
+		"@types/bun": "1.4.4",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
-		"markdownlint-cli2": "^0.23.3",
+		"markdownlint-cli2": "^0.24.0",
 		"secretlint": "^13.0.7",
 		"typedoc": "^0.28.20"
 	},
 	"optionalDependencies": {
-		"@tikoci/quickchr": "^0.4.8"
+		"@tikoci/quickchr": "^0.5.2"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
@@ -42,7 +42,7 @@
 	},
 	"description": "All-in-one TypeScript library/CLI/MCP for interacting with MikroTik RouterOS devices (TUI stub)",
 	"engines": {
-		"bun": ">=1.3.11 <2"
+		"bun": ">=1.4.4 <2"
 	},
 	"private": false,
 	"files": [
@@ -118,6 +118,8 @@
 		"explain:operator-readme:check": "bun run scripts/explain-operator-slice.ts --readme --check",
 		"explain:operator-slice": "bun run scripts/explain-operator-slice.ts",
 		"explain:probe:brace-slots": "bun run scripts/probes/explain-brace-slot-sweep.ts",
+		"explain:probe:context-matrix": "bun run scripts/probes/explain-context-matrix.ts",
+		"explain:probe:corrected-anchors": "bun run scripts/probes/explain-corrected-anchors.ts",
 		"explain:probe:escapes": "bun run scripts/probes/explain-escape-sweep.ts",
 		"explain:probe:highlight-recapture": "bun run scripts/probes/explain-highlight-recapture.ts",
 		"explain:probe:operators": "bun run scripts/probes/explain-operator-sweep.ts",
@@ -125,6 +127,8 @@
 		"explain:probe:symbol-arms-score": "bun run scripts/probes/explain-symbol-arms-score.ts",
 		"explain:probe:symbol-bad-sigil-replay": "bun run scripts/probes/explain-symbol-bad-sigil-replay.ts",
 		"explain:probe:symbol-classes-replay": "bun run scripts/probes/explain-symbol-classes-replay.ts",
+		"explain:probe:import-blocker-validity": "bun run scripts/probes/explain-import-blocker-validity.ts",
+		"explain:probe:import-dry-run": "bun run scripts/probes/explain-import-dry-run.ts",
 		"explain:probe:version-floors": "bun run scripts/probes/explain-version-floors.ts",
 		"explain:menus:check": "bun run scripts/gen-explain-menus.ts --check",
 		"explain:value-census": "bun run scripts/explain-value-census.ts",

package/src/api-fanout.ts

@@ -62,6 +62,7 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -213,6 +214,7 @@ export async function apiFanout(
 	// missing endpoint or an invalid `-X` is an outer error regardless of how many
 	// targets the selection resolves to (so an empty selection cannot mask it).
 	validateApiRequestShape(request);
+	assertNoMatchInFanout(request.match);
 	const config = await loadEnvFileDefaults(env);
 	const method = parseApiMethod(request.method);
 	const requestSummary = apiRequestSummaryFromRequest(request, env);

package/src/api.ts

@@ -45,6 +45,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { assertRouterOsMenuPath } from "./core/menu-path.ts";
 import {
 	compileQueryWords,
 	type ParsedQuery,
@@ -160,6 +161,12 @@ export interface ApiRequest {
 	verbose?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** Opt-in host ARP resolution for a MAC target (`none` default, or `arp`). */
 	resolve?: string;
 	stdinIsTty?: boolean;
@@ -937,6 +944,7 @@ export async function resolveApiRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
@@ -2176,6 +2184,10 @@ export function validateApiRequestShape(request: ApiRequest): void {
 				"Pass a path with at least one menu segment, such as `ip/address`.",
 		});
 	}
+	// Before transport choice and regardless of --validate: a `#`/`?` in the
+	// path cut `/print` off the REST URL and a GET read posted to the bare
+	// command, rebooting the router (#586).
+	assertRouterOsMenuPath(normalized.path, { endpoint: request.endpoint });
 }
 
 /**

package/src/btest.ts

@@ -113,6 +113,12 @@ export interface BtestClientRequest {
 	natMode?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	env?: Record<string, string | undefined>;
 	signal?: AbortSignal;
 	/** Live per-interval frame callback (text/csv streaming). */
@@ -264,6 +270,7 @@ export async function btestClient(
 				targetInput: request.targetInput,
 				cdbFile: request.cdbFile,
 				cdbPassword: request.cdbPassword,
+				match: request.match,
 			},
 			env,
 		);

package/src/cli/api.ts

@@ -23,7 +23,10 @@ import {
 	formatCentrsErrorText,
 } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
-import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
+import {
+	assertNoMatchInFanout,
+	assertNoQuickchrOverrideConflict,
+} from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -165,6 +168,12 @@ export const apiCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -179,7 +188,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--validate / --no-validate",
 			description:
-				"Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted).",
+				"Validate structured requests with `/console/inspect`; `/execute` scripts run offline analysis, then RouterOS :parse (default true; `--validate=false` disables both stages).",
 		},
 		{
 			flag: "--format",
@@ -330,6 +339,9 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;
@@ -473,6 +485,11 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				selectionFlags.quickchr[0] ?? "",
 			);
 		}
+		// `--match` + fan-out is refused here too, before `--input -` can block
+		// on stdin; `apiFanout` keeps the same check for library callers (#583).
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			assertNoMatchInFanout(parsed.match);
+		}
 
 		// Resolve `--input` (file / stdin) before handing the body to the orchestrator.
 		if (parsed.inputPath !== undefined) {

package/src/cli/btest.ts

@@ -145,6 +145,12 @@ export const btestCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "(client) Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"(client) Pick one of several CDB records saved for <router> (as `devices show --match`); `btest server` rejects it.",
+		},
 		{
 			flag: "--format",
 			valueName: `<${btestOutputFormats.join("|")}>`,
@@ -302,6 +308,9 @@ function parseClientArgs(args: readonly string[]): ClientCliArgs {
 			case "--cdb-password":
 				request.cdbPassword = expectValue(args, ++i, arg);
 				break;
+			case "--match":
+				request.match = expectValue(args, ++i, arg);
+				break;
 			case "--csv":
 				parsed.format = "csv";
 				break;

package/src/cli/common.ts

@@ -63,6 +63,7 @@ export interface CliCommandMetadata {
 	usage: string;
 	summary: string;
 	options: readonly CliCommandOption[];
+	subcommands?: readonly CliCommandMetadata[];
 }
 
 export function expectValue(