@getvitops/create 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @getvitops/create
 
+## 0.7.0
+
+### Minor Changes
+
+- **Breaking (for scaffolds) — both templates now ship `site.json` instead of `design-system.json`.**
+
+  `design-system.json` is deleted from the `static` and `emdash` templates; its contents move under
+  `designSystem.themes.default` inside a new `site.json` (the umbrella `Config`), because a
+  scaffolded config can't merely reference a sibling design-system file — `ConfigSchema` requires
+  `designSystem` and there is no file-level `extends`. `astro.config.mjs`'s `css.input` (and
+  `site.input`, for emdash) now point at `site.json`; so do the `build:css`/`lint:design` scripts.
+
+  **Migration** for a project already scaffolded from an older version of this template: create
+  `site.json` with your existing `design-system.json`'s content under
+  `designSystem.themes.default`, delete `design-system.json`, and update `css.input`/`site.input` in
+  `astro.config.mjs`. Not reachable by `vitops lint --fix` — this is the whole migration.
+
+  Also new in both templates:
+
+  - **`SETUP.html`** — a client-onboarding checklist (styled entirely with the framework's own
+    classes, checkbox state in `localStorage`), generated a stylesheet for via the new
+    `pnpm run sop` script.
+  - **`.agents/skills/setup/SKILL.md`** — lets an AI agent work the same checklist autonomously,
+    stopping only at the steps that genuinely need a human (the Cloudflare API token, the
+    domain cutover, publishing generated legal documents).
+  - `scripts/init-github.mjs` and `scripts/init-hosting.mjs` are deleted; `pnpm run init:github` /
+    `init:hosting` / the new `setup` script now call `vitops setup repo` / `vitops setup hosting`
+    (from `@getvitops/cli`, requires the `minor` release in the same batch as this one) instead of
+    a template-local script, so the same capability now reaches any existing project, not just a
+    fresh scaffold.
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/create",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -19,7 +19,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "4.1.9"
+    "vitest": "4.1.9",
+    "@getvitops/generator": "8.1.0"
   },
   "engines": {
     "node": ">=24"

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

@@ -0,0 +1,61 @@
+---
+name: setup
+description: Work the client-onboarding checklist (SETUP.html) autonomously — GitHub repo + branch policy, hosting resources, Search Console/GCP/ads connections. Use when the user asks to set up, onboard, or provision this project (e.g. "run setup", "onboard this site", "get this ready to deploy"). Never run this as a side effect of unrelated work, and never on your own initiative without the user asking.
+---
+
+# Setup (client onboarding)
+
+`SETUP.html` is the canonical checklist — this skill adds only sequencing,
+gates, and where to stop. It does not restate the steps; read `SETUP.html`
+(or `npx vitops setup --help`) for what each stage actually does and why.
+
+## Steps
+
+1. **Preview the whole sequence first.**
+
+   ```bash
+   npx vitops setup all --dry
+   ```
+
+   Read the plan before doing anything. It names every step it would take and
+   why any step is blocked — a missing credential, a field not yet in
+   `site.json`, GitHub Pro/Team gating branch protection.
+
+2. **Run it.**
+
+   ```bash
+   npx vitops setup all
+   ```
+
+   Re-run `npx vitops setup --check` after each leg rather than retrying on
+   your own judgment — a step already done resolves to a no-op skip, so a
+   second run is safe, and `--check` tells you exactly what still needs doing
+   instead of you guessing from output.
+
+3. **Tick `SETUP.html` boxes only for what you actually completed.** Never
+   check a box for a step marked below as human-only, even if you did
+   everything up to it — the human still has to act.
+
+## Hard stops — ask the human, do not attempt
+
+- **The Cloudflare API token.** No API can create one; there is no command to
+  run. Tell the user to create it at
+  <https://dash.cloudflare.com/profile/api-tokens> (Workers + D1 + R2 edit)
+  and run `gh secret set CLOUDFLARE_API_TOKEN`, then continue.
+- **The domain cutover** (`vitops setup domain`, stage 4b in `SETUP.html`).
+  Uncommenting the custom-domain route and deploying overwrites the zone's DNS
+  record at that instant — it takes an existing live site down. `setup domain`
+  only ever plans and checks this; it never applies it, and neither should
+  you. Report the plan and hand the actual cutover to the user.
+- **Publishing any generated legal document.** `vitops legal` renders a
+  starting point from the config, not a reviewed policy. Generate it, tell the
+  user it needs review, and stop — do not paste it into the admin or commit it
+  yourself.
+
+## If something is blocked
+
+`vitops setup --check` names the field or credential and where to get it —
+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).

package/templates/emdash/AGENTS.md

@@ -3,10 +3,14 @@ styled by the Vitops design system.
 
 ## Ground rules
 
-- `design-system.json` is the single source of truth for the 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.
+- `site.json` is the single source of truth — organization + site facts, and
+  the design system (colors, type, spacing, patterns, animations) under
+  `designSystem.themes.default`. Never edit `src/styles/tailwind.css` — it is
+  generated from `site.json` by the `vitops()` integration on every dev/build
+  and is gitignored. (There is no separate `design-system.json`: a scaffolded
+  config can't merely reference a sibling file, so the token set lives inside
+  `site.json` — see `AGENTS.md`'s "Client onboarding" section in the toolchain
+  repo for why.)
 - `src/assets/placeholder/` holds neutral wireframe stand-ins (square,
   portrait, landscape; SVG + PNG) for layout work before real imagery
   exists. Delete the directory once real assets land — it's separate from
@@ -74,6 +78,10 @@ styled by the Vitops design system.
   d1/r2/sqlite there. Switch targets via `vitopsHosting({ target })` or the
   `HOSTING` env var (see README "Hosting"); the `node` target needs
   `@astrojs/node` + `better-sqlite3` installed first.
+- **`SETUP.html` is the client-onboarding checklist.** When working it via the
+  `.agents/skills/setup/` skill, tick a box only for a step you actually
+  completed — never on the operator's behalf for a step marked human-only
+  (the Cloudflare API token, the domain cutover, publishing legal documents).
 
 ## Branch model
 
@@ -90,12 +98,12 @@ styled by the Vitops design system.
   and obviously unfinished; do not "improve" them into something that reads as
   a finished policy, because the risk here is a plausible-looking document
   getting shipped unread.
-  To replace them properly, write a site config and run
-  `npx vitops legal --format portable-text --out ./legal`, then paste each
-  document's blocks into the page in the admin. That renders a real policy from
-  what the site actually does — the analytics provider it uses, the fields its
-  forms collect, where it deploys — rather than from guesses. It still needs
-  review before launch.
+  To replace them properly, fill in `site.json`'s `organization`/`site.legal`
+  fields and run `npx vitops legal --format portable-text --out ./legal`, then
+  paste each document's blocks into the page in the admin. That renders a real
+  policy from what the site actually does — the analytics provider it uses,
+  the fields its forms collect, where it deploys — rather than from guesses.
+  It still needs review before launch.
 
 ## Docs MCP servers
 
@@ -112,4 +120,4 @@ searching them over pre-trained knowledge for Astro/EmDash questions.
   dev default). Only run when the user asks to set up GitHub.
 - `pnpm run init:hosting` — one-time: provision the hosting platform (dev
   D1/R2 + repo secrets on cloudflare). Only run when the user asks for it.
-- `npx vitops validate design-system.json` — schema-check the design config
+- `npx vitops validate site.json` — schema-check the site config

package/templates/emdash/README.md

@@ -10,9 +10,9 @@ Scaffolded from `vp create @getvitops:emdash`.
 - **Astro** (SSR) on **Cloudflare Workers** — D1 database, R2 media storage
 - **EmDash** — the admin lives at `/_emdash/admin`; content is queried with
   `getEmDashCollection` / `getEmDashEntry` (Astro live content collections)
-- **`@getvitops/astro`** — generates the design-system CSS from
-  `design-system.json` (Tailwind v4 format), generates favicons/PWA assets
-  from `src/assets/logo.svg`, and serves the web-component runtime
+- **`@getvitops/astro`** — generates the design-system CSS from `site.json`
+  (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
 
@@ -42,7 +42,7 @@ Until then the home route shows a friendly empty state. Unknown paths render
 `src/pages/404.astro`.
 
 The two legal pages are placeholders. To generate real ones from what your site
-actually does, describe it in a site config and run:
+actually does, fill in `site.json`'s `organization`/`site.legal` fields and run:
 
 ```sh
 npx vitops legal --format portable-text --out ./legal
@@ -82,22 +82,18 @@ 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:
-
-1. `pnpm run init:github` — creates a GitHub repo named after this project
-   (via the `gh` CLI; `-- --public` for a public repo), commits if needed,
-   pushes `main` + `dev`, and makes `dev` the default branch. Idempotent;
-   `-- --dry-run` previews. Then branch-protect `main` (require the promotion
-   PR + review).
-2. `pnpm run init:hosting` — provisions the hosting platform (after
-   `npx wrangler login`): creates the isolated dev D1 + R2 and sets the
-   `DEV_D1_ID` / `CLOUDFLARE_ACCOUNT_ID` repo secrets. Idempotent;
-   `-- --dry-run` previews.
-3. Create a Cloudflare API token (Workers + D1 + R2 edit —
-   <https://dash.cloudflare.com/profile/api-tokens>; tokens can't be created
-   via CLI) and `gh secret set CLOUDFLARE_API_TOKEN`. Optionally
-   `PROMOTE_TOKEN` (a PAT allowed to bypass protection) for hands-off
-   promotion. The first workflow runs fail until the secrets exist.
+One-time setup — work through the checklist:
+
+```bash
+pnpm run sop && open SETUP.html   # or: xdg-open SETUP.html
+```
+
+It covers host choice, GitHub + branch policy, hosting resources, going live
+safely on `*.workers.dev` before any custom-domain cutover, configuration,
+Search Console/GCP/ads connections, legal documents, and launch gates — one
+command per step. An AI agent can work the same list autonomously via
+`.agents/skills/setup/`; it stops at the steps that genuinely need a human
+(the Cloudflare API token, the domain cutover, publishing legal documents).
 
 `pnpm deploy:dev` reproduces the dev deploy locally: it rewrites the
 adapter-generated wrangler config (`scripts/build-dev-wrangler.mjs`) so the
@@ -146,8 +142,10 @@ and media in the storage backend (bucket/directory copy).
 
 ## The design system
 
-`design-system.json` is the single source of truth for colors, type, spacing,
-shadows, patterns, and animations. The `vitops()` integration regenerates
+`site.json`'s `designSystem.themes.default` is the single source of truth for
+colors, type, spacing, shadows, patterns, and animations — there is no
+separate `design-system.json`, since a scaffolded config can't merely
+reference a sibling file. The `vitops()` integration regenerates
 `src/styles/tailwind.css` from it on dev/build (the file is gitignored — edit
 the JSON, not the CSS). `Layout.astro` imports the stylesheet so the admin
 routes stay unstyled by it.
@@ -155,27 +153,27 @@ routes stay unstyled by it.
 Useful commands (via `@getvitops/cli`):
 
 ```bash
-npx vitops validate design-system.json   # check the config against the schema
-npx vitops agents                        # write the design-system reference into AGENTS.md
-pnpm build:css                           # regenerate the CSS manually
+npx vitops validate site.json   # check the config against the schema
+npx vitops agents               # write the design-system reference into AGENTS.md
+pnpm build:css                  # regenerate the CSS manually
 ```
 
 ## Project map
 
-| Path                             | Purpose                                                           |
-| -------------------------------- | ----------------------------------------------------------------- |
-| `design-system.json`             | Design tokens + patterns → generated CSS                          |
-| `seed/seed.json`                 | First-boot content model + starter content                        |
-| `src/worker.ts`                  | Worker entry (fetch + EmDash scheduled handler)                   |
-| `src/live.config.ts`             | Astro live content collections wiring for EmDash                  |
-| `src/layouts/Layout.astro`       | Site chrome: EmDash + Vitops head tags, nav from the CMS menu     |
-| `src/pages/index.astro`          | Home — renders the `home` page entry                              |
-| `src/pages/[...slug].astro`      | Catch-all — renders any `pages` entry at its slug                 |
-| `src/pages/404.astro`            | Not-found page (the catch-all rewrites here)                      |
-| `wrangler.jsonc`                 | Cloudflare bindings (D1/R2) + cron trigger                        |
-| `scripts/build-dev-wrangler.mjs` | Rewrites the built wrangler config for the isolated dev worker    |
-| `scripts/init-github.mjs`        | One-time: create + push the GitHub repo (`pnpm run init:github`)  |
-| `.github/workflows/`             | deploy-dev (push to `dev`), deploy-prod (push to `main`), promote |
-| `.agents/skills/promote/`        | Agent skill: dispatch the dev → main promotion                    |
-| `.mcp.json`                      | Astro + EmDash docs MCP servers for coding agents                 |
-| `.claude/hooks/`                 | Claude Code web: Node 24 + pnpm setup on session start            |
+| Path                             | Purpose                                                                                    |
+| -------------------------------- | ------------------------------------------------------------------------------------------ |
+| `site.json`                      | Org + site config; design tokens/patterns at `designSystem.themes.default` → generated CSS |
+| `seed/seed.json`                 | First-boot content model + starter content                                                 |
+| `src/worker.ts`                  | Worker entry (fetch + EmDash scheduled handler)                                            |
+| `src/live.config.ts`             | Astro live content collections wiring for EmDash                                           |
+| `src/layouts/Layout.astro`       | Site chrome: EmDash + Vitops head tags, nav from the CMS menu                              |
+| `src/pages/index.astro`          | Home — renders the `home` page entry                                                       |
+| `src/pages/[...slug].astro`      | Catch-all — renders any `pages` entry at its slug                                          |
+| `src/pages/404.astro`            | Not-found page (the catch-all rewrites here)                                               |
+| `wrangler.jsonc`                 | Cloudflare bindings (D1/R2) + cron trigger                                                 |
+| `scripts/build-dev-wrangler.mjs` | Rewrites the built wrangler config for the isolated dev worker                             |
+| `SETUP.html`                     | Client-onboarding checklist — run `pnpm run sop` first (see "One-time setup")              |
+| `.github/workflows/`             | deploy-dev (push to `dev`), deploy-prod (push to `main`), promote                          |
+| `.agents/skills/promote/`        | Agent skill: dispatch the dev → main promotion                                             |
+| `.mcp.json`                      | Astro + EmDash docs MCP servers for coding agents                                          |
+| `.claude/hooks/`                 | Claude Code web: Node 24 + pnpm setup on session start                                     |