Keystatic setup (scaffold-time, opt-in)

Adds an optional editor UI to the new-website Astro overlay. Opt-in: the default scaffold is CMS-free (Markdown-in-git is the workflow). Run this only when new-website §1 Q3 says a non-technical person edits after launch. Keystatic is git-based — it writes Markdown/Markdoc into the repo, so "data rests in your GitHub" stays literally true and the site stays free + static. (Keystatic is built by Thinkmill, the Keystone team.)

Prereq: the site uses Content Collections (new-website Q1) — Keystatic edits the files those collections read. If the site is flat pages only, add a collection first.

Local mode (what this skill wires up)

Edit via the dev server; Keystatic commits nothing on its own — you review and git commit/push, Cloudflare deploys. The admin runs in astro dev only; the production build stays fully static (no adapter, no auth, no server). Steps applied to the project:

1. Install (per the official Astro guide — verify current commands at keystatic.com):

   npm install @keystatic/core @keystatic/astro
   npx astro add react markdoc          # admin UI (React) + content format (Markdoc)

2. astro.config.mjs — add the integrations. The keystatic() integration injects a server-rendered /keystatic admin route, so adding it unconditionally fails the static build with [NoAdapterInstalled] (verified). For local mode, gate it to astro dev — the admin runs locally, production stays fully static, no adapter needed:

   import react from '@astrojs/react';
   import markdoc from '@astrojs/markdoc';
   import keystatic from '@keystatic/astro';
   
   const isDev = process.argv.includes('dev');   // keystatic admin = dev-only
   
   export default defineConfig({
     // …existing site/trailingSlash/build…
     integrations: [/* existing */ react(), markdoc(), ...(isDev ? [keystatic()] : [])],
     output: 'static',
   });

   The keystatic() integration auto-injects the /keystatic admin route + its API — you do NOT hand-write route files. (Verified deps on Astro 7 — each checked via npm view <pkg>, not assumed: @astrojs/markdoc@^2 (peer astro: ^7.0.0 — the ^1 line stays capped at astro: ^6.0.0 and will NOT install against an Astro 7 site); @keystatic/astro@^5 (peer range explicitly covers astro: 2 || 3 || 4 || 5 || 6 || 7); @astrojs/react@^6, NOT ^5 — ^5 declares no astro peer so it installs against Astro 7, but its own vite dependency is ^7.3.2 against astro 7's vite@^8.0.13, producing a duplicate non-deduped vite tree and real build-time deprecation warnings; ^6.0.1's vite dependency (^8.0.13) matches astro 7 exactly, confirmed via npm view @astrojs/react@6 dependencies.vite; @keystatic/core@^0.5 declares no astro peer and has no such transitive mismatch either, so it's fine as-is; react@19. npx astro add react markdoc (the Install step above) resolves the right majors automatically — this parenthetical is for anyone tempted to hand-pin an older note.)
3. keystatic.config.ts at the repo root — one collection per repeating content type, each path pointing into src/content/:

   import { config, fields, collection } from '@keystatic/core';
   export default config({
     storage: { kind: 'local' },
     collections: {
       posts: collection({
         label: 'Posts',
         slugField: 'title',
         path: 'src/content/posts/*',
         format: { contentField: 'content' },
         schema: {
           title: fields.slug({ name: { label: 'Title' } }),
           content: fields.markdoc({ label: 'Content' }),
         },
       }),
     },
   });

   The label: strings ARE the CMS UI the owner sees daily — write them in the owner's language, not English (a German owner gets label: 'Beiträge' / 'Titel' / 'Inhalt'). For a multilingual site built with astro-i18n-setup: per-locale entry dirs → mirror them as separate collections (one per locale directory — a single path glob can't span locale subdirectories, and a mis-scoped path leaves the other locale uneditable); a locale frontmatter field → keep ONE collection and add that field to the Keystatic schema. Mirror the site's real Content Collections (the same path/schema the Astro src/content.config.ts reads), so the CMS and the site agree on shape.
4. Allowlist — Bash(npx keystatic:*) + WebFetch(domain:keystatic.com) already ship in the template settings.json; just confirm they're present in the project's copy (don't re-add — avoid duplicates).
5. README — document the workflow: npm run dev → open /keystatic → edit → the files under src/content/ change → git commit && git push → Cloudflare deploys.

GitHub cloud mode (documented upgrade — not wired by default)

Local mode needs the editor to run a dev server. For a truly non-technical editor who should edit in the browser, upgrade to GitHub mode (commits straight to the repo from a hosted admin):

• keystatic.config.ts: storage: { kind: 'github', repo: 'owner/name' }.
• Connect Keystatic to GitHub (Keystatic Cloud, or your own GitHub App) for auth.
• The admin's auth/API routes now need on-demand rendering → add a server adapter (@astrojs/cloudflare) and switch the relevant routes to server output; add the KEYSTATIC_GITHUB_* env vars + OAuth callback. Follow the current keystatic.com docs.
• Trade-off: browser editing for non-technical users, at the cost of an adapter + a GitHub App + secrets to manage. Recommend only when local mode is genuinely too technical.

Caveats

• Keystatic's default content format is Markdoc (.mdoc), not plain .md — pick fields.markdoc/fields.mdx/fields.text to match what the site renders.
• Local-mode admin is dev-only; it is not part of the deployed static site.
• Adds React + Markdoc deps — only worth it when someone actually edits via UI.

Wiring (done once in the suite)

• new-website/SKILL.md §1 Q3 → "if non-technical editor: run keystatic-setup"; add the skill to the §3 bundled-skills copy list (conditional — only for CMS sites).
• references/WEBSITE_ARCHITECTURE.md Part 4 (Keystatic) → point at this skill.

Verify (scaffold a throwaway CMS site in /tmp)

npm install && npm run build      # static prod build succeeds (keystatic gated off in build)
npm run dev                        # open http://localhost:4321/keystatic → admin loads (200)
# create an entry in the UI → a Markdown/Markdoc file appears under src/content/<collection>/
npm test                           # suite stays green