@warlock.js/core 5.34.1 → 5.34.2

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 > ⚠ **Versioning: `@warlock.js/*` does not follow SemVer strictly — breaking changes may ship in a minor.** This is a deliberate decision, not an oversight: the framework is pre-adoption and the cost of a major per behaviour fix currently outweighs the benefit. **Pin an exact version or a tilde range (`~4.13.0`) if you need to opt into changes rather than receive them.** Every breaking change is marked **BREAKING** in its entry and summarised in an _Upgrading_ section at the top of the release. **This policy will change once the framework has consumers beyond its author.**
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Export framework issue-reporting guidance as a proper skill topic; complete index coverage for browser testing and upgrade guidance, and include package orientation in LLM projections.
+
 ## 5.34.1 - 2026-10-19
 
 ### Added

package/llms-full.txt

@@ -4,6 +4,47 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/core/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+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`, 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/add-connector/SKILL.md`
 
 ---
@@ -3745,6 +3786,169 @@ router.get("/webhooks/status", webhookStatusController, { rateLimit: false });
 - The `warlock-conventions` topic — module layout, the `guarded` convention, path aliases.
 
 
+## report-framework-issue  `@warlock.js/core/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/request-memo/SKILL.md`
 
 ---
@@ -11319,7 +11523,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.

package/llms.txt

@@ -6,6 +6,7 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/core/skills/index.md): 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.
 - [add-connector](@warlock.js/core/add-connector/SKILL.md): Extend Warlock with a `BaseConnector` subclass and register its instance in `warlock.config.ts > connectors`. Covers runtime lifecycle (`boot`, `start`, `shutdown`, priority, phase, watched files) and the optional static `build.generate` / `build.emit` contribution used by `warlock build`. Triggers: `BaseConnector`, `connectors`, `ConnectorLifecyclePhase`, `ConnectorBuildContribution`, `build.generate`, `build.emit`; "add a queue worker", "wire a subsystem into bootstrap", "contribute files to warlock build", "control startup ordering", "graceful shutdown hook". Skip: app context accessors — the `use-app-context` topic; general config shape — the `configure-app` topic; competing pattern: hand-rolled process signal blocks, NestJS lifecycle hooks.
 - [benchmark-code](@warlock.js/core/benchmark-code/SKILL.md): Wrap a function with `measure(name, fn, options?)` to time it and classify the latency — onComplete/onError/onFinish hooks, `latencyRange` thresholds, `BenchmarkProfiler` for percentiles, `BenchmarkSnapshots` for raw captures. Triggers: `measure`, `BenchmarkProfiler`, `BenchmarkSnapshots`, `BenchmarkChannel`, `ConsoleChannel`, `latencyRange`, `shouldBenchmarkError`; "time this operation", "profile a slow service", "emit p50/p95/p99 metrics", "classify latency against thresholds"; typical import `import { measure, BenchmarkProfiler } from "@warlock.js/core"`. Skip: retry composition — the `retry-operation` topic; benchmark config wiring — the `configure-app` topic; competing libs `prom-client`, `pino`, `perf_hooks`, `console.time`.
 - [build-restful](@warlock.js/core/build-restful/SKILL.md): Generate standard CRUD endpoints — via `router.route(path).list().show().create().update().destroy()` chain or the `Restful` base class. Pick the chain by default; reach for `Restful` when you want repository-bound defaults. Triggers: `router.route`, `Restful`, `router.restfulResource`, `RouteResource`, `.crud`, `.nest`, `beforeCreate`, `onCreate`; "build a CRUD API", "register list/show/create/update/destroy", "repository-bound default handlers", "override a single REST action"; typical import `import { router, Restful } from "@warlock.js/core"`. Skip: wider router surface — the `register-route` topic; per-action controllers — the `create-controller` topic; wire mapping — the `define-resource` topic; competing pattern: hand-rolled controllers, `@nestjs/swagger` decorator-driven CRUD.
@@ -23,6 +24,7 @@
 - [model-factories](@warlock.js/core/model-factories/SKILL.md): Deterministic model factories for tests and seeders — `defineFactory(Model, (seed) => attributes)` with `make()`, `makeMany(n)`, `create()`, `create(n)`, `createMany(n)`, named states via `.state()` / `.with()`, and a faker-free seed (`seed.text`, `seed.email`, `seed.uuid`, `seed.date`, `seed.number`, `seed.pick`). Triggers: `defineFactory`, `Factory`, `FactorySeed`, `resetFactorySequences`, `userFactory`; "test fixtures", "create test users", "factory states", "deterministic test data", "build a request body for a test". Typical import `import { defineFactory } from "@warlock.js/core/tests"`. Skip: seeding a real database for development — the `write-seeder` topic; fakes — the `test-fakes` topic.
 - [process-image](@warlock.js/core/process-image/SKILL.md): Transform images with the `Image` class — resize, crop, rotate, format, quality, watermark, blur, etc. — using a deferred pipeline that runs only at `save()` / `toBuffer()` / `toBase64()` / `toDataUrl()` time. Requires sharp via `warlock add image`. Triggers: `Image`, `Image.fromFile`, `Image.fromBuffer`, `Image.fromUrl`, `.resize`, `.crop`, `.watermark`, `.toBuffer`, `.toDataUrl`, `.apply`; "resize an image", "generate a thumbnail", "watermark a product photo", "build an image pipeline"; typical import `import { Image } from "@warlock.js/core"`. Skip: multipart upload entry — the `upload-file` topic; storage persistence — the `store-file` topic; competing libs `sharp` direct, `jimp`, `imagemagick`, `gm`.
 - [register-route](@warlock.js/core/register-route/SKILL.md): Register HTTP routes via @warlock.js/core's router — single routes, prefix groups, middleware-guarded blocks, and RESTful resource chains. Routes always live in `src/app/<module>/routes.ts`. Triggers: `router.get`, `router.post`, `router.prefix`, `router.group`, `router.route`, `guarded`; "add a route", "wire a controller to a URL", "group routes by prefix", "register a RESTful resource"; typical import `import { router } from "@warlock.js/core"`. Skip: handler shape — the `create-controller` topic; CRUD chain details — the `build-restful` topic; middleware authoring — the `write-middleware` topic; competing libs `express`, `fastify`, `koa`, `@nestjs/common`.
+- [report-framework-issue](@warlock.js/core/report-framework-issue/SKILL.md): 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.
 - [request-memo](@warlock.js/core/request-memo/SKILL.md): Memoize async work for one HTTP request with `requestMemo<T>(key, fn)` — the v5 replacement for removed `fromRequest`, with single-flight promise sharing, settled-success reuse, rejection eviction, and no cross-request fallback. Triggers: `requestMemo`, `fromRequest`, `fromRequest removed`, `request-scoped cache`, `single-flight`, `current request memo`; "migrate off fromRequest", "load this once per request", "deduplicate concurrent loaders", "cache a repository lookup during one request"; typical import `import { requestMemo } from "@warlock.js/core"`. Skip: middleware-written request state — the `use-request-locals` topic; process-wide or cross-request caching — the `use-middleware` topic; competing patterns: dynamic `request[key]` properties, module-global `Map`, payload `request.get()` / `request.set()`.
 - [request-tracing](@warlock.js/core/request-tracing/SKILL.md): Vendor-neutral request tracing hooks (`http.tracing`) — observe request start/end and named phase spans (`route.match`, `middleware`, `validation`, `handler`, `response.write`) without adopting an OTel/vendor dependency in `core`. Covers the `TracingHooks` shape, trace id derivation from an inbound W3C `traceparent` vs `request.id`, that a throwing hook is caught and reported once (never breaks the request), and zero overhead when disabled. Triggers: `http.tracing`, `TracingHooks`, `onRequestStart`, `onRequestEnd`, `onPhase`, `traceparent`, `traceId`, `dispatchPhase`, "instrument requests", "trace a request", "slow phase logging", "APM / OTel bridge for Warlock". Skip: request-id header echo/inheritance (`X-Request-Id`) — the `use-middleware` topic; app-level structured logging — the `logger-basics` topic of the `warlock-js-logger` skill; competing libs `@opentelemetry/api` direct instrumentation, `express-request-id`, hand-rolled `X-Trace-Id` middleware.
 - [resolve-path](@warlock.js/core/resolve-path/SKILL.md): Path helpers anchored at `process.cwd()` — `rootPath`, `srcPath`, `appPath`, `configPath`, `publicPath`, `storagePath`, `uploadsPath`, `cachePath`, `logsPath`, `tempPath`, `warlockPath`, `sanitizePath`. Optional `uploads.root` config overrides the uploads anchor. Triggers: `appPath`, `configPath`, `uploadsPath`, `storagePath`, `publicPath`, `cachePath`, `logsPath`, `tempPath`, `sanitizePath`, `paths`; "resolve a path inside src/app", "absolute upload destination", "sanitize a user filename", "ship uploads to a mounted volume"; typical import `import { appPath, uploadsPath } from "@warlock.js/core"`. Skip: HTTP URL helpers — the `build-url` topic; app metadata — the `use-app-context` topic; storage abstraction — the `store-file` topic; competing patterns: `path.join(process.cwd(), ...)`, hand-rolled directory constants.

package/package.json

@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^3.0.0",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.34.1",
-    "@warlock.js/cascade": "5.34.1",
-    "@warlock.js/context": "5.34.1",
-    "@warlock.js/fs": "5.34.1",
-    "@warlock.js/logger": "5.34.1",
-    "@warlock.js/seal": "5.34.1",
+    "@warlock.js/cache": "5.34.2",
+    "@warlock.js/cascade": "5.34.2",
+    "@warlock.js/context": "5.34.2",
+    "@warlock.js/fs": "5.34.2",
+    "@warlock.js/logger": "5.34.2",
+    "@warlock.js/seal": "5.34.2",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -55,12 +55,12 @@
     "@aws-sdk/lib-storage": "^3.955.0",
     "@aws-sdk/s3-request-presigner": "^3.955.0",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/access": "5.34.1",
-    "@warlock.js/ai": "5.34.1",
-    "@warlock.js/ai-tools": "5.34.1",
-    "@warlock.js/devtools": "5.34.1",
-    "@warlock.js/herald": "5.34.1",
-    "@warlock.js/notifications": "5.34.1",
+    "@warlock.js/access": "5.34.2",
+    "@warlock.js/ai": "5.34.2",
+    "@warlock.js/ai-tools": "5.34.2",
+    "@warlock.js/devtools": "5.34.2",
+    "@warlock.js/herald": "5.34.2",
+    "@warlock.js/notifications": "5.34.2",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -145,7 +145,7 @@
   "engines": {
     "node": ">=22.15"
   },
-  "version": "5.34.1",
+  "version": "5.34.2",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/index.md

@@ -14,11 +14,11 @@ Core is the application runtime: it boots the app, auto-loads each module's spec
 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 `report-framework-issue.md` to prepare a public report and ask the user before filing.
+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
+- **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
@@ -26,7 +26,7 @@ When the framework is wrong or missing a capability, follow `report-framework-is
 - **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-http, test-service, test-fakes, model-factories
+- **Testing:** test-browser, test-http, test-service, test-fakes, model-factories
 
 ## Conventions and pitfalls
 

package/skills/{report-framework-issue.md → report-framework-issue/SKILL.md}

@@ -1,3 +1,8 @@
+---
+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,

package/skills/warlock-check/SKILL.md

@@ -127,7 +127,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.

package/skills/README.md

@@ -1,76 +0,0 @@
-# @warlock.js/core — skills index
-
-Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The `llms.txt` / `llms-full.txt` at the package root are **generated projections** of this folder — run `node scripts/generate-llms.mjs` from the package root after any skill change; never hand-edit them.
-
-## HTTP layer
-
-- `register-route` — register single routes, prefix groups, middleware-guarded blocks, and RESTful resource chains.
-- `build-restful` — generate standard CRUD endpoints via the `router.route(...)` chain or the `Restful` base class.
-- `create-controller` — author HTTP controllers: `RequestHandler` signature, validated input, response helpers, middleware, `responseSchema` response types.
-- `send-response` — `Response` helpers: success/error variants, status helpers, redirects, files, streams, SSE.
-- `validate-input` — author seal schemas, attach them to controllers, infer types, layer DTOs.
-- `use-middleware` — attach built-in HTTP middleware (rateLimit, concurrencyLimit, maxBodySize, …) via the `middleware` namespace.
-- `write-middleware` — author HTTP middleware: the `({ request, response })` signature, short-circuit, request enrichment.
-- `build-url` — HTTP URL helpers (`url`, `publicUrl`, `assetsUrl`, `uploadsUrl`) anchored at `app.baseUrl`.
-- `upload-file` — handle multipart uploads: `request.file()`, `v.file()` validation, `UploadedFile.save()`.
-- `health-checks` — built-in `/health` + `/ready` endpoints, the `health` registry, and graceful request draining.
-
-## Data layer
-
-- `use-repository` — subclass `RepositoryManager`: `source`/`filterBy`/`defaultOptions`, list/find/CRUD, cached/cursor variants, and the `filterBy`-aware aggregates (`sum`/`avg`/`min`/`max`/`groupBy`/`aggregate`).
-- `use-model-transformers` — schema-side helpers: `useHashedPassword()`, `useComputedSlug()`, and friends.
-- `define-resource` — map model fields to wire-shape via `defineResource()` / `Resource` subclasses (output-only); typed output with `ResourceOutput`, `Serialized<T, W>` and `ModelResourceRegistry`.
-- `write-seeder` — author a seed file with `seeder()` — `name`/`dependsOn`/`once`/`order`/`batchSize`, `run({ track, now, batchSize })`, `warlock seed --drop`.
-
-## Files, media, mail
-
-- `store-file` — read/write/delete files via the `storage` singleton (local/S3/R2/DO Spaces), `StorageFile` handles, presigned URLs.
-- `process-image` — transform images with the `Image` class (resize, crop, rotate, format, watermark, …) on a deferred pipeline.
-- `send-mail` — send transactional email: the `Mail` fluent builder, `sendMail()`, React Email, test-mode capture.
-
-## App, config, lifecycle
-
-- `configure-app` — the two config layers (`warlock.config.ts` vs `src/config/*.ts`), `.env` + `env()`.
-- `use-app-context` — read app-wide context via the `Application` static class and the `app` runtime accessor.
-- `add-connector` — extend the lifecycle with a `BaseConnector` subclass (`start`/`shutdown`/`watchedFiles`).
-- `wire-socket` — configure Socket.IO, reach the live server via `getSocketServer()` / `app.socket`.
-- `use-localization` — multi-locale translations: `groupedTranslations`, `t()` (always, never `request.t()`), locale resolution.
-
-## Use-cases & services
-
-- `write-use-case` — author `useCase()` pipelines: guards, schema, before/after, retry, benchmark, broadcast, lifecycle.
-- `create-module` — scaffold a feature module under `src/app/<name>/` via `warlock generate.module` + follow-up generators.
-- `make-endpoint` — `warlock make endpoint <module>/<name>`: one spec-first endpoint (schema → service, resource, controller, route, locale key, OpenAPI response, HTTP test); `--dry-run` / `--json` on every generator.
-
-## CLI & operations
-
-- `warlock-doctor` — `warlock doctor`: read-only diagnostics (routes/config/connectors/optional-peers/health/release-hygiene) with a pass/warn/fail report and non-zero exit on failure.
-- `warlock-inspect` — `warlock inspect [--json] [--section ...]`: the app's routes, models, resources, config keys, events, pages, jobs, schedules and package versions from the booted registries, as a versioned JSON report; `inspectApp()` from `@warlock.js/core/tooling`.
-- `warlock-check` — `warlock check` / `typecheck` / `explain`: one verify command (typecheck, lint, affected tests, conventions) with one JSON object per problem, stable `WL` error codes, and exit 1 for your code vs 2 for this machine.
-- `warlock-mcp` — `warlock mcp [--http] [--allow-writes]` and `warlock dev --mcp`: the app as an MCP server for coding agents — `inspect_*`, `db_schema`, offline `docs_search` over installed skills, `explain`, `check_run`, `test_run`, devtools `requests_recent`, and `generate_make` / `generate_add` that return a diff by default.
-- `warlock-trace` — `warlock trace <method> <url> [--json]`: send one request to the running dev server and print its devtools timeline (middleware, validation, queries with N+1 flags, logs, response, timings).
-- `warlock-agents-md` — `warlock agents-md [--write]`: the app-specific AGENTS.md section between `warlock:generated` markers, refreshed by `warlock dev`.
-- `warlock-board` — `warlock board init|add|status|send|watch`: a git-ignored task board with review states and append-only messages for an implementer and a reviewer agent.
-- `warlock-routes` — `warlock routes`: list the registered HTTP routes as a verb-colored table (method/path/name/action/middleware/source); filter by method/path/name or emit JSON. Read-only, no connectors.
-- `write-cli-command` — author a custom `warlock <cmd>` via the `command()` factory, or inspect built-in `warlock add` feature scaffolding such as the Web starter.
-- `generate-openapi` — `warlock generate.openapi`: an OpenAPI 3.1 document from the routes (validation, `responseSchema`, auth), plus the dev-only API docs page.
-- `run-app` — `warlock dev` / `warlock build` / `warlock start` operational commands.
-- `update-packages` — bump every `@warlock.js/*` dependency with `warlock update`.
-
-## Testing
-
-- `test-http` — integration tests against a real HTTP server (`startHttpTestServer()`, `testGet` / `testPost`).
-- `test-service` — pure unit tests against services/repositories/models/use-cases via `setupTest({ connectors })`.
-- `store-secrets` — app-scoped credentials, lazy keychain/environment/encrypted file storage, memory backends and safe errors.
-- `test-fakes` — mail, queue, cache, storage, clock, ids and secrets fakes, on by default in tests, and their assertions; opting out.
-- `model-factories` — `defineFactory(Model, (seed) => attrs)`: deterministic `make()` / `create(n)` / states.
-
-## Utilities
-
-- `encrypt-data` — reversible AES-256-GCM `encrypt`/`decrypt`, plus one-way `hmacHash` fingerprints.
-- `hash-password` — one-way bcrypt `hashPassword`/`verifyPassword` and the `useHashedPassword()` transformer.
-- `resolve-path` — path helpers anchored at `process.cwd()` (`rootPath`, `srcPath`, `appPath`, …).
-- `benchmark-code` — time a function with `measure(name, fn, options?)` and classify the latency.
-- `retry-operation` — wrap a flaky operation with `retry(fn, options)` (now from `@mongez/reinforcements`).
-- `lower-stage3-decorators` — the `lowerStage3Decorators()` Vite/Vitest plugin for native decorators.
-- `warlock-conventions` — framework-wide invariants: module layout, canonical imports, layered flow, file naming.