create-kywi-app 0.3.1 → 0.4.0

package/README.md

@@ -64,6 +64,22 @@ next.config.mjs                    the FULL config to consume core (transpilePac
 .env.example                       DATABASE_URL + AUTH_SECRET
 .gitignore
 README.md                          project-specific quick start (createdb, migrate, seed, dev, /admin, admin.features)
+AGENTS.md                          guidance for AI agents working on this site: an app-specific
+                                   header (where things live, the /admin URL, the CLI, the three
+                                   scaffolded Claude Code skills) + Kywi's official building
+                                   patterns (docs/agents/AGENT-PATTERNS.md, verbatim)
+CLAUDE.md                          thin pointer that sends a Claude Code session to AGENTS.md first,
+                                   plus a nudge toward the kywi-content-model skill (and the other
+                                   two scaffolded skills)
+.claude/skills/kywi-content-model/SKILL.md  Claude Code project skill: design a CONTENT-MODEL.md and get
+                                   owner sign-off before creating types or entering content — loaded
+                                   automatically by Claude Code, a pre-build checklist for other agents
+.claude/skills/kywi-collections/SKILL.md  Claude Code project skill: build any collection (testimonials,
+                                   logos, posts, products, …) as folder + feed + Feed Display — loaded
+                                   automatically when adding a collection
+.claude/skills/kywi-personalization/SKILL.md  Claude Code project skill: confirm the use case, then
+                                   build audiences, page variants, or A/B experiments — loaded
+                                   automatically when the owner wants personalization or A/B testing
 lib/kywi.ts                        server runtime: DB, API handler, content scope (memoised)
 lib/config.ts                      re-export of kywi.config
 middleware.ts                      auth gate + session refresh + cookie→bearer bridge (over core/host)

package/assets/agent-patterns.md

@@ -0,0 +1,294 @@
+# Kywi Patterns — building sites end users can maintain
+
+Guidance for agents building Kywi sites. These are opinions, not rules — a
+developer can overrule any of them — but they encode what Kywi is *for*: sites
+that get handed to non-developers who keep them alive without you. Follow them
+unless the project has a stated reason not to.
+
+## The core principle
+
+**If a non-developer might ever want to change it, model it in the CMS — don't
+hardcode it.** Every hardcoded testimonial array, pasted-in logo grid, or
+copy-edited JSX headline is a future support request. The test before writing
+any markup: *"When the site owner wants this different next month, do they
+edit content in the admin, or do they need a developer?"* If the answer is
+"developer," reach for one of the patterns below instead.
+
+Static code is for structure and brand chrome. Content — anything with words,
+images, prices, names, dates — belongs in Kywi.
+
+## 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 —
+types bolted on mid-build, collections discovered after their items were
+entered as free-form pages, taxonomy retrofitted onto a hundred nodes. Content
+entry is the costly part; planning is cheap. So **start every new site (or any
+significant new content area) by proposing the content model and getting the
+owner's sign-off before creating types or entering content.**
+
+Produce a short `CONTENT-MODEL.md` at the project root covering:
+
+- **Content inventory → types.** Every repeated shape, with its proposed type
+  (built-in page vs. custom), fields (name, field type, required), and
+  relationships. One table per type.
+- **Site tree sketch.** Top-level pages and a folder per collection (§1).
+- **Feeds.** Name, source type, taxonomy filter, sort/limit, and which pages
+  display each one.
+- **Taxonomy.** The category sets and expected tags (§3).
+- **Reusable components.** The sections that will appear on multiple pages (§4).
+- **Maintenance notes.** Who edits what; whether review workflow (§9), i18n
+  (§11), or scheduling (§10) apply.
+- **Open questions** for the owner.
+
+Present it, iterate, and get explicit approval — then build in playbook order.
+Keep the file updated as the model evolves; it's the site's living map.
+
+Proportionality applies (this is guidance, not law): a single-page brochure
+site needs a few sentences of confirmation, not a document. But anything
+involving custom types, collections, or more than a handful of pages deserves
+the full proposal — ten minutes of sign-off beats re-entering fifty nodes.
+
+## Quick decisions
+
+| You're about to… | Do this instead |
+|---|---|
+| Hardcode a list (testimonials, logos, posts, products, team) | Folder of nodes + a Feed + the Feed Display module (§1) |
+| Create one-off pages with identical field shapes | A custom content type + one node per item (§2) |
+| 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) |
+| 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) |
+| Let everyone publish straight to the live site | Configure groups + review workflow (§9) |
+| "Launch this next Tuesday" by deploying on Tuesday | Scheduled publishing / a changeset (§10) |
+
+---
+
+## 1. Collections: folders + feeds + Feed Display
+
+**The workhorse pattern.** Any repeating set of items that appears somewhere on
+the site — customer logos, testimonials, recent blog posts, products, portfolio
+pieces, team members, FAQs, press mentions — is a collection, and collections
+are never hardcoded.
+
+- **Structure:** a folder in the Site Tree per collection (`/testimonials`,
+  `/customers`, `/work`), one content node per item. Items that need their own
+  public page (blog posts, portfolio pieces) live at real paths; items that are
+  only ever displayed in aggregate (logos, quotes) still get nodes — their pages
+  just aren't linked.
+- **Query:** create a Feed (admin → Feeds): pick the content type, filter by
+  taxonomy, sort, and limit ("6 most recent posts", "testimonials tagged
+  `homepage`").
+- **Display:** place the **Feed Display** module wherever the collection should
+  render — home page hero strip, interior sidebars, a `/blog` index. One feed
+  can feed many pages.
+- **Why it wins:** the owner adds a testimonial by creating one node. Every
+  page showing that feed updates. No layout edits, no deploys.
+
+Advanced: product catalogs and portfolios are the same pattern with a richer
+custom type (§2) and taxonomy-driven feeds per category (§3). Multiple feeds
+over one collection give different slices (featured vs. all, per-category).
+
+## 2. Structured data: custom content types
+
+When several nodes share the same shape — recipes (ingredients, steps, prep
+time), team profiles (role, bio, headshot, links), products (price, SKU,
+gallery), case studies (client, industry, outcome) — define a **custom content
+type** so the shape is enforced and the data is queryable, instead of burying
+it in free-form body text.
+
+**Default: create types in the admin (Type Designer), not in kywi.config.ts.**
+Admin-created types are runtime-managed: the site owner can add a field next
+year ("dietary tags on recipes") without a developer or a migration. Reserve
+config-defined types (`contentTypes` in `kywi.config.ts`) for schema the
+*developer* must own — shapes that code depends on, reviewed in git, migrated
+by `kywi migrate`. When in doubt, admin-created.
+
+- Fields available include text, textarea, rich text, date, image, URL, email,
+  JSON, and relationship (with a target type — e.g. a recipe's `author` →
+  profile). Title can be made optional per type.
+- **Combine with §1:** the type gives you structure; a feed over the type gives
+  you the listing (`/recipes` index, an intranet's people directory); each
+  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.
+
+## 3. Taxonomy: categories & tags
+
+Categories and tags are the cross-cutting organization layer over §1 and §2.
+Use **categories** for a site's stable sections (Recipes: Breakfast / Dinner /
+Dessert) and **tags** for freeform, evolving labels (gluten-free, quick,
+featured).
+
+- Feeds filter by taxonomy, so "show featured testimonials on the home page"
+  is: tag the nodes `featured`, point the feed at the tag. The owner curates
+  the home page by tagging — never by editing the page.
+- Prefer taxonomy-driven feeds over separate folders when items belong to
+  multiple groupings (a recipe is both `quick` and `vegetarian`; a folder can
+  only hold it once).
+
+## 4. Reusable components: edit once, propagate everywhere
+
+Anything designed once and used on multiple pages — CTA bands, promo banners,
+newsletter signup blocks, campaign snippets, "as seen in" strips — should be a
+**reusable component**, not copy-pasted sections.
+
+- In the layout editor, select the module and **Save as Component**; insert it
+  elsewhere from the component picker. Placed instances are **live
+  references**: editing the source component updates every page that uses it.
+- **Detach** an instance when a page genuinely needs a one-off variant — it
+  becomes an independent copy from that point on.
+- Rule of thumb: the second time you paste the same section, stop and make it
+  a component. The owner should be able to update the sitewide CTA in one
+  place, ten minutes before their webinar.
+
+## 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.
+
+## 6. Forms: always the Forms builder
+
+Never hand-code a `<form>`. Build forms in the Forms admin (fields, multi-step,
+success message, notification emails, optional reCAPTCHA via Settings →
+Security) and place them with the **Form / Form Embed** modules, which submit
+through Kywi's pipeline into admin → Submissions.
+
+- The owner edits fields, recipients, and the thank-you message without code.
+- Submissions are stored, browsable, and exportable — a hand-rolled form that
+  emails someone is data loss with extra steps.
+
+## 7. Media: the library, not /public
+
+All owner-managed imagery — logos, hero images, headshots, product shots —
+goes through the Media library (upload, alt text, automatic variants,
+on-demand resize). Reserve `/public` for build-time brand assets (favicon,
+font files) that only change when the code does.
+
+The difference matters at handover: the owner can swap a hero image in the
+library; they cannot ship a new `/public` file.
+
+## 8. Personalization & A/B testing — offer it, don't default to it
+
+Kywi ships a full personalization stack: **audiences** (rule-based, plus an
+optional self-identification widget), **page variants** targeted per audience,
+and **A/B experiments** with stable per-visitor assignment and recorded
+exposures. Most sites don't need it on day one — and unrequested
+personalization is complexity the owner didn't ask to maintain.
+
+**The agent's job is to surface the capability, not to assume it.** When
+scoping a build, ask the owner whether any of these fit, with examples:
+
+- *"Should returning visitors see a different home-page hero than first-timers
+  (e.g. 'Welcome back — pick up where you left off')?"*
+- *"Do you serve distinct segments (agencies vs. freelancers, industries,
+  regions) that should get tailored messaging on key pages?"*
+- *"Would you like visitors to self-identify (e.g. 'I'm a developer / I'm a
+  marketer') and see content ordered for them?"*
+- *"Is there a headline, CTA, or pricing presentation you'd like to A/B test
+  before committing?"*
+
+If yes, principles: personalize **sections and modules**, not whole sites; the
+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.
+
+## 9. Editorial workflow: drafts, review, versions
+
+For any site with more than one author — or an owner who wants a safety net —
+configure the workflow rather than letting everything publish directly:
+
+- **Groups & permissions:** editors write (`draft → Submit for Review`),
+  a smaller group approves and publishes. Content-level permissions can gate
+  specific sections (e.g. only Legal edits `/legal/*`).
+- Published pages accept **pending revisions** — edits go through review while
+  the live page keeps serving — so review doesn't mean taking pages down.
+- Every save records a **version** with restore; approvers see field-level
+  diffs. Mention this at handover: "you can always roll back."
+
+Solo-owner sites can publish directly — but still enable it before the team
+grows past one.
+
+## 10. Scheduling & changesets
+
+- Content has schedule fields: publish at a future time, unpublish/expire
+  automatically. The background scheduler handles both — "post this Monday 9am"
+  is a field, not a calendar reminder.
+- **Changesets** batch related edits (a product launch touching six pages) and
+  publish them together, optionally on a schedule. Use one whenever a launch
+  spans multiple nodes — partial launches are worse than late ones.
+
+## 11. Multilingual sites
+
+If the owner needs more than one language, declare `locales` in
+`kywi.config.ts` up front — the scaffold routes locale prefixes (`/es/...`),
+falls back to the default locale, and emits hreflang alternates. Translations
+are per-node in the admin. Retrofitting i18n is far costlier than declaring it
+early, so ask at scoping time.
+
+## 12. SEO & the Agent Experience layer
+
+- Fill the **SEO tab** on every page that matters (meta title/description,
+  og:image); the scaffold maps it into the public head and emits JSON-LD.
+- The AX layer serves `llms.txt`, `llms-full.txt`, `sitemap.xml`, and
+  `robots.txt` at the site root out of the box — a Kywi site is legible to
+  agents and crawlers by default. Don't remove these routes; they're part of
+  the product's value.
+
+## Other capabilities worth knowing
+
+- **Comments:** a moderated Comments module (submissions land pending) for
+  blogs/community pages — ask the owner if discussion fits.
+- **Webhooks** (Web Services → Webhooks): notify external systems on content
+  events (rebuild a static mirror, ping Slack, sync a CRM) — signed, retried.
+- **API keys** with enforced scopes: hand a read-only key to a partner or a
+  frontend without exposing write access.
+
+## Build-order playbook (new site)
+
+0. **Propose the content model and get sign-off** ("Before you build", above)
+   — nothing else starts until the owner approves it.
+1. **Model first:** custom content types for every repeated shape (§2).
+2. **Structure:** site tree — pages, folders per collection (§1).
+3. **Taxonomy:** categories/tags the feeds will need (§3).
+4. **Media:** upload the brand's assets to the library (§7).
+5. **Templates:** saved layouts + reusable components for the recurring
+   sections (§4, §5); custom modules only where the palette falls short.
+6. **Wire collections:** feeds + Feed Display placements (§1).
+7. **Forms:** contact/newsletter/etc. in the builder (§6).
+8. **Workflow:** groups, permissions, review path (§9).
+9. **Ask about** personalization/A-B (§8), comments, webhooks, i18n (§11).
+10. **SEO pass** (§12), then hand over: show the owner where *their* edits
+    live — content nodes, feeds, components — and confirm nothing they'll want
+    to change requires you.
+
+## Anti-patterns (smells)
+
+- Creating types and entering content before the owner signed off on a
+  content model.
+- A hardcoded array of testimonials/logos/posts in a page component.
+- The same CTA JSX pasted on four pages.
+- A `<form>` that POSTs to a hand-rolled route (or nowhere).
+- 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.
+- Personalization built speculatively, with no owner request behind it.
+- Direct-publish-only workflow on a multi-author site.
+
+Every one of these has a section above. If you catch yourself mid-smell, refactor to the pattern before handover — it's minutes now, migrations later.

package/assets/kywi-collections-skill.md

@@ -0,0 +1,73 @@
+---
+name: kywi-collections
+description: Use when adding ANY collection to this Kywi site — testimonials, customer logos, blog posts, products, portfolio pieces, team members, FAQs, press mentions — or whenever you catch yourself about to hardcode a repeating list of items in a page. Walks the folder + feed + Feed Display pattern end to end.
+---
+
+# Build a collection: folder + feed + Feed Display
+
+Collections are never hardcoded. A collection is any set of similar items that
+grows over time and is displayed somewhere — the owner must be able to add an
+item in the admin and see every relevant page update, with no code changes.
+
+## Workflow
+
+### 1. Recognize the collection
+
+About to write an array of testimonials, a grid of logos, a list of cards in
+JSX? Stop — that's a collection. Confirm the shape: what fields does one item
+have, and where on the site do items appear (one page? several? aggregate-only
+or does each item need its own page)?
+
+### 2. Model the item type
+
+- Items with structure beyond title/body/image (products, recipes, profiles)
+  → create a custom content type first (admin → Content Types; admin-created
+  by default so the owner can evolve it). Match the approved `CONTENT-MODEL.md`
+  — if this collection isn't in it, update the model and confirm the addition
+  with the owner before building.
+- Simple items (a quote + attribution, a logo + link) can use an existing or
+  minimal type — don't over-model.
+
+### 3. Structure: a folder in the Site Tree
+
+Create a folder for the collection (`/testimonials`, `/work`, `/customers`)
+and add the initial nodes inside it. Two gotchas:
+
+- **Nodes must be `published`** to appear in public feeds — drafts won't show.
+- Aggregate-only items (logos, quotes) still get nodes; their individual pages
+  simply go unlinked. Items needing detail pages (posts, portfolio pieces)
+  live at real, linkable paths.
+
+### 4. Query: create the Feed
+
+Admin → Feeds → new feed: pick the content type, add taxonomy filters if the
+display is a slice ("testimonials tagged `homepage`"), set sort and limit
+("6 most recent"). **Check the feed preview shows the expected items before
+moving on** — an empty preview means a wrong type, unpublished nodes, or a
+taxonomy term that isn't applied to anything yet.
+
+Multiple slices of one collection = multiple feeds over the same type
+(featured vs. all; per-category).
+
+### 5. Display: place the Feed Display module
+
+In the layout editor on each target page, add the **Feed Display** module and
+select the feed. If the same feed placement (with surrounding design) recurs
+on several pages, save the section as a reusable component instead of
+rebuilding it per page.
+
+Scaffolded apps hydrate feeds server-side automatically. A hand-built host
+must call `hydrateLayoutFeeds` before rendering `KywiLayout` — if the module
+renders an empty list publicly but previews fine in the admin, missing host
+hydration is the usual cause.
+
+### 6. Verify end to end
+
+Publish the page, load it publicly, confirm items render. Then the real test:
+**add one more node to the folder and reload — it must appear without touching
+the page.** If it doesn't, the loop isn't closed; fix before moving on.
+
+### 7. Handover note
+
+Record in `CONTENT-MODEL.md` (feeds table) and tell the owner: "to add a
+<item>, create it in <folder>; it appears on <pages> automatically."

package/assets/kywi-content-model-skill.md

@@ -0,0 +1,94 @@
+---
+name: kywi-content-model
+description: Use BEFORE building out this Kywi site or adding any significant new content area (custom types, collections, structured sections) — designs the content model and gets the owner's sign-off first. The most expensive CMS failure is a poorly planned content model; content entry is costly, planning is cheap.
+---
+
+# Design the content model, then get sign-off
+
+Do not create content types, enter content, or build page layouts for a new
+site or content area until the owner has approved a content model. This is
+guidance, not law — a single-page brochure site needs a sentence of
+confirmation, not a document — but anything with custom types, collections, or
+more than a handful of pages gets the full treatment.
+
+## Workflow
+
+### 1. Discovery — ask before proposing
+
+Understand the site before modeling it. Ask the owner (batch the questions):
+
+- What does the site need to communicate, and to whom?
+- What kinds of content exist or are planned? (posts, products, recipes,
+  people, case studies, events, FAQs, testimonials, locations…)
+- Which of those are *collections* — sets of similar items that grow over time?
+- Who maintains the site after handover, and how technical are they?
+- Multiple authors (→ review workflow)? Multiple languages? Timed launches?
+- Any personalization/A-B interest? (Offer examples; don't assume — see
+  AGENTS.md §8.)
+
+### 2. Draft `CONTENT-MODEL.md` at the project root
+
+Use this template:
+
+```markdown
+# Content model — <site>
+
+## Types
+| Type | Built-in/custom | Purpose | Maintained by |
+|---|---|---|---|
+
+### <each custom type>
+| Field | Type | Required | Notes |
+|---|---|---|---|
+
+## Site tree
+<top-level pages and a folder per collection, as an indented list>
+
+## Feeds
+| Feed | Source type | Filter | Sort/limit | Displayed on |
+|---|---|---|---|---|
+
+## Taxonomy
+Categories: <stable sets>  ·  Tags: <expected freeform labels>
+
+## Reusable components
+| Component | Used on |
+|---|---|
+
+## Maintenance
+Editors/approvers, workflow needs, i18n locales, scheduling needs.
+
+## Open questions
+```
+
+Modeling rules of thumb (full rationale in AGENTS.md):
+
+- Repeated shape → custom type, **admin-created by default** (owners can add
+  fields later without a developer); config-defined only for developer-owned
+  schema.
+- Anything displayed as a list somewhere → collection: folder + feed + Feed
+  Display module. Never a hardcoded array.
+- Cross-cutting groupings → categories (stable) and tags (evolving), queried
+  by feeds.
+- Sections used on 2+ pages → reusable components.
+- Don't shadow built-in fields (title, slug, body); don't invent a type per
+  page — types are for repeated shapes.
+
+### 3. Get explicit sign-off
+
+Present the proposal and iterate. Ask directly: *"Does this content model
+match how you think about your content, and who will maintain each part?"*
+Get an explicit yes before proceeding. If scope is trivial, a one-paragraph
+summary and a "confirm?" suffices.
+
+### 4. Build — only after approval
+
+Follow the build-order playbook in AGENTS.md: types → tree/folders → taxonomy
+→ media → layouts/components → feeds → forms → workflow → (ask about
+personalization, comments, i18n) → SEO pass → handover.
+
+### 5. Keep the model current
+
+`CONTENT-MODEL.md` is a living document. When the model changes later (new
+type, new collection), update the file and re-confirm significant changes with
+the owner. It doubles as the handover map of "where your content lives."

package/assets/kywi-personalization-skill.md

@@ -0,0 +1,72 @@
+---
+name: kywi-personalization
+description: Use when the site owner wants personalization or A/B testing on this Kywi site — audience-targeted content, segment-specific pages, self-identification, or experiments — or before YOU propose any of those. Multi-step - audiences, variants/experiments, preview-token verification, conclusion.
+---
+
+# Personalization & A/B testing — confirmed use case first, then build
+
+**Never build personalization speculatively.** If the owner hasn't asked,
+offer it with concrete examples and let them decide (returning-visitor hero,
+segment-specific messaging, self-identified content ordering, a CTA test).
+Only proceed with a confirmed use case and a stated success measure.
+
+## Workflow
+
+### 1. Confirm the use case and what "working" means
+
+With the owner, pin down: which segment or hypothesis, which page(s) and
+section(s), and what outcome defines success (a conversion, a click-through, a
+qualitative "the right people see the right message"). Write it down — it
+decides the mechanism and when you're done.
+
+### 2. Choose the mechanism
+
+- **Known segment, deterministic content** → audience + **page variant**
+  ("agencies see the agency hero"). No measurement involved.
+- **Hypothesis to measure** → **A/B experiment** ("does the short headline
+  convert better?"). Variants + recorded exposures.
+- **Visitor-declared identity** → **self-ID widget** ("I'm a developer / I'm
+  a marketer") feeding an audience.
+
+### 3. Build the audience (variant and self-ID paths)
+
+Admin → Audiences: define the rules, or configure the self-ID widget and its
+fields. Use the audience test tool to confirm the rules match the intended
+visitors before wiring anything to it.
+
+### 4a. Page-variant path
+
+In the layout editor on the target page: **+ Page Variant** → select the
+audience → edit the variant. Change **only the sections that segment needs** —
+the default variant must remain complete and self-sufficient (personalization
+is progressive enhancement; anonymous visitors get the default).
+
+### 4b. Experiment path
+
+Admin → Experiments: create the experiment. In the layout, add an A/B
+container with an arm per treatment. Assignment is deterministic per visitor
+(the scaffold's middleware issues a persistent `kywi_visitor` cookie), so a
+visitor sees the same arm on every visit — no client runtime needed.
+
+### 5. Verify before calling it done
+
+- **Preview tokens** (Audiences → Preview Tokens): view the page *as each
+  audience* and confirm the right variant serves.
+- Experiments: two fresh browser profiles should get (possibly) different
+  arms, and each profile must get the **same** arm on reload.
+- Confirm exposures are being recorded in the Experiments admin.
+- Load the page as a plain anonymous visitor: the default must be complete.
+
+### 6. Run, conclude, promote
+
+One experiment per conversion goal; let it reach a conclusion before layering
+another on the same page. When it concludes, **promote the winner into the
+base layout and remove the experiment container** — a site accreting stale
+experiments is a maintenance smell.
+
+### 7. Document for handover
+
+Record what is personalized where (and why) in `CONTENT-MODEL.md`'s
+maintenance notes. The owner must know a page has variants before they edit
+it — editing only the default of a heavily-personalized page is a classic
+post-handover surprise.

package/lib/templates.mjs

@@ -32,6 +32,10 @@
  * ships session fixes without the app hand-maintaining crypto.
  */
 
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 /** @typedef {{ projectName: string, dbProvider: 'postgresql'|'mysql', authProviders: string[], mode: 'coupled'|'headless'|'decoupled', kywiVersion: string }} Answers */
 
 const CORE_RANGE = (v) => `^${v}`
@@ -1903,6 +1907,11 @@ ${themingBlock}
 
 \`\`\`
 kywi.config.ts                    your config: sites, themes, content types, 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)
 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)
@@ -1929,6 +1938,150 @@ function escapeJsxText(value) {
   return String(value).replace(/[{}<>]/g, (ch) => `{'${ch}'}`)
 }
 
+// ── Agent guidance (AGENTS.md / CLAUDE.md) ──────────────────────────────────────
+
+/**
+ * Kywi's canonical building-patterns doc, shipped as a package asset and embedded
+ * verbatim into every generated app's AGENTS.md. Resolved relative to THIS module
+ * (import.meta.url), NOT process.cwd(), so it loads from an installed
+ * create-kywi-app the same as from the monorepo. Kept byte-identical to
+ * docs/agents/AGENT-PATTERNS.md by scripts/sync-agent-patterns.mjs (a drift test
+ * guards it). Cached so repeated buildFileSet() calls don't re-read the file.
+ * @returns {string}
+ */
+let _agentPatternsDoc
+function agentPatternsDoc() {
+  if (_agentPatternsDoc === undefined) {
+    const assetPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'agent-patterns.md')
+    _agentPatternsDoc = readFileSync(assetPath, 'utf8')
+  }
+  return _agentPatternsDoc
+}
+
+/**
+ * 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
+ * (all modes, in this order). Exported so tests can iterate the same table
+ * instead of duplicating it.
+ * @type {Array<{ slug: string, asset: string }>}
+ */
+export const SKILLS = [
+  // Before building anything: design the content model, get owner sign-off.
+  { 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 owner wants personalization/A-B: confirm the use case, then build.
+  { slug: 'kywi-personalization', asset: 'kywi-personalization-skill.md' },
+]
+
+/**
+ * Cache of asset filename → file content for scaffolded Claude Code skills,
+ * populated lazily by {@link skillDoc}.
+ * @type {Map<string, string>}
+ */
+const _skillDocCache = new Map()
+
+/**
+ * Read (and cache) one Claude Code skill's SKILL.md asset by filename.
+ * Resolved relative to THIS module (import.meta.url), same mechanism as
+ * {@link agentPatternsDoc}, so it loads from an installed create-kywi-app the
+ * same as from the monorepo. Cached so repeated buildFileSet() calls don't
+ * re-read the file.
+ * @param {string} asset
+ * @returns {string}
+ */
+function skillDoc(asset) {
+  if (!_skillDocCache.has(asset)) {
+    const assetPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', asset)
+    _skillDocCache.set(asset, readFileSync(assetPath, 'utf8'))
+  }
+  return _skillDocCache.get(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.
+ * @param {Answers} a
+ */
+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,
+  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
+  separate frontend against the REST API at \`/api/v1\` with \`@kywi-software/sdk\`.`
+  const header = `# Agent guide — ${a.projectName}
+
+This is a **Kywi CMS** project scaffolded by \`create-kywi-app\` (\`${a.mode}\` mode).
+${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.
+
+## Running it
+
+\`\`\`bash
+pnpm migrate   # apply the schema
+pnpm seed      # create the default site + a superadmin (prints credentials)
+pnpm dev       # http://localhost:3000  (admin at /admin)
+\`\`\`
+
+## Kywi's building patterns
+
+Everything below is **Kywi's official guidance** for building sites end users can
+maintain — read it before adding content, pages, forms, or modules. The rule that
+matters most: **if a non-developer might ever want to change it, model it in the
+CMS instead of hardcoding it.**
+
+---
+
+`
+  return header + agentPatternsDoc()
+}
+
+/**
+ * CLAUDE.md — a thin pointer so a Claude Code session reads AGENTS.md first.
+ * @param {Answers} a
+ */
+function claudeMd(a) {
+  return `# ${a.projectName}
+
+This is a **Kywi CMS** project. **Read \`AGENTS.md\` before building anything** — it
+holds Kywi's official building patterns and a map of where things live in this app.
+
+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.
+`
+}
+
 /**
  * Build the complete map of relative-path → file-content for a project.
  * @param {Answers} answers
@@ -1945,6 +2098,10 @@ 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),
     // server runtime + config
     'lib/kywi.ts': libKywi(),
     'lib/config.ts': libConfig(),
@@ -1969,6 +2126,15 @@ 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.3.1",
+  "version": "0.4.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",
@@ -15,6 +15,7 @@
   "files": [
     "bin",
     "lib",
+    "assets",
     "README.md",
     "LICENSE"
   ],