@theholocron/cli 5.0.0-alpha.152 → 5.0.0-alpha.153

package/dist/cli.mjs

@@ -4,8 +4,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSyn
 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 { KNOWN_WORKFLOWS, createAlexignore, createAlexrc, createAstromech, createCommitMsg, createDependabot, createDevmoji, createEditorconfig, createEditorconfigChecker, createHeader, createLabeler, createPreCommit, createPrePush, createPrepareCommitMsg, createYamlignore, createYamllint, deployOnRelease, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
+import { lintCommitMsgFile } from "@theholocron/astromech/lint";
 import { LOG_LEVELS, NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -14,14 +15,16 @@ import { createEnvLookup, firstEnv, withEnvPrefix } from "@theholocron/env-utils
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { pathToFileURL } from "node:url";
 import { errorMessage } from "@theholocron/misc-utils";
+import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
+import { readGitRemote, updateGitignore } from "@theholocron/git-utils";
+import { listWorkspacePackagesSync, readPackageJson, readPackageJsonSync } from "@theholocron/pkg-utils";
 import { createLogger, isCI, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
 import chalk from "chalk";
-import ora from "ora";
+import search from "@inquirer/search";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
+import ora from "ora";
 import { findRootSync, walkFilesSync } from "@theholocron/fs-utils";
 import { stringifyJson } from "@theholocron/json-utils";
-import { listWorkspacePackagesSync, readPackageJson, readPackageJsonSync } from "@theholocron/pkg-utils";
-import { readGitRemote, updateGitignore } from "@theholocron/git-utils";
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
@@ -29,11 +32,7 @@ import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getU
 import { createGitHubClient } from "@theholocron/github-client";
 import { PostHogSink } from "@theholocron/observability/analytics";
 import { SentrySink } from "@theholocron/observability/errors";
-import load from "@commitlint/load";
-import lint from "@commitlint/lint";
-import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
-import search from "@inquirer/search";
-//#region src/env.ts
+//#region src/env/env.ts
 /** Singleton env for simple global lookups throughout the CLI. */
 const env = createEnvLookup();
 /**
@@ -51,7 +50,7 @@ function makeEnv(source) {
 	return createEnvLookup(source);
 }
 //#endregion
-//#region src/auth/keyring.ts
+//#region src/auth/keyring/keyring.ts
 /**
 * Keyring-backed bootstrap credential store.
 *
@@ -121,7 +120,7 @@ function listStoredProviders() {
 	}
 }
 //#endregion
-//#region src/auth/auth-resolver.ts
+//#region src/auth/auth-resolver/auth-resolver.ts
 /**
 * Build a strict, single-feature token resolver.
 *
@@ -139,7 +138,7 @@ function createFeatureResolver(config) {
 	};
 }
 //#endregion
-//#region src/auth/token-args.ts
+//#region src/auth/token-args/token-args.ts
 var TokenParseError = class extends Error {
 	name = "TokenParseError";
 };
@@ -177,7 +176,7 @@ function parseTokenArgs(tokens) {
 	return result;
 }
 //#endregion
-//#region src/plugin/capabilities.ts
+//#region src/plugin/capabilities/capabilities.ts
 const CARDINALITY = {
 	source: "single",
 	ci: "single",
@@ -205,7 +204,7 @@ const CARDINALITY = {
 */
 const REQUIRED_CAPABILITIES = [];
 //#endregion
-//#region src/config/config.ts
+//#region src/config/config/config.ts
 var ConfigError = class extends Error {
 	name = "ConfigError";
 };
@@ -314,7 +313,64 @@ function resolveConfig(raw) {
 	};
 }
 //#endregion
-//#region src/commands/contexts.ts
+//#region src/config/load-config/load-config.ts
+/**
+* `holocron.config.{ts,js,mjs,cjs,json}` loader.
+*
+* File discovery + module loading (typed configs via `tsx`, no build
+* step) is delegated to `@theholocron/datapad`. This module keeps the
+* holocron-specific parts: filling `name` / `repo.name` defaults and
+* running the config through `resolveConfig`.
+*
+* Probe order is TS-first (`.ts` → `.js` → `.mjs` → `.cjs` → `.json`) —
+* see ADR-0010 / issue #75 / #81.
+*/
+/**
+* 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 fails schema checks.
+*/
+async function loadConfig(cwd) {
+	const found = await loadConfigFile({
+		cwd,
+		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 {
+		resolved: resolveConfig(await deriveDefaults$1(found)),
+		filepath: found.filepath
+	};
+}
+async function deriveDefaults$1(found) {
+	const configDir = dirname(found.filepath);
+	const result = { ...found.config };
+	if (!result.name) result.name = await readPackageJsonName(configDir) ?? basename(configDir);
+	if (result.repo && !result.repo.name) {
+		const remote = await readGitRemote(configDir);
+		if (remote?.host === "github.com") result.repo = {
+			...result.repo,
+			name: remote.slug
+		};
+	}
+	const manifest = await loadTasksConfig(configDir, { holocron: found });
+	if (manifest.tasks) result.tasks = manifest.tasks;
+	if (manifest.syncScripts !== void 0) result.syncScripts = manifest.syncScripts;
+	if (manifest.holocronScript !== void 0) result.holocronScript = manifest.holocronScript;
+	if (manifest.hooks !== void 0) result.hooks = manifest.hooks;
+	if (manifest.extraRequiredChecks) result.extraRequiredChecks = [...result.extraRequiredChecks ?? [], ...manifest.extraRequiredChecks];
+	return result;
+}
+async function readPackageJsonName(dir) {
+	const name = (await readPackageJson(dir))?.name;
+	return name === void 0 ? void 0 : name.replace(/^@[^/]+\//, "");
+}
+//#endregion
+//#region src/commands/contexts/contexts.ts
 /**
 * Command → context. Keys are the full command path as it lands in
 * yargs' `argv._` (`"auth set"`, `"repo upgrade node"`), the bare verb
@@ -375,183 +431,556 @@ 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. `--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;
-}
+//#region src/ui/non-interactive-error/non-interactive-error.ts
 /**
-* 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.
+* Raised when a prompt is needed but stdin isn't a TTY. A non-TTY run (CI, a
+* script, a pipe) throws this instead of hanging on `@inquirer/prompts`, which
+* otherwise throws its own `ExitPromptError` the moment stdin closes. `cli.ts`'s
+* `USER_FACING_ERRORS` catch prints the message cleanly.
 */
-function resolveConsoleOutput(argv) {
-	if (argv.log || argv.verbose || argv.quiet) return true;
-	return isCI() ? void 0 : false;
+var NonInteractiveError = class extends Error {
+	name = "NonInteractiveError";
+};
+//#endregion
+//#region src/ui/json-view/json-view.ts
+function isContainer(value) {
+	return typeof value === "object" && value !== null;
 }
-let root;
-let rootLevel;
-let rootCommand;
-let rootAxiomKey;
-/**
-* 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 isGlobal = contextForCommand(opts.command ?? rootCommand ?? "") === "global";
-	if (!isGlobal) {
-		const fromEnv = resolveAxiomFromEnv();
-		if (fromEnv) return fromEnv;
-	}
-	const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : holocronEnv.get("AXIOM_DATASET") ?? opts.configAxiomDataset;
-	if (!dataset) return void 0;
-	const org = opts.org ?? env.get("HOLOCRON_ORG");
-	const token = holocronEnv.get("AXIOM_TOKEN") || (org ? getToken(`axiom.${org}`) : null) || getToken("axiom");
-	return token ? {
-		dataset,
-		token
-	} : void 0;
+function childrenOf(value) {
+	return Array.isArray(value) ? value.map((v, i) => [String(i), v]) : Object.entries(value);
 }
-/**
-* The process-wide root logger. Built once (from `cli.ts`'s middleware,
-* with the command name + flags + env). Rebuilt at most once more when a
-* command's handler supplies `holocron.config` context the flag/env-only
-* first pass could not have known — `log.level` (unless `--verbose` /
-* `--quiet` already fixed it) or `log.axiom.dataset` + the resolved org
-* for a keyring-backed Axiom transport. That rebuild generates a fresh
-* `runId`, which is harmless: nothing logs between the middleware and the
-* handler.
-*/
-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 && !argv.log;
-	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
-		const built = createLogger({
-			...level ? { level } : {},
-			...axiom ? { axiom } : {},
-			...consoleOutput !== void 0 ? { consoleOutput } : {}
-		});
-		root = {
-			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
-			runId: built.runId
-		};
-		rootLevel = level;
-		rootAxiomKey = axiomKey;
-	}
-	return root;
+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));
 }
-/**
-* 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({ consoleOutput: resolveConsoleOutput({}) })).logger;
+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}}`);
 }
 /**
-* 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.
+* Paths of every container deeper than `depth` levels are left out, so those
+* render collapsed. `depth: 0` collapses the root; `Infinity` expands all.
 */
-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() {
-	return root?.runId;
+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;
 }
-//#endregion
-//#region src/plugin/loader.ts
-/**
-* `PluginLoader` — loads provider plugins per the resolved config and
-* builds a typed capability registry the runtime can query.
-*
-* Flow:
-*   1. Walk `config.providers[*]` from `resolveConfig()`
-*   2. For each entry, dynamic-import the resolved package name
-*      (`@theholocron/holocron-plugin-<provider>` by default)
-*   3. Call the package's exported `createPlugin(options)` to get a
-*      plugin object whose `capabilities` map holds factories
-*   4. Invoke the matching capability factory and stash the impl in
-*      the registry — single-cardinality entries hold one impl,
-*      many-cardinality entries hold an array
-*
-* A package may instead export a capability config (see
-* `CapabilityConfigPackage` in config.ts). The loader detects the shape
-* at import time and re-resolves to the underlying plugin, merging the
+/** 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/menu/menu.ts
+/**
+* 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 pickMenuItem(items, message = "What would you like to do?") {
+	return search({
+		message,
+		source: (term) => searchChoices(items, term)
+	});
+}
+/**
+* `@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 item.
+*/
+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
+	}));
+}
+//#endregion
+//#region src/ui/open-path/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/ui/progress/progress.ts
+/**
+* Runs `fn`, showing an ora spinner for its duration in TTY environments.
+* In non-TTY environments (CI, pipes, tests) the spinner is skipped entirely.
+*/
+async function withSpinner(label, fn) {
+	if (!process.stdout.isTTY) return fn();
+	const spinner = ora(label).start();
+	try {
+		const result = await fn();
+		spinner.succeed();
+		return result;
+	} catch (err) {
+		spinner.fail();
+		throw err;
+	}
+}
+//#endregion
+//#region src/ui/prompt-positionals/prompt-positionals.ts
+/**
+* For each of `entry.positionals` not already present in `argv`, prompts for
+* it (`input()` or `select()`, per the positional's `type`) and returns the
+* resolved values in positional order — ready to append to a spawned child's
+* argv, or to use directly in the current handler (Layer 3).
+*
+* Throws {@link NonInteractiveError} the first time it would need to prompt
+* on a non-TTY stdin, and again if a `select` positional's choices resolve
+* empty (nothing to pick from — e.g. `auth unset` with no stored tokens).
+*/
+async function promptForPositionals(entry, argv) {
+	const out = [];
+	for (const positional of entry.positionals) {
+		const existing = argv[positional.key];
+		if (existing !== void 0 && existing !== "") {
+			out.push(String(existing));
+			continue;
+		}
+		if (!process.stdin.isTTY) throw new NonInteractiveError(`\`${entry.name}\` needs "${positional.key}" — pass it directly: holocron ${entry.name} <${positional.cliArg ?? positional.key}>`);
+		if (positional.type === "select") {
+			const choices = typeof positional.choices === "function" ? positional.choices() : positional.choices ?? [];
+			if (choices.length === 0) throw new NonInteractiveError(`\`${entry.name}\`: no ${positional.key} to choose from — nothing stored yet`);
+			out.push(await select({
+				message: positional.message,
+				choices: choices.map((c) => ({ value: c }))
+			}));
+		} else out.push(await input({
+			message: positional.message,
+			...positional.validate ? { validate: positional.validate } : {}
+		}));
+	}
+	return out;
+}
+//#endregion
+//#region src/ui/style/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/ui/status-row/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/observability/logger/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
+* `resolve-telemetry.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. `--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.
+*
+* 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 isGlobal = contextForCommand(opts.command ?? rootCommand ?? "") === "global";
+	if (!isGlobal) {
+		const fromEnv = resolveAxiomFromEnv();
+		if (fromEnv) return fromEnv;
+	}
+	const dataset = isGlobal ? GLOBAL_AXIOM_DATASET : holocronEnv.get("AXIOM_DATASET") ?? opts.configAxiomDataset;
+	if (!dataset) return void 0;
+	const org = opts.org ?? env.get("HOLOCRON_ORG");
+	const token = holocronEnv.get("AXIOM_TOKEN") || (org ? getToken(`axiom.${org}`) : null) || getToken("axiom");
+	return token ? {
+		dataset,
+		token
+	} : void 0;
+}
+/**
+* The process-wide root logger. Built once (from `cli.ts`'s middleware,
+* with the command name + flags + env). Rebuilt at most once more when a
+* command's handler supplies `holocron.config` context the flag/env-only
+* first pass could not have known — `log.level` (unless `--verbose` /
+* `--quiet` already fixed it) or `log.axiom.dataset` + the resolved org
+* for a keyring-backed Axiom transport. That rebuild generates a fresh
+* `runId`, which is harmless: nothing logs between the middleware and the
+* handler.
+*/
+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 && !argv.log;
+	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
+		const built = createLogger({
+			...level ? { level } : {},
+			...axiom ? { axiom } : {},
+			...consoleOutput !== void 0 ? { consoleOutput } : {}
+		});
+		root = {
+			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
+			runId: built.runId
+		};
+		rootLevel = level;
+		rootAxiomKey = axiomKey;
+	}
+	return root;
+}
+/**
+* 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({ 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() {
+	return root?.runId;
+}
+//#endregion
+//#region src/plugin/loader/loader.ts
+/**
+* `PluginLoader` — loads provider plugins per the resolved config and
+* builds a typed capability registry the runtime can query.
+*
+* Flow:
+*   1. Walk `config.providers[*]` from `resolveConfig()`
+*   2. For each entry, dynamic-import the resolved package name
+*      (`@theholocron/holocron-plugin-<provider>` by default)
+*   3. Call the package's exported `createPlugin(options)` to get a
+*      plugin object whose `capabilities` map holds factories
+*   4. Invoke the matching capability factory and stash the impl in
+*      the registry — single-cardinality entries hold one impl,
+*      many-cardinality entries hold an array
+*
+* A package may instead export a capability config (see
+* `CapabilityConfigPackage` in config.ts). The loader detects the shape
+* at import time and re-resolves to the underlying plugin, merging the
 * preset options with any per-project overrides from the config file
 * (project options win, mirroring ESLint's `extends` precedence).
 *
@@ -699,7 +1128,111 @@ function isCapabilityConfigModule(mod) {
 	return typeof mod.default?.provider === "string";
 }
 //#endregion
-//#region src/plugin/workspace.ts
+//#region src/plugin/run-check/run-check.ts
+async function runCheckAgainstUrl(input, opts = {}) {
+	const doFetch = opts.fetch ?? fetch;
+	const url = resolveUrl(input.url, opts.url);
+	const method = input.method ?? "GET";
+	const hasBody = input.body !== void 0 && method !== "GET" && method !== "HEAD";
+	const needsBody = (input.assertions ?? []).some((a) => a.source === "body");
+	const start = Date.now();
+	let response;
+	let bodyText = "";
+	try {
+		response = await doFetch(url, {
+			method,
+			...hasBody ? { body: input.body } : {},
+			redirect: "manual",
+			signal: AbortSignal.timeout(opts.timeoutMs ?? 1e4)
+		});
+		if (needsBody) bodyText = await readBodyCapped(response, opts.maxBodyBytes ?? 1e6);
+	} catch (err) {
+		return {
+			passed: false,
+			failures: [],
+			requestError: requestErrorMessage(err)
+		};
+	}
+	const responseTimeMs = Date.now() - start;
+	const failures = [];
+	if (!input.shouldFail && response.status >= 400) failures.push(`HTTP ${response.status} (>= 400 counts as a failure unless \`shouldFail\` is set)`);
+	for (const assertion of input.assertions ?? []) {
+		const actual = extractActual(assertion, {
+			response,
+			bodyText,
+			responseTimeMs
+		});
+		if (!evaluate(assertion.comparison, actual, assertion.target)) failures.push(`${assertion.source} ${assertion.comparison} "${assertion.target ?? ""}" — got "${truncate(actual)}"`);
+	}
+	return {
+		passed: failures.length === 0,
+		status: response.status,
+		responseTimeMs,
+		failures
+	};
+}
+/** Swaps in `overrideUrl`'s origin, keeping `originalUrl`'s own path + query. */
+function resolveUrl(originalUrl, overrideUrl) {
+	if (!overrideUrl) return originalUrl;
+	const original = new URL(originalUrl);
+	const resolved = new URL(overrideUrl);
+	resolved.pathname = original.pathname;
+	resolved.search = original.search;
+	return resolved.toString();
+}
+function requestErrorMessage(err) {
+	if (err instanceof Error) return err.name === "TimeoutError" ? `request timed out: ${err.message}` : err.message;
+	return String(err);
+}
+/** Reads up to `maxBytes` of the response body, discarding the rest — a large/unending body can't exhaust memory. */
+async function readBodyCapped(response, maxBytes) {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const remaining = maxBytes - total;
+			if (remaining <= 0) break;
+			const stored = value.length > remaining ? value.slice(0, remaining) : value;
+			chunks.push(stored);
+			total += stored.length;
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8");
+}
+/** Keeps a failure message readable when `actual` is a full HTML/JSON response body. */
+function truncate(value, max = 200) {
+	return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+function extractActual(assertion, ctx) {
+	switch (assertion.source) {
+		case "status_code": return String(ctx.response.status);
+		case "response_time": return String(ctx.responseTimeMs);
+		case "body": return ctx.bodyText;
+		case "header": {
+			const name = assertion.property ?? "";
+			return name ? ctx.response.headers.get(name) ?? "" : "";
+		}
+	}
+}
+function evaluate(comparison, actual, target) {
+	const t = target ?? "";
+	switch (comparison) {
+		case "equals": return actual === t;
+		case "not_equals": return actual !== t;
+		case "contains": return actual.includes(t);
+		case "not_contains": return !actual.includes(t);
+		case "greater_than": return Number(actual) > Number(t);
+		case "less_than": return Number(actual) < Number(t);
+	}
+}
+//#endregion
+//#region src/plugin/workspace/workspace.ts
 /**
 * The `workspace`-context guard.
 *
@@ -769,25 +1302,7 @@ function assertPluginsResolvable(loader, command) {
 	throw new WorkspaceContextError(command, [...new Set(failures.map((f) => f.packageName))]);
 }
 //#endregion
-//#region src/ui/progress.ts
-/**
-* Runs `fn`, showing an ora spinner for its duration in TTY environments.
-* In non-TTY environments (CI, pipes, tests) the spinner is skipped entirely.
-*/
-async function withSpinner(label, fn) {
-	if (!process.stdout.isTTY) return fn();
-	const spinner = ora(label).start();
-	try {
-		const result = await fn();
-		spinner.succeed();
-		return result;
-	} catch (err) {
-		spinner.fail();
-		throw err;
-	}
-}
-//#endregion
-//#region src/commands/auth.ts
+//#region src/commands/auth/auth.ts
 /**
 * `holocron auth <subcommand>` — manage bootstrap credentials in the
 * OS keyring.
@@ -1068,7 +1583,7 @@ async function tryLoadHint(importer, packageName) {
 	}
 }
 //#endregion
-//#region src/commands/cleanup-preview.ts
+//#region src/commands/cleanup-preview/cleanup-preview.ts
 function prStateLabel(pr) {
 	if (pr.merged) return style.success("merged");
 	if (pr.state === "closed") return style.dim("closed (not merged)");
@@ -1208,28 +1723,7 @@ 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
+//#region src/commands/clone/clone.ts
 /**
 * Accepts a bare org (`"theholocron"`) — clones every repo in it — or an
 * `org/repo` coordinate (`"theholocron/new-repo"`) — clones just that one
@@ -1426,7 +1920,7 @@ async function runClone(input) {
 	};
 }
 //#endregion
-//#region src/commands/deploy.ts
+//#region src/commands/deploy/deploy.ts
 /**
 * `holocron deploy` — trigger a deployment via the configured
 * `deployment` capability.
@@ -1666,7 +2160,7 @@ async function runDeployFromFiles(input) {
 	}
 }
 //#endregion
-//#region src/commands/doctor.ts
+//#region src/commands/doctor/doctor.ts
 /**
 * `holocron doctor` — load the config, instantiate every capability,
 * print a per-capability readiness report.
@@ -1812,117 +2306,13 @@ function countResolvedLifecycle(report) {
 function mk(capability, provider, status, message) {
 	return {
 		capability,
-		provider,
-		status,
-		message
-	};
-}
-//#endregion
-//#region src/plugin/run-check.ts
-async function runCheckAgainstUrl(input, opts = {}) {
-	const doFetch = opts.fetch ?? fetch;
-	const url = resolveUrl(input.url, opts.url);
-	const method = input.method ?? "GET";
-	const hasBody = input.body !== void 0 && method !== "GET" && method !== "HEAD";
-	const needsBody = (input.assertions ?? []).some((a) => a.source === "body");
-	const start = Date.now();
-	let response;
-	let bodyText = "";
-	try {
-		response = await doFetch(url, {
-			method,
-			...hasBody ? { body: input.body } : {},
-			redirect: "manual",
-			signal: AbortSignal.timeout(opts.timeoutMs ?? 1e4)
-		});
-		if (needsBody) bodyText = await readBodyCapped(response, opts.maxBodyBytes ?? 1e6);
-	} catch (err) {
-		return {
-			passed: false,
-			failures: [],
-			requestError: requestErrorMessage(err)
-		};
-	}
-	const responseTimeMs = Date.now() - start;
-	const failures = [];
-	if (!input.shouldFail && response.status >= 400) failures.push(`HTTP ${response.status} (>= 400 counts as a failure unless \`shouldFail\` is set)`);
-	for (const assertion of input.assertions ?? []) {
-		const actual = extractActual(assertion, {
-			response,
-			bodyText,
-			responseTimeMs
-		});
-		if (!evaluate(assertion.comparison, actual, assertion.target)) failures.push(`${assertion.source} ${assertion.comparison} "${assertion.target ?? ""}" — got "${truncate(actual)}"`);
-	}
-	return {
-		passed: failures.length === 0,
-		status: response.status,
-		responseTimeMs,
-		failures
-	};
-}
-/** Swaps in `overrideUrl`'s origin, keeping `originalUrl`'s own path + query. */
-function resolveUrl(originalUrl, overrideUrl) {
-	if (!overrideUrl) return originalUrl;
-	const original = new URL(originalUrl);
-	const resolved = new URL(overrideUrl);
-	resolved.pathname = original.pathname;
-	resolved.search = original.search;
-	return resolved.toString();
-}
-function requestErrorMessage(err) {
-	if (err instanceof Error) return err.name === "TimeoutError" ? `request timed out: ${err.message}` : err.message;
-	return String(err);
-}
-/** Reads up to `maxBytes` of the response body, discarding the rest — a large/unending body can't exhaust memory. */
-async function readBodyCapped(response, maxBytes) {
-	if (!response.body) return "";
-	const reader = response.body.getReader();
-	const chunks = [];
-	let total = 0;
-	try {
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			const remaining = maxBytes - total;
-			if (remaining <= 0) break;
-			const stored = value.length > remaining ? value.slice(0, remaining) : value;
-			chunks.push(stored);
-			total += stored.length;
-		}
-	} finally {
-		await reader.cancel().catch(() => {});
-	}
-	return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8");
-}
-/** Keeps a failure message readable when `actual` is a full HTML/JSON response body. */
-function truncate(value, max = 200) {
-	return value.length > max ? `${value.slice(0, max)}…` : value;
-}
-function extractActual(assertion, ctx) {
-	switch (assertion.source) {
-		case "status_code": return String(ctx.response.status);
-		case "response_time": return String(ctx.responseTimeMs);
-		case "body": return ctx.bodyText;
-		case "header": {
-			const name = assertion.property ?? "";
-			return name ? ctx.response.headers.get(name) ?? "" : "";
-		}
-	}
-}
-function evaluate(comparison, actual, target) {
-	const t = target ?? "";
-	switch (comparison) {
-		case "equals": return actual === t;
-		case "not_equals": return actual !== t;
-		case "contains": return actual.includes(t);
-		case "not_contains": return !actual.includes(t);
-		case "greater_than": return Number(actual) > Number(t);
-		case "less_than": return Number(actual) < Number(t);
-	}
+		provider,
+		status,
+		message
+	};
 }
 //#endregion
-//#region src/commands/monitoring-check.ts
+//#region src/commands/monitoring-check/monitoring-check.ts
 async function runMonitoringCheck(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1983,7 +2373,7 @@ async function runMonitoringCheck(input) {
 	};
 }
 //#endregion
-//#region src/commands/new.ts
+//#region src/commands/new/new.ts
 /**
 * `holocron new repo <type> <name>` — create a GitHub repo from a template and
 * bootstrap it by replacing all template-slug casing variants with the new
@@ -2377,7 +2767,7 @@ async function runNew(input) {
 	};
 }
 //#endregion
-//#region src/commands/npm-bump-versions.ts
+//#region src/commands/npm-bump-versions/npm-bump-versions.ts
 async function runNpmBumpVersions(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -2458,9 +2848,9 @@ async function runNpmBumpVersions(input) {
 	};
 }
 //#endregion
-//#region src/commands/plugin-create/template-inputs.ts
+//#region src/commands/plugin-create/template-inputs/template-inputs.ts
 /** Derive the standard defaults from a slug + vendor name. */
-function deriveDefaults$1(input) {
+function deriveDefaults(input) {
 	const vendorUpper = input.slug.toUpperCase().replace(/-/g, "_");
 	const capability = input.capability;
 	return {
@@ -3399,7 +3789,7 @@ function runPluginCreate(input) {
 	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({
+	const derived = deriveDefaults({
 		slug: input.slug,
 		vendorName: input.vendorName,
 		capability: input.capability
@@ -3555,224 +3945,142 @@ function printNextSteps$1(print, inputs) {
 	print("    7. Commit + push when capability is functionally complete.");
 }
 //#endregion
-//#region src/commands/publish.ts
+//#region src/commands/publish/default-exec.ts
+const defaultExec$1 = async (cmd, args, opts) => {
+	const result = spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		exitCode: result.status ?? -1,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? ""
+	};
+};
+//#endregion
+//#region src/commands/publish/default-login.ts
 /**
-* `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
-* configured on it. So the first publish has to happen outside the OIDC
-* flow — a browser-auth session (`npm login --auth-type=web`) or an
-* ephemeral automation token. This command drives the login step itself
-* (when `npm whoami` shows you're not authenticated), runs the publish
-* step, and tells you exactly what to do next.
-*
-* Workflow:
-*
-*   $ pnpm install --frozen-lockfile
-*   $ pnpm build
-*   $ 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 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.
-*
-* If `NPM_TOKEN` is detected in env, the command prints a final
-* "revoke this token at <url>" reminder — same pattern as `rando vc
-* setup` for the ephemeral GH admin PAT.
+* Fully interactive — `npm login --auth-type=web` prints a URL and waits for
+* the browser flow to complete; the operator needs to see that live, so all
+* three stdio streams are inherited (unlike `defaultExec`, which pipes
+* stdout/stderr for capture).
 */
+const defaultLogin = async (cwd) => {
+	return { exitCode: spawnSync("npm", ["login", "--auth-type=web"], {
+		cwd,
+		stdio: "inherit"
+	}).status ?? -1 };
+};
+//#endregion
+//#region src/commands/publish/has-packages-dir.ts
+function hasPackagesDir(cwd) {
+	return existsSync(join(cwd, "packages"));
+}
+//#endregion
+//#region src/commands/publish/has-plugins-dir.ts
+/** `plugins/` — vendor capability providers, split from `packages/` as a sibling workspace root (#993). */
+function hasPluginsDir(cwd) {
+	return existsSync(join(cwd, "plugins"));
+}
+//#endregion
+//#region src/commands/publish/discover-manifests.ts
 /**
-* `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
-* Trusted Publisher to a workflow FILENAME per package, so renaming the
-* release workflow breaks OIDC publish (`ENEEDAUTH`) until every package's
-* config is updated to match.
-*
-* Requires npm@11.15.0+ (`npm trust`) — always shells out through
-* `npx -y npm@latest` regardless of the locally-installed npm version.
-*
-* npm's `trust` mutations — and reads, once a short-lived OTP grant lapses —
-* require a fresh interactive browser 2FA approval (an `EOTP` error with an
-* `authUrl`). No token bypasses this (npm's own docs: Granular Access Tokens
-* with the bypass-2FA option are explicitly unsupported for trust commands).
-* This command can't drive that browser step itself, so on the first `EOTP`
-* it stops immediately, prints the `authUrl`, and returns — the operator
-* approves it and re-runs; already-migrated packages are skipped on the next
-* pass, so it's safe to resume from wherever it stopped.
+* Monorepo (`packages/` and/or `plugins/` present): every workspace under
+* either. Single package (neither dir present): the root `package.json`.
+* Callers keep the public ones.
 */
-async function runSyncTrust(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	const cwd = input.cwd ?? process.cwd();
-	const repo = input.repo ?? "theholocron/holocron";
-	const dryRun = input.dryRun ?? false;
-	const exec = input.exec ?? defaultExec$1;
-	const packageNames = input.packages ?? discoverPublicPackages(cwd);
-	const npm = "npx";
-	const npmArgs = ["-y", "npm@latest"];
-	print(`Holocron publish --sync-trust${dryRun ? " (dry-run)" : ""}`);
-	print(`  ${input.oldFile} -> ${input.newFile}  (repo: ${repo})`);
-	print(`  ${packageNames.length} public packages`);
-	print("");
-	logger.info({
-		oldFile: input.oldFile,
-		newFile: input.newFile,
-		packages: packageNames.length
-	}, "sync-trust: start");
-	if (packageNames.length === 0) {
-		const message = "nothing to sync (no packages/*, plugins/*, or root package.json is private or unnamed)";
-		print(`  ✗ ${message}`);
-		return {
-			status: "fail",
-			message,
-			packages: []
-		};
-	}
-	if (dryRun) {
-		for (const name of packageNames) print(`  … would sync ${name}`);
-		return {
-			status: "dry-run",
-			message: "dry-run — no npm calls made",
-			packages: []
-		};
-	}
-	const results = [];
-	for (const name of packageNames) {
-		print(`=== ${name} ===`);
-		const parsed = parseJson((await exec(npm, [
-			...npmArgs,
-			"trust",
-			"list",
-			name,
-			"--json"
-		], { cwd })).stdout);
-		if (isEotp(parsed)) {
-			const authUrl = parsed.error?.authUrl ?? "";
-			print(`  needs fresh 2FA — open and approve: ${authUrl}`);
-			print("  then re-run; already-migrated packages are skipped.");
-			results.push({
-				name,
-				status: "needs-auth",
-				message: authUrl
-			});
-			logger.warn({
-				package: name,
-				authUrl
-			}, "sync-trust: needs auth, stopping");
-			return {
-				status: "fail",
-				message: "npm 2FA grant needed — see printed authUrl",
-				packages: results
-			};
-		}
-		const entry = parsed;
-		if (entry.file === input.newFile) {
-			print(`  already on ${input.newFile}, skipping`);
-			results.push({
-				name,
-				status: "skipped"
-			});
-			continue;
-		}
-		if (entry.id) {
-			print(`  revoking existing trust (file=${entry.file ?? "?"}, id=${entry.id})`);
-			const revoke = await exec(npm, [
-				...npmArgs,
-				"trust",
-				"revoke",
-				name,
-				"--id",
-				entry.id,
-				"-y"
-			], { cwd });
-			if (revoke.exitCode !== 0 && isEotp(parseJson(revoke.stdout))) {
-				const authUrl = parseJson(revoke.stdout).error?.authUrl ?? "";
-				print(`  needs fresh 2FA — open and approve: ${authUrl}`);
-				results.push({
-					name,
-					status: "needs-auth",
-					message: authUrl
-				});
-				return {
-					status: "fail",
-					message: "npm 2FA grant needed — see printed authUrl",
-					packages: results
-				};
-			}
-		} else print("  no existing trust config found");
-		print(`  creating trust: ${input.newFile}`);
-		const create = await exec(npm, [
-			...npmArgs,
-			"trust",
-			"github",
-			name,
-			"--repo",
-			repo,
-			"--file",
-			input.newFile,
-			"--allow-publish",
-			"--allow-stage-publish",
-			"-y"
-		], { cwd });
-		if (create.exitCode === 0) {
-			print("  ✓ ok");
-			results.push({
-				name,
-				status: "ok"
-			});
-		} else {
-			const createParsed = parseJson(create.stdout);
-			if (isEotp(createParsed)) {
-				const authUrl = createParsed.error?.authUrl ?? "";
-				print(`  needs fresh 2FA — open and approve: ${authUrl}`);
-				results.push({
-					name,
-					status: "needs-auth",
-					message: authUrl
-				});
-				return {
-					status: "fail",
-					message: "npm 2FA grant needed — see printed authUrl",
-					packages: results
-				};
-			}
-			const message = create.stderr.trim() || create.stdout.trim() || `exit ${create.exitCode}`;
-			print(`  ✗ FAILED: ${message}`);
-			results.push({
-				name,
-				status: "fail",
-				message
-			});
-		}
+function discoverManifests(cwd) {
+	if (!hasPackagesDir(cwd) && !hasPluginsDir(cwd)) {
+		const manifest = readPackageJsonSync(cwd);
+		return manifest ? [{
+			manifest,
+			dir: "."
+		}] : [];
 	}
-	const failed = results.filter((r) => r.status === "fail");
-	logger.info({
-		ok: results.filter((r) => r.status === "ok").length,
-		failed: failed.length
-	}, "sync-trust: done");
-	return {
-		status: failed.length > 0 ? "fail" : "ok",
-		...failed.length > 0 ? { message: `${failed.length} package(s) failed` } : {},
-		packages: results
-	};
+	return listWorkspacePackagesSync(cwd).map(({ manifest, relativeDir }) => ({
+		manifest,
+		dir: `./${relativeDir}`
+	}));
 }
-function parseJson(raw) {
-	try {
-		return JSON.parse(raw);
-	} catch {
-		return;
+//#endregion
+//#region src/commands/publish/discover-public-packages.ts
+/** The names of `discoverPublicPackageEntries`' packages, without requiring a version. */
+function discoverPublicPackages(cwd) {
+	return discoverManifests(cwd).flatMap(({ manifest }) => !manifest.private && manifest.name ? [manifest.name] : []);
+}
+//#endregion
+//#region src/commands/publish/print-next-steps.ts
+function printNextSteps(print, env, packageNames, repoName) {
+	print("");
+	print("  → next: configure Trusted Publisher for each package on npm:");
+	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
+	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: delivery.publish.yml`);
+	if (env.get("NPM_TOKEN")) {
+		print("");
+		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
+		print("    https://www.npmjs.com/settings/~/tokens");
 	}
 }
-function isEotp(parsed) {
-	return typeof parsed === "object" && parsed !== null && "error" in parsed && parsed.error?.code === "EOTP";
+//#endregion
+//#region src/commands/publish/resolve-repo-name.ts
+async function resolveRepoName(cwd, exec) {
+	return (await readGitRemote(cwd, { exec: async (args, options) => {
+		const result = await exec("git", args, options);
+		if (result.exitCode !== 0) throw new Error(`git ${args.join(" ")} exited ${result.exitCode}`);
+		return result.stdout;
+	} }))?.repo ?? "unknown";
+}
+//#endregion
+//#region src/commands/publish/workspace-filter-args.ts
+/**
+* `-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] : [];
 }
+//#endregion
+//#region src/commands/publish/run-publish/run-publish.ts
+/**
+* `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
+* configured on it. So the first publish has to happen outside the OIDC
+* flow — a browser-auth session (`npm login --auth-type=web`) or an
+* ephemeral automation token. This command drives the login step itself
+* (when `npm whoami` shows you're not authenticated), runs the publish
+* step, and tells you exactly what to do next.
+*
+* Workflow:
+*
+*   $ pnpm install --frozen-lockfile
+*   $ pnpm build
+*   $ 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 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.
+*
+* If `NPM_TOKEN` is detected in env, the command prints a final
+* "revoke this token at <url>" reminder — same pattern as `rando vc
+* setup` for the ephemeral GH admin PAT.
+*/
 async function runPublish(input = {}) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -3893,6 +4201,23 @@ async function runPublish(input = {}) {
 		packageNames
 	};
 }
+//#endregion
+//#region src/commands/publish/discover-public-package-entries.ts
+/**
+* Every public package (`!private && name`) with its version and a
+* `pnpm --filter`-ready path — {@link runSteadyPublish}'s `skipAlreadyPublished`
+* mode needs both to check `npm view <pkg>@<version>` and publish one
+* workspace at a time.
+*/
+function discoverPublicPackageEntries(cwd) {
+	return discoverManifests(cwd).flatMap(({ manifest, dir }) => !manifest.private && manifest.name && manifest.version ? [{
+		name: manifest.name,
+		version: manifest.version,
+		dir
+	}] : []);
+}
+//#endregion
+//#region src/commands/publish/run-steady-publish/run-steady-publish.ts
 /**
 * `holocron package publish` (no `--initial`) — the steady-state publish
 * `exec.publishCmd` in `release.config.ts` should call, replacing each
@@ -4036,129 +4361,222 @@ async function runSteadyPublish(input = {}) {
 			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
 			print(`    pnpm exec holocron package publish --otp <6-digit-code>`);
 		}
-		logger.warn({
-			tag,
-			reason: message
-		}, "publish: done");
-		return {
-			status: "fail",
-			message,
-			packageNames
-		};
+		logger.warn({
+			tag,
+			reason: message
+		}, "publish: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	print("    ✓ publish complete");
+	logger.info({
+		tag,
+		status: "ok",
+		packages: entries.length
+	}, "publish: done");
+	return {
+		status: "ok",
+		packageNames
+	};
+}
+//#endregion
+//#region src/commands/publish/is-eotp.ts
+function isEotp(parsed) {
+	return typeof parsed === "object" && parsed !== null && "error" in parsed && parsed.error?.code === "EOTP";
+}
+//#endregion
+//#region src/commands/publish/parse-json.ts
+function parseJson(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/commands/publish/run-sync-trust/run-sync-trust.ts
+/**
+* `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
+* Trusted Publisher to a workflow FILENAME per package, so renaming the
+* release workflow breaks OIDC publish (`ENEEDAUTH`) until every package's
+* config is updated to match.
+*
+* Requires npm@11.15.0+ (`npm trust`) — always shells out through
+* `npx -y npm@latest` regardless of the locally-installed npm version.
+*
+* npm's `trust` mutations — and reads, once a short-lived OTP grant lapses —
+* require a fresh interactive browser 2FA approval (an `EOTP` error with an
+* `authUrl`). No token bypasses this (npm's own docs: Granular Access Tokens
+* with the bypass-2FA option are explicitly unsupported for trust commands).
+* This command can't drive that browser step itself, so on the first `EOTP`
+* it stops immediately, prints the `authUrl`, and returns — the operator
+* approves it and re-runs; already-migrated packages are skipped on the next
+* pass, so it's safe to resume from wherever it stopped.
+*/
+async function runSyncTrust(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const cwd = input.cwd ?? process.cwd();
+	const repo = input.repo ?? "theholocron/holocron";
+	const dryRun = input.dryRun ?? false;
+	const exec = input.exec ?? defaultExec$1;
+	const packageNames = input.packages ?? discoverPublicPackages(cwd);
+	const npm = "npx";
+	const npmArgs = ["-y", "npm@latest"];
+	print(`Holocron publish --sync-trust${dryRun ? " (dry-run)" : ""}`);
+	print(`  ${input.oldFile} -> ${input.newFile}  (repo: ${repo})`);
+	print(`  ${packageNames.length} public packages`);
+	print("");
+	logger.info({
+		oldFile: input.oldFile,
+		newFile: input.newFile,
+		packages: packageNames.length
+	}, "sync-trust: start");
+	if (packageNames.length === 0) {
+		const message = "nothing to sync (no packages/*, plugins/*, or root package.json is private or unnamed)";
+		print(`  ✗ ${message}`);
+		return {
+			status: "fail",
+			message,
+			packages: []
+		};
+	}
+	if (dryRun) {
+		for (const name of packageNames) print(`  … would sync ${name}`);
+		return {
+			status: "dry-run",
+			message: "dry-run — no npm calls made",
+			packages: []
+		};
+	}
+	const results = [];
+	for (const name of packageNames) {
+		print(`=== ${name} ===`);
+		const parsed = parseJson((await exec(npm, [
+			...npmArgs,
+			"trust",
+			"list",
+			name,
+			"--json"
+		], { cwd })).stdout);
+		if (isEotp(parsed)) {
+			const authUrl = parsed.error?.authUrl ?? "";
+			print(`  needs fresh 2FA — open and approve: ${authUrl}`);
+			print("  then re-run; already-migrated packages are skipped.");
+			results.push({
+				name,
+				status: "needs-auth",
+				message: authUrl
+			});
+			logger.warn({
+				package: name,
+				authUrl
+			}, "sync-trust: needs auth, stopping");
+			return {
+				status: "fail",
+				message: "npm 2FA grant needed — see printed authUrl",
+				packages: results
+			};
+		}
+		const entry = parsed;
+		if (entry.file === input.newFile) {
+			print(`  already on ${input.newFile}, skipping`);
+			results.push({
+				name,
+				status: "skipped"
+			});
+			continue;
+		}
+		if (entry.id) {
+			print(`  revoking existing trust (file=${entry.file ?? "?"}, id=${entry.id})`);
+			const revoke = await exec(npm, [
+				...npmArgs,
+				"trust",
+				"revoke",
+				name,
+				"--id",
+				entry.id,
+				"-y"
+			], { cwd });
+			if (revoke.exitCode !== 0 && isEotp(parseJson(revoke.stdout))) {
+				const authUrl = parseJson(revoke.stdout).error?.authUrl ?? "";
+				print(`  needs fresh 2FA — open and approve: ${authUrl}`);
+				results.push({
+					name,
+					status: "needs-auth",
+					message: authUrl
+				});
+				return {
+					status: "fail",
+					message: "npm 2FA grant needed — see printed authUrl",
+					packages: results
+				};
+			}
+		} else print("  no existing trust config found");
+		print(`  creating trust: ${input.newFile}`);
+		const create = await exec(npm, [
+			...npmArgs,
+			"trust",
+			"github",
+			name,
+			"--repo",
+			repo,
+			"--file",
+			input.newFile,
+			"--allow-publish",
+			"--allow-stage-publish",
+			"-y"
+		], { cwd });
+		if (create.exitCode === 0) {
+			print("  ✓ ok");
+			results.push({
+				name,
+				status: "ok"
+			});
+		} else {
+			const createParsed = parseJson(create.stdout);
+			if (isEotp(createParsed)) {
+				const authUrl = createParsed.error?.authUrl ?? "";
+				print(`  needs fresh 2FA — open and approve: ${authUrl}`);
+				results.push({
+					name,
+					status: "needs-auth",
+					message: authUrl
+				});
+				return {
+					status: "fail",
+					message: "npm 2FA grant needed — see printed authUrl",
+					packages: results
+				};
+			}
+			const message = create.stderr.trim() || create.stdout.trim() || `exit ${create.exitCode}`;
+			print(`  ✗ FAILED: ${message}`);
+			results.push({
+				name,
+				status: "fail",
+				message
+			});
+		}
 	}
-	print("    ✓ publish complete");
+	const failed = results.filter((r) => r.status === "fail");
 	logger.info({
-		tag,
-		status: "ok",
-		packages: entries.length
-	}, "publish: done");
+		ok: results.filter((r) => r.status === "ok").length,
+		failed: failed.length
+	}, "sync-trust: done");
 	return {
-		status: "ok",
-		packageNames
+		status: failed.length > 0 ? "fail" : "ok",
+		...failed.length > 0 ? { message: `${failed.length} package(s) failed` } : {},
+		packages: results
 	};
 }
-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] : [];
-}
-/**
-* Monorepo (`packages/` and/or `plugins/` present): every workspace under
-* either. Single package (neither dir present): the root `package.json`.
-* Callers keep the public ones.
-*/
-function discoverManifests(cwd) {
-	if (!hasPackagesDir(cwd) && !hasPluginsDir(cwd)) {
-		const manifest = readPackageJsonSync(cwd);
-		return manifest ? [{
-			manifest,
-			dir: "."
-		}] : [];
-	}
-	return listWorkspacePackagesSync(cwd).map(({ manifest, relativeDir }) => ({
-		manifest,
-		dir: `./${relativeDir}`
-	}));
-}
-/**
-* Every public package (`!private && name`) with its version and a
-* `pnpm --filter`-ready path — {@link runSteadyPublish}'s `skipAlreadyPublished`
-* mode needs both to check `npm view <pkg>@<version>` and publish one
-* workspace at a time.
-*/
-function discoverPublicPackageEntries(cwd) {
-	return discoverManifests(cwd).flatMap(({ manifest, dir }) => !manifest.private && manifest.name && manifest.version ? [{
-		name: manifest.name,
-		version: manifest.version,
-		dir
-	}] : []);
-}
-/** The names of {@link discoverPublicPackageEntries}' packages, without requiring a version. */
-function discoverPublicPackages(cwd) {
-	return discoverManifests(cwd).flatMap(({ manifest }) => !manifest.private && manifest.name ? [manifest.name] : []);
-}
-async function resolveRepoName(cwd, exec) {
-	return (await readGitRemote(cwd, { exec: async (args, options) => {
-		const result = await exec("git", args, options);
-		if (result.exitCode !== 0) throw new Error(`git ${args.join(" ")} exited ${result.exitCode}`);
-		return result.stdout;
-	} }))?.repo ?? "unknown";
-}
-function printNextSteps(print, env, packageNames, repoName) {
-	print("");
-	print("  → next: configure Trusted Publisher for each package on npm:");
-	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
-	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: delivery.publish.yml`);
-	if (env.get("NPM_TOKEN")) {
-		print("");
-		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
-		print("    https://www.npmjs.com/settings/~/tokens");
-	}
-}
-const defaultExec$1 = async (cmd, args, opts) => {
-	const result = spawnSync(cmd, args, {
-		cwd: opts.cwd,
-		encoding: "utf8",
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		]
-	});
-	return {
-		exitCode: result.status ?? -1,
-		stdout: result.stdout ?? "",
-		stderr: result.stderr ?? ""
-	};
-};
-/**
-* Fully interactive — `npm login --auth-type=web` prints a URL and waits for
-* the browser flow to complete; the operator needs to see that live, so all
-* three stdio streams are inherited (unlike `defaultExec`, which pipes
-* stdout/stderr for capture).
-*/
-const defaultLogin = async (cwd) => {
-	return { exitCode: spawnSync("npm", ["login", "--auth-type=web"], {
-		cwd,
-		stdio: "inherit"
-	}).status ?? -1 };
-};
 //#endregion
-//#region src/commands/secret-set.ts
+//#region src/commands/secret-set/secret-set.ts
 /**
 * `holocron secrets set` — one-shot single-secret push.
 *
@@ -4250,7 +4668,7 @@ function describeScope(scope) {
 	return `scope=organization:${scope.name}`;
 }
 //#endregion
-//#region src/commands/secrets-sync.ts
+//#region src/commands/secrets-sync/secrets-sync.ts
 /**
 * `holocron secrets sync` — vault → destinations.
 *
@@ -4415,7 +4833,7 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
-//#region src/commands/setup/derived-properties.ts
+//#region src/commands/setup/derived-properties/derived-properties.ts
 /**
 * Repo archetype, in priority order:
 * 1. `*-template` repo name → `template` (independent of package shape).
@@ -4609,221 +5027,9 @@ const STALE_LABELS = [
 	"released on @alpha"
 ];
 //#endregion
-//#region src/templates/config.yml
-var config_default = "# Configuration for sentiment-bot - https://github.com/behaviorbot/sentiment-bot\n\n# *Required* toxicity threshold between 0 and .99 with the higher numbers being the most toxic\n# Anything higher than this threshold will be marked as toxic and commented on\nsentimentBotToxicityThreshold: .7\n\n# *Required* Comment to reply with\nsentimentBotReplyComment: >\n  Please be sure to review the [Code of Conduct](https://docs.theholocron.dev/reference/code-of-conduct/) and be respectful of other users.\n";
-//#endregion
-//#region src/utils/create-header.ts
-function createHeader(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") {
-			if (format === "cjs") return [
-				`/* ${doNotEdit}`,
-				` * Source:  theholocron/holocron · ${source}`,
-				` * Tool:    ${tool}`,
-				` * Changes: edit source in theholocron/holocron`,
-				` */`,
-				``
-			].join("\n");
-			const yamlLines = [
-				`# ${doNotEdit}`,
-				`# Source:  theholocron/holocron · ${source}`,
-				`# Tool:    ${tool}`,
-				`# Changes: edit source in theholocron/holocron`,
-				``
-			].join("\n");
-			if (format === "shebang") return `#!/bin/sh\n\n${yamlLines}`;
-			return yamlLines;
-		},
-		scaffoldHeader() {
-			return [
-				`# Scaffolded by holocron repo setup — edit this file freely.`,
-				`# Source:  theholocron/holocron · ${source}`,
-				``
-			].join("\n");
-		}
-	};
-}
-//#endregion
-//#region src/templates/configs/alexjs/alexignore
-var alexignore_default = ".github/*\nCHANGELOG.md\nLICENSE\n";
-//#endregion
-//#region src/templates/configs/alexjs/alexrc.json
-var alexrc_default = { allow: [
-	"dead",
-	"execute",
-	"execution",
-	"executes",
-	"failure",
-	"failures",
-	"hook",
-	"hooks",
-	"husky",
-	"period"
-] };
-//#endregion
-//#region src/templates/configs/alexjs/create-config.ts
-const { workflowHeader: workflowHeader$9 } = createHeader({ source: "packages/cli/src/templates/configs/alexjs/create-config.ts" });
-function createRcConfig() {
-	return stringifyJson(alexrc_default);
-}
-function createIgnoreConfig$1() {
-	return `${workflowHeader$9()}${alexignore_default}`;
-}
-//#endregion
-//#region src/templates/configs/commit-msg/commit-msg
-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" });
-/**
-* `.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
-const { workflowHeader: workflowHeader$7 } = createHeader({ source: "packages/cli/src/templates/configs/devmoji/create-config.ts" });
-function createConfig$6() {
-	return [
-		workflowHeader$7("cjs"),
-		`/* eslint-disable */`,
-		`const { defineConfig } = require("@theholocron/devmoji-config");`,
-		`module.exports = defineConfig();`,
-		``
-	].join("\n");
-}
-//#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\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" });
-function createConfig$5() {
-	return `${workflowHeader$6()}${editorconfig_default}`;
-}
-//#endregion
-//#region src/templates/configs/editorconfig-checker/editorconfig-checker.json
-var editorconfig_checker_default = {
-	Verbose: false,
-	Format: "",
-	Debug: false,
-	IgnoreDefaults: false,
-	SpacesAfterTabs: false,
-	NoColor: false,
-	Exclude: [
-		"(^|.+/)LICENSE$",
-		"^public/.*",
-		"\\.md$",
-		"\\.mdx$"
-	],
-	AllowedContentTypes: [],
-	PassedFiles: [],
-	Disable: {
-		"EndOfLine": false,
-		"Indentation": false,
-		"InsertFinalNewline": false,
-		"TrimTrailingWhitespace": false,
-		"IndentSize": false,
-		"MaxLineLength": false
-	}
-};
-//#endregion
-//#region src/templates/configs/editorconfig-checker/create-config.ts
-/**
-* The generated `.editorconfig-checker.json`.
-*
-* Deliberately carries no `"Version"` key: editorconfig-checker treats it as a
-* hard gate and exits non-zero the moment the running binary's version differs
-* — which it does the instant a contributor's local install (Homebrew tracks
-* latest) drifts from the version super-linter bundles in CI, breaking
-* `holocron run lint` / the pre-push hook for everyone (#618). The config
-* options here (`Exclude`, `Disable`) are stable across releases, so pinning
-* buys nothing.
-*/
-function createConfig$4() {
-	return stringifyJson(editorconfig_checker_default);
-}
-//#endregion
-//#region src/templates/configs/pre-commit/pre-commit
-var pre_commit_default = "# Run GitLeaks against staged changes only — a full `gitleaks git` history\n# scan re-flags every pre-existing (already-merged) finding on every commit,\n# permanently blocking the repo once any false positive lands in history.\n# CI's super-linter GITLEAKS validator is likewise scoped to changed files.\ngitleaks protect --staged --no-banner\n\n# Exit with non-zero if secrets are detected by GitLeaks\nif [ $? -ne 0 ]; then\n	echo \"Secrets detected by GitLeaks, aborting commit!\"\n	exit 1\nfi\n\n# Run lint-staged with a custom config\nnpx lint-staged --config @theholocron/lint-staged-config\n";
-//#endregion
-//#region src/templates/configs/pre-commit/create-config.ts
-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 repo setup` when hooks
-* are enabled (default for `protection: "strict"`). `git commit --no-verify`
-* bypasses it.
-*
-* `gitleaks protect --staged` (not `gitleaks git`) is deliberate: the latter
-* scans the entire commit history on every invocation, so once any false
-* positive lands in a past commit — a fake test token, an example key in a
-* doc — every future commit is permanently blocked, regardless of what's
-* actually staged.
-*/
-function createConfig$3() {
-	return `${workflowHeader$5("shebang")}${pre_commit_default}`;
-}
-//#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__ 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 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
-*   `pnpm exec holocron`; the source repo passes `node packages/cli/dist/cli.mjs`.
-*/
-function createConfig$2(holocronScript = "pnpm exec holocron") {
-	return `${workflowHeader$4("shebang")}${pre_push_default.replace("__HOLOCRON_SCRIPT__", holocronScript)}`;
-}
-//#endregion
-//#region src/templates/configs/prepare-commit-msg/prepare-commit-msg
-var prepare_commit_msg_default = "NAME=$(git config user.name)\nEMAIL=$(git config user.email)\n\nif [ -z \"$NAME\" ]; then\n	echo \"empty git config user.name\"\n	exit 1\nfi\n\nif [ -z \"$EMAIL\" ]; then\n	echo \"empty git config user.email\"\n	exit 1\nfi\n\ngit interpret-trailers --if-exists doNothing --trailer \\\n	\"Signed-off-by: $NAME <$EMAIL>\" \\\n	--in-place \"$1\"\n\n# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to devmoji's own auto-discovery of a local devmoji.config.cjs when the\n# shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nDEVMOJI_CONFIG=\"node_modules/@theholocron/devmoji-config/dist/index.cjs\"\nif [ -f \"$DEVMOJI_CONFIG\" ]; then\n	npx devmoji --config \"$DEVMOJI_CONFIG\" -e\nelse\n	npx devmoji -e\nfi\n";
-//#endregion
-//#region src/templates/configs/prepare-commit-msg/create-config.ts
-const { workflowHeader: workflowHeader$3 } = createHeader({ source: "packages/cli/src/templates/configs/prepare-commit-msg/create-config.ts" });
-function createConfig$1() {
-	return `${workflowHeader$3("shebang")}${prepare_commit_msg_default}`;
-}
-//#endregion
-//#region src/templates/configs/yamllint/.yamlignore
-var _yamlignore_default = "pnpm-lock.yaml\n";
-//#endregion
-//#region src/templates/configs/yamllint/.yamllint.yml
-var _yamllint_default = "---\nextends: default\n\nignore-from-file:\n  - .gitignore\n  - .yamlignore\n\nrules:\n  comments:\n    min-spaces-from-content: 1\n    require-starting-space: true\n\n  comments-indentation: {}\n\n  document-start:\n    ignore: |\n      .github/*.yml\n\n  indentation:\n    spaces: consistent\n    indent-sequences: consistent\n\n  line-length: disable\n";
-//#endregion
-//#region src/templates/configs/yamllint/create-config.ts
-const { workflowHeader: workflowHeader$2 } = createHeader({ source: "packages/cli/src/templates/configs/yamllint/create-config.ts" });
-function createConfig() {
-	return `${workflowHeader$2()}${_yamllint_default}`;
-}
-function createIgnoreConfig() {
-	return `${workflowHeader$2()}${_yamlignore_default}`;
-}
-//#endregion
 //#region src/templates/dco.yml
 var dco_default = "allowRemediationCommits:\n  individual: true\n";
 //#endregion
-//#region src/templates/dependabot.yml
-var dependabot_default = "version: 2\nupdates:\n  - package-ecosystem: npm\n    directory: /\n    schedule:\n      interval: weekly\n    commit-message:\n      prefix: \"chore(deps)\"\n      prefix-development: \"chore(deps-dev)\"\n    groups:\n      security-patches:\n        applies-to: security-updates\n        patterns:\n          - \"*\"\n      all-dependencies:\n        update-types:\n          - minor\n          - patch\n\n  - package-ecosystem: github-actions\n    directory: /\n    schedule:\n      interval: weekly\n    commit-message:\n      prefix: \"chore(deps)\"\n    groups:\n      all-actions:\n        patterns:\n          - \"*\"\n";
-//#endregion
-//#region src/templates/labeler.yml
-var labeler_default = "bug:\n  - \"^fix\"\n\nchore:\n  - '^chore(?!\\(deps)'\n\nci:\n  - \"^ci\"\n\ndependencies:\n  - '^chore\\(deps'\n\ndocumentation:\n  - \"^docs\"\n\nenhancement:\n  - \"^feat\"\n\nperformance:\n  - \"^perf\"\n\nrefactor:\n  - \"^refactor\"\n\ntest:\n  - \"^test\"\n";
-//#endregion
 //#region src/commands/setup/agent-prompts-data.ts
 /**
 * Canonical AI engineering workflow role prompts.
@@ -4834,7 +5040,6 @@ var labeler_default = "bug:\n  - \"^fix\"\n\nchore:\n  - '^chore(?!\\(deps)'\n\n
 *
 * Source: docs/wiki/specifications/ai-engineering-workflow.spec.md
 */
-const DECISIONS_TEMPLATE = "---\nid: ADR-XXXX\ntitle: \"\"\nstatus: proposed\ndate: YYYY-MM-DD\nowners: []\nspecs: []\ndiscussion:\n  github:\nsupersedes: []\nsuperseded-by: []\ntags: []\n---\n\n# [Short title of the decision]\n\n- Status: [proposed | accepted | rejected | deprecated | superseded by ADR-XXXX]\n- Date: YYYY-MM-DD\n\n## Context and Problem Statement\n\n2–3 sentences describing the situation that forced this decision.\n\n## Decision Drivers\n\n- [driver 1 — a constraint, goal, or value]\n- [driver 2]\n\n## Considered Options\n\n- [Option A]\n- [Option B]\n- [Option C — do nothing]\n\n## Decision Outcome\n\nChosen option: **[Option A]**, because [one-sentence justification].\n\n### Positive Consequences\n\n- …\n\n### Negative Consequences\n\n- …\n\n## Pros and Cons of the Options\n\n### [Option A]\n\n- Good, because [argument]\n- Bad, because [argument]\n\n### [Option B]\n\n- Good, because [argument]\n- Bad, because [argument]\n";
 const AGENT_PROMPTS = {
 	"discovery.md": `# Discovery Agent
 
@@ -4963,10 +5168,14 @@ confidently, identify the missing information instead of inventing it.
 
 ## Format
 
-Use MADR format. Copy the template and number sequentially:
+Use MADR format. Start from the \`adr\` skill's template,
+\`.agents/skills/adr/assets/template.md\`, and number the record sequentially.
+\`holocron repo setup\` installs that skill when \`adr\` is listed under
+\`skills\` in \`holocron.config\` — if the file is missing, add it there and
+re-run setup.
 
 \`\`\`sh
-cp docs/wiki/decisions/template.md docs/wiki/decisions/000N-short-title.md
+cp .agents/skills/adr/assets/template.md docs/wiki/decisions/000N-short-title.md
 \`\`\`
 
 Save to \`docs/wiki/decisions/NNNN-<slug>.md\`.
@@ -5173,10 +5382,13 @@ decision, the options that were considered, and the rationale for the choice mad
 
 ## Creating a new decision
 
-Copy the template and number it sequentially:
+Start from the template that ships with the \`adr\` skill,
+\`.agents/skills/adr/assets/template.md\` (installed by \`holocron repo setup\`
+when \`adr\` is listed under \`skills\` in \`holocron.config\`), and number the
+record sequentially:
 
 \`\`\`sh
-cp docs/wiki/decisions/template.md docs/wiki/decisions/000N-short-title.md
+cp .agents/skills/adr/assets/template.md docs/wiki/decisions/000N-short-title.md
 \`\`\`
 
 \`madr\` has no CLI — creation is manual. Frontmatter is validated in CI
@@ -5358,7 +5570,6 @@ async function writeIfAbsent(filePath, content) {
 async function installEngineeringStructure({ repoRoot }) {
 	const results = [];
 	const writes = [
-		[join(repoRoot, "docs/wiki/decisions/template.md"), DECISIONS_TEMPLATE],
 		[join(repoRoot, "docs/wiki/decisions/README.md"), DECISIONS_README],
 		[join(repoRoot, "docs/wiki/standards/README.md"), STANDARDS_README],
 		[join(repoRoot, "docs/wiki/specifications/README.md"), SPECIFICATIONS_README]
@@ -5381,7 +5592,7 @@ const BALANCED_REPO_SETTINGS = {
 	has_wiki: false
 };
 //#endregion
-//#region src/commands/setup/run-step.ts
+//#region src/commands/setup/run-step/run-step.ts
 async function runStep(capability, step, dryRun, body, opts = {}) {
 	const result = await execStep(capability, step, dryRun, body, opts);
 	const { status, message, reason } = result;
@@ -5452,7 +5663,7 @@ function formatStep(step) {
 	return `    ${style.dim(`· ${label}`)}`;
 }
 //#endregion
-//#region src/commands/setup/skills.ts
+//#region src/commands/setup/skills/skills.ts
 async function fetchExternalSkill(entry) {
 	if (entry.sourceType !== "github")
  /* c8 ignore next */
@@ -5729,14 +5940,14 @@ async function runSetup(input) {
 	if (loader.has("source") && (config.tasks ?? []).map((e) => typeof e === "string" ? e : e.name).includes("bookkeeping")) {
 		const source = loader.get("source");
 		steps.push(await runStep("source", "write .github/labeler.yml", dryRun, async () => {
-			await source.writeRepoFile(".github/labeler.yml", `${workflowHeader$1()}${labeler_default}`);
+			await source.writeRepoFile(".github/labeler.yml", createLabeler());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 	}
 	if (loader.has("source") && effectivePreset !== "none") {
 		const source = loader.get("source");
 		steps.push(await runStep("source", "write .github/dependabot.yml", dryRun, async () => {
-			await source.writeRepoFile(".github/dependabot.yml", `${workflowHeader$1()}${dependabot_default}`);
+			await source.writeRepoFile(".github/dependabot.yml", createDependabot());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .github/dco.yml", dryRun, async () => {
@@ -5746,54 +5957,50 @@ async function runSetup(input) {
 	}
 	if (loader.has("source")) {
 		const source = loader.get("source");
-		steps.push(await runStep("source", "write .github/config.yml", dryRun, async () => {
-			await source.writeRepoFile(".github/config.yml", `${workflowHeader$1()}${config_default}`);
-		}));
-		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .alexrc.json", dryRun, async () => {
-			await source.writeRepoFile(".alexrc.json", createRcConfig());
+			await source.writeRepoFile(".alexrc.json", createAlexrc());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .alexignore", dryRun, async () => {
-			await source.writeRepoFile(".alexignore", createIgnoreConfig$1());
+			await source.writeRepoFile(".alexignore", createAlexignore());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .yamllint.yml", dryRun, async () => {
-			await source.writeRepoFile(".yamllint.yml", createConfig());
+			await source.writeRepoFile(".yamllint.yml", createYamllint());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .yamlignore", dryRun, async () => {
-			await source.writeRepoFile(".yamlignore", createIgnoreConfig());
+			await source.writeRepoFile(".yamlignore", createYamlignore());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .editorconfig", dryRun, async () => {
-			await source.writeRepoFile(".editorconfig", createConfig$5());
+			await source.writeRepoFile(".editorconfig", createEditorconfig());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .editorconfig-checker.json", dryRun, async () => {
-			await source.writeRepoFile(".editorconfig-checker.json", createConfig$4());
+			await source.writeRepoFile(".editorconfig-checker.json", createEditorconfigChecker());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write devmoji.config.cjs", dryRun, async () => {
-			await source.writeRepoFile("devmoji.config.cjs", createConfig$6());
+			await source.writeRepoFile("devmoji.config.cjs", createDevmoji());
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .husky/prepare-commit-msg", dryRun, async () => {
-			await source.writeRepoFile(".husky/prepare-commit-msg", createConfig$1());
+			await source.writeRepoFile(".husky/prepare-commit-msg", createPrepareCommitMsg());
 		}));
 		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(config.holocronScript));
+			await source.writeRepoFile(".husky/commit-msg", createCommitMsg(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));
+				await source.writeRepoFile(".husky/pre-push", createPrePush(config.holocronScript));
 				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 () => {
-				await source.writeRepoFile(".husky/pre-commit", createConfig$3());
+				await source.writeRepoFile(".husky/pre-commit", createPreCommit());
 				return "runs GitLeaks (staged-only) + lint-staged before commit";
 			}));
 			print(formatStep(steps[steps.length - 1]));
@@ -6309,7 +6516,7 @@ async function ensurePrepareScript(repoRoot) {
 	return true;
 }
 //#endregion
-//#region src/commands/skills.ts
+//#region src/commands/skills/skills.ts
 /**
 * `holocron skills` — install, remove, and update agent skills from @theholocron/skills.
 *
@@ -6408,7 +6615,7 @@ function runSkillsUpdate(input) {
 	return { status: exitCode === 0 ? "ok" : "fail" };
 }
 //#endregion
-//#region src/commands/sync-readme.ts
+//#region src/commands/sync-readme/sync-readme.ts
 const MARKER_INSTALL_START = "<!-- holocron:installation -->";
 const MARKER_INSTALL_END = "<!-- /holocron:installation -->";
 const REGISTRY_MAP = {
@@ -6564,7 +6771,7 @@ async function runSyncReadme(input) {
 	};
 }
 //#endregion
-//#region src/commands/sync-wiki.ts
+//#region src/commands/sync-wiki/sync-wiki.ts
 function resolveToken(input) {
 	return input.token ?? input.context.cliToken ?? firstEnv(env, [
 		"HOLOCRON_READ_TOKEN",
@@ -6781,7 +6988,7 @@ async function runSyncWiki(input) {
 	}
 }
 //#endregion
-//#region src/commands/sync.ts
+//#region src/commands/sync/sync.ts
 const { workflowHeader } = createHeader({
 	source: "packages/astromech/src/thin-callers.ts",
 	tool: "holocron repo sync"
@@ -7369,7 +7576,7 @@ async function writeWorkflowFile(repoRoot, filename, content) {
 	await rename(tmpPath, join(dir, filename));
 }
 //#endregion
-//#region src/telemetry/resolve.ts
+//#region src/observability/resolve-telemetry/resolve-telemetry.ts
 /**
 * Holocron-specific credential resolution for the telemetry sinks — the env
 * chain plus Holocron's own shipped fallbacks. This is **CLI policy**, not part
@@ -7404,7 +7611,7 @@ function resolvePostHogHost() {
 	return holocronEnv.get("POSTHOG_HOST") ?? DEFAULT_POSTHOG_HOST;
 }
 //#endregion
-//#region src/telemetry.ts
+//#region src/observability/telemetry/telemetry.ts
 /**
 * CLI self-telemetry orchestration — errors (Sentry), usage analytics (PostHog).
 *
@@ -7415,7 +7622,7 @@ function resolvePostHogHost() {
 * installed when telemetry is off. Same seam the package's `Logger` uses for
 * Pino.
 *
-* Activation is env-var + shipped-fallback, resolved here (`telemetry/resolve.ts`)
+* Activation is env-var + shipped-fallback, resolved here (`resolve-telemetry.ts`)
 * and passed to the sink — the adapters read no environment. The single kill
 * switch is `HOLOCRON_TELEMETRY=false` (legacy alias `NO_HOLOCRON_TELEMETRY`);
 * see ADR-0007 / ADR-0008.
@@ -7548,7 +7755,7 @@ async function flush() {
 	analytics = new NoopAnalyticsSink();
 }
 //#endregion
-//#region src/commands/sync-github.ts
+//#region src/commands/sync-github/sync-github.ts
 const DEFAULT_REPO = "theholocron/.github";
 /**
 * The file set `sync-github` pushes to `theholocron/.github` — the reusable
@@ -7788,7 +7995,7 @@ async function runSyncGithub(input) {
 	});
 }
 //#endregion
-//#region src/commands/upgrade-deps.ts
+//#region src/commands/upgrade-deps/upgrade-deps.ts
 /**
 * `holocron repo upgrade deps` — bring a repo's `@theholocron/*` dependency pins and
 * its `holocron.config.ts` up to the current major.
@@ -8016,7 +8223,7 @@ async function runUpgradeDeps(input = {}) {
 	};
 }
 //#endregion
-//#region src/commands/upgrade-node.ts
+//#region src/commands/upgrade-node/upgrade-node.ts
 const SKIP_DIRS = [
 	"node_modules",
 	".git",
@@ -8194,268 +8401,45 @@ async function runUpgradeNode(input) {
 		to,
 		updated: updated.length,
 		status
-	}, "upgrade node: done");
-	return {
-		status,
-		updated
-	};
-}
-//#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.
-*
-* File discovery + module loading (typed configs via `tsx`, no build
-* step) is delegated to `@theholocron/datapad`. This module keeps the
-* holocron-specific parts: filling `name` / `repo.name` defaults and
-* running the config through `resolveConfig`.
-*
-* Probe order is TS-first (`.ts` → `.js` → `.mjs` → `.cjs` → `.json`) —
-* see ADR-0010 / issue #75 / #81.
-*/
-/**
-* 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 fails schema checks.
-*/
-async function loadConfig(cwd) {
-	const found = await loadConfigFile({
-		cwd,
-		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.`);
+	}, "upgrade node: done");
 	return {
-		resolved: resolveConfig(await deriveDefaults(found)),
-		filepath: found.filepath
+		status,
+		updated
 	};
 }
-async function deriveDefaults(found) {
-	const configDir = dirname(found.filepath);
-	const result = { ...found.config };
-	if (!result.name) result.name = await readPackageJsonName(configDir) ?? basename(configDir);
-	if (result.repo && !result.repo.name) {
-		const remote = await readGitRemote(configDir);
-		if (remote?.host === "github.com") result.repo = {
-			...result.repo,
-			name: remote.slug
-		};
-	}
-	const manifest = await loadTasksConfig(configDir, { holocron: found });
-	if (manifest.tasks) result.tasks = manifest.tasks;
-	if (manifest.syncScripts !== void 0) result.syncScripts = manifest.syncScripts;
-	if (manifest.holocronScript !== void 0) result.holocronScript = manifest.holocronScript;
-	if (manifest.hooks !== void 0) result.hooks = manifest.hooks;
-	if (manifest.extraRequiredChecks) result.extraRequiredChecks = [...result.extraRequiredChecks ?? [], ...manifest.extraRequiredChecks];
-	return result;
-}
-async function readPackageJsonName(dir) {
-	const name = (await readPackageJson(dir))?.name;
-	return name === void 0 ? void 0 : name.replace(/^@[^/]+\//, "");
-}
 //#endregion
-//#region src/interactive-menu.ts
+//#region src/interactive-menu/child-argv/child-argv.ts
 /**
-* The interactive fallback — replaces every "run --help to see commands"
-* dead end with a prompt. Three layers, all driven by {@link COMMAND_REGISTRY}:
-*
-*   1. `holocron` with no command      → searchable picker over every command
-*   2. a parent command with no sub    → `select()` over that group's commands
-*   3. a leaf command missing a        → `input()` / `select()` per positional
-*      required positional
-*
-* Layers 1–2 are driven from `cli.ts`'s `$0` handlers via {@link launchMenu}:
-* pick a command, prompt for its required positionals, then **spawn a fresh
-* `holocron <command> …` child process** (`stdio: "inherit"`) rather than
-* re-entering yargs' own parse pipeline — see the spec's "spawn vs re-parse"
-* section (theholocron/holocron#438) for why. Layer 3 is driven directly from
-* each leaf command's own handler in `cli.ts`, calling
-* {@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.
+* `--token` (repeatable), `--org`, `--cwd`, `--dry-run` — the global flags a
+* 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.
 *
-* 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
-* `ExitPromptError` the moment stdin closes) — `cli.ts`'s `USER_FACING_ERRORS`
-* catch prints its message cleanly, restoring the old demandCommand-style
-* hard failure for non-interactive callers.
-*/
-/** Raised when a prompt is needed but stdin isn't a TTY — see the module doc. */
-var NonInteractiveError = class extends Error {
-	name = "NonInteractiveError";
-};
-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.
+* `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 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;
+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 (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
+	return out;
 }
-/**
-* 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;
+/** `entry.spawnArgs` if set, else `entry.name` split into tokens — resolved positionals appended, then forwarded flags. */
+function buildChildArgv(entry, positionals, parentArgv, dryRunOverride) {
+	return [
+		...entry.spawnArgs ?? entry.name.split(" "),
+		...positionals,
+		...forwardedFlags(parentArgv, dryRunOverride)
+	];
 }
+//#endregion
+//#region src/interactive-menu/command-registry/command-registry.ts
+const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
 /**
 * The full command surface, hand-maintained in parallel with `cli.ts`'s
 * yargs registrations (this module does not introspect yargs at runtime).
@@ -8693,6 +8677,9 @@ function getEntry(name) {
 	if (!entry) throw new Error(`interactive-menu: no COMMAND_REGISTRY entry named "${name}"`);
 	return entry;
 }
+//#endregion
+//#region src/interactive-menu/menu-items/menu-items.ts
+/** Prefix of a menu item's `value` that opens a submenu rather than running a command. */
 const GROUP = "group:";
 /** The "← back" item's value; only offered below the first level. */
 const BACK = "back";
@@ -8738,105 +8725,16 @@ function menuItems(entries, path = []) {
 			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 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 pickMenuItem(items, message = "What would you like to do?") {
-	return search({
-		message,
-		source: (term) => searchChoices(items, term)
-	});
-}
-/**
-* `@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 item.
-*/
-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
-	}));
-}
-/**
-* For each of `entry.positionals` not already present in `argv`, prompts for
-* it (`input()` or `select()`, per the positional's `type`) and returns the
-* resolved values in positional order — ready to append to a spawned child's
-* argv, or to use directly in the current handler (Layer 3).
-*
-* Throws {@link NonInteractiveError} the first time it would need to prompt
-* on a non-TTY stdin, and again if a `select` positional's choices resolve
-* empty (nothing to pick from — e.g. `auth unset` with no stored tokens).
-*/
-async function promptForPositionals(entry, argv) {
-	const out = [];
-	for (const positional of entry.positionals) {
-		const existing = argv[positional.key];
-		if (existing !== void 0 && existing !== "") {
-			out.push(String(existing));
-			continue;
-		}
-		if (!process.stdin.isTTY) throw new NonInteractiveError(`\`${entry.name}\` needs "${positional.key}" — pass it directly: holocron ${entry.name} <${positional.cliArg ?? positional.key}>`);
-		if (positional.type === "select") {
-			const choices = typeof positional.choices === "function" ? positional.choices() : positional.choices ?? [];
-			if (choices.length === 0) throw new NonInteractiveError(`\`${entry.name}\`: no ${positional.key} to choose from — nothing stored yet`);
-			out.push(await select({
-				message: positional.message,
-				choices: choices.map((c) => ({ value: c }))
-			}));
-		} else out.push(await input({
-			message: positional.message,
-			...positional.validate ? { validate: positional.validate } : {}
-		}));
-	}
-	return out;
-}
-/**
-* `--token` (repeatable), `--org`, `--cwd`, `--dry-run` — the global flags a
-* 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, 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 (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
-	return out;
-}
-/** `entry.spawnArgs` if set, else `entry.name` split into tokens — resolved positionals appended, then forwarded flags. */
-function buildChildArgv(entry, positionals, parentArgv, dryRunOverride) {
-	return [
-		...entry.spawnArgs ?? entry.name.split(" "),
-		...positionals,
-		...forwardedFlags(parentArgv, dryRunOverride)
-	];
+				value: `${GROUP}${full}`,
+				description: children.join(", "),
+				haystack: haystackOf(family)
+			});
+		}
+	}
+	return items;
 }
+//#endregion
+//#region src/interactive-menu/launch-menu/launch-menu.ts
 /**
 * 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
@@ -8859,353 +8757,200 @@ const DRY_RUN_PREVIEW_ENV_VAR = "HOLOCRON_DRY_RUN_PREVIEW";
 * 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",
-			env: {
-				...process.env,
-				NO_UPDATE_NOTIFIER: "1",
-				...extraEnv
-			}
-		});
-		child.on("exit", (code) => resolve(code ?? 0));
-		child.on("error", () => resolve(1));
-	});
-}
-/**
-* 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.", startPath = []) {
-	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
-	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/ui/json-view.ts
-function isContainer(value) {
-	return typeof value === "object" && value !== null;
-}
-function childrenOf(value) {
-	return Array.isArray(value) ? value.map((v, i) => [String(i), v]) : Object.entries(value);
-}
-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 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}}`);
-}
-/**
-* 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;
+function spawnChild(args, extraEnv) {
+	return new Promise((resolve) => {
+		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));
 	});
-	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();
-	}
+/**
+* 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;
 }
 /**
-* 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).
+* 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 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));
+async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessage = "Run `holocron --help` to see available commands.", startPath = []) {
+	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
+	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;
 	}
-	const lines = renderTree(value, { expanded: expandToDepth(value, depth) });
-	console.log(lines.map((l) => l.text).join("\n"));
+	process.exitCode = await spawnChild(buildChildArgv(picked, positionals, parentArgv));
 }
 //#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]
+//#region src/interactive-menu/run-menu-entries/run-menu-entries.ts
+/**
+* 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;
 }
 /**
-* 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).
+* 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 openPath(path) {
-	const { cmd, args } = openCommand(path);
-	const child = spawn(cmd, args, {
-		stdio: "ignore",
-		detached: true
-	});
-	child.on("error", () => {});
-	child.unref();
+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;
 }
 //#endregion
-//#region src/update-notifier.ts
+//#region src/update-notifier/update-notifier.ts
 const PACKAGE_NAME = "@theholocron/cli";
 const CACHE_TTL_MS = 864e5;
 const FETCH_TIMEOUT_MS = 3e3;