@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/commands/transfer/examples.md

@@ -569,3 +569,49 @@ list succeeds over sftp: `meta.via=sftp`, `meta.target.source.kind=provider`,
 handed over) carried as a provider-sourced `sshKey`. Otherwise the envelope is
 `ok: false` with `error.code=quickchr/unsupported-via` and exit code 1 — a
 typed gate, **never** a password prompt and never a silent fallback to REST.
+
+## CDB record `via=` (#591)
+
+A record's `via=` names a transport, shared with `execute`; transfer maps it
+to a method (`ssh`→`sftp`, `rest-api`→`rest`, `native-api`→`native`). `$CDB`
+holds one record for `127.0.0.1` whose comment is
+`via=ssh port=$SSH_PORT ssh-key=$KEY insecure=true`; the key is imported as
+in the sftp section. C1–C2 are covered by
+`test/integration/transfer-cdb-via.test.ts`; C3–C4 are offline error
+contracts covered by `test/unit/transfer.test.ts`
+(`resolveTransferRequest takes the CDB record's via=`).
+
+### C1. A `via=ssh` record runs execute over ssh and transfer over sftp
+
+```bash
+centrs execute 127.0.0.1 --cdb-file $CDB /system/identity/print --json
+centrs transfer 127.0.0.1 --cdb-file $CDB upload $SRC centrs-591.txt --json
+```
+
+Both `ok: true` with `meta.via="ssh"`, and no `--via` on either. The
+transfer's `meta.settings.via` is `{kind: "comment-kv", key: "record:0:via"}`.
+
+### C2. Download from the same record, with and without `--via sftp`
+
+```bash
+centrs transfer 127.0.0.1 --cdb-file $CDB download centrs-591.txt $TMP/c2-auto.txt --json
+centrs transfer 127.0.0.1 --cdb-file $CDB --via sftp download centrs-591.txt $TMP/c2-sftp.txt --json
+```
+
+Both `ok: true`, `meta.via="ssh"`; each file is byte-identical to `$SRC`.
+`--via ssh` is accepted as the same method as `--via sftp`.
+
+### C3. A record transport that cannot carry files
+
+A record with `via=mac-telnet` (or `romon`, `snmp`, `winbox-terminal`,
+`mndp`, `btest`) and no `--via`: `ok: false`, `error.code=settings/invalid-via`,
+`error.context.source="record:N:via"`, and the remediation suggests
+`--via sftp`, `--via rest` or `--via native`. An explicit `--via` wins over
+the record and the transfer proceeds.
+
+### C4. A `via=rest-api` record does not auto-hop a large upload
+
+A `via=rest-api` record uploading more than 60 KB with no `--via`:
+`ok: false`, `error.code=transport/unsupported-operation`, nothing sent. The
+remediation names `record:N:via` and suggests `--via sftp`, matching a
+pinned `--via rest`.

package/docs/CLI.md

@@ -15,7 +15,7 @@ implemented flags live in each command's `commands/<name>/README.md`.
 | [`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. |
+| [`explain`](#explain) | Analyze RouterOS input offline or add read-only device evidence from one router. |
 | [`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). |
@@ -64,6 +64,7 @@ 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. |
@@ -97,6 +98,7 @@ 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). |
@@ -145,6 +147,7 @@ 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). |
@@ -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. |
@@ -220,18 +225,32 @@ Usage: centrs terminal <router> [flags] | centrs terminal --host <host> [flags]
 
 ## explain
 
-Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics.
+Analyze RouterOS input offline or add read-only device evidence from one router.
 
 ```text
-Usage: centrs explain '<input>' [flags]
+Usage: centrs explain [<router>] '<input>' [flags]
 ```
 
 | Flag | Value | Description |
 | ---- | ----- | ----------- |
+| `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
+| `--host` | &lt;host\|url&gt; | Host or base URL to dial. With no `<router>` it is the target (no CDB lookup); with one it overrides the resolved host. |
+| `--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). |
+| `-p` | `<secret>` | Alias for --password. |
+| `--quickchr` | `<name>` | Resolve one running quickchr VM by name. |
 | `--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. |
+| `--complete` |  | Candidates at the cursor: menus and verbs, argument names, or values. Live evidence — offline emits a tip and enumerates nothing. |
+| `--schema` |  | Describe the path at the cursor: a menu's verbs and submenus, a command's arguments, `print`'s proplist. Live evidence — offline emits a tip and enumerates nothing. |
+| `--cursor` | `<byte>` | UTF-8 byte offset for --complete/--schema. Default: the end of the input. |
+| `--full` |  | Lift --complete/--schema sizing to its safety ceiling (1024 names, 128 expansion probes). |
 | `--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[]` (every byte not claimed by an analyzer is `unclassified`). |
 | `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
@@ -244,13 +263,15 @@ Usage: centrs explain '<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>` | Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used for `init --encrypt`, `encrypt`, and 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`. |
@@ -326,6 +347,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/CONSTITUTION.md

@@ -73,15 +73,20 @@ gate passed keeps `passed`. When something stopped the gate before it gave a
 verdict (a `transport/*` or `auth/*` failure, a device error that is not a
 gate answer, or a refusal before the gate ran), `result` and the
 `syntax`/`semantic` summaries are absent. Each stage the gate did not reach is
-then `skipped` with `reason: "not reached: <error.code>"` (GH#435). On an
-`execute` rejection, `syntax: true` survives only for a name-level refusal (an
-unknown attribute in a structured command). Any other device or offline
-refusal is `syntax: false`, and `semantic` is then absent (`not-applicable` for
-script input), because the name-level check was never asked. `api`'s
-structured requests run no `:parse`, so their `syntax: false` means "not run",
-even on success. That overload is part of the review below. This is an
-interim shape: the validation meta across commands is reviewed again with live
-`explain` (#236).
+then `skipped` with `reason: "not reached: <error.code>"` (GH#435).
+
+The flat `syntax` / `semantic` fields summarize `stages[]`, and each is present
+**only when a stage gave that verdict** (#535). Absent means no stage was
+asked, never "passed" and never "failed". So `--validate=false` carries
+neither. A script has no `semantic` field, because it has no names to check,
+and `api`'s structured requests have no `syntax` field, because they run no
+`:parse`. On a rejection, `syntax: true` with `semantic: false` is a
+name-level refusal (an unknown attribute in a structured command). A `:parse`
+or offline refusal is `syntax: false` with no `semantic`. Every gated success
+reports its `stages[]`, retrieve and transfer included. `explain` is not a
+gate, because it never runs the input: its `meta.validation` is
+`{ enabled: false }` with no `result`, offline and live, and its verdict is
+`data.verdict`.
 
 `--validate=false` disables **both** stages — one flag, one meaning. A bypass
 that covered only the device stage would leave a caller stranded behind a

package/docs/MATRIX.md

@@ -40,7 +40,7 @@ their command-specific evidence contracts.
 | devices  | —             | —             | —             | —             | —             | —             | —             | —                |
 | discover | —             | —             | —             | —             | —             | `CHR-passed`  | —             | —                |
 | check    | `designed`    | `designed`    | `designed`    | `designed`    | `not-started` | `not-started` | `not-started` | `not-started`    |
-| explain  | `designed`    | `designed`    | —             | —             | —             | —             | —             | —                |
+| explain  | `CHR-passed`  | `CHR-passed`  | —             | —             | —             | —             | —             | —                |
 | settings | —             | —             | —             | —             | —             | —             | —             | —                |
 
 ## Status pointers
@@ -101,10 +101,14 @@ and implementation sequencing in the linked issues.
   `winbox-terminal` stay `not-started`. Its per-host fan-out is the machinery the
   IP-scan discovery (#149) will iterate; the L2-default timing evidence (#136) is
   recorded in the README before the cells advance past `designed`.
-- `explain`'s two `designed` protocol cells are the future live probes
-  (`/console/inspect` + `:parse`, #236). The live grammar
-  (`explain <router> '<input>'`) is parsed and refused with
-  `usage/not-implemented`, never degraded to an offline run. Offline analysis
+- `explain`'s two `CHR-passed` protocol cells are the whole live capability
+  (#236). `explain <router> '<input>'` collects read-only `:parse`, highlight
+  and child argument-name evidence (#491), and `--schema`/`--complete` describe
+  paths and complete at a cursor (#492). Live value types (#225) fill
+  `observedType` from visible `:parse` conversions and `schemaType` from
+  argument `syntax`. Examples 7–16, 19, 24, 48 and 52–53 pass on REST and
+  native API in `test/integration/explain-live*.test.ts`, on stable 7.24.5 and
+  long-term 7.23.8. `runtimeAcceptance` stays `not-proven`. Offline analysis
   has its own capability entry below. The generated structure tables
   `src/explain/menus.ts` and `src/explain/catalog.ts` keep analysis offline;
   their ownership and regeneration contracts live in `commands/explain/README.md`.
@@ -182,16 +186,27 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
+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'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
-published offline readings honest (#350, #211), give the result a statement
-tree, then the live probe foundation (#491). Then use those probes to
-ground #351, #358 and #371, and finish live (#492 → #236 closeout). The
+published offline readings honest (#350, #211; complete), give the result a
+statement tree (#497; complete), then the live probe foundation (#491;
+complete). Those probes grounded #351, #358 and #371 (complete), #492
+added the describe/completion facets, and #225 the live value types. The
+closeout of #236 promoted both live cells (complete). The
 plan, and what is deliberately out of this run, is the 2026-10-16 plan
 comment on #90. It is step 3 of the validation track below.
 
-**The CMR track is paused until RouterOS 7.26beta2** (maintainer decision
-2026-10-16). It was first from the 2026-10-12 decision on
+**The CMR track is paused** (maintainer decision 2026-10-16; held for the
+7.26beta caller-policy fix — #527 now carries direct 7.26beta3 evidence that a
+restricted caller is refused, with the first refusing release still
+unbracketed). It was first from the 2026-10-12 decision on
 [#441](https://github.com/tikoci/centrs/issues/441). Done: `execute --cmr`
 (#450), which runs one validated command on CMR clients through their
 controller. The contract is in
@@ -222,11 +237,11 @@ order agreed on [#236](https://github.com/tikoci/centrs/issues/236):
 2. **Done** — front the `execute` / `api` device preflight with the offline
    analyzer (#354). The gate is now two-stage; the contract is in
    [`docs/CONSTITUTION.md` → Validation is the product](CONSTITUTION.md#validation-is-the-product).
-3. **Next** — **live `explain` (#236)**, as stage two of a gate that now exists.
-   Start with [the #90 task index](https://github.com/tikoci/centrs/issues/90),
-   then follow [`commands/explain/README.md`](../commands/explain/README.md) and
-   the live examples in
-   [`commands/explain/examples.md`](../commands/explain/examples.md).
+3. **Done** — **live `explain` (#236)**, as stage two of a gate that now exists.
+   The contract is [`commands/explain/README.md`](../commands/explain/README.md)
+   and the live examples in
+   [`commands/explain/examples.md`](../commands/explain/examples.md);
+   [#90](https://github.com/tikoci/centrs/issues/90) indexes what follows.
 
 The offline baseline stays `verified`: #264 closed the measured token vocabulary
 and #322 closed the final bounded-execution gap, including the public depth-axis
@@ -235,17 +250,17 @@ guard.
 The live pass is the device-backed cross-check on the offline result, not a
 replacement for it. It adds read-only `/console/inspect` and `:parse` evidence,
 the describe/completion facets, and the live `observedType`/`schemaType`
-producers owned with #225. REST and native-api cells advance only when their
+producers (#225). REST and native-api cells advance only when their
 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. #350 (the broad optional `=`,
-schema-dependent and so belonging to step 3), #351 (an unresolvable menu that
-abstains at 2-deep nesting but hard-fails at 3-deep) and #355 (`'` is not a
-RouterOS token — a false ACCEPT the corpus join cannot see) are bounded analyzer
-defects that step 2 now surfaces through the `execute`/`api` gate. #336, #342 and #498 are complete: the
+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
+`commands/explain/README.md`. #336, #342 and #498 are complete: the
 corpus is pinned to schema 5, with one recorded session per release channel
 (long-term 7.23.8, stable 7.24.5, testing 7.25rc2, development 7.26beta1) read
 through `scripts/corpus-db.ts`. The highlight slice is cut from those sessions

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/cmr/caller-policy-not-enforced.md

@@ -22,9 +22,11 @@ re-proves it (CMR15 in `commands/execute/examples.md`):
 | `read,test,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to the controller's own row; `/cmr/device/reboot` rebooted a client |
 
 MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) this is fixed for 7.26beta2: a `read` group will not
-be allowed to do it. That has not been checked on a beta2 build yet. centrs
-still warns on any version, because the warning reads the login's policy, not
-the RouterOS version. On a build that refuses the write, the members fail
+be allowed to do it. #527 now carries direct 7.26beta3 evidence that a
+restricted caller is refused, with the first refusing release still
+unbracketed. centrs still warns on any version, because the warning reads
+the login's policy, not the RouterOS version. On a build that refuses the
+write, the members fail
 instead and the warning only says what the login lacks.
 
 `context` names the login (`username`, `group`), the policies it lacks

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/routeros/permission-denied.md

@@ -0,0 +1,24 @@
+# `routeros/permission-denied`
+
+RouterOS refused the command because the user's group lacks a policy it needs.
+The router answered, and a retry gives the same result. A single refused
+command did not run. A multi-statement script run through `/execute` can be
+partly applied: statements before the refused one already ran.
+
+## Typical RouterOS strings
+
+- `not enough permissions (9)`: the command needs a policy the group does not
+  have, for example a `set` without `write`.
+- `std failure: not allowed (9)`: on REST before RouterOS 7.26beta3, every
+  request fails this way (a plain GET included) when the group has `rest-api`
+  but not `api`. 7.26beta3 fixed it.
+
+Over REST both arrive as HTTP 500 with the string in `detail`; over the native
+API as a `!trap`. Grounded on CHR 7.23.8, 7.25, 7.26beta1 and 7.26beta3.
+
+## Fix
+
+Grant the missing policy to the user's group in `/user/group`: `read` for
+reads, `write` for changes. Before 7.26beta3 a REST user needs both `api` and
+`rest-api`. Avoid the built-in `read` group for a least-privilege user: it also
+carries `reboot`, `sensitive`, `password` and others.

package/docs/errors/transport/edge-auth-failed.md

@@ -0,0 +1,22 @@
+# `transport/edge-auth-failed`
+
+An HTTP layer in front of RouterOS (auth proxy, tunnel edge, WAF) refused the
+request before RouterOS answered it.
+
+## How centrs tells
+
+RouterOS answers every REST auth refusal with a JSON body whose `error` equals
+the HTTP status (`{"error":401,"message":"Unauthorized"}`), adding
+`WWW-Authenticate: Basic` only when no credentials were sent. A 401 or 403 with
+any other body, or a challenge for another scheme (Cloudflare Access sends
+`Bearer`), came from something in front of the router. `context` records the
+challenge scheme, `server`, content type and whether a `cf-ray` header was
+present. A `cf-ray` header alone does not decide it: a tunnel passes RouterOS's
+own 401 through with one.
+
+## Fix
+
+centrs sends only RouterOS Basic credentials, so changing the RouterOS username
+or password will not help. Point `--host` at an address that reaches RouterOS
+directly, or at a local proxy that authenticates to the front layer for you.
+The request never reached RouterOS, so a write was not applied.

package/docs/errors/transport/write-outcome-unknown.md

@@ -9,6 +9,9 @@ whether the write happened.
 
 - A connection closed or reset after an `execute` or `api` write was sent.
 - A REST 5xx or a timeout on a write.
+- A multi-statement `execute` or `api /execute` script refused with
+  `routeros/permission-denied`: statements before the refused one may already
+  have run (#549). A single refused statement did not run and warns nothing.
 
 centrs never retries a write that it has sent, in single-target or fan-out
 mode, because replaying an `add`, a script run or a counter change would apply

package/docs/errors/usage/invalid-cursor.md

@@ -0,0 +1,20 @@
+# `usage/invalid-cursor`
+
+An explain --cursor is not a byte offset inside the input being analyzed.
+
+## Typical trigger
+
+`centrs explain <router> '<input>' --complete --cursor <byte>` with a value that
+is not a whole number, or that is larger than the input's UTF-8 byte length.
+Library callers get the same code for an original-document position
+(`{ line, character }`) that addresses no character in the input.
+
+The check runs before any connection is made, so nothing is sent to the router.
+
+## Fix
+
+- Count the cursor in **UTF-8 bytes**, not characters: `é` is two bytes and
+  `🛰` is four. The end of the input (the default) is the input's byte length.
+- A cursor inside a multi-byte character is accepted and moves back to that
+  character's first byte.
+- Omit `--cursor` to complete or describe at the end of the input.

package/docs/errors/validation/unknown-path.md

@@ -19,3 +19,12 @@ Two sources raise it:
 
 Check the spelling of the segment in `error.context.segment`. `centrs explain
 '<command>'` shows how the rest of the command reads offline.
+
+One path is not a typo: `/system/routerboard` exists only on MikroTik
+hardware, so `retrieve` answers its absence on CHR and x86 systems with a
+targeted remediation instead of the generic one. For the device's license
+ID, read `/system/license` (`system-id` on CHR, `software-id` on x86):
+
+```bash
+centrs retrieve <router> /system/license
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.23",
+	"version": "0.1.9-next.27",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -12,18 +12,18 @@
 	"packageManager": "bun@1.4.2",
 	"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",
 		"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"
@@ -40,7 +40,7 @@
 	"bin": {
 		"centrs": "src/cli.ts"
 	},
-	"description": "All-in-one TypeScript library/CLI/TUI/MCP for interacting with MikroTik RouterOS devices",
+	"description": "All-in-one TypeScript library/CLI/MCP for interacting with MikroTik RouterOS devices (TUI stub)",
 	"engines": {
 		"bun": ">=1.3.11 <2"
 	},
@@ -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);