@webjsdev/cli 0.10.30 → 0.10.32

package/templates/.cursorrules

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md doesn't
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -18,6 +18,51 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app
+  USES and delete the rest (files AND folders). No persistence means
+  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
+  used means delete `components/ui/`, `components.json`, and
+  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
+  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
+  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a
+  full-bleed dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:
@@ -110,13 +155,17 @@ self-review loop.
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
+- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, `route.ts`, or `middleware.ts`. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
 - Components must call customElements.define('tag', Class)
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
 - **Keep pages and layouts as pure carriers** so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the browser's network tab.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions. When AGENTS.md doesn't cover what you need,
-the full hosted docs are at **https://docs.webjs.com**.
+the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -18,6 +18,51 @@ the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app
+  USES and delete the rest (files AND folders). No persistence means
+  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
+  used means delete `components/ui/`, `components.json`, and
+  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
+  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
+  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a
+  full-bleed dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:
@@ -107,9 +152,13 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
 - Server actions: *.server.ts files with one exported async function each.
+- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, route.ts, or middleware.ts. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
 - Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'

package/templates/AGENTS.md

@@ -4,8 +4,8 @@ Read this before editing any file. This is a webjs app: AI-first, web-
 components-first, no build step. The framework's own full API reference
 lives at https://github.com/webjsdev/webjs/blob/main/AGENTS.md and the
 full hosted documentation (every API, recipe, and example) lives at
-**https://docs.webjs.com**. Treat this file as the app-scoped
-companion and reach for docs.webjs.com whenever you need more detail.
+**https://docs.webjs.dev**. Treat this file as the app-scoped
+companion and reach for docs.webjs.dev whenever you need more detail.
 
 ## If you just scaffolded this app (AI agents, read first)
 
@@ -20,7 +20,22 @@ example `Home` nav, and pick a content-width container that fits. The
 default `<main class="max-w-[760px]">` is a reading column for prose and
 forms, so for a full-bleed app, dashboard, or board, widen the cap or
 remove it (keep the theme tokens). A wide layout left in the 760px
-reading column overflows into a horizontal scrollbar. This is ENFORCED:
+reading column overflows into a horizontal scrollbar. **Give the app a
+unique design, and redesign means more than recolor.** When it has a UI,
+choose its palette, typography, LAYOUT, and chrome from what the app IS.
+Recoloring the scaffold and swapping the logo while keeping its skeleton (a
+fixed top header with a Home link and a theme toggle, the centered ~760px
+reading column, the "Built with webjs" footer) is NOT a unique design.
+Decide from scratch whether this app even needs a header or footer, what nav
+(if any), and what layout fits (a centered board, a full-bleed dashboard, a
+split, a single card). Before finishing, self-audit that nothing still reads
+as the scaffold example (no "Built with webjs" footer, no leftover example
+nav, no default reading column unless it truly fits). The `api` template has
+no UI, so this does not apply there. The design tokens and theme wiring are
+infrastructure to keep and restyle on top of. Style with Tailwind utilities
+wherever they reach, and use custom CSS only for what utilities cannot
+express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+gradients). This is ENFORCED:
 the example `app/page.ts` and `app/layout.ts` carry a
 `webjs-scaffold-placeholder` marker comment, and `webjs check` fails
 while any marker remains, so this freshly scaffolded app fails the check
@@ -51,6 +66,17 @@ user asked for, never leftover scaffold code.
    app's real domain models (delete the example `User` model unless the
    app actually needs users), run `webjs db generate` then
    `webjs db migrate`, then build pages / actions / queries against them.
+4. **Prune what the app does not use.** The scaffold is reference, so keep
+   the infrastructure the app USES and delete the rest, both files AND
+   folders. No persistence means delete `db/`, `drizzle.config.ts`, and
+   the `db:*` scripts. No UI kit used means delete `components/ui/`,
+   `components.json`, and `lib/utils/cn.ts`. No PWA means delete
+   `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
+   (`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files, the MCP
+   wiring), never prune it, so removing example code never removes your
+   context. Prune AFTER you have used the features and examples as reference, never
+   blindly up front. This is a no-op for the `api` template (no UI kit,
+   no PWA files).
 
 **Picking the right scaffold from the user's prompt** (you do this BEFORE
 running `webjs create`; if you're reading this you've already scaffolded.
@@ -171,7 +197,7 @@ entry, its own template parser. Inside `` html`…` `` templates you get:
 In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
 automatically (no `tsconfig.json` edit, no separate Lit extension).
 
-See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
+See [docs.webjs.dev → Editor setup](https://docs.webjs.dev/docs/editor-setup)
 for the full walkthrough.
 
 **Config validation in `package.json`.** The scaffold ships
@@ -296,11 +322,32 @@ wrapper adds zero value and obscures the real element from inspection,
 form submission, and screen readers. Custom elements are reserved for
 behavior the browser can't deliver natively.
 
+### Accessible control labeling
+
+Give every interactive control an accessible name, and make clickable
+text a `<label for="control-id">` (or the control itself) so a text click
+activates the control on BOTH the JS path and the no-JS form-submit path.
+Use `aria-label` and `aria-pressed` on icon-only controls (a toggle
+button, an icon-only close/menu button). A native `<input>` under a
+`<label>` gets this for free, which is another reason to reach for the
+Tier-1 class helpers on real elements. In a browser test,
+`assertNoA11yViolations(el)` from `@webjsdev/core/testing` catches
+missing labels.
+
 ## File conventions
 
 ```
-app/                     thin route adapters (import from modules/)
-  page.ts                → /
+app/                     ROUTING ONLY: thin route adapters (import from modules/).
+                         No CSS, helpers, or constants here; those live in
+                         styles/, lib/utils/, and modules/. globals.css is at
+                         styles/, NOT app/.
+  page.ts                → / (the scaffold home links to the gallery)
+  features/<name>/       single-feature demos (routing, components,
+                         server-actions, optimistic-ui, async-render,
+                         directives, route-handler, forms, metadata, caching,
+                         env, client-router, service-worker); prune what you skip
+  examples/<name>/       whole example apps that compose features (todo);
+                         prune what you skip
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
@@ -324,6 +371,8 @@ modules/<feature>/
   types.ts               feature types
 lib/
   ...                    cross-cutting infra (session, auth config, etc.)
+styles/
+  globals.css            @webjsdev/ui theme tokens (NOT in app/; app/ is routing-only)
 db/
   schema.server.ts       Drizzle models + relations (your data layer)
   columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
@@ -332,15 +381,54 @@ db/
   dev.db                 SQLite file (gitignored); created when migrations apply (\`dev\`/\`start\` run \`webjs db migrate\`)
   migrations/            generated migration SQL (committed)
 drizzle.config.ts        drizzle-kit config (root; SQLite by default, --db postgres to switch)
-public/                  static assets, served at /public/*
+public/                  static assets at /public/* (favicon, sw.js, offline.html serve at root)
 test/<feature>/                feature-scoped tests, one folder per concern
   <name>.test.ts                node unit / integration test (node --test)
-  browser/<name>.test.js        real-browser test (web-test-runner)
+  browser/<name>.test.js        real-browser test (web-test-runner); may ALSO be
+                                co-located next to a component, e.g.
+                                modules/<feature>/components/browser/<name>.test.js
+                                (see the gallery counter-card test for the idioms:
+                                suite/test, ssrFixture, inline assert, no chai)
   e2e/<name>.test.ts            end-to-end test (full app boot, opt in via WEBJS_E2E=1)
   smoke/<name>.test.ts          fast post-deploy sanity check
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### The gallery (reference content, prune it)
+
+The scaffold ships a gallery organized by KIND, so features and whole apps are
+not mixed:
+- `app/features/<name>/` are single-feature demos, one webjs concept each
+  (routing, components, server-actions, optimistic-ui, async-render, directives,
+  route-handler, forms, metadata, caching, env, client-router, service-worker,
+  plus the infra demos websockets, file-storage, rate-limit, broadcast).
+- `app/examples/<name>/` are whole example apps that compose several features
+  (todo: optimistic UI + progressive enhancement + a11y + db + modules).
+
+Both keep their logic in `modules/<name>/`. Each route is small, idiomatic, and
+heavily commented, and the gallery is your PRIMARY reference for how webjs works.
+
+**Study the whole gallery FIRST, prune SECOND.** Before you write or delete
+anything, read every feature demo and the example app end to end (the code AND
+the comments) to absorb the idioms you will reuse: the modules split, signals,
+the `optimistic()` API, `async render()`, the `.server.ts` vs `'use server'`
+boundary, progressive-enhancement forms, `<label for>` a11y, dynamic routes, and
+`route.ts` handlers. Only AFTER you have internalised the patterns should you
+prune. Never delete the examples blindly up front (that throws away your context
+before you have read it), and never prune the durable knowledge surfaces
+(`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files), which stay as context
+for every future iteration.
+
+Then prune: the examples are REFERENCE, not your app, so keep and adapt the ones
+you need and delete the rest. Pruning a route means deleting its
+`app/features/<name>` or `app/examples/<name>` folder AND its `modules/<name>`
+folder (and, for the todo app, the `todos` table in `db/schema.server.ts`), then
+removing its link from `app/page.ts`. Each route page carries a
+`webjs-scaffold-placeholder` marker so `webjs check` fails until you have
+consciously kept-and-adapted or pruned it. After pruning, delete any now-empty
+directories (an empty `lib/utils/` or `modules/<name>/` is leftover scaffolding,
+not structure).
+
 ### Typed page / layout / route-handler props
 
 Type page / layout / route-handler arguments with the exported helpers so a
@@ -517,7 +605,7 @@ git commit -m "vendor + download dayjs"
 Bundle files land in `.webjs/vendor/<pkg>@<version>.js`. importmap
 points at local `/__webjs/vendor/` paths. Browser fetches from your
 own origin. Suitable for `script-src 'self'` CSP, air-gapped deploys,
-or compliance environments. See [docs.webjs.com Deployment → CSP](https://docs.webjs.com/docs/deployment#csp).
+or compliance environments. See [docs.webjs.dev Deployment → CSP](https://docs.webjs.dev/docs/deployment#csp).
 
 **Other CLI commands:**
 
@@ -593,7 +681,7 @@ const url = process.env.WEBJS_PUBLIC_API_URL;       // works
 const secret = process.env.AUTH_SECRET;             // undefined (fail-closed)
 ```
 
-`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.com/docs/configuration).
+`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.dev/docs/configuration).
 
 ## Component pattern
 
@@ -751,6 +839,31 @@ globally. Prefer Tailwind. When a utility bundle repeats, extract it into
 a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment, not a
 CSS class.
 
+#### Design tokens: ONE theme, shadcn-canonical
+
+The app has a SINGLE theme, defined once in `app/layout.ts`. It uses the
+standard `@webjsdev/ui` (shadcn-compatible) semantic tokens, set to this app's
+brand palette. Use the canonical utility names everywhere, in the page chrome
+AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+`text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`,
+`text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the
+tokens the components copied in by `webjs ui add <name>` read, so a scaffolded
+page and a later-added ui component share one coherent theme automatically.
+
+- **Never invent a parallel token vocabulary** (`--fg`, `--bg`, `text-fg`,
+  `bg-elev`, a separate `--brand`). It collides with the ui tokens (the accent
+  once flipped to neutral on navigation for exactly this reason) and diverges
+  from the shadcn conventions the ui kit and AI agents both expect.
+- **Reach for opacity modifiers before a new token**: `bg-primary/10` for a
+  tint, `hover:bg-primary/90` for a hover, `text-muted-foreground/70` for a
+  subtler text level.
+- **Edit the palette in one place** (`app/layout.ts`). To ADD a token, do it
+  the canonical way: a `--x` variable in the `:root` / `.dark` blocks plus a
+  `--color-x: var(--x)` line in the `@theme inline` block, then use it as
+  `bg-x` / `text-x`.
+- Dark mode is a `.dark` class the theme toggle sets. Tokens switch by theme
+  automatically, so a component written with these names works in both.
+
 Reserve raw CSS for what utilities cannot express: design-token `:root` /
 `@theme` definitions, `@property` + `@keyframes` animations,
 `::-webkit-scrollbar`, `prefers-reduced-motion` blocks, and complex
@@ -761,6 +874,16 @@ legitimately use `static styles = css\`\`` for scoped CSS.
 
 ## Server action pattern
 
+**The `.server.ts` vs `'use server'` decision, in one question.** Will the
+client call it? Add `'use server'` and the file becomes an RPC action
+(the browser import is rewritten to a typed stub). Is it server-only
+infra instead (a DB driver, secrets, `node:*`)? Use NO directive, and
+never import it into a page, layout, or component. Reach it from a
+`'use server'` action, a `route.ts` handler, or `middleware.ts`. A
+`.server.ts` file WITHOUT the directive is a server-only utility whose
+browser import throws at module load (invariant 2 below), so a
+page/component that imports it directly crashes on the client.
+
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
@@ -788,7 +911,43 @@ that RETURNS a `ReadableStream` / async generator streams its chunks (consume
 with `for await`); read the request `AbortSignal` via `actionSignal()` to cancel
 on disconnect. **SAFETY:** a `cache` with `public: true` shares one response
 across all users, so use it only for data identical for every visitor. Full
-reference: https://docs.webjs.com/docs/server-actions
+reference: https://docs.webjs.dev/docs/server-actions
+
+## Mutations: default to optimistic UI
+
+Default to optimistic UI for every feasible mutation. Use `optimistic()`
+from `@webjsdev/core` (create, toggle, like, follow, reorder, rename,
+status change) so the UI updates instantly and rolls back automatically
+on failure. The declarative form queues an update on a component with
+auto-release when the action promise settles, no hand-written try-catch,
+cache-and-restore, or temp-id bookkeeping.
+
+```ts
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '#modules/todos/actions/create-todo.server.ts';
+
+class TodoList extends WebComponent({ todos: prop<Todo[]>(Array) }) {
+  private optimisticTodos = optimistic(this, {
+    source: () => this.todos,
+    update: (state, title: string) => [...state, { title, pending: true }],
+  });
+  async handleSubmit(title: string) {
+    const promise = createTodo({ title });
+    this.optimisticTodos.add(title, promise);   // auto-releases on settle
+    await promise;
+  }
+  render() {
+    return html`<ul>${this.optimisticTodos.value.map(t => html`
+      <li class=${t.pending ? 'opacity-50' : ''}>${t.title}</li>`)}</ul>`;
+  }
+}
+```
+
+Do NOT use optimistic UI where it hurts: unpredictable or server-computed
+results (AI output, server-assigned values the client cannot guess),
+side-effectful mutations the user must wait on (payment, email, OAuth),
+and destructive irreversible actions (a confirm-first UX is better). Full
+reference: https://docs.webjs.com/docs/optimistic-ui
 
 ## Client navigation patterns (auto-magic)
 
@@ -1258,8 +1417,10 @@ composition, so a nested shell ends up dropped by the HTML parser.
 3. Commit and push **per logical unit**, not at the end. A logical unit is one
    feature, one fix, one rename, one doc rewrite. If you have 5+ unstaged files
    spanning different concerns, commit the current group before continuing.
-   The framework ships a `nudge-uncommitted` hook for several agents that
-   fires at threshold 4:
+   For Claude Code, its `CLAUDE.md` explicitly OVERRIDES Claude Code's built-in
+   never-commit default, so it commits per unit without waiting to be asked. The
+   framework also ships a `nudge-uncommitted` hook for several agents that fires
+   at threshold 4:
 
    | Agent | Hook path | Doc |
    |---|---|---|
@@ -1270,6 +1431,12 @@ composition, so a nested shell ends up dropped by the HTML parser.
    | Antigravity (Google) | text rule only (post-write hooks not yet exposed) | `.agents/rules/workflow.md` |
    | GitHub Copilot | text rule only (no hooks API) | `.github/copilot-instructions.md` |
 
+   Claude Code adds two more backstops of its own. A `commit-before-stop.sh`
+   Stop hook refuses to end a turn with a pile of uncommitted work on a feature
+   branch (loop-safe, disable with `WEBJS_NO_COMMIT_STOP=1`), and a
+   `cleanup-merged-worktree.sh` PostToolUse hook removes a merged branch's
+   worktree after a `gh pr merge`.
+
    The `.hooks/pre-commit` hook blocks commits to main and nothing else;
    `webjs test` + `webjs check` run in CI (`.github/workflows/ci.yml`) on
    every PR and push to main, regardless of which agent (or human) made

package/templates/CLAUDE.md

@@ -1,2 +1,24 @@
 @AGENTS.md
 @CONVENTIONS.md
+
+# 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.
+
+- 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`).
+
+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.