@webjsdev/cli 0.10.69 → 0.10.70

package/lib/create.js

@@ -444,9 +444,20 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       '@webjsdev/cli': 'latest',
       '@webjsdev/core': 'latest',
       '@webjsdev/server': 'latest',
+      // What the production BOOT runs, so production dependencies (#1606):
+      // `webjs start` runs the `webjs.start.before` steps at every boot,
+      // `webjs db migrate` (drizzle-kit) and, on a UI app, the Tailwind
+      // compile. The Dockerfile installs production dependencies only, so as
+      // devDependencies these would be missing from the image and the boot
+      // would fail. `tailwindcss` itself is declared too (#1493):
+      // public/input.css starts with `@import "tailwindcss"`, and bun's
+      // isolated linker and pnpm link only declared packages, so leaving it
+      // transitive (via @tailwindcss/cli) fails the compile with
+      // `Can't resolve 'tailwindcss'`. The api template has no CSS.
+      'drizzle-kit': '1.0.0-rc.3',
+      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
     },
     devDependencies: {
-      'drizzle-kit': '1.0.0-rc.3',
       ...(dialect === 'postgres' ? { '@types/pg': '^8.11.0' } : {}),
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
@@ -467,15 +478,6 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // assertNoA11yViolations() test helper from @webjsdev/core/testing.
       // Test-only: dynamically imported, never shipped to the app runtime.
       'axe-core': '^4.10.0',
-      // The Tailwind v4 CLI that css:build runs to compile public/input.css into
-      // the static public/tailwind.css the layout links. UI templates only (the
-      // api template has no CSS). Build tooling, never shipped to the runtime.
-      // `tailwindcss` itself is declared too (#1493): public/input.css starts
-      // with `@import "tailwindcss"`, so the app imports that package directly.
-      // Leaving it transitive (via @tailwindcss/cli) breaks under bun's isolated
-      // linker and pnpm, which link only declared packages into the app's
-      // node_modules, so the compile fails with `Can't resolve 'tailwindcss'`.
-      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
       // tsserver plugin, wired into tsconfig below. Gives the language
       // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
       // templates) in any tsserver editor with NO editor plugin installed,
@@ -1721,8 +1723,8 @@ ThemeToggle.register('theme-toggle');
 `);
   }
   console.log(`For AI agents, read this before editing:
-  • Read AGENTS.md first: it carries the build steps and a worked example of
-    every common pattern. .agents/skills/webjs/ is the deeper reference.
+  • 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.
   • 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-reload.js

@@ -68,7 +68,9 @@ export const KILL_TIMEOUT_MS = 2000;
  * @returns {boolean}
  */
 export function shouldIgnoreRestartPath(rel) {
-  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '');
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '')
+    // Tool output nothing serves, as the server's watcher skips it (watch-ignore.js).
+    || /(?:^|[\\/])(?:coverage|\.cache|\.nyc_output|test-results|playwright-report|\.turbo)(?:[\\/]|$)|\.log$|(?:^|[\\/])\.DS_Store$|\.swp$|~$/.test(rel || '');
 }
 
 /**

package/lib/runtime-rewrite.js

@@ -23,7 +23,7 @@
  *   - the `dev` / `start` scripts force `bun --bun` (the server is Bun),
  *   - every other command stays `bun run` / `webjs ...` (runs on Node via the
  *     `webjs` bin's `#!/usr/bin/env node` shebang),
- *   - the Dockerfile is a pure `oven/bun:1` base (#595). This is safe as of
+ *   - the Dockerfile is a pure `oven/bun:1-slim` base (#595, #1606). This is safe as of
  *     `@webjsdev/cli@0.10.20` (#570): `webjs db migrate` resolves drizzle-kit
  *     and runs it under Bun (no `npx`), so a Node-less image works. (Before
  *     #570 shipped as `latest`, this stayed on `node:24-alpine` + a copied Bun
@@ -96,7 +96,7 @@ export function bunifyProse(s) {
 /**
  * Rewrite the scaffolded Dockerfile for Bun.
  *
- * Base decision (acceptance criterion): a pure `oven/bun:1` image (no Node).
+ * Base decision (acceptance criterion): a pure `oven/bun:1-slim` image (no Node).
  * Safe as of `@webjsdev/cli@0.10.20` (#570): `webjs db` / `webjs test` resolve
  * their tools (drizzle-kit, wtr) and spawn them with the current runtime instead
  * of `npx`, so the boot-time `webjs db migrate` runs under Bun with no Node
@@ -123,7 +123,9 @@ export function bunifyDockerfile(s) {
       '# runs on Node 24+; for a Node base instead, swap to `node:24-alpine` and start with\n' +
       '# `npm start`.\n',
     )
-    .replace('FROM node:24-alpine', 'FROM oven/bun:1')
+    // The slim variant: the same Bun on a Debian slim base (ca-certificates
+    // included), without the full image's extra system packages.
+    .replace('FROM node:24-alpine', 'FROM oven/bun:1-slim')
     // Debian base: ca-certificates already present, no `apk`. Drop the alpine line.
     .replace(
       /# ca-certificates for outbound TLS \(e\.g\. a managed Postgres\)\. SQLite uses the\n# built-in node:sqlite \(no native module, no build toolchain needed\)\.\nRUN apk add --no-cache ca-certificates\n\n/,
@@ -131,8 +133,12 @@ export function bunifyDockerfile(s) {
     )
     // Lockfile + install (bun.lock, bun install).
     .replace(
-      '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\nCOPY package.json package-lock.json* ./\nRUN npm install --no-audit --no-fund',
-      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. SQLite uses the built-in bun:sqlite, so no\n# native dependency or postinstall is involved.\nCOPY package.json bun.lock* ./\nRUN bun install',
+      '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\n',
+      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. SQLite uses the built-in bun:sqlite, so no\n# native dependency or postinstall is involved.\n',
+    )
+    .replace(
+      'reason. The npm cache is emptied in the same layer: it is a second copy of\n# every package fetched and would otherwise ship in the image.\nCOPY package.json package-lock.json* ./\nRUN npm install --omit=dev --no-audit --no-fund && npm cache clean --force',
+      'reason. bun\'s package cache is emptied in the same layer: it is a second copy\n# of every package fetched and would otherwise ship in the image.\nCOPY package.json bun.lock* ./\nRUN bun install --production && bun pm cache rm',
     )
     // Healthcheck: the pure Bun image has no node; use `bun -e`. Keep the
     // dependency-free-probe comment accurate (the probe runs under Bun now).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.69",
+  "version": "0.10.70",
   "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.87",
+    "@webjsdev/server": "^0.8.88",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -2,21 +2,23 @@
 
 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.md`; the
-deeper reference set is `.agents/skills/webjs/SKILL.md`. Full hosted docs are
-at https://webjs.dev/docs.
+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.
 
 ## Grow the app in place (non-negotiable)
 
-- **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.
+- **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.
 - **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
@@ -24,8 +26,9 @@ 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.** Give the design
-  tokens in `public/input.css` a palette that fits the app, then open every
+- **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
   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,8 +9,6 @@ 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

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

@@ -68,7 +68,7 @@ One limit worth knowing: the rewrite belongs to `startServer`. An app embedded t
 webjs create my-app --runtime bun
 ```
 
-`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
+`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1-slim` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
 
 ## Running on Bun
 
@@ -79,13 +79,15 @@ bun install
 bun run dev      # or: bun run start
 ```
 
-`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun, selecting the native `Bun.serve` listener and `amaro` type stripping. The app's dependencies resolve from `node_modules` exactly as on Node. The `start.before` migrate step (`webjs db migrate`) runs under Bun too. Commit the `bun.lock` for reproducible, offline installs. The scaffold's Bun Dockerfile runs `bun install` and serves via `CMD ["bun", "--bun", "run", "start"]`.
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun, selecting the native `Bun.serve` listener and `amaro` type stripping. The app's dependencies resolve from `node_modules` exactly as on Node. The `start.before` migrate step (`webjs db migrate`) runs under Bun too. Commit the `bun.lock` for reproducible, offline installs. The scaffold's Bun Dockerfile runs `bun install --production` and serves via `CMD ["bun", "--bun", "run", "start"]`.
+
+**What the dev watcher ignores.** On both runtimes a change to a file nothing serves never reloads the page: `*.log`, `coverage/`, `.cache/`, `test-results/`, `playwright-report/`, and anything the app's `.gitignore` ignores (except `.env*`). So `npm run dev > dev.log` in the app folder is safe.
 
 ## Deploying either runtime
 
 Production runs `npm run start` (Node) or `bun run start` (Bun), which serves the source directly with no build step. Both speak plain HTTP/1.1, so put a reverse proxy or platform edge in front for TLS and HTTP/2 (production perf leans on HTTP/2 multiplexing plus `modulepreload` hints, not a bundle). A `start.before` migrate runs first on both runtimes.
 
-The scaffold ships a matching Dockerfile per runtime: a Node image for the default, a pure `oven/bun:1` image for `--runtime bun`. Commit the lockfile the runtime uses (`package-lock.json` for Node, `bun.lock` for Bun) so the deploy install is reproducible and offline.
+The scaffold ships a matching Dockerfile per runtime: a Node image for the default, a pure `oven/bun:1-slim` image for `--runtime bun`. Both install production dependencies only and leave the package manager's cache out of the image. What the boot runs is a production dependency for that reason: `drizzle-kit` (the `start.before` migrate) and, on a UI app, `@tailwindcss/cli` + `tailwindcss` (the CSS compile). Keep a tool the boot runs in `dependencies`; one moved to `devDependencies` is missing from the image and the boot fails. Commit the lockfile the runtime uses (`package-lock.json` for Node, `bun.lock` for Bun) so the deploy install is reproducible and offline.
 
 ## SQLite busy_timeout
 

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

@@ -30,13 +30,6 @@ 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,52 +1,82 @@
 # AGENTS.md for {{APP_NAME}}
 
-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.
+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.
 
 {{PLAYBOOK}}
 
-## 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.
+## 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.

package/templates/CLAUDE.md

@@ -3,19 +3,21 @@
 # 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 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.
+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.
 
-- 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`).
+- 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`).
 
-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.
+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.

package/templates/CONVENTIONS.md

@@ -1,9 +1,9 @@
 # Conventions for {{APP_NAME}}
 
-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 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 essentials
 
@@ -17,12 +17,13 @@ surfaces. This file 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 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.
+- **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.
 - **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/Dockerfile

@@ -30,8 +30,14 @@ WORKDIR /app
 # Install deps first so this layer is cached unless the manifests change.
 # package-lock.json is optional (it's absent when the app was scaffolded with
 # --no-install); the glob keeps the COPY working with or without it.
+# Production dependencies only: the image never runs the type checker, the
+# test runner or the browser tests, and leaving them out keeps it a fraction
+# of the size. What the boot itself runs (drizzle-kit for `webjs db migrate`,
+# the Tailwind CLI for the CSS compile) is a production dependency for that
+# reason. The npm cache is emptied in the same layer: it is a second copy of
+# every package fetched and would otherwise ship in the image.
 COPY package.json package-lock.json* ./
-RUN npm install --no-audit --no-fund
+RUN npm install --omit=dev --no-audit --no-fund && npm cache clean --force
 
 # App source. node_modules and local state are excluded via .dockerignore.
 COPY . .

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

@@ -1,571 +1,135 @@
-## 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.
+## 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.
 
 ### Commands
 
 ```sh
-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/
+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
 ```

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 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/).');
+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/.');
 
 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.md</code>.
+        app from here. The guide is <code class="text-[0.9em]">.agents/skills/webjs/SKILL.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>