@kywi-software/core 0.3.1 → 0.4.0

package/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/README.md

@@ -7,6 +7,17 @@ app. See the [root README](https://github.com/Kywi-Software/kywi-cms#readme) for
 an orientation to the whole project, and `packages/core/src/config/types.ts`
 for the full config shape.
 
+## For agents building with Kywi
+
+[`AGENT-PATTERNS.md`](./AGENT-PATTERNS.md) (shipped with this package) is Kywi's
+official guidance for agents building Kywi sites. The core principle: **if a
+non-developer might ever want to change it, model it in the CMS instead of
+hardcoding it** — content, collections, forms, and page sections belong in Kywi
+so the site owner can maintain them without a developer. A scaffolded
+`create-kywi-app` project embeds this doc in its `AGENTS.md`. It is a verbatim
+copy of `docs/agents/AGENT-PATTERNS.md` in the monorepo (kept in sync by
+`scripts/sync-agent-patterns.mjs`); edit the canonical there, not this copy.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kywi-software/core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Kywi CMS core — schema generator, REST API, and admin UI for Next.js.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "AGENT-PATTERNS.md",
     "README.md",
     "LICENSE"
   ],