@theholocron/cli 5.0.0-alpha.187 → 5.0.0-alpha.188

package/dist/cli.mjs

@@ -24,9 +24,9 @@ import search from "@inquirer/search";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import ora from "ora";
 import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-utils";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { stringifyJson } from "@theholocron/json-utils";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
 import { createGitHubClient } from "@theholocron/github-client";
@@ -409,7 +409,7 @@ const COMMAND_CONTEXTS = {
 	"secrets sync": "workspace",
 	"notifications channel add": "workspace",
 	"notifications setup": "workspace",
-	"notifications verify": "workspace",
+	"doctor notifications": "workspace",
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
 	"monitoring check": "workspace",
@@ -2634,219 +2634,748 @@ function mk(capability, provider, status, message, logMessage) {
 	};
 }
 //#endregion
-//#region src/commands/monitoring-check/monitoring-check.ts
+//#region src/commands/notifications-channel-add/notifications-channel-add.ts
 /**
-* `holocron monitoring check <url>` — runs every configured `monitoring`
-* check against an arbitrary URL instead of each check's own configured
-* one (holocron#1010).
-*
-* Built for CI: the `delivery.previewCheck` task runs this against a
-* PR's Vercel preview deployment, reusing the exact same check
-* definitions already in `holocron.config.ts` for production — no
-* vendor API call, no separate checks-as-code file to keep in sync.
+* `holocron notifications channel add` — create one channel (and, with
+* `--with-webhook`, an inbound webhook whose URL goes straight into a secret).
 *
-* Split into two pieces (holocron#1030/#1032 review) so a caller that
-* needs to attach a credential to the request (e.g. Vercel's Deployment
-* Protection bypass header) can do so in a process that never loads a
-* PR's own `holocron.config.ts` at all:
-*   - {@link resolveMonitoringChecks} — loads config/plugins, returns the
-*     configured `MonitoringCheckInput[]`. Untrusted: this executes
-*     whatever code a PR's own config file contains. Never give this
-*     process a credential worth protecting.
-*   - {@link reportChecks} — takes an already-resolved check list (no
-*     config loading at all) and runs/report them against a URL. Safe
-*     to run with a credential present, since nothing here executes
-*     PR-authored code.
-* `runMonitoringCheck` composes both, unchanged, for every caller that
-* doesn't need the split (the plain CLI invocation, tests, anywhere a
-* credential isn't in play).
+* Provider-neutral: it drives the `notifications` capability's `ensure*`
+* methods, so any provider that implements them works. Idempotent — an
+* existing channel or webhook is left alone, and a webhook URL is never
+* printed, only stored.
 */
 /**
-* Loads config/plugins and returns the configured `monitoring` checks —
-* the untrusted half of `monitoring check`. Executes a PR's own
-* `holocron.config.ts` (and whatever it imports); never run this with a
-* credential in the process environment that a malicious config could
-* read and exfiltrate.
+* `HOLOCRON_NOTIFY_WEBHOOK_SYNC` for channel `sync`. Named after the job, not the
+* provider, so changing providers means re-pointing the same secrets at new
+* webhook URLs, with no workflow edits.
 */
-async function resolveMonitoringChecks(input) {
-	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
-	assertPluginsResolvable(loader, "monitoring check");
-	return [...loader.get("monitoring").checks];
+function defaultSecretName(channel) {
+	return `HOLOCRON_NOTIFY_WEBHOOK_${channel.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
 }
 /**
-* Runs an already-resolved check list against `url` and reports
-* pass/fail — the trusted half of `monitoring check`. Takes plain data,
-* never touches `holocron.config.ts` or any plugin: safe to run with a
-* credential (in `headers` or elsewhere in the process env) present.
+* Prefix of the throwaway secret the preflight writes and removes. Every run adds a
+* random suffix, so it can never overwrite (and then delete) a secret someone already
+* has; layouts may not use any name under this prefix for their own secrets.
 */
-async function reportChecks(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	const run = input.runCheck ?? runCheckAgainstUrl;
-	print(`Holocron monitoring check — against ${input.url}`);
-	if (input.checks.length === 0) {
-		print(`✗ no monitoring checks configured — nothing to validate`);
-		logger.warn({ url: input.url }, "monitoring check: no checks configured");
-		return {
-			status: "fail",
-			checks: []
-		};
-	}
-	const checks = [];
-	for (const checkInput of input.checks) {
-		const result = await run(checkInput, {
-			url: input.url,
-			...input.headers ? { headers: input.headers } : {}
-		});
-		if (result.requestError) {
-			print(`  ✗ ${checkInput.name}  (request failed: ${result.requestError})`);
-			checks.push({
-				name: checkInput.name,
-				passed: false,
-				failures: [],
-				requestError: result.requestError
-			});
-		} else if (result.passed) {
-			print(`  ✓ ${checkInput.name}`);
-			checks.push({
-				name: checkInput.name,
-				passed: true,
-				failures: []
-			});
-		} else {
-			print(`  ✗ ${checkInput.name}`);
-			for (const failure of result.failures) print(`      ${failure}`);
-			checks.push({
-				name: checkInput.name,
-				passed: false,
-				failures: result.failures
-			});
-		}
-	}
-	const failCount = checks.filter((c) => !c.passed).length;
-	const status = failCount === 0 ? "ok" : "fail";
-	print(`${status === "ok" ? "✓" : "✗"} ${checks.length - failCount} passed, ${failCount} failed`);
-	logger.info({
-		url: input.url,
-		total: checks.length,
-		failed: failCount,
-		status
-	}, "monitoring check: done");
-	return {
-		status,
-		checks
-	};
+const PREFLIGHT_PREFIX = "HOLOCRON_NOTIFY_PREFLIGHT";
+/** Whether a secret name is under the preflight's reserved prefix. GitHub secret names are case-insensitive. */
+function isReservedSecret(name) {
+	return name.toUpperCase().startsWith(PREFLIGHT_PREFIX);
 }
 /**
-* `resolveMonitoringChecks` + `reportChecks` in one call — the plain CLI
-* contract, unchanged. Only safe to run with a credential present when
-* the config being loaded is trusted (no PR in the loop); CI's
-* `delivery.previewCheck` uses the two halves separately instead.
+* Prove the secrets store can be WRITTEN before creating anything that needs it.
+* A webhook's URL is shown once; creating the webhook and then failing to store
+* it leaves an orphan the user has to delete by hand. Listing is not enough --
+* a token can read secrets it cannot write -- so write a throwaway secret and
+* remove it.
 */
-async function runMonitoringCheck(input) {
-	return reportChecks({
-		checks: await resolveMonitoringChecks({
-			loaded: input.loaded,
-			context: input.context,
-			loader: input.loader
-		}),
-		url: input.url,
-		...input.headers ? { headers: input.headers } : {},
-		...input.print ? { print: input.print } : {},
-		...input.logger ? { logger: input.logger } : {},
-		...input.runCheck ? { runCheck: input.runCheck } : {}
-	});
+async function assertSecretsReachable(secrets, scope) {
+	const probe = `${PREFLIGHT_PREFIX}_${randomBytes(4).toString("hex").toUpperCase()}`;
+	try {
+		await secrets.setSecret(scope, probe, "ok");
+		await secrets.deleteSecret(scope, probe);
+	} catch (err) {
+		const where = scope.kind === "organization" ? `organization ${scope.name}` : scope.kind;
+		throw new Error(`cannot write to the secrets store for ${where} (${describeProviderError(err)}) — fix that token before creating webhooks. If a secret named ${probe} was left behind, delete it`, { cause: err });
+	}
 }
-//#endregion
-//#region src/commands/monitoring-resolve-checks/monitoring-resolve-checks.ts
-/**
-* `holocron monitoring resolve-checks` — loads config/plugins and writes
-* the configured `monitoring` checks to a file as JSON (holocron#1030/
-* #1032 review).
-*
-* The untrusted half of the `delivery.previewCheck` split: this process
-* executes a PR's own `holocron.config.ts`, so it must never run with a
-* credential worth protecting (e.g. a Deployment Protection bypass
-* secret) present in its environment. `monitoring run-resolved` is the
-* trusted half — it reads this command's output file and performs the
-* actual authenticated request, with no config loading at all.
-*/
-async function runMonitoringResolveChecks(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const checks = await resolveMonitoringChecks({
-		loaded: input.loaded,
-		context: input.context,
-		loader: input.loader
-	});
-	await writeFile(input.outFile, JSON.stringify(checks), "utf8");
-	print(`Resolved ${checks.length} monitoring check(s) → ${input.outFile}`);
+/** Why a capability is not loaded: the plugin's own load error when there is one (e.g. a missing token). */
+function whyMissing(loader, key, fallback) {
+	const failure = loader.loadFailures().find((f) => f.key === key);
+	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${describeProviderError(failure.error)})` : fallback;
+}
+/** The configured `notifications` providers, or an error that says why there are none (including a plugin that failed to load). */
+function notificationProviders(loader) {
+	const providers = loader.has("notifications") ? loader.get("notifications") : [];
+	if (providers.length === 0) throw new Error(whyMissing(loader, "notifications", "no `notifications` provider is available — add one to holocron.config.ts"));
+	return providers;
 }
-//#endregion
-//#region src/commands/monitoring-run-resolved/monitoring-run-resolved.ts
-/**
-* `holocron monitoring run-resolved <url>` — runs an already-resolved
-* check list (no `holocron.config.ts` loading at all) against `url`
-* (holocron#1030/#1032 review).
-*
-* The trusted half of the `delivery.previewCheck` split, paired with
-* `monitoring resolve-checks` (the untrusted half, which loads config).
-* Safe to run with a credential present, since nothing here executes
-* PR-authored code — but a credential is only ever attached after
-* `verifyVercelDeploymentProject` confirms `url` actually belongs to
-* `vercelProject`: a URL merely ending in `.vercel.app` proves nothing,
-* since anyone can register their own Vercel project (sourcery review
-* on holocron#1032). No `vercelProject` given at all → the credential
-* is never attached, regardless of whether one is configured.
-*/
 /**
-* The shared gate every caller that might attach the Deployment
-* Protection bypass header goes through — `monitoring check`'s direct
-* CLI invocation included (sourcery review on holocron#1032 called this
-* out explicitly: verifying only in `delivery.previewCheck`'s own split
-* commands and not here would leave the exact same unverified-host
-* problem reachable by hand). No `vercelProject` → never attach
-* anything, regardless of whether a `bypassSecret` happens to be
-* configured. `vercelProject` given but verification fails or no token
-* is available → `undefined` AND a printed reason, never a thrown
-* error — callers decide for themselves whether that's fatal.
+* Pick the provider that can do what the command needs; with several, `--provider`
+* decides. `can` says what "able" means (a command that only reads needs `inspect`, not
+* provisioning), and `verb` words the errors.
 */
-async function resolveVercelBypassHeaders(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	if (!input.vercelProject) return { verified: true };
-	if (!input.vercelToken) {
-		print(`✗ --vercel-project was given but no Vercel token is available to verify deployment ownership`);
-		return { verified: false };
-	}
-	if (!await (input.verify ?? verifyVercelDeploymentProject)(input.url, input.vercelProject, input.vercelToken, { ...input.vercelTeamId ? { teamId: input.vercelTeamId } : {} })) {
-		print(`✗ ${input.url} does not resolve to a deployment of Vercel project "${input.vercelProject}" — refusing to attach the Deployment Protection bypass credential or run checks against an unverified URL`);
-		return { verified: false };
+function pickProvider(providers, wanted, can, verb) {
+	const capable = providers.filter(can);
+	if (capable.length === 0) throw new Error(`no \`notifications\` provider can ${verb.infinitive} — add one that implements it (for example discord) to holocron.config.ts`);
+	if (wanted) {
+		const match = capable.find((p) => p.providerName === wanted);
+		if (!match) throw new Error(`no ${verb.gerund} \`notifications\` provider named \`${wanted}\` (have: ${names(capable)})`);
+		return match;
 	}
-	return input.bypassSecret ? {
-		verified: true,
-		headers: { "x-vercel-protection-bypass": input.bypassSecret }
-	} : { verified: true };
+	if (capable.length > 1) throw new Error(`several \`notifications\` providers can ${verb.infinitive} (${names(capable)}) — pass --provider <name>`);
+	return capable[0];
 }
-async function runMonitoringRunResolved(input) {
-	const { headers, verified } = await resolveVercelBypassHeaders(input);
-	if (!verified) return {
-		status: "fail",
-		checks: []
-	};
-	return reportChecks({
-		checks: input.checks,
-		url: input.url,
-		...headers ? { headers } : {},
-		...input.print ? { print: input.print } : {},
-		...input.logger ? { logger: input.logger } : {},
-		...input.runCheck ? { runCheck: input.runCheck } : {}
+/** Pick the provider that can provision. Any ensure* method counts: a role-only layout needs no channel support. */
+function pickProvisioner(providers, wanted) {
+	return pickProvider(providers, wanted, (p) => typeof p.ensureChannel === "function" || typeof p.ensureCategory === "function" || typeof p.ensureRole === "function", {
+		infinitive: "provision",
+		gerund: "provisioning"
 	});
 }
-//#endregion
-//#region src/commands/new/new.ts
+const names = (ps) => ps.map((p) => p.providerName).join(", ");
 /**
-* `holocron new repo <type> <name>` — create a GitHub repo from a template and
-* bootstrap it by replacing all template-slug casing variants with the new
+* The first reason the layout's secret names cannot work, or undefined. Two things
+* cannot share one secret: the second write would overwrite the first and callers
+* would read the wrong value. Punctuation normalising (release-notes vs
+* release_notes) makes that easy to hit by accident, GitHub secret names are
+* case-insensitive, and the preflight's own prefix is reserved. Shared by `setup`
+* (which refuses) and `verify` (which reports it).
+*/
+function layoutSecretProblem(layout) {
+	const taken = /* @__PURE__ */ new Map();
+	const claim = (secret, owner, hint) => {
+		if (isReservedSecret(secret)) return `${owner} would store into ${secret}, a name reserved for the setup preflight — choose another`;
+		const key = secret.toUpperCase();
+		const other = taken.get(key);
+		if (other) return `${other} and ${owner} would both store into ${secret} — ${hint}`;
+		taken.set(key, owner);
+	};
+	for (const category of layout.categories ?? []) for (const channel of category.channels ?? []) {
+		if (!channel.webhook) continue;
+		const clash = claim(channel.webhook !== true && channel.webhook.secret || defaultSecretName(channel.name), `channel \`${channel.name}\``, "give one a distinct `webhook.secret`");
+		if (clash) return clash;
+	}
+	for (const role of layout.roles ?? []) {
+		if (!role.secret) continue;
+		const clash = claim(role.secret, `role \`${role.name}\``, "give one a distinct secret");
+		if (clash) return clash;
+	}
+}
+/** Ensure one channel and, if asked, its webhook + secret. Shared with `notifications setup`. */
+async function provisionChannel(deps, spec) {
+	const { notifications, secrets, scope, dryRun, print, tally } = deps;
+	const webhookCfg = spec.webhook || void 0;
+	const secretName = webhookCfg?.secret ?? defaultSecretName(spec.name);
+	const webhookName = webhookCfg?.name ?? spec.name;
+	const where = spec.category ? ` in ${spec.category}` : "";
+	if (!notifications.ensureChannel) throw new Error(`\`${notifications.providerName}\` cannot create channels`);
+	if (webhookCfg && !notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
+	if (webhookCfg && isReservedSecret(secretName)) throw new Error(`secret name ${secretName} is reserved for the setup preflight -- choose another`);
+	if (webhookCfg && !dryRun && !secrets) throw new Error("storing a webhook URL needs a `secrets` provider — add one to holocron.config.ts");
+	if (dryRun) {
+		print(`  ${style.skip(`would ensure channel ${spec.name}${where}`)}`);
+		if (tally) tally.skip += webhookCfg ? 2 : 1;
+		if (webhookCfg) print(`  ${style.skip(`would ensure webhook ${webhookName} and store its URL in ${secretName}`)}`);
+		return {
+			name: spec.name,
+			...spec.category ? { category: spec.category } : {},
+			created: false
+		};
+	}
+	const channel = await notifications.ensureChannel({
+		name: spec.name,
+		...spec.category ? { category: spec.category } : {},
+		...spec.topic ? { topic: spec.topic } : {}
+	});
+	print(`  ${(channel.created ? style.success : style.skip)(`${channel.created ? "created" : "exists "} channel ${spec.name}${where}`)}`);
+	if (tally) tally[channel.created ? "ok" : "skip"]++;
+	const outcome = {
+		name: spec.name,
+		...spec.category ? { category: spec.category } : {},
+		created: channel.created
+	};
+	if (!webhookCfg) return outcome;
+	const hook = await notifications.ensureWebhook({
+		channel: spec.name,
+		name: webhookName,
+		...spec.category ? { category: spec.category } : {}
+	});
+	if (hook.url) {
+		try {
+			await secrets.setSecret(scope, secretName, hook.url);
+		} catch (err) {
+			throw new Error(`webhook ${webhookName} was ${hook.created ? "created" : "found"} but storing its URL in ${secretName} failed (${describeProviderError(err)}) — delete the webhook in the provider and re-run to get a fresh URL`, { cause: err });
+		}
+		print(`  ${style.success(`${hook.created ? "created" : "found  "} webhook ${webhookName}; URL stored in ${secretName}`)}`);
+		if (tally) tally.ok++;
+		outcome.webhook = {
+			name: webhookName,
+			created: hook.created,
+			secret: secretName,
+			stored: true
+		};
+	} else {
+		const note = `webhook ${webhookName} already exists and its URL cannot be read back — delete it in the provider and re-run, or set ${secretName} yourself`;
+		print(`  ${style.warn(note)}`);
+		outcome.webhook = {
+			name: webhookName,
+			created: hook.created,
+			secret: secretName,
+			stored: false,
+			note
+		};
+	}
+	return outcome;
+}
+async function runNotificationsChannelAdd(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "notifications channel add");
+	const dryRun = input.context.dryRun ?? false;
+	print(`Holocron notifications channel add — ${input.name}${dryRun ? " (dry-run)" : ""}`);
+	try {
+		const notifications = pickProvisioner(notificationProviders(loader), input.provider);
+		let secrets;
+		if (input.withWebhook && !dryRun) {
+			if (!loader.has("secrets")) throw new Error(whyMissing(loader, "secrets", "`--with-webhook` needs a `secrets` capability — add a `secrets` provider to holocron.config.ts"));
+			secrets = loader.get("secrets");
+		}
+		const org = input.context.org;
+		const scope = input.scope ?? (org ? {
+			kind: "organization",
+			name: org
+		} : void 0);
+		if (input.withWebhook && !scope && !dryRun) throw new Error("no org to store the webhook secret under — pass --scope or set `org` in holocron.config.ts");
+		if (secrets && scope && !dryRun) await assertSecretsReachable(secrets, scope);
+		const channel = await provisionChannel({
+			notifications,
+			...secrets ? { secrets } : {},
+			scope: scope ?? { kind: "repo" },
+			dryRun,
+			print
+		}, {
+			name: input.name,
+			...input.category ? { category: input.category } : {},
+			...input.topic ? { topic: input.topic } : {},
+			...input.withWebhook ? { webhook: {
+				...input.webhookName ? { name: input.webhookName } : {},
+				...input.secret ? { secret: input.secret } : {}
+			} } : {}
+		});
+		logger.info({
+			channel: input.name,
+			created: channel.created,
+			provider: notifications.providerName,
+			status: "ok"
+		}, `notifications channel add: ${input.name}`);
+		if (channel.webhook && !channel.webhook.stored && !dryRun) {
+			const message = channel.webhook.note;
+			print(`  ${style.fail(message)}`);
+			return {
+				status: "fail",
+				channel,
+				message
+			};
+		}
+		return {
+			status: dryRun ? "dry-run" : "ok",
+			channel
+		};
+	} catch (err) {
+		const message = describeProviderError(err);
+		print(`  ${style.fail(message)}`);
+		logger.warn({
+			channel: input.name,
+			reason: logReason(err)
+		}, `notifications channel add: ${input.name}`);
+		return {
+			status: "fail",
+			message
+		};
+	}
+}
+//#endregion
+//#region src/commands/doctor-notifications/doctor-notifications.ts
+/**
+* `holocron doctor notifications` -- read-only: compare the layout a provider
+* declares in `holocron.config.ts` with what is actually on the server and in the
+* secrets store, step by step.
+*
+* It is the end-to-end check for `notifications setup`, and stays useful after
+* as a drift check. Everything the layout and `setup` cannot do yet is listed
+* too, as plain failing steps, so the command is red until the last feature
+* lands and each feature built turns exactly one step green. The list
+* is {@link PLANNED_CHECKS}; the numbers match the table in holocron#1098.
+*/
+/** Features not built yet, in the order of the table in holocron#1098. Move an entry into a real check when it lands. */
+const PLANNED_CHECKS = [
+	{
+		step: 8,
+		id: "permissions",
+		title: "channel and category permissions set"
+	},
+	{
+		step: 10,
+		id: "server-settings",
+		title: "server verification, notifications and system channels set"
+	},
+	{
+		step: 11,
+		id: "welcome",
+		title: "welcome screen and onboarding set"
+	},
+	{
+		step: 12,
+		id: "webhook-appearance",
+		title: "webhook names and avatars set"
+	},
+	{
+		step: 13,
+		id: "app-settings",
+		title: "bot description, tags, install link and URLs set"
+	},
+	{
+		step: 14,
+		id: "role-assignment",
+		title: "role assigned to team members"
+	},
+	{
+		step: 15,
+		id: "post-works",
+		title: "test post reached every channel (platform.notifyCheck)"
+	},
+	{
+		step: 16,
+		id: "server-creation",
+		title: "server created from config"
+	}
+];
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+const shown = (s) => sanitizeDetail(s);
+const ROLE_APPEARANCE_TITLE = "role colour, hoist and permissions set";
+const SECRETS_TITLE = "webhook URLs and role id stored as secrets";
+async function runDoctorNotifications(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "doctor notifications");
+	const checks = [];
+	const add = (id, title, problems, pass) => {
+		checks.push({
+			id,
+			title,
+			status: problems.length === 0 ? "pass" : "fail",
+			detail: problems.length === 0 ? pass : `${problems.length} problem(s)`,
+			problems
+		});
+	};
+	const byId = (id) => checks.find((c) => c.id === id);
+	const failed = (id, title, reason) => {
+		checks.push({
+			id,
+			title,
+			status: "fail",
+			detail: reason,
+			problems: []
+		});
+	};
+	const summarise = () => ({
+		pass: checks.filter((c) => c.status === "pass").length,
+		fail: checks.filter((c) => c.status === "fail").length,
+		skip: input.builtOnly ? PLANNED_CHECKS.length : 0
+	});
+	const finish = () => {
+		const summary = summarise();
+		const report = {
+			status: summary.fail > 0 ? "fail" : "ok",
+			checks,
+			summary
+		};
+		logger.info({
+			...summary,
+			status: report.status,
+			checks: checks.map((c) => `${c.id}:${c.status}`)
+		}, "doctor notifications");
+		return report;
+	};
+	const refuse = (message, reason = message) => {
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
+		logger.warn({ reason }, "doctor notifications");
+		return {
+			status: "fail",
+			checks,
+			summary: summarise(),
+			message
+		};
+	};
+	let notifications;
+	try {
+		notifications = pickProvider(notificationProviders(loader), input.provider, (p) => typeof p.inspect === "function", {
+			infinitive: "inspect a server",
+			gerund: "inspecting"
+		});
+	} catch (err) {
+		return refuse(describeProviderError(err));
+	}
+	const layout = notifications.layout;
+	if (!layout) return refuse(`the \`${notifications.providerName}\` provider declares no layout — add \`layout\` to its options in holocron.config.ts`);
+	let found;
+	let readError = "";
+	try {
+		found = await notifications.inspect(layout);
+	} catch (err) {
+		readError = describeProviderError(err);
+	}
+	if (notifications.whoami) try {
+		const who = await notifications.whoami();
+		if (who) checks.push({
+			id: "server",
+			title: "server reachable",
+			status: "pass",
+			detail: shown(who.target),
+			problems: []
+		});
+		else failed("server", "server reachable", "no server configured (the provider's whoami has nothing to check)");
+	} catch (err) {
+		failed("server", "server reachable", describeProviderError(err));
+	}
+	else if (found) checks.push({
+		id: "server",
+		title: "server reachable",
+		status: "pass",
+		detail: "readable (the provider has no whoami)",
+		problems: []
+	});
+	else failed("server", "server reachable", readError);
+	const declaredChannels = (layout.categories ?? []).flatMap((cat) => (cat.channels ?? []).map((channel) => ({
+		cat: cat.name,
+		channel
+	})));
+	const pick = (name, category) => {
+		const named = found.channels.filter((c) => same(c.name, name));
+		return {
+			named,
+			match: named.find((c) => c.category !== void 0 && same(c.category, category))
+		};
+	};
+	if (!found) {
+		if (byId("server")?.status !== "fail") failed("read", "read server", readError);
+		for (const [id, title] of [
+			["categories", "categories exist"],
+			["channels", "channels in their category, with topics"],
+			["webhooks", "webhooks on their channels"],
+			["roles", "roles exist and are mentionable"],
+			["role-appearance", ROLE_APPEARANCE_TITLE]
+		]) failed(id, title, "not checked: could not read the server");
+	} else {
+		const inspected = found;
+		const categories = layout.categories ?? [];
+		add("categories", "categories exist", categories.filter((cat) => !inspected.categories.some((name) => same(name, cat.name))).map((cat) => `${shown(cat.name)}: missing`), categories.length === 0 ? "none declared" : `${categories.length} of ${categories.length} exist`);
+		const channelProblems = [];
+		for (const { cat, channel } of declaredChannels) {
+			const { named, match } = pick(channel.name, cat);
+			if (named.length === 0) {
+				channelProblems.push(`#${shown(channel.name)}: missing`);
+				continue;
+			}
+			if (!match) {
+				const where = named.map((c) => c.category ?? "no category").join(", ");
+				channelProblems.push(`#${shown(channel.name)}: exists, but under ${shown(where)} and not ${shown(cat)}`);
+				continue;
+			}
+			if (channel.topic && (match.topic ?? "") !== channel.topic) channelProblems.push(`#${shown(channel.name)}: topic is "${shown(match.topic ?? "")}" but the layout says "${shown(channel.topic)}"`);
+		}
+		add("channels", "channels in their category, with topics", channelProblems, declaredChannels.length === 0 ? "none declared" : `${declaredChannels.length} of ${declaredChannels.length} as declared`);
+		const withWebhook = declaredChannels.filter(({ channel }) => channel.webhook);
+		const webhookProblems = [];
+		for (const { cat, channel } of withWebhook) {
+			const name = (channel.webhook === true ? {} : channel.webhook).name ?? channel.name;
+			const { match } = pick(channel.name, cat);
+			if (!match) webhookProblems.push(`#${shown(channel.name)}: no channel to hold the webhook`);
+			else if (match.webhooksError) webhookProblems.push(`#${shown(channel.name)}: could not list its webhooks (${shown(match.webhooksError)})`);
+			else if (!match.webhooks.some((w) => same(w, name))) webhookProblems.push(`#${shown(channel.name)}: no webhook named ${shown(name)}`);
+		}
+		add("webhooks", "webhooks on their channels", webhookProblems, withWebhook.length === 0 ? "none declared" : `${withWebhook.length} of ${withWebhook.length} exist`);
+		const roles = layout.roles ?? [];
+		const roleProblems = [];
+		if (inspected.rolesError) roleProblems.push(`could not read the roles (${shown(inspected.rolesError)})`);
+		for (const role of inspected.rolesError ? [] : roles) {
+			const named = inspected.roles.filter((r) => same(r.name, role.name));
+			const actual = named[0];
+			if (named.length > 1) roleProblems.push(`${shown(role.name)}: ${named.length} roles have this name; setup cannot tell which to manage`);
+			else if (!actual) roleProblems.push(`${shown(role.name)}: missing`);
+			else if (role.mentionable !== void 0 && actual.mentionable !== role.mentionable) roleProblems.push(`${shown(role.name)}: mentionable is ${actual.mentionable} but the layout says ${role.mentionable}`);
+		}
+		add("roles", "roles exist and are mentionable", roleProblems, roles.length === 0 ? "none declared" : `${roles.length} of ${roles.length} as declared`);
+		const appearance = [];
+		if (!inspected.rolesError) for (const role of roles) {
+			const actual = inspected.roles.find((r) => same(r.name, role.name));
+			if (!actual) {
+				appearance.push(`${shown(role.name)}: not checked, the role is missing`);
+				continue;
+			}
+			if (role.color !== void 0 && (actual.color ?? "").toLowerCase() !== role.color.toLowerCase()) appearance.push(`${shown(role.name)}: colour is ${shown(actual.color ?? "default")} but the layout says ${shown(role.color)}`);
+			if (role.hoist !== void 0 && (actual.hoist ?? false) !== role.hoist) appearance.push(`${shown(role.name)}: hoist is ${actual.hoist ?? false} but the layout says ${role.hoist}`);
+			const reported = actual.permissions;
+			if (role.permissions !== void 0) {
+				if (reported === void 0) appearance.push(`${shown(role.name)}: the provider did not report its permissions`);
+				else {
+					const have = new Set(reported.map((n) => n.toLowerCase()));
+					const want = new Set(role.permissions.map((n) => n.toLowerCase()));
+					const missing = role.permissions.filter((n) => !have.has(n.toLowerCase()));
+					const extra = reported.filter((n) => !want.has(n.toLowerCase()));
+					if (missing.length > 0) appearance.push(`${shown(role.name)}: missing permissions ${missing.map(shown).join(", ")}`);
+					if (extra.length > 0) appearance.push(`${shown(role.name)}: has extra permissions ${extra.map(shown).join(", ")}`);
+				}
+			}
+		}
+		const styled = roles.filter((r) => r.color !== void 0 || r.hoist !== void 0 || r.permissions !== void 0);
+		add("role-appearance", ROLE_APPEARANCE_TITLE, inspected.rolesError ? [`not checked: could not read the roles`] : appearance, styled.length === 0 ? "none declared" : `${styled.length} of ${styled.length} as declared`);
+	}
+	const wanted = [...declaredChannels.filter(({ channel }) => channel.webhook).map(({ channel }) => channel.webhook !== true && channel.webhook && channel.webhook.secret ? channel.webhook.secret : defaultSecretName(channel.name)), ...(layout.roles ?? []).flatMap((r) => r.secret ? [r.secret] : [])];
+	if (wanted.length === 0) checks.push({
+		id: "secrets",
+		title: SECRETS_TITLE,
+		status: "pass",
+		detail: "none declared",
+		problems: []
+	});
+	else if (!loader.has("secrets")) failed("secrets", SECRETS_TITLE, whyMissing(loader, "secrets", "no `secrets` provider to check them with"));
+	else {
+		const org = input.context.org;
+		const scope = input.scope ?? (org ? {
+			kind: "organization",
+			name: org
+		} : void 0);
+		if (!scope) failed("secrets", SECRETS_TITLE, "no org to look under — pass --scope or set `org` in holocron.config.ts");
+		else try {
+			const have = new Set((await loader.get("secrets").listSecrets(scope)).map((n) => n.toUpperCase()));
+			const clash = layoutSecretProblem(layout);
+			add("secrets", SECRETS_TITLE, [...clash ? [shown(clash)] : [], ...wanted.filter((n) => !have.has(n.toUpperCase())).map((n) => `${shown(n)}: missing`)], `${wanted.length} of ${wanted.length} exist`);
+		} catch (err) {
+			failed("secrets", SECRETS_TITLE, describeProviderError(err));
+		}
+	}
+	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
+		id: planned.id,
+		title: planned.title,
+		status: "fail",
+		detail: `not built yet (#1098, step ${planned.step})`,
+		problems: [],
+		step: planned.step
+	});
+	const width = Math.max(...checks.map((c) => c.title.length));
+	for (const check of checks) {
+		print(statusRow(check.status === "pass" ? "ok" : "fail", [check.title.padEnd(width), check.detail]));
+		for (const problem of check.problems) print(`      - ${problem}`);
+	}
+	const summary = summarise();
+	print("");
+	print(style.header(`${summary.pass} ok, ${summary.fail} fail, ${summary.skip} skipped`));
+	return finish();
+}
+//#endregion
+//#region src/commands/monitoring-check/monitoring-check.ts
+/**
+* `holocron monitoring check <url>` — runs every configured `monitoring`
+* check against an arbitrary URL instead of each check's own configured
+* one (holocron#1010).
+*
+* Built for CI: the `delivery.previewCheck` task runs this against a
+* PR's Vercel preview deployment, reusing the exact same check
+* definitions already in `holocron.config.ts` for production — no
+* vendor API call, no separate checks-as-code file to keep in sync.
+*
+* Split into two pieces (holocron#1030/#1032 review) so a caller that
+* needs to attach a credential to the request (e.g. Vercel's Deployment
+* Protection bypass header) can do so in a process that never loads a
+* PR's own `holocron.config.ts` at all:
+*   - {@link resolveMonitoringChecks} — loads config/plugins, returns the
+*     configured `MonitoringCheckInput[]`. Untrusted: this executes
+*     whatever code a PR's own config file contains. Never give this
+*     process a credential worth protecting.
+*   - {@link reportChecks} — takes an already-resolved check list (no
+*     config loading at all) and runs/report them against a URL. Safe
+*     to run with a credential present, since nothing here executes
+*     PR-authored code.
+* `runMonitoringCheck` composes both, unchanged, for every caller that
+* doesn't need the split (the plain CLI invocation, tests, anywhere a
+* credential isn't in play).
+*/
+/**
+* Loads config/plugins and returns the configured `monitoring` checks —
+* the untrusted half of `monitoring check`. Executes a PR's own
+* `holocron.config.ts` (and whatever it imports); never run this with a
+* credential in the process environment that a malicious config could
+* read and exfiltrate.
+*/
+async function resolveMonitoringChecks(input) {
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "monitoring check");
+	return [...loader.get("monitoring").checks];
+}
+/**
+* Runs an already-resolved check list against `url` and reports
+* pass/fail — the trusted half of `monitoring check`. Takes plain data,
+* never touches `holocron.config.ts` or any plugin: safe to run with a
+* credential (in `headers` or elsewhere in the process env) present.
+*/
+async function reportChecks(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const run = input.runCheck ?? runCheckAgainstUrl;
+	print(`Holocron monitoring check — against ${input.url}`);
+	if (input.checks.length === 0) {
+		print(`✗ no monitoring checks configured — nothing to validate`);
+		logger.warn({ url: input.url }, "monitoring check: no checks configured");
+		return {
+			status: "fail",
+			checks: []
+		};
+	}
+	const checks = [];
+	for (const checkInput of input.checks) {
+		const result = await run(checkInput, {
+			url: input.url,
+			...input.headers ? { headers: input.headers } : {}
+		});
+		if (result.requestError) {
+			print(`  ✗ ${checkInput.name}  (request failed: ${result.requestError})`);
+			checks.push({
+				name: checkInput.name,
+				passed: false,
+				failures: [],
+				requestError: result.requestError
+			});
+		} else if (result.passed) {
+			print(`  ✓ ${checkInput.name}`);
+			checks.push({
+				name: checkInput.name,
+				passed: true,
+				failures: []
+			});
+		} else {
+			print(`  ✗ ${checkInput.name}`);
+			for (const failure of result.failures) print(`      ${failure}`);
+			checks.push({
+				name: checkInput.name,
+				passed: false,
+				failures: result.failures
+			});
+		}
+	}
+	const failCount = checks.filter((c) => !c.passed).length;
+	const status = failCount === 0 ? "ok" : "fail";
+	print(`${status === "ok" ? "✓" : "✗"} ${checks.length - failCount} passed, ${failCount} failed`);
+	logger.info({
+		url: input.url,
+		total: checks.length,
+		failed: failCount,
+		status
+	}, "monitoring check: done");
+	return {
+		status,
+		checks
+	};
+}
+/**
+* `resolveMonitoringChecks` + `reportChecks` in one call — the plain CLI
+* contract, unchanged. Only safe to run with a credential present when
+* the config being loaded is trusted (no PR in the loop); CI's
+* `delivery.previewCheck` uses the two halves separately instead.
+*/
+async function runMonitoringCheck(input) {
+	return reportChecks({
+		checks: await resolveMonitoringChecks({
+			loaded: input.loaded,
+			context: input.context,
+			loader: input.loader
+		}),
+		url: input.url,
+		...input.headers ? { headers: input.headers } : {},
+		...input.print ? { print: input.print } : {},
+		...input.logger ? { logger: input.logger } : {},
+		...input.runCheck ? { runCheck: input.runCheck } : {}
+	});
+}
+//#endregion
+//#region src/commands/monitoring-resolve-checks/monitoring-resolve-checks.ts
+/**
+* `holocron monitoring resolve-checks` — loads config/plugins and writes
+* the configured `monitoring` checks to a file as JSON (holocron#1030/
+* #1032 review).
+*
+* The untrusted half of the `delivery.previewCheck` split: this process
+* executes a PR's own `holocron.config.ts`, so it must never run with a
+* credential worth protecting (e.g. a Deployment Protection bypass
+* secret) present in its environment. `monitoring run-resolved` is the
+* trusted half — it reads this command's output file and performs the
+* actual authenticated request, with no config loading at all.
+*/
+async function runMonitoringResolveChecks(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const checks = await resolveMonitoringChecks({
+		loaded: input.loaded,
+		context: input.context,
+		loader: input.loader
+	});
+	await writeFile(input.outFile, JSON.stringify(checks), "utf8");
+	print(`Resolved ${checks.length} monitoring check(s) → ${input.outFile}`);
+}
+//#endregion
+//#region src/commands/monitoring-run-resolved/monitoring-run-resolved.ts
+/**
+* `holocron monitoring run-resolved <url>` — runs an already-resolved
+* check list (no `holocron.config.ts` loading at all) against `url`
+* (holocron#1030/#1032 review).
+*
+* The trusted half of the `delivery.previewCheck` split, paired with
+* `monitoring resolve-checks` (the untrusted half, which loads config).
+* Safe to run with a credential present, since nothing here executes
+* PR-authored code — but a credential is only ever attached after
+* `verifyVercelDeploymentProject` confirms `url` actually belongs to
+* `vercelProject`: a URL merely ending in `.vercel.app` proves nothing,
+* since anyone can register their own Vercel project (sourcery review
+* on holocron#1032). No `vercelProject` given at all → the credential
+* is never attached, regardless of whether one is configured.
+*/
+/**
+* The shared gate every caller that might attach the Deployment
+* Protection bypass header goes through — `monitoring check`'s direct
+* CLI invocation included (sourcery review on holocron#1032 called this
+* out explicitly: verifying only in `delivery.previewCheck`'s own split
+* commands and not here would leave the exact same unverified-host
+* problem reachable by hand). No `vercelProject` → never attach
+* anything, regardless of whether a `bypassSecret` happens to be
+* configured. `vercelProject` given but verification fails or no token
+* is available → `undefined` AND a printed reason, never a thrown
+* error — callers decide for themselves whether that's fatal.
+*/
+async function resolveVercelBypassHeaders(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	if (!input.vercelProject) return { verified: true };
+	if (!input.vercelToken) {
+		print(`✗ --vercel-project was given but no Vercel token is available to verify deployment ownership`);
+		return { verified: false };
+	}
+	if (!await (input.verify ?? verifyVercelDeploymentProject)(input.url, input.vercelProject, input.vercelToken, { ...input.vercelTeamId ? { teamId: input.vercelTeamId } : {} })) {
+		print(`✗ ${input.url} does not resolve to a deployment of Vercel project "${input.vercelProject}" — refusing to attach the Deployment Protection bypass credential or run checks against an unverified URL`);
+		return { verified: false };
+	}
+	return input.bypassSecret ? {
+		verified: true,
+		headers: { "x-vercel-protection-bypass": input.bypassSecret }
+	} : { verified: true };
+}
+async function runMonitoringRunResolved(input) {
+	const { headers, verified } = await resolveVercelBypassHeaders(input);
+	if (!verified) return {
+		status: "fail",
+		checks: []
+	};
+	return reportChecks({
+		checks: input.checks,
+		url: input.url,
+		...headers ? { headers } : {},
+		...input.print ? { print: input.print } : {},
+		...input.logger ? { logger: input.logger } : {},
+		...input.runCheck ? { runCheck: input.runCheck } : {}
+	});
+}
+//#endregion
+//#region src/commands/new/new.ts
+/**
+* `holocron new repo <type> <name>` — create a GitHub repo from a template and
+* bootstrap it by replacing all template-slug casing variants with the new
 * project name, then generate a `holocron.config.ts` from the answers given
 * during the interactive wizard.
 *
@@ -3203,280 +3732,38 @@ async function runNew(input) {
 			}
 			if (!env.get("HOLOCRON_DEPLOY_TOKEN")) {
 				const deployToken = keychainLookup("github.deploy");
-				if (deployToken) setupEnv["HOLOCRON_DEPLOY_TOKEN"] = deployToken;
-			}
-			execFn("holocron", setupArgs, {
-				cwd: repoDir,
-				stdio: "inherit",
-				env: setupEnv
-			});
-		} catch {
-			print("  ✗ holocron repo setup failed — run it manually after checking your config");
-		}
-	}
-	print("");
-	print(`  Scaffolded ${newRepo} (${filesPatched.length} file${filesPatched.length === 1 ? "" : "s"} patched).`);
-	print("");
-	print("  Next:");
-	print(`    1. cd ${repoDir}`);
-	if (input.noVerify) {
-		print(`    2. pnpm install`);
-		print(`    3. holocron repo setup  # wire up secrets, teams, labels, etc.`);
-		print(`    4. git push -u origin HEAD`);
-	} else print(`    2. git push -u origin HEAD`);
-	logger.info({
-		repo: newRepo,
-		repoDir,
-		filesPatched,
-		status: "ok"
-	}, "new: done");
-	return {
-		status: "ok",
-		repoDir,
-		filesPatched
-	};
-}
-//#endregion
-//#region src/commands/notifications-channel-add/notifications-channel-add.ts
-/**
-* `holocron notifications channel add` — create one channel (and, with
-* `--with-webhook`, an inbound webhook whose URL goes straight into a secret).
-*
-* Provider-neutral: it drives the `notifications` capability's `ensure*`
-* methods, so any provider that implements them works. Idempotent — an
-* existing channel or webhook is left alone, and a webhook URL is never
-* printed, only stored.
-*/
-/**
-* `HOLOCRON_NOTIFY_WEBHOOK_SYNC` for channel `sync`. Named after the job, not the
-* provider, so changing providers means re-pointing the same secrets at new
-* webhook URLs, with no workflow edits.
-*/
-function defaultSecretName(channel) {
-	return `HOLOCRON_NOTIFY_WEBHOOK_${channel.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
-}
-/**
-* Prefix of the throwaway secret the preflight writes and removes. Every run adds a
-* random suffix, so it can never overwrite (and then delete) a secret someone already
-* has; layouts may not use any name under this prefix for their own secrets.
-*/
-const PREFLIGHT_PREFIX = "HOLOCRON_NOTIFY_PREFLIGHT";
-/** Whether a secret name is under the preflight's reserved prefix. GitHub secret names are case-insensitive. */
-function isReservedSecret(name) {
-	return name.toUpperCase().startsWith(PREFLIGHT_PREFIX);
-}
-/**
-* Prove the secrets store can be WRITTEN before creating anything that needs it.
-* A webhook's URL is shown once; creating the webhook and then failing to store
-* it leaves an orphan the user has to delete by hand. Listing is not enough --
-* a token can read secrets it cannot write -- so write a throwaway secret and
-* remove it.
-*/
-async function assertSecretsReachable(secrets, scope) {
-	const probe = `${PREFLIGHT_PREFIX}_${randomBytes(4).toString("hex").toUpperCase()}`;
-	try {
-		await secrets.setSecret(scope, probe, "ok");
-		await secrets.deleteSecret(scope, probe);
-	} catch (err) {
-		const where = scope.kind === "organization" ? `organization ${scope.name}` : scope.kind;
-		throw new Error(`cannot write to the secrets store for ${where} (${describeProviderError(err)}) — fix that token before creating webhooks. If a secret named ${probe} was left behind, delete it`, { cause: err });
-	}
-}
-/** Why a capability is not loaded: the plugin's own load error when there is one (e.g. a missing token). */
-function whyMissing(loader, key, fallback) {
-	const failure = loader.loadFailures().find((f) => f.key === key);
-	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${describeProviderError(failure.error)})` : fallback;
-}
-/** The configured `notifications` providers, or an error that says why there are none (including a plugin that failed to load). */
-function notificationProviders(loader) {
-	const providers = loader.has("notifications") ? loader.get("notifications") : [];
-	if (providers.length === 0) throw new Error(whyMissing(loader, "notifications", "no `notifications` provider is available — add one to holocron.config.ts"));
-	return providers;
-}
-/**
-* Pick the provider that can do what the command needs; with several, `--provider`
-* decides. `can` says what "able" means (a command that only reads needs `inspect`, not
-* provisioning), and `verb` words the errors.
-*/
-function pickProvider(providers, wanted, can, verb) {
-	const capable = providers.filter(can);
-	if (capable.length === 0) throw new Error(`no \`notifications\` provider can ${verb.infinitive} — add one that implements it (for example discord) to holocron.config.ts`);
-	if (wanted) {
-		const match = capable.find((p) => p.providerName === wanted);
-		if (!match) throw new Error(`no ${verb.gerund} \`notifications\` provider named \`${wanted}\` (have: ${names(capable)})`);
-		return match;
-	}
-	if (capable.length > 1) throw new Error(`several \`notifications\` providers can ${verb.infinitive} (${names(capable)}) — pass --provider <name>`);
-	return capable[0];
-}
-/** Pick the provider that can provision. Any ensure* method counts: a role-only layout needs no channel support. */
-function pickProvisioner(providers, wanted) {
-	return pickProvider(providers, wanted, (p) => typeof p.ensureChannel === "function" || typeof p.ensureCategory === "function" || typeof p.ensureRole === "function", {
-		infinitive: "provision",
-		gerund: "provisioning"
-	});
-}
-const names = (ps) => ps.map((p) => p.providerName).join(", ");
-/**
-* The first reason the layout's secret names cannot work, or undefined. Two things
-* cannot share one secret: the second write would overwrite the first and callers
-* would read the wrong value. Punctuation normalising (release-notes vs
-* release_notes) makes that easy to hit by accident, GitHub secret names are
-* case-insensitive, and the preflight's own prefix is reserved. Shared by `setup`
-* (which refuses) and `verify` (which reports it).
-*/
-function layoutSecretProblem(layout) {
-	const taken = /* @__PURE__ */ new Map();
-	const claim = (secret, owner, hint) => {
-		if (isReservedSecret(secret)) return `${owner} would store into ${secret}, a name reserved for the setup preflight — choose another`;
-		const key = secret.toUpperCase();
-		const other = taken.get(key);
-		if (other) return `${other} and ${owner} would both store into ${secret} — ${hint}`;
-		taken.set(key, owner);
-	};
-	for (const category of layout.categories ?? []) for (const channel of category.channels ?? []) {
-		if (!channel.webhook) continue;
-		const clash = claim(channel.webhook !== true && channel.webhook.secret || defaultSecretName(channel.name), `channel \`${channel.name}\``, "give one a distinct `webhook.secret`");
-		if (clash) return clash;
-	}
-	for (const role of layout.roles ?? []) {
-		if (!role.secret) continue;
-		const clash = claim(role.secret, `role \`${role.name}\``, "give one a distinct secret");
-		if (clash) return clash;
-	}
-}
-/** Ensure one channel and, if asked, its webhook + secret. Shared with `notifications setup`. */
-async function provisionChannel(deps, spec) {
-	const { notifications, secrets, scope, dryRun, print } = deps;
-	const webhookCfg = spec.webhook || void 0;
-	const secretName = webhookCfg?.secret ?? defaultSecretName(spec.name);
-	const webhookName = webhookCfg?.name ?? spec.name;
-	const where = spec.category ? ` in ${spec.category}` : "";
-	if (!notifications.ensureChannel) throw new Error(`\`${notifications.providerName}\` cannot create channels`);
-	if (webhookCfg && !notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
-	if (webhookCfg && isReservedSecret(secretName)) throw new Error(`secret name ${secretName} is reserved for the setup preflight -- choose another`);
-	if (webhookCfg && !dryRun && !secrets) throw new Error("storing a webhook URL needs a `secrets` provider — add one to holocron.config.ts");
-	if (dryRun) {
-		print(`  … would ensure channel ${spec.name}${where}`);
-		if (webhookCfg) print(`  … would ensure webhook ${webhookName} and store its URL in ${secretName}`);
-		return {
-			name: spec.name,
-			...spec.category ? { category: spec.category } : {},
-			created: false
-		};
-	}
-	const channel = await notifications.ensureChannel({
-		name: spec.name,
-		...spec.category ? { category: spec.category } : {},
-		...spec.topic ? { topic: spec.topic } : {}
-	});
-	print(`  ${channel.created ? "✓ created" : "· exists "} channel ${spec.name}${where}`);
-	const outcome = {
-		name: spec.name,
-		...spec.category ? { category: spec.category } : {},
-		created: channel.created
-	};
-	if (!webhookCfg) return outcome;
-	const hook = await notifications.ensureWebhook({
-		channel: spec.name,
-		name: webhookName,
-		...spec.category ? { category: spec.category } : {}
-	});
-	if (hook.url) {
-		try {
-			await secrets.setSecret(scope, secretName, hook.url);
-		} catch (err) {
-			throw new Error(`webhook ${webhookName} was ${hook.created ? "created" : "found"} but storing its URL in ${secretName} failed (${describeProviderError(err)}) — delete the webhook in the provider and re-run to get a fresh URL`, { cause: err });
-		}
-		print(`  ✓ ${hook.created ? "created" : "found  "} webhook ${webhookName}; URL stored in ${secretName}`);
-		outcome.webhook = {
-			name: webhookName,
-			created: hook.created,
-			secret: secretName,
-			stored: true
-		};
-	} else {
-		const note = `webhook ${webhookName} already exists and its URL cannot be read back — delete it in the provider and re-run, or set ${secretName} yourself`;
-		print(`  ! ${note}`);
-		outcome.webhook = {
-			name: webhookName,
-			created: hook.created,
-			secret: secretName,
-			stored: false,
-			note
-		};
-	}
-	return outcome;
-}
-async function runNotificationsChannelAdd(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
-	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
-	assertPluginsResolvable(loader, "notifications channel add");
-	const dryRun = input.context.dryRun ?? false;
-	print(`Holocron notifications channel add — ${input.name}${dryRun ? " (dry-run)" : ""}`);
-	try {
-		const notifications = pickProvisioner(notificationProviders(loader), input.provider);
-		let secrets;
-		if (input.withWebhook && !dryRun) {
-			if (!loader.has("secrets")) throw new Error(whyMissing(loader, "secrets", "`--with-webhook` needs a `secrets` capability — add a `secrets` provider to holocron.config.ts"));
-			secrets = loader.get("secrets");
-		}
-		const org = input.context.org;
-		const scope = input.scope ?? (org ? {
-			kind: "organization",
-			name: org
-		} : void 0);
-		if (input.withWebhook && !scope && !dryRun) throw new Error("no org to store the webhook secret under — pass --scope or set `org` in holocron.config.ts");
-		if (secrets && scope && !dryRun) await assertSecretsReachable(secrets, scope);
-		const channel = await provisionChannel({
-			notifications,
-			...secrets ? { secrets } : {},
-			scope: scope ?? { kind: "repo" },
-			dryRun,
-			print
-		}, {
-			name: input.name,
-			...input.category ? { category: input.category } : {},
-			...input.topic ? { topic: input.topic } : {},
-			...input.withWebhook ? { webhook: {
-				...input.webhookName ? { name: input.webhookName } : {},
-				...input.secret ? { secret: input.secret } : {}
-			} } : {}
-		});
-		logger.info({
-			channel: input.name,
-			created: channel.created,
-			provider: notifications.providerName,
-			status: "ok"
-		}, `notifications channel add: ${input.name}`);
-		if (channel.webhook && !channel.webhook.stored && !dryRun) {
-			const message = channel.webhook.note;
-			print(`  ✗ ${message}`);
-			return {
-				status: "fail",
-				channel,
-				message
-			};
+				if (deployToken) setupEnv["HOLOCRON_DEPLOY_TOKEN"] = deployToken;
+			}
+			execFn("holocron", setupArgs, {
+				cwd: repoDir,
+				stdio: "inherit",
+				env: setupEnv
+			});
+		} catch {
+			print("  ✗ holocron repo setup failed — run it manually after checking your config");
 		}
-		return {
-			status: dryRun ? "dry-run" : "ok",
-			channel
-		};
-	} catch (err) {
-		const message = describeProviderError(err);
-		print(`  ✗ ${message}`);
-		logger.warn({
-			channel: input.name,
-			reason: logReason(err)
-		}, `notifications channel add: ${input.name}`);
-		return {
-			status: "fail",
-			message
-		};
 	}
+	print("");
+	print(`  Scaffolded ${newRepo} (${filesPatched.length} file${filesPatched.length === 1 ? "" : "s"} patched).`);
+	print("");
+	print("  Next:");
+	print(`    1. cd ${repoDir}`);
+	if (input.noVerify) {
+		print(`    2. pnpm install`);
+		print(`    3. holocron repo setup  # wire up secrets, teams, labels, etc.`);
+		print(`    4. git push -u origin HEAD`);
+	} else print(`    2. git push -u origin HEAD`);
+	logger.info({
+		repo: newRepo,
+		repoDir,
+		filesPatched,
+		status: "ok"
+	}, "new: done");
+	return {
+		status: "ok",
+		repoDir,
+		filesPatched
+	};
 }
 //#endregion
 //#region src/commands/notifications-setup/notifications-setup.ts
@@ -3489,411 +3776,167 @@ async function runNotificationsChannelAdd(input) {
 * missing, so it is safe to re-run and `--dry-run` previews it. A failing step
 * is reported and the rest still run.
 *
-* Run it from ONE repo per server — a layout is org-level, and putting it in a
-* shared preset would apply it from every repo.
-*/
-async function runNotificationsSetup(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
-	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
-	assertPluginsResolvable(loader, "notifications setup");
-	const dryRun = input.context.dryRun ?? false;
-	const report = {
-		status: "ok",
-		categories: [],
-		channels: [],
-		roles: [],
-		failures: []
-	};
-	const refuse = (message, reason = message) => {
-		print(`  ✗ ${message}`);
-		logger.warn({ reason }, "notifications setup");
-		return {
-			...report,
-			status: "fail",
-			message
-		};
-	};
-	let notifications;
-	try {
-		notifications = pickProvisioner(notificationProviders(loader), input.provider);
-	} catch (err) {
-		return refuse(errorMessage(err));
-	}
-	const layout = notifications.layout;
-	if (!layout) return refuse(`the \`${notifications.providerName}\` provider declares no layout — add \`layout\` to its options in holocron.config.ts`);
-	const wantsSecrets = (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.webhook)) || (layout.roles ?? []).some((r) => r.secret);
-	let secrets;
-	if (wantsSecrets && !dryRun) {
-		if (!loader.has("secrets")) return refuse(whyMissing(loader, "secrets", "the layout stores webhook URLs or role ids, which need a `secrets` capability — add a `secrets` provider"));
-		secrets = loader.get("secrets");
-	}
-	const org = input.context.org;
-	const scope = input.scope ?? (org ? {
-		kind: "organization",
-		name: org
-	} : void 0);
-	if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under — pass --scope or set `org` in holocron.config.ts");
-	if (secrets && scope && !dryRun) try {
-		await assertSecretsReachable(secrets, scope);
-	} catch (err) {
-		return refuse(errorMessage(err), logReason(err));
-	}
-	const secretProblem = layoutSecretProblem(layout);
-	if (secretProblem) return refuse(secretProblem);
-	print(`Holocron notifications setup — ${notifications.providerName}${dryRun ? " (dry-run)" : ""}`);
-	const attempt = async (step, fn) => {
-		try {
-			await fn();
-		} catch (err) {
-			const message = describeProviderError(err);
-			print(`  ✗ ${step}: ${message}`);
-			report.failures.push({
-				step,
-				message
-			});
-		}
-	};
-	for (const category of layout.categories ?? []) {
-		print(`\n${category.name}`);
-		report.categories.push(category.name);
-		await attempt(`category ${category.name}`, async () => {
-			if (!notifications.ensureCategory) return;
-			if (dryRun) {
-				print(`  … would ensure category ${category.name}`);
-				return;
-			}
-			const made = await notifications.ensureCategory(category.name);
-			print(`  ${made.created ? "✓ created" : "· exists "} category ${category.name}`);
-		});
-		for (const channel of category.channels ?? []) await attempt(`channel ${channel.name}`, async () => {
-			const outcome = await provisionChannel({
-				notifications,
-				...secrets ? { secrets } : {},
-				scope: scope ?? { kind: "repo" },
-				dryRun,
-				print
-			}, {
-				name: channel.name,
-				category: category.name,
-				...channel.topic ? { topic: channel.topic } : {},
-				...channel.webhook ? { webhook: channel.webhook === true ? {} : channel.webhook } : {}
-			});
-			report.channels.push(outcome);
-			if (outcome.webhook && !outcome.webhook.stored) report.failures.push({
-				step: `webhook ${outcome.webhook.name}`,
-				message: outcome.webhook.note
-			});
-		});
-	}
-	if ((layout.roles ?? []).length > 0) print("\nRoles");
-	for (const role of layout.roles ?? []) await attempt(`role ${role.name}`, async () => {
-		if (!notifications.ensureRole) throw new Error(`\`${notifications.providerName}\` cannot manage roles`);
-		if (dryRun) {
-			print(`  … would ensure role ${role.name}${role.secret ? ` and store its id in ${role.secret}` : ""}`);
-			report.roles.push({
-				name: role.name,
-				created: false,
-				...role.secret ? { secret: role.secret } : {}
-			});
-			return;
-		}
-		const made = await notifications.ensureRole({
-			name: role.name,
-			...role.mentionable !== void 0 ? { mentionable: role.mentionable } : {}
-		});
-		const outcome = {
-			name: role.name,
-			id: made.id,
-			created: made.created
-		};
-		report.roles.push(outcome);
-		print(`  ${made.created ? "✓ created" : "· exists "} role ${role.name} (id ${made.id})`);
-		if (role.secret) {
-			await secrets.setSecret(scope, role.secret, made.id);
-			outcome.secret = role.secret;
-			outcome.stored = true;
-			print(`  ✓ stored the id of ${role.name} in ${role.secret}`);
-		}
-	});
-	if (report.failures.length > 0) {
-		report.status = "fail";
-		print(`\n${report.failures.length} step(s) need attention`);
-	} else if (dryRun) report.status = "dry-run";
-	logger.info({
-		provider: notifications.providerName,
-		channels: report.channels.length,
-		roles: report.roles.length,
-		failures: report.failures.length,
-		status: report.status
-	}, "notifications setup");
-	return report;
-}
-//#endregion
-//#region src/commands/notifications-verify/notifications-verify.ts
-/**
-* `holocron notifications verify` -- read-only: compare the layout a provider
-* declares in `holocron.config.ts` with what is actually on the server and in the
-* secrets store, step by step.
-*
-* It is the end-to-end check for `notifications setup`, and stays useful after
-* as a drift check. Everything the layout and `setup` cannot do yet is listed
-* too, as a failing "not built" step, so the command is red until the last
-* feature lands and each feature built turns exactly one step green. The list
-* is {@link PLANNED_CHECKS}; the numbers match the table in holocron#1098.
-*/
-/** Features not built yet, in the order of the table in holocron#1098. Move an entry into a real check when it lands. */
-const PLANNED_CHECKS = [
-	{
-		step: 8,
-		id: "permissions",
-		title: "channel and category permissions"
-	},
-	{
-		step: 9,
-		id: "role-appearance",
-		title: "role colour, hoist and permissions"
-	},
-	{
-		step: 10,
-		id: "server-settings",
-		title: "server settings (verification, notifications, system channels)"
-	},
-	{
-		step: 11,
-		id: "welcome",
-		title: "welcome and onboarding content"
-	},
-	{
-		step: 12,
-		id: "webhook-appearance",
-		title: "webhook names and avatars"
-	},
-	{
-		step: 13,
-		id: "app-settings",
-		title: "bot application settings (description, tags, install, links)"
-	},
-	{
-		step: 14,
-		id: "role-assignment",
-		title: "role assigned to team members"
-	},
-	{
-		step: 15,
-		id: "post-works",
-		title: "a test post reached every channel (platform.notifyCheck)"
-	},
-	{
-		step: 16,
-		id: "server-creation",
-		title: "the server itself created from config"
-	}
-];
-const same = (a, b) => a.toLowerCase() === b.toLowerCase();
-const shown = (s) => sanitizeDetail(s);
-async function runNotificationsVerify(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
-	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
-	assertPluginsResolvable(loader, "notifications verify");
-	const checks = [];
-	const add = (id, title, problems, pass) => {
-		checks.push({
-			id,
-			title,
-			status: problems.length === 0 ? "pass" : "fail",
-			detail: problems.length === 0 ? pass : `${problems.length} problem(s)`,
-			problems
-		});
-	};
-	const byId = (id) => checks.find((c) => c.id === id);
-	const failed = (id, title, reason) => {
-		checks.push({
-			id,
-			title,
-			status: "fail",
-			detail: reason,
-			problems: []
-		});
-	};
-	const summarise = () => ({
-		pass: checks.filter((c) => c.status === "pass").length,
-		fail: checks.filter((c) => c.status === "fail").length,
-		planned: checks.filter((c) => c.status === "planned").length
-	});
-	const finish = () => {
-		const summary = summarise();
-		const report = {
-			status: summary.fail + summary.planned > 0 ? "fail" : "ok",
-			checks,
-			summary
-		};
-		logger.info({
-			...summary,
-			status: report.status,
-			checks: checks.map((c) => `${c.id}:${c.status}`)
-		}, "notifications verify");
-		return report;
+* Run it from ONE repo per server — a layout is org-level, and putting it in a
+* shared preset would apply it from every repo.
+*/
+async function runNotificationsSetup(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "notifications setup");
+	const dryRun = input.context.dryRun ?? false;
+	const report = {
+		status: "ok",
+		categories: [],
+		channels: [],
+		roles: [],
+		failures: []
 	};
 	const refuse = (message, reason = message) => {
-		print(`  ✗ ${message}`);
-		logger.warn({ reason }, "notifications verify");
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
+		logger.warn({ reason }, "notifications setup");
 		return {
+			...report,
 			status: "fail",
-			checks,
-			summary: summarise(),
 			message
 		};
 	};
 	let notifications;
 	try {
-		notifications = pickProvider(notificationProviders(loader), input.provider, (p) => typeof p.inspect === "function", {
-			infinitive: "inspect a server",
-			gerund: "inspecting"
-		});
+		notifications = pickProvisioner(notificationProviders(loader), input.provider);
 	} catch (err) {
-		return refuse(describeProviderError(err));
+		return refuse(errorMessage(err));
 	}
 	const layout = notifications.layout;
 	if (!layout) return refuse(`the \`${notifications.providerName}\` provider declares no layout — add \`layout\` to its options in holocron.config.ts`);
-	print(`Holocron notifications verify — ${notifications.providerName}\n`);
-	let found;
-	let readError = "";
-	try {
-		found = await notifications.inspect(layout);
-	} catch (err) {
-		readError = describeProviderError(err);
+	const wantsSecrets = (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.webhook)) || (layout.roles ?? []).some((r) => r.secret);
+	let secrets;
+	if (wantsSecrets && !dryRun) {
+		if (!loader.has("secrets")) return refuse(whyMissing(loader, "secrets", "the layout stores webhook URLs or role ids, which need a `secrets` capability — add a `secrets` provider"));
+		secrets = loader.get("secrets");
 	}
-	if (notifications.whoami) try {
-		const who = await notifications.whoami();
-		if (who) checks.push({
-			id: "server",
-			title: "server",
-			status: "pass",
-			detail: shown(who.target),
-			problems: []
-		});
-		else failed("server", "server", "no server configured (the provider's whoami has nothing to check)");
+	const org = input.context.org;
+	const scope = input.scope ?? (org ? {
+		kind: "organization",
+		name: org
+	} : void 0);
+	if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under — pass --scope or set `org` in holocron.config.ts");
+	if (secrets && scope && !dryRun) try {
+		await assertSecretsReachable(secrets, scope);
 	} catch (err) {
-		failed("server", "server", describeProviderError(err));
+		return refuse(errorMessage(err), logReason(err));
 	}
-	else if (found) checks.push({
-		id: "server",
-		title: "server",
-		status: "pass",
-		detail: "readable (the provider has no whoami)",
-		problems: []
-	});
-	else failed("server", "server", readError);
-	const declaredChannels = (layout.categories ?? []).flatMap((cat) => (cat.channels ?? []).map((channel) => ({
-		cat: cat.name,
-		channel
-	})));
-	const pick = (name, category) => {
-		const named = found.channels.filter((c) => same(c.name, name));
-		return {
-			named,
-			match: named.find((c) => c.category !== void 0 && same(c.category, category))
-		};
+	const secretProblem = layoutSecretProblem(layout);
+	if (secretProblem) return refuse(secretProblem);
+	const providerProblem = notifications.validateLayout?.(layout);
+	if (providerProblem) return refuse(providerProblem);
+	const tally = {
+		ok: 0,
+		skip: 0
 	};
-	if (!found) {
-		if (byId("server")?.status !== "fail") failed("read", "read server", readError);
-		for (const [id, title] of [
-			["categories", "categories"],
-			["channels", "channels"],
-			["webhooks", "webhooks"],
-			["roles", "roles"]
-		]) failed(id, title, "not checked: could not read the server");
-	} else {
-		const inspected = found;
-		const categories = layout.categories ?? [];
-		add("categories", "categories", categories.filter((cat) => !inspected.categories.some((name) => same(name, cat.name))).map((cat) => `${shown(cat.name)}: missing`), categories.length === 0 ? "none declared" : `${categories.length} of ${categories.length} exist`);
-		const channelProblems = [];
-		for (const { cat, channel } of declaredChannels) {
-			const { named, match } = pick(channel.name, cat);
-			if (named.length === 0) {
-				channelProblems.push(`#${shown(channel.name)}: missing`);
-				continue;
-			}
-			if (!match) {
-				const where = named.map((c) => c.category ?? "no category").join(", ");
-				channelProblems.push(`#${shown(channel.name)}: exists, but under ${shown(where)} and not ${shown(cat)}`);
-				continue;
-			}
-			if (channel.topic && (match.topic ?? "") !== channel.topic) channelProblems.push(`#${shown(channel.name)}: topic is "${shown(match.topic ?? "")}" but the layout says "${shown(channel.topic)}"`);
-		}
-		add("channels", "channels", channelProblems, declaredChannels.length === 0 ? "none declared" : `${declaredChannels.length} of ${declaredChannels.length} as declared`);
-		const withWebhook = declaredChannels.filter(({ channel }) => channel.webhook);
-		const webhookProblems = [];
-		for (const { cat, channel } of withWebhook) {
-			const name = (channel.webhook === true ? {} : channel.webhook).name ?? channel.name;
-			const { match } = pick(channel.name, cat);
-			if (!match) webhookProblems.push(`#${shown(channel.name)}: no channel to hold the webhook`);
-			else if (match.webhooksError) webhookProblems.push(`#${shown(channel.name)}: could not list its webhooks (${shown(match.webhooksError)})`);
-			else if (!match.webhooks.some((w) => same(w, name))) webhookProblems.push(`#${shown(channel.name)}: no webhook named ${shown(name)}`);
-		}
-		add("webhooks", "webhooks", webhookProblems, withWebhook.length === 0 ? "none declared" : `${withWebhook.length} of ${withWebhook.length} exist`);
-		const roles = layout.roles ?? [];
-		const roleProblems = [];
-		if (inspected.rolesError) roleProblems.push(`could not read the roles (${shown(inspected.rolesError)})`);
-		for (const role of inspected.rolesError ? [] : roles) {
-			const actual = inspected.roles.find((r) => same(r.name, role.name));
-			if (!actual) roleProblems.push(`${shown(role.name)}: missing`);
-			else if (role.mentionable !== void 0 && actual.mentionable !== role.mentionable) roleProblems.push(`${shown(role.name)}: mentionable is ${actual.mentionable} but the layout says ${role.mentionable}`);
-		}
-		add("roles", "roles", roleProblems, roles.length === 0 ? "none declared" : `${roles.length} of ${roles.length} as declared`);
-	}
-	const wanted = [...declaredChannels.filter(({ channel }) => channel.webhook).map(({ channel }) => channel.webhook !== true && channel.webhook && channel.webhook.secret ? channel.webhook.secret : defaultSecretName(channel.name)), ...(layout.roles ?? []).flatMap((r) => r.secret ? [r.secret] : [])];
-	if (wanted.length === 0) checks.push({
-		id: "secrets",
-		title: "secrets",
-		status: "pass",
-		detail: "none declared",
-		problems: []
-	});
-	else if (!loader.has("secrets")) failed("secrets", "secrets", whyMissing(loader, "secrets", "no `secrets` provider to check them with"));
-	else {
-		const org = input.context.org;
-		const scope = input.scope ?? (org ? {
-			kind: "organization",
-			name: org
-		} : void 0);
-		if (!scope) failed("secrets", "secrets", "no org to look under — pass --scope or set `org` in holocron.config.ts");
-		else try {
-			const have = new Set((await loader.get("secrets").listSecrets(scope)).map((n) => n.toUpperCase()));
-			const clash = layoutSecretProblem(layout);
-			add("secrets", "secrets", [...clash ? [shown(clash)] : [], ...wanted.filter((n) => !have.has(n.toUpperCase())).map((n) => `${shown(n)}: missing`)], `${wanted.length} of ${wanted.length} exist`);
+	const made = (created) => void (created ? tally.ok++ : tally.skip++);
+	const attempt = async (step, fn) => {
+		try {
+			await fn();
 		} catch (err) {
-			failed("secrets", "secrets", describeProviderError(err));
+			const message = describeProviderError(err);
+			print(`  ${style.fail(`${step}: ${message}`)}`);
+			report.failures.push({
+				step,
+				message
+			});
 		}
+	};
+	for (const category of layout.categories ?? []) {
+		print(`\n${style.header(category.name)}`);
+		report.categories.push(category.name);
+		await attempt(`category ${category.name}`, async () => {
+			if (!notifications.ensureCategory) return;
+			if (dryRun) {
+				print(`  ${style.skip(`would ensure category ${category.name}`)}`);
+				tally.skip++;
+				return;
+			}
+			const result = await notifications.ensureCategory(category.name);
+			print(`  ${(result.created ? style.success : style.skip)(`${result.created ? "created" : "exists "} category ${category.name}`)}`);
+			made(result.created);
+		});
+		for (const channel of category.channels ?? []) await attempt(`channel ${channel.name}`, async () => {
+			const outcome = await provisionChannel({
+				notifications,
+				...secrets ? { secrets } : {},
+				scope: scope ?? { kind: "repo" },
+				dryRun,
+				print,
+				tally
+			}, {
+				name: channel.name,
+				category: category.name,
+				...channel.topic ? { topic: channel.topic } : {},
+				...channel.webhook ? { webhook: channel.webhook === true ? {} : channel.webhook } : {}
+			});
+			report.channels.push(outcome);
+			if (outcome.webhook && !outcome.webhook.stored) report.failures.push({
+				step: `webhook ${outcome.webhook.name}`,
+				message: outcome.webhook.note
+			});
+		});
 	}
-	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
-		id: planned.id,
-		title: planned.title,
-		status: "planned",
-		detail: `not built yet (#1098, step ${planned.step})`,
-		problems: [],
-		step: planned.step
+	if ((layout.roles ?? []).length > 0) print(`\n${style.header("Roles")}`);
+	for (const role of layout.roles ?? []) await attempt(`role ${role.name}`, async () => {
+		if (!notifications.ensureRole) throw new Error(`\`${notifications.providerName}\` cannot manage roles`);
+		if (dryRun) {
+			print(`  ${style.skip(`would ensure role ${role.name}${role.secret ? ` and store its id in ${role.secret}` : ""}`)}`);
+			tally.skip++;
+			report.roles.push({
+				name: role.name,
+				created: false,
+				...role.secret ? { secret: role.secret } : {}
+			});
+			return;
+		}
+		const result = await notifications.ensureRole({
+			name: role.name,
+			...role.mentionable !== void 0 ? { mentionable: role.mentionable } : {},
+			...role.color !== void 0 ? { color: role.color } : {},
+			...role.hoist !== void 0 ? { hoist: role.hoist } : {},
+			...role.permissions !== void 0 ? { permissions: role.permissions } : {}
+		});
+		const outcome = {
+			name: role.name,
+			id: result.id,
+			created: result.created,
+			...result.updated?.length ? { updated: result.updated } : {}
+		};
+		report.roles.push(outcome);
+		const changed = result.created || (result.updated?.length ?? 0) > 0;
+		const verb = result.created ? "created" : changed ? "updated" : "exists ";
+		print(`  ${(changed ? style.success : style.skip)(`${verb} role ${role.name} (id ${result.id})${result.updated?.length ? `: ${result.updated.join(", ")}` : ""}`)}`);
+		made(changed);
+		if (role.secret) {
+			await secrets.setSecret(scope, role.secret, result.id);
+			outcome.secret = role.secret;
+			outcome.stored = true;
+			print(`  ${style.success(`stored the id of ${role.name} in ${role.secret}`)}`);
+			tally.ok++;
+		}
 	});
-	const built = checks.filter((c) => c.status !== "planned");
-	const width = Math.max(...built.map((c) => c.title.length));
-	for (const check of built) {
-		print(`  ${check.status === "pass" ? "✓" : "✗"} ${check.title.padEnd(width)}  ${check.detail}`);
-		for (const problem of check.problems) print(`      - ${problem}`);
-	}
-	const planned = checks.filter((c) => c.status === "planned");
-	if (planned.length > 0) {
-		print("\nNot built yet (each fails until it lands, see #1098):");
-		for (const check of planned) print(`  ✗ ${String(check.step).padStart(2)}  ${check.title}`);
-	}
-	const summary = summarise();
-	print(`\n${summary.pass} passed, ${summary.fail} failed${input.builtOnly ? "" : `, ${summary.planned} not built`}`);
-	return finish();
+	if (report.failures.length > 0) report.status = "fail";
+	else if (dryRun) report.status = "dry-run";
+	print("");
+	print(style.header(`${tally.ok} ok, ${report.failures.length} fail, ${tally.skip} skipped`));
+	logger.info({
+		provider: notifications.providerName,
+		channels: report.channels.length,
+		roles: report.roles.length,
+		failures: report.failures.length,
+		status: report.status
+	}, "notifications setup");
+	return report;
 }
 //#endregion
 //#region src/commands/npm-bump-versions/npm-bump-versions.ts
@@ -10033,7 +10076,7 @@ const COMMAND_REGISTRY = [
 		supportsDryRun: true
 	},
 	{
-		name: "notifications verify",
+		name: "doctor notifications",
 		description: "Check the layout against the server and the secrets store, step by step (read-only)",
 		positionals: [],
 		supportsDryRun: false
@@ -10865,6 +10908,32 @@ try {
 	}).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
 		type: "string",
 		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
+	}).command("notifications", "Check the layout against the server and the secrets store, step by step (read-only)", (y) => y.option("scope", {
+		type: "string",
+		describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
+	}).option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can inspect"
+	}).option("built-only", {
+		type: "boolean",
+		default: false,
+		describe: "Leave out the features that are not built yet (a routine drift check)"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runDoctorNotifications({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			...argv.scope ? { scope: parseScope(argv.scope) } : {},
+			...argv.provider ? { provider: argv.provider } : {},
+			...argv.builtOnly ? { builtOnly: true } : {}
+		})).status === "fail") process.exitCode = 1;
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
@@ -11596,32 +11665,6 @@ try {
 			...argv.scope ? { scope: parseScope(argv.scope) } : {},
 			...argv.provider ? { provider: argv.provider } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("verify", "Check the layout against the server and the secrets store, step by step (read-only)", (y) => y.option("scope", {
-		type: "string",
-		describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
-	}).option("provider", {
-		type: "string",
-		describe: "Which notifications provider, when several can inspect"
-	}).option("built-only", {
-		type: "boolean",
-		default: false,
-		describe: "Leave out the features that are not built yet (a routine drift check)"
-	}), async (argv) => {
-		const tokens = tokenContext(argv.token);
-		if (!tokens) return;
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runNotificationsVerify({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
-			...argv.scope ? { scope: parseScope(argv.scope) } : {},
-			...argv.provider ? { provider: argv.provider } : {},
-			...argv.builtOnly ? { builtOnly: true } : {}
-		})).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchGroupMenu("notifications", argv);
 	}), () => {}).command("sync", "Sync generated files to other repos", (g) => g.command("github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {