create-kywi-app 0.6.3 → 0.6.4

package/assets/agent-patterns.md

@@ -17,6 +17,27 @@ edit content in the admin, or do they need a developer?"* If the answer is
 Static code is for structure and brand chrome. Content — anything with words,
 images, prices, names, dates — belongs in Kywi.
 
+## Where the owner edits — the surfaces you're building for
+
+"Editable" isn't an abstraction. It means the thing appears in one of three
+shipped surfaces:
+
+- **Admin → Content / Site Tree** — the fields on a node (which fields exist is
+  decided by the type, §2).
+- **Admin → the layout editor** — regions, sections, columns, modules, page
+  variants, and section-level personalized/A-B containers with an arm switcher.
+- **The public site itself** — a signed-in admin gets a toolbar on every public
+  page (page title, status, **Edit this page**), which opens that same layout
+  editor *in place*: the real page, the site's own stylesheet, chrome docked to
+  the viewport edges. Text-bearing modules are edited by typing on the page.
+
+The build rule that follows: **prefer structures that show up in those
+surfaces.** A headline in a `heading` module is editable in all three; the same
+headline in a hand-written component is editable in none. Custom modules (§5)
+must expose their copy as first-class props for the same reason — and a module
+whose *first* declared prop is `text`, `textarea` or `richText` becomes
+inline-editable on the front of the site for free.
+
 ## Before you build: design the content model and get sign-off
 
 The most expensive failure in a CMS build is a poorly planned content model —
@@ -57,6 +78,8 @@ the full proposal — ten minutes of sign-off beats re-entering fifty nodes.
 | Filter/group content by topic, industry, audience | Categories & tags, queried by feeds (§3) |
 | Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component (§4) |
 | Write page sections as JSX | Build them as layout sections/modules the owner can edit (§5) |
+| Build a page as one column of full-width headings and paragraphs | Compose: section bands, columns, object modules (§5) |
+| Put a custom module's editable copy in a `json` prop | One `text`/`textarea`/`richText` prop per field the owner edits (§5) |
 | Hand-code a `<form>` | Build it in the Forms admin, place the Form module (§6) |
 | Drop images into `/public` | Upload to the Media library (§7) |
 | Build segment-specific or experimental UI unprompted | Ask the owner first — offer personalization/A-B with examples (§8) |
@@ -113,6 +136,28 @@ by `kywi migrate`. When in doubt, admin-created.
   node's own page is the detail view. Listing + detail with zero custom code.
 - Don't shadow built-in fields (slug, body) with custom ones — Kywi will block
   it; use the built-ins.
+- The scaffold ships one config type (`page`) so a fresh site can publish
+  immediately. That's the floor, not the pattern — add your types in the Type
+  Designer, and only put a type in `contentTypes` when code depends on its shape.
+
+**Creating types programmatically.** The admin UI is one client of the REST API;
+an agent uses the same endpoints, and the order matters:
+
+1. `POST /api/v1/content-types` — create the type.
+2. `POST /api/v1/content-types/:type/fields` — add each field.
+3. `POST /api/v1/content-types/apply` — **materialize the schema** (diffs the
+   type and runs the CREATE/ALTER for its side table).
+4. *Then* create nodes — before the apply step the side table doesn't exist and
+   the write fails (cleanly rolled back since 0.6.3, but still a failure).
+
+**Seed with an idempotent script.** Put structural setup in a
+`scripts/seed-content.mjs` that logs in (`POST /api/v1/auth/login`) and *checks
+before creating* every object — list types → create the missing, list fields →
+add the missing, same for taxonomy, audiences, experiments, self-ID. It is
+re-runnable, reviewable in git, and rebuilds the site on a fresh database. Build
+pages, layouts and feeds over MCP or in the admin instead. The script seeds
+structure; it doesn't own content — once the owner edits a node, a re-run must
+not clobber it.
 
 ## 3. Taxonomy: categories & tags
 
@@ -146,22 +191,138 @@ newsletter signup blocks, campaign snippets, "as seen in" strips — should be a
 ## 5. Page layouts & modules — not hardcoded JSX
 
 Pages the owner should be able to restructure — landing pages, the home page,
-campaign pages — should be built **in the layout editor** (sections, columns,
-modules), rendered through Kywi's layout renderer. A scaffolded app already
-renders saved layouts on every content page; keep it that way.
-
-- The built-in module palette (hero, cards, CTA, testimonial, feed display,
-  pricing, FAQ, forms, comments, media…) covers most marketing-site needs.
-- Brand-specific blocks the palette lacks: build a **custom module** once
-  (`defineModule` in `kywi.config.ts` + a React component registered in the
-  host's module map — the scaffold's `lib/modules.tsx` shows the shape). The
-  developer owns the component; the owner places and configures instances.
-- Create **saved layouts** (Layouts admin) as page templates — "Landing page",
-  "Case study" — so new pages start from a consistent skeleton instead of a
-  blank canvas.
-- Hand-written JSX pages are fine for genuinely fixed chrome (a bespoke 404,
-  legal boilerplate shells) — but if marketing will ever want to swap a
-  headline, it's a layout page.
+campaign pages — should be built **in the layout editor** (regions → sections →
+columns → modules), rendered through Kywi's layout renderer. A scaffolded app
+already renders saved layouts on every content page; keep it that way.
+
+**Compose.** A page is not a stack of full-width `heading` + `richText` blocks.
+That is the shape an agent falls into when it doesn't know the palette, and it
+reads as a styled document rather than a site. Sections are bands (each owns its
+background and padding), `columns` splits them, and the object modules below do
+the rest.
+
+### The built-in palette
+
+`name` is the exact `type` value in a layout node and in MCP `add_module`. A
+custom module that reuses one of these names **overrides** the built-in
+everywhere.
+
+**Layout** — the skeleton of a page.
+
+| `name` | Purpose |
+|---|---|
+| `section` | Top-level band in a region; owns background colour and vertical padding |
+| `container` | Width-capped, padded wrapper inside a section |
+| `columns` | Multi-column split (`preset` picks the ratio, `gap` the spacing) |
+| `spacer` | Fixed vertical gap |
+| `divider` | Horizontal rule (colour, thickness) |
+
+**Elements** — the primitives.
+
+| `name` | Purpose |
+|---|---|
+| `richText` | WYSIWYG prose — the default home for owner-authored copy |
+| `heading` | One heading, with its level (h1–h6) |
+| `text` | Plain paragraph text |
+| `image` | Media-library image with alt text and caption |
+| `button` | Labelled link with a style variant |
+| `html` | Raw HTML escape hatch (sanitized) — not a layout tool |
+| `blockquote` | Quote with author and citation URL |
+| `badge` | Small label/pill, optionally linked |
+| `icon` | Named icon with size, colour, accessible label |
+| `video` | Video file with poster, autoplay/loop/muted |
+| `embed` | Third-party embed code |
+
+**Objects** — the composed blocks.
+
+| `name` | Purpose |
+|---|---|
+| `card` | Title + body + image + link — the generic tile |
+| `accordion` | One collapsible title/content panel |
+| `tabs` | Tabbed panels (`tabs` JSON prop) |
+| `carousel` | Rotating slides (`items` JSON prop, autoplay/interval) |
+| `testimonial` | Quote + author + role + avatar |
+| `hero` | Headline, subtext, background image, one CTA button |
+| `cta` | Headline + subtext + button — the conversion band |
+| `pricing` | One plan: name, price, period, features, button |
+| `faq` | One question/answer pair, optionally open by default |
+| `alert` | Inline notice (info/warning/…), optionally dismissible |
+| `countdown` | Counts down to a target date |
+| `feedDisplay` | Renders a Feed (§1) — title, summary, image per item |
+| `tagCloud` | Weighted tag list |
+| `relatedContent` | Manual list of related links (`items` JSON prop) |
+| `categorySummary` | One category: name, description, image, count |
+| `categoryList` | Auto-listed child categories under a parent slug |
+| `comments` | Moderated comment thread for the current node |
+
+**Navigation** — wayfinding.
+
+| `name` | Purpose |
+|---|---|
+| `breadcrumbs` | Trail of ancestor links |
+| `navMenu` | A named menu (`menuSlug`) rendered to a depth |
+| `navigation` | Site navigation with a style variant and depth |
+| `siteMap` | Nested list of the site tree |
+| `searchBox` | Compact search input posting to a results URL |
+| `search` | Full search form (method, label, results URL) |
+
+**Personalization**, **Compliance**, and **Saved** (references to things
+authored elsewhere in the admin).
+
+| `name` | Purpose |
+|---|---|
+| `variantContainer` | Module-level arms revealed client-side per audience — read §8 first |
+| `personalizationBadge` | Mount point for the "you're seeing X" transparency control |
+| `socialShare` | Share links for a URL/title across networks |
+| `map` | Embedded map at a lat/lng or address |
+| `cookieConsent` | Consent banner with message + privacy-policy link |
+| `component` | Places a saved reusable component by slug (§4) |
+| `form` | Renders a form built in the Forms admin (§6) |
+| `formEmbed` | Embeds a form by slug — lighter-weight placement of the same |
+
+### Which do I reach for? (in order)
+
+1. **A built-in already does it** → use it. Read the tables before inventing
+   anything; "the palette is thin" is almost always "I didn't look".
+2. **Prose, a heading, an image, a link** → `richText` / `heading` / `image` /
+   `button`. Never build a module to hold copy.
+3. **A repeating set of items** → a collection: folder + Feed + `feedDisplay`
+   (§1). Know the ceiling: Feed Display renders **title, summary and image
+   only**. If the cards need a price or a job title, denormalize it into
+   `summary` at authoring time, or build a custom module that reads the feed.
+4. **The same designed section on several pages** → build it once and **Save as
+   Component** (§4). Zero code, live references, owner-editable.
+5. **A composition or brand block the palette genuinely lacks** — media⇄text
+   split, stat callout, steps band, tabbed code sample, diagram frame → **one
+   custom module, reused**. Not a one-off `html` blob pasted per page.
+
+### Custom modules
+
+Three steps, all required: `defineModule({ name, label, component, category,
+props })` in `kywi.config.ts` `modules: []`; a `'use client'` React component
+taking `{ props }: { props: Record<string, unknown> }`; an entry in
+`lib/modules.tsx` `moduleComponents` keyed by the same `name`. Skip the third
+and the module renders "Unknown module" in the editor *and* on the live page.
+Full recipe, worked example and hazards: the **`kywi-custom-modules` skill**.
+
+**Design the props for the owner, not for yourself.** The props panel gives the
+owner real controls for `text`/`textarea`/`richText` (text inputs),
+`image`/`file` (media picker), `boolean` (checkbox) and `number`/`date`/`color`
+(native inputs); `select`, `slug`, `relationship` and `multiSelect` fall back to
+a plain text input, so name the allowed values in the label. A `json` prop is a
+raw JSON textarea — developer territory. A "three stats" module with `stats: {
+type: 'json' }` has taken the copy away from the owner; the same module with
+`stat1Value` / `stat1Label` … as `text` props hasn't.
+
+**Declare the primary copy prop first.** The front-of-site editor makes a
+module's *first* prop inline-editable on the page when its type is `text`,
+`textarea` or `richText` — so `props: { headline, … }` can be typed over
+directly on the live page, and `props: { variant, headline, … }` cannot.
+
+Also: create **saved layouts** (Layouts admin) as page templates — "Landing
+page", "Case study" — so new pages start from a consistent skeleton. Hand-written
+JSX stays fine for genuinely fixed chrome (a bespoke 404, legal boilerplate) —
+but if marketing will ever want to swap a headline, it's a layout page.
 
 ## 6. Forms: always the Forms builder
 
@@ -209,6 +370,48 @@ default variant must stand alone (personalization is progressive enhancement);
 one experiment per conversion goal, and let it conclude before layering more.
 If no, skip it — the machinery is there when they grow into it.
 
+### Variant containers: pick the right shape
+
+Two different things are called `variantContainer`, and they are not
+interchangeable.
+
+- **Section-level** — a *region* node, sibling of sections (`defaultSections` +
+  `variants[].sections`). Resolved **on the server** from the visitor's audience
+  or experiment arm, so the first paint is already correct: no flash, and the
+  page is complete with JavaScript off. This is the default for anything the
+  server can know — rule-based audiences (UTM, referrer, the `kywi_audience`
+  pin) and A/B experiments. Since 0.6.3 it also renders in the layout editor as
+  a badged block with an **arm switcher**, each arm editable with the ordinary
+  section/column/module tools, so server-resolution no longer costs the owner
+  their editing surface.
+- **Module-level** — the `variantContainer` *module*, placed in a column; its
+  arms are HTML strings (`defaultContent`, `variants: [{audienceId, label,
+  content}]`). Every arm ships in the HTML (default visible, the rest
+  `display:none`) and the browser runtime reveals the matching one. Use it
+  **only for signals the server cannot read at first paint** — in practice, a
+  self-ID answer held in `localStorage`.
+
+Four traps, each of which fails silently:
+
+1. **Use the layout module, not the React component.** `VariantContainer.tsx`
+   (`core/src/components/personalization/`) has a loading branch that renders
+   the skeleton and nothing else — a JS-off visitor gets an empty container —
+   and its `ab_test` path draws a fresh `Math.random()` per render, so the same
+   visitor sees a different arm on every refresh. The layout module
+   (`VariantContainerModule`) always renders the default arm.
+2. **Leave `skeleton` off.** With `skeleton: true` the container ships
+   `aria-busy="true"` and only the client runtime clears it — a JS-off visitor
+   sits in a loading state forever.
+3. **An audience match beats the experiment.** `resolveVariant` returns the
+   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 badge no-op silently unless the built
+   `@kywi-software/js` bundle is at `public/kywi.js`.
+
+Standing rule: **the default arm must be complete on its own.** It is what
+search engines, answer engines, and every opted-out visitor receive.
+
 ## 9. Editorial workflow: drafts, review, versions
 
 For any site with more than one author — or an owner who wants a safety net —
@@ -288,6 +491,8 @@ early, so ask at scoping time.
 - Marketing imagery in `/public`.
 - A "blog" that is a folder of `.mdx` files the owner can't edit.
 - One-off content types created in config for shapes the owner will evolve.
+- A page built as a flat stack of full-width `heading` + `richText` modules.
+- A custom module whose owner-facing copy lives in a `json` prop.
 - Personalization built speculatively, with no owner request behind it.
 - Direct-publish-only workflow on a multi-author site.
 

package/assets/kywi-custom-modules-skill.md

@@ -0,0 +1,172 @@
+---
+name: kywi-custom-modules
+description: Use when a page needs a block the built-in module palette doesn't have — a media/text split, stat callout, steps band, tabbed code sample, diagram frame, branded hero — or whenever you catch yourself pasting bespoke markup into an `html` module or writing a page section as JSX. Covers when a custom module is the right call, the three-step recipe, owner-editable props, and the hazards that break SSR, JS-off visitors, or the owner's editing surface.
+---
+
+# Build a custom module (only when the palette falls short)
+
+A custom module is a React component the *developer* owns and the *owner*
+places and configures. It's the right tool for composition the built-in palette
+lacks — and the wrong tool for anything the palette already does, for copy, and
+for one-off page decoration.
+
+## Workflow
+
+### 1. Confirm you need one
+
+Walk the ladder in AGENTS.md §5 first: built-in module → `richText`/`heading`/
+`image`/`button` → collection + `feedDisplay` → saved component → custom module.
+
+**Build one when:**
+
+- The page needs a *composition* the palette has no shape for: media⇄text
+  split, stat/metric callout row, numbered steps band, tabbed code sample,
+  diagram frame, a hero with a product visual beside the copy.
+- The same brand-specific block will recur across pages and needs consistent
+  markup and styling.
+- A built-in is 90% right but needs different markup — register a module with
+  the built-in's `name` to **override** it everywhere (editor and public site).
+
+**Don't build one when:**
+
+- A built-in covers it. Read the §5 palette tables; "the palette is thin" is
+  almost always "I didn't look".
+- It's copy. Copy goes in `richText` — a module per paragraph is a smell.
+- It's a repeating set of items. That's a collection (folder + feed +
+  `feedDisplay`), not a module with a hardcoded array.
+- It'd be used once, on one page. Compose it from built-ins, or if the design
+  is genuinely bespoke chrome, keep it in the page component and accept that
+  the owner can't edit it — deliberately, and say so at handover.
+- You'd need it because the owner's content doesn't fit `feedDisplay`'s
+  title/summary/image ceiling. Denormalizing into `summary` is usually cheaper.
+
+### 2. Design the props before writing the component
+
+The props *are* the owner's editing surface. Decide, field by field, who edits
+it — then pick the type:
+
+| Prop type | Editor control | Use for |
+|---|---|---|
+| `text` | text input | headlines, eyebrows, labels, stat values |
+| `textarea` | multi-line input | short body copy, quotes |
+| `richText` | rich-text input | owner-authored HTML body copy |
+| `image` / `file` | media picker | anything from the Media library |
+| `boolean` | checkbox | layout flips (`reverse`), show/hide |
+| `number` / `date` / `color` | native inputs | counts, deadlines, accents |
+| `select` / `slug` / `relationship` | plain text input (today) | constrained values — name the options in the label |
+| `json` | raw JSON textarea | **developer territory** — structure the owner never edits |
+
+Two rules that decide whether the module is really editable:
+
+- **Keep owner copy out of `json`.** `stats: {type:'json'}` hands the owner a
+  JSON blob; `stat1Value` / `stat1Label` / `stat2Value` … as `text` props hands
+  them fields. Use `json` only for structure that never changes after build.
+- **Declare the primary copy prop first.** The front-of-site editor makes a
+  module's *first* prop inline-editable on the live page when its type is
+  `text`, `textarea` or `richText`. Put the headline first; put `variant` and
+  layout switches after it.
+
+### 3. Register it — `defineModule` in `kywi.config.ts`
+
+```ts
+import { defineKywiConfig, defineModule } from '@kywi-software/core/config'
+
+export default defineKywiConfig({
+  // …sites, themes, contentTypes…
+  modules: [
+    defineModule({
+      name: 'splitFeature',            // the layout node `type` + MCP add_module type
+      label: 'Media / text split',     // what the owner sees in the palette
+      component: 'splitFeature',       // the key you'll map in lib/modules.tsx
+      category: 'Marketing',           // groups it in the palette
+      props: {
+        heading: { type: 'text', label: 'Heading' },       // first = inline-editable
+        body: { type: 'richText', label: 'Body' },
+        image: { type: 'image', label: 'Image' },
+        imageAlt: { type: 'text', label: 'Image alt text' },
+        reverse: { type: 'boolean', label: 'Image on the left', defaultValue: false },
+      },
+    }),
+  ],
+})
+```
+
+### 4. Write the component
+
+```tsx
+// lib/split-feature.tsx
+'use client'
+import { resolveMediaRef } from '@kywi-software/core/layout'
+
+export function SplitFeature({ props }: { props: Record<string, unknown> }) {
+  const src = resolveMediaRef(props.image)   // media UUID → public file URL
+  return (
+    <div className={`split-feature${props.reverse === true ? ' is-reversed' : ''}`}>
+      <div className="split-feature__copy">
+        <h2>{String(props.heading ?? '')}</h2>
+        <div dangerouslySetInnerHTML={{ __html: String(props.body ?? '') }} />
+      </div>
+      {src ? <img src={src} alt={String(props.imageAlt ?? '')} /> : null}
+    </div>
+  )
+}
+```
+
+Every prop is `unknown` — coerce and default each one. A module that throws on a
+missing prop breaks the editor canvas as well as the page.
+
+### 5. Map it in `lib/modules.tsx`
+
+```tsx
+import { SplitFeature } from './split-feature'
+
+export const moduleComponents: ModuleComponentMap = {
+  splitFeature: SplitFeature,
+}
+```
+
+This one map is passed to both `KywiAdminApp` and `KywiLayout`, so the module
+renders identically in the editor canvas and live. **Skip this step and the
+module renders "Unknown module" in both** — the most common custom-module bug.
+The host merges `{ ...BUILT_IN_MODULE_COMPONENTS, ...moduleComponents }`, so an
+entry named after a built-in replaces it.
+
+### 6. Hazards checklist
+
+- **Unique ids need `React.useId()`.** A module-scope counter produces different
+  ids on server and client and breaks hydration. Same for `Date.now()` and
+  `Math.random()` in render.
+- **Escape owner text inside `<script type="application/ld+json">`.** Replace
+  every `<` with the JS escape `\u003c`, break up `-->`, and escape the line
+  separators U+2028/U+2029 (matched via
+  `String.fromCharCode(0x2028, 0x2029)`) — otherwise a stray character in owner
+  copy ends the script tag early.
+- **`dangerouslySetInnerHTML` is the pattern for `richText`/HTML props** — the
+  values are sanitized by Kywi before storage and on render. Don't reach for it
+  for plain `text` props.
+- **Stay safe with JavaScript off.** A `'use client'` module still server-renders
+  its initial HTML — but anything that only appears after an effect is invisible
+  to crawlers and JS-off visitors. Interactivity is progressive enhancement over
+  complete server-rendered markup.
+- **Style through theme tokens** (`var(--kywi-color-primary)`, `--kywi-spacing-*`)
+  in the site stylesheet, not hardcoded hex — the owner retunes the theme from
+  `kywi.config.ts` and your module should follow.
+- **Don't fetch in the module.** Data comes from props (or, for feeds, the
+  host's server-side hydration). A module that fetches breaks the editor canvas.
+
+### 7. Verify
+
+1. Restart the dev server (config changes need a restart).
+2. Open the layout editor: the module appears in the palette under its
+   `category`, with its `label`.
+3. Place it, fill every prop from the props panel, save — it renders in the
+   canvas (not "Unknown module") and on the public page.
+4. Open the public page as a signed-in admin → **Edit this page**: the first
+   text prop is editable by typing on the page.
+5. Load the page with JavaScript disabled: the content is all there.
+
+### 8. Handover note
+
+Record the module in `CONTENT-MODEL.md` (reusable components / modules) with one
+line per prop: what the owner changes and where. A module the owner doesn't know
+exists is a module they'll ask a developer to change.

package/lib/templates.mjs

@@ -102,7 +102,7 @@ function packageJson(a) {
 /** @param {Answers} a */
 function kywiConfig(a) {
   const providers = a.authProviders.map((p) => `'${p}'`).join(', ')
-  return `import { defineKywiConfig, defineSite, defineTheme } from '@kywi-software/core/config'
+  return `import { defineKywiConfig, defineSite, defineTheme, 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
@@ -179,9 +179,14 @@ export default defineKywiConfig({
     }),
   ],
 
-  // 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\`.
+  // Config-defined content types. "Page" ships so a fresh site can create and
+  // publish pages immediately — that's the floor, not the pattern.
+  //
+  // DEFAULT: create your own types in the admin's **Type Designer**
+  // (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\`.
   contentTypes: [
     {
       name: 'page',
@@ -190,6 +195,29 @@ export default defineKywiConfig({
       fields: [],
     },
   ],
+
+  // Custom layout modules (\`defineModule\`) — the palette additions this project
+  // owns. Register a module here, then map its \`name\` → the React component that
+  // renders it in \`lib/modules.tsx\` (both the admin editor and the public site
+  // read that map). Reach for one only when the built-in palette genuinely lacks
+  // the composition; see AGENTS.md §5 and the \`kywi-custom-modules\` skill.
+  //
+  //   modules: [
+  //     defineModule({
+  //       name: 'splitFeature',          // layout node \`type\` + MCP add_module type
+  //       label: 'Media / text split',   // what the owner sees in the palette
+  //       component: 'splitFeature',     // the key you map in lib/modules.tsx
+  //       category: 'Marketing',
+  //       props: {
+  //         // First text prop = inline-editable on the live page. Keep owner
+  //         // copy in text/textarea/richText props, never in a json blob.
+  //         heading: { type: 'text', label: 'Heading' },
+  //         body: { type: 'richText', label: 'Body' },
+  //         image: { type: 'image', label: 'Image' },
+  //       },
+  //     }),
+  //   ],
+  modules: [],
 })
 `
 }
@@ -2150,7 +2178,10 @@ in \`kywi.config.ts\` (\`modules: [defineModule({ name: 'pricingTable', … })]\
 then map its \`name\` to the React component that renders it in \`lib/modules.tsx\`.
 That one map is passed to both the admin editor and the public site, so a custom
 module renders identically in the canvas and live (it shows an "Unknown module"
-placeholder until you add the entry). See the worked example in \`lib/modules.tsx\`.
+placeholder until you add the entry). See the commented example in
+\`kywi.config.ts\`, the worked example in \`lib/modules.tsx\`, and the
+\`kywi-custom-modules\` skill for when a custom module is the right call at all —
+the built-in palette (47 modules) covers most of what a site needs.
 
 ### Create your first page
 
@@ -2171,12 +2202,10 @@ ${themingBlock}
 ## Project layout
 
 \`\`\`
-kywi.config.ts                    your config: sites, themes, content types, auth, mode, admin.features
+kywi.config.ts                    your config: sites, themes, content types, custom modules, auth, mode, admin.features
 AGENTS.md                         guidance for AI agents working on this site (Kywi's building patterns)
 CLAUDE.md                         points AI agents to AGENTS.md
-.claude/skills/kywi-content-model/SKILL.md  content-model skill (loaded automatically)
-.claude/skills/kywi-collections/SKILL.md  collections skill (loaded automatically)
-.claude/skills/kywi-personalization/SKILL.md  personalization skill (loaded automatically)
+${SKILLS.map(({ slug }) => `.claude/skills/${slug}/SKILL.md  ${slug.replace(/^kywi-/, '')} skill (loaded automatically)`).join('\n')}
 middleware.ts                     auth gate + session refresh + cookie→bearer bridge
 next.config.mjs                   required Next config to consume @kywi-software/core
 lib/kywi.ts                       server runtime (DB, API handler, content scope)
@@ -2223,6 +2252,38 @@ function agentPatternsDoc() {
   return _agentPatternsDoc
 }
 
+/**
+ * Version of the agent-guidance SURFACE (this AGENTS.md shape + the skill set),
+ * independent of the package version. Bump when the guidance changes in a way a
+ * retrofitted app should pick up (new skill, restructured patterns doc), so an
+ * app can compare its stamp against a newer create-kywi-app and know it's stale.
+ */
+export const GUIDANCE_VERSION = 1
+
+/**
+ * This package's own version, read from its package.json (resolved relative to
+ * THIS module, same mechanism as {@link agentPatternsDoc}). Cached.
+ * @returns {string}
+ */
+let _pkgVersion
+function packageVersion() {
+  if (_pkgVersion === undefined) {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+    _pkgVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version
+  }
+  return _pkgVersion
+}
+
+/**
+ * The staleness stamp emitted as AGENTS.md's first line — an HTML comment, so it
+ * is invisible when the file is rendered but greppable by tooling and by an agent
+ * asking "is this project's guidance current?".
+ * @returns {string}
+ */
+export function guidanceStamp() {
+  return `<!-- kywi-agent-guidance v${GUIDANCE_VERSION} (create-kywi-app ${packageVersion()}) -->`
+}
+
 /**
  * Kywi's Claude Code project skills — each ships as a package asset and is
  * embedded verbatim into every generated app's .claude/skills/<slug>/SKILL.md
@@ -2235,6 +2296,9 @@ export const SKILLS = [
   { slug: 'kywi-content-model', asset: 'kywi-content-model-skill.md' },
   // When adding any collection: folder + feed + Feed Display, end to end.
   { slug: 'kywi-collections', asset: 'kywi-collections-skill.md' },
+  // When the built-in module palette falls short: the defineModule recipe,
+  // owner-editable props, and the SSR/JS-off hazards.
+  { slug: 'kywi-custom-modules', asset: 'kywi-custom-modules-skill.md' },
   // When the owner wants personalization/A-B: confirm the use case, then build.
   { slug: 'kywi-personalization', asset: 'kywi-personalization-skill.md' },
 ]
@@ -2406,10 +2470,13 @@ export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
   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-custom-modules/SKILL.md\` — custom-module skill, loaded
+  automatically when the built-in module palette falls short.`)
   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}
+  const header = `${guidanceStamp()}
+# Agent guide — ${a.projectName}
 
 ${intro}
 ${modeSentence}
@@ -2451,7 +2518,7 @@ holds Kywi's official building patterns and a map of where things live in this a
 
 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 and personalization.
+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.
 `
 }
 

package/package.json

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