@getvitops/create 0.6.0 → 0.8.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # @getvitops/create
 
+## 0.8.0-alpha.0
+
+### Minor Changes
+
+- c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
+designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+'./site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
+  offered, now usable by the client directly, no dev server required. An edit is visible
+  site-wide immediately (a runtime `:root` override, served via a new plugin API route and
+  `page:fragments`) and — once `site.deployment.repo`/`branch` and a `VITOPS_GITHUB_TOKEN`
+  secret are set (see the scaffold's `SETUP.html`) — auto-commits to your `dev` branch, so it
+  reaches the git-tracked `site.json` through your repo's normal review path rather than
+  becoming a second, unreviewed source of truth. Until that's configured, the live half still
+  works; only the auto-commit half is skipped (and says so in the admin page). The save route
+  runs the exact same accessibility (APCA contrast) gate `generate()` enforces at build time,
+  synchronously, before persisting — nothing non-compliant ever goes live even momentarily.
+
+  Requires `@astrojs/react` + `react` + `react-dom` (already scaffold dependencies, for
+  EmDash's own admin) and `@getvitops/core` (added as a new scaffold dependency this release).
+  Declares two new plugin capabilities when enabled: `network:request` (for the GitHub
+  auto-commit) and `hooks.page-fragments:register` (for the live override) — reviewed once at
+  plugin-install time.
+
+  **Breaking for `@getvitops/emdash`**: `vitopsEmdash()`'s `hooks.page-fragments:register`
+  capability is now also granted whenever `designSystemEditor` is set, independent of the
+  existing `scripts: 'fragments'` option (which governs something unrelated — web-component
+  script delivery). No change if you don't use `designSystemEditor`.
+
+  Also new, supporting the above:
+  - `@getvitops/generator`: `validateColorContract()` and `buildReverseIndex()` (both
+    `/tokens` subpath, Worker-safe) — the monotonicity/contrast gate and the
+    `design-manifest.json` reverse-index, each extracted from `generate()`'s `build()` into
+    standalone, non-throwing functions. `patchToOverrideCss()` turns a design-system patch
+    into the `:root` override `<style>` block. `designSystemPath`/`getAt`/`setAt`/
+    `mergePatch`/`formatConfig` moved from `@getvitops/vite` into `@getvitops/generator/config`
+    (re-exported from `@getvitops/vite` unchanged) — one "patch a config file's design-system
+    subtree" implementation shared by the dev endpoint and the new plugin route. New
+    `site.deployment.repo`/`branch` config fields.
+  - `@getvitops/utils`: new `/git` subpath — `commitFile()`, a Worker-safe (fetch-only)
+    wrapper over GitHub's Contents API.
+  - `@getvitops/core`: `<wc-theme-editor>` gains a `save-endpoint` attribute (default
+    unchanged — `/__vitops/design-system`) so the same element can target the new plugin
+    route instead of the dev-only Vite endpoint.
+
+### Patch Changes
+
+- 0574388: Add `vitops email setup|check` — connect `site.notifications.email.from` to whether its domain is
+  actually onboarded onto an outbound email provider.
+
+  Before this, nothing checked that. `EMAIL.send()` throws `E_SENDER_NOT_VERIFIED` at runtime with no
+  build or deploy-time warning — the failure mode is silent and production-only.
+
+  `vitops email setup [domain]` onboards a sending domain (currently Cloudflare Email Sending only)
+  and polls DNS until its SPF/DKIM/DMARC records resolve or a timeout is reached; `vitops email
+check` is the non-blocking deploy guard both `@getvitops/create` templates' `deploy`/`deploy:dev`
+  scripts now run first (`--strict` makes it a real gate; opt out per-site with
+  `site.notifications.email.verifySender: false`, or globally with `--skip` /
+  `VITOPS_SKIP_EMAIL_CHECK`).
+
+  Two things worth knowing before running it:
+  - **The onboarded entity is an exact name, and it is usually a subdomain**
+    (`send.yourdomain.com`), never the apex your `from` address names. When the exact domain isn't
+    onboarded but a sibling in the same zone already is, the command reports that as the fix — send
+    from the onboarded subdomain — rather than silently trying to onboard the apex, which rewrites
+    `_dmarc.<domain>` and can tighten DMARC policy on every other mail your domain sends.
+  - Candidates come from `site.notifications.email.from` (or its derived `noreply@<domains
+.canonical>` default) first; a best-effort scan of `--src` only supplements it, and never guesses
+    at a computed `from` value.
+
+  New `@getvitops/utils/email` subpath and `site.notifications.email.verifySender` config field.
+  Needs `CLOUDFLARE_API_TOKEN` with an Email Sending scope in addition to the `Zone:Read` other
+  commands already use.
+
+- 0574388: Bump `emdash`/`@emdash-cms/cloudflare` peers to `>=1.0.0 <2` and `vite-plus` to `^1.0.0`, following
+  both projects' GA releases.
+
+  **Breaking for `@getvitops/emdash` consumers on EmDash 0.x**: the peer range no longer admits
+  `emdash@0.31.x`/`@emdash-cms/cloudflare@0.31.x`. Upgrade `emdash` and `@emdash-cms/cloudflare` to
+  `^1.0.1` first — nothing in `@getvitops/emdash`'s own plugin surface (`admin.portableTextBlocks`,
+  the `hooks.page-fragments:register` capability, `definePlugin()`) changed against EmDash 1.0, so no
+  code here needed to change, only the declared range.
+
+  The `emdash` scaffold template (`vp create @getvitops:emdash`) picks up several fixes alongside
+  the version bump:
+  - `tailwindcss`/`@tailwindcss/vite` are now real dependencies — the template selected
+    `css.format: 'tailwind'` without installing either, which threw on build.
+  - `site.json` now sets `site.icons.sprite: true` plus the full `semantic` list the
+    `vitops.actionLink` block's icon picker offers — previously its sprite icons pointed at a file
+    the build never generated.
+  - `astro.config.mjs` sets `migrations: { runtime: 'check', dev: 'auto' }`, and
+    `site-deploy-emdash.yml` runs EmDash 1.0's documented `build → status → apply → deploy → check`
+    migration sequence explicitly, rather than relying solely on first-request auto-migration. This
+    needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
+    which only a human can set — run `emdash migrate --status` against the real deployed database,
+    review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
+<value>`. Deploys fail clearly on the migration-apply step until it's set.
+  - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
+    not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
+    errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).
+    Uncomment it once scaffolded into its own repo.
+
+  No config schema changes. `@getvitops/generator` also switches from the `zod/mini` subpath import
+  to the standalone `@zod/mini` package (zod 4.5+; same API) and fixes `validateConfig()` silently
+  losing the offending key name on an `unrecognized_keys` error (e.g. a typo'd `site.ads` platform
+  now names the bad key instead of reporting a bare "Invalid input").
+
+  Also fixed: `vp check`'s `tsconfig-error` for `packages/create/templates/emdash/tsconfig.json`
+  (`extends: "astro/tsconfigs/strict"`, unresolvable from inside this monorepo since the template
+  has no `node_modules` of its own — a pre-existing, structural gap, newly surfaced as a hard error
+  by oxlint 1.85's deeper config discovery, and blocking on every commit since this repo's pre-commit
+  hook runs `vp check --fix`). Fixed with a new `scripts/link-template-deps.mjs`, wired as the root
+  `postinstall` script: symlinks `astro`/`emdash`/`@emdash-cms/cloudflare` into the template's own
+  `node_modules/` (resolved fresh from sibling packages that already depend on them for real, not a
+  hardcoded `.pnpm` hash) and writes a minimal `astro:content` ambient shim at `.astro/types.d.ts`
+  (the same path `astro sync` would generate for real). Both are gitignored and only ever exist
+  inside this monorepo's copy of the template — a real scaffold installs its own real copies instead.
+  Considered and rejected first: inlining astro's strict preset (drift risk against astro's own
+  evolving default) and making the template a real pnpm workspace member (would change how its
+  `@getvitops/*: "latest"` deps resolve locally, which `templates.test.ts` exists to protect).
+
+  **Known gap, not fixed here**: `packages/astro/src/components/container.test.ts` (the
+  `AstroContainer`-based render tests) fails to even load under vite-plus 1.0's Vite 8 — direct
+  `.astro` imports in a Vitest file need the Astro Vite plugin registered, which nothing in this
+  repo's test config actually does (Astro's own docs call for `getViteConfig()`, which doesn't
+  compose with vite-plus's own `defineConfig`). A type-level shim
+  (`packages/astro/src/components/astro-modules.d.ts`) fixes `vp check`'s type-aware pass, but the
+  runtime `vp test` failure for this one file is still open.
+
+- 0f8c018: **New: `resolveOrganizationName(config, locale?)`**, exported from `@getvitops/astro/routes`
+  alongside `toNotifyContext`/`toCrmConfig` — the same `organization.name` → `legalName` →
+  `undefined` fallback chain `toNotifyContext` already used for its `organizationName` field,
+  now usable standalone anywhere a build-time-only display name is needed (favicon generation,
+  a scaffold's `astro.config.mjs`, a `Layout.astro` fallback). `toNotifyContext` is unchanged —
+  it now delegates to this helper internally.
+
+  The emdash scaffold uses it to remove a three-way duplicated `'My EmDash Site'` string:
+  `astro.config.mjs`'s favicon `name` and `Layout.astro`'s title fallback both previously
+  hardcoded it independently of `site.json`'s `organization.name`. EmDash's own
+  `getSiteSettings().title` (set in the admin) still wins at render time when it's set — it's a
+  runtime-only fact that can't be read at build time at all — this only replaces the two
+  hardcoded _fallback_ strings.
+
+## 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
@@ -235,15 +408,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/create",
-  "version": "0.6.0",
+  "version": "0.8.0-alpha.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",
@@ -19,7 +19,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "4.1.9"
+    "@getvitops/generator": "8.2.0-alpha.0"
   },
   "engines": {
     "node": ">=24"

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/.astro/types.d.ts

@@ -0,0 +1,3 @@
+declare module 'astro:content' {
+  export function defineLiveCollection(config: unknown): unknown;
+}

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

@@ -1,7 +1,7 @@
 # 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. The
-# `production` GitHub Environment (set up by `scripts/init-github.mjs`) has
+# `production` GitHub Environment (set up by `vitops setup repo`) has
 # required reviewers restricted to admins, so this PAUSES for approval before
 # deploying.
 #

package/templates/emdash/AGENTS.md

@@ -3,10 +3,14 @@ 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
@@ -74,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
 
@@ -90,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
 
@@ -112,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,9 +10,9 @@ 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
 
@@ -27,6 +27,11 @@ pnpm install
 pnpm dev
 ```
 
+Once this is its own repo (not sitting inside the `getvitops/design-system`
+monorepo), uncomment `lint.options` in `vite.config.ts` for type-aware
+`vp check`/`vp lint` — it ships commented out because vite-plus 1.0 only
+honours that option at a project's actual root, and errors on it otherwise.
+
 No Cloudflare account needed: `astro dev` runs the Worker locally with local
 D1/R2 emulation (state in `.wrangler/`). On first boot EmDash runs its
 migrations and applies the structure from `seed/seed.json` — a `pages`
@@ -42,7 +47,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
@@ -82,22 +87,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
@@ -146,8 +147,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.
@@ -155,27 +158,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                                     |