@warlock.js/core 5.24.0 → 5.26.0

package/llms-full.txt

@@ -618,8 +618,8 @@ export class UsersRestful extends Restful<User> implements RouteResource {
   public validation = {
     create: {
       schema: v.object({
-        name: v.string().required().min(2),
-        email: v.email().required(),
+        name: v.string().min(2),
+        email: v.email(),
       }),
     },
     update: {
@@ -1197,6 +1197,8 @@ Same shape — TS validates the union; runtime picks the `default` key.
 - `socket.adapter` — adapter factory for cross-server broadcast.
 - `cache.silenceSingleServerWarning`, `storage.silenceSingleServerWarning`, `socket.silenceSingleServerWarning` — silence the production warnings for in-memory cache, local storage, and adapter-less sockets.
 
+`http.modelValidationErrorStatus` sets the status for a Cascade model-write validation failure (a model failing its own schema on save). It defaults to `500` with an opaque body, because request input is already validated with a `422` before the model is touched. Set a `4xx` (e.g. `422`) to treat it as a client error instead; the response then carries `{ errors }`.
+
 ## Per-env knobs
 
 For one-off switches gated on environment, the canonical pattern is `Application.isProduction` (also `isDevelopment`, `isTest`):
@@ -1380,6 +1382,10 @@ Two pieces:
 
 If validation fails, the framework returns a 400 with an `errors` payload and your handler never runs.
 
+### Validating route params
+
+`handler.validation = { params: v.object({ id: v.int().min(1) }) }` validates path segments (e.g. `/posts/:id`). Number and boolean validators convert the string segments; the app's schema object is never changed. Parsed values replace `request.params` (`request.input("id")` is a number) and merge into `request.validated()`, with params winning over body fields. Failures answer like a `schema` failure.
+
 ### Typing a guarded handler
 
 Routes behind `authMiddleware` need `request.locals.user` typed. Project conventions add a `GuardedRequest<TSchema>` (overriding `locals` to `RequestLocals & { user: User }`) and a paired `GuardedRequestHandler<TSchema>` alias in `app/auth/requests/guarded.request`:
@@ -1934,6 +1940,10 @@ export class Product extends Model {
 
 This is convention, not a framework requirement. Controllers/services that import the resource explicitly work the same way.
 
+### `id` and Mongo `_id`
+
+The output `id` falls back to `_id` when the record has no `id`; an explicit `id` always wins. If a collection uses native ObjectIds, set `public primaryKey = "_id"` on the model so `Model.find(hex)` resolves the `id` your resource emits.
+
 ## Output-only rule
 
 Resources map fields. They do not:
@@ -3148,6 +3158,7 @@ type TracingContext = {
 type TracingPhaseInfo = {
   name: string;
   durationMs: number;
+  startedAt?: number; // epoch milliseconds; supplied when the phase started
   attrs?: Record<string, unknown>;
 };
 
@@ -3166,29 +3177,52 @@ type TracingHooks = {
 
 Every verb is optional — a hook that only wants phase spans need not implement
 `onRequestStart`/`onRequestEnd`. Register as many hooks as you like via
-`hooks: TracingHooks[]`; each fires independently.
+`hooks: TracingHooks[]`; each fires independently. Use `registerTracingHooks()`
+when the observer is installed by application code rather than static config:
+
+```ts
+import { registerTracingHooks, type TracingHooks } from "@warlock.js/core";
+
+const hooks: TracingHooks = {
+  onPhase(ctx, phase) {
+    console.log(ctx.traceId, phase.name, phase.startedAt);
+  },
+};
+
+const unregister = registerTracingHooks(hooks);
+// Later, for example during plugin teardown:
+unregister();
+```
+
+`registerTracingHooks(hooks): () => void` enables tracing immediately. Runtime
+hooks run after configured hooks; calling the returned unregister function more
+than once is safe. When a phase did not provide `startedAt`, the dispatcher
+derives it from its duration before delivering the callback.
 
 ## Phase names
 
 `core` wires five phases into the request lifecycle, in this order, for every
 HTTP request:
 
-| Phase | Fires around |
-| --- | --- |
-| `route.match` | Resolving the incoming path/method to a registered route |
-| `middleware` | Each middleware in the route's chain — one `onPhase` call per middleware, with `attrs: { name, index }` |
-| `validation` | The route's input validation (`v.object(...)` / RESTful resource validation) |
-| `handler` | The route handler itself |
+| Phase            | Fires around                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `route.match`    | Resolving the incoming path/method to a registered route                                                                           |
+| `middleware`     | Each middleware in the route's chain — one `onPhase` call per middleware, with `attrs: { name, index }`                            |
+| `validation`     | The route's input validation (`v.object(...)` / RESTful resource validation)                                                       |
+| `handler`        | The route handler itself                                                                                                           |
 | `response.write` | The overall request span, closed once the response has settled (success or thrown error) — this is also where `onRequestEnd` fires |
 
 `@warlock.js/web` page requests report through this same `onPhase` surface
 instead of adding a separate hook API. They add three phases:
 
-| Phase | Fires around |
-| --- | --- |
-| `loader` | Each loader level, once per app/layout/page, with `attrs: { level, layoutPath? }` |
-| `render.shell` | Time from render start until React's shell is ready to stream |
-| `stream.end` | The whole streamed response, including every `defer()` value settling |
+| Phase             | Fires around                                                                                        |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `loader`          | Each loader level, once per app/layout/page, with `attrs: { level, layoutPath? }`                   |
+| `render.shell`    | Time from render start until React's shell is ready to stream                                       |
+| `stream.end`      | The whole streamed response, including every `defer()` value settling                               |
+| `page.middleware` | Page middleware chain; `attrs: { count, outcome }`, where outcome is `next`, `response`, or `error` |
+| `page.cache`      | Page-cache lookup; `attrs: { status }`, where status is `hit`, `miss`, or `bypass`                  |
+| `defer.settle`    | A deferred key settling; `attrs: { key, status }`, where status is `fulfilled` or `rejected`        |
 
 ## Trace id derivation
 
@@ -3282,9 +3316,8 @@ export default {
 - **No OTel dependency, and none planned for `core`.** An OTel (or other
   vendor) bridge is a separate, optional package that subscribes to these
   hooks — never add `@opentelemetry/api` to `core` itself.
-- **`web`'s phases aren't live yet.** Don't register a hook expecting
-  `loader`/`render.shell`/`stream.end` calls today; only the five `core`
-  phases fire in this release.
+- **Web phases share the same hook.** Do not create a second page-tracing
+  integration: subscribe with `TracingHooks.onPhase`.
 - **`route` is `undefined` until routing has matched.** There's no path where
   a hook fires before that, but code branching on `ctx.route` for an
   early-failing request (e.g. a 404 with no match) must handle `undefined`.
@@ -3620,11 +3653,11 @@ Boots the framework in dev mode: file watcher, HMR-style module reload, on-disk
 
 ### Flags
 
-| Flag                  | Default | Purpose                                                                                                  |
-| --------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| Flag                  | Default | Purpose                                                                                                     |
+| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
 | `--fresh, -f`         | off     | Delete `.warlock/manifest.json` before start — forces a full re-parse from disk. Use after odd boot states. |
-| `--skip-typings, -st` | off     | Skip background type generation **for this run**. Overrides `devServer.generateTypings` config.           |
-| `--skip-health, -sh`  | off     | Skip file health checkers **for this run**. Overrides `devServer.healthCheckers` config.                  |
+| `--skip-typings, -st` | off     | Skip background type generation **for this run**. Overrides `devServer.generateTypings` config.             |
+| `--skip-health, -sh`  | off     | Skip file health checkers **for this run**. Overrides `devServer.healthCheckers` config.                    |
 
 When a flag is **not** passed, the corresponding `warlock.config.ts > devServer.*` value applies. When passed, the flag wins.
 
@@ -3632,14 +3665,14 @@ When a flag is **not** passed, the corresponding `warlock.config.ts > devServer.
 
 Once the server is ready, `warlock dev` listens for single keypresses:
 
-| Key      | Does                                                                       |
-| -------- | ---------------------------------------------------------------------------- |
-| `r`      | Restart the server on a fresh process.                                     |
-| `c`      | Clear the console.                                                         |
-| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                    |
-| `h`      | Print the shortcuts that are armed right now.                              |
+| Key      | Does                                                                                                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `r`      | Restart the server on a fresh process.                                                                                                                                  |
+| `c`      | Clear the console.                                                                                                                                                      |
+| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                                                                                                                |
+| `h`      | Print the shortcuts that are armed right now.                                                                                                                           |
 | `u`      | **Only while an update notice is showing** — update every `@warlock.js/*` package, install, and restart. See [`update-packages/SKILL.md`](../update-packages/SKILL.md). |
-| `Ctrl+C` | Graceful shutdown, unchanged.                                              |
+| `Ctrl+C` | Graceful shutdown, unchanged.                                                                                                                                           |
 
 A "restart" is a fresh process (`r` and `u` both use it) — see [The supervisor](#the-supervisor) below for how that works.
 
@@ -3659,7 +3692,7 @@ shell
 
 The supervisor spawns the worker with `stdio: "inherit"` and mirrors its exit code. To restart, the worker shuts down cleanly — freeing the http port — and exits `75`; the supervisor spawns a replacement. **The tree never gets deeper**, however many restarts happen.
 
-The supervisor is chosen in the `dev` command's `preAction`, which runs *before* the preloaders — deliberately, so the supervisor never loads config or starts connectors. A supervisor holding a second database connection open for the session would be a real bug, not a cosmetic one.
+The supervisor is chosen in the `dev` command's `preAction`, which runs _before_ the preloaders — deliberately, so the supervisor never loads config or starts connectors. A supervisor holding a second database connection open for the session would be a real bug, not a cosmetic one.
 
 Signals: `SIGINT` reaches the worker directly (same process group), so the supervisor ignores it and only notes that the next exit is final — acting on it would exit the parent while the worker was still draining. `SIGTERM` / `SIGHUP` are forwarded explicitly, since they don't propagate to the group on Windows. After any worker exits, the supervisor puts stdin back out of raw mode in case the worker was killed before it could.
 
@@ -3673,13 +3706,13 @@ A worker that dies **after running healthily for at least 5s** — OOM, a native
 14:31:02 Development server was killed by SIGSEGV — restarting.
 ```
 
-A worker that dies *sooner* than that failed to **boot** — a broken config, a port already taken — and it has already printed why. Restarting there would just reprint the same error and bury it, so the supervisor mirrors the exit code and stops.
+A worker that dies _sooner_ than that failed to **boot** — a broken config, a port already taken — and it has already printed why. Restarting there would just reprint the same error and bury it, so the supervisor mirrors the exit code and stops.
 
-A busy port is now caught *before* the bind attempt: the HTTP connector calls `assertPortIsAvailable(port, host)` immediately before `listen()`, so the failure is `Port <port> is already in use on <host>. Stop the dev server (or whatever else is listening on port <port>) and run again, or start on a free port…` — not a raw `EADDRINUSE` surfacing from inside Fastify. Same connector, same preflight, for `warlock start`.
+A busy port is now caught _before_ the bind attempt: the HTTP connector calls `assertPortIsAvailable(port, host)` immediately before `listen()`, so the failure is `Port <port> is already in use on <host>. Stop the dev server (or whatever else is listening on port <port>) and run again, or start on a free port…` — not a raw `EADDRINUSE` surfacing from inside Fastify. Same connector, same preflight, for `warlock start`.
 
 Flapping is capped: more than 3 crashes inside 60s and the supervisor gives up rather than restarting behind your back.
 
-An explicit restart (`r`, `u`, a config change) is a *request*, not a crash, so the uptime rule never swallows it.
+An explicit restart (`r`, `u`, a config change) is a _request_, not a crash, so the uptime rule never swallows it.
 
 ### Restart on config change
 
@@ -3695,7 +3728,7 @@ Set `devServer.restartOnConfigChange: false` for the previous behaviour (a warni
 
 On first boot `warlock dev` bundles its ESM loader hook and writes it to **your project's** `.warlock/loader-hook.mjs` — the hook runs in a fresh Node worker thread with no TypeScript loader of its own, so it has to be plain, pre-bundled ESM.
 
-Because that file lives in your directory rather than core's, every npm import inside it is rewritten at generation time to an **absolute path resolved from core's own install**. A bare `import "esbuild"` there would resolve from *your* `node_modules`, and `esbuild` / `get-tsconfig` are core's dependencies, not yours.
+Because that file lives in your directory rather than core's, every npm import inside it is rewritten at generation time to an **absolute path resolved from core's own install**. A bare `import "esbuild"` there would resolve from _your_ `node_modules`, and `esbuild` / `get-tsconfig` are core's dependencies, not yours.
 
 :::note[Fixed in 4.9.2 — pnpm users]
 Before 4.9.2 those imports were left bare. npm and yarn hoist every transitive dependency into one flat tree, so they resolved by accident; pnpm's strict layout does not, and the dev server failed with `ERR_MODULE_NOT_FOUND: Cannot find package 'esbuild'`. The workaround was declaring `esbuild` and `get-tsconfig` in your own `package.json` — no longer needed, and you can drop them.
@@ -3757,12 +3790,13 @@ esbuild bundle of the app down to a single JS file in `dist/`. No flags — ever
 ```ts title="warlock.config.ts"
 export default defineConfig({
   build: {
-    outdir: "dist",        // default — relative or absolute
-    outFile: "app.js",            // default — bundle filename
-    minify: true,                 // default — esbuild minify
-    sourcemap: true,              // default — true | false | "inline" | "linked"
-    singleBundle: false,          // default — one runnable file, deps inlined
-    esmShim: true,                // default — require/__filename/__dirname for bundled CJS
+    outdir: "dist", // default — relative or absolute
+    outFile: "app.js", // default — bundle filename
+    minify: true, // default — esbuild minify
+    sourcemap: true, // default — true | false | "inline" | "linked"
+    singleBundle: false, // default — one runnable file, deps inlined
+    esmShim: true, // default — require/__filename/__dirname for bundled CJS
+    routeRegistrationTimeoutMs: 30_000, // default — route-registration child deadline
   },
 });
 ```
@@ -3774,8 +3808,9 @@ Defaults are sensible for the typical "Node service" deployment. Knobs to actual
 - **`minify: false`** — flip to debug a production-only bug. Larger bundle, readable stack traces.
 - **`sourcemap: "inline"`** — embed the source map in the bundle. Useful when your error reporter only captures the bundle and can't fetch a `.map` sidecar.
 - **`sourcemap: false`** — skip source maps entirely. Smaller artifact, but stack traces in production logs lose their file:line precision (and `warlock start` will not enable `--enable-source-maps` since there's nothing to map).
-- **`singleBundle: true`** — inline dependencies so `node dist/app.js` runs with no `node_modules` and no launcher. Sets `packages: "bundle"` + `splitting: false` as **defaults you can override**. ⚠ Native `.node` addons are still emitted alongside — "single bundle" is one JS file *plus* any native addons. Do NOT reach for it as the default: keeping deps external is right when you deploy the folder.
+- **`singleBundle: true`** — inline dependencies so `node dist/app.js` runs with no `node_modules` and no launcher. Sets `packages: "bundle"` + `splitting: false` as **defaults you can override**. ⚠ Native `.node` addons are still emitted alongside — "single bundle" is one JS file _plus_ any native addons. Do NOT reach for it as the default: keeping deps external is right when you deploy the folder.
 - **`esmShim: false`** — only if you are certain nothing in the graph is CommonJS. Leave it on.
+- **`routeRegistrationTimeoutMs`** — increase on busy CI runners when static route registration needs more than 30 seconds. `WARLOCK_ROUTE_REGISTRATION_TIMEOUT_MS` overrides this value for a build; invalid values warn and use 30,000ms.
 
 ⚠ **The trap this replaced.** Setting `packages: "bundle"` by hand used to produce a clean build whose process died on start with `Error: Dynamic require of "node:assert" is not supported`. The output is ESM; bundled CJS deps call `require(...)` and read `__dirname`, and neither exists in an ES module, so the bundler substitutes a throwing stub. **A green `warlock build` was not evidence the bundle ran.** `esmShim` now injects `createRequire(import.meta.url)` and friends automatically for any ESM build, so both `singleBundle` and a hand-written `packages: "bundle"` work. An existing hand-written `banner` is preserved — the shim is prepended, not substituted.
 
@@ -3833,6 +3868,41 @@ npx warlock start --inspect              # → spawns node --enable-source-maps
 npx warlock start --max-old-space-size=4096  # → spawns node --enable-source-maps --max-old-space-size=4096 dist/app.js
 ```
 
+### Deploy one build in parts
+
+One production build can run as API, page, and background-worker processes.
+Omit `--role` to run every role (the existing default); combine roles with a
+comma-separated list:
+
+```bash
+npx warlock start --role=api
+npx warlock start --role=web --sites=admin,storefront
+npx warlock start --role=worker
+npx warlock start --role=web,api
+```
+
+`--sites=a,b` is valid only with the `web` role and installs the listed site
+keys' pages (shared non-site pages remain installed). Unknown roles, an empty
+list, `--sites` without `web`, and unknown site keys fail boot rather than
+silently serving the wrong traffic.
+
+An API or web role binds HTTP. A worker-only process binds no HTTP port; it
+loads worker work, starts queue workers and the scheduler there, and its
+readiness banner reports `worker ready`. `warlock dev` always runs every role.
+
+Inside application code, inspect the roles resolved at bootstrap:
+
+```ts
+import { Application } from "@warlock.js/core";
+
+if (Application.hasRole("worker")) {
+  // worker-only integration
+}
+
+Application.roles; // ReadonlySet<"api" | "web" | "worker">
+Application.sites; // ReadonlySet<string> | undefined (undefined = all sites)
+```
+
 Everything you pass after `start` is forwarded to the spawned Node process. Use this to attach a debugger (`--inspect`), tune memory (`--max-old-space-size`), or pass any other Node flag without editing the command.
 
 ### Source maps
@@ -3875,9 +3945,9 @@ Nothing else is needed for pnpm. Warlock never requires an app to declare a pack
 
 **A success line on stdout means the app is serving requests.** That is a contract, not a convention, and you can build a CI gate or a health probe on it.
 
-| Stream     | Carries                                                        |
-| ---------- | -------------------------------------------------------------- |
-| **stdout** | the started banner, and start failures. Nothing else.           |
+| Stream     | Carries                                                                                |
+| ---------- | -------------------------------------------------------------------------------------- |
+| **stdout** | the started banner, and start failures. Nothing else.                                  |
 | **stderr** | progress (`🚀 Starting production server...`), diagnostics, the application's own logs |
 
 The started banner prints **only** when the running application reports a completed boot — not when the command starts, not when the child is spawned. A child that dies before reporting is a failed start: the failure is written to **both** streams (stderr for humans and log collectors, stdout so a supervisor greping for the banner finds a failure rather than silence), and `warlock start` exits non-zero **even when the child itself exited `0`**.
@@ -3913,7 +3983,7 @@ else is listening on port 3000) and run again, or start on a free port — e.g.
 startHttpTestServer({ port: 3001 }).
 ```
 
-**The process exits `78` (`EX_CONFIG`), and `warlock dev`'s supervisor treats that as terminal — it prints once and stops rather than restarting.** That code is the counterpart of `75`, which a worker uses to ask for a fresh process. The distinction is the point: a code error is worth restarting, and a *startup precondition* — a port held by something else, a port value that is not a port, a boot validator that rejected — cannot change because we tried again six seconds later. Retrying one only reprints the diagnostic and then scrolls it away.
+**The process exits `78` (`EX_CONFIG`), and `warlock dev`'s supervisor treats that as terminal — it prints once and stops rather than restarting.** That code is the counterpart of `75`, which a worker uses to ask for a fresh process. The distinction is the point: a code error is worth restarting, and a _startup precondition_ — a port held by something else, a port value that is not a port, a boot validator that rejected — cannot change because we tried again six seconds later. Retrying one only reprints the diagnostic and then scrolls it away.
 
 `EACCES` on the port is treated the same way as `EADDRINUSE` (a privileged port you may not bind is also "not available"); anything else the probe throws is rethrown untouched.
 
@@ -3928,7 +3998,7 @@ Configured http.port "03999" normalised to 3999.
 `warlock start` spawns the bundle with an IPC channel and sets `WARLOCK_BOOT_SIGNAL=1` on it. `Application.markBooted()` — which the production entry calls after the late-phase connectors (http, socket) are up — sends one versioned message and closes the channel:
 
 ```ts
-{ type: "warlock:ready", version: 1, pid, at, environment, runtimeStrategy, bootDurationMs?, port? }
+{ type: "warlock:ready", version: 1, pid, at, environment, runtimeStrategy, bootDurationMs?, port?, roles }
 ```
 
 Three consequences worth knowing:
@@ -3943,11 +4013,11 @@ If you need the same fact inside the app, use `Application.onceBooted()` / `Appl
 
 `Application.environment` and `Application.runtimeStrategy` are separate axes:
 
-| Mode             | `environment`   | `runtimeStrategy` | How                                       |
-| ---------------- | --------------- | ----------------- | ----------------------------------------- |
-| `warlock dev`    | `development`*  | `development`     | preload force-sets `runtimeStrategy`      |
-| `warlock build`  | n/a (no app boots) | n/a            | only loads warlock.config.ts              |
-| `warlock start`  | `production`*   | `production`*     | usually set via `NODE_ENV` in the env     |
+| Mode            | `environment`      | `runtimeStrategy` | How                                   |
+| --------------- | ------------------ | ----------------- | ------------------------------------- |
+| `warlock dev`   | `development`*     | `development`     | preload force-sets `runtimeStrategy`  |
+| `warlock build` | n/a (no app boots) | n/a               | only loads warlock.config.ts          |
+| `warlock start` | `production`*      | `production`*     | usually set via `NODE_ENV` in the env |
 
 `*` — `environment` follows `NODE_ENV`. The dev command doesn't force it, but the default in most projects is `development`. `start` doesn't force it either; deployments set `NODE_ENV=production` themselves.
 
@@ -4006,7 +4076,7 @@ export default defineConfig({
 
 CI sets `BUILD_OUT=build/<sha>` per pipeline. `warlock start` reads the same config and finds the bundle without any hardcoded paths.
 
-**This recipe only started working in 4.11.0.** Before that, `warlock.config.ts` was evaluated *before* any `.env` file was read, so every `env()` call in it returned its default — silently, under every command. If you copied this recipe earlier and concluded that `BUILD_OUT` was ignored, it was.
+**This recipe only started working in 4.11.0.** Before that, `warlock.config.ts` was evaluated _before_ any `.env` file was read, so every `env()` call in it returned its default — silently, under every command. If you copied this recipe earlier and concluded that `BUILD_OUT` was ignored, it was.
 
 **Which file the value comes from is decided by `NODE_ENV`, and no Warlock command sets it.** `env()` reads `.env.<NODE_ENV>` when that file exists and falls back to plain `.env`. So:
 
@@ -4086,10 +4156,7 @@ Two APIs over the same engine. The fluent `Mail` builder reads top-to-bottom in
 ```ts
 import { Mail } from "@warlock.js/core";
 
-await Mail.to("user@example.com")
-  .subject("Welcome!")
-  .text("Thanks for joining.")
-  .send();
+await Mail.to("user@example.com").subject("Welcome!").text("Thanks for joining.").send();
 ```
 
 Or:
@@ -4133,10 +4200,25 @@ For named mailers (multi-provider apps), export a `MailersConfig` instead:
 
 ```ts
 const config: MailersConfig = {
-  default: { host: "smtp.sendgrid.net", port: 587, username: "apikey", password: env("SENDGRID_KEY") },
+  default: {
+    host: "smtp.sendgrid.net",
+    port: 587,
+    username: "apikey",
+    password: env("SENDGRID_KEY"),
+  },
   mailers: {
-    marketing: { host: "smtp.mailchimp.com", port: 587, username: env("MC_USER"), password: env("MC_PASS") },
-    transactional: { host: "smtp.postmark.com", port: 587, username: env("PM_USER"), password: env("PM_PASS") },
+    marketing: {
+      host: "smtp.mailchimp.com",
+      port: 587,
+      username: env("MC_USER"),
+      password: env("MC_PASS"),
+    },
+    transactional: {
+      host: "smtp.postmark.com",
+      port: 587,
+      username: env("PM_USER"),
+      password: env("PM_PASS"),
+    },
   },
 };
 ```
@@ -4168,9 +4250,9 @@ The mail pipeline switches behavior on a global mode:
 ```ts
 import { setMailMode } from "@warlock.js/core";
 
-setMailMode("production");   // actually send (default)
-setMailMode("development");  // log subject + recipient, no send
-setMailMode("test");         // capture to test mailbox, no send
+setMailMode("production"); // actually send (default)
+setMailMode("development"); // log subject + recipient, no send
+setMailMode("test"); // capture to test mailbox, no send
 ```
 
 Production sends. Development logs and returns a fake-success `MailResult`. Test captures every call into an in-memory mailbox (cleared between tests) and returns success — handy for asserting "the welcome email got sent" without hitting SMTP.
@@ -4183,7 +4265,7 @@ Production sends. Development logs and returns a fake-success `MailResult`. Test
 
 ```ts
 await Mail.to("a@example.com")
-  .to(["a@example.com", "b@example.com"])      // override
+  .to(["a@example.com", "b@example.com"]) // override
   .cc("manager@example.com")
   .bcc("audit@example.com")
   .replyTo("support@example.com")
@@ -4224,15 +4306,15 @@ await Mail.to("u@e.com")
 
 ### Other knobs
 
-| Method                                | Purpose                                       |
-| ------------------------------------- | --------------------------------------------- |
-| `.priority("high" \| "normal" \| "low")` | priority header                            |
-| `.headers({ "X-Foo": "bar" })`        | replace custom headers                        |
-| `.header("X-Foo", "bar")`             | add one header                                |
-| `.tags(["welcome"])` / `.tag("transactional")` | categorization tags                  |
-| `.correlationId("req-123")`           | tracking id (logged with sends)               |
-| `.config(MailConfigurations)`         | one-off override of the global config         |
-| `.mailer("marketing")`                | route via a named mailer from config          |
+| Method                                         | Purpose                               |
+| ---------------------------------------------- | ------------------------------------- |
+| `.priority("high" \| "normal" \| "low")`       | priority header                       |
+| `.headers({ "X-Foo": "bar" })`                 | replace custom headers                |
+| `.header("X-Foo", "bar")`                      | add one header                        |
+| `.tags(["welcome"])` / `.tag("transactional")` | categorization tags                   |
+| `.correlationId("req-123")`                    | tracking id (logged with sends)       |
+| `.config(MailConfigurations)`                  | one-off override of the global config |
+| `.mailer("marketing")`                         | route via a named mailer from config  |
 
 ### Per-mail event handlers
 
@@ -4245,9 +4327,9 @@ await Mail.to("u@e.com")
   .beforeSending((mail) => {
     // mutate `mail` or return false to cancel
   })
-  .onSent((mail, result, error) => {})    // always fires after attempt
-  .onSuccess((mail, result) => {})        // only on success
-  .onError((mail, error) => {})           // only on failure
+  .onSent((mail, result, error) => {}) // always fires after attempt
+  .onSuccess((mail, result) => {}) // only on success
+  .onError((mail, error) => {}) // only on failure
   .send();
 ```
 
@@ -4317,6 +4399,23 @@ mailEvents.onBeforeSending((mail) => {
 
 Global hooks fire for **every** mail. Per-mail handlers from the builder / `sendMail` fire only for that one send.
 
+### Observe captured development and test mail
+
+Development and test sends create a `CapturedMail` and synchronously emit the
+global `mail.captured` event. Subscribe with `mailEvents.onCaptured`:
+
+```ts
+import { mailEvents, type CapturedMail } from "@warlock.js/core";
+
+mailEvents.onCaptured((mail: CapturedMail) => {
+  console.log(mail.id, mail.options.subject);
+});
+```
+
+`CapturedMail.id` is the mail's generated or supplied id. This event is for
+development/test tooling; production sends do not emit it. Listener failures
+are logged and never interrupt mail delivery.
+
 For correlated tracking of a specific mail, generate an id and subscribe by id:
 
 ```ts
@@ -4370,10 +4469,11 @@ Captured mail shape:
 
 ```ts
 type CapturedMail = {
-  options: MailOptions;       // original payload
+  id: string;
+  options: MailOptions; // original payload
   normalized: NormalizedMail; // post-normalization (arrays, resolved from)
   timestamp: Date;
-  result?: MailResult;        // in test mode, always success
+  result?: MailResult; // in test mode, always success
   error?: MailError;
 };
 ```
@@ -5177,7 +5277,7 @@ Some tests need the full stack: route matching, middleware chain, validation, co
 
 `startHttpTestServer()` is the bootstrap. `testGet` / `testPost` / `expectJson` are the call helpers. Both ship in `@warlock.js/core/tests`.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** These helpers used to be re-exported from the package root; they are not any more, because that put the test helpers into every application's production module graph. `import { testGet } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** These helpers used to be re-exported from the package root; they are not any more, because that put the test helpers into every application's production module graph. `import { testGet } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
@@ -5218,7 +5318,7 @@ import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests"
 - Loads `warlock.config.ts` + bootstrap + `filesOrchestrator` (without file watching).
 - Loads `src/config/*.ts`.
 - Loads every module (`routes.ts`, `main.ts`, `events/*.ts`).
-- Starts **ALL** connectors, including HTTP.
+- Starts **ALL** connectors, including HTTP, by default.
 
 Unlike the dev server, it doesn't watch files, doesn't do HMR, doesn't run health checkers. Just a working HTTP endpoint listening on the configured port.
 
@@ -5238,6 +5338,14 @@ The explicit port wins over `http.port` — including over `HTTP_PORT` in `.env`
 
 The request helpers follow with no extra wiring: the bound port is published as `WARLOCK_TEST_SERVER_PORT`, which the workers inherit, and `getTestServerUrl()` prefers it over their own `.env`-resolved `http.port`. `stopHttpTestServer()` withdraws it.
 
+### API-only suites — `startHttpTestServer({ web: false })`
+
+```ts
+await startHttpTestServer({ web: false });
+```
+
+Use this in `globalSetup` for a suite that exercises API routes only. It still boots the HTTP connector and every other configured connector, but excludes the optional `web` connector before its lifecycle begins. That means web's lazy delegate never constructs `WebConnector`, and Vite is never created. Omitting `web` keeps the default full-stack behavior.
+
 ### The port is preflighted
 
 Before binding, the test server checks the resolved port is free and fails with an instruction if it isn't:
@@ -5293,8 +5401,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
-    globalSetup: "./src/test-global-setup.ts",  // ← starts the HTTP server
-    setupFiles: ["./src/test-setup.ts"],         // ← setupTest + afterAll(teardownTest), per test file
+    globalSetup: "./src/test-global-setup.ts", // ← starts the HTTP server
+    setupFiles: ["./src/test-setup.ts"], // ← setupTest + afterAll(teardownTest), per test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -5310,6 +5418,17 @@ Both files (and this config, with `lowerStage3Decorators()` first so decorated m
 
 **HTTP is the exception and stays in `globalSetup`**, which genuinely does run once in the main vitest process and owns a real port. **That split is the point:** one server for the whole run, one framework per test file.
 
+### Keep Vitest setup out of development
+
+`warlock dev` (and `warlock build`) load your app's `vite.config.ts`. Anything you put there for tests runs in development too. Guard vitest-only setup:
+
+```ts
+// vite.config.ts
+if (process.env.VITEST) {
+  Object.assign(process.env, testEnv); // test database, test keys...
+}
+```
+
 ## HTTP request helpers
 
 Everything is built on native `fetch` — no extra dependency, no special wire format.
@@ -5319,7 +5438,7 @@ Everything is built on native `fetch` — no extra dependency, no special wire f
 ```ts
 import { getTestServerUrl } from "@warlock.js/core/tests";
 
-const url = getTestServerUrl();  // → "http://localhost:2031" (defaults)
+const url = getTestServerUrl(); // → "http://localhost:2031" (defaults)
 ```
 
 Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config — unless `startHttpTestServer` published a port, which wins, since a worker's own config never sees the `{ port }` option passed in `globalSetup`. If you change the HTTP config, helpers follow automatically.
@@ -5357,9 +5476,9 @@ import { expectJson, parseJsonResponse } from "@warlock.js/core/tests";
 const body = await parseJsonResponse<MyShape>(response);
 
 // Assert status + parse in one call
-const body = await expectJson<MyShape>(response);          // expects 200
-const body = await expectJson<MyShape>(response, 201);     // expects 201
-const body = await expectJson<MyShape>(response, 404);     // expects 404 (testing error paths)
+const body = await expectJson<MyShape>(response); // expects 200
+const body = await expectJson<MyShape>(response, 201); // expects 201
+const body = await expectJson<MyShape>(response, 404); // expects 404 (testing error paths)
 ```
 
 `expectJson` throws with the actual status + response body when the assertion fails — no chasing "got 500" messages without context.
@@ -5395,7 +5514,7 @@ describe("Products API — happy path", () => {
 
 ```ts
 it("rejects missing required fields with 400", async () => {
-  const response = await testPost("/products", { name: "" });  // price missing
+  const response = await testPost("/products", { name: "" }); // price missing
   const body = await expectJson<{ errors: Array<{ key: string }> }>(response, 400);
 
   expect(body.errors.some((e) => e.key === "price")).toBe(true);
@@ -5520,13 +5639,13 @@ For unit tests, you import the thing under test and call it directly. No HTTP, n
 
 ⚠ **Corrected in 4.14.0 — `setupTest` is CALLED once per TEST FILE, not once per worker.** Every version of this skill through 4.13.0 said "per worker", the generated `src/test-setup.ts` carries a `Per-Worker Test Setup` comment saying the same thing, and **both were wrong.** Vitest runs `setupFiles` before **each test file**, and the setup module's registry is rebuilt every time — measured across all four `pool` × `isolate` combinations.
 
-⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an *explicit* value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
+⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an _explicit_ value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
 
 **The lifetime is FILE-SCOPED, on purpose.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
 
-⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See *Lifecycle and repeated calls* below.
+⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See _Lifecycle and repeated calls_ below.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
@@ -5543,7 +5662,7 @@ describe("registerUserService", () => {
     });
 
     expect(user.get("email")).toBe("test@example.com");
-    expect(user.get("password")).not.toBe("secret");  // hashed by useHashedPassword()
+    expect(user.get("password")).not.toBe("secret"); // hashed by useHashedPassword()
 
     const found = await usersRepository.first({ email: "test@example.com" });
     expect(found).toBeDefined();
@@ -5568,18 +5687,18 @@ What it does (in order):
 3. Runs `bootstrap()` — env, app, prestart hooks.
 4. Initializes the `filesOrchestrator` (module/route/config discovery, no file watching).
 5. Loads all `src/config/*.ts` files.
-6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See *Selecting connectors* below.
+6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See _Selecting connectors_ below.
 7. Starts the chosen connectors — but **never `http`** when you pass a boolean. HTTP is the global-setup's job.
 
 The result: DB/cache/logger/storage connections your code can use. Models save, repositories query, services run. Same code as production, just isolated to the test process.
 
 ### The `connectors` parameter
 
-| Value                  | Boots                                                            | Use when                                              |
-| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
-| `true` *(default)*     | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.              |
-| `false`                | None                                                             | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
-| `["database", "cache"]` | Just those, in that order                                        | A test that only needs DB but not, say, the storage driver. |
+| Value                   | Boots                                                                                                               | Use when                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `true` _(default)_      | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.                                           |
+| `false`                 | None                                                                                                                | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
+| `["database", "cache"]` | Just those, in that order                                                                                           | A test that only needs DB but not, say, the storage driver.                        |
 
 The default `true` is the sane choice. Reach for `false` when the unit you're testing genuinely doesn't talk to any framework subsystem — pulling up a DB connection **for every file** just to test a string parser is wasted setup time.
 
@@ -5595,25 +5714,25 @@ export default testsConfigurations;
 
 ⚠ **BREAKING in 4.14.0 — the precedence flipped.**
 
-| | Order |
-|---|---|
-| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true` |
-| **4.14.0 onward** | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
+|                        | Order                                                                                           |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true`              |
+| **4.14.0 onward**      | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
 
-**An explicit call-site value now beats project config.** If your project sets `tests.connectors` *and* some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
+**An explicit call-site value now beats project config.** If your project sets `tests.connectors` _and_ some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
 
 **"Explicit" means you supplied a non-`undefined` value.** Both of these fall through to config:
 
 ```ts
-await setupTest();                       // → tests.connectors, else true
-await setupTest({});                     // → tests.connectors, else true
+await setupTest(); // → tests.connectors, else true
+await setupTest({}); // → tests.connectors, else true
 await setupTest({ connectors: undefined }); // → tests.connectors, else true — NOT "start none"
 ```
 
 The `undefined` rule is deliberate: an optional variable that happens to be `undefined` must not silently erase your project config.
 
 ```ts
-await setupTest({ connectors: false });        // → none, even if config says otherwise
+await setupTest({ connectors: false }); // → none, even if config says otherwise
 await setupTest({ connectors: ["database"] }); // → exactly that, even if config differs
 ```
 
@@ -5640,7 +5759,7 @@ afterAll(teardownTest);
 ⛔ **Three things changed here in 4.14.0. If you generated this file earlier, replace all three — it is not a comment fix.**
 
 1. **`afterAll(teardownTest)` is new and mandatory.** Nothing else closes the framework your tests started. This is what makes the lifetime file-scoped and owned rather than left running.
-2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an *explicit* value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
+2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an _explicit_ value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
 3. **The comment used to say `Per-Worker Test Setup` / "Runs in EACH Vitest worker thread".** False — see the top of this skill.
 
 ```ts title="vite.config.ts"
@@ -5651,8 +5770,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
-    globalSetup: "./src/test-global-setup.ts",  // ← HTTP server (see test-http skill)
-    setupFiles: ["./src/test-setup.ts"],         // ← runs setupTest before EACH test file
+    globalSetup: "./src/test-global-setup.ts", // ← HTTP server (see test-http skill)
+    setupFiles: ["./src/test-setup.ts"], // ← runs setupTest before EACH test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -5662,6 +5781,17 @@ export default defineConfig({
 
 The `mongezVite()` plugin handles TypeScript path resolution and the framework's module shape. Without it, your imports break the moment vitest tries to load a Warlock module. `lowerStage3Decorators()` goes **first** — it lets decorated Cascade models (`@RegisterModel`, …) load under Vitest 4 / Vite 8; see [`@warlock.js/core/lower-stage3-decorators/SKILL.md`](@warlock.js/core/lower-stage3-decorators/SKILL.md).
 
+### Keep Vitest setup out of development
+
+`warlock dev` (and `warlock build`) load your app's `vite.config.ts`. Anything you put there for tests runs in development too. Guard vitest-only setup:
+
+```ts
+// vite.config.ts
+if (process.env.VITEST) {
+  Object.assign(process.env, testEnv); // test database, test keys...
+}
+```
+
 Tests live colocated with the module: `src/app/<module>/tests/*.test.ts`. The `include` pattern picks them up.
 
 ## Patterns
@@ -5687,9 +5817,9 @@ describe("createProductService", () => {
   it("rejects duplicate names", async () => {
     await Product.create({ name: "Existing", price: 10 });
 
-    await expect(
-      createProductService({ name: "Existing", price: 20 }),
-    ).rejects.toThrow(/already exists/i);
+    await expect(createProductService({ name: "Existing", price: 20 })).rejects.toThrow(
+      /already exists/i,
+    );
   });
 });
 ```
@@ -5759,7 +5889,7 @@ afterEach(async () => {
 
 Vitest runs the tests within one file sequentially, so an `afterEach` truncate gives each test a clean slate.
 
-⚠ **Cross-*file* isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
+⚠ **Cross-_file_ isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
 
 ### Skipping connectors for pure logic tests
 
@@ -5769,7 +5899,7 @@ import { setupTest } from "@warlock.js/core/tests";
 import { slugify } from "../utils/slugify";
 
 beforeAll(async () => {
-  await setupTest({ connectors: false });  // starts no connectors at all
+  await setupTest({ connectors: false }); // starts no connectors at all
 });
 
 describe("slugify", () => {
@@ -5796,7 +5926,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await teardownTest();      // ← REQUIRED, see below
+  await teardownTest(); // ← REQUIRED, see below
 });
 ```
 
@@ -5817,16 +5947,16 @@ afterAll(async () => {
 
 `setupTest` / `teardownTest` are a pair. **The harness that calls one owns calling the other in the same context.**
 
-| Call | Behaviour |
-|---|---|
-| `setupTest(x)` while idle | bootstraps |
-| `setupTest(x)` while already ready with the **same** effective options | no-op |
-| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested |
-| two concurrent `setupTest(x)` calls | share one startup |
-| `setupTest` after a failed setup | allowed — a failed setup unwinds and returns to idle |
-| `teardownTest()` while idle | no-op |
-| two concurrent `teardownTest()` calls | share one shutdown |
-| `setupTest(y)` after a **successful** teardown | allowed, different options fine |
+| Call                                                                        | Behaviour                                            |
+| --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `setupTest(x)` while idle                                                   | bootstraps                                           |
+| `setupTest(x)` while already ready with the **same** effective options      | no-op                                                |
+| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested           |
+| two concurrent `setupTest(x)` calls                                         | share one startup                                    |
+| `setupTest` after a failed setup                                            | allowed — a failed setup unwinds and returns to idle |
+| `teardownTest()` while idle                                                 | no-op                                                |
+| two concurrent `teardownTest()` calls                                       | share one shutdown                                   |
+| `setupTest(y)` after a **successful** teardown                              | allowed, different options fine                      |
 
 **"Same options" is compared by meaning, not by literal value** — connector arrays are deduplicated and compared as sets, so `["cache", "database"]` and `["database", "cache", "cache"]` are the same selection.
 
@@ -5841,7 +5971,7 @@ afterAll(async () => {
 ```ts title="src/config/tests.ts"
 const testsConfigurations = {
   connectors: ["database", "logger"],
-  setupTimeout: 120000,   // milliseconds — this is the default
+  setupTimeout: 120000, // milliseconds — this is the default
 };
 
 export default testsConfigurations;
@@ -5860,9 +5990,9 @@ in `src/config/tests.ts` — milliseconds, default 120000.
 1. **It bounds the setup ATTEMPT, not teardown separately.** `teardownTest()` awaits the same attempt, so it inherits the bound — **one timer, not two.** A second teardown-side deadline was tried and rejected: it re-introduced the unbounded re-entry this whole guard exists to remove.
 2. **Expiry poisons the lifecycle**, it does not return to `idle`. The attempt may have started connectors nobody can now account for, so pretending the runtime is clean would be worse than refusing.
 3. **⛔ An invalid `setupTimeout` throws, naming the bad value.** Zero, negative and non-numeric all fail loudly rather than falling back to the default — a silent fallback would hide a typo behind a working suite.
-4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens *inside* the window being bounded; re-arming naively would give you the default plus your configured value.
+4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens _inside_ the window being bounded; re-arming naively would give you the default plus your configured value.
 
-⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default *value* is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle *decides*, not what a genuinely wedged connector does.
+⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default _value_ is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle _decides_, not what a genuinely wedged connector does.
 
 ### State is per worker runtime, not per module
 
@@ -5893,6 +6023,16 @@ In both cases the guard's scope matches the resource's scope, which is the point
 - [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where tests live in a module (`tests/*.test.ts`).
 - [`write-cli-command/SKILL.md`](../write-cli-command/SKILL.md) — `warlock add test` for the initial scaffold.
 
+## App modules and `importModule`
+
+Under Vitest, test files run through vite-node while Warlock's own native `import()` of app modules (config, routes, events) does not, so app classes such as `User` can exist twice in one worker and `instanceof` fails. Pass `importModule` to `setupTest` so Warlock loads app modules through the test's own module graph:
+
+```ts
+setupTest({ importModule: (file) => import(file) });
+```
+
+The generated `src/test-setup.ts` already does this. Without it, `setupTest()` under Vitest warns once.
+
 
 ## update-packages  `@warlock.js/core/update-packages/SKILL.md`
 
@@ -6654,7 +6794,7 @@ cors: {
 
 ---
 name: use-localization
-description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` / `request.t()` / `request.trans()` (look up), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
+description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` (look up; always use it in app code, never `request.t()`), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
 ---
 
 # Warlock — translate keys + pick localized values
@@ -6669,7 +6809,7 @@ Both pivot on **the request's locale** — auto-detected from headers / query st
 ## The shape
 
 ```ts
-// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.ts)
+// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.json)
 import { groupedTranslations } from "@mongez/localization";
 
 groupedTranslations("products", {
@@ -6681,8 +6821,7 @@ groupedTranslations("products", {
 import { t } from "@warlock.js/core";
 
 throw new ResourceNotFoundError(t("products.notFound"));
-// or via the request:
-return response.success({ message: request.t("products.created") });
+return response.success({ message: t("products.created") });
 
 // 3. Pick a value from a localized-array column
 import { getLocalized } from "@warlock.js/core";
@@ -6691,7 +6830,26 @@ const name = getLocalized(product.get("name_translations"));
 // → reads the current request's locale, returns the matching value
 ```
 
-## Declaring translations — `groupedTranslations`
+## Declaring translations — module `locales.json`
+
+Prefer a data-only dictionary in `src/app/<module>/utils/locales.json`. The
+module folder is its default group, so this example registers
+`products.notFound`; a root `$group` string replaces that group when a module
+needs a different namespace. The module loader validates the strict JSON
+shape, flattens nested keys, and rejects duplicate ownership. Do not import the
+file yourself.
+
+```json title="src/app/products/utils/locales.json"
+{
+  "notFound": { "en": "Product not found", "ar": "المنتج غير موجود" },
+  "errors": { "outOfStock": { "en": "Product out of stock", "ar": "المنتج غير متوفر" } }
+}
+```
+
+`utils/locales.ts` with `groupedTranslations` remains supported but is
+deprecated and will be removed in v6. Migrate it with `warlock doctor --fix`.
+
+### Legacy `groupedTranslations`
 
 Every module owns its translation namespace under `src/app/<module>/utils/locales.ts`. The file is auto-loaded at boot — you don't import it from anywhere; the framework picks it up via the module loader.
 
@@ -6728,31 +6886,25 @@ t("products.outOfStock", { name: "Pen", count: 0 });
 
 Placeholders use the `:name` syntax. The lookup helper substitutes them from the second argument.
 
-## Looking up translations — `t()`, `request.t()`, `request.trans()`
+## Looking up translations — always `t()`
 
-Three calls, same job, slightly different reachability:
+**Rule: app code translates with `t()` from `@warlock.js/core`.** It works everywhere: controllers, services, page and layout loaders, `metadata`, events and jobs. It returns a `string`.
 
 ```ts
-// 1. Top-level helper — works inside or outside a request.
-//    Inside a request: uses request's locale.
-//    Outside: uses the global default locale.
 import { t } from "@warlock.js/core";
 
 t("products.notFound");
 t("products.outOfStock", { name: "Pen", count: 0 });
-
-// 2. On the request object — explicit, scoped to that request.
-request.t("products.notFound");
-
-// 3. Alias for request.t — same behavior.
-request.trans("products.notFound");
 ```
 
-All three lookups go through `@mongez/localization`'s `trans()` under the hood, with the locale pulled from the request context (or the global default).
+- Inside a request (a controller or a page loader) it uses the request's locale. In a page it first checks the route's `locales.json` snapshot, then falls back to module translations (`groupedTranslations` or module `locales.json`).
+- Outside a request (jobs, CLI) it uses the configured default locale.
+- `request.t()` / `request.trans()` are the per-request binding that `t()` delegates to. Don't call them in app code: `t()` gives the same result without threading `request` through services.
+- Don't wrap it in `String(...)`; it is already typed `string`.
 
 ### Web `useTrans()` key checking
 
-When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic groups/keys and placeholders are not inferred.
+When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from module `locales.json` dictionaries and literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic TypeScript groups/keys and placeholders are not inferred.
 
 `useTrans()` now works correctly across hydration (5.15.0): the hydration
 payload ships a `translations` key with the active locale's keywords, and
@@ -6798,7 +6950,7 @@ export default {
 request.setLocaleCode("ar");
 ```
 
-After this, every `request.t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
+After this, every `t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
 
 ## Localized columns — `getLocalized`
 
@@ -6895,6 +7047,7 @@ The error's message is locale-aware — the `inject-request-context` middleware
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
+import { t } from "@warlock.js/core";
 
 export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
@@ -6902,7 +7055,7 @@ export const createProductController: GuardedRequestHandler<CreateProductSchema>
 }) => {
   const product = await createProductService(request.validated());
   return response.success({
-    message: request.t("products.created"),
+    message: t("products.created"),
     product,
   });
 };
@@ -6942,11 +7095,11 @@ await Product.create({
 GET /products/42?locale=ar
 ```
 
-`request.getLocaleCode()` returns `"ar"` — every `request.t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
+`request.getLocaleCode()` returns `"ar"` — every `t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
 
 ## Gotchas
 
-- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.ts` is picked up by the module loader on boot. Importing it manually causes double-registration warnings.
+- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.json` is picked up by the module loader on boot. Importing legacy `locales.ts` manually causes double-registration warnings.
 - **Group names should match module URL slugs.** `groupedTranslations("products", ...)` for the `/products` module. Mismatch breaks the convention but doesn't throw.
 - **Every key needs every locale.** If a key is missing for the active locale, the lookup falls back to the key string itself (`"products.notFound"` literally appears in the response). Always ship all locales together when adding a key.
 - **`t()` outside a request uses the global default.** `Application.environment === "test"` or background jobs without a request context get the configured `app.localeCode`, not whatever the most recent request used.
@@ -6959,8 +7112,8 @@ GET /products/42?locale=ar
 
 - [`send-response/SKILL.md`](../send-response/SKILL.md) — error helpers that pair with translated messages (`response.notFound({ error: t("...") })`).
 - [`define-resource/SKILL.md`](../define-resource/SKILL.md) — using `getLocalized` inside resource output for clean per-locale responses.
-- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.ts` file is part of the generated module scaffold.
-- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.ts` is auto-loaded; the suffix is mandatory.
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.json` file is part of the generated module scaffold.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.json` is auto-loaded; the suffix is mandatory.
 
 ## Route-owned web translations (5.17)
 
@@ -6974,9 +7127,9 @@ GET /products/42?locale=ar
 }
 ```
 
-This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()`, `request.t()`, and `request.trans()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
+This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()` and `t()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
 
-When a route-locales snapshot applies, `request.t()`, `request.trans()`, and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
+When a route-locales snapshot applies, `t()` (through the request binding) and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
 
 
 ## use-middleware  `@warlock.js/core/use-middleware/SKILL.md`
@@ -8417,6 +8570,9 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
 2. **Several files are auto-loaded — never `import` them.** The dev-server file watcher and the production builder categorize these as "special" and load them on boot.
    - `src/app/<module>/routes.ts` — route declarations
    - `src/app/<module>/main.ts` — per-module one-time setup
+   - `src/app/<module>/worker.ts` — worker-only setup (queue job definitions,
+     `scheduler.addJob(...)`, `scheduler.start()`); loaded only for the
+     `worker` role, and always loaded by `warlock dev`
    - `src/app/main.ts` — **project-level** one-time application setup (global hooks and other app initialization; connector instances belong in `warlock.config.ts > connectors`)
    - `src/app/<module>/events/*.ts(x)` — **any** `.ts(x)` file inside the `events/` folder (the `*.event.ts` suffix is convention, not a framework requirement)
    - `src/app/<module>/utils/locales.ts` — module translations via `groupedTranslations(...)`
@@ -8437,7 +8593,7 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    ```ts title="src/app/<module>/schema/create-<thing>.schema.ts"
    import { v, type Infer } from "@warlock.js/seal";
 
-   export const createThingSchema = v.object({ /* … */ });
+   export const createThingSchema = v.object({/* … */});
    export type CreateThingSchema = Infer<typeof createThingSchema>;
    ```
 
@@ -8446,13 +8602,17 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    import { type CreateThingSchema, createThingSchema } from "../schema/create-thing.schema";
    import { createThingService } from "../services/create-thing.service";
 
-   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({ request, response }) => {
+   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({
+     request,
+     response,
+   }) => {
      const thing = await createThingService(request.validated());
      return response.success({ thing });
    };
 
    createThingController.validation = { schema: createThingSchema };
    ```
+
 8. **Model getters beat `.get<T>("field")`.** Add a typed getter on the model rather than scattering `.get<string>("name")` casts across call sites.
 
 ## Module layout (the standard subfolders)
@@ -8471,26 +8631,27 @@ src/app/<module>/
   seeds/                    seed data for `warlock seed`
   routes.ts                 ← auto-loaded
   main.ts                   ← auto-loaded once, one-time setup
+  worker.ts                 ← auto-loaded for the worker role only
 ```
 
 Some older modules still have a `validation/` folder instead of `schema/` — historical drift. The framework treats them as plain folders either way; the generator emits to `schema/`.
 
 ## File naming (project-wide)
 
-| Suffix              | Role                                  | Example                             |
-| ------------------- | ------------------------------------- | ----------------------------------- |
-| `.controller.ts`    | HTTP handler                          | `create-product.controller.ts`      |
-| `.service.ts`       | Stateless business logic              | `create-product.service.ts`         |
-| `.usecase.ts`       | `useCase()` pipeline                  | `login.usecase.ts`                  |
-| `.model.ts`         | Cascade model class                   | `product.model.ts`                  |
-| `.repository.ts`    | `RepositoryManager` subclass          | `products.repository.ts`            |
-| `.resource.ts`      | `Resource` subclass                   | `product.resource.ts`               |
-| `.schema.ts`        | seal validation schema + its inferred `<Name>Schema` type from the same file | `create-product.schema.ts`          |
-| `.type.ts`          | data shape (TypeScript `type`)        | `cart-state.type.ts`                |
-| `.contract.ts`      | interface (TypeScript `interface`)    | `model.contract.ts`                 |
-| `.event.ts`         | event listener registrations (any `.ts(x)` inside `events/` works; the suffix is convention) | `audit.event.ts`                    |
-| `.migration.ts`     | Cascade migration                     | `2026_05_22_120000_product.migration.ts` |
-| `.seed.ts`          | seed data                             | `products.seed.ts`                  |
+| Suffix           | Role                                                                                         | Example                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `.controller.ts` | HTTP handler                                                                                 | `create-product.controller.ts`           |
+| `.service.ts`    | Stateless business logic                                                                     | `create-product.service.ts`              |
+| `.usecase.ts`    | `useCase()` pipeline                                                                         | `login.usecase.ts`                       |
+| `.model.ts`      | Cascade model class                                                                          | `product.model.ts`                       |
+| `.repository.ts` | `RepositoryManager` subclass                                                                 | `products.repository.ts`                 |
+| `.resource.ts`   | `Resource` subclass                                                                          | `product.resource.ts`                    |
+| `.schema.ts`     | seal validation schema + its inferred `<Name>Schema` type from the same file                 | `create-product.schema.ts`               |
+| `.type.ts`       | data shape (TypeScript `type`)                                                               | `cart-state.type.ts`                     |
+| `.contract.ts`   | interface (TypeScript `interface`)                                                           | `model.contract.ts`                      |
+| `.event.ts`      | event listener registrations (any `.ts(x)` inside `events/` works; the suffix is convention) | `audit.event.ts`                         |
+| `.migration.ts`  | Cascade migration                                                                            | `2026_05_22_120000_product.migration.ts` |
+| `.seed.ts`       | seed data                                                                                    | `products.seed.ts`                       |
 
 Filenames are kebab-case. Class names are PascalCase. Function names are camelCase. Table/collection names are snake_case (plural).
 
@@ -8501,8 +8662,8 @@ The scaffolded `tsconfig.json` defines:
 ```jsonc
 {
   "paths": {
-    "app/*": ["./src/app/*"]
-  }
+    "app/*": ["./src/app/*"],
+  },
 }
 ```
 
@@ -9147,16 +9308,16 @@ Run it: `npx warlock users.promote --email=hasan@example.com` (or `npx warlock u
 
 ## `CLICommandOptions` — the factory input
 
-| Field         | Type                          | Required | Notes                                                                                          |
-| ------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `name`        | `string`                      | yes      | Dot notation OK (`db.seed`, `jwt.generate`). May include positional placeholders (`name <arg>`). |
-| `description` | `string`                      |          | Shown in `warlock --help` and `warlock <cmd> --help`.                                          |
-| `alias`       | `string`                      |          | Short name (`m` for `migrate`).                                                                |
-| `action`      | `(data) => void \| Promise`   | yes      | Runs after preloaders. `data` is `{ args, options }`.                                          |
-| `preAction`   | `(data) => void \| Promise`   |          | Runs **before** preloaders — banner, input validation.                                         |
-| `preload`     | `CLICommandPreload`           |          | What to load before `action` runs. See below.                                                  |
-| `persistent`  | `boolean`                     |          | `true` for long-running commands (dev server). Skips the auto-exit.                            |
-| `options`     | `CLICommandOption[]`          |          | Flag definitions. See below.                                                                   |
+| Field         | Type                        | Required | Notes                                                                                            |
+| ------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `name`        | `string`                    | yes      | Dot notation OK (`db.seed`, `jwt.generate`). May include positional placeholders (`name <arg>`). |
+| `description` | `string`                    |          | Shown in `warlock --help` and `warlock <cmd> --help`.                                            |
+| `alias`       | `string`                    |          | Short name (`m` for `migrate`).                                                                  |
+| `action`      | `(data) => void \| Promise` | yes      | Runs after preloaders. `data` is `{ args, options }`.                                            |
+| `preAction`   | `(data) => void \| Promise` |          | Runs **before** preloaders — banner, input validation.                                           |
+| `preload`     | `CLICommandPreload`         |          | What to load before `action` runs. See below.                                                    |
+| `persistent`  | `boolean`                   |          | `true` for long-running commands (dev server). Skips the auto-exit.                              |
+| `options`     | `CLICommandOption[]`        |          | Flag definitions. See below.                                                                     |
 
 ## Options — flag shape
 
@@ -9258,29 +9419,29 @@ The framework ships a fixed set of commands you call but don't author. Knowing t
 
 ### Database + migrations
 
-| Command  | Flags / args                                    | Preloads                       |
-| -------- | ----------------------------------------------- | ------------------------------ |
-| `warlock migrate` | `--list` / `-l` (executed **and** pending), `--pending` (pending only, sets an exit code), `--fresh` / `-f` (drop tables first) | database, logger          |
-| `warlock seed` | `--name <pattern>` (run seeds matching the pattern) | full bootstrap (env, configs, app modules) |
-| `warlock create-database <name>` | bare positional `<name>`        | database                       |
-| `warlock drop.tables` | `--force, -f` (skip confirmation prompt) | database, logger          |
-| `warlock db.indexes` | builds DB indexes for every registered model    | database                  |
+| Command                          | Flags / args                                                                                                                    | Preloads                                   |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `warlock migrate`                | `--list` / `-l` (executed **and** pending), `--pending` (pending only, sets an exit code), `--fresh` / `-f` (drop tables first) | database, logger                           |
+| `warlock seed`                   | `--name <pattern>` (run seeds matching the pattern)                                                                             | full bootstrap (env, configs, app modules) |
+| `warlock create-database <name>` | bare positional `<name>`                                                                                                        | database                                   |
+| `warlock drop.tables`            | `--force, -f` (skip confirmation prompt)                                                                                        | database, logger                           |
+| `warlock db.indexes`             | builds DB indexes for every registered model                                                                                    | database                                   |
 
 **Asking what will run next.** `warlock migrate --list` prints executed migrations and then the pending ones **in execution order**. Do not derive the pending set by differencing `--all` against `--list`: `--all` globs `src/app` only, while `--list` reads the migrations table, which also holds migrations that packages register through `database.migrations` (`@warlock.js/auth` contributes two). The difference under-counts pending, in the direction that says "safe to proceed".
 
 `--list` is a report and always exits `0`. `--pending` is a gate, and its exit code is its whole API:
 
-| Exit | Meaning |
-| ---- | ------- |
+| Exit | Meaning                   |
+| ---- | ------------------------- |
 | `0`  | computed, nothing pending |
-| `1`  | computed, N pending |
+| `1`  | computed, N pending       |
 | `2`  | **could not be computed** |
 
 ```bash
 warlock migrate --pending && ./deploy.sh
 ```
 
-`2` is separate from `1` on purpose — a script must be able to tell a backlog from an unknown, because one means *run them* and the other means *stop*. When the migration files cannot be loaded, both commands print `Pending: unavailable — <reason>` beneath a complete executed listing rather than reporting `0`.
+`2` is separate from `1` on purpose — a script must be able to tell a backlog from an unknown, because one means _run them_ and the other means _stop_. When the migration files cannot be loaded, both commands print `Pending: unavailable — <reason>` beneath a complete executed listing rather than reporting `0`.
 
 **If you are writing a command that reports on pending migrations:** register migrations first. `listPendingMigrations()` filters the runner's registry, so a caller that has not loaded anything gets `[]` — which reads as "nothing pending" and is not the same claim.
 
@@ -9306,36 +9467,41 @@ warlock generate                         (alias: g)      — interactive picker
 
 `warlock add <features...>` installs framework-adjacent features through a curated registry — bundles npm dependencies + scaffold files + tsconfig patches + package.json scripts in one call. Featured names (from `add-command.action.ts`):
 
-| Feature       | Installs                                                                                            |
-| ------------- | --------------------------------------------------------------------------------------------------- |
-| `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json` |
-| `web`         | Warlock Web + React stack; scaffolds the application page, localization, contact endpoint, and Web configuration                         |
-| `react`       | `react` + `react-dom` + types                                                                       |
+| Feature       | Installs                                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json`                               |
+| `web`         | Warlock Web + React stack; scaffolds the application page, localization, contact endpoint, and Web configuration                                                                       |
+| `react`       | `react` + `react-dom` + types                                                                                                                                                          |
 | `bull-board`  | `@bull-board/api` + `@bull-board/fastify`; writes a `dashboard` block to `src/config/queue.ts`. `requires: ["queue"]` — adds the `queue` feature first automatically when it's missing |
-| `image`       | `sharp` (for the `Image` class)                                                                     |
-| `mail`        | `nodemailer` + types                                                                                |
-| `ses`         | `@aws-sdk/client-sesv2`                                                                             |
-| `mongodb`     | `mongodb` driver                                                                                    |
-| `postgres`    | `pg`                                                                                                |
-| `mysql`       | `mysql2`                                                                                            |
-| `redis`       | `redis`                                                                                             |
-| `s3`          | `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`                     |
-| `scheduler`   | `@warlock.js/scheduler`                                                                             |
-| `swagger`     | `@warlock.js/swagger`                                                                               |
-| `postman`     | `@warlock.js/postman`                                                                               |
-| `herald`      | `@warlock.js/herald` + `amqplib` + types; ejects `src/config/communicator.ts`                       |
-| `test`        | `vitest` + `@mongez/vite` + coverage; drops `test-global-setup.ts` / `test-setup.ts` / `vite.config.ts` |
+| `image`       | `sharp` (for the `Image` class)                                                                                                                                                        |
+| `mail`        | `nodemailer` + types                                                                                                                                                                   |
+| `ses`         | `@aws-sdk/client-sesv2`                                                                                                                                                                |
+| `mongodb`     | `mongodb` driver                                                                                                                                                                       |
+| `postgres`    | `pg`                                                                                                                                                                                   |
+| `mysql`       | `mysql2`                                                                                                                                                                               |
+| `redis`       | `redis`                                                                                                                                                                                |
+| `s3`          | `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`                                                                                                        |
+| `scheduler`   | `@warlock.js/scheduler`                                                                                                                                                                |
+| `swagger`     | `@warlock.js/swagger`                                                                                                                                                                  |
+| `postman`     | `@warlock.js/postman`                                                                                                                                                                  |
+| `herald`      | `@warlock.js/herald` + `amqplib` + types; ejects `src/config/communicator.ts`                                                                                                          |
+| `test`        | `vitest` + `@mongez/vite` + coverage; drops `test-global-setup.ts` / `test-setup.ts` / `vite.config.ts`                                                                                |
+| `devtools`    | `@warlock.js/devtools` as a dev dependency; `warlock dev` auto-loads its development dashboard at `/__warlock`                                                                         |
 
 Run `warlock add --list` to see what's currently registered. Pass `--packageManager <yarn\|pnpm\|npm>` to override auto-detection (defaults to whichever lockfile is present).
 
+`warlock add devtools` never adds anything to `warlock.config.ts`. The package
+is loaded automatically by `warlock dev` when installed, and is omitted from a
+production install with dev dependencies excluded.
+
 The Web starter keeps the page's universal non-component setup in `src/web/index.register.ts`, while `src/web/index.page.tsx` re-exports `register`. Warlock still discovers and runs the hook from the page namespace in both SSR and the browser, but editing the page component remains inside React's Fast Refresh boundary. Do not move the `register()` declaration inline beside the component: React Refresh treats that non-component export as incompatible and reloads the page, losing component state.
 
 ### Misc
 
-| Command  | Purpose                                                     |
-| -------- | ----------------------------------------------------------- |
-| `warlock storage.put <localPath> [destination]` | Upload a local file to the default storage disk |
-| `warlock jwt.generate` | Generate a JWT secret in `.env` (from `@warlock.js/auth`)            |
+| Command                                         | Purpose                                                   |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `warlock storage.put <localPath> [destination]` | Upload a local file to the default storage disk           |
+| `warlock jwt.generate`                          | Generate a JWT secret in `.env` (from `@warlock.js/auth`) |
 
 ## Common patterns
 
@@ -9397,7 +9563,7 @@ export default command({
 });
 ```
 
-`preAction` runs *before* preloaders — cheap way to bail out without spinning up the database.
+`preAction` runs _before_ preloaders — cheap way to bail out without spinning up the database.
 
 ## Gotchas
 
@@ -9405,7 +9571,7 @@ export default command({
 - **Don't put logic at module top level.** The file gets imported during the commands scan (`warlock --warm-cache`). Anything outside `action` runs at scan time, possibly before any config or env is loaded.
 - **Required options block execution.** If `required: true` and the user omits the flag, the framework prints `Missing required options:` and exits `1` before `action` runs.
 - **Connectors are not free.** `connectors: true` boots the database, cache, storage, etc. For a print-version-and-exit command, leave `preload` undefined.
-- **`name` field with positional slots** (`name: "storage.put <localPath>"`) — the *registered* name is still `storage.put` (the first whitespace-separated token), so look up + alias work normally. Slots are only documentation/help-output.
+- **`name` field with positional slots** (`name: "storage.put <localPath>"`) — the _registered_ name is still `storage.put` (the first whitespace-separated token), so look up + alias work normally. Slots are only documentation/help-output.
 - **Aliases must be unique across plugin + framework + project.** The first registration wins; later collisions silently overwrite the map entry.
 
 ## See also
@@ -10302,6 +10468,8 @@ Per-invocation callbacks fire first, then use-case-level, then globals. The retu
 
 Don't reach for `useCase` for a 5-line service — the ceremony outweighs the benefit.
 
+For the plain-function flavour (`warlock generate.use-case <module>/<verb-noun>`) shared by a page action and a controller, see the guide [One use-case, two adapters](https://warlock.js.org/v/latest/core/guides/one-use-case-two-adapters/).
+
 ## Gotchas
 
 - **`name` must be unique.** The registry de-dupes by name; a duplicate in dev logs a warning and one wins. Use namespaced names: `"orders.placeOrder"`.