@getvitops/cli 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # @getvitops/cli
 
+## 4.0.0
+
+### Major Changes
+
+- f7bc0a0: Add `vitops search setup` — onboard domains into Google Search Console as domain properties.
+
+  **Breaking:** the `vitops indexing` command has been renamed to **`vitops search notify`**. There is
+  no alias — update any scripts or CI that call `vitops indexing` to `vitops search notify` (same flags,
+  same behaviour).
+
+  **New: `vitops search setup`.** For each domain in a site config's new `site.searchConsole` block
+  (a record keyed by bare hostname), it:
+  - ensures the apex verification TXT record in Cloudflare,
+  - verifies ownership via the Site Verification API (DNS_TXT), retried with exponential backoff while
+    DNS propagates — a still-unverified domain is reported **PENDING**, not failed,
+  - adds the `sc-domain:` property via the Search Console API,
+  - adds any `delegatedOwners` to the verified Site Verification web resource.
+
+  It is idempotent (a re-run of an onboarded domain is a no-op), supports `--check` (report drift, exit
+  non-zero, mutate nothing) and `--dry` (print the plan, change nothing), and `--domain <name>` to
+  scope to one entry. DNS records are only ever created, never edited or deleted.
+
+  Credentials come from the environment, never the config: `CLOUDFLARE_API_TOKEN` (a `Zone:DNS:Edit`
+  token) and a Google **user OAuth refresh token** as `VITOPS_GOOGLE_CLIENT_ID` /
+  `VITOPS_GOOGLE_CLIENT_SECRET` / `VITOPS_GOOGLE_REFRESH_TOKEN` (scoped to `siteverification` +
+  `webmasters`). Granting a Google Group **Full-User** access has no Search Console API and is surfaced
+  as a reminder in the summary rather than automated.
+
+- ceed51f: `vitops search notify` now accepts either Google credential, so most sites need only one.
+
+  The two halves of `vitops search` each demanded a different, unrelated Google setup — five environment variables between them. `search setup` requires a user OAuth credential (verifying a site makes the caller an **owner** of the property, and that should be a person, not a project robot), while `search notify` accepted only a service account. Search Console does not care which identity calls it, so a consumer who had already run `search setup` was being made to create a second credential for the other half of the same command.
+
+  `search notify` now takes whichever you have, preferring the service account when both are set — it runs on every deploy, in CI, and a service account does not expire, whereas a refresh token can be revoked and expires after 7 days for an OAuth client still in _Testing_ publishing status. `search setup` is unchanged and still requires user OAuth.
+
+  **Breaking — two renamed exports.** Both did the same job under the same name from different subpaths, which forced an alias at every call site:
+  - `@getvitops/utils/indexing`: `getAccessToken` → **`serviceAccountToken`**
+  - `@getvitops/utils/onboarding`: `getAccessToken` → **`refreshTokenGrant`**
+
+  New: `googleAccessToken(credential)` from `@getvitops/utils/indexing` takes a `GoogleCredential` union and is what both wrappers now call. If you were importing either `getAccessToken`, switch to the specific name, or to `googleAccessToken` if you want to accept either identity.
+
+  Internally the exchange is now one function. The two grants send different form bodies; everything after that — endpoint, content-type, error handling, `access_token` extraction — was duplicated verbatim in two modules. The service-account JWT signing had no test at all, because it was only reachable over the network; it now does, including the literal-`\n`-in-a-PEM case that secret stores produce.
+
+### Minor Changes
+
+- 14813fa: Document which tier provides each pattern — `vitops docs components`.
+
+  The toolkit ships four tiers that compose: CSS framework classes, `<wc-*>` web components, Astro
+  components, Bricks elements. Nothing said so. The class reference listed pattern names, the
+  elements reference listed Bricks controls, and the fact that `tree` is _also_ a web component
+  _and_ an Astro component existed only in the source layout. The cost is silent: you hand-write
+  the markup a component already emits, or you wrap a component that already emits its own tag.
+
+  `TIERS` in `@getvitops/generator` is the new manifest — per pattern, its CSS partial and
+  representative classes, its `wc-*` tag and which bundle that ships in, its Astro component(s),
+  its Bricks element, and one line saying what to actually write. `tierPatterns(tier)` projects one
+  tier. `vitops docs components` renders all four in one document, and the reference sections it
+  feeds render the same data per tier.
+
+  It is **authored rather than derived, and drift-guarded** instead. Naming convention carries most
+  of it and breaks exactly where it matters — `splitter.css` hosts two components, `tag.css` serves
+  three config patterns, `anchor-link.css` provides `.link`, `layout.css` provides `.split` and
+  `.centered` — so a derivation would need an exceptions table longer than the rule, and a rename
+  would silently drop a link. Instead, tests fail the build when a hand-written CSS partial, a
+  `customElements.define`, an exported Astro component or a Bricks element isn't accounted for.
+
+  Four things the manifest records that cannot be inferred, each a real failure mode:
+  - **Whether an Astro component wraps a web component.** `Tree` and `CookieConsent` emit the
+    `<wc-*>` tag with the fallback inside; `Details`, `Drawer`, `Popover`, `NavShell` and `Subgrid`
+    emit tier-1 markup with no web component at all. Reading the first group as the second gives
+    `<wc-tree><Tree /></wc-tree>` — two elements on one tree, which renders and misbehaves.
+  - **Where each element ships.** `elements.js` for the registered set, its own bundle for
+    `<wc-consent>` and `<wc-theme-editor>`, and **no bundle at all** for the four editor-v2 tags —
+    which are registered, importable-looking and inert in a consumer project. The guard checks this
+    against what `js/elements.ts` imports, so it can't claim an element ships when it doesn't.
+  - **Whether a pattern is config-authored.** `patterns.items` patterns get the token cascade,
+    states, role variants and override hooks; a structural partial gets none of them. The docs also
+    now say when a config-authored pattern is **absent from your config**, because naming its
+    classes while your build emits none of them is worse than omitting it.
+  - **The import specifier, verbatim.** These are published as the line to copy, so they are checked
+    against `@getvitops/astro`'s `exports`. That guard immediately caught
+    `@getvitops/astro/components/../CookieConsent.astro` — plausible-looking, right basename, not an
+    importable path (`CookieConsent.astro` ships from the package root).
+
+- 14813fa: Document the consent, conversion-tracking, search and legal subsystems for agents.
+
+  `vitops docs` gains four topics — `consent`, `tracking`, `search`, `legal` — and the docs
+  bundle gains the matching concept docs under `concepts/`. Until now these subsystems were
+  described only by their generated config-schema field descriptions, so an agent working in a
+  consumer project had no account of the rules that make them work, and every one of those rules
+  fails **silently** when broken:
+  - a gated tag given a live `src` instead of `type="text/plain"` fetches the third party anyway,
+    so the gate becomes decorative;
+  - a caller using `granted()` instead of `require()` never raises the banner, so on a site where
+    nothing else demands that category the permission is never offered, never granted, and the
+    write never happens;
+  - an absent `window.vitopsConsent` read as "denied" rather than "this site has no gate";
+  - a consent patch widened to every category records consent nobody gave;
+  - a sitemap with no `<lastmod>` makes edited pages undetectable, so `search notify` looks
+    healthy while never resubmitting anything;
+  - a stale IndexNow key file returns `202` and is then discarded;
+  - Google's Indexing API accepts ordinary URLs, discards them, and violates its own terms.
+
+  The packaged agent skill now covers consent and conversion tracking, and its description names
+  these subsystems so it is actually surfaced when they are the task.
+
+  Also fixed: the icons concept doc still called the Astro integration `getvitops()`, renamed to
+  `vitops()` in 3.0.
+
+### Patch Changes
+
+- Updated dependencies [14813fa]
+- Updated dependencies [c6b99e7]
+- Updated dependencies [c6b99e7]
+- Updated dependencies [f7bc0a0]
+- Updated dependencies [ceed51f]
+- Updated dependencies [14813fa]
+- Updated dependencies [14813fa]
+  - @getvitops/generator@4.0.0
+  - @getvitops/utils@4.0.0
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -25,7 +25,7 @@ npx vitops generate --format bricks,css --out dist
 | `vitops favicon -i <svg\|png> -o <dir>`            | generate a favicon set from a source image      |
 | `vitops agents [-o AGENTS.md] [--docs-dir <dir>]`  | link the agent skill + AGENTS.md pointer        |
 | `vitops docs [topic] [--all]`                      | print live reference docs to stdout             |
-| `vitops indexing [--dry] [--check]`                | tell search engines about a deploy              |
+| `vitops search notify [--dry] [--check]`           | tell search engines about a deploy              |
 | `vitops media [--raw <dir>] [-o <dir>]`            | encode raw video to WebM + MP4 + poster         |
 
 Every `--input` takes a `design-system.json` **or** the larger site config that embeds one

package/dist/cli.mjs

@@ -6,8 +6,9 @@ import { dirname, join, parse, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
 import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
-import { SNAPSHOT_PATH, collectEntries, formatPlan, getAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
-import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$1, processMedia } from "@getvitops/utils/media";
+import { SCOPES, SNAPSHOT_PATH, collectEntries, formatPlan, googleAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
+import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as formatPlan$1, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan as plan$1, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource } from "@getvitops/utils/onboarding";
+import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$2, processMedia } from "@getvitops/utils/media";
 
 //#region src/agents.ts
 /**
@@ -54,6 +55,26 @@ const TOPICS = {
 		path: "concepts/patterns.md",
 		summary: "pattern CSS: token cascade, override hooks, states, role variants"
 	},
+	components: {
+		path: "concepts/components.md",
+		summary: "which of the four tiers provides each pattern, and the call to make"
+	},
+	consent: {
+		path: "concepts/consent.md",
+		summary: "the consent gate: inert gated tags, demand-driven prompting, three-valued choices"
+	},
+	tracking: {
+		path: "concepts/tracking.md",
+		summary: "ad-click attribution, the `_ac` cookie, conversion notifications"
+	},
+	search: {
+		path: "concepts/search.md",
+		summary: "what search engines accept, Search Console onboarding, deploy notification"
+	},
+	legal: {
+		path: "concepts/legal.md",
+		summary: "privacy policy / terms / cookie notice derived from config facts"
+	},
 	elements: {
 		path: "bricks/elements.md",
 		summary: "Bricks Builder custom elements, controls, defaults"
@@ -536,7 +557,7 @@ function lintSource(files, v, format) {
 *   vitops docs      [topic] [--input <json>] [--all]
 *   vitops lint      [--input <json>] [--format <fmt>] [--src <dir>]
 *   vitops legal     [--input <site.json>] [--doc <name>] [--format <md|html|portable-text>] [--out <dir>]
-*   vitops indexing  [--input <site.json>] [--dry] [--all] [--check]
+*   vitops search    setup [--domain <name>] [--dry] [--check]  |  notify [--dry] [--all] [--check]
 *   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
 *
 * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
@@ -580,7 +601,7 @@ Usage:
   vitops lint [options]         Report framework classes in your source that resolve to nothing
   vitops legal [options]        Render legal documents from a site config
   vitops icons [options]        Report which icons your source uses, and build the sprite
-  vitops indexing [options]    Tell search engines about a deploy (sitemap + IndexNow)
+  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)
   vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
 
 Generate options:
@@ -654,7 +675,29 @@ Legal options:
   Generated from your config — a starting point, not legal advice. Review before
   publishing, and make sure the config describes what your site actually does.
 
-Indexing options:
+Search subcommands:
+  vitops search setup [opts]    Onboard site.searchConsole domains into GSC
+  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)
+
+Search setup options:
+  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+      --domain <name>   Scope to a single site.searchConsole entry
+      --dry             Print the plan and exit. Changes nothing.
+      --check           Report drift and exit non-zero if any domain is not fully
+                        onboarded. Mutates nothing.
+
+  For each domain it ensures the apex verification TXT in Cloudflare, verifies
+  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-
+  unverified domain is reported PENDING, not failed), adds the sc-domain: property,
+  and adds any delegatedOwners to the web resource. DNS is only ever created,
+  never edited or deleted. Credentials come from the environment:
+  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit), and VITOPS_GOOGLE_CLIENT_ID /
+  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token
+  scoped to siteverification + webmasters). Granting a Google Group Full-User
+  access has no API and is surfaced as a reminder.
+
+Search notify options:
   -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)
       --site-env <env>  Environment to notify for (default: production). An
                         environment whose robots policy says noindex is refused.
@@ -671,13 +714,16 @@ Indexing options:
                         Persist it between runs (a CI cache) or every run submits
                         everything.
 
-  What this can and cannot do: Google exposes no "request indexing" API, and its
+  What notify can and cannot do: Google exposes no "request indexing" API, and its
   sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap
   through the Search Console API and verifies the result with --check. IndexNow
   reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.
-  Search Console needs a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
-  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), added as an owner of the
-  property.
+  Search Console takes either credential, whichever you already have, added as an
+  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
+  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth
+  credential "search setup" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /
+  _REFRESH_TOKEN). The service account is preferred when both are set — this runs
+  on every deploy, and it does not expire.
 
 Media options:
       --raw <dir>       Directory of unprocessed video, walked recursively
@@ -707,6 +753,13 @@ Media options:
 Common:
   -h, --help            Show this help
 `;
+const SEARCH_HELP = `vitops search — Google Search Console
+
+  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties
+  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)
+
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
 function fail(msg) {
 	console.error(`✖ ${msg}`);
 	process.exit(1);
@@ -959,7 +1012,7 @@ async function cmdMedia(argv) {
 			onProgress: (message) => console.error(`  … ${message}`)
 		});
 		if (values.dry) {
-			console.log(formatPlan$1(result.plan));
+			console.log(formatPlan$2(result.plan));
 			return;
 		}
 		console.log(`✓ media → ${values.out} (${result.written.length} written, ${result.skipped} unchanged)`);
@@ -1275,7 +1328,7 @@ const readSitemap = async (source) => {
 * The Indexing API is deliberately absent — see `@getvitops/utils/indexing`'s
 * `gsc.ts`.
 */
-async function cmdIndexing(argv) {
+async function cmdSearchNotify(argv) {
 	const { values } = parseArgs({
 		args: argv,
 		options: {
@@ -1318,7 +1371,7 @@ async function cmdIndexing(argv) {
 		const key = newKey();
 		console.log(key);
 		console.log(`\n  Add to your site config:\n    "seo": { "indexing": { "indexNow": { "key": "${key}" } } }`);
-		console.log(`  Then serve it at /${key}.txt — \`vitops indexing --write-key public\`.`);
+		console.log(`  Then serve it at /${key}.txt — \`vitops search notify --write-key public\`.`);
 		return;
 	}
 	const config = toIndexingConfig(await loadConfig(resolve(values.input), values["site-env"]), values["site-env"]);
@@ -1354,13 +1407,13 @@ async function cmdIndexing(argv) {
 		console.log("\n(--dry: nothing was submitted)");
 		return;
 	}
-	const account = loadServiceAccount();
+	const credential = loadSearchCredential();
 	let failed = false;
 	if (values.check) {
 		if (!p.searchConsole.siteUrl) fail("--check needs seo.indexing.searchConsole.siteUrl (the Search Console property)");
-		if (!account) fail("--check needs a Search Console service account in VITOPS_GSC_SERVICE_ACCOUNT or GOOGLE_APPLICATION_CREDENTIALS");
+		if (!credential) fail(`--check needs a Search Console credential — ${CREDENTIAL_HINT}`);
 		if (p.check.length === 0) fail("--check needs seo.indexing.priorityUrls — the pages whose indexing matters");
-		const token = await getAccessToken(account);
+		const token = await googleAccessToken(credential);
 		console.log(`\nInspecting ${p.check.length} priority URL(s):`);
 		for (const url of p.check) {
 			const r = await inspectUrl(token, p.searchConsole.siteUrl, url);
@@ -1384,7 +1437,7 @@ async function cmdIndexing(argv) {
 		const check = await verifyKeyFile(keyLocation, key);
 		if (!check.ok) {
 			console.error(`✖ IndexNow key file check failed — ${check.reason}`);
-			console.error(`  Write it with: vitops indexing --write-key <public dir>`);
+			console.error(`  Write it with: vitops search notify --write-key <public dir>`);
 			failed = true;
 		} else {
 			let sent = 0;
@@ -1400,9 +1453,9 @@ async function cmdIndexing(argv) {
 			if (!failed) console.log(`✓ IndexNow: ${sent} URL(s) submitted`);
 		}
 	}
-	if (p.searchConsole.enabled) if (!account) console.log("· Search Console: skipped — no VITOPS_GSC_SERVICE_ACCOUNT / GOOGLE_APPLICATION_CREDENTIALS");
+	if (p.searchConsole.enabled) if (!credential) console.log(`· Search Console: skipped — no credential (${CREDENTIAL_HINT})`);
 	else {
-		const r = await submitSitemap(await getAccessToken(account), p.searchConsole.siteUrl, sitemapUrl);
+		const r = await submitSitemap(await googleAccessToken(credential), p.searchConsole.siteUrl, sitemapUrl);
 		if (r.ok) console.log(`✓ Search Console: sitemap resubmitted`);
 		else {
 			console.error(`✖ Search Console: ${r.message}`);
@@ -1414,7 +1467,267 @@ async function cmdIndexing(argv) {
 		writeSnapshot(snapshotPath, toSnapshot(sitemapUrl, current, (/* @__PURE__ */ new Date()).toISOString()));
 		console.log(`  state → ${relative(process.cwd(), snapshotPath)}`);
 	}
-	if (p.check.length > 0) console.log(`\n  Indexing is not instant. Run \`vitops indexing --check\` in a day or two to see what Google actually did.`);
+	if (p.check.length > 0) console.log(`\n  Indexing is not instant. Run \`vitops search notify --check\` in a day or two to see what Google actually did.`);
+}
+/**
+* Adapt a `Config` to the onboarding module's own option shape.
+*
+* The same flat field map as `toIndexingConfig`, and for the same reason — utils
+* cannot import the generator. `--domain` scopes to a single `site.searchConsole`
+* entry, and a name that isn't there is an error, not an empty run.
+*/
+function toSearchConsoleSetup(cfg, domainFilter) {
+	const entries = cfg.site.searchConsole ?? {};
+	const setups = Object.entries(entries).map(([domain, e]) => ({
+		domain,
+		...e.delegatedOwners ? { delegatedOwners: e.delegatedOwners } : {},
+		...e.fullUserGroup ? { fullUserGroup: e.fullUserGroup } : {}
+	}));
+	if (domainFilter) {
+		const one = setups.find((s) => s.domain === domainFilter);
+		if (!one) fail(`--domain "${domainFilter}" is not in site.searchConsole (have: ${setups.map((s) => s.domain).join(", ") || "none"})`);
+		return [one];
+	}
+	return setups;
+}
+/**
+* The Cloudflare DNS credential. From the environment only — a `site.json` is
+* committed, and this is a real secret. A `Zone:DNS:Edit` token (the standard
+* "Edit zone DNS" template, which also carries `Zone:Read`).
+*/
+function loadCloudflareToken() {
+	return process.env.CLOUDFLARE_API_TOKEN || void 0;
+}
+/**
+* The Google user-OAuth credential (refresh-token flow), from the environment.
+*
+* A user token, not a service account: onboarding acts *as a person* who can own
+* the sites. All-or-nothing — a partial set is a misconfiguration worth naming
+* rather than a reason to run degraded.
+*/
+function loadGoogleOAuth() {
+	const clientId = process.env.VITOPS_GOOGLE_CLIENT_ID;
+	const clientSecret = process.env.VITOPS_GOOGLE_CLIENT_SECRET;
+	const refreshToken = process.env.VITOPS_GOOGLE_REFRESH_TOKEN;
+	if (!clientId && !clientSecret && !refreshToken) return void 0;
+	const missing = [
+		["VITOPS_GOOGLE_CLIENT_ID", clientId],
+		["VITOPS_GOOGLE_CLIENT_SECRET", clientSecret],
+		["VITOPS_GOOGLE_REFRESH_TOKEN", refreshToken]
+	].filter(([, v]) => !v).map(([k]) => k);
+	if (missing.length) fail(`incomplete Google OAuth credential — missing ${missing.join(", ")}`);
+	return {
+		clientId,
+		clientSecret,
+		refreshToken
+	};
+}
+/**
+* The Google identity for `search notify`, preferring a service account.
+*
+* Search Console accepts either, and the preference is about *where this command
+* runs*: it fires on every deploy, in CI, and a service account has no expiry,
+* while a refresh token can be revoked — and for an OAuth client still in
+* *Testing* publishing status Google expires it after 7 days, which is a bad
+* property for a deploy step. So the robot wins when it is available.
+*
+* The fallback is the point, though. `search setup` needs user OAuth (verifying
+* a site makes the caller an owner, which should be a person), so a consumer who
+* ran setup already has a Google credential. Demanding a second, unrelated one
+* for the other half of the same command bought nothing.
+*/
+function loadSearchCredential() {
+	const account = loadServiceAccount();
+	if (account) return {
+		kind: "service-account",
+		account,
+		scope: SCOPES.webmasters
+	};
+	const oauth = loadGoogleOAuth();
+	return oauth ? {
+		kind: "oauth",
+		oauth
+	} : void 0;
+}
+/** Both spellings, for an error that has to tell you what to actually set. */
+const CREDENTIAL_HINT = "a service account in VITOPS_GSC_SERVICE_ACCOUNT / GOOGLE_APPLICATION_CREDENTIALS, or a user OAuth credential in VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* `vitops search` — everything that talks to search engines.
+*
+* Two subcommands, split by what they touch: `setup` onboards a domain into
+* Search Console (DNS + verification + property), `notify` tells the engines a
+* deploy happened (sitemap + IndexNow). `notify` is the former top-level
+* `vitops indexing`.
+*/
+async function cmdSearch(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "setup": return cmdSearchSetup(rest);
+		case "notify": return cmdSearchNotify(rest);
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(SEARCH_HELP);
+			return;
+		default: fail(`unknown "search" subcommand "${sub}" (expected: setup | notify). Try: vitops --help`);
+	}
+}
+/**
+* Onboard domains into Google Search Console as domain properties.
+*
+* Idempotent by construction: the planner decides each step from the domain's live
+* state, so a re-run of a fully-onboarded domain is all skips. `--check` reports
+* drift and exits non-zero without mutating; `--dry` prints the plan and stops.
+* DNS is only ever *created* — the verification TXT — never edited or removed.
+*
+* Search Console has no user/permission API, so granting a Google Group Full-User
+* access stays manual and is surfaced as a reminder, not attempted.
+*/
+async function cmdSearchSetup(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			domain: { type: "string" },
+			check: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: false
+	});
+	const domains = toSearchConsoleSetup(await loadConfig(resolve(values.input), values["site-env"]), values.domain);
+	if (domains.length === 0) fail("no domains in site.searchConsole — add domains to onboard (keyed by bare hostname)");
+	const cfToken = loadCloudflareToken();
+	const oauth = loadGoogleOAuth();
+	if (!cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token) — reading and writing DNS needs it");
+	if (!oauth) fail("set VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN — a user OAuth token scoped to siteverification + webmasters");
+	const token = await refreshTokenGrant(oauth);
+	const states = /* @__PURE__ */ new Map();
+	const verifyTokens = /* @__PURE__ */ new Map();
+	const webIds = /* @__PURE__ */ new Map();
+	for (const d of domains) {
+		const zone = await findZoneId(cfToken, d.domain);
+		if (!zone.ok || !zone.zoneId) fail(`${d.domain}: ${zone.message}`);
+		const vt = await getVerificationToken(token, d.domain);
+		if (!vt.ok || !vt.token) fail(`${d.domain}: could not obtain a verification token — ${vt.message}`);
+		verifyTokens.set(d.domain, vt.token);
+		const txt = await listApexTxt(cfToken, zone.zoneId, d.domain);
+		if (!txt.ok) fail(`${d.domain}: ${txt.message}`);
+		const wr = await getWebResource(token, d.domain);
+		if (!wr.ok) fail(`${d.domain}: ${wr.message}`);
+		if (wr.id) webIds.set(d.domain, wr.id);
+		const site = await getSite(token, siteUrlFor(d.domain));
+		if (!site.ok) fail(`${d.domain}: ${site.message}`);
+		states.set(d.domain, {
+			zoneId: zone.zoneId,
+			txtPresent: txt.contents.includes(vt.token),
+			verified: wr.exists,
+			currentOwners: wr.owners,
+			propertyExists: site.exists
+		});
+	}
+	const p = plan$1({ domains }, states);
+	console.log(formatPlan$1(p));
+	if (values.check) {
+		if (hasDrift(p)) {
+			console.error("\n✖ drift — one or more domains are not fully onboarded");
+			process.exit(1);
+		}
+		console.log("\n✓ every domain is onboarded");
+		return;
+	}
+	if (values.dry) {
+		console.log("\n(--dry: nothing was changed)");
+		return;
+	}
+	const results = [];
+	let failed = false;
+	const delays = backoffSchedule();
+	for (const d of domains) {
+		const dp = p.domains.find((x) => x.domain === d.domain);
+		const state = states.get(d.domain);
+		const result = {
+			domain: d.domain,
+			txt: "—",
+			verified: "—",
+			property: "—",
+			reminders: dp.reminders
+		};
+		if (dp.txt.action === "skip") result.txt = "present";
+		else {
+			const r = await createApexTxt(cfToken, state.zoneId, d.domain, verifyTokens.get(d.domain));
+			if (!r.ok) {
+				console.error(`✖ ${d.domain} TXT: ${r.message}`);
+				result.txt = "failed";
+				failed = true;
+				results.push(result);
+				continue;
+			}
+			result.txt = "created";
+		}
+		let verified = state.verified;
+		if (verified) result.verified = "yes";
+		else {
+			for (let attempt = 0; attempt < delays.length; attempt++) {
+				const v = await verifyWebResource(token, d.domain);
+				if (v.ok) {
+					verified = true;
+					if (v.id) webIds.set(d.domain, v.id);
+					state.currentOwners = v.owners;
+					break;
+				}
+				if (attempt < delays.length - 1) {
+					const wait = delays[attempt];
+					console.log(`  … ${d.domain}: not verified yet (attempt ${attempt + 1}/${delays.length}); retrying in ${wait / 1e3}s`);
+					await sleep(wait);
+				}
+			}
+			result.verified = verified ? "yes" : "pending";
+		}
+		if (!verified) {
+			results.push(result);
+			continue;
+		}
+		if (dp.property.action === "skip") result.property = "present";
+		else {
+			const r = await addSite(token, dp.siteUrl);
+			if (!r.ok) {
+				console.error(`✖ ${d.domain} property: ${r.message}`);
+				result.property = "failed";
+				failed = true;
+			} else result.property = "added";
+		}
+		if (dp.owners.action === "update" && dp.ownersToAdd.length) {
+			const id = webIds.get(d.domain);
+			if (!id) {
+				console.error(`✖ ${d.domain} owners: no web-resource id (verify may be too fresh)`);
+				failed = true;
+			} else {
+				const r = await updateOwners(token, id, d.domain, ownerUnion(state.currentOwners, dp.ownersToAdd));
+				if (!r.ok) {
+					console.error(`✖ ${d.domain} owners: ${r.message}`);
+					failed = true;
+				} else console.log(`✓ ${d.domain}: added ${dp.ownersToAdd.length} owner(s)`);
+			}
+		}
+		results.push(result);
+	}
+	console.log(`\n${formatSummary(results)}`);
+	if (failed) process.exit(1);
 }
 function cliVersion() {
 	try {
@@ -1641,9 +1954,9 @@ async function main() {
 		case "lint": return cmdLint(rest);
 		case "legal": return cmdLegal(rest);
 		case "icons": return cmdIcons(rest);
-		case "indexing": return cmdIndexing(rest);
+		case "search": return cmdSearch(rest);
 		case "media": return cmdMedia(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | indexing | media). Try: vitops --help`);
+		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | search | media). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));