From d2d5a850a3e9de3e361547c2060711a22f52d25e Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 14:53:58 +0530
Subject: [PATCH 01/53] chore: start the scaffold feature-gallery (#824)


From 1990dc202192bd50f1ac6b70c65094cbd4d1a272 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 15:02:12 +0530
Subject: [PATCH 02/53] feat(cli): gallery flagship /todo example (optimistic +
 a11y + PE + modules) (#824)

The first idiomatic gallery example: app-thin route + modules/todo logic
(query, 3 actions, the <todo-app> component), densely commented to teach
optimistic UI (with when-not-to), the a11y <label for> pattern, progressive
enhancement, the .server boundary, and the Drizzle rc.3 read/write patterns.
Establishes the per-feature app-thin + modules-logic structure the rest of the
gallery follows.
---
 .../gallery/app/examples/todo/page.ts         |  33 ++++++
 .../todo/actions/create-todo.server.ts        |  15 +++
 .../todo/actions/delete-todo.server.ts        |  12 +++
 .../todo/actions/toggle-todo.server.ts        |  21 ++++
 .../modules/todo/components/todo-app.ts       | 100 ++++++++++++++++++
 .../modules/todo/queries/list-todos.server.ts |  18 ++++
 .../templates/gallery/modules/todo/types.ts   |  12 +++
 7 files changed, 211 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/examples/todo/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/actions/toggle-todo.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/components/todo-app.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/todo/types.ts

diff --git a/packages/cli/templates/gallery/app/examples/todo/page.ts b/packages/cli/templates/gallery/app/examples/todo/page.ts
new file mode 100644
index 000000000..711a91b99
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/todo/page.ts
@@ -0,0 +1,33 @@
+// A THIN route adapter: app/ is routing only. It fetches the initial data
+// (server-side) via the 'use server' query and renders the interactive
+// component, plus a page `action` for the no-JS write path. All the real logic
+// lives in modules/todo/. This is the idiomatic app-thin + modules-logic split.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core'; // Metadata is a @webjsdev/core type
+import { listTodos } from '#modules/todo/queries/list-todos.server.ts';
+import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
+import { toggleTodo } from '#modules/todo/actions/toggle-todo.server.ts';
+import { deleteTodo } from '#modules/todo/actions/delete-todo.server.ts';
+import '#modules/todo/components/todo-app.ts';
+
+export const metadata: Metadata = { title: 'Todo (optimistic UI) | examples' };
+
+export default async function TodoExample() {
+  // SSR-fetched and seeded, so <todo-app> paints the real list on first byte.
+  const todos = await listTodos();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Optimistic todo</h1>
+    <todo-app .todos=${todos}></todo-app>
+  `;
+}
+
+// No-JS write path: the component's <form>s post here; with JS the component
+// intercepts and mutates optimistically instead. Success is a 303 PRG.
+export async function action({ formData }: { formData: FormData }) {
+  const intent = String(formData.get('intent') ?? '');
+  const id = String(formData.get('id') ?? '');
+  if (intent === 'create') return createTodo({ title: String(formData.get('title') ?? '') });
+  if (intent === 'toggle') return toggleTodo({ id });
+  if (intent === 'delete') return deleteTodo({ id });
+  return { success: false as const, error: 'Unknown action.', status: 400 };
+}
diff --git a/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts b/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
new file mode 100644
index 000000000..e12040e3e
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
@@ -0,0 +1,15 @@
+'use server';
+// A MUTATION (no `method` export defaults to POST: CSRF-protected, rich body).
+// Args and the returned ActionResult round-trip through webjs's serializer.
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { Todo } from '../types.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function createTodo(input: { title: string }): Promise<ActionResult<Todo>> {
+  const title = String(input?.title ?? '').trim();
+  if (!title) return { success: false, error: 'A task needs a title.', status: 400 };
+  // rc.3 mutation: `.returning()` takes NO field args in rc.3 (agent-docs/orm.md).
+  const [row] = await db.insert(todos).values({ title }).returning();
+  return { success: true, data: row as Todo };
+}
diff --git a/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts b/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
new file mode 100644
index 000000000..17c27138e
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
@@ -0,0 +1,12 @@
+'use server';
+import { eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function deleteTodo(input: { id: string }): Promise<ActionResult<{ id: string }>> {
+  const id = String(input?.id ?? '');
+  if (!id) return { success: false, error: 'Missing id.', status: 400 };
+  await db.delete(todos).where(eq(todos.id, id));
+  return { success: true, data: { id } };
+}
diff --git a/packages/cli/templates/gallery/modules/todo/actions/toggle-todo.server.ts b/packages/cli/templates/gallery/modules/todo/actions/toggle-todo.server.ts
new file mode 100644
index 000000000..d06c21ab5
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/actions/toggle-todo.server.ts
@@ -0,0 +1,21 @@
+'use server';
+import { eq } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { Todo } from '../types.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+// `completed` is explicit on the JS path; omit it on the no-JS <form> path and
+// the server reads the row and flips it (so the example degrades without JS).
+export async function toggleTodo(input: { id: string; completed?: boolean }): Promise<ActionResult<Todo>> {
+  const id = String(input?.id ?? '');
+  if (!id) return { success: false, error: 'Missing id.', status: 400 };
+  let completed = input?.completed;
+  if (typeof completed !== 'boolean') {
+    const cur = await db.query.todos.findFirst({ where: { id } });
+    if (!cur) return { success: false, error: 'Not found.', status: 404 };
+    completed = !cur.completed;
+  }
+  const [row] = await db.update(todos).set({ completed }).where(eq(todos.id, id)).returning();
+  return { success: true, data: row as Todo };
+}
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
new file mode 100644
index 000000000..a00c51e90
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -0,0 +1,100 @@
+// The interactive surface. Demonstrates: the WebComponent factory + reactive
+// prop, the DECLARATIVE optimistic() API (instant update, auto-rollback), and
+// progressive enhancement (each mutation is a <form> posting to the page action,
+// intercepted by JS for the optimistic path). All interactivity lives in a
+// component; a page/layout cannot be interactive in its own markup.
+import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { createTodo } from '../actions/create-todo.server.ts';
+import { toggleTodo } from '../actions/toggle-todo.server.ts';
+import { deleteTodo } from '../actions/delete-todo.server.ts';
+import type { Todo } from '../types.ts';
+
+type Op =
+  | { kind: 'add'; tempId: string; title: string }
+  | { kind: 'toggle'; id: string; completed: boolean }
+  | { kind: 'delete'; id: string };
+
+export class TodoApp extends WebComponent({
+  // A reactive prop: the SSR'd list arrives via `.todos=${todos}` and hydrates.
+  todos: prop<Todo[]>(Array),
+}) {
+  // One optimistic store, three ops. `.add(payload, promise)` applies `update`
+  // instantly and auto-releases when the promise settles (resolve OR reject),
+  // so there is no manual try-catch / rollback / temp-id bookkeeping.
+  private store = optimistic(this, {
+    source: () => this.todos ?? [],
+    update: (state: Todo[], op: Op): Todo[] => {
+      if (op.kind === 'add') return [{ id: op.tempId, title: op.title, completed: false, createdAt: new Date(), pending: true }, ...state];
+      if (op.kind === 'toggle') return state.map((t) => (t.id === op.id ? { ...t, completed: op.completed } : t));
+      return state.filter((t) => t.id !== op.id);
+    },
+  });
+
+  async add(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const title = String(new FormData(form).get('title') ?? '').trim();
+    if (!title) return;
+    form.reset();
+    const tempId = crypto.randomUUID();
+    const promise = createTodo({ title });
+    this.store.add({ kind: 'add', tempId, title }, promise);
+    const r = await promise;
+    if (r.success && r.data) this.todos = [r.data, ...(this.todos ?? [])];
+  }
+
+  async toggle(e: Event, todo: Todo) {
+    e.preventDefault();
+    if (todo.pending) return;
+    const completed = !todo.completed;
+    const promise = toggleTodo({ id: todo.id, completed });
+    this.store.add({ kind: 'toggle', id: todo.id, completed }, promise);
+    const r = await promise;
+    if (r.success && r.data) { const d = r.data; this.todos = (this.todos ?? []).map((t) => (t.id === todo.id ? d : t)); }
+  }
+
+  async remove(e: Event, todo: Todo) {
+    e.preventDefault();
+    if (todo.pending) return;
+    const promise = deleteTodo({ id: todo.id });
+    this.store.add({ kind: 'delete', id: todo.id }, promise);
+    const r = await promise;
+    if (r.success) this.todos = (this.todos ?? []).filter((t) => t.id !== todo.id);
+  }
+
+  render() {
+    const list = this.store.value;
+    return html`
+      <section class="grid gap-4 max-w-[520px]">
+        <!-- Add: a real <form> so it works with JS off (posts to the page action);
+             with JS, @submit intercepts and runs the optimistic path. -->
+        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)} class="flex gap-2">
+          <input type="hidden" name="intent" value="create" />
+          <input name="title" required placeholder="What needs doing?" class="flex-1 border border-border rounded-lg px-3 py-2" />
+          <button type="submit" class="px-4 py-2 rounded-lg bg-accent text-accent-fg font-semibold">Add</button>
+        </form>
+        <ul class="list-none m-0 p-0 grid gap-2">
+          ${list.map((todo) => html`
+            <li>
+              <form method="post" action="" class="flex items-center gap-3 border border-border rounded-lg px-3 py-2 ${todo.pending ? 'opacity-50' : ''}">
+                <input type="hidden" name="id" value=${todo.id} />
+                <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS
+                     @click intercepts for the optimistic toggle. -->
+                <button id="t-${todo.id}" type="submit" name="intent" value="toggle"
+                  aria-pressed=${todo.completed ? 'true' : 'false'}
+                  @click=${(e: Event) => this.toggle(e, todo)}
+                  class="w-5 h-5 rounded-full border-2 ${todo.completed ? 'bg-accent border-accent' : 'border-border'}">✓</button>
+                <!-- The title is a <label for> the toggle: clicking the text toggles
+                     the task (works on JS and no-JS paths, and screen readers). -->
+                <label for="t-${todo.id}" class="flex-1 cursor-pointer ${todo.completed ? 'line-through opacity-60' : ''}">${todo.title}</label>
+                <button type="submit" name="intent" value="delete" aria-label="Delete"
+                  @click=${(e: Event) => this.remove(e, todo)} class="text-fg-subtle">x</button>
+              </form>
+            </li>
+          `)}
+        </ul>
+      </section>
+    `;
+  }
+}
+TodoApp.register('todo-app');
diff --git a/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
new file mode 100644
index 000000000..b3dd3c64a
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
@@ -0,0 +1,18 @@
+'use server';
+// A READ is a `'use server'` action so the client (and SSR) can call it via the
+// normal import (rewritten to a typed RPC stub). `method = 'GET'` rides args in
+// the URL, is CSRF-exempt, and its result is SSR-seeded so the component does
+// not re-fetch on hydration.
+import { desc } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { todos } from '#db/schema.server.ts';
+import type { Todo } from '../types.ts';
+
+export const method = 'GET';
+
+export async function listTodos(): Promise<Todo[]> {
+  // rc.3 read: the relational query API. Do NOT use `db.select({ col })` (its
+  // projection overload trips TS2554 in rc.3). See agent-docs/orm.md.
+  const rows = await db.query.todos.findMany({ orderBy: [desc(todos.createdAt)] });
+  return rows as Todo[];
+}
diff --git a/packages/cli/templates/gallery/modules/todo/types.ts b/packages/cli/templates/gallery/modules/todo/types.ts
new file mode 100644
index 000000000..89ebe5030
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/todo/types.ts
@@ -0,0 +1,12 @@
+// WHY a hand-written interface (not `typeof todos.$inferSelect` from the schema):
+// this type is imported by the browser-shipped <todo-app> component. A VALUE
+// import from `db/*.server.ts` would pin the component to a server module and
+// crash it at load (webjs check flags it). A browser-safe shape here is safe.
+// See agent-docs/types-and-mutations.md.
+export interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+  createdAt: Date;
+  pending?: boolean; // client-only: true while an optimistic create is in flight
+}

From 63492704f886f1d492cc90753b5a40a648706794 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 15:13:09 +0530
Subject: [PATCH 03/53] feat(cli): gallery /tic-tac-toe example (client-only
 signals) (#824)

---
 .../gallery/app/examples/tic-tac-toe/page.ts  | 16 ++++++
 .../tic-tac-toe/components/tic-tac-toe.ts     | 52 +++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts

diff --git a/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts b/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
new file mode 100644
index 000000000..3b945f763
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
@@ -0,0 +1,16 @@
+// A thin route rendering a client-only component. The page runs server-side to
+// produce the SSR'd first paint (the empty board), then <tic-tac-toe> hydrates
+// and all interactivity runs client-side. Pages do not hydrate; components do.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/tic-tac-toe/components/tic-tac-toe.ts';
+
+export const metadata: Metadata = { title: 'Tic-tac-toe (client signals) | examples' };
+
+export default function TicTacToeExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Tic-tac-toe</h1>
+    <p class="text-fg-muted mb-4">Client-only interactivity with signals, no server or database.</p>
+    <tic-tac-toe></tic-tac-toe>
+  `;
+}
diff --git a/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts b/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts
new file mode 100644
index 000000000..de2942a79
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts
@@ -0,0 +1,52 @@
+// A CLIENT-ONLY interactive component: no server, no db. Demonstrates instance
+// signals as the default state primitive (read with .get() in render(), the
+// built-in SignalWatcher re-renders on change) and @click handlers. Nothing
+// here ships to the server; it is pure client interactivity in a component.
+import { WebComponent, signal, html } from '@webjsdev/core';
+
+type Cell = 'X' | 'O' | null;
+
+export class TicTacToe extends WebComponent {
+  // Instance signals are component-local (a module-scope signal would be shared
+  // across every instance and survive navigations, which is not wanted here).
+  private board = signal<Cell[]>(Array(9).fill(null));
+  private turn = signal<'X' | 'O'>('X');
+
+  private winner(b: Cell[]): Cell {
+    const lines = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
+    for (const [a, c, d] of lines) if (b[a] && b[a] === b[c] && b[a] === b[d]) return b[a];
+    return null;
+  }
+
+  private play(i: number) {
+    const b = this.board.get();
+    if (b[i] || this.winner(b)) return;
+    const next = b.slice();
+    next[i] = this.turn.get();
+    this.board.set(next);
+    this.turn.set(this.turn.get() === 'X' ? 'O' : 'X');
+  }
+
+  private reset() { this.board.set(Array(9).fill(null)); this.turn.set('X'); }
+
+  render() {
+    const b = this.board.get();
+    const win = this.winner(b);
+    const status = win ? `${win} wins` : b.every(Boolean) ? 'Draw' : `${this.turn.get()} to move`;
+    return html`
+      <div class="grid gap-3 w-fit">
+        <p class="font-semibold" aria-live="polite">${status}</p>
+        <div class="grid grid-cols-3 gap-1">
+          ${b.map((cell, i) => html`
+            <button
+              @click=${() => this.play(i)}
+              aria-label="cell ${i + 1}${cell ? `, ${cell}` : ''}"
+              class="w-14 h-14 text-2xl font-bold border border-border rounded grid place-items-center">${cell ?? ''}</button>
+          `)}
+        </div>
+        <button @click=${() => this.reset()} class="text-sm text-fg-subtle underline underline-offset-4">Reset</button>
+      </div>
+    `;
+  }
+}
+TicTacToe.register('tic-tac-toe');

From 1244433f88a525ee35729dbd419491ff92991dd6 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 15:14:32 +0530
Subject: [PATCH 04/53] feat(cli): gallery /components example (factory,
 signals, slots) (#824)

---
 .../gallery/app/examples/components/page.ts   | 13 ++++++++
 .../components/components/counter-card.ts     | 31 +++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/examples/components/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/components/components/counter-card.ts

diff --git a/packages/cli/templates/gallery/app/examples/components/page.ts b/packages/cli/templates/gallery/app/examples/components/page.ts
new file mode 100644
index 000000000..e47a24152
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/components/page.ts
@@ -0,0 +1,13 @@
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/components/components/counter-card.ts';
+
+export const metadata: Metadata = { title: 'Components (signals + slots) | examples' };
+
+export default function ComponentsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Components</h1>
+    <p class="text-fg-muted mb-4">The WebComponent factory, a reactive prop, an instance signal, and a slot.</p>
+    <counter-card label="Taps"><strong>A slotted title</strong></counter-card>
+  `;
+}
diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
new file mode 100644
index 000000000..ae351b1b3
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -0,0 +1,31 @@
+// Demonstrates the WebComponent essentials: the declare-free reactive-prop
+// factory, an instance signal for local state, a lifecycle hook, and a <slot>
+// for content projection (works in light DOM, the default). This is the core
+// component authoring shape.
+import { WebComponent, prop, signal, html } from '@webjsdev/core';
+
+export class CounterCard extends WebComponent({
+  // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
+  // (no `static properties`, no class-field `label = ''` which would clobber the
+  // accessor). Set defaults in the constructor.
+  label: prop(String),
+}) {
+  private count = signal(0); // instance signal: component-local state
+
+  constructor() {
+    super();
+    this.label = this.label || 'Clicks';
+  }
+
+  render() {
+    return html`
+      <div class="border border-border rounded-xl p-4 grid gap-2">
+        <slot></slot>
+        <p class="font-semibold">${this.label}: ${this.count.get()}</p>
+        <button @click=${() => this.count.set(this.count.get() + 1)}
+          class="px-3 py-1.5 rounded-lg bg-accent text-accent-fg w-fit">Increment</button>
+      </div>
+    `;
+  }
+}
+CounterCard.register('counter-card');

From 35a37abd4c2af722c80875e25d6a9971a1da755b Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 15:15:20 +0530
Subject: [PATCH 05/53] feat(cli): gallery /routing example (static + dynamic
 [id] param) (#824)

---
 .../gallery/app/examples/routing/[id]/page.ts  | 12 ++++++++++++
 .../gallery/app/examples/routing/page.ts       | 18 ++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/examples/routing/[id]/page.ts
 create mode 100644 packages/cli/templates/gallery/app/examples/routing/page.ts

diff --git a/packages/cli/templates/gallery/app/examples/routing/[id]/page.ts b/packages/cli/templates/gallery/app/examples/routing/[id]/page.ts
new file mode 100644
index 000000000..947db9cbe
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/routing/[id]/page.ts
@@ -0,0 +1,12 @@
+// A dynamic route: `params.id` is the URL segment. The default export is a
+// (possibly async) function receiving { params, searchParams, url }; it runs
+// ONLY on the server. Throw notFound() / redirect() to short-circuit.
+import { html } from '@webjsdev/core';
+
+export default function RoutingParam({ params }: { params: { id: string } }) {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Route param</h1>
+    <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
+    <p class="mt-3"><a class="text-accent" href="/examples/routing">Back</a></p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/examples/routing/page.ts b/packages/cli/templates/gallery/app/examples/routing/page.ts
new file mode 100644
index 000000000..b816718fc
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/routing/page.ts
@@ -0,0 +1,18 @@
+// Routing basics: a static page that links to a dynamic route. app/ is routing
+// only; a folder maps to a URL segment, and [id] is a dynamic segment read from
+// `params`. See app/examples/routing/[id]/page.ts.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Routing (dynamic params) | examples' };
+
+export default function RoutingExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Routing</h1>
+    <p class="text-fg-muted mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
+    <ul class="list-disc pl-5">
+      <li><a class="text-accent" href="/examples/routing/42">/examples/routing/42</a></li>
+      <li><a class="text-accent" href="/examples/routing/hello">/examples/routing/hello</a></li>
+    </ul>
+  `;
+}

From be675dd47c4b16cc623ce268ca321ecc5ac4cca6 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 15:17:00 +0530
Subject: [PATCH 06/53] feat(cli): gallery /server-actions example (.server vs
 use server) (#824)

---
 .../app/examples/server-actions/page.ts       | 13 ++++++++++
 .../server-actions/actions/greet.server.ts    | 12 ++++++++++
 .../server-actions/components/greeter.ts      | 24 +++++++++++++++++++
 .../server-actions/utils/format.server.ts     |  7 ++++++
 4 files changed, 56 insertions(+)
 create mode 100644 packages/cli/templates/gallery/app/examples/server-actions/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/server-actions/actions/greet.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
 create mode 100644 packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts

diff --git a/packages/cli/templates/gallery/app/examples/server-actions/page.ts b/packages/cli/templates/gallery/app/examples/server-actions/page.ts
new file mode 100644
index 000000000..9ed4506ed
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/server-actions/page.ts
@@ -0,0 +1,13 @@
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/server-actions/components/greeter.ts';
+
+export const metadata: Metadata = { title: 'Server actions (.server vs use server) | examples' };
+
+export default function ServerActionsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Server actions</h1>
+    <p class="text-fg-muted mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
+    <server-greeter></server-greeter>
+  `;
+}
diff --git a/packages/cli/templates/gallery/modules/server-actions/actions/greet.server.ts b/packages/cli/templates/gallery/modules/server-actions/actions/greet.server.ts
new file mode 100644
index 000000000..8665d4d3a
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/server-actions/actions/greet.server.ts
@@ -0,0 +1,12 @@
+'use server';
+// A 'use server' action IS the API: a client import is rewritten to a typed RPC
+// stub POSTing to the server. It may use server-only utilities (they run here,
+// server-side), which is why the util above stays off the client.
+import { shout } from '../utils/format.server.ts';
+import type { ActionResult } from '@webjsdev/server';
+
+export async function greet(input: { name: string }): Promise<ActionResult<{ message: string }>> {
+  const name = String(input?.name ?? '').trim();
+  if (!name) return { success: false, error: 'Name required.', status: 400 };
+  return { success: true, data: { message: shout('hello ' + name) } };
+}
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
new file mode 100644
index 000000000..4df8bf02e
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -0,0 +1,24 @@
+// Calls the 'use server' action via a normal import (the RPC stub). Never
+// hand-write fetch(); importing the action IS the API.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { greet } from '../actions/greet.server.ts';
+
+export class Greeter extends WebComponent {
+  private msg = signal('');
+  async run(e: SubmitEvent) {
+    e.preventDefault();
+    const name = String(new FormData(e.target as HTMLFormElement).get('name') ?? '');
+    const r = await greet({ name });
+    this.msg.set(r.success && r.data ? r.data.message : (r.error ?? 'error'));
+  }
+  render() {
+    return html`
+      <form @submit=${(e: SubmitEvent) => this.run(e)} class="flex gap-2">
+        <input name="name" placeholder="your name" class="border border-border rounded px-3 py-2" />
+        <button type="submit" class="px-3 py-2 rounded bg-accent text-accent-fg">Greet</button>
+      </form>
+      <p class="mt-3 font-semibold">${this.msg.get()}</p>
+    `;
+  }
+}
+Greeter.register('server-greeter');
diff --git a/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts b/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts
new file mode 100644
index 000000000..983119733
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts
@@ -0,0 +1,7 @@
+// A server-only utility: a `.server.ts` file with NO 'use server' directive.
+// Its browser import is a throw-at-load stub, so NEVER import this into a page
+// or component. Reach it only from a 'use server' action / route.ts / middleware.
+// (See agent-docs/types-and-mutations.md and the .server vs 'use server' rule.)
+export function shout(s: string): string {
+  return s.trim().toUpperCase() + '!';
+}

From b40c73de2f0198f19cce64e6210bcdd5a4c84a92 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:13:24 +0530
Subject: [PATCH 07/53] feat(cli): wire the always-on example gallery into the
 full-stack scaffold

Generate the example gallery in the default full-stack scaffold: copy
templates/gallery/{app/examples,modules} into the app, add a `todos`
table to the schema, and turn the home page into a gallery index that
links each example route. The gallery is the scaffold's teaching payload
(idiomatic app-thin routes + modules/<feature> logic), so an agent gains
webjs context by browsing real working code.

Each example page carries a webjs-scaffold-placeholder marker so an agent
consciously keeps-and-adapts or prunes it (route + module) rather than
silently shipping leftover example code; webjs check fails until each is
resolved.

api has no UI and saas overwrites the schema (users-only) with its own
focused auth example, so the gallery ships in full-stack only. The
full-stack run command now generates+migrates so /examples/todo works on
first boot, matching the saas precedent.

Also place the shadcn theme at styles/globals.css, not app/globals.css:
app/ is routing-only, so a non-routing stylesheet does not belong there.

Closes #824
Closes #821
Closes #817
---
 packages/cli/lib/create.js                    | 172 +++++++++++-------
 .../gallery/app/examples/components/page.ts   |   1 +
 .../gallery/app/examples/routing/page.ts      |   1 +
 .../app/examples/server-actions/page.ts       |   1 +
 .../gallery/app/examples/tic-tac-toe/page.ts  |   1 +
 .../gallery/app/examples/todo/page.ts         |   1 +
 6 files changed, 114 insertions(+), 63 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index af192bedf..5b2e09290 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -131,6 +131,27 @@ async function copyUiComponents(appDir, names) {
   }
 }
 
+/**
+ * Copy the example gallery (idiomatic, densely-commented working examples) into
+ * the scaffolded app. Merges `templates/gallery/{app,modules}` over the app so
+ * the example routes land under `app/examples/<feature>/` and their logic under
+ * `modules/<feature>/`, the app-thin + modules-logic split webjs prescribes.
+ *
+ * Ships verbatim (no `{{APP_NAME}}` substitution): the examples are self-
+ * contained and reference only `@webjsdev/*`, drizzle, `#db/*`, and each other.
+ * The scaffold's own `app/page.ts` / `app/layout.ts` are written AFTER this and
+ * the gallery ships neither, so there is no clobber. `cp` merges into existing
+ * `app/` and `modules/` dirs rather than replacing them.
+ *
+ * @param {string} appDir
+ */
+async function copyGallery(appDir) {
+  const galleryDir = join(TEMPLATES, 'gallery');
+  for (const sub of ['app', 'modules']) {
+    await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
+  }
+}
+
 /**
  * Write `lib/utils/cn.ts` (the `cn()` helper) and `components.json` so the
  * scaffolded app is pre-initialised for `webjs ui add`. Reads the registry's
@@ -154,11 +175,13 @@ async function writeUiBootstrap(appDir) {
   // 2) components.json: the same shape `webjsui init` writes for webjs
   // projects (see packages/ui/src/utils/detect-project.js). The utils alias
   // is lib/utils/cn so get-config.js's `+ '.ts'` resolves to lib/utils/cn.ts.
+  // The theme CSS lives at styles/globals.css, NOT app/globals.css: app/ is
+  // routing-only, so a non-routing stylesheet does not belong there.
   const componentsJson = {
     $schema: 'https://ui.webjs.dev/schema.json',
     style: 'default',
     tailwind: {
-      css: 'app/globals.css',
+      css: 'styles/globals.css',
       baseColor: 'neutral',
       cssVariables: true,
     },
@@ -175,13 +198,16 @@ async function writeUiBootstrap(appDir) {
     JSON.stringify(componentsJson, null, 2) + '\n',
   );
 
-  // 3) app/globals.css: copy the neutral theme verbatim. components.json
-  // references this path, and future `webjs ui add` calls append to it.
+  // 3) styles/globals.css: copy the neutral theme verbatim. components.json
+  // references this path, and future `webjs ui add` calls append to it. It
+  // lives OUTSIDE app/ because app/ is routing-only; the layout inlines the
+  // same tokens into a <style type="text/tailwindcss"> block so the browser
+  // Tailwind runtime resolves them with no build step.
   const css = await readFile(
     join(UI_REGISTRY_ROOT, 'themes', 'index.css'), 'utf8',
   );
-  await mkdir(join(appDir, 'app'), { recursive: true });
-  await writeFile(join(appDir, 'app', 'globals.css'), css);
+  await mkdir(join(appDir, 'styles'), { recursive: true });
+  await writeFile(join(appDir, 'styles', 'globals.css'), css);
 }
 
 /**
@@ -251,6 +277,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   }
   const isApi = template === 'api';
   const isSaas = template === 'saas';
+  // The example gallery ships in the DEFAULT full-stack scaffold only: api has no
+  // UI, and saas overwrites db/schema.server.ts (users-only, so the gallery's
+  // todos table would vanish) and already carries its own idiomatic auth example.
+  const isFullStack = !isApi && !isSaas;
 
   // Database dialect (#563): sqlite (default) or postgres. Drizzle is the ORM;
   // the schema/queries/actions are identical across dialects, only db/columns
@@ -622,7 +652,7 @@ export const index = (...cols: PgColumn[]) =>
 
   // Example schema (dialect-agnostic). Replace the User model with your own.
   await writeFile(join(appDir, 'db', 'schema.server.ts'), `import { defineRelations } from 'drizzle-orm';
-import { table, pk, text, createdAt } from './columns.server.ts';
+import { table, pk, ${isFullStack ? 'uuidPk, ' : ''}text, ${isFullStack ? 'bool, ' : ''}createdAt } from './columns.server.ts';
 
 // Example model. Feel free to delete or extend.
 export const users = table('users', {
@@ -631,10 +661,19 @@ export const users = table('users', {
   name: text(),
   createdAt: createdAt(),
 });
-
+${isFullStack ? `
+// Backs the example-gallery /examples/todo route (modules/todo). Delete it with
+// the gallery when you prune the examples you do not use.
+export const todos = table('todos', {
+  id: uuidPk(),
+  title: text().notNull(),
+  completed: bool().notNull().default(false),
+  createdAt: createdAt(),
+});
+` : ''}
 // Relations live here (one defineRelations for the whole schema). Empty
 // for now; add per-model relations as your schema grows.
-export const relations = defineRelations({ users }, () => ({}));
+export const relations = defineRelations({ users${isFullStack ? ', todos' : ''} }, () => ({}));
 
 // Derived types, never hand-written.
 export type User = typeof users.$inferSelect;
@@ -905,7 +944,7 @@ export type ActionResult<T> =
 
     // Pre-initialise @webjsdev/ui so the scaffold boots ready for
     // `webjs ui add <name>`: writes components.json + lib/utils/cn.ts +
-    // app/globals.css (the shadcn theme).
+    // styles/globals.css (the shadcn theme).
     await writeUiBootstrap(appDir);
 
     // Copy the standard ui-* component kit the scaffold's example pages
@@ -915,11 +954,19 @@ export type ActionResult<T> =
       'button', 'card', 'alert', 'badge', 'separator', 'label', 'input',
     ]);
 
+    // The example gallery: idiomatic, densely-commented working examples of
+    // webjs features (app-thin routes under app/examples/ + modules/<feature>/
+    // logic), linked from the home page. Shipped in the default full-stack
+    // scaffold so an agent gains context by browsing real code; prune
+    // per-feature (delete the route + its module) for what the app does not
+    // use. See CONVENTIONS.md "prune what the app does not use".
+    if (isFullStack) await copyGallery(appDir);
+
     // The shadcn theme tokens (`--color-primary`, `--color-card`, …) the
     // ui-* components consume. We read the registry's themes/index.css at
     // create time and inline it into the layout's
     // `<style type="text/tailwindcss">` block so the Tailwind browser
-    // runtime picks it up. Same content also lives at app/globals.css for
+    // runtime picks it up. Same content also lives at styles/globals.css for
     // `webjsui` tooling.
     const SHADCN_THEME = (await readThemeCss())
       // Escape backticks + ${} so the CSS survives interpolation into the
@@ -1011,7 +1058,7 @@ export default function RootLayout({ children }: { children: unknown }) {
     <!--
       Webjs UI theme. Design tokens (--color-primary,
       --color-card, --radius, etc.) the ui-* components consume.
-      The same content is also at app/globals.css; we inline it here so
+      The same content is also at styles/globals.css. We inline it here so
       the Tailwind browser runtime resolves the tokens without a build step.
       Edit base palette via the :root / .dark blocks below.
     -->
@@ -1141,65 +1188,59 @@ import {
   cardHeaderClass,
   cardTitleClass,
   cardDescriptionClass,
-  cardContentClass,
 } from '#components/ui/card.ts';
-import { alertClass, alertTitleClass, alertDescriptionClass } from '#components/ui/alert.ts';
-import { separatorClass } from '#components/ui/separator.ts';
 
 export const metadata = {
   title: '${name}: built with webjs',
 };
 
+// The example routes this scaffold ships, each a small idiomatic webjs app.
+// Prune the ones you do not need (delete the app/examples/<name> route AND its
+// modules/<name> folder), then reshape this page into your app's real home.
+const examples = [
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'Optimistic UI with instant updates and auto-rollback, progressive-enhancement forms, accessible labels, and the app-thin plus modules split, backed by SQLite.' },
+  { href: '/examples/tic-tac-toe', title: 'Tic-tac-toe', blurb: 'Client-only state with signals. No server and no database, so all interactivity lives in the component.' },
+  { href: '/examples/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+  { href: '/examples/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+  { href: '/examples/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+];
+
 export default function Home() {
   return html\`
-    <section class="mb-18">
+    <section class="mb-14">
       \${rubric('welcome')}
       \${displayH1(html\`Hello from <span class="text-accent italic">${name}</span>.\`)}
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
-        Edit <code class="font-mono text-[0.9em]">app/page.ts</code> to get started.
-        Run \${accentLink('#', 'webjs test')} to run tests and
-        \${accentLink('#', 'webjs check')} to catch correctness issues.
+        This scaffold ships an example gallery below: small, idiomatic, heavily
+        commented webjs apps. Browse them for context, then replace this page
+        with your own. See \${accentLink('https://docs.webjs.com', 'the docs')}
+        for the full reference.
       </p>
       <div class="flex gap-3 items-center">
-        <button class=\${buttonClass()}>Get started</button>
-        <button class=\${buttonClass({ variant: 'outline' })}>View docs</button>
+        <a href="/examples/todo" class=\${buttonClass()}>Open the todo example</a>
         <span class=\${badgeClass({ variant: 'secondary' })}>v0.1</span>
       </div>
     </section>
 
-    <div class=\${cardClass()} style="margin-bottom: 3rem">
-      <div class=\${cardHeaderClass()}>
-        <h3 class=\${cardTitleClass()}>Web Components + Server Actions</h3>
-        <p class=\${cardDescriptionClass()}>
-          Drop a custom element anywhere. Call a server action like a local
-          function. webjs rewrites the import into a typed RPC stub.
-        </p>
-      </div>
-      <div class=\${cardContentClass()}>
-        <div class=\${alertClass()}>
-          <h5 class=\${alertTitleClass()}>AI-first component kit included</h5>
-          <div class=\${alertDescriptionClass()}>
-            button, card, alert, badge, separator, label, input are already
-            in <code class="font-mono text-[0.9em]">components/ui/</code> as
-            class-helper functions you call from a native element. Add more
-            with <code class="font-mono text-[0.9em]">webjs ui add &lt;name&gt;</code>.
-          </div>
-        </div>
-      </div>
-    </div>
-
-    <div class=\${separatorClass()} style="margin: 2.5rem 0"></div>
-
-    <section class="mt-10">
-      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-2">Light DOM + Tailwind</h2>
-      <p class="text-fg-muted text-sm m-0 mb-4">
-        Components render into light DOM by default. Tailwind utility classes
-        apply directly. Set <code class="font-mono text-[0.9em]">static shadow = true</code>
-        on a component when you need scoped styles or third-party-embed
-        isolation. &lt;slot&gt; projection works identically in both modes,
-        including named slots, fallback content, and the full
-        assignedNodes / slotchange API.
+    <section>
+      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Example gallery</h2>
+      <p class="text-fg-muted text-sm m-0 mb-5">
+        Each route lives under <code class="font-mono text-[0.9em]">app/examples/</code>
+        with its logic in <code class="font-mono text-[0.9em]">modules/</code>.
+        Delete the ones you do not need.
       </p>
+      <div class="grid gap-4 sm:grid-cols-2">
+        \${examples.map((ex) => html\`
+          <a href=\${ex.href} class="block no-underline">
+            <div class="\${cardClass()} h-full transition-colors hover:border-border-strong">
+              <div class=\${cardHeaderClass()}>
+                <h3 class=\${cardTitleClass()}>\${ex.title}</h3>
+                <p class=\${cardDescriptionClass()}>\${ex.blurb}</p>
+              </div>
+            </div>
+          </a>
+        \`)}
+      </div>
     </section>
   \`;
 }
@@ -1308,7 +1349,7 @@ ThemeToggle.register('theme-toggle');
     app/layout.ts, page.ts, login/, signup/
     app/dashboard/{page,settings,middleware}.ts  ← protected
     app/api/auth/[...path]/route.ts      ← auth API
-    app/globals.css                      ← @webjsdev/ui theme tokens
+    styles/globals.css                   ← @webjsdev/ui theme tokens
     components.json                      ← preconfigured for \`webjs ui add\`
     components/ui/{button,card,alert,badge,separator,label,input,
                     dialog,form,field,switch,checkbox}.ts
@@ -1321,15 +1362,19 @@ ThemeToggle.register('theme-toggle');
 `);
   } else {
     console.log(`  ${name}/
-    app/layout.ts, page.ts       ← light DOM + Tailwind + @theme tokens
-    app/globals.css              ← @webjsdev/ui theme tokens
+    app/layout.ts, page.ts       ← home links to the example gallery
+    app/examples/{todo,tic-tac-toe,components,routing,server-actions}/
+                                 ← thin routes for the gallery
+    styles/globals.css           ← @webjsdev/ui theme tokens
     components.json              ← preconfigured for \`webjs ui add\`
     components/ui/{button,card,alert,badge,separator,label,input}.ts
     components/theme-toggle.ts   ← light DOM web component
     lib/utils/cn.ts              ← cn() helper for ui-* components
     lib/utils/ui.ts              ← Tailwind class-bundle helpers
     public/tailwind-browser.js   ← Tailwind runtime
-    modules/
+    modules/{todo,tic-tac-toe,components,routing,server-actions}/
+                                 ← gallery logic (prune what you skip)
+    db/{schema,columns,connection}.server.ts  ← Drizzle (User + Todo)
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
   }
@@ -1391,13 +1436,14 @@ For AI agents, read this before editing scaffolded files:
   // templates ship with @webjsdev/ui already initialised; the api
   // template has no UI but may add one later.
   const installSegment = installed ? '' : `${pm} install && `;
-  // The saas example queries the users table on its first request (auth), so it
-  // needs a migration authored first: `db:generate` writes it and the
-  // `webjs.dev.before` migrate applies it on `run dev` (Drizzle splits Prisma's
-  // `migrate dev` into generate-then-migrate). The full-stack / api examples do
-  // not query the db on first paint, so they boot with just `run dev`; once you
-  // add a db route, `db:generate` then `run dev` is the loop (dev auto-migrates).
-  const dbSegment = isSaas ? `${pm} run db:generate && ` : '';
+  // Some examples query the db on their first request, so a migration must be
+  // authored first: `db:generate` writes it and the `webjs.dev.before` migrate
+  // applies it on `run dev` (Drizzle splits Prisma's `migrate dev` into
+  // generate-then-migrate). The saas example queries users (auth); the
+  // full-stack scaffold ships the gallery's /examples/todo route (queries todos).
+  // The api template has no such first-request query, so it boots with just
+  // `run dev`; once you add a db route, `db:generate` then `run dev` is the loop.
+  const dbSegment = isApi ? '' : `${pm} run db:generate && `;
   const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
   // Postgres needs a reachable DATABASE_URL before any migrate (sqlite uses a
   // local file with no .env). Point it at a running database; `dev` / `start`
diff --git a/packages/cli/templates/gallery/app/examples/components/page.ts b/packages/cli/templates/gallery/app/examples/components/page.ts
index e47a24152..846ea85d4 100644
--- a/packages/cli/templates/gallery/app/examples/components/page.ts
+++ b/packages/cli/templates/gallery/app/examples/components/page.ts
@@ -1,3 +1,4 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/components route AND modules/components), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/components/components/counter-card.ts';
diff --git a/packages/cli/templates/gallery/app/examples/routing/page.ts b/packages/cli/templates/gallery/app/examples/routing/page.ts
index b816718fc..fa23704f3 100644
--- a/packages/cli/templates/gallery/app/examples/routing/page.ts
+++ b/packages/cli/templates/gallery/app/examples/routing/page.ts
@@ -1,3 +1,4 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/routing route), then delete this marker line. webjs check fails while the marker remains.
 // Routing basics: a static page that links to a dynamic route. app/ is routing
 // only; a folder maps to a URL segment, and [id] is a dynamic segment read from
 // `params`. See app/examples/routing/[id]/page.ts.
diff --git a/packages/cli/templates/gallery/app/examples/server-actions/page.ts b/packages/cli/templates/gallery/app/examples/server-actions/page.ts
index 9ed4506ed..ac226766f 100644
--- a/packages/cli/templates/gallery/app/examples/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/examples/server-actions/page.ts
@@ -1,3 +1,4 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/server-actions route AND modules/server-actions), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/server-actions/components/greeter.ts';
diff --git a/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts b/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
index 3b945f763..3b1e5af8d 100644
--- a/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
+++ b/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
@@ -1,3 +1,4 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/tic-tac-toe route AND modules/tic-tac-toe), then delete this marker line. webjs check fails while the marker remains.
 // A thin route rendering a client-only component. The page runs server-side to
 // produce the SSR'd first paint (the empty board), then <tic-tac-toe> hydrates
 // and all interactivity runs client-side. Pages do not hydrate; components do.
diff --git a/packages/cli/templates/gallery/app/examples/todo/page.ts b/packages/cli/templates/gallery/app/examples/todo/page.ts
index 711a91b99..6ace4b266 100644
--- a/packages/cli/templates/gallery/app/examples/todo/page.ts
+++ b/packages/cli/templates/gallery/app/examples/todo/page.ts
@@ -1,3 +1,4 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/todo route, modules/todo, AND the todos table in db/schema.server.ts), then delete this marker line. webjs check fails while the marker remains.
 // A THIN route adapter: app/ is routing only. It fetches the initial data
 // (server-side) via the 'use server' query and renders the interactive
 // component, plus a page `action` for the no-JS write path. All the real logic

From 0a14a77afeb6862d2641f639543af8ed720f8ef8 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:13:30 +0530
Subject: [PATCH 08/53] refactor(ui): default webjs projects to
 styles/globals.css

`webjs ui init` in a webjs project put the theme at app/globals.css, but
app/ is routing-only in webjs, so a non-routing stylesheet does not
belong there. Default to styles/globals.css instead (matching the plain
project default) so `webjs ui init` and the scaffold agree.
---
 packages/ui/src/utils/detect-project.js |  4 +++-
 packages/ui/test/detect-project.test.js |  4 ++--
 packages/ui/test/init-command.test.js   | 20 +++++++-------------
 3 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/packages/ui/src/utils/detect-project.js b/packages/ui/src/utils/detect-project.js
index 4fa0385a3..f1624a733 100644
--- a/packages/ui/src/utils/detect-project.js
+++ b/packages/ui/src/utils/detect-project.js
@@ -34,7 +34,9 @@ export function defaultsForProject(cwd = process.cwd()) {
   switch (type) {
     case 'webjs':
       return {
-        tailwindCss: 'app/globals.css',
+        // styles/globals.css, NOT app/globals.css: in webjs, app/ is routing-only,
+        // so a non-routing stylesheet lives outside it.
+        tailwindCss: 'styles/globals.css',
         aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
       };
     case 'next':
diff --git a/packages/ui/test/detect-project.test.js b/packages/ui/test/detect-project.test.js
index 9a784db6d..b19dc74b0 100644
--- a/packages/ui/test/detect-project.test.js
+++ b/packages/ui/test/detect-project.test.js
@@ -41,12 +41,12 @@ test('detectProject: plain when no package.json', () => {
   } finally { rmSync(d, { recursive: true }); }
 });
 
-test('defaultsForProject: webjs uses app/globals.css', () => {
+test('defaultsForProject: webjs uses styles/globals.css (app/ is routing-only)', () => {
   const d = tmp();
   try {
     writeFileSync(join(d, 'package.json'), JSON.stringify({ dependencies: { '@webjsdev/server': '*' } }));
     const def = defaultsForProject(d);
-    assert.equal(def.tailwindCss, 'app/globals.css');
+    assert.equal(def.tailwindCss, 'styles/globals.css');
     assert.equal(def.aliases.ui, 'components/ui');
   } finally { rmSync(d, { recursive: true }); }
 });
diff --git a/packages/ui/test/init-command.test.js b/packages/ui/test/init-command.test.js
index e6076ab31..b181e6bfb 100644
--- a/packages/ui/test/init-command.test.js
+++ b/packages/ui/test/init-command.test.js
@@ -41,7 +41,7 @@ test('init: writes components.json with project-detected defaults', async () =>
     const cfg = JSON.parse(readFileSync(join(d, 'components.json'), 'utf8'));
     assert.equal(cfg.style, 'default');
     assert.equal(cfg.tailwind.baseColor, 'neutral');
-    assert.equal(cfg.tailwind.css, 'app/globals.css'); // webjs default
+    assert.equal(cfg.tailwind.css, 'styles/globals.css'); // webjs default (app/ is routing-only)
     assert.equal(cfg.aliases.ui, 'components/ui');
   } finally {
     globalThis.fetch = origFetch;
@@ -66,18 +66,12 @@ test('init: writes lib/utils.ts from registry', async () => {
 test('init: appends theme CSS to globals.css', async () => {
   stubFetch();
   const d = tmp();
-  try {
-    // Pre-seed globals with existing content
-    writeFileSync(join(d, 'app', 'globals.css'), '/* existing */\n', { flag: 'w' });
-  } catch {
-    // First create the directory
-  }
   try {
     const { mkdirSync } = await import('node:fs');
-    mkdirSync(join(d, 'app'), { recursive: true });
-    writeFileSync(join(d, 'app', 'globals.css'), '/* existing */\n');
+    mkdirSync(join(d, 'styles'), { recursive: true });
+    writeFileSync(join(d, 'styles', 'globals.css'), '/* existing */\n');
     await init.parseAsync(['--yes', '--cwd', d, '--registry', 'http://test/r'], { from: 'user' });
-    const css = readFileSync(join(d, 'app', 'globals.css'), 'utf8');
+    const css = readFileSync(join(d, 'styles', 'globals.css'), 'utf8');
     assert.match(css, /\/\* existing \*\//);
     assert.match(css, /@webjsdev\/ui theme/);
     assert.match(css, /--primary: #000/);
@@ -92,11 +86,11 @@ test('init: theme is idempotent (doesn\'t append twice)', async () => {
   const d = tmp();
   try {
     const { mkdirSync } = await import('node:fs');
-    mkdirSync(join(d, 'app'), { recursive: true });
-    writeFileSync(join(d, 'app', 'globals.css'), '');
+    mkdirSync(join(d, 'styles'), { recursive: true });
+    writeFileSync(join(d, 'styles', 'globals.css'), '');
     await init.parseAsync(['--yes', '--cwd', d, '--registry', 'http://test/r'], { from: 'user' });
     await init.parseAsync(['--yes', '--cwd', d, '--registry', 'http://test/r'], { from: 'user' });
-    const css = readFileSync(join(d, 'app', 'globals.css'), 'utf8');
+    const css = readFileSync(join(d, 'styles', 'globals.css'), 'utf8');
     const occurrences = (css.match(/@webjsdev\/ui theme/g) || []).length;
     assert.equal(occurrences, 1, 'theme block should only appear once');
   } finally {

From 705e242aedac06bf44f95c3da7faafd9871c2ac3 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:17:32 +0530
Subject: [PATCH 09/53] fix(cli): use object-form orderBy in the gallery todo
 query

`db.query.todos.findMany({ orderBy: [desc(todos.createdAt)] })` compiles
to a bad SQL alias in drizzle rc.3 (`no such column: d0.0`), 500ing
/examples/todo on first load. The relational query API wants the object
form `{ createdAt: 'desc' }`. Verified end-to-end: the todo route now
renders and create/toggle/delete persist via the no-JS form path.
---
 .../gallery/modules/todo/queries/list-todos.server.ts | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
index b3dd3c64a..8d69b507b 100644
--- a/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
+++ b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
@@ -3,16 +3,17 @@
 // normal import (rewritten to a typed RPC stub). `method = 'GET'` rides args in
 // the URL, is CSRF-exempt, and its result is SSR-seeded so the component does
 // not re-fetch on hydration.
-import { desc } from 'drizzle-orm';
 import { db } from '#db/connection.server.ts';
-import { todos } from '#db/schema.server.ts';
 import type { Todo } from '../types.ts';
 
 export const method = 'GET';
 
 export async function listTodos(): Promise<Todo[]> {
-  // rc.3 read: the relational query API. Do NOT use `db.select({ col })` (its
-  // projection overload trips TS2554 in rc.3). See agent-docs/orm.md.
-  const rows = await db.query.todos.findMany({ orderBy: [desc(todos.createdAt)] });
+  // rc.3 read: the relational query API. `orderBy` uses the object form
+  // (`{ column: 'asc' | 'desc' }`); passing `[desc(todos.createdAt)]` with an
+  // imported column mis-compiles to a bad SQL alias in rc.3. Do NOT use
+  // `db.select({ col })` either (its projection overload trips TS2554 in rc.3).
+  // See agent-docs/orm.md.
+  const rows = await db.query.todos.findMany({ orderBy: { createdAt: 'desc' } });
   return rows as Todo[];
 }

From 011ecba7870d23d3059f15353e8519fe70790b5d Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:21:00 +0530
Subject: [PATCH 10/53] docs(cli): teach scaffold agents the gallery, pruning,
 and app-routing-only

Sync all five per-agent rule files plus the create banner: the full-stack
scaffold now ships an example gallery (reference to browse and prune, not
the final product), app/ is routing-only (globals.css lives at styles/,
helpers at lib/utils/), and now-empty directories are pruned after
removing generated content. The banner no longer hardcodes "two"
placeholder violations (the gallery routes carry markers too).
---
 packages/cli/lib/create.js                    | 18 +++++----
 .../cli/templates/.agents/rules/workflow.md   | 11 ++++++
 packages/cli/templates/.cursorrules           | 11 ++++++
 .../templates/.github/copilot-instructions.md | 11 ++++++
 packages/cli/templates/AGENTS.md              | 26 ++++++++++++-
 packages/cli/templates/CONVENTIONS.md         | 38 ++++++++++++++++---
 6 files changed, 99 insertions(+), 16 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 5b2e09290..a511b83c7 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1391,14 +1391,16 @@ ThemeToggle.register('theme-toggle');
   ✓ Convention validation via \`webjs check\`
 
 For AI agents, read this before editing scaffolded files:
-  • The example layout / page / components / schema are REFERENCE ONLY.
-    Replace them with the app the user actually asked for. Don't ship
-    the scaffold's example User model or "Hello from …" page as the
-    final product.
-  • This fresh app intentionally FAILS \`webjs check\` with two
-    no-scaffold-placeholder violations (app/page.ts, app/layout.ts).
-    That is the signal to replace the example content. Delete each
-    marker comment line as you do, and the check goes green.
+  • The example layout, home page, the app/examples gallery (+ its
+    modules) and schema are REFERENCE ONLY. Replace them with the app
+    the user asked for, and prune the example routes you do not use
+    (delete the app/examples/<name> route AND its modules/<name>). Don't
+    ship the scaffold's examples as the final product.
+  • This fresh app intentionally FAILS \`webjs check\` with
+    no-scaffold-placeholder violations on the example content (the home
+    page, the layout, and each app/examples route). That is the signal
+    to replace or prune each. Delete the marker comment line as you do,
+    and the check goes green.
   • Use Drizzle + SQLite for app data. It's already wired up. Define
     real models in db/schema.server.ts, then run \`webjs db generate\`
     and \`webjs db migrate\`. NEVER store app data in JSON files,
diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index 28afb1f6b..d077e738a 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -19,6 +19,17 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   the example `User` model, the example users module, etc. with the app the
   user actually asked for. Do not ship "Hello from <app-name>" as the
   deliverable.
+- **The example gallery is reference too, prune it.** The full-stack scaffold
+  ships a gallery under `app/examples/` (logic in `modules/`). Read it to learn
+  the patterns, keep and adapt what you need, and delete the rest (the
+  `app/examples/<name>` route AND its `modules/<name>`; for the todo example,
+  also the `todos` table). Each example page has a `webjs-scaffold-placeholder`
+  marker so `webjs check` fails until you resolve it. Delete now-empty
+  directories after pruning.
+- **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
+  route, middleware, metadata routes). CSS, helpers, and constants do NOT:
+  `globals.css` is at `styles/`, browser-safe helpers at `lib/utils/`, feature
+  logic in `modules/`.
 - **Use a unique design (UI apps).** When the app has a UI, give it a design of
   your own (palette, layout, typography, chrome) that fits what the user asked
   for. Do NOT mimic the scaffold's example look (its warm colors, the 760px
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 07c536b99..431ea2446 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -18,6 +18,17 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **The example gallery is reference too, prune it.** The full-stack
+  scaffold ships a gallery under `app/examples/` (logic in `modules/`).
+  Read it to learn the patterns, keep and adapt what you need, and delete
+  the rest (the `app/examples/<name>` route AND its `modules/<name>`; for
+  the todo example, also the `todos` table). Each example page has a
+  `webjs-scaffold-placeholder` marker so `webjs check` fails until you
+  resolve it. Delete now-empty directories after pruning.
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
 - **Use a unique design (UI apps).** When the app has a UI, give it a
   design of your own (palette, layout, typography, chrome) that fits what
   the user asked for. Do NOT mimic the scaffold's example look (its warm
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 2b4c1bf48..912fb5053 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -18,6 +18,17 @@ the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
+- **The example gallery is reference too, prune it.** The full-stack
+  scaffold ships a gallery under `app/examples/` (logic in `modules/`).
+  Read it to learn the patterns, keep and adapt what you need, and delete
+  the rest (the `app/examples/<name>` route AND its `modules/<name>`; for
+  the todo example, also the `todos` table). Each example page has a
+  `webjs-scaffold-placeholder` marker so `webjs check` fails until you
+  resolve it. Delete now-empty directories after pruning.
+- **`app/` is routing-only.** Only routing files live in `app/` (page,
+  layout, route, middleware, metadata routes). CSS, helpers, and constants
+  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
+  `lib/utils/`, feature logic in `modules/`.
 - **Use a unique design (UI apps).** When the app has a UI, give it a
   design of your own (palette, layout, typography, chrome) that fits what
   the user asked for. Do NOT mimic the scaffold's example look (its warm
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index ea633b393..40d962723 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -305,8 +305,13 @@ behavior the browser can't deliver natively.
 ## File conventions
 
 ```
-app/                     thin route adapters (import from modules/)
-  page.ts                → /
+app/                     ROUTING ONLY: thin route adapters (import from modules/).
+                         No CSS, helpers, or constants here; those live in
+                         styles/, lib/utils/, and modules/. globals.css is at
+                         styles/, NOT app/.
+  page.ts                → / (the scaffold home links to the example gallery)
+  examples/<name>/       the example gallery (todo, tic-tac-toe, components,
+                         routing, server-actions); prune what you do not use
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
@@ -330,6 +335,8 @@ modules/<feature>/
   types.ts               feature types
 lib/
   ...                    cross-cutting infra (session, auth config, etc.)
+styles/
+  globals.css            @webjsdev/ui theme tokens (NOT in app/; app/ is routing-only)
 db/
   schema.server.ts       Drizzle models + relations (your data layer)
   columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
@@ -347,6 +354,21 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
+### The example gallery (reference content, prune it)
+
+The scaffold ships a working example gallery under `app/examples/` with its
+logic in `modules/`. Each example is small, idiomatic, and heavily commented,
+so read them to learn the webjs patterns (optimistic UI, progressive
+enhancement, signals, slots, dynamic routes, the `.server.ts` vs `'use server'`
+boundary). They are REFERENCE, not your app: keep and adapt the ones you need,
+and prune the rest. Pruning one example means deleting its `app/examples/<name>`
+route AND its `modules/<name>` folder (and, for the todo example, the `todos`
+table in `db/schema.server.ts`), then removing its link from `app/page.ts`. Each
+example page carries a `webjs-scaffold-placeholder` marker so `webjs check`
+fails until you have consciously kept-and-adapted or pruned it. After pruning,
+delete any now-empty directories (an empty `lib/utils/` or `modules/<name>/` is
+leftover scaffolding, not structure).
+
 ### Typed page / layout / route-handler props
 
 Type page / layout / route-handler arguments with the exported helpers so a
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index b8aea701c..d4e0079c9 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -310,9 +310,31 @@ production workloads.
 <!-- OVERRIDE -->
 
 This project was created with `webjs create`. Every file you see right
-now (the `app/page.ts` "Hello from …" homepage, the example `User`
-model, the `theme-toggle` component, the example users module in api /
-saas templates) is a **starting point**.
+now (the `app/page.ts` homepage, the example `User` model, the
+`theme-toggle` component, the example gallery under `app/examples/` in
+the full-stack template, the example users module in api / saas
+templates) is a **starting point**.
+
+The full-stack scaffold ships an **example gallery**: small, idiomatic,
+heavily commented working apps under `app/examples/` (with their logic in
+`modules/`) that demonstrate optimistic UI, progressive enhancement,
+signals, slots, dynamic routes, and the `.server.ts` vs `'use server'`
+boundary. Read them to learn the patterns. They are REFERENCE, not the
+app: keep and adapt the ones you need, and **prune the rest**. Pruning an
+example means deleting its `app/examples/<name>` route AND its
+`modules/<name>` folder (for the todo example, also the `todos` table in
+`db/schema.server.ts` and its link in `app/page.ts`). Each example page
+carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails
+until you consciously keep-and-adapt or prune it. After pruning, delete
+any now-empty directories, an empty `lib/utils/` or `modules/<name>/` is
+leftover scaffolding, not structure.
+
+**`app/` is routing-only.** Only routing files belong in `app/` (page,
+layout, route, middleware, and metadata routes). CSS, helpers, and
+constants do NOT: the theme lives at `styles/globals.css` (NOT
+`app/globals.css`), browser-safe helpers at `lib/utils/`, and feature
+logic in `modules/`. If you add a stylesheet or a helper, put it outside
+`app/`.
 
 When the user asks the agent to build their actual app:
 
@@ -325,6 +347,9 @@ When the user asks the agent to build their actual app:
    need a theme picker.
 4. **Delete the example users module** (api/saas templates) if the app
    doesn't use it.
+4b. **Prune the example gallery** (full-stack template). Keep and adapt the
+   examples the app uses, delete the rest (route + module + any table),
+   and remove their links from `app/page.ts`.
 5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
    brand, replace the example `Home` nav with the app's navigation, and
    pick a content-width container that fits. The default
@@ -347,9 +372,10 @@ When the user asks the agent to build their actual app:
    conventions, the design tokens in `app/layout.ts`. These are the
    infrastructure, not the example app.
 
-This is enforced, not just advised. The example `app/page.ts` and
-`app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and
-the `no-scaffold-placeholder` check fails while any marker remains, so a
+This is enforced, not just advised. The example `app/page.ts`,
+`app/layout.ts`, and each `app/examples/<name>/page.ts` carry a
+`webjs-scaffold-placeholder` marker comment, and the
+`no-scaffold-placeholder` check fails while any marker remains, so a
 freshly scaffolded app fails `webjs check` until you address each
 placeholder. The marker is acknowledge-and-remove: replace the example
 content, or deliberately keep it, and in either case delete the marker

From 17a84f5c40210e0215df186f3035edfc5c6811e9 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:26:34 +0530
Subject: [PATCH 11/53] fix(cli): fix two type errors in the gallery components

Typecheck of a generated full-stack app surfaced two TS errors:
- greeter.ts read `r.error` without narrowing on `r.success`, which does
  not exist on the success branch of ActionResult. Narrow on `r.success`.
- todo-app.ts named a handler `remove`, clashing with the built-in
  `Element.remove(): void` (TS2416). Rename to `removeTodo`.

Verified: a fresh full-stack app now passes `webjs typecheck` (exit 0),
and the optimistic add + label-toggle work in the browser.
---
 .../gallery/modules/server-actions/components/greeter.ts    | 3 ++-
 .../templates/gallery/modules/todo/components/todo-app.ts   | 6 ++++--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index 4df8bf02e..ac53c3039 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -9,7 +9,8 @@ export class Greeter extends WebComponent {
     e.preventDefault();
     const name = String(new FormData(e.target as HTMLFormElement).get('name') ?? '');
     const r = await greet({ name });
-    this.msg.set(r.success && r.data ? r.data.message : (r.error ?? 'error'));
+    // Narrow on r.success so TS knows `data` (success) vs `error` (failure).
+    this.msg.set(r.success ? (r.data?.message ?? '') : (r.error ?? 'error'));
   }
   render() {
     return html`
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index a00c51e90..372f231ab 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -53,7 +53,9 @@ export class TodoApp extends WebComponent({
     if (r.success && r.data) { const d = r.data; this.todos = (this.todos ?? []).map((t) => (t.id === todo.id ? d : t)); }
   }
 
-  async remove(e: Event, todo: Todo) {
+  // NOT named `remove`: Element.remove() is a built-in DOM method, so a method
+  // named `remove` with a different signature would clash (TS2416).
+  async removeTodo(e: Event, todo: Todo) {
     e.preventDefault();
     if (todo.pending) return;
     const promise = deleteTodo({ id: todo.id });
@@ -88,7 +90,7 @@ export class TodoApp extends WebComponent({
                      the task (works on JS and no-JS paths, and screen readers). -->
                 <label for="t-${todo.id}" class="flex-1 cursor-pointer ${todo.completed ? 'line-through opacity-60' : ''}">${todo.title}</label>
                 <button type="submit" name="intent" value="delete" aria-label="Delete"
-                  @click=${(e: Event) => this.remove(e, todo)} class="text-fg-subtle">x</button>
+                  @click=${(e: Event) => this.removeTodo(e, todo)} class="text-fg-subtle">x</button>
               </form>
             </li>
           `)}

From 7d8fcd1d101795c19f152b6b97d8793778b56722 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:36:31 +0530
Subject: [PATCH 12/53] feat(cli): add async-render, directives, and
 route-handler gallery examples

Broaden the gallery beyond the core five with three more distinct
concepts, each verified (SSR boot + typecheck + browser):
- async-render: a component awaits server data in `async render()`, so
  the resolved value is in the first paint (static refresh = true ships it).
- directives: `repeat` keyed reordering + `watch(signal)` fine-grained swap.
- route-handler: a server-only `route.ts` JSON endpoint at a deeper segment.

Home links all eight; the two page-only examples (routing, route-handler)
have no module by design.
---
 packages/cli/lib/create.js                    |  10 +-
 packages/cli/templates/AGENTS.md              |   3 +-
 .../gallery/app/examples/async-render/page.ts |  14 ++
 .../gallery/app/examples/directives/page.ts   |  14 ++
 .../app/examples/route-handler/data/route.ts  |   8 +
 .../app/examples/route-handler/page.ts        |  13 ++
 .../async-render/components/server-clock.ts   |  26 +++
 .../queries/server-greeting.server.ts         |   9 ++
 .../directives/components/directive-demo.ts   |  49 ++++++
 test/scaffolds/scaffold-gallery.test.js       | 148 ++++++++++++++++++
 10 files changed, 290 insertions(+), 4 deletions(-)
 create mode 100644 packages/cli/templates/gallery/app/examples/async-render/page.ts
 create mode 100644 packages/cli/templates/gallery/app/examples/directives/page.ts
 create mode 100644 packages/cli/templates/gallery/app/examples/route-handler/data/route.ts
 create mode 100644 packages/cli/templates/gallery/app/examples/route-handler/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/async-render/components/server-clock.ts
 create mode 100644 packages/cli/templates/gallery/modules/async-render/queries/server-greeting.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
 create mode 100644 test/scaffolds/scaffold-gallery.test.js

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index a511b83c7..5ca6f235a 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1203,6 +1203,9 @@ const examples = [
   { href: '/examples/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
   { href: '/examples/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
   { href: '/examples/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+  { href: '/examples/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+  { href: '/examples/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+  { href: '/examples/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
 ];
 
 export default function Home() {
@@ -1363,7 +1366,8 @@ ThemeToggle.register('theme-toggle');
   } else {
     console.log(`  ${name}/
     app/layout.ts, page.ts       ← home links to the example gallery
-    app/examples/{todo,tic-tac-toe,components,routing,server-actions}/
+    app/examples/{todo,tic-tac-toe,components,routing,server-actions,
+                  async-render,directives,route-handler}/
                                  ← thin routes for the gallery
     styles/globals.css           ← @webjsdev/ui theme tokens
     components.json              ← preconfigured for \`webjs ui add\`
@@ -1372,8 +1376,8 @@ ThemeToggle.register('theme-toggle');
     lib/utils/cn.ts              ← cn() helper for ui-* components
     lib/utils/ui.ts              ← Tailwind class-bundle helpers
     public/tailwind-browser.js   ← Tailwind runtime
-    modules/{todo,tic-tac-toe,components,routing,server-actions}/
-                                 ← gallery logic (prune what you skip)
+    modules/{todo,tic-tac-toe,components,server-actions,async-render,
+             directives}/       ← gallery logic (prune what you skip)
     db/{schema,columns,connection}.server.ts  ← Drizzle (User + Todo)
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 40d962723..3d3415e43 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -311,7 +311,8 @@ app/                     ROUTING ONLY: thin route adapters (import from modules/
                          styles/, NOT app/.
   page.ts                → / (the scaffold home links to the example gallery)
   examples/<name>/       the example gallery (todo, tic-tac-toe, components,
-                         routing, server-actions); prune what you do not use
+                         routing, server-actions, async-render, directives,
+                         route-handler); prune what you do not use
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
diff --git a/packages/cli/templates/gallery/app/examples/async-render/page.ts b/packages/cli/templates/gallery/app/examples/async-render/page.ts
new file mode 100644
index 000000000..f9af3509f
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/async-render/page.ts
@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/async-render route AND modules/async-render), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/async-render/components/server-clock.ts';
+
+export const metadata: Metadata = { title: 'Async render (server data in first paint) | examples' };
+
+export default function AsyncRenderExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Async render</h1>
+    <p class="text-fg-muted mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    <server-clock></server-clock>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/examples/directives/page.ts b/packages/cli/templates/gallery/app/examples/directives/page.ts
new file mode 100644
index 000000000..aed77e68a
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/directives/page.ts
@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/directives route AND modules/directives), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/directives/components/directive-demo.ts';
+
+export const metadata: Metadata = { title: 'Directives (repeat + watch) | examples' };
+
+export default function DirectivesExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Directives</h1>
+    <p class="text-fg-muted mb-4">The lit-html directive set: <code>repeat</code> keys a reordering list so nodes are reused, and <code>watch(signal)</code> swaps one node without a full re-render.</p>
+    <directive-demo></directive-demo>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/examples/route-handler/data/route.ts b/packages/cli/templates/gallery/app/examples/route-handler/data/route.ts
new file mode 100644
index 000000000..c41daeffc
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/route-handler/data/route.ts
@@ -0,0 +1,8 @@
+// A route.ts is a server-only HTTP handler (named GET / POST / PUT / PATCH /
+// DELETE exports). It is NOT isomorphic and never ships to the client, the webjs
+// equivalent of a Next route handler. Each handler returns a Response (a plain
+// value auto-JSONs). A folder cannot have BOTH page.ts and route.ts, so this
+// endpoint lives one segment deeper, at /examples/route-handler/data.
+export async function GET() {
+  return Response.json({ ok: true, at: new Date().toISOString() });
+}
diff --git a/packages/cli/templates/gallery/app/examples/route-handler/page.ts b/packages/cli/templates/gallery/app/examples/route-handler/page.ts
new file mode 100644
index 000000000..c86aade26
--- /dev/null
+++ b/packages/cli/templates/gallery/app/examples/route-handler/page.ts
@@ -0,0 +1,13 @@
+// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/route-handler route, including its data/route.ts handler), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Route handlers (route.ts) | examples' };
+
+export default function RouteHandlerExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
+    <p class="text-fg-muted mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
+    <p><a class="text-accent" href="/examples/route-handler/data">GET /examples/route-handler/data</a> returns JSON.</p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/modules/async-render/components/server-clock.ts b/packages/cli/templates/gallery/modules/async-render/components/server-clock.ts
new file mode 100644
index 000000000..cb729c767
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/async-render/components/server-clock.ts
@@ -0,0 +1,26 @@
+// async render() awaits server data directly in the leaf component. Three
+// decoupled concerns to know (see AGENTS.md "Async render"):
+//   1. SSR always BLOCKS, so the resolved data is in the first paint with no
+//      fallback markup (progressive-enhancement safe, readable with JS off).
+//   2. The client re-fetch default is stale-while-revalidate (old content stays
+//      until the new render resolves, no blank flash).
+//   3. renderFallback() is the OPTIONAL re-fetch loading UI, never first paint.
+// Reach for async render() when request-time SERVER data belongs in the first
+// paint; reach for a Task / signals for genuinely client-only data.
+import { WebComponent, html } from '@webjsdev/core';
+import { serverGreeting } from '../queries/server-greeting.server.ts';
+
+export class ServerClock extends WebComponent {
+  // A bare async-render component (no other client signal) is ELIDED, since its
+  // SSR'd HTML is already the complete output. `static refresh = true` opts into
+  // keeping the on-load re-fetch so the module ships (drop it for request-stable
+  // data you are happy to leave server-rendered).
+  static refresh = true;
+
+  async render() {
+    const info = await serverGreeting();
+    return html`<p class="font-mono text-sm">server rendered this at
+      <strong>${info.at}</strong> (pid ${info.pid})</p>`;
+  }
+}
+ServerClock.register('server-clock');
diff --git a/packages/cli/templates/gallery/modules/async-render/queries/server-greeting.server.ts b/packages/cli/templates/gallery/modules/async-render/queries/server-greeting.server.ts
new file mode 100644
index 000000000..7ec27067d
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/async-render/queries/server-greeting.server.ts
@@ -0,0 +1,9 @@
+'use server';
+// A GET 'use server' query a component awaits directly inside `async render()`.
+// It returns request-time SERVER data the client cannot know, which is exactly
+// what async render() is for (the resolved value lands in the first paint).
+export const method = 'GET';
+
+export async function serverGreeting(): Promise<{ at: string; pid: number }> {
+  return { at: new Date().toISOString(), pid: process.pid };
+}
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
new file mode 100644
index 000000000..8f8aa4b2f
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -0,0 +1,49 @@
+// The lit-html directive set webjs re-exports (from '@webjsdev/core/directives').
+// `repeat` keys a list so DOM nodes are REUSED across reorders instead of being
+// recreated (use it for keyed lists that reorder; plain `.map()` is fine for
+// static lists). `watch(signal)` does a fine-grained DOM swap of ONE node when
+// the signal changes, without re-running the whole template.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { repeat, watch } from '@webjsdev/core/directives';
+
+interface Item { id: number; label: string }
+
+let nextId = 4;
+
+export class DirectiveDemo extends WebComponent {
+  private items = signal<Item[]>([
+    { id: 1, label: 'Alpha' },
+    { id: 2, label: 'Bravo' },
+    { id: 3, label: 'Charlie' },
+  ]);
+  private ticks = signal(0);
+
+  private reverse() {
+    this.items.set(this.items.get().slice().reverse());
+  }
+  private add() {
+    const id = nextId++;
+    this.items.set([...this.items.get(), { id, label: 'Item ' + id }]);
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <div class="flex gap-2">
+          <button @click=${() => this.reverse()} class="px-3 py-1.5 rounded bg-accent text-accent-fg">Reverse</button>
+          <button @click=${() => this.add()} class="px-3 py-1.5 rounded border border-border">Add</button>
+        </div>
+        <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
+        <ul class="grid gap-1 list-none m-0 p-0">
+          ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
+            <li class="border border-border rounded px-3 py-1.5">#${it.id} ${it.label}</li>
+          `)}
+        </ul>
+        <!-- watch(signal) swaps only this node when ticks changes. -->
+        <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
+          class="text-sm underline underline-offset-4 w-fit">ticks: ${watch(this.ticks)}</button>
+      </div>
+    `;
+  }
+}
+DirectiveDemo.register('directive-demo');
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
new file mode 100644
index 000000000..27923fc72
--- /dev/null
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -0,0 +1,148 @@
+/**
+ * Verifies the always-on example gallery the full-stack scaffold ships (#824 /
+ * #821 / #817): idiomatic example routes under app/examples/ with their logic
+ * in modules/, linked from the home page, backed by a todos table, each page
+ * carrying a webjs-scaffold-placeholder marker so `webjs check` fails until an
+ * agent keeps-and-adapts or prunes it.
+ *
+ * Also guards the scoping decision: api has no UI and saas overwrites the schema
+ * with its own focused auth example, so the gallery ships in FULL-STACK ONLY.
+ *
+ * The todo query assertion is a regression guard for the rc.3 relational-query
+ * orderBy bug (`[desc(col)]` compiles to `no such column: d0.0`); the query must
+ * use the object form `{ createdAt: 'desc' }`.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { scaffoldApp } from '../../packages/cli/lib/create.js';
+
+const EXAMPLES = [
+  'todo', 'tic-tac-toe', 'components', 'routing', 'server-actions',
+  'async-render', 'directives', 'route-handler',
+];
+// Examples whose logic lives in a modules/<name> folder (routing and
+// route-handler are app-only: a pages-only route and a route.ts handler).
+const MODULE_EXAMPLES = ['todo', 'tic-tac-toe', 'components', 'server-actions', 'async-render', 'directives'];
+
+async function tempCwd() {
+  return mkdtemp(join(tmpdir(), 'webjs-scaffold-gallery-'));
+}
+async function exists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+test('full-stack scaffold ships the example gallery (routes + modules)', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const appDir = join(cwd, 'demo');
+
+    for (const name of EXAMPLES) {
+      assert.ok(
+        await exists(join(appDir, 'app', 'examples', name, 'page.ts')),
+        `app/examples/${name}/page.ts should exist`,
+      );
+    }
+    // Dynamic route param example.
+    assert.ok(await exists(join(appDir, 'app', 'examples', 'routing', '[id]', 'page.ts')));
+    // Route-handler example ships a server-only route.ts endpoint.
+    assert.ok(await exists(join(appDir, 'app', 'examples', 'route-handler', 'data', 'route.ts')));
+    // Feature logic lives in modules/, not app/.
+    for (const name of MODULE_EXAMPLES) {
+      assert.ok(await exists(join(appDir, 'modules', name)), `modules/${name} should exist`);
+    }
+    assert.ok(await exists(join(appDir, 'modules', 'todo', 'queries', 'list-todos.server.ts')));
+    assert.ok(await exists(join(appDir, 'modules', 'todo', 'components', 'todo-app.ts')));
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('full-stack home page links the gallery and keeps its placeholder marker', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const appDir = join(cwd, 'demo');
+    const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
+
+    assert.match(home, /webjs-scaffold-placeholder/, 'home keeps its placeholder marker');
+    for (const name of EXAMPLES) {
+      assert.match(home, new RegExp(`/examples/${name}`), `home links /examples/${name}`);
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('every gallery example page carries a webjs-scaffold-placeholder marker', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const appDir = join(cwd, 'demo');
+    for (const name of EXAMPLES) {
+      const src = await readFile(join(appDir, 'app', 'examples', name, 'page.ts'), 'utf8');
+      assert.match(
+        src,
+        /webjs-scaffold-placeholder/,
+        `app/examples/${name}/page.ts must carry a placeholder marker so the agent prunes or keeps it`,
+      );
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('full-stack schema adds a todos table backing the gallery', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const schema = await readFile(join(cwd, 'demo', 'db', 'schema.server.ts'), 'utf8');
+    assert.match(schema, /export const todos = table\('todos'/, 'todos table present');
+    assert.match(schema, /defineRelations\(\{ users, todos \}/, 'todos wired into relations');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('gallery todo query uses rc.3 object-form orderBy (regression guard)', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const q = await readFile(join(cwd, 'demo', 'modules', 'todo', 'queries', 'list-todos.server.ts'), 'utf8');
+    assert.match(q, /orderBy:\s*\{\s*createdAt:\s*'desc'\s*\}/, 'uses object-form orderBy');
+    // The array form `orderBy: [desc(col)]` mis-compiles in rc.3; match only real
+    // code (an `orderBy: [`), not the cautionary comment that names the bad form.
+    assert.doesNotMatch(q, /orderBy:\s*\[/, 'must not use array-form orderBy which mis-compiles in rc.3');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('api and saas do NOT ship the gallery (full-stack only)', async () => {
+  for (const template of ['api', 'saas']) {
+    const cwd = await tempCwd();
+    try {
+      await scaffoldApp('demo', cwd, { template });
+      const appDir = join(cwd, 'demo');
+      assert.equal(
+        existsSync(join(appDir, 'app', 'examples')),
+        false,
+        `${template} must not ship app/examples`,
+      );
+      assert.equal(
+        existsSync(join(appDir, 'modules', 'todo')),
+        false,
+        `${template} must not ship the todo module`,
+      );
+      const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
+      assert.doesNotMatch(schema, /table\('todos'/, `${template} schema must not add the gallery todos table`);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  }
+});

From 87b037284839bb13d7df406418b0fb5fa2248252 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 16:57:28 +0530
Subject: [PATCH 13/53] refactor(cli): split the gallery into features/ and one
 example app

Feedback: the gallery mixed granularities, single-feature demos
(components, server-actions, routing, ...) sat in the same app/examples/
bucket as whole apps (todo, tic-tac-toe). Separate them by kind:

- app/features/<name>/  single-feature demos (routing, components,
  server-actions, optimistic-ui, async-render, directives, route-handler).
- app/examples/<name>/  whole apps that compose features (todo).

Add a focused /features/optimistic-ui demo (the imperative
optimistic(signal, value, action) flip) distinct from the todo app's
declarative list form, and drop tic-tac-toe (a toy whose only lesson,
client-only signals, is already covered by components + directives). The
home page now has separate Features and Example apps sections. Docs
templates, banner, and tests follow.

Verified: fresh app typechecks (exit 0), all routes boot 200, and the
like-button + todo optimistic paths work in the browser.
---
 packages/cli/lib/create.js                    | 113 ++++++++++--------
 .../cli/templates/.agents/rules/workflow.md   |  15 +--
 packages/cli/templates/.cursorrules           |  15 +--
 .../templates/.github/copilot-instructions.md |  15 +--
 packages/cli/templates/AGENTS.md              |  44 ++++---
 packages/cli/templates/CONVENTIONS.md         |  40 ++++---
 .../gallery/app/examples/tic-tac-toe/page.ts  |  17 ---
 .../async-render/page.ts                      |   2 +-
 .../{examples => features}/components/page.ts |   2 +-
 .../{examples => features}/directives/page.ts |   2 +-
 .../app/features/optimistic-ui/page.ts        |  14 +++
 .../route-handler/data/route.ts               |   0
 .../route-handler/page.ts                     |   2 +-
 .../routing/[id]/page.ts                      |   0
 .../{examples => features}/routing/page.ts    |   4 +-
 .../server-actions/page.ts                    |   2 +-
 .../optimistic-ui/actions/like-post.server.ts |   9 ++
 .../optimistic-ui/components/like-button.ts   |  34 ++++++
 .../tic-tac-toe/components/tic-tac-toe.ts     |  52 --------
 test/scaffolds/scaffold-gallery.test.js       |  95 ++++++++-------
 .../scaffolds/scaffold-ui-integration.test.js |  13 +-
 21 files changed, 256 insertions(+), 234 deletions(-)
 delete mode 100644 packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
 rename packages/cli/templates/gallery/app/{examples => features}/async-render/page.ts (84%)
 rename packages/cli/templates/gallery/app/{examples => features}/components/page.ts (83%)
 rename packages/cli/templates/gallery/app/{examples => features}/directives/page.ts (84%)
 create mode 100644 packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
 rename packages/cli/templates/gallery/app/{examples => features}/route-handler/data/route.ts (100%)
 rename packages/cli/templates/gallery/app/{examples => features}/route-handler/page.ts (85%)
 rename packages/cli/templates/gallery/app/{examples => features}/routing/[id]/page.ts (100%)
 rename packages/cli/templates/gallery/app/{examples => features}/routing/page.ts (82%)
 rename packages/cli/templates/gallery/app/{examples => features}/server-actions/page.ts (84%)
 create mode 100644 packages/cli/templates/gallery/modules/optimistic-ui/actions/like-post.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
 delete mode 100644 packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 5ca6f235a..a8ad276cd 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -134,8 +134,9 @@ async function copyUiComponents(appDir, names) {
 /**
  * Copy the example gallery (idiomatic, densely-commented working examples) into
  * the scaffolded app. Merges `templates/gallery/{app,modules}` over the app so
- * the example routes land under `app/examples/<feature>/` and their logic under
- * `modules/<feature>/`, the app-thin + modules-logic split webjs prescribes.
+ * single-feature demos land under `app/features/<name>/`, whole example apps
+ * under `app/examples/<name>/`, and their logic under `modules/<name>/`, the
+ * app-thin + modules-logic split webjs prescribes.
  *
  * Ships verbatim (no `{{APP_NAME}}` substitution): the examples are self-
  * contained and reference only `@webjsdev/*`, drizzle, `#db/*`, and each other.
@@ -954,9 +955,9 @@ export type ActionResult<T> =
       'button', 'card', 'alert', 'badge', 'separator', 'label', 'input',
     ]);
 
-    // The example gallery: idiomatic, densely-commented working examples of
-    // webjs features (app-thin routes under app/examples/ + modules/<feature>/
-    // logic), linked from the home page. Shipped in the default full-stack
+    // The gallery: idiomatic, densely-commented single-feature demos under
+    // app/features/ plus one whole example app under app/examples/, with logic
+    // in modules/, linked from the home page. Shipped in the default full-stack
     // scaffold so an agent gains context by browsing real code; prune
     // per-feature (delete the route + its module) for what the app does not
     // use. See CONVENTIONS.md "prune what the app does not use".
@@ -1194,55 +1195,69 @@ export const metadata = {
   title: '${name}: built with webjs',
 };
 
-// The example routes this scaffold ships, each a small idiomatic webjs app.
-// Prune the ones you do not need (delete the app/examples/<name> route AND its
-// modules/<name> folder), then reshape this page into your app's real home.
+// Two kinds of reference the scaffold ships. FEATURES are single-concept demos
+// (one webjs feature each, under app/features/, logic in modules/). EXAMPLES are
+// whole apps that compose several features (under app/examples/). Prune what you
+// do not use (delete the route AND its modules/<name>), then reshape this page.
+const features = [
+  { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+  { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+  { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+  { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+  { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+  { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+  { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
+];
 const examples = [
-  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'Optimistic UI with instant updates and auto-rollback, progressive-enhancement forms, accessible labels, and the app-thin plus modules split, backed by SQLite.' },
-  { href: '/examples/tic-tac-toe', title: 'Tic-tac-toe', blurb: 'Client-only state with signals. No server and no database, so all interactivity lives in the component.' },
-  { href: '/examples/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
-  { href: '/examples/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
-  { href: '/examples/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
-  { href: '/examples/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
-  { href: '/examples/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
-  { href: '/examples/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
 ];
 
+const galleryCard = (item: { href: string; title: string; blurb: string }) => html\`
+  <a href=\${item.href} class="block no-underline">
+    <div class="\${cardClass()} h-full transition-colors hover:border-border-strong">
+      <div class=\${cardHeaderClass()}>
+        <h3 class=\${cardTitleClass()}>\${item.title}</h3>
+        <p class=\${cardDescriptionClass()}>\${item.blurb}</p>
+      </div>
+    </div>
+  </a>
+\`;
+
 export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
       \${displayH1(html\`Hello from <span class="text-accent italic">${name}</span>.\`)}
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
-        This scaffold ships an example gallery below: small, idiomatic, heavily
-        commented webjs apps. Browse them for context, then replace this page
-        with your own. See \${accentLink('https://docs.webjs.com', 'the docs')}
-        for the full reference.
+        This scaffold ships a gallery below: single-feature demos and one whole
+        example app, all small, idiomatic, and heavily commented. Browse them for
+        context, then replace this page with your own. See
+        \${accentLink('https://docs.webjs.com', 'the docs')} for the full reference.
       </p>
       <div class="flex gap-3 items-center">
-        <a href="/examples/todo" class=\${buttonClass()}>Open the todo example</a>
+        <a href="/examples/todo" class=\${buttonClass()}>Open the todo app</a>
         <span class=\${badgeClass({ variant: 'secondary' })}>v0.1</span>
       </div>
     </section>
 
+    <section class="mb-12">
+      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Features</h2>
+      <p class="text-fg-muted text-sm m-0 mb-5">
+        One webjs concept each, under <code class="font-mono text-[0.9em]">app/features/</code>
+        with logic in <code class="font-mono text-[0.9em]">modules/</code>. Delete the ones you do not need.
+      </p>
+      <div class="grid gap-4 sm:grid-cols-2">
+        \${features.map(galleryCard)}
+      </div>
+    </section>
+
     <section>
-      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Example gallery</h2>
+      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Example apps</h2>
       <p class="text-fg-muted text-sm m-0 mb-5">
-        Each route lives under <code class="font-mono text-[0.9em]">app/examples/</code>
-        with its logic in <code class="font-mono text-[0.9em]">modules/</code>.
-        Delete the ones you do not need.
+        Whole apps that compose several features, under <code class="font-mono text-[0.9em]">app/examples/</code>.
       </p>
       <div class="grid gap-4 sm:grid-cols-2">
-        \${examples.map((ex) => html\`
-          <a href=\${ex.href} class="block no-underline">
-            <div class="\${cardClass()} h-full transition-colors hover:border-border-strong">
-              <div class=\${cardHeaderClass()}>
-                <h3 class=\${cardTitleClass()}>\${ex.title}</h3>
-                <p class=\${cardDescriptionClass()}>\${ex.blurb}</p>
-              </div>
-            </div>
-          </a>
-        \`)}
+        \${examples.map(galleryCard)}
       </div>
     </section>
   \`;
@@ -1365,10 +1380,11 @@ ThemeToggle.register('theme-toggle');
 `);
   } else {
     console.log(`  ${name}/
-    app/layout.ts, page.ts       ← home links to the example gallery
-    app/examples/{todo,tic-tac-toe,components,routing,server-actions,
+    app/layout.ts, page.ts       ← home links to the gallery
+    app/features/{routing,components,server-actions,optimistic-ui,
                   async-render,directives,route-handler}/
-                                 ← thin routes for the gallery
+                                 ← single-feature demos
+    app/examples/todo/           ← one whole example app (composes features)
     styles/globals.css           ← @webjsdev/ui theme tokens
     components.json              ← preconfigured for \`webjs ui add\`
     components/ui/{button,card,alert,badge,separator,label,input}.ts
@@ -1376,8 +1392,8 @@ ThemeToggle.register('theme-toggle');
     lib/utils/cn.ts              ← cn() helper for ui-* components
     lib/utils/ui.ts              ← Tailwind class-bundle helpers
     public/tailwind-browser.js   ← Tailwind runtime
-    modules/{todo,tic-tac-toe,components,server-actions,async-render,
-             directives}/       ← gallery logic (prune what you skip)
+    modules/{components,server-actions,optimistic-ui,async-render,
+             directives,todo}/  ← feature + example logic (prune what you skip)
     db/{schema,columns,connection}.server.ts  ← Drizzle (User + Todo)
     CONVENTIONS.md, AGENTS.md, CLAUDE.md
 `);
@@ -1395,16 +1411,17 @@ ThemeToggle.register('theme-toggle');
   ✓ Convention validation via \`webjs check\`
 
 For AI agents, read this before editing scaffolded files:
-  • The example layout, home page, the app/examples gallery (+ its
-    modules) and schema are REFERENCE ONLY. Replace them with the app
-    the user asked for, and prune the example routes you do not use
-    (delete the app/examples/<name> route AND its modules/<name>). Don't
-    ship the scaffold's examples as the final product.
+  • The example layout, home page, the gallery under app/features/ and
+    app/examples/ (+ their modules) and schema are REFERENCE ONLY. Replace
+    them with the app the user asked for, and prune the routes you do not
+    use (delete the app/features/<name> or app/examples/<name> route AND
+    its modules/<name>). Don't ship the scaffold's examples as the final
+    product.
   • This fresh app intentionally FAILS \`webjs check\` with
     no-scaffold-placeholder violations on the example content (the home
-    page, the layout, and each app/examples route). That is the signal
-    to replace or prune each. Delete the marker comment line as you do,
-    and the check goes green.
+    page, the layout, and each gallery route). That is the signal to
+    replace or prune each. Delete the marker comment line as you do, and
+    the check goes green.
   • Use Drizzle + SQLite for app data. It's already wired up. Define
     real models in db/schema.server.ts, then run \`webjs db generate\`
     and \`webjs db migrate\`. NEVER store app data in JSON files,
diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index d077e738a..6176da9f8 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -19,13 +19,14 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   the example `User` model, the example users module, etc. with the app the
   user actually asked for. Do not ship "Hello from <app-name>" as the
   deliverable.
-- **The example gallery is reference too, prune it.** The full-stack scaffold
-  ships a gallery under `app/examples/` (logic in `modules/`). Read it to learn
-  the patterns, keep and adapt what you need, and delete the rest (the
-  `app/examples/<name>` route AND its `modules/<name>`; for the todo example,
-  also the `todos` table). Each example page has a `webjs-scaffold-placeholder`
-  marker so `webjs check` fails until you resolve it. Delete now-empty
-  directories after pruning.
+- **The gallery is reference too, prune it.** The full-stack scaffold ships
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). Read it to learn the patterns, keep and
+  adapt what you need, and delete the rest (the `app/features/<name>` or
+  `app/examples/<name>` route AND its `modules/<name>`; for the todo app, also
+  the `todos` table). Each route page has a `webjs-scaffold-placeholder` marker
+  so `webjs check` fails until you resolve it. Delete now-empty directories after
+  pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
   route, middleware, metadata routes). CSS, helpers, and constants do NOT:
   `globals.css` is at `styles/`, browser-safe helpers at `lib/utils/`, feature
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 431ea2446..fbef5568c 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -18,13 +18,14 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **The example gallery is reference too, prune it.** The full-stack
-  scaffold ships a gallery under `app/examples/` (logic in `modules/`).
-  Read it to learn the patterns, keep and adapt what you need, and delete
-  the rest (the `app/examples/<name>` route AND its `modules/<name>`; for
-  the todo example, also the `todos` table). Each example page has a
-  `webjs-scaffold-placeholder` marker so `webjs check` fails until you
-  resolve it. Delete now-empty directories after pruning.
+- **The gallery is reference too, prune it.** The full-stack scaffold ships
+  single-feature demos under `app/features/` plus one whole example app
+  under `app/examples/` (logic in `modules/`). Read it to learn the
+  patterns, keep and adapt what you need, and delete the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its
+  `modules/<name>`; for the todo app, also the `todos` table). Each route
+  page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
   do NOT: `globals.css` is at `styles/`, browser-safe helpers at
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 912fb5053..39783e956 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -18,13 +18,14 @@ the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **The example gallery is reference too, prune it.** The full-stack
-  scaffold ships a gallery under `app/examples/` (logic in `modules/`).
-  Read it to learn the patterns, keep and adapt what you need, and delete
-  the rest (the `app/examples/<name>` route AND its `modules/<name>`; for
-  the todo example, also the `todos` table). Each example page has a
-  `webjs-scaffold-placeholder` marker so `webjs check` fails until you
-  resolve it. Delete now-empty directories after pruning.
+- **The gallery is reference too, prune it.** The full-stack scaffold ships
+  single-feature demos under `app/features/` plus one whole example app
+  under `app/examples/` (logic in `modules/`). Read it to learn the
+  patterns, keep and adapt what you need, and delete the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its
+  `modules/<name>`; for the todo app, also the `todos` table). Each route
+  page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
   do NOT: `globals.css` is at `styles/`, browser-safe helpers at
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 3d3415e43..a58e47d1b 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -309,10 +309,12 @@ app/                     ROUTING ONLY: thin route adapters (import from modules/
                          No CSS, helpers, or constants here; those live in
                          styles/, lib/utils/, and modules/. globals.css is at
                          styles/, NOT app/.
-  page.ts                → / (the scaffold home links to the example gallery)
-  examples/<name>/       the example gallery (todo, tic-tac-toe, components,
-                         routing, server-actions, async-render, directives,
-                         route-handler); prune what you do not use
+  page.ts                → / (the scaffold home links to the gallery)
+  features/<name>/       single-feature demos (routing, components,
+                         server-actions, optimistic-ui, async-render,
+                         directives, route-handler); prune what you skip
+  examples/<name>/       whole example apps that compose features (todo);
+                         prune what you skip
   layout.ts              root layout, wraps every page
   error.ts               error boundary (render failures → user-friendly)
   loading.ts             Suspense fallback for sibling page
@@ -355,20 +357,26 @@ test/<feature>/                feature-scoped tests, one folder per concern
 middleware.ts            root middleware (optional, outermost)
 ```
 
-### The example gallery (reference content, prune it)
-
-The scaffold ships a working example gallery under `app/examples/` with its
-logic in `modules/`. Each example is small, idiomatic, and heavily commented,
-so read them to learn the webjs patterns (optimistic UI, progressive
-enhancement, signals, slots, dynamic routes, the `.server.ts` vs `'use server'`
-boundary). They are REFERENCE, not your app: keep and adapt the ones you need,
-and prune the rest. Pruning one example means deleting its `app/examples/<name>`
-route AND its `modules/<name>` folder (and, for the todo example, the `todos`
-table in `db/schema.server.ts`), then removing its link from `app/page.ts`. Each
-example page carries a `webjs-scaffold-placeholder` marker so `webjs check`
-fails until you have consciously kept-and-adapted or pruned it. After pruning,
-delete any now-empty directories (an empty `lib/utils/` or `modules/<name>/` is
-leftover scaffolding, not structure).
+### The gallery (reference content, prune it)
+
+The scaffold ships a gallery organized by KIND, so features and whole apps are
+not mixed:
+- `app/features/<name>/` are single-feature demos, one webjs concept each
+  (routing, components, server-actions, optimistic-ui, async-render, directives,
+  route-handler).
+- `app/examples/<name>/` are whole example apps that compose several features
+  (todo: optimistic UI + progressive enhancement + a11y + db + modules).
+
+Both keep their logic in `modules/<name>/`. Each route is small, idiomatic, and
+heavily commented, so read them to learn the webjs patterns. They are REFERENCE,
+not your app: keep and adapt the ones you need, and prune the rest. Pruning a
+route means deleting its `app/features/<name>` or `app/examples/<name>` folder
+AND its `modules/<name>` folder (and, for the todo app, the `todos` table in
+`db/schema.server.ts`), then removing its link from `app/page.ts`. Each route
+page carries a `webjs-scaffold-placeholder` marker so `webjs check` fails until
+you have consciously kept-and-adapted or pruned it. After pruning, delete any
+now-empty directories (an empty `lib/utils/` or `modules/<name>/` is leftover
+scaffolding, not structure).
 
 ### Typed page / layout / route-handler props
 
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index d4e0079c9..632c0a01a 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -311,20 +311,22 @@ production workloads.
 
 This project was created with `webjs create`. Every file you see right
 now (the `app/page.ts` homepage, the example `User` model, the
-`theme-toggle` component, the example gallery under `app/examples/` in
-the full-stack template, the example users module in api / saas
-templates) is a **starting point**.
-
-The full-stack scaffold ships an **example gallery**: small, idiomatic,
-heavily commented working apps under `app/examples/` (with their logic in
-`modules/`) that demonstrate optimistic UI, progressive enhancement,
-signals, slots, dynamic routes, and the `.server.ts` vs `'use server'`
-boundary. Read them to learn the patterns. They are REFERENCE, not the
-app: keep and adapt the ones you need, and **prune the rest**. Pruning an
-example means deleting its `app/examples/<name>` route AND its
-`modules/<name>` folder (for the todo example, also the `todos` table in
-`db/schema.server.ts` and its link in `app/page.ts`). Each example page
-carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails
+`theme-toggle` component, the gallery under `app/features/` and
+`app/examples/` in the full-stack template, the example users module in
+api / saas templates) is a **starting point**.
+
+The full-stack scaffold ships a **gallery** organized by kind so features
+and whole apps are not mixed. `app/features/<name>/` are single-feature
+demos, one webjs concept each (routing, components, server-actions,
+optimistic-ui, async-render, directives, route-handler). `app/examples/<name>/`
+are whole example apps that compose several features (todo: optimistic UI
++ progressive enhancement + a11y + db + modules). Both keep their logic in
+`modules/`, are small and heavily commented, and are REFERENCE, not the
+app: keep and adapt the ones you need, and **prune the rest**. Pruning a
+route means deleting its `app/features/<name>` or `app/examples/<name>`
+folder AND its `modules/<name>` folder (for the todo app, also the `todos`
+table in `db/schema.server.ts` and its link in `app/page.ts`). Each route
+page carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails
 until you consciously keep-and-adapt or prune it. After pruning, delete
 any now-empty directories, an empty `lib/utils/` or `modules/<name>/` is
 leftover scaffolding, not structure.
@@ -347,9 +349,10 @@ When the user asks the agent to build their actual app:
    need a theme picker.
 4. **Delete the example users module** (api/saas templates) if the app
    doesn't use it.
-4b. **Prune the example gallery** (full-stack template). Keep and adapt the
-   examples the app uses, delete the rest (route + module + any table),
-   and remove their links from `app/page.ts`.
+4b. **Prune the gallery** (full-stack template). Keep and adapt the
+   `app/features/` demos and the `app/examples/` app the real app uses,
+   delete the rest (route + module + any table), and remove their links
+   from `app/page.ts`.
 5. **Adapt `app/layout.ts` to the app, not just the page.** Set the real
    brand, replace the example `Home` nav with the app's navigation, and
    pick a content-width container that fits. The default
@@ -373,7 +376,8 @@ When the user asks the agent to build their actual app:
    infrastructure, not the example app.
 
 This is enforced, not just advised. The example `app/page.ts`,
-`app/layout.ts`, and each `app/examples/<name>/page.ts` carry a
+`app/layout.ts`, and each `app/features/<name>/page.ts` +
+`app/examples/<name>/page.ts` carry a
 `webjs-scaffold-placeholder` marker comment, and the
 `no-scaffold-placeholder` check fails while any marker remains, so a
 freshly scaffolded app fails `webjs check` until you address each
diff --git a/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts b/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
deleted file mode 100644
index 3b1e5af8d..000000000
--- a/packages/cli/templates/gallery/app/examples/tic-tac-toe/page.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/tic-tac-toe route AND modules/tic-tac-toe), then delete this marker line. webjs check fails while the marker remains.
-// A thin route rendering a client-only component. The page runs server-side to
-// produce the SSR'd first paint (the empty board), then <tic-tac-toe> hydrates
-// and all interactivity runs client-side. Pages do not hydrate; components do.
-import { html } from '@webjsdev/core';
-import type { Metadata } from '@webjsdev/core';
-import '#modules/tic-tac-toe/components/tic-tac-toe.ts';
-
-export const metadata: Metadata = { title: 'Tic-tac-toe (client signals) | examples' };
-
-export default function TicTacToeExample() {
-  return html`
-    <h1 class="text-h2 font-bold mb-4">Tic-tac-toe</h1>
-    <p class="text-fg-muted mb-4">Client-only interactivity with signals, no server or database.</p>
-    <tic-tac-toe></tic-tac-toe>
-  `;
-}
diff --git a/packages/cli/templates/gallery/app/examples/async-render/page.ts b/packages/cli/templates/gallery/app/features/async-render/page.ts
similarity index 84%
rename from packages/cli/templates/gallery/app/examples/async-render/page.ts
rename to packages/cli/templates/gallery/app/features/async-render/page.ts
index f9af3509f..402f25122 100644
--- a/packages/cli/templates/gallery/app/examples/async-render/page.ts
+++ b/packages/cli/templates/gallery/app/features/async-render/page.ts
@@ -1,4 +1,4 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/async-render route AND modules/async-render), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/async-render route AND modules/async-render), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/async-render/components/server-clock.ts';
diff --git a/packages/cli/templates/gallery/app/examples/components/page.ts b/packages/cli/templates/gallery/app/features/components/page.ts
similarity index 83%
rename from packages/cli/templates/gallery/app/examples/components/page.ts
rename to packages/cli/templates/gallery/app/features/components/page.ts
index 846ea85d4..e173a56f2 100644
--- a/packages/cli/templates/gallery/app/examples/components/page.ts
+++ b/packages/cli/templates/gallery/app/features/components/page.ts
@@ -1,4 +1,4 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/components route AND modules/components), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/components route AND modules/components), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/components/components/counter-card.ts';
diff --git a/packages/cli/templates/gallery/app/examples/directives/page.ts b/packages/cli/templates/gallery/app/features/directives/page.ts
similarity index 84%
rename from packages/cli/templates/gallery/app/examples/directives/page.ts
rename to packages/cli/templates/gallery/app/features/directives/page.ts
index aed77e68a..75bc67ee9 100644
--- a/packages/cli/templates/gallery/app/examples/directives/page.ts
+++ b/packages/cli/templates/gallery/app/features/directives/page.ts
@@ -1,4 +1,4 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/directives route AND modules/directives), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/directives route AND modules/directives), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/directives/components/directive-demo.ts';
diff --git a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
new file mode 100644
index 000000000..f747d250b
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
@@ -0,0 +1,14 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/optimistic-ui route AND modules/optimistic-ui), then delete this marker line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/optimistic-ui/components/like-button.ts';
+
+export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | features' };
+
+export default function OptimisticUiFeature() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Optimistic UI</h1>
+    <p class="text-fg-muted mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-accent" href="/examples/todo">/examples/todo</a>.</p>
+    <like-button></like-button>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/examples/route-handler/data/route.ts b/packages/cli/templates/gallery/app/features/route-handler/data/route.ts
similarity index 100%
rename from packages/cli/templates/gallery/app/examples/route-handler/data/route.ts
rename to packages/cli/templates/gallery/app/features/route-handler/data/route.ts
diff --git a/packages/cli/templates/gallery/app/examples/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
similarity index 85%
rename from packages/cli/templates/gallery/app/examples/route-handler/page.ts
rename to packages/cli/templates/gallery/app/features/route-handler/page.ts
index c86aade26..e702b05dd 100644
--- a/packages/cli/templates/gallery/app/examples/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/page.ts
@@ -1,4 +1,4 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/route-handler route, including its data/route.ts handler), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/route-handler route, including its data/route.ts handler), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 
diff --git a/packages/cli/templates/gallery/app/examples/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
similarity index 100%
rename from packages/cli/templates/gallery/app/examples/routing/[id]/page.ts
rename to packages/cli/templates/gallery/app/features/routing/[id]/page.ts
diff --git a/packages/cli/templates/gallery/app/examples/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
similarity index 82%
rename from packages/cli/templates/gallery/app/examples/routing/page.ts
rename to packages/cli/templates/gallery/app/features/routing/page.ts
index fa23704f3..91fb18950 100644
--- a/packages/cli/templates/gallery/app/examples/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -1,7 +1,7 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/routing route), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/routing route), then delete this marker line. webjs check fails while the marker remains.
 // Routing basics: a static page that links to a dynamic route. app/ is routing
 // only; a folder maps to a URL segment, and [id] is a dynamic segment read from
-// `params`. See app/examples/routing/[id]/page.ts.
+// `params`. See app/features/routing/[id]/page.ts.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 
diff --git a/packages/cli/templates/gallery/app/examples/server-actions/page.ts b/packages/cli/templates/gallery/app/features/server-actions/page.ts
similarity index 84%
rename from packages/cli/templates/gallery/app/examples/server-actions/page.ts
rename to packages/cli/templates/gallery/app/features/server-actions/page.ts
index ac226766f..6be3115dc 100644
--- a/packages/cli/templates/gallery/app/examples/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/features/server-actions/page.ts
@@ -1,4 +1,4 @@
-// webjs-scaffold-placeholder. Example gallery route. Keep and adapt it, or prune it (delete this app/examples/server-actions route AND modules/server-actions), then delete this marker line. webjs check fails while the marker remains.
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/server-actions route AND modules/server-actions), then delete this marker line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/server-actions/components/greeter.ts';
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/actions/like-post.server.ts b/packages/cli/templates/gallery/modules/optimistic-ui/actions/like-post.server.ts
new file mode 100644
index 000000000..839e7dea3
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/actions/like-post.server.ts
@@ -0,0 +1,9 @@
+'use server';
+// A tiny mutation for the optimistic-UI feature demo. It validates and echoes
+// (no persistence needed to show the mechanic). In a real app this would write
+// to the db and return the saved row.
+import type { ActionResult } from '@webjsdev/server';
+
+export async function likePost(input: { liked: boolean }): Promise<ActionResult<{ liked: boolean }>> {
+  return { success: true, data: { liked: !!input?.liked } };
+}
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
new file mode 100644
index 000000000..e3ded09ad
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -0,0 +1,34 @@
+// The IMPERATIVE optimistic() form for a simple flip: set the signal to the new
+// value instantly, run the action, and roll back automatically if it rejects.
+// Use optimistic UI where the client can PREDICT the result (likes, toggles,
+// reorders, renames). Skip it where it hurts: unpredictable / server-computed
+// results, side-effectful or OAuth / payment mutations, and destructive
+// irreversible actions (confirm-first is better there).
+//
+// This is the simple-flip API. For a LIST mutation (add / remove with rollback)
+// see the declarative optimistic(host, { source, update }) + .add() form in the
+// /examples/todo app.
+import { WebComponent, signal, optimistic, html } from '@webjsdev/core';
+import { likePost } from '../actions/like-post.server.ts';
+
+export class LikeButton extends WebComponent {
+  private liked = signal(false);
+
+  private async toggle() {
+    const next = !this.liked.get();
+    // optimistic(signal, value, action) flips `liked` to `next` immediately,
+    // runs the action, and restores the old value if the action rejects.
+    await optimistic(this.liked, next, () => likePost({ liked: next }));
+  }
+
+  render() {
+    const liked = this.liked.get();
+    return html`
+      <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
+        class="px-4 py-2 rounded-full border font-semibold ${liked ? 'bg-accent text-accent-fg border-accent' : 'border-border'}">
+        ${liked ? 'Liked' : 'Like'}
+      </button>
+    `;
+  }
+}
+LikeButton.register('like-button');
diff --git a/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts b/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts
deleted file mode 100644
index de2942a79..000000000
--- a/packages/cli/templates/gallery/modules/tic-tac-toe/components/tic-tac-toe.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-// A CLIENT-ONLY interactive component: no server, no db. Demonstrates instance
-// signals as the default state primitive (read with .get() in render(), the
-// built-in SignalWatcher re-renders on change) and @click handlers. Nothing
-// here ships to the server; it is pure client interactivity in a component.
-import { WebComponent, signal, html } from '@webjsdev/core';
-
-type Cell = 'X' | 'O' | null;
-
-export class TicTacToe extends WebComponent {
-  // Instance signals are component-local (a module-scope signal would be shared
-  // across every instance and survive navigations, which is not wanted here).
-  private board = signal<Cell[]>(Array(9).fill(null));
-  private turn = signal<'X' | 'O'>('X');
-
-  private winner(b: Cell[]): Cell {
-    const lines = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
-    for (const [a, c, d] of lines) if (b[a] && b[a] === b[c] && b[a] === b[d]) return b[a];
-    return null;
-  }
-
-  private play(i: number) {
-    const b = this.board.get();
-    if (b[i] || this.winner(b)) return;
-    const next = b.slice();
-    next[i] = this.turn.get();
-    this.board.set(next);
-    this.turn.set(this.turn.get() === 'X' ? 'O' : 'X');
-  }
-
-  private reset() { this.board.set(Array(9).fill(null)); this.turn.set('X'); }
-
-  render() {
-    const b = this.board.get();
-    const win = this.winner(b);
-    const status = win ? `${win} wins` : b.every(Boolean) ? 'Draw' : `${this.turn.get()} to move`;
-    return html`
-      <div class="grid gap-3 w-fit">
-        <p class="font-semibold" aria-live="polite">${status}</p>
-        <div class="grid grid-cols-3 gap-1">
-          ${b.map((cell, i) => html`
-            <button
-              @click=${() => this.play(i)}
-              aria-label="cell ${i + 1}${cell ? `, ${cell}` : ''}"
-              class="w-14 h-14 text-2xl font-bold border border-border rounded grid place-items-center">${cell ?? ''}</button>
-          `)}
-        </div>
-        <button @click=${() => this.reset()} class="text-sm text-fg-subtle underline underline-offset-4">Reset</button>
-      </div>
-    `;
-  }
-}
-TicTacToe.register('tic-tac-toe');
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 27923fc72..cd0bc76e8 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -1,8 +1,10 @@
 /**
- * Verifies the always-on example gallery the full-stack scaffold ships (#824 /
- * #821 / #817): idiomatic example routes under app/examples/ with their logic
- * in modules/, linked from the home page, backed by a todos table, each page
- * carrying a webjs-scaffold-placeholder marker so `webjs check` fails until an
+ * Verifies the always-on gallery the full-stack scaffold ships (#824 / #821 /
+ * #817), organized by KIND so features and whole apps are not mixed:
+ *   - app/features/<name>  single-feature demos (one webjs concept each),
+ *   - app/examples/<name>  whole example apps that compose several features.
+ * Each has its logic in modules/<name>, is linked from the home page, and
+ * carries a webjs-scaffold-placeholder marker so `webjs check` fails until an
  * agent keeps-and-adapts or prunes it.
  *
  * Also guards the scoping decision: api has no UI and saas overwrites the schema
@@ -21,13 +23,16 @@ import { tmpdir } from 'node:os';
 
 import { scaffoldApp } from '../../packages/cli/lib/create.js';
 
-const EXAMPLES = [
-  'todo', 'tic-tac-toe', 'components', 'routing', 'server-actions',
+// Single-feature demos under app/features/<name>.
+const FEATURES = [
+  'routing', 'components', 'server-actions', 'optimistic-ui',
   'async-render', 'directives', 'route-handler',
 ];
-// Examples whose logic lives in a modules/<name> folder (routing and
+// Whole example apps under app/examples/<name>.
+const EXAMPLE_APPS = ['todo'];
+// Routes whose logic lives in a modules/<name> folder (routing and
 // route-handler are app-only: a pages-only route and a route.ts handler).
-const MODULE_EXAMPLES = ['todo', 'tic-tac-toe', 'components', 'server-actions', 'async-render', 'directives'];
+const MODULE_ROUTES = ['components', 'server-actions', 'optimistic-ui', 'async-render', 'directives', 'todo'];
 
 async function tempCwd() {
   return mkdtemp(join(tmpdir(), 'webjs-scaffold-gallery-'));
@@ -36,42 +41,44 @@ async function exists(p) {
   try { await stat(p); return true; } catch { return false; }
 }
 
-test('full-stack scaffold ships the example gallery (routes + modules)', async () => {
+test('full-stack scaffold ships feature demos and one example app', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
     const appDir = join(cwd, 'demo');
 
-    for (const name of EXAMPLES) {
-      assert.ok(
-        await exists(join(appDir, 'app', 'examples', name, 'page.ts')),
-        `app/examples/${name}/page.ts should exist`,
-      );
+    for (const name of FEATURES) {
+      assert.ok(await exists(join(appDir, 'app', 'features', name, 'page.ts')), `app/features/${name}/page.ts`);
     }
-    // Dynamic route param example.
-    assert.ok(await exists(join(appDir, 'app', 'examples', 'routing', '[id]', 'page.ts')));
-    // Route-handler example ships a server-only route.ts endpoint.
-    assert.ok(await exists(join(appDir, 'app', 'examples', 'route-handler', 'data', 'route.ts')));
-    // Feature logic lives in modules/, not app/.
-    for (const name of MODULE_EXAMPLES) {
-      assert.ok(await exists(join(appDir, 'modules', name)), `modules/${name} should exist`);
+    for (const name of EXAMPLE_APPS) {
+      assert.ok(await exists(join(appDir, 'app', 'examples', name, 'page.ts')), `app/examples/${name}/page.ts`);
     }
-    assert.ok(await exists(join(appDir, 'modules', 'todo', 'queries', 'list-todos.server.ts')));
-    assert.ok(await exists(join(appDir, 'modules', 'todo', 'components', 'todo-app.ts')));
+    // Dynamic route param example + the route.ts handler.
+    assert.ok(await exists(join(appDir, 'app', 'features', 'routing', '[id]', 'page.ts')));
+    assert.ok(await exists(join(appDir, 'app', 'features', 'route-handler', 'data', 'route.ts')));
+    // Feature/app logic lives in modules/, not app/.
+    for (const name of MODULE_ROUTES) {
+      assert.ok(await exists(join(appDir, 'modules', name)), `modules/${name}`);
+    }
+    // tic-tac-toe was dropped.
+    assert.equal(existsSync(join(appDir, 'app', 'examples', 'tic-tac-toe')), false);
+    assert.equal(existsSync(join(appDir, 'modules', 'tic-tac-toe')), false);
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }
 });
 
-test('full-stack home page links the gallery and keeps its placeholder marker', async () => {
+test('full-stack home page links every feature and the example app, keeps its marker', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
-    const appDir = join(cwd, 'demo');
-    const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
+    const home = await readFile(join(cwd, 'demo', 'app', 'page.ts'), 'utf8');
 
     assert.match(home, /webjs-scaffold-placeholder/, 'home keeps its placeholder marker');
-    for (const name of EXAMPLES) {
+    for (const name of FEATURES) {
+      assert.match(home, new RegExp(`/features/${name}`), `home links /features/${name}`);
+    }
+    for (const name of EXAMPLE_APPS) {
       assert.match(home, new RegExp(`/examples/${name}`), `home links /examples/${name}`);
     }
   } finally {
@@ -79,25 +86,25 @@ test('full-stack home page links the gallery and keeps its placeholder marker',
   }
 });
 
-test('every gallery example page carries a webjs-scaffold-placeholder marker', async () => {
+test('every gallery route page carries a webjs-scaffold-placeholder marker', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
     const appDir = join(cwd, 'demo');
-    for (const name of EXAMPLES) {
+    for (const name of FEATURES) {
+      const src = await readFile(join(appDir, 'app', 'features', name, 'page.ts'), 'utf8');
+      assert.match(src, /webjs-scaffold-placeholder/, `app/features/${name} marker`);
+    }
+    for (const name of EXAMPLE_APPS) {
       const src = await readFile(join(appDir, 'app', 'examples', name, 'page.ts'), 'utf8');
-      assert.match(
-        src,
-        /webjs-scaffold-placeholder/,
-        `app/examples/${name}/page.ts must carry a placeholder marker so the agent prunes or keeps it`,
-      );
+      assert.match(src, /webjs-scaffold-placeholder/, `app/examples/${name} marker`);
     }
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }
 });
 
-test('full-stack schema adds a todos table backing the gallery', async () => {
+test('full-stack schema adds a todos table backing the todo example', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
@@ -109,14 +116,13 @@ test('full-stack schema adds a todos table backing the gallery', async () => {
   }
 });
 
-test('gallery todo query uses rc.3 object-form orderBy (regression guard)', async () => {
+test('todo query uses rc.3 object-form orderBy (regression guard)', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'full-stack' });
     const q = await readFile(join(cwd, 'demo', 'modules', 'todo', 'queries', 'list-todos.server.ts'), 'utf8');
     assert.match(q, /orderBy:\s*\{\s*createdAt:\s*'desc'\s*\}/, 'uses object-form orderBy');
-    // The array form `orderBy: [desc(col)]` mis-compiles in rc.3; match only real
-    // code (an `orderBy: [`), not the cautionary comment that names the bad form.
+    // Match only real code (an `orderBy: [`), not the cautionary comment.
     assert.doesNotMatch(q, /orderBy:\s*\[/, 'must not use array-form orderBy which mis-compiles in rc.3');
   } finally {
     await rm(cwd, { recursive: true, force: true });
@@ -129,16 +135,9 @@ test('api and saas do NOT ship the gallery (full-stack only)', async () => {
     try {
       await scaffoldApp('demo', cwd, { template });
       const appDir = join(cwd, 'demo');
-      assert.equal(
-        existsSync(join(appDir, 'app', 'examples')),
-        false,
-        `${template} must not ship app/examples`,
-      );
-      assert.equal(
-        existsSync(join(appDir, 'modules', 'todo')),
-        false,
-        `${template} must not ship the todo module`,
-      );
+      assert.equal(existsSync(join(appDir, 'app', 'features')), false, `${template} must not ship app/features`);
+      assert.equal(existsSync(join(appDir, 'app', 'examples')), false, `${template} must not ship app/examples`);
+      assert.equal(existsSync(join(appDir, 'modules', 'todo')), false, `${template} must not ship the todo module`);
       const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
       assert.doesNotMatch(schema, /table\('todos'/, `${template} schema must not add the gallery todos table`);
     } finally {
diff --git a/test/scaffolds/scaffold-ui-integration.test.js b/test/scaffolds/scaffold-ui-integration.test.js
index 78282fdbe..3ba6fcc97 100644
--- a/test/scaffolds/scaffold-ui-integration.test.js
+++ b/test/scaffolds/scaffold-ui-integration.test.js
@@ -1,6 +1,6 @@
 /**
  * Verifies that the full-stack and saas scaffolds pre-initialise the Webjs UI
- * kit correctly: components.json + lib/utils/cn.ts + app/globals.css are
+ * kit correctly: components.json + lib/utils/cn.ts + styles/globals.css are
  * written, the standard component sources land in components/ui/, generated
  * pages call the Tier-1 class helpers on raw native elements (not stale
  * `<ui-X>` tags for Tier-1 components), and the API template deliberately
@@ -72,11 +72,13 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
     assert.ok(await exists(join(appDir, 'components.json')), 'components.json should exist');
     assert.ok(await exists(join(appDir, 'lib', 'utils', 'cn.ts')), 'lib/utils/cn.ts should exist');
     assert.ok(await exists(join(appDir, 'lib', 'utils', 'ui.ts')), 'lib/utils/ui.ts should exist');
-    assert.ok(await exists(join(appDir, 'app', 'globals.css')), 'app/globals.css should exist');
+    assert.ok(await exists(join(appDir, 'styles', 'globals.css')), 'styles/globals.css should exist');
+    // app/ is routing-only: the theme must NOT live in app/.
+    assert.equal(existsSync(join(appDir, 'app', 'globals.css')), false, 'globals.css must not be in routing-only app/');
 
     // components.json shape matches what webjsui init writes for webjs
     const cfg = JSON.parse(await readFile(join(appDir, 'components.json'), 'utf8'));
-    assert.equal(cfg.tailwind.css, 'app/globals.css');
+    assert.equal(cfg.tailwind.css, 'styles/globals.css');
     assert.equal(cfg.tailwind.baseColor, 'neutral');
     assert.equal(cfg.aliases.ui, 'components/ui');
     assert.equal(cfg.aliases.utils, 'lib/utils/cn');
@@ -108,9 +110,9 @@ test('full-stack scaffold pre-initialises the Webjs UI kit', async () => {
       'Tier-1 side-effect imports should be removed from layout',
     );
 
-    // Homepage calls Tier-1 class helpers on native elements
+    // Homepage (the gallery index) calls Tier-1 class helpers on native elements
     const page = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
-    for (const fn of [...TIER1_HELPERS_BUTTON, 'badgeClass', 'cardClass', 'cardHeaderClass', 'cardTitleClass', 'alertClass']) {
+    for (const fn of [...TIER1_HELPERS_BUTTON, 'badgeClass', 'cardClass', 'cardHeaderClass', 'cardTitleClass', 'cardDescriptionClass']) {
       assert.match(page, new RegExp(`\\b${fn}\\b`), `homepage should call ${fn}()`);
     }
     // …and contains no Tier-1 custom element tags
@@ -185,6 +187,7 @@ test('api scaffold deliberately ships no ui-* components', async () => {
     assert.equal(existsSync(join(appDir, 'components', 'ui')), false);
     assert.equal(existsSync(join(appDir, 'components.json')), false);
     assert.equal(existsSync(join(appDir, 'app', 'globals.css')), false);
+    assert.equal(existsSync(join(appDir, 'styles', 'globals.css')), false);
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }

From 4249c46d1f83cc18dffacfee32199d9656b5bd5c Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 17:02:08 +0530
Subject: [PATCH 14/53] docs(cli): tell agents to study the gallery fully
 before pruning

The gallery is the agent's primary webjs reference (#821), so pruning
must come AFTER reading it, never before (#818's ordering rule). Make the
sequence explicit across all five rule files plus AGENTS.md/CONVENTIONS.md:
study every feature demo and the example app end to end to absorb the
idioms first, prune only after internalising them, and never delete the
examples blindly up front.
---
 .../cli/templates/.agents/rules/workflow.md   | 16 +++++-----
 packages/cli/templates/.cursorrules           | 16 +++++-----
 .../templates/.github/copilot-instructions.md | 16 +++++-----
 packages/cli/templates/AGENTS.md              | 31 +++++++++++++------
 packages/cli/templates/CONVENTIONS.md         | 28 ++++++++++++-----
 5 files changed, 69 insertions(+), 38 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index 6176da9f8..a0fcf512d 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -19,14 +19,16 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   the example `User` model, the example users module, etc. with the app the
   user actually asked for. Do not ship "Hello from <app-name>" as the
   deliverable.
-- **The gallery is reference too, prune it.** The full-stack scaffold ships
+- **Study the gallery first, prune it second.** The full-stack scaffold ships
   single-feature demos under `app/features/` plus one whole example app under
-  `app/examples/` (logic in `modules/`). Read it to learn the patterns, keep and
-  adapt what you need, and delete the rest (the `app/features/<name>` or
-  `app/examples/<name>` route AND its `modules/<name>`; for the todo app, also
-  the `todos` table). Each route page has a `webjs-scaffold-placeholder` marker
-  so `webjs check` fails until you resolve it. Delete now-empty directories after
-  pruning.
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference: read
+  every demo end to end (code AND comments) to learn the idioms BEFORE you write
+  or delete anything. Only after internalising the patterns should you prune,
+  keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
   route, middleware, metadata routes). CSS, helpers, and constants do NOT:
   `globals.css` is at `styles/`, browser-safe helpers at `lib/utils/`, feature
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index fbef5568c..9baeb73e5 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -18,13 +18,15 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **The gallery is reference too, prune it.** The full-stack scaffold ships
-  single-feature demos under `app/features/` plus one whole example app
-  under `app/examples/` (logic in `modules/`). Read it to learn the
-  patterns, keep and adapt what you need, and delete the rest (the
-  `app/features/<name>` or `app/examples/<name>` route AND its
-  `modules/<name>`; for the todo app, also the `todos` table). Each route
-  page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+- **Study the gallery first, prune it second.** The full-stack scaffold ships
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
   until you resolve it. Delete now-empty directories after pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 39783e956..e2342dee2 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -18,13 +18,15 @@ the full hosted docs are at **https://docs.webjs.com**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **The gallery is reference too, prune it.** The full-stack scaffold ships
-  single-feature demos under `app/features/` plus one whole example app
-  under `app/examples/` (logic in `modules/`). Read it to learn the
-  patterns, keep and adapt what you need, and delete the rest (the
-  `app/features/<name>` or `app/examples/<name>` route AND its
-  `modules/<name>`; for the todo app, also the `todos` table). Each route
-  page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+- **Study the gallery first, prune it second.** The full-stack scaffold ships
+  single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
+  read every demo end to end (code AND comments) to learn the idioms BEFORE you
+  write or delete anything. Only after internalising the patterns should you
+  prune, keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
   until you resolve it. Delete now-empty directories after pruning.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index a58e47d1b..4cedfd44d 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -368,15 +368,28 @@ not mixed:
   (todo: optimistic UI + progressive enhancement + a11y + db + modules).
 
 Both keep their logic in `modules/<name>/`. Each route is small, idiomatic, and
-heavily commented, so read them to learn the webjs patterns. They are REFERENCE,
-not your app: keep and adapt the ones you need, and prune the rest. Pruning a
-route means deleting its `app/features/<name>` or `app/examples/<name>` folder
-AND its `modules/<name>` folder (and, for the todo app, the `todos` table in
-`db/schema.server.ts`), then removing its link from `app/page.ts`. Each route
-page carries a `webjs-scaffold-placeholder` marker so `webjs check` fails until
-you have consciously kept-and-adapted or pruned it. After pruning, delete any
-now-empty directories (an empty `lib/utils/` or `modules/<name>/` is leftover
-scaffolding, not structure).
+heavily commented, and the gallery is your PRIMARY reference for how webjs works.
+
+**Study the whole gallery FIRST, prune SECOND.** Before you write or delete
+anything, read every feature demo and the example app end to end (the code AND
+the comments) to absorb the idioms you will reuse: the modules split, signals,
+the `optimistic()` API, `async render()`, the `.server.ts` vs `'use server'`
+boundary, progressive-enhancement forms, `<label for>` a11y, dynamic routes, and
+`route.ts` handlers. Only AFTER you have internalised the patterns should you
+prune. Never delete the examples blindly up front (that throws away your context
+before you have read it), and never prune the durable knowledge surfaces
+(`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files), which stay as context
+for every future iteration.
+
+Then prune: the examples are REFERENCE, not your app, so keep and adapt the ones
+you need and delete the rest. Pruning a route means deleting its
+`app/features/<name>` or `app/examples/<name>` folder AND its `modules/<name>`
+folder (and, for the todo app, the `todos` table in `db/schema.server.ts`), then
+removing its link from `app/page.ts`. Each route page carries a
+`webjs-scaffold-placeholder` marker so `webjs check` fails until you have
+consciously kept-and-adapted or pruned it. After pruning, delete any now-empty
+directories (an empty `lib/utils/` or `modules/<name>/` is leftover scaffolding,
+not structure).
 
 ### Typed page / layout / route-handler props
 
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index 632c0a01a..784e36813 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -321,14 +321,26 @@ demos, one webjs concept each (routing, components, server-actions,
 optimistic-ui, async-render, directives, route-handler). `app/examples/<name>/`
 are whole example apps that compose several features (todo: optimistic UI
 + progressive enhancement + a11y + db + modules). Both keep their logic in
-`modules/`, are small and heavily commented, and are REFERENCE, not the
-app: keep and adapt the ones you need, and **prune the rest**. Pruning a
-route means deleting its `app/features/<name>` or `app/examples/<name>`
-folder AND its `modules/<name>` folder (for the todo app, also the `todos`
-table in `db/schema.server.ts` and its link in `app/page.ts`). Each route
-page carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails
-until you consciously keep-and-adapt or prune it. After pruning, delete
-any now-empty directories, an empty `lib/utils/` or `modules/<name>/` is
+`modules/`, are small and heavily commented, and are the PRIMARY reference
+for how webjs works.
+
+**Study the whole gallery FIRST, prune SECOND.** Before writing or deleting
+anything, read every feature demo and the example app end to end (code AND
+comments) to absorb the idioms you will reuse. Only AFTER you have
+internalised the patterns should you prune. Never delete the examples
+blindly up front (that discards your context before you have read it), and
+never prune the durable knowledge surfaces (`AGENTS.md`, `CONVENTIONS.md`,
+the per-agent rule files), which stay as context for every future
+iteration.
+
+Then prune: the examples are REFERENCE, not the app, so keep and adapt the
+ones you need and **delete the rest**. Pruning a route means deleting its
+`app/features/<name>` or `app/examples/<name>` folder AND its
+`modules/<name>` folder (for the todo app, also the `todos` table in
+`db/schema.server.ts` and its link in `app/page.ts`). Each route page
+carries a `webjs-scaffold-placeholder` marker, so `webjs check` fails until
+you consciously keep-and-adapt or prune it. After pruning, delete any
+now-empty directories, an empty `lib/utils/` or `modules/<name>/` is
 leftover scaffolding, not structure.
 
 **`app/` is routing-only.** Only routing files belong in `app/` (page,

From 7fd318332decbe824d78895c44b06ca5ecfb702a Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 17:06:04 +0530
Subject: [PATCH 15/53] fix(cli): repair stale /examples/ links in the moved
 feature demos

The features/ refactor updated the marker paths but missed the in-page
navigation links and one teaching comment, so 3 of the 7 feature demos
linked to /examples/* 404s (routing's sample links + Back link, the
route-handler endpoint link + its comment). Point them at /features/*.
Also align the feature-page metadata title suffix to "| features".

Verified: every in-page link now resolves 200 on a booted app.
---
 .../cli/templates/gallery/app/features/async-render/page.ts | 2 +-
 .../cli/templates/gallery/app/features/components/page.ts   | 2 +-
 .../cli/templates/gallery/app/features/directives/page.ts   | 2 +-
 .../gallery/app/features/route-handler/data/route.ts        | 2 +-
 .../templates/gallery/app/features/route-handler/page.ts    | 4 ++--
 .../cli/templates/gallery/app/features/routing/[id]/page.ts | 2 +-
 packages/cli/templates/gallery/app/features/routing/page.ts | 6 +++---
 .../templates/gallery/app/features/server-actions/page.ts   | 2 +-
 8 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/async-render/page.ts b/packages/cli/templates/gallery/app/features/async-render/page.ts
index 402f25122..f7ec56db8 100644
--- a/packages/cli/templates/gallery/app/features/async-render/page.ts
+++ b/packages/cli/templates/gallery/app/features/async-render/page.ts
@@ -3,7 +3,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/async-render/components/server-clock.ts';
 
-export const metadata: Metadata = { title: 'Async render (server data in first paint) | examples' };
+export const metadata: Metadata = { title: 'Async render (server data in first paint) | features' };
 
 export default function AsyncRenderExample() {
   return html`
diff --git a/packages/cli/templates/gallery/app/features/components/page.ts b/packages/cli/templates/gallery/app/features/components/page.ts
index e173a56f2..8082e33da 100644
--- a/packages/cli/templates/gallery/app/features/components/page.ts
+++ b/packages/cli/templates/gallery/app/features/components/page.ts
@@ -3,7 +3,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/components/components/counter-card.ts';
 
-export const metadata: Metadata = { title: 'Components (signals + slots) | examples' };
+export const metadata: Metadata = { title: 'Components (signals + slots) | features' };
 
 export default function ComponentsExample() {
   return html`
diff --git a/packages/cli/templates/gallery/app/features/directives/page.ts b/packages/cli/templates/gallery/app/features/directives/page.ts
index 75bc67ee9..06a6b134f 100644
--- a/packages/cli/templates/gallery/app/features/directives/page.ts
+++ b/packages/cli/templates/gallery/app/features/directives/page.ts
@@ -3,7 +3,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/directives/components/directive-demo.ts';
 
-export const metadata: Metadata = { title: 'Directives (repeat + watch) | examples' };
+export const metadata: Metadata = { title: 'Directives (repeat + watch) | features' };
 
 export default function DirectivesExample() {
   return html`
diff --git a/packages/cli/templates/gallery/app/features/route-handler/data/route.ts b/packages/cli/templates/gallery/app/features/route-handler/data/route.ts
index c41daeffc..9c370430f 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/data/route.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/data/route.ts
@@ -2,7 +2,7 @@
 // DELETE exports). It is NOT isomorphic and never ships to the client, the webjs
 // equivalent of a Next route handler. Each handler returns a Response (a plain
 // value auto-JSONs). A folder cannot have BOTH page.ts and route.ts, so this
-// endpoint lives one segment deeper, at /examples/route-handler/data.
+// endpoint lives one segment deeper, at /features/route-handler/data.
 export async function GET() {
   return Response.json({ ok: true, at: new Date().toISOString() });
 }
diff --git a/packages/cli/templates/gallery/app/features/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
index e702b05dd..bdc92162e 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/page.ts
@@ -2,12 +2,12 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 
-export const metadata: Metadata = { title: 'Route handlers (route.ts) | examples' };
+export const metadata: Metadata = { title: 'Route handlers (route.ts) | features' };
 
 export default function RouteHandlerExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
     <p class="text-fg-muted mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
-    <p><a class="text-accent" href="/examples/route-handler/data">GET /examples/route-handler/data</a> returns JSON.</p>
+    <p><a class="text-accent" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index 947db9cbe..b58ef8251 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -7,6 +7,6 @@ export default function RoutingParam({ params }: { params: { id: string } }) {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route param</h1>
     <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
-    <p class="mt-3"><a class="text-accent" href="/examples/routing">Back</a></p>
+    <p class="mt-3"><a class="text-accent" href="/features/routing">Back</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 91fb18950..1506d3eca 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -5,15 +5,15 @@
 import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 
-export const metadata: Metadata = { title: 'Routing (dynamic params) | examples' };
+export const metadata: Metadata = { title: 'Routing (dynamic params) | features' };
 
 export default function RoutingExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Routing</h1>
     <p class="text-fg-muted mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
     <ul class="list-disc pl-5">
-      <li><a class="text-accent" href="/examples/routing/42">/examples/routing/42</a></li>
-      <li><a class="text-accent" href="/examples/routing/hello">/examples/routing/hello</a></li>
+      <li><a class="text-accent" href="/features/routing/42">/features/routing/42</a></li>
+      <li><a class="text-accent" href="/features/routing/hello">/features/routing/hello</a></li>
     </ul>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/server-actions/page.ts b/packages/cli/templates/gallery/app/features/server-actions/page.ts
index 6be3115dc..30189bccc 100644
--- a/packages/cli/templates/gallery/app/features/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/features/server-actions/page.ts
@@ -3,7 +3,7 @@ import { html } from '@webjsdev/core';
 import type { Metadata } from '@webjsdev/core';
 import '#modules/server-actions/components/greeter.ts';
 
-export const metadata: Metadata = { title: 'Server actions (.server vs use server) | examples' };
+export const metadata: Metadata = { title: 'Server actions (.server vs use server) | features' };
 
 export default function ServerActionsExample() {
   return html`

From 5f251640e1419f7585807f601b84309e0e8bde12 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 17:07:45 +0530
Subject: [PATCH 16/53] test(cli): guard against stale /examples/ links in
 feature pages

Regression test for the features/ refactor: assert no app/features page
links to a /examples/<name> route other than the todo app, so a future
rename that misses in-page hrefs fails CI instead of shipping 404s.
---
 test/scaffolds/scaffold-gallery.test.js | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index cd0bc76e8..6759eab1b 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -129,6 +129,30 @@ test('todo query uses rc.3 object-form orderBy (regression guard)', async () =>
   }
 });
 
+test('feature pages have no stale /examples/ links after the features refactor', async () => {
+  // Regression guard: moving the demos from app/examples/ to app/features/ must
+  // update the in-page hrefs too, not just the marker text. The ONLY valid
+  // /examples/* link anywhere is the todo app (app/examples/todo).
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'full-stack' });
+    const featuresDir = join(cwd, 'demo', 'app', 'features');
+    const pages = [
+      ...FEATURES.map((n) => join(featuresDir, n, 'page.ts')),
+      join(featuresDir, 'routing', '[id]', 'page.ts'),
+      join(featuresDir, 'route-handler', 'data', 'route.ts'),
+    ];
+    for (const p of pages) {
+      const src = await readFile(p, 'utf8');
+      for (const m of src.matchAll(/\/examples\/[a-z-]+/g)) {
+        assert.equal(m[0], '/examples/todo', `${p}: stale link ${m[0]} (todo is the only /examples/ route)`);
+      }
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
 test('api and saas do NOT ship the gallery (full-stack only)', async () => {
   for (const template of ['api', 'saas']) {
     const cwd = await tempCwd();

From cba8c8e9d1bf9707d8400da6c2e14e11c63488c7 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 17:16:08 +0530
Subject: [PATCH 17/53] docs(cli): point gallery comments at the app's own
 AGENTS.md

The gallery comments referenced agent-docs/orm.md and
agent-docs/types-and-mutations.md, which are added by the sibling PR #825
and do not exist on this branch, so they would be dead links if #826
merges first. Point them at the scaffolded app's own always-present
AGENTS.md sections instead, keeping #826 self-contained.
---
 .../gallery/modules/server-actions/utils/format.server.ts      | 3 ++-
 .../gallery/modules/todo/actions/create-todo.server.ts         | 3 ++-
 .../gallery/modules/todo/queries/list-todos.server.ts          | 2 +-
 packages/cli/templates/gallery/modules/todo/types.ts           | 2 +-
 4 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts b/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts
index 983119733..17b2e1f13 100644
--- a/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/utils/format.server.ts
@@ -1,7 +1,8 @@
 // A server-only utility: a `.server.ts` file with NO 'use server' directive.
 // Its browser import is a throw-at-load stub, so NEVER import this into a page
 // or component. Reach it only from a 'use server' action / route.ts / middleware.
-// (See agent-docs/types-and-mutations.md and the .server vs 'use server' rule.)
+// (See the server-actions section in this app's AGENTS.md for the .server.ts
+// vs 'use server' rule.)
 export function shout(s: string): string {
   return s.trim().toUpperCase() + '!';
 }
diff --git a/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts b/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
index e12040e3e..d1b222655 100644
--- a/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
+++ b/packages/cli/templates/gallery/modules/todo/actions/create-todo.server.ts
@@ -9,7 +9,8 @@ import type { ActionResult } from '@webjsdev/server';
 export async function createTodo(input: { title: string }): Promise<ActionResult<Todo>> {
   const title = String(input?.title ?? '').trim();
   if (!title) return { success: false, error: 'A task needs a title.', status: 400 };
-  // rc.3 mutation: `.returning()` takes NO field args in rc.3 (agent-docs/orm.md).
+  // rc.3 mutation: `.returning()` takes NO field args in rc.3 (see the Database
+  // section in this app's AGENTS.md).
   const [row] = await db.insert(todos).values({ title }).returning();
   return { success: true, data: row as Todo };
 }
diff --git a/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
index 8d69b507b..6d28986d0 100644
--- a/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
+++ b/packages/cli/templates/gallery/modules/todo/queries/list-todos.server.ts
@@ -13,7 +13,7 @@ export async function listTodos(): Promise<Todo[]> {
   // (`{ column: 'asc' | 'desc' }`); passing `[desc(todos.createdAt)]` with an
   // imported column mis-compiles to a bad SQL alias in rc.3. Do NOT use
   // `db.select({ col })` either (its projection overload trips TS2554 in rc.3).
-  // See agent-docs/orm.md.
+  // See the Database (Drizzle) section in this app's AGENTS.md.
   const rows = await db.query.todos.findMany({ orderBy: { createdAt: 'desc' } });
   return rows as Todo[];
 }
diff --git a/packages/cli/templates/gallery/modules/todo/types.ts b/packages/cli/templates/gallery/modules/todo/types.ts
index 89ebe5030..85d21f807 100644
--- a/packages/cli/templates/gallery/modules/todo/types.ts
+++ b/packages/cli/templates/gallery/modules/todo/types.ts
@@ -2,7 +2,7 @@
 // this type is imported by the browser-shipped <todo-app> component. A VALUE
 // import from `db/*.server.ts` would pin the component to a server module and
 // crash it at load (webjs check flags it). A browser-safe shape here is safe.
-// See agent-docs/types-and-mutations.md.
+// See the server-actions section in this app's AGENTS.md.
 export interface Todo {
   id: string;
   title: string;

From 7ea4955f30eff35d15f3adb3dc24c2ff4fbff832 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:08:11 +0530
Subject: [PATCH 18/53] fix(cli): polish gallery components with the UI kit

The gallery hand-rolled raw Tailwind (bg-accent buttons, an off-center
checkmark, a bare "x") that rendered flat and looked disabled. Switch the
buttons and inputs to the shipped @webjsdev/ui helpers (buttonClass /
inputClass), which CONVENTIONS already prescribes over raw Tailwind, and
fix the todo toggle: center the checkmark (inline-flex) and show it only
once completed; make delete a proper ghost icon button.

Verified in a real browser: components, server-actions, directives, and
the todo app now render as proper, consistent, polished controls.
---
 .../components/components/counter-card.ts      |  5 ++++-
 .../directives/components/directive-demo.ts    |  5 +++--
 .../server-actions/components/greeter.ts       |  6 ++++--
 .../modules/todo/components/todo-app.ts        | 18 +++++++++++++-----
 4 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index ae351b1b3..5afc1790e 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -3,6 +3,9 @@
 // for content projection (works in light DOM, the default). This is the core
 // component authoring shape.
 import { WebComponent, prop, signal, html } from '@webjsdev/core';
+// A shipped @webjsdev/ui class helper (CONVENTIONS.md prefers the kit over raw
+// Tailwind); it is a pure browser-safe function returning a class string.
+import { buttonClass } from '#components/ui/button.ts';
 
 export class CounterCard extends WebComponent({
   // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
@@ -23,7 +26,7 @@ export class CounterCard extends WebComponent({
         <slot></slot>
         <p class="font-semibold">${this.label}: ${this.count.get()}</p>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="px-3 py-1.5 rounded-lg bg-accent text-accent-fg w-fit">Increment</button>
+          class="${buttonClass({ size: 'sm' })} w-fit">Increment</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index 8f8aa4b2f..a540be6dc 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -5,6 +5,7 @@
 // the signal changes, without re-running the whole template.
 import { WebComponent, signal, html } from '@webjsdev/core';
 import { repeat, watch } from '@webjsdev/core/directives';
+import { buttonClass } from '#components/ui/button.ts';
 
 interface Item { id: number; label: string }
 
@@ -30,8 +31,8 @@ export class DirectiveDemo extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex gap-2">
-          <button @click=${() => this.reverse()} class="px-3 py-1.5 rounded bg-accent text-accent-fg">Reverse</button>
-          <button @click=${() => this.add()} class="px-3 py-1.5 rounded border border-border">Add</button>
+          <button @click=${() => this.reverse()} class=${buttonClass({ size: 'sm' })}>Reverse</button>
+          <button @click=${() => this.add()} class=${buttonClass({ variant: 'outline', size: 'sm' })}>Add</button>
         </div>
         <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
         <ul class="grid gap-1 list-none m-0 p-0">
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index ac53c3039..d96a5e302 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -1,6 +1,8 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
@@ -15,8 +17,8 @@ export class Greeter extends WebComponent {
   render() {
     return html`
       <form @submit=${(e: SubmitEvent) => this.run(e)} class="flex gap-2">
-        <input name="name" placeholder="your name" class="border border-border rounded px-3 py-2" />
-        <button type="submit" class="px-3 py-2 rounded bg-accent text-accent-fg">Greet</button>
+        <input name="name" placeholder="your name" class=${inputClass()} />
+        <button type="submit" class=${buttonClass()}>Greet</button>
       </form>
       <p class="mt-3 font-semibold">${this.msg.get()}</p>
     `;
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 372f231ab..c2abd1655 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -4,6 +4,12 @@
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+// Prefer the shipped @webjsdev/ui class helpers over hand-rolled Tailwind
+// (CONVENTIONS.md "UI components: prefer the Webjs UI kit"). They are pure
+// browser-safe functions returning a class string, so they compose with a
+// native element and add no client runtime.
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -72,8 +78,8 @@ export class TodoApp extends WebComponent({
              with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)} class="flex gap-2">
           <input type="hidden" name="intent" value="create" />
-          <input name="title" required placeholder="What needs doing?" class="flex-1 border border-border rounded-lg px-3 py-2" />
-          <button type="submit" class="px-4 py-2 rounded-lg bg-accent text-accent-fg font-semibold">Add</button>
+          <input name="title" required placeholder="What needs doing?" class="${inputClass()} flex-1" />
+          <button type="submit" class=${buttonClass()}>Add</button>
         </form>
         <ul class="list-none m-0 p-0 grid gap-2">
           ${list.map((todo) => html`
@@ -81,16 +87,18 @@ export class TodoApp extends WebComponent({
               <form method="post" action="" class="flex items-center gap-3 border border-border rounded-lg px-3 py-2 ${todo.pending ? 'opacity-50' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS
-                     @click intercepts for the optimistic toggle. -->
+                     @click intercepts for the optimistic toggle. The checkmark is
+                     centered (inline-flex) and only visible once completed. -->
                 <button id="t-${todo.id}" type="submit" name="intent" value="toggle"
                   aria-pressed=${todo.completed ? 'true' : 'false'}
                   @click=${(e: Event) => this.toggle(e, todo)}
-                  class="w-5 h-5 rounded-full border-2 ${todo.completed ? 'bg-accent border-accent' : 'border-border'}">✓</button>
+                  class="w-5 h-5 shrink-0 inline-flex items-center justify-center rounded-full border-2 text-[11px] leading-none transition-colors ${todo.completed ? 'bg-accent border-accent text-accent-fg' : 'border-border text-transparent hover:border-accent'}">✓</button>
                 <!-- The title is a <label for> the toggle: clicking the text toggles
                      the task (works on JS and no-JS paths, and screen readers). -->
                 <label for="t-${todo.id}" class="flex-1 cursor-pointer ${todo.completed ? 'line-through opacity-60' : ''}">${todo.title}</label>
                 <button type="submit" name="intent" value="delete" aria-label="Delete"
-                  @click=${(e: Event) => this.removeTodo(e, todo)} class="text-fg-subtle">x</button>
+                  @click=${(e: Event) => this.removeTodo(e, todo)}
+                  class="${buttonClass({ variant: 'ghost', size: 'icon' })} shrink-0 text-fg-muted hover:text-destructive">✕</button>
               </form>
             </li>
           `)}

From d6423192a74ac2f487cc0112e1cdba1e32d2d6ff Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:21:32 +0530
Subject: [PATCH 19/53] feat(cli): redesign gallery components to real-product
 quality

Bring the gallery to the taskflow bar with crafted, token-based Tailwind
instead of flat raw utilities or generic shadcn buttons: branded accent
buttons (hover:bg-accent-hover, active:scale), bg-elev cards, and proper
states. The todo gains a progress header, an elevated composer, task rows
with a centered SVG checkmark (cursor-pointer) and a hover-reveal delete,
and an empty state, matching taskflow. counter-card, greeter, directives,
and the like-button follow the same language.

Verified in a real browser: the todo and every feature demo now render as
a coherent, polished product.
---
 .../components/components/counter-card.ts     | 15 ++--
 .../directives/components/directive-demo.ts   | 15 ++--
 .../optimistic-ui/components/like-button.ts   |  3 +-
 .../server-actions/components/greeter.ts      | 17 +++--
 .../modules/todo/components/todo-app.ts       | 71 +++++++++++++------
 5 files changed, 79 insertions(+), 42 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index 5afc1790e..99a317c96 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -1,11 +1,9 @@
 // Demonstrates the WebComponent essentials: the declare-free reactive-prop
 // factory, an instance signal for local state, a lifecycle hook, and a <slot>
 // for content projection (works in light DOM, the default). This is the core
-// component authoring shape.
+// component authoring shape. Styling is crafted Tailwind on the app's design
+// tokens so it stays visually coherent with the rest of the app.
 import { WebComponent, prop, signal, html } from '@webjsdev/core';
-// A shipped @webjsdev/ui class helper (CONVENTIONS.md prefers the kit over raw
-// Tailwind); it is a pure browser-safe function returning a class string.
-import { buttonClass } from '#components/ui/button.ts';
 
 export class CounterCard extends WebComponent({
   // A reactive prop rides an HTML attribute / SSR hydration. Declared ONLY here
@@ -22,11 +20,14 @@ export class CounterCard extends WebComponent({
 
   render() {
     return html`
-      <div class="border border-border rounded-xl p-4 grid gap-2">
+      <div class="grid gap-4 p-5 rounded-2xl bg-bg-elev border border-border max-w-[320px]">
         <slot></slot>
-        <p class="font-semibold">${this.label}: ${this.count.get()}</p>
+        <div class="flex items-baseline gap-2">
+          <span class="text-[2.5rem] font-bold tabular-nums leading-none text-fg">${this.count.get()}</span>
+          <span class="text-sm text-fg-subtle">${this.label}</span>
+        </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="${buttonClass({ size: 'sm' })} w-fit">Increment</button>
+          class="w-fit px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Increment</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index a540be6dc..13221dfc6 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -5,7 +5,6 @@
 // the signal changes, without re-running the whole template.
 import { WebComponent, signal, html } from '@webjsdev/core';
 import { repeat, watch } from '@webjsdev/core/directives';
-import { buttonClass } from '#components/ui/button.ts';
 
 interface Item { id: number; label: string }
 
@@ -31,18 +30,22 @@ export class DirectiveDemo extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex gap-2">
-          <button @click=${() => this.reverse()} class=${buttonClass({ size: 'sm' })}>Reverse</button>
-          <button @click=${() => this.add()} class=${buttonClass({ variant: 'outline', size: 'sm' })}>Add</button>
+          <button @click=${() => this.reverse()}
+            class="px-3.5 py-1.5 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Reverse</button>
+          <button @click=${() => this.add()}
+            class="px-3.5 py-1.5 rounded-xl bg-bg-elev border border-border text-fg font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
         </div>
         <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
-        <ul class="grid gap-1 list-none m-0 p-0">
+        <ul class="grid gap-2 list-none m-0 p-0">
           ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
-            <li class="border border-border rounded px-3 py-1.5">#${it.id} ${it.label}</li>
+            <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-bg-elev border border-border text-[15px] text-fg">
+              <span class="text-fg-subtle tabular-nums text-[13px]">#${it.id}</span>${it.label}
+            </li>
           `)}
         </ul>
         <!-- watch(signal) swaps only this node when ticks changes. -->
         <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-          class="text-sm underline underline-offset-4 w-fit">ticks: ${watch(this.ticks)}</button>
+          class="w-fit text-sm text-fg-muted cursor-pointer transition-colors hover:text-fg underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
index e3ded09ad..9f033c01a 100644
--- a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -25,7 +25,8 @@ export class LikeButton extends WebComponent {
     const liked = this.liked.get();
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="px-4 py-2 rounded-full border font-semibold ${liked ? 'bg-accent text-accent-fg border-accent' : 'border-border'}">
+        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-accent text-accent-fg border-accent' : 'bg-bg-elev text-fg border-border hover:border-border-strong'}">
+        <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>
     `;
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index d96a5e302..ba9445576 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -1,8 +1,6 @@
 // Calls the 'use server' action via a normal import (the RPC stub). Never
 // hand-write fetch(); importing the action IS the API.
 import { WebComponent, signal, html } from '@webjsdev/core';
-import { buttonClass } from '#components/ui/button.ts';
-import { inputClass } from '#components/ui/input.ts';
 import { greet } from '../actions/greet.server.ts';
 
 export class Greeter extends WebComponent {
@@ -16,11 +14,16 @@ export class Greeter extends WebComponent {
   }
   render() {
     return html`
-      <form @submit=${(e: SubmitEvent) => this.run(e)} class="flex gap-2">
-        <input name="name" placeholder="your name" class=${inputClass()} />
-        <button type="submit" class=${buttonClass()}>Greet</button>
-      </form>
-      <p class="mt-3 font-semibold">${this.msg.get()}</p>
+      <div class="grid gap-3 max-w-[420px]">
+        <form @submit=${(e: SubmitEvent) => this.run(e)}
+          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-bg-elev border border-border">
+          <input name="name" placeholder="your name" autocomplete="off"
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-fg text-[15px] placeholder:text-fg-subtle py-1.5" />
+          <button type="submit"
+            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Greet</button>
+        </form>
+        ${this.msg.get() ? html`<p class="m-0 font-semibold text-fg">${this.msg.get()}</p>` : ''}
+      </div>
     `;
   }
 }
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index c2abd1655..1abe33172 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -3,13 +3,12 @@
 // progressive enhancement (each mutation is a <form> posting to the page action,
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
+//
+// Styling is crafted Tailwind on the app's design tokens (bg-elev, accent,
+// fg-muted, border-strong, ...), the same tokens the layout defines. Prefer this
+// or the @webjsdev/ui class helpers over ad-hoc colors, so the whole app stays
+// visually coherent.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
-// Prefer the shipped @webjsdev/ui class helpers over hand-rolled Tailwind
-// (CONVENTIONS.md "UI components: prefer the Webjs UI kit"). They are pure
-// browser-safe functions returning a class string, so they compose with a
-// native element and add no client runtime.
-import { buttonClass } from '#components/ui/button.ts';
-import { inputClass } from '#components/ui/input.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -59,8 +58,6 @@ export class TodoApp extends WebComponent({
     if (r.success && r.data) { const d = r.data; this.todos = (this.todos ?? []).map((t) => (t.id === todo.id ? d : t)); }
   }
 
-  // NOT named `remove`: Element.remove() is a built-in DOM method, so a method
-  // named `remove` with a different signature would clash (TS2416).
   async removeTodo(e: Event, todo: Todo) {
     e.preventDefault();
     if (todo.pending) return;
@@ -72,36 +69,68 @@ export class TodoApp extends WebComponent({
 
   render() {
     const list = this.store.value;
+    const done = list.filter((t) => t.completed).length;
+    const pct = list.length ? Math.round((done / list.length) * 100) : 0;
     return html`
-      <section class="grid gap-4 max-w-[520px]">
+      <section class="w-full max-w-[540px] grid gap-5">
+        <!-- Header: a title, a live done/total count, and a progress bar. -->
+        <header class="grid gap-3">
+          <div class="flex items-center gap-3">
+            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-accent-tint text-accent shrink-0">
+              <svg viewBox="0 0 24 24" class="w-5 h-5 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+            </span>
+            <div class="grid gap-0.5">
+              <h2 class="m-0 text-[1.4rem] font-bold tracking-[-0.02em] leading-none text-fg">Tasks</h2>
+              <p class="m-0 text-[13px] text-fg-subtle leading-none">${done} of ${list.length} done</p>
+            </div>
+            <span class="ml-auto text-[13px] font-semibold tabular-nums text-fg-muted">${pct}%</span>
+          </div>
+          <div class="h-1.5 rounded-full bg-bg-subtle overflow-hidden">
+            <div class="h-full rounded-full bg-accent transition-[width] duration-300" style="width:${pct}%"></div>
+          </div>
+        </header>
+
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
              with JS, @submit intercepts and runs the optimistic path. -->
-        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)} class="flex gap-2">
+        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
+          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-bg-elev border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--fg)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
-          <input name="title" required placeholder="What needs doing?" class="${inputClass()} flex-1" />
-          <button type="submit" class=${buttonClass()}>Add</button>
+          <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-fg text-[15px] placeholder:text-fg-subtle py-1.5" />
+          <button type="submit"
+            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Add</button>
         </form>
+
         <ul class="list-none m-0 p-0 grid gap-2">
-          ${list.map((todo) => html`
+          ${list.length ? list.map((todo) => html`
             <li>
-              <form method="post" action="" class="flex items-center gap-3 border border-border rounded-lg px-3 py-2 ${todo.pending ? 'opacity-50' : ''}">
+              <form method="post" action=""
+                class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-bg-elev border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS
-                     @click intercepts for the optimistic toggle. The checkmark is
-                     centered (inline-flex) and only visible once completed. -->
+                     @click intercepts for the optimistic toggle. The check is centered
+                     (grid place-items-center) and only visible once completed. -->
                 <button id="t-${todo.id}" type="submit" name="intent" value="toggle"
                   aria-pressed=${todo.completed ? 'true' : 'false'}
+                  aria-label=${todo.completed ? 'Mark as not done' : 'Mark as done'}
                   @click=${(e: Event) => this.toggle(e, todo)}
-                  class="w-5 h-5 shrink-0 inline-flex items-center justify-center rounded-full border-2 text-[11px] leading-none transition-colors ${todo.completed ? 'bg-accent border-accent text-accent-fg' : 'border-border text-transparent hover:border-accent'}">✓</button>
+                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-accent border-accent text-accent-fg' : 'bg-transparent border-border-strong text-transparent hover:border-accent'}">
+                  <svg viewBox="0 0 24 24" class="w-3 h-3 stroke-current fill-none" style="stroke-width:3.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+                </button>
                 <!-- The title is a <label for> the toggle: clicking the text toggles
                      the task (works on JS and no-JS paths, and screen readers). -->
-                <label for="t-${todo.id}" class="flex-1 cursor-pointer ${todo.completed ? 'line-through opacity-60' : ''}">${todo.title}</label>
-                <button type="submit" name="intent" value="delete" aria-label="Delete"
+                <label for="t-${todo.id}" class="flex-1 min-w-0 text-[15px] leading-snug break-words cursor-pointer select-none ${todo.completed ? 'line-through text-fg-subtle' : 'text-fg'}">${todo.title}</label>
+                <!-- Delete: a proper icon button, revealed on row hover / focus. -->
+                <button type="submit" name="intent" value="delete" aria-label="Delete task"
                   @click=${(e: Event) => this.removeTodo(e, todo)}
-                  class="${buttonClass({ variant: 'ghost', size: 'icon' })} shrink-0 text-fg-muted hover:text-destructive">✕</button>
+                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-fg-subtle cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
+                  <svg viewBox="0 0 24 24" class="w-4 h-4 stroke-current fill-none" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M18 6 6 18M6 6l12 12"/></svg>
+                </button>
               </form>
             </li>
-          `)}
+          `) : html`
+            <li class="text-center text-fg-subtle text-sm py-14 border border-dashed border-border rounded-2xl">No tasks yet. Add your first one above.</li>
+          `}
         </ul>
       </section>
     `;

From 89811487afd9f9ac0c6b35c698a8f1300ed9a439 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:25:23 +0530
Subject: [PATCH 20/53] fix(cli): make the hero accent stable across
 back-navigation

The hero used `text-accent`, a utility the no-build Tailwind browser
runtime regenerates on DOM change, so a client-router back-nav briefly
dropped it to a neutral fallback (most visible in dev, where the
live-reload connection disables bfcache). Paint the brand accent from the
`:root` design token via an inline style instead, so the color rides with
the DOM node and never depends on a runtime recompute.
---
 packages/cli/lib/create.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index a8ad276cd..b180f5286 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1227,7 +1227,7 @@ export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
-      \${displayH1(html\`Hello from <span class="text-accent italic">${name}</span>.\`)}
+      \${displayH1(html\`Hello from <span class="italic" style="color:var(--accent)">${name}</span>.\`)}
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for

From a5f0c42c45d40c27bb37947de26b3f232e440dbd Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:32:26 +0530
Subject: [PATCH 21/53] fix(cli): show a title-cased app name in the example
 hero

The hero rendered the raw npm slug ("gallery-preview"), which reads as an
ugly title. Derive a title-cased displayName ("Gallery Preview") for the
hero and the metadata title, while the package name stays the raw slug.
---
 packages/cli/lib/create.js | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index b180f5286..8ded6c44e 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -263,6 +263,11 @@ function assertUiRegistryAvailable() {
  */
 export async function scaffoldApp(name, cwd, opts = {}) {
   const template = opts.template || 'full-stack';
+  // A human-friendly display title for the example home page. The npm `name`
+  // stays the raw slug (lowercase, hyphenated), but showing a hyphenated slug as
+  // a hero title looks unpolished, so title-case it for display ("my-app" ->
+  // "My App"). Replace this with your real brand anyway.
+  const displayName = name.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
   // `install` is opt-in at the library level (so tests + programmatic
   // callers get a side-effect-free scaffold by default). The CLI entry
   // points (`webjs create` and `npx create-webjs-app`) explicitly set
@@ -1192,7 +1197,7 @@ import {
 } from '#components/ui/card.ts';
 
 export const metadata = {
-  title: '${name}: built with webjs',
+  title: '${displayName}: built with webjs',
 };
 
 // Two kinds of reference the scaffold ships. FEATURES are single-concept demos
@@ -1227,7 +1232,7 @@ export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
-      \${displayH1(html\`Hello from <span class="italic" style="color:var(--accent)">${name}</span>.\`)}
+      \${displayH1(html\`Hello from <span class="italic" style="color:var(--accent)">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for

From 044242733a74efd07b44e9bf7667942ecc21b335 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:44:57 +0530
Subject: [PATCH 22/53] feat(cli): match the scaffold accent to the webjs
 website (light + dark)

Align the scaffold's brand accent with the website's warm orange (hue 52,
chroma 0.16): light --accent oklch(0.54 0.16 52) on white text, dark
oklch(0.7 0.16 52) on dark text, with --accent-live driving the tint via
color-mix, exactly as website/app/layout.ts defines them. Revert the hero
accent to the Tailwind `text-accent` utility (no inline custom CSS); the
brief accent recompute on client-router back-navigation is a separate
framework-level trait of the no-build Tailwind runtime, tracked apart.
---
 packages/cli/lib/create.js | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 8ded6c44e..af301658b 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1108,10 +1108,12 @@ ${SHADCN_THEME}
         --bg-subtle:     oklch(0.16 0.01 55);
         --border:        oklch(0.26 0.012 55 / 0.9);
         --border-strong: oklch(0.38 0.012 55 / 0.9);
-        --accent:        oklch(0.78 0.14 55);
-        --accent-hover:  oklch(0.85 0.14 55);
-        --accent-fg:     oklch(0.15 0.01 55);
-        --accent-tint:   oklch(0.78 0.14 55 / 0.14);
+        /* Accent matches the webjs website (warm orange, hue 52). */
+        --accent:        oklch(0.7 0.16 52);
+        --accent-hover:  oklch(0.75 0.16 52);
+        --accent-fg:     oklch(0.17 0.02 52);
+        --accent-live:   oklch(0.63 0.17 50);
+        --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
         --font-sans:   -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         --font-serif:  ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:   ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
@@ -1125,10 +1127,11 @@ ${SHADCN_THEME}
         --bg-subtle:     oklch(0.96 0.008 80);
         --border:        oklch(0.88 0.01 75 / 0.95);
         --border-strong: oklch(0.78 0.01 75 / 0.95);
-        --accent:        oklch(0.58 0.15 55);
-        --accent-hover:  oklch(0.5 0.15 55);
+        --accent:        oklch(0.54 0.16 52);
+        --accent-hover:  oklch(0.5 0.16 52);
         --accent-fg:     oklch(1 0 0);
-        --accent-tint:   oklch(0.58 0.15 55 / 0.1);
+        --accent-live:   oklch(0.63 0.17 50);
+        --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
       }
       @media (prefers-color-scheme: light) {
         :root:not([data-theme='dark']) {
@@ -1140,10 +1143,11 @@ ${SHADCN_THEME}
           --bg-subtle:     oklch(0.96 0.008 80);
           --border:        oklch(0.88 0.01 75 / 0.95);
           --border-strong: oklch(0.78 0.01 75 / 0.95);
-          --accent:        oklch(0.58 0.15 55);
-          --accent-hover:  oklch(0.5 0.15 55);
+          --accent:        oklch(0.54 0.16 52);
+          --accent-hover:  oklch(0.5 0.16 52);
           --accent-fg:     oklch(1 0 0);
-          --accent-tint:   oklch(0.58 0.15 55 / 0.1);
+          --accent-live:   oklch(0.63 0.17 50);
+          --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
         }
       }
       /* Body + pseudo-elements utility classes can't reach. */
@@ -1232,7 +1236,7 @@ export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
-      \${displayH1(html\`Hello from <span class="italic" style="color:var(--accent)">${displayName}</span>.\`)}
+      \${displayH1(html\`Hello from <span class="text-accent italic">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for

From 1ed26d8b11e3637d155dc47c3f1000dd8527b2c4 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 18:51:41 +0530
Subject: [PATCH 23/53] feat(cli): add the forms feature demo (no-JS PE + page
 action)

A real <form> posting to the page's action export: server-side
validation returns fieldErrors on a 422 re-render, and success does a 303
Post-Redirect-Get to a confirmation. Works with JS off; the client router
applies the response in place with JS. Polished to the gallery design bar.

Verified in a booted app: GET 200, invalid POST shows all field errors,
valid POST redirects to the confirmation. (Caught that webjs searchParams
is a plain object, not a URLSearchParams.)
---
 packages/cli/lib/create.js                    |  1 +
 .../gallery/app/features/forms/page.ts        | 72 +++++++++++++++++++
 test/scaffolds/scaffold-gallery.test.js       |  2 +-
 3 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 packages/cli/templates/gallery/app/features/forms/page.ts

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index af301658b..6445863e0 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1216,6 +1216,7 @@ const features = [
   { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
   { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
   { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
+  { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
 ];
 const examples = [
   { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
new file mode 100644
index 000000000..a11510eee
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -0,0 +1,72 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/forms route), then delete this marker line. webjs check fails while the marker remains.
+// forms: the no-JS write path. A real <form method="post"> posts to this page's
+// `action` export, and the framework re-renders the SAME page with the result on
+// `actionData`. WHY it matters: the form works with JS OFF (server round-trip),
+// and with JS the client router applies the response in place (no full reload).
+// Never reach for fetch() + a click handler where a <form> + page action does.
+// On failure the framework re-renders at 422 with the result; on success it
+// does a 303 Post-Redirect-Get, so we redirect to ?sent=1 to show a confirmation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Forms (no-JS PE) | features' };
+
+interface Result {
+  success: boolean;
+  fieldErrors?: Record<string, string>;
+  values?: Record<string, string>;
+  redirect?: string;
+}
+
+const field = (label: string, name: string, input: unknown, error?: string) => html`
+  <div class="grid gap-1.5">
+    <label for=${name} class="text-[13px] font-medium text-fg-muted">${label}</label>
+    ${input}
+    ${error ? html`<p class="m-0 text-[12.5px] text-destructive">${error}</p>` : ''}
+  </div>
+`;
+
+const inputCls = 'w-full bg-bg border border-border rounded-xl px-3 py-2 text-[15px] text-fg outline-none transition-colors focus:border-accent placeholder:text-fg-subtle';
+
+export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
+  if (searchParams.sent) {
+    return html`
+      <h1 class="text-h2 font-bold mb-4">Forms</h1>
+      <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-bg-elev border border-border text-center">
+        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-accent-tint text-accent">
+          <svg viewBox="0 0 24 24" class="w-6 h-6 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
+        </span>
+        <p class="m-0 text-lg font-semibold text-fg">Message sent</p>
+        <p class="m-0 text-sm text-fg-muted">Thanks, we got it. <a class="text-accent" href="/features/forms">Send another</a>.</p>
+      </div>
+    `;
+  }
+  const errs = actionData?.fieldErrors ?? {};
+  const v = actionData?.values ?? {};
+  return html`
+    <h1 class="text-h2 font-bold mb-2">Forms</h1>
+    <p class="text-fg-muted mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
+    <form method="post" action="" class="max-w-[460px] grid gap-4 p-5 rounded-2xl bg-bg-elev border border-border">
+      ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
+      ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
+      ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
+      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Send message</button>
+    </form>
+  `;
+}
+
+// The page action runs on a non-GET submission to this URL (the no-JS write
+// path). Validate, then return a failure (re-renders at 422 with fieldErrors +
+// values) or a success with a same-site `redirect` (a 303 PRG to the confirmation).
+export async function action({ formData }: { formData: FormData }): Promise<Result> {
+  const name = String(formData.get('name') ?? '').trim();
+  const email = String(formData.get('email') ?? '').trim();
+  const message = String(formData.get('message') ?? '').trim();
+  const fieldErrors: Record<string, string> = {};
+  if (!name) fieldErrors.name = 'Your name is required.';
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) fieldErrors.email = 'A valid email is required.';
+  if (message.length < 5) fieldErrors.message = 'Message must be at least 5 characters.';
+  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values: { name, email, message } };
+  // A real app would persist / email here. We just confirm.
+  return { success: true, redirect: '/features/forms?sent=1' };
+}
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 6759eab1b..bb451a307 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -26,7 +26,7 @@ import { scaffoldApp } from '../../packages/cli/lib/create.js';
 // Single-feature demos under app/features/<name>.
 const FEATURES = [
   'routing', 'components', 'server-actions', 'optimistic-ui',
-  'async-render', 'directives', 'route-handler',
+  'async-render', 'directives', 'route-handler', 'forms',
 ];
 // Whole example apps under app/examples/<name>.
 const EXAMPLE_APPS = ['todo'];

From 65d7b867f81df0da042511f0eef3ef2ba4aa8bdf Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:03:14 +0530
Subject: [PATCH 24/53] fix(cli): stop the accent flipping to neutral on
 back-navigation

Root cause was a design-token collision, not a framework bug (other webjs
apps do not hit it). The @webjsdev/ui theme defines a neutral `--accent`
(its shadcn-compatible convention) and the scaffold defined a brand
`--accent` (orange); both fed `--color-accent: var(--accent)`. On a
client-router back-nav the Tailwind runtime recompiles and re-injects the
ui-theme's grey `--accent` last, so the brand orange lost permanently.

Rename the scaffold's brand token to `--brand` and point
`--color-accent: var(--brand)` in the scaffold's own @theme (emitted after
the ui theme's, so it wins deterministically). The ui kit keeps its
`--accent` for its components; no more collision. Verified in a browser:
the accent stays orange across back-nav AND a forced runtime recompile.

Also route the navbar brand through the title-cased displayName ("my-app"
-> "My App"), and correct the internal wording from "shadcn" to
"@webjsdev/ui" (the kit mirrors shadcn conventions but is webjs's own).
---
 packages/cli/lib/create.js | 65 +++++++++++++++++++-------------------
 1 file changed, 33 insertions(+), 32 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 6445863e0..2b9de26eb 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -212,7 +212,7 @@ async function writeUiBootstrap(appDir) {
 }
 
 /**
- * Read the shadcn theme CSS so we can inline it into the layout's
+ * Read the @webjsdev/ui theme CSS so we can inline it into the layout's
  * `<style type="text/tailwindcss">` block. The Tailwind browser runtime
  * picks up inline `<style type="text/tailwindcss">` content, so the theme
  * tokens (`--color-primary`, `--color-card`, …) the registry components
@@ -227,7 +227,7 @@ async function readThemeCss() {
 
 /**
  * Fail loudly when the @webjsdev/ui registry is not on disk. The scaffold
- * reads component sources, the cn() helper, and the shadcn theme from
+ * reads component sources, the cn() helper, and the @webjsdev/ui theme from
  * UI_REGISTRY_ROOT and weaves them into a generated app/page.ts that
  * imports `components/ui/button.ts`. If the registry is missing, the
  * generated app boots to ERR_MODULE_NOT_FOUND on first request, which is
@@ -417,9 +417,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // tsserver plugin can't provide); tsserver dedupes by name, so loading
       // it both ways is a no-op. Standalone, no Lit dependency. Editor-only.
       '@webjsdev/intellisense': 'latest',
-      // NOTE: @webjsdev/ui is intentionally NOT pinned. The UI kit is
-      // shadcn-style copy-in: `webjs ui add <name>` copies component source
-      // into components/ui/ (they import @webjsdev/core, not the kit), and the
+      // NOTE: @webjsdev/ui is intentionally NOT pinned. The UI kit uses a
+      // copy-in model (shadcn-compatible conventions): `webjs ui add <name>`
+      // copies component source into components/ui/ (they import
+      // @webjsdev/core, not the kit), and the
       // CLI resolves @webjsdev/ui from its own install.
     },
     // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
@@ -950,7 +951,7 @@ export type ActionResult<T> =
 
     // Pre-initialise @webjsdev/ui so the scaffold boots ready for
     // `webjs ui add <name>`: writes components.json + lib/utils/cn.ts +
-    // styles/globals.css (the shadcn theme).
+    // styles/globals.css (the @webjsdev/ui theme).
     await writeUiBootstrap(appDir);
 
     // Copy the standard ui-* component kit the scaffold's example pages
@@ -968,13 +969,13 @@ export type ActionResult<T> =
     // use. See CONVENTIONS.md "prune what the app does not use".
     if (isFullStack) await copyGallery(appDir);
 
-    // The shadcn theme tokens (`--color-primary`, `--color-card`, …) the
+    // The @webjsdev/ui theme tokens (`--color-primary`, `--color-card`, …) the
     // ui-* components consume. We read the registry's themes/index.css at
     // create time and inline it into the layout's
     // `<style type="text/tailwindcss">` block so the Tailwind browser
     // runtime picks it up. Same content also lives at styles/globals.css for
     // `webjsui` tooling.
-    const SHADCN_THEME = (await readThemeCss())
+    const UI_THEME = (await readThemeCss())
       // Escape backticks + ${} so the CSS survives interpolation into the
       // layout's template literal below.
       .replace(/\\/g, '\\\\')
@@ -1029,7 +1030,7 @@ export default function RootLayout({ children }: { children: unknown }) {
             var el = document.documentElement;
             if (t === 'light' || t === 'dark') el.dataset.theme = t;
             else delete el.dataset.theme;
-            // Keep shadcn's .dark class in sync with the effective theme so the
+            // Keep the .dark class the @webjsdev/ui kit uses in sync with the effective theme so the
             // copied ui-* components (button, card, etc.) follow light/dark too.
             // Dark is the default unless the OS prefers light or 'light' is set.
             var dark = t === 'dark' || (t !== 'light' && !mq.matches);
@@ -1069,7 +1070,7 @@ export default function RootLayout({ children }: { children: unknown }) {
       Edit base palette via the :root / .dark blocks below.
     -->
     <style type="text/tailwindcss">
-${SHADCN_THEME}
+${UI_THEME}
     </style>
     <style type="text/tailwindcss">
       @theme {
@@ -1081,10 +1082,10 @@ ${SHADCN_THEME}
         --color-bg-subtle:     var(--bg-subtle);
         --color-border:        var(--border);
         --color-border-strong: var(--border-strong);
-        --color-accent:        var(--accent);
-        --color-accent-hover:  var(--accent-hover);
-        --color-accent-fg:     var(--accent-fg);
-        --color-accent-tint:   var(--accent-tint);
+        --color-accent:        var(--brand);
+        --color-accent-hover:  var(--brand-hover);
+        --color-accent-fg:     var(--brand-fg);
+        --color-accent-tint:   var(--brand-tint);
         --font-sans:  var(--font-sans);
         --font-serif: var(--font-serif);
         --font-mono:  var(--font-mono);
@@ -1109,11 +1110,11 @@ ${SHADCN_THEME}
         --border:        oklch(0.26 0.012 55 / 0.9);
         --border-strong: oklch(0.38 0.012 55 / 0.9);
         /* Accent matches the webjs website (warm orange, hue 52). */
-        --accent:        oklch(0.7 0.16 52);
-        --accent-hover:  oklch(0.75 0.16 52);
-        --accent-fg:     oklch(0.17 0.02 52);
-        --accent-live:   oklch(0.63 0.17 50);
-        --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
+        --brand:        oklch(0.7 0.16 52);
+        --brand-hover:  oklch(0.75 0.16 52);
+        --brand-fg:     oklch(0.17 0.02 52);
+        --brand-live:   oklch(0.63 0.17 50);
+        --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
         --font-sans:   -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         --font-serif:  ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:   ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
@@ -1127,11 +1128,11 @@ ${SHADCN_THEME}
         --bg-subtle:     oklch(0.96 0.008 80);
         --border:        oklch(0.88 0.01 75 / 0.95);
         --border-strong: oklch(0.78 0.01 75 / 0.95);
-        --accent:        oklch(0.54 0.16 52);
-        --accent-hover:  oklch(0.5 0.16 52);
-        --accent-fg:     oklch(1 0 0);
-        --accent-live:   oklch(0.63 0.17 50);
-        --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
+        --brand:        oklch(0.54 0.16 52);
+        --brand-hover:  oklch(0.5 0.16 52);
+        --brand-fg:     oklch(1 0 0);
+        --brand-live:   oklch(0.63 0.17 50);
+        --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
       }
       @media (prefers-color-scheme: light) {
         :root:not([data-theme='dark']) {
@@ -1143,11 +1144,11 @@ ${SHADCN_THEME}
           --bg-subtle:     oklch(0.96 0.008 80);
           --border:        oklch(0.88 0.01 75 / 0.95);
           --border-strong: oklch(0.78 0.01 75 / 0.95);
-          --accent:        oklch(0.54 0.16 52);
-          --accent-hover:  oklch(0.5 0.16 52);
-          --accent-fg:     oklch(1 0 0);
-          --accent-live:   oklch(0.63 0.17 50);
-          --accent-tint:   color-mix(in oklch, var(--accent-live) 14%, transparent);
+          --brand:        oklch(0.54 0.16 52);
+          --brand-hover:  oklch(0.5 0.16 52);
+          --brand-fg:     oklch(1 0 0);
+          --brand-live:   oklch(0.63 0.17 50);
+          --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
         }
       }
       /* Body + pseudo-elements utility classes can't reach. */
@@ -1160,12 +1161,12 @@ ${SHADCN_THEME}
         font: 16px/1.65 var(--font-sans);
         -webkit-font-smoothing: antialiased;
       }
-      ::selection { background: var(--accent-tint); color: var(--fg); }
+      ::selection { background: var(--brand-tint); color: var(--fg); }
     </style>
 
     <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--bg)_75%,transparent)] backdrop-blur-[18px]">
       <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-fg font-semibold text-[15px] leading-none tracking-tight">
-        <span>${name}</span>
+        <span>${displayName}</span>
       </a>
       <nav class="flex gap-4 items-center">
         <!-- Example nav. Replace with the real navigation for your app. -->
@@ -1315,7 +1316,7 @@ export class ThemeToggle extends WebComponent {
     const el = document.documentElement;
     if (next === 'system') delete el.dataset.theme;
     else el.dataset.theme = next;
-    // Keep shadcn's .dark class in sync so the ui-* components follow the theme.
+    // Keep the .dark class the @webjsdev/ui kit uses in sync so the ui-* components follow the theme.
     const dark = next === 'dark'
       || (next === 'system' && !window.matchMedia('(prefers-color-scheme: light)').matches);
     el.classList.toggle('dark', dark);

From e3e4fbe5f17d29eaa7b5d79bcd4a98ec48140932 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:40:54 +0530
Subject: [PATCH 25/53] refactor(cli): use one canonical shadcn token system
 (no invented vocab)

The scaffold layered a parallel, invented token vocabulary (--fg, --bg,
--brand, text-fg, bg-bg-elev, ...) on top of the @webjsdev/ui theme, which
both collided (the accent flip) and diverged from the shadcn conventions
@webjsdev/ui promises parity with (and that AI agents are trained on).

Adopt the canonical shadcn v4 pattern as the single source of truth:
- Set the @webjsdev/ui semantic tokens' VALUES to the brand palette
  (--background/--foreground/--card/--primary/--accent/--border/...),
  overriding them in a tailwindcss-layer block emitted after the ui theme
  so they win deterministically on every runtime recompile. Dark-first,
  light via the toggle (data-theme) or OS.
- Migrate the chrome + gallery onto shadcn's utilities: text-foreground,
  text-muted-foreground, bg-card, bg-muted, bg-accent, text-accent-foreground,
  border-border, and opacity modifiers (bg-accent/10, hover:bg-accent/90,
  text-muted-foreground/70) instead of invented -tint/-hover/-subtle tokens.
- Add only genuinely-extra tokens the canonical way (--border-strong via
  @theme inline). Fonts/text-sizes/durations stay as theme tokens.

One theme now: the ui-* components AND the example chrome read the same
tokens, and `webjs ui add <name>` components inherit the brand automatically.
Verified in a browser: light + dark render correctly, and the accent stays
orange across a forced Tailwind recompile (the back-nav bug, fixed at root).
---
 packages/cli/lib/create.js                    | 182 ++++++++++--------
 .../gallery/app/features/async-render/page.ts |   2 +-
 .../gallery/app/features/components/page.ts   |   2 +-
 .../gallery/app/features/directives/page.ts   |   2 +-
 .../gallery/app/features/forms/page.ts        |  18 +-
 .../app/features/optimistic-ui/page.ts        |   2 +-
 .../app/features/route-handler/page.ts        |   2 +-
 .../gallery/app/features/routing/page.ts      |   2 +-
 .../app/features/server-actions/page.ts       |   2 +-
 .../components/components/counter-card.ts     |   8 +-
 .../directives/components/directive-demo.ts   |  10 +-
 .../optimistic-ui/components/like-button.ts   |   2 +-
 .../server-actions/components/greeter.ts      |   8 +-
 .../modules/todo/components/todo-app.ts       |  35 ++--
 14 files changed, 152 insertions(+), 125 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 2b9de26eb..9c56c1b44 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1002,7 +1002,7 @@ import '#components/theme-toggle.ts';
  *
  * Light DOM + Tailwind by default. Design tokens live in :root and are
  * mapped into the Tailwind palette via @theme, so classes like
- * text-fg, bg-bg-elev, font-serif, duration-fast, text-display all work.
+ * text-foreground, bg-card, font-serif, duration-fast, text-display all work.
  *
  * Nav + footer links repeat the same class bundle, so they're extracted
  * into small JS helpers below. Each helper runs at SSR time inside
@@ -1010,7 +1010,7 @@ import '#components/theme-toggle.ts';
  */
 
 const navLink = (href: string, label: string) => html\`
-  <a href=\${href} class="text-fg-muted no-underline font-medium text-[13px] leading-none tracking-[0.005em] transition-colors duration-fast hover:text-fg">\${label}</a>
+  <a href=\${href} class="text-muted-foreground no-underline font-medium text-[13px] leading-none tracking-[0.005em] transition-colors duration-fast hover:text-foreground">\${label}</a>
 \`;
 
 export default function RootLayout({ children }: { children: unknown }) {
@@ -1073,19 +1073,99 @@ export default function RootLayout({ children }: { children: unknown }) {
 ${UI_THEME}
     </style>
     <style type="text/tailwindcss">
-      @theme {
-        --color-fg:            var(--fg);
-        --color-fg-muted:      var(--fg-muted);
-        --color-fg-subtle:     var(--fg-subtle);
-        --color-bg:            var(--bg);
-        --color-bg-elev:       var(--bg-elev);
-        --color-bg-subtle:     var(--bg-subtle);
-        --color-border:        var(--border);
+      /* ONE theme, canonical shadcn-style tokens. The @webjsdev/ui theme above
+         provides the token STRUCTURE and the @theme inline mappings that generate
+         bg-background, text-foreground, bg-card, bg-primary, bg-accent,
+         text-muted-foreground, border-border, ring-ring, and the rest. Here we
+         set those tokens' VALUES to this app's brand palette, so the ui-*
+         components AND the example chrome read ONE source of truth. Any component
+         added later with webjs ui add <name> inherits it automatically. This
+         block is emitted after the ui theme, so these values win on every Tailwind
+         recompile. Dark-first, with light via the theme toggle (data-theme) or the
+         OS. Edit the palette here. Add a new design token the canonical way, a
+         --x variable below plus a --color-x: var(--x) line in the @theme inline
+         block, then use it as bg-x / text-x. Reach for opacity modifiers
+         (bg-accent/10, hover:bg-accent/90, text-muted-foreground/70) before
+         inventing a new token. */
+      :root {
+        --font-sans:  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
+        --font-mono:  ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+        --header-h: 56px;
+      }
+      /* dark (the default, and the explicit .dark the toggle sets) */
+      :root, .dark {
+        color-scheme: dark;
+        --background: oklch(0.14 0.01 55);
+        --foreground: oklch(0.96 0.015 60);
+        --card: oklch(0.18 0.01 55);
+        --card-foreground: oklch(0.96 0.015 60);
+        --popover: oklch(0.18 0.01 55);
+        --popover-foreground: oklch(0.96 0.015 60);
+        --primary: oklch(0.922 0 0);
+        --primary-foreground: oklch(0.205 0 0);
+        --secondary: oklch(0.22 0.01 55);
+        --secondary-foreground: oklch(0.96 0.015 60);
+        --muted: oklch(0.16 0.01 55);
+        --muted-foreground: oklch(0.72 0.02 60);
+        --accent: oklch(0.7 0.16 52);
+        --accent-foreground: oklch(0.17 0.02 52);
+        --border: oklch(0.26 0.012 55 / 0.9);
+        --border-strong: oklch(0.38 0.012 55 / 0.9);
+        --input: oklch(0.26 0.012 55 / 0.9);
+        --ring: oklch(0.7 0.16 52);
+      }
+      /* light (explicit via the toggle) */
+      :root[data-theme='light'] {
+        color-scheme: light;
+        --background: oklch(0.985 0.008 80);
+        --foreground: oklch(0.18 0.015 60);
+        --card: oklch(1 0 0);
+        --card-foreground: oklch(0.18 0.015 60);
+        --popover: oklch(1 0 0);
+        --popover-foreground: oklch(0.18 0.015 60);
+        --primary: oklch(0.205 0 0);
+        --primary-foreground: oklch(0.985 0 0);
+        --secondary: oklch(0.96 0.008 80);
+        --secondary-foreground: oklch(0.18 0.015 60);
+        --muted: oklch(0.96 0.008 80);
+        --muted-foreground: oklch(0.42 0.02 65);
+        --accent: oklch(0.54 0.16 52);
+        --accent-foreground: oklch(1 0 0);
+        --border: oklch(0.88 0.01 75 / 0.95);
+        --border-strong: oklch(0.78 0.01 75 / 0.95);
+        --input: oklch(0.88 0.01 75 / 0.95);
+        --ring: oklch(0.54 0.16 52);
+      }
+      /* light (OS preference, when the user has made no explicit choice) */
+      @media (prefers-color-scheme: light) {
+        :root:not(.dark):not([data-theme='dark']) {
+          color-scheme: light;
+          --background: oklch(0.985 0.008 80);
+          --foreground: oklch(0.18 0.015 60);
+          --card: oklch(1 0 0);
+          --card-foreground: oklch(0.18 0.015 60);
+          --popover: oklch(1 0 0);
+          --popover-foreground: oklch(0.18 0.015 60);
+          --primary: oklch(0.205 0 0);
+          --primary-foreground: oklch(0.985 0 0);
+          --secondary: oklch(0.96 0.008 80);
+          --secondary-foreground: oklch(0.18 0.015 60);
+          --muted: oklch(0.96 0.008 80);
+          --muted-foreground: oklch(0.42 0.02 65);
+          --accent: oklch(0.54 0.16 52);
+          --accent-foreground: oklch(1 0 0);
+          --border: oklch(0.88 0.01 75 / 0.95);
+          --border-strong: oklch(0.78 0.01 75 / 0.95);
+          --input: oklch(0.88 0.01 75 / 0.95);
+          --ring: oklch(0.54 0.16 52);
+        }
+      }
+      @theme inline {
+        /* Only tokens the @webjsdev/ui theme does not already map live here. It
+           already maps --color-background/foreground/card/primary/secondary/
+           muted/accent/border/input/ring/destructive. */
         --color-border-strong: var(--border-strong);
-        --color-accent:        var(--brand);
-        --color-accent-hover:  var(--brand-hover);
-        --color-accent-fg:     var(--brand-fg);
-        --color-accent-tint:   var(--brand-tint);
         --font-sans:  var(--font-sans);
         --font-serif: var(--font-serif);
         --font-mono:  var(--font-mono);
@@ -1098,74 +1178,20 @@ ${UI_THEME}
       }
     </style>
     <style>
-      :root {
-        color-scheme: light dark;
-        /* ---------- dark (default) ---------- */
-        --fg:            oklch(0.96 0.015 60);
-        --fg-muted:      oklch(0.72 0.02 60);
-        --fg-subtle:     oklch(0.55 0.02 60);
-        --bg:            oklch(0.14 0.01 55);
-        --bg-elev:       oklch(0.18 0.01 55);
-        --bg-subtle:     oklch(0.16 0.01 55);
-        --border:        oklch(0.26 0.012 55 / 0.9);
-        --border-strong: oklch(0.38 0.012 55 / 0.9);
-        /* Accent matches the webjs website (warm orange, hue 52). */
-        --brand:        oklch(0.7 0.16 52);
-        --brand-hover:  oklch(0.75 0.16 52);
-        --brand-fg:     oklch(0.17 0.02 52);
-        --brand-live:   oklch(0.63 0.17 50);
-        --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
-        --font-sans:   -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-        --font-serif:  ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
-        --font-mono:   ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-      }
-      :root[data-theme='light'] {
-        --fg:            oklch(0.18 0.015 60);
-        --fg-muted:      oklch(0.42 0.02 65);
-        --fg-subtle:     oklch(0.62 0.015 70);
-        --bg:            oklch(0.985 0.008 80);
-        --bg-elev:       oklch(1 0 0);
-        --bg-subtle:     oklch(0.96 0.008 80);
-        --border:        oklch(0.88 0.01 75 / 0.95);
-        --border-strong: oklch(0.78 0.01 75 / 0.95);
-        --brand:        oklch(0.54 0.16 52);
-        --brand-hover:  oklch(0.5 0.16 52);
-        --brand-fg:     oklch(1 0 0);
-        --brand-live:   oklch(0.63 0.17 50);
-        --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
-      }
-      @media (prefers-color-scheme: light) {
-        :root:not([data-theme='dark']) {
-          --fg:            oklch(0.18 0.015 60);
-          --fg-muted:      oklch(0.42 0.02 65);
-          --fg-subtle:     oklch(0.62 0.015 70);
-          --bg:            oklch(0.985 0.008 80);
-          --bg-elev:       oklch(1 0 0);
-          --bg-subtle:     oklch(0.96 0.008 80);
-          --border:        oklch(0.88 0.01 75 / 0.95);
-          --border-strong: oklch(0.78 0.01 75 / 0.95);
-          --brand:        oklch(0.54 0.16 52);
-          --brand-hover:  oklch(0.5 0.16 52);
-          --brand-fg:     oklch(1 0 0);
-          --brand-live:   oklch(0.63 0.17 50);
-          --brand-tint:   color-mix(in oklch, var(--brand-live) 14%, transparent);
-        }
-      }
-      /* Body + pseudo-elements utility classes can't reach. */
+      /* Base styles utility classes can't reach. */
       html, body { margin: 0; }
-      :root { --header-h: 56px; } /* fixed-header offset, kept exact by the script above */
       body {
         padding-top: var(--header-h);
-        background: var(--bg);
-        color: var(--fg);
+        background: var(--background);
+        color: var(--foreground);
         font: 16px/1.65 var(--font-sans);
         -webkit-font-smoothing: antialiased;
       }
-      ::selection { background: var(--brand-tint); color: var(--fg); }
+      ::selection { background: color-mix(in oklch, var(--accent) 22%, transparent); color: var(--foreground); }
     </style>
 
-    <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--bg)_75%,transparent)] backdrop-blur-[18px]">
-      <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-fg font-semibold text-[15px] leading-none tracking-tight">
+    <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--background)_75%,transparent)] backdrop-blur-[18px]">
+      <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-foreground font-semibold text-[15px] leading-none tracking-tight">
         <span>${displayName}</span>
       </a>
       <nav class="flex gap-4 items-center">
@@ -1239,7 +1265,7 @@ export default function Home() {
     <section class="mb-14">
       \${rubric('welcome')}
       \${displayH1(html\`Hello from <span class="text-accent italic">${displayName}</span>.\`)}
-      <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
+      <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for
         context, then replace this page with your own. See
@@ -1253,7 +1279,7 @@ export default function Home() {
 
     <section class="mb-12">
       <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Features</h2>
-      <p class="text-fg-muted text-sm m-0 mb-5">
+      <p class="text-muted-foreground text-sm m-0 mb-5">
         One webjs concept each, under <code class="font-mono text-[0.9em]">app/features/</code>
         with logic in <code class="font-mono text-[0.9em]">modules/</code>. Delete the ones you do not need.
       </p>
@@ -1264,7 +1290,7 @@ export default function Home() {
 
     <section>
       <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Example apps</h2>
-      <p class="text-fg-muted text-sm m-0 mb-5">
+      <p class="text-muted-foreground text-sm m-0 mb-5">
         Whole apps that compose several features, under <code class="font-mono text-[0.9em]">app/examples/</code>.
       </p>
       <div class="grid gap-4 sm:grid-cols-2">
@@ -1328,7 +1354,7 @@ export class ThemeToggle extends WebComponent {
     const icon = t === 'light' ? ICONS.sun : t === 'dark' ? ICONS.moon : ICONS.system;
     return html\`
       <button
-        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-bg-elev text-fg-muted cursor-pointer transition-all duration-150 hover:text-fg hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-accent focus-visible:ring-[3px] focus-visible:ring-accent-tint"
+        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-card text-muted-foreground cursor-pointer transition-all duration-150 hover:text-foreground hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-accent focus-visible:ring-[3px] focus-visible:ring-accent-tint"
         @click=\${() => this.cycle()}
         aria-label="Cycle theme (currently \${label})"
         title="Theme: \${label.toLowerCase()}"
diff --git a/packages/cli/templates/gallery/app/features/async-render/page.ts b/packages/cli/templates/gallery/app/features/async-render/page.ts
index f7ec56db8..98991a787 100644
--- a/packages/cli/templates/gallery/app/features/async-render/page.ts
+++ b/packages/cli/templates/gallery/app/features/async-render/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Async render (server data in first p
 export default function AsyncRenderExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Async render</h1>
-    <p class="text-fg-muted mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
+    <p class="text-muted-foreground mb-4">A component's <code>async render()</code> awaits server data. SSR blocks, so the resolved value is in the first paint (no fallback, readable with JS off).</p>
     <server-clock></server-clock>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/components/page.ts b/packages/cli/templates/gallery/app/features/components/page.ts
index 8082e33da..4968c89f1 100644
--- a/packages/cli/templates/gallery/app/features/components/page.ts
+++ b/packages/cli/templates/gallery/app/features/components/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Components (signals + slots) | featu
 export default function ComponentsExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Components</h1>
-    <p class="text-fg-muted mb-4">The WebComponent factory, a reactive prop, an instance signal, and a slot.</p>
+    <p class="text-muted-foreground mb-4">The WebComponent factory, a reactive prop, an instance signal, and a slot.</p>
     <counter-card label="Taps"><strong>A slotted title</strong></counter-card>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/directives/page.ts b/packages/cli/templates/gallery/app/features/directives/page.ts
index 06a6b134f..399b0f155 100644
--- a/packages/cli/templates/gallery/app/features/directives/page.ts
+++ b/packages/cli/templates/gallery/app/features/directives/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Directives (repeat + watch) | featur
 export default function DirectivesExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Directives</h1>
-    <p class="text-fg-muted mb-4">The lit-html directive set: <code>repeat</code> keys a reordering list so nodes are reused, and <code>watch(signal)</code> swaps one node without a full re-render.</p>
+    <p class="text-muted-foreground mb-4">The lit-html directive set: <code>repeat</code> keys a reordering list so nodes are reused, and <code>watch(signal)</code> swaps one node without a full re-render.</p>
     <directive-demo></directive-demo>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index a11510eee..b6a5a7f97 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -20,24 +20,24 @@ interface Result {
 
 const field = (label: string, name: string, input: unknown, error?: string) => html`
   <div class="grid gap-1.5">
-    <label for=${name} class="text-[13px] font-medium text-fg-muted">${label}</label>
+    <label for=${name} class="text-[13px] font-medium text-muted-foreground">${label}</label>
     ${input}
     ${error ? html`<p class="m-0 text-[12.5px] text-destructive">${error}</p>` : ''}
   </div>
 `;
 
-const inputCls = 'w-full bg-bg border border-border rounded-xl px-3 py-2 text-[15px] text-fg outline-none transition-colors focus:border-accent placeholder:text-fg-subtle';
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-accent placeholder:text-muted-foreground/70';
 
 export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
   if (searchParams.sent) {
     return html`
       <h1 class="text-h2 font-bold mb-4">Forms</h1>
-      <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-bg-elev border border-border text-center">
-        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-accent-tint text-accent">
+      <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-card border border-border text-center">
+        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
           <svg viewBox="0 0 24 24" class="w-6 h-6 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
         </span>
-        <p class="m-0 text-lg font-semibold text-fg">Message sent</p>
-        <p class="m-0 text-sm text-fg-muted">Thanks, we got it. <a class="text-accent" href="/features/forms">Send another</a>.</p>
+        <p class="m-0 text-lg font-semibold text-foreground">Message sent</p>
+        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-accent" href="/features/forms">Send another</a>.</p>
       </div>
     `;
   }
@@ -45,12 +45,12 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
   const v = actionData?.values ?? {};
   return html`
     <h1 class="text-h2 font-bold mb-2">Forms</h1>
-    <p class="text-fg-muted mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
-    <form method="post" action="" class="max-w-[460px] grid gap-4 p-5 rounded-2xl bg-bg-elev border border-border">
+    <p class="text-muted-foreground mb-5 max-w-[460px]">A real <code>&lt;form&gt;</code> posting to this page's <code>action</code>. It works with JS off; validation errors come back on <code>actionData</code>.</p>
+    <form method="post" action="" class="max-w-[460px] grid gap-4 p-5 rounded-2xl bg-card border border-border">
       ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
       ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
       ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
-      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Send message</button>
+      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send message</button>
     </form>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
index f747d250b..fbc6781d4 100644
--- a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
+++ b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | fe
 export default function OptimisticUiFeature() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Optimistic UI</h1>
-    <p class="text-fg-muted mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-accent" href="/examples/todo">/examples/todo</a>.</p>
+    <p class="text-muted-foreground mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-accent" href="/examples/todo">/examples/todo</a>.</p>
     <like-button></like-button>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
index bdc92162e..55c1b13e4 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/page.ts
@@ -7,7 +7,7 @@ export const metadata: Metadata = { title: 'Route handlers (route.ts) | features
 export default function RouteHandlerExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
-    <p class="text-fg-muted mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
+    <p class="text-muted-foreground mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
     <p><a class="text-accent" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 1506d3eca..e8981330c 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -10,7 +10,7 @@ export const metadata: Metadata = { title: 'Routing (dynamic params) | features'
 export default function RoutingExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Routing</h1>
-    <p class="text-fg-muted mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
+    <p class="text-muted-foreground mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
     <ul class="list-disc pl-5">
       <li><a class="text-accent" href="/features/routing/42">/features/routing/42</a></li>
       <li><a class="text-accent" href="/features/routing/hello">/features/routing/hello</a></li>
diff --git a/packages/cli/templates/gallery/app/features/server-actions/page.ts b/packages/cli/templates/gallery/app/features/server-actions/page.ts
index 30189bccc..b873b14c2 100644
--- a/packages/cli/templates/gallery/app/features/server-actions/page.ts
+++ b/packages/cli/templates/gallery/app/features/server-actions/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Server actions (.server vs use serve
 export default function ServerActionsExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Server actions</h1>
-    <p class="text-fg-muted mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
+    <p class="text-muted-foreground mb-4">A 'use server' action is RPC-callable from the client; a plain .server.ts is a server-only utility you never import into a component.</p>
     <server-greeter></server-greeter>
   `;
 }
diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index 99a317c96..34d313e9f 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -20,14 +20,14 @@ export class CounterCard extends WebComponent({
 
   render() {
     return html`
-      <div class="grid gap-4 p-5 rounded-2xl bg-bg-elev border border-border max-w-[320px]">
+      <div class="grid gap-4 p-5 rounded-2xl bg-card border border-border max-w-[320px]">
         <slot></slot>
         <div class="flex items-baseline gap-2">
-          <span class="text-[2.5rem] font-bold tabular-nums leading-none text-fg">${this.count.get()}</span>
-          <span class="text-sm text-fg-subtle">${this.label}</span>
+          <span class="text-[2.5rem] font-bold tabular-nums leading-none text-foreground">${this.count.get()}</span>
+          <span class="text-sm text-muted-foreground/70">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="w-fit px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Increment</button>
+          class="w-fit px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Increment</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index 13221dfc6..d8aa5f606 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -31,21 +31,21 @@ export class DirectiveDemo extends WebComponent {
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex gap-2">
           <button @click=${() => this.reverse()}
-            class="px-3.5 py-1.5 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Reverse</button>
+            class="px-3.5 py-1.5 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Reverse</button>
           <button @click=${() => this.add()}
-            class="px-3.5 py-1.5 rounded-xl bg-bg-elev border border-border text-fg font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
+            class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
         </div>
         <!-- repeat keyed by item.id: reversing reuses the existing <li> nodes. -->
         <ul class="grid gap-2 list-none m-0 p-0">
           ${repeat(this.items.get(), (it: Item) => it.id, (it: Item) => html`
-            <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-bg-elev border border-border text-[15px] text-fg">
-              <span class="text-fg-subtle tabular-nums text-[13px]">#${it.id}</span>${it.label}
+            <li class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">
+              <span class="text-muted-foreground/70 tabular-nums text-[13px]">#${it.id}</span>${it.label}
             </li>
           `)}
         </ul>
         <!-- watch(signal) swaps only this node when ticks changes. -->
         <button @click=${() => this.ticks.set(this.ticks.get() + 1)}
-          class="w-fit text-sm text-fg-muted cursor-pointer transition-colors hover:text-fg underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
+          class="w-fit text-sm text-muted-foreground cursor-pointer transition-colors hover:text-foreground underline decoration-dotted underline-offset-4">ticks: ${watch(this.ticks)}</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
index 9f033c01a..70291d913 100644
--- a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -25,7 +25,7 @@ export class LikeButton extends WebComponent {
     const liked = this.liked.get();
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-accent text-accent-fg border-accent' : 'bg-bg-elev text-fg border-border hover:border-border-strong'}">
+        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-accent text-accent-foreground border-accent' : 'bg-card text-foreground border-border hover:border-border-strong'}">
         <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index ba9445576..1d592c9f2 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -16,13 +16,13 @@ export class Greeter extends WebComponent {
     return html`
       <div class="grid gap-3 max-w-[420px]">
         <form @submit=${(e: SubmitEvent) => this.run(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-bg-elev border border-border">
+          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border">
           <input name="name" placeholder="your name" autocomplete="off"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-fg text-[15px] placeholder:text-fg-subtle py-1.5" />
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
           <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Greet</button>
+            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Greet</button>
         </form>
-        ${this.msg.get() ? html`<p class="m-0 font-semibold text-fg">${this.msg.get()}</p>` : ''}
+        ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 1abe33172..0cf0ed9a8 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -4,10 +4,11 @@
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
 //
-// Styling is crafted Tailwind on the app's design tokens (bg-elev, accent,
-// fg-muted, border-strong, ...), the same tokens the layout defines. Prefer this
-// or the @webjsdev/ui class helpers over ad-hoc colors, so the whole app stays
-// visually coherent.
+// Styling uses the shadcn-standard design tokens the @webjsdev/ui theme defines
+// (bg-card, text-foreground, bg-accent, text-muted-foreground, border-border,
+// ...), so the whole app (this component AND any `webjs ui add` component) shares
+// one coherent theme. Prefer these tokens (and opacity modifiers like
+// bg-accent/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
@@ -76,16 +77,16 @@ export class TodoApp extends WebComponent({
         <!-- Header: a title, a live done/total count, and a progress bar. -->
         <header class="grid gap-3">
           <div class="flex items-center gap-3">
-            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-accent-tint text-accent shrink-0">
+            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-accent/15 text-accent shrink-0">
               <svg viewBox="0 0 24 24" class="w-5 h-5 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
             </span>
             <div class="grid gap-0.5">
-              <h2 class="m-0 text-[1.4rem] font-bold tracking-[-0.02em] leading-none text-fg">Tasks</h2>
-              <p class="m-0 text-[13px] text-fg-subtle leading-none">${done} of ${list.length} done</p>
+              <h2 class="m-0 text-[1.4rem] font-bold tracking-[-0.02em] leading-none text-foreground">Tasks</h2>
+              <p class="m-0 text-[13px] text-muted-foreground/70 leading-none">${done} of ${list.length} done</p>
             </div>
-            <span class="ml-auto text-[13px] font-semibold tabular-nums text-fg-muted">${pct}%</span>
+            <span class="ml-auto text-[13px] font-semibold tabular-nums text-muted-foreground">${pct}%</span>
           </div>
-          <div class="h-1.5 rounded-full bg-bg-subtle overflow-hidden">
+          <div class="h-1.5 rounded-full bg-muted overflow-hidden">
             <div class="h-full rounded-full bg-accent transition-[width] duration-300" style="width:${pct}%"></div>
           </div>
         </header>
@@ -93,19 +94,19 @@ export class TodoApp extends WebComponent({
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
              with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-bg-elev border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--fg)_5%,transparent)]">
+          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-fg text-[15px] placeholder:text-fg-subtle py-1.5" />
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
           <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-fg font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent-hover active:scale-[0.97]">Add</button>
+            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">
           ${list.length ? list.map((todo) => html`
             <li>
               <form method="post" action=""
-                class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-bg-elev border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
+                class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-card border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS
                      @click intercepts for the optimistic toggle. The check is centered
@@ -114,22 +115,22 @@ export class TodoApp extends WebComponent({
                   aria-pressed=${todo.completed ? 'true' : 'false'}
                   aria-label=${todo.completed ? 'Mark as not done' : 'Mark as done'}
                   @click=${(e: Event) => this.toggle(e, todo)}
-                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-accent border-accent text-accent-fg' : 'bg-transparent border-border-strong text-transparent hover:border-accent'}">
+                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-accent border-accent text-accent-foreground' : 'bg-transparent border-border-strong text-transparent hover:border-accent'}">
                   <svg viewBox="0 0 24 24" class="w-3 h-3 stroke-current fill-none" style="stroke-width:3.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
                 </button>
                 <!-- The title is a <label for> the toggle: clicking the text toggles
                      the task (works on JS and no-JS paths, and screen readers). -->
-                <label for="t-${todo.id}" class="flex-1 min-w-0 text-[15px] leading-snug break-words cursor-pointer select-none ${todo.completed ? 'line-through text-fg-subtle' : 'text-fg'}">${todo.title}</label>
+                <label for="t-${todo.id}" class="flex-1 min-w-0 text-[15px] leading-snug break-words cursor-pointer select-none ${todo.completed ? 'line-through text-muted-foreground/70' : 'text-foreground'}">${todo.title}</label>
                 <!-- Delete: a proper icon button, revealed on row hover / focus. -->
                 <button type="submit" name="intent" value="delete" aria-label="Delete task"
                   @click=${(e: Event) => this.removeTodo(e, todo)}
-                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-fg-subtle cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
+                  class="shrink-0 grid place-items-center w-7 h-7 rounded-lg border-0 bg-transparent text-muted-foreground/70 cursor-pointer opacity-0 group-hover:opacity-100 focus:opacity-100 transition-all hover:text-destructive hover:bg-[color-mix(in_oklch,var(--color-destructive)_12%,transparent)]">
                   <svg viewBox="0 0 24 24" class="w-4 h-4 stroke-current fill-none" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M18 6 6 18M6 6l12 12"/></svg>
                 </button>
               </form>
             </li>
           `) : html`
-            <li class="text-center text-fg-subtle text-sm py-14 border border-dashed border-border rounded-2xl">No tasks yet. Add your first one above.</li>
+            <li class="text-center text-muted-foreground/70 text-sm py-14 border border-dashed border-border rounded-2xl">No tasks yet. Add your first one above.</li>
           `}
         </ul>
       </section>

From da199148b66a1cb4979626f4bdd79b5fde553bb7 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:44:42 +0530
Subject: [PATCH 26/53] fix: correct the docs domain to webjs.dev (we own .dev,
 not .com)

Every reference pointed at docs.webjs.com, an unowned domain. Rewrite to
docs.webjs.dev across the scaffold templates, the cli banner/help, the
root docs, README, docs site, examples, agent-docs, and the doc-sync skill.
---
 .agents/skills/webjs-doc-sync/SKILL.md        |   2 +-
 .claude/skills/webjs-doc-sync/SKILL.md        |   2 +-
 AGENTS.md                                     |   4 ++--
 README.md                                     |   2 +-
 agent-docs/advanced.md                        |   2 +-
 agent-docs/components.md                      |   2 +-
 docs/app/docs/ai-first/page.ts                |   2 +-
 docs/app/docs/getting-started/page.ts         |   2 +-
 docs/lib/llms.server.ts                       | Bin 15452 -> 15452 bytes
 examples/blog/.agents/rules/workflow.md       |   2 +-
 examples/blog/.cursorrules                    |   2 +-
 examples/blog/.github/copilot-instructions.md |   2 +-
 packages/cli/bin/webjs.js                     |   2 +-
 packages/cli/lib/create.js                    |   4 ++--
 .../cli/templates/.agents/rules/workflow.md   |   2 +-
 packages/cli/templates/.cursorrules           |   2 +-
 .../templates/.github/copilot-instructions.md |   2 +-
 packages/cli/templates/AGENTS.md              |  12 ++++++------
 packages/core/src/component.js                |   2 +-
 packages/server/src/actions.js                |   2 +-
 packages/server/src/dev.js                    |   2 +-
 .../guardrails/server-file-guardrail.test.js  |   2 +-
 test/docs/doc-source-consistency.test.mjs     |   2 +-
 test/docs/llms.test.mjs                       |   2 +-
 24 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.agents/skills/webjs-doc-sync/SKILL.md b/.agents/skills/webjs-doc-sync/SKILL.md
index 19f19209b..ba3b28b63 100644
--- a/.agents/skills/webjs-doc-sync/SKILL.md
+++ b/.agents/skills/webjs-doc-sync/SKILL.md
@@ -42,7 +42,7 @@ applies, then update or consciously skip each.
 2. **`README.md`** (repo root). Update when a headline capability changes (the
    feature list, the quickstart, the runtime/template matrix).
 3. **The docs site: `docs/app/docs/<topic>/page.tsx`.** This is the
-   user-facing documentation at docs.webjs.com. Find the topic page(s) that cover
+   user-facing documentation at docs.webjs.dev. Find the topic page(s) that cover
    the area (`server-actions`, `routing`, `components`, `caching`, `configuration`,
    `client-router`, `data-fetching`, ...) and update them. `llms.txt` /
    `llms-full.txt` are generated LIVE from the doc pages (no build step), so they
diff --git a/.claude/skills/webjs-doc-sync/SKILL.md b/.claude/skills/webjs-doc-sync/SKILL.md
index 19f19209b..ba3b28b63 100644
--- a/.claude/skills/webjs-doc-sync/SKILL.md
+++ b/.claude/skills/webjs-doc-sync/SKILL.md
@@ -42,7 +42,7 @@ applies, then update or consciously skip each.
 2. **`README.md`** (repo root). Update when a headline capability changes (the
    feature list, the quickstart, the runtime/template matrix).
 3. **The docs site: `docs/app/docs/<topic>/page.tsx`.** This is the
-   user-facing documentation at docs.webjs.com. Find the topic page(s) that cover
+   user-facing documentation at docs.webjs.dev. Find the topic page(s) that cover
    the area (`server-actions`, `routing`, `components`, `caching`, `configuration`,
    `client-router`, `data-fetching`, ...) and update them. `llms.txt` /
    `llms-full.txt` are generated LIVE from the doc pages (no build step), so they
diff --git a/AGENTS.md b/AGENTS.md
index 9bdd93c50..59f8025bc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -413,7 +413,7 @@ const result = await optimistic(liked, true, () => likePost(postId));
 
 ## Invariants (for both humans and agents)
 
-> Hit one of these as a runtime error? The [Troubleshooting page](https://docs.webjs.com/docs/troubleshooting) is keyed by symptom (the throw-at-load server import, the backtick-in-template 500, the TypeScript strip failure, the SSR browser-global crash, the missing-frame swap) and maps each back to the invariant and the `webjs check` rule below.
+> Hit one of these as a runtime error? The [Troubleshooting page](https://docs.webjs.dev/docs/troubleshooting) is keyed by symptom (the throw-at-load server import, the backtick-in-template 500, the TypeScript strip failure, the SSR browser-global crash, the missing-frame swap) and maps each back to the invariant and the `webjs check` rule below.
 
 1. **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** The `.server.{js,ts}` extension is the path-level boundary (the file router refuses to serve the source); a `'use server'` directive additionally makes exports RPC-callable, else the file is a server-only utility whose browser import is a throw-at-load stub. Importing a DB driver (`pg`), `node:*`, or any server-only dep from a component or an `app/**` page / layout / loading / error / not-found file crashes the browser at module load.
 2. **Every `*.server.{js,ts}` file with `'use server'` exports must be `async` functions returning serializer-safe values.** Args and results round-trip via webjs's wire. Files without `'use server'` (server-only utilities) can export anything, including singletons.
@@ -434,7 +434,7 @@ const result = await optimistic(liked, true, () => likePost(postId));
 
 Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). The `--runtime node|bun` flag (default node, #541) is ORTHOGONAL to the template and re-flavors any of the three for Bun (`bun --bun` dev/start scripts so the SERVER runs on Bun, `bun.lock`, a pure `oven/bun:1` Dockerfile (#595; safe since cli@0.10.20's npx-free `webjs db migrate` (#570) needs no Node in the image) + bun-install CI, bun-command agent docs; the test/db/check tooling stays on Node); `bun create webjs <name>` auto-detects it. Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
 
-Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.com.
+Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.dev.
 
 ---
 
diff --git a/README.md b/README.md
index 86b50f126..a7d48b5bf 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ TypeScript with zero build step, real SSR with Declarative Shadow DOM.
 > - Auth, login/signup, protected dashboard, SaaS → **`--template saas`**
 >
 > Full rules: [`AGENTS.md` → How AI agents must scaffold](./AGENTS.md#how-ai-agents-must-scaffold).
-> Full framework docs (every API, every recipe): **https://docs.webjs.com**.
+> Full framework docs (every API, every recipe): **https://docs.webjs.dev**.
 
 ```sh
 # Get started in one command (no global install required)
diff --git a/agent-docs/advanced.md b/agent-docs/advanced.md
index c298d4144..291957d78 100644
--- a/agent-docs/advanced.md
+++ b/agent-docs/advanced.md
@@ -1246,7 +1246,7 @@ prod. A truncated stream (a server crash, a dropped connection) also throws
 rather than completing silently: a healthy stream always ends in an explicit
 terminal frame, so a missing one is an error. For a slow region you want behind a fallback on the FIRST paint, use
 `<webjs-suspense>` instead; streaming RPC is for an imperative stream consumed
-after an interaction. Full reference: the [Data fetching](https://docs.webjs.com/docs/data-fetching) page.
+after an interaction. Full reference: the [Data fetching](https://docs.webjs.dev/docs/data-fetching) page.
 
 ### Opt out per link
 
diff --git a/agent-docs/components.md b/agent-docs/components.md
index 73f51c6e9..01ce6b95c 100644
--- a/agent-docs/components.md
+++ b/agent-docs/components.md
@@ -96,7 +96,7 @@ The SSR pipeline runs the **pre-render value-deriving hooks** before `render()`:
 
 For component-local state, create an instance signal in the constructor and call `signal.set(...)` to mutate. The built-in `SignalWatcher` re-runs `render()` on the next microtask; the same lifecycle hooks fire as for reactive-property changes.
 
-See [`/docs/lifecycle`](https://docs.webjs.com/docs/lifecycle) for per-hook usage examples.
+See [`/docs/lifecycle`](https://docs.webjs.dev/docs/lifecycle) for per-hook usage examples.
 
 ## Async render: bare-await data fetch (#469)
 
diff --git a/docs/app/docs/ai-first/page.ts b/docs/app/docs/ai-first/page.ts
index ab5bff62d..f405c261f 100644
--- a/docs/app/docs/ai-first/page.ts
+++ b/docs/app/docs/ai-first/page.ts
@@ -136,7 +136,7 @@ HTTP/JSON API only, no UI                                --template api
 Auth / login / signup / SaaS                            --template saas</pre>
     <p>The scaffold is REFERENCE, not the final product. The agent's job after scaffolding is to replace the example <code>app/page.ts</code> ("Hello from …"), the example <code>User</code> model in <code>db/schema.server.ts</code>, and the example components with the app the user actually requested. The infrastructure (Drizzle wiring, test config, agent rules, route conventions) stays.</p>
 
-    <p><strong>When the scaffolded <code>AGENTS.md</code> doesn't cover what you need</strong> (an obscure directive, an auth-provider recipe, deployment specifics, edge cases), the full hosted documentation is at <a href="https://docs.webjs.com">docs.webjs.com</a>. Every API, every recipe, every example lives there. Reach for it before guessing or hand-rolling.</p>
+    <p><strong>When the scaffolded <code>AGENTS.md</code> doesn't cover what you need</strong> (an obscure directive, an auth-provider recipe, deployment specifics, edge cases), the full hosted documentation is at <a href="https://docs.webjs.dev">docs.webjs.dev</a>. Every API, every recipe, every example lives there. Reach for it before guessing or hand-rolling.</p>
 
     <h2>What an AI Agent Can Do with webjs</h2>
     <p>Given a webjs app + AGENTS.md, an AI coding assistant can:</p>
diff --git a/docs/app/docs/getting-started/page.ts b/docs/app/docs/getting-started/page.ts
index 352a9df25..271c14f4d 100644
--- a/docs/app/docs/getting-started/page.ts
+++ b/docs/app/docs/getting-started/page.ts
@@ -36,7 +36,7 @@ webjs create my-api --template api
 # SaaS starter (auth + dashboard + Drizzle User model + modules)
 webjs create my-app --template saas</pre>
 
-    <p><strong>For AI agents:</strong> only those three templates exist, and the CLI rejects any other <code>--template</code> value. Default to full-stack with Drizzle + SQLite for any product app (todo, blog, dashboard, marketplace, social, e-commerce…). Pick <code>--template api</code> only if the user explicitly asks for a backend-only API with no UI. Pick <code>--template saas</code> only if the user explicitly asks for auth / login / accounts. The scaffold is a starting point. Replace the example layout, page, and <code>User</code> model with the app the user actually asked for. Use Drizzle for any persisted data, never JSON files, in-memory arrays, or localStorage. When AGENTS.md doesn't cover what you need, the full hosted docs are at <a href="https://docs.webjs.com">docs.webjs.com</a>.</p>
+    <p><strong>For AI agents:</strong> only those three templates exist, and the CLI rejects any other <code>--template</code> value. Default to full-stack with Drizzle + SQLite for any product app (todo, blog, dashboard, marketplace, social, e-commerce…). Pick <code>--template api</code> only if the user explicitly asks for a backend-only API with no UI. Pick <code>--template saas</code> only if the user explicitly asks for auth / login / accounts. The scaffold is a starting point. Replace the example layout, page, and <code>User</code> model with the app the user actually asked for. Use Drizzle for any persisted data, never JSON files, in-memory arrays, or localStorage. When AGENTS.md doesn't cover what you need, the full hosted docs are at <a href="https://docs.webjs.dev">docs.webjs.dev</a>.</p>
 
     <p>The <code>--template api</code> scaffold generates thin route handlers that wrap typed server actions. Business logic lives in <code>modules/</code>. Routes just import and call the action/query, giving you file-based routing for URL structure plus type-safe server actions for logic.</p>
 
diff --git a/docs/lib/llms.server.ts b/docs/lib/llms.server.ts
index 1bd67fdf04a04429d592f5c0d2979d60c3b2fc88..4a3453b9f2332be29810d8a69a898699b1eb1ea8 100644
GIT binary patch
delta 16
Xcmcapai?MfD?f8eYT0HE{t#UNJ!l2`

delta 16
Xcmcapai?MfD?f8`e(q)t{t#UNJ#Yp3

diff --git a/examples/blog/.agents/rules/workflow.md b/examples/blog/.agents/rules/workflow.md
index 666a38e27..e484fd146 100644
--- a/examples/blog/.agents/rules/workflow.md
+++ b/examples/blog/.agents/rules/workflow.md
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md does not
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/examples/blog/.cursorrules b/examples/blog/.cursorrules
index f6207f99e..bf69dd129 100644
--- a/examples/blog/.cursorrules
+++ b/examples/blog/.cursorrules
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md doesn't
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/examples/blog/.github/copilot-instructions.md b/examples/blog/.github/copilot-instructions.md
index 008513023..638924c33 100644
--- a/examples/blog/.github/copilot-instructions.md
+++ b/examples/blog/.github/copilot-instructions.md
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions. When AGENTS.md doesn't cover what you need,
-the full hosted docs are at **https://docs.webjs.com**.
+the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/packages/cli/bin/webjs.js b/packages/cli/bin/webjs.js
index 05463c62a..dce29c138 100755
--- a/packages/cli/bin/webjs.js
+++ b/packages/cli/bin/webjs.js
@@ -524,7 +524,7 @@ components/schema with the actual app the user requested. Use Drizzle +
 SQLite for persistence (already wired up). Never store app data in JSON
 files.
 
-Full docs: https://docs.webjs.com`);
+Full docs: https://docs.webjs.dev`);
         process.exit(1);
       }
       const noInstall = rest.includes('--no-install');
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 9c56c1b44..0e97ee4ce 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1269,7 +1269,7 @@ export default function Home() {
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for
         context, then replace this page with your own. See
-        \${accentLink('https://docs.webjs.com', 'the docs')} for the full reference.
+        \${accentLink('https://docs.webjs.dev', 'the docs')} for the full reference.
       </p>
       <div class="flex gap-3 items-center">
         <a href="/examples/todo" class=\${buttonClass()}>Open the todo app</a>
@@ -1468,7 +1468,7 @@ For AI agents, read this before editing scaffolded files:
     the closest scaffold and adapt it.
   • Read AGENTS.md + CONVENTIONS.md in the new project before writing
     any code. They are the contract.
-  • Need more detail? Full hosted docs are at https://docs.webjs.com
+  • Need more detail? Full hosted docs are at https://docs.webjs.dev
     (every API, directive, recipe, and deployment guide).
 `);
 
diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index a0fcf512d..002b561b1 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md does not
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 9baeb73e5..8c2202713 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md doesn't
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index e2342dee2..e14441ccc 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions. When AGENTS.md doesn't cover what you need,
-the full hosted docs are at **https://docs.webjs.com**.
+the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 4cedfd44d..6eec56cfd 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -4,8 +4,8 @@ Read this before editing any file. This is a webjs app: AI-first, web-
 components-first, no build step. The framework's own full API reference
 lives at https://github.com/webjsdev/webjs/blob/main/AGENTS.md and the
 full hosted documentation (every API, recipe, and example) lives at
-**https://docs.webjs.com**. Treat this file as the app-scoped
-companion and reach for docs.webjs.com whenever you need more detail.
+**https://docs.webjs.dev**. Treat this file as the app-scoped
+companion and reach for docs.webjs.dev whenever you need more detail.
 
 ## If you just scaffolded this app (AI agents, read first)
 
@@ -177,7 +177,7 @@ entry, its own template parser. Inside `` html`…` `` templates you get:
 In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
 automatically (no `tsconfig.json` edit, no separate Lit extension).
 
-See [docs.webjs.com → Editor setup](https://docs.webjs.com/docs/editor-setup)
+See [docs.webjs.dev → Editor setup](https://docs.webjs.dev/docs/editor-setup)
 for the full walkthrough.
 
 **Config validation in `package.json`.** The scaffold ships
@@ -567,7 +567,7 @@ git commit -m "vendor + download dayjs"
 Bundle files land in `.webjs/vendor/<pkg>@<version>.js`. importmap
 points at local `/__webjs/vendor/` paths. Browser fetches from your
 own origin. Suitable for `script-src 'self'` CSP, air-gapped deploys,
-or compliance environments. See [docs.webjs.com Deployment → CSP](https://docs.webjs.com/docs/deployment#csp).
+or compliance environments. See [docs.webjs.dev Deployment → CSP](https://docs.webjs.dev/docs/deployment#csp).
 
 **Other CLI commands:**
 
@@ -643,7 +643,7 @@ const url = process.env.WEBJS_PUBLIC_API_URL;       // works
 const secret = process.env.AUTH_SECRET;             // undefined (fail-closed)
 ```
 
-`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.com/docs/configuration).
+`process.env.NODE_ENV` is also defined in the browser (`'development'` in `webjs dev`, `'production'` in `webjs start`), so vendor bundles that probe it work without setup. Full docs: [Configuration](https://docs.webjs.dev/docs/configuration).
 
 ## Component pattern
 
@@ -838,7 +838,7 @@ that RETURNS a `ReadableStream` / async generator streams its chunks (consume
 with `for await`); read the request `AbortSignal` via `actionSignal()` to cancel
 on disconnect. **SAFETY:** a `cache` with `public: true` shares one response
 across all users, so use it only for data identical for every visitor. Full
-reference: https://docs.webjs.com/docs/server-actions
+reference: https://docs.webjs.dev/docs/server-actions
 
 ## Client navigation patterns (auto-magic)
 
diff --git a/packages/core/src/component.js b/packages/core/src/component.js
index f29ea3316..e94a093b9 100644
--- a/packages/core/src/component.js
+++ b/packages/core/src/component.js
@@ -573,7 +573,7 @@ class WebComponentBase extends Base {
             `properties via the factory instead: \`class ${name} extends WebComponent({ ` +
             `count: Number })\`. Use the \`prop()\` helper for options ` +
             `(\`prop(Number, { reflect: true })\`) and set defaults in the ` +
-            `constructor after \`super()\`. See https://docs.webjs.com/docs/components.`,
+            `constructor after \`super()\`. See https://docs.webjs.dev/docs/components.`,
         );
       }
       C = Object.getPrototypeOf(C);
diff --git a/packages/server/src/actions.js b/packages/server/src/actions.js
index 2341def41..47986a793 100644
--- a/packages/server/src/actions.js
+++ b/packages/server/src/actions.js
@@ -267,7 +267,7 @@ export function serveServerOnlyStub(relPath) {
     `This file is server-only (a .server.{js,ts} file with no 'use server' directive). ` +
     `Either add 'use server' at the top of the file to expose its exports as RPC, ` +
     `or wrap the server-only logic in a separate *.server.{js,ts} action and import that instead. ` +
-    `Docs: https://docs.webjs.com/docs/server-actions`;
+    `Docs: https://docs.webjs.dev/docs/server-actions`;
   return `// webjs: server-only module stub for ${relPath} (no 'use server' directive)
 throw new Error(${JSON.stringify(msg)});
 `;
diff --git a/packages/server/src/dev.js b/packages/server/src/dev.js
index 32bae289b..c544b331b 100644
--- a/packages/server/src/dev.js
+++ b/packages/server/src/dev.js
@@ -2369,7 +2369,7 @@ async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDevError)
           `Replace enum / namespace / parameter-property / legacy-decorator / ` +
           `import = require constructs with their erasable equivalents. ` +
           `Run \`webjs check\` for guidance (no-non-erasable-typescript rule). ` +
-          `Docs: https://docs.webjs.com/docs/typescript`
+          `Docs: https://docs.webjs.dev/docs/typescript`
         // Prod: terse, no path leak, no Node-message leak (Node's
         // message can include source snippets). Operators get the
         // detail in server logs above.
diff --git a/packages/server/test/guardrails/server-file-guardrail.test.js b/packages/server/test/guardrails/server-file-guardrail.test.js
index 358761ef8..75f375f7e 100644
--- a/packages/server/test/guardrails/server-file-guardrail.test.js
+++ b/packages/server/test/guardrails/server-file-guardrail.test.js
@@ -64,7 +64,7 @@ function assertIsServerOnlyStub(text) {
   assert.ok(/throw new Error/.test(text), 'server-only stub must throw on import');
   // #263: the throw-at-load message anchors a stable, fetchable docs URL.
   assert.ok(
-    text.includes('https://docs.webjs.com/docs/server-actions'),
+    text.includes('https://docs.webjs.dev/docs/server-actions'),
     'server-only stub message must anchor a docs URL'
   );
   assertNoSourceLeak(text);
diff --git a/test/docs/doc-source-consistency.test.mjs b/test/docs/doc-source-consistency.test.mjs
index e8919ec64..22194dd44 100644
--- a/test/docs/doc-source-consistency.test.mjs
+++ b/test/docs/doc-source-consistency.test.mjs
@@ -113,7 +113,7 @@ async function walkFiles(dir, re, out = []) {
  * The agent- AND user-facing doc corpus. Three surfaces:
  *  - AGENTS.md + agent-docs/*.md (agent-facing markdown, imports in ``` fences).
  *  - the scaffold's shipped AGENTS.md (ships into every app).
- *  - the docs SITE (`docs/app/**`, the docs.webjs.com source): its code samples
+ *  - the docs SITE (`docs/app/**`, the docs.webjs.dev source): its code samples
  *    are embedded in `.ts` page template strings, and its own components import
  *    the framework for real. Both must resolve, so the site cannot drift ahead
  *    of the shipped surface (the external documentation the user asked about).
diff --git a/test/docs/llms.test.mjs b/test/docs/llms.test.mjs
index e30cf987f..68d7f9309 100644
--- a/test/docs/llms.test.mjs
+++ b/test/docs/llms.test.mjs
@@ -60,7 +60,7 @@ describe('docs /llms.txt (the index)', () => {
     // The request origin is http in the harness, so links carry the
     // request origin. Assert the known titles are linked, and that the
     // link target is an absolute URL (origin-prefixed), which in
-    // production resolves to https://docs.webjs.com.
+    // production resolves to https://docs.webjs.dev.
     const links = body.split('\n').filter((l) => l.startsWith('- ['));
     assert.ok(links.length >= 3, 'expected at least 3 topic links');
     for (const title of ['Getting Started', 'Components', 'Server Actions']) {

From 9d0ede6543995859cbcf0bb6b0b13147133c5061 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:45:13 +0530
Subject: [PATCH 27/53] fix(cli): stop the layout forcing a scrollbar on short
 pages

<main> used min-h-screen (100vh) while <body> also reserves the fixed
header via padding-top, so the page was always header-height taller than
the viewport and showed a scrollbar even with little content. Size main to
min-h-[calc(100dvh-var(--header-h))] so body totals exactly the viewport.
---
 packages/cli/lib/create.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 0e97ee4ce..909fd428d 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1208,7 +1208,7 @@ ${UI_THEME}
       drop the cap and mx-auto for an edge-to-edge layout. A wide layout left
       inside the 760px reading column overflows into a horizontal scrollbar.
     -->
-    <main class="block max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12 min-h-screen">
+    <main class="block max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12 min-h-[calc(100dvh-var(--header-h))]">
       \${children}
     </main>
   \`;

From 0c6e457e566eceb27d1330a09ca5345fada063db Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:52:33 +0530
Subject: [PATCH 28/53] fix(cli): give saas its own home; teach agents the
 single-theme rule

Two things:
- The gallery-index home (links every /features/* demo + /examples/todo)
  leaked into the saas scaffold, which does not ship the gallery, so its
  home had nine dead links. Gate that home to full-stack; saas now gets a
  landing that links /login, /signup, /dashboard (what it actually ships).
- Document the single canonical theme in the scaffold AGENTS.md styling
  section: use the shadcn-standard tokens (bg-background, text-foreground,
  bg-accent, text-muted-foreground, border-border), never invent a parallel
  vocabulary, reach for opacity modifiers, edit the palette in one place,
  and `webjs ui add` components inherit it.
---
 packages/cli/lib/create.js       | 35 ++++++++++++++++++++++++++++++++
 packages/cli/templates/AGENTS.md | 25 +++++++++++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 909fd428d..4082982d2 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1215,6 +1215,10 @@ ${UI_THEME}
 }
 `);
 
+  // The gallery-index home (links every feature demo + the example app) ships
+  // only in the full-stack scaffold, which is the only one that ships the
+  // gallery. saas gets its own landing below.
+  if (isFullStack) {
   await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real page, then delete this line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import { rubric, displayH1, accentLink } from '#lib/utils/ui.ts';
@@ -1300,6 +1304,37 @@ export default function Home() {
   \`;
 }
 `);
+  } else {
+    // saas landing: the app has auth + a dashboard, so link those instead of a
+    // gallery it does not ship.
+    await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real landing page, then delete this line. webjs check fails while the marker remains.
+import { html } from '@webjsdev/core';
+import { rubric, displayH1, accentLink } from '#lib/utils/ui.ts';
+
+export const metadata = {
+  title: '${displayName}: built with webjs',
+};
+
+export default function Home() {
+  return html\`
+    <section class="mb-14">
+      \${rubric('welcome')}
+      \${displayH1(html\`Hello from <span class="text-accent italic">${displayName}</span>.\`)}
+      <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
+        The saas starter: email and password auth, a protected dashboard, and a
+        User model, all wired up. Replace this page with your product's landing.
+        See \${accentLink('https://docs.webjs.dev', 'the docs')} for the full reference.
+      </p>
+      <div class="flex gap-3 items-center">
+        <a href="/login" class="inline-flex items-center px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm no-underline transition-all hover:bg-accent/90 active:scale-[0.97]">Log in</a>
+        <a href="/signup" class="text-accent no-underline font-medium text-sm">Create an account</a>
+        <a href="/dashboard" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Dashboard</a>
+      </div>
+    </section>
+  \`;
+}
+`);
+  }
 
   // AGENTS.md is copied via the `templateFiles` loop above, from
   // `packages/cli/templates/AGENTS.md` with `{{APP_NAME}}` substitution.
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 6eec56cfd..e03129fda 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -801,6 +801,31 @@ globally. Prefer Tailwind. When a utility bundle repeats, extract it into
 a `lib/utils/ui.ts` helper returning an `` html`...` `` fragment, not a
 CSS class.
 
+#### Design tokens: ONE theme, shadcn-canonical
+
+The app has a SINGLE theme, defined once in `app/layout.ts`. It uses the
+standard `@webjsdev/ui` (shadcn-compatible) semantic tokens, set to this app's
+brand palette. Use the canonical utility names everywhere, in the page chrome
+AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+`text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`,
+`text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the
+tokens the components copied in by `webjs ui add <name>` read, so a scaffolded
+page and a later-added ui component share one coherent theme automatically.
+
+- **Never invent a parallel token vocabulary** (`--fg`, `--bg`, `text-fg`,
+  `bg-elev`, a separate `--brand`). It collides with the ui tokens (the accent
+  once flipped to neutral on navigation for exactly this reason) and diverges
+  from the shadcn conventions the ui kit and AI agents both expect.
+- **Reach for opacity modifiers before a new token**: `bg-accent/10` for a
+  tint, `hover:bg-accent/90` for a hover, `text-muted-foreground/70` for a
+  subtler text level.
+- **Edit the palette in one place** (`app/layout.ts`). To ADD a token, do it
+  the canonical way: a `--x` variable in the `:root` / `.dark` blocks plus a
+  `--color-x: var(--x)` line in the `@theme inline` block, then use it as
+  `bg-x` / `text-x`.
+- Dark mode is a `.dark` class the theme toggle sets. Tokens switch by theme
+  automatically, so a component written with these names works in both.
+
 Reserve raw CSS for what utilities cannot express: design-token `:root` /
 `@theme` definitions, `@property` + `@keyframes` animations,
 `::-webkit-scrollbar`, `prefers-reduced-motion` blocks, and complex

From 13d6452b7c8afb070dc706cf6a50e3badee5942e Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 19:57:58 +0530
Subject: [PATCH 29/53] feat(cli): add a "Built with webjs" footer with the
 brand mark

The scaffold showed no webjs branding. Add a footer (full-stack + saas
layout) with the gradient logo mark and a webjs.dev link, using
--logo-from / --logo-to tokens that match the website in light and dark.
Wrap main + footer in a flex column sized to the viewport minus the
header, so the footer sits at the bottom without reintroducing a
scrollbar on short pages.
---
 packages/cli/lib/create.js | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 4082982d2..5d48d6b26 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1114,6 +1114,8 @@ ${UI_THEME}
         --border-strong: oklch(0.38 0.012 55 / 0.9);
         --input: oklch(0.26 0.012 55 / 0.9);
         --ring: oklch(0.7 0.16 52);
+        --logo-from: oklch(0.8 0.16 58);
+        --logo-to: oklch(0.62 0.18 44);
       }
       /* light (explicit via the toggle) */
       :root[data-theme='light'] {
@@ -1136,6 +1138,8 @@ ${UI_THEME}
         --border-strong: oklch(0.78 0.01 75 / 0.95);
         --input: oklch(0.88 0.01 75 / 0.95);
         --ring: oklch(0.54 0.16 52);
+        --logo-from: oklch(0.63 0.17 50);
+        --logo-to: oklch(0.44 0.11 52);
       }
       /* light (OS preference, when the user has made no explicit choice) */
       @media (prefers-color-scheme: light) {
@@ -1159,6 +1163,8 @@ ${UI_THEME}
           --border-strong: oklch(0.78 0.01 75 / 0.95);
           --input: oklch(0.88 0.01 75 / 0.95);
           --ring: oklch(0.54 0.16 52);
+          --logo-from: oklch(0.63 0.17 50);
+          --logo-to: oklch(0.44 0.11 52);
         }
       }
       @theme inline {
@@ -1208,9 +1214,22 @@ ${UI_THEME}
       drop the cap and mx-auto for an edge-to-edge layout. A wide layout left
       inside the 760px reading column overflows into a horizontal scrollbar.
     -->
-    <main class="block max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12 min-h-[calc(100dvh-var(--header-h))]">
-      \${children}
-    </main>
+    <div class="flex flex-col min-h-[calc(100dvh-var(--header-h))]">
+      <main class="flex-1 w-full max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12">
+        \${children}
+      </main>
+      <!-- "Built with webjs" attribution. Keep it or replace it with your own
+           footer; the gradient mark uses the --logo-from/--logo-to tokens. -->
+      <footer class="border-t border-border">
+        <div class="max-w-[760px] mx-auto px-4 sm:px-6 py-6 flex items-center justify-center">
+          <a href="https://webjs.dev" class="inline-flex items-center gap-2 no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">
+            <span>Built with</span>
+            <span class="w-[18px] h-[18px] rounded-[6px] bg-gradient-to-br from-[var(--logo-from)] to-[var(--logo-to)] shadow-[0_2px_10px_var(--accent-tint)]"></span>
+            <span class="font-semibold text-foreground">webjs</span>
+          </a>
+        </div>
+      </footer>
+    </div>
   \`;
 }
 `);

From 922631b8d3ecd559135b12596d727c339337d4c7 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 20:33:36 +0530
Subject: [PATCH 30/53] feat(cli): add 9 advanced gallery feature demos (#827)

Expand the scaffold feature gallery from 8 to 17 single-feature demos so a
coding agent gains context on the whole webjs surface, not just the core.

New pure-page demos: metadata (generateMetadata), caching (revalidate), env
(public vs server), client-router (soft nav + a second page), service-worker
(opt-in registration recipe).

New infra demos, each with a server endpoint and a hydrating component or a
no-JS form: websockets (WS echo + connectWS), broadcast (fan-out to all
clients), rate-limit (rateLimit middleware scoped to one endpoint), file-storage
(multipart upload streamed into the FileStore, served back through a route).

Every demo is app-thin routing plus modules/ logic, densely commented,
progressive-enhancement-safe, and carries a webjs-scaffold-placeholder marker.
Verified in a generated app: all 17 routes 200, the rate limiter 429s past its
window, the upload round-trips, and both WebSocket endpoints echo and fan out.
Full-stack template only (api has no UI; saas ships its own auth example).
---
 packages/cli/lib/create.js                    |  9 +++
 packages/cli/templates/AGENTS.md              |  6 +-
 .../app/features/broadcast/feed/route.ts      | 19 ++++++
 .../gallery/app/features/broadcast/page.ts    | 24 +++++++
 .../gallery/app/features/caching/page.ts      | 39 ++++++++++++
 .../app/features/client-router/page.ts        | 34 ++++++++++
 .../app/features/client-router/second/page.ts | 20 ++++++
 .../gallery/app/features/env/page.ts          | 36 +++++++++++
 .../features/file-storage/file/[key]/route.ts | 19 ++++++
 .../gallery/app/features/file-storage/page.ts | 62 +++++++++++++++++++
 .../gallery/app/features/metadata/page.ts     | 55 ++++++++++++++++
 .../gallery/app/features/rate-limit/page.ts   | 29 +++++++++
 .../features/rate-limit/ping/middleware.ts    |  8 +++
 .../app/features/rate-limit/ping/route.ts     |  7 +++
 .../app/features/service-worker/page.ts       | 34 ++++++++++
 .../app/features/websockets/echo/route.ts     | 19 ++++++
 .../gallery/app/features/websockets/page.ts   | 25 ++++++++
 .../broadcast/components/broadcast-feed.ts    | 61 ++++++++++++++++++
 .../actions/store-upload.server.ts            | 18 ++++++
 .../rate-limit/components/rate-probe.ts       | 49 +++++++++++++++
 .../modules/websockets/components/ws-echo.ts  | 62 +++++++++++++++++++
 test/scaffolds/scaffold-gallery.test.js       | 12 +++-
 22 files changed, 644 insertions(+), 3 deletions(-)
 create mode 100644 packages/cli/templates/gallery/app/features/broadcast/feed/route.ts
 create mode 100644 packages/cli/templates/gallery/app/features/broadcast/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/caching/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/client-router/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/client-router/second/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/env/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/file-storage/file/[key]/route.ts
 create mode 100644 packages/cli/templates/gallery/app/features/file-storage/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/metadata/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/rate-limit/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/rate-limit/ping/middleware.ts
 create mode 100644 packages/cli/templates/gallery/app/features/rate-limit/ping/route.ts
 create mode 100644 packages/cli/templates/gallery/app/features/service-worker/page.ts
 create mode 100644 packages/cli/templates/gallery/app/features/websockets/echo/route.ts
 create mode 100644 packages/cli/templates/gallery/app/features/websockets/page.ts
 create mode 100644 packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
 create mode 100644 packages/cli/templates/gallery/modules/file-storage/actions/store-upload.server.ts
 create mode 100644 packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
 create mode 100644 packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 5d48d6b26..7afb65547 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1267,6 +1267,15 @@ const features = [
   { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
   { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
   { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+  { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+  { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
+  { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
+  { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
+  { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
+  { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
+  { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
+  { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
+  { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
 ];
 const examples = [
   { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index e03129fda..ec491e167 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -312,7 +312,8 @@ app/                     ROUTING ONLY: thin route adapters (import from modules/
   page.ts                → / (the scaffold home links to the gallery)
   features/<name>/       single-feature demos (routing, components,
                          server-actions, optimistic-ui, async-render,
-                         directives, route-handler); prune what you skip
+                         directives, route-handler, forms, metadata, caching,
+                         env, client-router, service-worker); prune what you skip
   examples/<name>/       whole example apps that compose features (todo);
                          prune what you skip
   layout.ts              root layout, wraps every page
@@ -363,7 +364,8 @@ The scaffold ships a gallery organized by KIND, so features and whole apps are
 not mixed:
 - `app/features/<name>/` are single-feature demos, one webjs concept each
   (routing, components, server-actions, optimistic-ui, async-render, directives,
-  route-handler).
+  route-handler, forms, metadata, caching, env, client-router, service-worker,
+  plus the infra demos websockets, file-storage, rate-limit, broadcast).
 - `app/examples/<name>/` are whole example apps that compose several features
   (todo: optimistic UI + progressive enhancement + a11y + db + modules).
 
diff --git a/packages/cli/templates/gallery/app/features/broadcast/feed/route.ts b/packages/cli/templates/gallery/app/features/broadcast/feed/route.ts
new file mode 100644
index 000000000..0ea639b01
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/broadcast/feed/route.ts
@@ -0,0 +1,19 @@
+// The WebSocket endpoint for the broadcast demo. Unlike the echo endpoint, this
+// fans each incoming message out to EVERY client on the path with broadcast()
+// from '@webjsdev/server'. The framework auto-registers each connection to its
+// route path, so broadcast('/features/broadcast/feed', ...) reaches all of them.
+import { broadcast } from '@webjsdev/server';
+
+// Structural type for the socket, so the demo needs no `@types/ws` dependency.
+type WSLike = {
+  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;
+  send(msg: string): void;
+};
+
+export function WS(ws: WSLike) {
+  ws.on('message', (data) => {
+    // Fan out to every connected client (the sender included, so all open tabs
+    // stay in sync). Pass { except: ws } if you want to skip the sender.
+    broadcast('/features/broadcast/feed', data.toString());
+  });
+}
diff --git a/packages/cli/templates/gallery/app/features/broadcast/page.ts b/packages/cli/templates/gallery/app/features/broadcast/page.ts
new file mode 100644
index 000000000..40c9aee95
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/broadcast/page.ts
@@ -0,0 +1,24 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/broadcast route AND modules/broadcast), then delete this marker line. webjs check fails while the marker remains.
+// Broadcast: fan a message out to EVERY client connected to a WebSocket path,
+// not just the sender. The framework auto-registers each connection to its path,
+// so broadcast(path, data) from '@webjsdev/server' reaches all of them. This is
+// the difference from the plain websockets demo (which echoes to one socket).
+// Open this page in two browser tabs and send: both see every message.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/broadcast/components/broadcast-feed.ts';
+
+export const metadata: Metadata = { title: 'Broadcast (fan-out to all clients) | features' };
+
+export default function BroadcastExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Broadcast</h1>
+    <p class="text-muted-foreground mb-4">
+      Every message is fanned out to all connected clients via
+      <code class="font-mono">broadcast()</code>. Open this page in a second tab
+      and watch messages appear in both. Single-instance by default; wire Redis
+      to scale across processes.
+    </p>
+    <broadcast-feed></broadcast-feed>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
new file mode 100644
index 000000000..45eb16b51
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -0,0 +1,39 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/caching route), then delete this marker line. webjs check fails while the marker remains.
+// Caching: `export const revalidate = N` opts the page into the server HTML
+// response cache, keyed by URL for N seconds. The rendered timestamp below only
+// changes once per window: reload inside 10s and it is identical, reload after
+// and it refreshes. SAFETY: only cache a page that is identical for every
+// visitor (no cookies(), no session, no per-user data), since the key is the URL
+// alone. For per-query reads use cache() + tags with revalidateTag; for assets
+// use HTTP Cache-Control + ETag (conditional GET).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Caching (revalidate) | features' };
+
+// Cache this page's SSR HTML for 10 seconds.
+export const revalidate = 10;
+
+export default function CachingExample() {
+  // Runs at render time, then the whole response is cached for `revalidate`
+  // seconds, so this value is frozen until the window elapses.
+  const renderedAt = new Date().toLocaleTimeString('en-US', { hour12: false });
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Caching</h1>
+    <p class="text-muted-foreground mb-4">
+      This page sets <code>export const revalidate = 10</code>, so its
+      server-rendered HTML is cached per URL for ten seconds.
+    </p>
+    <p class="mb-4">
+      Rendered at
+      <code class="font-mono text-accent">${renderedAt}</code>.
+      Reload within 10s and this is unchanged; after 10s it re-renders.
+    </p>
+    <p class="text-muted-foreground text-sm">
+      Only for pages identical for every visitor. For per-user or per-query data
+      use <code>cache()</code> with <code>tags</code> and
+      <code>revalidateTag</code>, or a GET action's
+      <code>export const cache</code>.
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
new file mode 100644
index 000000000..827129909
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -0,0 +1,34 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/client-router route AND its second/ subpage), then delete this marker line. webjs check fails while the marker remains.
+// Client router: automatic. It auto-enables the moment @webjsdev/core loads in
+// the browser (the bundle every component pulls, so any page with a component
+// gets it for free). There is nothing to import. An <a href> to another page
+// does a soft navigation: the framework fetches only the divergent fragment
+// (via the X-Webjs-Have header), swaps it in place, and restores scroll on
+// back/forward. Links prefetch on hover by default. It degrades perfectly: with
+// JS off, every link is a normal full-page navigation.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router (soft nav) | features' };
+
+export default function ClientRouterExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Client router</h1>
+    <p class="text-muted-foreground mb-4">
+      Navigate to the second page and back. With JS on it is a soft swap (no full
+      reload, scroll restored); open the network tab to see only a fragment
+      fetched, prefetched on hover. With JS off the same links do full-page
+      navigations. Nothing was imported to get this.
+    </p>
+    <div class="flex gap-3 items-center">
+      <a href="/features/client-router/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm no-underline transition-all hover:bg-accent/90 active:scale-[0.97]">Go to page two</a>
+      <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
+    </div>
+    <p class="text-muted-foreground text-sm mt-6">
+      Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,
+      or per-link with <code class="font-mono">data-no-router</code> (use it for
+      auth flows like <code class="font-mono">/logout</code> that must reset
+      in-memory state).
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/client-router/second/page.ts b/packages/cli/templates/gallery/app/features/client-router/second/page.ts
new file mode 100644
index 000000000..c7204063c
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/client-router/second/page.ts
@@ -0,0 +1,20 @@
+// webjs-scaffold-placeholder. Feature gallery route (client-router page two). Pruned together with the parent app/features/client-router route. Delete this marker line once you adapt or remove it. webjs check fails while the marker remains.
+// The soft-navigation target for the client-router demo. A plain page: the
+// router needs no per-page code. The browser Back button restores this page and
+// its scroll position from the client-router snapshot cache.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Client router: page two | features' };
+
+export default function ClientRouterSecond() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Page two</h1>
+    <p class="text-muted-foreground mb-4">
+      You arrived here without a full reload. Press the browser Back button (or
+      the link below): the previous page and its scroll position are restored
+      from the snapshot cache.
+    </p>
+    <a href="/features/client-router" class="text-accent no-underline font-medium">&larr; Back to page one</a>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/env/page.ts b/packages/cli/templates/gallery/app/features/env/page.ts
new file mode 100644
index 000000000..5f1589fca
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/env/page.ts
@@ -0,0 +1,36 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/env route), then delete this marker line. webjs check fails while the marker remains.
+// Environment variables: process.env.X reads are server-only. NODE_ENV is
+// defined on both sides. A name prefixed WEBJS_PUBLIC_ is exposed to the browser
+// through an inline script (no build step); everything else stays server-side
+// so secrets never reach the client. This page reads them during SSR, so the
+// values are in the first paint with no JS. Validate required vars at boot with
+// an app-root env.ts (a schema or a validator fn) that fails fast.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Env vars (public vs server) | features' };
+
+export default function EnvExample() {
+  // Server-only read (this function runs on the server for SSR).
+  const nodeEnv = process.env.NODE_ENV || 'development';
+  // A WEBJS_PUBLIC_ var is safe to surface to the browser; unset here unless you
+  // add WEBJS_PUBLIC_APP_NAME=... to .env, which demonstrates the default.
+  const publicName = process.env.WEBJS_PUBLIC_APP_NAME || '(unset, add WEBJS_PUBLIC_APP_NAME to .env)';
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Environment variables</h1>
+    <p class="text-muted-foreground mb-4">
+      Read on the server during SSR. Only <code>WEBJS_PUBLIC_</code>-prefixed
+      names are exposed to the browser; the rest stay server-side.
+    </p>
+    <ul class="list-disc pl-5 mb-4 space-y-1">
+      <li><code class="font-mono text-sm">NODE_ENV</code> = <span class="text-accent">${nodeEnv}</span> <span class="text-muted-foreground text-sm">(defined both sides)</span></li>
+      <li><code class="font-mono text-sm">WEBJS_PUBLIC_APP_NAME</code> = <span class="text-accent">${publicName}</span></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Never read a secret in a page, layout, or component that ships to the
+      browser. Keep secret reads in <code class="font-mono">.server.ts</code>
+      files, and validate required vars at boot with
+      <code class="font-mono">app/env.ts</code>.
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/file-storage/file/[key]/route.ts b/packages/cli/templates/gallery/app/features/file-storage/file/[key]/route.ts
new file mode 100644
index 000000000..62d88d052
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/file-storage/file/[key]/route.ts
@@ -0,0 +1,19 @@
+// Serves a stored file back by key. getFileStore().get(key) returns the bytes as
+// a web ReadableStream (streamed, never buffered whole into memory) plus the
+// content type recorded at upload. A route.ts is server-only, so importing the
+// storage singleton here is safe. The [key] segment is validated inside the
+// store (traversal-safe), so a crafted key cannot escape the uploads directory.
+import { getFileStore } from '@webjsdev/server';
+
+export async function GET(_req: Request, { params }: { params: { key: string } }) {
+  const file = await getFileStore().get(params.key);
+  if (!file) return new Response('Not found', { status: 404 });
+  // file.body is a web ReadableStream at runtime (the diskStore streams the
+  // bytes); the store's type is a Node/web union, so narrow it for Response.
+  return new Response(file.body as ReadableStream<Uint8Array>, {
+    headers: {
+      'content-type': file.contentType,
+      'content-length': String(file.size),
+    },
+  });
+}
diff --git a/packages/cli/templates/gallery/app/features/file-storage/page.ts b/packages/cli/templates/gallery/app/features/file-storage/page.ts
new file mode 100644
index 000000000..86416fa0d
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/file-storage/page.ts
@@ -0,0 +1,62 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/file-storage route AND modules/file-storage), then delete this marker line. webjs check fails while the marker remains.
+// File storage: a no-JS upload. A multipart <form> posts to this page's `action`
+// (the progressive-enhancement write path); the action calls a 'use server'
+// helper that streams the bytes into the FileStore. On success it redirects
+// (PRG) with the new key in the query, and the page renders a download link that
+// streams the file back through file/[key]/route.ts. Works with JS off; the
+// client router applies the same flow in place with JS on.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import { storeUpload } from '#modules/file-storage/actions/store-upload.server.ts';
+
+export const metadata: Metadata = { title: 'File storage (upload + serve) | features' };
+
+export async function action({ formData }: { formData: FormData }) {
+  const file = formData.get('file');
+  if (!(file instanceof File) || file.size === 0) {
+    return { success: false, error: 'Choose a file to upload.' };
+  }
+  const result = await storeUpload(file);
+  if (!result.success) return result;
+  const { key, name, size } = result.data;
+  const q = new URLSearchParams({ key, name, size: String(size) });
+  return { success: true, redirect: '/features/file-storage?' + q.toString() };
+}
+
+export default function FileStorageExample({
+  searchParams,
+  actionData,
+}: {
+  searchParams: Record<string, string | undefined>;
+  actionData?: { error?: string };
+}) {
+  const key = (searchParams.key || '').trim();
+  const name = (searchParams.name || '').trim();
+  const size = (searchParams.size || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">File storage</h1>
+    <p class="text-muted-foreground mb-4">
+      Upload a file: the bytes stream into the FileStore (a local
+      <code class="font-mono">.webjs/uploads</code> directory by default,
+      gitignored). Swap the backend for S3/R2 with one
+      <code class="font-mono">setFileStore()</code> call, no call-site change.
+    </p>
+    <form method="post" enctype="multipart/form-data" class="flex flex-wrap gap-3 items-center mb-4">
+      <input type="file" name="file" required
+        class="text-sm text-muted-foreground file:mr-3 file:px-3.5 file:py-2 file:rounded-xl file:border-0 file:bg-card file:border file:border-border file:text-foreground file:text-sm file:cursor-pointer" />
+      <button type="submit"
+        class="px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Upload</button>
+    </form>
+    ${actionData?.error
+      ? html`<p class="text-destructive text-sm mb-4">${actionData.error}</p>`
+      : ''}
+    ${key
+      ? html`
+        <div class="px-4 py-3 rounded-xl bg-card border border-border text-sm">
+          Stored <span class="text-foreground font-medium">${name}</span>
+          <span class="text-muted-foreground/70">(${size} bytes)</span>
+          <a class="text-accent no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
+        </div>`
+      : ''}
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/metadata/page.ts b/packages/cli/templates/gallery/app/features/metadata/page.ts
new file mode 100644
index 000000000..103c307b4
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/metadata/page.ts
@@ -0,0 +1,55 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/metadata route), then delete this marker line. webjs check fails while the marker remains.
+// Metadata: how a page declares its <title>, description, and Open Graph tags.
+// A static `metadata` export is read as-is. `generateMetadata(ctx)` takes
+// precedence and can read the request (params, searchParams, url) to compute
+// the tags, and may be async. Both run only on the server, so the tags are in
+// the first paint (no JS, crawler-friendly). Whole-page metadata ROUTES
+// (sitemap.ts, robots.ts, opengraph-image.ts, ...) live at the app root.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+// generateMetadata wins over a static `metadata` export when both exist. Here
+// it derives the title from a ?topic= query param to show the dynamic form;
+// with no param it falls back to a default. Change the URL to ?topic=webjs and
+// view source: the <title> follows.
+export function generateMetadata({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}): Metadata {
+  const topic = (searchParams.topic || '').trim();
+  return {
+    title: topic ? topic + ' | metadata' : 'Metadata (generateMetadata) | features',
+    description: 'How a webjs page declares title, description, and Open Graph tags.',
+    openGraph: { title: topic || 'Metadata', type: 'article' },
+  };
+}
+
+export default function MetadataExample({
+  searchParams,
+}: {
+  searchParams: Record<string, string | undefined>;
+}) {
+  const topic = (searchParams.topic || '').trim();
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Metadata</h1>
+    <p class="text-muted-foreground mb-4">
+      <code>generateMetadata(ctx)</code> runs on the server and can read the
+      request, so the <code>&lt;title&gt;</code> is computed per URL. View source
+      to see the tag this page produced.
+    </p>
+    <p class="mb-4">
+      Current title source:
+      <code class="font-mono text-sm">${topic ? '?topic=' + topic : '(default, no ?topic=)'}</code>
+    </p>
+    <ul class="list-disc pl-5 mb-4">
+      <li><a class="text-accent" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
+      <li><a class="text-accent" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
+      <li><a class="text-accent" href="/features/metadata">clear the param</a></li>
+    </ul>
+    <p class="text-muted-foreground text-sm">
+      Site-wide metadata (sitemap, robots, Open Graph images) lives in metadata
+      ROUTES at the app root, e.g. <code class="font-mono">app/sitemap.ts</code>.
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
new file mode 100644
index 000000000..8b44cf6be
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -0,0 +1,29 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/rate-limit route AND modules/rate-limit), then delete this marker line. webjs check fails while the marker remains.
+// Rate limiting: rateLimit() from '@webjsdev/server' is a middleware. It lives in
+// a middleware.ts scoped to the endpoint it protects (here app/features/
+// rate-limit/ping/middleware.ts, so it limits /features/rate-limit/ping WITHOUT
+// touching this page). It is backed by the pluggable cache store, in-memory by
+// default; point the store at Redis to share the window across instances.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/rate-limit/components/rate-probe.ts';
+
+export const metadata: Metadata = { title: 'Rate limiting (rateLimit middleware) | features' };
+
+export default function RateLimitExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Rate limiting</h1>
+    <p class="text-muted-foreground mb-4">
+      The <code class="font-mono">/ping</code> endpoint is limited to five
+      requests per ten seconds by a scoped <code class="font-mono">middleware.ts</code>.
+      Ping past the limit to get a <code class="font-mono">429</code> with a
+      <code class="font-mono">Retry-After</code> header.
+    </p>
+    <rate-probe></rate-probe>
+    <p class="text-muted-foreground text-sm mt-4">
+      With JavaScript off, hit
+      <a class="text-accent" href="/features/rate-limit/ping">/features/rate-limit/ping</a>
+      directly (refresh past five times in ten seconds).
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/ping/middleware.ts b/packages/cli/templates/gallery/app/features/rate-limit/ping/middleware.ts
new file mode 100644
index 000000000..1b029c1a6
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/rate-limit/ping/middleware.ts
@@ -0,0 +1,8 @@
+// Per-segment middleware. It sits in the ping/ folder, so it applies ONLY to
+// /features/rate-limit/ping (its route.ts), not to the demo page one level up.
+// rateLimit() returns a standard webjs middleware: return a Response to
+// short-circuit (the 429), or call next() to continue. Keyed by client IP by
+// default; pass `key` to key by user id, API key, etc.
+import { rateLimit } from '@webjsdev/server';
+
+export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/ping/route.ts b/packages/cli/templates/gallery/app/features/rate-limit/ping/route.ts
new file mode 100644
index 000000000..4f954c5e6
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/rate-limit/ping/route.ts
@@ -0,0 +1,7 @@
+// The rate-limited endpoint. A plain GET route handler: it just reports success.
+// The rateLimit() middleware in this folder runs BEFORE it and stamps the
+// X-RateLimit-* headers onto the response (and returns a 429 once the window is
+// exhausted, so this handler never runs on a limited request).
+export function GET() {
+  return Response.json({ ok: true, at: new Date().toISOString() });
+}
diff --git a/packages/cli/templates/gallery/app/features/service-worker/page.ts b/packages/cli/templates/gallery/app/features/service-worker/page.ts
new file mode 100644
index 000000000..aa2786dfa
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/service-worker/page.ts
@@ -0,0 +1,34 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/service-worker route), then delete this marker line. webjs check fails while the marker remains.
+// Service worker: opt-in progressive enhancement. webjs does NOT register one by
+// default (an active SW caches aggressively and would confuse dev). You opt in
+// by adding public/sw.js and registering it from a component's connectedCallback
+// (browser-only). This page is a guided reference, not an active registration,
+// so the scaffold stays predictable until you deliberately turn it on. See
+// agent-docs/service-worker.md for the full recipe.
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+
+export const metadata: Metadata = { title: 'Service worker (opt-in) | features' };
+
+export default function ServiceWorkerExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">Service worker</h1>
+    <p class="text-muted-foreground mb-4">
+      Opt-in offline/caching enhancement. Nothing is registered until you add
+      <code class="font-mono">public/sw.js</code> and register it from a
+      browser-only lifecycle hook.
+    </p>
+    <p class="mb-2 text-sm font-medium">Register inside a component (never in a page or layout):</p>
+    <pre class="bg-card border border-border rounded-xl p-4 overflow-x-auto text-sm font-mono mb-4"><code>connectedCallback() {
+  super.connectedCallback();
+  if ('serviceWorker' in navigator) {
+    navigator.serviceWorker.register('/public/sw.js');
+  }
+}</code></pre>
+    <p class="text-muted-foreground text-sm">
+      Registration lives in a component because it is browser-only work.
+      A page or layout never hydrates, so it is the wrong home for it. Full
+      recipe: <code class="font-mono">agent-docs/service-worker.md</code>.
+    </p>
+  `;
+}
diff --git a/packages/cli/templates/gallery/app/features/websockets/echo/route.ts b/packages/cli/templates/gallery/app/features/websockets/echo/route.ts
new file mode 100644
index 000000000..6381880fb
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/websockets/echo/route.ts
@@ -0,0 +1,19 @@
+// The WebSocket endpoint for the websockets feature demo. A route.ts is a
+// server-only HTTP file; exporting WS(ws, req, ctx) upgrades it to a WebSocket
+// endpoint. `ws` is a standard ws-library socket: listen with ws.on('message'),
+// reply with ws.send(). In dev the module is re-imported per connection, so keep
+// shared state on globalThis if you need it (this echo endpoint is stateless).
+
+// Structural type for the socket, so the demo needs no `@types/ws` dependency.
+type WSLike = {
+  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;
+  send(msg: string): void;
+};
+
+export function WS(ws: WSLike) {
+  ws.on('message', (data) => {
+    // Echo the text back to just this client. For a fan-out to ALL connected
+    // clients, use broadcast() from '@webjsdev/server' (see the broadcast demo).
+    ws.send('echo: ' + data.toString());
+  });
+}
diff --git a/packages/cli/templates/gallery/app/features/websockets/page.ts b/packages/cli/templates/gallery/app/features/websockets/page.ts
new file mode 100644
index 000000000..0c83c0aee
--- /dev/null
+++ b/packages/cli/templates/gallery/app/features/websockets/page.ts
@@ -0,0 +1,25 @@
+// webjs-scaffold-placeholder. Feature gallery route. Keep and adapt it, or prune it (delete this app/features/websockets route AND modules/websockets), then delete this marker line. webjs check fails while the marker remains.
+// WebSockets: a route.ts exports WS(ws, req) for the server endpoint, and a
+// component uses connectWS() to talk to it. WebSockets are inherently JS-only
+// (there is no no-JS fallback for a live socket), so the component degrades to a
+// clear "requires JavaScript" note at SSR and enhances on hydration. The echo
+// endpoint lives at app/features/websockets/echo/route.ts (a sibling folder, so
+// it does not collide with this page).
+import { html } from '@webjsdev/core';
+import type { Metadata } from '@webjsdev/core';
+import '#modules/websockets/components/ws-echo.ts';
+
+export const metadata: Metadata = { title: 'WebSockets (connectWS + WS) | features' };
+
+export default function WebSocketsExample() {
+  return html`
+    <h1 class="text-h2 font-bold mb-4">WebSockets</h1>
+    <p class="text-muted-foreground mb-4">
+      A <code class="font-mono">WS(ws, req)</code> export in
+      <code class="font-mono">route.ts</code> is the server endpoint;
+      <code class="font-mono">connectWS()</code> (auto-reconnect, JSON
+      encode/decode, queued sends) is the client. This echoes each message back.
+    </p>
+    <ws-echo></ws-echo>
+  `;
+}
diff --git a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
new file mode 100644
index 000000000..15cc1731a
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
@@ -0,0 +1,61 @@
+// A shared broadcast room. Same connectWS() client as the websockets demo, but
+// the server fans each message out to all connected sockets, so every open tab
+// shows the same feed. The socket opens in connectedCallback (browser-only) and
+// closes in disconnectedCallback. At SSR it renders the disconnected state, so
+// the page still reads with JS off (a live feed has no no-JS equivalent).
+import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+
+export class BroadcastFeed extends WebComponent {
+  private connected = signal(false);
+  private lines = signal<string[]>([]);
+  #conn: ReturnType<typeof connectWS> | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#conn = connectWS('/features/broadcast/feed', {
+      onOpen: () => this.connected.set(true),
+      onClose: () => this.connected.set(false),
+      onMessage: (msg: unknown) => this.lines.set([...this.lines.get(), String(msg)]),
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#conn?.close();
+    this.#conn = null;
+  }
+
+  private send(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const input = form.elements.namedItem('msg') as HTMLInputElement;
+    const text = input.value.trim();
+    if (!text) return;
+    this.#conn?.send(text);
+    input.value = '';
+  }
+
+  render() {
+    const on = this.connected.get();
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <div class="flex items-center gap-2 text-sm">
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-accent' : 'bg-muted-foreground/40'}"></span>
+          <span class="text-muted-foreground">${on ? 'in the room' : 'connecting (the live room needs JavaScript)'}</span>
+        </div>
+        <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
+          <input name="msg" autocomplete="off" placeholder="Message everyone"
+            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+          <button type="submit"
+            class="px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send</button>
+        </form>
+        <ul class="grid gap-1.5 list-none m-0 p-0">
+          ${this.lines.get().map((line) => html`
+            <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">${line}</li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+BroadcastFeed.register('broadcast-feed');
diff --git a/packages/cli/templates/gallery/modules/file-storage/actions/store-upload.server.ts b/packages/cli/templates/gallery/modules/file-storage/actions/store-upload.server.ts
new file mode 100644
index 000000000..12d6b6823
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/file-storage/actions/store-upload.server.ts
@@ -0,0 +1,18 @@
+// 'use server' so the page's action can call it (server-side, a direct call) and
+// it never crashes the browser module that imports it (the client gets a safe
+// RPC stub, not the node:fs code). getFileStore() is the pluggable storage
+// singleton: a local diskStore rooted at <cwd>/.webjs/uploads by default
+// (gitignored), swappable for S3/R2/GCS with one setFileStore() call at boot.
+// generateKey() mints a collision-free, traversal-safe key preserving a
+// whitelisted extension.
+'use server';
+import { getFileStore, generateKey } from '@webjsdev/server';
+
+export async function storeUpload(file: File) {
+  if (!(file instanceof File) || file.size === 0) {
+    return { success: false as const, error: 'No file provided.' };
+  }
+  const key = generateKey(file.name);
+  const { size, contentType } = await getFileStore().put(key, file, { contentType: file.type });
+  return { success: true as const, data: { key, name: file.name, size, contentType } };
+}
diff --git a/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
new file mode 100644
index 000000000..c413c5928
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
@@ -0,0 +1,49 @@
+// A small probe for the rate-limited endpoint. Each click fetches
+// /features/rate-limit/ping and records the status plus the X-RateLimit-Remaining
+// header the middleware stamped on. This is a legitimate hand-written fetch: the
+// target is a route.ts HTTP endpoint (not a server action, which you would
+// import and call instead). The button is the interactivity signal, so this
+// component ships and hydrates.
+import { WebComponent, signal, html } from '@webjsdev/core';
+
+interface Probe { n: number; status: number; remaining: string }
+
+export class RateProbe extends WebComponent {
+  private log = signal<Probe[]>([]);
+  private busy = signal(false);
+  #n = 0;
+
+  private async ping() {
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    try {
+      const res = await fetch('/features/rate-limit/ping', { headers: { accept: 'application/json' } });
+      this.#n += 1;
+      this.log.set([
+        { n: this.#n, status: res.status, remaining: res.headers.get('x-ratelimit-remaining') ?? '?' },
+        ...this.log.get(),
+      ].slice(0, 8));
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  render() {
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <button @click=${() => this.ping()}
+          class="w-fit px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Ping the endpoint</button>
+        <ul class="grid gap-1.5 list-none m-0 p-0">
+          ${this.log.get().map((p) => html`
+            <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">
+              <span class="text-muted-foreground">#${p.n}</span>
+              <span class="font-mono ${p.status === 429 ? 'text-destructive' : 'text-accent'}">${p.status === 429 ? '429 limited' : '200 ok'}</span>
+              <span class="text-muted-foreground/70 text-[13px]">remaining: ${p.remaining}</span>
+            </li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+RateProbe.register('rate-probe');
diff --git a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
new file mode 100644
index 000000000..1e4678f2e
--- /dev/null
+++ b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
@@ -0,0 +1,62 @@
+// A WebSocket echo client. connectWS() (from '@webjsdev/core') opens the socket,
+// auto-reconnects with backoff, JSON-encodes/decodes, and queues sends while
+// disconnected. The connection is opened in connectedCallback (browser-only, so
+// it never runs during SSR) and closed in disconnectedCallback. At SSR the
+// component renders its disconnected state, so with JS off the page still reads
+// (a live socket has no no-JS equivalent, which is the honest fallback here).
+import { WebComponent, signal, html, connectWS } from '@webjsdev/core';
+
+export class WsEcho extends WebComponent {
+  private connected = signal(false);
+  private lines = signal<string[]>([]);
+  #conn: ReturnType<typeof connectWS> | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#conn = connectWS('/features/websockets/echo', {
+      onOpen: () => this.connected.set(true),
+      onClose: () => this.connected.set(false),
+      onMessage: (msg: unknown) => this.lines.set([...this.lines.get(), String(msg)]),
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#conn?.close();
+    this.#conn = null;
+  }
+
+  private send(e: SubmitEvent) {
+    e.preventDefault();
+    const form = e.target as HTMLFormElement;
+    const input = form.elements.namedItem('msg') as HTMLInputElement;
+    const text = input.value.trim();
+    if (!text) return;
+    this.#conn?.send(text);
+    input.value = '';
+  }
+
+  render() {
+    const on = this.connected.get();
+    return html`
+      <div class="grid gap-4 max-w-[420px]">
+        <div class="flex items-center gap-2 text-sm">
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-accent' : 'bg-muted-foreground/40'}"></span>
+          <span class="text-muted-foreground">${on ? 'connected' : 'connecting (live echo needs JavaScript)'}</span>
+        </div>
+        <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
+          <input name="msg" autocomplete="off" placeholder="Say something"
+            class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
+          <button type="submit"
+            class="px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send</button>
+        </form>
+        <ul class="grid gap-1.5 list-none m-0 p-0">
+          ${this.lines.get().map((line) => html`
+            <li class="px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground font-mono">${line}</li>
+          `)}
+        </ul>
+      </div>
+    `;
+  }
+}
+WsEcho.register('ws-echo');
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index bb451a307..c1b36c2c7 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -27,12 +27,14 @@ import { scaffoldApp } from '../../packages/cli/lib/create.js';
 const FEATURES = [
   'routing', 'components', 'server-actions', 'optimistic-ui',
   'async-render', 'directives', 'route-handler', 'forms',
+  'metadata', 'caching', 'env', 'client-router', 'service-worker',
+  'websockets', 'broadcast', 'rate-limit', 'file-storage',
 ];
 // Whole example apps under app/examples/<name>.
 const EXAMPLE_APPS = ['todo'];
 // Routes whose logic lives in a modules/<name> folder (routing and
 // route-handler are app-only: a pages-only route and a route.ts handler).
-const MODULE_ROUTES = ['components', 'server-actions', 'optimistic-ui', 'async-render', 'directives', 'todo'];
+const MODULE_ROUTES = ['components', 'server-actions', 'optimistic-ui', 'async-render', 'directives', 'todo', 'websockets', 'broadcast', 'rate-limit', 'file-storage'];
 
 async function tempCwd() {
   return mkdtemp(join(tmpdir(), 'webjs-scaffold-gallery-'));
@@ -56,6 +58,14 @@ test('full-stack scaffold ships feature demos and one example app', async () =>
     // Dynamic route param example + the route.ts handler.
     assert.ok(await exists(join(appDir, 'app', 'features', 'routing', '[id]', 'page.ts')));
     assert.ok(await exists(join(appDir, 'app', 'features', 'route-handler', 'data', 'route.ts')));
+    // Client-router soft-nav target subpage.
+    assert.ok(await exists(join(appDir, 'app', 'features', 'client-router', 'second', 'page.ts')));
+    // Infra features ship their server endpoints alongside the page.
+    assert.ok(await exists(join(appDir, 'app', 'features', 'websockets', 'echo', 'route.ts')));
+    assert.ok(await exists(join(appDir, 'app', 'features', 'broadcast', 'feed', 'route.ts')));
+    assert.ok(await exists(join(appDir, 'app', 'features', 'rate-limit', 'ping', 'route.ts')));
+    assert.ok(await exists(join(appDir, 'app', 'features', 'rate-limit', 'ping', 'middleware.ts')));
+    assert.ok(await exists(join(appDir, 'app', 'features', 'file-storage', 'file', '[key]', 'route.ts')));
     // Feature/app logic lives in modules/, not app/.
     for (const name of MODULE_ROUTES) {
       assert.ok(await exists(join(appDir, 'modules', name)), `modules/${name}`);

From b140fb751a3cba261512177c3bd9634ed1d191c2 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 20:36:44 +0530
Subject: [PATCH 31/53] docs(cli): sync the single-theme token rule across all
 agent rule files

AGENTS.md carried the ONE-theme, shadcn-canonical token guidance; mirror a
concise form into CONVENTIONS.md and the per-agent rule files (.cursorrules,
copilot-instructions.md, .agents/rules/workflow.md) so every agent gets the
same rule in its own format. Also fix two stale invented-token references
(text-fg, bg-bg-elev) in CONVENTIONS.md examples that contradicted the rule.
---
 .../cli/templates/.agents/rules/workflow.md   | 15 +++++++++++
 packages/cli/templates/.cursorrules           |  1 +
 .../templates/.github/copilot-instructions.md |  1 +
 packages/cli/templates/CONVENTIONS.md         | 25 ++++++++++++++++---
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index 002b561b1..a4084cf44 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -155,6 +155,21 @@ self-review loop.
   gradients); when unavoidable in a light-DOM component, prefix every class
   selector with the component tag. Shadow-DOM components legitimately use
   `static styles = css\`...\`` for scoped CSS.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in
+  `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible)
+  semantic tokens set to the brand palette. Use the canonical utility names
+  everywhere, in the page chrome AND inside components: `bg-background`,
+  `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`,
+  `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`,
+  `border-border`, `ring-ring`. These are exactly the tokens a component copied
+  in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui
+  component share one theme with no wiring. NEVER invent a parallel token
+  vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it
+  collides with the ui tokens (the accent once flipped to neutral on navigation
+  for exactly this reason) and diverges from the shadcn conventions the kit and
+  AI agents expect. Reach for opacity modifiers (`bg-accent/10`,
+  `hover:bg-accent/90`) before adding a token; add one the canonical way (a
+  `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 8c2202713..45eadad68 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -131,6 +131,7 @@ self-review loop.
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index e14441ccc..05e90230e 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -128,6 +128,7 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index 784e36813..48c811c0d 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -714,7 +714,7 @@ export class MyWidget extends WebComponent({
   render() {
     return html`
       <div class="p-4 border border-border rounded-lg">
-        <p class="font-serif text-fg">${this.label}: ${this.count}</p>
+        <p class="font-serif text-foreground">${this.label}: ${this.count}</p>
       </div>
     `;
   }
@@ -774,8 +774,27 @@ Both hydrate without flash on the client.
 The scaffold ships with the **Tailwind CSS browser runtime** + `@theme`
 design tokens defined in the root layout. Every colour, font family,
 fluid type scale value, and motion duration is declared once in `@theme`
-and available everywhere via utility classes (`text-fg`, `bg-bg-elev`,
-`font-serif`, `duration-fast`, `text-display`).
+and available everywhere via utility classes (`text-foreground`,
+`bg-card`, `font-serif`, `duration-fast`, `text-display`).
+
+**One theme, canonical tokens.** The app has a SINGLE theme, defined
+once in `app/layout.ts` using the standard `@webjsdev/ui`
+(shadcn-compatible) semantic tokens set to the brand palette. Use the
+canonical utility names everywhere, in the page chrome AND inside
+components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`,
+`text-muted-foreground`, `bg-primary`, `text-primary-foreground`,
+`bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`.
+These are exactly the tokens a component copied in by
+`webjs ui add <name>` reads, so a scaffolded page and a later-added ui
+component share one coherent theme with no extra wiring. **Never invent a
+parallel token vocabulary** (`--fg`, `--bg`, `text-fg`, `bg-elev`, a
+separate `--brand`): it collides with the ui tokens (the accent once
+flipped to neutral on navigation for exactly this reason) and diverges
+from the shadcn conventions the kit and AI agents both expect. Reach for
+opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`,
+`text-muted-foreground/70`) before adding a token; to ADD one, do it the
+canonical way (a `--x` variable in the `:root` / `.dark` blocks plus a
+`--color-x: var(--x)` line in `@theme inline`, then `bg-x` / `text-x`).
 
 **Tailwind-first is the strong default for pages AND light-DOM
 components (the default DOM mode).** Use utilities for layout, spacing,

From 229c0ed455d1a3d387674ada6f4c6d90969efbea Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 20:43:17 +0530
Subject: [PATCH 32/53] test(server): update dev-handler docs URL assertion to
 webjs.dev

The docs-domain correction (da199148) changed the non-erasable-TS 500
message to point at docs.webjs.dev, but this assertion still matched the
old docs.webjs.com URL, so the DEV-mode test failed in CI. Match the
corrected domain.
---
 packages/server/test/dev/dev-handler.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/server/test/dev/dev-handler.test.js b/packages/server/test/dev/dev-handler.test.js
index 88323d278..0293fcf68 100644
--- a/packages/server/test/dev/dev-handler.test.js
+++ b/packages/server/test/dev/dev-handler.test.js
@@ -395,7 +395,7 @@ test('handle: .ts source with non-erasable TS returns 500 pointing at the lint r
   assert.match(body, /advanced\.ts/, 'body should name the offending file');
   assert.match(body, /no-non-erasable-typescript/, 'body should point at the lint rule');
   // #263: the error carries a stable, fetchable docs URL an agent can act on.
-  assert.match(body, /https:\/\/docs\.webjs\.com\/docs\/typescript/, 'body should anchor a docs URL');
+  assert.match(body, /https:\/\/docs\.webjs\.dev\/docs\/typescript/, 'body should anchor a docs URL');
 });
 
 test('handle: .ts source with non-erasable TS returns terse 500 in PROD (no filesystem path leak)', async () => {

From 2a0d59c6f0a661228a92119e06b083db8564d495 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 20:53:25 +0530
Subject: [PATCH 33/53] fix(cli): register the service worker at root /sw.js in
 the demo

The service-worker demo snippet registered '/public/sw.js', but a worker
must be registered at the site root to get whole-origin scope, matching
the canonical recipe in agent-docs/service-worker.md and the shipped
public/sw.js. Point the demo at '/sw.js'.
---
 .../cli/templates/gallery/app/features/service-worker/page.ts  | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/service-worker/page.ts b/packages/cli/templates/gallery/app/features/service-worker/page.ts
index aa2786dfa..e5113d458 100644
--- a/packages/cli/templates/gallery/app/features/service-worker/page.ts
+++ b/packages/cli/templates/gallery/app/features/service-worker/page.ts
@@ -22,7 +22,8 @@ export default function ServiceWorkerExample() {
     <pre class="bg-card border border-border rounded-xl p-4 overflow-x-auto text-sm font-mono mb-4"><code>connectedCallback() {
   super.connectedCallback();
   if ('serviceWorker' in navigator) {
-    navigator.serviceWorker.register('/public/sw.js');
+    // Register at the site root so the worker's scope is the whole origin.
+    navigator.serviceWorker.register('/sw.js');
   }
 }</code></pre>
     <p class="text-muted-foreground text-sm">

From 91473f865fafe0ed7f3344785faf29f5aa0b5d1c Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 20:56:19 +0530
Subject: [PATCH 34/53] feat(cli): showcase type-safe routes in the routing
 gallery demo

The [id] page typed its props with an inline { params: { id: string } }.
Use PageProps<'/features/routing/[id]'> instead so the demo shows webjs's
type-safe routing: webjs types generates a Route union and per-route
params, and PageProps<R> narrows params against it. Verified typecheck is
clean with the generated .webjs/routes.d.ts (21 routes typed).
---
 .../gallery/app/features/routing/[id]/page.ts     | 15 ++++++++++++++-
 .../gallery/app/features/routing/page.ts          | 10 +++++++++-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index b58ef8251..ee2cac89c 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -1,12 +1,25 @@
 // A dynamic route: `params.id` is the URL segment. The default export is a
 // (possibly async) function receiving { params, searchParams, url }; it runs
 // ONLY on the server. Throw notFound() / redirect() to short-circuit.
+//
+// Type-safe routes: instead of hand-typing `{ params: { id: string } }`, type
+// the props with PageProps<'<route>'>. `webjs types` (run automatically by
+// `webjs dev`) generates .webjs/routes.d.ts with a Route union and per-route
+// params, so PageProps<'/features/routing/[id]'>['params'] narrows to
+// { id: string } automatically. Rename the folder and the type follows; pass a
+// route literal that does not exist and it is a compile error.
 import { html } from '@webjsdev/core';
+import type { PageProps } from '@webjsdev/core';
 
-export default function RoutingParam({ params }: { params: { id: string } }) {
+export default function RoutingParam({ params }: PageProps<'/features/routing/[id]'>) {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route param</h1>
     <p>The <code>[id]</code> segment is: <strong>${params.id}</strong></p>
+    <p class="text-muted-foreground text-sm mt-3">
+      Typed with <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>,
+      so <code class="font-mono">params.id</code> is a checked
+      <code class="font-mono">string</code> from the generated route union.
+    </p>
     <p class="mt-3"><a class="text-accent" href="/features/routing">Back</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index e8981330c..1503db60f 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -11,9 +11,17 @@ export default function RoutingExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Routing</h1>
     <p class="text-muted-foreground mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
-    <ul class="list-disc pl-5">
+    <ul class="list-disc pl-5 mb-4">
       <li><a class="text-accent" href="/features/routing/42">/features/routing/42</a></li>
       <li><a class="text-accent" href="/features/routing/hello">/features/routing/hello</a></li>
     </ul>
+    <p class="text-muted-foreground text-sm">
+      Routes are type-safe: <code class="font-mono">webjs types</code> (run by
+      <code class="font-mono">webjs dev</code>) generates a
+      <code class="font-mono">Route</code> union, and the
+      <code class="font-mono">[id]</code> page types its props with
+      <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>
+      so <code class="font-mono">params</code> is checked against the real routes.
+    </p>
   `;
 }

From 4b6cf30810ce6c7fffdfb97bbf8aa182979246be Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 21:00:39 +0530
Subject: [PATCH 35/53] docs(cli): note navigate() route type-safety in the
 routing demo

Round out the type-safe routing story: navigate(url) is typed to the
generated Route union, so navigate('/random/42') is a compile error in
the editor and webjs typecheck. Also note the boundary that plain
<a href> strings are not checked, so navigate() is preferred for
internal links you want verified.
---
 .../templates/gallery/app/features/routing/page.ts   | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 1503db60f..181f7680c 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -15,7 +15,7 @@ export default function RoutingExample() {
       <li><a class="text-accent" href="/features/routing/42">/features/routing/42</a></li>
       <li><a class="text-accent" href="/features/routing/hello">/features/routing/hello</a></li>
     </ul>
-    <p class="text-muted-foreground text-sm">
+    <p class="text-muted-foreground text-sm mb-2">
       Routes are type-safe: <code class="font-mono">webjs types</code> (run by
       <code class="font-mono">webjs dev</code>) generates a
       <code class="font-mono">Route</code> union, and the
@@ -23,5 +23,15 @@ export default function RoutingExample() {
       <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>
       so <code class="font-mono">params</code> is checked against the real routes.
     </p>
+    <p class="text-muted-foreground text-sm">
+      Programmatic navigation is checked too:
+      <code class="font-mono">navigate(url)</code> takes that
+      <code class="font-mono">Route</code> union, so
+      <code class="font-mono">navigate('/random/42')</code> is a compile error in
+      your editor and <code class="font-mono">webjs typecheck</code>. (Plain
+      <code class="font-mono">&lt;a href&gt;</code> strings are not checked, so
+      prefer <code class="font-mono">navigate()</code> for internal links you want
+      verified.)
+    </p>
   `;
 }

From e6b40c11c0d2c4a6717be1c36f5f6ae292621db0 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 21:09:43 +0530
Subject: [PATCH 36/53] docs(cli): contrast navigate() vs redirect() in the
 routing demo

The routing demo mentioned each separately but never contrasted them.
Add a note: navigate() is the client-side soft nav from an event
handler, redirect() is thrown on the server to bail before render and
return a 3xx. Server side throw redirect(), client side call navigate().
---
 .../templates/gallery/app/features/routing/page.ts   | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 181f7680c..3beddcf4d 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -23,7 +23,7 @@ export default function RoutingExample() {
       <code class="font-mono">PageProps&lt;'/features/routing/[id]'&gt;</code>
       so <code class="font-mono">params</code> is checked against the real routes.
     </p>
-    <p class="text-muted-foreground text-sm">
+    <p class="text-muted-foreground text-sm mb-2">
       Programmatic navigation is checked too:
       <code class="font-mono">navigate(url)</code> takes that
       <code class="font-mono">Route</code> union, so
@@ -33,5 +33,15 @@ export default function RoutingExample() {
       prefer <code class="font-mono">navigate()</code> for internal links you want
       verified.)
     </p>
+    <p class="text-muted-foreground text-sm">
+      Changing route in code, two sides:
+      <code class="font-mono">navigate(url)</code> runs in the browser (a soft,
+      in-place client-router nav from an event handler, no reload), while
+      <code class="font-mono">redirect(url)</code> runs on the server (throw it in
+      a page or an <code class="font-mono">action</code> to bail before render and
+      return an HTTP 3xx). Throw
+      <code class="font-mono">redirect()</code> on the server, call
+      <code class="font-mono">navigate()</code> on the client.
+    </p>
   `;
 }

From 5e0c2db6b7ed32b03141b0c6cd2cc28a371c0ede Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 21:27:01 +0530
Subject: [PATCH 37/53] fix(cli): restore the --accent-tint token the theme
 rename dropped

The canonical-token refactor removed --accent-tint, but the footer logo
shadow (shadow-[...var(--accent-tint)]) and the theme-toggle focus ring
(ring-accent-tint) still referenced it, so the logo glow silently
rendered nothing and the focus ring fell back to currentColor. Define
--accent-tint once (derived from --accent via color-mix, so it tracks
light/dark) plus --color-accent-tint in @theme inline for the ring
utility. Verified in-browser: the footer shadow resolves to the accent
tint and .focus-visible:ring-accent-tint sets --tw-ring-color to it.
---
 packages/cli/lib/create.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 7afb65547..316844398 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1092,6 +1092,9 @@ ${UI_THEME}
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:  ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
         --header-h: 56px;
+        /* A translucent accent, derived from --accent so it tracks light/dark
+           automatically. Used for the logo glow and the focus ring tint. */
+        --accent-tint: color-mix(in oklch, var(--accent) 20%, transparent);
       }
       /* dark (the default, and the explicit .dark the toggle sets) */
       :root, .dark {
@@ -1172,6 +1175,7 @@ ${UI_THEME}
            already maps --color-background/foreground/card/primary/secondary/
            muted/accent/border/input/ring/destructive. */
         --color-border-strong: var(--border-strong);
+        --color-accent-tint: var(--accent-tint);
         --font-sans:  var(--font-sans);
         --font-serif: var(--font-serif);
         --font-mono:  var(--font-mono);

From b4ec34882aae1e30dbc26b1990f9c02976e542cc Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 21:54:53 +0530
Subject: [PATCH 38/53] feat(cli): give the api template a JSON root index
 instead of a 404

An api-template app has no UI, so GET / returned a bare 404, which reads
as broken when you first open the app. Add a root app/route.ts that
returns a JSON index of the available endpoints (health, users), the
common API-root convention.
---
 packages/cli/lib/create.js | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 316844398..225f1c6ff 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -829,6 +829,20 @@ export default cors({
     await writeFile(join(appDir, 'app', 'api', 'health', 'route.ts'), `export async function GET() {
   return Response.json({ status: 'ok', timestamp: Date.now() });
 }
+`);
+    // Root API index. The api template has no UI, so \`/\` is a route handler,
+    // not a page: it lists the available endpoints instead of returning a bare
+    // 404 (friendlier than an empty root for an API-only app).
+    await writeFile(join(appDir, 'app', 'route.ts'), `export async function GET(request: Request) {
+  const base = new URL(request.url).origin;
+  return Response.json({
+    name: '${name}',
+    endpoints: {
+      health: \`\${base}/api/health\`,
+      users: \`\${base}/api/users\`,
+    },
+  });
+}
 `);
     await mkdir(join(appDir, 'modules', 'users', 'actions'), { recursive: true });
     await mkdir(join(appDir, 'modules', 'users', 'queries'), { recursive: true });

From 05465e2e2e4ec2485c3d75639b45cd7b5ca5c996 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 22:04:34 +0530
Subject: [PATCH 39/53] fix(cli): use shadcn token roles (primary=brand,
 accent=neutral hover)

The scaffold used --accent as the brand color, the inverse of the shadcn
model @webjsdev/ui follows (primary = brand, accent = a neutral hover
tint). With a saturated orange accent and a dark accent-foreground, the
ui kit's outline/ghost/dropdown dark-mode hover became dark-on-dark and
unreadable (e.g. the saas dashboard Settings button).

Un-swap the roles: --primary is now the orange brand (primary buttons,
links, emphasis) and --accent falls back to the kit's neutral hover pair,
so hover states keep proper contrast. The gallery + chrome brand usages
move accent->primary (visually identical, orange preserved), the logo
glow + focus ring tint become --primary-tint, and ::selection uses the
brand. Verified in-browser: primary CTA is orange in both themes, links
are orange, and the dark outline hover is now light-on-dark (readable).
---
 packages/cli/lib/create.js                    | 61 +++++++++++--------
 .../gallery/app/features/caching/page.ts      |  2 +-
 .../app/features/client-router/page.ts        |  2 +-
 .../app/features/client-router/second/page.ts |  2 +-
 .../gallery/app/features/env/page.ts          |  4 +-
 .../gallery/app/features/file-storage/page.ts |  4 +-
 .../gallery/app/features/forms/page.ts        |  8 +--
 .../gallery/app/features/metadata/page.ts     |  6 +-
 .../app/features/optimistic-ui/page.ts        |  2 +-
 .../gallery/app/features/rate-limit/page.ts   |  2 +-
 .../app/features/route-handler/page.ts        |  2 +-
 .../gallery/app/features/routing/[id]/page.ts |  2 +-
 .../gallery/app/features/routing/page.ts      |  4 +-
 .../broadcast/components/broadcast-feed.ts    |  4 +-
 .../components/components/counter-card.ts     |  2 +-
 .../directives/components/directive-demo.ts   |  2 +-
 .../optimistic-ui/components/like-button.ts   |  2 +-
 .../rate-limit/components/rate-probe.ts       |  4 +-
 .../server-actions/components/greeter.ts      |  2 +-
 .../modules/todo/components/todo-app.ts       | 12 ++--
 .../modules/websockets/components/ws-echo.ts  |  4 +-
 packages/cli/templates/lib/utils/ui.ts        |  8 +--
 22 files changed, 74 insertions(+), 67 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 225f1c6ff..763014820 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -1096,19 +1096,23 @@ ${UI_THEME}
          added later with webjs ui add <name> inherits it automatically. This
          block is emitted after the ui theme, so these values win on every Tailwind
          recompile. Dark-first, with light via the theme toggle (data-theme) or the
-         OS. Edit the palette here. Add a new design token the canonical way, a
-         --x variable below plus a --color-x: var(--x) line in the @theme inline
-         block, then use it as bg-x / text-x. Reach for opacity modifiers
-         (bg-accent/10, hover:bg-accent/90, text-muted-foreground/70) before
+         OS. Follows the shadcn model: --primary is the BRAND color (orange, used
+         for primary buttons, links, and emphasis), while --accent stays a NEUTRAL
+         hover tint so the ui kit's outline/ghost/dropdown hover states keep proper
+         contrast. Use bg-primary / text-primary for brand, bg-accent for hovers.
+         Add a new design token the canonical way, a --x variable below plus a
+         --color-x: var(--x) line in the @theme inline block, then use it as bg-x /
+         text-x. Reach for opacity modifiers
+         (bg-primary/10, hover:bg-primary/90, text-muted-foreground/70) before
          inventing a new token. */
       :root {
         --font-sans:  -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         --font-serif: ui-serif, 'Iowan Old Style', Palatino, Georgia, serif;
         --font-mono:  ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
         --header-h: 56px;
-        /* A translucent accent, derived from --accent so it tracks light/dark
-           automatically. Used for the logo glow and the focus ring tint. */
-        --accent-tint: color-mix(in oklch, var(--accent) 20%, transparent);
+        /* A translucent brand tint, derived from --primary so it tracks
+           light/dark automatically. Used for the logo glow and focus ring. */
+        --primary-tint: color-mix(in oklch, var(--primary) 20%, transparent);
       }
       /* dark (the default, and the explicit .dark the toggle sets) */
       :root, .dark {
@@ -1119,14 +1123,17 @@ ${UI_THEME}
         --card-foreground: oklch(0.96 0.015 60);
         --popover: oklch(0.18 0.01 55);
         --popover-foreground: oklch(0.96 0.015 60);
-        --primary: oklch(0.922 0 0);
-        --primary-foreground: oklch(0.205 0 0);
+        /* --primary is the orange BRAND color (shadcn model: primary = brand). */
+        --primary: oklch(0.7 0.16 52);
+        --primary-foreground: oklch(0.17 0.02 52);
         --secondary: oklch(0.22 0.01 55);
         --secondary-foreground: oklch(0.96 0.015 60);
         --muted: oklch(0.16 0.01 55);
         --muted-foreground: oklch(0.72 0.02 60);
-        --accent: oklch(0.7 0.16 52);
-        --accent-foreground: oklch(0.17 0.02 52);
+        /* --accent stays a NEUTRAL hover tint (shadcn model), so the ui kit's
+           outline/ghost/dropdown hover states keep proper contrast. */
+        --accent: oklch(0.27 0.008 55);
+        --accent-foreground: oklch(0.96 0.015 60);
         --border: oklch(0.26 0.012 55 / 0.9);
         --border-strong: oklch(0.38 0.012 55 / 0.9);
         --input: oklch(0.26 0.012 55 / 0.9);
@@ -1143,14 +1150,14 @@ ${UI_THEME}
         --card-foreground: oklch(0.18 0.015 60);
         --popover: oklch(1 0 0);
         --popover-foreground: oklch(0.18 0.015 60);
-        --primary: oklch(0.205 0 0);
-        --primary-foreground: oklch(0.985 0 0);
+        --primary: oklch(0.54 0.16 52);
+        --primary-foreground: oklch(1 0 0);
         --secondary: oklch(0.96 0.008 80);
         --secondary-foreground: oklch(0.18 0.015 60);
         --muted: oklch(0.96 0.008 80);
         --muted-foreground: oklch(0.42 0.02 65);
-        --accent: oklch(0.54 0.16 52);
-        --accent-foreground: oklch(1 0 0);
+        --accent: oklch(0.955 0.006 80);
+        --accent-foreground: oklch(0.18 0.015 60);
         --border: oklch(0.88 0.01 75 / 0.95);
         --border-strong: oklch(0.78 0.01 75 / 0.95);
         --input: oklch(0.88 0.01 75 / 0.95);
@@ -1168,14 +1175,14 @@ ${UI_THEME}
           --card-foreground: oklch(0.18 0.015 60);
           --popover: oklch(1 0 0);
           --popover-foreground: oklch(0.18 0.015 60);
-          --primary: oklch(0.205 0 0);
-          --primary-foreground: oklch(0.985 0 0);
+          --primary: oklch(0.54 0.16 52);
+          --primary-foreground: oklch(1 0 0);
           --secondary: oklch(0.96 0.008 80);
           --secondary-foreground: oklch(0.18 0.015 60);
           --muted: oklch(0.96 0.008 80);
           --muted-foreground: oklch(0.42 0.02 65);
-          --accent: oklch(0.54 0.16 52);
-          --accent-foreground: oklch(1 0 0);
+          --accent: oklch(0.955 0.006 80);
+          --accent-foreground: oklch(0.18 0.015 60);
           --border: oklch(0.88 0.01 75 / 0.95);
           --border-strong: oklch(0.78 0.01 75 / 0.95);
           --input: oklch(0.88 0.01 75 / 0.95);
@@ -1189,7 +1196,7 @@ ${UI_THEME}
            already maps --color-background/foreground/card/primary/secondary/
            muted/accent/border/input/ring/destructive. */
         --color-border-strong: var(--border-strong);
-        --color-accent-tint: var(--accent-tint);
+        --color-primary-tint: var(--primary-tint);
         --font-sans:  var(--font-sans);
         --font-serif: var(--font-serif);
         --font-mono:  var(--font-mono);
@@ -1211,7 +1218,7 @@ ${UI_THEME}
         font: 16px/1.65 var(--font-sans);
         -webkit-font-smoothing: antialiased;
       }
-      ::selection { background: color-mix(in oklch, var(--accent) 22%, transparent); color: var(--foreground); }
+      ::selection { background: color-mix(in oklch, var(--primary) 22%, transparent); color: var(--foreground); }
     </style>
 
     <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--background)_75%,transparent)] backdrop-blur-[18px]">
@@ -1242,7 +1249,7 @@ ${UI_THEME}
         <div class="max-w-[760px] mx-auto px-4 sm:px-6 py-6 flex items-center justify-center">
           <a href="https://webjs.dev" class="inline-flex items-center gap-2 no-underline text-sm text-muted-foreground hover:text-foreground transition-colors">
             <span>Built with</span>
-            <span class="w-[18px] h-[18px] rounded-[6px] bg-gradient-to-br from-[var(--logo-from)] to-[var(--logo-to)] shadow-[0_2px_10px_var(--accent-tint)]"></span>
+            <span class="w-[18px] h-[18px] rounded-[6px] bg-gradient-to-br from-[var(--logo-from)] to-[var(--logo-to)] shadow-[0_2px_10px_var(--primary-tint)]"></span>
             <span class="font-semibold text-foreground">webjs</span>
           </a>
         </div>
@@ -1314,7 +1321,7 @@ export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
-      \${displayH1(html\`Hello from <span class="text-accent italic">${displayName}</span>.\`)}
+      \${displayH1(html\`Hello from <span class="text-primary italic">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
         This scaffold ships a gallery below: single-feature demos and one whole
         example app, all small, idiomatic, and heavily commented. Browse them for
@@ -1365,15 +1372,15 @@ export default function Home() {
   return html\`
     <section class="mb-14">
       \${rubric('welcome')}
-      \${displayH1(html\`Hello from <span class="text-accent italic">${displayName}</span>.\`)}
+      \${displayH1(html\`Hello from <span class="text-primary italic">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
         The saas starter: email and password auth, a protected dashboard, and a
         User model, all wired up. Replace this page with your product's landing.
         See \${accentLink('https://docs.webjs.dev', 'the docs')} for the full reference.
       </p>
       <div class="flex gap-3 items-center">
-        <a href="/login" class="inline-flex items-center px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm no-underline transition-all hover:bg-accent/90 active:scale-[0.97]">Log in</a>
-        <a href="/signup" class="text-accent no-underline font-medium text-sm">Create an account</a>
+        <a href="/login" class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm no-underline transition-all hover:bg-primary/90 active:scale-[0.97]">Log in</a>
+        <a href="/signup" class="text-primary no-underline font-medium text-sm">Create an account</a>
         <a href="/dashboard" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Dashboard</a>
       </div>
     </section>
@@ -1435,7 +1442,7 @@ export class ThemeToggle extends WebComponent {
     const icon = t === 'light' ? ICONS.sun : t === 'dark' ? ICONS.moon : ICONS.system;
     return html\`
       <button
-        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-card text-muted-foreground cursor-pointer transition-all duration-150 hover:text-foreground hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-accent focus-visible:ring-[3px] focus-visible:ring-accent-tint"
+        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-card text-muted-foreground cursor-pointer transition-all duration-150 hover:text-foreground hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-primary focus-visible:ring-[3px] focus-visible:ring-primary-tint"
         @click=\${() => this.cycle()}
         aria-label="Cycle theme (currently \${label})"
         title="Theme: \${label.toLowerCase()}"
diff --git a/packages/cli/templates/gallery/app/features/caching/page.ts b/packages/cli/templates/gallery/app/features/caching/page.ts
index 45eb16b51..3a5274c86 100644
--- a/packages/cli/templates/gallery/app/features/caching/page.ts
+++ b/packages/cli/templates/gallery/app/features/caching/page.ts
@@ -26,7 +26,7 @@ export default function CachingExample() {
     </p>
     <p class="mb-4">
       Rendered at
-      <code class="font-mono text-accent">${renderedAt}</code>.
+      <code class="font-mono text-primary">${renderedAt}</code>.
       Reload within 10s and this is unchanged; after 10s it re-renders.
     </p>
     <p class="text-muted-foreground text-sm">
diff --git a/packages/cli/templates/gallery/app/features/client-router/page.ts b/packages/cli/templates/gallery/app/features/client-router/page.ts
index 827129909..40087c04d 100644
--- a/packages/cli/templates/gallery/app/features/client-router/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/page.ts
@@ -21,7 +21,7 @@ export default function ClientRouterExample() {
       navigations. Nothing was imported to get this.
     </p>
     <div class="flex gap-3 items-center">
-      <a href="/features/client-router/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm no-underline transition-all hover:bg-accent/90 active:scale-[0.97]">Go to page two</a>
+      <a href="/features/client-router/second" class="inline-flex items-center px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm no-underline transition-all hover:bg-primary/90 active:scale-[0.97]">Go to page two</a>
       <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
     </div>
     <p class="text-muted-foreground text-sm mt-6">
diff --git a/packages/cli/templates/gallery/app/features/client-router/second/page.ts b/packages/cli/templates/gallery/app/features/client-router/second/page.ts
index c7204063c..fc55f9f06 100644
--- a/packages/cli/templates/gallery/app/features/client-router/second/page.ts
+++ b/packages/cli/templates/gallery/app/features/client-router/second/page.ts
@@ -15,6 +15,6 @@ export default function ClientRouterSecond() {
       the link below): the previous page and its scroll position are restored
       from the snapshot cache.
     </p>
-    <a href="/features/client-router" class="text-accent no-underline font-medium">&larr; Back to page one</a>
+    <a href="/features/client-router" class="text-primary no-underline font-medium">&larr; Back to page one</a>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/env/page.ts b/packages/cli/templates/gallery/app/features/env/page.ts
index 5f1589fca..83098110f 100644
--- a/packages/cli/templates/gallery/app/features/env/page.ts
+++ b/packages/cli/templates/gallery/app/features/env/page.ts
@@ -23,8 +23,8 @@ export default function EnvExample() {
       names are exposed to the browser; the rest stay server-side.
     </p>
     <ul class="list-disc pl-5 mb-4 space-y-1">
-      <li><code class="font-mono text-sm">NODE_ENV</code> = <span class="text-accent">${nodeEnv}</span> <span class="text-muted-foreground text-sm">(defined both sides)</span></li>
-      <li><code class="font-mono text-sm">WEBJS_PUBLIC_APP_NAME</code> = <span class="text-accent">${publicName}</span></li>
+      <li><code class="font-mono text-sm">NODE_ENV</code> = <span class="text-primary">${nodeEnv}</span> <span class="text-muted-foreground text-sm">(defined both sides)</span></li>
+      <li><code class="font-mono text-sm">WEBJS_PUBLIC_APP_NAME</code> = <span class="text-primary">${publicName}</span></li>
     </ul>
     <p class="text-muted-foreground text-sm">
       Never read a secret in a page, layout, or component that ships to the
diff --git a/packages/cli/templates/gallery/app/features/file-storage/page.ts b/packages/cli/templates/gallery/app/features/file-storage/page.ts
index 86416fa0d..98eab5cec 100644
--- a/packages/cli/templates/gallery/app/features/file-storage/page.ts
+++ b/packages/cli/templates/gallery/app/features/file-storage/page.ts
@@ -45,7 +45,7 @@ export default function FileStorageExample({
       <input type="file" name="file" required
         class="text-sm text-muted-foreground file:mr-3 file:px-3.5 file:py-2 file:rounded-xl file:border-0 file:bg-card file:border file:border-border file:text-foreground file:text-sm file:cursor-pointer" />
       <button type="submit"
-        class="px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Upload</button>
+        class="px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Upload</button>
     </form>
     ${actionData?.error
       ? html`<p class="text-destructive text-sm mb-4">${actionData.error}</p>`
@@ -55,7 +55,7 @@ export default function FileStorageExample({
         <div class="px-4 py-3 rounded-xl bg-card border border-border text-sm">
           Stored <span class="text-foreground font-medium">${name}</span>
           <span class="text-muted-foreground/70">(${size} bytes)</span>
-          <a class="text-accent no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
+          <a class="text-primary no-underline ml-2" href="/features/file-storage/file/${key}">download</a>
         </div>`
       : ''}
   `;
diff --git a/packages/cli/templates/gallery/app/features/forms/page.ts b/packages/cli/templates/gallery/app/features/forms/page.ts
index b6a5a7f97..c71f49beb 100644
--- a/packages/cli/templates/gallery/app/features/forms/page.ts
+++ b/packages/cli/templates/gallery/app/features/forms/page.ts
@@ -26,18 +26,18 @@ const field = (label: string, name: string, input: unknown, error?: string) => h
   </div>
 `;
 
-const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-accent placeholder:text-muted-foreground/70';
+const inputCls = 'w-full bg-background border border-border rounded-xl px-3 py-2 text-[15px] text-foreground outline-none transition-colors focus:border-primary placeholder:text-muted-foreground/70';
 
 export default function FormsFeature({ searchParams, actionData }: { searchParams: Record<string, string | undefined>; actionData?: Result }) {
   if (searchParams.sent) {
     return html`
       <h1 class="text-h2 font-bold mb-4">Forms</h1>
       <div class="max-w-[460px] grid gap-3 p-6 rounded-2xl bg-card border border-border text-center">
-        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
+        <span class="mx-auto grid place-items-center w-12 h-12 rounded-2xl bg-primary/15 text-primary">
           <svg viewBox="0 0 24 24" class="w-6 h-6 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
         </span>
         <p class="m-0 text-lg font-semibold text-foreground">Message sent</p>
-        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-accent" href="/features/forms">Send another</a>.</p>
+        <p class="m-0 text-sm text-muted-foreground">Thanks, we got it. <a class="text-primary" href="/features/forms">Send another</a>.</p>
       </div>
     `;
   }
@@ -50,7 +50,7 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
       ${field('Name', 'name', html`<input id="name" name="name" value=${v.name ?? ''} class=${inputCls} placeholder="Ada Lovelace" />`, errs.name)}
       ${field('Email', 'email', html`<input id="email" name="email" type="email" value=${v.email ?? ''} class=${inputCls} placeholder="ada@example.com" />`, errs.email)}
       ${field('Message', 'message', html`<textarea id="message" name="message" rows="3" class=${inputCls} placeholder="Say hello...">${v.message ?? ''}</textarea>`, errs.message)}
-      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send message</button>
+      <button type="submit" class="justify-self-start px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send message</button>
     </form>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/metadata/page.ts b/packages/cli/templates/gallery/app/features/metadata/page.ts
index 103c307b4..cf241810d 100644
--- a/packages/cli/templates/gallery/app/features/metadata/page.ts
+++ b/packages/cli/templates/gallery/app/features/metadata/page.ts
@@ -43,9 +43,9 @@ export default function MetadataExample({
       <code class="font-mono text-sm">${topic ? '?topic=' + topic : '(default, no ?topic=)'}</code>
     </p>
     <ul class="list-disc pl-5 mb-4">
-      <li><a class="text-accent" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
-      <li><a class="text-accent" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
-      <li><a class="text-accent" href="/features/metadata">clear the param</a></li>
+      <li><a class="text-primary" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
+      <li><a class="text-primary" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
+      <li><a class="text-primary" href="/features/metadata">clear the param</a></li>
     </ul>
     <p class="text-muted-foreground text-sm">
       Site-wide metadata (sitemap, robots, Open Graph images) lives in metadata
diff --git a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
index fbc6781d4..e512724df 100644
--- a/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
+++ b/packages/cli/templates/gallery/app/features/optimistic-ui/page.ts
@@ -8,7 +8,7 @@ export const metadata: Metadata = { title: 'Optimistic UI (imperative flip) | fe
 export default function OptimisticUiFeature() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Optimistic UI</h1>
-    <p class="text-muted-foreground mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-accent" href="/examples/todo">/examples/todo</a>.</p>
+    <p class="text-muted-foreground mb-4">The imperative <code>optimistic(signal, value, action)</code> form: the UI flips instantly and rolls back if the action fails. For the declarative list form (add / remove with rollback) in a full app, see <a class="text-primary" href="/examples/todo">/examples/todo</a>.</p>
     <like-button></like-button>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/rate-limit/page.ts b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
index 8b44cf6be..db7500df8 100644
--- a/packages/cli/templates/gallery/app/features/rate-limit/page.ts
+++ b/packages/cli/templates/gallery/app/features/rate-limit/page.ts
@@ -22,7 +22,7 @@ export default function RateLimitExample() {
     <rate-probe></rate-probe>
     <p class="text-muted-foreground text-sm mt-4">
       With JavaScript off, hit
-      <a class="text-accent" href="/features/rate-limit/ping">/features/rate-limit/ping</a>
+      <a class="text-primary" href="/features/rate-limit/ping">/features/rate-limit/ping</a>
       directly (refresh past five times in ten seconds).
     </p>
   `;
diff --git a/packages/cli/templates/gallery/app/features/route-handler/page.ts b/packages/cli/templates/gallery/app/features/route-handler/page.ts
index 55c1b13e4..627bb0446 100644
--- a/packages/cli/templates/gallery/app/features/route-handler/page.ts
+++ b/packages/cli/templates/gallery/app/features/route-handler/page.ts
@@ -8,6 +8,6 @@ export default function RouteHandlerExample() {
   return html`
     <h1 class="text-h2 font-bold mb-4">Route handlers</h1>
     <p class="text-muted-foreground mb-4">A <code>route.ts</code> is a server-only HTTP endpoint (named <code>GET</code>/<code>POST</code>/... exports), the webjs equivalent of a Next route handler. It never ships to the client.</p>
-    <p><a class="text-accent" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
+    <p><a class="text-primary" href="/features/route-handler/data">GET /features/route-handler/data</a> returns JSON.</p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
index ee2cac89c..2e9e7cc2b 100644
--- a/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/[id]/page.ts
@@ -20,6 +20,6 @@ export default function RoutingParam({ params }: PageProps<'/features/routing/[i
       so <code class="font-mono">params.id</code> is a checked
       <code class="font-mono">string</code> from the generated route union.
     </p>
-    <p class="mt-3"><a class="text-accent" href="/features/routing">Back</a></p>
+    <p class="mt-3"><a class="text-primary" href="/features/routing">Back</a></p>
   `;
 }
diff --git a/packages/cli/templates/gallery/app/features/routing/page.ts b/packages/cli/templates/gallery/app/features/routing/page.ts
index 3beddcf4d..7dfffa58e 100644
--- a/packages/cli/templates/gallery/app/features/routing/page.ts
+++ b/packages/cli/templates/gallery/app/features/routing/page.ts
@@ -12,8 +12,8 @@ export default function RoutingExample() {
     <h1 class="text-h2 font-bold mb-4">Routing</h1>
     <p class="text-muted-foreground mb-4">A folder is a URL segment; a <code>[id]</code> folder is a dynamic param.</p>
     <ul class="list-disc pl-5 mb-4">
-      <li><a class="text-accent" href="/features/routing/42">/features/routing/42</a></li>
-      <li><a class="text-accent" href="/features/routing/hello">/features/routing/hello</a></li>
+      <li><a class="text-primary" href="/features/routing/42">/features/routing/42</a></li>
+      <li><a class="text-primary" href="/features/routing/hello">/features/routing/hello</a></li>
     </ul>
     <p class="text-muted-foreground text-sm mb-2">
       Routes are type-safe: <code class="font-mono">webjs types</code> (run by
diff --git a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
index 15cc1731a..de6aae69c 100644
--- a/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
+++ b/packages/cli/templates/gallery/modules/broadcast/components/broadcast-feed.ts
@@ -40,14 +40,14 @@ export class BroadcastFeed extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex items-center gap-2 text-sm">
-          <span class="w-2 h-2 rounded-full ${on ? 'bg-accent' : 'bg-muted-foreground/40'}"></span>
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-primary' : 'bg-muted-foreground/40'}"></span>
           <span class="text-muted-foreground">${on ? 'in the room' : 'connecting (the live room needs JavaScript)'}</span>
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Message everyone"
             class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
           <button type="submit"
-            class="px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send</button>
+            class="px-3.5 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
diff --git a/packages/cli/templates/gallery/modules/components/components/counter-card.ts b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
index 34d313e9f..5f2084dda 100644
--- a/packages/cli/templates/gallery/modules/components/components/counter-card.ts
+++ b/packages/cli/templates/gallery/modules/components/components/counter-card.ts
@@ -27,7 +27,7 @@ export class CounterCard extends WebComponent({
           <span class="text-sm text-muted-foreground/70">${this.label}</span>
         </div>
         <button @click=${() => this.count.set(this.count.get() + 1)}
-          class="w-fit px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Increment</button>
+          class="w-fit px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Increment</button>
       </div>
     `;
   }
diff --git a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
index d8aa5f606..4851dd2d4 100644
--- a/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
+++ b/packages/cli/templates/gallery/modules/directives/components/directive-demo.ts
@@ -31,7 +31,7 @@ export class DirectiveDemo extends WebComponent {
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex gap-2">
           <button @click=${() => this.reverse()}
-            class="px-3.5 py-1.5 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Reverse</button>
+            class="px-3.5 py-1.5 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Reverse</button>
           <button @click=${() => this.add()}
             class="px-3.5 py-1.5 rounded-xl bg-card border border-border text-foreground font-medium text-sm cursor-pointer transition-colors hover:border-border-strong">Add</button>
         </div>
diff --git a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
index 70291d913..23222f321 100644
--- a/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
+++ b/packages/cli/templates/gallery/modules/optimistic-ui/components/like-button.ts
@@ -25,7 +25,7 @@ export class LikeButton extends WebComponent {
     const liked = this.liked.get();
     return html`
       <button @click=${() => this.toggle()} aria-pressed=${liked ? 'true' : 'false'}
-        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-accent text-accent-foreground border-accent' : 'bg-card text-foreground border-border hover:border-border-strong'}">
+        class="inline-flex items-center gap-2 px-4 py-2 rounded-full font-semibold text-sm border cursor-pointer transition-all active:scale-[0.97] ${liked ? 'bg-primary text-primary-foreground border-primary' : 'bg-card text-foreground border-border hover:border-border-strong'}">
         <svg viewBox="0 0 24 24" class="w-4 h-4 ${liked ? 'fill-current stroke-none' : 'fill-none stroke-current'}" style="stroke-width:2;stroke-linecap:round;stroke-linejoin:round"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.7l-1-1.1a5.5 5.5 0 0 0-7.8 7.8l1.1 1L12 21l7.7-7.6 1.1-1a5.5 5.5 0 0 0 0-7.8Z"/></svg>
         ${liked ? 'Liked' : 'Like'}
       </button>
diff --git a/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
index c413c5928..e6f785f26 100644
--- a/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
+++ b/packages/cli/templates/gallery/modules/rate-limit/components/rate-probe.ts
@@ -32,12 +32,12 @@ export class RateProbe extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <button @click=${() => this.ping()}
-          class="w-fit px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Ping the endpoint</button>
+          class="w-fit px-3.5 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Ping the endpoint</button>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.log.get().map((p) => html`
             <li class="flex items-center justify-between px-3 py-2 rounded-xl bg-card border border-border text-sm">
               <span class="text-muted-foreground">#${p.n}</span>
-              <span class="font-mono ${p.status === 429 ? 'text-destructive' : 'text-accent'}">${p.status === 429 ? '429 limited' : '200 ok'}</span>
+              <span class="font-mono ${p.status === 429 ? 'text-destructive' : 'text-primary'}">${p.status === 429 ? '429 limited' : '200 ok'}</span>
               <span class="text-muted-foreground/70 text-[13px]">remaining: ${p.remaining}</span>
             </li>
           `)}
diff --git a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
index 1d592c9f2..bc7b6b083 100644
--- a/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
+++ b/packages/cli/templates/gallery/modules/server-actions/components/greeter.ts
@@ -20,7 +20,7 @@ export class Greeter extends WebComponent {
           <input name="name" placeholder="your name" autocomplete="off"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
           <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Greet</button>
+            class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Greet</button>
         </form>
         ${this.msg.get() ? html`<p class="m-0 font-semibold text-foreground">${this.msg.get()}</p>` : ''}
       </div>
diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 0cf0ed9a8..0929457e4 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -5,10 +5,10 @@
 // component; a page/layout cannot be interactive in its own markup.
 //
 // Styling uses the shadcn-standard design tokens the @webjsdev/ui theme defines
-// (bg-card, text-foreground, bg-accent, text-muted-foreground, border-border,
+// (bg-card, text-foreground, bg-primary, text-muted-foreground, border-border,
 // ...), so the whole app (this component AND any `webjs ui add` component) shares
 // one coherent theme. Prefer these tokens (and opacity modifiers like
-// bg-accent/90) over ad-hoc colors.
+// bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
@@ -77,7 +77,7 @@ export class TodoApp extends WebComponent({
         <!-- Header: a title, a live done/total count, and a progress bar. -->
         <header class="grid gap-3">
           <div class="flex items-center gap-3">
-            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-accent/15 text-accent shrink-0">
+            <span class="grid place-items-center w-10 h-10 rounded-2xl bg-primary/15 text-primary shrink-0">
               <svg viewBox="0 0 24 24" class="w-5 h-5 stroke-current fill-none" style="stroke-width:2.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
             </span>
             <div class="grid gap-0.5">
@@ -87,7 +87,7 @@ export class TodoApp extends WebComponent({
             <span class="ml-auto text-[13px] font-semibold tabular-nums text-muted-foreground">${pct}%</span>
           </div>
           <div class="h-1.5 rounded-full bg-muted overflow-hidden">
-            <div class="h-full rounded-full bg-accent transition-[width] duration-300" style="width:${pct}%"></div>
+            <div class="h-full rounded-full bg-primary transition-[width] duration-300" style="width:${pct}%"></div>
           </div>
         </header>
 
@@ -99,7 +99,7 @@ export class TodoApp extends WebComponent({
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
           <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Add</button>
+            class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">
@@ -115,7 +115,7 @@ export class TodoApp extends WebComponent({
                   aria-pressed=${todo.completed ? 'true' : 'false'}
                   aria-label=${todo.completed ? 'Mark as not done' : 'Mark as done'}
                   @click=${(e: Event) => this.toggle(e, todo)}
-                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-accent border-accent text-accent-foreground' : 'bg-transparent border-border-strong text-transparent hover:border-accent'}">
+                  class="shrink-0 grid place-items-center w-5 h-5 rounded-full border-2 cursor-pointer transition-all ${todo.completed ? 'bg-primary border-primary text-primary-foreground' : 'bg-transparent border-border-strong text-transparent hover:border-primary'}">
                   <svg viewBox="0 0 24 24" class="w-3 h-3 stroke-current fill-none" style="stroke-width:3.4;stroke-linecap:round;stroke-linejoin:round"><path d="m5 13 4 4L19 7"/></svg>
                 </button>
                 <!-- The title is a <label for> the toggle: clicking the text toggles
diff --git a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
index 1e4678f2e..48525b653 100644
--- a/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
+++ b/packages/cli/templates/gallery/modules/websockets/components/ws-echo.ts
@@ -41,14 +41,14 @@ export class WsEcho extends WebComponent {
     return html`
       <div class="grid gap-4 max-w-[420px]">
         <div class="flex items-center gap-2 text-sm">
-          <span class="w-2 h-2 rounded-full ${on ? 'bg-accent' : 'bg-muted-foreground/40'}"></span>
+          <span class="w-2 h-2 rounded-full ${on ? 'bg-primary' : 'bg-muted-foreground/40'}"></span>
           <span class="text-muted-foreground">${on ? 'connected' : 'connecting (live echo needs JavaScript)'}</span>
         </div>
         <form @submit=${(e: SubmitEvent) => this.send(e)} class="flex gap-2">
           <input name="msg" autocomplete="off" placeholder="Say something"
             class="flex-1 px-3 py-2 rounded-xl bg-card border border-border text-foreground text-sm outline-none focus:border-border-strong" />
           <button type="submit"
-            class="px-3.5 py-2 rounded-xl bg-accent text-accent-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-accent/90 active:scale-[0.97]">Send</button>
+            class="px-3.5 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Send</button>
         </form>
         <ul class="grid gap-1.5 list-none m-0 p-0">
           ${this.lines.get().map((line) => html`
diff --git a/packages/cli/templates/lib/utils/ui.ts b/packages/cli/templates/lib/utils/ui.ts
index 5e70432af..f3faa7a2d 100644
--- a/packages/cli/templates/lib/utils/ui.ts
+++ b/packages/cli/templates/lib/utils/ui.ts
@@ -16,11 +16,11 @@
  */
 import { html } from '@webjsdev/core';
 
-/** `● label` kicker: small caps, accent colour, above headings. */
+/** `● label` kicker: small caps, brand colour, above headings. */
 export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
   const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
   return html`
-    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-accent ${mbCls}">● ${label}</span>
+    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-primary ${mbCls}">● ${label}</span>
   `;
 }
 
@@ -68,10 +68,10 @@ export function banner(content: unknown) {
   `;
 }
 
-/** Inline accent link: used inside body copy and banners. */
+/** Inline brand link: used inside body copy and banners. */
 export function accentLink(href: string, label: unknown) {
   return html`
-    <a href=${href} class="text-accent font-semibold no-underline hover:underline hover:underline-offset-[3px]">${label}</a>
+    <a href=${href} class="text-primary font-semibold no-underline hover:underline hover:underline-offset-[3px]">${label}</a>
   `;
 }
 

From 76048b9413390820a63fe61219e302f684803df2 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 22:05:34 +0530
Subject: [PATCH 40/53] docs(cli): update brand-tint token examples to primary
 in rule files

Follow the primary=brand / accent=neutral-hover token roles: the
opacity-modifier examples now show bg-primary/10 and hover:bg-primary/90
for a brand tint (bg-accent stays in the canonical token list as the
neutral hover token).
---
 packages/cli/templates/.agents/rules/workflow.md       | 4 ++--
 packages/cli/templates/.cursorrules                    | 2 +-
 packages/cli/templates/.github/copilot-instructions.md | 2 +-
 packages/cli/templates/AGENTS.md                       | 4 ++--
 packages/cli/templates/CONVENTIONS.md                  | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index a4084cf44..73f39778e 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -167,8 +167,8 @@ self-review loop.
   vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it
   collides with the ui tokens (the accent once flipped to neutral on navigation
   for exactly this reason) and diverges from the shadcn conventions the kit and
-  AI agents expect. Reach for opacity modifiers (`bg-accent/10`,
-  `hover:bg-accent/90`) before adding a token; add one the canonical way (a
+  AI agents expect. Reach for opacity modifiers (`bg-primary/10`,
+  `hover:bg-primary/90`) before adding a token; add one the canonical way (a
   `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 45eadad68..686e77fd1 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -131,7 +131,7 @@ self-review loop.
 - No build step: source files are served as ES modules
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
-- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 05e90230e..87673e849 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -128,7 +128,7 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
-- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index ec491e167..624297a83 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -818,8 +818,8 @@ page and a later-added ui component share one coherent theme automatically.
   `bg-elev`, a separate `--brand`). It collides with the ui tokens (the accent
   once flipped to neutral on navigation for exactly this reason) and diverges
   from the shadcn conventions the ui kit and AI agents both expect.
-- **Reach for opacity modifiers before a new token**: `bg-accent/10` for a
-  tint, `hover:bg-accent/90` for a hover, `text-muted-foreground/70` for a
+- **Reach for opacity modifiers before a new token**: `bg-primary/10` for a
+  tint, `hover:bg-primary/90` for a hover, `text-muted-foreground/70` for a
   subtler text level.
 - **Edit the palette in one place** (`app/layout.ts`). To ADD a token, do it
   the canonical way: a `--x` variable in the `:root` / `.dark` blocks plus a
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index 48c811c0d..0d5da9abd 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -791,7 +791,7 @@ parallel token vocabulary** (`--fg`, `--bg`, `text-fg`, `bg-elev`, a
 separate `--brand`): it collides with the ui tokens (the accent once
 flipped to neutral on navigation for exactly this reason) and diverges
 from the shadcn conventions the kit and AI agents both expect. Reach for
-opacity modifiers (`bg-accent/10`, `hover:bg-accent/90`,
+opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`,
 `text-muted-foreground/70`) before adding a token; to ADD one, do it the
 canonical way (a `--x` variable in the `:root` / `.dark` blocks plus a
 `--color-x: var(--x)` line in `@theme inline`, then `bg-x` / `text-x`).

From ad903a7cbc5384a54ffe0ab673ad6ff7b0ade792 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 23:03:12 +0530
Subject: [PATCH 41/53] feat(cli): ship the feature gallery in the saas
 template too

The gallery is webjs-idiom learning material (components, server actions,
optimistic UI, routing, etc.), just as relevant when building a saas app.
Only the api template (no UI) omits it. copyGallery now runs for every UI
template (!isApi). The saas home keeps its auth landing hero and shows the
Features + Example apps gallery below it, and the saas schema carries both
the auth users table and the gallery todos table so the todo example runs.
Verified in a generated saas app: home shows auth + gallery, every feature
route and /examples/todo serve 200, auth is intact, webjs check clean.
---
 packages/cli/lib/create.js                    | 76 ++++++++++++++++++-
 packages/cli/lib/saas-template.js             | 13 +++-
 packages/cli/templates/.cursorrules           |  2 +-
 .../templates/.github/copilot-instructions.md |  2 +-
 packages/cli/templates/CONVENTIONS.md         |  2 +-
 test/scaffolds/scaffold-gallery.test.js       | 52 +++++++++----
 6 files changed, 125 insertions(+), 22 deletions(-)

diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 763014820..7d028270a 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -981,7 +981,7 @@ export type ActionResult<T> =
     // scaffold so an agent gains context by browsing real code; prune
     // per-feature (delete the route + its module) for what the app does not
     // use. See CONVENTIONS.md "prune what the app does not use".
-    if (isFullStack) await copyGallery(appDir);
+    if (!isApi) await copyGallery(appDir);
 
     // The @webjsdev/ui theme tokens (`--color-primary`, `--color-card`, …) the
     // ui-* components consume. We read the registry's themes/index.css at
@@ -1358,16 +1358,62 @@ export default function Home() {
 }
 `);
   } else {
-    // saas landing: the app has auth + a dashboard, so link those instead of a
-    // gallery it does not ship.
+    // saas home: the auth landing (hero + login/signup/dashboard) stays the
+    // headline, and the webjs feature gallery sits BELOW it, so a saas app is
+    // also a learning surface. Keep the `features` list in sync with the
+    // full-stack home above (both ship the same gallery).
     await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real landing page, then delete this line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
 import { rubric, displayH1, accentLink } from '#lib/utils/ui.ts';
+import {
+  cardClass,
+  cardHeaderClass,
+  cardTitleClass,
+  cardDescriptionClass,
+} from '#components/ui/card.ts';
 
 export const metadata = {
   title: '${displayName}: built with webjs',
 };
 
+// The webjs feature gallery, shown below the auth landing. FEATURES are
+// single-concept demos (under app/features/, logic in modules/); EXAMPLES are
+// whole apps (under app/examples/). Prune what you do not use (delete the route
+// AND its modules/<name>). Keep this list in sync with the full-stack home.
+const features = [
+  { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
+  { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
+  { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
+  { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
+  { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+  { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
+  { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the webjs equivalent of a Next route handler.' },
+  { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
+  { href: '/features/metadata', title: 'Metadata', blurb: 'Static metadata plus generateMetadata(ctx), which reads the request to compute the title and Open Graph tags.' },
+  { href: '/features/caching', title: 'Caching', blurb: 'export const revalidate caches the page HTML per URL, with the safety rule for when a shared cache is allowed.' },
+  { href: '/features/env', title: 'Env vars', blurb: 'The server-only vs WEBJS_PUBLIC_ boundary, read during SSR so secrets never reach the browser.' },
+  { href: '/features/client-router', title: 'Client router', blurb: 'Automatic soft navigation: fragment-only fetches, hover prefetch, scroll restore, and graceful no-JS fallback.' },
+  { href: '/features/service-worker', title: 'Service worker', blurb: 'The opt-in offline enhancement, registered from a browser-only lifecycle hook (never a page or layout).' },
+  { href: '/features/websockets', title: 'WebSockets', blurb: 'A WS(ws, req) route endpoint plus the connectWS() client, echoing messages over a live socket.' },
+  { href: '/features/broadcast', title: 'Broadcast', blurb: 'Fan a message out to every connected client on a WebSocket path, so all open tabs stay in sync.' },
+  { href: '/features/rate-limit', title: 'Rate limiting', blurb: 'The rateLimit() middleware scoped to one endpoint, returning a 429 with Retry-After past the window.' },
+  { href: '/features/file-storage', title: 'File storage', blurb: 'A no-JS multipart upload streamed into the FileStore, then served back through a streaming route.' },
+];
+const examples = [
+  { href: '/examples/todo', title: 'Optimistic todo', blurb: 'A whole app composing several features: the declarative optimistic() list API, progressive-enhancement forms, accessible labels, the modules split, and SQLite.' },
+];
+
+const galleryCard = (item: { href: string; title: string; blurb: string }) => html\`
+  <a href=\${item.href} class="block no-underline">
+    <div class="\${cardClass()} h-full transition-colors hover:border-border-strong">
+      <div class=\${cardHeaderClass()}>
+        <h3 class=\${cardTitleClass()}>\${item.title}</h3>
+        <p class=\${cardDescriptionClass()}>\${item.blurb}</p>
+      </div>
+    </div>
+  </a>
+\`;
+
 export default function Home() {
   return html\`
     <section class="mb-14">
@@ -1375,7 +1421,8 @@ export default function Home() {
       \${displayH1(html\`Hello from <span class="text-primary italic">${displayName}</span>.\`)}
       <p class="text-lede leading-[1.5] text-muted-foreground max-w-[56ch] m-0 mb-6">
         The saas starter: email and password auth, a protected dashboard, and a
-        User model, all wired up. Replace this page with your product's landing.
+        User model, all wired up. Replace this hero with your product's landing;
+        the webjs feature gallery below is reference, prune what you do not need.
         See \${accentLink('https://docs.webjs.dev', 'the docs')} for the full reference.
       </p>
       <div class="flex gap-3 items-center">
@@ -1384,6 +1431,27 @@ export default function Home() {
         <a href="/dashboard" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Dashboard</a>
       </div>
     </section>
+
+    <section class="mb-12">
+      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Features</h2>
+      <p class="text-muted-foreground text-sm m-0 mb-5">
+        One webjs concept each, under <code class="font-mono text-[0.9em]">app/features/</code>
+        with logic in <code class="font-mono text-[0.9em]">modules/</code>. Delete the ones you do not need.
+      </p>
+      <div class="grid gap-4 sm:grid-cols-2">
+        \${features.map(galleryCard)}
+      </div>
+    </section>
+
+    <section>
+      <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 mb-1">Example apps</h2>
+      <p class="text-muted-foreground text-sm m-0 mb-5">
+        Whole apps that compose several features, under <code class="font-mono text-[0.9em]">app/examples/</code>.
+      </p>
+      <div class="grid gap-4 sm:grid-cols-2">
+        \${examples.map(galleryCard)}
+      </div>
+    </section>
   \`;
 }
 `);
diff --git a/packages/cli/lib/saas-template.js b/packages/cli/lib/saas-template.js
index ea296686c..aec13bba9 100644
--- a/packages/cli/lib/saas-template.js
+++ b/packages/cli/lib/saas-template.js
@@ -106,7 +106,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
   // add passwordHash (the column auth needs). Drizzle, dialect-agnostic.
   await writeFile(join(appDir, 'db', 'schema.server.ts'), [
     "import { defineRelations } from 'drizzle-orm';",
-    "import { table, pk, text, createdAt } from './columns.server.ts';",
+    "import { table, pk, uuidPk, text, bool, createdAt } from './columns.server.ts';",
     "",
     "export const users = table('users', {",
     "  id: pk(),",
@@ -116,7 +116,16 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  createdAt: createdAt(),",
     "});",
     "",
-    "export const relations = defineRelations({ users }, () => ({}));",
+    "// Backs the example-gallery /examples/todo route (modules/todo). Delete it",
+    "// with the gallery when you prune the examples you do not use.",
+    "export const todos = table('todos', {",
+    "  id: uuidPk(),",
+    "  title: text().notNull(),",
+    "  completed: bool().notNull().default(false),",
+    "  createdAt: createdAt(),",
+    "});",
+    "",
+    "export const relations = defineRelations({ users, todos }, () => ({}));",
     "",
     "export type User = typeof users.$inferSelect;",
     "",
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index 686e77fd1..f2b63d5e2 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -18,7 +18,7 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **Study the gallery first, prune it second.** The full-stack scaffold ships
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
   single-feature demos under `app/features/` plus one whole example app under
   `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
   read every demo end to end (code AND comments) to learn the idioms BEFORE you
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 87673e849..f4ccd62f8 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -18,7 +18,7 @@ the full hosted docs are at **https://docs.webjs.dev**.
   `app/page.ts`, the example `User` model, the example users module, etc.
   with the app the user actually asked for. Don't ship "Hello from
   <app-name>" as the deliverable.
-- **Study the gallery first, prune it second.** The full-stack scaffold ships
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
   single-feature demos under `app/features/` plus one whole example app under
   `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
   read every demo end to end (code AND comments) to learn the idioms BEFORE you
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index 0d5da9abd..663cc85bc 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -315,7 +315,7 @@ now (the `app/page.ts` homepage, the example `User` model, the
 `app/examples/` in the full-stack template, the example users module in
 api / saas templates) is a **starting point**.
 
-The full-stack scaffold ships a **gallery** organized by kind so features
+The full-stack and saas scaffolds ship a **gallery** organized by kind so features
 and whole apps are not mixed. `app/features/<name>/` are single-feature
 demos, one webjs concept each (routing, components, server-actions,
 optimistic-ui, async-render, directives, route-handler). `app/examples/<name>/`
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index c1b36c2c7..59e7084ec 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -163,19 +163,45 @@ test('feature pages have no stale /examples/ links after the features refactor',
   }
 });
 
-test('api and saas do NOT ship the gallery (full-stack only)', async () => {
-  for (const template of ['api', 'saas']) {
-    const cwd = await tempCwd();
-    try {
-      await scaffoldApp('demo', cwd, { template });
-      const appDir = join(cwd, 'demo');
-      assert.equal(existsSync(join(appDir, 'app', 'features')), false, `${template} must not ship app/features`);
-      assert.equal(existsSync(join(appDir, 'app', 'examples')), false, `${template} must not ship app/examples`);
-      assert.equal(existsSync(join(appDir, 'modules', 'todo')), false, `${template} must not ship the todo module`);
-      const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
-      assert.doesNotMatch(schema, /table\('todos'/, `${template} schema must not add the gallery todos table`);
-    } finally {
-      await rm(cwd, { recursive: true, force: true });
+test('the api template does NOT ship the gallery (no UI)', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'api' });
+    const appDir = join(cwd, 'demo');
+    assert.equal(existsSync(join(appDir, 'app', 'features')), false, 'api must not ship app/features');
+    assert.equal(existsSync(join(appDir, 'app', 'examples')), false, 'api must not ship app/examples');
+    assert.equal(existsSync(join(appDir, 'modules', 'todo')), false, 'api must not ship the todo module');
+    const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
+    assert.doesNotMatch(schema, /table\('todos'/, 'api schema must not add the gallery todos table');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('the saas template ships the gallery AND keeps its auth example', async () => {
+  const cwd = await tempCwd();
+  try {
+    await scaffoldApp('demo', cwd, { template: 'saas' });
+    const appDir = join(cwd, 'demo');
+    // The full webjs feature gallery ships below the auth landing.
+    for (const name of FEATURES) {
+      assert.ok(await exists(join(appDir, 'app', 'features', name, 'page.ts')), `saas app/features/${name}/page.ts`);
     }
+    assert.ok(await exists(join(appDir, 'app', 'examples', 'todo', 'page.ts')), 'saas todo example');
+    assert.ok(await exists(join(appDir, 'modules', 'todo')), 'saas todo module');
+    // The saas schema carries BOTH the auth users table and the gallery todos table.
+    const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
+    assert.match(schema, /table\('users'/, 'saas keeps the auth users table');
+    assert.match(schema, /passwordHash/, 'saas users table keeps the auth column');
+    assert.match(schema, /table\('todos'/, 'saas adds the gallery todos table');
+    // The auth example is intact.
+    assert.ok(await exists(join(appDir, 'app', 'login', 'page.ts')), 'saas keeps login');
+    assert.ok(await exists(join(appDir, 'app', 'dashboard', 'page.ts')), 'saas keeps the dashboard');
+    // The saas home shows both the auth CTAs and the gallery.
+    const home = await readFile(join(appDir, 'app', 'page.ts'), 'utf8');
+    assert.match(home, /\/login/, 'saas home keeps the auth CTA');
+    assert.match(home, /\/features\/routing/, 'saas home links the gallery');
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
   }
 });

From d8209ef962ec237d8bcc6544313b4b9567495439 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 23:13:26 +0530
Subject: [PATCH 42/53] feat(cli): add a backend-features showcase to the api
 template

The UI gallery does not fit the api template (no pages/components), but an
API app should still learn webjs's backend surface. Add a showcase of JSON
endpoints under app/api/features/: the route() adapter + input validation,
rate limiting, a streaming NDJSON response, file storage (upload + serve),
and a WebSocket endpoint with broadcast, plus a boot-time env.ts validation
example. The root app/route.ts index lists them. Each demo carries a
webjs-scaffold-placeholder marker. Verified in a generated api app: validate
422s bad input, rate-limit 429s past the window, stream arrives incrementally,
file upload round-trips, WS broadcasts A to B, webjs check + typecheck clean.
---
 packages/cli/lib/api-gallery.js               | 193 ++++++++++++++++++
 packages/cli/lib/create.js                    |  15 ++
 packages/cli/templates/.cursorrules           |   6 +-
 .../templates/.github/copilot-instructions.md |   6 +-
 test/scaffolds/scaffold-gallery.test.js       |  19 +-
 5 files changed, 233 insertions(+), 6 deletions(-)
 create mode 100644 packages/cli/lib/api-gallery.js

diff --git a/packages/cli/lib/api-gallery.js b/packages/cli/lib/api-gallery.js
new file mode 100644
index 000000000..1406993be
--- /dev/null
+++ b/packages/cli/lib/api-gallery.js
@@ -0,0 +1,193 @@
+/**
+ * Backend-features showcase for `webjs create --template api`.
+ * A set of JSON/HTTP endpoints under `app/api/features/` that demonstrate the
+ * backend capabilities an API app uses (the api counterpart of the UI gallery).
+ * Extracted here (like saas-template.js) to keep create.js readable and dodge
+ * nested-template-literal escaping: files are built from arrays of
+ * double-quoted strings, so `${...}` and backticks are emitted literally.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Write the api backend-features gallery into `<appDir>/app/api/features/**`
+ * plus a boot-time env-validation example at `app/env.ts`. Each demo carries a
+ * `webjs-scaffold-placeholder` marker so `webjs check` fails until it is
+ * pruned or adapted.
+ * @param {string} appDir
+ */
+export async function writeApiGallery(appDir) {
+  const feat = (...p) => join(appDir, 'app', 'api', 'features', ...p);
+
+  // 1) route() adapter + input validation.
+  await mkdir(join(appDir, 'modules', 'widgets', 'actions'), { recursive: true });
+  await writeFile(join(appDir, 'modules', 'widgets', 'actions', 'create-widget.server.ts'), [
+    "'use server';",
+    "",
+    "// A plain 'use server' mutation. Exposed over REST by the route() adapter in",
+    "// app/api/features/validate/route.ts, which merges the query + params + JSON",
+    "// body into one input, runs the boundary validator, and JSON-responds.",
+    "export async function createWidget(input: { name: string }) {",
+    "  return { id: crypto.randomUUID(), name: input.name, createdAt: new Date().toISOString() };",
+    "}",
+    "",
+  ].join('\n'));
+  await mkdir(feat('validate'), { recursive: true });
+  await writeFile(feat('validate', 'route.ts'), [
+    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/validate route AND modules/widgets), then delete this marker line. webjs check fails while the marker remains.",
+    "// route() turns a 'use server' action into a REST endpoint: it merges the URL",
+    "// query, route params, and JSON body into one input, runs `validate` at the",
+    "// boundary (a { success:false, fieldErrors } return is a 422, no action call),",
+    "// then JSON-responds the result. POST { \"name\": \"Gadget\" } to try it.",
+    "import { route } from '@webjsdev/server';",
+    "import { createWidget } from '#modules/widgets/actions/create-widget.server.ts';",
+    "",
+    "const validate = (input: { name?: unknown }) => {",
+    "  const name = typeof input?.name === 'string' ? input.name.trim() : '';",
+    "  if (!name) return { success: false as const, fieldErrors: { name: 'name is required' } };",
+    "  return { success: true as const, data: { name } };",
+    "};",
+    "",
+    "export const POST = route(createWidget, { validate });",
+    "",
+  ].join('\n'));
+
+  // 2) Rate limiting (middleware scoped to this endpoint).
+  await mkdir(feat('rate-limit'), { recursive: true });
+  await writeFile(feat('rate-limit', 'middleware.ts'), [
+    "// Per-segment middleware: it sits beside this route, so it rate-limits ONLY",
+    "// /api/features/rate-limit. rateLimit() is backed by the pluggable cache store",
+    "// (in-memory by default; point it at Redis to share the window across nodes).",
+    "import { rateLimit } from '@webjsdev/server';",
+    "",
+    "export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });",
+    "",
+  ].join('\n'));
+  await writeFile(feat('rate-limit', 'route.ts'), [
+    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/rate-limit route), then delete this marker line. webjs check fails while the marker remains.",
+    "// The middleware.ts beside this file stamps X-RateLimit-* headers and returns",
+    "// a 429 with Retry-After once the window is exhausted, so this handler never",
+    "// runs on a limited request. Call it six times in ten seconds to see the 429.",
+    "export async function GET() {",
+    "  return Response.json({ ok: true, at: new Date().toISOString() });",
+    "}",
+    "",
+  ].join('\n'));
+
+  // 3) Streaming response (chunks flushed as produced, no buffering).
+  await mkdir(feat('stream'), { recursive: true });
+  await writeFile(feat('stream', 'route.ts'), [
+    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/stream route), then delete this marker line. webjs check fails while the marker remains.",
+    "// Streams NDJSON chunks as they are produced, so a slow or large result is",
+    "// delivered incrementally instead of buffered whole. A hand-written route.ts",
+    "// returns a ReadableStream for full control; `curl -N` shows the lines arrive",
+    "// one at a time.",
+    "export async function GET() {",
+    "  const encoder = new TextEncoder();",
+    "  const stream = new ReadableStream({",
+    "    async start(controller) {",
+    "      for (let i = 1; i <= 5; i++) {",
+    "        controller.enqueue(encoder.encode(JSON.stringify({ n: i, at: new Date().toISOString() }) + '\\n'));",
+    "        await new Promise((r) => setTimeout(r, 200));",
+    "      }",
+    "      controller.close();",
+    "    },",
+    "  });",
+    "  return new Response(stream, { headers: { 'content-type': 'application/x-ndjson' } });",
+    "}",
+    "",
+  ].join('\n'));
+
+  // 4) File storage (upload + serve), both hand-written route.ts.
+  await mkdir(feat('files', '[key]'), { recursive: true });
+  await writeFile(feat('files', 'route.ts'), [
+    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/files route), then delete this marker line. webjs check fails while the marker remains.",
+    "// POST a multipart file: the bytes stream into the FileStore (a local",
+    "// .webjs/uploads dir by default, gitignored; swap for S3/R2 with one",
+    "// setFileStore() call). Returns the key + a URL served by [key]/route.ts.",
+    "// Try: curl -F file=@README.md http://localhost:8080/api/features/files",
+    "import { getFileStore, generateKey } from '@webjsdev/server';",
+    "",
+    "export async function POST(req: Request) {",
+    "  const form = await req.formData();",
+    "  const file = form.get('file');",
+    "  if (!(file instanceof File) || file.size === 0) {",
+    "    return Response.json({ error: 'no file provided' }, { status: 400 });",
+    "  }",
+    "  const key = generateKey(file.name);",
+    "  const { size, contentType } = await getFileStore().put(key, file, { contentType: file.type });",
+    "  const base = new URL(req.url).origin;",
+    "  return Response.json({ key, size, contentType, url: `${base}/api/features/files/${key}` });",
+    "}",
+    "",
+  ].join('\n'));
+  await writeFile(feat('files', '[key]', 'route.ts'), [
+    "// Serves a stored file back by key. getFileStore().get(key) returns the bytes",
+    "// as a web ReadableStream (streamed, never buffered whole) plus the recorded",
+    "// content type. The key is validated inside the store (traversal-safe).",
+    "import { getFileStore } from '@webjsdev/server';",
+    "",
+    "export async function GET(_req: Request, { params }: { params: { key: string } }) {",
+    "  const file = await getFileStore().get(params.key);",
+    "  if (!file) return new Response('Not found', { status: 404 });",
+    "  return new Response(file.body as ReadableStream<Uint8Array>, {",
+    "    headers: { 'content-type': file.contentType, 'content-length': String(file.size) },",
+    "  });",
+    "}",
+    "",
+  ].join('\n'));
+
+  // 5) WebSocket endpoint with broadcast fan-out.
+  await mkdir(feat('ws'), { recursive: true });
+  await writeFile(feat('ws', 'route.ts'), [
+    "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/ws route), then delete this marker line. webjs check fails while the marker remains.",
+    "// A WebSocket endpoint: exporting WS(ws, req) upgrades this route to a socket.",
+    "// The framework auto-registers each connection to its path, so broadcast()",
+    "// fans a message out to every connected client. Connect two clients to",
+    "// ws://localhost:8080/api/features/ws and watch messages arrive in both.",
+    "import { broadcast } from '@webjsdev/server';",
+    "",
+    "type WSLike = {",
+    "  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;",
+    "  send(msg: string): void;",
+    "};",
+    "",
+    "export function WS(ws: WSLike) {",
+    "  ws.on('message', (data) => {",
+    "    broadcast('/api/features/ws', data.toString());",
+    "  });",
+    "}",
+    "",
+  ].join('\n'));
+
+  // 6) Boot-time env validation (opt-in). env.ts lives at the app ROOT (sibling
+  // to middleware.ts), not inside app/. All-optional so it never blocks boot.
+  await writeFile(join(appDir, 'env.ts'), [
+    "// Boot-time env validation (opt-in, app-root env.ts). A schema of var name to",
+    "// type/options; webjs coerces values, applies defaults, and fails fast naming",
+    "// EVERY bad var. Kept all-optional here so it never blocks a fresh boot; make",
+    "// a var required by dropping `optional`.",
+    "export default {",
+    "  DATABASE_URL: { type: 'string', optional: true },",
+    "  PORT: { type: 'number', optional: true, default: 8080 },",
+    "  NODE_ENV: { type: 'enum', values: ['development', 'production', 'test'], optional: true },",
+    "};",
+    "",
+  ].join('\n'));
+
+  // A starter test for the validated action.
+  await writeFile(join(appDir, 'test', 'unit', 'widgets.test.ts'), [
+    "import { test } from 'node:test';",
+    "import assert from 'node:assert/strict';",
+    "",
+    "import { createWidget } from '#modules/widgets/actions/create-widget.server.ts';",
+    "",
+    "test('createWidget echoes the name and mints an id', async () => {",
+    "  const w = await createWidget({ name: 'Gadget' });",
+    "  assert.equal(w.name, 'Gadget');",
+    "  assert.ok(w.id);",
+    "});",
+    "",
+  ].join('\n'));
+}
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
index 7d028270a..ceeaa2d72 100644
--- a/packages/cli/lib/create.js
+++ b/packages/cli/lib/create.js
@@ -841,6 +841,14 @@ export default cors({
       health: \`\${base}/api/health\`,
       users: \`\${base}/api/users\`,
     },
+    // The backend-features showcase (delete app/api/features + its modules to prune).
+    features: {
+      validate: \`\${base}/api/features/validate\`,
+      'rate-limit': \`\${base}/api/features/rate-limit\`,
+      stream: \`\${base}/api/features/stream\`,
+      files: \`\${base}/api/features/files\`,
+      ws: \`\${base.replace(/^http/, 'ws')}/api/features/ws\`,
+    },
   });
 }
 `);
@@ -925,6 +933,13 @@ export type ActionResult<T> =
   | { success: true; data: T }
   | { success: false; error: string; status: number };
 `);
+
+    // The api backend-features showcase: endpoints under app/api/features/**
+    // demonstrating the server-side surface (route() adapter + validation, rate
+    // limiting, streaming, file storage, WebSockets + broadcast) plus env
+    // validation. The api counterpart of the UI gallery. Prune what you skip.
+    const { writeApiGallery } = await import('./api-gallery.js');
+    await writeApiGallery(appDir);
   }
 
   if (!isApi) {
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index f2b63d5e2..9ea105d69 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -27,7 +27,11 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
   for the todo app, also the `todos` table). Never delete blindly up front. Each
   route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
-  until you resolve it. Delete now-empty directories after pruning.
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
   do NOT: `globals.css` is at `styles/`, browser-safe helpers at
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index f4ccd62f8..dd311a300 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -27,7 +27,11 @@ the full hosted docs are at **https://docs.webjs.dev**.
   `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
   for the todo app, also the `todos` table). Never delete blindly up front. Each
   route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
-  until you resolve it. Delete now-empty directories after pruning.
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
   do NOT: `globals.css` is at `styles/`, browser-safe helpers at
diff --git a/test/scaffolds/scaffold-gallery.test.js b/test/scaffolds/scaffold-gallery.test.js
index 59e7084ec..913450d1c 100644
--- a/test/scaffolds/scaffold-gallery.test.js
+++ b/test/scaffolds/scaffold-gallery.test.js
@@ -163,16 +163,27 @@ test('feature pages have no stale /examples/ links after the features refactor',
   }
 });
 
-test('the api template does NOT ship the gallery (no UI)', async () => {
+test('the api template ships the backend-features showcase, not the UI gallery', async () => {
   const cwd = await tempCwd();
   try {
     await scaffoldApp('demo', cwd, { template: 'api' });
     const appDir = join(cwd, 'demo');
-    assert.equal(existsSync(join(appDir, 'app', 'features')), false, 'api must not ship app/features');
+    // No UI gallery (the api template has no pages/components).
+    assert.equal(existsSync(join(appDir, 'app', 'features')), false, 'api must not ship the UI app/features');
     assert.equal(existsSync(join(appDir, 'app', 'examples')), false, 'api must not ship app/examples');
     assert.equal(existsSync(join(appDir, 'modules', 'todo')), false, 'api must not ship the todo module');
-    const schema = await readFile(join(appDir, 'db', 'schema.server.ts'), 'utf8');
-    assert.doesNotMatch(schema, /table\('todos'/, 'api schema must not add the gallery todos table');
+    // The BACKEND-features showcase (endpoints under app/api/features/).
+    for (const name of ['validate', 'rate-limit', 'stream', 'files', 'ws']) {
+      assert.ok(await exists(join(appDir, 'app', 'api', 'features', name, 'route.ts')), `api backend demo ${name}`);
+    }
+    assert.ok(await exists(join(appDir, 'app', 'api', 'features', 'rate-limit', 'middleware.ts')), 'rate-limit middleware');
+    assert.ok(await exists(join(appDir, 'app', 'api', 'features', 'files', '[key]', 'route.ts')), 'file serve route');
+    assert.ok(await exists(join(appDir, 'modules', 'widgets', 'actions', 'create-widget.server.ts')), 'widgets action');
+    assert.ok(await exists(join(appDir, 'env.ts')), 'env-validation demo at the app root');
+    // The root index lists the showcase.
+    const rootRoute = await readFile(join(appDir, 'app', 'route.ts'), 'utf8');
+    assert.match(rootRoute, /features:/, 'root index lists the features');
+    assert.match(rootRoute, /api\/features\/validate/, 'root index links the validate endpoint');
   } finally {
     await rm(cwd, { recursive: true, force: true });
   }

From f819b3556d98b61d7bb6325fbe588a2f93005ce1 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 23:24:18 +0530
Subject: [PATCH 43/53] fix(cli): serve the api stream demo as text/plain so
 browsers render it

application/x-ndjson made browsers download the streaming endpoint as a
file instead of showing it. Serve text/plain (+ nosniff) so it renders
inline and incrementally in a browser; curl -N still sees the same
JSON-per-line chunks arrive one at a time.
---
 packages/cli/lib/api-gallery.js | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/cli/lib/api-gallery.js b/packages/cli/lib/api-gallery.js
index 1406993be..317ae552b 100644
--- a/packages/cli/lib/api-gallery.js
+++ b/packages/cli/lib/api-gallery.js
@@ -79,10 +79,12 @@ export async function writeApiGallery(appDir) {
   await mkdir(feat('stream'), { recursive: true });
   await writeFile(feat('stream', 'route.ts'), [
     "// webjs-scaffold-placeholder. API backend-features demo. Keep and adapt it, or prune it (delete this app/api/features/stream route), then delete this marker line. webjs check fails while the marker remains.",
-    "// Streams NDJSON chunks as they are produced, so a slow or large result is",
-    "// delivered incrementally instead of buffered whole. A hand-written route.ts",
-    "// returns a ReadableStream for full control; `curl -N` shows the lines arrive",
-    "// one at a time.",
+    "// Streams JSON-per-line chunks as they are produced, so a slow or large",
+    "// result is delivered incrementally instead of buffered whole. A hand-written",
+    "// route.ts returns a ReadableStream for full control. Served as text/plain so",
+    "// it renders INLINE and incrementally in a browser (application/x-ndjson would",
+    "// make the browser download a file instead); `curl -N` shows the same lines",
+    "// arrive one at a time.",
     "export async function GET() {",
     "  const encoder = new TextEncoder();",
     "  const stream = new ReadableStream({",
@@ -94,7 +96,7 @@ export async function writeApiGallery(appDir) {
     "      controller.close();",
     "    },",
     "  });",
-    "  return new Response(stream, { headers: { 'content-type': 'application/x-ndjson' } });",
+    "  return new Response(stream, { headers: { 'content-type': 'text/plain; charset=utf-8', 'x-content-type-options': 'nosniff' } });",
     "}",
     "",
   ].join('\n'));

From 10eeabe60cfd77704b1962ad6863d18c4eadc735 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Tue, 7 Jul 2026 23:28:47 +0530
Subject: [PATCH 44/53] fix(cli): make the POST/WS api demos explorable with a
 GET usage handler

Opening /api/features/files (or validate, or ws) in a browser did a GET
and got a bare 405, since those endpoints are POST/WS-only. Add a GET
handler to each that returns usage JSON (method, description, example),
so every showcase endpoint is browser-discoverable while the real
POST/upload/WebSocket behavior is unchanged. Verified: GET returns 200
usage, POST/upload still work, typecheck clean.
---
 packages/cli/lib/api-gallery.js | 34 +++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/cli/lib/api-gallery.js b/packages/cli/lib/api-gallery.js
index 317ae552b..214753012 100644
--- a/packages/cli/lib/api-gallery.js
+++ b/packages/cli/lib/api-gallery.js
@@ -49,6 +49,17 @@ export async function writeApiGallery(appDir) {
     "  return { success: true as const, data: { name } };",
     "};",
     "",
+    "// A GET returns usage so the endpoint is explorable in a browser; the real",
+    "// validated action is the POST below.",
+    "export async function GET(req: Request) {",
+    "  const base = new URL(req.url).origin;",
+    "  return Response.json({",
+    "    method: 'POST',",
+    "    usage: 'POST JSON { name } to validate the input and create a widget; an empty name returns a 422 with fieldErrors.',",
+    "    example: 'curl -X POST -H content-type:application/json -d {\"name\":\"Gadget\"} ' + base + '/api/features/validate',",
+    "  });",
+    "}",
+    "",
     "export const POST = route(createWidget, { validate });",
     "",
   ].join('\n'));
@@ -111,6 +122,18 @@ export async function writeApiGallery(appDir) {
     "// Try: curl -F file=@README.md http://localhost:8080/api/features/files",
     "import { getFileStore, generateKey } from '@webjsdev/server';",
     "",
+    "// A GET on the upload endpoint returns usage, so it is explorable in a browser",
+    "// (the real upload is the POST below).",
+    "export async function GET(req: Request) {",
+    "  const base = new URL(req.url).origin;",
+    "  return Response.json({",
+    "    method: 'POST',",
+    "    usage: 'POST a multipart form with a `file` field to upload.',",
+    "    example: 'curl -F file=@README.md ' + base + '/api/features/files',",
+    "    serve: base + '/api/features/files/<key>',",
+    "  });",
+    "}",
+    "",
     "export async function POST(req: Request) {",
     "  const form = await req.formData();",
     "  const file = form.get('file');",
@@ -150,6 +173,17 @@ export async function writeApiGallery(appDir) {
     "// ws://localhost:8080/api/features/ws and watch messages arrive in both.",
     "import { broadcast } from '@webjsdev/server';",
     "",
+    "// A plain GET (a browser opening the URL) returns usage; the live socket is",
+    "// the WS handler below, reached over ws:// with a WebSocket client.",
+    "export async function GET(req: Request) {",
+    "  const base = new URL(req.url).origin.replace(/^http/, 'ws');",
+    "  return Response.json({",
+    "    protocol: 'WebSocket',",
+    "    usage: 'Connect over ws:// and send a message; it is broadcast to every connected client.',",
+    "    url: base + '/api/features/ws',",
+    "  });",
+    "}",
+    "",
     "type WSLike = {",
     "  on(event: 'message' | 'close', cb: (data: Buffer) => void): void;",
     "  send(msg: string): void;",

From f251c0276c1d209dc5cdd8d51f6429efdf5ac70f Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 00:03:05 +0530
Subject: [PATCH 45/53] docs(cli): add the missing explanatory header to the
 delete-todo action

The delete-todo gallery action was the one demo file with no comment.
Add the same mutation/RPC-stub header its create/toggle siblings carry,
so every gallery file explains its webjs concept.
---
 .../gallery/modules/todo/actions/delete-todo.server.ts         | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts b/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
index 17c27138e..b969a58c8 100644
--- a/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
+++ b/packages/cli/templates/gallery/modules/todo/actions/delete-todo.server.ts
@@ -1,4 +1,7 @@
 'use server';
+// A MUTATION (no `method` export defaults to POST: CSRF-protected). Imported
+// directly by the client component (the import becomes a typed RPC stub); the
+// id argument and the ActionResult round-trip through webjs's serializer.
 import { eq } from 'drizzle-orm';
 import { db } from '#db/connection.server.ts';
 import { todos } from '#db/schema.server.ts';

From b7f361f3828d2fe3f7a3871256a811a8aa8f1c3d Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 00:37:36 +0530
Subject: [PATCH 46/53] docs: document the scaffold gallery + api backend
 showcase across surfaces

The scaffold is the primary teaching surface for AI agents, but the
framework docs never mentioned the feature gallery. Add it to the docs
site getting-started page, the framework AGENTS.md scaffolding section,
and the README: every UI scaffold (full-stack + saas) ships a commented
feature gallery, and the api template ships a backend-features showcase,
each pruned per-feature via the placeholder markers.
---
 AGENTS.md                             | 2 +-
 README.md                             | 2 ++
 docs/app/docs/getting-started/page.ts | 2 ++
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 59f8025bc..98b164b4f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -434,7 +434,7 @@ const result = await optimistic(liked, true, () => likePost(postId));
 
 Three scaffolds exist (do not invent template names): `webjs create <name>` (full-stack: layout, page, components, modules, Drizzle+SQLite), `webjs create <name> --template api` (backend-only routes + modules + Drizzle, no SSR), `webjs create <name> --template saas` (auth + login/signup + protected dashboard + User model). The `--db sqlite|postgres` flag (default sqlite) picks the dialect; the schema/queries/actions are identical across dialects (see #563). The `--runtime node|bun` flag (default node, #541) is ORTHOGONAL to the template and re-flavors any of the three for Bun (`bun --bun` dev/start scripts so the SERVER runs on Bun, `bun.lock`, a pure `oven/bun:1` Dockerfile (#595; safe since cli@0.10.20's npx-free `webjs db migrate` (#570) needs no Node in the image) + bun-install CI, bun-command agent docs; the test/db/check tooling stays on Node); `bun create webjs <name>` auto-detects it. Pick from the request: default for any product with UI (todo, blog, dashboard, marketplace, social, e-commerce), `api` for an HTTP/JSON API with no UI, `saas` for accounts/login/signup; default to full-stack when ambiguous.
 
-Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. Docs at https://docs.webjs.dev.
+Rules: **always scaffold via `webjs create`** (never hand-roll). **Default to a real database (Drizzle + SQLite); NEVER use JSON files, in-memory arrays, or localStorage for persistence.** Update `db/schema.server.ts` to real models FIRST, then `webjs db generate` + `webjs db migrate`, then build pages/actions/queries. **Treat the scaffold as REFERENCE, not the final product:** replace the example page / `User` model / components and adapt `app/layout.ts` (brand, nav, content width; the default `<main class="max-w-[760px]">` reading column needs widening for a full-bleed app). ENFORCED: examples carry a `webjs-scaffold-placeholder` comment and `no-scaffold-placeholder` fails until the content is replaced and the marker deleted. **The scaffold IS the primary teaching surface:** every UI scaffold (full-stack AND saas) ships a densely commented feature gallery (one webjs concept per demo under `app/features/`, logic in `modules/`, plus a whole example app under `app/examples/`), and the `api` template ships a backend-features showcase under `app/api/features/` (the `route()` adapter + validation, rate limiting, streaming, file storage, WebSockets + broadcast) listed in the root `app/route.ts` index; read the demos to learn the idioms, then prune per-feature. Docs at https://docs.webjs.dev.
 
 ---
 
diff --git a/README.md b/README.md
index a7d48b5bf..6e1d7dd7d 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,8 @@ TypeScript with zero build step, real SSR with Declarative Shadow DOM.
 > - Backend-only HTTP/JSON API, no UI → **`--template api`**
 > - Auth, login/signup, protected dashboard, SaaS → **`--template saas`**
 >
+> **The scaffold is the tutorial.** Every UI scaffold (full-stack and saas) ships a commented **feature gallery** (`app/features/` + an example app under `app/examples/`); the `api` template ships a **backend-features showcase** (`app/api/features/`). Read the demos to learn the idioms, then prune per-feature.
+>
 > Full rules: [`AGENTS.md` → How AI agents must scaffold](./AGENTS.md#how-ai-agents-must-scaffold).
 > Full framework docs (every API, every recipe): **https://docs.webjs.dev**.
 
diff --git a/docs/app/docs/getting-started/page.ts b/docs/app/docs/getting-started/page.ts
index 271c14f4d..8c0b1379e 100644
--- a/docs/app/docs/getting-started/page.ts
+++ b/docs/app/docs/getting-started/page.ts
@@ -42,6 +42,8 @@ webjs create my-app --template saas</pre>
 
     <p>The <code>--template saas</code> scaffold includes login + signup pages, a dashboard with auth middleware guard, settings page, auth API route, <code>createAuth()</code> with Credentials provider, Drizzle User model with password hashing, and a modules architecture (<code>modules/auth/{actions,queries,types.ts}</code>, <code>db/connection.server.ts</code>, <code>lib/{auth,password}.ts</code>).</p>
 
+    <p><strong>The scaffold IS the tutorial.</strong> Every UI scaffold (full-stack AND saas) ships a densely commented <strong>feature gallery</strong>: one webjs concept per demo under <code>app/features/</code> (routing, components, server actions, optimistic UI, async render, directives, forms, metadata, caching, env vars, the client router, service worker, WebSockets, broadcast, rate limiting, file storage, type-safe routes) with logic in <code>modules/</code>, plus a whole example app under <code>app/examples/</code>. The <code>--template api</code> scaffold ships the backend counterpart instead, a <strong>backend-features showcase</strong> under <code>app/api/features/</code> (the <code>route()</code> adapter + input validation, rate limiting, a streaming response, file storage, and a WebSocket + broadcast endpoint) listed in the root <code>app/route.ts</code> index. Read each demo end to end (the code AND its comments) to learn the idioms, then prune the ones you do not need. Each demo carries a <code>webjs-scaffold-placeholder</code> marker, so <code>webjs check</code> fails until you keep-and-adapt or delete it (the route AND its <code>modules/&lt;name&gt;</code>).</p>
+
     <h3>Scaffolding a Bun app</h3>
     <p>webjs runs on Node 24+ or Bun. To generate a Bun-flavored app, add <code>--runtime bun</code> (a separate axis from <code>--template</code>, so it works with all three). It is auto-detected when you scaffold through Bun, so both forms below produce the same Bun app:</p>
     <pre># auto-detected: scaffolding through bun implies --runtime bun

From cbc89a779818f4c2362fb764a48f995fb31be2d4 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 00:44:01 +0530
Subject: [PATCH 47/53] chore: add a webjs-scaffold-sync skill (scaffold-side
 sibling of doc-sync)

The scaffold is webjs's primary teaching surface for AI agents, and a
change to what `webjs create` generates has many surfaces that drift
(the generators, the per-agent rule files, the scaffold tests, the
framework template-matrix docs, the preview apps). Add a webjs-scaffold-sync
skill that maps them all with the change-type mapping and a mandatory
generate-boot-check step, route it from the route-skills hook, wire it into
webjs-start-work's Definition of Done and cross-reference it from
webjs-doc-sync. Committed in-repo so a fresh clone routes to it.
---
 .claude/hooks/route-skills.sh               |  19 +++
 .claude/skills/webjs-doc-sync/SKILL.md      |   8 +-
 .claude/skills/webjs-scaffold-sync/SKILL.md | 149 ++++++++++++++++++++
 .claude/skills/webjs-start-work/SKILL.md    |   2 +-
 test/hooks/route-skills.test.mjs            |  14 ++
 5 files changed, 190 insertions(+), 2 deletions(-)
 create mode 100644 .claude/skills/webjs-scaffold-sync/SKILL.md

diff --git a/.claude/hooks/route-skills.sh b/.claude/hooks/route-skills.sh
index cfa184952..dc25c7bec 100755
--- a/.claude/hooks/route-skills.sh
+++ b/.claude/hooks/route-skills.sh
@@ -128,6 +128,25 @@ if has '(doc|documentation) (gap|drift|sync|coverage|debt)' \
   add_match "webjs-doc-sync: the request is about documentation sync, drift, or a doc gap. Invoke the webjs-doc-sync skill BEFORE editing any doc. It holds the authoritative map of EVERY surface (AGENTS.md + agent-docs/, README, the docs site under docs/app/docs/, the marketing website/, and the scaffold templates' per-agent rule files) and the change-type to surface mapping, so no surface is silently skipped. File each confirmed gap via webjs-file-issue."
 fi
 
+# --- webjs-scaffold-sync: keep every scaffold surface in sync -----------
+# Triggers: change what `webjs create` generates (a gallery/showcase demo, a
+# template, the generated layout/home/theme/schema), sync the scaffold,
+# "update all three templates", check the scaffold is consistent, teach
+# agents via the scaffold. The scaffold is webjs's PRIMARY teaching surface,
+# so a change must propagate across the generators (packages/cli/lib/*), the
+# per-agent rule files, the scaffold tests, the framework template-matrix
+# docs, and the preview apps, with a mandatory "generate + boot + check".
+if has '(sync|update|check|fix|add to).{0,24}(the )?(scaffold|template)' \
+   || has '(all (three|3) )?(scaffold )?templates?\b' \
+   || has 'gallery.{0,40}(template|saas|api|full-?stack|scaffold)' \
+   || has '(ship|include|add|put).{0,30}(the )?(gallery|showcase)' \
+   || has '(add|new|update).{0,24}(gallery|showcase)' \
+   || has '(scaffold|gallery) (consistent|in sync|drift|gap)' \
+   || has 'what `?webjs create`? generates' \
+   || has '(feature|backend) gallery'; then
+  add_match "webjs-scaffold-sync: the request changes what \`webjs create\` generates (a gallery/showcase demo, a template, a generated file, a scaffold convention). Invoke the webjs-scaffold-sync skill BEFORE editing. It holds the authoritative map of every scaffold surface (the packages/cli/lib/* generators, the templates/, the per-agent rule files in lockstep, the scaffold tests, the framework template-matrix docs, the preview apps) plus the mandatory generate-boot-check verification, so no surface is silently skipped. It is the scaffold-side sibling of webjs-doc-sync."
+fi
+
 # --- code-review: review the diff before a PR is ready ------------------
 # Triggers: review the PR/diff/branch/changes, code review, look it over
 # for bugs. Reviewing every change before it is marked ready is a standing
diff --git a/.claude/skills/webjs-doc-sync/SKILL.md b/.claude/skills/webjs-doc-sync/SKILL.md
index ba3b28b63..dccc8a0c5 100644
--- a/.claude/skills/webjs-doc-sync/SKILL.md
+++ b/.claude/skills/webjs-doc-sync/SKILL.md
@@ -59,7 +59,13 @@ applies, then update or consciously skip each.
    `.gemini` / `.opencode` / `.claude` rule files. These per-agent files all carry
    the SAME rules in each agent's format; a workflow/convention change must land in
    ALL of them in lockstep (the #134 / #136 divergence lesson). The CLI help text
-   in `packages/cli/` is part of this surface for a new command or flag.
+   in `packages/cli/` is part of this surface for a new command or flag. When the
+   change is to what `webjs create` GENERATES (a gallery/showcase demo, a
+   template, the generated layout/home/theme/schema, a scaffold convention),
+   this surface has more parts (the `packages/cli/lib/*` generators, the scaffold
+   tests, the framework template-matrix docs, the preview apps) and a mandatory
+   "generate + boot + check" step: use the dedicated **`webjs-scaffold-sync`**
+   skill for those, and treat this doc-sync entry as the docs-only slice.
 6. **Example / dogfood apps** (`examples/blog/CONVENTIONS.md` and friends). Update
    when a convention the example demonstrates changes.
 
diff --git a/.claude/skills/webjs-scaffold-sync/SKILL.md b/.claude/skills/webjs-scaffold-sync/SKILL.md
new file mode 100644
index 000000000..937e57020
--- /dev/null
+++ b/.claude/skills/webjs-scaffold-sync/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: webjs-scaffold-sync
+description: Use this skill whenever a change affects what `webjs create` GENERATES (a new or changed gallery/showcase demo, a new template, a changed generated file like the layout/home/theme/schema, a new convention that belongs in generated apps, a new scaffold-shipped config/hook) OR when the user asks to sync the scaffold, "update all three templates", check the scaffold is consistent, or teach agents how to use webjs through the scaffold. The scaffold is webjs's PRIMARY teaching surface for AI agents, so a change to it must propagate in lockstep across the generators, the per-agent rule files, the scaffold tests, the framework docs that describe the scaffold, and the preview/example apps. This skill is the authoritative map of every scaffold surface plus the change-type to surface mapping, and the mandatory "generate + boot + check" verification, so no surface is silently skipped. Complements webjs-doc-sync (which owns framework API/behaviour docs); this skill owns what the scaffold emits.
+when_to_use: |
+  Examples that should trigger this skill:
+    "add a new demo to the feature gallery"
+    "the gallery should also ship in the saas template"
+    "update all three scaffold templates with this"
+    "add a backend-features showcase to the api template"
+    "make sure the scaffold teaches agents how to do X"
+    "did we keep the scaffold rule files in sync?"
+    "the saas home / theme / schema changed, sync everything"
+    finishing any change to what `webjs create` generates
+  Do NOT trigger for: a framework API/behaviour change with no scaffold
+  impact (use webjs-doc-sync), or a pure-internal refactor of the CLI
+  that does not change generated output.
+---
+
+# Keep every scaffold surface in sync with what `webjs create` generates
+
+The scaffold is the **primary way AI agents learn webjs**: an agent reads the
+generated gallery/showcase and its comments to learn the idioms, then builds the
+real app by adapting them. So a change to what `webjs create` emits is a
+first-class change with MANY surfaces, and the recurring failure is updating one
+(usually a template file) while the per-agent rule files, the scaffold tests, the
+framework docs, and the preview apps drift behind. This skill closes that gap.
+
+It is the sibling of `webjs-doc-sync`. Division of labour:
+
+- **webjs-doc-sync** owns the framework's API/behaviour docs (the root `AGENTS.md`
+  API sections, `agent-docs/*.md`, docs-site topic pages, the marketing website).
+- **webjs-scaffold-sync** (this skill) owns what the scaffold GENERATES and the
+  surfaces that DESCRIBE the scaffold.
+
+They overlap on two surfaces (the scaffold's per-agent rule files, and the
+template matrix in the framework docs/README). Whichever skill reaches that
+surface must update it; when in doubt run both.
+
+## The complete scaffold surface map
+
+Treat this as the universe. For any scaffold change, decide per surface whether
+it applies, then update or consciously skip each.
+
+1. **The generators** (the code that writes the app):
+   - `packages/cli/lib/create.js` (the main generator: layout, home page, the
+     theme block, db/schema, the full-stack gallery wiring, the per-template
+     gates like `isApi` / `isSaas` / `!isApi`).
+   - `packages/cli/lib/saas-template.js` (the saas-only files: auth, login/signup,
+     dashboard, the saas schema).
+   - `packages/cli/lib/api-gallery.js` (the api backend-features showcase).
+   - Any future `*-template.js` / `*-gallery.js` split out for escaping sanity.
+2. **The verbatim template files** copied into every app:
+   - `packages/cli/templates/gallery/**` (the UI feature gallery + example app,
+     shipped in full-stack AND saas).
+   - `packages/cli/templates/**` (everything else copied per app: `lib/utils/ui.ts`,
+     `public/`, `tsconfig.json`, `gitignore`, `.hooks/`, the metadata/route stubs).
+3. **The per-agent rule files** (LOCKSTEP: all carry the SAME rules in each
+   agent's format, the #134/#136 divergence lesson). A convention/workflow change
+   for generated apps must land in ALL of them together:
+   - `packages/cli/templates/AGENTS.md`
+   - `packages/cli/templates/CLAUDE.md`
+   - `packages/cli/templates/CONVENTIONS.md`
+   - `packages/cli/templates/.cursorrules`
+   - `packages/cli/templates/.github/copilot-instructions.md`
+   - `packages/cli/templates/.agents/rules/workflow.md`
+   - `packages/cli/templates/.gemini/**`, `.opencode/**`, `.claude/**` (whatever
+     per-agent rule files the scaffold currently ships; enumerate, do not assume)
+4. **The scaffold tests**: `test/scaffolds/*.test.js` (e.g. `scaffold-gallery`,
+   `scaffold-ui-integration`). A new demo/template/generated-file assertion goes
+   here, including the counterfactual (a per-template exclusion test).
+5. **The framework docs that DESCRIBE the scaffold** (shared with doc-sync):
+   - Root `AGENTS.md` "Scaffolding" section.
+   - The docs site: `docs/app/docs/getting-started/page.ts` (+ `backend-only`,
+     `ai-first`, `conventions` where they describe generated structure).
+   - `README.md` (the template matrix + the "scaffold is the tutorial" note).
+6. **The CLI surface**: `packages/cli/` `--template` validation + `--help`/usage
+   text when a template or flag is added or renamed.
+7. **The preview / example / dogfood apps**: `examples/blog/` and any in-repo
+   apps, plus the local preview apps the user tests, when a convention they
+   demonstrate changes.
+
+## Change-type to surface mapping
+
+| Change | Surfaces that MUST be checked |
+|---|---|
+| New / changed **gallery or showcase demo** | the template file(s) or generator strings for the demo + the home-page `features`/index array + the scaffold AGENTS.md gallery list + `test/scaffolds/*` FEATURES/assertions + **generate + boot the affected template** |
+| New / removed **template** | the `create.js` template branch (+ a `*-template.js` if large) + the "only N templates exist" list in EVERY per-agent rule file + the framework `AGENTS.md`/getting-started/README template matrix + the CLI `--template` validation + `--help` + `test/scaffolds/*` |
+| New **convention/rule** for generated apps | ALL per-agent rule files in lockstep (surface 3) + repo `CONVENTIONS.md` if the repo demonstrates it + `agent-docs` only if it also changes a framework API |
+| Changed **generated file** (layout, theme, home, schema, middleware) | the generator (`create.js`/`*-template.js`) + any scaffold test asserting it + any doc/preview describing it + **regenerate + boot** |
+| New **scaffold-shipped config/hook** (`.hooks/`, `webjs.*` in the generated `package.json`, a check rule) | `templates/**` + `webjs doctor`/`check` that reads it + the per-agent rule files if agents must know it |
+| Which **templates ship the gallery** (scoping) | the `copyGallery` / gallery gate in `create.js` + the "full-stack only / full-stack and saas" wording in the per-agent rule files AND the framework docs (grep the old scoping phrase everywhere) |
+| Pure-internal CLI refactor (no change to generated output) | NONE. Record that no scaffold surface applies. |
+
+## Per-change sync procedure
+
+1. Identify the change's IDENTIFYING TOKENS: the demo route (`app/features/<x>`,
+   `app/api/features/<x>`), the template name, the generated file path, the
+   convention phrase, or the scoping phrase (e.g. "full-stack only").
+2. Grep those tokens across every scaffold surface:
+   ```sh
+   git grep -n -iE '<token1>|<token2>' -- \
+     'packages/cli/lib/**' 'packages/cli/templates/**' 'test/scaffolds/**' \
+     AGENTS.md README.md 'docs/app/docs/**'
+   ```
+3. Update every surface the mapping says applies. For a SCOPING or wording change
+   (e.g. "gallery is full-stack only" becoming "full-stack and saas"), the grep
+   MUST surface and fix every copy, in the rule files AND the framework docs.
+4. **VERIFY BY GENERATING (mandatory, non-negotiable).** The generators emit
+   strings, so a template-literal / escaping / interpolation bug is invisible in
+   the generator's own syntax and only appears in the GENERATED app. For each
+   affected template, generate an app and prove it:
+   ```sh
+   # generate (files only is enough for structure/typecheck; install to boot)
+   node -e "import('packages/cli/lib/create.js').then(m => m.scaffoldApp('probe', '/tmp/x', { template: 'saas', install: false }))"
+   # then in the generated app: webjs check (only no-scaffold-placeholder should
+   # remain), webjs typecheck (clean), and boot it to hit the new route(s).
+   ```
+   A scaffold change is NOT done until a freshly generated app of each affected
+   template BOOTS, serves the new/changed route, passes `webjs check` (only the
+   intended `no-scaffold-placeholder` markers), and `webjs typecheck` is clean.
+5. Run the scaffold tests (`node --test 'test/scaffolds/*.test.js'`) and add/adjust
+   assertions (a new demo in the FEATURES list, a per-template inclusion/exclusion
+   test, the counterfactual).
+6. Respect the prose-punctuation invariant (#11) in every comment and doc, and
+   keep each demo densely commented (a header stating the webjs concept + the
+   why, inline comments on the non-obvious idiom, a `webjs-scaffold-placeholder`
+   marker). The scaffold teaches by its comments; a thin demo is a bug.
+
+## Audit-mode procedure (sweep the scaffold for drift)
+
+1. List the shipped scaffold changes (new demos, new template, scoping changes,
+   changed generated files).
+2. For each, pull its tokens and run the surface grep above.
+3. A surface is a GAP when the mapping says it applies but the token is absent or
+   describes stale behaviour there (a classic gap: a demo added to the full-stack
+   home but missing from the saas home, or a scoping phrase updated in one rule
+   file but not the other five).
+4. For a bulk audit, file a grounded follow-up via **webjs-file-issue** per gap
+   (title `scaffold: <surface> missing <thing>`); for a single in-flight change,
+   just fix all surfaces on the same PR.
+
+## What this skill does NOT do
+
+- It does not regenerate `llms.txt` / `llms-full.txt` (live-generated) or the
+  website changelog (auto from PR titles).
+- It does not own framework API/behaviour docs (that is `webjs-doc-sync`); when a
+  change touches both a framework API and the scaffold, run both skills.
+- It does not decide whether a CLI change alters generated output; that judgement
+  is step 1, and a pure-internal refactor correctly updates no scaffold surface.
diff --git a/.claude/skills/webjs-start-work/SKILL.md b/.claude/skills/webjs-start-work/SKILL.md
index 2c94cd5d0..10d0fc429 100644
--- a/.claude/skills/webjs-start-work/SKILL.md
+++ b/.claude/skills/webjs-start-work/SKILL.md
@@ -126,7 +126,7 @@ Doc drift is the #1 way a framework rots. Documentation MUST stay in sync with c
    - `CLAUDE.md` (only if a Claude Code rule is specifically added; framework conventions go in AGENTS.md).
    - `.github/*.md` (issue templates, PR templates, contributing) when a workflow rule shifts.
 3. **User-facing docs site** under `docs/app/docs/<topic>/page.ts` (these are `.ts` files, not markdown, so they're excluded by the markdown query but they're the canonical user-facing reference). If the change is visible to a user reading the docs site, update the matching topic page. Add a new page if the surface is new and there's no obvious home.
-4. **Scaffold templates** under `packages/cli/templates/`. Update if the change affects what `webjs create` generates (default code, agent config files, `.hooks` content, scaffolded `package.json` shape).
+4. **Scaffold templates** under `packages/cli/templates/` and the generators `packages/cli/lib/{create,saas-template,api-gallery}.js`. Update if the change affects what `webjs create` generates (default code, the gallery/showcase demos, agent config files, `.hooks` content, scaffolded `package.json` shape). The scaffold is webjs's PRIMARY teaching surface for AI agents, so this surface has many parts that must move in lockstep (the generators, the per-agent rule files, the scaffold tests, the framework docs that describe the scaffold, the preview/example apps) and a mandatory "generate + boot + `webjs check`" verification. **Invoke the `webjs-scaffold-sync` skill** to walk them all; it is the scaffold-side sibling of `webjs-doc-sync`.
 5. **The MCP server** (the standalone `@webjsdev/mcp` package, `packages/mcp/src/{mcp,mcp-docs,mcp-source}.js`, extracted from the CLI in #415; `webjs mcp` and `npx @webjsdev/mcp` both run it). The MCP is how AI agents learn and introspect webjs, so it must stay in lockstep with the surfaces it exposes. Update it whenever the change touches what it serves:
    - **Introspection tools** (`list_routes` / `list_actions` / `list_components` / `check`): if you change the route table shape, the action/RPC-hash scheme, component registration, or a `webjs check` rule, update the matching tool projection so the MCP reports reality.
    - **Knowledge layer** (resources + `init` + `docs` + prompts): the resources are the `agent-docs/*.md` corpus + `AGENTS.md`, so a docs change is picked up automatically (it is bundled at `prepack`). But if you add or rename an `agent-docs` file, ADD A NEW INVARIANT, change the execution model, or add an authoring concept an agent should know, also: (a) confirm the `init` primer still pulls the right `AGENTS.md` sections (it sources the Execution-model + Invariants headings, so a heading rename breaks it), and (b) add a guided-workflow PROMPT for any new common recipe (a new page/route/action/component-shaped task). New recipes without a prompt are a silent gap.
diff --git a/test/hooks/route-skills.test.mjs b/test/hooks/route-skills.test.mjs
index ffceaffaa..61788c760 100644
--- a/test/hooks/route-skills.test.mjs
+++ b/test/hooks/route-skills.test.mjs
@@ -116,6 +116,20 @@ test('webjs-research-record routes on research/design phrases', () => {
   }
 });
 
+test('webjs-scaffold-sync routes on scaffold-change phrases', () => {
+  for (const p of [
+    'add a new demo to the feature gallery',
+    'the gallery should also ship in the saas template',
+    'update all three scaffold templates with this',
+    'add a backend gallery to the api template',
+    'sync the scaffold across every surface',
+    'is the scaffold consistent across templates',
+  ]) {
+    const { ctx } = run(p);
+    assert.ok(routed(ctx, 'webjs-scaffold-sync'), `expected scaffold-sync route for: ${p}`);
+  }
+});
+
 test('code-review routes on review phrases', () => {
   for (const p of [
     'review the PR',

From b75b707abcbfcd3439b700859942886f35ca6d03 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 00:56:26 +0530
Subject: [PATCH 48/53] feat: hard-gate scaffold sync on framework-feature
 commits (#826)

The scaffold is webjs's primary teaching surface for AI agents, but unlike
tests and docs it had no commit-time gate, so a framework feature could
ship without the scaffold that teaches it. Add require-scaffold-with-src.sh
(the scaffold twin of require-docs-with-src.sh): it BLOCKS a commit staging
packages/(core|server|cli)/src feature source with no scaffold surface
(packages/cli/templates or packages/cli/lib) alongside it, escape hatch
WEBJS_NO_SCAFFOLD_GATE=1. Register it in settings.json, make Scaffold sync a
first-class item in the AGENTS.md Code-workflow, and cover the hook with
test/hooks/require-scaffold-with-src.test.mjs (7 cases: block, satisfy via
gallery/generator, scaffold-only, excluded package, escape hatch, non-commit).
---
 .claude/hooks/require-scaffold-with-src.sh    |  98 ++++++++++++++
 .claude/settings.json                         |   4 +
 .claude/skills/webjs-scaffold-sync/SKILL.md   |   8 ++
 AGENTS.md                                     |   3 +-
 test/hooks/require-scaffold-with-src.test.mjs | 123 ++++++++++++++++++
 5 files changed, 235 insertions(+), 1 deletion(-)
 create mode 100755 .claude/hooks/require-scaffold-with-src.sh
 create mode 100644 test/hooks/require-scaffold-with-src.test.mjs

diff --git a/.claude/hooks/require-scaffold-with-src.sh b/.claude/hooks/require-scaffold-with-src.sh
new file mode 100755
index 000000000..f76909af5
--- /dev/null
+++ b/.claude/hooks/require-scaffold-with-src.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook: BLOCK a `git commit` that changes framework FEATURE
+# source but stages NO scaffold surface. The scaffold is webjs's PRIMARY
+# teaching surface for AI agents: an agent learns the framework by reading
+# the generated gallery/showcase and its comments, then builds the real app
+# by adapting them. So when a webjs FEATURE is added or changed, the scaffold
+# that teaches it must move too, exactly as the docs must (this is the
+# scaffold twin of require-docs-with-src.sh).
+#
+# It fires on every commit, decides from the STAGED diff (not model
+# judgement), and BLOCKS (exit 2) when framework-feature source is staged
+# with no scaffold surface in the same commit.
+#
+# What a hook CANNOT do: know WHETHER a given change actually needs a
+# scaffold demo (a bug fix, an internal perf change, or a tweak to an
+# already-demoed feature may not). So it enforces the floor (a
+# feature-source commit must stage SOME scaffold surface OR consciously opt
+# out) and points at the webjs-scaffold-sync skill for the per-surface walk
+# and the mandatory generate-boot-check.
+#
+# Scope: only fires on `git commit` Bash calls. Inspects the STAGED diff,
+# so `git add` choices drive it.
+#
+# Trigger (feature source that MAY need a scaffold update): the runtime +
+# CLI packages' src, packages/(core|server|cli)/src/**. Editor plugins, the
+# MCP, and intellisense do not shape the scaffold, so they are excluded.
+#
+# Satisfying surface: the scaffold itself, packages/cli/templates/** (the
+# template files + per-agent rule files) OR packages/cli/lib/** (the
+# create.js / saas-template.js / api-gallery.js generators).
+#
+# Allowed (exit 0): commits touching no feature src; commits that stage a
+# scaffold surface alongside the source; and a change that genuinely needs
+# no scaffold update (a bug fix, an internal refactor, a tweak to an
+# already-demoed feature) via WEBJS_NO_SCAFFOLD_GATE=1.
+#
+# Rule: AGENTS.md "Code workflow" (Scaffold) + the webjs-scaffold-sync skill.
+
+set -euo pipefail
+
+if [ "${WEBJS_NO_SCAFFOLD_GATE:-}" = "1" ]; then
+  exit 0
+fi
+
+payload=$(cat)
+cmd=$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+
+# Match `git commit` as a whole word (a real commit, not git commit-tree).
+if ! printf '%s' "$cmd" | grep -Eq '(^|[^[:alnum:]-])git commit([^[:alnum:]-]|$)'; then
+  exit 0
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+staged=$(git diff --cached --name-only 2>/dev/null || true)
+if [ -z "$staged" ]; then exit 0; fi
+
+# Framework FEATURE source: the runtime + CLI packages' src. A change here is
+# the kind that MAY need the scaffold that teaches it to move too.
+src_touched=$(printf '%s\n' "$staged" | grep -E '^packages/(core|server|cli)/src/' || true)
+if [ -z "$src_touched" ]; then exit 0; fi
+
+# Any scaffold surface staged in the same commit? The scaffold is the
+# templates (files + per-agent rule files) and the generators (cli/lib).
+scaffold_staged=$(printf '%s\n' "$staged" | grep -E '^packages/cli/(templates|lib)/' || true)
+if [ -n "$scaffold_staged" ]; then exit 0; fi
+
+cat >&2 <<'EOF'
+BLOCKED: this commit changes framework-feature source but stages no scaffold.
+
+Staged source under packages/(core|server|cli)/src/** with no scaffold
+surface in the same commit. The scaffold is webjs's PRIMARY teaching surface
+for AI agents (they learn the framework by reading the generated
+gallery/showcase, then build the real app by adapting it), so a task is NOT
+done until the scaffold that teaches the changed feature is in sync too.
+
+If this added or changed a webjs FEATURE an agent should learn from the
+scaffold (a new export/API, an html hole, a lifecycle hook, a server-action
+capability, a config key, a CLI behaviour), invoke the webjs-scaffold-sync
+skill, then `git add` the scaffold surface(s) and commit again:
+  packages/cli/templates/gallery/         a UI feature-gallery demo (full-stack + saas)
+  packages/cli/lib/api-gallery.js         an api backend-showcase endpoint
+  packages/cli/lib/{create,saas-template}.js  the generators (home, theme, schema, wiring)
+  packages/cli/templates/ (AGENTS/CONVENTIONS/.cursorrules/...)  scaffold rules in lockstep
+  test/scaffolds/**                       the scaffold assertions for the above
+The skill walks every surface AND runs the mandatory generate + boot +
+`webjs check` verification (the generators emit strings, so escaping bugs
+only show in a freshly generated app).
+
+Change that genuinely needs no scaffold update (a bug fix, an internal
+refactor, a tweak to an already-demoed feature)? Re-run with
+WEBJS_NO_SCAFFOLD_GATE=1.
+
+Hook: .claude/hooks/require-scaffold-with-src.sh
+EOF
+exit 2
diff --git a/.claude/settings.json b/.claude/settings.json
index 18137e2eb..3df01041d 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -40,6 +40,10 @@
             "type": "command",
             "command": ".claude/hooks/require-docs-with-src.sh"
           },
+          {
+            "type": "command",
+            "command": ".claude/hooks/require-scaffold-with-src.sh"
+          },
           {
             "type": "command",
             "command": ".claude/hooks/require-bun-parity-with-runtime-src.sh"
diff --git a/.claude/skills/webjs-scaffold-sync/SKILL.md b/.claude/skills/webjs-scaffold-sync/SKILL.md
index 937e57020..6686f34c6 100644
--- a/.claude/skills/webjs-scaffold-sync/SKILL.md
+++ b/.claude/skills/webjs-scaffold-sync/SKILL.md
@@ -36,6 +36,14 @@ They overlap on two surfaces (the scaffold's per-agent rule files, and the
 template matrix in the framework docs/README). Whichever skill reaches that
 surface must update it; when in doubt run both.
 
+A hard commit gate enforces the FLOOR: `.claude/hooks/require-scaffold-with-src.sh`
+BLOCKS a commit that stages framework-feature source (`packages/(core|server|cli)/src`)
+with no scaffold surface (`packages/cli/templates` or `packages/cli/lib`) in the
+same commit (escape hatch `WEBJS_NO_SCAFFOLD_GATE=1` for a change that genuinely
+needs no scaffold update). The hook can only enforce "stage SOME scaffold
+surface"; THIS skill does the substantive per-surface judgment and the
+generate-boot-check verification.
+
 ## The complete scaffold surface map
 
 Treat this as the universe. For any scaffold change, decide per surface whether
diff --git a/AGENTS.md b/AGENTS.md
index 98b164b4f..18dba6c98 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,8 @@ Every code change MUST include, automatically:
 
 1. **Tests, every applicable layer (not just unit).** Ship the tests that prove the change across EVERY layer it touches: **unit** (`packages/*/test/**`, `test/**`, including the counterfactual that fails when reverted), **browser** (`*/test/**/browser/*` via `npm run test:browser`, for hydration / DOM / slots / client router / custom-element upgrade), **e2e** (`test/e2e/*.test.mjs` via `WEBJS_E2E=1`, including network probes / navigation / streaming), and **smoke** (`test/examples/*/smoke/*`). A unit test is NECESSARY BUT NOT SUFFICIENT for any client-router / component / browser-facing change (the headline behaviour is a browser/e2e assertion). **Bun parity is part of the task, not an afterthought:** webjs runs on Node 24+ AND Bun (#508), so a change to a runtime-sensitive surface (the serializer, the node:http vs `Bun.serve` listener + request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) MUST be proven on Bun (`node scripts/run-bun-tests.js` + the touched `test/bun/*.mjs` under `bun`) AND ship an added/updated `test/bun/<feature>.mjs` cross-runtime assertion. `npm test` does NOT run browser, e2e, or Bun; run them yourself and report the result. Never report work done with failing or missing tests. See `agent-docs/testing.md`. Enforced by `.claude/hooks/require-tests-with-src.sh` (the scaffold variant WARNS unless `WEBJS_TEST_GATE=block`) and `.claude/hooks/require-bun-parity-with-runtime-src.sh` (BLOCKS a commit that stages runtime-sensitive source with no `test/bun/**` test; escape hatch `WEBJS_BUN_VERIFIED=1`).
 2. **Documentation, part of the definition of done (not optional).** A task is NOT done until EVERY doc surface its change touches is in sync: `AGENTS.md` + `agent-docs/*.md` for new API surface, `CONVENTIONS.md` (and per-package `AGENTS.md`) for new conventions, the docs site (`docs/app/docs/<topic>`), the marketing `website/`, the scaffold templates (`packages/cli/templates/` per-agent rule files), and `README.md` for a headline capability. Updating `AGENTS.md` alone reproduces the #488 gap (docs site left stale). Invoke the `webjs-doc-sync` skill to sync every applicable surface. Enforced by `.claude/hooks/require-docs-with-src.sh`, which BLOCKS a commit that stages public `packages/*/src` source with no doc surface alongside it (a genuinely internal refactor / CI / release / perf change with no behaviour change bypasses with `WEBJS_NO_DOC_GATE=1`).
-3. **Convention validation.** Run `webjs check` and fix violations.
+3. **Scaffold sync, part of the definition of done (not optional).** The scaffold is webjs's PRIMARY teaching surface for AI agents: they learn the framework by reading the generated gallery/showcase and its comments, then build the real app by adapting them. So when a webjs FEATURE is added or changed, the scaffold that teaches it must move too, the same way the docs must. Ask on EVERY feature change: does a UI feature-gallery demo (`packages/cli/templates/gallery/`, shipped in full-stack + saas), an api backend-showcase endpoint (`packages/cli/lib/api-gallery.js`), a generator surface (`packages/cli/lib/{create,saas-template}.js` for the home/theme/schema/wiring), a scaffold convention (the per-agent rule files in lockstep), or a scaffold test (`test/scaffolds/**`) need to change? Invoke the `webjs-scaffold-sync` skill to walk every surface AND run its mandatory generate + boot + `webjs check` verification (the generators emit strings, so an escaping bug only shows in a freshly generated app). Enforced by `.claude/hooks/require-scaffold-with-src.sh`, which BLOCKS a commit that stages `packages/(core|server|cli)/src` feature source with no scaffold surface (`packages/cli/templates` or `packages/cli/lib`) alongside it (a bug fix, an internal refactor, or a tweak to an already-demoed feature that needs no scaffold change bypasses with `WEBJS_NO_SCAFFOLD_GATE=1`).
+4. **Convention validation.** Run `webjs check` and fix violations.
 
 ### Git workflow (mandatory)
 
diff --git a/test/hooks/require-scaffold-with-src.test.mjs b/test/hooks/require-scaffold-with-src.test.mjs
new file mode 100644
index 000000000..34cf8e342
--- /dev/null
+++ b/test/hooks/require-scaffold-with-src.test.mjs
@@ -0,0 +1,123 @@
+// Tests for the FRAMEWORK's require-scaffold-with-src PreToolUse hook
+// (.claude/hooks/require-scaffold-with-src.sh). It is the scaffold twin of
+// require-docs-with-src.sh: a `git commit` that stages framework-FEATURE
+// source (packages/(core|server|cli)/src/**) with NO scaffold surface
+// (packages/cli/templates/** or packages/cli/lib/**) exits 2 to block it,
+// with a WEBJS_NO_SCAFFOLD_GATE=1 escape hatch.
+//
+// Each case builds a throwaway repo, stages a shape of change, feeds the
+// hook the commit payload, and asserts the exit code.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOOK = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '../../.claude/hooks/require-scaffold-with-src.sh',
+);
+
+/** Init a throwaway monorepo-shaped repo with a baseline commit. */
+function makeRepo() {
+  const dir = mkdtempSync(join(tmpdir(), 'webjs-scaffoldgate-'));
+  const git = (...args) => execFileSync('git', args, { cwd: dir, stdio: 'pipe' });
+  git('init', '-q');
+  git('config', 'user.email', 't@t');
+  git('config', 'user.name', 't');
+  for (const d of [
+    'packages/core/src', 'packages/server/src', 'packages/cli/src',
+    'packages/cli/lib', 'packages/cli/templates/gallery/app/features/x',
+    'packages/editors/vscode/src',
+  ]) mkdirSync(join(dir, d), { recursive: true });
+  writeFileSync(join(dir, 'packages/core/src/x.js'), 'v1\n');
+  writeFileSync(join(dir, 'packages/cli/lib/create.js'), 'gen1\n');
+  writeFileSync(join(dir, 'README.md'), 'docs\n');
+  git('add', '-A');
+  git('commit', '-qm', 'init');
+  return { dir, git };
+}
+
+function runHook(dir, env = {}) {
+  const r = spawnSync('bash', [HOOK], {
+    cwd: dir,
+    input: JSON.stringify({ tool_input: { command: 'git commit -m x' } }),
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+  });
+  return r.status;
+}
+
+test('blocks a feature-src commit that stages no scaffold surface', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/core/src/x.js'), 'v2\n');
+    git('add', 'packages/core/src/x.js');
+    assert.equal(runHook(dir), 2);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('allows a feature-src commit that also stages a gallery demo', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/server/src/y.js'), 'v2\n');
+    writeFileSync(join(dir, 'packages/cli/templates/gallery/app/features/x/page.ts'), 'demo\n');
+    git('add', '-A');
+    assert.equal(runHook(dir), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('allows a feature-src commit that also stages a generator (cli/lib)', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/core/src/x.js'), 'v2\n');
+    writeFileSync(join(dir, 'packages/cli/lib/create.js'), 'gen2\n');
+    git('add', '-A');
+    assert.equal(runHook(dir), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('allows a scaffold-only commit (no feature src touched)', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/cli/lib/create.js'), 'gen2\n');
+    git('add', 'packages/cli/lib/create.js');
+    assert.equal(runHook(dir), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('allows an excluded-package src commit (editor plugin does not shape the scaffold)', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/editors/vscode/src/z.js'), 'v2\n');
+    git('add', 'packages/editors/vscode/src/z.js');
+    assert.equal(runHook(dir), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('escape hatch WEBJS_NO_SCAFFOLD_GATE=1 allows a feature-src-only commit', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/core/src/x.js'), 'v2\n');
+    git('add', 'packages/core/src/x.js');
+    assert.equal(runHook(dir, { WEBJS_NO_SCAFFOLD_GATE: '1' }), 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('ignores a non-commit git command', () => {
+  const { dir, git } = makeRepo();
+  try {
+    writeFileSync(join(dir, 'packages/core/src/x.js'), 'v2\n');
+    git('add', 'packages/core/src/x.js');
+    const r = spawnSync('bash', [HOOK], {
+      cwd: dir,
+      input: JSON.stringify({ tool_input: { command: 'git status' } }),
+      env: process.env,
+      encoding: 'utf8',
+    });
+    assert.equal(r.status, 0);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});

From 761bc04f09de1e55a2146e3668eff5bdd50c2dd7 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 01:07:46 +0530
Subject: [PATCH 49/53] refactor(cli): use buttonClass() for the todo composer
 Add button

The composer's Add button is a standard button, so use the @webjsdev/ui
buttonClass() helper (a class string, light-DOM safe) instead of
hand-rolled Tailwind, and note inline why the toggle + delete stay
hand-rolled (a circular checkbox and an icon affordance are not standard
buttons). Verified against the published core: the todo renders and the
Add button carries the buttonClass output; typecheck + webjs check clean.
---
 .../templates/gallery/modules/todo/components/todo-app.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 0929457e4..9d7e76d3f 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -10,6 +10,7 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
+import { buttonClass } from '#components/ui/button.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -98,8 +99,11 @@ export class TodoApp extends WebComponent({
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
             class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
-          <button type="submit"
-            class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Add</button>
+          <!-- The @webjsdev/ui buttonClass() helper: a class STRING (not a custom
+               element), so it drops into a light-DOM component's markup. The
+               toggle + delete below stay hand-rolled because they are not
+               standard buttons (a circular checkbox, an icon affordance). -->
+          <button type="submit" class=${buttonClass()}>Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">

From c89b1aa7795a561b4d971a48f71f034877b188b7 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 01:12:50 +0530
Subject: [PATCH 50/53] refactor(cli): use inputClass() for the todo composer
 input

Following the buttonClass() change, use the @webjsdev/ui inputClass()
helper for the composer input too, so the composer is the standard ui-kit
form (inputClass + buttonClass, both class-string helpers). This drops the
bespoke integrated pill for a more idiomatic, instructive form. The toggle
+ delete stay hand-rolled (a circular checkbox and an icon affordance are
not standard controls). Verified against the published core: the input
renders the inputClass output; typecheck + webjs check clean.
---
 .../gallery/modules/todo/components/todo-app.ts   | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 9d7e76d3f..5ff7fb56b 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -11,6 +11,7 @@
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -93,16 +94,16 @@ export class TodoApp extends WebComponent({
         </header>
 
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
-             with JS, @submit intercepts and runs the optimistic path. -->
+             with JS, @submit intercepts and runs the optimistic path. It uses the
+             @webjsdev/ui form helpers, inputClass() + buttonClass() (both plain
+             class STRINGS, so they drop into a light-DOM component). The toggle +
+             delete below stay hand-rolled: they are not standard controls (a
+             circular checkbox, an icon affordance). -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
+          class="flex items-center gap-2">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
-          <!-- The @webjsdev/ui buttonClass() helper: a class STRING (not a custom
-               element), so it drops into a light-DOM component's markup. The
-               toggle + delete below stay hand-rolled because they are not
-               standard buttons (a circular checkbox, an icon affordance). -->
+            class="${inputClass()} flex-1" />
           <button type="submit" class=${buttonClass()}>Add</button>
         </form>
 

From d0b884834c5ed6f403af2665f39cd8445acd5488 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 01:16:45 +0530
Subject: [PATCH 51/53] revert(cli): restore the bespoke todo composer (input +
 button)

Revert the buttonClass()/inputClass() composer changes back to the
original crafted design: the integrated pill (rounded-2xl card) with a
transparent borderless input and a hand-rolled Add button. The ui-kit
form was more idiomatic but lost the taskflow-quality look the composer
was built for. The home CTA still demonstrates buttonClass().
---
 .../gallery/modules/todo/components/todo-app.ts   | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
index 5ff7fb56b..0929457e4 100644
--- a/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
+++ b/packages/cli/templates/gallery/modules/todo/components/todo-app.ts
@@ -10,8 +10,6 @@
 // one coherent theme. Prefer these tokens (and opacity modifiers like
 // bg-primary/90) over ad-hoc colors.
 import { WebComponent, prop, optimistic, html } from '@webjsdev/core';
-import { buttonClass } from '#components/ui/button.ts';
-import { inputClass } from '#components/ui/input.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
@@ -94,17 +92,14 @@ export class TodoApp extends WebComponent({
         </header>
 
         <!-- Add: a real <form> so it works with JS off (posts to the page action);
-             with JS, @submit intercepts and runs the optimistic path. It uses the
-             @webjsdev/ui form helpers, inputClass() + buttonClass() (both plain
-             class STRINGS, so they drop into a light-DOM component). The toggle +
-             delete below stay hand-rolled: they are not standard controls (a
-             circular checkbox, an icon affordance). -->
+             with JS, @submit intercepts and runs the optimistic path. -->
         <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
-          class="flex items-center gap-2">
+          class="flex items-center gap-2 p-2 pl-4 rounded-2xl bg-card border border-border shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
-            class="${inputClass()} flex-1" />
-          <button type="submit" class=${buttonClass()}>Add</button>
+            class="flex-1 min-w-0 bg-transparent border-0 outline-none text-foreground text-[15px] placeholder:text-muted-foreground/70 py-1.5" />
+          <button type="submit"
+            class="shrink-0 px-4 py-2 rounded-xl bg-primary text-primary-foreground font-semibold text-sm border-0 cursor-pointer transition-all hover:bg-primary/90 active:scale-[0.97]">Add</button>
         </form>
 
         <ul class="list-none m-0 p-0 grid gap-2">

From ffd1c7906a4049ed51b467b68e15d0fa3a81a18f Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 01:20:08 +0530
Subject: [PATCH 52/53] fix(docs): avoid the literal placeholder token in the
 getting-started page

The getting-started copy described the marker by writing the literal
webjs-scaffold-placeholder token, which the no-scaffold-placeholder check
scans for, so webjs check flagged the docs page itself. Describe it
without the exact token (name the no-scaffold-placeholder rule instead).
---
 docs/app/docs/getting-started/page.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/app/docs/getting-started/page.ts b/docs/app/docs/getting-started/page.ts
index 8c0b1379e..466edbcfb 100644
--- a/docs/app/docs/getting-started/page.ts
+++ b/docs/app/docs/getting-started/page.ts
@@ -42,7 +42,7 @@ webjs create my-app --template saas</pre>
 
     <p>The <code>--template saas</code> scaffold includes login + signup pages, a dashboard with auth middleware guard, settings page, auth API route, <code>createAuth()</code> with Credentials provider, Drizzle User model with password hashing, and a modules architecture (<code>modules/auth/{actions,queries,types.ts}</code>, <code>db/connection.server.ts</code>, <code>lib/{auth,password}.ts</code>).</p>
 
-    <p><strong>The scaffold IS the tutorial.</strong> Every UI scaffold (full-stack AND saas) ships a densely commented <strong>feature gallery</strong>: one webjs concept per demo under <code>app/features/</code> (routing, components, server actions, optimistic UI, async render, directives, forms, metadata, caching, env vars, the client router, service worker, WebSockets, broadcast, rate limiting, file storage, type-safe routes) with logic in <code>modules/</code>, plus a whole example app under <code>app/examples/</code>. The <code>--template api</code> scaffold ships the backend counterpart instead, a <strong>backend-features showcase</strong> under <code>app/api/features/</code> (the <code>route()</code> adapter + input validation, rate limiting, a streaming response, file storage, and a WebSocket + broadcast endpoint) listed in the root <code>app/route.ts</code> index. Read each demo end to end (the code AND its comments) to learn the idioms, then prune the ones you do not need. Each demo carries a <code>webjs-scaffold-placeholder</code> marker, so <code>webjs check</code> fails until you keep-and-adapt or delete it (the route AND its <code>modules/&lt;name&gt;</code>).</p>
+    <p><strong>The scaffold IS the tutorial.</strong> Every UI scaffold (full-stack AND saas) ships a densely commented <strong>feature gallery</strong>: one webjs concept per demo under <code>app/features/</code> (routing, components, server actions, optimistic UI, async render, directives, forms, metadata, caching, env vars, the client router, service worker, WebSockets, broadcast, rate limiting, file storage, type-safe routes) with logic in <code>modules/</code>, plus a whole example app under <code>app/examples/</code>. The <code>--template api</code> scaffold ships the backend counterpart instead, a <strong>backend-features showcase</strong> under <code>app/api/features/</code> (the <code>route()</code> adapter + input validation, rate limiting, a streaming response, file storage, and a WebSocket + broadcast endpoint) listed in the root <code>app/route.ts</code> index. Read each demo end to end (the code AND its comments) to learn the idioms, then prune the ones you do not need. Each demo carries a placeholder marker (the <code>no-scaffold-placeholder</code> check), so <code>webjs check</code> fails until you keep-and-adapt or delete it (the route AND its <code>modules/&lt;name&gt;</code>).</p>
 
     <h3>Scaffolding a Bun app</h3>
     <p>webjs runs on Node 24+ or Bun. To generate a Bun-flavored app, add <code>--runtime bun</code> (a separate axis from <code>--template</code>, so it works with all three). It is auto-detected when you scaffold through Bun, so both forms below produce the same Bun app:</p>

From 6503983fbfae830a1fc2e07c0ce29c132019176a Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 8 Jul 2026 09:46:42 +0530
Subject: [PATCH 53/53] docs(scaffold): say prune after using features AND
 examples as reference

---
 packages/cli/templates/.agents/rules/workflow.md       | 2 +-
 packages/cli/templates/.cursorrules                    | 4 ++--
 packages/cli/templates/.github/copilot-instructions.md | 4 ++--
 packages/cli/templates/AGENTS.md                       | 2 +-
 packages/cli/templates/CONVENTIONS.md                  | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md
index d11dc6f38..ff8441e47 100644
--- a/packages/cli/templates/.agents/rules/workflow.md
+++ b/packages/cli/templates/.agents/rules/workflow.md
@@ -40,7 +40,7 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   delete `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
   (`AGENTS.md`, `CONVENTIONS.md`, the rule files, the MCP), never prune it, so
   removing example code never removes your context. Prune AFTER using the
-  examples as reference, never blindly up front. A no-op for the `api` template
+  features and examples as reference, never blindly up front. A no-op for the `api` template
   (no UI kit, no PWA files).
 - **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
   route, middleware, metadata routes). CSS, helpers, and constants do NOT:
diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules
index a73687e05..b7d82b687 100644
--- a/packages/cli/templates/.cursorrules
+++ b/packages/cli/templates/.cursorrules
@@ -39,8 +39,8 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
   `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
   `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
-  example code never removes your context. Prune AFTER using the examples
-  as reference, never blindly up front. A no-op for the `api` template
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
   (no UI kit, no PWA files).
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md
index 5912d10fe..59d14e2c8 100644
--- a/packages/cli/templates/.github/copilot-instructions.md
+++ b/packages/cli/templates/.github/copilot-instructions.md
@@ -39,8 +39,8 @@ the full hosted docs are at **https://docs.webjs.dev**.
   `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
   `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
   `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
-  example code never removes your context. Prune AFTER using the examples
-  as reference, never blindly up front. A no-op for the `api` template
+  example code never removes your context. Prune AFTER using the features
+  and examples as reference, never blindly up front. A no-op for the `api` template
   (no UI kit, no PWA files).
 - **`app/` is routing-only.** Only routing files live in `app/` (page,
   layout, route, middleware, metadata routes). CSS, helpers, and constants
diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md
index 4bafbd5e1..577e07845 100644
--- a/packages/cli/templates/AGENTS.md
+++ b/packages/cli/templates/AGENTS.md
@@ -65,7 +65,7 @@ user asked for, never leftover scaffold code.
    `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
    (`AGENTS.md`, `CONVENTIONS.md`, the per-agent rule files, the MCP
    wiring), never prune it, so removing example code never removes your
-   context. Prune AFTER you have used the examples as reference, never
+   context. Prune AFTER you have used the features and examples as reference, never
    blindly up front. This is a no-op for the `api` template (no UI kit,
    no PWA files).
 
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
index 043a7de62..c6fe3c4fc 100644
--- a/packages/cli/templates/CONVENTIONS.md
+++ b/packages/cli/templates/CONVENTIONS.md
@@ -412,7 +412,7 @@ kit used means delete `components/ui/`, `components.json`, and
 Always KEEP the durable knowledge (`AGENTS.md`, `CONVENTIONS.md`, the
 per-agent rule files, the MCP wiring), and never prune it, so removing
 example code never removes your context. Prune AFTER you have used the
-examples as reference, never blindly up front. This is a no-op for the
+features and examples as reference, never blindly up front. This is a no-op for the
 `api` template, which ships no UI kit and no PWA files.
 
 ---