@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/commands/devices/README.md

@@ -65,7 +65,15 @@ inert. (Earlier drafts said "the comment is not a lookup key" — superseded.)
 When `<router>` matches an entry (by `target` or a lookup key), credentials and
 other CDB-resident fields load from that entry. If nothing matches, the call
 still proceeds but `--username` / `--password` (or `CENTRS_USERNAME` /
-`CENTRS_PASSWORD`, or a `__default__` record) become mandatory.
+`CENTRS_PASSWORD`, or a `__default__` record) become mandatory. The one
+exception is a **pinned** CDB (`--cdb-file`, `CENTRS_CDB_FILE`,
+`CENTRS_CDB_PASSWORD`, or a `centrs.env` CDB path) with no `__default__`
+record: a DNS name or identity that matches nothing fails closed with
+`cdb/not-found-target`, because it can't be told apart from a mistyped record.
+An address that matches nothing still proceeds as a literal host: an IPv4 or
+IPv6 literal (optionally with a port, IPv6 as `[…]:port`), an `http(s)://` URL,
+or a MAC. On MCP every target must still be registered
+(`cdb/target-not-registered`).
 
 ### Ambiguity
 
@@ -326,12 +334,13 @@ runs produce stable diffs.
 - A multi-target **write** is gated by `--yes`, confirmed once up front (not per
   target); without it the error/tip names the blast radius (how many routers).
   `--force` stays scoped to destructive `devices` CDB mutations.
-- Commands that are not safe to fan out (`terminal`, and `api --stream` /
-  `--listen`) reject a multi-target selection with `usage/fanout-not-supported`.
+- Commands that are not safe to fan out (`terminal`, and `api --stream` or a
+  `/listen` endpoint) reject a multi-target selection with `usage/fanout-not-supported`.
 
 ## Subcommands
 
 ```text
+centrs devices init                     # create an empty CDB at the resolved path
 centrs devices list [--group G] [--where attr=value]
                     [--near lat,lon,radius] [--bbox south,west,north,east]
                     [--format json|yaml|text]
@@ -361,8 +370,16 @@ clack-style prompt used by `@tikoci/quickchr`); it is **not** a separate
 field-editing verb, and invoking it today returns `usage/not-implemented`. There
 is no `update`.
 
+- `init` creates an empty open CDB at the resolved path (`--cdb-file`,
+  `CENTRS_CDB_FILE`, or the default), with parent directories and mode `0600`.
+  It never overwrites: on an existing, readable CDB it succeeds with a
+  `cdb/file-exists` warning and writes nothing. An explicit path is created only
+  by `init`; every other subcommand reports `cdb/not-found` for it (typo
+  protection), and that error names `init`.
 - `list` (alias `print`) shows resolved targets, their record type, group, and
-  a one-line provenance summary. No network IO. `--where attr=value`
+  a one-line provenance summary. Each row carries the `identity=`/`mac=`/`ip=`
+  lookup keys it resolves by (when set), so one call maps names to records. No
+  network IO. `--where attr=value`
   (repeatable, AND-combined) filters by CDB-stored facts/comment-kv plus core
   record fields (`target`/`group`/`identity`/`mac`) — e.g. `--where
   lat=37.7749`. `--near lat,lon,radius` and `--bbox south,west,north,east`

package/commands/devices/examples.md

@@ -29,7 +29,8 @@ centrs devices list --cdb-file $CDB
 ```
 
 Envelope: `ok: true`, `data` is an array of `{ target, recordType, group?,
-user, sources }`. No `meta.timing.request`.
+user, identity?, mac?, ip?, sources }` — the lookup keys appear only when the
+record's comment sets them. No `meta.timing.request`.
 
 ### 2. List a single group
 
@@ -46,7 +47,8 @@ valid success.
 centrs devices list --cdb-file /tmp/does-not-exist.cdb
 ```
 
-Errors with `cdb/not-found`. `details_url` populated.
+Errors with `cdb/not-found`. `details_url` populated. The remediation names
+`centrs devices init --cdb-file <path>` (example 54).
 
 ## show
 
@@ -634,3 +636,32 @@ Both succeed: the `add` stores the freeform comment verbatim, and the later
 `set timeout=5000` does **not** raise `input/incomplete-gps` even though the
 record's GPS pair is incomplete. Touching `lat`/`lon` (e.g. `set lat=…`) would
 re-enable the pairing check.
+
+## init
+
+`init` is the explicit way to start a CDB at a path you choose (#376). Reads
+and mutations never create an explicit `--cdb-file`/`CENTRS_CDB_FILE`; only the
+default path is created implicitly on first run.
+
+### 54. Start a repo-local CDB
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+centrs devices add 192.0.2.1 --user robot-reader --cdb-file ./lab/winbox.cdb --json
+```
+
+Creates missing parent directories and an empty open CDB with mode `0600`.
+`data` is `{ cdbFile, created: true, recordCount: 0 }`. The `add` then succeeds.
+
+### 55. `init` never clobbers
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+```
+
+On an existing, readable CDB: `ok: true`, `data.created: false`,
+`data.recordCount` is the current count, and a `cdb/file-exists` warning says
+nothing was written. As with `git init`, re-running is safe. An existing file that
+does not load fails with that load error (`cdb/parse-failed`,
+`cdb/password-required`) and is left untouched. A location that cannot be
+written fails with `cdb/create-failed`.

package/commands/execute/README.md

@@ -1,12 +1,12 @@
 # execute
 
 Run a RouterOS CLI command and return its (semi-structured) output. `execute`
-is the single read/write surface for RouterOS add/set/remove and other
+is the single read/write surface for RouterOS configuration and operational
 CLI-shaped commands — there is no separate `update` command.
 
 Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 `docs/MATRIX.md` and `commands/execute/examples.md`, examples 1–11 over REST,
-12–19 over the native API, 20–22 over mac-telnet, and S1–S4 over ssh, green via
+12–19 over the native API, 20–22 over mac-telnet, and S1–S5 over ssh, green via
 `bun run test:integration`), including multi-target fan-out (see **Target
 selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 `not-started`. SNMP is retrieve-only and rejects `execute`.
@@ -15,7 +15,8 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 
 - Mirror RouterOS `execute` semantics. Input is a CLI string; output is
   console-shaped text (or structured records for path+verb writes) wrapped in
-  the standard envelope. This includes write-shaped add/set/remove.
+  the standard envelope. This includes selector-, positional-id-, and
+  non-CRUD-shaped writes.
 - Validation runs **offline first, then on the device** (see constitution:
   validation; GH#354). Stage 1 is the corpus-gated analyzer over the exact
   command string, with no connection: a syntax fault is rejected with a byte
@@ -27,8 +28,10 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   GH#230): a single `:put [:parse "<cmd>"]` covers both the syntax and the
   unknown-attribute (name-level) gate on **every** transport — `:parse` never
   throws; its return value's printed form (`(evl …)` / `(evl bad parameter …)` /
-  `(<%% bad command name …)`) is read from the REST/native `ret` *and* the
-  console output. That check is necessary, not sufficient: value-type errors pass
+  `(<%% bad command name …)`, or a bare line-anchored `syntax error` /
+  `expected …` / `missing … (line N column M)`, examples V4) is read from the
+  REST/native `ret` *and* the console output. An accepted return can echo
+  those words, so only the anchored forms reject. That check is necessary, not sufficient: value-type errors pass
   it, and the `/console/inspect request=child` / server re-validation semantic
   checks are separate. Command-level `request=completion` is deliberately not
   used: it hangs REST and closes native API on RouterOS 7.12.2 (GH#343), while
@@ -36,9 +39,21 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   The outer RouterOS string literal escapes backslash, quote, and dollar so
   validation parses the caller's exact command rather than expanding variables
   in the wrapper.
-- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
-  `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
-  whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
+- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` in
+  `src/execute.ts`): it decides which validation and transport path runs.
+  `isWriteShaped` is deliberately independent: script fallback for `[find]`, a
+  positional id, or other non-`key=value` input never bypasses confirmation.
+  Known read verbs are allowlisted; an unknown menu verb fails closed as a
+  write-shaped operation. In script mode every command head in a statement
+  (the statement start and each `[…]` or `{…}` body) must be a read: its verb
+  is the first word past the known menu prefix, so `/ip address print` is a
+  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, and so is any command
+  carrying `file=`: RouterOS redirects command output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc` and
+  `/file/print file=test` creates `test.txt` even though `export` and `print`
+  are read verbs. The shared
+  `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
   `test/unit/execute-canonicalize-contract.test.ts`; the parser-vendoring
@@ -68,12 +83,11 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   else passes its `detail`/body plus the HTTP status through
   `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
   a hand-rolled `routeros/*` table on the REST side.
-- **Run-time fault mapping — later (JG-28).** `mapRouterOsError`'s table covers
-  the faults seen so far; a known gap is errors that *pass* `:parse`/validation
-  but fail at **run time** (a syntactically valid command the router rejects when
-  executed). `tikoci/vscode-tikbook` has an error-string mapping for these worth
-  porting into `src/core/routeros-errors.ts`. Background research, not yet
-  scheduled — captured here so it isn't lost (no GitHub issue by design).
+- **Run-time fault mapping.** A successful transport can still carry a RouterOS
+  rejection in `/execute`'s `ret`. Result detection lives beside the grounded
+  mappings in `src/core/routeros-errors.ts`, uses anchored result shapes so
+  ordinary output containing error-like prose remains output, and preserves a
+  passed validation history while failing the overall envelope.
 - Output is *string*-shaped for script-mode; richer parsing is a future
   concern. The envelope must still distinguish RouterOS errors from successful
   runs (a 200 with a RouterOS error string is still an error — see
@@ -122,14 +136,28 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   mac-telnet. Callers that want IP-level execution may opt into ARP-based
   MAC → IP resolution with `--resolve arp` (plus `--via native-api`/`rest-api`)
   before protocol selection.
+- An explicit `http(s)://host[:port]` target (positional, `--host`, or
+  `CENTRS_HOST`) names the REST service: with no `via` pinned anywhere,
+  auto-selection picks `rest-api` and keeps the URL's scheme and port
+  (`meta.settings.via` source `default` / `via:target-url`). Otherwise
+  auto-selection picks native-api. On the IP transports (native-api, REST,
+  ssh), a port typed into the target (`host:port`, `http://host:port`,
+  including an explicit `:80`/`:443`) is honored. The port settings ladder
+  (`--port`, `CENTRS_PORT`, a CDB `port=` comment, config) wins over it, and
+  the transport default comes last. The port carried by a matched CDB
+  record's `target` is not applied to native-api. mac-telnet addresses the MAC,
+  so its `--host`/`--port` are only the UDP delivery endpoint.
 - When the resolved transport is mac-telnet and **no** username or password is
   resolved from any source, execute emits a `tip/mac-telnet-no-credentials`
   pointer: mac-telnet logs in with RouterOS credentials over **MTWEI** (MD5 is
   refused by current RouterOS), so an empty login is rejected at connect time.
   It is a tip, not an error — the call is still attempted.
 - Default output is human-readable `text`; pass `--json`/`--format json`
-  (or set `CENTRS_FORMAT=json`) for the structured envelope. Errors always
-  render as `[code] summary` + `Fix:` lines in text mode.
+  (or set `CENTRS_FORMAT=json`) for the structured envelope. In text mode every
+  command renders errors the same way (`formatCentrsErrorText`): `[code] summary`,
+  then `At:` (RouterOS position or offline byte span), `Device said:` (RouterOS's
+  own words), `Fix:` and `Details:` when present. `--verbose` adds the full
+  `context`.
 - CDB comment-kv metadata may provide per-target `via`, `port`, and `ssh-key`
   overrides; CLI/API arguments still win.
 - RoMON and WinBox Terminal are lower priority than mac-telnet until their
@@ -175,6 +203,10 @@ with the first SSH consumer, `transfer`/sftp; `execute / ssh` (this command) and
 `terminal / ssh` followed as separate transports over the same host-`ssh`
 plumbing (`src/protocols/ssh.ts`) — all three SSH cells are `CHR-passed`.
 
+A selected key adds `IdentitiesOnly=yes`, preventing fallback to unrelated
+agent keys. Explicit OpenSSH `IdentityFile` configuration still applies; see
+[`terminal` → SSH key selection](../terminal/README.md#ssh-key-selection).
+
 Over SSH — like mac-telnet — `execute` is a **console transport**: it runs a
 CLI line and returns text (`SshExecClient`, one `ssh user@host "<command>"` per
 command; validation reuses the same `:put [:parse …]` gate), so structured
@@ -215,9 +247,19 @@ many tokens):
   the command; no `--` needed). One `--quickchr` stays single-target; repeating
   it fans out; mixing it with positionals or CDB selectors is
   `usage/conflicting-flags` (constitution: resolution providers).
+- `execute --host http://192.0.2.10:8080 '/system/resource/print'` (or
+  `execute --host <host|url> -- <command>`) — the `--host` **flag** stands in
+  for a missing `<target>`: a lone positional is the command, and nothing
+  before `--` is fine. There is no `<target>`, so there is no CDB lookup and no
+  record credential can be picked up; auth comes from flags, env or config.
+  Two or more positionals without `--` keep the legacy split, so
+  `execute <mac> <command> --via mac-telnet --host <udp-host>` (the mac-telnet
+  delivery override) is unchanged. `CENTRS_HOST` never changes positional
+  parsing: `execute '<command>'` with it set still reads the lone positional as
+  the target.
 
-Because `execute` is the primary **write** path, a write-shaped fan-out
-(add/set/remove) is gated by **`--yes`**, confirmed **once** up front; without it
+Because `execute` is the primary **write** path, a write-shaped fan-out is gated
+by **`--yes`**, confirmed **once** up front; without it
 the error names the blast radius (how many routers). Write-ness is determined from
 the command alone (`canonicalizeExecuteCommand` + `isWriteShaped`), so the gate
 fires before any target is dialed. Per-target validation still runs because

package/commands/execute/examples.md

@@ -373,6 +373,23 @@ centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.51/32 interface=eth
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`, `meta.via=ssh`,
 and no address is added — the console `:parse` gate catches `bogus` pre-mutation.
 
+### S5. An explicit rejected key cannot fall back to an unrelated agent key
+
+`test/integration/ssh-identity.test.ts` imports `$KEY` on a disposable CHR and
+loads it into a private SSH agent. `$WRONG_KEY` is a second, untrusted key.
+The test uses an empty OpenSSH config so no other `IdentityFile` is selected.
+
+```bash
+centrs execute 127.0.0.1 ':put [/system/identity/get name]' --via ssh --port $SSH_PORT --username $U --ssh-key $WRONG_KEY --insecure --json
+centrs transfer 127.0.0.1 list --via sftp --port $SSH_PORT --username $U --ssh-key $WRONG_KEY --insecure --json
+printf ':put ("centrs-identity:" . [/system/identity/get name])\n/quit\n' | centrs terminal 127.0.0.1 --via ssh --port $SSH_PORT --username $U --ssh-key $WRONG_KEY --insecure
+```
+
+Execute and transfer fail with `auth/failed`; the terminal relay preserves
+OpenSSH's nonzero exit and `Permission denied` diagnostic. The test disables
+interactive prompts on its terminal relay. Controls using `$KEY`, or omitting
+`--ssh-key` to use the private agent, succeed for all three commands.
+
 ## Offline gate (stage 1)
 
 Validation runs offline before it runs on the device
@@ -428,6 +445,155 @@ and `meta.validation.stages` listing **both** stages as `skipped`. A gated
 surface always reports every stage, so a consumer reading `stages` never has to
 special-case the disabled shape.
 
+### V4. A device-only `missing …` rejection is still a rejection
+
+The offline stage passes `/ip/address/find where=`: an empty `where` is not a
+structural fault it can see. RouterOS's `:parse` returns
+`missing value for where (line 1 column 24)` (CHR 7.24.4), a bare diagnostic
+like `syntax error`, so the device stage must reject it (GH#375). Before that
+fix the classifier only knew `syntax error`, `bad command name` and
+`expected …`, so it reported this reply as a pass and the command ran.
+
+```bash
+centrs execute $R '/ip/address/find where=' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`, `error.context.detail`
+is RouterOS's own `missing value for where (line 1 column 24)`,
+`error.position={"line":1,"column":24}`, and `meta.validation.stages` is
+`offline: passed` followed by `device: failed`. `meta.validation.syntax=false`,
+and `semantic` is absent: `:parse` refused the command, so the name-level check
+was never asked (GH#435).
+
+CHR 7.24.4 controls, via `:put [:parse "…"]`: `find where` without `=` parses
+(IL). `print where=` is rejected differently (`expected end of command`, at
+`where`). An unclosed bare `{` block or menu block (`/ip address {` then
+newlines) returns `missing closing brace (line 3 column 1)`, while an unclosed
+`do={` returns `expected closing brace`. Offline analysis usually catches the
+unclosed-brace cases first.
+
+### V5. A menu from a package that is not installed is not a syntax error
+
+RouterOS's `:parse` reports a menu the device does not have as a syntax fault —
+`syntax error (line 1 column 10)` for `/zerotier/print`, pointing at the `/`
+after the absent segment, and `bad command name container (line 1 column 2)` for
+the space spelling `/container print` (CHR 7.23.7). centrs locates the segment,
+looks the path up in its path catalog, and names the package (GH#361).
+
+```bash
+centrs execute $R '/zerotier/print' --via rest-api --username $U --password $P --json
+centrs execute $R '/container print' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/package-missing`,
+`error.context.path` is `/zerotier` (then `/container`),
+`error.context.packages` names the published package, the remediation points at
+`/system/package/print` and never at the syntax, and `error.position` and
+`error.context.detail` keep RouterOS's own column and words. V5–V7 all report
+`meta.validation.syntax=false`. `semantic` is absent, or `not-applicable` for
+the script-shaped `/container print` (GH#435).
+
+### V6. A menu no RouterOS build has is an unknown path
+
+```bash
+centrs execute $R '/ip/nosuchmenu/print' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-path`,
+`error.context.path=/ip/nosuchmenu`, `error.context.segment=nosuchmenu`. The
+path catalog covers every 7.10–7.25 build with all extra packages, so a path it
+lacks is not a missing package.
+
+### V7. A published menu gated on more than a package
+
+```bash
+centrs execute $R '/interface/w60g/print' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/menu-unavailable`,
+`error.context.path=/interface/w60g`, and `error.context.gates` carries both
+published gates — package `wireless-rep` and hardware capability `60ghz` —
+because a 60 GHz menu can be absent with the package installed. Nested and later
+statements locate the same way (`:put [/interface/w60g/get [find] disabled]`
+points at column 22). A menu-scope block (`/ip { nosuchmenu print }`) or a menu
+named on an earlier line abstains and stays `validation/syntax`: the offline
+analyzer does not resolve that parent, and centrs does not guess it.
+
+### V8. Wrong credentials: the device stage is not reached (GH#435)
+
+```bash
+centrs execute $R '/system/identity/print' --via rest-api --username centrs-wrong --password centrs-wrong --json
+```
+
+Envelope: `ok: false`, `error.code=transport/auth-failed`. `meta.validation`
+has no `result`, `syntax` or `semantic`. Its stages are `offline: passed`, then
+`device: skipped` with `reason: "not reached: transport/auth-failed"`. RouterOS
+answered 401 before `:parse` could give a verdict.
+
+## Write authorization and returned runtime faults
+
+These regressions are transport-independent and run in
+`test/integration/execute.test.ts` (with MCP's selector form also covered by
+`test/integration/mcp.test.ts`).
+
+### W1. Script-mode selector and positional writes still require confirmation
+
+```bash
+centrs execute $R '/ip/address/remove [find comment=centrs-write-gate]' --via rest-api --username $U --password $P </dev/null
+```
+
+The same contract holds for `/ip/address/remove *1`. Both stay script-mode so
+RouterOS receives the raw selector/id syntax, but the independent safety gate
+returns `usage/confirmation-required` before validation or mutation.
+
+### W2. Non-CRUD mutation verbs still require confirmation
+
+```bash
+centrs execute $R '/ip/address/disable numbers=*1' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`; the address
+remains enabled. Unknown RouterOS menu verbs also fail closed as write-shaped.
+Root mutators such as `/import` and indirect execution through `:execute` use
+the same gate.
+
+### W3. Space-separated menu reads run without confirmation
+
+```bash
+centrs execute $R '/system identity print' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true`. The space-separated spelling puts menu segments and the
+verb in bare words, so the gate walks the known menu prefix and reads the first
+word past it as the verb. `/ip address print where …` and
+`:put [/system identity get name]` are reads the same way. The walk is also what
+keeps an unlearned command gated: `/user expire-password print` names
+`expire-password`, a published command outside both verb allowlists, whose
+argument happens to be `print`, so it returns `usage/confirmation-required`.
+Every command head in a statement is checked, including `[…]` and `do={…}`
+bodies.
+
+### R1. A post-validation `/execute` rejection fails the overall envelope
+
+```bash
+centrs execute $R '/ip/service/set www-ssl certificate=nope' --via rest-api --username $U --password $P --yes --json
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, exit `1`, while
+`meta.validation.result="passed"` and both stages remain `passed`: the rejection
+happened at run time, after the scoped checks completed. The same result is
+asserted over native API.
+
+### R2. Error-like prose remains ordinary script output
+
+```bash
+centrs execute $R ':put "status: no such item appears in ordinary output"' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: true`. Returned-text classification uses anchored grounded
+shapes; it does not fail arbitrary output merely because it contains an error
+phrase.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar
@@ -495,6 +661,17 @@ command). With no `--cdb-file`, both are ad-hoc literals, labeled by
 `meta.target.input` with no `recordIndex`: `data.summary = { total: 2, ok: 1,
 failed: 1 }`, exit `2`.
 
+### F7. An address that misses a pinned CDB is a literal; a name is not (#427)
+
+```bash
+centrs execute $A:$API_PORT no-such-router --cdb-file $CDB --username $U --password $P --json -- /system/resource/print
+```
+
+Neither positional matches a record. The address is dialed as a literal host
+(inner `ok: true`). The name fails closed with `cdb/not-found-target`, because
+it can't be told apart from a mistyped record name. `data.summary = { total: 2,
+ok: 1, failed: 1 }`, exit `2`.
+
 ## Protocol selection notes
 
 For an unresolved MAC target, execute auto-selection defaults to mac-telnet
@@ -510,6 +687,53 @@ Envelope: `meta.via=mac-telnet` when `$MAC` is not resolved from CDB and no
 they must opt into MAC-to-IP resolution (`--resolve arp` + `--via …`) before
 protocol selection.
 
+### P1. An `http(s)://` target selects rest-api on its own port (#426)
+
+```bash
+centrs execute http://$A:$REST_PORT ':put [/system/identity/get name]' --username $U --password $P --json
+```
+
+Envelope: `ok: true`, `meta.via=rest-api`, `meta.settings.via =
+{ kind: "default", key: "via:target-url" }`. No `--via` is pinned, and the URL's
+scheme and port are what get dialed.
+
+### P2. A typed `host:port` keeps native-api on that port (#426)
+
+```bash
+centrs execute $A:$API_PORT ':put [/system/identity/get name]' --username $U --password $P --json
+```
+
+Envelope: `ok: true`, `meta.via=native-api`, dialing `$API_PORT` (no
+`--port` flag), the same way ssh and REST already treat a typed port.
+
+### P3. A pinned CDB doesn't refuse an address it has no record for (#427)
+
+```bash
+centrs execute $A:$API_PORT ':put [/system/identity/get name]' --cdb-file $CDB --username $U --password $P --json
+centrs execute http://$A:$REST_PORT ':put [/system/identity/get name]' --cdb-file $CDB --username $U --password $P --json
+centrs execute no-such-router ':put [/system/identity/get name]' --cdb-file $CDB --username $U --password $P --json
+```
+
+`$CDB` has no record for any of the three. The first two are `ok: true` over
+native-api and rest-api: an IP, `[IPv6]`, `http(s)://` URL or MAC that misses a
+pinned CDB is a literal host, exactly as with no CDB. The third is `ok: false`,
+`error.code = cdb/not-found-target`: a name or identity that misses still fails
+closed.
+
+## `--host` as the target (#428)
+
+### H1. `--host` stands in for `<target>`; a lone positional is the command
+
+```bash
+centrs execute --host http://$A:$REST_PORT ':put [/system/identity/get name]' --username $U --password $P --json
+centrs execute --host $A:$API_PORT --username $U --password $P --json -- ':put [/system/identity/get name]'
+```
+
+Both are `ok: true`, the first over rest-api (the URL names REST) and the second
+over native-api on `$API_PORT`. `meta.target.source = { kind: "cli", key:
+"host" }`, with no `recordIndex`: there is no `<target>`, so there is no CDB
+lookup. `retrieve`, `api` and `transfer` have the same rule (their H1).
+
 ## quickchr targets (#134)
 
 `$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth

package/commands/explain/README.md

@@ -172,7 +172,7 @@ today's path/verb/args split and script-vs-structured gate:
   The *container* half of that pair is since decidable. `src/explain/menus.ts`
   (#207) bakes only the menu-vs-command node type — not a schema — and it is
   version-less because the pinned trees show no `dir`↔`cmd` flip across
-  7.10.2 → 7.25beta3 or across architectures. So `/ip/route` now resolves as
+  7.10.2 → 7.25beta5 or across architectures. So `/ip/route` now resolves as
   `navigation` (#210). The floor is unmoved: the table is deliberately
   incomplete, absence from it decides nothing, and every rule above it still
   refuses rather than guesses.
@@ -199,10 +199,11 @@ today's path/verb/args split and script-vs-structured gate:
   Discovery is the union of MikroTik's two published inventories, not the
   sitemap alone. A *branching* menu is served as a trailing-slash category URL
   with no `.md` of its own, while that menu's own entry is published at
-  `<dir>/<basename>.md` and listed only in `llms.txt` — so sitemap-only
-  discovery dropped 256 of 1,070 pages, silently and field-heavily. Generation
-  asserts that every category dir still contributes its leaf, so the next
-  inventory reshape fails loudly instead of shrinking the table (#285,
+  `<dir>/<basename>.md` (since 2026-10-06, `<dir>.md`) and listed only in
+  `llms.txt` — so sitemap-only discovery dropped 256 of 1,070 pages, silently
+  and field-heavily. Generation asserts that every category dir still
+  contributes its own page under one of those two spellings, so the next
+  inventory reshape fails loudly instead of shrinking the table (#285, #417,
   tikoci/rosetta#137).
 
   **Source refresh (#335, accepted 2026-09-13).** The inspect pins retain the
@@ -221,6 +222,42 @@ today's path/verb/args split and script-vs-structured gate:
   coherent generated catalog has 1,120 paths: 959 `both`, 67 `inspect`, and 94
   `published`; it still reports zero navigation-vs-command contradictions.
 
+  **Source refresh (accepted 2026-09-27).** The two current pins advance to the
+  channels then live — stable 7.24.2 → 7.24.4 and development 7.25beta3 →
+  7.25beta5 — both still architecture-paired, both history anchors untouched.
+  The refresh is a structural no-op: the inspect union holds at 617 menus and
+  the catalog at 1,120 paths, with no path added or removed and no kind change.
+  What moved is current-only publication: the CLI Reference grows from 1,053
+  pages / 1,060 entries to 1,055 / 1,062, which documents
+  `/interface/ethernet/pon` and `/ip/ssh/known-hosts` for the first time and so
+  moves both from `inspect` to `both` — 961 `both`, 65 `inspect`, 94
+  `published`. Zero navigation-vs-command contradictions, unchanged.
+
+  **Source refresh (accepted 2026-10-11, #417).** MikroTik changed the CLI
+  Reference layout on 2026-10-06: a branching menu's own entry moved from
+  `<dir>/<basename>.md` to `<dir>.md`, and pages dropped their MDX `import`
+  preamble, so the `# title` line is no longer fenced off by an import. Both
+  guards refused, correctly, and the catalog check could not report anything
+  for days. The parser now accepts either layout (a category dir needs one of
+  the two page spellings, and both at once is reported); losing the page
+  entirely still aborts. The inventories reconcile exactly: 846 sitemap pages
+  plus 253 category pages equal the 1,099 pages `llms.txt` lists. The inspect
+  pins add 7.26beta1 (x86 and arm64) because the manual documents the
+  development channel, and a path new in it with no matching tree is
+  published-only with no gate to explain it. Reviewed against the committed
+  catalog: 47 paths added, 1 removed, 3 gate strings changed, and no kind
+  change, no provenance loss and no navigation-vs-command contradiction. The
+  additions are the 32 `/cmr` paths, `/interface/wifi/dashboard`,
+  `/system/dashboard`, `/tool/apptraffic`, `/interface/ethernet/pon/monitor`,
+  `/interface/wireless/snooper/snoop` and
+  `/interface/ethernet/switch/rule/reset-counters-all`; the removal is the
+  published-only `/system/routerboard/settings/keep-frequency`, which its page
+  no longer lists. The CLI Reference moves from 1,055 pages / 1,062 entries to
+  1,099 / 1,106; the inspect union from 617 to 636 menus; the catalog from
+  1,120 to 1,166 paths: 1,005 `both`, 67 `inspect`, 94 `published`.
+  `/interface/wifi/dashboard` and `/system/dashboard` are `inspect` only: the
+  trees carry them, the manual publishes no menu entry for them.
+
 There are real unknowns in how far offline parsing can go (expression
 grammar, scope fidelity vs `:parse`, `[]`-nesting corner cases). Grounding
 those unknowns was **phase 0** (#185); its findings are folded in throughout

package/commands/mcp/README.md

@@ -125,7 +125,8 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 - `centrs_retrieve` mirrors `retrieve`, including attribute projection,
   `listAttributes`, and `group` fanout.
 - `centrs_execute` mirrors `execute`. Read-shaped commands run subject only to
-  CDB membership; write-shaped add/set/remove are gated by the CDB policy below.
+  CDB membership; every write-shaped command is gated by the CDB policy below,
+  including selector/positional script forms and non-CRUD mutation verbs.
   Its MCP `destructiveHint` is **conservative — always `true`**, even though the
   tool also serves read-shaped commands: a single execute tool cannot vary the
   static annotation by argument, so it advertises the worst case and lets the