@tikoci/centrs 0.1.4 → 0.1.6

package/commands/explain/examples.md

@@ -4,9 +4,10 @@ Each numbered example is an executable spec. Once `explain` is implemented,
 offline examples run under `test/unit/explain.test.ts` and live examples under
 `test/integration/explain.test.ts` (rest-api) and
 `test/integration/native-api-explain.test.ts` (native-api) against a CHR booted by
-`@tikoci/quickchr` — one assertion per example (example N ↔ assertion N).
-The offline examples are **green** as of #202c-2, including 1, 2, 6 and 23's
-`transport`/`--curl` assertions. The live examples are still the **target**:
+`@tikoci/quickchr` — one named test per example (example N ↔ named test N); a
+named test may carry several assertions. The offline examples are **green**
+as of #202c-2, including 1, 2, 6 and 23's `transport`/`--curl` assertions.
+The live examples are still the **target**:
 those cells are `designed`, and flag and field names track the ratified surface
 in `README.md`.
 
@@ -604,3 +605,98 @@ No members are emitted for a bare comma run, because whether it splits at all is
 the schema's answer. The `(1,2)` spelling is different — its delimiters prove
 the array — so `servers=(1.1.1.1,8.8.8.8)` yields the array plus two `["ip"]`
 members.
+
+### 29. A second command-shaped run is a missing separator, not an operand
+
+```bash
+centrs explain '/ip/address add interface=ether1 /ip/route add gateway=192.168.88.1' --json
+```
+
+`data.verdict` is `fail` with one
+`explain/canonicalizer/missing-statement-separator` **error** spanning the whole
+second run (`[33,46)` — `/ip/route add`), whose message says to insert `;` or a
+newline before it.
+
+The source stays **one** statement: `resolution` is `"resolved"` on
+`/ip/address add`, because that head really was read and the device's own
+`highlight` agrees. What is withdrawn is the reading the run contradicts —
+`command.args` is absent, `arguments.read` is `false`, and `transport.
+classification` is `"unknown"`, so no `centrs execute` line is offered for bytes
+the same result rejects. `data.values.occurrences` is cut at the same byte: it
+keeps `interface` and drops `gateway`, which the device reads as the value of
+`/ip/address/add`'s own `address=` rather than as an attribute name.
+
+The rule is a known **menu path** followed by a console **verb**, never "a `/`
+after the verb": `/file remove /flash/skins/foo.html` is legal and lowers to
+`numbers=/flash/skins/foo.html`. It abstains on a menu path with no verb after
+it and on an operand no structure table lists, both of which draw the device's
+generic `bad parameter` and need per-menu positional schema to decide.
+
+### 29b. The same commands, separated, read as two
+
+```bash
+centrs explain '/ip/address add interface=ether1; /ip/route add gateway=192.168.88.1' --json
+```
+
+`data.verdict` is `pass` with no diagnostics, two statements, and each keeps its
+own `command.args`. The newline spelling is identical.
+
+### 30. A known menu path with arguments does not get an invented verb
+
+```bash
+centrs explain '/ip/firewall/address-list name=ytkids timeout=1h' --json
+```
+
+One statement with `resolution: "ambiguous"` and no `command` at all, plus an
+`explain/canonicalizer/ambiguous-statement` **warning** over the whole
+statement naming both premises: `/ip/firewall/address-list` is a known menu,
+and `address-list` is not a console verb. `data.verdict` is `warn`, so the
+default `--fail-on error` still exits `0` — offline is saying it cannot read
+this, not that RouterOS rejects it.
+
+It used to answer `resolution: "resolved"`, `command.path: "/ip/firewall"`,
+`command.verb: "address-list"` — a verb assembled out of a path segment. The
+spaced spelling `/ip firewall address-list name=x` was worse, promoting
+`firewall` and reporting the menu as `/ip`. Adding the verb resolves it again
+(`/ip/firewall/address-list add name=ytkids` is `resolved`/`command`), and the
+bare path without arguments is still `resolved`/`menu` (example 18b's rule).
+
+### 31. A command substitution inside a string keeps its own tokens
+
+```bash
+centrs explain ':put "$[/ip address print as-value]"' --tokens --json
+```
+
+`data.structure.subcommands[0]` resolves `/ip/address` verb `print` — it always
+did — and `data.tokens[]` now agrees with it: `dir` over `/ip` and `address`,
+`cmd` over `print`, with the quote, the `$[`, the separators and the trailing
+`as-value]"` left as `string`. The whole quoted run used to be one opaque
+`string` token, so an editor rendering the partition painted a command centrs
+had already read as flat text.
+
+Byte coverage does not change — the partition is still total and gapless — only
+which fill owns those bytes. The `$` sigil and the `[` / `]` delimiters stay
+`string`: #264 B5 kept them there because `structure.subcommands` already
+publishes the resolution and its `innerSpan` locates the brackets around it.
+
+### 32. A block binder the envelope cannot publish is still located
+
+```bash
+centrs explain ':if ($x = 1) do={ :put "hi" }' --tokens --json
+```
+
+`data.structure.statements[0].arguments` is `{ read: false, why: "a
+substitution or expression value" }` — the strict reading is all-or-nothing and
+a runnable request cannot be rendered from a half-read argument list, so the
+envelope publishes no `ExplainArgumentToken` here at all. `data.tokens[]` still
+locates the argument: `arg` over `do`, `arg-sep` over its `=`, `brace` over the
+`{`.
+
+That is why #264 B5 gave the `=` its own class. A consumer holding only the
+envelope would otherwise have to derive the name/value boundary from
+`arguments[].valueSpan.start - 1`, and for 30.8% of the corpus's `=` runs —
+`do=` first among them — there is no published `valueSpan` to derive it from.
+
+The same command also shows the two `=` bytes staying apart: the one in
+`($x = 1)` is a comparison and comes back `operator`, decided by fill order
+rather than by a scan for the byte.

package/commands/mcp/README.md

@@ -80,8 +80,8 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
   rejected. RouterOS 7.23 no longer reproduces that exact `blackhole=yes` case,
   but the lesson stands: schema-presence is not parser-acceptance.
   `:put [:parse "<cmd>"]` runs the real parser, and centrs runs **both** `:parse`
-  and `/console/inspect`, so the MCP exposes validation as a first-class
-  **dry-run** tool (`centrs_validate`) that never mutates.
+  and `/console/inspect request=child`, so the MCP exposes validation as a
+  first-class **dry-run** tool (`centrs_validate`) that never mutates.
 - **Stateful intents need device-validate-before-apply.** Gold using
   `interface=ether2` fails on a CHR exposing only `ether1`. Pair `execute` with
   cheap readback (`retrieve`).
@@ -104,7 +104,7 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 | Tool | Core mapping | Reads/Writes | Target source |
 | ---- | ------------ | ------------ | ------------- |
 | `centrs_explain` | `canonicalizeExecuteCommand` | offline, none | none (string only) |
-| `centrs_validate` | execute validation only (`:parse` + `/console/inspect`), **no run** | read-only | CDB |
+| `centrs_validate` | execute validation only, **no run**: offline analysis, then the device stage — `:put [:parse ...]` alone over ssh/mac-telnet, `:parse` + `/console/inspect` for structured REST/native | read-only | CDB |
 | `centrs_retrieve` | `retrieve` / `retrieveGroup` | read-only | CDB |
 | `centrs_execute` | `execute` | read or write | CDB |
 | `centrs_devices` | `devices` (`list`/`show`/`groups`/`add`/`edit`/`set`/`remove`) | CDB read/write | CDB file |
@@ -118,7 +118,10 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 - `centrs_validate` is the headline distilled from the bench: a dry-run that runs
   the real parser plus schema inspection against a registered target and returns
   the validation envelope **without executing**. Use it to reject schema-invalid
-  commands before any write.
+  commands before any write. It shares `execute`'s two-stage gate (constitution:
+  validation is the product, GH#354), so a syntax fault comes back from the
+  offline stage with a byte span and without contacting the target at all, and
+  `meta.validation.stages[]` says which stage spoke.
 - `centrs_retrieve` mirrors `retrieve`, including attribute projection,
   `listAttributes`, and `group` fanout.
 - `centrs_execute` mirrors `execute`. Read-shaped commands run subject only to

package/commands/mcp/examples.md

@@ -65,8 +65,8 @@ matters for the bench gold-bug in example 4.
 ```
 
 Envelope: `ok: false`, `error.code = "validation/unknown-attribute"` — the
-`/console/inspect` semantic gate rejects the unknown attribute and **no route is
-created**. This proves the validate tool fails closed on bad input.
+`/console/inspect request=child` semantic gate rejects the unknown attribute and
+**no route is created**. This proves the validate tool fails closed on bad input.
 
 > Bench note: the bench's original gold-bug command
 > `/ip/route/add dst-address=10.99.0.0/24 blackhole=yes` (where `/console/inspect`

package/commands/terminal/examples.md

@@ -42,6 +42,9 @@ printf '/system/identity/print\n' | centrs terminal $MAC --via mac-telnet --host
 ```
 
 stdout contains the device identity (cross-checked against REST). Exit code `0`.
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
 
 ### T2. `--via rest-api` has no terminal capability
 
@@ -99,7 +102,10 @@ analog of T4** (a piped subprocess stdin cannot be a TTY), not in CI.
 printf '/system/identity/print\n/quit\n' | centrs terminal 127.0.0.1 --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure
 ```
 
-stdout contains the device identity (cross-checked against REST). centrs returns
+stdout contains the device identity (cross-checked against REST).
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout. centrs returns
 ssh's exit code (a no-PTY console closed by EOF can exit non-zero — that is the
 device/ssh's result, not a centrs failure; a clean `/quit` from a real TTY exits
 `0`).

package/docs/CLI.md

@@ -114,7 +114,7 @@ Usage: centrs api <router> <endpoint> [flags]
 | `--query / --filter` | `<expr>` | RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name. |
 | `--raw-query` | `<word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions. |
 | `--attribute / --proplist` | `<a,b>` | Property projection → `.proplist`. |
-| `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does not imply `--yes`. |
+| `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`. |
 | `--yes` |  | Confirm a mutating (non-read) request in non-interactive runs. |
 | `--stream / --listen` |  | Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope. |
 | `--count` | `<n>` | Stop a `--stream` after N change frames. |
@@ -223,7 +223,7 @@ Usage: centrs explain '<input>' [flags]
 | `--complete` |  | Continuation candidates at the cursor. Live evidence — offline emits a tip and enumerates nothing. |
 | `--schema` |  | Path enumeration (verbs, args, types, enums). Live evidence — offline emits a tip and enumerates nothing. |
 | `--curl` |  | Render a ready-to-edit REST curl for statements covered by a runtime-tested mapping rule. |
-| `--tokens` |  | Emit the total, gapless token partition behind `data.tokens[]` (provisional `class` until #264 B5: every byte not claimed by an analyzer is `unclassified`). |
+| `--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. |
 | `--json` |  | Shortcut for `--format json`. |
 | `--yaml` |  | Shortcut for `--format yaml`. |

package/docs/CONSTITUTION.md

@@ -9,15 +9,22 @@ This file is short on purpose. Resist the urge to grow it.
 
 ## What centrs is
 
-A typed library, with CLI/MCP/TUI/proxy frontends, that reaches RouterOS over
-multiple protocols and gives the caller **validated** access plus structured,
-actionable diagnostics. The TypeScript API is the root surface; everything else
-is an adapter over it.
+A typed library for RouterOS analysis and **validated** device access, with
+CLI/MCP/TUI/proxy frontends and structured, actionable diagnostics. The
+TypeScript API is the root surface; everything else is an adapter over it.
+The initial consumers are other TIKOCI tools and developers building integrations.
 
 The product is *not* "REST/SSH/native API wrappers." The product is
 **validation + structured envelopes + identity resolution** on top of those
 transports. Without those, this is a worse `curl`.
 
+`explain` is shared analysis across transports and a useful offline capability
+in its own right. It exposes source structure, facts, uncertainty, and evidence
+without executing the input. Those facts can support future diagnostics in
+other commands' envelopes; that integration is not implemented by declaring
+this boundary. Analysis findings do not grant execution permission or replace
+the runners' validation gates.
+
 centrs also speaks a small set of MikroTik **peer protocols** that are *not*
 RouterOS-command transports — currently the **bandwidth test** (`btest`), which
 mirrors `/tool/bandwidth-test` and `/tool/bandwidth-server`. This is a
@@ -29,8 +36,40 @@ friendly errors, but the "validate a RouterOS-shaped command" gate below does
 
 ## Validation is the product
 
-Every RouterOS-shaped call goes through canonicalize → validate → run →
-re-validate-server-side. Validation is not optional polish.
+Every RouterOS-shaped operation sent to a device goes through canonicalize →
+validate → run → re-validate-server-side. Analysis-only `explain` never runs
+the analyzed input; offline analysis opens no connection. Validation on the
+runners is not optional polish.
+
+The `validate` step itself has **two stages, in this order** (GH#354):
+
+1. **Offline** — the same corpus-gated analyzer `explain` publishes, run over
+   the input with no connection (`src/offline-gate.ts`). A rejection is a byte
+   span and no round trip; the protocol adapter is never dialed. This stage runs
+   on every transport, for `execute` and for `api`'s `/execute` script mode.
+2. **Device** — the RouterOS-side probe below: `:put [:parse "…"]` and/or
+   `/console/inspect request=child`, depending on the command shape and the
+   transport.
+
+The stages are not interchangeable and neither subsumes the other. Offline has
+no per-menu schema (decision 3 — no offline schema snapshot), so it cannot see
+an unknown attribute; the device probe is version-fragile (GH#343), so where it
+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.
+
+`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
+accepted it" from "the device was never asked".
+
+`--validate=false` disables **both** stages — one flag, one meaning. A bypass
+that covered only the device stage would leave a caller stranded behind a
+stage-1 defect with no escape at all, and the analyzer is demonstrably wrong in
+both directions today (GH#355 is a live false accept, GH#351 a live false
+reject). That is a reason for the flag to reach both stages, not a license to
+use it: the rule below still holds — a wrong rejection is fixed in the
+validator, with CHR evidence.
 
 - `retrieve` and other read-shaped calls validate against
   `/console/inspect request=syntax path=...,print` (path joined by commas) and
@@ -397,22 +436,38 @@ default), so key auth is the normal sftp path.
 
 ## Done definition
 
-A feature is done when its **CHR integration test is green** against a real
-RouterOS CHR booted by `@tikoci/quickchr`. Not when code exists. Not when unit
-tests pass. Not when the spec says so. This is the **normative** done
-definition; `AGENTS.md` and
+Done requires executable evidence for the capability being claimed. Device
+operations and live analysis require **green CHR integration tests** against a
+real RouterOS CHR booted by `@tikoci/quickchr`, via `bun run test:integration`.
+Code existing or unit tests passing cannot establish live behavior. This is
+the **normative** done definition; `AGENTS.md` and
 `.github/instructions/done-definition.instructions.md` point here (the latter
 carries the Copilot-workflow procedure for satisfying it).
 
-`docs/MATRIX.md` is the single source of truth for *what* is done and defines the
-cell states (`not-started` / `designed` / `coded` / `CHR-passed`). A cell
-advances only with the matching evidence in the same change, and the commit that
-advances it must include the test name and CHR version.
+Offline analysis is `verified` when its applicable command examples and
+contract checks pass without a router, its RouterOS semantic claims have
+committed CHR-grounded evidence, and the command's baseline acceptance criteria
+are satisfied. New or changed RouterOS semantics still require live grounding
+with accepted and rejected controls plus a reproducible capture/replay path;
+offline tests do not establish new device facts. Changes to shared execution
+or transport behavior still require `bun run test:integration`. The offline
+call itself never needs a router merely to satisfy a workflow label.
+
+`docs/MATRIX.md` owns capability status and the selected work track. A
+capability's acceptance criteria — like `explain`'s Offline baseline
+acceptance — live in its `commands/<name>/README.md`; GitHub issues own the
+tasks and dependencies that satisfy those criteria, not the criteria
+themselves. Umbrella issues index that work rather than replacing capability
+status. Status advances only with matching evidence in the same change.
+Record test names, fixture provenance, and CHR versions where applicable.
+Offline verification never advances a live protocol cell to `CHR-passed`.
 
 ## Boundaries
 
 centrs does:
 
+- Analyze RouterOS source independently of a connection, preserving ordered
+  structure, source locations, evidence, and ambiguous/unknown readings.
 - Resolve devices/groups from explicit input, env, CDB, MNDP cache.
 - Choose protocols per the table above and configure them.
 - Validate before execute; re-validate server-side immediately before run.
@@ -425,7 +480,9 @@ centrs does:
 
 centrs does not:
 
-- Replace RouterOS syntax with high-level abstractions.
+- Replace RouterOS syntax with high-level configuration helpers. Normalized
+  representations that preserve its semantics are in scope; reconstructing
+  final device state or predicting network behavior is not an offline parse claim.
 - Treat passive discovery (MNDP) as authoritative inventory.
 - Run write-shaped operations without an explicit target and validation policy.
 - Make generated output the hand-edited source of truth.

package/docs/MATRIX.md

@@ -1,11 +1,15 @@
 # Matrix
 
-The product is a 2D grid of commands × protocols. This file is the **only**
-source of truth for what is done. No alpha gates, no milestones, no roadmap
-prose.
+This file owns **capability status and the selected work track**. The
+command × protocol grid covers live operations; offline analysis, frontends,
+and peer measurement have separate entries below. A capability's acceptance
+criteria live in its `commands/<name>/README.md`; GitHub issues own the tasks
+and dependencies that satisfy them.
 
-Pick the highest-priority cell that is not `CHR-passed`. That is the next
-work. See `docs/CONSTITUTION.md` for the cell-state definitions.
+Start with [Current priority](#current-priority), then the command's README,
+examples, and linked issue. Verification follows `docs/CONSTITUTION.md` →
+Done definition. A completed implementation slice is not proof that the whole
+capability is complete.
 
 ## Cell states
 
@@ -15,10 +19,15 @@ work. See `docs/CONSTITUTION.md` for the cell-state definitions.
 | `not-started` | No code and no design                                           |
 | `designed`     | `commands/<name>/README.md` describes intent and flags          |
 | `coded`        | Implementation exists in `src/`                                 |
+| `verified`     | Offline capability meets its command README's baseline acceptance criteria in full (examples, contract checks, measured/consumer gates, and CHR-grounded evidence). |
 | `CHR-passed`   | Every example in `commands/<name>/examples.md` is green on CHR  |
 
 A cell advances only with the matching evidence in the same change.
 
+`verified` applies to offline capabilities; it does not advance a live protocol
+cell. Existing `CHR-passed` fixture-backed `devices`/`settings` entries retain
+their command-specific evidence contracts.
+
 ## Grid
 
 | Command  | rest-api      | native-api    | ssh           | mac-telnet    | snmp          | mndp          | romon         | winbox-terminal |
@@ -37,8 +46,8 @@ A cell advances only with the matching evidence in the same change.
 ## Status pointers
 
 Detailed command contracts live in `commands/<name>/README.md`; example evidence
-lives in `commands/<name>/examples.md` and the named integration tests. Keep this
-section short enough that the grid remains the status surface.
+lives in `commands/<name>/examples.md` and the named tests. Keep task history
+and implementation sequencing in the linked issues.
 
 - `devices` is transport-less, so its row stays `—`; command state is
   `CHR-passed` by fixture-backed integration tests in `test/integration/devices.test.ts`.
@@ -60,42 +69,13 @@ section short enough that the grid remains the status surface.
   `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` is `designed` (`commands/explain/README.md`): the explain →
-  validate → run knowledge tier — canonical structure, LSP-like
-  spans/diagnostics, transport classification (api-able vs execute, `curl`
-  rendering), and live schema/completion facts. Its offline mode is the
-  canonicalizer only and opens no protocol connection (evidence is
-  unit/fixture tests); the
-  live probes (`/console/inspect` + `:parse`) ride rest-api/native-api, so
-  those two cells are `designed`. The surface was decided in the 2026-07-19
-  design round (#90) and the spec is **ratified** on the phase-0 grounding
-  lab (#185, ratification PR #187). Phase 0.5 has since promoted the ratified
-  lab logic into the library — `src/explain/{segment,blocks,coordinates,defects,
-  pathresolve,verbsplit,write,symbols,menus,verbs,args,values,brace-slots}.ts`
-  with frozen fixtures under `test/fixtures/explain/` — and phase 1 has composed
-  them into one analysis and envelope in `src/explain.ts` (`explainCommand` /
-  `explainEnvelope`, #202a). **`centrs explain '<input>'` is a real command as
-  of #202b** (`src/cli/explain.ts`), and #202c adds statement argument reading,
-  the closed Q8 transport classifier, equivalent centrs invocations, and
-  opt-in `--curl`. All offline examples, including 1, 2, 6 and 23, run green in
-  `test/unit/explain.test.ts`. The row nonetheless stays `designed`: offline
-  mode occupies no protocol cell, and the two `designed` cells are the live
-  `/console/inspect` + `:parse` probes, which are phase 2. The live grammar
+- `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` rather than degraded to an offline run. Cells advance
-  only when the live probes land and their examples run green per the done rule.
-  `src/explain/menus.ts` and `src/explain/catalog.ts` are the **generated**
-  files in that set — the RouterOS menu-vs-command table (#207, from pinned
-  restraml typed trees) and the path catalog (#228, those trees unioned with
-  MikroTik's published CLI Reference, carrying kind, per-entry provenance and
-  the published applicability gate). Regenerate with `bun run explain:menus` /
-  `bun run explain:catalog`; both are drift-checked in QA. They keep the offline
-  analyzer offline; do not hand-edit them. The catalog's **command axis is read**
-  by `pathresolve.ts`, `verbsplit.ts` and `write.ts` (#228 step 2); #235 also
-  reads its menu/settings kind, unioned with `menus.ts` behind
-  `src/explain/is-known-menu.ts`, for both a context-applied relative bare path
-  and an absolute one. Both changes are inside the offline canonicalizer, so
-  this grid is unchanged by them.
+  `usage/not-implemented`, never degraded to an offline run. 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`.
 - `transfer / ssh` means the SFTP-backed transfer method. Deferred file-transfer
   methods such as `scp`, `fetch`, and `ftp` are tracked in
   `commands/transfer/README.md`; `fetch` is not a grid column.
@@ -108,9 +88,20 @@ section short enough that the grid remains the status surface.
 - Transport wire-format and delivery caveats belong in `src/protocols/*.ts`
   module headers. Do not expand this file with per-packet or per-router findings.
 
-Beyond the grid: post-`CHR-passed` hardening, ergonomics, and research work is
-tracked in GitHub issues (`dry-july` and successors). Those issues may point back
-to this matrix for current status, but they are not additional cell states.
+### Offline analysis
+
+This capability opens no protocol connection. It is usable independently and
+provides shared analysis for future integrations across the command grid.
+
+| Capability | State | Contract and evidence | Work |
+| ---------- | ----- | --------------------- | ---- |
+| explain / offline baseline | `verified` | `commands/explain/README.md` → Offline baseline acceptance; offline examples in `test/unit/explain.test.ts`, focused `test/unit/explain-*` suites, and CHR captures under `test/fixtures/explain/`. The token partition is scored against device `highlight` by `test/unit/explain-highlight-agreement.test.ts` and `test/fixtures/explain/highlight-agreement.json`. The public entry is `@tikoci/centrs/explain`; its dependency boundary and executed browser-consumer proof are gated by `test/unit/explain-browser-entry.test.ts` (`bun run explain:browser-consumer`). #322's fixed-size 16× depth guard and deterministic structural-work guards close the bounded-execution criterion. | #90 indexes correctness, token agreement (#264/#263), consumer verification, and bounded execution (#322). |
+
+The CLI/library expose structure, diagnostics, token partitions, symbols, and
+flow-sensitive value facts. `verified` records the offline acceptance evidence;
+it is not a parser-coverage score and does not advance either live protocol cell.
+Live probes (#236), MCP response alignment (#223), and future configuration
+policies are distinct work, not prerequisites for using offline analysis.
 
 ### Transport-base readiness
 
@@ -126,8 +117,8 @@ single home for wire-format, auth, and delivery facts.
 
 ### Frontend surfaces (orthogonal to the command grid)
 
-The grid tracks the core (commands × protocols). Frontends are adapters over that
-core and carry their own state, tracked here:
+Frontends adapt the shared analysis and device-operation core and carry their
+own state, tracked here:
 
 | Surface | State | Spec | Notes |
 | ------- | ----- | ---- | ----- |
@@ -157,11 +148,57 @@ its own capability axis and is exempt from the RouterOS command-validation gate.
 Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 `src/protocols/btest*.ts` / `src/protocols/ec-srp5.ts` module headers.
 
-## Priority order
-
-Do not start a later item until the earlier cell or dependency checkpoint has
-matching evidence. The grid above is the live status; per-item detail lives in
-the linked `commands/<name>/`.
+## Current priority
+
+**Tightening validation as a whole** is the selected track, in the three-step
+order agreed on [#236](https://github.com/tikoci/centrs/issues/236):
+
+1. **Done** — fix the offline false rejects so the analyzer can be trusted as a
+   gate (#347/#348, shipped in #349; the measured corpus false-reject count went
+   4 → 1).
+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).
+
+The offline baseline stays `verified`: #264 closed the measured token vocabulary
+and #322 closed the final bounded-execution gap, including the public depth-axis
+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
+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
+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
+assertion, give that defect a bounded issue and matching CHR-grounded controls
+rather than folding it silently into the live implementation.
+
+Unfinished SNMP, RoMON, TUI, or other protocol/frontend cells do not preempt this
+track. Change this selection when the maintainer selects another track.
+
+### Protocol backlog order
+
+Retained for protocol work when selected; this is not a dependency chain for
+offline analysis. Per-item detail lives in the linked `commands/<name>/`.
 
 1. **retrieve / rest-api** — `CHR-passed` (`commands/retrieve/`).
 2. **CDB resolution + metadata overrides** — `CHR-passed` (`commands/devices/`).

package/docs/errors/validation/syntax.md

@@ -1,9 +1,34 @@
 # `validation/syntax`
 
-RouterOS rejected the command syntax during the :parse gate.
+The command syntax was rejected by the validation gate — offline analysis, or
+the RouterOS `:parse` probe.
+
+The gate has two stages
+([`docs/CONSTITUTION.md` → Validation is the product](../../CONSTITUTION.md#validation-is-the-product)),
+and `error.context.validationStage` says which one spoke:
+
+- **`"offline"`** — centrs rejected the input before any connection was opened,
+  and `meta.validation.stages[]` shows the device stage `skipped`: the router was
+  never asked. The **corpus-gated analyzer** is the whole of this stage, and
+  `error.context.validationSource` names it. `error.context.span` carries the
+  offending byte range (end-exclusive) and `error.context.diagnostics[]` the
+  analyzer's own `explain/<analyzer>/<slug>` codes.
+
+  A quote-balance supplement used to sit beside it for the unterminated `"` or
+  `'` the analyzer passed, reporting no span. It is gone (GH#355): the analyzer
+  rejects a bare `'` itself now, with the byte span, and the supplement's own
+  model of `'` as a delimiter was false-rejecting input RouterOS accepts.
+- **absent** — RouterOS itself rejected it, through `:put [:parse "…"]`. When the
+  device reported a `(line N column M)`, it is on `error.position`, which is
+  RouterOS's authoritative 1-based **byte** column and is never synthesized by
+  centrs. An offline rejection never carries `error.position`.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `validation/syntax`.
+Run `centrs explain '<command>'` to see the offending bytes in context, fix the
+RouterOS CLI syntax — quotes and bracketed expressions most often — and retry.
+
+`--validate=false` bypasses **both** stages. Use it only to probe a RouterOS edge
+centrs reads wrong, never to work around a rejection you believe is correct: if
+the validator rejects something a real router accepts, the validator is the bug
+(constitution: validation is the product).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -31,6 +31,7 @@
 	"exports": {
 		".": "./src/index.ts",
 		"./cli": "./src/cli.ts",
+		"./explain": "./src/explain.ts",
 		"./mcp": "./src/mcp.ts",
 		"./tui": "./src/tui.ts",
 		"./webproxy": "./src/webproxy.ts",
@@ -64,7 +65,7 @@
 		"lint": "bun run lint:biome && bun run lint:typecheck",
 		"lint:git:commit": "bun run lint:biome",
 		"lint:git:push": "bun run lint:ci",
-		"lint:ci": "bun run lint && bun run docs:cli:check && bun run explain:value-census:readme:check && bun run explain:token-census:readme:check && bun run explain:operator-readme:check && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
+		"lint:ci": "bun run lint && bun run docs:cli:check && bun run explain:value-census:readme:check && bun run explain:token-census:readme:check && bun run explain:highlight-agreement:readme:check && bun run explain:operator-readme:check && bun run explain:bracket-equals:readme:check && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
 		"lint:cspell": "cspell lint . --gitignore",
 		"lint:cspell:all": "cspell lint . --no-gitignore",
 		"lint:markdownlint": "markdownlint-cli2 \"**/*.md\" \"!.scratch/**\"",
@@ -92,9 +93,18 @@
 		"docs:cli": "bun run scripts/gen-cli-docs.ts",
 		"docs:cli:check": "bun run scripts/gen-cli-docs.ts --check",
 		"docs:errors": "bun run scripts/gen-error-pages.ts",
+		"explain:bracket-equals": "bun run scripts/explain-bracket-equals.ts",
+		"explain:bracket-equals:check": "bun run scripts/explain-bracket-equals.ts --check",
+		"explain:bracket-equals:readme": "bun run scripts/explain-bracket-equals.ts --readme",
+		"explain:bracket-equals:readme:check": "bun run scripts/explain-bracket-equals.ts --readme --check",
+		"explain:browser-consumer": "bun run scripts/explain-browser-consumer.ts",
 		"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: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:menus": "bun run scripts/gen-explain-menus.ts",
 		"explain:operator-census": "bun run scripts/explain-operator-census.ts",
@@ -116,6 +126,7 @@
 		"explain:value-census:check": "bun run scripts/explain-value-census.ts --check",
 		"explain:value-census:readme": "bun run scripts/explain-value-census.ts --readme",
 		"explain:value-census:readme:check": "bun run scripts/explain-value-census.ts --readme --check",
+		"explain:arg-reach": "bun run scripts/explain-arg-reach-sweep.ts",
 		"explain:token-census": "bun run scripts/explain-token-census.ts",
 		"explain:token-census:check": "bun run scripts/explain-token-census.ts --check",
 		"explain:token-census:readme": "bun run scripts/explain-token-census.ts --readme",