@warlock.js/core 5.2.3 → 5.3.0

package/llms.txt

@@ -42,7 +42,7 @@
 - [warlock-doctor](@warlock.js/core/warlock-doctor/SKILL.md): Run `warlock doctor` — a read-only diagnostics command that checks routes / config / connectors / optional-peers / health endpoints / release hygiene and prints a pass/warn/fail report, exiting non-zero on any failure. Add your own probe with the `DoctorCheck` contract and `runChecks` / `formatReportLines`. Triggers: `warlock doctor`, `doctorCommand`, `DoctorCheck`, `CheckResult`, `CheckStatus`, `DoctorReport`, `runChecks`, `formatReportLines`, `printReport`, `defaultDoctorChecks`; "diagnose my app", "preflight / preflight check", "is the app healthy", "why are there 0 routes", "pre-release sanity check", "CI smoke check"; run as `pnpm warlock doctor`. Skip: the live `/health` + `/ready` HTTP probes — `@warlock.js/core/health-checks/SKILL.md`; authoring a general CLI command — `@warlock.js/core/write-cli-command/SKILL.md`; releasing the package — `releasing-warlock-monorepo`; competing tools `npm doctor`, `nest info`, hand-rolled preflight scripts.
 - [warlock-routes](@warlock.js/core/warlock-routes/SKILL.md): Run `warlock routes` — a read-only command that lists the registered HTTP routes as a verb-colored table (method / path / name / action / middleware-count / source), a sibling of `warlock doctor`. Filter with `--method` / `--path` / `--name`, or emit normalized rows as JSON with `--json`. Also covers `warlock routes:diff`, which compares live page routes against the last `warlock build`'s route snapshot and exits non-zero on drift. Triggers: `warlock routes`, `routesCommand`, `warlock routes:diff`, `routesDiffCommand`, "list my routes", "show all routes", "route table", "what endpoints does my app expose", "dump routes as JSON", "which routes have middleware", "route map for CI", "did my page routes drift from the last build"; run as `pnpm warlock routes` / `pnpm warlock routes:diff`. Skip: read-only health/preflight checks — `@warlock.js/core/warlock-doctor/SKILL.md`; defining/naming/grouping routes — `@warlock.js/core/register-route/SKILL.md`; authoring a general CLI command — `@warlock.js/core/write-cli-command/SKILL.md`; competing tools `nest`/`express` route listers, `php artisan route:list`.
 - [wire-socket](@warlock.js/core/wire-socket/SKILL.md): Configure Socket.IO via `src/config/socket.ts`, reach the live server through `getSocketServer()` (or `app.socket` post-bootstrap), register `connection` handlers once the late-phase socket connector has booted, emit from controllers/services, use rooms and namespaces. Triggers: `app.socket`, `getSocketServer`, `SocketOptions`, `socket.io` `Server`, `socket.join`, `socket.to`, `io.of`, `io.use`; "add realtime chat", "emit socket events from a service", "use rooms and namespaces", "per-socket JWT auth". Skip: connector lifecycle — `@warlock.js/core/add-connector/SKILL.md`; app context accessors — `@warlock.js/core/use-app-context/SKILL.md`; competing libs `ws`, `socket.io` direct without Warlock connector, `uWebSockets.js`.
-- [write-cli-command](@warlock.js/core/write-cli-command/SKILL.md): Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.
-- [write-middleware](@warlock.js/core/write-middleware/SKILL.md): Author HTTP middleware for @warlock.js/core — the `(request, response)` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.
+- [write-cli-command](@warlock.js/core/write-cli-command/SKILL.md): Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Also covers built-in `warlock add` feature scaffolding, including the Web starter and `index.register.ts`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`, `warlock add`, `index.register.ts`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.
+- [write-middleware](@warlock.js/core/write-middleware/SKILL.md): Author HTTP middleware for @warlock.js/core — the `({ request, response })` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.
 - [write-seeder](@warlock.js/core/write-seeder/SKILL.md): Author a seed file under `src/app/<module>/seeds/<name>.ts` using the `seeder()` factory — `name`, `dependsOn`, `once`, `order`, `batchSize`, `run({ track, now, batchSize })`. Auto-discovered by `warlock seed`; tracked in a `seeds` table; per-record refs in `seed_records` so `warlock seed --drop` can undo a seed. Triggers: `seeder`, `Seeder`, `SeedResult`, `SeedContext`, `SeedClock`, `track`, `now`, `batchSize`, `SeedersManager`, `warlock seed`, `--fresh`, `--drop`, `--list`, `--path`; "seed default roles", "undo a seed", "one-time data migration", "auto-discovered seeds", "order seeds by dependency", "deterministic seed timestamps", "inject a seed clock"; typical import `import { seeder } from "@warlock.js/core"`. Skip: module folder layout — `@warlock.js/core/create-module/SKILL.md`; repository CRUD — `@warlock.js/core/use-repository/SKILL.md`; CLI flags — `@warlock.js/core/write-cli-command/SKILL.md`; competing patterns: hand-rolled `node scripts/seed.js`, `typeorm-seeding`.
 - [write-use-case](@warlock.js/core/write-use-case/SKILL.md): Author `useCase()` pipelines for business logic — guards, schema, before/after middleware, retry, benchmark, broadcast, lifecycle callbacks; transport-agnostic and observable by default. Input is inferred from the `schema`. Triggers: `useCase`, `UseCaseContext`, `UseCaseResult`, `retry`, `benchmark`, `broadcast`, `description`, `globalUseCasesEvents`, `UseCaseBroadcastChannel`; "encapsulate a business operation", "share logic between HTTP and CLI", "add guards and lifecycle hooks", "broadcast a use case result", "transport-agnostic pipeline"; typical import `import { useCase } from "@warlock.js/core"`. Skip: thin handler shape — `@warlock.js/core/create-controller/SKILL.md`; schema details — `@warlock.js/core/validate-input/SKILL.md`; the standalone retry util — `@warlock.js/core/retry-operation/SKILL.md`; competing libs `@nestjs/cqrs`, `inversify`, hand-rolled service classes.

package/package.json

@@ -25,13 +25,13 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.4",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/auth": "5.2.3",
-    "@warlock.js/cache": "5.2.3",
-    "@warlock.js/cascade": "5.2.3",
-    "@warlock.js/context": "5.2.3",
-    "@warlock.js/logger": "5.2.3",
-    "@warlock.js/seal": "5.2.3",
-    "@warlock.js/fs": "5.2.3",
+    "@warlock.js/auth": "5.3.0",
+    "@warlock.js/cache": "5.3.0",
+    "@warlock.js/cascade": "5.3.0",
+    "@warlock.js/context": "5.3.0",
+    "@warlock.js/logger": "5.3.0",
+    "@warlock.js/seal": "5.3.0",
+    "@warlock.js/fs": "5.3.0",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
@@ -57,10 +57,10 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/herald": "5.2.3",
-    "@warlock.js/ai": "5.2.3",
-    "@warlock.js/access": "5.2.3",
-    "@warlock.js/notifications": "5.2.3"
+    "@warlock.js/herald": "5.3.0",
+    "@warlock.js/ai": "5.3.0",
+    "@warlock.js/access": "5.3.0",
+    "@warlock.js/notifications": "5.3.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -123,7 +123,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.2.3",
+  "version": "5.3.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/README.md

@@ -10,7 +10,7 @@ Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The
 - [send-response](send-response/SKILL.md) — `Response` helpers: success/error variants, status helpers, redirects, files, streams, SSE.
 - [validate-input](validate-input/SKILL.md) — author seal schemas, attach them to controllers, infer types, layer DTOs.
 - [use-middleware](use-middleware/SKILL.md) — attach built-in HTTP middleware (rateLimit, concurrencyLimit, maxBodySize, …) via the `middleware` namespace.
-- [write-middleware](write-middleware/SKILL.md) — author HTTP middleware: the `(request, response)` signature, short-circuit, request enrichment.
+- [write-middleware](write-middleware/SKILL.md) — author HTTP middleware: the `({ request, response })` signature, short-circuit, request enrichment.
 - [build-url](build-url/SKILL.md) — HTTP URL helpers (`url`, `publicUrl`, `assetsUrl`, `uploadsUrl`) anchored at `app.baseUrl`.
 - [upload-file](upload-file/SKILL.md) — handle multipart uploads: `request.file()`, `v.file()` validation, `UploadedFile.save()`.
 - [health-checks](health-checks/SKILL.md) — built-in `/health` + `/ready` endpoints, the `health` registry, and graceful request draining.
@@ -45,7 +45,7 @@ Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The
 
 - [warlock-doctor](warlock-doctor/SKILL.md) — `warlock doctor`: read-only diagnostics (routes/config/connectors/optional-peers/health/release-hygiene) with a pass/warn/fail report and non-zero exit on failure.
 - [warlock-routes](warlock-routes/SKILL.md) — `warlock routes`: list the registered HTTP routes as a verb-colored table (method/path/name/action/middleware/source); filter by method/path/name or emit JSON. Read-only, no connectors.
-- [write-cli-command](write-cli-command/SKILL.md) — author a custom `warlock <cmd>` via the `command()` factory (name, action, options, preload).
+- [write-cli-command](write-cli-command/SKILL.md) — author a custom `warlock <cmd>` via the `command()` factory, or inspect built-in `warlock add` feature scaffolding such as the Web starter.
 - [run-app](run-app/SKILL.md) — `warlock dev` / `warlock build` / `warlock start` operational commands.
 - [update-packages](update-packages/SKILL.md) — bump every `@warlock.js/*` dependency with `warlock update`.
 

package/skills/create-controller/SKILL.md

@@ -12,7 +12,7 @@ A controller is a thin function: pull inputs from `request`, call work, return t
 ```ts title="src/app/<module>/controllers/<action>.controller.ts"
 import { type RequestHandler } from "@warlock.js/core";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   return response.success({ products: [] });
 };
 ```
@@ -67,10 +67,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -96,10 +96,10 @@ Routes behind `authMiddleware` need `request.user` typed. Project conventions ad
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   // request.user is typed
   const product = await createProductService(request.validated());
   return response.successCreate({ product });
@@ -146,7 +146,7 @@ If your controller is over ~30 lines, the work probably belongs in a service.
 import { type RequestHandler } from "@warlock.js/core";
 import { listProductsService } from "../services/list-products.service";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   const { data: products, pagination } = await listProductsService({
     ...request.all(),
     organization_id: request.user.organizationId,
@@ -163,10 +163,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -200,7 +200,7 @@ export async function getProductService(id: string) {
 import type { RequestHandler } from "@warlock.js/core";
 import { getProductService } from "../services/get-product.service";
 
-export const getProductController: RequestHandler = async (request, response) => {
+export const getProductController: RequestHandler = async ({ request, response }) => {
   const product = await getProductService(request.input("id"));
 
   return response.success({ product });

package/skills/send-response/SKILL.md

@@ -10,9 +10,9 @@ description: 'Send HTTP responses via @warlock.js/core''s Response helpers — s
 ## The shape
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import type { RequestHandler } from "@warlock.js/core";
 
-export const myController: RequestHandler = async (request, response: Response) => {
+export const myController: RequestHandler = async ({ request, response }) => {
   // …choose a helper and return it
   return response.success({ data: "…" });
 };
@@ -22,11 +22,11 @@ Always `return response.<helper>(...)`. The return value drives Fastify's send.
 
 ## Success helpers
 
-| Method                              | Status | When                                      |
-| ----------------------------------- | ------ | ----------------------------------------- |
-| `response.success(data?)`           | 200    | normal read / update                      |
-| `response.successCreate(data)`      | 201    | resource created (POST)                   |
-| `response.noContent()`              | 204    | delete succeeded, no body needed          |
+| Method                         | Status | When                             |
+| ------------------------------ | ------ | -------------------------------- |
+| `response.success(data?)`      | 200    | normal read / update             |
+| `response.successCreate(data)` | 201    | resource created (POST)          |
+| `response.noContent()`         | 204    | delete succeeded, no body needed |
 
 ```ts
 return response.success({ products: [...] });
@@ -40,13 +40,13 @@ return response.noContent();
 
 ## Client-error helpers
 
-| Method                                              | Status | When                                  |
-| --------------------------------------------------- | ------ | ------------------------------------- |
-| `response.badRequest(data)`                         | 400    | malformed or invalid input            |
-| `response.unauthorized(data?)`                      | 401    | missing/invalid auth token            |
-| `response.forbidden(data?)`                         | 403    | authenticated but not allowed         |
-| `response.notFound(data?)`                          | 404    | record missing                        |
-| `response.conflict(data?)`                          | 409    | uniqueness violation, state conflict  |
+| Method                         | Status | When                                 |
+| ------------------------------ | ------ | ------------------------------------ |
+| `response.badRequest(data)`    | 400    | malformed or invalid input           |
+| `response.unauthorized(data?)` | 401    | missing/invalid auth token           |
+| `response.forbidden(data?)`    | 403    | authenticated but not allowed        |
+| `response.notFound(data?)`     | 404    | record missing                       |
+| `response.conflict(data?)`     | 409    | uniqueness violation, state conflict |
 
 ```ts
 return response.badRequest({ error: t("validation.invalid") });
@@ -65,8 +65,8 @@ Most error helpers accept an optional payload — if you omit it, they send a de
 ## Redirects
 
 ```ts
-return response.redirect("/login");                    // 302
-return response.redirect("/new-home", 301);            // permanent
+return response.redirect("/login"); // 302
+return response.redirect("/new-home", 301); // permanent
 ```
 
 ## Files
@@ -98,19 +98,19 @@ stream.end();
 
 ## Throwing HTTP errors
 
-Most of the time, controllers don't need to *choose* an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
+Most of the time, controllers don't need to _choose_ an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
 
 ```ts
 import {
-  ResourceNotFoundError,   // 404
-  UnAuthorizedError,        // 401
-  ForbiddenError,           // 403
-  BadRequestError,          // 400
-  ConflictError,            // 409
-  NotAcceptableError,       // 406
-  NotAllowedError,          // 405
-  ServerError,              // 500
-  HttpError,                // base class — `new HttpError(status, message, payload?)` for arbitrary codes
+  ResourceNotFoundError, // 404
+  UnAuthorizedError, // 401
+  ForbiddenError, // 403
+  BadRequestError, // 400
+  ConflictError, // 409
+  NotAcceptableError, // 406
+  NotAllowedError, // 405
+  ServerError, // 500
+  HttpError, // base class — `new HttpError(status, message, payload?)` for arbitrary codes
 } from "@warlock.js/core";
 
 throw new ResourceNotFoundError("product.notFound");
@@ -118,13 +118,27 @@ throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
 ```
 
-Each class takes `(message, payload?)`. The payload merges into the response body alongside `error`. In development mode, the stack trace is included too.
+Each class takes `(message, payload?)`. The framework keeps the optional
+detail nested under `payload`:
+
+```json
+{
+  "error": "Product not found",
+  "payload": { "id": 42 }
+}
+```
+
+Every unhandled error response also carries
+`Cache-Control: private, no-store`, regardless of status. The floor is
+applied once at the shared error funnel, so API-route errors cannot be stored
+and replayed across users. In development mode, the stack trace is included
+too.
 
 Pick the class, throw from the service or use-case, and forget about response shaping at the call site. The controller stays focused on the success path:
 
 ```ts
-export const getProductController: RequestHandler = async (request, response) => {
-  const product = await getProductService(request.input("id"));   // throws ResourceNotFoundError on miss
+export const getProductController: RequestHandler = async ({ request, response }) => {
+  const product = await getProductService(request.input("id")); // throws ResourceNotFoundError on miss
   return response.success({ product });
 };
 ```
@@ -136,9 +150,9 @@ See [`create-controller`](../create-controller/SKILL.md) for the "throw from ser
 ```ts
 const sse = response.sse();
 
-sse.send("tick", { count: 1 });             // event name, data, optional id
-sse.send("tick", { count: 2 }, "msg-2");    // third arg is the SSE event id
-sse.comment("keep-alive");                  // invisible to the client, prevents timeout
+sse.send("tick", { count: 1 }); // event name, data, optional id
+sse.send("tick", { count: 2 }, "msg-2"); // third arg is the SSE event id
+sse.comment("keep-alive"); // invisible to the client, prevents timeout
 sse.end();
 ```
 
@@ -178,11 +192,11 @@ response.clearCookie("session_id");
 
 Every response cookie gets `httpOnly: true`, `sameSite: "lax"`, and `secure: true` outside development, unless you override them:
 
-| Flag | Default | Why it's the default |
-|---|---|---|
-| `httpOnly` | `true` | without it, any injected script can read the cookie |
-| `sameSite` | `"lax"` | without it, the cookie rides along on cross-site requests |
-| `secure` | `true`, except in development | without it, the cookie travels in cleartext |
+| Flag       | Default                       | Why it's the default                                      |
+| ---------- | ----------------------------- | --------------------------------------------------------- |
+| `httpOnly` | `true`                        | without it, any injected script can read the cookie       |
+| `sameSite` | `"lax"`                       | without it, the cookie rides along on cross-site requests |
+| `secure`   | `true`, except in development | without it, the cookie travels in cleartext               |
 
 `secure` is relaxed in development only — browsers drop a `Secure` cookie over plain http, which would silently break every local login. It stays on in test and staging.
 

package/skills/store-file/SKILL.md

@@ -345,12 +345,17 @@ Set `STORAGE_DRIVER=r2` in production, leave unset in dev — same code uses loc
 ### Uploading a request file
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { storage } from "@warlock.js/core";
 
-export const uploadAvatarController: RequestHandler = async (request, response: Response) => {
+export const uploadAvatarController: GuardedRequestHandler = async ({ request, response }) => {
   const upload = request.file("avatar");
-  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.fileName}`);
+
+  if (!upload) {
+    return response.badRequest({ error: "missing file" });
+  }
+
+  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.name}`);
 
   return response.successCreate({ url: file.url, hash: file.hash });
 };

package/skills/upload-file/SKILL.md

@@ -9,8 +9,8 @@ Multipart uploads come in as `UploadedFile` instances. The class wraps Fastify's
 
 ## The shape
 
-```ts title="src/app/uploads/schema/index.ts"
-import { v } from "@warlock.js/seal";
+```ts title="src/app/uploads/schema/upload-avatar.schema.ts"
+import { v, type Infer } from "@warlock.js/seal";
 
 export const uploadAvatarSchema = v.object({
   avatar: v
@@ -19,16 +19,18 @@ export const uploadAvatarSchema = v.object({
     .maxSize({ unit: "MB", size: 5 })
     .mimeType(["image/jpeg", "image/png", "image/webp"]),
 });
+
+export type UploadAvatarSchema = Infer<typeof uploadAvatarSchema>;
 ```
 
 ```ts title="src/app/uploads/controllers/upload-avatar.controller.ts"
-import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type UploadAvatarSchema, uploadAvatarSchema } from "../schema/upload-avatar.schema";
 
-export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async (
+export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const { avatar } = request.validated();
 
   const file = await avatar
@@ -54,7 +56,7 @@ Inside a controller:
 ```ts
 import type { RequestHandler, UploadedFile } from "@warlock.js/core";
 
-export const uploadController: RequestHandler = async (request, response) => {
+export const uploadController: RequestHandler = async ({ request, response }) => {
   // option A — direct from request, no validation
   const file: UploadedFile | undefined = request.file("avatar");
 
@@ -236,7 +238,7 @@ export const uploadFilesSchema = v.object({
 ```ts title="src/app/uploads/controllers/create-upload.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const createUploadController: RequestHandler = async (request, response) => {
+export const createUploadController: RequestHandler = async ({ request, response }) => {
   const { files } = request.validated();
 
   const saved = await Promise.all(

package/skills/use-app-context/SKILL.md

@@ -232,9 +232,9 @@ const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-
 ### Health endpoint
 
 ```ts title="src/app/system/controllers/health.controller.ts"
-import { Application, type RequestHandler, type Response } from "@warlock.js/core";
+import { Application, type RequestHandler } from "@warlock.js/core";
 
-export const healthController: RequestHandler = async (_request, response: Response) => {
+export const healthController: RequestHandler = async ({ response }) => {
   return response.success({
     status: "ok",
     environment: Application.environment,

package/skills/use-localization/SKILL.md

@@ -229,10 +229,14 @@ The error's message is locale-aware — the `inject-request-context` middleware
 ### Translated response message in a controller
 
 ```ts
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { type CreateProductSchema } from "../schema/create-product.schema";
+import { createProductService } from "../services/create-product.service";
+
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
   return response.success({
     message: request.t("products.created"),

package/skills/use-repository/SKILL.md

@@ -276,10 +276,10 @@ export async function listFaqsService(filters: FaqListOptions) {
 ```
 
 ```ts title="src/app/faqs/controllers/list-faqs.controller.ts"
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { listFaqsService } from "../services/list-faqs.service";
 
-export const listFaqsController: RequestHandler = async (request, response: Response) => {
+export const listFaqsController: GuardedRequestHandler = async ({ request, response }) => {
   const { data, pagination } = await listFaqsService({
     ...request.all(),
     organization_id: request.user.organizationId,

package/skills/use-request-locals/SKILL.md

@@ -30,7 +30,7 @@ public locals: RequestLocals = {};
 ```ts title="src/app/observability/middleware/request-timing.middleware.ts"
 import type { Middleware } from "@warlock.js/core";
 
-export const requestTimingMiddleware: Middleware = request => {
+export const requestTimingMiddleware: Middleware = (request) => {
   request.startedAt = Date.now();
 };
 ```
@@ -38,7 +38,7 @@ export const requestTimingMiddleware: Middleware = request => {
 ```ts title="src/app/observability/controllers/timing.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const timingController: RequestHandler = async (request, response) => {
+export const timingController: RequestHandler = async ({ request, response }) => {
   return response.success({ elapsedMs: Date.now() - request.startedAt });
 };
 ```
@@ -123,7 +123,7 @@ Feature-local files such as `src/app/organizations/request-locals.d.ts` are equa
 
 Two rules the scaffold's own comments spell out, and both bite silently:
 
-- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an *ambient* module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
+- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an _ambient_ module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
 - **Keep them `interface`, not `type`.** This project otherwise prefers `type`; these are the named exception, because declaration merging is interface-only. `type RequestUser = { ... }` is a duplicate-identifier error, not an augmentation.
 
 On a project scaffolded before 5.1 there is no `src/typings.d.ts`, and `tsconfig.json` carries `"typeRoots": ["./src/typings.d.ts"]` — wrong twice, since `typeRoots` takes directories of `@types` packages rather than files, and that file did not exist. Drop the `typeRoots` entry, create the file, and list it under `include`.

package/skills/validate-input/SKILL.md

@@ -26,10 +26,10 @@ import type { Request, RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });

package/skills/warlock-conventions/SKILL.md

@@ -38,11 +38,11 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    ```
 
    ```ts title="src/app/<module>/controllers/create-<thing>.controller.ts"
-   import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+   import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
    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 });
    };

package/skills/wire-socket/SKILL.md

@@ -123,10 +123,10 @@ export async function notifyUserService(user: User, payload: unknown) {
 Then from a controller:
 
 ```ts
-import type { GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import type { GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { notifyUserService } from "../services/notify-user.service";
 
-export const sendNotificationController: GuardedRequestHandler = async (request, response) => {
+export const sendNotificationController: GuardedRequestHandler = async ({ request, response }) => {
   await notifyUserService(request.user, request.input("payload"));
   return response.success({ delivered: true });
 };

package/skills/write-cli-command/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-cli-command
-description: 'Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.'
+description: 'Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Also covers built-in `warlock add` feature scaffolding, including the Web starter and `index.register.ts`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`, `warlock add`, `index.register.ts`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.'
 ---
 
 # Warlock — write a CLI command
@@ -205,6 +205,7 @@ warlock generate                         (alias: g)      — interactive picker
 | 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                                                                       |
 | `image`       | `sharp` (for the `Image` class)                                                                     |
 | `mail`        | `nodemailer` + types                                                                                |
@@ -222,6 +223,8 @@ warlock generate                         (alias: g)      — interactive picker
 
 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).
 
+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                                                     |