@tikoci/centrs 0.1.2 → 0.1.4

package/docs/errors/settings/consequential-value.md

@@ -0,0 +1,26 @@
+# `settings/consequential-value`
+
+`settings set` accepted a syntactically valid value with a real, non-obvious consequence (e.g. a global --insecure default, or a transfer-via value gated elsewhere).
+
+## Fix
+
+This is a warning, not a failure — the envelope is still `ok: true` and the
+value is written. `centrs settings set` emits it for exactly two keys today
+(the `warn` callback on the matching `SettingsKeyDef` in `src/settings.ts`):
+
+- `insecure` set to any truthy spelling (`true`, `yes`, `on`, `1`) makes
+  every command run without an explicit `--insecure`/`--no-insecure`
+  override trust RouterOS's self-signed TLS certificate or unknown SSH host
+  key globally, not just for one invocation. See the `insecure` row in
+  `commands/settings/README.md`'s "Known settings keys" table.
+- `transfer-via` set to `ftp` is accepted here — `ftp` is a syntactically
+  valid `CENTRS_TRANSFER_VIA` value — but `transfer` still rejects it at
+  call time with [`settings/unsafe-protocol-blocked`](unsafe-protocol-blocked.md)
+  unless `ALLOW_UNSAFE_PROTOCOLS` also includes `ftp`. The warning exists so
+  the write doesn't silently look like it "worked" when the value won't
+  actually take effect anywhere else yet.
+
+There is nothing to fix in the sense of retrying with different input — the
+value you asked for was written as requested. Run `centrs settings set
+insecure false` or pick a different `transfer-via` value if the consequence
+wasn't intended. See example 24 in `commands/settings/examples.md`.

package/docs/errors/settings/invalid-boolean.md

@@ -4,6 +4,24 @@ A boolean-like setting received a non-boolean value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-boolean`.
+`centrs settings set <attr> <value>` throws this for the three boolean-typed
+managed keys — `mcp-allow-adhoc`, `validate`, `insecure` — when `<value>`
+isn't one of the spellings the shared parser (`parseBoolean` in
+`src/resolver/settings.ts`) accepts: `true`/`false`, `yes`/`no`, `on`/`off`,
+or `1`/`0`, case-insensitively. Anything else — `maybe`, `2`, an empty
+string — fails with a remediation listing the accepted spellings.
+
+This isn't a `settings`-only rule: `parseBoolean` backs every `CENTRS_*`
+boolean setting across the app, so the same error and message shape appears
+whenever any command resolves a boolean env var to an unrecognized value,
+not just through `settings set`.
+
+One canonicalization detail worth knowing even though it isn't what triggers
+this error: once a boolean value *does* validate, `settings set` always
+writes the canonical `1` or `0` to `centrs.env`, never `true`/`false` —
+`CENTRS_MCP_ALLOW_ADHOC`'s reader in `src/mcp/config.ts` checks the literal
+string `"1"` rather than reusing `parseBoolean`, so writing `1`/`0`
+uniformly is what satisfies every reader. Retry `set` with one of the
+accepted spellings above; see
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-format.md

@@ -4,6 +4,21 @@ An unsupported output format was requested.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-format`.
+`centrs settings set format <value>` throws this when `<value>` isn't one of
+`text`, `json`, or `yaml` — the same `{text, json, yaml}` set every
+command's own `--format` flag (and `CENTRS_FORMAT`) validates against
+(`retrieveOutputFormats` and its `execute`/`transfer`/`api` counterparts).
+`centrs settings set format xml` is the canonical trigger; see example 14 in
+`commands/settings/examples.md`. A failed `set` never partially writes — the
+file is unchanged.
+
+`format` is the one managed key without a single universal built-in
+default: `retrieve`/`execute`/`transfer` default to `text`, but `api`
+defaults to `json`. Because of that, `centrs settings print`/`get format`
+can't report one scalar default when the key is unset — it reports a
+`perCommandDefault` map (`{ retrieve: "text", execute: "text", transfer:
+"text", api: "json" }`) instead, so this is the one key where "unset" looks
+different in the output shape than every other key.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for
+where `format` sits in the resolver chain once a value is set.

package/docs/errors/settings/invalid-integer.md

@@ -4,6 +4,21 @@ An integer setting received a non-integer or out-of-range value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-integer`.
+`centrs settings set max-results <value>` and `centrs settings set port
+<value>` both throw this when `<value>` fails the shared positive-integer
+rule (`resolveOptionalIntegerSetting` in `src/resolver/settings.ts`):
+`Number.isInteger(n) && n > 0`. `0`, negative numbers (`-1`), and
+non-numeric strings (`abc`) are all rejected the same way — `centrs settings
+set max-results 0` is the canonical trigger (example 20 in
+`commands/settings/examples.md`).
+
+This validator isn't specific to `settings` — `resolveOptionalIntegerSetting`
+is the shared helper every `CENTRS_*` integer setting resolves through
+(`max-results`, `port`, and any future integer key), so the same code and
+message shape appear whenever an integer env var, CLI flag, or `centrs.env`
+line resolves to a non-positive or non-numeric value anywhere in the app,
+not only through `settings set`.
+
+A failed `set` never partially writes; re-run with a positive integer. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-timeout.md

@@ -4,6 +4,23 @@ A timeout setting received an invalid value.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-timeout`.
+`centrs settings set timeout <value>` throws this when `<value>` doesn't
+match the shared duration grammar (`parseDuration` in
+`src/resolver/settings.ts`): a bare integer (milliseconds) or an integer
+with a `ms`/`s`/`m` suffix — `500ms`, `5s`, `1m`. Anything else, like
+`not-a-duration` (example 22 in `commands/settings/examples.md`), fails.
+`settings.ts` layers one more rule on top for `timeout` specifically: even a
+syntactically valid duration that parses to `0` is rejected — a zero timeout
+isn't a meaningful value to set.
+
+Like the other typed-value codes here, this isn't `settings`-exclusive:
+`parseDuration` backs `CENTRS_TIMEOUT` and every command's own `--timeout`
+flag, so the same failure shape shows up anywhere a duration string is
+resolved, not just through `settings set`.
+
+One write detail worth knowing: `settings set timeout` writes the
+**canonical parsed milliseconds**, not the raw suffixed string you typed —
+`centrs settings set timeout 5s` writes `CENTRS_TIMEOUT=5000` to
+`centrs.env`, not `CENTRS_TIMEOUT=5s`. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+this value feeds into the resolver chain.

package/docs/errors/settings/invalid-via.md

@@ -4,6 +4,25 @@ An unsupported protocol identifier was supplied to --via.
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `settings/invalid-via`.
+This one code covers two different value sets, because `settings` reuses it
+for two different keys. `centrs settings set via <value>` requires one of
+the protocol identifiers in `plannedProtocols` (`src/protocols/index.ts`):
+`rest-api`, `native-api`, `ssh`, `snmp`, `mndp`, `mac-telnet`, `romon`,
+`winbox-terminal` — `centrs settings set via carrier-pigeon` is the
+canonical trigger (example 21 in `commands/settings/examples.md`).
+`centrs settings set transfer-via <value>` reuses the same error code but
+validates against a completely different set: `auto`, `rest`/`rest-api`,
+`native`/`native-api`, `sftp`, `scp`, `fetch`, `ftp`. Unlike `CENTRS_VIA`,
+which has a per-device `via=` comment-kv counterpart, `CENTRS_TRANSFER_VIA`
+has none — `transfer` reads only the env var.
+
+The same validation backs `retrieve`/`execute`/`api`'s own `--via` flag more
+broadly, so the identical code and message shape appear there too, not only
+through `settings set`.
+
+`transfer-via ftp` is syntactically valid against the `transfer-via` set
+above — it does **not** trigger this error — but it does trigger a separate
+warning, [`settings/consequential-value`](consequential-value.md), because
+`transfer` still rejects `ftp` at call time unless `ALLOW_UNSAFE_PROTOCOLS`
+also opts in. See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Protocol
+selection) for the full `via` vocabulary.

package/docs/errors/settings/reserved-key.md

@@ -0,0 +1,29 @@
+# `settings/reserved-key`
+
+`settings set`/`reset` refused a credential-shaped or self-referential CENTRS_* key.
+
+## Fix
+
+`centrs settings set <attr> <value>` and `centrs settings reset <attr>` refuse
+five keys outright: `password`, `username`, `cdb-password`, `skip-env-file`,
+and `run-fast-integration` (the `settingsRefusedKeys` list in
+`src/settings.ts`). Each is refused for a different reason, not a blanket
+policy: `password`/`username` are credential-shaped and belong on the
+`__default__` CDB record — run `centrs devices add __default__ --user …
+--password …` instead of duplicating a secret into a second, unencrypted
+file. `cdb-password` is the CDB's own decrypt password; writing it beside the
+encrypted CDB it unlocks would defeat the encryption, so pass
+`--cdb-password` per invocation or export `CENTRS_CDB_PASSWORD` in the
+calling shell instead. `skip-env-file` is self-referential — a line in
+`centrs.env` that says "ignore this file" is a no-op by construction, since
+the file has to be read to find it. `run-fast-integration` is a CI/test
+signal `bun run test:integration` sets, never a human preference.
+
+`settings get`/`settings print` still work read-only on all five keys — this
+error is specific to the write path (`set`/`reset`). A read of `cdb-password`
+or `password` redacts the value rather than refusing outright; see
+[`settings/unknown-key`](unknown-key.md) for the different case of a token
+that isn't a recognized setting at all. See examples 17 and 29 in
+`commands/settings/examples.md`, and
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Identity and CDB) for why
+credentials route through `devices` rather than `centrs.env`.

package/docs/errors/settings/skip-env-file-active.md

@@ -0,0 +1,25 @@
+# `settings/skip-env-file-active`
+
+`settings print` ran under --skip-env-file; the shown centrs.env values would not apply to other commands run in the same environment.
+
+## Fix
+
+This is an informational warning, not a failure — `centrs settings print`
+still returns `ok: true` with the file's real contents. It appears only when
+`--skip-env-file` (or `CENTRS_SKIP_ENV_FILE`) was active on that same
+`print` invocation, as a reminder that the flag doesn't apply to `settings`
+itself: `settings` always reads and writes the real `centrs.env` file
+regardless of `--skip-env-file`, since inspecting/editing the file is this
+command's whole job (see the module doc comment at the top of
+`src/settings.ts`).
+
+What the warning is actually flagging is every *other* command: if
+`--skip-env-file`/`CENTRS_SKIP_ENV_FILE` is also active when you run
+`retrieve`/`execute`/`transfer`/`api` in that same shell or environment,
+those commands' resolvers skip loading `centrs.env` as a settings source —
+so the values `print` just showed you would not apply there. There's
+nothing to fix; either drop `--skip-env-file` if you want other commands to
+see these values, or ignore the warning if the isolation is intentional. See
+example 6 in `commands/settings/examples.md`, and
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Settings precedence) for how
+the config tier fits into the precedence ladder.

package/docs/errors/settings/unknown-key.md

@@ -0,0 +1,25 @@
+# `settings/unknown-key`
+
+`settings get`/`set`/`reset` received a token that is not a recognized CENTRS_*-shaped setting.
+
+## Fix
+
+`centrs settings get <attr>`, `set <attr> <value>`, and `reset <attr>` all
+normalize the token first — with or without the `CENTRS_` prefix, in
+kebab-case or SCREAMING_SNAKE (`format`, `FORMAT`, `centrs_format`, and
+`CENTRS_FORMAT` all resolve to the same key) — then look it up against the 13
+keys `settings` manages plus the 5 refused keys. This error fires when the
+normalized token matches neither list: a typo, a made-up name, or a
+`CENTRS_*` var no shipped command actually reads (see
+`commands/settings/README.md`, "Not yet wired — exclude from v1", for three
+such names that are deliberately unsupported today).
+
+Run `centrs settings print --all` to see every key `settings` recognizes,
+plus any unrecognized `CENTRS_*` lines already present in the file, tagged
+`(unrecognized)` — that second list is the fastest way to spot a typo you
+already wrote into `centrs.env` by hand.
+
+This is a different failure from [`settings/reserved-key`](reserved-key.md):
+that error means "this is a real setting, but writing it is off-limits";
+`settings/unknown-key` means the token isn't a setting `centrs` knows about
+at all. See examples 9 and 19 in `commands/settings/examples.md`.

package/docs/errors/transport/provider-trust.md

@@ -0,0 +1,29 @@
+# `transport/provider-trust`
+
+A warning (not an error): the target came from a named-live-provider
+(`--quickchr <name>`), and centrs relaxed peer verification to use its
+endpoint.
+
+## Why this happens
+
+quickchr's descriptor prefers the VM's TLS forwards (`https` / `api-ssl`),
+whose certificate is the CHR's own self-signed one, and its SSH endpoint's
+host key is regenerated per VM. The descriptor carries no trust material, so
+strict verification would reject every quickchr target and force `--insecure`
+ceremony onto every lab call.
+
+Instead, centrs treats the endpoint as **trusted by provenance**: quickchr
+vouches for a loopback-forwarded port (`127.0.0.1:<port>`) of a VM the user
+owns, so peer verification is relaxed for exactly that connection — with
+`provider` provenance on `meta.settings.insecure` and this warning on the
+envelope, never silently.
+
+## When to care
+
+- If this warning appears on a target you did **not** select with
+  `--quickchr`, that is a bug — report it.
+- The relaxation never applies to CDB, literal, or env-resolved targets;
+  those still require an explicit `--insecure` (which raises
+  [`transport/insecure-trust`](./insecure-trust.md) instead).
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.

package/docs/errors/usage/fanout-not-supported.md

@@ -0,0 +1,16 @@
+# `usage/fanout-not-supported`
+
+The command or mode cannot fan out across multiple targets.
+
+## Fix
+
+Some surfaces are single-session by nature and reject a multi-target selection:
+
+- `terminal` — an interactive console relay to one device.
+- `api --stream` / `api --listen` — an open-ended native-api follow is a single
+  long-lived subscription.
+
+Run the command against a single target (one positional, no `--group` / `--where` /
+`--all` / `--default`). To act on a fleet, use a fan-out-capable verb instead
+(`retrieve`, `execute`, `api` without `--stream`, `transfer`). See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) (Target selection).

package/docs/errors/usage/stdin-ignored.md

@@ -0,0 +1,28 @@
+# `usage/stdin-ignored`
+
+stdin was redirected but the input came from the positional argument, so
+anything piped in was not analyzed.
+
+This is a **warning**, not an error: the analysis ran and its result is exactly
+what the arguments asked for. What the warning reports is that a second possible
+input source was present and lost.
+
+## Fix
+
+Name the source you meant:
+
+```bash
+cat script.rsc | centrs explain --file -  # analyze stdin
+centrs explain '/ip/route print'          # analyze the positional
+```
+
+The live form spells the same thing (`… | centrs explain edge1 --file -`) and is
+already parsed, but it is refused with
+[`usage/not-implemented`](not-implemented.md) until the phase-2 live probes
+land — so it is not a fix you can apply today.
+
+`explain` reads ambient stdin only when no positional could be the input, so a
+positional always wins. It cannot check whether the pipe actually carries bytes
+without consuming fd 0, which is why the collision is reported rather than
+resolved. See [`commands/explain/README.md`](https://github.com/tikoci/centrs/blob/main/commands/explain/README.md)
+for the positional grammar.

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

@@ -1,9 +1,42 @@
 # `validation/unknown-attribute`
 
-An attribute is not valid for the path/verb per /console/inspect.
+An attribute or argument is not valid for the requested RouterOS operation.
+The validator rejects the request before RouterOS executes it.
+
+## Context keys
+
+Context keys vary by validation mechanism. Callers must not assume every key
+below is present on every `validation/unknown-attribute` rejection.
+
+| Key | Type | Notes |
+| --- | ---- | ----- |
+| `parameter` | `string` | First offending name. Present on retrieve and inspect-gated rejections, and on console `:parse` when RouterOS reports `bad parameter <name>`. |
+| `requestedAttributes` | `string[]` | Full requested name list. Retrieve and inspect-gated API/execute validation only. |
+| `availableAttributes` | `string[]` | Names exposed for the path/verb. Retrieve and inspect-gated API/execute validation only. |
+| `path` | `string` | Slash-prefixed RouterOS path (for example `/ip/address`). Retrieve and inspect-gated API/execute validation only. |
+| `verb` | `string` | Verb when applicable (`print`, `add`, `set`, …). Inspect-gated API/execute validation only; retrieve is path-only. |
+| `validationSource` | `string` | Validation provenance. Inspect-gated API/execute and console `:parse` only; retrieve does not currently emit it. |
+| `command` | `string` | Original CLI command. Console `:parse` only. |
+| `detail` | `string` | Raw RouterOS parse diagnostic. Console `:parse` only. |
+
+Console `:parse` may also put RouterOS' byte location in the top-level
+`error.position` field. On older RouterOS versions, an unknown name can produce
+only a generic syntax diagnostic; that is reported as `validation/syntax`
+because no parameter identity is available.
+
+Provenance:
+
+- `src/api.ts:988,1033` — REST/native `validateApiRequest` (print vs add/set branches)
+- `src/execute.ts:742` — REST `validateRestExecute`
+- `src/retrieve.ts:233` — REST `retrieve` attribute projection
+- `src/protocols/mac-telnet-console.ts:674` — console `:parse` (`bad parameter <name>`) over mac-telnet/ssh
+- `src/core/routeros-errors.ts:128` — `!trap`/`detail` `unknown parameter <name>` (routeros/unknown-attribute sibling)
 
 ## 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/unknown-attribute`.
+For `retrieve` and inspect-gated API/execute validation, check the name against
+`/console/inspect`; `retrieve --list-attributes` lists the available properties.
+For console `:parse`, compare `context.parameter` with the RouterOS parameters
+for `context.command`; `context.detail` preserves the device's raw diagnostic.
+Use `--validate=false` only when intentionally probing an undocumented RouterOS
+edge.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -9,21 +9,22 @@
 	},
 	"homepage": "https://github.com/tikoci/centrs#readme",
 	"bugs": "https://github.com/tikoci/centrs/issues",
-	"packageManager": "bun@1.3.13",
+	"packageManager": "bun@1.3.14",
+	"license": "MIT",
 	"devDependencies": {
-		"@agent-lint/cli": "^0.8.1",
-		"@biomejs/biome": "2.5.1",
+		"@biomejs/biome": "2.5.7",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
-		"@tikoci/quickchr": "^0.4.2",
 		"@types/bun": "^1.3.13",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.0.0",
 		"has-flag": "4.0.0",
-		"markdownlint-cli2": "^0.22.1",
+		"markdownlint-cli2": "^0.23.0",
 		"secretlint": "^13.0.2",
 		"typedoc": "^0.28.19"
 	},
-	"optionalDependencies": {},
+	"optionalDependencies": {
+		"@tikoci/quickchr": "^0.4.7"
+	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
 	},
@@ -46,22 +47,24 @@
 	"files": [
 		"src/",
 		"commands/",
+		"docs/CLI.md",
 		"docs/CONSTITUTION.md",
 		"docs/MATRIX.md",
 		"docs/errors/",
 		"README.md",
 		"CHANGELOG.md",
 		"SECURITY.md",
+		"LICENSE",
 		"GLOSSARY.txt"
 	],
 	"scripts": {
-		"ci": "bun run lint && bun run test && bun run build",
-		"git:pre-commit": "bun run lint",
+		"ci": "bun run lint:ci && bun run test && bun run build",
+		"git:pre-commit": "bun run lint:git:commit",
 		"git:pre-push": "bun run lint:git:push",
 		"lint": "bun run lint:biome && bun run lint:typecheck",
-		"lint:git:commit": "bun run lint",
-		"lint:git:push": "bun run lint:ci && bun run test && bun run build",
-		"lint:ci": "bun run lint && bun run lint:markdownlint && bun run lint:cspell && bun run lint:secretlint",
+		"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:cspell": "cspell lint . --gitignore",
 		"lint:cspell:all": "cspell lint . --no-gitignore",
 		"lint:markdownlint": "markdownlint-cli2 \"**/*.md\" \"!.scratch/**\"",
@@ -70,10 +73,10 @@
 		"lint:biome": "biome check .",
 		"lint:fix": "biome check --write .",
 		"lint:secretlint": "secretlint \"**/*\"",
-		"lint:agents": "agent-lint scan --stdout",
 		"test": "bun test",
 		"test:smoke": "bun test test/integration/cli-smoke.test.ts",
-		"test:integration:fast": "bun test test/integration/devices.test.ts",
+		"test:integration:fast": "bun test test/integration/devices.test.ts test/integration/settings.test.ts",
+		"test:integration:settings": "bun test test/integration/settings.test.ts",
 		"test:integration:smoke": "CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/chr-smoke.test.ts",
 		"test:integration": "CENTRS_RUN_FAST_INTEGRATION=1 bun test test/integration/",
 		"test:integration:stable": "CENTRS_CHR_CHANNEL=stable bun run test:integration",
@@ -82,9 +85,41 @@
 		"test:integration:development": "CENTRS_CHR_CHANNEL=development bun run test:integration",
 		"test:ci": "bun test --coverage",
 		"test:all": "bun run test:ci",
+		"check:agent": "bun run scripts/agent-check.ts",
+		"corpus:fetch": "bun run scripts/corpus-fetch.ts",
 		"build": "bun build src/index.ts src/cli.ts src/mcp.ts src/tui.ts src/webproxy.ts src/protocols/index.ts --outdir dist --target bun",
 		"build:doc:api": "typedoc --out docs/api src/index.ts",
+		"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: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-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",
+		"explain:operator-census:check": "bun run scripts/explain-operator-census.ts --check",
+		"explain:operator-readme": "bun run scripts/explain-operator-slice.ts --readme",
+		"explain:operator-readme:check": "bun run scripts/explain-operator-slice.ts --readme --check",
+		"explain:operator-slice": "bun run scripts/explain-operator-slice.ts",
+		"explain:probe:brace-slots": "bun run scripts/probes/explain-brace-slot-sweep.ts",
+		"explain:probe:escapes": "bun run scripts/probes/explain-escape-sweep.ts",
+		"explain:probe:highlight-recapture": "bun run scripts/probes/explain-highlight-recapture.ts",
+		"explain:probe:operators": "bun run scripts/probes/explain-operator-sweep.ts",
+		"explain:probe:symbol-anchors": "bun run scripts/probes/explain-symbol-anchors.ts",
+		"explain:probe:symbol-arms-score": "bun run scripts/probes/explain-symbol-arms-score.ts",
+		"explain:probe:symbol-bad-sigil-replay": "bun run scripts/probes/explain-symbol-bad-sigil-replay.ts",
+		"explain:probe:symbol-classes-replay": "bun run scripts/probes/explain-symbol-classes-replay.ts",
+		"explain:probe:version-floors": "bun run scripts/probes/explain-version-floors.ts",
+		"explain:menus:check": "bun run scripts/gen-explain-menus.ts --check",
+		"explain:value-census": "bun run scripts/explain-value-census.ts",
+		"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: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",
+		"explain:token-census:readme:check": "bun run scripts/explain-token-census.ts --readme --check",
 		"security": "bun run lint:secretlint && bun run lint:markdownlint"
 	},
 	"type": "module",