@warlock.js/core 5.30.0 → 5.31.0

package/skills/validate-input/SKILL.md

@@ -5,7 +5,7 @@ description: 'Author seal schemas, attach them to controllers via `controller.va
 
 # Warlock — validate a request
 
-Validation is a three-file pattern: a seal schema, a `Request<Schema>` type alias, and the controller that attaches the schema via a static property. If validation fails, the framework returns a 400 with an `errors` payload — your handler never runs.
+Validation is a three-file pattern: a seal schema, a `Request<Schema>` type alias, and the controller that attaches the schema via a static property. If validation fails, the framework returns a 422 with an `errors` payload — your handler never runs (see "Your own failure body" to change it).
 
 ## The shape
 
@@ -53,29 +53,29 @@ Scaffold with `npx warlock generate.controller <module>/<action> --with-validati
 
 From `@warlock.js/seal` — **always import from seal directly**. `@warlock.js/core` does not re-export `v`/`Infer`.
 
-| Factory                            | Output type                  | Common chain                                     |
-| ---------------------------------- | ---------------------------- | ------------------------------------------------ |
-| `v.string(msg?)`                   | `string`                     | `.min(n)`, `.max(n)`, `.length(n)`, `.pattern(re)`, `.email()`, `.url()`, `.oneOf([...])`, `.trim()`, `.lowercase()`, `.uppercase()` |
-| `v.email(msg?)`                    | `string`                     | (alias of `v.string().email()`)                  |
-| `v.number(msg?)`                   | `number`                     | `.min(n)`, `.max(n)`, `.positive()`              |
-| `v.numeric(msg?)`                  | `number` (accepts numeric strings) | same                                        |
-| `v.int(msg?)`                      | `number` (integer)           | same                                             |
-| `v.float(msg?)`                    | `number`                     | same                                             |
-| `v.boolean(msg?)`                  | `boolean`                    | —                                                |
-| `v.date(msg?)`                     | `Date`                       | —                                                |
-| `v.array(inner, msg?)`             | `T[]`                        | `.minLength(n)`, `.maxLength(n)`                 |
-| `v.object(shape, msg?)`            | `{ ... }`                    | —                                                |
-| `v.record(value, msg?)`            | `Record<string, T>`          | —                                                |
-| `v.tuple([a, b, c], msg?)`         | `[A, B, C]`                  | —                                                |
-| `v.union([a, b], msg?)`            | `A | B`                      | —                                                |
-| `v.discriminatedUnion(key, [...])` | `A | B` (tagged)             | each branch must be `v.object({ key: v.literal(...) })` |
-| `v.enum([...] | EnumObj, msg?)`    | literal union                | —                                                |
-| `v.literal(...values)`             | exact literals               | —                                                |
-| `v.instanceof(Ctor, msg?)`         | `Ctor` instances             | —                                                |
-| `v.lazy(() => schema)`             | recursive/forward refs       | —                                                |
-| `v.file(msg?)`                     | `UploadedFile`               | `.image()`, `.accept(exts)`, `.mimeType(types)`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(n)`, `.maxWidth(n)` — see the `upload-file` topic |
-| `v.computed(callback)`             | derived value                | —                                                |
-| `v.managed(callback)`              | framework-injected value     | —                                                |
+| Factory                            | Output type                        | Common chain                                                                                                                                |
+| ---------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `v.string(msg?)`                   | `string`                           | `.min(n)`, `.max(n)`, `.length(n)`, `.pattern(re)`, `.email()`, `.url()`, `.oneOf([...])`, `.trim()`, `.lowercase()`, `.uppercase()`        |
+| `v.email(msg?)`                    | `string`                           | (alias of `v.string().email()`)                                                                                                             |
+| `v.number(msg?)`                   | `number`                           | `.min(n)`, `.max(n)`, `.positive()`                                                                                                         |
+| `v.numeric(msg?)`                  | `number` (accepts numeric strings) | same                                                                                                                                        |
+| `v.int(msg?)`                      | `number` (integer)                 | same                                                                                                                                        |
+| `v.float(msg?)`                    | `number`                           | same                                                                                                                                        |
+| `v.boolean(msg?)`                  | `boolean`                          | —                                                                                                                                           |
+| `v.date(msg?)`                     | `Date`                             | —                                                                                                                                           |
+| `v.array(inner, msg?)`             | `T[]`                              | `.minLength(n)`, `.maxLength(n)`                                                                                                            |
+| `v.object(shape, msg?)`            | `{ ... }`                          | —                                                                                                                                           |
+| `v.record(value, msg?)`            | `Record<string, T>`                | —                                                                                                                                           |
+| `v.tuple([a, b, c], msg?)`         | `[A, B, C]`                        | —                                                                                                                                           |
+| `v.union([a, b], msg?)`            | `A                                 | B`                                                                                                                                          | —                                                       |
+| `v.discriminatedUnion(key, [...])` | `A                                 | B` (tagged)                                                                                                                                 | each branch must be `v.object({ key: v.literal(...) })` |
+| `v.enum([...]                      | EnumObj, msg?)`                    | literal union                                                                                                                               | —                                                       |
+| `v.literal(...values)`             | exact literals                     | —                                                                                                                                           |
+| `v.instanceof(Ctor, msg?)`         | `Ctor` instances                   | —                                                                                                                                           |
+| `v.lazy(() => schema)`             | recursive/forward refs             | —                                                                                                                                           |
+| `v.file(msg?)`                     | `UploadedFile`                     | `.image()`, `.accept(exts)`, `.mimeType(types)`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(n)`, `.maxWidth(n)` — see the `upload-file` topic |
+| `v.computed(callback)`             | derived value                      | —                                                                                                                                           |
+| `v.managed(callback)`              | framework-injected value           | —                                                                                                                                           |
 
 Universal modifiers from `BaseValidator`: `.optional()`, `.nullable()`, `.default(value)`, `.catch(value)`. Note: **there is no `v.url(...)`** at factory level — use `v.string().url(...)`.
 
@@ -187,18 +187,59 @@ const updateAvatarSchema = v.object({
 
 The framework calls `response.failedSchema(result)` which sends `422` by default (set `validation.response.status` to change it) with the shape configured under `validation.response` (defaults shown):
 
-```jsonc
-// 422 Unprocessable Entity
+```json
 {
   "errors": [
     { "input": "email", "error": "The email must be a valid email" },
-    { "input": "password", "error": "The password must be at least 6 characters" },
+    { "input": "password", "error": "The password must be at least 6 characters" }
   ]
 }
 ```
 
 The key names (`errors`, `input`, `error`) come from `config.get("validation.response")` — change them globally if your wire format differs.
 
+### Your own failure body
+
+For a contract with stable error codes, set `onFailure` on the validation. It gets the seal result and `{ request, response, route }` and returns `{ status?, body }` (no `status` → `validation.response.status`, 422):
+
+```ts title="src/app/imports/controllers/create-import.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+import { v } from "@warlock.js/seal";
+
+const importSchema = v.object({ name: v.string().required() });
+
+export const createImportController: RequestHandler = async ({ response }) =>
+  response.successCreate({ id: "import-1" });
+
+createImportController.validation = {
+  schema: importSchema,
+  onFailure: () => ({ status: 400, body: { error: "IMPORT_REQUEST_INVALID" } }),
+};
+
+// Declare the failure status so `warlock generate.openapi` documents the body.
+createImportController.responseSchema = {
+  201: { body: { id: "string" } },
+  400: { body: { error: "string" } },
+};
+```
+
+The same `validation` object is accepted as a route option, merged over the handler's (route keys win): `router.post("/imports", createImportController, { validation: { onFailure } })`.
+
+For every route at once, configure a global hook; a route's `onFailure` still wins, and returning `undefined` from either falls through to the next:
+
+```ts title="src/config/validation.ts"
+import type { ValidationConfiguration } from "@warlock.js/core";
+
+const validationConfig: ValidationConfiguration = {
+  response: {
+    status: 400,
+    body: (result, route) => ({ error: `${route.name}.invalid`, fields: result.errors.length }),
+  },
+};
+
+export default validationConfig;
+```
+
 ## Scoping what's validated
 
 By default the validator merges `request.body + request.query` (everything but route params) and validates the merged object. To narrow:
@@ -219,6 +260,9 @@ For background jobs, CLI commands, or anywhere outside the HTTP path, call `vali
 ```ts
 import { v } from "@warlock.js/seal";
 
+const createProductSchema = v.object({ name: v.string().required(), price: v.number().min(0) });
+declare const untrustedInput: unknown; // a queue payload, a webhook body, a CSV row…
+
 const result = await v.validate(createProductSchema, untrustedInput);
 
 if (!result.isValid) {
@@ -296,7 +340,7 @@ updateProductController.validation = {
 ## Gotchas
 
 - **`v.url(...)` does not exist on the factory.** Use `v.string().url(...)`. Same goes for any other rule that's not in the table above — check `BaseValidator` / `StringValidator` first.
-- **`.optional()` and `.required()` are not symmetric.** `.optional()` brands the field as absent-allowed. `.required()` clears the optional flag *and* replaces any prior required rule — read seal's `BaseValidator` source if you need conditional required.
+- **`.optional()` and `.required()` are not symmetric.** `.optional()` brands the field as absent-allowed. `.required()` clears the optional flag _and_ replaces any prior required rule — read seal's `BaseValidator` source if you need conditional required.
 - **`uniqueExceptCurrentId` reads `request.input("id")`.** It only works inside an HTTP context — useless in CLI/job code.
 - **`request.validated()` is empty until the framework runs validation.** If you forgot the `controller.validation = { schema }` line, `validated()` returns `{}` (or the input from `setValidatedData` if you set it manually). Always pair the schema with the assignment.
 - **Import `v`/`Infer` from `@warlock.js/seal`.** Core does not re-export them — `@warlock.js/seal` is the canonical and only home.

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,132 @@
+---
+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
+
+- 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.