@getvitops/create 0.8.2 → 0.9.0-alpha.1

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,14 +21,30 @@ 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`.
+- **Escape hatches on every block.** Each `vitops.*` block (and the section type) has an
+  `anchor` (becomes the `id`, for `#links`), `className` (extra classes — with the tailwind format
+  only ones the site already uses) and `style` (CSS custom properties only, e.g. `--p-card: 2rem`;
+  anything else is dropped). `vitops_section` also has a `theme`: one pick for a tinted or solid
+  backdrop with readable text. Set `--header-offset` to the sticky header's height so anchors
+  clear it.
+- **`vitops audit`** needs optional packages and a browser, checked before it starts a server:
+  `vp add -D playwright @axe-core/playwright lighthouse && vp exec playwright install chromium`.
+  Its page list is the built sitemap, then the seed's menus.
+- **Section, block or widget area?** Copy-and-edit content is an EmDash Section. The same content
+  everywhere (an announcement bar, a pre-footer call to action, a sidebar, footer columns) is a
+  **widget area**: define it under Widgets in the admin, render it with
+  `<VitopsWidgetArea name="…" />` from `@getvitops/emdash/astro` in the layout, or place it in
+  page content with the `vitops.widgetArea` block. The layout renders `announcement` and
+  `pre-footer`. Page-specific content is blocks. An area cannot hold another area, and prerendered
+  pages show an edit after the next deploy (like menus).
 - `seed/seed.json` only applies against an empty database: structure
   (collections, menus, settings) on first boot; the `content` entries only
   when the setup wizard's "include sample content" option is chosen. Changing
@@ -36,7 +52,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 +86,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 +189,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 +208,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 +216,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 +311,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 '*' -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.

package/templates/emdash/README.md

@@ -3,7 +3,7 @@
 An [EmDash CMS](https://docs.emdashcms.com) website on Cloudflare Workers,
 styled by the [Vitops design system](https://www.npmjs.com/org/getvitops).
 
-Scaffolded from `vp create @getvitops:emdash`.
+Scaffolded from `vp create @getvitops:emdash --directory <client-slug>` (pass a directory: `vp create` derives the package name from it and invents a random slug otherwise).
 
 ## Stack
 
@@ -15,7 +15,7 @@ Scaffolded from `vp create @getvitops:emdash`.
   `src/assets/logo.svg`, and serves the web-component runtime
 - **`@getvitops/emdash`** — design-system Portable Text blocks in the editor
   slash menu (hero, cards, accordion, carousel, gallery, marquee, banner, …);
-  `npx vitops docs blocks` lists every block and field
+  `vp exec vitops docs blocks` lists every block and field
 
 `src/assets/placeholder/` ships neutral wireframe images for layout work
 before real imagery exists — delete once real assets land (separate from
@@ -24,8 +24,8 @@ before real imagery exists — delete once real assets land (separate from
 ## Local development
 
 ```bash
-pnpm install
-pnpm dev
+vp install
+vpr dev
 ```
 
 Once this is its own repo (not sitting inside the `getvitops/design-system`
@@ -36,22 +36,30 @@ 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`
-collection, a `primary` menu, and the site settings.
+collection, three menus (`primary`, `footer-sitemap`, `footer-legal`), and the site
+settings.
 
 - Site: <http://localhost:4321>
 - Admin: <http://localhost:4321/_emdash/admin>
 
 Open the admin and complete the setup wizard — it creates your first account,
 and choosing to **include sample content** publishes the starter pages from
-the seed: home, about, terms (`/terms`), and privacy policy (`/privacy`).
-Until then the home route shows a friendly empty state. Unknown paths render
-`src/pages/404.astro`.
+the seed: home, about, contact (`/contact`), terms (`/terms`), privacy policy
+(`/privacy`) and cookie notice (`/cookies`) — every link in the seeded menus
+resolves. Until then the home route shows a friendly empty state. Unknown paths
+get the prerendered `src/pages/404.astro` with a real 404 status.
+
+**Pages are prerendered.** `vpr build` writes static HTML for every published
+`pages` entry, so an edit in the admin goes live on the next rebuild rather than
+per request — see AGENTS.md "Rendering and freshness" for how production content
+reaches the build (`scripts/pull-content.mjs`) and for the publish-triggered rebuild.
+In `vpr dev` the pages read your local database, so edits appear straight away.
 
 The two legal pages are placeholders. To generate real ones from what your site
 actually does, fill in `site.json`'s `organization`/`site.legal` fields and run:
 
 ```sh
-npx vitops legal --format portable-text --out ./legal
+vp exec vitops legal --format portable-text --out ./legal
 ```
 
 Then paste each document's blocks into the matching page in the admin. The
@@ -61,8 +69,8 @@ before you publish.
 ## Deploy
 
 ```bash
-npx wrangler login
-pnpm deploy
+vp exec wrangler login
+vpr deploy
 ```
 
 Wrangler provisions the D1 database and R2 bucket named in `wrangler.jsonc`
@@ -92,7 +100,7 @@ One-time setup — see [Start a new EmDash site](https://docs.vitops.ca/guides/n
 procedure, then work through the checklist:
 
 ```bash
-pnpm run sop && open SETUP.html   # or: xdg-open SETUP.html
+vpr sop && open SETUP.html   # or: xdg-open SETUP.html
 ```
 
 It covers host choice, GitHub + branch policy, hosting resources, going live
@@ -102,7 +110,7 @@ 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
+`vpr deploy:dev` reproduces the dev deploy locally: it rewrites the
 adapter-generated wrangler config (`scripts/build-dev-wrangler.mjs`) so the
 dev worker never touches prod data — it hard-fails without `DEV_D1_ID`,
 on purpose. Schema/content changes live in the EmDash database, not git, so
@@ -119,7 +127,7 @@ is a configurable dimension of the project, not a rewrite:
   belong to this target.
 - **`node`** — `@astrojs/node` (standalone) + SQLite file + local uploads,
   for a VPS / docker-compose / k8s host. Not installed by default; to switch:
-  `pnpm add @astrojs/node better-sqlite3`, then `vitopsHosting({ target:
+  `vp add @astrojs/node better-sqlite3`, then `vitopsHosting({ target:
   'node' })` (or set `HOSTING=node` — the env var wins). Run the built site
   with `node ./dist/server/entry.mjs`; data lives in `./data/` (gitignored) —
   persist it as a volume. Scheduled publishing runs in-process on Node, so
@@ -139,12 +147,12 @@ and media in the storage backend (bucket/directory copy).
   agents answer from current documentation. Your running site also exposes its
   own content MCP server at `/_emdash/api/mcp` (authenticated).
 - **Skills** (`.agents/skills/`): `promote` dispatches the dev → main
-  promotion workflow. Run `npx vitops agents` to also write the design-system
+  promotion workflow. Run `vp exec vitops agents` to also write the design-system
   class reference into `AGENTS.md`.
 - **EmDash skills** are installed per project so they match the pinned `emdash`
-  version: `npx skills add emdash-cms/skills --skill '*' -y`,
+  version: `vp dlx skills add emdash-cms/skills --skill '*' -y`,
   then commit `.agents/skills/`, the `.claude/skills/` symlinks and `skills-lock.json`. Update with
-  `npx skills update` after an `emdash` bump.
+  `vp dlx skills update` after an `emdash` bump.
 - **Claude Code on the web**: the SessionStart hook
   (`.claude/hooks/session-start.sh`) installs Node 24 (matching
   `devEngines`), activates the pinned pnpm, and installs dependencies in the
@@ -164,27 +172,30 @@ routes stay unstyled by it.
 Useful commands (via `@getvitops/cli`):
 
 ```bash
-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
+vp exec vitops validate site.json   # check the config against the schema
+vp exec vitops agents               # write the design-system reference into AGENTS.md
+vpr build:css                  # regenerate the CSS manually
 ```
 
 ## Project map
 
-| 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                                     |
+| 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 — prerendered from the `home` page entry                                                      |
+| `src/pages/[...slug].astro`      | Prerendered once per published `pages` entry (`getStaticPaths`)                                    |
+| `src/pages/404.astro`            | Prerendered not-found page, served with a 404 status for any unmatched URL                         |
+| `public/_headers`                | Report-Only CSP for the static pages (see AGENTS.md "Content Security Policy")                     |
+| `scripts/pull-content.mjs`       | Loads production's D1 into the local build DB before the prerender (`deploy`/`deploy:dev`)         |
+| `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 `vpr sop` first (see "One-time setup")                           |
+| `.github/workflows/`             | deploy-dev (push to `dev`), deploy-prod (push to `main`, or an `emdash-publish` dispatch), promote |
+| `.agents/skills/promote/`        | Agent skill: dispatch the dev → main promotion                                                     |
+| `.agents/skills/custom-blocks/`  | Agent skill: when (and how) to add a block type — compose, extend, local, upstream                 |
+| `.mcp.json`                      | Astro + EmDash docs MCP servers for coding agents                                                  |
+| `.claude/hooks/`                 | Claude Code web: Node 24 + pnpm setup on session start                                             |