@warlock.js/core 5.29.0 → 5.31.0

package/skills/create-module/SKILL.md

@@ -14,7 +14,7 @@ npx warlock generate.module products            # full CRUD bootstrap (default
 npx warlock generate.module products --minimal  # bare bones (routes.ts + main.ts + utils/locales.ts + empty subfolders)
 ```
 
-Full CRUD is the default — opt down to a bare skeleton with `--minimal` (`-m`) when you want to build the module piece by piece. `--force` (`-f`) overwrites existing files. The plural form is auto-derived: `generate.module product` and `generate.module products` produce the same `src/app/products/` folder.
+Full CRUD is the default — opt down to a bare skeleton with `--minimal` (`-m`) when you want to build the module piece by piece. `--force` (`-f`) overwrites existing files. Every generator takes `--dry-run` (write nothing, list the plan) and `--json` (one machine-readable report on stdout). To add one endpoint from its request schema — controller, service, resource, route, locale key and an HTTP test — use `warlock make endpoint` (the `make-endpoint` topic). The plural form is auto-derived: `generate.module product` and `generate.module products` produce the same `src/app/products/` folder.
 
 ## What the generator creates
 
@@ -76,7 +76,7 @@ Run after `generate.module` to fill in gaps or add to an existing module.
 | Command                                         | Alias     | Flags                                                             |
 | ----------------------------------------------- | --------- | ----------------------------------------------------------------- |
 | `warlock generate.module <name>`                | `gen.m`   | `--minimal` (`-m`), `--force`                                     |
-| `warlock generate.controller <module>/<action>` | `gen.c`   | `--with-validation` (also generates the `schema/` file)            |
+| `warlock generate.controller <module>/<action>` | `gen.c`   | `--with-validation` (also generates the `schema/` file)           |
 | `warlock generate.service <module>/<action>`    | `gen.s`   | `--force`                                                         |
 | `warlock generate.model <module>/<entity>`      | `gen.md`  | `--with-resource`, `--table <name>`, `--timestamps`               |
 | `warlock generate.repository <module>/<entity>` | `gen.r`   | `--force`                                                         |
@@ -85,7 +85,7 @@ Run after `generate.module` to fill in gaps or add to an existing module.
 
 The DSL for `--add` is `name:type:modifier,…` — see `write-cli-command` and the column-DSL parser in `@warlock.js/core/src/cli/commands/generate/generators/column-dsl-parser.ts`.
 
-Every `generate.*` command (and the master `generate`) also accepts **`--dry-run`** — it prints the files it *would* create and writes nothing. Run it before a full `generate.module` scaffold or any `--force` to preview the blast radius.
+Every `generate.*` command (and the master `generate`) also accepts **`--dry-run`** — it prints the files it _would_ create and writes nothing. Run it before a full `generate.module` scaffold or any `--force` to preview the blast radius.
 
 ## Path alias
 

package/skills/define-resource/SKILL.md

@@ -53,20 +53,20 @@ Default to `defineResource`. Reach for a subclass only when a hook would be ugli
 
 ## Cast types
 
-| Cast        | Source                  | Output                                        |
-| ----------- | ----------------------- | --------------------------------------------- |
-| `string`    | any                     | `String(value)`                               |
-| `number`    | any                     | `Number(value)` (NaN → `undefined` or `null`) |
-| `int`       | any                     | `parseInt(value)`                             |
-| `float`     | any                     | `parseFloat(value)`                           |
-| `boolean`   | any                     | `Boolean(value)`                              |
-| `date`      | `Date` / ISO string     | configurable object (format/iso/timestamp/humanTime) |
-| `localized` | `LocalizedObject[]`     | string for the request's locale               |
-| `url`       | path                    | absolute URL via `url()` helper               |
-| `uploadsUrl`| path                    | absolute URL under the uploads prefix         |
-| `storageUrl`| path                    | absolute URL via `storage.url(...)`           |
-| `object`    | any object              | passes through if non-empty object            |
-| `array`     | any                     | passes through if array                       |
+| Cast         | Source              | Output                                               |
+| ------------ | ------------------- | ---------------------------------------------------- |
+| `string`     | any                 | `String(value)`                                      |
+| `number`     | any                 | `Number(value)` (NaN → `undefined` or `null`)        |
+| `int`        | any                 | `parseInt(value)`                                    |
+| `float`      | any                 | `parseFloat(value)`                                  |
+| `boolean`    | any                 | `Boolean(value)`                                     |
+| `date`       | `Date` / ISO string | configurable object (format/iso/timestamp/humanTime) |
+| `localized`  | `LocalizedObject[]` | string for the request's locale                      |
+| `url`        | path                | absolute URL via `url()` helper                      |
+| `uploadsUrl` | path                | absolute URL under the uploads prefix                |
+| `storageUrl` | path                | absolute URL via `storage.url(...)`                  |
+| `object`     | any object          | passes through if non-empty object                   |
+| `array`      | any                 | passes through if array                              |
 
 ### Suffix modifiers
 
@@ -232,20 +232,20 @@ const json = new UserResource(user).toJSON(); // typed as UserJson
 
 How each schema entry is typed:
 
-| Schema entry                                                      | Output type                                                           |
-| ----------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `"string"`, `"localized"`, `"url"`, `"uploadsUrl"`, `"storageUrl"` | `string`                                                              |
-| `"number"`, `"float"`, `"int"`                                    | `number`                                                              |
-| `"boolean"`                                                       | `boolean`                                                             |
-| `"date"`                                                          | `{ iso: string; format: string; timestamp: number; humanTime: string }` (the default date output) |
-| `"object"` / `"array"`                                            | `Record<string, unknown>` / `unknown[]`                               |
-| `"x[]"`                                                           | array of the base type                                                |
-| `"x?"`                                                            | `T \| null`; the key is always present, never optional               |
-| a nested resource, `lazy(() => R)`                                | that resource's output (one object, even if the model holds an array) |
-| `"self"` / `"self[]"`                                             | this resource's own output / an array of it                           |
-| `["inputKey", "cast"]` tuple                                      | the cast's type                                                       |
-| a resolver function                                               | its return type (an `any` return becomes `unknown`)                   |
-| a field builder (`this.date()...`, `new ResourceFieldBuilder(...)`) | `unknown`                                                             |
+| Schema entry                                                        | Output type                                                                                       |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `"string"`, `"localized"`, `"url"`, `"uploadsUrl"`, `"storageUrl"`  | `string`                                                                                          |
+| `"number"`, `"float"`, `"int"`                                      | `number`                                                                                          |
+| `"boolean"`                                                         | `boolean`                                                                                         |
+| `"date"`                                                            | `{ iso: string; format: string; timestamp: number; humanTime: string }` (the default date output) |
+| `"object"` / `"array"`                                              | `Record<string, unknown>` / `unknown[]`                                                           |
+| `"x[]"`                                                             | array of the base type                                                                            |
+| `"x?"`                                                              | `T \| null`; the key is always present, never optional                                            |
+| a nested resource, `lazy(() => R)`                                  | that resource's output (one object, even if the model holds an array)                             |
+| `"self"` / `"self[]"`                                               | this resource's own output / an array of it                                                       |
+| `["inputKey", "cast"]` tuple                                        | the cast's type                                                                                   |
+| a resolver function                                                 | its return type (an `any` return becomes `unknown`)                                               |
+| a field builder (`this.date()...`, `new ResourceFieldBuilder(...)`) | `unknown`                                                                                         |
 
 The type reflects the schema only, not the data: mark a field `?` when the model may not have a value. `boot`, `extend`, `transform` and builders can change the real shape; when they do, state the output with a type argument, which replaces the inferred type:
 
@@ -296,7 +296,10 @@ Rules, in the order the runtime applies them:
 ```ts title=".warlock/typings/model-resources.d.ts (generated)"
 declare module "@warlock.js/core" {
   interface ModelResourceRegistry {
-    "User": { model: import("../../src/app/users/models/user.model").User; resource: typeof import("../../src/app/users/resources/user.resource").UserResource };
+    User: {
+      model: import("../../src/app/users/models/user.model").User;
+      resource: typeof import("../../src/app/users/resources/user.resource").UserResource;
+    };
   }
 }
 ```

package/skills/encrypt-data/SKILL.md

@@ -7,10 +7,10 @@ description: 'Reversible AES-256-GCM `encrypt` / `decrypt` for secrets you need
 
 Two helpers, two different jobs:
 
-| Tool                    | Direction  | Algorithm    | Use for                                                        |
-| ----------------------- | ---------- | ------------ | -------------------------------------------------------------- |
-| `encrypt` / `decrypt`   | reversible | AES-256-GCM  | Secrets you need to read back (API keys, OAuth tokens).        |
-| `hmacHash`              | one-way    | HMAC-SHA256  | Deterministic fingerprint for lookup/dedup of encrypted values. |
+| Tool                  | Direction  | Algorithm   | Use for                                                         |
+| --------------------- | ---------- | ----------- | --------------------------------------------------------------- |
+| `encrypt` / `decrypt` | reversible | AES-256-GCM | Secrets you need to read back (API keys, OAuth tokens).         |
+| `hmacHash`            | one-way    | HMAC-SHA256 | Deterministic fingerprint for lookup/dedup of encrypted values. |
 
 Both live in `@warlock.js/core`. For **password hashing** (a one-way job with very different requirements), reach for the `hash-password` topic instead — bcrypt is the right tool there, not encrypt.
 
@@ -34,9 +34,9 @@ import type { EncryptionConfigurations } from "@warlock.js/core";
 import { env } from "@warlock.js/core";
 
 const encryptionConfig: EncryptionConfigurations = {
-  key: env("APP_ENCRYPTION_KEY"),     // 64 hex chars = 32 bytes — required
-  algorithm: "aes-256-gcm",            // optional, default
-  hmacKey: env("APP_HMAC_KEY"),       // 64 hex chars — falls back to `key` if absent
+  key: env("APP_ENCRYPTION_KEY"), // 64 hex chars = 32 bytes — required
+  algorithm: "aes-256-gcm", // optional, default
+  hmacKey: env("APP_HMAC_KEY"), // 64 hex chars — falls back to `key` if absent
 };
 
 export default encryptionConfig;
@@ -71,8 +71,8 @@ export async function createAiApiKeyService(data: { key: string; organization_id
 
   return AiApiKey.create({
     ...data,
-    key: encrypt(data.key),                // the secret, recoverable
-    hash: hmacHash(data.key),              // the fingerprint, lookup-able
+    key: encrypt(data.key), // the secret, recoverable
+    hash: hmacHash(data.key), // the fingerprint, lookup-able
     last_four_chars: data.key.slice(-4),
   });
 }
@@ -133,8 +133,8 @@ log.info("api-key", "used", { fingerprint: hmacHash(apiKey).slice(0, 8) });
 ```ts
 await Model.create({
   key: encrypt(plain),
-  hash: hmacHash(plain),                   // for lookups
-  last_four_chars: plain.slice(-4),         // for UI display ("ending in 1234")
+  hash: hmacHash(plain), // for lookups
+  last_four_chars: plain.slice(-4), // for UI display ("ending in 1234")
 });
 ```
 
@@ -163,7 +163,7 @@ Keeps the encryption boundary in one place — controllers and services deal in
 ```ts
 log.info("ai-api-key", "used", {
   organization_id,
-  fingerprint: hmacHash(apiKey).slice(0, 8),  // first 8 hex chars = enough to correlate
+  fingerprint: hmacHash(apiKey).slice(0, 8), // first 8 hex chars = enough to correlate
 });
 ```
 
@@ -172,13 +172,15 @@ You can search logs for the same fingerprint to track usage of a specific key ac
 ### Idempotency keys
 
 ```ts
-const idempotencyKey = hmacHash(JSON.stringify({
-  user_id: user.id,
-  action: "transfer",
-  amount,
-  to,
-  // include a monotonic component if the same exact payload should be allowed twice
-}));
+const idempotencyKey = hmacHash(
+  JSON.stringify({
+    user_id: user.id,
+    action: "transfer",
+    amount,
+    to,
+    // include a monotonic component if the same exact payload should be allowed twice
+  }),
+);
 
 const existing = await idempotencyRepository.first({ key: idempotencyKey });
 if (existing) return existing.get("result");

package/skills/generate-openapi/SKILL.md

@@ -16,12 +16,12 @@ Routes are read in the same isolated registration child process `warlock build`
 
 ## Options
 
-| Option            | Default                                        | Meaning                                                      |
-| ----------------- | ---------------------------------------------- | ------------------------------------------------------------ |
-| `--out`, `-o`     | `storage/openapi/openapi.json`                 | Output file, relative to the project root. Parent folders are created. |
-| `--title`         | `name` in `package.json` (else `Warlock API`)  | `info.title`. `info.version` is the `package.json` version (else `0.0.0`); `info.description` is its `description`. |
-| `--server`        | `http://<host>:<port>` from the `http` config  | `servers[0].url`. A wildcard host (`0.0.0.0`, `::`) becomes `localhost`. |
-| `--include-pages` | off                                            | Also document page (SSR) routes; each is a `200` with `text/html`. |
+| Option            | Default                                       | Meaning                                                                                                             |
+| ----------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `--out`, `-o`     | `storage/openapi/openapi.json`                | Output file, relative to the project root. Parent folders are created.                                              |
+| `--title`         | `name` in `package.json` (else `Warlock API`) | `info.title`. `info.version` is the `package.json` version (else `0.0.0`); `info.description` is its `description`. |
+| `--server`        | `http://<host>:<port>` from the `http` config | `servers[0].url`. A wildcard host (`0.0.0.0`, `::`) becomes `localhost`.                                            |
+| `--include-pages` | off                                           | Also document page (SSR) routes; each is a `200` with `text/html`.                                                  |
 
 ```bash
 npx warlock generate.openapi --out docs/openapi.json --title "Shop API" --server https://api.shop.test
@@ -29,18 +29,44 @@ npx warlock generate.openapi --out docs/openapi.json --title "Shop API" --server
 
 ## What is documented
 
-| Part                    | Source                                                                                          |
-| ----------------------- | ----------------------------------------------------------------------------------------------- |
-| Paths                   | `:id` becomes `{id}`. An `all` route expands into one operation per verb (get, post, put, patch, delete, options, head). |
-| `operationId`           | The route `name` (`name.<verb>` when an `all` route expands), else `<verb>_<path_slug>`. Duplicates are renamed with a warning. |
-| Tag                     | The first static path segment (`/users/:id` is tagged `users`).                                  |
-| Summary / description   | The route `label`; the route or handler `description`, plus a line about required user types and the cookie CSRF rule when the route is guarded. |
-| Path parameters         | `validation.params` gives typed ones; a path segment with no schema is a required `string`.       |
-| Request body / query    | `validation.schema`, converted with the Seal schema's JSON Schema output. It is the JSON request body for POST/PUT/PATCH and query parameters for GET/HEAD/DELETE, following `validating` the way validation reads the request. |
-| Responses               | `handler.responseSchema`, one response per declared status (see below). A route with no 2xx declared gets a `200` description only. |
-| `422`                   | Added when the route has `validation.schema`, shaped by `validation.response` (`errors`, `inputKey`, `inputError`, `status`; `Response.failedSchema` defaults to 422). Stored once as `components.schemas.ValidationFailed`. A route with only `validation.params` gets none. |
-| `401`                   | Added when the route is guarded, as `{ error: string }` (`components.schemas.Unauthorized`). A status you declare yourself is kept. |
-| Security                | `authMiddleware()` tags the middleware it returns with a `Symbol.for("warlock.auth")` descriptor (`{ sources, userTypes }`); core reads it without importing auth. A header source is `bearerAuth` (HTTP bearer), a cookie source is `cookieAuth` (API key in that cookie); header plus cookie is an OR. Only the schemes a route uses are emitted. Middleware without a descriptor adds nothing. |
+| Part                  | Source                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Paths                 | `:id` becomes `{id}`. An `all` route expands into one operation per verb (get, post, put, patch, delete, options, head).                                                                                                                                                                                                                                                                                                                   |
+| `operationId`         | The route `name` (`name.<verb>` when an `all` route expands), else `<verb>_<path_slug>`. Duplicates are renamed with a warning.                                                                                                                                                                                                                                                                                                            |
+| Tag                   | The first static path segment (`/users/:id` is tagged `users`).                                                                                                                                                                                                                                                                                                                                                                            |
+| Summary / description | The route `label`; the route or handler `description`, plus a line about required user types and the cookie CSRF rule when the route is guarded.                                                                                                                                                                                                                                                                                           |
+| Path parameters       | `validation.params` gives typed ones; a path segment with no schema is a required `string`.                                                                                                                                                                                                                                                                                                                                                |
+| Request body / query  | `validation.schema`, converted with the Seal schema's JSON Schema output. It is the JSON request body for POST/PUT/PATCH and query parameters for GET/HEAD/DELETE, following `validating` the way validation reads the request.                                                                                                                                                                                                            |
+| Responses             | `handler.responseSchema`, one response per declared status (see below). A route with no 2xx declared gets a `200` description only.                                                                                                                                                                                                                                                                                                        |
+| `422`                 | Added when the route has `validation.schema`, shaped by `validation.response` (`errors`, `inputKey`, `inputError`, `status`; `Response.failedSchema` defaults to 422). Stored once as `components.schemas.ValidationFailed`. A route with only `validation.params` gets none. A custom failure body (`validation.onFailure`, `validation.response.body`) is documented from the `responseSchema` entry for its status instead (see below). |
+| `401`                 | Added when the route is guarded, as `{ error: string }` (`components.schemas.Unauthorized`). A status you declare yourself is kept.                                                                                                                                                                                                                                                                                                        |
+| Security              | `authMiddleware()` tags the middleware it returns with a `Symbol.for("warlock.auth")` descriptor (`{ sources, userTypes }`); core reads it without importing auth. A header source is `bearerAuth` (HTTP bearer), a cookie source is `cookieAuth` (API key in that cookie); header plus cookie is an OR. Only the schemes a route uses are emitted. Middleware without a descriptor adds nothing.                                          |
+
+### Custom validation failure bodies
+
+When a route shapes its own failure body, declare that status in `responseSchema`; the generator documents it instead of `ValidationFailed`:
+
+```ts title="src/app/imports/controllers/create-import.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+import { v } from "@warlock.js/seal";
+
+const importSchema = v.object({ name: v.string().required() });
+
+export const createImportController: RequestHandler = async ({ response }) =>
+  response.successCreate({ id: "import-1" });
+
+createImportController.validation = {
+  schema: importSchema,
+  onFailure: () => ({ status: 400, body: { error: "IMPORT_REQUEST_INVALID" } }),
+};
+
+createImportController.responseSchema = {
+  201: { body: { id: "string" } },
+  400: { body: { error: "string" } },
+};
+```
+
+Undeclared, the configured failure status (`validation.response.status`, default 422) gets a description-only response, and a route-level `onFailure` also produces a warning. Any declared 4xx entry on a route with `onFailure` is trusted as its failure response.
 
 ### Responses from `responseSchema`
 
@@ -103,12 +129,12 @@ npx warlock generate.postman
 # Postman collection written to <root>/storage/postman/collection.json (3 folders, 17 requests). Import it in Postman and set the {{token}} variable.
 ```
 
-| Option            | Default                                   | Meaning                                                            |
-| ----------------- | ----------------------------------------- | ------------------------------------------------------------------ |
-| `--out`, `-o`     | `storage/postman/collection.json`         | Output file, relative to the project root.                          |
-| `--title`         | `name` in `package.json`                  | Collection name; the collection id is a stable hash of it.          |
-| `--server`        | `http://<host>:<port>` from the `http` config | Value of the `{{baseUrl}}` variable.                              |
-| `--include-pages` | off                                       | Also include page (SSR) routes.                                     |
+| Option            | Default                                       | Meaning                                                    |
+| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
+| `--out`, `-o`     | `storage/postman/collection.json`             | Output file, relative to the project root.                 |
+| `--title`         | `name` in `package.json`                      | Collection name; the collection id is a stable hash of it. |
+| `--server`        | `http://<host>:<port>` from the `http` config | Value of the `{{baseUrl}}` variable.                       |
+| `--include-pages` | off                                           | Also include page (SSR) routes.                            |
 
 What the collection contains:
 

package/skills/hash-password/SKILL.md

@@ -31,7 +31,7 @@ import type { EncryptionConfigurations } from "@warlock.js/core";
 
 const encryptionConfig: EncryptionConfigurations = {
   password: {
-    salt: 12,    // bcrypt rounds — 10–12 is the standard band
+    salt: 12, // bcrypt rounds — 10–12 is the standard band
   },
   // ...other crypto config (key/hmacKey for encrypt/decrypt — see encrypt-data skill)
 };
@@ -117,7 +117,7 @@ await user.save({ password: await hashPassword(newPassword) });
 If the model uses `useHashedPassword()`, you can skip the explicit `hashPassword` call:
 
 ```ts
-await user.save({ password: newPassword });  // transformer hashes on save
+await user.save({ password: newPassword }); // transformer hashes on save
 ```
 
 The transformer detects that the field is changing and re-hashes.

package/skills/health-checks/SKILL.md

@@ -11,10 +11,10 @@ Two endpoints and a drain, so a load balancer never routes to an instance that i
 
 The HTTP connector registers them on the Fastify server during boot (before route scanning), so they exist by the time the server listens:
 
-| Path | Probe | 200 when | 503 when |
-| --- | --- | --- | --- |
-| `/health` | liveness | the process is up | shutdown has begun |
-| `/ready` | readiness | booted **and** not shutting down **and** every check passes | before boot, during shutdown, or any failing check |
+| Path      | Probe     | 200 when                                                    | 503 when                                           |
+| --------- | --------- | ----------------------------------------------------------- | -------------------------------------------------- |
+| `/health` | liveness  | the process is up                                           | shutdown has begun                                 |
+| `/ready`  | readiness | booted **and** not shutting down **and** every check passes | before boot, during shutdown, or any failing check |
 
 **Liveness** answers "should the orchestrator RESTART me?" — it ignores dependency checks (a failing DB doesn't mean restart the pod). **Readiness** answers "should the load balancer ROUTE to me?" — it gates on boot completion, shutdown state, and your registered checks.
 
@@ -31,15 +31,30 @@ import type { HttpConfigurations } from "@warlock.js/core";
 
 const httpConfigurations: HttpConfigurations = {
   health: {
-    enabled: true,          // default; set false to remove both endpoints
-    path: "/health",        // liveness path
+    enabled: true, // default; set false to remove both endpoints
+    path: "/health", // liveness path
     readinessPath: "/ready", // readiness path
+    rateLimit: false, // exempt probes from global client quotas (default)
   },
 };
 
 export default httpConfigurations;
 ```
 
+Built-in liveness and readiness routes bypass `http.rateLimit` by default,
+including renamed probe paths. Application traffic cannot consume their quota,
+and probe traffic does not consume the application's quota. Their normal
+liveness/readiness status still applies.
+
+Set `http.health.rateLimit: true` to opt both probes into the global policy and
+shared client bucket. This requires the rate-limit plugin to be enabled and
+`http.rateLimit.global` to remain enabled; exhausted quotas can then return 429
+for probes too. Disabling global limits leaves opted-in probes unlimited.
+
+Static files are exempt the same way (public folder, `router.directory()` mounts,
+`router.file()` routes, the web build's assets); `http.rateLimit.staticFiles:
+true` counts them. Pages and API routes always share the global bucket.
+
 ## Readiness checks
 
 Readiness is `isBooted && !isShuttingDown` plus every registered check. Register a check from a connector, a `main.ts`, or anywhere:
@@ -47,6 +62,8 @@ Readiness is `isBooted && !isShuttingDown` plus every registered check. Register
 ```ts
 import { health } from "@warlock.js/core";
 
+declare const database: { isConnected(): boolean }; // your connection handle
+
 health.addCheck("db", async () => {
   return database.isConnected();
 });
@@ -82,7 +99,7 @@ import type { HttpConfigurations } from "@warlock.js/core";
 
 const httpConfigurations: HttpConfigurations = {
   gracefulShutdown: {
-    timeout: 10_000,              // ms to wait for in-flight drain (default 10s)
+    timeout: 10_000, // ms to wait for in-flight drain (default 10s)
     forceCloseConnections: "idle", // close idle keep-alives, let active finish (default)
   },
 };
@@ -92,6 +109,8 @@ export default httpConfigurations;
 
 `forceCloseConnections`: `"idle"` (default) closes idle keep-alive connections and lets active requests finish; `true` force-closes everything immediately; `false` waits for every connection.
 
+Under `"idle"`, a request that is still running when shutdown begins answers with `Connection: close`, and its keep-alive connection is closed as soon as the response finishes, so a browser's kept-alive connection does not hold the drain open until the timeout. Responses that had already sent their headers (streams, SSE) are closed when they end. Active responses are never cut short.
+
 ## The zero-downtime deploy flow
 
 ```

package/skills/index.md

@@ -1,28 +1,33 @@
 ---
 description: "The Warlock server framework: HTTP routes, controllers, responses, resources, repositories, CLI, mail, storage, security helpers. Exports `router`, `Request`, `Response`, `RequestHandler`, `useCase`, `RepositoryManager`, `defineResource`, `defineConfig`, `storage`, `sendMail`, `hashPassword`, `command`. Use for: add a route, write a controller, return a JSON response, hide a field from the response, upload a file, send an email, hash a password, add a CLI command, generate an OpenAPI document, type an API response, wire a socket, run or configure the app. Not this package: database models/queries → @warlock.js/cascade; input schemas → @warlock.js/seal; SSR pages → @warlock.js/web."
 ---
+
 # @warlock.js/core
 
 Core is the application runtime: it boots the app, auto-loads each module's special files, serves HTTP, and provides the helpers every feature layer uses. Features live in `src/app/<module>/` and flow one way: `routes.ts → controllers → services → repositories → models`; resources map output at the edge. Start with `warlock-conventions.md`, which every other topic assumes.
 
 ## The 80% path
+
 1. Scaffold a module (`create-module.md`), then declare routes in its `routes.ts` (`register-route.md`, `warlock-routes.md`).
 2. Write a thin controller (`create-controller.md`); validate input with a schema attached to the handler (`validate-input.md`).
 3. Put logic in a service or use case (`write-use-case.md`), and data access in a repository (`use-repository.md`).
 4. Return via `response.*` (`send-response.md`) and shape output with a resource (`define-resource.md`); declare `responseSchema` for typed clients and docs (`create-controller.md`, `generate-openapi.md`).
-5. Configure and run (`configure-app.md`, `run-app.md`); check setup with `warlock-doctor.md`.
+5. Configure and run (`configure-app.md`, `run-app.md`); check setup with `warlock-doctor.md`, read the app with `warlock-inspect.md` (or serve it to an agent with `warlock-mcp.md`), verify a change with `warlock-check.md`, and a request's runtime behaviour with `warlock-trace.md`.
 
 ## Topics by area
-- **Foundations:** warlock-conventions, create-module, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators
+
+- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators
 - **HTTP & routing:** register-route, warlock-routes, create-controller, use-middleware, write-middleware, validate-input, use-request-locals, build-restful, wire-socket
 - **Responses & resources:** send-response, define-resource, use-model-transformers, use-localization
 - **Domain layers:** write-use-case, use-repository, write-seeder
-- **CLI & running the app:** run-app, write-cli-command, add-connector, health-checks, warlock-doctor, generate-openapi
+- **CLI & running the app:** run-app, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
+- **Agent tooling:** warlock-mcp, warlock-trace, warlock-agents-md, warlock-board
 - **Storage, files & mail:** store-file, upload-file, process-image, send-mail
 - **Security & utilities:** hash-password, encrypt-data, retry-operation, benchmark-code, request-memo, request-tracing
-- **Testing:** test-http, test-service
+- **Testing:** test-http, test-service, test-fakes, model-factories
 
 ## Conventions and pitfalls
+
 - Several files are auto-loaded (`routes.ts`, `main.ts`, `events/*`, `utils/locales.ts`, `src/config/*`); never import them by hand.
 - Core does NOT re-export `v`/`Infer` (import from `@warlock.js/seal`), or `Model`/`Migration` (from `@warlock.js/cascade`).
 - Controllers stay thin: no business logic, transactions, or external API calls. Resources are output-only.

package/skills/lower-stage3-decorators/SKILL.md

@@ -11,11 +11,11 @@ Cascade declares relations with **native** decorators — `@RegisterModel`, `@Be
 SyntaxError: Invalid or unexpected token
 ```
 
-The cause is two transforms that don't understand each other. Vite 8 transpiles `.ts` with **oxc**, which only lowers *legacy* (`experimentalDecorators`) decorators — it leaves native ones in place. Then Vite's SSR `moduleRunnerTransform` rewrites the decorator's imported name into `@(0, __vite_ssr_import__.RegisterModel)()` — which is no longer valid decorator syntax. V8 throws on the first decorated model it evaluates, and your whole suite is dead before a single test runs.
+The cause is two transforms that don't understand each other. Vite 8 transpiles `.ts` with **oxc**, which only lowers _legacy_ (`experimentalDecorators`) decorators — it leaves native ones in place. Then Vite's SSR `moduleRunnerTransform` rewrites the decorator's imported name into `@(0, __vite_ssr_import__.RegisterModel)()` — which is no longer valid decorator syntax. V8 throws on the first decorated model it evaluates, and your whole suite is dead before a single test runs.
 
-`lowerStage3Decorators()` fixes it by getting **esbuild** to lower the decorators *first*.
+`lowerStage3Decorators()` fixes it by getting **esbuild** to lower the decorators _first_.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** The plugin used to be re-exported from the package root; it is not any more, because that put the Vite integration into every application's production module graph. `import { lowerStage3Decorators } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/vite` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** The plugin used to be re-exported from the package root; it is not any more, because that put the Vite integration into every application's production module graph. `import { lowerStage3Decorators } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/vite` to the specifier and nothing else changes.**
 
 ## Use it
 
@@ -45,7 +45,7 @@ It's the **same esbuild transform the production `tsx`/build path uses**, so a f
 
 ## Things NOT to do
 
-- **Don't reach for `oxc: { target: "es2022" }`** — it's insufficient. oxc can only lower *legacy* decorators, and the breakage is the SSR rewrite, not the transpile target. Legacy lowering would also mangle the Stage-3 `(value, context)` signature.
+- **Don't reach for `oxc: { target: "es2022" }`** — it's insufficient. oxc can only lower _legacy_ decorators, and the breakage is the SSR rewrite, not the transpile target. Legacy lowering would also mangle the Stage-3 `(value, context)` signature.
 - **Don't put it after `@mongez/vite`** — it must run `pre`, before any other transform. Keep it first.
 - **Don't set `experimentalDecorators: true`** anywhere in the test tsconfig — Cascade's decorators are native (Stage-3), not legacy. Legacy mode changes their call signature and breaks `context.kind` / `context.metadata`.
 

package/skills/make-endpoint/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: make-endpoint
+description: 'Generate one endpoint spec-first with `warlock make endpoint <module>/<name>` — request schema (from `--schema`), service, resource, a single controller using `request.validated()` with an OpenAPI `responseSchema`, the route (guarded by default, `public: true` with `--public`), a locale key, and a test that hits the real HTTP stack. Also: `--dry-run` and `--json` on every `make` / `generate.*` / `add` command. Triggers: `warlock make endpoint`, `make.endpoint`, `generate.endpoint`, `warlock make`, `--schema`, `--resource`, `--public`, `--auth`, `--dry-run`, `--json`, `public: true`, `GenerationReport`; "scaffold an endpoint", "add a POST route with validation and a test", "preview what a generator writes", "machine-readable generator output". Skip: a whole CRUD module — the `create-module` topic; controller shape by hand — the `create-controller` topic.'
+---
+
+# Warlock — make an endpoint
+
+Write the request schema, then let the generator write everything around it in the framework's conventions.
+
+## 1. The spec
+
+```ts title="post.spec-input.ts"
+import { type Infer, v } from "@warlock.js/seal";
+
+export const postInput = v.object({
+  title: v.string().min(3),
+  views: v.int().min(1).optional(),
+});
+
+export type PostInput = Infer<typeof postInput>;
+```
+
+The file may live anywhere. Outside `src/` it is copied into the module (relative imports re-pointed); under `src/` it is imported where it lives. The export is found by the conventional name (`createPostSchema`), else the only `v.object(...)` export, else the default export.
+
+## 2. Preview, then generate
+
+```bash
+warlock make endpoint posts/create-post --schema ./post.spec-input.ts --dry-run --json
+warlock make endpoint posts/create-post --schema ./post.spec-input.ts
+warlock make endpoint posts/update-post --method patch --schema ./post.spec-input.ts
+warlock make endpoint contact/send-message --schema ./message.ts --public
+```
+
+Options: `--method get|post|put|patch|delete` (default `post`), `--path` (default `/<module>`, or `/<module>/:id` for put/patch/delete), `--resource <Name>` (default: the module's singular), `--auth` (default) or `--public`, `--force`, `--dry-run`, `--json`. `warlock generate.endpoint` and `warlock make.endpoint` are the same command.
+
+## 3. What it writes (`src/app/posts/`)
+
+- `schema/create-post.schema.ts` — `createPostSchema` and its `CreatePostSchema` type.
+- `services/create-post.service.ts` — `createPostService(input)`; validated input only, never the request. Fill it in.
+- `resources/post.resource.ts` — `PostResource` shaped from the schema fields (skipped when it exists).
+- `controllers/create-post.controller.ts` — one handler:
+
+```ts
+export const createPostController: GuardedRequestHandler<CreatePostSchema> = async ({
+  request,
+  response,
+}) => {
+  const post = await createPostService(request.validated());
+
+  return response.successCreate({
+    message: t("posts.createPostSuccess"),
+    post: new PostResource(post),
+  });
+};
+
+createPostController.validation = { schema: createPostSchema };
+
+createPostController.responseSchema = {
+  201: { body: { message: "string", post: PostResource } },
+};
+```
+
+- `routes.ts` — appended: `guarded(() => { router.post("/posts", createPostController); })`, or with `--public`: `router.post("/posts", createPostController, { public: true });`.
+- `utils/locales.json` — `createPostSuccess` merged in (existing keys win).
+- `tests/create-post.test.ts` — a valid request derived from the schema expecting `201` and the resource, a request missing a required field expecting a 4xx, and for guarded routes an anonymous `401` plus a signed-in case through `actingAs()`.
+
+Existing files are skipped and reported (never overwritten without `--force`); a controller already in `routes.ts` is not registered twice.
+
+## 4. Run its test
+
+```bash
+warlock test --related src/app/posts/tests/create-post.test.ts
+```
+
+The test needs `warlock add test`. Signed-in cases create a user through `auth.userType.user` (a test database); adjust its fields if your user model requires more. A required file field turns the happy path into an `it.todo` (JSON cannot carry files).
+
+## `--dry-run` and `--json` everywhere
+
+Every `generate.*` command, `make`, and `add` take both. `--dry-run` writes (and for `add`, installs) nothing. `--json` prints exactly one report on stdout — also on failure — and sends everything else to stderr:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "make endpoint",
+  "dryRun": true,
+  "ok": true,
+  "written": ["src/app/posts/controllers/create-post.controller.ts"],
+  "skipped": [
+    {
+      "path": "src/app/posts/resources/post.resource.ts",
+      "reason": "exists (pass --force to overwrite)"
+    }
+  ],
+  "files": [{ "path": "src/app/posts/routes.ts", "type": "update" }],
+  "details": { "endpoint": { "method": "POST", "path": "/posts", "access": "guarded" } },
+  "messages": []
+}
+```
+
+`files[].type`: `create`, `overwrite`, `update`, `unchanged`, `skip`. On failure `ok: false` and `error` says why. `add --list --json` puts the feature catalog in `details.features`.
+
+## `public: true`
+
+`RouteOptions.public` changes nothing at runtime; it records that a route deliberately has no auth guard, so a mutating route without one reads as a decision. `warlock dev`, `warlock inspect` and `warlock check` (`WL9006`) read it.
+
+## See also
+
+- The `create-module` topic — a whole CRUD module.
+- The `test-http` topic — the HTTP helpers the generated test uses.
+- The `generate-openapi` topic — what `responseSchema` documents.