@webjsdev/cli 0.10.68 → 0.10.69

package/bin/webjs.js

@@ -591,7 +591,7 @@ async function main() {
       superviseDevServer({
         cwd: process.cwd(),
         plan,
-        env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
+        env: { ...process.env, ...plan.env, __WEBJS_DEV_CHILD: '1' },
         onExit: (code) => { killTasks(); process.exit(code); },
       });
       break;

package/lib/create.js

@@ -383,10 +383,15 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // would exec WebJs under Node, silently running the "bun" app on Node).
       // Baking it into the script body means a plain `bun run dev` (or even
       // `npm run dev`) starts on Bun, so a user never has to remember the flag.
-      // The runtime-neutral tooling scripts below (test / db / check / typecheck
-      // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
-      // drizzle-kit, tsc) and forcing `--bun` there buys nothing (and `webjs
-      // test` shells `node --test`, which a `bun --test` would not be).
+      // The db scripts force it too (#1598): `webjs db` runs drizzle-kit and the
+      // seed with the CLI's own runtime, and through the node shebang that was
+      // Node, at 2.5 to 4 times the CPU of the same command on Bun (generate
+      // about 3 CPU-s against 1, migrate 1.2 against 0.5, seed 1 against 0.2,
+      // measured on the Postgres scaffold); on Bun the seed also sees `.env`.
+      // It is the path a Node-less oven/bun image already takes (#570). The
+      // other tooling scripts (test / check / typecheck / doctor / ci) stay
+      // plain `webjs ...`: `webjs test` shells `node --test`, which a
+      // `bun --test` would not be, and `check` costs the same on both.
       // Compile Tailwind from public/input.css to a STATIC public/tailwind.css
       // that app/layout.ts links, so the app is fully styled with JavaScript
       // DISABLED (a real stylesheet, not an in-browser compile). Runs inside the
@@ -419,11 +424,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // from the step list in the `webjs.ci` block below. Runtime-neutral like
       // the other tooling scripts (it spawns `webjs ...` children).
       ci: 'webjs ci',
-      'db:generate': 'webjs db generate',
-      'db:migrate': 'webjs db migrate',
-      'db:push': 'webjs db push',
-      'db:studio': 'webjs db studio',
-      'db:seed': 'webjs db seed',
+      'db:generate': isBun ? 'bun --bun webjs db generate' : 'webjs db generate',
+      'db:migrate': isBun ? 'bun --bun webjs db migrate' : 'webjs db migrate',
+      'db:push': isBun ? 'bun --bun webjs db push' : 'webjs db push',
+      'db:studio': isBun ? 'bun --bun webjs db studio' : 'webjs db studio',
+      'db:seed': isBun ? 'bun --bun webjs db seed' : 'webjs db seed',
     },
     dependencies: {
       // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
@@ -1716,8 +1721,8 @@ ThemeToggle.register('theme-toggle');
 `);
   }
   console.log(`For AI agents, read this before editing:
-  • Read AGENTS.md, then .agents/skills/webjs/SKILL.md. The skill is the guide
-    to building a WebJs app and routes to focused references on demand.
+  • Read AGENTS.md first: it carries the build steps and a worked example of
+    every common pattern. .agents/skills/webjs/ is the deeper reference.
   • This scaffold is a minimal starting point, not a demo to prune. Grow the app
     in place: add routes under app/, components under components/, and features
     under modules/<feature>/, and keep server-only code behind .server.ts.

package/lib/dev-supervisor.js

@@ -78,7 +78,7 @@ export function isBootFile(path) {
  * @param {string[]} opts.argv  `process.argv.slice(1)` (the script path followed by its args), forwarded to the child verbatim.
  * @param {boolean} opts.noHot  Whether `--no-hot` was passed (opt out of the supervisor entirely).
  * @param {boolean} [opts.sourceLocations]  Whether dev source locations are on (`WEBJS_SOURCE_LOCATIONS` / `webjs.dev.sourceLocations`), which puts every app module behind a Bun plugin.
- * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], restartOnChange: boolean, restartFor?: (path: string) => boolean, inPlaceRestartFor?: (path: string) => boolean, watchDirs: string[], watchFiles: string[] }}
+ * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], env?: Record<string, string>, restartOnChange: boolean, restartFor?: (path: string) => boolean, inPlaceRestartFor?: (path: string) => boolean, watchDirs: string[], watchFiles: string[] }}
  *   `inline` runs the server in this process (no reload watcher); `supervise`
  *   spawns `process.execPath` with `args` and `__WEBJS_DEV_CHILD=1` under the
  *   supervisor, which watches `watchDirs` (recursively) and `watchFiles` (at
@@ -101,6 +101,7 @@ export function planDevSupervisor({ isBun, argv, noHot, sourceLocations = false
     return {
       mode: 'supervise',
       args: ['--hot', ...argv],
+      env: BUN_CHILD_ENV,
       restartOnChange: true,
       restartFor: (p) => plugin(p) || isBootFile(p),
       inPlaceRestartFor: isBootFile,
@@ -110,6 +111,20 @@ export function planDevSupervisor({ isBun, argv, noHot, sourceLocations = false
   return { mode: 'supervise', args: [...argv], restartOnChange: true, ...watch };
 }
 
+/**
+ * Extra env for the Bun dev child: turn off Bun's runtime transpiler cache.
+ *
+ * Bun caches the transpile of every source over 50KB on disk, keyed by the
+ * file's CONTENT, with the import paths a `Bun.plugin` `onResolve` returned
+ * baked in. The dev alias resolver (#1575) returns absolute paths, so the
+ * cached output of a large app module pins its `#` imports to the checkout
+ * that first ran `webjs dev`. Any other copy of the same file (a git worktree,
+ * a moved or copied app, a later `webjs start`) then imports from that old
+ * directory: a 500 when it is gone, the other copy's code when it is not. The
+ * variable is read at process start, so it has to be set on the child.
+ */
+const BUN_CHILD_ENV = Object.freeze({ BUN_RUNTIME_TRANSPILER_CACHE_PATH: '0' });
+
 const SERVER_MODULE = /\.server\.m?[jt]s$/;
 const APP_MODULE = /\.m?[jt]s$/;
 

package/lib/resolve-bin.js

@@ -13,6 +13,14 @@
  * 'drizzle-kit/bin.cjs')` throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. The `.` main
  * entry DOES resolve, so resolve that, walk up to the package root (the nearest
  * dir with a package.json), and read the `bin` field, which is version-robust.
+ *
+ * Installed means reachable through a `node_modules/<pkg>` entry in `cwd` or an
+ * ancestor, the lookup Node's resolver does. That is checked BEFORE resolving
+ * because Bun auto-installs: when no `node_modules` sits above `cwd`, Bun's
+ * `require.resolve` fetches an undeclared package into its global cache and
+ * returns that path. Without the check, an app that never installed
+ * @web/test-runner would launch whatever version Bun downloaded instead of
+ * getting the "not installed" remedy.
  */
 import { createRequire } from 'node:module';
 import { readFileSync, existsSync } from 'node:fs';
@@ -27,6 +35,9 @@ import { join, dirname, resolve } from 'node:path';
  * @throws if the package is not installed or has no matching bin
  */
 export function resolveBin(cwd, pkgName, binName) {
+  if (!hasNodeModulesEntry(cwd, pkgName)) {
+    throw new Error(`Cannot find package '${pkgName}' in a node_modules above ${cwd}`);
+  }
   const req = createRequire(join(cwd, 'package.json'));
   // `.` (the main entry) is exported even when subpaths are not.
   let pkgDir = dirname(req.resolve(pkgName));
@@ -40,3 +51,18 @@ export function resolveBin(cwd, pkgName, binName) {
   if (!binRel) throw new Error(`bin '${binName}' not found in ${pkgName}`);
   return resolve(pkgDir, binRel);
 }
+
+/**
+ * @param {string} cwd
+ * @param {string} pkgName
+ * @returns {boolean} whether `node_modules/<pkgName>` exists in cwd or an ancestor
+ */
+function hasNodeModulesEntry(cwd, pkgName) {
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(join(dir, 'node_modules', pkgName))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.68",
+  "version": "0.10.69",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.86",
+    "@webjsdev/server": "^0.8.87",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/rules/workflow.md

@@ -2,23 +2,21 @@
 
 You are working on a WebJs app (AI-first, no-build, web-components-first). This
 file is the WORKFLOW contract (git, tests, review). For HOW to build (routing,
-components, actions, styling, the framework API), read
-`.agents/skills/webjs/SKILL.md`, which routes to focused references on demand.
-Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
+components, actions, styling, the framework API), read `AGENTS.md`; the
+deeper reference set is `.agents/skills/webjs/SKILL.md`. Full hosted docs are
+at https://webjs.dev/docs.
 
 ## Grow the app in place (non-negotiable)
 
-- **Study the shipped examples, then clear them and build.** The scaffold is a
-  starting point with a browsable showcase to learn the real idioms from, plus a
-  database wired up. A full-stack app ships a UI feature gallery (`app/features/`,
-  `app/examples/todo`); the api template ships a backend-features showcase
-  (`app/api/features/`), with logic in `modules/`. Building a real app: study the
-  parts that match your task (the skill teaches the same and SURVIVES the clear),
-  run `npm run gallery:clear` to shed the showcase (it keeps the agent skill and
-  the database wiring, and resets to a clean base), then regenerate the database
-  and grow the app in place under `app/`, `components/`, and `modules/<feature>/`.
-  `AGENTS.md` carries the full template-specific build playbook and the order to
-  follow.
+- **Clear the showcase, then build.** The scaffold is a starting point with a
+  browsable demo showcase plus a database wired up. A full-stack app ships a UI
+  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
+  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
+  Building a real app: run `npm run gallery:clear` to shed the showcase (it
+  keeps the agent docs and the database wiring, and resets to a clean base),
+  then regenerate the database and grow the app in place under `app/`,
+  `components/`, and `modules/<feature>/`. `AGENTS.md` carries the
+  template-specific build steps and the order to follow.
 - **Use the wired-up database (Drizzle), never JSON files.** For any data the app
   stores, define a Drizzle table in `db/schema.server.ts`, then
   `npm run db:generate` and `npm run db:migrate`. Never use a JSON file, a
@@ -26,9 +24,8 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 - **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
   route, middleware, metadata routes). Browser-safe helpers go in `lib/utils/`,
   feature logic in `modules/`, server-only code behind `.server.ts`.
-- **For a UI app, render and LOOK before calling it done.** Define design tokens
-  in `app/layout.ts` with a palette that fits the app
-  (`.agents/skills/webjs/references/styling.md` is the guide), then open every
+- **For a UI app, render and LOOK before calling it done.** Give the design
+  tokens in `public/input.css` a palette that fits the app, then open every
   route you changed in a real browser and play through its states.
   `npm run check` and `npm run typecheck` pass even when a layout collapses, so
   the browser is the real check.

package/templates/.agents/skills/webjs/SKILL.md

@@ -9,6 +9,8 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
+In a scaffolded app, `AGENTS.md` carries the build steps and a worked example of every common pattern (pages, layouts, form-bound actions with validation, queries, owner-scoped CRUD, `createAuth`, a component with signals, a test). Build from it first, and come here for a surface it does not show.
+
 This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
@@ -44,7 +46,6 @@ Rows point rather than explain. The reference is the authority on the rule, and
 | add a URL, static or with a dynamic segment | a file at `app/<path>/page.ts`, `[id]` for a param | registering the route in a table or config | `references/routing-and-pages.md` | `app/features/routing` |
 | abandon a render because something is missing or not allowed | throw `notFound()` / `forbidden()` / `unauthorized()` | returning an error object and branching in the template | `references/routing-and-pages.md` | `app/features/boundaries` |
 | set a page's title, description, or social preview | `export const metadata` or `generateMetadata()` | writing `<head>` tags in the page | `references/routing-and-pages.md` | `app/features/metadata` |
-| give the app its own favicon, home-screen icon and manifest | replace the placeholder `app/icon.svg` with a simple symbol for the app in its colours, add `app/apple-icon.png`, edit `app/manifest.webmanifest` | leaving the scaffold placeholder, or a hand-written `<link rel="icon">` | `references/routing-and-pages.md` (App icon and manifest) | `app/icon.ts` |
 | make part of the page respond to a click or hold state | a `WebComponent` custom element | expecting the page's own markup to hydrate | `references/components.md` | `app/features/components` |
 | render a keyed list, or swap one node when state changes | `repeat()` / `watch()` from `/directives` | re-rendering the component or diffing by hand | `references/components.md` | `app/features/directives` |
 | get server data into a component's first paint | `async render()` awaiting an action | fetching in `connectedCallback`, which SSR never calls | `references/components.md` | `app/features/async-render` |

package/templates/.agents/skills/webjs/references/runtime.md

@@ -44,6 +44,8 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 
 Bun keeps ONE dev server process for the whole session (#1575), so it gets the refresh. `bun --hot` re-runs the CLI on a change; the first run's server owns the process (its listener, live-reload stream, watchers and analysis caches) and a re-run only tells it the module registry was reset, so nothing is started twice and memory stays flat over hundreds of edits (it used to grow about 25 MB an edit until `bun --hot` stopped reloading). The app's modules load through a `Bun.plugin` that reads them fresh, and its `#` imports resolve through the app's own `imports` map, because Bun keeps the old source of a file that was replaced (an atomic save) and a stale directory listing for a new file next to a `*.server.*` module. So `bun --hot` no longer sees app edits itself, and the dev server asks it for a registry reset after an edit to a module some other module imports, a new module, or a `*.server.*` module, all without a process restart. A page, layout or route handler nothing imports needs no reset: the dev re-import is keyed by the file's content, so an unchanged file reuses its loaded module (no new module instance per request) and an edited one is a new import. `instrumentation.*` and `env.*` run once per process, so an edit to one restarts the server on both runtimes. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
 
+After a reset, app code that imports `@webjsdev/server` gets a fresh copy of the package while the first run's server keeps handling requests. Everything the two copies must agree on (the request `auth()`, `cookies()` and `headers()` read, the action signal, the seed collector and action identity, the default cache store, sessions, broadcast clients) lives in process-wide state keyed by `Symbol.for`, so a signed-in page and the `'use server'` queries it calls still see the request after any number of edits (#1590). Before that fix, `auth()` without an explicit request returned `null` in app code after the first edit.
+
 **`webjs dev` and `webjs start` serve the directory they are started in, and refuse anywhere else (#1526).** Run them in the app directory, the one holding `app/`. In a workspace (`apps/web` under a root `package.json` with `workspaces`) that is the member, even when the CLI is hoisted to the root `node_modules`: the hoisted bin and the Bun `--hot` child both keep the directory they were started in. Started where there is no `app/` (the workspace root, or a subdirectory such as `app/` itself), both exit 1 before any `before` step runs, naming the app to start (`cd apps/web && webjs dev`), instead of booting a server that answers 404 for every route.
 
 **`webjs dev` does not stay down (#1521).** The supervisor and the server's own watcher handle every watcher error: a file in a watched dir the dev server cannot read or watch (the 0600 temp file `sed -i` creates when another user runs it, a file removed mid-scan) logs one `file watcher skipped <path> (EACCES)` warning and both keep running, where `node --watch` used to crash and leave the preview dead. Edits that REPLACE a file (`sed -i`, an editor saving through a temp file, an atomic write) are heard every time, however often the same file is replaced (#1529: on Linux under Node the watchers watch each directory, since Node 24's own recursive watcher stopped hearing a file after its first replacement). A server process that crashes is started again on the next file change, or by itself after a backoff of 0.5s growing to 10s for repeated crashes. On Bun the supervisor restarts the server only for an `instrumentation.*` / `env.*` edit (#1575), and otherwise does only the crash recovery. An agent writing files the way an AI editor does (bursts, partial writes, syntax errors then fixes, renames, deletes, atomic writes) is exercised by `scripts/dev-reload-stress.mjs` (`node scripts/dev-reload-stress.mjs <appDir> <url>` against any running app). Stopping `webjs dev` (Ctrl-C, SIGTERM) stops the server child too, and a child whose supervisor was killed outright exits on its own, so nothing is left holding the port.

package/templates/.claude/hooks/nudge-uncommitted.sh

@@ -30,6 +30,13 @@ fi
 # Read stdin so we don't break Claude Code's hook contract.
 cat /dev/stdin >/dev/null 2>&1 || true
 
+# A repository with no commit yet is a first build from the scaffold: the whole
+# build is one logical unit (CLAUDE.md), committed once at the end, so nudging
+# mid-build would only split it. The Stop hook still asks for that commit.
+if ! git rev-parse --verify -q HEAD >/dev/null 2>&1; then
+  exit 0
+fi
+
 CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
 
 if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then

package/templates/AGENTS.md

@@ -1,82 +1,52 @@
 # AGENTS.md for {{APP_NAME}}
 
-This is a WebJs app: AI-first, web-components-first, buildless, and
-progressively enhanced. Read this whole file before you edit anything, then
-follow it. The steps here are required, not optional.
-
-## Gather context BEFORE you build (required)
-
-WebJs is its own framework. It is not React, Next, or Lit, so writing code from
-that muscle memory produces broken WebJs code. Before you write or change
-anything, gather context from these sources. Do not skip a step to save time.
-This is what separates a working app from a broken one.
-
-1. **Read the skill.** Start with `.agents/skills/webjs/SKILL.md`, then load the
-   `references/*.md` files it routes to for the surface you are touching. The
-   skill is the guide to building a WebJs app: it helps you choose the right
-   layer, reach for the right export, and avoid the mistakes Next.js or Lit
-   habits cause. Reading it is never wasted work: it survives the
-   gallery-clearing step in the playbook below.
-2. **Study the shipped examples, then build on a clean slate.** The template
-   playbook below says what ships and the exact order to follow. The workflow
-   rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
-   too.
-3. **Read the framework source for exact contracts.** WebJs is 100% buildless
-   native ES modules, so the source you run IS the source you read. When you
-   need a precise API signature or behavior, open the package source under
-   `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://webjs.dev/docs.
+This is a WebJs app: server-rendered pages, web components for interactivity,
+server actions, Drizzle, and no build step. WebJs is its own framework, not
+React, Next.js or Lit, so write it from the patterns in this file rather than
+from that memory. Read this whole file before you edit anything.
 
 {{PLAYBOOK}}
 
-## Type everything (all templates)
-
-Full-stack type safety is what the `.server.ts` boundary buys you: a client
-component importing a server action resolves to that action's real signature at
-type-check time, with no build step and no code generation in between. So
-DERIVE the type at every boundary instead of widening it:
-
-- A database row: `export type Todo = typeof todos.$inferSelect` in
-  `db/schema.server.ts` (`$inferInsert` for a write), carried into a
-  browser-shipped component with `import type` (erased before it reaches the
-  browser, so it does not trip the server-import boundary).
-- An action's input: a named `interface`. Its result: `ActionResult<T>`.
-  Narrow with `if (result.success && result.data)`.
-- Routing files: `PageProps<'/blog/[slug]'>`, `LayoutProps`,
-  `RouteHandlerContext`, all from `@webjsdev/core`. Run `npx webjsdev types`
-  for the typed `Route` union and per-route `params`.
-- A reactive property: `prop<Student>(Object)`, `prop<Tag[]>(Array)`.
-
-Never reach for `any` or a loose `as any` cast, and do not reach for `unknown`
-either just because it looks safer. `unknown` is right for a payload nothing
-has vouched for yet, narrowed on the very next line (a `route.ts` `await
-req.json()`, an action's `export const validate` or a validator it delegates
-to, a `catch` binding), and for a parameter of YOUR OWN helper that forwards
-into an `html` template hole (a hole renders a string, a number, a
-`TemplateResult`, or an array of those, so `TemplateResult` alone is too
-narrow). That second case is about a value you accept, never one the framework
-already types. Everywhere else it is a missing type, not a safe one: `unknown`
-that survives into a return type, a component prop, a layout's `children`, or
-an action signature is the shape to fix.
-Nothing enforces this (both are valid TypeScript, so `webjs check` and `tsc`
-pass either way), which is exactly why it is written down. The full ladder,
-with an end-to-end example, is in
-`.agents/skills/webjs/references/typescript.md`.
-
-Keep server-only code (database drivers, secrets, `node:*` builtins) in
-`.server.ts` modules. There are exactly two kinds:
-
-- A `.server.ts` file WITH `'use server';` as its first line is a server
-  action: WebJs exposes its exported async functions to browser code as RPC
-  calls, so browser modules may import it directly.
-- A `.server.ts` file WITHOUT `'use server'` is a server-only utility:
-  importing it from a page, layout, or component CRASHES in the browser at
-  module load. Reach it only from `'use server'` actions, `route.ts` handlers,
-  or middleware. Never add `'use server'` to a file only other server code
-  imports (the DB connection, the schema).
-
-## Data (all templates)
-
-Use the wired-up database (Drizzle) for every piece of data the app stores;
-the playbook above has the modeling step. Never store app data in a JSON file,
-an in-memory array, or localStorage.
+## Rules that hold everywhere
+
+- **Type every boundary from its source.** A row is
+  `typeof posts.$inferSelect` (exported from `db/schema.server.ts`, carried
+  into browser code with `import type`), an action's input is a named
+  `interface`, a routing file uses `PageProps<'/posts/[id]'>` / `LayoutProps` /
+  `RouteHandlerContext` from `@webjsdev/core`, and a component prop that holds
+  an object is `prop<Post>(Object)`. Never reach for `any` or `as any`, and
+  keep `unknown` for an untrusted payload you narrow on the next line.
+- **Server-only code stays behind `.server.ts`.** A file WITH `'use server'`
+  exposes its exported async functions as actions; a file WITHOUT it is a
+  server-only utility that only other server code may import. Never add
+  `'use server'` to a file only server code imports (the DB connection, the
+  schema).
+- **Store data with Drizzle** in the wired-up database (`db/`), never in a
+  JSON file, an in-memory array or Map, or localStorage. Every schema change is
+  `npm run db:generate` then `npm run db:migrate`, and the generated
+  migrations are committed.
+- **TypeScript is erasable:** no `enum`, no `namespace`, no constructor
+  parameter properties, no decorators. Never put a backtick inside an
+  `html` template body, even in a comment.
+- **Errors tell you the fix.** `npm run check` and `npm run typecheck` name
+  the file, the rule and the fix; do what they say rather than searching.
+
+## Git
+
+Commit per logical unit (CLAUDE.md has the rule). When you build a whole app
+from a spec in one session, the build is one unit: work on a feature branch
+(commits to `main` are refused), and commit once at the end after the checks
+pass (`git add -A && git commit -m "<imperative subject>"`). Team workflow
+(pull requests, CI, worktrees) is in `.agents/rules/workflow.md`.
+
+## When you need more
+
+The reference set is `.agents/skills/webjs/` (`SKILL.md` routes to
+`references/*.md`). Open one only for a surface this file does not show:
+streaming and Suspense (`client-router-and-streaming.md`), optimistic UI
+(`optimistic-ui.md`), caching, rate limits, file uploads, env vars
+(`built-ins.md`), OAuth providers and sessions (`auth-and-sessions.md`),
+browser and e2e tests (`testing.md`), deeper component topics such as slots,
+shadow DOM, context and directives (`components.md`). The exact framework
+source is under `node_modules/@webjsdev/*`, and the hosted docs are at
+https://webjs.dev/docs.

package/templates/CLAUDE.md

@@ -3,21 +3,19 @@
 # Committing per logical unit (this OVERRIDES Claude Code's default)
 
 Claude Code's built-in default is to NEVER commit unless the user explicitly
-asks. **For this project that default does NOT apply.** Commit and push per
-logical unit (one feature, one fix, one rename, one doc rewrite) as soon as it
-is complete, WITHOUT being asked. Do not save all the work for one commit at the
-end. A finished implementation with zero commits is a mistake here, because git
-history is the user's revert and cherry-pick safety net.
+asks. **For this project that default does NOT apply.** Commit per logical
+unit (one feature, one fix, one rename, one doc rewrite) as soon as it is
+complete and its checks pass, WITHOUT being asked, then push when there is a
+remote. Git history is the user's revert and cherry-pick safety net.
 
-- After each completed unit whose tests pass, `git add` the related files and
-  `git commit` with an imperative subject under 72 chars, then push. If 5+ files
-  span more than one concern, you already waited too long.
-- Never commit to `main`. Work on a feature branch (the
-  `.claude/hooks/guard-branch-context.sh` hook enforces this).
-- No AI-attribution trailers (`Co-Authored-By`, `Generated by`).
+- Building a whole app from a spec in one session is ONE unit: build it,
+  verify it, then commit once. Later changes are one commit each.
+- Never commit to `main`. Work on a feature branch (the pre-commit hook
+  refuses `main`).
+- Imperative subject under 72 characters. No AI-attribution trailers
+  (`Co-Authored-By`, `Generated by`).
 
-See AGENTS.md "Git workflow" for the full contract. Two hooks back this up: the
-`.claude/hooks/nudge-uncommitted.sh` PostToolUse hook reminds you while
-uncommitted changes pile up during work, and the
-`.claude/hooks/commit-before-stop.sh` Stop hook stops you from ending a turn
-with a pile of uncommitted work still on a feature branch.
+Two hooks back this up: `.claude/hooks/nudge-uncommitted.sh` reminds you while
+uncommitted changes pile up on a branch that already has commits, and
+`.claude/hooks/commit-before-stop.sh` stops you from ending a turn with
+uncommitted work on a feature branch.

package/templates/CONVENTIONS.md

@@ -1,9 +1,9 @@
 # Conventions for {{APP_NAME}}
 
-The conventions for building a WebJs app live in the agent skill. **Read
-`AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (it routes to focused
-references under `.agents/skills/webjs/references/`, loaded on demand). This file
-is the short version.
+The conventions for building a WebJs app live in **`AGENTS.md`**, which shows
+every common pattern as a worked example. The deeper reference set is
+`.agents/skills/webjs/` (`SKILL.md` routes to `references/*.md`), for the rarer
+surfaces. This file is the short version.
 
 ## The essentials
 
@@ -17,13 +17,12 @@ is the short version.
 - **Use the wired-up database (Drizzle).** Define real models in
   `db/schema.server.ts`, then `npm run db:generate` and `npm run db:migrate`.
   Never persist to a JSON file, an in-memory array or Map, or localStorage.
-- **The scaffold ships a showcase to learn from.** A full-stack app ships a UI
-  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
-  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
-  When you build a real app, study the parts that match your task (the skill
-  teaches the same and survives the clear), run `npm run gallery:clear` to shed
-  the showcase, then grow the app in place. `AGENTS.md` has the full
-  template-specific playbook.
+- **The scaffold ships a demo showcase.** A full-stack app ships a UI feature
+  gallery (`app/features/`, `app/examples/todo`); the api template ships a
+  backend-features showcase (`app/api/features/`), with logic in `modules/`.
+  When you build a real app, run `npm run gallery:clear` first to shed the
+  showcase, then grow the app in place. `AGENTS.md` has the template-specific
+  build steps.
 - **Derive types at every boundary.** Rows from `$inferSelect`, action inputs
   from an `interface`, routing files from `PageProps` / `LayoutProps`. Never
   `any`, and never `unknown` where a real type exists.

package/templates/partials/agents-playbook-fullstack.md

@@ -1,135 +1,571 @@
-## Build a full-stack app (default template)
-
-This scaffold ships a browsable feature gallery to learn from: single-concept
-demos under `app/features/`, the `app/examples/todo` app, and an example design
-system under `components/ui/`, with logic in `modules/`. Build in this order.
-
-### 1. Study the gallery, then clear it
-
-Read the demos under `app/features/` (and `app/examples/todo`) that match what
-you are building, so you copy the real idiom: server actions, queries,
-optimistic UI, component hydration, design tokens. Then run
-`npm run gallery:clear` to shed the whole gallery and reset `app/page.ts` and
-`app/layout.ts` to a blank slate. The clear also removes the example
-`components/ui/` primitives, the demo `todos` table, and the demo migrations;
-it keeps the agent skill, the database wiring, and `lib/utils/cn.ts` (needed by
-`npx webjsdev ui add`). The skill teaches the same patterns, so the gallery is
-a runnable copy you study first, not something you lose.
-
-### 2. Model the data
-
-Define real models in `db/schema.server.ts`, then run `npm run db:generate` and
-`npm run db:migrate` (required after the clear, which removed the demo table and
-migrations). Write a seed script at `db/seed.server.ts` and run
-`npm run db:seed` so list and detail pages render real rows while you build,
-instead of empty states. Put reads in `modules/<feature>/queries/*.server.ts`
-and writes in `modules/<feature>/actions/*.server.ts`, one function per file.
-
-### 3. Build a token-based design system
-
-Full reference: `.agents/skills/webjs/references/styling.md`.
-
-- Define your color tokens as CSS custom properties in `app/layout.ts`, each
-  written ONCE with the native CSS `light-dark(LIGHT, DARK)` function, so light
-  and dark modes come from one declaration.
-- Define at least: `--background`, `--foreground`, `--card`, `--primary`,
-  `--secondary`, `--muted`, `--muted-foreground`, `--accent`, `--border`,
-  `--ring`, `--destructive`. Add the matching `*-foreground` pair for each
-  surface token you use, following the styling guide's reference palette.
-- Consume colors ONLY as token utilities: `bg-background`, `text-foreground`,
-  `bg-card`, `border-border`, `text-primary`, `text-muted-foreground`,
-  `bg-destructive`.
-- NEVER put a raw un-themed Tailwind color (`red-500`, `blue-600`, `gray-100`)
-  on an element or a `@webjsdev/ui` helper.
-- Add an inline theme-detection script in the layout `<head>` so the first
-  paint matches the saved theme with no flash.
-
-### 4. Use the UI kit, do not hand-roll primitives
-
-Pull primitives with `npx webjsdev ui add <name>`; the source is copied into
-`components/ui/`, so you own it fully and can add, remove, restructure, or theme
-it however your app needs. Do NOT guess a helper or tag signature. Inspect the
-copied file `components/ui/<name>.ts`, or run
-`npx webjsdev ui view <name>`, for the exact exported names, variants, and
-sizes. The kit has two tiers:
-
-- **Tier 1, class helpers** for static primitives (button, card, input, badge,
-  native-select, textarea). Spread the helper onto a native element, for example
-  `class=${buttonClass({ variant: 'outline', size: 'sm' })}`.
-- **Tier 2, custom elements** for stateful controls and overlays (`<ui-tabs>`,
-  `<ui-dialog>`, `<ui-dropdown-menu>`, `<ui-tooltip>`, sonner toasts). Use the
-  registered tag; it owns its ARIA, focus trap, and keyboard navigation out of
-  the box. Never hand-author a tab strip or a modal when a Tier-2 element
-  covers it.
-
-Full reference: `.agents/skills/webjs/references/ui-kit.md`.
-
-### 5. Build a multi-page app (MPA), not a single page
-
-Structure the product as real routes, not one page that swaps client state:
-
-- `/` a home or overview page.
-- `/<resource>` a list page with search, filters, sorting, and a create form or
-  modal.
-- `/<resource>/[id]` a detail page for one item.
-- a couple of additional feature pages as the product needs.
-
-Give `app/layout.ts` a navbar that links the main pages, pinned with
-`position: fixed` (never `position: sticky`, which flickers on iOS during a
-client-router navigation), and reserve its height on the content with a
-`--header-height` offset. In a list or table, clicking a row or card navigates
-to that item's detail page. Wrap each row action button (edit, delete, status)
-so its handler calls `event.stopPropagation()`, letting the button run its own
-action without also triggering the row navigation.
-
-### 6. Build components for interactivity
-
-Pages and layouts (`app/**/page.ts`, `app/**/layout.ts`) are server-only HTML
-generators, so put every interactive behavior inside a `WebComponent` custom
-element. Declare a component's reactive properties in the base-class factory,
-never as a class-field initializer (`items = []` clobbers the reactive
-accessor). Use the shorthand for primitives
-(`extends WebComponent({ name: String, count: Number, open: Boolean })`) and the
-`prop<T>()` helper for typed objects and arrays
-(`extends WebComponent({ items: prop<Item[]>(Array), user: prop<User>(Object) })`).
-
-### 7. Verify before you call it done
-
-Run `npm run ci` and fix what it reports. It is one command for every gate,
-the step list declared in `package.json` under `webjs.ci`, with a result line
-per step:
-
-- `webjs check` (correctness: no browser-import or boundary violation).
-- `webjs doctor` (project health). It fails on whatever `package.json`
-  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
-  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
-- `webjs typecheck` (zero type errors).
-- A dependency audit.
-- The server, browser, and e2e test layers for the features you built.
-
-The GitHub workflow runs the same list, so a green local run predicts CI.
-While iterating, `npm run ci -- --only Tests` runs one layer. Then
-`npm run css:build` (compile Tailwind).
-
-Then boot `npm run dev`, confirm every page route returns HTTP 200, and open
-every route you changed in a real browser and play through its states: `check`
-and `typecheck` pass even when a layout collapses, so the browser is the real
-check for UI work.
+## Build an app (full-stack template)
+
+### Build steps
+
+Everything a typical app needs (pages, forms, validation, auth, owner-scoped
+CRUD, a component, Drizzle) is in this file, so build straight from it instead
+of exploring. Write in a few large steps (one shell heredoc or one write per
+group of files), not one file per turn.
+
+1. Branch, clear the demo gallery, and add the UI kit, in one command:
+   `git checkout -b feat/<name> && npm run gallery:clear && npx webjsdev ui add button input label textarea native-select card badge`.
+   The gallery (`app/features/`, `app/examples/`, the demo `modules/`) is only a
+   demo: never read it, everything it teaches is below.
+2. Write `db/schema.server.ts` (replace the whole file: its `users` table is a
+   placeholder), then `npm run db:generate && npm run db:migrate`.
+3. Write every `modules/` file (auth, queries, actions, components, utils).
+4. Write `app/layout.ts` and `app/page.ts` (replace both whole; no need to
+   read them first), every other page, `app/not-found.ts`, and
+   `test/<feature>/*.test.ts`.
+5. `npm run check && npm run typecheck && npm run test:server`, and fix what
+   they report.
+6. Walk the app once in a real browser. `curl` cannot submit a bound form
+   (the form carries a hidden action field), so use Playwright, which is
+   installed (if Chromium is missing: `npx playwright install chromium`).
+   First write one script, `walk.mjs` in the app folder, that signs up and
+   drives each feature once with `page.getByLabel(...)` and
+   `page.getByRole('button', { name })`. With JavaScript on, a submit is
+   applied in place, so wait for its outcome (`await page.waitForURL(...)` or
+   `await page.getByText('...').waitFor()`), never a fixed timeout. Save a
+   phone-width and a desktop-width screenshot under `/tmp`. Then start
+   `PORT=<port> npm run dev > dev.log 2>&1 &` (`*.log` is gitignored), run
+   `node walk.mjs`, look at the screenshots, fix what the walk shows in the
+   app, stop the server you started, and delete `walk.mjs`.
+7. Commit (see Git below).
+
+### How WebJs works
+
+- **Pages and layouts run only on the server.** They return `html` and never
+  hydrate: an `@click` in a page does nothing. Interactivity lives in a
+  `WebComponent` custom element; a page imports the component file to
+  register it and writes its tag.
+- **`*.server.ts` is the server boundary.** With `'use server';` as the first
+  line, its exported async functions are server actions: a page calls them
+  directly on the server, a component calls them over RPC (the import becomes
+  a typed stub). WITHOUT `'use server'` the file is a server-only utility (the
+  DB, secrets, `node:*`, `createAuth`): import it only from other `.server.ts`
+  files, `route.ts` or `middleware.ts`, never from a page, layout or component
+  (it crashes the browser). So a page reaches data and the session only
+  through `'use server'` queries.
+- **Forms post to actions.** `<form action=${someAction}>` is the whole wiring
+  (no `method`, no `fetch`, works without JavaScript; with JavaScript the router
+  applies the result in place). The action receives the `FormData` and returns:
+  `{ success: true, redirect: '/path' }` (a 303 to that path), or
+  `{ success: false, error?, fieldErrors?, status? }`, which re-renders the
+  same page (422) with the result on the page's `actionData`;
+  `actionData.values` already holds every submitted text field. A returned
+  `Response` (for example from `signIn`) is sent as is.
+- **Control flow:** `notFound()` and `redirect(url)` from `@webjsdev/core`
+  throw; use them in pages, layouts and form actions. In a `route.ts` return a
+  `Response` instead, and in an action called over RPC return
+  `{ success: false, error }` instead of throwing.
+
+### File map
+
+```
+app/layout.ts                 root layout: the only file that writes <head> content
+app/page.ts                   /
+app/<seg>/[id]/page.ts        dynamic route; params.id is a string
+app/<seg>/[id]/edit/page.ts   nested route
+app/not-found.ts              the 404 page, also rendered by notFound()
+app/<path>/route.ts           HTTP endpoint: export async function GET(req, { params })
+modules/<feature>/queries/<verb-noun>.server.ts   reads, 'use server', one function per file
+modules/<feature>/actions/<verb-noun>.server.ts   writes, 'use server', one function per file
+modules/<feature>/components/<tag>.ts             one custom element per file
+modules/<feature>/utils/*.ts, types.ts            pure browser-safe helpers and types
+lib/utils/*.ts                app-wide browser-safe helpers
+db/schema.server.ts           tables; `db` is in db/connection.server.ts
+test/<feature>/*.test.ts      server tests (node:test), run by `npm run test:server`
+```
+
+Import app files through the `#` root alias with the `.ts` extension:
+`import { db } from '#db/connection.server.ts'`.
+
+### Worked example: a signed-in CRUD feature
+
+Each block is a whole file. Copy the shape and rename (`posts` becomes your
+resource). Child resources (a project's tasks) follow the same pattern: the
+child table references the parent with `onDelete: 'cascade'`, and every query
+and action checks that the parent belongs to the signed-in user.
+
+```ts
+// db/schema.server.ts (columns.server.ts provides table, pk, text, integer, createdAt, index)
+import { defineRelations } from 'drizzle-orm';
+import { table, pk, text, integer, createdAt, index } from './columns.server.ts';
+import { POST_STATUSES } from '#modules/posts/types.ts';
+
+export const users = table('users', {
+  id: pk(),
+  email: text().notNull().unique(),
+  passwordHash: text().notNull(),
+  createdAt: createdAt(),
+});
+export const posts = table('posts', {
+  id: pk(),
+  ownerId: integer().notNull().references(() => users.id, { onDelete: 'cascade' }),
+  title: text().notNull(),
+  body: text().notNull().default(''),
+  status: text({ enum: POST_STATUSES }).notNull().default('draft'),
+  publishOn: text(), // 'YYYY-MM-DD' from <input type="date">, or null
+  createdAt: createdAt(),
+}, (t) => [index(t.ownerId)]);
+export const relations = defineRelations({ users, posts }, () => ({}));
+export type User = typeof users.$inferSelect;
+export type Post = typeof posts.$inferSelect;
+```
+
+```ts
+// modules/posts/types.ts (browser-safe: components import this, never the schema)
+export const POST_STATUSES = ['draft', 'review', 'published'] as const;
+export type PostStatus = (typeof POST_STATUSES)[number];
+export interface StatusCounts { draft: number; review: number; published: number; total: number }
+```
+
+```ts
+// lib/utils/form.ts
+import { html } from '@webjsdev/core';
+import { labelClass } from '#components/ui/label.ts';
+import { inputClass } from '#components/ui/input.ts';
+
+/** What a failed form action hands back to the page as `actionData`. */
+export interface FormState { error?: string; fieldErrors?: Record<string, string>; values?: Record<string, string> }
+export const isEmail = (s: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
+export const str = (fd: FormData, k: string) => String(fd.get(k) ?? '').trim();
+export const toId = (v: unknown) => { const n = Number(v); return Number.isInteger(n) && n > 0 ? n : null; };
+
+/** A labelled input with its server error under it and the typed value kept. */
+export function field(o: { label: string; name: string; type?: string; value?: string; error?: string; required?: boolean }) {
+  return html`
+    <div class="grid gap-1.5">
+      <label for=${o.name} class=${labelClass()}>${o.label}</label>
+      <input id=${o.name} name=${o.name} type=${o.type ?? 'text'} value=${o.value ?? ''} ?required=${o.required}
+        aria-invalid=${o.error ? 'true' : 'false'} class=${inputClass()}>
+      ${o.error ? html`<p class="text-sm text-destructive">${o.error}</p>` : ''}
+    </div>`;
+}
+```
+
+Auth uses the built-in `createAuth` (a signed session cookie) and `node:crypto`
+scrypt. No extra package is needed.
+
+```ts
+// modules/auth/password.server.ts
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+const scryptAsync = promisify(scrypt);
+export async function hashPassword(pw: string) {
+  const salt = randomBytes(16).toString('hex');
+  return salt + ':' + ((await scryptAsync(pw, salt, 64)) as Buffer).toString('hex');
+}
+export async function verifyPassword(pw: string, stored: string) {
+  const [salt, key] = stored.split(':');
+  return timingSafeEqual((await scryptAsync(pw, salt, 64)) as Buffer, Buffer.from(key, 'hex'));
+}
+```
+
+```ts
+// modules/auth/auth.server.ts (server-only: no 'use server')
+import { createAuth, Credentials } from '@webjsdev/server';
+import { db } from '#db/connection.server.ts';
+import { verifyPassword } from './password.server.ts';
+
+const secret = process.env.AUTH_SECRET;
+if (!secret) throw new Error('AUTH_SECRET is not set');
+export const { auth, signIn, signOut } = createAuth({
+  secret,
+  pages: { signIn: '/signin', error: '/signin' },
+  providers: [Credentials({
+    async authorize(c: { email: string; password: string }) {
+      const user = await db.query.users.findFirst({ where: { email: c.email } });
+      if (!user || !(await verifyPassword(c.password, user.passwordHash))) return null;
+      return { id: String(user.id), email: user.email };
+    },
+  })],
+});
+export interface SessionUser { id: number; email: string }
+export async function getUser(): Promise<SessionUser | null> {
+  const u = (await auth())?.user;
+  return u?.id ? { id: Number(u.id), email: String(u.email) } : null;
+}
+```
+
+```ts
+// modules/auth/queries/current-user.server.ts (for the layout and public pages)
+'use server';
+import { getUser, type SessionUser } from '../auth.server.ts';
+export async function currentUser(): Promise<SessionUser | null> {
+  return getUser();
+}
+
+// modules/auth/queries/require-user.server.ts (call first in every signed-in page)
+'use server';
+import { redirect } from '@webjsdev/core';
+import { getUser, type SessionUser } from '../auth.server.ts';
+export async function requireUser(): Promise<SessionUser> {
+  return (await getUser()) ?? redirect('/signin');
+}
+```
+
+```ts
+// modules/auth/actions/sign-up.server.ts
+'use server';
+import { db } from '#db/connection.server.ts';
+import { users } from '#db/schema.server.ts';
+import { isEmail, str } from '#lib/utils/form.ts';
+import { hashPassword } from '../password.server.ts';
+import { signIn } from '../auth.server.ts';
+
+export async function signUp(fd: FormData) {
+  const email = str(fd, 'email').toLowerCase();
+  const password = String(fd.get('password') ?? '');
+  const fieldErrors: Record<string, string> = {};
+  if (!isEmail(email)) fieldErrors.email = 'Enter a valid email address.';
+  if (password.length < 8) fieldErrors.password = 'Password must be at least 8 characters.';
+  if (!fieldErrors.email && (await db.query.users.findFirst({ where: { email } }))) {
+    fieldErrors.email = 'An account with this email already exists.';
+  }
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors };
+  await db.insert(users).values({ email, passwordHash: await hashPassword(password) });
+  return signIn('credentials', { email, password }, { redirectTo: '/posts' }); // sets the cookie, 302
+}
+```
+
+Sign-in is the same shape: look the user up, `verifyPassword`, return
+`{ success: false, error: 'Invalid email or password.' }` on a mismatch, else
+`return signIn('credentials', { email, password }, { redirectTo: '/posts' })`.
+Sign-out is an action bound to a form in the layout:
+
+```ts
+// modules/auth/actions/sign-out.server.ts
+'use server';
+import { signOut } from '../auth.server.ts';
+export async function signOutUser(_fd: FormData) {
+  return signOut({ redirectTo: '/signin' }); // clears the cookie, 302
+}
+```
+
+```ts
+// modules/posts/utils/validate-post.ts (pure: shared by create and update, unit-tested)
+import { str } from '#lib/utils/form.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+export interface PostInput { title: string; body: string; status: PostStatus; publishOn: string | null }
+export function validatePost(fd: FormData) {
+  const values = { title: str(fd, 'title'), body: str(fd, 'body'), status: str(fd, 'status') || 'draft', publishOn: str(fd, 'publishOn') };
+  const fieldErrors: Record<string, string> = {};
+  if (!values.title) fieldErrors.title = 'Title is required.';
+  if (!(POST_STATUSES as readonly string[]).includes(values.status)) fieldErrors.status = 'Pick a status.';
+  if (values.publishOn && !/^\d{4}-\d{2}-\d{2}$/.test(values.publishOn)) fieldErrors.publishOn = 'Use a valid date.';
+  if (Object.keys(fieldErrors).length) return { ok: false as const, fieldErrors, values };
+  const data: PostInput = { ...values, status: values.status as PostStatus, publishOn: values.publishOn || null };
+  return { ok: true as const, data };
+}
+```
+
+Reads use the relational API (`db.query.<table>.findMany/findFirst` with an
+object `where` and `orderBy`) and always filter by the owner:
+
+```ts
+// modules/posts/queries/get-post.server.ts (list-posts.server.ts is the same with findMany + orderBy: { createdAt: 'desc' })
+'use server';
+import { db } from '#db/connection.server.ts';
+import type { Post } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { toId } from '#lib/utils/form.ts';
+
+/** The post when it exists AND belongs to the signed-in user, else null (the page throws notFound()). */
+export async function getPost(id: string): Promise<Post | null> {
+  const user = await getUser();
+  const postId = toId(id);
+  if (!user || !postId) return null;
+  return (await db.query.posts.findFirst({ where: { id: postId, ownerId: user.id } })) ?? null;
+}
+```
+
+```ts
+// modules/posts/queries/count-posts.server.ts (one grouped query, never one per row)
+'use server';
+import { count, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import type { StatusCounts } from '../types.ts';
+
+export async function countPosts(): Promise<StatusCounts> {
+  const c: StatusCounts = { draft: 0, review: 0, published: 0, total: 0 };
+  const user = await getUser();
+  if (!user) return c;
+  const rows = await db.select({ status: posts.status, n: count() }).from(posts)
+    .where(eq(posts.ownerId, user.id)).groupBy(posts.status);
+  for (const r of rows) { c[r.status] = r.n; c.total += r.n; }
+  return c;
+}
+```
+
+Writes use the query builder with `eq` / `and`, and put the owner in the
+`where` so another user's id changes nothing. `create-post.server.ts` is
+`validatePost`, then `db.insert(posts).values({ ...v.data, ownerId: user.id }).returning()`,
+then `{ success: true, redirect: '/posts/' + post.id }`. `delete-post.server.ts`
+reads the id from a hidden input and returns `{ success: true, redirect: '/posts' }`.
+
+```ts
+// modules/posts/actions/update-post.server.ts
+'use server';
+import { and, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { toId } from '#lib/utils/form.ts';
+import { validatePost } from '../utils/validate-post.ts';
+
+export async function updatePost(fd: FormData) {
+  const user = await getUser();
+  const id = toId(fd.get('id'));
+  if (!user || !id) return { success: false, error: 'Not found.', status: 404 };
+  const v = validatePost(fd);
+  if (!v.ok) return { success: false, fieldErrors: v.fieldErrors, values: v.values };
+  const rows = await db.update(posts).set(v.data).where(and(eq(posts.id, id), eq(posts.ownerId, user.id))).returning();
+  if (!rows.length) return { success: false, error: 'Not found.', status: 404 };
+  return { success: true, redirect: `/posts/${id}` };
+}
+```
+
+An action a component calls over RPC takes a typed object, checks it, and
+returns a result (it never throws or redirects):
+
+```ts
+// modules/posts/actions/set-post-status.server.ts
+'use server';
+import { and, eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
+import { getUser } from '#modules/auth/auth.server.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+
+export interface SetStatusInput { id: number; status: PostStatus }
+export async function setPostStatus(input: SetStatusInput) {
+  const user = await getUser();
+  if (!user) return { success: false, error: 'Sign in first.', status: 401 };
+  if (!POST_STATUSES.includes(input.status)) return { success: false, error: 'Bad status.', status: 400 };
+  const rows = await db.update(posts).set({ status: input.status })
+    .where(and(eq(posts.id, Number(input.id)), eq(posts.ownerId, user.id))).returning();
+  return rows.length ? { success: true } : { success: false, error: 'Not found.', status: 404 };
+}
+```
+
+A component declares reactive properties in the `WebComponent({...})` factory
+(attributes arrive kebab-cased: `postId` is `post-id`), keeps local state in
+signals, and binds events with an unquoted `@event=${fn}`:
+
+```ts
+// modules/posts/components/post-status.ts
+import { WebComponent, html, signal } from '@webjsdev/core';
+import { setPostStatus } from '../actions/set-post-status.server.ts';
+import { POST_STATUSES, type PostStatus } from '../types.ts';
+import { labelClass } from '#components/ui/label.ts';
+import { nativeSelectClass } from '#components/ui/native-select.ts';
+
+/** Status select that saves on change over RPC, with no page reload. */
+export class PostStatusSelect extends WebComponent({ postId: Number, status: String }) {
+  note = signal('');
+  async onChange(e: Event) {
+    const select = e.target as HTMLSelectElement;
+    const before = this.status;
+    this.status = select.value;
+    const res = await setPostStatus({ id: this.postId, status: select.value as PostStatus });
+    if (res.success) this.note.set('Saved');
+    else { this.status = before; select.value = before; this.note.set(res.error ?? 'Could not save'); }
+  }
+  render() {
+    const id = `status-${this.postId}`;
+    return html`
+      <div class="flex items-center gap-2">
+        <label for=${id} class=${labelClass()}>Status</label>
+        <select id=${id} class=${nativeSelectClass()} @change=${(e: Event) => this.onChange(e)}>
+          ${POST_STATUSES.map((s) => html`<option value=${s} ?selected=${s === this.status}>${s}</option>`)}
+        </select>
+        <span class="text-xs text-muted-foreground" aria-live="polite">${this.note.get()}</span>
+      </div>`;
+  }
+}
+PostStatusSelect.register('post-status');
+```
+
+```ts
+// app/layout.ts
+import { html, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+import { signOutUser } from '#modules/auth/actions/sign-out.server.ts';
+
+export const metadata = { title: { default: 'Posts', template: '%s | Posts' } };
+export default async function RootLayout({ children }: LayoutProps) {
+  const user = await currentUser();
+  return html`
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href=${asset('/public/tailwind.css')}>
+    <script>if (matchMedia('(prefers-color-scheme: dark)').matches) document.documentElement.classList.add('dark');</script>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --background: light-dark(#ffffff, #14161a); --foreground: light-dark(#17191c, #e6e8eb);
+        --card: light-dark(#f7f8fa, #1c1f24); --card-foreground: var(--foreground);
+        --primary: light-dark(#2f5bd3, #8fb0ff); --primary-foreground: light-dark(#ffffff, #0b1530);
+        --secondary: light-dark(#eef0f3, #2a2e34); --secondary-foreground: var(--foreground);
+        --muted: light-dark(#f1f3f5, #23272d); --muted-foreground: light-dark(#5b626b, #9aa1aa);
+        --accent: light-dark(#e9edf5, #2a3140); --accent-foreground: var(--foreground);
+        --border: light-dark(#e2e5e9, #343a42); --input: var(--border); --ring: light-dark(#8aa4e8, #5b78c4);
+        --destructive: light-dark(#c0362c, #f28b82);
+      }
+      body { margin: 0; background: var(--background); color: var(--foreground); font: 15px/1.6 system-ui, sans-serif; }
+    </style>
+    <header class="fixed inset-x-0 top-0 z-40 h-14 border-b border-border bg-background/95 backdrop-blur">
+      <nav class="mx-auto flex h-full max-w-4xl items-center gap-4 px-4">
+        <a href="/" class="font-semibold text-foreground no-underline">Posts</a>
+        ${user ? html`
+          <span class="ml-auto hidden text-sm text-muted-foreground sm:inline">${user.email}</span>
+          <form action=${signOutUser} class="ml-auto sm:ml-0"><button class=${buttonClass({ variant: 'outline', size: 'sm' })}>Sign out</button></form>`
+        : html`<a href="/signin" class="ml-auto text-sm">Sign in</a>`}
+      </nav>
+    </header>
+    <main class="mx-auto min-h-dvh max-w-4xl px-4 pb-16 pt-20 text-foreground">${children}</main>`;
+}
+```
+
+```ts
+// app/page.ts
+import { redirect } from '@webjsdev/core';
+import { currentUser } from '#modules/auth/queries/current-user.server.ts';
+export default async function Home() {
+  redirect((await currentUser()) ? '/posts' : '/signin');
+}
+```
+
+A page with a form reads `actionData` (typed with `FormState`). The sign-in
+and sign-up pages are this shape too, with `if (await currentUser()) redirect('/posts');`
+first and `actionData.error` shown above the fields.
+
+```ts
+// app/posts/page.ts
+import { html } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { cardClass } from '#components/ui/card.ts';
+import { field, type FormState } from '#lib/utils/form.ts';
+import { requireUser } from '#modules/auth/queries/require-user.server.ts';
+import { listPosts } from '#modules/posts/queries/list-posts.server.ts';
+import { countPosts } from '#modules/posts/queries/count-posts.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+
+export const metadata = { title: 'Your posts' };
+export default async function PostsPage({ actionData }: PageProps<'/posts'> & { actionData?: FormState }) {
+  await requireUser();
+  const [items, counts] = await Promise.all([listPosts(), countPosts()]);
+  const e = actionData?.fieldErrors ?? {};
+  const v = actionData?.values ?? {};
+  return html`
+    <h1 class="text-2xl font-semibold">Your posts</h1>
+    <p class="mt-1 text-sm text-muted-foreground">${counts.total} total, ${counts.published} published</p>
+    <form action=${createPost} class="${cardClass()} mt-6 grid gap-3 p-4 sm:grid-cols-[1fr_auto] sm:items-end">
+      ${field({ label: 'Title', name: 'title', value: v.title, error: e.title, required: true })}
+      <button class=${buttonClass()}>Create post</button>
+    </form>
+    <ul class="mt-6 grid gap-3 sm:grid-cols-2">
+      ${items.map((p) => html`
+        <li class="${cardClass()} p-4">
+          <a href="/posts/${p.id}" class="font-medium text-foreground">${p.title}</a>
+          <p class="mt-1 text-sm text-muted-foreground">${p.status}</p>
+        </li>`)}
+    </ul>
+    ${items.length ? '' : html`<p class="mt-6 text-muted-foreground">No posts yet.</p>`}`;
+}
+```
+
+```ts
+// app/posts/[id]/page.ts
+import { html, notFound } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { requireUser } from '#modules/auth/queries/require-user.server.ts';
+import { getPost } from '#modules/posts/queries/get-post.server.ts';
+import { deletePost } from '#modules/posts/actions/delete-post.server.ts';
+import '#modules/posts/components/post-status.ts'; // registers <post-status>
+
+export default async function PostPage({ params }: PageProps<'/posts/[id]'>) {
+  await requireUser();
+  const post = await getPost(params.id);
+  if (!post) notFound();
+  return html`
+    <h1 class="text-2xl font-semibold">${post.title}</h1>
+    ${post.body ? html`<p class="mt-3 whitespace-pre-line">${post.body}</p>` : ''}
+    <div class="mt-6 flex flex-wrap items-center gap-3">
+      <post-status post-id=${post.id} status=${post.status}></post-status>
+      <a href="/posts/${post.id}/edit" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Edit</a>
+      <form action=${deletePost} onsubmit="return confirm('Delete this post?')">
+        <input type="hidden" name="id" value=${post.id}>
+        <button class=${buttonClass({ variant: 'destructive', size: 'sm' })}>Delete</button>
+      </form>
+    </div>`;
+}
+```
+
+The edit page loads the row the same way, pre-fills from it
+(`const v = actionData?.values ?? { title: post.title, ... }`), and posts a
+hidden `id` to `updatePost`. A `<textarea class=${textareaClass()}>` holds its
+value as text content; a `<select class=${nativeSelectClass()}>` marks the
+current option with `?selected=${s === v.status}`. Both need a `<label for>`.
+
+```ts
+// app/not-found.ts
+import { html } from '@webjsdev/core';
+export default function NotFound() {
+  return html`<h1 class="text-2xl font-semibold">Not found</h1><p class="mt-2 text-muted-foreground"><a href="/">Go home</a></p>`;
+}
+```
+
+```ts
+// test/posts/validate-post.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validatePost } from '#modules/posts/utils/validate-post.ts';
+const fd = (o: Record<string, string>) => { const f = new FormData(); for (const [k, v] of Object.entries(o)) f.set(k, v); return f; };
+test('a post needs a title', () => {
+  const r = validatePost(fd({ title: '  ' }));
+  assert.equal(r.ok ? '' : r.fieldErrors.title, 'Title is required.');
+});
+```
+
+### Look and the UI kit
+
+- The palette is the token block in the layout's `<style>`, each colour
+  written once as `light-dark(LIGHT, DARK)`; `public/input.css` maps the tokens
+  into Tailwind. Pick values that fit the product, and style only with token
+  utilities:
+  `bg-background text-foreground bg-card text-card-foreground bg-primary
+  text-primary-foreground bg-muted text-muted-foreground border-border
+  text-destructive ring-ring`. Never a raw colour such as `bg-blue-600`.
+- Pin the header with `position: fixed` (never `sticky`) and offset the
+  content by its height, as the layout above does. Mobile first: one column
+  that widens at `sm:` / `md:`.
+- The kit copies class helpers into `components/ui/` (you own them; no need to
+  open them): `buttonClass({ variant?: 'default' | 'destructive' | 'outline' |
+  'secondary' | 'ghost' | 'link', size?: 'default' | 'xs' | 'sm' | 'lg' |
+  'icon' })`, `inputClass()`, `textareaClass()`, `labelClass()`,
+  `nativeSelectClass()`, `cardClass({ size?: 'default' | 'sm' })`,
+  `badgeClass({ variant?: 'default' | 'secondary' | 'destructive' | 'outline' })`.
+  Use them as `class=${buttonClass({ variant: 'outline' })}` on native
+  elements. Stateful widgets (dialog, tabs, dropdown menu, tooltip, toasts) are
+  custom elements: `npx webjsdev ui add dialog`, then `npx webjsdev ui view dialog`
+  for the tags.
 
 ### Commands
 
 ```sh
-npm install
-npm run gallery:clear        # shed the demo gallery before building a real app
-npm run dev                  # dev server at http://localhost:8080
-npm run start                # production server
-npm test                     # unit + browser tests
-npm run typecheck
-npm run css:build            # compile Tailwind
-npm run ci                   # every gate, one command (the webjs.ci steps in package.json)
-npm run check                # correctness checks
-npm run doctor               # project health (severity per check: webjs.doctor.gate)
-npx webjsdev ui add <name>   # copy a ui primitive into components/ui/
-npx webjsdev ui view <name>  # inspect a primitive's exact signature
-npm run db:generate && npm run db:migrate
+npm run dev                    # dev server; PORT=<port> to choose the port
+npm run db:generate && npm run db:migrate   # after every schema change
+npm run check                  # framework rules (boundaries, forms, components)
+npm run typecheck              # TypeScript
+npm run test:server            # node:test files under test/
+npm run ci                     # every gate, before you push
+npx webjsdev ui add <name>     # copy a UI kit primitive into components/ui/
 ```

package/templates/scripts/clear-gallery.mjs

@@ -147,8 +147,8 @@ for (const f of ['db/dev.db', 'db/dev.db-shm', 'db/dev.db-wal']) rm(f);
 // children before test/ so it reads as empty.
 for (const d of ['app/api', 'test/unit', 'test/e2e', 'test']) if (pruneEmpty(d)) removed++;
 
-console.log(`Gallery cleared (${removed} paths removed). The agent skill and your database wiring are kept. Build your own design system: run \`npx webjsdev ui add <name>\` and theme it (see .agents/skills/webjs/references/styling.md).`);
-console.log('Next: regenerate the database (db:generate then db:migrate), then start the dev server and build your app in app/ and modules/.');
+console.log(`Gallery cleared (${removed} paths removed). The agent docs and your database wiring are kept.`);
+console.log('Next: follow the build steps in AGENTS.md (schema, then db:generate and db:migrate, then modules/ and app/).');
 
 function MINIMAL_PAGE() {
   return `import { html } from '@webjsdev/core';
@@ -163,7 +163,7 @@ export default function Home() {
       <h1 class="text-4xl font-bold tracking-tight m-0">Your app</h1>
       <p class="text-base leading-relaxed m-0 opacity-70">
         The gallery is cleared. This is <code class="text-[0.9em]">app/page.ts</code>. Build your
-        app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.md</code>.
+        app from here. The guide is <code class="text-[0.9em]">AGENTS.md</code>.
       </p>
       <nav class="flex items-center gap-5 text-sm opacity-70">
         <a href="https://webjs.dev/docs" target="_blank" rel="noopener" class="hover:opacity-100 transition-opacity no-underline">Docs</a>