@getvitops/cli 4.0.0 → 5.0.0

package/dist/cli.mjs

@@ -2,13 +2,16 @@
 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 { NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, 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";
-import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$2, processMedia } from "@getvitops/utils/media";
+import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$2, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, plan as plan$2, renderTag, tagId } from "@getvitops/utils/ads";
+import { PLATFORM_PARAMS } from "@getvitops/utils/tracking";
+import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$3, processMedia } from "@getvitops/utils/media";
+import { createInterface } from "node:readline/promises";
 
 //#region src/agents.ts
 /**
@@ -126,13 +129,469 @@ 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
+/**
+* Asking for the config values `vitops ads setup` cannot derive, and writing the
+* answers back.
+*
+* The realistic first run has no verification token in the config, because the
+* token does not exist until someone opens the platform UI and asks for one. That
+* makes a missing token a **question**, not an error — but only when there is
+* somebody there to answer it, which is why every decision about *whether* to ask
+* is made here and the planner stays pure.
+*
+* The split mirrors the rest of the toolchain: `questionFor` and `patchRaw` are
+* pure and tested; `ask` and `writeConfigPatch` are the I/O, and they decide
+* nothing.
+*
+* Two rules hold the whole file together:
+*
+*  - **A prompt must never hang a CI run.** Asking requires a TTY and an explicit
+*    absence of `--dry` / `--check` / `--no-prompt`; otherwise the caller gets the
+*    same named error it would have got before this file existed.
+*  - **A fact about the site goes in the config; a credential stays in the
+*    environment.** A verification token is published in DNS — the platform
+*    fetching it back is the ownership proof — so persisting it is right, and it is
+*    the only thing here that gets written. `CLOUDFLARE_API_TOKEN` may be typed at
+*    a prompt and lives only in the process.
+*/
+/**
+* What to ask for one gap, and where the operator finds it.
+*
+* The hints are the point. "meta.domainVerification is missing" is true and
+* useless; the UI path plus the console URL is the difference between a prompt
+* someone can answer now and one they abandon to go searching.
+*/
+function questionFor(provider, needs) {
+	const platform = AD_PLATFORMS[provider];
+	if (needs === "domainVerification") return {
+		provider,
+		needs,
+		title: `${platform.name} — domain verification token`,
+		hints: [...platform.verification.where ? [platform.verification.where] : [], platform.consoleUrl],
+		label: platform.verification.txtPrefix ?? "token"
+	};
+	const what = needs === "pixelId" ? provider === "google" ? "conversion ID (AW-…, not the customer ID)" : "pixel / tag ID" : "advertising account ID";
+	return {
+		provider,
+		needs,
+		title: `${platform.name} — ${what}`,
+		hints: [platform.consoleUrl],
+		label: needs
+	};
+}
+/** The error a non-interactive run gets instead of a prompt. */
+function missingFieldMessage(provider, needs) {
+	const q = questionFor(provider, needs);
+	return `site.ads.${provider}.${needs} is not set — ${q.title}.\n` + q.hints.map((h) => `  ${h}`).join("\n") + `\n  Run this interactively to be prompted for it, or add it to the config yourself.`;
+}
+/** Whether this run is allowed to ask. Everything that would hang CI is checked here. */
+function canPrompt(opts) {
+	if (opts.dry || opts.check || opts.noPrompt) return false;
+	return opts.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+* Ask one question. An empty answer means "skip this one" — reported as still
+* blocked rather than treated as a value, so nothing is written and nothing is
+* created on the strength of a stray Enter.
+*/
+async function ask(q) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		console.log(`\n${q.title}`);
+		for (const hint of q.hints) console.log(`  ${hint}`);
+		return (await rl.question(`  ${q.label} `)).trim() || void 0;
+	} finally {
+		rl.close();
+	}
+}
+/**
+* Merge one ad-property field into a **raw, on-disk** config object.
+*
+* Raw is load-bearing, and it is the rule `@getvitops/vite`'s `designSystemPath()`
+* already follows for the theme editor's save: `resolveConfig` normalises shorthand
+* shapes and resolves `extends` in memory, so writing from the resolved object
+* would grow keys beside the author's and silently edit a copy nothing builds from.
+* Everything outside `site.ads.<provider>.<field>` is left exactly as it was.
+*/
+function patchRaw(raw, provider, field, value) {
+	if (typeof raw !== "object" || raw == null || Array.isArray(raw)) throw new Error("config is not an object");
+	const root = raw;
+	const site = root["site"] ?? {};
+	const ads = site["ads"] ?? {};
+	const entry = ads[provider] ?? {};
+	return {
+		...root,
+		site: {
+			...site,
+			ads: {
+				...ads,
+				[provider]: {
+					...entry,
+					[field]: value
+				}
+			}
+		}
+	};
+}
+/** Indentation the file already uses, so a patch doesn't reformat the whole document. */
+function detectIndent(source) {
+	const match = /\n([ \t]+)"/.exec(source);
+	if (!match?.[1]) return 2;
+	return match[1].includes("	") ? "	" : match[1].length;
+}
+/**
+* Persist one answered field into the config file.
+*
+* JSON only: a `.js`/`.ts` config is code, and rewriting code to insert a value is
+* a different (and much worse) problem than merging an object — so the caller is
+* told to paste it instead. Returns whether it wrote.
+*/
+function writeConfigPatch(path, provider, field, value) {
+	if (!path.endsWith(".json")) return {
+		written: false,
+		reason: `${path} is a module, not JSON — add "${field}": "${value}" to site.ads.${provider} yourself`
+	};
+	if (!existsSync(path)) return {
+		written: false,
+		reason: `${path} no longer exists`
+	};
+	const source = readFileSync(path, "utf8");
+	const next = patchRaw(JSON.parse(source), provider, field, value);
+	const trailingNewline = source.endsWith("\n") ? "\n" : "";
+	writeFileSync(path, JSON.stringify(next, null, detectIndent(source)) + trailingNewline);
+	return { written: true };
+}
+
 //#endregion
 //#region src/css-scan.ts
 /** Strip comments, preserving newlines so line numbers survive. */
 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.
@@ -207,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;
@@ -220,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
@@ -242,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
@@ -278,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) => {
@@ -301,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;
@@ -360,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
 /**
@@ -498,268 +1322,93 @@ function judge(raw, v, format) {
 		const near = nearest(font[1], v.typeRoles);
 		if (near) return {
 			cls: raw,
-			severity: "error",
-			reason: `\`${font[1]}\` is not a typography role`,
-			suggestion: `font-${near}`
-		};
-	}
-	const ds = /^drop-shadow-(.+)$/.exec(base);
-	if (ds && v.shadows.length && !v.shadows.includes(ds[1])) return {
-		cls: raw,
-		severity: "error",
-		reason: `\`${ds[1]}\` is not a defined shadow`,
-		suggestion: `drop-shadow-${v.shadows[0]}`
-	};
-	return null;
-}
-const CLASS_ATTR = /(?:class|className|:class)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/g;
-/** Extract class tokens from a source file, with line numbers. */
-function extractClasses(src) {
-	const out = [];
-	for (const m of src.matchAll(CLASS_ATTR)) {
-		const value = m[1] ?? m[2] ?? m[3] ?? "";
-		const line = src.slice(0, m.index).split("\n").length;
-		for (const tok of value.split(/\s+/)) if (tok && !tok.includes("${") && !tok.includes("{") && /^[@\w:[\]().%/-]+$/.test(tok)) out.push({
-			cls: tok,
-			line
-		});
-	}
-	return out;
-}
-function lintSource(files, v, format) {
-	const findings = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const f of files) for (const { cls, line } of extractClasses(f.text)) {
-		const verdict = judge(cls, v, format);
-		if (!verdict) continue;
-		const key = `${f.path}:${line}:${cls}`;
-		if (seen.has(key)) continue;
-		seen.add(key);
-		findings.push({
-			file: f.path,
-			line,
-			...verdict
-		});
-	}
-	return findings;
-}
-
-//#endregion
-//#region src/cli.ts
-/**
-* `vitops` — CLI for the Vitops design-system generator.
-*
-*   vitops generate  --input <json> --format <bricks|css|tailwind|design[,…]> --out <dir>
-*   vitops init      [--out design-system.json] [--force]
-*   vitops validate  <design-system.json|site.json>
-*   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>] [--background <hex>]
-*   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]
-*   vitops docs      [topic] [--input <json>] [--all]
-*   vitops lint      [--input <json>] [--format <fmt>] [--src <dir>]
-*   vitops legal     [--input <site.json>] [--doc <name>] [--format <md|html|portable-text>] [--out <dir>]
-*   vitops search    setup [--domain <name>] [--dry] [--check]  |  notify [--dry] [--all] [--check]
-*   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
-*
-* Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
-* Every client brings their own consumer-editable design-system.json.
-*/
-const FORMATS = new Set([
-	"bricks",
-	"css",
-	"tailwind",
-	"design"
-]);
-const LINT_FORMATS = new Set([
-	"bricks",
-	"css",
-	"tailwind"
-]);
-const LEGAL_DOCS = new Set([
-	"privacy",
-	"terms",
-	"cookies"
-]);
-const LEGAL_OUTPUTS = new Set([
-	"md",
-	"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 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.
-
-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)
+			severity: "error",
+			reason: `\`${font[1]}\` is not a typography role`,
+			suggestion: `font-${near}`
+		};
+	}
+	const ds = /^drop-shadow-(.+)$/.exec(base);
+	if (ds && v.shadows.length && !v.shadows.includes(ds[1])) return {
+		cls: raw,
+		severity: "error",
+		reason: `\`${ds[1]}\` is not a defined shadow`,
+		suggestion: `drop-shadow-${v.shadows[0]}`
+	};
+	return null;
+}
+const CLASS_ATTR = /(?:class|className|:class)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/g;
+/** Extract class tokens from a source file, with line numbers. */
+function extractClasses(src) {
+	const out = [];
+	for (const m of src.matchAll(CLASS_ATTR)) {
+		const value = m[1] ?? m[2] ?? m[3] ?? "";
+		const line = src.slice(0, m.index).split("\n").length;
+		for (const tok of value.split(/\s+/)) if (tok && !tok.includes("${") && !tok.includes("{") && /^[@\w:[\]().%/-]+$/.test(tok)) out.push({
+			cls: tok,
+			line
+		});
+	}
+	return out;
+}
+function lintSource(files, v, format) {
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const f of files) for (const { cls, line } of extractClasses(f.text)) {
+		const verdict = judge(cls, v, format);
+		if (!verdict) continue;
+		const key = `${f.path}:${line}:${cls}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		findings.push({
+			file: f.path,
+			line,
+			...verdict
+		});
+	}
+	return findings;
+}
 
-Run \`vitops --help\` for the full option list for each subcommand.
-`;
+//#endregion
+//#region src/cli.ts
+/**
+* `vitops` — CLI for the Vitops design-system generator.
+*
+*   vitops generate  --input <json> --format <bricks|css|tailwind|design[,…]> --out <dir>
+*   vitops init      [--out design-system.json] [--force]
+*   vitops validate  <design-system.json|site.json>
+*   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>] [--background <hex>]
+*   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]
+*   vitops docs      [topic] [--input <json>] [--all]
+*   vitops lint      [--input <json>] [--format <fmt>] [--src <dir>]
+*   vitops legal     [--input <site.json>] [--doc <name>] [--format <md|html|portable-text>] [--out <dir>]
+*   vitops search    setup [--domain <name>] [--dry] [--check]  |  notify [--dry] [--all] [--check]
+*   vitops ads       setup [--provider <name>] [--dry] [--check]  |  tags  |  lint
+*   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
+*
+* Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
+* Every client brings their own consumer-editable design-system.json.
+*/
+const FORMATS = new Set([
+	"bricks",
+	"css",
+	"tailwind",
+	"design"
+]);
+const LINT_FORMATS = new Set([
+	"bricks",
+	"css",
+	"tailwind"
+]);
+const LEGAL_DOCS = new Set([
+	"privacy",
+	"terms",
+	"cookies"
+]);
+const LEGAL_OUTPUTS = new Set([
+	"md",
+	"html",
+	"portable-text"
+]);
 function fail(msg) {
 	console.error(`✖ ${msg}`);
 	process.exit(1);
@@ -830,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.
@@ -1012,7 +1661,7 @@ async function cmdMedia(argv) {
 			onProgress: (message) => console.error(`  … ${message}`)
 		});
 		if (values.dry) {
-			console.log(formatPlan$2(result.plan));
+			console.log(formatPlan$3(result.plan));
 			return;
 		}
 		console.log(`✓ media → ${values.out} (${result.written.length} written, ${result.skipped} unchanged)`);
@@ -1255,15 +1904,30 @@ async function cmdLegal(argv) {
 		docs,
 		output
 	});
+	/**
+	* A processor placed nowhere cannot appear in the cross-border disclosure — there
+	* is nothing true to say about it — so it drops out of that section silently,
+	* which is the failure that looks tidy. Reported here rather than in the document:
+	* a policy must not editorialise about its own gaps.
+	*
+	* 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.
@@ -1613,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();
@@ -1729,6 +2406,320 @@ async function cmdSearchSetup(argv) {
 	console.log(`\n${formatSummary(results)}`);
 	if (failed) process.exit(1);
 }
+/**
+* Adapt a `Config` to the ads module's own option shape.
+*
+* The same flat field map as `toSearchConsoleSetup` and `toIndexingConfig`, for the
+* same reason — utils cannot import the generator. The domain default is the one
+* derived value: a platform verifies the host the site is published at, so
+* `domains.canonical` answers it, and only an ad account verified against some
+* other host needs `site.ads.<provider>.domain` stated.
+*/
+function toAdProperties(cfg, providerFilter) {
+	const canonicalHost = (() => {
+		const url = cfg.site.domains?.canonical;
+		if (!url) return void 0;
+		try {
+			return new URL(url).hostname;
+		} catch {
+			return;
+		}
+	})();
+	const entries = cfg.site.ads ?? {};
+	const properties = AD_PROVIDER_KEYS.filter((p) => entries[p] != null).map((provider) => {
+		const e = entries[provider];
+		const domain = e.domain ?? canonicalHost;
+		return {
+			provider,
+			...e.accountId ? { accountId: e.accountId } : {},
+			...e.pixelId ? { pixelId: e.pixelId } : {},
+			...e.conversionLabel ? { conversionLabel: e.conversionLabel } : {},
+			...domain ? { domain } : {},
+			...e.domainVerification ? { domainVerification: e.domainVerification } : {},
+			...e.category ? { category: e.category } : {},
+			...e.enabled != null ? { enabled: e.enabled } : {}
+		};
+	});
+	if (providerFilter) {
+		if (!isAdProvider(providerFilter)) fail(`--provider "${providerFilter}" is not a known ad platform (expected: ${AD_PROVIDER_KEYS.join(" | ")})`);
+		const one = properties.find((p) => p.provider === providerFilter);
+		if (!one) fail(`--provider "${providerFilter}" is not in site.ads (have: ${properties.map((p) => p.provider).join(", ") || "none"})`);
+		return [one];
+	}
+	return properties;
+}
+/**
+* `vitops ads` — everything that links this site to an ad platform.
+*
+* Three subcommands, split by what they touch: `setup` writes DNS, `tags` writes
+* nothing and prints markup, `lint` reads and reports.
+*/
+async function cmdAds(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "setup": return cmdAdsSetup(rest);
+		case "tags": return cmdAdsTags(rest);
+		case "lint": return cmdAdsLint(rest);
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(ADS_HELP);
+			return;
+		default: fail(`unknown "ads" subcommand "${sub}" (expected: setup | tags | lint). Try: vitops --help`);
+	}
+}
+/**
+* Link each configured ad property: ensure the platform's domain-verification TXT,
+* report what only a human can finish.
+*
+* Idempotent by construction — the planner decides each step from live DNS, so a
+* re-run of a linked property is all skips. `--check` reports drift and exits
+* non-zero without mutating; `--dry` prints the plan and stops. Neither is offline:
+* the DNS observation runs before the planner either way.
+*
+* The one thing this does that `search setup` does not is **ask**. A first run has
+* no verification token, because the token doesn't exist until someone fetches it
+* from the platform UI — so a blocked step becomes a prompt, the answer is folded
+* into the setup, and the planner runs again on it. That re-plan matters: what gets
+* executed is always a plan the pure planner produced, never a special case built
+* out of an answer.
+*/
+async function cmdAdsSetup(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			provider: { type: "string" },
+			check: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			},
+			"no-prompt": {
+				type: "boolean",
+				default: false
+			},
+			"no-write": {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: false
+	});
+	const input = resolve(values.input);
+	let properties = toAdProperties(await loadConfig(input, values["site-env"]), values.provider);
+	if (properties.length === 0) fail("no properties in site.ads — add the ad platforms this site is linked to");
+	const dry = values.dry;
+	const check = values.check;
+	const needsDns = properties.some((p) => AD_PLATFORMS[p.provider].verification.method === "dns-txt");
+	const cfToken = loadCloudflareToken();
+	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();
+		if (!cfToken) return states;
+		for (const p of properties) {
+			const domain = p.domain;
+			if (!domain || states.has(domain)) continue;
+			if (AD_PLATFORMS[p.provider].verification.method !== "dns-txt") continue;
+			const zone = await findZoneId(cfToken, domain);
+			if (!zone.ok || !zone.zoneId) fail(`${domain}: ${zone.message}`);
+			const txt = await listApexTxt(cfToken, zone.zoneId, domain);
+			if (!txt.ok) fail(`${domain}: ${txt.message}`);
+			states.set(domain, {
+				zoneId: zone.zoneId,
+				txtContents: txt.contents
+			});
+		}
+		return states;
+	};
+	let states = await observe();
+	let adsPlan = plan$2({ properties }, states);
+	const interactive = canPrompt({
+		dry,
+		check,
+		noPrompt: values["no-prompt"]
+	});
+	const gaps = missingFields(adsPlan);
+	if (gaps.length && interactive) {
+		const answers = [];
+		for (const gap of gaps) {
+			const value = await ask(questionFor(gap.provider, gap.needs));
+			if (value) answers.push({
+				provider: gap.provider,
+				needs: gap.needs,
+				value
+			});
+		}
+		if (answers.length) {
+			properties = properties.map((p) => {
+				return answers.filter((a) => a.provider === p.provider).reduce((acc, a) => ({
+					...acc,
+					[a.needs]: a.value
+				}), p);
+			});
+			adsPlan = plan$2({ properties }, states);
+			if (!values["no-write"]) for (const a of answers) {
+				const res = writeConfigPatch(input, a.provider, a.needs, a.value);
+				if (res.written) console.log(`✓ wrote site.ads.${a.provider}.${a.needs} to ${input}`);
+				else console.error(`! ${res.reason}`);
+			}
+		}
+		states = await observe();
+		adsPlan = plan$2({ properties }, states);
+	} else if (gaps.length && !dry && !check) for (const gap of gaps) console.error(`! ${missingFieldMessage(gap.provider, gap.needs)}`);
+	if (dry || check) {
+		console.log(formatPlan$2(adsPlan));
+		if (check && hasDrift$1(adsPlan)) {
+			console.error("\n✖ ad properties are not fully linked");
+			process.exit(1);
+		}
+		return;
+	}
+	const results = [];
+	let failed = false;
+	for (const p of adsPlan.properties) {
+		const result = {
+			provider: p.provider,
+			domain: p.domain ?? "—",
+			txt: "n/a",
+			tag: p.tag.action === "skip" ? "ready" : "blocked",
+			reminders: p.reminders
+		};
+		if (p.txt.action === "blocked" || p.tag.action === "blocked") failed = true;
+		if (p.txt.action === "blocked") result.txt = "blocked";
+		else if (p.txt.action === "skip") result.txt = AD_PLATFORMS[p.provider].verification.method === "dns-txt" ? "present" : "n/a";
+		else {
+			const zoneId = p.domain ? states.get(p.domain)?.zoneId : void 0;
+			if (!cfToken || !zoneId || !p.domain || !p.txtContent) {
+				console.error(`✖ ${p.provider}: no Cloudflare zone for ${p.domain ?? "(no domain)"}`);
+				result.txt = "failed";
+				failed = true;
+			} else {
+				const r = await createApexTxt(cfToken, zoneId, p.domain, p.txtContent);
+				if (!r.ok) {
+					console.error(`✖ ${p.provider} TXT: ${r.message}`);
+					result.txt = "failed";
+					failed = true;
+				} else {
+					console.log(`✓ ${p.provider}: created TXT on ${p.domain}`);
+					result.txt = "created";
+				}
+			}
+		}
+		results.push(result);
+	}
+	console.log(`\n${formatSummary$1(results)}`);
+	if (results.some((r) => r.txt === "created")) console.log("\n  DNS takes minutes to propagate before a platform can see the record.");
+	if (results.some((r) => r.reminders.length)) console.log("  Finish the reminders above in the platform UI — no API covers those.");
+	if (failed) process.exit(1);
+}
+/**
+* Print each configured pixel as an inert, consent-gated `<script>`.
+*
+* The universal delivery path, the same reasoning as `vitops legal`: every consumer
+* has this CLI whatever their stack, so Bricks, WordPress and a hand-built site all
+* get the correct gated markup without integration code.
+*/
+async function cmdAdsTags(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			provider: { type: "string" },
+			strategy: {
+				type: "string",
+				default: "idle"
+			}
+		},
+		allowPositionals: false
+	});
+	const strategy = values.strategy;
+	if (![
+		"idle",
+		"async",
+		"interaction"
+	].includes(strategy)) fail(`--strategy "${strategy}" is not one of: idle | async | interaction`);
+	const properties = toAdProperties(await loadConfig(resolve(values.input), values["site-env"]), values.provider);
+	if (properties.length === 0) fail("no properties in site.ads — nothing to emit");
+	const out = [];
+	for (const p of properties) {
+		if (p.enabled === false) continue;
+		const tag = renderTag(p, strategy);
+		if (!tag) {
+			console.error(`! ${p.provider}: no ${AD_PLATFORMS[p.provider].tag.needs} — skipped (run \`vitops ads setup\` to be prompted for it)`);
+			continue;
+		}
+		out.push(tag);
+	}
+	if (out.length === 0) fail("no ad property has a tag id yet");
+	console.log(out.join("\n\n"));
+}
+/**
+* Report the ad-property gaps that are invisible at runtime.
+*
+* Each finding is a silent failure, which is the bar for being here at all: an
+* uncaptured click ID looks exactly like organic traffic, and a pixel on a site
+* with tracking off produces conversions no campaign gets credit for.
+*/
+async function cmdAdsLint(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			}
+		},
+		allowPositionals: false
+	});
+	const cfg = await loadConfig(resolve(values.input), values["site-env"]);
+	const properties = toAdProperties(cfg, void 0);
+	if (properties.length === 0) {
+		console.log("· no site.ads properties — nothing to check");
+		return;
+	}
+	const findings = [];
+	const trackingOn = cfg.site.tracking?.enabled === true;
+	for (const p of properties) {
+		const platform = AD_PLATFORMS[p.provider];
+		if (p.enabled === false) continue;
+		if (!tagId(p)) findings.push(`${p.provider}: no ${platform.tag.needs} — the property is on record but no tag can be emitted`);
+		const uncaptured = platform.clickIdParams.filter((param) => !(param in PLATFORM_PARAMS));
+		if (uncaptured.length) findings.push(`${p.provider}: click ID ${uncaptured.join(", ")} is not in the capture vocabulary — every conversion from this platform will arrive unattributed`);
+		if (!trackingOn) findings.push(`${p.provider}: site.tracking.enabled is not true, so ${platform.clickIdParams.join("/")} is never captured — conversions will be unattributed`);
+	}
+	if (findings.length === 0) {
+		console.log(`✓ ${properties.length} ad propert${properties.length === 1 ? "y" : "ies"} check out`);
+		return;
+	}
+	for (const f of findings) console.error(`✖ ${f}`);
+	process.exit(1);
+}
 function cliVersion() {
 	try {
 		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -1771,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: {
@@ -1793,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",
@@ -1809,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");
@@ -1828,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,
@@ -1850,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`);
@@ -1898,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",
@@ -1905,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,
 		"",
@@ -1944,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);
@@ -1955,8 +3034,9 @@ async function main() {
 		case "legal": return cmdLegal(rest);
 		case "icons": return cmdIcons(rest);
 		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 | media). Try: vitops --help`);
+		default: fail(`unknown command "${command}" (expected: ${COMMANDS.join(" | ")}). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));