@getvitops/generator 3.0.0 → 4.0.0

package/dist/index.mjs

@@ -20,7 +20,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 +38,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 +519,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,6 +629,17 @@ 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."),
@@ -818,7 +829,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 +843,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 +854,8 @@ 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.")
 });
 /**
 * Which template set the generated legal documents are written against. This is
@@ -878,6 +889,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 +916,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 +929,19 @@ 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."),
 	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`."),
@@ -1753,6 +1773,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 +2374,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 +3119,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 +3146,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 +3286,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 +3312,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 +3605,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 +3822,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 +3968,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 +4030,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 +4085,476 @@ 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.
+
+- **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 +4565,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 +4619,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(),
@@ -4041,21 +5347,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",
@@ -4093,6 +5421,11 @@ 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"
+		}] : [],
 		countries: countries || void 0,
 		consentModel: consent?.enabled ? consent.type ?? "opt-in" : "none",
 		cookieCategories: consent?.categories ?? []
@@ -4383,18 +5716,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) {
@@ -6385,5 +7728,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 { 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, TIERS, TIER_NAMES, TW_CLASH, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, 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