create-kywi-app 0.6.2 → 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: [],
 })
 `
 }
@@ -755,20 +783,30 @@ export function clientRuntimeEnabled(): boolean {
 
 /** The self-ID widget config in the serializable shape the client runtime reads. */
 export interface PublicSelfIdWidget {
-  fields: Array<{ id: string; label: string; type: 'select'; options?: string[]; required?: boolean }>
+  fields: Array<{
+    id: string
+    label: string
+    type: 'select'
+    options?: Array<{ value: string; label: string }>
+    required?: boolean
+  }>
   headline: string
   subheadline?: string
   submitLabel: string
   skipLabel?: string
-  displayMode: 'modal' | 'inline' | 'slide-in'
+  displayMode: 'modal' | 'inline' | 'slide-in' | 'hello_bar_top' | 'hello_bar_bottom' | 'drawer'
   frequency: 'once' | 'session' | 'always'
   trigger: SelfIdTrigger
 }
 
+// The admin's five display modes (SelfIdWidgetConfig['displayMode']) and the
+// client runtime's (PublicSelfIdWidget['displayMode'], @kywi-software/js) are the
+// same set — the runtime implements hello_bar_top/hello_bar_bottom/drawer as
+// their own layouts, not folded into slide-in (kywi-cms#97) — so this is a
+// passthrough. Kept as a named function (rather than assigning displayMode
+// directly) so the two types stay checked against each other at compile time.
 function mapDisplayMode(mode: SelfIdWidgetConfig['displayMode']): PublicSelfIdWidget['displayMode'] {
-  if (mode === 'modal') return 'modal'
-  if (mode === 'inline') return 'inline'
-  return 'slide-in' // hello bars + drawer both animate in from an edge
+  return mode
 }
 
 function mapFrequency(freq: SelfIdWidgetConfig['frequency']): PublicSelfIdWidget['frequency'] {
@@ -797,7 +835,10 @@ export async function resolveSelfIdWidget(runtime: KywiRuntime): Promise<PublicS
       id: f.id,
       label: f.label,
       type: 'select' as const,
-      options: f.picklist.map((p) => p.value),
+      // {value, label} pairs, not bare values — the client runtime renders the
+      // label and submits the value (kywi-cms#96); dropping the label here is
+      // what made every option render as its raw value.
+      options: f.picklist,
       required: f.required,
     }))
   if (fields.length === 0) return null
@@ -921,10 +962,33 @@ async function fetchFreshAccessToken(origin: string, refreshToken: string): Prom
   }
 }
 
+// Markdown content negotiation by URL suffix. Core serves markdown at
+// \`/api/v1/ax/md/slug/<slug>\` and the AX layer enables it (ax.markdown), but the
+// scaffold never wires the friendly \`/<path>.md\` URL the AX pitch (and the
+// developer copy) names — so it 404s despite the feature being on. Rewrite any
+// GET/HEAD for \`/<path>.md\` onto the core route so the named URL actually
+// resolves. Nested paths keep their full slug (e.g. /docs/foo.md -> docs/foo).
+// Never intercepts Next internals or the API — those never carry this suffix,
+// but are excluded explicitly since the matcher's own exclusion is broad.
+function handleMarkdownNegotiation(req: NextRequest): NextResponse | null {
+  const { pathname } = req.nextUrl
+  if (req.method !== 'GET' && req.method !== 'HEAD') return null
+  if (!pathname.endsWith('.md')) return null
+  if (pathname.startsWith('/api/') || pathname.startsWith('/_next/')) return null
+  const slug = pathname.replace(/^\\//, '').replace(/\\.md$/, '')
+  if (!slug) return null
+  const url = req.nextUrl.clone()
+  url.pathname = '/api/v1/ax/md/slug/' + slug
+  return NextResponse.rewrite(url)
+}
+
 export async function middleware(req: NextRequest): Promise<NextResponse> {
   const { pathname } = req.nextUrl
   if (isAuthEndpoint(pathname)) return NextResponse.next()
 
+  const md = handleMarkdownNegotiation(req)
+  if (md) return md
+
   // Public pages are never auth-gated — just give them a stable visitor id.
   const isAdmin = pathname === '/admin' || pathname.startsWith('/admin/')
   const isApi = pathname.startsWith('/api/v1/')
@@ -980,6 +1044,10 @@ export const config = {
     // any path with a file extension (static assets, /favicon.ico, /kywi.js, and
     // the AX files /robots.txt, /sitemap.xml, /llms*.txt).
     '/((?!_next/|.*\\\\..*).*)',
+    // \`/<path>.md\` — the markdown-negotiation URL. The extension-excluding
+    // pattern above skips it, so it needs its own entry to reach
+    // handleMarkdownNegotiation.
+    '/((?!_next/|api/).*\\\\.md)',
   ],
 }
 `
@@ -1239,12 +1307,17 @@ function hasRenderableLayout(layout: LayoutDocument | null | undefined): layout
 // Is the current visitor a signed-in admin who may edit? The public route is
 // outside the middleware's auth matcher, so verify the httpOnly session cookie
 // here and derive the content permissions the overlay needs. Returns null for
-// anyone who cannot edit — no edit DOM is emitted for them.
+// anyone who cannot edit — no edit DOM (not even the browse-mode toolbar) is
+// emitted for them. Called on EVERY request (not just ?kywi-edit=1 ones) so the
+// toolbar can surface itself for a signed-in admin who is just browsing — this
+// is a cookie read + JWT verify, no DB round-trip, so the cost on an anonymous
+// visitor's fast path is a fast null return (\`readSessionClaims\` bails
+// immediately when there's no cookie).
 async function resolveEditPermissions() {
   const token = (await cookies()).get(ACCESS_COOKIE)?.value
   const claims = await readSessionClaims(token, config.auth.secret)
   if (!claims || !canAccessContent(claims.role, 'write')) return null
-  return { canEdit: true, canPublish: canAccessContent(claims.role, 'publish') }
+  return { canEdit: true, canPublish: canAccessContent(claims.role, 'publish'), role: claims.role }
 }
 
 // "/" resolves the seeded Home node; any other URL resolves the published node at
@@ -1264,9 +1337,13 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
   const featured = mediaUrl(node['featuredImageId'])
   const layout = node['layout'] as LayoutDocument | null | undefined
 
-  // ?kywi-edit=1 opts an authenticated admin into the front-of-site overlay.
+  // Resolved on every request so a signed-in admin gets the persistent browse
+  // toolbar even when just browsing — ?kywi-edit=1 only decides whether the
+  // page auto-enters the full overlay editor on mount (kywi-cms#93). An
+  // anonymous/read-only visitor resolves to perms === null: zero extra client
+  // JS, identical output to before this route ever heard of the overlay.
   const editRequested = (await searchParams)['kywi-edit'] === '1'
-  const perms = editRequested ? await resolveEditPermissions() : null
+  const perms = await resolveEditPermissions()
 
   // Server-side personalization (#50), evaluated once: the winning audience (or a
   // kywi_preview_init preview) drives page variants + variantContainers, and this
@@ -1347,12 +1424,16 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     )
   }
 
-  // Mount the overlay (client) only for an authenticated admin who asked for it.
+  // Mount the overlay (client) for any authenticated admin (write role+) —
+  // browse mode renders just the slim toolbar; ?kywi-edit=1 (editRequested)
+  // additionally auto-starts the full overlay editor. Nothing mounts for an
+  // anonymous or read-only visitor.
   if (perms) {
     return (
       <KywiFrontEdit
         canEdit={perms.canEdit}
         canPublish={perms.canPublish}
+        editRequested={editRequested}
         contentId={contentId}
         contentType={contentType}
         pageTitle={title}
@@ -1372,18 +1453,25 @@ 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).
+ * Front-of-site edit overlay (client). Mounted by the public page for ANY
+ * authenticated admin (write role+) — the page verifies the session cookie
+ * server-side first (resolveEditPermissions, called unconditionally) and only
+ * mounts this when that check passes, so canEdit is always true here.
  *
  * 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.
+ *  - **Browse** (default) — core's slim `KywiEditToolbar`, a persistent
+ *    WordPress-admin-bar-style strip over the live page (page title, draft/
+ *    published status, "Edit this page", "Go to admin") — this is the
+ *    discoverability fix (kywi-cms#93): an admin browsing the public site
+ *    normally, with no query param, now sees the entry point. The editable
+ *    regions are also outlined via the `data-kywi-*` protocol.
+ *  - **Edit** (the toolbar's "Edit this page", or landing with
+ *    `?kywi-edit=1`) — 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. Entering/leaving
+ *    edit mode keeps `?kywi-edit=1` in sync via history.replaceState, so a
+ *    reload (or a shared link) lands back in the same mode.
  *
  * The OverlayShell is lazy-loaded (`next/dynamic`, client-only): its weight
  * (dnd-kit, canvas, side panels) is only fetched when an editor actually enters
@@ -1420,6 +1508,8 @@ const OverlayShell = dynamic(
 export interface KywiFrontEditProps {
   canEdit: boolean
   canPublish: boolean
+  /** True when the page was requested with \`?kywi-edit=1\` — auto-starts the full overlay editor on mount. */
+  editRequested: boolean
   contentId: string
   contentType: string
   pageTitle: string
@@ -1434,13 +1524,19 @@ export interface KywiFrontEditProps {
 }
 
 /**
- * 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
- * permission gate (canEdit) is always satisfied here.
+ * Wraps the public page with the front-of-site edit affordance. The page
+ * renders this for ANY signed-in admin (write role+) — canEdit is always true
+ * here, since the page only mounts KywiFrontEdit once resolveEditPermissions
+ * has already confirmed it server-side. Browse mode shows the persistent
+ * KywiEditToolbar (the primary discoverability fix, kywi-cms#93); the full
+ * OverlayShell editor only mounts once edit mode actually starts — either the
+ * toolbar's "Edit this page" button, or landing with \`?kywi-edit=1\`
+ * (editRequested), which auto-starts it once on mount.
  */
 export function KywiFrontEdit({
   canEdit,
   canPublish,
+  editRequested,
   contentId,
   contentType,
   pageTitle,
@@ -1452,11 +1548,14 @@ export function KywiFrontEdit({
 }: KywiFrontEditProps) {
   const edit = useKywiEditMode({ canEdit, canPublish })
 
-  // ?kywi-edit=1 means "enter edit mode now" — flip it on once after mount.
+  // ?kywi-edit=1 (editRequested) means "enter edit mode now" — flip it on once
+  // after mount. Without it the page mounts straight into browse mode (the
+  // persistent toolbar), which is the common case now that KywiFrontEdit
+  // renders for every signed-in admin, not only deep-linked ones.
   const { startEdit, endEdit } = edit
   React.useEffect(() => {
-    startEdit()
-  }, [startEdit])
+    if (editRequested) startEdit()
+  }, [editRequested, startEdit])
 
   // 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
@@ -1514,15 +1613,23 @@ export function KywiFrontEdit({
   }, [contentId])
 
   // Edit mode: the full layout editor, in place, over the live page.
+  // NOTE: no \`kywi-admin-shell\` here (kywi-cms#94). That class is the admin
+  // design system's base+reset — font family, font size, colours, heading
+  // resets — and wrapping the page in it re-typesets the very content the
+  // owner is trying to judge at real width. The editor chrome carries its own
+  // styling; the page keeps the site's.
   if (edit.isEditMode && edit.canEdit) {
     return (
-      <div className="kywi-admin-shell kywi-frontend-edit">
+      <div className="kywi-frontend-edit">
         <OverlayShell
           editMode={edit}
           initialLayout={initialLayout}
           contentId={contentId}
           contentType={contentType}
           pageTitle={pageTitle}
+          /* The page's own body wrapper, so the site's page-level CSS (width,
+             gutters, rhythm) still applies while editing in place. */
+          pageClassName="page page--layout"
           themeName="default"
           themeRegistry={themeRegistry}
           moduleRegistry={moduleRegistry}
@@ -1969,14 +2076,21 @@ wired in \`app/(site)/[[...slug]]/page.tsx\`). Pages without a layout fall back
 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 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
+**Front-of-site editor.** Signed in as an admin, every public page shows a slim
+toolbar across the top — the page title, its draft/published status, **Edit
+this page**, and **Go to admin** (a WordPress-admin-bar equivalent, and the
+primary way to discover in-place editing; there's also an **Edit on site**
+link on each item in the admin content editor, for the reverse direction).
+Click **Edit this page** — or open a page with \`?kywi-edit=1\` as a deep link —
+to 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). **Done** returns you to the browse toolbar. Entering or
+leaving the editor keeps \`?kywi-edit=1\` in the URL in sync, so reloading (or
+sharing the link) lands back in the same mode. 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
+lazy-loaded, so pages your visitors see never carry its weight — an anonymous
+or read-only visitor gets no toolbar and no extra client JS. 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.
@@ -2064,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
 
@@ -2085,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)
@@ -2137,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
@@ -2149,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' },
 ]
@@ -2320,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}
@@ -2365,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.2",
+  "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",