@getvitops/create 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # @getvitops/create
 
+## 0.6.0
+
+### Minor Changes
+
+- Scaffolded `static` and `emdash` projects now ship neutral placeholder wireframe images under
+  `src/assets/placeholder/` (square, portrait, landscape; SVG + PNG) for layout work before real
+  imagery exists. Delete the directory once real assets land.
+
+## 0.5.0
+
+### Minor Changes
+
+- **The framework now says out loud which patterns are foundational, and reports it when you
+  reach past them.** From repeated downstream reports: sites were inventing a `.wrap` class and
+  using it everywhere instead of `.centered`, and `.subgrid` — the class for any set of cards —
+  was going essentially unused. Neither failure is visible in a build: every class involved is
+  real, nothing errors, and the page renders.
+
+  **`.subgrid` was missing from the generated class reference entirely.** So was `.cluster`, and
+  so was `.region`. `vitops docs classes` is the doc an agent is told to fetch for "which class
+  do I apply", and the framework's answer for a set of cards was not in it — which is most of why
+  it never got used. All three are now documented, along with `grid-auto`, and the reference opens
+  with a **Foundations** section that states the six substitutions as
+  _temptation → what to write instead_ rather than as a vocabulary list. The same table is now in
+  the shipped agent skill and in the `@getvitops/create` template's `AGENTS.md`, because a pointer
+  to a doc only helps someone who already suspects there is something to look up. (`css`/`bricks`
+  and `tailwind` alike — this is documentation and the `TIERS` manifest, not emitted CSS.)
+
+  **`vitops lint` gained three reuse rules and a markup pass.** The existing `.centered` rule only
+  fired when the hand-written CSS already referenced `--width-measure`, which is precisely the
+  author who was never going to hand-roll a container. It now also catches a page-scale
+  `max-width` (≥ 48rem, or a `ch` reading measure) with auto margins, and a
+  container-shaped class name — `wrap`, `wrapper`, `container`, `inner`, `shell`, … — carrying any
+  width cap at all. Reading the cap out of `min()` / `clamp()` too. New rules report a
+  hand-written `repeat()` grid as `.subgrid` (or `.grid-auto`), and a new **markup** pass reports a
+  repeated card set laid out without either — a loop that renders a card, or three or more cards
+  written out. That last one is the only check that can see this drift at all, since a card list
+  built from utility classes contains no bad class and no hand-written CSS.
+
+  All of these are `suggestion` severity, so they do not fail your build unless you pass
+  `--strict`. They found five real instances in this repo's own docs site.
+
+  **`vitops lint [files...]`** now takes explicit paths instead of scanning `--src`, so it can be
+  wired into a pre-commit hook — `vp`'s `staged` key appends the staged files to whatever it runs,
+  and a command that refused positionals could not be put in the one place the feedback lands at
+  the moment the code is written. Unreadable and non-source paths are skipped rather than fatal. The
+  `@getvitops/create` emdash template wires it up with `--strict` and adds a `lint:design` script.
+
+  **Two answers for "the whole card is a link", because one cannot exist.** Reported downstream:
+  agents dislike the `<li>` wrapper when a card is a link and write `<li><a class="card">` instead.
+  That shape is **wrong in a way that renders fine**, which is why it survives review — the `<li>`
+  is the grid item, so the anchor is an ordinary block inside it and the tranches within the anchor
+  never reach the parent's shared row lines. The alignment `.subgrid` exists for silently does not
+  happen, and the anchor does not fill the cell either. Putting the anchor in the grid's place
+  (`<ul><a></ul>`) is invalid HTML, so there was genuinely no correct shape to reach for.
+
+  There are now two, and they trade against each other because **no CSS-only technique can make a
+  whole card clickable and leave its text selectable** — a transparent overlay necessarily receives
+  the pointer-drag:
+
+  | Want                                     | Use                                         |
+  | ---------------------------------------- | ------------------------------------------- |
+  | zero JS, whole card clickable            | `.stretched-link` — **text not selectable** |
+  | selectable text **and** a clickable card | `<Cards>` / `<wc-cards>` — needs JS         |
+
+  `.stretched-link` goes on a link inside the card; its `::after` covers the card.
+  **`<wc-cards>` is a new tier-2 element** that adds no overlay and instead tells a click apart from
+  the end of a drag, so text selection survives. Its fallback is the card's own link, fully usable
+  with no JS, and the pointer cursor is applied by the element — so the affordance never appears
+  without the behaviour. `<Cards>` emits it for you. They are alternatives, never layered: with an
+  overlay present the JS has nothing to do, and `vitops lint` reports the combination. (All formats
+  — pattern partials, deliberately not `utilities.css`, which the tailwind format skips on the
+  invariant that everything left in it is a name Tailwind ships itself.)
+
+  ### Breaking
+  - **`<Subgrid />` renders its slot verbatim — author the `<li>` items yourself.**
+
+    ```diff
+      <Subgrid>
+    -   <article class="card">…</article>
+    +   <li class="card subgrid-card">…</li>
+      </Subgrid>
+    ```
+
+    It used to parse the slotted HTML and rebuild each child as an `<li>`, carrying over only
+    `class` and `style`. That existed solely because a `<ul>` may contain nothing else, and it cost
+    more than it bought: the child's tag was discarded, `id`/`data-*`/`aria-*` were silently
+    dropped, and `href` could not survive at all. Nothing is copied now, so nothing is lost. `as`
+    picks the container (`ul` by default, `ol`, `div`), and all other props are forwarded — they
+    were previously discarded, including `role`.
+
+  - **`<Subgrid />` and `<Tree />` now emit `role="list"`,** as does the Bricks `sitenav` element.
+    `list-style: none` stops Safari + VoiceOver announcing a `<ul>` as a list, so every marker-less
+    framework list was silently losing the semantics its `<ul>` was chosen for. If you hand-write
+    `.subgrid`, `.list`, `.facet-list`, `.nav-items`, `.collapse-menu` or `.tree` markup, add
+    `role="list"` yourself — the framework cannot add it to markup it does not render, and each
+    partial now says so at the `list-style` reset.
+  - **`<Cards />` no longer adds `class="card"` to slotted children,** because it no longer parses
+    them. Write the class on the item. It now emits `<wc-cards>` around a `<Subgrid>`, which is what
+    makes the whole card clickable — and like `<Tree />`, **it emits its own element, so do not wrap
+    it in `<wc-cards>` yourself.** It also previously passed a `role="list"` that `<Subgrid>` silently
+    discarded, so that never took effect.
+  - **`.subgrid-card` now sets `position: relative`**, so `stretched-link` inside it needs no extra
+    class. If you were absolutely positioning a descendant of a `.subgrid-card` against an ancestor
+    _outside_ that card, it will now resolve against the card. Move the positioning context
+    explicitly. (`css`/`bricks`/`tailwind` — the pattern partial is inlined into all three.) Not
+    reachable by `vitops lint --fix`: the fix depends on which ancestor you meant, which the
+    linter cannot know.
+
+  ### Fixed
+  - **`packages/generator/src/docs.ts` contained a literal NUL byte** (`CODE_SLOT`, written as the
+    raw character rather than an escape). libmagic classified the file as `data` rather than text, so
+    grep and ripgrep treated the largest doc emitter in the repo as **binary and silently skipped
+    it** — every search for a string in it returned nothing, with no error. It is now written as the `\u0000` escape.
+    Behaviour is identical; the file is searchable.
+  - **`.grid-auto` is documented.** It was a real framework class for auto-fit card grids with no
+    entry in the class reference, so the honest alternative to `subgrid` was as invisible as
+    `subgrid` itself.
+  - **`.raised` replaces the advice to use `.relative` above a `stretched-link` overlay**, which
+    could not work: a positioned element at `z-index: auto` does not rise above an explicit
+    `z-index` regardless of DOM order, so a second link or button in the card stayed underneath and
+    unclickable. `.raised` sets both, against the same `--z-tier-raised` token the overlay now uses
+    instead of a hard-coded `1`.
+
 ## 0.4.0
 
 ### Minor Changes
@@ -111,15 +235,15 @@
   which `@getvitops/astro` re-exports wholesale. So from `astro.config.mjs`:
 
   ```js
-  import { generateIconInclude } from '@getvitops/astro';
-  import icon from 'astro-icon';
+  import { generateIconInclude } from "@getvitops/astro";
+  import icon from "astro-icon";
 
   integrations: [
     icon({
       include: generateIconInclude({
-        ui: 'fa7-solid',
-        brand: 'simple-icons',
-        semantic: ['menu', 'close', 'search', 'github'],
+        ui: "fa7-solid",
+        brand: "simple-icons",
+        semantic: ["menu", "close", "search", "github"],
       }),
     }),
   ];

package/README.md

@@ -73,6 +73,13 @@ provisions the D1/R2 resources on first deploy).
 Template dependencies must use concrete npm ranges (no `workspace:*` /
 `catalog:` — the scaffolded project lives outside this monorepo).
 
+`assets/` (this package root, unpublished) is the source of truth for
+placeholder imagery shared across templates — `vp create` copies only the
+one directory a template names, so there's no step that could copy a
+sibling `assets/` for you. Mirror any new file into each template's
+`src/assets/placeholder/` by hand; `templates.test.ts` asserts every mirror
+stays byte-identical to the source.
+
 ## Changelog
 
 This package's history: [`CHANGELOG.md`](./CHANGELOG.md) (shipped in the npm tarball, so it

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@getvitops/create",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Project templates for the Vitops design system — scaffold wired-up sites with `vp create @getvitops`.",
+  "homepage": "https://docs.vitops.ca",
+  "bugs": "https://github.com/getvitops/design-system/issues",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getvitops/design-system.git",
+    "directory": "packages/create"
+  },
   "files": [
     "templates",
     "CHANGELOG.md"
@@ -12,10 +19,18 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "^4.1.9"
+    "vitest": "4.1.9"
+  },
+  "engines": {
+    "node": ">=24"
   },
   "createConfig": {
     "templates": [
+      {
+        "name": "static",
+        "description": "Static Astro website on Cloudflare Workers static assets with the Vitops design system pre-wired",
+        "template": "./templates/static"
+      },
       {
         "name": "emdash",
         "description": "EmDash CMS website on Cloudflare Workers (D1 + R2) with the Vitops design system pre-wired",

package/templates/emdash/.env

@@ -0,0 +1 @@
+CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

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

@@ -0,0 +1,12 @@
+# Runs on every PR: typecheck + design-lint + build. deploy-dev.yml /
+# deploy-prod.yml call the same reusable `site-ci.yml` themselves before they
+# deploy, so this is what gives a PR the identical signal before it's even
+# merged to `dev` — a broken build never reaches the dev worker.
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  ci:
+    uses: getvitops/design-system/.github/workflows/site-ci.yml@v1

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

@@ -3,6 +3,11 @@
 # `dev` is the integration branch — every push here refreshes the review site.
 # Promote to production with the "Promote dev → main" workflow (promote.yml).
 #
+# Deploys via the vitops toolchain's reusable EmDash deploy workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-deploy-emdash.yml
+# for what it does. Pinned to @v1 so a fix there reaches this repo without a
+# manual re-paste; bump the tag deliberately if you want to pick up a change.
+#
 # Required repo secrets:
 #   CLOUDFLARE_API_TOKEN   — token with Workers + D1 + R2 edit on this account
 #   CLOUDFLARE_ACCOUNT_ID  — the Cloudflare account id
@@ -14,28 +19,21 @@ on:
   push:
     branches: [dev]
 
-permissions:
-  contents: read
-
 concurrency:
   group: deploy-dev
   cancel-in-progress: true
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
-    environment: dev
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - name: Build + deploy dev worker
-        run: pnpm run deploy:dev
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          DEV_D1_ID: ${{ secrets.DEV_D1_ID }}
+    uses: getvitops/design-system/.github/workflows/site-deploy-emdash.yml@v1
+    with:
+      environment: dev
+      is-dev: true
+      # Set this to your dev worker's URL (or dev.<domain>) once known, so a
+      # bad migration fails the deploy instead of surfacing to the first
+      # visitor — see the reusable workflow's docblock.
+      health-check-url: ''
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      DEV_D1_ID: ${{ secrets.DEV_D1_ID }}

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

@@ -1,36 +1,32 @@
 # Deploys `main` to production.
 # `main` should be branch-protected — it then only advances via the Promote
-# workflow (promote.yml), so a push here always represents promoted code.
+# workflow (promote.yml), so a push here always represents promoted code. The
+# `production` GitHub Environment (set up by `scripts/init-github.mjs`) has
+# required reviewers restricted to admins, so this PAUSES for approval before
+# deploying.
 #
-# Required repo secrets:
-#   CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
+# Deploys via the vitops toolchain's reusable EmDash deploy workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-deploy-emdash.yml
+#
+# Required repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
 name: Deploy prod
 
 on:
   push:
     branches: [main]
 
-permissions:
-  contents: read
-
 concurrency:
   group: deploy-prod
   cancel-in-progress: false
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
-    environment: production
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          cache: pnpm
-      - run: pnpm install --frozen-lockfile
-      - name: Build + deploy prod worker
-        run: pnpm run deploy
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+    uses: getvitops/design-system/.github/workflows/site-deploy-emdash.yml@v1
+    with:
+      environment: production
+      is-dev: false
+      # Set this to your production URL once known.
+      health-check-url: ''
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

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

@@ -2,48 +2,20 @@
 # Opens a PR from dev into the protected `main` branch and enables auto-merge;
 # the merge triggers Deploy prod.
 #
-# Branch protection on `main` means the merge only completes when its rules are
-# satisfied. Choose ONE:
-#   (a) let a human approve the PR (required reviews) — safest, full audit trail;
-#   (b) set repo secret PROMOTE_TOKEN to a PAT / GitHub App token allowed to
-#       bypass protection, for hands-off promotion.
-# The default GITHUB_TOKEN cannot approve its own PR, so with required reviews
-# the PR waits for a human — which is usually what you want for a prod promotion.
+# Deploys via the vitops toolchain's reusable promote workflow — see
+# https://github.com/getvitops/design-system/blob/main/.github/workflows/site-promote.yml
+# for the branch-protection / PROMOTE_TOKEN options.
 #
-# Schema/content promotion is deliberately NOT here — the content model lives in
-# the EmDash database, not git. Apply schema changes to prod via the admin or
-# the site's MCP server, additive changes before the code deploy that uses
+# Schema/content promotion is deliberately NOT here — the content model lives
+# in the EmDash database, not git. Apply schema changes to prod via the admin
+# or the site's MCP server, additive changes before the code deploy that uses
 # them, removals after the code that stops using them.
 name: Promote dev → main
 
 on:
   workflow_dispatch:
 
-permissions:
-  contents: write
-  pull-requests: write
-
 jobs:
   promote:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Open promotion PR and enable auto-merge
-        env:
-          GH_TOKEN: ${{ secrets.PROMOTE_TOKEN || github.token }}
-        run: |
-          set -euo pipefail
-          if gh pr view dev --base main --json number >/dev/null 2>&1; then
-            echo "Promotion PR already open; ensuring auto-merge is enabled."
-          else
-            # printf, not a multi-line string: an unindented continuation line
-            # would end this YAML block and break the whole workflow file.
-            gh pr create --base main --head dev \
-              --title "Promote dev → main" \
-              --body "$(printf '%s\n\n%s' \
-                "Automated code promotion from \`dev\`. Merging deploys to production." \
-                "Remember: schema/content changes live in the EmDash database, not git — promote them separately if this release changes the content model.")"
-          fi
-          gh pr merge dev --auto --merge
+    uses: getvitops/design-system/.github/workflows/site-promote.yml@v1
+    secrets: inherit

package/templates/emdash/.mcp.json

@@ -7,6 +7,10 @@
     "emdash-docs": {
       "type": "http",
       "url": "https://docs.emdashcms.com/mcp"
+    },
+    "semrush": {
+      "type": "http",
+      "url": "https://mcp.semrush.com/v1/mcp"
     }
   }
 }

package/templates/emdash/.nvmrc

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

package/templates/emdash/AGENTS.md

@@ -7,6 +7,10 @@ styled by the Vitops design system.
   (colors, type, spacing, patterns, animations). Never edit
   `src/styles/tailwind.css` — it is generated from the JSON by the
   `vitops()` integration on every dev/build and is gitignored.
+- `src/assets/placeholder/` holds neutral wireframe stand-ins (square,
+  portrait, landscape; SVG + PNG) for layout work before real imagery
+  exists. Delete the directory once real assets land — it's separate from
+  `src/assets/logo.svg`, the actual brand asset.
 - Content lives in the EmDash database, not in the repo. Query it with
   `getEmDashCollection` / `getEmDashEntry` from `emdash`; render Portable Text
   with `<PortableText />` from `emdash/ui` (the Vitops blocks from
@@ -20,6 +24,49 @@ styled by the Vitops design system.
 - Prefer framework CSS classes (utilities, patterns, type roles like
   `font-heading`) over bespoke CSS. Run `npx vitops agents` to append the
   full generated class-vocabulary reference to this file.
+- **Layout foundations — these are the answer, not a starting point.** Six
+  substitutions carry the structure of nearly every page:
+  | About to write… | Write instead |
+  | --- | --- |
+  | a `wrap`/`wrapper`/`container`/`inner` class | **`centered`** |
+  | `max-width` + `margin-inline: auto` | **`centered`** |
+  | `padding-block` on a section | **`region`** |
+  | margins between headings/paragraphs/lists | **`rhythm`** |
+  | `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`** |
+  | `repeat(auto-fit, minmax(…))` | **`grid-auto`** |
+  | `display: flex` + `gap` for a row of controls | **`cluster`** |
+
+  `centered` is a grid of _named tracks_, not a max-width box — a child widens
+  itself with `breakout`/`spotlight`/`fullbleed` without the parent knowing, which
+  is the thing a bespoke `.wrap` can never do. **More than one card means
+  `subgrid`**: a plain grid aligns the outer boxes but not the tranches inside
+  them, so headings and CTAs land at different heights across the set. Write
+  `<ul class="subgrid subgrid-cols-3" role="list">` with
+  `<li class="card subgrid-card">` items, or `<Subgrid />` (which renders the slot
+  verbatim — author the `<li>`s yourself; it adds `role="list"` for you, and a
+  hand-written one needs it because a marker-less `<ul>` stops being announced as a
+  list in Safari).
+
+  **When the whole card is a link the card is still the item**, and pick by whether
+  the card's text must stay selectable: `stretched-link` on a link inside it is
+  zero-JS but kills text selection, while `<Cards>` (which wraps the list in
+  `<wc-cards>`) keeps selection and falls back to that same link with no JS. Never
+  both — the overlay wins and the JS never runs. Never `<li><a class="card">`: the
+  `li` is the grid item, so the anchor's tranches never align and it does not fill
+  the cell; it renders fine, which is why it keeps getting written.
+
+  `npm run lint:design` reports all of these, and the pre-commit hook fails on them
+  — the fix is the class, not a justification for the CSS.
+
+- **Prerender by default.** `output: 'server'` is required (the admin, media/API
+  routes, preview and scheduled publishing need a server), so prerendering is
+  opt-in per route: put `export const prerender = true` on every page that
+  doesn't need per-request data, and give dynamic routes a `getStaticPaths()`
+  that queries the collection at build time. A route with no `prerender` export
+  is re-rendered for every visitor on every request. The cost is that a
+  prerendered page reflects the database as of the last build, so an admin
+  publish needs a redeploy — leave a route server-rendered only where that is
+  unacceptable (preview, personalised content, must-be-live-in-seconds).
 - The Worker cron trigger in `wrangler.jsonc` drives scheduled publishing —
   don't remove it.
 - Hosting (adapter + EmDash database/storage) comes from `vitopsHosting()`

package/templates/emdash/README.md

@@ -16,6 +16,10 @@ Scaffolded from `vp create @getvitops:emdash`.
 - **`@getvitops/emdash`** — design-system Portable Text blocks in the editor
   slash menu: image compare, copy snippet, banner, disclosure, carousel
 
+`src/assets/placeholder/` ships neutral wireframe images for layout work
+before real imagery exists — delete once real assets land (separate from
+`src/assets/logo.svg`, the brand asset).
+
 ## Local development
 
 ```bash

package/templates/emdash/design-system.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://unpkg.com/@getvitops/generator/schema.json",
+  "$schema": "./node_modules/@getvitops/generator/schema.json",
   "colors": {
     "palette": {
       "brand": { "seed": "#2e9b73" },
@@ -54,7 +54,7 @@
       "p": "1rem",
       "fs": "1rem"
     },
-    "radii": { "pill": "999px", "circle": "50%" },
+    "radii": { "circle": "50%" },
     "groups": {
       "control": {
         "ds": "var(--ds-default)",

package/templates/emdash/package.json

@@ -13,6 +13,7 @@
     "init:hosting": "node scripts/init-hosting.mjs",
     "typecheck": "astro check",
     "build:css": "vitops generate -i design-system.json -f tailwind -o src/styles",
+    "lint:design": "vitops lint -i design-system.json -f tailwind --strict",
     "prepare": "vp config"
   },
   "dependencies": {

package/templates/emdash/scripts/init-github.mjs

@@ -1,15 +1,29 @@
 // One-time GitHub bootstrap: creates a GitHub repo named after this project
-// (package.json name), pushes `main` + `dev`, and makes `dev` the default
-// branch — the shape the deploy workflows expect (deploy-dev on push to dev,
-// deploy-prod on push to main, promote.yml between them).
+// (package.json name), pushes `main` + `dev`, makes `dev` the default branch,
+// and provisions the branch-protection + environment policy the deploy
+// workflows assume (deploy-dev on push to dev, deploy-prod on push to main,
+// promote.yml between them):
+//
+//   - `main` requires a PR + the `ci` status check — it only advances via
+//     promote.yml, never a direct push.
+//   - the `production` GitHub Environment requires review from an admin
+//     collaborator before deploy-prod.yml is allowed to run — this is the
+//     "promoting to prod needs admin sign-off" gate.
+//   - `dev` is left UNPROTECTED on purpose — that's what lets an agent (or
+//     anyone with push access) commit and merge there directly for
+//     integration; only the promotion to `main` is gated.
 //
 //   pnpm run init:github             # private repo (default)
 //   pnpm run init:github -- --public
 //   pnpm run init:github -- --dry-run
 //
-// Idempotent: safe to re-run — existing git repo, commits, dev branch, and
-// origin remote are all left alone. Requires the GitHub CLI (`gh`), logged in
-// (`gh auth login`).
+// Idempotent: safe to re-run — existing git repo, commits, dev branch, origin
+// remote, branch protection and environments are all left alone or updated
+// in place. Requires the GitHub CLI (`gh`), logged in (`gh auth login`).
+//
+// NOTE: branch protection and environment required-reviewers are GitHub
+// Pro/Team features on a PRIVATE repo. Each `gh api` call below prints the
+// manual equivalent and continues rather than aborting when it 403s.
 
 import { execSync, spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
@@ -48,6 +62,26 @@ function run(cmd) {
   }
 }
 
+/**
+ * Like `run`, but for `gh api` calls that provision an org/plan-gated
+ * feature (branch protection, environment reviewers). A 403 there means the
+ * repo's plan doesn't support it — not that the bootstrap failed — so this
+ * prints the manual equivalent and keeps going instead of exiting.
+ */
+function runPolicy(cmd, manualHint) {
+  if (dryRun) {
+    console.log(`[dry-run] ${cmd}`);
+    return;
+  }
+  console.log(`$ ${cmd}`);
+  const result = spawnSync(cmd, { shell: true, encoding: 'utf8' });
+  if (result.status === 0) return;
+  console.warn(
+    `\nWARNING: \`${cmd}\` failed (likely needs GitHub Pro/Team on a private repo).\n` +
+      `Set it up manually instead:\n  ${manualHint}\n`,
+  );
+}
+
 // --- Preflight: gh installed and authenticated -------------------------------
 if (check(['gh', '--version']).status !== 0) {
   console.error('ERROR: the GitHub CLI (`gh`) is required. Install it from https://cli.github.com');
@@ -64,7 +98,7 @@ if (quiet('git rev-parse --is-inside-work-tree') === null) {
 }
 if (quiet('git rev-parse HEAD') === null) {
   run('git add -A');
-  run('git commit -m "Initial commit (scaffolded from @getvitops/create emdash template)"');
+  run('git commit -m "Initial commit (scaffolded from @getvitops/create)"');
 }
 
 // The workflows key off `main`; normalize whatever the initial branch is.
@@ -86,9 +120,58 @@ run('git push -u origin main dev');
 run('gh repo edit --default-branch dev');
 run('git checkout dev');
 
+// --- Policy: protect main, gate production behind admin review --------------
+const nwo = quiet('gh repo view --json nameWithOwner -q .nameWithOwner');
+if (nwo) {
+  runPolicy(
+    `gh api -X PUT repos/${nwo}/branches/main/protection --input - <<'JSON'
+{
+  "required_status_checks": { "strict": true, "contexts": ["ci"] },
+  "enforce_admins": false,
+  "required_pull_request_reviews": { "required_approving_review_count": 1 },
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+JSON`,
+    `Settings → Branches → protect 'main' (require a PR, 1 approval, the 'ci' ` +
+      `status check, no force-push/deletion).`,
+  );
+
+  const admins = quiet(
+    `gh api repos/${nwo}/collaborators?permission=admin -q '[.[].login]' 2>/dev/null`,
+  );
+  const reviewers = admins
+    ? JSON.parse(admins).map((login) => ({ type: 'User', id_or_login: login }))
+    : [];
+
+  runPolicy(
+    `gh api -X PUT repos/${nwo}/environments/production --input - <<'JSON'
+{
+  "reviewers": ${JSON.stringify(reviewers)},
+  "deployment_branch_policy": { "protected_branches": true, "custom_branch_policies": false }
+}
+JSON`,
+    `Settings → Environments → 'production' → require reviewers = your admins, ` +
+      `restrict deployment branches to 'main'. This is the prod-needs-admin-approval gate.`,
+  );
+
+  // `dev` gets an environment too (for the deploy-dev workflow's `environment:
+  // dev` reference), but deliberately no reviewers and no branch restriction —
+  // that's what keeps it open for direct pushes/merges.
+  runPolicy(
+    `gh api -X PUT repos/${nwo}/environments/dev --input - <<'JSON'
+{ "reviewers": [] }
+JSON`,
+    `Settings → Environments → create 'dev' with no required reviewers.`,
+  );
+} else {
+  console.warn('WARNING: could not resolve the repo name-with-owner; skipping policy setup.');
+}
+
 // --- What's left (manual, needs your Cloudflare account) ---------------------
 console.log(`
-Repo ready: main (production) + dev (integration, default branch).
+Repo ready: main (protected, production) + dev (integration, default branch).
 NOTE: the first workflow runs will fail until the secrets below exist.
 
 Next steps:
@@ -97,6 +180,7 @@ Next steps:
   2. Secrets:        gh secret set CLOUDFLARE_API_TOKEN
                      gh secret set CLOUDFLARE_ACCOUNT_ID
                      gh secret set DEV_D1_ID
-  3. Protect main:   Settings → Branches → protect 'main' (require the
-                     promotion PR + review), so prod only ships via promote.yml.
+  3. Verify policy:  Settings → Branches (main protected?) and
+                     Settings → Environments → production (reviewers set?) —
+                     printed above if this ran on a plan that supports them.
 `);

package/templates/emdash/src/assets/placeholder/wireframe-400x400.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="400" height="400" viewBox="0 0 400 400"><rect width="100%" height="100%" fill="#DDDDDD"/><path fill="#999999" d="M87.3 204.72h11.66v-12.54q0-1.77.24-3.92zm17.36 0h4.82v3.79q0 .53-.35.91-.34.39-.98.39h-3.49v9.35h-5.7v-9.35H82.79q-.66 0-1.16-.42-.51-.41-.64-1.02l-.69-3.31 18.16-24.25h6.2zm35.59-4.72q0 5.01-1.08 8.71-1.07 3.69-2.97 6.1-1.89 2.42-4.47 3.59-2.59 1.18-5.58 1.18-3 0-5.55-1.18-2.56-1.17-4.44-3.59-1.88-2.41-2.94-6.1-1.06-3.7-1.06-8.71 0-5.03 1.06-8.72 1.06-3.68 2.94-6.09t4.44-3.59q2.55-1.18 5.55-1.18 2.99 0 5.58 1.18 2.58 1.18 4.47 3.59 1.9 2.41 2.97 6.09 1.08 3.69 1.08 8.72m-6.76 0q0-4.16-.61-6.89t-1.63-4.35q-1.02-1.61-2.35-2.26-1.32-.65-2.75-.65-1.41 0-2.72.65t-2.32 2.26q-1 1.62-1.6 4.35t-.6 6.89.6 6.89 1.6 4.35q1.01 1.61 2.32 2.26t2.72.65q1.43 0 2.75-.65 1.33-.65 2.35-2.26 1.02-1.62 1.63-4.35t.61-6.89m37.5 0q0 5.01-1.08 8.71-1.07 3.69-2.97 6.1-1.89 2.42-4.47 3.59-2.59 1.18-5.58 1.18-3 0-5.55-1.18-2.56-1.17-4.44-3.59-1.88-2.41-2.94-6.1-1.06-3.7-1.06-8.71 0-5.03 1.06-8.72 1.06-3.68 2.94-6.09t4.44-3.59q2.55-1.18 5.55-1.18 2.99 0 5.58 1.18 2.58 1.18 4.47 3.59 1.9 2.41 2.97 6.09 1.08 3.69 1.08 8.72m-6.76 0q0-4.16-.61-6.89t-1.63-4.35q-1.02-1.61-2.35-2.26-1.32-.65-2.75-.65-1.41 0-2.72.65t-2.32 2.26q-1 1.62-1.6 4.35t-.6 6.89.6 6.89 1.6 4.35q1.01 1.61 2.32 2.26t2.72.65q1.43 0 2.75-.65 1.33-.65 2.35-2.26 1.02-1.62 1.63-4.35t.61-6.89m48.84 10.39-3.47 3.42-8.99-8.99-9.06 9.04-3.47-3.42 9.06-9.09-8.64-8.64 3.45-3.44 8.64 8.64 8.58-8.59 3.5 3.45-8.61 8.61zm22.95-5.67h11.66v-12.54q0-1.77.24-3.92zm17.35 0h4.83v3.79q0 .53-.35.91-.34.39-.98.39h-3.5v9.35h-5.69v-9.35h-16.17q-.66 0-1.16-.42-.51-.41-.64-1.02l-.69-3.31 18.15-24.25h6.2zm35.59-4.72q0 5.01-1.07 8.71-1.07 3.69-2.97 6.1-1.89 2.42-4.48 3.59-2.58 1.18-5.57 1.18-3 0-5.56-1.18-2.55-1.17-4.43-3.59-1.89-2.41-2.95-6.1-1.06-3.7-1.06-8.71 0-5.03 1.06-8.72 1.06-3.68 2.95-6.09 1.88-2.41 4.43-3.59 2.56-1.18 5.56-1.18 2.99 0 5.57 1.18 2.59 1.18 4.48 3.59 1.9 2.41 2.97 6.09 1.07 3.69 1.07 8.72m-6.75 0q0-4.16-.61-6.89t-1.63-4.35q-1.02-1.61-2.35-2.26-1.32-.65-2.75-.65-1.41 0-2.72.65t-2.32 2.26q-1.01 1.62-1.6 4.35-.6 2.73-.6 6.89t.6 6.89q.59 2.73 1.6 4.35 1.01 1.61 2.32 2.26t2.72.65q1.43 0 2.75-.65 1.33-.65 2.35-2.26 1.02-1.62 1.63-4.35t.61-6.89m37.49 0q0 5.01-1.07 8.71-1.07 3.69-2.97 6.1-1.89 2.42-4.48 3.59-2.58 1.18-5.57 1.18-3 0-5.56-1.18-2.55-1.17-4.43-3.59-1.89-2.41-2.95-6.1-1.06-3.7-1.06-8.71 0-5.03 1.06-8.72 1.06-3.68 2.95-6.09 1.88-2.41 4.43-3.59 2.56-1.18 5.56-1.18 2.99 0 5.57 1.18 2.59 1.18 4.48 3.59 1.9 2.41 2.97 6.09 1.07 3.69 1.07 8.72m-6.75 0q0-4.16-.61-6.89t-1.63-4.35q-1.02-1.61-2.35-2.26-1.32-.65-2.75-.65-1.41 0-2.72.65t-2.32 2.26q-1.01 1.62-1.6 4.35-.6 2.73-.6 6.89t.6 6.89q.59 2.73 1.6 4.35 1.01 1.61 2.32 2.26t2.72.65q1.43 0 2.75-.65 1.33-.65 2.35-2.26 1.02-1.62 1.63-4.35t.61-6.89"/></svg>