@warlock.js/core 5.30.0 → 5.32.0

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)
   },
 };

package/skills/index.md

@@ -1,28 +1,35 @@
 ---
 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`.
+
+When the framework is wrong or missing a capability, follow `report-framework-issue.md` to prepare a public report and ask the user before filing.
 
 ## 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.