@getvitops/cli 8.2.0 → 8.3.0-alpha.1

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, parse, relative, resolve } from "node:path";
 import { CONFIG_SCHEMA_LOCAL_PATH, JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_LOCAL_PATH, buildIconSprite, defaultConfig, defaultSiteConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, movedTokens, processorsMissingLocation, renderRobotsTxt, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
 import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
@@ -14,11 +14,14 @@ import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as form
 import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$4, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, normalizeConversionActionIds, normalizeConversionLabels, plan as plan$3, renderTag, tagId } from "@getvitops/utils/ads";
 import { PLATFORM_PARAMS } from "@getvitops/utils/tracking";
 import { createInterface } from "node:readline/promises";
+import { DEFAULT_BUDGETS, buildReport, fetchSitemapPaths, formatSummary as formatSummary$2, parseImpacts, pathsFromSeed, planPages, preflight, reportFiles, runAudit, runCommand, startPreview } from "@getvitops/utils/audit";
 import { zohoAccountsHost, zohoApiHost } from "@getvitops/utils/crm";
-import { backoffSchedule as backoffSchedule$1, blockedDomains, collectFromAddresses, dnsStatus, enableSending, findZoneForHost, formatPlan as formatPlan$5, formatSummary as formatSummary$2, hasDrift as hasDrift$2, listSendingSubdomains, planSendingDomains, resolveTxt, sendingDns } from "@getvitops/utils/email";
+import { backoffSchedule as backoffSchedule$1, blockedDomains, collectFromAddresses, dnsStatus, enableSending, findZoneForHost, formatPlan as formatPlan$5, formatSummary as formatSummary$3, hasDrift as hasDrift$2, listSendingSubdomains, planSendingDomains, resolveTxt, sendingDns } from "@getvitops/utils/email";
 import { normalizeEmailChannel, resolveSender } from "@getvitops/utils/notify";
-import { execFileSync } from "node:child_process";
-import { adminCollaboratorIds, branches, createD1, createDevEnvironment, createProdEnvironment, createR2Bucket, createRepo, defaultBranch, environments, findD1, findR2Bucket, formatPlan as formatPlan$6, formatSummary as formatSummary$3, ghAuthed, mainProtected, originRemote, plan as plan$4, planDomainConsistency, protectMain, pushBranches, repoNwo, secretsPresent, setDefaultBranch, setSecret, wranglerWhoami } from "@getvitops/utils/hosting";
+import { execFileSync, spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { adminCollaboratorIds, branches, createD1, createDevEnvironment, createProdEnvironment, createR2Bucket, createRepo, defaultBranch, environments, findD1, findR2Bucket, formatPlan as formatPlan$6, formatSummary as formatSummary$4, ghAuthed, mainProtected, originRemote, plan as plan$4, planDomainConsistency, protectMain, pushBranches, repoNwo, secretsPresent, setDefaultBranch, setSecret, wranglerWhoami } from "@getvitops/utils/hosting";
+import { createWidget, deriveDomains, formatPlan as formatPlan$7, formatSummary as formatSummary$5, hasDrift as hasDrift$3, listWidgets, patchSiteKey, plan as plan$5, resolveAccountId } from "@getvitops/utils/turnstile";
 
 // src/args.ts
 /**
@@ -360,6 +363,7 @@ Usage:
   vitops setup <sub> [opts]     Scripted onboarding: repo, hosting, domain, search, ads, all
   vitops email <sub> [opts]     Sender-domain onboarding: check (setup) + deploy guard (check)
   vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
+  vitops audit [options]       Performance + accessibility budgets over a built site (Lighthouse + axe)
 
 Generate options:
   -i, --input <path>    design-system.json or site config (default: ./design-system.json)
@@ -415,7 +419,8 @@ Agents options:
 Docs options:
   <topic>               classes | authoring | formats | color | scales | patterns | elements
                         (no topic: list topics with summaries)
-  -i, --input <path>    design-system.json or site config (default: ./design-system.json)
+  -i, --input <path>    site config or design-system.json (default: ./site.json, else
+                        ./design-system.json)
       --theme <name>    Theme to render docs from, when --input is a site config
       --all             Print every topic, concatenated
 
@@ -428,7 +433,8 @@ Icons options:
       --json            Machine-readable report on stdout
 
 Lint options:
-  -i, --input <path>    design-system.json or site config (default: ./design-system.json)
+  -i, --input <path>    site config or design-system.json (default: ./site.json, else
+                        ./design-system.json)
       --theme <name>    Theme to judge classes against, when --input is a site config
   -f, --format <fmt>    Format you build (bricks | css | tailwind; default: bricks).
                         Responsive md-* classes are real in css/bricks, inert in tailwind.
@@ -671,6 +677,22 @@ Setup domain options:
   or deploys. Cutover overwrites the zone's DNS record and can take an existing live
   site down; that step is manual, on purpose. See SETUP.html's "Domain strategy" stage.
 
+Setup turnstile options:
+  -i, --input <path>    Site config (default: ./site.json)
+      --site-env <env>  Environment to read (default: production)
+      --dry             Print the plan and exit (needs no token)
+      --check           Exit non-zero if no widget/site key is set up; mutates nothing
+      --no-write        Do not write site.security.turnstile.siteKey back to the config
+      --no-secret       Do not run \`wrangler secret put\` for the new widget's secret
+
+  Creates a managed Turnstile widget for the site's hostnames (canonical + each
+  environment URL) unless one already covers them, and writes the PUBLIC site key to
+  site.security.turnstile.siteKey. The SECRET is returned once at creation: it is piped
+  to \`wrangler secret put VITOPS_TURNSTILE_SECRET\` and never written to a config file.
+  Never edits, rotates or deletes an existing widget.
+  Needs CLOUDFLARE_API_TOKEN with "Account > Turnstile > Edit", plus CLOUDFLARE_ACCOUNT_ID
+  (or a token that can list accounts), and \`wrangler login\` for the secret.
+
 Setup search options:
   Forwards every option to \`vitops search setup\` unchanged — see "Search setup
   options:" above.
@@ -689,6 +711,21 @@ Setup all options:
   Runs repo, hosting, search, ads in order. Stops at the first stage that fails;
   a blocked step (the API token, GitHub Pro/Team gating) is reported, not fatal.
 
+Emdash subcommands:
+  vitops emdash prepare-db           Migrate and seed the local D1 the build prerenders from
+  vitops emdash check-prerender [d]  Fail if a prerendered page is not a real page
+
+Emdash prepare-db options:
+  (none)  Starts \`astro dev\` once, calls EmDash's dev-bypass setup (migrates, applies the
+          seed's sample content), checks the home page renders, stops. Only writes the
+          disposable .wrangler/state. SKIP_PREPARE_LOCAL_DB=1 skips it.
+
+Emdash check-prerender options:
+  [dir]   Build output to check (default: dist/client). Fails on a page that carries the
+          pending-migrations message, is not an HTML document, or has no <title>.
+  --strict  Also fail (not just warn) when a page uses a type-role class (font-display, …)
+          the built CSS has no rule for.
+
 Email subcommands:
   vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve
   vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded
@@ -754,6 +791,31 @@ Media options:
   ffmpeg output is not reproducible across versions, so re-encoding in CI churns
   the diff on every toolchain bump. Use --force when you mean to re-encode.
 
+Audit options:
+      --build           Run \`astro build\` first (default: audit the existing build)
+      --url <base>      Audit an already-running server instead of \`astro preview\`
+      --port <n>        Port for \`astro preview\` (default: 4398; aborts if taken)
+      --dir <path>      Project directory (default: .)
+      --pages <list>    Extra comma-separated paths. The page list is the built sitemap
+                        plus links in seed/seed.json's primary* and footer* menus; only
+                        when neither exists are / /privacy /terms /cookies /contact
+                        guessed. A 404 skips a page (with its reason in the report); a
+                        404 on / fails the run.
+      --no-defaults     Never guess the default pages
+      --seed <path>     EmDash seed to read menus from (default: seed/seed.json if present)
+      --lcp <ms>        LCP budget (default: 2500)
+      --cls <n>         CLS budget (default: 0.1)
+      --tbt <ms>        Total Blocking Time budget, the INP proxy (default: 200)
+      --impact <list>   axe impacts that fail a page (default: serious,critical)
+      --form-factor <f> mobile | desktop Lighthouse profile (default: mobile)
+  -o, --out <dir>       Report directory (default: .vitops/audit): report.json, report.md,
+                        and pages/<page>.{json,md}
+      --warn            Report without failing (exit 0), for first adoption
+
+  Needs the optional packages: vp add -D playwright @axe-core/playwright lighthouse
+  && vp exec playwright install chromium (checked before any server starts). A pass means no automated axe violations and the
+  budgets held — it is NOT AODA certification; report.md lists the manual checks.
+
 Common:
   -h, --help            Show this help
 `;
@@ -784,6 +846,15 @@ const EMAIL_HELP = `vitops email — sender-domain onboarding checks
   vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve
   vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded
 
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
+const EMDASH_HELP = `vitops emdash — build-time steps for an EmDash site
+
+  vitops emdash prepare-db           Migrate and seed the local D1 the build prerenders from
+                                     (SKIP_PREPARE_LOCAL_DB=1 skips)
+  vitops emdash check-prerender [d]  Fail if a prerendered page under [d] (default dist/client)
+                                     is not a real page
+
 Run \`vitops --help\` for the full option list for each subcommand.
 `;
 const SETUP_HELP$1 = `vitops setup — the scripted path from an empty scaffold to a live site
@@ -820,7 +891,9 @@ const COMMANDS = [
 	"crm",
 	"setup",
 	"email",
-	"media"
+	"emdash",
+	"media",
+	"audit"
 ];
 /**
 * The slice of `HELP` documenting one command, addressed by its heading.
@@ -849,7 +922,7 @@ const wantsHelp = (argv) => argv.includes("-h") || argv.includes("--help");
 /** The help text to print for `vitops <command> [sub] --help`. */
 function helpFor(command, argv) {
 	const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : void 0;
-	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? "vitops search — Google Search Console\n\n  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties\n  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "ads" ? "vitops ads — link this site to its ad properties\n\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "crm" ? "vitops crm — push form submissions into a client CRM\n\n  vitops crm check [opts]       Compare site.crm's fieldMap/trackingFields against the live CRM\n  vitops crm setup [opts]       Create missing HubSpot properties (Bigin/Jobber have no such API)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "setup" ? "vitops setup — the scripted path from an empty scaffold to a live site\n\n  vitops setup repo [opts]      GitHub repo + branch policy (main protected, dev open)\n  vitops setup hosting [opts]   Dev D1 + R2 + repo secrets (cloudflare) or a Node target\n  vitops setup domain [opts]    Plan/check the workers.dev-vs-custom-domain consistency\n                                 (never applies the cutover — see SETUP.html)\n  vitops setup search [opts]    Forwards to `vitops search setup`\n  vitops setup ads [opts]       Forwards to `vitops ads setup`\n  vitops setup all [opts]       Run repo, hosting, search, ads in order\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "email" ? "vitops email — sender-domain onboarding checks\n\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nRun `vitops --help` for the full option list for each subcommand.\n" : void 0) ?? "vitops — generate design-system outputs from a design-system.json\n\nAnywhere a command takes --input, that file may be a design-system.json OR the\nlarger site config that embeds one (company.json / site.json). The two are told\napart by shape, and a site config also supplies the site-level facts generation\nreads — its default colour scheme, its legal documents, its icon sprite.\n\nUsage:\n  vitops generate [options]     Generate platform output from a config\n  vitops init [options]         Scaffold a starter design-system.json\n  vitops validate <file>        Validate a config against the schema it says it is\n  vitops favicon [options]      Generate a favicon set from a source image\n  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer\n  vitops docs [topic]           Print live design-system reference docs to stdout\n  vitops lint [opts] [files]    Report classes that resolve to nothing + primitives you re-implemented\n  vitops legal [options]        Render legal documents from a site config\n  vitops robots [options]       Render robots.txt from a site config's environment\n  vitops reviews [options]      Fetch + cache Google Business Profile reviews\n  vitops icons [options]        Report which icons your source uses, and build the sprite\n  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)\n  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint\n  vitops setup <sub> [opts]     Scripted onboarding: repo, hosting, domain, search, ads, all\n  vitops email <sub> [opts]     Sender-domain onboarding: check (setup) + deploy guard (check)\n  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster\n\nGenerate options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n  -f, --format <list>   bricks | css | tailwind | design (comma-separated; default: bricks)\n                        design emits DESIGN.md only (the agent-facing brief) — pair it\n                        with --out . to write it beside AGENTS.md, or compose:\n                        --format css,design\n  -o, --out <dir>       Output directory (default: ./dist)\n      --theme <name>    Which designSystem.themes entry to build, when --input is\n                        a site config (default: its defaultTheme, else \"default\")\n      --site <path>     Site config, when it is a different file from --input.\n                        Emits legal/*.html into the output directory (see:\n                        vitops legal). Omitted with a plain design-system.json:\n                        no legal files.\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\nInit options:\n  -o, --out <path>      Where to write (default: ./design-system.json, or\n                        ./site.json with --site)\n      --force           Overwrite an existing file\n      --site            Write a site config (Config) instead of a bare\n                        design-system.json — embeds a starter design system at\n                        designSystem.themes.default, since a Config can't\n                        merely reference a sibling file\n      --name <name>     organization.name, when --site is set\n      --url <url>       site.environments.{production,dev}.url, when --site is set\n\nValidate options:\n  <file>                Config to check (default: ./design-system.json). Either\n                        kind — a design-system.json or the config that embeds one.\n  -i, --input <path>    Same, as a flag\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Checks the schema, then the things a schema cannot: that every role points at a\n  palette hue that exists, that every var() an authored declaration references\n  resolves to a token this config emits, and that the colour grammar is current.\n\nFavicon options:\n  -i, --input <path>    Source SVG or PNG (required)\n  -o, --out <dir>       Output directory (default: ./public)\n      --low-res <path>  Optional simplified source for the 16px icon\n      --background <hex>  Background under the maskable icons, which must be\n                        opaque (default: #ffffff)\n\nAgents options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json;\n                        validated if present)\n      --theme <name>    Theme to read, when --input is a site config\n  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)\n      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir\n                        instead of linking the packaged skill\n\nDocs options:\n  <topic>               classes | authoring | formats | color | scales | patterns | elements\n                        (no topic: list topics with summaries)\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n      --theme <name>    Theme to render docs from, when --input is a site config\n      --all             Print every topic, concatenated\n\nIcons options:\n  -i, --input <path>    Site config carrying the \"icons\" block (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for icon usage (default: ./src)\n      --sprite          Also build the SVG sprite\n  -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)\n      --json            Machine-readable report on stdout\n\nLint options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n      --theme <name>    Theme to judge classes against, when --input is a site config\n  -f, --format <fmt>    Format you build (bricks | css | tailwind; default: bricks).\n                        Responsive md-* classes are real in css/bricks, inert in tailwind.\n  -s, --src <dir>       Directory to scan (default: ./src)\n      --strict          Also fail on suggestions (reuse hints), not just on\n                        classes that resolve to nothing\n  [files...]            Lint these paths instead of scanning --src. Unreadable\n                        and non-source paths are skipped, so this can be wired\n                        into a pre-commit hook that appends the staged files.\n      --fix             Rewrite pre-1.0 colour-grammar token references\n                        (var(--<role>-<suffix>) → var(--color-<target>-<role>…))\n                        in CSS and <style> blocks. Applied in ONE pass, so the\n                        renames that rotate cannot compound. Nothing else is\n                        rewritten — every other finding is a judgement call.\n\n  Run this after a major bump: it is the migration tool for anything the\n  changelog says was renamed.\n\nLegal options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -d, --doc <name>      privacy | terms | cookies (repeatable; default: those\n                        enabled in the config)\n  -f, --format <fmt>    md | html | portable-text (default: md)\n                        html suits WordPress/Bricks and plain sites;\n                        portable-text suits EmDash\n  -o, --out <dir>       Write files here (default: print to stdout)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Generated from your config — a starting point, not legal advice. Review before\n  publishing, and make sure the config describes what your site actually does.\n\nRobots options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -o, --out <dir>       Write robots.txt here (default: print to stdout)\n      --site-env <env>  Which site.environments entry to render for (default: production)\n\n  Reads the resolved environment's robots directive (falling back to\n  site.seo.robots) — the same fact vitops search notify's noindex gate already\n  reads. A directive containing noindex disallows every user agent and emits\n  no Sitemap line; otherwise it allows everything and links\n  site.seo.indexing.sitemapUrl, or the derived <canonical>/sitemap-index.xml.\n\nReviews options:\n  -i, --input <path>    Site config carrying site.reviews (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --location <key>  Fetch only this site.reviews.locations key\n      --cache <path>    Where to read/write the cache (default: .vitops/reviews.json)\n      --out <dir>       Also write the selected reviews per location as JSON here\n      --dry             Print the plan and exit. Fetches nothing.\n      --check           Fetch and diff against the cache; exit non-zero on drift.\n                        Mutates nothing.\n\n  Reviews live only on the legacy Business Profile v4 API — there is no newer\n  replacement — and the calling GCP project must be allowlisted by Google before\n  any call succeeds (a one-time approval; a 403 says so rather than failing\n  opaquely). Auth is user OAuth, the same VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (or ADC login) that\n  vitops search setup uses, scoped to business.manage. The cache is meant to be\n  committed: reviews change slowly, and a build should not need a live Google\n  credential. Review JSON-LD is off by default (site.reviews.schema) — a business\n  marking up reviews of itself is not eligible for Google's rich results and\n  risks a manual action.\n\nSearch subcommands:\n  vitops search setup [opts]    Onboard site.searchConsole domains into GSC\n  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)\n\nSearch setup options:\n  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --domain <name>   Scope to a single site.searchConsole entry\n      --dry             Print the plan and exit. Changes nothing, and runs without\n                        credentials (planning from scratch, which it says).\n      --check           Report drift and exit non-zero if any domain is not fully\n                        onboarded. Mutates nothing, but does need credentials —\n                        drift is a comparison against live state.\n\n  For each domain it ensures the apex verification TXT in Cloudflare, verifies\n  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-\n  unverified domain is reported PENDING, not failed), adds the sc-domain: property,\n  and adds any delegatedOwners to the web resource. DNS is only ever created,\n  never edited or deleted. Credentials come from the environment:\n  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit + Zone:Read — the standard \"Edit zone DNS\"\n  template covers both; Zone:Read is what the zone-by-name lookup uses), and\n  VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token\n  scoped to siteverification + webmasters). Granting a Google Group Full-User\n  access has no API and is surfaced as a reminder.\n\n  Or just be logged in: with no VITOPS_GOOGLE_* set, an Application Default\n  Credentials login is used —\n    gcloud auth application-default login \\\n      --scopes=openid,https://www.googleapis.com/auth/siteverification,\\\n  https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/cloud-platform\n  ADC authenticates through a shared OAuth client that owns no project, so it also\n  needs site.google.project in the config (sent as x-goog-user-project), both APIs\n  enabled on that project, and serviceusage.services.use on it. One project per site\n  is what keeps each site's API usage and billing separate.\n\nSearch notify options:\n  -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)\n      --site-env <env>  Environment to notify for (default: production). An\n                        environment whose robots policy says noindex is refused.\n      --sitemap <src>   Sitemap URL or local path (default: from the config)\n      --urls <list>     Comma-separated URLs to submit, skipping the diff\n      --all             Submit every URL in the sitemap, not just what changed\n      --dry             Print the plan and exit. Makes no requests.\n      --check           Read-only: ask Google whether seo.indexing.priorityUrls\n                        are indexed. Exits non-zero if one is not.\n      --new-key         Print a fresh IndexNow key and exit\n      --write-key <dir> Write the IndexNow key file into <dir> (for stacks with\n                        no Astro integration to do it — Bricks, WordPress)\n      --snapshot <path> Changed-URL state file (default: .vitops/sitemap-snapshot.json).\n                        Persist it between runs (a CI cache) or every run submits\n                        everything.\n\n  What notify can and cannot do: Google exposes no \"request indexing\" API, and its\n  sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap\n  through the Search Console API and verifies the result with --check. IndexNow\n  reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.\n  Search Console takes either credential, whichever you already have, added as an\n  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline\n  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth\n  credential \"search setup\" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /\n  _REFRESH_TOKEN). The service account is preferred when both are set — this runs\n  on every deploy, and it does not expire.\n\nAds subcommands:\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nAds setup options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --provider <name> Scope to one site.ads entry (google | meta | linkedin |\n                        reddit | tiktok | microsoft | pinterest | snapchat)\n      --dry             Print the plan and exit. Creates nothing. With\n                        CLOUDFLARE_API_TOKEN set it reads live DNS first, so the\n                        plan says what is already done; without one it plans from\n                        scratch and says so, rather than refusing to run.\n      --check           Report drift and exit non-zero if any property is not\n                        linked. Mutates nothing, prompts for nothing.\n      --no-prompt       Never ask for a missing token; fail with the field name\n                        instead (the default when stdin is not a TTY, e.g. in CI)\n      --no-write        Don't persist an answered token back into the config\n\n  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —\n  and that record is the one thing this creates for you (in Cloudflare, via\n  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,\n  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking\n  there is the tag and the account ID, and the run says so rather than skipping in\n  silence. No platform Marketing API is called — Meta's needs a system-user token\n  and Google's needs an approved developer token, so the final \"Verify\" click stays\n  a reminder. The verification token is not a secret (it is published in DNS, which\n  is the ownership proof), so it lives in the config and is prompted for on the\n  first run.\n\nAds tags options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --provider <name> Print one platform's tag\n      --strategy <s>    idle | async | interaction (default: idle)\n\n  Prints each pixel as an INERT, consent-gated <script>: type=\"text/plain\" with the\n  library URL on data-src, so an undecided visitor's page issues no third-party\n  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.\n  Paste into your template; @getvitops/core's consent runtime activates them.\n\nAds lint options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n\n  Reports the gaps that are invisible at runtime: a click-ID parameter this\n  platform stamps that attribution doesn't capture, a pixel while site.tracking is\n  off (every conversion arrives unattributed), and a configured property with no\n  tag ID. Exits non-zero on a finding.\n\nCrm check options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n\n  Fetches the live field/property list (HubSpot: crm/v3/properties/contacts;\n  Bigin: bigin/v2/settings/fields) and reports every fieldMap/trackingFields\n  target that doesn't exist there. HubSpot rejects a submission naming an\n  unrecognised property; Bigin silently ignores it — this is the only way to\n  see a broken mapping before a real submission finds it. Needs\n  VITOPS_HUBSPOT_ACCESS_TOKEN, VITOPS_ZOHO_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, or (unused for now) VITOPS_JOBBER_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, matching whichever provider site.crm names. Jobber currently\n  renders fieldMap/trackingFields as note-text lines rather than app-configured\n  custom fields, so there is nothing live to check there yet. Exits non-zero\n  on any missing target.\n\nCrm setup options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n      --dry             Print what would be created and exit. Creates nothing.\n\n  HubSpot: creates missing contact properties named by fieldMap/trackingFields.\n  Bigin: no such API exists, so this always prints a manual reminder listing\n  the fields to add in Zoho Bigin's field editor, then re-run \"crm check\".\n  Jobber: app-configured custom fields aren't wired up yet, so this prints a\n  reminder instead of creating anything.\n\nSetup repo options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --public          Create the repo public (default: private)\n      --platform <p>    cloudflare (default) | node — shown for parity with the hosting stage's plan\n      --no-dev-resources  Same — this stage never provisions D1/R2 either way\n\n  Creates the GitHub repo (via `gh`), pushes main + dev, makes dev the default\n  branch, and requests main branch protection + the production/dev environments.\n  Idempotent — a re-run of a fully set-up repo is all skips. Branch protection and\n  environment reviewers 403 on a private repo without GitHub Pro/Team; that is\n  reported as blocked, with the manual Settings path, never as a failure.\n\nSetup hosting options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --platform <p>    cloudflare (default) | node\n      --no-dev-resources  Skip D1/R2 — a pure static Workers Assets project has\n                        nothing to provision, just the account id + token\n\n  Provisions the isolated dev D1 database + R2 bucket (cloudflare) and sets the\n  DEV_D1_ID / CLOUDFLARE_ACCOUNT_ID repo secrets, once `vitops setup repo` has run.\n  CLOUDFLARE_API_TOKEN is always reported as blocked — no API can create one; see\n  the printed dashboard link. Requires `npx wrangler login` first.\n\nSetup domain options:\n  -i, --input <path>    Site config (default: ./site.json)\n      --site-env <env>  Environment to check (default: production)\n      --dry             Print the plan and exit\n      --check           Exit non-zero if the domain state is inconsistent\n      --domain <apex>   Print the manual cutover steps for this apex\n\n  Plans and checks the consistency between wrangler.jsonc's workers.dev/custom-domain\n  state and site.json's environments/domains/robots — it NEVER edits wrangler.jsonc\n  or deploys. Cutover overwrites the zone's DNS record and can take an existing live\n  site down; that step is manual, on purpose. See SETUP.html's \"Domain strategy\" stage.\n\nSetup search options:\n  Forwards every option to `vitops search setup` unchanged — see \"Search setup\n  options:\" above.\n\nSetup ads options:\n  Forwards every option to `vitops ads setup` unchanged — see \"Ads setup options:\"\n  above.\n\nSetup all options:\n      --dry             Print every stage's plan and exit\n      --check           Report drift across every stage and exit non-zero\n      --public          Create the repo public, for the repo stage\n      --platform <p>    cloudflare (default) | node, for the repo + hosting stages\n      --no-dev-resources  Skip D1/R2 in the hosting stage (repo stage never provisions them)\n\n  Runs repo, hosting, search, ads in order. Stops at the first stage that fails;\n  a blocked step (the API token, GitHub Pro/Team gating) is reported, not fatal.\n\nEmail subcommands:\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nEmail setup options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n  [domain]              Onboard this exact name instead of deriving candidates from\n                        config + a source scan\n      --src <dir>       Source to scan for from: literals as a supplement to config\n                        (default: ./src)\n      --dry             Print the plan and exit. Needs no credential — plans from\n                        scratch and says so.\n      --check           Report drift and exit non-zero. Mutates nothing.\n      --no-prompt       Never ask before enabling a domain (the default when\n                        stdin is not a TTY, e.g. in CI — it just enables)\n      --timeout <s>     Cap on each DNS-propagation poll wait, in seconds (default: 5)\n\n  The onboarded entity is an EXACT name, and it is usually a subdomain\n  (send.example.com), never the apex a from address names. When the exact\n  domain is absent but a sibling in the same zone is already onboarded, this\n  is reported blocked rather than silently enabling the apex too — enabling\n  it rewrites _dmarc.<domain>, which can tighten policy on every OTHER mail\n  sent from that domain. Sending from the onboarded sibling is the\n  recommended fix. Needs CLOUDFLARE_API_TOKEN (Zone:Read + an Email Sending\n  scope — broader than the \"Edit zone DNS\" template other commands use).\n\nEmail check options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for from: literals (default: ./src)\n      --strict          Exit non-zero on drift (the default just warns and exits 0)\n      --skip            Skip the check entirely (same as VITOPS_SKIP_EMAIL_CHECK)\n\n  Meant to run before a deploy. With no CLOUDFLARE_API_TOKEN it reports \"not\n  checked\" and exits 0, so a CI job without the secret never fails on the\n  check itself. Skip per-site with site.notifications.email.verifySender: false\n  when the scan can't see the real from address and the warning would be a\n  false positive.\n\nMedia options:\n      --raw <dir>       Directory of unprocessed video, walked recursively\n                        (default: ./raw)\n  -o, --out <dir>       Where the encoded outputs go (default: ./src/assets/processed).\n                        Subdirectories under --raw are preserved.\n      --max-width <px>  Cap the output width, keeping aspect ratio (default: 1920;\n                        0 disables scaling)\n      --crf <n>         Quality on VP9's scale, 0-63, lower is better (default: 32).\n                        The MP4 fallback uses the equivalent on H.264's scale.\n      --max-bitrate <r> Optional ceiling, e.g. 2M or 800k (default: none, which is\n                        constant quality rather than constrained)\n      --audio           Keep the audio track (default: dropped — the common case is\n                        a muted autoplay loop)\n      --poster-time <s> Timestamp the poster frame is taken from (default: 0, which\n                        is often black on a clip that fades in)\n      --outputs <list>  Comma-separated: webm | mp4 | poster (default: all three)\n      --manifest <path> Cache file (default: .vitops/media-manifest.json)\n      --force           Re-encode everything, ignoring the cache\n      --dry             Print the plan and exit. Encodes nothing.\n\n  Needs ffmpeg on PATH — it is an external tool, not an npm dependency, and this\n  command fails rather than quietly skipping. Commit the outputs and the manifest:\n  ffmpeg output is not reproducible across versions, so re-encoding in CI churns\n  the diff on every toolchain bump. Use --force when you mean to re-encode.\n\nCommon:\n  -h, --help            Show this help\n";
+	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? "vitops search — Google Search Console\n\n  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties\n  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "ads" ? "vitops ads — link this site to its ad properties\n\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "crm" ? "vitops crm — push form submissions into a client CRM\n\n  vitops crm check [opts]       Compare site.crm's fieldMap/trackingFields against the live CRM\n  vitops crm setup [opts]       Create missing HubSpot properties (Bigin/Jobber have no such API)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "setup" ? "vitops setup — the scripted path from an empty scaffold to a live site\n\n  vitops setup repo [opts]      GitHub repo + branch policy (main protected, dev open)\n  vitops setup hosting [opts]   Dev D1 + R2 + repo secrets (cloudflare) or a Node target\n  vitops setup domain [opts]    Plan/check the workers.dev-vs-custom-domain consistency\n                                 (never applies the cutover — see SETUP.html)\n  vitops setup search [opts]    Forwards to `vitops search setup`\n  vitops setup ads [opts]       Forwards to `vitops ads setup`\n  vitops setup all [opts]       Run repo, hosting, search, ads in order\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "email" ? "vitops email — sender-domain onboarding checks\n\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "emdash" ? "vitops emdash — build-time steps for an EmDash site\n\n  vitops emdash prepare-db           Migrate and seed the local D1 the build prerenders from\n                                     (SKIP_PREPARE_LOCAL_DB=1 skips)\n  vitops emdash check-prerender [d]  Fail if a prerendered page under [d] (default dist/client)\n                                     is not a real page\n\nRun `vitops --help` for the full option list for each subcommand.\n" : void 0) ?? "vitops — generate design-system outputs from a design-system.json\n\nAnywhere a command takes --input, that file may be a design-system.json OR the\nlarger site config that embeds one (company.json / site.json). The two are told\napart by shape, and a site config also supplies the site-level facts generation\nreads — its default colour scheme, its legal documents, its icon sprite.\n\nUsage:\n  vitops generate [options]     Generate platform output from a config\n  vitops init [options]         Scaffold a starter design-system.json\n  vitops validate <file>        Validate a config against the schema it says it is\n  vitops favicon [options]      Generate a favicon set from a source image\n  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer\n  vitops docs [topic]           Print live design-system reference docs to stdout\n  vitops lint [opts] [files]    Report classes that resolve to nothing + primitives you re-implemented\n  vitops legal [options]        Render legal documents from a site config\n  vitops robots [options]       Render robots.txt from a site config's environment\n  vitops reviews [options]      Fetch + cache Google Business Profile reviews\n  vitops icons [options]        Report which icons your source uses, and build the sprite\n  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)\n  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint\n  vitops setup <sub> [opts]     Scripted onboarding: repo, hosting, domain, search, ads, all\n  vitops email <sub> [opts]     Sender-domain onboarding: check (setup) + deploy guard (check)\n  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster\n  vitops audit [options]       Performance + accessibility budgets over a built site (Lighthouse + axe)\n\nGenerate options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n  -f, --format <list>   bricks | css | tailwind | design (comma-separated; default: bricks)\n                        design emits DESIGN.md only (the agent-facing brief) — pair it\n                        with --out . to write it beside AGENTS.md, or compose:\n                        --format css,design\n  -o, --out <dir>       Output directory (default: ./dist)\n      --theme <name>    Which designSystem.themes entry to build, when --input is\n                        a site config (default: its defaultTheme, else \"default\")\n      --site <path>     Site config, when it is a different file from --input.\n                        Emits legal/*.html into the output directory (see:\n                        vitops legal). Omitted with a plain design-system.json:\n                        no legal files.\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\nInit options:\n  -o, --out <path>      Where to write (default: ./design-system.json, or\n                        ./site.json with --site)\n      --force           Overwrite an existing file\n      --site            Write a site config (Config) instead of a bare\n                        design-system.json — embeds a starter design system at\n                        designSystem.themes.default, since a Config can't\n                        merely reference a sibling file\n      --name <name>     organization.name, when --site is set\n      --url <url>       site.environments.{production,dev}.url, when --site is set\n\nValidate options:\n  <file>                Config to check (default: ./design-system.json). Either\n                        kind — a design-system.json or the config that embeds one.\n  -i, --input <path>    Same, as a flag\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Checks the schema, then the things a schema cannot: that every role points at a\n  palette hue that exists, that every var() an authored declaration references\n  resolves to a token this config emits, and that the colour grammar is current.\n\nFavicon options:\n  -i, --input <path>    Source SVG or PNG (required)\n  -o, --out <dir>       Output directory (default: ./public)\n      --low-res <path>  Optional simplified source for the 16px icon\n      --background <hex>  Background under the maskable icons, which must be\n                        opaque (default: #ffffff)\n\nAgents options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json;\n                        validated if present)\n      --theme <name>    Theme to read, when --input is a site config\n  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)\n      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir\n                        instead of linking the packaged skill\n\nDocs options:\n  <topic>               classes | authoring | formats | color | scales | patterns | elements\n                        (no topic: list topics with summaries)\n  -i, --input <path>    site config or design-system.json (default: ./site.json, else\n                        ./design-system.json)\n      --theme <name>    Theme to render docs from, when --input is a site config\n      --all             Print every topic, concatenated\n\nIcons options:\n  -i, --input <path>    Site config carrying the \"icons\" block (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for icon usage (default: ./src)\n      --sprite          Also build the SVG sprite\n  -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)\n      --json            Machine-readable report on stdout\n\nLint options:\n  -i, --input <path>    site config or design-system.json (default: ./site.json, else\n                        ./design-system.json)\n      --theme <name>    Theme to judge classes against, when --input is a site config\n  -f, --format <fmt>    Format you build (bricks | css | tailwind; default: bricks).\n                        Responsive md-* classes are real in css/bricks, inert in tailwind.\n  -s, --src <dir>       Directory to scan (default: ./src)\n      --strict          Also fail on suggestions (reuse hints), not just on\n                        classes that resolve to nothing\n  [files...]            Lint these paths instead of scanning --src. Unreadable\n                        and non-source paths are skipped, so this can be wired\n                        into a pre-commit hook that appends the staged files.\n      --fix             Rewrite pre-1.0 colour-grammar token references\n                        (var(--<role>-<suffix>) → var(--color-<target>-<role>…))\n                        in CSS and <style> blocks. Applied in ONE pass, so the\n                        renames that rotate cannot compound. Nothing else is\n                        rewritten — every other finding is a judgement call.\n\n  Run this after a major bump: it is the migration tool for anything the\n  changelog says was renamed.\n\nLegal options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -d, --doc <name>      privacy | terms | cookies (repeatable; default: those\n                        enabled in the config)\n  -f, --format <fmt>    md | html | portable-text (default: md)\n                        html suits WordPress/Bricks and plain sites;\n                        portable-text suits EmDash\n  -o, --out <dir>       Write files here (default: print to stdout)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Generated from your config — a starting point, not legal advice. Review before\n  publishing, and make sure the config describes what your site actually does.\n\nRobots options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -o, --out <dir>       Write robots.txt here (default: print to stdout)\n      --site-env <env>  Which site.environments entry to render for (default: production)\n\n  Reads the resolved environment's robots directive (falling back to\n  site.seo.robots) — the same fact vitops search notify's noindex gate already\n  reads. A directive containing noindex disallows every user agent and emits\n  no Sitemap line; otherwise it allows everything and links\n  site.seo.indexing.sitemapUrl, or the derived <canonical>/sitemap-index.xml.\n\nReviews options:\n  -i, --input <path>    Site config carrying site.reviews (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --location <key>  Fetch only this site.reviews.locations key\n      --cache <path>    Where to read/write the cache (default: .vitops/reviews.json)\n      --out <dir>       Also write the selected reviews per location as JSON here\n      --dry             Print the plan and exit. Fetches nothing.\n      --check           Fetch and diff against the cache; exit non-zero on drift.\n                        Mutates nothing.\n\n  Reviews live only on the legacy Business Profile v4 API — there is no newer\n  replacement — and the calling GCP project must be allowlisted by Google before\n  any call succeeds (a one-time approval; a 403 says so rather than failing\n  opaquely). Auth is user OAuth, the same VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (or ADC login) that\n  vitops search setup uses, scoped to business.manage. The cache is meant to be\n  committed: reviews change slowly, and a build should not need a live Google\n  credential. Review JSON-LD is off by default (site.reviews.schema) — a business\n  marking up reviews of itself is not eligible for Google's rich results and\n  risks a manual action.\n\nSearch subcommands:\n  vitops search setup [opts]    Onboard site.searchConsole domains into GSC\n  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)\n\nSearch setup options:\n  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --domain <name>   Scope to a single site.searchConsole entry\n      --dry             Print the plan and exit. Changes nothing, and runs without\n                        credentials (planning from scratch, which it says).\n      --check           Report drift and exit non-zero if any domain is not fully\n                        onboarded. Mutates nothing, but does need credentials —\n                        drift is a comparison against live state.\n\n  For each domain it ensures the apex verification TXT in Cloudflare, verifies\n  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-\n  unverified domain is reported PENDING, not failed), adds the sc-domain: property,\n  and adds any delegatedOwners to the web resource. DNS is only ever created,\n  never edited or deleted. Credentials come from the environment:\n  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit + Zone:Read — the standard \"Edit zone DNS\"\n  template covers both; Zone:Read is what the zone-by-name lookup uses), and\n  VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token\n  scoped to siteverification + webmasters). Granting a Google Group Full-User\n  access has no API and is surfaced as a reminder.\n\n  Or just be logged in: with no VITOPS_GOOGLE_* set, an Application Default\n  Credentials login is used —\n    gcloud auth application-default login \\\n      --scopes=openid,https://www.googleapis.com/auth/siteverification,\\\n  https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/cloud-platform\n  ADC authenticates through a shared OAuth client that owns no project, so it also\n  needs site.google.project in the config (sent as x-goog-user-project), both APIs\n  enabled on that project, and serviceusage.services.use on it. One project per site\n  is what keeps each site's API usage and billing separate.\n\nSearch notify options:\n  -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)\n      --site-env <env>  Environment to notify for (default: production). An\n                        environment whose robots policy says noindex is refused.\n      --sitemap <src>   Sitemap URL or local path (default: from the config)\n      --urls <list>     Comma-separated URLs to submit, skipping the diff\n      --all             Submit every URL in the sitemap, not just what changed\n      --dry             Print the plan and exit. Makes no requests.\n      --check           Read-only: ask Google whether seo.indexing.priorityUrls\n                        are indexed. Exits non-zero if one is not.\n      --new-key         Print a fresh IndexNow key and exit\n      --write-key <dir> Write the IndexNow key file into <dir> (for stacks with\n                        no Astro integration to do it — Bricks, WordPress)\n      --snapshot <path> Changed-URL state file (default: .vitops/sitemap-snapshot.json).\n                        Persist it between runs (a CI cache) or every run submits\n                        everything.\n\n  What notify can and cannot do: Google exposes no \"request indexing\" API, and its\n  sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap\n  through the Search Console API and verifies the result with --check. IndexNow\n  reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.\n  Search Console takes either credential, whichever you already have, added as an\n  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline\n  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth\n  credential \"search setup\" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /\n  _REFRESH_TOKEN). The service account is preferred when both are set — this runs\n  on every deploy, and it does not expire.\n\nAds subcommands:\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nAds setup options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --provider <name> Scope to one site.ads entry (google | meta | linkedin |\n                        reddit | tiktok | microsoft | pinterest | snapchat)\n      --dry             Print the plan and exit. Creates nothing. With\n                        CLOUDFLARE_API_TOKEN set it reads live DNS first, so the\n                        plan says what is already done; without one it plans from\n                        scratch and says so, rather than refusing to run.\n      --check           Report drift and exit non-zero if any property is not\n                        linked. Mutates nothing, prompts for nothing.\n      --no-prompt       Never ask for a missing token; fail with the field name\n                        instead (the default when stdin is not a TTY, e.g. in CI)\n      --no-write        Don't persist an answered token back into the config\n\n  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —\n  and that record is the one thing this creates for you (in Cloudflare, via\n  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,\n  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking\n  there is the tag and the account ID, and the run says so rather than skipping in\n  silence. No platform Marketing API is called — Meta's needs a system-user token\n  and Google's needs an approved developer token, so the final \"Verify\" click stays\n  a reminder. The verification token is not a secret (it is published in DNS, which\n  is the ownership proof), so it lives in the config and is prompted for on the\n  first run.\n\nAds tags options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --provider <name> Print one platform's tag\n      --strategy <s>    idle | async | interaction (default: idle)\n\n  Prints each pixel as an INERT, consent-gated <script>: type=\"text/plain\" with the\n  library URL on data-src, so an undecided visitor's page issues no third-party\n  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.\n  Paste into your template; @getvitops/core's consent runtime activates them.\n\nAds lint options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n\n  Reports the gaps that are invisible at runtime: a click-ID parameter this\n  platform stamps that attribution doesn't capture, a pixel while site.tracking is\n  off (every conversion arrives unattributed), and a configured property with no\n  tag ID. Exits non-zero on a finding.\n\nCrm check options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n\n  Fetches the live field/property list (HubSpot: crm/v3/properties/contacts;\n  Bigin: bigin/v2/settings/fields) and reports every fieldMap/trackingFields\n  target that doesn't exist there. HubSpot rejects a submission naming an\n  unrecognised property; Bigin silently ignores it — this is the only way to\n  see a broken mapping before a real submission finds it. Needs\n  VITOPS_HUBSPOT_ACCESS_TOKEN, VITOPS_ZOHO_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, or (unused for now) VITOPS_JOBBER_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, matching whichever provider site.crm names. Jobber currently\n  renders fieldMap/trackingFields as note-text lines rather than app-configured\n  custom fields, so there is nothing live to check there yet. Exits non-zero\n  on any missing target.\n\nCrm setup options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n      --dry             Print what would be created and exit. Creates nothing.\n\n  HubSpot: creates missing contact properties named by fieldMap/trackingFields.\n  Bigin: no such API exists, so this always prints a manual reminder listing\n  the fields to add in Zoho Bigin's field editor, then re-run \"crm check\".\n  Jobber: app-configured custom fields aren't wired up yet, so this prints a\n  reminder instead of creating anything.\n\nSetup repo options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --public          Create the repo public (default: private)\n      --platform <p>    cloudflare (default) | node — shown for parity with the hosting stage's plan\n      --no-dev-resources  Same — this stage never provisions D1/R2 either way\n\n  Creates the GitHub repo (via `gh`), pushes main + dev, makes dev the default\n  branch, and requests main branch protection + the production/dev environments.\n  Idempotent — a re-run of a fully set-up repo is all skips. Branch protection and\n  environment reviewers 403 on a private repo without GitHub Pro/Team; that is\n  reported as blocked, with the manual Settings path, never as a failure.\n\nSetup hosting options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --platform <p>    cloudflare (default) | node\n      --no-dev-resources  Skip D1/R2 — a pure static Workers Assets project has\n                        nothing to provision, just the account id + token\n\n  Provisions the isolated dev D1 database + R2 bucket (cloudflare) and sets the\n  DEV_D1_ID / CLOUDFLARE_ACCOUNT_ID repo secrets, once `vitops setup repo` has run.\n  CLOUDFLARE_API_TOKEN is always reported as blocked — no API can create one; see\n  the printed dashboard link. Requires `npx wrangler login` first.\n\nSetup domain options:\n  -i, --input <path>    Site config (default: ./site.json)\n      --site-env <env>  Environment to check (default: production)\n      --dry             Print the plan and exit\n      --check           Exit non-zero if the domain state is inconsistent\n      --domain <apex>   Print the manual cutover steps for this apex\n\n  Plans and checks the consistency between wrangler.jsonc's workers.dev/custom-domain\n  state and site.json's environments/domains/robots — it NEVER edits wrangler.jsonc\n  or deploys. Cutover overwrites the zone's DNS record and can take an existing live\n  site down; that step is manual, on purpose. See SETUP.html's \"Domain strategy\" stage.\n\nSetup turnstile options:\n  -i, --input <path>    Site config (default: ./site.json)\n      --site-env <env>  Environment to read (default: production)\n      --dry             Print the plan and exit (needs no token)\n      --check           Exit non-zero if no widget/site key is set up; mutates nothing\n      --no-write        Do not write site.security.turnstile.siteKey back to the config\n      --no-secret       Do not run `wrangler secret put` for the new widget's secret\n\n  Creates a managed Turnstile widget for the site's hostnames (canonical + each\n  environment URL) unless one already covers them, and writes the PUBLIC site key to\n  site.security.turnstile.siteKey. The SECRET is returned once at creation: it is piped\n  to `wrangler secret put VITOPS_TURNSTILE_SECRET` and never written to a config file.\n  Never edits, rotates or deletes an existing widget.\n  Needs CLOUDFLARE_API_TOKEN with \"Account > Turnstile > Edit\", plus CLOUDFLARE_ACCOUNT_ID\n  (or a token that can list accounts), and `wrangler login` for the secret.\n\nSetup search options:\n  Forwards every option to `vitops search setup` unchanged — see \"Search setup\n  options:\" above.\n\nSetup ads options:\n  Forwards every option to `vitops ads setup` unchanged — see \"Ads setup options:\"\n  above.\n\nSetup all options:\n      --dry             Print every stage's plan and exit\n      --check           Report drift across every stage and exit non-zero\n      --public          Create the repo public, for the repo stage\n      --platform <p>    cloudflare (default) | node, for the repo + hosting stages\n      --no-dev-resources  Skip D1/R2 in the hosting stage (repo stage never provisions them)\n\n  Runs repo, hosting, search, ads in order. Stops at the first stage that fails;\n  a blocked step (the API token, GitHub Pro/Team gating) is reported, not fatal.\n\nEmdash subcommands:\n  vitops emdash prepare-db           Migrate and seed the local D1 the build prerenders from\n  vitops emdash check-prerender [d]  Fail if a prerendered page is not a real page\n\nEmdash prepare-db options:\n  (none)  Starts `astro dev` once, calls EmDash's dev-bypass setup (migrates, applies the\n          seed's sample content), checks the home page renders, stops. Only writes the\n          disposable .wrangler/state. SKIP_PREPARE_LOCAL_DB=1 skips it.\n\nEmdash check-prerender options:\n  [dir]   Build output to check (default: dist/client). Fails on a page that carries the\n          pending-migrations message, is not an HTML document, or has no <title>.\n  --strict  Also fail (not just warn) when a page uses a type-role class (font-display, …)\n          the built CSS has no rule for.\n\nEmail subcommands:\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nEmail setup options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n  [domain]              Onboard this exact name instead of deriving candidates from\n                        config + a source scan\n      --src <dir>       Source to scan for from: literals as a supplement to config\n                        (default: ./src)\n      --dry             Print the plan and exit. Needs no credential — plans from\n                        scratch and says so.\n      --check           Report drift and exit non-zero. Mutates nothing.\n      --no-prompt       Never ask before enabling a domain (the default when\n                        stdin is not a TTY, e.g. in CI — it just enables)\n      --timeout <s>     Cap on each DNS-propagation poll wait, in seconds (default: 5)\n\n  The onboarded entity is an EXACT name, and it is usually a subdomain\n  (send.example.com), never the apex a from address names. When the exact\n  domain is absent but a sibling in the same zone is already onboarded, this\n  is reported blocked rather than silently enabling the apex too — enabling\n  it rewrites _dmarc.<domain>, which can tighten policy on every OTHER mail\n  sent from that domain. Sending from the onboarded sibling is the\n  recommended fix. Needs CLOUDFLARE_API_TOKEN (Zone:Read + an Email Sending\n  scope — broader than the \"Edit zone DNS\" template other commands use).\n\nEmail check options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for from: literals (default: ./src)\n      --strict          Exit non-zero on drift (the default just warns and exits 0)\n      --skip            Skip the check entirely (same as VITOPS_SKIP_EMAIL_CHECK)\n\n  Meant to run before a deploy. With no CLOUDFLARE_API_TOKEN it reports \"not\n  checked\" and exits 0, so a CI job without the secret never fails on the\n  check itself. Skip per-site with site.notifications.email.verifySender: false\n  when the scan can't see the real from address and the warning would be a\n  false positive.\n\nMedia options:\n      --raw <dir>       Directory of unprocessed video, walked recursively\n                        (default: ./raw)\n  -o, --out <dir>       Where the encoded outputs go (default: ./src/assets/processed).\n                        Subdirectories under --raw are preserved.\n      --max-width <px>  Cap the output width, keeping aspect ratio (default: 1920;\n                        0 disables scaling)\n      --crf <n>         Quality on VP9's scale, 0-63, lower is better (default: 32).\n                        The MP4 fallback uses the equivalent on H.264's scale.\n      --max-bitrate <r> Optional ceiling, e.g. 2M or 800k (default: none, which is\n                        constant quality rather than constrained)\n      --audio           Keep the audio track (default: dropped — the common case is\n                        a muted autoplay loop)\n      --poster-time <s> Timestamp the poster frame is taken from (default: 0, which\n                        is often black on a clip that fades in)\n      --outputs <list>  Comma-separated: webm | mp4 | poster (default: all three)\n      --manifest <path> Cache file (default: .vitops/media-manifest.json)\n      --force           Re-encode everything, ignoring the cache\n      --dry             Print the plan and exit. Encodes nothing.\n\n  Needs ffmpeg on PATH — it is an external tool, not an npm dependency, and this\n  command fails rather than quietly skipping. Commit the outputs and the manifest:\n  ffmpeg output is not reproducible across versions, so re-encoding in CI churns\n  the diff on every toolchain bump. Use --force when you mean to re-encode.\n\nAudit options:\n      --build           Run `astro build` first (default: audit the existing build)\n      --url <base>      Audit an already-running server instead of `astro preview`\n      --port <n>        Port for `astro preview` (default: 4398; aborts if taken)\n      --dir <path>      Project directory (default: .)\n      --pages <list>    Extra comma-separated paths. The page list is the built sitemap\n                        plus links in seed/seed.json's primary* and footer* menus; only\n                        when neither exists are / /privacy /terms /cookies /contact\n                        guessed. A 404 skips a page (with its reason in the report); a\n                        404 on / fails the run.\n      --no-defaults     Never guess the default pages\n      --seed <path>     EmDash seed to read menus from (default: seed/seed.json if present)\n      --lcp <ms>        LCP budget (default: 2500)\n      --cls <n>         CLS budget (default: 0.1)\n      --tbt <ms>        Total Blocking Time budget, the INP proxy (default: 200)\n      --impact <list>   axe impacts that fail a page (default: serious,critical)\n      --form-factor <f> mobile | desktop Lighthouse profile (default: mobile)\n  -o, --out <dir>       Report directory (default: .vitops/audit): report.json, report.md,\n                        and pages/<page>.{json,md}\n      --warn            Report without failing (exit 0), for first adoption\n\n  Needs the optional packages: vp add -D playwright @axe-core/playwright lighthouse\n  && vp exec playwright install chromium (checked before any server starts). A pass means no automated axe violations and the\n  budgets held — it is NOT AODA certification; report.md lists the manual checks.\n\nCommon:\n  -h, --help            Show this help\n";
 }
 
 // src/commands/search.ts
@@ -1666,6 +1739,163 @@ async function cmdAds(argv) {
 	}
 }
 
+// src/commands/audit.ts
+/**
+* `vitops audit` — performance + accessibility budgets over a built site.
+*
+* The planner (page discovery, status handling, budgets, report rendering) is pure and
+* lives in `@getvitops/utils/audit` beside `ads/`, `indexing/` and `onboarding/`, as
+* `plan.ts`; this file is wiring only — flags in, files + exit code out. The browser
+* tooling (Playwright, axe, Lighthouse) is lazy and optional, see `audit/run.ts`.
+*/
+/** Dedicated port: not Astro's 4321, which a developer's own `astro dev` is likely on. */
+const DEFAULT_PORT = 4398;
+function num(flag, raw, fallback) {
+	if (raw === void 0) return fallback;
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n <= 0) fail(`audit: --${flag} must be a positive number`);
+	return n;
+}
+async function cmdAudit(argv) {
+	const args = parse$1(argv, {
+		dir: {
+			type: "string",
+			default: "."
+		},
+		url: { type: "string" },
+		build: {
+			type: "boolean",
+			default: false
+		},
+		port: { type: "string" },
+		pages: { type: "string" },
+		"no-defaults": {
+			type: "boolean",
+			default: false
+		},
+		seed: { type: "string" },
+		out: {
+			type: "string",
+			short: "o",
+			default: ".vitops/audit"
+		},
+		lcp: { type: "string" },
+		cls: { type: "string" },
+		tbt: { type: "string" },
+		impact: { type: "string" },
+		"form-factor": {
+			type: "string",
+			default: "mobile"
+		},
+		warn: {
+			type: "boolean",
+			default: false
+		}
+	});
+	const dir = resolve(args.str("dir"));
+	const formFactor = args.str("form-factor");
+	if (formFactor !== "mobile" && formFactor !== "desktop") fail("audit: --form-factor must be mobile or desktop");
+	let impacts = DEFAULT_BUDGETS.blockingImpacts;
+	const impactFlag = args.opt("impact");
+	if (impactFlag) try {
+		impacts = parseImpacts(impactFlag);
+	} catch (err) {
+		fail(`audit: ${msg(err)}`);
+	}
+	const budgets = {
+		lcpMs: num("lcp", args.opt("lcp"), DEFAULT_BUDGETS.lcpMs),
+		cls: num("cls", args.opt("cls"), DEFAULT_BUDGETS.cls),
+		tbtMs: num("tbt", args.opt("tbt"), DEFAULT_BUDGETS.tbtMs),
+		blockingImpacts: impacts
+	};
+	const seedFlag = args.opt("seed");
+	const seedPath = seedFlag ? resolve(seedFlag) : join(dir, "seed", "seed.json");
+	let menuPaths = [];
+	if (existsSync(seedPath)) try {
+		menuPaths = pathsFromSeed(JSON.parse(readFileSync(seedPath, "utf8")));
+	} catch (err) {
+		fail(`audit: could not read menus from ${seedPath}: ${msg(err)}`);
+	}
+	else if (seedFlag) fail(`audit: seed not found: ${seedPath}`);
+	if (args.flag("build") && !args.opt("url")) {
+		console.log("▸ building (astro build)");
+		try {
+			await runCommand("npx", [
+				"--no-install",
+				"astro",
+				"build"
+			], dir);
+		} catch (err) {
+			fail(`audit: build failed: ${msg(err)}`);
+		}
+	}
+	try {
+		await preflight();
+	} catch (err) {
+		fail(`audit: ${msg(err)}`);
+	}
+	let server;
+	let baseUrl = args.opt("url");
+	const stopServer = () => server?.stop();
+	const onSignal = (signal) => {
+		stopServer();
+		process.exit(signal === "SIGINT" ? 130 : 143);
+	};
+	process.once("SIGINT", onSignal);
+	process.once("SIGTERM", onSignal);
+	process.once("exit", stopServer);
+	try {
+		if (!baseUrl) {
+			const port = num("port", args.opt("port"), DEFAULT_PORT);
+			console.log(`▸ astro preview on :${port}`);
+			server = await startPreview({
+				cwd: dir,
+				port
+			});
+			baseUrl = server.baseUrl;
+		}
+		const sitemapPaths = await fetchSitemapPaths(baseUrl);
+		const paths = planPages({
+			sitemapPaths,
+			menuPaths,
+			extra: (args.opt("pages") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+			includeDefaults: !args.flag("no-defaults")
+		});
+		console.log(sitemapPaths.length ? `▸ ${sitemapPaths.length} page(s) from the sitemap` : "▸ no sitemap found; using menus and defaults");
+		console.log(`▸ auditing ${paths.length} candidate page(s) at ${baseUrl} (${formFactor})`);
+		const pages = await runAudit({
+			baseUrl,
+			paths,
+			budgets,
+			formFactor,
+			onProgress: (m) => console.log(`  ${m}`)
+		});
+		const report = buildReport({
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			baseUrl,
+			formFactor,
+			budgets,
+			pages
+		});
+		const out = resolve(dir, args.str("out"));
+		for (const [name, contents] of Object.entries(reportFiles(report))) {
+			const file = join(out, name);
+			mkdirSync(dirname(file), { recursive: true });
+			writeFileSync(file, contents);
+		}
+		console.log(`\n${formatSummary$2(report)}\n\nReport: ${join(out, "report.md")}`);
+		if (!report.passed) {
+			if (args.flag("warn")) console.log("(--warn: reporting only, exit 0)");
+			else process.exitCode = 1;
+		}
+	} catch (err) {
+		server?.stop();
+		fail(`audit: ${msg(err)}`);
+	} finally {
+		server?.stop();
+	}
+}
+
 // src/commands/crm.ts
 /**
 * `vitops crm` — the two things `site.crm` needs a human-in-the-loop for.
@@ -2084,7 +2314,7 @@ async function cmdEmailSetup(argv) {
 			reminders
 		});
 	}
-	console.log(`\n${formatSummary$2(results)}`);
+	console.log(`\n${formatSummary$3(results)}`);
 	for (const n of dynamicNotes) console.log(n);
 	for (const f of failures) console.error(`! ${f}`);
 	if (failed) process.exit(1);
@@ -2164,6 +2394,202 @@ async function cmdEmail(argv) {
 	}
 }
 
+// src/prerender-check.ts
+/**
+* The pure half of `vitops emdash check-prerender`: is a prerendered `.html` body a real page?
+*
+* `astro build` succeeds even when a prerendered route's response was an error. Against a local
+* database with pending migrations EmDash answers with a one-line "Database migrations are
+* required" body, which is written to `index.html` like any other page, and the deploy then
+* publishes it.
+*/
+const PENDING_MIGRATIONS = /Database migrations are required/i;
+/** Why `html` is not a real page, or `undefined` when it looks like one. */
+function prerenderProblem(html) {
+	if (PENDING_MIGRATIONS.test(html)) return "carries the pending-migrations message";
+	if (!/<html[\s>]/i.test(html)) return "is not an HTML document";
+	if (!/<title>[^<]+<\/title>/i.test(html)) return "has no <title>";
+}
+const TYPE_ROLE_CLASS = new RegExp(`^font-(?:${[
+	"display",
+	"title",
+	"heading",
+	"body",
+	"quote",
+	"caption",
+	"eyebrow",
+	"code",
+	"lead",
+	"footnote",
+	"tag"
+].join("|")})$`);
+/** Every `class="…"` token in a page. */
+function classesIn(html) {
+	const out = /* @__PURE__ */ new Set();
+	for (const m of html.matchAll(/\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) for (const token of (m[1] ?? m[2] ?? "").split(/\s+/)) if (token) out.add(token);
+	return out;
+}
+/**
+* Type-role classes a page uses that the built stylesheet has no rule for.
+*
+* Tailwind v4 does not scan `node_modules`, so a utility used only by a package's own renderer
+* (`font-display` in `vitops.stats`) was never generated, and the page rendered at body size with
+* no error. The type roles are the one family checkable without the site's config: the list is
+* closed. A class is "defined" when the CSS names it as a selector.
+*/
+function missingTypeRoleRules(html, css) {
+	const defined = (cls) => new RegExp(`\\.${cls}(?![\\w-])`).test(css);
+	return [...classesIn(html)].filter((c) => TYPE_ROLE_CLASS.test(c) && !defined(c)).sort();
+}
+
+// src/commands/emdash.ts
+/**
+* `vitops emdash` — build-time steps for an EmDash site on the Cloudflare adapter.
+*
+* These used to be copied into every scaffold as `scripts/*.mjs`, which froze each fix at
+* scaffold time. As commands they arrive with `@getvitops/cli`, so a site's `package.json`
+* keeps one-line entries and `vp update` delivers the logic (the same move `vitops setup`
+* made for the template's old `init-github`/`init-hosting` scripts).
+*
+*   prepare-db        migrate and seed the LOCAL D1 the build prerenders from
+*   check-prerender   fail if a prerendered page is not a real page
+*
+* Why both exist: `astro build` prerenders every page inside a local workerd against a local D1
+* (`.wrangler/state`), never the deployed database. The template sets
+* `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 the build still succeeds. A fresh CI runner, a first deploy, a `SKIP_PULL_CONTENT=1`
+* build and an upgrade deploy all hand the build exactly that database.
+*/
+function freePort() {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const { port } = server.address() ?? { port: 0 };
+			server.close(() => resolve(port));
+		});
+	});
+}
+async function until(test, what, ms = 12e4) {
+	const deadline = Date.now() + ms;
+	while (Date.now() < deadline) {
+		try {
+			if (await test()) return;
+		} catch {}
+		await new Promise((r) => setTimeout(r, 1e3));
+	}
+	throw new Error(`timed out waiting for ${what}`);
+}
+const log = (msg) => console.log(`prepare-db: ${msg}`);
+/**
+* `astro dev` daemonizes: the child outlives the command that started it, so capturing its
+* output through pipes would leave this process waiting on the daemon's inherited handles,
+* which looks exactly like a hang. Output is ignored and every call has a timeout.
+*/
+const astro = (args) => spawnSync(existsSync("node_modules/.bin/astro") ? "node_modules/.bin/astro" : "astro", args, {
+	stdio: "ignore",
+	timeout: 3e5,
+	env: {
+		...process.env,
+		CI: "1"
+	}
+});
+/**
+* Starts `astro dev` once, calls EmDash's `dev-bypass` setup endpoint (the non-interactive
+* setup wizard: it runs migrations, `dev: 'auto'`, and applies the seed), checks the home page
+* renders, stops. Only ever writes the local `.wrangler/state`, which is disposable; the dev
+* administrator it creates lives in that copy and is never deployed. Content already there
+* (from `pull-content`) is kept: the seed applies with `onConflict: skip`.
+*/
+async function cmdPrepareDb() {
+	if (process.env.SKIP_PREPARE_LOCAL_DB) {
+		log("SKIP_PREPARE_LOCAL_DB set — leaving the local database as it is.");
+		return;
+	}
+	const port = await freePort();
+	const base = `http://127.0.0.1:${port}`;
+	log(`starting astro dev on ${base} ...`);
+	const started = astro([
+		"dev",
+		"--port",
+		String(port),
+		"--host",
+		"127.0.0.1"
+	]);
+	if (started.error?.code === "ENOENT") fail("`astro` is not on PATH. Run it through the package scripts (`vpr prepare-local-db`).");
+	if (started.status !== 0) fail(`could not start astro dev (${started.signal ?? `exit ${started.status}`}). It is killed after 5 minutes (exit 143 = SIGTERM). Run \`astro dev\` by hand to see why.`);
+	let failure = null;
+	try {
+		await until(async () => (await fetch(`${base}/_emdash/api/setup/status`)).ok, "astro dev");
+		log("dev server is up; migrating and seeding (first run can take a minute) ...");
+		const setup = await fetch(`${base}/_emdash/api/setup/dev-bypass?redirect=/`, {
+			redirect: "manual",
+			signal: AbortSignal.timeout(12e4)
+		});
+		if (setup.status >= 400) console.warn(`prepare-db: dev-bypass answered ${setup.status}; checking the home page anyway.`);
+		const home = await fetch(`${base}/`);
+		const html = await home.text();
+		if (!home.ok) throw new Error(`astro dev answered ${home.status} on / — the dev runtime is broken`);
+		if (PENDING_MIGRATIONS.test(html)) throw new Error("the local database still has pending migrations");
+		log("the local database is migrated and the home page renders.");
+	} catch (e) {
+		failure = e;
+	} finally {
+		astro(["dev", "stop"]);
+	}
+	if (failure) fail(`${failure.message}\nRefusing to continue: prerendering now would publish error pages as the site.`);
+}
+function* filesWith(dir, ext) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) yield* filesWith(path, ext);
+		else if (entry.name.endsWith(ext)) yield path;
+	}
+}
+const htmlFiles = (dir) => filesWith(dir, ".html");
+const cssFiles = (dir) => [...filesWith(dir, ".css")];
+function cmdCheckPrerender(argv) {
+	const root = argv.find((a) => !a.startsWith("-")) ?? "dist/client";
+	const strict = argv.includes("--strict");
+	if (!existsSync(root)) fail(`${root} does not exist (run \`astro build\` first).`);
+	const bad = [];
+	const unstyled = [];
+	const css = cssFiles(root).map((f) => readFileSync(f, "utf8")).join("\n");
+	let count = 0;
+	for (const file of htmlFiles(root)) {
+		count += 1;
+		const html = readFileSync(file, "utf8");
+		const why = prerenderProblem(html);
+		if (why) bad.push(`  ${file} ${why}`);
+		else if (css) {
+			const missing = missingTypeRoleRules(html, css);
+			if (missing.length) unstyled.push(`  ${file}: ${missing.join(", ")}`);
+		}
+	}
+	if (count === 0) fail(`no .html files under ${root}.`);
+	if (bad.length) fail(`the build prerendered pages that are not real pages:\n${bad.join("\n")}\n\nThe local database the build reads is probably unmigrated. Run \`vpr prepare-local-db\` (it migrates and seeds the local D1 through \`astro dev\`), then build again.`);
+	if (unstyled.length) {
+		const note = `type-role classes with no rule in the built CSS (they render at body size):\n${unstyled.join("\n")}\n\nTailwind does not scan node_modules. Use @getvitops/astro >= the release that adds the \`@source\` lines, or add \`@source\` for the package that renders them to the site's stylesheet.`;
+		if (strict) fail(note);
+		console.warn(`check-prerender: warning: ${note}`);
+	}
+	console.log(`check-prerender: ${count} prerendered page(s) look like real pages.`);
+}
+async function cmdEmdash(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "prepare-db": return cmdPrepareDb();
+		case "check-prerender": return cmdCheckPrerender(rest);
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(EMDASH_HELP);
+			return;
+		default: fail(`unknown "emdash" subcommand "${sub}" (expected: prepare-db | check-prerender). Try: vitops --help`);
+	}
+}
+
 // src/commands/setup.ts
 /**
 * `vitops setup` — the scripted path from an empty scaffold to a live site.
@@ -2188,6 +2614,7 @@ const SETUP_HELP = `vitops setup <sub> [options]
   vitops setup repo    [--dry] [--check] [--public]
   vitops setup hosting [--dry] [--check] [--platform cloudflare|node]
   vitops setup domain  [--dry] [--check] [--domain <apex>]
+  vitops setup turnstile [--dry] [--check] [--no-write] [--no-secret]
   vitops setup search  [options]   (forwards to \`vitops search setup\`)
   vitops setup ads     [options]   (forwards to \`vitops ads setup\`)
   vitops setup all     [--dry] [--check] [--public] [--platform <p>]
@@ -2355,7 +2782,7 @@ async function cmdSetupRepo(argv) {
 		status: "blocked",
 		detail: "no GitHub repo yet — run this again once \"repo\" succeeds"
 	});
-	console.log(formatSummary$3(results));
+	console.log(formatSummary$4(results));
 	if (results.some((r) => r.status === "failed")) process.exit(1);
 }
 async function cmdSetupHosting(argv) {
@@ -2465,7 +2892,7 @@ async function cmdSetupHosting(argv) {
 		status: "blocked",
 		detail: p.secrets["CLOUDFLARE_API_TOKEN"]?.detail ?? "create it by hand"
 	});
-	console.log(formatSummary$3(results));
+	console.log(formatSummary$4(results));
 	for (const n of p.notes) console.log(`! ${n}`);
 	if (results.some((r) => r.status === "failed")) process.exit(1);
 }
@@ -2501,6 +2928,157 @@ async function cmdSetupDomain(argv) {
 	if (a.opt("domain")) console.log(`\nCutover is never applied by this command — see SETUP.html stage 4b. To cut over: uncomment routes in wrangler.jsonc with "pattern": "${a.opt("domain")}", deploy, then update site.domains.canonical and site.environments.${a.str("site-env")}.url to match.`);
 	if (a.flag("check") && step.action !== "skip") process.exit(1);
 }
+/**
+* Create the Cloudflare Turnstile widget for the site and record its PUBLIC site key.
+*
+* The secret is returned by Cloudflare only at creation. It is never written to a config
+* file: it is piped to `wrangler secret put VITOPS_TURNSTILE_SECRET` on stdin (never argv,
+* never logged). If that fails, it is shown once on an interactive terminal and otherwise
+* not at all, with the rotate instruction. Never edits, rotates or deletes a widget.
+*/
+async function cmdSetupTurnstile(argv) {
+	const a = parse$1(argv, {
+		...SITE_OPTS,
+		dry: {
+			type: "boolean",
+			default: false
+		},
+		check: {
+			type: "boolean",
+			default: false
+		},
+		"no-write": {
+			type: "boolean",
+			default: false
+		},
+		"no-secret": {
+			type: "boolean",
+			default: false
+		}
+	});
+	const input = a.path("input");
+	const cfg = await loadConfig(input, a.str("site-env"));
+	const dry = a.flag("dry");
+	const check = a.flag("check");
+	const token = loadCloudflareToken();
+	if (!token && !dry) fail(`${CLOUDFLARE_TOKEN_HINT}\n  For this command the token needs "Account > Turnstile > Edit" (also set CLOUDFLARE_ACCOUNT_ID, or the token must be able to list accounts).`);
+	const setup = {
+		name: (() => {
+			const n = cfg.organization?.name;
+			return (typeof n === "string" ? n : n ? Object.values(n)[0] : void 0) ?? projectName();
+		})(),
+		domains: deriveDomains(cfg.site),
+		siteKey: cfg.site.security?.turnstile?.siteKey
+	};
+	let accountId;
+	let widgets = [];
+	if (token) {
+		const acct = await resolveAccountId(token, process.env.CLOUDFLARE_ACCOUNT_ID || void 0);
+		if (!acct.ok) {
+			if (!dry) fail(`Cloudflare account: ${acct.message}`);
+		} else {
+			accountId = acct.accountId;
+			const listed = await listWidgets(token, accountId);
+			if (!listed.ok) fail(`listing Turnstile widgets: ${listed.message}`);
+			widgets = listed.widgets;
+		}
+	}
+	const p = plan$5(setup, {
+		accountId,
+		widgets
+	});
+	if (dry || check) {
+		console.log(formatPlan$7(p));
+		if (check && hasDrift$3(p)) {
+			console.error("\n✖ Turnstile is not set up");
+			process.exit(1);
+		}
+		return;
+	}
+	const results = [];
+	let siteKey = p.adopt?.sitekey;
+	if (p.widget.action === "blocked") results.push({
+		step: "widget",
+		status: "blocked",
+		detail: p.widget.detail
+	});
+	else if (p.widget.action === "create") {
+		const r = await createWidget(token, accountId, {
+			name: setup.name,
+			domains: p.domains
+		});
+		if (!r.ok) results.push({
+			step: "widget",
+			status: "failed",
+			detail: r.message ?? "failed"
+		});
+		else {
+			siteKey = r.sitekey;
+			results.push({
+				step: "widget",
+				status: "created",
+				detail: r.sitekey
+			});
+			if (a.flag("no-secret")) console.error("! --no-secret: the secret was NOT saved and cannot be read back. Rotate it in the dashboard, then `wrangler secret put VITOPS_TURNSTILE_SECRET`.");
+			else try {
+				execFileSync("npx", [
+					"wrangler",
+					"secret",
+					"put",
+					"VITOPS_TURNSTILE_SECRET"
+				], {
+					input: r.secret,
+					stdio: [
+						"pipe",
+						"inherit",
+						"inherit"
+					]
+				});
+				results.push({
+					step: "secret",
+					status: "created",
+					detail: "VITOPS_TURNSTILE_SECRET (Worker secret)"
+				});
+			} catch {
+				results.push({
+					step: "secret",
+					status: "failed",
+					detail: "wrangler secret put failed"
+				});
+				if (process.stdout.isTTY) console.error(`! Save this now, it is shown once: VITOPS_TURNSTILE_SECRET=${r.secret}\n  Then: npx wrangler secret put VITOPS_TURNSTILE_SECRET`);
+				else console.error("! The secret was not saved and is not printed (non-interactive). Rotate it in the dashboard, then `wrangler secret put VITOPS_TURNSTILE_SECRET`.");
+			}
+		}
+	} else results.push({
+		step: "widget",
+		status: "present",
+		detail: p.widget.detail
+	});
+	if (siteKey && p.config.action === "create" && !a.flag("no-write")) {
+		if (!input.endsWith(".json")) results.push({
+			step: "site.json",
+			status: "blocked",
+			detail: `${input} is a module — add site.security.turnstile.siteKey: "${siteKey}" yourself`
+		});
+		else {
+			const source = readFileSync(input, "utf8");
+			const indent = /\n([ \t]+)"/.exec(source)?.[1];
+			writeFileSync(input, JSON.stringify(patchSiteKey(JSON.parse(source), siteKey), null, indent?.includes("	") ? "	" : indent?.length ?? 2) + (source.endsWith("\n") ? "\n" : ""));
+			results.push({
+				step: "site.json",
+				status: "created",
+				detail: "site.security.turnstile.siteKey"
+			});
+		}
+	} else if (p.config.action === "skip") results.push({
+		step: "site.json",
+		status: "present",
+		detail: p.config.detail
+	});
+	console.log(`\n${formatSummary$5(results)}`);
+	for (const r of p.reminders) console.log(`  ${r}`);
+	if (results.some((r) => r.status === "failed" || r.status === "blocked")) process.exit(1);
+}
 /** Forward to the CLI's own `search setup` / `ads setup` as a child process — see
 * this module's docblock for why (their behaviour must not be re-derived). */
 function forward(sub, argv) {
@@ -2523,6 +3101,7 @@ async function cmdSetup(argv) {
 		case "repo": return cmdSetupRepo(rest);
 		case "hosting": return cmdSetupHosting(rest);
 		case "domain": return cmdSetupDomain(rest);
+		case "turnstile": return cmdSetupTurnstile(rest);
 		case "search":
 			if (!forward("search", rest)) process.exit(1);
 			return;
@@ -2575,7 +3154,7 @@ async function cmdSetup(argv) {
 		case "--help":
 			console.log(SETUP_HELP);
 			return;
-		default: fail(`unknown "setup" subcommand "${sub}" (expected: repo | hosting | domain | search | ads | all). Try: vitops --help`);
+		default: fail(`unknown "setup" subcommand "${sub}" (expected: repo | hosting | domain | turnstile | search | ads | all). Try: vitops --help`);
 	}
 }
 
@@ -3329,6 +3908,18 @@ const UTIL_FAMILIES = [
 	"fill",
 	"stroke"
 ];
+/** Class families the framework owns in every format, for variant-spelling checks. */
+const FRAMEWORK_FAMILY = new RegExp(`^(${[
+	...UTIL_FAMILIES,
+	"font",
+	"drop-shadow",
+	"split",
+	"flex",
+	"items",
+	"justify",
+	"gap",
+	"space"
+].join("|")})(-|$)`);
 /**
 * The modifiers actually emitted for one family + role, read back out of the
 * generator's own class list.
@@ -3384,6 +3975,13 @@ function judge(raw, v, format) {
 		reason: `\`@${cq[1]}:\` container-query variants are a tailwind-format spelling; the ${format} format emits pre-expanded classes`,
 		suggestion: `${cq[1]}-${cq[2]}`
 	};
+	const sv = /^(hover|focus|focus-visible|focus-within|active|disabled|dark|group-hover):(.+)$/.exec(raw);
+	if (sv && format !== "tailwind" && FRAMEWORK_FAMILY.test(sv[2])) return {
+		cls: raw,
+		severity: "error",
+		reason: `\`${sv[1]}:\` state variants are a tailwind-format spelling; the ${format} format emits no such class`,
+		suggestion: `${sv[1]}-${sv[2]} where an effect class exists, otherwise a pattern state`
+	};
 	const bp = /^(sm|md|lg|xl)-(.+)$/.exec(cls);
 	if (bp && format === "tailwind") return {
 		cls: raw,
@@ -3496,7 +4094,9 @@ function lintSource(files, v, format) {
 *   vitops ads       setup [--provider <name>] [--dry] [--check]  |  tags  |  lint
 *   vitops setup     repo | hosting | domain | search | ads | all [--dry] [--check]
 *   vitops email     setup [domain] [--dry] [--check]  |  check [--strict] [--skip]
+*   vitops emdash    prepare-db  |  check-prerender [dir]
 *   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
+*   vitops audit     [--url <base>] [--build] [--pages <list>] [--warn] [--out <dir>]
 *
 * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
 * Every client brings their own consumer-editable design-system.json.
@@ -4145,6 +4745,20 @@ function generatorAssetsDir() {
 }
 const AGENTS_START = "<!-- vitops:start -->";
 const AGENTS_END = "<!-- vitops:end -->";
+/**
+* Input path for the read-only commands (`docs`, `lint`) when `-i` is absent.
+*
+* `site.json` is the file `vitops init --site` and every scaffold write, so it
+* is the default; a bare `design-system.json` is the fallback for projects that
+* keep tokens on their own. An explicit `-i` is never second-guessed. If
+* neither exists the legacy name is returned so the "config not found" message
+* names a path a reader recognises.
+*/
+function defaultDesignInput(argv, value) {
+	if (argv.some((a) => a === "-i" || a === "--input" || a.startsWith("--input="))) return value;
+	for (const name of ["site.json", "design-system.json"]) if (existsSync(resolve(name))) return name;
+	return value;
+}
 /** Print a live reference doc (rendered from the project's config) to stdout. */
 async function cmdDocs(argv) {
 	const { values, positionals } = parseArgs({
@@ -4171,7 +4785,7 @@ async function cmdDocs(argv) {
 	}
 	if (topic && !TOPICS[topic]) fail(`unknown topic "${topic}". Valid topics:\n${topicList()}`);
 	const names = values.all ? Object.keys(TOPICS) : [topic];
-	const docs = names.every((n) => TOPICS[n].external) ? {} : generateDocs(loadDesignSystem(resolve(values.input), values.theme), generatorAssetsDir());
+	const docs = names.every((n) => TOPICS[n].external) ? {} : generateDocs(loadDesignSystem(resolve(defaultDesignInput(argv, values.input)), values.theme), generatorAssetsDir());
 	const parts = [];
 	for (const name of names) {
 		const t = TOPICS[name];
@@ -4229,7 +4843,7 @@ function cmdLint(argv) {
 	});
 	const format = values.format;
 	if (!LINT_FORMATS.has(format)) fail(`unknown format "${format}" (expected: bricks | css | tailwind)`);
-	const ds = loadDesignSystem(resolve(values.input), values.theme);
+	const ds = loadDesignSystem(resolve(defaultDesignInput(argv, values.input)), values.theme);
 	const srcDir = resolve(values.src);
 	if (!positionals.length && !existsSync(srcDir)) fail(`source directory not found: ${srcDir}`);
 	const palette = expandPalette(ds.colors.palette);
@@ -4474,8 +5088,10 @@ async function main() {
 		case "ads": return cmdAds(rest);
 		case "crm": return cmdCrm(rest);
 		case "email": return cmdEmail(rest);
+		case "emdash": return cmdEmdash(rest);
 		case "setup": return cmdSetup(rest);
 		case "media": return cmdMedia(rest);
+		case "audit": return cmdAudit(rest);
 		default: fail(`unknown command "${command}" (expected: ${COMMANDS.join(" | ")}). Try: vitops --help`);
 	}
 }