@getvitops/cli 1.0.0 → 2.1.0

package/dist/cli.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, extname, join, parse, relative, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, parse, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { NUMERIC_STEPS, SCHEMA_URL, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, resolveSiteConfig, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
-import { generateFavicons } from "@getvitops/utils";
+import { NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isSiteConfig, resolveInput, resolveSiteConfig, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
+import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
+import { SNAPSHOT_PATH, collectEntries, formatPlan, getAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
+import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$1, processMedia } from "@getvitops/utils/media";
 
 //#region src/agents.ts
 /**
@@ -40,6 +42,10 @@ const TOPICS = {
 		path: "concepts/scales.md",
 		summary: "fluid modular type & space scales"
 	},
+	icons: {
+		path: "concepts/icons.md",
+		summary: "semantic icon names across sets, bundle derivation, sprite delivery"
+	},
 	patterns: {
 		path: "concepts/patterns.md",
 		summary: "pattern CSS: token cascade, override hooks, states, role variants"
@@ -95,6 +101,240 @@ function linkSkill(linkPath, targetDir) {
 	}
 }
 
+//#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;
+/**
+* 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.
+*/
+function parseDeclarations(body) {
+	const out = [];
+	let depth = 0;
+	let start = 0;
+	const push = (chunk) => {
+		const colon = chunk.indexOf(":");
+		if (colon < 0) return;
+		const property = chunk.slice(0, colon).trim();
+		const value = chunk.slice(colon + 1).trim();
+		if (!property || property.includes("{") || !value) return;
+		out.push({
+			property,
+			value
+		});
+	};
+	for (let i = 0; i < body.length; i++) {
+		const ch = body[i];
+		if (ch === "(" || ch === "[") depth++;
+		else if (ch === ")" || ch === "]") depth--;
+		else if (ch === ";" && depth === 0) {
+			push(body.slice(start, i));
+			start = i + 1;
+		}
+	}
+	push(body.slice(start));
+	return out;
+}
+/**
+* Scan a stylesheet into its style rules.
+*
+* Never throws: this runs over consumer source that may be a fragment, and a
+* linter that dies on one unparseable file is one nobody keeps in CI.
+*/
+function scanCss(css) {
+	const src = stripComments(css);
+	const rules = [];
+	const stack = [];
+	let depth = 0;
+	let preludeStart = 0;
+	for (let i = 0; i < src.length; i++) {
+		const ch = src[i];
+		if (ch === "\"" || ch === "'") {
+			const quote = ch;
+			i++;
+			while (i < src.length && src[i] !== quote) {
+				if (src[i] === "\\") i++;
+				i++;
+			}
+			continue;
+		}
+		if (ch === "{") {
+			const raw = src.slice(preludeStart, i);
+			const prelude = raw.trim();
+			stack.push({
+				prelude,
+				index: preludeStart + raw.indexOf(prelude.slice(0, 1))
+			});
+			depth++;
+			preludeStart = i + 1;
+			continue;
+		}
+		if (ch === "}") {
+			const frame = stack.pop();
+			depth--;
+			if (frame && !frame.prelude.startsWith("@")) {
+				const bodyStart = src.indexOf("{", frame.index) + 1;
+				rules.push({
+					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)
+				});
+			}
+			preludeStart = i + 1;
+			continue;
+		}
+	}
+	return rules.filter((r) => r.selector && depth >= 0);
+}
+/** `<style>` block contents from an .astro/.vue/.svelte/.html file. */
+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);
+		out.push({
+			css: m[1] ?? "",
+			line
+		});
+	}
+	return out;
+}
+
+//#endregion
+//#region src/lint-css.ts
+/**
+* The framework's own track widths. Declared in two places today
+* (`core/css/layout.css` and the tailwind emitter), so a rule keyed to the token
+* NAME rather than to a value survives either one moving.
+*/
+const TRACK_WIDTHS = [
+	"--width-measure",
+	"--width-breakout",
+	"--width-spotlight"
+];
+/**
+* Column ratios that correspond to a `split-<a>-<b>` class.
+*
+* `.split` is FLEX, not grid — `display: flex` with `flex: 1` children, and a
+* ratio class setting `--_split-a`/`--_split-b`. Equal columns are the base
+* `.split` with no ratio class, which is why `1fr 1fr` is deliberately absent:
+* suggesting `split-1-1` would name a class that does not exist, and this file
+* would then be committing the very defect `lint.ts` reports.
+*/
+const SPLITS = {
+	"1fr 2fr": "1-2",
+	"2fr 1fr": "2-1",
+	"1fr 3fr": "1-3",
+	"3fr 1fr": "3-1",
+	"1fr 4fr": "1-4",
+	"4fr 1fr": "4-1",
+	"2fr 3fr": "2-3",
+	"3fr 2fr": "3-2"
+};
+const decl = (rule, property) => rule.declarations.find((d) => d.property === property)?.value;
+/** Is this rule inside a `min-width` media or container query? */
+const inMinWidthQuery = (rule) => rule.conditions.some((c) => /min-width\s*:/.test(c));
+/** The framework breakpoint a `min-width` condition corresponds to, if any. */
+function breakpointOf(rule) {
+	const rem = rule.conditions.map((c) => /min-width\s*:\s*([\d.]+)rem/.exec(c)?.[1]).find(Boolean);
+	if (!rem) return null;
+	const n = Number(rem);
+	return n >= 80 ? "xl" : n >= 64 ? "lg" : n >= 48 ? "md" : n >= 30 ? "sm" : null;
+}
+/** Spell a responsive utility the way the target format actually emits it. */
+const responsive = (bp, base, format) => format === "tailwind" ? `@${bp}:${base}` : `${bp}-${base}`;
+/**
+* One rule = one check. Kept as data rather than a chain of ifs so adding a
+* primitive is adding an entry, and so each carries its own explanation.
+*/
+const RULES = [
+	(rule) => {
+		const token = TRACK_WIDTHS.find((t) => decl(rule, "max-inline-size")?.includes(t) || decl(rule, "max-width")?.includes(t));
+		const centred = /\bauto\b/.test(decl(rule, "margin-inline") ?? decl(rule, "margin") ?? "");
+		if (!token || !centred) return null;
+		return {
+			cls: `${rule.selector} { max-inline-size: var(${token}); margin-inline: auto }`,
+			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"
+		};
+	},
+	(rule, format) => {
+		const cols = decl(rule, "grid-template-columns");
+		if (!cols || !inMinWidthQuery(rule)) return null;
+		const ratio = SPLITS[cols.replace(/\s+/g, " ").trim()];
+		const bp = ratio && breakpointOf(rule);
+		if (!ratio || !bp) return null;
+		return {
+			cls: `${rule.selector} { grid-template-columns: ${cols} }`,
+			severity: "suggestion",
+			reason: `a ${cols} split behind a min-width query is the \`split-${ratio}\` utility`,
+			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, format) => {
+		if (decl(rule, "display") !== "flex") return null;
+		if (decl(rule, "align-items") !== "center") return null;
+		if (/column/.test(decl(rule, "flex-direction") ?? "")) return null;
+		return {
+			cls: `${rule.selector} { display: flex; align-items: center }`,
+			severity: "suggestion",
+			reason: "the framework has this as utilities",
+			suggestion: format === "tailwind" ? "Tailwind's own `flex items-center` (the framework drops these names in this format)" : "`flex items-center`, or `.cluster-start` if this is a row of related controls"
+		};
+	}
+];
+/**
+* Lint stylesheets and the `<style>` blocks of component files.
+*
+* `files` carries raw text, same as `lintSource` — this module stays free of the
+* filesystem so the caller owns discovery.
+*/
+/**
+* The banner every generated stylesheet opens with.
+*
+* Linting the generator's own output is the worst false positive this tool can
+* produce: the emitted bundle contains the framework's real implementations of
+* these very patterns, so it reports `.split` as reinventing `.split`. The
+* `css` format writes `styles.css` into the consumer's source tree (`src/styles`
+* by default), which is squarely inside what `--src` scans.
+*
+* Matched on the banner rather than on a path, because the output directory is
+* configurable and a path rule would silently stop working when someone changes
+* it.
+*/
+const GENERATED = /^\s*\/\*!?\s*GENERATED\b|do not edit by hand\./;
+function lintCss(files, format) {
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		if (GENERATED.test(file.text.slice(0, 400))) continue;
+		const blocks = file.path.endsWith(".css") ? [{
+			css: file.text,
+			line: 1
+		}] : extractStyleBlocks(file.text);
+		for (const block of blocks) for (const rule of scanCss(block.css)) for (const check of RULES) {
+			const verdict = check(rule, format);
+			if (!verdict) continue;
+			const line = block.line + rule.line - 1;
+			const key = `${file.path}:${line}:${verdict.reason}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			findings.push({
+				file: file.path,
+				line,
+				...verdict
+			});
+			break;
+		}
+	}
+	return findings;
+}
+
 //#endregion
 //#region src/lint.ts
 /**
@@ -154,10 +394,21 @@ function vocabulary(ds, roleClasses) {
 		roleClasses: new Set(roleClasses)
 	};
 }
-/** Strip Tailwind variant prefixes (`@md:`, `hover:`, `dark:`) from a candidate. */
-const stripVariants = (cls) => {
+/**
+* Strip variant prefixes (`@md:`, `hover:`, `dark:`) from a candidate.
+*
+* Format-aware, because the container-query spelling only exists in tailwind.
+* Stripping `@md:` unconditionally made the check asymmetric: `md-split-1-2` in a
+* tailwind project was caught, but `@md:split-1-2` in a css/bricks project became
+* a bare `split-1-2` that matched nothing and returned null — the same silent
+* no-op, in the other direction, unreported.
+*/
+const stripVariants = (cls, format) => {
 	let out = cls;
-	while (/^@?[a-zA-Z0-9_-]+:/.test(out)) out = out.slice(out.indexOf(":") + 1);
+	while (/^@?[a-zA-Z0-9_-]+:/.test(out)) {
+		if (format !== "tailwind" && out.startsWith("@")) break;
+		out = out.slice(out.indexOf(":") + 1);
+	}
 	return out;
 };
 const nearest = (want, pool) => pool.find((p) => p.startsWith(want) || want.startsWith(p));
@@ -166,10 +417,18 @@ const nearest = (want, pool) => pool.find((p) => p.startsWith(want) || want.star
 * which is the common case and the whole reason this is low-noise.
 */
 function judge(raw, v, format) {
-	const cls = stripVariants(raw);
+	const cls = stripVariants(raw, format);
+	const cq = /^@(sm|md|lg|xl):(.+)$/.exec(cls);
+	if (cq && format !== "tailwind") return {
+		cls: raw,
+		severity: "error",
+		reason: `\`@${cq[1]}:\` container-query variants are a tailwind-format spelling; the ${format} format emits pre-expanded classes`,
+		suggestion: `${cq[1]}-${cq[2]}`
+	};
 	const bp = /^(sm|md|lg|xl)-(.+)$/.exec(cls);
 	if (bp && format === "tailwind") return {
 		cls: raw,
+		severity: "error",
 		reason: `\`${bp[1]}-\` responsive classes are not emitted in the tailwind format`,
 		suggestion: `@${bp[1]}:${bp[2]} (framework breakpoints) or ${bp[1]}:${bp[2]} (Tailwind's)`
 	};
@@ -186,6 +445,7 @@ function judge(raw, v, format) {
 			const valid = emittedModifiers(v.roleClasses, fam, role);
 			return {
 				cls: raw,
+				severity: "error",
 				reason: `\`${fam}-${role}${mod ? `-${mod}` : ""}\` is not emitted for the \`${role}\` role`,
 				suggestion: valid.length ? `valid modifiers: ${valid.join(", ")}` : `the \`${role}\` role emits no \`${fam}-*\` utilities`
 			};
@@ -194,11 +454,13 @@ function judge(raw, v, format) {
 			const step = rest.slice(hue.length + 1);
 			if (step === "") return {
 				cls: raw,
+				severity: "error",
 				reason: `\`${fam}-${hue}\` names a palette hue with no step`,
 				suggestion: `${fam}-${hue}-500, or a role such as ${fam}-${v.roles[0] ?? "neutral"}`
 			};
 			if (!v.steps.includes(step)) return {
 				cls: raw,
+				severity: "error",
 				reason: `\`${step}\` is not a step on the \`${hue}\` scale (steps are 50…950)`,
 				suggestion: `${fam}-${hue}-500, or a role such as ${fam}-${v.roles[0] ?? "neutral"} which also flips in dark mode`
 			};
@@ -211,6 +473,7 @@ 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}`
 		};
@@ -218,6 +481,7 @@ function judge(raw, v, format) {
 	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]}`
 	};
@@ -262,12 +526,14 @@ function lintSource(files, v, format) {
 *
 *   vitops generate  --input <json> --format <bricks|css|tailwind|design[,…]> --out <dir>
 *   vitops init      [--out design-system.json] [--force]
-*   vitops validate  <design-system.json>
-*   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>]
+*   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 indexing  [--input <site.json>] [--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.
@@ -295,25 +561,38 @@ const LEGAL_OUTPUTS = new Set([
 ]);
 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
+  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 indexing [options]    Tell search engines about a deploy (sitemap + IndexNow)
+  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
 
 Generate options:
-  -i, --input <path>    Config file (default: ./design-system.json)
+  -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)
-      --site <path>     Site config; also emits legal/*.html into the output
-                        directory (see: vitops legal). Omitted: no legal files.
+      --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)
@@ -323,9 +602,13 @@ 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>    Config file (default: ./design-system.json; validated if present)
+  -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
@@ -333,14 +616,25 @@ Agents options:
 Docs options:
   <topic>               classes | authoring | formats | color | scales | patterns | elements
                         (no topic: list topics with summaries)
-  -i, --input <path>    Config file (default: ./design-system.json)
+  -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>    Config file (default: ./design-system.json)
+  -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
@@ -356,6 +650,56 @@ Legal options:
   Generated from your config — a starting point, not legal advice. Review before
   publishing, and make sure the config describes what your site actually does.
 
+Indexing 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 this 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 needs a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
+  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), added as an owner of the
+  property.
+
+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
 `;
@@ -382,7 +726,9 @@ async function cmdGenerate(argv) {
 				short: "o",
 				default: "dist"
 			},
-			site: { type: "string" }
+			site: { type: "string" },
+			theme: { type: "string" },
+			"site-env": { type: "string" }
 		},
 		allowPositionals: false
 	});
@@ -397,7 +743,9 @@ async function cmdGenerate(argv) {
 			input,
 			format,
 			outDir: values.out,
-			...site ? { site } : {}
+			...site ? { site } : {},
+			...values.theme ? { theme: values.theme } : {},
+			...values["site-env"] ? { siteEnv: values["site-env"] } : {}
 		});
 		console.log(`✓ ${format} → ${res.outDir} (${res.written.length} paths)`);
 	} catch (err) {
@@ -427,13 +775,25 @@ function cmdInit(argv) {
 	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.`);
 }
+/**
+* Validate a config against the schema its shape says it is.
+*
+* Routing on kind rather than asking the caller matters here: pointed at a site
+* config, the design-system schema used to report a single `unrecognized_keys`
+* for `designSystem` and nothing about the file's actual contents — a wrong
+* answer that reads like a right one. A site config is validated whole, which
+* also covers the cross-field integrity JSON Schema can't express.
+*/
 function cmdValidate(argv) {
 	const { values, positionals } = parseArgs({
 		args: argv,
-		options: { input: {
-			type: "string",
-			short: "i"
-		} },
+		options: {
+			input: {
+				type: "string",
+				short: "i"
+			},
+			"site-env": { type: "string" }
+		},
 		allowPositionals: true
 	});
 	const path = resolve(positionals[0] ?? values.input ?? "design-system.json");
@@ -444,6 +804,30 @@ function cmdValidate(argv) {
 	} catch (err) {
 		fail(`could not parse JSON: ${err.message}`);
 	}
+	if (isSiteConfig(raw)) {
+		let site;
+		try {
+			site = resolveSiteConfig(raw, values["site-env"]);
+		} catch (err) {
+			console.error(`✖ ${path} is invalid as a site config:`);
+			console.error(err.message.replace(/^Invalid site config:\n/, ""));
+			process.exit(1);
+		}
+		const themes = site.designSystem?.themes ?? {};
+		let bad = false;
+		for (const name of Object.keys(themes)) {
+			const result = validate(resolveTheme(themes, name));
+			for (const w of result.warnings) console.warn(`  ! designSystem.themes.${name}: ${w}`);
+			if (result.ok) continue;
+			bad = true;
+			console.error(`✖ ${path} — designSystem.themes.${name} is not a complete design system:`);
+			for (const e of result.errors) console.error(`  • ${e.path.join(".") || "(root)"}: ${e.message}`);
+		}
+		if (bad) process.exit(1);
+		const n = Object.keys(themes).length;
+		console.log(`✓ ${path} is a valid site config (${n} theme${n === 1 ? "" : "s"})`);
+		return;
+	}
 	const result = validate(raw);
 	for (const w of result.warnings) console.warn(`  ! ${w}`);
 	if (result.ok) {
@@ -467,7 +851,8 @@ async function cmdFavicon(argv) {
 				short: "o",
 				default: "public"
 			},
-			"low-res": { type: "string" }
+			"low-res": { type: "string" },
+			background: { type: "string" }
 		},
 		allowPositionals: false
 	});
@@ -478,14 +863,117 @@ async function cmdFavicon(argv) {
 		const written = await generateFavicons({
 			source,
 			outputDir: values.out,
-			...values["low-res"] ? { lowResSource: resolve(values["low-res"]) } : {}
+			...values["low-res"] ? { lowResSource: resolve(values["low-res"]) } : {},
+			...values.background ? { backgroundColor: values.background } : {}
 		});
 		console.log(`✓ favicons → ${values.out} (${written.length} files)`);
 	} catch (err) {
 		fail(err.message);
 	}
 }
-function loadConfig(path) {
+const OUTPUT_KINDS = new Set([
+	"webm",
+	"mp4",
+	"poster"
+]);
+/**
+* `vitops media` — encode a directory of raw video into web-ready outputs.
+*
+* Flags only, with no config file, following `favicon`: `site.favicon` exists in
+* the schema and `cmdFavicon` still doesn't read it. The same reasoning applies
+* more strongly here — `legal`, `icons` and `indexing` are anchored to a
+* `SiteConfig` because what they emit *describes the site*, and an encoder setting
+* describes a build step.
+*/
+async function cmdMedia(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			raw: {
+				type: "string",
+				default: "raw"
+			},
+			out: {
+				type: "string",
+				short: "o",
+				default: "src/assets/processed"
+			},
+			"max-width": { type: "string" },
+			crf: { type: "string" },
+			"max-bitrate": { type: "string" },
+			audio: {
+				type: "boolean",
+				default: false
+			},
+			"poster-time": { type: "string" },
+			outputs: { type: "string" },
+			manifest: {
+				type: "string",
+				default: MEDIA_MANIFEST_PATH
+			},
+			force: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: false
+	});
+	const num = (flag, raw) => {
+		if (raw === void 0) return void 0;
+		const n = Number(raw);
+		if (!Number.isFinite(n) || n < 0) fail(`media: --${flag} must be a non-negative number`);
+		return n;
+	};
+	let outputs;
+	if (values.outputs) {
+		outputs = values.outputs.split(",").map((s) => s.trim());
+		for (const kind of outputs) if (!OUTPUT_KINDS.has(kind)) fail(`media: unknown output "${kind}" (expected: webm | mp4 | poster)`);
+	}
+	const maxWidth = num("max-width", values["max-width"]);
+	const crf = num("crf", values.crf);
+	const posterTime = num("poster-time", values["poster-time"]);
+	const config = {
+		...maxWidth !== void 0 ? { maxWidth } : {},
+		...crf !== void 0 ? { crf } : {},
+		...values["max-bitrate"] ? { maxBitrate: values["max-bitrate"] } : {},
+		...values.audio ? { audio: true } : {},
+		...posterTime !== void 0 ? { posterTime } : {},
+		...outputs ? { outputs } : {}
+	};
+	try {
+		const result = await processMedia({
+			raw: values.raw,
+			out: values.out,
+			config,
+			manifest: values.manifest,
+			force: values.force,
+			dry: values.dry,
+			onProgress: (message) => console.error(`  … ${message}`)
+		});
+		if (values.dry) {
+			console.log(formatPlan$1(result.plan));
+			return;
+		}
+		console.log(`✓ media → ${values.out} (${result.written.length} written, ${result.skipped} unchanged)`);
+		for (const note of result.plan.notes) console.error(`  ! ${note}`);
+	} catch (err) {
+		fail(err.message);
+	}
+}
+/**
+* Read + parse + validate the design system at `path`, or exit with a message.
+*
+* `path` may be a `design-system.json` **or** the larger site config that embeds
+* one — every command that judges source against the design system (`docs`,
+* `lint`, `agents`) accepts either, so a consumer who keeps their tokens in
+* `company.json` doesn't have to maintain a second file for the tooling's sake.
+* `resolveInput` tells them apart by shape and resolves the theme.
+*/
+function loadConfig(path, theme) {
 	if (!existsSync(path)) fail(`config not found: ${path}`);
 	let raw;
 	try {
@@ -493,9 +981,16 @@ function loadConfig(path) {
 	} catch (err) {
 		fail(`could not parse JSON: ${err.message}`);
 	}
-	const result = validate(raw);
+	let resolved;
+	try {
+		resolved = resolveInput(raw, theme != null ? { theme } : {});
+	} catch (err) {
+		fail(`${path}: ${err.message}`);
+	}
+	const result = validate(resolved.designSystem);
 	if (!result.ok) {
-		console.error(`✖ ${path} is invalid:`);
+		const where = resolved.theme != null ? ` (designSystem.themes.${resolved.theme})` : "";
+		console.error(`✖ ${path}${where} is invalid:`);
 		for (const e of result.errors) console.error(`  • ${e.path.join(".") || "(root)"}: ${e.message}`);
 		process.exit(1);
 	}
@@ -540,6 +1035,128 @@ async function loadSiteConfig(path, siteEnv) {
 * the same documents without any integration code. Prints to stdout like
 * `vitops docs`, or writes files when given `--out`.
 */
+/**
+* Report the icon vocabulary a project actually uses, and optionally build the
+* sprite from it.
+*
+* A sibling of `legal` rather than a widening of `lint`: `lint` judges classes
+* against a design-system.json, whereas icons are anchored to a SiteConfig.
+*
+* Exit codes carry the same distinction the Astro integration makes. A name the
+* config DECLARES but that doesn't resolve is a config error and fails the
+* command; a name only the SCAN found is reported and tolerated, because a bare
+* unmapped name is more often a local src/icons/*.svg than a mistake. Runtime-
+* computed names are listed with file and line so they can be declared, never
+* guessed at.
+*/
+async function cmdIcons(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			site: {
+				type: "string",
+				default: "site.json"
+			},
+			src: {
+				type: "string",
+				default: "src"
+			},
+			sprite: {
+				type: "boolean",
+				default: false
+			},
+			out: {
+				type: "string",
+				short: "o",
+				default: "dist"
+			},
+			json: {
+				type: "boolean",
+				default: false
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			}
+		},
+		allowPositionals: false
+	});
+	const sitePath = resolve(values.site);
+	const icons = existsSync(sitePath) ? (await loadSiteConfig(sitePath, values["site-env"])).icons ?? {} : {};
+	const ui = icons.ui ?? "fa7-solid";
+	const brand = icons.brand ?? "simple-icons";
+	const weight = icons.weight;
+	const weightOpt = weight ? { weight } : {};
+	let include = {};
+	try {
+		include = generateIconInclude({ ...icons });
+	} catch (e) {
+		fail(e.message);
+	}
+	const add = (prefix, name) => {
+		const list = include[prefix] ??= [];
+		if (!list.includes(name)) list.push(name);
+	};
+	const srcDir = resolve(values.src);
+	const scanned = existsSync(srcDir) ? collectIconRefs(scanFiles(srcDir)) : null;
+	const unmapped = [];
+	for (const name of scanned?.names ?? []) {
+		const colon = name.indexOf(":");
+		if (colon > 0) {
+			add(name.slice(0, colon), name.slice(colon + 1));
+			continue;
+		}
+		try {
+			const q = resolveIcon(name, ui, weightOpt);
+			add(q.slice(0, q.indexOf(":")), q.slice(q.indexOf(":") + 1));
+		} catch {
+			unmapped.push(name);
+		}
+	}
+	const dynamic = (scanned?.dynamic ?? []).map((d) => ({
+		file: relative(process.cwd(), d.file),
+		line: d.line,
+		expr: d.expr
+	}));
+	const total = Object.values(include).flat().length;
+	let sprite = null;
+	if (values.sprite) {
+		const aliases = {};
+		for (const name of icons.semantic ?? []) try {
+			aliases[`icon-${name}`] = resolveIcon(name, ui, weightOpt);
+		} catch {}
+		const built = await buildIconSprite({
+			include,
+			aliases
+		});
+		const outDir = resolve(values.out);
+		mkdirSync(outDir, { recursive: true });
+		writeFileSync(join(outDir, "icons.svg"), built.svg);
+		sprite = {
+			ids: built.ids,
+			missing: built.missing
+		};
+	}
+	if (values.json) process.stdout.write(`${JSON.stringify({
+		ui,
+		brand,
+		weight: weight ?? null,
+		include,
+		unmapped,
+		dynamic,
+		sprite
+	}, null, 2)}\n`);
+	else {
+		console.log(`icon sets: ui=${ui} brand=${brand}${weight ? ` weight=${weight}` : ""}`);
+		for (const [prefix, names] of Object.entries(include)) console.log(`  ${prefix}: ${names.length} — ${names.join(", ")}`);
+		console.log(`✓ ${total} icon(s) across ${Object.keys(include).length} set(s)`);
+		if (sprite) console.log(`✓ sprite → ${resolve(values.out)}/icons.svg (${sprite.ids.length} symbols)`);
+		for (const d of dynamic) console.log(`  ! ${d.file}:${d.line}  ${d.expr} — computed at runtime, declare it in icons`);
+		if (unmapped.length) console.log(`  ! not in the '${ui}' map: ${unmapped.join(", ")} (fine for a local svg or sprite id)`);
+		if (sprite?.missing.length) console.log(`  ! absent from the sprite: ${sprite.missing.join(", ")}`);
+	}
+	if (sprite?.missing.length) process.exitCode = 1;
+}
 async function cmdLegal(argv) {
 	const { values } = parseArgs({
 		args: argv,
@@ -591,6 +1208,209 @@ async function cmdLegal(argv) {
 	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.");
 }
+/**
+* Adapt a `SiteConfig` to the indexing module's own option shape.
+*
+* A flat field map, as intended: `@getvitops/utils` cannot import from the
+* generator (the generator already depends on it), so `IndexingConfig` mirrors the
+* `seo.indexing` block rather than being it. The one piece of judgment here is the
+* origin — see below.
+*/
+function toIndexingConfig(site, siteEnv) {
+	const indexing = site.seo?.indexing ?? {};
+	const env = site.environments?.[siteEnv];
+	const canonical = env?.url ?? site.domains?.canonical;
+	return {
+		...canonical ? { canonical } : {},
+		...indexing.sitemapUrl ? { sitemapUrl: indexing.sitemapUrl } : {},
+		...indexing.indexNow ? { indexNow: indexing.indexNow } : {},
+		...indexing.searchConsole ? { searchConsole: indexing.searchConsole } : {},
+		...indexing.priorityUrls ? { priorityUrls: indexing.priorityUrls } : {},
+		...env?.robots ?? site.seo?.robots ? { robots: env?.robots ?? site.seo?.robots } : {}
+	};
+}
+/**
+* The Search Console credential, from either supported source.
+*
+* Never from the config file: it is the one genuine secret in this command, and a
+* `site.json` is committed. Returns `undefined` rather than failing, so a site
+* running IndexNow alone doesn't need a GCP project at all.
+*/
+function loadServiceAccount() {
+	const inline = process.env.VITOPS_GSC_SERVICE_ACCOUNT;
+	const path = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+	const raw = inline ?? (path && existsSync(path) ? readFileSync(path, "utf8") : void 0);
+	if (!raw) return void 0;
+	try {
+		return parseServiceAccount(raw);
+	} catch (err) {
+		fail(`${inline ? "VITOPS_GSC_SERVICE_ACCOUNT" : `GOOGLE_APPLICATION_CREDENTIALS (${path})`}: ${err.message}`);
+	}
+}
+/** Read a sitemap from a URL or a local path. */
+const readSitemap = async (source) => {
+	if (/^https?:\/\//i.test(source)) {
+		const res = await fetch(source);
+		if (!res.ok) fail(`could not fetch ${source}: ${res.status}`);
+		return res.text();
+	}
+	if (!existsSync(source)) fail(`sitemap not found: ${source}`);
+	return readFileSync(source, "utf8");
+};
+/**
+* Tell search engines a deploy happened.
+*
+* Worth being precise about what this is, because the obvious expectation is
+* wrong: **Google has no API that requests indexing.** The Search Console button
+* is not exposed anywhere, URL Inspection is read-only, and the sitemap ping
+* endpoint was removed in 2023. So the Google half of this command resubmits the
+* sitemap and then *verifies* the outcome with `--check`; the immediate-push half
+* is IndexNow, which Google does not participate in.
+*
+* The Indexing API is deliberately absent — see `@getvitops/utils/indexing`'s
+* `gsc.ts`.
+*/
+async function cmdIndexing(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			sitemap: { type: "string" },
+			urls: { type: "string" },
+			all: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			},
+			check: {
+				type: "boolean",
+				default: false
+			},
+			"new-key": {
+				type: "boolean",
+				default: false
+			},
+			"write-key": { type: "string" },
+			snapshot: {
+				type: "string",
+				default: SNAPSHOT_PATH
+			}
+		},
+		allowPositionals: false
+	});
+	if (values["new-key"]) {
+		const key = newKey();
+		console.log(key);
+		console.log(`\n  Add to your site config:\n    "seo": { "indexing": { "indexNow": { "key": "${key}" } } }`);
+		console.log(`  Then serve it at /${key}.txt — \`vitops indexing --write-key public\`.`);
+		return;
+	}
+	const config = toIndexingConfig(await loadSiteConfig(resolve(values.input), values["site-env"]), values["site-env"]);
+	if (values["write-key"] !== void 0) {
+		const key = config.indexNow?.key;
+		if (!key) fail("no seo.indexing.indexNow.key in the config — generate one with --new-key");
+		const dir = resolve(values["write-key"]);
+		mkdirSync(dir, { recursive: true });
+		const file = join(dir, `${key}.txt`);
+		writeFileSync(file, keyFileContents(key));
+		console.log(`✓ IndexNow key file → ${file}`);
+		console.log(`  It must be served at ${resolveKeyLocation(config) ?? `/${key}.txt`}`);
+		return;
+	}
+	const sitemapUrl = values.sitemap ?? resolveSitemapUrl(config);
+	if (!sitemapUrl) fail("no sitemap to read — set seo.indexing.sitemapUrl or domains.canonical, or pass --sitemap");
+	const explicitUrls = values.urls ? values.urls.split(",").map((u) => u.trim()).filter(Boolean) : void 0;
+	const current = explicitUrls?.length && !values.check ? [] : (await collectEntries(sitemapUrl, readSitemap)).entries;
+	const snapshotPath = resolve(values.snapshot);
+	const p = plan({
+		config: {
+			...config,
+			sitemapUrl
+		},
+		current,
+		previous: readSnapshot(snapshotPath),
+		explicitUrls,
+		all: values.all
+	});
+	console.log(formatPlan(p));
+	if (p.blocked) return;
+	if (values.dry) {
+		console.log("\n(--dry: nothing was submitted)");
+		return;
+	}
+	const account = loadServiceAccount();
+	let failed = false;
+	if (values.check) {
+		if (!p.searchConsole.siteUrl) fail("--check needs seo.indexing.searchConsole.siteUrl (the Search Console property)");
+		if (!account) fail("--check needs a Search Console service account in VITOPS_GSC_SERVICE_ACCOUNT or GOOGLE_APPLICATION_CREDENTIALS");
+		if (p.check.length === 0) fail("--check needs seo.indexing.priorityUrls — the pages whose indexing matters");
+		const token = await getAccessToken(account);
+		console.log(`\nInspecting ${p.check.length} priority URL(s):`);
+		for (const url of p.check) {
+			const r = await inspectUrl(token, p.searchConsole.siteUrl, url);
+			if (r.error) {
+				console.log(`  ? ${url} — ${r.error}`);
+				failed = true;
+			} else {
+				console.log(`  ${r.indexed ? "✓" : "✗"} ${url} — ${r.coverageState ?? r.verdict ?? "unknown"}`);
+				if (!r.indexed) failed = true;
+			}
+		}
+		if (failed) {
+			console.error("\n✖ one or more priority URLs are not indexed");
+			process.exit(1);
+		}
+		console.log("\n✓ every priority URL is indexed");
+		return;
+	}
+	if (p.indexNow.enabled) {
+		const { key, keyLocation } = p.indexNow;
+		const check = await verifyKeyFile(keyLocation, key);
+		if (!check.ok) {
+			console.error(`✖ IndexNow key file check failed — ${check.reason}`);
+			console.error(`  Write it with: vitops indexing --write-key <public dir>`);
+			failed = true;
+		} else {
+			let sent = 0;
+			for (const batch of p.indexNow.batches) {
+				const r = await submitBatch(p.indexNow, batch);
+				if (!r.ok) {
+					console.error(`✖ IndexNow: ${r.message ?? r.status}`);
+					failed = true;
+					break;
+				}
+				sent += r.urls;
+			}
+			if (!failed) console.log(`✓ IndexNow: ${sent} URL(s) submitted`);
+		}
+	}
+	if (p.searchConsole.enabled) if (!account) console.log("· Search Console: skipped — no VITOPS_GSC_SERVICE_ACCOUNT / GOOGLE_APPLICATION_CREDENTIALS");
+	else {
+		const r = await submitSitemap(await getAccessToken(account), p.searchConsole.siteUrl, sitemapUrl);
+		if (r.ok) console.log(`✓ Search Console: sitemap resubmitted`);
+		else {
+			console.error(`✖ Search Console: ${r.message}`);
+			failed = true;
+		}
+	}
+	if (failed) process.exit(1);
+	if (current.length > 0) {
+		writeSnapshot(snapshotPath, toSnapshot(sitemapUrl, current, (/* @__PURE__ */ new Date()).toISOString()));
+		console.log(`  state → ${relative(process.cwd(), snapshotPath)}`);
+	}
+	if (p.check.length > 0) console.log(`\n  Indexing is not instant. Run \`vitops indexing --check\` in a day or two to see what Google actually did.`);
+}
 function cliVersion() {
 	try {
 		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -613,6 +1433,7 @@ function cmdDocs(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			all: {
 				type: "boolean",
 				default: false
@@ -627,45 +1448,10 @@ function cmdDocs(argv) {
 		return;
 	}
 	if (topic && !TOPICS[topic]) fail(`unknown topic "${topic}". Valid topics:\n${topicList()}`);
-	const docs = generateDocs(loadConfig(resolve(values.input)), generatorAssetsDir());
+	const docs = generateDocs(loadConfig(resolve(values.input), values.theme), generatorAssetsDir());
 	const paths = values.all ? Object.values(TOPICS).map((t) => t.path) : [TOPICS[topic].path];
 	process.stdout.write(paths.map((p) => docs[p]).join("\n"));
 }
-const SCAN_EXT = new Set([
-	".astro",
-	".html",
-	".htm",
-	".js",
-	".jsx",
-	".ts",
-	".tsx",
-	".vue",
-	".svelte",
-	".php",
-	".md",
-	".mdx"
-]);
-const SCAN_SKIP = new Set([
-	"node_modules",
-	"dist",
-	".git",
-	".astro",
-	"build",
-	"coverage"
-]);
-function scanFiles(dir, acc = []) {
-	for (const e of readdirSync(dir, { withFileTypes: true })) {
-		if (e.name.startsWith(".") && e.name !== ".") continue;
-		const p = join(dir, e.name);
-		if (e.isDirectory()) {
-			if (!SCAN_SKIP.has(e.name)) scanFiles(p, acc);
-		} else if (SCAN_EXT.has(extname(e.name))) acc.push({
-			path: p,
-			text: readFileSync(p, "utf8")
-		});
-	}
-	return acc;
-}
 function cmdLint(argv) {
 	const { values } = parseArgs({
 		args: argv,
@@ -675,6 +1461,7 @@ function cmdLint(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			format: {
 				type: "string",
 				short: "f",
@@ -684,13 +1471,17 @@ function cmdLint(argv) {
 				type: "string",
 				short: "s",
 				default: "src"
+			},
+			strict: {
+				type: "boolean",
+				default: false
 			}
 		},
 		allowPositionals: false
 	});
 	const format = values.format;
 	if (!LINT_FORMATS.has(format)) fail(`unknown format "${format}" (expected: bricks | css | tailwind)`);
-	const ds = loadConfig(resolve(values.input));
+	const ds = loadConfig(resolve(values.input), values.theme);
 	const srcDir = resolve(values.src);
 	if (!existsSync(srcDir)) fail(`source directory not found: ${srcDir}`);
 	const palette = expandPalette(ds.colors.palette);
@@ -701,19 +1492,26 @@ function cmdLint(argv) {
 		"border"
 	]).map((u) => u.cls);
 	const files = scanFiles(srcDir);
-	const findings = lintSource(files, vocabulary(ds, roleClasses), format);
+	const cssFiles = [...files, ...scanFiles(srcDir, { exts: [".css"] })];
+	const findings = [...lintSource(files, vocabulary(ds, roleClasses), format), ...lintCss(cssFiles, format)];
 	if (!findings.length) {
 		console.log(`✓ no unresolvable framework classes in ${values.src} (${files.length} file${files.length === 1 ? "" : "s"} scanned)`);
 		return;
 	}
-	for (const f of findings) {
-		console.error(`${f.file}:${f.line}  ${f.cls}`);
+	const errors = findings.filter((f) => f.severity === "error");
+	const suggestions = findings.filter((f) => f.severity === "suggestion");
+	for (const f of [...errors, ...suggestions]) {
+		console.error(`${f.file}:${f.line}  ${f.severity === "error" ? f.cls : `(${f.cls})`}`);
 		console.error(`    ${f.reason}`);
 		if (f.suggestion) console.error(`    try: ${f.suggestion}`);
 	}
-	const n = findings.length;
-	console.error(`\n✖ ${n} unresolvable class${n === 1 ? "" : "es"} in ${files.length} file${files.length === 1 ? "" : "s"}`);
-	process.exit(1);
+	const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+	const parts = [];
+	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)" : ""));
+	if (failing) process.exit(1);
 }
 function cmdAgents(argv) {
 	const { values } = parseArgs({
@@ -724,6 +1522,7 @@ function cmdAgents(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			out: {
 				type: "string",
 				short: "o",
@@ -735,7 +1534,7 @@ function cmdAgents(argv) {
 	});
 	const inputRel = values.input;
 	let ds = null;
-	if (existsSync(resolve(inputRel))) ds = loadConfig(resolve(inputRel));
+	if (existsSync(resolve(inputRel))) ds = loadConfig(resolve(inputRel), values.theme);
 	else console.warn(`  ⚠ ${inputRel} not found — run \`vitops init\` to scaffold one`);
 	const legacyDocsDir = values["docs-dir"];
 	let summary;
@@ -836,7 +1635,10 @@ async function main() {
 		case "docs": return cmdDocs(rest);
 		case "lint": return cmdLint(rest);
 		case "legal": return cmdLegal(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal). Try: vitops --help`);
+		case "icons": return cmdIcons(rest);
+		case "indexing": return cmdIndexing(rest);
+		case "media": return cmdMedia(rest);
+		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | indexing | media). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));