@warlock.js/core 5.34.2 → 5.35.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 4.1.10 or newer is required for the generated runner.
+
+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 `VitestTestRunner.onCleanupWorkerContext`, verified
+in Vitest 4.1.10's `runners.d.ts`, 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 { VitestTestRunner } from "vitest/runners";
+
+export default class WarlockTestRunner extends VitestTestRunner {
+  public constructor(config: ConstructorParameters<typeof VitestTestRunner>[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` 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

@@ -476,6 +476,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
@@ -530,3 +534,21 @@ 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.

package/skills/use-localization/SKILL.md

@@ -336,3 +336,24 @@ 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.

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,74 @@ 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.                                                                                                  |
+
+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/warlock-trace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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`
@@ -78,4 +78,4 @@ 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.

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

@@ -337,5 +337,23 @@ 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.
+
+## 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"}