@getvitops/generator 4.1.0 → 5.0.0

package/dist/index.mjs

@@ -5,8 +5,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { transform } from "lightningcss";
 import * as z from "zod/mini";
-import { AD_PLATFORMS, AD_PROVIDER_KEYS } from "@getvitops/utils/ads";
 import { LIGHTNESS_LADDER, contrastLc, generateOklchPalette, hexToOklch, oklchStringToHex, pickOn, tintedEndpoints } from "@getvitops/utils/color";
+import { AD_PLATFORMS, AD_PROVIDER_KEYS } from "@getvitops/utils/ads";
 import { generateIconInclude, nodesToHtml, resolveIcon, t } from "@getvitops/utils";
 import { getIconData, iconToSVG, replaceIDs } from "@iconify/utils";
 
@@ -191,1683 +191,1999 @@ const TW_CLASH = new Set([
 ]);
 
 //#endregion
-//#region src/schema.ts
+//#region src/tokens.ts
 /**
-* Canonical `design-system.json` schema — the single source of truth.
+* Palette expansion + semantic colour tokens.
 *
-* Authored with `zod/mini` (tree-shakeable Zod v4). Everything else derives from it:
-*   • the `DesignSystem` TS type (`z.infer`), used throughout the generator,
-*   • the published JSON Schema (`toJSONSchema`), emitted to `schema.json` for `$schema` refs,
-*   • runtime validation (`validate`) for the CLI and to gate `generate`,
-*   • the generated `authoring.md` reference doc (walks `jsonSchema`'s descriptions).
-*/
-/**
-* Attach a JSON-Schema `description`. zod/mini has no `.describe()` method; the
-* mini-API equivalent is `.check(z.describe(…))`, and `.check()` clones — so a
-* shared sub-schema (`Scale`, `CssDecls`, …) can carry a different description
-* per use-site without mutating the original.
-*/
-const desc = (schema, text) => schema.check(z.describe(text));
-const CssDecls = desc(z.record(z.string(), z.string()), "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them.");
-const Scalar = z.union([z.string(), z.number()]);
-const VarMap = z.record(z.string(), Scalar);
-const SeededRamp = desc(z.strictObject({
-	seed: desc(z.string(), "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."),
-	anchors: z.optional(desc(z.record(z.string(), z.string()), "Step → colour overrides (hex or oklch()) pinned VERBATIM at those steps. Every other step takes its lightness from the shared ladder, with chroma and hue interpolated between the anchors — so an anchor is reproduced exactly and is the only step allowed off the ladder. An explicit anchor overrides the seed at that step; two anchors that resolve to the same step are an error."))
-}), "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps).");
-const FixedRamp = desc(z.strictObject({ tones: desc(z.union([z.array(z.string()), z.record(z.string(), z.string())]), "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map.") }), "Fixed hue: authored brand tones used verbatim; no generation.");
-const Ramp = desc(z.union([SeededRamp, FixedRamp]), "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim.");
-/**
-* A role points at a hue, and optionally declares its kind. The bare-string form
-* is the shorthand for a chromatic role — signal colours are the common case,
-* and the two or three surfaces are worth naming explicitly.
-*/
-const RoleSpecSchema = z.union([desc(z.string(), "A palette hue name. Shorthand for `{ hue, kind: \"chromatic\" }`."), z.strictObject({
-	hue: desc(z.string(), "The palette hue this role resolves to."),
-	kind: z.optional(desc(z.enum(["surface", "chromatic"]), "`surface` — a page/panel colour: gets a bare `bg-<role>` plus the full emphasis range and text scale. `chromatic` (default) — a signal colour: tints and solids only, no bare `bg-<role>`."))
-})]);
-const UtilityName = z.enum([
-	"bg",
-	"text",
-	"icon",
-	"border",
-	"outline",
-	"fill",
-	"stroke"
-]);
-const Colors = desc(z.strictObject({
-	palette: desc(z.record(z.string(), Ramp), "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`). Every ramp shares one fixed lightness ladder, so a step means the same lightness in every hue; only chroma and hue vary. Beyond the outermost authored colour the chroma decays towards a small endpoint value (0.008 light / 0.015 dark) so the near-white and near-black ends keep a whisper of the hue — but that is a **ceiling**, not a target, so a low-chroma seed stays low and **a chroma-0 seed gives a true neutral** rather than a tinted one. The ladder is also enforced: if pinned colours leave a ramp non-monotonic (some step darker than the one below it), the build fails rather than shipping a scale whose hover states run backwards."),
-	roles: desc(z.record(z.string(), RoleSpecSchema), `Maps semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's token set (\`--color-<target>-<role>[-<variant>]\` for target bg/text/icon/border), its dark-mode flip and its utility classes.\n\nA value is either a hue name (\`"danger": "rust"\`) or \`{ "hue": …, "kind": "surface" | "chromatic" }\`. **The kind decides the shape of the token set.** \`chromatic\` (the default, and what the bare-string form means) is a signal colour: its backgrounds split into tints (\`bg-<role>-x-muted\`/\`-muted\`) and solids (\`bg-<role>-solid[-bold|-x-bold]\`), with deliberately **no bare \`bg-<role>\`** — "how loud?" is a question the author answers. \`surface\` is a page/panel colour: it has a bare \`bg-<role>\` plus the full emphasis range and text scale.\n\nDark mode flips automatically; there is no per-appearance scheme grammar. The solid family and its computed \`text-on-<role>\` foreground stay mode-stable so a filled button keeps its identity. Six roles are a required core, because the shipped framework CSS references them with no fallback: ${REQUIRED_ROLES.join(", ")}. Conventional additions are ui-secondary/accent, brand-secondary, info and success.`),
-	utilities: z.optional(desc(z.array(UtilityName), "Which colour utility-class families to emit (`bg-*`, `text-*`, `icon-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, icon, border. `icon` is a separate non-text tier (a glyph may run more vivid than text); `outline`/`fill`/`stroke` have no tokens of their own and alias the border and icon tiers."))
-}), "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all role tokens and dark mode derive.");
-const Scale = z.strictObject({
-	base: desc(z.string(), "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."),
-	ratio: desc(z.number(), "Modular ratio between adjacent steps at large viewports."),
-	steps: desc(z.optional(z.number()), "Token count when `names` is absent (steps are then named 1..steps)."),
-	names: desc(z.optional(z.array(z.string())), "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix."),
-	baseStep: desc(z.optional(z.number()), "1-based index of the step whose value is `base`."),
-	baseline: desc(z.optional(z.string()), "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`)."),
-	fluid: desc(z.optional(z.strictObject({
-		minVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling bottoms out."),
-		maxVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling tops out."),
-		minRatio: desc(z.number(), "Modular ratio at/below `minVw` (usually < `ratio`).")
-	})), "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.")
-});
-const Pattern = desc(z.strictObject({
-	group: desc(z.optional(z.string()), "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`."),
-	overrides: z.optional(desc(CssDecls, "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values.")),
-	element: desc(z.optional(z.string()), "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class)."),
-	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key when no `element` is set). Combined with `element`, the pattern emits one zero-specificity `:where(<element>, .<class>)` rule so the class works on any tag and any explicit class overrides it."),
-	fill: desc(z.optional(z.boolean()), "Whether this pattern is colour-filled (states/roles drive `background-color` + `on-solid` text) or text-coloured (they drive `color`). Defaults to true when `base` declares a background."),
-	default_role: desc(z.optional(z.string()), "Semantic colour role applied to the bare/default variant."),
-	base: z.optional(desc(CssDecls, "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable.")),
-	states: desc(z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))), "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify the fill or text by n rungs — `bg-<role>-solid` → `-solid-bold`, `text-<role>` → `-bold`), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`."),
-	roles: desc(z.optional(z.array(z.string())), "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).")
-}), "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade.");
-const Patterns = desc(z.strictObject({
-	defaults: z.optional(desc(CssDecls, "Cascade-wide fallback tokens, emitted as `--<prop>-default`.")),
-	radii: z.optional(desc(CssDecls, "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases).")),
-	groups: desc(z.optional(z.record(z.string(), CssDecls)), "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key."),
-	z: desc(z.optional(z.record(z.string(), z.number())), "Z-index tiers → `--z-tier-<name>`."),
-	items: desc(z.optional(z.record(z.string(), Pattern)), "The component patterns to emit, keyed by name.")
-}), "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives.");
-const TypographyRole = desc(z.record(z.string(), Scalar), "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. Note the last four are spelled with their full CSS property names — `transform` and `decoration` are NOT accepted. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped `transform: uppercase` is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels.");
-const Typography = desc(z.strictObject({
-	families: desc(z.optional(z.record(z.string(), z.string())), "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\")."),
-	roles: desc(z.optional(z.record(z.string(), TypographyRole)), "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class."),
-	headings: desc(z.optional(z.record(z.string(), z.string())), "Maps bare elements to type roles so unclassed markup picks up role styling — `{ \"h1\": \"display\", \"h2\": \"heading\" }`. The key is used verbatim as a selector, so it is not limited to h1…h6: **map `\"body\"` to your prose role** to bind base page typography to the role rather than hand-writing it. That binding is what makes the role editable — a stylesheet that re-states `font-family`/`line-height` as literals on `body` shadows `--<role>-ff`/`--<role>-lh`, and the live theme editor then appears to do nothing.")
-}), "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping.");
-const AnimEffect = desc(z.strictObject({
-	kf: desc(z.string(), "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."),
-	css: z.optional(desc(VarMap, "Extra literal declarations merged into the effect class as-is.")),
-	vars: z.optional(desc(VarMap, "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."))
-}), "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine.");
-const Animations = desc(z.strictObject({
-	effects: desc(z.optional(z.record(z.string(), AnimEffect)), "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name."),
-	journeys: desc(z.optional(z.strictObject({
-		base: desc(z.optional(z.record(z.string(), VarMap)), "Named journey building blocks: part name → var map."),
-		compose: desc(z.optional(z.array(z.array(z.string()))), "Combinations of base parts, each emitted as a `.<parts>-journey` class.")
-	})), "Multi-part journey classes composed from `base` building blocks.")
-}), "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here.");
-const DesignSystemSchema = z.strictObject({
-	$schema: desc(z.optional(z.string()), "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation."),
-	meta: desc(z.optional(z.strictObject({
-		name: desc(z.optional(z.string()), "Brand/system name. Used as the `name` field and `<h1>` of the `design` format's `DESIGN.md`. Defaults to \"Design System\"."),
-		description: desc(z.optional(z.string()), "One or two sentences on the brand personality and the feeling the UI should evoke — what an agent needs when no token answers the question. Becomes the DESIGN.md `description` field and opens its Overview section; if omitted, a generic description of the system's mechanics is used instead.")
-	})), "Brand identity for agent-facing output. Consumed only by the `design` format (`DESIGN.md`); it emits no CSS and no tokens."),
-	colors: Colors,
-	shadows: desc(z.optional(z.record(z.string(), z.string())), "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour). Each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading."),
-	fonts: desc(z.optional(z.record(z.string(), z.string())), "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`). **Stacks only — vitops does not load webfonts.** A value here is a `font-family` list and nothing more: it emits no `@font-face`, no preload, and no metrics-matched fallback. If a family needs loading, declare it in Astro's `fonts:` config (`astro.config`, or the site config's `fonts` array) and point the token at the family's `cssVariable` — `\"display\": \"var(--font-league-spartan), sans-serif\"`. Installing a `@fontsource*` package and importing its CSS also works but gives up subsetting, preload and `size-adjust`/`ascent-override` fallbacks, so it regresses CLS."),
-	typeScale: desc(z.optional(Scale), "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities."),
-	spaceScale: desc(z.optional(Scale), "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm."),
-	patterns: z.optional(Patterns),
-	typography: z.optional(Typography),
-	animations: z.optional(Animations)
-});
-const ColorsPatch = z.strictObject({
-	palette: z.optional(z.record(z.string(), Ramp)),
-	roles: z.optional(z.record(z.string(), RoleSpecSchema)),
-	utilities: z.optional(z.array(UtilityName))
-});
-const DesignSystemPatchSchema = z.extend(z.partial(DesignSystemSchema), { colors: z.optional(ColorsPatch) });
-/**
-* Stable URL of the published JSON Schema. Resolves once `@getvitops/generator` is on
-* npm (unpkg serves the packaged `schema.json`); `vitops init` stamps this into a
-* scaffolded config's `$schema` so editors light up autocomplete + validation.
+* A palette hue is authored one of two ways:
+*   • `{ seed, anchors? }` — an 11-step numeric scale (50…950) generated in
+*     OKLCH via @getvitops/utils/color. Lightness comes from the shared
+*     `LIGHTNESS_LADDER`; the seed (and any anchors) are reproduced verbatim at
+*     their steps.
+*   • `{ tones }` — a fixed brand kit: authored tones placed verbatim at their
+*     nearest steps + tinted endpoints; nothing else is invented (strict kits).
+*
+* **The grammar.** Every role gets tokens named `--color-<target>-<role>[-<variant>]`,
+* where target ∈ bg | text | icon | border. Putting the target *inside* the name is
+* the point: `--color-bg-danger-muted` and `--color-text-danger-muted` are distinct
+* tokens, so the two axes that used to collide over one `<family>-<role>-<modifier>
+* ` namespace cannot any more. The utility class is the token name minus `--color-`.
+*
+* Variants are ordinal — xx-muted < x-muted < muted < (bare) < bold < x-bold —
+* and the tables are **sparse**: a target only emits the cells that are actually
+* viable. `bold` means "more emphatic than the role's default in the current
+* appearance", not "darker"; the appearance decides polarity.
+*
+* Roles come in two kinds (declared in `colors.roles`):
+*   • `surface` — a page/panel colour. Has a bare `bg-<role>` plus the full
+*     emphasis range and the complete text scale.
+*   • `chromatic` (default) — a signal colour. Backgrounds split into *tints*
+*     (`bg-<role>-x-muted` / `-muted`) and *solids* (`bg-<role>-solid[-bold|-x-bold]`);
+*     there is deliberately **no bare `bg-<role>`**, because "how loud?" is a
+*     question the author has to answer.
+*
+* Dark mode re-points which step each token reads; the solid family and the
+* `text-on-<role>` foreground computed against it stay mode-stable, so a filled
+* button keeps its identity across appearances.
 */
-const SCHEMA_URL = "https://unpkg.com/@getvitops/generator/schema.json";
-/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
-const jsonSchema = {
-	$id: SCHEMA_URL,
-	...z.toJSONSchema(DesignSystemSchema, { target: "draft-2020-12" })
-};
-/** Split a CSS value on top-level commas, ignoring commas nested in `rgba(…)` etc. */
-const splitLayers = (value) => {
-	const out = [];
-	let depth = 0;
-	let start = 0;
-	for (let i = 0; i < value.length; i++) {
-		const c = value[i];
-		if (c === "(") depth++;
-		else if (c === ")") depth--;
-		else if (c === "," && depth === 0) {
-			out.push(value.slice(start, i));
-			start = i + 1;
-		}
-	}
-	out.push(value.slice(start));
-	return out.map((s) => s.trim()).filter(Boolean);
-};
-const LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px|rem|em|ch|ex|vh|vw|vmin|vmax|cm|mm|in|pt|pc|q)?$/i;
+const NUMERIC_STEPS = [
+	"50",
+	"100",
+	"200",
+	"300",
+	"400",
+	"500",
+	"600",
+	"700",
+	"800",
+	"900",
+	"950"
+];
 /**
-* Why a shadow can be *valid CSS* and still render nothing: a `--shadow-<name>`
-* token is consumed both as a `box-shadow` (pattern geometry) and inside
-* `filter: drop-shadow(…)` (the `.drop-shadow-<name>` utilities, the `shadow:`
-* state shortcut). `drop-shadow()` accepts a *single* layer of at most three
-* lengths and no `inset` — a spread radius, a second comma-separated layer or an
-* inset keyword makes the function invalid, which drops the entire `filter`
-* declaration. `box-shadow` accepts all three happily, so the value looks fine
-* everywhere it is authored and only the utility silently goes blank.
+* Lightness of each numeric step. Re-exported from the engine's ladder rather
+* than restated — there used to be three copies of this curve (here, the engine,
+* and the linter) and they were free to drift.
 */
-const dropShadowIssue = (value) => {
-	const layers = splitLayers(value);
-	if (layers.length > 1) return `${layers.length} comma-separated layers`;
-	const layer = layers[0] ?? "";
-	if (/(^|\s)inset(\s|$)/i.test(layer)) return "an `inset` keyword";
-	const lengths = layer.replaceAll(/[\w-]*\([^()]*\)/g, " ").split(/\s+/).filter((t) => LENGTH.test(t));
-	if (lengths.length > 3) return `a spread radius (${lengths.length} lengths)`;
+const STEP_L = Object.fromEntries(NUMERIC_STEPS.map((s) => [s, LIGHTNESS_LADDER[Number(s)]]));
+const isHex = (v) => v.startsWith("#");
+const toOklchStr = (v) => {
+	if (!isHex(v)) return v;
+	const { l, c, h } = hexToOklch(v);
+	return `oklch(${(l * 100).toFixed(2)}% ${c.toFixed(4)} ${h.toFixed(2)})`;
 };
-const RAMP_KEYS = new Set([
-	"seed",
-	"anchors",
-	"tones"
-]);
+const nearestStep = (l) => NUMERIC_STEPS.reduce((best, s) => Math.abs(l - STEP_L[s]) < Math.abs(l - STEP_L[best]) ? s : best);
 /**
-* Replace the bare "Invalid input" a failed union produces with the reason.
+* Claim `step` for `value`, refusing to overwrite a step another colour already
+* took.
 *
-* `Ramp` is `SeededRamp | FixedRamp`, and both branches are closed — so `{ seed,
-* tones }` or a stray key fails *both* and zod reports only that the union didn't
-* match. That message sends you reading the schema rather than looking at the two
-* keys in front of you, and the config that produced it is one whose `tones` were
-* being silently discarded at generate time.
+* Silently dropping one of two colliding tones is the worst outcome: the palette
+* still builds, and the tone the author cared about is simply gone. The record
+* form (`tones: { "600": "#…", "700": "#…" }`) is the escape hatch, so the error
+* points at it.
 */
-const explainRamp = (input) => (issue) => {
-	if (issue.code === "unrecognized_keys") {
-		const keys = issue.keys ?? [];
-		if (keys.length) return {
-			...issue,
-			message: `unknown key${keys.length > 1 ? "s" : ""} ${keys.map((k) => `"${k}"`).join(", ")} — not part of the schema, so ignored at generate time.`
-		};
-	}
-	if (issue.path.length !== 3 || issue.path[0] !== "colors" || issue.path[1] !== "palette") return issue;
-	const hue = input?.colors?.palette?.[String(issue.path[2])];
-	if (hue == null || typeof hue !== "object") return issue;
-	const keys = Object.keys(hue);
-	const unknown = keys.filter((k) => !RAMP_KEYS.has(k));
-	const message = "seed" in hue && "tones" in hue ? "a hue is either seeded (`seed`, with optional `anchors`) or fixed (`tones`) — not both. Drop one: with both present the `tones` are ignored at generate time." : unknown.length ? `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}. A hue takes \`seed\` + optional \`anchors\`, or \`tones\`.` : keys.length === 0 ? "a hue needs `seed` (+ optional `anchors`) or `tones`." : null;
-	return message ? {
-		...issue,
-		message
-	} : issue;
-};
-/**
-* Validate an unknown value against the design-system schema.
-*
-* `warnings` are configurations that parse and generate, but produce output that
-* won't behave as authored — currently only the token-namespace collisions the
-* flat `--<prop>-<name>` grammar makes possible.
-*/
-function validate(input) {
-	const result = z.safeParse(DesignSystemSchema, input);
-	if (!result.success) return {
-		ok: false,
-		data: void 0,
-		errors: result.error.issues.map(explainRamp(input)),
-		warnings: []
+function claim(into, step, value, hueLabel, what) {
+	const taken = into[step];
+	if (taken != null && taken !== value) throw new Error(`palette hue "${hueLabel}": ${what} ${value} and ${taken} both map to step ${step}. Key them explicitly, e.g. { "${step}": "${taken}", "${Number(step) + 100}": "${value}" }.`);
+	into[step] = value;
+}
+function expandSeeded(input, hueLabel) {
+	const anchors = {};
+	for (const [key, value] of Object.entries(input.anchors ?? {})) claim(anchors, NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(value).l), toOklchStr(value), hueLabel, "anchors");
+	const seedStep = nearestStep(hexToOklch(input.seed).l);
+	anchors[seedStep] ??= toOklchStr(input.seed);
+	const scale = generateOklchPalette(anchors);
+	const numeric = {};
+	for (const s of NUMERIC_STEPS) if (scale[s] != null) numeric[s] = oklchStringToHex(scale[s]);
+	return {
+		numeric,
+		deviations: deviationsFor(anchors)
 	};
-	const { palette, roles } = result.data.colors;
-	for (const [role, spec] of Object.entries(roles)) {
-		const hue = roleHue(spec);
-		if (palette[hue] == null) return {
-			ok: false,
-			data: void 0,
-			errors: [{
-				code: "custom",
-				path: [
-					"colors",
-					"roles",
-					role
-				],
-				message: `role "${role}" references unknown palette hue "${hue}"`
-			}],
-			warnings: []
-		};
+}
+function expandTones(input, hueLabel) {
+	const entries = Array.isArray(input.tones) ? input.tones.map((hex) => [null, hex]) : Object.entries(input.tones).map(([k, hex]) => [k, hex]);
+	const placed = {};
+	for (const [key, hex] of entries) claim(placed, key != null && NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(hex).l), hex, hueLabel, "tones");
+	const numeric = {};
+	for (const [step, hex] of Object.entries(placed)) numeric[step] = hex;
+	const ends = tintedEndpoints(hexToOklch(entries[0]?.[1] ?? "#808080").h);
+	numeric["50"] ??= ends.light;
+	numeric["950"] ??= ends.dark;
+	return {
+		numeric,
+		sparse: true,
+		deviations: deviationsFor(placed)
+	};
+}
+/** How far each pinned colour sits from its step's ladder lightness. */
+function deviationsFor(pinned) {
+	const out = {};
+	for (const [step, value] of Object.entries(pinned)) out[step] = (isHex(value) ? hexToOklch(value).l : hexToOklch(oklchStringToHex(value)).l) - STEP_L[step];
+	return out;
+}
+/** Snap to the nearest AVAILABLE numeric step (sparse kits). */
+function snap(numeric, want) {
+	if (numeric[want] != null) return want;
+	return NUMERIC_STEPS.filter((s) => numeric[s] != null).reduce((best, s) => Math.abs(STEP_L[s] - STEP_L[want]) < Math.abs(STEP_L[best] - STEP_L[want]) ? s : best);
+}
+/** Expand every palette hue into its numeric scale. */
+function expandPalette(raw) {
+	const out = {};
+	for (const [name, entry] of Object.entries(raw)) {
+		const e = entry;
+		if (typeof e?.seed === "string") out[name] = expandSeeded(e, name);
+		else if (e?.tones != null) out[name] = expandTones(e, name);
+		else throw new Error(`palette hue "${name}" must have a "seed" or "tones"`);
 	}
+	return out;
+}
+/**
+* Warn about pinned colours that sit noticeably off the ladder. Not an error:
+* the author asked for that exact colour and gets it. But at ~0.03 L the hue
+* starts reading visibly heavier or lighter than its siblings at that step, and
+* that is the class of drift the fixed ladder exists to prevent.
+*/
+const LADDER_TOLERANCE = .03;
+function ladderWarnings(palette) {
 	const warnings = [];
-	const missing = REQUIRED_ROLES.filter((r) => roles[r] == null);
-	if (missing.length) warnings.push(`colors.roles is missing ${missing.map((r) => `"${r}"`).join(", ")} — the framework's own component CSS references ${missing.length === 1 ? "it" : "them"} with no fallback, so those components will render uncoloured. Add any role you like, but keep these defined.`);
-	const radii = Object.keys(result.data.patterns?.radii ?? {});
-	const items = new Set(Object.keys(result.data.patterns?.items ?? {}));
-	for (const name of radii) if (items.has(name)) warnings.push(`patterns.radii.${name} collides with the "${name}" pattern on --br-${name}; the pattern's override hook wins — rename the radius`);
-	for (const [name, value] of Object.entries(result.data.shadows ?? {})) {
-		const issue = dropShadowIssue(value);
-		if (issue) warnings.push(`shadows.${name} carries ${issue}, which \`filter: drop-shadow()\` rejects — \`.drop-shadow-${name}\` will render no shadow at all (the token still works as a \`box-shadow\`). Use one layer of at most three lengths.`);
+	for (const [hue, expanded] of Object.entries(palette)) for (const [step, deviation] of Object.entries(expanded.deviations ?? {})) {
+		if (Math.abs(deviation) <= .03) continue;
+		const dir = deviation > 0 ? "lighter" : "darker";
+		warnings.push(`colors.palette.${hue}: the colour pinned at step ${step} is ${Math.abs(deviation).toFixed(3)} ${dir} than the shared lightness ladder — this hue will read ${dir} than others at ${step}. Legal, but move it to a neighbouring step if that wasn't intended.`);
 	}
-	return {
-		ok: true,
-		data: result.data,
-		errors: [],
-		warnings
-	};
+	return warnings;
 }
-
-//#endregion
-//#region src/config.ts
 /**
-* The top-level configuration schema — the umbrella around a
-* `design-system.json`-compliant `designSystem`.
-*
-* **Three sections, one document.** A config is `{ designSystem, organization,
-* site }`:
-*
-*  - `designSystem` — the token set (named themes + which theme/appearance).
-*  - `organization` — the company: who it is, where it is, how to reach it, what
-*    it sells. Facts that stay true if the site is rebuilt from scratch.
-*  - `site` — this published site: locales, domains, environments, SEO,
-*    analytics, legal, icons, deployment. Facts about *a* presentation of the
-*    organization.
-*
-* The split is not cosmetic. The flat predecessor (`SiteConfig`) held the company
-* and the deployment as peers, so no single noun described it — and the
-* multi-site case was inexpressible. With three sections, several sites can share
-* one `organization` and override only `site`.
-*
-* Authored with `zod/mini` (same instance the design-system schema uses), so the
-* two compose: `DesignSystemSchema` is embedded as `designSystem.themes.<theme>` and the
-* whole thing serialises to one JSON Schema via `z.toJSONSchema`. Everything a
-* generator needs derives from here: the `Config` type (`z.infer`), the
-* published JSON Schema (`configJsonSchema`), and runtime validation (`validateConfig`).
-*
-* Pure: no YAML/env/fs. `resolveConfig` takes an already-parsed object; a
-* thin loader (reading YAML, injecting `SITE_ENV`) lives outside this module.
+* Gamut mapping nudges lightness by a hair, so an exact `<` comparison would
+* report rounding as an inversion. Well below any deviation a person could see.
 */
-const LocalizableSchema = desc(z.union([z.string(), z.record(z.string(), z.string())]), "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`).");
-const ImageRefSchema = z.union([z.string(), z.object({
-	src: z.string(),
-	alt: z.string(),
-	width: z.optional(z.number()),
-	height: z.optional(z.number())
-})]);
-const AttrValue = z.union([
-	z.string(),
-	z.number(),
-	z.boolean()
-]);
-const AttrsSchema = z.optional(z.record(z.string(), AttrValue));
-const IsoDate = z.string().check(z.regex(/^\d{4}-\d{2}-\d{2}$/));
-const Iso4217 = z.string().check(z.regex(/^[A-Z]{3}$/));
-const DayOfWeek = z.enum([
-	"Monday",
-	"Tuesday",
-	"Wednesday",
-	"Thursday",
-	"Friday",
-	"Saturday",
-	"Sunday"
-]);
-const DesignSystemEntry = z.extend(DesignSystemPatchSchema, {
-	displayName: desc(z.optional(LocalizableSchema), "Human-readable theme name (localisable). The label a theme picker would show — nothing reads it yet, because nothing builds more than one theme (see `themes`)."),
-	extends: desc(z.optional(z.string()), "Another `themes` key to inherit from; this entry then only supplies what it overrides.")
-});
+const MONOTONIC_EPSILON = .001;
 /**
-* The design system as a whole: the named themes plus the facts that describe the
-* system rather than any one theme.
+* Ramps whose lightness does not fall monotonically from 50 to 950.
 *
-* `themes` is nested rather than being the block itself because the block used to
-* BE the map — every key was a theme name, so there was nowhere to put
-* system-wide metadata without it colliding with a theme of that name.
+* A ramp built from the ladder alone cannot invert — only pinned colours (a seed,
+* an `anchor`, a `tones` entry) can, because they are the one thing allowed off
+* it. `ladderWarnings` will not catch it: it compares each pinned step against
+* *its own* ladder rung, never against its neighbours, so it reports the wrong
+* defect ("reads darker than others at 600") while the real problem is that 600
+* is darker than 700. And since `LADDER_TOLERANCE` is 0.03 — the same size as the
+* ladder's own 50→100 gap — two anchors can each sit within tolerance and still
+* invert, with no warning at all.
 *
-* Note the two axes here are independent, and deliberately so. `defaultTheme`
-* picks a *theme* (an authored design system); `defaultColorScheme` picks an
-* *appearance* (light/dark), which every theme already has because the flip is
-* derived from one ramp rather than authored. "Theme `elegant`, appearance
-* follows the OS" has to be sayable, and a single union could not express it.
+* This is an error rather than a warning because the rest of the system assumes
+* the order: `snap` picks the nearest step by ladder lightness, the mode-stable
+* solid family hard-codes 600/700/800 as increasingly dark, and both dark tables
+* re-point steps on the same assumption. An inverted ramp therefore runs hover
+* states backwards — the failure the fixed ladder was introduced to eliminate.
 */
-const DesignSystemBlock = desc(z.strictObject({
-	themes: desc(z.record(z.string(), DesignSystemEntry), "Named themes. `default` is the base; others may `extends` another and supply a partial patch. Light/dark is NOT a theme — the functional tokens flip per appearance within each one, so `default` already has both. Only the default theme is built today; multi-theme output and a picker are not wired yet."),
-	defaultTheme: desc(z.optional(z.string()), "Which `themes` entry to use (convention: \"default\"). Validated against the map; selecting a non-default theme is not wired yet."),
-	defaultColorScheme: desc(z.optional(z.enum([
-		"light",
-		"dark",
-		"system"
-	])), "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<wc-color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.")
-}), "The design system: named themes plus the system-wide facts (which theme, which appearance). A bare design system, or a bare theme map, is accepted as shorthand for `{ themes: … }`.");
-const LocaleSchema = z.object({
-	name: desc(z.string(), "Display name of the locale (e.g. \"English\")."),
-	tagline: desc(z.optional(z.string()), "Site tagline in this locale."),
-	basePath: desc(z.optional(z.string()), "URL prefix for this locale (e.g. \"/fr\").")
-});
-const HttpRedirect = z.union([
-	z.literal(301),
-	z.literal(302),
-	z.literal(307),
-	z.literal(308)
-]);
-const DomainAliasSchema = z.object({
-	domain: z.string(),
-	redirectType: HttpRedirect,
-	redirectTo: z.string(),
-	environment: z.optional(z.string())
-});
-const PostalAddressSchema = desc(z.object({
-	streetAddress: z.string(),
-	addressLocality: desc(z.string(), "City."),
-	addressRegion: desc(z.optional(z.string()), "State / province."),
-	postalCode: z.optional(z.string()),
-	addressCountry: desc(z.string(), "Country (ISO 3166-1 alpha-2 preferred).")
-}), "schema.org `PostalAddress` field names, so JSON-LD generation is lossless.");
-const ContactObjectSchema = z.object({
-	name: z.optional(z.string()),
-	email: z.optional(z.email()),
-	phone: z.optional(z.string()),
-	address: z.optional(PostalAddressSchema)
-});
-const ContactConfigSchema = z.union([z.string(), ContactObjectSchema]);
-const GeoSchema = z.object({
-	latitude: z.number().check(z.gte(-90), z.lte(90)),
-	longitude: z.number().check(z.gte(-180), z.lte(180))
-});
-/** schema.org `OpeningHoursSpecification` — per-day open/close (24h `HH:MM`). */
-const OpeningHoursSchema = z.object({
-	dayOfWeek: z.array(DayOfWeek),
-	opens: z.string().check(z.regex(/^\d{2}:\d{2}$/)),
-	closes: z.string().check(z.regex(/^\d{2}:\d{2}$/))
-});
-const LocalBusinessType = z.enum([
-	"LocalBusiness",
-	"Store",
-	"Restaurant",
-	"CafeOrCoffeeShop",
-	"ProfessionalService",
-	"MedicalBusiness",
-	"HealthAndBeautyBusiness",
-	"HomeAndConstructionBusiness",
-	"AutomotiveBusiness",
-	"FinancialService",
-	"LegalService",
-	"RealEstateAgent",
-	"Organization"
-]);
-const LocationSchema = z.object({
-	slug: z.optional(LocalizableSchema),
-	name: LocalizableSchema,
-	email: z.optional(z.email()),
-	phone: z.optional(z.string()),
-	address: z.optional(PostalAddressSchema),
-	geo: z.optional(GeoSchema),
-	hours: z.optional(z.array(OpeningHoursSchema)),
-	type: z.optional(LocalBusinessType),
-	description: z.optional(LocalizableSchema),
-	areaServed: z.optional(z.array(z.string())),
-	priceRange: z.optional(z.string()),
-	paymentAccepted: z.optional(z.array(z.string())),
-	currenciesAccepted: z.optional(Iso4217),
-	knowsLanguage: z.optional(z.array(z.string()))
-});
-const OrganizationSchema = z.object({
-	name: desc(z.optional(LocalizableSchema), "Trading name, as a reader would recognise it (e.g. \"Acme\"). Localisable."),
-	legalName: desc(z.optional(z.string()), "Registered legal name (e.g. \"Acme Widgets Inc.\"). The generated legal documents prefer this over `name` — a policy is a statement by the legal entity."),
-	foundingDate: desc(z.optional(IsoDate), "Date the organization was founded (YYYY-MM-DD)."),
-	logo: desc(z.optional(ImageRefSchema), "Organization logo → JSON-LD `logo`."),
-	email: desc(z.optional(z.email()), "General contact address. Also the last fallback for privacy requests — see `contact`."),
-	phone: desc(z.optional(z.string()), "General contact telephone number."),
-	address: desc(z.optional(PostalAddressSchema), "Registered/mailing address. Its `addressRegion` and `addressCountry` are what the governing-law clause of the generated terms of service defaults to."),
-	taxID: desc(z.optional(z.string()), "Tax identification number."),
-	vatID: desc(z.optional(z.string()), "VAT identification number."),
-	sameAs: desc(z.optional(z.array(z.url())), "Profile URLs → JSON-LD `sameAs` (mirrors `links`).")
-});
-const DnsRecordType = z.enum([
-	"A",
-	"AAAA",
-	"CNAME",
-	"TXT",
-	"MX",
-	"NS",
-	"SRV",
-	"CAA",
-	"PTR",
-	"SOA"
-]);
-const DnsRecordSchema = z.object({
-	type: DnsRecordType,
-	name: z.optional(z.string()),
-	value: z.string(),
-	ttl: z.optional(z.number().check(z.int(), z.positive())),
-	proxied: z.optional(z.boolean())
-});
-const DnsDomainSchema = z.object({
-	provider: z.optional(z.string()),
-	nameservers: z.optional(z.array(z.string())),
-	records: z.optional(z.array(DnsRecordSchema))
-});
+function monotonicityErrors(palette) {
+	const errors = [];
+	for (const [hue, expanded] of Object.entries(palette)) {
+		const numeric = expanded.numeric ?? {};
+		const steps = NUMERIC_STEPS.filter((s) => numeric[s] != null);
+		for (let i = 1; i < steps.length; i++) {
+			const [prev, step] = [steps[i - 1], steps[i]];
+			const lPrev = hexToOklch(numeric[prev]).l;
+			const lStep = hexToOklch(numeric[step]).l;
+			if (lStep < lPrev + MONOTONIC_EPSILON) continue;
+			const pinned = expanded.deviations ?? {};
+			const culprits = [prev, step].filter((s) => pinned[s] != null);
+			const fix = culprits.length ? culprits.map((s) => {
+				const l = hexToOklch(numeric[s]).l;
+				return `${numeric[s]} (pinned at ${s}) sits at L ${l.toFixed(3)}, nearest step ${nearestStep(l)}`;
+			}).join("; ") : `no step here is pinned, so this is a bug in the generator rather than in your config`;
+			errors.push(`colors.palette.${hue}: step ${step} (${numeric[step]}, L ${lStep.toFixed(3)}) is LIGHTER than step ${prev} (${numeric[prev]}, L ${lPrev.toFixed(3)}). A ramp must darken from 50 to 950 — inverted, a hover from \`bg-<role>-solid\` to \`-solid-bold\` gets lighter, and the dark-mode tables re-point steps assuming the order. ${fix}.`);
+		}
+	}
+	return errors;
+}
 /**
-* One domain to onboard into Google Search Console via `vitops search setup`.
+* Surface roles: a bare `bg` (cards, panels, inputs), `bg-muted` for the page
+* behind them, `bg-x-muted` for wells, and `bg-bold`/`-x-bold` for the inverse
+* surface a tooltip sits on. Elevation is expressed by *which* token you reach
+* for — page `bg-muted`, card `bg` — rather than by a raised/sunken pair. That
+* is what lets a future `data-surfaces` axis flatten it without touching markup.
+*/
+const SURFACE_LIGHT = {
+	bg: "50",
+	"bg-muted": "100",
+	"bg-x-muted": "200",
+	"bg-bold": "800",
+	"bg-x-bold": "950",
+	text: "900",
+	"text-bold": "950",
+	"text-muted": "700",
+	"text-x-muted": "500",
+	"text-xx-muted": "400",
+	"text-on-bold": "50",
+	icon: "600",
+	"icon-muted": "500",
+	"border-muted": "200",
+	border: "300",
+	"border-bold": "600"
+};
+const SURFACE_DARK = {
+	bg: "900",
+	"bg-muted": "950",
+	"bg-x-muted": "950",
+	"bg-bold": "200",
+	"bg-x-bold": "50",
+	text: "100",
+	"text-bold": "50",
+	"text-muted": "300",
+	"text-x-muted": "500",
+	"text-xx-muted": "600",
+	"text-on-bold": "950",
+	icon: "400",
+	"icon-muted": "500",
+	"border-muted": "800",
+	border: "700",
+	"border-bold": "400"
+};
+/**
+* Chromatic roles: tints for alert/badge backgrounds, solids for fills. No bare
+* `bg` — see the module docblock. No `text-muted` either: a de-emphasised
+* coloured text could not hold its contrast target off a white surface, so the
+* way to soften coloured text is weight/size, not another colour.
+*/
+const CHROMATIC_LIGHT = {
+	"bg-x-muted": "50",
+	"bg-muted": "100",
+	text: "700",
+	"text-bold": "900",
+	icon: "600",
+	border: "200",
+	"border-bold": "300"
+};
+const CHROMATIC_DARK = {
+	"bg-x-muted": "950",
+	"bg-muted": "900",
+	text: "300",
+	"text-bold": "200",
+	icon: "400",
+	border: "800",
+	"border-bold": "700"
+};
+/**
+* The solid family — mode-stable, so a filled button keeps its identity when the
+* appearance flips. Fixed steps rather than the old scan-and-clamp: with a shared
+* lightness ladder every hue's 600 already sits at the same lightness, so there
+* is nothing left to search for. `text-on-<role>` is computed against `bg-solid`.
+*/
+const SOLID = {
+	"bg-solid": "600",
+	"bg-solid-bold": "700",
+	"bg-solid-x-bold": "800"
+};
+/**
+* Map a token key to its CSS custom property for a given role.
 *
-* The verification token is fetched live from the Site Verification API at run
-* time and written to DNS — it is never stored here. What the config records is
-* the *intent*: which domains to onboard, and who should co-own them.
+* `on` is the one irregular case: the foreground for a filled surface reads
+* `--color-text-on-<role>`, with the role *after* `on`, because it names what it
+* sits on rather than what it is.
+*
+* The utility class name is this minus the `--color-` prefix, which is why the
+* emitter and the linter can both derive their vocabulary from one function.
 */
-const SearchConsoleSetupSchema = z.object({
-	delegatedOwners: desc(z.optional(z.array(z.email())), "Emails added as verification owners on the Site Verification web resource. Automated via the API — additive and idempotent, never removes an existing owner."),
-	fullUserGroup: desc(z.optional(z.email()), "A Google Group to grant Full-User access in Search Console. SURFACED AS A REMINDER only: Search Console exposes no user/permission API, so this step stays manual by design.")
-});
-const RobotsSchema = z.string();
-const EnvironmentSchema = z.object({
-	url: desc(z.url(), "Public origin of this environment."),
-	api: desc(z.optional(z.url()), "API origin, when different from `url`."),
-	analytics: desc(z.optional(z.boolean()), "Whether analytics fire in this environment."),
-	ads: desc(z.optional(z.boolean()), "Whether `site.ads` pixels fire in this environment. Defaults to `analytics`, then true — a preview deployment sending pageviews is survivable, one firing conversion pixels is not, so this can be turned off on its own."),
-	robots: desc(z.optional(RobotsSchema), "Robots policy (e.g. \"noindex,nofollow\" for dev)."),
-	variant: desc(z.optional(z.string()), "Active `abTesting.variants` key for this environment.")
-});
-const AbVariantSchema = z.object({
-	environment: z.string(),
-	description: z.optional(z.string()),
-	overrides: z.optional(z.record(z.string(), z.unknown()))
-});
-const FontProvider = z.enum([
-	"google",
-	"fontsource",
-	"adobe",
-	"bunny",
-	"fontshare",
-	"googleicons",
-	"npm",
-	"local"
-]);
-const FontStyle = z.enum(["normal", "italic"]);
-const FontDisplay = z.enum([
-	"auto",
-	"block",
-	"swap",
-	"fallback",
-	"optional"
-]);
-const FontWeight = z.union([z.number(), z.string()]);
-/** A local-font face (`provider: 'local'`). */
-const FontVariantSchema = z.object({
-	src: z.array(z.string()),
-	weight: z.optional(FontWeight),
-	style: z.optional(FontStyle),
-	unicodeRange: z.optional(z.array(z.string())),
-	display: z.optional(FontDisplay)
-});
-const SiteFontSchema = z.object({
-	name: z.string(),
-	provider: FontProvider,
-	cssVariable: z.string().check(z.regex(/^--/)),
-	weights: z.optional(z.array(FontWeight)),
-	styles: z.optional(z.array(FontStyle)),
-	subsets: z.optional(z.array(z.string())),
-	fallbacks: z.optional(z.array(z.string())),
-	optimizedFallbacks: z.optional(z.boolean()),
-	display: z.optional(FontDisplay),
-	formats: z.optional(z.array(z.string())),
-	unicodeRange: z.optional(z.array(z.string())),
-	variants: z.optional(z.array(FontVariantSchema)),
-	preload: desc(z.optional(z.union([z.boolean(), z.array(z.object({
-		weight: FontWeight,
-		style: z.optional(FontStyle)
-	}))])), "Emit `<Font preload />` for this family (true, or a list of weight/style faces).")
-});
-const PresentSchema = z.optional(z.record(z.string(), z.unknown()));
-const NavItemSchema = z.object({
-	label: z.optional(LocalizableSchema),
-	image: z.optional(ImageRefSchema),
-	href: z.optional(z.string()),
-	icon: z.optional(z.string()),
-	attrs: AttrsSchema,
-	itemAttrs: AttrsSchema,
-	submenu: z.optional(z.object({
-		present: PresentSchema,
-		get items() {
-			return z.optional(z.array(NavItemSchema));
+function tokenVar(role, key) {
+	const dash = key.indexOf("-");
+	const target = dash === -1 ? key : key.slice(0, dash);
+	const variant = dash === -1 ? "" : key.slice(dash + 1);
+	if (variant === "on") return `--color-${target}-on-${role}`;
+	if (variant.startsWith("on-")) return `--color-${target}-on-${role}-${variant.slice(3)}`;
+	return variant ? `--color-${target}-${role}-${variant}` : `--color-${target}-${role}`;
+}
+/** The class name a token key produces for a role (`bg-danger-solid`, …). */
+const tokenClass = (role, key) => tokenVar(role, key).slice(8);
+/** Resolve the token set for one role over its hue. */
+function functionalRole(role, hueName, hue, kind = "chromatic") {
+	const numeric = hue.numeric;
+	const v = (n) => `var(--color-${hueName}-${snap(numeric, n)})`;
+	const hex = (n) => numeric[snap(numeric, n)];
+	const map = (table) => {
+		const out = {};
+		for (const [token, step] of Object.entries(table)) out[token] = v(step);
+		return out;
+	};
+	const solids = map(SOLID);
+	const onSolid = pickOn(hex(SOLID["bg-solid"]));
+	return {
+		role,
+		hue: hueName,
+		kind,
+		light: {
+			...map(kind === "surface" ? SURFACE_LIGHT : CHROMATIC_LIGHT),
+			...solids,
+			"text-on": onSolid
+		},
+		dark: {
+			...map(kind === "surface" ? SURFACE_DARK : CHROMATIC_DARK),
+			...solids,
+			"text-on": onSolid
 		}
-	}))
-});
-const FormFieldType = z.enum([
-	"text",
-	"email",
-	"tel",
-	"url",
-	"number",
-	"password",
-	"textarea",
-	"select",
-	"checkbox",
-	"radio",
-	"date",
-	"file",
-	"hidden"
+	};
+}
+/**
+* APCA targets. `TEXT` is the body-text bar; `SECONDARY` covers text on a
+* non-primary surface and de-emphasised text. `NON_TEXT` is the icon/boundary
+* tier — the APCA analogue of WCAG's 3:1, where a glyph may run more vivid than
+* text because shape carries meaning alongside contrast.
+*/
+const CONTRAST = {
+	TEXT: 75,
+	SECONDARY: 60,
+	NON_TEXT: 45
+};
+/**
+* Text tokens deliberately exempt from the contract. Placeholders and disabled
+* text are required to look unavailable; holding them to the body-text bar would
+* defeat the affordance. Nothing else may be exempt.
+*/
+const EXEMPT_TEXT = new Set(["text-x-muted", "text-xx-muted"]);
+/**
+* Verify a role's contrast targets. Returns human-readable failures.
+*
+* Chromatic roles are checked against the surface planes they actually sit on
+* (`surfaceBg`) as well as their own tints — coloured text almost never appears
+* over its own solid, it appears over the page. Checking only within the role
+* would have missed the pairing that matters most.
+*/
+function checkContrast(fr, numericOf, surfaceBg) {
+	const failures = [];
+	const resolve = (val) => {
+		const m = /^var\(--color-([a-z0-9-]+)-(\d+)\)$/.exec(val);
+		if (!m) return val;
+		return numericOf(m[1])[m[2]] ?? val;
+	};
+	const fail = (appearance, msg) => failures.push(`${fr.role}/${appearance}: ${msg}`);
+	for (const [appearance, tokens] of [["light", fr.light], ["dark", fr.dark]]) {
+		const ownBg = Object.keys(tokens).filter((k) => k === "bg" || k.startsWith("bg-")).filter((k) => !k.startsWith("bg-solid")).filter((k) => !k.startsWith("bg-bold") && !k.startsWith("bg-x-bold"));
+		const planes = fr.kind === "surface" ? ownBg.map((k) => [k, resolve(tokens[k])]) : [...(surfaceBg?.[appearance] ?? []).map((h, i) => [`surface#${i}`, h]), ...ownBg.map((k) => [k, resolve(tokens[k])])];
+		for (const [planeName, bg] of planes) {
+			const textMin = planeName === "bg" ? CONTRAST.TEXT : CONTRAST.SECONDARY;
+			for (const key of [
+				"text",
+				"text-bold",
+				"text-muted"
+			]) {
+				if (tokens[key] == null || EXEMPT_TEXT.has(key)) continue;
+				const min = key === "text-muted" ? CONTRAST.SECONDARY : textMin;
+				const lc = contrastLc(resolve(tokens[key]), bg);
+				if (lc < min) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${min} on ${planeName} ${bg}`);
+			}
+			const nonText = fr.kind === "surface" ? ["icon", "border-bold"] : ["icon"];
+			for (const key of nonText) {
+				if (tokens[key] == null) continue;
+				const lc = contrastLc(resolve(tokens[key]), bg);
+				if (lc < CONTRAST.NON_TEXT) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${CONTRAST.NON_TEXT} on ${planeName} ${bg}`);
+			}
+		}
+		const solid = resolve(tokens["bg-solid"]);
+		const onLc = contrastLc(tokens["text-on"], solid);
+		if (onLc < CONTRAST.SECONDARY) fail(appearance, `text-on Lc ${onLc.toFixed(1)} < ${CONTRAST.SECONDARY} on bg-solid`);
+		if (tokens["bg-bold"] != null && tokens["text-on-bold"] != null) {
+			const lc = contrastLc(resolve(tokens["text-on-bold"]), resolve(tokens["bg-bold"]));
+			if (lc < CONTRAST.TEXT) fail(appearance, `text-on-bold Lc ${lc.toFixed(1)} < ${CONTRAST.TEXT} on bg-bold`);
+		}
+	}
+	return failures;
+}
+
+//#endregion
+//#region src/token-refs.ts
+/**
+* Cross-layer check: does every `var(--…)` a config authors resolve to a token
+* the generator actually emits?
+*
+* A `patterns` value is a string the schema deliberately does not interpret
+* (see `CssDecls` in `schema.ts`), so a reference to a token that does not exist
+* parses, generates, minifies and ships. The declaration then resolves to
+* `inherit`/`unset` in the browser and nothing anywhere says so. Downstream this
+* shipped a `.cta` whose `color` fell back to `inherit` on a brand fill —
+* unreadable text on every filled button — and two of the four dead references
+* in that config had been dead for several versions.
+*
+* **The check is anchored to namespaces the generator owns**, exactly as
+* `vitops lint` is anchored to classes derived from the consumer's own config.
+* A pattern may legitimately reference a framework token defined in
+* `@getvitops/core`'s hand-written CSS (`--icon-size`, `--animation-duration`,
+* a consumer's own hook), and `validate()` is a pure function that must not read
+* the filesystem to find out. Enumerating "every valid token" would therefore
+* turn every such reference into a false positive. Enumerating only what the
+* generator emits — the colour layer, shadows, z-tiers — is a set it can compute
+* from the config alone, and it is where the dangling references actually occur.
+*
+* `FRAMEWORK_OWNED` is the one leak in that reasoning: a token that sits inside
+* an owned prefix but is defined by core's CSS instead. `token-refs.test.ts`
+* greps the shipped partials and fails if a new one appears, so the allowlist
+* cannot silently go stale.
+*
+* A reference carrying a fallback (`var(--x, 0.25rem)`) is **never** flagged: the
+* fallback is the author stating what happens when the token is absent, which is
+* the whole difference between a considered default and an accident.
+*/
+/**
+* Prefixes whose entire contents the generator emits. A `var()` inside one of
+* these either resolves to something the colour/shadow/z layer defines, or it
+* resolves to nothing — there is no third possibility, which is what makes an
+* error (rather than a warning) the right severity.
+*/
+const OWNED_PREFIXES = [
+	"--color-",
+	"--shadow-",
+	"--z-tier-"
+];
+/** Singleton tokens the colour layer emits, checked by exact name. */
+const OWNED_EXACT = new Set(["--surface-glass", "--overlay"]);
+/**
+* Tokens inside an owned prefix that `@getvitops/core`'s hand-written CSS
+* defines rather than the generator. Drift-guarded by `token-refs.test.ts`.
+*/
+const FRAMEWORK_OWNED = new Set(["--color-swatch-size"]);
+/**
+* Roles whose name says "this is a surface" while the bare-string shorthand
+* says `chromatic`. The two kinds emit *different token sets* — a chromatic role
+* has no bare `bg`, so `--color-bg-surface` and every `.bg-surface` utility
+* simply cease to exist, taking 36 references in the framework's own CSS with
+* them. Naming one of these and getting the chromatic set is almost always a
+* mistake, and it is the exact one a downstream config made.
+*/
+const SURFACE_SHAPED = new Set([
+	"surface",
+	"neutral",
+	"background",
+	"page",
+	"canvas"
 ]);
-const FormFieldSchema = z.object({
-	name: z.string(),
-	type: FormFieldType,
-	label: z.optional(LocalizableSchema),
-	required: z.optional(z.boolean()),
-	validation: z.optional(z.string()),
-	options: z.optional(z.union([z.string(), z.array(z.object({
-		label: z.string(),
-		value: z.string()
-	}))])),
-	attrs: AttrsSchema
-});
-const ContentNodeSchema = z.object({
-	tag: z.string(),
-	attrs: AttrsSchema,
-	text: z.optional(z.string()),
-	get children() {
-		return z.optional(z.array(ContentNodeSchema));
+/**
+* The 1.0 colour-grammar rename, as data.
+*
+* Old suffix (on `--<role>-<suffix>`) → new token key (fed through `tokenVar`).
+* Transcribed from the migration table in the 1.0 changelog; `surface` rotates
+* separately below because its rename is value-preserving rather than
+* mechanical. `--color-<role>-<variant>` "stops" are deliberately absent — the
+* changelog says to judge those by use, and they already land in the owned
+* `--color-` namespace, so the generic check catches them with a near-miss hint.
+*/
+const MOVED_SUFFIXES = {
+	bg: "bg-x-muted",
+	"bg-muted": "bg-muted",
+	solid: "bg-solid",
+	"solid-bold": "bg-solid-bold",
+	"solid-x-bold": "bg-solid-x-bold",
+	"on-solid": "text-on",
+	"on-solid-bold": "text-on-bold",
+	text: "text",
+	"text-muted": "text-muted",
+	"text-x-muted": "text-x-muted",
+	"text-xx-muted": "text-xx-muted",
+	"text-bold": "text-bold",
+	icon: "icon",
+	"icon-muted": "icon-muted",
+	border: "border",
+	"border-muted": "border-muted",
+	"border-bold": "border-bold"
+};
+/**
+* `surface`'s background names rotate rather than map: what was `--surface-bg`
+* (the page) is now `--color-bg-surface-muted`, and what was `--surface-bg-bold`
+* (raised) is now `--color-bg-surface`. Applying the chromatic rule to it would
+* silently move the page background two rungs.
+*/
+const SURFACE_BG_ROTATION = {
+	bg: "bg-muted",
+	"bg-bold": "bg",
+	"bg-muted": "bg-x-muted"
+};
+/**
+* Old-grammar token name → its 1.0 replacement, for the roles this config
+* declares.
+*
+* Built per-config rather than as a static table because the old names embed
+* the *consumer's own* role names — there is no fixed list to hard-code, which
+* is why nothing detected these before.
+*/
+function movedTokens(roles) {
+	const out = {};
+	for (const [role, spec] of Object.entries(roles)) {
+		const rotate = roleKind(spec) === "surface";
+		for (const [old, key] of Object.entries(MOVED_SUFFIXES)) out[`--${role}-${old}`] = tokenVar(role, rotate && SURFACE_BG_ROTATION[old] || key);
+		if (rotate) for (const [old, key] of Object.entries(SURFACE_BG_ROTATION)) out[`--${role}-${old}`] = tokenVar(role, key);
+	}
+	return out;
+}
+/**
+* Extract every `var(--name[, fallback])` from a CSS value.
+*
+* Hand-rolled rather than a regex because the fallback has to be detected at the
+* reference's *own* paren depth: in `var(--a, var(--b))` the outer reference has
+* a fallback and the inner one does not, and a regex that stops at the first `)`
+* gets both wrong.
+*/
+function extractVarRefs(value, path) {
+	const out = [];
+	for (let i = value.indexOf("var("); i !== -1; i = value.indexOf("var(", i + 1)) {
+		let j = i + 4;
+		while (j < value.length && /\s/.test(value[j])) j++;
+		const start = j;
+		while (j < value.length && /[\w-]/.test(value[j])) j++;
+		const name = value.slice(start, j);
+		if (!name.startsWith("--")) continue;
+		let depth = 0;
+		let fallback = false;
+		for (let k = j; k < value.length; k++) {
+			const c = value[k];
+			if (c === "(") depth++;
+			else if (c === ")") {
+				if (depth === 0) break;
+				depth--;
+			} else if (c === "," && depth === 0) fallback = true;
+		}
+		out.push({
+			path,
+			name,
+			fallback
+		});
+	}
+	return out;
+}
+/** Recursively collect refs from a value that may be a string or a nested map. */
+const walkValue = (value, path, out) => {
+	if (typeof value === "string") out.push(...extractVarRefs(value, path));
+	else if (value != null && typeof value === "object" && !Array.isArray(value)) for (const [k, v] of Object.entries(value)) walkValue(v, `${path}.${k}`, out);
+};
+/**
+* Every authored declaration that can hold a `var()`.
+*
+* `patterns` is where the reported failures were, but `typography.roles.*.color`
+* and a `shadows` entry are authored the same way and fail the same way, so the
+* same walk covers them. `patterns.items.*.states` is walked recursively — a
+* state's `css` shortcut is a nested declaration map.
+*/
+function collectVarRefs(ds) {
+	const out = [];
+	const p = ds.patterns ?? {};
+	walkValue(p["defaults"], "patterns.defaults", out);
+	walkValue(p["radii"], "patterns.radii", out);
+	walkValue(p["groups"], "patterns.groups", out);
+	for (const [name, item] of Object.entries(p["items"] ?? {})) {
+		const it = item ?? {};
+		walkValue(it["base"], `patterns.items.${name}.base`, out);
+		walkValue(it["overrides"], `patterns.items.${name}.overrides`, out);
+		walkValue(it["states"], `patterns.items.${name}.states`, out);
+	}
+	walkValue(ds.typography?.["roles"], "typography.roles", out);
+	walkValue(ds.shadows, "shadows", out);
+	return out;
+}
+/**
+* The custom properties the generator emits, as names.
+*
+* Derived from the same functions the emitter uses — `expandPalette` for the
+* ramps and `functionalRole` + `tokenVar` for the role set — so the check cannot
+* disagree with the output about what exists. Both appearances are unioned: a
+* token that only appears in the dark block is still defined.
+*/
+function emittedTokens(ds) {
+	const defined = /* @__PURE__ */ new Set();
+	const palette = expandPalette(ds.colors.palette);
+	for (const [hueName, hue] of Object.entries(palette)) for (const n of Object.keys(hue.numeric)) defined.add(`--color-${hueName}-${n}`);
+	let hasSurface = false;
+	for (const [role, spec] of Object.entries(ds.colors.roles)) {
+		const hueName = roleHue(spec);
+		const hue = palette[hueName];
+		if (hue == null) continue;
+		const kind = roleKind(spec);
+		if (role === "surface" && kind === "surface") hasSurface = true;
+		const fr = functionalRole(role, hueName, hue, kind);
+		for (const key of new Set([...Object.keys(fr.light), ...Object.keys(fr.dark)])) defined.add(tokenVar(role, key));
 	}
-});
-const TemplateSchema = z.union([
-	z.object({
-		type: z.literal("nav"),
-		tags: z.optional(z.array(z.string())),
-		present: PresentSchema,
-		items: z.optional(z.array(NavItemSchema))
-	}),
-	z.object({
-		type: z.literal("form"),
-		tags: z.optional(z.array(z.string())),
-		present: PresentSchema,
-		action: z.optional(z.string()),
-		method: z.optional(z.enum(["get", "post"])),
-		fields: z.optional(z.array(FormFieldSchema)),
-		submit: z.optional(z.record(z.string(), AttrValue)),
-		honeypot: z.optional(z.boolean())
-	}),
-	z.object({
-		type: z.literal("nodes"),
-		tags: z.optional(z.array(z.string())),
-		nodes: z.optional(z.array(ContentNodeSchema))
-	})
-]);
-const GalleryImageSchema = z.object({
-	src: z.string(),
-	alt: LocalizableSchema,
-	caption: z.optional(LocalizableSchema)
-});
-const GallerySchema = z.object({
-	title: z.optional(LocalizableSchema),
-	tags: z.optional(z.array(z.string())),
-	images: z.array(GalleryImageSchema)
-});
-const TestimonialItemSchema = z.object({
-	quote: LocalizableSchema,
-	name: z.string(),
-	role: z.optional(z.string()),
-	rating: z.optional(z.number().check(z.gte(0), z.lte(5))),
-	date: z.optional(IsoDate)
-});
-const TestimonialGroupSchema = z.object({
-	title: z.optional(LocalizableSchema),
-	items: z.array(TestimonialItemSchema)
-});
-const OfferSchema = z.object({
-	name: z.optional(LocalizableSchema),
-	price: z.optional(z.union([z.string(), z.number()])),
-	priceCurrency: z.optional(Iso4217),
-	availability: z.optional(z.string()),
-	url: z.optional(z.url()),
-	validFrom: z.optional(IsoDate),
-	priceValidUntil: z.optional(IsoDate)
-});
-const ServiceSchema = z.object({
-	name: LocalizableSchema,
-	description: z.optional(LocalizableSchema),
-	slug: z.optional(LocalizableSchema),
-	offers: z.optional(z.array(OfferSchema))
-});
-const OpenGraphSchema = z.object({
-	type: z.optional(z.string()),
-	siteName: z.optional(z.string()),
-	title: z.optional(LocalizableSchema),
-	description: z.optional(LocalizableSchema),
-	image: z.optional(ImageRefSchema),
-	locale: z.optional(z.string())
-});
-const TwitterSchema = z.object({
-	card: z.optional(z.enum([
-		"summary",
-		"summary_large_image",
-		"app",
-		"player"
-	])),
-	site: z.optional(z.string()),
-	creator: z.optional(z.string()),
-	title: z.optional(LocalizableSchema),
-	description: z.optional(LocalizableSchema),
-	image: z.optional(ImageRefSchema)
-});
+	if (Object.keys(ds.colors.roles).length) defined.add("--color-border-focus");
+	if (hasSurface) {
+		defined.add("--surface-glass");
+		defined.add("--overlay");
+	}
+	for (const name of Object.keys(ds.shadows ?? {})) defined.add(`--shadow-${name}`);
+	for (const name of Object.keys(ds.patterns?.z ?? {})) defined.add(`--z-tier-${name}`);
+	return defined;
+}
+/** Whether this check has an opinion about a given custom property. */
+const isOwned = (name) => !FRAMEWORK_OWNED.has(name) && (OWNED_EXACT.has(name) || OWNED_PREFIXES.some((p) => name.startsWith(p)));
 /**
-* What `vitops search notify` needs to tell search engines a deploy happened.
+* Suggest a near-miss from the emitted set, so the message names the fix rather
+* than only the failure. Cheap edit-distance-ish heuristic: same prefix, or a
+* one-segment difference.
+*/
+const nearest = (name, defined) => {
+	const segs = name.split("-").filter(Boolean);
+	let best;
+	let bestScore = 0;
+	for (const cand of defined) {
+		const cs = cand.split("-").filter(Boolean);
+		const score = cs.filter((s) => segs.includes(s)).length - Math.abs(cs.length - segs.length) * .5;
+		if (score > bestScore) {
+			bestScore = score;
+			best = cand;
+		}
+	}
+	return bestScore >= Math.max(2, segs.length - 1) ? best : void 0;
+};
+/**
+* Check a parsed design system's authored `var()` references, plus the
+* role-kind heuristic that produces most of them.
 *
-* Scoped by what search engines actually accept, which is narrower than it looks:
-* Google exposes **no** "request indexing" API (the Search Console button is not in
-* its API, and URL Inspection is read-only), and it removed the sitemap ping
-* endpoint in 2023. So the sanctioned set is: an accurate sitemap, a Search Console
-* sitemap resubmit, an IndexNow ping — which Google does *not* honour but Bing,
-* Yandex, Naver, Seznam and Yep do — and a read-only inspection pass to find out
-* what Google actually did.
+* Returns messages rather than issues so `validate()` owns the `$ZodIssue`
+* shaping, and so the same check can be reported by `generate()` without
+* inventing a second vocabulary.
+*/
+function tokenRefIssues(ds) {
+	const errors = [];
+	const warnings = [];
+	for (const [role, spec] of Object.entries(ds.colors.roles)) if (SURFACE_SHAPED.has(role) && roleKind(spec) === "chromatic") warnings.push(`colors.roles.${role} is declared chromatic (a bare hue string is shorthand for \`kind: "chromatic"\`), but the name reads as a surface. A chromatic role emits no bare \`--color-bg-${role}\` and no \`.bg-${role}\` utility` + (REQUIRED_ROLES.includes(role) ? `, and the framework's own component CSS references those with no fallback` : "") + `. Write \`"${role}": { "hue": "${roleHue(spec)}", "kind": "surface" }\` if you meant a surface.`);
+	let defined;
+	try {
+		defined = emittedTokens(ds);
+	} catch {
+		return {
+			errors,
+			warnings
+		};
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const renames = movedTokens(ds.colors.roles);
+	const moved = /* @__PURE__ */ new Map();
+	const excused = /* @__PURE__ */ new Set();
+	for (const role of REQUIRED_ROLES) if (ds.colors.roles[role] == null) for (const key of ROLE_TOKEN_KEYS) excused.add(tokenVar(role, key));
+	for (const ref of collectVarRefs(ds)) {
+		if (ref.fallback || defined.has(ref.name) || excused.has(ref.name)) continue;
+		const moveTo = renames[ref.name];
+		if (moveTo != null) {
+			moved.set(ref.name, moveTo);
+			continue;
+		}
+		if (!isOwned(ref.name)) continue;
+		const key = `${ref.name} ${ref.path}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const hint = nearest(ref.name, defined);
+		errors.push({
+			path: ref.path.split("."),
+			message: `${ref.path} references \`var(${ref.name})\`, which this config emits no token for — the declaration will resolve to nothing at runtime.` + (hint ? ` Did you mean \`var(${hint})\`?` : "") + ` (Give it a fallback — \`var(${ref.name}, <value>)\` — if the absence is intentional.)`
+		});
+	}
+	if (moved.size) errors.unshift({
+		path: ["colors"],
+		message: `${moved.size} token reference${moved.size === 1 ? " uses" : "s use"} the pre-1.0 colour grammar. The role moved into the middle of the property name, after its target (\`--color-<target>-<role>[-<variant>]\`):\n` + [...moved].map(([old, next]) => `  ${old} → ${next}`).join("\n") + "\n\nApply these simultaneously, not one at a time — several renames are cyclic (a surface role's backgrounds rotate), so sequential replacement compounds them. `vitops lint <src> --fix` does this for markup and CSS."
+	});
+	return {
+		errors,
+		warnings
+	};
+}
+
+//#endregion
+//#region src/schema.ts
+/**
+* Canonical `design-system.json` schema — the single source of truth.
 *
-* Facts only, the same rule the legal block follows: this records what the site has
-* (a key, a property, which pages matter), never what to say about it.
+* Authored with `zod/mini` (tree-shakeable Zod v4). Everything else derives from it:
+*   • the `DesignSystem` TS type (`z.infer`), used throughout the generator,
+*   • the published JSON Schema (`toJSONSchema`), emitted to `schema.json` for `$schema` refs,
+*   • runtime validation (`validate`) for the CLI and to gate `generate`,
+*   • the generated `authoring.md` reference doc (walks `jsonSchema`'s descriptions).
 */
-const IndexNowSchema = z.object({
-	key: desc(z.string().check(z.regex(/^[a-zA-Z0-9-]{8,128}$/)), "IndexNow key (8–128 chars, hex is conventional). NOT a secret — it is served publicly at `keyLocation` so the engine can verify you own the host. Generate one with `vitops search notify --new-key`."),
-	keyLocation: desc(z.optional(z.url()), "Absolute URL of the key file. Defaults to `<canonical>/<key>.txt`; set it only when the file lives elsewhere."),
-	endpoint: desc(z.optional(z.url()), "IndexNow endpoint (default `https://api.indexnow.org/indexnow`). Any participating engine shares submissions with the rest, so one is normally enough.")
+/**
+* Attach a JSON-Schema `description`. zod/mini has no `.describe()` method; the
+* mini-API equivalent is `.check(z.describe(…))`, and `.check()` clones — so a
+* shared sub-schema (`Scale`, `CssDecls`, …) can carry a different description
+* per use-site without mutating the original.
+*/
+const desc = (schema, text) => schema.check(z.describe(text));
+const CssDecls = desc(z.record(z.string(), z.string()), "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them.");
+const Scalar = z.union([z.string(), z.number()]);
+const VarMap = z.record(z.string(), Scalar);
+const SeededRamp = desc(z.strictObject({
+	seed: desc(z.string(), "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."),
+	anchors: z.optional(desc(z.record(z.string(), z.string()), "Step → colour overrides (hex or oklch()) pinned VERBATIM at those steps. Every other step takes its lightness from the shared ladder, with chroma and hue interpolated between the anchors — so an anchor is reproduced exactly and is the only step allowed off the ladder. An explicit anchor overrides the seed at that step; two anchors that resolve to the same step are an error."))
+}), "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps).");
+const FixedRamp = desc(z.strictObject({ tones: desc(z.union([z.array(z.string()), z.record(z.string(), z.string())]), "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map.") }), "Fixed hue: authored brand tones used verbatim; no generation.");
+const Ramp = desc(z.union([SeededRamp, FixedRamp]), "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim.");
+/**
+* A role points at a hue, and optionally declares its kind. The bare-string form
+* is the shorthand for a chromatic role — signal colours are the common case,
+* and the two or three surfaces are worth naming explicitly.
+*/
+const RoleSpecSchema = z.union([desc(z.string(), "A palette hue name. Shorthand for `{ hue, kind: \"chromatic\" }`."), z.strictObject({
+	hue: desc(z.string(), "The palette hue this role resolves to."),
+	kind: z.optional(desc(z.enum(["surface", "chromatic"]), "`surface` — a page/panel colour: gets a bare `bg-<role>` plus the full emphasis range and text scale. `chromatic` (default) — a signal colour: tints and solids only, no bare `bg-<role>`."))
+})]);
+const UtilityName = z.enum([
+	"bg",
+	"text",
+	"icon",
+	"border",
+	"outline",
+	"fill",
+	"stroke"
+]);
+const Colors = desc(z.strictObject({
+	palette: desc(z.record(z.string(), Ramp), "Palette hues by name. Each becomes an 11-step numeric OKLCH scale (`--color-<hue>-50…950`). Every ramp shares one fixed lightness ladder, so a step means the same lightness in every hue; only chroma and hue vary. Beyond the outermost authored colour the chroma decays towards a small endpoint value (0.008 light / 0.015 dark) so the near-white and near-black ends keep a whisper of the hue — but that is a **ceiling**, not a target, so a low-chroma seed stays low and **a chroma-0 seed gives a true neutral** rather than a tinted one. The ladder is also enforced: if pinned colours leave a ramp non-monotonic (some step darker than the one below it), the build fails rather than shipping a scale whose hover states run backwards."),
+	roles: desc(z.record(z.string(), RoleSpecSchema), `Maps semantic role names onto palette hues. Role names are ARBITRARY — add a key and the generator emits that role's token set (\`--color-<target>-<role>[-<variant>]\` for target bg/text/icon/border), its dark-mode flip and its utility classes.\n\nA value is either a hue name (\`"danger": "rust"\`) or \`{ "hue": …, "kind": "surface" | "chromatic" }\`. **The kind decides the shape of the token set.** \`chromatic\` (the default, and what the bare-string form means) is a signal colour: its backgrounds split into tints (\`bg-<role>-x-muted\`/\`-muted\`) and solids (\`bg-<role>-solid[-bold|-x-bold]\`), with deliberately **no bare \`bg-<role>\`** — "how loud?" is a question the author answers. \`surface\` is a page/panel colour: it has a bare \`bg-<role>\` plus the full emphasis range and text scale.\n\nDark mode flips automatically; there is no per-appearance scheme grammar. The solid family and its computed \`text-on-<role>\` foreground stay mode-stable so a filled button keeps its identity. Six roles are a required core, because the shipped framework CSS references them with no fallback: ${REQUIRED_ROLES.join(", ")}. Conventional additions are ui-secondary/accent, brand-secondary, info and success.`),
+	utilities: z.optional(desc(z.array(UtilityName), "Which colour utility-class families to emit (`bg-*`, `text-*`, `icon-*`, `border-*`, `outline-*`, `fill-*`, `stroke-*`). Defaults to bg, text, icon, border. `icon` is a separate non-text tier (a glyph may run more vivid than text); `outline`/`fill`/`stroke` have no tokens of their own and alias the border and icon tiers."))
+}), "The colour system (the only required section): `palette` hues become generated OKLCH scales; `roles` map semantic roles onto those hues, from which all role tokens and dark mode derive.");
+const Scale = z.strictObject({
+	base: desc(z.string(), "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."),
+	ratio: desc(z.number(), "Modular ratio between adjacent steps at large viewports."),
+	steps: desc(z.optional(z.number()), "Token count when `names` is absent (steps are then named 1..steps)."),
+	names: desc(z.optional(z.array(z.string())), "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix."),
+	baseStep: desc(z.optional(z.number()), "1-based index of the step whose value is `base`."),
+	baseline: desc(z.optional(z.string()), "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`)."),
+	fluid: desc(z.optional(z.strictObject({
+		minVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling bottoms out."),
+		maxVw: desc(z.string(), "Viewport width (CSS length) where fluid scaling tops out."),
+		minRatio: desc(z.number(), "Modular ratio at/below `minVw` (usually < `ratio`).")
+	})), "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.")
 });
-const SearchConsoleSchema = z.object({
-	siteUrl: desc(z.string(), "The property exactly as Search Console identifies it — `sc-domain:acme.ca` for a domain property, or the URL-prefix form `https://acme.ca/`. A mismatch here is a 403, not a \"not found\"."),
-	resubmitSitemap: desc(z.optional(z.boolean()), "Re-submit the sitemap through the Search Console API on each notify (default true when `searchConsole` is set). This is the automated equivalent of the manual resubmit in the UI.")
+const Pattern = desc(z.strictObject({
+	group: desc(z.optional(z.string()), "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`."),
+	overrides: z.optional(desc(CssDecls, "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values.")),
+	element: desc(z.optional(z.string()), "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class)."),
+	class: desc(z.optional(z.string()), "Class name to emit (defaults to the pattern's key when no `element` is set). Combined with `element`, the pattern emits one zero-specificity `:where(<element>, .<class>)` rule so the class works on any tag and any explicit class overrides it."),
+	fill: desc(z.optional(z.boolean()), "Whether this pattern is colour-filled (states/roles drive `background-color` + `on-solid` text) or text-coloured (they drive `color`). Defaults to true when `base` declares a background."),
+	default_role: desc(z.optional(z.string()), "Semantic colour role applied to the bare/default variant."),
+	base: z.optional(desc(CssDecls, "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable.")),
+	states: desc(z.optional(z.record(z.string(), z.record(z.string(), z.unknown()))), "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify the fill or text by n rungs — `bg-<role>-solid` → `-solid-bold`, `text-<role>` → `-bold`), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`."),
+	roles: desc(z.optional(z.array(z.string())), "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).")
+}), "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade.");
+const Patterns = desc(z.strictObject({
+	defaults: z.optional(desc(CssDecls, "Cascade-wide fallback tokens, emitted as `--<prop>-default`.")),
+	radii: z.optional(desc(CssDecls, "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases).")),
+	groups: desc(z.optional(z.record(z.string(), CssDecls)), "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key."),
+	z: desc(z.optional(z.record(z.string(), z.number())), "Z-index tiers → `--z-tier-<name>`."),
+	items: desc(z.optional(z.record(z.string(), Pattern)), "The component patterns to emit, keyed by name.")
+}), "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives.");
+const TypographyRole = desc(z.record(z.string(), Scalar), "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. Note the last four are spelled with their full CSS property names — `transform` and `decoration` are NOT accepted. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped `transform: uppercase` is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels.");
+const Typography = desc(z.strictObject({
+	families: desc(z.optional(z.record(z.string(), z.string())), "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\")."),
+	roles: desc(z.optional(z.record(z.string(), TypographyRole)), "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class."),
+	headings: desc(z.optional(z.record(z.string(), z.string())), "Maps bare elements to type roles so unclassed markup picks up role styling — `{ \"h1\": \"display\", \"h2\": \"heading\" }`. The key is used verbatim as a selector, so it is not limited to h1…h6: **map `\"body\"` to your prose role** to bind base page typography to the role rather than hand-writing it. That binding is what makes the role editable — a stylesheet that re-states `font-family`/`line-height` as literals on `body` shadows `--<role>-ff`/`--<role>-lh`, and the live theme editor then appears to do nothing.")
+}), "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the bare-element → role mapping.");
+const AnimEffect = desc(z.strictObject({
+	kf: desc(z.string(), "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."),
+	css: z.optional(desc(VarMap, "Extra literal declarations merged into the effect class as-is.")),
+	vars: z.optional(desc(VarMap, "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."))
+}), "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine.");
+const Animations = desc(z.strictObject({
+	effects: desc(z.optional(z.record(z.string(), AnimEffect)), "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name."),
+	journeys: desc(z.optional(z.strictObject({
+		base: desc(z.optional(z.record(z.string(), VarMap)), "Named journey building blocks: part name → var map."),
+		compose: desc(z.optional(z.array(z.array(z.string()))), "Combinations of base parts, each emitted as a `.<parts>-journey` class.")
+	})), "Multi-part journey classes composed from `base` building blocks.")
+}), "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here.");
+const DesignSystemSchema = z.strictObject({
+	$schema: desc(z.optional(z.string()), "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation."),
+	meta: desc(z.optional(z.strictObject({
+		name: desc(z.optional(z.string()), "Brand/system name. Used as the `name` field and `<h1>` of the `design` format's `DESIGN.md`. Defaults to \"Design System\"."),
+		description: desc(z.optional(z.string()), "One or two sentences on the brand personality and the feeling the UI should evoke — what an agent needs when no token answers the question. Becomes the DESIGN.md `description` field and opens its Overview section; if omitted, a generic description of the system's mechanics is used instead.")
+	})), "Brand identity for agent-facing output. Consumed only by the `design` format (`DESIGN.md`); it emits no CSS and no tokens."),
+	colors: Colors,
+	shadows: desc(z.optional(z.record(z.string(), z.string())), "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour). Each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading."),
+	fonts: desc(z.optional(z.record(z.string(), z.string())), "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`). **Stacks only — vitops does not load webfonts.** A value here is a `font-family` list and nothing more: it emits no `@font-face`, no preload, and no metrics-matched fallback. If a family needs loading, declare it in Astro's `fonts:` config (`astro.config`, or the site config's `fonts` array) and point the token at the family's `cssVariable` — `\"display\": \"var(--font-league-spartan), sans-serif\"`. Installing a `@fontsource*` package and importing its CSS also works but gives up subsetting, preload and `size-adjust`/`ascent-override` fallbacks, so it regresses CLS."),
+	typeScale: desc(z.optional(Scale), "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities."),
+	spaceScale: desc(z.optional(Scale), "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm."),
+	patterns: z.optional(Patterns),
+	typography: z.optional(Typography),
+	animations: z.optional(Animations)
 });
-const IndexingSchema = z.object({
-	sitemapUrl: desc(z.optional(z.url()), "The sitemap to submit and to diff for changed URLs. Defaults to `<canonical>/sitemap-index.xml`."),
-	indexNow: desc(z.optional(IndexNowSchema), "IndexNow submission (Bing, Yandex, Naver, Seznam, Yep — not Google). Omit to skip the channel."),
-	searchConsole: desc(z.optional(SearchConsoleSchema), "Google Search Console property. Needs a credential at run time — either a service account in `VITOPS_GSC_SERVICE_ACCOUNT` / `GOOGLE_APPLICATION_CREDENTIALS`, or the user OAuth credential `vitops search setup` uses (`VITOPS_GOOGLE_CLIENT_ID` / `_CLIENT_SECRET` / `_REFRESH_TOKEN`). The service account wins when both are set. Never put a key in this file."),
-	priorityUrls: desc(z.optional(z.array(z.url())), "The pages whose indexing actually matters. `vitops search notify --check` inspects these and exits non-zero if Google has not indexed one. Kept explicit because URL Inspection is quota-bound (2000/day), so checking every page is neither affordable nor informative.")
+const ColorsPatch = z.strictObject({
+	palette: z.optional(z.record(z.string(), Ramp)),
+	roles: z.optional(z.record(z.string(), RoleSpecSchema)),
+	utilities: z.optional(z.array(UtilityName))
 });
+const DesignSystemPatchSchema = z.extend(z.partial(DesignSystemSchema), { colors: z.optional(ColorsPatch) });
 /**
-* The ad platforms `vitops ads` can link a site to.
+* Stable URL of the published JSON Schema. Resolves once `@getvitops/generator` is on
+* npm (unpkg serves the packaged `schema.json`); `vitops init` stamps this into a
+* scaffolded config's `$schema` so editors light up autocomplete + validation.
+*/
+const SCHEMA_URL = "https://unpkg.com/@getvitops/generator/schema.json";
+/**
+* What `vitops init` actually stamps into a scaffolded config's `$schema`.
 *
-* A closed enum, mirroring `AD_PROVIDER_KEYS` in `@getvitops/utils/ads` — that
-* module owns what each platform *can do* (whether it verifies a domain, what its
-* tag is, which click ID it stamps), this owns what a config may *say*. Mirrored
-* rather than derived because a `z.enum` needs literals to reach the published JSON
-* Schema; `config.test.ts` asserts the two lists are the same set, so a provider
-* added to one and not the other fails the build rather than silently getting no
-* verification step and no tag.
+* A **local** path, following wrangler's `node_modules/wrangler/config-schema.json`.
+* `SCHEMA_URL` has no version in it, so unpkg resolves it to whatever is newest
+* — an editor validating a project pinned to generator 2.x silently checks it
+* against the 3.x schema, reporting errors for valid config and accepting
+* fields that do not exist yet. The installed copy is by definition the one
+* that matches the toolchain doing the building.
+*
+* `SCHEMA_URL` remains the schema's `$id`, which is what it is for.
 */
-const AD_PROVIDERS = [
-	"google",
-	"meta",
-	"linkedin",
-	"reddit",
-	"tiktok",
-	"microsoft",
-	"pinterest",
-	"snapchat"
-];
-const AdProviderSchema = z.enum(AD_PROVIDERS);
+const SCHEMA_LOCAL_PATH = "./node_modules/@getvitops/generator/schema.json";
+/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
+const jsonSchema = {
+	$id: SCHEMA_URL,
+	...z.toJSONSchema(DesignSystemSchema, { target: "draft-2020-12" })
+};
+/** Split a CSS value on top-level commas, ignoring commas nested in `rgba(…)` etc. */
+const splitLayers = (value) => {
+	const out = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < value.length; i++) {
+		const c = value[i];
+		if (c === "(") depth++;
+		else if (c === ")") depth--;
+		else if (c === "," && depth === 0) {
+			out.push(value.slice(start, i));
+			start = i + 1;
+		}
+	}
+	out.push(value.slice(start));
+	return out.map((s) => s.trim()).filter(Boolean);
+};
+const LENGTH = /^[+-]?(\d+\.?\d*|\.\d+)(px|rem|em|ch|ex|vh|vw|vmin|vmax|cm|mm|in|pt|pc|q)?$/i;
 /**
-* One ad property this site is linked to.
+* Why a shadow can be *valid CSS* and still render nothing: a `--shadow-<name>`
+* token is consumed both as a `box-shadow` (pattern geometry) and inside
+* `filter: drop-shadow(…)` (the `.drop-shadow-<name>` utilities, the `shadow:`
+* state shortcut). `drop-shadow()` accepts a *single* layer of at most three
+* lengths and no `inset` — a spread radius, a second comma-separated layer or an
+* inset keyword makes the function invalid, which drops the entire `filter`
+* declaration. `box-shadow` accepts all three happily, so the value looks fine
+* everywhere it is authored and only the utility silently goes blank.
+*/
+const dropShadowIssue = (value) => {
+	const layers = splitLayers(value);
+	if (layers.length > 1) return `${layers.length} comma-separated layers`;
+	const layer = layers[0] ?? "";
+	if (/(^|\s)inset(\s|$)/i.test(layer)) return "an `inset` keyword";
+	const lengths = layer.replaceAll(/[\w-]*\([^()]*\)/g, " ").split(/\s+/).filter((t) => LENGTH.test(t));
+	if (lengths.length > 3) return `a spread radius (${lengths.length} lengths)`;
+};
+const RAMP_KEYS = new Set([
+	"seed",
+	"anchors",
+	"tones"
+]);
+/**
+* Replace the bare "Invalid input" a failed union produces with the reason.
 *
-* Facts, not prose — the same rule the legal block follows. This records *which*
-* account and *which* tag id, and the platform capability table decides what can be
-* done about them. It is also what finally lets the rest of the toolchain see an ad
-* pixel: the generated cookie notice discloses its cookies, `vitops ads lint`
-* checks its click ID is captured, and the consent gate is handed the cookie names
-* to clear on revoke. A pixel pasted into a template is invisible to all three.
+* `Ramp` is `SeededRamp | FixedRamp`, and both branches are closed — so `{ seed,
+* tones }` or a stray key fails *both* and zod reports only that the union didn't
+* match. That message sends you reading the schema rather than looking at the two
+* keys in front of you, and the config that produced it is one whose `tones` were
+* being silently discarded at generate time.
 */
-const AdPropertySchema = z.object({
-	accountId: desc(z.optional(z.string()), "The advertising account as the platform shows it — Google Ads customer ID, Meta ad account, LinkedIn partner ID, Reddit advertiser ID. For LinkedIn this is also the Insight Tag id; everywhere else the tag id is `pixelId`."),
-	pixelId: desc(z.optional(z.string()), "The tag/pixel ID the browser snippet initialises — Meta pixel, TikTok pixel, Reddit pixel, Microsoft UET tag ID, Pinterest tag ID, Snap pixel, or the Google Ads conversion ID (`AW-…`, which is NOT the customer ID)."),
-	conversionLabel: desc(z.optional(z.string()), "Google Ads only: the conversion action label paired with the `AW-…` conversion ID."),
-	domain: desc(z.optional(z.string()), "Bare hostname to verify with this platform. Defaults to the host of `domains.canonical` — set it only when the ad account is verified against a different domain."),
-	domainVerification: desc(z.optional(z.string()), "The verification token from the platform UI, for the platforms that verify by DNS TXT (Meta, TikTok, Pinterest, Snapchat). `vitops ads setup` prompts for it and writes it here on first run. NOT a secret — it is published in DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key. A value containing `=` is used as the whole record, which is the escape hatch if a platform changes its prefix."),
-	category: desc(z.optional(z.enum(["marketing", "analytics"])), "Consent category the tag waits on (default `marketing`). An ad pixel is advertising by default; `analytics` is for a site using one purely for its own measurement."),
-	enabled: desc(z.optional(z.boolean()), "Set false to keep the property on record without emitting its tag.")
-});
+const explainRamp = (input) => (issue) => {
+	if (issue.code === "unrecognized_keys") {
+		const keys = issue.keys ?? [];
+		if (keys.length) return {
+			...issue,
+			message: `unknown key${keys.length > 1 ? "s" : ""} ${keys.map((k) => `"${k}"`).join(", ")} — not part of the schema, so ignored at generate time.`
+		};
+	}
+	if (issue.path.length !== 3 || issue.path[0] !== "colors" || issue.path[1] !== "palette") return issue;
+	const hue = input?.colors?.palette?.[String(issue.path[2])];
+	if (hue == null || typeof hue !== "object") return issue;
+	const keys = Object.keys(hue);
+	const unknown = keys.filter((k) => !RAMP_KEYS.has(k));
+	const message = "seed" in hue && "tones" in hue ? "a hue is either seeded (`seed`, with optional `anchors`) or fixed (`tones`) — not both. Drop one: with both present the `tones` are ignored at generate time." : unknown.length ? `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")}. A hue takes \`seed\` + optional \`anchors\`, or \`tones\`.` : keys.length === 0 ? "a hue needs `seed` (+ optional `anchors`) or `tones`." : null;
+	return message ? {
+		...issue,
+		message
+	} : issue;
+};
 /**
-* Which template set the generated legal documents are written against. This is
-* a closed enum rather than a free string because an unrecognised value would
-* otherwise silently fall back to the wrong body of law; `validateConfig` rejects
-* anything without a registered template. Add a member here and a matching entry
-* in `legal/templates/index.ts` — the two are checked against each other.
+* Validate an unknown value against the design-system schema.
+*
+* `warnings` are configurations that parse and generate, but produce output that
+* won't behave as authored — currently only the token-namespace collisions the
+* flat `--<prop>-<name>` grammar makes possible.
 */
-const JURISDICTIONS = ["ca"];
-const JurisdictionSchema = z.enum(JURISDICTIONS);
+function validate(input) {
+	const result = z.safeParse(DesignSystemSchema, input);
+	if (!result.success) return {
+		ok: false,
+		data: void 0,
+		errors: result.error.issues.map(explainRamp(input)),
+		warnings: []
+	};
+	const { palette, roles } = result.data.colors;
+	for (const [role, spec] of Object.entries(roles)) {
+		const hue = roleHue(spec);
+		if (palette[hue] == null) return {
+			ok: false,
+			data: void 0,
+			errors: [{
+				code: "custom",
+				path: [
+					"colors",
+					"roles",
+					role
+				],
+				message: `role "${role}" references unknown palette hue "${hue}"`
+			}],
+			warnings: []
+		};
+	}
+	const warnings = [];
+	const missing = REQUIRED_ROLES.filter((r) => roles[r] == null);
+	if (missing.length) warnings.push(`colors.roles is missing ${missing.map((r) => `"${r}"`).join(", ")} — the framework's own component CSS references ${missing.length === 1 ? "it" : "them"} with no fallback, so those components will render uncoloured. Add any role you like, but keep these defined.`);
+	const radii = Object.keys(result.data.patterns?.radii ?? {});
+	const items = new Set(Object.keys(result.data.patterns?.items ?? {}));
+	for (const name of radii) if (items.has(name)) warnings.push(`patterns.radii.${name} collides with the "${name}" pattern on --br-${name}; the pattern's override hook wins — rename the radius`);
+	for (const [name, value] of Object.entries(result.data.shadows ?? {})) {
+		const issue = dropShadowIssue(value);
+		if (issue) warnings.push(`shadows.${name} carries ${issue}, which \`filter: drop-shadow()\` rejects — \`.drop-shadow-${name}\` will render no shadow at all (the token still works as a \`box-shadow\`). Use one layer of at most three lengths.`);
+	}
+	const refs = tokenRefIssues(result.data);
+	warnings.push(...refs.warnings);
+	if (refs.errors.length) return {
+		ok: false,
+		data: void 0,
+		errors: refs.errors.map((e) => ({
+			code: "custom",
+			...e
+		})),
+		warnings
+	};
+	return {
+		ok: true,
+		data: result.data,
+		errors: [],
+		warnings
+	};
+}
+
+//#endregion
+//#region src/config.ts
 /**
-* The country each template set frames cross-border transfers as *leaving*.
+* The top-level configuration schema — the umbrella around a
+* `design-system.json`-compliant `designSystem`.
 *
-* A jurisdiction's own country is not a transfer, so this is what filters the
-* disclosure lists — without it, `country: "Canada"` renders the incoherent
-* "outside of Canada, including Canada".
+* **Three sections, one document.** A config is `{ designSystem, organization,
+* site }`:
 *
-* It belongs to the **jurisdiction**, not to `organization.address`: a `ca` policy
-* says "outside of Canada" even for a business incorporated elsewhere. (The
-* address drives a different sentence — the terms' governing-law clause, via
-* `governingCountry`.) `satisfies` makes a new jurisdiction unable to forget it,
-* the same guard style as `TEMPLATES`.
+*  - `designSystem` — the token set (named themes + which theme/appearance).
+*  - `organization` — the company: who it is, where it is, how to reach it, what
+*    it sells. Facts that stay true if the site is rebuilt from scratch.
+*  - `site` — this published site: locales, domains, environments, SEO,
+*    analytics, legal, icons, deployment. Facts about *a* presentation of the
+*    organization.
+*
+* The split is not cosmetic. The flat predecessor (`SiteConfig`) held the company
+* and the deployment as peers, so no single noun described it — and the
+* multi-site case was inexpressible. With three sections, several sites can share
+* one `organization` and override only `site`.
+*
+* Authored with `zod/mini` (same instance the design-system schema uses), so the
+* two compose: `DesignSystemSchema` is embedded as `designSystem.themes.<theme>` and the
+* whole thing serialises to one JSON Schema via `z.toJSONSchema`. Everything a
+* generator needs derives from here: the `Config` type (`z.infer`), the
+* published JSON Schema (`configJsonSchema`), and runtime validation (`validateConfig`).
+*
+* Pure: no YAML/env/fs. `resolveConfig` takes an already-parsed object; a
+* thin loader (reading YAML, injecting `SITE_ENV`) lives outside this module.
 */
-const JURISDICTION_COUNTRIES = { ca: "Canada" };
+const LocalizableSchema = desc(z.union([z.string(), z.record(z.string(), z.string())]), "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`).");
+const ImageRefSchema = z.union([z.string(), z.object({
+	src: z.string(),
+	alt: z.string(),
+	width: z.optional(z.number()),
+	height: z.optional(z.number())
+})]);
+const AttrValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+]);
+const AttrsSchema = z.optional(z.record(z.string(), AttrValue));
+const IsoDate = z.string().check(z.regex(/^\d{4}-\d{2}-\d{2}$/));
+const Iso4217 = z.string().check(z.regex(/^[A-Z]{3}$/));
+const DayOfWeek = z.enum([
+	"Monday",
+	"Tuesday",
+	"Wednesday",
+	"Thursday",
+	"Friday",
+	"Saturday",
+	"Sunday"
+]);
+const DesignSystemEntry = z.extend(DesignSystemPatchSchema, {
+	displayName: desc(z.optional(LocalizableSchema), "Human-readable theme name (localisable). The label a theme picker would show — nothing reads it yet, because nothing builds more than one theme (see `themes`)."),
+	extends: desc(z.optional(z.string()), "Another `themes` key to inherit from; this entry then only supplies what it overrides.")
+});
 /**
-* A third party that receives personal information. The generator derives the
-* ones it can see (analytics IDs, Turnstile, the deploy platform); this is for
-* the rest, which no other part of the config implies.
+* The design system as a whole: the named themes plus the facts that describe the
+* system rather than any one theme.
 *
-* Deliberately facts, not prose: the config records *what is true*, the template
-* owns *how it is said*. That keeps a policy correct when the wording changes.
+* `themes` is nested rather than being the block itself because the block used to
+* BE the map — every key was a theme name, so there was nowhere to put
+* system-wide metadata without it colliding with a theme of that name.
+*
+* Note the two axes here are independent, and deliberately so. `defaultTheme`
+* picks a *theme* (an authored design system); `defaultColorScheme` picks an
+* *appearance* (light/dark), which every theme already has because the flip is
+* derived from one ramp rather than authored. "Theme `elegant`, appearance
+* follows the OS" has to be sayable, and a single union could not express it.
 */
-const ProcessorStorageSchema = z.object({
-	country: desc(z.string(), "A country or bloc where this provider stores or processes the information, as it should read in a sentence (e.g. \"Canada\", \"the United States\", \"the European Union\"). Naming the jurisdiction the policy is written for is meaningful: it says this information does not leave it."),
-	scope: desc(z.optional(z.string()), "Which information is held there, as a noun phrase that reads after \"in the case of\" (e.g. \"account and sign-in information\", \"mailbox contents\"). Omit when this location holds everything the provider receives — a scoped entry claims LESS than an unscoped one, so omitting it is the safe default.")
+const DesignSystemBlock = desc(z.strictObject({
+	themes: desc(z.record(z.string(), DesignSystemEntry), "Named themes. `default` is the base; others may `extends` another and supply a partial patch. Light/dark is NOT a theme — the functional tokens flip per appearance within each one, so `default` already has both. Only the default theme is built today; multi-theme output and a picker are not wired yet."),
+	defaultTheme: desc(z.optional(z.string()), "Which `themes` entry to use (convention: \"default\"). Validated against the map; selecting a non-default theme is not wired yet."),
+	defaultColorScheme: desc(z.optional(z.enum([
+		"light",
+		"dark",
+		"system"
+	])), "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<wc-color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.")
+}), "The design system: named themes plus the system-wide facts (which theme, which appearance). A bare design system, or a bare theme map, is accepted as shorthand for `{ themes: … }`.");
+const LocaleSchema = z.object({
+	name: desc(z.string(), "Display name of the locale (e.g. \"English\")."),
+	tagline: desc(z.optional(z.string()), "Site tagline in this locale."),
+	basePath: desc(z.optional(z.string()), "URL prefix for this locale (e.g. \"/fr\").")
 });
-const ProcessorSchema = z.object({
-	name: desc(z.string(), "The provider, as a reader would recognise it (e.g. \"Stripe\")."),
-	purpose: desc(z.string(), "Why they receive it, as a noun phrase that reads after \"for\" (e.g. \"payment processing\")."),
-	country: desc(z.optional(z.string()), "Shorthand for the common case where one country is both where they store it and whose laws reach it: asserts BOTH `storage: [{ country }]` AND `operatorCountry`. Reads inside a sentence (e.g. \"the United States\"). When the two differ — a Canadian region operated by a US company — state `storage` and `operatorCountry` instead; setting this alongside either is rejected."),
-	storage: desc(z.optional(z.array(ProcessorStorageSchema)), "Where the information actually rests. Feeds the \"stored or processed outside of <jurisdiction>\" disclosure and nothing else. Several entries are allowed, each optionally scoped to a category of information — which is what makes a Canadian-region tenant holding identity data in the US expressible."),
-	operatorCountry: desc(z.optional(z.string()), "The jurisdiction that can compel this provider to hand the information over — where it is established, or from which it is controlled. Reads after \"the laws of\" (e.g. \"the United States\"); a bloc is acceptable. A SEPARATE fact from `storage`, because privacy law cares about foreign *access*, not only foreign storage: a Canadian-region service run by a US company is `storage: [{ country: \"Canada\" }]` with `operatorCountry: \"the United States\"`."),
-	privacyUrl: z.optional(z.url())
+const HttpRedirect = z.union([
+	z.literal(301),
+	z.literal(302),
+	z.literal(307),
+	z.literal(308)
+]);
+const DomainAliasSchema = z.object({
+	domain: z.string(),
+	redirectType: HttpRedirect,
+	redirectTo: z.string(),
+	environment: z.optional(z.string())
 });
-const SiteSectionSchema = z.object({
-	defaultLocale: desc(z.string(), "The locale used when none is specified; must be a `locales` key."),
-	locales: desc(z.record(z.string(), LocaleSchema), "Locales the site is published in, keyed by BCP 47 tag (e.g. \"en\", \"fr\")."),
-	domains: desc(z.optional(z.object({
-		canonical: desc(z.url(), "The canonical origin used for absolute URLs and SEO."),
-		aliases: desc(z.optional(z.array(DomainAliasSchema)), "Alias domains and how they redirect to the canonical one.")
-	})), "Canonical domain + redirecting aliases."),
-	dns: desc(z.optional(z.record(z.string(), DnsDomainSchema)), "Desired DNS state per domain (provider, nameservers, records) — declarative reference, not applied automatically."),
-	cloudflare: desc(z.optional(z.record(z.string(), z.unknown())), "Deliberate escape hatch for provider-specific Cloudflare settings — out of scope to model here."),
-	searchConsole: desc(z.optional(z.record(z.string(), SearchConsoleSetupSchema)), "Domains to onboard as Google Search Console *domain properties* via `vitops search setup`, keyed by bare hostname (mirrors `dns`). Credentials come from the environment (CLOUDFLARE_API_TOKEN + the Google OAuth vars) — never in this file."),
-	environments: desc(z.record(z.string(), EnvironmentSchema), "Deploy environments (production, dev, …): URL, API origin, analytics toggle, robots policy, active A/B variant."),
-	abTesting: desc(z.optional(z.object({
-		enabled: z.boolean(),
-		cookieName: z.optional(z.string()),
-		cookieMaxAge: desc(z.optional(z.number().check(z.int(), z.positive())), "Seconds."),
-		splitRatio: desc(z.optional(z.number().check(z.gte(0), z.lte(1))), "Fraction of traffic sent to the variant (0–1)."),
-		variants: desc(z.optional(z.record(z.string(), AbVariantSchema)), "Named variants; each targets an environment and may deep-merge config `overrides`.")
-	})), "A/B testing: cookie-based split plus named variants whose `overrides` patch the config per environment."),
-	fonts: desc(z.optional(z.array(SiteFontSchema)), "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.themes.<theme>.fonts` and reference the same `cssVariable`."),
-	tags: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-tag taxonomy (site-specific; not interpreted by the generator)."),
-	postTypes: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-type definitions (site-specific; not interpreted by the generator)."),
-	galleries: desc(z.optional(z.record(z.string(), GallerySchema)), "Named image galleries (title, tags, images with localisable alt/caption)."),
-	testimonials: desc(z.optional(z.record(z.string(), TestimonialGroupSchema)), "Named testimonial groups (quote, name, role, rating, date)."),
-	templates: desc(z.optional(z.record(z.string(), TemplateSchema)), "Named content templates rendered at SSR time: `nav` (menu trees), `form` (field lists + submit), or `nodes` (raw element trees)."),
-	navigation: desc(z.optional(z.object({ activeTemplate: desc(z.optional(z.object({
-		default: desc(z.optional(z.string()), "A `templates` key."),
-		breakpoints: desc(z.optional(z.record(z.string(), z.string())), "Breakpoint name → `templates` key overrides.")
-	})), "Which nav template is active, optionally per breakpoint.") })), "Site navigation settings (which nav template renders where)."),
-	seo: desc(z.optional(z.object({
-		titleTemplate: desc(z.optional(z.string()), "Page-title pattern (e.g. \"%s · Acme\")."),
-		descriptionTemplate: z.optional(z.string()),
-		robots: desc(z.optional(RobotsSchema), "e.g. \"index,follow\" / \"noindex,nofollow\"."),
-		googleSiteVerification: z.optional(z.string()),
-		bingSiteVerification: z.optional(z.string()),
-		openGraph: z.optional(OpenGraphSchema),
-		twitter: z.optional(TwitterSchema),
-		indexing: desc(z.optional(IndexingSchema), "How `vitops search notify` tells search engines about a deploy: which sitemap, IndexNow key, Search Console property, and which pages to verify afterwards.")
-	})), "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification."),
-	analytics: desc(z.optional(z.object({
-		googleAnalyticsId: z.optional(z.string()),
-		plausibleDomain: z.optional(z.string()),
-		googleTagManagerId: z.optional(z.string()),
-		clarityId: desc(z.optional(z.string()), "Microsoft Clarity project ID."),
-		matomo: desc(z.optional(z.object({
-			url: desc(z.string(), "Instance base URL (self-hosted, or `*.matomo.cloud`)."),
-			siteId: desc(z.string(), "Site ID within that instance."),
-			cookies: desc(z.optional(z.boolean()), "Default false — Matomo runs cookieless (`disableCookies`), which is what lets the cookie notice state positively that it sets none.")
-		})), "Matomo instance.")
-	})), "Analytics provider IDs (gated per environment via `environments.<env>.analytics`). Which provider is set is also what the generated privacy policy and cookie notice disclose — see `legal`."),
-	notifications: desc(z.optional(z.object({ email: desc(z.optional(z.union([z.email(), z.object({
-		provider: desc(z.literal("cloudflare"), "Delivery provider. Only Cloudflare Email Sending is implemented; the field is stated so adding another is additive."),
-		to: desc(z.optional(z.email()), "Recipient. Defaults to the primary location’s `email`, then the first location that has one."),
-		from: desc(z.optional(z.email()), "Sender. Defaults to `noreply@<domains.canonical>`. Its domain must be onboarded (`wrangler email sending enable <domain>`) or every send fails."),
-		fromName: desc(z.optional(z.string()), "Display name on the From header. Defaults to `organization.name`."),
-		replyTo: desc(z.optional(z.email()), "Reply-To header."),
-		binding: desc(z.optional(z.string()), "Workers `send_email` binding name (default `EMAIL`). Set it when using a restricted binding.")
-	})])), "Where conversion notifications are e-mailed. A bare address is shorthand for `{ provider: \"cloudflare\", to }`.") })), "Where site notifications (form submissions, tracked calls) are sent. TODO: `sms` and `persist` channels — only `email` is implemented."),
-	tracking: desc(z.optional(z.object({
-		enabled: desc(z.optional(z.boolean()), "Capture ad click IDs and UTMs from the landing URL into the `_ac` cookie, for attributing conversions."),
-		category: desc(z.optional(z.enum(["marketing", "analytics"])), "Consent category the `_ac` cookie waits on (default `marketing`). It is a 90-day identifier tying a visitor to the ad that brought them, so it is only written once this category is granted — and asking for it is what raises the banner."),
-		platforms: desc(z.optional(z.array(z.string())), "Informational list of ad platforms in use. Capture recognises every known click-ID parameter regardless.")
-	})), "Ad-click attribution for conversion tracking."),
-	ads: desc(z.optional(z.partialRecord(AdProviderSchema, AdPropertySchema)), "Ad properties this site is linked to, keyed by platform. Read by `vitops ads setup` (ensure the DNS verification record), `vitops ads tags` (emit the consent-gated pixel), and the generated cookie notice (disclose what each pixel stores). Credentials never live here — the DNS write uses CLOUDFLARE_API_TOKEN from the environment."),
-	security: desc(z.optional(z.object({ turnstile: z.optional(z.object({ siteKey: desc(z.optional(z.string()), "Cloudflare Turnstile site key (public).") })) })), "Security integrations (bot protection)."),
-	legal: desc(z.optional(z.object({
-		jurisdiction: desc(z.optional(JurisdictionSchema), "Which legal template set the generated documents use. Default `ca`."),
-		privacyPolicy: z.optional(z.object({
-			enabled: z.boolean(),
-			url: z.optional(z.url()),
-			lastUpdated: z.optional(IsoDate),
-			privacyOfficer: desc(z.optional(ContactConfigSchema), "Who privacy requests go to. Falls back to `contact`, then `primaryLocation`."),
-			retention: desc(z.optional(z.string()), "How long personal information is kept, in prose (e.g. \"24 months after last contact\")."),
-			processors: desc(z.optional(z.array(ProcessorSchema)), "Third parties that receive personal information and cannot be inferred from the rest of the config (payment processors, CRMs, mail senders). Known providers implied by `analytics`, `security` and `deployment` are added automatically — list only the rest.")
-		})),
-		termsOfService: z.optional(z.object({
-			enabled: z.boolean(),
-			url: z.optional(z.url()),
-			lastUpdated: z.optional(z.nullable(IsoDate)),
-			governingLaw: desc(z.optional(z.string()), "Governing-law clause, in prose (e.g. \"the Province of Ontario\"). Defaults from the contact address.")
-		})),
-		cookieConsent: z.optional(z.object({
-			enabled: z.boolean(),
-			type: desc(z.optional(z.enum(["opt-in", "opt-out"])), "Consent model."),
-			position: z.optional(z.enum([
-				"top",
-				"bottom",
-				"center"
-			])),
-			categories: z.optional(z.array(z.string()))
-		}))
-	})), "Legal pages: which documents exist, where they live, and the facts the generated prose asserts."),
-	icons: desc(z.optional(z.looseObject({
-		ui: desc(z.optional(z.string()), "Icon set used for UI chrome (e.g. \"lucide\", \"ph\")."),
-		brand: desc(z.optional(z.string()), "Icon set used for brand marks."),
-		weight: desc(z.optional(z.string()), "Weight for suffix-weighted sets like Phosphor (\"regular\" | \"bold\" | \"duotone\" | \"fill\" | \"light\" | \"thin\"). Ignored by sets that split weights across collections, e.g. Font Awesome."),
-		sprite: desc(z.optional(z.boolean()), "Emit an SVG sprite (icons.svg) alongside the stylesheet, for consumers that cannot run an icon integration (Bricks/WordPress, EmDash renderers)."),
-		semantic: desc(z.optional(z.array(z.string())), "Named semantic icons to include."),
-		"fa7-solid": z.optional(z.array(z.string())),
-		"fa7-regular": z.optional(z.array(z.string())),
-		"fa7-light": z.optional(z.array(z.string())),
-		"fa7-thin": z.optional(z.array(z.string())),
-		"fa7-brands": z.optional(z.array(z.string())),
-		"simple-icons": z.optional(z.array(z.string())),
-		"material-symbols": z.optional(z.array(z.string())),
-		lucide: z.optional(z.array(z.string())),
-		ph: z.optional(z.array(z.string()))
-	})), "Icon sets and the specific icons to bundle from each (keys are iconify collection names)."),
-	favicon: desc(z.optional(z.object({
-		source: desc(z.string(), "Source image (SVG/PNG) the favicon set is generated from."),
-		lowResSource: desc(z.optional(z.string()), "Alternate source for small raster sizes (16/32px) when the main source scales down poorly."),
-		name: desc(z.optional(z.string()), "App name for the generated web manifest / PWA."),
-		themeColor: desc(z.optional(z.string()), "PWA theme color (also `<meta name=\"theme-color\">`)."),
-		backgroundColor: desc(z.optional(z.string()), "PWA background color.")
-	})), "Favicon/PWA asset generation (consumed by `@getvitops/utils` favicon tooling)."),
-	deployment: desc(z.optional(z.object({
-		platform: z.optional(z.string()),
-		buildCommand: z.optional(z.string()),
-		deployCommand: z.optional(z.string()),
-		outputDirectory: z.optional(z.string()),
-		type: z.optional(z.string())
-	})), "How the site is built and deployed (platform, commands, output directory) — informational for tooling.")
+const PostalAddressSchema = desc(z.object({
+	streetAddress: z.string(),
+	addressLocality: desc(z.string(), "City."),
+	addressRegion: desc(z.optional(z.string()), "State / province."),
+	postalCode: z.optional(z.string()),
+	addressCountry: desc(z.string(), "Country (ISO 3166-1 alpha-2 preferred).")
+}), "schema.org `PostalAddress` field names, so JSON-LD generation is lossless.");
+const ContactObjectSchema = z.object({
+	name: z.optional(z.string()),
+	email: z.optional(z.email()),
+	phone: z.optional(z.string()),
+	address: z.optional(PostalAddressSchema)
 });
-const OrganizationSectionSchema = z.extend(OrganizationSchema, {
-	contact: desc(z.optional(ContactConfigSchema), "Primary contact: either a `locations` key (string reference) or an inline name/email/phone/address object."),
-	primaryLocation: desc(z.optional(z.string()), "The main `locations` key (for JSON-LD and defaults)."),
-	locations: desc(z.optional(z.record(z.string(), LocationSchema)), "Physical locations (schema.org LocalBusiness): address, geo, opening hours, service area."),
-	services: desc(z.optional(z.record(z.string(), ServiceSchema)), "Services offered (schema.org Service/Offer): name, description, slug, price offers."),
-	links: desc(z.optional(z.object({
-		googleMaps: z.optional(z.url()),
-		instagram: z.optional(z.url()),
-		facebook: z.optional(z.url()),
-		x: z.optional(z.url()),
-		linkedin: z.optional(z.url()),
-		youtube: z.optional(z.url()),
-		github: z.optional(z.url())
-	})), "Public profile URLs (also feed JSON-LD `sameAs` via `organization.sameAs`).")
+const ContactConfigSchema = z.union([z.string(), ContactObjectSchema]);
+const GeoSchema = z.object({
+	latitude: z.number().check(z.gte(-90), z.lte(90)),
+	longitude: z.number().check(z.gte(-180), z.lte(180))
 });
-const ConfigSchema = z.object({
-	designSystem: DesignSystemBlock,
-	organization: desc(z.optional(OrganizationSectionSchema), "The company: schema.org Organization details for JSON-LD (name, legalName, logo, tax IDs, sameAs), plus its contact, physical locations, services and public profiles. These stay true across sites — several sites can share one `organization` and differ only in `site`."),
-	site: desc(SiteSectionSchema, "This published site: locales, domains, environments, content templates, SEO, analytics, legal documents, icons, favicon and deployment. Facts about a *presentation* of the organization rather than the organization itself.")
+/** schema.org `OpeningHoursSpecification` — per-day open/close (24h `HH:MM`). */
+const OpeningHoursSchema = z.object({
+	dayOfWeek: z.array(DayOfWeek),
+	opens: z.string().check(z.regex(/^\d{2}:\d{2}$/)),
+	closes: z.string().check(z.regex(/^\d{2}:\d{2}$/))
 });
-const CONFIG_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/config.schema.json";
-/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
-const configJsonSchema = {
-	$id: CONFIG_SCHEMA_URL,
-	...z.toJSONSchema(ConfigSchema, { target: "draft-2020-12" })
-};
-const issue = (path, message) => ({
-	code: "custom",
-	path,
-	message
+const LocalBusinessType = z.enum([
+	"LocalBusiness",
+	"Store",
+	"Restaurant",
+	"CafeOrCoffeeShop",
+	"ProfessionalService",
+	"MedicalBusiness",
+	"HealthAndBeautyBusiness",
+	"HomeAndConstructionBusiness",
+	"AutomotiveBusiness",
+	"FinancialService",
+	"LegalService",
+	"RealEstateAgent",
+	"Organization"
+]);
+const LocationSchema = z.object({
+	slug: z.optional(LocalizableSchema),
+	name: LocalizableSchema,
+	email: z.optional(z.email()),
+	phone: z.optional(z.string()),
+	address: z.optional(PostalAddressSchema),
+	geo: z.optional(GeoSchema),
+	hours: z.optional(z.array(OpeningHoursSchema)),
+	type: z.optional(LocalBusinessType),
+	description: z.optional(LocalizableSchema),
+	areaServed: z.optional(z.array(z.string())),
+	priceRange: z.optional(z.string()),
+	paymentAccepted: z.optional(z.array(z.string())),
+	currenciesAccepted: z.optional(Iso4217),
+	knowsLanguage: z.optional(z.array(z.string()))
+});
+const OrganizationSchema = z.object({
+	name: desc(z.optional(LocalizableSchema), "Trading name, as a reader would recognise it (e.g. \"Acme\"). Localisable."),
+	legalName: desc(z.optional(z.string()), "Registered legal name (e.g. \"Acme Widgets Inc.\"). The generated legal documents prefer this over `name` — a policy is a statement by the legal entity."),
+	foundingDate: desc(z.optional(IsoDate), "Date the organization was founded (YYYY-MM-DD)."),
+	logo: desc(z.optional(ImageRefSchema), "Organization logo → JSON-LD `logo`."),
+	email: desc(z.optional(z.email()), "General contact address. Also the last fallback for privacy requests — see `contact`."),
+	phone: desc(z.optional(z.string()), "General contact telephone number."),
+	address: desc(z.optional(PostalAddressSchema), "Registered/mailing address. Its `addressRegion` and `addressCountry` are what the governing-law clause of the generated terms of service defaults to."),
+	taxID: desc(z.optional(z.string()), "Tax identification number."),
+	vatID: desc(z.optional(z.string()), "VAT identification number."),
+	sameAs: desc(z.optional(z.array(z.url())), "Profile URLs → JSON-LD `sameAs` (mirrors `links`).")
+});
+const DnsRecordType = z.enum([
+	"A",
+	"AAAA",
+	"CNAME",
+	"TXT",
+	"MX",
+	"NS",
+	"SRV",
+	"CAA",
+	"PTR",
+	"SOA"
+]);
+const DnsRecordSchema = z.object({
+	type: DnsRecordType,
+	name: z.optional(z.string()),
+	value: z.string(),
+	ttl: z.optional(z.number().check(z.int(), z.positive())),
+	proxied: z.optional(z.boolean())
+});
+const DnsDomainSchema = z.object({
+	provider: z.optional(z.string()),
+	nameservers: z.optional(z.array(z.string())),
+	records: z.optional(z.array(DnsRecordSchema))
 });
 /**
-* Where each key of the old flat config now lives.
-*
-* This exists so the restructure fails with a sentence a reader can act on. Zod
-* reports a flat config as a dozen separate `unrecognized_keys` issues plus a
-* missing required `site` — an accurate description of the document that teaches
-* nobody where anything went. Checked first, and it short-circuits: once we know
-* the document is the old shape, every other error is downstream noise.
-*/
-const MOVED_KEYS = {
-	defaultLocale: "site",
-	locales: "site",
-	domains: "site",
-	dns: "site",
-	cloudflare: "site",
-	environments: "site",
-	abTesting: "site",
-	fonts: "site",
-	tags: "site",
-	postTypes: "site",
-	galleries: "site",
-	testimonials: "site",
-	templates: "site",
-	navigation: "site",
-	seo: "site",
-	analytics: "site",
-	notifications: "site",
-	tracking: "site",
-	security: "site",
-	legal: "site",
-	icons: "site",
-	favicon: "site",
-	deployment: "site",
-	contact: "organization",
-	primaryLocation: "organization",
-	locations: "organization",
-	services: "organization",
-	links: "organization"
-};
-/**
-* Detect the pre-3.0 flat shape and name the moves.
+* One domain to onboard into Google Search Console via `vitops search setup`.
 *
-* Keyed on a moved key sitting at the ROOT, not on the absence of `site` — a
-* config that simply forgot `site` should get the ordinary "required" error, and
-* a partially-migrated one (some keys moved, some not) is exactly the case worth
-* catching loudly.
-*/
-function migrationIssues(raw) {
-	if (typeof raw !== "object" || raw == null || Array.isArray(raw)) return [];
-	const found = Object.keys(raw).filter((k) => k in MOVED_KEYS);
-	if (found.length === 0) return [];
-	return [issue([], `this is the pre-3.0 flat site config. The top level is now three sections — \`designSystem\`, \`organization\`, \`site\` — and these keys moved:
-${found.map((k) => `  ${k} → ${MOVED_KEYS[k]}.${k}`).join("\n")}\n\`designSystem\` and the fields already under \`organization\` stay where they are.`)];
-}
-/**
-* Validate a raw (already parsed) config: shape via zod, then the cross-field
-* integrity that JSON Schema can't express (referential keys, extends acyclicity).
-* These live only here — the published JSON Schema enforces shape, not integrity.
+* The verification token is fetched live from the Site Verification API at run
+* time and written to DNS — it is never stored here. What the config records is
+* the *intent*: which domains to onboard, and who should co-own them.
 */
-function validateConfig(input) {
-	const migration = migrationIssues(input);
-	if (migration.length) return {
-		ok: false,
-		data: void 0,
-		errors: migration
-	};
-	const parsed = z.safeParse(ConfigSchema, input);
-	if (!parsed.success) return {
-		ok: false,
-		data: void 0,
-		errors: parsed.error.issues
-	};
-	const cfg = parsed.data;
-	const site = cfg.site;
-	const org = cfg.organization;
-	const errors = [];
-	const has = (m, k) => !!m && k in m;
-	if (!has(site.locales, site.defaultLocale)) errors.push(issue(["site", "defaultLocale"], `defaultLocale "${site.defaultLocale}" is not in locales`));
-	const themes = cfg.designSystem?.themes ?? {};
-	const defaultTheme = cfg.designSystem?.defaultTheme;
-	if (!has(themes, "default") && defaultTheme == null) errors.push(issue(["designSystem", "themes"], "themes must include a \"default\" entry"));
-	if (defaultTheme != null && !has(themes, defaultTheme)) errors.push(issue(["designSystem", "defaultTheme"], `defaultTheme "${defaultTheme}" is not in designSystem.themes`));
-	for (const [key, entry] of Object.entries(themes)) if (entry.extends != null && !has(themes, entry.extends)) errors.push(issue([
-		"designSystem",
-		"themes",
-		key,
-		"extends"
-	], `extends "${entry.extends}" is not a themes key`));
-	for (const key of Object.keys(themes)) try {
-		resolveTheme(themes, key);
-	} catch (e) {
-		errors.push(issue([
-			"designSystem",
-			"themes",
-			key
-		], e.message));
-	}
-	if (org?.primaryLocation != null && !has(org.locations, org.primaryLocation)) errors.push(issue(["organization", "primaryLocation"], `primaryLocation "${org.primaryLocation}" is not in organization.locations`));
-	if (typeof org?.contact === "string" && !has(org.locations, org.contact)) errors.push(issue(["organization", "contact"], `contact "${org.contact}" is not an organization.locations key`));
-	for (const [name, v] of Object.entries(site.abTesting?.variants ?? {})) if (!has(site.environments, v.environment)) errors.push(issue([
-		"site",
-		"abTesting",
-		"variants",
-		name,
-		"environment"
-	], `environment "${v.environment}" is not in site.environments`));
-	for (const [i, a] of (site.domains?.aliases ?? []).entries()) if (a.environment != null && !has(site.environments, a.environment)) errors.push(issue([
-		"site",
-		"domains",
-		"aliases",
-		i,
-		"environment"
-	], `environment "${a.environment}" is not in site.environments`));
-	const templates = site.templates;
-	const at = site.navigation?.activeTemplate;
-	if (at?.default != null && !has(templates, at.default)) errors.push(issue([
-		"site",
-		"navigation",
-		"activeTemplate",
-		"default"
-	], `template "${at.default}" is not in site.templates`));
-	for (const [bp, tpl] of Object.entries(at?.breakpoints ?? {})) if (!has(templates, tpl)) errors.push(issue([
-		"site",
-		"navigation",
-		"activeTemplate",
-		"breakpoints",
-		bp
-	], `template "${tpl}" is not in site.templates`));
-	const privacy = site.legal?.privacyPolicy;
-	/**
-	* `country` is shorthand for BOTH `storage` and `operatorCountry`, so combining it
-	* with either is genuinely ambiguous — is the shorthand narrowing the explicit
-	* fact, or adding to it? Both readings are plausible and they make *contradictory
-	* legal claims*, so this is rejected rather than resolved by a silent rule.
-	*
-	* Checked unconditionally, not gated on `privacy.enabled`: the fact is wrong
-	* either way, and a document turned on later shouldn't surface it for the first
-	* time. Here rather than as a `z.refine` on the schema because parse-time
-	* rejection would make `resolveConfig` throw on the `vitops legal` path, which
-	* has no formatting for a zod issue — `validateConfig` is where every other
-	* cross-field legal requirement already lives, and it prints `path: message`.
-	*/
-	for (const [i, p] of (privacy?.processors ?? []).entries()) if (p.country != null && (p.storage != null || p.operatorCountry != null)) errors.push(issue([
-		"site",
-		"legal",
-		"privacyPolicy",
-		"processors",
-		i,
-		"country"
-	], `processor "${p.name}": \`country\` is shorthand for BOTH \`storage\` and \`operatorCountry\`, so combining it with either makes the narrower claim ambiguous — drop \`country\` and state the two facts, or drop the two and keep the shorthand`));
-	if (typeof privacy?.privacyOfficer === "string" && !has(org?.locations, privacy.privacyOfficer)) errors.push(issue([
-		"site",
-		"legal",
-		"privacyPolicy",
-		"privacyOfficer"
-	], `privacyOfficer "${privacy.privacyOfficer}" is not an organization.locations key`));
-	if (privacy?.enabled) {
-		if (resolvePrivacyContact(cfg) == null) errors.push(issue([
-			"site",
-			"legal",
-			"privacyPolicy"
-		], "privacyPolicy.enabled requires a contact for privacy requests — set site.legal.privacyPolicy.privacyOfficer, organization.contact, or organization.email/address"));
-		if (site.domains?.canonical == null) errors.push(issue([
-			"site",
-			"legal",
-			"privacyPolicy"
-		], "privacyPolicy.enabled requires site.domains.canonical — the policy states where information is held"));
-	}
-	const indexing = site.seo?.indexing;
-	if (indexing != null && site.domains?.canonical == null) {
-		if (indexing.sitemapUrl == null) errors.push(issue([
-			"site",
-			"seo",
-			"indexing",
-			"sitemapUrl"
-		], "site.seo.indexing needs site.domains.canonical to derive the sitemap URL — set one, or state sitemapUrl explicitly"));
-		if (indexing.indexNow != null && indexing.indexNow.keyLocation == null) errors.push(issue([
-			"site",
-			"seo",
-			"indexing",
-			"indexNow",
-			"keyLocation"
-		], "site.seo.indexing.indexNow needs site.domains.canonical to derive the key location — set one, or state keyLocation explicitly"));
-	}
-	for (const [provider, entry] of Object.entries(site.ads ?? {})) {
-		if (entry == null) continue;
-		const platform = AD_PLATFORMS[provider];
-		const at = [
-			"site",
-			"ads",
-			provider
-		];
-		if (entry.domainVerification != null && platform.verification.method === "none") errors.push(issue([...at, "domainVerification"], `${platform.name} has no domain verification — ${platform.verification.reason ?? "nothing verifies a domain there"}. Remove the token; linking is the tag and the account id.`));
-		if (entry.domainVerification != null && entry.domain == null && site.domains?.canonical == null) errors.push(issue([...at, "domain"], `site.ads.${provider}.domainVerification needs a domain to put the record on — set site.domains.canonical, or state site.ads.${provider}.domain explicitly`));
-		if (entry.accountId == null && entry.pixelId == null) errors.push(issue(at, `site.ads.${provider} identifies nothing — set accountId (the advertising account) and/or pixelId (the tag: ${platform.tag.needs} is what its snippet needs)`));
+const SearchConsoleSetupSchema = z.object({
+	delegatedOwners: desc(z.optional(z.array(z.email())), "Emails added as verification owners on the Site Verification web resource. Automated via the API — additive and idempotent, never removes an existing owner."),
+	fullUserGroup: desc(z.optional(z.email()), "A Google Group to grant Full-User access in Search Console. SURFACED AS A REMINDER only: Search Console exposes no user/permission API, so this step stays manual by design.")
+});
+const RobotsSchema = z.string();
+const EnvironmentSchema = z.object({
+	url: desc(z.url(), "Public origin of this environment."),
+	api: desc(z.optional(z.url()), "API origin, when different from `url`."),
+	analytics: desc(z.optional(z.boolean()), "Whether analytics fire in this environment."),
+	ads: desc(z.optional(z.boolean()), "Whether `site.ads` pixels fire in this environment. Defaults to `analytics`, then true — a preview deployment sending pageviews is survivable, one firing conversion pixels is not, so this can be turned off on its own."),
+	robots: desc(z.optional(RobotsSchema), "Robots policy (e.g. \"noindex,nofollow\" for dev)."),
+	variant: desc(z.optional(z.string()), "Active `abTesting.variants` key for this environment.")
+});
+const AbVariantSchema = z.object({
+	environment: z.string(),
+	description: z.optional(z.string()),
+	overrides: z.optional(z.record(z.string(), z.unknown()))
+});
+const FontProvider = z.enum([
+	"google",
+	"fontsource",
+	"adobe",
+	"bunny",
+	"fontshare",
+	"googleicons",
+	"npm",
+	"local"
+]);
+const FontStyle = z.enum(["normal", "italic"]);
+const FontDisplay = z.enum([
+	"auto",
+	"block",
+	"swap",
+	"fallback",
+	"optional"
+]);
+const FontWeight = z.union([z.number(), z.string()]);
+/** A local-font face (`provider: 'local'`). */
+const FontVariantSchema = z.object({
+	src: z.array(z.string()),
+	weight: z.optional(FontWeight),
+	style: z.optional(FontStyle),
+	unicodeRange: z.optional(z.array(z.string())),
+	display: z.optional(FontDisplay)
+});
+const SiteFontSchema = z.object({
+	name: z.string(),
+	provider: FontProvider,
+	cssVariable: z.string().check(z.regex(/^--/)),
+	weights: z.optional(z.array(FontWeight)),
+	styles: z.optional(z.array(FontStyle)),
+	subsets: z.optional(z.array(z.string())),
+	fallbacks: z.optional(z.array(z.string())),
+	optimizedFallbacks: z.optional(z.boolean()),
+	display: z.optional(FontDisplay),
+	formats: z.optional(z.array(z.string())),
+	unicodeRange: z.optional(z.array(z.string())),
+	variants: z.optional(z.array(FontVariantSchema)),
+	preload: desc(z.optional(z.union([z.boolean(), z.array(z.object({
+		weight: FontWeight,
+		style: z.optional(FontStyle)
+	}))])), "Emit `<Font preload />` for this family (true, or a list of weight/style faces).")
+});
+const PresentSchema = z.optional(z.record(z.string(), z.unknown()));
+const NavItemSchema = z.object({
+	label: z.optional(LocalizableSchema),
+	image: z.optional(ImageRefSchema),
+	href: z.optional(z.string()),
+	icon: z.optional(z.string()),
+	attrs: AttrsSchema,
+	itemAttrs: AttrsSchema,
+	submenu: z.optional(z.object({
+		present: PresentSchema,
+		get items() {
+			return z.optional(z.array(NavItemSchema));
+		}
+	}))
+});
+const FormFieldType = z.enum([
+	"text",
+	"email",
+	"tel",
+	"url",
+	"number",
+	"password",
+	"textarea",
+	"select",
+	"checkbox",
+	"radio",
+	"date",
+	"file",
+	"hidden"
+]);
+const FormFieldSchema = z.object({
+	name: z.string(),
+	type: FormFieldType,
+	label: z.optional(LocalizableSchema),
+	required: z.optional(z.boolean()),
+	validation: z.optional(z.string()),
+	options: z.optional(z.union([z.string(), z.array(z.object({
+		label: z.string(),
+		value: z.string()
+	}))])),
+	attrs: AttrsSchema
+});
+const ContentNodeSchema = z.object({
+	tag: z.string(),
+	attrs: AttrsSchema,
+	text: z.optional(z.string()),
+	get children() {
+		return z.optional(z.array(ContentNodeSchema));
 	}
-	if (errors.length) return {
-		ok: false,
-		data: void 0,
-		errors
-	};
-	return {
-		ok: true,
-		data: cfg,
-		errors: []
-	};
-}
+});
+const TemplateSchema = z.union([
+	z.object({
+		type: z.literal("nav"),
+		tags: z.optional(z.array(z.string())),
+		present: PresentSchema,
+		items: z.optional(z.array(NavItemSchema))
+	}),
+	z.object({
+		type: z.literal("form"),
+		tags: z.optional(z.array(z.string())),
+		present: PresentSchema,
+		action: z.optional(z.string()),
+		method: z.optional(z.enum(["get", "post"])),
+		fields: z.optional(z.array(FormFieldSchema)),
+		submit: z.optional(z.record(z.string(), AttrValue)),
+		honeypot: z.optional(z.boolean())
+	}),
+	z.object({
+		type: z.literal("nodes"),
+		tags: z.optional(z.array(z.string())),
+		nodes: z.optional(z.array(ContentNodeSchema))
+	})
+]);
+const GalleryImageSchema = z.object({
+	src: z.string(),
+	alt: LocalizableSchema,
+	caption: z.optional(LocalizableSchema)
+});
+const GallerySchema = z.object({
+	title: z.optional(LocalizableSchema),
+	tags: z.optional(z.array(z.string())),
+	images: z.array(GalleryImageSchema)
+});
+const TestimonialItemSchema = z.object({
+	quote: LocalizableSchema,
+	name: z.string(),
+	role: z.optional(z.string()),
+	rating: z.optional(z.number().check(z.gte(0), z.lte(5))),
+	date: z.optional(IsoDate)
+});
+const TestimonialGroupSchema = z.object({
+	title: z.optional(LocalizableSchema),
+	items: z.array(TestimonialItemSchema)
+});
+const OfferSchema = z.object({
+	name: z.optional(LocalizableSchema),
+	price: z.optional(z.union([z.string(), z.number()])),
+	priceCurrency: z.optional(Iso4217),
+	availability: z.optional(z.string()),
+	url: z.optional(z.url()),
+	validFrom: z.optional(IsoDate),
+	priceValidUntil: z.optional(IsoDate)
+});
+const ServiceSchema = z.object({
+	name: LocalizableSchema,
+	description: z.optional(LocalizableSchema),
+	slug: z.optional(LocalizableSchema),
+	offers: z.optional(z.array(OfferSchema))
+});
+const OpenGraphSchema = z.object({
+	type: z.optional(z.string()),
+	siteName: z.optional(z.string()),
+	title: z.optional(LocalizableSchema),
+	description: z.optional(LocalizableSchema),
+	image: z.optional(ImageRefSchema),
+	locale: z.optional(z.string())
+});
+const TwitterSchema = z.object({
+	card: z.optional(z.enum([
+		"summary",
+		"summary_large_image",
+		"app",
+		"player"
+	])),
+	site: z.optional(z.string()),
+	creator: z.optional(z.string()),
+	title: z.optional(LocalizableSchema),
+	description: z.optional(LocalizableSchema),
+	image: z.optional(ImageRefSchema)
+});
 /**
-* Resolve who privacy requests go to: the explicit privacy officer, else the
-* organization's contact, else its primary location, else the organization itself.
+* What `vitops search notify` needs to tell search engines a deploy happened.
 *
-* Exported because `validateConfig` and the legal-document derivation must agree
-* on it exactly — a config that validates must be one the policy can render, and
-* two copies of this precedence would drift into a policy with a blank address.
+* Scoped by what search engines actually accept, which is narrower than it looks:
+* Google exposes **no** "request indexing" API (the Search Console button is not in
+* its API, and URL Inspection is read-only), and it removed the sitemap ping
+* endpoint in 2023. So the sanctioned set is: an accurate sitemap, a Search Console
+* sitemap resubmit, an IndexNow ping — which Google does *not* honour but Bing,
+* Yandex, Naver, Seznam and Yep do — and a read-only inspection pass to find out
+* what Google actually did.
 *
-* Note every candidate but the first now lives in `organization`, and the first
-* (`site.legal.privacyPolicy.privacyOfficer`) still dereferences against
-* `organization.locations` — the officer is a person at the company, named by the
-* site because a company may publish more than one policy.
-*/
-function resolvePrivacyContact(cfg) {
-	const org = cfg.organization;
-	const deref = (c) => {
-		if (c == null) return void 0;
-		if (typeof c !== "string") return c;
-		const loc = org?.locations?.[c];
-		return loc && {
-			email: loc.email,
-			phone: loc.phone,
-			address: loc.address
-		};
-	};
-	return [
-		deref(cfg.site.legal?.privacyPolicy?.privacyOfficer),
-		deref(org?.contact),
-		deref(org?.primaryLocation),
-		org && {
-			email: org.email,
-			phone: org.phone,
-			address: org.address
-		}
-	].find((c) => c != null && (c.email != null || c.address != null));
-}
-/**
-* Resolve a design-system theme by following its `extends` chain and deep-merging
-* base → child (child wins; arrays replace wholesale, correct for token overrides).
-* Throws on unknown keys or an `extends` cycle. The result is a plain
-* `DesignSystem` (validate it against `DesignSystemSchema` for completeness).
+* Facts only, the same rule the legal block follows: this records what the site has
+* (a key, a property, which pages matter), never what to say about it.
 */
-function resolveTheme(designSystem, key) {
-	const chain = [];
-	const seen = /* @__PURE__ */ new Set();
-	let cur = key;
-	while (cur != null) {
-		if (seen.has(cur)) throw new Error(`extends cycle in designSystem at "${cur}"`);
-		seen.add(cur);
-		const entry = designSystem[cur];
-		if (entry == null) throw new Error(`designSystem theme "${cur}" not found`);
-		chain.unshift(entry);
-		cur = entry.extends;
-	}
-	const out = {};
-	for (const entry of chain) {
-		const { extends: _e, displayName: _d, ...ds } = entry;
-		deepMerge(out, ds);
-	}
-	return out;
-}
+const IndexNowSchema = z.object({
+	key: desc(z.string().check(z.regex(/^[a-zA-Z0-9-]{8,128}$/)), "IndexNow key (8–128 chars, hex is conventional). NOT a secret — it is served publicly at `keyLocation` so the engine can verify you own the host. Generate one with `vitops search notify --new-key`."),
+	keyLocation: desc(z.optional(z.url()), "Absolute URL of the key file. Defaults to `<canonical>/<key>.txt`; set it only when the file lives elsewhere."),
+	endpoint: desc(z.optional(z.url()), "IndexNow endpoint (default `https://api.indexnow.org/indexnow`). Any participating engine shares submissions with the rest, so one is normally enough.")
+});
+const SearchConsoleSchema = z.object({
+	siteUrl: desc(z.string(), "The property exactly as Search Console identifies it — `sc-domain:acme.ca` for a domain property, or the URL-prefix form `https://acme.ca/`. A mismatch here is a 403, not a \"not found\"."),
+	resubmitSitemap: desc(z.optional(z.boolean()), "Re-submit the sitemap through the Search Console API on each notify (default true when `searchConsole` is set). This is the automated equivalent of the manual resubmit in the UI.")
+});
+const IndexingSchema = z.object({
+	sitemapUrl: desc(z.optional(z.url()), "The sitemap to submit and to diff for changed URLs. Defaults to `<canonical>/sitemap-index.xml`."),
+	indexNow: desc(z.optional(IndexNowSchema), "IndexNow submission (Bing, Yandex, Naver, Seznam, Yep — not Google). Omit to skip the channel."),
+	searchConsole: desc(z.optional(SearchConsoleSchema), "Google Search Console property. Needs a credential at run time — either a service account in `VITOPS_GSC_SERVICE_ACCOUNT` / `GOOGLE_APPLICATION_CREDENTIALS`, or the user OAuth credential `vitops search setup` uses (`VITOPS_GOOGLE_CLIENT_ID` / `_CLIENT_SECRET` / `_REFRESH_TOKEN`). The service account wins when both are set. Never put a key in this file."),
+	priorityUrls: desc(z.optional(z.array(z.url())), "The pages whose indexing actually matters. `vitops search notify --check` inspects these and exits non-zero if Google has not indexed one. Kept explicit because URL Inspection is quota-bound (2000/day), so checking every page is neither affordable nor informative.")
+});
 /**
-* Normalise the two `designSystem` shorthands to the canonical
-* `{ themes: { … } }` shape.
+* The ad platforms `vitops ads` can link a site to.
 *
-* Both are keyed off what CANNOT be a theme name in the other reading:
-*  - `colors` → a bare `DesignSystem` was written inline.
-*  - `themes` → already canonical.
-*  - neither → the legacy bare theme map, from before the block gained
-*    system-wide fields. Every config authored against the old schema takes this
-*    branch, which is what keeps the change forgiving at runtime even though the
-*    published JSON Schema moved.
+* A closed enum, mirroring `AD_PROVIDER_KEYS` in `@getvitops/utils/ads` — that
+* module owns what each platform *can do* (whether it verifies a domain, what its
+* tag is, which click ID it stamps), this owns what a config may *say*. Mirrored
+* rather than derived because a `z.enum` needs literals to reach the published JSON
+* Schema; `config.test.ts` asserts the two lists are the same set, so a provider
+* added to one and not the other fails the build rather than silently getting no
+* verification step and no tag.
 */
-function normaliseDesignSystem(raw) {
-	const ds = raw.designSystem;
-	if (ds == null || typeof ds !== "object") return;
-	if ("themes" in ds) return;
-	raw.designSystem = "colors" in ds ? { themes: { default: ds } } : { themes: ds };
-}
+const AD_PROVIDERS = [
+	"google",
+	"meta",
+	"linkedin",
+	"reddit",
+	"tiktok",
+	"microsoft",
+	"pinterest",
+	"snapchat"
+];
+const AdProviderSchema = z.enum(AD_PROVIDERS);
 /**
-* Resolve a raw (already-parsed) config into a validated `Config`:
-*  1. strip YAML nulls,
-*  2. normalise the `designSystem` shorthands to `{ themes: … }`,
-*  3. apply the active A/B variant's `overrides` (by `siteEnv`),
-*  4. validate (shape + cross-field).
-* Pure — no YAML/env access. A loader supplies `siteEnv`.
-*
-* Steps 2 and 3 are in this order deliberately. Normalising first means an
-* `abTesting` override always addresses the canonical shape
-* (`designSystem.themes.<name>`), whatever shorthand the base config used. With
-* the merge first, an override's key path depended on how the base happened to be
-* written — so the same patch hit a different place in two configs that were
-* otherwise equivalent.
+* One ad property this site is linked to.
 *
-* The A/B lookup reads `site.environments` / `site.abTesting`, and the overrides
-* still deep-merge at the **root** — a variant patches whichever section it names,
-* which is what lets one target `designSystem` and another `site.seo`.
+* Facts, not prose — the same rule the legal block follows. This records *which*
+* account and *which* tag id, and the platform capability table decides what can be
+* done about them. It is also what finally lets the rest of the toolchain see an ad
+* pixel: the generated cookie notice discloses its cookies, `vitops ads lint`
+* checks its click ID is captured, and the consent gate is handed the cookie names
+* to clear on revoke. A pixel pasted into a template is invisible to all three.
 */
-function resolveConfig(input, siteEnv = "production") {
-	const raw = stripNulls(input);
-	normaliseDesignSystem(raw);
-	const site = raw.site;
-	const envConfig = (site?.environments)?.[siteEnv];
-	if (envConfig?.variant) {
-		const overrides = (site?.abTesting)?.variants?.[envConfig.variant]?.overrides;
-		if (overrides) {
-			normaliseDesignSystem(overrides);
-			deepMerge(raw, overrides);
-		}
-	}
-	const result = validateConfig(raw);
-	if (!result.ok) {
-		const msg = result.errors.map((e) => `  ${e.path.join(".") || "<root>"}: ${e.message}`).join("\n");
-		throw new Error(`Invalid config:\n${msg}`);
-	}
-	return result.data;
-}
+const AdPropertySchema = z.object({
+	accountId: desc(z.optional(z.string()), "The advertising account as the platform shows it — Google Ads customer ID, Meta ad account, LinkedIn partner ID, Reddit advertiser ID. For LinkedIn this is also the Insight Tag id; everywhere else the tag id is `pixelId`."),
+	pixelId: desc(z.optional(z.string()), "The tag/pixel ID the browser snippet initialises — Meta pixel, TikTok pixel, Reddit pixel, Microsoft UET tag ID, Pinterest tag ID, Snap pixel, or the Google Ads conversion ID (`AW-…`, which is NOT the customer ID)."),
+	conversionLabel: desc(z.optional(z.string()), "Google Ads only: the conversion action label paired with the `AW-…` conversion ID."),
+	domain: desc(z.optional(z.string()), "Bare hostname to verify with this platform. Defaults to the host of `domains.canonical` — set it only when the ad account is verified against a different domain."),
+	domainVerification: desc(z.optional(z.string()), "The verification token from the platform UI, for the platforms that verify by DNS TXT (Meta, TikTok, Pinterest, Snapchat). `vitops ads setup` prompts for it and writes it here on first run. NOT a secret — it is published in DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key. A value containing `=` is used as the whole record, which is the escape hatch if a platform changes its prefix."),
+	category: desc(z.optional(z.enum(["marketing", "analytics"])), "Consent category the tag waits on (default `marketing`). An ad pixel is advertising by default; `analytics` is for a site using one purely for its own measurement."),
+	enabled: desc(z.optional(z.boolean()), "Set false to keep the property on record without emitting its tag.")
+});
 /**
-* Is this raw config a full `Config` rather than a bare `design-system.json`?
-*
-* The discriminator is **total**, not a heuristic, and both halves are load-
-* bearing: `ConfigSchema` cannot validate without a `designSystem` (it is a
-* required key), and `DesignSystemSchema` is strict, so a `designSystem` key in a
-* design system is an `unrecognized_keys` error. No document can be read as both,
-* and no document that is neither reaches here without failing validation anyway.
+* Which template set the generated legal documents are written against. This is
+* a closed enum rather than a free string because an unrecognised value would
+* otherwise silently fall back to the wrong body of law; `validateConfig` rejects
+* anything without a registered template. Add a member here and a matching entry
+* in `legal/templates/index.ts` — the two are checked against each other.
+*/
+const JURISDICTIONS = ["ca"];
+const JurisdictionSchema = z.enum(JURISDICTIONS);
+/**
+* The country each template set frames cross-border transfers as *leaving*.
 *
-* The restructure did not weaken this: `designSystem` stayed at the root
-* precisely so the discriminator kept working unchanged.
+* A jurisdiction's own country is not a transfer, so this is what filters the
+* disclosure lists — without it, `country: "Canada"` renders the incoherent
+* "outside of Canada, including Canada".
 *
-* Deliberately shape-based rather than filename-based: consumers name this file
-* whatever suits them (`company.json`, `site.json`, `vitops.config.json`), and a
-* rule keyed to a name would silently stop working the moment someone renamed it.
+* It belongs to the **jurisdiction**, not to `organization.address`: a `ca` policy
+* says "outside of Canada" even for a business incorporated elsewhere. (The
+* address drives a different sentence — the terms' governing-law clause, via
+* `governingCountry`.) `satisfies` makes a new jurisdiction unable to forget it,
+* the same guard style as `TEMPLATES`.
 */
-function isConfig(raw) {
-	return typeof raw === "object" && raw != null && !Array.isArray(raw) && "designSystem" in raw;
-}
+const JURISDICTION_COUNTRIES = { ca: "Canada" };
 /**
-* Resolve a raw config of either kind into the design system to build from.
-*
-* Every entry point that used to take a `design-system.json` goes through this,
-* so a consumer who keeps their tokens inside the larger config points the
-* same option at that file instead of maintaining a second one. The config
-* is handed back too, because the parts of generation that depend on site-level
-* facts (`designSystem.defaultColorScheme`, the legal documents, the icon
-* sprite) would otherwise need the same path declared a second time.
+* A third party that receives personal information. The generator derives the
+* ones it can see (analytics IDs, Turnstile, the deploy platform); this is for
+* the rest, which no other part of the config implies.
 *
-* The returned `designSystem` is **not** validated here — the caller does that,
-* so it can say which file and which theme the errors belong to. Validation of
-* the config itself has already happened (`resolveConfig` throws).
+* Deliberately facts, not prose: the config records *what is true*, the template
+* owns *how it is said*. That keeps a policy correct when the wording changes.
 */
-function resolveInput(raw, opts = {}) {
-	if (!isConfig(raw)) {
-		if (opts.theme != null) throw new Error(`theme "${opts.theme}" was requested, but this is a design-system.json — it holds one design system and no \`themes\` map. Point at a full config to select a theme.`);
-		return { designSystem: raw };
-	}
-	const config = resolveConfig(raw, opts.siteEnv);
-	const themes = config.designSystem?.themes ?? {};
-	const theme = opts.theme ?? config.designSystem?.defaultTheme ?? "default";
-	if (!(theme in themes)) throw new Error(`designSystem.themes has no "${theme}" entry (found: ${Object.keys(themes).join(", ") || "none"})`);
-	return {
-		designSystem: resolveTheme(themes, theme),
-		config,
-		theme
-	};
-}
-/** Strip nulls (YAML `~`/`null`) → undefined so optional fields validate. */
-function stripNulls(obj) {
-	if (obj === null) return void 0;
-	if (Array.isArray(obj)) return obj.map(stripNulls);
-	if (obj && typeof obj === "object") {
-		const result = {};
-		for (const [key, value] of Object.entries(obj)) {
-			const stripped = stripNulls(value);
-			if (stripped !== void 0) result[key] = stripped;
-		}
-		return result;
-	}
-	return obj;
-}
-/** Deep-merge `source` into `target` (in place). Arrays replace wholesale. */
-function deepMerge(target, source) {
-	for (const key of Object.keys(source)) {
-		const s = source[key];
-		const t = target[key];
-		if (s && typeof s === "object" && !Array.isArray(s) && t && typeof t === "object" && !Array.isArray(t)) deepMerge(t, s);
-		else target[key] = s;
-	}
-}
-
-//#endregion
-//#region src/tokens.ts
+const ProcessorStorageSchema = z.object({
+	country: desc(z.string(), "A country or bloc where this provider stores or processes the information, as it should read in a sentence (e.g. \"Canada\", \"the United States\", \"the European Union\"). Naming the jurisdiction the policy is written for is meaningful: it says this information does not leave it."),
+	scope: desc(z.optional(z.string()), "Which information is held there, as a noun phrase that reads after \"in the case of\" (e.g. \"account and sign-in information\", \"mailbox contents\"). Omit when this location holds everything the provider receives — a scoped entry claims LESS than an unscoped one, so omitting it is the safe default.")
+});
+const ProcessorSchema = z.object({
+	name: desc(z.string(), "The provider, as a reader would recognise it (e.g. \"Stripe\")."),
+	purpose: desc(z.string(), "Why they receive it, as a noun phrase that reads after \"for\" (e.g. \"payment processing\")."),
+	country: desc(z.optional(z.string()), "Shorthand for the common case where one country is both where they store it and whose laws reach it: asserts BOTH `storage: [{ country }]` AND `operatorCountry`. Reads inside a sentence (e.g. \"the United States\"). When the two differ — a Canadian region operated by a US company — state `storage` and `operatorCountry` instead; setting this alongside either is rejected."),
+	storage: desc(z.optional(z.array(ProcessorStorageSchema)), "Where the information actually rests. Feeds the \"stored or processed outside of <jurisdiction>\" disclosure and nothing else. Several entries are allowed, each optionally scoped to a category of information — which is what makes a Canadian-region tenant holding identity data in the US expressible."),
+	operatorCountry: desc(z.optional(z.string()), "The jurisdiction that can compel this provider to hand the information over — where it is established, or from which it is controlled. Reads after \"the laws of\" (e.g. \"the United States\"); a bloc is acceptable. A SEPARATE fact from `storage`, because privacy law cares about foreign *access*, not only foreign storage: a Canadian-region service run by a US company is `storage: [{ country: \"Canada\" }]` with `operatorCountry: \"the United States\"`."),
+	privacyUrl: z.optional(z.url())
+});
+const SiteSectionSchema = z.object({
+	defaultLocale: desc(z.string(), "The locale used when none is specified; must be a `locales` key."),
+	locales: desc(z.record(z.string(), LocaleSchema), "Locales the site is published in, keyed by BCP 47 tag (e.g. \"en\", \"fr\")."),
+	domains: desc(z.optional(z.object({
+		canonical: desc(z.url(), "The canonical origin used for absolute URLs and SEO."),
+		aliases: desc(z.optional(z.array(DomainAliasSchema)), "Alias domains and how they redirect to the canonical one.")
+	})), "Canonical domain + redirecting aliases."),
+	dns: desc(z.optional(z.record(z.string(), DnsDomainSchema)), "Desired DNS state per domain (provider, nameservers, records) — declarative reference, not applied automatically."),
+	cloudflare: desc(z.optional(z.record(z.string(), z.unknown())), "Deliberate escape hatch for provider-specific Cloudflare settings — out of scope to model here."),
+	searchConsole: desc(z.optional(z.record(z.string(), SearchConsoleSetupSchema)), "Domains to onboard as Google Search Console *domain properties* via `vitops search setup`, keyed by bare hostname (mirrors `dns`). Credentials come from the environment (CLOUDFLARE_API_TOKEN + the Google OAuth vars) — never in this file."),
+	environments: desc(z.record(z.string(), EnvironmentSchema), "Deploy environments (production, dev, …): URL, API origin, analytics toggle, robots policy, active A/B variant."),
+	abTesting: desc(z.optional(z.object({
+		enabled: z.boolean(),
+		cookieName: z.optional(z.string()),
+		cookieMaxAge: desc(z.optional(z.number().check(z.int(), z.positive())), "Seconds."),
+		splitRatio: desc(z.optional(z.number().check(z.gte(0), z.lte(1))), "Fraction of traffic sent to the variant (0–1)."),
+		variants: desc(z.optional(z.record(z.string(), AbVariantSchema)), "Named variants; each targets an environment and may deep-merge config `overrides`.")
+	})), "A/B testing: cookie-based split plus named variants whose `overrides` patch the config per environment."),
+	fonts: desc(z.optional(z.array(SiteFontSchema)), "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.themes.<theme>.fonts` and reference the same `cssVariable`."),
+	tags: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-tag taxonomy (site-specific; not interpreted by the generator)."),
+	postTypes: desc(z.optional(z.record(z.string(), z.unknown())), "Free-form content-type definitions (site-specific; not interpreted by the generator)."),
+	galleries: desc(z.optional(z.record(z.string(), GallerySchema)), "Named image galleries (title, tags, images with localisable alt/caption)."),
+	testimonials: desc(z.optional(z.record(z.string(), TestimonialGroupSchema)), "Named testimonial groups (quote, name, role, rating, date)."),
+	templates: desc(z.optional(z.record(z.string(), TemplateSchema)), "Named content templates rendered at SSR time: `nav` (menu trees), `form` (field lists + submit), or `nodes` (raw element trees)."),
+	navigation: desc(z.optional(z.object({ activeTemplate: desc(z.optional(z.object({
+		default: desc(z.optional(z.string()), "A `templates` key."),
+		breakpoints: desc(z.optional(z.record(z.string(), z.string())), "Breakpoint name → `templates` key overrides.")
+	})), "Which nav template is active, optionally per breakpoint.") })), "Site navigation settings (which nav template renders where)."),
+	seo: desc(z.optional(z.object({
+		titleTemplate: desc(z.optional(z.string()), "Page-title pattern (e.g. \"%s · Acme\")."),
+		descriptionTemplate: z.optional(z.string()),
+		robots: desc(z.optional(RobotsSchema), "e.g. \"index,follow\" / \"noindex,nofollow\"."),
+		googleSiteVerification: z.optional(z.string()),
+		bingSiteVerification: z.optional(z.string()),
+		openGraph: z.optional(OpenGraphSchema),
+		twitter: z.optional(TwitterSchema),
+		indexing: desc(z.optional(IndexingSchema), "How `vitops search notify` tells search engines about a deploy: which sitemap, IndexNow key, Search Console property, and which pages to verify afterwards.")
+	})), "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification."),
+	analytics: desc(z.optional(z.object({
+		googleAnalyticsId: z.optional(z.string()),
+		plausibleDomain: z.optional(z.string()),
+		googleTagManagerId: z.optional(z.string()),
+		clarityId: desc(z.optional(z.string()), "Microsoft Clarity project ID."),
+		matomo: desc(z.optional(z.object({
+			url: desc(z.string(), "Instance base URL (self-hosted, or `*.matomo.cloud`)."),
+			siteId: desc(z.string(), "Site ID within that instance."),
+			cookies: desc(z.optional(z.boolean()), "Default false — Matomo runs cookieless (`disableCookies`), which is what lets the cookie notice state positively that it sets none.")
+		})), "Matomo instance.")
+	})), "Analytics provider IDs (gated per environment via `environments.<env>.analytics`). Which provider is set is also what the generated privacy policy and cookie notice disclose — see `legal`."),
+	notifications: desc(z.optional(z.object({ email: desc(z.optional(z.union([z.email(), z.object({
+		provider: desc(z.literal("cloudflare"), "Delivery provider. Only Cloudflare Email Sending is implemented; the field is stated so adding another is additive."),
+		to: desc(z.optional(z.email()), "Recipient. Defaults to the primary location’s `email`, then the first location that has one."),
+		from: desc(z.optional(z.email()), "Sender. Defaults to `noreply@<domains.canonical>`. Its domain must be onboarded (`wrangler email sending enable <domain>`) or every send fails."),
+		fromName: desc(z.optional(z.string()), "Display name on the From header. Defaults to `organization.name`."),
+		replyTo: desc(z.optional(z.email()), "Reply-To header."),
+		binding: desc(z.optional(z.string()), "Workers `send_email` binding name (default `EMAIL`). Set it when using a restricted binding.")
+	})])), "Where conversion notifications are e-mailed. A bare address is shorthand for `{ provider: \"cloudflare\", to }`.") })), "Where site notifications (form submissions, tracked calls) are sent. TODO: `sms` and `persist` channels — only `email` is implemented."),
+	tracking: desc(z.optional(z.object({
+		enabled: desc(z.optional(z.boolean()), "Capture ad click IDs and UTMs from the landing URL into the `_ac` cookie, for attributing conversions."),
+		category: desc(z.optional(z.enum(["marketing", "analytics"])), "Consent category the `_ac` cookie waits on (default `marketing`). It is a 90-day identifier tying a visitor to the ad that brought them, so it is only written once this category is granted — and asking for it is what raises the banner."),
+		platforms: desc(z.optional(z.array(z.string())), "Informational list of ad platforms in use. Capture recognises every known click-ID parameter regardless.")
+	})), "Ad-click attribution for conversion tracking."),
+	ads: desc(z.optional(z.partialRecord(AdProviderSchema, AdPropertySchema)), "Ad properties this site is linked to, keyed by platform. Read by `vitops ads setup` (ensure the DNS verification record), `vitops ads tags` (emit the consent-gated pixel), and the generated cookie notice (disclose what each pixel stores). Credentials never live here — the DNS write uses CLOUDFLARE_API_TOKEN from the environment."),
+	security: desc(z.optional(z.object({ turnstile: z.optional(z.object({ siteKey: desc(z.optional(z.string()), "Cloudflare Turnstile site key (public).") })) })), "Security integrations (bot protection)."),
+	legal: desc(z.optional(z.object({
+		jurisdiction: desc(z.optional(JurisdictionSchema), "Which legal template set the generated documents use. Default `ca`."),
+		privacyPolicy: z.optional(z.object({
+			enabled: z.boolean(),
+			url: z.optional(z.url()),
+			lastUpdated: z.optional(IsoDate),
+			privacyOfficer: desc(z.optional(ContactConfigSchema), "Who privacy requests go to. Falls back to `contact`, then `primaryLocation`."),
+			retention: desc(z.optional(z.string()), "How long personal information is kept, in prose (e.g. \"24 months after last contact\")."),
+			processors: desc(z.optional(z.array(ProcessorSchema)), "Third parties that receive personal information and cannot be inferred from the rest of the config (payment processors, CRMs, mail senders). Known providers implied by `analytics`, `security` and `deployment` are added automatically — list only the rest.")
+		})),
+		termsOfService: z.optional(z.object({
+			enabled: z.boolean(),
+			url: z.optional(z.url()),
+			lastUpdated: z.optional(z.nullable(IsoDate)),
+			governingLaw: desc(z.optional(z.string()), "Governing-law clause, in prose (e.g. \"the Province of Ontario\"). Defaults from the contact address.")
+		})),
+		cookieConsent: z.optional(z.object({
+			enabled: z.boolean(),
+			type: desc(z.optional(z.enum(["opt-in", "opt-out"])), "Consent model."),
+			position: z.optional(z.enum([
+				"top",
+				"bottom",
+				"center"
+			])),
+			categories: z.optional(z.array(z.string()))
+		}))
+	})), "Legal pages: which documents exist, where they live, and the facts the generated prose asserts."),
+	icons: desc(z.optional(z.looseObject({
+		ui: desc(z.optional(z.string()), "Icon set used for UI chrome (e.g. \"lucide\", \"ph\")."),
+		brand: desc(z.optional(z.string()), "Icon set used for brand marks."),
+		weight: desc(z.optional(z.string()), "Weight for suffix-weighted sets like Phosphor (\"regular\" | \"bold\" | \"duotone\" | \"fill\" | \"light\" | \"thin\"). Ignored by sets that split weights across collections, e.g. Font Awesome."),
+		sprite: desc(z.optional(z.boolean()), "Emit an SVG sprite (icons.svg) alongside the stylesheet, for consumers that cannot run an icon integration (Bricks/WordPress, EmDash renderers)."),
+		semantic: desc(z.optional(z.array(z.string())), "Named semantic icons to include."),
+		"fa7-solid": z.optional(z.array(z.string())),
+		"fa7-regular": z.optional(z.array(z.string())),
+		"fa7-light": z.optional(z.array(z.string())),
+		"fa7-thin": z.optional(z.array(z.string())),
+		"fa7-brands": z.optional(z.array(z.string())),
+		"simple-icons": z.optional(z.array(z.string())),
+		"material-symbols": z.optional(z.array(z.string())),
+		lucide: z.optional(z.array(z.string())),
+		ph: z.optional(z.array(z.string()))
+	})), "Icon sets and the specific icons to bundle from each (keys are iconify collection names)."),
+	favicon: desc(z.optional(z.object({
+		source: desc(z.string(), "Source image (SVG/PNG) the favicon set is generated from."),
+		lowResSource: desc(z.optional(z.string()), "Alternate source for small raster sizes (16/32px) when the main source scales down poorly."),
+		name: desc(z.optional(z.string()), "App name for the generated web manifest. Setting this AND `themeColor` is what makes the site installable: together they emit `site.webmanifest` (with `display: \"standalone\"`) and link it. Neither alone does anything. A marketing site that does not want a browser offering to install it should leave one of them unset."),
+		themeColor: desc(z.optional(z.string()), "Browser UI colour, emitted as `<meta name=\"theme-color\">` on every page — so it applies with or without a manifest. Note it is also half the manifest switch: see `name`."),
+		backgroundColor: desc(z.optional(z.string()), "Background composited under the OPAQUE generated icons — `apple-touch-icon.png` and the maskable `icon-mask.png` — which are produced whether or not there is a manifest. Defaults to white, so a dark logo on a transparent source needs this set. It is also the manifest `background_color` when one is emitted, but it is not manifest-only.")
+	})), "Favicon/PWA asset generation (consumed by `@getvitops/utils` favicon tooling)."),
+	deployment: desc(z.optional(z.object({
+		platform: z.optional(z.string()),
+		buildCommand: z.optional(z.string()),
+		deployCommand: z.optional(z.string()),
+		outputDirectory: z.optional(z.string()),
+		type: z.optional(z.string())
+	})), "How the site is built and deployed (platform, commands, output directory) — informational for tooling.")
+});
+const OrganizationSectionSchema = z.extend(OrganizationSchema, {
+	contact: desc(z.optional(ContactConfigSchema), "Primary contact: either a `locations` key (string reference) or an inline name/email/phone/address object."),
+	primaryLocation: desc(z.optional(z.string()), "The main `locations` key (for JSON-LD and defaults)."),
+	locations: desc(z.optional(z.record(z.string(), LocationSchema)), "Physical locations (schema.org LocalBusiness): address, geo, opening hours, service area."),
+	services: desc(z.optional(z.record(z.string(), ServiceSchema)), "Services offered (schema.org Service/Offer): name, description, slug, price offers."),
+	links: desc(z.optional(z.object({
+		googleMaps: z.optional(z.url()),
+		instagram: z.optional(z.url()),
+		facebook: z.optional(z.url()),
+		x: z.optional(z.url()),
+		linkedin: z.optional(z.url()),
+		youtube: z.optional(z.url()),
+		github: z.optional(z.url())
+	})), "Public profile URLs (also feed JSON-LD `sameAs` via `organization.sameAs`).")
+});
+const ConfigSchema = z.object({
+	designSystem: DesignSystemBlock,
+	organization: desc(z.optional(OrganizationSectionSchema), "The company: schema.org Organization details for JSON-LD (name, legalName, logo, tax IDs, sameAs), plus its contact, physical locations, services and public profiles. These stay true across sites — several sites can share one `organization` and differ only in `site`."),
+	site: desc(SiteSectionSchema, "This published site: locales, domains, environments, content templates, SEO, analytics, legal documents, icons, favicon and deployment. Facts about a *presentation* of the organization rather than the organization itself.")
+});
+const CONFIG_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/config.schema.json";
+/** The published JSON Schema (draft-2020-12), derived from the zod schema. */
+const configJsonSchema = {
+	$id: CONFIG_SCHEMA_URL,
+	...z.toJSONSchema(ConfigSchema, { target: "draft-2020-12" })
+};
+const issue = (path, message) => ({
+	code: "custom",
+	path,
+	message
+});
 /**
-* Palette expansion + semantic colour tokens.
-*
-* A palette hue is authored one of two ways:
-*   • `{ seed, anchors? }` — an 11-step numeric scale (50…950) generated in
-*     OKLCH via @getvitops/utils/color. Lightness comes from the shared
-*     `LIGHTNESS_LADDER`; the seed (and any anchors) are reproduced verbatim at
-*     their steps.
-*   • `{ tones }` — a fixed brand kit: authored tones placed verbatim at their
-*     nearest steps + tinted endpoints; nothing else is invented (strict kits).
-*
-* **The grammar.** Every role gets tokens named `--color-<target>-<role>[-<variant>]`,
-* where target ∈ bg | text | icon | border. Putting the target *inside* the name is
-* the point: `--color-bg-danger-muted` and `--color-text-danger-muted` are distinct
-* tokens, so the two axes that used to collide over one `<family>-<role>-<modifier>
-* ` namespace cannot any more. The utility class is the token name minus `--color-`.
-*
-* Variants are ordinal — xx-muted < x-muted < muted < (bare) < bold < x-bold —
-* and the tables are **sparse**: a target only emits the cells that are actually
-* viable. `bold` means "more emphatic than the role's default in the current
-* appearance", not "darker"; the appearance decides polarity.
-*
-* Roles come in two kinds (declared in `colors.roles`):
-*   • `surface` — a page/panel colour. Has a bare `bg-<role>` plus the full
-*     emphasis range and the complete text scale.
-*   • `chromatic` (default) — a signal colour. Backgrounds split into *tints*
-*     (`bg-<role>-x-muted` / `-muted`) and *solids* (`bg-<role>-solid[-bold|-x-bold]`);
-*     there is deliberately **no bare `bg-<role>`**, because "how loud?" is a
-*     question the author has to answer.
+* Where each key of the old flat config now lives.
 *
-* Dark mode re-points which step each token reads; the solid family and the
-* `text-on-<role>` foreground computed against it stay mode-stable, so a filled
-* button keeps its identity across appearances.
-*/
-const NUMERIC_STEPS = [
-	"50",
-	"100",
-	"200",
-	"300",
-	"400",
-	"500",
-	"600",
-	"700",
-	"800",
-	"900",
-	"950"
-];
-/**
-* Lightness of each numeric step. Re-exported from the engine's ladder rather
-* than restated — there used to be three copies of this curve (here, the engine,
-* and the linter) and they were free to drift.
+* This exists so the restructure fails with a sentence a reader can act on. Zod
+* reports a flat config as a dozen separate `unrecognized_keys` issues plus a
+* missing required `site` — an accurate description of the document that teaches
+* nobody where anything went. Checked first, and it short-circuits: once we know
+* the document is the old shape, every other error is downstream noise.
 */
-const STEP_L = Object.fromEntries(NUMERIC_STEPS.map((s) => [s, LIGHTNESS_LADDER[Number(s)]]));
-const isHex = (v) => v.startsWith("#");
-const toOklchStr = (v) => {
-	if (!isHex(v)) return v;
-	const { l, c, h } = hexToOklch(v);
-	return `oklch(${(l * 100).toFixed(2)}% ${c.toFixed(4)} ${h.toFixed(2)})`;
+const MOVED_KEYS = {
+	defaultLocale: "site",
+	locales: "site",
+	domains: "site",
+	dns: "site",
+	cloudflare: "site",
+	environments: "site",
+	abTesting: "site",
+	fonts: "site",
+	tags: "site",
+	postTypes: "site",
+	galleries: "site",
+	testimonials: "site",
+	templates: "site",
+	navigation: "site",
+	seo: "site",
+	analytics: "site",
+	notifications: "site",
+	tracking: "site",
+	security: "site",
+	legal: "site",
+	icons: "site",
+	favicon: "site",
+	deployment: "site",
+	contact: "organization",
+	primaryLocation: "organization",
+	locations: "organization",
+	services: "organization",
+	links: "organization"
 };
-const nearestStep = (l) => NUMERIC_STEPS.reduce((best, s) => Math.abs(l - STEP_L[s]) < Math.abs(l - STEP_L[best]) ? s : best);
 /**
-* Claim `step` for `value`, refusing to overwrite a step another colour already
-* took.
+* Detect the pre-3.0 flat shape and name the moves.
 *
-* Silently dropping one of two colliding tones is the worst outcome: the palette
-* still builds, and the tone the author cared about is simply gone. The record
-* form (`tones: { "600": "#…", "700": "#…" }`) is the escape hatch, so the error
-* points at it.
+* Keyed on a moved key sitting at the ROOT, not on the absence of `site` — a
+* config that simply forgot `site` should get the ordinary "required" error, and
+* a partially-migrated one (some keys moved, some not) is exactly the case worth
+* catching loudly.
 */
-function claim(into, step, value, hueLabel, what) {
-	const taken = into[step];
-	if (taken != null && taken !== value) throw new Error(`palette hue "${hueLabel}": ${what} ${value} and ${taken} both map to step ${step}. Key them explicitly, e.g. { "${step}": "${taken}", "${Number(step) + 100}": "${value}" }.`);
-	into[step] = value;
+function migrationIssues(raw) {
+	if (typeof raw !== "object" || raw == null || Array.isArray(raw)) return [];
+	const found = Object.keys(raw).filter((k) => k in MOVED_KEYS);
+	if (found.length === 0) return [];
+	return [issue([], `this is the pre-3.0 flat site config. The top level is now three sections — \`designSystem\`, \`organization\`, \`site\` — and these keys moved:
+${found.map((k) => `  ${k} → ${MOVED_KEYS[k]}.${k}`).join("\n")}\n\`designSystem\` and the fields already under \`organization\` stay where they are.`)];
 }
-function expandSeeded(input, hueLabel) {
-	const anchors = {};
-	for (const [key, value] of Object.entries(input.anchors ?? {})) claim(anchors, NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(value).l), toOklchStr(value), hueLabel, "anchors");
-	const seedStep = nearestStep(hexToOklch(input.seed).l);
-	anchors[seedStep] ??= toOklchStr(input.seed);
-	const scale = generateOklchPalette(anchors);
-	const numeric = {};
-	for (const s of NUMERIC_STEPS) if (scale[s] != null) numeric[s] = oklchStringToHex(scale[s]);
-	return {
-		numeric,
-		deviations: deviationsFor(anchors)
+/**
+* Validate a raw (already parsed) config: shape via zod, then the cross-field
+* integrity that JSON Schema can't express (referential keys, extends acyclicity).
+* These live only here — the published JSON Schema enforces shape, not integrity.
+*/
+function validateConfig(input) {
+	const migration = migrationIssues(input);
+	if (migration.length) return {
+		ok: false,
+		data: void 0,
+		errors: migration
+	};
+	const parsed = z.safeParse(ConfigSchema, input);
+	if (!parsed.success) return {
+		ok: false,
+		data: void 0,
+		errors: parsed.error.issues
+	};
+	const cfg = parsed.data;
+	const site = cfg.site;
+	const org = cfg.organization;
+	const errors = [];
+	const has = (m, k) => !!m && k in m;
+	if (!has(site.locales, site.defaultLocale)) errors.push(issue(["site", "defaultLocale"], `defaultLocale "${site.defaultLocale}" is not in locales`));
+	const themes = cfg.designSystem?.themes ?? {};
+	const defaultTheme = cfg.designSystem?.defaultTheme;
+	if (!has(themes, "default") && defaultTheme == null) errors.push(issue(["designSystem", "themes"], "themes must include a \"default\" entry"));
+	if (defaultTheme != null && !has(themes, defaultTheme)) errors.push(issue(["designSystem", "defaultTheme"], `defaultTheme "${defaultTheme}" is not in designSystem.themes`));
+	for (const [key, entry] of Object.entries(themes)) if (entry.extends != null && !has(themes, entry.extends)) errors.push(issue([
+		"designSystem",
+		"themes",
+		key,
+		"extends"
+	], `extends "${entry.extends}" is not a themes key`));
+	for (const key of Object.keys(themes)) try {
+		resolveTheme(themes, key);
+	} catch (e) {
+		errors.push(issue([
+			"designSystem",
+			"themes",
+			key
+		], e.message));
+	}
+	if (org?.primaryLocation != null && !has(org.locations, org.primaryLocation)) errors.push(issue(["organization", "primaryLocation"], `primaryLocation "${org.primaryLocation}" is not in organization.locations`));
+	if (typeof org?.contact === "string" && !has(org.locations, org.contact)) errors.push(issue(["organization", "contact"], `contact "${org.contact}" is not an organization.locations key`));
+	for (const [name, v] of Object.entries(site.abTesting?.variants ?? {})) if (!has(site.environments, v.environment)) errors.push(issue([
+		"site",
+		"abTesting",
+		"variants",
+		name,
+		"environment"
+	], `environment "${v.environment}" is not in site.environments`));
+	for (const [i, a] of (site.domains?.aliases ?? []).entries()) if (a.environment != null && !has(site.environments, a.environment)) errors.push(issue([
+		"site",
+		"domains",
+		"aliases",
+		i,
+		"environment"
+	], `environment "${a.environment}" is not in site.environments`));
+	const templates = site.templates;
+	const at = site.navigation?.activeTemplate;
+	if (at?.default != null && !has(templates, at.default)) errors.push(issue([
+		"site",
+		"navigation",
+		"activeTemplate",
+		"default"
+	], `template "${at.default}" is not in site.templates`));
+	for (const [bp, tpl] of Object.entries(at?.breakpoints ?? {})) if (!has(templates, tpl)) errors.push(issue([
+		"site",
+		"navigation",
+		"activeTemplate",
+		"breakpoints",
+		bp
+	], `template "${tpl}" is not in site.templates`));
+	const privacy = site.legal?.privacyPolicy;
+	/**
+	* `country` is shorthand for BOTH `storage` and `operatorCountry`, so combining it
+	* with either is genuinely ambiguous — is the shorthand narrowing the explicit
+	* fact, or adding to it? Both readings are plausible and they make *contradictory
+	* legal claims*, so this is rejected rather than resolved by a silent rule.
+	*
+	* Checked unconditionally, not gated on `privacy.enabled`: the fact is wrong
+	* either way, and a document turned on later shouldn't surface it for the first
+	* time. Here rather than as a `z.refine` on the schema because parse-time
+	* rejection would make `resolveConfig` throw on the `vitops legal` path, which
+	* has no formatting for a zod issue — `validateConfig` is where every other
+	* cross-field legal requirement already lives, and it prints `path: message`.
+	*/
+	for (const [i, p] of (privacy?.processors ?? []).entries()) if (p.country != null && (p.storage != null || p.operatorCountry != null)) errors.push(issue([
+		"site",
+		"legal",
+		"privacyPolicy",
+		"processors",
+		i,
+		"country"
+	], `processor "${p.name}": \`country\` is shorthand for BOTH \`storage\` and \`operatorCountry\`, so combining it with either makes the narrower claim ambiguous — drop \`country\` and state the two facts, or drop the two and keep the shorthand`));
+	if (typeof privacy?.privacyOfficer === "string" && !has(org?.locations, privacy.privacyOfficer)) errors.push(issue([
+		"site",
+		"legal",
+		"privacyPolicy",
+		"privacyOfficer"
+	], `privacyOfficer "${privacy.privacyOfficer}" is not an organization.locations key`));
+	if (privacy?.enabled) {
+		if (resolvePrivacyContact(cfg) == null) errors.push(issue([
+			"site",
+			"legal",
+			"privacyPolicy"
+		], "privacyPolicy.enabled requires a contact for privacy requests — set site.legal.privacyPolicy.privacyOfficer, organization.contact, or organization.email/address"));
+		if (site.domains?.canonical == null) errors.push(issue([
+			"site",
+			"legal",
+			"privacyPolicy"
+		], "privacyPolicy.enabled requires site.domains.canonical — the policy states where information is held"));
+	}
+	const indexing = site.seo?.indexing;
+	if (indexing != null && site.domains?.canonical == null) {
+		if (indexing.sitemapUrl == null) errors.push(issue([
+			"site",
+			"seo",
+			"indexing",
+			"sitemapUrl"
+		], "site.seo.indexing needs site.domains.canonical to derive the sitemap URL — set one, or state sitemapUrl explicitly"));
+		if (indexing.indexNow != null && indexing.indexNow.keyLocation == null) errors.push(issue([
+			"site",
+			"seo",
+			"indexing",
+			"indexNow",
+			"keyLocation"
+		], "site.seo.indexing.indexNow needs site.domains.canonical to derive the key location — set one, or state keyLocation explicitly"));
+	}
+	for (const [provider, entry] of Object.entries(site.ads ?? {})) {
+		if (entry == null) continue;
+		const platform = AD_PLATFORMS[provider];
+		const at = [
+			"site",
+			"ads",
+			provider
+		];
+		if (entry.domainVerification != null && platform.verification.method === "none") errors.push(issue([...at, "domainVerification"], `${platform.name} has no domain verification — ${platform.verification.reason ?? "nothing verifies a domain there"}. Remove the token; linking is the tag and the account id.`));
+		if (entry.domainVerification != null && entry.domain == null && site.domains?.canonical == null) errors.push(issue([...at, "domain"], `site.ads.${provider}.domainVerification needs a domain to put the record on — set site.domains.canonical, or state site.ads.${provider}.domain explicitly`));
+		if (entry.accountId == null && entry.pixelId == null) errors.push(issue(at, `site.ads.${provider} identifies nothing — set accountId (the advertising account) and/or pixelId (the tag: ${platform.tag.needs} is what its snippet needs)`));
+	}
+	if (errors.length) return {
+		ok: false,
+		data: void 0,
+		errors
 	};
-}
-function expandTones(input, hueLabel) {
-	const entries = Array.isArray(input.tones) ? input.tones.map((hex) => [null, hex]) : Object.entries(input.tones).map(([k, hex]) => [k, hex]);
-	const placed = {};
-	for (const [key, hex] of entries) claim(placed, key != null && NUMERIC_STEPS.includes(key) ? key : nearestStep(hexToOklch(hex).l), hex, hueLabel, "tones");
-	const numeric = {};
-	for (const [step, hex] of Object.entries(placed)) numeric[step] = hex;
-	const ends = tintedEndpoints(hexToOklch(entries[0]?.[1] ?? "#808080").h);
-	numeric["50"] ??= ends.light;
-	numeric["950"] ??= ends.dark;
 	return {
-		numeric,
-		sparse: true,
-		deviations: deviationsFor(placed)
+		ok: true,
+		data: cfg,
+		errors: []
 	};
 }
-/** How far each pinned colour sits from its step's ladder lightness. */
-function deviationsFor(pinned) {
-	const out = {};
-	for (const [step, value] of Object.entries(pinned)) out[step] = (isHex(value) ? hexToOklch(value).l : hexToOklch(oklchStringToHex(value)).l) - STEP_L[step];
-	return out;
-}
-/** Snap to the nearest AVAILABLE numeric step (sparse kits). */
-function snap(numeric, want) {
-	if (numeric[want] != null) return want;
-	return NUMERIC_STEPS.filter((s) => numeric[s] != null).reduce((best, s) => Math.abs(STEP_L[s] - STEP_L[want]) < Math.abs(STEP_L[best] - STEP_L[want]) ? s : best);
-}
-/** Expand every palette hue into its numeric scale. */
-function expandPalette(raw) {
-	const out = {};
-	for (const [name, entry] of Object.entries(raw)) {
-		const e = entry;
-		if (typeof e?.seed === "string") out[name] = expandSeeded(e, name);
-		else if (e?.tones != null) out[name] = expandTones(e, name);
-		else throw new Error(`palette hue "${name}" must have a "seed" or "tones"`);
-	}
-	return out;
-}
-/**
-* Warn about pinned colours that sit noticeably off the ladder. Not an error:
-* the author asked for that exact colour and gets it. But at ~0.03 L the hue
-* starts reading visibly heavier or lighter than its siblings at that step, and
-* that is the class of drift the fixed ladder exists to prevent.
-*/
-const LADDER_TOLERANCE = .03;
-function ladderWarnings(palette) {
-	const warnings = [];
-	for (const [hue, expanded] of Object.entries(palette)) for (const [step, deviation] of Object.entries(expanded.deviations ?? {})) {
-		if (Math.abs(deviation) <= .03) continue;
-		const dir = deviation > 0 ? "lighter" : "darker";
-		warnings.push(`colors.palette.${hue}: the colour pinned at step ${step} is ${Math.abs(deviation).toFixed(3)} ${dir} than the shared lightness ladder — this hue will read ${dir} than others at ${step}. Legal, but move it to a neighbouring step if that wasn't intended.`);
-	}
-	return warnings;
-}
 /**
-* Gamut mapping nudges lightness by a hair, so an exact `<` comparison would
-* report rounding as an inversion. Well below any deviation a person could see.
-*/
-const MONOTONIC_EPSILON = .001;
-/**
-* Ramps whose lightness does not fall monotonically from 50 to 950.
+* Resolve who privacy requests go to: the explicit privacy officer, else the
+* organization's contact, else its primary location, else the organization itself.
 *
-* A ramp built from the ladder alone cannot invert — only pinned colours (a seed,
-* an `anchor`, a `tones` entry) can, because they are the one thing allowed off
-* it. `ladderWarnings` will not catch it: it compares each pinned step against
-* *its own* ladder rung, never against its neighbours, so it reports the wrong
-* defect ("reads darker than others at 600") while the real problem is that 600
-* is darker than 700. And since `LADDER_TOLERANCE` is 0.03 — the same size as the
-* ladder's own 50→100 gap — two anchors can each sit within tolerance and still
-* invert, with no warning at all.
+* Exported because `validateConfig` and the legal-document derivation must agree
+* on it exactly — a config that validates must be one the policy can render, and
+* two copies of this precedence would drift into a policy with a blank address.
 *
-* This is an error rather than a warning because the rest of the system assumes
-* the order: `snap` picks the nearest step by ladder lightness, the mode-stable
-* solid family hard-codes 600/700/800 as increasingly dark, and both dark tables
-* re-point steps on the same assumption. An inverted ramp therefore runs hover
-* states backwards — the failure the fixed ladder was introduced to eliminate.
+* Note every candidate but the first now lives in `organization`, and the first
+* (`site.legal.privacyPolicy.privacyOfficer`) still dereferences against
+* `organization.locations` — the officer is a person at the company, named by the
+* site because a company may publish more than one policy.
 */
-function monotonicityErrors(palette) {
-	const errors = [];
-	for (const [hue, expanded] of Object.entries(palette)) {
-		const numeric = expanded.numeric ?? {};
-		const steps = NUMERIC_STEPS.filter((s) => numeric[s] != null);
-		for (let i = 1; i < steps.length; i++) {
-			const [prev, step] = [steps[i - 1], steps[i]];
-			const lPrev = hexToOklch(numeric[prev]).l;
-			const lStep = hexToOklch(numeric[step]).l;
-			if (lStep < lPrev + MONOTONIC_EPSILON) continue;
-			const pinned = expanded.deviations ?? {};
-			const culprits = [prev, step].filter((s) => pinned[s] != null);
-			const fix = culprits.length ? culprits.map((s) => {
-				const l = hexToOklch(numeric[s]).l;
-				return `${numeric[s]} (pinned at ${s}) sits at L ${l.toFixed(3)}, nearest step ${nearestStep(l)}`;
-			}).join("; ") : `no step here is pinned, so this is a bug in the generator rather than in your config`;
-			errors.push(`colors.palette.${hue}: step ${step} (${numeric[step]}, L ${lStep.toFixed(3)}) is LIGHTER than step ${prev} (${numeric[prev]}, L ${lPrev.toFixed(3)}). A ramp must darken from 50 to 950 — inverted, a hover from \`bg-<role>-solid\` to \`-solid-bold\` gets lighter, and the dark-mode tables re-point steps assuming the order. ${fix}.`);
+function resolvePrivacyContact(cfg) {
+	const org = cfg.organization;
+	const deref = (c) => {
+		if (c == null) return void 0;
+		if (typeof c !== "string") return c;
+		const loc = org?.locations?.[c];
+		return loc && {
+			email: loc.email,
+			phone: loc.phone,
+			address: loc.address
+		};
+	};
+	return [
+		deref(cfg.site.legal?.privacyPolicy?.privacyOfficer),
+		deref(org?.contact),
+		deref(org?.primaryLocation),
+		org && {
+			email: org.email,
+			phone: org.phone,
+			address: org.address
 		}
-	}
-	return errors;
-}
-/**
-* Surface roles: a bare `bg` (cards, panels, inputs), `bg-muted` for the page
-* behind them, `bg-x-muted` for wells, and `bg-bold`/`-x-bold` for the inverse
-* surface a tooltip sits on. Elevation is expressed by *which* token you reach
-* for — page `bg-muted`, card `bg` — rather than by a raised/sunken pair. That
-* is what lets a future `data-surfaces` axis flatten it without touching markup.
-*/
-const SURFACE_LIGHT = {
-	bg: "50",
-	"bg-muted": "100",
-	"bg-x-muted": "200",
-	"bg-bold": "800",
-	"bg-x-bold": "950",
-	text: "900",
-	"text-bold": "950",
-	"text-muted": "700",
-	"text-x-muted": "500",
-	"text-xx-muted": "400",
-	"text-on-bold": "50",
-	icon: "600",
-	"icon-muted": "500",
-	"border-muted": "200",
-	border: "300",
-	"border-bold": "600"
-};
-const SURFACE_DARK = {
-	bg: "900",
-	"bg-muted": "950",
-	"bg-x-muted": "950",
-	"bg-bold": "200",
-	"bg-x-bold": "50",
-	text: "100",
-	"text-bold": "50",
-	"text-muted": "300",
-	"text-x-muted": "500",
-	"text-xx-muted": "600",
-	"text-on-bold": "950",
-	icon: "400",
-	"icon-muted": "500",
-	"border-muted": "800",
-	border: "700",
-	"border-bold": "400"
-};
-/**
-* Chromatic roles: tints for alert/badge backgrounds, solids for fills. No bare
-* `bg` — see the module docblock. No `text-muted` either: a de-emphasised
-* coloured text could not hold its contrast target off a white surface, so the
-* way to soften coloured text is weight/size, not another colour.
-*/
-const CHROMATIC_LIGHT = {
-	"bg-x-muted": "50",
-	"bg-muted": "100",
-	text: "700",
-	"text-bold": "900",
-	icon: "600",
-	border: "200",
-	"border-bold": "300"
-};
-const CHROMATIC_DARK = {
-	"bg-x-muted": "950",
-	"bg-muted": "900",
-	text: "300",
-	"text-bold": "200",
-	icon: "400",
-	border: "800",
-	"border-bold": "700"
-};
+	].find((c) => c != null && (c.email != null || c.address != null));
+}
 /**
-* The solid family — mode-stable, so a filled button keeps its identity when the
-* appearance flips. Fixed steps rather than the old scan-and-clamp: with a shared
-* lightness ladder every hue's 600 already sits at the same lightness, so there
-* is nothing left to search for. `text-on-<role>` is computed against `bg-solid`.
+* Resolve a design-system theme by following its `extends` chain and deep-merging
+* base → child (child wins; arrays replace wholesale, correct for token overrides).
+* Throws on unknown keys or an `extends` cycle. The result is a plain
+* `DesignSystem` (validate it against `DesignSystemSchema` for completeness).
 */
-const SOLID = {
-	"bg-solid": "600",
-	"bg-solid-bold": "700",
-	"bg-solid-x-bold": "800"
-};
+function resolveTheme(designSystem, key) {
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set();
+	let cur = key;
+	while (cur != null) {
+		if (seen.has(cur)) throw new Error(`extends cycle in designSystem at "${cur}"`);
+		seen.add(cur);
+		const entry = designSystem[cur];
+		if (entry == null) throw new Error(`designSystem theme "${cur}" not found`);
+		chain.unshift(entry);
+		cur = entry.extends;
+	}
+	const out = {};
+	for (const entry of chain) {
+		const { extends: _e, displayName: _d, ...ds } = entry;
+		deepMerge(out, ds);
+	}
+	return out;
+}
 /**
-* Map a token key to its CSS custom property for a given role.
-*
-* `on` is the one irregular case: the foreground for a filled surface reads
-* `--color-text-on-<role>`, with the role *after* `on`, because it names what it
-* sits on rather than what it is.
+* Normalise the two `designSystem` shorthands to the canonical
+* `{ themes: { … } }` shape.
 *
-* The utility class name is this minus the `--color-` prefix, which is why the
-* emitter and the linter can both derive their vocabulary from one function.
+* Both are keyed off what CANNOT be a theme name in the other reading:
+*  - `colors` → a bare `DesignSystem` was written inline.
+*  - `themes` → already canonical.
+*  - neither → the legacy bare theme map, from before the block gained
+*    system-wide fields. Every config authored against the old schema takes this
+*    branch, which is what keeps the change forgiving at runtime even though the
+*    published JSON Schema moved.
 */
-function tokenVar(role, key) {
-	const dash = key.indexOf("-");
-	const target = dash === -1 ? key : key.slice(0, dash);
-	const variant = dash === -1 ? "" : key.slice(dash + 1);
-	if (variant === "on") return `--color-${target}-on-${role}`;
-	if (variant.startsWith("on-")) return `--color-${target}-on-${role}-${variant.slice(3)}`;
-	return variant ? `--color-${target}-${role}-${variant}` : `--color-${target}-${role}`;
-}
-/** The class name a token key produces for a role (`bg-danger-solid`, …). */
-const tokenClass = (role, key) => tokenVar(role, key).slice(8);
-/** Resolve the token set for one role over its hue. */
-function functionalRole(role, hueName, hue, kind = "chromatic") {
-	const numeric = hue.numeric;
-	const v = (n) => `var(--color-${hueName}-${snap(numeric, n)})`;
-	const hex = (n) => numeric[snap(numeric, n)];
-	const map = (table) => {
-		const out = {};
-		for (const [token, step] of Object.entries(table)) out[token] = v(step);
-		return out;
-	};
-	const solids = map(SOLID);
-	const onSolid = pickOn(hex(SOLID["bg-solid"]));
-	return {
-		role,
-		hue: hueName,
-		kind,
-		light: {
-			...map(kind === "surface" ? SURFACE_LIGHT : CHROMATIC_LIGHT),
-			...solids,
-			"text-on": onSolid
-		},
-		dark: {
-			...map(kind === "surface" ? SURFACE_DARK : CHROMATIC_DARK),
-			...solids,
-			"text-on": onSolid
-		}
-	};
+function normaliseDesignSystem(raw) {
+	const ds = raw.designSystem;
+	if (ds == null || typeof ds !== "object") return;
+	if ("themes" in ds) return;
+	raw.designSystem = "colors" in ds ? { themes: { default: ds } } : { themes: ds };
 }
 /**
-* APCA targets. `TEXT` is the body-text bar; `SECONDARY` covers text on a
-* non-primary surface and de-emphasised text. `NON_TEXT` is the icon/boundary
-* tier — the APCA analogue of WCAG's 3:1, where a glyph may run more vivid than
-* text because shape carries meaning alongside contrast.
+* Resolve a raw (already-parsed) config into a validated `Config`:
+*  1. strip YAML nulls,
+*  2. normalise the `designSystem` shorthands to `{ themes: … }`,
+*  3. apply the active A/B variant's `overrides` (by `siteEnv`),
+*  4. validate (shape + cross-field).
+* Pure — no YAML/env access. A loader supplies `siteEnv`.
+*
+* Steps 2 and 3 are in this order deliberately. Normalising first means an
+* `abTesting` override always addresses the canonical shape
+* (`designSystem.themes.<name>`), whatever shorthand the base config used. With
+* the merge first, an override's key path depended on how the base happened to be
+* written — so the same patch hit a different place in two configs that were
+* otherwise equivalent.
+*
+* The A/B lookup reads `site.environments` / `site.abTesting`, and the overrides
+* still deep-merge at the **root** — a variant patches whichever section it names,
+* which is what lets one target `designSystem` and another `site.seo`.
 */
-const CONTRAST = {
-	TEXT: 75,
-	SECONDARY: 60,
-	NON_TEXT: 45
-};
+function resolveConfig(input, siteEnv = "production") {
+	const raw = stripNulls(input);
+	normaliseDesignSystem(raw);
+	const site = raw.site;
+	const envConfig = (site?.environments)?.[siteEnv];
+	if (envConfig?.variant) {
+		const overrides = (site?.abTesting)?.variants?.[envConfig.variant]?.overrides;
+		if (overrides) {
+			normaliseDesignSystem(overrides);
+			deepMerge(raw, overrides);
+		}
+	}
+	const result = validateConfig(raw);
+	if (!result.ok) {
+		const msg = result.errors.map((e) => `  ${e.path.join(".") || "<root>"}: ${e.message}`).join("\n");
+		throw new Error(`Invalid config:\n${msg}`);
+	}
+	return result.data;
+}
 /**
-* Text tokens deliberately exempt from the contract. Placeholders and disabled
-* text are required to look unavailable; holding them to the body-text bar would
-* defeat the affordance. Nothing else may be exempt.
+* Is this raw config a full `Config` rather than a bare `design-system.json`?
+*
+* The discriminator is **total**, not a heuristic, and both halves are load-
+* bearing: `ConfigSchema` cannot validate without a `designSystem` (it is a
+* required key), and `DesignSystemSchema` is strict, so a `designSystem` key in a
+* design system is an `unrecognized_keys` error. No document can be read as both,
+* and no document that is neither reaches here without failing validation anyway.
+*
+* The restructure did not weaken this: `designSystem` stayed at the root
+* precisely so the discriminator kept working unchanged.
+*
+* Deliberately shape-based rather than filename-based: consumers name this file
+* whatever suits them (`company.json`, `site.json`, `vitops.config.json`), and a
+* rule keyed to a name would silently stop working the moment someone renamed it.
 */
-const EXEMPT_TEXT = new Set(["text-x-muted", "text-xx-muted"]);
+function isConfig(raw) {
+	return typeof raw === "object" && raw != null && !Array.isArray(raw) && "designSystem" in raw;
+}
 /**
-* Verify a role's contrast targets. Returns human-readable failures.
+* Resolve a raw config of either kind into the design system to build from.
 *
-* Chromatic roles are checked against the surface planes they actually sit on
-* (`surfaceBg`) as well as their own tints — coloured text almost never appears
-* over its own solid, it appears over the page. Checking only within the role
-* would have missed the pairing that matters most.
+* Every entry point that used to take a `design-system.json` goes through this,
+* so a consumer who keeps their tokens inside the larger config points the
+* same option at that file instead of maintaining a second one. The config
+* is handed back too, because the parts of generation that depend on site-level
+* facts (`designSystem.defaultColorScheme`, the legal documents, the icon
+* sprite) would otherwise need the same path declared a second time.
+*
+* The returned `designSystem` is **not** validated here — the caller does that,
+* so it can say which file and which theme the errors belong to. Validation of
+* the config itself has already happened (`resolveConfig` throws).
 */
-function checkContrast(fr, numericOf, surfaceBg) {
-	const failures = [];
-	const resolve = (val) => {
-		const m = /^var\(--color-([a-z0-9-]+)-(\d+)\)$/.exec(val);
-		if (!m) return val;
-		return numericOf(m[1])[m[2]] ?? val;
+function resolveInput(raw, opts = {}) {
+	if (!isConfig(raw)) {
+		if (opts.theme != null) throw new Error(`theme "${opts.theme}" was requested, but this is a design-system.json — it holds one design system and no \`themes\` map. Point at a full config to select a theme.`);
+		return { designSystem: raw };
+	}
+	const config = resolveConfig(raw, opts.siteEnv);
+	const themes = config.designSystem?.themes ?? {};
+	const theme = opts.theme ?? config.designSystem?.defaultTheme ?? "default";
+	if (!(theme in themes)) throw new Error(`designSystem.themes has no "${theme}" entry (found: ${Object.keys(themes).join(", ") || "none"})`);
+	return {
+		designSystem: resolveTheme(themes, theme),
+		config,
+		theme
 	};
-	const fail = (appearance, msg) => failures.push(`${fr.role}/${appearance}: ${msg}`);
-	for (const [appearance, tokens] of [["light", fr.light], ["dark", fr.dark]]) {
-		const ownBg = Object.keys(tokens).filter((k) => k === "bg" || k.startsWith("bg-")).filter((k) => !k.startsWith("bg-solid")).filter((k) => !k.startsWith("bg-bold") && !k.startsWith("bg-x-bold"));
-		const planes = fr.kind === "surface" ? ownBg.map((k) => [k, resolve(tokens[k])]) : [...(surfaceBg?.[appearance] ?? []).map((h, i) => [`surface#${i}`, h]), ...ownBg.map((k) => [k, resolve(tokens[k])])];
-		for (const [planeName, bg] of planes) {
-			const textMin = planeName === "bg" ? CONTRAST.TEXT : CONTRAST.SECONDARY;
-			for (const key of [
-				"text",
-				"text-bold",
-				"text-muted"
-			]) {
-				if (tokens[key] == null || EXEMPT_TEXT.has(key)) continue;
-				const min = key === "text-muted" ? CONTRAST.SECONDARY : textMin;
-				const lc = contrastLc(resolve(tokens[key]), bg);
-				if (lc < min) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${min} on ${planeName} ${bg}`);
-			}
-			const nonText = fr.kind === "surface" ? ["icon", "border-bold"] : ["icon"];
-			for (const key of nonText) {
-				if (tokens[key] == null) continue;
-				const lc = contrastLc(resolve(tokens[key]), bg);
-				if (lc < CONTRAST.NON_TEXT) fail(appearance, `${key} Lc ${lc.toFixed(1)} < ${CONTRAST.NON_TEXT} on ${planeName} ${bg}`);
-			}
-		}
-		const solid = resolve(tokens["bg-solid"]);
-		const onLc = contrastLc(tokens["text-on"], solid);
-		if (onLc < CONTRAST.SECONDARY) fail(appearance, `text-on Lc ${onLc.toFixed(1)} < ${CONTRAST.SECONDARY} on bg-solid`);
-		if (tokens["bg-bold"] != null && tokens["text-on-bold"] != null) {
-			const lc = contrastLc(resolve(tokens["text-on-bold"]), resolve(tokens["bg-bold"]));
-			if (lc < CONTRAST.TEXT) fail(appearance, `text-on-bold Lc ${lc.toFixed(1)} < ${CONTRAST.TEXT} on bg-bold`);
+}
+/** Strip nulls (YAML `~`/`null`) → undefined so optional fields validate. */
+function stripNulls(obj) {
+	if (obj === null) return void 0;
+	if (Array.isArray(obj)) return obj.map(stripNulls);
+	if (obj && typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) {
+			const stripped = stripNulls(value);
+			if (stripped !== void 0) result[key] = stripped;
 		}
+		return result;
+	}
+	return obj;
+}
+/** Deep-merge `source` into `target` (in place). Arrays replace wholesale. */
+function deepMerge(target, source) {
+	for (const key of Object.keys(source)) {
+		const s = source[key];
+		const t = target[key];
+		if (s && typeof s === "object" && !Array.isArray(s) && t && typeof t === "object" && !Array.isArray(t)) deepMerge(t, s);
+		else target[key] = s;
 	}
-	return failures;
 }
 
 //#endregion
@@ -2138,12 +2454,17 @@ const TIERS = {
 			"pricing-grid"
 		], "patterns/subgrid.css"),
 		astro: a("Subgrid", "css"),
-		use: "`<Subgrid>` — emits `<ul class=\"grid\">` with row-subgrid children so cards align across tracks."
+		use: "`<Subgrid>` — emits `<ul class=\"subgrid\" role=\"list\">`; author `<li class=\"card subgrid-card\">` items yourself, so tranches align across the set."
 	},
 	card: {
-		css: c(["card"], void 0, true),
-		astro: a("Cards", "css"),
-		use: "`<Cards>` for a list, or the `.card` class directly. Generated pattern: has roles and states."
+		css: c(["card"], "patterns/card.css", true),
+		wc: {
+			tag: "wc-cards",
+			registered: true,
+			adds: "whole-card click that keeps the card text selectable"
+		},
+		astro: a("Cards", "wc"),
+		use: "`<Cards>` — it emits `<wc-cards>` itself, so do NOT add your own wrapper. `<Subgrid>` is the same grid without the click enhancement."
 	},
 	icon: {
 		css: c([
@@ -2201,8 +2522,13 @@ const TIERS = {
 		use: "`.cta` on any element — usually `<a>`, since a CTA navigates. Filled, with role variants."
 	},
 	link: {
-		css: c(["link", "skip-link"], "patterns/anchor-link.css", true),
-		use: "`<a>` gets it at zero specificity; `.link` for other tags."
+		css: c([
+			"link",
+			"skip-link",
+			"stretched-link",
+			"raised"
+		], "patterns/anchor-link.css", true),
+		use: "`<a>` gets it at zero specificity; `.link` for other tags. `.stretched-link` makes one link cover its positioned ancestor (whole-card click, no JS — but the card text stops being selectable); `.raised` lifts content back above that overlay."
 	},
 	badge: {
 		css: c(["badge", "badge-indicator"], "patterns/tag.css", true),
@@ -2427,7 +2753,7 @@ function tierTags() {
 * The patterns one tier provides, in `TIER_NAMES` order.
 *
 * Every renderer goes through this rather than filtering `TIERS` itself: the docs
-* bundle projects all four tiers into one table for agents, the docsite projects
+* bundle projects every tier into one table for agents, the docsite projects
 * each tier as its own page for humans, and they must agree about which patterns
 * are in a tier. Five copies of `.filter(e => e.wc)` would agree until one of them
 * didn't.
@@ -2980,6 +3306,44 @@ Every utility accepts a **container-breakpoint prefix**; animation utilities als
 - State prefixes (animation effects only): \`hover-\`, \`active-\`, \`focus-\`, and \`flip-<effect>\`
   (plays the effect in reverse on toggle). Effects require \`transition\` on the element.
 
+## Foundations — read this before writing any page markup
+
+Six classes carry the structure of almost every page. They are not a starting suggestion
+you refine into hand-written CSS; **they are the answer**, and reaching past them is the
+single most common way a page drifts off the design system. Each line below is the
+temptation followed by what to write instead.
+
+| If you are about to write…                                     | Write this instead                                     |
+| -------------------------------------------------------------- | ------------------------------------------------------ |
+| a \`wrap\` / \`wrapper\` / \`container\` / \`inner\` class              | **\`centered\`** — never invent a container class        |
+| \`max-width\` + \`margin-inline: auto\`                            | **\`centered\`**                                        |
+| \`padding-block\` on a section, to space it from the next        | **\`region\`**                                          |
+| margins between headings, paragraphs and lists                 | **\`rhythm\`** on the container                         |
+| \`display: grid\` + \`grid-template-columns: repeat(n, 1fr)\`      | **\`subgrid\`** — see below, this is the missed one     |
+| \`grid-template-columns: repeat(auto-fit, minmax(…))\`           | **\`grid-auto\`** (or \`subgrid\`, see below)             |
+| \`display: flex\` + \`gap\` for a row of buttons/badges/meta      | **\`cluster\`** (or \`flex\` + \`items-*\` utilities)      |
+
+**The container is \`centered\`, and it is not a max-width box.** It is a grid of *named
+tracks*, so a child opts into a wider track (\`breakout\`, \`spotlight\`, \`fullbleed\`) without
+the parent knowing. A hand-rolled \`.wrap\` renders the same on the happy path and then has
+no answer for the full-bleed image, which is why the escape from it is always more
+hand-written CSS. There is **no case** where a bespoke container class is the right call.
+
+**Multiple cards means \`subgrid\`, essentially always.** This is the most under-used class in
+the framework, and the reason is that a plain \`grid\` *looks* correct: it aligns the outer
+boxes. What it cannot do is align the tranches **inside** them — so across three cards the
+headings sit at three different heights, the bodies start at three different points, and the
+footers float wherever the copy ended. \`subgrid\` re-declares the parent's row tracks on every
+item, so head / body / footer land on shared row lines no matter how much content each card
+holds. If the answer to "is this a repeated set of things with internal structure" is yes,
+this is the class.
+
+**The one honest alternative is \`grid-auto\`** — an auto-fit track (\`--grid-min\`, \`--grid-gap\`)
+where the column count is content-driven. Use it when the items have **no internal tranches to
+align**: a bare image gallery, a logo wall, a row of icons. The moment an item has an eyebrow
+and a heading and a footer, \`subgrid\` is the one that makes them line up. Never hand-write
+\`repeat(auto-fit, minmax(…))\` — that is \`grid-auto\`.
+
 ## Layout & structure
 
 - **\`centered\`** — named-track grid centering content in the reading \`measure\` track.
@@ -2988,6 +3352,70 @@ Every utility accepts a **container-breakpoint prefix**; animation utilities als
   \`--width-breakout\` / \`--width-spotlight\` and \`--gutter\`.
 - **\`rhythm\`** — relationship-based vertical spacing (margins between headings, paragraphs,
   lists, media) driven by the space scale. Usually paired with \`centered\`.
+- **\`region\`** — vertical rhythm *between sections* (fluid \`padding-block\`, tunable with
+  \`--region-space\` / \`--region-space-min\` / \`--region-space-max\`). Goes on the section;
+  \`centered\` goes on the container inside it. \`rhythm\` handles flow **within** a region.
+- **\`subgrid\`** — the class for any repeated set of items with internal structure: cards,
+  pricing tiers, feature panels. Items share the parent's row tracks, so each item's
+  tranches (head / body / footer) align across the whole set — which a plain \`grid\`
+  cannot do. **Reach for this whenever there is more than one card.**
+  - Columns: \`--subgrid-cols\` (default 3) or \`subgrid-cols-{1,2,3,4}\`; tranches per item:
+    \`--subgrid-row-span\` (default 2) or \`subgrid-rows-{2,3,4}\` — this must match how many
+    row bands each item actually contains.
+  - \`subgrid-responsive\` collapses to 2 columns under 60rem and 1 under 40rem.
+  - Gaps: \`--subgrid-gap\` (between columns *and* between tranches) and \`--subgrid-row-gap\`
+    (extra space between wrapped rows of items only).
+  - \`subgrid-card\` is the matching item: \`--subgrid-card-rows\` tranches, with
+    \`subgrid-card__media\` (bleeds to the card edge) and \`subgrid-card__footer\`
+    (pinned to the last row band, so CTAs line up across the set).
+  - It is markerless when it is a \`ul\`/\`ol\` — and a set of cards **is** a list, so prefer
+    \`<ul class="subgrid" role="list">\` with \`<li>\` items over a stack of \`<div>\`s.
+    **\`role="list"\` is not optional here.** Safari + VoiceOver stop announcing a marker-less
+    \`<ul>\` as a list, so the marker reset silently costs the semantics the \`<ul>\` was chosen
+    for. \`<Subgrid>\` adds it for you; hand-written markup must say it.
+  - **When the whole card is a link, the card is still the item**, and there are two ways to
+    do it. Both keep the accessible name on real text rather than on a whole card of it.
+    | Want                                         | Use                                          |
+    | -------------------------------------------- | -------------------------------------------- |
+    | no JS at all                                 | \`stretched-link\` — **text not selectable**   |
+    | selectable text and a clickable card         | \`<Cards>\` / \`<wc-cards>\` — needs JS          |
+    - \`stretched-link\` goes on a link **inside** the card (usually the heading); its
+      \`::after\` covers the card. \`subgrid-card\` already carries the \`position: relative\` it
+      resolves against; on a bare \`card\`, add \`relative\`. Anything else interactive in the
+      card needs **\`raised\`** to sit above the overlay — \`relative\` alone is not enough,
+      because a positioned element at \`z-index: auto\` does not rise above an explicit one.
+      The cost is inherent: the overlay takes the pointer-drag, so the card's text can no
+      longer be selected.
+    - \`<Cards>\` wraps the list in \`<wc-cards>\`, which adds no overlay and instead tells a
+      click apart from the end of a drag. Text stays selectable; with no JS the card's own
+      link still works, and the pointer cursor only appears once the element has upgraded.
+    - **Never layer the two** — the overlay wins, so you lose selection and the JS never
+      runs. \`vitops lint\` reports the combination.
+    **\`<li><a class="card">\` is the wrong shape and it renders fine**, which is why it keeps
+    getting written: 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 does not fill the
+    cell either. Putting the anchor in the grid's place instead (\`<ul><a></ul>\`) is invalid
+    HTML. \`vitops lint\` reports this one.
+  - Related subgrid layouts: \`pricing-grid\` + \`pricing-card\` (with \`pricing-card--featured\`)
+    and \`comparison-table\`.
+- **\`grid-auto\`** — an auto-fit grid: items wrap into as many equal columns as fit, each at
+  least \`--grid-min\` wide (default 13rem), gap \`--grid-gap\`. The content-driven counterpart
+  to \`split\`'s explicit fractions. Prefer \`subgrid\` when the items have internal tranches to
+  align; this is the right class for a gallery, a logo wall, a row of icons.
+- **\`stretched-link\`** — makes one link cover its nearest positioned ancestor, so a whole
+  card is clickable while the accessible name stays on real text. Pair with \`relative\` on the
+  container (\`subgrid-card\` already has it). **The card's text stops being selectable** — the
+  overlay takes the pointer-drag — so where that matters use \`<Cards>\` instead.
+- **\`raised\`** — lifts content back above a \`stretched-link\` overlay, for a second link or a
+  button in the same card. Sets \`position: relative\` **and** a z-index, both of which are
+  required: \`relative\` on its own leaves the element underneath and unclickable.
+- **\`relative\`** — \`position: relative\`, the containing block \`stretched-link\` needs.
+- **\`cluster\`** — a wrapping row of related inline things (buttons, badges, tags, meta) with
+  a shared \`--cluster-gap\`. Alignment variants \`cluster-{start,center,end}\`,
+  \`cluster-{between,around,evenly}\`, and the two-axis form
+  \`cluster-<align>-<justify>\` over \`start\`/\`center\`/\`end\`. Prefer this over a hand-written
+  \`display: flex\` + \`gap\` for a group of controls.
 - **\`split\`** — a two-column pair. Ratio rule: **\`split-<a>-<b>\`** where \`<a>-<b>\` ∈
   \`1-2\`, \`2-1\`, \`1-3\`, \`3-1\`, \`1-4\`, \`4-1\`, \`2-3\`, \`3-2\` (breakpoint-prefixable); equal
   columns without one. The ratio is a flex **basis**, so a column's padding counts
@@ -3255,7 +3683,16 @@ const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ({
 	">": "&gt;",
 	"\"": "&quot;"
 })[c]);
-/** Sentinel for a lifted code span. Cannot occur in authored schema prose. */
+/**
+* Sentinel for a lifted code span. Cannot occur in authored schema prose.
+*
+* Written as an ESCAPE, never as the literal byte. A raw NUL here made this whole
+* file `data` rather than `text` to libmagic, so grep and ripgrep classified it
+* as binary and **silently skipped it** — every search for a string in the
+* largest doc emitter in the repo returned nothing, with no error and nothing to
+* notice. That is the failure mode this codebase is written against, aimed at the
+* tool an agent uses to find anything.
+*/
 const CODE_SLOT = "\0";
 /**
 * The inline markdown the schema's `desc()` text actually uses, as HTML. Closed
@@ -3920,7 +4357,10 @@ bare, unsuffixed pattern. States re-apply per variant with the variant's role.
 `;
 }
 /**
-* All four tiers in ONE doc — the agent-facing projection of `TIERS`.
+* All three tiers in ONE doc — the agent-facing projection of `TIERS`.
+*
+* Four columns, three tiers: Astro and Bricks are both the platform-wrapper tier,
+* split by package rather than ranked.
 *
 * The docsite projects each tier as its own page, because a human arrives already
 * knowing which stack they are in ("show me the Astro components"). An agent
@@ -3968,7 +4408,7 @@ function renderComponentsConcept(ds) {
 	return `${frontmatter({
 		type: "Design Concept",
 		title: "Vitops components — which tier provides a pattern, and what to write",
-		description: "Every UI pattern across the four tiers (CSS classes, wc-* web components, Astro components, Bricks elements): which tiers provide it, which call to make, and how the tiers compose.",
+		description: "Every UI pattern across the three tiers (CSS classes, wc-* web components, and the platform wrappers: Astro components and Bricks elements): which tiers provide it, which call to make, and how the tiers compose.",
 		resource: DS_PATH,
 		tags: [
 			"components",
@@ -3982,20 +4422,26 @@ function renderComponentsConcept(ds) {
 
 # Components
 
-A pattern is provided by up to four tiers, and they **compose** rather than compete:
+A pattern is provided by up to **three tiers**, and they **compose** rather than compete:
 
 1. **CSS framework classes** — every pattern expressible in pure HTML/CSS. Reach here first.
 2. **Web components** (${code("<wc-*>")}, Lit) — only where a pattern genuinely benefits from
    progressive enhancement. The slotted markup is the fallback and must be usable with no JS;
    the element parses and augments it in place.
-3. **Astro components** — authoring conveniences that emit the correct markup. They must not
-   require runtime JS. Where a pattern has a web component, the Astro component emits that tag
-   **with the accessible fallback inside it**.
-4. **Bricks elements** — the same patterns as WordPress/Bricks Builder elements.
+3. **Platform wrappers** — authoring conveniences that generate the correct markup at build
+   time, using the classes and elements of tiers 1 and 2. They must not require runtime JS.
+   Where a pattern has a web component, the wrapper emits that tag **with the accessible
+   fallback inside it**. Two platforms:
+   - **Astro components** (${code("@getvitops/astro")})
+   - **Bricks elements** (WordPress / Bricks Builder)
+
+**Astro and Bricks are the same tier**, not tiers 3 and 4. They are siblings chosen by which
+platform you are on — no project uses both, and neither outranks the other. The tables below
+give them separate columns because they are separate packages, not separate levels.
 
 ## Choosing
 
-**Use the highest-numbered tier available for your stack, and write only its call.** In Astro
+**Use the highest tier available for your stack, and write only its call.** In Astro
 that is the Astro component; in Bricks the element; anywhere else the classes, plus the
 ${code("<wc-*>")} tag when one exists.
 
@@ -4362,6 +4808,19 @@ Both utils entries are **separate subpaths** because they are the only modules t
 **Worker** rather than at build time. Keeping them off the package index is what stops a
 conversion endpoint pulling \`sharp\` into its bundle. Neither may use a Node builtin.
 
+**Import them from \`@getvitops/astro\` if that is your only direct dependency.**
+\`@getvitops/astro/tracking\` re-exports everything in \`@getvitops/utils/tracking\` (plus
+\`TRACKING_ENDPOINT\`), so the flow works with one install — under strict pnpm, app code cannot
+resolve a transitive dependency, and \`@getvitops/utils\` would otherwise have to be added by
+hand. Do **not** reach for the same symbols on \`@getvitops/astro\`'s index instead: that entry
+pulls the integration and its Node builtins, which is the import that drags \`sharp\` toward a
+Worker bundle. \`@getvitops/astro/tracking\` and \`@getvitops/astro/routes\` are both clean.
+
+⚠️ The route you mount must answer **\`/api/track\`** (\`TRACKING_ENDPOINT\`) — the capture
+script beacons \`tel:\` conversions there, and a route at any other path means every call
+conversion 404s silently. The integration warns at build when tracking is on and no such route
+exists.
+
 ## The capture demands consent
 
 \`_ac\` is a 90-day identifier tying a visitor to an ad, so it waits on \`marketing\` (override
@@ -4677,7 +5136,7 @@ function renderConceptsIndex() {
 * [Colour system](color.md) - seeded OKLCH scales on a shared lightness ladder, target-prefixed tokens, automatic dark mode
 * [Type & space scales](scales.md) - fluid modular scales and the tokens they emit
 * [Component patterns](patterns.md) - token cascade, override hooks, states, role variants
-* [Components](components.md) - which of the four tiers provides each pattern, and the call to make
+* [Components](components.md) - which of the three tiers provides each pattern, and the call to make
 * [Icons](icons.md) - semantic names across icon sets, bundle derivation, sprite delivery
 * [Consent gate](consent.md) - inert gated tags, demand-driven prompting, three-valued choices
 * [Conversion tracking](tracking.md) - ad-click attribution, the \`_ac\` cookie, conversion notifications
@@ -6641,7 +7100,8 @@ function build(ds, format, assetsDir, buildOpts = {}) {
 		if (hue == null) throw new Error(`role "${role}" references unknown palette hue "${hueName}"`);
 		scaleRoles.push(functionalRole(role, hueName, hue, roleKind(spec)));
 	}
-	const surfaceRole = scaleRoles.find((r) => r.role === "surface");
+	const surfaceRole = scaleRoles.find((r) => r.role === "surface" && "bg" in r.light);
+	if (!surfaceRole && roleMap["surface"] != null) console.warn("[vitops] colors.roles.surface is chromatic, so no --color-bg-surface exists — skipping --surface-glass, --overlay and .glass. Declare it as { \"hue\": \"…\", \"kind\": \"surface\" } if you meant a surface role.");
 	const focusRole = scaleRoles.find((r) => r.role === "ui-primary") ?? scaleRoles[0];
 	for (const w of ladderWarnings(expandedPalette)) console.warn(`[vitops] ${w}`);
 	{
@@ -7175,7 +7635,7 @@ function emitTailwind(ctx) {
 		for (const fr of scaleRoles) for (const [t, val] of Object.entries(fr.light)) fn += `  ${tokenVar(fr.role, t)}: ${val};\n`;
 		const focus = scaleRoles.find((r) => r.role === "ui-primary") ?? scaleRoles[0];
 		if (focus) fn += `  --color-border-focus: ${focus.light["bg-solid"]};\n`;
-		const surface = scaleRoles.find((r) => r.role === "surface");
+		const surface = scaleRoles.find((r) => r.role === "surface" && "bg" in r.light);
 		if (surface) {
 			fn += `  --surface-glass: color-mix(in oklch, var(--color-bg-surface) 72%, transparent);\n`;
 			fn += `  --overlay: color-mix(in oklch, var(--color-${surface.hue}-950) 45%, transparent);\n`;
@@ -7203,7 +7663,7 @@ function emitTailwind(ctx) {
 	if (scaleRoles.length) {
 		util.push(`/* Role colour utilities (the public API) */`);
 		for (const { cls, prop, value } of roleColorUtilities(scaleRoles, utilities)) util.push(`@utility ${cls} {\n  ${prop}: ${value};\n}`);
-		if (scaleRoles.some((r) => r.role === "surface")) util.push(`@utility glass {\n  background-color: var(--surface-glass);\n  backdrop-filter: blur(12px);\n  -webkit-backdrop-filter: blur(12px);\n}`);
+		if (scaleRoles.some((r) => r.role === "surface" && "bg" in r.light)) util.push(`@utility glass {\n  background-color: var(--surface-glass);\n  backdrop-filter: blur(12px);\n  -webkit-backdrop-filter: blur(12px);\n}`);
 	}
 	util.push(`/* Typography roles */`);
 	for (const [role, spec] of Object.entries(typography?.roles ?? {})) util.push(`@utility font-${role} {\n${decls(roleDecls(role, spec))}\n}`);
@@ -7749,7 +8209,7 @@ function loadConfigFile(input, siteEnv) {
 */
 function defaultConfig() {
 	return {
-		$schema: SCHEMA_URL,
+		$schema: SCHEMA_LOCAL_PATH,
 		colors: {
 			palette: {
 				brand: { seed: "#2e9b73" },
@@ -8019,5 +8479,5 @@ function defaultConfig() {
 }
 
 //#endregion
-export { AD_PROVIDERS, BASE_HOOK, CONFIG_SCHEMA_URL, CONTRAST, ConfigSchema, DARK_SEL, DOC_ORDER, DOC_SLUGS, DesignSystemSchema, JURISDICTIONS, JURISDICTION_COUNTRIES, KNOWN_PROCESSORS, NUMERIC_STEPS, REQUIRED_ROLES, ROLE_TOKEN_KEYS, SCHEMA_URL, SiteFontSchema, TEMPLATES, TIERS, TIER_NAMES, TW_CLASH, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, processorsMissingLocation, renderInlineMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, schemaTreeNodes, spriteId, stripNulls, tierPatterns, tierTags, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
+export { AD_PROVIDERS, BASE_HOOK, CONFIG_SCHEMA_URL, CONTRAST, ConfigSchema, DARK_SEL, DOC_ORDER, DOC_SLUGS, DesignSystemSchema, JURISDICTIONS, JURISDICTION_COUNTRIES, KNOWN_PROCESSORS, NUMERIC_STEPS, REQUIRED_ROLES, ROLE_TOKEN_KEYS, SCHEMA_LOCAL_PATH, SCHEMA_URL, SiteFontSchema, TEMPLATES, TIERS, TIER_NAMES, TW_CLASH, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, movedTokens, parseMarkdown, processorsMissingLocation, renderInlineMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, schemaTreeNodes, spriteId, stripNulls, tierPatterns, tierTags, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
 //# sourceMappingURL=index.mjs.map