create-kywi-app 0.3.2 → 0.5.0

package/README.md

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

package/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/bin/create-kywi-app.mjs

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

package/lib/templates.mjs

@@ -32,6 +32,10 @@
  * ships session fixes without the app hand-maintaining crypto.
  */
 
+import { readFileSync, existsSync } 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,282 @@ 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}
+ */
+export 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)
+}
+
+/**
+ * Landmark → its relative path in a Kywi project. A "landmark" is a file whose
+ * presence changes how the AGENTS.md header should describe the app. The scaffold
+ * derives its set statically from the mode ({@link scaffoldLandmarks}); the
+ * `agents` refresh command detects them on disk ({@link detectAgentsLandmarks}),
+ * so the header reflects the REAL project instead of asserting scaffold structure.
+ * One source of truth for the path strings, shared by both.
+ * @type {Record<'adminHost'|'moduleMap'|'middleware'|'libSite'|'sitePage'|'headlessPage', string>}
+ */
+export const AGENTS_LANDMARK_PATHS = {
+  adminHost: 'app/admin/[[...admin]]/page.tsx',
+  moduleMap: 'lib/modules.tsx',
+  middleware: 'middleware.ts',
+  libSite: 'lib/site.ts',
+  sitePage: 'app/(site)/[[...slug]]/page.tsx',
+  headlessPage: 'app/page.tsx',
+}
+
+/**
+ * @typedef {Object} AgentsLandmarks
+ * @property {boolean} scaffolded  Generating for a fresh scaffold (true) vs
+ *   refreshing into an existing project (false). Controls only the intro line's
+ *   "scaffolded by create-kywi-app" claim.
+ * @property {boolean} adminHost   app/admin/[[...admin]]/page.tsx present
+ * @property {boolean} moduleMap   lib/modules.tsx present
+ * @property {boolean} middleware  middleware.ts present
+ * @property {boolean} libSite     lib/site.ts present (the scaffold's public-render helpers)
+ * @property {boolean} sitePage    app/(site)/[[...slug]]/page.tsx present (renders public pages)
+ * @property {boolean} headlessPage app/page.tsx present (the headless/decoupled 404 root)
+ */
+
+/**
+ * The landmark set a FRESH scaffold of the given mode has — derived statically
+ * from the mode, never from the filesystem, so buildFileSet emits AGENTS.md that
+ * is byte-identical to the previous mode-branching implementation.
+ * @param {'coupled'|'headless'|'decoupled'} mode
+ * @returns {AgentsLandmarks}
+ */
+export function scaffoldLandmarks(mode) {
+  const coupled = mode === 'coupled'
+  return {
+    scaffolded: true,
+    adminHost: true,
+    moduleMap: true,
+    middleware: true,
+    libSite: coupled,
+    sitePage: coupled,
+    headlessPage: !coupled,
+  }
+}
+
+/**
+ * Detect the AGENTS.md landmarks that actually exist in an EXISTING project, so
+ * `create-kywi-app agents` writes a header that matches the app on disk (a
+ * hand-built app may render the public site from the page directly and predate
+ * the scaffold's lib/site.ts helper or lib/modules.tsx map).
+ * @param {string} projectDir  absolute path to the project root
+ * @returns {AgentsLandmarks}
+ */
+export function detectAgentsLandmarks(projectDir) {
+  const has = (rel) => existsSync(join(projectDir, rel))
+  return {
+    scaffolded: false,
+    adminHost: has(AGENTS_LANDMARK_PATHS.adminHost),
+    moduleMap: has(AGENTS_LANDMARK_PATHS.moduleMap),
+    middleware: has(AGENTS_LANDMARK_PATHS.middleware),
+    libSite: has(AGENTS_LANDMARK_PATHS.libSite),
+    sitePage: has(AGENTS_LANDMARK_PATHS.sitePage),
+    headlessPage: has(AGENTS_LANDMARK_PATHS.headlessPage),
+  }
+}
+
+/**
+ * AGENTS.md — a short, app-specific header that orients an agent in THIS app,
+ * followed by Kywi's canonical patterns doc verbatim. Landmark-aware: each "Where
+ * things live" bullet is emitted only for a landmark that is actually present, and
+ * absent public-render (lib/site.ts) or module-map (lib/modules.tsx) wiring becomes
+ * an honest "this app predates the scaffold's …" line instead of a bullet that
+ * asserts a file the project does not have. With no landmarks passed it defaults to
+ * the fresh-scaffold set for the mode, so the scaffold output is unchanged.
+ * @param {Answers} a
+ * @param {AgentsLandmarks} [landmarks]
+ */
+export function agentsMd(a, landmarks = scaffoldLandmarks(a.mode)) {
+  const L = landmarks
+  const modeSentence =
+    a.mode === 'coupled'
+      ? 'This app renders the public site AND serves the admin + API.'
+      : a.mode === 'headless'
+        ? 'This app serves the admin + API only (`GET /` returns 404); there is no public rendering here.'
+        : 'This app serves the admin + API only; a separate frontend consumes the API via `@kywi-software/sdk`. There is no public rendering here.'
+
+  // Existing projects aren't necessarily scaffolded — don't assert they were.
+  const intro = L.scaffolded
+    ? `This is a **Kywi CMS** project scaffolded by \`create-kywi-app\` (\`${a.mode}\` mode).`
+    : `This is a **Kywi CMS** project (\`${a.mode}\` mode).`
+
+  // "Where things live" — one bullet per PRESENT landmark, in a fixed order.
+  const bullets = []
+  bullets.push(`- \`kywi.config.ts\` — project config: sites, themes, content types, auth
+  providers, deployment mode, and \`admin.features\`. Edit it, then re-run
+  \`pnpm migrate\`.`)
+  if (L.adminHost) {
+    bullets.push(`- \`app/admin/[[...admin]]/page.tsx\` — mounts Kywi's **full admin**
+  (\`KywiAdminApp\`) at **\`/admin\`**. Every surface — content, media, feeds,
+  forms, audiences, settings, … — is already there; never hand-build admin pages.`)
+  }
+  if (L.moduleMap) {
+    bullets.push(`- \`lib/modules.tsx\` — the custom-module map (\`defineModule\` renderers), shared
+  by the admin editor and the public site.`)
+  } else {
+    bullets.push(`- No \`lib/modules.tsx\` custom-module map — this app predates the scaffold's
+  \`defineModule\` module map (shared by the admin editor and the public site); see
+  the patterns doc below for the intended shape.`)
+  }
+  // Public-render surface: the scaffold's lib/site.ts helper, else a page that
+  // renders publicly without it (honest note), else no public rendering at all.
+  if (L.libSite) {
+    bullets.push(`- \`lib/site.ts\` — public-render helpers (path/locale resolution, feeds,
+  components, personalization) used by \`app/(site)/[[...slug]]/page.tsx\`, which
+  renders every published page at its slug.`)
+  } else if (L.sitePage) {
+    bullets.push(`- \`app/(site)/[[...slug]]/page.tsx\` — renders every published page at its
+  slug. This app predates the scaffold's \`lib/site.ts\` public-render helpers
+  (path/locale resolution, feeds, components, personalization); see the patterns
+  doc below for the intended shape.`)
+  } else {
+    bullets.push(
+      a.mode === 'decoupled'
+        ? `- No public rendering in this mode — \`app/page.tsx\` returns 404. Build a
+  separate frontend against the REST API at \`/api/v1\` with \`@kywi-software/sdk\`.`
+        : `- No public rendering in this mode — \`app/page.tsx\` returns 404. Content is
+  served over the REST API at \`/api/v1\`.`,
+    )
+  }
+  if (L.middleware) {
+    bullets.push(`- \`middleware.ts\` — auth gate + session refresh, thin wiring over
+  \`@kywi-software/core/host\`.`)
+  }
+  bullets.push(`- \`.claude/skills/kywi-content-model/SKILL.md\` — content-model planning
+  skill, loaded automatically before building anything.`)
+  bullets.push(`- \`.claude/skills/kywi-collections/SKILL.md\` — collections skill, loaded
+  automatically when adding any collection.`)
+  bullets.push(`- \`.claude/skills/kywi-personalization/SKILL.md\` — personalization skill,
+  loaded automatically when the owner wants personalization or A/B testing.`)
+
+  const header = `# Agent guide — ${a.projectName}
+
+${intro}
+${modeSentence}
+
+## Where things live
+
+${bullets.join('\n')}
+
+## 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
+ */
+export 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.
+`
+}
+
+/**
+ * The agent-guidance files every Kywi app should carry: AGENTS.md, an app-specific
+ * header + Kywi's canonical patterns doc; CLAUDE.md, a thin pointer into it; and
+ * the three Claude Code project skills, verbatim assets. ONE source of truth for
+ * "which files are the agent guidance", shared by {@link buildFileSet} (fresh
+ * scaffold, {@link scaffoldLandmarks}) and the `agents` refresh command
+ * ({@link detectAgentsLandmarks}) — so both emit identical content for identical
+ * inputs, and adding/renaming a skill in {@link SKILLS} updates both at once.
+ * @param {Answers} a
+ * @param {AgentsLandmarks} [landmarks]
+ * @returns {Record<string, string>}
+ */
+export function guidanceFileSet(a, landmarks = scaffoldLandmarks(a.mode)) {
+  /** @type {Record<string, string>} */
+  const files = {
+    'AGENTS.md': agentsMd(a, landmarks),
+    'CLAUDE.md': claudeMd(a),
+  }
+  for (const { slug, asset } of SKILLS) {
+    files[`.claude/skills/${slug}/SKILL.md`] = skillDoc(asset)
+  }
+  return files
+}
+
 /**
  * Build the complete map of relative-path → file-content for a project.
  * @param {Answers} answers
@@ -1945,6 +2230,12 @@ export function buildFileSet(answers) {
     '.env.example': envExample(),
     '.gitignore': gitignore(),
     'README.md': readme(answers),
+    // agent guidance (every mode): AGENTS.md (app-specific header + Kywi's
+    // canonical patterns doc verbatim), CLAUDE.md (thin pointer into it), and the
+    // three Claude Code project skills. Landmarks are derived statically from the
+    // mode so this stays byte-identical to the pre-landmark implementation; the
+    // same guidanceFileSet powers `create-kywi-app agents` for existing projects.
+    ...guidanceFileSet(answers, scaffoldLandmarks(answers.mode)),
     // server runtime + config
     'lib/kywi.ts': libKywi(),
     'lib/config.ts': libConfig(),

package/package.json

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