holycodex 0.13.4 → 0.13.5

package/README.md

@@ -1,18 +1,22 @@
 # holycodex
 
-HolyCodex installer and doctor CLI. Plugin prompts, skills, agents, hooks, and runtime assets ship through the exact-version `@holycodex/plugin` dependency.
+`holycodex` is the public installer, doctor, and cleanup CLI for HolyCodex. It installs the exact matching `@holycodex/plugin` payload and makes durable Codex workflows, retained Luna specialists, plan-aware routing, Context7, LSP, and native-Windows Git Bash available to Codex. Product and ownership details live in the repository [README](../../README.md) and [architecture](../../docs/ARCHITECTURE.md).
+
+Stable installation:
 
 ```sh
-bunx holycodex@dev install
-bunx holycodex@dev doctor
+bunx holycodex install
+bunx holycodex doctor
 ```
 
-Use `holycodex --help` for commands, autonomy options, routing plans, and service tiers. `--fast` selects Fast for generated agents, `--fast-all` selects Fast for Root and generated agents, and `--no-fast` or omitting Fast flags selects Standard. Fast uses `2×` API-equivalent usage and changes only the serving tier, not model quality or routing. See the repository's [routing policy](../../docs/ROUTING.md). Stable releases use `bunx holycodex`; development releases use npm's `dev` dist-tag.
+Development installation uses the development dist-tag:
 
-On a fresh installation, omitting autonomy flags seeds Codex Approve for me semantics: `approval_policy = "on-request"`, `approvals_reviewer = "auto_review"`, and `sandbox_mode = "workspace-write"`. On an existing installation, omitting autonomy flags preserves the complete current permission selection. `--no-codex-autonomous`, `--codex-autonomous`, and `--dangerous-codex-autonomous` explicitly replace that selection with their documented modes. HolyCodex never generates `default_permissions` or selects a named permission profile.
+```sh
+bunx holycodex@dev install
+```
 
-Install keeps an explicit managed Computer Use choice across upgrades. Use `--computer-use` to install and verify the official `computer-use@openai-bundled` plugin and enable Root-only guidance, or `--no-computer-use` to keep both disabled. Interactive installs ask when no choice is persisted; non-interactive installs require one of these flags. The official `codex-security@openai-curated` plugin remains a separate install attempt. If no global Codex CLI is available, HolyCodex can use the active Bun executable or a supported npm/pnpm package runner. External availability failures are reported with actionable human and JSON results. Cleanup leaves independent official plugins installed. Build Web Apps remains separately managed by Codex.
+Use `holycodex --help` for commands and options. `--plan` selects the catalog plan, `--fast`, `--fast-all`, and `--no-fast` select the service tier, and `--computer-use` or `--no-computer-use` controls the optional official plugin. Standard is the default tier. See [routing policy](../../docs/ROUTING.md) for plan values, quotas, and route ownership.
 
-Human-readable installs show each step as it completes. Use `-v` or `--verbose` for launcher, backup, plan, and plugin-state details; `--json` remains progress-free and machine-readable.
+`doctor` and `cleanup` accept `--json`; install also supports JSON output and concise human progress. Cleanup removes only HolyCodex-managed assets and preserves unrelated Codex configuration and plugins. The CLI does not install MCP servers.
 
-Repository, documentation, license, and security notices: https://github.com/davidbasilefilho/holycodex
+Repository, documentation, license, and security notices: [HolyCodex](https://github.com/davidbasilefilho/holycodex), [security advisories](https://github.com/davidbasilefilho/holycodex/security/advisories/new).

package/dist/cli.js

@@ -1,5 +1,5 @@
 import process$1 from "node:process";
-import { access, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
@@ -4391,7 +4391,7 @@ function superRefine(fn, params) {
 }
 //#endregion
 //#region packages/cli/src/catalog.ts
-var VERSION = "0.13.4";
+var VERSION = "0.13.5";
 var SKILLS = [
 	"ast-grep",
 	"babysit-ci",
@@ -6758,7 +6758,9 @@ function formatInstalledRuntimeGuidance(pluginRoot) {
 var CORE_INSTRUCTIONS = "HolyCodex: Root is user-facing. Before updates, classify intent and load required skills. Start with \"I detect [intent] intent — [action].\" Choose the accurate intent naturally; no fixed intent taxonomy applies. `plan` and `plan-review` instead own their exact heading and intent as the first visible block; no other mode prints a heading. Do not conceal orchestration. Give concise updates naming each specialist type and what it will do, such as \"Explorer maps X\", \"Librarian verifies Y\", or \"Worker implements Z\". Do not disclose Root orchestration mechanics or explain why delegation is running unless asked. Skills govern method only. Root owns interaction, intent, scope, architecture, product choices, ambiguity, integration, external state, and final judgment and verification. Root is not another implementation branch: evaluate specialist output against scope, fixed architecture, user decisions, repository conventions, and proof; reject or repair weak output and integrate only accepted work. On every plan other than Go, use a CLI workflow for substantive discovery, implementation, verification, multi-file work, risky changes, or architecture-sensitive work. Root may work directly for genuinely small bounded operations such as repository synchronization, one quick mechanical edit, or an equivalent one-off change. State when the direct-work exception applies, and never use it to bypass delegation for broader work. Never invoke regular Codex collaboration subagents. If a required workflow is unavailable or cannot perform the operation, report the blocker instead of bypassing delegation. Missing task-child visibility is not a reason to avoid workflows. Go does not support workflows, so Root works directly without specialist subagents. A task may contain multiple sequential workflows. Prefer the smallest useful fan-out, stop discovery when evidence is sufficient, and avoid duplicate investigation. The selected plan is authoritative: enforce its permitted model routes for each agent and stage, low verbosity, Fast as the only service-tier variation, concurrency, soft target calls, hard maximum calls, workflow depth, retries, loop iterations, fan-out, projected usage, and soft-size guidance. Root should remain near target calls and exceed them only when intermediate evidence justifies more work; the hard maximum is only a safety and quota ceiling. Larger plans do not automatically consume larger allowances. Keep explorer, librarian, and worker selectable only where the plan permits. Root owns workflow integration and final proof. After any code or manifest implementation, Root loads `code-review` exactly once before final response; it also loads `code-review` for a user-requested snippet, file, directory, diff, patch, or PR review. That skill owns the final audit, repair, proportional checks and reruns, reinspection, diff, and status. Classify unknowns: delegate facts, ask material decisions, and state and use safe reversible defaults. Whenever Root needs user input or would ask any question, it must use `request_user_input` when that tool is available, in every scenario and mode. Root must never stop or reply with a plain-text question when the tool is available. If the tool is unavailable, use a safe reversible default where possible or report a non-question blocker. Never repeat questions or ask discoverable facts. Root must use `request_user_input` immediately before committing, pushing, creating or moving tags, building or compiling, publishing, deploying, destructive or irreversible actions, permission changes, financial actions, sending, or any other externally visible action. Earlier general authorization does not replace this immediate approval unless the user explicitly authorized that exact action in the current turn. Root controls browser and native desktop UI itself. Explorer is repository-read-only, Librarian research-only, and Worker cannot alter dashboards, accounts, permissions, or external state. Specialists never delegate, broaden, review, or make final judgments.";
 var NATIVE_IO_INSTRUCTIONS = "For `plan` and `plan-review` headings, never print provisionally. Never delegate browser or computer control. For frontend creation, redesign, or visual verification, use installed Build Web Apps `frontend-app-builder` for concept, approval, implementation, and visual verification. For authorized security reviews, audits, scans, threat models, vulnerabilities, or attack paths, use matching installed Codex Security plugin skills. Use these capabilities instead of manual-click instructions, shell-as-GUI, or public research as a substitute for authenticated control. Use Codex native `apply_patch` for workspace file creation, updates, moves, and deletion. Use available native read or shell tools for file inspection and repository search. Do not re-read files only to verify a successful `apply_patch` call.";
 var COMPUTER_USE_INSTRUCTIONS = "For native desktop tasks, use the available Computer Use capability.";
-var ROOT_LUNA_POLICY = "Root is the judgment and control plane: own interaction, scope, architecture, product and risk decisions, workflow integration, material ambiguity, external state, and the final decision. Luna specialists are bounded execution context: Explorer maps sufficient repository facts, Librarian verifies assigned current facts, and Worker implements, integrates, inspects diffs, runs checks, performs mechanical repair and retest, routine review, evidence compression, and optional synthesis. Root accepts successful structured Luna evidence without rereading or re-verifying it; material architecture, product, scope, risk, or contradictory-evidence decisions return to Root. On plus-low, prefer retained context, compact outcomes, Luna-local loops and synthesis, sufficient discovery, and genuine concurrency without changing plan quotas. Structured substantive outcomes are the branching contract, not prose parsing. Escalate Luna high to xhigh to max only when the evidence justifies it and the active plan permits the route; max insufficiency returns compact evidence to Root and never creates a Sol specialist.";
+var ROOT_LUNA_POLICY = "Root is the judgment and control plane: own interaction, scope, architecture, product and risk decisions, workflow integration, material ambiguity, external state, and the final decision. Luna specialists are bounded execution context: Explorer maps sufficient repository facts, Librarian verifies assigned current facts, and Worker implements, integrates, inspects diffs, runs checks, performs mechanical repair and retest, routine review, evidence compression, and optional synthesis. Root accepts successful structured Luna evidence without rereading or re-verifying it; material architecture, product, scope, risk, or contradictory-evidence decisions return to Root. When retained context is valid, prefer it with compact outcomes, Luna-local loops and synthesis, sufficient discovery, and genuine concurrency without changing plan quotas. Structured substantive outcomes are the branching contract, not prose parsing. Escalate Luna high to xhigh to max only when the evidence justifies it and the active plan permits the route; max insufficiency returns compact evidence to Root and never creates a Sol specialist.";
+var ROOT_DESIGN_GATE_POLICY = "Use a lightweight Root design gate only for architecture-sensitive, substantive, or meaningfully multi-file work; trivial, one-off mechanical, and genuinely small single-file work is excluded. Record the owner and seam, data and control flow, stable interfaces, state and policy location, exclusions, duplication seam, errors and recovery, tests, compatibility, and why the chosen shape is preferred when real alternatives exist. This is a compact constraint gate, not a mandatory extra call or a second plan. Repository-native evidence from source, tests, configuration, commands, diff, and status is authoritative for implementation facts. If repository evidence conflicts with the approved constraint, architecture, scope, or another material decision, escalate to Root rather than resolving it silently.";
+var WORKER_BRIEF_POLICY = "Root gives Worker a compact constraint/outcome brief containing the objective and outcome, literal scope and exclusions, owner and seam, existing mechanism to extend, data and control flow, stable interfaces, state and policy location, error and recovery obligations, compatibility, tests and exact repository-native proof, plus stop and escalation conditions. Worker follows that brief, does not rediscover architecture or make material choices, and returns the standard structured outcome. Worker may perform one warranted bounded diff-level taste/simplification pass for clarity, naming, duplication, or avoidable complexity in changed files only; it must preserve behavior, interfaces, ownership, and scope and then stop. Worker routine review and repair stay within that seam; Root retains final judgment for material architecture, product, scope, risk, and contradictory evidence.";
 var CODE_REVIEW_ACTIVATION_POLICY = "After loading `code-review`, its first visible line is **CODE REVIEW MODE ACTIVATED**.";
 /** Gets core instructions with platform and active agent-capacity context. */
 function coreInstructions(platform, capacity, computerUseEnabled = false, pluginRoot) {
@@ -6766,7 +6768,7 @@ function coreInstructions(platform, capacity, computerUseEnabled = false, plugin
 	const depth = capacity?.maxDepth;
 	const capacityInstructions = threads === void 0 || depth === void 0 ? "Before delegation, use active collaboration tool instructions as the authoritative agent-capacity limit." : `Host agent capacity: agents.max_concurrent_threads_per_session=${threads} includes Root. The host nesting limit is ${depth}; the active plan's maxCalls is the hard workflow call ceiling and targetCalls is soft planning guidance. Its lower concurrency, depth, and fan-out limits remain authoritative. Substantive, multi-file, risky, and architecture-sensitive work uses a CLI workflow; genuinely small bounded operations may remain direct. Report a blocker when a required workflow runtime is unavailable. Go does not support workflows, so Root works directly without specialist subagents.`;
 	const platformInstructions = platform === "win32" ? ` ${WINDOWS_SHELL_POLICY}` : "";
-	return `${CORE_INSTRUCTIONS} ${ROOT_LUNA_POLICY} ${LITE_WRITING_POLICY} ${CONTEXT7_POLICY} ${NATIVE_IO_INSTRUCTIONS}${computerUseEnabled ? ` ${COMPUTER_USE_INSTRUCTIONS}` : ""} ${CODE_REVIEW_ACTIVATION_POLICY} ${capacityInstructions}${platformInstructions}${pluginRoot === void 0 ? "" : ` ${formatInstalledRuntimeGuidance(pluginRoot)}`}`;
+	return `${CORE_INSTRUCTIONS} ${ROOT_LUNA_POLICY} ${ROOT_DESIGN_GATE_POLICY} ${WORKER_BRIEF_POLICY} ${LITE_WRITING_POLICY} ${CONTEXT7_POLICY} ${NATIVE_IO_INSTRUCTIONS}${computerUseEnabled ? ` ${COMPUTER_USE_INSTRUCTIONS}` : ""} ${CODE_REVIEW_ACTIVATION_POLICY} ${capacityInstructions}${platformInstructions}${pluginRoot === void 0 ? "" : ` ${formatInstalledRuntimeGuidance(pluginRoot)}`}`;
 }
 //#endregion
 //#region packages/cli/src/doctor.ts
@@ -6935,16 +6937,26 @@ async function exists(path) {
 }
 /** Provides backup. */
 async function backup(path, root) {
-	if (!await exists(path)) return void 0;
-	const target = join(root, path.replace(/^([A-Za-z]:)?[\\/]+/, "").replaceAll(":", ""));
+	try {
+		await lstat(path);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+	const target = join(root, backupPath(path));
 	await mkdir(dirname(target), { recursive: true });
 	await copyBackup(path, target);
 	return target;
 }
+function backupPath(path) {
+	const segments = path.replaceAll("\\", "/").replace(/^(?:[A-Za-z]:)?\/+/, "").split("/").filter((segment) => segment !== "" && segment !== ".");
+	if (segments.some((segment) => segment === "..")) throw new Error(`Cannot create a backup for unsafe path: ${path}`);
+	return join(...segments);
+}
 async function copyBackup(source, target) {
 	const metadata = await lstat(source);
 	if (metadata.isSymbolicLink()) {
-		await writeFile(`${target}.symlink`, await readlink(source), "utf8");
+		await symlink(await readlink(source), target);
 		return;
 	}
 	if (!metadata.isDirectory()) {
@@ -6954,6 +6966,60 @@ async function copyBackup(source, target) {
 	await mkdir(target, { recursive: true });
 	for (const entry of await readdir(source)) await copyBackup(join(source, entry), join(target, entry));
 }
+/** Restores a backup while preserving the original file and symlink types. */
+async function restoreBackup(path, source) {
+	if (source === void 0) {
+		await rm(path, {
+			recursive: true,
+			force: true
+		});
+		return;
+	}
+	if ((await lstat(source)).isSymbolicLink()) {
+		await rm(path, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(dirname(path), { recursive: true });
+		await symlink(await readlink(source), path);
+		return;
+	}
+	await rm(path, {
+		recursive: true,
+		force: true
+	});
+	await restoreBackupTree(source, path);
+}
+async function restoreBackupTree(source, target) {
+	if (!(await lstat(source)).isDirectory()) {
+		await mkdir(dirname(target), { recursive: true });
+		await copyFile(source, target);
+		return;
+	}
+	await mkdir(target, { recursive: true });
+	for (const entry of await readdir(source)) {
+		const entrySource = join(source, entry);
+		const entryTarget = join(target, entry);
+		if ((await lstat(entrySource)).isSymbolicLink()) {
+			await rm(entryTarget, {
+				recursive: true,
+				force: true
+			});
+			await symlink(await readlink(entrySource), entryTarget);
+			continue;
+		}
+		if (entry.endsWith(".symlink")) {
+			const symlinkTarget = entryTarget.slice(0, -8);
+			await rm(symlinkTarget, {
+				recursive: true,
+				force: true
+			});
+			await symlink(await readFile(entrySource, "utf8"), symlinkTarget);
+			continue;
+		}
+		await restoreBackupTree(entrySource, entryTarget);
+	}
+}
 /** Provides atomic write. */
 async function atomicWrite(path, content) {
 	await mkdir(dirname(path), { recursive: true });
@@ -7000,23 +7066,31 @@ function assertGitBashReady(platform, resolution) {
 }
 /** Provides install. */
 async function install(options, runtime = defaultRuntime) {
+	try {
+		return await installOnce(options, runtime);
+	} finally {
+		await pruneBackupHistory();
+	}
+}
+async function installOnce(options, runtime) {
 	notify(options, "prerequisites", "Checking prerequisites", "running");
 	assertGitBashReady(runtime.platform, runtime.gitBash());
 	notify(options, "prerequisites", "Checking prerequisites", "complete");
 	const target = paths();
 	const existingConfig = await readText(target.config);
 	const plan = options.plan ?? readManagedPlan(existingConfig) ?? "plus";
-	const computerUseChoice = resolveComputerUseChoice(options);
+	const computerUseChoice = resolveComputerUseChoice(options, existingConfig);
 	const root = backupRoot();
 	notify(options, "backup", "Backing up existing installation", "running");
 	const configBackup = await backup(target.config, root);
 	const cacheBackup = await backup(target.marketplaceCache, root);
 	const agentsBackup = await backup(target.agents, root);
+	const legacyBackups = await Promise.all(target.legacy.map((path) => backup(path, root)));
 	const backups = [
 		configBackup,
 		cacheBackup,
 		agentsBackup,
-		...await Promise.all(target.legacy.map((path) => backup(path, root)))
+		...legacyBackups
 	].filter((path) => path !== void 0);
 	notify(options, "backup", "Backing up existing installation", "complete", `${backups.length} saved`);
 	notify(options, "configuration", "Preparing configuration", "running");
@@ -7083,9 +7157,13 @@ async function install(options, runtime = defaultRuntime) {
 		await removeObsoleteVersionCaches(target.cacheRoot);
 		notify(options, "cleanup", "Removing obsolete caches", "complete");
 	} catch (error) {
-		await restoreTarget(target.config, configBackup);
-		await restoreTarget(target.marketplaceCache, cacheBackup);
-		await restoreTarget(target.agents, agentsBackup);
+		await restoreBackup(target.config, configBackup);
+		await restoreBackup(target.marketplaceCache, cacheBackup);
+		await restoreBackup(target.agents, agentsBackup);
+		await Promise.all(target.legacy.map(async (path, index) => {
+			const source = legacyBackups[index];
+			if (source !== void 0) await restoreBackup(path, source);
+		}));
 		throw error;
 	} finally {
 		await rm(staging, {
@@ -7093,7 +7171,6 @@ async function install(options, runtime = defaultRuntime) {
 			force: true
 		});
 	}
-	await pruneBackupHistory();
 	return {
 		action: "install",
 		changed: [
@@ -7109,8 +7186,8 @@ async function install(options, runtime = defaultRuntime) {
 		buildWebApps
 	};
 }
-function resolveComputerUseChoice(options) {
-	return options.computerUse ?? "disabled";
+function resolveComputerUseChoice(options, existingConfig) {
+	return options.computerUse ?? readManagedComputerUse(existingConfig) ?? "disabled";
 }
 function computerUseFailure(result) {
 	const reason = result.reason.replaceAll("-", " ");
@@ -7139,16 +7216,9 @@ async function validateStaging(cache, agents) {
 	for (const path of required) if (!await exists(path)) missing.push(path);
 	if (missing.length > 0) throw new Error(`Staged HolyCodex installation is incomplete: ${missing.join(", ")}`);
 }
-async function restoreTarget(target, source) {
-	await rm(target, {
-		recursive: true,
-		force: true
-	});
-	if (source !== void 0) await cp(source, target, { recursive: true });
-}
 async function removeObsoleteVersionCaches(cacheRoot) {
 	if (!await exists(cacheRoot)) return;
-	for (const entry of await readdir(cacheRoot)) if (entry !== "0.13.4") await rm(join(cacheRoot, entry), {
+	for (const entry of await readdir(cacheRoot)) if (entry !== "0.13.5") await rm(join(cacheRoot, entry), {
 		recursive: true,
 		force: true
 	});
@@ -7157,7 +7227,7 @@ async function pruneBackupHistory() {
 	const root = join(tmpdir(), "holycodex-backups");
 	if (!await exists(root)) return;
 	const entries = (await readdir(root)).sort().reverse();
-	await Promise.allSettled(entries.slice(BACKUP_RETENTION, 6).map((entry) => rm(join(root, entry), {
+	await Promise.allSettled(entries.slice(BACKUP_RETENTION).map((entry) => rm(join(root, entry), {
 		recursive: true,
 		force: true
 	})));
@@ -7256,6 +7326,13 @@ function composeAgentPolicies(input, platform) {
 }
 /** Provides cleanup. */
 async function cleanup(_options) {
+	try {
+		return await cleanupOnce();
+	} finally {
+		await pruneBackupHistory();
+	}
+}
+async function cleanupOnce() {
 	const target = paths();
 	const root = backupRoot();
 	const backups = [
@@ -7308,6 +7385,10 @@ function formatCliError(error) {
 	if (!(error instanceof ZodError)) return error instanceof Error ? error.message : String(error);
 	return error.issues.map((issue) => `${issue.path.length === 0 ? "input" : issue.path.join(".")}: ${issue.message}`).join("; ");
 }
+/** Renders a stable machine-readable CLI failure envelope. */
+function renderJsonError(message) {
+	return `${JSON.stringify({ error: { message } })}\n`;
+}
 /** Checks whether terminal color output is supported. */
 function supportsColor(isTTY, noColor) {
 	return isTTY === true && noColor === void 0;
@@ -7317,15 +7398,70 @@ function renderHelp(version, color) {
 	const title = paint(color, `${BOLD}${CYAN}`, `HolyCodex ${version}`);
 	const section = (text) => paint(color, BOLD, text);
 	const muted = (text) => paint(color, DIM, text);
-	return `${title}\n${muted("Lean Codex toolkit installer and doctor")}\n\n${section("USAGE")}\n  holycodex <command> [options]\n\n${section("COMMANDS")}\n  install                         Install or update HolyCodex\n  cleanup                         Remove HolyCodex-owned state\n  doctor                          Diagnose installation and runtime\n\n${section("OPTIONS")}\n  --plan <plan>                   Model routing plan for install: ${PLAN_HELP}\n                                   Default: ${DEFAULT_PLAN}\n  --max-subagents <count>          Override concurrent direct subagents for install\n  --fast                          Use Fast for generated subagents only\n  --fast-all                      Use Fast for Root and generated subagents\n  --no-fast                       Use Standard for Root and generated subagents\n  -h, --help                      Show help\n  -v, --version                   Show version\n  --no-tui                        Accepted; commands remain noninteractive\n  --codex-autonomous              Never ask; keep workspace sandbox\n  --no-codex-autonomous           Safe interactive defaults\n  --dangerous-codex-autonomous    Never ask; disable filesystem sandbox\n  install --verbose              Show detailed install steps
-  --json                          Print machine-readable output\n  --computer-use                  Enable and verify the official Computer Use plugin\n  --no-computer-use               Keep Computer Use disabled\n`;
+	return `${title}
+${muted("Durable Codex workflow installer, doctor, and cleanup")}
+
+${section("USAGE")}
+  holycodex <command> [options]
+
+${section("COMMANDS")}
+  install                         Install or update HolyCodex
+  cleanup                         Remove HolyCodex-owned state
+  doctor                          Diagnose installation and runtime
+
+${section("OPTIONS")}
+  --plan <plan>                   Model routing plan for install: ${PLAN_HELP}
+                                   Default: ${DEFAULT_PLAN}
+  --max-subagents <count>         Override concurrent direct subagents for install
+  --fast                          Use Fast for generated subagents only
+  --fast-all                      Use Fast for Root and generated subagents
+  --no-fast                       Use Standard for Root and generated subagents
+  -h, --help                      Show help
+  -v, --version                   Show version
+  --no-tui                        Accepted; commands remain noninteractive
+  --codex-autonomous              Never ask; keep workspace sandbox
+  --no-codex-autonomous           Safe interactive defaults
+  --dangerous-codex-autonomous    Never ask; disable filesystem sandbox
+  install --verbose               Show detailed install steps
+  --json                          Print machine-readable output
+  --computer-use                  Enable and verify the official Computer Use plugin
+  --no-computer-use               Keep Computer Use disabled
+`;
 }
 /** Renders install-specific model plan and option help. */
 function renderInstallHelp(version, color) {
 	const title = paint(color, `${BOLD}${CYAN}`, `HolyCodex ${version}`);
 	const section = (text) => `${paint(color, BOLD, text)}${text === "Options:" ? "\n  --computer-use                  Enable and verify the official Computer Use plugin\n  --no-computer-use               Keep Computer Use disabled" : ""}`;
-	return `${title}\n\n${section("Usage:")}\n  holycodex install [options]\n\n${section("Options:")}\n  --plan <plan>                   Model routing plan: ${PLAN_HELP}\n                                   Default: ${DEFAULT_PLAN}\n  --max-subagents <count>          Override concurrent direct subagents\n  --fast                          Use Fast for generated subagents only\n  --fast-all                      Use Fast for Root and generated subagents\n  --no-fast                       Use Standard for Root and generated subagents\n  -v, --verbose                   Show detailed install steps
-  --json                          Print machine-readable output\n  --no-tui                        Accepted; install remains noninteractive\n  --codex-autonomous              Never ask; keep workspace sandbox\n  --no-codex-autonomous           Safe interactive defaults\n  --dangerous-codex-autonomous    Never ask; disable filesystem sandbox\n  -h, --help                      Show help\n\nPlans provide increasing expected model usage and capability. Fast flags are mutually exclusive.\n\n${section("Examples:")}\n  bunx holycodex install\n  bunx holycodex install --plan go\n  bunx holycodex install --plan plus-low --fast\n  bunx holycodex install --plan plus-high\n  bunx holycodex install --plan pro-5x --fast-all\n  bunx holycodex install --plan pro-20x --no-fast\n`;
+	return `${title}
+
+${section("Usage:")}
+  holycodex install [options]
+
+${section("Options:")}
+  --plan <plan>                   Model routing plan: ${PLAN_HELP}
+                                   Default: ${DEFAULT_PLAN}
+  --max-subagents <count>         Override concurrent direct subagents
+  --fast                          Use Fast for generated subagents only
+  --fast-all                      Use Fast for Root and generated subagents
+  --no-fast                       Use Standard for Root and generated subagents
+  -v, --verbose                   Show detailed install steps
+  --json                          Print machine-readable output
+  --no-tui                        Accepted; install remains noninteractive
+  --codex-autonomous              Never ask; keep workspace sandbox
+  --no-codex-autonomous           Safe interactive defaults
+  --dangerous-codex-autonomous    Never ask; disable filesystem sandbox
+  -h, --help                      Show help
+
+Plans provide increasing expected model usage and capability. Fast flags are mutually exclusive.
+
+${section("Examples:")}
+  bunx holycodex install
+  bunx holycodex install --plan go
+  bunx holycodex install --plan plus-low --fast
+  bunx holycodex install --plan plus-high
+  bunx holycodex install --plan pro-5x --fast-all
+  bunx holycodex install --plan pro-20x --no-fast
+`;
 }
 /** Renders error. */
 function renderError(message, color) {
@@ -7394,8 +7530,8 @@ function renderNotice(kind, message, color) {
 }
 //#endregion
 //#region packages/cli/src/cli.ts
-async function main() {
-	const parsed = parseCliArguments(process$1.argv.slice(2));
+async function main(args = process$1.argv.slice(2)) {
+	const parsed = parseCliArguments(args);
 	const stdoutColor = supportsColor(process$1.stdout.isTTY, process$1.env.NO_COLOR);
 	const stderrColor = supportsColor(process$1.stderr.isTTY, process$1.env.NO_COLOR);
 	if (parsed.action === "help") {
@@ -7422,15 +7558,18 @@ async function main() {
 		if (!result.healthy) process$1.exitCode = 1;
 		return;
 	}
-	if (parsed.autonomy.requested && parsed.autonomy.mode === "dangerous") process$1.stderr.write(renderNotice("warning", "Dangerous autonomy disables approvals and filesystem sandboxing.", stderrColor));
+	if (!parsed.json && parsed.autonomy.requested && parsed.autonomy.mode === "dangerous") process$1.stderr.write(renderNotice("warning", "Dangerous autonomy disables approvals and filesystem sandboxing.", stderrColor));
 	const result = parsed.command === "install" ? await install(options) : await cleanup(options);
 	process$1.stdout.write(parsed.json ? `${JSON.stringify(result)}\n` : renderRunResult(result, stdoutColor));
 }
 try {
 	await main();
 } catch (error) {
-	const color = supportsColor(process$1.stderr.isTTY, process$1.env.NO_COLOR);
-	process$1.stderr.write(renderError(formatCliError(error), color));
+	if (process$1.argv.slice(2).includes("--json")) process$1.stderr.write(renderJsonError(formatCliError(error)));
+	else {
+		const color = supportsColor(process$1.stderr.isTTY, process$1.env.NO_COLOR);
+		process$1.stderr.write(renderError(formatCliError(error), color));
+	}
 	process$1.exitCode = 1;
 }
 //#endregion

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "holycodex",
-  "version": "0.13.4",
-  "description": "Lean Codex-only agent toolkit installer and doctor",
+  "version": "0.13.5",
+  "description": "HolyCodex installer, doctor, and cleanup CLI for durable Codex workflows",
   "keywords": [
     "agents",
     "chatgpt",
     "codex",
-    "developer-tools"
+    "developer-tools",
+    "lsp",
+    "orchestration",
+    "workflows"
   ],
   "homepage": "https://github.com/davidbasilefilho/holycodex#readme",
   "bugs": {
@@ -39,7 +42,7 @@
     "prepack": "vp run --workspace-root build"
   },
   "dependencies": {
-    "@holycodex/plugin": "0.13.4",
+    "@holycodex/plugin": "0.13.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {