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

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,849 +2634,1179 @@ 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
-* project name, then generate a `holocron.config.ts` from the answers given
-* during the interactive wizard.
-*
-* Flow:
-*   1. Preflight — verify `gh` CLI is available.
-*   2. Resolve type, name, description, homepage, vault/deployment/agent options.
-*   3. `gh repo create <org>/<name> --template <org>/<type>-template --private --clone`
-*      → clones to `<cwd>/<name>/`
-*   4. Detect template slug from cloned package.json.
-*   5. Replace all casing variants of the slug across every text file.
-*   6. Replace `<description>` and `<homepage>` placeholders.
-*   7. Generate and write `holocron.config.ts` based on wizard answers.
-*   8. Commit the patched files (-s for DCO).
-*   9. Unless --no-verify: `pnpm install` in the new repo.
-*  10. Print next steps.
+* 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).
 */
-var NewError = class extends Error {
-	name = "NewError";
-};
-function cap(word) {
-	return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+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;
+	}
 }
-/**
-* Derive all common casing variants of a kebab-case slug (e.g.
-* "cli-template") and map each to the corresponding form of a
-* kebab-case name (e.g. "my-tool").
-*
-* Returns search→replacement pairs, deduplicating single-word slugs
-* that would otherwise produce identical entries.
-*/
-function deriveVariants(slug, name) {
-	const sw = slug.split("-");
-	const nw = name.split("-");
-	const pairs = [
-		[slug, name],
-		[sw.join("_"), nw.join("_")],
-		[sw.join("_").toUpperCase(), nw.join("_").toUpperCase()],
-		[sw.map(cap).join(""), nw.map(cap).join("")],
-		[sw[0].toLowerCase() + sw.slice(1).map(cap).join(""), nw[0].toLowerCase() + nw.slice(1).map(cap).join("")],
-		[sw.map(cap).join(" "), nw.map(cap).join(" ")]
-	];
-	const seen = /* @__PURE__ */ new Set();
-	return pairs.filter(([s]) => {
-		if (seen.has(s)) return false;
-		seen.add(s);
-		return true;
+/** 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 } : {},
+		...spec.access ? { access: spec.access } : {}
 	});
+	const changed = channel.created || (channel.updated?.length ?? 0) > 0;
+	const verb = channel.created ? "created" : changed ? "updated" : "exists ";
+	const what = channel.updated?.length ? `: ${channel.updated.join(", ")}` : "";
+	print(`  ${(changed ? style.success : style.skip)(`${verb} channel ${spec.name}${where}${what}`)}`);
+	if (tally) tally[changed ? "ok" : "skip"]++;
+	const outcome = {
+		name: spec.name,
+		...spec.category ? { category: spec.category } : {},
+		created: channel.created,
+		...channel.updated?.length ? { updated: channel.updated } : {}
+	};
+	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;
 }
-/** Validate a repo name: must be lowercase kebab-case. Returns `true` on success or an error string. */
-function validateRepoName(v) {
-	return /^[a-z][a-z0-9-]*$/.test(v.trim()) ? true : "Must be lowercase kebab-case (e.g. my-tool)";
-}
-/** Parse a comma-separated topics string into a trimmed, non-empty array. */
-function parseTopics(raw) {
-	return raw ? String(raw).split(",").map((t) => t.trim()).filter(Boolean) : [];
+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
 /**
-* Generate the content of `holocron.config.ts` for a newly-scaffolded repo.
-* Uses the `node()` preset from `@theholocron/holocron-config` as the baseline
-* and layers in the provider/agent choices made during the wizard.
+* `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.
 */
-function generateHolocronConfig(opts) {
-	const lines = [
-		`import { defineConfig } from "@theholocron/cli";`,
-		`import { compose, node, typecheck } from "@theholocron/holocron-config";`,
-		``,
-		`const preset = compose(node(), typecheck());`,
-		`export default defineConfig({`,
-		`\t...preset,`
-	];
-	if (opts.description) lines.push(`\tdescription: ${JSON.stringify(opts.description)},`);
-	if (opts.homepage) lines.push(`\thomepage: ${JSON.stringify(opts.homepage)},`);
-	const topics = opts.topics?.length ? opts.topics : [];
-	const hasRuntimeOverride = opts.runtimeEnvironment != null && opts.runtimeEnvironment !== "node";
-	if (opts.org != null) {
-		const repoName = `${opts.org}/${opts.name}`;
-		lines.push(`\trepo: {`);
-		lines.push(`\t\t...preset.repo,`);
-		lines.push(`\t\tname: ${JSON.stringify(repoName)},`);
-		lines.push(`\t\tteams: [{ slug: "gatekeepers", permission: "maintain" }],`);
-		lines.push(`\t\ttopics: ${JSON.stringify(topics)},`);
-		if (opts.protection && opts.protection !== "strict") lines.push(`\t\tprotection: ${JSON.stringify(opts.protection)},`);
-		const propParts = [];
-		if (hasRuntimeOverride) propParts.push(`runtime_environment: ${JSON.stringify(opts.runtimeEnvironment)}`);
-		if (opts.openSource === false) propParts.push(`open_source: false`);
-		if (opts.usesExternalPackages === false) propParts.push(`uses_external_packages: false`);
-		if (propParts.length > 0) lines.push(`\t\tproperties: { ...preset.repo?.properties, ${propParts.join(", ")} },`);
-		lines.push(`\t},`);
-	} else if (topics.length > 0 || hasRuntimeOverride) {
-		lines.push(`\trepo: {`);
-		lines.push(`\t\t...preset.repo,`);
-		if (topics.length > 0) lines.push(`\t\ttopics: ${JSON.stringify(topics)},`);
-		if (hasRuntimeOverride) lines.push(`\t\tproperties: { ...preset.repo?.properties, runtime_environment: ${JSON.stringify(opts.runtimeEnvironment)} },`);
-		lines.push(`\t},`);
+/** 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: 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 hasVault = opts.vaultProvider && opts.vaultProvider !== "none";
-	const hasDeployment = opts.deploymentProvider && opts.deploymentProvider !== "none";
-	if (hasVault || hasDeployment) {
-		lines.push(`\tproviders: {`);
-		lines.push(`\t\t...preset.providers,`);
-		if (opts.vaultProvider === "doppler") {
-			const proj = JSON.stringify(opts.vaultProject ?? opts.name);
-			const cfg = JSON.stringify(opts.vaultConfig ?? "dev");
-			lines.push(`\t\tvault: ["doppler", { project: ${proj}, config: ${cfg} }],`);
-		} else if (opts.vaultProvider === "1password") {
-			const vault = JSON.stringify(opts.vaultProject ?? opts.name);
-			lines.push(`\t\tvault: ["1password", { vault: ${vault} }],`);
-		} else if (opts.vaultProvider === "infisical") {
-			const proj = JSON.stringify(opts.vaultProject ?? opts.name);
-			lines.push(`\t\tvault: ["infisical", { project: ${proj} }],`);
+];
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+/** `everyone`, or the roles sorted and lower-cased, so order and case do not matter when comparing. */
+const accessKey = (v) => v === "everyone" ? "everyone" : JSON.stringify([...new Set(v.map((r) => r.toLowerCase()))].sort());
+const accessText = (v) => v === "everyone" ? "everyone" : v.length === 0 ? "nobody (bots and webhooks only)" : v.join(", ");
+const shown = (s) => sanitizeDetail(s);
+const ACCESS_TITLE = "channel and category access set";
+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],
+			["access", ACCESS_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)}"`);
 		}
-		if (opts.deploymentProvider === "vercel") lines.push(`\t\tdeployment: "vercel",`);
-		lines.push(`\t},`);
-	}
-	if (opts.agent && opts.agent !== "none") lines.push(`\tagent: ${JSON.stringify(opts.agent)},`);
-	if (opts.skills?.length) lines.push(`\tskills: ${JSON.stringify(opts.skills)},`);
-	lines.push(`});`);
-	lines.push(``);
-	return lines.join("\n");
-}
-const SKIP_DIRS$1 = [
-	".git",
-	"node_modules",
-	"dist",
-	".turbo"
-];
-const defaultWalkFiles$1 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$1 });
-function isBinary(content) {
-	for (let i = 0; i < Math.min(content.length, 8e3); i++) if (content.charCodeAt(i) === 0) return true;
-	return false;
-}
-function patchFiles(dir, variants, description, homepage, runtimeEnvironment, print, readFn, writeFn, walkFn) {
-	const patched = [];
-	for (const filepath of walkFn(dir)) {
-		let content;
-		try {
-			content = readFn(filepath);
-		} catch {
-			continue;
+		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)}`);
 		}
-		if (isBinary(content)) continue;
-		const original = content;
-		for (const [search, replacement] of variants) content = content.split(search).join(replacement);
-		if (description !== void 0) {
-			content = content.split("<description>").join(description);
-			content = content.replace(/(<!-- holocron:description -->)[\s\S]*?(<!-- \/holocron:description -->)/g, `$1\n${description}\n$2`);
+		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}`);
 		}
-		if (homepage !== void 0) content = content.split("<homepage>").join(homepage);
-		if (runtimeEnvironment !== void 0) content = content.split("<runtime_environment>").join(runtimeEnvironment);
-		content = content.replace(/\n?<!-- holocron:template-only -->[\s\S]*?<!-- \/holocron:template-only -->\n?/g, "");
-		if (content !== original) {
-			writeFn(filepath, content);
-			print(`  ✓ ${path.relative(dir, filepath)}`);
-			patched.push(filepath);
+		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 accessProblems = [];
+		const compare = (label, want, have) => {
+			if (!have) {
+				accessProblems.push(`${label}: the provider did not report its access`);
+				return;
+			}
+			if (have === "custom") {
+				accessProblems.push(`${label}: has permission overwrites that are not an access the layout can state; re-run setup to replace them`);
+				return;
+			}
+			for (const field of ["view", "post"]) {
+				const wanted = want[field] ?? "everyone";
+				if (accessKey(wanted) !== accessKey(have[field])) accessProblems.push(`${label}: ${field} is ${accessText(have[field])} but the layout says ${accessText(wanted)}`);
+			}
+		};
+		let accessDeclared = 0;
+		for (const cat of categories) {
+			if (cat.access) {
+				accessDeclared++;
+				if (!inspected.categories.some((name) => same(name, cat.name))) accessProblems.push(`${shown(cat.name)}: not checked, the category is missing`);
+				else {
+					const have = Object.entries(inspected.categoryAccess ?? {}).find(([n]) => same(n, cat.name))?.[1];
+					compare(shown(cat.name), cat.access, have);
+				}
+			}
+			for (const channel of cat.channels ?? []) {
+				if (!cat.access && !channel.access) continue;
+				accessDeclared++;
+				const want = {
+					...cat.access,
+					...channel.access
+				};
+				const { match } = pick(channel.name, cat.name);
+				if (!match) accessProblems.push(`#${shown(channel.name)}: not checked, the channel is missing`);
+				else compare(`#${shown(channel.name)}`, want, match.access);
+			}
 		}
+		add("access", ACCESS_TITLE, inspected.rolesError && accessDeclared > 0 ? ["not checked: could not read the roles"] : accessProblems, accessDeclared === 0 ? "none declared" : `${accessDeclared} of ${accessDeclared} as declared`);
 	}
-	return patched;
-}
-function preflight$1() {
-	const result = spawnSync("gh", ["--version"], { encoding: "utf8" });
-	if (result.error != null || result.status !== 0) throw new NewError("`gh` CLI is not installed or not on PATH. Install it from https://cli.github.com");
-}
-function defaultExec$3(cmd, args, opts) {
-	execFileSync(cmd, args, {
-		cwd: opts.cwd,
-		stdio: opts.stdio,
-		...opts.env && Object.keys(opts.env).length > 0 ? { env: {
-			...process.env,
-			...opts.env
-		} } : {}
+	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();
 }
-function keychainLookup(key) {
-	const result = spawnSync("security", [
-		"find-generic-password",
-		"-s",
-		"com.theholocron.cli",
-		"-a",
-		key,
-		"-w"
-	], { encoding: "utf8" });
-	return result.status === 0 ? result.stdout?.trim() || void 0 : void 0;
-}
-function defaultReadFile(filepath) {
-	return readFileSync(filepath, "utf-8");
-}
-function defaultWriteFile(filepath, content) {
-	mkdirSync(path.dirname(filepath), { recursive: true });
-	writeFileSync(filepath, content, "utf-8");
+//#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];
 }
-async function runNew(input) {
-	const cwd = input.cwd ?? process.cwd();
-	const org = input.org ?? "theholocron";
+/**
+* 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 execFn = input.exec ?? defaultExec$3;
-	const readFn = input.readFile ?? defaultReadFile;
-	const writeFn = input.writeFile ?? defaultWriteFile;
-	const walkFn = input.walkFiles ?? defaultWalkFiles$1;
-	preflight$1();
-	const templateRepo = `${org}/${input.type}-template`;
-	const newRepo = `${org}/${input.name}`;
-	const repoDir = path.join(cwd, input.name);
-	logger.info({
-		repo: newRepo,
-		template: templateRepo,
-		dryRun: input.dryRun || void 0
-	}, "new: start");
-	if (input.dryRun) {
-		print(`  Would create ${newRepo} from template ${templateRepo}`);
-		print(`  Would clone to ${repoDir}`);
-		print(`  Would patch all casing variants of "${input.type}-template" → "${input.name}"`);
-		if (input.description) print(`  Would replace <description> → "${input.description}"`);
-		if (input.homepage) print(`  Would replace <homepage> → "${input.homepage}"`);
-		if (input.runtimeEnvironment) print(`  Would replace <runtime_environment> → "${input.runtimeEnvironment}"`);
-		print(`  Would generate holocron.config.ts`);
-		logger.info({
-			repo: newRepo,
-			status: "dry-run"
-		}, "new: done");
-		return { status: "dry-run" };
-	}
-	if (existsSync(repoDir)) throw new NewError(`\`${repoDir}\` already exists — delete it or pick a different name.`);
-	print(`  Creating ${newRepo} from template ${templateRepo}…`);
-	const visibility = input.openSource ? "--public" : "--private";
-	try {
-		execFn("gh", [
-			"repo",
-			"create",
-			newRepo,
-			`--template=${templateRepo}`,
-			visibility,
-			"--clone"
-		], {
-			cwd,
-			stdio: "inherit"
-		});
-	} catch (err) {
-		throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
-	}
-	if (input.isTemplate) try {
-		execFn("gh", [
-			"repo",
-			"edit",
-			newRepo,
-			"--template=true"
-		], {
-			cwd,
-			stdio: "inherit"
-		});
-	} catch {}
-	try {
-		execFn("gh", [
-			"repo",
-			"edit",
-			newRepo,
-			`--visibility=${input.openSource ? "public" : "private"}`
-		], {
-			cwd,
-			stdio: "inherit"
+	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 } : {}
 		});
-	} catch {}
-	let templateSlug = `${input.type}-template`;
-	const pkgJsonPath = path.join(repoDir, "package.json");
-	if (existsSync(pkgJsonPath)) try {
-		const pkg = JSON.parse(readFn(pkgJsonPath));
-		if (typeof pkg.name === "string") templateSlug = pkg.name.split("/").at(-1) || templateSlug;
-	} catch {}
-	print(`  Detected template slug: ${templateSlug}`);
-	print(`  Patching files…`);
-	const variants = deriveVariants(templateSlug, input.name);
-	variants.unshift([`theholocron/${templateSlug}`, `${org}/${input.name}`]);
-	const filesPatched = patchFiles(repoDir, variants, input.description, input.homepage, input.runtimeEnvironment, print, readFn, writeFn, walkFn);
-	print(`  ${filesPatched.length} file${filesPatched.length === 1 ? "" : "s"} patched`);
-	if (input.description !== void 0 || input.homepage !== void 0) try {
-		const raw = readFn(pkgJsonPath);
-		const pkg = JSON.parse(raw);
-		if (input.description !== void 0) pkg["description"] = input.description;
-		if (input.homepage !== void 0) pkg["homepage"] = input.homepage;
-		writeFn(pkgJsonPath, stringifyJson(pkg, { like: raw }));
-		print(`  ✓ package.json (description/homepage)`);
-	} catch {}
-	const displayName = input.name.split("-").map(cap).join(" ");
-	const rootTsconfigPath = path.join(repoDir, "tsconfig.json");
-	try {
-		const rawTsconfig = readFn(rootTsconfigPath);
-		const tsconfig = JSON.parse(rawTsconfig);
-		if (typeof tsconfig["display"] === "string") {
-			tsconfig["display"] = displayName;
-			writeFn(rootTsconfigPath, stringifyJson(tsconfig, { like: rawTsconfig }));
-			print(`  ✓ tsconfig.json (display)`);
-		}
-	} catch {}
-	const configContent = generateHolocronConfig({
-		name: input.name,
-		type: input.type,
-		org,
-		description: input.description,
-		homepage: input.homepage,
-		vaultProvider: input.vaultProvider,
-		vaultProject: input.vaultProject,
-		vaultConfig: input.vaultConfig,
-		deploymentProvider: input.deploymentProvider,
-		agent: input.agent,
-		runtimeEnvironment: input.runtimeEnvironment,
-		protection: input.protection,
-		openSource: input.openSource,
-		usesExternalPackages: input.usesExternalPackages,
-		topics: input.topics,
-		skills: input.skills
-	});
-	writeFn(path.join(repoDir, "holocron.config.ts"), configContent);
-	print(`  Generated holocron.config.ts`);
-	execFn("git", ["add", "-A"], {
-		cwd: repoDir,
-		stdio: "inherit"
-	});
-	execFn("git", [
-		"commit",
-		"-s",
-		"-m",
-		`chore: bootstrap from ${templateSlug}`
-	], {
-		cwd: repoDir,
-		stdio: "inherit"
-	});
-	if (!input.noVerify) {
-		print("");
-		print("  Installing dependencies…");
-		try {
-			execFn("pnpm", ["install"], {
-				cwd: repoDir,
-				stdio: "inherit"
+		if (result.requestError) {
+			print(`  ✗ ${checkInput.name}  (request failed: ${result.requestError})`);
+			checks.push({
+				name: checkInput.name,
+				passed: false,
+				failures: [],
+				requestError: result.requestError
 			});
-		} catch (err) {
-			print(`  ✗ pnpm install failed — ${errorMessage(err)}`);
-			return {
-				status: "fail",
-				repoDir,
-				filesPatched,
-				message: "pnpm install failed; inspect output above"
-			};
-		}
-		print("");
-		print("  Running holocron repo setup…");
-		try {
-			const setupArgs = ["setup"];
-			const setupEnv = {};
-			const adminToken = input.token ?? keychainLookup("github.admin");
-			if (adminToken) setupArgs.push("--token", adminToken);
-			if (!env.get("HOLOCRON_ORG_TOKEN")) {
-				const orgToken = keychainLookup("github.org");
-				if (orgToken) setupEnv["HOLOCRON_ORG_TOKEN"] = orgToken;
-			}
-			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
+		} 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
 			});
-		} 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`);
+	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({
-		repo: newRepo,
-		repoDir,
-		filesPatched,
-		status: "ok"
-	}, "new: done");
+		url: input.url,
+		total: checks.length,
+		failed: failCount,
+		status
+	}, "monitoring check: done");
 	return {
-		status: "ok",
-		repoDir,
-		filesPatched
+		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/notifications-channel-add/notifications-channel-add.ts
+//#region src/commands/monitoring-resolve-checks/monitoring-resolve-checks.ts
 /**
-* `holocron notifications channel add` — create one channel (and, with
-* `--with-webhook`, an inbound webhook whose URL goes straight into a secret).
+* `holocron monitoring resolve-checks` — loads config/plugins and writes
+* the configured `monitoring` checks to a file as JSON (holocron#1030/
+* #1032 review).
 *
-* 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.
+* 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_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.
+* `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.
 */
-function defaultSecretName(channel) {
-	return `HOLOCRON_NOTIFY_WEBHOOK_${channel.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+/**
+* 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
 /**
-* 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.
+* `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.
+*
+* Flow:
+*   1. Preflight — verify `gh` CLI is available.
+*   2. Resolve type, name, description, homepage, vault/deployment/agent options.
+*   3. `gh repo create <org>/<name> --template <org>/<type>-template --private --clone`
+*      → clones to `<cwd>/<name>/`
+*   4. Detect template slug from cloned package.json.
+*   5. Replace all casing variants of the slug across every text file.
+*   6. Replace `<description>` and `<homepage>` placeholders.
+*   7. Generate and write `holocron.config.ts` based on wizard answers.
+*   8. Commit the patched files (-s for DCO).
+*   9. Unless --no-verify: `pnpm install` in the new repo.
+*  10. Print next steps.
 */
-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);
+var NewError = class extends Error {
+	name = "NewError";
+};
+function cap(word) {
+	return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
 }
 /**
-* 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.
+* Derive all common casing variants of a kebab-case slug (e.g.
+* "cli-template") and map each to the corresponding form of a
+* kebab-case name (e.g. "my-tool").
+*
+* Returns search→replacement pairs, deduplicating single-word slugs
+* that would otherwise produce identical entries.
 */
-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;
+function deriveVariants(slug, name) {
+	const sw = slug.split("-");
+	const nw = name.split("-");
+	const pairs = [
+		[slug, name],
+		[sw.join("_"), nw.join("_")],
+		[sw.join("_").toUpperCase(), nw.join("_").toUpperCase()],
+		[sw.map(cap).join(""), nw.map(cap).join("")],
+		[sw[0].toLowerCase() + sw.slice(1).map(cap).join(""), nw[0].toLowerCase() + nw.slice(1).map(cap).join("")],
+		[sw.map(cap).join(" "), nw.map(cap).join(" ")]
+	];
+	const seen = /* @__PURE__ */ new Set();
+	return pairs.filter(([s]) => {
+		if (seen.has(s)) return false;
+		seen.add(s);
+		return true;
+	});
 }
-/**
-* 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];
+/** Validate a repo name: must be lowercase kebab-case. Returns `true` on success or an error string. */
+function validateRepoName(v) {
+	return /^[a-z][a-z0-9-]*$/.test(v.trim()) ? true : "Must be lowercase kebab-case (e.g. my-tool)";
 }
-/** 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"
-	});
+/** Parse a comma-separated topics string into a trimmed, non-empty array. */
+function parseTopics(raw) {
+	return raw ? String(raw).split(",").map((t) => t.trim()).filter(Boolean) : [];
 }
-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).
+* Generate the content of `holocron.config.ts` for a newly-scaffolded repo.
+* Uses the `node()` preset from `@theholocron/holocron-config` as the baseline
+* and layers in the provider/agent choices made during the wizard.
 */
-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;
+function generateHolocronConfig(opts) {
+	const lines = [
+		`import { defineConfig } from "@theholocron/cli";`,
+		`import { compose, node, typecheck } from "@theholocron/holocron-config";`,
+		``,
+		`const preset = compose(node(), typecheck());`,
+		`export default defineConfig({`,
+		`\t...preset,`
+	];
+	if (opts.description) lines.push(`\tdescription: ${JSON.stringify(opts.description)},`);
+	if (opts.homepage) lines.push(`\thomepage: ${JSON.stringify(opts.homepage)},`);
+	const topics = opts.topics?.length ? opts.topics : [];
+	const hasRuntimeOverride = opts.runtimeEnvironment != null && opts.runtimeEnvironment !== "node";
+	if (opts.org != null) {
+		const repoName = `${opts.org}/${opts.name}`;
+		lines.push(`\trepo: {`);
+		lines.push(`\t\t...preset.repo,`);
+		lines.push(`\t\tname: ${JSON.stringify(repoName)},`);
+		lines.push(`\t\tteams: [{ slug: "gatekeepers", permission: "maintain" }],`);
+		lines.push(`\t\ttopics: ${JSON.stringify(topics)},`);
+		if (opts.protection && opts.protection !== "strict") lines.push(`\t\tprotection: ${JSON.stringify(opts.protection)},`);
+		const propParts = [];
+		if (hasRuntimeOverride) propParts.push(`runtime_environment: ${JSON.stringify(opts.runtimeEnvironment)}`);
+		if (opts.openSource === false) propParts.push(`open_source: false`);
+		if (opts.usesExternalPackages === false) propParts.push(`uses_external_packages: false`);
+		if (propParts.length > 0) lines.push(`\t\tproperties: { ...preset.repo?.properties, ${propParts.join(", ")} },`);
+		lines.push(`\t},`);
+	} else if (topics.length > 0 || hasRuntimeOverride) {
+		lines.push(`\trepo: {`);
+		lines.push(`\t\t...preset.repo,`);
+		if (topics.length > 0) lines.push(`\t\ttopics: ${JSON.stringify(topics)},`);
+		if (hasRuntimeOverride) lines.push(`\t\tproperties: { ...preset.repo?.properties, runtime_environment: ${JSON.stringify(opts.runtimeEnvironment)} },`);
+		lines.push(`\t},`);
 	}
-	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;
+	const hasVault = opts.vaultProvider && opts.vaultProvider !== "none";
+	const hasDeployment = opts.deploymentProvider && opts.deploymentProvider !== "none";
+	if (hasVault || hasDeployment) {
+		lines.push(`\tproviders: {`);
+		lines.push(`\t\t...preset.providers,`);
+		if (opts.vaultProvider === "doppler") {
+			const proj = JSON.stringify(opts.vaultProject ?? opts.name);
+			const cfg = JSON.stringify(opts.vaultConfig ?? "dev");
+			lines.push(`\t\tvault: ["doppler", { project: ${proj}, config: ${cfg} }],`);
+		} else if (opts.vaultProvider === "1password") {
+			const vault = JSON.stringify(opts.vaultProject ?? opts.name);
+			lines.push(`\t\tvault: ["1password", { vault: ${vault} }],`);
+		} else if (opts.vaultProvider === "infisical") {
+			const proj = JSON.stringify(opts.vaultProject ?? opts.name);
+			lines.push(`\t\tvault: ["infisical", { project: ${proj} }],`);
+		}
+		if (opts.deploymentProvider === "vercel") lines.push(`\t\tdeployment: "vercel",`);
+		lines.push(`\t},`);
 	}
+	if (opts.agent && opts.agent !== "none") lines.push(`\tagent: ${JSON.stringify(opts.agent)},`);
+	if (opts.skills?.length) lines.push(`\tskills: ${JSON.stringify(opts.skills)},`);
+	lines.push(`});`);
+	lines.push(``);
+	return lines.join("\n");
 }
-/** 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) {
+const SKIP_DIRS$1 = [
+	".git",
+	"node_modules",
+	"dist",
+	".turbo"
+];
+const defaultWalkFiles$1 = (dir) => walkFilesSync(dir, { skip: SKIP_DIRS$1 });
+function isBinary(content) {
+	for (let i = 0; i < Math.min(content.length, 8e3); i++) if (content.charCodeAt(i) === 0) return true;
+	return false;
+}
+function patchFiles(dir, variants, description, homepage, runtimeEnvironment, print, readFn, writeFn, walkFn) {
+	const patched = [];
+	for (const filepath of walkFn(dir)) {
+		let content;
 		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 });
+			content = readFn(filepath);
+		} catch {
+			continue;
+		}
+		if (isBinary(content)) continue;
+		const original = content;
+		for (const [search, replacement] of variants) content = content.split(search).join(replacement);
+		if (description !== void 0) {
+			content = content.split("<description>").join(description);
+			content = content.replace(/(<!-- holocron:description -->)[\s\S]*?(<!-- \/holocron:description -->)/g, `$1\n${description}\n$2`);
+		}
+		if (homepage !== void 0) content = content.split("<homepage>").join(homepage);
+		if (runtimeEnvironment !== void 0) content = content.split("<runtime_environment>").join(runtimeEnvironment);
+		content = content.replace(/\n?<!-- holocron:template-only -->[\s\S]*?<!-- \/holocron:template-only -->\n?/g, "");
+		if (content !== original) {
+			writeFn(filepath, content);
+			print(`  ✓ ${path.relative(dir, filepath)}`);
+			patched.push(filepath);
 		}
-		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;
+	return patched;
 }
-async function runNotificationsChannelAdd(input) {
+function preflight$1() {
+	const result = spawnSync("gh", ["--version"], { encoding: "utf8" });
+	if (result.error != null || result.status !== 0) throw new NewError("`gh` CLI is not installed or not on PATH. Install it from https://cli.github.com");
+}
+function defaultExec$3(cmd, args, opts) {
+	execFileSync(cmd, args, {
+		cwd: opts.cwd,
+		stdio: opts.stdio,
+		...opts.env && Object.keys(opts.env).length > 0 ? { env: {
+			...process.env,
+			...opts.env
+		} } : {}
+	});
+}
+function keychainLookup(key) {
+	const result = spawnSync("security", [
+		"find-generic-password",
+		"-s",
+		"com.theholocron.cli",
+		"-a",
+		key,
+		"-w"
+	], { encoding: "utf8" });
+	return result.status === 0 ? result.stdout?.trim() || void 0 : void 0;
+}
+function defaultReadFile(filepath) {
+	return readFileSync(filepath, "utf-8");
+}
+function defaultWriteFile(filepath, content) {
+	mkdirSync(path.dirname(filepath), { recursive: true });
+	writeFileSync(filepath, content, "utf-8");
+}
+async function runNew(input) {
+	const cwd = input.cwd ?? process.cwd();
+	const org = input.org ?? "theholocron";
 	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)" : ""}`);
+	const execFn = input.exec ?? defaultExec$3;
+	const readFn = input.readFile ?? defaultReadFile;
+	const writeFn = input.writeFile ?? defaultWriteFile;
+	const walkFn = input.walkFiles ?? defaultWalkFiles$1;
+	preflight$1();
+	const templateRepo = `${org}/${input.type}-template`;
+	const newRepo = `${org}/${input.name}`;
+	const repoDir = path.join(cwd, input.name);
+	logger.info({
+		repo: newRepo,
+		template: templateRepo,
+		dryRun: input.dryRun || void 0
+	}, "new: start");
+	if (input.dryRun) {
+		print(`  Would create ${newRepo} from template ${templateRepo}`);
+		print(`  Would clone to ${repoDir}`);
+		print(`  Would patch all casing variants of "${input.type}-template" → "${input.name}"`);
+		if (input.description) print(`  Would replace <description> → "${input.description}"`);
+		if (input.homepage) print(`  Would replace <homepage> → "${input.homepage}"`);
+		if (input.runtimeEnvironment) print(`  Would replace <runtime_environment> → "${input.runtimeEnvironment}"`);
+		print(`  Would generate holocron.config.ts`);
+		logger.info({
+			repo: newRepo,
+			status: "dry-run"
+		}, "new: done");
+		return { status: "dry-run" };
+	}
+	if (existsSync(repoDir)) throw new NewError(`\`${repoDir}\` already exists — delete it or pick a different name.`);
+	print(`  Creating ${newRepo} from template ${templateRepo}…`);
+	const visibility = input.openSource ? "--public" : "--private";
 	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 } : {}
-			} } : {}
+		execFn("gh", [
+			"repo",
+			"create",
+			newRepo,
+			`--template=${templateRepo}`,
+			visibility,
+			"--clone"
+		], {
+			cwd,
+			stdio: "inherit"
 		});
-		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}`);
+	} catch (err) {
+		throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
+	}
+	if (input.isTemplate) try {
+		execFn("gh", [
+			"repo",
+			"edit",
+			newRepo,
+			"--template=true"
+		], {
+			cwd,
+			stdio: "inherit"
+		});
+	} catch {}
+	try {
+		execFn("gh", [
+			"repo",
+			"edit",
+			newRepo,
+			`--visibility=${input.openSource ? "public" : "private"}`
+		], {
+			cwd,
+			stdio: "inherit"
+		});
+	} catch {}
+	let templateSlug = `${input.type}-template`;
+	const pkgJsonPath = path.join(repoDir, "package.json");
+	if (existsSync(pkgJsonPath)) try {
+		const pkg = JSON.parse(readFn(pkgJsonPath));
+		if (typeof pkg.name === "string") templateSlug = pkg.name.split("/").at(-1) || templateSlug;
+	} catch {}
+	print(`  Detected template slug: ${templateSlug}`);
+	print(`  Patching files…`);
+	const variants = deriveVariants(templateSlug, input.name);
+	variants.unshift([`theholocron/${templateSlug}`, `${org}/${input.name}`]);
+	const filesPatched = patchFiles(repoDir, variants, input.description, input.homepage, input.runtimeEnvironment, print, readFn, writeFn, walkFn);
+	print(`  ${filesPatched.length} file${filesPatched.length === 1 ? "" : "s"} patched`);
+	if (input.description !== void 0 || input.homepage !== void 0) try {
+		const raw = readFn(pkgJsonPath);
+		const pkg = JSON.parse(raw);
+		if (input.description !== void 0) pkg["description"] = input.description;
+		if (input.homepage !== void 0) pkg["homepage"] = input.homepage;
+		writeFn(pkgJsonPath, stringifyJson(pkg, { like: raw }));
+		print(`  ✓ package.json (description/homepage)`);
+	} catch {}
+	const displayName = input.name.split("-").map(cap).join(" ");
+	const rootTsconfigPath = path.join(repoDir, "tsconfig.json");
+	try {
+		const rawTsconfig = readFn(rootTsconfigPath);
+		const tsconfig = JSON.parse(rawTsconfig);
+		if (typeof tsconfig["display"] === "string") {
+			tsconfig["display"] = displayName;
+			writeFn(rootTsconfigPath, stringifyJson(tsconfig, { like: rawTsconfig }));
+			print(`  ✓ tsconfig.json (display)`);
+		}
+	} catch {}
+	const configContent = generateHolocronConfig({
+		name: input.name,
+		type: input.type,
+		org,
+		description: input.description,
+		homepage: input.homepage,
+		vaultProvider: input.vaultProvider,
+		vaultProject: input.vaultProject,
+		vaultConfig: input.vaultConfig,
+		deploymentProvider: input.deploymentProvider,
+		agent: input.agent,
+		runtimeEnvironment: input.runtimeEnvironment,
+		protection: input.protection,
+		openSource: input.openSource,
+		usesExternalPackages: input.usesExternalPackages,
+		topics: input.topics,
+		skills: input.skills
+	});
+	writeFn(path.join(repoDir, "holocron.config.ts"), configContent);
+	print(`  Generated holocron.config.ts`);
+	execFn("git", ["add", "-A"], {
+		cwd: repoDir,
+		stdio: "inherit"
+	});
+	execFn("git", [
+		"commit",
+		"-s",
+		"-m",
+		`chore: bootstrap from ${templateSlug}`
+	], {
+		cwd: repoDir,
+		stdio: "inherit"
+	});
+	if (!input.noVerify) {
+		print("");
+		print("  Installing dependencies…");
+		try {
+			execFn("pnpm", ["install"], {
+				cwd: repoDir,
+				stdio: "inherit"
+			});
+		} catch (err) {
+			print(`  ✗ pnpm install failed — ${errorMessage(err)}`);
 			return {
 				status: "fail",
-				channel,
-				message
+				repoDir,
+				filesPatched,
+				message: "pnpm install failed; inspect output above"
 			};
 		}
-		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("  Running holocron repo setup…");
+		try {
+			const setupArgs = ["setup"];
+			const setupEnv = {};
+			const adminToken = input.token ?? keychainLookup("github.admin");
+			if (adminToken) setupArgs.push("--token", adminToken);
+			if (!env.get("HOLOCRON_ORG_TOKEN")) {
+				const orgToken = keychainLookup("github.org");
+				if (orgToken) setupEnv["HOLOCRON_ORG_TOKEN"] = orgToken;
+			}
+			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-setup/notifications-setup.ts
@@ -3492,408 +3822,218 @@ async function runNotificationsChannelAdd(input) {
 * 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
-			});
-		}
+/** A channel's access: its category's, with any field the channel states itself laid over it. */
+function effectiveAccess(category, channel) {
+	if (!category && !channel) return void 0;
+	return {
+		...category,
+		...channel
 	};
-	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;
+/** The first role an `access` names that the layout does not declare, or undefined. */
+function accessRoleProblem(layout) {
+	const declared = new Set((layout.roles ?? []).map((r) => r.name.toLowerCase()));
+	const check = (where, access) => {
+		for (const field of ["view", "post"]) {
+			const value = access?.[field];
+			if (!Array.isArray(value)) continue;
+			const unknown = value.find((name) => !declared.has(name.toLowerCase()));
+			if (unknown !== void 0) return `${where}: \`access.${field}\` names the role \`${unknown}\`, which is not in the layout's roles`;
+		}
+	};
+	const cannotSee = (where, access) => {
+		if (!Array.isArray(access?.view) || !Array.isArray(access?.post)) return void 0;
+		const seen = new Set(access.view.map((r) => r.toLowerCase()));
+		const stuck = access.post.find((r) => !seen.has(r.toLowerCase()));
+		return stuck === void 0 ? void 0 : `${where}: the role \`${stuck}\` may post but is not in \`view\`, so it could not see the channel`;
+	};
+	for (const category of layout.categories ?? []) {
+		const problem = check(`category \`${category.name}\``, category.access);
+		if (problem) return problem;
+		const stuckCategory = cannotSee(`category \`${category.name}\``, category.access);
+		if (stuckCategory) return stuckCategory;
+		for (const channel of category.channels ?? []) {
+			const found = check(`channel \`${channel.name}\``, channel.access);
+			if (found) return found;
+			const stuck = cannotSee(`channel \`${channel.name}\``, effectiveAccess(category.access, channel.access));
+			if (stuck) return stuck;
+		}
+	}
+}
+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 accessProblem = accessRoleProblem(layout);
+	if (accessProblem) return refuse(accessProblem);
+	const needsCategories = (layout.categories ?? []).find((c) => c.access);
+	if (needsCategories && !notifications.ensureCategory) return refuse(`category \`${needsCategories.name}\` declares \`access\`, but the \`${notifications.providerName}\` provider cannot manage categories`);
+	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)}"`);
+	const made = (created) => void (created ? tally.ok++ : tally.skip++);
+	const attempt = async (step, fn) => {
+		try {
+			await fn();
+			return true;
+		} catch (err) {
+			const message = describeProviderError(err);
+			print(`  ${style.fail(`${step}: ${message}`)}`);
+			report.failures.push({
+				step,
+				message
+			});
+			return false;
 		}
-		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)}`);
+	};
+	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;
 		}
-		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}`);
+		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++;
 		}
-		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`);
-		} catch (err) {
-			failed("secrets", "secrets", describeProviderError(err));
+	for (const category of layout.categories ?? []) {
+		print(`\n${style.header(category.name)}`);
+		report.categories.push(category.name);
+		const categoryOk = 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, { ...category.access ? { access: category.access } : {} });
+			const changed = result.created || (result.updated?.length ?? 0) > 0;
+			const verb = result.created ? "created" : changed ? "updated" : "exists ";
+			const what = result.updated?.length ? `: ${result.updated.join(", ")}` : "";
+			print(`  ${(changed ? style.success : style.skip)(`${verb} category ${category.name}${what}`)}`);
+			made(changed);
+		});
+		const channels = category.channels ?? [];
+		if (!categoryOk && channels.length > 0) {
+			print(`  ${style.skip(`skipped ${channels.length} channel${channels.length === 1 ? "" : "s"}: the category failed`)}`);
+			tally.skip += channels.length;
+			continue;
 		}
+		for (const channel of 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 } : {},
+				...effectiveAccess(category.access, channel.access) ? { access: effectiveAccess(category.access, channel.access) } : {},
+				...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
-	});
-	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 +10173,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 +11005,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 +11762,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", {