@407dev/cli 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@407dev/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/407dev/cms.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "cms": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "dependencies": {
+    "@astrojs/compiler": "^2.13.1",
+    "@jridgewell/trace-mapping": "^0.3.25",
+    "@supabase/supabase-js": "^2.48.1",
+    "typescript": "^5.7.3",
+    "zod": "^4.4.3",
+    "@407dev/blocks": "0.1.0",
+    "@407dev/field-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "3.0.7",
+    "@407dev/config": "0.0.1",
+    "@407dev/api-client": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "biome check src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
+  }
+}

package/skills/407dev-cms-fields/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: 407dev-cms-fields
+description: Rules and best practices for adding, renaming, removing, or restructuring 407dev CMS content in an Astro site — field helpers (f.text, f.img, f.richText, …), f.scope, f.group, collections (defineCollection, getEntries, f.entryScope), key naming, static-extraction constraints, and the cms check / cms push workflow. Use whenever editing code that imports @407dev/cms-astro, when asked to make something editable or add a CMS field, key, group, or collection, or when fixing a `cms check` diagnostic.
+---
+
+# 407dev CMS: fields, keys, and collections
+
+## Mental model
+- Code owns layout, components, and routing. The CMS stores only **values** under string keys (`home.hero.heading` → `"Welcome"`) plus repeatable **collection entries**.
+- **Usage is the schema.** A helper call both renders the value and declares the field. `cms push` parses `.astro`/`.ts` source statically (it never runs it), builds the site manifest, and syncs it. There is no separate schema file to edit.
+- Editors change values in the dashboard; nothing reaches the live site until they publish. Published builds read a published snapshot only.
+
+## Pick the construct
+| Content | Construct |
+| --- | --- |
+| Copy that appears once on one page | `const intro = f.scope('about.intro')` → `<intro.text k="heading" />` |
+| Site-wide chrome (header, footer, contact info) | `f.scope('site')`, `f.scope('nav')`, `f.scope('footer')` in the layout |
+| The same set of fields reused in several places | `f.group` in `src/cms/groups.ts`, instantiated once per prefix |
+| A list of same-shaped items, or items with their own URL | `defineCollection` in `src/cms/collections.ts` |
+
+If you catch yourself numbering keys (`card1.title`, `card2.title`), it's a collection.
+
+## Key naming
+- Keys look like `<page-or-global>.<section>.<field>`, for example `home.hero.heading`, `pricing.faq.intro`, `footer.legal`. Use lowerCamel segments separated by `.`.
+- Keys are permanent identifiers (see *Changing things*). Name them by role (`hero.heading`), never by current copy (`hero.welcomeToAcme`) or styling (`hero.bigRedText`).
+- Never encode data in a key: no ids, slugs, dates, or indexes.
+
+## Fields
+```astro
+---
+import { f } from '@407dev/cms-astro';
+const hero = f.scope('home.hero');
+const heading = hero.text('heading', { defaultValue: 'Welcome' }); // raw value
+---
+<title>{heading}</title>
+<hero.text k="heading" as="h1" class="hero-title" defaultValue="Welcome" />
+```
+- **Component form** (`<hero.text k="…" />`) renders an element carrying `data-cms-field="home.hero.heading"`, which is what makes it click-to-edit in the editor preview and dev toolbar. Use it for anything visible.
+- **Function form** (`hero.text('…')`) returns the raw value without a marker. Use it only for attributes, `<title>`/meta, logic, and complex types. To keep a function-form element clickable, add `data-cms-field={hero('image')}` yourself (`hero('x')` returns the full key).
+- `as="h1"` sets the rendered tag. Other props (`class`, `id`, `aria-*`) pass through to that element. Put the element's existing attributes on the helper instead of wrapping it, so the markup doesn't grow an extra `<span>`.
+- `defaultValue` renders whenever nothing is stored. Always set one when keying existing copy. Only literal strings, numbers, and booleans are recorded as the field's default on push; object or expression defaults still render but aren't pushed.
+- Missing value with no default: `astro dev` shows `[home.hero.heading]`, and `astro build` renders the type's empty value and prints a warning listing the missing keys.
+- The helper catalog, value shapes, and image/rich-text recipes are in [references/helpers.md](references/helpers.md).
+
+## Groups (reusable field sets)
+```ts
+// src/cms/groups.ts
+import { f } from '@407dev/cms-astro';
+export const Hero = f.group('Hero', { heading: f.text, subheading: f.text, image: f.img });
+```
+```astro
+---
+// src/pages/index.astro
+import { Hero } from '../cms/groups';
+import HeroSection from '../components/HeroSection.astro';
+const hero = Hero('home.hero'); // declares home.hero.heading / .subheading / .image
+---
+<HeroSection content={hero} />
+```
+```astro
+---
+// src/components/HeroSection.astro
+import type { BoundGroupAccessor, f } from '@407dev/cms-astro';
+interface Props {
+  content: BoundGroupAccessor<{ heading: typeof f.text; subheading: typeof f.text; image: typeof f.img }>;
+}
+const { content } = Astro.props;
+---
+<section {...content.attrs()}>
+  <content.heading as="h1" />
+  <content.subheading as="p" />
+  <content.image class="hero-img" />
+</section>
+```
+- Shape values must be helper references (`f.text`), not strings or calls.
+- Never call `f.text('literal')` inside a reusable component. Every usage would share one key. Pass a bound group accessor as a prop instead.
+
+## Collections
+```ts
+// src/cms/collections.ts
+import { defineCollection, z } from '@407dev/cms-astro';
+export const blog = defineCollection({
+  key: 'blog',
+  schema: z.object({ title: z.string(), excerpt: z.string().optional(), body: z.any() }),
+  route: '/blog/[slug]',   // omit for items without their own page (testimonials, team)
+  presentation: 'form',    // 'form' = document form + preview pane; 'visual' = edit on the page
+  titleField: 'title',
+  bodyField: 'body',       // rich-text body edited in the form view
+  orderable: true,         // editors can drag to reorder
+});
+```
+Listing page:
+```astro
+---
+import { getEntries } from '@407dev/cms-astro';
+import { blog } from '../../cms/collections';
+const posts = getEntries(blog); // published only in production; includes drafts/scheduled in preview
+---
+{posts.map((p) => <a href={`/blog/${p.slug}`}>{p.content.title}</a>)}
+```
+Detail page (`src/pages/blog/[slug].astro`):
+```astro
+---
+import { collectionPaths, f, getEntry } from '@407dev/cms-astro';
+import { blog } from '../../cms/collections';
+export async function getStaticPaths() {
+  return await collectionPaths(blog); // published entries only
+}
+// Server-rendered preview/dev skips getStaticPaths props and must also see drafts.
+const entry = Astro.props.entry ?? getEntry(blog, Astro.params.slug ?? '');
+if (!entry) return Astro.redirect('/404');
+const post = f.entryScope(blog, entry.slug);
+---
+<article {...post.attrs()}>
+  <post.text k="title" as="h1" defaultValue={entry.content.title} />
+  <post.richtext k="body" defaultValue={entry.content.body} />
+</article>
+```
+- `f.entryScope` keys are paths into the entry's `content` and must match schema property names. They don't create page fields.
+- **Collection schemas are read textually, property by property.** Keep them flat, using the forms below:
+  - `z.string()`, `z.number()`, and `z.boolean()` map to their types. Anything else (nested objects, enums) is pushed as a string.
+  - A property is required unless its initializer contains `.optional()`. `.default()` alone still counts as required.
+  - `z.array(...)` is always pushed as an array of strings.
+  - Rich text: set `bodyField`, or use an initializer whose text contains `richtext`.
+  - Images or video: the initializer must call a function literally named `image(`, `video(`, or `asset(`. Define it in the collections file, e.g. `const image = () => z.string();` → `hero: image().optional()`. The bundle delivers the resolved asset object.
+- Don't use `.refine()` or `.superRefine()`. They can't be serialized and throw `RefinementError`.
+
+## Extraction rules (`cms check` enforces them)
+- Keys, `k="…"` props, scope prefixes, group prefixes, and collection `key`s must be **static string literals**. `f.text(name)`, ``k={`${x}.title`}``, and `Hero(prefix)` are errors. Dynamic, per-item content belongs in a collection.
+- Groups and collections must be imported **directly from the file that defines them**. Re-exporting through a barrel `index.ts` is a "multiple hops" error.
+- Import `f`, `defineCollection`, and friends from `@407dev/cms-astro`, not through a local wrapper.
+- Diagnostics you'll see and their fixes are in [references/helpers.md](references/helpers.md#diagnostics).
+
+## Changing things safely
+1. Edit code → `pnpm exec cms check` → `pnpm exec cms push --dry-run` → `pnpm exec cms push`.
+2. **New keys** start empty. They render `defaultValue` until an editor fills them in and publishes.
+3. **Renaming or removing a key orphans it.** The stored value is kept but no longer attached to code, and the new key starts empty. `cms push` lists the orphans and asks for confirmation. There is no rename command, so before renaming a key that may hold client content, tell the user and let them decide. Never pass `--yes` to get past an orphan prompt you haven't shown the user.
+4. Don't change an existing key's helper type (text → richtext). Add a new key and remove the old one, following step 3.
+5. **Collection schemas:** adding a new `.optional()` property is safe. Renaming or removing properties, or tightening types, can invalidate existing entries, so ask first. Removing a collection orphans it; its entries are preserved.
+6. Changing a collection `route` changes live URLs. Tell the user so they can add redirects in the dashboard.
+
+## Current limitations (don't work around silently)
+- `f.select` options can't be declared in code: the extractor reads only `defaultValue`. Ask the user how options should be managed rather than inventing an API.
+- `defineCollection({ group: '…' })` is read by the extractor, but it isn't in the TypeScript type yet, so it fails `astro check`. Leave it out unless the user asks.
+- Collection initial data is declared via `defineCollection({ seed: [...] })`. Seeds must be static literals or same-file `const` array literals; `cms push` inserts them once into empty, never-seeded collections, after which dashboard edits own the content. Seeded content is not live until a dashboard publish — a rebuild/redeploy doesn't publish, and deploy tokens can't either. `cms push` keeps warning (`Unpublished: ...`) until someone publishes.

package/skills/407dev-cms-fields/references/helpers.md

@@ -0,0 +1,78 @@
+# Field helper reference
+
+All helpers exist on `f`, on any `f.scope(...)`, on bound group accessors, and on `f.entryScope(...)`.
+
+| Helper (alias) | Stored type | Value shape | Component renders |
+| --- | --- | --- | --- |
+| `f.text` | `text` | `string` | `<span>` (override with `as`) |
+| `f.number` | `number` | `number` | `<span>` |
+| `f.toggle` | `toggle` | `boolean` | `<span>true</span>`, so use the function form for logic |
+| `f.select` | `select` | `string` | `<span>` |
+| `f.img` (`f.image`) | `image` | `CmsAsset` `{ url, alt?, width?, height?, focal_x?, focal_y? }` or URL string | `<img>` with `src`/`alt`/`width`/`height` filled from the asset |
+| `f.vid` (`f.video`) | `video` | asset `{ url, poster?, width?, height? }` or URL string | `<video controls>` |
+| `f.richText` (`f.richtext`) | `richtext` | ProseMirror JSON doc | `<div>` of sanitized HTML |
+| `f.videoList` | `media.videoList` | `Array<{ src, poster?, caption?, href? }>` | function form only |
+| `f.geoArea` | `geo.area` | GeoJSON `Polygon` | function form only |
+| `f.address` | `address` | `{ line1, city, region, postal, country, lat?, lng? }` | function form only |
+| `f.addressList` | `address.list` | `Array<address>` | function form only |
+
+"Function form only" means the component form would stringify an object. Read the value with the function form and render it yourself:
+```astro
+---
+const area = f.scope('home.serviceArea');
+const locations = area.addressList('locations', { defaultValue: [] });
+---
+<ul data-cms-field={area('locations')} data-cms-kind="address.list">
+  {locations.map((l) => <li>{l.line1}, {l.city}</li>)}
+</ul>
+```
+
+## Images
+- The simple approach is `<hero.img k="image" class="hero-img" />`. Asset `alt`/`width`/`height` apply unless you pass them explicitly, and an explicit `alt` **overrides** the editor's alt text, so don't hard-code it.
+- For a default when nothing is stored, pass an object so it carries alt text: `defaultValue={{ url: '/img/hero.jpg', alt: 'Van in driveway' }}`. With an `astro:assets` import, use `{ url: heroImg.src, width: heroImg.width, height: heroImg.height, alt: '…' }`.
+- For responsive srcsets, CDN transforms, and editor focal points, use `<CmsImage>`:
+```astro
+---
+import CmsImage from '@407dev/cms-astro/CmsImage.astro';
+import { f } from '@407dev/cms-astro';
+const hero = f.scope('home.hero');
+const image = hero.img('image');
+const alt = typeof image === 'object' && image ? (image.alt ?? '') : '';
+---
+{image && (
+  <CmsImage src={image} alt={alt} widths={[640, 1280, 1920]} sizes="100vw"
+    data-cms-field={hero('image')} data-cms-kind="image" />
+)}
+```
+
+## Rich text
+- Allowed nodes: `paragraph`, `heading`, `bulletList`, `orderedList`, `listItem`, `blockquote`, `codeBlock`, `hardBreak`, `horizontalRule`, `text`, `image`. Allowed marks: `bold`, `italic`, `underline`, `strike`, `code`, `link` (hrefs are scheme-checked). Anything else is dropped.
+- A `defaultValue` must be a ProseMirror doc:
+```js
+{ type: 'doc', content: [{ type: 'paragraph', content: [
+  { type: 'text', text: 'Serving Tulsa ' },
+  { type: 'text', text: 'since 1998', marks: [{ type: 'bold' }] },
+] }] }
+```
+- To render a stored value with custom components per node, use `<RichText value={doc} components={{ heading: MyHeading }} />` from `@407dev/cms-astro/RichText.astro`.
+- For short copy with a little inline emphasis, prefer splitting it into text fields over using rich text. Rich text lets editors add arbitrary blocks.
+
+## Collection seeds
+- Declared in `defineCollection({ seed: [...] })` as an array of `{ slug: string, content: z.input<TSchema> }`.
+- **Literal constraint:** `seed` must be a static JSON literal (strings, numbers, booleans, null, arrays, objects, no-substitution templates) or an identifier referencing a same-file `const` array literal. Calls, `.map()`, spreads, and imported identifiers are rejected with `seed must be a literal`.
+- **Seed-once semantics:** `cms push` inserts seed entries once only when the collection has never been seeded (`collections.seeded_at IS NULL`) and has zero entries. Once seeded, `seeded_at` is recorded and the dashboard owns all content. Seeds are never re-applied, even if an editor deletes every item, and seeds are never a render-time fallback.
+- **Seeding is not publishing:** seeded entries land as `published` in the draft tables, but the live site only ever serves the last published `site_versions` snapshot. A rebuild or redeploy re-reads that old snapshot — it never publishes. Deploy tokens can't publish either, so ask the user to publish from the dashboard. `cms push` warns with `Unpublished: ...` on every push while any collection has published content missing from the live bundle, not just the push that seeded it.
+
+## Diagnostics
+| `cms check` message | Fix |
+| --- | --- |
+| `Field key in '…' must be a static string literal` | Use a literal key. For per-item data, use a collection. |
+| `JSX attribute 'k' on '<…>' must be a static string literal` | `k="heading"`, not `k={name}` |
+| `Field helper '…' called without a key` | Pass `k="…"` or a first string argument. |
+| `Scope '…' declared without a prefix` / `Scope prefix … must be a static string literal` | `f.scope('home.hero')` with a literal |
+| `Group '…' instantiated without a scope prefix` / `with dynamic non-literal scope` | `Hero('home.hero')` with a literal |
+| `Group '…' field '…' does not reference a known field helper … defaulting to 'text'` | Shape values must be `f.text`, `f.img`, and so on |
+| `… is imported across multiple hops …` | Import the group or collection from its defining file, not a barrel |
+| `Collection defined without a static string key` | `defineCollection({ key: 'blog', … })` |
+| `seed must be a literal` | Provide `seed` as a static array literal or a same-file `const` array literal without spreads, `.map`, or calls. |
+| `Package '…' export '…' lacks a 'source' condition …` | A factory imported from a package can't be statically resolved. Define it in the site source instead. |

package/skills/407dev-cms-keying/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: 407dev-cms-keying
+description: Convert an existing Astro site's hard-coded copy, images, and repeated content into 407dev CMS fields, groups, and collections ("keying" a site) without changing what it renders. Use when the user asks to make an existing site editable, CMS-enable or key pages, move hard-coded content or Markdown/content collections into the CMS, or wire a handed-off site to the CMS.
+---
+
+# 407dev CMS: key an existing site
+
+Goal: everything the client should be able to edit comes from the CMS, the built site renders the same text as before any content is entered, and `cms check` is clean.
+
+Prerequisites:
+- `cmsAstro` is in `astro.config.*` and `.env` has `CMS_SITE_ID` from `cms link`. If not, follow `407dev-cms-setup` first.
+- Load `407dev-cms-fields` for the rules (naming, helpers, extraction limits). This skill is the workflow.
+
+## 1. Snapshot the baseline
+```sh
+pnpm astro build
+BASELINE="$(mktemp -d)/dist" && cp -r dist "$BASELINE" && echo "$BASELINE"
+```
+Keep the printed path for step 5.
+
+## 2. Inventory and plan keys before editing
+Read `src/layouts`, `src/pages`, `src/components`, any `src/content/` + `src/content.config.ts`, and data files (`src/data/*`). Build a key map (file → content → construct → key) with these rules:
+
+- **Key it:** headings, body copy, CTA labels, taglines, contact details, hours, prices, testimonials, team bios, and images the client would swap.
+- **Leave it in code:** markup and structure, class names, icons, routes and nav hrefs, form field names, analytics or third-party ids, and anything the code branches on. Ask before keying legal copy or navigation.
+- **Layout chrome** → `site.*`, `nav.*`, `footer.*`.
+- **Page copy** → `<page>.<section>.<field>`, where page is the route name (`home`, `about`, `pricing`) and section is the visual block.
+- **Components that take copy props** (`<Hero title=… subtitle=…>`) → an `f.group`. Replace the copy props with a `content: BoundGroupAccessor<…>` prop and instantiate the group once per page prefix.
+- **Arrays mapped in templates** (features, FAQs, testimonials, team) → a collection. Omit `route` when items have no page, and set `orderable: true` when order matters.
+- **Astro content collections / Markdown** → a CMS collection with the same frontmatter fields as schema properties, plus `body: z.any()` with `bodyField: 'body'`. Replace `astro:content`'s `getCollection`/`getEntry` with `getEntries`/`getEntry`/`collectionPaths` from `@407dev/cms-astro`.
+
+If the site has more than a handful of pages, show the key map to the user before editing. Keys are permanent, and renaming them later orphans content.
+
+## 3. Key page by page
+Order: layout first, then one page at a time, running `pnpm exec cms check` after each.
+
+Before:
+```astro
+<h1 class="hero-title">Plumbing you can trust</h1>
+<img src="/img/hero.jpg" alt="Van in driveway" class="hero-img" />
+```
+After:
+```astro
+---
+import { f } from '@407dev/cms-astro';
+const hero = f.scope('home.hero');
+---
+<hero.text k="heading" as="h1" class="hero-title" defaultValue="Plumbing you can trust" />
+<hero.img k="image" class="hero-img" defaultValue={{ url: '/img/hero.jpg', alt: 'Van in driveway' }} />
+```
+- Move the element's tag (`as`) and attributes onto the helper so the markup doesn't gain a wrapper `<span>`.
+- Copy the current text into `defaultValue` verbatim. That's what keeps the output identical until the client edits it.
+- Copy with inline markup (`<strong>`, links): split it into several text fields, or use a `richtext` field with a ProseMirror `defaultValue` (see `407dev-cms-fields` references).
+- `<title>` and meta tags: use the function form, `site.text('title', { defaultValue: '…' })`.
+
+## 4. Collections and seed data
+- Move the existing hard-coded array into `defineCollection({ seed: [...] })` (typed against the collection schema). `seed` must be a static literal or a same-file `const` array literal.
+- `cms push` inserts seed entries **once** into empty, never-seeded collections. After that, dashboard edits take over and seeds are never re-applied.
+- Workflow: push manifest (`cms push`) → publish in dashboard → deploy. Built output remains identical before and after keying.
+- The publish step is mandatory: seeded entries are `published` in the draft tables, but the live site serves only the last published snapshot, so a rebuild/redeploy without publishing leaves seeded content missing. Deploy tokens can't publish — ask the user to. `cms push` warns (`Unpublished: ...`) until they do.
+
+## 5. Verify
+```sh
+pnpm exec cms check
+pnpm astro build
+strip() { sed -E 's/ data-cms-[a-z-]+="[^"]*"//g; s/ data-astro-cid-[a-z0-9]+//g' "$1"; }
+(cd "$BASELINE" && find . -name '*.html') | while read -r p; do
+  diff -q <(strip "$BASELINE/$p") <(strip "dist/$p") >/dev/null 2>&1 || echo "changed: $p"
+done
+```
+- Inspect every `changed:` file. Expected differences are CSS asset hashes. Anything else means a default was lost or markup changed, so fix it.
+- `pnpm exec cms extract --json`: review the full key list for naming consistency and typos.
+- `pnpm exec cms push --dry-run`, then `pnpm exec cms push`.
+- `pnpm astro dev`: keyed elements should highlight in the CMS toolbar app, and un-keyed copy the client will expect to edit should be rare.
+
+## 6. Hand off
+Report to the user:
+- Keys added, per page
+- Collections seeded (keys and entry counts)
+- Anything deliberately left hard-coded, and why

package/skills/407dev-cms-setup/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: 407dev-cms-setup
+description: Set up an Astro site with the 407dev CMS — scaffold a new Astro project or integrate an existing one, install @407dev/cms-astro and @407dev/cli, link the repo to a CMS site, and run the first manifest push, plus CI/deploy wiring. Use when the user asks to connect, add, install, bootstrap, or wire up the CMS (407dev, cms-astro, `cms link`, `cms push`) in a site repo, or when a repo has no `cmsAstro` integration yet.
+---
+
+# 407dev CMS: site setup
+
+The CMS is a content dictionary. Layout, components, and routing stay in code, and the CMS stores only editable values under string keys plus repeatable collection entries. A field helper call in a template both renders the value and declares the field. Load `407dev-cms-fields` before writing any keys.
+
+## 1. Detect the starting point
+- **No Astro project:** `pnpm create astro@latest <dir> -- --template minimal --install --git --yes`. If the repo already uses npm, yarn, or bun (check the lockfile), use that manager everywhere below.
+- **Existing Astro project:** confirm `astro` is major 5, which is the `@407dev/cms-astro` peer range. If it's older, stop and ask before upgrading.
+- **Already has `@407dev/cms-astro` and `cmsAstro` in `astro.config.*`:** skip to step 4.
+- Requires Node ≥ 20.12, because the config below uses `process.loadEnvFile`.
+
+## 2. Install
+```sh
+pnpm add @407dev/cms-astro @astrojs/cloudflare
+pnpm add -D @407dev/cli
+```
+The CLI binary is `cms` (`pnpm exec cms --help`). Sites deploy to Cloudflare Pages, and preview deployments render on demand, so they need the Cloudflare adapter.
+
+## 3. Add the integration
+Merge this into `astro.config.mjs`, keeping existing integrations and options:
+```js
+import fs from 'node:fs';
+import cloudflare from '@astrojs/cloudflare';
+import { cmsAstro } from '@407dev/cms-astro';
+import { defineConfig } from 'astro/config';
+
+// Astro doesn't load .env into process.env at config time, and cmsAstro() reads process.env.
+// Values already in the environment (CI, Pages) take precedence.
+if (fs.existsSync('.env')) process.loadEnvFile('.env');
+
+const isPreviewBuild = process.env.CMS_PREVIEW_BUILD === '1';
+// Static output prerenders even under `astro dev`, which would skip the per-request draft bundle.
+const isDevServer = process.argv.includes('dev');
+
+export default defineConfig({
+  site: 'https://example.com', // the production origin; used for canonical URLs and sitemap.xml
+  output: isPreviewBuild || isDevServer ? 'server' : 'static',
+  adapter: cloudflare(),
+  integrations: [cmsAstro()],
+});
+```
+`cmsAstro()` takes no arguments. It reads `CMS_SITE_ID` and `CMS_CONTENT_URL`. Production builds emit `_redirects`, `robots.txt`, and `sitemap.xml` from CMS site settings.
+
+## 4. Log in and link
+```sh
+pnpm exec cms login          # opens the browser
+pnpm exec cms link           # pick the site; or: pnpm exec cms link --site <site-id>
+```
+- If `cms link` reports no sites, **stop**. Ask the user to create the site in the CMS web dashboard (inside the right organization), then re-run `cms link`. Don't try to create sites from the CLI or API.
+- `cms link` writes `CMS_SITE_ID`, `CMS_API_URL`, and `CMS_CONTENT_URL` into `.env` without touching other lines. Make sure `.env` and `.cms/` are in `.gitignore`.
+- Optional: `CMS_PREVIEW_SECRET` in `.env` is only used locally during `astro dev` if you want local preview token minting. Deployed site hosts never hold preview secrets.
+
+## 5. Scaffold
+- Create `src/cms/groups.ts` and `src/cms/collections.ts` (empty exports are fine). Groups and collections must live in files that pages import directly, with no barrel re-exports.
+- Key one real field in the layout to prove the loop works:
+```astro
+---
+import { f } from '@407dev/cms-astro';
+const site = f.scope('site');
+---
+<title>{site.text('title', { defaultValue: 'Current Site Title' })}</title>
+```
+- Add these scripts to `package.json`, keeping existing ones:
+```json
+"cms:check": "cms check",
+"cms:push": "cms push"
+```
+  If there's a `lint` script, prefix it with `cms check && `.
+- If the site already has hard-coded content to make editable, continue with `407dev-cms-keying` after step 6.
+
+## 6. Verify and push
+```sh
+pnpm exec cms check            # must report no errors
+pnpm exec cms push --dry-run   # shows what would be created
+pnpm exec cms push
+pnpm astro dev
+```
+In the dev server:
+- Unfilled keys without defaults render as `[site.title]`.
+- The Astro dev toolbar shows a **CMS Content** app listing the page's fields.
+- Against a non-local API, `cms login` (from step 4) is sufficient to enable inline toolbar edits; `CMS_DEV_TOKEN` is an optional override.
+
+## 7. CI and deploy
+- The user creates a **deploy token** for the site in the dashboard. It's shown once and starts with `cms_dt_`. Store it as the CI secret `CMS_AUTH_TOKEN`. It only authorizes manifest pushes and migrations for that site.
+- The pipeline order is `pnpm exec cms check` → `pnpm exec cms push --yes` → `pnpm astro build`. Use `--yes` only in CI, where orphan prompts can't be answered. Review orphans locally first.
+- Cloudflare Pages env vars:
+  - Production: `CMS_SITE_ID`, `CMS_CONTENT_URL`.
+  - Preview deployment: `CMS_SITE_ID`, `CMS_CONTENT_URL`, `CMS_PREVIEW_BUILD=1`. (Site hosts hold zero preview secrets; content-worker verifies preview tokens directly).
+- The Pages project name and branch are set on the site in the dashboard. Publishing in the CMS triggers the rebuild, so no webhook setup is needed in the repo.
+
+## Gotchas
+- A missing or wrong `CMS_SITE_ID` doesn't fail the build: bundle fetch errors are swallowed and every field renders its default. If the content looks stale, check `.cms/bundle.json`.
+- `cms push` skips unchanged manifests using `.cms/state.json`. `--force` pushes anyway.
+- Preview responses must stay `Cache-Control: no-store` and `noindex`, which the integration's middleware already handles. Don't add caching middleware in front of `/_preview/*`.