@webjsdev/cli 0.10.46 → 0.10.48

package/bin/webjs.js

@@ -497,28 +497,31 @@ async function main() {
       break;
     }
     case 'ui': {
-      // Delegate to @webjsdev/ui. Bundled as a hard dependency of
-      // @webjsdev/cli, so `npm install -g webjsdev` pulls it in
-      // automatically, and `webjs ui add button` works out of the box
-      // without an extra install in user projects.
-      const { createRequire } = await import('node:module');
-      const req = createRequire(import.meta.url);
+      // Delegate to @webjsdev/ui's bin. It is a hard dependency of
+      // @webjsdev/cli, so `npm install -g webjsdev` pulls it in automatically
+      // and `webjs ui add button` works without an extra install.
+      //
+      // Resolve via resolveBin, NOT req.resolve('@webjsdev/ui/bin/webjsui.js'):
+      // the ui package's `exports` map does not list the bin subpath, so a
+      // direct subpath resolve throws ERR_PACKAGE_PATH_NOT_EXPORTED even though
+      // the file exists, which surfaced as a misleading "could not be resolved"
+      // (#1073). resolveBin resolves the `.` export, walks to the package root,
+      // and reads the `bin` map, exactly as `db` / `test --browser` do.
       let entry;
       try {
-        entry = req.resolve('@webjsdev/ui/bin/webjsui.js');
+        // Hard-dep path: @webjsdev/ui in the CLI's own node_modules.
+        entry = resolveBin(join(__dirname, '..'), '@webjsdev/ui', 'webjsui');
       } catch {
-        // Fallback: try resolving from the user's cwd in case of weird
-        // workspace setups.
+        // Fallback: the user installed @webjsdev/ui directly in their project.
         try {
-          const userReq = createRequire(join(process.cwd(), 'package.json'));
-          entry = userReq.resolve('@webjsdev/ui/bin/webjsui.js');
+          entry = resolveBin(process.cwd(), '@webjsdev/ui', 'webjsui');
         } catch {
           console.error('@webjsdev/ui could not be resolved.');
           console.error('Reinstall the CLI:  npm install -g webjsdev');
           process.exit(1);
         }
       }
-      const child = spawn('node', [entry, ...rest], { stdio: 'inherit', cwd: process.cwd() });
+      const child = spawn(process.execPath, [entry, ...rest], { stdio: 'inherit', cwd: process.cwd() });
       child.on('exit', (code) => process.exit(code ?? 0));
       break;
     }

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.46",
+  "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,11 +91,11 @@ 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.
 
-**Own and theme your copy.** `webjs ui add <name>` copies the primitive INTO your `components/ui/`, so you own it. 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. Keep only the parts you use (the gallery's `cardClass` is surface-only, since its panels vary their own padding and layout). 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
 
-A cleared, growing app hand-authors its own controls, so accessibility is your job (the `@webjsdev/ui` primitives carry their own, but a raw `<button>` / `<input>` does not). Three habits keep hand-authored interactive markup accessible on BOTH the JS and no-JS paths:
+Even with the kit, an app hand-authors SOME markup (a one-off primitive the kit does not cover, or the native element you wrap a class helper around), and there accessibility is your job (the `@webjsdev/ui` primitives carry their own, but a raw `<button>` / `<input>` does not). Three habits keep hand-authored interactive markup accessible on BOTH the JS and no-JS paths:
 
 - **Associate a label with its control.** `<label for="email">` paired with `<input id="email">` (or wrap the control in the `<label>`), so a click on the label focuses the field and a screen reader announces it.
 - **State a toggle's pressed state.** A button that toggles carries `aria-pressed=${on}` so assistive tech announces on/off, not just "button".
@@ -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

@@ -1,8 +1,13 @@
 # The `@webjsdev/ui` component kit
 
-Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
-shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
-so you own and edit it. Two tiers:
+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 `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, 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
@@ -27,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,
@@ -61,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,68 +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>`, 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
+```