create-kywi-app 0.1.0

package/lib/templates.mjs

@@ -0,0 +1,1384 @@
+/**
+ * File templates for a scaffolded Kywi app.
+ *
+ * Each factory takes the resolved answers and returns file content. Kept as a
+ * plain data module (no deps) so the generator stays dependency-free and easy to
+ * unit test — buildFileSet() returns the exact map of path → content that the
+ * CLI writes, which is what the tests assert against.
+ *
+ * A generated project boots and works as documented with ZERO manual edits:
+ * `pnpm install && pnpm migrate && pnpm seed && pnpm dev` gives a working admin
+ * at /admin (log in with the seeded credentials, create + publish a page) and,
+ * in coupled mode, a public site that renders published pages at their slug.
+ *
+ * The three deployment modes differ only in the public surface:
+ *   - coupled:   renders the public site (app/(site)) AND serves the admin + API.
+ *   - headless:  admin + API only — GET / returns 404, no public rendering.
+ *   - decoupled: admin + API only — a SEPARATE frontend consumes the API via
+ *                @kywi-software/sdk (see the generated README).
+ * The admin (/admin) and API (/api/v1) are identical across all three modes.
+ *
+ * The security-critical session plumbing (JWT verify, httpOnly cookie contract,
+ * cookie→bearer bridge) is NOT copied into every project: it lives once in
+ * @kywi-software/core/host (+ /host-client) and the generated middleware.ts and
+ * API route are thin framework wiring over those primitives, so a `kywi` upgrade
+ * ships session fixes without the app hand-maintaining crypto.
+ */
+
+/** @typedef {{ projectName: string, dbProvider: 'postgresql'|'mysql', authProviders: string[], mode: 'coupled'|'headless'|'decoupled', kywiVersion: string }} Answers */
+
+const CORE_RANGE = (v) => `^${v}`
+
+// ── package.json ──────────────────────────────────────────────────────────────
+
+/** @param {Answers} a */
+function packageJson(a) {
+  return JSON.stringify(
+    {
+      name: a.projectName,
+      version: '0.1.0',
+      private: true,
+      type: 'module',
+      scripts: {
+        dev: 'next dev',
+        build: 'next build',
+        start: 'next start',
+        migrate: 'kywi migrate --push',
+        seed: 'kywi seed',
+      },
+      dependencies: {
+        '@kywi-software/core': CORE_RANGE(a.kywiVersion),
+        '@kywi-software/cli': CORE_RANGE(a.kywiVersion),
+        next: '^15.0.0',
+        react: '^19.0.0',
+        'react-dom': '^19.0.0',
+        // Server-side image processing used by core's media pipeline. Listed in
+        // next.config's serverExternalPackages, so it must be installed.
+        sharp: '^0.34.0',
+      },
+      devDependencies: {
+        '@types/node': '^20.0.0',
+        '@types/react': '^19.0.0',
+        '@types/react-dom': '^19.0.0',
+        // `kywi migrate` shells out to drizzle-kit against the schema generated
+        // into kywi-generated/. They must be present in THIS project's
+        // node_modules for `node_modules/.bin/drizzle-kit` to resolve.
+        'drizzle-kit': '^0.28.0',
+        'drizzle-orm': '^0.38.0',
+        // The kywi CLI loads your TypeScript kywi.config.ts via the tsx loader.
+        tsx: '^4.19.0',
+        typescript: '^5.5.0',
+      },
+      // Let pnpm run the native build steps these packages need without an
+      // interactive approval prompt (no-op for npm/yarn).
+      pnpm: {
+        onlyBuiltDependencies: ['esbuild', 'sharp'],
+      },
+    },
+    null,
+    2,
+  ) + '\n'
+}
+
+// ── kywi.config.ts ────────────────────────────────────────────────────────────
+
+/** @param {Answers} a */
+function kywiConfig(a) {
+  const providers = a.authProviders.map((p) => `'${p}'`).join(', ')
+  return `import { defineKywiConfig, defineSite, defineTheme } from '@kywi-software/core/config'
+import { assertProductionAuthSecret } from '@kywi-software/core/host'
+
+// Refuse to build/start in production with a missing or dev-fallback AUTH_SECRET
+// (tokens signed with a publicly-known default are forgeable). No-op in
+// development, so \`pnpm dev\` stays frictionless. Runs whenever this config is
+// imported — by the app at build/boot and by the CLI (migrate/seed).
+assertProductionAuthSecret(process.env.AUTH_SECRET)
+
+/**
+ * Kywi configuration — the single source of truth for this project.
+ * Docs: https://kywi.dev/docs/config
+ */
+export default defineKywiConfig({
+  // Deployment mode:
+  //   'coupled'   — this app renders the public site AND serves the API + admin.
+  //   'headless'  — API + admin only; no public rendering (GET / is 404).
+  //   'decoupled' — API + admin here; a separate frontend consumes @kywi-software/sdk.
+  mode: '${a.mode}',
+
+  db: {
+    provider: '${a.dbProvider}',
+    url: process.env.DATABASE_URL ?? 'postgres://localhost:5432/${slugify(a.projectName)}',
+  },
+
+  auth: {
+    // NEVER ship the fallback secret to production — set AUTH_SECRET in the env.
+    secret: process.env.AUTH_SECRET ?? 'dev-secret-change-in-production',
+    providers: [${providers}],
+  },
+
+  sites: [
+    defineSite({
+      id: 'default',
+      name: '${a.projectName}',
+      domain: 'localhost',
+      defaultLocale: 'en',
+      theme: 'default',
+    }),
+  ],
+
+  themes: [
+    defineTheme({
+      name: 'default',
+      regions: [
+        { name: 'header', label: 'Header' },
+        { name: 'main', label: 'Main Content' },
+        { name: 'footer', label: 'Footer' },
+      ],
+    }),
+  ],
+
+  // Content types you can author in the admin. "Page" ships by default so a
+  // fresh site can create and publish pages immediately; add your own here
+  // (blog posts, events, …) and re-run \`pnpm migrate\`.
+  contentTypes: [
+    {
+      name: 'page',
+      label: 'Page',
+      baseType: 'content',
+      fields: [],
+    },
+  ],
+})
+`
+}
+
+// ── tsconfig.json ─────────────────────────────────────────────────────────────
+
+function tsconfig() {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        lib: ['dom', 'dom.iterable', 'ES2022'],
+        module: 'ESNext',
+        moduleResolution: 'Bundler',
+        strict: true,
+        noEmit: true,
+        esModuleInterop: true,
+        jsx: 'preserve',
+        incremental: true,
+        skipLibCheck: true,
+        plugins: [{ name: 'next' }],
+        paths: { '@/*': ['./*'] },
+      },
+      include: ['**/*.ts', '**/*.tsx', '.next/types/**/*.ts'],
+      exclude: ['node_modules'],
+    },
+    null,
+    2,
+  ) + '\n'
+}
+
+// ── next.config.mjs ───────────────────────────────────────────────────────────
+
+function nextConfig() {
+  return `import { createRequire } from 'node:module'
+
+// require() is needed for require.resolve() of the local dompurify stub below.
+const require = createRequire(import.meta.url)
+
+/**
+ * Next.js config for a Kywi app. Every setting here is required to consume
+ * @kywi-software/core; removing any of them breaks the build:
+ *
+ *  - transpilePackages: core ships TypeScript/TSX source, transpiled in-app.
+ *  - extensionAlias:    core imports use the TS-ESM \`.js\` convention; webpack
+ *                       must resolve those specifiers to the real \`.ts\`/\`.tsx\`.
+ *  - serverExternalPackages: core's server deps (sharp, drizzle, postgres, …)
+ *                       stay server-side and out of the client bundle.
+ *  - isomorphic-dompurify stub: jsdom fails when webpack bundles it on the
+ *                       server, and its CJS/ESM interop breaks client transpile;
+ *                       the stub passes content through (sanitisation is
+ *                       defense-in-depth — CMS-authored content is trusted).
+ */
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@kywi-software/core'],
+  serverExternalPackages: [
+    'sharp',
+    'drizzle-orm',
+    'postgres',
+    'nodemailer',
+    'bcryptjs',
+    '@aws-sdk/client-s3',
+    'jsdom',
+    'isomorphic-dompurify',
+  ],
+  webpack(config) {
+    config.resolve.extensionAlias = {
+      ...config.resolve.extensionAlias,
+      '.js': ['.ts', '.tsx', '.js'],
+      '.jsx': ['.tsx', '.jsx'],
+    }
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      'isomorphic-dompurify': require.resolve('./lib/dompurify-stub.js'),
+    }
+    return config
+  },
+}
+
+export default nextConfig
+`
+}
+
+function dompurifyStub() {
+  return `/**
+ * Stub for isomorphic-dompurify used in both server and client webpack bundles.
+ * Server: isomorphic-dompurify uses jsdom, which fails when webpack bundles it.
+ * Client: its CJS/ESM interop breaks when @kywi-software/core is transpiled.
+ * This stub passes content through unchanged — DOMPurify sanitisation is
+ * defense-in-depth; CMS-authored content is trusted.
+ */
+const DOMPurify = {
+  sanitize: (dirty) => dirty,
+  addHook: () => {},
+  removeHook: () => {},
+  removeHooks: () => {},
+  removeAllHooks: () => {},
+  isValidAttribute: () => true,
+  setConfig: () => {},
+  clearConfig: () => {},
+}
+
+export default DOMPurify
+export const sanitize = DOMPurify.sanitize
+`
+}
+
+// ── env / gitignore ───────────────────────────────────────────────────────────
+
+function envExample() {
+  return `# Copy to .env and fill in. .env is gitignored.
+
+# PostgreSQL connection string. Create the database first: createdb my_db
+# Postgres 14 or newer works.
+DATABASE_URL=postgres://localhost:5432/CHANGE_ME
+
+# 32+ char random string. Generate: openssl rand -base64 32
+# Required in production — the app refuses to start without it.
+AUTH_SECRET=CHANGE_ME
+`
+}
+
+function gitignore() {
+  return `node_modules
+.next
+.env
+.env.local
+*.log
+`
+}
+
+// ── server runtime (lib/kywi.ts) ──────────────────────────────────────────────
+
+function libKywi() {
+  return `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 config from '../kywi.config'
+
+/**
+ * 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
+  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 first configured site (its \`id\` is the slug).
+  const sites = await scope.site.list()
+  const match = sites.find((s) => (s as { slug?: string }).slug === config.sites[0]?.id)
+  const siteId = (match?.['id'] as string | undefined) ?? config.sites[0]?.id ?? 'default'
+
+  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
+}
+`
+}
+
+function libConfig() {
+  return `/** Re-export the Kywi config for use throughout the app (single import path). */
+import config from '../kywi.config'
+export default config
+`
+}
+
+function libAdminAuth() {
+  return `/**
+ * Client-side admin helpers. Re-exported from @kywi-software/core/host-client so
+ * every admin surface imports them from one local path — swap the source here if
+ * you ever want to customise them.
+ */
+export {
+  adminFetch,
+  getAdminUser,
+  setAuth,
+  clearAuth,
+  signOut,
+  getActiveSiteId,
+  setActiveSiteId,
+  clearActiveSiteId,
+  type AdminUser,
+} from '@kywi-software/core/host-client'
+`
+}
+
+// ── middleware.ts (thin framework wiring over @kywi-software/core/host) ───────
+
+function middleware() {
+  return `import { NextResponse, type NextRequest } from 'next/server'
+import {
+  ACCESS_COOKIE,
+  REFRESH_COOKIE,
+  assertProductionAuthSecret,
+  classifyAccessToken,
+  setAccessCookie,
+  clearSessionCookies,
+} from '@kywi-software/core/host'
+
+/**
+ * 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.
+ */
+
+// 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'
+
+// 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')
+}
+
+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
+  }
+}
+
+export async function middleware(req: NextRequest): Promise<NextResponse> {
+  const { pathname } = req.nextUrl
+  if (isAuthEndpoint(pathname)) return NextResponse.next()
+
+  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
+  }
+
+  // /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
+  }
+
+  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*'],
+}
+`
+}
+
+// ── root layout + public site ────────────────────────────────────────────────
+
+function rootLayout() {
+  return `import React from 'react'
+
+export const metadata = {
+  title: 'Kywi CMS',
+  description: 'Built with Kywi',
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0, fontFamily: 'system-ui, -apple-system, sans-serif' }}>{children}</body>
+    </html>
+  )
+}
+`
+}
+
+/** @param {Answers} a — coupled public site shell. */
+function siteLayout(a) {
+  return `import React from 'react'
+
+/**
+ * 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.
+ */
+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>
+      </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>
+        </div>
+      </footer>
+    </div>
+  )
+}
+`
+}
+
+/** Coupled catch-all: renders home ("/") and any published page at its slug. */
+function siteSlugPage() {
+  return `import React from 'react'
+import { notFound } from 'next/navigation'
+import { KywiBody } from '@kywi-software/core/scope-client'
+import { getKywi } from '../../../lib/kywi'
+
+// 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) {
+  const { slug } = await params
+  const { scope, siteId } = await getKywi()
+  const target = slug && slug.length > 0 ? slug[slug.length - 1]! : 'home'
+
+  const node = (await scope.content.getBySlug(target, siteId)) as Record<string, unknown> | null
+  if (!node || node['status'] !== 'published') notFound()
+
+  const title = String(node['title'] ?? 'Untitled')
+  const body = (node['body'] as string) || ''
+
+  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>
+  )
+}
+`
+}
+
+/** @param {Answers} a — headless/decoupled root page (no public rendering). */
+function headlessHomePage(a) {
+  const note =
+    a.mode === 'decoupled'
+      ? 'This is a DECOUPLED deployment — build your frontend separately with @kywi-software/sdk and point it at /api/v1. See README.md.'
+      : 'This is a HEADLESS deployment — there is no public frontend. Use /admin and /api/v1.'
+  return `import { notFound } from 'next/navigation'
+
+// ${a.mode === 'decoupled' ? 'Decoupled' : 'Headless'} mode: no public rendering.
+// ${note}
+export default function HomePage() {
+  notFound()
+}
+`
+}
+
+// ── API route (thin proxy over @kywi-software/core/host) ──────────────────────
+
+function apiRoute() {
+  return `import { NextRequest, NextResponse } from 'next/server'
+import { getKywiHandler } from '../../../../lib/kywi'
+import {
+  TOKEN_ISSUING_PATHS,
+  parseSessionTokens,
+  setAccessCookie,
+  setRefreshCookie,
+  clearSessionCookies,
+} from '@kywi-software/core/host'
+
+/**
+ * The versioned Kywi API. Delegates every verb to core's DB-backed handler, with
+ * a thin session-cookie bridge on top: this route ESTABLISHES the session by
+ * lifting the tokens a login/refresh RESPONSE returns into httpOnly cookies (so
+ * an XSS payload can never read them), and clears them on logout. The read/
+ * 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 (TOKEN_ISSUING_PATHS.has(path) && res.ok) {
+    const bodyText = await res.text()
+    const { accessToken, refreshToken } = parseSessionTokens(bodyText)
+    const out = new NextResponse(bodyText, { status: res.status, headers: res.headers })
+    if (accessToken) setAccessCookie(out, accessToken)
+    if (refreshToken) setRefreshCookie(out, refreshToken)
+    return out
+  }
+
+  return res
+}
+
+export const GET = handleRequest
+export const POST = handleRequest
+export const PUT = handleRequest
+export const PATCH = handleRequest
+export const DELETE = handleRequest
+
+export const dynamic = 'force-dynamic'
+`
+}
+
+// ── admin ─────────────────────────────────────────────────────────────────────
+
+function adminLayout() {
+  return `import React from 'react'
+
+// Pass-through: the root layout provides <html>/<body>; admin pages bring their
+// own chrome (AdminShell for authed pages, nothing extra for the login page).
+export default function AdminLayout({ children }: { children: React.ReactNode }) {
+  return <>{children}</>
+}
+`
+}
+
+function adminIndexPage() {
+  return `import { redirect } from 'next/navigation'
+
+export default function AdminIndexPage() {
+  redirect('/admin/content')
+}
+`
+}
+
+function adminShellComponent() {
+  return `'use client'
+
+import React, { useEffect, useState } from 'react'
+import { usePathname } from 'next/navigation'
+import '@kywi-software/core/admin/styles.css'
+import { getAdminUser, signOut, type AdminUser } from '../lib/admin-auth'
+
+/**
+ * Minimal admin chrome: a sidebar + top bar around the authed admin pages. The
+ * server middleware is the real access gate (a valid session cookie was already
+ * verified to reach here); this only loads the user descriptor for display and
+ * bounces to /admin/login if it's gone (e.g. signed out in another tab).
+ *
+ * Extend this as you grow the admin — it's your app's own layer over core's
+ * admin components (ContentEditForm etc.).
+ */
+const NAV = [
+  { href: '/admin/content', label: 'Content' },
+]
+
+export function AdminShell({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname()
+  const [user, setUser] = useState<AdminUser | null>(null)
+  const [checked, setChecked] = useState(false)
+
+  useEffect(() => {
+    const u = getAdminUser()
+    if (!u) {
+      window.location.href = '/admin/login'
+      return
+    }
+    setUser(u)
+    setChecked(true)
+  }, [])
+
+  async function handleSignOut() {
+    await signOut()
+    window.location.href = '/admin/login'
+  }
+
+  if (!checked) {
+    return (
+      <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', minHeight: '100vh' }}>
+        Loading…
+      </div>
+    )
+  }
+
+  return (
+    <div style={{ display: 'flex', minHeight: '100vh', background: '#f8fafc' }}>
+      <aside style={{ width: 220, background: '#0f172a', color: '#e2e8f0', padding: '1.25rem 0', flexShrink: 0 }}>
+        <div style={{ padding: '0 1.25rem 1rem', fontWeight: 700, fontSize: '1.0625rem' }}>Kywi Admin</div>
+        <nav>
+          {NAV.map((item) => {
+            const active = pathname === item.href || pathname.startsWith(item.href + '/')
+            return (
+              <a
+                key={item.href}
+                href={item.href}
+                style={{
+                  display: 'block',
+                  padding: '0.5rem 1.25rem',
+                  color: active ? '#fff' : '#cbd5e1',
+                  background: active ? '#1e293b' : 'transparent',
+                  textDecoration: 'none',
+                  fontSize: '0.9375rem',
+                }}
+              >
+                {item.label}
+              </a>
+            )
+          })}
+        </nav>
+      </aside>
+      <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
+        <header
+          style={{
+            display: 'flex',
+            justifyContent: 'flex-end',
+            alignItems: 'center',
+            gap: '1rem',
+            padding: '0.75rem 1.5rem',
+            borderBottom: '1px solid #e2e8f0',
+            background: '#fff',
+          }}
+        >
+          <a href="/" style={{ color: '#64748b', fontSize: '0.875rem', textDecoration: 'none' }}>View site ↗</a>
+          <span style={{ color: '#64748b', fontSize: '0.875rem' }}>{user?.role}</span>
+          <button type="button" onClick={handleSignOut} className="kywi-btn kywi-btn-secondary kywi-btn-sm">
+            Sign out
+          </button>
+        </header>
+        <main style={{ padding: '1.5rem', flex: 1 }}>{children}</main>
+      </div>
+    </div>
+  )
+}
+`
+}
+
+function adminLoginPage() {
+  return `'use client'
+
+import React, { useState } from 'react'
+import { setAuth } from '../../../lib/admin-auth'
+import '@kywi-software/core/admin/styles.css'
+
+/** Honor a safe internal ?next= (set by middleware.ts), else the content list. */
+function safeNext(): string {
+  const fallback = '/admin/content'
+  if (typeof window === 'undefined') return fallback
+  const next = new URLSearchParams(window.location.search).get('next')
+  if (next && next.startsWith('/admin/') && !next.startsWith('//') && next !== '/admin/login') {
+    return next
+  }
+  return fallback
+}
+
+export default function AdminLoginPage() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+    setLoading(true)
+    try {
+      const res = await fetch('/api/v1/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+      })
+      const body = await res.json()
+      if (!res.ok) {
+        setError(body.error?.message ?? 'Login failed')
+        return
+      }
+      if (!body.data?.user || !body.data?.accessToken) {
+        setError('This account requires an unsupported login step.')
+        return
+      }
+      // The token is set by the server as an httpOnly cookie; we keep only the
+      // (non-sensitive) user descriptor for rendering the chrome.
+      setAuth(body.data.user)
+      window.location.href = safeNext()
+    } catch {
+      setError('Network error — is the server running?')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="kywi-admin-shell kywi-admin-login">
+      <form onSubmit={handleSubmit} className="kywi-admin-login-card">
+        <div className="kywi-admin-login-brand">
+          <span aria-hidden="true" className="kywi-admin-login-dot" />
+          <h1>Kywi Admin</h1>
+        </div>
+        <p className="kywi-admin-login-subtitle">Sign in to your workspace</p>
+        {error && (
+          <div className="kywi-admin-callout kywi-admin-callout-danger" role="alert">
+            {error}
+          </div>
+        )}
+        <label className="kywi-admin-login-field">
+          <span className="kywi-admin-login-label">Email</span>
+          <input type="email" className="kywi-input" value={email} onChange={(e) => setEmail(e.target.value)} required autoFocus />
+        </label>
+        <label className="kywi-admin-login-field">
+          <span className="kywi-admin-login-label">Password</span>
+          <input type="password" className="kywi-input" value={password} onChange={(e) => setPassword(e.target.value)} required />
+        </label>
+        <button type="submit" disabled={loading} className="kywi-btn kywi-btn-primary kywi-admin-login-submit">
+          {loading ? 'Signing in…' : 'Sign in'}
+        </button>
+      </form>
+    </div>
+  )
+}
+`
+}
+
+/** Shared client helper (bundled into pages that import it): resolve a content
+ * type by name from config + the built-ins. Emitted as a lib file. */
+function libContentTypes() {
+  return `import type { ContentTypeConfig } from '@kywi-software/core/config'
+import config from './config'
+
+/** Built-in types always available in the editor even if not in kywi.config.ts. */
+export const BUILT_IN_CONTENT_TYPES: ContentTypeConfig[] = [
+  { name: 'page', label: 'Page', baseType: 'content', fields: [] },
+  { name: 'folder', label: 'Folder', baseType: 'folder', fields: [] },
+  { name: 'link', label: 'Link', baseType: 'link', fields: [] },
+]
+
+/** All content types the admin can author: config-defined win over built-ins by name. */
+export function allContentTypes(): ContentTypeConfig[] {
+  const byName = new Map<string, ContentTypeConfig>()
+  for (const ct of BUILT_IN_CONTENT_TYPES) byName.set(ct.name, ct)
+  for (const ct of config.contentTypes) byName.set(ct.name, ct)
+  return [...byName.values()]
+}
+
+export function resolveContentType(name: string): ContentTypeConfig | null {
+  return allContentTypes().find((ct) => ct.name === name) ?? null
+}
+`
+}
+
+function adminContentLandingPage() {
+  return `'use client'
+
+import React from 'react'
+import { useRouter } from 'next/navigation'
+import { AdminShell } from '../../../components/admin-shell'
+import { allContentTypes } from '../../../lib/content-types'
+
+// Pick a content type to browse/author. Types come from kywi.config.ts plus the
+// always-available built-ins (page/folder/link).
+export default function ContentLandingPage() {
+  const router = useRouter()
+  const types = allContentTypes()
+
+  return (
+    <AdminShell>
+      <h1 style={{ margin: '0 0 1.5rem', fontSize: '1.25rem', fontWeight: 600 }}>Content</h1>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))', gap: '1rem' }}>
+        {types.map((ct) => (
+          <button
+            key={ct.name}
+            onClick={() => router.push('/admin/content/' + ct.name)}
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              alignItems: 'flex-start',
+              padding: '1.25rem',
+              background: '#fff',
+              border: '1px solid #e2e8f0',
+              borderRadius: 8,
+              cursor: 'pointer',
+              textAlign: 'left',
+            }}
+          >
+            <span style={{ fontSize: '1rem', fontWeight: 600, color: '#1e293b' }}>{ct.label}</span>
+            <span style={{ fontSize: '0.8125rem', color: '#64748b', marginTop: '0.25rem' }}>
+              {ct.fields.length} custom field{ct.fields.length !== 1 ? 's' : ''}
+            </span>
+          </button>
+        ))}
+      </div>
+    </AdminShell>
+  )
+}
+`
+}
+
+function adminContentListPage() {
+  return `'use client'
+
+import React, { useEffect, useState } from 'react'
+import { useParams, useRouter } from 'next/navigation'
+import { AdminShell } from '../../../../components/admin-shell'
+import { adminFetch } from '../../../../lib/admin-auth'
+import { resolveContentType } from '../../../../lib/content-types'
+
+interface Row {
+  id: string
+  title?: string
+  slug?: string
+  path?: string
+  status?: string
+}
+
+export default function ContentListPage() {
+  const params = useParams<{ type: string }>()
+  const router = useRouter()
+  const typeName = params.type
+  const contentType = resolveContentType(typeName)
+  const [rows, setRows] = useState<Row[] | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    adminFetch('/api/v1/content/' + typeName)
+      .then((res) => (res.ok ? res.json() : { data: [] }))
+      .then((body) => {
+        if (!cancelled) setRows((body?.data ?? []) as Row[])
+      })
+      .catch(() => {
+        if (!cancelled) setRows([])
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [typeName])
+
+  return (
+    <AdminShell>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '1.5rem' }}>
+        <h1 style={{ margin: 0, fontSize: '1.25rem', fontWeight: 600 }}>{contentType?.label ?? typeName}</h1>
+        <button className="kywi-btn kywi-btn-primary" onClick={() => router.push('/admin/content/' + typeName + '/new')}>
+          + New {contentType?.label ?? typeName}
+        </button>
+      </div>
+      {rows === null ? (
+        <p style={{ color: '#64748b' }}>Loading…</p>
+      ) : rows.length === 0 ? (
+        <p style={{ color: '#64748b' }}>Nothing here yet. Create your first {contentType?.label ?? typeName}.</p>
+      ) : (
+        <div className="kywi-table-scroll" style={{ background: '#fff', border: '1px solid #e2e8f0', borderRadius: 8 }}>
+          <table className="kywi-table" style={{ width: '100%' }}>
+            <thead>
+              <tr>
+                <th>Title</th>
+                <th>Slug</th>
+                <th>Status</th>
+                <th />
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((r) => (
+                <tr key={r.id}>
+                  <td>
+                    <a href={'/admin/content/' + typeName + '/' + r.id}>{r.title || '(untitled)'}</a>
+                  </td>
+                  <td>{r.slug}</td>
+                  <td>
+                    {r.status && <span className={'kywi-status-badge kywi-status-' + r.status}>{r.status}</span>}
+                  </td>
+                  <td style={{ textAlign: 'right' }}>
+                    {r.status === 'published' && r.path && (
+                      <a href={r.path} target="_blank" rel="noreferrer" style={{ fontSize: '0.875rem' }}>
+                        View ↗
+                      </a>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </AdminShell>
+  )
+}
+`
+}
+
+function adminContentNewPage() {
+  return `'use client'
+
+import React, { useState } from 'react'
+import { useParams, useRouter } from 'next/navigation'
+import { AdminShell } from '../../../../../components/admin-shell'
+import { ContentEditForm, buildWritablePayload } from '@kywi-software/core/admin'
+import { adminFetch } from '../../../../../lib/admin-auth'
+import { resolveContentType } from '../../../../../lib/content-types'
+
+export default function ContentNewPage() {
+  const params = useParams<{ type: string }>()
+  const router = useRouter()
+  const typeName = params.type
+  const contentType = resolveContentType(typeName)
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  if (!contentType) {
+    return (
+      <AdminShell>
+        <h1>Content type "{typeName}" not found</h1>
+        <p>It is not defined in kywi.config.ts.</p>
+      </AdminShell>
+    )
+  }
+
+  const fieldNames = contentType.fields.map((f) => f.name)
+
+  async function handleSubmit(data: Record<string, unknown>) {
+    setIsSubmitting(true)
+    setError(null)
+    try {
+      const payload = buildWritablePayload(data, fieldNames)
+      const res = await adminFetch('/api/v1/content/' + typeName, {
+        method: 'POST',
+        body: JSON.stringify(payload),
+      })
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}))
+        throw new Error(body.error?.message ?? 'HTTP ' + res.status)
+      }
+      const created = await res.json()
+      const id = created.data?.id ?? created.id
+      router.push(id ? '/admin/content/' + typeName + '/' + id : '/admin/content/' + typeName)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to create content')
+      setIsSubmitting(false)
+    }
+  }
+
+  return (
+    <AdminShell>
+      <div style={{ marginBottom: '1rem' }}>
+        <button className="kywi-btn kywi-btn-ghost kywi-btn-sm" onClick={() => router.push('/admin/content/' + typeName)}>
+          ← {contentType.label}
+        </button>
+      </div>
+      {error && (
+        <div className="kywi-admin-callout kywi-admin-callout-danger" style={{ marginBottom: '1rem' }}>
+          {error}
+        </div>
+      )}
+      <ContentEditForm
+        contentType={contentType}
+        mode="create"
+        isSubmitting={isSubmitting}
+        onSubmit={handleSubmit}
+        onCancel={() => router.push('/admin/content/' + typeName)}
+      />
+    </AdminShell>
+  )
+}
+`
+}
+
+function adminContentEditPage() {
+  return `'use client'
+
+import React, { useEffect, useState } from 'react'
+import { useParams, useRouter } from 'next/navigation'
+import { AdminShell } from '../../../../../components/admin-shell'
+import { ContentEditForm, buildWritablePayload, mapContentToInitialValues } from '@kywi-software/core/admin'
+import { adminFetch } from '../../../../../lib/admin-auth'
+import { resolveContentType } from '../../../../../lib/content-types'
+
+export default function ContentEditPage() {
+  const params = useParams<{ type: string; id: string }>()
+  const router = useRouter()
+  const typeName = params.type
+  const id = params.id
+  const contentType = resolveContentType(typeName)
+  const [node, setNode] = useState<Record<string, unknown> | null>(null)
+  const [loaded, setLoaded] = useState(false)
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    adminFetch('/api/v1/content/' + typeName + '/' + id)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((body) => {
+        if (cancelled) return
+        setNode((body?.data ?? null) as Record<string, unknown> | null)
+        setLoaded(true)
+      })
+      .catch(() => {
+        if (!cancelled) setLoaded(true)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [typeName, id])
+
+  if (!contentType) {
+    return (
+      <AdminShell>
+        <h1>Content type "{typeName}" not found</h1>
+      </AdminShell>
+    )
+  }
+
+  if (!loaded) {
+    return (
+      <AdminShell>
+        <p style={{ color: '#64748b' }}>Loading…</p>
+      </AdminShell>
+    )
+  }
+
+  if (!node) {
+    return (
+      <AdminShell>
+        <h1>Not found</h1>
+        <p>This content no longer exists.</p>
+      </AdminShell>
+    )
+  }
+
+  const fieldNames = contentType.fields.map((f) => f.name)
+  const status = String(node['status'] ?? 'draft')
+  const path = node['path'] as string | undefined
+
+  async function patch(payload: Record<string, unknown>): Promise<Record<string, unknown> | null> {
+    const res = await adminFetch('/api/v1/content/' + typeName + '/' + id, {
+      method: 'PATCH',
+      body: JSON.stringify(payload),
+    })
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}))
+      throw new Error(body.error?.message ?? 'HTTP ' + res.status)
+    }
+    const body = await res.json().catch(() => ({}))
+    return (body?.data ?? null) as Record<string, unknown> | null
+  }
+
+  async function handleSubmit(data: Record<string, unknown>) {
+    setIsSubmitting(true)
+    setError(null)
+    setNotice(null)
+    try {
+      const updated = await patch(buildWritablePayload(data, fieldNames))
+      if (updated) setNode(updated)
+      setNotice('Saved.')
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to save')
+    } finally {
+      setIsSubmitting(false)
+    }
+  }
+
+  // Publish/unpublish directly, so it works regardless of how you fill the form.
+  async function togglePublish() {
+    setError(null)
+    setNotice(null)
+    try {
+      const next = status === 'published' ? 'draft' : 'published'
+      const updated = await patch({ status: next })
+      if (updated) setNode(updated)
+      setNotice(next === 'published' ? 'Published.' : 'Unpublished.')
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to change status')
+    }
+  }
+
+  return (
+    <AdminShell>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '1rem', gap: '1rem' }}>
+        <button className="kywi-btn kywi-btn-ghost kywi-btn-sm" onClick={() => router.push('/admin/content/' + typeName)}>
+          ← {contentType.label}
+        </button>
+        <div style={{ display: 'flex', gap: '0.75rem', alignItems: 'center' }}>
+          <span className={'kywi-status-badge kywi-status-' + status}>{status}</span>
+          {status === 'published' && path && (
+            <a href={path} target="_blank" rel="noreferrer" className="kywi-btn kywi-btn-secondary kywi-btn-sm">
+              View ↗
+            </a>
+          )}
+          <button className="kywi-btn kywi-btn-primary kywi-btn-sm" onClick={togglePublish}>
+            {status === 'published' ? 'Unpublish' : 'Publish'}
+          </button>
+        </div>
+      </div>
+      {error && (
+        <div className="kywi-admin-callout kywi-admin-callout-danger" style={{ marginBottom: '1rem' }}>
+          {error}
+        </div>
+      )}
+      {notice && (
+        <div className="kywi-admin-callout" style={{ marginBottom: '1rem' }}>
+          {notice}
+        </div>
+      )}
+      <ContentEditForm
+        contentType={contentType}
+        mode="edit"
+        initialValues={mapContentToInitialValues(node)}
+        isSubmitting={isSubmitting}
+        onSubmit={handleSubmit}
+        onCancel={() => router.push('/admin/content/' + typeName)}
+      />
+    </AdminShell>
+  )
+}
+`
+}
+
+// ── README ────────────────────────────────────────────────────────────────────
+
+/** @param {Answers} a */
+function readme(a) {
+  const modeLine =
+    a.mode === 'coupled'
+      ? 'This app renders the public site and serves the API + admin.'
+      : a.mode === 'headless'
+        ? 'This is a headless deployment: API + admin only (GET / returns 404).'
+        : 'This is a decoupled deployment: the API + admin serve here; build your frontend separately with @kywi-software/sdk against /api/v1.'
+  const publicLine =
+    a.mode === 'coupled'
+      ? '- `http://localhost:3000/` — your public site (published pages render at their slug)'
+      : '- `http://localhost:3000/api/v1/content/page` — the content API'
+  const decoupledBlock =
+    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`
+      : ''
+  return `# ${a.projectName}
+
+A [Kywi CMS](https://kywi.dev) project (\`${a.mode}\` mode). ${modeLine}
+
+## Getting started
+
+\`\`\`bash
+# 1. Install dependencies
+pnpm install        # (or npm install / yarn)
+
+# 2. Create the database and configure the environment
+createdb ${slugify(a.projectName)}   # PostgreSQL 14+ works
+cp .env.example .env
+#   → set DATABASE_URL to your connection string
+#   → set AUTH_SECRET to a 32+ char random value (openssl rand -base64 32)
+
+# 3. Run migrations and seed the default site + admin user
+pnpm migrate        # applies the schema (see the note on NOTICEs below)
+pnpm seed           # prints the generated superadmin credentials
+
+# 4. Start the dev server
+pnpm dev            # http://localhost:3000
+\`\`\`
+
+Then open:
+- \`http://localhost:3000/admin\` — the admin UI. Sign in with the credentials
+  \`pnpm seed\` printed (default \`admin@kywi.dev\` / \`admin123\` unless you set
+  \`KYWI_ADMIN_EMAIL\` / \`KYWI_ADMIN_PASSWORD\`).
+${publicLine}
+${decoupledBlock}
+### Create your first page
+
+In the admin: **Content → Page → + New Page**, fill in a title and slug, save,
+then **Publish**.${a.mode === 'coupled' ? ' Open its slug (e.g. `/about`) to see it live.' : ' Fetch it from `/api/v1/content/page`.'}
+
+## Notes
+
+- **Migration NOTICEs are expected.** \`pnpm migrate\` prints PostgreSQL
+  \`NOTICE: identifier "..." will be truncated\` lines for a few long foreign-key
+  names. They are informational — the migration still applies cleanly.
+- **Config lives in \`kywi.config.ts\`** — sites, themes, content types, auth
+  providers and the deployment mode. Edit it (add content types, etc.) and
+  re-run \`pnpm migrate\`, then restart the dev server.
+
+## Project layout
+
+\`\`\`
+kywi.config.ts                    your config: sites, themes, content types, auth, mode
+middleware.ts                     auth gate + session refresh + cookie→bearer bridge
+next.config.mjs                   required Next config to consume @kywi-software/core
+lib/kywi.ts                       server runtime (DB, API handler, content scope)
+lib/admin-auth.ts                 client admin helpers (re-exported from core)
+app/api/v1/[...kywi]/route.ts     the versioned API (delegates to core)
+app/admin/…                       the admin UI (login + content authoring)
+components/admin-shell.tsx        your admin chrome${a.mode === 'coupled' ? '\napp/(site)/…                       your public site (renders published pages)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+\`\`\`
+`
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function slugify(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .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}'}`)
+}
+
+/**
+ * Build the complete map of relative-path → file-content for a project.
+ * @param {Answers} answers
+ * @returns {Record<string, string>}
+ */
+export function buildFileSet(answers) {
+  /** @type {Record<string, string>} */
+  const files = {
+    // config + build
+    'package.json': packageJson(answers),
+    'kywi.config.ts': kywiConfig(answers),
+    'tsconfig.json': tsconfig(),
+    'next.config.mjs': nextConfig(),
+    '.env.example': envExample(),
+    '.gitignore': gitignore(),
+    'README.md': readme(answers),
+    'lib/dompurify-stub.js': dompurifyStub(),
+    // server runtime + client helpers
+    'lib/kywi.ts': libKywi(),
+    'lib/config.ts': libConfig(),
+    'lib/admin-auth.ts': libAdminAuth(),
+    'lib/content-types.ts': libContentTypes(),
+    // host wiring (thin, over @kywi-software/core/host)
+    'middleware.ts': middleware(),
+    'app/api/v1/[...kywi]/route.ts': apiRoute(),
+    // root
+    'app/layout.tsx': rootLayout(),
+    // admin (all modes)
+    'components/admin-shell.tsx': adminShellComponent(),
+    'app/admin/layout.tsx': adminLayout(),
+    'app/admin/page.tsx': adminIndexPage(),
+    'app/admin/login/page.tsx': adminLoginPage(),
+    'app/admin/content/page.tsx': adminContentLandingPage(),
+    'app/admin/content/[type]/page.tsx': adminContentListPage(),
+    'app/admin/content/[type]/new/page.tsx': adminContentNewPage(),
+    'app/admin/content/[type]/[id]/page.tsx': adminContentEditPage(),
+  }
+
+  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)/[[...slug]]/page.tsx'] = siteSlugPage()
+  } else {
+    // headless + decoupled: no public rendering.
+    files['app/page.tsx'] = headlessHomePage(answers)
+  }
+
+  return files
+}
+
+export { slugify }