@webjsdev/cli 0.10.47 → 0.10.48

package/lib/create.js

@@ -621,6 +621,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       await mkdir(dirname(join(appDir, dest)), { recursive: true });
       let content = await readFile(src, 'utf8');
       content = content.replace(/\{\{APP_NAME\}\}/g, name);
+      // AGENTS.md carries a template-specific build playbook: the full-stack
+      // (UI) playbook or the api (backend) one. The shared meta-rules (required
+      // context-gathering, strict typing, data) live in AGENTS.md itself; only
+      // the `{{PLAYBOOK}}` section swaps, so the two stay single-sourced. The
+      // partials live under templates/partials/ and are NOT copied as app files.
+      if (f === 'AGENTS.md') {
+        const playbookFile = isApi ? 'agents-playbook-api.md' : 'agents-playbook-fullstack.md';
+        const playbook = await readFile(join(TEMPLATES, 'partials', playbookFile), 'utf8');
+        content = content.replace('{{PLAYBOOK}}', () => playbook.trimEnd());
+      }
       if (isBun) {
         if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
         else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
@@ -639,7 +649,23 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   const repoRootSkill = resolve(__dirname, '..', '..', '..', '.agents', 'skills', 'webjs');
   const skillSrc = existsSync(bundledSkill) ? bundledSkill : repoRootSkill;
   if (existsSync(skillSrc)) {
-    await cp(skillSrc, join(appDir, '.agents', 'skills', 'webjs'), { recursive: true });
+    const skillDest = join(appDir, '.agents', 'skills', 'webjs');
+    await cp(skillSrc, skillDest, { recursive: true });
+    // Bun runtime (#541): the skill's runnable commands are authored in the
+    // canonical npm forms, so derive the bun flavor on copy, the same way the
+    // agent-config markdown above goes through bunifyProse. references/runtime.md
+    // is EXCLUDED on purpose: it is the deliberate node-vs-bun command matrix,
+    // and rewriting its npm column would destroy the comparison it exists to
+    // make.
+    if (isBun) {
+      const { readdir } = await import('node:fs/promises');
+      const entries = await readdir(skillDest, { recursive: true, withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith('.md') || e.name === 'runtime.md') continue;
+        const p = join(e.parentPath, e.name);
+        await writeFile(p, bunifyProse(await readFile(p, 'utf8')));
+      }
+    }
   }
 
   // Make the Claude enforcement hooks + the git pre-commit executable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.47",
+  "version": "0.10.48",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

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

@@ -8,20 +8,17 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
 
 ## Grow the app in place (non-negotiable)
 
-- **The scaffold is a starting point with a browsable feature gallery.** It ships
-  a gallery index home, a root layout, a database wired up, and single-concept
-  demos under `app/features/` plus the `app/examples/todo` app (logic in
-  `modules/`). The gallery is reference, not part of your product. **Building a
-  real app? Learn from the gallery FIRST, then clear it, then build:** (1) skim
-  the demos relevant to your task under `app/features/<x>` for the runnable idiom
-  (the skill teaches the same and SURVIVES the clear, so you never lose it);
-  (2) run `npm run gallery:clear` to shed the whole gallery in one step (it keeps
-  the agent skill and the database wiring, and resets the home AND the root
-  layout to a token-free blank slate, no gallery palette or navbar survives; a
-  layout you already customised is kept, only its theme-toggle wiring stripped);
-  (3) regenerate the database and grow the app in place under `app/`,
-  `components/`, and `modules/<feature>/`. Keep the gallery only while exploring,
-  never ship it.
+- **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
@@ -29,12 +26,12 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
 - **`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`.
-- **Give a UI app its own design.** Define design tokens in `app/layout.ts` with
-  a palette that fits the app (after `gallery:clear` the layout is a token-free
-  blank slate; `.agents/skills/webjs/references/styling.md` is the guide).
-  Render the app and LOOK before calling UI work
-  done: `webjs check` and `webjs typecheck` pass even when a layout collapses, so
-  open every route you changed in a real browser and play through its states.
+- **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.
 
 ## Before starting ANY work
 
@@ -53,7 +50,7 @@ Read `AGENTS.md` first. Full hosted docs are at https://docs.webjs.dev.
 2. Browser tests in `test/<feature>/browser/*.test.js` for hydration, DOM, slots,
    and the client router.
 3. Documentation stays in sync on the SAME PR as the code, never a follow-up.
-4. `webjs check` must pass.
+4. `npm run check` must pass.
 5. Pre-merge self-review: before saying a PR is ready, run fresh-context review
    rounds until one round finds zero issues (minimum two rounds, rotate focus).
    Skip only for a one-line trivial change.

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

@@ -212,8 +212,8 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 ## Testing Defaults
 
 - Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
-- Add a browser test (`webjs test --browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
-- Render the app and LOOK for any UI change: `webjs check` and `webjs typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
+- Add a browser test (`npm run test:browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
+- Render the app and LOOK for any UI change: `npm run check` and `npm run typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.
 - WebJs runs on Node 24+ AND Bun. Prove a runtime-sensitive change (serializer, listener, streams, `node:crypto`, the TS stripper) on both.
 
 ## Common Mistakes To Avoid

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -53,9 +53,10 @@ Configure providers once in a `.server.ts` file. `createAuth` returns
 `handlers` (the OAuth redirect endpoints).
 
 ```ts
-// lib/auth.server.ts
+// modules/auth/auth.server.ts
 import { createAuth, Credentials, Google, GitHub } from '@webjsdev/server';
 import { db } from '#db/connection.server.ts';
+import { compare } from './password.server.ts';
 
 export const { auth, signIn, signOut, handlers } = createAuth({
   providers: [
@@ -154,7 +155,7 @@ is produced, so a logged-out visitor never receives protected markup.
 ```ts
 // app/dashboard/page.ts
 import { html, redirect } from '@webjsdev/core';
-import { auth } from '#lib/auth.server.ts';
+import { auth } from '#modules/auth/auth.server.ts';
 
 export default async function Dashboard() {
   const session = await auth();
@@ -197,7 +198,7 @@ default page.
 ```ts
 // app/admin/page.ts
 import { html, forbidden, unauthorized } from '@webjsdev/core';
-import { auth } from '#lib/auth.server.ts';
+import { auth } from '#modules/auth/auth.server.ts';
 
 export default async function Admin() {
   const session = await auth();
@@ -227,8 +228,10 @@ an `ActionResult` failure envelope with a status the client can act on.
 ```ts
 // modules/posts/actions/delete-post.server.ts
 'use server';
-import { auth } from '#lib/auth.server.ts';
+import { eq } from 'drizzle-orm';
+import { auth } from '#modules/auth/auth.server.ts';
 import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
 
 export async function deletePost(input: { id: string }) {
   const session = await auth();

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -108,7 +108,7 @@ export function WS(ws, req) {
 }
 ```
 
-`broadcast(path, data, opts?)` fans out to all clients on `path`; `opts.except` skips one socket (typically the sender). `clientCount(path)` returns the live count. Single-instance by default; wire Redis pub/sub yourself for multi-instance.
+`broadcast(path, data, opts?)` fans out to all clients on `path`; `opts.except` skips one socket (typically the sender). Single-instance by default; wire Redis pub/sub yourself for multi-instance.
 
 ## File storage
 

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -142,17 +142,18 @@ Actions: `append` / `prepend` (child of the target id), `before` / `after` (sibl
 ```ts
 // app/post/[id]/route.ts
 import { stream, streamResponse, acceptsStream, broadcast } from '@webjsdev/server';
+import { escapeText } from '@webjsdev/core';
 
 export async function POST(req: Request, { params }) {
   const comment = await addComment(params.id, await req.formData());
-  const parts = stream.append('comments', `<li>${escapeHtml(comment.text)}</li>`);
+  const parts = stream.append('comments', `<li>${escapeText(comment.text)}</li>`);
   broadcast(`post:${params.id}`, parts);              // fan out to every viewer
   if (acceptsStream(req)) return streamResponse(parts);
-  return Response.redirect(`/post/${params.id}`, 303); // no-JS fallback
+  return Response.redirect(new URL(`/post/${params.id}`, req.url), 303); // no-JS fallback
 }
 ```
 
-`stream.*` escapes the target id but NOT the content, so escape any user substring yourself, exactly like an `html` hole.
+`stream.*` escapes the target id but NOT the content, so escape any user substring yourself with `escapeText` (from `@webjsdev/core`), exactly like an `html` hole.
 
 ## Streaming (Suspense and RPC)
 

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -24,7 +24,7 @@ In Next, `redirect()` works in Server Components, Actions, and Route Handlers al
 // route.ts WRONG: redirect() is uncaught here.
 export async function GET() { redirect('/login'); }
 // route.ts RIGHT: return a real redirect Response.
-export async function GET() { return Response.redirect(new URL('/login', req.url), 303); }
+export async function GET(req: Request) { return Response.redirect(new URL('/login', req.url), 303); }
 ```
 
 Do NOT throw `redirect()` from a page `action` to bounce a form POST either. The method-preserving 307 default re-POSTs the body and re-runs the mutation. Return an `ActionResult` with a `redirect` field instead (a 303 PRG), or throw only for a real external redirect.

package/templates/.agents/skills/webjs/references/service-worker.md

@@ -75,4 +75,4 @@ Or rely on the worker's own update lifecycle to phase it out.
 
 After adding the registration snippet, load the app, then open the browser devtools Application panel and confirm a worker is registered and activated for the origin. To exercise the offline path, visit a page (so it caches), then toggle offline in devtools and reload: a previously visited page should serve from cache, and an unvisited URL should render `public/offline.html`. Confirm the JS-off baseline is unchanged by disabling JavaScript and checking that no worker registers and navigation still works as a plain server-rendered app.
 
-Do not register the worker until the offline experience is something you actually want, because a registered worker keeps serving cached shells to returning visitors until its cache is evicted by a new deploy build id.
+Do not register the worker until the offline experience is something you actually want. Once registered, a worker changes caching for returning visitors: navigations stay network-first (an online visitor gets fresh server HTML), assets are served stale-while-revalidate, and the cached page shell is served only when the visitor is offline, until a new deploy build id evicts the cache.

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

@@ -73,7 +73,7 @@ Avoid `@apply`: it hides which utilities a class uses and creates a second sourc
 An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
 
 ```ts
-// components/ui/button.ts  (webjs ui add button, themed to your app)
+// components/ui/button.ts  (npx webjsdev ui add button, themed to your app)
 import { cn } from '#lib/utils/cn.ts';
 const BASE = 'inline-flex cursor-pointer items-center justify-center ...';
 const VARIANTS = { default: 'bg-primary text-primary-foreground ...', secondary: '...' } as const;
@@ -91,7 +91,7 @@ html`<button class=${buttonClass({ variant: 'secondary', size: 'sm' })} @click=$
 
 Why a class helper (not a `<ui-button>` wrapper): it adds NO indirection, so the element stays native (`@click`, `?disabled`, form submission, focus, a11y all just work) and the markup stays readable, while every button shares one source of truth (so no button can forget `cursor-pointer` or drift). Put the affordance every variant needs (like `cursor-pointer`) on the shared BASE.
 
-**Default: `webjs ui add`, then modify. Do not hand-write a primitive from scratch.** For a repeated primitive with variants, run `webjs ui add <name>` then trim and theme the copied source. The scaffold already ships the `cn` prerequisite at `lib/utils/cn.ts`, so `add` works out of the box (a non-scaffold app runs `webjs ui init` once first to write `components.json`, the `cn` util, and the design tokens). The kit is shadcn-style, so `add` COPIES the helper's source INTO your `components/ui/` and you own and edit it exactly as freely as code you typed yourself. That is the key point: `add`-then-modify and hand-writing end at the SAME place (owned, editable class-helper source), so the difference is only the STARTING POINT. `add` starts you from vetted, variant-complete source you then adapt (and the copied header spells out the primitive's accessibility obligations), where hand-writing starts from a blank file and re-derives all of it for no benefit. Theme it to YOUR app (change the class values so the helper produces YOUR look, rather than bending your app to the kit's defaults) and keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). Hand-author a primitive yourself ONLY for a one-off the kit does not cover, or a deliberate opt-out of the kit. Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
+**Default: `npx webjsdev ui add`, then modify. Do not hand-write a primitive from scratch.** For a repeated primitive with variants, run `npx webjsdev ui add <name>` then adapt the copied source (add, remove, restructure, or theme it as your app needs). The scaffold already ships the `cn` prerequisite at `lib/utils/cn.ts`, so `add` works out of the box (a non-scaffold app runs `npx webjsdev ui init` once first to write `components.json`, the `cn` util, and the design tokens). The kit is shadcn-style, so `add` COPIES the helper's source INTO your `components/ui/` and you own and edit it exactly as freely as code you typed yourself. That is the key point: `add`-then-modify and hand-writing end at the SAME place (owned, editable class-helper source), so the difference is only the STARTING POINT. `add` starts you from vetted, variant-complete source you then adapt (and the copied header spells out the primitive's accessibility obligations), where hand-writing starts from a blank file and re-derives all of it for no benefit. You own the copied source and can add, remove, restructure, or theme it however your app needs: change the class values so the helper produces YOUR look (rather than bending your app to the kit's defaults), keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout), and add variants the kit does not ship. Hand-author a primitive yourself ONLY for a one-off the kit does not cover, or a deliberate opt-out of the kit. Reserve `lib/utils/ui.ts` `html`-fragment helpers for repeated markup chunks; reserve `components/ui/*` class helpers for themed primitives with variants.
 
 ## Accessible native controls
 
@@ -119,9 +119,14 @@ The default stack is a static compiled Tailwind stylesheet (`css:build` compiles
     --background:       light-dark(#ffffff, #1e2226);
     --foreground:       light-dark(#191c20, #dee2e6);
     --card:             light-dark(#f7f8fa, #313539);
+    --primary:          light-dark(#1e2226, #dee2e6);
+    --secondary:        light-dark(#eef0f3, #3a3f45);
+    --muted:            light-dark(#f1f3f5, #2a2e33);
     --muted-foreground: light-dark(#565c64, #94989c);
+    --accent:           light-dark(#e9ecef, #383d43);
     --border:           light-dark(#e2e5e9, #3d434b);
-    --primary:          light-dark(#1e2226, #dee2e6);
+    --ring:             light-dark(#9aa1a9, #6c737b);
+    --destructive:      light-dark(#b3261e, #f2b8b5);
     /* a derived token tracks BOTH themes for free via var(--primary) */
     --primary-tint: color-mix(in srgb, var(--primary) 22%, transparent);
   }

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

@@ -4,7 +4,7 @@
 
 - The four test layers (unit, browser, e2e, smoke) and where each file lives.
 - The `handle()` harness from `@webjsdev/server/testing` for driving the real request pipeline against a native `Response`.
-- `webjs test` and `webjs test --browser`, plus when a browser or e2e test is REQUIRED (hydration, client router, slots, custom-element upgrade).
+- `npm run test` and `npm run test:browser`, plus when a browser or e2e test is REQUIRED (hydration, client router, slots, custom-element upgrade).
 - Bun cross-runtime parity for runtime-sensitive code.
 - Rendering the app and LOOKING for visual defects a static check cannot catch (a collapsed or reflowing layout).
 - Convention validation with `webjs check`.
@@ -27,12 +27,12 @@ Assert only on what the layer needs. A block that inspects only the HTTP respons
 ## App runners (`webjs test`)
 
 ```sh
-webjs test              # runtime test runner over everything not under browser/ or e2e/
-webjs test --browser    # web-test-runner against test/**/browser/**
-WEBJS_E2E=1 webjs test   # adds the e2e layer
+npm run test              # unit + browser tests (both layers; e2e only with WEBJS_E2E=1)
+npm run test:browser      # web-test-runner against test/**/browser/**
+WEBJS_E2E=1 npm run test  # adds the e2e layer
 ```
 
-`webjs test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
+`npm run test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
 
 A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
 
@@ -110,11 +110,11 @@ A layout bug (a board that collapses, cells of unequal size, a grid that resizes
 
 WebJs runs on Node 24+ or Bun. The Node suite is the source of truth; an additive Bun matrix re-runs the runtime-sensitive suite under Bun to catch the long tail of cross-runtime incompatibilities (a `node:*` API Bun implements differently, a crypto or stream edge case, an error-message-format quirk).
 
-Bun parity is part of the definition of done. A change to a runtime-sensitive surface (the serializer, the `node:http` vs `Bun.serve` listener and request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) is NOT done until you run the Bun matrix green AND add or update a `test/bun/<feature>.mjs` cross-runtime assertion. Run it with `node scripts/run-bun-tests.js` (needs `bun` on PATH).
+If your app targets Bun, Bun parity is part of the definition of done. A change to a runtime-sensitive surface (the serializer, the `node:http` vs `Bun.serve` listener and request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) is NOT done until you also run your suite under the Bun runtime (needs `bun` installed) and add a cross-runtime assertion for the touched surface.
 
 ## Convention validation (`webjs check`)
 
-`webjs check` is the correctness validator. Every rule catches code that is wrong to ship (a crash, a security leak, a type-strip failure), plus the `no-scaffold-placeholder` sentinel for unreplaced scaffold content. Run it and fix every violation before considering the change done (`webjs check --json` for an agent loop, `webjs check --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
+`npm run check` is the correctness validator. Every rule catches code that is wrong to ship (a crash, a security leak, a type-strip failure), plus the `no-scaffold-placeholder` sentinel for unreplaced scaffold content. Run it and fix every violation before considering the change done (`npm run check -- --json` for an agent loop, `npm run check -- --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
 
 ## What NOT to do
 

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

@@ -128,18 +128,18 @@ With no route literal (or before you generate route types), `params` is `Record<
 
 Type page metadata with the exported `Metadata` type (and `MetadataContext` for the `generateMetadata` argument), the same ergonomics as Next.js's `import type { Metadata } from 'next'`.
 
-### The generated route union (`webjs types`)
+### The generated route union (`npx webjsdev types`)
 
-Run `webjs types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
+Run `npx webjsdev types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
 
 - The `Route` href type: `navigate('/blog/anything')` passes, `navigate('/nonexistent')` is an error. Until you generate the types, `Route` is `string` (unconstrained, non-breaking for JSDoc and un-generated apps).
 - Per-route `params`: `PageProps<'/blog/[slug]'>['params']` becomes `{ slug: string }`.
 
 ```sh
-webjs types     # writes .webjs/routes.d.ts (route count printed)
+npx webjsdev types     # writes .webjs/routes.d.ts (route count printed)
 ```
 
-`webjs dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `webjs types` once and add `.webjs/routes.d.ts` to `include`. This is webjs's no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
+`npm run dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `npx webjsdev types` once and add `.webjs/routes.d.ts` to `include`. This is the WebJs no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
 
 ### The `webjs` config block and auth user
 

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -2,12 +2,12 @@
 
 Load this when the app uses `@webjsdev/ui` (a `components.json` is present), OR
 when you are about to add a UI primitive (button, card, input, badge) to a fresh
-app that has not initialised the kit yet: running `webjs ui init` then
-`webjs ui add <name>` is HOW the kit comes to exist, and it is the default for a
+app that has not initialised the kit yet: running `npx webjsdev ui init` then
+`npx webjsdev ui add <name>` is HOW the kit comes to exist, and it is the default for a
 repeated primitive over hand-writing one from scratch. `@webjsdev/ui` is the shadcn-style
 kit for WebJs. The source is copied into your repo (`components/ui/`), so you own
-and edit it exactly as freely as code you wrote yourself (the copied file is
-yours to trim and theme). Two tiers:
+and edit it exactly as freely as code you wrote yourself, and can add, remove,
+restructure, or theme it however your app needs. Two tiers:
 
 - **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
   class strings (`buttonClass({ variant })`, `cardClass()`), composed with
@@ -32,25 +32,25 @@ paste-ready structure on demand:
   kit inventory (each component's tier, helper signatures, npm deps); pass
   `{ name: "accordion" }` for one component's helper signatures, the paste-ready
   structural example, the accessibility header, and deps.
-- **CLI**: `webjs ui list` (inventory), `webjs ui view <name>` (the projected
+- **CLI**: `npx webjsdev ui list` (inventory), `npx webjsdev ui view <name>` (the projected
   view plus the full source). Same data as the MCP tool (one shared projector).
 
 So the loop is: `add` the component, then query `ui <name>` (MCP) or
-`webjs ui view <name>` for the accessible structure, paste it, and fill it in.
+`npx webjsdev ui view <name>` for the accessible structure, paste it, and fill it in.
 
 ## Setup and resolution
 
-- `webjs ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+- `npx webjsdev ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
   tokens the helpers render against (`--background`, `--foreground`,
   `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
   clean exit means the kit is styled. `add` self-heals the tokens if they go
   missing.
 - Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you
-  to the installed version; run `webjs ui diff` to see where your local copies
+  to the installed version; run `npx webjsdev ui diff` to see where your local copies
   drift from the upstream (that command alone compares against the live registry).
 
-## Inventory (run `webjs ui list` or the MCP `ui` tool for the authoritative, current set)
+## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 
 **Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
 breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
@@ -66,7 +66,7 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
 - A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
   The unquoted `${...}` is a normal `html` attribute hole.
 - Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
-  the tokens are missing (re-run `webjs ui init` or let `add` self-heal them).
+  the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the
   standard WebJs component model (`references/components.md`).
 

package/templates/.cursorrules

@@ -1,20 +1,20 @@
 # WebJs app rules (Cursor)
 
-Cursor reads `AGENTS.md` natively; this file points you at it and the agent
+Cursor reads `AGENTS.md` natively. This file points you at it and the agent
 skill, and carries the commit rule.
 
 - **Read `AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (the guide to
   building a WebJs app; it routes to focused references under
-  `.agents/skills/webjs/references/` that you load only when a task needs them).
-- **The scaffold ships a browsable feature gallery** (single-concept demos under
-  `app/features/` plus the `app/examples/todo` app, with logic in `modules/`).
-  It is reference to learn the idioms from, not part of your product.
-- **Building a real app? Learn from the gallery FIRST, then clear it, then
-  build.** Skim the demos relevant to your task for the runnable idiom (the skill
-  teaches the same and SURVIVES the clear, so you never lose it), then run
-  `npm run gallery:clear` to shed the gallery and reset the home, then grow the
-  app in place: add routes under `app/`, components under `components/`, features
-  under `modules/<feature>/`, and keep server-only code behind `.server.ts`.
+  `.agents/skills/webjs/references/`). These are required context, not optional
+  reading: WebJs is not React, Next, or Lit, so gather this context before you
+  write code.
+- **Study the shipped examples, then clear them and build.** The scaffold ships
+  a browsable showcase to learn the real idioms from (a full-stack app ships a
+  UI feature gallery, the api template ships a backend-features showcase). Read
+  the parts that match your task, run `npm run gallery:clear` to shed the
+  showcase and reset to a clean base, then grow the app in place: add routes
+  under `app/`, features under `modules/<feature>/`, and keep server-only code
+  behind `.server.ts`. `AGENTS.md` carries the full template-specific playbook.
 - **Use the wired-up database (Drizzle)** for persistence. Never a JSON file, an
   in-memory array, or localStorage.
 - **Commit per logical unit** as soon as it is complete, and never commit to

package/templates/AGENTS.md

@@ -1,69 +1,56 @@
 # AGENTS.md for {{APP_NAME}}
 
-This is a WebJs app: AI-first, web-components-first, no build step. Read this
-before editing any file. It is deliberately short. The framework knowledge
-lives in one place that every AI tool can read.
-
-## Building features
-
-Read `.agents/skills/webjs/SKILL.md` first. It is the guide to building a WebJs
-app: it helps you choose the right layer, reach for the right export, and avoid
-the WebJs-specific mistakes that Next.js or Lit habits cause. It routes to
-focused references under `.agents/skills/webjs/references/` that you load only
-when a task needs them. The full hosted docs are at https://docs.webjs.dev.
-
-## Grow this app in place
-
-This scaffold is a starting point. It ships a gallery index home
-(`app/page.ts`), a root layout with a neutral design-token palette
-(`app/layout.ts`), a database wired up (`db/`), and a densely-commented feature
-gallery: single-concept demos under `app/features/` plus the `app/examples/todo`
-app, with logic in `modules/`. The gallery is reference to learn the idioms
-from, not part of your product.
-
-**Building a real app? Learn from the gallery FIRST, then clear it, then build.**
-The order matters:
-
-1. **Gather context.** Skim the demos relevant to your task under
-   `app/features/<x>` (and `app/examples/todo`) for the runnable idiom. You do
-   not have to read all of it, and you never lose it: the skill at
-   `.agents/skills/webjs/` teaches the same patterns and SURVIVES the clear, so
-   clearing is not a knowledge-loss event, the gallery is just a runnable bonus.
-2. **Clear it.** Run `npm run gallery:clear` to shed the whole gallery in one
-   step: it removes `app/features/`, `app/examples/`, the demo `modules/`, the
-   gallery's example design system (`components/ui/`, the theme-toggle), the
-   example tests, and the demo `todos` table, and resets `app/page.ts` to a
-   minimal home AND `app/layout.ts` to a token-free blank slate (OS system
-   colours, no navbar, no palette). A layout you already customised (the gallery
-   brand removed) is KEPT, with only the theme-toggle wiring stripped. It KEEPS
-   the agent skill, the database wiring, and `lib/utils/cn.ts` (the
-   `webjs ui add` prerequisite).
-3. **Build.** Regenerate the database (`npm run db:generate` then `npm run
-   db:migrate`), then grow the app in place: routes under `app/`, components
-   under `components/`, features under `modules/<feature>/`, server-only code
-   behind `.server.ts`. Build the app's OWN design system from the blank slate:
-   define design tokens in `app/layout.ts` and pull primitives with
-   `npx webjsdev ui add <name>` then theme the copied source (you own it, so
-   modify it rather than hand-writing a primitive from scratch), following
-   `.agents/skills/webjs/references/styling.md`.
-
-If you are only exploring, keep the gallery and browse it.
-
-## Commands
-
-```sh
-npm install
-npm run gallery:clear  # shed the demo gallery before building a real app
-npm run dev            # dev server at http://localhost:8080
-npm run start          # production server
-npm test               # unit + browser tests
-npm run typecheck
-npx webjsdev check     # correctness checks
-npx webjsdev ui add <name>   # add a ui-* component on demand
-```
-
-## Data
-
-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 store app data in JSON files, in-memory arrays, or localStorage.
+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://docs.webjs.dev.
+
+{{PLAYBOOK}}
+
+## Type everything (all templates)
+
+Define explicit TypeScript interfaces and discriminated unions for your data
+payloads and action inputs and outputs (and, in a UI app, component props and
+optimistic updates). Narrow an `ActionResult` with
+`if (result.success && result.data)`. Never reach for `any` or a loose
+`as any` cast.
+
+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/CONVENTIONS.md

@@ -17,12 +17,13 @@ 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 feature gallery to learn from.** Single-concept demos
-  under `app/features/` plus the `app/examples/todo` app, with logic in
-  `modules/`. When you build a real app: learn from the gallery FIRST (skim the
-  demos relevant to your task; the skill teaches the same and survives the
-  clear), then run `npm run gallery:clear` to shed the demos and reset the home,
-  then grow the app in place.
+- **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.
 - **Progressive enhancement is the default.** Pages render as HTML, `<a>`
   navigates, `<form>` + a page action submits, all with JavaScript off; opt into
   interactivity per behaviour inside a component.

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

@@ -0,0 +1,67 @@
+## Build a backend API (api template)
+
+This template has NO UI: no layout, no pages, no components, no CSS. It ships a
+backend-features showcase under `app/api/features/`, a set of JSON and HTTP
+endpoints that demonstrate the `route()` adapter, input validation, and rate
+limiting, with logic in `modules/`. Build in this order.
+
+### 1. Study the showcase, then clear it
+
+Read the endpoints under `app/api/features/` so you copy the real idiom: a
+`route.ts` handler, the `route()` adapter over a `'use server'` action,
+`validate`, and rate limiting. Then run `npm run gallery:clear` to shed the
+showcase and reset to a clean base. The skill teaches the same patterns and
+survives the clear, so the showcase 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`. Write a seed script at `db/seed.server.ts` and run
+`npm run db:seed` so endpoints return real rows while you build, instead of
+empty arrays. Put reads in `modules/<feature>/queries/*.server.ts` and writes
+in `modules/<feature>/actions/*.server.ts`, one function per file.
+
+### 3. Build endpoints
+
+Expose HTTP with a `route.ts` handler (named `GET` / `POST` / `PUT` / `PATCH` /
+`DELETE` exports), each `(request, { params }) => Response | value` (a returned
+plain value auto-JSONs, so return the data directly unless you need headers or
+a status). To publish a `'use server'` action as REST, use the `route()`
+adapter from `@webjsdev/server`, which merges the query, the route params, and
+the JSON body into one input object and JSON-responds. Full reference:
+`.agents/skills/webjs/references/data-and-actions.md` and
+`.agents/skills/webjs/references/routing-and-pages.md`.
+
+### 4. Secure every endpoint
+
+A `route.ts` handler is NOT covered by the action-RPC CSRF and error-sanitizing
+layer, so on every mutating endpoint you must: authenticate the request
+(sessions and auth are in `.agents/skills/webjs/references/auth-and-sessions.md`),
+pass a `validate` function, rate-limit it, and log without leaking secrets. For
+cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
+`credentials: true` set an explicit origin allowlist, never `'*'`.
+
+### 5. Verify before you call it done
+
+Run each of these and fix what it reports, in order:
+
+- `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run typecheck` (zero type errors).
+- `npm test` (unit tests for the endpoints and modules you built).
+
+Then boot `npm run dev` and probe each endpoint for the expected status and JSON
+shape.
+
+### Commands
+
+```sh
+npm install
+npm run gallery:clear   # shed the backend-features showcase before building
+npm run dev             # dev server at http://localhost:8080
+npm run start           # production server
+npm test                # unit + browser tests
+npm run typecheck
+npm run check           # correctness checks
+npm run db:generate && npm run db:migrate
+```

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

@@ -0,0 +1,124 @@
+## 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 each of these and fix what it reports, in order:
+
+- `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run typecheck` (zero type errors).
+- `npm test` (unit and browser tests for the features you built).
+- `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 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 check                # correctness checks
+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
+```