diff --git a/.agents/skills/webjs/references/routing-and-pages.md b/.agents/skills/webjs/references/routing-and-pages.md
index 0512c1300..baa4d1583 100644
--- a/.agents/skills/webjs/references/routing-and-pages.md
+++ b/.agents/skills/webjs/references/routing-and-pages.md
@@ -192,7 +192,28 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
 
-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). Then point `metadata` at the route via `openGraph.images` / `twitter.images` / `icons` (or drop a static file in `public/` instead).
+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.
+
+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:
+
+```ts
+// app/layout.ts  ->  these win; /icon and /apple-icon are no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};
+```
+
+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.
+
+`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
diff --git a/AGENTS.md b/AGENTS.md
index 93f0a759d..22167b637 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -305,7 +305,7 @@ Default export receives `{ children, params, searchParams, url }`, must embed `c
 
 ### Error / loading / metadata routes
 
-`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML.
+`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML. **`icon` / `apple-icon` are auto-LINKED** into the head (`<link rel="icon" href="/icon">`, `<link rel="apple-touch-icon" href="/apple-icon">`, base-path prefixed, no asserted `type` / `sizes` since the route picks its content type at request time), so writing the file is the whole wiring. A declared `metadata.icons` **suppresses** them rather than merging, matching Next's precedence for its static icon files, so an app that outgrows a placeholder route names its real icons instead of deleting it. `opengraph-image` / `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice): point `metadata.openGraph.images` / `metadata.twitter.images` at them. Declare a favicon through `metadata.icons` or a metadata route, never a hand-written `<link rel="icon">`, since only the root layout may write a shell at all (invariant 8). See `references/routing-and-pages.md`.
 
 ### Route handlers (`app/**/route.{js,ts}`)
 
diff --git a/packages/server/src/dev.js b/packages/server/src/dev.js
index 3cbe33ff0..a681396c6 100644
--- a/packages/server/src/dev.js
+++ b/packages/server/src/dev.js
@@ -14,7 +14,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
-import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
+import { ssrPage, ssrNotFound, setClientRouterEnabled, setMetadataIconRoutes } from './ssr.js';
 import { runFormAction, reportFormSubmittedAsGet } from './form-dispatch.js';
 import { handleApi } from './api.js';
 import {
@@ -742,6 +742,12 @@ export async function createRequestHandler(opts) {
   // like env.js / readiness.js), not a router stem. Resolve it once and stash it
   // on the route table so ssrOpts + the browser-servable gate reach it uniformly.
   routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+  // Auto-linked favicons: tell the head builder which icon metadata routes
+  // exist, so `app/icon.*` is linked when the app declares no metadata.icons.
+  // Bound here rather than threaded through ssrOpts, matching
+  // setClientRouterEnabled; re-bound in doRebuild so adding or deleting the
+  // file takes effect without a restart.
+  setMetadataIconRoutes(routeTable.metadataRoutes);
 
   // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
   // dev so an editor's tsserver always has up-to-date route types without the
@@ -1207,6 +1213,8 @@ export async function createRequestHandler(opts) {
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
     state.routeTable.instrumentationClient = await findInstrumentationClient(appDir);
+    // Adding or deleting app/icon.* changes whether the head auto-links it.
+    setMetadataIconRoutes(state.routeTable.metadataRoutes);
     // Refresh the generated route types (#258) so adding/removing a route file
     // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
     // best-effort (see emitRouteTypes).
diff --git a/packages/server/src/ssr.js b/packages/server/src/ssr.js
index d69feb635..53100b248 100644
--- a/packages/server/src/ssr.js
+++ b/packages/server/src/ssr.js
@@ -1360,6 +1360,54 @@ let _clientRouterEnabled = true;
 export function setClientRouterEnabled(enabled) { _clientRouterEnabled = enabled !== false; }
 function clientRouterEnabled() { return _clientRouterEnabled; }
 
+// Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
+// Set at boot and on each route rebuild from the route table, the same shape
+// as setClientRouterEnabled above, so no opt has to thread through every
+// render path. Empty by default, which keeps an app that declares its icons
+// (or has neither route) byte-identical.
+/** @type {{ icon: boolean, apple: boolean }} */
+let _metadataIconRoutes = { icon: false, apple: false };
+
+/**
+ * Record the icon metadata routes the app defines.
+ *
+ * @param {Iterable<{ stem: string }> | null | undefined} metadataRoutes
+ *   The route table's `metadataRoutes`, or nullish to clear.
+ */
+export function setMetadataIconRoutes(metadataRoutes) {
+  const stems = new Set();
+  for (const r of metadataRoutes || []) if (r && r.stem) stems.add(r.stem);
+  _metadataIconRoutes = { icon: stems.has('icon'), apple: stems.has('apple-icon') };
+}
+
+/**
+ * The implicit `metadata.icons` an app's icon routes stand for, or null when
+ * it has none. Base-path prefixed, because that is where the routes are
+ * SERVED: the listener strips the base path before matching, so under
+ * `webjs.basePath` the route answers at `<basePath>/icon`. A user-authored
+ * `icons` URL is deliberately left alone (it may be cross-origin, and the
+ * author writes the path they mean), so only these framework-emitted ones
+ * are prefixed.
+ *
+ * No `type` or `sizes` is emitted. A metadata route picks its own content
+ * type at request time, which is the reason to use one, so declaring a type
+ * here could contradict the bytes; and `sizes` is unknowable without reading
+ * the response. Both are optional in HTML, and a browser sniffs the served
+ * content type.
+ *
+ * @returns {{ icon?: string, apple?: string } | null}
+ */
+function autoMetadataRouteIcons() {
+  const { icon, apple } = _metadataIconRoutes;
+  if (!icon && !apple) return null;
+  const bp = basePath();
+  /** @type {{ icon?: string, apple?: string }} */
+  const out = {};
+  if (icon) out.icon = withBasePath('/icon', bp);
+  if (apple) out.apple = withBasePath('/apple-icon', bp);
+  return out;
+}
+
 function wrapHead(opts) {
   // CSP nonce: if provided, all inline <script> tags get nonce="…" so they
   // pass strict Content-Security-Policy headers. The nonce is extracted from
@@ -1837,10 +1885,21 @@ function wrapHead(opts) {
   //   - apple   → <link rel="apple-touch-icon">
   //   - shortcut→ <link rel="shortcut icon">
   //   - other   → <link rel="…" href="…"> using the entry's `rel` field
-  if (m.icons) {
-    const buckets = typeof m.icons === 'string' || Array.isArray(m.icons)
-      ? { icon: m.icons }
-      : m.icons;
+  //
+  // With no `icons` declared, an `app/icon.*` / `app/apple-icon.*` metadata
+  // ROUTE is linked automatically (Next parity). Those routes served their
+  // bytes and nothing referenced them before, so writing the file that every
+  // other framework treats as "this is my favicon" produced a blank tab and no
+  // diagnostic. A declared `icons` SUPPRESSES the routes rather than merging
+  // with them, which is also what Next does: it merges static icon files only
+  // when the resolved metadata has no `icons` of its own. Suppressing matters
+  // here because the file is frequently a placeholder an app has outgrown, and
+  // an author who names their icons has said which ones they want.
+  const declaredOrRouteIcons = m.icons || autoMetadataRouteIcons();
+  if (declaredOrRouteIcons) {
+    const buckets = typeof declaredOrRouteIcons === 'string' || Array.isArray(declaredOrRouteIcons)
+      ? { icon: declaredOrRouteIcons }
+      : declaredOrRouteIcons;
     /** @param {string} rel @param {unknown} entry */
     const pushIcon = (rel, entry) => {
       if (!entry) return;
diff --git a/test/bun/metadata-icon-routes.mjs b/test/bun/metadata-icon-routes.mjs
new file mode 100644
index 000000000..c32cc1c58
--- /dev/null
+++ b/test/bun/metadata-icon-routes.mjs
@@ -0,0 +1,151 @@
+/**
+ * Cross-runtime proof that an `app/icon.*` metadata ROUTE is auto-linked into
+ * the SSR'd head, on both Node and Bun. Run from the repo root:
+ *
+ *   node test/bun/metadata-icon-routes.mjs
+ *   bun  test/bun/metadata-icon-routes.mjs
+ *
+ * This is runtime-sensitive on two counts, which is why it is here and not
+ * only in test/ssr. It rides the SSR head-emission path, and it is wired
+ * through module state that `createRequestHandler` binds at boot from the
+ * route table, so a unit test of the head builder alone would pass while the
+ * real handler emitted nothing. The route files are `.ts`, so resolving them
+ * also crosses each runtime's TypeScript stripper (Node 24+'s built-in one,
+ * amaro on Bun).
+ *
+ * Asserts, on whichever runtime executes it: the route is linked and serves,
+ * a declared `metadata.icons` suppresses it (the Next precedence rule), an app
+ * with neither emits no icon link, and the auto-emitted href carries the app's
+ * `basePath` because that is where the route actually answers.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createRequestHandler } from '../../packages/server/src/dev.js';
+
+const runtime = process.versions.bun ? `bun ${process.versions.bun}` : `node ${process.versions.node}`;
+
+function makeApp(files) {
+  const appDir = mkdtempSync(join(tmpdir(), 'webjs-icon-routes-'));
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = join(appDir, rel);
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(abs, body);
+  }
+  return appDir;
+}
+
+const PAGE = `export default function Home() { return 'home'; }\n`;
+
+// A genuinely TypeScript metadata route, so each runtime's stripper has to
+// handle it before the router can see the file at all.
+const ICON_ROUTE = [
+  'export default function Icon(): Response {',
+  "  return new Response('<svg xmlns=\"http://www.w3.org/2000/svg\"/>', {",
+  "    headers: { 'content-type': 'image/svg+xml' },",
+  '  });',
+  '}',
+  '',
+].join('\n');
+
+const APPLE_ICON_ROUTE = ICON_ROUTE.replace('function Icon', 'function AppleIcon');
+
+/** Every icon href the rendered head declares. */
+async function headIconHrefs(handle, url = 'http://localhost/') {
+  const res = await handle(new Request(url));
+  assert.equal(res.status, 200, `page did not render on ${runtime}`);
+  const head = (await res.text()).split('</head>')[0];
+  return [...head.matchAll(/<link rel="[^"]*icon[^"]*"[^>]*href="([^"]+)"/g)].map((m) => m[1]);
+}
+
+// app/icon.ts with no declared icons: linked, and the link resolves.
+{
+  const appDir = makeApp({ 'app/page.js': PAGE, 'app/icon.ts': ICON_ROUTE });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle);
+  assert.deepEqual(hrefs, ['/icon'], `app/icon.ts was not auto-linked on ${runtime}`);
+
+  // The whole point of the link: the URL it names has to answer.
+  const icon = await h.handle(new Request('http://localhost/icon'));
+  assert.equal(icon.status, 200, `/icon did not serve on ${runtime}`);
+  assert.match(icon.headers.get('content-type') || '', /^image\//, `/icon served no image on ${runtime}`);
+}
+
+// app/apple-icon.ts maps to rel="apple-touch-icon", not a second rel="icon".
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'app/apple-icon.ts': APPLE_ICON_ROUTE,
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const res = await h.handle(new Request('http://localhost/'));
+  const head = (await res.text()).split('</head>')[0];
+  assert.match(head, /<link rel="icon" href="\/icon">/, `icon route missing on ${runtime}`);
+  assert.match(
+    head,
+    /<link rel="apple-touch-icon" href="\/apple-icon">/,
+    `apple-icon route missing on ${runtime}`,
+  );
+}
+
+// A declared metadata.icons wins outright, the way Next merges its static icon
+// files only when the resolved metadata declares no icons of its own.
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'app/apple-icon.ts': APPLE_ICON_ROUTE,
+    'app/layout.js': [
+      "export const metadata = { icons: '/public/brand.svg' };",
+      'export default function Layout({ children }) { return children; }',
+      '',
+    ].join('\n'),
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle);
+  assert.deepEqual(
+    hrefs,
+    ['/public/brand.svg'],
+    `a declared metadata.icons did not suppress the icon routes on ${runtime}`,
+  );
+}
+
+// Neither route nor declaration: no icon link at all. The counterfactual that
+// keeps every existing app byte-identical.
+{
+  const appDir = makeApp({ 'app/page.js': PAGE });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  assert.deepEqual(await headIconHrefs(h.handle), [], `an icon link appeared from nowhere on ${runtime}`);
+}
+
+// Under webjs.basePath the route is SERVED at <basePath>/icon (the listener
+// strips the prefix before matching), so the emitted href has to carry it or
+// the link 404s on exactly the deployments that need it most.
+{
+  const appDir = makeApp({
+    'app/page.js': PAGE,
+    'app/icon.ts': ICON_ROUTE,
+    'package.json': JSON.stringify({ name: 'basepath-icon-app', webjs: { basePath: '/app' } }, null, 2),
+  });
+  const h = await createRequestHandler({ appDir, dev: false });
+  await h.warmup?.();
+
+  const hrefs = await headIconHrefs(h.handle, 'http://localhost/app/');
+  assert.deepEqual(hrefs, ['/app/icon'], `the auto-linked icon href ignored basePath on ${runtime}`);
+
+  const icon = await h.handle(new Request('http://localhost/app/icon'));
+  assert.equal(icon.status, 200, `the base-path icon href did not serve on ${runtime}`);
+}
+
+console.log(`metadata icon routes: auto-link, precedence and basePath OK on ${runtime}`);
diff --git a/test/repo-health/gallery-favicon.test.mjs b/test/repo-health/gallery-favicon.test.mjs
index 4e35320e8..62a0b5402 100644
--- a/test/repo-health/gallery-favicon.test.mjs
+++ b/test/repo-health/gallery-favicon.test.mjs
@@ -106,6 +106,21 @@ test('the gallery serves the same brand mark as the website', async () => {
   );
 });
 
+test('the gallery does not link its app/icon.ts demo route', async () => {
+  // app/icon.ts is the metadata-route DEMO, generating a placeholder grey "w".
+  // It is auto-linked in an app that declares no metadata.icons, so the ONLY
+  // thing keeping the brand mark on gallery.webjs.dev is the precedence rule
+  // that a declaration suppresses the routes. Break that and the gallery
+  // silently reverts to the placeholder, which is the exact defect this file
+  // was written for, so assert the suppression rather than infer it.
+  const app = await makeHandler();
+  const paths = await declaredIconPaths(app.handle);
+  assert.ok(!paths.includes('/icon'), '/icon is not linked');
+  assert.ok(!paths.includes('/apple-icon'), '/apple-icon is not linked');
+  // Both still SERVE; they are browsable demos, just not this app's favicon.
+  assert.equal((await app.handle(new Request('http://localhost/icon'))).status, 200);
+});
+
 test('the gallery declares the raster icon ahead of the SVG', async () => {
   // Same rule the website follows: Google's favicon crawler takes the first
   // usable icon and renders raster reliably. metadata.icons emits array order,
diff --git a/test/repo-health/site-seo-tags.test.mjs b/test/repo-health/site-seo-tags.test.mjs
index bf91fcd9d..c00f56abe 100644
--- a/test/repo-health/site-seo-tags.test.mjs
+++ b/test/repo-health/site-seo-tags.test.mjs
@@ -20,9 +20,16 @@
  * them. `docs.webjs.dev` still resolves, but as a Cloudflare redirect rule
  * with nothing indexable of its own, which is the point of the move.
  *
- * These are source-level assertions on the layout file rather than SSR
- * renders, because the three apps have different dependency trees and
- * importing all of them into one test process is not worth the coupling.
+ * The icon assertions RENDER the app rather than reading its layout source.
+ * They used to regex the layout for hand-written `<link>` markup, which
+ * pinned an authoring style the framework tells apps not to use: only a ROOT
+ * layout may write a shell at all (invariant 8), so a hand-written tag is a
+ * pattern no other layout can copy, and favicons are declared through
+ * `metadata.icons`. Rendering asserts what a browser actually receives, which
+ * is the thing that matters and is also the only way to see icons the
+ * framework splices in. The canonical check stays source-level: it asserts
+ * how the value is DERIVED (origin plus pathname, trailing slash stripped),
+ * which one rendered URL cannot show.
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -30,6 +37,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { createRequestHandler } from '@webjsdev/server';
+
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 /**
@@ -52,49 +61,88 @@ function pngSize(path) {
   return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
 }
 
+/**
+ * The icon `<link>` tags the app's home page actually serves, in head order.
+ *
+ * Rendering is what makes this honest: the tags may come from hand-written
+ * markup, from `metadata.icons`, or from an auto-linked `app/icon.*` metadata
+ * route, and a browser cannot tell the difference. Neither should this.
+ */
+async function renderedIconLinks(dir) {
+  const app = await createRequestHandler({ appDir: resolve(REPO_ROOT, dir), dev: true });
+  const res = await app.handle(new Request('http://localhost/'));
+  assert.equal(res.status, 200, `${dir} home page renders`);
+  // Browsers ignore a favicon <link> in <body>, so only the head counts.
+  const head = (await res.text()).split('</head>')[0];
+  return [...head.matchAll(/<link rel="[^"]*icon[^"]*"[^>]*>/g)].map((m) => m[0]);
+}
+
+/** Pull an attribute off one rendered tag, order-independently. */
+const attr = (tag, name) => (tag.match(new RegExp(`${name}="([^"]*)"`)) || [])[1];
+
 for (const app of APPS) {
-  test(`${app.name}: the declared favicon size matches the real asset`, () => {
-    const src = layoutOf(app.dir);
-    const m = src.match(/<link rel="icon" href="\/public\/([\w.-]+\.png)" type="image\/png" sizes="(\d+)x(\d+)"/);
-    assert.ok(m, 'declares a PNG icon with an explicit size');
+  test(`${app.name}: the declared favicon size matches the real asset`, async () => {
+    const links = await renderedIconLinks(app.dir);
+    const png = links.find((l) => attr(l, 'type') === 'image/png');
+    assert.ok(png, 'serves a PNG icon with an explicit type');
+
+    const href = attr(png, 'href');
+    const sizes = attr(png, 'sizes');
+    assert.ok(sizes, 'the PNG icon declares a size');
+    const [w, h] = sizes.split('x');
+    assert.equal(w, h, 'declared as square');
 
-    const [, file, w, h] = m;
-    const declared = Number(w);
+    const file = href.replace(/^\/public\//, '');
     const asset = publicFile(app.dir, file);
     assert.ok(existsSync(asset), `${file} exists in public/`);
 
     const real = pngSize(asset);
-    assert.equal(w, h, 'declared as square');
     assert.equal(real.width, real.height, 'the asset really is square');
     // The original bug in one assertion: the markup claimed 32 for a 512 file.
-    assert.equal(declared, real.width, 'the DECLARED size matches the real asset');
+    assert.equal(Number(w), real.width, 'the DECLARED size matches the real asset');
     // The second half: 32 was under the floor, and 512 would have failed too,
     // since 512 % 48 is 32. Hence the 192px asset.
-    assert.equal(declared % 48, 0, 'the size is a multiple of 48px, which Google requires');
+    assert.equal(Number(w) % 48, 0, 'the size is a multiple of 48px, which Google requires');
   });
 
-  test(`${app.name}: the raster icon is declared before the SVG`, () => {
+  test(`${app.name}: the raster icon is served before the SVG`, async () => {
     // Google's favicon crawler takes the first usable icon, and raster is what
     // search results reliably render. All three led with the SVG before.
-    const src = layoutOf(app.dir);
-    const png = src.indexOf('type="image/png"');
-    const svg = src.indexOf('/public/favicon.svg');
-    assert.ok(png > -1 && svg > -1, 'declares both a PNG and an SVG icon');
-    assert.ok(png < svg, 'the PNG is declared ahead of the SVG');
+    const links = await renderedIconLinks(app.dir);
+    const png = links.findIndex((l) => attr(l, 'type') === 'image/png');
+    const svg = links.findIndex((l) => attr(l, 'type') === 'image/svg+xml');
+    assert.ok(png > -1 && svg > -1, 'serves both a PNG and an SVG icon');
+    assert.ok(png < svg, 'the PNG comes first in the head');
   });
 
-  test(`${app.name}: the apple-touch icon points at a correctly sized asset`, () => {
-    const src = layoutOf(app.dir);
-    const m = src.match(/<link rel="apple-touch-icon" sizes="(\d+)x\d+" href="\/public\/([\w.-]+\.png)"/);
-    assert.ok(m, 'declares an apple-touch-icon with an explicit size');
-    const asset = publicFile(app.dir, m[2]);
-    assert.ok(existsSync(asset), `${m[2]} exists in public/`);
-    assert.equal(Number(m[1]), pngSize(asset).width, 'the declared size matches the real asset');
+  test(`${app.name}: the apple-touch icon points at a correctly sized asset`, async () => {
+    const links = await renderedIconLinks(app.dir);
+    const apple = links.find((l) => attr(l, 'rel') === 'apple-touch-icon');
+    assert.ok(apple, 'serves an apple-touch-icon');
+    const file = attr(apple, 'href').replace(/^\/public\//, '');
+    const asset = publicFile(app.dir, file);
+    assert.ok(existsSync(asset), `${file} exists in public/`);
+    assert.equal(Number(attr(apple, 'sizes').split('x')[0]), pngSize(asset).width,
+      'the declared size matches the real asset');
+  });
+
+  test(`${app.name}: every icon it links is actually served`, async () => {
+    // A head naming a URL nothing answers is the failure mode that took
+    // gallery.webjs.dev two PRs to shake out, so resolve each href rather than
+    // trusting the markup.
+    const application = await createRequestHandler({ appDir: resolve(REPO_ROOT, app.dir), dev: true });
+    for (const link of await renderedIconLinks(app.dir)) {
+      const href = attr(link, 'href');
+      const res = await application.handle(new Request(`http://localhost${href}`));
+      assert.equal(res.status, 200, `${href} is served, not a 404`);
+    }
   });
 
   test(`${app.name}: ships a root favicon.ico with a 48x48 entry`, () => {
     // The framework serves /favicon.ico from public/favicon.ico. All three
     // returned 404 for it before, so the no-markup crawler fallback was absent.
+    // Deliberately NOT a rendered assertion: nothing links it, which is the
+    // point (crawlers that parse no HTML fetch the path directly).
     const ico = publicFile(app.dir, 'favicon.ico');
     assert.ok(existsSync(ico), 'public/favicon.ico exists');
     const buf = readFileSync(ico);
@@ -105,6 +153,16 @@ for (const app of APPS) {
     assert.ok(sizes.includes(48), `bundles a 48x48 entry, got ${sizes.join('/')}`);
   });
 
+  test(`${app.name}: declares its favicons, rather than hand-writing the markup`, () => {
+    // The convention the framework documents, and what every other app in the
+    // repo does. A hand-written tag works ONLY in a root layout (invariant 8),
+    // so it is a pattern no other layout can copy, and the docs told readers
+    // not to write it while this app did.
+    const src = layoutOf(app.dir);
+    assert.match(src, /icons:\s*\{/, 'declares metadata.icons');
+    assert.doesNotMatch(src, /<link rel="[^"]*icon/, 'writes no icon <link> by hand');
+  });
+
   test(`${app.name}: the root layout emits a canonical URL`, () => {
     const src = layoutOf(app.dir);
     assert.match(src, /alternates:\s*\{\s*canonical\s*\}/, 'sets alternates.canonical in generateMetadata');
diff --git a/test/ssr/ssr.test.js b/test/ssr/ssr.test.js
index c5c6f1ea4..1b5414b21 100644
--- a/test/ssr/ssr.test.js
+++ b/test/ssr/ssr.test.js
@@ -20,7 +20,7 @@ const WEBJS_MODULE_URL = pathToFileURL(
   resolve(__dirname, '../../packages/core/index.js')
 ).toString();
 
-let _hoistHeadTags, _extractUserShell, _buildDocumentParts, ssrPage, ssrNotFound;
+let _hoistHeadTags, _extractUserShell, _buildDocumentParts, ssrPage, ssrNotFound, setMetadataIconRoutes;
 let withRequest;
 let tmpDir;
 
@@ -31,6 +31,7 @@ before(async () => {
     _buildDocumentParts,
     ssrPage,
     ssrNotFound,
+    setMetadataIconRoutes,
   } = await import('../../packages/server/src/ssr.js'));
   // The CSP nonce now flows through the per-request AsyncLocalStorage store
   // (issue #233): `cspNonce()` reads the minted nonce there, or falls back
@@ -655,6 +656,66 @@ test('metadata.icons.other: arbitrary rel allowed', () => {
   assert.match(html, /<link rel="mask-icon" href="\/mask\.svg" type="image\/svg\+xml">/);
 });
 
+/* ------------ Auto-linked icon metadata routes ------------ */
+
+// `app/icon.*` served its bytes and nothing linked them, so the file every
+// other framework treats as "this is my favicon" produced a blank tab with no
+// diagnostic. Next links its static icon files; these pin the parity, and the
+// precedence rule that comes with it.
+//
+// setMetadataIconRoutes is module state (the setClientRouterEnabled shape), so
+// each test clears it rather than leaking a link into every later assertion.
+const withIconRoutes = (t, stems) => {
+  setMetadataIconRoutes(stems.map((stem) => ({ stem })));
+  t.after(() => setMetadataIconRoutes(null));
+};
+
+test('icon metadata route: linked automatically when no icons are declared', (t) => {
+  withIconRoutes(t, ['icon']);
+  assert.match(render({}), /<link rel="icon" href="\/icon">/);
+});
+
+test('apple-icon metadata route: linked as apple-touch-icon', (t) => {
+  withIconRoutes(t, ['icon', 'apple-icon']);
+  const html = render({});
+  assert.match(html, /<link rel="icon" href="\/icon">/);
+  assert.match(html, /<link rel="apple-touch-icon" href="\/apple-icon">/);
+});
+
+test('icon metadata route: no type or sizes is asserted for it', (t) => {
+  // The route picks its content type at request time, which is the reason to
+  // use one, so a declared type could contradict the bytes it serves.
+  withIconRoutes(t, ['icon']);
+  assert.match(render({}), /<link rel="icon" href="\/icon">/);
+  assert.doesNotMatch(render({}), /href="\/icon"[^>]*(type|sizes)=/);
+});
+
+test('a declared metadata.icons suppresses the icon route (Next precedence)', (t) => {
+  // Next merges its static icon files only when the resolved metadata has no
+  // `icons`. An author who names their icons has said which ones they want,
+  // and the route is often a placeholder the app has outgrown, which is
+  // exactly the gallery's case.
+  withIconRoutes(t, ['icon', 'apple-icon']);
+  const html = render({ icons: '/public/favicon.svg' });
+  assert.match(html, /<link rel="icon" href="\/public\/favicon\.svg">/);
+  assert.doesNotMatch(html, /href="\/icon"/);
+  assert.doesNotMatch(html, /href="\/apple-icon"/);
+});
+
+test('non-icon metadata routes never emit an icon link', (t) => {
+  // sitemap / robots / manifest / og-image share the metadata-route mechanism
+  // and are not favicons.
+  withIconRoutes(t, ['sitemap', 'robots', 'manifest', 'opengraph-image', 'twitter-image']);
+  assert.doesNotMatch(render({}), /<link rel="[^"]*icon/);
+});
+
+test('no icon route and no declared icons: no icon link at all', (t) => {
+  // The counterfactual for the whole feature. An app with neither must render
+  // byte-identically to before.
+  withIconRoutes(t, []);
+  assert.doesNotMatch(render({}), /<link rel="[^"]*icon/);
+});
+
 test('metadata.icons + metadataBase: relative URLs are absolutified', () => {
   const html = render({
     metadataBase: 'https://example.com',
diff --git a/website/app/docs/metadata-routes/page.ts b/website/app/docs/metadata-routes/page.ts
index ac800726d..df762e1e7 100644
--- a/website/app/docs/metadata-routes/page.ts
+++ b/website/app/docs/metadata-routes/page.ts
@@ -96,6 +96,34 @@ export default function manifest() {
   };
 }</code-block>
 
+    <h2>icon.ts and apple-icon.ts</h2>
+    <p>These two are <strong>linked into the head for you</strong>. Writing the file is the whole wiring, with no <code>&lt;link&gt;</code> to add anywhere:</p>
+    <code-block>// app/icon.ts  ->  serves /icon AND emits the link
+export default function Icon() {
+  const svg = '&lt;svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"&gt;...&lt;/svg&gt;';
+  return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
+}</code-block>
+    <code-block>&lt;!-- what lands in &lt;head&gt; --&gt;
+&lt;link rel="icon" href="/icon"&gt;
+&lt;link rel="apple-touch-icon" href="/apple-icon"&gt;</code-block>
+    <p>The href carries your <code>basePath</code>, because that is where the route answers. No <code>type</code> or <code>sizes</code> is asserted: a metadata route picks its content type at request time, which is the reason to use one, so declaring a type here could contradict the bytes it serves. Browsers sniff the served type.</p>
+    <p>Reach for a route when the mark must be computed per request (per theme, per tenant). For a favicon that never changes, a static file in <code>public/</code> declared through <code>metadata.icons</code> is simpler and cacheable.</p>
+
+    <h3>Declaring icons wins</h3>
+    <p>A <code>metadata.icons</code> declaration <strong>replaces</strong> the routes rather than merging with them, the same precedence Next applies to its static icon files. An app that outgrows a placeholder <code>app/icon.ts</code> names its real icons and the route stops being linked, without the file having to be deleted:</p>
+    <code-block>// app/layout.ts  ->  these win; /icon is no longer linked
+export const metadata = {
+  icons: {
+    icon: [
+      { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+      { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+    ],
+    apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+  },
+};</code-block>
+    <p>Declare a favicon one of those two ways, never as a hand-written <code>&lt;link rel="icon"&gt;</code>: only the root layout may write a document shell at all, so a hand-written tag is unavailable to every other layout. A <code>public/favicon.ico</code> needs no declaration either way, since it is served at the origin root for crawlers that read no markup.</p>
+    <p><code>opengraph-image.ts</code> and <code>twitter-image.ts</code> are <em>not</em> auto-linked, because a preview image is a per-page editorial choice rather than a site-wide default. Point <code>openGraph.images</code> / <code>twitter.images</code> at them.</p>
+
     <h2>Page-level metadata</h2>
     <p>For per-page title, description, and Open Graph tags, export a <code>metadata</code> object from any <code>page.ts</code>. Annotate it with the <code>Metadata</code> type (imported from <code>@webjsdev/core</code>) so a misspelled field or a wrong-typed value is a compile-time error:</p>
 
diff --git a/website/app/layout.ts b/website/app/layout.ts
index 5231941c2..56793df7a 100644
--- a/website/app/layout.ts
+++ b/website/app/layout.ts
@@ -64,6 +64,29 @@ export function generateMetadata(ctx: { url: string }) {
     cacheControl: 'public, max-age=60, s-maxage=600, stale-while-revalidate=86400',
     title: TITLE,
     description: DESCRIPTION,
+    // Favicons, ordered raster first on purpose. Google's favicon crawler takes
+    // the first usable icon and wants a SQUARE raster whose side is a multiple
+    // of 48px. This once declared sizes="32x32" on an asset that is really
+    // 512x512: the claim was both wrong and under Google's 48px floor, which is
+    // why webjs.dev showed no icon in search results. 192 is used because it is
+    // a clean multiple of 48 (512 is not, 512 % 48 = 32).
+    //
+    // Declared here rather than hand-written into the shell below, which is the
+    // way the framework documents and the way every other app in the repo does
+    // it. A hand-written tag only works because this is the ROOT layout, the
+    // one layout allowed to write a shell at all (invariant 8), so it was a
+    // pattern no other layout could copy.
+    //
+    // /favicon.ico is absent on purpose: it is served from public/favicon.ico
+    // at the origin root and stays the fallback for crawlers that read no
+    // markup, so linking it would add a tag nothing reads.
+    icons: {
+      icon: [
+        { url: '/public/favicon-192.png', type: 'image/png', sizes: '192x192' },
+        { url: '/public/favicon.svg', type: 'image/svg+xml', sizes: 'any' },
+      ],
+      apple: { url: '/public/apple-touch-icon.png', sizes: '180x180' },
+    },
     openGraph: {
       type: 'website',
       title: TITLE,
@@ -85,17 +108,8 @@ const panelLink = 'text-fg-muted no-underline font-medium text-sm px-3 py-2.5 ro
 export default function RootLayout({ children }: LayoutProps) {
   const nonce = cspNonce();
   return html`
-    <!-- Favicons, ordered raster first on purpose. Google's favicon crawler takes
-         the first usable icon and wants a SQUARE raster whose side is a multiple
-         of 48px. This previously declared sizes="32x32" on an asset that is
-         really 512x512: the claim was both wrong and under Google's 48px floor,
-         which is why webjs.dev showed no icon in search results. 192 is used
-         because it is a clean multiple of 48 (512 is not, 512 % 48 = 32).
-         /favicon.ico is served from public/favicon.ico at the origin root and
-         stays as the fallback for crawlers that read no markup at all. -->
-    <link rel="icon" href="/public/favicon-192.png" type="image/png" sizes="192x192">
-    <link rel="icon" href="/public/favicon.svg" type="image/svg+xml" sizes="any">
-    <link rel="apple-touch-icon" sizes="180x180" href="/public/apple-touch-icon.png">
+    <!-- Favicons are declared in generateMetadata above (metadata.icons), not
+         written here. The framework splices them into <head>. -->
 
     <!-- Self-hosted fonts (declared via @font-face in input.css), preloaded so
          they fetch in parallel with the stylesheet instead of being discovered
