@warlock.js/core 5.30.0 → 5.32.0

package/skills/warlock-agents-md/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: warlock-agents-md
+description: 'Generate the app-specific section of AGENTS.md from the booted app with `warlock agents-md [--write] [--json]` — modules, a routes summary with unguarded writes flagged, models, the conventions `warlock check` enforces, the installed skills and the verify commands — between `<!-- warlock:generated:start -->` / `<!-- warlock:generated:end -->` markers so hand-written content is never touched; `warlock dev` refreshes it (opt out with `devServer.agentsMd: false`). Triggers: `warlock agents-md`, `AGENTS.md`, `warlock:generated:start`, `renderAgentsMdSection`, `writeAgentsMd`, `upsertGeneratedSection`, `listInstalledSkills`, `createAgentsMdRefresher`, `devServer.agentsMd`, `WL7501`; "give agents the app facts", "keep AGENTS.md up to date", "which skills apply to this app". Skip: the full machine-readable report — the `warlock-inspect` topic; verifying a change — the `warlock-check` topic.'
+---
+
+# Warlock — `warlock agents-md`
+
+Write the facts an agent needs about **this** app into `AGENTS.md`, from the booted registries, and keep them current.
+
+```bash
+npx warlock agents-md            # print the section
+npx warlock agents-md --write    # write it into AGENTS.md (created when missing)
+npx warlock agents-md --json     # { file, status, section }
+```
+
+It boots like `warlock inspect` (connectors booted, none started — no connection, no port).
+
+## What it writes
+
+Between two marker lines, appended at the end of an existing file without markers:
+
+```md
+# Notes written by hand — never touched
+
+<!-- warlock:generated:start -->
+
+## blog 1.2.0 — generated facts
+
+### Modules
+
+| Module | Routes | Models |
+...
+
+### Routes
+
+4 route(s): 2 GET, 1 POST, 1 PATCH.
+Mutating routes without an auth guard (confirm each is meant to be public): `POST /posts`.
+...
+<!-- warlock:generated:end -->
+```
+
+Sections: app + `@warlock.js/*` versions, modules (`src/app/*`, routes/models per module), routes (counts, unguarded writes, a list capped at 60), models (table, module), conventions in force (`WL9001`–`WL9004` and the layout rules), installed skills (`node_modules/@warlock.js/*/skills/*/SKILL.md`, first sentence each), verify commands. No timestamps: an unchanged app regenerates the same bytes and nothing is written.
+
+## Rules
+
+- Only bytes between the markers change; a CRLF file stays CRLF.
+- Malformed markers (one missing, duplicated, end before start) → `WL7501`, nothing written. Fix by hand.
+- Put your own notes outside the markers; anything inside is replaced on the next refresh.
+
+## `warlock dev` keeps it fresh
+
+On boot and after reloads that change routes or modules (debounced). Opt out:
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: { agentsMd: false },
+});
+```
+
+## From code
+
+```ts
+import {
+  createAgentsMdRefresher,
+  inspectApp,
+  listInstalledSkills,
+  renderAgentsMdSection,
+  upsertGeneratedSection,
+  writeAgentsMd,
+} from "@warlock.js/core/tooling";
+
+const report = await inspectApp({ sections: ["routes", "models", "packages"] });
+
+const section = renderAgentsMdSection(report, { skills: listInstalledSkills(process.cwd()) });
+const next = upsertGeneratedSection("# Hand notes\n", section); // pure: returns the new file content
+
+const { status } = writeAgentsMd({ report }); // "created" | "updated" | "unchanged"
+
+const refresher = createAgentsMdRefresher({
+  collect: () => inspectApp({ sections: ["routes", "models", "packages"] }),
+  debounceMs: 1000,
+  onError: (error) => console.warn(error),
+});
+
+refresher.schedule(); // debounced
+await refresher.flush(); // run now
+refresher.dispose();
+```
+
+## See also
+
+- The `warlock-inspect` topic — the report the section is built from.
+- The `warlock-check` topic — the verify command the section points at.
+- The `warlock-conventions` topic — the conventions listed in the section.

package/skills/warlock-board/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: warlock-board
+description: 'Coordinate two coding agents (an implementer and a reviewer) through `warlock board`: work items with a review state machine (todo, in-progress, ready-for-review, changes-requested, approved, blocked), append-only numbered messages per recipient in the git-ignored `.warlock/board/`, `VERDICT: APPROVED` / `VERDICT: CHANGES REQUESTED` lines that move the item, and a blocking `watch` with a timeout; `--json` on every action. Triggers: `warlock board`, `board init`, `board add`, `board status`, `board send`, `board watch`, `--verdict`, `WARLOCK_AGENT`, `.warlock/board`, `to-reviewer/`, `initBoard`, `addBoardItem`, `moveBoardItem`, `sendBoardMessage`, `watchBoard`, `readBoardStatus`, `WL7401`, `WL7402`, `WL7403`, `WL7404`; "hand this to the reviewer agent", "wait for the review", "two agents working together", "request changes", "approve the item". Skip: verifying the code itself — the `warlock-check` topic; app facts — the `warlock-inspect` topic.'
+---
+
+# Warlock — `warlock board`
+
+A shared folder of plain files two agents use to hand work back and forth: **items** move through review states, **messages** are appended to the other agent's inbox, and `watch` blocks until something new arrives. Set `WARLOCK_AGENT` to your agent name so `--from` / `--by` default to it.
+
+```bash
+export WARLOCK_AGENT=implementer
+npx warlock board init
+npx warlock board add "Add the orders module" --assignee implementer --reviewer reviewer --json
+npx warlock board status --json
+```
+
+## The loop
+
+Implementer:
+
+```bash
+npx warlock board status 1 in-progress
+# write the code; loop on `npx warlock check --changed --json` until it is clean
+npx warlock board status 1 ready-for-review --note "check passes"
+npx warlock board send reviewer "Orders module ready" --item 1 --body @handoff.md
+npx warlock board watch implementer --timeout 1800 --json   # blocks for the verdict
+```
+
+Reviewer (`WARLOCK_AGENT=reviewer`):
+
+```bash
+npx warlock board watch reviewer --timeout 1800 --json
+# review the diff, run `npx warlock check --changed --json`
+npx warlock board send implementer "Review of orders" --item 1 --verdict changes-requested --body @review.md
+# or, when it is right:
+npx warlock board send implementer "Approved" --item 1 --verdict approved
+```
+
+On `changes-requested` the implementer moves the item back with `status 1 in-progress`, fixes, moves it to `ready-for-review` and sends a new message. The loop ends on `approved`.
+
+## States
+
+| From                | Allowed next                                   |
+| ------------------- | ---------------------------------------------- |
+| `todo`              | `in-progress`, `blocked`                       |
+| `in-progress`       | `ready-for-review`, `blocked`, `todo`          |
+| `ready-for-review`  | `approved`, `changes-requested`, `in-progress` |
+| `changes-requested` | `in-progress`, `blocked`                       |
+| `approved`          | `in-progress` (reopen)                         |
+| `blocked`           | `todo`, `in-progress`                          |
+
+Anything else fails with `WL7403`, and the message lists the allowed states. `npx warlock board status <id> --json` returns `{ item, next }`.
+
+## Reading what `watch` returns
+
+```json
+{
+  "ok": true,
+  "timedOut": false,
+  "agent": "implementer",
+  "cursor": 3,
+  "messages": [
+    {
+      "number": 3,
+      "file": ".warlock/board/to-implementer/0003-review-of-orders.md",
+      "from": "reviewer",
+      "to": "implementer",
+      "item": 1,
+      "subject": "Review of orders",
+      "at": "2026-10-17T09:12:44.512Z",
+      "body": "Wrap the list response in OrderResource.",
+      "verdict": "changes-requested"
+    }
+  ]
+}
+```
+
+- Every unread message comes back at once, oldest first, and the cursor moves past them. `--since 0` replays the inbox.
+- Timeout: exit code **3** and `{ "ok": false, "code": "WL7404", "timedOut": true }`. Just run `watch` again.
+- A message file ends with exactly `VERDICT: APPROVED` or `VERDICT: CHANGES REQUESTED` when it carries a verdict.
+
+## From code
+
+```ts
+import {
+  initBoard,
+  addBoardItem,
+  moveBoardItem,
+  sendBoardMessage,
+  watchBoard,
+} from "@warlock.js/core/tooling";
+
+initBoard();
+const item = addBoardItem({
+  title: "Add the orders module",
+  assignee: "implementer",
+  reviewer: "reviewer",
+});
+moveBoardItem(item.id, "in-progress", { by: "implementer" });
+moveBoardItem(item.id, "ready-for-review", { by: "implementer" });
+sendBoardMessage({
+  to: "reviewer",
+  from: "implementer",
+  subject: "Ready",
+  item: item.id,
+  body: "See the diff.",
+});
+
+const { messages } = await watchBoard({ agent: "implementer", timeoutMs: 30 * 60_000 });
+```
+
+## Gotchas
+
+- Run `init` first; every other action fails with `WL7401` until the board exists. `init` git-ignores `.warlock/board/`.
+- Messages are append-only and numbered per inbox; never edit or delete one by hand — send a new message.
+- A verdict naming an item moves it; if the item is not in `ready-for-review`, the send fails with `WL7403` and no message is written.
+- Agent names: lower-case letters, digits and dashes.
+- `@mongez/agent-kit` lives outside this repository; it integrates by calling these commands.
+
+## See also
+
+- The `warlock-check` topic — the verify command both agents loop on.
+- The `warlock-inspect` topic — the app's facts as JSON before you change it.

package/skills/warlock-check/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: warlock-check
+description: 'Verify a change with one command: `warlock check [--changed] [--json]` runs an incremental typecheck, the app''s ESLint/oxlint, the tests affected by the change and framework convention checks, and reports one JSON object per problem `{ code, category, severity, source, file, line, column, message, hint, skill, docs, rule }` with exit 1 for problems in your code and 2 for problems with this machine (missing Redis/DB, busy port, Node version, missing tool). Also `warlock typecheck [--changed]`, `warlock explain <CODE>` and the stable `WL` error codes (`errorCodeOf`, `WarlockError`). Triggers: `warlock check`, `warlock typecheck`, `warlock explain`, `--changed`, `--base`, `runCheck`, `runTypecheck`, `CHECK_EXIT_CODES`, `ToolingProblem`, `WL7101`, `WL8003`, `errorCodeOf`, `explainErrorCode`, `WarlockError`, "verify my change", "run the checks", "is this failure my code or the machine", "what does WL3001 mean", "typecheck only changed files". Skip: app diagnostics at boot — the `warlock-doctor` topic; reading the app''s routes/models — the `warlock-inspect` topic; writing tests — the `test-http` / `test-service` topics.'
+---
+
+# Warlock — `warlock check`, `typecheck`, `explain`
+
+Run `warlock check` after every change and loop on it until it exits 0.
+
+```bash
+npx warlock check --changed --json    # inner loop: only what changed vs HEAD (+ untracked)
+npx warlock check --base main         # what changed since the branch left main
+npx warlock check                     # everything, before you finish
+npx warlock check --skip tests        # steps: environment, typecheck, lint, tests, conventions
+```
+
+## Exit codes
+
+| Exit | Meaning                                                 | What to do                                                                                                      |
+| ---- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `0`  | no errors (warnings allowed)                            | done                                                                                                            |
+| `1`  | problems **in your code**                               | fix each problem at `file:line:column`                                                                          |
+| `2`  | a problem with **this machine** — the run is incomplete | fix the environment (start Redis/DB, free the port, switch Node, install the tool); do **not** edit code for it |
+
+`2` wins when both kinds exist. Each problem's `category` (`code` / `environment`) says the same per problem.
+
+## One problem
+
+```json
+{
+  "code": "WL8003",
+  "category": "environment",
+  "severity": "error",
+  "source": "environment",
+  "file": "src/app/posts/publish.spec.ts",
+  "line": null,
+  "column": null,
+  "message": "Error: connect ECONNREFUSED 127.0.0.1:6379",
+  "hint": "Start the service named in the message (database, Redis, ...) or point the config at a running one.",
+  "skill": "warlock-check",
+  "docs": "https://warlock.js.org/v/latest/core/cli/error-codes/#wl8003",
+  "rule": "publish caches the post"
+}
+```
+
+```bash
+npx warlock check --changed --json > check.json; code=$?
+jq -r '.problems[] | "\(.file // "-"):\(.line // 0) \(.code) \(.message)\n  → \(.hint)"' check.json
+[ "$code" = 2 ] && echo "environment problem — fix the machine, not the code"
+```
+
+| Code                | Problem                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `WL7101`            | type error (`rule` = `TS2322`, …)                                                                             |
+| `WL7102`            | tsconfig missing/invalid                                                                                      |
+| `WL7201` / `WL7202` | lint error / warning (`rule` = the rule id)                                                                   |
+| `WL7301` / `WL7302` | a test failed / a test file failed to load                                                                    |
+| `WL9001`            | imports an auto-loaded file (`routes.ts`, `main.ts`, `worker.ts`, `events/*`)                                 |
+| `WL9002`            | relative import ends in `.js`                                                                                 |
+| `WL9003`            | relative import into another `src/app/<module>` — use `app/<module>/...`                                      |
+| `WL9004`            | `experimentalDecorators: true` in tsconfig                                                                    |
+| `WL9005`            | `request.all()` passed to a query, a service or `inApp()` — use `request.validated()`                         |
+| `WL9006`            | POST/PUT/PATCH/DELETE route with no auth middleware and no `public: true`                                     |
+| `WL9007`            | redirect / `navigateTo()` / `<Link to>` target from request input without `safeRedirect()`                    |
+| `WL9008`            | raw email, credential or request body in a log call                                                           |
+| `WL9009`            | regex with `*` / `+` / `{n,}` run on request input                                                            |
+| `WL9010`–`WL9012`   | warnings: `await log.*()`, a second controller in a file, a `kind` discriminator                              |
+| `WL8001`–`WL8007`   | this machine: Node version, missing tool, unreachable service, busy port, esbuild binary, git, tool crash/OOM |
+
+## `warlock typecheck`
+
+```bash
+npx warlock typecheck                 # whole program, incremental (.warlock/cache/typecheck.tsbuildinfo)
+npx warlock typecheck --changed       # changed files + the files importing them
+npx warlock typecheck --json --project tsconfig.app.json
+```
+
+`--changed` checks the changed files and their direct importers only; a full run (cheap after the first, it is incremental) catches anything further away.
+
+## `warlock explain`
+
+```bash
+npx warlock explain WL3001          # title, fix, skill, docs link
+npx warlock explain WL3001 --json   # the registry entry
+npx warlock explain                 # every code
+```
+
+## Error codes in code
+
+Framework errors carry a stable `code`; read any thrown value with `errorCodeOf()` (it also maps `ECONNREFUSED` → `WL8003`, `EADDRINUSE` / `PortInUseError` → `WL8004`, and follows `cause`):
+
+```ts
+import { errorCodeOf, explainErrorCode, router, WarlockError } from "@warlock.js/core";
+
+try {
+  router.getRoute("posts.show", {});
+} catch (error) {
+  const code = errorCodeOf(error); // "WL3003" (unknown route name) or "WL3004" (missing param)
+  console.error(code, code && explainErrorCode(code)?.fix);
+}
+
+// Throw a coded framework error from a connector or plugin:
+throw new WarlockError("WL2003", "search connector failed to boot: SEARCH_URL is not set");
+```
+
+## From code
+
+```ts
+import { CHECK_EXIT_CODES, runCheck, runTypecheck } from "@warlock.js/core/tooling";
+
+const report = await runCheck({ changed: true });
+
+if (report.exitCode === CHECK_EXIT_CODES.environment) {
+  // tell the user which service/tool is missing; don't touch the code
+}
+
+const types = runTypecheck({ files: ["src/app/posts/services/publish.service.ts"] });
+```
+
+## Gotchas
+
+- `check` boots nothing — no config, no connection, no port — so it runs the same with or without services; only tests that need them fail, and those report `WL8003`/`WL8004`.
+- Lint runs only the linters the app configures (`eslint.config.*`; an oxlint config + the `oxlint` package). No config → the step is skipped, not failed.
+- Tests use the app's own vitest (`vitest run`, or `vitest related <files> --run` with `--changed`). Test files without vitest installed → `WL8002`.
+- The typecheck runs in a child `warlock typecheck` process; running out of memory is reported as `WL8007` instead of ending the run.
+- The convention checks are the framework's own and run the same with ESLint, Oxlint or no linter. A deliberate exception gets `// warlock-check-ignore WL9006 -- why` on the problem's line or the line above (no code = every code on that line).
+
+## See also
+
+- `report-framework-issue.md` — confirm a framework bug or missing capability, collect `warlock issue` output, and get the user's approval before filing.
+- The `warlock-doctor` topic — boot-time diagnostics; `doctor --json` uses the same codes and fields.
+- The `warlock-inspect` topic — the app's routes, models and config as JSON.
+- The `warlock-conventions` topic — the rules behind `WL9001`–`WL9012`, with the fix for each.

package/skills/warlock-conventions/SKILL.md

@@ -130,8 +130,123 @@ Within the same module, use relative paths (`./`, `../`).
 
 Cascade uses `@RegisterModel()` for the model registry and `@BelongsTo` / `@HasMany` / `@MorphTo` for relations. The scaffolded `tsconfig.json` has `"experimentalDecorators": false` — these are native Stage-3 decorators, not legacy. Never set that flag to `true`; see the `lower-stage3-decorators` topic.
 
+## What `warlock check` enforces
+
+`npx warlock check` (the `warlock-check` topic) reports these with a stable code. They run the same whatever linter the app uses.
+
+| Code     | Rule                                                                                              |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| `WL9001` | never import an auto-loaded file (fact 2)                                                         |
+| `WL9002` | no `.js` extension on a relative import                                                           |
+| `WL9003` | cross-module imports use `app/<module>/...` (see Path aliases)                                    |
+| `WL9004` | no `"experimentalDecorators": true`                                                               |
+| `WL9005` | queries, services and `inApp()` get `request.validated()`, never `request.all()`                  |
+| `WL9006` | every POST/PUT/PATCH/DELETE route is guarded or says `public: true`                               |
+| `WL9007` | redirect and link targets from request input go through `safeRedirect()` / `safeRedirectTarget()` |
+| `WL9008` | no raw email, credential or request body in a log call                                            |
+| `WL9009` | regexes run on request input have bounded quantifiers                                             |
+| `WL9010` | warning: no `await` on `log.info()` and its siblings                                              |
+| `WL9011` | warning: one controller per file                                                                  |
+| `WL9012` | warning: a tagged union's discriminator is `type`, not `kind`                                     |
+
+### `WL9005` — validated input only
+
+`request.all()` hands every client-sent field to whatever receives it (mass assignment). Declare a schema and pass what it accepted:
+
+```ts
+import { type RequestHandler } from "@warlock.js/core";
+import { v } from "@warlock.js/seal";
+
+const createPostSchema = v.object({ title: v.string(), body: v.string() });
+
+async function createPostService(input: { title: string; body: string }) {
+  return { id: 1, ...input };
+}
+
+export const createPostController: RequestHandler = async ({ request, response }) => {
+  const post = await createPostService(request.validated());
+  return response.successCreate({ post });
+};
+
+createPostController.validation = { schema: createPostSchema };
+```
+
+### `WL9006` — guarded or public
+
+```ts
+import { authMiddleware } from "@warlock.js/auth";
+import { router, type RequestHandler } from "@warlock.js/core";
+
+const createPostController: RequestHandler = async ({ response }) => response.successCreate({});
+const contactController: RequestHandler = async ({ response }) => response.success({ sent: true });
+
+router.post("/posts", createPostController, { middleware: [authMiddleware("user")] });
+
+// Intentionally open: say so.
+router.post("/contact", contactController, { public: true });
+```
+
+A route inside `guarded(() => …)` or `router.group({ middleware: [authMiddleware()] }, …)` is guarded. A middleware counts as a guard when its name contains `auth` or `guard`, or when it is a constant initialised with `markAuthGuard()` in the same file. `warlock dev` warns about the same routes at runtime.
+
+### `WL9007` — safe redirects
+
+```ts
+import { safeRedirect, type RequestHandler } from "@warlock.js/core";
+
+export const afterLoginController: RequestHandler = async ({ request, response }) => {
+  return response.redirect(
+    safeRedirect(request.input("next"), { allowedOrigins: ["https://app.example.com"] }),
+  );
+};
+```
+
+In pages, `safeRedirectTarget(target) ?? "/"` from `@warlock.js/web` does the same for `navigateTo()` and `<Link to>`. A target checked by an enclosing `if (isSafeRedirect(target))` passes.
+
+### `WL9008` — redacted logs
+
+```ts
+import type { Request } from "@warlock.js/core";
+import { log, maskEmail } from "@warlock.js/logger";
+
+export function logLogin(request: Request, user: { id: number; email: string }, token: string) {
+  log.info("auth", "login", `Signed in ${maskEmail(user.email)}`, {
+    userId: user.id,
+    token, // `token` is a key the logger censors by default
+    request: request.toLogSnapshot(),
+  });
+}
+```
+
+Keys the logger censors by default (`token`, `password`, `apiKey`, `authorization`, …) may carry secrets as structured data. Emails are not censored by default, so they always need `maskEmail()`. Free text from the client goes through `escapeLogValue()`.
+
+### `WL9009` — bounded regexes on input
+
+```ts
+const SLUG = /^[a-z0-9-]{1,64}$/;
+
+export function isSlug(value: string): boolean {
+  return SLUG.test(value);
+}
+```
+
+Bound each repetition (`{1,64}`, not `+`) or cap the input's length before matching.
+
+### `WL9010`–`WL9012`
+
+Drop the `await` from `log.info(…)` (`await log.flush()` waits for delivery); move each extra controller into its own `<name>.controller.ts`; rename a union's `kind` tag to `type` and update the `switch`.
+
+### A deliberate exception
+
+```ts
+// warlock-check-ignore WL9006 -- authenticated by the provider's signature header
+router.post("/webhooks/billing", billingWebhookController, { middleware: [verifySignature()] });
+```
+
+The comment covers the codes it names on its own line and the next; with no code it covers every code there.
+
 ## See also
 
+- The `warlock-check` topic — running the checks and reading the report.
 - The `register-route` topic — how to wire URLs to controllers.
 - The `create-controller` topic — controller signature, validation, response shape.
 - The `send-response` topic — the full Response helper surface.

package/skills/warlock-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warlock-doctor
-description: 'Run `warlock doctor` — a read-only diagnostics command that checks routes / config / connectors / optional-peers / health endpoints / release hygiene and prints a pass/warn/fail report, exiting non-zero on any failure. Add your own probe with the `DoctorCheck` contract and `runChecks` / `formatReportLines`. Triggers: `warlock doctor`, `doctorCommand`, `DoctorCheck`, `CheckResult`, `CheckStatus`, `DoctorReport`, `runChecks`, `formatReportLines`, `printReport`, `defaultDoctorChecks`; "diagnose my app", "preflight / preflight check", "is the app healthy", "why are there 0 routes", "pre-release sanity check", "CI smoke check"; run as `npx warlock doctor`. Skip: the live `/health` + `/ready` HTTP probes — the `health-checks` topic; authoring a general CLI command — the `write-cli-command` topic; releasing the package — `releasing-warlock-monorepo`; competing tools `npm doctor`, `nest info`, hand-rolled preflight scripts.'
+description: 'Run `warlock doctor` — a read-only diagnostics command that checks routes / config / connectors / optional-peers / health endpoints / release hygiene and prints a pass/warn/fail report, exiting non-zero on any failure. Add your own probe with the `DoctorCheck` contract and `runChecks` / `formatReportLines`. Triggers: `warlock doctor`, `warlock doctor --json`, `toDoctorJson`, `WL1001`, `doctorCommand`, `DoctorCheck`, `CheckResult`, `CheckStatus`, `DoctorReport`, `runChecks`, `formatReportLines`, `printReport`, `defaultDoctorChecks`; "diagnose my app", "preflight / preflight check", "is the app healthy", "why are there 0 routes", "pre-release sanity check", "CI smoke check"; run as `npx warlock doctor`. Skip: the live `/health` + `/ready` HTTP probes — the `health-checks` topic; authoring a general CLI command — the `write-cli-command` topic; releasing the package — `releasing-warlock-monorepo`; competing tools `npm doctor`, `nest info`, hand-rolled preflight scripts.'
 ---
 
 # Warlock — `warlock doctor`
@@ -22,23 +22,53 @@ npx warlock doctor
 Summary: 5 ok, 1 warn, 0 fail
 ```
 
+## Error codes and `--json`
+
+Every `warn`/`fail` finding carries a stable error code (`WL1001`, `WL2001`, …), printed after the detail and explained by `warlock explain <code>`. `--json` prints the report with the same `code` / `hint` / `skill` / `docs` fields `warlock check --json` uses (boot output goes to stderr):
+
+```bash
+npx warlock doctor --json | jq '.results[] | select(.status != "ok") | "\(.code) \(.detail)"'
+npx warlock explain WL1001
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "results": [
+    {
+      "name": "config",
+      "status": "fail",
+      "detail": "missing required config section(s): http",
+      "code": "WL1001",
+      "hint": "Add the missing file under src/config/ (for example src/config/app.ts) exporting the section.",
+      "skill": "configure-app",
+      "docs": "https://warlock.js.org/v/latest/core/cli/error-codes/#wl1001"
+    }
+  ],
+  "summary": { "ok": 0, "warn": 0, "fail": 1 },
+  "exitCode": 1
+}
+```
+
+A custom check sets `code` on its non-ok results the same way (`{ name, status: "fail", code: "WL2003", detail }`); `ok` results carry none.
+
 ## What it checks
 
 The default set is `defaultDoctorChecks` (in registration order — runtime-surface checks first, release hygiene last):
 
-| Check | `ok` | `warn` | `fail` |
-| --- | --- | --- | --- |
-| `routes` | ≥ 1 route registered | 0 routes (a route module likely failed to load) | — |
-| `config` | required sections (`app`, `http`) present | — | a required section is missing |
-| `connectors` | manager enumerable; reports registered + active set | — | (only if the probe itself throws) |
-| `optional-peers` | every known optional peer installed | a peer is missing → its feature is unavailable | — |
-| `jwt-secret` | `auth.userType` configured and a JWT signing secret set | — | `auth.userType` is configured but no signing secret (`auth.accessToken.secret` / `auth.jwt.secret`) is set |
-| `health` | `/health` + `/ready` will be exposed | `http.health.enabled = false` (probes off) | — |
-| `release-hygiene` | `package.json` version matches the top `## x.y.z` CHANGELOG heading | no `CHANGELOG.md`, or no parseable heading | version ≠ top heading |
+| Check             | `ok`                                                                | `warn`                                          | `fail`                                                                                                     |
+| ----------------- | ------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `routes`          | ≥ 1 route registered                                                | 0 routes (a route module likely failed to load) | —                                                                                                          |
+| `config`          | required sections (`app`, `http`) present                           | —                                               | a required section is missing                                                                              |
+| `connectors`      | manager enumerable; reports registered + active set                 | —                                               | (only if the probe itself throws)                                                                          |
+| `optional-peers`  | every known optional peer installed                                 | a peer is missing → its feature is unavailable  | —                                                                                                          |
+| `jwt-secret`      | `auth.userType` configured and a JWT signing secret set             | —                                               | `auth.userType` is configured but no signing secret (`auth.accessToken.secret` / `auth.jwt.secret`) is set |
+| `health`          | `/health` + `/ready` will be exposed                                | `http.health.enabled = false` (probes off)      | —                                                                                                          |
+| `release-hygiene` | `package.json` version matches the top `## x.y.z` CHANGELOG heading | no `CHANGELOG.md`, or no parseable heading      | version ≠ top heading                                                                                      |
 
 `jwt-secret` is the pre-flight form of the silent first-login 500: when `auth.userType` is set but no signing secret is, every login and token operation fails with a generic 500 at runtime — `doctor` turns that into a `fail` before you ship. It resolves the secret from both the current key (`auth.accessToken.secret`) and the legacy `auth.jwt.secret`, so a project on the older-but-supported shape doesn't trip it. When `auth.userType` isn't configured at all (no auth), the check emits **no line** — it's skipped, not a pass — so it never nags a project that isn't doing auth.
 
-Optional peers are resolved from the **consuming app's** `node_modules` (via `createRequire(process.cwd())`), so the report reflects what *your* project has installed, not core's own deps.
+Optional peers are resolved from the **consuming app's** `node_modules` (via `createRequire(process.cwd())`), so the report reflects what _your_ project has installed, not core's own deps.
 
 ## Exit code
 
@@ -55,21 +85,22 @@ any fail    → exit 1   (so CI / a release script can gate on it)
 type CheckStatus = "ok" | "warn" | "fail";
 
 type CheckResult = {
-  name: string;     // stable check name, e.g. "routes"
+  name: string; // stable check name, e.g. "routes"
   status: CheckStatus;
-  detail: string;   // one-line, user-facing explanation
+  detail: string; // one-line, user-facing explanation
+  code?: WarlockErrorCode; // stable code of a warn/fail verdict, e.g. "WL1001"
 };
 
 type DoctorCheck = {
   name: string;
-  run: () => CheckResult | Promise<CheckResult>;   // MUST be read-only
+  run: () => CheckResult | Promise<CheckResult>; // MUST be read-only
 };
 
 type DoctorReport = {
-  results: CheckResult[];                 // in registration order
-  summary: Record<CheckStatus, number>;   // counts per status
-  hasFailures: boolean;                   // true iff any fail
-  exitCode: 0 | 1;                        // 1 when hasFailures, else 0
+  results: CheckResult[]; // in registration order
+  summary: Record<CheckStatus, number>; // counts per status
+  hasFailures: boolean; // true iff any fail
+  exitCode: 0 | 1; // 1 when hasFailures, else 0
 };
 ```
 
@@ -91,7 +122,7 @@ import {
 const migrationsCheck: DoctorCheck = {
   name: "migrations",
   async run() {
-    const pending = await countPendingMigrations();   // your read-only probe
+    const pending = await countPendingMigrations(); // your read-only probe
 
     return pending === 0
       ? { name: "migrations", status: "ok", detail: "no pending migrations" }
@@ -101,8 +132,8 @@ const migrationsCheck: DoctorCheck = {
 
 const report = await runChecks([...defaultDoctorChecks, migrationsCheck]);
 
-printReport(report);                  // colored, to stdout
-const lines = formatReportLines(report);   // plain strings — snapshot-friendly
+printReport(report); // colored, to stdout
+const lines = formatReportLines(report); // plain strings — snapshot-friendly
 
 if (report.hasFailures) process.exit(report.exitCode);
 ```
@@ -125,7 +156,7 @@ A `⚠ routes: 0 routes registered` line is the tell that a route module threw o
 
 ## Gotchas
 
-- **`doctor` starts no connectors.** It intentionally does not open DB / cache / socket connections — the `connectors` check reports the *registered* set and which are already active, without forcing any up. Don't expect it to detect a down database.
+- **`doctor` starts no connectors.** It intentionally does not open DB / cache / socket connections — the `connectors` check reports the _registered_ set and which are already active, without forcing any up. Don't expect it to detect a down database.
 - **Optional-peers resolves from the project, not core.** A peer installed only inside core's own `node_modules` still reports as missing — the probe uses `process.cwd()`.
 - **Warnings don't fail the command.** Only a `fail` flips the exit code. Missing optional peers and disabled health endpoints are deliberate-choice `warn`s.
 - **Custom checks must stay read-only.** `run()` runs against a booted-but-not-connected app; mutating state or opening a connection breaks the contract and can hang the command.
@@ -136,3 +167,5 @@ A `⚠ routes: 0 routes registered` line is the tell that a route module threw o
 - The `write-cli-command` topic — authoring a command + its `preload` plan, the shape `doctorCommand` is built from.
 - The `add-connector` topic — connector registration, which the `connectors` check enumerates.
 - The `warlock-conventions` topic — project layout the checks assume.
+- The `warlock-check` topic — `warlock check` / `typecheck` / `explain` and the error-code registry the findings use.
+- The `warlock-inspect` topic — `warlock inspect`, the same boot pass printed as a versioned JSON report of the app.