@getvitops/generator 3.0.0 → 4.1.0

package/dist/index.mjs

@@ -5,6 +5,7 @@ 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 { generateIconInclude, nodesToHtml, resolveIcon, t } from "@getvitops/utils";
 import { getIconData, iconToSVG, replaceIDs } from "@iconify/utils";
@@ -20,7 +21,7 @@ import { getIconData, iconToSVG, replaceIDs } from "@iconify/utils";
 *
 * `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
 * WordPress target needs. Nothing sets it anywhere else, which meant the dark
-* flip was unreachable outside Bricks: the shipped `<color-scheme-toggle>` web
+* flip was unreachable outside Bricks: the shipped `<wc-color-scheme-toggle>` web
 * component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
 * clicking "Dark" changed an attribute no rule matched. Matching both makes the
 * component work on every target without changing what Bricks already does.
@@ -38,7 +39,7 @@ const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
 *
 * Derived from `DARK_SEL`'s attributes rather than written out a third time, and
 * inverted: this must apply when NO explicit choice has been made. That is
-* exactly what `<color-scheme-toggle>`'s "System" position produces — it removes
+* exactly what `<wc-color-scheme-toggle>`'s "System" position produces — it removes
 * `data-theme` entirely — so with this block present System resolves to the OS
 * instead of silently falling through to light, and needs no JS to do it.
 *
@@ -519,7 +520,7 @@ const DesignSystemBlock = desc(z.strictObject({
 		"light",
 		"dark",
 		"system"
-	])), "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<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.")
+	])), "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\")."),
@@ -629,11 +630,23 @@ const DnsDomainSchema = z.object({
 	nameservers: z.optional(z.array(z.string())),
 	records: z.optional(z.array(DnsRecordSchema))
 });
+/**
+* One domain to onboard into Google Search Console via `vitops search setup`.
+*
+* 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.
+*/
+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.")
 });
@@ -818,7 +831,7 @@ const TwitterSchema = z.object({
 	image: z.optional(ImageRefSchema)
 });
 /**
-* What `vitops notify` needs to tell search engines a deploy happened.
+* What `vitops search notify` needs to tell search engines a deploy happened.
 *
 * 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
@@ -832,7 +845,7 @@ const TwitterSchema = z.object({
 * (a key, a property, which pages matter), never what to say about it.
 */
 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 notify --new-key`."),
+	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.")
 });
@@ -843,8 +856,49 @@ const SearchConsoleSchema = z.object({
 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 service-account credential in `VITOPS_GSC_SERVICE_ACCOUNT` or `GOOGLE_APPLICATION_CREDENTIALS` at run time — never put the key in this file."),
-	priorityUrls: desc(z.optional(z.array(z.url())), "The pages whose indexing actually matters. `vitops 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.")
+	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.")
+});
+/**
+* The ad platforms `vitops ads` can link a site to.
+*
+* 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.
+*/
+const AD_PROVIDERS = [
+	"google",
+	"meta",
+	"linkedin",
+	"reddit",
+	"tiktok",
+	"microsoft",
+	"pinterest",
+	"snapchat"
+];
+const AdProviderSchema = z.enum(AD_PROVIDERS);
+/**
+* One ad property this site is linked to.
+*
+* 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.
+*/
+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.")
 });
 /**
 * Which template set the generated legal documents are written against. This is
@@ -856,6 +910,20 @@ const IndexingSchema = z.object({
 const JURISDICTIONS = ["ca"];
 const JurisdictionSchema = z.enum(JURISDICTIONS);
 /**
+* The country each template set frames cross-border transfers as *leaving*.
+*
+* 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".
+*
+* 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`.
+*/
+const JURISDICTION_COUNTRIES = { ca: "Canada" };
+/**
 * 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.
@@ -863,10 +931,16 @@ const JurisdictionSchema = z.enum(JURISDICTIONS);
 * 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.
 */
+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()), "Where they process it, as it should read in a sentence (e.g. \"the United States\"). Feeds the cross-border-transfer disclosure."),
+	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({
@@ -878,6 +952,7 @@ const SiteSectionSchema = z.object({
 	})), "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(),
@@ -904,7 +979,7 @@ const SiteSectionSchema = z.object({
 		bingSiteVerification: z.optional(z.string()),
 		openGraph: z.optional(OpenGraphSchema),
 		twitter: z.optional(TwitterSchema),
-		indexing: desc(z.optional(IndexingSchema), "How `vitops notify` tells search engines about a deploy: which sitemap, IndexNow key, Search Console property, and which pages to verify afterwards.")
+		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()),
@@ -917,11 +992,20 @@ const SiteSectionSchema = z.object({
 			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: z.optional(z.email()) })), "Where site notifications (e.g. form submissions) are sent."),
+	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: z.optional(z.boolean()),
-		platforms: z.optional(z.array(z.string()))
-	})), "Marketing/conversion tracking toggles per platform."),
+		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`."),
@@ -1141,6 +1225,27 @@ function validateConfig(input) {
 		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",
@@ -1175,6 +1280,18 @@ function validateConfig(input) {
 			"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,
@@ -1753,6 +1870,590 @@ function checkContrast(fr, numericOf, surfaceBg) {
 	return failures;
 }
 
+//#endregion
+//#region src/tiers.ts
+const c = (classes, partial, generated = false) => ({
+	...partial ? { partial } : {},
+	classes,
+	generated
+});
+/**
+* Shorthand for the usual `@getvitops/astro/components/<name>.astro` export.
+*
+* Not every component lives under `components/` — `CookieConsent.astro` is exported
+* from the package root — so those are written out in full. The specifier must be
+* one a consumer can actually import: `tiers.test.ts` checks each against
+* `packages/astro/package.json`'s `exports`, because a wrong one is a copy-pasteable
+* import that fails only in the consumer's project.
+*/
+const a = (name, wraps) => [{
+	component: `@getvitops/astro/components/${name}.astro`,
+	wraps
+}];
+const TIERS = {
+	tree: {
+		css: c([
+			"tree",
+			"tree__item",
+			"tree__content",
+			"tree__toggle",
+			"tree__label"
+		], "patterns/tree.css", true),
+		wc: {
+			tag: "wc-tree",
+			registered: true,
+			adds: "filter, expand/collapse all, hash deep-linking"
+		},
+		astro: a("Tree", "wc"),
+		use: "`<Tree items={…} />` — it emits `<wc-tree>` itself, so do NOT add your own wrapper."
+	},
+	carousel: {
+		css: c(["carousel"], "patterns/carousel.css", true),
+		wc: {
+			tag: "wc-carousel",
+			registered: true,
+			adds: "cloned slides for a seamless loop, autoplay, snap nav"
+		},
+		bricks: "vitops-carousel",
+		use: "`<wc-carousel>` around your slides; each child is a slide. Works unenhanced as a scroll-snap strip."
+	},
+	entries: {
+		css: c([
+			"entries__table",
+			"entries__scroll",
+			"entries__nav"
+		], "patterns/table.css"),
+		wc: {
+			tag: "wc-entries",
+			registered: true,
+			adds: "parses heading + `<dl>` pairs into a table above a breakpoint"
+		},
+		bricks: "vitops-entries",
+		use: "`<wc-entries>` around `<h3>` + `<dl>` pairs. The tier-2 exemplar: semantic pairs with no JS, a table with it."
+	},
+	copy: {
+		css: c([
+			"copy",
+			"copy__button",
+			"copy__icon",
+			"copy__tooltip"
+		], "patterns/copy.css"),
+		wc: {
+			tag: "wc-copy",
+			registered: true,
+			adds: "clipboard write plus success feedback"
+		},
+		bricks: "vitops-copy-button",
+		use: "`<wc-copy>` around the content and a `[data-copy]` button."
+	},
+	dismissable: {
+		css: c(["banner__close", "notification__close"], "patterns/banner.css"),
+		wc: {
+			tag: "wc-dismissable",
+			registered: true,
+			adds: "fade-out + removal, optional auto-dismiss"
+		},
+		bricks: "vitops-dismissable",
+		use: "`<wc-dismissable>` around any banner/notification containing a `[data-dismiss]` control."
+	},
+	"split-panel": {
+		css: c([
+			"splitter",
+			"splitter__panel",
+			"splitter__handle"
+		], "patterns/splitter.css"),
+		wc: {
+			tag: "wc-split-panel",
+			registered: true,
+			adds: "draggable divider between two panels"
+		},
+		bricks: "vitops-split-panel",
+		use: "`<wc-split-panel>` with two children. Unenhanced they simply stack."
+	},
+	"image-compare": {
+		css: c([
+			"image-compare",
+			"image-compare__before",
+			"image-compare__handle"
+		], "patterns/splitter.css"),
+		wc: {
+			tag: "wc-image-compare",
+			registered: true,
+			adds: "drag handle revealing the before/after image"
+		},
+		bricks: "vitops-image-compare",
+		use: "`<wc-image-compare>` with two images. Both are visible without JS."
+	},
+	marquee: {
+		css: c([
+			"marquee",
+			"marquee__content",
+			"marquee__item"
+		], "patterns/marquee.css"),
+		wc: {
+			tag: "wc-marquee",
+			registered: true,
+			adds: "fills the track with enough copies to scroll seamlessly"
+		},
+		use: "`<wc-marquee>` around one `.marquee__content`. Scrolls via CSS alone; JS only removes the seam."
+	},
+	"multi-field": {
+		css: c([
+			"form-group",
+			"input-group",
+			"fieldset"
+		], "patterns/forms.css"),
+		wc: {
+			tag: "wc-multi-field",
+			registered: true,
+			adds: "add/remove repeating field rows"
+		},
+		bricks: "vitops-multi-field",
+		use: "`<wc-multi-field>` around a field template. One row submits fine with no JS."
+	},
+	"color-scheme-toggle": {
+		css: c([], "patterns/icon.css"),
+		wc: {
+			tag: "wc-color-scheme-toggle",
+			registered: true,
+			adds: "segmented light/dark/system control; persists the choice (consent-gated)"
+		},
+		bricks: "vitops-color-scheme-toggle",
+		use: "`<wc-color-scheme-toggle></wc-color-scheme-toggle>`. Renamed from `<color-scheme-toggle>` in 4.0. Shadow DOM, so it is absent rather than broken without JS."
+	},
+	consent: {
+		css: c([
+			"consent",
+			"consent__body",
+			"consent__options",
+			"consent__actions"
+		], "patterns/consent.css"),
+		wc: {
+			tag: "wc-consent",
+			registered: false,
+			bundle: "@getvitops/core/consent",
+			adds: "the permission gate itself — activates `type=\"text/plain\"` tags on grant"
+		},
+		astro: [{
+			component: "@getvitops/astro/CookieConsent.astro",
+			wraps: "wc"
+		}],
+		use: "`<CookieConsent />`. Its own Lit-free bundle so a site needing consent does not download a rendering framework."
+	},
+	"theme-editor": {
+		css: c([
+			"ed-panel",
+			"ed-launch",
+			"ed-input"
+		], "patterns/theme-editor.css"),
+		wc: {
+			tag: "wc-theme-editor",
+			registered: false,
+			bundle: "@getvitops/core/editor",
+			adds: "live `:root` token overrides, export as CSS or a config patch"
+		},
+		use: "`<wc-theme-editor manifest=\"…\">`. TOOLING, not a page pattern — the one deliberate tier-2 exception, quarantined in its own opt-in bundle."
+	},
+	"color-wheel": {
+		css: c([]),
+		wc: {
+			tag: "wc-color-wheel",
+			registered: false,
+			adds: "hue/chroma wheel input",
+			bundle: "(none — editor-v2 track, not yet bundled)"
+		},
+		use: "Not shipped. Registered but absent from every bundle, so the tag is inert in a consumer project."
+	},
+	"oklch-color-picker": {
+		css: c([]),
+		wc: {
+			tag: "wc-oklch-color-picker",
+			registered: false,
+			adds: "OKLCH L/C/H picker",
+			bundle: "(none — editor-v2 track, not yet bundled)"
+		},
+		use: "Not shipped. See `color-wheel`."
+	},
+	"icon-picker": {
+		css: c([], "patterns/icon.css"),
+		wc: {
+			tag: "wc-icon-picker",
+			registered: false,
+			adds: "browses the semantic icon map for the configured set",
+			bundle: "(none — editor-v2 track, not yet bundled)"
+		},
+		use: "Not shipped. See `color-wheel`."
+	},
+	"typography-config": {
+		css: c([]),
+		wc: {
+			tag: "wc-typography-config",
+			registered: false,
+			adds: "type role editor",
+			bundle: "(none — editor-v2 track, not yet bundled)"
+		},
+		use: "Not shipped. See `color-wheel`."
+	},
+	details: {
+		css: c([
+			"details",
+			"details-trigger",
+			"details-icon"
+		], "patterns/details.css", true),
+		astro: a("Details", "css"),
+		use: "`<Details>` — or hand-write `<details>`. No JS at either tier; `::details-content` animates in CSS."
+	},
+	drawer: {
+		css: c([
+			"drawer",
+			"drawer--start",
+			"drawer--end"
+		], "patterns/drawer.css", true),
+		astro: a("Drawer", "css"),
+		use: "`<Drawer>` — `<dialog class=\"drawer\">` plus an Invoker Commands trigger. No JS."
+	},
+	popover: {
+		css: c([
+			"popover",
+			"popover-trigger",
+			"popover-anchor"
+		], "patterns/popover.css", true),
+		astro: a("Popover", "css"),
+		use: "`<Popover>` — native Popover API + CSS Anchor Positioning. No JS."
+	},
+	navshell: {
+		css: c([
+			"navshell",
+			"navshell__bar",
+			"navshell__panel",
+			"navshell-toggle"
+		], "patterns/navshell.css"),
+		astro: [...a("NavShell", "css"), ...a("NavShellToggle", "css")],
+		use: "`<NavShell>` with a `nav` slot, plus `<NavShellToggle>` if the toggle must live outside the shell."
+	},
+	subgrid: {
+		css: c([
+			"subgrid",
+			"subgrid-card",
+			"pricing-grid"
+		], "patterns/subgrid.css"),
+		astro: a("Subgrid", "css"),
+		use: "`<Subgrid>` — emits `<ul class=\"grid\">` with row-subgrid children so cards align across tracks."
+	},
+	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."
+	},
+	icon: {
+		css: c([
+			"icon",
+			"icon-button",
+			"icon-mask"
+		], "patterns/icon.css"),
+		astro: a("Icon", "css"),
+		bricks: "vitops-icon",
+		use: "`<Icon name=\"menu\" />`. Names are semantic and resolve per configured set; a name containing `:` passes through."
+	},
+	split: {
+		css: c([
+			"split",
+			"split-1-2",
+			"split-reverse"
+		], "layout.css"),
+		bricks: "vitops-split",
+		use: "`.split` plus a ratio class. Pure CSS; `md-split-1-2` for the responsive form."
+	},
+	centered: {
+		css: c([
+			"centered",
+			"spotlight",
+			"breakout",
+			"fullbleed"
+		], "layout.css"),
+		bricks: "vitops-centered",
+		use: "`.centered` as a track grid. Children land in `measure` — give it a track child to lay out inside."
+	},
+	sitenav: {
+		css: c([
+			"sitenav",
+			"sitenav__link",
+			"sitenav--drawer-start"
+		], "patterns/sitenav.css"),
+		bricks: "vitops-sitenav",
+		use: "`.sitenav` with `--bp-*` and a drawer direction. `<details>` + Invoker Commands, no JS."
+	},
+	"split-link": {
+		css: c([
+			"split-link",
+			"split-link__toggle",
+			"split-link__panel"
+		], "patterns/split-link.css"),
+		bricks: "vitops-split-link",
+		use: "`.split-link` — a link plus a disclosure toggle. No JS."
+	},
+	btn: {
+		css: c(["btn"], void 0, true),
+		use: "`<button>` gets it with no class; `.btn` carries it to other tags. `fill: false`, so states drive `color`."
+	},
+	cta: {
+		css: c(["cta", "cta-danger"], void 0, true),
+		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."
+	},
+	badge: {
+		css: c(["badge", "badge-indicator"], "patterns/tag.css", true),
+		use: "`.badge` — a STATIC label. Use `tag` if it is dismissable or editable."
+	},
+	tag: {
+		css: c([
+			"tag",
+			"tag__remove",
+			"tag__icon",
+			"tag-list"
+		], "patterns/tag.css", true),
+		use: "`.tag` — an editable/dismissable label. Its group is `label`, not `tag`."
+	},
+	status: {
+		css: c(["status", "status-dot--pulse"], "patterns/tag.css", true),
+		use: "`.status` with a role variant."
+	},
+	tooltip: {
+		css: c(["tooltip-trigger"], "patterns/tooltip.css", true),
+		use: "`.tooltip-trigger` — CSS only, anchor-positioned."
+	},
+	dialog: {
+		css: c([
+			"dialog__header",
+			"dialog__body",
+			"dialog__footer"
+		], "patterns/dialog.css", true),
+		use: "Native `<dialog>` plus the `.dialog__*` parts. No JS beyond `showModal()`."
+	},
+	dropdown: {
+		css: c(["dropdown--show-on-hover", "dropdown-menu"], "patterns/dropdown.css", true),
+		use: "`.dropdown` — Popover API based."
+	},
+	notification: {
+		css: c([
+			"notification",
+			"notification__title",
+			"notification__actions"
+		], "patterns/notification.css", true),
+		use: "`.notification` with a role variant; wrap in `<wc-dismissable>` to make it dismissable."
+	},
+	lightbox: {
+		css: c(["lightbox", "lightbox-dialog__content"], "patterns/lightbox.css", true),
+		use: "`.lightbox` thumbnails plus a `<dialog>`."
+	},
+	comment: {
+		css: c([
+			"comment",
+			"comment__author",
+			"comment-thread"
+		], "patterns/comment.css", true),
+		use: "`.comment` inside `.comment-thread`."
+	},
+	tabs: {
+		css: c(["tabs"], void 0, true),
+		use: "Generated pattern only; no structural partial and no component yet."
+	},
+	nav: {
+		css: c([
+			"menu",
+			"navbar",
+			"nav-collapse",
+			"drawer-nav"
+		], "patterns/nav.css", true),
+		use: "`.menu` / `.navbar`. See `navbar` and `navshell` for the newer shells."
+	},
+	navbar: {
+		css: c([
+			"navbar",
+			"navbar--sticky",
+			"nav-items"
+		], "patterns/navbar.css"),
+		use: "`.navbar` with `--start/--center/--end`."
+	},
+	banner: {
+		css: c([
+			"banner",
+			"banner__content",
+			"banner__action"
+		], "patterns/banner.css", true),
+		use: "`.banner`; wrap in `<wc-dismissable>` for a close button that works."
+	},
+	table: {
+		css: c(["table", "table-wrapper"], "patterns/table.css", true),
+		use: "`.table` inside `.table-wrapper`. See `entries` for the responsive-to-table pattern."
+	},
+	list: {
+		css: c(["facet-list", "filtered-list"], "patterns/list.css", true),
+		use: "`.facet-list` / `.filtered-list`."
+	},
+	"pull-quote": {
+		css: c(["pull-quote", "pull-quote__attribution"], "patterns/pull-quote.css", true),
+		use: "`.pull-quote`. Note the type role `quote` is separate."
+	},
+	combobox: {
+		css: c([
+			"combobox",
+			"combobox__listbox",
+			"combobox__option"
+		], "patterns/combobox.css", true),
+		use: "CSS shell only — the Lit component is a TODO, so it is not interactive yet."
+	},
+	forms: {
+		css: c([
+			"form-group",
+			"input-group",
+			"fieldset",
+			"custom-check"
+		], "patterns/forms.css", true),
+		use: "Wrap text controls in `.form-group` or `.input-group` — a bare `<input>` gets browser defaults."
+	},
+	cluster: {
+		css: c([
+			"cluster",
+			"cluster-between",
+			"cluster-start"
+		], "patterns/cluster.css"),
+		use: "`.cluster` plus an alignment variant."
+	},
+	code: {
+		css: c([], "patterns/code.css"),
+		use: "Element selectors on `pre`/`code`; no class needed."
+	},
+	grouped: {
+		css: c([
+			"group",
+			"group-inline",
+			"bordered"
+		], "patterns/grouped.css"),
+		use: "`.group-inline` / `.group-block` to join adjacent controls."
+	},
+	"horizontal-scroll": {
+		css: c(["horizontal-scroll"], "patterns/horizontal-scroll.css"),
+		use: "`.horizontal-scroll` for a snap strip."
+	},
+	masonry: {
+		css: c(["masonry", "masonry__item"], "patterns/masonry.css"),
+		use: "`.masonry` — CSS columns based."
+	},
+	media: {
+		css: c([
+			"media",
+			"media__figure",
+			"tile"
+		], "patterns/media.css"),
+		use: "`.media` for a figure/body pair; `.tile` for the stacked form."
+	},
+	overlay: {
+		css: c(["overlay"], "patterns/overlay.css"),
+		use: "`.overlay` for a scrim."
+	},
+	reveal: {
+		css: c([
+			"reveal",
+			"reveal-fade",
+			"reveal-h"
+		], "patterns/reveal.css"),
+		use: "`.reveal` — scroll-driven, no JS. Hosts the `interpolate-size` that `<details>` animation needs."
+	},
+	"scroll-based": {
+		css: c([
+			"parallax",
+			"scroll-progress",
+			"scroll-spy"
+		], "patterns/scroll-based.css"),
+		use: "Scroll-timeline driven; no JS."
+	},
+	"scroll-target": {
+		css: c(["scroll-target-group", "toc-sidebar"], "patterns/scroll-target.css"),
+		use: "`.scroll-target-group` for `:target-current` highlighting."
+	},
+	separator: {
+		css: c([
+			"separator",
+			"separator__text",
+			"separator__ornament"
+		], "patterns/separator.css"),
+		use: "`.separator`, optionally with text or an ornament."
+	},
+	stack: {
+		css: c(["stack", "stack__card"], "patterns/stack.css"),
+		use: "`.stack` for overlapping cards."
+	},
+	sticky: {
+		css: c([
+			"sticky",
+			"sticky-header",
+			"sticky-nav"
+		], "patterns/sticky.css"),
+		use: "`.sticky-header` etc. Pure CSS."
+	},
+	svg: {
+		css: c([
+			"svg-container",
+			"svg-shape",
+			"svg-animated"
+		], "patterns/svg.css"),
+		use: "`.svg-*` helpers for inline SVG."
+	},
+	"text-effects": {
+		css: c([
+			"typing",
+			"text-highlight",
+			"text-gradient-animate",
+			"text-stagger"
+		], "patterns/text-effects.css"),
+		use: "`.typing`, `.text-highlight`, … CSS animation only."
+	}
+};
+/** Pattern names, sorted — a stable order for docs and tests. */
+const TIER_NAMES = Object.keys(TIERS).sort();
+/** Every `wc-*` tag the manifest knows, whether shipped in `elements.js` or not. */
+function tierTags() {
+	return Object.entries(TIERS).filter(([, e]) => e.wc).map(([pattern, e]) => ({
+		tag: e.wc.tag,
+		registered: e.wc.registered,
+		pattern
+	}));
+}
+/**
+* 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
+* 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.
+*
+* `css` needs a predicate rather than a presence check, which is the non-obvious
+* part. `TierEntry.css` is required, so *every* entry has one — including the
+* editor-v2 track, whose entries carry `c([])`: no partial, no classes, not
+* generated. Treating the field's presence as membership would list four patterns
+* on the CSS page with nothing to show for them, and `color-wheel` genuinely has
+* no CSS. The other three tiers are optional fields, so presence is the test.
+*/
+function tierPatterns(tier) {
+	const has = (e) => {
+		switch (tier) {
+			case "css": return !!e.css.partial || e.css.classes.length > 0 || e.css.generated;
+			case "wc": return !!e.wc;
+			case "astro": return !!e.astro?.length;
+			case "bricks": return !!e.bricks;
+		}
+	};
+	return TIER_NAMES.filter((name) => has(TIERS[name])).map((name) => ({
+		name,
+		entry: TIERS[name]
+	}));
+}
+
 //#endregion
 //#region src/docs.ts
 /**
@@ -1770,13 +2471,13 @@ const ORDER = [
 	"split",
 	"centered",
 	"carousel",
-	"color-scheme-toggle",
+	"wc-color-scheme-toggle",
 	"wc-copy",
 	"dismissable",
 	"entries",
 	"image-compare",
 	"sitenav",
-	"wc-multifield",
+	"wc-multi-field",
 	"split-link",
 	"split-panel"
 ];
@@ -2515,26 +3216,26 @@ function childEntries(node) {
 	}];
 	return [];
 }
-function renderSchemaNode(label, node, required, depth, out) {
+function renderSchemaNode(label, node, required, depth, out, maxDepth = 3) {
 	const indent = "  ".repeat(depth);
 	const meta = `(${typeLabel(node)}${required ? ", required" : ""})`;
 	out.push(`${indent}- \`${label}\` ${meta}${node.description ? ` — ${node.description}` : ""}`);
-	if (depth >= 3) return;
+	if (depth >= maxDepth) return;
 	if (node.anyOf && !node.anyOf.every(isPrimitive)) {
 		for (const variant of node.anyOf) {
 			out.push(`${indent}  - *one of*${variant.description ? ` — ${variant.description}` : ""}`);
-			for (const c of childEntries(variant)) renderSchemaNode(c.label, c.node, c.required, depth + 2, out);
+			for (const c of childEntries(variant)) renderSchemaNode(c.label, c.node, c.required, depth + 2, out, maxDepth);
 		}
 		return;
 	}
-	for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, depth + 1, out);
+	for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, depth + 1, out, maxDepth);
 }
 /**
 * One `## <key>` section per top-level property: its description, then its
 * fields as a bullet tree. Shared by both references so the two cannot drift in
 * presentation — only in which schema they are pointed at.
 */
-function schemaSections(schema, heading = "##") {
+function schemaSections(schema, heading = "##", maxDepth = 3) {
 	const required = schema.required ?? [];
 	const sections = [];
 	for (const [key, node] of Object.entries(schema.properties ?? {})) {
@@ -2542,12 +3243,102 @@ function schemaSections(schema, heading = "##") {
 		const parts = [`${heading} \`${key}\`${required.includes(key) ? "" : " *(optional)*"}`];
 		if (node.description) parts.push("", node.description);
 		const bullets = [];
-		for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, 0, bullets);
+		for (const c of childEntries(node)) renderSchemaNode(c.label, c.node, c.required, 0, bullets, maxDepth);
 		if (bullets.length) parts.push("", ...bullets);
 		sections.push(parts.join("\n"));
 	}
 	return sections;
 }
+const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+})[c]);
+/** Sentinel for a lifted code span. Cannot occur in authored schema prose. */
+const CODE_SLOT = "\0";
+/**
+* The inline markdown the schema's `desc()` text actually uses, as HTML. Closed
+* on purpose, exactly like the legal renderer's subset: these strings are
+* authored in `schema.ts`, so the set is knowable rather than guessed at.
+*
+* Escaping happens before any markup is emitted, so a description containing `<`
+* cannot inject tags — several do (`<canonical>/<key>.txt`). Exported because the
+* only safe place for this is one tested function; a caller doing its own escaping
+* is how one of them eventually doesn't.
+*
+* **Code spans are lifted out FIRST, and that is load-bearing rather than tidy.**
+* `colors.utilities` describes the target families as `` `bg-*` ``, `` `text-*` ``,
+* `` `border-*` `` — literal asterisk WILDCARDS. Run emphasis over the raw string
+* and the `*` closing `bg-*` pairs with the one closing `text-*`, wrapping the
+* text between two unrelated utilities in `<em>` and eating both asterisks. The
+* prose then silently describes families that don't exist. Lifting code spans
+* first makes emphasis structurally unable to see inside them.
+*/
+const renderInlineMarkdown = (s) => {
+	const spans = [];
+	return escapeHtml(s.replace(/`([^`]+)`/g, (_, body) => {
+		spans.push(body);
+		return `${CODE_SLOT}${spans.length - 1}${CODE_SLOT}`;
+	})).replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/\*([^*\n]+)\*/g, "<em>$1</em>").replace(new RegExp(`${CODE_SLOT}(\\d+)${CODE_SLOT}`, "g"), (_, i) => `<code>${escapeHtml(spans[Number(i)] ?? "")}</code>`);
+};
+/**
+* Walk a JSON Schema into tree DATA.
+*
+* The same walk that produces the `authoring.md` / `config.md` bullet lists,
+* returned as a node model instead of a string. Returning data rather than markup
+* is deliberate and follows `roleColorUtilities()`: the *shape* of the tree is one
+* decision, and each medium renders it — markdown for agents, an accessible
+* `<details>` tree for the docs site. An HTML-emitting version here would be a
+* second source of the markup contract for `<wc-tree>` to drift from.
+*
+* Ids are dotted paths so a field can be linked to directly. Map-value and
+* array-item pseudo-labels are skipped in the path: `site.dns.records` reads
+* better than `site.dns.<domain>.records`, and neither `<domain>` nor `[items]`
+* is a real key.
+*/
+function schemaTreeNodes(schema, opts = {}) {
+	const { idPrefix = "", maxDepth = 12, prune = [] } = opts;
+	const pruned = new Set(prune);
+	const isPseudo = (label) => label === "<name>" || label === "[items]";
+	const join = (a, b) => a ? `${a}.${b}` : b;
+	/**
+	* Paths already claimed. An `anyOf` branch has no key of its own, so sibling
+	* branches sharing a field name resolve to the same dotted path
+	* (`site.templates.type` exists in all three template variants). Rather than
+	* invent a branch index that no real config document contains, the first
+	* occurrence keeps the id — which is what `getElementById` would have picked
+	* anyway, now true instead of accidental.
+	*/
+	const seen = /* @__PURE__ */ new Set();
+	const build = (label, n, required, path, depth) => {
+		const addressable = path !== "" && !isPseudo(label) && !seen.has(path);
+		if (addressable) seen.add(path);
+		const variants = n.anyOf && !n.anyOf.every(isPrimitive) ? n.anyOf : [];
+		const children = [];
+		if (depth < maxDepth && !pruned.has(path)) {
+			for (const v of variants) children.push({
+				label: "one of",
+				type: typeLabel(v),
+				required: false,
+				variant: true,
+				...v.description ? { description: v.description } : {},
+				children: childEntries(v).map((c) => build(c.label, c.node, c.required, isPseudo(c.label) ? path : join(path, c.label), depth + 2))
+			});
+			if (!variants.length) for (const c of childEntries(n)) children.push(build(c.label, c.node, c.required, isPseudo(c.label) ? path : join(path, c.label), depth + 1));
+		}
+		return {
+			label,
+			type: typeLabel(n),
+			required,
+			...n.description ? { description: n.description } : {},
+			...addressable ? { id: path } : {},
+			children
+		};
+	};
+	const required = schema.required ?? [];
+	return Object.entries(schema.properties ?? {}).filter(([key]) => key !== "$schema").map(([key, child]) => build(key, child, required.includes(key), join(idPrefix, key), 0));
+}
 function renderAuthoring() {
 	const sections = schemaSections(jsonSchema);
 	return `${frontmatter({
@@ -2592,7 +3383,7 @@ function renderConfig() {
 	const required = schema.required ?? [];
 	const sections = Object.entries(props).map(([key, node]) => {
 		const head = [`## \`${key}\`${required.includes(key) ? "" : " *(optional)*"}`, ...node.description ? ["", node.description] : []].join("\n");
-		const fields = schemaSections(node, "###").join("\n\n");
+		const fields = schemaSections(node, "###", key === "designSystem" ? 0 : 3).join("\n\n");
 		if (key === "designSystem") return [
 			head,
 			"The token set. Its `themes.<name>` entries are full design systems — every field of\none is in [authoring.md](authoring.md). Only the wrapper is listed here.",
@@ -2618,7 +3409,7 @@ function renderConfig() {
 
 The document that describes a **whole project**: the token set, the company, and the
 published site. It is the input every command that needs more than tokens is anchored
-to — \`vitops legal\`, \`vitops icons\`, \`vitops indexing\` — and it can also stand in for
+to — \`vitops legal\`, \`vitops icons\`, \`vitops search\` — and it can also stand in for
 a \`design-system.json\` anywhere the toolchain takes one, since it carries a full
 \`designSystem\`.
 
@@ -2911,14 +3702,14 @@ Raw hue steps (\`--color-<hue>-<step>\`) are the exception — they are fixed va
 ignores the appearance.
 
 Two attributes, one flip: \`data-brx-theme\` is Bricks' own (Bricks sets it on the
-WordPress target), \`data-theme\` is what the shipped \`<color-scheme-toggle>\` writes on
+WordPress target), \`data-theme\` is what the shipped \`<wc-color-scheme-toggle>\` writes on
 \`<html>\`, so the toggle works on every other target. Set either.
 
 The OS preference is a **second, opt-in block**. Set
 \`designSystem.defaultColorScheme: "system"\` in your site config and the same delta is emitted again inside
 \`@media (prefers-color-scheme: dark)\`, under
 \`${SYSTEM_DARK_SEL}\` — i.e. whenever no explicit choice has been made. That is what makes
-\`<color-scheme-toggle>\`'s "System" position resolve to the OS (it *removes* the attribute,
+\`<wc-color-scheme-toggle>\`'s "System" position resolve to the OS (it *removes* the attribute,
 so without this block it fell through to light), and it gives a no-JS page the OS
 appearance, which the toggle alone never could. An explicit light choice still wins.
 
@@ -3128,6 +3919,138 @@ token guaranteed legible over a surface in both appearances. \`default_role\` co
 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`.
+*
+* 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
+* arrives the other way round: it knows the *pattern* it needs and has to be told
+* which tiers offer it and which call to make. Four docs would mean an agent
+* fetching `components/astro` learns `<Tree />` exists and never learns it must not
+* wrap it in `<wc-tree>` — the composition only exists between the tiers, so the
+* projection that serves agents is the one that keeps them together.
+*
+* `ds` is read for one thing: whether each config-authored pattern is actually
+* declared in THIS consumer's `patterns.items`. `TIERS.css.generated` records that a
+* pattern is *of that kind* against this repo's reference config; it cannot know
+* that a given consumer dropped `card`. Reporting a class that this config emits no
+* CSS for is the failure worth preventing here.
+*/
+function renderComponentsConcept(ds) {
+	const declared = new Set(Object.keys(ds.patterns?.items ?? {}));
+	const cell = (s) => s.replace(/\|/g, "\\|");
+	const code = (s) => `\`${s}\``;
+	const list = (xs) => xs.map(code).join(", ");
+	const tiersOf = (name) => [
+		"css",
+		"wc",
+		"astro",
+		"bricks"
+	].filter((t) => tierPatterns(t).some((p) => p.name === name));
+	const overview = TIER_NAMES.map((name) => {
+		const e = TIERS[name];
+		return `| ${code(name)} | ${tiersOf(name).join(" · ")} | ${cell(e.use)} |`;
+	}).join("\n");
+	const wc = tierPatterns("wc").map(({ name, entry }) => {
+		const w = entry.wc;
+		const ships = w.registered ? code("elements.js") : w.bundle ? code(w.bundle) : "nothing";
+		return `| ${code(`<${w.tag}>`)} | ${code(name)} | ${ships} | ${cell(w.adds)} |`;
+	}).join("\n");
+	const astro = tierPatterns("astro").flatMap(({ name, entry }) => entry.astro.map((a) => `| ${code(a.component)} | ${code(name)} | ${a.wraps === "wc" ? `the ${code(`<${entry.wc.tag}>`)} tag, fallback inside` : "tier-1 markup — no web component"} |`)).join("\n");
+	const bricks = tierPatterns("bricks").map(({ name, entry }) => `| ${code(entry.bricks)} | ${code(name)} |`).join("\n");
+	const css = tierPatterns("css").map(({ name, entry }) => {
+		const c = entry.css;
+		const config = !c.generated ? "—" : declared.has(name) ? "declared" : "**absent from this config — no CSS emitted**";
+		return `| ${code(name)} | ${c.partial ? code(c.partial) : "—"} | ${c.classes.length ? list(c.classes) : "—"} | ${config} |`;
+	}).join("\n");
+	const hooks = [...new Set(Object.values(BASE_HOOK))].map((sfx) => code(`--${sfx}-<pattern>`)).join(", ");
+	const unshipped = tierPatterns("wc").filter(({ entry }) => !entry.wc.registered && entry.wc.bundle?.startsWith("(none")).map(({ entry }) => code(`<${entry.wc.tag}>`)).join(", ");
+	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.",
+		resource: DS_PATH,
+		tags: [
+			"components",
+			"web-components",
+			"astro",
+			"bricks",
+			"tiers",
+			"design-system"
+		]
+	})}
+
+# Components
+
+A pattern is provided by up to four 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.
+
+## Choosing
+
+**Use the highest-numbered 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.
+
+The trap is composing two tiers by hand. When ${code("wraps")} below says the Astro component
+emits the tag, that one call is the whole composition —
+${code("<wc-tree><Tree /></wc-tree>")} nests two elements on one tree. A tier-3 component that
+would need runtime JS is in the wrong tier: build a web component instead and have the wrapper
+emit its tag.
+
+## Every pattern
+
+| Pattern | Tiers | What to write |
+| --- | --- | --- |
+${overview}
+
+## Web components
+
+Shipped as feature-detected, deferred ES-module bundles. ${code("elements.js")} carries the
+registered set; ${code("<wc-consent>")} and ${code("<wc-theme-editor>")} ship separately, the
+first so a site needing consent does not download a rendering framework, the second because it
+is tooling and opt-in per consumer.
+
+| Tag | Pattern | Ships in | What JS adds over the fallback |
+| --- | --- | --- | --- |
+${wc}
+
+${unshipped ? `${unshipped} are **registered but in no bundle** (the editor-v2 track). The tags are inert in a consumer project — they are listed so that "the tag does nothing" is documented rather than discovered.` : ""}
+
+## Astro components
+
+| Component | Pattern | Emits |
+| --- | --- | --- |
+${astro}
+
+## Bricks elements
+
+Controls, defaults and seeded children for each are in [the elements reference](../bricks/elements.md).
+
+| Element | Pattern |
+| --- | --- |
+${bricks}
+
+## CSS
+
+${code("patterns.items")} patterns get the full token cascade — ${code("base")} declarations,
+${code("states")}, role variants and override hooks (${hooks}); see
+[component patterns](patterns.md). A structural partial has none of those. The class lists below
+are representative, not exhaustive — [the class vocabulary](../css/classes.md) states the naming
+rules that generate them all.
+
+| Pattern | Partial | Classes | ${code("patterns.items")} |
+| --- | --- | --- | --- |
+${css}
+`;
+}
 function renderTopIndex() {
 	return `${INDEX_NOTE}
 
@@ -3142,7 +4065,7 @@ variable-driven CSS framework plus progressively-enhanced web components, genera
 * [Authoring reference](authoring.md) - every design-system.json field, generated from the JSON Schema
 * [Config reference](config.md) - every field of the three-section config (designSystem / organization / site), generated from the JSON Schema
 * [Output formats](formats.md) - tailwind vs css vs bricks vs design: what's emitted, what the platform provides, which utilities Tailwind owns
-* [Concepts](concepts/) - the colour system, type/space scales, and pattern CSS architecture
+* [Concepts](concepts/) - the colour system, type/space scales, pattern CSS architecture, the four component tiers, icons, and the consent / tracking / search / legal subsystems
 * [CSS framework](css/) - the class vocabulary (colour, type, space, layout, animation, component patterns), stated as naming rules
 * [Bricks Builder](bricks/) - custom elements and how to style them
 `;
@@ -3204,7 +4127,7 @@ astro-icon is **zero-config on a static build**. Under \`output: 'server'\` it b
 *every icon in a set* unless given an \`include\` map — which is why projects end up
 hand-maintaining one.
 
-The \`icons\` option on \`getvitops()\` derives it by scanning your source, merged with
+The \`icons\` option on \`vitops()\` derives it by scanning your source, merged with
 whatever you declare. On a static build **no include is passed at all**: there is
 nothing to trim there, and a list could only drop a glyph the scan couldn't see.
 
@@ -3259,6 +4182,491 @@ Note \`.icon-mask\` is a different thing: the CSS-only adornment path used by
 is no markup to hang an \`<svg>\` on.
 `;
 }
+function renderConsentConcept() {
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops consent — a demand-driven permission gate",
+		description: "How the consent gate works: inert `type=\"text/plain\"` tags, demand-driven prompting, three-valued choices, and the invariants that make the gate real rather than a promise.",
+		resource: CONFIG_PATH,
+		tags: [
+			"consent",
+			"cookies",
+			"privacy",
+			"gdpr",
+			"analytics"
+		]
+	})}
+
+# The consent gate
+
+\`@getvitops/core/consent\` is a **general permission gate, not an analytics feature**. Anything
+marked \`data-consent="<category>"\` waits on one visitor choice — a third-party tag, an A/B
+assignment, a personalisation cookie, an embedded map. It carries no Lit and is a separate
+bundle from \`elements.js\`, because consent is a legal requirement: a site that needs it must
+not be made to download a rendering framework first.
+
+Categories are \`necessary\`, \`analytics\`, \`marketing\`, \`preferences\`.
+
+## Gating something
+
+A gated script renders **inert**, with its URL parked on \`data-src\`:
+
+\`\`\`html
+<script
+  type="text/plain"
+  data-vitops-tag
+  data-consent="analytics"
+  data-consent-cookies="_ga,_ga_*"
+  data-src="https://example.com/analytics.js"
+><\/script>
+\`\`\`
+
+⚠️ **\`type="text/plain"\` is what makes the gate real. Never give a gated tag a live \`src\`.**
+The browser neither parses the body nor fetches the library, so an undecided visitor's page
+issues **no third-party request at all**. A gate that instead loads a script and politely asks
+it not to track is a promise, not a gate.
+
+\`data-consent-cookies\` is written by whoever emitted the tag, because that is who knows what
+the provider sets. It is what a revoke clears.
+
+## Demand-driven: two different ideas
+
+**Offered** categories are a build-time fact — which rows \`<CookieConsent />\` renders. The
+default is deliberately generous; a hidden row costs nothing.
+
+**Demanded** categories are a runtime fact — what something has actually asked for and the
+visitor hasn't answered. The banner appears only when a demand is outstanding, so **a site
+whose only provider is cookieless never interrupts anyone.**
+
+Demand is registered by:
+
+- a gated element **reaching its loading strategy** — so an \`idle\` tag asks after \`load\`, off
+  the LCP path, and an \`interaction\` tag asks only once the visitor acts; or
+- an explicit \`require()\` / \`request()\`.
+
+## The runtime API
+
+\`window.vitopsConsent\`, plus a \`vitops:consent\` \`CustomEvent\` on \`document\`.
+
+| Call | Does |
+| --- | --- |
+| \`granted(cat)\` | Is it granted? **Passive — does not prompt.** |
+| \`require(cat)\` | Declare a need *now* and report whether it's granted. **This is what raises the banner.** Synchronous. |
+| \`request(cat)\` | \`require()\`, but resolves once the visitor answers *this* category. |
+| \`needed()\` | Is a prompt warranted? True only if something demanded an unanswered category. |
+| \`demanded()\` | What has asked, this page view. |
+| \`set(patch)\` | Record a decision for exactly these categories. |
+| \`open()\` | Re-show the banner without discarding the current choice. |
+| \`reset()\` | Forget the choice and re-prompt. |
+
+⚠️ If you want a side effect to be *possible*, you must \`require()\` it. Calling \`granted()\`
+and doing nothing else is a **permanent no-op** on any site where nothing else demands that
+category: it is never offered, never granted, and your write never happens — silently.
+
+## An absent gate means "store freely"
+
+\`consent.js\` and \`elements.js\` are both deferred with no ordering between them, so a component
+can upgrade and be clicked before the gate exists. \`<Head />\` therefore emits a synchronous
+inline **stub** that answers \`false\` and queues; the runtime replays the queue on load.
+
+That makes the absence of \`window.vitopsConsent\` meaningful: it reliably means **this site has
+no gate**. Read it as *store freely* — never as *denied*.
+
+Because the stub is not the full API, listen for the \`vitops:consent\` event rather than calling
+\`subscribe()\`, which the stub does not have.
+
+## Three-valued, and why it matters
+
+The cookie (\`vitops_consent\`, v2) records each category as \`true\` / \`false\` / **\`null\`**.
+"Not asked" is a third value, not a synonym for "declined" — and only \`null\` can be
+re-prompted. That is what lets a \`preferences\` demand arrive *after* an \`analytics\` prompt was
+already answered.
+
+Three consequences:
+
+- **Nothing is stored until the visitor chooses.** Absence of the cookie is *undecided*, and
+  undecided denies everything but \`necessary\`. If merely showing the banner wrote state, the
+  banner would be the thing it asks permission for.
+- **A corrupt or wrong-version cookie re-prompts.** It does not read as "decided, all denied" —
+  that safe-looking read strands a visitor who wants to opt in with no way to say so.
+- **A patch must cover exactly the categories a showing put on screen.** \`<wc-consent>\` builds
+  its own patch rather than calling \`acceptAll()\`, because "Accept" on a preferences-only
+  prompt that also granted analytics would be consent nobody gave. \`acceptAll()\` /
+  \`rejectAll()\` mean *literally every* optional category — widening a patch to "all" is the
+  easy version of this bug.
+
+## Revoking reloads
+
+An already-executing tracker cannot be unloaded. Clearing its cookies only stops it identifying
+the visitor *next* time, while the running instance keeps reporting until the document goes
+away — so a revoke clears the named cookies and **reloads**. (\`reloadOnRevoke = false\` defers
+that to the next navigation.)
+
+## The notice must match what loads
+
+The same config facts drive the **generated cookie notice** — see
+[legal.md](legal.md). \`site.analytics.clarityId\` is what makes the notice name Clarity; the
+same provider in \`vitops({ analytics })\` is what makes the tag load. The Astro integration
+**warns when the two disagree**, because a site running a tag its own notice omits is a
+compliance defect, not a documentation gap.
+
+## Reference consumer
+
+\`<wc-color-scheme-toggle>\` applies the chosen scheme **immediately** and gates only the
+\`localStorage\` write. Nothing about honouring a visitor's click needs permission; remembering
+it does.
+`;
+}
+function renderTrackingConcept() {
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops conversion tracking — ad attribution and notifications",
+		description: "How an ad click becomes a notified conversion: the `_ac` cookie, consent-demanding capture, the pure notification planner, and the Cloudflare email channel.",
+		resource: CONFIG_PATH,
+		tags: [
+			"tracking",
+			"attribution",
+			"conversions",
+			"notifications",
+			"consent"
+		]
+	})}
+
+# Conversion tracking
+
+A visitor arrives on an ad carrying a click ID; \`<Tracking />\` captures it into the
+first-party **\`_ac\`** cookie; when they later submit a form or tap a \`tel:\` link,
+\`createConversionRoute()\` reads the cookie back and notifies whoever the config names.
+
+\`\`\`json
+{
+  "site": {
+    "tracking": { "enabled": true, "category": "marketing" },
+    "notifications": { "email": "leads@example.com" }
+  }
+}
+\`\`\`
+
+A bare address is shorthand for \`{ provider: "cloudflare", to }\`. The recipient otherwise
+falls back to the primary location's email, and the sender to \`noreply@<domains.canonical>\`.
+
+## Where each piece lives
+
+| Layer | Module | Why there |
+| --- | --- | --- |
+| Attribution vocabulary + cookie | \`@getvitops/utils/tracking\` | Needed on **both** sides of the wire |
+| Plan / render / send | \`@getvitops/utils/notify\` | Pure planner, I/O sender |
+| Capture script, \`<Tracking />\`, route factory | \`@getvitops/astro\` | Beside the analytics components |
+
+Both utils entries are **separate subpaths** because they are the only modules that run in a
+**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.
+
+## The capture demands consent
+
+\`_ac\` is a 90-day identifier tying a visitor to an ad, so it waits on \`marketing\` (override
+with \`site.tracking.category\`).
+
+⚠️ The script calls **\`require()\`**, not \`granted()\` — \`require()\` is what *raises the
+banner*. A passive \`granted()\` here is a permanent no-op: nothing else on a page demands
+\`marketing\`, so it is never offered, never granted, and \`_ac\` is never written — silently, on
+every gated site. The integration adds \`marketing\` to the offered categories when tracking is
+on, so there is a row for the category the script will ask about.
+
+**Only an arrival that carried something asks.** The demand is guarded on the URL actually
+holding a click ID or UTM, so an organic visitor — who has nothing to attribute — is never
+interrupted. That is demand-driven consent applied to attribution.
+
+**The capture is synchronous; only the write waits.** Reading the query string is not storage
+and needs no permission; *keeping* it does. The click ID is in the URL only on the landing
+page, so deferring the read would lose it outright.
+
+The marker element carries \`data-consent\` but deliberately **not** \`data-vitops-tag\`: the
+scan never tries to "activate" it (it is ungated by design), while the revoke path — which
+queries \`[data-consent="…"]\` — still finds it and clears \`_ac\`.
+
+## The event is the abstraction
+
+\`ConversionEvent\` is the *fact*; how it reads belongs to the channel. That is what lets an SMS
+channel render 160 characters from the same event an email renders in full.
+
+**The plan is pure and says why anything is skipped.** \`planNotifications\` touches no network
+and no binding, so a misconfigured site can be told exactly why no notification will arrive — a
+silently unsent conversion notification is indistinguishable from no conversion.
+
+## The email channel
+
+Cloudflare Email Sending's **current** binding — structured
+\`env.EMAIL.send({ to, from, subject, html, text })\`, not the legacy \`EmailMessage\` plus
+hand-built MIME. The binding is **passed in, never imported**, so utils takes no Cloudflare
+dependency.
+
+Only transient codes are retried. \`E_SENDER_NOT_VERIFIED\` and friends are surfaced
+**verbatim**, because nothing here can check whether the sending domain was onboarded — run:
+
+\`\`\`sh
+wrangler email sending enable <domain>
+\`\`\`
+
+A generic "send failed" would hide the one thing worth knowing.
+
+Only \`email\` is implemented. \`sms\` and \`persist\` are a planned seam
+(\`NotificationsConfig\` plus a sender with \`sendEmail\`'s signature); one channel is not enough
+to know what the abstraction should be.
+
+## Disclosure
+
+\`_ac\` is disclosed by the generated cookie notice as a first-party cookie. It has to be stated
+explicitly: no provider table would ever name a first-party cookie, so a site running
+attribution alongside a **cookieless** analytics provider would otherwise be described as
+setting no cookies at all. See [legal.md](legal.md).
+`;
+}
+function renderSearchConcept() {
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops search — Search Console onboarding and deploy notification",
+		description: "What search engines actually accept, why the Indexing API is deliberately not wired, and how `vitops search setup` and `vitops search notify` work.",
+		resource: CONFIG_PATH,
+		tags: [
+			"seo",
+			"search-console",
+			"indexnow",
+			"sitemap",
+			"indexing"
+		]
+	})}
+
+# Search
+
+Two commands, both anchored to a full config:
+
+- **\`vitops search notify\`** — tell search engines a deploy happened (from \`site.seo.indexing\`).
+- **\`vitops search setup\`** — onboard domains into Search Console (from \`site.searchConsole\`).
+
+## Start from what engines actually accept
+
+The obvious assumption is wrong, and every design decision here follows from that:
+
+- **Google exposes no "request indexing" API.** The button in the Search Console UI is not in
+  the Search Console API or anywhere else, and the **URL Inspection API is read-only**.
+- **The sitemap ping endpoint was removed in June 2023.** \`google.com/ping?sitemap=\` is a no-op.
+- **The Indexing API is scoped to \`JobPosting\` / \`BroadcastEvent\`.** It accepts other URLs and
+  discards them; general use violates its terms, with *your own* GCP project on the line.
+  ⚠️ **Deliberately not wired. Do not add it.**
+- **Google does not participate in IndexNow.** Bing, Yandex, Naver, Seznam and Yep do.
+
+So \`search notify\` does every sanctioned thing and then **verifies**: resubmit the sitemap,
+ping IndexNow, and \`--check\` inspects \`priorityUrls\` and exits non-zero on one Google hasn't
+indexed. That last part is what actually replaces the manual Search Console visit.
+
+⚠️ Never describe this as making Google re-index faster. It cannot.
+
+## \`search notify\`
+
+- **The pure/I-O split is the point.** The planner decides everything — which URLs, which
+  channels, why each was skipped — and touches no network, no filesystem, no clock. That is what
+  makes \`--dry\` a *complete* account of a run rather than an approximation.
+- **\`lastmod\` is not a nice-to-have, it is the mechanism.** The changed-URL diff compares each
+  sitemap entry's \`<lastmod>\` against a stored snapshot. With no lastmod the diff can see pages
+  appear and disappear but **never see one change** — so an edited page is never resubmitted, and
+  the command looks healthy while doing less than it appears to. It counts lastmod-less entries
+  and says so every run.
+
+  \`gitLastmod()\` in \`@getvitops/astro\` derives real dates from \`git log\`. It is an exported
+  helper rather than a \`sitemap\` option because it shells out to git and returns **nothing**
+  from a shallow CI clone (\`fetch-depth: 1\`). It leaves an unmatched URL alone rather than
+  stamping the build time: Google weighs lastmod only while it stays consistent with what
+  actually changed, so a site that stamps every page every deploy teaches it to distrust the
+  field site-wide.
+- **The \`noindex\` gate reads the environment, so the URLs must too.** The run is refused
+  entirely when the resolved environment's \`robots\` contains \`noindex\` — submitting a staging
+  host to IndexNow publishes it to several engines and invites them to crawl it, which a later
+  directive does not undo. Origins therefore derive from \`site.environments[env].url\` **before**
+  \`domains.canonical\`: the canonical is the *production* origin, so deriving from it while
+  notifying staging would submit production URLs the gate would not catch.
+- **Verify the IndexNow key file before submitting.** A submission whose key file is unreachable
+  returns \`403\`, but one whose key file is *reachable and stale* is accepted with \`202\` and then
+  silently discarded. Only a prior GET distinguishes "submitted" from "submitted and ignored".
+  The key is **not a secret** — the engine fetching it back is the ownership proof — so it lives
+  in the config, and the Astro integration writes \`public/<key>.txt\` from it.
+- **Write the snapshot last, and only on success.** Writing it eagerly records URLs as notified
+  that never were; because the next run diffs against it, one transient \`503\` would drop those
+  pages from every future run — silently and permanently. A corrupt or absent snapshot reads as
+  "submit everything, and say so", never as "nothing changed".
+
+## \`search setup\`
+
+Automates the otherwise-manual DNS-paste / wait / verify / add-property dance.
+\`site.searchConsole\` is keyed by bare hostname (mirroring \`site.dns\`):
+
+\`\`\`json
+{
+  "site": {
+    "searchConsole": {
+      "example.com": {
+        "delegatedOwners": ["dev@example.com"],
+        "fullUserGroup": "seo@example.com"
+      }
+    }
+  }
+}
+\`\`\`
+
+Per domain it ensures the apex verification TXT in Cloudflare, verifies ownership via the Site
+Verification API (\`DNS_TXT\`), adds the \`sc-domain:\` property, then adds any
+\`delegatedOwners\`. The verification token is fetched live and written to DNS — never stored in
+the config.
+
+- **Idempotency lives in the planner.** A step whose desired state already holds resolves to
+  \`skip\`, so re-running an onboarded domain is a no-op **by construction**, not because the
+  executors check twice. \`--check\` reports drift, exits non-zero and mutates nothing;
+  \`--dry\` prints the plan and stops.
+- **DNS is only ever created, never edited or deleted.** The command never removes a record, so
+  the Cloudflare executor simply has no update or delete verb.
+- **Verification retries with backoff, then reports PENDING — not failed.** \`DNS_TXT\`
+  verification fails until the record propagates, which is slow, not broken. A domain still
+  unverified after the last attempt is \`PENDING\`, and its property and owner steps are skipped
+  for that run. Re-run later.
+- **Search Console has no user/permission API.** Adding a Google Group as a **Full User** is
+  genuinely un-automatable, so \`fullUserGroup\` is surfaced as a **reminder** in the summary,
+  never attempted. That is distinct from \`delegatedOwners\`, which *are* automated — those are
+  Site Verification web-resource owners (an additive union, so an existing owner is never
+  dropped), a different concept from Search Console property users. Don't conflate them.
+
+## Credentials
+
+Always from the environment; never in the config. There is **one** token exchange and **two
+grants**, tracking where each command runs:
+
+| Grant | Env vars | Used by |
+| --- | --- | --- |
+| **Service account** (JWT bearer) | \`VITOPS_GSC_SERVICE_ACCOUNT\` (inline JSON) or \`GOOGLE_APPLICATION_CREDENTIALS\` (path) | \`search notify\` — never expires, right for CI |
+| **User OAuth** (refresh token) | \`VITOPS_GOOGLE_CLIENT_ID\` / \`_CLIENT_SECRET\` / \`_REFRESH_TOKEN\` | \`search setup\` — **required** |
+
+Cloudflare uses \`CLOUDFLARE_API_TOKEN\` (a \`Zone:DNS:Edit\` token; the standard "Edit zone DNS"
+template also carries the \`Zone:Read\` the zone-by-name lookup needs).
+
+\`search setup\` requires user OAuth because **verifying a site makes the caller an owner** of
+the property, and that should be a person, not a project robot. Note a refresh token can be
+revoked, and for an OAuth client still in *Testing* publishing status Google expires it after
+**7 days** — fine for a one-time human setup, bad for a deploy step.
+
+**\`search notify\` accepts either**, preferring the service account when both are set. Search
+Console does not care which identity calls it, and someone who has run \`search setup\` already
+holds a Google credential.
+
+⚠️ Do not add \`googleapis\` — an enormous dependency for a handful of REST endpoints in a CLI
+that installs into every consumer project. The JWT is minted with ~30 lines of \`node:crypto\`.
+`;
+}
+function renderLegalConcept() {
+	return `${frontmatter({
+		type: "Design Concept",
+		title: "Vitops legal documents — generated policy, terms and cookie notice",
+		description: "How the privacy policy, terms of service and cookie notice are derived from config facts, why the provider table exists, and the four delivery paths.",
+		resource: CONFIG_PATH,
+		tags: [
+			"legal",
+			"privacy",
+			"cookies",
+			"pipeda",
+			"compliance"
+		]
+	})}
+
+# Legal documents
+
+A privacy policy, terms of service and cookie notice, rendered from a full config: the company
+from \`organization\`, what the site actually *does* from \`site\`.
+
+It is a **sibling of the docs generator, not a \`generate()\` format** — structurally, not
+stylistically. \`generate()\` is keyed to a design system, so a "legal format" would be a format
+that ignores its own input.
+
+## The governing rule
+
+**The config records facts; the template owns prose.**
+
+Nothing in the derivation writes a sentence a lawyer would review, and no template invents a
+fact. That is what lets wording be corrected without touching your config, and your provider
+change land without touching prose.
+
+⚠️ It also means **the fix for a wrong policy is a corrected config.** Hand-editing the output
+is overwritten by the next build.
+
+## What derives from what
+
+- **The provider table is what makes derivation possible.** A policy naming Plausible while the
+  site runs GA is a compliance defect, not a typo — so the provider comes from *which analytics
+  ID is set*, whether \`site.security.turnstile.siteKey\` exists, and what
+  \`site.deployment.platform\` says. Never from a hand-maintained string.
+
+  It covers only what the schema can imply. Everything else — payment, CRM, mail — is declared
+  in \`site.legal.privacyPolicy.processors\` and flows through the same pipeline.
+
+- **\`cookies: []\` is meaningfully different from \`undefined\`.** It *asserts* a provider is
+  cookieless (Plausible), which the cookie notice states **positively** rather than omitting.
+
+- **"Stored in" is not the same fact as "reachable by".** A processor's \`storage\` is where the
+  information rests; \`operatorCountry\` is the jurisdiction that can compel the provider to hand
+  it over. Privacy law turns on foreign **access**, not merely foreign storage, so the two get
+  separate sentences — an Azure tenant in a Canadian region never moves the data and is still
+  subject to US law. \`country\` is shorthand asserting both, and combining it with either is
+  **rejected** rather than resolved by a silent rule: whether it narrows or adds is a
+  contradiction between two legal claims, not a formatting choice.
+
+  A \`storage\` entry may be \`scope\`d to a category, which is what makes a Canadian tenant
+  holding identity data abroad expressible. A country in the policy's own jurisdiction is not a
+  transfer and is filtered out — that is what stopped \`country: "Canada"\` rendering "outside of
+  Canada, including Canada". Only what the config states is asserted: hosts like Cloudflare
+  declare an \`operatorCountry\` and **no** storage, because anycast means the config cannot know
+  which region served a request, and "we don't know" is a fact.
+
+- **Form templates are the PII inventory.** \`site.templates\` entries of type \`form\` are the
+  only place the config says what personal information the site actually collects, so the
+  disclosed list derives from their fields. \`hidden\` fields and honeypots are **excluded** —
+  neither is visitor-supplied, and describing them as collected would be untrue.
+
+- **First-party cookies are declared, not detected.** The attribution cookie \`_ac\` is disclosed
+  this way; see [tracking.md](tracking.md).
+
+## The markdown subset is closed
+
+We author every template, so the renderer is exactly as capable as they are: \`#\`/\`##\`/\`###\`,
+\`- \` bullets, \`> \` quote, \`**strong**\`, \`\\\`code\\\`\`. **An unsupported construct is an error,
+not a silent degrade** — that is what stops a literal \`| --- |\` reaching a published page.
+
+Portable Text maps the \`> \` quote to a banner block and **drops the \`# \` heading**, which is
+EmDash's own title field.
+
+## Jurisdictions
+
+Adding one is: author three templates, add one enum member, add one registry key. The two are
+checked against each other at compile time, so skipping either **fails to compile** rather than
+rendering against the wrong body of law.
+
+⚠️ Only **\`ca\` (PIPEDA)** ships. Its prose names the Office of the Privacy Commissioner of
+Canada and frames transfers as "outside of Canada" — **do not reuse it for another
+jurisdiction.**
+
+## Delivery: one renderer, four consumers
+
+| Consumer | How |
+| --- | --- |
+| **any stack** | \`vitops legal [--doc <name>] [--format md\\|html\\|portable-text] [--out <dir>]\` — stdout without \`--out\`. Hugo, Eleventy or a hand-built WordPress theme need no integration code. |
+| **WordPress** | \`generate({ site })\` also emits \`dist/legal/*.html\`; \`[vitops_legal doc="privacy"]\` renders one. \`doc\` is matched against a fixed allowlist, because it lands in a filesystem read. |
+| **Astro** | \`vitops({ legal: { input, out } })\` — a sibling of \`css\`, not a widening of it. Regenerates on config change; writes markdown to a content collection. No route injection. |
+| **EmDash** | \`--format portable-text\`, pasted into the admin. |
+
+The CLI is the load-bearing one: it is the surface every consumer has regardless of stack.
+
+## The review banner
+
+Every document opens with a **non-optional** review banner. These are rendered from a template
+by a build tool; the one failure mode with real consequences is a consumer publishing one as-is.
+`;
+}
 function renderConceptsIndex() {
 	return `${INDEX_NOTE}
 
@@ -3269,7 +4677,12 @@ 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
 * [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
+* [Search](search.md) - what engines accept, Search Console onboarding, deploy notification
+* [Legal documents](legal.md) - policy/terms/cookie notice derived from config facts
 `;
 }
 function renderCssIndex() {
@@ -3318,7 +4731,12 @@ function generateDocs(ds, assetsDir) {
 		"concepts/color.md": renderColorConcept(ds),
 		"concepts/scales.md": renderScalesConcept(ds),
 		"concepts/patterns.md": renderPatternsConcept(ds),
+		"concepts/components.md": renderComponentsConcept(ds),
 		"concepts/icons.md": renderIconsConcept(),
+		"concepts/consent.md": renderConsentConcept(),
+		"concepts/tracking.md": renderTrackingConcept(),
+		"concepts/search.md": renderSearchConcept(),
+		"concepts/legal.md": renderLegalConcept(),
 		"css/index.md": renderCssIndex(),
 		"css/classes.md": renderCssClasses(ds),
 		"bricks/index.md": renderBricksIndex(),
@@ -3757,6 +5175,26 @@ across every pattern. Focus rings are never removed, only restyled.
 //#endregion
 //#region src/legal/providers.ts
 /**
+* What the config already tells us about third parties that receive personal
+* information.
+*
+* A privacy policy's riskiest sentence is the one naming service providers: if
+* it says "Plausible" while the site runs Google Analytics, the document is a
+* compliance defect, not a typo. The site config already records which analytics
+* ID is set, whether Turnstile is deployed and where the site is hosted — so the
+* sentence derives from those signals rather than from a hand-maintained string
+* that drifts the moment someone swaps providers.
+*
+* Presence of the key is the signal, matching how `analytics` already works
+* (provider identity is implied by which ID is set, not by an enum).
+*
+* This table is deliberately small and covers only what the schema can imply.
+* Everything else — payment processors, CRMs, mail senders — is declared by the
+* consumer in `legal.privacyPolicy.processors`, which flows through the same
+* pipeline. This is not a directory of the web; it's the set of providers the
+* toolchain itself can vouch for.
+*/
+/**
 * The providers the config can imply. Keyed for testability — a test can assert
 * a given config resolves to a given key without matching on prose.
 */
@@ -3810,28 +5248,28 @@ const KNOWN_PROCESSORS = {
 	turnstile: {
 		name: "Cloudflare Turnstile",
 		purpose: "bot protection on forms",
-		country: "the United States",
+		operatorCountry: "the United States",
 		privacyUrl: "https://www.cloudflare.com/privacypolicy/",
 		cookies: ["cf_clearance"]
 	},
 	cloudflare: {
 		name: "Cloudflare",
 		purpose: "website hosting and content delivery",
-		country: "the United States",
+		operatorCountry: "the United States",
 		privacyUrl: "https://www.cloudflare.com/privacypolicy/",
 		cookies: []
 	},
 	vercel: {
 		name: "Vercel",
 		purpose: "website hosting",
-		country: "the United States",
+		operatorCountry: "the United States",
 		privacyUrl: "https://vercel.com/legal/privacy-policy",
 		cookies: []
 	},
 	netlify: {
 		name: "Netlify",
 		purpose: "website hosting",
-		country: "the United States",
+		operatorCountry: "the United States",
 		privacyUrl: "https://www.netlify.com/privacy/",
 		cookies: []
 	}
@@ -3872,9 +5310,81 @@ function detectProcessorKeys(cfg) {
 * an explicit declaration is a statement of fact we have no grounds to drop.
 */
 function resolveProcessors(cfg) {
-	const detected = detectProcessorKeys(cfg).map((k) => matomoCountry(KNOWN_PROCESSORS[k], cfg.site));
+	const detected = detectProcessorKeys(cfg).map((k) => matomoLocation(KNOWN_PROCESSORS[k], cfg.site));
 	const declared = cfg.site.legal?.privacyPolicy?.processors ?? [];
-	return [...detected, ...declared];
+	return [
+		...detected,
+		...adProcessors(cfg),
+		...declared
+	].map(desugarCountry);
+}
+/**
+* The ad platforms `site.ads` links this site to, as processors.
+*
+* Derived from `AD_PLATFORMS` rather than written out here, because the cookie
+* names, the privacy URL and the opt-out are the *same facts* `vitops ads tags`
+* writes into `data-consent-cookies` — and the one failure that matters is those
+* two disagreeing. A pixel that sets `_fbp` while the notice omits it is a
+* compliance defect, and a revoke that clears a cookie the notice never mentioned
+* is the same defect seen from the other end.
+*
+* `enabled: false` keeps a property on record without emitting its tag, so nothing
+* is set and nothing is disclosed. Everything else with an id is live.
+*/
+function adProcessors(cfg) {
+	const ads = cfg.site.ads ?? {};
+	return AD_PROVIDER_KEYS.filter((provider) => {
+		const entry = ads[provider];
+		return entry != null && entry.enabled !== false && (entry.pixelId ?? entry.accountId) != null;
+	}).map((provider) => {
+		const platform = AD_PLATFORMS[provider];
+		return {
+			name: platform.name,
+			purpose: "advertising measurement and retargeting",
+			operatorCountry: platform.operatorCountry,
+			privacyUrl: platform.tag.privacyUrl,
+			cookies: platform.tag.cookies,
+			...platform.tag.optOut ? { optOut: platform.tag.optOut } : {}
+		};
+	});
+}
+/**
+* `country` → both facts it has always asserted.
+*
+* The sentence it fed claimed storage *and* legal reach in one breath ("may be
+* stored or processed in … including X. As a result … access requests from
+* governments … in those jurisdictions"). So expanding it to storage alone would
+* silently retract half of a claim consumers have already published. Expanding to
+* both is also what keeps the rendered output byte-identical for every config that
+* used the shorthand.
+*
+* `country` is left in place — it is public API and `PolicyVars.countries` still
+* reports it. When the explicit fields are present they win; `validateConfig`
+* rejects that combination, so it is unreachable through a validated config, but
+* `resolveProcessors` is exported and needs a defined answer regardless.
+*/
+function desugarCountry(p) {
+	if (!p.country) return p;
+	return {
+		...p,
+		storage: p.storage ?? [{ country: p.country }],
+		operatorCountry: p.operatorCountry ?? p.country
+	};
+}
+/**
+* Processors the config discloses but places nowhere.
+*
+* Such a processor cannot appear in the transfer disclosure — there is nothing true
+* to say about it — and today it vanishes from that section in silence, which is the
+* tidy-looking failure. Names only, and deliberately NOT on `PolicyVars`: that type
+* is the facts a template renders from, and a document must not editorialise about
+* its own gaps. The CLI reports these on stderr instead.
+*
+* Not a `validateConfig` error either: a bare `{ name, purpose }` validates today,
+* so rejecting it would make this a breaking change.
+*/
+function processorsMissingLocation(cfg) {
+	return resolveProcessors(cfg).filter((p) => !p.operatorCountry && !p.storage?.length).map((p) => p.name);
 }
 /**
 * Matomo is the one provider whose location the config actually knows.
@@ -3884,13 +5394,17 @@ function resolveProcessors(cfg) {
 * country. So the cross-border transfer sentence is asserted only for the case we
 * can see. Naming a transfer that isn't happening is the same class of error as
 * omitting one that is — the config records facts, and "we don't know" is a fact.
+*
+* This sets `storage`, not `operatorCountry`: Matomo Cloud genuinely holds the data
+* in the EU. InnoCraft is New Zealand-based, but nothing in the config sees that, so
+* no operator jurisdiction is asserted — the same rule, applied to the other fact.
 */
-function matomoCountry(processor, site) {
+function matomoLocation(processor, site) {
 	if (processor.name !== "Matomo") return processor;
 	const url = site.analytics?.matomo?.url ?? "";
 	return /\.matomo\.cloud/i.test(url) ? {
 		...processor,
-		country: "the European Union"
+		storage: [{ country: "the European Union" }]
 	} : processor;
 }
 
@@ -4041,21 +5555,43 @@ function derivePolicyVars(cfg) {
 		"improve our Site to better meet your needs"
 	]);
 	const ab = site.abTesting;
+	/**
+	* A site offering the `preferences` category stores at least one setting the
+	* visitor chose — `<wc-color-scheme-toggle>` writes `vitops-color-scheme` to local
+	* storage, gated on exactly this category. The banner asking about it while the
+	* notice never mentions it is the disclosure gap `providers.ts` exists to
+	* prevent, just on the browser-storage side rather than the third-party one.
+	*/
+	const hasPreferences = consent?.enabled === true && !!consent.categories?.includes("preferences");
+	/**
+	* `site.tracking.enabled` writes the `_ac` cookie: the click ID from the ad a
+	* visitor followed, kept for 90 days so a later enquiry can be attributed to
+	* the campaign that produced it. It is first-party and never leaves the site,
+	* which is exactly why nothing in the provider table would ever mention it —
+	* and why it has to be stated here instead. A notice that lists every
+	* third-party cookie while omitting the one the site sets itself is the same
+	* disclosure defect, pointed inward.
+	*/
+	const hasAdTracking = site.tracking?.enabled === true;
 	const cookieTracked = uniq([
 		"your IP address",
 		"the type of web browser and operating system used",
 		"the pages of the Site visited",
+		hasPreferences ? "display settings you have chosen, such as light or dark appearance" : void 0,
+		hasAdTracking ? "which advertisement or campaign brought you to our Site" : void 0,
 		ab?.enabled ? "which version of a page you were shown" : void 0,
 		hasSessionReplay ? "how you moved through and interacted with a page" : void 0
 	]);
 	const cookiePurposes = uniq([
 		"keep the Site functioning as you move between pages",
 		hasAnalytics ? "understand how our Site is used, in aggregate" : void 0,
+		hasPreferences ? "remember display settings you choose, between visits" : void 0,
+		hasAdTracking ? "attribute an enquiry to the advertisement that brought you here, for up to 90 days" : void 0,
 		hasSessionReplay ? "recognise a returning visit as part of the same session" : void 0,
 		ab?.enabled ? "keep you on a consistent version of the Site between visits" : void 0,
 		site.security?.turnstile?.siteKey ? "distinguish visitors from automated traffic" : void 0
 	]);
-	const cookieTool = consent?.enabled ? consent.type === "opt-in" ? "You may also choose which categories of cookies to allow using the consent banner shown when you first visit our Site, and you may change that choice at any time." : "You may also withdraw your consent to non-essential cookies at any time using the consent controls on our Site." : void 0;
+	const cookieTool = consent?.enabled ? consent.type === "opt-in" ? "You may also choose which categories of cookies to allow using the consent banner, which appears when something on the Site first needs your permission, and you may change that choice at any time." : "You may also withdraw your consent to non-essential cookies at any time using the consent controls on our Site." : void 0;
 	const usePurposes = uniq([
 		"respond to your inquiries",
 		"supply you with requested products or services",
@@ -4071,7 +5607,38 @@ function derivePolicyVars(cfg) {
 		...processors.filter((p) => p.optOut).map((p) => `You may opt out of ${p.name} directly at ${p.optOut}.`)
 	]);
 	const optOutOptions = uniq(["You may unsubscribe from any commercial e-mail we send using the \"unsubscribe\" link in that e-mail.", ...cookieOptOutOptions]);
-	const countries = list(uniq(processors.map((p) => p.country)));
+	/**
+	* The cross-border disclosure, as two facts rather than one flattened list.
+	*
+	* Order matters here — each step narrows what the next may claim:
+	*
+	* 1. Anything in this jurisdiction is not a transfer at all, so it is filtered
+	*    out. Without this, `country: "Canada"` rendered "outside of Canada,
+	*    including Canada".
+	* 2. An unscoped storage country is the BROAD claim; a scoped one covering the
+	*    same country would only narrow it, so it is dropped as redundant.
+	* 3. An operator country already named as storage adds no fact — "US law reaches
+	*    information stored in the US" is a sentence, not information.
+	*
+	* Steps 2 and 3 are what make the rendered output byte-identical for every config
+	* that used `country` (which desugars to both facts).
+	*
+	* No geography is inferred — "France" is not resolved into "the European Union".
+	* Only what the config states is asserted, which is the `matomoLocation` rule.
+	*/
+	const jurisdictionCountry = JURISDICTION_COUNTRIES[legal?.jurisdiction ?? "ca"];
+	const norm = (c) => c.trim().toLowerCase().replace(/^the\s+/, "");
+	const foreign = (c) => norm(c) !== norm(jurisdictionCountry);
+	const allStorage = processors.flatMap((p) => p.storage ?? []);
+	const unscoped = uniq(allStorage.filter((s) => !s.scope && foreign(s.country)).map((s) => s.country));
+	const storageCountries = list(unscoped);
+	const named = new Set(unscoped.map(norm));
+	const scopedStorage = [...new Map(allStorage.filter((s) => s.scope && foreign(s.country) && !named.has(norm(s.country))).map((s) => [`${norm(s.country)}|${s.scope}`, {
+		country: s.country,
+		scope: s.scope
+	}])).values()];
+	const operatorCountries = list(uniq(processors.map((p) => p.operatorCountry)).filter((c) => foreign(c) && !named.has(norm(c))));
+	const countries = list(uniq(processors.flatMap((p) => [...(p.storage ?? []).map((s) => s.country), p.operatorCountry])));
 	const address = contact?.address ?? org?.address;
 	return {
 		businessName,
@@ -4093,6 +5660,15 @@ function derivePolicyVars(cfg) {
 		optOutOptions,
 		cookieOptOutOptions,
 		processors,
+		firstPartyCookies: hasAdTracking ? [{
+			name: "_ac",
+			purpose: "records the advertisement or campaign you arrived from, so an enquiry can be attributed to it",
+			retention: "90 days"
+		}] : [],
+		jurisdictionCountry,
+		storageCountries: storageCountries || void 0,
+		scopedStorage,
+		operatorCountries: operatorCountries || void 0,
 		countries: countries || void 0,
 		consentModel: consent?.enabled ? consent.type ?? "opt-in" : "none",
 		cookieCategories: consent?.categories ?? []
@@ -4383,18 +5959,28 @@ If you have questions about our use of cookies, please contact us at ${v.mailing
 * "This site sets no cookies" is a real and increasingly common answer — a
 * cookieless analytics provider is a selling point, not an omission. Saying it
 * plainly beats an empty section that reads as an oversight.
+*
+* But it is only true if the site sets none of its **own**, which is why
+* `firstPartyCookies` is checked alongside the processors: a site running
+* attribution with a cookieless analytics provider sets `_ac` and no third-party
+* cookie at all, and the old wording would have declared it cookie-free.
 */
 function providersSection$1(v) {
 	const setting = v.processors.filter((p) => p.cookies?.length);
 	const cookieless = v.processors.filter((p) => p.cookies?.length === 0);
-	if (setting.length === 0) return `## Cookies Set on This Site
-
-Beyond the cookies strictly necessary to serve and secure the Site, we do not set cookies.${cookieless.length ? ` The third party ${cookieless.length === 1 ? "service" : "services"} we use on this Site — ${list(cookieless.map((p) => p.name))} — ${cookieless.length === 1 ? "does" : "do"} not set cookies of ${cookieless.length === 1 ? "its" : "their"} own.` : ""}
-`;
+	const own = v.firstPartyCookies;
+	const ownSection = own.length ? `\n### Cookies We Set Ourselves\n\n${bullets(own.map((c) => `\`${c.name}\` — ${c.purpose}. Kept for ${c.retention}.`))}\n` : "";
+	if (setting.length === 0) {
+		const named = cookieless.length ? ` The third party ${cookieless.length === 1 ? "service" : "services"} we use on this Site — ${list(cookieless.map((p) => p.name))} — ${cookieless.length === 1 ? "does" : "do"} not set cookies of ${cookieless.length === 1 ? "its" : "their"} own.` : "";
+		return `## Cookies Set on This Site
+
+${own.length ? `Beyond the cookies strictly necessary to serve and secure the Site, no third party sets cookies through this Site.${named}` : `Beyond the cookies strictly necessary to serve and secure the Site, we do not set cookies.${named}`}
+${ownSection}`;
+	}
 	return `## Cookies Set on This Site
 
 ${bullets(setting.map((p) => `**${p.name}** (${p.purpose}) — ${(p.cookies ?? []).map((c) => `\`${c}\``).join(", ")}${p.privacyUrl ? `. Privacy policy: ${p.privacyUrl}` : ""}`))}
-${cookieless.length ? `\nWe also use ${list(cookieless.map((p) => p.name))}, which ${cookieless.length === 1 ? "does" : "do"} not set cookies of ${cookieless.length === 1 ? "its" : "their"} own.\n` : ""}`;
+${cookieless.length ? `\nWe also use ${list(cookieless.map((p) => p.name))}, which ${cookieless.length === 1 ? "does" : "do"} not set cookies of ${cookieless.length === 1 ? "its" : "their"} own.\n` : ""}${ownSection}`;
 }
 /** Only meaningful when a consent tool actually offers the categories. */
 function categoriesSection(v) {
@@ -4410,6 +5996,23 @@ ${bullets(v.cookieCategories)}
 
 //#endregion
 //#region src/legal/templates/privacy.ca.ts
+/**
+* Privacy policy — Canada (PIPEDA).
+*
+* Ported from the pandoc prototype at `packages/core/legal-templates/`. Two
+* things changed in the port and both are load-bearing:
+*
+*  1. `${var}` is now real TypeScript interpolation rather than a pandoc Lua
+*     filter, so an unresolved variable is a compile error. The filter left
+*     unknown keys as the literal text `${key}` — which would ship a live
+*     privacy policy containing `${countries}`.
+*  2. Lists are built from arrays, not by splicing a string into a fixed bullet.
+*     An empty derived value used to produce a stray `- ; and` bullet.
+*
+* The prose is jurisdiction-specific: it names the Office of the Privacy
+* Commissioner of Canada and frames transfers as "outside of Canada". Do not
+* reuse it for another jurisdiction — add a sibling template instead.
+*/
 function privacyCa(v) {
 	return `# Privacy Policy
 ${updatedLine(v)}
@@ -4511,15 +6114,46 @@ ${bullets(v.processors.map((p) => `${p.name}, for ${p.purpose}${p.privacyUrl ? `
 
 We remain responsible for personal information in the possession of our service providers.`;
 }
-/** Omitted entirely when nothing leaves the country — a false claim otherwise. */
+/**
+* Omitted entirely when nothing leaves the country — a false claim otherwise.
+*
+* Two clauses, because storage and legal reach are two facts and the OPC's concern
+* is foreign **access**, not merely foreign storage. A provider can hold data in
+* Canada and still be compellable abroad (Azure in a Canadian region), and a
+* provider can hold only one category of data abroad (a Canadian tenant whose
+* identity data sits in the US). One sentence could state neither.
+*
+* The closer is shared: it is true of whichever clauses appear.
+*/
 function transferSection(v) {
-	if (!v.countries) return "";
+	const clauses = [storageClause(v), operatorClause(v)].filter(Boolean);
+	if (clauses.length === 0) return "";
 	return `
 ### We May Transfer Personal Information to Other Countries
 
-Some or all of the personal information we collect may be stored or processed in jurisdictions outside of Canada, including ${v.countries}. As a result, this information may be subject to access requests from governments, courts or law enforcement in those jurisdictions according to laws in those jurisdictions.
+${clauses.join("\n\n")}
+
+As a result, this information may be subject to access requests from governments, courts or law enforcement in those jurisdictions according to laws in those jurisdictions.
 `;
 }
+/**
+* Where the information rests.
+*
+* A scoped location gets its own sentence rather than joining the "including …"
+* list: folded in, a reader would take it to cover everything the provider holds,
+* which is a broader claim than the config made.
+*/
+function storageClause(v) {
+	const scoped = list(v.scopedStorage.map((s) => `${s.country}, in the case of ${s.scope}`));
+	if (v.storageCountries) return `Some or all of the personal information we collect may be stored or processed in jurisdictions outside of Canada, including ${v.storageCountries}.${scoped ? ` Certain categories of personal information are held outside of Canada even where the rest is not: ${scoped}.` : ""}`;
+	if (scoped) return `Certain categories of the personal information we collect are stored or processed outside of Canada: ${scoped}.`;
+	return "";
+}
+/** The Azure-in-Canada case: the information never moves, and foreign law still reaches it. */
+function operatorClause(v) {
+	if (!v.operatorCountries) return "";
+	return `Some of the service providers we use are established in, or controlled from, jurisdictions outside of Canada, including ${v.operatorCountries}. Personal information those providers handle on our behalf may be subject to the laws of those jurisdictions even when it is stored in Canada.`;
+}
 
 //#endregion
 //#region src/legal/templates/terms.ca.ts
@@ -6385,5 +8019,5 @@ function defaultConfig() {
 }
 
 //#endregion
-export { BASE_HOOK, CONFIG_SCHEMA_URL, CONTRAST, ConfigSchema, DARK_SEL, DOC_ORDER, DOC_SLUGS, DesignSystemSchema, JURISDICTIONS, KNOWN_PROCESSORS, NUMERIC_STEPS, REQUIRED_ROLES, ROLE_TOKEN_KEYS, SCHEMA_URL, SiteFontSchema, TEMPLATES, TW_CLASH, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, spriteId, stripNulls, 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_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 };
 //# sourceMappingURL=index.mjs.map