@webjsdev/cli 0.10.31 → 0.10.33

package/lib/create.js

@@ -49,6 +49,27 @@ function runInstall(appDir, pm) {
   return r.status === 0;
 }
 
+/**
+ * Author the INITIAL Drizzle migration for the shipped schema, so the app boots
+ * with its tables and the very first `run dev` works with no manual step. The
+ * scaffold's schema is TypeScript (`db/schema.server.ts`); `db migrate` (run in
+ * `webjs.dev.before` / `webjs.start.before`) only applies migration SQL FILES, so
+ * with no file the shipped example hits "no such table". `db generate` turns the
+ * schema into that first `db/migrations/*.sql`. It runs OFFLINE (a schema-to-SQL
+ * diff, no database connection), so it is safe for sqlite AND postgres here, well
+ * before any `DATABASE_URL` exists. Needs `drizzle-kit`, so it only runs after a
+ * successful install; on `--no-install` the printed next-steps still show
+ * `db:generate`. Returns whether a migration was authored.
+ *
+ * @param {string} appDir
+ * @param {string} pm
+ * @returns {boolean}
+ */
+function runDbGenerate(appDir, pm) {
+  const r = spawnSync(pm, ['run', 'db:generate'], { cwd: appDir, stdio: 'inherit' });
+  return r.status === 0;
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = resolve(__dirname, '..', 'templates');
 
@@ -401,14 +422,18 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // for relations v2. SQLite needs NO driver dependency: the connection
       // uses the built-in node:sqlite (Node) / bun:sqlite (Bun) via Drizzle's
       // node-sqlite / bun-sqlite adapters. Postgres still needs the pg driver.
-      'drizzle-orm': '^1.0.0-rc.3',
+      // Pinned EXACTLY (no caret): a caret on a prerelease still admits later
+      // rc.N of 1.0.0, and the relations-v2 query API the scaffold is written and
+      // tested against is rc.3 (#562). An exact pin keeps generated apps
+      // deterministic instead of silently drifting to a newer rc.
+      'drizzle-orm': '1.0.0-rc.3',
       ...(dialect === 'postgres' ? { pg: '^8.13.0' } : {}),
       '@webjsdev/cli': 'latest',
       '@webjsdev/core': 'latest',
       '@webjsdev/server': 'latest',
     },
     devDependencies: {
-      'drizzle-kit': '^1.0.0-rc.3',
+      'drizzle-kit': '1.0.0-rc.3',
       ...(dialect === 'postgres' ? { '@types/pg': '^8.11.0' } : {}),
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
@@ -528,6 +553,8 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.claude/hooks/block-prose-punctuation.sh',
     '.claude/hooks/guard-branch-context.sh',
     '.claude/hooks/nudge-uncommitted.sh',
+    '.claude/hooks/commit-before-stop.sh',
+    '.claude/hooks/cleanup-merged-worktree.sh',
     '.claude/hooks/require-tests-with-src.sh',
     '.claude/hooks/check-server-imports.sh',
     '.claude/hooks/check-server-imports.mjs',
@@ -603,7 +630,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
 
   // Make hook scripts executable
   const { chmod } = await import('node:fs/promises');
-  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh', 'require-tests-with-src.sh']) {
+  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh', 'commit-before-stop.sh', 'cleanup-merged-worktree.sh', 'require-tests-with-src.sh']) {
     const hookPath = join(appDir, '.claude', 'hooks', hook);
     if (existsSync(hookPath)) await chmod(hookPath, 0o755);
   }
@@ -1274,8 +1301,10 @@ ${UI_THEME}
       <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. -->
+      <!-- webjs-scaffold-placeholder. This "Built with webjs" footer is SCAFFOLD
+           branding, not your app's. REMOVE it, or replace it with your own
+           footer, before shipping a delivered app. Delete this line once done.
+           webjs check fails while the marker remains. -->
       <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">
@@ -1668,11 +1697,21 @@ For AI agents, read this before editing scaffolded files:
   // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun).
   const pm = isBun ? 'bun' : detectPackageManager();
   let installed = false;
+  let generatedMigration = false;
   if (shouldInstall) {
     console.log(`Running '${pm} install' in ${name}/ ...\n`);
     installed = runInstall(appDir, pm);
     if (!installed) {
       console.log(`\n[warn] ${pm} install failed. Run '${pm} install' manually in ${name}/ to finish setup.\n`);
+    } else {
+      // Author the initial migration NOW (drizzle-kit is installed), so the
+      // shipped schema's tables exist and the very first `run dev` works with no
+      // manual step (webjs.*.before applies the migration on boot). See runDbGenerate.
+      console.log(`Authoring the initial database migration ('${pm} run db:generate') ...\n`);
+      generatedMigration = runDbGenerate(appDir, pm);
+      if (!generatedMigration) {
+        console.log(`\n[warn] '${pm} run db:generate' failed. Run it manually in ${name}/ before '${pm} run dev'.\n`);
+      }
     }
   }
 
@@ -1683,14 +1722,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 && `;
-  // 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 && `;
+  // The shipped schema is applied on the first `run dev` (webjs.*.before runs
+  // `db migrate`), but only if a migration FILE exists. When we installed, we
+  // already authored it above (runDbGenerate), so the run command is just
+  // `run dev`. Otherwise (--no-install, or generate failed) the user authors it
+  // first: `db:generate` writes the migration from db/schema.server.ts, then
+  // `run dev` applies it (Drizzle splits Prisma's `migrate dev` into
+  // generate-then-migrate).
+  const dbSegment = generatedMigration ? '' : `${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`

package/package.json

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

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

@@ -46,12 +46,23 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   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
-  reading column, the example header/nav). The `api` template has no UI, so this
-  does not apply there. Keep the design tokens and theme setup in
-  `app/layout.ts`, those are infrastructure, and restyle on top of them.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a full-bleed
+  dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default full-stack),
   `--template api`, `--template saas`. The CLI rejects any other `--template`
   value. Pick:

package/templates/.claude/hooks/cleanup-merged-worktree.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Claude Code PostToolUse hook (matcher: Bash).
+#
+# After a `gh pr merge`, sweep the repo's git worktrees and REMOVE the ones
+# whose work has already landed, so a merged branch's worktree does not leak.
+# Accumulated stale worktrees (a session that merged but never cleaned up, or
+# crashed mid-task) are exactly what this closes: the webjs-start-work skill
+# already says "after the PR merges, git worktree remove", but as guidance it
+# gets skipped, so this makes the cleanup deterministic.
+#
+# CONSERVATIVE BY DESIGN. A worktree is removed ONLY when ALL hold:
+#   * it is a LINKED worktree, not the primary checkout;
+#   * it is NOT the current directory (you cannot remove the one you are in);
+#   * its branch is not main/master;
+#   * its branch is MERGED (an ancestor of the base ref, OR a merged GitHub PR
+#     for that head branch, which is how squash-merges are detected);
+#   * its working tree is CLEAN apart from untracked node_modules / .webjs.
+# Anything with uncommitted or unpushed-looking work is KEPT and reported, so
+# the hook can never destroy in-flight work.
+#
+# It never blocks the tool (always exits 0) and reports what it did back to the
+# model via hookSpecificOutput.additionalContext. Disable with
+# WEBJS_NO_WORKTREE_CLEANUP=1.
+#
+# Rule: AGENTS.md "One task per git worktree" + the webjs-start-work skill.
+
+set -uo pipefail
+
+# Read the whole payload first so we always honour the hook contract.
+payload=$(cat 2>/dev/null || true)
+
+if [ "${WEBJS_NO_WORKTREE_CLEANUP:-}" = "1" ]; then exit 0; fi
+
+cmd=$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+
+# Only act after a `gh pr merge` (whole word, not `gh pr merge-queue` typos etc.).
+if ! printf '%s' "$cmd" | grep -Eq '(^|[^[:alnum:]-])gh pr merge([^[:alnum:]-]|$)'; then
+  exit 0
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+# The base ref merged branches land on. Prefer origin/main; fall back to a
+# local main/master (the test harness has no remote).
+base=""
+for ref in origin/main origin/master main master; do
+  if git rev-parse --verify --quiet "$ref" >/dev/null 2>&1; then base="$ref"; break; fi
+done
+[ -z "$base" ] && exit 0
+
+here=$(git rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PWD")
+# The primary worktree is the first entry of `git worktree list`.
+primary=$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')
+
+is_merged() {
+  local br="$1"
+  # Ancestor of the base ref (fast-forward / rebase merges, and the real
+  # merges the test harness makes).
+  if git merge-base --is-ancestor "refs/heads/$br" "$base" 2>/dev/null; then return 0; fi
+  # A merged GitHub PR for this head branch (squash merges, which are NOT an
+  # ancestor of base). Network; skipped when gh is absent or unauthenticated.
+  if command -v gh >/dev/null 2>&1; then
+    local n
+    n=$(gh pr list --state merged --head "$br" --json number --jq '.[0].number' 2>/dev/null || true)
+    [ -n "$n" ] && return 0
+  fi
+  return 1
+}
+
+# Clean = nothing in `git status` except untracked node_modules / .webjs caches.
+is_clean() {
+  local wt="$1" dirty
+  dirty=$(git -C "$wt" status --porcelain 2>/dev/null \
+    | grep -vE '(^|/)(node_modules|\.webjs)(/|$)' || true)
+  [ -z "$dirty" ]
+}
+
+removed=()
+kept=()
+
+# Parse worktree path + branch pairs.
+wt=""
+while IFS= read -r line; do
+  case "$line" in
+    worktree\ *) wt="${line#worktree }" ;;
+    branch\ *)
+      br="${line#branch refs/heads/}"
+      # Skip the primary checkout and main/master lines.
+      if [ "$wt" = "$primary" ] || [ "$br" = "main" ] || [ "$br" = "master" ]; then wt=""; continue; fi
+      # Never remove the worktree we are currently in.
+      if [ "$wt" = "$here" ]; then
+        kept+=("$wt (current directory; cd out then \`git worktree remove\`)")
+        wt=""; continue
+      fi
+      if ! is_clean "$wt"; then
+        kept+=("$wt (uncommitted changes)"); wt=""; continue
+      fi
+      if ! is_merged "$br"; then
+        kept+=("$wt (branch $br not merged yet)"); wt=""; continue
+      fi
+      if git worktree remove --force "$wt" >/dev/null 2>&1; then
+        removed+=("$wt ($br)")
+      else
+        kept+=("$wt (git worktree remove failed)")
+      fi
+      wt="" ;;
+    "") wt="" ;;
+  esac
+done < <(git worktree list --porcelain 2>/dev/null)
+
+git worktree prune >/dev/null 2>&1 || true
+
+# Report nothing if there was nothing to do.
+if [ "${#removed[@]}" -eq 0 ] && [ "${#kept[@]}" -eq 0 ]; then exit 0; fi
+
+msg="Worktree cleanup after \`gh pr merge\`:"
+for r in "${removed[@]:-}"; do [ -n "$r" ] && msg="$msg"$'\n'"  removed $r (merged, clean)"; done
+for k in "${kept[@]:-}"; do [ -n "$k" ] && msg="$msg"$'\n'"  kept $k"; done
+
+jq -n --arg ctx "$msg" '{
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: $ctx
+  }
+}' 2>/dev/null || true
+
+exit 0

package/templates/.claude/hooks/commit-before-stop.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# Claude Code Stop hook.
+#
+# The commit-per-logical-unit rule (CLAUDE.md + AGENTS.md "Git workflow") is
+# easy for an agent to defer to "the end", and then the end arrives with the
+# whole feature done and ZERO commits, which is the worst outcome: git history,
+# the user's revert and cherry-pick safety net, is empty. The PostToolUse
+# `nudge-uncommitted.sh` reminds DURING work but is only a soft context nudge an
+# agent can ignore. This Stop hook is the backstop at the END of a turn: if you
+# try to finish with a pile of uncommitted work on a feature branch, it blocks
+# the stop once and tells you to commit the completed unit first.
+#
+# Loop-safe: when `stop_hook_active` is already true (this hook fired and the
+# agent is continuing because of it), it does NOT block again, so it nags at
+# most once per stop and can never trap the agent in a loop.
+#
+# Skipped on main/master (you must not commit there anyway) and outside a git
+# work tree. Threshold via WEBJS_COMMIT_STOP_THRESHOLD (default 2). Disable
+# entirely with WEBJS_NO_COMMIT_STOP=1.
+
+set -uo pipefail
+
+payload=$(cat 2>/dev/null || true)
+
+if [ "${WEBJS_NO_COMMIT_STOP:-}" = "1" ]; then exit 0; fi
+
+# Loop guard: if we already blocked once this stop-cycle, let the agent stop.
+active=$(printf '%s' "$payload" | jq -r '.stop_hook_active // false' 2>/dev/null || echo false)
+if [ "$active" = "true" ]; then exit 0; fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$branch" ] || [ "$branch" = "main" ] || [ "$branch" = "master" ]; then exit 0; fi
+
+threshold="${WEBJS_COMMIT_STOP_THRESHOLD:-2}"
+
+# Count real changes: tracked modifications + staged + untracked, minus the
+# noise the agent should never commit (node_modules, the sqlite db, caches).
+changed=$(git status --porcelain 2>/dev/null \
+  | grep -vE '(^|/)(node_modules|\.webjs)(/|$)|dev\.db($|-journal)' \
+  | grep -c . || true)
+
+if [ -z "$changed" ] || [ "$changed" -lt "$threshold" ]; then exit 0; fi
+
+reason="You are ending the turn with ${changed} uncommitted changes on '${branch}'. This project OVERRIDES Claude Code's never-commit default: commit per logical unit (see CLAUDE.md and AGENTS.md \"Git workflow\"). Before you stop, group the completed work into a meaningful commit ('git add' the related files, 'git commit' with an imperative subject under 72 chars) and push. If the work is genuinely mid-change and not yet a coherent unit, commit what IS complete, or explain in your final message why it cannot be committed yet. To relax this backstop set WEBJS_COMMIT_STOP_THRESHOLD, or disable it with WEBJS_NO_COMMIT_STOP=1."
+
+jq -n --arg r "$reason" '{decision: "block", reason: $r}' 2>/dev/null \
+  || printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$reason" | jq -Rs . 2>/dev/null || echo '""')"
+
+exit 0

package/templates/.claude/settings.json

@@ -56,6 +56,25 @@
             "command": ".claude/hooks/nudge-uncommitted.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/cleanup-merged-worktree.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/commit-before-stop.sh"
+          }
+        ]
       }
     ]
   }

package/templates/.cursorrules

@@ -46,13 +46,23 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   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 reading column, the example header/nav). The `api`
-  template has no UI, so this does not apply there. Keep the design tokens
-  and theme setup in `app/layout.ts`, those are infrastructure, and
-  restyle on top of them.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a
+  full-bleed dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:

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

@@ -46,13 +46,23 @@ the full hosted docs are at **https://docs.webjs.dev**.
   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 reading column, the example header/nav). The `api`
-  template has no UI, so this does not apply there. Keep the design tokens
-  and theme setup in `app/layout.ts`, those are infrastructure, and
-  restyle on top of them.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a
+  full-bleed dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick:

package/templates/AGENTS.md

@@ -21,12 +21,21 @@ default `<main class="max-w-[760px]">` is a reading column for prose and
 forms, so for a full-bleed app, dashboard, or board, widen the cap or
 remove it (keep the theme tokens). A wide layout left in the 760px
 reading column overflows into a horizontal scrollbar. **Give the app a
-unique design.** When it has a UI, choose its palette, layout, typography,
-and chrome to fit what the user asked for, rather than mimicking the
-scaffold's example look (the warm accent, the reading column, the serif
-display, the example header/nav) or just recoloring the same layout. The
-`api` template has no UI, so this does not apply there. The design tokens
-and theme wiring are infrastructure to keep and restyle on top of. This is ENFORCED:
+unique design, and redesign means more than recolor.** When it has a UI,
+choose its palette, typography, LAYOUT, and chrome from what the app IS.
+Recoloring the scaffold and swapping the logo while keeping its skeleton (a
+fixed top header with a Home link and a theme toggle, the centered ~760px
+reading column, the "Built with webjs" footer) is NOT a unique design.
+Decide from scratch whether this app even needs a header or footer, what nav
+(if any), and what layout fits (a centered board, a full-bleed dashboard, a
+split, a single card). Before finishing, self-audit that nothing still reads
+as the scaffold example (no "Built with webjs" footer, no leftover example
+nav, no default reading column unless it truly fits). The `api` template has
+no UI, so this does not apply there. The design tokens and theme wiring are
+infrastructure to keep and restyle on top of. Style with Tailwind utilities
+wherever they reach, and use custom CSS only for what utilities cannot
+express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+gradients). This is ENFORCED:
 the example `app/page.ts` and `app/layout.ts` carry a
 `webjs-scaffold-placeholder` marker comment, and `webjs check` fails
 while any marker remains, so this freshly scaffolded app fails the check
@@ -372,10 +381,14 @@ db/
   dev.db                 SQLite file (gitignored); created when migrations apply (\`dev\`/\`start\` run \`webjs db migrate\`)
   migrations/            generated migration SQL (committed)
 drizzle.config.ts        drizzle-kit config (root; SQLite by default, --db postgres to switch)
-public/                  static assets, served at /public/*
+public/                  static assets at /public/* (favicon, sw.js, offline.html serve at root)
 test/<feature>/                feature-scoped tests, one folder per concern
   <name>.test.ts                node unit / integration test (node --test)
-  browser/<name>.test.js        real-browser test (web-test-runner)
+  browser/<name>.test.js        real-browser test (web-test-runner); may ALSO be
+                                co-located next to a component, e.g.
+                                modules/<feature>/components/browser/<name>.test.js
+                                (see the gallery counter-card test for the idioms:
+                                suite/test, ssrFixture, inline assert, no chai)
   e2e/<name>.test.ts            end-to-end test (full app boot, opt in via WEBJS_E2E=1)
   smoke/<name>.test.ts          fast post-deploy sanity check
 middleware.ts            root middleware (optional, outermost)
@@ -536,6 +549,7 @@ Scripts (all wrap `drizzle-kit`):
 - `npm run db:studio`: `webjs db studio` (visual DB browser)
 - `npm run db:seed`: `webjs db seed` (run `db/seed.server.ts`)
 - `webjs.dev.before` and `webjs.start.before` both run `webjs db migrate` inside `webjs dev` / `webjs start` (idempotent; replaces the old `prestart` hook), so after you `db:generate` a migration it is applied on the next boot with no manual `db:migrate` step.
+- The INITIAL migration for the shipped schema is authored by `webjs create` at setup time (right after install), so `db/migrations/` is populated and the first `run dev` works with no manual database step. You run `db:generate` yourself only when you CHANGE `db/schema.server.ts` (a new table or column), then the next `run dev` applies it.
 
 Always import `db` from `db/connection.server.ts` (the globalThis-cached
 singleton avoids opening a new connection on every dev-server reload), and
@@ -1404,8 +1418,10 @@ composition, so a nested shell ends up dropped by the HTML parser.
 3. Commit and push **per logical unit**, not at the end. A logical unit is one
    feature, one fix, one rename, one doc rewrite. If you have 5+ unstaged files
    spanning different concerns, commit the current group before continuing.
-   The framework ships a `nudge-uncommitted` hook for several agents that
-   fires at threshold 4:
+   For Claude Code, its `CLAUDE.md` explicitly OVERRIDES Claude Code's built-in
+   never-commit default, so it commits per unit without waiting to be asked. The
+   framework also ships a `nudge-uncommitted` hook for several agents that fires
+   at threshold 4:
 
    | Agent | Hook path | Doc |
    |---|---|---|
@@ -1416,6 +1432,12 @@ composition, so a nested shell ends up dropped by the HTML parser.
    | Antigravity (Google) | text rule only (post-write hooks not yet exposed) | `.agents/rules/workflow.md` |
    | GitHub Copilot | text rule only (no hooks API) | `.github/copilot-instructions.md` |
 
+   Claude Code adds two more backstops of its own. A `commit-before-stop.sh`
+   Stop hook refuses to end a turn with a pile of uncommitted work on a feature
+   branch (loop-safe, disable with `WEBJS_NO_COMMIT_STOP=1`), and a
+   `cleanup-merged-worktree.sh` PostToolUse hook removes a merged branch's
+   worktree after a `gh pr merge`.
+
    The `.hooks/pre-commit` hook blocks commits to main and nothing else;
    `webjs test` + `webjs check` run in CI (`.github/workflows/ci.yml`) on
    every PR and push to main, regardless of which agent (or human) made

package/templates/CLAUDE.md

@@ -1,2 +1,24 @@
 @AGENTS.md
 @CONVENTIONS.md
+
+# Committing per logical unit (this OVERRIDES Claude Code's default)
+
+Claude Code's built-in default is to NEVER commit unless the user explicitly
+asks. **For this project that default does NOT apply.** Commit and push per
+logical unit (one feature, one fix, one rename, one doc rewrite) as soon as it
+is complete, WITHOUT being asked. Do not save all the work for one commit at the
+end. A finished implementation with zero commits is a mistake here, because git
+history is the user's revert and cherry-pick safety net.
+
+- After each completed unit whose tests pass, `git add` the related files and
+  `git commit` with an imperative subject under 72 chars, then push. If 5+ files
+  span more than one concern, you already waited too long.
+- Never commit to `main`. Work on a feature branch (the
+  `.claude/hooks/guard-branch-context.sh` hook enforces this).
+- No AI-attribution trailers (`Co-Authored-By`, `Generated by`).
+
+See AGENTS.md "Git workflow" for the full contract. Two hooks back this up: the
+`.claude/hooks/nudge-uncommitted.sh` PostToolUse hook reminds you while
+uncommitted changes pile up during work, and the
+`.claude/hooks/commit-before-stop.sh` Stop hook stops you from ending a turn
+with a pile of uncommitted work still on a feature branch.

package/templates/CONVENTIONS.md

@@ -373,14 +373,24 @@ When the user asks the agent to build their actual app:
    dashboard, or board, or a wide layout overflows into an unnecessary
    horizontal scrollbar. Keep the design tokens and theme setup, those
    are infrastructure.
-6. **Use a unique design (UI apps).** Give the app a look of its own that
-   fits what the user asked for. Choose the palette, layout, typography,
-   spacing, and chrome deliberately. Do NOT mimic the scaffold's example
-   look (its warm accent, the 760px reading column, the serif display, the
-   example header/nav), and do not just recolor the same layout. The
-   `api` template has no UI, so this does not apply there. The design
-   tokens and theme wiring in `app/layout.ts` are infrastructure to keep
-   and restyle on top of, not the example look to preserve.
+6. **Use a unique design, and redesign means more than recolor (UI apps).**
+   Give the app a design of its own (palette, typography, LAYOUT, spacing,
+   and chrome) chosen from what the app IS. Recoloring the scaffold and
+   swapping the logo while keeping its skeleton (a fixed top header with a
+   Home link and a theme toggle, the centered ~760px reading column, the
+   "Built with webjs" footer) is NOT a unique design. Decide from scratch
+   whether this app even needs a header or footer, what nav (if any), and
+   what layout fits (a centered board, a full-bleed dashboard, a split, a
+   single card). The scaffold ships a `webjs-scaffold-placeholder` marker on
+   its footer, so `webjs check` fails until you remove or replace the
+   "Built with webjs" branding. Self-audit before finishing: nothing should
+   read as the scaffold example (no "Built with webjs" footer, no leftover
+   example nav, no default reading column unless it truly fits). The design
+   tokens and theme wiring in `app/layout.ts` are infrastructure to keep and
+   restyle on top of, not the example look to preserve. Style with Tailwind
+   utilities wherever they reach, and use custom CSS only for what utilities
+   cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix
+   or gradients). The `api` template has no UI, so this does not apply there.
 7. **Keep:** the Drizzle setup, the test config, the agent config files
    (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.),
    `db/connection.server.ts` + `db/columns.server.ts`, the directory
@@ -1255,8 +1265,12 @@ This project enforces a git workflow via agent-specific config files
   (`Add contact form with email validation`, not `update files`).
 - **NEVER add AI attribution.** No `Co-Authored-By: Claude`, no
   `Generated by AI`, no `AI-assisted` trailers or prefixes.
-- **Committing is automatic.** The user should never have to ask
-  "please commit". Commit after completing each logical unit.
+- **Committing is automatic (this overrides Claude Code's default).** The
+  user should never have to ask "please commit". Commit after completing each
+  logical unit. Claude Code's built-in never-commit default is overridden by
+  `CLAUDE.md`, and the `.claude/hooks/commit-before-stop.sh` Stop hook refuses
+  to end a turn with a pile of uncommitted work on a feature branch (disable
+  with `WEBJS_NO_COMMIT_STOP=1`).
 
 **Branch rules:**
 - **Feature branches.** Never commit directly to main

package/templates/gallery/app/features/forms/page.ts

@@ -58,6 +58,12 @@ export default function FormsFeature({ searchParams, actionData }: { searchParam
 // 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).
+//
+// FOOTGUN: to redirect on success, RETURN `{ success: true, redirect: '/path' }`
+// (a 303 See Other, so the browser follows with a GET). Do NOT THROW `redirect()`
+// from a page action, that is a 307 which PRESERVES the POST method and body, so
+// the browser re-POSTs to the target and re-runs the mutation (a duplicate write).
+// Throw `redirect()` only from a page render / GET context, never a page action.
 export async function action({ formData }: { formData: FormData }): Promise<Result> {
   const name = String(formData.get('name') ?? '').trim();
   const email = String(formData.get('email') ?? '').trim();

package/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) {
-    // Register at the site root so the worker's scope is the whole origin.
+    // The framework serves your public/sw.js at the site root /sw.js (with a
+    // Service-Worker-Allowed: / header), so the worker's scope is the whole origin.
     navigator.serviceWorker.register('/sw.js');
   }
 }</code></pre>

package/templates/gallery/modules/components/components/browser/counter-card.test.js

@@ -0,0 +1,36 @@
+// Co-located browser test for the <counter-card> component. This is the webjs
+// component-test SHAPE, so copy it for your own components:
+//   - It runs in REAL Chromium (webjs test --browser, or npx wtr), not jsdom. If
+//     the browser binary is missing, install it once: npx playwright install chromium.
+//   - The runner's mocha UI is `tdd`, so use suite() / test(), NOT describe / it().
+//   - There is NO assertion library in the importmap (no chai, no expect). Throw
+//     to fail. A tiny inline `assert` is plenty.
+//   - `ssrFixture` server-renders AND hydrates the component, so you exercise the
+//     REAL SSR output and the client interactivity, not a jsdom approximation.
+// It lives NEXT TO the component (a `browser/` dir inside the module), the
+// co-located default; the runner discovers browser tests under any browser dir.
+import { html } from '@webjsdev/core';
+import { ssrFixture } from '@webjsdev/core/testing';
+import '../counter-card.ts';
+
+const assert = (cond, msg) => { if (!cond) throw new Error(msg || 'assertion failed'); };
+
+suite('<counter-card>', () => {
+  test('SSRs its initial state and the default label', async () => {
+    const el = await ssrFixture(html`<counter-card></counter-card>`);
+    assert(el.textContent.includes('0'), 'the count starts at 0');
+    assert(el.textContent.includes('Clicks'), 'the default label renders');
+  });
+
+  test('reads the label reactive prop', async () => {
+    const el = await ssrFixture(html`<counter-card label="Taps"></counter-card>`);
+    assert(el.textContent.includes('Taps'), 'the provided label renders');
+  });
+
+  test('increments on click (hydrated interactivity)', async () => {
+    const el = await ssrFixture(html`<counter-card></counter-card>`);
+    el.querySelector('button').click();
+    await el.updateComplete;
+    assert(el.textContent.includes('1'), 'the count becomes 1 after one click');
+  });
+});

package/templates/gallery/modules/todo/queries/list-todos.server.ts

@@ -14,6 +14,12 @@ export async function listTodos(): Promise<Todo[]> {
   // 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 the Database (Drizzle) section in this app's AGENTS.md.
+  //
+  // Two equivalent read styles, both fine: the relational query API
+  // (`db.query.todos.findFirst({ where: { id } })` / `findMany`, used here and in
+  // toggle-todo) reads by an object filter; the core builder
+  // (`db.select().from(todos).where(eq(todos.id, id))`) reads with the `eq()`
+  // helper. Reach for whichever fits; the relational form is terser for by-id reads.
   const rows = await db.query.todos.findMany({ orderBy: { createdAt: 'desc' } });
   return rows as Todo[];
 }

package/templates/test/hello/browser/hello.test.js

@@ -3,6 +3,12 @@
  *
  * Run:  webjs test --browser
  *       npx wtr
+ * First run only, if Chromium is missing:  npx playwright install chromium
+ *
+ * The runner's mocha UI is `tdd`: use suite() / test() (NOT describe / it), and
+ * throw to fail (there is no chai / expect in the importmap; a tiny inline assert
+ * like the one below is the idiom). See modules/components/components/browser for
+ * a co-located COMPONENT browser test using ssrFixture.
  *
  * Tests here have full access to real browser APIs: Shadow DOM,
  * adoptedStyleSheets, IntersectionObserver, events, etc.

package/templates/web-test-runner.config.js

@@ -33,7 +33,15 @@ export default {
   // Browser tests are `.js` (web-test-runner serves them through its own test
   // framework); the components + modules they import are `.ts`, served
   // transformed by the webjs middleware below.
-  files: ['test/**/browser/**/*.test.js'],
+  // Browser tests live under any `browser/` dir: the top-level `test/<feature>/
+  // browser/`, OR co-located next to the code they exercise (a component's
+  // `modules/<feature>/components/browser/`, the modules-architecture default).
+  files: [
+    'test/**/browser/**/*.test.js',
+    'app/**/browser/**/*.test.js',
+    'modules/**/browser/**/*.test.js',
+    'components/**/browser/**/*.test.js',
+  ],
   // webjs's importmap resolves `@webjsdev/core`, the `#` app aliases, and
   // vendors, so web-test-runner must NOT rewrite bare specifiers to
   // node_modules paths.