@getvitops/cli 4.1.0 → 5.0.0

package/dist/cli.mjs

@@ -2,9 +2,9 @@
 import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, parse, relative, resolve } from "node:path";
+import { dirname, extname, join, parse, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, processorsMissingLocation, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
+import { JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_LOCAL_PATH, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, movedTokens, processorsMissingLocation, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
 import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
 import { SCOPES, SNAPSHOT_PATH, collectEntries, formatPlan, googleAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
 import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as formatPlan$1, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan as plan$1, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource } from "@getvitops/utils/onboarding";
@@ -129,6 +129,324 @@ function linkSkill(linkPath, targetDir) {
 	}
 }
 
+//#endregion
+//#region src/help.ts
+/**
+* The CLI's help text, and the addressing that lets every subcommand answer
+* `--help`.
+*
+* It lives beside `cli.ts` rather than inside it for one reason: `cli.ts` calls
+* `main()` at import time, so nothing can import it to check anything. The
+* drift guard in `help.test.ts` needs `COMMANDS` and `helpSection` as values.
+*/
+const HELP = `vitops — generate design-system outputs from a design-system.json
+
+Anywhere a command takes --input, that file may be a design-system.json OR the
+larger site config that embeds one (company.json / site.json). The two are told
+apart by shape, and a site config also supplies the site-level facts generation
+reads — its default colour scheme, its legal documents, its icon sprite.
+
+Usage:
+  vitops generate [options]     Generate platform output from a config
+  vitops init [options]         Scaffold a starter design-system.json
+  vitops validate <file>        Validate a config against the schema it says it is
+  vitops favicon [options]      Generate a favicon set from a source image
+  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer
+  vitops docs [topic]           Print live design-system reference docs to stdout
+  vitops lint [opts] [files]    Report classes that resolve to nothing + primitives you re-implemented
+  vitops legal [options]        Render legal documents from a site config
+  vitops icons [options]        Report which icons your source uses, and build the sprite
+  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)
+  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint
+  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
+
+Generate options:
+  -i, --input <path>    design-system.json or site config (default: ./design-system.json)
+  -f, --format <list>   bricks | css | tailwind | design (comma-separated; default: bricks)
+                        design emits DESIGN.md only (the agent-facing brief) — pair it
+                        with --out . to write it beside AGENTS.md, or compose:
+                        --format css,design
+  -o, --out <dir>       Output directory (default: ./dist)
+      --theme <name>    Which designSystem.themes entry to build, when --input is
+                        a site config (default: its defaultTheme, else "default")
+      --site <path>     Site config, when it is a different file from --input.
+                        Emits legal/*.html into the output directory (see:
+                        vitops legal). Omitted with a plain design-system.json:
+                        no legal files.
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+
+Init options:
+  -o, --out <path>      Where to write (default: ./design-system.json)
+      --force           Overwrite an existing file
+
+Validate options:
+  <file>                Config to check (default: ./design-system.json). Either
+                        kind — a design-system.json or the config that embeds one.
+  -i, --input <path>    Same, as a flag
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+
+  Checks the schema, then the things a schema cannot: that every role points at a
+  palette hue that exists, that every var() an authored declaration references
+  resolves to a token this config emits, and that the colour grammar is current.
+
+Favicon options:
+  -i, --input <path>    Source SVG or PNG (required)
+  -o, --out <dir>       Output directory (default: ./public)
+      --low-res <path>  Optional simplified source for the 16px icon
+      --background <hex>  Background under the maskable icons, which must be
+                        opaque (default: #ffffff)
+
+Agents options:
+  -i, --input <path>    design-system.json or site config (default: ./design-system.json;
+                        validated if present)
+      --theme <name>    Theme to read, when --input is a site config
+  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)
+      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir
+                        instead of linking the packaged skill
+
+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)
+      --theme <name>    Theme to render docs from, when --input is a site config
+      --all             Print every topic, concatenated
+
+Icons options:
+      --site <path>     Site config carrying the "icons" block (default: ./site.json)
+      --src <dir>       Source to scan for icon usage (default: ./src)
+      --sprite          Also build the SVG sprite
+  -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)
+      --json            Machine-readable report on stdout
+
+Lint options:
+  -i, --input <path>    design-system.json or site config (default: ./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.
+  -s, --src <dir>       Directory to scan (default: ./src)
+      --strict          Also fail on suggestions (reuse hints), not just on
+                        classes that resolve to nothing
+  [files...]            Lint these paths instead of scanning --src. Unreadable
+                        and non-source paths are skipped, so this can be wired
+                        into a pre-commit hook that appends the staged files.
+      --fix             Rewrite pre-1.0 colour-grammar token references
+                        (var(--<role>-<suffix>) → var(--color-<target>-<role>…))
+                        in CSS and <style> blocks. Applied in ONE pass, so the
+                        renames that rotate cannot compound. Nothing else is
+                        rewritten — every other finding is a judgement call.
+
+  Run this after a major bump: it is the migration tool for anything the
+  changelog says was renamed.
+
+Legal options:
+  -i, --input <path>    Site config: .json, or a .js/.ts module with a default
+                        export (default: ./site.json)
+  -d, --doc <name>      privacy | terms | cookies (repeatable; default: those
+                        enabled in the config)
+  -f, --format <fmt>    md | html | portable-text (default: md)
+                        html suits WordPress/Bricks and plain sites;
+                        portable-text suits EmDash
+  -o, --out <dir>       Write files here (default: print to stdout)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+
+  Generated from your config — a starting point, not legal advice. Review before
+  publishing, and make sure the config describes what your site actually does.
+
+Search subcommands:
+  vitops search setup [opts]    Onboard site.searchConsole domains into GSC
+  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)
+
+Search setup options:
+  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+      --domain <name>   Scope to a single site.searchConsole entry
+      --dry             Print the plan and exit. Changes nothing, and runs without
+                        credentials (planning from scratch, which it says).
+      --check           Report drift and exit non-zero if any domain is not fully
+                        onboarded. Mutates nothing, but does need credentials —
+                        drift is a comparison against live state.
+
+  For each domain it ensures the apex verification TXT in Cloudflare, verifies
+  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-
+  unverified domain is reported PENDING, not failed), adds the sc-domain: property,
+  and adds any delegatedOwners to the web resource. DNS is only ever created,
+  never edited or deleted. Credentials come from the environment:
+  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit + Zone:Read — the standard "Edit zone DNS"
+  template covers both; Zone:Read is what the zone-by-name lookup uses), and
+  VITOPS_GOOGLE_CLIENT_ID /
+  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token
+  scoped to siteverification + webmasters). Granting a Google Group Full-User
+  access has no API and is surfaced as a reminder.
+
+Search notify options:
+  -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)
+      --site-env <env>  Environment to notify for (default: production). An
+                        environment whose robots policy says noindex is refused.
+      --sitemap <src>   Sitemap URL or local path (default: from the config)
+      --urls <list>     Comma-separated URLs to submit, skipping the diff
+      --all             Submit every URL in the sitemap, not just what changed
+      --dry             Print the plan and exit. Makes no requests.
+      --check           Read-only: ask Google whether seo.indexing.priorityUrls
+                        are indexed. Exits non-zero if one is not.
+      --new-key         Print a fresh IndexNow key and exit
+      --write-key <dir> Write the IndexNow key file into <dir> (for stacks with
+                        no Astro integration to do it — Bricks, WordPress)
+      --snapshot <path> Changed-URL state file (default: .vitops/sitemap-snapshot.json).
+                        Persist it between runs (a CI cache) or every run submits
+                        everything.
+
+  What notify can and cannot do: Google exposes no "request indexing" API, and its
+  sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap
+  through the Search Console API and verifies the result with --check. IndexNow
+  reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.
+  Search Console takes either credential, whichever you already have, added as an
+  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
+  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth
+  credential "search setup" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /
+  _REFRESH_TOKEN). The service account is preferred when both are set — this runs
+  on every deploy, and it does not expire.
+
+Ads subcommands:
+  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
+  vitops ads tags [opts]        Print the consent-gated pixel snippets
+  vitops ads lint [opts]        Report ad properties the rest of the config can't see
+
+Ads setup options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+      --provider <name> Scope to one site.ads entry (google | meta | linkedin |
+                        reddit | tiktok | microsoft | pinterest | snapchat)
+      --dry             Print the plan and exit. Creates nothing. With
+                        CLOUDFLARE_API_TOKEN set it reads live DNS first, so the
+                        plan says what is already done; without one it plans from
+                        scratch and says so, rather than refusing to run.
+      --check           Report drift and exit non-zero if any property is not
+                        linked. Mutates nothing, prompts for nothing.
+      --no-prompt       Never ask for a missing token; fail with the field name
+                        instead (the default when stdin is not a TTY, e.g. in CI)
+      --no-write        Don't persist an answered token back into the config
+
+  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —
+  and that record is the one thing this creates for you (in Cloudflare, via
+  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,
+  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking
+  there is the tag and the account ID, and the run says so rather than skipping in
+  silence. No platform Marketing API is called — Meta's needs a system-user token
+  and Google's needs an approved developer token, so the final "Verify" click stays
+  a reminder. The verification token is not a secret (it is published in DNS, which
+  is the ownership proof), so it lives in the config and is prompted for on the
+  first run.
+
+Ads tags options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+      --provider <name> Print one platform's tag
+      --strategy <s>    idle | async | interaction (default: idle)
+
+  Prints each pixel as an INERT, consent-gated <script>: type="text/plain" with the
+  library URL on data-src, so an undecided visitor's page issues no third-party
+  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.
+  Paste into your template; @getvitops/core's consent runtime activates them.
+
+Ads lint options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+
+  Reports the gaps that are invisible at runtime: a click-ID parameter this
+  platform stamps that attribution doesn't capture, a pixel while site.tracking is
+  off (every conversion arrives unattributed), and a configured property with no
+  tag ID. Exits non-zero on a finding.
+
+Media options:
+      --raw <dir>       Directory of unprocessed video, walked recursively
+                        (default: ./raw)
+  -o, --out <dir>       Where the encoded outputs go (default: ./src/assets/processed).
+                        Subdirectories under --raw are preserved.
+      --max-width <px>  Cap the output width, keeping aspect ratio (default: 1920;
+                        0 disables scaling)
+      --crf <n>         Quality on VP9's scale, 0-63, lower is better (default: 32).
+                        The MP4 fallback uses the equivalent on H.264's scale.
+      --max-bitrate <r> Optional ceiling, e.g. 2M or 800k (default: none, which is
+                        constant quality rather than constrained)
+      --audio           Keep the audio track (default: dropped — the common case is
+                        a muted autoplay loop)
+      --poster-time <s> Timestamp the poster frame is taken from (default: 0, which
+                        is often black on a clip that fades in)
+      --outputs <list>  Comma-separated: webm | mp4 | poster (default: all three)
+      --manifest <path> Cache file (default: .vitops/media-manifest.json)
+      --force           Re-encode everything, ignoring the cache
+      --dry             Print the plan and exit. Encodes nothing.
+
+  Needs ffmpeg on PATH — it is an external tool, not an npm dependency, and this
+  command fails rather than quietly skipping. Commit the outputs and the manifest:
+  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.
+
+Common:
+  -h, --help            Show this help
+`;
+const SEARCH_HELP = `vitops search — Google Search Console
+
+  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties
+  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)
+
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
+const ADS_HELP = `vitops ads — link this site to its ad properties
+
+  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
+  vitops ads tags [opts]        Print the consent-gated pixel snippets
+  vitops ads lint [opts]        Report ad properties the rest of the config can't see
+
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
+/**
+* Every command `main()` dispatches. Exported so the unknown-command message
+* and the help drift guard read the same list — the message used to carry its
+* own hand-maintained copy.
+*/
+const COMMANDS = [
+	"generate",
+	"init",
+	"validate",
+	"favicon",
+	"agents",
+	"docs",
+	"lint",
+	"legal",
+	"icons",
+	"search",
+	"ads",
+	"media"
+];
+/**
+* The slice of `HELP` documenting one command, addressed by its heading.
+*
+* `HELP` is already organised as `<Command> options:` blocks, so this reads the
+* section rather than duplicating it — a second copy of every option list is a
+* second thing to keep true.
+*/
+function helpSection(...parts) {
+	const name = parts.join(" ");
+	const title = `${name.charAt(0).toUpperCase()}${name.slice(1)} options:`;
+	const start = HELP.indexOf(`\n${title}\n`);
+	if (start === -1) return void 0;
+	const body = HELP.slice(start + 1);
+	const next = body.slice(title.length).search(/\n[A-Z][A-Za-z ]*:\n/);
+	return next === -1 ? body : body.slice(0, title.length + next);
+}
+/**
+* `--help` on a leaf subcommand used to reach `parseArgs`, which is strict and
+* declares no `help` option — so `vitops lint --help` exited non-zero with a
+* bare `Unknown option '--help'`. Every subcommand answers it now, and it is
+* resolved in one place rather than in fifteen `options` objects, so a new
+* command cannot forget to.
+*/
+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" ? SEARCH_HELP : command === "ads" ? ADS_HELP : void 0) ?? HELP;
+}
+
 //#endregion
 //#region src/prompt.ts
 /**
@@ -273,7 +591,7 @@ function writeConfigPatch(path, provider, field, value) {
 function stripComments(css) {
 	return css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ""));
 }
-const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+const lineAt$1 = (src, index) => src.slice(0, index).split("\n").length;
 /**
 * Parse declarations from a rule body. Splits on top-level `;` only, so a
 * `var(--x, a; b)` or a data URI cannot end a declaration early.
@@ -348,7 +666,7 @@ function scanCss(css) {
 					selector: frame.prelude,
 					declarations: parseDeclarations(src.slice(bodyStart, i)),
 					conditions: stack.filter((f) => f.prelude.startsWith("@")).map((f) => f.prelude),
-					line: lineAt(src, frame.index)
+					line: lineAt$1(src, frame.index)
 				});
 			}
 			preludeStart = i + 1;
@@ -361,7 +679,7 @@ function scanCss(css) {
 function extractStyleBlocks(src) {
 	const out = [];
 	for (const m of src.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
-		const line = lineAt(src, (m.index ?? 0) + m[0].indexOf(">") + 1);
+		const line = lineAt$1(src, (m.index ?? 0) + m[0].indexOf(">") + 1);
 		out.push({
 			css: m[1] ?? "",
 			line
@@ -383,6 +701,68 @@ const TRACK_WIDTHS = [
 	"--width-spotlight"
 ];
 /**
+* Class names that mean "the thing that constrains page width".
+*
+* The token-anchored rule below only fires once someone already knows about
+* `--width-measure`, which is precisely the author who was never going to
+* hand-roll a container. The reported failure was the other author: agents
+* inventing a `.wrap` from scratch, with a plain pixel `max-width`, on site after
+* site. `wrap` is also the more *available* name for the concept, so it wins the
+* naming race against `.centered` every time unless something says otherwise.
+*
+* Matched on the name only in combination with a width-constraining declaration —
+* a `.wrapper` that merely sets `display: flex` is not this pattern.
+*/
+const CONTAINER_NAMES = [
+	"wrap",
+	"wrapper",
+	"container",
+	"inner",
+	"outer",
+	"content-wrap",
+	"content-wrapper",
+	"page-wrap",
+	"page-wrapper",
+	"site-wrap",
+	"site-wrapper",
+	"shell",
+	"constrain",
+	"measure"
+];
+/**
+* Page scale, as a rem-equivalent, above which a width cap is a *container*
+* rather than an element.
+*
+* Keyed to the framework's own `md` breakpoint (48rem) rather than to a number
+* picked for this rule, and it is what keeps a capped figure quiet — someone
+* writing `max-width: 40rem` on an image is not reinventing `.centered`.
+*/
+const PAGE_SCALE_REM = 48;
+/** The same line in `ch`, where a width cap is a reading measure by construction. */
+const PAGE_SCALE_CH = 40;
+/**
+* The largest length in a width value, as a rem-equivalent — so `min(100%,
+* 1200px)` and `clamp(20rem, 90vw, 75rem)` are read at their cap rather than
+* skipped for not being a bare length.
+*
+* Relative-to-viewport units (`%`, `vw`, `vmin`) are deliberately ignored: they
+* express "as wide as there is", which is not a container cap.
+*/
+function widthScale(value) {
+	let rem = 0;
+	let ch = 0;
+	for (const m of value.matchAll(/([\d.]+)(rem|px|em|ch)\b/g)) {
+		const n = Number(m[1]);
+		if (!Number.isFinite(n)) continue;
+		if (m[2] === "ch") ch = Math.max(ch, n);
+		else rem = Math.max(rem, m[2] === "px" ? n / 16 : n);
+	}
+	return {
+		rem,
+		ch
+	};
+}
+/**
 * Column ratios that correspond to a `split-<a>-<b>` class.
 *
 * `.split` is FLEX, not grid — `display: flex` with `flex: 1` children, and a
@@ -419,14 +799,21 @@ const responsive = (bp, base, format) => format === "tailwind" ? `@${bp}:${base}
 */
 const RULES = [
 	(rule) => {
-		const token = TRACK_WIDTHS.find((t) => decl(rule, "max-inline-size")?.includes(t) || decl(rule, "max-width")?.includes(t));
+		const cap = decl(rule, "max-inline-size") ?? decl(rule, "max-width") ?? decl(rule, "width");
 		const centred = /\bauto\b/.test(decl(rule, "margin-inline") ?? decl(rule, "margin") ?? "");
-		if (!token || !centred) return null;
+		if (!cap) return null;
+		const token = TRACK_WIDTHS.find((t) => cap.includes(t));
+		const { rem, ch } = widthScale(cap);
+		const pageScale = rem >= PAGE_SCALE_REM || ch >= PAGE_SCALE_CH;
+		const named = CONTAINER_NAMES.some((n) => new RegExp(`[.#]([a-z0-9]+[-_]+)*${n}([-_]+[a-z0-9]+)*\\b`, "i").test(rule.selector));
+		const why = token ? `it caps width at \`var(${token})\`, a framework track` : named ? `\`${rule.selector.trim()}\` names a page container` : pageScale && centred ? `it caps width at page scale and centres with auto margins` : null;
+		if (!why) return null;
+		if (token && !centred) return null;
 		return {
-			cls: `${rule.selector} { max-inline-size: var(${token}); margin-inline: auto }`,
+			cls: `${rule.selector} { ${cap.length > 40 ? "width cap" : `max-width: ${cap}`} }`,
 			severity: "suggestion",
-			reason: "`.centered` is this pattern — a grid of named tracks, not a max-width plus auto margins",
-			suggestion: "use `.centered`, and widen an individual child with `breakout`, `spotlight` or `fullbleed` on that child rather than overriding the parent"
+			reason: `\`.centered\` is this pattern — ${why}`,
+			suggestion: "use `.centered`. It is a grid of named tracks, not a max-width box, so a child opts into a wider track with `breakout`, `spotlight` or `fullbleed` on itself — a hand-rolled container has no answer for the full-bleed image except more CSS"
 		};
 	},
 	(rule, format) => {
@@ -442,6 +829,22 @@ const RULES = [
 			suggestion: `${responsive(bp, `split-${ratio}`, format)} on the container — the responsive form is equal below the breakpoint and takes the ratio above it, which is what the query is doing by hand`
 		};
 	},
+	(rule) => {
+		const cols = decl(rule, "grid-template-columns");
+		if (!cols || !/^\s*repeat\(/i.test(cols)) return null;
+		if (!/\bgrid\b/.test(decl(rule, "display") ?? "")) return null;
+		if (rule.declarations.some((d) => /subgrid/.test(d.value))) return null;
+		const count = /^\s*repeat\(\s*(\d+)/i.exec(cols)?.[1];
+		const auto = /^\s*repeat\(\s*auto-(fit|fill)/i.test(cols);
+		if (!count && !auto) return null;
+		if (count && Number(count) < 2) return null;
+		return {
+			cls: `${rule.selector} { grid-template-columns: ${cols} }`,
+			severity: "suggestion",
+			reason: "a grid of repeated items is `.subgrid` — a plain grid aligns the outer boxes but not the tranches inside them, so headings, bodies and footers land at different heights across the set",
+			suggestion: auto ? "`.subgrid subgrid-responsive` (2 columns under 60rem, 1 under 40rem) with `--subgrid-row-span` set to the number of row bands each item contains — or `.grid-auto` with `--grid-min`, which is the framework class for this exact auto-fit track and the right answer when the items have no tranches to align" : `\`.subgrid subgrid-cols-${count}\`, with \`--subgrid-row-span\` (or \`subgrid-rows-<n>\`) set to the number of row bands each item contains — and \`.subgrid-card\` on the items to get an edge-bled \`__media\` and a pinned \`__footer\``
+		};
+	},
 	(rule, format) => {
 		if (decl(rule, "display") !== "flex") return null;
 		if (decl(rule, "align-items") !== "center") return null;
@@ -501,6 +904,286 @@ function lintCss(files, format) {
 	return findings;
 }
 
+//#endregion
+//#region src/lint-markup.ts
+/**
+* The third linting direction: markup that lays out a repeated set of things
+* without the framework's pattern for it.
+*
+* `lint.ts` catches a class that resolves to nothing. `lint-css.ts` catches
+* hand-written CSS that re-implements a primitive. Neither reaches the most common
+* reported drift, because it involves no bad class and no hand-written CSS at all:
+* a page renders a list of cards with `class="grid"`, or with nothing, and every
+* class in it is real. The design system has `.subgrid` for exactly this and it
+* goes unused, so across three cards the headings sit at three heights and the
+* CTAs float wherever the copy ended.
+*
+* That cannot be judged from a class token in isolation, so this module is the one
+* that looks at *shape*: is there a repeated card construct here, and is it inside
+* a subgrid?
+*
+* **It is heuristic, and the heuristics are chosen to under-report.** Every finding
+* is a `suggestion`, at most one per file, and each requires a repetition signal
+* strong enough to state in the message: a loop that renders a card, or three or
+* more sibling cards written out. Two cards in a file is not enough — they are as
+* likely to be in unrelated sections, and a rule that fires there would teach
+* people to stop reading the output, which costs more than the drift.
+*/
+/**
+* Only real markup is examined.
+*
+* Markdown is excluded on purpose, and it is the exclusion that matters most: a
+* `.md` file is as likely to *discuss* `.card` as to use it. Run against this
+* repo's own docs site, the first version reported `changelog.md` and two
+* generated reference pages — prose about the framework, counted as drift by it.
+* A consumer's markdown content can hold real markup, so this does give up a
+* little coverage; that is the right side to err on for a heuristic.
+*/
+const MARKUP_EXT = new Set([
+	".astro",
+	".html",
+	".htm",
+	".jsx",
+	".tsx",
+	".vue",
+	".svelte",
+	".ts",
+	".js"
+]);
+/**
+* A class attribute's value, in the spellings the supported frameworks use.
+* Mirrors `lint.ts`'s extractor — the token must be in a real `class`, not merely
+* somewhere in the file.
+*/
+const CLASS_ATTR$1 = /(?:class|className|class:list)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\}|\{([^}]*)\})/g;
+/**
+* The card-ish classes worth caring about.
+*
+* Anchored to `card` as a whole word or suffix, which covers the framework's own
+* `card` / `subgrid-card` / `pricing-card` and a consumer's `service-card` alike.
+* Not `*-item` or `*-tile`: too many of those are not laid out as a set.
+*/
+const CARD_CLASS = /(?:^|[\s"'`])((?:[a-z0-9]+-)*card)(?:__[a-z0-9-]+)?(?=[\s"'`]|$)/i;
+/** Every card class named in a real class attribute, with its offset in `src`. */
+function cardsInClassAttrs(src) {
+	const out = [];
+	for (const m of src.matchAll(CLASS_ATTR$1)) {
+		const value = m[1] ?? m[2] ?? m[3] ?? m[4] ?? "";
+		for (const tok of value.split(/[\s'"`]+/)) {
+			const card = CARD_CLASS.exec(` ${tok} `);
+			if (card && !tok.includes("__")) out.push({
+				name: card[1],
+				index: m.index ?? 0
+			});
+		}
+	}
+	return out;
+}
+/**
+* Already using the pattern — in any tier's spelling.
+*
+* `<Cards>` and `<wc-cards>` count: `<Cards>` renders a `Subgrid`, and `<wc-cards>`
+* only ever wraps one. Omitting them reported a correct card grid as a missed one.
+*/
+const HAS_SUBGRID = /\bsubgrid\b|<Subgrid\b|<Cards\b|<wc-cards\b/;
+/**
+* Constructs that render one item many times.
+*
+* The JS/Astro/JSX `.map(`, and the block forms Svelte/Vue/Handlebars use. A loop
+* whose body contains a card is a repeated card set by construction — no counting
+* and no sibling analysis needed, which is why it is the primary signal.
+*/
+const LOOPS = [
+	/\.\s*map\s*\(/g,
+	/\{#each\b/g,
+	/v-for\s*=/g,
+	/\{%\s*for\b/g
+];
+/** Line number of a character offset. */
+const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+/**
+* The body of a loop, approximated by taking the text that follows it.
+*
+* A real brace-matcher would be more precise and is not worth it: the question is
+* only "does a card appear inside this repetition", and a card 600 characters past
+* a `.map(` is inside it in every realistic template. Over-reaching here can only
+* produce a suggestion on a file that does render cards somewhere.
+*/
+const LOOP_WINDOW = 600;
+/** The strongest repetition signal in one file, or none. */
+function cardSignal(text) {
+	const cards = cardsInClassAttrs(text);
+	if (!cards.length) return null;
+	for (const loop of LOOPS) for (const m of text.matchAll(loop)) {
+		const start = (m.index ?? 0) + m[0].length;
+		const card = cards.find((c) => c.index >= start && c.index < start + LOOP_WINDOW);
+		if (!card) continue;
+		return {
+			line: lineAt(text, m.index ?? 0),
+			evidence: `a \`${m[0].trim()}\` loop renders \`.${card.name}\``,
+			cls: `${m[0].trim()} … .${card.name}`
+		};
+	}
+	if (cards.length >= 3) {
+		const first = cards[0];
+		return {
+			line: lineAt(text, first.index),
+			evidence: `\`.${first.name}\` appears on ${cards.length} elements in this file`,
+			cls: `.${first.name} ×${cards.length}`
+		};
+	}
+	return null;
+}
+/**
+* Lint markup for repeated card sets laid out without `.subgrid`.
+*
+* Takes raw text like the other linters — discovery stays with the caller. One
+* finding per file: the drift is a decision about a layout, not about a line, and
+* repeating it per card would bury every other finding the command prints.
+*/
+/**
+* An anchor carrying a card class inside a subgrid.
+*
+* The shape everyone reaches for when the whole card is a link — and it renders
+* fine, which is why it survives. The `<li>` is the grid item, so the anchor is an
+* ordinary block inside it and the tranches within the anchor never reach the
+* parent's shared row lines: the alignment `.subgrid` exists for silently does not
+* happen, and the anchor doesn't fill the cell either. This is the one markup
+* finding that reports a *broken* result rather than a missed primitive.
+*/
+const LINK_CARD = /<a\b[^>]*\bclass(?:Name)?\s*=\s*["'{][^"'}]*\b(?:[a-z0-9]+-)*card\b/gi;
+/**
+* Is this offset inside an `<li>`?
+*
+* The rule's claim is "the anchor is nested inside the grid item rather than being
+* it", and only an anchor within an `<li>` is that. Checking the file merely
+* *mentions* subgrid is far too coarse: a page documenting several patterns tripped
+* on a standalone `<a class="tile card">`, which is a perfectly good anchor-as-card —
+* outside a grid there is no grid item for it to compete with.
+*/
+function insideListItem(text, index) {
+	const before = text.slice(0, index);
+	return before.lastIndexOf("<li") > before.lastIndexOf("</li");
+}
+function linkCardFinding(file) {
+	const m = [...file.text.matchAll(LINK_CARD)].find((hit) => insideListItem(file.text, hit.index ?? 0));
+	if (!m || m.index === void 0) return null;
+	return {
+		file: file.path,
+		line: lineAt(file.text, m.index),
+		cls: "<a class=\"…card\">",
+		severity: "suggestion",
+		reason: "a card class on an `<a>` inside a `subgrid` does not align — the `<li>` is the grid item, so the anchor's tranches never reach the parent's shared row lines, and the anchor does not fill the cell either. It renders, it just silently is not a subgrid",
+		suggestion: "keep the card as the item (`<li class=\"card subgrid-card\">`) and make the whole card clickable from inside it — either `class=\"stretched-link\"` on a link (no JS, but the card's text stops being selectable) or `<Cards>` / `<wc-cards>` around the list (keeps selection, needs JS, falls back to the link). Both keep the accessible name on real text. Lift anything that must stay above a stretched overlay with `raised`"
+	};
+}
+/**
+* `.stretched-link` inside `<wc-cards>` — the two whole-card-click mechanisms layered.
+*
+* They are alternatives, not layers, and combining them is silently the worse of the
+* two: the overlay takes the pointer-drag, so the card's text stops being selectable
+* — which is the only reason to reach for `<wc-cards>` — and the element's
+* click-vs-drag logic never gets a chance to run, because the browser follows the
+* overlaid link natively first.
+*/
+const WC_CARDS = /<wc-cards\b|<Cards\b/;
+const STRETCHED = /\bclass(?:Name)?\s*=\s*["'{][^"'}]*\bstretched-link\b/;
+function layeredCardLinkFinding(file) {
+	if (!WC_CARDS.test(file.text)) return null;
+	const m = STRETCHED.exec(file.text);
+	if (!m) return null;
+	return {
+		file: file.path,
+		line: lineAt(file.text, m.index),
+		cls: "stretched-link inside wc-cards",
+		severity: "suggestion",
+		reason: "`.stretched-link` and `<wc-cards>` are two ways to do the same thing, and layering them silently picks the worse one — the overlay takes the pointer-drag, so the card's text is no longer selectable, which is the only reason to use `<wc-cards>` at all",
+		suggestion: "drop one. Keep `stretched-link` and use `<Subgrid>` if you want zero JS and can accept unselectable card text; keep `<Cards>` / `<wc-cards>` and remove `stretched-link` if selectable text matters — the plain `link` class on the heading is then the fallback"
+	};
+}
+function lintMarkup(files) {
+	const findings = [];
+	for (const file of files) {
+		if (!MARKUP_EXT.has(extname(file.path).toLowerCase())) continue;
+		const layered = layeredCardLinkFinding(file);
+		if (layered) findings.push(layered);
+		if (HAS_SUBGRID.test(file.text)) {
+			const broken = linkCardFinding(file);
+			if (broken) findings.push(broken);
+			continue;
+		}
+		const signal = cardSignal(file.text);
+		if (!signal) continue;
+		const usingGrid = /\bgrid-auto\b|class(?:Name)?="[^"]*\bgrid\b/.test(file.text);
+		findings.push({
+			file: file.path,
+			line: signal.line,
+			cls: signal.cls,
+			severity: "suggestion",
+			reason: `${signal.evidence}, ${usingGrid ? "laid out with a plain grid rather than a `subgrid`" : "and nothing here is a `subgrid`"} — more than one card is what \`.subgrid\` is for. A plain grid aligns the outer boxes but not the tranches inside them, so the set's headings, bodies and footers land at different heights`,
+			suggestion: "`<ul class=\"subgrid subgrid-cols-3\" role=\"list\">` with `<li class=\"card subgrid-card\">` items (a set of cards is a list; `role=\"list\"` is needed because `.subgrid` is markerless and Safari stops announcing a marker-less `ul` as a list); set `--subgrid-row-span` to the number of row bands each card contains. In Astro, `<Subgrid />` adds the role for you. If the items genuinely have no internal tranches to align (a bare image gallery), `.grid-auto` is the right call and this is a false positive"
+		});
+	}
+	return findings;
+}
+
+//#endregion
+//#region src/lint-tokens.ts
+/**
+* Rewrite every old name in one pass.
+*
+* Longest-first alternation so a name that is a prefix of another (`--x-bg` vs
+* `--x-bg-bold`) cannot be matched short, and a single `replace` so no output of
+* one rename is ever input to the next.
+*/
+function applyRenames(text, renames) {
+	const names = Object.keys(renames).sort((a, b) => b.length - a.length);
+	if (!names.length) return text;
+	const escaped = names.map((n) => n.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`));
+	const re = new RegExp(`(${escaped.join("|")})(?![\\w-])`, "g");
+	return text.replace(re, (m) => renames[m] ?? m);
+}
+/** Every `var(--name)` in a text, with its line number. */
+function varRefs(src) {
+	const out = [];
+	for (const m of src.matchAll(/var\(\s*(--[\w-]+)/g)) out.push({
+		name: m[1],
+		line: src.slice(0, m.index).split("\n").length
+	});
+	return out;
+}
+/**
+* Report old-grammar token references in source files.
+*
+* `renames` comes from the generator's `movedTokens()`, built from the
+* consumer's own role names — there is no fixed list, which is why nothing
+* detected these before.
+*/
+function lintTokens(files, renames) {
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const f of files) for (const { name, line } of varRefs(f.text)) {
+		const to = renames[name];
+		if (to == null) continue;
+		const key = `${f.path}:${line}:${name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		findings.push({
+			file: f.path,
+			line,
+			cls: `var(${name})`,
+			severity: "error",
+			reason: `\`${name}\` is the pre-1.0 colour grammar and resolves to nothing`,
+			suggestion: `var(${to})`,
+			fix: {
+				from: name,
+				to
+			}
+		});
+	}
+	return findings;
+}
+
 //#endregion
 //#region src/lint.ts
 /**
@@ -726,238 +1409,6 @@ const LEGAL_OUTPUTS = new Set([
 	"html",
 	"portable-text"
 ]);
-const HELP = `vitops — generate design-system outputs from a design-system.json
-
-Anywhere a command takes --input, that file may be a design-system.json OR the
-larger site config that embeds one (company.json / site.json). The two are told
-apart by shape, and a site config also supplies the site-level facts generation
-reads — its default colour scheme, its legal documents, its icon sprite.
-
-Usage:
-  vitops generate [options]     Generate platform output from a config
-  vitops init [options]         Scaffold a starter design-system.json
-  vitops validate <file>        Validate a config against the schema it says it is
-  vitops favicon [options]      Generate a favicon set from a source image
-  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer
-  vitops docs [topic]           Print live design-system reference docs to stdout
-  vitops lint [options]         Report framework classes in your source that resolve to nothing
-  vitops legal [options]        Render legal documents from a site config
-  vitops icons [options]        Report which icons your source uses, and build the sprite
-  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)
-  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint
-  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
-
-Generate options:
-  -i, --input <path>    design-system.json or site config (default: ./design-system.json)
-  -f, --format <list>   bricks | css | tailwind | design (comma-separated; default: bricks)
-                        design emits DESIGN.md only (the agent-facing brief) — pair it
-                        with --out . to write it beside AGENTS.md, or compose:
-                        --format css,design
-  -o, --out <dir>       Output directory (default: ./dist)
-      --theme <name>    Which designSystem.themes entry to build, when --input is
-                        a site config (default: its defaultTheme, else "default")
-      --site <path>     Site config, when it is a different file from --input.
-                        Emits legal/*.html into the output directory (see:
-                        vitops legal). Omitted with a plain design-system.json:
-                        no legal files.
-      --site-env <env>  Environment whose A/B variant applies (default: production)
-
-Init options:
-  -o, --out <path>      Where to write (default: ./design-system.json)
-      --force           Overwrite an existing file
-
-Favicon options:
-  -i, --input <path>    Source SVG or PNG (required)
-  -o, --out <dir>       Output directory (default: ./public)
-      --low-res <path>  Optional simplified source for the 16px icon
-      --background <hex>  Background under the maskable icons, which must be
-                        opaque (default: #ffffff)
-
-Agents options:
-  -i, --input <path>    design-system.json or site config (default: ./design-system.json;
-                        validated if present)
-      --theme <name>    Theme to read, when --input is a site config
-  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)
-      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir
-                        instead of linking the packaged skill
-
-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)
-      --theme <name>    Theme to render docs from, when --input is a site config
-      --all             Print every topic, concatenated
-
-Icons options:
-      --site <path>     Site config carrying the "icons" block (default: ./site.json)
-      --src <dir>       Source to scan for icon usage (default: ./src)
-      --sprite          Also build the SVG sprite
-  -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)
-      --json            Machine-readable report on stdout
-
-Lint options:
-  -i, --input <path>    design-system.json or site config (default: ./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.
-  -s, --src <dir>       Directory to scan (default: ./src)
-      --strict          Also fail on suggestions (reuse hints), not just on
-                        classes that resolve to nothing
-
-Legal options:
-  -i, --input <path>    Site config: .json, or a .js/.ts module with a default
-                        export (default: ./site.json)
-  -d, --doc <name>      privacy | terms | cookies (repeatable; default: those
-                        enabled in the config)
-  -f, --format <fmt>    md | html | portable-text (default: md)
-                        html suits WordPress/Bricks and plain sites;
-                        portable-text suits EmDash
-  -o, --out <dir>       Write files here (default: print to stdout)
-      --site-env <env>  Environment whose A/B variant applies (default: production)
-
-  Generated from your config — a starting point, not legal advice. Review before
-  publishing, and make sure the config describes what your site actually does.
-
-Search subcommands:
-  vitops search setup [opts]    Onboard site.searchConsole domains into GSC
-  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)
-
-Search setup options:
-  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)
-      --site-env <env>  Environment whose A/B variant applies (default: production)
-      --domain <name>   Scope to a single site.searchConsole entry
-      --dry             Print the plan and exit. Changes nothing.
-      --check           Report drift and exit non-zero if any domain is not fully
-                        onboarded. Mutates nothing.
-
-  For each domain it ensures the apex verification TXT in Cloudflare, verifies
-  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-
-  unverified domain is reported PENDING, not failed), adds the sc-domain: property,
-  and adds any delegatedOwners to the web resource. DNS is only ever created,
-  never edited or deleted. Credentials come from the environment:
-  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit), and VITOPS_GOOGLE_CLIENT_ID /
-  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token
-  scoped to siteverification + webmasters). Granting a Google Group Full-User
-  access has no API and is surfaced as a reminder.
-
-Search notify options:
-  -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)
-      --site-env <env>  Environment to notify for (default: production). An
-                        environment whose robots policy says noindex is refused.
-      --sitemap <src>   Sitemap URL or local path (default: from the config)
-      --urls <list>     Comma-separated URLs to submit, skipping the diff
-      --all             Submit every URL in the sitemap, not just what changed
-      --dry             Print the plan and exit. Makes no requests.
-      --check           Read-only: ask Google whether seo.indexing.priorityUrls
-                        are indexed. Exits non-zero if one is not.
-      --new-key         Print a fresh IndexNow key and exit
-      --write-key <dir> Write the IndexNow key file into <dir> (for stacks with
-                        no Astro integration to do it — Bricks, WordPress)
-      --snapshot <path> Changed-URL state file (default: .vitops/sitemap-snapshot.json).
-                        Persist it between runs (a CI cache) or every run submits
-                        everything.
-
-  What notify can and cannot do: Google exposes no "request indexing" API, and its
-  sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap
-  through the Search Console API and verifies the result with --check. IndexNow
-  reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.
-  Search Console takes either credential, whichever you already have, added as an
-  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
-  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth
-  credential "search setup" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /
-  _REFRESH_TOKEN). The service account is preferred when both are set — this runs
-  on every deploy, and it does not expire.
-
-Ads subcommands:
-  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
-  vitops ads tags [opts]        Print the consent-gated pixel snippets
-  vitops ads lint [opts]        Report ad properties the rest of the config can't see
-
-Ads setup options:
-  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
-      --site-env <env>  Environment whose A/B variant applies (default: production)
-      --provider <name> Scope to one site.ads entry (google | meta | linkedin |
-                        reddit | tiktok | microsoft | pinterest | snapchat)
-      --dry             Print the plan and exit. Creates nothing — but it does READ
-                        live DNS first, so it needs CLOUDFLARE_API_TOKEN.
-      --check           Report drift and exit non-zero if any property is not
-                        linked. Mutates nothing, prompts for nothing.
-      --no-prompt       Never ask for a missing token; fail with the field name
-                        instead (the default when stdin is not a TTY, e.g. in CI)
-      --no-write        Don't persist an answered token back into the config
-
-  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —
-  and that record is the one thing this creates for you (in Cloudflare, via
-  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,
-  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking
-  there is the tag and the account ID, and the run says so rather than skipping in
-  silence. No platform Marketing API is called — Meta's needs a system-user token
-  and Google's needs an approved developer token, so the final "Verify" click stays
-  a reminder. The verification token is not a secret (it is published in DNS, which
-  is the ownership proof), so it lives in the config and is prompted for on the
-  first run.
-
-Ads tags options:
-  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
-      --provider <name> Print one platform's tag
-      --strategy <s>    idle | async | interaction (default: idle)
-
-  Prints each pixel as an INERT, consent-gated <script>: type="text/plain" with the
-  library URL on data-src, so an undecided visitor's page issues no third-party
-  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.
-  Paste into your template; @getvitops/core's consent runtime activates them.
-
-Ads lint options:
-  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
-
-  Reports the gaps that are invisible at runtime: a click-ID parameter this
-  platform stamps that attribution doesn't capture, a pixel while site.tracking is
-  off (every conversion arrives unattributed), and a configured property with no
-  tag ID. Exits non-zero on a finding.
-
-Media options:
-      --raw <dir>       Directory of unprocessed video, walked recursively
-                        (default: ./raw)
-  -o, --out <dir>       Where the encoded outputs go (default: ./src/assets/processed).
-                        Subdirectories under --raw are preserved.
-      --max-width <px>  Cap the output width, keeping aspect ratio (default: 1920;
-                        0 disables scaling)
-      --crf <n>         Quality on VP9's scale, 0-63, lower is better (default: 32).
-                        The MP4 fallback uses the equivalent on H.264's scale.
-      --max-bitrate <r> Optional ceiling, e.g. 2M or 800k (default: none, which is
-                        constant quality rather than constrained)
-      --audio           Keep the audio track (default: dropped — the common case is
-                        a muted autoplay loop)
-      --poster-time <s> Timestamp the poster frame is taken from (default: 0, which
-                        is often black on a clip that fades in)
-      --outputs <list>  Comma-separated: webm | mp4 | poster (default: all three)
-      --manifest <path> Cache file (default: .vitops/media-manifest.json)
-      --force           Re-encode everything, ignoring the cache
-      --dry             Print the plan and exit. Encodes nothing.
-
-  Needs ffmpeg on PATH — it is an external tool, not an npm dependency, and this
-  command fails rather than quietly skipping. Commit the outputs and the manifest:
-  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.
-
-Common:
-  -h, --help            Show this help
-`;
-const SEARCH_HELP = `vitops search — Google Search Console
-
-  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties
-  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)
-
-Run \`vitops --help\` for the full option list for each subcommand.
-`;
-const ADS_HELP = `vitops ads — link this site to its ad properties
-
-  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
-  vitops ads tags [opts]        Print the consent-gated pixel snippets
-  vitops ads lint [opts]        Report ad properties the rest of the config can't see
-
-Run \`vitops --help\` for the full option list for each subcommand.
-`;
 function fail(msg) {
 	console.error(`✖ ${msg}`);
 	process.exit(1);
@@ -1028,7 +1479,7 @@ function cmdInit(argv) {
 	writeFileSync(out, JSON.stringify(defaultConfig(), null, 2) + "\n");
 	console.log(`✓ wrote ${out}`);
 	console.log(`  Edit it, then: vitops generate --input ${values.out} --format tailwind --out src/styles`);
-	console.log(`  Editors read the "$schema" (${SCHEMA_URL}) for autocomplete + validation.`);
+	console.log(`  Editors read the "$schema" (${SCHEMA_LOCAL_PATH}) for autocomplete + validation — the installed copy, so it matches the toolchain you build with.`);
 }
 /**
 * Validate a config against the schema its shape says it is.
@@ -1462,15 +1913,21 @@ async function cmdLegal(argv) {
 	* On **stderr** because stdout is the document and gets piped or redirected.
 	*/
 	if (docs.includes("privacy")) for (const name of processorsMissingLocation(site)) console.error(`  ! ${name}: no country, storage or operatorCountry declared — it will not appear in the cross-border transfer disclosure. Add one, or state storage: [{ country: "${JURISDICTION_COUNTRIES[site.site.legal?.jurisdiction ?? "ca"]}" }] to say it does not leave the country.`);
+	const REVIEW = "  These are generated from your config and are not legal advice — review them before publishing.";
 	if (!values.out) {
 		process.stdout.write(Object.values(files).join("\n"));
+		console.error(REVIEW);
 		return;
 	}
 	const outDir = resolve(values.out);
 	mkdirSync(outDir, { recursive: true });
+	const isNew = (name) => !existsSync(join(outDir, name));
+	const added = Object.keys(files).filter(isNew);
 	for (const [name, content] of Object.entries(files)) writeFileSync(join(outDir, name), content);
-	console.log(`✓ legal → ${outDir} (${Object.keys(files).length} files)`);
-	console.log("  These are generated from your config and are not legal advice — review them before publishing.");
+	console.log(`✓ legal → ${outDir}`);
+	for (const name of Object.keys(files)) console.log(`    ${name}${added.includes(name) ? "  (new)" : ""}`);
+	if (added.length) console.log(added.length === 1 ? `\n  That document is new. It needs somewhere to live: a page or route that renders it, and a link to it${added[0]?.startsWith("cookie") ? " — including the URL your consent banner points at" : ""}.` : `\n  Those ${added.length} documents are new. Each needs somewhere to live: a page or route that renders it, and a link to it — for a cookie notice, including the URL your consent banner points at.`);
+	console.log(REVIEW);
 }
 /**
 * Adapt a `Config` to the indexing module's own option shape.
@@ -1820,7 +2277,20 @@ async function cmdSearchSetup(argv) {
 	if (domains.length === 0) fail("no domains in site.searchConsole — add domains to onboard (keyed by bare hostname)");
 	const cfToken = loadCloudflareToken();
 	const oauth = loadGoogleOAuth();
-	if (!cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token) — reading and writing DNS needs it");
+	if (values.dry && (!cfToken || !oauth)) {
+		const blank = {
+			zoneId: "",
+			txtPresent: false,
+			verified: false,
+			currentOwners: [],
+			propertyExists: false
+		};
+		console.log(formatPlan$1(plan$1({ domains }, new Map(domains.map((d) => [d.domain, blank])))));
+		const missing = [...cfToken ? [] : ["CLOUDFLARE_API_TOKEN (Zone:DNS:Edit + Zone:Read)"], ...oauth ? [] : ["VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN"]];
+		console.log(`\n(--dry, and no credentials set: planned from scratch rather than from live state, so nothing here is reported as already done.\n A real run needs ${missing.join(" and ")}.)`);
+		return;
+	}
+	if (!cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token — the standard \"Edit zone DNS\" template, which also carries the Zone:Read that the zone-by-name lookup needs)");
 	if (!oauth) fail("set VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN — a user OAuth token scoped to siteverification + webmasters");
 	const token = await refreshTokenGrant(oauth);
 	const states = /* @__PURE__ */ new Map();
@@ -2054,7 +2524,7 @@ async function cmdAdsSetup(argv) {
 	const check = values.check;
 	const needsDns = properties.some((p) => AD_PLATFORMS[p.provider].verification.method === "dns-txt");
 	const cfToken = loadCloudflareToken();
-	if (needsDns && !cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token) — reading and writing DNS needs it");
+	if (needsDns && !cfToken && values.dry !== true) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token — the standard \"Edit zone DNS\" template, which also carries the Zone:Read that the zone-by-name lookup needs)");
 	/** Observe live DNS per domain. Cached by domain: several platforms share one. */
 	const observe = async () => {
 		const states = /* @__PURE__ */ new Map();
@@ -2292,7 +2762,7 @@ function cmdDocs(argv) {
 	process.stdout.write(paths.map((p) => docs[p]).join("\n"));
 }
 function cmdLint(argv) {
-	const { values } = parseArgs({
+	const { values, positionals } = parseArgs({
 		args: argv,
 		options: {
 			input: {
@@ -2314,15 +2784,19 @@ function cmdLint(argv) {
 			strict: {
 				type: "boolean",
 				default: false
+			},
+			fix: {
+				type: "boolean",
+				default: false
 			}
 		},
-		allowPositionals: false
+		allowPositionals: true
 	});
 	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 srcDir = resolve(values.src);
-	if (!existsSync(srcDir)) fail(`source directory not found: ${srcDir}`);
+	if (!positionals.length && !existsSync(srcDir)) fail(`source directory not found: ${srcDir}`);
 	const palette = expandPalette(ds.colors.palette);
 	const roleClasses = roleColorUtilities(Object.entries(ds.colors.roles).map(([role, spec]) => functionalRole(role, roleHue(spec), palette[roleHue(spec)], roleKind(spec))), ds.colors.utilities ?? [
 		"bg",
@@ -2330,11 +2804,56 @@ function cmdLint(argv) {
 		"icon",
 		"border"
 	]).map((u) => u.cls);
-	const files = scanFiles(srcDir);
-	const cssFiles = [...files, ...scanFiles(srcDir, { exts: [".css"] })];
-	const findings = [...lintSource(files, vocabulary(ds, roleClasses), format), ...lintCss(cssFiles, format)];
+	const LINTABLE = new Set([
+		".astro",
+		".html",
+		".js",
+		".jsx",
+		".ts",
+		".tsx",
+		".vue",
+		".svelte"
+	]);
+	const named = positionals.filter((p) => LINTABLE.has(extname(p)) || extname(p) === ".css").flatMap((p) => {
+		try {
+			return [{
+				path: p,
+				text: readFileSync(resolve(p), "utf8")
+			}];
+		} catch {
+			return [];
+		}
+	});
+	const files = positionals.length ? named.filter((f) => extname(f.path) !== ".css") : scanFiles(srcDir);
+	const cssFiles = positionals.length ? named : [...files, ...scanFiles(srcDir, { exts: [".css"] })];
+	if (positionals.length && !cssFiles.length) {
+		console.log("✓ no lintable files among the paths given");
+		return;
+	}
+	const renames = movedTokens(ds.colors.roles);
+	const tokenFindings = lintTokens(cssFiles, renames);
+	const findings = [
+		...lintSource(files, vocabulary(ds, roleClasses), format),
+		...lintCss(cssFiles, format),
+		...lintMarkup(files),
+		...tokenFindings
+	];
+	if (values.fix === true) {
+		const byFile = /* @__PURE__ */ new Map();
+		for (const f of tokenFindings) (byFile.get(f.file) ?? byFile.set(f.file, /* @__PURE__ */ new Set()).get(f.file)).add(f.fix.from);
+		for (const [file, names] of byFile) {
+			const subset = Object.fromEntries([...names].map((n) => [n, renames[n]]));
+			writeFileSync(file, applyRenames(readFileSync(file, "utf8"), subset));
+		}
+		const remaining = findings.length - tokenFindings.length;
+		console.log(`✓ rewrote ${tokenFindings.length} token reference${tokenFindings.length === 1 ? "" : "s"} in ${byFile.size} file${byFile.size === 1 ? "" : "s"}` + (remaining ? `\n! ${remaining} other finding${remaining === 1 ? "" : "s"} need a decision — re-run without --fix to see ${remaining === 1 ? "it" : "them"}` : ""));
+		if (remaining) process.exitCode = 1;
+		return;
+	}
+	const scope = positionals.length ? "the files given" : values.src;
+	const scanned = positionals.length ? cssFiles.length : files.length;
 	if (!findings.length) {
-		console.log(`✓ no unresolvable framework classes in ${values.src} (${files.length} file${files.length === 1 ? "" : "s"} scanned)`);
+		console.log(`✓ no unresolvable framework classes or missed primitives in ${scope} (${scanned} file${scanned === 1 ? "" : "s"} checked)`);
 		return;
 	}
 	const errors = findings.filter((f) => f.severity === "error");
@@ -2349,9 +2868,35 @@ function cmdLint(argv) {
 	if (errors.length) parts.push(count(errors.length, "unresolvable class", "unresolvable classes"));
 	if (suggestions.length) parts.push(count(suggestions.length, "suggestion", "suggestions"));
 	const failing = errors.length > 0 || values.strict === true && suggestions.length > 0;
-	console.error(`\n${failing ? "✖" : "!"} ${parts.join(", ")} in ${files.length} file${files.length === 1 ? "" : "s"}` + (suggestions.length && !values.strict ? " (suggestions do not fail; use --strict)" : ""));
+	console.error(`\n${failing ? "✖" : "!"} ${parts.join(", ")} in ${scanned} file${scanned === 1 ? "" : "s"}` + (suggestions.length && !values.strict ? " (suggestions do not fail; use --strict)" : ""));
 	if (failing) process.exit(1);
 }
+/**
+* Find the config when `design-system.json` isn't there.
+*
+* Keyed to SHAPE, not just to the filename — `resolveInput` already tells a
+* design system from the config that embeds one, and consumers name that file
+* whatever they like (`company.json`, `site.json`). The candidate list is
+* ordered, and a tie is resolved by taking the first: this only ever supplies a
+* default that the run then prints, so a wrong guess is visible rather than
+* silent, and `-i` overrides it.
+*/
+function discoverConfig(cwd) {
+	for (const name of [
+		"design-system.json",
+		"vitops.json",
+		"site.json",
+		"company.json",
+		"organization.json"
+	]) {
+		const p = resolve(cwd, name);
+		if (!existsSync(p)) continue;
+		try {
+			const raw = JSON.parse(readFileSync(p, "utf8"));
+			if (isConfig(raw) || raw && typeof raw === "object" && "colors" in raw) return name;
+		} catch {}
+	}
+}
 function cmdAgents(argv) {
 	const { values } = parseArgs({
 		args: argv,
@@ -2371,7 +2916,15 @@ function cmdAgents(argv) {
 		},
 		allowPositionals: false
 	});
-	const inputRel = values.input;
+	const explicitInput = argv.includes("-i") || argv.includes("--input");
+	let inputRel = values.input;
+	if (!explicitInput && !existsSync(resolve(inputRel))) {
+		const found = discoverConfig(process.cwd());
+		if (found) {
+			inputRel = found;
+			console.warn(`  ⚠ no design-system.json here — using ${found} (pass -i to choose another)`);
+		} else fail(`config not found: ${resolve(inputRel)}\n  This command writes the path into ${values.out}, so it will not guess one. Pass -i <path> if your tokens live elsewhere (a site config works), or run \`vitops init\`.`);
+	}
 	let ds = null;
 	if (existsSync(resolve(inputRel))) ds = loadDesignSystem(resolve(inputRel), values.theme);
 	else console.warn(`  ⚠ ${inputRel} not found — run \`vitops init\` to scaffold one`);
@@ -2419,6 +2972,7 @@ function cmdAgents(argv) {
 			...Object.entries(TOPICS).map(([name, t]) => `- \`vitops docs ${name}\` — ${t.summary}`)
 		];
 	}
+	const inputFlag = inputRel === "design-system.json" ? "" : ` --input ${inputRel}`;
 	const block = [
 		AGENTS_START,
 		"## Vitops design system",
@@ -2426,11 +2980,11 @@ function cmdAgents(argv) {
 		`Styled with the Vitops design system (\`@getvitops/*\`); tokens live in \`${inputRel}\`.`,
 		"Generate output with the CLI:",
 		"",
-		"- `vitops generate --format tailwind --out src/styles` — Tailwind v4 / Astro",
-		"- `vitops generate --format css --out dist` — standalone CSS",
-		"- `vitops generate --format bricks --out <theme>/dist` — WordPress / Bricks",
-		"- `vitops generate --format design --out .` — `DESIGN.md`, the agent-facing brief",
-		"- `vitops init` · `vitops validate` · `vitops favicon`",
+		`- \`vitops generate${inputFlag} --format tailwind --out src/styles\` — Tailwind v4 / Astro`,
+		`- \`vitops generate${inputFlag} --format css --out dist\` — standalone CSS`,
+		`- \`vitops generate${inputFlag} --format bricks --out <theme>/dist\` — WordPress / Bricks`,
+		`- \`vitops generate${inputFlag} --format design --out .\` — \`DESIGN.md\`, the agent-facing brief`,
+		`- \`vitops init\` · \`vitops validate${inputFlag}\` · \`vitops favicon\``,
 		"",
 		...pointer,
 		"",
@@ -2465,6 +3019,10 @@ async function main() {
 		console.log(HELP);
 		return;
 	}
+	if (wantsHelp(rest)) {
+		console.log(helpFor(command, rest));
+		return;
+	}
 	switch (command) {
 		case "generate": return cmdGenerate(rest);
 		case "init": return cmdInit(rest);
@@ -2478,7 +3036,7 @@ async function main() {
 		case "search": return cmdSearch(rest);
 		case "ads": return cmdAds(rest);
 		case "media": return cmdMedia(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | search | ads | media). Try: vitops --help`);
+		default: fail(`unknown command "${command}" (expected: ${COMMANDS.join(" | ")}). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));