@warlock.js/core 5.34.3 → 5.36.0

package/skills/test-http/SKILL.md

@@ -458,3 +458,94 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 - The `create-controller` topic — the controller shape your HTTP tests are exercising.
 - The `warlock-conventions` topic — module layout, where `tests/*.test.ts` files live.
 - The `write-cli-command` topic — `warlock add test` scaffolds both global + worker setup files.
+
+## Worker dictionaries and owned runtime resources
+
+The generated `src/test-setup.ts` calls:
+
+```ts
+await setupTest({ importModule: (file) => import(file) });
+```
+
+`setupTest()` reads `src/app/*/utils/locales.json` after configuration in each
+Vitest worker. Server translation helpers therefore see all configured locales
+without manual registration. Invalid dictionaries fail setup. `teardownTest()`
+unregisters those dictionaries; legacy executable locale files still require
+explicit imports in worker setup.
+
+Global HTTP fixtures should use `await startHttpTestServer({ port: 0, web: false })`
+for API-only suites and `await stopHttpTestServer()` in teardown. Stop releases
+connectors and the file runtime's loader channel, queued work, watchers, health
+workers, and registered module cleanup hooks, including after partial startup.
+A Node loader registration is process-scoped; its message channel is closed at
+teardown. Module-owned timers/listeners must register their cleanup hooks.
+
+A module that owns a long-running handle can export an awaited cleanup:
+
+```ts
+// src/app/messages/main.ts
+import { createServer } from "node:net";
+const listener = createServer();
+listener.listen(0, "127.0.0.1");
+export async function cleanup(): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    listener.close((error) => (error ? reject(error) : resolve()));
+  });
+}
+```
+
+HTTP test teardown awaits these cleanup functions and reports failures after
+attempting every module's cleanup. Avoid leaving module-owned handles running
+outside this lifecycle.
+
+## Response contracts from declared schemas
+
+`assertResponseContracts` from `@warlock.js/core/tests` sends HTTP requests and
+asserts the serialized JSON body against the handler's `responseSchema` for the
+actual status. It reuses Core's OpenAPI schema translation, including resource
+classes, nested objects, arrays, nullable casts and resource self references.
+It checks required fields and primitive types without coercion; extra fields
+are allowed. URL/date format annotations are not checked beyond their declared
+JSON shape. Builders, computed resolvers and resources without a static shape
+fail with a diagnostic rather than silently passing.
+
+```ts
+import { it } from "vitest";
+import { router } from "@warlock.js/core";
+import { assertResponseContracts } from "@warlock.js/core/tests";
+
+it("matches product response declarations", async () => {
+  await assertResponseContracts({
+    routes: router.list().filter((route) => route.path === "/products"),
+    cases: () => [{ path: "/products?page=1&limit=10", status: 200 }],
+    requireAllStatuses: true,
+  });
+});
+```
+
+With the shared test server, retain `startHttpTestServer({ port: 0 })` in global
+setup and `setupTest` in the worker. The routes and their handler schemas must
+also be loaded in the worker running this assertion (import their routes module
+there); global setup runs in a different process. Omit `routes` to discover all
+registered routes with `responseSchema` in that worker. Empty discovery fails.
+Explicit routes lacking a schema also fail.
+
+Static GET routes default to one request without headers. Parameterized routes
+and non-GET methods require explicit `cases(route)` fixtures; an empty case
+list fails. Each case can supply a concrete `path`, `init` (headers, serialized
+body, etc.) and expected `status`. Supply fixtures with valid IDs, seeded data,
+authentication and invalid inputs to exercise the desired outcomes. An `all` route also needs a concrete fixture `method`. Redirects
+are not followed. POST/PUT/PATCH/DELETE fixtures execute real side effects;
+use isolated test data and clean it up.
+
+Undeclared response statuses fail. Only statuses actually returned are checked
+by default; `requireAllStatuses: true` additionally fails if any declared status
+has no exercised fixture. HEAD, 204 and 304 responses must have an empty body; declare it with
+`{ body: {} }`. Other statuses must carry matching JSON.
+
+For an in-process server, pass `client: app` from `createTestHttpServer()` and
+close it in teardown. For signed-in requests, pass `client: await actingAs(user)`
+and dispose that client afterward. These clients use the same assertion and
+run the real HTTP middleware and serialization paths.
+
+Cleanup hooks that own asynchronous handles should return a promise for completed closure. For MessagePorts, subscribe to `close` before calling `close()` and await the event before checking reference state.

package/skills/test-service/SKILL.md

@@ -13,9 +13,9 @@ For unit tests, you import the thing under test and call it directly. No HTTP, n
 
 ⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an _explicit_ value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
 
-**The lifetime is FILE-SCOPED, on purpose.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
+**The default lifetime is FILE-SCOPED.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
 
-⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See _Lifecycle and repeated calls_ below.
+Worker lifetime is available as an opt-in in 5.35.0. See the runtime lifetime section below for its runner, pool and isolation requirements.
 
 ⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
@@ -417,7 +417,7 @@ Node process, preserve the source package's module mode. ESM fixtures need a
 CommonJS and named exports fail before the behavior under test runs. Assert the
 child process exit status with its captured stderr before checking stdout.
 
-- **`setupTest` runs per test file, not per worker** — every version of this skill through 4.13.0 said otherwise. **You pay one framework bootstrap per test file**, which is what 4.13.0 already cost; the difference is that it is now a chosen lifetime rather than a side effect of a module flag resetting.
+- **By default `setupTest` boots per test file** — every version of this skill through 4.13.0 said otherwise. **You pay one framework bootstrap per test file**, which is what 4.13.0 already cost; the difference is that it is now a chosen lifetime rather than a side effect of a module flag resetting.
 - ⛔ **Never delete the `afterAll(teardownTest)` from your setup file.** Without it nothing closes what `setupTest` opened, and the connectors outlive the file that started them.
 - ⛔ **You can't swap the connector set by calling `setupTest` again — it rejects now.** Through 4.13.0 the second call was silently ignored. Tear down first, or don't call it.
 - **These connections are separate from the HTTP test server's.** A row inserted by a service-level test is on this connection; the HTTP test server has its own. They only see each other if both point at the same physical DB **and** the inserting test has committed.
@@ -444,3 +444,161 @@ setupTest({ importModule: (file) => import(file) });
 ```
 
 The generated `src/test-setup.ts` already does this. Without it, `setupTest()` under Vitest warns once.
+
+## Runtime lifetime, unit projects and setup profiling
+
+`warlock add test` (also used by `create-warlock --features=test`) generates two
+Vitest projects. `unit` discovers `src/**/*.spec.ts` outside `tests/` directories
+and has no Warlock setup or HTTP global setup. `integration` discovers
+`src/**/*.test.ts`, specs inside `src/**/tests/`, and `tests/**/*.{test,spec}.ts`.
+It uses the framework setup, HTTP global setup and a generated `src/test-runner.ts`.
+Keep pure service specs beside their source and mock repositories at the boundary.
+Existing config files are preserved; copy the projects layout into them manually.
+Vitest 5 or newer is required for the generated runner (Vitest 5 removed `vitest/runners`; the runner extends `TestRunner` from `vitest`).
+
+For a unit spec that needs configuration values, use:
+
+```ts
+import { afterAll, expect } from "vitest";
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
+
+await setupTest({
+  mode: "unit",
+  importModule: (file) => import(file),
+  file: expect.getState().testPath,
+});
+afterAll(teardownTest);
+```
+
+Unit mode loads `warlock.config.ts` and configuration values once per module graph.
+It skips bootstrap/env/prestart hooks, connectors, config special handlers,
+`filesOrchestrator.init()`, the native ESM loader, and fake installation. Keep
+configuration imports free of side effects; arbitrary code imported by a config
+file can still perform I/O. A plain unit spec usually needs no `setupTest()` at all.
+`connectors: false` still bootstraps; it is not the cheap unit mode. Use separate
+projects for unit and integration runtimes.
+
+### Opt into one runtime per fork
+
+The default remains `tests.lifetime: "file"`. To reuse a runtime, change the
+integration project's `isolate` to `false`, keep `pool: "forks"` and
+`runner: "./src/test-runner.ts"`, then configure:
+
+```ts title="src/config/tests.ts"
+import { resetWorkerDatabase } from "../test-database";
+
+export default {
+  lifetime: "worker",
+  // Application-owned callback: truncate only this worker's test database.
+  // Called before every file's fixtures, including the first file.
+  resetBetweenFiles: async () => {
+    await resetWorkerDatabase();
+  },
+  profileSetup: true,
+};
+```
+
+Run with `npx vitest run --project integration`. Worker lifetime refuses watch,
+threads, isolated module graphs, or a missing runner with a message explaining
+the required settings. Keep `afterAll(teardownTest)` in the setup file: in worker
+mode it marks the end of the file; Vitest's awaited worker cleanup closes the
+runtime once. The runner uses `TestRunner.onCleanupWorkerContext`, verified
+in Vitest 5.0.3's `TestRunner` declaration, runner implementation and worker cleanup source.
+For an existing project, generate this runner without overwriting your config:
+
+```ts title="src/test-runner.ts"
+import { configureTestWorker } from "@warlock.js/core/tests";
+import { TestRunner } from "vitest";
+
+export default class WarlockTestRunner extends TestRunner {
+  public constructor(config: ConstructorParameters<typeof TestRunner>[0]) {
+    super(config);
+    configureTestWorker(
+      { pool: this.pool, watch: config.watch, isolate: config.isolate },
+      (cleanup) => this.onCleanupWorkerContext?.(cleanup),
+    );
+  }
+}
+```
+
+The first file bootstraps; subsequent files reuse connectors and config. Between
+files, selected fakes are restored and reinstalled, resetting mail/queue records,
+cache, secrets, clock, IDs and a private storage directory. Worker storage is
+separate from the global HTTP server's storage: use an in-process test HTTP server
+when assertions need to see request-side fake state. The hook runs after fake
+reset and before fixtures. It must finish before returning. Within a file,
+repeated `setupTest()` calls remain idempotent; use `beforeEach`/`afterEach` for
+per-test cleanup.
+
+This trades module isolation for startup cost: application singletons, config
+mutations, mocks and module side effects can survive between files. Reset your
+own state in `resetBetweenFiles`, restore mocks, and keep connector selection
+consistent. Give each worker a distinct database/schema using
+`process.env.VITEST_POOL_ID` (1-based since Vitest 5) when preparing test connections. Never drop a shared
+database from this hook while other workers are using it. The framework does not
+create a memory replica set or a cross-worker lock; those belong to the application's
+global setup. A shared HTTP server and a single replica set can contend on I/O,
+locks and shared fixtures even though workers run concurrently. Scope rows and
+HTTP fixtures per worker, or run tests that require global mutation separately
+with `maxWorkers: 1`. No test-server teardown ownership changes are needed here.
+
+`getTestRuntimeStats()` from `@warlock.js/core/tests` returns process-local
+`{ bootstraps, files }`. For example, after setup in worker mode:
+
+```ts
+import { expect, it } from "vitest";
+import { getTestRuntimeStats } from "@warlock.js/core/tests";
+
+it("reuses this worker's runtime", () => {
+  expect(getTestRuntimeStats().bootstraps).toBe(1);
+});
+```
+
+Across one integration project, a successful run with no worker recycling needs
+at most `maxWorkers` bootstraps. Multiple projects, worker crashes and memory-limit
+recycling can create additional processes; count distinct PIDs in profiles.
+
+### Measure and size CI workers
+
+Set `tests.profileSetup: true` or run
+`WARLOCK_TEST_PROFILE=1 npx vitest run --project integration`. Pass
+`file: expect.getState().testPath` to `setupTest()` for file labels (the generated
+setup does this). Each file emits one line with milliseconds for environment, config,
+bootstrap, orchestrator, app config, connectors, fakes, reset and teardown as
+applicable. Reused files report reset instead of startup steps. A summary per
+worker reports file/bootstrap counts, summed step timings and final shutdown.
+The generated config also installs `TestSetupReporter` from `@warlock.js/core/vite`
+(`reporters: ["default", new TestSetupReporter()]`), which aggregates file counts,
+bootstrap counts and timings across PIDs into a run summary. Summed timings are
+not wall time. Worker shutdown is included when its summary reaches the reporter
+before the run-end callback; individual worker summaries always report it.
+
+The generated config sets `maxWorkers: recommendedTestWorkers()` from
+`@warlock.js/core/vite`. It takes the smaller of CPU affinity and the tightest
+visible cgroup v2 quota, rounding fractional CPUs down with a minimum of one.
+For example `cpu.max = 1200000 100000` recommends 12 workers on a 48-CPU host.
+The format follows the [kernel cgroup v2 CPU interface](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#cpu-interface-files).
+It reads `/proc/self/cgroup` and visible ancestors under `/sys/fs/cgroup`; hosts
+without readable v2 quotas use affinity. Set `maxWorkers` explicitly on cgroup v1,
+custom cgroup mounts, or when database/memory limits require fewer workers.
+
+### Release gate
+
+```bash
+npx warlock test --changed --since "$LAST_RELEASE_REF"
+npx vitest run --project integration
+# Nightly (all projects):
+npx vitest run
+```
+
+The first command includes affected tests, using the existing changed-test CLI;
+the second always covers integration wiring. Keep the full suite nightly and
+compare cold and reused setup profiles on the same revision, worker count and
+database fixture before claiming a speedup.
+
+For a manual fake harness outside `setupTest`, the same private storage behavior
+is available with `await installTestFakes(true, { isolatedStorage: true })`, paired
+with `await restoreTestFakes()`. Both are exported from `@warlock.js/core/tests`.
+`await storageFake.install({ isolated: true })` / `await storageFake.restore()`
+provides it for a storage-only harness. Existing installs share the HTTP root by
+default; the isolated option never replaces or deletes that shared root.

package/skills/upgrade-from-5-29/SKILL.md

@@ -534,3 +534,112 @@ editor settings and nonstandard scripts can also require review.
 existing Oxc configs retain their categories. A real lockfile beside a workspace
 marker determines the installer: `package-lock.json` plus `pnpm-workspace.yaml`
 without `pnpm-lock.yaml` now produces `npm install`.
+
+## 5.34 to 5.35 resource hidden input
+
+Model resources now receive hidden input columns (subject to `resourceColumns`)
+to support derivations such as `has_secret: Boolean(data.secret)`. Model
+serialization removes `hidden` top-level keys from the final resource result.
+Review resources that copy input under renamed or nested keys and return explicit
+public projections. Direct resource construction does not invoke model filtering.
+
+## 5.34 to 5.35 document hydration
+
+Initial Web hydration now includes `root.tsx`, matching the document ancestry
+used by SSR so `useId()` and generated Mongez form IDs agree beneath layouts.
+Root components and providers execute in both realms. Move server-only work into
+`root.setup.ts` loaders and pass browser-safe results as `data`; retain exactly
+one `#vessel` around `{children}`. Client navigation still swaps layout/page
+children while preserving the document root. Remove temporary explicit form IDs
+only when the application does not otherwise depend on those names.
+
+## 5.35 to 5.36 per-page API routes
+
+A page document now carries only the named API routes its client code can reach. Before 5.36 every page carried every named route, so a browser call to a name the build cannot see worked on every page by accident. Check each `apiHref()` and `useSubmitForm({ route })` call:
+
+- A name written as a string literal, a constant or a template with a static prefix is found automatically.
+- A name computed at run time, or taken from a module the build cannot follow, now throws on the page that calls it. Declare the names in that page's setup file, for example `export const config = { apiRoutes: ["orders.*"] };`, a layout or root `config` covers every page that renders it. Or call the endpoint with an explicit `path` and `method`.
+- `npx warlock check` reports the call sites that need a declaration as `WL9019`.
+
+Routes registered with `clientVisible: false` are never embedded, and a browser call to one is an error (`WL9020`). Keep endpoints the browser must not reach on that option. Authorization is unchanged: the server still decides each request.
+
+To measure a page's inline payload, set `build.budgets.payload` (default `64kb`). An over-budget route logs one line per process and never fails a request.
+
+## 5.35 to 5.36 translation payloads
+
+A page's hydration payload now carries only the translations its client code
+can reach, in route-dictionary (`locales.json`) and global-registry (`extend()`)
+apps alike. The groups every page uses (default `app` and `common`) arrive once
+per locale in a hashed, cached file that the page preloads. Nothing in a page's
+render changes: server output is the full dictionary, as before.
+
+Run `warlock build`, then `warlock check`. A `WL9104` warning marks a page that
+renders a translation key computed at runtime. Declare the keys it renders in
+the page's setup file, for example
+`export const config = { translations: ["statuses.*", "members.title"] }`, so the
+page ships only what it uses.
+
+In development, a warning names a key the page reads but its payload lacks, and
+resolves it from the full table so the page keeps working. In production the
+key renders as its own text and the miss is reported once through
+`onClientError` with `kind: "translations"`. Declare the key, or set
+`build: { translations: { prune: false } }` in the web connector options while migrating to
+restore the previous per-page payload.
+
+Global-registry apps are covered too. Their shared table is served at
+`/__warlock/translations/<locale>.<hash>.json`, which is cached immutable in
+production. A direct `trans()` call from `@mongez/localization` is not checked
+for a pruning miss; the calls through `useTrans()` are.
+
+## 5.35 to 5.36 Vite 8 and Vitest 5
+
+`@warlock.js/web` requires Vite 8 (`^8.0.0`) and `@vitejs/plugin-react` 6, and the
+test kit requires Vitest 5. Vite 8 bundles with Rolldown and transforms
+TypeScript with Oxc. Vite 7 is not supported; plugin-react 6 needs Vite 8, so the
+family moves together. Vite 8 needs Node.js 20.19 or 22.12 and newer, Vitest 5
+needs 22.12 or newer; Warlock already requires 22.15.
+
+```bash
+npx warlock upgrade --from 5.35 --to 5.36.0 --dry-run
+npx warlock upgrade --from 5.35 --to 5.36.0
+npm install
+npx warlock check
+```
+
+The `vite-8-vitest-5` codemod:
+
+- raises `vite` (8.3.3), `vitest` and `@vitest/*` (5.0.3) and `@vitejs/plugin-react`
+  (6.1.2) in `dependencies`, `devDependencies`, `overrides` and `resolutions`,
+  keeping `^`, `~` or exact style;
+- rewrites a generated `src/test-runner.ts` from `VitestTestRunner` in
+  `vitest/runners` to `TestRunner` from `vitest`, and calls
+  `this.onCleanupWorkerContext?.(cleanup)` (the hook is absent in vm pools);
+- lists, without editing, imports of the removed `vitest/coverage`,
+  `vitest/reporters`, `vitest/environments`, `vitest/snapshot`, `vitest/suite`,
+  `vitest/mocker` and `vitest/internal/module-runner` entry points, other names
+  imported from `vitest/runners`, a top-level `esbuild` option in a Vite or
+  Vitest config, and object-form `output.manualChunks`.
+
+Do these by hand when the codemod lists them:
+
+- Move a config's `esbuild: { jsx: "automatic" }` to
+  `oxc: { jsx: { runtime: "automatic" } }`. `esbuild.target` is not converted, and
+  Oxc does not lower native decorators: keep `lowerStage3Decorators()` from
+  `@warlock.js/core/vite` first in `plugins` for decorated modules, as in the
+  generated test config.
+- Replace object `manualChunks` with
+  `build.rolldownOptions.output.codeSplitting.groups`; `build.rollupOptions` still
+  works but is deprecated in favour of `build.rolldownOptions`.
+- A custom bundler `external` list that names Node builtins is still refused by the
+  client build.
+
+Vitest 5 changes defaults that can alter a green suite: `clearMocks` is true,
+`json` and `junit` reporters write to `.vitest/` instead of stdout, `-t` joins a
+test's names with `>`, `VITEST_POOL_ID` and `VITEST_WORKER_ID` start at 1, nested
+`vi.mock`/`vi.hoisted` calls throw, and an unawaited `resolves` or `rejects`
+assertion fails the test. Vitest also no longer searches parent directories for a
+config file; run it from the package that owns the config. Official guides:
+https://vite.dev/guide/migration and https://vitest.dev/guide/migration.
+
+A project that uses `@warlock.js/ai`'s custom matchers needs Vitest 5 for their
+TypeScript types.

package/skills/use-localization/SKILL.md

@@ -336,3 +336,28 @@ GET /products/42?locale=ar
 This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()` and `t()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
 
 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.
+
+## Worker dictionaries and owned runtime resources
+
+The generated `src/test-setup.ts` calls:
+
+```ts
+await setupTest({ importModule: (file) => import(file) });
+```
+
+`setupTest()` reads `src/app/*/utils/locales.json` after configuration in each
+Vitest worker. Server translation helpers therefore see all configured locales
+without manual registration. Invalid dictionaries fail setup. `teardownTest()`
+unregisters those dictionaries; legacy executable locale files still require
+explicit imports in worker setup.
+
+Global HTTP fixtures should use `await startHttpTestServer({ port: 0, web: false })`
+for API-only suites and `await stopHttpTestServer()` in teardown. Stop releases
+connectors and the file runtime's loader channel, queued work, watchers, health
+workers, and registered module cleanup hooks, including after partial startup.
+A Node loader registration is process-scoped; its message channel is closed at
+teardown. Module-owned timers/listeners must register their cleanup hooks.
+
+## Translation keys in pages (5.36)
+
+`warlock check` reports `WL9104` when a page renders a translation key computed at runtime (`trans(key)` with no static prefix, or a translator passed on as a value). Such a page ships every translation group. Declare its keys in the page's setup file, `export const config = { translations: ["statuses.*", "members.title"] }`, to ship only what it uses. The `web` skill `localize-pages` covers the browser side.

package/skills/warlock-check/SKILL.md

@@ -75,7 +75,7 @@ npx warlock typecheck --changed       # changed files + the files importing them
 npx warlock typecheck --json --project tsconfig.app.json
 ```
 
-`--changed` checks the changed files and their direct importers only; a full run (cheap after the first, it is incremental) catches anything further away.
+`--changed` checks diagnostics for changed files and their transitive importers. The native compiler still performs an incremental program compilation.
 
 ## `warlock explain`
 
@@ -135,3 +135,77 @@ const types = runTypecheck({ files: ["src/app/posts/services/publish.service.ts"
 Migrate lint and format tooling with
 `npx warlock upgrade --from 5.32 --to 5.33.0 --dry-run`, then remove `--dry-run`
 and work through the manual-review list. Use `--lint=oxc` for new apps.
+
+## Web and response contract conventions
+
+The following codes default to **warnings**, so upgrading does not fail existing projects.
+They parse real TypeScript/JSX syntax with the same oxc-parser adapter as the existing conventions.
+
+| Code     | Convention                                                                       | Remedy                                                                                                                                                             |
+| -------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WL9013` | A component file exceeds 150 lines                                               | Split components and extract hooks; configure `componentLineLimit`.                                                                                                |
+| `WL9014` | More than one component in a file                                                | Move each component into its own TSX file.                                                                                                                         |
+| `WL9015` | State/effects or event-handler functions inside a component                      | Move `useState`, `useReducer`, `useEffect`, `useLayoutEffect` and handlers into `use-*.ts` hooks.                                                                  |
+| `WL9016` | Native select, checkbox, radio, date, time or datetime-local input               | Use the design-system control. Native controls are allowed in `src/web/design-system/**`.                                                                          |
+| `WL9017` | DOM input/textarea/select native validation                                      | Use shared schema validation instead of `required`, `pattern`, `min`, `max`, `minLength`, `maxLength` or input `type="email"`. Custom component props are allowed. |
+| `WL9018` | Exported `RequestHandler` in `src/app/**/controllers` lacks `responseSchema`     | Assign `handler.responseSchema` to document each response status.                                                                                                  |
+| `WL9019` | Browser route call (`apiHref`, `useSubmitForm({ route })`) takes a run-time name | Pass a string literal or a template with a static prefix, or declare the names with `config.apiRoutes` in a page setup file.                                       |
+| `WL9020` | Browser code names a route registered with `clientVisible: false` (error)        | Call the endpoint from the server, or remove `clientVisible: false` from the route.                                                                                |
+| `WL9104` | Translation key computed at runtime in `src/web` (the page ships every group)    | Declare the keys with `config.translations` in the page's setup file, for example `["statuses.*"]`.                                                                |
+
+Web rules apply to `src/web/**/*.tsx`. Components are top-level JSX-returning functions
+with a capitalized name (or an anonymous default export). Hook files and ordinary helpers
+are excluded. Handler checks recognize inline JSX callbacks, `handle*`/`on*` functions,
+and local function values referenced by event props. They do not execute code or infer
+runtime spreads, factory contracts or values imported from other files.
+
+Create `.warlock-check.json` in the project root:
+
+```json
+{
+  "componentLineLimit": 180,
+  "rules": {
+    "WL9013": "warning",
+    "WL9015": "error",
+    "WL9016": "off"
+  }
+}
+```
+
+`rules` accepts `"off"`, `"warning"`, or `"error"` for convention codes, including
+existing codes. Per-line `// warlock-check-ignore WL9015 -- reason` works as before.
+Use `npx warlock explain WL9015` for the registry explanation.
+
+```bash
+npx warlock check --changed --fix --json
+```
+
+`--changed` selects tracked changes against HEAD plus untracked source files and their
+transitive import dependents (including re-exports, type imports and related tests).
+Resolution uses the project's compiler configuration, with relative/app imports as a
+fallback for files outside that configuration. Lint and conventions receive that selection;
+Vitest uses related mode. TypeScript still compiles incrementally as a program, then filters
+diagnostics to the selection and its importers; this is not a partial compilation.
+
+`--fix` applies safe convention edits before the pipeline. Currently it removes `.js`
+suffixes from relative imports (`WL9002`). Ignored/disabled findings are not fixed.
+Component extraction, control replacement and response schemas require human decisions.
+Problems that have a safe edit include optional `fix: { start, end, text }` in JSON;
+`start` and `end` are zero-based source string offsets with an exclusive end.
+The report otherwise keeps schema version 1 and its existing shape. Applied fixes disappear
+from the final report; unresolved findings remain. Review the resulting source diff.
+
+Programmatic usage: `await runCheck({ changed: true, fix: true })` from
+`@warlock.js/core/tooling`.
+
+## Explain a source file
+
+`npx warlock explain src/app/posts/services/list.service.ts --json` reports the file's module, convention role, exports, imports, importers and reaching routes/pages. It boots the app for route/page registrations; error-code explanations remain static. See the `warlock-inspect` topic for graph semantics and the boot-free `npx warlock inspect --section files --json` command.
+
+Starter controllers declare a response contract for each returned status. For example:
+
+```ts
+contactController.responseSchema = { 200: { body: { message: "string" } } };
+```
+
+Use `npx warlock inspect --section files --json` for static inspection without booting the app; `npx warlock explain src/app/contact/controllers/contact.controller.ts` explains its entry points.

package/skills/warlock-inspect/SKILL.md

@@ -13,9 +13,9 @@ npx warlock inspect --json > app.json                # the full report
 npx warlock inspect --json --section routes,models   # only some sections
 ```
 
-It boots like `warlock doctor`: connectors boot (routes register) but none starts — no database, cache or socket connection, no port. With `--json`, stdout is only the JSON.
+Except for `--section files` (static source inspection without app boot), it boots like `warlock doctor`: connectors boot (routes register) but none starts — no database, cache or socket connection, no port. With `--json`, stdout is only the JSON.
 
-Sections: `routes`, `models`, `resources`, `config`, `events`, `pages`, `jobs`, `schedules`, `packages`. An unknown section fails before the app boots.
+Sections: `routes`, `models`, `resources`, `config`, `events`, `pages`, `jobs`, `schedules`, `packages`, `files`. An unknown section fails before the app boots.
 
 ## Answer questions with jq
 
@@ -132,3 +132,46 @@ const valid = new Ajv2020({ strict: false }).validate(INSPECT_REPORT_JSON_SCHEMA
 - The `warlock-agents-md` topic — the app summary `warlock dev` keeps in AGENTS.md.
 - The `warlock-routes` topic — the human route table.
 - The `generate-openapi` topic — the same route schemas as an OpenAPI document.
+
+## Session middleware in groups
+
+`sessionMiddleware({ userTypes: "user" })` publishes the same `warlock.auth`
+descriptor as `authMiddleware()`. Group middleware is inherited by nested
+routes, so `inspect` and the generated `agents-md` summary recognize these guards.
+`{ optional: true }` reports `auth.required: false`, with sources and user types
+retained. Such routes remain in the unguarded-write list. Legacy descriptors
+without `required` still mean required authentication.
+
+```ts
+import { router } from "@warlock.js/core";
+import { sessionMiddleware } from "@warlock.js/auth";
+
+router.group({ middleware: [sessionMiddleware({ userTypes: "user" })] }, () => {
+  router.post("/settings", async ({ response }) => response.success({ saved: true }));
+});
+```
+
+## Source files and reachability
+
+```bash
+npx warlock inspect --section files --json
+npx warlock explain src/app/posts/services/list.service.ts
+npx warlock explain src/web/components/Post.tsx --json
+npx warlock explain WL3001 --json
+```
+
+The `files` section reads every file under `src/`, without importing app modules or booting connectors. Each entry has `file`, `module`, `role`, `exports`, `imports` and `importedBy`. Paths are relative to the project root. Modules use `src/app/<module>` or the containing top-level `src` directory. Roles follow file names and directories: controller, service, repository, model, migration, schema, resource, routes, page, setup, layout, root, hook, component, util, type, config and spec; unmatched files use `source`. Non-code assets have empty exports and imports.
+
+Each code file is parsed once with OXC per inspection. Export names include types, aliases, destructured bindings, `default` and `*` for star re-exports; star exports are recorded rather than expanded. Imports include type imports, side effects, re-exports and literal dynamic imports. Each import is `{ specifier, file }`: `file` is the resolved local path, or `null` for external/unresolved imports. Resolution follows inherited tsconfig path aliases, fallback targets, baseUrl, extensionless files and directory indexes within `src/`. Computed dynamic imports and CommonJS `require()` calls are not graph edges. Parse/config failures appear in `warnings`.
+
+File explanations accept a project-relative or absolute path. They boot the app to read the existing routes/pages sections, then walk the static graph to find entry points reaching the file, including page layouts and loaders. Type-only edges participate; this is source reachability, not proof that runtime execution calls a function. Every route declared in a reaching route module is listed. Boot warnings remain in the JSON explanation and human output, so missing registrations are visible. `warlock explain <WLxxxx>` keeps its static error-code behavior.
+
+```ts
+import { inspectApp, explainFile } from "@warlock.js/core/tooling";
+
+const report = await inspectApp({ sections: ["files"] });
+const source = explainFile("src/app/posts/services/list.service.ts", report);
+console.log(source.role, source.exports, source.importedBy);
+```
+
+For route/page reachability in code, call `inspectApp({ sections: ["files", "routes", "pages"] })` in an already booted app. `inspect_files` exposes the section through MCP with a case-insensitive `filter` on file, module or role.

package/skills/warlock-mcp/SKILL.md

@@ -118,3 +118,7 @@ await server.close();
 - The `warlock-check` topic — what `check_run` and `test_run` report.
 - The `warlock-trace` topic — send a request and read its timeline.
 - The `expose-as-mcp-server` topic of @warlock.js/ai-tools — the transport underneath.
+
+## Source file graph
+
+Call `inspect_files` with `{ "filter": "service" }` for file paths, modules, convention roles, export names, resolved imports and reverse `importedBy` edges. This section scans `src/` without executing source modules; files-only requests skip the lazy app boot. `inspect_app` includes a `files` count. See `npx warlock explain src/app/posts/services/list.service.ts --json` for reaching routes and pages.

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

@@ -339,3 +339,21 @@ 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 `warlock-js-process`
 skill contains complete working examples.
+
+## Add the shared design system
+
+```bash
+npx warlock add tailwind
+npx warlock add design-system
+```
+
+`design-system` refuses before dependency installation when Tailwind is absent
+from `package.json` or `src/web/app.css`. It adds pinned shadcn primitives and
+Mongez controls to `src/web/design-system`, preserving existing source files.
+Use `--no-install` to record dependencies only, or `--dry-run --json` to preview
+files and dependencies without writing. For example, a generated control is
+`import TextInput from "web/design-system/components/text-input";` with
+`<TextInput id="profile-name" name="name" label="Name" />`.
+See Web's `build-accessible-controls` topic for the complete control contract.
+
+Built-in `npx warlock add notifications` preloads `config: ["app"]` so generated locale stubs respect `app.localeCodes`, without bootstrap hooks or connectors.

package/esm/production/build-app-production.mjs

@@ -1,14 +0,0 @@
-import { ProductionBuilder } from "./production-builder.mjs";
-
-//#region ../../packages/core/src/production/build-app-production.ts
-/**
-* Build the application for production
-* Options are loaded from warlock.config.ts
-*/
-async function buildAppProduction() {
-	await new ProductionBuilder().build();
-}
-
-//#endregion
-export { buildAppProduction };
-//# sourceMappingURL=build-app-production.mjs.map

package/esm/production/build-app-production.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-app-production.mjs","names":[],"sources":["../../../../../../../../packages/core/src/production/build-app-production.ts"],"sourcesContent":["import { ProductionBuilder } from \"./production-builder\";\n\n/**\n * Build the application for production\n * Options are loaded from warlock.config.ts\n */\nexport async function buildAppProduction() {\n  const builder = new ProductionBuilder();\n  await builder.build();\n}\n"],"mappings":";;;;;;;AAMA,eAAsB,qBAAqB;CAEzC,MAAM,IADc,kBACR,CAAC,CAAC,MAAM;AACtB"}