create-kywi-app 0.2.0 → 0.3.0

package/lib/templates.mjs

@@ -147,6 +147,31 @@ export default defineKywiConfig({
         { name: 'main', label: 'Main Content' },
         { name: 'footer', label: 'Footer' },
       ],
+      // Design tokens flow to the public site as \`:root { --kywi-* }\` CSS
+      // variables (the site layout emits them via \`themeTokenStyleBlock\`), and
+      // \`@kywi-software/core/site/styles.css\` styles every rendered element from
+      // them. Edit a value here → the whole site restyles, no CSS to touch.
+      // Naming: colors → --kywi-color-*, spacing → --kywi-spacing-*,
+      // typography → --kywi-font-*, borderRadius → --kywi-border-radius-*.
+      // See README → "Theming" for the full pipeline and \`key@breakpoint\` syntax.
+      tokens: {
+        colors: {
+          primary: '#2563eb',
+          'primary-contrast': '#ffffff',
+          text: '#0f172a',
+          heading: '#0f172a',
+          muted: '#64748b',
+          background: '#ffffff',
+          surface: '#f8fafc',
+          border: '#e2e8f0',
+        },
+        spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2.5rem' },
+        borderRadius: { sm: '6px', md: '10px', lg: '16px' },
+        typography: {
+          'family-base': 'system-ui, -apple-system, "Segoe UI", sans-serif',
+          'family-heading': 'system-ui, -apple-system, "Segoe UI", sans-serif',
+        },
+      },
     }),
   ],
 
@@ -241,6 +266,10 @@ function envExample() {
 
 # PostgreSQL connection string. Create the database first: createdb my_db
 # Postgres 14 or newer works.
+# No user:pass@ needed for local trust/peer auth (the default on most local
+# Postgres installs). If your Postgres requires a password (hosted DBs,
+# Docker images with POSTGRES_PASSWORD, etc.), add user:pass@, e.g.:
+#   postgres://user:pass@localhost:5432/mydb
 DATABASE_URL=postgres://localhost:5432/CHANGE_ME
 
 # 32+ char random string. Generate: openssl rand -base64 32
@@ -334,6 +363,419 @@ export default config
 `
 }
 
+// ── public-render helpers (lib/site.ts) ───────────────────────────────────────
+
+/**
+ * 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.
+ */
+function libSite() {
+  return `import { headers, cookies } from 'next/headers'
+import type {
+  LayoutDocument,
+  RegionNode,
+  ModuleNode,
+  FeedItemsResolver,
+  ComponentResolver,
+  PersonalizationState,
+} from '@kywi-software/core/layout'
+import { isLayoutSection, applyPageVariant } from '@kywi-software/core/layout'
+import { resolveContentByPath, normalizePath } from '@kywi-software/core/nav'
+import { getFeedBySlug, getComponentById, resolveLocaleFromRequest } from '@kywi-software/core'
+import { resolveComponentDefinition } from '@kywi-software/core/admin/server'
+import {
+  evaluateActiveAudiences,
+  getSelfIdWidgetConfig,
+  listSelfIdFields,
+  COOKIE_NAMES,
+} from '@kywi-software/core/audiences'
+import type {
+  Audience,
+  VisitorSignals,
+  SelfIdField,
+  SelfIdWidgetConfig,
+  SelfIdTrigger,
+} from '@kywi-software/core/audiences/types'
+import { listRunningExperiments, resolveExperimentForContainer } from '@kywi-software/core/experiments'
+import { getKywi, type KywiRuntime } from './kywi'
+import config from './config'
+
+/** 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) ────────────────────────────────────────────────────
+
+/** The active site's configured locales (the default is always included first). */
+export function siteLocales(): { defaultLocale: string; locales: string[] } {
+  const site = config.sites[0]
+  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 }
+}
+
+/**
+ * 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\`.
+ */
+export function resolveRequestLocale(
+  slugSegments: string[],
+  acceptLanguage?: string | null,
+): { locale: string; slugPath: string[] } {
+  const { defaultLocale, locales } = siteLocales()
+  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 }
+}
+
+/**
+ * hreflang alternates for a page across the site's configured locales, or
+ * undefined for a single-locale site. Feeds Next's \`alternates.languages\`.
+ */
+export function localeAlternates(slugSegments: string[]): Record<string, string> | undefined {
+  const { defaultLocale, locales } = siteLocales()
+  if (locales.length <= 1) return undefined
+  const { slugPath } = resolveRequestLocale(slugSegments, null)
+  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
+}
+
+// ─── 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'\`.
+ */
+export async function resolvePublicContent(
+  slugSegments: string[],
+  opts?: { acceptLanguage?: string | null },
+): Promise<ContentNode | null> {
+  const { scope, db, siteId } = await getKywi()
+  const { defaultLocale } = siteLocales()
+  const { locale, slugPath } = resolveRequestLocale(slugSegments, opts?.acceptLanguage)
+
+  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
+  }
+
+  // Home ("/"): the seeded root node (slug "home", path "/").
+  if (slugPath.length === 0) return bySlug('home')
+
+  // 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
+}
+
+// ─── Feed hydration (#28) ────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export function buildFeedResolver(runtime: KywiRuntime): FeedItemsResolver {
+  const { scope, db, siteId } = 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,
+    }))
+  }
+}
+
+// ─── Component resolver (#46) ────────────────────────────────────────────────
+
+function* moduleNodesInRegions(regions: Record<string, RegionNode[]>): Generator<ModuleNode> {
+  for (const nodes of Object.values(regions)) {
+    for (const node of nodes) {
+      if (isLayoutSection(node)) {
+        for (const col of node.columns) for (const m of col.nodes) yield m
+      } else {
+        for (const s of node.defaultSections) for (const col of s.columns) for (const m of col.nodes) yield m
+        for (const v of node.variants) for (const s of v.sections) for (const col of s.columns) for (const m of col.nodes) yield m
+      }
+    }
+  }
+}
+
+/**
+ * Prefetch every connected-component (\`componentId\`) referenced by the layout and
+ * return a synchronous {@link ComponentResolver} over that snapshot — the
+ * renderer resolves components during render, so they must be resolved up front.
+ * Returns undefined when the layout references no components (skip the prop).
+ */
+export async function buildComponentResolver(
+  layout: LayoutDocument,
+  runtime: KywiRuntime,
+): Promise<ComponentResolver | undefined> {
+  const ids = new Set<string>()
+  for (const node of moduleNodesInRegions(layout.regions)) {
+    if (node.componentId) ids.add(node.componentId)
+  }
+  if (ids.size === 0) return undefined
+  const { db, siteId } = runtime
+  const entries = await Promise.all(
+    [...ids].map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
+  )
+  const map = new Map(entries)
+  return (componentId) => resolveComponentDefinition(map.get(componentId) ?? null)
+}
+
+// ─── 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
+  /** 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)
+}
+
+/**
+ * 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.
+ */
+export async function resolvePersonalization(
+  runtime: KywiRuntime,
+  layout: LayoutDocument | null | undefined,
+): Promise<PublicPersonalization> {
+  const [h, cookieStore] = await Promise.all([headers(), cookies()])
+  const visitorId =
+    h.get('x-kywi-visitor') ?? cookieStore.get(COOKIE_NAMES.VISITOR)?.value ?? '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, siteId } = runtime
+  const { result, audiences } = await evaluateActiveAudiences(db, siteId, request)
+
+  const previewId = cookieStore.get(COOKIE_NAMES.PREVIEW_INIT)?.value || null
+  const audienceId = isActiveAudience(previewId, audiences) ? previewId : result.winningAudienceId
+
+  const experimentAssignments = await resolveExperimentAssignments(runtime, layout, audienceId, visitorId)
+
+  return {
+    personalization: { resolvedAudienceId: audienceId, experimentAssignments },
+    audienceId,
+    visitorId,
+    audiences,
+    signals: result.signals,
+  }
+}
+
+function* variantContainersInRegions(regions: Record<string, RegionNode[]>): Generator<RegionNode> {
+  for (const nodes of Object.values(regions)) {
+    for (const node of nodes) {
+      if (!isLayoutSection(node)) yield node
+    }
+  }
+}
+
+/**
+ * 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>.
+ */
+async function resolveExperimentAssignments(
+  runtime: KywiRuntime,
+  layout: LayoutDocument | null | undefined,
+  audienceId: string | null,
+  visitorId: string,
+): Promise<Record<string, string | null>> {
+  if (!layout) return {}
+  const resolved = applyPageVariant(layout, audienceId)
+  const experimentIds = new Set<string>()
+  for (const node of variantContainersInRegions(resolved.regions)) {
+    if (!isLayoutSection(node) && node.mode === 'ab_test' && !node.winnerId && node.experimentId) {
+      experimentIds.add(node.experimentId)
+    }
+  }
+  if (experimentIds.size === 0) return {}
+
+  const running = await listRunningExperiments(runtime.db, runtime.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)
+    assignments[id] = res.variantKey
+  }
+  return assignments
+}
+
+/**
+ * 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. variantContainer arms
+ * still resolve at render time from the threaded PersonalizationState.
+ */
+export function personalizeLayout(
+  layout: LayoutDocument,
+  audienceId: string | null,
+): LayoutDocument {
+  return applyPageVariant(layout, audienceId)
+}
+
+/** Is the @kywi-software/js client runtime enabled for this site's theme? */
+export function clientRuntimeEnabled(): boolean {
+  const themeName = config.sites[0]?.theme
+  const theme = config.themes.find((t) => t.name === themeName) ?? config.themes[0]
+  return theme?.personalization?.clientRuntime === true
+}
+
+// ─── 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?: string[]; required?: boolean }>
+  headline: string
+  subheadline?: string
+  submitLabel: string
+  skipLabel?: string
+  displayMode: 'modal' | 'inline' | 'slide-in'
+  frequency: 'once' | 'session' | 'always'
+  trigger: SelfIdTrigger
+}
+
+function mapDisplayMode(mode: SelfIdWidgetConfig['displayMode']): PublicSelfIdWidget['displayMode'] {
+  if (mode === 'modal') return 'modal'
+  if (mode === 'inline') return 'inline'
+  return 'slide-in' // hello bars + drawer both animate in from an edge
+}
+
+function mapFrequency(freq: SelfIdWidgetConfig['frequency']): PublicSelfIdWidget['frequency'] {
+  if (freq === 'once_visitor') return 'once'
+  if (freq === 'once_session') return 'session'
+  return 'always'
+}
+
+/**
+ * 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.
+ */
+export async function resolveSelfIdWidget(runtime: KywiRuntime): Promise<PublicSelfIdWidget | null> {
+  const [widget, allFields] = await Promise.all([
+    getSelfIdWidgetConfig(runtime.db, runtime.siteId),
+    listSelfIdFields(runtime.db, runtime.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,
+      options: f.picklist.map((p) => p.value),
+      required: f.required,
+    }))
+  if (fields.length === 0) return null
+
+  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,
+  }
+}
+`
+}
+
 // ── middleware.ts (thin framework wiring over @kywi-software/core/host) ───────
 
 function middleware() {
@@ -380,6 +822,32 @@ function isAuthEndpoint(pathname: string): boolean {
     !pathname.startsWith('/api/v1/auth/api-keys')
 }
 
+// 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()). Everything else passes through.
+ */
+function handlePublicRequest(req: NextRequest): NextResponse {
+  const existing = req.cookies.get(VISITOR_COOKIE)?.value
+  const visitorId = existing ?? crypto.randomUUID()
+  const headers = new Headers(req.headers)
+  headers.set('x-kywi-visitor', visitorId)
+  const res = NextResponse.next({ request: { headers } })
+  if (!existing) {
+    res.cookies.set(VISITOR_COOKIE, visitorId, { path: '/', maxAge: VISITOR_MAX_AGE, sameSite: 'lax' })
+  }
+  return res
+}
+
 async function fetchFreshAccessToken(origin: string, refreshToken: string): Promise<string | undefined> {
   try {
     const res = await fetch(origin + '/api/v1/auth/refresh', {
@@ -400,6 +868,11 @@ export async function middleware(req: NextRequest): Promise<NextResponse> {
   const { pathname } = req.nextUrl
   if (isAuthEndpoint(pathname)) return NextResponse.next()
 
+  // 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)
@@ -443,7 +916,14 @@ export async function middleware(req: NextRequest): Promise<NextResponse> {
 }
 
 export const config = {
-  matcher: ['/admin/:path*', '/api/v1/:path*'],
+  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/|.*\\\\..*).*)',
+  ],
 }
 `
 }
@@ -471,24 +951,48 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 /** @param {Answers} a — coupled public site shell. */
 function siteLayout(a) {
   return `import React from 'react'
+import { themeTokenStyleBlock } from '@kywi-software/core/layout'
+// 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 config from '../../kywi.config'
 
 /**
- * Public site shell. The header carries this project's name; edit freely — this
- * is your app's own layer over the DB-backed content that ${'app/(site)/[[...slug]]'} renders.
+ * 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 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.
  */
+const siteTheme =
+  config.themes.find((t) => t.name === config.sites[0]?.theme) ?? config.themes[0]
+const themeVars = themeTokenStyleBlock(siteTheme?.tokens)
+
 export default function SiteLayout({ children }: { children: React.ReactNode }) {
   return (
-    <div>
-      <header style={{ borderBottom: '1px solid #e2e8f0', background: '#fff' }}>
-        <div style={{ maxWidth: 960, margin: '0 auto', padding: '1rem', display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
-          <a href="/" style={{ fontWeight: 700, fontSize: '1.125rem', color: '#0f172a', textDecoration: 'none' }}>${escapeJsxText(a.projectName)}</a>
-          <a href="/admin" style={{ color: '#2563eb', textDecoration: 'none', fontSize: '0.9375rem' }}>Admin →</a>
+    <div className="site-shell">
+      {themeVars ? <style dangerouslySetInnerHTML={{ __html: themeVars }} /> : null}
+
+      <header className="site-header">
+        <div className="site-header__inner">
+          <a className="site-brand" href="/">${escapeJsxText(a.projectName)}</a>
+          <nav className="site-nav" aria-label="Primary">
+            <a className="site-nav__admin" href="/admin">Admin →</a>
+          </nav>
         </div>
       </header>
-      <main style={{ maxWidth: 720, margin: '0 auto', padding: '2.5rem 1rem' }}>{children}</main>
-      <footer style={{ borderTop: '1px solid #e2e8f0', marginTop: '3rem' }}>
-        <div style={{ maxWidth: 960, margin: '0 auto', padding: '1.5rem 1rem', color: '#64748b', fontSize: '0.875rem' }}>
-          Powered by <a href="https://kywi.dev" style={{ color: '#64748b' }}>Kywi CMS</a>
+
+      <main className="site-main">{children}</main>
+
+      <footer className="site-footer">
+        <div className="site-footer__inner">
+          Powered by <a href="https://kywi.dev">Kywi CMS</a>
         </div>
       </footer>
     </div>
@@ -497,41 +1001,489 @@ export default function SiteLayout({ children }: { children: React.ReactNode })
 `
 }
 
-/** Coupled catch-all: renders home ("/") and any published page at its slug. */
+/** @param {Answers} a — the app's OWN public-site chrome CSS (header/footer/page). */
+function siteStyles(a) {
+  return `/*
+ * ${a.projectName} — public-site chrome.
+ *
+ * This is YOUR stylesheet: the site header, footer, and page wrapper. It is a
+ * thin layer over @kywi-software/core/site/styles.css (imported alongside it in
+ * app/(site)/layout.tsx), which already styles everything Kywi RENDERS (prose,
+ * layout modules, forms, the edit overlay).
+ *
+ * Everything here reads the theme's --kywi-* design tokens (kywi.config.ts →
+ * themes[].tokens) with a neutral fallback, so editing a token restyles the
+ * whole site. Prefer changing a token over hardcoding a value here.
+ */
+
+.site-shell {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  color: var(--kywi-color-text, #0f172a);
+  background: var(--kywi-color-background, #ffffff);
+  font-family: var(--kywi-font-family-base, system-ui, -apple-system, sans-serif);
+}
+
+/* Header */
+.site-header {
+  border-bottom: 1px solid var(--kywi-color-border, #e2e8f0);
+  background: var(--kywi-color-background, #ffffff);
+}
+.site-header__inner {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: var(--kywi-spacing-md, 1rem);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.site-brand {
+  font-weight: 700;
+  font-size: 1.125rem;
+  color: var(--kywi-color-heading, #0f172a);
+  text-decoration: none;
+}
+.site-nav__admin {
+  color: var(--kywi-color-primary, #2563eb);
+  text-decoration: none;
+  font-size: 0.9375rem;
+}
+
+/* Main content column */
+.site-main {
+  flex: 1;
+  width: 100%;
+  max-width: 760px;
+  margin: 0 auto;
+  padding: var(--kywi-spacing-xl, 2.5rem) var(--kywi-spacing-md, 1rem);
+}
+
+/* A page rendered from the DB (title + body, or the full layout). */
+.page__title {
+  font-size: 2rem;
+  line-height: 1.15;
+  margin: 0 0 var(--kywi-spacing-lg, 1.5rem);
+  color: var(--kywi-color-heading, #0f172a);
+}
+.page__featured {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: var(--kywi-border-radius-md, 10px);
+  margin: 0 0 var(--kywi-spacing-lg, 1.5rem);
+}
+.page__empty { color: var(--kywi-color-muted, #64748b); }
+/* When a page is designed in the Layout tab it spans the full column. */
+.page--layout { max-width: none; }
+
+/* Footer */
+.site-footer {
+  border-top: 1px solid var(--kywi-color-border, #e2e8f0);
+  margin-top: var(--kywi-spacing-xl, 2.5rem);
+}
+.site-footer__inner {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: var(--kywi-spacing-lg, 1.5rem) var(--kywi-spacing-md, 1rem);
+  color: var(--kywi-color-muted, #64748b);
+  font-size: 0.875rem;
+}
+.site-footer__inner a { color: var(--kywi-color-muted, #64748b); }
+`
+}
+
+/** Coupled catch-all: renders home ("/") and any published page at its path. */
 function siteSlugPage() {
-  return `import React from 'react'
+  return `import React, { cache } from 'react'
+import type { Metadata } from 'next'
 import { notFound } from 'next/navigation'
-import { KywiBody } from '@kywi-software/core/scope-client'
+import { cookies, headers } from 'next/headers'
+import { KywiBody, KywiEditableAttribute, KywiEditableRegion } from '@kywi-software/core/scope-client'
+import { KywiLayout, KywiRegion, AudienceMetaTags, hydrateLayoutFeeds, 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 { getKywi } from '../../../lib/kywi'
+import {
+  resolvePublicContent,
+  resolvePersonalization,
+  personalizeLayout,
+  resolveSelfIdWidget,
+  clientRuntimeEnabled,
+  buildFeedResolver,
+  buildComponentResolver,
+  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[] }> }
-
-// "/" resolves the seeded Home node; any other path resolves the published node
-// whose slug is the last URL segment. Draft / missing content 404s.
-export default async function PublicPage({ params }: Params) {
+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 { scope, siteId } = await getKywi()
-  const target = slug && slug.length > 0 ? slug[slug.length - 1]! : 'home'
+  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 = 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,
+  )
+}
 
-  const node = (await scope.content.getBySlug(target, siteId)) as Record<string, unknown> | null
+// 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 is emitted for them.
+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') }
+}
+
+// "/" 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()
 
+  const runtime = await getKywi()
+  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
+
+  // ?kywi-edit=1 opts an authenticated admin into the front-of-site overlay.
+  const editRequested = (await searchParams)['kywi-edit'] === '1'
+  const perms = editRequested ? await resolveEditPermissions() : null
+
+  // 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)
+
+  // <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.
+  const baseUrl = await requestBaseUrl()
+  const head = (
+    <>
+      <meta name="kywi:content-id" content={contentId} />
+      <KywiJsonLd node={node} config={runtime.config} baseUrl={baseUrl} siteId={runtime.siteId} />
+      <AudienceMetaTags audienceId={perso.audienceId} visitorId={perso.visitorId} />
+      {clientRuntimeEnabled() && perso.audiences.length > 0 ? (
+        <PersonalizationRuntime
+          audiences={perso.audiences}
+          serverSignals={perso.signals}
+          selfIdWidget={selfIdWidget}
+        />
+      ) : 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 hydrated = await hydrateLayoutFeeds(personalized, buildFeedResolver(runtime))
+    const componentResolver = await buildComponentResolver(hydrated, runtime)
+    content = (
+      <article className="page page--layout" data-kywi-content-id={contentId}>
+        {head}
+        <KywiLayout
+          layout={hydrated}
+          personalization={perso.personalization}
+          moduleComponents={moduleComponents}
+          {...(componentResolver ? { componentResolver } : {})}
+        >
+          {Object.keys(hydrated.regions).map((name) => (
+            <KywiRegion key={name} name={name} />
+          ))}
+        </KywiLayout>
+      </article>
+    )
+  } else {
+    content = (
+      <article className="page" data-kywi-content-id={contentId}>
+        {head}
+        {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) only for an authenticated admin who asked for it.
+  if (perms) {
+    return (
+      <KywiFrontEdit
+        canEdit={perms.canEdit}
+        canPublish={perms.canPublish}
+        contentId={contentId}
+        pageTitle={title}
+        pageStatus={String(node['status'] ?? '')}
+        adminHref={\`/admin/content/\${contentType}/\${contentId}\`}
+      >
+        {content}
+      </KywiFrontEdit>
+    )
+  }
+
+  return content
+}
+`
+}
+
+/**
+ * Front-of-site edit overlay (client). Mounted by the public page ONLY for an
+ * authenticated admin who opened the page with ?kywi-edit=1 (the page verifies
+ * the session cookie server-side first). Surfaces core's KywiEditToolbar and
+ * enters edit mode, which outlines the editable regions core already marks with
+ * the `data-kywi-*` protocol. Real content edits happen in the full admin editor
+ * (the toolbar's Admin link deep-links to this page there); Publish posts to the
+ * API for admins with publish permission.
+ */
+function frontEditOverlay() {
+  return `'use client'
+import React from 'react'
+import { KywiEditToolbar, useKywiEditMode } from '@kywi-software/core/scope-client'
+import { adminFetch } from '@kywi-software/core/host-client'
+
+export interface KywiFrontEditProps {
+  canEdit: boolean
+  canPublish: boolean
+  contentId: string
+  pageTitle: string
+  pageStatus: string
+  /** Deep link to this page in the full admin editor. */
+  adminHref: string
+  children: React.ReactNode
+}
+
+/**
+ * Wraps the public page with the front-of-site edit affordance. The page only
+ * renders this for a signed-in admin who asked to edit (?kywi-edit=1), so the
+ * toolbar's own permission gate (canEdit) is always satisfied here.
+ */
+export function KywiFrontEdit({
+  canEdit,
+  canPublish,
+  contentId,
+  pageTitle,
+  pageStatus,
+  adminHref,
+  children,
+}: KywiFrontEditProps) {
+  const edit = useKywiEditMode({ canEdit, canPublish })
+
+  // ?kywi-edit=1 means "enter edit mode now" — flip it on once after mount.
+  const { startEdit } = edit
+  React.useEffect(() => {
+    startEdit()
+  }, [startEdit])
+
+  const handlePublish = React.useCallback(async () => {
+    const res = await adminFetch(\`/api/v1/content/by-id/\${contentId}/publish\`, { method: 'POST' })
+    if (res.ok) window.location.reload()
+  }, [contentId])
 
   return (
-    <article>
-      <h1 style={{ fontSize: '2rem', marginBottom: '1rem', color: '#0f172a' }}>{title}</h1>
-      {body ? <KywiBody content={body} /> : <p style={{ color: '#64748b' }}>This page has no content yet.</p>}
-    </article>
+    <>
+      <KywiEditToolbar
+        isEditMode={edit.isEditMode}
+        canEdit={edit.canEdit}
+        canPublish={edit.canPublish}
+        onToggleEdit={edit.toggleEdit}
+        onPublish={handlePublish}
+        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>
+    </>
   )
 }
 `
 }
 
+/**
+ * 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.
+ */
+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'
+
+/* 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
+}
+
+/**
+ * Loads /kywi.js and 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.
+ */
+export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget }: 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: audiences.map((a) => a.id), currentPath } }
+            : {}),
+        })
+        .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)
+    }
+
+    const existing = document.querySelector<HTMLScriptElement>('script[data-kywi-js]')
+    if (existing) {
+      if (ready()) boot()
+      else existing.addEventListener('load', whenReady)
+    } else {
+      const script = document.createElement('script')
+      script.src = '/kywi.js'
+      script.async = true
+      script.dataset.kywiJs = 'true'
+      script.addEventListener('load', whenReady)
+      document.body.appendChild(script)
+    }
+
+    return () => {
+      cancelled = true
+    }
+    // Boot once on mount; audiences/serverSignals are per-request stable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return null
+}
+`
+}
+
 /** @param {Answers} a — headless/decoupled root page (no public rendering). */
 function headlessHomePage(a) {
   const note =
@@ -548,6 +1500,33 @@ export default function HomePage() {
 `
 }
 
+// ── AX root routes (llms.txt / sitemap.xml / robots.txt / llms-full.txt) ──────
+
+/**
+ * @param {string} axPath — the AX filename core's handler serves (e.g. 'llms.txt').
+ * A thin root-level Route Handler that delegates to the SAME core AX generator
+ * the /api/v1/[axPath] catch-all uses, so the *core* generators stay the single,
+ * cache-aware, hook-invalidated source of truth. The Agent Experience surface
+ * advertises these at the ROOT (its robots.txt even emits `Sitemap:` / `# LLM
+ * index:` lines pointing at root URLs), but the scaffold previously mounted them
+ * only under /api/v1/* — so every advertised root URL 404'd (kywi-cms#55). These
+ * routes close that gap. `force-dynamic` because core owns caching (no
+ * double-caching at the edge); decoupled/headless consumers may still hit
+ * /api/v1/[axPath] directly.
+ */
+function axRootRoute(axPath) {
+  return `import { getKywiHandler } from '../../lib/kywi'
+
+/** Root-level \`/${axPath}\` — delegates to the core AX generator (kywi-cms#55). */
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request): Promise<Response> {
+  const handler = await getKywiHandler()
+  return handler.handle(req, ['${axPath}'])
+}
+`
+}
+
 // ── API route (thin proxy over @kywi-software/core/host) ──────────────────────
 
 function apiRoute() {
@@ -631,11 +1610,15 @@ function adminCatchAllPage() {
  * design-system tokens/inputs live there, so without it every surface (and the
  * login page) renders unstyled. Do not remove it.
  *
- * Server-side 404: before rendering, the segments are checked against the config
- * ceiling with the pure resolveSurface helper, calling Next's notFound() for a
- * true HTTP 404 on an unknown or config-disabled path. The \`login\` segment is
- * exempt (it is not a registry surface — the middleware's auth exception renders
- * it chrome-less through KywiAdminApp); the bare /admin index (segments === [])
+ * Server-side 404 (#58): the segments are resolved with the three-state
+ * resolveSurfaceState helper. Next's notFound() fires for a real HTTP 404 ONLY
+ * on a genuinely unknown path (status 'not-found'). A KNOWN surface held off by
+ * the config ceiling (status 'config-disabled') is NOT hard-404'd here — it
+ * falls through to KywiAdminApp, which renders the same in-shell "disabled"
+ * message a runtime-disabled surface gets, so both disable paths present
+ * consistently instead of hard-404 vs soft-hide. The \`login\` segment is exempt
+ * (not a registry surface — the middleware's auth exception renders it
+ * chrome-less through KywiAdminApp); the bare /admin index (segments === [])
  * resolves to the dashboard, so it never 404s.
  *
  * You should not need to edit this file. To disable surfaces per deployment, set
@@ -644,10 +1627,13 @@ function adminCatchAllPage() {
  */
 import { notFound } from 'next/navigation'
 import { KywiAdminApp } from '@kywi-software/core/admin/app'
-import { toAdminRuntimeConfig, resolveSurface } from '@kywi-software/core/admin/server'
+import { toAdminRuntimeConfig, resolveSurfaceState } from '@kywi-software/core/admin/server'
 // CRITICAL: load the admin design system once for the whole mount.
 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,
@@ -662,15 +1648,75 @@ export default async function AdminCatchAll({
 
   const runtime = toAdminRuntimeConfig(kywiConfig)
 
-  // Hard, server-side config ceiling → real HTTP 404. 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.
+  // 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 && resolveSurface(admin, runtime.admin) === null) {
+  if (!isLogin && resolveSurfaceState(admin, runtime.admin).status === 'not-found') {
     notFound()
   }
 
-  return <KywiAdminApp runtime={runtime} segments={admin} loginNext={next} />
+  return (
+    <KywiAdminApp
+      runtime={runtime}
+      segments={admin}
+      loginNext={next}
+      moduleComponents={moduleComponents}
+    />
+  )
+}
+`
+}
+
+// ── custom module renderers (lib/modules.tsx) ─────────────────────────────────
+
+/**
+ * The shared custom-module component map (kywi-cms#48). Imported by BOTH the
+ * admin host page (→ KywiAdminApp) and the public layout renderer (→ KywiLayout)
+ * so a `defineModule`-registered module resolves to the same component in the
+ * editor canvas and on the live site. Ships empty (built-ins need no entry) with
+ * a worked example, so the extension path is discoverable without docs-diving.
+ */
+function libModules() {
+  return `import type { ModuleComponentMap } from '@kywi-software/core/layout'
+
+/**
+ * Custom module renderers (kywi-cms#48).
+ *
+ * A module you register with \`defineModule\` in kywi.config.ts is authorable in
+ * the Layout editor, but the PUBLIC site (and the editor canvas) still need the
+ * React component that RENDERS it. Map each custom module's \`name\` → its
+ * component here; this map is passed to BOTH the admin (KywiAdminApp) and the
+ * public layout renderer (KywiLayout), so the module resolves to your component
+ * instead of an "Unknown module" placeholder everywhere. Built-in modules (hero,
+ * cards, CTA, testimonials, feed display, …) need no entry; an entry that reuses
+ * a built-in \`name\` overrides that built-in.
+ *
+ * Example — register a module in kywi.config.ts and render it here:
+ *
+ *   // kywi.config.ts
+ *   import { defineModule } from '@kywi-software/core/config'
+ *   // …inside defineKywiConfig({ … }):
+ *   //   modules: [
+ *   //     defineModule({ name: 'pricingTable', label: 'Pricing Table', component: 'pricingTable' }),
+ *   //   ],
+ *
+ *   // lib/pricing-table.tsx
+ *   'use client'
+ *   export function PricingTable({ props }: { props: Record<string, unknown> }) {
+ *     return <div className="pricing-table">{String(props.heading ?? '')}</div>
+ *   }
+ *
+ *   // here:
+ *   import { PricingTable } from './pricing-table'
+ *   export const moduleComponents: ModuleComponentMap = {
+ *     pricingTable: PricingTable,
+ *   }
+ */
+export const moduleComponents: ModuleComponentMap = {
+  // Add custom module renderers here, keyed by the \`name\` you gave defineModule.
 }
 `
 }
@@ -693,6 +1739,94 @@ function readme(a) {
     a.mode === 'decoupled'
       ? `\n### Separate frontend\n\nInstall \`@kywi-software/sdk\` in your frontend project and point it at this API:\n\n\`\`\`ts\nimport { createKywiSdk } from '@kywi-software/sdk'\nconst kywi = createKywiSdk({ baseUrl: 'http://localhost:3000/api/v1' })\n\`\`\`\n`
       : ''
+  // Theming only applies where THIS app renders the public site (coupled mode).
+  const themingBlock =
+    a.mode === 'coupled'
+      ? `
+## Theming
+
+The public site is styled entirely from **design tokens** you set on a theme in
+\`kywi.config.ts\`. No CSS editing required — change a token and the whole site
+restyles.
+
+\`\`\`ts
+defineTheme({
+  name: 'default',
+  regions: [/* … */],
+  tokens: {
+    colors:  { primary: '#2563eb', text: '#0f172a', border: '#e2e8f0', /* … */ },
+    spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2.5rem' },
+    borderRadius: { sm: '6px', md: '10px', lg: '16px' },
+    typography:   { 'family-base': 'system-ui, sans-serif' },
+    // Responsive override: a \`key@breakpoint\` suffix emits an @media rule.
+    // e.g. spacing: { 'lg@mobile': '1rem' }
+  },
+})
+\`\`\`
+
+**How it flows.** \`app/(site)/layout.tsx\` calls \`themeTokenStyleBlock(theme.tokens)\`
+and injects the result as a \`:root { --kywi-* }\` block. Every token becomes a CSS
+custom property under a predictable name:
+
+| Token category  | CSS variable            | Example                     |
+| --------------- | ----------------------- | --------------------------- |
+| \`colors\`        | \`--kywi-color-*\`        | \`--kywi-color-primary\`      |
+| \`spacing\`       | \`--kywi-spacing-*\`      | \`--kywi-spacing-lg\`         |
+| \`typography\`    | \`--kywi-font-*\`         | \`--kywi-font-family-base\`   |
+| \`borderRadius\`  | \`--kywi-border-radius-*\`| \`--kywi-border-radius-md\`   |
+| \`shadow\`        | \`--kywi-shadow-*\`       | \`--kywi-shadow-card\`        |
+
+Two stylesheets consume those variables (both imported in \`app/(site)/layout.tsx\`):
+
+- \`@kywi-software/core/site/styles.css\` — neutral, element-level defaults for
+  **everything Kywi renders**: prose, the layout-engine grid and modules (hero,
+  cards, CTA, testimonials, feed display, …), and embedded forms. Restyle it by
+  overriding tokens rather than editing rules.
+- \`app/(site)/site.css\` — **your** site chrome (header, footer, page wrapper).
+  Yours to edit; it reads the same \`--kywi-*\` variables with fallbacks.
+
+**Responsive tokens.** Suffix a token key with \`@breakpoint\` (\`mobile\`, \`tablet\`,
+\`desktop\`, or \`sm\`/\`md\`/\`lg\`/\`xl\`) and \`themeTokenStyleBlock\` emits the value inside
+the matching \`@media\` query.
+
+**Layout renderer.** A page designed in the admin's **Layout** tab is rendered on
+the public site through core's layout engine (\`KywiLayout\`/\`KywiRegion\`, already
+wired in \`app/(site)/[[...slug]]/page.tsx\`). Pages without a layout fall back to
+their Body rich text. Reach for the Layout tab when a page needs sections,
+columns, or modules; use the Body for simple prose.
+
+**Front-of-site editor.** Signed in as an admin, append \`?kywi-edit=1\` to any
+public page to get an edit toolbar (the \`app/(site)/kywi-front-edit.tsx\` overlay).
+
+## Personalization, A/B testing & self-ID
+
+Audiences, experiments and the self-ID widget you configure in the admin resolve
+**server-side** on every public request, with no extra setup:
+
+- **Audience-targeted content** — a page's audience variant (Layout tab) and any
+  audience \`variantContainer\` render for the winning audience.
+- **A/B experiments** — each visitor is assigned a variant arm deterministically
+  and the exposure is recorded. The assignment is stable because the
+  \`middleware.ts\` gives every visitor a persistent \`kywi_visitor\` id.
+- **Preview links** — an admin preview link sets \`kywi_preview_init\` and the page
+  honours it, so you can preview an audience's experience.
+
+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.
+
+## Locales
+
+Set \`locales\` on your site in \`kywi.config.ts\` (e.g. \`locales: ['en', 'es']\`),
+create translations in the admin, and they are reachable at a locale-prefixed URL
+(\`/es/pricing\`). Resolution order is URL prefix › \`Accept-Language\` › the site's
+\`defaultLocale\`, with a fallback to the default-locale row; \`generateMetadata\`
+emits \`hreflang\` alternates. A single-locale site needs no prefix.
+`
+      : ''
   return `# ${a.projectName}
 
 A [Kywi CMS](https://kywi.dev) project (\`${a.mode}\` mode). ${modeLine}
@@ -742,12 +1876,20 @@ to disable surfaces you don't want in this deployment (e.g. hide Forms or
 Audiences). SuperAdmins can also toggle surfaces at runtime from the
 **Admin Features** surface inside the admin — no redeploy needed.
 
+**Custom modules.** Register your own Layout-editor module with \`defineModule\`
+in \`kywi.config.ts\` (\`modules: [defineModule({ name: 'pricingTable', … })]\`),
+then map its \`name\` to the React component that renders it in \`lib/modules.tsx\`.
+That one map is passed to both the admin editor and the public site, so a custom
+module renders identically in the canvas and live (it shows an "Unknown module"
+placeholder until you add the entry). See the worked example in \`lib/modules.tsx\`.
+
 ### Create your first page
 
 In the admin, open **Site Tree** (or **Content**), create a new **Page**, enter a
 title (the slug is auto-generated from it — or type your own), then click
-**Create**. Open the new page and click **Publish**.${a.mode === 'coupled' ? ' The published page lives at `/<slug>` (e.g. a page with slug `about` is served at `/about`) — open it to see it live.' : ' Fetch it from `/api/v1/content/page`.'}
-
+**Create**. Open the new page, switch to the **Publishing** tab, set **Status**
+to **Published**, and click **Save**.${a.mode === 'coupled' ? ' The published page lives at `/<slug>` (e.g. a page with slug `about` is served at `/about`) — open it to see it live.' : ' Fetch it from `/api/v1/content/page`.'}
+${themingBlock}
 ## Notes
 
 - **Migration NOTICEs are expected.** \`pnpm migrate\` prints PostgreSQL
@@ -766,7 +1908,9 @@ next.config.mjs                   required Next config to consume @kywi-software
 lib/kywi.ts                       server runtime (DB, API handler, content scope)
 lib/config.ts                     single import path for kywi.config.ts
 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${a.mode === 'coupled' ? '\napp/(site)/…                       your public site (renders published pages)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+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/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site edit overlay (?kywi-edit=1)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
 \`\`\`
 `
 }
@@ -804,6 +1948,8 @@ export function buildFileSet(answers) {
     // server runtime + config
     '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)
     'middleware.ts': middleware(),
     'app/api/v1/[...kywi]/route.ts': apiRoute(),
@@ -812,13 +1958,30 @@ export function buildFileSet(answers) {
     'app/icon.svg': faviconSvg(),
     // admin (all modes): the FULL core admin (all surfaces) via one catch-all.
     'app/admin/[[...admin]]/page.tsx': adminCatchAllPage(),
+    // AX layer served at the ROOT paths the Agent Experience surface advertises
+    // (a crawler/agent follows /llms.txt, /sitemap.xml, /robots.txt — not the
+    // /api/v1/* prefix). Delegate to the same core generators (#55). Present in
+    // every mode: these are agent-facing projections of published content, not
+    // public HTML rendering.
+    'app/llms.txt/route.ts': axRootRoute('llms.txt'),
+    'app/llms-full.txt/route.ts': axRootRoute('llms-full.txt'),
+    'app/sitemap.xml/route.ts': axRootRoute('sitemap.xml'),
+    'app/robots.txt/route.ts': axRootRoute('robots.txt'),
   }
 
   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)
+    files['app/(site)/site.css'] = siteStyles(answers)
     files['app/(site)/[[...slug]]/page.tsx'] = siteSlugPage()
+    // Public-render helpers: path/locale resolution, feed + component resolvers,
+    // personalization + experiments.
+    files['lib/site.ts'] = libSite()
+    // 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()
   } else {
     // headless + decoupled: no public rendering.
     files['app/page.tsx'] = headlessHomePage(answers)