create-kywi-app 0.23.0 → 0.25.0

package/README.md

@@ -60,7 +60,7 @@ pages at their slug.
 
 ```
 package.json                       scripts (dev/build/start/migrate/seed) + deps incl. drizzle-kit + tsx
-kywi.config.ts                     defineKywiConfig/Site/Theme + a default "Page" content type
+kywi.config.ts                     defineKywiConfig/Site/Theme + a default "Page" content type in defineContentType
 tsconfig.json
 next.config.mjs                    the FULL config to consume core (transpilePackages, extensionAlias,
                                    serverExternalPackages) — every line is load-bearing
@@ -69,8 +69,15 @@ next.config.mjs                    the FULL config to consume core (transpilePac
 README.md                          project-specific quick start (createdb, migrate, seed, dev, /admin, admin.features)
 AGENTS.md                          guidance for AI agents working on this site: an app-specific
                                    header (where things live, the /admin URL, the CLI, the three
-                                   scaffolded Claude Code skills) + Kywi's official building
-                                   patterns (docs/agents/AGENT-PATTERNS.md, verbatim)
+                                   scaffolded Claude Code skills, a pointer to AGENTS.local.md) +
+                                   Kywi's official building patterns (docs/agents/AGENT-PATTERNS.md,
+                                   verbatim). AGENTS.local.md itself is never generated: it is
+                                   where the project's own instructions go
+.mcp.json                          wires both Kywi MCP servers for an agent client: kywi-site (content,
+                                   nav, media over this app's API at ${KYWI_API_URL}, key from
+                                   ${KYWI_API_KEY}, an env reference, never a value) and kywi-dev
+                                   (edits ./kywi.config.ts on disk). Safe to commit; the key stays in
+                                   the gitignored .env / .env.local
 CLAUDE.md                          thin pointer that sends a Claude Code session to AGENTS.md first,
                                    plus a nudge toward the kywi-content-model skill (and the other
                                    two scaffolded skills)
@@ -99,14 +106,17 @@ app/admin/[[...admin]]/page.tsx    mounts the FULL core admin (KywiAdminApp, eve
 
 **coupled** additionally gets `app/(site)/layout.tsx` + `app/(site)/[[...slug]]/page.tsx`
 (the public site — renders "/" and every published page at its slug, both **stamped**),
+`app/kywi.js/route.ts` (**stamped**: core serves the installed `@kywi-software/js`
+browser bundle at `/kywi.js`, so `pnpm up @kywi-software/js` is the whole upgrade
+and there is no copy step),
 plus `app/(site)/site.css` and `components/site-nav.tsx` (project-owned, unstamped).
 **headless** and **decoupled** instead get `app/page.tsx` (returns 404 — no public
 rendering, unstamped).
 
-All eleven of the files marked **(stamped)** above are **thin, version-stamped
-delegates**: the two `app/(site)` route files, `middleware.ts`, `lib/kywi.ts`,
-`kywi.layers.ts`, the API route, the four AX root routes and the admin catch-all
-page. Each opens with a `// kywi-render v2 (create-kywi-app <version>)
+All twelve of the files marked **(stamped)** above are **thin, version-stamped
+delegates**: the two `app/(site)` route files and `app/kywi.js/route.ts` (coupled
+only), `middleware.ts`, `lib/kywi.ts`, `kywi.layers.ts`, the API route, the four
+AX root routes and the admin catch-all page. Each opens with a `// kywi-render v2 (create-kywi-app <version>)
 sha256:<12 hex>` comment — the hash is over the file's own body, so
 `create-kywi-app upgrade` (see below) can tell an untouched generated file
 (safe to replace) from one you've edited (refused) without a diff against
@@ -128,6 +138,16 @@ generated files. Core validates the registry at startup and fails loudly when a
 site or theme is missing from it, when two themes of one site disagree on region names, or
 when a layer overrides a module name neither core nor `kywi.config.ts` defines.
 
+**`templates.hydrateLayout` reads the site from `ctx`, never from the runtime.** The
+transform is called per request with `ctx: { runtime, siteId, site }`, where `ctx.siteId`
+is the DB id of the site *this request* is for. `ctx.runtime.siteId` is the default site,
+fixed at boot, so a query scoped by it serves site A's data on site B's host:
+
+```ts
+hydrateLayout: async (layout, ctx) =>
+  withFeatured(layout, await ctx.runtime.scope.content.getBySlug('featured', ctx.siteId)), // not ctx.runtime.siteId
+```
+
 Note what's *not* in this list: there is no `components/admin-shell.tsx`, no
 per-route `app/admin/content/**`, no `lib/admin-auth.ts`. Since 0.2.0 the whole
 admin is one component (`KywiAdminApp`) shipped by `@kywi-software/core` — the
@@ -162,8 +182,9 @@ npx create-kywi-app@latest agents           # add any missing guidance files
 npx create-kywi-app@latest agents --force    # overwrite them with the latest
 ```
 
-It writes the same five files (`AGENTS.md`, `CLAUDE.md`, and the three
-`.claude/skills/<slug>/SKILL.md`). What it does:
+It writes the same guidance files a fresh scaffold gets (`AGENTS.md`,
+`CLAUDE.md`, `.mcp.json` and the `.claude/skills/<slug>/SKILL.md` skills). What
+it does:
 
 - **Detects the project** — requires a `kywi.config.ts` in the current directory
   (otherwise it exits with an error), reads the project name from `package.json`
@@ -176,14 +197,28 @@ It writes the same five files (`AGENTS.md`, `CLAUDE.md`, and the three
   doesn't have, or claims a thin delegate where it holds its own copy.
 - **Never clobbers by default** — existing files are skipped (a customized
   `AGENTS.md` is left untouched); pass `--force` to overwrite. It prints a
-  created/updated/skipped summary either way.
+  created/updated/skipped/kept summary either way.
+- **Merges `.mcp.json` instead of replacing it** — a project may wire its own
+  MCP servers there. Without `--force` it adds whichever of `kywi-site` /
+  `kywi-dev` is missing; with `--force` it resets those two entries. Any other
+  server is kept as-is, and a file that is not valid JSON is left alone and
+  reported as skipped. To use the site server, create an API key (admin → Web
+  Services → API Keys) and export `KYWI_API_KEY` (and `KYWI_API_URL` for a
+  deployed site) in the shell you start your agent from; `.mcp.json` only
+  references them.
+- **Never writes `AGENTS.local.md`** — that file is where this project's own
+  agent instructions belong (deploy steps, site conventions, anything specific
+  to this site). `AGENTS.md` and `CLAUDE.md` point at it; `create-kywi-app`
+  never creates, rewrites or deletes it, so `agents --force` cannot lose what is
+  in it. When it exists, the run reports it as `kept`. Do not put site-specific
+  guidance in `AGENTS.md` itself: the next `--force` refresh replaces it.
 
 Use `@latest` so an existing project picks up the newest guidance regardless of
 which `create-kywi-app` version originally scaffolded it.
 
 ## Upgrading a project
 
-Every generated render-path file is version-stamped (see the eleven **(stamped)**
+Every generated render-path file is version-stamped (see the twelve **(stamped)**
 files above), so `create-kywi-app upgrade` can prove which ones are still exactly
 what it emitted and safe to replace, versus which ones carry your own edits and
 must not be touched. Run it **from the project's root**:
@@ -201,6 +236,11 @@ then retired pre-0.19 glue:
   in `kywi.config.ts` has none of yet.
 - **`replaced`** — a stamped landmark whose hash proves it is still untouched;
   swapped for the current emission.
+- **`relabeled`** — a stamped landmark whose body is byte-identical to the
+  current emission and whose stamp only names an older create-kywi-app (`(stamp
+  says create-kywi-app 0.22.0; body identical, not rewritten)`). Nothing changed
+  in the code, so the file is left exactly as it is: a release that changed no
+  render file costs no commit. It counts as caught up, like `current`.
 - **`current`** — a stamped landmark that already matches the current emission
   byte for byte.
 - **`kept`** — a layer file under `sites/**` that already exists. Layer files are
@@ -223,6 +263,18 @@ then retired pre-0.19 glue:
 - **`backed up: <path> → .kywi-upgrade/<timestamp>/<path>`** — printed above any
   `replaced`/`removed` line that `--force` produced from a refusal: the original
   is copied there before it's touched.
+- **`warn: public/kywi.js is a copied bundle; …`** / **`warn: package.json does
+  not depend on @kywi-software/js, …`** — advisory only, coupled projects: core
+  now serves `/kywi.js` from `app/kywi.js/route.ts` (which `upgrade` creates), so
+  a hand-copied `public/kywi.js` (and any script that copies it) should go, and
+  the project needs `@kywi-software/js` as a dependency for the route to have a
+  bundle to serve. `upgrade` never edits `package.json` or `public/` itself.
+- **`warn: <file> imports <target>, which upgrade removes — import from
+  @kywi-software/core/next instead`** — advisory only: a project file of yours
+  (any `.ts`/`.tsx` outside `node_modules`, `.next` and `.kywi-upgrade`) has a
+  relative or `@/` import that resolves to one of the retired files above, or
+  imports a name (for example `KywiRuntime`) from a `lib/kywi.ts` that the
+  regenerated thin file no longer exports. Repoint it before you build.
 - **`warn: <path> was ejected from @kywi-software/core <v>; installed is <v>`** —
   advisory only, for a file `create-kywi-app eject` (below) put under `sites/**`
   whose stamped core version no longer matches the installed one.

package/assets/agent-patterns.md

@@ -729,8 +729,10 @@ Four traps, each of which fails silently:
    audience arm first, so a visitor who matches an audience never enters the
    split. Don't run an experiment and an audience variant on the same container.
 4. **The client runtime needs `/kywi.js`.** Self-ID, behavioral re-evaluation
-   and the transparency panel no-op silently unless the built
-   `@kywi-software/js` bundle is at `public/kywi.js`.
+   and the transparency panel no-op silently unless the app serves `/kywi.js`.
+   A coupled scaffold does, through `app/kywi.js/route.ts` (core's
+   `createKywiJsRoute`) over the installed `@kywi-software/js`: keep that
+   package as a dependency, and never copy the bundle into `public/`.
 
 Standing rule: **the default arm must be complete on its own.** It is what
 search engines, answer engines, and every opted-out visitor receive.

package/bin/create-kywi-app.mjs

@@ -17,7 +17,9 @@ import { createInterface } from 'node:readline/promises'
 import { stdin, stdout, argv, exit } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { readFileSync } from 'node:fs'
-import { buildFileSet, guidanceFileSet, detectAgentsLandmarks } from '../lib/templates.mjs'
+import {
+  buildFileSet, guidanceFileSet, detectAgentsLandmarks, AGENTS_LOCAL_PATH, MCP_JSON_PATH, mergeMcpJson,
+} from '../lib/templates.mjs'
 import { planUpgrade, applyUpgrade, formatReport, exitCodeFor } from '../lib/upgrade.mjs'
 import { planEject, applyEject, wiringHints } from '../lib/eject.mjs'
 
@@ -280,6 +282,19 @@ async function runAgentsCommand(opts) {
   for (const [rel, content] of Object.entries(files)) {
     const abs = join(cwd, rel)
     const exists = existsSync(abs)
+    // .mcp.json may wire the project's own servers too: merge, never replace.
+    if (rel === MCP_JSON_PATH && exists) {
+      const merged = mergeMcpJson(readFileSync(abs, 'utf8'), answers, { force: opts.force })
+      if (merged.action === 'skipped') {
+        stdout.write(`  skipped (${merged.reason === 'invalid' ? 'not valid JSON' : 'exists'}): ${rel}\n`)
+        skipped++
+      } else {
+        await writeFile(abs, merged.content, 'utf8')
+        stdout.write(`  updated: ${rel}${merged.added.length > 0 ? ` (added ${merged.added.join(', ')})` : ''}\n`)
+        updated++
+      }
+      continue
+    }
     if (exists && !opts.force) {
       stdout.write(`  skipped (exists): ${rel}\n`)
       skipped++
@@ -296,7 +311,14 @@ async function runAgentsCommand(opts) {
     }
   }
 
-  stdout.write(`\n✔ ${created} created, ${updated} updated, ${skipped} skipped.\n`)
+  // The project's own guidance is never written, only acknowledged (#272).
+  let kept = 0
+  if (existsSync(join(cwd, AGENTS_LOCAL_PATH))) {
+    stdout.write(`  kept: ${AGENTS_LOCAL_PATH} (this project's own instructions; never written)\n`)
+    kept++
+  }
+
+  stdout.write(`\n✔ ${created} created, ${updated} updated, ${skipped} skipped, ${kept} kept.\n`)
   if (skipped > 0) {
     stdout.write(`  Re-run with --force to overwrite the skipped file(s).\n`)
   }

package/lib/templates.mjs

@@ -53,9 +53,9 @@ function packageJson(a) {
   // — see `ensureAdminStylesheet` in core's front-edit.tsx). The SYNC stays
   // project-owned even though the overlay is core's: core fetches
   // /kywi-admin.css.version at runtime, and only the app can put a file in its
-  // own public/. Unlike public/kywi.js (opt-in, manually placed when
-  // personalization.clientRuntime is enabled — see README), this is a CORE
-  // feature every coupled-mode app has, so the sync is automatic.
+  // own public/. (The browser runtime is NOT synced this way: core serves
+  // /kywi.js itself, from the installed @kywi-software/js, through the stamped
+  // app/kywi.js/route.ts — #236. Upgrading the package is the whole upgrade.)
   const syncScripts =
     a.mode === 'coupled'
       ? {
@@ -91,6 +91,9 @@ function packageJson(a) {
         // 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',
+        // The browser runtime core serves at /kywi.js (app/kywi.js/route.ts):
+        // nav enhancement and the personalization client layer. Coupled only.
+        ...(a.mode === 'coupled' ? { '@kywi-software/js': CORE_RANGE(a.kywiVersion) } : {}),
       },
       devDependencies: {
         '@types/node': '^20.0.0',
@@ -184,7 +187,7 @@ try {
 /** @param {Answers} a */
 function kywiConfig(a) {
   const providers = a.authProviders.map((p) => `'${p}'`).join(', ')
-  return `import { defineKywiConfig, defineSite, defineTheme, defineModule } from '@kywi-software/core/config'
+  return `import { defineKywiConfig, defineSite, defineTheme, defineContentType, defineModule } 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
@@ -268,14 +271,16 @@ export default defineKywiConfig({
   // (admin → Content Types). Admin-created types are runtime-managed, so the
   // site owner can add a field next year without a developer or a migration.
   // Add a type HERE only when the *developer* must own its shape — code depends
-  // on it, it's reviewed in git, it migrates with \`pnpm migrate\`.
+  // on it, it's reviewed in git, it migrates with \`pnpm migrate\`. Wrap each one
+  // in \`defineContentType({ … })\`: it applies the type defaults a bare object
+  // literal skips.
   contentTypes: [
-    {
+    defineContentType({
       name: 'page',
       label: 'Page',
       baseType: 'content',
       fields: [],
-    },
+    }),
   ],
 
   // Custom layout modules (\`defineModule\`) — the palette additions this project
@@ -381,7 +386,16 @@ declare module '*.css'
 
 // ── next.config.mjs ───────────────────────────────────────────────────────────
 
-function nextConfig() {
+function nextConfig(a) {
+  // Serverless hosts ship only the files Next traces into each function, and
+  // core's /kywi.js route reads the bundle with fs at request time, which the
+  // tracer cannot follow. Coupled only: the other modes have no such route.
+  const tracing = a.mode === 'coupled'
+    ? `
+  // core serves /kywi.js from the installed @kywi-software/js (app/kywi.js/route.ts);
+  // trace the bundle into that function so serverless deploys include it.
+  outputFileTracingIncludes: { '/kywi.js': ['./node_modules/@kywi-software/js/dist/kywi.js'] },`
+    : ''
   return `/**
  * Next.js config for a Kywi app. Every setting here is required to consume
  * @kywi-software/core; removing any of them breaks the build:
@@ -406,7 +420,7 @@ const nextConfig = {
     'nodemailer',
     'bcryptjs',
     '@aws-sdk/client-s3',
-  ],
+  ],${tracing}
   webpack(config) {
     config.resolve.extensionAlias = {
       ...config.resolve.extensionAlias,
@@ -437,6 +451,15 @@ 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
+
+# Agent access over MCP (.mcp.json). The site server talks to this app's REST
+# API; .mcp.json only REFERENCES the key as \${KYWI_API_KEY}, so the key itself
+# never lands in a committed file. Create one in admin → Web Services → API
+# Keys, keep it here (or in .env.local), and export both variables in the shell
+# you start your agent from. The developer server needs no key: it edits
+# kywi.config.ts on disk.
+# KYWI_API_URL=http://localhost:3000/api/v1
+# KYWI_API_KEY=
 `
 }
 
@@ -454,6 +477,7 @@ function faviconSvg() {
 function gitignore() {
   return `node_modules
 .next
+# Secrets, including the KYWI_API_KEY that .mcp.json references.
 .env
 .env.local
 *.log
@@ -469,7 +493,7 @@ public/kywi-admin.css.version
 // ── the generated render path: version stamp + landmarks ─────────────────────
 
 /**
- * Version of the GENERATED RENDER PATH's SHAPE — the eleven generated files
+ * Version of the GENERATED RENDER PATH's SHAPE — the generated files
  * {@link RENDER_LANDMARK_PATHS} names, independent of the package version. Bump
  * it when their shape changes in a way an existing project should pick up, so a
  * project can compare its stamp against a newer create-kywi-app and know its
@@ -547,7 +571,7 @@ export function splitRenderStamp(text) {
  */
 export const RENDER_STAMP_RE = /^\/\/ kywi-render v(\d+) \(create-kywi-app ([^)]+)\)(?: sha256:([0-9a-f]{12}))?$/m
 
-/** @typedef {'runtime'|'middleware'|'siteLayout'|'sitePage'|'layers'|'apiRoute'|'axLlms'|'axLlmsFull'|'axSitemap'|'axRobots'|'adminHost'} RenderLandmark */
+/** @typedef {'runtime'|'middleware'|'siteLayout'|'sitePage'|'layers'|'apiRoute'|'axLlms'|'axLlmsFull'|'axSitemap'|'axRobots'|'adminHost'|'kywiJs'} RenderLandmark */
 
 /**
  * Landmark → its relative path, for the RENDER PATH: one entry per generated
@@ -557,8 +581,9 @@ export const RENDER_STAMP_RE = /^\/\/ kywi-render v(\d+) \(create-kywi-app ([^)]
  * the E8 drift guard (`__tests__/render-drift.test.mjs`) and, in plan E3, the
  * `upgrade` command.
  *
- * ALL ELEVEN generated render files are listed, not just the thin delegates
- * (plan E3 Task 1). The membership rule is "create-kywi-app wrote it and owns
+ * ALL generated render files are listed, not just the thin delegates (plan
+ * E3 Task 1): eleven at E3, plus `kywiJs` (#236), the coupled-only
+ * `/kywi.js` route. The membership rule is "create-kywi-app wrote it and owns
  * its shape", because that is what `upgrade` must be able to find and — when
  * the stamp's hash proves the file untouched — replace. The API route, the four
  * AX root routes and the admin host page qualify on exactly that basis; the
@@ -579,6 +604,7 @@ export const RENDER_LANDMARK_PATHS = {
   axSitemap: 'app/sitemap.xml/route.ts',
   axRobots: 'app/robots.txt/route.ts',
   adminHost: 'app/admin/[[...admin]]/page.tsx',
+  kywiJs: 'app/kywi.js/route.ts',
 }
 
 /**
@@ -624,6 +650,7 @@ export function renderLandmarks(mode) {
     axSitemap: true,
     axRobots: true,
     adminHost: true,
+    kywiJs: coupled,
   }
 }
 
@@ -1242,6 +1269,27 @@ export const dynamic = 'force-dynamic'
 `)
 }
 
+/**
+ * `/kywi.js` — the `@kywi-software/js` browser runtime, served by core's
+ * `createKywiJsRoute` from the package this app installed (#236). Core's public
+ * render path injects `<script src="/kywi.js">` for the nav enhancement and the
+ * personalization client layer; before this route a project had to copy the
+ * bundle into `public/` and keep the copy in step with the package by hand.
+ * Coupled only, like the `app/(site)` routes it serves.
+ */
+function kywiJsRoute() {
+  return stamped(`import { createKywiJsRoute } from '@kywi-software/core/next'
+
+const route = createKywiJsRoute()
+
+/** \`/kywi.js\` — the installed @kywi-software/js browser bundle, served by core (#236). */
+export const GET = route.GET
+export const HEAD = route.HEAD
+
+export const dynamic = 'force-dynamic'
+`)
+}
+
 // ── API route (thin proxy over @kywi-software/core/host) ──────────────────────
 
 function apiRoute() {
@@ -1485,19 +1533,26 @@ Audiences, experiments and the self-ID widget you configure in the admin resolve
 
 The **self-ID widget**, live re-evaluation, the transparency bar and behavioral
 signals are an optional *client* layer. Enable it by setting
-\`personalization: { clientRuntime: true }\` on your theme in \`kywi.config.ts\` and
-dropping the built \`@kywi-software/js\` browser bundle at \`public/kywi.js\`;
-core's \`PersonalizationRuntime\` (mounted by the public page) loads it
-best-effort. Without it, the server-rendered variant is what every visitor sees.
-
-The same \`public/kywi.js\` bundle also drives the header nav's hover-intent,
-Escape/arrow-key and viewport-edge-flip enhancement — independent of
-personalization. Core's site layout loads it whenever the site has
-a nav, whether or not \`clientRuntime\` is on, so the nav gets that polish on
-every site once the bundle is in place; the nav renders and works fully without
-it either way. (\`public/kywi-admin.css\`, the front-of-site editor's stylesheet,
-is a separate file synced automatically on \`dev\`/\`build\` — see "Front-of-site
-editor" above — unlike \`kywi.js\`, which you place yourself.)
+\`personalization: { clientRuntime: true }\` on your theme in \`kywi.config.ts\`;
+core's \`PersonalizationRuntime\` (mounted by the public page) loads the browser
+runtime from \`/kywi.js\` best-effort. Without it, the server-rendered variant is
+what every visitor sees.
+
+\`/kywi.js\` is served by core: \`app/kywi.js/route.ts\` (stamped) delegates to
+\`createKywiJsRoute\`, which reads the bundle from the \`@kywi-software/js\` this
+project depends on, with a short revalidating cache and an ETag. There is no copy
+step: \`pnpm up @kywi-software/js\` is the whole upgrade, and the next request
+serves the new bundle. Keep \`@kywi-software/js\` on the same version as
+\`@kywi-software/core\`. \`next.config.mjs\` traces the bundle into that route
+(\`outputFileTracingIncludes\`) so serverless deploys ship it.
+
+The same bundle also drives the header nav's hover-intent, Escape/arrow-key and
+viewport-edge-flip enhancement — independent of personalization. Core's site
+layout loads it whenever the site has a nav, whether or not \`clientRuntime\` is
+on; the nav renders and works fully without it either way.
+(\`public/kywi-admin.css\`, the front-of-site editor's stylesheet, is a separate
+file synced automatically on \`dev\`/\`build\` — see "Front-of-site editor"
+above.)
 
 ## Locales
 
@@ -1901,6 +1956,11 @@ export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
 ${intro}
 ${modeSentence}
 
+${AGENTS_LOCAL_POINTER}
+It is yours: \`create-kywi-app\` never writes it, and \`create-kywi-app agents
+--force\` never touches it. Where it disagrees with the generic guidance below,
+it wins.
+
 ## Where things live
 
 ${bullets.join('\n')}
@@ -1926,6 +1986,18 @@ CMS instead of hardcoding it.**
   return header + agentPatternsDoc()
 }
 
+/**
+ * Where a project keeps its OWN agent instructions (#272). The generator never
+ * writes this file, in any command: `agents --force` rewrites AGENTS.md,
+ * CLAUDE.md and the skills wholesale, so site-specific guidance kept in any of
+ * those would be deleted on the next refresh. AGENTS.md and CLAUDE.md point at
+ * it instead, and `agents` reports it `kept` when it exists.
+ */
+export const AGENTS_LOCAL_PATH = 'AGENTS.local.md'
+
+/** The pointer line AGENTS.md carries to {@link AGENTS_LOCAL_PATH}. */
+export const AGENTS_LOCAL_POINTER = `See \`${AGENTS_LOCAL_PATH}\` for this project's own instructions.`
+
 /**
  * CLAUDE.md — a thin pointer so a Claude Code session reads AGENTS.md first.
  * @param {Answers} a
@@ -1936,12 +2008,102 @@ export function claudeMd(a) {
 This is a **Kywi CMS** project. **Read \`AGENTS.md\` before building anything** — it
 holds Kywi's official building patterns and a map of where things live in this app.
 
+This project's own instructions, if it has any, are in \`AGENTS.local.md\` (never written by \`create-kywi-app\`).
+
 Core principle: **model content in the CMS instead of hardcoding it** — see \`AGENTS.md\`.
 
 Before building out a new content area, use the \`kywi-content-model\` skill (design the model, get sign-off) — skills in \`.claude/skills/\` also cover collections, custom modules, and personalization.
 `
 }
 
+// ── .mcp.json (#297) ──────────────────────────────────────────────────────────
+
+/** Where an MCP client (Claude Code and others) reads a project's servers. */
+export const MCP_JSON_PATH = '.mcp.json'
+
+/**
+ * The two Kywi MCP servers, keyed by the names `@kywi-software/mcp`'s README
+ * uses. Both run through `npx --package` pinned to this release's range, so the
+ * file works whether or not the project installed `@kywi-software/mcp`.
+ *
+ * - `kywi-site` — content, nav and media over this app's REST API. The URL and
+ *   the key are `\${VAR}` references the client expands from its environment,
+ *   so the key is never written to a file that gets committed: it lives in the
+ *   gitignored `.env` / `.env.local`. The server reads its key from
+ *   `KYWI_MCP_API_KEY`; the project-facing name is `KYWI_API_KEY`. The `:-`
+ *   defaults matter: a client refuses a config whose variable is unset with no
+ *   default, which would take the developer server down with it.
+ * - `kywi-dev` — reads and edits `kywi.config.ts` on disk (filesystem mode),
+ *   relative to the directory the agent was started in: the project root.
+ * @param {Answers} a
+ * @returns {Record<string, { command: string, args: string[], env: Record<string, string> }>}
+ */
+export function kywiMcpServers(a) {
+  const pkg = `@kywi-software/mcp@${CORE_RANGE(a.kywiVersion)}`
+  return {
+    'kywi-site': {
+      command: 'npx',
+      args: ['-y', '--package', pkg, 'kywi-mcp-site'],
+      env: {
+        KYWI_API_URL: '${KYWI_API_URL:-http://localhost:3000/api/v1}',
+        KYWI_MCP_API_KEY: '${KYWI_API_KEY:-}',
+      },
+    },
+    'kywi-dev': {
+      command: 'npx',
+      args: ['-y', '--package', pkg, 'kywi-mcp-dev'],
+      env: {
+        KYWI_CONFIG_PATH: './kywi.config.ts',
+        KYWI_MCP_MODE: 'filesystem',
+      },
+    },
+  }
+}
+
+/** @param {Answers} a */
+export function mcpJson(a) {
+  return `${JSON.stringify({ mcpServers: kywiMcpServers(a) }, null, 2)}\n`
+}
+
+/**
+ * Fold the Kywi servers into a project's EXISTING `.mcp.json` — the `agents`
+ * command's write for that one file. A project may wire other servers there, so
+ * replacing the file wholesale (what `--force` does to the guidance files) would
+ * delete them. Without `force`, only missing Kywi entries are added; with it,
+ * the Kywi entries are reset to the current emission. Anything else in the file
+ * is carried over as-is. A file that is not JSON is never touched.
+ * @param {string} existing  the current file's text
+ * @param {Answers} a
+ * @param {{ force?: boolean }} [options]
+ * @returns {{ action: 'updated'|'skipped', content: string|null, added: string[], reason: 'exists'|'invalid'|null }}
+ */
+export function mergeMcpJson(existing, a, { force = false } = {}) {
+  let parsed
+  try {
+    parsed = JSON.parse(existing)
+  } catch {
+    parsed = null
+  }
+  const servers = parsed?.mcpServers
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) ||
+    (servers !== undefined && (servers === null || typeof servers !== 'object' || Array.isArray(servers)))) {
+    return { action: 'skipped', content: null, added: [], reason: 'invalid' }
+  }
+  const ours = kywiMcpServers(a)
+  const added = Object.keys(ours).filter((name) => !(servers && name in servers))
+  if (!force && added.length === 0) return { action: 'skipped', content: null, added, reason: 'exists' }
+  const merged = { ...(servers ?? {}) }
+  for (const [name, server] of Object.entries(ours)) {
+    if (force || !(name in merged)) merged[name] = server
+  }
+  return {
+    action: 'updated',
+    content: `${JSON.stringify({ ...parsed, mcpServers: merged }, null, 2)}\n`,
+    added,
+    reason: null,
+  }
+}
+
 /**
  * The agent-guidance files every Kywi app should carry: AGENTS.md, an app-specific
  * header + Kywi's canonical patterns doc; CLAUDE.md, a thin pointer into it; and
@@ -1959,6 +2121,7 @@ export function guidanceFileSet(a, landmarks = scaffoldLandmarks(a.mode)) {
   const files = {
     'AGENTS.md': agentsMd(a, landmarks),
     'CLAUDE.md': claudeMd(a),
+    [MCP_JSON_PATH]: mcpJson(a),
   }
   for (const { slug, asset } of SKILLS) {
     files[`.claude/skills/${slug}/SKILL.md`] = skillDoc(asset)
@@ -1981,7 +2144,7 @@ export function buildFileSet(answers) {
     // Ambient module declarations the generated code needs in order to type-check
     // (see `cssTypes`). Every mode: the admin catch-all imports the stylesheet too.
     'types/css.d.ts': cssTypes(),
-    'next.config.mjs': nextConfig(),
+    'next.config.mjs': nextConfig(answers),
     '.env.example': envExample(),
     '.gitignore': gitignore(),
     'README.md': readme(answers),
@@ -2040,6 +2203,9 @@ export function buildFileSet(answers) {
     // explicitly, because the header nav is the thing a site restyles first.
     files['components/site-nav.tsx'] = siteNavComponent()
     files['app/(site)/[[...slug]]/page.tsx'] = siteSlugPage()
+    // The browser runtime, served by core from the installed @kywi-software/js
+    // (RENDER_LANDMARK_PATHS.kywiJs, #236). No copy step, no sync script.
+    files['app/kywi.js/route.ts'] = kywiJsRoute()
     // Syncs the admin stylesheet + a cache-busting version marker into
     // public/ on every predev/prebuild — see the doc comment on
     // syncKywiAdminCssScript and packageJson's syncScripts.

package/lib/upgrade.mjs

@@ -38,15 +38,18 @@
 import {
   copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync,
 } from 'node:fs'
-import { basename, dirname, join, relative } from 'node:path'
+import { basename, dirname, join, posix, relative, sep } from 'node:path'
 import {
   RENDER_LANDMARK_PATHS,
   LEGACY_RENDER_FILES,
   KNOWN_UNSTAMPED_EMISSIONS,
   GUIDANCE_VERSION,
+  AGENTS_LOCAL_PATH,
   buildFileSet,
   detectRenderLandmarks,
   hashRenderBody,
+  RENDER_VERSION,
+  splitRenderStamp,
   kywiLayers,
   layerFilesFor,
   packageVersion,
@@ -69,7 +72,14 @@ const EJECT_STAMP_RE = /^\/\/ kywi-eject (\S+) \(@kywi-software\/core ([^)]+)\)$
 const GUIDANCE_STAMP_RE = /^<!-- kywi-agent-guidance v(\d+) \(create-kywi-app ([^)]+)\) -->$/
 
 /**
- * @typedef {'create'|'replace'|'current'|'kept'|'refused'|'removed'} UpgradeAction
+ * `relabel` is a landmark whose BODY is byte-identical to the current emission
+ * and whose stamp differs only in the generator label (`create-kywi-app 0.22.0`
+ * where this release says `0.23.0`). It is never rewritten: a stamp-only rewrite
+ * would turn every release into an all-files commit with no functional change
+ * (#280). It is still counted apart from `current`, so the summary does not
+ * claim the bytes match when only the code does.
+ *
+ * @typedef {'create'|'replace'|'relabel'|'current'|'kept'|'refused'|'removed'} UpgradeAction
  * @typedef {{
  *   kind: 'landmark'|'layer'|'legacy',
  *   path: string,
@@ -77,6 +87,7 @@ const GUIDANCE_STAMP_RE = /^<!-- kywi-agent-guidance v(\d+) \(create-kywi-app ([
  *   reason: 'edited'|'unstamped'|'legacy'|null,
  *   content: string|null,
  *   backup: string|null,
+ *   stampedBy?: string|null,
  * }} UpgradeEntry
  */
 
@@ -177,6 +188,18 @@ export function planUpgrade(projectDir, { force = false, dryRun = false } = {})
     }
 
     const stamped = d.version !== null
+
+    // Same stamp version, intact, and the body that follows the stamp hashes
+    // exactly like this release's body: only the CLI label in the stamp line
+    // differs. Nothing to replace (#280).
+    if (
+      stamped && d.version === RENDER_VERSION && d.intact === true &&
+      d.hash === hashRenderBody(splitRenderStamp(expected).body)
+    ) {
+      plan.entries.push({ ...entry('landmark', rel, 'relabel', null, null), stampedBy: d.cliVersion })
+      continue
+    }
+
     // `intact === null` on a stamped file means the stamp carries no hash, which
     // is only legitimate for the pre-E3 v1 stamp. A v2 stamp without a hash was
     // hand-assembled, so its integrity is unknowable and it is treated as
@@ -215,8 +238,11 @@ export function planUpgrade(projectDir, { force = false, dryRun = false } = {})
 
   if (plan.entries.some((e) => e.backup)) plan.backupDir = backupDir
 
-  // 4. Advisory only, in report order: ejected artifacts, then the two version
-  //    hints. None of these ever cause a write or change the exit code.
+  // 4. Advisory only, in report order: project files that import what this run
+  //    removes, ejected artifacts, then the two version hints. None of these
+  //    ever cause a write or change the exit code.
+  plan.warns.push(...danglingImportWarns(projectDir, plan, expectedFor('runtime', RENDER_LANDMARK_PATHS.runtime)))
+  if (wanted.kywiJs) plan.warns.push(...kywiJsWarns(projectDir))
   const installedCore = installedCoreVersion(projectDir)
   for (const { path, artifact, version } of scanEjectedArtifacts(projectDir)) {
     if (installedCore === null || version === installedCore) continue
@@ -230,7 +256,7 @@ export function planUpgrade(projectDir, { force = false, dryRun = false } = {})
   const guidance = staleGuidance(projectDir)
   if (guidance !== null) {
     plan.notes.push(
-      `AGENTS.md guidance is from create-kywi-app ${guidance}; run \`create-kywi-app agents --force\` to refresh.`,
+      `AGENTS.md guidance is from create-kywi-app ${guidance}; run \`create-kywi-app agents --force\` to refresh (it never touches ${AGENTS_LOCAL_PATH}, where this project's own instructions belong).`,
     )
   }
 
@@ -267,6 +293,191 @@ function sanitizeProjectName(name) {
 
 // ── the advisory scanners ─────────────────────────────────────────────────────
 
+/**
+ * Project files that will stop compiling after this run (#271). `upgrade` only
+ * classifies landmarks, so a project-owned file importing one of the retired
+ * glue files (`lib/site.ts`, …) or a name the old `lib/kywi.ts` exported and the
+ * thin one does not (`KywiRuntime`) used to lose its import target without a
+ * word, and the build broke afterwards. This greps every `.ts`/`.tsx` outside
+ * `node_modules`, `.next`, `.git` and `.kywi-upgrade` for relative (or `@/`)
+ * import specifiers that resolve to such a file. A string scan rather than a
+ * parse: a false positive costs one warn line, never a write.
+ *
+ * @param {string} projectDir
+ * @param {ReturnType<typeof planUpgrade>} plan  entries already decided
+ * @param {string} runtimeEmission  the `lib/kywi.ts` this run would write
+ * @returns {string[]}
+ */
+function danglingImportWarns(projectDir, plan, runtimeEmission) {
+  const runtimeRel = RENDER_LANDMARK_PATHS.runtime
+  const legacy = plan.entries.filter((e) => e.kind === 'legacy').map((e) => e.path)
+  const runtimeReplaced = plan.entries.some((e) => e.path === runtimeRel && e.action === 'replace')
+  if (legacy.length === 0 && !runtimeReplaced) return []
+
+  const runtimeExports = exportedNames(runtimeEmission)
+  // Files this run rewrites or removes are not the project's problem to repoint.
+  const rewritten = new Set(
+    plan.entries.filter((e) => e.action === 'replace' || e.action === 'removed' || e.kind === 'legacy').map((e) => e.path),
+  )
+  const removal = plan.force ? 'this upgrade removes' : '`upgrade --force` removes'
+  const warns = []
+  for (const file of projectSourceFiles(projectDir)) {
+    if (rewritten.has(file)) continue
+    let text
+    try {
+      text = readFileSync(join(projectDir, file), 'utf8')
+    } catch {
+      continue
+    }
+    const code = stripComments(text)
+    const seen = new Set()
+    for (const { specifier, names } of importsOf(code)) {
+      const candidates = resolveCandidates(file, specifier)
+      if (candidates === null) continue
+      const target = legacy.find((rel) => candidates.includes(rel))
+      if (target !== undefined && !seen.has(target)) {
+        seen.add(target)
+        warns.push(`${file} imports ${target}, which ${removal} — import from @kywi-software/core/next instead`)
+      }
+      if (runtimeReplaced && candidates.includes(runtimeRel)) {
+        for (const name of names) {
+          if (runtimeExports.has(name) || seen.has(`${runtimeRel}#${name}`)) continue
+          seen.add(`${runtimeRel}#${name}`)
+          warns.push(
+            `${file} imports ${name} from ${runtimeRel}, which the regenerated file no longer exports — import it from @kywi-software/core/next instead`,
+          )
+        }
+      }
+    }
+  }
+  return warns
+}
+
+/**
+ * A coupled project from before core served `/kywi.js` (#236) copied the
+ * `@kywi-software/js` bundle into `public/kywi.js` itself (by hand, or with a
+ * `sync:runtime`-style script), and may not depend on the package at all.
+ * `upgrade` never edits `package.json` or `public/`, so both are warns: the
+ * copy is the stale bundle this route exists to retire, and without the
+ * dependency the route has nothing to serve.
+ * @returns {string[]}
+ */
+function kywiJsWarns(projectDir) {
+  const warns = []
+  if (existsSync(join(projectDir, 'public/kywi.js'))) {
+    warns.push(
+      `public/kywi.js is a copied bundle; core now serves /kywi.js from ${RENDER_LANDMARK_PATHS.kywiJs} — delete public/kywi.js and any script that copies it`,
+    )
+  }
+  let pkg = null
+  try {
+    pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'))
+  } catch {
+    /* no/invalid package.json — nothing to check */
+  }
+  if (pkg !== null && !pkg?.dependencies?.['@kywi-software/js'] && !pkg?.devDependencies?.['@kywi-software/js']) {
+    warns.push('package.json does not depend on @kywi-software/js, so /kywi.js will 404 — pnpm add @kywi-software/js')
+  }
+  return warns
+}
+
+const SCAN_SKIP_DIRS =new Set(['node_modules', '.next', '.git', '.kywi-upgrade'])
+
+/** Every `.ts`/`.tsx` under the project, as sorted posix-relative paths. */
+function projectSourceFiles(projectDir) {
+  const out = []
+  const stack = [projectDir]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    let dirents
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const dirent of dirents) {
+      const abs = join(dir, dirent.name)
+      if (dirent.isDirectory()) {
+        if (!SCAN_SKIP_DIRS.has(dirent.name)) stack.push(abs)
+      } else if (/\.tsx?$/.test(dirent.name) && !dirent.name.endsWith('.d.ts')) {
+        out.push(relative(projectDir, abs).split(sep).join('/'))
+      }
+    }
+  }
+  return out.sort()
+}
+
+/** Line and block comments out, so a commented-out import never warns. */
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`])\/\/.*$/gm, '$1')
+}
+
+/**
+ * Every module specifier in `code`, with the named bindings it imports (empty
+ * for a side-effect, namespace, default or dynamic import).
+ * @returns {Array<{ specifier: string, names: string[] }>}
+ */
+function importsOf(code) {
+  const out = []
+  const re = /\b(?:import|export)\s+(?:type\s+)?([^;'"]*?)\s*\bfrom\s*(['"])([^'"]+)\2|\bimport\s*\(?\s*(['"])([^'"]+)\4/g
+  let match
+  while ((match = re.exec(code)) !== null) {
+    if (match[3] !== undefined) {
+      const braces = /\{([^}]*)\}/.exec(match[1])
+      const names = braces === null
+        ? []
+        : braces[1].split(',')
+          .map((part) => part.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim())
+          .filter(Boolean)
+      out.push({ specifier: match[3], names })
+    } else {
+      out.push({ specifier: match[5], names: [] })
+    }
+  }
+  return out
+}
+
+/**
+ * The project-relative paths a relative or `@/` specifier could resolve to
+ * (the scaffold's tsconfig maps `@/*` to the project root), or `null` for a
+ * package import.
+ * @returns {string[]|null}
+ */
+function resolveCandidates(importer, specifier) {
+  let base
+  if (specifier.startsWith('./') || specifier.startsWith('../')) {
+    base = posix.normalize(posix.join(posix.dirname(importer), specifier))
+  } else if (specifier.startsWith('@/')) {
+    base = posix.normalize(specifier.slice(2))
+  } else {
+    return null
+  }
+  const stem = base.replace(/\.(?:m?jsx?|tsx?)$/, '')
+  return [base, `${stem}.ts`, `${stem}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]
+}
+
+/** The names a generated module exports, read off its `export` statements. */
+function exportedNames(code) {
+  const names = new Set()
+  for (const m of code.matchAll(/\bexport\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function\*?|class|type|interface|enum)\s+([A-Za-z_$][\w$]*)/g)) {
+    names.add(m[1])
+  }
+  for (const m of code.matchAll(/\bexport\s+(?:const|let|var)\s*\{([^}]*)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const name = part.split(':').pop().split('=')[0].trim()
+      if (name) names.add(name)
+    }
+  }
+  for (const m of code.matchAll(/\bexport\s+(?:type\s+)?\{([^}]*)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const name = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop().trim()
+      if (name) names.add(name)
+    }
+  }
+  if (/\bexport\s+default\b/.test(code)) names.add('default')
+  return names
+}
+
 /**
  * The `@kywi-software/core` version this project actually runs: the installed
  * package if there is one (the truth), else the declared dependency range with
@@ -448,13 +659,15 @@ export function formatReport(plan, applied) {
     const to = backedUp.get(e.path)
     if (to) out.push(`  backed up: ${e.path} → ${to}\n`)
     if (e.action === 'refused') out.push(`  REFUSED (${e.reason}): ${e.path}\n`)
-    else out.push(`  ${ACTION_LABEL[e.action]}: ${e.path}\n`)
+    else if (e.action === 'relabel') {
+      out.push(`  relabeled: ${e.path} (stamp says create-kywi-app ${e.stampedBy}; body identical, not rewritten)\n`)
+    } else out.push(`  ${ACTION_LABEL[e.action]}: ${e.path}\n`)
   }
   for (const warn of plan.warns) out.push(`  warn: ${warn}\n`)
   for (const note of plan.notes) out.push(`  note: ${note}\n`)
 
   const n = countActions(plan)
-  out.push(`\n✔ ${n.create} created, ${n.replace} replaced, ${n.current} current, ${n.kept} kept, ${n.refused} refused.\n`)
+  out.push(`\n✔ ${n.create} created, ${n.replace} replaced, ${n.relabel} relabeled, ${n.current} current, ${n.kept} kept, ${n.refused} refused.\n`)
   if (n.refused > 0) {
     out.push(
       '  Re-run with --force to replace the refused file(s) (each is backed up under .kywi-upgrade/ first). ' +
@@ -469,7 +682,7 @@ export function formatReport(plan, applied) {
 }
 
 function countActions(plan) {
-  const n = { create: 0, replace: 0, current: 0, kept: 0, refused: 0 }
+  const n = { create: 0, replace: 0, relabel: 0, current: 0, kept: 0, refused: 0 }
   for (const e of plan.entries) {
     if (e.action === 'refused') n.refused++
     else if (e.action in n) n[e.action]++

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Scaffold a new Kywi CMS project — npx create-kywi-app my-site",
   "type": "module",
   "homepage": "https://github.com/Kywi-Software/kywi-cms#readme",