@getvitops/skills 0.1.0-alpha.0 → 0.1.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @getvitops/skills
 
+## 0.1.0-alpha.2
+
+### Minor Changes
+
+- 6b5ea17: **Leaner scaffolded `AGENTS.md`, and skills named by scope.** The EmDash template's `AGENTS.md` went from 212 to about 70 lines and the static one from 141 to about 50: only always-true rules stay (source of truth, generated CSS, branches, `vp`/`vpr`, where to look), and task-specific guidance moved into skills loaded when the task matches.
+
+  - **Breaking, `@getvitops/skills`: skills are renamed by scope.** `custom-blocks` → `emdash-custom-blocks`, `content-and-deploys` → `emdash-content-and-deploys`, `contact-form` → `emdash-contact-form`, `csp` → `vitops-csp`, `see-the-page` → `vitops-see-the-page`, `ads` → `vitops-ads`. `emdash-*` skills only apply to an EmDash site; `vitops-*` apply anywhere, and both prefixes are reserved for toolkit skills. New: `emdash-building-pages` (blocks, nesting, page opener, widget areas, escape hatches, layout primitives, `site.chrome`) and `vitops-consent` (split out of `vitops-design-system`, whose description and body now cover styling and tokens only). Existing sites: run `vp install` so `skills experimental_sync` relinks, and replace the per-skill `.agents/skills/<name>` / `.claude/skills/<name>` lines in `.gitignore` with `.agents/skills/vitops-*`, `.agents/skills/emdash-*` and the same two under `.claude/skills/`. A site's own skill must not use those prefixes.
+  - **`vitops agents sync`:** the block lists only skills that apply (a project without `emdash` in its dependencies gets no `emdash-*` ones, and they are not linked), summaries are cut at a clause rather than with an ellipsis, the pointer says `vp exec vitops docs`, and the version stamp is gone so the file no longer changes on every CLI bump.
+  - **`@getvitops/create`:** both templates ship the trimmed `AGENTS.md`; the project-naming steps moved into the `setup` skill and EmDash 1.x behaviours, legal-page replacement and the audit prerequisites into `emdash-content-and-deploys`. Existing sites: nothing to change beyond the skill rename; delete the sections you no longer need.
+
+- bb61a35: **Call tracking numbers: show an ad visitor a number that attributes the phone call.** Two additive config blocks, no CSS, no breaking change — all formats unaffected.
+
+  - **`site.ads.google.callTracking`** — Google Ads _website call conversions_. `{ label, number, cache? }` makes the consent-gated Google tag fetch a Google forwarding number (Canada supported) and swap it in for visitors who arrived from a Google ad. Google replaces text only, so the capture script also rewrites the matching `tel:` href. Needs `pixelId` and `site.tracking.enabled`; rejected on any other platform (only Google can put a number on the website — Microsoft's exist only inside the ad, in the US/UK/AU).
+  - **`site.tracking.phoneNumbers`** — per-platform numbers for every other platform: the real `number`, `sources` keyed by `site.ads` platform (plus `default-paid`), and an informational `provider`. You provision the numbers with a call-tracking service (Twilio, CallRail, …). The landing URL decides first, then the `_ac` cookie, so a visitor who declines `marketing` sees a tracking number on the landing page only. An organic visitor is never swapped, and the server-rendered HTML always carries the real number.
+  - The `tel:` tap beacon now carries which number was shown (`phoneSource`), and the conversion notification says so.
+  - `vitops ads lint` flags a call-tracking provider that is not in `site.legal.privacyPolicy.processors`, and notes that `callTracking` plus `conversionLabel.call` can count one call twice (make one secondary in Google Ads).
+  - `@getvitops/utils/tracking` exports the pure `selectPhoneNumber()` and helpers; the capture script mirrors it and `tracking.test.ts` pins the two.
+  - `@getvitops/skills` gains a **`vitops-ads`** skill (overview plus a `call-tracking.md` topic). The templates gitignore synced skills by prefix (`vitops-*`, `emdash-*`), so it needs no `.gitignore` line of its own.
+
+  `@getvitops/core`, `@getvitops/vite` and `@getvitops/emdash` — no consumer-facing change in these packages.
+
+- 7069f93: **Agents now look at rendered pages with `playwright-cli`.** Both templates add `playwright` as a devDependency, run `playwright cli install --skills` from `prepare` (writing the upstream command reference to `.claude/skills/playwright-cli/`), ship `.playwright/cli.config.json`, allow `pnpm exec playwright cli`, and deny `mcp__claude-in-chrome__*` and `mcp__playwright__*` in `.claude/settings.json`. `@getvitops/skills` adds a short `see-the-page` skill (serve first, snapshot before screenshot, dark mode, mobile, no-JS) that defers to the upstream one. Existing sites: add `playwright` as a devDependency, extend `prepare`, and copy the settings. `vitops audit` now needs only `@axe-core/playwright lighthouse` added.
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- 322dd6a: Tooling fixes from the vitops.ca build (findings 14, 23, 24, 25).
+
+  - **`vitops emdash form-template --from <seed.json | export.json> [--name contact] [--site site.json] [--dry]`** copies a `vitops_form` block into `site.templates` with the renderer's own field resolver, so the generated privacy policy and `check-prerender` know what the form collects. A re-run is a no-op, and the result is validated before it is written.
+  - `site.templates` form fields accept `checkboxes` (the block's spelling), and the template union now discriminates on `type`, so a bad entry is reported at its path instead of as a bare "Invalid input".
+  - **`prepare-db` fails fast and says why.** It validates `site.json` before starting the dev server, writes the server's output to `.vitops/prepare-db.log`, stops waiting as soon as the log shows an error, and prints the log's tail on failure, instead of waiting out a five-minute timeout with nothing to read.
+  - **`check-prerender`** skips the toolkit's own assets under `vitops/` (no more "0 h1" for the theme-editor page) and warns when the sitemap lists URLs the build produced no page for (a collection with no `urlPattern` is listed as `/<collection>/<slug>` while the site serves `/<slug>`).
+  - The emdash template ignores the duplicate `pnpm-@getvitops+skills-*` links `skills experimental_sync` leaves beside each skill; the `content-and-deploys` skill explains the sitemap warning.
+
 ## 0.1.0-alpha.0
 
 ### Minor Changes

package/README.md

@@ -28,15 +28,20 @@ Claude Code is selected), records them in `skills-lock.json`, and relinks on eve
 
 `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.
+A skill the site installed or wrote itself is never replaced, so a site can override one by name. The `vitops-` and `emdash-` prefixes are reserved for toolkit skills (the templates gitignore them by prefix), so name a site's own skill without them.
 
 ## 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                      |
+Names carry scope: `emdash-*` only apply to an EmDash site, `vitops-*` to any site built with the toolchain. `vitops agents sync` lists only the ones that apply.
+
+| Skill                        | Use it for                                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------------------------- |
+| `emdash-custom-blocks`       | Deciding whether a page section needs a new EmDash block type, and building it              |
+| `emdash-content-and-deploys` | Where content vs code is the truth, prerendering, publish-triggered rebuilds                |
+| `emdash-contact-form`        | The `/api/track` route, no-JS behaviour, spam protection, privacy inventory                 |
+| `vitops-csp`                 | The Report-Only CSP and what to check before enforcing it                                   |
+| `vitops-ads`                 | Ad pixels, conversions, attribution and call-tracking numbers (`site.ads`)                  |
+| `vitops-see-the-page`        | Looking at a rendered page with `playwright-cli`                                            |
+| `emdash-building-pages`      | Authoring pages from `vitops_*` blocks: nesting, page opener, escape hatches, `site.chrome` |
 
 The `vitops-design-system` skill still ships with `@getvitops/cli` and is linked by `vitops agents`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/skills",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "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",

package/skills/emdash-building-pages/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: emdash-building-pages
+description: Use when authoring or changing a page's layout or content on this EmDash site — composing `vitops_*` blocks, nesting sections, page openers and heroes, widget areas, block `theme`/`anchor`/`className`/`style`, heading levels, card grids, or the header (`site.chrome`, `<Masthead>`, mega menu panels).
+---
+
+# Building pages
+
+Reference, rendered from this project: `vp exec vitops docs blocks` (every block and field),
+`vp exec vitops docs components` (every pattern, which tiers provide it and which block renders it),
+`vp exec vitops docs classes` (class vocabulary), `vp exec vitops docs config` (`site.chrome`).
+
+## Blocks
+
+- The editor's insert menu offers the `vitops_*` blocks.
+- **Nesting.** A block type with a `portableText` field, such as `vitops_section`, holds other
+  blocks. A `vitops_*` block holds only scalar fields and repeaters (cards, gallery images,
+  accordion items, slides), so it can't. EmDash's built-in `columns` doesn't render `vitops_*`
+  children. For layout, nest in a section, use a `blocks` field, or hand-write the template with
+  `@getvitops/astro` components (`Subgrid`, `Cards`, `Carousel`, …).
+- **Page opener.** Use `vitops_section` at heading level 1 with its button fields (`cta_label`,
+  `secondary_label`) and `stack: rhythm`; don't nest a `vitops_hero` or another section wrapper in a
+  section body, which renders two layers of `section > .centered`. `vitops_hero` is for a hero
+  that stands alone (it carries option cards).
+- **Section, block or widget area?** Copy-and-edit content is an EmDash Section. The same content
+  everywhere (announcement bar, pre-footer call to action, sidebar, footer columns) is a **widget
+  area**: define it under Widgets in the admin and render it with `<VitopsWidgetArea name="…" />`
+  from `@getvitops/emdash/astro` in the layout, or in page content with the `vitops_widgetArea`
+  block. Page-specific content is blocks. An area can't hold another area, and prerendered pages
+  show an edit after the next deploy (like menus).
+- **Escape hatches on every block:** `theme` (a backdrop from the site's colour roles, `surface` or
+  `brand-primary:solid`, with the readable text for it picked by the design system, so contrast is
+  not the editor's judgement), `anchor` (the `id`, for `#links`), `className` (extra classes; under
+  the tailwind format only ones the site already uses) and `style` (CSS custom properties only,
+  e.g. `--p-card: 2rem`; anything else is dropped). The same backdrop is available on a widget area
+  (`<VitopsWidgetArea theme="…">`) and on your own markup (`themeAttrs('surface')` from
+  `@getvitops/emdash/astro`, spread on the layout's `<body>`).
+- Override a block per site with `<PortableText components={{ type: { 'vitops_cards': MyCards } }} />`;
+  hide one with `vitopsEmdash({ blocks: { exclude: [...] } })`. Before adding a block **type**, use
+  the `emdash-custom-blocks` skill: types can't be renamed or deleted once pages use them.
+- **One `<h1>` per page.** The template's page routes render the title as an `<h1>`, and a hero's
+  heading level defaults to `h1`, so set a hero's level to `2` on those pages (or let the hero own
+  the `h1`). Use `p` for a display heading that is not part of the outline. `vitops emdash build`
+  warns on any page without exactly one `<h1>`.
+- Labels: `badge` is static (status, count, category); `tag` may be editable or dismissable. Don't
+  invent `chip` or `pill`. The button class is `btn`.
+
+## Layout foundations — the answer, not a starting point
+
+| About to write…                                         | Write instead   |
+| ------------------------------------------------------- | --------------- |
+| a `wrap`/`wrapper`/`container`/`inner` class            | **`centered`**  |
+| `max-width` + `margin-inline: auto`                     | **`centered`**  |
+| `padding-block` on a section                            | **`region`**    |
+| margins between headings/paragraphs/lists               | **`rhythm`**    |
+| `display: grid` + `grid-template-columns: repeat(n, …)` | **`subgrid`**   |
+| `repeat(auto-fit, minmax(…))`                           | **`grid-auto`** |
+| `display: flex` + `gap` for a row of controls           | **`cluster`**   |
+
+`centered` is a grid of _named tracks_: a child widens itself with `breakout`/`spotlight`/
+`fullbleed` without the parent knowing, which a bespoke `.wrap` can't do.
+
+- **More than one card means `subgrid`**, so headings and CTAs align across the set:
+  `<ul class="subgrid subgrid-cols-3" role="list">` with `<li class="card subgrid-card">`, or
+  `<Subgrid />` (renders the slot verbatim; author the `<li>`s).
+- **A card that is a link:** `stretched-link` inside it is zero-JS but kills text selection;
+  `<Cards>` keeps selection and falls back to the same link with no JS. Never both. Never
+  `<li><a class="card">`: the `li` is the grid item, so the tranches don't align.
+- `vpr lint:design` reports all of these and the pre-commit hook fails on them. Fix the class, not
+  the CSS.
+
+## The header: `site.chrome`
+
+The header is configuration, not markup. `site.chrome.masthead` sets position
+(`static|sticky|fixed`), `behavior` (`always|hide-on-scroll`), `surface`
+(`solid|glass|transparent|transparent-until-scrolled`), `layout` (`full|inset|floating`), `height`,
+`inset` and `elevation`; `site.chrome.nav` sets `compact` (`drawer|dropdown`), `drawerSide`,
+breakpoints and depths. A `<Masthead>` prop overrides one field for a layout (a landing page can be
+`position="fixed" surface="transparent-until-scrolled"`). A sticky masthead sets `--header-offset`
+itself, so anchors clear it. Nav tiers are menus: `primary`, optional `primary-mobile` and
+`primary-mega`. For the mega panel's featured column, create a widget area named
+`mega-<item url slug>` (e.g. `mega-services`), or put `mega-area:<name>` in the menu item's CSS
+classes.

package/skills/{contact-form → emdash-contact-form}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: contact-form
+name: emdash-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`.
 ---
 

package/skills/{content-and-deploys → emdash-content-and-deploys}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: content-and-deploys
+name: emdash-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.
 ---
 
@@ -101,3 +101,30 @@ reviewers' approval** like any prod deploy (relax that rule if editors' publishe
 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.
+
+## Sitemap lists `/pages/<slug>`
+
+A collection with no `urlPattern` is listed as `/<collection>/<slug>`, so the sitemap would send
+search engines to 404s while the site serves `/<slug>`. `vitops emdash build` (check-prerender) warns
+when the sitemap lists URLs the build has no page for. Set the pattern on the collection (the seed's
+`urlPattern`, or Content types in the admin); a database made before the seed set it needs the admin fix.
+
+## EmDash 1.x behaviours
+
+- Passkeys are bound to the hostname they were created on. After a domain cutover use **Settings →
+  General → Change domain**, then **Continue on**.
+- Link entries by `entry.data.slug`, never `entry.id` (multilingual sites prefix `id` with a locale).
+- Submit `/sitemap.xml` to search engines, not a per-collection sitemap.
+- Clear a stuck D1 migration lock with `vp exec emdash migrate --take-over-lock <id>` (needs
+  `--expected-target-fingerprint` non-interactively).
+
+## Legal pages and the audit
+
+- The sample `/terms` and `/privacy` pages are short placeholders. To replace them, fill in
+  `site.json`'s `organization`/`site.legal`, run
+  `vp exec vitops legal --format portable-text --out ./legal`, and paste each document into the page
+  in the admin. The output still needs review before launch.
+- `vitops audit` needs optional packages and a browser, checked before it starts a server:
+  `vp add -D @axe-core/playwright lighthouse && vp exec playwright install chromium`
+  (`playwright` itself is already a devDependency). Its page list is the built sitemap, then the
+  seed's menus.

package/skills/{custom-blocks → emdash-custom-blocks}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: custom-blocks
+name: emdash-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".
 ---
 

package/skills/vitops-ads/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: vitops-ads
+description: How ad platforms, pixels, conversions and attribution work on this site — `site.ads`, the consent-gated tags, click-ID capture into `_ac`, `vitops ads setup|tags|lint`, and the `tel:`/form conversions they report. Also call tracking and forwarding numbers (Google website call conversions, per-platform CallRail/Twilio numbers). Use when adding or changing a Google/Meta/LinkedIn/TikTok/Microsoft/Reddit/Pinterest/Snapchat pixel, verifying a domain with an ad platform, debugging conversions that arrive unattributed, or showing different phone numbers to ad visitors.
+---
+
+# Ads
+
+An ad platform is recorded as facts in `site.json` under `site.ads.<platform>`; the toolchain turns
+those facts into the tag, the cookie-notice disclosure, the consent behaviour and the lint checks. A
+pixel pasted into a template is invisible to all four, so don't.
+
+- **Platforms:** `google` `meta` `linkedin` `reddit` `tiktok` `microsoft` `pinterest` `snapchat`. Each
+  entry names the account (`accountId`), the tag (`pixelId`; for Google the `AW-…` conversion ID, not
+  the customer ID) and, where the platform verifies a domain, the token (`domainVerification`).
+- **Tags are inert until consent.** `<Ads />` renders each as `type="text/plain"` with its URL on
+  `data-src`, so an undecided visitor's page makes no third-party request. Never give an ad tag a live
+  `src`. Category is `marketing` unless `category: "analytics"`. `environments.<env>.ads: false`
+  switches every tag off for that environment (a preview must not fire conversion pixels).
+- **Click IDs are captured into `_ac`** by `<Tracking />` once `site.tracking.enabled` is true. It
+  reads the landing URL synchronously, but only _writes_ the 90-day cookie after `marketing` is
+  granted, and only an arrival that carried a click ID or UTM raises the banner. With tracking off,
+  every conversion from an ad arrives unattributed — it looks exactly like organic.
+- **Conversions** are `tel:` taps, `mailto:` taps and form posts. For Google, `conversionLabel`
+  takes one label or `{ call, email, form }`, and each is its own action in Google Ads (the category —
+  "Phone call lead", "Contact", "Submit lead form" — is set there, not in code).
+  `reporting: "server"` + `conversionActionId` uploads from the conversion route instead of the browser.
+- **Domain verification:** only Meta, TikTok, Pinterest and Snapchat verify, by an apex DNS TXT record.
+  Google Ads, LinkedIn, Reddit and Microsoft have none — linking is the tag and the account ID.
+
+## Commands
+
+- `vitops ads setup` — creates the verification TXT (needs `CLOUDFLARE_API_TOKEN`), asks for a missing
+  token and writes it back to `site.json`. It never edits or deletes a DNS record, and calls no
+  platform API; the final "Verify" click stays manual (it prints a reminder).
+- `vitops ads tags` — prints the inert, gated `<script>` markup for stacks that aren't Astro.
+- `vitops ads lint` — reports gaps nothing shows at runtime: a click ID that isn't captured, tracking
+  turned off, an undeclared call-tracking processor. Run it before launch and when adding a platform.
+
+## Topics
+
+- [call-tracking.md](call-tracking.md) — showing ad visitors a forwarding number: Google's website
+  call conversions, per-platform numbers from a call-tracking provider, what each platform can and
+  can't do, consent timing, double counting, privacy policy, and how to test. Read when the task
+  involves phone numbers, `tel:` links or "calls from ads".
+
+See also the `emdash-contact-form` skill (where form conversions land and what the notification says) and the
+`vitops-csp` skill (origins a new tag needs before the CSP is enforced).
+
+## Conversion tracking details
+
+`vitops docs tracking`. `site.tracking.enabled` captures ad click IDs and UTMs from the
+landing URL into the first-party `_ac` cookie; a conversion route reads it back and notifies
+via `site.notifications`. Points worth holding:
+
+- `_ac` is a 90-day identifier, so it waits on `marketing` (or `site.tracking.category`) and
+  the capture **`require()`s** it — see above.
+- Only an arrival actually carrying a click ID or UTM asks; organic visitors are never
+  interrupted.
+- The read is synchronous and the _write_ is what waits — the click ID exists only in the
+  landing URL, so it cannot be deferred.
+- Only the `email` channel (Cloudflare Email Sending) is implemented. Its sending domain must
+  be onboarded with `wrangler email sending enable <domain>` or every send fails; the tool
+  surfaces that error verbatim rather than as "send failed".
+- `--dry`-style planning is pure and reports **why** anything was skipped. A silently unsent
+  notification is indistinguishable from no conversion, so never leave one unexplained.

package/skills/vitops-ads/call-tracking.md

@@ -0,0 +1,106 @@
+# Call tracking numbers
+
+Goal: attribute a real phone call to the ad that caused it, not just the `tel:` tap. That means
+showing an ad visitor a different number than everyone else, then reading which number was dialled.
+
+## What each platform can do
+
+| Platform                                            | Number on the website?                                                                                           |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Google Ads**                                      | Yes — _website call conversions_. Google supplies the forwarding number. Canada is supported (local, toll-free). |
+| **Microsoft Ads**                                   | No. Forwarding numbers exist only inside the ad's call extension, and only in the US, UK and Australia.          |
+| Meta, LinkedIn, TikTok, Reddit, Pinterest, Snapchat | No platform-provided numbers at all.                                                                             |
+
+For everything except Google the only route is a number the client provisions with a call-tracking
+provider (Twilio, CallRail, CallScaler, …), forwarding to the real line, shown to that platform's
+visitors. That is `site.tracking.phoneNumbers`. Re-check Google's and Microsoft's availability pages
+before promising a client either: country lists change.
+
+## Rules that hold for both routes
+
+- **The served HTML always carries the real number.** Swapping happens in the browser only, so
+  crawlers, structured data, no-JS visitors and local-SEO listings all see one consistent number, and
+  `organization.phone` stays the truth. Never render a tracking number server-side.
+- **Only matching links and marked text are swapped.** A `tel:` link is swapped when its digits equal
+  the configured number (href and any text that is that number; a link labelled "Call us" only has its
+  href changed). Other text is swapped only inside an element with `data-vitops-phone`. Write the
+  number on the page in the same digits as the config — `613-555-0100`, `(613) 555-0100` and
+  `+1 613 555 0100` all match; a number written with a typo never does and is silently left alone.
+- **An organic visitor is never swapped.** Nobody sees a tracking number they weren't sent to.
+- **Needs `site.tracking.enabled: true`.** The capture script does the swapping; validation rejects
+  either feature without it.
+
+## Google: `site.ads.google.callTracking`
+
+```json
+"ads": { "google": {
+  "pixelId": "AW-123456789",
+  "callTracking": { "label": "AbC_dEf-1", "number": "613-555-0100" }
+} }
+```
+
+- `label` belongs to a **separate** Google Ads conversion action of type _Calls from a phone number on
+  your website_, not the `conversionLabel.call` action (that one counts taps).
+- Output is `gtag('config', 'AW-…/<label>', { phone_conversion_number, phone_conversion_callback })`,
+  inside the same consent-gated `marketing` tag, so nothing loads or swaps before consent.
+- Google replaces displayed **text** only. The callback hands the result to the capture script, which
+  rewrites the `tel:` href. Without that, the visible number would be Google's and the tap would dial
+  the real one.
+- Google decides who is shown a number (ad click, remembered for a while in a cookie; `cache: false`
+  turns that cache off). Only one number per page can be tracked this way.
+- **Double counting:** one call can count as the tap action and the call action. In Google Ads make
+  one secondary. `vitops ads lint` reminds you when both are set.
+- **Verification:** with a swapped number Google can't verify the domain by scanning the page. Link
+  Search Console. A tag installed through Google Tag Manager can't verify it either, so don't move this
+  tag into GTM.
+- Test: after granting marketing consent, load a landing URL with `#google-wcc-debug` appended and
+  confirm the number and the `tel:` href both changed. Set the action's minimum call length in
+  Google Ads.
+- Not available on the Display Network.
+
+## Everyone else: `site.tracking.phoneNumbers`
+
+```json
+"tracking": { "enabled": true, "phoneNumbers": {
+  "number": "613-555-0100",
+  "provider": "callrail",
+  "sources": { "meta": "613-555-0101", "microsoft": "613-555-0102", "default-paid": "613-555-0199" }
+} }
+```
+
+- `sources` keys are the `site.ads` platform names plus `default-paid`, the fallback for a paid visit
+  (any click ID, or `utm_medium` of `cpc`/`ppc`/`paid…`) from a platform with no number of its own.
+  Unknown keys fail validation. A `google` key is rejected while `callTracking` is set — two numbers
+  would compete for one visitor.
+- Which source wins: the **landing URL** first (click ID, then a known `utm_source` such as
+  `facebook`→meta, `bing`→microsoft), then the stored `_ac` cookie. A fresh Meta click beats an old
+  stored Google ID.
+- **Consent timing:** on the landing page the number is chosen from the URL, which is not storage and
+  needs no permission. On later pages it comes from `_ac`, which exists only if `marketing` was
+  granted. A visitor who declines therefore sees a tracking number on the landing page only — say so
+  to the client; it is a deliberate consequence of not storing without consent.
+- The tap beacon carries which number was dialled, so the conversion notification says e.g. "Number
+  shown: meta tracking number". The call itself is attributed by the provider's own reporting.
+- The decision lives in `@getvitops/utils/tracking`'s `selectPhoneNumber()` (pure, tested). The
+  capture script `packages/astro/src/scripts/tracking.ts` mirrors it because it is inlined into the
+  document; `tracking.test.ts` pins the two, so change them together.
+
+## Privacy policy
+
+A call-tracking provider records every caller's number and often a recording, so it is a processor the
+generated policy must name. State it in `site.legal.privacyPolicy.processors` (the toolchain has no
+known-provider entry for these yet). `phoneNumbers.provider` is informational and exists so `vitops ads
+lint` can flag a provider missing from that list. Call recording needs its own caller notice; that
+belongs in the provider's settings, not here.
+
+## CSP
+
+If the CSP is enforced, Google's number fetch needs Google origins in `script-src`/`connect-src`;
+watch the Report-Only console on a landing page with `#google-wcc-debug` for the exact ones. See the
+`vitops-csp` skill.
+
+## Verifying a change
+
+- `vitops validate` / `vitops ads lint` after editing `site.json`.
+- In a browser: load `/?fbclid=test` and confirm the Meta number appears and the `tel:` href matches;
+  load `/` and confirm the real number; load with JavaScript disabled and confirm the real number.

package/skills/vitops-consent/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: vitops-consent
+description: Use before gating, adding or changing any non-essential third-party tag, cookie, embed or `localStorage` write on a site with the consent gate (`<wc-consent>`, `data-consent`, `window.vitopsConsent`), or when a consent banner does not appear or a tag loads before consent.
+---
+
+# Consent and third-party tags
+
+If the site has a consent gate, **every** non-essential third party goes through it. Run
+`vitops docs consent` before wiring one up — the failure modes here are silent and legal.
+The four that bite:
+
+- **A gated tag must render inert.** `type="text/plain"` + `data-consent="<category>"` +
+  the URL on `data-src` (never `src`), plus `data-consent-cookies` naming what it sets so
+  a revoke can clear them. Given a live `src` the browser fetches the library immediately
+  and the gate is decorative — an undecided visitor's page must issue **no** third-party
+  request.
+- **Use `require()`, not `granted()`, when you want permission.** `granted()` is passive:
+  it never raises the banner, so on a site where nothing else demands that category it is a
+  **permanent silent no-op** and your write never happens. `require()` registers the demand,
+  which is what makes the banner appear. `request()` is the promise form.
+- **No `window.vitopsConsent` means the site has no gate — store freely.** It does not mean
+  denied. (A synchronous stub in `<head>` covers the window before the runtime loads, so
+  absence is reliable. Listen for the `vitops:consent` event rather than calling
+  `subscribe()`, which the stub lacks.)
+- **Patch exactly the categories you put on screen.** `acceptAll()` / `rejectAll()` mean
+  literally every optional category — using one to answer a single-category prompt records
+  consent nobody gave. "Not asked" is a third value (`null`), distinct from declined, and
+  only it can be re-prompted.
+
+The banner is **demand-driven**: it appears when something actually asks, not on first visit.
+A site whose only analytics provider is cookieless never interrupts anyone. Don't "fix" a
+missing banner by forcing it to show — find out what should have demanded a category.
+
+Whatever loads must match what the **generated cookie notice** discloses; the Astro
+integration warns when they disagree, and that is a compliance defect, not a doc nit.

package/skills/{csp → vitops-csp}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: csp
+name: vitops-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.
 ---
 

package/skills/vitops-see-the-page/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: vitops-see-the-page
+description: How to look at a rendered page of this site (layout, colour, dark mode, no-JS fallback, mobile width) with playwright-cli. Use whenever you need to see, screenshot or click through a page, verify a visual change, or check how a page behaves without JavaScript.
+---
+
+# Seeing the rendered page
+
+`playwright-cli` is the only way to look at a page here. Don't use the Claude-in-Chrome extension or a
+browser MCP server; `.claude/settings.json` denies them. The full command reference is the upstream
+`playwright-cli` skill (written by `prepare` into `.claude/skills/playwright-cli/`); this file only
+covers what is specific to this site.
+
+## Steps
+
+1. **Serve the page first.** `vpr dev` for source changes, or `vpr build` then the preview command
+   for exactly what ships. On EmDash, run `vpr prepare-local-db` before the first build.
+2. **Open a named session:** `pnpm exec playwright cli -s=<task> open http://localhost:<port>/<path>`.
+   One session per task; `close` it when done.
+3. **`snapshot` first.** It's text, cheap, and gives element refs. `screenshot` only when the
+   question is visual (spacing, colour, overflow). Output files land in `.playwright-cli/`
+   (gitignored).
+4. **Dark mode:** set `data-theme="dark"` on `<html>` (the attribute `<wc-color-scheme-toggle>` writes)
+   rather than clicking through the toggle.
+5. **Mobile width:** `open --device="iPhone 15"` or `--mobile`.
+6. **No-JS fallback:** the web components must be usable without JavaScript. Open with a config
+   file whose `browser.contextOptions` sets `javaScriptEnabled: false` and check the slotted markup
+   is readable and operable.
+
+## Don't
+
+- Don't sign in to a production admin or paste real credentials into a session.
+- Don't leave sessions running (`close-all` if unsure).
+- If the browser is missing: `pnpm exec playwright cli install-browser chromium`.