create-kywi-app 0.19.0 → 0.20.0

package/lib/templates.mjs

@@ -32,6 +32,7 @@
  * ships session fixes without the app hand-maintaining crypto.
  */
 
+import { createHash } from 'node:crypto'
 import { readFileSync, existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -468,66 +469,162 @@ public/kywi-admin.css.version
 // ── the generated render path: version stamp + landmarks ─────────────────────
 
 /**
- * Version of the GENERATED RENDER PATH's SHAPE — the four thin delegating files
- * below (`lib/kywi.ts`, `app/(site)/layout.tsx`,
- * `app/(site)/[[...slug]]/page.tsx`, `middleware.ts`), independent of the
- * package version. Bump it when their shape changes in a way an existing
- * project should pick up, so a project can compare its stamp against a newer
- * create-kywi-app and know its render path is stale.
+ * Version of the GENERATED RENDER PATH's SHAPE — the eleven generated files
+ * {@link RENDER_LANDMARK_PATHS} names, independent of the package version. Bump
+ * it when their shape changes in a way an existing project should pick up, so a
+ * project can compare its stamp against a newer create-kywi-app and know its
+ * render path is stale.
+ *
+ * **v2 (plan E3 Task 1)** adds an INTEGRITY HASH to the stamp and extends the
+ * stamped set from five files to eleven. A v1 stamp says only "create-kywi-app
+ * X emitted a v1-shaped file here"; a v2 stamp additionally proves whether the
+ * file is still byte-for-byte that emission. That is the distinction
+ * `create-kywi-app upgrade` (plan E3) needs: an UNTOUCHED generated file can be
+ * replaced silently, an EDITED one must never be clobbered, and before v2 the
+ * two were indistinguishable without diffing against every historical emission.
  *
  * Exactly the {@link GUIDANCE_VERSION} / {@link guidanceStamp} convention, one
  * namespace over: `kywi-render` where the guidance files say
  * `kywi-agent-guidance`. `layered-architecture DESIGN.md` §6 names that
- * mechanism as the one `create-kywi-app upgrade` (plan E3) extends to these
- * files — this is the half E1 owns, the emission of a detectable stamp.
+ * mechanism as the one `create-kywi-app upgrade` extends to these files.
+ */
+export const RENDER_VERSION = 2
+
+/**
+ * The integrity half of the stamp: the first 12 hex characters of the sha256 of
+ * the file body that FOLLOWS the stamp line — the exact bytes, with no
+ * normalisation of whitespace or line endings, so any edit at all changes it.
+ * 48 bits is far more than enough to catch an edit (this is a tamper-EVIDENCE
+ * check, not a security boundary) and keeps the stamp line readable.
+ * @param {string} body  everything after the stamp line's newline
+ * @returns {string} 12 lowercase hex characters
+ */
+export function hashRenderBody(body) {
+  return createHash('sha256').update(body, 'utf8').digest('hex').slice(0, 12)
+}
+
+/**
+ * The staleness + integrity stamp every generated render-path file opens with. A
+ * `//` comment rather than the guidance files' `<!-- … -->` (these are
+ * .ts/.tsx), so it is inert to the compiler but greppable by tooling and by an
+ * agent asking "is this project's render path current, and untouched?".
+ * @param {string} body  the file body the stamp will precede
+ * @returns {string}
  */
-export const RENDER_VERSION = 1
+export function renderStamp(body) {
+  return `// kywi-render v${RENDER_VERSION} (create-kywi-app ${packageVersion()}) sha256:${hashRenderBody(body)}`
+}
 
 /**
- * The staleness stamp every generated render-path file opens with. A `//`
- * comment rather than the guidance files' `<!-- … -->` (these are .ts/.tsx),
- * so it is inert to the compiler but greppable by tooling and by an agent
- * asking "is this project's render path current?".
+ * A body plus its own stamp — what every render-path emitter returns.
+ * @param {string} body
  * @returns {string}
  */
-export function renderStamp() {
-  return `// kywi-render v${RENDER_VERSION} (create-kywi-app ${packageVersion()})`
+export function stamped(body) {
+  return `${renderStamp(body)}\n${body}`
+}
+
+/**
+ * Splits a stamped file back into `{ stamp, body }`. The body is the text with
+ * its first line removed WHEN that line is a stamp; an unstamped file comes back
+ * whole with `stamp: null`, so a caller can hash the same bytes either way.
+ * @param {string} text
+ * @returns {{ stamp: string|null, body: string }}
+ */
+export function splitRenderStamp(text) {
+  const newline = text.indexOf('\n')
+  const firstLine = newline === -1 ? text : text.slice(0, newline)
+  if (!RENDER_STAMP_RE.test(firstLine)) return { stamp: null, body: text }
+  return { stamp: firstLine, body: newline === -1 ? '' : text.slice(newline + 1) }
 }
 
 /**
  * Parses a {@link renderStamp} back out of a file's text:
- * `[, renderVersion, cliVersion]`. Anchored to a whole line so a mention of the
- * stamp inside prose cannot match.
+ * `[, renderVersion, cliVersion, bodyHash]`. Anchored to a whole line so a
+ * mention of the stamp inside prose cannot match. The hash group is OPTIONAL:
+ * a project scaffolded before v2 carries a hashless stamp, and `upgrade` must
+ * still be able to read its version rather than treating it as hand-written.
  */
-export const RENDER_STAMP_RE = /^\/\/ kywi-render v(\d+) \(create-kywi-app ([^)]+)\)$/m
+export const RENDER_STAMP_RE = /^\/\/ kywi-render v(\d+) \(create-kywi-app ([^)]+)\)(?: sha256:([0-9a-f]{12}))?$/m
+
+/** @typedef {'runtime'|'middleware'|'siteLayout'|'sitePage'|'layers'|'apiRoute'|'axLlms'|'axLlmsFull'|'axSitemap'|'axRobots'|'adminHost'} RenderLandmark */
 
 /**
- * Landmark → its relative path, for the RENDER PATH: one entry per thin,
- * version-stamped file the scaffold emits at a path Next demands. Same role as
- * {@link AGENTS_LANDMARK_PATHS} — one source of truth for the path strings —
- * shared by the emitter ({@link buildFileSet}), the E8 drift guard
- * (`__tests__/render-drift.test.mjs`) and, in plan E3, the `upgrade` command.
- * @type {Record<'runtime'|'middleware'|'siteLayout'|'sitePage', string>}
+ * Landmark → its relative path, for the RENDER PATH: one entry per generated
+ * file the scaffold emits at a path Next demands and stamps with {@link
+ * renderStamp}. Same role as {@link AGENTS_LANDMARK_PATHS} — one source of
+ * truth for the path strings — shared by the emitter ({@link buildFileSet}),
+ * the E8 drift guard (`__tests__/render-drift.test.mjs`) and, in plan E3, the
+ * `upgrade` command.
+ *
+ * ALL ELEVEN generated render files are listed, not just the thin delegates
+ * (plan E3 Task 1). The membership rule is "create-kywi-app wrote it and owns
+ * its shape", because that is what `upgrade` must be able to find and — when
+ * the stamp's hash proves the file untouched — replace. The API route, the four
+ * AX root routes and the admin host page qualify on exactly that basis; the
+ * project-owned files a site actually edits (`kywi.config.ts`, `site.css`,
+ * `lib/modules.tsx`, `components/site-nav.tsx`, the `sites/` layers) do not,
+ * and stay unstamped.
+ * @type {Record<RenderLandmark, string>}
  */
 export const RENDER_LANDMARK_PATHS = {
   runtime: 'lib/kywi.ts',
   middleware: 'middleware.ts',
   siteLayout: 'app/(site)/layout.tsx',
   sitePage: 'app/(site)/[[...slug]]/page.tsx',
+  layers: 'kywi.layers.ts',
+  apiRoute: 'app/api/v1/[...kywi]/route.ts',
+  axLlms: 'app/llms.txt/route.ts',
+  axLlmsFull: 'app/llms-full.txt/route.ts',
+  axSitemap: 'app/sitemap.xml/route.ts',
+  axRobots: 'app/robots.txt/route.ts',
+  adminHost: 'app/admin/[[...admin]]/page.tsx',
 }
 
+/**
+ * The render-path files a PRE-E1 project still carries and a current one must
+ * not: their contents moved into `@kywi-software/core/next`. One list, so the
+ * E8 drift guard (which fails if the scaffold emits any of them) and plan E3's
+ * `upgrade` (which deletes them from an existing project) cannot disagree about
+ * the set.
+ * @type {string[]}
+ */
+export const LEGACY_RENDER_FILES = [
+  'lib/site.ts',
+  'lib/config.ts',
+  'lib/kywi-js-loader.ts',
+  'components/kywi-js-loader.tsx',
+  'components/personalization-runtime.tsx',
+  'app/(site)/kywi-front-edit.tsx',
+]
+
 /**
  * Which render-path files a FRESH scaffold of the given mode emits — derived
  * statically from the mode, never from the filesystem ({@link
- * scaffoldLandmarks}'s counterpart for the render path). The wiring runtime and
- * the middleware exist in every mode; the two `app/(site)` routes are coupled
- * mode only.
+ * scaffoldLandmarks}'s counterpart for the render path). The wiring runtime, the
+ * middleware, the layer registry, the API route, the four AX root routes and the
+ * admin host page exist in every mode (the admin and the API are identical
+ * across all three, and the AX routes are agent-facing projections of published
+ * content rather than public HTML rendering); only the two `app/(site)` routes
+ * are coupled mode only.
  * @param {'coupled'|'headless'|'decoupled'} mode
- * @returns {Record<'runtime'|'middleware'|'siteLayout'|'sitePage', boolean>}
+ * @returns {Record<RenderLandmark, boolean>}
  */
 export function renderLandmarks(mode) {
   const coupled = mode === 'coupled'
-  return { runtime: true, middleware: true, siteLayout: coupled, sitePage: coupled }
+  return {
+    runtime: true,
+    middleware: true,
+    siteLayout: coupled,
+    sitePage: coupled,
+    layers: true,
+    apiRoute: true,
+    axLlms: true,
+    axLlmsFull: true,
+    axSitemap: true,
+    axRobots: true,
+    adminHost: true,
+  }
 }
 
 /**
@@ -538,26 +635,101 @@ export function renderLandmarks(mode) {
  * while an unstamped one was hand-written or predates the layered shape
  * (`layered-architecture DESIGN.md` §8) and must be ejected, not clobbered.
  * E1 only emits and detects; E3 acts on it.
+ *
+ * `intact` is the v2 addition and the field `upgrade` actually branches on:
+ *   - `true`  — the stamp's hash matches the body on disk: untouched
+ *               create-kywi-app output, safe to replace.
+ *   - `false` — a hash is present and does NOT match: the file was edited after
+ *               it was generated, so replacing it would destroy work.
+ *   - `null`  — integrity is UNKNOWABLE: the file is absent or unstamped, or it
+ *               carries a hashless v1 stamp from a project scaffolded before
+ *               plan E3. Not the same claim as `false`, and callers must not
+ *               collapse the two.
  * @param {string} projectDir  absolute path to the project root
- * @returns {Record<string, { path: string, present: boolean, version: number|null, cliVersion: string|null }>}
+ * @returns {Record<string, { path: string, present: boolean, version: number|null, cliVersion: string|null, hash: string|null, intact: boolean|null }>}
  */
 export function detectRenderLandmarks(projectDir) {
-  /** @type {Record<string, { path: string, present: boolean, version: number|null, cliVersion: string|null }>} */
+  /** @type {Record<string, { path: string, present: boolean, version: number|null, cliVersion: string|null, hash: string|null, intact: boolean|null }>} */
   const out = {}
   for (const [key, rel] of Object.entries(RENDER_LANDMARK_PATHS)) {
     const abs = join(projectDir, rel)
     const present = existsSync(abs)
-    const match = present ? RENDER_STAMP_RE.exec(readFileSync(abs, 'utf8')) : null
+    const text = present ? readFileSync(abs, 'utf8') : null
+    const { stamp, body } = text === null ? { stamp: null, body: '' } : splitRenderStamp(text)
+    const match = stamp === null ? null : RENDER_STAMP_RE.exec(stamp)
+    const hash = match ? (match[3] ?? null) : null
     out[key] = {
       path: rel,
       present,
       version: match ? Number(match[1]) : null,
       cliVersion: match ? match[2] : null,
+      hash,
+      intact: hash === null ? null : hash === hashRenderBody(body),
     }
   }
   return out
 }
 
+/**
+ * UNSTAMPED emissions from a published create-kywi-app version that
+ * `create-kywi-app upgrade` must still recognise as its own output, even
+ * though they carry no {@link renderStamp}.
+ *
+ * WHY THIS EXISTS. create-kywi-app 0.19.0 (git tag `v0.19.0`, commit
+ * `cc8259d`) emitted six of the eleven {@link RENDER_LANDMARK_PATHS} files —
+ * the API route, the four AX root routes and the admin host page — via
+ * `apiRoute()`, `axRootRoute(axPath)` and `adminCatchAllPage()`, and none of
+ * those three functions wrapped their return value in {@link stamped}; only
+ * the other five emitters (`libKywi`, `middleware`, `siteLayout`, `sitePage`,
+ * `kywiLayers`) did. So a project scaffolded by 0.19.0 has six generated
+ * files `detectRenderLandmarks` reports as `present: true, version: null` —
+ * indistinguishable, by the stamp alone, from a hand-written file, which is
+ * why `upgrade` refused them and demanded `--force` even though nothing of
+ * the project owner's is in them.
+ *
+ * Those six emissions were ANSWER-INDEPENDENT at 0.19.0 (none of the three
+ * functions reads `answers`), so their exact bytes are knowable, and their
+ * WHOLE-FILE hash ({@link hashRenderBody} over the entire text, since there
+ * is no stamp line to split off first) identifies them just as reliably as a
+ * stamp's hash identifies an intact stamped file. `create-kywi-app upgrade`
+ * checks an UNSTAMPED present landmark's whole-content hash against this
+ * table before refusing it as `unstamped`; a match is classified `replace`
+ * exactly as a stamped-and-intact file would be.
+ *
+ * HOW THESE HASHES WERE COMPUTED (to verify or recompute them):
+ *   1. `git show v0.19.0:packages/create-kywi-app/lib/templates.mjs >
+ *      packages/create-kywi-app/lib/.baseline-0.19.0.mjs` — written INSIDE
+ *      `lib/` so the historical module's own relative `../package.json` and
+ *      `../assets/*` reads resolve against the real package.
+ *   2. Import that module and call `buildFileSet({ projectName: 'kywi-app',
+ *      dbProvider: 'postgresql', authProviders: ['credentials'], mode:
+ *      'coupled', kywiVersion: '0.19.0' })`. `mode: 'coupled'` because it is
+ *      the superset (all eleven landmarks); the six paths below are
+ *      answer-independent, so a headless/decoupled build would hash
+ *      identically.
+ *   3. For each of the six paths below, `hashRenderBody(files[path])` — the
+ *      WHOLE file, not a body-after-stamp, since 0.19.0 wrote no stamp line
+ *      for these six.
+ *   4. Delete the baseline copy — it must never be committed.
+ *
+ * THIS TABLE IS CLOSED AT SIX ENTRIES. It grows only if some future
+ * create-kywi-app release ships an unstamped render-landmark emission again —
+ * which the stamp discipline this file now enforces ({@link RENDER_VERSION},
+ * every {@link RENDER_LANDMARK_PATHS} emitter routing through {@link
+ * stamped}) forbids from happening again. There is no code path left in
+ * `buildFileSet` that can produce a seventh unstamped landmark from a current
+ * release, so a new entry here would mean that guarantee broke.
+ * @type {Record<string, Record<string, string>>}
+ */
+export const KNOWN_UNSTAMPED_EMISSIONS = {
+  'app/api/v1/[...kywi]/route.ts': { '370fca738a32': 'create-kywi-app 0.19.0' },
+  'app/llms.txt/route.ts': { '9228324de82e': 'create-kywi-app 0.19.0' },
+  'app/llms-full.txt/route.ts': { 'c4ec73448df6': 'create-kywi-app 0.19.0' },
+  'app/sitemap.xml/route.ts': { 'f7d60cf68c99': 'create-kywi-app 0.19.0' },
+  'app/robots.txt/route.ts': { 'd0e1a402e5d0': 'create-kywi-app 0.19.0' },
+  'app/admin/[[...admin]]/page.tsx': { '929264b9d714': 'create-kywi-app 0.19.0' },
+}
+
 // ── the wiring runtime (lib/kywi.ts) ──────────────────────────────────────────
 
 /**
@@ -572,8 +744,7 @@ export function detectRenderLandmarks(projectDir) {
  * config in — see `packages/core/src/next/runtime.ts`'s header.
  */
 function libKywi() {
-  return `${renderStamp()}
-// This app's ONE Kywi wiring point. The render path lives in
+  return stamped(`// This app's ONE Kywi wiring point. The render path lives in
 // @kywi-software/core/next and reads kywi.config.ts THROUGH this runtime — a
 // package cannot import your config itself. Regenerated by
 // \`create-kywi-app upgrade\`: make your changes in kywi.config.ts, not here.
@@ -585,7 +756,7 @@ export const kywi = createKywiNextRuntime(config)
 // Named accessors for the API + AX route handlers, which want the handler
 // rather than the whole runtime.
 export const { getKywi, getKywiHandler, getActiveSite } = kywi
-`
+`)
 }
 
 // ── middleware.ts (a re-export of core's own) ─────────────────────────────────
@@ -602,15 +773,198 @@ export const { getKywi, getKywiHandler, getActiveSite } = kywi
  * `./host` split (see that file's header in core).
  */
 function middleware() {
-  return `${renderStamp()}
-// Auth gate, session refresh, the cookie→bearer bridge, the visitor/UTM/entry
+  return stamped(`// Auth gate, session refresh, the cookie→bearer bridge, the visitor/UTM/entry
 // cookies and .md content negotiation — all core's, all upgraded with the
 // package. Imported from its OWN entry, never the \`/next\` barrel: that barrel
 // reaches the database and sharp, which no edge bundle can carry.
 export { middleware, config } from '@kywi-software/core/next/middleware'
+`)
+}
+
+// ── kywi.layers.ts + the sites/ layer files ──────────────────────────────────
+
+/**
+ * WHICH sites and themes a project's layer registry enumerates. A fresh
+ * scaffold has exactly one of each; a real project grows more, and `upgrade`
+ * derives this from the project's own `kywi.config.ts` (`registryLayout` over
+ * `lib/config-scan.mjs`'s scan) rather than from this hard-wired default.
+ *
+ * The registry must match the config EXACTLY: core's `assertLayerContracts`
+ * (plan E2) throws at boot when a configured site — or its theme — has no
+ * layer, so a registry regenerated from anything but the config is a
+ * production outage waiting for the next deploy.
+ * @typedef {{ sites: Array<{ id: string, theme: string|null }>, themes: Array<{ name: string }> }} RegistryLayout
+ */
+
+/**
+ * What a fresh scaffold emits: one site, one theme, both named `default`.
+ * @type {RegistryLayout}
+ */
+export const DEFAULT_REGISTRY_LAYOUT = {
+  sites: [{ id: 'default', theme: 'default' }],
+  themes: [{ name: 'default' }],
+}
+
+/**
+ * A {@link scanKywiConfig} result narrowed to what the emitters need. It drops
+ * NOTHING — a site whose theme the scanner could not read comes through with
+ * `theme: null`, because `upgrade` has to be able to tell the owner which site
+ * it could not generate a theme layer for, and a silently shortened list
+ * cannot.
+ * @param {{ sites?: Array<{ id: string, theme?: string|null }>, themes?: Array<{ name: string }> }} scan
+ * @returns {RegistryLayout}
+ */
+export function registryLayout(scan) {
+  return {
+    sites: (scan?.sites ?? []).map(({ id, theme }) => ({ id, theme: theme ?? null })),
+    themes: (scan?.themes ?? []).map(({ name }) => ({ name })),
+  }
+}
+
+/** A bare `key: value` is legal only for an identifier-safe key; everything else is quoted. */
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** @param {string} key */
+function objectKey(key) {
+  return IDENTIFIER_RE.test(key) ? key : `'${key.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+}
+
+/** `northwind-analytics-demo` → `northwindAnalyticsDemo`; the import alias stem for a site id. */
+function camelIdentifier(id) {
+  const parts = String(id).split(/[^A-Za-z0-9]+/).filter(Boolean)
+  if (parts.length === 0) return 'site'
+  const head = parts[0].replace(/^[0-9]+/, '') || 'x'
+  return (
+    head[0].toLowerCase() +
+    head.slice(1) +
+    parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1)).join('')
+  )
+}
+
+/** Keeps alias collisions (`my-site` and `my_site` both camel to `mySite`) out of the emitted file. */
+function uniqueAlias(base, used) {
+  let alias = base
+  for (let n = 2; used.has(alias); n++) alias = `${base}${n}`
+  used.add(alias)
+  return alias
+}
+
+/**
+ * Group a layout's sites into ONE registry entry per site id, each carrying its
+ * distinct themes with a deterministic import alias. Grouping (rather than
+ * emitting one entry per array element) is what stops a config that names a
+ * site twice from producing a file with a duplicate object key and two
+ * identical `import * as` lines — neither of which compiles.
+ */
+function registryEntries(layout) {
+  /** @type {Map<string, { id: string, themes: string[] }>} */
+  const bySite = new Map()
+  for (const site of layout.sites ?? []) {
+    const entry = bySite.get(site.id) ?? { id: site.id, themes: [] }
+    if (site.theme && !entry.themes.includes(site.theme)) entry.themes.push(site.theme)
+    bySite.set(site.id, entry)
+  }
+
+  const used = new Set()
+  return [...bySite.values()].map(({ id, themes }) => {
+    const stem = camelIdentifier(id)
+    return {
+      id,
+      siteAlias: uniqueAlias(`${stem}Site`, used),
+      themes: themes.map((theme) => ({ theme, alias: uniqueAlias(`${stem}Theme`, used) })),
+    }
+  })
+}
+
+/**
+ * `kywi.layers.ts` — the build-time enumerable registry core's layer resolver
+ * reads. Every site in the project's config gets an entry; every (site, theme)
+ * pair gets an import, because a theme layer lives UNDER its site
+ * (`sites/<id>/themes/<theme>/`), so two sites sharing the name `default` are
+ * two different modules, not one.
+ * @param {RegistryLayout} layout
+ */
+export function kywiLayers(layout = DEFAULT_REGISTRY_LAYOUT) {
+  const entries = registryEntries(layout)
+  const imports = [
+    `import type { KywiLayerRegistry } from '@kywi-software/core/next'`,
+    ...entries.map((e) => `import * as ${e.siteAlias} from './sites/${e.id}'`),
+    ...entries.flatMap((e) =>
+      e.themes.map((t) => `import * as ${t.alias} from './sites/${e.id}/themes/${t.theme}'`),
+    ),
+  ]
+  const body = entries.map((e) => {
+    const themes =
+      e.themes.length === 0
+        ? '    themes: {},'
+        : ['    themes: {', ...e.themes.map((t) => `      ${objectKey(t.theme)}: ${t.alias},`), '    },'].join('\n')
+    return [`  ${objectKey(e.id)}: {`, `    site: ${e.siteAlias},`, themes, '  },'].join('\n')
+  })
+
+  return stamped(`// Generated registry for Kywi's layer chain. Regenerated by create-kywi-app
+// upgrade; edit files under sites/<site>/ instead of editing this file.
+${imports.join('\n')}
+
+export const layers = {
+${body.join('\n')}
+} satisfies KywiLayerRegistry
+`)
+}
+
+/**
+ * `sites/<id>/index.ts` — identical for every site: the custom-module map is
+ * project-wide (one `lib/modules.tsx`), so what varies per site is the theme
+ * and the content, not this re-export.
+ */
+function siteLayer() {
+  return `// This site's layer: overrides core defaults and loses to theme overrides.
+// The custom-module map stays authored in lib/modules.tsx (kywi-cms#48);
+// this re-export is what wires it into the layer chain.
+export { moduleComponents as modules } from '../../lib/modules'
 `
 }
 
+/**
+ * `sites/<id>/themes/<theme>/index.tsx`. The four `../` are fixed, not derived:
+ * the path shape is always `sites/<id>/themes/<theme>/index.tsx`, four levels
+ * below the project root, whatever the site and theme are called.
+ * @param {Answers['mode']} mode - nav template only in coupled mode (components/site-nav.tsx is a coupled-only emit).
+ */
+function themeLayer(mode) {
+  if (mode !== 'coupled') {
+    return `import type { KywiLayerModule } from '@kywi-software/core/next'
+
+export const templates = {} satisfies NonNullable<KywiLayerModule['templates']>
+`
+  }
+  return `import { SiteNav } from '../../../../components/site-nav'
+import type { KywiLayerModule } from '@kywi-software/core/next'
+
+export const templates = {
+  nav: SiteNav,
+} satisfies NonNullable<KywiLayerModule['templates']>
+`
+}
+
+/**
+ * The `sites/**` half of the layer chain: one index per site, one per
+ * (site, theme) pair. Paired with {@link kywiLayers} — the registry names
+ * exactly these files, so they are generated from the same layout or the
+ * project does not compile.
+ * @param {RegistryLayout} layout
+ * @param {Answers['mode']} mode
+ * @returns {Record<string, string>}
+ */
+export function layerFilesFor(layout, mode) {
+  /** @type {Record<string, string>} */
+  const files = {}
+  for (const site of layout.sites ?? []) {
+    files[`sites/${site.id}/index.ts`] = siteLayer()
+    if (site.theme) files[`sites/${site.id}/themes/${site.theme}/index.tsx`] = themeLayer(mode)
+  }
+  return files
+}
+
 // ── root layout + public site ────────────────────────────────────────────────
 
 function rootLayout() {
@@ -685,35 +1039,28 @@ export function SiteNav({ items, variant, ariaLabel, depth }: SiteNavProps) {
  *  1. **Both CSS imports.** Next admits a global stylesheet only from a file
  *     inside `app/`, and a published package cannot import the project's own
  *     `site.css` at all (`layered-architecture DESIGN.md` §4.1).
- *  2. **The brand label**, because the scaffold bakes the project name in.
- *     Core defaults it to the ACTIVE site's configured `name`; passing it
- *     explicitly preserves what the template has always emitted.
- *  3. **The nav component**, wired explicitly to `components/site-nav.tsx`.
- *     Core ships an identical default, so this line is redundant at runtime —
- *     it is here so the customization point is VISIBLE in the generated code:
- *     a project restyling its header edits that file and nothing else.
- * @param {Answers} a
+ *  2. **The layer registry**, which gives core the active site/theme override
+ *     modules and templates while keeping this route a thin delegate.
  */
-function siteLayout(a) {
-  return `${renderStamp()}
-// The public site shell — header, footer, data-driven nav and the active site's
+function siteLayout() {
+  return stamped(`// The public site shell — header, footer, data-driven nav and the active site's
 // theme tokens, all resolved per request. It lives in @kywi-software/core/next;
-// this file wires in THIS app's runtime, brand and nav component, and imports
-// the stylesheets (Next takes a global stylesheet only from a file in app/, and
-// a package cannot import yours). Restyle via site.css, theme tokens
-// (kywi.config.ts) and components/site-nav.tsx — not by editing this file.
+// this file wires in THIS app's runtime and generated layer registry, and
+// imports the stylesheets (Next takes a global stylesheet only from a file in
+// app/, and a package cannot import yours). Restyle via site.css, theme tokens
+// (kywi.config.ts), sites/default/** and components/site-nav.tsx.
 import { createSiteLayout } from '@kywi-software/core/next'
 import '@kywi-software/core/site/styles.css'
 import './site.css'
 import { kywi } from '../../lib/kywi'
-import { SiteNav } from '../../components/site-nav'
+import { layers } from '../../kywi.layers'
 
-const layout = createSiteLayout({ runtime: kywi, brand: { label: '${escapeJsString(a.projectName)}' }, nav: SiteNav })
+const layout = createSiteLayout({ runtime: kywi, layers })
 
 export default layout.default
 // A LITERAL — same reason as the page route below it in the tree.
 export const dynamic = 'force-dynamic'
-`
+`)
 }
 
 /** @param {Answers} a — the app's OWN public-site chrome CSS (header/footer/page). */
@@ -834,23 +1181,22 @@ function siteStyles(a) {
  * literal `'force-dynamic'` so the two still cannot drift.
  */
 function siteSlugPage() {
-  return `${renderStamp()}
-// The public catch-all: "/" and every published page at its Site Tree path.
+  return stamped(`// The public catch-all: "/" and every published page at its Site Tree path.
 // Content resolution, SEO metadata, JSON-LD, personalization + A/B assignment
 // and the front-edit overlay all live in @kywi-software/core/next; this file
-// wires in THIS app's runtime and its custom module renderers (lib/modules.tsx).
+// wires in THIS app's runtime and generated layer registry.
 import { createPublicPage } from '@kywi-software/core/next'
 import { kywi } from '../../../lib/kywi'
-import { moduleComponents } from '../../../lib/modules'
+import { layers } from '../../../kywi.layers'
 
-const page = createPublicPage({ runtime: kywi, modules: moduleComponents })
+const page = createPublicPage({ runtime: kywi, layers })
 
 export default page.default
 export const generateMetadata = page.generateMetadata
 // A LITERAL, never \`page.dynamic\`: Next parses route segment config statically
 // and fails the build on a MemberExpression.
 export const dynamic = 'force-dynamic'
-`
+`)
 }
 
 /** @param {Answers} a — headless/decoupled root page (no public rendering). */
@@ -884,30 +1230,23 @@ export default function HomePage() {
  * /api/v1/[axPath] directly.
  */
 function axRootRoute(axPath) {
-  return `import { getKywiHandler } from '../../lib/kywi'
+  return stamped(`import { createAxRoute } from '@kywi-software/core/next'
+import { kywi } from '../../lib/kywi'
+
+const route = createAxRoute({ runtime: kywi, axPath: '${axPath}' })
 
 /** Root-level \`/${axPath}\` — delegates to the core AX generator (kywi-cms#55). */
-export const dynamic = 'force-dynamic'
+export const GET = route.GET
 
-export async function GET(req: Request): Promise<Response> {
-  const handler = await getKywiHandler()
-  return handler.handle(req, ['${axPath}'])
-}
-`
+export const dynamic = 'force-dynamic'
+`)
 }
 
 // ── API route (thin proxy over @kywi-software/core/host) ──────────────────────
 
 function apiRoute() {
-  return `import { NextRequest, NextResponse } from 'next/server'
-import { getKywiHandler } from '../../../../lib/kywi'
-import {
-  isTokenIssuingPath,
-  parseSessionTokens,
-  setAccessCookie,
-  setRefreshCookie,
-  clearSessionCookies,
-} from '@kywi-software/core/host'
+  return stamped(`import { createApiRoute } from '@kywi-software/core/next'
+import { kywi } from '../../../../lib/kywi'
 
 /**
  * The versioned Kywi API. Delegates every verb to core's DB-backed handler, with
@@ -917,126 +1256,52 @@ import {
  * refresh side lives in middleware.ts. The cookie contract is shared via
  * @kywi-software/core/host — core itself is untouched.
  */
-async function handleRequest(
-  req: NextRequest,
-  ctx: { params: Promise<{ kywi: string[] }> },
-): Promise<Response> {
-  const segments = (await ctx.params).kywi
-  const path = segments.join('/')
-  const handler = await getKywiHandler()
-  const res = await handler.handle(req, segments)
-
-  if (path === 'auth/logout') {
-    const bodyText = await res.text()
-    const out = new NextResponse(bodyText, { status: res.status, headers: res.headers })
-    clearSessionCookies(out)
-    return out
-  }
+const route = createApiRoute({ runtime: kywi })
 
-  if (isTokenIssuingPath(path) && res.ok) {
-    const bodyText = await res.text()
-    const { accessToken, refreshToken } = parseSessionTokens(bodyText)
-    const out = new NextResponse(bodyText, { status: res.status, headers: res.headers })
-    if (accessToken) setAccessCookie(out, accessToken)
-    if (refreshToken) setRefreshCookie(out, refreshToken)
-    return out
-  }
-
-  return res
-}
-
-export const GET = handleRequest
-export const POST = handleRequest
-export const PUT = handleRequest
-export const PATCH = handleRequest
-export const DELETE = handleRequest
+export const GET = route.GET
+export const POST = route.POST
+export const PUT = route.PUT
+export const PATCH = route.PATCH
+export const DELETE = route.DELETE
 
 export const dynamic = 'force-dynamic'
-`
+`)
 }
 
 // ── admin (the full core admin, mounted at /admin) ─────────────────────────────
 
 /**
- * The single optional-catch-all host page that mounts the ENTIRE core admin
- * (all surfaces) at /admin. Modeled on apps/reference — the whole scaffolded
- * admin is `KywiAdminApp`, upgraded via `npm update @kywi-software/core`, not
- * hand-written per-surface pages.
- */
-function adminCatchAllPage() {
-  return `/**
- * Host page for the core-mounted admin (\`KywiAdminApp\`).
+ * The admin host page — a thin delegate over `createAdminPage` (plan E3 T4).
  *
- * This ONE optional-catch-all serves your entire admin at /admin — dashboard,
- * site tree, media, users, forms, categories, tags, audiences, settings, and
- * every other surface. It is a server component: it projects the full,
- * server-side kywi.config.ts down to the secret-free AdminRuntimeConfig
- * (toAdminRuntimeConfig), extracts ?next= for the login surface, and renders the
- * one client KywiAdminApp, which maps the URL segments to a surface and mounts
- * it inside the core admin chrome.
- *
- * The @kywi-software/core/admin/styles.css import is LOAD-BEARING: the admin
- * design-system tokens/inputs live there, so without it every surface (and the
- * login page) renders unstyled. Do not remove it.
- *
- * Server-side 404 (#58): the segments are resolved with the three-state
- * resolveSurfaceState helper. Next's notFound() fires for a real HTTP 404 ONLY
- * on a genuinely unknown path (status 'not-found'). A KNOWN surface held off by
- * the config ceiling (status 'config-disabled') is NOT hard-404'd here — it
- * falls through to KywiAdminApp, which renders the same in-shell "disabled"
- * message a runtime-disabled surface gets, so both disable paths present
- * consistently instead of hard-404 vs soft-hide. The \`login\` segment is exempt
- * (not a registry surface — the middleware's auth exception renders it
- * chrome-less through KywiAdminApp); the bare /admin index (segments === [])
- * resolves to the dashboard, so it never 404s.
- *
- * You should not need to edit this file. To disable surfaces per deployment, set
- * \`admin.features\` in kywi.config.ts; superAdmins can also toggle surfaces at
- * runtime from the "Admin Features" surface.
+ * What used to be 70 emitted lines (the AdminRuntimeConfig projection, the
+ * `?next=` extraction and the three-state #58 404 gate) is
+ * `@kywi-software/core/next`. TWO things stay in the generated file, and only
+ * two: the admin stylesheet import (Next admits a global stylesheet only from a
+ * file inside `app/`, and a published package cannot import it on the app's
+ * behalf) and the `dynamic` LITERAL (Next parses route segment config
+ * statically, so `export const dynamic = page.dynamic` fails the build).
  */
-import { notFound } from 'next/navigation'
-import { KywiAdminApp } from '@kywi-software/core/admin/app'
-import { toAdminRuntimeConfig, resolveSurfaceState } from '@kywi-software/core/admin/server'
-// CRITICAL: load the admin design system once for the whole mount.
+function adminCatchAllPage() {
+  return stamped(`// Your entire admin at /admin — every surface. The surface resolution, the
+// secret-free config projection and the server-side 404 all live in
+// @kywi-software/core/next; this file wires in THIS app's runtime and generated
+// layer registry, and imports the admin stylesheet (Next takes a global
+// stylesheet only from a file in app/, and a package cannot import it for you) —
+// without it every surface, login included, renders unstyled. You should not
+// need to edit this file: to disable surfaces set \`admin.features\` in
+// kywi.config.ts, or toggle them at runtime from the Admin Features surface.
+import { createAdminPage } from '@kywi-software/core/next'
 import '@kywi-software/core/admin/styles.css'
-import kywiConfig from '../../../kywi.config'
-// Custom (defineModule) renderers, shared with the public layout so the Layout
-// editor canvas renders them the same as the live site (#48). Empty by default.
-import { moduleComponents } from '../../../lib/modules'
-
-export default async function AdminCatchAll({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ admin?: string[] }>
-  searchParams: Promise<Record<string, string | string[] | undefined>>
-}) {
-  const { admin = [] } = await params
-  const sp = await searchParams
-  const next = typeof sp.next === 'string' ? sp.next : null
-
-  const runtime = toAdminRuntimeConfig(kywiConfig)
-
-  // Real HTTP 404 only for a genuinely unknown admin path. A config-disabled
-  // surface is a known route held off by the ceiling — it renders the consistent
-  // in-shell "disabled" message via KywiAdminApp rather than a hard 404 (#58).
-  // The login segment is not a surface (chrome-less middleware exception); the
-  // bare index resolves to the dashboard, so both skip the 404 pre-check.
-  const isLogin = admin.length === 1 && admin[0] === 'login'
-  if (!isLogin && resolveSurfaceState(admin, runtime.admin).status === 'not-found') {
-    notFound()
-  }
+import { kywi } from '../../../lib/kywi'
+import { layers } from '../../../kywi.layers'
 
-  return (
-    <KywiAdminApp
-      runtime={runtime}
-      segments={admin}
-      loginNext={next}
-      moduleComponents={moduleComponents}
-    />
-  )
-}
-`
+const page = createAdminPage({ runtime: kywi, layers })
+
+export default page.default
+// A LITERAL, never \`page.dynamic\`: Next parses route segment config statically
+// and fails the build on a MemberExpression.
+export const dynamic = 'force-dynamic'
+`)
 }
 
 // ── custom module renderers (lib/modules.tsx) ─────────────────────────────────
@@ -1402,7 +1667,7 @@ export const GUIDANCE_VERSION = 1
  * @returns {string}
  */
 let _pkgVersion
-function packageVersion() {
+export function packageVersion() {
   if (_pkgVersion === undefined) {
     const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
     _pkgVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version
@@ -1731,6 +1996,12 @@ export function buildFileSet(answers) {
     'lib/kywi.ts': libKywi(),
     // custom (defineModule) module renderers, shared by admin + public layout (#48)
     'lib/modules.tsx': libModules(),
+    // Build-time enumerable site/theme registry for core's layer resolver
+    // (RENDER_LANDMARK_PATHS.layers).
+    'kywi.layers.ts': kywiLayers(),
+    // …and the layer files it names. A fresh scaffold is one site with one
+    // theme; `upgrade` regenerates BOTH from the project's own kywi.config.ts.
+    ...layerFilesFor(DEFAULT_REGISTRY_LAYOUT, answers.mode),
     // host wiring: a re-export of core's own middleware
     // (RENDER_LANDMARK_PATHS.middleware).
     'middleware.ts': middleware(),
@@ -1759,7 +2030,7 @@ export function buildFileSet(answers) {
     // `pnpm up @kywi-software/core` reaches it. Nothing here may grow a copy of
     // a core helper; `__tests__/render-drift.test.mjs` (verification E8) fails
     // the build if it does.
-    files['app/(site)/layout.tsx'] = siteLayout(answers)
+    files['app/(site)/layout.tsx'] = siteLayout()
     files['app/(site)/site.css'] = siteStyles(answers)
     // 'use client' wrapper around core's shared nav renderer — required because
     // BUILT_IN_MODULE_COMPONENTS is exported from a 'use client' core module, so