@getvitops/create 0.9.0-alpha.4 → 0.9.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @getvitops/create
 
+## 0.9.0-alpha.5
+
+### Minor Changes
+
+- 6b5ea17: **Leaner scaffolded `AGENTS.md`, and skills named by scope.** The EmDash template's `AGENTS.md` went from 212 to about 70 lines and the static one from 141 to about 50: only always-true rules stay (source of truth, generated CSS, branches, `vp`/`vpr`, where to look), and task-specific guidance moved into skills loaded when the task matches.
+
+  - **Breaking, `@getvitops/skills`: skills are renamed by scope.** `custom-blocks` → `emdash-custom-blocks`, `content-and-deploys` → `emdash-content-and-deploys`, `contact-form` → `emdash-contact-form`, `csp` → `vitops-csp`, `see-the-page` → `vitops-see-the-page`, `ads` → `vitops-ads`. `emdash-*` skills only apply to an EmDash site; `vitops-*` apply anywhere, and both prefixes are reserved for toolkit skills. New: `emdash-building-pages` (blocks, nesting, page opener, widget areas, escape hatches, layout primitives, `site.chrome`) and `vitops-consent` (split out of `vitops-design-system`, whose description and body now cover styling and tokens only). Existing sites: run `vp install` so `skills experimental_sync` relinks, and replace the per-skill `.agents/skills/<name>` / `.claude/skills/<name>` lines in `.gitignore` with `.agents/skills/vitops-*`, `.agents/skills/emdash-*` and the same two under `.claude/skills/`. A site's own skill must not use those prefixes.
+  - **`vitops agents sync`:** the block lists only skills that apply (a project without `emdash` in its dependencies gets no `emdash-*` ones, and they are not linked), summaries are cut at a clause rather than with an ellipsis, the pointer says `vp exec vitops docs`, and the version stamp is gone so the file no longer changes on every CLI bump.
+  - **`@getvitops/create`:** both templates ship the trimmed `AGENTS.md`; the project-naming steps moved into the `setup` skill and EmDash 1.x behaviours, legal-page replacement and the audit prerequisites into `emdash-content-and-deploys`. Existing sites: nothing to change beyond the skill rename; delete the sections you no longer need.
+
+- 7069f93: **Agents now look at rendered pages with `playwright-cli`.** Both templates add `playwright` as a devDependency, run `playwright cli install --skills` from `prepare` (writing the upstream command reference to `.claude/skills/playwright-cli/`), ship `.playwright/cli.config.json`, allow `pnpm exec playwright cli`, and deny `mcp__claude-in-chrome__*` and `mcp__playwright__*` in `.claude/settings.json`. `@getvitops/skills` adds a short `see-the-page` skill (serve first, snapshot before screenshot, dark mode, mobile, no-JS) that defers to the upstream one. Existing sites: add `playwright` as a devDependency, extend `prepare`, and copy the settings. `vitops audit` now needs only `@axe-core/playwright lighthouse` added.
+- 4d94c8b: **Added: `site.chrome` — a configurable masthead and nav behaviour.** Non-breaking.
+
+  - `site.chrome.masthead` (new `@getvitops/config` schema): `position` (`static|sticky|fixed`), `behavior` (`always|hide-on-scroll`), `surface` (`solid|glass|transparent|transparent-until-scrolled`), `tone` (a `colors.roles` key), `layout` (`full|inset|floating`), `width`, `elevation` (`shadow`, `border`, `onScroll`), `height` and `inset`. `height` and `inset` take fluid lengths (`calc()`, `clamp()`, `min()`, `max()`, with `cqi`/`vw`/… units), checked against a closed grammar because they are written into CSS. `validateConfig` rejects a `tone` or `shadow` the design system does not define (only when the default theme states them directly, not via `extends`).
+  - `site.chrome.nav`: `compact` (`drawer|dropdown`), `drawerSide`, `breakpoint`/`mobileBreakpoint`/`megaBreakpoint`, `depth`, `megaDepth`.
+  - `<Masthead config={site}>` (`@getvitops/astro`, slots `brand`/default/`actions`) and `resolveMasthead()` / `resolveNavOptions()`. A prop overrides one field per layout. The key is `chrome`/`masthead` on purpose: `<header>` is valid in any section and `banner` already means the announcement bar and the landmark role.
+  - `<SiteNav>` gains `compact="dropdown"` (a columnar panel anchored under the toggle), `drawerSide` (previously hardcoded to the end edge in Astro), `megaDepth` and `megaPanel`. `.sitenav--mega` now styles second-level items as column headings and has an optional featured column.
+  - `@getvitops/emdash`: `VitopsMegaPanel` fills that column from the widget area `mega-<item url slug>` (or a `mega-area:<name>` class on the menu item). No area means no column.
+  - `@getvitops/create` (emdash template): the layout renders through `<Masthead>`; `site.json` ships a sticky glass masthead with a shadow once scrolled. The hand-written `.navbar { block-size: 64px }` is gone (use `masthead.height`).
+  - CSS (`patterns/masthead.css`, `patterns/sitenav.css`): **all formats**, including tailwind, where the patterns are inlined into `@layer components`. Hide-on-scroll and the `*-on-scroll` states are `scroll-state()` container queries that only subtract from a settled (solid, elevated, visible) bar, so a browser without them (Firefox today) shows that bar rather than a transparent one. A sticky or fixed masthead sets `--header-offset` / `--top-offset` so anchors land below it.
+  - `@getvitops/generator`: new `TIERS.masthead`; `TIERS.sitenav` documents the new props.
+
+### Patch Changes
+
+- bb61a35: **Call tracking numbers: show an ad visitor a number that attributes the phone call.** Two additive config blocks, no CSS, no breaking change — all formats unaffected.
+
+  - **`site.ads.google.callTracking`** — Google Ads _website call conversions_. `{ label, number, cache? }` makes the consent-gated Google tag fetch a Google forwarding number (Canada supported) and swap it in for visitors who arrived from a Google ad. Google replaces text only, so the capture script also rewrites the matching `tel:` href. Needs `pixelId` and `site.tracking.enabled`; rejected on any other platform (only Google can put a number on the website — Microsoft's exist only inside the ad, in the US/UK/AU).
+  - **`site.tracking.phoneNumbers`** — per-platform numbers for every other platform: the real `number`, `sources` keyed by `site.ads` platform (plus `default-paid`), and an informational `provider`. You provision the numbers with a call-tracking service (Twilio, CallRail, …). The landing URL decides first, then the `_ac` cookie, so a visitor who declines `marketing` sees a tracking number on the landing page only. An organic visitor is never swapped, and the server-rendered HTML always carries the real number.
+  - The `tel:` tap beacon now carries which number was shown (`phoneSource`), and the conversion notification says so.
+  - `vitops ads lint` flags a call-tracking provider that is not in `site.legal.privacyPolicy.processors`, and notes that `callTracking` plus `conversionLabel.call` can count one call twice (make one secondary in Google Ads).
+  - `@getvitops/utils/tracking` exports the pure `selectPhoneNumber()` and helpers; the capture script mirrors it and `tracking.test.ts` pins the two.
+  - `@getvitops/skills` gains a **`vitops-ads`** skill (overview plus a `call-tracking.md` topic). The templates gitignore synced skills by prefix (`vitops-*`, `emdash-*`), so it needs no `.gitignore` line of its own.
+
+  `@getvitops/core`, `@getvitops/vite` and `@getvitops/emdash` — no consumer-facing change in these packages.
+
+- 74a87ed: **Scaffolded sites no longer exempt third-party tooling from the 3-day release cooldown.** The templates floated `vite-plus` and `emdash` on `latest` and exempted them (plus `@voidzero-dev/*`, `oxlint`, `oxfmt`) from `minimumReleaseAge`. An exempt package's exact-pinned dependencies are not exempt, so `vp create` then failed with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` whenever vite-plus had just pinned a fresh `@oxc-project/*`. Now only `@getvitops/*` is exempt; `vite-plus` and `vite` (the `vite-plus-core` alias) are `^1.5.1` (the security fix for 1.5.0) and `emdash` and `@emdash-cms/cloudflare` are `^1.4.0`, all ranges, so pnpm resolves the newest version that has cleared the cooldown. Existing sites: in `pnpm-workspace.yaml` reduce `minimumReleaseAgeExclude` to `'@getvitops/*'` and change the `catalog` entries to `^1.5.1`; in `package.json` change those four dependencies from `latest` to those ranges (`vite` as `npm:@voidzero-dev/vite-plus-core@^1.5.1`).
+
 ## 0.9.0-alpha.4
 
 ### Minor Changes

package/package.json

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

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

@@ -59,3 +59,10 @@ report that verbatim rather than guessing at a fix. A step reported as
 "blocked" is not a failure to retry; it is waiting on one of the hard stops
 above, or on a `site.json` field the user still needs to fill in (stage 5,
 Configuration).
+
+## 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:<template> --directory <client-slug>`. `wrangler.jsonc`'s
+`name` (and on EmDash the D1 `database_name` and R2 `bucket_name`) are separate and still say what
+the template shipped; rename them to match before the first deploy.

package/templates/emdash/.claude/settings.json

@@ -1,6 +1,12 @@
 {
   "permissions": {
-    "allow": ["mcp__astro-docs__search_astro_docs", "mcp__emdash-docs__search_docs"]
+    "allow": [
+      "mcp__astro-docs__search_astro_docs",
+      "mcp__emdash-docs__search_docs",
+      "Bash(pnpm exec playwright cli:*)",
+      "Bash(npx --no-install playwright cli:*)"
+    ],
+    "deny": ["mcp__claude-in-chrome__*", "mcp__playwright__*"]
   },
   "hooks": {
     "SessionStart": [

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/skills/content-and-deploys,
+# and an EmDash `content:afterPublish` hook POSTs that event (.agents/skills/emdash-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/.playwright/cli.config.json

@@ -0,0 +1,7 @@
+{
+  "browser": {
+    "browserName": "chromium",
+    "launchOptions": { "headless": true }
+  },
+  "outputDir": ".playwright-cli"
+}

package/templates/emdash/AGENTS.md

@@ -3,198 +3,72 @@
 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 -->
+- [emdash-building-pages](.agents/skills/emdash-building-pages/SKILL.md) — Use when authoring or changing a page's layout or content on this EmDash site — composing `vitops_*` blocks
+- [emdash-contact-form](.agents/skills/emdash-contact-form/SKILL.md) — Use when adding or changing a form, fixing submissions that don't arrive, setting up notifications, CRM or Turnstile
+- [emdash-content-and-deploys](.agents/skills/emdash-content-and-deploys/SKILL.md) — Use for any deploy or build problem, stale or missing content, "my publish isn't live", scheduled posts, previews
+- [emdash-custom-blocks](.agents/skills/emdash-custom-blocks/SKILL.md) — Use before creating, renaming or deleting any block type, any `src/components/blocks/*` renderer
+- [vitops-ads](.agents/skills/vitops-ads/SKILL.md) — Use when adding or changing a Google/Meta/LinkedIn/TikTok/Microsoft/Reddit/Pinterest/Snapchat pixel
+- [vitops-consent](.agents/skills/vitops-consent/SKILL.md) — Use before gating, adding or changing any non-essential third-party tag, cookie, embed
+- [vitops-csp](.agents/skills/vitops-csp/SKILL.md) — Use when changing `public/_headers`, adding an embed, tracking snippet or third-party script, turning the CSP on
+- [vitops-design-system](.agents/skills/vitops-design-system/SKILL.md) — Use when styling or authoring pages or components (choosing utility/pattern classes, colours, spacing, typography)
+- [vitops-see-the-page](.agents/skills/vitops-see-the-page/SKILL.md) — How to look at a rendered page of this site
+
+Reference, rendered from this project: `vp exec vitops docs [topic]` (no topic lists them).
 <!-- 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.
+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
-  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.
+- `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`,
+  rebuilt from `site.json` on every dev/build, gitignored); put your own CSS in a separate file
+  (e.g. `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).
+  `getEmDashEntry` from `emdash`; render Portable Text with `<PortableText />` from `emdash/ui`.
 - **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`.
+  refreshed from prod, never promoted back.
 - `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.
+- Hosting comes from `vitopsHosting()` in `astro.config.mjs`; never hard-code an adapter or
+  d1/r2/sqlite. Keep the Worker cron trigger in `wrangler.jsonc`: it publishes scheduled content.
 - 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`, …).
-- **Page opener.** Use `vitops_section` at heading level 1 with its button fields (`cta_label`,
-  `secondary_label`) and `stack: rhythm`; don't nest a `vitops_hero` or another section wrapper in a
-  section body, which renders two layers of `section > .centered`. `vitops_hero` is for a hero
-  that stands alone (it carries option cards).
-- **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.
-
-## Branch model
-
-- 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.
+  `vpr lint:design` fails the pre-commit hook on unresolvable classes and layout primitives you
+  hand-rolled (`centered`, `region`, `rhythm`, `subgrid`, `grid-auto`, `cluster` exist for those).
+- `src/assets/placeholder/` is wireframe stand-in imagery; delete it once real assets land.
 - 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`.
+  "improve" them into something that reads as a finished policy.
+- `SETUP.html` is the onboarding checklist (the `setup` skill). Tick a box only for a step you
+  completed, never for a human-only one (the Cloudflare API token, domain cutover, legal documents).
 
-## Docs and skills
+## Branches
 
-- `.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`.
+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, and only when the
+user explicitly asks. Shipping is not a package release: no changeset or version bump.
 
 ## Commands
 
-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.
+This is a **Vite+** project: use `vp` (and `vpr` for scripts), not `pnpm`/`npm`/`npx`. Scripts that
+wrap Astro go through `vpr` (`vpr dev`, `vpr build`), 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>`                                          |
-| 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`                                         |
-| design-lint the markup                   | `vpr lint:design`                                       |
+`vp exec astro dev stop`; the site is at <http://localhost:4321>. `package.json` lists the scripts;
+`vp check` and `vpr typecheck` verify a change. `vpr init:github` and `vpr init:hosting` are one-time
+setup, only when the user asks.
 
-| 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                                                                       |
-| `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                                                                |
+## Where to look
 
-Shipping is not a package release: no changeset or version bump. Commit to `dev`, then promote.
-(`vp` has no `vp change` command.)
-
-`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.
+- **Skills** are listed in the block at the top; load the one matching the task before starting.
+- **Reference** for this project's own tokens, classes, blocks and config: `vp exec vitops docs`.
+- `.mcp.json` preconfigures the Astro and EmDash docs MCP servers; search them before relying on
+  pre-trained knowledge. The EmDash skills (`building-emdash-site`, `emdash-cli`, …) 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`.
+- **Improving the toolkit:** when you work around a framework built-in, 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: what you tried, what failed or was missing, the
+  workaround (file path), the change you'd propose, and the package. Mention new entries in your
+  end-of-task summary. Never patch `node_modules`.

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/skills/content-and-deploys` for how production content
+per request — see `.agents/skills/emdash-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.
 
@@ -179,23 +179,23 @@ 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 — 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/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                                     |
-| `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                                             |
+| 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/skills/vitops-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                                     |
+| `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/emdash-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                                             |

package/templates/emdash/_gitignore

@@ -35,14 +35,14 @@ public/vitops/
 .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
+# (the `vitops-` and `emdash-` prefixes are reserved for toolkit skills)
+.agents/skills/vitops-*
+.agents/skills/emdash-*
+.claude/skills/vitops-*
+.claude/skills/emdash-*
 # `skills experimental_sync` also leaves a duplicate `pnpm-@getvitops+skills-*` link per skill
 .agents/skills/pnpm-*
 .claude/skills/pnpm-*
+# playwright-cli: skill regenerated by `prepare`; output is per-session scratch
+.claude/skills/playwright-cli
+.playwright-cli/

package/templates/emdash/package.json

@@ -18,19 +18,19 @@
     "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 && skills experimental_sync -y -a claude-code --no-frozen-lockfile && vitops agents sync -i site.json"
+    "prepare": "vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile && playwright cli install --skills && vitops agents sync -i site.json"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.0.0",
     "@astrojs/react": "^7.1.2",
-    "@emdash-cms/cloudflare": "latest",
+    "@emdash-cms/cloudflare": "^1.4.0",
     "@getvitops/astro": "latest",
     "@getvitops/core": "latest",
     "@getvitops/emdash": "latest",
     "@getvitops/skills": "latest",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "^7.4.4",
-    "emdash": "latest",
+    "emdash": "^1.4.0",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
     "tailwindcss": "^4.3.3"
@@ -40,10 +40,11 @@
     "@cloudflare/workers-types": "^4.20260305.1",
     "@getvitops/cli": "latest",
     "@iconify-json/fa7-solid": "^1.2.5",
+    "playwright": "^1.62.1",
     "skills": "^1.7.6",
     "typescript": "^6.0.3",
-    "vite": "latest",
-    "vite-plus": "latest",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^1.5.1",
+    "vite-plus": "^1.5.1",
     "wrangler": "^4.111.0"
   },
   "devEngines": {

package/templates/emdash/pnpm-workspace.yaml

@@ -6,25 +6,18 @@ allowBuilds:
   better-sqlite3: false
   sharp: false
 
-# Supply-chain hardening: cooldown on brand-new releases (toolchain exempt)
-# and no non-registry transitive sources.
+# Supply-chain hardening: nothing installs within 3 days of its publish, and no non-registry
+# transitive sources. Only our own lockstep `@getvitops/*` is exempt. Do NOT exempt a third-party
+# toolchain: an exempt package's exact pins are not exempt (vite-plus pins `@oxc-project/*`
+# exactly), so the install fails whenever one is fresher than the window. A security patch may be
+# admitted with an exact `name@x.y.z` line and a dated reason; remove it once it matures.
 minimumReleaseAge: 4320
 minimumReleaseAgeExclude:
   - '@getvitops/*'
-  - emdash
-  - '@emdash-cms/*'
-  - vite-plus
-  - '@voidzero-dev/*'
-  - oxlint
-  - '@oxlint/*'
-  - oxlint-tsgolint
-  - '@oxlint-tsgolint/*'
-  - oxfmt
-  - '@oxfmt/*'
 blockExoticSubdeps: true
 catalog:
-  vite: npm:@voidzero-dev/vite-plus-core@latest
-  vite-plus: latest
+  vite: npm:@voidzero-dev/vite-plus-core@^1.5.1
+  vite-plus: ^1.5.1
 overrides:
   vite: 'catalog:'
 peerDependencyRules:

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/skills/csp.
+# on-demand). See .agents/skills/vitops-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/skills/content-and-deploys), so this
+// into every page. Production is the truth for content (see .agents/skills/emdash-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/site.json

@@ -414,6 +414,17 @@
   },
   "site": {
     "defaultLocale": "en",
+    "chrome": {
+      "masthead": {
+        "position": "sticky",
+        "behavior": "always",
+        "surface": "glass",
+        "layout": "full",
+        "elevation": { "shadow": "sm", "onScroll": true },
+        "height": "4rem"
+      },
+      "nav": { "compact": "drawer", "drawerSide": "end" }
+    },
     "templates": {
       "contact": {
         "type": "form",

package/templates/emdash/src/layouts/Layout.astro

@@ -5,9 +5,11 @@ import { getMenu, getSiteSettings } from 'emdash';
 import { createPublicPageContext } from 'emdash/page';
 import SiteFooter from '@getvitops/astro/components/SiteFooter.astro';
 import SiteNav from '@getvitops/astro/components/SiteNav.astro';
+import Masthead from '@getvitops/astro/components/Masthead.astro';
+import { resolveNavOptions } from '@getvitops/astro/components/masthead.ts';
 import { loadNavMenus } from '@getvitops/astro/components/sitenav.ts';
 import { EmDashHead } from 'emdash/ui';
-import { VitopsWidgetArea } from '@getvitops/emdash/astro';
+import { VitopsMegaPanel, VitopsWidgetArea } from '@getvitops/emdash/astro';
 import config from '../../site.json' with { type: 'json' };
 // Design-system CSS, layout-scoped (vitops css.inject: false): only pages
 // rendered through this layout get it — keeps it out of /_emdash/admin, while
@@ -75,18 +77,19 @@ const orgName = config.organization?.name || siteTitle;
   <body>
     <!-- Widget areas (Widgets in the admin): the same content wherever they appear. -->
     <VitopsWidgetArea name="announcement" class="centered" />
-    <header class="navbar-sticky centered">
-      <div class="navbar">
-        <a class="brand flex items-center" href="/" aria-label={`${siteTitle} home`}>
-          <span class="brand-mark" set:html={logo} aria-hidden="true" />
-          <span class="font-heading">{siteTitle}</span>
-        </a>
-        <div class="header-end flex items-center">
-          <SiteNav {...nav} />
-          <wc-color-scheme-toggle></wc-color-scheme-toggle>
-        </div>
+    <!-- The masthead's look and the nav's behaviour come from `site.chrome` in site.json
+         (position, hide-on-scroll, glass, inset, shadow, drawer vs dropdown). A prop here
+         overrides one field for this layout. -->
+    <Masthead config={config}>
+      <a slot="brand" class="brand flex items-center" href="/" aria-label={`${siteTitle} home`}>
+        <span class="brand-mark" set:html={logo} aria-hidden="true" />
+        <span class="font-heading">{siteTitle}</span>
+      </a>
+      <div class="header-end flex items-center">
+        <SiteNav {...nav} {...resolveNavOptions(config)} megaPanel={VitopsMegaPanel} />
+        <wc-color-scheme-toggle></wc-color-scheme-toggle>
       </div>
-    </header>
+    </Masthead>
 
     <main class="centered rhythm">
       <slot />
@@ -109,10 +112,6 @@ const orgName = config.organization?.name || siteTitle;
         block-size: 1.75rem;
       }
 
-      .navbar {
-        block-size: 64px;
-      }
-
       .header-end {
         gap: var(--space-s, 0.75rem);
       }

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/skills/content-and-deploys).
+// (see .agents/skills/emdash-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

@@ -2,7 +2,7 @@
  * 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/skills/content-and-deploys); this route sets
+ * Every public page is prerendered (see .agents/skills/emdash-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,7 +5,7 @@ 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/skills/content-and-deploys,
+// a publish triggers a rebuild that bakes the change in (.agents/skills/emdash-content-and-deploys,
 // "Rendering and freshness"). The Vitops blocks from @getvitops/emdash render automatically —
 // EmDash merges the plugin's block components into <PortableText>.
 //

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

@@ -59,3 +59,10 @@ report that verbatim rather than guessing at a fix. A step reported as
 "blocked" is not a failure to retry; it is waiting on one of the hard stops
 above, or on a `site.json` field the user still needs to fill in (stage 5,
 Configuration).
+
+## 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:<template> --directory <client-slug>`. `wrangler.jsonc`'s
+`name` (and on EmDash the D1 `database_name` and R2 `bucket_name`) are separate and still say what
+the template shipped; rename them to match before the first deploy.

package/templates/static/.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "allow": ["Bash(pnpm exec playwright cli:*)", "Bash(npx --no-install playwright cli:*)"],
+    "deny": ["mcp__claude-in-chrome__*", "mcp__playwright__*"]
+  }
+}

package/templates/static/.playwright/cli.config.json

@@ -0,0 +1,7 @@
+{
+  "browser": {
+    "browserName": "chromium",
+    "launchOptions": { "headless": true }
+  },
+  "outputDir": ".playwright-cli"
+}

package/templates/static/AGENTS.md

@@ -3,138 +3,50 @@
 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…
+- [vitops-ads](.agents/skills/vitops-ads/SKILL.md) — Use when adding or changing a Google/Meta/LinkedIn/TikTok/Microsoft/Reddit/Pinterest/Snapchat pixel
+- [vitops-consent](.agents/skills/vitops-consent/SKILL.md) — Use before gating, adding or changing any non-essential third-party tag, cookie, embed
+- [vitops-csp](.agents/skills/vitops-csp/SKILL.md) — Use when changing `public/_headers`, adding an embed, tracking snippet or third-party script, turning the CSP on
+- [vitops-design-system](.agents/skills/vitops-design-system/SKILL.md) — Use when styling or authoring pages or components (choosing utility/pattern classes, colours, spacing, typography)
+- [vitops-see-the-page](.agents/skills/vitops-see-the-page/SKILL.md) — How to look at a rendered page of this site
 
-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 -->
+Reference, rendered from this project: `vp exec vitops docs [topic]` (no topic lists them).
 <!-- 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).
+This is a static Astro website styled by the Vitops design system, deployed as Cloudflare Workers
+static assets (no server runtime, no database).
 
 ## 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/` by hand — 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`.)
-- `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.
-- Prefer framework CSS classes (utilities, patterns, type roles like
-  `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   |
-  | ------------------------------------------------------- | --------------- |
-  | 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`**   |
-- Every page is prerendered by default (`output: 'static'`) — there is no
-  server to fall back to, so nothing here can read request-time data
-  (cookies, headers, query params) at render time. If a page genuinely needs
-  that, it needs an adapter and a different template — this one stays pure
-  static on purpose.
-- **`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 (`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:
-  `.github/workflows/promote.yml`, dispatched manually, opens a `dev → main`
-  PR with auto-merge; merging deploys prod. Only run it when the user
-  explicitly asks to promote/ship to production.
-
-## 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>`).
-
-## Content Security Policy
-
-`public/_headers` ships a **`Content-Security-Policy-Report-Only`** header for every
-page (they are all static assets): violations are logged to the browser console and
-nothing is blocked, 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), with no `'unsafe-inline'`. `contentSecurityPolicy()` and
-`inlineScriptHashes()` from `@getvitops/astro` produce the same strings.
-
-Before enforcing it (rename the header to `Content-Security-Policy`), browse the pages
-with the console open: add the origins of any third-party tag the consent gate
-activates to `script-src` / `connect-src`, any embed to `frame-src`, and hash any
-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.
+- `site.json` is the single source of truth: organization + site facts, and the design system under
+  `designSystem.themes.default`. Never edit `src/styles/`: it is generated from `site.json` on every
+  dev/build and gitignored.
+- Every page is prerendered (`output: 'static'`): nothing can read request-time data (cookies,
+  headers, query params). A page that needs that needs an adapter and a different template.
+- Prefer framework classes (utilities, patterns, type roles like `font-heading`) over bespoke CSS.
+  `vpr lint:design` fails the pre-commit hook on unresolvable classes and layout primitives you
+  hand-rolled (`centered`, `region`, `rhythm`, `subgrid`, `grid-auto`, `cluster` exist for those).
+- `src/assets/placeholder/` is wireframe stand-in imagery; delete it once real assets land.
+- `SETUP.html` is the onboarding checklist (the `setup` skill). Tick a box only for a step you
+  completed, never for a human-only one (the Cloudflare API token, domain cutover, legal documents).
+
+## Branches
+
+Work on **`dev`**; every push auto-deploys the isolated `-dev` worker. **`main`** is production and
+protected: never push or merge to it directly; production ships only through the manual `promote`
+workflow (`.github/workflows/promote.yml`), only when the user explicitly asks. Shipping is not a
+package release: no changeset or version bump.
 
 ## 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.
-
-| 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 classes`) |
-| 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                                                                                                                           |
-| `vpr build:css`                           | regenerate the framework CSS from `site.json`                                                                                       |
-| `vpr deploy`                              | build + `wrangler deploy` to prod                                                                                                   |
-| `vpr deploy:dev`                          | build + deploy the isolated dev worker                                                                                              |
-| `vpr init:github`                         | one-time: create + push the GitHub repo (main + dev, dev default, branch protection + environment policy). Only when the user asks. |
-| `vpr init:hosting`                        | one-time: read the Cloudflare account id and set it as a repo secret. Only when the user asks.                                      |
-| `vp exec vitops validate site.json`       | schema-check the site config                                                                                                        |
-| `vp exec vitops lint -i site.json -f css` | find framework classes in source that resolve to nothing under this format                                                          |
+This is a **Vite+** project: use `vp` (and `vpr` for scripts), not `pnpm`/`npm`/`npx`. Scripts that
+wrap Astro go through `vpr` (`vpr dev`, `vpr build`), 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>. `package.json` lists the scripts;
+`vp check` and `vpr typecheck` verify a change. `vpr init:github` and `vpr init:hosting` are one-time
+setup, only when the user asks.
 
-**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`.
+## Where to look
 
-**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:static --directory <client-slug>`. `wrangler.jsonc`'s `name`
-is separate and still says what the template shipped — rename it to match before
-the first deploy.
+- **Skills** are listed in the block at the top; load the one matching the task before starting.
+- **Reference** for this project's own tokens, classes and config: `vp exec vitops docs`.

package/templates/static/_gitignore

@@ -27,11 +27,11 @@ public/vitops/
 .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
+# (the `vitops-` and `emdash-` prefixes are reserved for toolkit skills)
+.agents/skills/vitops-*
+.agents/skills/emdash-*
+.claude/skills/vitops-*
+.claude/skills/emdash-*
+# playwright-cli: skill regenerated by `prepare`; output is per-session scratch
+.claude/skills/playwright-cli
+.playwright-cli/

package/templates/static/package.json

@@ -16,7 +16,7 @@
     "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 && skills experimental_sync -y -a claude-code --no-frozen-lockfile && vitops agents sync -i site.json"
+    "prepare": "vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile && playwright cli install --skills && vitops agents sync -i site.json"
   },
   "dependencies": {
     "@getvitops/astro": "latest",
@@ -26,10 +26,11 @@
   "devDependencies": {
     "@astrojs/check": "^0.9.12",
     "@getvitops/cli": "latest",
+    "playwright": "^1.62.1",
     "skills": "^1.7.6",
     "typescript": "^6.0.3",
-    "vite": "latest",
-    "vite-plus": "latest",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^1.5.1",
+    "vite-plus": "^1.5.1",
     "wrangler": "^4.111.0"
   },
   "devEngines": {

package/templates/static/pnpm-workspace.yaml

@@ -5,17 +5,12 @@ allowBuilds:
   workerd: true
   sharp: false
 
-# Supply-chain hardening: nothing installs within 3 days of its publish
-# (toolchain exempt), and no non-registry transitive sources.
+# Supply-chain hardening: nothing installs within 3 days of its publish, and no non-registry
+# transitive sources. Only our own lockstep `@getvitops/*` is exempt. Do NOT exempt a third-party
+# toolchain: an exempt package's exact pins are not exempt (vite-plus pins `@oxc-project/*`
+# exactly), so the install fails whenever one is fresher than the window. A security patch may be
+# admitted with an exact `name@x.y.z` line and a dated reason; remove it once it matures.
 minimumReleaseAge: 4320
 minimumReleaseAgeExclude:
   - '@getvitops/*'
-  - vite-plus
-  - '@voidzero-dev/*'
-  - oxlint
-  - '@oxlint/*'
-  - oxlint-tsgolint
-  - '@oxlint-tsgolint/*'
-  - oxfmt
-  - '@oxfmt/*'
 blockExoticSubdeps: true