@webjsdev/mcp 0.1.1 → 0.1.3

package/README.md

@@ -25,9 +25,11 @@ subcommand) delegates to this same server, so both routes run identical code.
 ## What it exposes
 
 - **Introspection tools** (read-only, scoped to an `appDir`): `list_routes`,
-  `list_actions` (with the `/__webjs/action/<hash>/<fn>` RPC endpoints),
-  `list_components`, `check` (the structured `webjs check` violations). Each
-  projects an existing `@webjsdev/server` data function and mutates nothing.
+  `list_actions` (RPC endpoints plus the full data contract: HTTP verb, cache
+  config, and boolean flags for tags/invalidates/validate/middleware; reserved
+  config exports are excluded from the callable-action list), `list_components`,
+  `check` (the structured `webjs check` violations). Each projects an existing
+  `@webjsdev/server` data function and mutates nothing.
 - **Knowledge layer**: an `init` mental-model primer, a `docs` retrieval tool,
   MCP `resources` (the `agent-docs/*` corpus + `AGENTS.md` as `webjs-docs://*`),
   and `prompts` (the recipes as guided workflows).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "The webjs Model Context Protocol server: live app introspection (routes / actions / components / check) plus the framework knowledge layer (docs, recipes, source) for AI coding agents",
   "bin": {

package/resources/AGENTS.md

@@ -14,10 +14,9 @@ reference there.
 | `agent-docs/components.md` | WebComponent deep-dive (controllers, hooks, light/shadow DOM, slots) |
 | `agent-docs/styling.md` | Tailwind helpers + vanilla-CSS opt-out conventions |
 | `agent-docs/built-ins.md` | Auth, sessions, env vars, caching (cache(), HTTP cache, asset-hash, conditional GET), rate-limit, broadcast, file storage |
-| `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, ingress caps) + observability |
+| `agent-docs/configuration.md` | The `package.json` `"webjs"` block (security headers, CSP, redirects, trailing-slash, basePath, ingress caps, dev/start task orchestration) + observability |
 | `agent-docs/advanced.md` | Suspense streaming, performance, bundling, client router (prefetch, frames, view transitions, stream actions), WebSockets |
 | `agent-docs/typescript.md` | TS at runtime + full-stack type safety |
-| `agent-docs/deployment.md` | Production, runtime targets, embedded use |
 | `agent-docs/service-worker.md` | The opt-in progressive-enhancement service worker (`public/sw.js`) |
 | `agent-docs/testing.md` | Unit, browser, convention validation, the `handle()` test harness (`@webjsdev/server/testing`) |
 | `agent-docs/framework-dev.md` | Monorepo dev (only when editing webjs itself): commands, repo-health git config, changelog flow, dev error overlay |
@@ -40,7 +39,7 @@ Claude Code enforces step 1 via `.claude/hooks/guard-branch-context.sh`. Other a
 
 ### Skills are routed deterministically, never skipped
 
-A Skill is model-invoked, so it fires only when the model judges a match. The `.claude/hooks/route-skills.sh` `UserPromptSubmit` hook makes routing deterministic: it keyword-matches each prompt against every skill's documented triggers and injects a directive to invoke the matched skill before other work. Check the available skills and invoke a matching one before starting. Tests in `test/hooks/route-skills.test.mjs`.
+A Skill is model-invoked, so it fires only when the model judges a match. The `.claude/hooks/route-skills.sh` `UserPromptSubmit` hook makes routing deterministic: it keyword-matches each prompt against every skill's documented triggers and injects a directive to invoke the matched skill before other work. Check the available skills and invoke a matching one before starting. The skills themselves are committed under `.claude/skills/` (alongside the hooks), so a fresh clone has both the router and the skills it routes to (no machine-local dependency). Tests in `test/hooks/route-skills.test.mjs`, which also asserts every skill the hook references is committed in-repo.
 
 ### Autonomous mode (sandbox / bypass permissions)
 
@@ -78,7 +77,7 @@ See `agent-docs/framework-dev.md` for monorepo commands, workspace layout, per-f
 
 An **AI-first, web-components-first** framework inspired by NextJs, Lit, and Rails. The component runtime API matches lit (reactive `static properties`, the lit lifecycle hooks, ReactiveControllers, the `lit-html` directive set, `html` / `css` templates) so lit training data transfers directly, but webjs ships its own no-build implementation under `packages/core/src/`. Decorators are the one lit exception (invariant 10); use `declare` + `static properties`.
 
-- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped via Node 24+'s `module.stripTypeScriptTypes` (invariant 10 + `agent-docs/typescript.md`). Node 24+ is required, enforced by an early `assertNodeVersion()` preflight.
+- **No build step.** Source files are served as native ES modules. JSDoc `.js` is default; `.ts` / `.mts` is stripped through a pluggable stripper (#508): Node 24+'s built-in `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, position-preserving) (invariant 10 + `agent-docs/typescript.md`). **Runs on Node 24+ or Bun** (run a Bun app with `bun --bun run dev` / `start`); the early `assertNodeVersion()` preflight enforces the Node floor and admits Bun. On Bun, `startServer` selects a native `Bun.serve` listener shell instead of the node:http one (skipping the compat bridge for ~1.9x more req/s on the listening path, at near-complete feature parity, the one node-only gap being 103 Early Hints since `Bun.serve` has no informational-response API), via a runtime-neutral seam that also sets up future `Deno.serve` / embedded adapters. Edge runtimes (no filesystem) are a separate, later target.
 - **SSR + CSR by default.** Pages are server-rendered HTML; components render light DOM by default, shadow DOM opt-in via `static shadow = true` with DSD SSR.
 - **Progressive enhancement is the default architecture.** Pages and components are SSR'd; with JS off, content reads, `<a>` navigates, `<form>` server actions submit, display-only elements render. JS is opt-in *per interactive behaviour* (`@click`, a reactive property assignment, a signal mutation). Never write a first paint that depends on hydration; never use `fetch` + JS where a `<form>` + server action would do.
 - **Display-only components are elided from the browser.** A component with no interactivity signal renders identical HTML with or without its JS, so the framework strips its import (and any vendor reachable only through it, importmap entry included) from the served source. Automatic, conservative, verified differentially. Disable with `"webjs": { "elide": false }` or `WEBJS_ELIDE=0`. See `agent-docs/components.md`.
@@ -101,7 +100,7 @@ A page/layout module still **loads** in the browser for its top-level side effec
 
 `route.{js,ts}` is the one routing file that is NOT isomorphic: a server-only HTTP handler (named `GET` / `POST` exports), the webjs equivalent of a Next route handler. It never ships to the client.
 
-**`.server.{js,ts}` is the one server boundary, an RPC + source-protection mechanism, NOT an RSC component.** With `'use server'` exports are RPC-callable (the browser import becomes a stub POSTing to `/__webjs/action/<hash>/<fn>`); without it the file is a server-only utility whose browser import **throws at module load** (Prisma, secrets, `node:*`, hashing). Consequence: **never import a no-`'use server'` util directly into a page, layout, or component** (it works at SSR but the client stub crashes on load); use it inside `'use server'` actions, `route.{js,ts}`, or `middleware`, and reach it from a page by importing a `'use server'` action (whose RPC stub loads safely client-side). This boundary, not a component annotation, is how a dependency is kept off the client (a date library used only during SSR belongs in `lib/format.server.ts`). See `agent-docs/components.md`.
+**`.server.{js,ts}` is the one server boundary, an RPC + source-protection mechanism, NOT an RSC component.** With `'use server'` exports are RPC-callable (the browser import becomes a stub POSTing to `/__webjs/action/<hash>/<fn>`); without it the file is a server-only utility whose browser import **throws at module load** (the DB driver, secrets, `node:*`, hashing). Consequence: **never import a no-`'use server'` util directly into a page, layout, or component** (it works at SSR but the client stub crashes on load); use it inside `'use server'` actions, `route.{js,ts}`, or `middleware`, and reach it from a page by importing a `'use server'` action (whose RPC stub loads safely client-side). This boundary, not a component annotation, is how a dependency is kept off the client (a date library used only during SSR belongs in `lib/format.server.ts`). See `agent-docs/components.md`.
 
 ---
 
@@ -135,7 +134,7 @@ lib/                        app-wide code (lib/*.server.js infra, lib/utils/ bro
 modules/<feature>/          feature-scoped: actions/ (mutations), queries/ (reads), components/, utils/, types.js
 components/*.js             SHARED presentational primitives
 public/*                    static assets, served at /<name>
-prisma/schema.prisma        data models
+db/*.server.{js,ts}         data layer (Drizzle: schema, columns, connection)
 ```
 
 Every file is a plain ES module.
@@ -149,7 +148,7 @@ import { html, css, WebComponent, render } from '@webjsdev/core';
 import { renderToString } from '@webjsdev/core/server';
 ```
 
-The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `expose.js`, `setCspNonceProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
+The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server-only modules (`render-server.js`, `setCspNonceProvider`); `renderToString` / `renderToStream` live at `@webjsdev/core/server` for Node-side consumers.
 
 | Export | Purpose |
 |---|---|
@@ -159,8 +158,6 @@ The bare `@webjsdev/core` specifier resolves to a BROWSER bundle dropping server
 | `render(v, el)` | Client-side render into a DOM element. |
 | `renderToString` | Server-side async render to HTML with DSD (from `/server`). |
 | `notFound()` / `redirect(url[, status])` | Throw to return 404, or a redirect. No-status default is convention-picked at the catching site: 302 for a GET page-render gate, 307 (method-preserving) for a server-action redirect. Override with `redirect(url, 308)` or `redirect(url, { status })`. |
-| `expose(p, fn)` | Tag a server action ALSO reachable at a REST path. Server-side only. |
-| `validateInput(fn, validate)` | Attach an input validator running on BOTH the RPC and `expose()` REST paths (#245). Server-side only. See Server actions. |
 | `Suspense({fallback, children})` | Page/region-level streaming boundary (a value in a hole). `repeat` keyed-list directive is also re-exported. |
 | `<webjs-suspense .fallback=${html\`…\`}>` | Component-level streaming boundary element (#471): wraps one or more components, flushes `.fallback` on the first byte, streams the resolved content in (concurrently across boundaries, progressively on soft nav). The renderer-recognized opt-in for SLOW async-render data. |
 | `connectWS(url, handlers)` / `richFetch<T>` | Client WebSocket (auto-reconnect, queued sends); content-negotiated rich-type fetch. |
@@ -197,7 +194,7 @@ MyThing.register('my-thing');
 
 **Lifecycle (lit-aligned), in order:** `shouldUpdate`, `willUpdate`, controllers' `hostUpdate()`, `update` (calls `render()` + commits), controllers' `hostUpdated()`, `firstUpdated`, `updated`, `updateComplete`, each receiving a `changedProperties` Map. **SSR runs only the constructor, attribute application, the pre-render hooks (`willUpdate` / `hostUpdate`), `reflect: true` reflection, and `render()`; it does NOT call `connectedCallback`, `firstUpdated`, `updated`, or any browser-only hook.** So defaults for first paint go in the constructor; browser-only data (localStorage, viewport, `navigator.*`) goes in `connectedCallback` writing a signal; server-known data arrives via the page function. Never ship a placeholder first paint that fetches in `connectedCallback`. A browser-only global in the constructor/`render()` throws at SSR (flagged by `no-browser-globals-in-render`; attribute methods and `closest()` are shimmed).
 
-**Async render (`async render()`), bare-await data fetch (#469).** A component may write `async render() { const u = await getUser(this.id); return html\`<h3>${u.name}</h3>\`; }`. Writing `await` makes the function async by JS rule, and every render path awaits a promise-returning `render()` automatically (no flag). This co-locates the fetch in the leaf component (no prop-drilling). The model is decoupled into three separate concerns. (1) **SSR always blocks**, so the resolved DATA is in the first paint with no fallback markup (PE-safe, JS-off reads it). (2) **The client re-fetch default is stale-while-revalidate**: when a prop / dependency change re-runs `async render()`, the current content stays until the new render resolves (no blank, no flash). (3) **`renderFallback()` is the OPTIONAL re-fetch loading UI**, a prop-aware method shown ONLY during a client re-fetch, NEVER on the first paint, and it does NOT trigger SSR streaming. **Errors are isolated per component by default** (no user code): a thrown `await getData()` renders a component-scoped error state while siblings render, and `renderError()` optionally customizes it (dev surfaces the message, prod stays silent). `getData()` is already isomorphic (a `'use server'` action is the real function during SSR and an RPC stub on the client), so the same line works both sides. Use `async render()` for request-time-known SERVER data that should be in the first paint; keep `Task` / signals for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). A **bare** async-render component (an `async render()` with no other client signal, light DOM) is **elided** like any display-only component (#474): its SSR'd HTML is the complete output, so the framework drops the module AND the redundant on-hydration re-fetch. It SHIPS only when it also carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, `static shadow = true`, `static refresh = true`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship: `static shadow = true` (Declarative Shadow DOM attaches only during HTML parsing, so a streamed or soft-navigated shadow component needs its module to re-run `attachShadow`) and `static refresh = true` (the explicit opt-in keeping the stale-while-revalidate on-load re-fetch that eliding drops, moot for request-stable data). **For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`…\`}>` to STREAM it** (the fallback flushes on the first byte, the data streams in; multiple boundaries fetch concurrently). This is the only way to show a first-paint fallback, a deliberate choice for slow regions, and it streams progressively on soft navigation too. A throwing component inside a boundary is isolated (renders its error state, siblings stream). (A hydration-seed optimization that would also skip the redundant client re-fetch on load is deferred, #472; stale-while-revalidate already hides it.)
+**Async render (`async render()`), bare-await data fetch (#469).** A component may write `async render() { const u = await getUser(this.id); return html\`<h3>${u.name}</h3>\`; }`. Writing `await` makes the function async by JS rule, and every render path awaits a promise-returning `render()` automatically (no flag). This co-locates the fetch in the leaf component (no prop-drilling). The model is decoupled into three separate concerns. (1) **SSR always blocks**, so the resolved DATA is in the first paint with no fallback markup (PE-safe, JS-off reads it). (2) **The client re-fetch default is stale-while-revalidate**: when a prop / dependency change re-runs `async render()`, the current content stays until the new render resolves (no blank, no flash). (3) **`renderFallback()` is the OPTIONAL re-fetch loading UI**, a prop-aware method shown ONLY during a client re-fetch, NEVER on the first paint, and it does NOT trigger SSR streaming. **Errors are isolated per component by default** (no user code): a thrown `await getData()` renders a component-scoped error state while siblings render, and `renderError()` optionally customizes it (dev surfaces the message, prod stays silent). `getData()` is already isomorphic (a `'use server'` action is the real function during SSR and an RPC stub on the client), so the same line works both sides. Use `async render()` for request-time-known SERVER data that should be in the first paint; keep `Task` / signals for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). A **bare** async-render component (an `async render()` with no other client signal, light DOM) is **elided** like any display-only component (#474): its SSR'd HTML is the complete output, so the framework drops the module AND the redundant on-hydration re-fetch. It SHIPS only when it also carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, `static shadow = true`, `static refresh = true`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship: `static shadow = true` (Declarative Shadow DOM attaches only during HTML parsing, so a streamed or soft-navigated shadow component needs its module to re-run `attachShadow`) and `static refresh = true` (the explicit opt-in keeping the stale-while-revalidate on-load re-fetch that eliding drops, moot for request-stable data). **For SLOW data where blocking the first byte hurts, wrap the region in `<webjs-suspense .fallback=${html\`…\`}>` to STREAM it** (the fallback flushes on the first byte, the data streams in; multiple boundaries fetch concurrently). This is the only way to show a first-paint fallback, a deliberate choice for slow regions, and it streams progressively on soft navigation too. A throwing component inside a boundary is isolated (renders its error state, siblings stream). **The on-hydration re-fetch is itself eliminated by SSR action seeding (#472):** each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page, and the generated RPC stub reads that seed on its first client call, so a shipping async component does NOT re-issue the RPC on hydration (a later refetch / arg-change still goes to the network). Keyed by action-hash + fn + serialized args, consume-once, fail-open (a miss degrades to a normal RPC, never wrong data). Captured via a transparent server-side `'use server'` facade (no source transform, no build step; the browser source tab and on-disk files are unchanged), default on, opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0`.
 
 **Light DOM (default) vs Shadow DOM.** Light DOM applies global CSS and Tailwind directly (default; for Tailwind/global CSS + simple composition). Shadow DOM (`static shadow = true`) is for `static styles` scoped CSS and third-party isolation; `<slot>` works in either. A light-DOM component authoring custom CSS MUST prefix every class selector with its tag name (invariant 7); prefer Tailwind. Install the `webjs` VSCode extension (`packages/editors/vscode`, VS Marketplace + Open VSX; also covers Cursor / Antigravity / Windsurf) or `webjs.nvim` (`packages/editors/nvim`, via lazy.nvim) for template highlighting + editor intelligence with no Lit plugin, or add the standalone `@webjsdev/intellisense` to `tsconfig.json` `plugins` manually (JetBrains). Full deep-dive in `agent-docs/components.md` + `agent-docs/lit-muscle-memory-gotchas.md`.
 
@@ -244,11 +241,13 @@ Optional app-root file default-exporting a **schema object** (env-var names to a
 
 The server-only-utility row (`.server.ts`, no `'use server'`) is a runtime trap: its browser stub throws at module load, so a page / layout / component that ends up SHIPPING to the browser and transitively imports one crashes the moment the module loads, while `webjs typecheck` and the rest of `webjs check` pass. `webjs check`'s `no-server-import-in-browser-module` rule catches this statically by reusing the build's elision verdict (it only flags modules that genuinely ship; a display-only page the framework elides is fine, because the framework strips its server import). A `'use server'` action is exempt: its browser stub is a working RPC, which is the intended way to call the server from a shipping module.
 
-Server actions export named async functions whose args + returns round-trip through the serializer. **Importing from a client component IS the API** (rewritten to an RPC stub; never hand-write `fetch()`). **Expose as REST:** `expose('METHOD /path', fn, { validate? })`. **Input validation runs on BOTH call paths (#245),** declared via `validateInput(fn, validate)` or `expose(..., { validate })`; the framework only CALLS the validator (ships no validation library) and reads its return (`{ success: true, data? }` runs the action, `{ success: false, fieldErrors }` returns a `422` without running the body, a THROW is a sanitized error, any other value is transformed input). The validator stays server-side and receives the action's first argument. Full reference in `agent-docs/recipes.md`.
+Server actions export named async functions whose args + returns round-trip through the serializer. **Importing from a client component IS the API** (rewritten to an RPC stub; never hand-write `fetch()`). **REST over HTTP is a `route.ts`** that imports and calls the action (optionally via the `route(action, opts?)` adapter from `@webjsdev/server`, which merges query + route params + JSON body into one input object and JSON-responds). **Input validation (#245)** is declared via the `export const validate` config export (read on the RPC boundary); a `route()` endpoint passes the same validator as its `{ validate }` option. The framework only CALLS the validator (ships no validation library) and reads its return (`{ success: true, data? }` runs the action, `{ success: false, fieldErrors }` returns a `422` without running the body, a THROW is a sanitized error, any other value is transformed input). The validator stays server-side and receives the action's first argument. Full reference in `agent-docs/recipes.md`.
 
-### RPC + expose security
+**HTTP-verb actions via config exports (#488).** A `'use server'` action declares its HTTP semantics through RESERVED sibling exports the framework reads statically, the same way a page declares `export const revalidate`: `export const method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'` (absent = POST, so existing actions are unchanged), `export const cache = 60` (seconds, or `{ maxAge, swr, public }`, default `private`; **`public: true` SHARES the response across users keyed only by URL + args, so use it ONLY for data identical for every visitor, never for a session / per-user read, the same safety rule as a page's `export const revalidate`**), `export const tags = (id) => [\`user:${id}\`]` (a GET's cache tags), `export const invalidates = (id) => [...]` (a mutation's tags to evict), `export const validate = (input) => ...` (the boundary validator), and `export const middleware = [mw1, mw2]` (#490: per-action middleware, each `async (ctx, next) => result`, run around the action on BOTH the RPC and `route.ts` (including the `route()` adapter) boundaries; a middleware short-circuits by returning an `ActionResult` instead of calling `next()`, and accumulates context the action reads via `actionContext()` from `@webjsdev/server`, no signature change). The function stays a plain `export async function`; **one function per file** (a configured file with more than one callable function is a `webjs check` error). The call site never changes (`await getUser(7)`); the verb only changes the transport: a **GET** rides args in the URL (`?a=`, with a POST fallback over a 4KB cap), is CSRF-exempt, carries `Cache-Control` + a weak ETag (answering `If-None-Match` with a 304) and `X-Webjs-Tags`, and reads the SSR seed (#472) first; a **mutation** (POST/PUT/PATCH/DELETE) sends the rich body (DELETE rides the URL), is CSRF-protected, and on completion (the action did not throw) evicts its `invalidates` tags from the server `cache()` (`revalidateTags`) and reports them via `X-Webjs-Invalidate` so the client browser-cache coordinator revalidates a later read. A mismatched request method is a `405` + `Allow`. Why webjs needs this and Next does not: webjs has no RSC server/client split, so reads and writes both flow through the one action mechanism (Next's reads are Server Component fetches, so its actions stay POST-only). `validate` is a BOUNDARY concern (the RPC endpoint and a `route.ts`), not a direct server-to-server call. A public REST endpoint is a `route.ts` that imports and calls the action (optionally via the `route()` adapter). **Cancellation (#492):** an action reads the request's `AbortSignal` via `actionSignal()` (from `@webjsdev/server`) to stop work on a client disconnect / abort (a never-aborting signal outside an action keeps the line safe server-to-server); on the client, a superseded `async render()` automatically ABORTS the previous render's in-flight action fetch (not just drops it), via a per-render `AbortController` the stub binds each fetch to. **Streaming results (#489):** an action that RETURNS a `ReadableStream` / async iterable / async generator (any verb) streams its chunks over the single RPC response instead of buffering; the call site does `for await (const chunk of await streamTokens(8))` and each rich-serialized chunk arrives as it is yielded (back-pressure respected, the source generator cancelled on a client disconnect / superseded render). Detection is purely on the return value (no config export); a streamed result is never cached / ETagged / seeded (a mutation still emits `X-Webjs-Invalidate`). A mid-stream throw surfaces as an error from the iterable (the HTTP status is already 200), the author message in prod.
 
-Client to action RPC posts `x-webjs-csrf` matching the cookie issued on first SSR (mismatch 403); prod errors are sanitized to `message` only. `expose()`d REST endpoints are NOT CSRF-protected: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
+### RPC + REST endpoint security
+
+Client to action RPC posts `x-webjs-csrf` matching the cookie issued on first SSR (mismatch 403); prod errors are sanitized to `message` only. A `route.ts` REST endpoint (hand-written or via the `route()` adapter) is NOT CSRF-protected: authenticate every mutating endpoint, use `validate`, log without secrets, rate-limit. For CORS use the `cors()` middleware from `@webjsdev/server`; **`credentials: true` REQUIRES an explicit origin allowlist, never `'*'`.** See `agent-docs/advanced.md`.
 
 ### Components (`components/*.{js,ts}`)
 
@@ -259,7 +258,7 @@ One custom element per file; call `Class.register('tag')` at module top level. S
 ## Modules architecture (preferred for non-trivial apps)
 
 - **`modules/<feature>/actions/*.server.{js,ts}`** mutations, **`queries/*.server.{js,ts}`** reads (one function per file), **`components/*.{js,ts}`** feature-owned components (shared UI in top-level `components/`), **`utils/*.{js,ts}`** pure helpers (no `'use server'`, no DB), **`types.{js,ts}`** typedefs.
-- **`lib/`** cross-cutting: `lib/*.server.{js,ts}` server-only infra (Prisma, session, hashing), `lib/utils/*` browser-safe helpers, `lib/*.ts` app-wide values.
+- **`lib/`** cross-cutting: `lib/*.server.{js,ts}` server-only infra (session, hashing; the DB connection lives in `db/connection.server.ts`), `lib/utils/*` browser-safe helpers, `lib/*.ts` app-wide values.
 
 ### The `ActionResult<T>` envelope
 
@@ -294,7 +293,7 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 > Hit one of these as a runtime error? The [Troubleshooting page](https://docs.webjs.com/docs/troubleshooting) is keyed by symptom (the throw-at-load server import, the backtick-in-template 500, the TypeScript strip failure, the SSR browser-global crash, the missing-frame swap) and maps each back to the invariant and the `webjs check` rule below.
 
-1. **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** The `.server.{js,ts}` extension is the path-level boundary (the file router refuses to serve the source); a `'use server'` directive additionally makes exports RPC-callable, else the file is a server-only utility whose browser import is a throw-at-load stub. Importing `@prisma/client`, `node:*`, or any server-only dep from a component or an `app/**` page / layout / loading / error / not-found file crashes the browser at module load.
+1. **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** The `.server.{js,ts}` extension is the path-level boundary (the file router refuses to serve the source); a `'use server'` directive additionally makes exports RPC-callable, else the file is a server-only utility whose browser import is a throw-at-load stub. Importing a DB driver (`better-sqlite3` / `pg`), `node:*`, or any server-only dep from a component or an `app/**` page / layout / loading / error / not-found file crashes the browser at module load.
 2. **Every `*.server.{js,ts}` file with `'use server'` exports must be `async` functions returning serializer-safe values.** Args and results round-trip via webjs's wire. Files without `'use server'` (server-only utilities) can export anything, including singletons.
 3. **Custom element tag names must contain a hyphen** (HTML spec). Pass the tag to `Class.register('tag-name')`, not a static field. Any short-string quote works: `'tag-name'`, `"tag-name"`, or `` `tag-name` `` (single-line, no interpolation).
 4. **Event (`@`), property (`.`), boolean (`?`) holes in `html` must be unquoted**, e.g. `@click=${fn}`, never `@click="${fn}"`.
@@ -311,17 +310,17 @@ The advanced client-router surface is in `agent-docs/advanced.md`: **link prefet
 
 ## Scaffolding
 
-Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Prisma+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Prisma, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
+Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
 
-Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Prisma + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `prisma/schema.prisma` to real models FIRST, then `webjs db migrate <name>`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
+Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
 
 ---
 
 ## CLI reference
 
 ```sh
-webjs dev    [--port N]            # dev server with live reload
-webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2)
+webjs dev    [--port N] [--no-hot] # dev server with live reload (node --watch on Node, bun --hot on Bun). --no-hot runs in-process. Runs webjs.dev.before + webjs.dev.parallel (#550)
+webjs start  [--port N]            # prod server; source IS the runtime, plain HTTP/1.1 (reverse-proxy for TLS + HTTP/2). Runs webjs.start.before first (#550)
 webjs test   [--server] [--browser] [--watch]
 webjs check  [--rules] [--json]    # correctness validator (report-only, no autofix); --json for an agent loop
 webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, check
@@ -329,19 +328,19 @@ webjs doctor                       # project-health checklist; non-zero exit on
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)
 webjs typecheck [tsc args...]      # the project's own tsc --noEmit
 webjs create <name> [--template api|saas]
-webjs db <prisma-subcommand> [...]
+webjs db <generate|migrate|push|studio|seed>   # wraps drizzle-kit (+ runs db/seed.server.ts)
 webjs ui init | add <names...> | list | view <name>
 webjs vendor pin|unpin|list|audit|outdated|update [--from PROVIDER]   # importmap pinning, .webjs/vendor/importmap.json
 ```
 
-`--from PROVIDER` accepts `jspm` (default), `jsdelivr`, `unpkg`, `skypack` and is persisted in the pin file. `PORT` is honoured when `--port` is absent; `webjs dev` emits `routes.d.ts` automatically. Running this repo's own apps (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`): always `cd` in and use **its** `npm run dev` / `npm start`, never `webjs dev` / `webjs start` directly (each composes extra watchers via `npm`).
+`--from PROVIDER` accepts `jspm` (default), `jsdelivr`, `unpkg`, `skypack` and is persisted in the pin file. `PORT` is honoured when `--port` is absent; `webjs dev` emits `routes.d.ts` automatically. Running this repo's own apps (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`): `cd` in and use **its** `npm run dev` / `npm start`; as of #550 a bare `webjs dev` / `webjs start` is equivalent (the per-app orchestration moved into the `webjs.dev` / `webjs.start` tasks config, which the primitive runs), so the npm scripts are now just thin aliases.
 
 ---
 
 ## Environment, server config, caching, observability
 
 - **Env vars.** `process.env.X` reads are server-only; `WEBJS_PUBLIC_`-prefixed names are exposed in the browser via an inline `<script>` (no build); `NODE_ENV` is defined both sides. See `agent-docs/built-ins.md`.
-- **The `package.json` `"webjs"` block.** Security headers (on by default, per-path `webjs.headers` overrides), CSP (opt-in nonce, `webjs.csp`), declarative `webjs.redirects` (#254), `webjs.trailingSlash` (#255), `webjs.basePath` (#256), and ingress caps (`maxBodyBytes` / `maxMultipartBytes` / server timeouts). Type it with `WebjsConfig` + the JSON Schema. See `agent-docs/configuration.md`.
+- **The `package.json` `"webjs"` block.** Security headers (on by default, per-path `webjs.headers` overrides), CSP (opt-in nonce, `webjs.csp`), declarative `webjs.redirects` (#254), `webjs.trailingSlash` (#255), `webjs.basePath` (#256), ingress caps (`maxBodyBytes` / `maxMultipartBytes` / server timeouts), and dev/start task orchestration (`webjs.dev.before` / `webjs.dev.parallel` / `webjs.start.before`, #550, the orchestration `webjs dev`/`start` run so they match `npm run dev`/`start`). Type it with `WebjsConfig` + the JSON Schema. See `agent-docs/configuration.md`.
 - **Caching + file storage** (`agent-docs/built-ins.md`). HTTP `Cache-Control`, the `cache()` query helper + `revalidateTag`, the server HTML response cache (`export const revalidate` + `revalidatePath`, #241), content-hash asset URLs (`?v=`, #243), conditional GET (ETag, #240), and `FileStore` + `diskStore` (streaming, traversal-safe, signed URLs, S3-pluggable, #247).
 - **Observability** (`agent-docs/configuration.md`). Access log, `requestId()` + `X-Request-Id`, the `onError` APM hook, `GET /__webjs/version` (#239).
 
@@ -386,11 +385,13 @@ export default async function User({ params }: { params: { id: string } }) {
 ```ts
 // modules/users/actions/update-profile.server.ts
 'use server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { eq } from 'drizzle-orm';
+import { db } from '../../../db/connection.server.ts';
+import { users } from '../../../db/schema.server.ts';
 export async function updateProfile(input: { name: string }) {
   const name = String(input?.name || '').trim();
   if (!name) return { success: false, error: 'name required', status: 400 };
-  const row = await prisma.user.update({ where: { id: me.id }, data: { name } });
+  const [row] = await db.update(users).set({ name }).where(eq(users.id, me.id)).returning();
   return { success: true, data: row };
 }
 ```
@@ -406,4 +407,4 @@ Not in v1. Do not implement as part of other tasks:
 - **Bundling and per-route code splitting.** webjs is **no-build** (the Rails 7 + importmap model); prod perf comes from HTTP/2 multiplex + `<link rel="modulepreload">` hints, not concatenation. **Do not propose a bundler or `webjs build`.**
 - **Vite-grade HMR with state preservation.** Custom elements only `define` once, so full reload is necessary; data reloads are near-instant via `fs.watch` to SSE.
 - **React Server Components Flight.** Server actions + `Suspense` streaming cover the need.
-- **Edge-runtime bundling / full portability** (see `agent-docs/deployment.md`), **i18n, image optimization** (layer libraries on top).
+- **Edge-runtime bundling / full portability** (deployment guidance lives in the docs site at `/docs/deployment`), **i18n, image optimization** (layer libraries on top).

package/resources/agent-docs/advanced.md

@@ -360,7 +360,7 @@ export async function GET(req) {
 ### Behavior
 
 - **Preflight.** An `OPTIONS` request carrying `Access-Control-Request-Method` short-circuits with a `204` carrying the Allow-Methods / Allow-Headers / Max-Age headers. `next()` is NOT called. A disallowed-origin preflight returns a bare `204` with no CORS headers, so the browser blocks the follow-up.
-- **Actual request.** `next()` runs, then `Access-Control-Allow-Origin` (plus credentials / exposed headers) is attached. A disallowed origin gets NO `Access-Control-Allow-Origin`, and the browser blocks the cross-origin read, but the server still serves the response (CORS is browser-enforced, not a server gate; this matches the `expose()` path, which never 403s a mismatched actual request).
+- **Actual request.** `next()` runs, then `Access-Control-Allow-Origin` (plus credentials / exposed headers) is attached. A disallowed origin gets NO `Access-Control-Allow-Origin`, and the browser blocks the cross-origin read, but the server still serves the response (CORS is browser-enforced, not a server gate, so a mismatched actual request is never 403'd server-side).
 - **`Vary: Origin`.** Appended (never clobbering an existing `Vary`) whenever the allowed origin is dynamic (a reflected, per-origin value), so a shared cache keys on `Origin` and cannot poison one origin's response onto another. A constant `*` (no credentials) does not vary, so no `Vary` is added.
 
 ### `credentials: true` requires an explicit origin allowlist (spec, enforced, warned)
@@ -1096,6 +1096,47 @@ branch return a normal `ActionResult` instead. `renderStream` is auto-registered
 by the client router, so it (and the `<webjs-stream>` element) is available
 wherever a layout imports `@webjsdev/core/client-router`.
 
+### Streaming RPC results: an action returns a stream (#489)
+
+`<webjs-stream>` above is the SERVER-PUSHED render-side primitive (the server
+decides what changes and ships HTML actions). Streaming RPC is the complementary
+PULL-side primitive: a `'use server'` action that RETURNS a `ReadableStream`, an
+async iterable, or an async generator streams its chunks over the single RPC
+response, and the client gets back an async iterable to `for await`. This is the
+token-stream / progress / incremental-result case a component consumes
+imperatively after an interaction.
+
+```ts
+// modules/ai/actions/stream-answer.server.ts
+'use server';
+export async function* streamAnswer(prompt: string) {
+  for await (const token of llm.complete(prompt)) yield token;
+}
+```
+
+```ts
+// inside a component
+for await (const token of await streamAnswer(q)) {
+  this.text.set(this.text.get() + token);   // renders incrementally
+}
+```
+
+The wire is a sequence of length-prefixed frames (`application/vnd.webjs+stream`):
+each chunk is rich-serialized (a `Date` / `Map` / `BigInt` round-trips), then a
+terminal frame closes the stream. Detection is purely on the RETURN value, so any
+verb (#488) can stream and there is no config export to declare. Back-pressure is
+respected (a slow consumer throttles a fast producer), and the request
+`AbortSignal` (#492) cancels the source generator on a client disconnect or a
+superseded `async render()`. A streamed result is never cached, ETagged, or
+seeded (#472); a mutation that streams still emits its `X-Webjs-Invalidate`
+header. A mid-stream throw surfaces as an error from the iterable (the HTTP status
+is already 200, so wrap the `for await` in `try/catch`), the author message in
+prod. A truncated stream (a server crash, a dropped connection) also throws
+rather than completing silently: a healthy stream always ends in an explicit
+terminal frame, so a missing one is an error. For a slow region you want behind a fallback on the FIRST paint, use
+`<webjs-suspense>` instead; streaming RPC is for an imperative stream consumed
+after an interaction. Full reference: the [Data fetching](https://docs.webjs.com/docs/data-fetching) page.
+
 ### Opt out per link
 
 ```html

package/resources/agent-docs/built-ins.md

@@ -13,7 +13,7 @@ layer to debug.
 ```js
 // route handler
 export async function GET() {
-  const posts = await prisma.post.findMany();
+  const posts = await db.query.posts.findMany();
   return new Response(JSON.stringify(posts), {
     headers: {
       'Cache-Control': 'public, max-age=60, stale-while-revalidate=300',
@@ -51,10 +51,10 @@ until the TTL expires:
 // modules/posts/queries/list-posts.server.ts
 'use server';
 import { cache } from '@webjsdev/server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { db } from '../../../db/connection.server.ts';
 
 export const listPosts = cache(
-  async () => prisma.post.findMany({ orderBy: { createdAt: 'desc' } }),
+  async () => db.query.posts.findMany({ orderBy: { createdAt: 'desc' } }),
   { key: 'posts', ttl: 60 }
 );
 ```
@@ -65,12 +65,12 @@ wrapper), add `tags`. It is either a static `string[]` or a function
 
 ```ts
 export const postById = cache(
-  async (id: string) => prisma.post.findUnique({ where: { id } }),
+  async (id: string) => db.query.posts.findFirst({ where: { id } }),
   { key: 'post', ttl: 300, tags: (id) => ['post:' + id] } // per-entity tag
 );
 
 export const listPosts = cache(
-  async () => prisma.post.findMany(),
+  async () => db.query.posts.findMany(),
   { key: 'posts', ttl: 60, tags: ['posts'] } // static tag
 );
 ```
@@ -83,9 +83,11 @@ no import of the wrapper):
 // modules/comments/actions/create-comment.server.ts
 'use server';
 import { revalidateTag, revalidatePath } from '@webjsdev/server';
+import { db } from '../../../db/connection.server.ts';
+import { comments } from '../../../db/schema.server.ts';
 
 export async function createComment(input) {
-  await prisma.comment.create({ data: input });
+  await db.insert(comments).values(input);
   await revalidateTag('post:' + input.postId); // postById(postId) recomputes
   await revalidateTag('posts');                 // listPosts recomputes
   await revalidatePath('/blog');                // also evict the cached HTML
@@ -163,7 +165,7 @@ Evict on a write with `revalidatePath`:
 import { revalidatePath } from '@webjsdev/server';
 
 export async function publishPost(input) {
-  // ... persist via Prisma ...
+  // ... persist via Drizzle ...
   await revalidatePath('/blog');   // next /blog request re-renders fresh
   return { success: true };
 }
@@ -248,7 +250,7 @@ export const { auth, signIn, signOut, handlers } = createAuth({
   providers: [
     Credentials({
       async authorize(credentials) {
-        const user = await prisma.user.findUnique({ where: { email: credentials.email } });
+        const user = await db.query.users.findFirst({ where: { email: credentials.email } });
         if (!user || !verifyPassword(credentials.password, user.passwordHash)) return null;
         return { id: user.id, name: user.name, email: user.email, role: user.role };
       },

package/resources/agent-docs/components.md

@@ -116,6 +116,10 @@ class Report extends WebComponent {
 
 **Elision (#474).** A **bare** `async render()` (no other client signal, light DOM) is **elided** like any display-only component: the SSR'd data is the complete first paint, so the framework drops the module and the redundant on-hydration re-fetch (a common content / docs leaf shape). It ships only when it ALSO carries an independent signal (an `@event`, a non-`state` reactive prop, a signal / reactive import, a lifecycle hook including `renderFallback()`, a `<slot>`, cross-module observation, or a transitively-reachable interactive child). Two carve-outs always ship. `static shadow = true` ships because Declarative Shadow DOM attaches only during HTML parsing, so a streamed (`<webjs-suspense>`) or soft-navigated shadow component arrives via a JS DOM insertion and needs its module to re-run `attachShadow`. `static refresh = true` is the explicit opt-in to keep the stale-while-revalidate on-load re-fetch that eliding drops (moot for request-stable data, the default; reach for it only when fresh-on-load matters). The only behaviour eliding removes is that on-load refresh; the first paint is byte-identical, verified by the differential-elision guard.
 
+**SSR action seeding (#472).** For a SHIPPING async component (one that hydrates because it carries an interactivity signal), the on-hydration re-fetch is eliminated without eliding the module. Each `'use server'` action result invoked during a (non-streamed) SSR render is serialized into the page as one `<script type="application/json" id="__webjs-seeds">` block, keyed by the action's hash + function name + serialized args. The generated client RPC stub reads that seed on its FIRST call: a hit resolves synchronously (no network, no hydration flicker), a later refetch or arg-change misses (consume-once) and goes to RPC as normal. So `const u = await getUser(this.id)` runs once, server-side, and its result is reused on the client's first render. The capture is a transparent server-side facade over the `'use server'` module (a synchronous load hook wraps each export in a recording `Proxy`), so there is **no source transform and no build step**: the browser source tab and the on-disk files are byte-unchanged, and the RPC stub the browser fetches is the same shape as before (it just consults the seed first). The install mechanism is runtime-neutral (#529): Node uses `module.registerHooks`, Bun uses a `Bun.plugin` `onLoad` (Bun has no `module.registerHooks`), and both emit the identical seed, so a page seeds the same on either runtime. Fail-open by construction: a key miss is always a normal RPC, never wrong data. Default on; opt out with `"webjs": { "seed": false }` or `WEBJS_SEED=0` (then the client re-fetches on hydration, hidden by stale-while-revalidate as before). A soft navigation carries the seed too: the client router ingests the incoming page's payload (`applySwap` -> `scanSeeds`) before its components hydrate, so a navigated async component also skips the refetch. Streamed regions (`<webjs-suspense>`) are NOT seeded (their data resolves after the first flush), so a slow boundary keeps the stale-while-revalidate refetch.
+
+**Interactivity during a COLD on-hydration re-fetch (#528).** Seeding matters for more than a wasted round trip. When a SHIPPING async component DOES re-fetch on hydration (seeding off via `WEBJS_SEED=0`, a `static refresh = true` leaf, or a seed miss), its FIRST client commit is deferred until that re-fetch resolves, and that commit is the step that binds the component's event listeners. So for the fetch's duration the SSR'd markup is visible but NOT yet interactive: an `@click` does nothing until the data lands (the window equals the action's latency, not a constant). Seeding erases this by resolving the first render synchronously, so the component hydrates and binds its listeners immediately, which is the default and works on both Node and Bun (#529, seeding is no longer Node-only). The component is fully reactive once that first commit lands: this is purely a cold-start window, NOT a lost signal subscription (a bump after the commit re-renders normally). To keep an async leaf interactive from the first paint regardless, give it a synchronous first render (read request-known data from a prop / the constructor) and move the async work to a signal-driven `Task` or an `@event` handler.
+
 ### Streaming a slow region with `<webjs-suspense>` (#471)
 
 `async render()` BLOCKS the first byte by default (the SSR HTML waits for the data). For a SLOW region where that wait hurts time-to-first-byte, wrap it in `<webjs-suspense>` to stream it: the fallback flushes immediately, the resolved content streams in.

package/resources/agent-docs/configuration.md

@@ -208,6 +208,37 @@ Returns JSON describing the live build, alongside the `/__webjs/health` and `/__
 
 ---
 
+## Dev/start task orchestration: `webjs.dev` / `webjs.start` (#550)
+
+`webjs dev` and `webjs start` run an app's per-environment orchestration
+themselves, read from the `package.json` `"webjs"` block, so the framework
+primitive is not a degraded run versus `npm run dev` / `npm start`. The npm
+scripts become thin aliases (`"dev": "webjs dev"`), and both forms behave
+identically. This replaces the old `predev` / `prestart` npm hooks +
+`concurrently` watchers (which a bare `webjs dev` silently skipped, #452).
+
+```jsonc
+"webjs": {
+  "dev": {
+    "before":   ["webjs db migrate"],                                  // one-shot, runs to completion first
+    "parallel": ["tailwindcss -i ./public/input.css -o ./public/tailwind.css --watch"]  // long-lived, runs alongside the server
+  },
+  "start": {
+    "before":   ["webjs db migrate"]                                   // one-shot, before serving
+  }
+}
+```
+
+- **`before`** (dev and start): commands run sequentially to completion BEFORE the server boots (the old `predev` / `prestart`: `webjs db migrate`, a registry copy). A non-zero exit ABORTS the boot with a clear message, so a failed migration never serves stale code/schema.
+- **`parallel`** (dev only): long-lived child processes that run ALONGSIDE the server (the old `concurrently` watchers: the Tailwind CLI `--watch`). They are spawned once in the parent (not on every hot-reload restart) and TORN DOWN on exit (SIGINT / SIGTERM / server exit), so a watcher cannot leak past the dev server.
+- Each command runs through a shell, so a normal command line works. An empty / absent block means `webjs dev` / `start` run unchanged, so a plain app with no Tailwind/DB needs no config.
+- The scaffold uses the Tailwind browser runtime (no CSS build step), so it ships only `dev.before` / `start.before` (the Drizzle migration apply); an app that adds the Tailwind CLI puts its `--watch` under `webjs.dev.parallel`. The in-repo apps (`examples/blog`, `website`, `docs`, ui-website) show the Tailwind `parallel` watcher pattern.
+- **Prod note:** `before` runs at boot, so `webjs start` runs `webjs db migrate` in-process to apply pending migrations. Drizzle has no client-codegen step (the schema IS the types, inferred at compile time), so there is nothing to run at image-BUILD time. Authoring a new migration from a schema change is a dev-time `webjs db generate`, committed to source control, not a boot step. So `CMD ["npm", "start"]` and `CMD ["webjs", "start"]` are equivalent.
+
+Read by `readAppTasks` in `packages/cli/lib/app-tasks.js` (pure, unit-tested); orchestrated in `packages/cli/bin/webjs.js` (`runBeforeSteps` / `startParallelTasks`).
+
+---
+
 ## Server port resolution (`--port` / `PORT` / `.env`) (#447)
 
 Both `webjs dev` and `webjs start` resolve the listen port with a single

package/resources/agent-docs/framework-dev.md

@@ -1,6 +1,6 @@
 # Framework development (editing webjs itself)
 
-Read this only when editing the webjs monorepo (this repo), not a scaffolded app. The repo is buildless: `packages/` is plain `.js` with JSDoc (never add `.ts` there); TypeScript is fine in `examples/`, `docs/`, `website/`. Each in-repo app (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`) is run via its OWN `npm run dev` / `npm start`, never `webjs dev` directly, since each composes extra watchers. The sections below cover the repo-health git config, the changelog flow, and the dev error overlay.
+Read this only when editing the webjs monorepo (this repo), not a scaffolded app. The repo is buildless: `packages/` is plain `.js` with JSDoc (never add `.ts` there); TypeScript is fine in `examples/`, `docs/`, `website/`. Each in-repo app (`website/`, `docs/`, `examples/blog/`, `packages/ui/packages/website/`) is run from its OWN dir via `npm run dev` / `npm start`; as of #550 a bare `webjs dev` / `webjs start` is equivalent (each app's per-environment orchestration, the Tailwind watcher, `webjs db migrate`, the registry copy, moved into its `webjs.dev` / `webjs.start` tasks config, which `webjs dev`/`start` run). The sections below cover the repo-health git config, the changelog flow, and the dev error overlay.
 
 ---
 

package/resources/agent-docs/recipes.md

@@ -13,41 +13,36 @@ schema with the real domain models, then build features on top. This is the
 transition agents most often get wrong, so it is the first recipe.
 
 > **Two non-negotiables.** NEVER leave the example `User` model in
-> `schema.prisma` if the app does not actually have users (delete or replace
-> it). NEVER persist app data in JSON files (`data/todos.json`, `db.json`), in
-> a module-scope array or `Map`, or in `localStorage`. Those reset on every
-> reload and cannot scale. Every piece of stored data is a Prisma model.
-
-1. **Edit `prisma/schema.prisma`** to the real domain. Replace the example
-   `User` model with the models the app needs.
-
-   ```prisma
-   // prisma/schema.prisma
-   model Post {
-     id        String   @id @default(cuid())
-     title     String
-     body      String
-     published Boolean  @default(false)
-     createdAt DateTime @default(now())
-   }
-   ```
+> `db/schema.server.ts` if the app does not actually have users (delete or
+> replace it). NEVER persist app data in JSON files (`data/todos.json`,
+> `db.json`), in a module-scope array or `Map`, or in `localStorage`. Those
+> reset on every reload and cannot scale. Every piece of stored data is a
+> Drizzle table.
+
+1. **Edit `db/schema.server.ts`** to the real domain. Replace the example
+   `User` model with the models the app needs (the helpers come from
+   `db/columns.server.ts`).
 
-   Start the dev server with `npm run dev` (the canonical command), NOT a bare
-   `webjs dev`: `npm run dev` runs the `predev` hook (`prisma generate`) first,
-   while `webjs dev` skips it and boots against an ungenerated client. A bare
-   `webjs dev` will now warn and point you back at `npm run dev`, but use the
-   npm script from the start.
+   ```ts
+   // db/schema.server.ts
+   import { table, pk, text, bool, createdAt, index } from './columns.server.ts';
+   export const posts = table('posts', {
+     id: pk(),
+     title: text().notNull(),
+     body: text().notNull(),
+     published: bool().notNull().default(false),
+     createdAt: createdAt(),
+   }, (t) => [index(t.createdAt)]);
+   ```
 
-2. **Migrate.** Run the npm script (not the `webjs`/`prisma` binary directly,
-   so the `predev` / `db:*` hooks fire):
+2. **Generate + migrate.** Drizzle has no codegen; `generate` turns the schema
+   into SQL, `migrate` applies it:
 
    ```sh
-   npm run db:migrate -- --name add_post
+   npm run db:generate      # schema -> SQL migration (drizzle-kit)
+   npm run db:migrate       # apply it to the dev SQLite database
    ```
 
-   This creates the migration, applies it to the dev SQLite database, and
-   regenerates the Prisma client.
-
 3. **Generate one query and one action per operation**, one exported function
    per file, named after the file, under the feature module. Reads go in
    `queries/`, mutations in `actions/`. Both are `.server.ts` with
@@ -56,27 +51,28 @@ transition agents most often get wrong, so it is the first recipe.
    ```ts
    // modules/posts/queries/list-posts.server.ts
    'use server';
-   import { prisma } from '../../../lib/prisma.server.ts';
+   import { db } from '../../../db/connection.server.ts';
    export async function listPosts() {
-     return prisma.post.findMany({ where: { published: true }, orderBy: { createdAt: 'desc' } });
+     return db.query.posts.findMany({ where: { published: true }, orderBy: { createdAt: 'desc' } });
    }
    ```
 
    ```ts
    // modules/posts/actions/create-post.server.ts
    'use server';
-   import { prisma } from '../../../lib/prisma.server.ts';
+   import { db } from '../../../db/connection.server.ts';
+   import { posts } from '../../../db/schema.server.ts';
    export async function createPost(input: { title: string; body: string }) {
      const title = String(input?.title || '').trim();
      if (!title) return { success: false, error: 'title required', status: 400 };
-     const post = await prisma.post.create({ data: { title, body: String(input?.body || '') } });
+     const [post] = await db.insert(posts).values({ title, body: String(input?.body || '') }).returning();
      return { success: true, data: post };
    }
    ```
 
 4. **Wire it into a page** by calling the query (the page runs on the server,
    so it imports the `.server` query directly and awaits it). Never import
-   `@prisma/client` into a page; reach the database through the query.
+   the DB driver into a page; reach the database through the query.
 
    ```ts
    // app/posts/page.ts
@@ -118,11 +114,13 @@ export default async function User({ params }: { params: { id: string } }) {
 ```ts
 // modules/users/actions/update-profile.server.ts
 'use server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { eq } from 'drizzle-orm';
+import { db } from '../../../db/connection.server.ts';
+import { users } from '../../../db/schema.server.ts';
 export async function updateProfile(input: { name: string }) {
   const name = String(input?.name || '').trim();
   if (!name) return { success: false, error: 'name required', status: 400 };
-  const row = await prisma.user.update({ where: { id: me.id }, data: { name } });
+  const [row] = await db.update(users).set({ name }).where(eq(users.id, me.id)).returning();
   return { success: true, data: row };
 }
 ```
@@ -130,12 +128,12 @@ export async function updateProfile(input: { name: string }) {
 Call it from a client component via a normal import. The dev server
 rewrites the import to a typed RPC stub.
 
-## Validate a server action's input once, for both call paths (#245)
+## Validate a server action's input (#245)
 
-`validateInput(fn, validate)` attaches an input validator that runs
-SERVER-SIDE before the action body on EVERY call path (the RPC path a
-client component import takes AND the `expose()` REST route if the action
-has one). On failure it returns a structured `ActionResult`
+Declare a `validate` config export beside the action (#488). It runs
+SERVER-SIDE before the action body on the RPC boundary (the path a client
+component import takes), receiving the action's FIRST argument. On failure
+it returns a structured `ActionResult`
 (`{ success: false, fieldErrors, status: 422 }`) the client reads as
 `result.fieldErrors`. The framework ships no validation library; the
 validator is a plain function (or a three-line zod adapter).
@@ -143,25 +141,24 @@ validator is a plain function (or a three-line zod adapter).
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { validateInput } from '@webjsdev/core';
-import { prisma } from '../../../lib/prisma.server.ts';
-
-export const createPost = validateInput(
-  // the action body: runs ONLY when validation passes
-  async (input: { title: string; body: string }) => {
-    const row = await prisma.post.create({ data: input });
-    return { success: true, data: row };
-  },
-  // the validator: receives the action's FIRST argument
-  (input) => {
-    const fieldErrors: Record<string, string> = {};
-    const title = String(input?.title || '').trim();
-    if (!title) fieldErrors.title = 'Title is required';
-    if (String(input?.body || '').length < 10) fieldErrors.body = 'Too short';
-    if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
-    return { success: true, data: { title, body: String(input.body) } }; // coerced input
-  },
-);
+import { db } from '../../../db/connection.server.ts';
+import { posts } from '../../../db/schema.server.ts';
+
+// the validator: receives the action's FIRST argument
+export const validate = (input: any) => {
+  const fieldErrors: Record<string, string> = {};
+  const title = String(input?.title || '').trim();
+  if (!title) fieldErrors.title = 'Title is required';
+  if (String(input?.body || '').length < 10) fieldErrors.body = 'Too short';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
+  return { success: true, data: { title, body: String(input.body) } }; // coerced input
+};
+
+// the action body: runs ONLY when validation passes
+export async function createPost(input: { title: string; body: string }) {
+  const [row] = await db.insert(posts).values(input).returning();
+  return { success: true, data: row };
+}
 ```
 
 Reading the structured failure in a client component is just a property
@@ -187,23 +184,21 @@ result becomes the contract envelope.
 import { z } from 'zod';
 const Schema = z.object({ title: z.string().min(1), body: z.string().min(10) });
 
-export const createPost = validateInput(
-  async (input) => { /* ... */ },
-  (i) => {
-    const r = Schema.safeParse(i);
-    return r.success
-      ? { success: true, data: r.data }
-      : { success: false, fieldErrors: r.error.flatten().fieldErrors };
-  },
-);
+export const validate = (i: any) => {
+  const r = Schema.safeParse(i);
+  return r.success
+    ? { success: true, data: r.data }
+    : { success: false, fieldErrors: r.error.flatten().fieldErrors };
+};
+export async function createPost(input) { /* ... */ }
 ```
 
-To ALSO expose the action as REST with the SAME validator, pass `validate`
-to `expose()` instead of using `validateInput`:
-`expose('POST /api/posts', fn, { validate })`. A `{ success: false,
-fieldErrors }` return becomes a 422 JSON response there; a validator that
-THROWS (the classic `Schema.parse` style) becomes a 400, and a non-envelope
-return transforms the input (back-compat).
+To ALSO expose the action over REST with the SAME validator, put it behind
+a `route.ts` and pass the validator as the `route()` adapter's `{ validate }`
+option: `export const POST = route(createPost, { validate })`. A
+`{ success: false, fieldErrors }` return becomes a 422 JSON response there; a
+validator that THROWS (the classic `Schema.parse` style) becomes a 400, and a
+non-envelope return transforms the input.
 
 ## Add a component
 
@@ -414,7 +409,9 @@ the user-supplied filename as a key; `generateKey` makes an opaque one.
 // modules/avatar/actions/save-avatar.server.ts
 'use server';
 import { getFileStore, generateKey } from '@webjsdev/server';
-import { prisma } from '../../../lib/prisma.server.ts';
+import { eq } from 'drizzle-orm';
+import { db } from '../../../db/connection.server.ts';
+import { users } from '../../../db/schema.server.ts';
 
 export async function saveAvatar(file: File) {
   const key = generateKey(file.name);                // <uuid>.<ext>, safe
@@ -423,7 +420,7 @@ export async function saveAvatar(file: File) {
     await getFileStore().delete(key);
     return { success: false, fieldErrors: { avatar: 'Max 5 MB' }, status: 422 };
   }
-  await prisma.user.update({ where: { id: 'me' }, data: { avatarKey: key } });
+  await db.update(users).set({ avatarKey: key }).where(eq(users.id, 'me'));
   return { success: true, data: { key, contentType } };
 }
 ```

package/resources/agent-docs/testing.md

@@ -74,7 +74,7 @@ packages/
   intellisense/test/plugin/        tsserver plugin tests (.test.mjs)
 test/                              cross-package only
   ssr/                             SSR pipeline (core + server)
-  actions/                         expose() (core + server)
+  actions/                         server actions (core + server)
   serialization/                   json-negotiation (core + server)
   scaffolds/                       full app boots from CLI scaffolds
   blog/                            examples/blog smoke + browser e2e
@@ -108,6 +108,51 @@ cross-package suite (`packages/*/test/` + `test/`). They do NOT walk the in-repo
 apps' own test dirs (`website/test/`, `examples/blog/test/`), so those run from
 each app's OWN `webjs test` script, not the root runner.
 
+### The Bun test matrix (#509)
+
+webjs runs on Node 24+ or Bun (#508). The **Node suite (`npm test`) is the
+source of truth**; a separate, additive **Bun matrix** re-runs the
+runtime-sensitive suite under Bun to catch the long tail of cross-runtime
+incompatibilities (a `node:*` API Bun implements differently, a crypto/stream
+edge case, an error-message-format quirk).
+
+- `node scripts/run-bun-tests.js` (needs `bun` on PATH; `BUN=…` overrides) runs
+  the `node:test` files under `test/`, `packages/core/test/`, and
+  `packages/server/test/` (excluding `browser/`, `e2e/`, the network-bound
+  `vendor/`) file by file via `bun test <file>`, and CLASSIFIES each result:
+  **pass**, **skip(node-only)** (a documented file that asserts Node-only
+  behavior or trips a Bun-test-runner quirk, listed with a reason in the
+  script's `DENYLIST`, its Bun behavior covered elsewhere), **skip(harness)**
+  (a Bun `node:test` compat gap, auto-detected by error signature),
+  **skip(env)** (needs Redis / a DOM), and **genuine fail** (a real Bun
+  failure, which fails the job). Set `WEBJS_BUN_TESTS=<substr,…>` to scope a
+  local run.
+- CI runs it in the `bun` job alongside `test/bun/smoke.mjs` (#508) and
+  `test/bun/listener.mjs` (#511, the listener-shell parity).
+- Two cross-runtime test scripts also run under BOTH runtimes: `test/bun/smoke.mjs`
+  (boot + SSR + TS strip + a server-action RPC) and `test/bun/listener.mjs`
+  (`startServer` over a real socket: SSR + route + SSE + WebSocket). Plain assert
+  scripts (not `node:test`) so the same file runs identically on each runtime.
+
+**Dev hot-reload of server modules (cross-runtime, #514).** webjs's dev server
+re-imports a `route.ts` / `.server.ts` / page module per request with a
+`?t=<timestamp>` query cache-bust to pick up edits. Node honors that query and
+re-imports, so under `node --watch` an edit is picked up live. Bun's ESM loader
+IGNORES the query string and exposes no module-eviction API, so that mechanism
+alone leaves a server-side edit stale on Bun. The CLI closes the gap by
+re-execing `webjs dev` under `bun --hot` on Bun (vs `node --watch` on Node),
+whose file-watching cache invalidation makes the next re-import fresh with no
+restart (`Bun.serve` is reused across hot reloads, so the listener is not
+duplicated). The cross-runtime test `test/bun/dev-hot-reload.mjs` proves the
+edit-picked-up behaviour on BOTH runtimes (and runs as a dedicated CI step on
+Bun). The `api` dev-cache-bust UNIT test asserts the bare server-level `?t=`
+mechanism directly (no supervisor), which Bun ignores by design, so it stays on
+the Bun-matrix denylist; the user-facing hot reload it underpins is covered on
+Bun by the dev-hot-reload script instead. A `--no-hot` flag opts out of the
+supervisor on either runtime (run the server in-process, edits need a manual
+restart). Component / page / layout SOURCE edits already hot-reload on both
+runtimes (the served `.ts`/`.js` is read from disk per request, not imported).
+
 ### In-repo app tests in CI (#342)
 
 Each in-repo app (`website`, `examples/blog`) carries its own test suite under
@@ -116,7 +161,7 @@ its `test/` dir and runs it through its own `webjs test` script (the website's
 not discover these, so a dedicated `.github/workflows/ci.yml` job, **In-repo app
 tests (website + blog)**, runs `npm test --workspace=@webjsdev/website` and
 `npm test --workspace=@webjsdev/example-blog` (with Playwright installed for the
-website browser tests and the Prisma DB prepared for the blog, the same setup
+website browser tests and the SQLite DB prepared for the blog, the same setup
 the `unit` + `e2e` jobs use). It is a required status check, so a regression in
 an app's tests gates the merge. The app test dirs are not walked by the root
 runner, so the framework-package tests never double-run. `docs` and the

package/resources/agent-docs/typescript.md

@@ -6,12 +6,13 @@ run is part of the user-visible workflow, no separate build step:
 
 - **Editor** (VS Code) runs the TypeScript language server continuously. Red-squiggle on wrong types, including non-erasable syntax (see below).
 - **CI** (optional) runs `tsc --noEmit` against `tsconfig.json`. Type-check only. Also catches non-erasable syntax via `erasableSyntaxOnly`.
-- **Dev + prod server** (runtime, both directions): Node 24+'s built-in TypeScript type-stripping handles server-side `.ts` imports automatically (`process.features.typescript === 'strip'`). Browser-bound `.ts` requests go through `module.stripTypeScriptTypes` on the dev server, which performs whitespace replacement: every (line, column) in the source maps to the same position in the stripped output, so no sourcemap needs to be shipped and stack traces are byte-exact. The transform is cached by mtime (~microseconds per cache hit). Implementation backing: Node ships the [`amaro`](https://github.com/nodejs/amaro) package internally, which wraps SWC's WASM TypeScript transform in a position-preserving strip-only mode. If the framework ever needs to run on a non-Node runtime (Bun, Deno) we will install `amaro` directly or an equivalent position-preserving stripper (Sucrase preserves lines but not columns; SWC's strip mode also works).
+- **Dev + prod server** (runtime, both directions): the runtime's TypeScript type-stripping handles server-side `.ts` imports automatically (on Node, `process.features.typescript === 'strip'`; Bun runs `.ts` natively). Browser-bound `.ts` requests go through the pluggable stripper in `packages/server/src/ts-strip.js` (#508) on the dev server, which performs whitespace replacement: every (line, column) in the source maps to the same position in the stripped output, so no sourcemap needs to be shipped and stack traces are byte-exact. The transform is cached by mtime (~microseconds per cache hit). Implementation backing: on **Node 24+** it is the built-in `module.stripTypeScriptTypes` (which itself wraps the [`amaro`](https://github.com/nodejs/amaro) package, SWC's WASM TypeScript transform in position-preserving strip-only mode); on **Bun** (no such built-in) it is `amaro` loaded directly, an `optionalDependency` of `@webjsdev/server`, producing byte-identical output. `WEBJS_TS_STRIPPER=builtin|amaro` forces a backend. Edge runtimes without a filesystem are a separate, later target.
 
 ## TypeScript feature support: erasable only
 
-The framework uses Node 24+'s built-in `module.stripTypeScriptTypes`,
-which only supports **erasable TypeScript**: type annotations,
+The framework strips with Node 24+'s built-in `module.stripTypeScriptTypes`
+(or `amaro` on Bun, the same engine), which only supports **erasable
+TypeScript**: type annotations,
 `interface`, `type`, `declare`, generics, `import type`, `as` casts,
 and `satisfies`. Non-erasable syntax is rejected.
 
@@ -62,15 +63,15 @@ off so you catch the configuration drift before runtime.
 
 ## Import convention
 
-Use explicit `.ts` extensions in imports. Node 24+'s built-in
-type-stripping and the dev server's HTTP handler both key on the
+Use explicit `.ts` extensions in imports. The runtime's type-stripping
+and the dev server's HTTP handler both key on the
 file URL ending in `.ts` / `.mts`. For mixed codebases, `.js` imports
 that point at a `.ts` sibling also resolve in the dev server. Still
 prefer explicit `.ts`.
 
 ```ts
 // modules/posts/queries/list-posts.server.ts
-import { prisma } from '../../../lib/prisma.js';         // JS file unchanged
+import { db } from '../../../db/connection.server.js';   // .js specifier resolves the .ts sibling
 import { formatPost } from '../utils/slugify.ts';         // TS file
 ```
 
@@ -128,6 +129,31 @@ Supported: `Date`, `Map`, `Set`, `BigInt`, `Error`, `undefined`,
 instances come through as plain objects, with prototypes lost and methods
 gone (matches React Server Actions).
 
+#### Catching a non-serializable signature at compile time (`SerializableActionFn`)
+
+The class-instance / function caveat above is a silent runtime surprise: a
+method-valued field or a function argument typechecks fine but vanishes on the
+wire. The opt-in `SerializableActionFn` annotation turns it into a compile-time
+error. webjs actions stay plain `export async function`s (the framework rewrites
+the client import to an RPC stub at runtime, it does not wrap the authored
+function), so the guard is an OPTIONAL type annotation the author applies when
+they want it:
+
+```ts
+import type { SerializableActionFn } from '@webjsdev/core';
+
+export const getUser: SerializableActionFn<(id: number) => Promise<User>> =
+  async (id) => db.user.find(id);
+//  ^ if User carries a method (or any arg is a function), this is a type error
+//    pointing at the offending member, instead of a value that silently loses
+//    it on the wire.
+```
+
+`Serializable<T>` (also exported) maps a fully serializable `T` to itself and a
+non-serializable position (a function / method) to a branded `NonSerializable`
+marker; `SerializableArgs` / `SerializableResult` apply it across an action's
+parameters and (promise-unwrapped) return. All types-only, erased at runtime.
+
 ### API routes: opt in via content negotiation
 
 `route.ts` handlers use standard JSON by default so external consumers

package/src/mcp-docs.js

@@ -333,11 +333,13 @@ const PROMPT_BODIES = {
     '```ts',
     '// modules/<feature>/actions/<name>.server.ts',
     "'use server';",
-    "import { prisma } from '../../../lib/prisma.server.ts';",
+    "import { db } from '../../../db/connection.server.ts';",
+    "import { things } from '../../../db/schema.server.ts';",
     'export async function doThing(input: { name: string }) {',
     "  const name = String(input?.name || '').trim();",
     "  if (!name) return { success: false, error: 'name required', status: 400 };",
-    '  return { success: true, data: await prisma.thing.create({ data: { name } }) };',
+    '  const [row] = await db.insert(things).values({ name }).returning();',
+    '  return { success: true, data: row };',
     '}',
     '```',
     '',

package/src/mcp.js

@@ -36,6 +36,13 @@ import { resolveFrameworkRoots, runSourceTool } from './mcp-source.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 
+// Mirrors packages/server/src/action-config.js. A drift test in
+// packages/mcp/test/mcp.test.mjs asserts these stay in sync with the source.
+/** HTTP verbs an action may declare (mirrors RPC_VERBS in action-config.js). */
+const RPC_VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+/** Reserved config export names in a 'use server' file (mirrors RESERVED_CONFIG in action-config.js). */
+const RESERVED_CONFIG = new Set(['method', 'cache', 'tags', 'invalidates', 'validate', 'middleware']);
+
 /**
  * The four read-only tools. Each takes an optional `{ appDir }` (default the
  * server's cwd) and projects an EXISTING `@webjsdev/server` function's output
@@ -128,7 +135,7 @@ const TOOL_DEFS = [
   {
     name: 'list_actions',
     description:
-      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, and the /__webjs/action/<hash>/<fn> RPC endpoint. Read-only.',
+      'List registered server actions (the .server.{js,ts} files with "use server"): file, exported function name, the /__webjs/action/<hash>/<fn> RPC endpoint, HTTP verb (method), cache config, and boolean flags for tags/invalidates/validate/middleware. Config-only exports (method, cache, tags, invalidates, validate, middleware) are NOT listed as actions. Read-only.',
     inputSchema: APPDIR_SCHEMA,
   },
   {
@@ -148,7 +155,7 @@ const TOOL_DEFS = [
 /**
  * Lexically extract the names exported from a module source. Recognises the
  * common forms a server-action / route file uses without LOADING the module
- * (loading would run its top-level side effects: Prisma init, DB connects).
+ * (loading would run its top-level side effects: DB init, connections).
  *
  *   export async function foo() {}   export function foo() {}
  *   export const foo = ...           export let/var foo = ...
@@ -206,6 +213,67 @@ export function extractRouteMethods(src) {
   return METHODS.filter((m) => exported.has(m));
 }
 
+/**
+ * Lexically extract the HTTP-verb action config declared as reserved sibling
+ * exports in a `'use server'` file (#488). Reads source text only (no module
+ * load) so there are no DB-init side effects.
+ *
+ * Returned shape:
+ *   {
+ *     method: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE',  // default 'POST'
+ *     cache: string | null,    // raw RHS literal when present, else null
+ *     tags: boolean,           // whether the tags export is declared
+ *     invalidates: boolean,    // whether the invalidates export is declared
+ *     validate: boolean,       // whether the validate export is declared
+ *     middleware: boolean,     // whether the middleware export is declared
+ *   }
+ *
+ * @param {string} src
+ * @returns {{ method: string, cache: string|null, tags: boolean, invalidates: boolean, validate: boolean, middleware: boolean }}
+ */
+export function extractActionConfig(src) {
+  // Extract `method` from: export const method = 'GET'  (single/double/backtick)
+  const methodMatch = /\bexport\s+const\s+method\s*=\s*(['"`])([A-Za-z]+)\1/.exec(src);
+  let method = 'POST';
+  if (methodMatch) {
+    const upper = methodMatch[2].toUpperCase();
+    if (RPC_VERBS.has(upper)) method = upper;
+  }
+
+  // Extract `cache` RHS. Single-line: `export const cache = 60` -> '60'
+  // Multi-line object: capture balanced braces across lines.
+  let cache = null;
+  const cacheMatch = /\bexport\s+const\s+cache\s*=\s*/.exec(src);
+  if (cacheMatch) {
+    const rest = src.slice(cacheMatch.index + cacheMatch[0].length);
+    if (rest.startsWith('{')) {
+      // Capture the balanced-brace object (may span lines).
+      let depth = 0;
+      let end = 0;
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '{') depth++;
+        else if (rest[i] === '}') { depth--; if (depth === 0) { end = i; break; } }
+      }
+      cache = rest.slice(0, end + 1).trim();
+    } else {
+      // Single-line: read up to the first newline or semicolon.
+      const lineMatch = /^([^\n;]+)/.exec(rest);
+      if (lineMatch) cache = lineMatch[1].trim();
+    }
+  }
+
+  // Boolean presence of the remaining config names.
+  const exported = new Set(extractExportNames(src));
+  return {
+    method,
+    cache,
+    tags: exported.has('tags'),
+    invalidates: exported.has('invalidates'),
+    validate: exported.has('validate'),
+    middleware: exported.has('middleware'),
+  };
+}
+
 /**
  * The literal URL path for a page/api directory: `blog/[slug]` -> `/blog/[slug]`,
  * the root `.` -> `/`. Route groups `(group)` and `_private` segments drop, the
@@ -274,23 +342,33 @@ export function makeToolRunners(deps) {
     },
 
     async list_actions(appDir) {
-      // `skipExposeLoad` builds the file -> hash maps WITHOUT importing any
-      // `expose()` module, so this stays truly read-only (no Prisma/DB init, and
-      // no stray stdout from a loaded module corrupting the JSON-RPC channel).
-      // The RPC hash is over the file path only, so no module load is needed.
-      const idx = await buildActionIndex(appDir, false, { skipExposeLoad: true });
-      /** @type {Array<{ file: string, fn: string, endpoint: string }>} */
+      // buildActionIndex is a pure file -> hash mapping that imports no module,
+      // so this stays truly read-only (no DB init, and no stray stdout
+      // from a loaded module corrupting the JSON-RPC channel). The RPC hash is
+      // over the file path only, so no module load is needed.
+      const idx = await buildActionIndex(appDir, false);
+      /** @type {Array<{ file: string, fn: string, endpoint: string, method: string, cache: string|null, tags: boolean, invalidates: boolean, validate: boolean, middleware: boolean }>} */
       const actions = [];
       for (const [file, hash] of idx.fileToHash) {
-        let names = [];
+        let src = '';
         try {
-          names = extractExportNames(await readFile(file, 'utf8'));
+          src = await readFile(file, 'utf8');
         } catch {}
+        const names = extractExportNames(src);
+        const config = extractActionConfig(src);
         for (const fn of names) {
+          // Skip reserved config export names: they are config, not callable actions.
+          if (RESERVED_CONFIG.has(fn)) continue;
           actions.push({
             file: relative(appDir, file),
             fn,
             endpoint: `/__webjs/action/${hash}/${fn}`,
+            method: config.method,
+            cache: config.cache,
+            tags: config.tags,
+            invalidates: config.invalidates,
+            validate: config.validate,
+            middleware: config.middleware,
           });
         }
       }

package/resources/agent-docs/ssr-partial-nav-design.md

@@ -1,214 +0,0 @@
-# SSR partial navigation: design note
-
-**Status:** SHIPPED (feature/nested-layout-partial-swap, 2026-05-16).
-The mechanism described below is implemented and tested. This document
-is preserved as the design record. Runtime reference for callers lives
-in `agent-docs/advanced.md` (Client router section) and the framework
-API table in `AGENTS.md`.
-
-**Motivating bug (resolved):** ui-website docs sidenav lost scroll on
-every link click because the docs layout sat 2 levels deep under the
-root layout, beyond `findLayoutShell`'s body-direct-child probe.
-**Previous workaround (now deleted):** `app/docs/layout.ts` saved /
-restored `.docs-sidenav` `scrollTop` via `sessionStorage` on every
-`webjs:navigate` event. Removed in the same PR as the framework fix.
-
----
-
-**What actually shipped vs. what's below:**
-- The recommendation in this doc was `<webjs-frame>` as the primary
-  primitive. During design discussion the decision evolved to make
-  layout-marker discovery **auto-derived from folder structure**, so
-  layout authors write nothing. `<webjs-frame>` ships as the escape
-  hatch for non-layout partial-swap regions (rare).
-- The marker format is `<!--wj:children:<segment-path>-->` comment
-  pairs (Remix v3 lineage), not the `<webjs-frame>`-element approach
-  sketched below.
-- Wire-byte optimization, snapshot cache, keyed DOM diff with live-
-  attribute preservation, and per-segment `<template id="wj-loading:...">`
-  cloning all shipped in the same PR (originally deferred as v2+).
-
-The original `<webjs-frame>`-centric sketch below is preserved as
-historical context.
-
----
-
-## Goal
-
-Preserve the DOM of any layout, at any depth, across same-origin navigations. Re-render only the deepest segment that actually changed.
-
-## Non-goals
-
-- Per-segment data fetching (Remix v3 `<Frame src>` style). Wire model stays one SSR response per nav.
-- React-style reconciler with full keyed-DOM diff inside the swap region. Out of scope for v1, can come later.
-- Parallel routes / intercepting routes (Next.js feature). Separate design.
-
-## Background: how the four references handle this
-
-| Framework | Mechanism | Wire format | Scope decided by |
-|---|---|---|---|
-| **Turbo** | `<turbo-frame id="X">` (flat DOM element) | full HTML response, server may optimize via `Turbo-Frame: X` header | Innermost enclosing `<turbo-frame>` of the click (`closest()`) |
-| **Remix v3** | `<!--rmx:f:id-->...<!--/rmx:f-->` comment markers + per-frame `src` | per-frame HTML or `<template id>` streams | Author-declared `<Frame name="...">` + `rmx-target` on link |
-| **Next.js App Router** | Recursive `FlightRouterState` tuple + per-segment `CacheNode` tree | RSC Flight (`react-server-dom-webpack`) | Server walks the tree, returns from divergence point |
-| **Lit Labs** | `Routes` controller with `outlet()` + child controllers via `RoutesConnectedEvent` | full template re-render (no partial scoping) | N/A (full subtree re-render every nav) |
-
-**Closest fit to webjs's current router:** Turbo. webjs already mirrors Turbo Drive (link interception, body swap, `pushState`, `data-no-router` ≡ `data-turbo="false"`).
-
-## Recommendation
-
-Adopt a Turbo-style frame primitive: `<webjs-frame id="...">`. Layouts that want partial-swap behavior wrap their replaceable region:
-
-```ts
-// app/docs/layout.ts
-import { html } from '@webjsdev/core';
-import { sidenav } from './sidenav.ts';
-
-export default function DocsLayout({ children }) {
-  return html`
-    <div class="docs-grid">
-      ${sidenav()}
-      <webjs-frame id="docs-content">${children}</webjs-frame>
-    </div>
-  `;
-}
-```
-
-### Algorithm: `packages/core/src/router-client.js` delta
-
-Existing `findLayoutShell(body)` stays as a fallback. Add `findActiveFrame(linkEl)`:
-
-```js
-function findActiveFrame(linkEl) {
-  // Walk up through shadow boundaries and into light DOM via composedPath at call site.
-  const frame = linkEl.closest('webjs-frame');
-  return frame ? frame.id : null;
-}
-
-async function navigate(url, event) {
-  const frameId = event ? findActiveFrame(event.target) : null;
-
-  const res = await fetch(url, {
-    headers: frameId ? { 'X-Webjs-Frame': frameId } : {},
-  });
-  if (!res.headers.get('content-type')?.startsWith('text/html')) {
-    // existing fallback: full nav
-    window.location.href = url;
-    return;
-  }
-
-  const html = await res.text();
-  const incoming = Document.parseHTMLUnsafe(html);
-
-  // 1. Frame path: preferred if active frame exists in both.
-  if (frameId) {
-    const target = document.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
-    const source = incoming.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
-    if (target && source) {
-      target.replaceChildren(...source.childNodes);
-      mergeHead(incoming.head);
-      runFrameScripts(target);
-      customElements.upgrade(target);
-      history.pushState({}, '', url);
-      document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url, frameId } }));
-      return;
-    }
-  }
-
-  // 2. Existing layout-shell path (one level deep).
-  const shell = findLayoutShell(document.body);
-  const incomingShell = shell ? findLayoutShell(incoming.body) : null;
-  if (shell && incomingShell && shellsMatch(shell, incomingShell)) {
-    swapShellContent(shell, incomingShell);
-    /* existing path... */
-    return;
-  }
-
-  // 3. Full body swap (existing fallback).
-  document.body.replaceChildren(...incoming.body.childNodes);
-  /* existing path... */
-}
-```
-
-That's the entire detection delta: a `querySelector` keyed by the active frame's id, with the existing logic preserved as fallback.
-
-### `<webjs-frame>` element: ~30 lines
-
-```js
-// packages/core/src/webjs-frame.js
-import { WebComponent, html } from './index.js';
-
-export class WebjsFrame extends WebComponent {
-  static properties = { id: { type: String, reflect: true } };
-  render() { return html`<slot></slot>`; }
-}
-WebjsFrame.register('webjs-frame');
-```
-
-Light DOM (default): no shadow boundary, no slot mechanics. The element exists purely as a swap anchor with an addressable `id`. Children are normal light-DOM children that the router replaces via `replaceChildren`.
-
-### Server side: `X-Webjs-Frame` request header (optional optimization)
-
-When set, the SSR pipeline can return only the matching frame's HTML wrapped in a minimal stub document, skipping the rest of the layout chain. Wire is still plain HTML (no new format). v1 ships **without** this optimization. Full SSR response, client extracts what it needs. The header is forward-compat for the perf pass.
-
-### Head merging
-
-Same as today's `mergeHead`: replace `<title>`, merge `<meta>` tags by `name`/`property`, append new `<link>`/`<style>` elements, dedupe.
-
-### Script handling inside the swap region
-
-Re-execute `<script>` elements that match the existing one-level-shell path's `runScripts` logic. Idempotent registration via `Class.register()` makes this safe. The framework already handles `customElements.define` collisions.
-
-## Edge cases
-
-| Case | Behavior |
-|---|---|
-| Click on a link inside `<webjs-frame>` but `data-no-router` | Full browser navigation (existing semantics) |
-| Click on a link *outside* any frame, both pages share a `findLayoutShell` match | Falls through to existing layout-shell path |
-| Frame in old page but not in new (route change leaves the layout tree) | Frame lookup fails → fall to layout-shell or full body swap. Correct. |
-| Nested `<webjs-frame>`s | Innermost wins: `closest('webjs-frame')` returns the nearest enclosing frame. Mirrors Turbo behavior. |
-| Form submission inside a frame | Same. POST response gets the same frame-extract treatment. (Implement in form-submit path alongside link-click.) |
-| Hash-fragment-only navigation | Existing behavior. No fetch, browser handles. |
-| `data-frame="_top"` on a link | Escapes the enclosing frame, full nav. (Turbo precedent.) |
-
-## What this fixes
-
-- **ui-website docs sidenav scroll**: docs layout wraps content in `<webjs-frame id="docs-content">`. Sidenav lives *outside* the frame. Navigation between `/docs/components/a` → `/docs/components/b` only swaps frame children. The sidenav DOM is untouched, and `<aside>` scroll position is preserved natively. The `sessionStorage` workaround in `app/docs/layout.ts` can be deleted.
-- **Any nested-layout app**: the same primitive works whether the partial-swap region is 2, 3, or 5 levels deep.
-- **Mixed layouts**: pages that don't opt-in fall through to the existing one-level shell detection or full body swap. No regression risk.
-
-## What's deliberately deferred (future passes)
-
-1. **Keyed `data-key` DOM diff inside the frame.** Adopt Remix v3's `diff-dom.ts` algorithm to preserve input values, `<details>` open state, popover state, scroll positions on inner scroll containers across nav. Today's `replaceChildren` is coarse, but fine for v1 since the frame *itself* is preserved (outer scroll, sidenav, etc.).
-2. **`X-Webjs-Frame` server optimization** to avoid re-rendering layouts the client already has.
-3. **Server-pushed partial updates** (turbo-stream equivalent) via `<webjs-stream action="replace" target="...">`. Separate feature, useful for SSE/WebSocket-driven UI.
-4. **Frame-scoped error boundaries.** If a frame fetch 5xxs, render only the frame's `error.ts`, not the whole page.
-
-## Implementation plan
-
-1. **`packages/core/src/webjs-frame.js`**: new file, the custom element.
-2. **`packages/core/index.js`**: export `WebjsFrame`. Re-export `<webjs-frame>` via auto-registration import (so any app that imports `@webjsdev/core` gets it).
-3. **`packages/core/src/router-client.js`**: add `findActiveFrame()`, frame-swap branch in `navigate()`. Preserve existing `findLayoutShell` and full-body fallback.
-4. **`packages/core/src/router-client.js` (form path)**: apply the same frame-extract to form submit responses.
-5. **`packages/server/src/dev.js`**: accept `X-Webjs-Frame` header in dev mode (no-op for v1 but adds the request signal for telemetry).
-6. **Tests:**
-   - `packages/core/test/routing/router-client.test.js`: frame detection, querySelector with various ids, fallback when source frame missing.
-   - `test/e2e/nested-layout-partial-swap.test.mjs`: load `/docs/components/a`, scroll sidenav, click `/docs/components/b`, assert scroll preserved AND only frame children swapped.
-7. **Docs:**
-   - `AGENTS.md`: add `<webjs-frame>` to the public API table.
-   - `agent-docs/advanced.md`: new "Frames" section under the client-router doc.
-   - `docs/` app: a new docs page showing the pattern.
-8. **`packages/cli/templates/`**: none for v1 (frames are opt-in, no scaffold change needed).
-9. **ui-website cleanup**: remove the `sessionStorage` workaround in `app/docs/layout.ts` after the frame lands and tests prove scroll preservation.
-
-## Open questions
-
-1. **Should `<webjs-frame>` ship a `src=""` attribute** for lazy loading like turbo-frame does? Probably yes eventually, but not for v1. The motivating use case is layout-scope, not lazy data.
-2. **Should there be a sub-element registry** (something like `data-layout="docs"` as a shorthand)? Keep it explicit for v1: one mechanism. Consider sugar later.
-3. **`X-Webjs-Frame` header naming.** `Webjs-Frame` (like `Turbo-Frame`) is shorter. Either works, and v1 implements neither for response routing so the bikeshed is deferred.
-
-## References
-
-- Turbo source: `frame_controller.js:132-148` (response parse), `frame_renderer.js:5-16` (swap), `link_interceptor.js:48` (innermost-frame rule)
-- Remix v3 source: `packages/component/src/lib/frame.ts:1134-1146` (comment markers), `diff-dom.ts:124-162` (live-attr preservation list)
-- Next.js source: `packages/next/src/client/components/router-reducer/ppr-navigations.ts:230,251,292,354,486` (cache reuse vs create), `walk-tree-with-flight-router-state.tsx:106-112` (server-side tree walk)
-- webjs current: `packages/core/src/router-client.js` (`findLayoutShell`, single body-children scan)