@getvitops/create 0.8.1 → 0.9.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @getvitops/create
 
+## 0.9.0-alpha.0
+
+### Minor Changes
+
+- 161c7f3: A contact form that works end to end: `vitops setup turnstile`, `<wc-turnstile>`, the `vitops.form` EmDash block, and the route the emdash template ships to receive it.
+
+  **CSS, all formats** (no existing class changes): `forms.css` gains `.form-notice--target:not(:target)` (a message revealed only when the URL fragment names it, which is how a prerendered page shows a no-JS form's result) and `:where(wc-turnstile) { display: block }`.
+
+  **`@getvitops/core`:** new `<wc-turnstile sitekey="…">` in `elements.js`. It loads Cloudflare Turnstile on the first interaction with its form (no request to `challenges.cloudflare.com` for a visitor who only reads the page), holds an early submit until the token arrives, and leaves its slotted no-JS explanation in place until JS takes over. Turnstile is category `necessary`, so it is not behind the consent banner.
+
+  **`@getvitops/utils` / `@getvitops/cli`:** new `@getvitops/utils/turnstile` and `vitops setup turnstile [--dry] [--check] [--no-write] [--no-secret]`. It plans from the site's hostnames, creates a managed widget unless one already covers them (an existing widget is adopted, never edited, rotated or deleted), writes the public key to `site.security.turnstile.siteKey`, and pipes the one-time secret to `wrangler secret put VITOPS_TURNSTILE_SECRET` without writing it to any file. Needs `CLOUDFLARE_API_TOKEN` with **Account > Turnstile > Edit** and `CLOUDFLARE_ACCOUNT_ID`.
+
+  **`@getvitops/astro`:** `virtual:getvitops/head` gains `turnstileSiteKey` (read from `site.security.turnstile.siteKey`) so blocks can render the widget. No other change.
+
+  **`@getvitops/generator`:** `TIERS` gains a `turnstile` entry (wc-turnstile, claimed by `vitops.form`); `wc-multi-field`'s `emdashExempt` reason is reworded now the form block exists.
+
+  **`@getvitops/emdash`:** new `vitops.form` block: a field repeater (text, email, phone, long text, choose one, tick box), required flags, help text, success/error messages, optional Turnstile. It renders a semantic `<form method="post">` that works with no JavaScript, with a honeypot named per `createConversionRoute`'s defaults. A field named `phone` submits as `tel`, because the route reserves `phone` and `event`.
+
+  **`@getvitops/create`:** the emdash template ships `src/pages/api/track.ts` (`prerender = false`, `createConversionRoute()`), a seeded contact form, and `challenges.cloudflare.com` in both templates' Report-Only CSP (`script-src`, `frame-src`). The route refuses a post with nowhere to deliver and fails closed when a site key exists without `VITOPS_TURNSTILE_SECRET`. SETUP.html gains the Turnstile step. Existing sites: copy the route and the CSP change, then run `vitops setup turnstile`.
+
+- fec1b4b: The EmDash template's two build scripts are now CLI commands, so fixes reach existing sites with `vp update` instead of a re-copy.
+
+  - `vitops emdash prepare-db` migrates and seeds the local D1 the build prerenders from (was `scripts/prepare-local-db.mjs`). The start and stop calls time out after 5 minutes and it prints progress.
+  - `vitops emdash check-prerender [dir]` fails the build if a prerendered page is not a real page (was `scripts/check-prerender.mjs`).
+
+  **Migration for a site scaffolded earlier:** delete `scripts/prepare-local-db.mjs` and `scripts/check-prerender.mjs`, then in `package.json` set `"prepare-local-db": "vitops emdash prepare-db"`, `"build": "astro build && vitops emdash check-prerender"`, and use the same two commands in place of `node scripts/…` inside `deploy` and `deploy:dev`. A site that never had the scripts needs only the `package.json` entries.
+
+- 224a731: **`@getvitops/astro` (no CSS change; all formats unaffected)**
+
+  - **`site.fonts` is no longer silently ignored.** `vitops()` now turns webfonts on by default when the site config (`site` option, or a `css.input` that is a site config) declares `site.fonts`, and logs that it did. Before, no `@font-face`, preload or warning was emitted unless you also passed `fonts: true`. Pass `fonts: false` to opt out. Migration: none — sites that already set `fonts` behave the same; sites that declared `site.fonts` without it will start loading those families.
+  - **The icon sprite is served when the site config asks for it.** `site.icons.sprite: true` made the generator write `icons.svg`, but only the `icons` integration option copied it to `public/vitops/`, so `/vitops/icons.svg` was never served. It is now mirrored whenever the site config sets it.
+  - **Strict CSP is achievable.** New build-time exports `inlineScriptHashes()`, `cspScriptHash()` and `contentSecurityPolicy()` give the SHA-256 hashes of the two inline scripts `<Head />` emits (colour-scheme bootstrap, consent-gate stub) and a starting policy built on them, with no `'unsafe-inline'` in `script-src`. The scripts moved from `Head.astro`'s frontmatter to `src/inline-scripts.ts` (shipped in the package) so the hash and the emitted bytes are the same constant; the rendered output is byte-identical.
+
+  **`@getvitops/create` (templates; existing scaffolded sites are not changed)**
+
+  - **emdash: every public page is prerendered.** `index.astro`, `[...slug].astro` (via `getStaticPaths` over the published `pages`) and `404.astro` set `prerender = true`. Unknown URLs now return the prerendered 404 with a real 404 status — the old `Astro.rewrite('/404')` from an on-demand route to a prerendered one was refused by Astro, so every unknown URL was a 500. `scripts/pull-content.mjs` (first step of `deploy`/`deploy:dev`) loads production's D1 into the local build database, because the Cloudflare adapter prerenders against a local D1 that is empty on CI; it fails closed. The deploy-prod workflow also runs on a `repository_dispatch` of type `emdash-publish`. Migration for an existing site: copy those pages, the script and the two `package.json` scripts, and add the trigger; previews of unpublished drafts no longer work on the public routes (see AGENTS.md).
+  - **emdash: seed menus are `primary` (Contact), `footer-sitemap` (Home, Contact) and `footer-legal` (Privacy Policy, Terms & Conditions, Cookie Notice)**, replacing `primary` (Home, About) and `footer` (Terms, Privacy), with placeholder `contact` and `cookies` pages so every seeded link resolves. The template Layout still reads the old menu names until it is updated; the seed only applies to an empty database, so existing sites keep their menus.
+  - **Both templates: `badge` and `tag` patterns (group `label`) are enabled, `button` carries `class: "btn"` so `<a class="btn">` is styled, and `neutral`/`surface` are declared as surface roles** (they were chromatic, which emitted no `.bg-neutral`/`text-neutral-muted`). css/bricks/tailwind output of a scaffolded site changes accordingly.
+  - **Both templates ship `public/_headers` with a `Content-Security-Policy-Report-Only` default** naming `<Head />`'s inline scripts by hash. It blocks nothing. `_headers` applies to static assets only, not Worker-rendered responses; see AGENTS.md for the EmDash admin and HTML-block trade-off.
+  - **Guidance is Vite+-first**: `AGENTS.md`, README, the `setup` skill, `SETUP.html` and the session hook use `vp`/`vpr`/`vp exec` instead of `pnpm`/`npx`, with one command table; `vpr dev` is documented as returning immediately. There is no `vp change`/`vp pm change` (checked against vp 1.5.0); the release flow is `dev` → promote.
+  - emdash ships `.agents/skills/custom-blocks/SKILL.md` (compose, extend, site-local, upstream; naming and lifecycle rules) and the favicon `themeColor`/`name` now derive from `site.json`.
+  - Label vocabulary: `badge` is a static label, `tag` is static or dynamic; `chip`/`pill` are not used.
+
+  **`@getvitops/cli`**: the bundled `vitops-design-system` skill points at `vp exec vitops docs <topic>`.
+
+  No consumer-facing change in `@getvitops/core`, `@getvitops/generator`, `@getvitops/utils` or `@getvitops/vite`.
+
+- 55061e2: **Added: `<SiteNav>` and `<SiteFooter>` for Astro/EmDash sites.** Both are tier-1 markup over the existing `sitenav` pattern (no runtime JS: `<details>` accordions + Popover API drawer). Non-breaking.
+
+  - `<SiteNav {...await loadNavMenus(getMenu)} />` renders EmDash menu `primary` (the default: depth 3, dropdowns from the `md` container width, drawer below). If a `primary-mobile` menu exists it replaces the nav below `md` (depth 1); if `primary-mega` exists it replaces it from `xl` (mega panels). Adding the menu in the admin is the whole change. Only one tier is in the accessibility tree at a time. An item's `titleAttr` is its description (EmDash has no description field yet).
+  - `<SiteFooter sitemap legal name>` renders `footer-sitemap` + `footer-legal` + a copyright line.
+  - `@getvitops/astro/components/sitenav.ts` exports the pure helpers (`loadNavMenus`, `selectTiers`, ...).
+  - CSS (`patterns/sitenav.css`, **all formats**): tier visibility classes (`.sitenav-tier--below-*`/`--from-*`), `.sitenav--mega`, `.sitenav__desc`, `.sitefooter*`, `aria-current` styling, reduced-motion and forced-colors handling. Existing `.sitenav` rules are unchanged, so the Bricks element is unaffected.
+  - `@getvitops/create` (emdash template): the layout now renders header and footer through these components, with the colour-scheme toggle in the header. It reads menus `primary`, `footer-sitemap` and `footer-legal`; a template whose seed still has the old `footer` menu renders no footer links until the seed is updated.
+  - `@getvitops/generator`: `TIERS.sitenav` now lists the two Astro components.
+
+- 7a4241e: EmDash template: make the database a build prerenders from valid before it builds, and fail the build when it isn't. The template runs `migrations: { runtime: 'check' }`, so a build against a local D1 with pending migrations prerendered EmDash's one-line "Database migrations are required" response into every page while still succeeding. A fresh CI runner, a first deploy, a `SKIP_PULL_CONTENT=1` build and an upgrade deploy all hit it.
+
+  - **New `scripts/prepare-local-db.mjs`** (`vpr prepare-local-db`): starts `astro dev` once, calls EmDash's `dev-bypass` setup (which migrates and applies the seed's sample content), checks the home page renders, and stops it. Writes only the disposable `.wrangler/state`. Run after `pull-content` by `vpr deploy`, `vpr deploy:dev` and the reusable deploy workflow. `SKIP_PREPARE_LOCAL_DB=1` skips it.
+  - **New `scripts/check-prerender.mjs`**, part of `vpr build` and both deploy scripts: fails when any prerendered page is not an HTML document with a title, or carries the pending-migrations message.
+  - **Existing sites:** add the two scripts, the `prepare-local-db` script entry, and `&& node scripts/check-prerender.mjs` after `astro build`; add a "Prepare local database" step before each Build step in a copied deploy workflow. Run `vpr prepare-local-db` once before a first local `vpr build`.
+
+  No consumer-facing change in the other toolchain packages.
+
+### Patch Changes
+
+- 06d6112: Fix the EmDash `/design-system` admin page erroring on a tailwind site. It fetches `/vitops/design-manifest.json`, which the `tailwind` format never emitted and the integration only mirrored under `editor: true` (which also loads `editor.js` on every public page).
+
+  - **generator** (`tailwind` format only): `design-manifest.json` is now emitted alongside `tailwind.css`. No change to the CSS.
+  - **astro**: new `vitops({ editorManifest: true })` writes everything an outside host needs into `public/vitops/` (`design-manifest.json`, `editor.js`, a standalone `editor.css`, and `design-system-editor.html`) without loading the editor on public pages. `editor: true` still loads it from `<Head />`.
+  - **vite**: `editorManifestDir` also writes `vitops/editor.css`, from a throwaway `css`-format pass on tailwind sites.
+  - **emdash**: the `/design-system` admin page was unstyled and overflowed the admin, because the editor borrows the framework CSS and the admin never loads it. It now embeds `/vitops/design-system-editor.html` in an iframe, so the design system can't leak into the admin's styles. **Requires `editorManifest: true`** in `vitops({ … })`.
+  - **create**: the EmDash template sets `editorManifest: true`. Existing sites: add it to `vitops({ … })` in `astro.config.mjs`.
+
+  No consumer-facing change in the other toolchain packages.
+
+## 0.8.2
+
+### Patch Changes
+
+- 29fc659: EmDash template: the per-project EmDash skills install command is now `npx skills add emdash-cms/skills --skill '*' -y`. Without `-a`, the CLI writes the skills to `.agents/skills/` and symlinks them into `.claude/skills/`, so Claude Code and every other agent see the same files. The 0.8.0 notes named `-a claude-code`, which copies into `.claude/skills/` only.
+
 ## 0.8.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/create",
-  "version": "0.8.1",
+  "version": "0.9.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": {
-    "@getvitops/generator": "8.2.0"
+    "@getvitops/generator": "8.3.0-alpha.0"
   },
   "engines": {
     "node": ">=24"

package/templates/emdash/.agents/skills/custom-blocks/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: custom-blocks
+description: Decide whether a page section needs a new EmDash block type, and if so how to name, build, version and retire it. Use before creating, renaming or deleting any block type, any `src/components/blocks/*` renderer, or when asked to "add a block", "make an editable section" or "add a component the editors can place".
+---
+
+# Custom blocks
+
+Pages are composed from **blocks** so non-technical editors can rearrange and edit
+them in the CMS. A new block type is the most expensive way to get a section onto a
+page: it adds a content-model entry, a renderer, a field schema and a migration
+burden, and **a block type cannot be renamed or deleted** once pages use it (see
+"Lifecycle"). So work down this list and stop at the first rung that fits.
+
+## 1. Decision rule
+
+1. **Compose what exists.** The `vitops.*` blocks from `@getvitops/emdash` (cards,
+   carousel, gallery, accordion, details, banner, hero, marquee, image-compare,
+   copy button, action link, …) resolve inside any block type's `portableText` field,
+   so "a section with a heading, intro and then a row of cards" is a section block
+   whose body holds `vitops.cards` — not a new "cards section" type. Check what is
+   installed first: `vp exec vitops docs components` lists every block the toolchain
+   ships and which tier provides it.
+2. **Extend an existing block** if one is close. An extra option (a `variant`
+   select, an optional slot) on a block that already exists is a version bump on that
+   block, not a new type. Prefer this when the new thing is a variation of the same
+   content shape.
+3. **Site-local block type** only when the content shape is specific to this site
+   (a bespoke dashboard mock, an A-versus-B argument with hard-coded figures). Keep
+   the renderer in `src/components/blocks/` and the type name prefixed for the site
+   (see "Naming"). Code-owned widgets expose only a caption field; the numbers live in
+   code, not in the CMS.
+4. **Upstream it** when a second site would plausibly want it. Don't build a
+   generic block here and quietly fork it: raise it against the toolchain
+   (`getvitops/design-system`) with the shape you used, so every site gets it. Until
+   it ships, keep the local version and mark it `local (watch)` in a comment, so it
+   is easy to retire when the real one lands.
+
+A form, a section container, a stats row, a logo grid, a CTA band and a steps list
+are all _generic_ — expect to find them upstream or to upstream them, not to keep
+them local.
+
+## 2. Naming: check the framework's vocabulary first
+
+Block types are permanent, so the name has to be right the first time. Before you
+name one:
+
+- Run `vp exec vitops docs components` and `vp exec vitops docs classes`. If the
+  framework already has a pattern by that name, **use its meaning**: `badge` is a
+  _static_ label; `tag` is a label that may be static or dynamic (editable,
+  dismissable). Never `chip` or `pill`. A block called `chips` that renders badges
+  cost one site a new type, a content migration and a permanently retired type.
+- Prefix site-local types with a short site code (`acme_section`), never `vitops.`
+  — that namespace belongs to the toolchain.
+- Name the thing, not its look: `section`, `steps`, `logos`; not `green-box`.
+
+## 3. Field and renderer conventions
+
+- **Colour: `tone` plus optional `color`.** `tone` takes a **role** name from
+  `site.json`'s `colors.roles` (preferred), falling back to a semantic name
+  (`info` `success` `warning` `danger`); `color` is the escape hatch for a palette
+  hue/step and should be rare — a site that sets it on every item is telling you a
+  role is missing. A select field can only list static options, so either list the
+  roles you actually use or take a validated string. Resolve it in one shared helper
+  (`src/components/blocks/tone.ts`) rather than per block.
+- **Class names cannot be built from field values.** Tailwind only emits classes it
+  can read in source, so `` `bg-${tone}` `` produces nothing. Resolve a tone to CSS
+  custom properties (or a lookup table of whole class names) instead.
+- **Links are `url` fields**, not `string`: EmDash's `url` type accepts site-relative
+  paths. (`string` is a mistake that needs a breaking version to undo.)
+- **Repeater sub-fields are scalar-only** (no `portableText`, no links inside text),
+  so a checklist is one newline-separated `text` field. Don't fight it; rich item
+  bodies need EmDash to lift that limit.
+- **Blocks don't nest.** A "section containing stats" is the section's own body
+  holding `vitops.*` blocks, or a flat sequence of sibling blocks; per-section
+  backdrops don't carry across siblings.
+- **Reach for framework classes** (`centered`, `region`, `rhythm`, `subgrid`,
+  `cluster`, `font-*`, `card`, `badge`, `tag`) in the renderer; run
+  `vpr lint:design` — hand-written layout CSS in a block is the signal that the
+  framework is missing a pattern worth upstreaming.
+- A card title is a heading: render a real `<h2>`–`<h4>` with a level prop, not a
+  styled `<p>`.
+
+## 4. Lifecycle
+
+- **Create** with the schema tools (the `schema_*` actions on the site's MCP server,
+  `/_emdash/api/mcp`) or the admin; commit the matching renderer and the
+  `emdash export-seed` output so a fresh environment gets the same model.
+- **A breaking change is a new version**, not an edit: add the version, migrate the
+  entries that use the old one, then activate it. Two things the tooling does not say:
+  `schema_activate_block_type_version`'s `expectedFingerprint` is the fingerprint of
+  the **currently active** version, not the one you are activating (a mismatch is a
+  `CONFLICT`), and `schema_update_block_type` **replaces the whole `fields` list**, so
+  send every field, not just the changed one.
+- **Migrating content:** `emdash content update` has no `--migrate-blocks` flag; the
+  REST route `PUT /_emdash/api/content/<collection>/<id>` with
+  `{ data, _rev, migrateBlocks: true }` does (it takes Portable Text arrays; the CLI
+  and MCP take Markdown). Updating a published entry stages a **draft** — a separate
+  `content publish` is needed before the live page changes, and (because pages are
+  prerendered) a rebuild after that.
+- **Retiring is not deleting.** A type that was renamed or superseded stays in the
+  database and the seed permanently; keep its renderer mapping old values so existing
+  content still renders, mark it retired, and stop offering it to editors.
+- **Typed fields:** `emdash types` does not type `blocks` fields (they come out as
+  `unknown[]`); hand-write a value type per renderer until EmDash generates it.

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

@@ -7,14 +7,14 @@ description: Work the client-onboarding checklist (SETUP.html) autonomously —
 
 `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.
+(or `vp exec vitops setup --help`) for what each stage actually does and why.
 
 ## Steps
 
 1. **Preview the whole sequence first.**
 
    ```bash
-   npx vitops setup all --dry
+   vp exec vitops setup all --dry
    ```
 
    Read the plan before doing anything. It names every step it would take and
@@ -24,10 +24,10 @@ gates, and where to stop. It does not restate the steps; read `SETUP.html`
 2. **Run it.**
 
    ```bash
-   npx vitops setup all
+   vp exec vitops setup all
    ```
 
-   Re-run `npx vitops setup --check` after each leg rather than retrying on
+   Re-run `vp exec 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.

package/templates/emdash/.claude/hooks/session-start.sh

@@ -31,10 +31,13 @@ export PATH="$NODE24_BIN:$PATH"
 echo "export PATH=\"$NODE24_BIN:\$PATH\"" >> "$CLAUDE_ENV_FILE"
 
 # --- Dependencies (pnpm, pinned via package.json > packageManager) -----------
+# pnpm is the bootstrap here: `vp` (Vite+) is a devDependency, so it only exists
+# once this install has run. After that, use `vp install` / `vpr <script>` /
+# `vp exec <bin>` — see AGENTS.md "Commands".
 cd "$CLAUDE_PROJECT_DIR"
 export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
 corepack enable
 # `install` (not `--frozen-lockfile`) so the warmed container cache is reusable.
 pnpm install
 
-echo "Ready: Node $(node --version), pnpm $(pnpm --version)"
+echo "Ready: Node $(node --version), pnpm $(pnpm --version), vp $(./node_modules/.bin/vp --version 2>/dev/null | head -1 || echo 'not installed')"

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

@@ -8,12 +8,23 @@
 # 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
 #
+# Also runs on a `repository_dispatch` of type `emdash-publish`: pages are
+# prerendered, so a publish in the EmDash admin only goes live after a rebuild,
+# and an EmDash `content:afterPublish` hook POSTs that event (AGENTS.md,
+# "Publish-triggered rebuilds"). A dispatch runs this file from the DEFAULT branch
+# (`dev`), so `ref` pins the build to `main` — production's code, not dev's. It
+# still goes through the `production` environment, so it still waits for the
+# reviewers' approval; relax that rule if editors' publishes should go live
+# unattended.
+#
 # Required repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
 name: Deploy prod
 
 on:
   push:
     branches: [main]
+  repository_dispatch:
+    types: [emdash-publish]
 
 concurrency:
   group: deploy-prod
@@ -25,6 +36,7 @@ jobs:
     with:
       environment: production
       is-dev: false
+      ref: ${{ github.event_name == 'repository_dispatch' && 'main' || '' }}
       # Set this to your production URL once known.
       health-check-url: ''
     secrets:

package/templates/emdash/AGENTS.md

@@ -1,5 +1,5 @@
-This is an EmDash CMS website (Astro SSR on Cloudflare Workers, D1 + R2)
-styled by the Vitops design system.
+This is an EmDash CMS website (Astro on Cloudflare Workers, D1 + R2 — public pages
+prerendered, the Worker serving the admin and API) styled by the Vitops design system.
 
 ## Ground rules
 
@@ -21,11 +21,11 @@ styled by the Vitops design system.
   `@getvitops/emdash` are merged in automatically).
 - **Building pages from patterns:** the editor's insert menu offers the `vitops.*` blocks —
   link/button, image compare, copy snippet, banner, disclosure, accordion, hero, carousel, gallery,
-  cards, marquee (`npx vitops docs blocks` lists them with every field). Repeating content (cards, gallery images, accordion items, carousel slides) is
+  cards, marquee (`vp exec vitops docs blocks` lists them with every field). Repeating content (cards, gallery images, accordion items, carousel slides) is
   a repeater field. A block cannot contain other blocks, and a `vitops.*` block inside EmDash's
   built-in `columns` does not render — for layout (a section, a split, a hero) use a `blocks`
   field, or hand-write the page template with `@getvitops/astro` components
-  (`Subgrid`, `Cards`, `Carousel`, …). `npx vitops docs components` lists every pattern, which
+  (`Subgrid`, `Cards`, `Carousel`, …). `vp exec vitops docs components` lists every pattern, which
   tiers provide it, and which block renders it. Override a block's rendering per site with
   `<PortableText components={{ type: { 'vitops.cards': MyCards } }} />`; hide one with
   `vitopsEmdash({ blocks: { exclude: [...] } })` in `astro.config.mjs`.
@@ -36,7 +36,7 @@ styled by the Vitops design system.
   (`/_emdash/admin`) or the site's MCP server (`/_emdash/api/mcp`) to change
   the content model of a running site.
 - Prefer framework CSS classes (utilities, patterns, type roles like
-  `font-heading`) over bespoke CSS. Run `npx vitops agents` to append the
+  `font-heading`) over bespoke CSS. Run `vp exec vitops agents` to append the
   full generated class-vocabulary reference to this file.
 - **Layout foundations — these are the answer, not a starting point.** Six
   substitutions carry the structure of nearly every page:
@@ -70,18 +70,81 @@ styled by the Vitops design system.
   `li` is the grid item, so the anchor's tranches never align and it does not fill
   the cell; it renders fine, which is why it keeps getting written.
 
-  `npm run lint:design` reports all of these, and the pre-commit hook fails on them
+  `vpr lint:design` reports all of these, and the pre-commit hook fails on them
   — the fix is the class, not a justification for the CSS.
 
-- **Prerender by default.** `output: 'server'` is required (the admin, media/API
-  routes, preview and scheduled publishing need a server), so prerendering is
-  opt-in per route: put `export const prerender = true` on every page that
-  doesn't need per-request data, and give dynamic routes a `getStaticPaths()`
-  that queries the collection at build time. A route with no `prerender` export
-  is re-rendered for every visitor on every request. The cost is that a
-  prerendered page reflects the database as of the last build, so an admin
-  publish needs a redeploy — leave a route server-rendered only where that is
-  unacceptable (preview, personalised content, must-be-live-in-seconds).
+- **Rendering and freshness: everything is prerendered.** `output: 'server'` is
+  still required (the admin, media/API routes and scheduled publishing need a
+  Worker), but every public page — `index.astro`, `[...slug].astro`, `404.astro` —
+  has `export const prerender = true`, and `[...slug].astro` lists the published
+  `pages` entries in `getStaticPaths()`. The HTML is written at build time and
+  served as a static asset; the Worker only handles `/_emdash/*` and anything
+  you deliberately leave on-demand. A route with no `prerender` export is
+  re-rendered on every request, so don't leave it off by accident.
+  - **Where build-time content comes from.** The Cloudflare adapter prerenders
+    against a _local_ D1 (`.wrangler/state`), never the deployed one — on a CI
+    runner that is an empty database, which would bake "No home page yet" into
+    every page. `scripts/pull-content.mjs` (the first step of `vpr deploy` and
+    `vpr deploy:dev`) exports production's D1 and loads it locally first. It
+    fails closed: a failed export aborts the deploy rather than publishing an
+    empty site (the one exception is a database that doesn't exist yet, the first
+    deploy, which builds from the seed). `SKIP_PULL_CONTENT=1` skips it.
+  - **The local database must be migrated before the build.** The template runs
+    `migrations: { runtime: 'check' }`, so a build against a local database with
+    pending migrations prerenders EmDash's one-line "Database migrations are
+    required" response into every page — and still succeeds. That is what a fresh
+    runner, a first deploy, a `SKIP_PULL_CONTENT=1` build and an **upgrade** deploy
+    (the pull restores production's older schema, and `emdash migrate` only runs
+    after the build) would all publish. `vitops emdash prepare-db` (`vpr prepare-local-db`, run after the
+    pull by `vpr deploy`, `vpr deploy:dev` and the reusable workflow) starts `astro
+    dev` once, calls EmDash's `dev-bypass` setup (which migrates and applies the
+    seed's sample content) and stops it; `vitops emdash check-prerender` (part of
+    `vpr build`) then fails the build if any prerendered page is not a real HTML page
+    with a title. Run `vpr prepare-local-db` by hand before a first local `vpr build`.
+    It only writes the disposable `.wrangler/state`; the dev administrator it creates
+    is never deployed.
+  - **Freshness is a rebuild.** Production is the truth for content, and a page
+    reflects it as of the last build. Publishing in the admin therefore has to
+    trigger one: the deploy workflows listen for a `repository_dispatch` event of
+    type `emdash-publish` (see "Publish-triggered rebuilds" below).
+  - **Drafts and previews.** A prerendered page cannot show an unpublished
+    draft, so an admin "Preview" link shows the last published build. If previews
+    matter, add a dedicated on-demand route for them rather than removing
+    `prerender` from the public ones.
+  - **Dynamic parts are server islands.** Anything that must be fresh per request
+    goes in its own component rendered with `server:defer` inside the prerendered
+    page; the surrounding HTML stays static. Keep islands rare — each is a Worker
+    request after load.
+  - **Unknown URLs.** There is no `Astro.rewrite('/404')`: a slug not listed by
+    `getStaticPaths()` has no route, so Astro serves the prerendered `404.html`
+    with a real 404 status. Rewriting an on-demand route to a prerendered one
+    fails (500), so don't reintroduce it.
+- **The contact form is the one on-demand route.** The `vitops.form` block posts a plain
+  `<form method="post">` to `src/pages/api/track.ts` (`prerender = false`, built with
+  `createConversionRoute()`), which also answers the conversion beacons. The block works with
+  no JavaScript: the route answers a form post with a 303 back to the page plus `?sent=1#form-sent`
+  or `?error=1#form-error`, and the block's two notices are revealed by that fragment. Keep one
+  form per page. Where submissions go: `site.notifications.email` (or the primary location's
+  `email`) and `site.crm` when set. **With neither, the route refuses the post** rather than
+  accept a message nobody receives, so set `site.notifications.email` before launch and run
+  `vitops email setup` for its sender domain. A failed CRM write never fails the request; it is
+  stated in the notification email, which is the durability floor.
+  - **Spam protection**: a honeypot field, the route's origin / size / per-IP rate checks, and
+    Cloudflare Turnstile once `vitops setup turnstile` has put the public key in
+    `site.security.turnstile.siteKey` and saved the Worker secret `VITOPS_TURNSTILE_SECRET`
+    (never in `site.json`). With a key set the route fails closed if the secret is missing.
+    `TURNSTILE_REQUIRED` in the route (default `true`) makes a token-less post a refusal, which
+    means the form needs JavaScript; set it `false` to keep a no-JS submit working and accept
+    that a bot can then skip the token. Turnstile is category `necessary` (it protects the form
+    being sent), loads only when a visitor first uses the form, and its origin is allowed in the
+    Report-Only CSP in `public/_headers`.
+  - **Privacy policy inventory.** `vitops legal` derives "what personal information we collect"
+    from `site.templates` entries of type `form`, not from the editor's block, so a form added in
+    the admin is invisible to it. When you add or change form fields, mirror them in a
+    `site.templates` form entry in `site.json`, or the generated policy under-reports.
+  - A field named `phone` submits as `tel` (the route reserves `phone` and `event`).
+  - The per-IP rate limit is per Worker isolate; add a KV-backed `RateLimitStore` if you need a
+    fleet-wide one.
 - The Worker cron trigger in `wrangler.jsonc` drives scheduled publishing —
   don't remove it.
 - Hosting (adapter + EmDash database/storage) comes from `vitopsHosting()`
@@ -110,7 +173,7 @@ styled by the Vitops design system.
   a finished policy, because the risk here is a plausible-looking document
   getting shipped unread.
   To replace them properly, fill in `site.json`'s `organization`/`site.legal`
-  fields and run `npx vitops legal --format portable-text --out ./legal`, then
+  fields and run `vp exec 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.
@@ -129,7 +192,7 @@ styled by the Vitops design system.
 - **Submit `/sitemap.xml`** to search engines, not a per-collection sitemap;
   collection sitemaps now split into pages of 2,000 entries.
 - **A stuck D1 migration lock** is cleared with
-  `pnpm exec emdash migrate --take-over-lock <id>` (confirms the target, or
+  `vp exec emdash migrate --take-over-lock <id>` (confirms the target, or
   needs `--expected-target-fingerprint` non-interactively).
 
 ## Docs MCP servers
@@ -137,6 +200,92 @@ styled by the Vitops design system.
 `.mcp.json` preconfigures the Astro docs and EmDash docs MCP servers — prefer
 searching them over pre-trained knowledge for Astro/EmDash questions.
 
+## Labels: badge and tag
+
+Two label patterns, both enabled in `site.json`'s `patterns.items`: **`badge`** is a
+static label (a status, count or category) and **`tag`** is a label that may be
+static _or_ dynamic (editable, dismissable, in a `tag-list`). Don't invent a third
+name — `chip` and `pill` are not part of this vocabulary. The button pattern's class
+is `btn` (`<a class="btn">` is styled, not just a bare `<button>`).
+
+## Custom blocks
+
+Before adding a block type, a `src/components/blocks/*` renderer, or anything an
+editor places on a page, read `.agents/skills/custom-blocks/SKILL.md`: compose the
+existing `vitops.*` blocks first, extend one second, go site-local third, upstream
+last. Block types can't be renamed or deleted once pages use them, so check the
+framework's pattern names before choosing one.
+
+## Publish-triggered rebuilds
+
+Pages are static, so a publish in the admin goes live only after a rebuild.
+`.github/workflows/deploy-prod.yml` also runs on a `repository_dispatch` event of
+type `emdash-publish` (it pins `ref` to `main`, because a dispatch runs from the
+default branch, `dev`). Wire an EmDash plugin hook to send it:
+
+```jsonc
+// emdash-plugin.jsonc
+"capabilities": ["content:read", "network:request"],
+"allowedHosts": ["api.github.com"]
+```
+
+```ts
+// src/plugin.ts
+hooks: {
+  'content:afterPublish': async (_event, ctx) => {
+    const token = await ctx.settings.get<string>('githubToken'); // an encrypted plugin setting
+    if (!token || !ctx.http) return;
+    await ctx.http.fetch(`https://api.github.com/repos/${OWNER}/${REPO}/dispatches`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json' },
+      body: JSON.stringify({ event_type: 'emdash-publish' }),
+    });
+  },
+}
+```
+
+The token is a fine-grained GitHub token with `Contents: write` on this repo only,
+stored as the plugin's encrypted setting (a sandboxed plugin can't read Worker
+environment variables), never in the repo. The hook name, capabilities and
+`ctx.http` / `ctx.settings` calls follow EmDash's plugin reference but this exact
+plugin has not been run against a live site, so treat it as a starting point. Two
+costs to know: the run goes through the `production` environment, so it **waits for
+the reviewers' approval** like any prod deploy (relax that rule if editors' publishes
+should go live unattended), and bursts of publishes queue behind the
+`deploy-prod` concurrency group rather than cancelling each other. Without the hook,
+a manual run of **Deploy prod** (or a push to `main`) does the same job.
+
+## Content Security Policy
+
+`public/_headers` ships a **`Content-Security-Policy-Report-Only`** header: it logs
+violations to the browser console and blocks nothing, so it can't break a page. Its
+`script-src` is `'self'` plus the SHA-256 of each inline script `<Head />` emits (the
+colour-scheme bootstrap and the consent-gate stub) — no `'unsafe-inline'`. Hashes,
+not nonces, because prerendered pages have no per-request response to put a nonce in.
+`contentSecurityPolicy()` and `inlineScriptHashes()` from `@getvitops/astro` produce
+the same strings (`templates.test.ts` in the toolchain keeps the file in step).
+
+Know what it does not cover before you flip it to enforcing (rename the header to
+`Content-Security-Policy`):
+
+- **`_headers` applies to static assets only.** Worker-rendered responses — the EmDash
+  admin (`/_emdash/*`), its API, anything left on-demand — don't get it. Setting a
+  header there means doing it in code (e.g. Astro middleware calling
+  `contentSecurityPolicy()`), and the admin's own inline scripts and editor HTML
+  would need allowing; leave the admin out of an enforced policy.
+- **Editor-authored HTML blocks are the hard limit.** Any block that lets an editor
+  paste raw HTML or a `<script>` (an embed, a tracking snippet) puts arbitrary inline
+  script on the page, which a hash policy cannot name ahead of time. Enforcing a strict
+  policy means removing such blocks or moving embeds to a consent-gated
+  `data-consent` tag whose origin you allow explicitly.
+- **Third-party tags** the consent gate activates need their origins in `script-src`
+  / `connect-src`; anything with `frame` needs `frame-src`.
+- **A server island** (`server:defer`) adds an inline loader script and a request to
+  the Worker; expect a report for the loader until you hash it.
+
+Run the site, browse the pages you ship with the console open, fix or allow what is
+reported, and only then enforce.
+
 ## EmDash agent skills
 
 The EmDash skills (`building-emdash-site`, `creating-plugins`, `emdash-cli`,
@@ -146,20 +295,55 @@ project, not globally, so they match the `emdash` version this repo pins. If
 and `SETUP.html` have the full step):
 
 ```bash
-npx skills add emdash-cms/skills --skill '*' -a claude-code -y
+vp dlx skills add emdash-cms/skills --skill '*' -y
 ```
 
-Refresh them with `npx skills update` after bumping `emdash` — the
+Refresh them with `vp dlx skills update` after bumping `emdash` — the
 `upgrading-emdash` skill covers the rest of the upgrade.
 
 ## Commands
 
-- `pnpm dev` — local dev with local D1/R2 emulation (no Cloudflare account)
-- `pnpm typecheck` — `astro check`
-- `pnpm deploy` — build + `wrangler deploy` prod (provisions D1/R2 on first run)
-- `pnpm deploy:dev` — build + deploy the isolated dev worker (needs `DEV_D1_ID`)
-- `pnpm run init:github` — one-time: create + push the GitHub repo (main + dev,
-  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 site.json` — schema-check the site config
+This is a **Vite+** project: use `vp` (and its `vpr` shorthand), not `pnpm`/`npm`/`npx`.
+The package manager underneath is pnpm, but `vp` picks it up for you.
+
+| To…                                      | Run                                                     |
+| ---------------------------------------- | ------------------------------------------------------- |
+| install dependencies                     | `vp install`                                            |
+| add / remove / update a package          | `vp add <pkg>` · `vp remove <pkg>` · `vp update`        |
+| run a `package.json` script              | `vpr <script>` (alias for `vp run <script>`)            |
+| run a locally installed binary           | `vp exec <bin>` (e.g. `vp exec vitops docs components`) |
+| run a one-off package without installing | `vp dlx <pkg>`                                          |
+| format + lint + typecheck (files)        | `vp check`                                              |
+| typecheck Astro (`.astro` files)         | `vpr typecheck`                                         |
+
+**Scripts that wrap Astro must go through `vpr`.** `vp dev` / `vp build` run Vite
+directly and skip Astro, so use `vpr dev`, `vpr build`, `vpr preview`.
+
+**`vpr dev` returns immediately.** `astro dev` now starts the server in the
+background. Check it with `vp exec astro dev status`, read its output with
+`vp exec astro dev logs --follow`, and stop it with `vp exec astro dev stop`; the
+site is at <http://localhost:4321>. Don't wait on it as if it were a foreground
+process.
+
+| Script                              | What it does                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `vpr dev`                           | local dev with local D1/R2 emulation (no Cloudflare account)                                |
+| `vpr deploy`                        | pull production content, build, `wrangler deploy` prod (provisions D1/R2 on first run)      |
+| `vpr deploy:dev`                    | same, for the isolated dev worker (needs `DEV_D1_ID`)                                       |
+| `vpr pull-content`                  | just the content pull (see "Rendering and freshness")                                       |
+| `vpr prepare-local-db`              | migrate and seed the local D1 the build prerenders from                                     |
+| `vpr init:github`                   | one-time: create + push the GitHub repo (main + dev, dev default). Only when the user asks. |
+| `vpr init:hosting`                  | one-time: provision hosting (dev D1/R2 + repo secrets). Only when the user asks.            |
+| `vp exec vitops validate site.json` | schema-check the site config                                                                |
+
+**Release flow.** A site is not a published package, so there is no changeset or
+version bump: ship by committing to `dev` (auto-deploys the dev worker) and then
+running the **promote** workflow. `vp` has no `vp change` / `vp pm change` command
+(checked against vp 1.5.0); for a _package_ it does have `vp pm version`,
+`vp pm publish` and `vp pm stage`.
+
+**Naming the project.** `vp create` takes the package name from the target
+directory and invents a random slug when none is given, so pass one:
+`vp create @getvitops:emdash --directory <client-slug>`. `wrangler.jsonc`'s
+`name`, D1 `database_name` and R2 `bucket_name` are separate and still say
+`my-emdash-site` — rename them to match before the first deploy.