create-warlock 5.34.2 → 5.34.3

package/templates/warlock/skills/observability-and-resilience/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability-and-resilience
-description: 'How this project stays debuggable in production and survives flaky dependencies — `log.<level>(module, action, message, context)` from `@warlock.js/logger` with `X-Request-Id` propagation (already shipped via core middleware), structured metrics naming `<area>.<noun>.<unit>`, health endpoints (`/health/live` for liveness vs `/health/ready` for readiness), timeouts on every external call (`@warlock.js/http` `timeout` per Http instance / per request), retries with exponential backoff for idempotent ops only (never auto-retry POST without an idempotency key), idempotency keys for side effects (payments, emails, webhook deliveries), circuit breakers for flaky deps, graceful shutdown via `log.configure({ autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"] })`, N+1 detection, streaming for large payloads. Triggers: making an HTTP / AI / queue / DB call; adding a timeout or retry; designing an idempotency key for a side effect; instrumenting metrics; adding a health check; tracing a request across services; user asks "timeout", "retry policy", "idempotency", "request id", "tracing", "graceful shutdown", "health check", "circuit breaker", "N+1 query", "caching strategy", "metrics naming"; touching `@warlock.js/http` / `@warlock.js/scheduler` / `@warlock.js/ai` call sites. Skip: log call signature (load `skills/code-standards/SKILL.md` § 8); secrets in logs (load `skills/security-baseline/SKILL.md` § 8); pure-function refactors with no external I/O; cache driver setup (load `@warlock.js/cache` skills); HTTP client config in depth (load `@warlock.js/http` skills).'
+description: "Request correlation, structured logs, timeouts, retries, idempotency, health checks, metrics, shutdown and bounded queries. Use when adding external I/O or production instrumentation. Use security-baseline instead for secrets and sensitive data handling."
 ---
 
 # Observability & resilience
@@ -53,7 +53,7 @@ Set a default at the `Http` instance level; override per request when the endpoi
 // ✅ instance-level default
 const stripeClient = new Http({
   baseURL: "https://api.stripe.com",
-  timeout: 10_000,  // 10s — enough for most calls, short enough to fail fast
+  timeout: 10_000, // 10s — enough for most calls, short enough to fail fast
 });
 
 // ✅ per-request override for a known-slow call
@@ -132,12 +132,14 @@ Persist `key → result` with a TTL longer than your retry window (24h is typica
 
 ### 4.4 Pattern
 
+This simplified service sketch also needs an atomic reservation and provider-side idempotency to prevent concurrent duplicate charges. At the HTTP boundary, require `Idempotency-Key` and run `middleware.idempotency()` after auth as described in the `api-design` skill.
+
 ```typescript
 // ✅
 export async function chargePaymentService(input, idempotencyKey) {
-  const cached = await idempotencyRepository.find({ key: idempotencyKey });
+  const cached = await idempotencyRepository.findBy("key", idempotencyKey);
   if (cached) {
-    return cached.result;
+    return cached.get("result");
   }
 
   const result = await stripeClient.post("/v1/charges", input);
@@ -261,11 +263,11 @@ These belong here because performance failures present as resilience failures
 
 A list endpoint that fires one query per item is a bug. Either eager-load relations (Cascade's `.with("relation")`) or batch-fetch the related ids in a single query and join in-process.
 
-A code review that lets an N+1 through is doing its job poorly. Add it to the review checklist (already in `skills/api-design/SKILL.md`).
+A code review that lets an N+1 through is doing its job poorly. Add it to the review checklist (already in the `api-design` skill).
 
 ### 9.2 Pagination always
 
-See `skills/api-design/SKILL.md` § 3. No unbounded list ever, even if today's dataset is 12 rows.
+See the `api-design` skill § 3. No unbounded list ever, even if today's dataset is 12 rows.
 
 ### 9.3 Stream large payloads
 

package/templates/warlock/skills/security-baseline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-baseline
-description: 'Project-level security floor for Warlock.js apps — input validation at every boundary via `@warlock.js/seal` schemas, authentication via `@warlock.js/auth` (JWT + refresh) with `userType` config, server-side authorization never trusting client-supplied `userId`/`organizationId`, secrets only via `env(...)` + typed config files (never `process.env.X` scattered), parameterized queries through Cascade ORM (never raw concatenation), rate limiting via `@fastify/rate-limit` configured in `config/http.ts`, PII / token redaction in logs (`log.configure({ redact })`), `bcryptjs` for password hashing, `@mongez/encryption` for symmetric encryption, dependency vulnerability scanning (`yarn audit`). Triggers: writing a route handler / controller that accepts external input; touching auth, login, signup, session, token, JWT, password, refresh-token; reading secrets / API keys / env vars; writing a Cascade query or repository filter; handling file uploads, webhook payloads, queue messages; setting rate limits; user asks "is this secure", "input validation", "SQL / NoSQL injection", "XSS", "CSRF", "rate limiting", "secrets management", "authentication vs authorization", "where does X env var go"; importing `@warlock.js/seal` or `@warlock.js/auth` or `bcryptjs`. Skip: pure UI / styling that handles no data; code-style questions (load `skills/code-standards/SKILL.md`); HTTP envelope shape (load `skills/api-design/SKILL.md`); cryptography internals / writing your own crypto — stop and use a vetted lib; advanced auth flows (OAuth, SAML) — load `@warlock.js/social-auth` skill.'
+description: "Input schemas, authentication, authorization, secrets, safe queries, rate limits, password handling and log redaction. Use when code accepts external input or handles identity or credentials. Use api-design instead for HTTP response contracts."
 ---
 
 # Security baseline
@@ -10,7 +10,7 @@ description: 'Project-level security floor for Warlock.js apps — input validat
 
 The non-negotiable security floor for any project on this template. Each rule maps to a real class of incident — most production breaches trace back to one of these eight being absent or sloppy.
 
-> **Sub-agent rule:** Before writing any code that handles external input, identity, or secrets, read this file. Code-style rules live in `skills/code-standards/SKILL.md` — this skill is about what the code must do, not how it must look.
+> **Sub-agent rule:** Before writing any code that handles external input, identity, or secrets, read this file. Code-style rules live in the `code-standards` skill — this skill is about what the code must do, not how it must look.
 
 ---
 
@@ -27,13 +27,13 @@ Anything that crosses the process boundary:
 - Webhook payloads
 - Queue messages
 - Env vars (validated once at boot — see § 3)
-- Database rows from a *different* service (treat them as external if you don't own the writer)
+- Database rows from a _different_ service (treat them as external if you don't own the writer)
 
 ### 1.2 Where validation runs
 
 At the boundary, exactly once. Never inside services.
 
-The Warlock pattern: schema lives in the module's `schema/` folder, the controller types itself with the schema and attaches it via `controller.validation.schema`. See `skills/api-design/SKILL.md` § 6 for the full controller shape.
+The Warlock pattern: schema lives in the module's `schema/` folder, the controller types itself with the schema and attaches it via `controller.validation.schema`. See the `api-design` skill § 6 for the full controller shape.
 
 ```typescript
 // ✅ schema/create-order.schema.ts
@@ -56,10 +56,10 @@ export type CreateOrderSchema = Infer<typeof createOrderSchema>;
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateOrderSchema, createOrderSchema } from "../schema/create-order.schema";
 
-export const createOrderController: GuardedRequestHandler<CreateOrderSchema> = async (
+export const createOrderController: GuardedRequestHandler<CreateOrderSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const order = await placeOrderService(request.validated()); // already typed + safe
   return response.success({ order });
 };
@@ -80,7 +80,7 @@ The framework returns `422 Unprocessable Entity` with structured field errors au
 
 - **Verify the signature first**, schema-validate second. A signature failure aborts before any other work.
 - Reject requests older than the provider's replay window (typically 5 minutes).
-- Idempotency-key the handler (see `skills/observability-and-resilience/SKILL.md` § 4) — providers retry.
+- Idempotency-key the handler (see the `observability-and-resilience` skill § 4) — providers retry.
 
 ---
 
@@ -92,18 +92,18 @@ AuthN proves who you are. AuthZ decides what you can do. Conflating them is how
 
 ```typescript
 // ❌ trusting the client
-const order = await ordersRepository.find({ id, userId: request.input("userId") });
+const order = await Order.findOne({ publicId: id, userId: request.input("userId") });
 
 // ✅ identity from the authenticated session
 const user = request.locals.user;
-const order = await ordersRepository.find({ id, userId: user.id });
+const order = await Order.findOne({ publicId: id, userId: user.id });
 ```
 
 Any field whose value would determine permission (`userId`, `organizationId`, `roleId`, `isAdmin`) is read from the authenticated session — never from the request body, query, or header.
 
 ### 2.2 Authentication via `@warlock.js/auth`
 
-The project's auth stack: JWT access tokens (1h) + refresh tokens (30d), configured in `config/auth.ts`. Password hashing via `bcryptjs`. The framework's `authService` (`@warlock.js/auth`) is the single entry point:
+The project's auth stack: JWT access tokens and optional refresh tokens, configured in `src/config/auth.ts`. The starter uses `NO_EXPIRATION` for access tokens and disables refresh tokens; choose finite lifetimes and explicitly enable refresh when the application needs sessions. Password hashing via `bcryptjs`. The framework's `authService` (`@warlock.js/auth`) is the single entry point:
 
 ```typescript
 // ✅ thin wrapper service — the framework does the work
@@ -124,13 +124,13 @@ Pattern: at the start of every mutating service, check ownership and role:
 ```typescript
 // ✅
 export async function updateOrderService(orderId: string, input, user) {
-  const order = await ordersRepository.find({ id: orderId });
+  const order = await Order.findOne({ publicId: orderId });
 
   if (!order) {
     throw new OrderNotFoundError(orderId);
   }
 
-  if (order.userId !== user.id && !user.isAdmin) {
+  if (order.get("userId") !== user.id && !user.isAdmin) {
     throw new ForbiddenError("not your order");
   }
 
@@ -168,7 +168,7 @@ const authConfigurations: AuthConfigurations = {
   jwt: {
     secret: env("JWT_SECRET"),
     expiresIn: "1h",
-    refresh: { /* ... */ },
+    refresh: {/* ... */},
   },
 };
 ```
@@ -184,10 +184,10 @@ The logger redaction layer is the safety net, but the first line of defence is n
 log.info("auth", "login", "User authenticated", { user, password, token });
 
 // ✅
-log.info("auth", "login", "User authenticated", { userId: user.id });
+log.info("auth", "login", "User authenticated", { userId: user.get("publicId") });
 ```
 
-Configure `log.configure({ redact: { paths: ["password", "token", "*.secret", "*.apiKey"] } })` at startup — see `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`.
+Configure `log.configure({ redact: { paths: ["password", "token", "*.secret", "*.apiKey"] } })` at startup — see the `@warlock.js/logger` skill's `redact-sensitive-log-fields` topic.
 
 ### 3.4 Token lifetimes
 
@@ -213,7 +213,7 @@ const orders = await ordersRepository.raw(`status = '${input.status}'`);
 
 If a request body is `{ status: { $ne: null } }`, a naive `find({ status: input.status })` becomes a `$ne: null` match — returns every row. The seal schema is what prevents this: declaring `status: v.string()` rejects an object value at the boundary.
 
-This applies to **query strings too**, not just bodies — a `?status[$ne]=` smuggled through the query is the same attack. That's why list endpoints validate the query with a schema and never pass raw `request.all()` to the repository (see `skills/api-design/SKILL.md` § 3.5).
+This applies to **query strings too**, not just bodies — a `?status[$ne]=` smuggled through the query is the same attack. That's why list endpoints validate the query with a schema and never pass raw `request.all()` to the repository (see the `api-design` skill § 3.5).
 
 This is a real reason § 1 is non-negotiable.
 
@@ -281,6 +281,7 @@ For `/auth/login` and `/auth/reset-password`, key the limiter on the **email or
 ### 6.4 Progressive lockout
 
 After N failed login attempts:
+
 - 3 failures → 1-minute delay
 - 5 failures → 5-minute delay + email notification
 - 10 failures → temporary account lock + manual review
@@ -291,13 +292,13 @@ Never silently succeed-and-fail (returning 200 with no body to hide whether the
 
 ## 7. Dependency hygiene
 
-### 7.1 `yarn audit` in CI
+### 7.1 `npm audit` in CI
 
-CI runs `yarn audit --level=high` on every PR. High and critical vulnerabilities block merge. Moderate goes on the backlog with a fix-by date.
+CI runs `npm audit --audit-level=high` on every PR. High and critical vulnerabilities block merge. Moderate goes on the backlog with a fix-by date.
 
 ### 7.2 Lockfile committed
 
-`yarn.lock` is checked in. Always. CI installs with `--frozen-lockfile`.
+`package-lock.json` is checked in. CI installs with `npm ci`.
 
 ### 7.3 No `latest` in `package.json`
 
@@ -311,7 +312,7 @@ Every dependency is future risk. Before adding a 5-line utility, ask whether it'
 
 ## 8. Logging and PII
 
-See `skills/code-standards/SKILL.md` § 8 for the call signature. This is the **what not to log** list:
+See the `code-standards` skill § 8 for the call signature. This is the **what not to log** list:
 
 ### 8.1 Never log
 
@@ -340,7 +341,7 @@ log.configure({
 });
 ```
 
-See `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md` for the additive per-channel layer.
+See the `@warlock.js/logger` skill's `redact-sensitive-log-fields` topic for the additive per-channel layer.
 
 ---
 
@@ -356,7 +357,7 @@ Before merging a change that touches input, identity, secrets, or persistence:
 - [ ] All DB queries go through Cascade — no raw string-built queries
 - [ ] Rate limit appropriate for the route family (default for general, aggressive for auth)
 - [ ] No `.env` or secrets file in the commit
-- [ ] `yarn audit --level=high` passes
+- [ ] `npm audit --audit-level=high` passes
 - [ ] Logger redaction config covers any new sensitive field introduced
 - [ ] File uploads cap size, sniff MIME, server-generate the stored filename
 - [ ] Webhooks verify signature before any other work

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

@@ -1,6 +1,6 @@
 ---
 name: testing-strategy
-description: 'Test pyramid posture for Warlock.js apps — Vitest co-located (`foo.ts` → `foo.spec.ts`); **when testing is enabled in the project (a `test`/`test:*` script in package.json OR a `vitest.config.*` / `vite.config.*` file), it is mandatory that every service ships a co-located `.service.spec.ts` and every HTTP controller / request handler ships a test — a new service or endpoint without a spec is incomplete**; unit tests dominate (~70%), integration tests via `@testcontainers/mongodb` + `@testcontainers/postgresql` (~25%), e2e for critical user journeys only (~5%); coverage is a smoke detector not a target (`yarn test:coverage` via `@vitest/coverage-v8`); flaky-test zero-tolerance (quarantine in 24h, fix or delete in 7); test isolation (no shared state, no order dependency); AAA structure with blank-line phases; mock at the boundary not deep inside; `MockSDK` from `@warlock.js/ai` for AI calls; real DB via testcontainers for integration; snapshot tests only for small deterministic output; contract tests for external integrations. Triggers: deciding whether to write a unit / integration / e2e test for a change; setting up a new `.spec.ts`; debugging a flaky test; reviewing the test plan in a PR; user asks "should I unit test this", "what is our coverage policy", "this test keeps failing intermittently", "what should I mock", "test pyramid", "integration test vs unit test", "snapshot tests", "how do I test a service that hits the DB", "how do I test AI code". Skip: Vitest assertion API mechanics — that''s the testing framework''s docs; language / runtime questions; load testing / performance benchmarking; framework-package internals — load the relevant `@warlock.js/*` skill.'
+description: "Vitest test scope, co-located service and endpoint specs when testing is enabled, isolation, boundary mocks, integration tests and flaky-test policy. Use when planning or reviewing test coverage. Use git-workflow instead for CI and merge gates."
 ---
 
 # Testing strategy
@@ -32,7 +32,7 @@ Write the spec in the **same change** that adds the service or controller. A rev
 
 ### 0.2 If testing is NOT enabled
 
-No `test` script and no vitest/vite config — e.g. a scaffold created without the `test` feature. **Do not** add tests or testing dependencies unprompted, and don't invent a `vitest.config`. If the project is outgrowing prototype stage, *suggest* enabling the `test` feature — but never scaffold a suite the project didn't ask for.
+No `test` script and no vitest/vite config — e.g. a scaffold created without the `test` feature. **Do not** add tests or testing dependencies unprompted, and don't invent a `vitest.config`. If the project is outgrowing prototype stage, _suggest_ enabling the `test` feature — but never scaffold a suite the project didn't ask for.
 
 ---
 
@@ -95,7 +95,7 @@ Not enforced numerically. Enforced culturally — when a reviewer sees ten new e
 ### 2.2 Don't test
 
 - **The framework** — `@warlock.js/*` has its own tests. Don't re-test that `response.success()` returns 200.
-- **Trivial getters / setters** — `cart.totalCents` returning `this.get<number>("total_cents", 0)` doesn't need a test
+- **Trivial getters / setters** — `cart.totalCents` returning `this.get<number>("totalCents", 0)` doesn't need a test
 - **One-line passthroughs** — `loginService(...)` just calling `authService.login(...)` doesn't need a unit test (an integration test of the wiring is better)
 - **Generated code** — migrations, resource scaffolds
 
@@ -149,7 +149,7 @@ const result = await summarizeContentService(input, { provider: ai });
 expect(result).toBe("mocked response");
 ```
 
-See `@warlock.js/ai/skills/run-ai-agent/SKILL.md` for the full mock surface.
+See the `@warlock.js/ai` skill's `run-ai-agent` topic for the full mock surface.
 
 ### 4.3 Database — real, via testcontainers
 
@@ -179,7 +179,7 @@ In the test environment `setupTest()` installs fakes for mail, queue, cache, sto
 ```typescript
 import { mailFake, queueFake } from "@warlock.js/core/tests";
 
-const order = { id: 42 }; // what the code under test placed
+const order = { id: "550e8400-e29b-41d4-a716-446655440000" }; // what the code under test placed
 
 mailFake.assertSent({ to: "ada@example.test" });
 queueFake.assertPushed("invoices.send", { orderId: order.id });
@@ -235,7 +235,7 @@ Low coverage = guaranteed gaps. High coverage = no guarantee of correctness. Tre
 
 Chasing the last 5% of coverage produces brittle tests over edge-case code that nobody cares about. Spend the time on tests that catch real regressions.
 
-### 6.4 The `yarn test:coverage` command
+### 6.4 The `npm run test:coverage` command
 
 Runs Vitest with `@vitest/coverage-v8` (already in dependencies). Add coverage as a CI gate per the floors above once the suite is large enough.
 
@@ -337,4 +337,4 @@ Before merging a change that should include tests (testing enabled — see § 0)
 - [ ] Test names describe behaviour, not implementation
 - [ ] No `.only`, no `.skip` without a tracking ticket
 - [ ] Snapshots reviewed line-by-line if updated
-- [ ] `yarn test --run` passes; `yarn test:coverage` doesn't drop the floor
+- [ ] `npm run test --run` passes; `npm run test:coverage` doesn't drop the floor

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

@@ -1,16 +1,12 @@
 ---
 name: web-code-standards
-description: >-
-  Strict separation-of-concerns standards for Warlock.js src/web pages and
-  components: loaders delegate data and business rules to app services;
-  components delegate all behavior to separate custom-hook files.
-  Use alongside code-standards for web work; skip for backend-only changes.
+description: "Warlock web pages and setup files, component and hook ownership, Mongez forms, accessible controls, locale behavior and UI kit choices. Use when building or reviewing src/web features. Use code-standards instead for shared TypeScript rules."
 ---
 
 # Web code standards
 
 **Applies to:** `src/web/**` in this project. Read
-[`code-standards`](../code-standards/SKILL.md) for the shared TypeScript rules,
+the `code-standards` skill for the shared TypeScript rules,
 and the relevant `@warlock.js/web` skill before using a framework feature.
 This skill adds the web-specific rules; it does not override security or
 module-boundary requirements. When reviewing existing code, identify debt
@@ -45,7 +41,7 @@ ancestor and child dictionaries cannot redefine the same key. Keep legacy
 Within a web feature, use `components/`, `hooks/`, and `utils/` for their
 named purpose; do not create `lib/` as a catch-all. These folders have no
 barrel `index.ts`: import the named component, hook, or helper from its own
-file. Keep types in `types/` when a feature has several contracts, or in one
+file. These exact imports keep client bundles lean and prevent server-only code from being pulled through a barrel. The `code-standards` skill allows sub-folder barrels only for `src/app/**` server modules. Keep types in `types/` when a feature has several contracts, or in one
 `<feature>.types.ts` file when they are small. Do not duplicate a contract in
 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
@@ -54,13 +50,17 @@ make the feature harder to read.
 ## 1. Keep the page contract, make the implementation thin
 
 Page logic lives in the matching `.setup.ts` file: `config`, `loader`,
-`register`, and `action`/`actions`. UI files contain the default
-component and named components such as `ErrorBoundary`. Pair `layout.tsx` with
+`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
 `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`;
-metadata always belongs in `config.metadata`.
+metadata always belongs in `config.metadata`. Do not add an empty setup file
+when a component has no configuration, loader, action, or registration work.
+The starter follows this boundary for root configuration, home route policy
+and translations, and not-found metadata.
 
 Use the config type that matches the module. A page can preserve loader data
 inference for metadata by satisfying `PageConfig<typeof loader>`:
@@ -82,15 +82,18 @@ export const config = {
 ```
 
 ```tsx title="src/web/posts.page.tsx"
-export default function PostsPage() {
-  return <main>Posts</main>;
+import type { PageProps } from "@warlock.js/web";
+import type { loader } from "./posts.setup";
+
+export default function PostsPage({ data }: PageProps<typeof loader>) {
+  return <main>{data.title}</main>;
 }
 ```
 
-When code navigates by a page name, `href(name, params, query)` validates the
-published route table at runtime. `href("posts.indxe")` is a string that
-TypeScript accepts, then the helper throws with the known route names. Generated
-route-name and parameter types are not available in 5.17.
+Use `href(name, params, query)` for named page navigation. Generated declarations
+in `.warlock/typings/web-routes.d.ts` check route names and required path
+parameters when included in the app's TypeScript project; runtime route-table
+validation still applies. Do not widen those contracts to strings or add casts.
 
 Layouts use one `config satisfies LayoutConfig` object for `prefix`,
 `middleware`, `metadata`, and a sitemap default. Roots use one
@@ -133,11 +136,22 @@ queries, aggregations, and domain transformations in the service. A service
 must have a meaningful domain name and own the operation, not exist as a
 generic pass-through for a repository method.
 
-Extract substantive view sections into cohesive components. A component
-that needs any behavior gets a separate feature-named custom-hook file; a
-component with no behavior stays presentational and needs no hook. Split by
-responsibility, not by a mechanical line-count limit. Framework exports
-for logic remain in the setup file even when their work is delegated elsewhere.
+Give every component one responsibility and one reason to change. Define one
+component per file, with a named default export. Extract substantive view
+sections into cohesive components. Put hooks in `hooks/` and pure UI helpers
+in `utils/`, one hook or helper per file, exported by name. A hook owns state,
+effects, handlers, navigation, and client mutations; a utility has no React or
+browser lifecycle dependency. A presentational component needs no hook.
+
+Keep a small piece of logic or a private helper inline only when it is tightly
+coupled to that one component and keeping it there leaves the file small and
+focused. A component file past roughly 150 lines, a second component, or multiple
+helpers is a split signal, not a mechanical line limit: split at ownership
+boundaries, never into arbitrary chunks to meet a count. The one-component rule
+still applies. Framework logic exports remain in setup even when delegated.
+Keep feature CSS beside the feature and import it from the owning presentation
+boundary; keep loading, error, empty, focus, reduced-motion, and locale behavior
+with that boundary.
 
 Preserve the framework's rendering boundary: `root.tsx` owns the document,
 `#vessel` and `<Scripts />`; the loader runs on the server, while the rendered
@@ -153,35 +167,6 @@ output; the page composes `PostArticle`, `PostComments`, and `RelatedPosts`;
 `use-post-comments.ts` owns subscription, state, and handlers for
 `PostComments`. Each piece has one reason to change.
 
-## Setup and component files
-
-Use a setup file when a feature registers framework behavior. The setup file
-owns its `register`, `config`, and `loader` exports; its matching component
-only renders the supplied data. Keep loader inference type-only so it does
-not pull server work into a browser component:
-
-The default starter follows this boundary: `root.setup.ts` owns strict-mode
-configuration, `home/index.setup.ts` owns route policy, its loader, and the
-universal translations `register()`, and `404.setup.ts` owns not-found
-metadata. Do not add an empty setup file when a component has no server
-configuration, loader, or registration work.
-
-```tsx
-import type { PageProps } from "@warlock.js/web";
-import type { loader } from "./posts.setup";
-
-export default function PostsPage({ data }: PageProps<typeof loader>) {
-  return <PostsList posts={data.posts} />;
-}
-```
-
-Each React component file has one named default component. Export hooks,
-utilities, and types by name. A component renders; its feature hook owns
-state, effects, handlers, navigation, and client mutations. A utility stays
-pure and has no React or browser lifecycle dependency. Keep feature CSS beside
-the feature and import it from the owning presentation boundary; keep loading,
-error, empty, focus, reduced-motion, and locale behavior with that boundary.
-
 ## Declaration spacing and local types
 
 Put one blank line after the final import. Keep a short related declaration run
@@ -218,17 +203,17 @@ state starts unset, write `useState<ErrorText>()`; do not add a redundant
   same validated, public data as the page. Keep private routes out of public
   discovery, and do not generate database-backed assets on every GET.
 
-## 3. Components render; custom hooks own all behavior
+## 3. Components render; custom hooks own behavior
 
-**No behavior in React component bodies, even when it is small.** A
-component may declare props, call its dedicated custom hook if needed,
-and render JSX from its props and the hook's returned values. Put `useState`,
+**Delegate behavior to the component's dedicated custom hook by default.** A
+component declares props, calls that hook if needed, and renders JSX from its
+props and the hook's returned values. Put `useState`,
 `useEffect`, subscriptions, timers, browser API calls, derived-value
 calculations, event handlers, mutations, and navigation decisions in a
 separate custom-hook file. Keep pure domain calculations in `src/app`
 services; a hook may call a small pure UI helper outside the component.
-Do not put a one-line callback or inline computation in JSX because it
-"doesn't warrant a hook". Pure presentational components need no hook.
+Use section 1's inline exception only for small, tightly coupled logic;
+reuse or file growth means it belongs in its own hook or utility file.
 JSX conditionals that only select which markup to show are presentation,
 not a license to implement business rules in render.
 
@@ -272,6 +257,117 @@ enforce the same policy independently. Use a full navigation when an auth or
 document boundary requires it, otherwise prefer the framework's navigation
 and refresh primitives so state and loader data stay in sync.
 
+### Use Mongez React Form for every form
+
+Always use `Form`, `useFormControl`, and `useSubmitButton` from
+`@mongez/react-form`; the web stack already uses this package, including the
+starter's contact form. Do not add a second form library or manage field
+validation and submission state in parallel React state. Keep those hooks in
+the control's and submit button's dedicated hook files, following section 1.
+
+Declare validation in a browser-safe `<Form schema={schema}>` (Seal implements
+Standard Schema), a control's `schema`, or `useFormControl({ rules: [...] })`.
+The `rules` array contains imported rule objects, never rule-name strings.
+For example, `{ name: "email", type: "email", required: true,
+rules: [requiredRule, emailRule] }` uses Mongez's rules: `requiredRule` needs
+`required: true`, and `emailRule` needs the control's `type: "email"`.
+Put `requiredRule` first. Schema issues map back to registered control names,
+so keep schema paths and control names aligned.
+
+Never use `required`, `pattern`, `min`, `max`, `minLength`, or `type="email"`
+as browser validation, or rely on the browser's constraint UI. These may be
+Mongez rule configuration props; do not spread raw control props onto DOM
+inputs. Mongez v4's `Form` renders `noValidate` by default; keep it enabled
+and preserve it if using a custom form host. A schema-backed email field can
+render `type="text"` with `inputMode="email"` and `autoComplete="email"`,
+leaving email validation entirely to the form.
+
+Render the control's `error` through `getErrorProps()` and connect the field
+with `getInputProps()` (or equivalent explicit wiring for a custom widget).
+This keeps field identity, focus, blur validation, and error announcement in
+the same form contract. For example, each block below is its own file:
+
+```ts title="src/web/contact/contact.schema.ts"
+import { v } from "@warlock.js/seal";
+
+export const contactSchema = v.object({ email: v.email() });
+```
+
+```ts title="src/web/contact/hooks/use-contact-email.ts"
+import { useFormControl } from "@mongez/react-form";
+
+export function useContactEmail() {
+  return useFormControl({ name: "email" });
+}
+```
+
+```tsx title="src/web/contact/components/contact-email.tsx"
+import { useContactEmail } from "../hooks/use-contact-email";
+
+export default function ContactEmail() {
+  const { id, error, getInputProps, getErrorProps } = useContactEmail();
+
+  return (
+    <div>
+      <label htmlFor={id}>Email</label>
+      <input {...getInputProps({ type: "text", inputMode: "email", autoComplete: "email" })} />
+      {error ? <span {...getErrorProps()}>{error}</span> : null}
+    </div>
+  );
+}
+```
+
+Render `ContactEmail` inside `<Form schema={contactSchema} onSubmit={submit}>`;
+the feature hook owns `submit`. The submit button's hook calls
+`useSubmitButton()` and exposes `disabled` and `isSubmitting` to its component.
+For API mutations, use `useSubmitForm` from `@warlock.js/web/form` in the
+feature hook. With generated route declarations and a handler's `responseSchema`,
+`useSubmitForm({ route })` infers the declared success body; `ApiResponse` from
+`@warlock.js/web` reads a declared status body. Do not replace this inference
+with casts. Server endpoints must still validate input independently.
+
+### Build custom controls with the project's UI kit
+
+Do not render native `<select>`, `<input type="checkbox">`,
+`<input type="radio">`, or `<input type="date">` UI. Build a searchable
+select/dropdown with a search input, a custom checkbox, custom radio
+controls, and a custom date picker. Each field uses `useFormControl` through
+its dedicated hook; a radio group registers one selected value for the group.
+Connect value/checked changes, blur, disabled state, focus refs, validation,
+and errors to that control. Configure a checkbox control with
+`type: "checkbox"` and wire `checked` / `setChecked`. Adapt other widget
+callbacks to `changeValue`; do not blindly spread DOM input props onto a kit
+component with a different callback contract. Keep search text and popup state separate from
+the selected form value. A kit's hidden input for submission is acceptable;
+it must not display native UI or become a second validation source.
+
+Check the existing styling stack and UI kit before building controls:
+
+- With Tailwind and shadcn/ui already installed, compose its components:
+  Command + Popover for a searchable select, Checkbox, RadioGroup, and
+  Calendar + Popover for dates. Keep Mongez as the form owner rather than
+  copying a kit example that introduces another form library.
+- With Tailwind but no shadcn/ui, or with no UI kit, ask the user which kit
+  to use **before installing anything**. Recommend shadcn/ui for Tailwind
+  projects because its composable accessible primitives fit the styling
+  stack. Explain the recommendation for other stacks and wait for the
+  user's choice; never silently add dependencies.
+- With another established kit and no Tailwind, use its corresponding
+  accessible primitives and the same Mongez adapters.
+
+Custom controls must preserve the accessibility native controls supplied.
+Follow the WAI-ARIA APG [combobox/listbox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/),
+[checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/),
+[radiogroup](https://www.w3.org/WAI/ARIA/apg/patterns/radio/), and
+[date picker dialog/grid](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
+patterns. Preserve labels, visible focus, disabled/selected/checked states,
+`aria-invalid`, and error descriptions linked to `getErrorProps()` output.
+Support keyboard search and arrow navigation, Enter selection, Space toggling,
+and Escape dismissal as appropriate. Manage popup entry and focus return;
+a modal date dialog traps focus and its calendar grid supports day/month
+keyboard navigation. Kit composition still needs correct labels, focus refs,
+and announced errors; styling alone does not make a control accessible.
+
 ## 5. Ship usable, localizable presentation
 
 - Use semantic landmarks, headings, buttons, links, and explicit form labels.
@@ -311,12 +407,13 @@ Before approving a web change, ask:
    effects without untangling unrelated responsibilities?
 2. Does every loader obtain data and business decisions from a named app
    service, with models/repositories kept out of the web layer?
-3. Does each behavioral component delegate all state, effects, derived
-   values, event handlers, and mutations to its own custom hook file?
+3. Does each component have one responsibility and its own file, with hooks
+   and helpers extracted except for the small, tightly coupled inline case?
 4. Is the service query bounded, the resource shape intentional, and the
    cache scope safe?
 5. Do refresh, navigation, errors, retries, and cleanup leave the UI correct?
-6. Are forms and interactions accessible and translated to the degree the
-   interface promises?
+6. Do forms use Mongez schema/rules and accessible custom controls, with
+   native validation disabled and the UI kit choice agreed before installation?
+   Are interactions translated to the degree the interface promises?
 7. Are the relevant quality rules enforced or covered by focused tests,
    rather than described only in comments?

package/templates/warlock/src/app/auth/models/otp/otp.model.ts

@@ -33,9 +33,15 @@ export class OTP extends Model<OTPSchema> {
    * Check if OTP is valid (not expired, not used, not max attempts)
    */
   public get isValid(): boolean {
-    if (this.get("usedAt")) return false;
-    if ((this.get("attempts") ?? 0) >= (this.get("maxAttempts") ?? 0)) return false;
-    if (new Date() > new Date(this.get("expiresAt"))) return false;
+    if (this.get("usedAt")) {
+      return false;
+    }
+    if ((this.get("attempts") ?? 0) >= (this.get("maxAttempts") ?? 0)) {
+      return false;
+    }
+    if (new Date() > new Date(this.get("expiresAt"))) {
+      return false;
+    }
     return true;
   }
 

package/templates/warlock/src/app/auth/services/otp.service.ts

@@ -19,12 +19,24 @@ const DEFAULT_OTP_EXPIRATION: Duration = { minutes: 15 };
 // Parse duration to milliseconds
 function parseDurationToMs(duration: Duration): number {
   let ms = 0;
-  if (duration.milliseconds) ms += duration.milliseconds;
-  if (duration.seconds) ms += duration.seconds * 1000;
-  if (duration.minutes) ms += duration.minutes * 60 * 1000;
-  if (duration.hours) ms += duration.hours * 60 * 60 * 1000;
-  if (duration.days) ms += duration.days * 24 * 60 * 60 * 1000;
-  if (duration.weeks) ms += duration.weeks * 7 * 24 * 60 * 60 * 1000;
+  if (duration.milliseconds) {
+    ms += duration.milliseconds;
+  }
+  if (duration.seconds) {
+    ms += duration.seconds * 1000;
+  }
+  if (duration.minutes) {
+    ms += duration.minutes * 60 * 1000;
+  }
+  if (duration.hours) {
+    ms += duration.hours * 60 * 60 * 1000;
+  }
+  if (duration.days) {
+    ms += duration.days * 24 * 60 * 60 * 1000;
+  }
+  if (duration.weeks) {
+    ms += duration.weeks * 7 * 24 * 60 * 60 * 1000;
+  }
   return ms;
 }