@webjsdev/cli 0.10.37 → 0.10.39

package/lib/doctor.js

@@ -4,9 +4,10 @@
  * WebJs has unusually many fragile preconditions, each an independent failure
  * mode a contributor onboarding to an existing repo only hits at runtime: the
  * Node 24+ strip-types floor, the `erasableSyntaxOnly` TS flag, importmap pin
- * freshness, env drift vs `.env.example`, `@webjsdev/*` version coherence, and
- * the git pre-commit hook activation. `webjs doctor` verifies each one up front
- * and prints pass/warn/fail with an actionable fix line.
+ * freshness, env drift vs `.env.example`, `@webjsdev/*` version coherence,
+ * whether the framework even resolves from the app dir (the fresh-git-worktree
+ * trap, #954), and the git pre-commit hook activation. `webjs doctor` verifies
+ * each one up front and prints pass/warn/fail with an actionable fix line.
  *
  * This module is PURE: `runDoctorChecks(appDir, opts?)` reads files (and, for
  * the pin check, optionally the network), but NEVER calls `process.exit` and
@@ -25,7 +26,8 @@
  *     app's own runtime concern, never a doctor hard-fail: a missing tsconfig
  *     (a JS-only app legitimately has none), env drift, an outdated or
  *     unverifiable vendor pin, a `@webjsdev/*` version drift or missing install,
- *     and a missing/non-executable git hook.
+ *     an unresolvable framework (a worktree with no node_modules, #954), and a
+ *     missing/non-executable git hook.
  *   - 'pass' is the green path.
  *
  * Every NETWORK touch (only the vendor-pin freshness check) is BEST-EFFORT: a
@@ -37,6 +39,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import { createRequire } from 'node:module';
 import { checkNodeInline } from './node-preflight.js';
 
 /**
@@ -842,6 +845,119 @@ async function checkElisionCarriers(appDir) {
   };
 }
 
+/**
+ * ADVISORY: the delivered app still rides the scaffold shell. AGENTS.md /
+ * CONVENTIONS.md item 6 asks a UI app to own its design (layout, palette,
+ * typography, chrome); the scaffold is a teaching artifact, not a starting
+ * design. WARN-level and never a hard fail: a reading column or a theme toggle
+ * CAN be a legitimate choice, so this nudges, it does not gate. The signal is
+ * objective (distinctive scaffold-authored chrome strings still present in the
+ * root layout), not a judgment of taste. Two or more tells is the threshold.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkScaffoldDesign(appDir) {
+  const name = 'App design (own design, not the scaffold shell)';
+  let layoutSrc = '';
+  for (const ext of ['ts', 'js', 'mts', 'mjs']) {
+    const p = join(appDir, 'app', `layout.${ext}`);
+    if (existsSync(p)) { layoutSrc = await readFile(p, 'utf8').catch(() => ''); break; }
+  }
+  if (!layoutSrc) {
+    return { name, status: 'pass', message: 'no app/layout to analyse' };
+  }
+  const { scaffoldShellTells } = await import('./design-bar.js');
+  const tells = scaffoldShellTells(layoutSrc);
+  if (tells.length < 2) {
+    return { name, status: 'pass', message: 'app/layout does not look like the unmodified scaffold shell' };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `app/layout still carries ${tells.length} scaffold design signal(s): ${tells.join(', ')}. ` +
+      'A delivered UI app should own its design (layout AND palette), not adapt the scaffold.',
+    fix: 'Design the app\'s own layout, palette, typography, and chrome from what the app IS (a centered board, a full-bleed dashboard, ...), not the scaffold\'s exact 760px reading column, its "Built with webjs" attribution footer, or the unmodified starter palette values (the theme-toggle and --header-h are keep-infrastructure). Recoloring the scaffold is not a redesign. Render the app and look at it. See AGENTS.md / CONVENTIONS.md item 6.',
+  };
+}
+
+/**
+ * Probe whether `@webjsdev/core` resolves from `appDir`. Node resolution is
+ * directory-relative, so this must probe FROM the app (not the CLI's own
+ * location, which resolves the framework fine from a global install even when
+ * the app cannot). A no-op-cheap resolve, no I/O beyond what Node's resolver
+ * does, no network. Returns true when the framework resolves, false otherwise.
+ * @param {string} appDir
+ * @returns {boolean}
+ */
+export function frameworkResolves(appDir) {
+  try {
+    // The base file need not exist; createRequire only uses it to anchor the
+    // node_modules lookup at appDir.
+    const require = createRequire(join(appDir, '__webjs_resolve_probe__.js'));
+    require.resolve('@webjsdev/core');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CHECK 8, framework resolvability (#954). WARN when `@webjsdev/core` cannot be
+ * resolved FROM the app directory, which is the fresh-git-worktree trap: a
+ * worktree does not copy `node_modules`, so a plain `webjs dev` there dies at
+ * SSR with a raw `ERR_MODULE_NOT_FOUND: Cannot find package '@webjsdev/core'`
+ * whose remedy is not obvious. Silent PASS when the framework resolves (the
+ * common case), so this never slows a healthy app. WARN (not a hard fail): it
+ * is a setup/environment concern, the same tier as the version-coherence check.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkFrameworkResolves(appDir) {
+  const name = 'framework-resolve';
+  if (frameworkResolves(appDir)) {
+    return { name, status: 'pass', message: '@webjsdev/core resolves from the app directory.' };
+  }
+  const hasNodeModules = existsSync(join(appDir, 'node_modules'));
+  // A git worktree checks out `.git` as a FILE (a gitdir pointer), not a
+  // directory. That, plus a missing node_modules, is the exact #954 cause.
+  let isWorktree = false;
+  try {
+    isWorktree = statSync(join(appDir, '.git')).isFile();
+  } catch {
+    isWorktree = false;
+  }
+  if (isWorktree && !hasNodeModules) {
+    return {
+      name,
+      status: 'warn',
+      message:
+        '@webjsdev/core cannot be resolved from this directory, and this is a git worktree with no ' +
+        'node_modules. Git worktrees do not copy node_modules, so the framework is unresolvable here ' +
+        'and `webjs dev` / `webjs start` would fail at SSR with a raw ERR_MODULE_NOT_FOUND.',
+      fix:
+        'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
+        'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`).',
+    };
+  }
+  if (!hasNodeModules) {
+    return {
+      name,
+      status: 'warn',
+      message: '@webjsdev/core cannot be resolved from this directory (no node_modules present).',
+      fix: 'Run `npm install` in the app directory so the framework resolves.',
+    };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      '@webjsdev/core cannot be resolved from this directory even though node_modules exists ' +
+      '(a partial or corrupted install).',
+    fix: 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).',
+  };
+}
+
 export async function runDoctorChecks(appDir, opts = {}) {
   const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
   const results = await Promise.all([
@@ -851,9 +967,11 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkVendorPin(appDir, opts),
     checkVendorGitignore(appDir),
     checkWebjsVersions(appDir),
+    Promise.resolve(checkFrameworkResolves(appDir)),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
     checkElisionCarriers(appDir),
+    checkScaffoldDesign(appDir),
   ]);
   return results;
 }

package/lib/runtime-rewrite.js

@@ -142,9 +142,10 @@ export function bunifyDockerfile(s) {
     .replace(
       /# `npm start` is a thin alias[\s\S]*?the migrate no longer depends on an npm `prestart` hook\.\nCMD \["npm", "start"\]/,
       '# `bun --bun run start` runs the `start` script on Bun (the server serves via\n' +
-      '# Bun.serve). `webjs start` runs the `webjs.start.before` step (`webjs db migrate`,\n' +
-      '# which resolves drizzle-kit and runs it under Bun, no npx, #570), idempotent / a\n' +
-      '# no-op with no pending migrations, then serves on $PORT.\n' +
+      '# Bun.serve). `webjs start` runs the `webjs.start.before` steps: `webjs db migrate`\n' +
+      '# (resolves drizzle-kit and runs it under Bun, no npx, #570) and, for a UI app,\n' +
+      '# the Tailwind compile under `bun --bun` (no Node / npm in the image, #947), both\n' +
+      '# idempotent, then serves on $PORT.\n' +
       'CMD ["bun", "--bun", "run", "start"]',
     );
 }

package/lib/saas-template.js

@@ -118,6 +118,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    ...(process.env.AUTH_GOOGLE_ID ? [Google({ clientId: process.env.AUTH_GOOGLE_ID, clientSecret: process.env.AUTH_GOOGLE_SECRET })] : []),",
     "  ],",
     "  secret: authSecret,",
+    "  // A failed credentials sign-in 302s to `${pages.error}?error=CredentialsSignin`.",
+    "  // Point it at /login so app/login/page.ts reads searchParams.error and shows a",
+    "  // message, instead of the createAuth default (the home page) swallowing the error.",
+    "  pages: { error: '/login' },",
     "});",
     "",
   ].join('\n'));
@@ -339,7 +343,17 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "",
     "export const metadata = { title: 'Login' };",
     "",
-    "export default function LoginPage() {",
+    "// A failed sign-in 302s back here with ?error=... (createAuth is configured",
+    "// with pages.error: '/login' in lib/auth.server.ts). Map the code to a plain",
+    "// message so a bad password gets visible feedback instead of a silent bounce.",
+    "function errorMessage(code: string | undefined): string | null {",
+    "  if (!code) return null;",
+    "  if (code === 'CredentialsSignin') return 'Invalid email or password.';",
+    "  return 'Could not sign you in. Please try again.';",
+    "}",
+    "",
+    "export default function LoginPage({ searchParams }: { searchParams: { error?: string } }) {",
+    "  const error = errorMessage(searchParams.error);",
     "  return html`",
     "    <div class=\"max-w-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
@@ -348,6 +362,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "          <p class=${cardDescriptionClass()}>Welcome back: log in to continue.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
+    "          ${error ? html`<p role=\"alert\" class=\"mb-4 text-sm text-destructive\">${error}</p>` : ''}",
     "          <form method=\"POST\" action=\"/api/auth/signin/credentials\" class=\"flex flex-col gap-4\">",
     "            <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->",
     "            <input type=\"hidden\" name=\"redirectTo\" value=\"/dashboard\">",
@@ -461,12 +476,39 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "",
   ].join('\n'));
 
+  // app/dashboard/layout.ts: a thin sub-nav shared by every /dashboard page
+  // (page.ts and settings/page.ts). It carries the logout control so a signed-in
+  // user can end the session from anywhere under /dashboard.
+  await writeFile(join(appDir, 'app', 'dashboard', 'layout.ts'), [
+    "import { html } from '@webjsdev/core';",
+    "import { buttonClass } from '#components/ui/button.ts';",
+    "",
+    "// Nested layout for the protected /dashboard subtree. Logout is a plain",
+    "// <form method=\"POST\"> posting to the createAuth signout route: it clears the",
+    "// session cookie and 302s home, and works with JS off (progressive-enhancement",
+    "// default). signOut is server-only (lib/auth.server.ts), so we POST to its route",
+    "// rather than import it into a browser-shipping page. After signout the dashboard",
+    "// middleware bounces any later /dashboard visit to /login.",
+    "export default function DashboardLayout({ children }: { children: unknown }) {",
+    "  return html`",
+    "    <nav class=\"flex items-center gap-4 mb-6 pb-4 border-b border-border\">",
+    "      <a href=\"/dashboard\" class=\"text-sm font-medium hover:underline\">Dashboard</a>",
+    "      <a href=\"/dashboard/settings\" class=\"text-sm font-medium hover:underline\">Settings</a>",
+    "      <form method=\"POST\" action=\"/api/auth/signout\" class=\"ml-auto\">",
+    "        <button class=${buttonClass({ variant: 'outline', size: 'sm' })} type=\"submit\">Log out</button>",
+    "      </form>",
+    "    </nav>",
+    "    ${children}",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
   // app/dashboard/page.ts
   await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
     "import { currentUser } from '#modules/auth/queries/current-user.server.ts';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '#components/ui/card.ts';",
-    "import { buttonClass } from '#components/ui/button.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass } from '#components/ui/card.ts';",
     "import { badgeClass } from '#components/ui/badge.ts';",
     "",
     "export const metadata = { title: 'Dashboard' };",
@@ -483,9 +525,6 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        <h2 class=${cardTitleClass()}>Welcome, ${user?.name || user?.email}!</h2>",
     "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
     "      </div>",
-    "      <div class=${cardContentClass()}>",
-    "        <a class=${buttonClass({ variant: 'outline' })} href=\"/dashboard/settings\">Settings</a>",
-    "      </div>",
     "    </div>",
     "  `;",
     "}",

package/package.json

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

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

@@ -48,21 +48,39 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   logic in `modules/`.
 - **Use a unique design, and redesign means more than recolor (UI apps).** Give
   the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
-  from what the app IS. Recoloring the scaffold and swapping the logo while
-  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
-  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
-  unique design. Decide from scratch whether this app even needs a header or
-  footer, what nav (if any), and what layout fits (a centered board, a full-bleed
-  dashboard, a split, a single card). The scaffold ships a
-  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
-  you remove or replace the "Built with webjs" branding. Self-audit before
-  finishing: nothing should read as the scaffold example (no "Built with webjs"
-  footer, no leftover example nav, no default reading column unless it truly
-  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
-  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
-  utilities wherever they reach, and use custom CSS only for what utilities
-  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
-  gradients). The `api` template has no UI, so this does not apply there.
+  from what the app IS. `app/layout.ts` ships as a MINIMAL shell (theme, design
+  tokens, and Tailwind infra, then `${children}` in a bare padded container) with
+  NO header, nav, footer, or reading column: design the app's own chrome from
+  scratch. Decide whether it needs a header at all, a nav (or none), a footer, a
+  sidebar, a centered reading column, or a full-bleed canvas, from what fits the
+  app. `LAYOUT-REFERENCE.md` at the project root is a complete worked layout to
+  learn the patterns from, then build your own. Two `webjs-scaffold-placeholder`
+  markers gate `webjs check`: the minimal shell ("design your layout from
+  scratch") and the palette block ("own the colors"), so check fails until each
+  is addressed. Keep the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and set the token VALUES to your own palette;
+  run `webjs check --clear-placeholders` to keep the starter palette
+  deliberately. 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.
+- **Render the app and LOOK before you call UI work done (every agent, not just one harness).**
+  You write CSS blind, so a layout or design defect ships silently: `webjs check`
+  and `webjs typecheck` pass even when a component collapses, grid cells are
+  uneven, the layout resizes as it fills, or the app just kept the scaffold's
+  colors. Static tools give no failure signal for this. The only thing that
+  catches it is rendering the app and looking at the pixels. So for ANY page,
+  layout, or component work: run it (`webjs dev`), open every route you changed in
+  a real browser (drive it with your harness's browser tool or MCP if it has one,
+  otherwise open it yourself and screenshot), and PLAY THROUGH every state (empty,
+  filled, win, draw, reload, narrow and wide, light and dark). Confirm nothing
+  collapses or reflows, that cells stay equal, that the design is the app's OWN,
+  and that both themes read. Ship a real-browser test (`webjs test --browser`) for
+  the mechanical floor (measure `getBoundingClientRect()` and assert cells stay
+  equal across a move). Fix and re-render until it holds, then state in your final
+  message what you rendered and confirmed. Claude Code additionally ENFORCES this
+  via the `webjs-design-review` skill plus a Stop hook, but the discipline is
+  harness-agnostic and this rule is the source of truth for every agent.
 - **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/design-review-before-stop.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# Claude Code Stop hook: render-and-look before finishing UI work.
+#
+# An AI agent writes CSS blind (it never renders), and layout / design defects
+# have NO failure signal: `webjs check` and `typecheck` pass, the app runs. So a
+# collapsed board, uneven cells, a layout that resizes as it fills, or an app
+# that just kept the scaffold's design all ship silently. The one thing that
+# catches them is looking at the rendered pixels. This backstop fires at the END
+# of a turn that touched UI files and reminds you to render the app and inspect
+# every state (see the webjs-design-review skill + CONVENTIONS item 6) before you
+# stop. Loop-safe (fires at most once per stop) and skipped when no UI changed.
+#
+# Disable with WEBJS_NO_DESIGN_STOP=1.
+
+set -uo pipefail
+payload=$(cat 2>/dev/null || true)
+
+if [ "${WEBJS_NO_DESIGN_STOP:-}" = "1" ]; then exit 0; fi
+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
+
+# Did this turn touch UI surface? A component, a page/layout, or app styling.
+ui_changed=$(git status --porcelain --untracked-files=all 2>/dev/null \
+  | grep -vE '(^|/)(node_modules|\.webjs)(/|$)' \
+  | grep -cE '(app/.*(page|layout)\.(t|j)sx?$)|(components/.*\.(t|j)sx?$)|(modules/.*components/.*\.(t|j)sx?$)|(\.css$)' || true)
+
+if [ -z "$ui_changed" ] || [ "$ui_changed" -lt 1 ]; then exit 0; fi
+
+reason="You changed UI in this turn but a design/layout defect has no failing test: check and typecheck pass even when a component collapses, cells are uneven, the layout shifts as it fills, or the app just resembles the scaffold. Before you stop, RENDER the app and LOOK at it: start it (webjs dev / start), open the routes you changed in a browser, and PLAY THROUGH every state (fill the board, win, draw, reload). Confirm (1) nothing collapses or resizes, cells stay equal; (2) the design is the app's OWN (layout, palette, typography, chrome), not the scaffold shell or its default colors; (3) it looks correct in light AND dark. See the webjs-design-review skill and CONVENTIONS item 6. If you already rendered and verified it this turn, say so in your final message. Disable this backstop with WEBJS_NO_DESIGN_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/hooks/route-skills.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# UserPromptSubmit hook: route a UI-building prompt to the design-review
+# skill, so it is never silently skipped.
+#
+# Why this exists: a Skill is model-invoked, so it fires only when the model
+# judges the prompt to match, and that judgement is exactly what fails for
+# design work ("build a tic-tac-toe app" reads as backend/logic work and the
+# render-and-look step gets skipped, shipping a collapsed or scaffold-looking
+# UI). A hook is deterministic: it runs on every prompt, decides from the
+# prompt TEXT, and injects a directive the model reads before acting. It
+# cannot invoke the Skill itself (the harness forbids that); the strongest
+# lever is UserPromptSubmit additionalContext.
+#
+# Output contract: print one JSON object with
+# hookSpecificOutput.additionalContext and exit 0. Never block (exit 2 would
+# erase the prompt); routing informs, it does not gate.
+
+set -euo pipefail
+payload=$(cat)
+prompt=$(printf '%s' "$payload" | jq -r '.prompt // empty' 2>/dev/null || true)
+[ -z "$prompt" ] && exit 0
+lc=$(printf '%s' "$prompt" | tr '[:upper:]' '[:lower:]')
+has() { printf '%s' "$lc" | grep -Eq "$1"; }
+
+# UI / app-building intent: any request to build/create/change something the
+# user will SEE. Broad on purpose (a false positive just reminds you to look).
+if has '(build|create|make|add|design|redesign|style|implement|scaffold).{0,40}(app|page|layout|component|screen|view|board|form|dashboard|ui|site|game|list|table|card|nav|header|footer|modal|button|theme)' \
+   || has '(make|help me|let'\''s).{0,20}(look|prettier|beautiful|nicer|design)' \
+   || has '(tic.?tac.?toe|todo|blog|dashboard|landing|storefront|kanban|chat)'; then
+  ctx="ROUTING: this prompt involves UI work. Invoke the webjs-design-review skill (Skill tool) as part of this task: after building/changing any page, layout, or component and BEFORE reporting the work done, render the app in a real browser and LOOK at every state, confirming the app owns its design (layout + palette + type, not the scaffold), nothing collapses or resizes, cells stay even, and light + dark both read. A design/layout defect has NO failing test, so the render-and-look is the only check that catches it."
+  jq -n --arg c "$ctx" '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", additionalContext: $c}}'
+fi
+
+exit 0

package/templates/.claude/settings.json

@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/route-skills.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",
@@ -73,6 +83,10 @@
           {
             "type": "command",
             "command": ".claude/hooks/commit-before-stop.sh"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/design-review-before-stop.sh"
           }
         ]
       }

package/templates/.claude/skills/webjs-design-review/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: webjs-design-review
+description: >-
+  Render-and-look review for ANY UI work in a WebJs app. Invoke after building
+  or changing a page, layout, or component, and before you report the work done.
+  Triggers: "build", "create", "add a page", "component", "layout", "style",
+  "design", "UI", "screen", "board", "form", "dashboard", "make it look".
+---
+
+# Render the app and LOOK before you call UI work done
+
+You write CSS blind. You never see the pixels, so a whole class of defects ships
+silently: `webjs check` passes, `webjs typecheck` passes, the server boots, and
+the app still looks broken. A collapsed component, cells of unequal size, a
+layout that resizes as it fills with content, text that overflows its box, an
+app that just kept the scaffold's colors and chrome, none of these fail a test.
+The only thing that catches them is rendering the app and looking at it.
+
+So for ANY work that touches a page, layout, or component, this is the loop:
+
+## 1. Run the app and open what you changed
+
+```sh
+webjs dev            # or: webjs start, for the production render
+```
+
+Open every route you touched in a real browser. Use the browser MCP
+(`mcp__playwright__*` or `mcp__chrome-devtools__*`) if available so you can drive
+and screenshot it; otherwise open it yourself and take screenshots.
+
+## 2. Drive EVERY state, not just the first paint
+
+The first paint is the easy case. Bugs hide in the states you reach by
+interacting. Play the app the way a user will:
+
+- A game board: play a full game. Fill it. Win. Draw. Reset. Watch whether the
+  board or its cells change size as marks appear (they must NOT).
+- A list: empty, one item, many items, an item long enough to wrap.
+- A form: empty, invalid, submitted, error returned, success.
+- Anything async: loading, loaded, error, refetch.
+
+Reload each state. Resize the window narrow (mobile) and wide.
+
+## 3. Confirm the things a test can't
+
+Look at each state and confirm, with your eyes:
+
+1. **Nothing collapses, overflows, or resizes.** A container is the size it
+   should be (not 0-height, not collapsed to its content when it should fill).
+   Grid/flex children that should be equal ARE equal, and STAY equal as content
+   changes. Text stays inside its box.
+2. **The design is this app's OWN.** Not the scaffold shell, not its default
+   color tokens. The palette (real `oklch`/hex values, not just shadcn token
+   NAMES), the typography, the layout, and the chrome are chosen for THIS app.
+   "It still looks like the starter" is a defect to fix, not ship.
+3. **Light AND dark both look right.** Toggle the theme. Check contrast, that
+   nothing disappears against its background, that borders and shadows read.
+4. **It still renders with JavaScript OFF.** WebJs is SSR + progressive
+   enhancement, so the page must read and look right with no JS (disable it in
+   devtools, or load in a JS-off context). Content shows, `<a>` navigates,
+   forms submit, and CRUCIALLY the CSS is fully applied (the app links a static
+   compiled `public/tailwind.css`, so utilities resolve with no JS). An app that
+   goes unstyled or blank with JS off is a broken first paint, not a design to
+   ship.
+
+## 4. Iterate until it holds, then say what you saw
+
+If any of the above is wrong, fix it and re-render. Do not stop on the first
+render. When it holds, state in your final message WHAT you rendered and WHAT
+you confirmed (which states, light + dark), so the review is on the record.
+
+---
+
+**Why this is a skill and not just a test:** a real-browser test
+(`webjs test --browser`) catches the mechanical failures (collapse, uneven
+cells, reflow) and you SHOULD ship one. There is no framework helper for this; a
+layout-stability check is a few lines you write against your own component (in a
+`*/test/**/browser/*.test.js`): measure `getBoundingClientRect()` on the grid
+children and assert they stay equal-sized before AND after a move, so a collapse
+or reflow FAILS the test. But "looks like the scaffold", "the
+palette is bland", "the spacing is off", "it's ugly in dark mode" are judgment
+calls no assertion makes for you. That is what this human-in-the-loop look is
+for. Do both: the test for the mechanical floor, the look for everything above
+it. See CONVENTIONS item 6 and `agent-docs/styling.md`.

package/templates/.cursorrules

@@ -48,21 +48,39 @@ cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
   `lib/utils/`, feature logic in `modules/`.
 - **Use a unique design, and redesign means more than recolor (UI apps).** Give
   the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
-  from what the app IS. Recoloring the scaffold and swapping the logo while
-  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
-  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
-  unique design. Decide from scratch whether this app even needs a header or
-  footer, what nav (if any), and what layout fits (a centered board, a
-  full-bleed dashboard, a split, a single card). The scaffold ships a
-  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
-  you remove or replace the "Built with webjs" branding. Self-audit before
-  finishing: nothing should read as the scaffold example (no "Built with webjs"
-  footer, no leftover example nav, no default reading column unless it truly
-  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
-  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
-  utilities wherever they reach, and use custom CSS only for what utilities
-  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
-  gradients). The `api` template has no UI, so this does not apply there.
+  from what the app IS. `app/layout.ts` ships as a MINIMAL shell (theme, design
+  tokens, and Tailwind infra, then `${children}` in a bare padded container) with
+  NO header, nav, footer, or reading column: design the app's own chrome from
+  scratch. Decide whether it needs a header at all, a nav (or none), a footer, a
+  sidebar, a centered reading column, or a full-bleed canvas, from what fits the
+  app. `LAYOUT-REFERENCE.md` at the project root is a complete worked layout to
+  learn the patterns from, then build your own. Two `webjs-scaffold-placeholder`
+  markers gate `webjs check`: the minimal shell ("design your layout from
+  scratch") and the palette block ("own the colors"), so check fails until each
+  is addressed. Keep the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and set the token VALUES to your own palette;
+  run `webjs check --clear-placeholders` to keep the starter palette
+  deliberately. 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.
+- **Render the app and LOOK before you call UI work done (every agent, not just one harness).**
+  You write CSS blind, so a layout or design defect ships silently: `webjs check`
+  and `webjs typecheck` pass even when a component collapses, grid cells are
+  uneven, the layout resizes as it fills, or the app just kept the scaffold's
+  colors. Static tools give no failure signal for this. The only thing that
+  catches it is rendering the app and looking at the pixels. So for ANY page,
+  layout, or component work: run it (`webjs dev`), open every route you changed in
+  a real browser (drive it with your harness's browser tool or MCP if it has one,
+  otherwise open it yourself and screenshot), and PLAY THROUGH every state (empty,
+  filled, win, draw, reload, narrow and wide, light and dark). Confirm nothing
+  collapses or reflows, that cells stay equal, that the design is the app's OWN,
+  and that both themes read. Ship a real-browser test (`webjs test --browser`) for
+  the mechanical floor (measure `getBoundingClientRect()` and assert cells stay
+  equal across a move). Fix and re-render until it holds, then state in your final
+  message what you rendered and confirmed. Claude Code additionally ENFORCES this
+  via the `webjs-design-review` skill plus a Stop hook, but the discipline is
+  harness-agnostic and this rule is the source of truth for every agent.
 - **Only three templates exist:** `webjs create <name>` (default
   full-stack), `--template api`, `--template saas`. The CLI rejects any
   other `--template` value. Pick: