create-kywi-app 0.18.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'
@@ -44,12 +45,15 @@ const CORE_RANGE = (v) => `^${v}`
 
 /** @param {Answers} a */
 function packageJson(a) {
-  // Coupled mode's front-of-site editor (kywi-front-edit.tsx) needs the admin
-  // design system's stylesheet available at a plain, fetchable URL
-  // (/kywi-admin.css) — it is injected via a runtime <link> tag rather than a
-  // JS import (kywi-cms#130 follow-up: an import, even a dynamic one, still
-  // ships the stylesheet on every public route — see ensureAdminStylesheet in
-  // kywi-front-edit.tsx). Unlike public/kywi.js (opt-in, manually placed when
+  // Coupled mode's front-of-site editor (core's `KywiFrontEdit`, from
+  // @kywi-software/core/next/client) needs the admin design system's stylesheet
+  // available at a plain, fetchable URL (/kywi-admin.css) — it is injected via a
+  // runtime <link> tag rather than a JS import (kywi-cms#130 follow-up: an
+  // import, even a dynamic one, still ships the stylesheet on every public route
+  // — see `ensureAdminStylesheet` in core's front-edit.tsx). The SYNC stays
+  // project-owned even though the overlay is core's: core fetches
+  // /kywi-admin.css.version at runtime, and only the app can put a file in its
+  // own public/. Unlike public/kywi.js (opt-in, manually placed when
   // personalization.clientRuntime is enabled — see README), this is a CORE
   // feature every coupled-mode app has, so the sync is automatic.
   const syncScripts =
@@ -333,9 +337,11 @@ function tsconfig() {
  * Ambient declaration for stylesheet imports.
  *
  * WHY THIS FILE EXISTS (found by the scaffold compile gate, kywi-cms#147 T6;
- * history below). `app/(site)/kywi-front-edit.tsx` originally pulled the
- * admin design system in via `await import('@kywi-software/core/admin/
- * styles.css')` inside `next/dynamic`'s factory. TypeScript treats a
+ * history below). The front-edit overlay — then emitted as
+ * `app/(site)/kywi-front-edit.tsx`, since plan E1 core's own
+ * `@kywi-software/core/next/client` — originally pulled the admin design system
+ * in via `await import('@kywi-software/core/admin/styles.css')` inside
+ * `next/dynamic`'s factory. TypeScript treats a
  * *dynamic* import of a non-code file as an ordinary module import and
  * reports TS2307 for it, unlike a top-level `import 'x.css'` statement, which
  * it lets through as a resource import. Next type-checks during `next
@@ -344,11 +350,15 @@ function tsconfig() {
  * reference app imported that stylesheet in statement form and the
  * scaffold's own output had never been type-checked at all.
  *
+ * (The overlay moved into core in plan E1; the reasoning is kept here because
+ * this declaration is still what makes a stylesheet import type-check in a
+ * generated app.)
+ *
  * kywi-cms#130 follow-up: that dynamic import turned out to ship the
  * stylesheet to every public route regardless of the `next/dynamic`
  * wrapping (Next's App Router CSS collection bundles every css import it can
  * see in the reachable module graph, dynamic or not) — see
- * `ensureAdminStylesheet` in `frontEditOverlay()`, which replaced it with a
+ * `ensureAdminStylesheet` in core's `next/client/front-edit.tsx`, which replaced it with a
  * runtime `<link>` tag. This ambient declaration is no longer load-bearing
  * for that one case, but it costs nothing to keep as a general-purpose `*.css`
  * declaration for any future dynamic stylesheet import.
@@ -359,11 +369,12 @@ function tsconfig() {
 function cssTypes() {
   return `// Stylesheet imports. CSS Modules are typed by Next itself — the more
 // specific pattern wins. (History: originally required for a dynamic
-// \`await import('…/styles.css')\` in app/(site)/kywi-front-edit.tsx, which
-// TypeScript checks like any other module — see cssTypes' doc comment in
-// templates.mjs. That import was replaced by a runtime \`<link>\` tag,
-// kywi-cms#130 follow-up, so nothing in this generated app currently needs
-// this declaration — kept for any future dynamic stylesheet import.)
+// \`await import('…/styles.css')\` in the front-edit overlay, which TypeScript
+// checks like any other module — see cssTypes' doc comment in templates.mjs.
+// That import was replaced by a runtime \`<link>\` tag, kywi-cms#130 follow-up,
+// and the overlay itself now lives in @kywi-software/core/next, so nothing in
+// this generated app currently needs this declaration — kept for any future
+// dynamic stylesheet import.)
 declare module '*.css'
 `
 }
@@ -455,927 +466,505 @@ public/kywi-admin.css.version
 `
 }
 
-// ── server runtime (lib/kywi.ts) ──────────────────────────────────────────────
-
-function libKywi() {
-  return `import { cache } from 'react'
-import { headers } from 'next/headers'
-import {
-  createDb,
-  createKywiApiHandler,
-  createStorageProvider,
-  resolveDatabaseUrl,
-  resolveAuthSecret,
-} from '@kywi-software/core/server'
-import type { KywiApiHandler, KywiDb } from '@kywi-software/core/server'
-import { createKywiScope } from '@kywi-software/core/scope'
-import type { KywiScope } from '@kywi-software/core/scope'
-import { resolveActiveSite } from '@kywi-software/core/host'
-import config from '../kywi.config'
+// ── the generated render path: version stamp + landmarks ─────────────────────
 
 /**
- * Server-side Kywi singletons — config, DB, API handler and the DB-backed scope,
- * all sharing one connection pool. Memoised so it initialises once per process.
- */
-export interface KywiRuntime {
-  handler: KywiApiHandler
-  scope: KywiScope
-  db: KywiDb
-  /**
-   * DB UUID of the DEFAULT site (\`config.sites[0]\`), resolved once at init.
-   *
-   * This is a process-level fallback, NOT the site a request is for. Public
-   * render code must use \`getActiveSite()\` below, which resolves from the
-   * request's Host header — keying a public query on this instead is what makes
-   * a multi-site app serve the first site's content on every domain.
-   */
-  siteId: string
-  config: typeof config
-}
-
-let _runtime: KywiRuntime | null = null
-let _init: Promise<KywiRuntime> | null = null
-
-async function init(): Promise<KywiRuntime> {
-  const { url: dbUrl } = resolveDatabaseUrl(config.db.url)
-  const db = createDb(dbUrl, config.db.provider)
-  const authSecret = resolveAuthSecret(config.auth.secret)
-  const storage = createStorageProvider(config.media ?? { provider: 'local', localPath: './uploads' })
-  const handler = await createKywiApiHandler({ config, db, authSecret, storage })
-  const scope = createKywiScope(config, db, undefined, { mediaBaseUrl: '/api/v1' })
-
-  // Resolve the DB UUID for the DEFAULT configured site (its \`id\` is the slug).
-  // Per-request site resolution lives in \`getActiveSite()\`, not here.
-  const sites = await scope.site.list()
-  const match = sites.find((s) => (s as { slug?: string }).slug === config.sites[0]?.id) // DEFAULT-SITE FALLBACK: boot-time default, not a per-request resolution
-  const siteId = (match?.['id'] as string | undefined) ?? config.sites[0]?.id ?? 'default' // DEFAULT-SITE FALLBACK: boot-time default, not a per-request resolution
-
-  return { handler, scope, db, siteId, config }
-}
-
-export async function getKywi(): Promise<KywiRuntime> {
-  if (_runtime) return _runtime
-  if (!_init) _init = init().then((r) => (_runtime = r))
-  return _init
-}
-
-export async function getKywiHandler(): Promise<KywiApiHandler> {
-  return (await getKywi()).handler
-}
-
-// ─── Host → site resolution ─────────────────────────────────────────────────
-
-/** One configured site (config uses the slug as \`id\`). */
-export type SiteConfig = (typeof config.sites)[number]
-
-/** The site the current public request is for: config entry + its DB UUID. */
-export interface ActiveSite {
-  runtime: KywiRuntime
-  /** Resolved config site (matched by request Host, else the default site). */
-  site: SiteConfig
-  /** DB UUID of that site (what the scope/queries key on). */
-  siteId: string
-}
-
-// Config-slug → DB-UUID map, cached for the process. Sites are reconciled at
-// boot and static thereafter; a miss falls back to the slug.
-let _slugToUuid: Record<string, string> | null = null
-async function slugToUuid(runtime: KywiRuntime): Promise<Record<string, string>> {
-  if (_slugToUuid) return _slugToUuid
-  const rows = (await runtime.scope.site.list()) as Array<{ id?: string; slug?: string }>
-  const map: Record<string, string> = {}
-  for (const r of rows) if (r.slug && r.id) map[r.slug] = r.id
-  _slugToUuid = map
-  return map
-}
-
-/**
- * Which configured site is this request for? Resolved from the request's HOST
- * header, so \`docs.example.com\` serves the docs site and \`example.com\` serves
- * the marketing site from one app and one database.
+ * 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.
  *
- * Wrapped in React \`cache()\` so every helper on a single render shares one
- * lookup. The process-level singletons in \`getKywi()\` are unaffected — only the
- * per-request Host differs.
+ * **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.
  *
- * DO NOT read \`x-kywi-url\` here: in dev it carries the server's own bound origin
- * (localhost), which would defeat host-based routing entirely.
+ * 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` extends to these files.
  */
-export const getActiveSite = cache(async (): Promise<ActiveSite> => {
-  const runtime = await getKywi()
-  const host = (await headers()).get('host')
-  const map = await slugToUuid(runtime)
-  const { site, siteId } = resolveActiveSite(runtime.config.sites, map, host)
-  return { runtime, site, siteId }
-})
-`
-}
-
-function libConfig() {
-  return `/** Re-export the Kywi config for use throughout the app (single import path). */
-import config from '../kywi.config'
-export default config
-`
-}
-
-// ── public-render helpers (lib/site.ts) ───────────────────────────────────────
+export const RENDER_VERSION = 2
 
 /**
- * Server-side helpers for the coupled public site: path- and locale-aware content
- * resolution (#30, #51), the feed-hydration resolver (#28) and the component
- * resolver (#46) for the layout engine, plus small SEO/media utilities. Kept out
- * of the page so the route stays a thin render over these.
+ * 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
  */
-function libSite() {
-  return `import { headers, cookies } from 'next/headers'
-import type {
-  LayoutDocument,
-  FeedItemsResolver,
-  PersonalizationState,
-} from '@kywi-software/core/layout'
-import {
-  collectComponentRefs,
-  componentDetachSource,
-  resolveComponentPlacements,
-  applyPageVariant,
-  collectLayoutExperimentIds,
-} from '@kywi-software/core/layout'
-import { resolveContentByPath, normalizePath } from '@kywi-software/core/nav'
-import { getFeedBySlug, getComponentById, resolveLocaleFromRequest } from '@kywi-software/core'
-import {
-  evaluateActiveAudiences,
-  getSelfIdWidgetConfig,
-  listSelfIdFields,
-  COOKIE_NAMES,
-} from '@kywi-software/core/audiences'
-import { cookieAllowedByHeader } from '@kywi-software/core/audiences/consent'
-import type {
-  Audience,
-  VisitorSignals,
-  SelfIdField,
-  SelfIdWidgetConfig,
-  SelfIdTrigger,
-} from '@kywi-software/core/audiences/types'
-import { listRunningExperiments, resolveExperimentForContainer } from '@kywi-software/core/experiments'
-import { getActiveSite, type KywiRuntime, type SiteConfig } from './kywi'
-
-/** A resolved content node is a flat record of its columns (base + custom fields). */
-export type ContentNode = Record<string, unknown>
-
-// Absolute base for media/OG URLs. Set NEXT_PUBLIC_SITE_URL in production so
-// crawlers and structured data get absolute image URLs.
-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'
-
-/** Public URL for a media file served by the API handler, or null. */
-export function mediaUrl(id: unknown): string | null {
-  return typeof id === 'string' && id ? \`\${SITE_URL}/api/v1/media/\${id}/file\` : null
-}
-
-/** Absolute origin of the current request, for structured-data (JSON-LD) URLs. */
-export async function requestBaseUrl(): Promise<string> {
-  const h = await headers()
-  const host = h.get('host') ?? 'localhost'
-  const isLocal = host.startsWith('localhost') || host.startsWith('127.') || host.startsWith('0.0.0.0')
-  const proto = h.get('x-forwarded-proto') ?? (isLocal ? 'http' : 'https')
-  return \`\${proto}://\${host}\`
-}
-
-// ─── Locale routing (#51) ────────────────────────────────────────────────────
+export function hashRenderBody(body) {
+  return createHash('sha256').update(body, 'utf8').digest('hex').slice(0, 12)
+}
 
 /**
- * The active site's configured locales (the default is always included first).
- *
- * \`activeSite\` is the site the REQUEST resolved to (\`getActiveSite().site\`).
- * Omitting it falls back to the default site, which is right only for a
- * single-site app — a second site would otherwise be served site one's locales.
+ * 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 function siteLocales(
-  runtime: KywiRuntime,
-  activeSite?: SiteConfig,
-): { defaultLocale: string; locales: string[] } {
-  const site = activeSite ?? runtime.config.sites[0] // DEFAULT-SITE FALLBACK: Host matched no site
-  const defaultLocale = site?.defaultLocale ?? 'en'
-  const configured = site?.locales && site.locales.length > 0 ? site.locales : [defaultLocale]
-  const locales = configured.includes(defaultLocale) ? configured : [defaultLocale, ...configured]
-  return { defaultLocale, locales }
+export function renderStamp(body) {
+  return `// kywi-render v${RENDER_VERSION} (create-kywi-app ${packageVersion()}) sha256:${hashRenderBody(body)}`
 }
 
 /**
- * Split a URL slug path into its active locale and the remaining slug segments.
- * A leading segment matching a CONFIGURED locale is treated as a locale prefix
- * (\`/es/pricing\` → locale 'es', path ['pricing']); otherwise Accept-Language
- * selects a supported locale, else the site default applies (the whole path is
- * the slug). Locale prefixes are only honoured for locales in \`site.locales\`.
+ * A body plus its own stamp — what every render-path emitter returns.
+ * @param {string} body
+ * @returns {string}
  */
-export function resolveRequestLocale(
-  runtime: KywiRuntime,
-  slugSegments: string[],
-  acceptLanguage?: string | null,
-  activeSite?: SiteConfig,
-): { locale: string; slugPath: string[] } {
-  const { defaultLocale, locales } = siteLocales(runtime, activeSite)
-  const pathname = '/' + slugSegments.join('/')
-  const locale = resolveLocaleFromRequest(pathname, acceptLanguage ?? null, defaultLocale, locales)
-  const first = slugSegments[0]
-  const slugPath = first && locales.includes(first) ? slugSegments.slice(1) : slugSegments
-  return { locale, slugPath }
+export function stamped(body) {
+  return `${renderStamp(body)}\n${body}`
 }
 
 /**
- * hreflang alternates for a page across the site's configured locales, or
- * undefined for a single-locale site. Feeds Next's \`alternates.languages\`.
+ * 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 async function localeAlternates(
-  slugSegments: string[],
-): Promise<Record<string, string> | undefined> {
-  // Async because the alternates belong to the site THIS request is for: a
-  // two-locale docs site and a single-locale marketing site share this app, and
-  // reading the default site's locales here would emit the wrong hreflang set
-  // (or none) on the other host.
-  const { runtime, site } = await getActiveSite()
-  const { defaultLocale, locales } = siteLocales(runtime, site)
-  if (locales.length <= 1) return undefined
-  const { slugPath } = resolveRequestLocale(runtime, slugSegments, null, site)
-  const rel = slugPath.join('/')
-  const out: Record<string, string> = {}
-  for (const loc of locales) {
-    const base = loc === defaultLocale ? \`/\${rel}\` : \`/\${loc}/\${rel}\`
-    out[loc] = base.length > 1 ? base.replace(/\\/$/, '') : base
-  }
-  return out
+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) }
 }
 
-// ─── Content resolution (#30 full path + #51 locale) ─────────────────────────
-
 /**
- * Resolve a public content node from a URL slug path, honouring the Site Tree
- * hierarchy: the FULL materialized path is matched, so \`/a/b/<slug>\` serves only
- * the node actually at \`/a/b/<slug>\` — never a top-level \`<slug>\` (#30). The
- * locale (URL prefix › Accept-Language › default) is resolved first and preferred,
- * with a default-locale fallback (#51). Returns the node regardless of status;
- * the caller enforces \`status === 'published'\`.
+ * Parses a {@link renderStamp} back out of a file's text:
+ * `[, 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 async function resolvePublicContent(
-  slugSegments: string[],
-  opts?: { acceptLanguage?: string | null },
-): Promise<ContentNode | null> {
-  // Every query below is keyed on the site the REQUEST is for, not on the
-  // default site: this is the seam that decides whose \`/about\` a visitor gets.
-  const { runtime, site, siteId } = await getActiveSite()
-  const { scope, db } = runtime
-  const { defaultLocale } = siteLocales(runtime, site)
-  const { locale, slugPath } = resolveRequestLocale(runtime, slugSegments, opts?.acceptLanguage, site)
-
-  const bySlug = async (slug: string): Promise<ContentNode | null> => {
-    let node = await scope.content.getBySlug(slug, siteId, { locale })
-    if (!node && locale !== defaultLocale) {
-      node = await scope.content.getBySlug(slug, siteId, { locale: defaultLocale })
-    }
-    return (node as ContentNode | null) ?? null
-  }
+export const RENDER_STAMP_RE = /^\/\/ kywi-render v(\d+) \(create-kywi-app ([^)]+)\)(?: sha256:([0-9a-f]{12}))?$/m
 
-  // Home ("/"): the seeded root node (slug "home", path "/").
-  if (slugPath.length === 0) return bySlug('home')
+/** @typedef {'runtime'|'middleware'|'siteLayout'|'sitePage'|'layers'|'apiRoute'|'axLlms'|'axLlmsFull'|'axSitemap'|'axRobots'|'adminHost'} RenderLandmark */
 
-  // Structural resolution by the full path enforces the parent chain (#30) and
-  // picks the locale-correct row that shares that path (#51).
-  const fullPath = normalizePath('/' + slugPath.join('/'))
-  let structural = await resolveContentByPath(db, fullPath, siteId, { locale })
-  if (!structural && locale !== defaultLocale) {
-    structural = await resolveContentByPath(db, fullPath, siteId, { locale: defaultLocale })
-  }
-  if (structural) {
-    return (await scope.content.getById(structural.id)) as ContentNode | null
-  }
-
-  // Flat-slug fallback ONLY for a single-segment URL whose target has no parent
-  // chain (a top-level node whose \`path\` column was never materialized). A nested
-  // node is never reachable at a wrong prefix — that is the #30 fix.
-  if (slugPath.length === 1) {
-    const node = await bySlug(slugPath[0]!)
-    if (node && !node['parentId']) return node
-  }
-  return null
+/**
+ * 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',
 }
 
-// ─── Feed hydration (#28) ────────────────────────────────────────────────────
+/**
+ * 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',
+]
 
 /**
- * Build the {@link FeedItemsResolver} \`hydrateLayoutFeeds\` calls for each Feed
- * Display module: resolve the saved feed by slug, run its query (published-only,
- * per-module limit) through the feed engine, and pre-map each row's media id to a
- * URL so the (client) module can render images. Core owns the walk + item shape;
- * this owns the data access.
+ * 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, 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<RenderLandmark, boolean>}
  */
-export function buildFeedResolver(runtime: KywiRuntime, siteId: string): FeedItemsResolver {
-  const { scope, db } = runtime
-  return async (feedSlug, { limit }) => {
-    const feed = await getFeedBySlug(db, feedSlug, siteId)
-    if (!feed) return []
-    const result = await scope.feeds.query({
-      ...(feed.query as Record<string, unknown>),
-      siteId,
-      status: 'published',
-      limit,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    } as any)
-    return result.items.map((row) => ({
-      ...row,
-      image: mediaUrl(row['featuredImageId']) ?? undefined,
-    }))
+export function renderLandmarks(mode) {
+  const coupled = mode === 'coupled'
+  return {
+    runtime: true,
+    middleware: true,
+    siteLayout: coupled,
+    sitePage: coupled,
+    layers: true,
+    apiRoute: true,
+    axLlms: true,
+    axLlmsFull: true,
+    axSitemap: true,
+    axRobots: true,
+    adminHost: true,
   }
 }
 
-// ─── Linked components: server-side pre-resolution (#46, #69, #147) ──────────
-
-/** Fetch a set of component rows once and index them by id. */
-async function loadComponents(ids: string[], runtime: KywiRuntime, siteId: string) {
-  const { db } = runtime
-  const entries = await Promise.all(
-    ids.map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
-  )
-  return new Map(entries)
+/**
+ * Read the render-path stamps out of an EXISTING project. Mirrors {@link
+ * detectAgentsLandmarks} (presence on disk) and adds the parsed stamp, because
+ * a render file is REPLACEABLE where a guidance file is only skip-or-force: a
+ * file carrying a stamp is create-kywi-app's own output and safe to overwrite,
+ * 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, hash: string|null, intact: boolean|null }>}
+ */
+export function detectRenderLandmarks(projectDir) {
+  /** @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 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
 }
 
 /**
- * Resolve every linked component (\`componentId\`) the layout places, ON THE
- * SERVER, before the document reaches the renderer.
+ * 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.
  *
- * This is the ONLY way a Server Component can render linked components.
- * \`KywiLayout\` is a client component and its \`componentResolver\` /
- * \`sectionComponentResolver\` / \`variantContainerComponentResolver\` props are
- * FUNCTIONS: passing them from here throws "Functions cannot be passed directly
- * to Client Components" and the page 500s. Pre-resolution hands the renderer a
- * plain document instead — only data crosses the boundary — and produces exactly
- * the markup the resolvers were meant to produce, \`data-component-id\` included.
+ * 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.
  *
- * \`collectComponentRefs\` is the engine's own link walker, the same one the
- * instance index and detach-all use, so this never falls behind on where a link
- * may live. It also knows that a connected section's inline columns are fallback
- * copy rather than placements, so links buried in one are not fetched — they
- * only render when that section's own component has gone missing.
+ * 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.
  *
- * Definitions are read per request with no cache, so editing a component is live
- * on the next page view.
+ * 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 async function resolveLayoutComponents(
-  layout: LayoutDocument,
-  runtime: KywiRuntime,
-  siteId: string,
-): Promise<LayoutDocument> {
-  const refs = collectComponentRefs(layout)
-  if (refs.length === 0) return layout
-  const map = await loadComponents([...new Set(refs.map((ref) => ref.componentId))], runtime, siteId)
-  return resolveComponentPlacements(layout, (componentId) =>
-    componentDetachSource(map.get(componentId) ?? null),
-  )
+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' },
 }
 
-// ─── Personalization + experiments (#50) ─────────────────────────────────────
-
-/** Server-resolved personalization for one public request. */
-export interface PublicPersonalization {
-  /** Threaded into <KywiLayout personalization=…> for variantContainer nodes. */
-  personalization: PersonalizationState
-  /** Winning audience id (null = default / opted out / no match). */
-  audienceId: string | null
-  /** Stable visitor id (middleware cookie/header); keys A/B assignment. */
-  visitorId: string
-  /**
-   * True when \`visitorId\` is a durable identity this visitor consented to
-   * (kywi-cms#91). False means it was minted for this request alone — nothing
-   * may be written against it, including an A/B exposure.
-   */
-  tracked: boolean
-  /** Active audiences evaluated — handed to the client runtime for re-eval. */
-  audiences: Audience[]
-  /** Server-resolved signals — handed to the client runtime as serverSignals. */
-  signals: Partial<VisitorSignals>
-}
-
-/** Is the winning audience id one of the currently active audiences? */
-function isActiveAudience(id: string | null, audiences: Audience[]): boolean {
-  return id != null && audiences.some((a) => a.id === id)
-}
+// ── the wiring runtime (lib/kywi.ts) ──────────────────────────────────────────
 
 /**
- * Evaluate the site's active audiences for this request, exactly once, and pick
- * the visitor's A/B arms — the two server seams that make page variants,
- * variantContainers and experiments resolve per-visitor with NO client runtime
- * (kywi-cms#50). The request the audience engine reads (URL + cookies + referrer)
- * is reconstructed from next/headers, so this is safe from any (site) Server
- * Component. A \`kywi_preview_init=<audienceId>\` cookie (set by the admin preview
- * link) forces that audience, so an editor previews it without matching its live
- * conditions.
+ * The app's ONE config seam, and the only render-path file that exists in every
+ * mode. Before plan E1 this was 111 lines of connection-pool, singleton and
+ * Host→site-resolution code copied into every project; it is now four lines
+ * over `createKywiNextRuntime`, which core owns and `pnpm up` upgrades.
+ *
+ * It cannot collapse further: core cannot import an app's `kywi.config.ts`
+ * (there is no import path from a published package back into the app that
+ * installed it, and a config may pull in project plugins), so the app hands the
+ * config in — see `packages/core/src/next/runtime.ts`'s header.
  */
-export async function resolvePersonalization(
-  runtime: KywiRuntime,
-  layout: LayoutDocument | null | undefined,
-): Promise<PublicPersonalization> {
-  const [h, cookieStore] = await Promise.all([headers(), cookies()])
-  // Evaluate against the HOST-resolved site, so a visitor on site B is matched
-  // only against site B's audiences and gated by site B's theme flags.
-  const { site, siteId } = await getActiveSite()
-  // One resolution of \`theme.personalization.requireConsent\` for the whole
-  // request, handed to every gate below — the visitor-id read AND the audience
-  // engine's own collectors. They read the same cookies; disagreeing about
-  // whether consent is required would personalize half a page.
-  const gate = { requireConsent: requireConsentEnabled(runtime, site) }
-  // \`kywi_visitor\` is a \`personalization\` cookie, so without consent it is
-  // neither written nor read (kywi-cms#91) — the middleware hands this request a
-  // THROWAWAY id instead, freshly minted and different on the next request.
-  // \`tracked\` carries that fact to everything downstream that would otherwise
-  // write the id to the database.
-  const tracked = cookieAllowedByHeader(COOKIE_NAMES.VISITOR, h.get('cookie'), gate)
-  // The stored cookie is read THROUGH that gate too, not just written through
-  // it: a visitor who accepted last month and has since rejected still carries
-  // one, and honouring it would re-identify them under the identity they
-  // revoked. The header bridge is unaffected — the middleware already applied
-  // the same rule when it minted the id this request carries.
-  const visitorId =
-    h.get('x-kywi-visitor') ??
-    (tracked ? cookieStore.get(COOKIE_NAMES.VISITOR)?.value : undefined) ??
-    'vis-anon'
-  const host = h.get('host') ?? 'localhost'
-  const url = h.get('x-kywi-url') ?? \`http://\${host}/\`
-
-  const reqHeaders = new Headers()
-  h.forEach((value, key) => reqHeaders.set(key, value))
-  const request = new Request(url, { headers: reqHeaders })
-
-  const { db } = runtime
-  // \`gate\` reaches the engine's server collectors, so a site whose consent is
-  // owned by an external CMP (\`requireConsent: false\`) has its stored UTM /
-  // visitor / known / pinned-audience cookies read here too, not just by the
-  // middleware and the runtime routes.
-  const { result, audiences } = await evaluateActiveAudiences(db, siteId, request, gate)
-
-  const previewId = cookieStore.get(COOKIE_NAMES.PREVIEW_INIT)?.value || null
-  const audienceId = isActiveAudience(previewId, audiences) ? previewId : result.winningAudienceId
-
-  const experimentAssignments = await resolveExperimentAssignments(
-    runtime,
-    siteId,
-    layout,
-    audienceId,
-    visitorId,
-    tracked,
-  )
+function libKywi() {
+  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.
+import { createKywiNextRuntime } from '@kywi-software/core/next'
+import config from '../kywi.config'
 
-  return {
-    personalization: { resolvedAudienceId: audienceId, experimentAssignments },
-    audienceId,
-    visitorId,
-    tracked,
-    audiences,
-    signals: result.signals,
-  }
-}
+export const kywi = createKywiNextRuntime(config)
 
-/**
- * Deterministically assign this visitor to a variant of every running A/B
- * experiment the (audience-resolved) layout actually shows, and record the
- * exposure. Stable on visitorId → the visitor keeps the same arm across requests;
- * the write is idempotent on (experiment, visitor). Returns experimentId →
- * chosen variant key for <KywiLayout personalization.experimentAssignments>.
- *
- * \`tracked\` is the consent gate (kywi-cms#91): false means \`visitorId\` is a
- * throwaway the middleware minted for this request alone, and the idempotent
- * write stops being idempotent — every anonymous page view would insert another
- * assignment row. The ARM IS STILL CHOSEN, so the page renders exactly as it
- * does for anyone else; only the counting stops.
- *
- * Experiment ids come from \`collectLayoutExperimentIds\` — the engine's own
- * walker, the same one \`<KywiLayout>\` and the reference app use. It descends
- * into every section's columns as well as the top-level regions, so a
- * module-level \`moduleVariantContainer\` (an ab_test placed inside a section,
- * not a bare section-level band) is bucketed exactly like one — a hand-rolled
- * walker here previously stopped at the top level and silently never assigned
- * those (kywi-cms#221).
- */
-async function resolveExperimentAssignments(
-  runtime: KywiRuntime,
-  siteId: string,
-  layout: LayoutDocument | null | undefined,
-  audienceId: string | null,
-  visitorId: string,
-  tracked: boolean,
-): Promise<Record<string, string | null>> {
-  if (!layout) return {}
-  // Pre-resolve FIRST, then read the containers. A container component saved
-  // with \`mode: 'ab_test'\` keeps its experiment in the DEFINITION; a placement
-  // that carries only a \`componentId\` would otherwise look like a plain
-  // container to this pass, no assignment would be made, and every visitor would
-  // see the Default arm of a live experiment. After pre-resolution there are no
-  // unresolved placements left to special-case — the containers here are the
-  // containers that render.
-  const resolved = await resolveLayoutComponents(applyPageVariant(layout, audienceId), runtime, siteId)
-  const experimentIds = collectLayoutExperimentIds(resolved)
-  if (experimentIds.length === 0) return {}
-
-  const running = await listRunningExperiments(runtime.db, siteId)
-  const byId = new Map(running.map((e) => [e.id, e]))
-  const assignments: Record<string, string | null> = {}
-  for (const id of experimentIds) {
-    const exp = byId.get(id)
-    if (!exp) continue
-    const res = await resolveExperimentForContainer(runtime.db, exp, visitorId, { recordExposure: tracked })
-    assignments[id] = res.variantKey
-  }
-  return assignments
+// 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) ─────────────────────────────────
+
 /**
- * Return the audience-resolved layout: page variants (audience → whole-page
- * region override) applied, and \`pageVariants\`/\`abExperiments\` stripped so no
- * other audience's content is serialized to this visitor.
+ * The auth gate, transparent session refresh, cookie→bearer bridge, visitor /
+ * UTM / entry-page cookies and `.md` content negotiation were 242 lines of
+ * emitted code; they are now `@kywi-software/core/next/middleware`.
  *
- * This is only the PAGE-level half. Container-level arms (variantContainer /
- * moduleVariantContainer) are stripped by \`pruneLayoutToServedArms\` as the last
- * pass before \`<KywiLayout>\` — see the public page (#167). Run both, or the
- * losing arms are still readable in the page's RSC flight payload.
+ * It has its OWN core entry rather than living on the `/next` barrel because
+ * Next compiles this file for the EDGE runtime: the barrel reaches the
+ * database, sharp and the AWS SDK, and re-exporting the middleware from it
+ * would drag all of that into the edge bundle. Same precedent as core's
+ * `./host` split (see that file's header in core).
  */
-export function personalizeLayout(
-  layout: LayoutDocument,
-  audienceId: string | null,
-): LayoutDocument {
-  return applyPageVariant(layout, audienceId)
+function middleware() {
+  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'
+`)
 }
 
-/** Is the @kywi-software/js client runtime enabled for the ACTIVE site's theme? */
-export function clientRuntimeEnabled(runtime: KywiRuntime, activeSite?: SiteConfig): boolean {
-  const themeName = (activeSite ?? runtime.config.sites[0])?.theme // DEFAULT-SITE FALLBACK: Host matched no site
-  const theme = runtime.config.themes.find((t) => t.name === themeName) ?? runtime.config.themes[0]
-  return theme?.personalization?.clientRuntime === true
-}
+// ── kywi.layers.ts + the sites/ layer files ──────────────────────────────────
 
 /**
- * Is the global transparency surface (the automatic pill/panel showing which
- * audience the page was personalized for, with a switcher and opt-out) enabled
- * for this site's theme? \`personalization.transparencyNotice.enabled\` — unset
- * defaults to true; only an explicit \`false\` suppresses the surface from
- * appearing on its own. Even then a \`personalizationBadge\` module can still
- * open it deliberately.
+ * 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
  */
-export function transparencyNoticeEnabled(runtime: KywiRuntime, activeSite?: SiteConfig): boolean {
-  const themeName = (activeSite ?? runtime.config.sites[0])?.theme // DEFAULT-SITE FALLBACK: Host matched no site
-  const theme = runtime.config.themes.find((t) => t.name === themeName) ?? runtime.config.themes[0]
-  return theme?.personalization?.transparencyNotice?.enabled !== false
-}
 
 /**
- * Must a visitor consent before this site writes a \`personalization\` cookie
- * (\`kywi_visitor\`, \`kywi_signals\`, \`kywi_utm\`, \`kywi_audience\`)?
- * \`personalization.requireConsent\` — unset defaults to TRUE; only an explicit
- * \`false\` turns Kywi's consent gate off, for a site that collects consent with
- * external tooling (kywi-cms#91).
- *
- * \`middleware.ts\` runs on the edge and cannot read this config, so it mirrors
- * the same flag with \`KYWI_REQUIRE_CONSENT=false\`. Set both, or neither.
- *
- * The flag is resolved from the ACTIVE site's theme, but as of core 0.17.0 every
- * configured site in one deployment must agree on it: the edge mirror is a
- * single process-wide env var and cannot carry two answers, so
- * \`createKywiApiHandler\` FAILS STARTUP on a divergence rather than letting a
- * second site silently inherit the first site's privacy default. A per-host
- * mirror map would lift that constraint and is deferred
- * (\`docs-site DESIGN.md §3.4\`).
+ * What a fresh scaffold emits: one site, one theme, both named `default`.
+ * @type {RegistryLayout}
  */
-export function requireConsentEnabled(runtime: KywiRuntime, activeSite?: SiteConfig): boolean {
-  const themeName = (activeSite ?? runtime.config.sites[0])?.theme // DEFAULT-SITE FALLBACK: Host matched no site
-  const theme = runtime.config.themes.find((t) => t.name === themeName) ?? runtime.config.themes[0]
-  return theme?.personalization?.requireConsent !== false
-}
-
-// ─── Self-ID widget (#50) ────────────────────────────────────────────────────
-
-/** The self-ID widget config in the serializable shape the client runtime reads. */
-export interface PublicSelfIdWidget {
-  fields: Array<{
-    id: string
-    label: string
-    type: 'select'
-    options?: Array<{ value: string; label: string }>
-    required?: boolean
-  }>
-  headline: string
-  subheadline?: string
-  submitLabel: string
-  skipLabel?: string
-  displayMode: 'modal' | 'inline' | 'slide-in' | 'hello_bar_top' | 'hello_bar_bottom' | 'drawer'
-  frequency: 'once' | 'session' | 'always'
-  trigger: SelfIdTrigger
-}
-
-// The admin's five display modes (SelfIdWidgetConfig['displayMode']) and the
-// client runtime's (PublicSelfIdWidget['displayMode'], @kywi-software/js) are the
-// same set — the runtime implements hello_bar_top/hello_bar_bottom/drawer as
-// their own layouts, not folded into slide-in (kywi-cms#97) — so this is a
-// passthrough. Kept as a named function (rather than assigning displayMode
-// directly) so the two types stay checked against each other at compile time.
-function mapDisplayMode(mode: SelfIdWidgetConfig['displayMode']): PublicSelfIdWidget['displayMode'] {
-  return mode
-}
-
-function mapFrequency(freq: SelfIdWidgetConfig['frequency']): PublicSelfIdWidget['frequency'] {
-  if (freq === 'once_visitor') return 'once'
-  if (freq === 'once_session') return 'session'
-  return 'always'
+export const DEFAULT_REGISTRY_LAYOUT = {
+  sites: [{ id: 'default', theme: 'default' }],
+  themes: [{ name: 'default' }],
 }
 
 /**
- * Resolve the site's stored self-ID widget config into the runtime shape, its
- * picklist fields hydrated. Returns null when there is no config or it references
- * no resolvable fields, so the caller can skip mounting the widget entirely.
+ * 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 async function resolveSelfIdWidget(
-  runtime: KywiRuntime,
-  siteId: string,
-): Promise<PublicSelfIdWidget | null> {
-  const [widget, allFields] = await Promise.all([
-    getSelfIdWidgetConfig(runtime.db, siteId),
-    listSelfIdFields(runtime.db, siteId),
-  ])
-  if (!widget) return null
-
-  const byId = new Map<string, SelfIdField>(allFields.map((f) => [f.id, f]))
-  const fields = widget.fieldIds
-    .map((id) => byId.get(id))
-    .filter((f): f is SelfIdField => f != null)
-    .map((f) => ({
-      id: f.id,
-      label: f.label,
-      type: 'select' as const,
-      // {value, label} pairs, not bare values — the client runtime renders the
-      // label and submits the value (kywi-cms#96); dropping the label here is
-      // what made every option render as its raw value.
-      options: f.picklist,
-      required: f.required,
-    }))
-  if (fields.length === 0) return null
-
+export function registryLayout(scan) {
   return {
-    fields,
-    headline: widget.headline,
-    ...(widget.subheadline ? { subheadline: widget.subheadline } : {}),
-    submitLabel: widget.submitLabel,
-    ...(widget.skipLabel ? { skipLabel: widget.skipLabel } : {}),
-    displayMode: mapDisplayMode(widget.displayMode),
-    frequency: mapFrequency(widget.frequency),
-    trigger: widget.trigger,
+    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, "\\'")}'`
 }
 
-// ── middleware.ts (thin framework wiring over @kywi-software/core/host) ───────
+/** `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('')
+  )
+}
 
-function middleware() {
-  return `import { NextResponse, type NextRequest } from 'next/server'
-import {
-  ACCESS_COOKIE,
-  REFRESH_COOKIE,
-  assertProductionAuthSecret,
-  classifyAccessToken,
-  setAccessCookie,
-  clearSessionCookies,
-} from '@kywi-software/core/host'
-// Edge-safe leaf helper: builds the kywi_utm cookie value core's collectUtm reads
-// back. Its own dependency-free entry (never the DB-backed audiences barrel), so
-// it is importable from this edge middleware.
-import { UTM_COOKIE, utmCookieValue } from '@kywi-software/core/audiences/utm-persistence'
-// Same kind of edge-safe leaf: the kywi_entry writer, whose value core reads
-// back as \`session.entryPage\` (kywi-cms#196).
-import { ENTRY_COOKIE, entryPageCookieValue } from '@kywi-software/core/audiences/entry-page'
-// Same kind of edge-safe leaf entry: the cookie-consent category map + gate. The
-// visitor's decision (written by the \`cookieConsent\` layout module) decides
-// whether the personalization cookies below may be persisted at all.
-import { cookieAllowedByHeader } from '@kywi-software/core/audiences/consent'
+/** 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
+}
 
 /**
- * The edge mirror of \`theme.personalization.requireConsent\` (kywi-cms#91).
- * Middleware runs on the edge and must not import \`kywi.config.ts\` (a config is
- * free to pull in plugins and DB-backed code that cannot run there), so the one
- * flag that lives in config is mirrored here as an env var.
- * \`KYWI_REQUIRE_CONSENT=false\` turns the gate off for the two cookies this file
- * writes. Set it together with the theme flag, never one alone —
- * createKywiApiHandler THROWS at startup when the two disagree, so a mismatch
- * fails the deploy instead of silently making the middleware and the API
- * disagree about whether a visitor is tracked.
+ * 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.
  */
-const REQUIRE_CONSENT = process.env.KYWI_REQUIRE_CONSENT !== 'false'
+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) })),
+    }
+  })
+}
 
 /**
- * Server-side auth enforcement + transparent session refresh for /admin and the
- * versioned API. The security-critical logic (JWT verify, cookie contract) lives
- * in @kywi-software/core/host; this file is only the Next.js wiring:
- *
- *   1. Refresh a stale access cookie from the 7-day refresh cookie, so an admin
- *      is never bounced to /admin/login mid-session.
- *   2. Bridge the httpOnly access cookie onto \`Authorization: Bearer\` for
- *      /api/v1/* — core reads credentials only from that header, and the browser
- *      cannot attach it (the token is httpOnly).
- *   3. Gate /admin/* (except /admin/login): no usable session → redirect to login.
- *
- * Must resolve the SAME secret handed to createKywiApiHandler (config.auth.secret
- * === process.env.AUTH_SECRET ?? default), or it would reject tokens the API accepts.
+ * `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')
+  })
 
-// Refuse to run in production with a missing or dev-fallback AUTH_SECRET — this
-// middleware verifies session JWTs, so a publicly-known default would make them
-// forgeable. Runs at module load (edge bundle init), so a bad prod deploy fails
-// loudly instead of silently accepting forged tokens. No-op in development.
-assertProductionAuthSecret(process.env.AUTH_SECRET)
-
-const AUTH_SECRET = process.env.AUTH_SECRET ?? 'dev-secret-change-in-production'
+  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')}
 
-// Token/session endpoints are pass-through: never guarded, refreshed, or bridged
-// (they establish a session rather than require one; the refresh call below is
-// itself a POST to /auth/refresh and must not recurse).
-function isAuthEndpoint(pathname: string): boolean {
-  return pathname.startsWith('/api/v1/auth/') &&
-    !pathname.startsWith('/api/v1/auth/oauth-clients') &&
-    !pathname.startsWith('/api/v1/auth/api-keys')
+export const layers = {
+${body.join('\n')}
+} satisfies KywiLayerRegistry
+`)
 }
 
-// Anonymous visitor identity for personalization/experiments. A/B assignment is
-// deterministic on this id, so persisting it (2y cookie) is what gives a visitor
-// a STABLE experiment arm across requests without any client runtime (#50). Name
-// matches @kywi-software/core/audiences COOKIE_NAMES.VISITOR; kept as a literal
-// here so the edge middleware never imports the (server-only) audiences module.
-const VISITOR_COOKIE = 'kywi_visitor'
-const VISITOR_MAX_AGE = 60 * 60 * 24 * 365 * 2 // 2 years
-
 /**
- * Public (non-admin, non-API) request: never auth-gated. Ensure a stable
- * \`kywi_visitor\` id — mint one on first visit — and forward it to the render as
- * \`x-kywi-visitor\` so the page sees it on this very request (the freshly set
- * cookie is not yet readable via cookies()). Also forward the full request URL
- * as \`x-kywi-url\` (query string included) so the server render can read UTM
- * params off the very first request — without it, campaign personalization
- * would never fire on the landing page. Everything else passes through.
+ * `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 handlePublicRequest(req: NextRequest): NextResponse {
-  // Both cookies below are \`personalization\` cookies in core's consent map, so
-  // neither is written OR READ until the visitor accepts. The header bridge is
-  // unaffected — this request still gets a visitor id and still personalizes off
-  // its own URL — so a site with no consent banner still renders, it just serves
-  // default content instead of tracking anyone. Place the \`cookieConsent\`
-  // module to let visitors turn personalization on.
-  const cookieHeader = req.headers.get('cookie')
-  const gate = { requireConsent: REQUIRE_CONSENT }
-  const mayPersonalize = cookieAllowedByHeader(VISITOR_COOKIE, cookieHeader, gate)
-  // Without consent the stored id is IGNORED, not just left un-refreshed: a
-  // visitor who accepted last month and rejected today still carries the cookie,
-  // and reading it would keep them tracked under the identity they just revoked.
-  const existing = mayPersonalize ? req.cookies.get(VISITOR_COOKIE)?.value : undefined
-  const visitorId = existing ?? crypto.randomUUID()
-  const headers = new Headers(req.headers)
-  headers.set('x-kywi-visitor', visitorId)
-  headers.set('x-kywi-url', req.nextUrl.href)
-  const res = NextResponse.next({ request: { headers } })
-  if (!existing && mayPersonalize) {
-    res.cookies.set(VISITOR_COOKIE, visitorId, { path: '/', maxAge: VISITOR_MAX_AGE, sameSite: 'lax' })
-  }
-  // Persist campaign UTM params so audience matching survives internal
-  // navigation: core's collectUtm reads this cookie when the URL has no utm_*
-  // query string. Only written when the request carries utm_* params, so an
-  // ordinary page view never clobbers a persisted campaign (utmCookieValue
-  // returns null → the existing cookie is left in place) — and only once the
-  // visitor has consented, which utmCookieValue reads off the header we pass.
-  const utmValue = utmCookieValue(req.nextUrl.href, { cookieHeader, ...gate })
-  if (utmValue) {
-    res.cookies.set(UTM_COOKIE, utmValue, { path: '/', maxAge: 60 * 60 * 24 * 30, sameSite: 'lax' })
-  }
-  // Record the session's ENTRY page (path + query) so rules on
-  // \`session.entryPage\` keep matching once the visitor navigates on
-  // (kywi-cms#196). Written once, consent-gated like the two above, and with no
-  // maxAge — a new visit is a new entry page. The landing request needs no
-  // cookie: core falls back to the request's own path, so \`?from=marketer\`
-  // personalizes the page it links to on that very request.
-  // Sec-Fetch-Dest / Accept are passed so ONLY a document request can name the
-  // entry page: a subresource that happens to be the session's first request
-  // (\`/kywi.js\`, a font, a route handler) would otherwise record itself as the
-  // page the visitor arrived on, and every entry-page rule would match an asset.
-  const entryValue = entryPageCookieValue(req.nextUrl.href, {
-    cookieHeader,
-    secFetchDest: req.headers.get('sec-fetch-dest'),
-    accept: req.headers.get('accept'),
-    ...gate,
-  })
-  if (entryValue) {
-    res.cookies.set(ENTRY_COOKIE, entryValue, { path: '/', sameSite: 'lax' })
-  }
-  return res
-}
-
-async function fetchFreshAccessToken(origin: string, refreshToken: string): Promise<string | undefined> {
-  try {
-    const res = await fetch(origin + '/api/v1/auth/refresh', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ refreshToken }),
-    })
-    if (!res.ok) return undefined
-    const body = (await res.json().catch(() => null)) as { data?: { accessToken?: unknown } } | null
-    const token = body?.data?.accessToken
-    return typeof token === 'string' && token.length > 0 ? token : undefined
-  } catch {
-    return undefined
-  }
+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'
+`
 }
 
-// Markdown content negotiation by URL suffix. Core serves markdown at
-// \`/api/v1/ax/md/slug/<slug>\` and the AX layer enables it (ax.markdown), but the
-// scaffold never wires the friendly \`/<path>.md\` URL the AX pitch (and the
-// developer copy) names — so it 404s despite the feature being on. Rewrite any
-// GET/HEAD for \`/<path>.md\` onto the core route so the named URL actually
-// resolves. Nested paths keep their full slug (e.g. /docs/foo.md -> docs/foo).
-// Never intercepts Next internals or the API — those never carry this suffix,
-// but are excluded explicitly since the matcher's own exclusion is broad.
-function handleMarkdownNegotiation(req: NextRequest): NextResponse | null {
-  const { pathname } = req.nextUrl
-  if (req.method !== 'GET' && req.method !== 'HEAD') return null
-  if (!pathname.endsWith('.md')) return null
-  if (pathname.startsWith('/api/') || pathname.startsWith('/_next/')) return null
-  const slug = pathname.replace(/^\\//, '').replace(/\\.md$/, '')
-  if (!slug) return null
-  const url = req.nextUrl.clone()
-  url.pathname = '/api/v1/ax/md/slug/' + slug
-  return NextResponse.rewrite(url)
-}
-
-export async function middleware(req: NextRequest): Promise<NextResponse> {
-  const { pathname } = req.nextUrl
-  if (isAuthEndpoint(pathname)) return NextResponse.next()
-
-  const md = handleMarkdownNegotiation(req)
-  if (md) return md
-
-  // Public pages are never auth-gated — just give them a stable visitor id.
-  const isAdmin = pathname === '/admin' || pathname.startsWith('/admin/')
-  const isApi = pathname.startsWith('/api/v1/')
-  if (!isAdmin && !isApi) return handlePublicRequest(req)
-
-  const accessToken = req.cookies.get(ACCESS_COOKIE)?.value
-  const refreshToken = req.cookies.get(REFRESH_COOKIE)?.value
-  const status = await classifyAccessToken(accessToken, AUTH_SECRET)
-
-  let freshAccess: string | undefined
-  if (status !== 'valid' && refreshToken) {
-    freshAccess = await fetchFreshAccessToken(req.nextUrl.origin, refreshToken)
-  }
-  const usableToken = status === 'valid' ? accessToken : freshAccess
-
-  // /api/v1/*: bridge cookie → Authorization header.
-  if (pathname.startsWith('/api/v1/')) {
-    if (usableToken && !req.headers.get('authorization')) {
-      const headers = new Headers(req.headers)
-      headers.set('authorization', 'Bearer ' + usableToken)
-      const res = NextResponse.next({ request: { headers } })
-      if (freshAccess) setAccessCookie(res, freshAccess)
-      return res
-    }
-    const res = NextResponse.next()
-    if (status !== 'valid' && refreshToken && !freshAccess) clearSessionCookies(res)
-    return res
-  }
+/**
+ * `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'
 
-  // /admin/*: server-side gate. Login must stay reachable while anonymous.
-  if (pathname === '/admin/login') return NextResponse.next()
-  if (status === 'valid') return NextResponse.next()
-  if (freshAccess) {
-    const res = NextResponse.next()
-    setAccessCookie(res, freshAccess)
-    return res
+export const templates = {} satisfies NonNullable<KywiLayerModule['templates']>
+`
   }
+  return `import { SiteNav } from '../../../../components/site-nav'
+import type { KywiLayerModule } from '@kywi-software/core/next'
 
-  const loginUrl = req.nextUrl.clone()
-  loginUrl.pathname = '/admin/login'
-  loginUrl.search = ''
-  loginUrl.searchParams.set('next', pathname + req.nextUrl.search)
-  const res = NextResponse.redirect(loginUrl)
-  clearSessionCookies(res)
-  return res
-}
-
-export const config = {
-  matcher: [
-    '/admin/:path*',
-    '/api/v1/:path*',
-    // Public pages, for the visitor-id cookie above. Excludes Next internals and
-    // any path with a file extension (static assets, /favicon.ico, /kywi.js, and
-    // the AX files /robots.txt, /sitemap.xml, /llms*.txt).
-    '/((?!_next/|.*\\\\..*).*)',
-    // \`/<path>.md\` — the markdown-negotiation URL. The extension-excluding
-    // pattern above skips it, so it needs its own entry to reach
-    // handleMarkdownNegotiation.
-    '/((?!_next/|api/).*\\\\.md)',
-  ],
-}
+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() {
@@ -1442,114 +1031,36 @@ export function SiteNav({ items, variant, ariaLabel, depth }: SiteNavProps) {
 `
 }
 
-/** @param {Answers} a — coupled public site shell. */
-function siteLayout(a) {
-  return `import React from 'react'
-import { headers } from 'next/headers'
-import { themeTokenStyleBlock } from '@kywi-software/core/layout'
-import { navTreeToMenuItems, normalizePath } from '@kywi-software/core/nav'
-// Neutral, token-driven defaults for everything Kywi renders (prose, the layout
-// grid + modules, forms, the edit overlay). Restyle via theme tokens, not by
-// editing this — see README → "Theming".
-import '@kywi-software/core/site/styles.css'
-// This app's OWN chrome (header / footer / page wrapper). Yours to edit freely.
-import './site.css'
-import { getActiveSite } from '../../lib/kywi'
-import { SiteNav } from '../../components/site-nav'
-import { KywiJsLoader } from '../../components/kywi-js-loader'
-
 /**
- * Public site shell. Header + footer carry this project's brand; edit them (and
- * site.css) freely — this is your app's own layer over the DB-backed content
- * that ${'app/(site)/[[...slug]]'} renders.
- *
- * The header/footer nav is DATA-DRIVEN, never hand-typed: it renders the
- * owner-managed \`'main'\` menu (Admin → Menus) when one exists, falling back to
- * the published Site Tree (\`isNav\` pages) so a fresh site has working nav out
- * of the box — and the footer renders a \`'footer'\` menu when one exists. NEVER
- * hardcode this list: a menu item's href resolves from its linked page and
- * can never drift the way a pasted URL can (see AGENTS.md → Navigation).
- * Rendered through core's shared nav renderer via the generated
- * \`components/site-nav.tsx\` (a \`'use client'\` wrapper — see that file for why)
- * rather than bespoke markup, so it gets the same CSS and \`@kywi-software/js\`
- * enhancement as a \`navigation\` module placed in the page body.
+ * The public site shell — a thin delegate over `createSiteLayout`.
  *
- * The active site's theme tokens (kywi.config.ts → themes[].tokens) are flattened
- * into a \`:root { --kywi-* }\` block by \`themeTokenStyleBlock\` and injected below,
- * so kywi.config.ts is the single source of truth for the palette and spacing and
- * both site.css and core's default styles resolve against those variables.
+ * Three things stay in the generated file, and only three:
  *
- * Everything it renders — the menus, the nav-tree fallback and the theme block —
- * is keyed on the site the REQUEST resolved to, so one app serves each of its
- * configured domains its own nav and its own palette.
+ *  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 layer registry**, which gives core the active site/theme override
+ *     modules and templates while keeping this route a thin delegate.
  */
+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 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 { layers } from '../../kywi.layers'
 
-// Content edits (a renamed page, a reordered menu) must show up without a
-// restart — same reasoning as the page route.
-export const dynamic = 'force-dynamic'
-
-export default async function SiteLayout({ children }: { children: React.ReactNode }) {
-  // The site this request is FOR (resolved from its Host header), never the
-  // default site: the menus, the nav tree and the theme below are all keyed on
-  // it, so a second domain gets its own nav and its own palette.
-  const { runtime, site, siteId } = await getActiveSite()
-  const { scope } = runtime
-
-  // Resolved PER REQUEST, not at module scope: a module-scope constant is
-  // evaluated once at import, so every host would emit the first site's tokens
-  // and a second site could not be themed at all.
-  const siteTheme =
-    runtime.config.themes.find((t) => t.name === site.theme) ?? runtime.config.themes[0]
-  const themeVars = themeTokenStyleBlock(siteTheme?.tokens)
-
-  // The middleware forwards the full request URL as \`x-kywi-url\` (see
-  // middleware.ts) so this shared layout can resolve which page is current —
-  // without it, isActive/isAncestor on nav items would have nothing to match.
-  const h = await headers()
-  const url = h.get('x-kywi-url')
-  const currentPath = normalizePath(url ? new URL(url).pathname : '/')
-
-  const mainMenu = await scope.menus.getResolved(siteId, 'main', currentPath)
-  const headerItems = mainMenu ?? navTreeToMenuItems(await scope.nav.getTree(siteId, currentPath))
-  const footerItems = await scope.menus.getResolved(siteId, 'footer', currentPath)
+const layout = createSiteLayout({ runtime: kywi, layers })
 
-  return (
-    <div className="site-shell">
-      {themeVars ? <style dangerouslySetInnerHTML={{ __html: themeVars }} /> : null}
-      {/* /kywi.js for the nav's hover-intent/keyboard/viewport-flip enhancement
-          (kywi-cms#114) — independent of personalization, gated on the exact
-          same condition <SiteNav> renders on below (a non-empty header menu),
-          so it loads whenever a \`[data-kywi-nav]\` root actually exists. Shares
-          its dedup with <PersonalizationRuntime> (lib/kywi-js-loader.ts), so a
-          page with both nav AND the client runtime enabled loads it once. */}
-      {headerItems.length > 0 && <KywiJsLoader />}
-
-      <header className="site-header">
-        <div className="site-header__inner">
-          <a className="site-brand" href="/">${escapeJsxText(a.projectName)}</a>
-          <div className="site-nav">
-            {headerItems.length > 0 && (
-              <SiteNav items={headerItems} variant="horizontal" ariaLabel="Primary" depth={2} />
-            )}
-            <a className="site-nav__admin" href="/admin">Admin →</a>
-          </div>
-        </div>
-      </header>
-
-      <main className="site-main">{children}</main>
-
-      <footer className="site-footer">
-        <div className="site-footer__inner">
-          {footerItems && footerItems.length > 0 && (
-            <SiteNav items={footerItems} variant="footer" ariaLabel="Footer" />
-          )}
-          <p className="site-footer__credit">Powered by <a href="https://kywi.dev">Kywi CMS</a></p>
-        </div>
-      </footer>
-    </div>
-  )
-}
-`
+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). */
@@ -1654,759 +1165,38 @@ function siteStyles(a) {
 `
 }
 
-/** Coupled catch-all: renders home ("/") and any published page at its path. */
-function siteSlugPage() {
-  return `import React, { cache } from 'react'
-import type { Metadata } from 'next'
-import { notFound } from 'next/navigation'
-import { cookies, headers } from 'next/headers'
-import { KywiBody, KywiEditableAttribute, KywiEditableRegion } from '@kywi-software/core/scope-client'
-import {
-  KywiLayout,
-  KywiRegion,
-  AudienceMetaTags,
-  hydrateLayoutFeeds,
-  hydrateLayoutNav,
-  pruneLayoutToServedArms,
-  type LayoutDocument,
-} from '@kywi-software/core/layout'
-import { KywiJsonLd } from '@kywi-software/core/scope'
-import { ACCESS_COOKIE, canAccessContent, readSessionClaims } from '@kywi-software/core/host'
-import config from '../../../lib/config'
-import { getActiveSite } from '../../../lib/kywi'
-import {
-  resolvePublicContent,
-  resolvePersonalization,
-  personalizeLayout,
-  resolveSelfIdWidget,
-  clientRuntimeEnabled,
-  transparencyNoticeEnabled,
-  requireConsentEnabled,
-  buildFeedResolver,
-  resolveLayoutComponents,
-  localeAlternates,
-  mediaUrl,
-  requestBaseUrl,
-} from '../../../lib/site'
-import { moduleComponents } from '../../../lib/modules'
-import { PersonalizationRuntime } from '../../../components/personalization-runtime'
-import { KywiFrontEdit } from '../kywi-front-edit'
-
-// Every page comes from the database, so this route is always dynamic.
-export const dynamic = 'force-dynamic'
-
-type Params = { params: Promise<{ slug?: string[] }> }
-type Search = { searchParams: Promise<Record<string, string | string[] | undefined>> }
-
-// One resolution shared by generateMetadata and the page render (React.cache
-// dedupes within a request). Keyed on stable primitives so the two calls dedupe:
-// the slug segments joined (segments never contain "/") and the Accept-Language
-// header, which selects the locale variant.
-const getNode = cache((key: string, acceptLanguage: string | null) =>
-  resolvePublicContent(key ? key.split('/') : [], { acceptLanguage }),
-)
-
-// SEO: map the admin's SEO-tab fields — Meta Title / Description / Keywords, the
-// OG Image (metaImageId, falling back to the page's Featured Image), Canonical,
-// Robots index/follow, and (on a multi-locale site) hreflang alternates — onto
-// Next's Metadata. The sitemap-only fields (changeFreq, sitemapPriority) are not
-// <head> metadata.
-export async function generateMetadata({ params }: Params): Promise<Metadata> {
-  const { slug } = await params
-  const acceptLanguage = (await headers()).get('accept-language')
-  const node = await getNode((slug ?? []).join('/'), acceptLanguage)
-  if (!node || node['status'] !== 'published') return {}
-
-  const title = (node['metaTitle'] as string) || String(node['title'] ?? 'Untitled')
-  const description = (node['metaDescription'] as string) || undefined
-  const keywords = (node['metaKeywords'] as string) || undefined
-  const image = mediaUrl(node['metaImageId']) ?? mediaUrl(node['featuredImageId'])
-  const images = image ? [image] : undefined
-  const canonical = (node['canonicalUrl'] as string) || undefined
-  const languages = await localeAlternates(slug ?? [])
-  const alternates =
-    canonical || languages
-      ? { ...(canonical ? { canonical } : {}), ...(languages ? { languages } : {}) }
-      : undefined
-
-  return {
-    title,
-    description,
-    keywords,
-    ...(alternates ? { alternates } : {}),
-    robots: { index: node['robotsIndex'] !== 'noindex', follow: node['robotsFollow'] !== 'nofollow' },
-    openGraph: { title, description, images, type: 'website' },
-    twitter: { card: images ? 'summary_large_image' : 'summary', title, description, images },
-  }
-}
-
-// True once the Layout editor has placed at least one section into any region.
-// A page with an empty layout document falls back to its Body rich text.
-function hasRenderableLayout(layout: LayoutDocument | null | undefined): layout is LayoutDocument {
-  if (!layout || typeof layout !== 'object' || !layout.regions) return false
-  return Object.values(layout.regions).some(
-    (sections) => Array.isArray(sections) && sections.length > 0,
-  )
-}
-
-// Is the current visitor a signed-in admin who may edit? The public route is
-// outside the middleware's auth matcher, so verify the httpOnly session cookie
-// here and derive the content permissions the overlay needs. Returns null for
-// anyone who cannot edit — no edit DOM (not even the browse-mode toolbar) is
-// emitted for them. Called on EVERY request (not just ?kywi-edit=1 ones) so the
-// toolbar can surface itself for a signed-in admin who is just browsing — this
-// is a cookie read + JWT verify, no DB round-trip, so the cost on an anonymous
-// visitor's fast path is a fast null return (\`readSessionClaims\` bails
-// immediately when there's no cookie).
-async function resolveEditPermissions() {
-  const token = (await cookies()).get(ACCESS_COOKIE)?.value
-  const claims = await readSessionClaims(token, config.auth.secret)
-  if (!claims || !canAccessContent(claims.role, 'write')) return null
-  return { canEdit: true, canPublish: canAccessContent(claims.role, 'publish'), role: claims.role }
-}
-
-// "/" resolves the seeded Home node; any other URL resolves the published node at
-// that FULL Site Tree path (locale-aware), so /a/b/<slug> cannot serve a
-// top-level <slug> (#30, #51). Draft / missing content 404s.
-export default async function PublicPage({ params, searchParams }: Params & Search) {
-  const { slug } = await params
-  const acceptLanguage = (await headers()).get('accept-language')
-  const node = await getNode((slug ?? []).join('/'), acceptLanguage)
-  if (!node || node['status'] !== 'published') notFound()
-
-  // The site this request is FOR, resolved from its Host header. \`siteId\` (not
-  // \`runtime.siteId\`, which is the DEFAULT site) keys every site-scoped call
-  // below; \`site\` selects the theme the flag helpers read.
-  const { runtime, site, siteId } = await getActiveSite()
-  const contentId = String(node['id'] ?? '')
-  const contentType = String(node['contentTypeName'] ?? 'page')
-  const title = String(node['title'] ?? 'Untitled')
-  const body = (node['body'] as string) || ''
-  const featured = mediaUrl(node['featuredImageId'])
-  const layout = node['layout'] as LayoutDocument | null | undefined
-
-  // Resolved on every request so a signed-in admin gets the persistent browse
-  // toolbar even when just browsing — ?kywi-edit=1 only decides whether the
-  // page auto-enters the full overlay editor on mount (kywi-cms#93). An
-  // anonymous/read-only visitor resolves to perms === null: zero extra client
-  // JS, identical output to before this route ever heard of the overlay.
-  const editRequested = (await searchParams)['kywi-edit'] === '1'
-  const perms = await resolveEditPermissions()
-
-  // Server-side personalization (#50), evaluated once: the winning audience (or a
-  // kywi_preview_init preview) drives page variants + variantContainers, and this
-  // visitor's A/B arms are assigned deterministically. Opted-out / anonymous
-  // visitors resolve to the default experience.
-  const perso = await resolvePersonalization(runtime, layout)
-  const selfIdWidget = await resolveSelfIdWidget(runtime, siteId)
-
-  // <head> injections (React hoists these): per-page JSON-LD gated on the
-  // AX/JSON-LD setting, mapping the SAME node so page and schema agree (#56); the
-  // Comments module's content-id anchor (#29); the audience/visitor ids for
-  // client tooling (#50); and — when the theme opts in — the optional client
-  // runtime that mounts the self-ID widget and re-evaluates audiences.
-  //
-  // \`head\` is a FUNCTION because JSON-LD must describe the layout THIS visitor
-  // is served (#195): the served document only exists after the arms are pruned
-  // below, and building the description from the STORED layout would ship the
-  // DEFAULT arm's copy to a matched visitor — the #167 leak, through structured
-  // data. The no-layout branch passes nothing, and JSON-LD then describes the
-  // node's body/metaDescription/summary alone.
-  const baseUrl = await requestBaseUrl()
-  const headFor = (servedLayout?: unknown) => (
-    <>
-      <meta name="kywi:content-id" content={contentId} />
-      <KywiJsonLd
-        node={node}
-        config={runtime.config}
-        baseUrl={baseUrl}
-        siteId={siteId}
-        {...(servedLayout ? { layout: servedLayout } : {})}
-      />
-      <AudienceMetaTags audienceId={perso.audienceId} visitorId={perso.visitorId} />
-      {clientRuntimeEnabled(runtime, site) && perso.audiences.length > 0 ? (
-        <PersonalizationRuntime
-          audiences={perso.audiences}
-          serverSignals={perso.signals}
-          selfIdWidget={selfIdWidget}
-          transparencyNotice={transparencyNoticeEnabled(runtime, site)}
-          requireConsent={requireConsentEnabled(runtime, site)}
-        />
-      ) : null}
-    </>
-  )
-
-  // When the Layout tab has designed the page, render its region-based document
-  // through core's own layout renderer (KywiLayout / KywiRegion). Before that:
-  // hydrate every Feed Display module (#28), resolve connected reusable
-  // components (#46), and supply the custom-module renderers (#48). Otherwise
-  // fall back to the built-in Body rich text (+ any Featured Image).
-  let content: React.ReactNode
-  if (hasRenderableLayout(layout)) {
-    // Apply the audience's page variant (and strip the other variants), then
-    // hydrate feeds and resolve components on the layout THIS visitor sees.
-    // variantContainer arms resolve at render time from \`personalization\`.
-    const personalized = personalizeLayout(layout, perso.audienceId)
-    const feedsHydrated = await hydrateLayoutFeeds(personalized, buildFeedResolver(runtime, siteId))
-    // Resolve every navMenu/navigation/siteMap module placed in THIS layout
-    // (menuSlug → a real menu; the tree otherwise) — the same seam as feeds,
-    // so a nav module dropped into any region/section just works (#112).
-    const currentPath = String(node['path'] ?? '/')
-    const navHydrated = await hydrateLayoutNav(
-      feedsHydrated,
-      runtime.scope.menus.createHydrationResolver(siteId, currentPath),
-    )
-    // Linked components resolve HERE, on the server, into the document itself:
-    // KywiLayout is a client component and the renderer's resolver props are
-    // functions, which cannot cross the RSC boundary (#147).
-    const hydrated = await resolveLayoutComponents(navHydrated, runtime, siteId)
-    // LAST pass before the client boundary (#167): keep ONLY the arm this
-    // visitor is served in every variantContainer / moduleVariantContainer.
-    // KywiLayout is a client component, so anything still on the document here
-    // is serialized into the page's RSC flight payload — arm SELECTION was
-    // always server-side, but the losing arms crossed with it and were readable
-    // in view-source. Pruning uses the same \`perso.personalization\` the
-    // renderer is handed, so the markup is unchanged.
-    //
-    // Order matters: after component resolution (a container that is only a
-    // \`componentId\` has no arms of its own to prune yet) and after the feed/nav
-    // hydration passes. The front-edit overlay below is given the STORED
-    // \`layout\`, never this — an editor needs every arm.
-    const served = pruneLayoutToServedArms(hydrated, perso.personalization)
-    content = (
-      <article className="page page--layout" data-kywi-content-id={contentId}>
-        {headFor(served)}
-        <KywiLayout
-          layout={served}
-          personalization={perso.personalization}
-          moduleComponents={moduleComponents}
-        >
-          {Object.keys(served.regions).map((name) => (
-            <KywiRegion key={name} name={name} />
-          ))}
-        </KywiLayout>
-      </article>
-    )
-  } else {
-    content = (
-      <article className="page" data-kywi-content-id={contentId}>
-        {headFor()}
-        {featured ? <img className="page__featured" src={featured} alt="" /> : null}
-        <h1 className="page__title">{title}</h1>
-        {perms ? (
-          <KywiEditableRegion region="main">
-            <KywiEditableAttribute field="body" type="richtext" contentId={contentId}>
-              {body ? <KywiBody content={body} /> : <p className="page__empty">This page has no content yet.</p>}
-            </KywiEditableAttribute>
-          </KywiEditableRegion>
-        ) : body ? (
-          <KywiBody content={body} />
-        ) : (
-          <p className="page__empty">This page has no content yet.</p>
-        )}
-      </article>
-    )
-  }
-
-  // Mount the overlay (client) for any authenticated admin (write role+) —
-  // browse mode renders just the slim toolbar; ?kywi-edit=1 (editRequested)
-  // additionally auto-starts the full overlay editor. Nothing mounts for an
-  // anonymous or read-only visitor.
-  if (perms) {
-    return (
-      <KywiFrontEdit
-        canEdit={perms.canEdit}
-        canPublish={perms.canPublish}
-        editRequested={editRequested}
-        contentId={contentId}
-        contentType={contentType}
-        pageTitle={title}
-        pageStatus={String(node['status'] ?? '')}
-        initialLayout={layout ?? { regions: { main: [] } }}
-        adminHref={\`/admin/content/\${contentType}/\${contentId}\`}
-        moduleComponents={moduleComponents}
-        hostModules={config.modules ?? []}
-      >
-        {content}
-      </KywiFrontEdit>
-    )
-  }
-
-  return content
-}
-`
-}
-
-/**
- * Front-of-site edit overlay (client). Mounted by the public page for ANY
- * authenticated admin (write role+) — the page verifies the session cookie
- * server-side first (resolveEditPermissions, called unconditionally) and only
- * mounts this when that check passes, so canEdit is always true here.
- *
- * Two modes, same component:
- *  - **Browse** (default) — core's slim `KywiEditToolbar`, a persistent
- *    WordPress-admin-bar-style strip over the live page (page title, draft/
- *    published status, "Edit this page", "Go to admin") — this is the
- *    discoverability fix (kywi-cms#93): an admin browsing the public site
- *    normally, with no query param, now sees the entry point. The editable
- *    regions are also outlined via the `data-kywi-*` protocol.
- *  - **Edit** (the toolbar's "Edit this page", or landing with
- *    `?kywi-edit=1`) — the FULL `OverlayShell` layout editor, the same one the
- *    admin app mounts, rendered from the same core module registry + custom
- *    renderers. Save PUTs the layout document; Publish PUTs the layout then
- *    flips status — exactly the API the admin editor uses. Entering/leaving
- *    edit mode keeps `?kywi-edit=1` in sync via history.replaceState, so a
- *    reload (or a shared link) lands back in the same mode.
- *
- * The OverlayShell is lazy-loaded (`next/dynamic`, client-only): its weight
- * (dnd-kit, canvas, side panels) is only fetched when an editor actually enters
- * edit mode, so the public browse bundle stays light.
- */
-function frontEditOverlay() {
-  return `'use client'
-import React from 'react'
-import dynamic from 'next/dynamic'
-import { KywiEditToolbar, useKywiEditMode } from '@kywi-software/core/scope-client'
-import { adminFetch } from '@kywi-software/core/host-client'
-import {
-  createModuleRegistry,
-  createThemeRegistry,
-  BUILT_IN_MODULE_COMPONENTS,
-  type LayoutDocument,
-  type ModuleComponentMap,
-  type ModuleConfig,
-} from '@kywi-software/core/layout'
-import type { SaveAction } from '@kywi-software/core/admin'
-
-/**
- * Injects the admin design system's stylesheet as a plain \`<link>\` tag rather
- * than an ES \`import\` (kywi-cms#130 follow-up). A dynamic \`import('…/admin/
- * styles.css')\` still shipped the stylesheet on every public route that
- * reaches this factory, regardless of the \`next/dynamic\` wrapping around
- * it. A \`<link>\` created imperatively at runtime has no \`import\` statement
- * for Next's CSS collector to see, so it never enters the build's CSS graph.
- *
- * VERIFIED (in the reference app this template mirrors) against a real
- * \`next build && next start\`: an anonymous fetch of a real published content
- * page shows zero OverlayShell/editor.css/admin.css references in any of its
- * fetched resources. Fetching the SAME page against \`next dev\` still shows
- * every one of those markers regardless of this fix — \`next dev\` bundles far
- * more eagerly than a production build, for ALL routes, independent of any
- * dynamic()/runtime-injection technique. A generated app's own e2e coverage
- * of this (if any) needs to build for real, not assert against \`next dev\`.
- *
- * Two follow-ups from review:
- *  - CACHE-BUSTING: \`/kywi-admin.css\` and \`/kywi-admin.css.version\` are both
- *    synced from the installed \`@kywi-software/core\` package
- *    (scripts/sync-kywi-admin-css.mjs, run via package.json's
- *    \`sync:kywi-admin-css\` on every \`predev\`/\`prebuild\`) — mirroring how
- *    \`public/kywi.js\` is synced from \`@kywi-software/js\`. The version
- *    file's content becomes the \`?v=\` query string below, so a core upgrade
- *    that changes the stylesheet always serves a URL a CDN/browser has never
- *    cached, instead of a stale \`/kywi-admin.css\` response.
- *  - FOUC: returns a Promise that resolves once the tag has actually loaded
- *    (or failed to) — an existing, already-loaded tag resolves immediately;
- *    a fresh or still-loading one resolves on its \`load\`/\`error\` event. The
- *    dynamic() factory below awaits this ALONGSIDE the OverlayShell JS
- *    import, so the editor's first paint never races its own stylesheet.
- */
-function ensureAdminStylesheet(): Promise<void> {
-  if (typeof document === 'undefined') return Promise.resolve()
-  const existing = document.querySelector<HTMLLinkElement>('link[data-kywi-admin-css]')
-  if (existing) {
-    // \`.sheet\` is non-null only once the stylesheet has actually parsed —
-    // resolve immediately rather than re-attaching listeners to an event
-    // that already fired.
-    if (existing.sheet) return Promise.resolve()
-    return new Promise((resolve) => {
-      existing.addEventListener('load', () => resolve(), { once: true })
-      existing.addEventListener('error', () => resolve(), { once: true })
-    })
-  }
-  return fetch('/kywi-admin.css.version')
-    .then((res) => (res.ok ? res.text() : ''))
-    .catch(() => '')
-    .then(
-      (version) =>
-        new Promise<void>((resolve) => {
-          const link = document.createElement('link')
-          link.rel = 'stylesheet'
-          const v = version.trim()
-          link.href = v ? \`/kywi-admin.css?v=\${encodeURIComponent(v)}\` : '/kywi-admin.css'
-          link.dataset.kywiAdminCss = 'true'
-          // A load OR error either way lets the caller proceed — a stylesheet
-          // that 404s must never permanently block the editor from opening.
-          link.addEventListener('load', () => resolve(), { once: true })
-          link.addEventListener('error', () => resolve(), { once: true })
-          document.head.appendChild(link)
-        }),
-    )
-}
-
-// Lazy-load the full layout editor bundle: the shell's JS (dnd-kit, canvas,
-// panels) is pulled INSIDE this factory, so it enters the module graph only
-// when an editor opens the overlay — never in the public browse bundle a
-// visitor downloads. The stylesheet is handled separately — see
-// \`ensureAdminStylesheet\` above — since a css import here, even a dynamic
-// one, does not behave like the JS import right below it. Both are awaited
-// together so the editor never paints ahead of its own stylesheet (FOUC).
-const OverlayShell = dynamic(
-  async () => {
-    const [, mod] = await Promise.all([
-      ensureAdminStylesheet(),
-      import('@kywi-software/core/admin'),
-    ])
-    return mod.OverlayShell
-  },
-  { ssr: false },
-)
-
-export interface KywiFrontEditProps {
-  canEdit: boolean
-  canPublish: boolean
-  /** True when the page was requested with \`?kywi-edit=1\` — auto-starts the full overlay editor on mount. */
-  editRequested: boolean
-  contentId: string
-  contentType: string
-  pageTitle: string
-  pageStatus: string
-  /** The page's saved layout document (empty regions when it has none yet). */
-  initialLayout: LayoutDocument
-  /** Deep link to this page in the full admin editor. */
-  adminHref: string
-  /** Custom (defineModule) renderers, shared with the public layout + admin (#48). */
-  moduleComponents?: ModuleComponentMap
-  /** Custom (defineModule) module CONFIGS from kywi.config.ts — gives the overlay
-   *  editor each custom module's prop definitions, so the props rail and inline
-   *  text editing work for them exactly as in the admin editor (kywi-cms#118). */
-  hostModules?: ModuleConfig[]
-  children: React.ReactNode
-}
-
-/**
- * Wraps the public page with the front-of-site edit affordance. The page
- * renders this for ANY signed-in admin (write role+) — canEdit is always true
- * here, since the page only mounts KywiFrontEdit once resolveEditPermissions
- * has already confirmed it server-side. Browse mode shows the persistent
- * KywiEditToolbar (the primary discoverability fix, kywi-cms#93); the full
- * OverlayShell editor only mounts once edit mode actually starts — either the
- * toolbar's "Edit this page" button, or landing with \`?kywi-edit=1\`
- * (editRequested), which auto-starts it once on mount.
- */
-export function KywiFrontEdit({
-  canEdit,
-  canPublish,
-  editRequested,
-  contentId,
-  contentType,
-  pageTitle,
-  pageStatus,
-  initialLayout,
-  adminHref,
-  moduleComponents = {},
-  hostModules = [],
-  children,
-}: KywiFrontEditProps) {
-  const edit = useKywiEditMode({ canEdit, canPublish })
-
-  // ?kywi-edit=1 (editRequested) means "enter edit mode now" — flip it on once
-  // after mount. Without it the page mounts straight into browse mode (the
-  // persistent toolbar), which is the common case now that KywiFrontEdit
-  // renders for every signed-in admin, not only deep-linked ones.
-  const { startEdit, endEdit } = edit
-  React.useEffect(() => {
-    if (editRequested) startEdit()
-  }, [editRequested, startEdit])
-
-  // Registries + renderers for the editor: the module registry carries each
-  // module's prop definitions (built-ins + this app's kywi.config.ts modules —
-  // without the host list, custom modules render but are uneditable, kywi-cms#118),
-  // merged with the custom renderers from lib/modules (#48).
-  const moduleRegistry = React.useMemo(
-    () => createModuleRegistry(hostModules ?? []),
-    [hostModules],
-  )
-  const themeRegistry = React.useMemo(() => createThemeRegistry(), [])
-  const editorComponents = React.useMemo(
-    () => ({ ...BUILT_IN_MODULE_COMPONENTS, ...moduleComponents }),
-    [moduleComponents],
-  )
-
-  // Persist the edited layout to the same content API the admin editor uses.
-  const persistLayout = React.useCallback(
-    async (next: LayoutDocument) => {
-      const res = await fetch(\`/api/v1/content/\${contentType}/\${contentId}/layout\`, {
-        method: 'PUT',
-        credentials: 'same-origin',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(next),
-      })
-      return res.ok
-    },
-    [contentType, contentId],
-  )
-
-  const handleSave = React.useCallback(
-    async (next: LayoutDocument, _action: SaveAction) => {
-      await persistLayout(next)
-      endEdit()
-    },
-    [persistLayout, endEdit],
-  )
-
-  const handlePublish = React.useCallback(
-    async (next: LayoutDocument, _action: SaveAction) => {
-      const ok = await persistLayout(next)
-      if (ok) {
-        // Best-effort status flip; the layout itself is already persisted above.
-        await fetch(\`/api/v1/content/\${contentType}/\${contentId}\`, {
-          method: 'PUT',
-          credentials: 'same-origin',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ status: 'published' }),
-        }).catch(() => undefined)
-      }
-      endEdit()
-    },
-    [persistLayout, contentType, contentId, endEdit],
-  )
-
-  // Browse-mode one-click publish from the toolbar (no editor needed).
-  const handleToolbarPublish = React.useCallback(async () => {
-    const res = await adminFetch(\`/api/v1/content/by-id/\${contentId}/publish\`, { method: 'POST' })
-    if (res.ok) window.location.reload()
-  }, [contentId])
-
-  // Edit mode: the full layout editor, in place, over the live page.
-  // NOTE: no \`kywi-admin-shell\` here (kywi-cms#94). That class is the admin
-  // design system's base+reset — font family, font size, colours, heading
-  // resets — and wrapping the page in it re-typesets the very content the
-  // owner is trying to judge at real width. The editor chrome carries its own
-  // styling; the page keeps the site's.
-  if (edit.isEditMode && edit.canEdit) {
-    return (
-      <div className="kywi-frontend-edit">
-        <OverlayShell
-          editMode={edit}
-          initialLayout={initialLayout}
-          contentId={contentId}
-          contentType={contentType}
-          pageTitle={pageTitle}
-          /* The page's own body wrapper, so the site's page-level CSS (width,
-             gutters, rhythm) still applies while editing in place. */
-          pageClassName="page page--layout"
-          themeName="default"
-          themeRegistry={themeRegistry}
-          moduleRegistry={moduleRegistry}
-          moduleComponents={editorComponents}
-          onSave={handleSave}
-          onPublish={handlePublish}
-        />
-      </div>
-    )
-  }
-
-  // Browse mode: slim toolbar + editable-region outlines over the live page.
-  return (
-    <>
-      <KywiEditToolbar
-        isEditMode={edit.isEditMode}
-        canEdit={edit.canEdit}
-        canPublish={edit.canPublish}
-        onToggleEdit={edit.toggleEdit}
-        onPublish={handleToolbarPublish}
-        pageTitle={pageTitle}
-        pageStatus={pageStatus}
-        adminHref={adminHref}
-      />
-      {/* Toggling this attribute drives the editable-region outlines shipped in
-          @kywi-software/core/site/styles.css. */}
-      <div data-kywi-editing={edit.isEditMode ? '' : undefined}>{children}</div>
-    </>
-  )
-}
-`
-}
-
-/**
- * Shared `/kywi.js` script-injection primitive (kywi-cms#114). Two independent
- * triggers can each want the browser bundle on the page: the site layout's nav
- * (`<KywiJsLoader>`, purely for the hover-intent/keyboard/viewport-flip
- * enhancement `initNavMenus()` applies unconditionally once the script boots)
- * and `<PersonalizationRuntime>` (which additionally waits on
- * `window.Kywi.bootAudienceEngine`). Before this fix only the personalization
- * runtime ever injected the tag, so a site with `personalization.clientRuntime`
- * off — or simply no active audiences — never got the nav enhancement either,
- * even though the nav renders fully without it (kywi-cms#111's JS-off contract)
- * and would only ever gain from it. `ensureKywiJsScript` is idempotent:
- * whichever caller mounts first creates the ONE `<script data-kywi-js>` tag,
- * every other caller finds it already there — so both triggers being true at
- * once never loads the bundle twice.
- */
-function kywiJsLoaderLib() {
-  return `export function ensureKywiJsScript(): HTMLScriptElement | null {
-  if (typeof document === 'undefined') return null
-  const existing = document.querySelector<HTMLScriptElement>('script[data-kywi-js]')
-  if (existing) return existing
-  const script = document.createElement('script')
-  script.src = '/kywi.js'
-  script.async = true
-  script.dataset.kywiJs = 'true'
-  document.body.appendChild(script)
-  return script
-}
-`
-}
-
-/**
- * Loads `/kywi.js` for its nav enhancement alone, independent of
- * personalization (kywi-cms#114). Rendered by the site layout whenever the
- * resolved header menu is non-empty — the same condition `<SiteNav>` itself
- * gates on before it renders a `[data-kywi-nav]` root — so this mounts exactly
- * when there is a nav for `initNavMenus()` to enhance. Does nothing beyond
- * ensuring the script tag exists: `Kywi.boot()` runs `initNavMenus()`
- * unconditionally as part of its own bootstrap once the script loads, and
- * never touches personalization on its own.
- */
-function kywiJsLoaderComponent() {
-  return `'use client'
-
-import { useEffect } from 'react'
-import { ensureKywiJsScript } from '../lib/kywi-js-loader'
-
-export function KywiJsLoader() {
-  useEffect(() => {
-    ensureKywiJsScript()
-  }, [])
-
-  return null
-}
-`
-}
-
 /**
- * Client personalization runtime (kywi-cms#50). The SERVER already resolved and
- * rendered the correct audience/experiment variant and set the ids in <head>;
- * this optional client layer adds live re-evaluation, the self-ID widget, the
- * transparency bar, and behavioral-signal collection by booting the
- * @kywi-software/js browser bundle from /kywi.js. It is best-effort and mounted
- * only when the theme opts in (theme.personalization.clientRuntime), so the site
- * stays dependency-free by default: drop the built @kywi-software/js bundle at
- * public/kywi.js to enable it (see README → "Personalization"). Without it the
- * server-rendered variant is exactly what every visitor sees.
+ * The public catch-all — a thin delegate over `createPublicPage`.
  *
- * kywi-cms#114: `/kywi.js` may already be on the page independent of this
- * component — the site layout's `<KywiJsLoader>` loads it purely for nav
- * enhancement whenever the site has a nav. `ensureKywiJsScript` (shared with
- * that component, lib/kywi-js-loader.ts) is idempotent, so this never injects
- * a second copy.
- */
-function personalizationRuntime() {
-  return `'use client'
-
-import React, { useEffect } from 'react'
-import type { Audience, VisitorSignals } from '@kywi-software/core/audiences/types'
-import type { PublicSelfIdWidget } from '../lib/site'
-import { ensureKywiJsScript } from '../lib/kywi-js-loader'
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-declare global {
-  interface Window {
-    Kywi?: any
-    kywi?: any
-  }
-}
-
-interface PersonalizationRuntimeProps {
-  /** Active audiences the client re-evaluates (rule definitions, no PII). */
-  audiences: Audience[]
-  /** Server-resolved signals (UTM / referrer / identity / opt-out) for parity. */
-  serverSignals: Partial<VisitorSignals>
-  /** Resolved self-ID widget config; when present its trigger/frequency mount it. */
-  selfIdWidget?: PublicSelfIdWidget | null
-  /**
-   * \`personalization.transparencyNotice.enabled\` — false suppresses the
-   * automatic global transparency panel; the visitor can still open it
-   * deliberately through a \`personalizationBadge\` module. Defaults to true.
-   */
-  transparencyNotice?: boolean
-  /**
-   * \`personalization.requireConsent\` — false turns the client's consent gate
-   * off for a site that collects consent with external tooling. Defaults to
-   * true, so the resolved audience is only remembered for a consenting visitor
-   * (kywi-cms#91).
-   */
-  requireConsent?: boolean
-}
-
-/**
- * Ensures /kywi.js is on the page, then boots the audience data-layer.
- * bootAudienceEngine reads the opt-out cookie itself and resolves opted-out
- * visitors to the default experience, so opt-out is respected end to end.
- * Rendered only when theme.personalization.clientRuntime is on.
+ * What used to be 279 emitted lines (content resolution, SEO metadata + locale
+ * alternates, JSON-LD over the served document, audience meta tags, server-side
+ * personalization and A/B assignment, the self-ID widget, arm pruning, the
+ * front-edit overlay gate) is `@kywi-software/core/next`. The generated file
+ * supplies the two project-specific inputs `layered-architecture DESIGN.md` §2
+ * counted — the wiring runtime and this app's custom module renderers.
  *
- * kywi-cms#114: the script tag may already be on the page independent of this
- * component — the site layout's <KywiJsLoader> loads it purely for nav
- * enhancement whenever the site has a nav. ensureKywiJsScript (shared with
- * that component) is idempotent, so this never injects a second copy.
+ * `dynamic` is written as a LITERAL on purpose: Next parses route segment
+ * config statically and fails the build on `export const dynamic = page.dynamic`
+ * ("Unsupported node type MemberExpression"). Core types the field as the
+ * literal `'force-dynamic'` so the two still cannot drift.
  */
-export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget, transparencyNotice, requireConsent }: PersonalizationRuntimeProps) {
-  useEffect(() => {
-    let cancelled = false
-    const ready = () => typeof window.Kywi?.bootAudienceEngine === 'function'
-
-    function boot(): void {
-      if (cancelled || !ready()) return
-      const currentPath = window.location.pathname
-      window.Kywi
-        .bootAudienceEngine({
-          audiences,
-          currentPath,
-          serverSignals,
-          ...(selfIdWidget
-            ? { selfIdWidget: { ...selfIdWidget, audiences, currentPath } }
-            : {}),
-          ...(transparencyNotice === false ? { transparencyNotice: false } : {}),
-          ...(requireConsent === false ? { requireConsent: false } : {}),
-        })
-        .catch(() => {
-          /* client personalization is best-effort; the server already rendered defaults */
-        })
-    }
-
-    function whenReady(): void {
-      if (ready()) return boot()
-      let tries = 0
-      const timer = setInterval(() => {
-        tries += 1
-        if (ready()) {
-          clearInterval(timer)
-          boot()
-        } else if (tries > 50) {
-          clearInterval(timer)
-        }
-      }, 60)
-    }
-
-    // kywi-cms#114: the script tag itself may already be on the page — the
-    // site layout's <KywiJsLoader> injects it independently, purely for nav
-    // enhancement, whenever the site has a nav. \`ensureKywiJsScript\` is the
-    // shared dedup primitive: it returns the existing tag if one is already
-    // there, so this never creates a second one.
-    const script = ensureKywiJsScript()
-    if (ready()) boot()
-    else script?.addEventListener('load', whenReady)
-
-    return () => {
-      cancelled = true
-    }
-    // Boot once on mount; audiences/serverSignals are per-request stable.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
-
-  return null
-}
-`
+function siteSlugPage() {
+  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 generated layer registry.
+import { createPublicPage } from '@kywi-software/core/next'
+import { kywi } from '../../../lib/kywi'
+import { layers } from '../../../kywi.layers'
+
+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). */
@@ -2440,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
@@ -2473,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
-  }
-
-  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
-}
+const route = createApiRoute({ runtime: kywi })
 
-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\`).
- *
- * 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.
+ * The admin host page — a thin delegate over `createAdminPage` (plan E3 T4).
  *
- * 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 '../../../lib/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) ─────────────────────────────────
@@ -2732,7 +1441,8 @@ page: add sections and modules, then **Save** (PUTs the layout) or **Publish**
 (saves + publishes). **Done** returns you to the browse toolbar. Entering or
 leaving the editor keeps \`?kywi-edit=1\` in the URL in sync, so reloading (or
 sharing the link) lands back in the same mode. It all lives in
-\`app/(site)/kywi-front-edit.tsx\`; the editor bundle (and the admin stylesheet) is
+\`@kywi-software/core/next\` (mounted by the generated public page), so it
+upgrades with the package; the editor bundle (and the admin stylesheet) is
 lazy-loaded, so pages your visitors see never carry its weight — an anonymous
 or read-only visitor gets no toolbar and no extra client JS. Custom
 \`defineModule\` types from \`kywi.config.ts\` also appear in the front-of-site
@@ -2776,13 +1486,13 @@ Audiences, experiments and the self-ID widget you configure in the admin resolve
 The **self-ID widget**, live re-evaluation, the transparency bar and behavioral
 signals are an optional *client* layer. Enable it by setting
 \`personalization: { clientRuntime: true }\` on your theme in \`kywi.config.ts\` and
-dropping the built \`@kywi-software/js\` browser bundle at \`public/kywi.js\`; the
-generated \`components/personalization-runtime.tsx\` loads it best-effort. Without
-it, the server-rendered variant is what every visitor sees.
+dropping the built \`@kywi-software/js\` browser bundle at \`public/kywi.js\`;
+core's \`PersonalizationRuntime\` (mounted by the public page) loads it
+best-effort. Without it, the server-rendered variant is what every visitor sees.
 
 The same \`public/kywi.js\` bundle also drives the header nav's hover-intent,
 Escape/arrow-key and viewport-edge-flip enhancement — independent of
-personalization. \`components/kywi-js-loader.tsx\` loads it whenever the site has
+personalization. Core's site layout loads it whenever the site has
 a nav, whether or not \`clientRuntime\` is on, so the nav gets that polish on
 every site once the bundle is in place; the nav renders and works fully without
 it either way. (\`public/kywi-admin.css\`, the front-of-site editor's stylesheet,
@@ -2880,16 +1590,25 @@ kywi.config.ts                    your config: sites, themes, content types, cus
 AGENTS.md                         guidance for AI agents working on this site (Kywi's building patterns)
 CLAUDE.md                         points AI agents to AGENTS.md
 ${SKILLS.map(({ slug }) => `.claude/skills/${slug}/SKILL.md  ${slug.replace(/^kywi-/, '')} skill (loaded automatically)`).join('\n')}
-middleware.ts                     auth gate + session refresh + cookie→bearer bridge
+middleware.ts                     re-exports core's middleware (auth gate, session refresh, cookie→bearer)
 next.config.mjs                   required Next config to consume @kywi-software/core
-lib/kywi.ts                       server runtime (DB, API handler, content scope)
-lib/config.ts                     single import path for kywi.config.ts
+lib/kywi.ts                       the ONE wiring point: kywi.config.ts → core's render path
 app/api/v1/[...kywi]/route.ts     the versioned API (delegates to core)
 app/admin/[[...admin]]/page.tsx   mounts the FULL core admin (all surfaces) at /admin
 lib/modules.tsx                   custom (defineModule) module renderers (admin + public)
-app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/site-nav.tsx            client wrapper around the shared nav renderer (header + footer)\ncomponents/kywi-js-loader.tsx      loads /kywi.js for nav enhancement whenever the site has a nav\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell (delegate): your brand, nav + stylesheets\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (delegate): wires in your module map\ncomponents/site-nav.tsx            client wrapper around the shared nav renderer (header + footer)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
 \`\`\`
-`
+${a.mode === 'coupled' ? `
+\`lib/kywi.ts\`, \`middleware.ts\` and the two \`app/(site)\` route files are
+**thin, version-stamped delegates** (each opens with a \`// kywi-render v…\`
+comment; nothing else in the project carries one). The public render
+path itself — content and locale resolution, SEO metadata, JSON-LD, feed and nav
+hydration, personalization, A/B assignment and the front-of-site editor — lives
+in \`@kywi-software/core/next\`, so \`pnpm up @kywi-software/core\` upgrades it
+instead of leaving you to hand-merge a changelog into your own copy. What stays
+yours: \`kywi.config.ts\`, \`app/(site)/site.css\`, \`lib/modules.tsx\` and
+\`components/site-nav.tsx\`.
+` : ''}`
 }
 
 // ── helpers ───────────────────────────────────────────────────────────────────
@@ -2901,9 +1620,17 @@ function slugify(name) {
     .replace(/^_+|_+$/g, '') || 'kywi_app'
 }
 
-/** Escape a value interpolated as JSX text so it can't break out of the element. */
-function escapeJsxText(value) {
-  return String(value).replace(/[{}<>]/g, (ch) => `{'${ch}'}`)
+/**
+ * Escape a value interpolated into a SINGLE-QUOTED TypeScript string literal, so
+ * it cannot break out of the quotes or the line. Replaces the old
+ * `escapeJsxText`: since plan E1 the project name reaches the generated site
+ * layout as `brand: { label: '…' }` — a string literal argument — rather than as
+ * JSX text inside the header markup.
+ */
+function escapeJsString(value) {
+  return String(value)
+    .replace(/[\\']/g, (ch) => `\\${ch}`)
+    .replace(/\r?\n/g, '\\n')
 }
 
 // ── Agent guidance (AGENTS.md / CLAUDE.md) ──────────────────────────────────────
@@ -2940,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
@@ -3027,15 +1754,22 @@ export const AGENTS_LANDMARK_PATHS = {
  * @property {boolean} adminHost   app/admin/[[...admin]]/page.tsx present
  * @property {boolean} moduleMap   lib/modules.tsx present
  * @property {boolean} middleware  middleware.ts present
- * @property {boolean} libSite     lib/site.ts present (the scaffold's public-render helpers)
+ * @property {boolean} libSite     lib/site.ts present — a LEGACY landmark since
+ *   plan E1: the scaffold no longer emits it (the public-render helpers ship in
+ *   `@kywi-software/core/next`), but a project scaffolded before E1 still has
+ *   its own copy and the header must describe that honestly.
  * @property {boolean} sitePage    app/(site)/[[...slug]]/page.tsx present (renders public pages)
  * @property {boolean} headlessPage app/page.tsx present (the headless/decoupled 404 root)
  */
 
 /**
  * The landmark set a FRESH scaffold of the given mode has — derived statically
- * from the mode, never from the filesystem, so buildFileSet emits AGENTS.md that
- * is byte-identical to the previous mode-branching implementation.
+ * from the mode, never from the filesystem.
+ *
+ * `libSite` is FALSE in every mode since plan E1: a freshly scaffolded project
+ * has no `lib/site.ts` at all, because the public-render helpers ship in
+ * `@kywi-software/core/next`. It stays in the type because
+ * {@link detectAgentsLandmarks} still finds one in a pre-E1 project.
  * @param {'coupled'|'headless'|'decoupled'} mode
  * @returns {AgentsLandmarks}
  */
@@ -3046,7 +1780,7 @@ export function scaffoldLandmarks(mode) {
     adminHost: true,
     moduleMap: true,
     middleware: true,
-    libSite: coupled,
+    libSite: false,
     sitePage: coupled,
     headlessPage: !coupled,
   }
@@ -3055,8 +1789,8 @@ export function scaffoldLandmarks(mode) {
 /**
  * Detect the AGENTS.md landmarks that actually exist in an EXISTING project, so
  * `create-kywi-app agents` writes a header that matches the app on disk (a
- * hand-built app may render the public site from the page directly and predate
- * the scaffold's lib/site.ts helper or lib/modules.tsx map).
+ * hand-built app may have no lib/modules.tsx map; a project scaffolded before
+ * plan E1 still carries its own lib/site.ts copy of the render helpers).
  * @param {string} projectDir  absolute path to the project root
  * @returns {AgentsLandmarks}
  */
@@ -3077,9 +1811,10 @@ export function detectAgentsLandmarks(projectDir) {
  * AGENTS.md — a short, app-specific header that orients an agent in THIS app,
  * followed by Kywi's canonical patterns doc verbatim. Landmark-aware: each "Where
  * things live" bullet is emitted only for a landmark that is actually present, and
- * absent public-render (lib/site.ts) or module-map (lib/modules.tsx) wiring becomes
- * an honest "this app predates the scaffold's …" line instead of a bullet that
- * asserts a file the project does not have. With no landmarks passed it defaults to
+ * an absent module map (lib/modules.tsx) becomes an honest "this app predates the
+ * scaffold's …" line instead of a bullet that asserts a file the project does not
+ * have. A `lib/site.ts` found on disk (only a pre-E1 project has one) is described
+ * as the legacy copy it is. With no landmarks passed it defaults to
  * the fresh-scaffold set for the mode, so the scaffold output is unchanged.
  * @param {Answers} a
  * @param {AgentsLandmarks} [landmarks]
@@ -3116,17 +1851,26 @@ export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
   \`defineModule\` module map (shared by the admin editor and the public site); see
   the patterns doc below for the intended shape.`)
   }
-  // Public-render surface: the scaffold's lib/site.ts helper, else a page that
-  // renders publicly without it (honest note), else no public rendering at all.
+  // Public-render surface. Three honest cases, in order:
+  //  1. a PRE-E1 project that still owns a copy of the render helpers;
+  //  2. the current shape — thin delegates over @kywi-software/core/next;
+  //  3. no public rendering at all (headless/decoupled).
   if (L.libSite) {
-    bullets.push(`- \`lib/site.ts\` — public-render helpers (path/locale resolution, feeds,
-  components, personalization) used by \`app/(site)/[[...slug]]/page.tsx\`, which
-  renders every published page at its slug.`)
+    bullets.push(`- \`lib/site.ts\` — this app's OWN copy of Kywi's public-render helpers
+  (path/locale resolution, feeds, components, personalization), used by
+  \`app/(site)/[[...slug]]/page.tsx\`, which renders every published page at its
+  slug. It predates the layered shape: current Kywi ships those helpers in
+  \`@kywi-software/core/next\`, and a copy here is a copy a core upgrade cannot
+  reach. Prefer core's; do not add more render logic to this file.`)
   } else if (L.sitePage) {
-    bullets.push(`- \`app/(site)/[[...slug]]/page.tsx\` — renders every published page at its
-  slug. This app predates the scaffold's \`lib/site.ts\` public-render helpers
-  (path/locale resolution, feeds, components, personalization); see the patterns
-  doc below for the intended shape.`)
+    bullets.push(`- \`app/(site)/[[...slug]]/page.tsx\` + \`app/(site)/layout.tsx\` — thin,
+  version-stamped delegates. The public render path itself (content + locale
+  resolution, SEO metadata, JSON-LD, feeds, nav, personalization + A/B, the
+  front-edit overlay) lives in **\`@kywi-software/core/next\`** and upgrades with
+  the package, so \`pnpm up @kywi-software/core\` reaches it. \`lib/kywi.ts\` is
+  the one wiring point between the two. **Never paste render logic back into
+  these files** — extend through \`lib/modules.tsx\`, \`kywi.config.ts\`,
+  \`app/(site)/site.css\` and \`components/site-nav.tsx\` instead.`)
   } else {
     bullets.push(
       a.mode === 'decoupled'
@@ -3137,8 +1881,10 @@ export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
     )
   }
   if (L.middleware) {
-    bullets.push(`- \`middleware.ts\` — auth gate + session refresh, thin wiring over
-  \`@kywi-software/core/host\`.`)
+    bullets.push(`- \`middleware.ts\` — auth gate + session refresh. In a project scaffolded
+  since the layered render path it is a one-line re-export of
+  \`@kywi-software/core/next/middleware\`; older projects hold their own copy
+  over \`@kywi-software/core/host\`.`)
   }
   bullets.push(`- \`.claude/skills/kywi-content-model/SKILL.md\` — content-model planning
   skill, loaded automatically before building anything.`)
@@ -3245,12 +1991,19 @@ export function buildFileSet(answers) {
     // mode so this stays byte-identical to the pre-landmark implementation; the
     // same guidanceFileSet powers `create-kywi-app agents` for existing projects.
     ...guidanceFileSet(answers, scaffoldLandmarks(answers.mode)),
-    // server runtime + config
+    // The render path's ONE config seam — thin, stamped, upgradeable
+    // (RENDER_LANDMARK_PATHS.runtime).
     'lib/kywi.ts': libKywi(),
-    'lib/config.ts': libConfig(),
     // custom (defineModule) module renderers, shared by admin + public layout (#48)
     'lib/modules.tsx': libModules(),
-    // host wiring (thin, over @kywi-software/core/host)
+    // 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(),
     'app/api/v1/[...kywi]/route.ts': apiRoute(),
     // root
@@ -3272,26 +2025,21 @@ export function buildFileSet(answers) {
   if (answers.mode === 'coupled') {
     // Public site: an optional catch-all renders "/" (home) and every published
     // page at its slug. More-specific /admin and /api routes take precedence.
-    files['app/(site)/layout.tsx'] = siteLayout(answers)
+    // Both files are thin, stamped delegates over @kywi-software/core/next
+    // (RENDER_LANDMARK_PATHS) — the render path itself is core's, so
+    // `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()
     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
     // the (Server Component) site layout above must render it through here
     // rather than looking it up directly (see siteNavComponent's doc comment).
+    // Core ships an identical default; this stays project-owned, and wired
+    // explicitly, because the header nav is the thing a site restyles first.
     files['components/site-nav.tsx'] = siteNavComponent()
     files['app/(site)/[[...slug]]/page.tsx'] = siteSlugPage()
-    // Public-render helpers: path/locale resolution, feed + component resolvers,
-    // personalization + experiments.
-    files['lib/site.ts'] = libSite()
-    // Shared /kywi.js script-injection primitive (kywi-cms#114) — the site
-    // layout's nav loader and the personalization runtime below both use it,
-    // so loading the bundle for either reason never double-loads it.
-    files['lib/kywi-js-loader.ts'] = kywiJsLoaderLib()
-    files['components/kywi-js-loader.tsx'] = kywiJsLoaderComponent()
-    // Optional client personalization runtime (self-ID widget, live re-eval). #50
-    files['components/personalization-runtime.tsx'] = personalizationRuntime()
-    // Front-of-site edit overlay (?kywi-edit=1), mounted by the page above.
-    files['app/(site)/kywi-front-edit.tsx'] = frontEditOverlay()
     // Syncs the admin stylesheet + a cache-busting version marker into
     // public/ on every predev/prebuild — see the doc comment on
     // syncKywiAdminCssScript and packageJson's syncScripts.