@tikoci/centrs 0.1.0

package/docs/errors/README.md

@@ -0,0 +1,74 @@
+# centrs error pages
+
+Each `CentrsError` carries a `details_url` of the form
+`https://tikoci.github.io/centrs/errors/<code>`. This directory holds the
+human-readable page for each code, and is the home for the **error URL scheme**
+and the **RouterOS-fault mapping** (below); the constitution keeps only the
+one-line contract.
+
+## URL scheme
+
+`details_url` is `https://tikoci.github.io/centrs/errors/<code>`, with `<code>`
+the slash-namespaced code as-is (e.g.
+`https://tikoci.github.io/centrs/errors/routeros/unsupported-path`).
+
+- The URL is normalized; the GitHub Pages site routes it to a human page — **not**
+  the typedoc URL (typedoc lives elsewhere).
+- Adding an error code requires adding a Pages entry under the same path: code and
+  page ship together, and a missing page is a centrs bug.
+- The URL must stay **stable across centrs versions**; if a code is renamed, the
+  old URL must redirect.
+
+## Source of truth and the contributor contract
+
+The enumerable list of every code lives in code, not here:
+[`src/core/error-catalog.ts`](../../src/core/error-catalog.ts). The per-code
+pages in this directory are generated from it (`bun run docs:errors`, which
+only scaffolds missing pages and never overwrites hand-enriched ones).
+
+When you introduce a new error code you must, in the same change:
+
+1. add an entry to `src/core/error-catalog.ts`, and
+2. add a `docs/errors/<code>.md` page (run `bun run docs:errors`).
+
+`test/unit/error-pages.test.ts` enforces this three-way consistency — every live
+`code:` literal is cataloged, every catalogued code has a page, and no page is
+orphaned. A missing page is a centrs bug, so the guard fails the build.
+
+## Families
+
+Codes are slash-namespaced `family/slug`. The families and where they originate:
+
+- `auth/*` — credential rejection.
+- `cdb/*` — WinBox CDB load, parse, decrypt, mutation, and allowlist policy
+  (`src/data/`, `src/devices.ts`, `src/resolver/cdb.ts`).
+- `discover/*` — MNDP discovery (`src/discover.ts`).
+- `identity/*` — target → CDB record resolution (`src/resolver/`).
+- `input/*` — malformed caller input (paths, MACs, arguments).
+- `internal/*` — centrs bugs / unreachable states.
+- `mndp/*` — MNDP wire codec and listener (`src/data/mndp.ts`).
+- `routeros/*` — RouterOS-surfaced faults mapped by the grounded vocabulary in
+  `src/core/routeros-errors.ts` (REST `detail` and native-api `!trap`, identical
+  on CHR 7.23).
+- `settings/*` — settings/value parsing (`src/resolver/settings.ts`).
+- `target/*` — turning a `<router>` into a transport endpoint.
+- `transport/*` — connection, TLS, DNS, and timeout plumbing.
+- `usage/*` — how a command was invoked (arity, conflicting flags, confirmation).
+- `validation/*` — the canonicalize → validate gate (`:parse` + `/console/inspect`).
+
+The hand-enriched pages (richer trigger strings and remediation) currently are
+the `routeros/*` set produced by `src/core/routeros-errors.ts` and the
+`target/*` MAC-resolution pages; the rest are generated stubs to be enriched as
+each code is grounded.
+
+## RouterOS-fault mapping (`routeros/*`)
+
+The authoritative vocabulary for `routeros/*` is the live router's own strings
+(grounded on CHR 7.23): the REST `detail` field on HTTP ≥400 — shape
+`{"detail":"<msg>","error":<http-status>,"message":"<http reason>"}` — and the
+native-api `!trap` carry the **same** text for the same fault, so one shared
+table (`src/core/routeros-errors.ts`) maps both transports. The original string
+is always preserved — in `context.detail` for a matched rule, and in `cause` for
+the catch-all (`routeros/request-failed`). Ground new mappings on CHR evidence,
+not assumption (`tikoci/m2ir` is protocol-IR reference, not an accessible mapping
+source — the router strings are).

package/docs/errors/auth/failed.md

@@ -0,0 +1,9 @@
+# `auth/failed`
+
+RouterOS rejected the stored credentials for the device.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `auth/failed`.

package/docs/errors/cdb/already-exists.md

@@ -0,0 +1,9 @@
+# `cdb/already-exists`
+
+A CDB entry with that target already exists.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/already-exists`.

package/docs/errors/cdb/created.md

@@ -0,0 +1,9 @@
+# `cdb/created`
+
+A new CDB file was created at the resolved location.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/created`.

package/docs/errors/cdb/decrypt-failed.md

@@ -0,0 +1,9 @@
+# `cdb/decrypt-failed`
+
+The encrypted CDB could not be decrypted (wrong or missing password).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/decrypt-failed`.

package/docs/errors/cdb/empty-group.md

@@ -0,0 +1,9 @@
+# `cdb/empty-group`
+
+The named CDB group contains no records.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/empty-group`.

package/docs/errors/cdb/invalid-option.md

@@ -0,0 +1,9 @@
+# `cdb/invalid-option`
+
+A comment kv-soup option carried 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 `cdb/invalid-option`.

package/docs/errors/cdb/invalid-record.md

@@ -0,0 +1,9 @@
+# `cdb/invalid-record`
+
+A device record failed schema validation (blank target or wrong field type).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/invalid-record`.

package/docs/errors/cdb/not-found-target.md

@@ -0,0 +1,9 @@
+# `cdb/not-found-target`
+
+No CDB entry matched the requested target string.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/not-found-target`.

package/docs/errors/cdb/not-found.md

@@ -0,0 +1,9 @@
+# `cdb/not-found`
+
+The CDB file could not be found.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/not-found`.

package/docs/errors/cdb/override-applied.md

@@ -0,0 +1,9 @@
+# `cdb/override-applied`
+
+A comment kv-soup override replaced a resolved setting (informational).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/override-applied`.

package/docs/errors/cdb/parse-failed.md

@@ -0,0 +1,9 @@
+# `cdb/parse-failed`
+
+The CDB file could not be parsed.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/parse-failed`.

package/docs/errors/cdb/password-not-needed.md

@@ -0,0 +1,9 @@
+# `cdb/password-not-needed`
+
+A --cdb-password was supplied for an unencrypted CDB and was ignored.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/password-not-needed`.

package/docs/errors/cdb/password-required.md

@@ -0,0 +1,9 @@
+# `cdb/password-required`
+
+The CDB is encrypted; a --cdb-password is required to read it.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/password-required`.

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

@@ -0,0 +1,9 @@
+# `cdb/reserved-key`
+
+Comment kv-soup cannot carry a first-class CDB field.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/reserved-key`.

package/docs/errors/cdb/reserved-option.md

@@ -0,0 +1,9 @@
+# `cdb/reserved-option`
+
+A reserved comment kv-soup option was rejected.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/reserved-option`.

package/docs/errors/cdb/target-not-registered.md

@@ -0,0 +1,9 @@
+# `cdb/target-not-registered`
+
+The target is not on the CDB allowlist. Register it with centrs_devices (op add) first.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/target-not-registered`.

package/docs/errors/cdb/unknown-field.md

@@ -0,0 +1,9 @@
+# `cdb/unknown-field`
+
+An unknown CDB field name was referenced.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/unknown-field`.

package/docs/errors/cdb/unknown-option.md

@@ -0,0 +1,9 @@
+# `cdb/unknown-option`
+
+An unknown comment kv-soup option was encountered.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/unknown-option`.

package/docs/errors/cdb/write-not-permitted.md

@@ -0,0 +1,9 @@
+# `cdb/write-not-permitted`
+
+The device's CDB record is mcp=ro; MCP writes are not permitted until it is set to mcp=rw.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `cdb/write-not-permitted`.

package/docs/errors/discover/broadcast-unavailable.md

@@ -0,0 +1,9 @@
+# `discover/broadcast-unavailable`
+
+The MNDP listener could not enable UDP broadcast; discovery continued passively without sending refresh probes.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `discover/broadcast-unavailable`.

package/docs/errors/discover/failed.md

@@ -0,0 +1,9 @@
+# `discover/failed`
+
+MNDP discovery failed.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `discover/failed`.

package/docs/errors/identity/ambiguous.md

@@ -0,0 +1,9 @@
+# `identity/ambiguous`
+
+The target matches more than one CDB entry.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `identity/ambiguous`.

package/docs/errors/identity/no-match.md

@@ -0,0 +1,9 @@
+# `identity/no-match`
+
+The target has no CDB entry matching the requested record type.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `identity/no-match`.

package/docs/errors/input/invalid-command.md

@@ -0,0 +1,9 @@
+# `input/invalid-command`
+
+The request shape was invalid (bad or missing arguments).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-command`.

package/docs/errors/input/invalid-match.md

@@ -0,0 +1,9 @@
+# `input/invalid-match`
+
+The --match value is not a known CDB record type.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-match`.

package/docs/errors/input/invalid-path.md

@@ -0,0 +1,9 @@
+# `input/invalid-path`
+
+A file path contains a character the transport cannot quote (e.g. a quote or newline).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-path`.

package/docs/errors/input/invalid-routeros-path.md

@@ -0,0 +1,9 @@
+# `input/invalid-routeros-path`
+
+The RouterOS path is malformed (it must be slash-prefixed).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-routeros-path`.

package/docs/errors/input/invalid-target.md

@@ -0,0 +1,9 @@
+# `input/invalid-target`
+
+The target string is invalid for the requested operation.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/invalid-target`.

package/docs/errors/input/local-file-not-found.md

@@ -0,0 +1,9 @@
+# `input/local-file-not-found`
+
+A local file required for the transfer could not be read.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/local-file-not-found`.

package/docs/errors/input/mac-address.md

@@ -0,0 +1,9 @@
+# `input/mac-address`
+
+The value is not a valid 6-octet MAC address.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/mac-address`.

package/docs/errors/input/max-results-exceeded.md

@@ -0,0 +1,9 @@
+# `input/max-results-exceeded`
+
+Output exceeded the requested byte budget.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `input/max-results-exceeded`.

package/docs/errors/internal/devices-failed.md

@@ -0,0 +1,9 @@
+# `internal/devices-failed`
+
+The devices command failed with an unexpected internal error.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/devices-failed`.

package/docs/errors/internal/mcp-start.md

@@ -0,0 +1,9 @@
+# `internal/mcp-start`
+
+The MCP server failed to start.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/mcp-start`.

package/docs/errors/internal/mcp-tool.md

@@ -0,0 +1,9 @@
+# `internal/mcp-tool`
+
+An MCP tool handler failed with an unexpected internal error.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/mcp-tool`.

package/docs/errors/internal/native-api-length.md

@@ -0,0 +1,9 @@
+# `internal/native-api-length`
+
+A native-API word length could not be encoded.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/native-api-length`.

package/docs/errors/internal/unhandled.md

@@ -0,0 +1,9 @@
+# `internal/unhandled`
+
+An unexpected internal error occurred (this is a centrs bug).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/unhandled`.

package/docs/errors/internal/unreachable.md

@@ -0,0 +1,9 @@
+# `internal/unreachable`
+
+An unreachable code path was reached (this is a centrs bug).
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `internal/unreachable`.

package/docs/errors/mndp/encode-failed.md

@@ -0,0 +1,9 @@
+# `mndp/encode-failed`
+
+An MNDP field could not be encoded.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `mndp/encode-failed`.

package/docs/errors/mndp/listen-failed.md

@@ -0,0 +1,9 @@
+# `mndp/listen-failed`
+
+The MNDP UDP listener could not bind.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `mndp/listen-failed`.

package/docs/errors/mndp/malformed.md

@@ -0,0 +1,9 @@
+# `mndp/malformed`
+
+A received MNDP datagram could not be decoded.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `mndp/malformed`.

package/docs/errors/routeros/api-fatal.md

@@ -0,0 +1,9 @@
+# `routeros/api-fatal`
+
+The RouterOS native API returned a fatal sentence.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/api-fatal`.

package/docs/errors/routeros/api-protocol.md

@@ -0,0 +1,9 @@
+# `routeros/api-protocol`
+
+A RouterOS native API reply could not be parsed.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/api-protocol`.

package/docs/errors/routeros/api-trap.md

@@ -0,0 +1,9 @@
+# `routeros/api-trap`
+
+The RouterOS native API returned a !trap with no more specific mapping.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/api-trap`.

package/docs/errors/routeros/btest-protocol.md

@@ -0,0 +1,12 @@
+# `routeros/btest-protocol`
+
+A bandwidth-test (btest) packet could not be decoded.
+
+## Fix
+
+The peer sent a malformed or unexpected btest control/data packet (a bad command
+packet, EC-SRP5 auth frame, status message, or UDP datagram). Confirm the remote
+end is a MikroTik `/tool/bandwidth-server` (or a btest client) on the expected
+port, and that nothing else is answering on TCP/UDP 2000. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error contract and
+`commands/btest/README.md` for the protocol.

package/docs/errors/routeros/btest-too-many-sessions.md

@@ -0,0 +1,9 @@
+# `routeros/btest-too-many-sessions`
+
+The btest server refused a client because `max-sessions` is reached.
+
+## Fix
+
+Wait for an in-flight bandwidth test to finish, or start the centrs btest server
+with a higher `--max-sessions` (RouterOS allows `1..1000`, default `100`). See
+`commands/btest/README.md` and [`docs/CONSTITUTION.md`](../../CONSTITUTION.md).

package/docs/errors/routeros/command-failed.md

@@ -0,0 +1,14 @@
+# `routeros/command-failed`
+
+A generic RouterOS command failure. RouterOS reports these as a `failure: <msg>`
+string; the inner message is preserved in `context.failure` and the original
+string in `context.detail`.
+
+## Typical RouterOS strings
+
+- `failure: <msg>` (for example, `failure: already have such entry`)
+
+## Fix
+
+Inspect the RouterOS failure message, then adjust the path, attributes, or
+request shape accordingly.

package/docs/errors/routeros/ec-srp5-protocol.md

@@ -0,0 +1,11 @@
+# `routeros/ec-srp5-protocol`
+
+An EC-SRP5 authentication message or key could not be processed.
+
+## Fix
+
+The peer sent a malformed EC-SRP5 public key, an out-of-range value, or the
+shared-secret computation degenerated (the point at infinity). This is the shared
+EC-SRP5 layer used by both MAC-Telnet (MTWEI) and the bandwidth test (btest);
+confirm the remote end is a genuine MikroTik device and retry. See
+[`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error contract.

package/docs/errors/routeros/error.md

@@ -0,0 +1,9 @@
+# `routeros/error`
+
+RouterOS returned an error executing the command.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/error`.

package/docs/errors/routeros/invalid-value.md

@@ -0,0 +1,14 @@
+# `routeros/invalid-value`
+
+RouterOS rejected the value supplied for an argument. The offending argument
+name is captured in `context.argument`.
+
+## Typical RouterOS strings
+
+- `invalid value for argument <name>`
+- `invalid value of <name>`
+
+## Fix
+
+Supply a value that matches the argument's expected type/format for this
+RouterOS path.

package/docs/errors/routeros/mac-telnet-error.md

@@ -0,0 +1,9 @@
+# `routeros/mac-telnet-error`
+
+The device reported a MAC-Telnet error.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/mac-telnet-error`.

package/docs/errors/routeros/mac-telnet-not-ready.md

@@ -0,0 +1,9 @@
+# `routeros/mac-telnet-not-ready`
+
+Input was sent before the MAC-Telnet session was ready.
+
+## Fix
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
+contract. This stub will be expanded with the typical trigger and remediation
+for `routeros/mac-telnet-not-ready`.