@theholocron/cli 5.0.0-alpha.13 → 5.0.0-alpha.134

package/dist/cli.mjs

@@ -1,29 +1,32 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import path, { basename, dirname, join, relative, resolve } from "node:path";
-import { checkbox, input, select } from "@inquirer/prompts";
-import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
+import { homedir, hostname, tmpdir, userInfo } from "node:os";
+import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { checkbox, confirm, input, select } from "@inquirer/prompts";
+import { KNOWN_WORKFLOWS, createAstromech, deployOnRelease, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
+import { LOG_LEVELS, NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1, createRestClient } from "@theholocron/http-client";
 import { createEnvLookup } from "@theholocron/env-utils";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { pathToFileURL } from "node:url";
-import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
-import ora from "ora";
+import { errorMessage } from "@theholocron/misc-utils";
+import { createLogger, isCI, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
 import chalk from "chalk";
+import ora from "ora";
 import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
-import { homedir, hostname, userInfo } from "node:os";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash } 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";
 import { PostHogSink } from "@theholocron/observability/analytics";
-import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import { SentrySink } from "@theholocron/observability/errors";
+import load from "@commitlint/load";
+import lint from "@commitlint/lint";
 import { promisify } from "node:util";
 import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
 import search from "@inquirer/search";
@@ -181,6 +184,7 @@ const CARDINALITY = {
 	analytics: "many",
 	errors: "single",
 	logs: "single",
+	monitoring: "single",
 	wiki: "single",
 	workers: "single"
 };
@@ -295,46 +299,157 @@ function resolveConfig(raw) {
 		docs,
 		env: raw.env,
 		log: raw.log,
-		telemetry: raw.telemetry
+		telemetry: raw.telemetry,
+		eslint: raw.eslint
 	};
 }
 //#endregion
+//#region src/commands/contexts.ts
+/**
+* Command → context. Keys are the full command path as it lands in
+* yargs' `argv._` (`"auth set"`, `"repo upgrade node"`), the bare verb
+* otherwise; a longer, more specific key wins over its parent.
+*
+* - **`global`** — needs nothing but the CLI binary. Works anywhere.
+* - **`repo-aware`** — reads `./holocron.config` + `./package.json`
+*   relative to cwd, but never touches the plugin loader.
+* - **`workspace`** — needs the configured providers' plugin packages to
+*   resolve (devDeps in a repo, or `pnpm exec`).
+*/
+const COMMAND_CONTEXTS = {
+	clone: "global",
+	"new repo": "global",
+	"new plugin": "global",
+	"repo upgrade node": "global",
+	"repo upgrade deps": "global",
+	"auth set": "global",
+	"auth unset": "global",
+	"auth list": "global",
+	"auth check": "global",
+	"package bump-versions": "global",
+	"package publish": "global",
+	"skills install": "global",
+	"skills remove": "global",
+	"skills update": "global",
+	"run lint commit-msg": "global",
+	run: "repo-aware",
+	"run ci": "repo-aware",
+	"deploy on-release": "repo-aware",
+	"config show": "repo-aware",
+	"repo sync readme": "repo-aware",
+	doctor: "workspace",
+	"repo setup": "workspace",
+	"secrets set": "workspace",
+	"secrets sync": "workspace",
+	deploy: "workspace",
+	"deploy cleanup-preview": "workspace",
+	"repo sync": "workspace",
+	"sync github": "workspace"
+};
+/**
+* The context for a command name from `argv._`. Falls back to the leading
+* verb (`"auth foo"` → `"auth"`) and finally `undefined` for a name the
+* map doesn't know — callers treat unknown as "don't guard".
+*/
+function contextForCommand(name) {
+	const map = COMMAND_CONTEXTS;
+	const tokens = name.split(" ").filter(Boolean);
+	for (let n = tokens.length; n > 0; n--) {
+		const ctx = map[tokens.slice(0, n).join(" ")];
+		if (ctx) return ctx;
+	}
+}
+/** Command names in a given context, in registration order. */
+function commandsInContext(context) {
+	return Object.entries(COMMAND_CONTEXTS).filter(([, c]) => c === context).map(([name]) => name);
+}
+//#endregion
+//#region src/ui/style.ts
+const style = {
+	success: (msg) => `${chalk.green("✓")} ${msg}`,
+	warn: (msg) => `${chalk.yellow("⚠")} ${msg}`,
+	fail: (msg) => `${chalk.red("✗")} ${msg}`,
+	step: (msg) => `${chalk.cyan("→")} ${msg}`,
+	/** A dim `·` marker for a row that's neither a pass nor a failure — loaded but inactive, or skipped. */
+	skip: (msg) => chalk.dim(`· ${msg}`),
+	hint: (msg) => chalk.dim(msg),
+	dim: (msg) => chalk.dim(msg),
+	header: (msg) => chalk.bold(msg)
+};
+//#endregion
 //#region src/logger.ts
 /**
+* Dataset for `global`-context commands (`clone`, `auth set`, `upgrade
+* node`, …) — ADR-0012. These commands aren't "about" any repo, so their
+* logs must never depend on `$PWD` or which repo's `.envrc` happens to be
+* active; they always ship to holocron's own dataset instead of whatever
+* `HOLOCRON_AXIOM_DATASET` resolves to locally. Mirrors
+* `telemetry/resolve.ts`'s `FALLBACK_DSN` — a holocron-owned default, not a
+* per-repo override.
+*/
+const GLOBAL_AXIOM_DATASET = "holocron-global";
+/**
 * Resolve the explicit level to hand to `createLogger`, in priority order:
 *
-* 1. `--verbose` → `"debug"`   2. `--quiet` → `"error"`
-* 3. `HOLOCRON_LOG_LEVEL` env var
-* 4. `holocron.config` `log.level` (`configLevel`)
+* 1. `--log <level>`           2. `--verbose` → `"debug"`   3. `--quiet` → `"error"`
+* 4. `HOLOCRON_LOG_LEVEL` env var
+* 5. `holocron.config` `log.level` (`configLevel`)
 *
 * Returns `undefined` when nothing applies — `createLogger` then defaults
 * to `"info"`. Resolving the full chain here (rather than passing
 * `configLevel` straight through) keeps config below the env var.
 */
 function resolveLogLevel(argv, configLevel) {
+	if (argv.log) return argv.log;
 	if (argv.verbose) return "debug";
 	if (argv.quiet) return "error";
 	return parseLogLevel(env.get("HOLOCRON_LOG_LEVEL")) ?? configLevel;
 }
+/**
+* Resolve whether human-visible console output (pretty or NDJSON) should run
+* at all, independent of level — the `@theholocron/observability`
+* `consoleOutput` override.
+*
+* Local/interactive runs are quiet by default: any raw structured logger
+* output (colorized or not) stays off regardless of the resolved level,
+* unless the user explicitly asked to see it via `--log <level>`,
+* `--verbose`, or `--quiet`. CI is untouched either way — returning
+* `undefined` there preserves `createLogger`'s own `ci`/`tty`
+* auto-detection exactly, so CI's existing NDJSON-to-stdout behavior is
+* unaffected by this flag.
+*/
+function resolveConsoleOutput(argv) {
+	if (argv.log || argv.verbose || argv.quiet) return true;
+	return isCI() ? void 0 : false;
+}
 let root;
 let rootLevel;
 let rootCommand;
 let rootAxiomKey;
 /**
-* Resolve Axiom credentials for the CLI. Env vars win — same contract as
-* `@theholocron/observability`'s `resolveAxiomFromEnv`. Failing that, the CLI-only
-* bridge pairs the OS-keyring token (`axiom.<org>` then bare `axiom`) with a
-* dataset from `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or
-* `holocron.config` `log.axiom.dataset`. Returns `undefined` unless both a
-* token and a dataset are found.
+* Resolve Axiom credentials for the CLI.
+*
+* A `global`-context command (ADR-0012) always resolves to
+* {@link GLOBAL_AXIOM_DATASET}, ignoring `HOLOCRON_AXIOM_DATASET` /
+* `AXIOM_DATASET` / `holocron.config` `log.axiom.dataset` entirely — it
+* isn't "about" any repo, so the active directory's dataset is never the
+* right answer. Everything else keeps the existing chain: env vars win
+* (same contract as `@theholocron/observability`'s `resolveAxiomFromEnv`),
+* falling back to the CLI-only bridge that pairs the OS-keyring token
+* (`axiom.<org>` then bare `axiom`) with a dataset from
+* `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or `log.axiom.dataset`.
+* Returns `undefined` unless both a token and a dataset are found.
 */
 function resolveCliAxiom(opts) {
-	const fromEnv = resolveAxiomFromEnv();
-	if (fromEnv) return fromEnv;
-	const dataset = env.get("HOLOCRON_AXIOM_DATASET") || env.get("AXIOM_DATASET") || opts.configAxiomDataset;
+	const isGlobal = contextForCommand(opts.command ?? rootCommand ?? "") === "global";
+	if (!isGlobal) {
+		const fromEnv = resolveAxiomFromEnv();
+		if (fromEnv) return fromEnv;
+	}
+	const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : env.get("HOLOCRON_AXIOM_DATASET") || env.get("AXIOM_DATASET") || opts.configAxiomDataset;
 	if (!dataset) return void 0;
 	const org = opts.org ?? env.get("HOLOCRON_ORG");
-	const token = (org ? getToken(`axiom.${org}`) : null) ?? getToken("axiom");
+	const token = env.get("HOLOCRON_AXIOM_TOKEN") || env.get("AXIOM_TOKEN") || (org ? getToken(`axiom.${org}`) : null) || getToken("axiom");
 	return token ? {
 		dataset,
 		token
@@ -354,13 +469,15 @@ function buildCliLogger(argv, opts = {}) {
 	const { command, configLevel } = opts;
 	if (command) rootCommand = command;
 	const level = resolveLogLevel(argv, configLevel);
+	const consoleOutput = resolveConsoleOutput(argv);
 	const axiom = resolveCliAxiom(opts);
 	const axiomKey = axiom?.dataset;
-	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet;
+	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet && !argv.log;
 	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
 		const built = createLogger({
 			...level ? { level } : {},
-			...axiom ? { axiom } : {}
+			...axiom ? { axiom } : {},
+			...consoleOutput !== void 0 ? { consoleOutput } : {}
 		});
 		root = {
 			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
@@ -371,9 +488,35 @@ function buildCliLogger(argv, opts = {}) {
 	}
 	return root;
 }
-/** Lazily-memoized `Logger` for module-level call sites with no `argv` in scope. */
+/**
+* Lazily-memoized `Logger` for module-level call sites with no `argv` in
+* scope — notably yargs' own `.fail()` handler, which fires on a
+* pre-middleware validation failure (a missing required argument, an
+* unknown command) and therefore runs before `buildCliLogger` has ever
+* built the real root. Without an explicit `consoleOutput` here, that
+* fallback would use `createLogger`'s bare auto-detection (pretty on any
+* local TTY) and leak a structured block even though no flag asked for one
+* — so it resolves the same "quiet unless CI" default `buildCliLogger`
+* would, as if no flags were passed.
+*/
 function getLogger() {
-	return (root ??= createLogger()).logger;
+	return (root ??= createLogger({ consoleOutput: resolveConsoleOutput({}) })).logger;
+}
+/**
+* Report a fatal, command-ending CLI error: always printed to the console
+* (regardless of `consoleOutput` suppression) via `style.fail`, and also
+* sent through the structured logger for Axiom/telemetry visibility.
+*
+* Use this when a handler is returning or exiting right here with nothing
+* else for the user to see — a resolved `--token` failure, a yargs
+* validation failure, a thrown domain error. Don't use it for a per-step
+* warning inside a multi-step orchestrator that already prints its own
+* `ok / fail / skip` summary — that summary is the user-facing signal;
+* the per-step reason belongs in the structured log alone.
+*/
+function reportError(message, log = getLogger()) {
+	console.error(style.fail(message));
+	log.error(message);
 }
 /** The current root logger's correlation id, if a root has been built. */
 function getRunId() {
@@ -491,7 +634,7 @@ var PluginLoader = class {
 	/** Internal — invoke a plugin's capability factory and return the impl. */
 	async loadOne(key, tuple) {
 		const mod = await this.importer(tuple.packageName).catch((err) => {
-			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
+			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${errorMessage(err)}`);
 		});
 		if (isPluginModule(mod)) {
 			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
@@ -532,7 +675,8 @@ var PluginLoader = class {
 /** Default importer — resolves from cwd first so the global CLI finds project plugins. */
 const defaultImporter$1 = async (pkg) => {
 	try {
-		return import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
+		const resolved = createRequire(process.cwd() + "/").resolve(pkg);
+		return import(pathToFileURL(resolved).href);
 	} catch {
 		return import(pkg);
 	}
@@ -632,17 +776,6 @@ async function withSpinner(label, fn) {
 	}
 }
 //#endregion
-//#region src/ui/style.ts
-const style = {
-	success: (msg) => `${chalk.green("✓")} ${msg}`,
-	warn: (msg) => `${chalk.yellow("⚠")} ${msg}`,
-	fail: (msg) => `${chalk.red("✗")} ${msg}`,
-	step: (msg) => `${chalk.cyan("→")} ${msg}`,
-	hint: (msg) => chalk.dim(msg),
-	dim: (msg) => chalk.dim(msg),
-	header: (msg) => chalk.bold(msg)
-};
-//#endregion
 //#region src/commands/auth.ts
 /**
 * `holocron auth <subcommand>` — manage bootstrap credentials in the
@@ -664,7 +797,8 @@ const style = {
 */
 const defaultImporter = async (pkg) => {
 	try {
-		return await import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
+		const resolved = createRequire(process.cwd() + "/").resolve(pkg);
+		return await import(pathToFileURL(resolved).href);
 	} catch {
 		return await import(pkg);
 	}
@@ -733,7 +867,7 @@ async function runAuthSet(input) {
 			subject = verified.subject;
 		} else print(style.warn(`${provider} plugin has no verifyToken; storing without verification`));
 	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
+		const msg = errorMessage(err);
 		print(style.warn(`cannot verify token — failed to load ${packageName}: ${msg}`));
 		print(style.hint(`  storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`));
 	}
@@ -850,7 +984,7 @@ async function runAuthCheck(input) {
 			message: verified.message
 		};
 	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
+		const msg = errorMessage(err);
 		if (isModuleNotFound(err)) {
 			print(style.warn(`${keyringKey}: token present — verification skipped (plugin not available here)`));
 			logger.info({
@@ -937,7 +1071,7 @@ async function runCleanupPreview(input) {
 	// c8 ignore next -- real PluginLoader construction is integration-level; unit tests always supply loader
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
-	assertPluginsResolvable(loader, "cleanup-preview");
+	assertPluginsResolvable(loader, "deploy cleanup-preview");
 	logger.info({
 		pr: input.prNumber,
 		project: input.project
@@ -949,7 +1083,7 @@ async function runCleanupPreview(input) {
 	try {
 		pr = await source.getPullRequest(input.prNumber, input.repo);
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		throw new Error(`Failed to fetch PR #${input.prNumber}: ${message}`, { cause: err });
 	}
 	const branch = `${(input.repo ?? input.loaded.resolved.repo?.name ?? "").split("/").pop()}-pr-${pr.number}`;
@@ -966,7 +1100,7 @@ async function runCleanupPreview(input) {
 	try {
 		deployments = await deploy.listPreviewDeployments(input.project, branch);
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		throw new Error(`Failed to list deployments: ${message}`, { cause: err });
 	}
 	if (deployments.length === 0) {
@@ -1045,7 +1179,7 @@ async function runCleanupPreview(input) {
 			status: "ok"
 		};
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		print(style.fail(message));
 		logger.warn({
 			pr: pr.number,
@@ -1065,13 +1199,56 @@ async function runCleanupPreview(input) {
 	}
 }
 //#endregion
+//#region src/ui/status-row.ts
+/** Right-pads `s` to `width` with spaces — never truncates. */
+function pad(s, width) {
+	return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+/**
+* One row of a status report: a 2-space indent, the status icon (✓ / ✗ / ·),
+* then `columns` joined with a two-space gap (blank columns dropped, so a
+* row that has nothing for its last column doesn't trail whitespace).
+* Column padding (`pad`) is the caller's job — `doctor` pads capability and
+* provider to a fixed width; `clone`'s repo names and paths don't, since
+* they vary too widely for fixed-width alignment to read cleanly.
+*
+* Shared by `doctor` (capability / provider / message) and `clone` (repo /
+* destination / reason) so every status table in the CLI reads the same way.
+*/
+function statusRow(status, columns) {
+	const joined = columns.filter((c) => c.length > 0).join("  ");
+	return `  ${status === "ok" ? style.success(joined) : status === "fail" ? style.fail(joined) : style.skip(joined)}`;
+}
+//#endregion
 //#region src/commands/clone.ts
+/**
+* Accepts a bare org (`"theholocron"`) — clones every repo in it — or an
+* `org/repo` coordinate (`"theholocron/new-repo"`) — clones just that one
+* repo. The repo half is never silently discarded: if it's there, it's used.
+* A trailing slash with nothing after it (`"theholocron/"`) is treated the
+* same as a bare org.
+*/
+function parseCloneTarget(raw) {
+	const trimmed = raw.trim();
+	const slash = trimmed.indexOf("/");
+	if (slash === -1) return { org: trimmed };
+	const org = trimmed.slice(0, slash);
+	const repo = trimmed.slice(slash + 1);
+	return repo ? {
+		org,
+		repo
+	} : { org };
+}
 function encodeTokenForGitHttpAuth(token) {
 	const trimmed = token.trim();
 	if (!trimmed) throw new Error("empty token");
 	if (/[\u0000-\u001F\u007F\s]/.test(trimmed)) throw new Error("token contains whitespace or control characters");
 	return encodeURIComponent(trimmed);
 }
+/** Strip a leading dot so a hidden repo (e.g. `.github`) is still visible in Finder once cloned. */
+function repoDirName(repo) {
+	return repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
+}
 async function listOrgRepos(org, token, fetchFn) {
 	const repos = [];
 	let url = `https://api.github.com/orgs/${org}/repos?per_page=100&type=all`;
@@ -1088,6 +1265,16 @@ async function listOrgRepos(org, token, fetchFn) {
 	}
 	return repos;
 }
+async function getRepo(org, repo, token, fetchFn) {
+	const res = await fetchFn(`https://api.github.com/repos/${org}/${repo}`, { headers: {
+		Authorization: `Bearer ${token}`,
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	} });
+	if (res.status === 404) throw new Error(`${org}/${repo} not found — check the repo name and that the token can see it`);
+	if (!res.ok) throw new Error(`GitHub API ${res.status}: ${res.statusText} — check that the token has repo:read scope`);
+	return await res.json();
+}
 async function runClone(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1096,6 +1283,7 @@ async function runClone(input) {
 	const targetDir = resolve(input.dir ?? join(homedir(), "Code", input.org));
 	logger.info({
 		org: input.org,
+		repo: input.repo,
 		targetDir,
 		dryRun: dryRun || void 0
 	}, "clone: start");
@@ -1105,18 +1293,21 @@ async function runClone(input) {
 			stdio: "inherit"
 		}).status };
 	});
-	print(style.header(`Holocron clone — org=${input.org} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
-	if (!existsSync(targetDir)) if (dryRun) print(style.dim(`  would create ${targetDir}`));
-	else mkdirSync(targetDir, { recursive: true });
+	print("");
+	if (!existsSync(targetDir)) {
+		if (dryRun) print(style.dim(`  would create ${targetDir}`));
+		else mkdirSync(targetDir, { recursive: true });
+	}
 	let repos;
 	try {
-		repos = await listOrgRepos(input.org, input.token, fetchFn);
+		repos = input.repo ? [await getRepo(input.org, input.repo, input.token, fetchFn)] : await listOrgRepos(input.org, input.token, fetchFn);
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		logger.warn({
 			org: input.org,
+			repo: input.repo,
 			reason: message
-		}, "clone: failed to list org repos");
+		}, "clone: failed to list repos");
 		return {
 			status: "fail",
 			cloned: 0,
@@ -1125,13 +1316,39 @@ async function runClone(input) {
 			message
 		};
 	}
+	if (!input.repo && !dryRun && input.confirmWholeOrg) {
+		const alreadyCloned = repos.filter((r) => existsSync(join(targetDir, repoDirName(r)))).length;
+		const scope = {
+			total: repos.length,
+			alreadyCloned,
+			toClone: repos.length - alreadyCloned
+		};
+		if (!await input.confirmWholeOrg(scope)) {
+			print(style.dim("  aborted — nothing cloned"));
+			logger.info({
+				org: input.org,
+				...scope
+			}, "clone: aborted by user");
+			return {
+				status: "aborted",
+				cloned: 0,
+				skipped: 0,
+				failed: 0,
+				message: "aborted by user"
+			};
+		}
+	}
 	let cloned = 0;
 	let skipped = 0;
 	let failed = 0;
 	for (const repo of repos) {
-		const dest = join(targetDir, repo.name.startsWith(".") ? repo.name.slice(1) : repo.name);
+		const dest = join(targetDir, repoDirName(repo));
 		if (existsSync(dest)) {
-			print(style.dim(`  skip   ${repo.full_name}`));
+			print(statusRow("skip", [
+				repo.full_name,
+				dest,
+				"already exists"
+			]));
 			skipped++;
 			continue;
 		}
@@ -1140,10 +1357,14 @@ async function runClone(input) {
 			cloned++;
 			continue;
 		}
-		print(style.step(`  clone  ${repo.full_name}`));
+		print(style.step(`  clone  ${repo.full_name} → ${dest}`));
 		const { clone_url } = repo;
 		if (!clone_url.startsWith("https://github.com/")) {
-			print(style.fail(`  failed ${repo.full_name} — unexpected clone URL: ${clone_url}`));
+			print(statusRow("fail", [
+				repo.full_name,
+				dest,
+				`unexpected clone URL: ${clone_url}`
+			]));
 			failed++;
 			continue;
 		}
@@ -1151,7 +1372,11 @@ async function runClone(input) {
 		try {
 			encodedToken = encodeTokenForGitHttpAuth(input.token);
 		} catch (err) {
-			print(style.fail(`  failed ${repo.full_name} — invalid token format: ${err instanceof Error ? err.message : String(err)}`));
+			print(statusRow("fail", [
+				repo.full_name,
+				dest,
+				`invalid token format: ${errorMessage(err)}`
+			]));
 			failed++;
 			continue;
 		}
@@ -1161,23 +1386,29 @@ async function runClone(input) {
 			`https://x-access-token:${encodedToken}@github.com/${clone_url.slice(19)}`,
 			dest
 		], { cwd: targetDir }).status !== 0) {
-			print(style.fail(`  failed ${repo.full_name}`));
+			print(statusRow("fail", [repo.full_name, dest]));
 			failed++;
 		} else {
-			print(style.success(`  cloned ${repo.name}`));
+			print(statusRow("ok", [repo.full_name, dest]));
 			cloned++;
 		}
 	}
-	const summary = `${cloned} cloned, ${skipped} skipped, ${failed} failed`;
-	print(dryRun ? style.dim(`\n  dry-run: ${summary}`) : failed > 0 ? style.fail(`\n  ${summary}`) : style.success(`\n  ${summary}`));
+	const summary = `${cloned} cloned, ${failed} failed, ${skipped} skipped`;
+	print("");
+	print(dryRun ? style.dim(`  dry-run: ${summary}`) : failed > 0 ? style.fail(`  ${summary}`) : style.success(`  ${summary}`));
 	const status = dryRun ? "dry-run" : failed > 0 ? "fail" : "ok";
 	logger[failed > 0 ? "warn" : "info"]({
 		org: input.org,
+		repo: input.repo,
 		status,
 		cloned,
 		skipped,
 		failed
 	}, "clone: done");
+	if (input.confirmOpen) {
+		const openTarget = input.repo ? join(targetDir, repoDirName(repos[0])) : targetDir;
+		if (existsSync(openTarget)) await input.confirmOpen(openTarget, dryRun && cloned > 0);
+	}
 	return {
 		status,
 		cloned,
@@ -1186,53 +1417,81 @@ async function runClone(input) {
 	};
 }
 //#endregion
-//#region src/commands/contexts.ts
+//#region src/commands/deploy.ts
 /**
-* Command → context. Keys are the command name as it lands in yargs'
-* `argv._` — the full path for sub-commands (`"auth set"`, `"upgrade
-* node"`), the bare verb otherwise.
+* `holocron deploy` — trigger a deployment via the configured
+* `deployment` capability.
 *
-* - **`global`** — needs nothing but the CLI binary. Works anywhere.
-* - **`repo-aware`** — reads `./holocron.config` + `./package.json`
-*   relative to cwd, but never touches the plugin loader.
-* - **`workspace`** — needs the configured providers' plugin packages to
-*   resolve (devDeps in a repo, or `pnpm exec`).
+* Two modes, one command: `runDeploy` (the default — a Git branch,
+* `triggerDeployment()`) and `runDeployFromFiles` (`--files <dir>` —
+* a local directory of source files, `deployFunction()`, no linked
+* repo required — for a consumer with no Git history to deploy from,
+* e.g. Sentinel, shipped as an npm package). Separate functions, not
+* one branching `runDeploy`, because their inputs genuinely differ
+* (`branch` vs `dir`) and their result shapes differ too
+* (`DeploymentRecord` carries `status`/`branch`; `DeployFunctionResult`
+* is deliberately minimal, same as `DeployScriptResult` for Workers).
+*
+* Errors clearly when `deployment` isn't loaded (no provider declared
+* in `holocron.config.json`), or when the configured provider doesn't
+* implement `deployFunction` (it's optional on `Deployment` — not
+* every provider has a files-based deploy API).
+*
+* Dry-run skips the actual deploy call but still verifies the
+* deployment capability (and, for `--files`, `deployFunction`) is
+* present, so operators can sanity-check the wiring without spinning
+* up a build.
+*
+* **Both modes wait for the deployment to finish** (holocron#911): a
+* provider accepting the upload/trigger is not the deployment succeeding.
+* Vercel builds asynchronously — an `npm install` failure there leaves
+* the deployment in `ERROR` while production keeps serving the previous
+* one, and this command used to report `ok` regardless (found live:
+* Sentinel's holocron#910 deploy "succeeded" in CI, never went live). So
+* after triggering, {@link waitForDeployment} polls
+* `Deployment.getDeployment()` until a terminal state; only `ready` is
+* `ok`, while `error` / `cancelled` / a timeout are `fail` (non-zero exit
+* via `cli.ts`).
 */
-const COMMAND_CONTEXTS = {
-	version: "global",
-	clone: "global",
-	new: "global",
-	"upgrade node": "global",
-	"upgrade deps": "global",
-	"plugin create": "global",
-	"auth set": "global",
-	"auth unset": "global",
-	"auth list": "global",
-	"auth check": "global",
-	"bump-versions": "global",
-	publish: "global",
-	"skills install": "global",
-	"skills remove": "global",
-	"skills update": "global",
-	run: "repo-aware",
-	ci: "repo-aware",
-	"config show": "repo-aware",
-	"sync-readme": "repo-aware",
-	doctor: "workspace",
-	setup: "workspace",
-	"secret set": "workspace",
-	"secrets sync": "workspace",
-	deploy: "workspace",
-	"cleanup-preview": "workspace",
-	sync: "workspace",
-	"sync-github": "workspace"
-};
-/** Command names in a given context, in registration order. */
-function commandsInContext(context) {
-	return Object.entries(COMMAND_CONTEXTS).filter(([, c]) => c === context).map(([name]) => name);
+const DEFAULT_WAIT_TIMEOUT_MS = 6e5;
+const DEFAULT_WAIT_INTERVAL_MS = 5e3;
+const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+	"ready",
+	"error",
+	"cancelled"
+]);
+/**
+* Polls `getDeployment(id)` until the deployment reaches a terminal status
+* (`ready` / `error` / `cancelled`). Throws on timeout — the caller turns
+* that into a `fail` report, same as a provider throwing mid-trigger.
+*/
+async function waitForDeployment(deploy, deploymentId, options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+	const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const now = options.now ?? Date.now;
+	const deadline = now() + timeoutMs;
+	for (;;) {
+		const record = await deploy.getDeployment(deploymentId);
+		if (TERMINAL_STATUSES.has(record.status)) return record;
+		if (now() >= deadline) throw new Error(`deployment ${deploymentId} still ${record.status} after ${Math.round(timeoutMs / 1e3)}s — check the provider's dashboard`);
+		await sleep(intervalMs);
+	}
+}
+/** One terminal, non-ready record as a single human-readable failure line. */
+function terminalFailure(record) {
+	return `deployment ${record.id} ended ${record.status}${record.errorMessage ? `: ${record.errorMessage}` : ""}`;
+}
+/**
+* Provider `url` fields (Vercel's REST API, at least) come back as bare
+* hostnames — `"my-app.vercel.app"`, no scheme — which terminals don't
+* linkify and browsers won't navigate to unmodified. Printed output
+* should be a URL a human can click/paste; structured log fields keep
+* the raw provider value as-is.
+*/
+function withScheme(url) {
+	return /^https?:\/\//.test(url) ? url : `https://${url}`;
 }
-//#endregion
-//#region src/commands/deploy.ts
 async function runDeploy(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1259,23 +1518,43 @@ async function runDeploy(input) {
 		};
 	}
 	try {
-		const record = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
+		const triggered = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
 			projectId: input.projectId,
 			branch: input.branch,
 			...input.target ? { target: input.target } : {}
 		}));
-		print(`  ${style.success(`${record.status} — ${record.url}`)}`);
+		logger.info({
+			status: triggered.status,
+			url: triggered.url,
+			id: triggered.id
+		}, "deploy: triggered");
+		const record = TERMINAL_STATUSES.has(triggered.status) ? triggered : await withSpinner(`Waiting for ${withScheme(triggered.url)} to finish…`, () => waitForDeployment(deploy, triggered.id, input.wait));
+		if (record.status !== "ready") {
+			const message = terminalFailure(record);
+			print(`  ${style.fail(`${message} — ${withScheme(triggered.url)}`)}`);
+			logger.warn({
+				id: record.id,
+				status: record.status,
+				reason: record.errorMessage
+			}, "deploy: failed");
+			return {
+				deployment: record,
+				status: "fail",
+				message
+			};
+		}
+		print(`  ${style.success(`${record.status} — ${withScheme(triggered.url)}`)}`);
 		logger.info({
 			status: record.status,
-			url: record.url,
+			url: triggered.url,
 			id: record.id
-		}, "deploy: triggered");
+		}, "deploy: ready");
 		return {
 			deployment: record,
 			status: "ok"
 		};
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		print(`  ${style.fail(message)}`);
 		logger.warn({
 			branch: input.branch,
@@ -1288,8 +1567,124 @@ async function runDeploy(input) {
 		};
 	}
 }
+const SKIP_DIRS$2 = /* @__PURE__ */ new Set([
+	".git",
+	"node_modules",
+	".turbo"
+]);
+/** Recursively lists absolute file paths under `dir`, skipping VCS/tooling noise. */
+function defaultWalkFiles$2(dir) {
+	const results = [];
+	for (const entry of readdirSync(dir)) {
+		if (SKIP_DIRS$2.has(entry)) continue;
+		const full = join(dir, entry);
+		const stat = statSync(full);
+		if (stat.isDirectory()) results.push(...defaultWalkFiles$2(full));
+		else if (stat.isFile()) results.push(full);
+	}
+	return results;
+}
+/** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
+async function runDeployFromFiles(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "deploy");
+	const dryRun = input.context.dryRun ?? false;
+	const walkFiles = input.walkFiles ?? defaultWalkFiles$2;
+	const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const files = {};
+	for (const abs of walkFiles(input.dir)) {
+		const rel = relative(input.dir, abs).split(sep).join("/");
+		files[rel] = readFile(abs);
+	}
+	const fileCount = Object.keys(files).length;
+	logger.info({
+		dir: input.dir,
+		fileCount,
+		target: input.target ?? "preview",
+		projectId: input.projectId,
+		dryRun: dryRun || void 0
+	}, "deploy: start (files)");
+	print(style.header(`Holocron deploy — files=${input.dir} (${fileCount} file${fileCount === 1 ? "" : "s"})${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`));
+	if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
+	const deploy = loader.get("deployment");
+	if (!deploy.deployFunction) throw new Error(`deployment provider "${deploy.providerName}" does not support deploying from files — deployFunction() is not implemented`);
+	if (dryRun) {
+		const message = `would: ${deploy.providerName}.deployFunction(projectId=${input.projectId}, files=${fileCount}${input.target ? `, target=${input.target}` : ""})`;
+		print(`  ${style.dim(`… ${message}`)}`);
+		return {
+			deployment: null,
+			status: "dry-run",
+			message
+		};
+	}
+	try {
+		const result = await withSpinner(`Deploying ${fileCount} file${fileCount === 1 ? "" : "s"} from ${input.dir}…`, () => deploy.deployFunction(input.projectId, {
+			files,
+			...input.target ? { target: input.target } : {}
+		}));
+		logger.info({
+			url: result.url,
+			id: result.deploymentId
+		}, "deploy: triggered (files)");
+		const record = await withSpinner(`Waiting for ${withScheme(result.url)} to finish…`, () => waitForDeployment(deploy, result.deploymentId, input.wait));
+		if (record.status !== "ready") {
+			const message = terminalFailure(record);
+			print(`  ${style.fail(`${message} — ${withScheme(result.url)}`)}`);
+			logger.warn({
+				id: record.id,
+				status: record.status,
+				reason: record.errorMessage
+			}, "deploy: failed (files)");
+			return {
+				deployment: result,
+				status: "fail",
+				message
+			};
+		}
+		print(`  ${style.success(withScheme(result.url))}`);
+		logger.info({
+			url: result.url,
+			id: result.deploymentId
+		}, "deploy: ready (files)");
+		return {
+			deployment: result,
+			status: "ok"
+		};
+	} catch (err) {
+		const message = errorMessage(err);
+		print(`  ${style.fail(message)}`);
+		logger.warn({
+			dir: input.dir,
+			reason: message
+		}, "deploy: failed (files)");
+		return {
+			deployment: null,
+			status: "fail",
+			message
+		};
+	}
+}
 //#endregion
 //#region src/commands/doctor.ts
+/**
+* `holocron doctor` — load the config, instantiate every capability,
+* print a per-capability readiness report.
+*
+* Each capability gets a smoke check appropriate to its surface:
+*   source   → `whoami()`
+*   issues   → `doctor()` (rich report)
+*   secrets  → `listSecrets({ kind: 'repo' })`
+*   ci       → `listRuns({ limit: 1 })`
+*   errors   → `describe()`
+*   logs     → `whoami()` (dataset reachability) or `describe()`
+*   others   → just "loaded" (no smoke endpoint defined yet)
+*
+* Output is plain text via a passed-in `print` function so tests can
+* capture lines without ANSI / spinner noise.
+*/
 async function runDoctor(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -1297,7 +1692,7 @@ async function runDoctor(input) {
 	assertPluginsResolvable(loader, "doctor");
 	const rows = [];
 	const config = input.loaded.resolved;
-	print(style.header(`Holocron doctor — ${config.name}`));
+	print("");
 	print(style.dim(`  config: ${input.loaded.filepath}`));
 	print("");
 	for (const failure of loader.loadFailures()) rows.push({
@@ -1332,10 +1727,7 @@ async function runDoctor(input) {
 			status: row.status,
 			detail: row.message
 		}, `doctor: ${row.capability}`);
-		const label = `${pad(row.capability, 14)} via ${pad(row.provider, 14)}  ${row.message}`;
-		if (row.status === "ok") print(`  ${style.success(label)}`);
-		else if (row.status === "fail") print(`  ${style.fail(label)}`);
-		else print(`  ${style.dim(`· ${label}`)}`);
+		print(statusRow(row.status, [`${pad(row.capability, 14)} via ${pad(row.provider, 14)}`, row.message]));
 	}
 	const summary = rows.reduce((acc, r) => {
 		acc[r.status] += 1;
@@ -1347,7 +1739,7 @@ async function runDoctor(input) {
 	});
 	const summaryLine = `${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped`;
 	print("");
-	print(summary.fail > 0 ? style.fail(summaryLine) : style.success(summaryLine));
+	print(style.header(summaryLine));
 	return {
 		rows,
 		summary
@@ -1367,6 +1759,24 @@ async function smokeCheck(key, provider, impl) {
 				return mk(key, provider, "ok", runs.length === 0 ? "no recent runs" : `most recent: ${runs[0].workflowName} (${runs[0].status})`);
 			}
 			case "vault": return mk(key, provider, "ok", `${(await impl.list()).length} keys available`);
+			case "deployment": return mk(key, provider, "ok", `${(await impl.listProjects()).length} project(s) visible`);
+			case "environments": return mk(key, provider, "ok", `${(await impl.listEnvironments()).length} environment(s) configured`);
+			case "dns": {
+				const dns = impl;
+				if (dns.whoami) {
+					const who = await dns.whoami();
+					return mk(key, provider, who.ok ? "ok" : "fail", `${who.zones} zone(s) visible`);
+				}
+				return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
+			}
+			case "workers": {
+				const workers = impl;
+				if (workers.whoami) {
+					const who = await workers.whoami();
+					return mk(key, provider, who.ok ? "ok" : "fail", `${who.scripts} script(s) visible`);
+				}
+				return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
+			}
 			case "auth": {
 				const desc = await impl.describe();
 				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
@@ -1384,10 +1794,18 @@ async function smokeCheck(key, provider, impl) {
 				}
 				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
 			}
+			case "monitoring": {
+				const monitoring = impl;
+				if (monitoring.whoami) {
+					const who = await monitoring.whoami();
+					return mk(key, provider, who.ok ? "ok" : "fail", who.ok ? "token verified" : "token check failed");
+				}
+				return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
+			}
 			default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 		}
 	} catch (err) {
-		return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
+		return mk(key, provider, "fail", errorMessage(err));
 	}
 }
 function countResolvedLifecycle(report) {
@@ -1401,13 +1819,10 @@ function mk(capability, provider, status, message) {
 		message
 	};
 }
-function pad(s, width) {
-	return s.length >= width ? s : s + " ".repeat(width - s.length);
-}
 //#endregion
 //#region src/commands/new.ts
 /**
-* `holocron new <type> <name>` — create a GitHub repo from a template and
+* `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.
@@ -1657,7 +2072,7 @@ async function runNew(input) {
 			stdio: "inherit"
 		});
 	} catch (err) {
-		throw new NewError(`gh repo create failed: ${err instanceof Error ? err.message : String(err)}`);
+		throw new NewError(`gh repo create failed: ${errorMessage(err)}`);
 	}
 	if (input.isTemplate) try {
 		execFn("gh", [
@@ -1752,7 +2167,7 @@ async function runNew(input) {
 				stdio: "inherit"
 			});
 		} catch (err) {
-			print(`  ✗ pnpm install failed — ${err instanceof Error ? err.message : String(err)}`);
+			print(`  ✗ pnpm install failed — ${errorMessage(err)}`);
 			return {
 				status: "fail",
 				repoDir,
@@ -1761,7 +2176,7 @@ async function runNew(input) {
 			};
 		}
 		print("");
-		print("  Running holocron setup…");
+		print("  Running holocron repo setup…");
 		try {
 			const setupArgs = ["setup"];
 			const setupEnv = {};
@@ -1781,7 +2196,7 @@ async function runNew(input) {
 				env: setupEnv
 			});
 		} catch {
-			print("  ✗ holocron setup failed — run it manually after checking your config");
+			print("  ✗ holocron repo setup failed — run it manually after checking your config");
 		}
 	}
 	print("");
@@ -1791,7 +2206,7 @@ async function runNew(input) {
 	print(`    1. cd ${repoDir}`);
 	if (input.noVerify) {
 		print(`    2. pnpm install`);
-		print(`    3. holocron setup  # wire up secrets, teams, labels, etc.`);
+		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({
@@ -1963,14 +2378,16 @@ describe("resolveToken", () => {
 	});
 
 	it("throws AuthError with a helpful message when nothing is set", () => {
-		try {
-			resolveToken({ env: {}, keyring: noKeyring });
-			throw new Error("should have thrown");
-		} catch (err) {
-			expect(err).toBeInstanceOf(AuthError);
-			expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
-			expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
-		}
+		const err = (() => {
+			try {
+				resolveToken({ env: {}, keyring: noKeyring });
+			} catch (e) {
+				return e;
+			}
+		})();
+		expect(err).toBeInstanceOf(AuthError);
+		expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
+		expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
 	});
 });
 `;
@@ -2014,24 +2431,24 @@ export class ${inputs.capabilityClass} {
 //#endregion
 //#region src/commands/plugin-create/templates/capability-test.ts
 function render$14(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
-	return `import { describe, it } from "vitest";
+	const factoryName = `create${inputs.vendorName}RestClient`;
+	return `import { describe, expect, it } from "vitest";
 
 import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
-import { ${clientClass} } from "../rest.js";
+import { ${factoryName} } from "../rest.js";
 import { stubFetch } from "./helpers.js";
 
 // Stub client used by the constructor smoke test. Real capability
 // tests replace this with per-method stubs once implementations land.
 function makeCapability() {
 	const stub = stubFetch([]);
-	const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
+	const rest = ${factoryName}({ token: "t", fetch: stub.fetch });
 	return new ${inputs.capabilityClass}(() => rest);
 }
 
 describe("${inputs.capabilityClass}", () => {
 	it("constructs with a REST client", () => {
-		makeCapability();
+		expect(makeCapability().key).toBe("${inputs.capability}");
 	});
 
 	// TODO: implement one test per ${inputs.capability} capability method
@@ -2047,14 +2464,11 @@ describe("${inputs.capabilityClass}", () => {
 //#endregion
 //#region src/commands/plugin-create/templates/eslint-config.ts
 function render$13(_inputs) {
-	return `import root from "../../eslint.config.js";
+	return `import type { Linter } from "eslint";
 
-export default [
-	...root,
-	{
-		ignores: ["dist/**", "coverage/**"],
-	},
-];
+import root from "../../eslint.config.js";
+
+export default [...root, { ignores: ["dist/**", "coverage/**"] }] satisfies Linter.Config[];
 `;
 }
 //#endregion
@@ -2137,22 +2551,33 @@ describe("AUTH_HINT", () => {
 //#endregion
 //#region src/commands/plugin-create/templates/package-json.ts
 function render$10(inputs) {
+	const keywords = [
+		inputs.capability,
+		"holocron",
+		"plugin",
+		inputs.slug
+	].sort((a, b) => a.localeCompare(b));
 	return JSON.stringify({
 		name: `@theholocron/holocron-plugin-${inputs.slug}`,
 		version: "2.0.0-alpha.1",
 		description: `Holocron plugin for ${inputs.vendorName}. Implements the ${inputs.capability} capability against ${inputs.vendorName}'s REST API, plus exports verifyToken + AUTH_HINT for \`holocron auth\`.`,
-		homepage: `https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme`,
+		keywords,
+		homepage: `https://github.com/theholocron/holocron/tree/main/plugins/holocron-plugin-${inputs.slug}#readme`,
 		bugs: "https://github.com/theholocron/holocron/issues",
 		repository: {
 			type: "git",
 			url: "git+https://github.com/theholocron/holocron.git",
-			directory: `packages/holocron-plugin-${inputs.slug}`
+			directory: `plugins/holocron-plugin-${inputs.slug}`
 		},
 		license: "MIT",
 		author: "Newton Koumantzelis",
+		sideEffects: false,
 		type: "module",
-		main: "./src/index.ts",
-		exports: { ".": "./src/index.ts" },
+		exports: { ".": {
+			types: "./dist/index.d.mts",
+			import: "./dist/index.mjs",
+			default: "./dist/index.mjs"
+		} },
 		scripts: {
 			"delivery.build": "tsdown",
 			"sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
@@ -2161,36 +2586,33 @@ function render$10(inputs) {
 			"test:watch": "vitest",
 			validate: "tsx scripts/validate.mjs"
 		},
-		peerDependencies: { "@theholocron/cli": "workspace:*" },
+		peerDependencies: {
+			"@theholocron/cli": "workspace:*",
+			"@theholocron/misc-utils": "catalog:utils"
+		},
 		devDependencies: {
 			"@theholocron/cli": "workspace:*",
-			"@theholocron/tsconfig": "catalog:",
-			"@tsconfig/node-lts": "catalog:",
+			"@theholocron/misc-utils": "catalog:utils",
+			"@theholocron/tsconfig": "catalog:configs",
+			"@types/node": "catalog:",
 			"@vitest/coverage-v8": "catalog:",
 			eslint: "catalog:",
 			globals: "catalog:",
-			typescript: "catalog:",
-			vitest: "catalog:",
 			tsdown: "catalog:",
-			tsx: "catalog:"
-		},
-		publishConfig: {
-			access: "public",
-			main: "./dist/index.mjs",
-			types: "./dist/index.d.mts",
-			exports: { ".": {
-				types: "./dist/index.d.mts",
-				import: "./dist/index.mjs",
-				default: "./dist/index.mjs"
-			} }
+			tsx: "catalog:",
+			typescript: "catalog:",
+			vitest: "catalog:"
 		},
-		files: ["dist", "README.md"]
-	}, null, "	") + "\n";
+		engines: { node: ">=22" },
+		publishConfig: { access: "public" },
+		files: ["dist"]
+	}, null, 2) + "\n";
 }
 //#endregion
 //#region src/commands/plugin-create/templates/plugin-index.ts
 function render$9(inputs) {
 	const clientClass = `${inputs.vendorName}RestClient`;
+	const factoryName = `create${inputs.vendorName}RestClient`;
 	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
 	return `/**
  * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
@@ -2207,7 +2629,7 @@ function render$9(inputs) {
 
 import { resolveToken, type ResolveTokenInput } from "./auth.js";
 import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
-import { ${clientClass} } from "./rest.js";
+import { ${factoryName}, type ${clientClass} } from "./rest.js";
 
 export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
 	/** Override base URL for tests. */
@@ -2228,10 +2650,12 @@ export function createContext(options: ${inputs.vendorName}PluginOptions): Plugi
 		options,
 		rest: () => {
 			if (rest) return rest;
-			const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token: resolveToken(options) };
+			const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = {
+				token: resolveToken(options),
+			};
 			if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
 			if (options.fetch !== undefined) restOpts.fetch = options.fetch;
-			return (rest = new ${clientClass}(restOpts));
+			return (rest = ${factoryName}(restOpts));
 		},
 	};
 }
@@ -2265,10 +2689,10 @@ export const AUTH_HINT =
 // ── Public re-exports ────────────────────────────────────────────────
 
 export * from "./auth.js";
-export { ${clientClass} } from "./rest.js";
+export { type ${clientClass}, ${factoryName} } from "./rest.js";
 export { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
 export { verifyToken } from "./verify-token.js";
-export type { VerifyTokenResult, VerifyTokenSuccess, VerifyTokenFailure } from "./verify-token.js";
+export type { VerifyTokenFailure, VerifyTokenResult, VerifyTokenSuccess } from "@theholocron/cli";
 `;
 }
 //#endregion
@@ -2335,22 +2759,33 @@ TODO: fill in as capability methods land.
 
 ## Status
 
-**\`v2.0.0-alpha.1\`** — scaffolded via \`holocron plugin create\`.
+**\`v2.0.0-alpha.1\`** — scaffolded via \`holocron new plugin\`.
 Not yet published; capability methods are stubs.
 `;
 }
 //#endregion
 //#region src/commands/plugin-create/templates/rest.ts
 function render$7(inputs) {
-	return `import { createRestClient, type RequestOptions, type RestClient } from "@theholocron/cli";
+	const factoryName = `create${inputs.vendorName}RestClient`;
+	const clientType = `${inputs.vendorName}RestClient`;
+	return `import { createRestClient, type RestClient } from "@theholocron/cli";
+
+export type { RestClient };
 
-export type { RequestOptions, RestClient };
+/**
+ * TODO: narrow this to the specific ${inputs.vendorName} endpoints this
+ * plugin's capability needs (see \`@theholocron/holocron-plugin-axiom\`'s
+ * \`rest.ts\` for the pattern: an interface with one method per endpoint,
+ * built internally via \`createRestClient\`). Starts as an alias for the
+ * generic client so the scaffold compiles end to end immediately.
+ */
+export type ${clientType} = RestClient;
 
-export function ${`create${inputs.vendorName}RestClient`}(opts: {
+export function ${factoryName}(opts: {
 \ttoken: string;
 \tbaseUrl?: string;
 \tfetch?: typeof fetch;
-}): RestClient {
+}): ${clientType} {
 \treturn createRestClient({
 \t\tbaseUrl: opts.baseUrl ?? "${inputs.baseUrl}",
 \t\ttoken: opts.token,
@@ -2423,7 +2858,7 @@ describe("${factoryName}", () => {
 function render$5(inputs) {
 	return JSON.stringify({
 		display: `Holocron Plugin: ${inputs.vendorName}`,
-		extends: "@tsconfig/node-lts/tsconfig.json",
+		extends: "@theholocron/tsconfig/node-lts",
 		compilerOptions: {
 			baseUrl: "./",
 			outDir: "./dist",
@@ -2431,7 +2866,7 @@ function render$5(inputs) {
 		},
 		include: ["src/**/*.ts"],
 		exclude: ["node_modules", "dist"]
-	}, null, "	") + "\n";
+	}, null, 2) + "\n";
 }
 //#endregion
 //#region src/commands/plugin-create/templates/tsdown-config.ts
@@ -2487,11 +2922,12 @@ function render$3(inputs) {
  * TODO: replace the positional args below with whatever your
  * capability's methods need (e.g., project id, environment slug,
  * secret name). Adapt the test steps to your capability's method
- * surface. Model on \`packages/holocron-plugin-infisical/scripts/validate.mjs\`.
+ * surface. Model on \`plugins/holocron-plugin-infisical/scripts/validate.mjs\`.
  */
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
 import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
+import { errorMessage } from "@theholocron/misc-utils";
 
 const args = process.argv.slice(2);
 
@@ -2511,7 +2947,7 @@ try {
 } catch (err) {
 	if (err instanceof AuthError) {
 		console.error(err.message);
-		console.error("  see: packages/holocron-plugin-${inputs.slug}/README.md#setup");
+		console.error("  see: plugins/holocron-plugin-${inputs.slug}/README.md#setup");
 		process.exit(2);
 	}
 	throw err;
@@ -2547,11 +2983,12 @@ console.log("Done. Fill in capability method calls above before shipping.");
 // ── helpers ────────────────────────────────────────────────────────
 
 /** Wrap a capability call, print ERROR + hint on failure. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- called once a real capability check replaces the TODO example above
 async function runStep(body) {
 	try {
 		await body();
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		console.log(\`      ✗ ERROR: \${message}\`);
 		const hint = hintFor(message);
 		if (hint) console.log(\`         hint: \${hint}\`);
@@ -2586,7 +3023,7 @@ function hintFor(message) {
 //#endregion
 //#region src/commands/plugin-create/templates/verify-token.ts
 function render$2(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
+	const factoryName = `create${inputs.vendorName}RestClient`;
 	return `/**
  * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
  * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
@@ -2603,19 +3040,10 @@ function render$2(inputs) {
  * \`/me\`, \`/account\`.
  */
 
-import { ${clientClass} } from "./rest.js";
-
-export interface VerifyTokenSuccess {
-	ok: true;
-	subject: string;
-}
-
-export interface VerifyTokenFailure {
-	ok: false;
-	message: string;
-}
+import type { VerifyTokenResult } from "@theholocron/cli";
+import { errorMessage } from "@theholocron/misc-utils";
 
-export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+import { ${factoryName} } from "./rest.js";
 
 interface MeResponse {
 	/** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
@@ -2630,18 +3058,17 @@ export interface VerifyTokenOptions {
 }
 
 export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
-	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = { token };
 	if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
 	if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
-	const rest = new ${clientClass}(restOpts);
+	const rest = ${factoryName}(restOpts);
 	try {
 		const me = await rest.request<MeResponse>("/me");
 		// Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
 		const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
 		return { ok: true, subject: \`user @ \${subject}\` };
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		return { ok: false, message };
+		return { ok: false, message: errorMessage(err) };
 	}
 }
 `;
@@ -2659,18 +3086,14 @@ describe("verifyToken", () => {
 		const stub = stubFetch([{ status: 200, body: { email: "user@example.com" } }]);
 		const result = await verifyToken("token", { fetch: stub.fetch });
 		expect(result.ok).toBe(true);
-		if (result.ok) {
-			expect(result.subject).toMatch(/user@example.com/);
-		}
+		expect((result as { ok: boolean; subject?: string }).subject).toMatch(/user@example.com/);
 	});
 
 	it("returns ok:false with the error message on 401", async () => {
 		const stub = stubFetch([{ status: 401, body: { messages: ["Invalid token"] } }]);
 		const result = await verifyToken("bad", { fetch: stub.fetch });
 		expect(result.ok).toBe(false);
-		if (!result.ok) {
-			expect(result.message).toMatch(/→ 401/);
-		}
+		expect((result as { ok: boolean; message?: string }).message).toMatch(/→ 401/);
 	});
 
 	it("returns ok:false when the network layer throws", async () => {
@@ -2679,9 +3102,7 @@ describe("verifyToken", () => {
 		};
 		const result = await verifyToken("t", { fetch: throwing });
 		expect(result.ok).toBe(false);
-		if (!result.ok) {
-			expect(result.message).toMatch(/network down/);
-		}
+		expect((result as { ok: boolean; message?: string }).message).toMatch(/network down/);
 	});
 });
 `;
@@ -2709,7 +3130,7 @@ export default defineConfig({
 //#endregion
 //#region src/commands/plugin-create/index.ts
 /**
-* `holocron plugin create <slug> <vendor>` — scaffold a new plugin
+* `holocron new plugin <slug> <vendor>` — scaffold a new plugin
 * package matching the proven template.
 *
 * Design: see `docs/wiki/specifications/tool-plugin-create.spec.md`.
@@ -2717,11 +3138,11 @@ export default defineConfig({
 * Flow:
 *   1. Preflight — verify CWD is a workspace root (pnpm-workspace.yaml
 *      + packages/ dir present).
-*   2. Slug collision — packages/holocron-plugin-<slug>/ must not exist.
+*   2. Slug collision — plugins/holocron-plugin-<slug>/ must not exist.
 *   3. Capability sanity — must be one of the 14 known keys; warn for
 *      many-cardinality caps.
 *   4. Generate — for each template, write to
-*      packages/holocron-plugin-<slug>/<path>.
+*      plugins/holocron-plugin-<slug>/<path>.
 *   5. Verify (unless --no-verify) — runs pnpm install +
 *      pnpm --filter <pkg> typecheck lint test.
 *   6. Print next steps.
@@ -2755,7 +3176,7 @@ const TEMPLATES = [
 		render
 	},
 	{
-		path: "eslint.config.js",
+		path: "eslint.config.ts",
 		render: render$13
 	},
 	{
@@ -2827,7 +3248,7 @@ function runPluginCreate(input) {
 	preflight(cwd);
 	validateSlug(input.slug);
 	validateVendorName(input.vendorName);
-	const packageDir = path.join(cwd, "packages", `holocron-plugin-${input.slug}`);
+	const packageDir = path.join(cwd, "plugins", `holocron-plugin-${input.slug}`);
 	if (existsSync(packageDir)) throw new PluginCreateError(`\`${packageDir}\` already exists — edit in place or pick a different slug.`);
 	validateCapability(input.capability, print);
 	const derived = deriveDefaults$1({
@@ -2901,7 +3322,7 @@ function runPluginCreate(input) {
 			});
 			print("  ✓ scaffold verified");
 		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
+			const message = errorMessage(err);
 			print(`  ✗ verify failed — ${message}`);
 			logger.warn({
 				slug: inputs.slug,
@@ -2931,7 +3352,7 @@ function runPluginCreate(input) {
 	};
 }
 function preflight(cwd) {
-	if (!existsSync(path.join(cwd, "pnpm-workspace.yaml"))) throw new PluginCreateError(`\`pnpm-workspace.yaml\` not found in \`${cwd}\`. Run \`holocron plugin create\` from the monorepo root.`);
+	if (!existsSync(path.join(cwd, "pnpm-workspace.yaml"))) throw new PluginCreateError(`\`pnpm-workspace.yaml\` not found in \`${cwd}\`. Run \`holocron new plugin\` from the monorepo root.`);
 	if (!existsSync(path.join(cwd, "packages"))) throw new PluginCreateError(`\`packages/\` directory not found in \`${cwd}\`.`);
 }
 /**
@@ -2988,7 +3409,7 @@ function printNextSteps$1(print, inputs) {
 //#endregion
 //#region src/commands/publish.ts
 /**
-* `holocron publish --initial` — bottles up the chicken-and-egg bootstrap
+* `holocron package publish --initial` — bottles up the chicken-and-egg bootstrap
 * that every new npm-published holocron monorepo hits.
 *
 * npm requires a package to exist before Trusted Publishing can be
@@ -3002,14 +3423,14 @@ function printNextSteps$1(print, inputs) {
 *
 *   $ pnpm install --frozen-lockfile
 *   $ pnpm build
-*   $ pnpm exec tsx packages/cli/src/cli.ts publish --initial
+*   $ pnpm exec tsx packages/cli/src/cli.ts package publish --initial
 *
 * `npm login --auth-type=web` runs automatically the first time — no
 * separate manual step. `pnpm install` + `pnpm build` stay outside the
 * command (no pnpm-inside-pnpm).
 *
 * `--initial` is required today — this command only implements the
-* bootstrap publish. A non-initial `holocron publish` (for a manual publish
+* bootstrap publish. A non-initial `holocron package publish` (for a manual publish
 * outside the semantic-release/OIDC steady state) isn't built yet; the flag
 * exists so the surface doesn't need another rename when it is.
 *
@@ -3018,7 +3439,7 @@ function printNextSteps$1(print, inputs) {
 * setup` for the ephemeral GH admin PAT.
 */
 /**
-* `holocron publish --sync-trust <old-file> <new-file>` — bulk-migrates npm
+* `holocron package publish --sync-trust <old-file> <new-file>` — bulk-migrates npm
 * Trusted Publisher (OIDC) config to a new workflow filename across every
 * public package. See issue #689 / `scripts/npm-trust-migrate.sh` (the
 * shell-script prototype this supersedes) for the full "why": npm ties
@@ -3058,7 +3479,7 @@ async function runSyncTrust(input) {
 		packages: packageNames.length
 	}, "sync-trust: start");
 	if (packageNames.length === 0) {
-		const message = "nothing to sync (no packages/* and root package.json is private or unnamed)";
+		const message = "nothing to sync (no packages/*, plugins/*, or root package.json is private or unnamed)";
 		print(`  ✗ ${message}`);
 		return {
 			status: "fail",
@@ -3215,7 +3636,7 @@ async function runPublish(input = {}) {
 	const exec = input.exec ?? defaultExec$1;
 	const login = input.login ?? defaultLogin;
 	const publishArgs = [
-		...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+		...workspaceFilterArgs(cwd),
 		"publish",
 		"--access",
 		"public",
@@ -3266,7 +3687,7 @@ async function runPublish(input = {}) {
 	const packageNames = input.packages ?? discoverPublicPackages(cwd);
 	const repoName = input.repoName ?? await resolveRepoName(cwd, exec);
 	if (packageNames.length === 0) {
-		const message = "nothing to publish (no packages/* and root package.json is private or unnamed)";
+		const message = "nothing to publish (no packages/*, plugins/*, or root package.json is private or unnamed)";
 		print(`  ✗ ${message}`);
 		logger.warn({ reason: message }, "publish --initial: done");
 		return {
@@ -3300,7 +3721,7 @@ async function runPublish(input = {}) {
 		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
 			print("");
 			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
-			print(`    pnpm exec tsx packages/cli/src/cli.ts publish --initial --otp <6-digit-code>`);
+			print(`    pnpm exec tsx packages/cli/src/cli.ts package publish --initial --otp <6-digit-code>`);
 		}
 		logger.warn({
 			tag,
@@ -3325,7 +3746,7 @@ async function runPublish(input = {}) {
 	};
 }
 /**
-* `holocron publish` (no `--initial`) — the steady-state publish
+* `holocron package publish` (no `--initial`) — the steady-state publish
 * `exec.publishCmd` in `release.config.ts` should call, replacing each
 * repo's hand-typed `pnpm -r --filter=./packages/* publish ...` shell (which
 * differs, today, only in monorepo-vs-single-package, provenance on/off, and
@@ -3336,7 +3757,7 @@ async function runPublish(input = {}) {
 * Deliberately does not do the `--initial` bootstrap dance (npm
 * login-if-needed, Trusted Publisher next-steps printout) — a steady-state
 * publish runs in CI, authenticated via OIDC automatically, no interactive
-* step involved. Reuses `hasPackagesDir()`'s monorepo-vs-single-package
+* step involved. Reuses `workspaceFilterArgs()`'s monorepo-vs-single-package
 * detection rather than duplicating it.
 */
 async function runSteadyPublish(input = {}) {
@@ -3365,7 +3786,7 @@ async function runSteadyPublish(input = {}) {
 	if (otp) print(`  otp: <${otp.length} chars>`);
 	print("");
 	if (entries.length === 0) {
-		const message = "nothing to publish (no packages/* and root package.json is private or unnamed)";
+		const message = "nothing to publish (no packages/*, plugins/*, or root package.json is private or unnamed)";
 		print(`  ✗ ${message}`);
 		logger.warn({ reason: message }, "publish: done");
 		return {
@@ -3388,7 +3809,7 @@ async function runSteadyPublish(input = {}) {
 		if (skipAlreadyPublished) for (const entry of entries) print(`  … would check ${entry.name}@${entry.version}, publish if not already on npm`);
 		else {
 			const args = [
-				...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+				...workspaceFilterArgs(cwd),
 				"publish",
 				...baseFlags,
 				...otpFlags
@@ -3454,7 +3875,7 @@ async function runSteadyPublish(input = {}) {
 	}
 	print("  → publishing all public @theholocron/* packages…");
 	const publish = await exec("pnpm", [
-		...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+		...workspaceFilterArgs(cwd),
 		"publish",
 		...baseFlags,
 		...otpFlags
@@ -3465,7 +3886,7 @@ async function runSteadyPublish(input = {}) {
 		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
 			print("");
 			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
-			print(`    pnpm exec holocron publish --otp <6-digit-code>`);
+			print(`    pnpm exec holocron package publish --otp <6-digit-code>`);
 		}
 		logger.warn({
 			tag,
@@ -3491,6 +3912,22 @@ async function runSteadyPublish(input = {}) {
 function hasPackagesDir(cwd) {
 	return existsSync(join(cwd, "packages"));
 }
+/** `plugins/` — vendor capability providers, split from `packages/` as a sibling workspace root (#993). */
+function hasPluginsDir(cwd) {
+	return existsSync(join(cwd, "plugins"));
+}
+/**
+* `-r --filter=./packages/* --filter=./plugins/*` — whichever workspace
+* roots exist. Empty (single-package repo, no `-r`) when neither does.
+* Shared by every `pnpm publish` invocation below so a repo with only
+* `plugins/*` (or both) is covered the same as `packages/*`-only.
+*/
+function workspaceFilterArgs(cwd) {
+	const filters = [];
+	if (hasPackagesDir(cwd)) filters.push("--filter=./packages/*");
+	if (hasPluginsDir(cwd)) filters.push("--filter=./plugins/*");
+	return filters.length > 0 ? ["-r", ...filters] : [];
+}
 /** Read a `package.json`'s `name`, when it's public (`!private && name`). */
 function publicPackageName(pkgPath) {
 	if (!existsSync(pkgPath)) return void 0;
@@ -3522,29 +3959,38 @@ function publicPackageEntry(pkgPath, dir) {
 * and publish one workspace at a time.
 */
 function discoverPublicPackageEntries(cwd) {
-	if (!hasPackagesDir(cwd)) {
+	if (!hasPackagesDir(cwd) && !hasPluginsDir(cwd)) {
 		const entry = publicPackageEntry(join(cwd, "package.json"), ".");
 		return entry ? [entry] : [];
 	}
-	const packagesDir = join(cwd, "packages");
-	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
-		const entry = publicPackageEntry(join(packagesDir, e.name, "package.json"), `./packages/${e.name}`);
+	return [...entriesInWorkspaceDir(cwd, "packages"), ...entriesInWorkspaceDir(cwd, "plugins")];
+}
+function entriesInWorkspaceDir(cwd, dirName) {
+	const dirPath = join(cwd, dirName);
+	if (!existsSync(dirPath)) return [];
+	return readdirSync(dirPath, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
+		const entry = publicPackageEntry(join(dirPath, e.name, "package.json"), `./${dirName}/${e.name}`);
 		return entry ? [entry] : [];
 	});
 }
 /**
-* Monorepo (`packages/` present): every public `packages/*` workspace.
-* Single package (no `packages/`): the root `package.json`, if it's public —
-* most `node-template` scaffolds are one package at the repo root.
+* Monorepo (`packages/` and/or `plugins/` present): every public workspace
+* under either. Single package (neither dir present): the root
+* `package.json`, if it's public — most `node-template` scaffolds are one
+* package at the repo root.
 */
 function discoverPublicPackages(cwd) {
-	if (!hasPackagesDir(cwd)) {
+	if (!hasPackagesDir(cwd) && !hasPluginsDir(cwd)) {
 		const name = publicPackageName(join(cwd, "package.json"));
 		return name ? [name] : [];
 	}
-	const packagesDir = join(cwd, "packages");
-	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
-		const name = publicPackageName(join(packagesDir, e.name, "package.json"));
+	return [...namesInWorkspaceDir(cwd, "packages"), ...namesInWorkspaceDir(cwd, "plugins")];
+}
+function namesInWorkspaceDir(cwd, dirName) {
+	const dirPath = join(cwd, dirName);
+	if (!existsSync(dirPath)) return [];
+	return readdirSync(dirPath, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
+		const name = publicPackageName(join(dirPath, e.name, "package.json"));
 		return name ? [name] : [];
 	});
 }
@@ -3598,12 +4044,30 @@ const defaultLogin = async (cwd) => {
 };
 //#endregion
 //#region src/commands/secret-set.ts
+/**
+* `holocron secrets set` — one-shot single-secret push.
+*
+* Complements `holocron secrets sync` (bulk vault → destinations) for
+* ad-hoc scenarios:
+*   - Bootstrap secrets (e.g., NPM_TOKEN on theholocron/holocron itself
+*     before the rest of the setup exists)
+*   - One-off rotations that don't warrant a vault sync
+*   - Setting secrets the vault doesn't track
+*
+* Value source resolution (in priority order):
+*   1. Positional `value` argument
+*   2. `--from-stdin` reads from stdin
+*   3. `--from-env <NAME>` reads from the named env var
+*   4. Implicit: env var matching the secret name (e.g., `NPM_TOKEN`)
+*
+* Errors clearly when no value can be sourced.
+*/
 async function runSecretSet(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
-	assertPluginsResolvable(loader, "secret set");
+	assertPluginsResolvable(loader, "secrets set");
 	const dryRun = input.context.dryRun ?? false;
 	const scope = input.scope ?? { kind: "repo" };
 	if (!loader.has("secrets")) throw new Error("`secrets` capability is not configured — add a `secrets` provider to holocron.config.json");
@@ -3636,7 +4100,7 @@ async function runSecretSet(input) {
 			scope
 		};
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		print(`  ✗ ${message}`);
 		logger.warn({
 			key: input.name,
@@ -3672,6 +4136,38 @@ function describeScope(scope) {
 }
 //#endregion
 //#region src/commands/secrets-sync.ts
+/**
+* `holocron secrets sync` — vault → destinations.
+*
+* Reads a named environment from the configured `vault` (1P
+* Environment / similar) as KEY=VALUE pairs, then fans those values
+* out to the configured destinations:
+*
+*  - `secrets` capability (e.g., GH Actions secrets) — repo-scope
+*  - `deployment` capability (e.g., Vercel env vars) — per-target
+*  - local `.env` file (optional, planned for v5.1 — currently skipped
+*    with a soft "not yet" note)
+*
+* Per-secret routing rules:
+*
+*  - All keys go to `deployment` for each target the caller asks for
+*    (defaults: production + preview)
+*  - `secrets` (GH Actions) defaults to every key, repo-scoped — but a
+*    caller can pass `githubSecretKeys` (an allowlist, from repeatable
+*    `--github-secret KEY` CLI values) to restrict `secrets` to only
+*    those keys, and `githubSecretScope` (same `{ kind }` shape `secret
+*    set`'s own `--scope repo|env=NAME|org=NAME` parses to) to apply one
+*    scope to all of them. A key not in the allowlist is skipped for
+*    `secrets` entirely — still synced to `deployment` if configured.
+*    Needed for a vault holding a mix of deploy-only secrets and one
+*    CI-consumed, org-wide secret (holocron#781's Sentinel case: 4
+*    Vercel-only keys + one org-scoped Axiom ingest token
+*    `theholocron/.github`'s dispatched-check workflow also reads).
+*
+* The vault MUST implement `readEnvironment(envId)` (optional method).
+* If it doesn't, the command errors with a hint to populate the keys
+* individually via `holocron secrets set` (also planned for v5.1).
+*/
 async function runSecretsSync(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -3696,10 +4192,13 @@ async function runSecretsSync(input) {
 	const rows = [];
 	if (loader.has("secrets")) {
 		const secrets = loader.get("secrets");
-		print(style.step("secrets (repo scope)"));
+		const scope = input.githubSecretScope ?? { kind: "repo" };
+		const allowedKeys = input.githubSecretKeys ? new Set(input.githubSecretKeys) : void 0;
+		print(style.step("secrets"));
 		for (const key of keys) {
-			rows.push(await runRow(`secrets:${secrets.providerName}`, "scope=repo", key, dryRun, async () => {
-				await secrets.setSecret({ kind: "repo" }, key, envVars[key]);
+			if (allowedKeys && !allowedKeys.has(key)) continue;
+			rows.push(await runRow(`secrets:${secrets.providerName}`, scopeLabel(scope), key, dryRun, async () => {
+				await secrets.setSecret(scope, key, envVars[key]);
 			}));
 			print(formatRow(rows[rows.length - 1]));
 		}
@@ -3779,7 +4278,7 @@ async function runRow(destination, scope, key, dryRun, body) {
 			scope,
 			key,
 			status: "fail",
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -3791,6 +4290,11 @@ function formatRow(row) {
 	if (row.status === "dry-run") return `    ${style.dim(`… ${label}`)}`;
 	return `    ${style.dim(`· ${label}`)}`;
 }
+function scopeLabel(scope) {
+	if (scope.kind === "repo") return "scope=repo";
+	if (scope.kind === "organization") return `scope=organization,org=${scope.name}`;
+	return `scope=environment,env=${scope.name}`;
+}
 function vaultProviderName(loader) {
 	if (!loader.has("vault")) return "<missing>";
 	return loader.get("vault").providerName;
@@ -3867,7 +4371,7 @@ function deriveCapabilities(providers) {
 	return Object.keys(providers ?? {}).sort();
 }
 /**
-* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* `source` + `ci` are the minimal baseline every repo `holocron repo setup`
 * touches wires — every `holocron.config.ts` in this org already satisfies
 * this, so `non-compliant` here means drift (a provider manually removed
 * after setup), not an unmet aspirational policy. Deliberately not a richer
@@ -3995,7 +4499,7 @@ var config_default = "# Configuration for sentiment-bot - https://github.com/beh
 //#endregion
 //#region src/utils/create-header.ts
 function createHeader(options) {
-	const { source, tool = "holocron setup", forPrimary = false } = options;
+	const { source, tool = "holocron repo setup", forPrimary = false } = options;
 	const doNotEdit = forPrimary ? `AUTO-GENERATED — do not edit in theholocron/.github directly.` : `AUTO-GENERATED — do not edit directly.`;
 	return {
 		workflowHeader(format = "yaml") {
@@ -4019,7 +4523,7 @@ function createHeader(options) {
 		},
 		scaffoldHeader() {
 			return [
-				`# Scaffolded by holocron setup — edit this file freely.`,
+				`# Scaffolded by holocron repo setup — edit this file freely.`,
 				`# Source:  theholocron/holocron · ${source}`,
 				``
 			].join("\n");
@@ -4033,6 +4537,9 @@ var alexignore_default = ".github/*\nCHANGELOG.md\nLICENSE\n";
 //#region src/templates/configs/alexjs/alexrc.json
 var alexrc_default = { allow: [
 	"dead",
+	"execute",
+	"execution",
+	"executes",
 	"failure",
 	"failures",
 	"hook",
@@ -4051,12 +4558,21 @@ function createIgnoreConfig$1() {
 }
 //#endregion
 //#region src/templates/configs/commit-msg/commit-msg
-var commit_msg_default = "# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to commitlint's own auto-discovery of a local commitlint.config.ts when\n# the shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nCOMMITLINT_CONFIG=\"node_modules/@theholocron/commitlint-config/dist/index.js\"\nif [ -f \"$COMMITLINT_CONFIG\" ]; then\n	npx --no -- commitlint --config \"$COMMITLINT_CONFIG\" --edit \"$1\"\nelse\n	npx --no -- commitlint --edit \"$1\"\nfi\n";
+var commit_msg_default = "__HOLOCRON_SCRIPT__ run lint commit-msg \"$1\"\n";
 //#endregion
 //#region src/templates/configs/commit-msg/create-config.ts
 const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cli/src/templates/configs/commit-msg/create-config.ts" });
-function createConfig$7() {
-	return `${workflowHeader$8("shebang")}${commit_msg_default}`;
+/**
+* `.husky/commit-msg` — lints the commit message via `holocron run lint
+* commit-msg` (holocron#789), the real programmatic replacement for
+* shelling out to `commitlint --edit`. Installed by `holocron repo setup` when
+* hooks are enabled. Same `__HOLOCRON_SCRIPT__` substitution as `pre-push`.
+*
+* @param holocronScript - the command that invokes the CLI. Defaults to
+*   `pnpm exec holocron`; the source repo passes `node packages/cli/dist/cli.mjs`.
+*/
+function createConfig$7(holocronScript = "pnpm exec holocron") {
+	return `${workflowHeader$8("shebang")}${commit_msg_default.replace("__HOLOCRON_SCRIPT__", holocronScript)}`;
 }
 //#endregion
 //#region src/templates/configs/devmoji/create-config.ts
@@ -4072,7 +4588,7 @@ function createConfig$6() {
 }
 //#endregion
 //#region src/templates/configs/editorconfig/editorconfig
-var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
+var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\nindent_style = unset\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
 //#endregion
 //#region src/templates/configs/editorconfig/create-config.ts
 const { workflowHeader: workflowHeader$6 } = createHeader({ source: "packages/cli/src/templates/configs/editorconfig/create-config.ts" });
@@ -4129,7 +4645,7 @@ var pre_commit_default = "# Run GitLeaks against staged changes only — a full
 const { workflowHeader: workflowHeader$5 } = createHeader({ source: "packages/cli/src/templates/configs/pre-commit/create-config.ts" });
 /**
 * `.husky/pre-commit` — runs GitLeaks (scoped to staged changes) and
-* lint-staged before every commit. Installed by `holocron setup` when hooks
+* lint-staged before every commit. Installed by `holocron repo setup` when hooks
 * are enabled (default for `protection: "strict"`). `git commit --no-verify`
 * bypasses it.
 *
@@ -4144,13 +4660,13 @@ function createConfig$3() {
 }
 //#endregion
 //#region src/templates/configs/pre-push/pre-push
-var pre_push_default = "# Run the merge-gating checks locally before pushing — the same set CI runs.\n# Bypass once with:  git push --no-verify\n\n# CI runners (semantic-release, super-linter auto-commit, bots) push without a\n# built dev environment — the hook has nothing to add there.\n[ -n \"$CI\" ] && exit 0\n\n__HOLOCRON_SCRIPT__ ci\n";
+var pre_push_default = "# Run the merge-gating checks locally before pushing — the same set CI runs.\n# Bypass once with:  git push --no-verify\n\n# CI runners (semantic-release, super-linter auto-commit, bots) push without a\n# built dev environment — the hook has nothing to add there.\n[ -n \"$CI\" ] && exit 0\n\n__HOLOCRON_SCRIPT__ run ci\n";
 //#endregion
 //#region src/templates/configs/pre-push/create-config.ts
 const { workflowHeader: workflowHeader$4 } = createHeader({ source: "packages/cli/src/templates/configs/pre-push/create-config.ts" });
 /**
-* `.husky/pre-push` — runs `holocron ci` (the merge-gating checks, in CI order)
-* before every push. Installed by `holocron setup` when hooks are enabled
+* `.husky/pre-push` — runs `holocron run ci` (the merge-gating checks, in CI order)
+* before every push. Installed by `holocron repo setup` when hooks are enabled
 * (default for `protection: "strict"`). `git push --no-verify` bypasses it.
 *
 * @param holocronScript - the command that invokes the CLI. Defaults to
@@ -4197,7 +4713,7 @@ var labeler_default = "bug:\n  - \"^fix\"\n\nchore:\n  - '^chore(?!\\(deps)'\n\n
 /**
 * Canonical AI engineering workflow role prompts.
 *
-* Written to `.agents/prompts/<role>.md` by `holocron setup` when `agent` is
+* Written to `.agents/prompts/<role>.md` by `holocron repo setup` when `agent` is
 * configured. Paths are gitignored and regenerated on every setup run so the
 * content always reflects the current CLI version.
 *
@@ -4695,7 +5211,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
 			capability: "source",
 			step,
 			status: "fail",
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 	try {
@@ -4718,7 +5234,7 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
 			capability: "source",
 			step,
 			status: "fail",
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -4811,7 +5327,7 @@ async function execStep(capability, step, dryRun, body, opts = {}) {
 			capability,
 			step,
 			status: "fail",
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -4984,7 +5500,7 @@ async function updateSkillsGitignore(gitignorePath, existingContent, skills, sym
 //#endregion
 //#region src/commands/setup/run-setup.ts
 /**
-* `holocron setup` — orchestrates per-capability setup actions across
+* `holocron repo setup` — orchestrates per-capability setup actions across
 * every plugin loaded from `holocron.config.json`.
 *
 * Per CLAUDE.md soft-skip: each step is wrapped in a try/catch and
@@ -5004,18 +5520,18 @@ async function updateSkillsGitignore(gitignorePath, existingContent, skills, sym
 */
 const { workflowHeader: workflowHeader$1 } = createHeader({
 	source: "packages/cli/src/commands/setup/run-setup.ts",
-	tool: "holocron setup"
+	tool: "holocron repo setup"
 });
 const { workflowHeader: thinCallerHeader } = createHeader({
 	source: "packages/astromech/src/thin-callers.ts",
-	tool: "holocron setup"
+	tool: "holocron repo setup"
 });
 async function runSetup(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = getLogger();
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await withSpinner("Loading plugins…", () => loader.load());
-	assertPluginsResolvable(loader, "setup");
+	assertPluginsResolvable(loader, "repo setup");
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const steps = [];
@@ -5052,7 +5568,10 @@ async function runSetup(input) {
 		print(formatStep(steps[steps.length - 1]));
 		if (effectivePreset && effectivePreset !== "none") {
 			steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
-				await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
+				await source.updateRepoSettings({
+					...BALANCED_REPO_SETTINGS,
+					...repo?.defaultBranch ? { default_branch: repo.defaultBranch } : {}
+				});
 			}));
 			print(formatStep(steps[steps.length - 1]));
 			const tasksConfig = { tasks: config.tasks };
@@ -5159,13 +5678,13 @@ async function runSetup(input) {
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .husky/commit-msg", dryRun, async () => {
-			await source.writeRepoFile(".husky/commit-msg", createConfig$7());
+			await source.writeRepoFile(".husky/commit-msg", createConfig$7(config.holocronScript));
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		if (hooksEnabled) {
 			steps.push(await runStep("source", "write .husky/pre-push", dryRun, async () => {
 				await source.writeRepoFile(".husky/pre-push", createConfig$2(config.holocronScript));
-				return "runs `holocron ci` before push — bypass with `git push --no-verify`";
+				return "runs `holocron run ci` before push — bypass with `git push --no-verify`";
 			}));
 			print(formatStep(steps[steps.length - 1]));
 			steps.push(await runStep("source", "write .husky/pre-commit", dryRun, async () => {
@@ -5233,13 +5752,20 @@ async function runSetup(input) {
 					await source.writeRepoFile("turbo.json", content);
 				}));
 				print(formatStep(steps[steps.length - 1]));
-				const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
 				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
-				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const rootScripts = rootPkg?.scripts ?? {};
 				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
 				if (workspaceFix.changed) steps.push(await runStep("source", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
 					await source.writeRepoFile("pnpm-workspace.yaml", workspaceFix.content);
 				}));
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) steps.push(await runStep("source", "add turbo devDependency", dryRun, async () => {
+						await source.writeRepoFile("package.json", depFix.content);
+					}));
+				}
 			}
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5291,34 +5817,36 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		const teams = repo?.teams ?? [];
-		if (teams.length > 0) if (source.syncTeams) {
-			steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
-			print(formatStep(steps[steps.length - 1]));
-			const repoCoord = input.context.repo ?? repo?.name ?? "";
-			const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
-			const writeableTeams = teams.map((t) => typeof t === "string" ? {
-				slug: t,
-				permission: "push"
-			} : t).filter((t) => [
-				"push",
-				"maintain",
-				"admin"
-			].includes(t.permission));
-			if (org && writeableTeams.length > 0) {
-				steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
-					const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
-					await source.writeRepoFile(".github/CODEOWNERS", content);
-				}));
+		if (teams.length > 0) {
+			if (source.syncTeams) {
+				steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
+				print(formatStep(steps[steps.length - 1]));
+				const repoCoord = input.context.repo ?? repo?.name ?? "";
+				const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
+				const writeableTeams = teams.map((t) => typeof t === "string" ? {
+					slug: t,
+					permission: "push"
+				} : t).filter((t) => [
+					"push",
+					"maintain",
+					"admin"
+				].includes(t.permission));
+				if (org && writeableTeams.length > 0) {
+					steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
+						const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
+						await source.writeRepoFile(".github/CODEOWNERS", content);
+					}));
+					print(formatStep(steps[steps.length - 1]));
+				}
+			} else {
+				steps.push({
+					capability: "source",
+					step: "sync teams",
+					status: "skip",
+					message: "provider does not implement syncTeams"
+				});
 				print(formatStep(steps[steps.length - 1]));
 			}
-		} else {
-			steps.push({
-				capability: "source",
-				step: "sync teams",
-				status: "skip",
-				message: "provider does not implement syncTeams"
-			});
-			print(formatStep(steps[steps.length - 1]));
 		}
 	}
 	if (loader.has("environments")) {
@@ -5374,11 +5902,9 @@ async function runSetup(input) {
 		const wikiProxy = wiki.proxyConfig?.();
 		if (wikiDns && loader.has("dns")) {
 			const dns = loader.get("dns");
-			steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
+			steps.push(await runStep("dns", `upsertRecord ${wikiDns.record.name}`, dryRun, async () => {
 				await dns.upsertRecord(wikiDns.zone, {
-					type: "CNAME",
-					name: wikiDns.cname,
-					content: wikiDns.target,
+					...wikiDns.record,
 					ttl: 1,
 					...wikiProxy ? { proxied: true } : {}
 				});
@@ -5387,8 +5913,8 @@ async function runSetup(input) {
 		}
 		if (wikiProxy && wikiDns && loader.has("workers")) {
 			const workers = loader.get("workers");
-			steps.push(await runStep("workers", `upsertProxy ${wikiDns.cname}`, dryRun, async () => {
-				await workers.upsertProxy(wikiDns.cname, wikiProxy);
+			steps.push(await runStep("workers", `upsertProxy ${wikiDns.record.name}`, dryRun, async () => {
+				await workers.upsertProxy(wikiDns.record.name, wikiProxy);
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5401,11 +5927,31 @@ async function runSetup(input) {
 			org: config.org,
 			domain: config.domain
 		}) : null;
+		const ensureCustomDomain = async (projectId, hostname) => {
+			if (!deploy.ensureCustomDomain) return;
+			const customDomainDns = { value: null };
+			steps.push(await runStep("deployment", `ensureCustomDomain ${hostname}`, dryRun, async () => {
+				customDomainDns.value = await deploy.ensureCustomDomain(projectId, hostname);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+			if (customDomainDns.value && loader.has("dns")) {
+				const dns = loader.get("dns");
+				const dnsRecord = customDomainDns.value;
+				steps.push(await runStep("dns", `upsertRecord ${dnsRecord.record.name}`, dryRun, async () => {
+					await dns.upsertRecord(dnsRecord.zone, {
+						...dnsRecord.record,
+						ttl: 1
+					});
+				}));
+				print(formatStep(steps[steps.length - 1]));
+			}
+		};
 		if (!previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
 				await deploy.ensureProject({ name: config.name });
 			}));
 			print(formatStep(steps[steps.length - 1]));
+			if (deploy.domain) await ensureCustomDomain(config.name, deploy.domain);
 		}
 		if (previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${previewCfg.project}`, dryRun, async () => {
@@ -5413,13 +5959,8 @@ async function runSetup(input) {
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
-		if (previewCfg?.domain && deploy.ensureCustomDomain) {
-			steps.push(await runStep("deployment", `ensureCustomDomain ${previewCfg.domain}`, dryRun, async () => {
-				await deploy.ensureCustomDomain(previewCfg.project, previewCfg.domain);
-			}));
-			print(formatStep(steps[steps.length - 1]));
-		}
-		if (previewCfg?.domain && loader.has("dns")) {
+		if (previewCfg?.domain) await ensureCustomDomain(previewCfg.project, previewCfg.domain);
+		if (previewCfg?.domain && deploy.providerName === "cloudflare" && loader.has("dns")) {
 			const dns = loader.get("dns");
 			const wildcardDomain = `*.${previewCfg.domain}`;
 			steps.push(await runStep("dns", `upsertRecord ${previewCfg.domain}`, dryRun, async () => {
@@ -5493,7 +6034,7 @@ async function runSetup(input) {
 				capability: "vault",
 				step: "list",
 				status: "fail",
-				message: err instanceof Error ? err.message : String(err)
+				message: errorMessage(err)
 			});
 		}
 		print(formatStep(steps[steps.length - 1]));
@@ -5532,6 +6073,17 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 	}
+	if (loader.has("monitoring")) {
+		const monitoring = loader.get("monitoring");
+		print(style.step("monitoring"));
+		for (const checkInput of monitoring.checks) {
+			steps.push(await runStep("monitoring", `ensureCheck ${checkInput.name}`, dryRun, async () => {
+				const result = await monitoring.ensureCheck(checkInput);
+				return `${checkInput.name} ${result.alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
 	if (loader.has("tooling")) {
 		const tools = loader.get("tooling");
 		print(style.step("tooling"));
@@ -5618,7 +6170,7 @@ async function runSetup(input) {
 		print(style.hint("       · Metadata                — read (repository permission, auto-included)"));
 		print("");
 		print(style.hint("     Create tokens at: https://github.com/settings/personal-access-tokens/new"));
-		print(style.hint("     Then re-run:      holocron setup --token <your-admin-pat>"));
+		print(style.hint("     Then re-run:      holocron repo setup --token <your-admin-pat>"));
 		print(style.hint("     Store org token:  HOLOCRON_ORG_TOKEN env var or keyring key github.org"));
 	}
 	return {
@@ -5656,7 +6208,7 @@ async function ensurePrepareScript(repoRoot) {
 /**
 * `holocron skills` — install, remove, and update agent skills from @theholocron/skills.
 *
-* Unlike `holocron setup`, this command is purely local (no GitHub token
+* Unlike `holocron repo setup`, this command is purely local (no GitHub token
 * required). It reads `agent` and `skills` from the config and installs
 * the listed skills into `.agents/skills/<name>/` with a symlink at the
 * agent-specific path (e.g. `.claude/skills/<name>` for Claude Code).
@@ -5709,7 +6261,7 @@ async function runSkillsInstall(input) {
 			status: "ok"
 		}, "skills install: done");
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+		const message = errorMessage(err);
 		print(`  ✗ ${message}`);
 		logger.warn({
 			agent: config.agent,
@@ -5867,11 +6419,13 @@ async function runSyncReadme(input) {
 	}
 	const description = loaded.resolved.description ?? "";
 	const homepage = loaded.resolved.homepage ?? pkg.homepage ?? "";
+	const scripts = pkg.scripts ?? {};
+	const packages = pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0;
 	const sections = generateReadme({
 		description,
 		homepage,
-		scripts: pkg.scripts ?? {},
-		packages: pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0
+		scripts,
+		packages
 	});
 	const markerSections = {
 		...sections.packages !== void 0 && { packages: sections.packages },
@@ -6113,7 +6667,7 @@ async function runSyncWiki(input) {
 			capability: "local",
 			step: "sync wiki",
 			status: "fail",
-			message: err instanceof Error ? err.message : 			/* c8 ignore next */ String(err)
+			message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
 		};
 	}
 }
@@ -6121,7 +6675,7 @@ async function runSyncWiki(input) {
 //#region src/commands/sync.ts
 const { workflowHeader } = createHeader({
 	source: "packages/astromech/src/thin-callers.ts",
-	tool: "holocron sync"
+	tool: "holocron repo sync"
 });
 const SYNC_STEPS = [
 	"labels",
@@ -6175,55 +6729,59 @@ async function runSync(input) {
 		for (const stepName of SYNC_STEPS) {
 			if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
 			if (LOCAL_STEPS.has(stepName)) continue;
-			if (stepName === "labels") if (source.syncLabels) {
-				steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
-				print(formatSyncStep(steps[steps.length - 1]));
-			} else {
-				steps.push({
-					capability: "source",
-					step: "sync labels",
-					status: "skip",
-					message: "provider does not implement syncLabels"
-				});
-				print(formatSyncStep(steps[steps.length - 1]));
+			if (stepName === "labels") {
+				if (source.syncLabels) {
+					steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push({
+						capability: "source",
+						step: "sync labels",
+						status: "skip",
+						message: "provider does not implement syncLabels"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
 			}
-			if (stepName === "properties") if (source.syncProperties) {
-				const repo = config.repo;
-				const properties = {};
-				const effectivePreset = repo?.protection;
-				if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
-				const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
-				properties["monorepo"] = String(isMonorepo);
-				const manual = repo?.properties ?? {};
-				if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
-				if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
-				if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
-				if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
-				{
-					const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
-					const workspacePackages = readWorkspacePackages(input.context.repoRoot);
-					const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
-					properties["holocron_profile"] = deriveProfile({
-						rootPackageJson,
-						repoName: basename(input.context.repoRoot),
-						isMonorepo,
-						workspacePackageJsons
+			if (stepName === "properties") {
+				if (source.syncProperties) {
+					const repo = config.repo;
+					const properties = {};
+					const effectivePreset = repo?.protection;
+					if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
+					const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
+					properties["monorepo"] = String(isMonorepo);
+					const manual = repo?.properties ?? {};
+					if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
+					if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
+					if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
+					if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+					{
+						const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+						const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+						const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+						properties["holocron_profile"] = deriveProfile({
+							rootPackageJson,
+							repoName: basename(input.context.repoRoot),
+							isMonorepo,
+							workspacePackageJsons
+						});
+						properties["holocron_stack"] = deriveStack(rootPackageJson);
+						const capabilities = deriveCapabilities(config.providers);
+						properties["holocron_capabilities"] = capabilities;
+						properties["holocron_compliance"] = deriveCompliance(capabilities);
+					}
+					steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push({
+						capability: "source",
+						step: "sync properties",
+						status: "skip",
+						message: "provider does not implement syncProperties"
 					});
-					properties["holocron_stack"] = deriveStack(rootPackageJson);
-					const capabilities = deriveCapabilities(config.providers);
-					properties["holocron_capabilities"] = capabilities;
-					properties["holocron_compliance"] = deriveCompliance(capabilities);
+					print(formatSyncStep(steps[steps.length - 1]));
 				}
-				steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
-				print(formatSyncStep(steps[steps.length - 1]));
-			} else {
-				steps.push({
-					capability: "source",
-					step: "sync properties",
-					status: "skip",
-					message: "provider does not implement syncProperties"
-				});
-				print(formatSyncStep(steps[steps.length - 1]));
 			}
 			if (stepName === "teams") {
 				const teams = config.repo?.teams ?? [];
@@ -6435,29 +6993,34 @@ async function runSync(input) {
 				}
 			}
 		}
-		if (stepName === "scripts") if (config.syncScripts === false) {
-			steps.push({
-				capability: "local",
-				step: "sync scripts",
-				status: "skip",
-				message: "syncScripts: false"
-			});
-			print(formatSyncStep(steps[steps.length - 1]));
-		} else {
-			const tasksConfig = { tasks: config.tasks };
-			if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
-			const desired = createAstromech({
-				cwd: input.context.repoRoot,
-				config: tasksConfig,
-				logger
-			}).packageScripts();
-			steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
-				const changed = await mergePackageJsonScripts(input.context.repoRoot, desired);
-				if (changed === null) return "no package.json";
-				if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
-				return `${changed.join(", ")} set`;
-			}));
-			print(formatSyncStep(steps[steps.length - 1]));
+		if (stepName === "scripts") {
+			if (config.syncScripts === false) {
+				steps.push({
+					capability: "local",
+					step: "sync scripts",
+					status: "skip",
+					message: "syncScripts: false"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			} else {
+				const tasksConfig = { tasks: config.tasks };
+				if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
+				const astromechScripts = createAstromech({
+					cwd: input.context.repoRoot,
+					config: tasksConfig,
+					logger
+				});
+				const desired = astromechScripts.packageScripts();
+				const turboContent = astromechScripts.turboConfig();
+				const turboEligible = new Set(turboContent ? Object.keys(JSON.parse(turboContent).tasks) : []);
+				steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
+					const changed = await mergePackageJsonScripts(input.context.repoRoot, desired, turboEligible);
+					if (changed === null) return "no package.json";
+					if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
+					return `${changed.join(", ")} set`;
+				}));
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
 		}
 		if (stepName === "turbo") {
 			const astromechTurbo = createAstromech({
@@ -6479,9 +7042,10 @@ async function runSync(input) {
 					await writeFile(join(input.context.repoRoot, "turbo.json"), content, "utf8");
 				}));
 				print(formatSyncStep(steps[steps.length - 1]));
-				const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
 				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
-				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const rootScripts = rootPkg?.scripts ?? {};
 				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
 				if (workspaceFix.changed) {
 					steps.push(await runSyncStep("local", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
@@ -6489,6 +7053,15 @@ async function runSync(input) {
 					}));
 					print(formatSyncStep(steps[steps.length - 1]));
 				}
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) {
+						steps.push(await runSyncStep("local", "add turbo devDependency", dryRun, async () => {
+							await writeFile(join(input.context.repoRoot, "package.json"), depFix.content, "utf8");
+						}));
+						print(formatSyncStep(steps[steps.length - 1]));
+					}
+				}
 			}
 		}
 		if (stepName === "wiki") {
@@ -6546,7 +7119,7 @@ async function runSyncStep(capability, step, dryRun, body) {
 			capability,
 			step,
 			status: "fail",
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -6572,8 +7145,21 @@ async function writePackageJsonField(repoRoot, field, value) {
 * Merge `desired` script entries into `package.json#scripts` — sets only the
 * listed keys, never touches the rest. Returns the sorted list of keys that
 * drifted (empty when all current), or `null` when there is no `package.json`.
+*
+* `turboEligible` (#747): task names `turbo.json` fans out — the same set
+* {@link EnsureRootWorkspaceMemberResult} above already keys off. For those
+* only, an *existing* script that isn't the generated `holocron run <task>
+* --` wrapper is left untouched: root may genuinely be a directly-buildable
+* package (not an orchestrator) with its own real command (`tsc --noEmit`,
+* `vitest run`, …) for that task. Overwriting it would silently discard the
+* real command and, once `turbo.json` exists and root is a real workspace
+* member (#692), reintroduce infinite recursion — `turbo run <task>` →
+* root's own `<task>` script → the wrapper → `holocron run <task>` sees
+* `turbo.json` still defines the task → `turbo run <task>` again, forever.
+* Every other key (non-turbo tasks, `holocron`, `prepare`, …) has no
+* legitimate direct-command alternative and stays fully generator-owned.
 */
-async function mergePackageJsonScripts(repoRoot, desired) {
+async function mergePackageJsonScripts(repoRoot, desired, turboEligible) {
 	const pkgPath = join(repoRoot, "package.json");
 	let content;
 	try {
@@ -6584,15 +7170,31 @@ async function mergePackageJsonScripts(repoRoot, desired) {
 	const pkg = JSON.parse(content);
 	const scripts = pkg.scripts ?? {};
 	const changed = [];
-	for (const [name, command] of Object.entries(desired)) if (scripts[name] !== command) {
-		scripts[name] = command;
-		changed.push(name);
+	for (const [name, command] of Object.entries(desired)) {
+		const existing = scripts[name];
+		if (turboEligible.has(name) && existing !== void 0 && !isGeneratedRunWrapper(existing, name)) continue;
+		if (existing !== command) {
+			scripts[name] = command;
+			changed.push(name);
+		}
 	}
 	if (changed.length === 0) return [];
 	pkg.scripts = scripts;
 	await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
 	return changed.sort();
 }
+/**
+* Matches the exact shape `packageScripts()` generates for `taskName` —
+* `<bin> run <taskName> --`, `<bin>` normally `holocron` but substitutable
+* (`holocronScript`, itself allowed to be multi-word, e.g. `"node
+packages/cli/dist/cli.mjs"` — see its own test). Checking the *suffix*
+* rather than the whole string means an old wrapper survives a
+* `holocronScript` rename intact — it's still recognized as a wrapper (safe
+* to update to the new one), not mistaken for a real command.
+*/
+function isGeneratedRunWrapper(command, taskName) {
+	return command.endsWith(` run ${taskName} --`);
+}
 const README_DESC_START = "<!-- holocron:description -->";
 const README_DESC_END = "<!-- /holocron:description -->";
 async function updateReadmeDescription(repoRoot, description) {
@@ -6809,7 +7411,7 @@ const DEFAULT_REPO = "theholocron/.github";
 * The file set `sync-github` pushes to `theholocron/.github` — the reusable
 * `workflow_call` implementations, composite actions and starter-workflow
 * metadata, generated by `@theholocron/astromech`. Secondary repos get nothing:
-* their thin callers are managed by `holocron sync --steps workflows`, which
+* their thin callers are managed by `holocron repo sync --steps workflows`, which
 * executes the resolved config (regex parsing here can't resolve preset spreads
 * like `...tasks` from `nodeDocs()` — see issue #464).
 */
@@ -6835,7 +7437,7 @@ async function runSyncGithub(input) {
 		token,
 		fetch: input.fetch
 	});
-	print(`holocron sync-github${dryRun ? " (dry-run)" : ""}`);
+	print(`holocron sync github${dryRun ? " (dry-run)" : ""}`);
 	print(`  repo:   ${repo}`);
 	if (branch) print(`  branch: ${branch}`);
 	print("");
@@ -6964,7 +7566,7 @@ async function runSyncGithub(input) {
 			sha: blob.sha
 		});
 	} catch (err) {
-		const msg = `failed to create blob for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
+		const msg = `failed to create blob for ${file.path}: ${errorMessage(err)}`;
 		print(`  ✗ ${msg}`);
 		return done({
 			status: "fail",
@@ -6978,7 +7580,7 @@ async function runSyncGithub(input) {
 	try {
 		newTreeSha = (await client.git.createTree(repo, treeEntries, baseTreeSha)).sha;
 	} catch (err) {
-		const msg = `failed to create tree: ${err instanceof Error ? err.message : String(err)}`;
+		const msg = `failed to create tree: ${errorMessage(err)}`;
 		print(`  ✗ ${msg}`);
 		return done({
 			status: "fail",
@@ -6992,7 +7594,7 @@ async function runSyncGithub(input) {
 	try {
 		newCommitSha = (await client.git.createCommit(repo, message, newTreeSha, [headSha])).sha;
 	} catch (err) {
-		const msg = `failed to create commit: ${err instanceof Error ? err.message : String(err)}`;
+		const msg = `failed to create commit: ${errorMessage(err)}`;
 		print(`  ✗ ${msg}`);
 		return done({
 			status: "fail",
@@ -7011,7 +7613,7 @@ async function runSyncGithub(input) {
 		}
 		else await client.git.updateRef(repo, `heads/${targetBranch}`, newCommitSha);
 	} catch (err) {
-		const msg = `failed to update ref: ${err instanceof Error ? err.message : String(err)}`;
+		const msg = `failed to update ref: ${errorMessage(err)}`;
 		print(`  ✗ ${msg}`);
 		return done({
 			status: "fail",
@@ -7027,12 +7629,12 @@ async function runSyncGithub(input) {
 			title: message.split("\n")[0],
 			head: branch,
 			base: "main",
-			body: "Auto-generated by `holocron sync-github`. Review and merge to apply template updates."
+			body: "Auto-generated by `holocron sync github`. Review and merge to apply template updates."
 		})).html_url;
 		print(`  → PR opened: ${prUrl}`);
 	} catch (err) {
 		if (err instanceof ProviderApiError && err.status === 422 && String(err.details).includes("already exists")) print(`  → PR already open for ${branch} — branch updated, ready to merge`);
-		else print(`  ⚠ PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+		else print(`  ⚠ PR creation failed: ${errorMessage(err)}`);
 	}
 	return done({
 		status: "ok",
@@ -7045,7 +7647,7 @@ async function runSyncGithub(input) {
 //#endregion
 //#region src/commands/upgrade-deps.ts
 /**
-* `holocron upgrade deps` — bring a repo's `@theholocron/*` dependency pins and
+* `holocron repo upgrade deps` — bring a repo's `@theholocron/*` dependency pins and
 * its `holocron.config.ts` up to the current major.
 *
 * Two concerns:
@@ -7060,7 +7662,7 @@ async function runSyncGithub(input) {
 *    This applies the mechanical transforms and flags anything that needs a
 *    human eye.
 *
-* After running, `pnpm install && holocron ci`.
+* After running, `pnpm install && holocron run ci`.
 */
 const FETCH_TIMEOUT_MS$1 = 4e3;
 /** Resolve a package's `latest` dist-tag from the npm registry. */
@@ -7127,7 +7729,7 @@ function isLegacyConfig(content) {
 }
 /**
 * Apply the mechanical 7.x → 8.x transforms to a `holocron.config.ts`. Best
-* effort — the result should always be reviewed and run through `holocron ci`.
+* effort — the result should always be reviewed and run through `holocron run ci`.
 */
 function migrateConfig(content) {
 	const transforms = [];
@@ -7253,7 +7855,7 @@ async function runUpgradeDeps(input = {}) {
 	print("");
 	if (bumps.length === 0 && !configMigrated) print("Nothing to do — already up to date.");
 	else {
-		print(`Next: ${dryRun ? "run without --dry-run, then " : ""}\`pnpm install && holocron ci\``);
+		print(`Next: ${dryRun ? "run without --dry-run, then " : ""}\`pnpm install && holocron run ci\``);
 		if (configMigrated) print("      review holocron.config.ts before committing.");
 	}
 	const status = dryRun ? "dry-run" : "ok";
@@ -7459,6 +8061,63 @@ async function runUpgradeNode(input) {
 	};
 }
 //#endregion
+//#region src/commit-lint/lint-message.ts
+/**
+* Lints one commit message string against an already-loaded commitlint
+* config. The genuinely environment-independent half of commit-message
+* linting (holocron#789) — *obtaining* a `QualifiedConfig` differs by
+* caller (Sentinel isolates itself from any ambient config since it runs
+* standalone, away from a real repo checkout; `lintCommitMsgFile` below
+* just lets cosmiconfig discover the invoking repo's own
+* `commitlint.config.*`, matching `commitlint --edit`'s own contract) —
+* but linting one message against a loaded config is identical either way.
+*
+* Real `@commitlint/lint` — the same programmatic API `@commitlint/cli`
+* itself uses internally — never a reimplementation of commitlint's rules.
+*/
+/** `parserPreset.parserOpts`, if the loaded config sets one — same lookup `@commitlint/cli`'s own `selectParserOpts()` does. */
+function selectParserOpts(parserPreset) {
+	return parserPreset?.parserOpts;
+}
+async function lintCommitMessage(message, loaded) {
+	const opts = {
+		/* istanbul ignore next -- see comment above */
+		parserOpts: selectParserOpts(loaded.parserPreset) ?? {},
+		plugins: loaded.plugins,
+		/* istanbul ignore next -- see comment above */
+		ignores: loaded.ignores ?? [],
+		defaultIgnores: loaded.defaultIgnores !== false
+	};
+	const outcome = await lint(message, loaded.rules, opts);
+	if (outcome.valid) return [];
+	return outcome.errors.map((error) => ({
+		rule: error.name,
+		message: error.message
+	}));
+}
+//#endregion
+//#region src/commit-lint/lint-commit-msg-file.ts
+/**
+* `holocron run lint commit-msg <file>` — a real programmatic replacement for
+* shelling out to `commitlint --edit "$1"` from `.husky/commit-msg`
+* (holocron#789). Matches that CLI's own contract exactly: `file` is a
+* path to the commit message being written (the arg git's `commit-msg`
+* hook passes as `$1`), no `--config` override needed — `@commitlint/load`
+* runs from `cwd` with no seed, so cosmiconfig's own normal upward search
+* discovers the invoking repo's real `commitlint.config.*` file, exactly
+* as `commitlint --edit` (no `--config` flag) already does today. Unlike
+* Sentinel's `loadIsolatedConfig()`, no isolation is needed here — this
+* runs inside a real repo checkout with a real `node_modules`, not
+* standalone on a server.
+*/
+async function lintCommitMsgFile(filePath, cwd = process.cwd()) {
+	const violations = await lintCommitMessage(await readFile(filePath, "utf8"), await load({}, { cwd }));
+	return {
+		valid: violations.length === 0,
+		violations
+	};
+}
+//#endregion
 //#region src/config/load-config.ts
 /**
 * `holocron.config.{ts,js,mjs,cjs,json}` loader.
@@ -7473,14 +8132,19 @@ async function runUpgradeNode(input) {
 */
 const execFileAsync = promisify(execFile);
 /**
-* Read + parse + resolve `holocron.config.*` from the given directory.
+* Read + parse + resolve `holocron.config.*` starting from the given
+* directory, walking up through ancestors to the nearest `.git` boundary
+* when `cwd` itself has no match — every command is usable from any
+* subdirectory of a repo, not only its exact root (see
+* `@theholocron/datapad`'s own doc comment for the stop conditions).
 * Throws {@link ConfigFileError} when nothing is found or a file cannot
-* be loaded, or `ConfigError` when the config is invalid.
+* be loaded, or `ConfigError` when the config fails schema checks.
 */
 async function loadConfig(cwd) {
 	const found = await loadConfigFile({
 		cwd,
-		name: "holocron"
+		name: "holocron",
+		walkUp: true
 	});
 	if (!found) throw new ConfigFileError(`no holocron.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
 	return {
@@ -7553,6 +8217,15 @@ function parseGitRemoteUrl(url) {
 * {@link promptForPositionals} for just that one command — no spawn needed,
 * the handler already has everything else it needs.
 *
+* For a command whose handler honours `--dry-run` ({@link
+* CommandEntry.supportsDryRun}), `launchMenu` always previews it first — a
+* dry run doesn't mutate anything, so there's nothing to ask permission
+* for — then, once that preview comes back clean and found something to
+* do, asks the one real decision: "proceed with the real run?". A preview
+* that finds nothing to do skips that question too. `--skip-dry-run` opts
+* a top-level invocation out of the preview entirely, straight to the
+* real run, for when you already know what you want.
+*
 * Every prompt is preceded by a `process.stdin.isTTY` check. A non-TTY run
 * (CI, a script, a pipe) throws {@link NonInteractiveError} instead of
 * hanging on `@inquirer/prompts` (which otherwise throws its own
@@ -7566,40 +8239,153 @@ var NonInteractiveError = class extends Error {
 };
 const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
 /**
+* This repo's own resolved task manifest, filtered to what's actually
+* runnable locally — `Astromech.runnableTasks()`, reused rather than
+* reimplemented (deliberately *not* `packageScripts()`, whose
+* `syncScripts: false` short-circuit returns `{}` for repos — this one
+* included — that opt out of generated `package.json` scripts but still
+* have real runnable tasks). Empty (never throws) when there's no config to
+* resolve — feeds {@link buildRunMenuEntries}, which renders an empty list
+* as "run ›" simply having no children.
+*/
+async function listRunnableTasks(argv) {
+	const cwd = typeof argv.cwd === "string" ? argv.cwd : process.cwd();
+	const config = await loadTasksConfig(cwd).catch(() => void 0);
+	return createAstromech({
+		cwd,
+		config
+	}).runnableTasks();
+}
+/**
+* Namespace display order for the `run` menu — deliberately its own thing,
+* not `@theholocron/astromech`'s `CI_ORDER`: that one is tuned for "cheapest
+* signal first" in an automated gate, a different goal from "how a person
+* would naturally work through a repo" (build it, clean up its style, check
+* it's secure, test it, validate it, document it). A namespace absent here
+* (a repo-specific one this list doesn't know about) sorts after every
+* named one, in whatever order it was first seen.
+*/
+const RUN_MENU_NAMESPACE_ORDER = [
+	"delivery",
+	"sourceQuality",
+	"security",
+	"verification",
+	"platform",
+	"knowledge"
+];
+/**
+* Splits `taskNames` (`"sourceQuality.staticAnalysis"`, …) into namespace
+* groups, ordered by {@link RUN_MENU_NAMESPACE_ORDER} — insertion order
+* within each group is `taskNames`' own order (already declaration order,
+* from {@link listRunnableTasks}). A name with no `.` at all (defensive;
+* every real registry task has a namespace) is its own bucket, keyed by the
+* full name, sorted after every namespaced group.
+*/
+function groupByNamespace(taskNames) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const name of taskNames) {
+		const dot = name.indexOf(".");
+		const key = dot === -1 ? name : name.slice(0, dot);
+		const list = groups.get(key);
+		if (list) list.push(name);
+		else groups.set(key, [name]);
+	}
+	const ordered = /* @__PURE__ */ new Map();
+	const byMenuOrder = (a, b) => {
+		const ia = RUN_MENU_NAMESPACE_ORDER.indexOf(a);
+		const ib = RUN_MENU_NAMESPACE_ORDER.indexOf(b);
+		if (ia !== -1 || ib !== -1) return (ia === -1 ? Infinity : ia) - (ib === -1 ? Infinity : ib);
+		return 0;
+	};
+	for (const key of [...groups.keys()].sort(byMenuOrder)) ordered.set(key, groups.get(key));
+	return ordered;
+}
+/**
+* Dynamically-built `run` sub-entries for every locally-runnable task
+* ({@link listRunnableTasks}), grouped by namespace and merged into
+* `COMMAND_REGISTRY` at `cli.ts`'s `$0` call site — not a registry entry
+* itself, since the task set is per-repo, not a static surface this module
+* can hand-enumerate.
+*
+* Each namespace becomes a group with a leading "<namespace> (run it)" item
+* (`holocron run <namespace>` — every task in it, via
+* `Astromech.runGroup()`) alongside each of its individual tasks, the exact
+* same "a group that's also runnable" shape `menuItems` already renders for
+* `repo sync` / `deploy` — reached here for free by using a space, not the
+* task's own `.`, between namespace and leaf in `name` (`spawnArgs` carries
+* the real dotted invocation `buildChildArgv` actually spawns).
+*/
+function buildRunMenuEntries(taskNames) {
+	const entries = [];
+	for (const [namespace, tasks] of groupByNamespace(taskNames)) {
+		const isRealNamespace = tasks[0] !== namespace || tasks.length > 1;
+		if (isRealNamespace) entries.push({
+			name: `run ${namespace}`,
+			description: `Run every ${namespace}.* task in sequence`,
+			positionals: [],
+			supportsDryRun: true,
+			spawnArgs: ["run", namespace]
+		});
+		for (const task of tasks) {
+			const leaf = task === namespace ? namespace : task.slice(namespace.length + 1);
+			entries.push({
+				name: isRealNamespace ? `run ${namespace} ${leaf}` : `run ${leaf}`,
+				description: `Run ${task}`,
+				positionals: [],
+				supportsDryRun: true,
+				spawnArgs: ["run", task]
+			});
+		}
+	}
+	return entries;
+}
+/**
 * The full command surface, hand-maintained in parallel with `cli.ts`'s
 * yargs registrations (this module does not introspect yargs at runtime).
-* `run <task>` is deliberately excluded — it's CI/scripting-oriented, and an
-* interactive prompt in front of it would work against that.
+* `run <task>` has no entry here at all — `cli.ts`'s `$0` handler merges in
+* {@link buildRunMenuEntries}'s dynamically-built ones instead, since the
+* task namespace is this repo's own resolved manifest, not a static set
+* this module can hand-enumerate the way every other entry's positionals
+* are. `job` and `passthrough` stay un-prompted either way; picking a task
+* and running it plain covers the common case, and typing
+* `holocron run <task> <job> -- <args>` directly is one step away for
+* everything else. `run lint commit-msg <file>` stays excluded entirely:
+* it's invoked exclusively from `.husky/commit-msg "$1"`, never typed by a
+* human.
 */
 const COMMAND_REGISTRY = [
-	{
-		name: "version",
-		description: "Print the CLI version",
-		positionals: []
-	},
 	{
 		name: "clone",
-		description: "Clone all repos in a GitHub org as siblings under a single directory",
-		positionals: []
+		description: "Clone a single repo (org/repo) or every repo in an org (org)",
+		positionals: [{
+			key: "target",
+			message: "org/repo to clone (or a bare org to clone every repo in it):",
+			type: "input",
+			validate: (v) => v.trim().length > 0 || "org/repo or org is required"
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "doctor",
 		description: "Load the config and run a smoke check against every provider",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "setup",
+		name: "repo setup",
 		description: "Apply infra setup actions across every configured capability",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "secret set",
+		name: "secrets set",
 		description: "Set a single secret via the configured `secrets` capability",
 		positionals: [{
 			key: "name",
 			message: "Secret name:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "secrets sync",
@@ -7608,7 +8394,8 @@ const COMMAND_REGISTRY = [
 			key: "environmentId",
 			message: "Vault environment id:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "deploy",
@@ -7617,52 +8404,66 @@ const COMMAND_REGISTRY = [
 			key: "branch",
 			message: "Branch to deploy:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
-		name: "cleanup-preview",
+		name: "deploy cleanup-preview",
 		description: "List and delete Cloudflare Pages preview deployments for a GitHub PR",
 		positionals: [{
 			key: "pr",
 			message: "PR number:",
 			type: "input",
 			validate: numeric
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
-		name: "bump-versions",
+		name: "deploy on-release",
+		description: "Deploy every workspace package whose delivery.deploy task is `on: release`",
+		positionals: [],
+		supportsDryRun: true
+	},
+	{
+		name: "package bump-versions",
 		description: "Bump all non-private package versions in lockstep (semantic-release prepareCmd)",
 		positionals: [{
 			key: "newVersion",
 			cliArg: "new-version",
 			message: "New version:",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
-		name: "publish",
+		name: "package publish",
 		description: "Publish @theholocron/* packages to npm",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "sync",
+		name: "repo sync",
 		description: "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "ci",
+		name: "run ci",
 		description: "Run the merge-gating checks locally, in CI order — 'will CI pass?'",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "sync-github",
+		name: "sync github",
 		description: "Sync workflow templates and composite actions to theholocron/.github",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "sync-readme",
+		name: "repo sync readme",
 		description: "Sync the Installation + Usage block in README.md from package.json",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
 		name: "config show",
@@ -7670,12 +8471,13 @@ const COMMAND_REGISTRY = [
 		positionals: []
 	},
 	{
-		name: "new",
+		name: "new repo",
 		description: "Scaffold a new repo from a GitHub template (e.g. cli, react, nextjs, node, monorepo, base)",
-		positionals: []
+		positionals: [],
+		supportsDryRun: true
 	},
 	{
-		name: "plugin create",
+		name: "new plugin",
 		description: "Scaffold a new @theholocron/holocron-plugin-<slug> package",
 		positionals: [{
 			key: "slug",
@@ -7685,28 +8487,29 @@ const COMMAND_REGISTRY = [
 			key: "vendor",
 			message: "Vendor display name (PascalCase):",
 			type: "input"
-		}]
+		}],
+		supportsDryRun: true
 	},
 	{
 		name: "skills install",
 		description: "Copy skills from @theholocron/skills into .agents/ with agent symlinks",
 		positionals: [],
-		group: "skills"
+		supportsDryRun: true
 	},
 	{
 		name: "skills remove",
 		description: "Remove installed skills via npx skills remove",
 		positionals: [],
-		group: "skills"
+		supportsDryRun: true
 	},
 	{
 		name: "skills update",
 		description: "Update installed skills to their latest upstream versions via npx skills update",
 		positionals: [],
-		group: "skills"
+		supportsDryRun: true
 	},
 	{
-		name: "upgrade node",
+		name: "repo upgrade node",
 		description: "Scan the repo and update every Node.js version pin to a new major",
 		positionals: [{
 			key: "to",
@@ -7714,13 +8517,13 @@ const COMMAND_REGISTRY = [
 			type: "input",
 			validate: numeric
 		}],
-		group: "upgrade"
+		supportsDryRun: true
 	},
 	{
-		name: "upgrade deps",
+		name: "repo upgrade deps",
 		description: "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API",
 		positionals: [],
-		group: "upgrade"
+		supportsDryRun: true
 	},
 	{
 		name: "auth set",
@@ -7729,8 +8532,7 @@ const COMMAND_REGISTRY = [
 			key: "provider",
 			message: "Provider name:",
 			type: "input"
-		}],
-		group: "auth"
+		}]
 	},
 	{
 		name: "auth unset",
@@ -7740,8 +8542,7 @@ const COMMAND_REGISTRY = [
 			message: "Provider:",
 			type: "select",
 			choices: listStoredProviders
-		}],
-		group: "auth"
+		}]
 	},
 	{
 		name: "auth check",
@@ -7751,14 +8552,12 @@ const COMMAND_REGISTRY = [
 			message: "Provider:",
 			type: "select",
 			choices: listStoredProviders
-		}],
-		group: "auth"
+		}]
 	},
 	{
 		name: "auth list",
 		description: "List every provider with a stored bootstrap token",
-		positionals: [],
-		group: "auth"
+		positionals: []
 	}
 ];
 /** Look up a {@link CommandEntry} by its full name — for Layer 3 call sites in `cli.ts`. */
@@ -7767,36 +8566,89 @@ function getEntry(name) {
 	if (!entry) throw new Error(`interactive-menu: no COMMAND_REGISTRY entry named "${name}"`);
 	return entry;
 }
+const GROUP = "group:";
+/** The "← back" item's value; only offered below the first level. */
+const BACK = "back";
+/**
+* One level of the menu, derived from the registered command names: the next word
+* of every entry under `path` (`[]` is the top). A word is
+*
+* - a **command** when nothing is nested under it (`doctor`);
+* - a **group** when commands are nested under it (`repo` → `repo setup`, `repo sync`, …),
+*   which can nest as deep as the names go (`repo upgrade` → `repo upgrade node`);
+*
+* Every row is a single word, never a "<command> <subcommand>" path: `config show` is
+* `config ›` then `show`, even when a group holds just one command.
+*
+* A path that is itself runnable (`repo sync`, `deploy`) gets a leading "<word> (run it)" item.
+* Registration order is kept.
+*/
+function menuItems(entries, path = []) {
+	const prefix = path.join(" ");
+	const own = prefix ? entries.find((e) => e.name === prefix) : void 0;
+	const under = prefix ? entries.filter((e) => e.name.startsWith(`${prefix} `)) : entries;
+	const haystackOf = (list) => list.map((e) => `${e.name} ${e.description}`.toLowerCase()).join(" ");
+	const items = [];
+	if (own) items.push({
+		name: `${path[path.length - 1]} (run it)`,
+		value: own.name,
+		description: own.description,
+		haystack: haystackOf([own])
+	});
+	const words = [...new Set(under.map((e) => e.name.split(" ")[path.length]))];
+	for (const word of words) {
+		const full = [...path, word].join(" ");
+		const family = under.filter((e) => e.name === full || e.name.startsWith(`${full} `));
+		const self = family.find((e) => e.name === full);
+		const nested = family.filter((e) => e.name !== full);
+		if (nested.length === 0 && self) items.push({
+			name: word,
+			value: full,
+			description: self.description,
+			haystack: haystackOf([self])
+		});
+		else {
+			const children = [...new Set(nested.map((e) => e.name.split(" ")[path.length + 1]))];
+			items.push({
+				name: `${word} ›`,
+				value: `${GROUP}${full}`,
+				description: children.join(", "),
+				haystack: haystackOf(family)
+			});
+		}
+	}
+	return items;
+}
 /**
-* Searchable autocomplete over `entries` — the Layer 1 top-level picker, and
-* (passed a `group`-filtered subset) the Layer 2 parent-command picker.
-* `select()` would work too at these list sizes, but `search()` degrades
-* gracefully as the surface grows and costs nothing when it doesn't.
+* Searchable autocomplete over one menu level's `items`. `select()` would work too
+* at these list sizes, but `search()` degrades gracefully as the surface grows and
+* costs nothing when it doesn't. Resolves to the picked item's `value`.
 */
-async function pickCommand(entries, message = "What would you like to do?") {
-	const byName = new Map(entries.map((e) => [e.name, e]));
-	const picked = await search({
+async function pickMenuItem(items, message = "What would you like to do?") {
+	return search({
 		message,
-		source: (term) => searchChoices(entries, term)
+		source: (term) => searchChoices(items, term)
 	});
-	return byName.get(picked);
 }
 /**
 * `@inquirer/search`'s `source` callback, factored out as a plain function —
 * unit-testable directly instead of only through a mocked `search()` call.
-* Empty/undefined `term` (nothing typed yet) returns every entry.
+* Empty/undefined `term` (nothing typed yet) returns every item.
 */
-function searchChoices(entries, term) {
-	return (!term ? entries : entries.filter((e) => matches(e, term))).map((e) => ({
-		name: e.name,
-		value: e.name,
-		description: e.description
+function searchChoices(items, term) {
+	const needle = term?.toLowerCase();
+	const pool = !needle ? items : items.filter((i) => i.haystack.includes(needle));
+	const rank = (i) => {
+		if (!needle) return 0;
+		const name = i.name.toLowerCase();
+		return name.startsWith(needle) ? 0 : name.includes(needle) ? 1 : 2;
+	};
+	return [...pool].sort((a, b) => rank(a) - rank(b)).map((i) => ({
+		name: i.name,
+		value: i.value,
+		description: i.description
 	}));
 }
-function matches(entry, term) {
-	const needle = term.toLowerCase();
-	return entry.name.toLowerCase().includes(needle) || entry.description.toLowerCase().includes(needle);
-}
 /**
 * For each of `entry.positionals` not already present in `argv`, prompts for
 * it (`input()` or `select()`, per the positional's `type`) and returns the
@@ -7835,74 +8687,422 @@ async function promptForPositionals(entry, argv) {
 * menu-launched child should inherit from the parent invocation. Everything
 * else (command-specific options) was never captured by the top-level `$0`
 * handler in the first place, so there's nothing else to forward.
+*
+* `dryRunOverride`, when passed, wins over `argv.dryRun` — `launchMenu`'s
+* dry-run offer needs to force `--dry-run` on for the preview spawn and
+* force it back off for the real-run spawn that follows, regardless of
+* what was on the original invocation.
 */
-function forwardedFlags(argv) {
+function forwardedFlags(argv, dryRunOverride) {
 	const out = [];
 	const tokens = argv.token;
 	for (const t of tokens ?? []) out.push("--token", t);
 	if (typeof argv.org === "string") out.push("--org", argv.org);
 	if (typeof argv.cwd === "string") out.push("--cwd", argv.cwd);
-	if (argv.dryRun === true) out.push("--dry-run");
+	if (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
 	return out;
 }
-/** `entry.name` split into tokens, resolved positionals appended, then forwarded flags. */
-function buildChildArgv(entry, positionals, parentArgv) {
+/** `entry.spawnArgs` if set, else `entry.name` split into tokens — resolved positionals appended, then forwarded flags. */
+function buildChildArgv(entry, positionals, parentArgv, dryRunOverride) {
 	return [
-		...entry.name.split(" "),
+		...entry.spawnArgs ?? entry.name.split(" "),
 		...positionals,
-		...forwardedFlags(parentArgv)
+		...forwardedFlags(parentArgv, dryRunOverride)
 	];
 }
-/** Spawn `holocron <...args>` inheriting stdio; resolve with its exit code. */
-function spawnChild(args) {
+/**
+* Set on a dry-run preview child's env ({@link spawnChild}'s `extraEnv`) so
+* its handler knows this specific `--dry-run` came from `launchMenu`'s own
+* preview-then-ask flow, not a direct `holocron <cmd> --dry-run` invocation.
+* A handler that supports it uses this — never bare `argv.dryRun` — to
+* decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code
+* only has special meaning to `launchMenu` itself, so a direct/scripted
+* `--dry-run` call must never produce it — doing so unconditionally would
+* silently change the public exit-code contract for a successful dry run.
+*/
+const DRY_RUN_PREVIEW_ENV_VAR = "HOLOCRON_DRY_RUN_PREVIEW";
+/**
+* Spawn `holocron <...args>` inheriting stdio; resolve with its exit code.
+*
+* `NO_UPDATE_NOTIFIER` is forced on in the child's env — the parent's own
+* update-notifier tail still runs after this resolves (see `launchMenu`'s
+* docstring), so without this the freshly-spawned child independently runs
+* its own `checkForUpdates()` too and the notice prints twice: once from
+* the child right after its command output, once more from the parent
+* once the child exits. `extraEnv` layers on top — used only for {@link
+* DRY_RUN_PREVIEW_ENV_VAR} on the dry-run preview spawn.
+*/
+function spawnChild(args, extraEnv) {
 	return new Promise((resolve) => {
-		const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: "inherit" });
+		const child = spawn(process.execPath, [process.argv[1], ...args], {
+			stdio: "inherit",
+			env: {
+				...process.env,
+				NO_UPDATE_NOTIFIER: "1",
+				...extraEnv
+			}
+		});
 		child.on("exit", (code) => resolve(code ?? 0));
 		child.on("error", () => resolve(1));
 	});
 }
 /**
-* Layers 1 and 2: pick a command from `entries`, prompt for its required
-* positionals, spawn it as a fresh `holocron` invocation, and set
-* `process.exitCode` from the child — the caller (a `$0` handler in
-* `cli.ts`) returns normally afterward so the parent's own telemetry
-* flush / update-notifier tail still runs. The parent's own
-* `command_completed` event fires with command name "unknown" (the
-* middleware ran before any command was picked) — left as-is rather than
-* suppressed; it's a real, useful signal ("the menu got used").
+* Whether `launchMenu` should auto-preview a picked command before running
+* it for real — only when the command's handler actually honours
+* `--dry-run` ({@link CommandEntry.supportsDryRun}) and the top-level
+* invocation didn't pass `--skip-dry-run` to opt out of the preview
+* entirely (an escape hatch for "I already know what I want, skip
+* straight to the real run").
+*/
+function shouldPreviewDryRun(entry, parentArgv) {
+	return Boolean(entry.supportsDryRun) && parentArgv.skipDryRun !== true;
+}
+/**
+* Layers 1 and 2: walk the nested menu over `entries` (starting at `startPath`,
+* `[]` for the top), prompt for the picked command's required positionals, spawn
+* it as a fresh `holocron` invocation, and set `process.exitCode` from the child —
+* the caller (a `$0` handler in `cli.ts`) returns normally afterward so the
+* parent's own telemetry flush / update-notifier tail still runs. The parent's
+* own `command_completed` event fires with command name "unknown" (the middleware
+* ran before any command was picked) — left as-is rather than suppressed; it's a
+* real, useful signal ("the menu got used").
+*
+* Picking a group opens its submenu, which has a "← back" item; a command ends
+* the walk. See {@link menuItems} for how a level is built.
+*
+* For a command that honours `--dry-run` ({@link CommandEntry.supportsDryRun})
+* and wasn't opted out via `--skip-dry-run` ({@link shouldPreviewDryRun}),
+* this always previews first — a dry run doesn't mutate anything, so
+* there's nothing to ask permission for. A preview that exits non-zero
+* stops here; one that reports {@link DRY_RUN_NOOP_EXIT_CODE} (nothing
+* would change) stops here too, skipping the follow-up question since the
+* real run would have nothing to do either. Otherwise it asks "proceed
+* with the real run?" before the real spawn — the one actual decision
+* left to make, since this one does mutate something.
 */
-async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessage = "Run `holocron --help` to see available commands.") {
+async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessage = "Run `holocron --help` to see available commands.", startPath = []) {
 	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
-	const picked = await pickCommand(entries, pickMessage);
-	const childArgv = buildChildArgv(picked, await promptForPositionals(picked, {}), parentArgv);
-	process.exitCode = await spawnChild(childArgv);
+	const stack = [startPath];
+	let picked;
+	while (!picked) {
+		const path = stack[stack.length - 1];
+		const items = menuItems(entries, path);
+		if (stack.length > 1) items.push({
+			name: "← back",
+			value: BACK,
+			description: "Return to the previous menu",
+			haystack: "back"
+		});
+		const value = await pickMenuItem(items, stack.length === 1 ? pickMessage : `${path.join(" ")} — choose a subcommand:`);
+		if (value === "back") stack.pop();
+		else if (value.startsWith(GROUP)) stack.push(value.slice(6).split(" "));
+		else picked = entries.find((e) => e.name === value);
+	}
+	const positionals = await promptForPositionals(picked, {});
+	if (shouldPreviewDryRun(picked, parentArgv)) {
+		const dryExit = await spawnChild(buildChildArgv(picked, positionals, parentArgv, true), { [DRY_RUN_PREVIEW_ENV_VAR]: "1" });
+		if (dryExit === 2) {
+			process.exitCode = 0;
+			return;
+		}
+		if (dryExit !== 0) {
+			process.exitCode = dryExit;
+			return;
+		}
+		if (!await confirm({
+			message: "Dry run complete — proceed with the real run?",
+			default: false
+		})) {
+			process.exitCode = 0;
+			return;
+		}
+		process.exitCode = await spawnChild(buildChildArgv(picked, positionals, parentArgv, false));
+		return;
+	}
+	process.exitCode = await spawnChild(buildChildArgv(picked, positionals, parentArgv));
 }
 //#endregion
-//#region src/update-notifier.ts
-const PACKAGE_NAME = "@theholocron/cli";
-const CACHE_TTL_MS = 1440 * 60 * 1e3;
-const FETCH_TIMEOUT_MS = 3e3;
-function getCacheDir() {
-	return env.get("HOLOCRON_CACHE_DIR") ?? join(homedir(), ".cache", "holocron");
+//#region src/ui/json-view.ts
+function isContainer(value) {
+	return typeof value === "object" && value !== null;
 }
-function getCachePath() {
-	return join(getCacheDir(), "update-check.json");
+function childrenOf(value) {
+	return Array.isArray(value) ? value.map((v, i) => [String(i), v]) : Object.entries(value);
 }
-function readCache() {
-	try {
-		return JSON.parse(readFileSync(getCachePath(), "utf8"));
-	} catch {
-		return null;
-	}
+function scalar(value) {
+	if (typeof value === "string") return chalk.green(JSON.stringify(value));
+	if (typeof value === "number") return chalk.yellow(String(value));
+	if (typeof value === "boolean") return chalk.magenta(String(value));
+	return chalk.dim(String(value === void 0 ? null : value));
 }
-function writeCache(entry) {
-	try {
-		mkdirSync(getCacheDir(), { recursive: true });
-		writeFileSync(getCachePath(), JSON.stringify(entry));
-	} catch {}
+function summary(value) {
+	const n = childrenOf(value).length;
+	const unit = Array.isArray(value) ? n === 1 ? "item" : "items" : n === 1 ? "key" : "keys";
+	return chalk.dim(Array.isArray(value) ? `[… ${n} ${unit}]` : `{… ${n} ${unit}}`);
 }
-async function fetchLatestVersion(channel) {
-	try {
+/**
+* Paths of every container deeper than `depth` levels are left out, so those
+* render collapsed. `depth: 0` collapses the root; `Infinity` expands all.
+*/
+function expandToDepth(value, depth) {
+	const out = /* @__PURE__ */ new Set();
+	const walk = (v, path, level) => {
+		if (!isContainer(v) || level >= depth) return;
+		out.add(path);
+		for (const [k, child] of childrenOf(v)) walk(child, `${path}/${k}`, level + 1);
+	};
+	walk(value, "", 0);
+	return out;
+}
+/** Flatten `value` into the lines visible under `expanded`. Pure — no I/O. */
+function renderTree(value, { expanded }) {
+	const lines = [];
+	const walk = (v, path, level, label, trailing) => {
+		const indent = "  ".repeat(level);
+		const prefix = `${indent}${label}`;
+		if (!isContainer(v)) {
+			lines.push({
+				path,
+				text: `${prefix}${scalar(v)}${trailing}`,
+				foldable: false,
+				expanded: false,
+				level
+			});
+			return;
+		}
+		const kids = childrenOf(v);
+		const [open, close] = Array.isArray(v) ? ["[", "]"] : ["{", "}"];
+		if (kids.length === 0) {
+			lines.push({
+				path,
+				text: `${prefix}${open}${close}${trailing}`,
+				foldable: false,
+				expanded: false,
+				level
+			});
+			return;
+		}
+		if (!expanded.has(path)) {
+			lines.push({
+				path,
+				text: `${prefix}${summary(v)}${trailing}`,
+				foldable: true,
+				expanded: false,
+				level
+			});
+			return;
+		}
+		lines.push({
+			path,
+			text: `${prefix}${open}`,
+			foldable: true,
+			expanded: true,
+			level
+		});
+		kids.forEach(([k, child], i) => {
+			const comma = i < kids.length - 1 ? "," : "";
+			const childLabel = Array.isArray(v) ? "" : `${chalk.cyan(JSON.stringify(k))}: `;
+			walk(child, `${path}/${k}`, level + 1, childLabel, comma);
+		});
+		lines.push({
+			path: `${path}#close`,
+			text: `${indent}${close}${trailing}`,
+			foldable: false,
+			expanded: false,
+			level
+		});
+	};
+	walk(value, "", 0, "", "");
+	return lines;
+}
+/** Pure key reducer: `(state, key) -> state`. `rows` is the viewport height. */
+function reduceKey(state, key, value, rows) {
+	const lines = renderTree(value, { expanded: state.expanded });
+	const cur = lines[state.cursor];
+	let { cursor } = state;
+	const expanded = new Set(state.expanded);
+	switch (key) {
+		case "up":
+			cursor = Math.max(0, cursor - 1);
+			break;
+		case "down":
+			cursor = Math.min(lines.length - 1, cursor + 1);
+			break;
+		case "right":
+			if (cur?.foldable) expanded.add(cur.path);
+			break;
+		case "left":
+			if (cur?.foldable && cur.expanded) expanded.delete(cur.path);
+			else if (cur) {
+				const parent = lines.findLastIndex((l, i) => i < cursor && l.foldable && l.expanded && l.level < cur.level);
+				if (parent >= 0) cursor = parent;
+			}
+			break;
+		case "expandAll": return {
+			cursor,
+			top: state.top,
+			expanded: expandToDepth(value, Infinity)
+		};
+		case "collapseAll": return {
+			cursor: 0,
+			top: 0,
+			expanded: /* @__PURE__ */ new Set()
+		};
+	}
+	const count = renderTree(value, { expanded }).length;
+	cursor = Math.min(cursor, count - 1);
+	let top = state.top;
+	if (cursor < top) top = cursor;
+	if (cursor >= top + rows) top = cursor - rows + 1;
+	return {
+		cursor,
+		top: Math.max(0, top),
+		expanded
+	};
+}
+const KEYMAP = {
+	"\x1B[A": "up",
+	k: "up",
+	"\x1B[B": "down",
+	j: "down",
+	"\x1B[C": "right",
+	l: "right",
+	"\r": "right",
+	" ": "right",
+	"\x1B[D": "left",
+	h: "left",
+	E: "expandAll",
+	C: "collapseAll",
+	q: "quit",
+	"\x1B": "quit",
+	"": "quit"
+};
+function draw(out, value, state, rows) {
+	const lines = renderTree(value, { expanded: state.expanded });
+	const view = lines.slice(state.top, state.top + rows).map((l, i) => {
+		const row = `${l.foldable ? l.expanded ? "▾ " : "▸ " : "  "}${l.text}`;
+		return state.top + i === state.cursor ? chalk.inverse(row) : row;
+	});
+	const footer = chalk.dim(`${state.cursor + 1}/${lines.length}  ↑↓ move  →/⏎ expand  ← collapse  E/C all  q quit`);
+	out.write(`\u001b[H\u001b[J${view.join("\n")}\n${footer}`);
+}
+async function runInteractive(value, depth) {
+	const { stdin, stdout } = process;
+	if (!stdin.isTTY || !stdout.isTTY) throw new NonInteractiveError("--interactive needs a TTY on stdin and stdout.");
+	const rows = () => Math.max(3, (stdout.rows ?? 24) - 1);
+	let state = {
+		cursor: 0,
+		top: 0,
+		expanded: expandToDepth(value, depth)
+	};
+	const wasRaw = stdin.isRaw;
+	stdin.setRawMode(true);
+	stdin.resume();
+	stdout.write("\x1B[?1049h\x1B[?25l");
+	const redraw = () => draw(stdout, value, state, rows());
+	stdout.on("resize", redraw);
+	try {
+		redraw();
+		await new Promise((resolve) => {
+			const onData = (buf) => {
+				const key = KEYMAP[buf.toString()];
+				if (key === "quit") {
+					stdin.off("data", onData);
+					resolve();
+					return;
+				}
+				if (key) {
+					state = reduceKey(state, key, value, rows());
+					redraw();
+				}
+			};
+			stdin.on("data", onData);
+		});
+	} finally {
+		stdout.off("resize", redraw);
+		stdout.write("\x1B[?25h\x1B[?1049l");
+		stdin.setRawMode(wasRaw);
+		stdin.pause();
+	}
+}
+/**
+* Print `value` as JSON. Non-TTY stdout always gets plain, valid
+* `JSON.stringify` output (so `| jq` and redirects keep working); a TTY gets a
+* coloured tree, collapsed past `depth`. `interactive` opens a folding viewer (the default on a TTY).
+*/
+async function viewJson(value, options = {}) {
+	const depth = options.depth ?? Infinity;
+	if (options.interactive ?? (options.depth === void 0 && Boolean(process.stdin.isTTY && process.stdout.isTTY))) return runInteractive(value, options.depth ?? 1);
+	if (!process.stdout.isTTY) {
+		console.log(JSON.stringify(value, null, 2));
+		return;
+	}
+	const lines = renderTree(value, { expanded: expandToDepth(value, depth) });
+	console.log(lines.map((l) => l.text).join("\n"));
+}
+//#endregion
+//#region src/ui/open-path.ts
+/** Platform-appropriate command to open a path in the OS's file browser. */
+function openCommand(path) {
+	if (process.platform === "darwin") return {
+		cmd: "open",
+		args: [path]
+	};
+	if (process.platform === "win32") return {
+		cmd: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			path
+		]
+	};
+	return {
+		cmd: "xdg-open",
+		args: [path]
+	};
+}
+/**
+* Open `path` in the OS's default file browser (Finder / Explorer /
+* whatever `xdg-open` resolves to on Linux). Fire-and-forget — detached so
+* it outlives this process, and never throws when the opener binary isn't
+* on PATH (e.g. no `xdg-open` in a minimal container).
+*/
+function openPath(path) {
+	const { cmd, args } = openCommand(path);
+	const child = spawn(cmd, args, {
+		stdio: "ignore",
+		detached: true
+	});
+	child.on("error", () => {});
+	child.unref();
+}
+//#endregion
+//#region src/update-notifier.ts
+const PACKAGE_NAME = "@theholocron/cli";
+const CACHE_TTL_MS = 864e5;
+const FETCH_TIMEOUT_MS = 3e3;
+function getCacheDir() {
+	return env.get("HOLOCRON_CACHE_DIR") ?? join(homedir(), ".cache", "holocron");
+}
+function getCachePath() {
+	return join(getCacheDir(), "update-check.json");
+}
+function readCache() {
+	try {
+		return JSON.parse(readFileSync(getCachePath(), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function writeCache(entry) {
+	try {
+		mkdirSync(getCacheDir(), { recursive: true });
+		writeFileSync(getCachePath(), JSON.stringify(entry));
+	} catch {}
+}
+async function fetchLatestVersion(channel) {
+	try {
 		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
 		if (!res.ok) return null;
 		const data = await res.json();
@@ -8021,6 +9221,19 @@ function resolveOrg(argv, config) {
 	return argv.org ?? env.get("HOLOCRON_ORG") ?? config.org;
 }
 /**
+* Print the dim version line once per terminal session — keyed by the
+* parent shell's PID, since that's stable across repeated bare `holocron`
+* invocations in the same shell but changes in a new tab/window. A marker
+* file in the OS tmpdir tracks whether this shell has already seen it, so
+* re-running `holocron` doesn't repeat the line every time.
+*/
+function printVersionHeaderOnce() {
+	const marker = join(tmpdir(), `.holocron-version-shown-${process.ppid}`);
+	if (existsSync(marker)) return;
+	console.log(style.dim(`v${CLI_VERSION}`));
+	writeFileSync(marker, "");
+}
+/**
 * `buildCliLogger` options derived from a loaded `holocron.config` — the
 * level, the Axiom dataset, and the resolved org for a keyring-backed
 * Axiom token. Used by every handler that has already called `loadConfig`.
@@ -8050,23 +9263,31 @@ function tokenContext(rawTokens) {
 		return parseTokenArgs(rawTokens);
 	} catch (err) {
 		if (err instanceof TokenParseError) {
-			getLogger().error(`--token: ${err.message}`);
+			reportError(`--token: ${err.message}`);
 			process.exitCode = 1;
 			return null;
 		}
 		throw err;
 	}
 }
+/** Layer 2: a bare group command (`holocron repo`, `holocron repo upgrade`, …) opens the menu at that level. */
+async function launchGroupMenu(parent, argv) {
+	await launchMenu(COMMAND_REGISTRY, argv, `${parent} — choose a subcommand:`, `Run \`holocron ${parent} --help\` to see available ${parent} subcommands.`, parent.split(" "));
+}
 init(CLI_VERSION);
 const updateCheckPromise = checkForUpdates(CLI_VERSION);
 let finishCommand = () => {};
 /** Set by `.fail()` once it has printed an error, so the outer catch doesn't repeat it. */
 let errorReported = false;
 try {
-	await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").parserConfiguration({ "populate--": true }).option("dry-run", {
+	await yargs(hideBin(process.argv)).scriptName("").usage("holocron <command> [options]").version(CLI_VERSION).alias("version", "v").parserConfiguration({ "populate--": true }).option("dry-run", {
 		type: "boolean",
 		default: false,
 		describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
+	}).option("skip-dry-run", {
+		type: "boolean",
+		default: false,
+		describe: "Interactive mode only: skip the automatic dry-run preview for a dry-run-capable command and run for real immediately."
 	}).option("token", {
 		type: "string",
 		array: true,
@@ -8090,20 +9311,21 @@ try {
 		type: "boolean",
 		default: false,
 		describe: "Set the log level to error — suppress info and warn."
+	}).option("log", {
+		type: "string",
+		choices: LOG_LEVELS,
+		describe: "Show structured logger output at this level. Local/interactive runs are quiet by default (no console output regardless of level) — this opts back in."
 	}).middleware((argv) => {
-		const name = argv._.slice(0, 2).join(" ") || "unknown";
+		const name = argv._.slice(0, 3).join(" ") || "unknown";
 		printRunId = Boolean(argv.debug || argv.verbose);
 		buildCliLogger(argv, {
 			command: name,
 			org: argv.org
 		});
 		finishCommand = startCommand(name);
-	}).command("version", "Print the CLI version", () => {}, () => {
-		console.log(`holocron ${CLI_VERSION}`);
-	}).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
+	}).command("clone [target]", "Clone a single repo (org/repo) or every repo in an org (org)", (y) => y.positional("target", {
 		type: "string",
-		demandOption: true,
-		describe: "GitHub org to clone (e.g., theholocron)"
+		describe: "org/repo to clone, or a bare org to clone every repo in it (confirms first)."
 	}).option("dir", {
 		type: "string",
 		describe: "Parent directory to clone into (default: ~/Code/<org>)"
@@ -8114,16 +9336,39 @@ try {
 		try {
 			token = resolveCloneToken({ cliToken: tokens.cliTokens?.["github"] ?? tokens.cliToken });
 		} catch (err) {
-			getLogger().error(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
+			reportError(`clone: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
 			return;
 		}
-		if ((await runClone({
-			org: argv.org,
+		const [targetInput] = await promptForPositionals(getEntry("clone"), argv);
+		const { org, repo } = parseCloneTarget(targetInput);
+		const report = await runClone({
+			org,
+			...repo ? { repo } : {},
 			token,
 			dryRun: argv.dryRun,
-			...argv.dir ? { dir: argv.dir } : {}
-		})).status === "fail") process.exitCode = 1;
+			...argv.dir ? { dir: argv.dir } : {},
+			...!repo ? { confirmWholeOrg: async ({ total, alreadyCloned, toClone }) => {
+				if (!process.stdin.isTTY) throw new NonInteractiveError(`clone: cloning every repo in "${org}" needs interactive confirmation — run this from a terminal, or pass a specific org/repo instead`);
+				if (toClone === 0) return true;
+				return confirm({
+					message: `${org} has ${total} repos — ${alreadyCloned} already cloned locally, ${toClone} new. Clone them all?`,
+					default: false
+				});
+			} } : {},
+			confirmOpen: async (openTarget, moreToCome) => {
+				if (!process.stdin.isTTY) return;
+				if (moreToCome && env.get("HOLOCRON_DRY_RUN_PREVIEW") === "1") return;
+				if (await confirm({
+					message: `Open ${openTarget}?`,
+					default: false
+				})) openPath(openTarget);
+			}
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`clone: ${report.message}`);
+			process.exitCode = 1;
+		} else if (report.status === "dry-run" && report.cloned === 0 && env.get("HOLOCRON_DRY_RUN_PREVIEW") === "1") process.exitCode = 2;
 	}).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."
@@ -8142,28 +9387,6 @@ try {
 				org: resolveOrg(argv, loaded.resolved)
 			}
 		})).summary.fail > 0) process.exitCode = 1;
-	}).command("setup", "Apply infra setup actions across every configured capability", (y) => y.option("repo", {
-		type: "string",
-		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
-	}).option("hooks", {
-		type: "boolean",
-		describe: "Install git hooks (.husky/pre-push → holocron ci). Default: on for protection:'strict'. --no-hooks to skip."
-	}), async (argv) => {
-		const tokens = tokenContext(argv.token);
-		if (!tokens) return;
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSetup({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...argv.repo ? { repo: argv.repo } : {},
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
-			...argv.hooks !== void 0 ? { hooks: argv.hooks } : {}
-		})).summary.fail > 0) process.exitCode = 1;
 	}).command("skills", "Manage agent skills from the @theholocron/skills registry", (y) => y.command("install", "Copy skills from @theholocron/skills into .agents/ with agent symlinks", () => {}, async (argv) => {
 		await runSkillsInstall({
 			loaded: await loadConfig(argv.cwd),
@@ -8196,331 +9419,214 @@ try {
 			...argv.name ? { name: argv.name } : {}
 		}).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
-		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "skills"), argv, "skills — choose a subcommand:", "Run `holocron skills --help` to see available skills subcommands.");
-	}), () => {}).command("secret set [name] [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
+		await launchGroupMenu("skills", argv);
+	}), () => {}).command("run <task> [job] [passthrough..]", "Run a task locally (test, typecheck, lint, build, audit) — figures out turbo / the tool / the package manager. `run ci` runs every merge-gating check; `run lint commit-msg <file>` lints a commit message.", (y) => y.positional("task", {
 		type: "string",
-		describe: "Secret name (e.g., NPM_TOKEN)"
-	}).positional("value", {
+		demandOption: true,
+		describe: "Task name (test, typecheck, lint, build, audit, or `ci` for the merge-gating suite). See `holocron run --help`."
+	}).positional("job", {
 		type: "string",
-		describe: "Secret value (positional). If omitted, sources from --from-stdin, --from-env, or env var matching <name>."
-	}).option("from-stdin", {
+		describe: "Sub-job within the task (e.g. `holocron run audit performance`, `holocron run lint commit-msg <file>`). Omit to run every job."
+	}).positional("passthrough", {
+		type: "string",
+		array: true,
+		describe: "Args forwarded to the tool — put them after `--`."
+	}).option("required", {
 		type: "boolean",
 		default: false,
-		describe: "Read the secret value from stdin"
-	}).option("from-env", {
+		describe: "Fail (exit 1) if this repo has no such task, instead of skipping."
+	}).option("all", {
+		type: "boolean",
+		default: false,
+		describe: "With `run ci`: run every `ci: true` task, not just the required ones."
+	}).option("filter", {
 		type: "string",
-		describe: "Read the secret value from the named env var (otherwise: env var matching <name>)"
-	}).option("scope", {
+		describe: "turbo --filter=<pkg> passthrough (monorepo)."
+	}), async (argv) => {
+		const { logger } = buildCliLogger(argv, { command: argv.task === "ci" ? "run ci" : argv.task === "lint" && argv.job === "commit-msg" ? "run lint commit-msg" : "run" });
+		const passthrough = [...argv.passthrough ?? [], ...argv["--"] ?? []];
+		if (argv.task === "lint" && argv.job === "commit-msg") {
+			const file = passthrough[0];
+			if (!file) {
+				reportError("run lint commit-msg: missing <file> (the commit message file git passes as $1).");
+				process.exitCode = 1;
+				return;
+			}
+			const result = await lintCommitMsgFile(file, argv.cwd);
+			if (!result.valid) {
+				for (const violation of result.violations) console.error(`✖ ${violation.rule}: ${violation.message}`);
+				process.exitCode = 1;
+			}
+			return;
+		}
+		if (argv.task === "ci") {
+			const ciConfig = await loadTasksConfig(argv.cwd).catch(() => void 0);
+			if (createAstromech({
+				cwd: argv.cwd,
+				logger,
+				config: ciConfig
+			}).ci({
+				dryRun: argv.dryRun,
+				scope: argv.all ? "all" : "required",
+				...argv.filter ? { filter: argv.filter } : {}
+			}).status === "fail") process.exitCode = 1;
+			return;
+		}
+		const config = await loadTasksConfig(argv.cwd).catch(() => void 0);
+		const report = createAstromech({
+			cwd: argv.cwd,
+			logger,
+			config
+		}).run(argv.task, {
+			...argv.job !== void 0 ? { job: argv.job } : {},
+			passthrough,
+			dryRun: argv.dryRun,
+			required: argv.required,
+			...argv.filter ? { filter: argv.filter } : {}
+		});
+		if (report.status === "fail" || report.status === "unknown") process.exitCode = 1;
+	}).command("config show", "Print the resolved holocron config", (y) => y.option("depth", {
+		type: "number",
+		describe: "Collapse objects/arrays nested deeper than N levels (TTY output only)"
+	}).option("interactive", {
+		type: "boolean",
+		describe: "Browse the config in a foldable tree (default on a TTY; --no-interactive for static output)"
+	}), async (argv) => {
+		await viewJson((await loadConfig(argv.cwd)).resolved, {
+			depth: argv.depth,
+			interactive: argv.interactive
+		});
+	}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set [provider] [value]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", { type: "string" }).positional("value", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth set"), argv);
+		if ((await runAuthSet({
+			provider,
+			...argv.value ? { positional: argv.value } : {},
+			...argv.org ? { org: argv.org } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("unset [provider]", "Remove a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth unset"), argv);
+		runAuthUnset({ provider });
+	}).command("check [provider]", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth check"), argv);
+		if ((await runAuthCheck({
+			provider,
+			...argv.org ? { org: argv.org } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
+		await runAuthList();
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("auth", argv);
+	}), () => {}).command("$0", false, () => {}, async (argv) => {
+		printVersionHeaderOnce();
+		const runEntries = buildRunMenuEntries(await listRunnableTasks(argv));
+		await launchMenu([...COMMAND_REGISTRY, ...runEntries], argv);
+	}).command("repo", "Set up, sync and upgrade the current repo", (g) => g.command("setup", "Apply infra setup actions across every configured capability", (y) => y.option("repo", {
 		type: "string",
-		default: "repo",
-		describe: "Scope: \"repo\" (default), \"env=<name>\", or \"org=<name>\""
+		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
+	}).option("hooks", {
+		type: "boolean",
+		describe: "Install git hooks (.husky/pre-push → holocron run ci). Default: on for protection:'strict'. --no-hooks to skip."
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
-		const [name] = await promptForPositionals(getEntry("secret set"), argv);
-		const scopeArg = argv.scope;
-		const scope = parseScope(scopeArg);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSecretSet({
+		if ((await runSetup({
 			loaded,
 			context: {
 				repoRoot: argv.cwd,
 				dryRun: argv.dryRun,
+				...argv.repo ? { repo: argv.repo } : {},
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			name,
-			...argv.value ? { value: argv.value } : {},
-			...argv.fromStdin ? { fromStdin: true } : {},
-			...argv.fromEnv ? { fromEnv: argv.fromEnv } : {},
-			scope
-		})).status === "fail") process.exitCode = 1;
-	}).command("secrets sync [environmentId]", "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars", (y) => y.positional("environmentId", {
-		type: "string",
-		describe: "Vault environment id to read (1P Environment id, etc.)"
-	}).option("project-id", {
-		type: "string",
-		describe: "Deployment project id (e.g., Vercel prj_*). Required when deployment is loaded."
-	}).option("target", {
-		type: "array",
-		default: ["production", "preview"],
-		describe: "Deployment targets to sync to. Defaults to production + preview."
+			...argv.hooks !== void 0 ? { hooks: argv.hooks } : {}
+		})).summary.fail > 0) process.exitCode = 1;
+	}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.command("readme", "Sync the Installation + Usage block in README.md from package.json", (y) => y.option("dry-run", {
+		type: "boolean",
+		describe: "Print what would change without writing",
+		default: false
 	}), async (argv) => {
-		const tokens = tokenContext(argv.token);
-		if (!tokens) return;
-		const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSecretsSync({
+		const report = await runSyncReadme({
 			loaded,
 			context: {
 				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
-			environmentId,
-			...argv.projectId ? { projectId: argv.projectId } : {},
-			targets: argv.target
-		})).summary.fail > 0) process.exitCode = 1;
-	}).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
-		type: "string",
-		describe: "Git branch to deploy"
-	}).option("project-id", {
+				dryRun: argv.dryRun
+			}
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`repo sync readme: ${report.message}`);
+			process.exitCode = 1;
+		}
+	}).positional("steps", {
 		type: "string",
-		demandOption: true,
-		describe: "Deployment project id (e.g., Vercel prj_*)"
-	}).option("target", {
+		array: true,
+		describe: "Steps to run: labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki (default: all)"
+	}).option("repo", {
 		type: "string",
-		choices: ["production", "staging"],
-		describe: "Named environment to deploy into. Omit for a branch preview."
+		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
-		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runDeploy({
+		if ((await runSync({
 			loaded,
 			context: {
 				repoRoot: argv.cwd,
 				dryRun: argv.dryRun,
+				...argv.repo ? { repo: argv.repo } : {},
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			projectId: argv.projectId,
-			branch,
-			...argv.target ? { target: argv.target } : {}
-		})).status === "fail") process.exitCode = 1;
-	}).command("cleanup-preview [pr]", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
+			...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
+		})).summary.fail > 0) process.exitCode = 1;
+	}).command("upgrade", "Upgrade toolchain version pins across the repo", (y) => y.command("node [to]", "Scan the repo and update every Node.js version pin to a new major", (yy) => yy.positional("to", {
 		type: "number",
-		describe: "PR number to clean up"
-	}).option("project", {
-		type: "string",
-		demandOption: true,
-		describe: "Cloudflare Pages project name (e.g. theholocron-preview)"
-	}).option("repo", {
-		type: "string",
-		describe: "GitHub repo as owner/name — defaults to the repo in holocron.config"
-	}), async (argv) => {
-		const tokens = tokenContext(argv.token);
-		if (!tokens) return;
-		const [pr] = await promptForPositionals(getEntry("cleanup-preview"), argv);
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runCleanupPreview({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
-			prNumber: Number(pr),
-			project: argv.project,
-			...argv.repo ? { repo: argv.repo } : {}
-		})).status === "fail") process.exitCode = 1;
-	}).command("bump-versions [new-version]", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
-		type: "string",
-		describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
-	}), async (argv) => {
-		const [newVersion] = await promptForPositionals(getEntry("bump-versions"), argv);
-		if ((await runNpmBumpVersions({
-			version: newVersion,
-			cwd: argv.cwd,
-			dryRun: argv.dryRun
-		})).status === "fail") process.exitCode = 1;
-	}).command("publish", "Publish @theholocron/* packages to npm", (y) => y.option("initial", {
-		type: "boolean",
-		default: false,
-		describe: "One-shot bootstrap publish for trusted-publishing-eligible packages (npm needs the package to exist before Trusted Publishing can be configured for it). Skips the steady-state OIDC path below — use only for a package's very first publish."
-	}).option("tag", {
-		type: "string",
-		describe: "npm distribution tag. Defaults to alpha for --initial, latest for a steady-state publish."
-	}).option("otp", {
-		type: "string",
-		describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
-	}).option("sync-trust", {
-		type: "array",
-		describe: "Migrate npm Trusted Publisher config to a new workflow filename across every public package: --sync-trust <old-file> <new-file>. See issue #689 — npm requires fresh interactive 2FA per package; re-run after approving the printed authUrl if it stops early."
-	}).option("repo", {
-		type: "string",
-		describe: "owner/repo for Trusted Publisher config (--sync-trust). Defaults to theholocron/holocron."
-	}).option("provenance", {
-		type: "boolean",
-		default: true,
-		describe: "Publish with --provenance (steady-state only). Default on — free under CI/OIDC."
-	}).option("skip-already-published", {
-		type: "boolean",
-		default: false,
-		describe: "Steady-state only: check `npm view <pkg>@<version>` before publishing each package and skip it if that exact version already exists, instead of one bulk publish. For repos that ship many independently-versioned packages where a release doesn't bump every one."
-	}), async (argv) => {
-		if (argv.syncTrust) {
-			const [oldFile, newFile] = argv.syncTrust;
-			if (!oldFile || !newFile) {
-				getLogger().error("publish --sync-trust requires exactly two values: <old-file> <new-file>");
-				process.exitCode = 1;
-				return;
-			}
-			if ((await runSyncTrust({
-				cwd: argv.cwd,
-				oldFile,
-				newFile,
-				dryRun: argv.dryRun,
-				...argv.repo ? { repo: argv.repo } : {}
-			})).status === "fail") process.exitCode = 1;
-			return;
-		}
-		if (argv.initial) {
-			if ((await runPublish({
-				cwd: argv.cwd,
-				dryRun: argv.dryRun,
-				...argv.tag ? { tag: argv.tag } : {},
-				...argv.otp ? { otp: argv.otp } : {}
-			})).status === "fail") process.exitCode = 1;
-			return;
-		}
-		if ((await runSteadyPublish({
-			cwd: argv.cwd,
-			dryRun: argv.dryRun,
-			provenance: argv.provenance,
-			skipAlreadyPublished: argv.skipAlreadyPublished,
-			...argv.tag ? { tag: argv.tag } : {},
-			...argv.otp ? { otp: argv.otp } : {}
-		})).status === "fail") process.exitCode = 1;
-	}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.positional("steps", {
-		type: "string",
-		array: true,
-		describe: "Steps to run: labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki (default: all)"
-	}).option("repo", {
-		type: "string",
-		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
-	}), async (argv) => {
-		const tokens = tokenContext(argv.token);
-		if (!tokens) return;
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSync({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...argv.repo ? { repo: argv.repo } : {},
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
-			...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
-		})).summary.fail > 0) process.exitCode = 1;
-	}).command("run <task> [job] [passthrough..]", "Run a task locally (test, typecheck, lint, build, audit) — figures out turbo / the tool / the package manager", (y) => y.positional("task", {
-		type: "string",
-		demandOption: true,
-		describe: "Task name (test, typecheck, lint, build, audit). See `holocron run --help`."
-	}).positional("job", {
-		type: "string",
-		describe: "Sub-job within the task (e.g. `holocron run audit performance`). Omit to run every job. Only `audit` has jobs today."
-	}).positional("passthrough", {
-		type: "string",
-		array: true,
-		describe: "Args forwarded to the tool — put them after `--`."
-	}).option("required", {
-		type: "boolean",
-		default: false,
-		describe: "Fail (exit 1) if this repo has no such task, instead of skipping."
-	}).option("filter", {
-		type: "string",
-		describe: "turbo --filter=<pkg> passthrough (monorepo)."
+		describe: "Target Node.js major version (e.g., 22)"
+	}).option("from", {
+		type: "number",
+		describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
 	}), async (argv) => {
-		const { logger } = buildCliLogger(argv, { command: "run" });
-		const config = await loadTasksConfig(argv.cwd).catch(() => void 0);
-		const report = createAstromech({
+		const [to] = await promptForPositionals(getEntry("repo upgrade node"), argv);
+		let extra = [];
+		try {
+			const raw = readFileSync(join(argv.cwd, "holocron.config.json"), "utf8");
+			const extraRaw = JSON.parse(raw).upgrade?.node?.extra;
+			if (Array.isArray(extraRaw)) extra = extraRaw;
+		} catch {}
+		const report = await runUpgradeNode({
+			to: Number(to),
+			...argv.from != null ? { from: argv.from } : {},
 			cwd: argv.cwd,
-			logger,
-			config
-		}).run(argv.task, {
-			...argv.job !== void 0 ? { job: argv.job } : {},
-			passthrough: [...argv.passthrough ?? [], ...argv["--"] ?? []],
 			dryRun: argv.dryRun,
-			required: argv.required,
-			...argv.filter ? { filter: argv.filter } : {}
+			extra
 		});
-		if (report.status === "fail" || report.status === "unknown") process.exitCode = 1;
-	}).command("ci", "Run the merge-gating checks locally, in CI order — 'will CI pass?'", (y) => y.option("all", {
+		if (report.status === "fail") {
+			if (report.message) reportError(`upgrade node: ${report.message}`);
+			process.exitCode = 1;
+		}
+	}).command("deps", "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API", (yy) => yy.option("pins-only", {
 		type: "boolean",
 		default: false,
-		describe: "Run every `ci: true` task, not just the required ones."
-	}).option("filter", {
-		type: "string",
-		describe: "turbo --filter=<pkg> passthrough (monorepo)."
+		describe: "Only bump the catalog pins — skip the holocron.config.ts migration"
 	}), async (argv) => {
-		const { logger } = buildCliLogger(argv, { command: "ci" });
-		const config = await loadTasksConfig(argv.cwd).catch(() => void 0);
-		if (createAstromech({
+		const report = await runUpgradeDeps({
 			cwd: argv.cwd,
-			logger,
-			config
-		}).ci({
 			dryRun: argv.dryRun,
-			scope: argv.all ? "all" : "required",
-			...argv.filter ? { filter: argv.filter } : {}
-		}).status === "fail") process.exitCode = 1;
-	}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
-		type: "string",
-		default: "theholocron/.github",
-		describe: "Target org/repo (default: theholocron/.github)"
-	}).option("branch", {
-		type: "string",
-		describe: "Push to this branch instead of the default branch (enables PR-based workflow for protected repos)"
-	}).option("pr", {
-		type: "boolean",
-		default: false,
-		describe: "Open a PR after pushing to --branch (no-op without --branch)"
-	}).option("message", {
-		type: "string",
-		describe: "Commit message (default: chore: sync from theholocron/holocron)"
-	}).option("output-dir", {
-		type: "string",
-		describe: "Write generated files to this local directory instead of pushing (for validation)"
-	}), async (argv) => {
-		const outputDir = argv["output-dir"];
-		const parsed = tokenContext(argv.token);
-		if (!parsed) return;
-		let token;
-		if (outputDir) token = "no-token-needed";
-		else try {
-			token = resolveSyncToken({ cliToken: parsed.cliTokens?.["github"] ?? parsed.cliToken });
-		} catch (err) {
-			getLogger().error(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
+			pinsOnly: argv.pinsOnly
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`upgrade deps: ${report.message}`);
 			process.exitCode = 1;
-			return;
 		}
-		if ((await runSyncGithub({
-			token,
-			repo: argv.repo,
-			dryRun: argv.dryRun,
-			...argv.branch ? { branch: argv.branch } : {},
-			...argv.pr ? { createPr: true } : {},
-			...argv.message ? { message: argv.message } : {},
-			...outputDir ? { outputDir } : {}
-		})).status === "fail") process.exitCode = 1;
-	}).command("sync-readme", "Sync the Installation + Usage block in README.md from package.json", (y) => y.option("dry-run", {
-		type: "boolean",
-		describe: "Print what would change without writing",
-		default: false
-	}), async (argv) => {
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		if ((await runSyncReadme({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun
-			}
-		})).status === "fail") process.exitCode = 1;
-	}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
-		const loaded = await loadConfig(argv.cwd);
-		console.log(JSON.stringify(loaded.resolved, null, 2));
-	}).command("new [type] [name]", "Scaffold a new repo from a GitHub template (e.g. cli, react, nextjs, node, monorepo, base)", (y) => y.positional("type", {
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("repo upgrade", argv);
+	}), () => {}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("repo", argv);
+	}), () => {}).command("new", "Scaffold a new repo or plugin", (g) => g.command("repo [type] [name]", "Scaffold a new repo from a GitHub template (e.g. cli, react, nextjs, node, monorepo, base)", (y) => y.positional("type", {
 		type: "string",
 		describe: "Template type — maps to theholocron/<type>-template (e.g. cli, react, nextjs, node, monorepo, base)"
 	}).positional("name", {
@@ -8569,7 +9675,7 @@ try {
 	}).option("verify", {
 		type: "boolean",
 		default: true,
-		describe: "Run pnpm install + holocron setup after bootstrapping (--no-verify skips)"
+		describe: "Run pnpm install + holocron repo setup after bootstrapping (--no-verify skips)"
 	}), async (argv) => {
 		try {
 			const tokens = tokenContext(argv.token);
@@ -8745,12 +9851,12 @@ try {
 			}) === "yes";
 			if (skills.length === 0) skills = parseTopics(await input({ message: "Agent skills (comma-separated, optional):" }));
 			if (!type) {
-				getLogger().error("new: template type is required");
+				reportError("new: template type is required");
 				process.exitCode = 1;
 				return;
 			}
 			if (!name) {
-				getLogger().error("new: repo name is required");
+				reportError("new: repo name is required");
 				process.exitCode = 1;
 				return;
 			}
@@ -8779,13 +9885,13 @@ try {
 			})).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof NewError) {
-				getLogger().error(`new: ${err.message}`);
+				reportError(`new: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
 			throw err;
 		}
-	}).command("plugin create [slug] [vendor]", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
+	}).command("plugin [slug] [vendor]", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
 		type: "string",
 		describe: "Package slug (kebab-case)"
 	}).positional("vendor", {
@@ -8809,7 +9915,7 @@ try {
 		describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
 	}), async (argv) => {
 		try {
-			const [slug, vendor] = await promptForPositionals(getEntry("plugin create"), argv);
+			const [slug, vendor] = await promptForPositionals(getEntry("new plugin"), argv);
 			const { capability, vendorEnv, baseUrl } = await resolvePluginCreateInputs({
 				capability: argv.capability,
 				vendorEnv: argv.vendorEnv,
@@ -8838,92 +9944,315 @@ try {
 			}).status === "fail") process.exitCode = 1;
 		} catch (err) {
 			if (err instanceof PluginCreateError) {
-				getLogger().error(`plugin create: ${err.message}`);
+				reportError(`plugin create: ${err.message}`);
 				process.exitCode = 1;
 				return;
 			}
 			throw err;
 		}
-	}).command("upgrade", "Upgrade toolchain version pins across the repo", (y) => y.command("node [to]", "Scan the repo and update every Node.js version pin to a new major", (yy) => yy.positional("to", {
-		type: "number",
-		describe: "Target Node.js major version (e.g., 22)"
-	}).option("from", {
-		type: "number",
-		describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("new", argv);
+	}), () => {}).command("secrets", "Set secrets and sync vault environments", (g) => g.command("set [name] [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
+		type: "string",
+		describe: "Secret name (e.g., NPM_TOKEN)"
+	}).positional("value", {
+		type: "string",
+		describe: "Secret value (positional). If omitted, sources from --from-stdin, --from-env, or env var matching <name>."
+	}).option("from-stdin", {
+		type: "boolean",
+		default: false,
+		describe: "Read the secret value from stdin"
+	}).option("from-env", {
+		type: "string",
+		describe: "Read the secret value from the named env var (otherwise: env var matching <name>)"
+	}).option("scope", {
+		type: "string",
+		default: "repo",
+		describe: "Scope: \"repo\" (default), \"env=<name>\", or \"org=<name>\""
 	}), async (argv) => {
-		const [to] = await promptForPositionals(getEntry("upgrade node"), argv);
-		let extra = [];
-		try {
-			const raw = readFileSync(join(argv.cwd, "holocron.config.json"), "utf8");
-			const extraRaw = JSON.parse(raw).upgrade?.node?.extra;
-			if (Array.isArray(extraRaw)) extra = extraRaw;
-		} catch {}
-		const report = await runUpgradeNode({
-			to: Number(to),
-			...argv.from != null ? { from: argv.from } : {},
-			cwd: argv.cwd,
-			dryRun: argv.dryRun,
-			extra
-		});
-		if (report.status === "fail") {
-			if (report.message) getLogger().error(`upgrade node: ${report.message}`);
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const [name] = await promptForPositionals(getEntry("secrets set"), argv);
+		const scopeArg = argv.scope;
+		const scope = parseScope(scopeArg);
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runSecretSet({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			name,
+			...argv.value ? { value: argv.value } : {},
+			...argv.fromStdin ? { fromStdin: true } : {},
+			...argv.fromEnv ? { fromEnv: argv.fromEnv } : {},
+			scope
+		})).status === "fail") process.exitCode = 1;
+	}).command("sync [environmentId]", "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars", (y) => y.positional("environmentId", {
+		type: "string",
+		describe: "Vault environment id to read (1P Environment id, etc.)"
+	}).option("project-id", {
+		type: "string",
+		describe: "Deployment project id (e.g., Vercel prj_*). Required when deployment is loaded."
+	}).option("target", {
+		type: "array",
+		default: ["production", "preview"],
+		describe: "Deployment targets to sync to. Defaults to production + preview."
+	}).option("github-secret", {
+		type: "array",
+		describe: "Vault key(s) to push to GH Actions secrets (repeatable). Omit to push every key."
+	}).option("github-secret-scope", {
+		type: "string",
+		default: "repo",
+		describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const githubSecretScope = parseScope(argv.githubSecretScope);
+		const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runSecretsSync({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			environmentId,
+			...argv.projectId ? { projectId: argv.projectId } : {},
+			...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
+			githubSecretScope,
+			targets: argv.target
+		})).summary.fail > 0) process.exitCode = 1;
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("secrets", 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", {
+		type: "string",
+		default: "theholocron/.github",
+		describe: "Target org/repo (default: theholocron/.github)"
+	}).option("branch", {
+		type: "string",
+		describe: "Push to this branch instead of the default branch (enables PR-based workflow for protected repos)"
+	}).option("pr", {
+		type: "boolean",
+		default: false,
+		describe: "Open a PR after pushing to --branch (no-op without --branch)"
+	}).option("message", {
+		type: "string",
+		describe: "Commit message (default: chore: sync from theholocron/holocron)"
+	}).option("output-dir", {
+		type: "string",
+		describe: "Write generated files to this local directory instead of pushing (for validation)"
+	}), async (argv) => {
+		const outputDir = argv["output-dir"];
+		const parsed = tokenContext(argv.token);
+		if (!parsed) return;
+		let token;
+		if (outputDir) token = "no-token-needed";
+		else try {
+			token = resolveSyncToken({ cliToken: parsed.cliTokens?.["github"] ?? parsed.cliToken });
+		} catch (err) {
+			reportError(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
 			process.exitCode = 1;
+			return;
 		}
-	}).command("deps", "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API", (yy) => yy.option("pins-only", {
+		if ((await runSyncGithub({
+			token,
+			repo: argv.repo,
+			dryRun: argv.dryRun,
+			...argv.branch ? { branch: argv.branch } : {},
+			...argv.pr ? { createPr: true } : {},
+			...argv.message ? { message: argv.message } : {},
+			...outputDir ? { outputDir } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("sync", argv);
+	}), () => {}).command("package", "Version and publish workspace packages", (g) => g.command("bump-versions [new-version]", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
+		type: "string",
+		describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
+	}), async (argv) => {
+		const [newVersion] = await promptForPositionals(getEntry("package bump-versions"), argv);
+		if ((await runNpmBumpVersions({
+			version: newVersion,
+			cwd: argv.cwd,
+			dryRun: argv.dryRun
+		})).status === "fail") process.exitCode = 1;
+	}).command("publish", "Publish @theholocron/* packages to npm", (y) => y.option("initial", {
 		type: "boolean",
 		default: false,
-		describe: "Only bump the catalog pins — skip the holocron.config.ts migration"
+		describe: "One-shot bootstrap publish for trusted-publishing-eligible packages (npm needs the package to exist before Trusted Publishing can be configured for it). Skips the steady-state OIDC path below — use only for a package's very first publish."
+	}).option("tag", {
+		type: "string",
+		describe: "npm distribution tag. Defaults to alpha for --initial, latest for a steady-state publish."
+	}).option("otp", {
+		type: "string",
+		describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
+	}).option("sync-trust", {
+		type: "array",
+		describe: "Migrate npm Trusted Publisher config to a new workflow filename across every public package: --sync-trust <old-file> <new-file>. See issue #689 — npm requires fresh interactive 2FA per package; re-run after approving the printed authUrl if it stops early."
+	}).option("repo", {
+		type: "string",
+		describe: "owner/repo for Trusted Publisher config (--sync-trust). Defaults to theholocron/holocron."
+	}).option("provenance", {
+		type: "boolean",
+		default: true,
+		describe: "Publish with --provenance (steady-state only). Default on — free under CI/OIDC."
+	}).option("skip-already-published", {
+		type: "boolean",
+		default: false,
+		describe: "Steady-state only: check `npm view <pkg>@<version>` before publishing each package and skip it if that exact version already exists, instead of one bulk publish. For repos that ship many independently-versioned packages where a release doesn't bump every one."
 	}), async (argv) => {
-		const report = await runUpgradeDeps({
+		if (argv.syncTrust) {
+			const [oldFile, newFile] = argv.syncTrust;
+			if (!oldFile || !newFile) {
+				reportError("publish --sync-trust requires exactly two values: <old-file> <new-file>");
+				process.exitCode = 1;
+				return;
+			}
+			if ((await runSyncTrust({
+				cwd: argv.cwd,
+				oldFile,
+				newFile,
+				dryRun: argv.dryRun,
+				...argv.repo ? { repo: argv.repo } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
+		}
+		if (argv.initial) {
+			if ((await runPublish({
+				cwd: argv.cwd,
+				dryRun: argv.dryRun,
+				...argv.tag ? { tag: argv.tag } : {},
+				...argv.otp ? { otp: argv.otp } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
+		}
+		if ((await runSteadyPublish({
 			cwd: argv.cwd,
 			dryRun: argv.dryRun,
-			pinsOnly: argv.pinsOnly
-		});
-		if (report.status === "fail") {
-			if (report.message) getLogger().error(`upgrade deps: ${report.message}`);
-			process.exitCode = 1;
-		}
+			provenance: argv.provenance,
+			skipAlreadyPublished: argv.skipAlreadyPublished,
+			...argv.tag ? { tag: argv.tag } : {},
+			...argv.otp ? { otp: argv.otp } : {}
+		})).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
-		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "upgrade"), argv, "upgrade — choose a subcommand:", "Run `holocron upgrade --help` to see available upgrade subcommands.");
-	}), () => {}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set [provider] [value]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", { type: "string" }).positional("value", { type: "string" }), async (argv) => {
-		const [provider] = await promptForPositionals(getEntry("auth set"), argv);
-		if ((await runAuthSet({
-			provider,
-			...argv.value ? { positional: argv.value } : {},
-			...argv.org ? { org: argv.org } : {}
+		await launchGroupMenu("package", argv);
+	}), () => {}).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.command("cleanup-preview [pr]", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
+		type: "number",
+		describe: "PR number to clean up"
+	}).option("project", {
+		type: "string",
+		demandOption: true,
+		describe: "Cloudflare Pages project name (e.g. theholocron-preview)"
+	}).option("repo", {
+		type: "string",
+		describe: "GitHub repo as owner/name — defaults to the repo in holocron.config"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const [pr] = await promptForPositionals(getEntry("deploy cleanup-preview"), argv);
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runCleanupPreview({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			prNumber: Number(pr),
+			project: argv.project,
+			...argv.repo ? { repo: argv.repo } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("unset [provider]", "Remove a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
-		const [provider] = await promptForPositionals(getEntry("auth unset"), argv);
-		runAuthUnset({ provider });
-	}).command("check [provider]", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
-		const [provider] = await promptForPositionals(getEntry("auth check"), argv);
-		if ((await runAuthCheck({
-			provider,
-			...argv.org ? { org: argv.org } : {}
+	}).command("on-release", "Deploy every workspace package whose delivery.deploy task is `on: release` — run by the delivery.publish workflow's deploy job", (y) => y.option("channel", {
+		type: "string",
+		default: "",
+		describe: "The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release."
+	}).option("from", {
+		type: "string",
+		describe: "The previous release's commit, to diff against. Omit when there is none."
+	}).option("to", {
+		type: "string",
+		describe: "The release commit. Default HEAD."
+	}), async (argv) => {
+		if ((await deployOnRelease({
+			cwd: argv.cwd,
+			channel: argv.channel,
+			...argv.from ? { from: argv.from } : {},
+			...argv.to ? { to: argv.to } : {},
+			dryRun: argv.dryRun,
+			print: (line) => console.log(line)
+		})).status === "fail") process.exitCode = 1;
+	}).positional("branch", {
+		type: "string",
+		describe: "Git branch to deploy (omit when using --files)"
+	}).option("project-id", {
+		type: "string",
+		describe: "Deployment project id (required to trigger a deployment, e.g. Vercel prj_*)"
+	}).option("target", {
+		type: "string",
+		choices: ["production", "staging"],
+		describe: "Named environment to deploy into. Omit for a branch preview."
+	}).option("files", {
+		type: "string",
+		describe: "Deploy from a local directory of source files instead of a Git branch — calls deployFunction(), no linked repo required. Conflicts with `branch`."
+	}).conflicts("files", "branch"), async (argv) => {
+		if (!argv.projectId) {
+			reportError("deploy: missing required argument --project-id");
+			process.exitCode = 1;
+			return;
+		}
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		const context = {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...tokens,
+			org: resolveOrg(argv, loaded.resolved)
+		};
+		if (argv.files) {
+			if ((await runDeployFromFiles({
+				loaded,
+				context,
+				projectId: argv.projectId,
+				dir: argv.files,
+				...argv.target ? { target: argv.target } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
+		}
+		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
+		if ((await runDeploy({
+			loaded,
+			context,
+			projectId: argv.projectId,
+			branch,
+			...argv.target ? { target: argv.target } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
-		await runAuthList();
-	}).command("$0", false, () => {}, async (argv) => {
-		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "auth"), argv, "auth — choose a subcommand:", "Run `holocron auth --help` to see available auth subcommands.");
-	}), () => {}).command("$0", false, () => {}, async (argv) => {
-		await launchMenu(COMMAND_REGISTRY.filter((e) => !e.group), argv);
 	}).strict().help().epilogue(`Execution contexts:
   global      works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n  repo-aware  needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n  workspace   also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n  https://theholocron.github.io/holocron/execution-contexts`).fail((msg, err) => {
 		if (err instanceof Error && USER_FACING_ERRORS.has(err.name)) {
 			captureException(err);
-			getLogger().error(err.message);
+			reportError(err.message);
 			errorReported = true;
 			process.exitCode = 1;
 			return;
 		}
 		if (err) throw err;
-		getLogger().error(msg);
+		reportError(msg);
 		errorReported = true;
 		process.exitCode = 1;
 	}).parse();
 } catch (err) {
 	captureException(err);
-	if (!errorReported && err instanceof Error && USER_FACING_ERRORS.has(err.name)) getLogger().error(err.message);
+	if (!errorReported && err instanceof Error && USER_FACING_ERRORS.has(err.name)) reportError(err.message);
 	if (!process.exitCode) process.exitCode = 1;
 }
 finishCommand(!process.exitCode);