create-kywi-app 0.4.0 → 0.6.0

package/README.md

@@ -14,14 +14,17 @@ independently of the CLI's prompting/arg-parsing.
 ## Usage
 
 ```bash
-npx create-kywi-app [project-name] [options]
+npx create-kywi-app [project-name] [options]     # scaffold a new project (default)
+npx create-kywi-app agents [--force]             # add/refresh agent guidance in an
+                                                 # existing project (run from its root)
 
 Options:
   --yes, -y            Use defaults, skip prompts
   --mode <mode>        coupled | headless | decoupled   (default: coupled)
   --db <provider>      postgresql | mysql               (default: postgresql)
   --auth <list>        comma-separated: credentials,google,github  (default: credentials)
-  --help, -h            Show this help
+  --force, -f          agents: overwrite existing guidance files (default: skip them)
+  --help, -h           Show this help
 ```
 
 With no flags and a TTY, it prompts interactively (project name, DB provider,
@@ -116,6 +119,35 @@ The generated project's own `README.md` walks through `createdb`, copying
 `decoupled` deployment it also shows the `@kywi-software/sdk` usage snippet (see
 `packages/sdk/README.md` in this monorepo for the current, verified SDK API).
 
+## Adding (or refreshing) agent guidance in an existing project
+
+New scaffolds get the agent-guidance files above automatically. To add them to a
+project that already exists — or to pull the **latest** guidance into one that has
+older copies — run the `agents` subcommand **from the project's root**:
+
+```bash
+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:
+
+- **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`
+  (falling back to the directory name) and the deployment mode from the config.
+- **Writes the real `AGENTS.md` header** — the "where things live" section is
+  generated from the landmarks it actually finds on disk (e.g. `lib/site.ts`,
+  `lib/modules.tsx`, the public `app/(site)/[[...slug]]/page.tsx`), so a
+  hand-built app that predates part of the scaffold gets an honest header rather
+  than one that asserts files it doesn't have.
+- **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.
+
+Use `@latest` so an existing project picks up the newest guidance regardless of
+which `create-kywi-app` version originally scaffolded it.
+
 ## Installing the generated packages
 
 All `@kywi-software/*` packages (`core`, `cli`, `sdk`, `mcp`, `js`) are

package/bin/create-kywi-app.mjs

@@ -12,12 +12,12 @@
  */
 import { mkdir, writeFile, readdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, join, resolve, basename } from 'node:path'
 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 } from '../lib/templates.mjs'
+import { buildFileSet, guidanceFileSet, detectAgentsLandmarks } from '../lib/templates.mjs'
 
 const MODES = ['coupled', 'headless', 'decoupled']
 const DB_PROVIDERS = ['postgresql', 'mysql']
@@ -38,12 +38,13 @@ function readKywiVersion() {
 // ── Arg parsing ───────────────────────────────────────────────────────────────
 
 function parseArgs(args) {
-  const opts = { name: undefined, yes: false, mode: undefined, db: undefined, auth: undefined, help: false }
-  const positional = []
+  const opts = { name: undefined, yes: false, mode: undefined, db: undefined, auth: undefined, help: false, force: false, positional: [] }
+  const positional = opts.positional
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
     if (arg === '--yes' || arg === '-y') opts.yes = true
     else if (arg === '--help' || arg === '-h') opts.help = true
+    else if (arg === '--force' || arg === '-f') opts.force = true
     else if (arg === '--mode') opts.mode = args[++i]
     else if (arg.startsWith('--mode=')) opts.mode = arg.slice(7)
     else if (arg === '--db') opts.db = args[++i]
@@ -61,19 +62,27 @@ function printHelp() {
 create-kywi-app — scaffold a new Kywi CMS project
 
 Usage:
-  create-kywi-app [project-name] [options]
+  create-kywi-app [project-name] [options]     Scaffold a new project (default)
+  create-kywi-app agents [--force]             Install/refresh the agent-guidance
+                                               files (AGENTS.md, CLAUDE.md,
+                                               .claude/skills/) in the CURRENT
+                                               Kywi project — run it from the
+                                               project root
 
 Options:
   --yes, -y            Use defaults, skip prompts
   --mode <mode>        coupled | headless | decoupled   (default: coupled)
   --db <provider>      postgresql | mysql               (default: postgresql)
   --auth <list>        comma-separated: credentials,google,github  (default: credentials)
+  --force, -f          agents: overwrite existing guidance files (default: skip them)
   --help, -h           Show this help
 
 Examples:
   npx create-kywi-app my-site
   npx create-kywi-app my-site --yes
   npx create-kywi-app blog --mode headless --auth credentials,google
+  npx create-kywi-app@latest agents          # add guidance to an existing project
+  npx create-kywi-app@latest agents --force  # refresh it to the latest version
 `)
 }
 
@@ -146,6 +155,107 @@ async function isNonEmptyDir(dir) {
   return entries.length > 0
 }
 
+// ── `agents` subcommand ─────────────────────────────────────────────────────────
+
+const DETECTABLE_MODES = ['coupled', 'headless', 'decoupled']
+
+/** Read the project name from ./package.json, falling back to the directory name. */
+function readProjectName(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    if (typeof pkg.name === 'string' && pkg.name.trim()) return pkg.name.trim()
+  } catch {
+    /* no/invalid package.json — fall through to the directory basename */
+  }
+  return basename(dir) || 'kywi-app'
+}
+
+/**
+ * Detect the deployment mode from kywi.config.ts (`mode: 'coupled'|'headless'|
+ * 'decoupled'`). Returns coupled with detected:false when absent/unmatched, so the
+ * caller can print a note.
+ */
+function detectMode(dir) {
+  try {
+    const cfg = readFileSync(join(dir, 'kywi.config.ts'), 'utf8')
+    const m = cfg.match(/mode:\s*['"](coupled|headless|decoupled)['"]/)
+    if (m && DETECTABLE_MODES.includes(m[1])) return { mode: m[1], detected: true }
+  } catch {
+    /* unreadable config — handled by the caller's kywi.config.ts existence gate */
+  }
+  return { mode: 'coupled', detected: false }
+}
+
+/**
+ * `create-kywi-app agents [--force]` — install/refresh the agent-guidance files
+ * that a fresh scaffold ships (AGENTS.md, CLAUDE.md, the three .claude/skills/*)
+ * into an EXISTING Kywi project. The AGENTS.md header is generated from landmarks
+ * detected on disk, so it describes the real project rather than asserting scaffold
+ * structure. Without --force, existing target files are skipped (never clobbered);
+ * with --force, they are overwritten.
+ */
+async function runAgentsCommand(opts) {
+  const cwd = process.cwd()
+
+  // 1. Detect a Kywi project.
+  if (!existsSync(join(cwd, 'kywi.config.ts'))) {
+    stdout.write(
+      `\n✖ No kywi.config.ts here — run \`create-kywi-app agents\` inside a Kywi project (its root).\n`,
+    )
+    return 1
+  }
+
+  const projectName = readProjectName(cwd)
+  const { mode, detected } = detectMode(cwd)
+
+  stdout.write(`\nRefreshing agent guidance for ${projectName} (${mode} mode)…\n`)
+  if (!detected) {
+    stdout.write(`  note: no deployment mode found in kywi.config.ts — assuming \`coupled\`.\n`)
+  }
+
+  // The guidance files depend only on projectName + mode (+ detected landmarks);
+  // the other answers fields are irrelevant here but kept shape-complete.
+  const answers = {
+    projectName,
+    mode,
+    dbProvider: 'postgresql',
+    authProviders: ['credentials'],
+    kywiVersion: KYWI_VERSION,
+  }
+  const landmarks = detectAgentsLandmarks(cwd)
+  const files = guidanceFileSet(answers, landmarks)
+
+  // 4. Write with safe semantics: without --force, skip existing files.
+  let created = 0
+  let updated = 0
+  let skipped = 0
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(cwd, rel)
+    const exists = existsSync(abs)
+    if (exists && !opts.force) {
+      stdout.write(`  skipped (exists): ${rel}\n`)
+      skipped++
+      continue
+    }
+    await mkdir(dirname(abs), { recursive: true })
+    await writeFile(abs, content, 'utf8')
+    if (exists) {
+      stdout.write(`  updated: ${rel}\n`)
+      updated++
+    } else {
+      stdout.write(`  created: ${rel}\n`)
+      created++
+    }
+  }
+
+  stdout.write(`\n✔ ${created} created, ${updated} updated, ${skipped} skipped.\n`)
+  if (skipped > 0) {
+    stdout.write(`  Re-run with --force to overwrite the skipped file(s).\n`)
+  }
+  stdout.write(`\nAgents will pick these up automatically; see AGENTS.md.\n`)
+  return 0
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -155,6 +265,12 @@ async function main() {
     return 0
   }
 
+  // Subcommand: `create-kywi-app agents [--force]` refreshes the agent-guidance
+  // files in an existing project instead of scaffolding a new one.
+  if (opts.positional[0] === 'agents') {
+    return runAgentsCommand(opts)
+  }
+
   let answers
   try {
     answers = await resolveAnswers(opts)

package/lib/templates.mjs

@@ -32,7 +32,7 @@
  * ships session fixes without the app hand-maintaining crypto.
  */
 
-import { readFileSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -383,12 +383,13 @@ import type {
   ModuleNode,
   FeedItemsResolver,
   ComponentResolver,
+  SectionComponentResolver,
   PersonalizationState,
 } from '@kywi-software/core/layout'
 import { isLayoutSection, applyPageVariant } from '@kywi-software/core/layout'
 import { resolveContentByPath, normalizePath } from '@kywi-software/core/nav'
 import { getFeedBySlug, getComponentById, resolveLocaleFromRequest } from '@kywi-software/core'
-import { resolveComponentDefinition } from '@kywi-software/core/admin/server'
+import { resolveComponentDefinition, resolveSectionComponentDefinition } from '@kywi-software/core/admin/server'
 import {
   evaluateActiveAudiences,
   getSelfIdWidgetConfig,
@@ -590,6 +591,41 @@ export async function buildComponentResolver(
   return (componentId) => resolveComponentDefinition(map.get(componentId) ?? null)
 }
 
+/** Yield every section-level component reference (\`section.componentId\`) in the
+ *  layout, descending into variantContainer default + variant sections (#69). */
+function* sectionComponentIds(regions: Record<string, RegionNode[]>): Generator<string> {
+  for (const nodes of Object.values(regions)) {
+    for (const node of nodes) {
+      if (isLayoutSection(node)) {
+        if (node.componentId) yield node.componentId
+      } else {
+        for (const s of node.defaultSections) if (s.componentId) yield s.componentId
+        for (const v of node.variants) for (const s of v.sections) if (s.componentId) yield s.componentId
+      }
+    }
+  }
+}
+
+/**
+ * Prefetch every connected *section* component (\`section.componentId\`) referenced
+ * by the layout and return a synchronous {@link SectionComponentResolver} over the
+ * snapshot — parallel to {@link buildComponentResolver} but for reusable sections
+ * (#69). Returns undefined when the layout references none (skip the prop).
+ */
+export async function buildSectionComponentResolver(
+  layout: LayoutDocument,
+  runtime: KywiRuntime,
+): Promise<SectionComponentResolver | undefined> {
+  const ids = new Set<string>(sectionComponentIds(layout.regions))
+  if (ids.size === 0) return undefined
+  const { db, siteId } = runtime
+  const entries = await Promise.all(
+    [...ids].map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
+  )
+  const map = new Map(entries)
+  return (componentId) => resolveSectionComponentDefinition(map.get(componentId) ?? null)
+}
+
 // ─── Personalization + experiments (#50) ─────────────────────────────────────
 
 /** Server-resolved personalization for one public request. */
@@ -1117,6 +1153,7 @@ import {
   clientRuntimeEnabled,
   buildFeedResolver,
   buildComponentResolver,
+  buildSectionComponentResolver,
   localeAlternates,
   mediaUrl,
   requestBaseUrl,
@@ -1255,6 +1292,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     const personalized = personalizeLayout(layout, perso.audienceId)
     const hydrated = await hydrateLayoutFeeds(personalized, buildFeedResolver(runtime))
     const componentResolver = await buildComponentResolver(hydrated, runtime)
+    const sectionComponentResolver = await buildSectionComponentResolver(hydrated, runtime)
     content = (
       <article className="page page--layout" data-kywi-content-id={contentId}>
         {head}
@@ -1263,6 +1301,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
           personalization={perso.personalization}
           moduleComponents={moduleComponents}
           {...(componentResolver ? { componentResolver } : {})}
+          {...(sectionComponentResolver ? { sectionComponentResolver } : {})}
         >
           {Object.keys(hydrated.regions).map((name) => (
             <KywiRegion key={name} name={name} />
@@ -1298,9 +1337,12 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
         canEdit={perms.canEdit}
         canPublish={perms.canPublish}
         contentId={contentId}
+        contentType={contentType}
         pageTitle={title}
         pageStatus={String(node['status'] ?? '')}
+        initialLayout={layout ?? { regions: { main: [] } }}
         adminHref={\`/admin/content/\${contentType}/\${contentId}\`}
+        moduleComponents={moduleComponents}
       >
         {content}
       </KywiFrontEdit>
@@ -1315,56 +1357,167 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
 /**
  * Front-of-site edit overlay (client). Mounted by the public page ONLY for an
  * authenticated admin who opened the page with ?kywi-edit=1 (the page verifies
- * the session cookie server-side first). Surfaces core's KywiEditToolbar and
- * enters edit mode, which outlines the editable regions core already marks with
- * the `data-kywi-*` protocol. Real content edits happen in the full admin editor
- * (the toolbar's Admin link deep-links to this page there); Publish posts to the
- * API for admins with publish permission.
+ * the session cookie server-side first).
+ *
+ * Two modes, same component:
+ *  - **Browse** — core's slim `KywiEditToolbar` over the live page, with the
+ *    editable regions outlined via the `data-kywi-*` protocol.
+ *  - **Edit** (`?kywi-edit=1`, or the toolbar's Edit toggle) — the FULL
+ *    `OverlayShell` layout editor, the same one the admin app mounts, rendered
+ *    from the same core module registry + custom renderers. Save PUTs the layout
+ *    document; Publish PUTs the layout then flips status — exactly the API the
+ *    admin editor uses.
+ *
+ * The OverlayShell is lazy-loaded (`next/dynamic`, client-only): its weight
+ * (dnd-kit, canvas, side panels) is only fetched when an editor actually enters
+ * edit mode, so the public browse bundle stays light.
  */
 function frontEditOverlay() {
   return `'use client'
 import React from 'react'
+import dynamic from 'next/dynamic'
 import { KywiEditToolbar, useKywiEditMode } from '@kywi-software/core/scope-client'
 import { adminFetch } from '@kywi-software/core/host-client'
+import {
+  createModuleRegistry,
+  createThemeRegistry,
+  BUILT_IN_MODULE_COMPONENTS,
+  type LayoutDocument,
+  type ModuleComponentMap,
+} from '@kywi-software/core/layout'
+import type { SaveAction } from '@kywi-software/core/admin'
+
+// Lazy-load the full layout editor AND its stylesheet: the shell bundle (dnd-kit,
+// canvas, panels) and the ~4.7k-line admin design system are pulled INSIDE this
+// factory, so they enter the module graph only when an editor opens the overlay —
+// never in the public browse bundle a visitor downloads.
+const OverlayShell = dynamic(
+  async () => {
+    await import('@kywi-software/core/admin/styles.css')
+    const mod = await import('@kywi-software/core/admin')
+    return mod.OverlayShell
+  },
+  { ssr: false },
+)
 
 export interface KywiFrontEditProps {
   canEdit: boolean
   canPublish: boolean
   contentId: string
+  contentType: string
   pageTitle: string
   pageStatus: string
+  /** The page's saved layout document (empty regions when it has none yet). */
+  initialLayout: LayoutDocument
   /** Deep link to this page in the full admin editor. */
   adminHref: string
+  /** Custom (defineModule) renderers, shared with the public layout + admin (#48). */
+  moduleComponents?: ModuleComponentMap
   children: React.ReactNode
 }
 
 /**
  * Wraps the public page with the front-of-site edit affordance. The page only
  * renders this for a signed-in admin who asked to edit (?kywi-edit=1), so the
- * toolbar's own permission gate (canEdit) is always satisfied here.
+ * permission gate (canEdit) is always satisfied here.
  */
 export function KywiFrontEdit({
   canEdit,
   canPublish,
   contentId,
+  contentType,
   pageTitle,
   pageStatus,
+  initialLayout,
   adminHref,
+  moduleComponents = {},
   children,
 }: KywiFrontEditProps) {
   const edit = useKywiEditMode({ canEdit, canPublish })
 
   // ?kywi-edit=1 means "enter edit mode now" — flip it on once after mount.
-  const { startEdit } = edit
+  const { startEdit, endEdit } = edit
   React.useEffect(() => {
     startEdit()
   }, [startEdit])
 
-  const handlePublish = React.useCallback(async () => {
+  // Registries + renderers for the editor: built from core (no module list is
+  // re-declared here) and merged with this app's custom module renderers from
+  // lib/modules — the SAME source the admin app and public renderer use (#48).
+  const moduleRegistry = React.useMemo(() => createModuleRegistry([]), [])
+  const themeRegistry = React.useMemo(() => createThemeRegistry(), [])
+  const editorComponents = React.useMemo(
+    () => ({ ...BUILT_IN_MODULE_COMPONENTS, ...moduleComponents }),
+    [moduleComponents],
+  )
+
+  // Persist the edited layout to the same content API the admin editor uses.
+  const persistLayout = React.useCallback(
+    async (next: LayoutDocument) => {
+      const res = await fetch(\`/api/v1/content/\${contentType}/\${contentId}/layout\`, {
+        method: 'PUT',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(next),
+      })
+      return res.ok
+    },
+    [contentType, contentId],
+  )
+
+  const handleSave = React.useCallback(
+    async (next: LayoutDocument, _action: SaveAction) => {
+      await persistLayout(next)
+      endEdit()
+    },
+    [persistLayout, endEdit],
+  )
+
+  const handlePublish = React.useCallback(
+    async (next: LayoutDocument, _action: SaveAction) => {
+      const ok = await persistLayout(next)
+      if (ok) {
+        // Best-effort status flip; the layout itself is already persisted above.
+        await fetch(\`/api/v1/content/\${contentType}/\${contentId}\`, {
+          method: 'PUT',
+          credentials: 'same-origin',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ status: 'published' }),
+        }).catch(() => undefined)
+      }
+      endEdit()
+    },
+    [persistLayout, contentType, contentId, endEdit],
+  )
+
+  // Browse-mode one-click publish from the toolbar (no editor needed).
+  const handleToolbarPublish = React.useCallback(async () => {
     const res = await adminFetch(\`/api/v1/content/by-id/\${contentId}/publish\`, { method: 'POST' })
     if (res.ok) window.location.reload()
   }, [contentId])
 
+  // Edit mode: the full layout editor, in place, over the live page.
+  if (edit.isEditMode && edit.canEdit) {
+    return (
+      <div className="kywi-admin-shell kywi-frontend-edit">
+        <OverlayShell
+          editMode={edit}
+          initialLayout={initialLayout}
+          contentId={contentId}
+          contentType={contentType}
+          pageTitle={pageTitle}
+          themeName="default"
+          themeRegistry={themeRegistry}
+          moduleRegistry={moduleRegistry}
+          moduleComponents={editorComponents}
+          onSave={handleSave}
+          onPublish={handlePublish}
+        />
+      </div>
+    )
+  }
+
+  // Browse mode: slim toolbar + editable-region outlines over the live page.
   return (
     <>
       <KywiEditToolbar
@@ -1372,7 +1525,7 @@ export function KywiFrontEdit({
         canEdit={edit.canEdit}
         canPublish={edit.canPublish}
         onToggleEdit={edit.toggleEdit}
-        onPublish={handlePublish}
+        onPublish={handleToolbarPublish}
         pageTitle={pageTitle}
         pageStatus={pageStatus}
         adminHref={adminHref}
@@ -1800,7 +1953,16 @@ their Body rich text. Reach for the Layout tab when a page needs sections,
 columns, or modules; use the Body for simple prose.
 
 **Front-of-site editor.** Signed in as an admin, append \`?kywi-edit=1\` to any
-public page to get an edit toolbar (the \`app/(site)/kywi-front-edit.tsx\` overlay).
+public page to edit it in place. You get the full **Layout editor** (the same
+drag-and-drop canvas, module palette and props panel as the admin's Layout tab),
+mounted right over the live page — add sections and modules, then **Save** (PUTs
+the layout) or **Publish** (saves + publishes). Exit the editor for the slim
+browse toolbar with the editable-region outlines. It all lives in
+\`app/(site)/kywi-front-edit.tsx\`; the editor bundle (and the admin stylesheet) is
+lazy-loaded, so pages your visitors see never carry its weight. Note: custom
+\`defineModule\` types still RENDER on the canvas, but they don't appear in the
+front-of-site editor's insert palette (it uses the built-in module set) — add
+them from the admin's Layout tab instead.
 
 ## Personalization, A/B testing & self-ID
 
@@ -1919,7 +2081,7 @@ lib/config.ts                     single import path for kywi.config.ts
 app/api/v1/[...kywi]/route.ts     the versioned API (delegates to core)
 app/admin/[[...admin]]/page.tsx   mounts the FULL core admin (all surfaces) at /admin
 lib/modules.tsx                   custom (defineModule) module renderers (admin + public)
-app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site edit overlay (?kywi-edit=1)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
 \`\`\`
 `
 }
@@ -1990,7 +2152,7 @@ const _skillDocCache = new Map()
  * @param {string} asset
  * @returns {string}
  */
-function skillDoc(asset) {
+export function skillDoc(asset) {
   if (!_skillDocCache.has(asset)) {
     const assetPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', asset)
     _skillDocCache.set(asset, readFileSync(assetPath, 'utf8'))
@@ -1999,51 +2161,159 @@ function skillDoc(asset) {
 }
 
 /**
- * AGENTS.md — a short, app-specific header that orients an agent in THIS generated
- * app, followed by Kywi's canonical patterns doc verbatim. Mode-aware: only
- * coupled apps have public-render wiring (lib/site.ts), so the header reflects it.
+ * Landmark → its relative path in a Kywi project. A "landmark" is a file whose
+ * presence changes how the AGENTS.md header should describe the app. The scaffold
+ * derives its set statically from the mode ({@link scaffoldLandmarks}); the
+ * `agents` refresh command detects them on disk ({@link detectAgentsLandmarks}),
+ * so the header reflects the REAL project instead of asserting scaffold structure.
+ * One source of truth for the path strings, shared by both.
+ * @type {Record<'adminHost'|'moduleMap'|'middleware'|'libSite'|'sitePage'|'headlessPage', string>}
+ */
+export const AGENTS_LANDMARK_PATHS = {
+  adminHost: 'app/admin/[[...admin]]/page.tsx',
+  moduleMap: 'lib/modules.tsx',
+  middleware: 'middleware.ts',
+  libSite: 'lib/site.ts',
+  sitePage: 'app/(site)/[[...slug]]/page.tsx',
+  headlessPage: 'app/page.tsx',
+}
+
+/**
+ * @typedef {Object} AgentsLandmarks
+ * @property {boolean} scaffolded  Generating for a fresh scaffold (true) vs
+ *   refreshing into an existing project (false). Controls only the intro line's
+ *   "scaffolded by create-kywi-app" claim.
+ * @property {boolean} adminHost   app/admin/[[...admin]]/page.tsx present
+ * @property {boolean} moduleMap   lib/modules.tsx present
+ * @property {boolean} middleware  middleware.ts present
+ * @property {boolean} libSite     lib/site.ts present (the scaffold's public-render helpers)
+ * @property {boolean} sitePage    app/(site)/[[...slug]]/page.tsx present (renders public pages)
+ * @property {boolean} headlessPage app/page.tsx present (the headless/decoupled 404 root)
+ */
+
+/**
+ * The landmark set a FRESH scaffold of the given mode has — derived statically
+ * from the mode, never from the filesystem, so buildFileSet emits AGENTS.md that
+ * is byte-identical to the previous mode-branching implementation.
+ * @param {'coupled'|'headless'|'decoupled'} mode
+ * @returns {AgentsLandmarks}
+ */
+export function scaffoldLandmarks(mode) {
+  const coupled = mode === 'coupled'
+  return {
+    scaffolded: true,
+    adminHost: true,
+    moduleMap: true,
+    middleware: true,
+    libSite: coupled,
+    sitePage: coupled,
+    headlessPage: !coupled,
+  }
+}
+
+/**
+ * Detect the AGENTS.md landmarks that actually exist in an EXISTING project, so
+ * `create-kywi-app agents` writes a header that matches the app on disk (a
+ * hand-built app may render the public site from the page directly and predate
+ * the scaffold's lib/site.ts helper or lib/modules.tsx map).
+ * @param {string} projectDir  absolute path to the project root
+ * @returns {AgentsLandmarks}
+ */
+export function detectAgentsLandmarks(projectDir) {
+  const has = (rel) => existsSync(join(projectDir, rel))
+  return {
+    scaffolded: false,
+    adminHost: has(AGENTS_LANDMARK_PATHS.adminHost),
+    moduleMap: has(AGENTS_LANDMARK_PATHS.moduleMap),
+    middleware: has(AGENTS_LANDMARK_PATHS.middleware),
+    libSite: has(AGENTS_LANDMARK_PATHS.libSite),
+    sitePage: has(AGENTS_LANDMARK_PATHS.sitePage),
+    headlessPage: has(AGENTS_LANDMARK_PATHS.headlessPage),
+  }
+}
+
+/**
+ * AGENTS.md — a short, app-specific header that orients an agent in THIS app,
+ * followed by Kywi's canonical patterns doc verbatim. Landmark-aware: each "Where
+ * things live" bullet is emitted only for a landmark that is actually present, and
+ * absent public-render (lib/site.ts) or module-map (lib/modules.tsx) wiring becomes
+ * an honest "this app predates the scaffold's …" line instead of a bullet that
+ * asserts a file the project does not have. With no landmarks passed it defaults to
+ * the fresh-scaffold set for the mode, so the scaffold output is unchanged.
  * @param {Answers} a
+ * @param {AgentsLandmarks} [landmarks]
  */
-function agentsMd(a) {
-  const coupled = a.mode === 'coupled'
-  const modeSentence = coupled
-    ? 'This app renders the public site AND serves the admin + API.'
-    : a.mode === 'headless'
-      ? 'This app serves the admin + API only (`GET /` returns 404); there is no public rendering here.'
-      : 'This app serves the admin + API only; a separate frontend consumes the API via `@kywi-software/sdk`. There is no public rendering here.'
-  const surfaceLine = coupled
-    ? `- \`lib/site.ts\` — public-render helpers (path/locale resolution, feeds,
+export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
+  const L = landmarks
+  const modeSentence =
+    a.mode === 'coupled'
+      ? 'This app renders the public site AND serves the admin + API.'
+      : a.mode === 'headless'
+        ? 'This app serves the admin + API only (`GET /` returns 404); there is no public rendering here.'
+        : 'This app serves the admin + API only; a separate frontend consumes the API via `@kywi-software/sdk`. There is no public rendering here.'
+
+  // Existing projects aren't necessarily scaffolded — don't assert they were.
+  const intro = L.scaffolded
+    ? `This is a **Kywi CMS** project scaffolded by \`create-kywi-app\` (\`${a.mode}\` mode).`
+    : `This is a **Kywi CMS** project (\`${a.mode}\` mode).`
+
+  // "Where things live" — one bullet per PRESENT landmark, in a fixed order.
+  const bullets = []
+  bullets.push(`- \`kywi.config.ts\` — project config: sites, themes, content types, auth
+  providers, deployment mode, and \`admin.features\`. Edit it, then re-run
+  \`pnpm migrate\`.`)
+  if (L.adminHost) {
+    bullets.push(`- \`app/admin/[[...admin]]/page.tsx\` — mounts Kywi's **full admin**
+  (\`KywiAdminApp\`) at **\`/admin\`**. Every surface — content, media, feeds,
+  forms, audiences, settings, … — is already there; never hand-build admin pages.`)
+  }
+  if (L.moduleMap) {
+    bullets.push(`- \`lib/modules.tsx\` — the custom-module map (\`defineModule\` renderers), shared
+  by the admin editor and the public site.`)
+  } else {
+    bullets.push(`- No \`lib/modules.tsx\` custom-module map — this app predates the scaffold's
+  \`defineModule\` module map (shared by the admin editor and the public site); see
+  the patterns doc below for the intended shape.`)
+  }
+  // Public-render surface: the scaffold's lib/site.ts helper, else a page that
+  // renders publicly without it (honest note), else no public rendering at all.
+  if (L.libSite) {
+    bullets.push(`- \`lib/site.ts\` — public-render helpers (path/locale resolution, feeds,
   components, personalization) used by \`app/(site)/[[...slug]]/page.tsx\`, which
-  renders every published page at its slug.`
-    : a.mode === 'headless'
-      ? `- No public rendering in this mode — \`app/page.tsx\` returns 404. Content is
-  served over the REST API at \`/api/v1\`.`
-      : `- No public rendering in this mode — \`app/page.tsx\` returns 404. Build a
+  renders every published page at its slug.`)
+  } else if (L.sitePage) {
+    bullets.push(`- \`app/(site)/[[...slug]]/page.tsx\` — renders every published page at its
+  slug. This app predates the scaffold's \`lib/site.ts\` public-render helpers
+  (path/locale resolution, feeds, components, personalization); see the patterns
+  doc below for the intended shape.`)
+  } else {
+    bullets.push(
+      a.mode === 'decoupled'
+        ? `- No public rendering in this mode — \`app/page.tsx\` returns 404. Build a
   separate frontend against the REST API at \`/api/v1\` with \`@kywi-software/sdk\`.`
+        : `- No public rendering in this mode — \`app/page.tsx\` returns 404. Content is
+  served over the REST API at \`/api/v1\`.`,
+    )
+  }
+  if (L.middleware) {
+    bullets.push(`- \`middleware.ts\` — auth gate + session refresh, thin wiring over
+  \`@kywi-software/core/host\`.`)
+  }
+  bullets.push(`- \`.claude/skills/kywi-content-model/SKILL.md\` — content-model planning
+  skill, loaded automatically before building anything.`)
+  bullets.push(`- \`.claude/skills/kywi-collections/SKILL.md\` — collections skill, loaded
+  automatically when adding any collection.`)
+  bullets.push(`- \`.claude/skills/kywi-personalization/SKILL.md\` — personalization skill,
+  loaded automatically when the owner wants personalization or A/B testing.`)
+
   const header = `# Agent guide — ${a.projectName}
 
-This is a **Kywi CMS** project scaffolded by \`create-kywi-app\` (\`${a.mode}\` mode).
+${intro}
 ${modeSentence}
 
 ## Where things live
 
-- \`kywi.config.ts\` — project config: sites, themes, content types, auth
-  providers, deployment mode, and \`admin.features\`. Edit it, then re-run
-  \`pnpm migrate\`.
-- \`app/admin/[[...admin]]/page.tsx\` — mounts Kywi's **full admin**
-  (\`KywiAdminApp\`) at **\`/admin\`**. Every surface — content, media, feeds,
-  forms, audiences, settings, … — is already there; never hand-build admin pages.
-- \`lib/modules.tsx\` — the custom-module map (\`defineModule\` renderers), shared
-  by the admin editor and the public site.
-${surfaceLine}
-- \`middleware.ts\` — auth gate + session refresh, thin wiring over
-  \`@kywi-software/core/host\`.
-- \`.claude/skills/kywi-content-model/SKILL.md\` — content-model planning
-  skill, loaded automatically before building anything.
-- \`.claude/skills/kywi-collections/SKILL.md\` — collections skill, loaded
-  automatically when adding any collection.
-- \`.claude/skills/kywi-personalization/SKILL.md\` — personalization skill,
-  loaded automatically when the owner wants personalization or A/B testing.
+${bullets.join('\n')}
 
 ## Running it
 
@@ -2070,7 +2340,7 @@ CMS instead of hardcoding it.**
  * CLAUDE.md — a thin pointer so a Claude Code session reads AGENTS.md first.
  * @param {Answers} a
  */
-function claudeMd(a) {
+export function claudeMd(a) {
   return `# ${a.projectName}
 
 This is a **Kywi CMS** project. **Read \`AGENTS.md\` before building anything** — it
@@ -2082,6 +2352,30 @@ Before building out a new content area, use the \`kywi-content-model\` skill (de
 `
 }
 
+/**
+ * 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
+ * the three Claude Code project skills, verbatim assets. ONE source of truth for
+ * "which files are the agent guidance", shared by {@link buildFileSet} (fresh
+ * scaffold, {@link scaffoldLandmarks}) and the `agents` refresh command
+ * ({@link detectAgentsLandmarks}) — so both emit identical content for identical
+ * inputs, and adding/renaming a skill in {@link SKILLS} updates both at once.
+ * @param {Answers} a
+ * @param {AgentsLandmarks} [landmarks]
+ * @returns {Record<string, string>}
+ */
+export function guidanceFileSet(a, landmarks = scaffoldLandmarks(a.mode)) {
+  /** @type {Record<string, string>} */
+  const files = {
+    'AGENTS.md': agentsMd(a, landmarks),
+    'CLAUDE.md': claudeMd(a),
+  }
+  for (const { slug, asset } of SKILLS) {
+    files[`.claude/skills/${slug}/SKILL.md`] = skillDoc(asset)
+  }
+  return files
+}
+
 /**
  * Build the complete map of relative-path → file-content for a project.
  * @param {Answers} answers
@@ -2098,10 +2392,12 @@ export function buildFileSet(answers) {
     '.env.example': envExample(),
     '.gitignore': gitignore(),
     'README.md': readme(answers),
-    // agent guidance (every mode): app-specific header + Kywi's canonical patterns
-    // doc verbatim. CLAUDE.md is a thin pointer into AGENTS.md.
-    'AGENTS.md': agentsMd(answers),
-    'CLAUDE.md': claudeMd(answers),
+    // agent guidance (every mode): AGENTS.md (app-specific header + Kywi's
+    // canonical patterns doc verbatim), CLAUDE.md (thin pointer into it), and the
+    // three Claude Code project skills. Landmarks are derived statically from the
+    // mode so this stays byte-identical to the pre-landmark implementation; the
+    // same guidanceFileSet powers `create-kywi-app agents` for existing projects.
+    ...guidanceFileSet(answers, scaffoldLandmarks(answers.mode)),
     // server runtime + config
     'lib/kywi.ts': libKywi(),
     'lib/config.ts': libConfig(),
@@ -2126,15 +2422,6 @@ export function buildFileSet(answers) {
     'app/robots.txt/route.ts': axRootRoute('robots.txt'),
   }
 
-  // Claude Code project skills (every mode): content-model-first discipline,
-  // collections, and personalization — Claude Code loads each automatically at
-  // the moment it's relevant (see SKILLS above for when-to-use). Verbatim
-  // assets, same readFileSync-from-import.meta.url + cache mechanism as
-  // AGENTS.md above.
-  for (const { slug, asset } of SKILLS) {
-    files[`.claude/skills/${slug}/SKILL.md`] = skillDoc(asset)
-  }
-
   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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.4.0",
+  "version": "0.6.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",