@webjsdev/cli 0.10.67 → 0.10.69

package/bin/webjs.js

@@ -591,7 +591,7 @@ async function main() {
       superviseDevServer({
         cwd: process.cwd(),
         plan,
-        env: { ...process.env, __WEBJS_DEV_CHILD: '1' },
+        env: { ...process.env, ...plan.env, __WEBJS_DEV_CHILD: '1' },
         onExit: (code) => { killTasks(); process.exit(code); },
       });
       break;

package/lib/app-icon.js

@@ -0,0 +1,55 @@
+/**
+ * The app icon a new scaffold starts with, and how `webjs doctor` recognises
+ * an icon that was never replaced.
+ *
+ * A scaffold ships `app/icon.svg` (auto-linked as the favicon, served at
+ * /icon.svg and as the /favicon.ico fallback) and `app/manifest.webmanifest`
+ * (auto-linked as the web app manifest). The icon is a deliberately NEUTRAL
+ * placeholder: a grey tile with a dashed frame, so a tab strip shows at a
+ * glance that the app has no icon of its own yet, and no app ever ships
+ * looking like a WebJs demo. It carries `data-webjs-placeholder` so a check
+ * (webjs doctor, or any agent's own tester) can tell it apart from a real
+ * icon without comparing bytes.
+ */
+
+/** The attribute that marks the scaffold's placeholder icon. */
+export const PLACEHOLDER_MARKER = 'data-webjs-placeholder';
+
+/** The placeholder `app/icon.svg`. Replace it with the app's own mark. */
+export const PLACEHOLDER_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" ${PLACEHOLDER_MARKER}="icon">
+  <!-- PLACEHOLDER app icon from \`webjs create\`. Replace this file with the
+       app's own icon: a simple symbol for what the app is, in its colours,
+       legible at 16px. Keep the file name (app/icon.svg) and the framework
+       links it, serves it and answers /favicon.ico with it. -->
+  <rect width="32" height="32" rx="8" fill="#d4d4d8"/>
+  <rect x="7" y="7" width="18" height="18" rx="3" fill="none" stroke="#71717a" stroke-width="2" stroke-dasharray="3 2.4"/>
+</svg>
+`;
+
+/**
+ * The `app/manifest.webmanifest` a scaffold starts with: the app's name, the
+ * neutral colours of the scaffold palette, and the icon. Grow it with the app
+ * (its real theme colour, a 192 and 512 PNG for installability).
+ * @param {string} name the app's display name
+ */
+export function appManifest(name) {
+  return JSON.stringify({
+    name,
+    short_name: name,
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#ffffff',
+    theme_color: '#ffffff',
+    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

@@ -21,6 +21,7 @@ import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi, bunifyEnvExampl
 import { postgresCompose, postgresCi } from './db-rewrite.js';
 import { assertValidAppName, toDatabaseName } from './app-name.js';
 import { isGalleryAppShellFile } from './gallery-shell-files.js';
+import { PLACEHOLDER_ICON_SVG, appManifest } from './app-icon.js';
 import { detectPackageManager } from './package-manager.js';
 
 /**
@@ -382,10 +383,15 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // would exec WebJs under Node, silently running the "bun" app on Node).
       // Baking it into the script body means a plain `bun run dev` (or even
       // `npm run dev`) starts on Bun, so a user never has to remember the flag.
-      // The runtime-neutral tooling scripts below (test / db / check / typecheck
-      // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
-      // drizzle-kit, tsc) and forcing `--bun` there buys nothing (and `webjs
-      // test` shells `node --test`, which a `bun --test` would not be).
+      // The db scripts force it too (#1598): `webjs db` runs drizzle-kit and the
+      // seed with the CLI's own runtime, and through the node shebang that was
+      // Node, at 2.5 to 4 times the CPU of the same command on Bun (generate
+      // about 3 CPU-s against 1, migrate 1.2 against 0.5, seed 1 against 0.2,
+      // measured on the Postgres scaffold); on Bun the seed also sees `.env`.
+      // It is the path a Node-less oven/bun image already takes (#570). The
+      // other tooling scripts (test / check / typecheck / doctor / ci) stay
+      // plain `webjs ...`: `webjs test` shells `node --test`, which a
+      // `bun --test` would not be, and `check` costs the same on both.
       // Compile Tailwind from public/input.css to a STATIC public/tailwind.css
       // that app/layout.ts links, so the app is fully styled with JavaScript
       // DISABLED (a real stylesheet, not an in-browser compile). Runs inside the
@@ -418,11 +424,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // from the step list in the `webjs.ci` block below. Runtime-neutral like
       // the other tooling scripts (it spawns `webjs ...` children).
       ci: 'webjs ci',
-      'db:generate': 'webjs db generate',
-      'db:migrate': 'webjs db migrate',
-      'db:push': 'webjs db push',
-      'db:studio': 'webjs db studio',
-      'db:seed': 'webjs db seed',
+      'db:generate': isBun ? 'bun --bun webjs db generate' : 'webjs db generate',
+      'db:migrate': isBun ? 'bun --bun webjs db migrate' : 'webjs db migrate',
+      'db:push': isBun ? 'bun --bun webjs db push' : 'webjs db push',
+      'db:studio': isBun ? 'bun --bun webjs db studio' : 'webjs db studio',
+      'db:seed': isBun ? 'bun --bun webjs db seed' : 'webjs db seed',
     },
     dependencies: {
       // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
@@ -1246,10 +1252,15 @@ export type ActionResult<T> =
       const swSrc = join(TEMPLATES, 'public', swFile);
       if (existsSync(swSrc)) await cp(swSrc, join(publicDir, swFile));
     }
-    // A base SVG favicon (the root layout links it). It ships with the app, not
-    // the gallery, so it survives `npm run gallery:clear`.
-    const faviconSrc = join(TEMPLATES, 'public', 'favicon.svg');
-    if (existsSync(faviconSrc)) await cp(faviconSrc, join(publicDir, 'favicon.svg'));
+    // The app icon and web app manifest: `app/icon.svg` (a neutral PLACEHOLDER
+    // the agent replaces with the app's own icon; `webjs doctor` warns while it
+    // is still there) and `app/manifest.webmanifest` (the app's name). The
+    // framework links both into <head> and answers /favicon.ico with the icon,
+    // so the layout declares nothing. They ship with the app, not the gallery,
+    // so they survive `gallery:clear`.
+    await mkdir(join(appDir, 'app'), { recursive: true });
+    await writeFile(join(appDir, 'app', 'icon.svg'), PLACEHOLDER_ICON_SVG);
+    await writeFile(join(appDir, 'app', 'manifest.webmanifest'), appManifest(displayName));
 
     // The gallery-reset script (wired as `gallery:clear`). Only UI templates have
     // a gallery, so it ships here (NOT in the flat templateFiles list, which would
@@ -1355,11 +1366,10 @@ import '#components/theme-toggle.ts';
  * text-foreground, bg-card, bg-primary, and border-border all work.
  */
 
-// Declare the favicon via metadata.icons (NOT a hand-written <link> in the
-// template): the framework emits metadata links into <head>, whereas a <link>
-// written in the layout body stays in <body>, where browsers ignore it. The SVG
-// lives at public/favicon.svg and serves at /public/favicon.svg.
-export const metadata = { icons: '/public/favicon.svg' };
+// The favicon and manifest are app/icon.svg and app/manifest.webmanifest: the
+// framework links them into <head> itself, so nothing is declared here. Replace
+// the placeholder icon with this app's own (see the skill's routing-and-pages
+// reference, "App icon").
 
 // LayoutProps types every layout argument (children, params, searchParams,
 // url) from the framework, so children is a TemplateResult rather than an
@@ -1711,8 +1721,8 @@ ThemeToggle.register('theme-toggle');
 `);
   }
   console.log(`For AI agents, read this before editing:
-  • 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.
+  • Read AGENTS.md first: it carries the build steps and a worked example of
+    every common pattern. .agents/skills/webjs/ is the deeper reference.
   • 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-supervisor.js

@@ -78,7 +78,7 @@ export function isBootFile(path) {
  * @param {string[]} opts.argv  `process.argv.slice(1)` (the script path followed by its args), forwarded to the child verbatim.
  * @param {boolean} opts.noHot  Whether `--no-hot` was passed (opt out of the supervisor entirely).
  * @param {boolean} [opts.sourceLocations]  Whether dev source locations are on (`WEBJS_SOURCE_LOCATIONS` / `webjs.dev.sourceLocations`), which puts every app module behind a Bun plugin.
- * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], restartOnChange: boolean, restartFor?: (path: string) => boolean, inPlaceRestartFor?: (path: string) => boolean, watchDirs: string[], watchFiles: string[] }}
+ * @returns {{ mode: 'inline' } | { mode: 'supervise', args: string[], env?: Record<string, string>, restartOnChange: boolean, restartFor?: (path: string) => boolean, inPlaceRestartFor?: (path: string) => boolean, watchDirs: string[], watchFiles: string[] }}
  *   `inline` runs the server in this process (no reload watcher); `supervise`
  *   spawns `process.execPath` with `args` and `__WEBJS_DEV_CHILD=1` under the
  *   supervisor, which watches `watchDirs` (recursively) and `watchFiles` (at
@@ -101,6 +101,7 @@ export function planDevSupervisor({ isBun, argv, noHot, sourceLocations = false
     return {
       mode: 'supervise',
       args: ['--hot', ...argv],
+      env: BUN_CHILD_ENV,
       restartOnChange: true,
       restartFor: (p) => plugin(p) || isBootFile(p),
       inPlaceRestartFor: isBootFile,
@@ -110,6 +111,20 @@ export function planDevSupervisor({ isBun, argv, noHot, sourceLocations = false
   return { mode: 'supervise', args: [...argv], restartOnChange: true, ...watch };
 }
 
+/**
+ * Extra env for the Bun dev child: turn off Bun's runtime transpiler cache.
+ *
+ * Bun caches the transpile of every source over 50KB on disk, keyed by the
+ * file's CONTENT, with the import paths a `Bun.plugin` `onResolve` returned
+ * baked in. The dev alias resolver (#1575) returns absolute paths, so the
+ * cached output of a large app module pins its `#` imports to the checkout
+ * that first ran `webjs dev`. Any other copy of the same file (a git worktree,
+ * a moved or copied app, a later `webjs start`) then imports from that old
+ * directory: a 500 when it is gone, the other copy's code when it is not. The
+ * variable is read at process start, so it has to be set on the child.
+ */
+const BUN_CHILD_ENV = Object.freeze({ BUN_RUNTIME_TRANSPILER_CACHE_PATH: '0' });
+
 const SERVER_MODULE = /\.server\.m?[jt]s$/;
 const APP_MODULE = /\.m?[jt]s$/;
 

package/lib/doctor/codes.js

@@ -50,6 +50,7 @@ export const DOCTOR_CODES = {
   'Static build outputs (dev.regenerate freshness)': 'STATIC_ASSET_FRESHNESS',
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
   'workspace-overrides': 'WORKSPACE_OVERRIDES',
+  'app-icon': 'APP_ICON',
 };
 
 /**

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

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PLACEHOLDER_MARKER, isLegacyBrandFavicon } from '../../app-icon.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/** @param {string} file */
+function read(file) {
+  try { return readFileSync(file, 'utf8'); } catch { return ''; }
+}
+
+/**
+ * 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
+ * no pages) passes.
+ *
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+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.';
+  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/runner.js

@@ -12,6 +12,7 @@ import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
 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';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -66,6 +67,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkStaticAssetFreshness(appDir),
     checkUnmarkedAssetLinks(appDir),
     Promise.resolve(checkWorkspaceOverrides(appDir)),
+    Promise.resolve(checkAppIcon(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/gallery-shell-files.js

@@ -6,7 +6,7 @@
  * live app deployed on its own, so it needs a root layout, a home page, a theme
  * toggle, and the `cn()` helper. The scaffold writes all four itself, with
  * things the gallery's copies cannot carry: the app's `displayName`, the
- * `cspNonce()` wiring, `LayoutProps` typing, the `metadata.icons` favicon, and
+ * `cspNonce()` wiring, `LayoutProps` typing, and
  * a `cn.ts` read verbatim from the `@webjsdev/ui` registry so `webjs ui add`
  * stays in lockstep with the kit.
  *

package/lib/resolve-bin.js

@@ -13,6 +13,14 @@
  * 'drizzle-kit/bin.cjs')` throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. The `.` main
  * entry DOES resolve, so resolve that, walk up to the package root (the nearest
  * dir with a package.json), and read the `bin` field, which is version-robust.
+ *
+ * Installed means reachable through a `node_modules/<pkg>` entry in `cwd` or an
+ * ancestor, the lookup Node's resolver does. That is checked BEFORE resolving
+ * because Bun auto-installs: when no `node_modules` sits above `cwd`, Bun's
+ * `require.resolve` fetches an undeclared package into its global cache and
+ * returns that path. Without the check, an app that never installed
+ * @web/test-runner would launch whatever version Bun downloaded instead of
+ * getting the "not installed" remedy.
  */
 import { createRequire } from 'node:module';
 import { readFileSync, existsSync } from 'node:fs';
@@ -27,6 +35,9 @@ import { join, dirname, resolve } from 'node:path';
  * @throws if the package is not installed or has no matching bin
  */
 export function resolveBin(cwd, pkgName, binName) {
+  if (!hasNodeModulesEntry(cwd, pkgName)) {
+    throw new Error(`Cannot find package '${pkgName}' in a node_modules above ${cwd}`);
+  }
   const req = createRequire(join(cwd, 'package.json'));
   // `.` (the main entry) is exported even when subpaths are not.
   let pkgDir = dirname(req.resolve(pkgName));
@@ -40,3 +51,18 @@ export function resolveBin(cwd, pkgName, binName) {
   if (!binRel) throw new Error(`bin '${binName}' not found in ${pkgName}`);
   return resolve(pkgDir, binRel);
 }
+
+/**
+ * @param {string} cwd
+ * @param {string} pkgName
+ * @returns {boolean} whether `node_modules/<pkgName>` exists in cwd or an ancestor
+ */
+function hasNodeModulesEntry(cwd, pkgName) {
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(join(dir, 'node_modules', pkgName))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.67",
+  "version": "0.10.69",
   "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": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.84",
+    "@webjsdev/server": "^0.8.87",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

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

@@ -2,23 +2,21 @@
 
 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/skills/webjs/SKILL.md`, which routes to focused references on demand.
-Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
+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.
 
 ## 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.
+- **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
@@ -26,9 +24,8 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 - **`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
+- **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.

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

@@ -9,6 +9,8 @@ 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.
 
 ## What WebJs Is
@@ -174,7 +176,7 @@ Find the right export fast. Load the linked reference for full examples.
 
 ### File conventions
 
-`page.ts` (server-only fn), `layout.ts` (embeds `children`), `route.ts` (HTTP handler), `middleware.ts`, `*.server.ts` (server boundary), `error.ts` / `loading.ts` / `not-found.ts` / `forbidden.ts` / `unauthorized.ts` (boundaries), metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `opengraph-image.ts`).
+`page.ts` (server-only fn), `layout.ts` (embeds `children`), `route.ts` (HTTP handler), `middleware.ts`, `*.server.ts` (server boundary), `error.ts` / `loading.ts` / `not-found.ts` / `forbidden.ts` / `unauthorized.ts` (boundaries), metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `opengraph-image.ts`), and the static app-root icon files (`icon.svg`, `apple-icon.png`, `manifest.webmanifest`, `favicon.ico`), auto-linked into `<head>`. The scaffold's `app/icon.svg` is a placeholder: replace it with the app's own icon.
 
 ## Canonical Patterns
 

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

@@ -296,6 +296,8 @@ 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").
+
 ### Dependency audit allowlist
 
 `webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default `high`) that `webjs.audit.ignore` does not list. The scaffold's `Security: dependency audit` CI step runs it.

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -278,12 +278,26 @@ export default function robots({ siteUrl }: MetadataRouteContext) {
 
 The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
 
-**`icon` and `apple-icon` are LINKED for you.** An app that declares no `metadata.icons` gets `<link rel="icon" href="/icon">` and `<link rel="apple-touch-icon" href="/apple-icon">` in the head automatically, for whichever of the two routes it defines (base-path prefixed, since that is where the route answers). No `type` or `sizes` is asserted, because the route picks its content type at request time and the browser sniffs the served one.
+### App icon and manifest (replace the placeholder)
 
-Declaring `metadata.icons` **suppresses** the routes rather than merging with them, which is what Next does with its static icon files. So an app that outgrows a placeholder `app/icon.ts` names its real icons and the route stops being linked without having to be deleted:
+**Every app needs its OWN icon.** `webjs create` ships `app/icon.svg` as a neutral PLACEHOLDER (a grey tile with a dashed frame, marked `data-webjs-placeholder="icon"`) and `app/manifest.webmanifest` with the app's name. Replacing the placeholder is part of building the app, not polish: until you do, the tab, the bookmark and the home-screen icon look like every other unfinished app, and `webjs doctor` warns (`APP_ICON`). Draw a simple symbol for what the app IS (a grid for a tic-tac-toe game, a cup for a cafe, a check for a task list), in the app's own colours, on a 32x32 or 24x24 `viewBox`: a filled rounded tile in the primary colour with one bold shape in its foreground colour reads at 16px. Avoid thin strokes (under 2px at 32px), text longer than one letter, and detail that blurs at tab size. Then set `name`, `short_name`, `theme_color` and `background_color` in `app/manifest.webmanifest` to match.
+
+The icon conventions, all at the app ROOT and all auto-linked into `<head>` when the app declares no `metadata.icons`:
+
+| File | Served at | Linked as |
+|---|---|---|
+| `app/icon.svg` / `icon.png` / `icon.ico` | `/icon.svg` ... | `<link rel="icon">` with `type`, `sizes="any"` (SVG) or the PNG's real pixel size |
+| `app/apple-icon.png` (180x180) | `/apple-icon.png` | `<link rel="apple-touch-icon" sizes="180x180">` (iOS needs PNG, not SVG) |
+| `app/icon.ts` / `apple-icon.ts` | `/icon`, `/apple-icon` | bare link (the route picks its content type per request) |
+| `app/manifest.webmanifest` / `manifest.json` / `manifest.ts` | `/manifest.webmanifest`, `/manifest.json` | `<link rel="manifest">` (`metadata.manifest` wins; `manifest: null` opts out) |
+| `app/favicon.ico` | `/favicon.ico` | not linked; browsers request it themselves |
+
+`/favicon.ico` always answers: `public/favicon.ico`, else `app/favicon.ico`, else the app's icon (raster preferred over SVG, then the `icon.ts` route), so a crawler or feed reader that reads no markup gets the same icon. A static icon file wins the link over an icon route when both exist (the route still serves at its URL). Raster icons are linked before SVG, because Google's favicon crawler takes the first usable icon and wants a square raster. Use `icon.ts` only when the mark must be computed per request (per theme, per tenant); a route can render a PNG for `apple-icon.ts` the same way.
+
+Declaring `metadata.icons` **suppresses** all of the above rather than merging with them, which is what Next does with its static icon files. So name icons explicitly only when they live elsewhere (a CDN, `public/`):
 
 ```ts
-// app/layout.ts  ->  these win; /icon and /apple-icon are no longer linked
+// app/layout.ts  ->  these win; app/icon.* and app/apple-icon.* are no longer linked
 export const metadata = {
   icons: {
     icon: [
@@ -295,7 +309,7 @@ export const metadata = {
 };
 ```
 
-Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
+Never write a favicon as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout.
 
 `opengraph-image` and `twitter-image` are LINKED too, Next's behaviour: a page that declares no `openGraph.images` gets `og:image` pointing at the nearest `opengraph-image` route above it (absolute against the site URL), and likewise `twitter:image`. A page that declares its own image keeps it.
 

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

@@ -44,6 +44,8 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 
 Bun keeps ONE dev server process for the whole session (#1575), so it gets the refresh. `bun --hot` re-runs the CLI on a change; the first run's server owns the process (its listener, live-reload stream, watchers and analysis caches) and a re-run only tells it the module registry was reset, so nothing is started twice and memory stays flat over hundreds of edits (it used to grow about 25 MB an edit until `bun --hot` stopped reloading). The app's modules load through a `Bun.plugin` that reads them fresh, and its `#` imports resolve through the app's own `imports` map, because Bun keeps the old source of a file that was replaced (an atomic save) and a stale directory listing for a new file next to a `*.server.*` module. So `bun --hot` no longer sees app edits itself, and the dev server asks it for a registry reset after an edit to a module some other module imports, a new module, or a `*.server.*` module, all without a process restart. A page, layout or route handler nothing imports needs no reset: the dev re-import is keyed by the file's content, so an unchanged file reuses its loaded module (no new module instance per request) and an edited one is a new import. `instrumentation.*` and `env.*` run once per process, so an edit to one restarts the server on both runtimes. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
 
+After a reset, app code that imports `@webjsdev/server` gets a fresh copy of the package while the first run's server keeps handling requests. Everything the two copies must agree on (the request `auth()`, `cookies()` and `headers()` read, the action signal, the seed collector and action identity, the default cache store, sessions, broadcast clients) lives in process-wide state keyed by `Symbol.for`, so a signed-in page and the `'use server'` queries it calls still see the request after any number of edits (#1590). Before that fix, `auth()` without an explicit request returned `null` in app code after the first edit.
+
 **`webjs dev` and `webjs start` serve the directory they are started in, and refuse anywhere else (#1526).** Run them in the app directory, the one holding `app/`. In a workspace (`apps/web` under a root `package.json` with `workspaces`) that is the member, even when the CLI is hoisted to the root `node_modules`: the hoisted bin and the Bun `--hot` child both keep the directory they were started in. Started where there is no `app/` (the workspace root, or a subdirectory such as `app/` itself), both exit 1 before any `before` step runs, naming the app to start (`cd apps/web && webjs dev`), instead of booting a server that answers 404 for every route.
 
 **`webjs dev` does not stay down (#1521).** The supervisor and the server's own watcher handle every watcher error: a file in a watched dir the dev server cannot read or watch (the 0600 temp file `sed -i` creates when another user runs it, a file removed mid-scan) logs one `file watcher skipped <path> (EACCES)` warning and both keep running, where `node --watch` used to crash and leave the preview dead. Edits that REPLACE a file (`sed -i`, an editor saving through a temp file, an atomic write) are heard every time, however often the same file is replaced (#1529: on Linux under Node the watchers watch each directory, since Node 24's own recursive watcher stopped hearing a file after its first replacement). A server process that crashes is started again on the next file change, or by itself after a backoff of 0.5s growing to 10s for repeated crashes. On Bun the supervisor restarts the server only for an `instrumentation.*` / `env.*` edit (#1575), and otherwise does only the crash recovery. An agent writing files the way an AI editor does (bursts, partial writes, syntax errors then fixes, renames, deletes, atomic writes) is exercised by `scripts/dev-reload-stress.mjs` (`node scripts/dev-reload-stress.mjs <appDir> <url>` against any running app). Stopping `webjs dev` (Ctrl-C, SIGTERM) stops the server child too, and a child whose supervisor was killed outright exits on its own, so nothing is left holding the port.

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

@@ -30,6 +30,13 @@ 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