@tikoci/centrs 0.1.9-next.22 → 0.1.9-next.24

package/commands/transfer/README.md

@@ -96,7 +96,7 @@ size-aware. Grounding: [Files](https://help.mikrotik.com/docs/spaces/ROS/pages/2
 | `rest` / `native` | rest-api / native-api | small via `/file/get … contents` (**≤ 60 KB**); **large via chunked `/file/read offset chunk-size≤32768`** | **`/file/set contents=` ≤ 60 KB only** — no chunked write |
 | `sftp` (default secure) | ssh | any size | any size |
 | `scp` | ssh | any size | any size |
-| `fetch` *(deferred)* | rest-api/native-api + inbound HTTP | router PUTs to centrs (`upload=yes http-method=put src-path=…`) | router GETs from centrs (`url=http://centrs/… dst-path=…`) |
+| `fetch` *(deferred, upload-only)* | rest-api/native-api + inbound HTTP | chunked `/file/read` (router PUT fails: `only [s]ftp modes support upload`, #548) | router GETs from centrs (`url=http://centrs/… dst-path=…`) |
 | `ftp` *(gated)* | ftp | any size | any size |
 
 Auto-selection (no `--via`):
@@ -302,6 +302,10 @@ gate as in `retrieve` / `execute`; RouterOS's own menu errors (missing remote
 file, permission denied) map to `routeros/*`, and SFTP/SCP/fetch errors map to
 `transport/*` and `auth/*`.
 
+`meta.validation` reports that existence probe as one `device` stage. `list`
+runs no probe, so it is not a gate: its `meta.validation` is
+`{ enabled: false }`, on success and on failure (#535).
+
 A failure **after** target resolution keeps what resolution found: the error
 envelope carries the resolved `meta.target` (host, port, identity, sources),
 `meta.via`, the setting sources in `meta.settings`, and `meta.operation`
@@ -371,9 +375,9 @@ done rule. The first coded pass targets `rest`/`native` (no SSH dependency);
   (random URL token, bound to the interface facing the router) and drives the
   router with `/tool/fetch` over `rest`/`native`. **upload**: serve the local
   file, `fetch url=http://<advertise>/<token> dst-path=<remote>` → router GETs.
-  **download**: `fetch upload=yes http-method=put url=http://<advertise>/<token>
-  src-path=<remote>` → router PUTs to centrs (`http-method` any since 7.21;
-  binary REST serialization fixed 7.17). Open questions: advertise-host
+  **download** stays on chunked `/file/read`: router PUTs fail with `only
+  [s]ftp modes support upload` (#548), and HTTP `http-data` caps at 60000
+  bytes, so the PUT half cannot carry files. Open questions: advertise-host
   auto-detection behind NAT, HTTP-vs-HTTPS + `check-certificate`, and whether to
   add fetch's `user`/`password` on top of the URL token.
 - **ssh** — `sftp` is **built** (`src/protocols/sftp.ts`, host OpenSSH `sftp`

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). |
@@ -220,18 +220,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. |

package/docs/CONSTITUTION.md

@@ -58,6 +58,10 @@ is unsafe the offline stage is what keeps the gate from degrading to nothing. A
 clean offline pass is **necessary, never sufficient** — `explain` publishes
 `runtimeAcceptance: "not-proven"` for exactly this reason. An offline `warn` is
 an ABSTENTION and passes through to the device stage; only a `fail` rejects.
+The one exception is `discarded-close`: a stray top-level `}` or `]` that the
+device accepts and then silently stops reading at (#504). It is a warning,
+because nothing is rejected, and the gate refuses it by code
+(`src/offline-gate.ts`), because the device would run a different script.
 
 `meta.validation.stages[]` reports what each stage concluded, including a stage
 that was skipped and why. A reader must always be able to tell "the device
@@ -69,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,17 +186,35 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**First: the CMR track** (maintainer decision 2026-10-12 on
-[#441](https://github.com/tikoci/centrs/issues/441)). Done: `execute --cmr`
+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.
+
+**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; 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** (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
 [`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr),
 with examples CMR0–CMR15. Also done: the fleet blast-radius gate for
 controller fleet commands run with plain `execute` or `api` (#453), with
 examples CMR16–CMR18 and api CMR1. The feature map of CMR against centrs is
-on #441 (2026-10-13). Next is the read-only slice of #449 (a `devices` view
-of members and a default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
-Live `explain` resumes after this.
+on #441 (2026-10-13). When it resumes, next is the read-only slice of #449 (a
+`devices` view of members and a default controller). Deferred: CDB linkage
+(#449) and `retrieve --cmr` (#441).
 
 **The native-api / NDJSON line** (maintainer decision on
 [#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
@@ -213,11 +235,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
@@ -226,20 +248,23 @@ 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 retains the fail-closed unlisted-path decision; #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 and #342 are complete: the
-corpus is repinned to three *complete* builds (long-term 7.23.5, stable 7.24.2,
-development 7.25beta3), and the operator sweep and highlight slice are re-swept
-onto those same builds — plus 7.21.5 retained as an age anchor — so the operator
-axis and the token partition are scored on the same firmware. The #335
+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
+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
+and gated in CI, and the operator sweep is re-run on the same builds — plus
+7.21.5 retained as an age anchor — so the operator axis and the token partition
+are scored on the same firmware. The #335
 source refresh pins both architectures of those versions beside the 7.10.2 /
 7.16 history anchors and accepts the current CLI-Reference drift. Issue #223 is
 a separate MCP response migration. If live evidence finds a wrong offline

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/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.22",
+	"version": "0.1.9-next.24",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -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"
 	},
@@ -103,11 +103,14 @@
 		"explain:catalog": "bun run scripts/gen-explain-catalog.ts",
 		"explain:catalog:check": "bun run scripts/gen-explain-catalog.ts --check",
 		"explain:corpus-census": "bun run scripts/explain-corpus-census.ts",
+		"explain:conformance": "bun run scripts/explain-conformance.ts",
+		"explain:conformance:check": "bun run scripts/explain-conformance.ts --check",
 		"explain:highlight-agreement": "bun run scripts/explain-highlight-agreement.ts",
 		"explain:highlight-agreement:check": "bun run scripts/explain-highlight-agreement.ts --check",
 		"explain:highlight-agreement:readme": "bun run scripts/explain-highlight-agreement.ts --readme",
 		"explain:highlight-agreement:readme:check": "bun run scripts/explain-highlight-agreement.ts --readme --check",
 		"explain:highlight-slice": "bun run scripts/explain-highlight-slice.ts",
+		"explain:highlight-slice:check": "bun run scripts/explain-highlight-slice.ts --check",
 		"explain:menus": "bun run scripts/gen-explain-menus.ts",
 		"explain:operator-census": "bun run scripts/explain-operator-census.ts",
 		"explain:operator-census:check": "bun run scripts/explain-operator-census.ts --check",

package/src/api.ts

@@ -62,6 +62,7 @@ import {
 	promptForWriteConfirmation,
 	validateRouterOsScript,
 } from "./execute.ts";
+import { countExecutableStatements } from "./explain/segment.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -541,7 +542,7 @@ async function* streamResolvedApi(
 			trace.validation = validation;
 			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
 		} else {
-			validation = disabledValidationMeta();
+			validation = disabledApiValidationMeta(resolved);
 		}
 	} catch (error) {
 		await backend.close();
@@ -824,16 +825,6 @@ function adapterForResolved(resolved: ResolvedApiRequest): ProtocolAdapter {
 	});
 }
 
-function disabledValidationMeta(): EnvelopeValidationMeta {
-	return {
-		enabled: false,
-		source: "disabled",
-		result: "skipped",
-		syntax: false,
-		semantic: false,
-	};
-}
-
 export async function resolveApiRequest(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
@@ -1347,7 +1338,8 @@ interface ApiValidationResult {
  * validator is `/console/inspect`, never `:put [:parse]`. Path existence and
  * add/set attribute validity both come from `request=child` — command-level
  * `request=completion` is unsafe on RouterOS 7.12.2 (`core/inspect.ts`). A
- * `/execute` script is a CLI string → `semantic: not-applicable`.
+ * `/execute` script is a CLI string, so it has no `semantic` summary; a
+ * structured request runs no `:parse`, so it has no `syntax` summary (#535).
  */
 async function validateApiRequest(
 	resolved: ResolvedApiRequest,
@@ -1383,8 +1375,7 @@ async function validateApiRequest(
 						? "not-applicable"
 						: API_SCRIPT_DEVICE_STAGE_SOURCE,
 				result: "passed",
-				syntax: script !== undefined,
-				semantic: "not-applicable",
+				...(script !== undefined ? { syntax: true } : {}),
 				stages: [
 					{
 						stage: "offline",
@@ -1468,13 +1459,7 @@ async function validateApiRequest(
 			}
 		}
 		return {
-			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
-			},
+			validation: structuredValidationPassed(resolved),
 			tips,
 			queryMenu: isCommand ? `/${parent.join("/")}` : resolved.path,
 		};
@@ -1513,11 +1498,7 @@ async function validateApiRequest(
 		}
 		return {
 			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
+				...structuredValidationPassed(resolved),
 				availableAttributes: available,
 			},
 			tips,
@@ -1526,13 +1507,7 @@ async function validateApiRequest(
 	}
 
 	return {
-		validation: {
-			enabled: true,
-			source: "/console/inspect request=child",
-			result: "passed",
-			syntax: false,
-			semantic: true,
-		},
+		validation: structuredValidationPassed(resolved),
 		tips,
 		queryMenu: resolved.path,
 	};
@@ -1857,6 +1832,12 @@ export function buildApiErrorEnvelopeFromResolved(
 	trace?: ValidationTrace,
 ): ApiErrorEnvelope {
 	const centrsError = asApiError(error);
+	// A structured request is one operation; only a `/execute` script can
+	// carry several statements into one dispatch (#549), at the top level or
+	// inside an executed control scope.
+	const script = resolved.scriptMode ? scriptOf(resolved) : undefined;
+	const multiStatement =
+		script !== undefined && countExecutableStatements(script) > 1;
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
@@ -1866,6 +1847,7 @@ export function buildApiErrorEnvelopeFromResolved(
 				isApiMutating(resolved.method, resolved.path),
 				centrsError,
 				trace,
+				multiStatement,
 			),
 		],
 		tips: [],
@@ -1877,6 +1859,22 @@ export function buildApiErrorEnvelopeFromResolved(
 	};
 }
 
+/** A structured request the device stage passed; stage 1 does not apply to it. */
+function structuredValidationPassed(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationMeta {
+	return {
+		enabled: true,
+		source: API_DEVICE_STAGE_SOURCE,
+		result: "passed",
+		semantic: true,
+		stages: [
+			offlineApiStage(resolved),
+			{ stage: "device", source: API_DEVICE_STAGE_SOURCE, result: "passed" },
+		],
+	};
+}
+
 /**
  * `meta.validation` for an api error envelope. A stage-1 rejection opened no
  * connection, so the meta must not report `/console/inspect` as the validator
@@ -1896,7 +1894,6 @@ function failedApiValidationMeta(
 			source: OFFLINE_GATE_SOURCE,
 			result: "failed",
 			syntax: false,
-			semantic: "not-applicable",
 			stages: [
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
@@ -1911,14 +1908,14 @@ function failedApiValidationMeta(
 	// Only a `validation/*` error identifies the device stage as the rejecter.
 	// Everything downstream of a passed gate — a RouterOS fault on the request,
 	// a transport drop — is served by `trace.validation` before this function is
-	// ever reached.
+	// ever reached. A script is refused by `:parse` (syntax); a structured
+	// request by `/console/inspect` (names) (#535).
 	if (error.code.startsWith("validation/")) {
 		return {
 			enabled: true,
 			source: apiDeviceStageSource(resolved),
 			result: "failed",
-			syntax: false,
-			semantic: resolved.scriptMode ? "not-applicable" : false,
+			...(resolved.scriptMode ? { syntax: false } : { semantic: false }),
 			stages: [offlineApiStage(resolved, trace), deviceStageFailed(resolved)],
 		};
 	}
@@ -2012,8 +2009,6 @@ function disabledApiValidationMeta(
 		enabled: false,
 		source: "disabled",
 		result: "skipped",
-		syntax: false,
-		semantic: resolved.scriptMode ? "not-applicable" : false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
 			{