@theholocron/cli 5.0.0-alpha.129 → 5.0.0-alpha.133

package/dist/cli.mjs

@@ -184,6 +184,7 @@ const CARDINALITY = {
 	analytics: "many",
 	errors: "single",
 	logs: "single",
+	monitoring: "single",
 	wiki: "single",
 	workers: "single"
 };
@@ -305,9 +306,9 @@ function resolveConfig(raw) {
 //#endregion
 //#region src/commands/contexts.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.
+* 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`
@@ -317,33 +318,33 @@ function resolveConfig(raw) {
 */
 const COMMAND_CONTEXTS = {
 	clone: "global",
-	new: "global",
-	"upgrade node": "global",
-	"upgrade deps": "global",
-	"plugin create": "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",
-	"bump-versions": "global",
-	publish: "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",
+	"deploy on-release": "repo-aware",
 	"config show": "repo-aware",
-	"sync-readme": "repo-aware",
+	"repo sync readme": "repo-aware",
 	doctor: "workspace",
-	setup: "workspace",
-	"secret set": "workspace",
+	"repo setup": "workspace",
+	"secrets set": "workspace",
 	"secrets sync": "workspace",
 	deploy: "workspace",
-	"cleanup-preview": "workspace",
-	sync: "workspace",
-	"sync-github": "workspace"
+	"deploy cleanup-preview": "workspace",
+	"repo sync": "workspace",
+	"sync github": "workspace"
 };
 /**
 * The context for a command name from `argv._`. Falls back to the leading
@@ -352,8 +353,11 @@ const COMMAND_CONTEXTS = {
 */
 function contextForCommand(name) {
 	const map = COMMAND_CONTEXTS;
-	if (map[name]) return map[name];
-	return map[name.split(" ")[0] ?? ""];
+	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) {
@@ -1067,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
@@ -1790,6 +1794,14 @@ 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) {
@@ -1810,7 +1822,7 @@ function mk(capability, provider, status, message) {
 //#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.
@@ -2164,7 +2176,7 @@ async function runNew(input) {
 			};
 		}
 		print("");
-		print("  Running holocron setup…");
+		print("  Running holocron repo setup…");
 		try {
 			const setupArgs = ["setup"];
 			const setupEnv = {};
@@ -2184,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("");
@@ -2194,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({
@@ -2550,12 +2562,12 @@ function render$10(inputs) {
 		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\`.`,
 		keywords,
-		homepage: `https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme`,
+		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",
@@ -2680,7 +2692,7 @@ export * from "./auth.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
@@ -2747,7 +2759,7 @@ 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.
 `;
 }
@@ -2910,7 +2922,7 @@ 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
@@ -2935,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;
@@ -3118,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`.
@@ -3126,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.
@@ -3236,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({
@@ -3340,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}\`.`);
 }
 /**
@@ -3397,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
@@ -3411,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.
 *
@@ -3427,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
@@ -3709,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,
@@ -3734,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
@@ -3874,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,
@@ -4008,7 +4020,7 @@ const defaultLogin = async (cwd) => {
 //#endregion
 //#region src/commands/secret-set.ts
 /**
-* `holocron secret set` — one-shot single-secret push.
+* `holocron secrets set` — one-shot single-secret push.
 *
 * Complements `holocron secrets sync` (bulk vault → destinations) for
 * ad-hoc scenarios:
@@ -4030,7 +4042,7 @@ async function runSecretSet(input) {
 	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");
@@ -4129,7 +4141,7 @@ function describeScope(scope) {
 *
 * 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 secret set` (also planned for v5.1).
+* individually via `holocron secrets set` (also planned for v5.1).
 */
 async function runSecretsSync(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -4334,7 +4346,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
@@ -4462,7 +4474,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") {
@@ -4486,7 +4498,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");
@@ -4528,7 +4540,7 @@ const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cl
 /**
 * `.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 setup` when
+* 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
@@ -4608,7 +4620,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.
 *
@@ -4629,7 +4641,7 @@ var pre_push_default = "# Run the merge-gating checks locally before pushing —
 const { workflowHeader: workflowHeader$4 } = createHeader({ source: "packages/cli/src/templates/configs/pre-push/create-config.ts" });
 /**
 * `.husky/pre-push` — runs `holocron run ci` (the merge-gating checks, in CI order)
-* before every push. Installed by `holocron setup` when hooks are enabled
+* 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
@@ -4676,7 +4688,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.
 *
@@ -5463,7 +5475,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
@@ -5483,18 +5495,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 = [];
@@ -6036,6 +6048,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"));
@@ -6122,7 +6145,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 {
@@ -6160,7 +6183,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).
@@ -6627,7 +6650,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",
@@ -7363,7 +7386,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).
 */
@@ -7389,7 +7412,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("");
@@ -7581,7 +7604,7 @@ 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) {
@@ -7599,7 +7622,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:
@@ -8191,13 +8214,119 @@ 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 ci` is a
-* concrete, prompt-free entry, so it stays.) `run lint commit-msg <file>` is
-* excluded for the same reason: it's invoked exclusively from
-* `.husky/commit-msg "$1"`, never typed by a human.
+* `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 = [
 	{
@@ -8218,13 +8347,13 @@ const COMMAND_REGISTRY = [
 		supportsDryRun: true
 	},
 	{
-		name: "setup",
+		name: "repo setup",
 		description: "Apply infra setup actions across every configured capability",
 		positionals: [],
 		supportsDryRun: true
 	},
 	{
-		name: "secret set",
+		name: "secrets set",
 		description: "Set a single secret via the configured `secrets` capability",
 		positionals: [{
 			key: "name",
@@ -8254,7 +8383,7 @@ const COMMAND_REGISTRY = [
 		supportsDryRun: true
 	},
 	{
-		name: "cleanup-preview",
+		name: "deploy cleanup-preview",
 		description: "List and delete Cloudflare Pages preview deployments for a GitHub PR",
 		positionals: [{
 			key: "pr",
@@ -8265,7 +8394,13 @@ const COMMAND_REGISTRY = [
 		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",
@@ -8276,13 +8411,13 @@ const COMMAND_REGISTRY = [
 		supportsDryRun: true
 	},
 	{
-		name: "publish",
+		name: "package publish",
 		description: "Publish @theholocron/* packages to npm",
 		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: [],
 		supportsDryRun: true
@@ -8294,13 +8429,13 @@ const COMMAND_REGISTRY = [
 		supportsDryRun: true
 	},
 	{
-		name: "sync-github",
+		name: "sync github",
 		description: "Sync workflow templates and composite actions to theholocron/.github",
 		positionals: [],
 		supportsDryRun: true
 	},
 	{
-		name: "sync-readme",
+		name: "repo sync readme",
 		description: "Sync the Installation + Usage block in README.md from package.json",
 		positionals: [],
 		supportsDryRun: true
@@ -8311,13 +8446,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: [],
 		supportsDryRun: true
 	},
 	{
-		name: "plugin create",
+		name: "new plugin",
 		description: "Scaffold a new @theholocron/holocron-plugin-<slug> package",
 		positionals: [{
 			key: "slug",
@@ -8334,25 +8469,22 @@ const COMMAND_REGISTRY = [
 		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",
@@ -8360,14 +8492,12 @@ 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
 	},
 	{
@@ -8377,8 +8507,7 @@ const COMMAND_REGISTRY = [
 			key: "provider",
 			message: "Provider name:",
 			type: "input"
-		}],
-		group: "auth"
+		}]
 	},
 	{
 		name: "auth unset",
@@ -8388,8 +8517,7 @@ const COMMAND_REGISTRY = [
 			message: "Provider:",
 			type: "select",
 			choices: listStoredProviders
-		}],
-		group: "auth"
+		}]
 	},
 	{
 		name: "auth check",
@@ -8399,14 +8527,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`. */
@@ -8415,36 +8541,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
@@ -8498,10 +8677,10 @@ function forwardedFlags(argv, dryRunOverride) {
 	if (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
 	return out;
 }
-/** `entry.name` split into tokens, resolved positionals appended, then forwarded flags. */
+/** `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, dryRunOverride)
 	];
@@ -8554,14 +8733,17 @@ function shouldPreviewDryRun(entry, parentArgv) {
 	return Boolean(entry.supportsDryRun) && parentArgv.skipDryRun !== true;
 }
 /**
-* 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").
+* 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}),
@@ -8573,9 +8755,24 @@ function shouldPreviewDryRun(entry, parentArgv) {
 * 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 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" });
@@ -9048,6 +9245,10 @@ function tokenContext(rawTokens) {
 		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 = () => {};
@@ -9090,7 +9291,7 @@ try {
 		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,
@@ -9161,28 +9362,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 run 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),
@@ -9215,399 +9394,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", {
+			...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 loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		const report = await runSyncReadme({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun
+			}
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`repo sync readme: ${report.message}`);
+			process.exitCode = 1;
+		}
+	}).positional("steps", {
 		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", {
+		array: true,
+		describe: "Steps to run: labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki (default: all)"
+	}).option("repo", {
 		type: "string",
-		default: "repo",
-		describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
+		describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
 	}), 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({
+		if ((await runSync({
 			loaded,
 			context: {
 				repoRoot: argv.cwd,
 				dryRun: argv.dryRun,
+				...argv.repo ? { repo: argv.repo } : {},
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			environmentId,
-			...argv.projectId ? { projectId: argv.projectId } : {},
-			...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
-			githubSecretScope,
-			targets: argv.target
+			...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
 		})).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 (omit when using --files)"
-	}).option("project-id", {
-		type: "string",
-		demandOption: true,
-		describe: "Deployment project id (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) => {
-		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("cleanup-preview [pr]", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
+	}).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) {
-				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,
-			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. `run ci` runs every merge-gating check; `run lint commit-msg <file>` lints a commit message.", (y) => y.positional("task", {
-		type: "string",
-		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: "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: "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: "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("deploy-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."
+		describe: "Target Node.js major version (e.g., 22)"
 	}).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."
+		type: "number",
+		describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
 	}), async (argv) => {
-		if ((await deployOnRelease({
+		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,
-			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;
-	}).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) {
-			reportError(`sync-github: ${err instanceof AuthError ? err.message : String(err)}`);
+			extra
+		});
+		if (report.status === "fail") {
+			if (report.message) reportError(`upgrade node: ${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", {
+	}).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",
-		describe: "Print what would change without writing",
-		default: false
+		default: false,
+		describe: "Only bump the catalog pins — skip the holocron.config.ts migration"
 	}), async (argv) => {
-		const loaded = await loadConfig(argv.cwd);
-		applyResolvedConfig(argv, loaded.resolved);
-		const report = await runSyncReadme({
-			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun
-			}
+		const report = await runUpgradeDeps({
+			cwd: argv.cwd,
+			dryRun: argv.dryRun,
+			pinsOnly: argv.pinsOnly
 		});
 		if (report.status === "fail") {
-			if (report.message) reportError(`sync-readme: ${report.message}`);
+			if (report.message) reportError(`upgrade deps: ${report.message}`);
 			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("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", {
@@ -9656,7 +9650,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);
@@ -9872,129 +9866,351 @@ try {
 			}
 			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", {
+		type: "string",
+		describe: "Vendor display name (PascalCase)"
+	}).option("capability", {
+		type: "string",
+		describe: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|errors|logs|wiki|workers"
+	}).option("token-env", {
+		type: "string",
+		describe: "Holocron env var name (defaults to HOLOCRON_<VENDOR>_TOKEN)"
+	}).option("vendor-env", {
+		type: "string",
+		describe: "Vendor-native env var name"
+	}).option("base-url", {
+		type: "string",
+		describe: "REST base URL"
+	}).option("verify", {
+		type: "boolean",
+		default: true,
+		describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
+	}), async (argv) => {
+		try {
+			const [slug, vendor] = await promptForPositionals(getEntry("new plugin"), argv);
+			const { capability, vendorEnv, baseUrl } = await resolvePluginCreateInputs({
+				capability: argv.capability,
+				vendorEnv: argv.vendorEnv,
+				baseUrl: argv.baseUrl
+			}, {
+				selectCapability: () => select({
+					message: "Capability:",
+					choices: Object.keys(CARDINALITY).map((k) => ({
+						name: k,
+						value: k
+					}))
+				}),
+				inputVendorEnv: () => input({ message: `Vendor-native env var for the ${vendor} token (e.g. MYVENDOR_API_KEY):` }),
+				inputBaseUrl: () => input({ message: `REST base URL for the ${vendor} API (e.g. https://api.myvendor.com):` })
+			});
+			if (runPluginCreate({
+				slug,
+				vendorName: vendor,
+				capability,
+				vendorEnv,
+				baseUrl,
+				...argv.tokenEnv ? { tokenEnv: argv.tokenEnv } : {},
+				dryRun: argv.dryRun,
+				noVerify: !argv.verify,
+				cwd: argv.cwd
+			}).status === "fail") process.exitCode = 1;
+		} catch (err) {
+			if (err instanceof PluginCreateError) {
+				reportError(`plugin create: ${err.message}`);
+				process.exitCode = 1;
+				return;
+			}
+			throw err;
+		}
+	}).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 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: "Package slug (kebab-case)"
-	}).positional("vendor", {
+		describe: "Commit message (default: chore: sync from theholocron/holocron)"
+	}).option("output-dir", {
 		type: "string",
-		describe: "Vendor display name (PascalCase)"
-	}).option("capability", {
+		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;
+		}
+		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: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|errors|logs|wiki|workers"
-	}).option("token-env", {
+		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: "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: "Holocron env var name (defaults to HOLOCRON_<VENDOR>_TOKEN)"
-	}).option("vendor-env", {
+		describe: "npm distribution tag. Defaults to alpha for --initial, latest for a steady-state publish."
+	}).option("otp", {
 		type: "string",
-		describe: "Vendor-native env var name"
-	}).option("base-url", {
+		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: "REST base URL"
-	}).option("verify", {
+		describe: "owner/repo for Trusted Publisher config (--sync-trust). Defaults to theholocron/holocron."
+	}).option("provenance", {
 		type: "boolean",
 		default: true,
-		describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
+		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) => {
-		try {
-			const [slug, vendor] = await promptForPositionals(getEntry("plugin create"), argv);
-			const { capability, vendorEnv, baseUrl } = await resolvePluginCreateInputs({
-				capability: argv.capability,
-				vendorEnv: argv.vendorEnv,
-				baseUrl: argv.baseUrl
-			}, {
-				selectCapability: () => select({
-					message: "Capability:",
-					choices: Object.keys(CARDINALITY).map((k) => ({
-						name: k,
-						value: k
-					}))
-				}),
-				inputVendorEnv: () => input({ message: `Vendor-native env var for the ${vendor} token (e.g. MYVENDOR_API_KEY):` }),
-				inputBaseUrl: () => input({ message: `REST base URL for the ${vendor} API (e.g. https://api.myvendor.com):` })
-			});
-			if (runPluginCreate({
-				slug,
-				vendorName: vendor,
-				capability,
-				vendorEnv,
-				baseUrl,
-				...argv.tokenEnv ? { tokenEnv: argv.tokenEnv } : {},
-				dryRun: argv.dryRun,
-				noVerify: !argv.verify,
-				cwd: argv.cwd
-			}).status === "fail") process.exitCode = 1;
-		} catch (err) {
-			if (err instanceof PluginCreateError) {
-				reportError(`plugin create: ${err.message}`);
+		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;
 			}
-			throw err;
+			if ((await runSyncTrust({
+				cwd: argv.cwd,
+				oldFile,
+				newFile,
+				dryRun: argv.dryRun,
+				...argv.repo ? { repo: argv.repo } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
 		}
-	}).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", {
+		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("$0", false, () => {}, async (argv) => {
+		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: "Target Node.js major version (e.g., 22)"
+		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("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: "number",
-		describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
+		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) => {
-		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 } : {},
+		if ((await deployOnRelease({
 			cwd: argv.cwd,
+			channel: argv.channel,
+			...argv.from ? { from: argv.from } : {},
+			...argv.to ? { to: argv.to } : {},
 			dryRun: argv.dryRun,
-			extra
-		});
-		if (report.status === "fail") {
-			if (report.message) reportError(`upgrade node: ${report.message}`);
+			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;
 		}
-	}).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: "Only bump the catalog pins — skip the holocron.config.ts migration"
-	}), async (argv) => {
-		const report = await runUpgradeDeps({
-			cwd: argv.cwd,
+		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,
-			pinsOnly: argv.pinsOnly
-		});
-		if (report.status === "fail") {
-			if (report.message) reportError(`upgrade deps: ${report.message}`);
-			process.exitCode = 1;
+			...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;
 		}
-	}).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 } : {}
-		})).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 } : {}
+		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) => {
-		printVersionHeaderOnce();
-		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)) {