@getvitops/cli 0.9.0 → 2.0.0

package/dist/cli.mjs

@@ -1,10 +1,11 @@
 #!/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 { SCHEMA_URL, defaultConfig, expandPalette, functionalRole, generate, generateDocs, roleColorUtilities, validate } from "@getvitops/generator";
-import { generateFavicons } from "@getvitops/utils";
+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, 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";
 
 //#region src/agents.ts
 /**
@@ -39,6 +40,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"
@@ -94,53 +99,314 @@ 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
+/**
+* `vitops lint` — find framework classes in consumer source that resolve to
+* nothing in the format being built.
+*
+* The problem this exists for: an unknown utility class is indistinguishable
+* from a working one. Nothing errors, nothing warns, the element just doesn't
+* get the style. Two shapes of that were found in a real consumer site:
+*
+*   • `bg-navy-d` — a leftover from the named-step scale (`d`/`xd`/`xxd`)
+*     deleted in favour of numeric steps. The hue is real, the step is not.
+*     It appeared ~10× and looked fine only because the `.card` it sat on
+*     supplied its own background.
+*   • `md-flex-row` — the css/bricks spelling of a responsive variant, used in
+*     a `tailwind`-format project where that class is never emitted (Tailwind
+*     regenerates those on demand as `@md:`). Silently inert.
+*
+* DESIGN: this deliberately only inspects classes ANCHORED TO THE CONSUMER'S
+* OWN CONFIG — a hue name, a role name, a type role, a shadow, a pattern. It
+* never tries to enumerate "all valid classes", because in the tailwind format
+* that would mean knowing Tailwind's entire built-in vocabulary, and every
+* unknown would be a false positive. Anchoring means a finding is always
+* actionable: you named something from your design system, and it doesn't
+* resolve.
+*/
 const UTIL_FAMILIES = [
 	"bg",
 	"text",
+	"icon",
 	"border",
 	"outline",
 	"fill",
 	"stroke"
 ];
-const ROLE_MODIFIERS = [
-	"",
-	"muted",
-	"x-muted",
-	"bold",
-	"x-bold",
-	"solid",
-	"solid-bold",
-	"bg-bold"
-];
+/**
+* The modifiers actually emitted for one family + role, read back out of the
+* generator's own class list.
+*
+* This used to be a hand-maintained array, which is the wrong shape for a
+* suggestion: the two role kinds emit different modifiers (a chromatic role has
+* `solid` and no bare form; a surface role the reverse), so a single list was
+* wrong for one of them no matter what it said.
+*/
+const emittedModifiers = (roleClasses, fam, role) => {
+	const prefix = `${fam}-${role}`;
+	return [...roleClasses].filter((c) => c === prefix || c.startsWith(`${prefix}-`)).map((c) => c.slice(prefix.length + 1)).filter(Boolean).sort();
+};
 function vocabulary(ds, roleClasses) {
 	return {
 		roles: Object.keys(ds.colors?.roles ?? {}),
 		hues: Object.keys(ds.colors?.palette ?? {}),
-		steps: [
-			"50",
-			"100",
-			"200",
-			"300",
-			"400",
-			"500",
-			"600",
-			"700",
-			"800",
-			"900",
-			"950"
-		],
+		steps: [...NUMERIC_STEPS],
 		typeRoles: Object.keys(ds.typography?.roles ?? {}),
 		shadows: Object.keys(ds.shadows ?? {}),
 		patterns: Object.keys(ds.patterns?.items ?? {}),
 		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));
@@ -149,10 +415,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)`
 	};
@@ -166,21 +440,25 @@ function judge(raw, v, format) {
 		const role = prefix(v.roles);
 		if (role && (!hue || role.length > hue.length)) {
 			const mod = rest.slice(role.length + 1);
+			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 modifiers: ${ROLE_MODIFIERS.filter(Boolean).join(", ")}`
+				suggestion: valid.length ? `valid modifiers: ${valid.join(", ")}` : `the \`${role}\` role emits no \`${fam}-*\` utilities`
 			};
 		}
 		if (hue) {
 			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`
 			};
@@ -193,6 +471,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}`
 		};
@@ -200,6 +479,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]}`
 	};
@@ -242,37 +522,71 @@ function lintSource(files, v, format) {
 /**
 * `vitops` — CLI for the Vitops design-system generator.
 *
-*   vitops generate  --input <json> --format <bricks|css|tailwind[,…]> --out <dir>
+*   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>]
 *
 * 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
+  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
 
 Generate options:
-  -i, --input <path>    Config file (default: ./design-system.json)
-  -f, --format <list>   bricks | css | tailwind (comma-separated; default: bricks)
+  -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)
@@ -282,9 +596,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
@@ -292,14 +610,39 @@ 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
+                        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.
 
 Common:
   -h, --help            Show this help
@@ -326,19 +669,27 @@ async function cmdGenerate(argv) {
 				type: "string",
 				short: "o",
 				default: "dist"
-			}
+			},
+			site: { type: "string" },
+			theme: { type: "string" },
+			"site-env": { type: "string" }
 		},
 		allowPositionals: false
 	});
 	const input = resolve(values.input);
 	if (!existsSync(input)) fail(`config not found: ${input}`);
+	const site = values.site ? resolve(values.site) : void 0;
+	if (site && !existsSync(site)) fail(`site config not found: ${site}`);
 	const formats = values.format.split(",").map((f) => f.trim()).filter(Boolean);
-	for (const f of formats) if (!FORMATS.has(f)) fail(`unknown format "${f}" (expected: bricks | css | tailwind)`);
+	for (const f of formats) if (!FORMATS.has(f)) fail(`unknown format "${f}" (expected: bricks | css | tailwind | design)`);
 	for (const format of formats) try {
 		const res = await generate({
 			input,
 			format,
-			outDir: values.out
+			outDir: values.out,
+			...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) {
@@ -368,13 +719,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");
@@ -385,6 +748,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) {
@@ -408,7 +795,8 @@ async function cmdFavicon(argv) {
 				short: "o",
 				default: "public"
 			},
-			"low-res": { type: "string" }
+			"low-res": { type: "string" },
+			background: { type: "string" }
 		},
 		allowPositionals: false
 	});
@@ -419,14 +807,24 @@ 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) {
+/**
+* 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 {
@@ -434,15 +832,233 @@ 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);
 	}
 	for (const w of result.warnings) console.warn(`  ! ${w}`);
 	return result.data;
 }
+/**
+* Read + resolve a site config, or exit with a message.
+*
+* Accepts JSON, or a JS/TS module with a default export — deliberately not YAML,
+* which would mean a parser dependency for one command. `resolveSiteConfig` is
+* documented as taking an already-parsed object precisely so the loader is the
+* consumer's choice; anyone on YAML can convert it or export from a module.
+*/
+async function loadSiteConfig(path, siteEnv) {
+	if (!existsSync(path)) fail(`site config not found: ${path}`);
+	let raw;
+	if (/\.(json)$/.test(path)) try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch (err) {
+		fail(`could not parse JSON: ${err.message}`);
+	}
+	else {
+		try {
+			raw = (await import(pathToFileURL(path).href)).default;
+		} catch (err) {
+			fail(`could not import ${path}: ${err.message}`);
+		}
+		if (raw == null) fail(`${path} has no default export`);
+	}
+	try {
+		return resolveSiteConfig(raw, siteEnv);
+	} catch (err) {
+		fail(err.message);
+	}
+}
+/**
+* Render the site's legal documents.
+*
+* The universal delivery path: every consumer has this CLI regardless of stack,
+* so a WordPress theme, an Eleventy build or a hand-written HTML site all get
+* 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,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			doc: {
+				type: "string",
+				short: "d",
+				multiple: true
+			},
+			format: {
+				type: "string",
+				short: "f",
+				default: "md"
+			},
+			out: {
+				type: "string",
+				short: "o"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			}
+		},
+		allowPositionals: false
+	});
+	const output = values.format;
+	if (!LEGAL_OUTPUTS.has(output)) fail(`unknown format "${output}" (expected: ${[...LEGAL_OUTPUTS].join(" | ")})`);
+	const requested = values.doc ?? [];
+	for (const d of requested) if (!LEGAL_DOCS.has(d)) fail(`unknown doc "${d}" (expected: ${[...LEGAL_DOCS].join(" | ")})`);
+	const site = await loadSiteConfig(resolve(values.input), values["site-env"]);
+	const docs = requested.length ? requested : enabledDocs(site);
+	if (docs.length === 0) fail("no legal documents are enabled — set legal.privacyPolicy.enabled (or termsOfService / cookieConsent) in your site config, or name one with --doc");
+	const files = generateLegal(site, {
+		docs,
+		output
+	});
+	if (!values.out) {
+		process.stdout.write(Object.values(files).join("\n"));
+		return;
+	}
+	const outDir = resolve(values.out);
+	mkdirSync(outDir, { recursive: true });
+	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.");
+}
 function cliVersion() {
 	try {
 		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -465,6 +1081,7 @@ function cmdDocs(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			all: {
 				type: "boolean",
 				default: false
@@ -479,45 +1096,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,
@@ -527,6 +1109,7 @@ function cmdLint(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			format: {
 				type: "string",
 				short: "f",
@@ -536,34 +1119,47 @@ function cmdLint(argv) {
 				type: "string",
 				short: "s",
 				default: "src"
+			},
+			strict: {
+				type: "boolean",
+				default: false
 			}
 		},
 		allowPositionals: false
 	});
 	const format = values.format;
-	if (!FORMATS.has(format)) fail(`unknown format "${format}" (expected: bricks | css | tailwind)`);
-	const ds = loadConfig(resolve(values.input));
+	if (!LINT_FORMATS.has(format)) fail(`unknown format "${format}" (expected: bricks | css | tailwind)`);
+	const ds = loadConfig(resolve(values.input), values.theme);
 	const srcDir = resolve(values.src);
 	if (!existsSync(srcDir)) fail(`source directory not found: ${srcDir}`);
-	const roleClasses = roleColorUtilities(Object.entries(ds.colors.roles).map(([role, hue]) => functionalRole(role, hue, expandPalette(ds.colors.palette)[hue])), ds.colors.utilities ?? [
+	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",
 		"text",
+		"icon",
 		"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({
@@ -574,6 +1170,7 @@ function cmdAgents(argv) {
 				short: "i",
 				default: "design-system.json"
 			},
+			theme: { type: "string" },
 			out: {
 				type: "string",
 				short: "o",
@@ -585,7 +1182,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;
@@ -641,6 +1238,7 @@ function cmdAgents(argv) {
 		"- `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`",
 		"",
 		...pointer,
@@ -684,7 +1282,9 @@ async function main() {
 		case "agents": return cmdAgents(rest);
 		case "docs": return cmdDocs(rest);
 		case "lint": return cmdLint(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint). Try: vitops --help`);
+		case "legal": return cmdLegal(rest);
+		case "icons": return cmdIcons(rest);
+		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));