@getvitops/skills 0.0.0-stage → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @getvitops/skills
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- 0a47856: New package `@getvitops/skills`: agent skills for sites built with the toolchain (`custom-blocks`, `content-and-deploys`, `contact-form`, `csp`). The emdash template depends on it and runs `skills experimental_sync` on `prepare`, which links them into `.agents/skills/` and `.claude/skills/`, so they update with `vp update` instead of being copied at scaffold time. Existing sites: `vp add @getvitops/skills && vp add -D skills`, set `prepare` to `vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile`, gitignore the four linked names, and delete the site's own copies of those four skills (the sync never replaces a directory it did not create).
+
+  The emdash template's `AGENTS.md` is shortened to the always-relevant rules. Deploy and content mechanics (where each kind of data is the truth, prerendering, publish-triggered rebuilds, refreshing dev), the contact form, and the CSP move into those skills. Corrects the nesting guidance: a block type with a `portableText` field (such as `vitops_section`) holds other blocks, while `vitops_*` Portable Text blocks do not. Adds guidance for agents to record reusable toolkit gaps in `UPSTREAM.md`. The generated stylesheet is no longer described as always `tailwind.css`.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @getvitops/skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent skills for sites built with the Vitops toolchain. A skill is a `skills/<name>/SKILL.md` an
+agent loads when its `description` matches the task. They are knowledge about the toolkit, so they
+ship here and update with the package instead of being copied into each site at scaffold time.
+
+## Use
+
+```bash
+vp add @getvitops/skills
+vp add -D skills
+vp exec skills experimental_sync -y
+```
+
+`skills experimental_sync` links each skill into `.agents/skills/` (and `.claude/skills/` when
+Claude Code is selected), records them in `skills-lock.json`, and relinks on every run, so
+`vp update` refreshes them. Add it to `prepare` to run it after every install:
+
+```json
+{
+  "scripts": {
+    "prepare": "vp config && skills experimental_sync -y -a claude-code --no-frozen-lockfile"
+  }
+}
+```
+
+`--no-frozen-lockfile` matters on CI: `skills` defaults to a frozen lockfile there, so without it a fresh clone, or any `@getvitops/skills` update, fails the install until `skills-lock.json` is regenerated.
+
+`experimental_sync` is a preview command and may change; pin the `skills` version.
+
+A skill the site installed or wrote itself is never replaced, so a site can override one by name.
+
+## Skills
+
+| Skill                 | Use it for                                                                     |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `custom-blocks`       | Deciding whether a page section needs a new EmDash block type, and building it |
+| `content-and-deploys` | Where content vs code is the truth, prerendering, publish-triggered rebuilds   |
+| `contact-form`        | The `/api/track` route, no-JS behaviour, spam protection, privacy inventory    |
+| `csp`                 | The Report-Only CSP and what to check before enforcing it                      |
+
+The `vitops-design-system` skill still ships with `@getvitops/cli` and is linked by `vitops agents`.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@getvitops/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "description": "Agent skills for sites built with the Vitops toolchain. Installed as a dependency and linked into a project with `skills experimental_sync`, so they update with the package.",
+  "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/skills"
+  },
+  "files": [
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }

package/skills/contact-form/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: contact-form
+description: How the contact form works on this site — the on-demand `/api/track` route, no-JS behaviour, where submissions go, spam protection and Turnstile, and the privacy-policy inventory. Use when adding or changing a form, fixing submissions that don't arrive, setting up notifications, CRM or Turnstile, or touching `src/pages/api/track.ts`.
+---
+
+# Contact form
+
+The `vitops_form` block posts a plain `<form method="post">` to `src/pages/api/track.ts`
+(`prerender = false`, built with `createConversionRoute()`). It is the one on-demand public route,
+and it also answers the conversion beacons.
+
+- **No JavaScript needed.** The route answers a form post with a 303 back to the page plus
+  `?sent=1#form-sent` or `?error=1#form-error`, and the block's two notices are revealed by that
+  fragment. Keep one form per page.
+- **Where submissions go:** `site.notifications.email` (or the primary location's `email`) and
+  `site.crm` when set. **With neither, the route refuses the post** rather than accept a message
+  nobody receives, so set `site.notifications.email` before launch and run `vitops email setup` for
+  its sender domain. A failed CRM write never fails the request; it is stated in the notification
+  email, which is the durability floor.
+- **Spam protection:** a honeypot field, the route's origin / size / per-IP rate checks, and
+  Cloudflare Turnstile once `vitops setup turnstile` has put the public key in
+  `site.security.turnstile.siteKey` and saved the Worker secret `VITOPS_TURNSTILE_SECRET` (never in
+  `site.json`). With a key set the route fails closed if the secret is missing. `TURNSTILE_REQUIRED`
+  in the route (default `true`) makes a token-less post a refusal, which means the form needs
+  JavaScript; set it `false` to keep a no-JS submit working and accept that a bot can then skip the
+  token. Turnstile is category `necessary` (it protects the form being sent), loads only when a
+  visitor first uses the form, and its origin is allowed in the Report-Only CSP in
+  `public/_headers`.
+- **Privacy policy inventory.** `vitops legal` derives "what personal information we collect" from
+  `site.templates` entries of type `form`, not from the editor's block, so a form added in the admin
+  is invisible to it. When you add or change form fields, mirror them in a `site.templates` form
+  entry in `site.json`, or the generated policy under-reports.
+- A field named `phone` submits as `tel` (the route reserves `phone` and `event`).
+- The per-IP rate limit is per Worker isolate; add a KV-backed `RateLimitStore` if you need a
+  fleet-wide one.

package/skills/content-and-deploys/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: content-and-deploys
+description: How content, builds and deploys fit together on this EmDash site — where each kind of data is the source of truth, why pages are prerendered, how a publish reaches the live site, and refreshing the dev database. Use for any deploy or build problem, stale or missing content, "my publish isn't live", scheduled posts, previews, 404s, server islands, or refreshing dev from prod.
+---
+
+# Content and deploys
+
+## Where the truth lives
+
+Truth runs a different direction per kind of data.
+
+| Data                                                        | Truth                         | Moves by                                                                  |
+| ----------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
+| Code, Astro pages, `site.json`, design system, seed, schema | git (`dev`)                   | promote `dev → main`                                                      |
+| Content: entries, media, menus, settings                    | **production** D1/R2          | editors work there; drafts and "Publish changes" are the staging step     |
+| Dev database                                                | disposable copy of production | `scripts/refresh-dev.mjs` / the `site-refresh-dev` workflow, one way only |
+
+The dev site exists to rehearse code and schema changes against real content. Never promote it
+back. The refresh refuses any target not named `*-dev`, and drops every table in its target. It
+copies no sessions (they are in KV). Set `EMDASH_PREVIEW_SECRET` on the dev worker, or prod preview
+links would open drafts there. The dev worker's cron trigger is dropped, so scheduled publishing
+can't be exercised on dev.
+
+## Rendering and freshness: everything is prerendered
+
+`output: 'server'` is still required (the admin, media/API routes and scheduled publishing need a
+Worker), but every public page — `index.astro`, `[...slug].astro`, `404.astro` — has
+`export const prerender = true`, and `[...slug].astro` lists the published `pages` entries in
+`getStaticPaths()`. The HTML is written at build time and served as a static asset; the Worker only
+handles `/_emdash/*` and anything deliberately left on-demand. A route with no `prerender` export is
+re-rendered on every request, so don't leave it off by accident.
+
+- **Where build-time content comes from.** The Cloudflare adapter prerenders against a _local_ D1
+  (`.wrangler/state`), never the deployed one — on a CI runner that is an empty database, which
+  would bake "No home page yet" into every page. `scripts/pull-content.mjs` (the first step of
+  `vpr deploy` and `vpr deploy:dev`) exports production's D1 and loads it locally first. It fails
+  closed: a failed export aborts the deploy rather than publishing an empty site (the one exception
+  is a database that doesn't exist yet, the first deploy, which builds from the seed).
+  `SKIP_PULL_CONTENT=1` skips it.
+- **The local database must be migrated before the build.** The template runs
+  `migrations: { runtime: 'check' }`, so a build against a local database with pending migrations
+  prerenders EmDash's one-line "Database migrations are required" response into every page — and
+  still succeeds. A fresh runner, a first deploy, a `SKIP_PULL_CONTENT=1` build and an **upgrade**
+  deploy (the pull restores production's older schema, and `emdash migrate` only runs after the
+  build) would all publish that. `vitops emdash prepare-db` (`vpr prepare-local-db`, run after the
+  pull by `vpr deploy`, `vpr deploy:dev` and the reusable workflow) starts `astro dev` once, calls
+  EmDash's `dev-bypass` setup (which migrates and applies the seed's sample content) and stops it;
+  `vitops emdash check-prerender` (part of `vpr build`) then fails the build if any prerendered page
+  is not a real HTML page with a title. Run `vpr prepare-local-db` by hand before a first local
+  `vpr build`. It only writes the disposable `.wrangler/state`; the dev administrator it creates is
+  never deployed.
+- **Freshness is a rebuild.** A page reflects production as of the last build, so a publish in the
+  admin has to trigger one (see "Publish-triggered rebuilds").
+- **Scheduled publishes.** The Worker cron trigger in `wrangler.jsonc` (every minute) is what makes
+  content scheduled in the admin publish, and what runs plugin cron and maintenance. Keep it. A
+  scheduled publish changes the database but not the live HTML until a rebuild; whether it fires
+  the publish hook below is unverified, so check before relying on it.
+- **Drafts and previews.** A prerendered page cannot show an unpublished draft, so an admin
+  "Preview" link shows the last published build. If previews matter, add a dedicated on-demand
+  route for them rather than removing `prerender` from the public ones.
+- **Dynamic parts are server islands.** Anything that must be fresh per request goes in its own
+  component rendered with `server:defer` inside the prerendered page; the surrounding HTML stays
+  static. Keep islands rare — each is a Worker request after load.
+- **Unknown URLs.** There is no `Astro.rewrite('/404')`: a slug not listed by `getStaticPaths()` has
+  no route, so Astro serves the prerendered `404.html` with a real 404 status. Rewriting an
+  on-demand route to a prerendered one fails (500), so don't reintroduce it.
+
+## Publish-triggered rebuilds
+
+`.github/workflows/deploy-prod.yml` also runs on a `repository_dispatch` event of type
+`emdash-publish` (it pins `ref` to `main`, because a dispatch runs from the default branch, `dev`).
+Wire an EmDash plugin hook to send it:
+
+```jsonc
+// emdash-plugin.jsonc
+"capabilities": ["content:read", "network:request"],
+"allowedHosts": ["api.github.com"]
+```
+
+```ts
+// src/plugin.ts
+hooks: {
+  'content:afterPublish': async (_event, ctx) => {
+    const token = await ctx.settings.get<string>('githubToken'); // an encrypted plugin setting
+    if (!token || !ctx.http) return;
+    await ctx.http.fetch(`https://api.github.com/repos/${OWNER}/${REPO}/dispatches`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json' },
+      body: JSON.stringify({ event_type: 'emdash-publish' }),
+    });
+  },
+}
+```
+
+The token is a fine-grained GitHub token with `Contents: write` on this repo only, stored as the
+plugin's encrypted setting (a sandboxed plugin can't read Worker environment variables), never in
+the repo. The hook name, capabilities and `ctx.http` / `ctx.settings` calls follow EmDash's plugin
+reference but this exact plugin has not been run against a live site, so treat it as a starting
+point. Two costs: the run goes through the `production` environment, so it **waits for the
+reviewers' approval** like any prod deploy (relax that rule if editors' publishes should go live
+unattended), and bursts of publishes queue behind the `deploy-prod` concurrency group rather than
+cancelling each other. Without the hook, a manual run of **Deploy prod** (or a push to `main`) does
+the same job.

package/skills/csp/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: csp
+description: The Content Security Policy this site ships (Report-Only) and what to check before enforcing it. Use when changing `public/_headers`, adding an embed, tracking snippet or third-party script, turning the CSP on, or seeing CSP reports in the console.
+---
+
+# Content Security Policy
+
+`public/_headers` ships a **`Content-Security-Policy-Report-Only`** header: it logs violations to
+the browser console and blocks nothing, so it can't break a page. Its `script-src` is `'self'` plus
+the SHA-256 of each inline script `<Head />` emits (the colour-scheme bootstrap and the
+consent-gate stub) — no `'unsafe-inline'`. Hashes, not nonces, because prerendered pages have no
+per-request response to put a nonce in. `contentSecurityPolicy()` and `inlineScriptHashes()` from
+`@getvitops/astro` produce the same strings (`templates.test.ts` in the toolchain keeps the file in
+step).
+
+Know what it does not cover before you flip it to enforcing (rename the header to
+`Content-Security-Policy`):
+
+- **`_headers` applies to static assets only.** Worker-rendered responses — the EmDash admin
+  (`/_emdash/*`), its API, anything left on-demand — don't get it. Setting a header there means
+  doing it in code (e.g. Astro middleware calling `contentSecurityPolicy()`), and the admin's own
+  inline scripts and editor HTML would need allowing; leave the admin out of an enforced policy.
+- **Editor-authored HTML blocks are the hard limit.** Any block that lets an editor paste raw HTML
+  or a `<script>` (an embed, a tracking snippet) puts arbitrary inline script on the page, which a
+  hash policy cannot name ahead of time. HTML blocks created in the admin also run JavaScript in a
+  sandboxed iframe, and Astro's `security.csp` blocks their styles and scripts, so don't turn that
+  on without allowing for it. Enforcing a strict policy means removing such blocks or moving embeds
+  to a consent-gated `data-consent` tag whose origin you allow explicitly.
+- **Third-party tags** the consent gate activates need their origins in `script-src` /
+  `connect-src`; anything with `frame` needs `frame-src`.
+- **A server island** (`server:defer`) adds an inline loader script and a request to the Worker;
+  expect a report for the loader until you hash it.
+
+Run the site, browse the pages you ship with the console open, fix or allow what is reported, and
+only then enforce.

package/skills/custom-blocks/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: custom-blocks
+description: Decide whether a page section needs a new EmDash block type, and if so how to name, build, version and retire it. Use before creating, renaming or deleting any block type, any `src/components/blocks/*` renderer, or when asked to "add a block", "make an editable section" or "add a component the editors can place".
+---
+
+# Custom blocks
+
+Pages are composed from **blocks** so non-technical editors can rearrange and edit
+them in the CMS. A new block type is the most expensive way to get a section onto a
+page: it adds a content-model entry, a renderer, a field schema and a migration
+burden, and **a block type cannot be renamed or deleted** once pages use it (see
+"Lifecycle"). So work down this list and stop at the first rung that fits.
+
+## 1. Decision rule
+
+1. **Compose what exists.** The `vitops_*` blocks from `@getvitops/emdash` (cards,
+   carousel, gallery, accordion, details, banner, hero, marquee, image-compare,
+   copy button, action link, …) resolve inside any block type's `portableText` field,
+   so "a section with a heading, intro and then a row of cards" is a section block
+   whose body holds `vitops_cards` — not a new "cards section" type. Check what is
+   installed first: `vp exec vitops docs components` lists every block the toolchain
+   ships and which tier provides it.
+2. **Extend an existing block** if one is close. An extra option (a `variant`
+   select, an optional slot) on a block that already exists is a version bump on that
+   block, not a new type. Prefer this when the new thing is a variation of the same
+   content shape.
+3. **Site-local block type** only when the content shape is specific to this site
+   (a bespoke dashboard mock, an A-versus-B argument with hard-coded figures). Keep
+   the renderer in `src/components/blocks/` and the type name prefixed for the site
+   (see "Naming"). Code-owned widgets expose only a caption field; the numbers live in
+   code, not in the CMS.
+4. **Upstream it** when a second site would plausibly want it. Don't build a
+   generic block here and quietly fork it: raise it against the toolchain
+   (`getvitops/design-system`) with the shape you used, so every site gets it. Until
+   it ships, keep the local version and mark it `local (watch)` in a comment, so it
+   is easy to retire when the real one lands.
+
+A form, a section container, a stats row, a logo grid, a CTA band and a steps list
+are all _generic_ — expect to find them upstream or to upstream them, not to keep
+them local.
+
+## 2. Naming: check the framework's vocabulary first
+
+Block types are permanent, so the name has to be right the first time. Before you
+name one:
+
+- Run `vp exec vitops docs components` and `vp exec vitops docs classes`. If the
+  framework already has a pattern by that name, **use its meaning**: `badge` is a
+  _static_ label; `tag` is a label that may be static or dynamic (editable,
+  dismissable). Never `chip` or `pill`. A block called `chips` that renders badges
+  cost one site a new type, a content migration and a permanently retired type.
+- Prefix site-local types with a short site code (`acme_section`), never `vitops.`
+  — that namespace belongs to the toolchain.
+- Name the thing, not its look: `section`, `steps`, `logos`; not `green-box`.
+
+## 3. Field and renderer conventions
+
+- **Colour: `tone` plus optional `color`.** `tone` takes a **role** name from
+  `site.json`'s `colors.roles` (preferred), falling back to a semantic name
+  (`info` `success` `warning` `danger`); `color` is the escape hatch for a palette
+  hue/step and should be rare — a site that sets it on every item is telling you a
+  role is missing. A select field can only list static options, so either list the
+  roles you actually use or take a validated string. Resolve it in one shared helper
+  (`src/components/blocks/tone.ts`) rather than per block.
+- **Class names cannot be built from field values.** Tailwind only emits classes it
+  can read in source, so `` `bg-${tone}` `` produces nothing. Resolve a tone to CSS
+  custom properties (or a lookup table of whole class names) instead.
+- **Links are `url` fields**, not `string`: EmDash's `url` type accepts site-relative
+  paths. (`string` is a mistake that needs a breaking version to undo.)
+- **Repeater sub-fields are scalar-only** (no `portableText`, no links inside text),
+  so a checklist is one newline-separated `text` field. Don't fight it; rich item
+  bodies need EmDash to lift that limit.
+- **Nesting needs a `portableText` field.** A `vitops_*` Portable Text block holds
+  only scalars and repeaters, so it can't contain blocks. A block _type_ with a
+  `portableText` field can (`vitops_section`'s `body` holds any blocks), so "a
+  section containing stats" is a section whose body holds `vitops_stats`. A flat
+  sequence of siblings works too, but per-section backdrops don't carry across them.
+- **Reach for framework classes** (`centered`, `region`, `rhythm`, `subgrid`,
+  `cluster`, `font-*`, `card`, `badge`, `tag`) in the renderer; run
+  `vpr lint:design` — hand-written layout CSS in a block is the signal that the
+  framework is missing a pattern worth upstreaming.
+- A card title is a heading: render a real `<h2>`–`<h4>` with a level prop, not a
+  styled `<p>`.
+
+## 4. Lifecycle
+
+- **Create** with the schema tools (the `schema_*` actions on the site's MCP server,
+  `/_emdash/api/mcp`) or the admin; commit the matching renderer and the
+  `emdash export-seed` output so a fresh environment gets the same model.
+- **A breaking change is a new version**, not an edit: add the version, migrate the
+  entries that use the old one, then activate it. Two things the tooling does not say:
+  `schema_activate_block_type_version`'s `expectedFingerprint` is the fingerprint of
+  the **currently active** version, not the one you are activating (a mismatch is a
+  `CONFLICT`), and `schema_update_block_type` **replaces the whole `fields` list**, so
+  send every field, not just the changed one.
+- **Migrating content:** `emdash content update` has no `--migrate-blocks` flag; the
+  REST route `PUT /_emdash/api/content/<collection>/<id>` with
+  `{ data, _rev, migrateBlocks: true }` does (it takes Portable Text arrays; the CLI
+  and MCP take Markdown). Updating a published entry stages a **draft** — a separate
+  `content publish` is needed before the live page changes, and (because pages are
+  prerendered) a rebuild after that.
+- **Retiring is not deleting.** A type that was renamed or superseded stays in the
+  database and the seed permanently; keep its renderer mapping old values so existing
+  content still renders, mark it retired, and stop offering it to editors.
+- **Typed fields:** `emdash types` does not type `blocks` fields (they come out as
+  `unknown[]`); hand-write a value type per renderer until EmDash generates it.