@getvitops/create 0.8.0-alpha.0 → 0.8.1

package/CHANGELOG.md

@@ -1,12 +1,307 @@
 # @getvitops/create
 
+## 0.8.1
+
+### Patch Changes
+
+- Both templates pin Node by major only (`devEngines.runtime.version: "24"`), matching `.node-version`. The exact `24.18.0` pin disagreed with the floating `.node-version`, so `vp` warned in every fresh scaffold.
+
+## 0.8.0
+
+### Minor Changes
+
+- 226b1aa: **Content now lives in production; dev is a refreshed copy.** The `dev → main` flow is for code,
+  pages and `site.json`. EmDash content is edited on the production site (drafts, "Publish changes"
+  and preview links are the staging step), and the dev database is disposable and refreshed _from_
+  prod — never promoted back. Both templates gain a hotfix path back into `dev`.
+
+  - **New `refresh-dev.yml` (emdash template) + `scripts/refresh-dev.mjs`** — copies prod's D1
+    database into `<name>-dev` (weekly and on demand), and prod's R2 bucket too when the optional
+    `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` repo secrets are set. It drops every table in its
+    target, so it refuses a database that isn't `*-dev`, doesn't match `DEV_D1_ID`, or is
+    production's. **Overwrites everything in the dev database on each run** — content edited on dev
+    is lost by design.
+  - **New `backmerge.yml` (both templates)** — on every push to `main`, opens a `main → dev` PR when
+    merging would change `dev`, so a prod hotfix doesn't leave `dev` behind. The PR is left for a
+    human to merge unless a `BACKMERGE_TOKEN` secret (PAT / GitHub App token) is set: a merge made
+    with the default token triggers no workflows, so Deploy dev would not run.
+  - **Magic-link sign-in in the emdash template**: it now registers `cloudflareEmail()` and a
+    `send_email` binding named `EMAIL`. A passkey only works at the origin it was registered on, so a
+    refreshed dev site would otherwise lock editors out; the cloned users already exist, so the same
+    email signs in on both origins. **Existing sites:** templates are copied at scaffold time, so
+    nothing changes until you add both yourself, and magic link answers "Email is not configured"
+    until you do. Onboard the sender first (`npx vitops email setup send.<your-domain>`) and set
+    `from` to an address on that domain — the template ships a placeholder you must replace.
+  - **The dev worker no longer has a cron trigger** (`build-dev-wrangler.mjs`), since a refreshed
+    database carries prod's scheduled publishes and plugin jobs. Scheduled publishing can't be
+    exercised on dev. Set a different `EMDASH_PREVIEW_SECRET` on the dev worker, or prod preview
+    links will open drafts there.
+  - `SETUP.html` and the `promote` skill describe the new model; `SETUP.html` gains four items under
+    "3. Hosting resources" (the OAuth apps and preview secret are manual).
+
+  No consumer-facing change in `@getvitops/core`, `@getvitops/generator`, `@getvitops/utils`,
+  `@getvitops/cli`, `@getvitops/vite`, `@getvitops/astro` or `@getvitops/emdash`. The reusable
+  workflows (`site-refresh-dev.yml`, `site-backmerge.yml`) reach existing client repos only once the
+  `v1` tag is moved by `release-workflows.yml`; a client needs the new caller files above to use them.
+
+- 0a4f64b: **EmDash template:** documents installing the EmDash agent skills per project
+  (`npx skills add emdash-cms/skills --skill '*' -a claude-code -y`, so they match the pinned `emdash`) in
+  the README and `AGENTS.md`, and lists the current blocks (hero, cards, accordion, gallery, marquee, …)
+  with `npx vitops docs blocks` as the full reference. Raises the dependency floors (`@astrojs/react`
+  7.1, `@astrojs/check` 0.9.12, React 19.3.1) and both templates now pin `pnpm@12.16.1`.
+- c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
+  designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+  './site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
+  offered, now usable by the client directly, no dev server required. An edit is visible
+  site-wide immediately (a runtime `:root` override, served via a new plugin API route and
+  `page:fragments`) and — once `site.deployment.repo`/`branch` and a `VITOPS_GITHUB_TOKEN`
+  secret are set (see the scaffold's `SETUP.html`) — auto-commits to your `dev` branch, so it
+  reaches the git-tracked `site.json` through your repo's normal review path rather than
+  becoming a second, unreviewed source of truth. Until that's configured, the live half still
+  works; only the auto-commit half is skipped (and says so in the admin page). The save route
+  runs the exact same accessibility (APCA contrast) gate `generate()` enforces at build time,
+  synchronously, before persisting — nothing non-compliant ever goes live even momentarily.
+
+  Requires `@astrojs/react` + `react` + `react-dom` (already scaffold dependencies, for
+  EmDash's own admin) and `@getvitops/core` (added as a new scaffold dependency this release).
+  Declares two new plugin capabilities when enabled: `network:request` (for the GitHub
+  auto-commit) and `hooks.page-fragments:register` (for the live override) — reviewed once at
+  plugin-install time.
+
+  **Breaking for `@getvitops/emdash`**: `vitopsEmdash()`'s `hooks.page-fragments:register`
+  capability is now also granted whenever `designSystemEditor` is set, independent of the
+  existing `scripts: 'fragments'` option (which governs something unrelated — web-component
+  script delivery). No change if you don't use `designSystemEditor`.
+
+  Also new, supporting the above:
+
+  - `@getvitops/generator`: `validateColorContract()` and `buildReverseIndex()` (both
+    `/tokens` subpath, Worker-safe) — the monotonicity/contrast gate and the
+    `design-manifest.json` reverse-index, each extracted from `generate()`'s `build()` into
+    standalone, non-throwing functions. `patchToOverrideCss()` turns a design-system patch
+    into the `:root` override `<style>` block. `designSystemPath`/`getAt`/`setAt`/
+    `mergePatch`/`formatConfig` moved from `@getvitops/vite` into `@getvitops/generator/config`
+    (re-exported from `@getvitops/vite` unchanged) — one "patch a config file's design-system
+    subtree" implementation shared by the dev endpoint and the new plugin route. New
+    `site.deployment.repo`/`branch` config fields.
+  - `@getvitops/utils`: new `/git` subpath — `commitFile()`, a Worker-safe (fetch-only)
+    wrapper over GitHub's Contents API.
+  - `@getvitops/core`: `<wc-theme-editor>` gains a `save-endpoint` attribute (default
+    unchanged — `/__vitops/design-system`) so the same element can target the new plugin
+    route instead of the dev-only Vite endpoint.
+
+- 2ef2d41: **Tested against EmDash 1.4.** `emdash` and `@emdash-cms/cloudflare` are now `^1.4.0` in the
+  `emdash` template, and `@getvitops/emdash`'s peer ranges for both moved from `>=1.0.0 <2` to
+  `>=1.3.0 <2` — **breaking for a site still on EmDash 1.0–1.2**: upgrade `emdash` and
+  `@emdash-cms/cloudflare` together (EmDash warns at build when the two differ) before upgrading
+  this package. 1.4 fixes a stored XSS in the visual-editing toolbar (an author's published content
+  could run script for a signed-in editor), so an existing client site should take it promptly.
+
+  - **`vitopsHosting()` coalesces D1 reads by default** — new `cloudflare.coalesce` option
+    (default `true`, passed to `d1({ coalesce })`). With `session: 'auto'`, EmDash 1.3 stops
+    preloading settings/menus/widgets for logged-out visitors unless reads are coalesced, so this
+    restores one round trip instead of several. It is experimental upstream: a read and a write
+    started together may run write-first, so `await` a read before a write that must not affect it.
+    Set `coalesce: false` to opt out. No effect without a session.
+  - **Template:** `AGENTS.md` gains an "EmDash 1.x behaviours" section (passkeys are bound to a
+    hostname so use _Change domain_ at cutover; admin-authored HTML blocks run JS and conflict with
+    Astro CSP; link by `entry.data.slug`, not `entry.id`; submit `/sitemap.xml`; clearing a stuck D1
+    lock with `emdash migrate --take-over-lock`).
+  - **Upstream behaviour changes to know about (no code change here):** `cacheHint.lastModified` is
+    no longer auto-populated and pages lose the implicit `Cache-Control: no-cache`; collection
+    sitemaps paginate at 2,000 entries; `entry.id` is always locale-prefixed on multilingual sites.
+
+  No consumer-facing change in `@getvitops/core`, `@getvitops/generator`, `@getvitops/utils`,
+  `@getvitops/cli` or `@getvitops/vite`. `@getvitops/astro` has one — see the scaffold changeset.
+
+- ab451ae: **Scaffolds now pin Astro `^7.4.4` and ship a `.node-version`.** Both templates (`emdash`, `static`)
+  move from `astro: ^7.1.2` to `^7.4.4` — the newest release at least three days old when this was
+  chosen (7.4.5 was under a day old), matching what this repo builds and tests against — and add a
+  `.node-version` containing `24`, so version managers that read it (fnm, mise, asdf, Volta) agree with
+  the `.nvmrc` the reusable CI workflows read and the `devEngines` pin pnpm reads. `templates.test.ts`
+  now fails if those three disagree, or if a template's Astro range drifts from the repo's catalog.
+
+  Existing projects are not changed: bump `astro` yourself, and add `.node-version` if you want it.
+
+  Formats reached: none — no CSS change. Other packages in the `fixed` group: No consumer-facing change
+  in this package.
+
+- b70c7f0: **Scaffolded projects now hold new releases for 3 days before installing them.** Both templates set
+  `minimumReleaseAge: 4320` (the `emdash` template was 1440; the `static` template had no
+  `pnpm-workspace.yaml` and so used pnpm's one-day default). The `static` template now ships a
+  `pnpm-workspace.yaml` carrying the cooldown, the build approvals, and the same toolchain exemptions as
+  `emdash` — `@getvitops/*` and the Vite+ / Oxc tools are exempt, since they release together.
+
+  If a fresh install in a scaffolded project is rejected for a dependency published in the last three
+  days, wait for it to age or add its exact version to `minimumReleaseAgeExclude`. Existing projects are
+  not changed.
+
+  Formats reached: none — no CSS change. Other packages in the `fixed` group: No consumer-facing change
+  in this package.
+
+### Patch Changes
+
+- 0574388: Add `vitops email setup|check` — connect `site.notifications.email.from` to whether its domain is
+  actually onboarded onto an outbound email provider.
+
+  Before this, nothing checked that. `EMAIL.send()` throws `E_SENDER_NOT_VERIFIED` at runtime with no
+  build or deploy-time warning — the failure mode is silent and production-only.
+
+  `vitops email setup [domain]` onboards a sending domain (currently Cloudflare Email Sending only)
+  and polls DNS until its SPF/DKIM/DMARC records resolve or a timeout is reached; `vitops email
+  check` is the non-blocking deploy guard both `@getvitops/create` templates' `deploy`/`deploy:dev`
+  scripts now run first (`--strict` makes it a real gate; opt out per-site with
+  `site.notifications.email.verifySender: false`, or globally with `--skip` /
+  `VITOPS_SKIP_EMAIL_CHECK`).
+
+  Two things worth knowing before running it:
+
+  - **The onboarded entity is an exact name, and it is usually a subdomain**
+    (`send.yourdomain.com`), never the apex your `from` address names. When the exact domain isn't
+    onboarded but a sibling in the same zone already is, the command reports that as the fix — send
+    from the onboarded subdomain — rather than silently trying to onboard the apex, which rewrites
+    `_dmarc.<domain>` and can tighten DMARC policy on every other mail your domain sends.
+  - Candidates come from `site.notifications.email.from` (or its derived `noreply@<domains
+    .canonical>` default) first; a best-effort scan of `--src` only supplements it, and never guesses
+    at a computed `from` value.
+
+  New `@getvitops/utils/email` subpath and `site.notifications.email.verifySender` config field.
+  Needs `CLOUDFLARE_API_TOKEN` with an Email Sending scope in addition to the `Zone:Read` other
+  commands already use.
+
+- 1a8231d: **EmDash blocks are now a tier of the component manifest, and there are four more of them.**
+
+  `@getvitops/emdash` adds `vitops.gallery`, `vitops.cards`, `vitops.accordion` and `vitops.marquee`
+  (each a thin adapter over the matching `@getvitops/astro` component), and `vitops.carousel` now edits
+  its slides as a **Slides repeater** instead of two newline-separated fields. Blocks saved before this
+  keep rendering: with no `slides`, the carousel still reads `images`/`alts`, and both legacy fields stay
+  in the editor, labelled as legacy. The editor's field type now admits `repeater` and `media_picker`.
+
+  - **New `blocks` plugin option** — `vitopsEmdash({ blocks: { include, exclude, extra } })`. `include` is
+    an allowlist, `exclude` drops blocks, `extra` adds the site's own **editor** definitions (the site
+    supplies their renderers via `<PortableText components={{ type }}>`, the same route that overrides a
+    `vitops.*` renderer). An unknown name or a colliding `type` throws at plugin construction.
+  - Link and image URLs in blocks with a scheme other than `http`, `https`, `mailto` or `tel` are
+    dropped (see the security entry).
+
+  `@getvitops/generator`: `TierEntry` gains an optional `emdash: string[]` (block `_type`s) and `Tier`
+  gains `'emdash'`, so `tierPatterns('emdash')` projects it. **Breaking only for code that exhaustively
+  switches on `Tier` or builds a `Record<Tier, …>`** — add an `emdash` case. The agent doc
+  `vitops docs components` gains an "EmDash blocks" table and the docsite a `components/emdash` page. The
+  guard that every block and every `emdash` entry agree lives in `@getvitops/emdash`'s `blocks.test.ts`,
+  because the generator cannot import the plugin.
+
+  `@getvitops/create`: the EmDash template's agent guidance explains the blocks, their limits (a block
+  cannot contain blocks; `vitops.*` blocks do not render inside EmDash's built-in `columns`) and the
+  `blocks` option.
+
+  Formats reached: none — no CSS change. Other packages in the `fixed` group: No consumer-facing change
+  in this package.
+
+- 779d22e: Add a `vitops.hero` EmDash block (eyebrow, heading, text, two links, optional image; centered or split layout) built on the `.centered`/`.split` layout primitives. The EmDash template's home page now seeds one of each of hero, cards, accordion and marquee. `@getvitops/generator`: the `split` pattern lists the new block in `TIERS`.
+- 0574388: Bump `emdash`/`@emdash-cms/cloudflare` peers to `>=1.0.0 <2` and `vite-plus` to `^1.0.0`, following
+  both projects' GA releases.
+
+  **Breaking for `@getvitops/emdash` consumers on EmDash 0.x**: the peer range no longer admits
+  `emdash@0.31.x`/`@emdash-cms/cloudflare@0.31.x`. Upgrade `emdash` and `@emdash-cms/cloudflare` to
+  `^1.0.1` first — nothing in `@getvitops/emdash`'s own plugin surface (`admin.portableTextBlocks`,
+  the `hooks.page-fragments:register` capability, `definePlugin()`) changed against EmDash 1.0, so no
+  code here needed to change, only the declared range.
+
+  The `emdash` scaffold template (`vp create @getvitops:emdash`) picks up several fixes alongside
+  the version bump:
+
+  - `tailwindcss`/`@tailwindcss/vite` are now real dependencies — the template selected
+    `css.format: 'tailwind'` without installing either, which threw on build.
+  - `site.json` now sets `site.icons.sprite: true` plus the full `semantic` list the
+    `vitops.actionLink` block's icon picker offers — previously its sprite icons pointed at a file
+    the build never generated.
+  - `astro.config.mjs` sets `migrations: { runtime: 'check', dev: 'auto' }`, and
+    `site-deploy-emdash.yml` runs EmDash 1.0's documented `build → status → apply → deploy → check`
+    migration sequence explicitly, rather than relying solely on first-request auto-migration. This
+    needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
+    which only a human can set — run `emdash migrate --status` against the real deployed database,
+    review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
+    <value>`. Deploys fail clearly on the migration-apply step until it's set.
+  - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
+    not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
+    errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).
+    Uncomment it once scaffolded into its own repo.
+
+  No config schema changes. `@getvitops/generator` also switches from the `zod/mini` subpath import
+  to the standalone `@zod/mini` package (zod 4.5+; same API) and fixes `validateConfig()` silently
+  losing the offending key name on an `unrecognized_keys` error (e.g. a typo'd `site.ads` platform
+  now names the bad key instead of reporting a bare "Invalid input").
+
+  Also fixed: `vp check`'s `tsconfig-error` for `packages/create/templates/emdash/tsconfig.json`
+  (`extends: "astro/tsconfigs/strict"`, unresolvable from inside this monorepo since the template
+  has no `node_modules` of its own — a pre-existing, structural gap, newly surfaced as a hard error
+  by oxlint 1.85's deeper config discovery, and blocking on every commit since this repo's pre-commit
+  hook runs `vp check --fix`). Fixed with a new `scripts/link-template-deps.mjs`, wired as the root
+  `postinstall` script: symlinks `astro`/`emdash`/`@emdash-cms/cloudflare` into the template's own
+  `node_modules/` (resolved fresh from sibling packages that already depend on them for real, not a
+  hardcoded `.pnpm` hash) and writes a minimal `astro:content` ambient shim at `.astro/types.d.ts`
+  (the same path `astro sync` would generate for real). Both are gitignored and only ever exist
+  inside this monorepo's copy of the template — a real scaffold installs its own real copies instead.
+  Considered and rejected first: inlining astro's strict preset (drift risk against astro's own
+  evolving default) and making the template a real pnpm workspace member (would change how its
+  `@getvitops/*: "latest"` deps resolve locally, which `templates.test.ts` exists to protect).
+
+  **Known gap, not fixed here**: `packages/astro/src/components/container.test.ts` (the
+  `AstroContainer`-based render tests) fails to even load under vite-plus 1.0's Vite 8 — direct
+  `.astro` imports in a Vitest file need the Astro Vite plugin registered, which nothing in this
+  repo's test config actually does (Astro's own docs call for `getViteConfig()`, which doesn't
+  compose with vite-plus's own `defineConfig`). A type-level shim
+  (`packages/astro/src/components/astro-modules.d.ts`) fixes `vp check`'s type-aware pass, but the
+  runtime `vp test` failure for this one file is still open.
+
+- 0f8c018: **New: `resolveOrganizationName(config, locale?)`**, exported from `@getvitops/astro/routes`
+  alongside `toNotifyContext`/`toCrmConfig` — the same `organization.name` → `legalName` →
+  `undefined` fallback chain `toNotifyContext` already used for its `organizationName` field,
+  now usable standalone anywhere a build-time-only display name is needed (favicon generation,
+  a scaffold's `astro.config.mjs`, a `Layout.astro` fallback). `toNotifyContext` is unchanged —
+  it now delegates to this helper internally.
+
+  The emdash scaffold uses it to remove a three-way duplicated `'My EmDash Site'` string:
+  `astro.config.mjs`'s favicon `name` and `Layout.astro`'s title fallback both previously
+  hardcoded it independently of `site.json`'s `organization.name`. EmDash's own
+  `getSiteSettings().title` (set in the admin) still wins at render time when it's set — it's a
+  runtime-only fact that can't be read at build time at all — this only replaces the two
+  hardcoded _fallback_ strings.
+
+- 2ef2d41: **`resolveOrganizationName()` accepts a plain `import site from './site.json'`.** It was typed
+  against the full `Config`, which a JSON import cannot satisfy — TypeScript widens its literals
+  (`colors.utilities` becomes `string[]`, not the schema's union) — so every scaffolded site's
+  `Layout.astro` failed `astro check`. It now takes `OrganizationNameSource`, the slice it actually
+  reads (`organization.name` / `legalName`, `site.defaultLocale`); a resolved `Config` still
+  satisfies it, so nothing that compiled before stops compiling.
+
+  **Both templates now typecheck and lint clean on a fresh scaffold**, found by the new `scaffold`
+  CI job (it installs each template against this checkout's packed packages):
+
+  - `site.json` declares `neutral` and `surface` as `{ "hue": "ink", "kind": "surface" }`. As bare
+    hue strings they were chromatic roles, which emit no bare `bg-neutral` and no
+    `text-neutral-muted`, so the template's own footer class resolved to nothing and `vitops lint
+    --strict` (run by the template's pre-commit hook) failed. **Existing sites are unaffected** —
+    this changes only what a new scaffold starts with; if your own `site.json` has the same two
+    lines and uses `text-neutral-*` or `bg-surface*`, change them the same way.
+  - The `emdash` template's `index.astro` and `[...slug].astro` cast `page.data.title`, which is
+    `unknown` until `emdash types` has run against a live site, so `astro check` passed only after
+    the first `pnpm dev`.
+
+  No consumer-facing change in `@getvitops/core`, `@getvitops/generator`, `@getvitops/utils`,
+  `@getvitops/cli` or `@getvitops/vite`.
+
+- 80bbef1: Both templates ship `public/_headers` with a no-break security baseline (`X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `X-Frame-Options: SAMEORIGIN`), applied by Workers static assets. No CSP: `<Head />` emits inline scripts, so a policy needs per-site nonces or hashes. Note `_headers` covers static assets only; for the EmDash template's Worker-rendered pages, add headers in the Worker.
+
 ## 0.8.0-alpha.0
 
 ### Minor Changes
 
 - c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
-designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
-'./site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+  './site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
   `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
   offered, now usable by the client directly, no dev server required. An edit is visible
   site-wide immediately (a runtime `:root` override, served via a new plugin API route and
@@ -55,7 +350,7 @@ designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import c
 
   `vitops email setup [domain]` onboards a sending domain (currently Cloudflare Email Sending only)
   and polls DNS until its SPF/DKIM/DMARC records resolve or a timeout is reached; `vitops email
-check` is the non-blocking deploy guard both `@getvitops/create` templates' `deploy`/`deploy:dev`
+  check` is the non-blocking deploy guard both `@getvitops/create` templates' `deploy`/`deploy:dev`
   scripts now run first (`--strict` makes it a real gate; opt out per-site with
   `site.notifications.email.verifySender: false`, or globally with `--skip` /
   `VITOPS_SKIP_EMAIL_CHECK`).
@@ -67,7 +362,7 @@ check` is the non-blocking deploy guard both `@getvitops/create` templates' `dep
     from the onboarded subdomain — rather than silently trying to onboard the apex, which rewrites
     `_dmarc.<domain>` and can tighten DMARC policy on every other mail your domain sends.
   - Candidates come from `site.notifications.email.from` (or its derived `noreply@<domains
-.canonical>` default) first; a best-effort scan of `--src` only supplements it, and never guesses
+    .canonical>` default) first; a best-effort scan of `--src` only supplements it, and never guesses
     at a computed `from` value.
 
   New `@getvitops/utils/email` subpath and `site.notifications.email.verifySender` config field.
@@ -96,7 +391,7 @@ check` is the non-blocking deploy guard both `@getvitops/create` templates' `dep
     needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
     which only a human can set — run `emdash migrate --status` against the real deployed database,
     review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
-<value>`. Deploys fail clearly on the migration-apply step until it's set.
+    <value>`. Deploys fail clearly on the migration-apply step until it's set.
   - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
     not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
     errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/create",
-  "version": "0.8.0-alpha.0",
+  "version": "0.8.1",
   "description": "Project templates for the Vitops design system — scaffold wired-up sites with `vp create @getvitops`.",
   "homepage": "https://docs.vitops.ca",
   "bugs": "https://github.com/getvitops/design-system/issues",
@@ -19,7 +19,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@getvitops/generator": "8.2.0-alpha.0"
+    "@getvitops/generator": "8.2.0"
   },
   "engines": {
     "node": ">=24"

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

@@ -59,12 +59,29 @@ So this skill's only job is to kick off the `dev → main` promotion. It does
     no further action.
 - Once `main` advances, **Deploy prod** runs automatically.
 
-## Schema / content changes
+## Content is not promoted — it lives in prod
+
+Content (entries, media, menus, settings) is edited on the **production** site,
+using drafts, "Publish changes" and preview links as the staging step. The dev
+database is a disposable copy of prod: the **Refresh dev from prod** workflow
+(`refresh-dev.yml`) overwrites it, one direction only. Never try to carry dev
+content to prod — a refresh would erase it anyway.
+
+## Schema changes
 
 If this release changes the content model, code promotion is **not** enough —
-the schema lives in the EmDash database, not git. Apply the same schema change
-to the prod site separately (via its admin at `/_emdash/admin` or its MCP
-server at `/_emdash/api/mcp`). Ordering: additive changes (new collection /
-optional field) **before** the code deploy that uses them; removals **after**
-the code that stops using them. Mention this to the user only if the release
-plausibly touched the schema.
+the schema lives in the EmDash database, not git. Rehearse it first: run
+**Refresh dev from prod**, apply the change to dev, check the site. Then apply the
+same change to prod (admin at `/_emdash/admin`, or the MCP server at
+`/_emdash/api/mcp`). Ordering: additive changes (new collection / optional
+field) **before** the code deploy that uses them; removals **after** the code
+that stops using them. Mention this to the user only if the release plausibly
+touched the schema.
+
+## Hotfixing prod
+
+A fix that can't wait for dev: branch off `main`, PR into `main`, deploy. The
+**Back-merge main → dev** workflow then opens a `main → dev` PR so dev doesn't
+drift (merge it — that is what triggers a dev deploy — unless
+`BACKMERGE_TOKEN` is set, in which case it merges itself when clean). Conflicts
+are left on the PR for a human.

package/templates/emdash/.github/workflows/backmerge.yml

@@ -0,0 +1,18 @@
+# Carry changes made directly on `main` (a hotfix) back into `dev`, so the
+# integration branch doesn't silently drift from what is live. Runs on every
+# push to `main`, including each promotion, and opens a PR only when merging
+# main into dev would actually change dev.
+#
+# Deploys via the vitops toolchain's reusable workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-backmerge.yml
+# for why the PR is left for a human unless BACKMERGE_TOKEN is set.
+name: Back-merge main → dev
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  backmerge:
+    uses: getvitops/design-system/.github/workflows/site-backmerge.yml@v1
+    secrets: inherit

package/templates/emdash/.github/workflows/refresh-dev.yml

@@ -0,0 +1,25 @@
+# Refresh the dev site's database and media from PRODUCTION.
+#
+# Content is edited in prod (drafts + preview links are the staging step); dev
+# holds a disposable copy so code and schema changes can be rehearsed against
+# real data. This only ever copies prod → dev, and refuses to run against a
+# database whose id is production's. Run it before testing a schema change, or
+# let the weekly schedule keep dev from drifting.
+#
+# Deploys via the vitops toolchain's reusable workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-refresh-dev.yml
+#
+# Required: the same CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID / DEV_D1_ID
+# secrets Deploy dev uses. Optional, for copying media as well:
+#   R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY — an R2 API token (S3 credentials)
+name: Refresh dev from prod
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  refresh:
+    uses: getvitops/design-system/.github/workflows/site-refresh-dev.yml@v1
+    secrets: inherit

package/templates/emdash/.node-version

@@ -0,0 +1 @@
+24

package/templates/emdash/AGENTS.md

@@ -19,6 +19,16 @@ styled by the Vitops design system.
   `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 (`npx vitops docs blocks` lists them with every field). Repeating content (cards, gallery images, accordion items, carousel slides) is
+  a repeater field. A block cannot contain other blocks, and a `vitops.*` block inside EmDash's
+  built-in `columns` does not render — for layout (a section, a split, a hero) use a `blocks`
+  field, or hand-write the page template with `@getvitops/astro` components
+  (`Subgrid`, `Cards`, `Carousel`, …). `npx vitops docs components` lists every pattern, which
+  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`.
 - `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
@@ -30,15 +40,16 @@ styled by the Vitops design system.
   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`** |
+
+  | 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
@@ -105,11 +116,42 @@ styled by the Vitops design system.
   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
+  `pnpm 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.
 
+## 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
+npx skills add emdash-cms/skills --skill '*' -a claude-code -y
+```
+
+Refresh them with `npx skills update` after bumping `emdash` — the
+`upgrading-emdash` skill covers the rest of the upgrade.
+
 ## Commands
 
 - `pnpm dev` — local dev with local D1/R2 emulation (no Cloudflare account)

package/templates/emdash/README.md

@@ -14,7 +14,8 @@ Scaffolded from `vp create @getvitops:emdash`.
   (Tailwind v4 format), generates favicons/PWA assets from
   `src/assets/logo.svg`, and serves the web-component runtime
 - **`@getvitops/emdash`** — design-system Portable Text blocks in the editor
-  slash menu: image compare, copy snippet, banner, disclosure, carousel
+  slash menu (hero, cards, accordion, carousel, gallery, marquee, banner, …);
+  `npx vitops docs blocks` lists every block and field
 
 `src/assets/placeholder/` ships neutral wireframe images for layout work
 before real imagery exists — delete once real assets land (separate from
@@ -87,7 +88,8 @@ The repo ships a two-environment flow modeled on branch = environment:
   into `main` with auto-merge enabled. With required reviews on `main`, a
   human approves the PR; merging deploys prod.
 
-One-time setup — work through the checklist:
+One-time setup — see [Start a new EmDash site](https://docs.vitops.ca/guides/new-emdash-site) for the whole
+procedure, then work through the checklist:
 
 ```bash
 pnpm run sop && open SETUP.html   # or: xdg-open SETUP.html
@@ -118,12 +120,12 @@ is a configurable dimension of the project, not a rewrite:
 - **`node`** — `@astrojs/node` (standalone) + SQLite file + local uploads,
   for a VPS / docker-compose / k8s host. Not installed by default; to switch:
   `pnpm add @astrojs/node better-sqlite3`, then `vitopsHosting({ target:
-'node' })` (or set `HOSTING=node` — the env var wins). Run the built site
+  'node' })` (or set `HOSTING=node` — the env var wins). Run the built site
   with `node ./dist/server/entry.mjs`; data lives in `./data/` (gitignored) —
   persist it as a volume. Scheduled publishing runs in-process on Node, so
   the worker/cron pieces aren't needed. For production, move storage to
   S3-compatible and/or the database to Postgres via `vitopsHosting({ node:
-{ database, storage } })`. CI deploy for Node hosts is TBD — the shipped
+  { database, storage } })`. CI deploy for Node hosts is TBD — the shipped
   workflows are Cloudflare-specific.
 
 Moving an existing site between targets (either direction) is a data
@@ -139,6 +141,10 @@ and media in the storage backend (bucket/directory copy).
 - **Skills** (`.agents/skills/`): `promote` dispatches the dev → main
   promotion workflow. Run `npx vitops agents` to also write the design-system
   class reference into `AGENTS.md`.
+- **EmDash skills** are installed per project so they match the pinned `emdash`
+  version: `npx skills add emdash-cms/skills --skill '*' -a claude-code -y`,
+  then commit `.agents/skills/` and `skills-lock.json`. Update with
+  `npx skills update` after an `emdash` bump.
 - **Claude Code on the web**: the SessionStart hook
   (`.claude/hooks/session-start.sh`) installs Node 24 (matching
   `devEngines`), activates the pinned pnpm, and installs dependencies in the

package/templates/emdash/SETUP.html

@@ -194,6 +194,59 @@
                 so.
               </span>
             </label>
+            <label class="custom-check">
+              <input type="checkbox" data-sop="hosting.content-in-prod" />
+              <span class="custom-check__box"
+                ><span class="custom-check__indicator custom-check__indicator--check"></span
+              ></span>
+              <span>
+                <strong>Know where content is edited (EmDash template).</strong> Editors work on the
+                <em>production</em> site — drafts, "Publish changes" and preview links are the
+                staging step. The dev site holds a disposable copy of production's database; it is
+                refreshed from prod and never promoted back. Code, pages and
+                <code>site.json</code> still go dev → main.
+              </span>
+            </label>
+            <label class="custom-check">
+              <input type="checkbox" data-sop="hosting.refresh-dev" />
+              <span class="custom-check__box"
+                ><span class="custom-check__indicator custom-check__indicator--check"></span
+              ></span>
+              <span>
+                EmDash template: run <strong>Refresh dev from prod</strong> (Actions tab) once the
+                prod site has content, and again before rehearsing a schema change. It runs weekly
+                on its own. To copy media as well, set <code>R2_ACCESS_KEY_ID</code> and
+                <code>R2_SECRET_ACCESS_KEY</code> (an R2 API token's S3 credentials) as repo
+                secrets; without them only the database is refreshed.
+              </span>
+            </label>
+            <label class="custom-check">
+              <input type="checkbox" data-sop="hosting.magic-link" />
+              <span class="custom-check__box"
+                ><span class="custom-check__indicator custom-check__indicator--check"></span
+              ></span>
+              <span>
+                EmDash template: onboard the sender domain for sign-in email —
+                <code>npx vitops email setup send.&lt;your-domain&gt;</code>, then put that address
+                in <code>cloudflareEmail({ from })</code> in <code>astro.config.mjs</code> (it ships
+                a placeholder). Editors sign in with a magic link ("Sign in with email" on the login
+                page) because a passkey only works at the origin it was registered on, so a
+                refreshed dev site has no other way in. Check <strong>Settings → Email</strong> and
+                send the test email on both prod and dev.
+              </span>
+            </label>
+            <label class="custom-check">
+              <input type="checkbox" data-sop="hosting.preview-secret" />
+              <span class="custom-check__box"
+                ><span class="custom-check__indicator custom-check__indicator--check"></span
+              ></span>
+              <span>
+                EmDash template: set a different <code>EMDASH_PREVIEW_SECRET</code> on the dev
+                worker (<code>wrangler secret put EMDASH_PREVIEW_SECRET</code>). The secret lives in
+                the database, so a refresh copies prod's — and prod preview links would then open
+                drafts on dev.
+              </span>
+            </label>
           </div>
         </details>