create-warlock 5.37.1 → 5.39.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `create-warlock` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.39.0 - 2026-10-26
+
+### Fixed
+
+- `npm install` in a fresh scaffold no longer crashes on npm 10.9 (the npm bundled with Node 22) with `Cannot read properties of null (reading 'edgesOut')`: the template pins Vitest 5.0.5, because the Vitest releases before it trip that npm bug on their own. The `edgesOut` hint stays as a last resort.
+
+## 5.38.0 - 2026-10-25
+
+### Added
+
+- The web template ships `src/web/forbidden.page.tsx` and `forbidden.setup.ts` (styled by `forbidden.css`, imported from `app.css`): the page a 401/403 on a page route renders instead of raw JSON. The template README and the `web-code-standards` skill describe it.
+- The starter ships `src/config/web.ts` with `moduleBoundary: "error"`, so browser code importing a server-only module file fails the client build in new apps (the framework default for existing apps is `"warn"`).
+
+### Changed
+
+- The generated testing guidance and code standards use the `*.unit.spec.ts` / `*.unit.test.ts` convention for unit specs (the `test` feature's `unit` and `integration` Vitest projects pick files by that infix).
+- The starter boots the test framework once per Vitest worker: `src/config/tests.ts` sets `lifetime: "worker"` and `resetDatabase: true` (`WARLOCK_TEST_LIFETIME=file` switches back), and `src/config/database.ts` (and the PostgreSQL variant) uses one database per Vitest worker, `<DB_NAME>_test_<worker id>`. With `--features=test` the generated unit project fails a spec that imports a connector or boots the app, and the integration project runs with `isolate: false`. The PostgreSQL variant needs those databases created and migrated first.
+- The template's `testing-strategy` skill describes the per-file reset, the `setupTest({ lifetime: "file" })` opt-out, the unit-project guard, `WL9024`, the boot profile and Vitest 5's `clearMocks` default.
+- The starter app keeps translations in JSON: `app/auth/utils/locales.json` and `app/shared/utils/locales/{validation,http,attributes}.json` replace the two `utils/locales.ts` files, and `docs/new-module.md` describes `locales.json` and `locales/<feature>.json`.
+- The template's `module-boundaries`, `code-standards` and `web-code-standards` skills describe small exported types co-located in `*.service.ts`, optional barrels (and the opt-in `WL9023` lint), the browser-safe surface of an app module and the `*.client.ts(x)` boundary.
+
 ## 5.37.1 - 2026-10-24
 
 ### Changed

package/llms-full.txt

@@ -285,7 +285,7 @@ features. A database-free scaffold needs no external database.
 `npx create-warlock my-project --yes --features=test` delegates to `warlock add test`:
 unit `*.spec.ts` outside `tests/` runs without Warlock setup, integration `*.test.ts`
 and specs under `tests/` use framework setup and the generated cleanup runner.
-The template pins Vitest 5.0.3. See the generated `testing-strategy` skill for
+The template pins Vitest 5.0.5. See the generated `testing-strategy` skill for
 `setupTest({ mode: "unit", importModule })`, opt-in `tests.lifetime: "worker"`,
 `tests.resetBetweenFiles`, profiling and the changed-tests release gate.
 

package/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "@mongez/copper": "^2.1.3",
-    "@warlock.js/fs": "5.37.1",
+    "@warlock.js/fs": "5.39.0",
     "@mongez/reinforcements": "^4.0.2",
     "cross-spawn": "^7.0.3",
     "rimraf": "^6.0.1",
@@ -22,7 +22,7 @@
   "engines": {
     "node": ">=22.15"
   },
-  "version": "5.37.1",
+  "version": "5.39.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/SKILL.md

@@ -277,7 +277,7 @@ features. A database-free scaffold needs no external database.
 `npx create-warlock my-project --yes --features=test` delegates to `warlock add test`:
 unit `*.spec.ts` outside `tests/` runs without Warlock setup, integration `*.test.ts`
 and specs under `tests/` use framework setup and the generated cleanup runner.
-The template pins Vitest 5.0.3. See the generated `testing-strategy` skill for
+The template pins Vitest 5.0.5. See the generated `testing-strategy` skill for
 `setupTest({ mode: "unit", importModule })`, opt-in `tests.lifetime: "worker"`,
 `tests.resetBetweenFiles`, profiling and the changed-tests release gate.
 

package/templates/warlock/AGENTS.md

@@ -70,7 +70,7 @@ automatically on `postinstall`).
   schemas, authentication, and secrets handling.
 - **observability-and-resilience** — structured logging, retries, timeouts, and
   avoiding N+1 work.
-- **testing-strategy** — Vitest test pyramid with co-located `*.spec.ts` files.
+- **testing-strategy** — Vitest test pyramid with co-located `*.unit.spec.ts` unit files and `*.test.ts` integration files.
 - **git-workflow** — conventional commits, branching, PRs, and CI gates.
 
 ## Commands

package/templates/warlock/README.md

@@ -108,6 +108,7 @@ pages served by the same process as the API:
 - `src/web/root.tsx` — the HTML document every page renders inside
 - `src/web/home/index.page.tsx` — the UI at `/`; `index.setup.ts` owns its config (including `config.metadata`), loader, and registration
 - `src/web/404.page.tsx` — the not-found UI; `404.setup.ts` owns its `config.metadata`
+- `src/web/forbidden.page.tsx` — the UI for a 401/403 on a page route (`requireUser()`), never raw JSON; `forbidden.setup.ts` owns its `config.metadata`
 - `src/web/root.setup.ts` — document policy, paired with the `root.tsx` component
 - `*.page.tsx` files under `src/web` are pages; the folder path is the URL
 

package/templates/warlock/docs/new-module.md

@@ -42,7 +42,8 @@ src/app/[module-name]/
 ├── types/                       # TypeScript type definitions
 │   └── *.ts
 └── utils/                       # Module-specific utilities
-    ├── locales.ts              # Translations (auto-imported by Warlock.js)
+    ├── locales.json            # Translations (auto-loaded by Warlock.js)
+    ├── locales/                # Optional per-feature translation files (<feature>.json)
     └── flags.ts                # Constants/flags
 ```
 
@@ -352,7 +353,7 @@ export const cleanup = [event];
 export const cleanup = () => event.unsbcribe();
 ```
 
-**Note:** Files in the `events/` folder are auto-imported, similar to `routes.ts`, `main.ts`, and `utils/locales.ts`. Just create the file and it will be loaded automatically.
+**Note:** Files in the `events/` folder are auto-imported, similar to `routes.ts`, `main.ts`, and `utils/locales.json`. Just create the file and it will be loaded automatically.
 
 ### 11. services/mail/ (or separate mail/ folder)
 
@@ -443,25 +444,27 @@ export type UserRole = "admin" | "user" | "guest";
 
 ### 14. utils/
 
-Module-specific utility functions. **Must include `locales.ts`** which is automatically imported by Warlock.js.
+Module-specific utility functions. Translations live in `locales.json`, which Warlock.js loads automatically.
 
-**utils/locales.ts (Auto-imported):**
+**utils/locales.json (Auto-loaded):**
 
-```typescript
-import { groupedTranslations } from "@mongez/localization";
-
-groupedTranslations("moduleName", {
-  key1: {
-    en: "English translation",
-    ar: "Arabic translation",
+```json
+{
+  "key1": {
+    "en": "English translation",
+    "ar": "Arabic translation"
   },
-  invalidCredentials: {
-    en: "Invalid credentials",
-    ar: "بيانات الدخول غير صحيحة",
-  },
-});
+  "invalidCredentials": {
+    "en": "Invalid credentials",
+    "ar": "بيانات الدخول غير صحيحة"
+  }
+}
 ```
 
+Keys are registered under the module name (`moduleName.key1`); add `"$group": "name"` at the top to pick another group. Every key needs every locale in `app.localeCodes`; `npx warlock check` reports a missing one.
+
+When several people work in one module, put each feature's translations in `utils/locales/<feature>.json` instead of growing one file. All of the module's files are merged at load time, and a key may live in only one of them.
+
 **utils/flags.ts (Constants):**
 
 ```typescript
@@ -488,7 +491,7 @@ export function formatUserName(user: User): string {
 }
 ```
 
-**Note:** The `utils/locales.ts` file is automatically imported by Warlock.js, similar to `routes.ts`, `main.ts`, and files in the `events/` folder.
+**Note:** `utils/locales.json` and `utils/locales/*.json` are loaded automatically by Warlock.js, similar to `routes.ts`, `main.ts`, and files in the `events/` folder. The older `utils/locales.ts` is deprecated; `npx warlock doctor --fix` converts it.
 
 ## Best Practices
 
@@ -540,7 +543,7 @@ export function formatUserName(user: User): string {
 
    - `main.ts` - Module entry point
    - `routes.ts` - Route definitions
-   - `utils/locales.ts` - Translations
+   - `utils/locales.json` and `utils/locales/*.json` - Translations
    - All files in `events/` folder - Event handlers
    - No need to manually import these files elsewhere
 

package/templates/warlock/package.json

@@ -46,7 +46,7 @@
     "@mongez/agent-kit": "^1.3.1",
     "@types/node": "^25.0.3",
     "typescript": "7.0.2",
-    "vitest": "5.0.3",
+    "vitest": "5.0.5",
     "oxlint": "1.88.0",
     "oxfmt": "0.73.0"
   }

package/templates/warlock/skills/code-standards/SKILL.md

@@ -134,9 +134,11 @@ import { OrderStatus } from "app/orders/types/order.type";
 import { listUsersService } from "../../users/services";
 ```
 
-### 2.2 Barrel files — sub-folder level, not module level
+### 2.2 Barrel files — optional, sub-folder level, never module level
 
-Barrels (`index.ts`) make a module easier to consume **at the sub-folder level** — `services/`, `utils/`, `types/`. They become a problem when you put one at the **module root** and turn it into a giant re-export of everything inside.
+Barrels are optional. A module works with none: import from the file that defines the export. A hand-maintained barrel is a file every feature has to edit, which is where merge conflicts and circular imports come from, so add one only where a folder has several files that other modules consume together. Turn on the opt-in `WL9023` rule (`"rules": { "WL9023": "warning" }` in `.warlock-check.json`) to flag barrels, and set `generate: { barrels: false }` in `warlock.config.ts` so generators write none.
+
+Where you do use them, barrels (`index.ts`) make a module easier to consume **at the sub-folder level** — `services/`, `utils/`, `types/`. They become a problem when you put one at the **module root** and turn it into a giant re-export of everything inside.
 
 The right shape:
 
@@ -163,6 +165,22 @@ import { listUsersService, formatUserName, User } from "app/users";
 
 The module-root barrel is the one that causes circular imports and tree-shaking misses. This recommendation applies to server app modules under `src/app/**`. Web feature folders under `src/web/**` have no barrels: imports point to the exact component or hook file so client bundles stay lean and server-only code is never pulled through a barrel. See the `web-code-standards` skill.
 
+### 2.2.1 Small types beside the code that uses them
+
+A `*.service.ts`, `*.repository.ts` or `*.controller.ts` file may export the small input and output types it is written around, next to the function:
+
+```typescript
+// app/orders/services/create-order.service.ts
+export type CreateOrderInput = { customerId: string; lines: OrderLine[] };
+export type CreateOrderResult = { id: string; total: number };
+
+export async function createOrderService(input: CreateOrderInput): Promise<CreateOrderResult> {
+  // ...
+}
+```
+
+`warlock check` raises nothing for this, and another module or a page can share the type with `import type { CreateOrderInput } from "app/orders/services/create-order.service"` (a type-only import is erased, so it never pulls the service into the browser). Move a type to `types/` or `schema/` when several files need it, or when the browser needs the value and not only the type. Do not make a file per type. Web UI is unchanged: one component per file, logic in `*.setup.ts`.
+
 ### 2.3 No file extension in import paths
 
 Always bare: `from "./order.service"`, never `from "./order.service.ts"` or `.js`.
@@ -188,7 +206,8 @@ Always bare: `from "./order.service"`, never `from "./order.service.ts"` or `.js
 | `.setup.ts`               | Page, layout or root policy and server exports | `index.setup.ts`                        |
 | `use-*.ts`                | Named feature hook                             | `use-contact-form.ts`                   |
 | `.resource.ts`            | Output mapper                                  | `user.resource.ts`                      |
-| `.spec.ts` / `.test.ts`   | Co-located test                                | `cart.service.spec.ts`                  |
+| `.unit.spec.ts`           | Co-located unit test (no app boot)             | `cart.service.unit.spec.ts`             |
+| `.spec.ts` / `.test.ts`   | Co-located integration test (booted app)       | `cart.service.test.ts`                  |
 
 **One primary export per file.** If a `.contract.ts` also defines closely-related data types used only by that contract, that's fine — but the primary export is the interface.
 
@@ -567,7 +586,7 @@ A secret with no safe default (a payment key, a signing secret) should fail loud
 
 ## 10. Testing
 
-- **Vitest**, co-located: `cart.service.ts` → `cart.service.spec.ts` in the same folder.
+- **Vitest**, co-located: `cart.service.ts` → `cart.service.unit.spec.ts` in the same folder (the `.unit` infix selects the unit project; a plain `.spec.ts` or `.test.ts` runs in integration).
 - **Test the public surface.** If a private method needs testing, the public method that calls it does — test through it. If you can't reach the behaviour from outside, it shouldn't exist.
 - **Arrange / Act / Assert** structure per test. Blank lines between phases. One assertion target per test where practical.
 - **Mock at the boundary.** Use `MockSDK` from `@warlock.js/ai` for AI calls. Mock HTTP at the HTTP client level, not deep inside services.

package/templates/warlock/skills/module-boundaries/SKILL.md

@@ -51,8 +51,8 @@ src/app/<module>/
   controllers/              ← HTTP handlers (one per endpoint)
     <verb>-<noun>.controller.ts
   services/                 ← business logic (one per use case)
-    index.ts                ← sub-folder barrel ✅
-    <verb>-<noun>.service.ts
+    index.ts                ← optional sub-folder barrel
+    <verb>-<noun>.service.ts   ← may export its small input/output types
   models/
     <noun>/                 ← model folder (Cascade convention)
       <noun>.model.ts
@@ -66,10 +66,10 @@ src/app/<module>/
   resources/                ← output mappers (defineResource)
     <noun>.resource.ts
   types/                    ← TypeScript types and enums
-    index.ts                ← sub-folder barrel ✅
+    index.ts                ← optional sub-folder barrel
     <noun>-status.type.ts
   utils/                    ← pure helpers used inside the module
-    index.ts                ← sub-folder barrel ✅
+    index.ts                ← optional sub-folder barrel
     <verb>-<noun>.ts
   events/                   ← if the module emits events
     <noun>-<verb>.event.ts
@@ -83,17 +83,19 @@ src/app/<module>/
 
 Don't create `events/` if the module emits nothing. Don't create `errors/` until you have an error to put there. The layout is a vocabulary, not a checklist.
 
-### 2.2 No module-root `index.ts`
+### 2.2 No module-root `index.ts`; sub-folder barrels are optional
 
 This is the one absolute rule:
 
 ```
 ❌ src/app/orders/index.ts                ← banned
-✅ src/app/orders/services/index.ts        ← good (sub-folder barrel)
-✅ src/app/orders/utils/index.ts           ← good
-✅ src/app/orders/types/index.ts           ← good
+✅ src/app/orders/services/index.ts        ← allowed (optional sub-folder barrel)
+✅ src/app/orders/utils/index.ts           ← allowed
+✅ src/app/orders/types/index.ts           ← allowed
 ```
 
+A module needs no barrel at all; importing from the file that defines the export is fine. `rules: { "WL9023": "warning" }` in `.warlock-check.json` flags hand-maintained barrels, and `generate: { barrels: false }` in `warlock.config.ts` stops generators from writing them.
+
 See the `code-standards` skill § 2.2 for the reasoning.
 
 ---
@@ -102,13 +104,29 @@ See the `code-standards` skill § 2.2 for the reasoning.
 
 ### 3.1 Public (importable from other modules)
 
-- `src/app/<module>/services` (the sub-folder barrel)
-- `src/app/<module>/utils` (the sub-folder barrel)
-- `src/app/<module>/types` (the sub-folder barrel)
+- `src/app/<module>/services` (the sub-folder barrel, or the service file when there is none)
+- `src/app/<module>/utils` (the sub-folder barrel, or the file)
+- `src/app/<module>/types` (the sub-folder barrel, or the file)
 - `src/app/<module>/resources/<noun>.resource.ts`
 - `src/app/<module>/models/<noun>` (the model folder — for `BelongsTo("Name")` registrations and typed references)
 - `src/app/<module>/errors/<noun>-<reason>.error.ts`
 
+### 3.1.1 Browser-safe (importable from browser code)
+
+`src/app/<module>/` is server code. Code the client build reaches (pages, layouts, components) may import from a module **only**:
+
+- `*.client.ts` / `*.client.tsx` files
+- schema files: `*.schema.ts`, or anything under `schema/`
+- type files: `*.types.ts`, `*.d.ts`, or anything under `types/`
+- the module's `web/` folder
+- non-code files (JSON, CSS)
+
+Anything else (a service, repository, controller, model, route file, a plain helper) fails the client build with the import chain (this app sets `web.moduleBoundary: "error"` in `src/config/web.ts`; the framework default is `"warn"`, which only reports). `import type { CreateOrderInput } from "app/orders/services/create-order.service"` is always fine because a type-only import is erased. `web.moduleBoundary` in `src/config/web.ts` is `"error"` by default, `"warn"` while migrating, `"off"` to disable.
+
+### 3.1.2 `*.client.*` is browser code
+
+A `*.client.ts(x)` file may be imported by pages, layouts and components; it still renders on the server unless the component is wrapped in `<ClientOnly>`. Controllers, services, repositories, models, routes, connectors and `*.server.ts` files must never import it (`npx warlock check` reports `WL9022` with the import chain).
+
 ### 3.2 Private (not importable from other modules)
 
 - `src/app/<module>/controllers/*` — controllers serve HTTP; nobody else should call them
@@ -279,7 +297,7 @@ When you create a new module:
 2. **Create the folder.** `mkdir src/app/<noun>`.
 3. **Add `README.md`** at the module root. One paragraph: what the module owns, who owns the code, public surface.
 4. **Scaffold only what you need.** Don't pre-create `events/` and `errors/` if you won't use them today.
-5. **Add sub-folder barrels** only where you have 2+ files. A single service doesn't need a `services/index.ts` yet — but it will the moment a second service lands.
+5. **Add sub-folder barrels** only if the team wants them; they are optional, and `generate: { barrels: false }` makes generators write none.
 6. **Wire `routes.ts`** for any HTTP endpoints, register events for any emitted signals.
 7. **Verify no module-root `index.ts`** was created.
 
@@ -292,7 +310,8 @@ Before merging a change that adds, restructures, or imports across modules:
 - [ ] New module is named after a single domain noun
 - [ ] Standard folder layout from § 2 (only the folders the module needs)
 - [ ] No module-root `index.ts` created
-- [ ] Sub-folder barrels exist for `services/`, `utils/`, `types/` where applicable
+- [ ] Barrels, if any, are sub-folder barrels; none is required
+- [ ] Browser code imports from `app/<module>/` only `*.client.*`, schema, types and `web/` files
 - [ ] No imports from another module's `controllers/`, `repositories/`, `schema/`
 - [ ] No circular imports between modules (Oxlint `no-cycle` clean)
 - [ ] Cross-module communication uses direct service call or `@mongez/events` — never shared mutable globals

package/templates/warlock/skills/testing-strategy/SKILL.md

@@ -25,7 +25,7 @@ When the `test` feature is selected at scaffold time, both land automatically (V
 
 ### 0.1 If testing is enabled, tests are mandatory — not optional
 
-- **Every service** ships a co-located unit spec: `place-order.service.ts` → `place-order.service.spec.ts`. Cover the happy path, every branch, and every error path. Mock the repository — the service's logic is the unit under test.
+- **Every service** ships a co-located unit spec: `place-order.service.ts` → `place-order.service.unit.spec.ts`. Cover the happy path, every branch, and every error path. Mock the repository — the service's logic is the unit under test.
 - **Every HTTP controller / request handler** ships a test: a unit test with mocked services for its branch / validation / authorization logic, **or** an integration test through the route when the wiring is the point. A new endpoint without a test is an incomplete endpoint.
 
 Write the spec in the **same change** that adds the service or controller. A reviewer treats a missing spec as a blocking defect, not a follow-up.
@@ -299,7 +299,7 @@ Run against a recorded fixture in CI (fast, deterministic). Run against the real
 
 ### 9.2 Where they live
 
-Co-located with the integration: `src/app/payments/clients/stripe-client.contract.spec.ts`.
+Co-located with the integration: `src/app/payments/clients/stripe-client.contract.spec.ts` (an integration spec, because it has no `.unit`).
 
 ---
 
@@ -308,13 +308,13 @@ Co-located with the integration: `src/app/payments/clients/stripe-client.contrac
 ```
 src/app/orders/services/
   place-order.service.ts
-  place-order.service.spec.ts       ← unit test, mocks repository
-  place-order.service.test.ts  ← integration, real DB
+  place-order.service.unit.spec.ts  ← unit test, mocks repository
+  place-order.service.test.ts       ← integration, real DB
 ```
 
-- `.spec.ts` — default suffix; covers unit tests
-- `.test.ts` or a spec inside `tests/` — integration, real I/O (DB, queue)
-- Full-system journeys also use `.test.ts` in the integration project.
+- `.unit.spec.ts` / `.unit.test.ts` — the unit project: no app boot, no setup files
+- every other `.spec.ts` / `.test.ts`, and any file inside `tests/` — integration, with the booted app and real I/O (DB, queue)
+- Full-system journeys are plain `.test.ts` files in the integration project.
 
 Tests live next to the file under test, always. Never in a separate `__tests__/` or `test/` folder — colocation makes the link obvious and survives refactors.
 
@@ -324,7 +324,7 @@ Tests live next to the file under test, always. Never in a separate `__tests__/`
 
 Before merging a change that should include tests (testing enabled — see § 0):
 
-- [ ] Every new/changed **service** has a co-located `.service.spec.ts`
+- [ ] Every new/changed **service** has a co-located `.service.unit.spec.ts`
 - [ ] Every new/changed **HTTP controller / request handler** has a test (unit with mocked services, or integration through the route)
 - [ ] New public function has at least one test
 - [ ] Branches / error paths / edge cases covered
@@ -342,29 +342,42 @@ Before merging a change that should include tests (testing enabled — see § 0)
 ## Runtime cost and release gates
 
 With `--features=test`, create-warlock delegates to `warlock add test` to generate
-`vite.config.ts`: the `unit` project runs `src/**/*.spec.ts` outside `tests/`
-without framework or HTTP setup; `integration` runs `*.test.ts` and specs under
-`tests/` with `src/test-setup.ts`, global HTTP setup and `src/test-runner.ts`.
+`vite.config.ts`: the `unit` project runs `src/**/*.unit.{spec,test}.ts`
+without framework or HTTP setup; `integration` runs every other `*.spec.ts` and
+`*.test.ts` and anything under `tests/` with `src/test-setup.ts`, global HTTP setup and `src/test-runner.ts`.
 Prefer `npx vitest run --project unit` during the pure service loop.
 
 When a unit needs config values, call
 `setupTest({ mode: "unit", importModule: (file) => import(file) })` from
 `@warlock.js/core/tests` and pair it with `afterAll(teardownTest)`. Config loads
 once per module graph, without hooks, connectors, native loader or fakes.
-Most unit specs need no setup call.
-
-Integration setup defaults to `tests.lifetime: "file"`. For reuse, set
-`lifetime: "worker"` in `src/config/tests.ts`, change the integration project to
-`pool: "forks", isolate: false`, keep the generated runner, and use `vitest run`.
-Watch, threads and isolated graphs are refused. Keep `afterAll(teardownTest)`:
-it marks file boundaries while the runner closes connectors at worker exit.
-`warlock add test` generates `src/config/tests.ts` so `WARLOCK_TEST_LIFETIME=worker`
-switches `lifetime` to `"worker"`, turns on `resetDatabase` (truncates every table or
-collection before each file, keeping the migrations ledger) and flips the integration
-project to `isolate: false`. Use `workerDatabaseName(base)` from
-`@warlock.js/core/tests` so each worker has its own database. When setup dominates a
-file-lifetime run, the profiler summary recommends this. Servers from
-`createTestHttpServer()` a file leaves open are closed before the next file.
+Most unit specs need no setup call. The `.unit` infix is the only switch: a plain `.spec.ts` boots the app.
+
+Integration setup boots the framework once per Vitest worker (`lifetime: "worker"`
+in `tests`): the generated `src/config/tests.ts` also turns on `resetDatabase` (truncates
+every table or collection before each file, keeping the migrations ledger), the
+integration project has `pool: "forks", isolate: false` with the generated runner, and
+`src/config/database.ts` gives each worker its own database
+(`<DB_NAME>_test_<worker id>`). Use `vitest run`; watch, threads and isolated graphs are
+refused. Keep `afterAll(teardownTest)`: it marks file boundaries while the runner closes
+connectors at worker exit. `WARLOCK_TEST_LIFETIME=file` boots once per file instead
+(slower, with isolated module state).
+
+Before each file the runtime closes `createTestHttpServer()` servers the previous file
+left open, clears the request context, restores the route table to the booted app's,
+flushes a real in-memory cache, reinstalls the fakes (mail, queue, cache, storage, fake
+clock, ids) and truncates the database. A spec that changes global configuration these
+resets do not undo opts its file out with
+`setupTest({ importModule: (file) => import(file), lifetime: "file" })`.
+
+The `unit` project fails a spec that imports a connector, `connectorsManager`,
+`bootstrap`, a test-server helper, or calls `setupTest()` without `{ mode: "unit" }`.
+`warlock check` reports `WL9024` (a warning) for an integration spec that imports nothing
+needing the app: rename it to `<name>.unit.spec.ts`.
+
+Vitest 5 defaults `clearMocks` to true, which also clears the calls a module made when it
+was imported (a scheduler registering jobs from `main.ts`). To assert those calls, import
+the module inside the test after the mocks are set up, or set `clearMocks: false`.
 Set `tests.resetBetweenFiles` to an async application-owned cleanup callback;
 it runs before every file, including the first, after selected fakes, clock and
 IDs reset. Each worker needs a separate database/schema. Module singletons and
@@ -373,7 +386,9 @@ storage is private and does not mirror the shared HTTP server's fake files.
 
 Use `tests.profileSetup: true` or
 `WARLOCK_TEST_PROFILE=1 npx vitest run --project integration` for file timings and
-summaries per worker. Pass `file: expect.getState().testPath` in the setup call.
+summaries per worker; the run summary lists the boot phases (config, translations,
+connectors one by one, fakes, routes, reset, teardown), the HTTP test server's boot and
+the slowest files, and `WARLOCK_TEST_PROFILE_JSON=profile.json` writes them as JSON. Pass `file: expect.getState().testPath` in the setup call.
 `getTestRuntimeStats()` exposes bootstrap and file counts. Generated configs use
 `recommendedTestWorkers()` from `@warlock.js/core/vite` to respect visible cgroup
 v2 CPU quotas; reduce `maxWorkers` further for database or memory contention.

package/templates/warlock/skills/web-code-standards/SKILL.md

@@ -47,13 +47,24 @@ both places. Put component props in that dedicated type module by default;
 keep a tiny private prop type beside a component only when extracting it would
 make the feature harder to read.
 
+Browser code may import from `app/<module>/...` only `*.client.ts(x)` files,
+schema (`*.schema.ts`, `schema/`), types (`*.types.ts`, `types/`) and the
+module's `web/` folder; other files of a module are server code and fail the
+client build with the import chain. Use `import type` to share the input and
+output types a service exports. A `*.client.ts(x)` file may be imported by
+pages and components (it still renders on the server unless wrapped in
+`<ClientOnly>`) and never by server-only code; `warlock check` reports `WL9022`
+for that. These rules do not change the web layout: one component per file,
+logic in `*.setup.ts` and `use-*.ts`.
+
 ## 1. Keep the page contract, make the implementation thin
 
 Page logic lives in the matching `.setup.ts` file: `config`, `loader`,
 `register`, and `action`/`actions`. The UI file owns its named default
 component; re-export a framework-required named component such as `ErrorBoundary`
 from that component's own file. Pair `layout.tsx` with
-`layout.setup.ts`, `root.tsx` with `root.setup.ts`, and `error.page.tsx` with
+`layout.setup.ts`, `root.tsx` with `root.setup.ts`, `forbidden.page.tsx` with
+`forbidden.setup.ts`, and `error.page.tsx` with
 `error.setup.ts`. Use type-only imports from setup for loader/action inference.
 The framework projects browser-safe `register()` code to the client. Put route,
 cache, validation, middleware, metadata, and sitemap policy inside `config`;

package/templates/warlock/src/app/auth/utils/locales.json

@@ -0,0 +1,64 @@
+{
+  "invalidCredentials": {
+    "en": "Invalid email or password",
+    "ar": "البريد الالكتروني أو كلمة المرور غير صحيحة"
+  },
+  "loggedOut": {
+    "en": "Logged out successfully",
+    "ar": "تم تسجيل الخروج بنجاح"
+  },
+  "loggedOutAll": {
+    "en": "Logged out from all devices",
+    "ar": "تم تسجيل الخروج من جميع الأجهزة"
+  },
+  "refreshTokenRequired": {
+    "en": "Refresh token is required",
+    "ar": "رمز التحديث مطلوب"
+  },
+  "invalidRefreshToken": {
+    "en": "Invalid or expired refresh token",
+    "ar": "رمز التحديث غير صالح أو منتهي الصلاحية"
+  },
+  "userNotFound": {
+    "en": "User not found",
+    "ar": "المستخدم غير موجود"
+  },
+  "otpSent": {
+    "en": "Verification code sent",
+    "ar": "تم إرسال رمز التحقق"
+  },
+  "missingOtp": {
+    "en": "Verification code not found",
+    "ar": "رمز التحقق غير موجود"
+  },
+  "otpInvalid": {
+    "en": "Invalid verification code",
+    "ar": "رمز التحقق غير صالح"
+  },
+  "otpExpired": {
+    "en": "Verification code has expired",
+    "ar": "رمز التحقق منتهي الصلاحية"
+  },
+  "otpMaxAttempts": {
+    "en": "Too many failed attempts",
+    "ar": "عدد المحاولات تجاوز الحد المسموح"
+  },
+  "passwordResetSuccess": {
+    "en": "Password reset successfully",
+    "ar": "تم إعادة تعيين كلمة المرور بنجاح"
+  },
+  "errors": {
+    "missingAccessToken": {
+      "en": "Access token is required",
+      "ar": "رمز الوصول مطلوب"
+    },
+    "invalidAccessToken": {
+      "en": "Invalid or expired access token",
+      "ar": "رمز الوصول غير صالح أو منتهي الصلاحية"
+    },
+    "unauthorized": {
+      "en": "You are not authorized to access this resource",
+      "ar": "غير مصرح لك بالوصول إلى هذا المورد"
+    }
+  }
+}

package/templates/warlock/src/app/shared/utils/locales/attributes.json

@@ -0,0 +1,31 @@
+{
+  "$group": "attributes",
+  "email": {
+    "en": "Email",
+    "ar": "البريد الإلكتروني"
+  },
+  "phoneNumber": {
+    "en": "Phone Number",
+    "ar": "رقم الهاتف"
+  },
+  "firstName": {
+    "en": "First Name",
+    "ar": "الاسم الأول"
+  },
+  "lastName": {
+    "en": "Last Name",
+    "ar": "الاسم الأخير"
+  },
+  "password": {
+    "en": "Password",
+    "ar": "كلمة المرور"
+  },
+  "name": {
+    "en": "Name",
+    "ar": "الاسم"
+  },
+  "image": {
+    "en": "Image",
+    "ar": "الصورة"
+  }
+}

package/templates/warlock/src/app/shared/utils/locales/http.json

@@ -0,0 +1,31 @@
+{
+  "$group": "http",
+  "rateLimitExceeded": {
+    "en": "Too many requests. Please slow down and try again shortly.",
+    "ar": "عدد كبير من الطلبات. يرجى التمهل وإعادة المحاولة قريباً."
+  },
+  "concurrencyLimitReached": {
+    "en": "This endpoint is busy. Please retry in a moment.",
+    "ar": "هذه النقطة الطرفية مشغولة. يرجى إعادة المحاولة بعد قليل."
+  },
+  "bodyTooLarge": {
+    "en": "Request body is too large.",
+    "ar": "حجم الطلب كبير جداً."
+  },
+  "idempotencyKeyInvalid": {
+    "en": "Idempotency-Key header is malformed.",
+    "ar": "ترويسة Idempotency-Key غير صالحة."
+  },
+  "idempotencyKeyConflict": {
+    "en": "Idempotency-Key was reused with a different request body.",
+    "ar": "تم إعادة استخدام Idempotency-Key مع طلب مختلف."
+  },
+  "ipForbidden": {
+    "en": "Access denied for your IP address.",
+    "ar": "تم رفض الوصول من عنوان IP الخاص بك."
+  },
+  "maintenance": {
+    "en": "Service is temporarily unavailable for maintenance.",
+    "ar": "الخدمة غير متاحة مؤقتاً للصيانة."
+  }
+}