@warlock.js/core 5.34.1 → 5.34.3

package/llms-full.txt

@@ -4,7 +4,48 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/core/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
-## add-connector  `@warlock.js/core/add-connector/SKILL.md`
+## Package orientation
+
+---
+description: 'Warlock application runtime: `router`, `Request`, `Response`, `config`, `env`, `sendMail` and `defineConfig`. Use for "add an API route", controllers, middleware, CLI commands, config, uploads, mail, sockets, OpenAPI, testing or upgrades. Not this package → @warlock.js/web for React SSR pages; @warlock.js/cascade for database queries; @warlock.js/seal for standalone schemas; @warlock.js/auth for login.'
+---
+
+# @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`, 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 the `report-framework-issue` topic to prepare a public report and ask the user before filing.
+
+## Topics by area
+
+- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators, upgrade-from-5-29
+- **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, 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, store-secrets, retry-operation, benchmark-code, request-memo, request-tracing
+- **Testing:** test-browser, 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.
+- No per-action `*.request.ts` files; schema files export the value and the inferred type together.
+- Prefer typed model getters over scattered `.get<T>("field")` casts.
+
+
+## add-connector  `@warlock.js/core/skills/add-connector/SKILL.md`
 
 ---
 name: add-connector
@@ -236,7 +277,7 @@ See the [Registering a connector](#registering-a-connector) section above for th
 - The `warlock-conventions` topic — module layout, canonical imports.
 
 
-## benchmark-code  `@warlock.js/core/benchmark-code/SKILL.md`
+## benchmark-code  `@warlock.js/core/skills/benchmark-code/SKILL.md`
 
 ---
 name: benchmark-code
@@ -502,7 +543,7 @@ The `latency` is the _total_ time including retries — useful for the SLO you a
 - The `configure-app` topic — wiring `src/config/benchmark.ts`.
 
 
-## build-restful  `@warlock.js/core/build-restful/SKILL.md`
+## build-restful  `@warlock.js/core/skills/build-restful/SKILL.md`
 
 ---
 name: build-restful
@@ -774,7 +815,7 @@ router.restfulResource("/orders", new OrdersRestful());
 - The `warlock-conventions` topic — controller/service/repository layering rules.
 
 
-## build-url  `@warlock.js/core/build-url/SKILL.md`
+## build-url  `@warlock.js/core/skills/build-url/SKILL.md`
 
 ---
 name: build-url
@@ -958,7 +999,7 @@ Don't call `setBaseUrl` per request — it's process-global and races every othe
 - The `configure-app` topic — `src/config/app.ts` and the `baseUrl` env wiring.
 
 
-## configure-app  `@warlock.js/core/configure-app/SKILL.md`
+## configure-app  `@warlock.js/core/skills/configure-app/SKILL.md`
 
 ---
 name: configure-app
@@ -1384,8 +1425,35 @@ Keep the domain error class in an app module imported by both the service and
 this config. Return `undefined` for errors you do not recognize; a mapped 5xx
 is opaque unless the mapper explicitly chooses a public message.
 
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
+
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
 
-## create-controller  `@warlock.js/core/create-controller/SKILL.md`
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.
+
+
+## create-controller  `@warlock.js/core/skills/create-controller/SKILL.md`
 
 ---
 name: create-controller
@@ -1684,7 +1752,7 @@ export const remoteCatalogController: RequestHandler = async ({ request, respons
 ```
 
 
-## create-module  `@warlock.js/core/create-module/SKILL.md`
+## create-module  `@warlock.js/core/skills/create-module/SKILL.md`
 
 ---
 name: create-module
@@ -1885,7 +1953,7 @@ After editing generated code, run `npm run format` and `npm run lint:check`.
 Formatting retains unused imports; the linter reports them.
 
 
-## define-resource  `@warlock.js/core/define-resource/SKILL.md`
+## define-resource  `@warlock.js/core/skills/define-resource/SKILL.md`
 
 ---
 name: define-resource
@@ -2292,7 +2360,7 @@ export const CommentResource = defineResource({
 - The `create-controller` topic — calling `new XResource(record).toJSON()` from a controller.
 
 
-## encrypt-data  `@warlock.js/core/encrypt-data/SKILL.md`
+## encrypt-data  `@warlock.js/core/skills/encrypt-data/SKILL.md`
 
 ---
 name: encrypt-data
@@ -2506,11 +2574,11 @@ Password hashing (`hashPassword`) needs `bcryptjs`, which is its own install —
 - The `warlock-conventions` topic — service layering, where the encryption boundary should sit.
 
 
-## generate-openapi  `@warlock.js/core/generate-openapi/SKILL.md`
+## generate-openapi  `@warlock.js/core/skills/generate-openapi/SKILL.md`
 
 ---
 name: generate-openapi
-description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `devtools-overview` topic of the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
+description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
 ---
 
 # Warlock — generate an OpenAPI document
@@ -2684,7 +2752,7 @@ const { document, warnings } = buildOpenApiDocument(router.list(), {
 - The `warlock-routes` topic — list the routes the document is built from.
 
 
-## hash-password  `@warlock.js/core/hash-password/SKILL.md`
+## hash-password  `@warlock.js/core/skills/hash-password/SKILL.md`
 
 ---
 name: hash-password
@@ -2871,7 +2939,7 @@ There is no `warlock add` feature for password hashing — `bcryptjs` is a plain
 - The `warlock-conventions` topic — service layering, where the password boundary should sit.
 
 
-## health-checks  `@warlock.js/core/health-checks/SKILL.md`
+## health-checks  `@warlock.js/core/skills/health-checks/SKILL.md`
 
 ---
 name: health-checks
@@ -3013,7 +3081,7 @@ For an even smoother handoff, give the load balancer time to observe the 503 bef
 - The `use-middleware` topic — maintenance mode and other built-in middleware.
 
 
-## lower-stage3-decorators  `@warlock.js/core/lower-stage3-decorators/SKILL.md`
+## lower-stage3-decorators  `@warlock.js/core/skills/lower-stage3-decorators/SKILL.md`
 
 ---
 name: lower-stage3-decorators
@@ -3073,7 +3141,7 @@ It's the **same esbuild transform the production `tsx`/build path uses**, so a f
 - The `write-migration` topic of the `warlock-js-cascade` skill — the decorated models this plugin lets you load.
 
 
-## make-endpoint  `@warlock.js/core/make-endpoint/SKILL.md`
+## make-endpoint  `@warlock.js/core/skills/make-endpoint/SKILL.md`
 
 ---
 name: make-endpoint
@@ -3187,7 +3255,7 @@ Every `generate.*` command, `make`, and `add` take both. `--dry-run` writes (and
 - The `generate-openapi` topic — what `responseSchema` documents.
 
 
-## model-factories  `@warlock.js/core/model-factories/SKILL.md`
+## model-factories  `@warlock.js/core/skills/model-factories/SKILL.md`
 
 ---
 name: model-factories
@@ -3283,7 +3351,7 @@ it("lists users", async () => {
 - The `write-seeder` topic — seeding a development database.
 
 
-## process-image  `@warlock.js/core/process-image/SKILL.md`
+## process-image  `@warlock.js/core/skills/process-image/SKILL.md`
 
 ---
 name: process-image
@@ -3460,7 +3528,7 @@ See the `upload-file` topic for the multipart entry point and the `store-file` t
 - The `warlock-conventions` topic — where image-processing services live.
 
 
-## register-route  `@warlock.js/core/register-route/SKILL.md`
+## register-route  `@warlock.js/core/skills/register-route/SKILL.md`
 
 ---
 name: register-route
@@ -3745,7 +3813,170 @@ router.get("/webhooks/status", webhookStatusController, { rateLimit: false });
 - The `warlock-conventions` topic — module layout, the `guarded` convention, path aliases.
 
 
-## request-memo  `@warlock.js/core/request-memo/SKILL.md`
+## report-framework-issue  `@warlock.js/core/skills/report-framework-issue/SKILL.md`
+
+---
+name: report-framework-issue
+description: "Report a confirmed Warlock.js framework bug or missing capability. Read when behavior contradicts the installed docs, a crash appears to originate in @warlock.js packages, or no documented API meets a requirement; covers minimal reproduction, duplicate searches, sanitized warlock issue output and user approval before filing."
+---
+
+# Report a Warlock.js framework issue
+
+Use this topic when behavior contradicts the installed version's docs or skills,
+a crash originates inside `@warlock.js/*`, or a needed framework capability is
+missing. Framework reports belong at <https://github.com/warlockjs/framework>.
+
+## Confirm and search first
+
+1. Reduce the problem to a minimal reproduction in a clean, generic app. Isolate
+   application logic, third-party packages and configuration mistakes; a stack
+   frame in the framework alone does not prove a framework bug.
+2. Read the **installed version's** package `CHANGELOG.md` and skills. Confirm
+   that the documented API exists in that version and check whether a later
+   release already addresses it. For a feature, describe the missing capability
+   and why the documented APIs or an app-level workaround are insufficient.
+3. Run `warlock doctor --json` (see `warlock-doctor.md`). Fix app/environment
+   findings first. If boot fails, retain only the sanitized failure; `warlock
+   issue` itself does not boot the app.
+4. Search existing reports, including closed issues, using distinctive public
+   terms. If a matching issue exists, show its link and help draft a useful
+   follow-up instead of opening a duplicate. Ask before posting that follow-up.
+
+```bash
+gh issue list -R warlockjs/framework --state all --search "public error or capability"
+```
+
+Without GitHub CLI, use
+<https://github.com/warlockjs/framework/issues?q=is%3Aissue> and enter those terms.
+
+## Collect and protect
+
+```bash
+warlock issue --type bug --title "Public description of the failure"
+warlock issue --type feature --title "Public description of the capability" --json
+```
+
+Collect affected package names and **installed versions**, Node and package
+manager versions, OS/architecture, TypeScript version, the reviewed `warlock
+issue` environment output, a minimal reproduction with exact steps, expected
+versus actual behavior, and relevant sanitized logs / `warlock doctor --json`
+output. If a tool cannot run or there are no relevant logs, explain why.
+
+**Never paste secrets, tokens, `.env` contents, customer data, proprietary code or
+private app names** into titles, bodies, logs, screenshots, repro repositories,
+search queries or URLs. Replace the original app with a minimal generic repro.
+Review even generated environment output and stack traces; remove local paths,
+hostnames and identifying details. The command reads installed package metadata
+and a static config summary; it never reads `.env` or executes the app/config.
+Do not attach the app's full config or diagnostic report without sanitizing it.
+
+## Draft and get consent
+
+Choose one template below, replace every prompt with concrete evidence, and
+write the sanitized body to a local UTF-8 file such as `framework-issue.md`.
+**Always show the complete drafted title and body to the user and explicitly ask
+before filing.** Generating a draft or URL is not consent to publish. If the user
+requests edits, show the revised draft and obtain approval for that version.
+
+### Bug body
+
+```markdown
+### Summary
+
+Public description of the framework failure and affected packages.
+
+### Environment / warlock issue output
+
+Reviewed environment output: installed @warlock.js package versions, Node,
+package manager + version, OS/arch, TypeScript, static config summary.
+
+### Minimal reproduction
+
+Public minimal code or repro link, setup commands and exact steps.
+
+### Expected behavior
+
+What should happen, with the installed version's docs/skills reference.
+
+### Actual / current behavior
+
+What happens instead, including the error and impact.
+
+### Sanitized logs / doctor output
+
+Relevant logs and warlock doctor --json, or why unavailable / not applicable.
+
+### Checks
+
+- [ ] Searched existing issues and checked installed-version CHANGELOG and skills.
+- [ ] Removed secrets, tokens, .env, customer data, proprietary code and private app names.
+- [ ] User reviewed this complete draft and approved filing.
+```
+
+### Feature request body
+
+```markdown
+### Problem / use case
+
+Public description of the missing framework capability and affected packages.
+
+### Environment / warlock issue output
+
+Reviewed environment output: installed @warlock.js package versions, Node,
+package manager + version, OS/arch, TypeScript, static config summary.
+
+### Minimal reproduction
+
+Minimal public example of the capability that cannot currently be expressed.
+
+### Proposed behavior
+
+Desired API/behavior, with an example and why it belongs in the framework.
+
+### Actual / current behavior
+
+Current limitation and relevant installed-version docs/skills.
+
+### Alternatives considered
+
+Existing APIs, app-level workarounds and their limitations.
+
+### Sanitized logs / doctor output
+
+Relevant logs and warlock doctor --json, or why unavailable / not applicable.
+
+### Checks
+
+- [ ] Searched existing issues and checked installed-version CHANGELOG and skills.
+- [ ] Removed secrets, tokens, .env, customer data, proprietary code and private app names.
+- [ ] User reviewed this complete draft and approved filing.
+```
+
+Only check a box after completing that step, including obtaining consent.
+
+## File the approved draft
+
+Check `gh --version` and `gh auth status --hostname github.com`. If GitHub CLI is
+available and authenticated, **after approval** run:
+
+```bash
+gh issue create -R warlockjs/framework --title "Approved public title" --body-file framework-issue.md
+```
+
+Return the created issue's link. If GitHub CLI is unavailable or unauthenticated,
+give the user the pre-filled new-issue URL printed by `warlock issue` together
+with the approved body. The URL selects `bug.yml` or `feature.yml` and prefills
+the environment field; the user must complete the remaining form fields. URLs
+are capped at 7,500 characters and may include a truncation note: restore the
+remaining reviewed output manually. Never claim the issue was filed from merely
+printing or opening a URL. `warlock issue` never sends anything itself.
+
+GitHub CLI flags: [list](https://cli.github.com/manual/gh_issue_list),
+[create](https://cli.github.com/manual/gh_issue_create),
+[authentication](https://cli.github.com/manual/gh_auth_status).
+
+
+## request-memo  `@warlock.js/core/skills/request-memo/SKILL.md`
 
 ---
 name: request-memo
@@ -3891,7 +4122,7 @@ Reusing one key for different result types is a caller bug: TypeScript cannot co
 - The `create-controller` topic — consuming request-scoped values from controllers.
 
 
-## request-tracing  `@warlock.js/core/request-tracing/SKILL.md`
+## request-tracing  `@warlock.js/core/skills/request-tracing/SKILL.md`
 
 ---
 name: request-tracing
@@ -4129,7 +4360,7 @@ export default httpConfig;
 - The `logger-basics` topic of the `warlock-js-logger` skill — structured logging; tracing hooks are the place to bridge phase timing into your log channel.
 
 
-## resolve-path  `@warlock.js/core/resolve-path/SKILL.md`
+## resolve-path  `@warlock.js/core/skills/resolve-path/SKILL.md`
 
 ---
 name: resolve-path
@@ -4304,7 +4535,7 @@ If you find yourself reaching for `path.join(process.cwd(), ...)` — that's a s
 - The `upload-file` topic — the `UploadedFile` shape that pairs with `uploadsPath`.
 
 
-## retry-operation  `@warlock.js/core/retry-operation/SKILL.md`
+## retry-operation  `@warlock.js/core/skills/retry-operation/SKILL.md`
 
 ---
 name: retry-operation
@@ -4426,7 +4657,7 @@ const result = await measure("publish-event", () =>
 - The `write-use-case` topic — the use-case `retry` option.
 
 
-## run-app  `@warlock.js/core/run-app/SKILL.md`
+## run-app  `@warlock.js/core/skills/run-app/SKILL.md`
 
 ---
 name: run-app
@@ -5146,7 +5377,7 @@ directly. Regression tests cover both paths without inherited loader hooks,
 including configured declaration roots, source updates and deleted declarations.
 
 
-## send-mail  `@warlock.js/core/send-mail/SKILL.md`
+## send-mail  `@warlock.js/core/skills/send-mail/SKILL.md`
 
 ---
 name: send-mail
@@ -5552,7 +5783,7 @@ await Mail.to(user.email)
 - The `warlock-conventions` topic — where mail-sending services live.
 
 
-## send-response  `@warlock.js/core/send-response/SKILL.md`
+## send-response  `@warlock.js/core/skills/send-response/SKILL.md`
 
 ---
 name: send-response
@@ -6038,8 +6269,35 @@ export function requireProduct<T>(product: T | null | undefined): T {
 }
 ```
 
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
 
-## store-file  `@warlock.js/core/store-file/SKILL.md`
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
+
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.
+
+
+## store-file  `@warlock.js/core/skills/store-file/SKILL.md`
 
 ---
 name: store-file
@@ -6487,7 +6745,7 @@ Client `PUT`s the bytes straight to R2 — your server never sees them.
 - The `send-response` topic — `response.sendFile(absPath)` for serving local files.
 
 
-## store-secrets  `@warlock.js/core/store-secrets/SKILL.md`
+## store-secrets  `@warlock.js/core/skills/store-secrets/SKILL.md`
 
 ---
 name: store-secrets
@@ -6651,7 +6909,7 @@ The normal test harness still installs `secretsFake`; explicit `backend`
 instances and that fake continue to bypass configured backend selection.
 
 
-## test-browser  `@warlock.js/core/test-browser/SKILL.md`
+## test-browser  `@warlock.js/core/skills/test-browser/SKILL.md`
 
 ---
 name: test-browser
@@ -6758,6 +7016,7 @@ port-file handshake above when the app supports binding `0` itself.
   document. Selector helpers do not enter frames or closed shadow roots.
 
 Use `--browser /path/to/chrome` or `WARLOCK_E2E_BROWSER` if discovery fails.
+Set `browser.startupTimeoutMs` (default 30 seconds) when the browser is slow to start, for example on shared CI runners.
 `browser: { args: ["--no-sandbox"] }` is an explicit option for controlled root
 containers; it is not a default. On Windows, command arrays should invoke JS tools
 through `process.execPath`, avoiding `.cmd` executables that require a shell.
@@ -6774,7 +7033,7 @@ if ownership verification fails and reports the failure in evidence. Do not add
 process-name or port-based kills to a spec.
 
 
-## test-fakes  `@warlock.js/core/test-fakes/SKILL.md`
+## test-fakes  `@warlock.js/core/skills/test-fakes/SKILL.md`
 
 ---
 name: test-fakes
@@ -6903,7 +7162,7 @@ An unknown fake name or a non-boolean value fails setup with the list of known f
 - The `model-factories` topic — deterministic fixtures.
 
 
-## test-http  `@warlock.js/core/test-http/SKILL.md`
+## test-http  `@warlock.js/core/skills/test-http/SKILL.md`
 
 ---
 name: test-http
@@ -7367,7 +7626,7 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 - The `write-cli-command` topic — `warlock add test` scaffolds both global + worker setup files.
 
 
-## test-service  `@warlock.js/core/test-service/SKILL.md`
+## test-service  `@warlock.js/core/skills/test-service/SKILL.md`
 
 ---
 name: test-service
@@ -7817,7 +8076,7 @@ setupTest({ importModule: (file) => import(file) });
 The generated `src/test-setup.ts` already does this. Without it, `setupTest()` under Vitest warns once.
 
 
-## update-packages  `@warlock.js/core/update-packages/SKILL.md`
+## update-packages  `@warlock.js/core/skills/update-packages/SKILL.md`
 
 ---
 name: update-packages
@@ -7965,7 +8224,7 @@ Two small zero-dependency utilities back the tooling and are exported from `@war
 - The `configure-app` topic — `warlock.config.ts` shape and `defineConfig`.
 
 
-## upgrade-from-5-29  `@warlock.js/core/upgrade-from-5-29/SKILL.md`
+## upgrade-from-5-29  `@warlock.js/core/skills/upgrade-from-5-29/SKILL.md`
 
 ---
 name: upgrade-from-5-29
@@ -8445,6 +8704,10 @@ It replaces standard scripts/dependencies, pins TypeScript 7.0.2, updates genera
 editor settings, removes `healthCheckers.eslint` and selects Oxlint. A generated
 `.prettierignore` becomes `.oxfmtignore`; Oxfmt scripts read it explicitly.
 
+Generated migration configs enable `typescript/no-explicit-any`, `curly`, and
+`no-console` as errors, matching new apps. Fix those diagnostics before running
+`npm run lint:check` and `npx warlock check` again.
+
 The `oxc-toolchain` codemod also updates generated VS Code settings and literal
 ESLint/Oxlint health-check switches. Custom editor settings, checker arrays,
 computed options and nonstandard scripts require review. Oxc diagnostics keep
@@ -8501,7 +8764,7 @@ marker determines the installer: `package-lock.json` plus `pnpm-workspace.yaml`
 without `pnpm-lock.yaml` now produces `npm install`.
 
 
-## upload-file  `@warlock.js/core/upload-file/SKILL.md`
+## upload-file  `@warlock.js/core/skills/upload-file/SKILL.md`
 
 ---
 name: upload-file
@@ -8814,7 +9077,7 @@ The reverse direction — sending a stored file back via `response.sendFile(...)
 - The `warlock-conventions` topic — storage configuration and driver selection.
 
 
-## use-app-context  `@warlock.js/core/use-app-context/SKILL.md`
+## use-app-context  `@warlock.js/core/skills/use-app-context/SKILL.md`
 
 ---
 name: use-app-context
@@ -9125,7 +9388,7 @@ cors: {
 - The `warlock-conventions` topic — module layout, where paths point to.
 
 
-## use-localization  `@warlock.js/core/use-localization/SKILL.md`
+## use-localization  `@warlock.js/core/skills/use-localization/SKILL.md`
 
 ---
 name: use-localization
@@ -9467,7 +9730,7 @@ This produces `account.title` and `account.actions.save`. Keep every leaf comple
 When a route-locales snapshot applies, `t()` (through the request binding) and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
 
 
-## use-middleware  `@warlock.js/core/use-middleware/SKILL.md`
+## use-middleware  `@warlock.js/core/skills/use-middleware/SKILL.md`
 
 ---
 name: use-middleware
@@ -9765,7 +10028,7 @@ router.post("/private/preview", ({ response }) => response.success({ ready: true
 ```
 
 
-## use-model-transformers  `@warlock.js/core/use-model-transformers/SKILL.md`
+## use-model-transformers  `@warlock.js/core/skills/use-model-transformers/SKILL.md`
 
 ---
 name: use-model-transformers
@@ -9998,7 +10261,7 @@ Rule of thumb: transformers are for **pure, deterministic** transforms of the ro
 - The `warlock-conventions` topic — schema files live in `src/app/<module>/models/<entity>/<entity>.model.ts`.
 
 
-## use-repository  `@warlock.js/core/use-repository/SKILL.md`
+## use-repository  `@warlock.js/core/skills/use-repository/SKILL.md`
 
 ---
 name: use-repository
@@ -10432,7 +10695,7 @@ The third arg is a context object — `{ allValues, dateFormat, ... }` — for f
 - The `warlock-conventions` topic — controller → service → repository → model layering.
 
 
-## use-request-locals  `@warlock.js/core/use-request-locals/SKILL.md`
+## use-request-locals  `@warlock.js/core/skills/use-request-locals/SKILL.md`
 
 ---
 name: use-request-locals
@@ -10603,7 +10866,7 @@ Writing `request.locals.organization` does not affect `request.all()`, `request.
 - The `create-controller` topic — reading locals in downstream controllers.
 
 
-## validate-input  `@warlock.js/core/validate-input/SKILL.md`
+## validate-input  `@warlock.js/core/skills/validate-input/SKILL.md`
 
 ---
 name: validate-input
@@ -10961,7 +11224,7 @@ updateProductController.validation = {
 - The `warlock-conventions` topic — `Request<Schema>` type-alias convention.
 
 
-## warlock-agents-md  `@warlock.js/core/warlock-agents-md/SKILL.md`
+## warlock-agents-md  `@warlock.js/core/skills/warlock-agents-md/SKILL.md`
 
 ---
 name: warlock-agents-md
@@ -11061,7 +11324,7 @@ refresher.dispose();
 - The `warlock-conventions` topic — the conventions listed in the section.
 
 
-## warlock-board  `@warlock.js/core/warlock-board/SKILL.md`
+## warlock-board  `@warlock.js/core/skills/warlock-board/SKILL.md`
 
 ---
 name: warlock-board
@@ -11188,7 +11451,7 @@ const { messages } = await watchBoard({ agent: "implementer", timeoutMs: 30 * 60
 - The `warlock-inspect` topic — the app's facts as JSON before you change it.
 
 
-## warlock-check  `@warlock.js/core/warlock-check/SKILL.md`
+## warlock-check  `@warlock.js/core/skills/warlock-check/SKILL.md`
 
 ---
 name: warlock-check
@@ -11319,7 +11582,7 @@ const types = runTypecheck({ files: ["src/app/posts/services/publish.service.ts"
 
 ## See also
 
-- `report-framework-issue.md` — confirm a framework bug or missing capability, collect `warlock issue` output, and get the user's approval before filing.
+- the `report-framework-issue` topic — confirm a framework bug or missing capability, collect `warlock issue` output, and get the user's approval before filing.
 - The `warlock-doctor` topic — boot-time diagnostics; `doctor --json` uses the same codes and fields.
 - The `warlock-inspect` topic — the app's routes, models and config as JSON.
 - The `warlock-conventions` topic — the rules behind `WL9001`–`WL9012`, with the fix for each.
@@ -11329,7 +11592,7 @@ Migrate lint and format tooling with
 and work through the manual-review list. Use `--lint=oxc` for new apps.
 
 
-## warlock-conventions  `@warlock.js/core/warlock-conventions/SKILL.md`
+## warlock-conventions  `@warlock.js/core/skills/warlock-conventions/SKILL.md`
 
 ---
 name: warlock-conventions
@@ -11585,7 +11848,7 @@ The comment covers the codes it names on its own line and the next; with no code
 - The `send-response` topic — the full Response helper surface.
 
 
-## warlock-doctor  `@warlock.js/core/warlock-doctor/SKILL.md`
+## warlock-doctor  `@warlock.js/core/skills/warlock-doctor/SKILL.md`
 
 ---
 name: warlock-doctor
@@ -11768,7 +12031,7 @@ formatting. Oxlint/Oxfmt are the only supported tools in 5.34.0. Use the
 Migrate with `npx warlock upgrade --from 5.32 --to 5.33.0` (preview with `--dry-run`).
 
 
-## warlock-inspect  `@warlock.js/core/warlock-inspect/SKILL.md`
+## warlock-inspect  `@warlock.js/core/skills/warlock-inspect/SKILL.md`
 
 ---
 name: warlock-inspect
@@ -11906,7 +12169,7 @@ const valid = new Ajv2020({ strict: false }).validate(INSPECT_REPORT_JSON_SCHEMA
 - The `generate-openapi` topic — the same route schemas as an OpenAPI document.
 
 
-## warlock-mcp  `@warlock.js/core/warlock-mcp/SKILL.md`
+## warlock-mcp  `@warlock.js/core/skills/warlock-mcp/SKILL.md`
 
 ---
 name: warlock-mcp
@@ -12030,7 +12293,7 @@ await server.close();
 - The `expose-as-mcp-server` topic of @warlock.js/ai-tools — the transport underneath.
 
 
-## warlock-routes  `@warlock.js/core/warlock-routes/SKILL.md`
+## warlock-routes  `@warlock.js/core/skills/warlock-routes/SKILL.md`
 
 ---
 name: warlock-routes
@@ -12170,11 +12433,11 @@ and exits non-zero.
 - The `write-cli-command` topic — the command + `preload` shape `routesCommand` is built from.
 
 
-## warlock-trace  `@warlock.js/core/warlock-trace/SKILL.md`
+## warlock-trace  `@warlock.js/core/skills/warlock-trace/SKILL.md`
 
 ---
 name: warlock-trace
-description: 'Verify runtime behaviour without a browser: `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running `warlock dev` server and prints what devtools recorded for it — middleware chain with timings, validation result and errors, handler time, queries with N+1 flags, logs, cache operations, captured mails, the response and timings — as a versioned report (`schemaVersion: 1`); `traceRequest()` returns the same object. Triggers: `warlock trace`, `traceRequest`, `TraceReport`, `buildTraceReport`, `x-request-id`, `.warlock/dev-server.json`, `WL8008`, `WL8009`, `WL5004`, `--id-header`; "did validation pass for this request", "which queries does this endpoint run", "is there an N+1 on this route", "what middleware runs on this route", "check the endpoint after my change", "request timeline as JSON". Skip: the devtools dashboard in a browser — the `devtools-overview` skill of @warlock.js/devtools; static route facts (guard, rate limit, schemas) — the `warlock-inspect` topic; typecheck/lint/tests — the `warlock-check` topic.'
+description: 'Verify runtime behaviour without a browser: `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running `warlock dev` server and prints what devtools recorded for it — middleware chain with timings, validation result and errors, handler time, queries with N+1 flags, logs, cache operations, captured mails, the response and timings — as a versioned report (`schemaVersion: 1`); `traceRequest()` returns the same object. Triggers: `warlock trace`, `traceRequest`, `TraceReport`, `buildTraceReport`, `x-request-id`, `.warlock/dev-server.json`, `WL8008`, `WL8009`, `WL5004`, `--id-header`; "did validation pass for this request", "which queries does this endpoint run", "is there an N+1 on this route", "what middleware runs on this route", "check the endpoint after my change", "request timeline as JSON". Skip: the devtools dashboard in a browser — the `warlock-js-devtools` skill; static route facts (guard, rate limit, schemas) — the `warlock-inspect` topic; typecheck/lint/tests — the `warlock-check` topic.'
 ---
 
 # Warlock — `warlock trace`
@@ -12252,10 +12515,10 @@ Devtools is checked before anything is sent. With `--json` a failure prints `{ "
 
 - The `warlock-inspect` topic — the static facts of a route (guard, rate limit, schemas).
 - The `warlock-check` topic — typecheck, lint, tests and conventions in one run.
-- The `devtools-overview` skill of `@warlock.js/devtools` — the dashboard behind the timeline.
+- The `warlock-js-devtools` skill — the dashboard behind the timeline.
 
 
-## wire-socket  `@warlock.js/core/wire-socket/SKILL.md`
+## wire-socket  `@warlock.js/core/skills/wire-socket/SKILL.md`
 
 ---
 name: wire-socket
@@ -12566,7 +12829,7 @@ CLI commands, scheduled jobs, queue workers — anything running outside an HTTP
 - The `warlock-conventions` topic — where socket-related code lives (a setup function for handler registration, `services/` for emit sites).
 
 
-## write-cli-command  `@warlock.js/core/write-cli-command/SKILL.md`
+## write-cli-command  `@warlock.js/core/skills/write-cli-command/SKILL.md`
 
 ---
 name: write-cli-command
@@ -12907,11 +13170,11 @@ Set a unique owner and registry per app instance, then import `processes` from
 the generated module and await `processes.spawn({ kind: "worker", command,
 args, labels })`. Consume output and await `handle.exited`. Use handle stops or
 label filters; never stop processes by command or name. `spawnPty()` lazily
-loads separately installed optional peer `node-pty`. The `supervise-processes`
-skill in `@warlock.js/process` contains complete working examples.
+loads separately installed optional peer `node-pty`. The `warlock-js-process`
+skill contains complete working examples.
 
 
-## write-middleware  `@warlock.js/core/write-middleware/SKILL.md`
+## write-middleware  `@warlock.js/core/skills/write-middleware/SKILL.md`
 
 ---
 name: write-middleware
@@ -13139,7 +13402,7 @@ export const optionalAuth: Middleware = async ({ request, response }) => {
 - The `warlock-conventions` topic — the `guarded()` / `guardedAdmin()` / `publicRoutes()` convention.
 
 
-## write-seeder  `@warlock.js/core/write-seeder/SKILL.md`
+## write-seeder  `@warlock.js/core/skills/write-seeder/SKILL.md`
 
 ---
 name: write-seeder
@@ -13534,7 +13797,7 @@ warlock seed --transaction    # (default true) — pass --transaction=false to s
 - The `warlock-conventions` topic — `seeds/` is the canonical folder name (singular `seed/` is incorrect).
 
 
-## write-use-case  `@warlock.js/core/write-use-case/SKILL.md`
+## write-use-case  `@warlock.js/core/skills/write-use-case/SKILL.md`
 
 ---
 name: write-use-case