@webjsdev/mcp 0.1.10 → 0.1.11

package/resources/SKILL.md

@@ -9,7 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://docs.webjs.dev.
+This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
 
@@ -22,7 +22,7 @@ WebJs is an AI-first, web-components-first framework with **no build step**: sou
 - **`*.server.ts`** is the one server boundary. With `'use server'` its exports are RPC-callable from the client (the import is rewritten to a stub); without it the file is a server-only utility whose browser import throws at load. This, not a component annotation, is how a dependency (the DB driver, secrets, `node:*`) is kept off the client.
 - **`route.ts`** is a server-only HTTP handler (named `GET`/`POST` exports), the one routing file that is NOT isomorphic.
 
-**Progressive enhancement is the default architecture.** With JS off, content reads, `<a>` navigates, and `<form>` server actions submit. JS is opt-in per interactive behaviour. Never write a first paint that depends on hydration.
+**Progressive enhancement is the default architecture.** With JS off, content reads, `<a>` navigates, and a `<form action=${importedAction}>` submits to its server action. JS is opt-in per interactive behaviour. Never write a first paint that depends on hydration.
 
 ## When To Use This Skill
 
@@ -45,7 +45,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
 | Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
 | The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
-| TypeScript at runtime, erasable syntax, full-stack types                     | `references/typescript.md`                     |
+| TypeScript at runtime, erasable syntax, full-stack types, the derive-the-type rule (never `unknown` / `any`) | `references/typescript.md`                     |
 | Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
 | Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |
 | Node vs Bun, running the app, deploying, runtime-specific differences        | `references/runtime.md`                        |
@@ -54,7 +54,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 
 Common bundles:
 
-- **Form or CRUD feature** then routing-and-pages, data-and-actions, testing; add auth if user-specific
+- **Form or CRUD feature** then data-and-actions, routing-and-pages, testing; add auth if user-specific
 - **Interactive widget** then components, styling; add client-router-and-streaming only if it streams
 - **Protected area** then auth-and-sessions, routing-and-pages, testing
 - **Instant-feeling mutation** then data-and-actions, optimistic-ui
@@ -68,7 +68,8 @@ Common bundles:
 5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser.
 6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
 7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
-8. **Test the narrowest meaningful layer**, and render the app in a real browser for any UI change (static checks do not catch a collapsed layout).
+8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. See `references/typescript.md`.
+9. **Test the narrowest meaningful layer**, and render the app in a real browser for any UI change (static checks do not catch a collapsed layout).
 
 ## Project Layout
 
@@ -104,6 +105,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
 10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
 11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
+12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>` inside a bound form. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes, a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"`, `formmethod="get"` or an unparseable `formenctype` on ANY submitter in a bound form, and a non-action function all throw. A page has no `action` export, so a bare `<form method="post">` is a 405.
 
 ## Export Map
 
@@ -112,17 +114,20 @@ Find the right export fast. Load the linked reference for full examples.
 ### `@webjsdev/core` (browser + isomorphic)
 
 - `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `register(tag, C)` / `Class.register('tag')`.
-- `signal` / `computed` reactive state; `render(v, el)` client render.
+- `signal` / `computed` reactive state, `effect(fn)` client-only reaction (returns a disposer), `batch(fn)` coalesced writes; `render(v, el)` client render.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
 - `optimistic()` optimistic UI; `navigate(url)` / `revalidate(url?)` client-router control; `connectWS` / `richFetch`.
+- `asset(path)` content-hashes a `public/` url so a deploy cannot serve stale bytes (`href=${asset('/public/app.css')}`), served `immutable` for a year. Page / layout / metadata route only, inside the render function. See `references/built-ins.md`.
 - Types: `Metadata`, `PageProps<R>`, `LayoutProps<R>`, `RouteHandlerContext<R>`, `WebjsConfig`.
 - `@webjsdev/core/server`: `renderToString` / `renderToStream` (Node side).
-- `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`. `Task` lives at `@webjsdev/core/task`, context at `/context`.
+- `@webjsdev/core/directives`: `repeat`, `unsafeHTML` (trusted only), `live`, `keyed`, `guard`, `cache`, `until`, `watch(signal)`, `ref` / `createRef`, `asyncAppend` / `asyncReplace`, `templateContent`. `Task` / `TaskStatus` live at `@webjsdev/core/task`, context (`createContext` / `ContextProvider` / `ContextConsumer`) at `/context`. See `references/components.md` for the directive table + Task + context.
 
 ### `@webjsdev/server` (server side)
 
 - `createRequestHandler`, `cors()`, `route(action, opts?)` REST adapter, `sitemap()` / `sitemapIndex()`, `actionContext()`, `actionSignal()`, `requestId()`, `cache()` / `revalidateTag`.
+- Route-handler toolkit: `json(v)` rich responder, `readBody(req)`, `clientIp(req)`, no-arg `headers()` / `cookies()` / `cspNonce()` (client counterpart `richFetch` is in `@webjsdev/core`). See `references/routing-and-pages.md`.
+- Auth + sessions: `createAuth` (+ `Credentials` / `Google` / `GitHub`), `auth()` / `auth(req)`, `session()` + `cookieSession` / `storeSession`, `getSession(req)` (`.get` / `.set` / `.flash` / `.destroy`). File storage: `getFileStore` / `diskStore` / `signedUrl`. See `references/auth-and-sessions.md` + `references/built-ins.md`.
 - Data layer is Drizzle in `db/*.server.ts`. Auth, sessions, caching, rate limit, file storage are built in and pluggable (`references/built-ins.md`).
 
 ### File conventions
@@ -185,24 +190,32 @@ class Counter extends WebComponent({ count: prop(Number) }) {
 Counter.register('my-counter');
 ```
 
-### The no-JS write path (a page action)
+### The no-JS write path (a form-bound action)
 
 ```ts
-// app/contact/page.ts
-export const action = async ({ formData }) => {
+// modules/contact/actions/send-message.server.ts
+'use server';
+export async function sendMessage(formData: FormData) {
   const email = String(formData.get('email') || '');
   if (!email) return { success: false, fieldErrors: { email: 'required' } };
   return { success: true, redirect: '/thanks' };
-};
-export default function Contact({ actionData }) { /* render form + actionData errors */ }
+}
+
+// app/contact/page.ts
+import { sendMessage } from '#modules/contact/actions/send-message.server.ts';
+export default function Contact({ actionData }) {
+  return html`<form action=${sendMessage}><input name="email"></form>`;
+}
 ```
 
-Success is a 303 (PRG); failure re-renders the page at 422 with the result on `actionData`. With JS the client router applies the response in place.
+Binding the action is the whole wiring: the renderer omits `action` (so the form posts to the page's own url), supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` identity field. A form-bound action always receives the `FormData`.
+
+Success is a 303 (PRG); failure re-renders the page at 422 with the result on `actionData`. With JS the client router applies the response in place. A submission that binds nothing is a 405, and the submission is Origin-verified like an RPC call.
 
 ## Security And Session Defaults
 
 - Never ship demo secrets. Require session and provider secrets from the environment and fail fast if missing.
-- Action RPC CSRF is an Origin / `Sec-Fetch-Site` check, not a token cookie. A safe GET action is CSRF-exempt. A `route.ts` REST endpoint is NOT covered: authenticate every mutating endpoint, validate, rate-limit.
+- CSRF is an Origin / `Sec-Fetch-Site` check on both the action RPC and the form-submit path, not a token cookie. A safe GET action is CSRF-exempt. A `route.ts` REST endpoint is NOT covered: authenticate every mutating endpoint, validate, rate-limit.
 - Prod action errors are sanitized to a generic message plus a digest. Put a user-facing message on the `ActionResult` `{ success: false, error }` envelope, never on a raw throw.
 - Use `forbidden()` for an authenticated user lacking permission, `unauthorized()` for an unauthenticated request. Inside a `'use server'` RPC action, return an `ActionResult` for an auth failure instead of throwing.
 - For CORS use `cors()` from `@webjsdev/server`; `credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.
@@ -210,8 +223,8 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 ## Testing Defaults
 
 - Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
-- Add a browser test (`webjs test --browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
-- Render the app and LOOK for any UI change: `webjs check` and `webjs typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
+- Add a browser test (`npm run test:browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
+- Render the app and LOOK for any UI change: `npm run check` and `npm run typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
 - WebJs runs on Node 24+ AND Bun. Prove a runtime-sensitive change (serializer, listener, streams, `node:crypto`, the TS stripper) on both.
 
 ## Common Mistakes To Avoid
@@ -221,6 +234,10 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - Using a `static properties` block or a class-field initializer for reactive props instead of the `WebComponent({ ... })` factory.
 - Quoting an event / property / boolean hole (`@click="${fn}"`).
 - Writing `fetch()` to call your own server instead of importing the action.
+- Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
+- Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
+- Writing `formmethod="get"` or `formenctype="text/plain"` on any button inside a bound form. Neither can carry the action's body, so both are refused even when the button binds nothing.
+- Binding an action whose file declares `export const method = 'GET'`. That is a 405 at runtime and a `webjs check` error.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.

package/resources/references/auth-and-sessions.md

@@ -2,10 +2,10 @@
 
 ## What This Covers
 
-- Sessions: cookie by default, Redis-backed when configured, the `SESSION_SECRET` requirement
-- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action
-- Login and logout flows (`signIn` / `signOut` / `handlers`)
-- Protecting a route: gate at the top of a page or action, redirect when unauthenticated
+- Sessions: the `session()` middleware + storage factories (`cookieSession` / `storeSession`), the `getSession(req)` method API (`.get` / `.set` / `.flash` / `.destroy`), the `SESSION_SECRET` requirement
+- Authentication: `createAuth` (NextAuth-style), Credentials plus OAuth providers, `auth()` in a page or action, scrypt password hashing
+- Login and logout flows: mounting `handlers` at `app/api/auth/[...path]`, the no-JS credentials form (`/api/auth/signin/credentials` + `redirectTo` + `?error`), `signIn` / `signOut`
+- Protecting a route: a page-top `auth()` gate OR a per-segment `middleware.ts` calling `auth(req)`
 - `forbidden()` (403) vs `unauthorized()` (401) and their nearest-wins boundary files
 - Returning an `ActionResult` for an auth failure inside a `'use server'` action (do NOT throw there)
 - The Origin / `Sec-Fetch-Site` CSRF model (not a token cookie)
@@ -21,23 +21,30 @@ scaling, the full caching surface).
 
 ## Sessions
 
-Enable sessions in middleware, read and write them in a page or action.
+Enable sessions with `session()` MIDDLEWARE, then read and write them with `getSession(req)` in any route or middleware the session wraps.
 
 ```ts
-// middleware.ts: enable on all routes
-import { session } from '@webjsdev/server';
-export default session();   // auto: REDIS_URL present -> server-side, else -> cookie
+// middleware.ts: enable on all routes. Storage is pluggable.
+import { session, cookieSession, storeSession } from '@webjsdev/server';
+export default session({ secret: process.env.SESSION_SECRET, storage: cookieSession() });
+// cookieSession()  -> whole session in a signed cookie (stateless, the default)
+// storeSession()   -> session in the active store (memoryStore in dev, Redis in prod), id in the cookie
+```
 
-// in a page or action
+`getSession(req)` returns a small key/value `Session` with a METHOD API, not property assignment. Mutating it makes the middleware re-sign and set the cookie on the way out:
+
+```ts
 import { getSession } from '@webjsdev/server';
-const s = getSession(req);
-s.userId = user.id;         // auto-saved after the response
+export async function GET(req: Request) {
+  const s = getSession(req);
+  s.set('userId', user.id);            // write
+  const id = s.get('userId');          // read
+  s.flash('notice', 'Saved');          // one-read-only value (cleared after the next read)
+  s.destroy();                         // clear the whole session (logout)
+}
 ```
 
-Cookie sessions (the default) are signed and encrypted with no server
-state. Store sessions (with Redis) keep the session id in the cookie and
-the data in Redis. Both require `SESSION_SECRET`, read from the
-environment (never a literal in source) so boot fails if it is missing.
+Cookie sessions (the default) are signed with no server state; store sessions keep only the id in the cookie and the data in the store. `cookieSession` / `storeSession` are aliases for `cookieSessionStorage` / `storeSessionStorage`. Both strategies require `SESSION_SECRET`, read from the environment (never a literal in source) so boot fails if it is missing.
 
 ## Authentication (`createAuth`)
 
@@ -46,16 +53,17 @@ Configure providers once in a `.server.ts` file. `createAuth` returns
 `handlers` (the OAuth redirect endpoints).
 
 ```ts
-// lib/auth.server.ts
+// modules/auth/auth.server.ts
 import { createAuth, Credentials, Google, GitHub } from '@webjsdev/server';
 import { db } from '#db/connection.server.ts';
+import { compare } from './password.server.ts';
 
 export const { auth, signIn, signOut, handlers } = createAuth({
   providers: [
     Credentials({
       async authorize(credentials) {
         const user = await db.query.users.findFirst({ where: { email: credentials.email } });
-        if (!user || !verifyPassword(credentials.password, user.passwordHash)) return null;
+        if (!user || !(await compare(credentials.password, user.passwordHash))) return null;
         return { id: user.id, name: user.name, email: user.email, role: user.role };
       },
     }),
@@ -63,9 +71,50 @@ export const { auth, signIn, signOut, handlers } = createAuth({
     GitHub(),   // reads AUTH_GITHUB_ID, AUTH_GITHUB_SECRET
   ],
   secret: process.env.AUTH_SECRET,   // required, 32+ random chars, from the env
+  pages: { error: '/login' },        // a failed sign-in 302s here with ?error=<code>
 });
 ```
 
+**Password hashing is the app's job** (WebJs ships no `verifyPassword`). Use `scrypt` from `node:crypto` (built into Node AND Bun, no dependency) in a server-only utility, and call it from `authorize`:
+
+```ts
+// modules/auth/password.server.ts (a server-only utility, never reaches the browser)
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+const scryptAsync = promisify(scrypt);
+export async function hash(pw: string) {
+  const salt = randomBytes(16).toString('hex');
+  return salt + ':' + ((await scryptAsync(pw, salt, 64)) as Buffer).toString('hex');
+}
+export async function compare(pw: string, stored: string) {
+  const [salt, key] = stored.split(':');
+  return timingSafeEqual((await scryptAsync(pw, salt, 64)) as Buffer, Buffer.from(key, 'hex'));
+}
+```
+
+**Mount `handlers` at an `app/api/auth/[...path]/route.ts` catch-all** (at the app root, NOT under a feature folder): `createAuth` hardcodes `/api/auth/signin/*` and `/api/auth/callback/*` for its form posts and OAuth callback URIs.
+
+```ts
+// app/api/auth/[...path]/route.ts
+import { handlers } from '#modules/auth/auth.server.ts';
+export const GET = handlers.GET;
+export const POST = handlers.POST;
+```
+
+**The no-JS sign-in / sign-out flow is plain forms** (progressive-enhancement-safe). Sign in by POSTing to `/api/auth/signin/credentials` with a hidden `redirectTo`, and read `?error` (mapped from `pages.error`) for feedback; sign out by POSTing to `/api/auth/signout`:
+
+```html
+<form method="POST" action="/api/auth/signin/credentials">
+  <input type="hidden" name="redirectTo" value="/dashboard">
+  <input name="email" type="email" required><input name="password" type="password" required>
+  <button>Sign in</button>
+</form>
+<!-- log out -->
+<form method="POST" action="/api/auth/signout"><button>Log out</button></form>
+```
+
+For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
+
 Sessions are JWT by default (stateless, scales horizontally). OAuth
 providers handle the full redirect flow. Read the session anywhere on the
 server with `auth()`.
@@ -106,7 +155,7 @@ is produced, so a logged-out visitor never receives protected markup.
 ```ts
 // app/dashboard/page.ts
 import { html, redirect } from '@webjsdev/core';
-import { auth } from '#lib/auth.server.ts';
+import { auth } from '#modules/auth/auth.server.ts';
 
 export default async function Dashboard() {
   const session = await auth();
@@ -119,6 +168,20 @@ Reading the session through `auth()` also auto-excludes the page from the
 server HTML response cache, so a per-user page is never cached and served
 to another visitor (see `built-ins.md`).
 
+To gate a WHOLE subtree in one place, use a per-segment `middleware.ts` that reads `auth(req)` (the explicit-request form) and returns a `302` BEFORE the page renders. It runs for every request under its segment and needs only a cookie read (no DB query), so the gate is real the moment the app boots:
+
+```ts
+// app/dashboard/middleware.ts  (protects /dashboard/*)
+import { auth } from '#modules/auth/auth.server.ts';
+export default async function requireAuth(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (!session?.user) return new Response(null, { status: 302, headers: { location: '/login' } });
+  return next();
+}
+```
+
+`auth(req)` takes the in-flight request explicitly (for a middleware / route); the ambient `auth()` (no argument) reads from context inside a page or action.
+
 ## `forbidden()` (403) vs `unauthorized()` (401)
 
 Two control-flow throws from `@webjsdev/core`, mirroring the `notFound()`
@@ -135,7 +198,7 @@ default page.
 ```ts
 // app/admin/page.ts
 import { html, forbidden, unauthorized } from '@webjsdev/core';
-import { auth } from '#lib/auth.server.ts';
+import { auth } from '#modules/auth/auth.server.ts';
 
 export default async function Admin() {
   const session = await auth();
@@ -145,7 +208,7 @@ export default async function Admin() {
 }
 ```
 
-Both work from a page or layout render AND from a page `action` (the no-JS
+Both work from a page or layout render AND from a form-bound action (the no-JS
 write path). The boundary files (`app/forbidden.ts`, `app/unauthorized.ts`,
 or nested variants) live alongside the routes they cover and each
 default-export a function returning the boundary markup.
@@ -165,8 +228,10 @@ an `ActionResult` failure envelope with a status the client can act on.
 ```ts
 // modules/posts/actions/delete-post.server.ts
 'use server';
-import { auth } from '#lib/auth.server.ts';
+import { eq } from 'drizzle-orm';
+import { auth } from '#modules/auth/auth.server.ts';
 import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
 
 export async function deletePost(input: { id: string }) {
   const session = await auth();

package/resources/references/built-ins.md

@@ -4,11 +4,11 @@ Env vars, caching, rate limiting, broadcast, file storage, and the `package.json
 
 ## What This Covers
 
-- **Environment variables** and the `WEBJS_PUBLIC_` browser-exposed prefix.
+- **Environment variables**, the `WEBJS_PUBLIC_` browser-exposed prefix, and `env.ts` boot validation.
 - **Caching primitives.** `cache()` with tag invalidation, HTTP `Cache-Control`, the server HTML response cache (`export const revalidate`), content-hash asset URLs, conditional GET (ETag).
 - **Rate limiting** (`rateLimit()` middleware) and **broadcast** (`broadcast()` over WebSockets).
 - **File storage.** `FileStore` / `diskStore`, safe keys, signed URLs.
-- **The `"webjs"` config block.** Security headers, CSP, redirects, trailing-slash, basePath, allowed origins, client-router opt-out, ingress caps, dev/start task orchestration.
+- **The `"webjs"` config block.** Security headers, CSP, redirects, trailing-slash, basePath, allowed origins, client-router opt-out, ingress caps, dev/start task orchestration, the doctor severity gate.
 - **Observability.** Access log, `requestId()`, the `onError` hook, `instrumentation.ts`, the build-info endpoint.
 
 Read this when wiring caching or rate limiting, storing uploads, hardening headers, or configuring redirects and observability. **Auth and sessions are a separate reference (`auth-and-sessions.md`).** Server actions, `revalidateTag` from a mutation, and the `ActionResult` envelope live in `data-and-actions.md`.
@@ -25,6 +25,18 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 
+**Validate required vars at boot with an app-root `env.ts`** (optional). It default-exports either a SCHEMA object (each var mapped to a type `string` / `number` / `boolean` / `url` / `enum`, or an options object with `optional` / `default` / `minLength` / `pattern` / `values`) OR a validator function `(env) => void` that throws. It runs at boot after `.env` loads, coerces values and writes defaults back to `process.env`, and fails fast naming EVERY bad var:
+
+```ts
+// env.ts
+export default {
+  DATABASE_URL: 'url',
+  SESSION_SECRET: { type: 'string', minLength: 16 },
+  PORT: { type: 'number', default: 8080 },
+  LOG_LEVEL: { type: 'enum', values: ['debug', 'info', 'warn'], default: 'info' },
+};
+```
+
 ## Caching
 
 ### `cache()` for query and computation results
@@ -59,18 +71,33 @@ export const metadata = { cacheControl: 'public, max-age=60' };
 
 ### Server HTML response cache (`export const revalidate`)
 
-For a page that renders the **same HTML for every visitor**, opt into caching the SSR output (WebJs's no-build equivalent of ISR). Keyed by full URL only.
+For a page that renders the **same HTML for every visitor**, opt into caching the SSR output (WebJs's no-build equivalent of ISR). Keyed by the request origin plus the full URL.
 
 ```ts
 // app/blog/page.ts
 export const revalidate = 60;   // cache this page's HTML for 60s
 ```
 
-**Safety.** This asserts the page is identical for everyone for N seconds. Never set it on a page that reads `cookies()`, a session, or per-user data. The framework auto-marks a request dynamic and refuses to cache when the render reads per-user state through a framework helper (`cookies()`, `headers()`, `getSession()`, `auth()`), so an `auth()`-gated page fails safe. It also never caches a non-200, a streamed Suspense body, a `Set-Cookie` response, or a page under CSP. Evict on a write with `revalidatePath('/blog')`; `revalidateAll()` clears everything (single-instance / dev). This differs from the client-side `revalidate()` in `@webjsdev/core`, which evicts the browser snapshot cache.
+**Safety.** This asserts the page is identical for everyone for N seconds. Never set it on a page that reads `cookies()`, a session, or per-user data. The framework auto-marks a request dynamic and refuses to cache when the render reads per-user state through a framework helper (`cookies()`, `headers()`, `getSession()`, `auth()`), so an `auth()`-gated page fails safe. It also never caches a non-200, a streamed Suspense body, a `Set-Cookie` response, or a page under CSP. Evict on a write with `revalidatePath('/blog')`; `revalidateAll()` clears everything (single-instance / dev). This differs from the client-side `revalidate()` in `@webjsdev/core`, which evicts the browser snapshot cache. Keys carry the request ORIGIN as well as the path (#1097), because `ctx.url` comes from forwarded headers a proxy passes through rather than strips, so a hostile `X-Forwarded-Host` would otherwise bake an attacker-chosen origin into a body every later visitor gets served. A single-host deploy is unaffected (one origin, one entry per URL). It does mean a bare path does not name one entry, so `revalidatePath` resolves the origin from the calling request, which is exact for a server action; pass an absolute url from a background job that serves no requests of its own, where a bare path warns and evicts nothing. Under `webjs.basePath` the absolute url is the public one and its mount prefix is stripped, so it evicts the entry the write stored.
 
 ### Content-hash asset URLs and conditional GET
 
-Both are automatic, prod-focused, and need no config. In production every served module and `public/` asset gets a per-file `?v=<hash>` and `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Private (`no-store` / `private`) and streamed responses are excluded from the ETag path (no cross-session 304). Dev is byte-faithful (no hashing).
+Both are automatic, prod-focused, and need no config. In production every served MODULE gets a per-file `?v=<hash>`, and a `?v=`-carrying request is answered `Cache-Control: public, max-age=31536000, immutable`, so a returning client fetches a changed file only when its bytes change.
+
+A `public/` asset you reference yourself is opt-in, via `asset()` (#1194):
+
+```ts
+import { html, asset } from '@webjsdev/core';
+html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+```
+
+That emits `/public/app.css?v=<hash>` in production and gets the immutable year; the same url un-marked gets a ~1h cap and can serve stale bytes from a CDN after a deploy until something purges it. `asset()` resolves on the server; the browser has no resolver and returns the path unchanged. Call it from a PAGE, LAYOUT, or metadata route, which render only on the server. Inside a component that ships to the browser it silently costs you the caching: hydration is a full client re-render, so the bare path overwrites the hashed one and the asset downloads twice. The url stays valid either way, so this is a convention rather than a `webjs check` rule (`webjs doctor` does flag the plain form, see below). Under `webjs.basePath`, include the prefix yourself (`asset('/app/public/x.css')`): the framework base-path-prefixes only the urls it emits, so an author-written url is already yours to prefix. Two more constraints: call it INSIDE the render function, because a module-scope call is a side effect the elision analyser reads as client work and it ships the whole module; and mark only files that change with a DEPLOY, because the hash is memoized for the process lifetime, so a `public/` file rewritten in place at runtime would keep its old url while being served `immutable` for a year. Off in dev, so dev output is byte-identical. Only `public/` paths resolve; anything else (and a path that fails to resolve) is returned untouched.
+
+Forgetting it is the one real cost of opt-in, so `webjs doctor` catches it: a page, layout, or error boundary writing a plain `<link rel="stylesheet" href="/public/app.css">` gets a WARN naming the `file:line` and the fix (#1095). It reads your source and rewrites nothing, and it stays quiet about the non-marks that are deliberate: a cross-origin sheet, a `rel="icon"`, a `rel="preload"`, and any `href=${expr}` hole. Same posture as Rails (a `stylesheet_link_tag` helper over a digest manifest) and Remix (a hashed url from the build graph, surfaced through `links()`): take the fingerprint at the point the url is PRODUCED, never by rewriting a rendered document. A warning is easy to miss, so make it fatal in the app that cares: gate `UNMARKED_ASSET_LINKS` to `error` (see the doctor severity gate below) and one `npm run doctor` step in CI stops the un-versioned url reaching a deploy. The scaffold ships exactly that.
+
+It is opt-in rather than automatic because only the author knows which urls are the REQUEST. Do NOT mark a `rel="preload"` hint whose asset is actually fetched by CSS `url()`: the preload cache is keyed on the full url, so a versioned hint can never satisfy the unversioned request the stylesheet makes, and the file is fetched twice. Mark the thing that fetches, not the hint. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Unstorable (`no-store`) and streamed responses are excluded from the ETag path. A `private` response IS validated: `private` forbids SHARED storage, not validation, and the ETag hashes that response's own body, so two users with different bodies get different ETags and neither can match the other's, while two users with identical bodies are asking about identical bytes, where a 304 discloses nothing (#1140). That is what keeps the client router's partial responses cheap on a page that opted into caching; a default `no-store` page has nothing to validate either way. Dev is byte-faithful (no hashing).
+
+**A page's ETag is only useful if the page renders the same bytes twice.** The ETag is a hash of the response body, so any per-render-varying value anywhere in the document defeats it: a `Date.now()`, a `Math.random()`, an id from a module-scope counter (which never resets in a long-lived server), or a CSP nonce. The failure is silent and total. The page renders correctly, every content assertion still passes, the header is still present, and the only symptom is that no `If-None-Match` ever matches, so every revalidation ships the whole document instead of an empty 304. A page under CSP is excluded from the server HTML cache for exactly this reason (the nonce must differ per response). If a page opts into a public `Cache-Control`, guard it with a test that renders the page twice, through its layout, and asserts the two outputs are byte-identical.
 
 ## Rate limiting
 
@@ -82,7 +109,7 @@ import { rateLimit } from '@webjsdev/server';
 export default rateLimit({ window: '1m', max: 60 });
 ```
 
-Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the client IP), `message`, `store`, `trustProxy`. Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the client IP), `message`, `store`, `trustProxy` (honour the forwarded-IP headers; inert while `WEBJS_NO_TRUST_PROXY=1` is set, which outranks it and keeps the limiter on the framework-stamped peer). Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
 
 ## Broadcast
 
@@ -96,7 +123,7 @@ export function WS(ws, req) {
 }
 ```
 
-`broadcast(path, data, opts?)` fans out to all clients on `path`; `opts.except` skips one socket (typically the sender). `clientCount(path)` returns the live count. Single-instance by default; wire Redis pub/sub yourself for multi-instance.
+`broadcast(path, data, opts?)` fans out to all clients on `path`; `opts.except` skips one socket (typically the sender). Single-instance by default; wire Redis pub/sub yourself for multi-instance.
 
 ## File storage
 
@@ -112,13 +139,13 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 **Never trust a user filename as a key.** `generateKey(file.name)` returns an opaque `<uuid>.<ext>` with a sanitized extension; a traversal attempt yields a bare safe key. Keys are containment-checked before any filesystem op.
 
-**Signed URLs** gate serving without a session lookup. `signedUrl(key, { secret, expiresIn })` mints an expiring HMAC signature; `verifySignedUrl(searchParams, secret)` returns `{ valid }`. An `expiresIn` of `0` or negative fails closed.
+**Signed URLs** gate serving without a session lookup. `signedUrl(key, { secret, expiresIn })` mints an expiring HMAC signature; `verifySignedUrl(searchParams, secret)` returns `{ valid }`. An `expiresIn` of `0` or negative fails closed. Pass `base` to point the signed link at your own serve route instead of the default upload URL: `signedUrl(key, { secret, base: '/files/' + key, expiresIn: 3600 })`.
 
 **Serving-XSS warning.** The recorded content-type is attacker-controlled (the browser sent it at upload). A serving route MUST send `X-Content-Type-Options: nosniff` and SHOULD send `Content-Disposition: attachment` for user uploads. Only serve inline after validating bytes against a strict inert allowlist, never `text/html` / `image/svg+xml`. Add the uploads directory to `.gitignore`.
 
 ## The `"webjs"` config block (package.json)
 
-All keys are optional; a malformed entry is dropped at boot with a warning, never crashing the pipeline.
+All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot with a warning, never crashing the pipeline. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
 
 ### Security headers
 
@@ -136,6 +163,8 @@ On by default (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`,
 
 Off by default. `{ "webjs": { "csp": true } }` enables a strict-dynamic + per-request nonce posture. An object form merges `directives` and supports `reportOnly`. Read the nonce with `cspNonce()` from `@webjsdev/core` to stamp your own inline `<script>`.
 
+Enforcement is the HTTP `Content-Security-Policy` HEADER, never a `<meta http-equiv>` tag, so `frame-ancestors` / `report-uri` work. The emitted `<meta name="csp-nonce">` is only the client-side nonce CARRIER. Across a client-router soft navigation the ORIGINAL page-load nonce stays authoritative (the browser enforces the original document's CSP header, not the fetched response's fresh one), so the router preserves that meta and re-stamps every dynamically-inserted script / preload with the original nonce via `getCspNonce()`. The server still mints a fresh nonce per request, and CSP pages are excluded from the HTML cache so a nonce is never served stale. No client config is needed.
+
 ### Redirects, trailing-slash, basePath, allowed origins
 
 ```jsonc
@@ -181,6 +210,23 @@ An over-limit body responds `413` without buffering the whole payload.
 
 `before` runs to completion first (a non-zero exit aborts the boot). `parallel` (dev only) runs long-lived watchers alongside the server and tears them down on exit. `watch` (dev only) adds extra live-reload directories outside the app tree.
 
+### Doctor severity gate
+
+`webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` depends on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
+
+```jsonc
+{ "webjs": {
+  "doctor": { "gate": {
+    "UNMARKED_ASSET_LINKS": "error",   // fail the exit on this one
+    "ELISION_CARRIERS": "off"          // silence it entirely, even under --strict
+  } }
+} }
+```
+
+Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports without failing, `off` silences the check, meaning its finding is not printed and it cannot fail the exit (it still appears on the checklist as `[off]` and in the summary's silenced count, so a silenced check is never invisible, and `--json` still carries the whole result). A code with no entry keeps its default (`error` for a hard toolchain failure, `warn` otherwise), so an app that declares nothing behaves exactly as before. Read the codes off `webjs doctor --json`, where every result carries its `code` and its effective `severity`.
+
+Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
+
 ## Observability
 
 Wired at the single response funnel, covering pages, routes, actions, and assets uniformly.