@getvitops/create 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @getvitops/create
 
+## 0.7.0
+
+### Minor Changes
+
+- **Breaking (for scaffolds) — both templates now ship `site.json` instead of `design-system.json`.**
+
+  `design-system.json` is deleted from the `static` and `emdash` templates; its contents move under
+  `designSystem.themes.default` inside a new `site.json` (the umbrella `Config`), because a
+  scaffolded config can't merely reference a sibling design-system file — `ConfigSchema` requires
+  `designSystem` and there is no file-level `extends`. `astro.config.mjs`'s `css.input` (and
+  `site.input`, for emdash) now point at `site.json`; so do the `build:css`/`lint:design` scripts.
+
+  **Migration** for a project already scaffolded from an older version of this template: create
+  `site.json` with your existing `design-system.json`'s content under
+  `designSystem.themes.default`, delete `design-system.json`, and update `css.input`/`site.input` in
+  `astro.config.mjs`. Not reachable by `vitops lint --fix` — this is the whole migration.
+
+  Also new in both templates:
+
+  - **`SETUP.html`** — a client-onboarding checklist (styled entirely with the framework's own
+    classes, checkbox state in `localStorage`), generated a stylesheet for via the new
+    `pnpm run sop` script.
+  - **`.agents/skills/setup/SKILL.md`** — lets an AI agent work the same checklist autonomously,
+    stopping only at the steps that genuinely need a human (the Cloudflare API token, the
+    domain cutover, publishing generated legal documents).
+  - `scripts/init-github.mjs` and `scripts/init-hosting.mjs` are deleted; `pnpm run init:github` /
+    `init:hosting` / the new `setup` script now call `vitops setup repo` / `vitops setup hosting`
+    (from `@getvitops/cli`, requires the `minor` release in the same batch as this one) instead of
+    a template-local script, so the same capability now reaches any existing project, not just a
+    fresh scaffold.
+
+## 0.6.0
+
+### Minor Changes
+
+- Scaffolded `static` and `emdash` projects now ship neutral placeholder wireframe images under
+  `src/assets/placeholder/` (square, portrait, landscape; SVG + PNG) for layout work before real
+  imagery exists. Delete the directory once real assets land.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -227,15 +266,15 @@
   which `@getvitops/astro` re-exports wholesale. So from `astro.config.mjs`:
 
   ```js
-  import { generateIconInclude } from '@getvitops/astro';
-  import icon from 'astro-icon';
+  import { generateIconInclude } from "@getvitops/astro";
+  import icon from "astro-icon";
 
   integrations: [
     icon({
       include: generateIconInclude({
-        ui: 'fa7-solid',
-        brand: 'simple-icons',
-        semantic: ['menu', 'close', 'search', 'github'],
+        ui: "fa7-solid",
+        brand: "simple-icons",
+        semantic: ["menu", "close", "search", "github"],
       }),
     }),
   ];

package/README.md

@@ -73,6 +73,13 @@ provisions the D1/R2 resources on first deploy).
 Template dependencies must use concrete npm ranges (no `workspace:*` /
 `catalog:` — the scaffolded project lives outside this monorepo).
 
+`assets/` (this package root, unpublished) is the source of truth for
+placeholder imagery shared across templates — `vp create` copies only the
+one directory a template names, so there's no step that could copy a
+sibling `assets/` for you. Mirror any new file into each template's
+`src/assets/placeholder/` by hand; `templates.test.ts` asserts every mirror
+stays byte-identical to the source.
+
 ## Changelog
 
 This package's history: [`CHANGELOG.md`](./CHANGELOG.md) (shipped in the npm tarball, so it

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@getvitops/create",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Project templates for the Vitops design system — scaffold wired-up sites with `vp create @getvitops`.",
+  "homepage": "https://docs.vitops.ca",
+  "bugs": "https://github.com/getvitops/design-system/issues",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getvitops/design-system.git",
+    "directory": "packages/create"
+  },
   "files": [
     "templates",
     "CHANGELOG.md"
@@ -12,10 +19,19 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "^4.1.9"
+    "vitest": "4.1.9",
+    "@getvitops/generator": "8.1.0"
+  },
+  "engines": {
+    "node": ">=24"
   },
   "createConfig": {
     "templates": [
+      {
+        "name": "static",
+        "description": "Static Astro website on Cloudflare Workers static assets with the Vitops design system pre-wired",
+        "template": "./templates/static"
+      },
       {
         "name": "emdash",
         "description": "EmDash CMS website on Cloudflare Workers (D1 + R2) with the Vitops design system pre-wired",

package/templates/emdash/.agents/skills/setup/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: setup
+description: Work the client-onboarding checklist (SETUP.html) autonomously — GitHub repo + branch policy, hosting resources, Search Console/GCP/ads connections. Use when the user asks to set up, onboard, or provision this project (e.g. "run setup", "onboard this site", "get this ready to deploy"). Never run this as a side effect of unrelated work, and never on your own initiative without the user asking.
+---
+
+# Setup (client onboarding)
+
+`SETUP.html` is the canonical checklist — this skill adds only sequencing,
+gates, and where to stop. It does not restate the steps; read `SETUP.html`
+(or `npx vitops setup --help`) for what each stage actually does and why.
+
+## Steps
+
+1. **Preview the whole sequence first.**
+
+   ```bash
+   npx vitops setup all --dry
+   ```
+
+   Read the plan before doing anything. It names every step it would take and
+   why any step is blocked — a missing credential, a field not yet in
+   `site.json`, GitHub Pro/Team gating branch protection.
+
+2. **Run it.**
+
+   ```bash
+   npx vitops setup all
+   ```
+
+   Re-run `npx vitops setup --check` after each leg rather than retrying on
+   your own judgment — a step already done resolves to a no-op skip, so a
+   second run is safe, and `--check` tells you exactly what still needs doing
+   instead of you guessing from output.
+
+3. **Tick `SETUP.html` boxes only for what you actually completed.** Never
+   check a box for a step marked below as human-only, even if you did
+   everything up to it — the human still has to act.
+
+## Hard stops — ask the human, do not attempt
+
+- **The Cloudflare API token.** No API can create one; there is no command to
+  run. Tell the user to create it at
+  <https://dash.cloudflare.com/profile/api-tokens> (Workers + D1 + R2 edit)
+  and run `gh secret set CLOUDFLARE_API_TOKEN`, then continue.
+- **The domain cutover** (`vitops setup domain`, stage 4b in `SETUP.html`).
+  Uncommenting the custom-domain route and deploying overwrites the zone's DNS
+  record at that instant — it takes an existing live site down. `setup domain`
+  only ever plans and checks this; it never applies it, and neither should
+  you. Report the plan and hand the actual cutover to the user.
+- **Publishing any generated legal document.** `vitops legal` renders a
+  starting point from the config, not a reviewed policy. Generate it, tell the
+  user it needs review, and stop — do not paste it into the admin or commit it
+  yourself.
+
+## If something is blocked
+
+`vitops setup --check` names the field or credential and where to get it —
+report that verbatim rather than guessing at a fix. A step reported as
+"blocked" is not a failure to retry; it is waiting on one of the hard stops
+above, or on a `site.json` field the user still needs to fill in (stage 5,
+Configuration).

package/templates/emdash/.env

@@ -0,0 +1 @@
+CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

package/templates/emdash/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+# Runs on every PR: typecheck + design-lint + build. deploy-dev.yml /
+# deploy-prod.yml call the same reusable `site-ci.yml` themselves before they
+# deploy, so this is what gives a PR the identical signal before it's even
+# merged to `dev` — a broken build never reaches the dev worker.
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  ci:
+    uses: getvitops/design-system/.github/workflows/site-ci.yml@v1

package/templates/emdash/.github/workflows/deploy-dev.yml

@@ -3,6 +3,11 @@
 # `dev` is the integration branch — every push here refreshes the review site.
 # Promote to production with the "Promote dev → main" workflow (promote.yml).
 #
+# Deploys via the vitops toolchain's reusable EmDash deploy workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-deploy-emdash.yml
+# for what it does. Pinned to @v1 so a fix there reaches this repo without a
+# manual re-paste; bump the tag deliberately if you want to pick up a change.
+#
 # Required repo secrets:
 #   CLOUDFLARE_API_TOKEN   — token with Workers + D1 + R2 edit on this account
 #   CLOUDFLARE_ACCOUNT_ID  — the Cloudflare account id
@@ -14,28 +19,21 @@ on:
   push:
     branches: [dev]
 
-permissions:
-  contents: read
-
 concurrency:
   group: deploy-dev
   cancel-in-progress: true
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
-    environment: dev
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - name: Build + deploy dev worker
-        run: pnpm run deploy:dev
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          DEV_D1_ID: ${{ secrets.DEV_D1_ID }}
+    uses: getvitops/design-system/.github/workflows/site-deploy-emdash.yml@v1
+    with:
+      environment: dev
+      is-dev: true
+      # Set this to your dev worker's URL (or dev.<domain>) once known, so a
+      # bad migration fails the deploy instead of surfacing to the first
+      # visitor — see the reusable workflow's docblock.
+      health-check-url: ''
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      DEV_D1_ID: ${{ secrets.DEV_D1_ID }}

package/templates/emdash/.github/workflows/deploy-prod.yml

@@ -1,36 +1,32 @@
 # Deploys `main` to production.
 # `main` should be branch-protected — it then only advances via the Promote
-# workflow (promote.yml), so a push here always represents promoted code.
+# workflow (promote.yml), so a push here always represents promoted code. The
+# `production` GitHub Environment (set up by `scripts/init-github.mjs`) has
+# required reviewers restricted to admins, so this PAUSES for approval before
+# deploying.
 #
-# Required repo secrets:
-#   CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
+# Deploys via the vitops toolchain's reusable EmDash deploy workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-deploy-emdash.yml
+#
+# Required repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
 name: Deploy prod
 
 on:
   push:
     branches: [main]
 
-permissions:
-  contents: read
-
 concurrency:
   group: deploy-prod
   cancel-in-progress: false
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
-    environment: production
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - name: Build + deploy prod worker
-        run: pnpm run deploy
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+    uses: getvitops/design-system/.github/workflows/site-deploy-emdash.yml@v1
+    with:
+      environment: production
+      is-dev: false
+      # Set this to your production URL once known.
+      health-check-url: ''
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package/templates/emdash/.github/workflows/promote.yml

@@ -2,48 +2,20 @@
 # Opens a PR from dev into the protected `main` branch and enables auto-merge;
 # the merge triggers Deploy prod.
 #
-# Branch protection on `main` means the merge only completes when its rules are
-# satisfied. Choose ONE:
-#   (a) let a human approve the PR (required reviews) — safest, full audit trail;
-#   (b) set repo secret PROMOTE_TOKEN to a PAT / GitHub App token allowed to
-#       bypass protection, for hands-off promotion.
-# The default GITHUB_TOKEN cannot approve its own PR, so with required reviews
-# the PR waits for a human — which is usually what you want for a prod promotion.
+# Deploys via the vitops toolchain's reusable promote workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-promote.yml
+# for the branch-protection / PROMOTE_TOKEN options.
 #
-# Schema/content promotion is deliberately NOT here — the content model lives in
-# the EmDash database, not git. Apply schema changes to prod via the admin or
-# the site's MCP server, additive changes before the code deploy that uses
+# Schema/content promotion is deliberately NOT here — the content model lives
+# in the EmDash database, not git. Apply schema changes to prod via the admin
+# or the site's MCP server, additive changes before the code deploy that uses
 # them, removals after the code that stops using them.
 name: Promote dev → main
 
 on:
   workflow_dispatch:
 
-permissions:
-  contents: write
-  pull-requests: write
-
 jobs:
   promote:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Open promotion PR and enable auto-merge
-        env:
-          GH_TOKEN: ${{ secrets.PROMOTE_TOKEN || github.token }}
-        run: |
-          set -euo pipefail
-          if gh pr view dev --base main --json number >/dev/null 2>&1; then
-            echo "Promotion PR already open; ensuring auto-merge is enabled."
-          else
-            # printf, not a multi-line string: an unindented continuation line
-            # would end this YAML block and break the whole workflow file.
-            gh pr create --base main --head dev \
-              --title "Promote dev → main" \
-              --body "$(printf '%s\n\n%s' \
-                "Automated code promotion from \`dev\`. Merging deploys to production." \
-                "Remember: schema/content changes live in the EmDash database, not git — promote them separately if this release changes the content model.")"
-          fi
-          gh pr merge dev --auto --merge
+    uses: getvitops/design-system/.github/workflows/site-promote.yml@v1
+    secrets: inherit

package/templates/emdash/.mcp.json

@@ -7,6 +7,10 @@
     "emdash-docs": {
       "type": "http",
       "url": "https://docs.emdashcms.com/mcp"
+    },
+    "semrush": {
+      "type": "http",
+      "url": "https://mcp.semrush.com/v1/mcp"
     }
   }
 }

package/templates/emdash/.nvmrc

@@ -0,0 +1 @@
+24

package/templates/emdash/AGENTS.md

@@ -3,10 +3,18 @@ styled by the Vitops design system.
 
 ## Ground rules
 
-- `design-system.json` is the single source of truth for the design system
-  (colors, type, spacing, patterns, animations). Never edit
-  `src/styles/tailwind.css` — it is generated from the JSON by the
-  `vitops()` integration on every dev/build and is gitignored.
+- `site.json` is the single source of truth — organization + site facts, and
+  the design system (colors, type, spacing, patterns, animations) under
+  `designSystem.themes.default`. Never edit `src/styles/tailwind.css` — it is
+  generated from `site.json` by the `vitops()` integration on every dev/build
+  and is gitignored. (There is no separate `design-system.json`: a scaffolded
+  config can't merely reference a sibling file, so the token set lives inside
+  `site.json` — see `AGENTS.md`'s "Client onboarding" section in the toolchain
+  repo for why.)
+- `src/assets/placeholder/` holds neutral wireframe stand-ins (square,
+  portrait, landscape; SVG + PNG) for layout work before real imagery
+  exists. Delete the directory once real assets land — it's separate from
+  `src/assets/logo.svg`, the actual brand asset.
 - Content lives in the EmDash database, not in the repo. Query it with
   `getEmDashCollection` / `getEmDashEntry` from `emdash`; render Portable Text
   with `<PortableText />` from `emdash/ui` (the Vitops blocks from
@@ -70,6 +78,10 @@ styled by the Vitops design system.
   d1/r2/sqlite there. Switch targets via `vitopsHosting({ target })` or the
   `HOSTING` env var (see README "Hosting"); the `node` target needs
   `@astrojs/node` + `better-sqlite3` installed first.
+- **`SETUP.html` is the client-onboarding checklist.** When working it via the
+  `.agents/skills/setup/` skill, tick a box only for a step you actually
+  completed — never on the operator's behalf for a step marked human-only
+  (the Cloudflare API token, the domain cutover, publishing legal documents).
 
 ## Branch model
 
@@ -86,12 +98,12 @@ styled by the Vitops design system.
   and obviously unfinished; do not "improve" them into something that reads as
   a finished policy, because the risk here is a plausible-looking document
   getting shipped unread.
-  To replace them properly, write a site config and run
-  `npx vitops legal --format portable-text --out ./legal`, then paste each
-  document's blocks into the page in the admin. That renders a real policy from
-  what the site actually does — the analytics provider it uses, the fields its
-  forms collect, where it deploys — rather than from guesses. It still needs
-  review before launch.
+  To replace them properly, fill in `site.json`'s `organization`/`site.legal`
+  fields and run `npx vitops legal --format portable-text --out ./legal`, then
+  paste each document's blocks into the page in the admin. That renders a real
+  policy from what the site actually does — the analytics provider it uses,
+  the fields its forms collect, where it deploys — rather than from guesses.
+  It still needs review before launch.
 
 ## Docs MCP servers
 
@@ -108,4 +120,4 @@ searching them over pre-trained knowledge for Astro/EmDash questions.
   dev default). Only run when the user asks to set up GitHub.
 - `pnpm run init:hosting` — one-time: provision the hosting platform (dev
   D1/R2 + repo secrets on cloudflare). Only run when the user asks for it.
-- `npx vitops validate design-system.json` — schema-check the design config
+- `npx vitops validate site.json` — schema-check the site config

package/templates/emdash/README.md

@@ -10,12 +10,16 @@ Scaffolded from `vp create @getvitops:emdash`.
 - **Astro** (SSR) on **Cloudflare Workers** — D1 database, R2 media storage
 - **EmDash** — the admin lives at `/_emdash/admin`; content is queried with
   `getEmDashCollection` / `getEmDashEntry` (Astro live content collections)
-- **`@getvitops/astro`** — generates the design-system CSS from
-  `design-system.json` (Tailwind v4 format), generates favicons/PWA assets
-  from `src/assets/logo.svg`, and serves the web-component runtime
+- **`@getvitops/astro`** — generates the design-system CSS from `site.json`
+  (Tailwind v4 format), generates favicons/PWA assets from
+  `src/assets/logo.svg`, and serves the web-component runtime
 - **`@getvitops/emdash`** — design-system Portable Text blocks in the editor
   slash menu: image compare, copy snippet, banner, disclosure, carousel
 
+`src/assets/placeholder/` ships neutral wireframe images for layout work
+before real imagery exists — delete once real assets land (separate from
+`src/assets/logo.svg`, the brand asset).
+
 ## Local development
 
 ```bash
@@ -38,7 +42,7 @@ Until then the home route shows a friendly empty state. Unknown paths render
 `src/pages/404.astro`.
 
 The two legal pages are placeholders. To generate real ones from what your site
-actually does, describe it in a site config and run:
+actually does, fill in `site.json`'s `organization`/`site.legal` fields and run:
 
 ```sh
 npx vitops legal --format portable-text --out ./legal
@@ -78,22 +82,18 @@ The repo ships a two-environment flow modeled on branch = environment:
   into `main` with auto-merge enabled. With required reviews on `main`, a
   human approves the PR; merging deploys prod.
 
-One-time setup:
-
-1. `pnpm run init:github` — creates a GitHub repo named after this project
-   (via the `gh` CLI; `-- --public` for a public repo), commits if needed,
-   pushes `main` + `dev`, and makes `dev` the default branch. Idempotent;
-   `-- --dry-run` previews. Then branch-protect `main` (require the promotion
-   PR + review).
-2. `pnpm run init:hosting` — provisions the hosting platform (after
-   `npx wrangler login`): creates the isolated dev D1 + R2 and sets the
-   `DEV_D1_ID` / `CLOUDFLARE_ACCOUNT_ID` repo secrets. Idempotent;
-   `-- --dry-run` previews.
-3. Create a Cloudflare API token (Workers + D1 + R2 edit —
-   <https://dash.cloudflare.com/profile/api-tokens>; tokens can't be created
-   via CLI) and `gh secret set CLOUDFLARE_API_TOKEN`. Optionally
-   `PROMOTE_TOKEN` (a PAT allowed to bypass protection) for hands-off
-   promotion. The first workflow runs fail until the secrets exist.
+One-time setup — work through the checklist:
+
+```bash
+pnpm run sop && open SETUP.html   # or: xdg-open SETUP.html
+```
+
+It covers host choice, GitHub + branch policy, hosting resources, going live
+safely on `*.workers.dev` before any custom-domain cutover, configuration,
+Search Console/GCP/ads connections, legal documents, and launch gates — one
+command per step. An AI agent can work the same list autonomously via
+`.agents/skills/setup/`; it stops at the steps that genuinely need a human
+(the Cloudflare API token, the domain cutover, publishing legal documents).
 
 `pnpm deploy:dev` reproduces the dev deploy locally: it rewrites the
 adapter-generated wrangler config (`scripts/build-dev-wrangler.mjs`) so the
@@ -142,8 +142,10 @@ and media in the storage backend (bucket/directory copy).
 
 ## The design system
 
-`design-system.json` is the single source of truth for colors, type, spacing,
-shadows, patterns, and animations. The `vitops()` integration regenerates
+`site.json`'s `designSystem.themes.default` is the single source of truth for
+colors, type, spacing, shadows, patterns, and animations — there is no
+separate `design-system.json`, since a scaffolded config can't merely
+reference a sibling file. The `vitops()` integration regenerates
 `src/styles/tailwind.css` from it on dev/build (the file is gitignored — edit
 the JSON, not the CSS). `Layout.astro` imports the stylesheet so the admin
 routes stay unstyled by it.
@@ -151,27 +153,27 @@ routes stay unstyled by it.
 Useful commands (via `@getvitops/cli`):
 
 ```bash
-npx vitops validate design-system.json   # check the config against the schema
-npx vitops agents                        # write the design-system reference into AGENTS.md
-pnpm build:css                           # regenerate the CSS manually
+npx vitops validate site.json   # check the config against the schema
+npx vitops agents               # write the design-system reference into AGENTS.md
+pnpm build:css                  # regenerate the CSS manually
 ```
 
 ## Project map
 
-| Path                             | Purpose                                                           |
-| -------------------------------- | ----------------------------------------------------------------- |
-| `design-system.json`             | Design tokens + patterns → generated CSS                          |
-| `seed/seed.json`                 | First-boot content model + starter content                        |
-| `src/worker.ts`                  | Worker entry (fetch + EmDash scheduled handler)                   |
-| `src/live.config.ts`             | Astro live content collections wiring for EmDash                  |
-| `src/layouts/Layout.astro`       | Site chrome: EmDash + Vitops head tags, nav from the CMS menu     |
-| `src/pages/index.astro`          | Home — renders the `home` page entry                              |
-| `src/pages/[...slug].astro`      | Catch-all — renders any `pages` entry at its slug                 |
-| `src/pages/404.astro`            | Not-found page (the catch-all rewrites here)                      |
-| `wrangler.jsonc`                 | Cloudflare bindings (D1/R2) + cron trigger                        |
-| `scripts/build-dev-wrangler.mjs` | Rewrites the built wrangler config for the isolated dev worker    |
-| `scripts/init-github.mjs`        | One-time: create + push the GitHub repo (`pnpm run init:github`)  |
-| `.github/workflows/`             | deploy-dev (push to `dev`), deploy-prod (push to `main`), promote |
-| `.agents/skills/promote/`        | Agent skill: dispatch the dev → main promotion                    |
-| `.mcp.json`                      | Astro + EmDash docs MCP servers for coding agents                 |
-| `.claude/hooks/`                 | Claude Code web: Node 24 + pnpm setup on session start            |
+| Path                             | Purpose                                                                                    |
+| -------------------------------- | ------------------------------------------------------------------------------------------ |
+| `site.json`                      | Org + site config; design tokens/patterns at `designSystem.themes.default` → generated CSS |
+| `seed/seed.json`                 | First-boot content model + starter content                                                 |
+| `src/worker.ts`                  | Worker entry (fetch + EmDash scheduled handler)                                            |
+| `src/live.config.ts`             | Astro live content collections wiring for EmDash                                           |
+| `src/layouts/Layout.astro`       | Site chrome: EmDash + Vitops head tags, nav from the CMS menu                              |
+| `src/pages/index.astro`          | Home — renders the `home` page entry                                                       |
+| `src/pages/[...slug].astro`      | Catch-all — renders any `pages` entry at its slug                                          |
+| `src/pages/404.astro`            | Not-found page (the catch-all rewrites here)                                               |
+| `wrangler.jsonc`                 | Cloudflare bindings (D1/R2) + cron trigger                                                 |
+| `scripts/build-dev-wrangler.mjs` | Rewrites the built wrangler config for the isolated dev worker                             |
+| `SETUP.html`                     | Client-onboarding checklist — run `pnpm run sop` first (see "One-time setup")              |
+| `.github/workflows/`             | deploy-dev (push to `dev`), deploy-prod (push to `main`), promote                          |
+| `.agents/skills/promote/`        | Agent skill: dispatch the dev → main promotion                                             |
+| `.mcp.json`                      | Astro + EmDash docs MCP servers for coding agents                                          |
+| `.claude/hooks/`                 | Claude Code web: Node 24 + pnpm setup on session start                                     |