Payload Cms

Phase 2 — The content model

In text-schema.ts and globals.ts (references/content-model.md has the rules and the edge cases):

1. TEXT_GLOBALS — one entry per content object, slug / numbered label / group / base / a one-line note (what the screen is + any rule before Save). Group order = sidebar order.
2. SKIP — every wiring key the mocks use. Read each mock; anything a reader never sees as words.
3. OPEN_LISTS / FIXED_LISTS — with the reason in a comment, from the component's real constraints (a ring's angle, a marquee's fill, a headline's line count).
4. LABELS — every key whose humanised name an editor wouldn't understand.
5. Views read through content.ts: const hero = await getText("hero") in the view (Server Component), passed down exactly as the mock was. Nothing below the view changes. Shared chrome (header, footer, cookie banner) is read once in SiteDocument / the layout and passed as props.
6. Emails and other server copy: getText("emails") in the route; placeholders are named ({name}, {company}) and the editor's text is escaped.

Phase 3 — SEO (part of core — never skip)

1. seo-pages.ts: one entry per route + the 404 — titles 50–60 chars, absolute, opening on the brand; descriptions 100–150; written for search.
2. Every route's metadata comes through its view (hard rule #5 — page.tsx imports only @/views): the view exports export const getHomeMetadata = () => getPageMetadata("home") and the page does export const generateMetadata = getHomeMetadata. (site)/layout.tsx uses getSiteMetadata(); SiteDocument renders getStructuredData().
3. sitemap.ts → getSitemapPages() (noindex pages dropped, lastmod from the content). robots.ts → disallow /admin and /api/ (keep /robot-view).
4. /llms.txt from the kit. Details: references/seo-global.md.

Phase 4 — Schema, migration, first user

node -v                                   # ≥ 22 — see Phase 0
yarn generate:importmap                   # silent no-op? → node node_modules/payload/bin.js generate:importmap --force
yarn generate:types
yarn migrate:direct create init           # bare migrate:create does not load .env.local
yarn migrate:direct                       # apply over the session pooler
yarn dev                                  # /admin → create the first user

Commit src/payload-types.ts, src/migrations/*, importMap.js. A rename the drizzle prompt would ask about cannot be answered non-interactively — split it into drop + add migrations, or hand-write it and patch the .json snapshot (references/supabase-wiring.md §Migrations).

Phase 5 — The admin's look → payload-admin skill (§Skin)

Phase 6 — Analytics (only if wanted) → payload-analytics skill

Phase 7 — The editor's guide → payload-admin skill (§Guide) — last, it documents the final admin

Phase 8 — Prove it (each one, not "it built")

1. Edit → site: change a field in each group, Save, refresh the site — shown. Put it back.
2. Blank → fallback: clear a field — the code's copy shows, nothing breaks.
3. No database: unset DATABASE_URL, yarn build && yarn start — the full site renders from code, errors logged once per global.
4. Photo: upload into a "Replace photo" field — the file lands in the bucket, the site shows it via the public URL; delete it → the code's photo returns.
5. Open list: cut to the floor and add a row — the section still looks right at rest and in motion; a half-filled new row is refused with its missing lines.
6. SEO: view-source on each route — title, description, canonical, og:image (1200 × 630), JSON-LD; sitemap.xml, robots.txt, /llms.txt.
7. Static: the build output lists the site's routes as static (○), not ƒ.
8. yarn verify · yarn lint · yarn build · Lighthouse unchanged (yarn qa:lh) — the CMS must not cost the site a point.

Phase 9 — Vault (same turn)

cms-payload.md (what this project's admin holds: groups, open lists, kits, where data lives), tech-stack.md + changelog.md (deps), environment- variables.md, an ADR for any departure from D1–D16.

Traps (each cost time on the reference site)

• Payload CLI on Node 20.17 → silent no-op (Phase 0).
• .env.local overrides .env — a DATABASE_URL left in both takes .env.local's.
• Password with %/$ in the URL: % throws "URI malformed"; $ is expanded by @next/env and silently shortens it. Percent-encode, or letters+digits.
• Supabase's Direct host is IPv6-only → ENOTFOUND on IPv4; use the session pooler (5432) for DATABASE_URL_DIRECT.
• revalidatePath throws outside a request (seed, script) — the kit catches it.
• A "use client" module's exports are client references — a server component can't call a helper exported from one (why admin/format.ts exists).
• Payload's rich-text types use any — verify.sh skips payload-types.ts.
• Payload's admin class names aren't a public API: after an upgrade, open /admin and re-check the skin.
• Saving locally writes the live DB when dev and prod share one Supabase project — say so to the user; test edits go in and come back out.