@warlock.js/core 5.24.0 → 5.26.0

package/llms.txt

@@ -33,7 +33,7 @@
 - [update-packages](@warlock.js/core/update-packages/SKILL.md): Keep a project current with `warlock update` — bump every `@warlock.js/*` dependency in package.json to its latest published version (range operator preserved), then run the lockfile-detected package manager install. Also covers the `warlock dev` update notice, its `u` update-and-restart keyboard shortcut, and the `devServer.checkForUpdates` toggle. Triggers: `warlock update`, `--no-install`, `--dry-run`, `--check`, `checkForUpdates`, `fetchLatestVersion`, `isNewerVersion`; "update warlock packages", "upgrade the framework", "is there a new warlock version", "update notice in the dev server", "press u to update", "dev server keyboard shortcut", "update check offline", "bump @warlock.js/* to latest"; typical CLI `warlock update`. Skip: dev/build/start runtime — `@warlock.js/core/run-app/SKILL.md`; writing a custom command — `@warlock.js/core/write-cli-command/SKILL.md`; installing a NEW feature package (auth, mail, storage) — that is `warlock add`; releasing/publishing the framework — workspace release tooling, not this command.
 - [upload-file](@warlock.js/core/upload-file/SKILL.md): Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.
 - [use-app-context](@warlock.js/core/use-app-context/SKILL.md): Read app-wide context — the `Application` static class (env, version, uptime, runtime strategy, boot lifecycle) plus the `app` runtime accessor (live Fastify, socket.io, router, database via the DI container). Triggers: `Application.isProduction`, `Application.environment`, `Application.runtimeStrategy`, `Application.uptime`, `Application.version`, `Application.onceBooted`, `Application.whenBooted`, `Application.isBooted`, `Application.onShutdown`, `Application.isShuttingDown`, `app.http`, `app.socket`, `app.database`, `app.router`; "branch on environment", "reach the live Fastify instance", "framework version in health endpoint", "dev vs production runtime check", "run code once the app is fully booted", "after all connectors started", "app booted hook", "run cleanup before shutdown", "graceful shutdown hook"; typical import `import { Application, app } from "@warlock.js/core"`. Skip: path helpers — `@warlock.js/core/resolve-path/SKILL.md`; connector start order — `@warlock.js/core/add-connector/SKILL.md`; competing patterns: bare `process.env.NODE_ENV`, ad-hoc Fastify imports.
-- [use-localization](@warlock.js/core/use-localization/SKILL.md): 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`.
+- [use-localization](@warlock.js/core/use-localization/SKILL.md): 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`.
 - [use-middleware](@warlock.js/core/use-middleware/SKILL.md): Attach built-in HTTP middleware to routes via the `middleware` namespace from `@warlock.js/core` — rateLimit, concurrencyLimit, maxBodySize, idempotency, maintenance, ipFilter, cache. Plus `X-Request-Id` correlation, wired automatically. Triggers: `middleware.rateLimit`, `middleware.concurrencyLimit`, `middleware.maxBodySize`, `middleware.idempotency`, `middleware.maintenance`, `middleware.ipFilter`, `middleware.cache`, `X-Request-Id`, `Idempotency-Key`; "add rate limiting", "dedupe writes by idempotency key", "cap concurrent requests", "block IPs", "cache a GET response"; typical import `import { middleware } from "@warlock.js/core"`. Skip: author custom middleware — `@warlock.js/core/write-middleware/SKILL.md`; cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `@fastify/rate-limit` direct, `express-rate-limit`, `helmet`.
 - [use-model-transformers](@warlock.js/core/use-model-transformers/SKILL.md): Three schema-side helpers — `useHashedPassword()` (bcrypt on save) attaches via `.addTransformer(...)`; `useComputedSlug(field?, scope?)` (auto-slug from another field) and `useComputedModel(callback)` (arbitrary computed-on-save value) attach via `v.computed(...)`. Triggers: `useHashedPassword`, `useComputedSlug`, `useComputedModel`, `.addTransformer`, `v.computed`, `ComputedCallback`; "auto-hash a password field", "auto-slug from title on save", "derive a value at write time", "declarative model transformers"; typical import `import { useHashedPassword, useComputedSlug } from "@warlock.js/core"`. Skip: bcrypt setup details — `@warlock.js/core/hash-password/SKILL.md`; repository writes — `@warlock.js/core/use-repository/SKILL.md`; output filtering — `@warlock.js/core/define-resource/SKILL.md`; competing patterns: manual `await hashPassword(input)` in services, ORM lifecycle hooks.
 - [use-repository](@warlock.js/core/use-repository/SKILL.md): Subclass `RepositoryManager` for data access — declare `source`, `filterBy`, `defaultOptions`, then call `list()`/`listCached()`/`find()`/`create()`/`update()`/`delete()`, the active/cached/cursor variants, and the `filterBy`-aware aggregates `sum()`/`avg()`/`min()`/`max()`/`groupBy()`/`aggregate()`. Triggers: `RepositoryManager`, `FilterRules`, `RepositoryOptions`, `.list`, `.listCached`, `.find`, `.findCached`, `.create`, `.update`, `.delete`, `.sum`, `.avg`, `.min`, `.max`, `.groupBy`, `.aggregate`, `simpleSelectColumns`; "create a repository", "filter rules for a list endpoint", "cursor vs page pagination", "cached vs uncached read", "sum/avg/group-by with filters"; typical import `import { RepositoryManager } from "@warlock.js/core"`. Skip: cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; use-case pipelines — `@warlock.js/core/write-use-case/SKILL.md`; wire mapping — `@warlock.js/core/define-resource/SKILL.md`; competing libs `typeorm` Repository, `prisma.client.<model>`, `@nestjs/typeorm`.

package/package.json

@@ -8,12 +8,12 @@
     "warlock": "bin/warlock.js"
   },
   "dependencies": {
-    "@fastify/cookie": "^10.0.0",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/http-proxy": "^11.4.1",
-    "@fastify/multipart": "^9.3.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@fastify/static": "^8.3.0",
+    "@fastify/cookie": "^11.1.2",
+    "@fastify/cors": "^11.3.0",
+    "@fastify/http-proxy": "^11.6.3",
+    "@fastify/multipart": "^10.1.2",
+    "@fastify/rate-limit": "^11.2.0",
+    "@fastify/static": "^10.1.5",
     "@mongez/concat-route": "^1.2.1",
     "@mongez/config": "^1.2.2",
     "@mongez/copper": "^2.1.3",
@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.5",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.24.0",
-    "@warlock.js/cascade": "5.24.0",
-    "@warlock.js/context": "5.24.0",
-    "@warlock.js/fs": "5.24.0",
-    "@warlock.js/logger": "5.24.0",
-    "@warlock.js/seal": "5.24.0",
+    "@warlock.js/cache": "5.26.0",
+    "@warlock.js/cascade": "5.26.0",
+    "@warlock.js/context": "5.26.0",
+    "@warlock.js/fs": "5.26.0",
+    "@warlock.js/logger": "5.26.0",
+    "@warlock.js/seal": "5.26.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -38,8 +38,8 @@
     "esbuild": "^0.27.2",
     "eslint": "^9.18.0",
     "fast-glob": "^3.3.3",
-    "fastify": "^5.6.2",
-    "find-my-way": "^9.3.0",
+    "fastify": "^5.12.5",
+    "find-my-way": "^9.9.0",
     "get-tsconfig": "^5.0.0-beta.5",
     "import-meta-resolve": "^4.2.0",
     "mime": "^4.1.0",
@@ -52,10 +52,11 @@
     "@aws-sdk/lib-storage": "^3.955.0",
     "@aws-sdk/s3-request-presigner": "^3.955.0",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/access": "5.24.0",
-    "@warlock.js/ai": "5.24.0",
-    "@warlock.js/herald": "5.24.0",
-    "@warlock.js/notifications": "5.24.0",
+    "@warlock.js/access": "5.26.0",
+    "@warlock.js/ai": "5.26.0",
+    "@warlock.js/herald": "5.26.0",
+    "@warlock.js/notifications": "5.26.0",
+    "@warlock.js/devtools": "5.26.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -104,6 +105,9 @@
     },
     "@warlock.js/notifications": {
       "optional": true
+    },
+    "@warlock.js/devtools": {
+      "optional": true
     }
   },
   "repository": {
@@ -123,7 +127,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.24.0",
+  "version": "5.26.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/README.md

@@ -34,7 +34,7 @@ Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The
 - [use-app-context](use-app-context/SKILL.md) — read app-wide context via the `Application` static class and the `app` runtime accessor.
 - [add-connector](add-connector/SKILL.md) — extend the lifecycle with a `BaseConnector` subclass (`start`/`shutdown`/`watchedFiles`).
 - [wire-socket](wire-socket/SKILL.md) — configure Socket.IO, reach the live server via `getSocketServer()` / `app.socket`.
-- [use-localization](use-localization/SKILL.md) — multi-locale translations: `groupedTranslations`, `t()` / `request.t()`, locale resolution.
+- [use-localization](use-localization/SKILL.md) — multi-locale translations: `groupedTranslations`, `t()` (always, never `request.t()`), locale resolution.
 
 ## Use-cases & services
 

package/skills/configure-app/SKILL.md

@@ -229,6 +229,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`):

package/skills/create-controller/SKILL.md

@@ -102,6 +102,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`:

package/skills/define-resource/SKILL.md

@@ -221,6 +221,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:

package/skills/request-tracing/SKILL.md

@@ -55,6 +55,7 @@ type TracingContext = {
 type TracingPhaseInfo = {
   name: string;
   durationMs: number;
+  startedAt?: number; // epoch milliseconds; supplied when the phase started
   attrs?: Record<string, unknown>;
 };
 
@@ -73,29 +74,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
 
@@ -189,9 +213,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`.

package/skills/run-app/SKILL.md

@@ -28,11 +28,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.
 
@@ -40,14 +40,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.
 
@@ -67,7 +67,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.
 
@@ -81,13 +81,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
 
@@ -103,7 +103,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.
@@ -165,12 +165,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
   },
 });
 ```
@@ -182,8 +183,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.
 
@@ -241,6 +243,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
@@ -283,9 +320,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`**.
@@ -321,7 +358,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.
 
@@ -336,7 +373,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:
@@ -351,11 +388,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.
 
@@ -414,7 +451,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:
 

package/skills/send-mail/SKILL.md

@@ -12,10 +12,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:
@@ -59,10 +56,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"),
+    },
   },
 };
 ```
@@ -94,9 +106,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.
@@ -109,7 +121,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")
@@ -150,15 +162,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
 
@@ -171,9 +183,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();
 ```
 
@@ -243,6 +255,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
@@ -296,10 +325,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;
 };
 ```