@getvitops/create 0.9.0-alpha.1 → 0.9.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @getvitops/create
 
+## 0.9.0-alpha.3
+
+### Patch Changes
+
+- 8543f73: `vitops agents` (also `vitops agents sync`) now keeps a short fenced block at the **top** of `AGENTS.md` instead of appending a long one. The block names the config, says to prefer the framework's classes, and links the skills linked under `.agents/skills` from installed `@getvitops/*` packages (with a one-line "use when …" from each), plus `vitops docs <topic>` for reference; the generate-command list and the topic list are gone. A later run replaces only that block in place and leaves the rest of the file alone; with no block, it is added at the top; a block from an older release is updated where it is. The command also links every skill an installed `@getvitops/skills` ships, so it works without the `skills` CLI. The templates run it from `prepare` and ship the block already in `AGENTS.md`.
+
+## 0.9.0-alpha.2
+
+### Minor Changes
+
+- 0a47856: Build correctness and gaps from the second upstream round.
+
+  - **`@getvitops/emdash`: fixes a circular import that emptied the plugin block map in the static build.** `Section.astro` and `WidgetArea.astro` imported `emdash/ui` statically, which imports `virtual:emdash/block-components`, which is `@getvitops/emdash/astro` again. Depending on import order, every `vitops_*` block inside a section body was dropped from prerendered pages with only a `PortableText [components.type] is missing …` warning. Both now import it lazily, and a test fails if any renderer imports `emdash/ui` statically. No code change needed in sites.
+  - **`@getvitops/cli`: `vitops emdash build`** runs `astro build` and then `check-prerender`, and fails when the build reports a block type with no component (reported once per type). The template's `build`, `deploy` and `deploy:dev` scripts use it; existing sites replace `astro build && vitops emdash check-prerender` with `vitops emdash build`. `check-prerender` also warns (fails with `--strict`) on a page without exactly one `<h1>`.
+  - **`@getvitops/emdash`: `vitops_hero` and `vitops_section` heading level** accepts `h1`–`h6` and `p` (a heading that is styled but not in the outline). The hero defaults to `h1`; set the level to `2` on a page whose layout already renders an `h1` (the template's seed does).
+  - **`@getvitops/emdash`: `vitops_logos`** shows an entry's name as text (`.logos__name`) when it has no image. `@getvitops/core` adds the rule (all formats).
+  - **`@getvitops/emdash`: an empty content widget** (no text, no blocks) no longer renders its title, and an area whose widgets are all empty renders nothing.
+  - **`@getvitops/create`:** the template's `pages` collection gets `urlPattern: "/{slug}"` (the sitemap listed `/pages/<slug>`, which 404s; existing sites change it under Content Types), and `.gitignore` ignores only `src/styles/tailwind.css` and `tokens.json`, so site CSS kept in `src/styles/` is committed.
+  - **`@getvitops/emdash`: per-item colour.** The rows of `vitops_cards`, `vitops_stats`, `vitops_steps` and the hero's `cards` take their own `tone` / `color` (blank inherits the block's), so one block can hold a pine item and an amber one. Hero cards also take an `eyebrow` and a button (`ctaLabel` / `ctaHref`; with a button the card is no longer a stretched link).
+  - **`@getvitops/generator` / `@getvitops/emdash`: solid fills read.** The generator emits `--color-<hue>-<step>-on` for every step of every hue, the foreground for a fill at that step picked by the same APCA rule as `text-on-<role>` (css and tailwind formats, a plain `:root`, not `@theme`). A block fill chosen by `color` (hue and step) uses it instead of a fixed white..
+  - **`@getvitops/core`: `.counter__value.sr-only`** hides itself, so a build that never emitted the `.sr-only` utility no longer shows a counting figure twice (all formats).
+  - **`@getvitops/astro` / `@getvitops/core`: `SiteFooter` groups.** A top-level item of the `footer-sitemap` menu with children becomes a column (its label is the heading, its children the links, one level only); childless items stay in the flat list. Each column is a named `<nav>`.
+  - **`@getvitops/astro`: planned links and header buttons.** A menu item with `draft` in its CSS classes stays in the menu but is not rendered (at every level, in the header and the footer). `<SiteNav>` has an `actions` slot for header buttons that are not menu items, and an item with `cta` in its CSS classes renders as a button.
+  - **`@getvitops/cli`: `check-prerender` warnings** (fail with `--strict`): links to pages the build did not produce, a form with no delivery address (no `site.notifications.email`, location `email` or `site.crm`), and form fields missing from every `site.templates` form entry (the generated privacy policy reads those). It reads `./site.json`, or `--site=<path>`. `vitops setup … --dry-run` is accepted as `--dry`.
+  - **`@getvitops/emdash` / `@getvitops/astro`: "tick any number" form field** (`vitops_form` field kind `checkboxes`): a fieldset of checkboxes sharing one name. The conversion route joins repeated values (`IT, Marketing`) instead of keeping the last. The "required" toggle is not applied to the group (HTML cannot require one of several).
+  - **`@getvitops/core`: size hooks.** `.steps__title`, `.stats__figure` and `.card__title` read `--steps-title-size` (default one step below `heading`), `--stats-figure-size` and `--card-title-size`, set on the block through its `style` field. They set the `--heading-fs` / `--display-fs` properties the type-role utilities already read, so no extra class or prop is needed (all formats).
+  - **`@getvitops/create`:** the template's `site.json` lists its contact form under `site.templates`, so the privacy policy inventory and the new check agree.
+  - **`@getvitops/emdash`: `theme` on every block, on widget areas and on your own markup.** A `theme` select (`<role>` tinted, `<role>:solid` filled, populated from the site's roles by a new `themes/list` route) is a common field on every `vitops_*` block, applied to the block's own root with the role's computed readable text. `<VitopsWidgetArea theme="…">` takes the same, and `themeAttrs('surface')` gives `{ class, style }` for a layout `<body>`. `vitops_section`'s existing `theme` now goes through the same path.
+  - **`@getvitops/cli` / `@getvitops/emdash`: pages with a dropped block fail the build.** `vitops_section` and widget areas emit an invisible `<template data-vitops-unrendered="…">` for any body block with no renderer, and `check-prerender` fails the page naming the types (nested bodies only; `vitops emdash build` also scans the build log, which covers top-level bodies). A regression test imports the plugin entry first with a mock of the real virtual module, so the old import cycle fails it.
+  - **`@getvitops/emdash`: `formTemplateFromBlock(block)`** turns a saved `vitops_form` value into a `site.templates` form entry (names as submitted, a `checkboxes` field as a `checkbox` with options), to paste into `site.json` so the generated privacy policy lists what the form collects. The build cannot read the CMS database, so this is run by hand; `check-prerender` warns when fields are missing.
+  - **`@getvitops/utils`: `hasFormDelivery`** (`@getvitops/utils/notify`): the one test for "has this form anywhere to go", used by `check-prerender`.
+  - **`@getvitops/emdash`:** a `color` hue tint now flips with the colour scheme (`light-dark()`); hero option cards sit at `h2` under an `h1` hero; menu items also accept `hidden: true` (same as the `draft` class); `vitops docs blocks` documents `theme`, the per-row colours, the `--<role>-fs` type-size hook and the form checks.
+  - **`@getvitops/create`:** the template redirects `/home` to `/`, and the guides use `vp exec` instead of `vpx`.
+
+### Patch Changes
+
+- 0a47856: **Breaking: every block type is now `vitops_<name>`** (`vitops_cards`, `vitops_hero`, `vitops_actionLink`, …), where the Portable Text blocks were `vitops.<name>` and the section block type was already `vitops_section`. EmDash validates a block type's slug as `[a-z][a-z0-9_]*`, so `vitops.section` was never possible and the toolkit had two styles for one kind of thing. Underscore is the one form valid everywhere, so it is now the only one.
+
+  Migration: in stored content and in `seed/seed.json`, rename `_type` values from `vitops.<name>` to `vitops_<name>`; in `PortableText` `components`, rename the keys the same way; the `blocks: { include, exclude }` option takes full type names, so rename those too. `vt_*` names in a site are that site's own types and are unaffected. A search-and-replace of `vitops.(actionLink|imageCompare|copyButton|banner|details|carousel|gallery|cards|accordion|hero|marquee|logos|steps|stats|callout|entries|pricing|embed|form|reviews|nav|badges|widgetArea)` with `vitops_$1` covers it. `vitops emdash build` reports any block left on the old name as having no component.
+
+- 0a47856: New package `@getvitops/skills`: agent skills for sites built with the toolchain (`custom-blocks`, `content-and-deploys`, `contact-form`, `csp`). The emdash template depends on it and runs `skills experimental_sync` on `prepare`, which links them into `.agents/skills/` and `.claude/skills/`, so they update with `vp update` instead of being copied at scaffold time. Existing sites: `vp add @getvitops/skills && vp add -D skills`, set `prepare` to `vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile`, gitignore the four linked names, and delete the site's own copies of those four skills (the sync never replaces a directory it did not create).
+
+  The emdash template's `AGENTS.md` is shortened to the always-relevant rules. Deploy and content mechanics (where each kind of data is the truth, prerendering, publish-triggered rebuilds, refreshing dev), the contact form, and the CSP move into those skills. Corrects the nesting guidance: a block type with a `portableText` field (such as `vitops_section`) holds other blocks, while `vitops_*` Portable Text blocks do not. Adds guidance for agents to record reusable toolkit gaps in `UPSTREAM.md`. The generated stylesheet is no longer described as always `tailwind.css`.
+
 ## 0.9.0-alpha.1
 
 ### Minor Changes

package/package.json

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

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

@@ -10,7 +10,7 @@
 #
 # 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,
+# and an EmDash `content:afterPublish` hook POSTs that event (.agents/skills/content-and-deploys,
 # "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

package/templates/emdash/AGENTS.md

@@ -1,365 +1,196 @@
+<!-- vitops:start -->
+
+Built with the Vitops design system (`@getvitops/*`); tokens and site facts live in `site.json`.
+Prefer its classes and patterns over hand-written CSS. Load the skill that matches the task:
+
+- [contact-form](.agents/skills/contact-form/SKILL.md) — Use when adding or changing a form, fixing submissions that don't arrive, setting up noti…
+- [content-and-deploys](.agents/skills/content-and-deploys/SKILL.md) — Use for any deploy or build problem, stale or missing content, "my publish isn't live", s…
+- [csp](.agents/skills/csp/SKILL.md) — Use when changing `public/_headers`, adding an embed, tracking snippet or third-party scr…
+- [custom-blocks](.agents/skills/custom-blocks/SKILL.md) — Use before creating, renaming or deleting any block type, any `src/components/blocks/*` r…
+- [vitops-design-system](.agents/skills/vitops-design-system/SKILL.md) — Use when styling or authoring pages or components (choosing utility/pattern classes, colo…
+
+Reference, rendered from this project: `vitops docs <topic>` (no topic lists them).
+<!-- managed by `vitops agents sync` · @getvitops/cli@8.3.0-alpha.2 — edit outside this block -->
+<!-- vitops:end -->
+
 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
 
-- `site.json` is the single source of truth — organization + site facts, and
-  the design system (colors, type, spacing, patterns, animations) under
-  `designSystem.themes.default`. Never edit `src/styles/tailwind.css` — it is
-  generated from `site.json` by the `vitops()` integration on every dev/build
-  and is gitignored. (There is no separate `design-system.json`: a scaffolded
-  config can't merely reference a sibling file, so the token set lives inside
-  `site.json` — see `AGENTS.md`'s "Client onboarding" section in the toolchain
-  repo for why.)
-- `src/assets/placeholder/` holds neutral wireframe stand-ins (square,
-  portrait, landscape; SVG + PNG) for layout work before real imagery
-  exists. Delete the directory once real assets land — it's separate from
-  `src/assets/logo.svg`, the actual brand asset.
-- Content lives in the EmDash database, not in the repo. Query it with
-  `getEmDashCollection` / `getEmDashEntry` from `emdash`; render Portable Text
-  with `<PortableText />` from `emdash/ui` (the Vitops blocks from
-  `@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 (`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`, …). `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:
+- `site.json` is the single source of truth: organization + site facts, and the design system
+  under `designSystem.themes.default`. Never edit the generated stylesheet
+  (`src/styles/tailwind.css` with the default `tailwind` format; `css.format` in
+  `astro.config.mjs` picks it). It is rebuilt from `site.json` on every dev/build and gitignored.
+  Only `src/styles/tailwind.css` and `tokens.json` are ignored: put your own CSS in a separate file
+  (for example `src/site.css`, imported from the layout) and commit it.
+- Content lives in the EmDash database, not the repo. Read it with `getEmDashCollection` /
+  `getEmDashEntry` from `emdash`; render Portable Text with `<PortableText />` from `emdash/ui`
+  (the `vitops_*` blocks from `@getvitops/emdash` are merged in).
+- **Where truth lives:** content (entries, media, menus) is **production's**, edited there; code,
+  `site.json` and schema are **git's** (`dev` → `main`). The dev database is a disposable copy
+  refreshed from prod, never promoted back. See `.agents/skills/content-and-deploys/SKILL.md`.
+- `seed/seed.json` applies only to an empty database. To change a running site's content model, use
+  the admin (`/_emdash/admin`) or its MCP server (`/_emdash/api/mcp`).
+- Hosting comes from `vitopsHosting()` in `astro.config.mjs` — never hard-code an adapter or
+  d1/r2/sqlite. Switch with `vitopsHosting({ target })` or the `HOSTING` env var.
+- Keep the Worker cron trigger in `wrangler.jsonc`: it publishes content scheduled in the admin.
+- `src/assets/placeholder/` is wireframe stand-in imagery; delete it once real assets land.
+- Prefer framework classes (utilities, patterns, type roles like `font-heading`) over bespoke CSS.
+  `vp exec vitops docs classes` prints the full class reference.
+- `SETUP.html` is the onboarding checklist (`.agents/skills/setup/`). Tick a box only for a step you
+  completed, never for a human-only one (the Cloudflare API token, domain cutover, legal documents).
+
+## Building pages
+
+- The editor's insert menu offers the `vitops_*` blocks. `vp exec vitops docs blocks` lists them
+  with every field; `vp exec vitops docs components` lists every pattern, which tiers provide it
+  and which block renders it.
+- **Nesting.** A block type with a `portableText` field, such as `vitops_section`, holds other
+  blocks. A `vitops_*` block holds only scalar fields and repeaters (cards, gallery images,
+  accordion items, slides), so it can't. EmDash's built-in `columns` doesn't render `vitops_*`
+  children. For layout, nest in a section, use a `blocks` field, or hand-write the template with
+  `@getvitops/astro` components (`Subgrid`, `Cards`, `Carousel`, …).
+- **Section, block or widget area?** Copy-and-edit content is an EmDash Section. The same content
+  everywhere (announcement bar, pre-footer call to action, sidebar, footer columns) is a **widget
+  area**: define it under Widgets in the admin and render it with `<VitopsWidgetArea name="…" />`
+  from `@getvitops/emdash/astro` in the layout, or in page content with the `vitops_widgetArea`
+  block. Page-specific content is blocks. An area can't hold another area, and prerendered pages
+  show an edit after the next deploy (like menus).
+- **Escape hatches on every block:** `theme` (a backdrop from the site's colour roles, `surface` or
+  `brand-primary:solid`, with the readable text for it picked by the design system, so contrast is
+  not the editor's judgement), `anchor` (the `id`, for `#links`), `className` (extra classes; under
+  the tailwind format only ones the site already uses) and `style` (CSS custom properties only,
+  e.g. `--p-card: 2rem`; anything else is dropped). The same backdrop is available on a widget area
+  (`<VitopsWidgetArea theme="…">`) and on your own markup (`themeAttrs('surface')` from
+  `@getvitops/emdash/astro`, spread on the layout's `<body>`). How a role looks (flat, raised,
+  glass) is the site's own role styling in `site.json`. Set `--header-offset` to the sticky
+  header's height so anchors clear it.
+- Override a block per site with `<PortableText components={{ type: { 'vitops_cards': MyCards } }} />`;
+  hide one with `vitopsEmdash({ blocks: { exclude: [...] } })`.
+- **One `<h1>` per page.** The template's page routes render the title as an `<h1>`, and a hero's
+  heading level defaults to `h1`, so set a hero's level to `2` on those pages (or let the hero own
+  the `h1`). Use `p` for a display heading that is not part of the outline. `vitops emdash build`
+  warns on any page without exactly one `<h1>`.
+- Labels: `badge` is static (status, count, category); `tag` may be editable or dismissable. Don't
+  invent `chip` or `pill`. The button class is `btn`.
+- **Before adding a block type** or a `src/components/blocks/*` renderer, read
+  `.agents/skills/custom-blocks/SKILL.md`. Types can't be renamed or deleted once pages use them.
+
+## Layout foundations — the answer, not a starting point
+
+| About to write…                                         | Write instead   |
+| ------------------------------------------------------- | --------------- |
+| a `wrap`/`wrapper`/`container`/`inner` class            | **`centered`**  |
+| `max-width` + `margin-inline: auto`                     | **`centered`**  |
+| `padding-block` on a section                            | **`region`**    |
+| margins between headings/paragraphs/lists               | **`rhythm`**    |
+| `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`**   |
+| `repeat(auto-fit, minmax(…))`                           | **`grid-auto`** |
+| `display: flex` + `gap` for a row of controls           | **`cluster`**   |
+
+`centered` is a grid of _named tracks_: a child widens itself with `breakout`/`spotlight`/
+`fullbleed` without the parent knowing, which a bespoke `.wrap` can't do.
+
+- **More than one card means `subgrid`**, so headings and CTAs align across the set:
+  `<ul class="subgrid subgrid-cols-3" role="list">` with `<li class="card subgrid-card">`, or
+  `<Subgrid />` (renders the slot verbatim; author the `<li>`s).
+- **A card that is a link:** `stretched-link` inside it is zero-JS but kills text selection;
+  `<Cards>` keeps selection and falls back to the same link with no JS. Never both. Never
+  `<li><a class="card">`: the `li` is the grid item, so the tranches don't align.
+- `vpr lint:design` reports all of these and the pre-commit hook fails on them. Fix the class, not
+  the CSS.
+
+## Rendering and the contact form
+
+- Every public page is **prerendered**; the Worker handles `/_emdash/*` and `src/pages/api/track.ts`.
+  An admin publish goes live after a rebuild. Run `vpr prepare-local-db` before a first local
+  `vpr build`. Details, previews and server islands: `.agents/skills/content-and-deploys/SKILL.md`.
+- The contact form posts to `/api/track`. Set `site.notifications.email` before launch or the route
+  refuses posts, and mirror form fields in `site.templates`. Details:
+  `.agents/skills/contact-form/SKILL.md`.
+- `public/_headers` ships a Report-Only CSP. Read `.agents/skills/csp/SKILL.md` before enforcing it
+  or adding embeds.
+- `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
-  the seed does not migrate an existing site — use the admin
-  (`/_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 `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:
-
-  | About to write…                                         | Write instead   |
-  | ------------------------------------------------------- | --------------- |
-  | a `wrap`/`wrapper`/`container`/`inner` class            | **`centered`**  |
-  | `max-width` + `margin-inline: auto`                     | **`centered`**  |
-  | `padding-block` on a section                            | **`region`**    |
-  | margins between headings/paragraphs/lists               | **`rhythm`**    |
-  | `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`**   |
-  | `repeat(auto-fit, minmax(…))`                           | **`grid-auto`** |
-  | `display: flex` + `gap` for a row of controls           | **`cluster`**   |
-
-  `centered` is a grid of _named tracks_, not a max-width box — a child widens
-  itself with `breakout`/`spotlight`/`fullbleed` without the parent knowing, which
-  is the thing a bespoke `.wrap` can never do. **More than one card means
-  `subgrid`**: a plain grid aligns the outer boxes but not the tranches inside
-  them, so headings and CTAs land at different heights across the set. Write
-  `<ul class="subgrid subgrid-cols-3" role="list">` with
-  `<li class="card subgrid-card">` items, or `<Subgrid />` (which renders the slot
-  verbatim — author the `<li>`s yourself; it adds `role="list"` for you, and a
-  hand-written one needs it because a marker-less `<ul>` stops being announced as a
-  list in Safari).
-
-  **When the whole card is a link the card is still the item**, and pick by whether
-  the card's text must stay selectable: `stretched-link` on a link inside it is
-  zero-JS but kills text selection, while `<Cards>` (which wraps the list in
-  `<wc-cards>`) keeps selection and falls back to that same link with no JS. Never
-  both — the overlay wins and the JS never runs. Never `<li><a class="card">`: the
-  `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.
-
-  `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.
-
-- **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()`
-  (`@getvitops/emdash`) in astro.config.mjs — never hard-code an adapter or
-  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
 
-- Work on **`dev`** (the integration branch). Every push auto-deploys the
-  isolated `-dev` worker (own D1/R2; `dev.<domain>` with a custom domain).
-- **`main`** is production and branch-protected — never push or merge to it
-  directly. Production ships only via the manual **promote** flow: the
-  `promote` skill (`.agents/skills/promote/SKILL.md`) dispatches
-  `.github/workflows/promote.yml`, which opens a `dev → main` PR with
-  auto-merge; merging deploys prod. Only run it when the user explicitly asks
-  to promote/ship to production.
-- Sample legal pages (`/terms`, `/privacy`) ship as seeded placeholder content
-  — remind the user to replace them before launch. They are deliberately short
-  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, fill in `site.json`'s `organization`/`site.legal`
-  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.
-  It still needs review before launch.
-
-## EmDash 1.x behaviours worth knowing
-
-- **Passkeys are bound to the hostname they were created on.** After the
-  workers.dev → custom-domain cutover, use **Settings → General → Change
-  domain**, then **Continue on** to add a passkey at the new address.
-- **HTML blocks created in the admin run JavaScript** in a sandboxed iframe
-  (Contributor and up can add it). Astro's `security.csp` blocks their styles
-  and scripts, so don't turn CSP on without allowing for that.
-- **Link entries by `entry.data.slug`, never `entry.id`** — on multilingual
-  sites `id` carries a locale prefix.
-- **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
-  `vp exec emdash migrate --take-over-lock <id>` (confirms the target, or
-  needs `--expected-target-fingerprint` non-interactively).
-
-## Docs MCP servers
-
-`.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`,
-`upgrading-emdash` and the two WordPress porting skills) are installed per
-project, not globally, so they match the `emdash` version this repo pins. If
-`.agents/skills/building-emdash-site/` is missing, install them (the setup guide
-and `SETUP.html` have the full step):
-
-```bash
-vp dlx skills add emdash-cms/skills --skill '*' -y
-```
-
-Refresh them with `vp dlx skills update` after bumping `emdash` — the
-`upgrading-emdash` skill covers the rest of the upgrade.
+- Work on **`dev`**; every push auto-deploys the isolated `-dev` worker.
+- **`main`** is production and protected: never push or merge to it. It ships only through the
+  `promote` skill (`.agents/skills/promote/`), and only when the user explicitly asks.
+- Sample legal pages (`/terms`, `/privacy`) are deliberately short, unfinished placeholders; don't
+  "improve" them into something that reads as a finished policy. To replace them, fill in
+  `site.json`'s `organization`/`site.legal`, run
+  `vp exec vitops legal --format portable-text --out ./legal`, and paste each document into the page
+  in the admin. It still needs review before launch.
+
+## EmDash 1.x behaviours
+
+- Passkeys are bound to the hostname they were created on. After a domain cutover use **Settings →
+  General → Change domain**, then **Continue on**.
+- Link entries by `entry.data.slug`, never `entry.id` (multilingual sites prefix `id` with a locale).
+- Submit `/sitemap.xml` to search engines, not a per-collection sitemap.
+- Clear a stuck D1 migration lock with `vp exec emdash migrate --take-over-lock <id>` (needs
+  `--expected-target-fingerprint` non-interactively).
+
+## Improving the toolkit
+
+You are also a source of feedback for `@getvitops/*`. When you struggle with a framework built-in,
+write a workaround, add bespoke CSS or a site-local block, or find a doc wrong or missing, and the
+need is **not** unique to this site, record it in `UPSTREAM.md` at the repo root (create it if
+absent). One entry each, with: what you tried, what failed or was missing, the workaround (file
+path), the change you'd propose, and the package (`@getvitops/emdash`, `astro`, `core`, `cli`,
+`create`, or docs). Mention new entries in your end-of-task summary. Don't log choices that are
+specific to this site, and never patch `node_modules`.
+
+## Docs and skills
+
+- `.mcp.json` preconfigures the Astro and EmDash docs MCP servers; search them before relying on
+  pre-trained knowledge.
+- **Skills.** `@getvitops/skills` ships `custom-blocks`, `content-and-deploys`, `contact-form` and
+  `csp`. `skills experimental_sync` (run by `prepare`, so by `vp install`) links them into
+  `.agents/skills/` and `.claude/skills/`; they are gitignored and update with `vp update`. A skill
+  you write yourself with the same name is never replaced. `promote` and `setup` are this site's own.
+- The EmDash skills (`building-emdash-site`, `creating-plugins`, `emdash-cli`, `upgrading-emdash`,
+  two WordPress porting skills) are installed per project to match the pinned `emdash`. If
+  `.agents/skills/building-emdash-site/` is missing: `vp dlx skills add emdash-cms/skills --skill '*' -y`.
+  Refresh with `vp dlx skills update` after bumping `emdash`.
 
 ## Commands
 
-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.
+This is a **Vite+** project: use `vp` (and `vpr`), not `pnpm`/`npm`/`npx`. Scripts that wrap Astro
+go through `vpr` (`vpr dev`, `vpr build`, `vpr preview`), because `vp dev`/`vp build` skip Astro.
+`vpr dev` returns immediately (the server runs in the background): check it with
+`vp exec astro dev status`, read `vp exec astro dev logs --follow`, stop with
+`vp exec astro dev stop`; the site is at <http://localhost:4321>.
 
 | 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 `package.json` script              | `vpr <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.
+| design-lint the markup                   | `vpr lint:design`                                       |
 
 | 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 pull-content`                  | just the content pull                                                                       |
 | `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`.
+Shipping is not a package release: no changeset or version bump. Commit to `dev`, then promote.
+(`vp` has no `vp change` command.)
 
-**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.
+`vp create` names the package after the target directory (pass `--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

@@ -51,7 +51,7 @@ 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
+per request — see `.agents/skills/content-and-deploys` 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.
 
@@ -147,8 +147,8 @@ 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 `vp exec vitops agents` to also write the design-system
-  class reference into `AGENTS.md`.
+  promotion workflow. The short block at the top of `AGENTS.md` (fenced by
+  `<!-- vitops:start -->`) lists the toolkit skills; `vp install` refreshes it (`vitops agents sync`).
 - **EmDash skills** are installed per project so they match the pinned `emdash`
   version: `vp dlx skills add emdash-cms/skills --skill '*' -y`,
   then commit `.agents/skills/`, the `.claude/skills/` symlinks and `skills-lock.json`. Update with
@@ -173,7 +173,7 @@ Useful commands (via `@getvitops/cli`):
 
 ```bash
 vp exec vitops validate site.json   # check the config against the schema
-vp exec vitops agents               # write the design-system reference into AGENTS.md
+vp exec vitops agents sync          # refresh the managed block at the top of AGENTS.md and link the skills
 vpr build:css                  # regenerate the CSS manually
 ```
 
@@ -189,7 +189,7 @@ vpr build:css                  # regenerate the CSS manually
 | `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")                     |
+| `public/_headers`                | Report-Only CSP for the static pages (see `.agents/skills/csp`)                                    |
 | `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                                     |

package/templates/emdash/_gitignore

@@ -18,8 +18,9 @@ worker-configuration.d.ts
 # node hosting target: SQLite db + local uploads
 data/
 
-# generated by the vitops() integration on dev/build
-src/styles/
+# generated by the vitops() integration on dev/build (site CSS goes in src/site.css, not here)
+src/styles/tailwind.css
+src/styles/tokens.json
 public/vitops/
 
 # generated by `pnpm run sop` — styles SETUP.html for a file:// open
@@ -32,3 +33,13 @@ public/vitops/
 
 # os / editor
 .DS_Store
+
+# agent skills linked from @getvitops/skills by `skills experimental_sync` (see skills-lock.json)
+.agents/skills/custom-blocks
+.agents/skills/content-and-deploys
+.agents/skills/contact-form
+.agents/skills/csp
+.claude/skills/custom-blocks
+.claude/skills/content-and-deploys
+.claude/skills/contact-form
+.claude/skills/csp

package/templates/emdash/astro.config.mjs

@@ -35,6 +35,8 @@ const brandColor = colors.palette?.[roleHue('brand-primary')]?.seed ?? '#2e9b73'
 export default defineConfig({
   output: 'server',
   adapter,
+  // The seed's `pages` collection serves entries at `/{slug}` (urlPattern), and `home` lives at `/`.
+  redirects: { '/home': '/' },
   image: {
     layout: 'constrained',
     responsiveStyles: true,

package/templates/emdash/node_modules/.vitest-cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by Vitest.
+# For information about cache directory tags see https://bford.info/cachedir/

package/templates/emdash/node_modules/.vitest-cache/_metadata.json

@@ -0,0 +1,3 @@
+{
+  "lockfileHash": "4b2ac6bd"
+}

package/templates/emdash/package.json

@@ -5,12 +5,12 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev",
-    "build": "astro build && vitops emdash check-prerender",
+    "build": "vitops emdash build",
     "preview": "astro preview",
     "pull-content": "node scripts/pull-content.mjs",
     "prepare-local-db": "vitops emdash prepare-db",
-    "deploy": "vitops email check && node scripts/pull-content.mjs && vitops emdash prepare-db && astro build && vitops emdash check-prerender && emdash migrate --wrangler-config wrangler.jsonc && wrangler deploy",
-    "deploy:dev": "vitops email check && node scripts/pull-content.mjs && vitops emdash prepare-db && astro build && vitops emdash check-prerender && node scripts/build-dev-wrangler.mjs && emdash migrate --wrangler-config dist/server/wrangler.dev.json && wrangler deploy --config dist/server/wrangler.dev.json",
+    "deploy": "vitops email check && node scripts/pull-content.mjs && vitops emdash prepare-db && vitops emdash build && emdash migrate --wrangler-config wrangler.jsonc && wrangler deploy",
+    "deploy:dev": "vitops email check && node scripts/pull-content.mjs && vitops emdash prepare-db && vitops emdash build && node scripts/build-dev-wrangler.mjs && emdash migrate --wrangler-config dist/server/wrangler.dev.json && wrangler deploy --config dist/server/wrangler.dev.json",
     "init:github": "vitops setup repo",
     "init:hosting": "vitops setup hosting",
     "setup": "vitops setup all",
@@ -18,7 +18,7 @@
     "build:css": "vitops generate -i site.json -f tailwind -o src/styles",
     "lint:design": "vitops lint -i site.json -f tailwind --strict",
     "sop": "vitops generate -i site.json -f css -o .vitops/sop",
-    "prepare": "vp config"
+    "prepare": "vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile && vitops agents sync -i site.json"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.0.0",
@@ -27,6 +27,7 @@
     "@getvitops/astro": "latest",
     "@getvitops/core": "latest",
     "@getvitops/emdash": "latest",
+    "@getvitops/skills": "latest",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "^7.4.4",
     "emdash": "latest",
@@ -39,6 +40,7 @@
     "@cloudflare/workers-types": "^4.20260305.1",
     "@getvitops/cli": "latest",
     "@iconify-json/fa7-solid": "^1.2.5",
+    "skills": "^1.7.6",
     "typescript": "^6.0.3",
     "vite": "latest",
     "vite-plus": "latest",

package/templates/emdash/public/_headers

@@ -1,7 +1,7 @@
 # Cloudflare static-assets response headers. They apply to files served from the
 # static asset store — the prerendered pages — and NOT to responses the Worker
 # renders itself (the EmDash admin at /_emdash/*, its API, anything left
-# on-demand). See AGENTS.md "Content Security Policy".
+# on-demand). See .agents/skills/csp.
 #
 # REPORT-ONLY on purpose: violations are logged to the browser console and
 # nothing is blocked, so this cannot break a page. Read the console on the

package/templates/emdash/scripts/pull-content.mjs

@@ -6,7 +6,7 @@
 // `astro build`. The Cloudflare adapter prerenders inside a local workerd with a
 // LOCAL D1 (`.wrangler/state`), never the deployed database — so on a CI runner
 // the build would see an empty, auto-seeded database and bake "No home page yet"
-// into every page. Production is the truth for content (see AGENTS.md), so this
+// into every page. Production is the truth for content (see .agents/skills/content-and-deploys), so this
 // copies production's D1 into the local one first.
 //
 //   wrangler d1 export <db> --remote   →   .vitops/content.sql

package/templates/emdash/seed/seed.json

@@ -15,6 +15,7 @@
       "slug": "pages",
       "label": "Pages",
       "labelSingular": "Page",
+      "urlPattern": "/{slug}",
       "supports": ["drafts", "revisions", "seo"],
       "fields": [
         {
@@ -112,7 +113,7 @@
               ]
             },
             {
-              "_type": "vitops.actionLink",
+              "_type": "vitops_actionLink",
               "_key": "pf-cta",
               "label": "Contact us",
               "href": "/contact",
@@ -161,10 +162,11 @@
               ]
             },
             {
-              "_type": "vitops.hero",
+              "_type": "vitops_hero",
               "_key": "demo-hero",
               "eyebrow": "Vitops blocks",
               "heading": "Build pages from design-system patterns",
+              "level": "2",
               "body": "Every block below renders a framework pattern, so it follows your tokens and works without JavaScript.",
               "primaryLabel": "Open the admin",
               "primaryHref": "/_emdash/admin",
@@ -173,7 +175,7 @@
               "layout": "centered"
             },
             {
-              "_type": "vitops.cards",
+              "_type": "vitops_cards",
               "_key": "demo-cards",
               "columns": "3",
               "cards": [
@@ -197,7 +199,7 @@
               ]
             },
             {
-              "_type": "vitops.accordion",
+              "_type": "vitops_accordion",
               "_key": "demo-accordion",
               "exclusive": true,
               "items": [
@@ -215,7 +217,7 @@
               ]
             },
             {
-              "_type": "vitops.marquee",
+              "_type": "vitops_marquee",
               "_key": "demo-marquee",
               "pauseOnHover": true,
               "reverse": false,
@@ -239,14 +241,14 @@
               ]
             },
             {
-              "_type": "vitops.banner",
+              "_type": "vitops_banner",
               "_key": "welcome-banner",
               "message": "This banner is a Vitops block — dismiss it, then edit this page in the EmDash admin.",
               "tone": "info",
               "dismissible": true
             },
             {
-              "_type": "vitops.details",
+              "_type": "vitops_details",
               "_key": "next-steps",
               "summary": "Next steps",
               "body": "Adjust site.json (under designSystem.themes.default) to your brand (colors, type, patterns), replace src/assets/logo.svg, then deploy with `pnpm deploy`.",
@@ -287,7 +289,7 @@
           "title": "Terms & Conditions",
           "content": [
             {
-              "_type": "vitops.banner",
+              "_type": "vitops_banner",
               "_key": "terms-placeholder",
               "message": "Placeholder text — replace with your own terms before launch. This is not legal advice.",
               "tone": "warning",
@@ -388,7 +390,7 @@
           "title": "Privacy Policy",
           "content": [
             {
-              "_type": "vitops.banner",
+              "_type": "vitops_banner",
               "_key": "privacy-placeholder",
               "message": "Placeholder text — replace with your own privacy policy before launch. This is not legal advice.",
               "tone": "warning",
@@ -503,7 +505,7 @@
           "title": "Contact",
           "content": [
             {
-              "_type": "vitops.banner",
+              "_type": "vitops_banner",
               "_key": "contact-placeholder",
               "message": "Placeholder text — replace with your contact details before launch.",
               "tone": "warning",
@@ -524,7 +526,7 @@
               ]
             },
             {
-              "_type": "vitops.form",
+              "_type": "vitops_form",
               "_key": "contact-form",
               "heading": "Send us a message",
               "level": "2",
@@ -568,7 +570,7 @@
           "title": "Cookie Notice",
           "content": [
             {
-              "_type": "vitops.banner",
+              "_type": "vitops_banner",
               "_key": "cookies-placeholder",
               "message": "Placeholder text — replace with your own cookie notice before launch. This is not legal advice. `vitops legal` can generate a draft from site.json.",
               "tone": "warning",

package/templates/emdash/site.json

@@ -309,6 +309,17 @@
   },
   "site": {
     "defaultLocale": "en",
+    "templates": {
+      "contact": {
+        "type": "form",
+        "fields": [
+          { "name": "name", "type": "text", "required": true },
+          { "name": "email", "type": "email", "required": true },
+          { "name": "tel", "type": "tel" },
+          { "name": "message", "type": "textarea", "required": true }
+        ]
+      }
+    },
     "locales": {
       "en": {
         "name": "English"

package/templates/emdash/src/pages/[...slug].astro

@@ -8,7 +8,7 @@ import Layout from '../layouts/Layout.astro';
 // the content database — `scripts/pull-content.mjs` loads production's into the
 // local build database first (it is part of `deploy`/`deploy:dev`) — so an edit
 // in the admin goes live on the next rebuild, which a publish webhook triggers
-// (see AGENTS.md "Rendering and freshness").
+// (see .agents/skills/content-and-deploys).
 //
 // There is no `Astro.rewrite('/404')` here and no on-demand fallback: a URL that
 // isn't in the list below simply has no route, so Astro serves the prerendered

package/templates/emdash/src/pages/api/track.ts

@@ -1,8 +1,8 @@
 /**
- * The site's one on-demand endpoint: contact-form posts (the `vitops.form` block) and the
+ * The site's one on-demand endpoint: contact-form posts (the `vitops_form` block) and the
  * conversion beacons (`<Tracking />`, `tel:`/`mailto:` clicks) all arrive here.
  *
- * Every public page is prerendered (see AGENTS.md, "Rendering and freshness"); this route sets
+ * Every public page is prerendered (see .agents/skills/content-and-deploys); this route sets
  * `prerender = false` because it has to run on each request. It is the one exception, and the
  * Cloudflare adapter handles it in the Worker beside the EmDash admin.
  *

package/templates/emdash/src/pages/index.astro

@@ -5,8 +5,8 @@ import Layout from '../layouts/Layout.astro';
 
 // Prerendered, like every page in this template: written to static HTML at build
 // time from the `home` entry (seed/seed.json → pages/home). Edit it in the admin;
-// a publish triggers a rebuild that bakes the change in (AGENTS.md "Rendering and
-// freshness"). The Vitops blocks from @getvitops/emdash render automatically —
+// a publish triggers a rebuild that bakes the change in (.agents/skills/content-and-deploys,
+// "Rendering and freshness"). The Vitops blocks from @getvitops/emdash render automatically —
 // EmDash merges the plugin's block components into <PortableText>.
 //
 // Anything on a page that must be fresh per request (a stock count, a signed-in

package/templates/static/AGENTS.md

@@ -1,3 +1,18 @@
+<!-- vitops:start -->
+
+Built with the Vitops design system (`@getvitops/*`); tokens and site facts live in `site.json`.
+Prefer its classes and patterns over hand-written CSS. Load the skill that matches the task:
+
+- [contact-form](.agents/skills/contact-form/SKILL.md) — Use when adding or changing a form, fixing submissions that don't arrive, setting up noti…
+- [content-and-deploys](.agents/skills/content-and-deploys/SKILL.md) — Use for any deploy or build problem, stale or missing content, "my publish isn't live", s…
+- [csp](.agents/skills/csp/SKILL.md) — Use when changing `public/_headers`, adding an embed, tracking snippet or third-party scr…
+- [custom-blocks](.agents/skills/custom-blocks/SKILL.md) — Use before creating, renaming or deleting any block type, any `src/components/blocks/*` r…
+- [vitops-design-system](.agents/skills/vitops-design-system/SKILL.md) — Use when styling or authoring pages or components (choosing utility/pattern classes, colo…
+
+Reference, rendered from this project: `vitops docs <topic>` (no topic lists them).
+<!-- managed by `vitops agents sync` · @getvitops/cli@8.3.0-alpha.2 — edit outside this block -->
+<!-- vitops:end -->
+
 This is a static Astro website styled by the Vitops design system, deployed
 as Cloudflare Workers static assets (no server runtime, no database).
 
@@ -14,8 +29,8 @@ as Cloudflare Workers static assets (no server runtime, no database).
   portrait, landscape; SVG + PNG) for layout work before real imagery
   exists. Delete the directory once real assets land.
 - Prefer framework CSS classes (utilities, patterns, type roles like
-  `font-heading`) over bespoke CSS. Run `vp exec vitops agents` to append the
-  full generated class-vocabulary reference to this file.
+  `font-heading`) over bespoke CSS. `vp exec vitops docs classes` prints the
+  full class vocabulary.
 - **Layout foundations — these are the answer, not a starting point.** Six
   substitutions carry the structure of nearly every page:
   | About to write…                                         | Write instead   |
@@ -70,6 +85,13 @@ activates to `script-src` / `connect-src`, any embed to `frame-src`, and hash an
 inline script you add yourself. Hashes rather than nonces because a static page has no
 per-request response to carry one.
 
+## Skills
+
+`@getvitops/skills` ships agent skills that update with the package. `skills experimental_sync` (run
+by `prepare`, so by `vp install`) links them into `.agents/skills/` and `.claude/skills/`; they are
+gitignored. The set is written for EmDash sites, so `csp` is the one that applies here. A skill you
+write yourself with the same name is never replaced. `setup` is this site's own.
+
 ## Commands
 
 This is a **Vite+** project: use `vp` (and its `vpr` shorthand), not `pnpm`/`npm`/`npx`.

package/templates/static/_gitignore

@@ -25,3 +25,13 @@ public/vitops/
 
 # os / editor
 .DS_Store
+
+# agent skills linked from @getvitops/skills by `skills experimental_sync` (see skills-lock.json)
+.agents/skills/custom-blocks
+.agents/skills/content-and-deploys
+.agents/skills/contact-form
+.agents/skills/csp
+.claude/skills/custom-blocks
+.claude/skills/content-and-deploys
+.claude/skills/contact-form
+.claude/skills/csp

package/templates/static/package.json

@@ -16,15 +16,17 @@
     "build:css": "vitops generate -i site.json -f css -o src/styles",
     "lint:design": "vitops lint -i site.json -f css --strict",
     "sop": "vitops generate -i site.json -f css -o .vitops/sop",
-    "prepare": "vp config"
+    "prepare": "vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile && vitops agents sync -i site.json"
   },
   "dependencies": {
     "@getvitops/astro": "latest",
+    "@getvitops/skills": "latest",
     "astro": "^7.4.4"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.12",
     "@getvitops/cli": "latest",
+    "skills": "^1.7.6",
     "typescript": "^6.0.3",
     "vite": "latest",
     "vite-plus": "latest",

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

@@ -1,104 +0,0 @@
----
-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.