@webjsdev/cli 0.10.70 → 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

@@ -585,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,

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-slim` base (#595, #1606). 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.
  */
 
 /**
@@ -97,15 +95,11 @@ export function bunifyProse(s) {
  * Rewrite the scaffolded Dockerfile for Bun.
  *
  * Base decision (acceptance criterion): a pure `oven/bun:1-slim` 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.
+ * `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}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.70",
+  "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.88",
+    "@webjsdev/mcp": "^0.1.15",
+    "@webjsdev/server": "^0.8.89",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -8,30 +8,12 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 
 ## Grow the app in place (non-negotiable)
 
-- **Study the shipped examples, then clear them and build.** The scaffold is a
-  starting point with a browsable showcase to learn the real idioms from, plus a
-  database wired up. A full-stack app ships a UI feature gallery (`app/features/`,
-  `app/examples/todo`); the api template ships a backend-features showcase
-  (`app/api/features/`), with logic in `modules/`. Building a real app: study the
-  parts that match your task (the skill teaches the same and SURVIVES the clear),
-  run `npm run gallery:clear` to shed the showcase (it keeps the agent skill and
-  the database wiring, and resets to a clean base), then regenerate the database
-  and grow the app in place under `app/`, `components/`, and `modules/<feature>/`.
-  `AGENTS.md` carries the full template-specific build playbook and the order to
-  follow.
-- **Use the wired-up database (Drizzle), never JSON files.** For any data the app
-  stores, define a Drizzle table in `db/schema.server.ts`, then
-  `npm run db:generate` and `npm run db:migrate`. Never use a JSON file, a
-  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.** Define design tokens
-  in `app/layout.ts` with a palette that fits the app
-  (`.agents/skills/webjs/references/styling.md` is the guide), then open every
-  route you changed in a real browser and play through its states.
-  `npm run check` and `npm run typecheck` pass even when a layout collapses, so
-  the browser is the real check.
+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,7 +9,7 @@ Use this skill for end-to-end WebJs app work. It helps you choose the right laye
 
 ## Full Documentation
 
-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
 
@@ -104,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
 
@@ -137,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.
@@ -147,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
 
@@ -155,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.
@@ -272,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/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/AGENTS.md

@@ -22,58 +22,26 @@ This is what separates a working app from a broken one.
    rules (git, tests, review) are in `.agents/rules/workflow.md`; follow them
    too.
 3. **Read the framework source for exact contracts.** WebJs is 100% buildless
-   native ES modules, so the source you run IS the source you read. When you
-   need a precise API signature or behavior, open the package source under
-   `node_modules/@webjsdev/*` directly (each package ships its own `AGENTS.md`).
-   The full hosted docs are at https://webjs.dev/docs.
+   native ES modules, so the source you run IS the source you read. For one
+   export's signature and doc comment run `npx webjs source <Export>` (for
+   example `npx webjs source createAuth`); it reads the installed package and
+   prints the declaration, not the file. When you need the behaviour behind a
+   signature, open the package source under `node_modules/@webjsdev/*` directly
+   (each package ships its own `AGENTS.md`). The full hosted docs are at
+   https://webjs.dev/docs.
 
 {{PLAYBOOK}}
 
 ## Type everything (all templates)
 
-Full-stack type safety is what the `.server.ts` boundary buys you: a client
-component importing a server action resolves to that action's real signature at
-type-check time, with no build step and no code generation in between. So
-DERIVE the type at every boundary instead of widening it:
-
-- A database row: `export type Todo = typeof todos.$inferSelect` in
-  `db/schema.server.ts` (`$inferInsert` for a write), carried into a
-  browser-shipped component with `import type` (erased before it reaches the
-  browser, so it does not trip the server-import boundary).
-- An action's input: a named `interface`. Its result: `ActionResult<T>`.
-  Narrow with `if (result.success && result.data)`.
-- Routing files: `PageProps<'/blog/[slug]'>`, `LayoutProps`,
-  `RouteHandlerContext`, all from `@webjsdev/core`. Run `npx webjsdev types`
-  for the typed `Route` union and per-route `params`.
-- A reactive property: `prop<Student>(Object)`, `prop<Tag[]>(Array)`.
-
-Never reach for `any` or a loose `as any` cast, and do not reach for `unknown`
-either just because it looks safer. `unknown` is right for a payload nothing
-has vouched for yet, narrowed on the very next line (a `route.ts` `await
-req.json()`, an action's `export const validate` or a validator it delegates
-to, a `catch` binding), and for a parameter of YOUR OWN helper that forwards
-into an `html` template hole (a hole renders a string, a number, a
-`TemplateResult`, or an array of those, so `TemplateResult` alone is too
-narrow). That second case is about a value you accept, never one the framework
-already types. Everywhere else it is a missing type, not a safe one: `unknown`
-that survives into a return type, a component prop, a layout's `children`, or
-an action signature is the shape to fix.
-Nothing enforces this (both are valid TypeScript, so `webjs check` and `tsc`
-pass either way), which is exactly why it is written down. The full ladder,
-with an end-to-end example, is in
+Derive the type at every boundary from its source. Never reach for `any`, and
+never `unknown` where a real type exists. The rule is step 8 of the skill's "Default
+Workflow"; the full ladder, with an end-to-end example, is
 `.agents/skills/webjs/references/typescript.md`.
 
 Keep server-only code (database drivers, secrets, `node:*` builtins) in
-`.server.ts` modules. There are exactly two kinds:
-
-- A `.server.ts` file WITH `'use server';` as its first line is a server
-  action: WebJs exposes its exported async functions to browser code as RPC
-  calls, so browser modules may import it directly.
-- A `.server.ts` file WITHOUT `'use server'` is a server-only utility:
-  importing it from a page, layout, or component CRASHES in the browser at
-  module load. Reach it only from `'use server'` actions, `route.ts` handlers,
-  or middleware. Never add `'use server'` to a file only other server code
-  imports (the DB connection, the schema).
+`.server.ts` modules. The two kinds (with and without `'use server'`) are the
+skill's "Core WebJs Rules" 1 and 2.
 
 ## Data (all templates)
 

package/templates/CLAUDE.md

@@ -9,14 +9,9 @@ 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
+The full git contract (branches, commit messages, attribution) is
+`.agents/rules/workflow.md` "Git rules"; the
+`.claude/hooks/guard-branch-context.sh` hook refuses a commit on `main`. 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

package/templates/CONVENTIONS.md

@@ -3,34 +3,16 @@
 The conventions for building a WebJs app live in the agent skill. **Read
 `AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (it routes to focused
 references under `.agents/skills/webjs/references/`, loaded on demand). This file
-is the short version.
+only says where each rule lives, so no rule is stated twice.
 
-## The essentials
-
-- **`app/` is routing only.** Only routing files live there (page, layout, route,
-  middleware, metadata routes). Feature logic goes in `modules/<feature>/`
-  (`actions/`, `queries/`, `components/`, `utils/`); shared UI primitives go in
-  top-level `components/`; browser-safe helpers in `lib/utils/`.
-- **Server-only code goes behind `.server.ts`.** Reach it from a page or component
-  through a `'use server'` action, never by importing a server-only utility
-  directly into browser-bound code.
-- **Use the wired-up database (Drizzle).** Define real models in
-  `db/schema.server.ts`, then `npm run db:generate` and `npm run db:migrate`.
-  Never persist to a JSON file, an in-memory array or Map, or localStorage.
-- **The scaffold ships a showcase to learn from.** A full-stack app ships a UI
-  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
-  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
-  When you build a real app, study the parts that match your task (the skill
-  teaches the same and survives the clear), run `npm run gallery:clear` to shed
-  the showcase, then grow the app in place. `AGENTS.md` has the full
-  template-specific playbook.
-- **Derive types at every boundary.** Rows from `$inferSelect`, action inputs
-  from an `interface`, routing files from `PageProps` / `LayoutProps`. Never
-  `any`, and never `unknown` where a real type exists.
-- **Progressive enhancement is the default.** Pages render as HTML, `<a>`
-  navigates, a `<form action=${importedAction}>` submits, all with JavaScript off; opt into
-  interactivity per behaviour inside a component.
-- **Commit per logical unit** as soon as it is complete, and never push to `main`.
-
-Everything else (the module architecture, the `ActionResult` envelope, styling,
-testing, the client router, optimistic UI) is in the skill's references.
+- **Build order** (study the showcase: a full-stack app's gallery under
+  `app/features/` and `app/examples/todo`, the api template's
+  `app/api/features/`; then `npm run gallery:clear`, data, UI, verify):
+  the playbook in `AGENTS.md`.
+- **Data** (the wired-up Drizzle database, never a JSON file, an in-memory
+  array or Map, or localStorage): `AGENTS.md`, "Data".
+- **Layout** (`app/` is routing only, logic in `modules/<feature>/`): the
+  skill's "Project Layout".
+- **Server boundary, progressive enhancement, typing**: the skill's "What WebJs
+  Is", "Core WebJs Rules", and "Default Workflow".
+- **Git, tests, and `npm run ci`**: `.agents/rules/workflow.md`.

package/templates/partials/agents-playbook-api.md

@@ -44,20 +44,12 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 
 ### 5. Verify before you call it done
 
-Run `npm run ci` and fix what it reports. It is one command for every gate,
-the step list declared in `package.json` under `webjs.ci`, with a result line
-per step:
-
-- `webjs check` (correctness: no browser-import or boundary violation).
-- `webjs doctor` (project health). It fails on whatever `package.json`
-  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
-  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
-- `webjs typecheck` (zero type errors).
-- A dependency audit.
-- The test layers for the endpoints and modules you built.
-
-The GitHub workflow runs the same list, so a green local run predicts CI.
-While iterating, `npm run ci -- --only Tests` runs one layer.
+Run `npm run ci` and fix what it reports. It runs every gate declared under
+`webjs.ci` in `package.json` (`webjs check`, `webjs doctor`, `webjs typecheck`,
+a dependency audit, then the test layers for the endpoints and modules you
+built), and the GitHub workflow runs the
+same list; `.agents/rules/workflow.md` has what each gate checks. While
+iterating, `npm run ci -- --only Tests` runs one layer.
 
 Then boot `npm run dev` and probe each endpoint for the expected status and JSON
 shape.

package/templates/partials/agents-playbook-fullstack.md

@@ -84,31 +84,21 @@ action without also triggering the row navigation.
 
 ### 6. Build components for interactivity
 
-Pages and layouts (`app/**/page.ts`, `app/**/layout.ts`) are server-only HTML
-generators, so put every interactive behavior inside a `WebComponent` custom
-element. Declare a component's reactive properties in the base-class factory,
-never as a class-field initializer (`items = []` clobbers the reactive
-accessor). Use the shorthand for primitives
+Pages and layouts never hydrate, so put every interactive behavior inside a
+`WebComponent` custom element, and declare its reactive properties only in the
+base-class factory (the skill's "Core WebJs Rules" 11). Use the shorthand for primitives
 (`extends WebComponent({ name: String, count: Number, open: Boolean })`) and the
 `prop<T>()` helper for typed objects and arrays
 (`extends WebComponent({ items: prop<Item[]>(Array), user: prop<User>(Object) })`).
 
 ### 7. Verify before you call it done
 
-Run `npm run ci` and fix what it reports. It is one command for every gate,
-the step list declared in `package.json` under `webjs.ci`, with a result line
-per step:
-
-- `webjs check` (correctness: no browser-import or boundary violation).
-- `webjs doctor` (project health). It fails on whatever `package.json`
-  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
-  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
-- `webjs typecheck` (zero type errors).
-- A dependency audit.
-- The server, browser, and e2e test layers for the features you built.
-
-The GitHub workflow runs the same list, so a green local run predicts CI.
-While iterating, `npm run ci -- --only Tests` runs one layer. Then
+Run `npm run ci` and fix what it reports. It runs every gate declared under
+`webjs.ci` in `package.json` (`webjs check`, `webjs doctor`, `webjs typecheck`,
+a dependency audit, then the server, browser, and e2e test layers for the
+features you built), and the GitHub workflow runs the
+same list; `.agents/rules/workflow.md` has what each gate checks. While
+iterating, `npm run ci -- --only Tests` runs one layer. Then
 `npm run css:build` (compile Tailwind).
 
 Then boot `npm run dev`, confirm every page route returns HTTP 200, and open