@webjsdev/cli 0.10.69 → 0.10.71

package/bin/webjs.js

@@ -99,6 +99,8 @@ const USAGE = `webjs commands:
   webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
                                                   --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / elision / check)
+  webjs source <Export> [--pkg <name>]            Print the signature plus doc comment of one export from the installed @webjsdev/*
+                                                  packages (typed declarations first, the authored JSDoc as the fallback); exit 1 on a miss
   webjs doctor [--json] [--strict]                Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision, component elision, un-versioned stylesheet links).
                                                   --json emits the structured results (with stable codes). --strict additionally fails on every remaining warning.
                                                   Per-check severity is CONFIG: map a code to off/warn/error under "webjs": { "doctor": { "gate": {...} } }
@@ -326,6 +328,19 @@ const HELP = {
     summary: 'Start the read-only MCP server (routes / actions / components / elision / check + a docs/source knowledge layer).',
     examples: ['webjs mcp'],
   },
+  source: {
+    usage: 'webjs source <Export> [--pkg <name>]',
+    summary: 'Print one framework export\'s signature plus the doc comment above it, read from the installed @webjsdev/* packages (the typed declarations first, the authored JSDoc when none carries a doc; every overload). The cheap way to check a contract before opening the source file.',
+    options: [
+      { flag: '--pkg <name>', description: 'Search one package only: core, server, cli, ui or intellisense.' },
+    ],
+    notesTitle: 'Exit status',
+    notes: [
+      '0 when at least one declaration printed; 1 on a miss (the message names the packages that were searched).',
+      'The read-only MCP `source` tool returns the same text for { export: "<Export>" }.',
+    ],
+    examples: ['webjs source createAuth', 'webjs source optimistic --pkg core', 'webjs source getFileStore'],
+  },
   version: {
     usage: 'webjs version',
     summary: 'Print the installed @webjsdev/cli version. Also available as webjs --version / -v.',
@@ -1968,6 +1983,29 @@ Full docs: https://webjs.dev/docs`);
         `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
       process.exit(1);
     }
+    case 'source': {
+      // One export's signature plus its doc comment from the installed
+      // @webjsdev/* packages (#1623): the same lookup the MCP `source` tool
+      // runs for its `export` arg, so a Bash-only agent (no MCP) checks a
+      // contract for the price of the declaration instead of the whole file.
+      // Read-only: it reads the resolved package roots and loads no module.
+      const name = rest.find((a) => !a.startsWith('--'));
+      const pkgAt = rest.indexOf('--pkg');
+      const pkg = pkgAt >= 0 ? rest[pkgAt + 1] : undefined;
+      if (!name) {
+        console.error('usage: webjs source <Export> [--pkg core|server|cli|ui|intellisense]');
+        process.exit(1);
+      }
+      const { lookupExport, resolveFrameworkRoots } = await import('@webjsdev/mcp');
+      const { existsSync, readdirSync } = await import('node:fs');
+      const { readFile } = await import('node:fs/promises');
+      const roots = resolveFrameworkRoots(process.cwd(), { exists: existsSync });
+      const readdir = (d) => readdirSync(d, { withFileTypes: true }).map((e) => ({ name: e.name, isDir: e.isDirectory() }));
+      const out = await lookupExport({ roots, readFile, readdir }, name, pkg);
+      console.log(out);
+      if (!/^@webjsdev\//m.test(out)) process.exit(1);
+      break;
+    }
     case 'mcp': {
       // Read-only MCP server (#262, #415) over stdio. STDOUT is the JSON-RPC
       // channel, so nothing here may write to stdout: the data functions are

package/lib/app-icon.js

@@ -43,13 +43,3 @@ export function appManifest(name) {
     icons: [{ src: '/icon.svg', sizes: 'any', type: 'image/svg+xml' }],
   }, null, 2) + '\n';
 }
-
-/**
- * Whether an SVG is the WebJs brand mark earlier scaffolds shipped as
- * `public/favicon.svg` (a rounded square with the gallery's grey gradient).
- * Apps made before the placeholder still serve it as their favicon.
- * @param {string} svg
- */
-export function isLegacyBrandFavicon(svg) {
-  return /aria-label="WebJs"/.test(svg) && /<linearGradient id="wj"/.test(svg);
-}

package/lib/create.js

@@ -444,9 +444,20 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       '@webjsdev/cli': 'latest',
       '@webjsdev/core': 'latest',
       '@webjsdev/server': 'latest',
+      // What the production BOOT runs, so production dependencies (#1606):
+      // `webjs start` runs the `webjs.start.before` steps at every boot,
+      // `webjs db migrate` (drizzle-kit) and, on a UI app, the Tailwind
+      // compile. The Dockerfile installs production dependencies only, so as
+      // devDependencies these would be missing from the image and the boot
+      // would fail. `tailwindcss` itself is declared too (#1493):
+      // public/input.css starts with `@import "tailwindcss"`, and bun's
+      // isolated linker and pnpm link only declared packages, so leaving it
+      // transitive (via @tailwindcss/cli) fails the compile with
+      // `Can't resolve 'tailwindcss'`. The api template has no CSS.
+      'drizzle-kit': '1.0.0-rc.3',
+      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
     },
     devDependencies: {
-      '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
@@ -467,15 +478,6 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // assertNoA11yViolations() test helper from @webjsdev/core/testing.
       // Test-only: dynamically imported, never shipped to the app runtime.
       'axe-core': '^4.10.0',
-      // The Tailwind v4 CLI that css:build runs to compile public/input.css into
-      // the static public/tailwind.css the layout links. UI templates only (the
-      // api template has no CSS). Build tooling, never shipped to the runtime.
-      // `tailwindcss` itself is declared too (#1493): public/input.css starts
-      // with `@import "tailwindcss"`, so the app imports that package directly.
-      // Leaving it transitive (via @tailwindcss/cli) breaks under bun's isolated
-      // linker and pnpm, which link only declared packages into the app's
-      // node_modules, so the compile fails with `Can't resolve 'tailwindcss'`.
-      ...(isApi ? {} : { '@tailwindcss/cli': '^4.1.0', tailwindcss: '^4.1.0' }),
       // tsserver plugin, wired into tsconfig below. Gives the language
       // INTELLIGENCE (go-to-def, completions, diagnostics, hover inside html``
       // templates) in any tsserver editor with NO editor plugin installed,
@@ -583,9 +585,13 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // layout already writes asset(), so a fresh app is green on day one.
       // Two checks are fatal with no entry here at all, NODE_VERSION and
       // TSCONFIG_ERASABLE, because either would 500 the app at runtime;
-      // everything else keeps its default warn. Add a code with "off" to
+      // DARK_THEME_UNREACHABLE is at error too: AGENTS.md mandates light-dark()
+      // tokens, the generated layout writes them, and a layout that drops them
+      // leaves the stylesheet's .dark block dead and the OS setting ignored
+      // (#1628); elsewhere it is a design convention and stays a warning.
+      // Everything else keeps its default warn. Add a code with "off" to
       // silence it, or "error" to make it fatal too.
-      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error' } },
+      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error', DARK_THEME_UNREACHABLE: 'error' } },
       // The dependency audit's allowlist (#1492), the ONE place an accepted
       // advisory is listed, each with the reason it is safe. `webjs audit`
       // (the CI step below) fails on every other advisory at `level` or above,
@@ -1721,8 +1727,8 @@ ThemeToggle.register('theme-toggle');
 `);
   }
   console.log(`For AI agents, read this before editing:
-  • Read AGENTS.md first: it carries the build steps and a worked example of
-    every common pattern. .agents/skills/webjs/ is the deeper reference.
+  • Read AGENTS.md, then .agents/skills/webjs/SKILL.md. The skill is the guide
+    to building a WebJs app and routes to focused references on demand.
   • This scaffold is a minimal starting point, not a demo to prune. Grow the app
     in place: add routes under app/, components under components/, and features
     under modules/<feature>/, and keep server-only code behind .server.ts.

package/lib/dev-reload.js

@@ -68,7 +68,9 @@ export const KILL_TIMEOUT_MS = 2000;
  * @returns {boolean}
  */
 export function shouldIgnoreRestartPath(rel) {
-  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '');
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])db[\\/](?:dev\.db|migrations)/.test(rel || '')
+    // Tool output nothing serves, as the server's watcher skips it (watch-ignore.js).
+    || /(?:^|[\\/])(?:coverage|\.cache|\.nyc_output|test-results|playwright-report|\.turbo)(?:[\\/]|$)|\.log$|(?:^|[\\/])\.DS_Store$|\.swp$|~$/.test(rel || '');
 }
 
 /**

package/lib/doctor/codes.js

@@ -51,6 +51,7 @@ export const DOCTOR_CODES = {
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
   'workspace-overrides': 'WORKSPACE_OVERRIDES',
   'app-icon': 'APP_ICON',
+  'dark-theme': 'DARK_THEME_UNREACHABLE',
 };
 
 /**

package/lib/doctor/probes/app-icon.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { PLACEHOLDER_MARKER, isLegacyBrandFavicon } from '../../app-icon.js';
+import { PLACEHOLDER_MARKER } from '../../app-icon.js';
 
 /**
  * @typedef {import('../codes.js').DoctorResult} DoctorResult
@@ -12,11 +12,9 @@ function read(file) {
 }
 
 /**
- * Warn when the app's favicon is still the one `webjs create` shipped: the
- * neutral `app/icon.svg` placeholder, or the WebJs brand mark earlier
- * scaffolds put at `public/favicon.svg`. Either way every app made from the
- * scaffold shows the same tab icon, which reads as a demo rather than a
- * product. An app with no `app/` directory (a library, the api template with
+ * Warn when the app's favicon is still the neutral `app/icon.svg` placeholder
+ * `webjs create` shipped: every app made from the scaffold would show the same
+ * tab icon, which reads as a demo rather than a product. An app with no `app/` directory (a library, the api template with
  * no pages) passes.
  *
  * @param {string} appDir
@@ -25,12 +23,9 @@ function read(file) {
 export function checkAppIcon(appDir) {
   const name = 'app-icon';
   if (!existsSync(join(appDir, 'app'))) return { name, status: 'pass', message: 'no app/ directory to analyse' };
-  const fix = 'Replace app/icon.svg with an icon for this app (a simple symbol for what it is, in its own colours, legible at 16px), and delete public/favicon.svg plus any metadata.icons that still points at it.';
+  const fix = 'Replace app/icon.svg with an icon for this app (a simple symbol for what it is, in its own colours, legible at 16px).';
   if (read(join(appDir, 'app', 'icon.svg')).includes(PLACEHOLDER_MARKER)) {
     return { name, status: 'warn', message: 'app/icon.svg is still the scaffold placeholder icon', fix };
   }
-  if (isLegacyBrandFavicon(read(join(appDir, 'public', 'favicon.svg')))) {
-    return { name, status: 'warn', message: 'public/favicon.svg is still the WebJs mark an earlier scaffold shipped', fix };
-  }
   return { name, status: 'pass', message: 'the app has its own icon (or declares none)' };
 }

package/lib/doctor/probes/dark-theme.js

@@ -0,0 +1,91 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+const ROOT_LAYOUT = /^app\/layout\.(?:js|mjs|ts|mts)$/;
+/** Stylesheet sources: the Tailwind input and any hand-written sheet; never the compiled output. */
+const STYLE_SOURCE = /^(?:public|styles)\/(?:.+\/)?[^/]+\.css$/;
+const COMPILED_OR_VENDORED = /(?:^|\/)(?:tailwind\.css|node_modules\/|\.webjs\/|dist\/)/;
+/** A colour token definition: the two every palette starts from. */
+const TOKEN_DEF = /--(?:background|foreground)\s*:/;
+/** Any of these makes the dark half reachable. */
+const DUAL_TOKENS = /light-dark\s*\(/;
+const SCHEME_QUERY = /prefers-color-scheme/;
+/** A head script that applies a saved or detected theme. */
+const THEME_SCRIPT = /<script\b[^>]*>[\s\S]*?(?:prefers-color-scheme|localStorage|data-theme|classList\.(?:add|toggle)\(\s*['"`]dark['"`]|dataset\.theme)[\s\S]*?<\/script>/;
+
+/** CSS and JS block comments and line comments, so a commented-out token or hint does not count. */
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+/**
+ * The app's colour-token sources: the root layout (where the generated app
+ * writes its palette) and the stylesheet sources under `public/` and `styles/`.
+ * @param {string} appDir
+ * @returns {Promise<Array<{ rel: string, content: string }>>}
+ */
+async function tokenSources(appDir) {
+  /** @type {Array<{ rel: string, content: string }>} */
+  const out = [];
+  const read = async (rel) => {
+    try { out.push({ rel, content: await readFile(join(appDir, rel), 'utf8') }); } catch { /* unreadable: not a source */ }
+  };
+  for (const ext of ['ts', 'js', 'mts', 'mjs']) {
+    const rel = `app/layout.${ext}`;
+    if (existsSync(join(appDir, rel))) { await read(rel); break; }
+  }
+  for (const dir of ['public', 'styles']) {
+    const abs = join(appDir, dir);
+    if (!existsSync(abs)) continue;
+    for (const e of readdirSync(abs, { recursive: true, withFileTypes: true })) {
+      if (!e.isFile() || !e.name.endsWith('.css')) continue;
+      const rel = relative(appDir, join(e.parentPath || abs, e.name)).split('\\').join('/');
+      if (STYLE_SOURCE.test(rel) && !COMPILED_OR_VENDORED.test(rel)) await read(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * `DARK_THEME_UNREACHABLE` (#1628): the app defines colour tokens but nothing
+ * applies a dark half. The scaffold's stylesheet keeps the ui kit's `.dark`
+ * token block, and `AGENTS.md` asks for `light-dark()` tokens under
+ * `color-scheme: light dark`; a layout that uses neither, has no
+ * `prefers-color-scheme` rule and runs no theme script ships dead CSS and
+ * ignores the OS setting, which no light-mode screenshot reveals. A design
+ * convention rather than a runtime break, so it lives in doctor (WARN by
+ * default) and the scaffold gates it `error` because its AGENTS.md mandates
+ * the tokens. Silent when the app defines no colour tokens at all.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkDarkTheme(appDir) {
+  const name = 'dark-theme';
+  if (!existsSync(join(appDir, 'app'))) {
+    return { name, status: 'pass', message: 'no app/ directory to analyse' };
+  }
+  const sources = await tokenSources(appDir);
+  const defining = sources.filter((s) => TOKEN_DEF.test(stripComments(s.content)));
+  if (!defining.length) {
+    return { name, status: 'pass', message: 'no colour tokens defined (nothing to reach)' };
+  }
+  const all = sources.map((s) => stripComments(s.content)).join('\n');
+  const layout = sources.find((s) => ROOT_LAYOUT.test(s.rel));
+  if (DUAL_TOKENS.test(all) || SCHEME_QUERY.test(all) || (layout && THEME_SCRIPT.test(layout.content))) {
+    return { name, status: 'pass', message: 'the dark half of the colour tokens is reachable' };
+  }
+  const where = defining.map((s) => s.rel).join(' and ');
+  return {
+    name,
+    status: 'warn',
+    message:
+      `colour tokens are defined in ${where} with a light value only: nothing applies a dark half (no light-dark(), no prefers-color-scheme rule, no theme script in the root layout), so the OS dark setting is ignored and any .dark block is dead CSS`,
+    fix:
+      'Write each colour token ONCE as light-dark(LIGHT, DARK) under `color-scheme: light dark` in the root layout (the block in .agents/skills/webjs/references/styling.md), or give the tokens an `@media (prefers-color-scheme: dark)` half, or add a head <script> that applies the saved theme (data-theme / the .dark class). Then check the app in a real browser with the OS in dark mode.',
+  };
+}

package/lib/doctor/runner.js

@@ -13,6 +13,7 @@ import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
 import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
 import { checkWorkspaceOverrides } from './probes/workspace-overrides.js';
 import { checkAppIcon } from './probes/app-icon.js';
+import { checkDarkTheme } from './probes/dark-theme.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -68,6 +69,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkUnmarkedAssetLinks(appDir),
     Promise.resolve(checkWorkspaceOverrides(appDir)),
     Promise.resolve(checkAppIcon(appDir)),
+    checkDarkTheme(appDir),
   ]);
   // Attach the stable machine code to every result (#975). Centralized here so
   // each check function stays free of the code-contract concern.

package/lib/runtime-rewrite.js

@@ -23,11 +23,9 @@
  *   - the `dev` / `start` scripts force `bun --bun` (the server is Bun),
  *   - every other command stays `bun run` / `webjs ...` (runs on Node via the
  *     `webjs` bin's `#!/usr/bin/env node` shebang),
- *   - the Dockerfile is a pure `oven/bun:1` base (#595). This is safe as of
- *     `@webjsdev/cli@0.10.20` (#570): `webjs db migrate` resolves drizzle-kit
- *     and runs it under Bun (no `npx`), so a Node-less image works. (Before
- *     #570 shipped as `latest`, this stayed on `node:24-alpine` + a copied Bun
- *     binary, since the installed CLI could still shell `npx`.)
+ *   - the Dockerfile is a pure `oven/bun:1-slim` base (#595, #1606): `webjs db
+ *     migrate` resolves drizzle-kit and runs it under Bun (no `npx`, #570), so
+ *     a Node-less image works.
  */
 
 /**
@@ -96,16 +94,12 @@ export function bunifyProse(s) {
 /**
  * Rewrite the scaffolded Dockerfile for Bun.
  *
- * Base decision (acceptance criterion): a pure `oven/bun:1` image (no Node).
- * Safe as of `@webjsdev/cli@0.10.20` (#570): `webjs db` / `webjs test` resolve
- * their tools (drizzle-kit, wtr) and spawn them with the current runtime instead
- * of `npx`, so the boot-time `webjs db migrate` runs under Bun with no Node
- * toolchain. (Before #570 was the published `latest`, this stayed on a
- * `node:24-alpine` base with a copied Bun binary, since the installed CLI could
- * still shell `npx`, which a pure Bun image lacks. #595 flipped it once the
- * npx-free CLI shipped.) `oven/bun:1` is Debian-based: `ca-certificates` ship in
- * the image, and SQLite uses the built-in bun:sqlite (no native module), so no
- * build toolchain is needed.
+ * Base decision (acceptance criterion): a pure `oven/bun:1-slim` image (no Node).
+ * `webjs db` / `webjs test` resolve their tools (drizzle-kit, wtr) and spawn
+ * them with the current runtime instead of `npx` (#570), so the boot-time
+ * `webjs db migrate` runs under Bun with no Node toolchain. `oven/bun:1` is
+ * Debian-based: `ca-certificates` ship in the image, and SQLite uses the
+ * built-in bun:sqlite (no native module), so no build toolchain is needed.
  *
  * @param {string} s
  * @returns {string}
@@ -123,7 +117,9 @@ export function bunifyDockerfile(s) {
       '# runs on Node 24+; for a Node base instead, swap to `node:24-alpine` and start with\n' +
       '# `npm start`.\n',
     )
-    .replace('FROM node:24-alpine', 'FROM oven/bun:1')
+    // The slim variant: the same Bun on a Debian slim base (ca-certificates
+    // included), without the full image's extra system packages.
+    .replace('FROM node:24-alpine', 'FROM oven/bun:1-slim')
     // Debian base: ca-certificates already present, no `apk`. Drop the alpine line.
     .replace(
       /# ca-certificates for outbound TLS \(e\.g\. a managed Postgres\)\. SQLite uses the\n# built-in node:sqlite \(no native module, no build toolchain needed\)\.\nRUN apk add --no-cache ca-certificates\n\n/,
@@ -131,8 +127,12 @@ export function bunifyDockerfile(s) {
     )
     // Lockfile + install (bun.lock, bun install).
     .replace(
-      '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\nCOPY package.json package-lock.json* ./\nRUN npm install --no-audit --no-fund',
-      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. SQLite uses the built-in bun:sqlite, so no\n# native dependency or postinstall is involved.\nCOPY package.json bun.lock* ./\nRUN bun install',
+      '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\n',
+      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. SQLite uses the built-in bun:sqlite, so no\n# native dependency or postinstall is involved.\n',
+    )
+    .replace(
+      'reason. The npm cache is emptied in the same layer: it is a second copy of\n# every package fetched and would otherwise ship in the image.\nCOPY package.json package-lock.json* ./\nRUN npm install --omit=dev --no-audit --no-fund && npm cache clean --force',
+      'reason. bun\'s package cache is emptied in the same layer: it is a second copy\n# of every package fetched and would otherwise ship in the image.\nCOPY package.json bun.lock* ./\nRUN bun install --production && bun pm cache rm',
     )
     // Healthcheck: the pure Bun image has no node; use `bun -e`. Keep the
     // dependency-free-probe comment accurate (the probe runs under Bun now).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.69",
+  "version": "0.10.71",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -17,8 +17,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.87",
+    "@webjsdev/mcp": "^0.1.15",
+    "@webjsdev/server": "^0.8.89",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -2,33 +2,18 @@
 
 You are working on a WebJs app (AI-first, no-build, web-components-first). This
 file is the WORKFLOW contract (git, tests, review). For HOW to build (routing,
-components, actions, styling, the framework API), read `AGENTS.md`; the
-deeper reference set is `.agents/skills/webjs/SKILL.md`. Full hosted docs are
-at https://webjs.dev/docs.
+components, actions, styling, the framework API), read
+`.agents/skills/webjs/SKILL.md`, which routes to focused references on demand.
+Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 
 ## Grow the app in place (non-negotiable)
 
-- **Clear the showcase, then build.** The scaffold is a starting point with a
-  browsable demo showcase plus a database wired up. A full-stack app ships a UI
-  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
-  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
-  Building a real app: run `npm run gallery:clear` to shed the showcase (it
-  keeps the agent docs and the database wiring, and resets to a clean base),
-  then regenerate the database and grow the app in place under `app/`,
-  `components/`, and `modules/<feature>/`. `AGENTS.md` carries the
-  template-specific build steps and the order to follow.
-- **Use the wired-up database (Drizzle), never JSON files.** For any data the app
-  stores, define a Drizzle table in `db/schema.server.ts`, then
-  `npm run db:generate` and `npm run db:migrate`. Never use a JSON file, a
-  module-scope array or Map, or localStorage as a database.
-- **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
-  route, middleware, metadata routes). Browser-safe helpers go in `lib/utils/`,
-  feature logic in `modules/`, server-only code behind `.server.ts`.
-- **For a UI app, render and LOOK before calling it done.** Give the design
-  tokens in `public/input.css` a palette that fits the app, then open every
-  route you changed in a real browser and play through its states.
-  `npm run check` and `npm run typecheck` pass even when a layout collapses, so
-  the browser is the real check.
+Study the shipped showcase (a full-stack app's UI gallery under
+`app/features/` and `app/examples/todo`, the api template's
+`app/api/features/`), run `npm run gallery:clear`, then grow the app in place
+under `app/`, `components/`, and `modules/<feature>/`. `AGENTS.md` carries the
+build order, the data rule (the wired-up Drizzle database, never JSON files),
+and the browser check for a UI app.
 
 ## Before starting ANY work
 

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

@@ -9,9 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-In a scaffolded app, `AGENTS.md` carries the build steps and a worked example of every common pattern (pages, layouts, form-bound actions with validation, queries, owner-scoped CRUD, `createAuth`, a component with signals, a test). Build from it first, and come here for a surface it does not show.
-
-This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). The complete hosted docs live at https://webjs.dev/docs.
+This skill is the quick guide. When you need the full API reference for a surface, load the matching file in `references/` (listed below). For even deeper framework detail, WebJs ships buildless, so the source you run IS the source you read: look in `node_modules/@webjsdev/{core,server,cli}/` (each package ships its own `AGENTS.md`). To check ONE export's contract, run `npx webjs source <Export>` (for example `npx webjs source createAuth`, or `--pkg core` to narrow): it prints that export's signature and the doc comment above it from the installed package, so you read the declaration instead of the file. The MCP `source` tool does the same with `export`. Open the source file when the question is about behaviour the signature does not state. The complete hosted docs live at https://webjs.dev/docs.
 
 ## What WebJs Is
 
@@ -106,12 +104,12 @@ Common bundles:
 1. **Classify the change.** Route contract, data model, server mutation, auth, or only UI?
 2. **Start from the server.** Add the page/route and its server action or query before wiring interactive UI. A page render or a `<form>` POST should already return correct HTML before any component hydrates.
 3. **Put code in the narrowest owner.** Route-local first (`modules/<feature>/`), promote to `lib/` or `components/` only when reuse is real.
-4. **Keep server-only code behind `.server.ts`.** The DB driver, secrets, and `node:*` never belong in a page, layout, or component.
+4. **Keep server-only code behind `.server.ts`** (Core WebJs Rules 1 and 2).
 5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser. Then wrap the interactive part and STOP: the static markup around it stays in the page, where it costs nothing.
 6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
 7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
-8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. See `references/typescript.md`.
-9. **Test the narrowest meaningful layer**, and render the app in a real browser for any UI change (static checks do not catch a collapsed layout).
+8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. Carry a row type into a shipping component with `import type` (erased before the browser sees it). Nothing enforces this (both spellings are valid TypeScript, so `webjs check` and `tsc` pass either way), which is why it is written down. See `references/typescript.md`.
+9. **Test the narrowest meaningful layer**, and look at any UI change in a real browser (see Testing Defaults).
 
 ## Project Layout
 
@@ -139,7 +137,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 ## Core WebJs Rules (invariants)
 
 1. Server-only code lives in `.server.ts`, `route.ts`, or `middleware.ts`. Never in a page, layout, or component (it crashes the browser at module load).
-2. `'use server'` exports are `async` functions returning serializer-safe values. Files without `'use server'` are server-only utilities.
+2. `'use server'` exports are `async` functions returning serializer-safe values, callable from browser code as RPC. Files without `'use server'` are server-only utilities: reach them only from `'use server'` actions, `route.ts`, or middleware. Never add `'use server'` to a file only other server code imports (the DB connection, the schema).
 3. Custom element tag names contain a hyphen. Pass the tag to `Class.register('tag-name')`.
 4. Event (`@`), property (`.`), and boolean (`?`) holes in `html` are UNQUOTED: `@click=${fn}`, never `@click="${fn}"`.
 5. Signals are the default state primitive. Import `signal` / `computed` from `@webjsdev/core`, read via `signal.get()` inside `render()`. The base-class factory `WebComponent({ ... })` is only for values riding an HTML attribute or arriving via SSR hydration.
@@ -149,7 +147,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
 10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
 11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
-12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes, a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"`, a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
+12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes (the identity IS the button's name/value pair, so both halves are spoken for), a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"` (a GET sends no body for the action to read), a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
 
 ## Export Map
 
@@ -157,7 +155,7 @@ Find the right export fast. Load the linked reference for full examples.
 
 ### `@webjsdev/core` (browser + isomorphic)
 
-- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `register(tag, C)` / `Class.register('tag')`.
+- `html` / `css` tagged templates. `WebComponent({ ... })` base-class factory; `prop(type?, opts?)` declares one reactive property. `Class.register('tag')` binds the tag.
 - `signal` / `computed` reactive state, `effect(fn)` client-only reaction (returns a disposer), `batch(fn)` coalesced writes; `render(v, el)` client render.
 - `notFound()` / `redirect(url[, status])` control-flow throws (page/layout/action only, NOT `route.ts`). `forbidden()` / `unauthorized()` render the nearest boundary.
 - `Suspense({fallback, children})` page-level streaming; `<webjs-suspense>` component-level streaming.
@@ -274,18 +272,12 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 
 ## Common Mistakes To Avoid
 
-- Treating a page or layout like a React component and expecting its markup to hydrate. It runs server-only; put interactivity in a component.
+The invariants above are not repeated here; this list is the mistakes they do not already name.
+
 - Promoting a whole page section to a component so that one control inside it can be interactive. The island should wrap the control and the state it reads. An oversized island ships its own JS AND un-elides every display-only component inside it, so the cost is not linear in what you moved.
-- Importing a `.server.ts` utility (no `'use server'`) directly into a shipping component. Its browser stub throws at load; reach it through a `'use server'` action.
-- Using a `static properties` block or a class-field initializer for reactive props instead of the `WebComponent({ ... })` factory.
-- Quoting an event / property / boolean hole (`@click="${fn}"`).
 - Writing `fetch()` to call your own server instead of importing the action.
-- Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
-- Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
-- Writing `formmethod="get"` or `formenctype="text/plain"` on a button that BINDS an action. Neither can carry that action's body, so the pair contradicts itself and throws. On a button that binds nothing it is a legal native override and is honoured.
 - Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
 - Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
-- Writing `method="get"` on a bound `<form action=${fn}>`. WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.

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

@@ -296,7 +296,9 @@ Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports
 
 Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
 
-`APP_ICON` warns while the favicon is still the scaffold's: the placeholder `app/icon.svg` (marked `data-webjs-placeholder`) or the WebJs mark older scaffolds shipped at `public/favicon.svg`. Replace it with the app's own icon (`references/routing-and-pages.md`, "App icon and manifest").
+`APP_ICON` warns while the favicon is still the scaffold's placeholder `app/icon.svg` (marked `data-webjs-placeholder`). Replace it with the app's own icon (`references/routing-and-pages.md`, "App icon and manifest").
+
+`DARK_THEME_UNREACHABLE` warns when the app defines colour tokens with a light value only and nothing applies a dark half: no `light-dark()`, no `@media (prefers-color-scheme: dark)` rule, no theme script in the root layout. The scaffold gates it `error` in its `package.json` because its AGENTS.md mandates `light-dark()` tokens; the fix is the token block in `references/styling.md`.
 
 ### Dependency audit allowlist
 

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

@@ -68,7 +68,7 @@ One limit worth knowing: the rewrite belongs to `startServer`. An app embedded t
 webjs create my-app --runtime bun
 ```
 
-`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
+`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1-slim` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
 
 ## Running on Bun
 
@@ -79,13 +79,15 @@ bun install
 bun run dev      # or: bun run start
 ```
 
-`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun, selecting the native `Bun.serve` listener and `amaro` type stripping. The app's dependencies resolve from `node_modules` exactly as on Node. The `start.before` migrate step (`webjs db migrate`) runs under Bun too. Commit the `bun.lock` for reproducible, offline installs. The scaffold's Bun Dockerfile runs `bun install` and serves via `CMD ["bun", "--bun", "run", "start"]`.
+`bun --bun` overrides the `webjs` bin's Node shebang so the server runs on Bun, selecting the native `Bun.serve` listener and `amaro` type stripping. The app's dependencies resolve from `node_modules` exactly as on Node. The `start.before` migrate step (`webjs db migrate`) runs under Bun too. Commit the `bun.lock` for reproducible, offline installs. The scaffold's Bun Dockerfile runs `bun install --production` and serves via `CMD ["bun", "--bun", "run", "start"]`.
+
+**What the dev watcher ignores.** On both runtimes a change to a file nothing serves never reloads the page: `*.log`, `coverage/`, `.cache/`, `test-results/`, `playwright-report/`, and anything the app's `.gitignore` ignores (except `.env*`). So `npm run dev > dev.log` in the app folder is safe.
 
 ## Deploying either runtime
 
 Production runs `npm run start` (Node) or `bun run start` (Bun), which serves the source directly with no build step. Both speak plain HTTP/1.1, so put a reverse proxy or platform edge in front for TLS and HTTP/2 (production perf leans on HTTP/2 multiplexing plus `modulepreload` hints, not a bundle). A `start.before` migrate runs first on both runtimes.
 
-The scaffold ships a matching Dockerfile per runtime: a Node image for the default, a pure `oven/bun:1` image for `--runtime bun`. Commit the lockfile the runtime uses (`package-lock.json` for Node, `bun.lock` for Bun) so the deploy install is reproducible and offline.
+The scaffold ships a matching Dockerfile per runtime: a Node image for the default, a pure `oven/bun:1-slim` image for `--runtime bun`. Both install production dependencies only and leave the package manager's cache out of the image. What the boot runs is a production dependency for that reason: `drizzle-kit` (the `start.before` migrate) and, on a UI app, `@tailwindcss/cli` + `tailwindcss` (the CSS compile). Keep a tool the boot runs in `dependencies`; one moved to `devDependencies` is missing from the image and the boot fails. Commit the lockfile the runtime uses (`package-lock.json` for Node, `bun.lock` for Bun) so the deploy install is reproducible and offline.
 
 ## SQLite busy_timeout
 

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

@@ -193,7 +193,7 @@ Whichever form you use, a token nothing references is dropped in both, so an unu
 </style>
 ```
 
-`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour.
+`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour. `webjs doctor` reports the floor as `DARK_THEME_UNREACHABLE` (the scaffold gates it `error`): an app whose tokens have a light value only, with no `light-dark()`, no `prefers-color-scheme` rule and no theme script in the root layout, because the scaffold stylesheet's `.dark` block would then be dead CSS and the OS dark setting ignored.
 
 **A manual theme toggle** writes `data-theme` on `<html>` (`light` / `dark`, or removes it for "follow the OS"). If you use `@webjsdev/ui` components, ALSO keep the `.dark` class in sync (the ui kit keys its own tokens off `.dark`), and apply the saved choice in a tiny inline `<script>` in the layout head so there is no first-paint flash. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
 

package/templates/.claude/hooks/nudge-uncommitted.sh

@@ -30,13 +30,6 @@ fi
 # Read stdin so we don't break Claude Code's hook contract.
 cat /dev/stdin >/dev/null 2>&1 || true
 
-# A repository with no commit yet is a first build from the scaffold: the whole
-# build is one logical unit (CLAUDE.md), committed once at the end, so nudging
-# mid-build would only split it. The Stop hook still asks for that commit.
-if ! git rev-parse --verify -q HEAD >/dev/null 2>&1; then
-  exit 0
-fi
-
 CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
 
 if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then