heximon 0.9.0 → 0.11.0

package/dist/skills-command-Czsv_c74.mjs

@@ -0,0 +1,1799 @@
+import { createRequire } from "node:module";
+import { cancel, confirm, intro, log, outro, password, select, text } from "@clack/prompts";
+import process from "node:process";
+import { stripVTControlCharacters } from "node:util";
+import { defineCommand, parseArgs, renderUsage, runCommand, runMain } from "citty";
+import { readFileSync, statSync } from "node:fs";
+import { DiagnosticSeverity, SourceLocation } from "@heximon/compiler";
+import { spawn } from "node:child_process";
+import { dirname, join, relative, resolve } from "pathe";
+import { cp, lstat, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+//#region src/prompter.ts
+/** Thrown when the operator cancels an interactive prompt (Ctrl-C). */
+var PromptCancelledError = class extends Error {
+	constructor() {
+		super("Prompt cancelled.");
+		this.name = "PromptCancelledError";
+	}
+};
+//#endregion
+//#region src/clack-prompter.ts
+/**
+* The {@link Prompter} port backed by `@clack/prompts` — the one interactive surface the CLI exposes. A cancelled
+* prompt (clack's sentinel symbol) is normalized to a thrown {@link PromptCancelledError} so the credential
+* resolver handles one cancel failure mode.
+*/
+var ClackPrompter = class {
+	/** @throws PromptCancelledError when cancelled. */
+	async secret(message) {
+		const value = await password({ message });
+		if (typeof value === "symbol") throw new PromptCancelledError();
+		return value;
+	}
+	/** @throws PromptCancelledError when cancelled. */
+	async text(message) {
+		const value = await text({ message });
+		if (typeof value === "symbol") throw new PromptCancelledError();
+		return value;
+	}
+};
+//#endregion
+//#region src/cli-diagnostics.ts
+/** Builds the {@link CliDiagnostic}s of a `--json` document. */
+var CliDiagnostics = class CliDiagnostics {
+	/**
+	* Convert compiler diagnostics. Every compiler field stays as it is; `file`, `line` and `column` are added
+	* from the primary span. A source file that cannot be read gives `file` only.
+	*
+	* @param diagnostics - The diagnostics of a compile.
+	* @returns One CLI diagnostic for each compiler diagnostic, in the same order.
+	*/
+	static fromCompiler(diagnostics) {
+		const sources = /* @__PURE__ */ new Map();
+		return diagnostics.map((diagnostic) => {
+			const span = CliDiagnostics.primarySpan(diagnostic);
+			if (span === void 0) return { ...diagnostic };
+			if (!sources.has(span.sourceFile)) sources.set(span.sourceFile, CliDiagnostics.readSource(span.sourceFile));
+			const position = sources.get(span.sourceFile)?.locationAt(span.start);
+			return {
+				...diagnostic,
+				file: span.sourceFile,
+				...position === void 0 ? {} : {
+					line: position.line,
+					column: position.column
+				}
+			};
+		});
+	}
+	/**
+	* Make one error diagnostic that the CLI raises.
+	*
+	* @param code - The stable code.
+	* @param message - The sentence that names the problem.
+	* @param details - The fix hint, the option the diagnostic is about, and the file it points at.
+	* @returns The diagnostic.
+	*/
+	static error(code, message, details = {}) {
+		return CliDiagnostics.of(DiagnosticSeverity.Error, code, message, details);
+	}
+	/**
+	* Make one diagnostic that the CLI raises, at a chosen severity.
+	*
+	* @param severity - `error` fails the command; `warning` is advisory.
+	* @param code - The stable code.
+	* @param message - The sentence that names the problem.
+	* @param details - The fix hint, the option the diagnostic is about, and the file it points at.
+	* @returns The diagnostic.
+	*/
+	static of(severity, code, message, details = {}) {
+		return {
+			severity,
+			code,
+			message,
+			...details.hint === void 0 ? {} : { hint: details.hint },
+			...details.file === void 0 ? {} : { file: details.file },
+			...details.option === void 0 ? {} : { option: details.option }
+		};
+	}
+	/** The span a renderer anchors on: the diagnostic's own span, else its primary label. */
+	static primarySpan(diagnostic) {
+		return diagnostic.span ?? diagnostic.labels?.find((label) => label.isPrimary === true)?.span ?? diagnostic.labels?.[0]?.span;
+	}
+	/** Read one source file for its line table, or `undefined` when it cannot be read. */
+	static readSource(sourceFile) {
+		try {
+			return new SourceLocation(readFileSync(sourceFile, "utf8"));
+		} catch {
+			return;
+		}
+	}
+};
+//#endregion
+//#region src/cli-json-document.ts
+/**
+* The stable codes of the failures the CLI itself raises in a `--json` document. A compiler diagnostic keeps
+* its own compiler code; these cover what happens around the compile.
+*/
+const CliDiagnosticCode = {
+	/** The command threw an error it does not expect. The message is the error message; stderr has the stack. */
+	UnexpectedError: "cli.unexpected-error",
+	/** The command needs an answer that it would ask for in a prompt, and `--json` never prompts. */
+	OptionRequired: "cli.option-required",
+	/** The options of the run contradict each other, or an option has a value the command cannot use. */
+	InvalidOptions: "cli.invalid-options",
+	/** The `heximon.config.ts` sidecar threw when it was loaded. `file` names the sidecar. */
+	ConfigUnreadable: "cli.config-unreadable",
+	/** The command could not start the child process that runs the app's TypeScript source. */
+	ReexecFailed: "cli.reexec-failed",
+	/** The arguments do not fit the command: a missing positional, an unknown subcommand. stderr has the usage. */
+	UsageError: "cli.usage-error"
+};
+//#endregion
+//#region src/stdout-redirect.ts
+/**
+* Sends everything written to stdout to stderr for a while, so the log lines of an app that runs in this
+* process cannot mix with the JSON the command prints. {@link write} reaches the true stdout for that JSON,
+* also when this redirect starts inside another one (the executable's, which stays on until the process exits).
+*/
+var StdoutRedirect = class StdoutRedirect {
+	/** Every started redirect that has not stopped, so a redirect that starts inside one of them finds it. */
+	static started = /* @__PURE__ */ new Set();
+	/** The writer this redirect replaced, bound to stdout, for {@link write}. */
+	original;
+	/** The same writer as it was installed, unbound, which {@link stop} puts back so an outer redirect sees itself. */
+	replaced;
+	/** The writer this redirect installed, so {@link stop} restores only its own replacement. */
+	redirected;
+	/** The redirect this one started inside; its {@link write} reaches the true stdout. */
+	outer;
+	/** Whether {@link write} wrote a document, here or in a redirect started inside this one. */
+	documentWritten = false;
+	/** Start the redirect. A second call does nothing. */
+	start() {
+		if (this.original !== void 0) return;
+		this.outer = [...StdoutRedirect.started].find((redirect) => redirect.isInstalled());
+		this.replaced = Reflect.get(process.stdout, "write");
+		this.original = process.stdout.write.bind(process.stdout);
+		this.redirected = ((...parameters) => process.stderr.write(...parameters));
+		process.stdout.write = this.redirected;
+		StdoutRedirect.started.add(this);
+	}
+	/** Write a document to the true stdout, redirected or not: through the outer redirect, when there is one. */
+	write(text) {
+		this.documentWritten = true;
+		if (this.outer !== void 0) this.outer.write(text);
+		else (this.original ?? process.stdout.write.bind(process.stdout))(text);
+	}
+	/** Whether a document reached the true stdout through this redirect. */
+	isDocumentWritten() {
+		return this.documentWritten;
+	}
+	/** Whether the writer of this redirect is the current `process.stdout.write`. */
+	isInstalled() {
+		return this.redirected !== void 0 && process.stdout.write === this.redirected;
+	}
+	/** Stop the redirect. A writer that someone installed after this redirect stays in place. */
+	stop() {
+		if (this.original === void 0) return;
+		if (this.isInstalled() && this.replaced !== void 0) process.stdout.write = this.replaced;
+		StdoutRedirect.started.delete(this);
+		this.original = void 0;
+		this.replaced = void 0;
+		this.redirected = void 0;
+		this.outer = void 0;
+	}
+};
+//#endregion
+//#region src/cli-entry.ts
+/**
+* Starts the `heximon` command tree. Without a JSON flag it is citty's own `runMain`. With one, an argument
+* error that citty raises before a command runs (a missing positional, an unknown subcommand) is printed as one
+* {@link CliFailureDocument} on stdout, and the usage text goes to stderr. Any other error there is a
+* `cli.unexpected-error` document, with the stack on stderr. Under a JSON request, stdout is on stderr from the
+* start of the command until the process exits, and the documents reach the true stdout.
+*/
+var CliEntry = class CliEntry {
+	/** The flags that print usage; they keep citty's own output, JSON flag or not. */
+	static helpFlags = /* @__PURE__ */ new Set(["--help", "-h"]);
+	/** The name citty gives its argument and command errors. */
+	static usageErrorName = "CLIError";
+	/** The output flags as every command declares them, so the entry reads them as the command's parser does. */
+	static outputFlags = {
+		json: {
+			type: "boolean",
+			default: false
+		},
+		format: { type: "string" }
+	};
+	/**
+	* Run the command tree.
+	*
+	* @param main - The root command.
+	* @param rawArgs - The arguments after the binary name.
+	*/
+	static async run(main, rawArgs = process.argv.slice(2)) {
+		if (!CliEntry.isJsonRequest(rawArgs) || rawArgs.some((arg) => CliEntry.helpFlags.has(arg))) {
+			await runMain(main, { rawArgs: [...rawArgs] });
+			return;
+		}
+		const stdout = new StdoutRedirect();
+		stdout.start();
+		try {
+			await runCommand(main, { rawArgs: [...rawArgs] });
+		} catch (error) {
+			if (stdout.isDocumentWritten()) {
+				process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+				process.exitCode = 1;
+				return;
+			}
+			await CliEntry.reportEntryError(main, rawArgs, error, stdout);
+		}
+	}
+	/** Print an error raised before a command ran as a failure document. */
+	static async reportEntryError(main, rawArgs, error, stdout) {
+		if (!CliEntry.isUsageError(error)) {
+			process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+			CliEntry.fail(stdout, CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, error instanceof Error ? error.message : String(error), { hint: "The command failed in a way it does not expect. The stack trace is on stderr." }));
+			return;
+		}
+		const [command, parent] = await CliEntry.commandOf(main, rawArgs);
+		process.stderr.write(`${await renderUsage(command, parent)}\n`);
+		CliEntry.fail(stdout, CliDiagnostics.error(CliDiagnosticCode.UsageError, stripVTControlCharacters(error.message), { hint: "Run the command with --help to see its arguments and options." }));
+	}
+	/** Print a {@link CliFailureDocument} with one diagnostic on the true stdout, and set exit status 1. */
+	static fail(stdout, diagnostic) {
+		const document = {
+			ok: false,
+			diagnostics: [diagnostic]
+		};
+		stdout.write(`${JSON.stringify(document)}\n`);
+		process.exitCode = 1;
+	}
+	/**
+	* Whether the arguments ask for JSON output: `--json`, or `--format json`. citty's own parser reads them,
+	* so `--no-json`, `--json=false`, a repeated `--format` and a `--` separator count as the command sees them.
+	*
+	* @param rawArgs - The arguments after the binary name.
+	* @returns Whether the run prints a JSON document.
+	*/
+	static isJsonRequest(rawArgs) {
+		const parsed = parseArgs([...rawArgs], CliEntry.outputFlags);
+		return parsed.json === true || parsed.format === "json";
+	}
+	/** Whether a thrown value is a citty argument or command error. */
+	static isUsageError(error) {
+		return error instanceof Error && error.name === CliEntry.usageErrorName;
+	}
+	/** The deepest subcommand the arguments name, with its parent, for the usage text. */
+	static async commandOf(main, rawArgs) {
+		let command = main;
+		let parent;
+		for (const argument of rawArgs) {
+			if (argument.startsWith("-")) continue;
+			const next = (await CliEntry.resolve(command.subCommands))?.[argument];
+			if (next === void 0) break;
+			parent = command;
+			command = await CliEntry.resolve(next);
+		}
+		return [command, parent];
+	}
+	/** A citty `Resolvable`: the value, or what its function returns. */
+	static async resolve(value) {
+		return typeof value === "function" ? await value() : value;
+	}
+};
+//#endregion
+//#region src/cli-environment.ts
+/** Detects how the CLI is being run, so the deploy credential ladder knows whether interactive prompting is safe. */
+var CliEnvironment = class {
+	/**
+	* Whether this is an interactive session a prompt may block on: a real TTY on stdin AND not a CI runner. In CI
+	* (or a piped/non-TTY invocation) the deploy credential ladder must fail fast on a missing value rather than
+	* hang on a prompt no one can answer.
+	*/
+	static isInteractive() {
+		return process.stdin.isTTY === true && process.env["CI"] === void 0;
+	}
+};
+//#endregion
+//#region src/command-failure.ts
+/**
+* An expected failure that stops a command. {@link CommandOutput.run} prints it as a `{ ok: false }` document
+* under `--json`, and as one `heximon <command>: <message>` line on stderr without it. Both exit 1.
+*/
+var CommandFailure = class CommandFailure extends Error {
+	diagnostics;
+	/**
+	* @param diagnostics - The diagnostics of the failure; the first one gives the error message.
+	*/
+	constructor(diagnostics) {
+		super(diagnostics[0]?.message ?? "The command failed.");
+		this.diagnostics = diagnostics;
+		this.name = "CommandFailure";
+	}
+	/**
+	* A failure with one error diagnostic.
+	*
+	* @param code - The stable code.
+	* @param message - The sentence that names the problem.
+	* @param hint - How to fix it.
+	* @returns The failure, ready to throw.
+	*/
+	static of(code, message, hint) {
+		return new CommandFailure([CliDiagnostics.error(code, message, hint === void 0 ? {} : { hint })]);
+	}
+};
+/**
+* Thrown when a command would prompt under `--json`. The diagnostic has the code
+* {@link CliDiagnosticCode.OptionRequired} and names the option that supplies the answer.
+*/
+var PromptRefusedError = class extends CommandFailure {
+	option;
+	question;
+	/**
+	* @param option - The flag or environment variable that answers the prompt, for example `--yes`.
+	* @param question - The prompt the command did not show.
+	*/
+	constructor(option, question) {
+		super([CliDiagnostics.error(CliDiagnosticCode.OptionRequired, `The command needs an answer to "${question}", and it never prompts under --json.`, {
+			hint: `Pass ${option}.`,
+			option
+		})]);
+		this.option = option;
+		this.question = question;
+		this.name = "PromptRefusedError";
+	}
+};
+//#endregion
+//#region src/refusing-prompter.ts
+/**
+* The {@link Prompter} of a `--json` run: every prompt fails with a {@link PromptRefusedError} that names the
+* option or environment variable that supplies the answer.
+*/
+var RefusingPrompter = class {
+	optionFor;
+	/**
+	* @param optionFor - Maps a prompt message to the option that answers it, for example `CLOUDFLARE_API_TOKEN`.
+	*/
+	constructor(optionFor) {
+		this.optionFor = optionFor;
+	}
+	/** @throws PromptRefusedError always. */
+	secret(message) {
+		return Promise.reject(new PromptRefusedError(this.optionFor(message), message));
+	}
+	/** @throws PromptRefusedError always. */
+	text(message) {
+		return Promise.reject(new PromptRefusedError(this.optionFor(message), message));
+	}
+};
+//#endregion
+//#region src/command-output.ts
+/**
+* Owns the output mode of one command run. Under `--json`, stdout holds exactly one JSON document, written
+* when the command ends: everything else written to stdout during the run goes to stderr, a prompt fails, and a
+* thrown error becomes a `{ ok: false, diagnostics }` document.
+*/
+var CommandOutput = class CommandOutput {
+	commandName;
+	json;
+	/** The `--json` argument every command declares, so the flag is the same everywhere. */
+	static jsonFlag = {
+		type: "boolean",
+		description: "Print one JSON document on stdout when the command ends. Logs go to stderr, and the command never prompts.",
+		default: false
+	};
+	/** The document {@link emit} recorded, written when {@link run} ends. */
+	document;
+	stdout = new StdoutRedirect();
+	/**
+	* @param commandName - The verb, for the text failure line (`check`, `workflows`).
+	* @param json - Whether this run prints a JSON document.
+	*/
+	constructor(commandName, json) {
+		this.commandName = commandName;
+		this.json = json;
+	}
+	/**
+	* Decide the output mode of one run.
+	*
+	* @param commandName - The verb, for the text failure line.
+	* @param args - The parsed arguments: `--json`, or `--format json` where the command has `--format`.
+	* @returns The output owner of the run.
+	*/
+	static resolve(commandName, args) {
+		return new CommandOutput(commandName, args.json === true || args.format === "json");
+	}
+	/** Whether this run prints a JSON document instead of text. */
+	isJson() {
+		return this.json;
+	}
+	/** Whether a prompt or a spinner may run: an interactive session, and not `--json`. */
+	isInteractive() {
+		return !this.json && CliEnvironment.isInteractive();
+	}
+	/**
+	* Run the body of the command. Under `--json` it writes the one document when the body ends: the one
+	* {@link emit} recorded, or a failure document when the body threw. A {@link CommandFailure} exits 1 in both
+	* modes; without `--json`, any other error is thrown again.
+	*
+	* @param body - The work of the command. It calls {@link emit} once under `--json`.
+	*/
+	async run(body) {
+		if (!this.json) {
+			try {
+				await body();
+			} catch (error) {
+				if (!(error instanceof CommandFailure)) throw error;
+				this.reportText(error.diagnostics);
+				process.exitCode = 1;
+			}
+			return;
+		}
+		this.stdout.start();
+		try {
+			let document;
+			try {
+				await body();
+				document = this.document ?? CommandOutput.failure(CommandOutput.missingDocument());
+			} catch (error) {
+				if (!(error instanceof CommandFailure)) process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+				document = CommandOutput.failure(CommandOutput.diagnosticsOf(error));
+			}
+			if (document.ok && !CommandOutput.isZero(process.exitCode)) document = {
+				...document,
+				ok: false,
+				diagnostics: [...document.diagnostics, CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, `The command exited with status ${String(process.exitCode)}, but its document said it succeeded.`)]
+			};
+			let text;
+			try {
+				text = JSON.stringify(document);
+			} catch (error) {
+				document = CommandOutput.failure(CommandOutput.diagnosticsOf(error));
+				text = JSON.stringify(document);
+			}
+			this.stdout.write(`${text}\n`);
+			if (!document.ok && CommandOutput.isZero(process.exitCode)) process.exitCode = 1;
+		} finally {
+			this.stdout.stop();
+		}
+	}
+	/**
+	* Record the document of the run. It is written when {@link run} ends, so a later throw replaces it with a
+	* failure document. Does nothing without `--json`.
+	*
+	* @param document - The document; its `ok` must agree with the exit status the command sets.
+	* @throws Error when the run already recorded a document.
+	*/
+	emit(document) {
+		if (!this.json) return;
+		if (this.document !== void 0) throw new Error(`heximon ${this.commandName} recorded a second JSON document.`);
+		this.document = document;
+	}
+	/**
+	* Stop before a direct `@clack/prompts` call under `--json`. Does nothing without `--json`.
+	*
+	* @param option - The option that supplies the answer, for example `--yes` or `--name`.
+	* @param question - The prompt the command would show.
+	* @throws PromptRefusedError under `--json`.
+	*/
+	assertCanPrompt(option, question) {
+		if (this.json) throw new PromptRefusedError(option, question);
+	}
+	/**
+	* The {@link Prompter} of the run: the clack prompts, or under `--json` one that refuses every prompt.
+	*
+	* @param optionFor - Maps a prompt message to the option or environment variable that answers it.
+	* @returns The prompter.
+	*/
+	prompter(optionFor) {
+		return this.json ? new RefusingPrompter(optionFor) : new ClackPrompter();
+	}
+	/** Print the errors of a {@link CommandFailure} as text lines on stderr. */
+	reportText(diagnostics) {
+		for (const diagnostic of diagnostics) {
+			const hint = diagnostic.hint === void 0 ? "" : ` ${diagnostic.hint}`;
+			process.stderr.write(`heximon ${this.commandName}: ${diagnostic.message}${hint}\n`);
+		}
+	}
+	/** The diagnostics of a thrown value: those of a {@link CommandFailure}, else one unexpected error. */
+	static diagnosticsOf(error) {
+		if (error instanceof CommandFailure) return error.diagnostics;
+		return [CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, error instanceof Error ? error.message : String(error), { hint: "The command failed in a way it does not expect. The stack trace is on stderr." })];
+	}
+	/** The diagnostic of a body that ended without {@link emit}: a defect of the command. */
+	static missingDocument() {
+		return [CliDiagnostics.error(CliDiagnosticCode.UnexpectedError, "The command ended without a JSON document.")];
+	}
+	/** A failure document. */
+	static failure(diagnostics) {
+		return {
+			ok: false,
+			diagnostics
+		};
+	}
+	/** Whether an exit status is unset or zero. */
+	static isZero(exitCode) {
+		return exitCode === void 0 || exitCode === null || Number(exitCode) === 0;
+	}
+};
+//#endregion
+//#region src/create-json-document.ts
+/** The codes of the failures `heximon create` raises in a `--json` document. */
+const CreateDiagnosticCode = {
+	/** The target directory already holds files. `create` never overwrites. */
+	TargetNotEmpty: "create.target-not-empty",
+	/** The starter template could not be downloaded, from the version branch or from `main`. */
+	TemplateDownloadFailed: "create.template-download-failed",
+	/** The scaffold failed for another reason, for example a template without a `package.json`. */
+	ScaffoldFailed: "create.scaffold-failed",
+	/** The registry check before the install failed, so the command did not install. The project stays. */
+	RegistryAccessFailed: "create.registry-access-failed",
+	/** The dependency install exited with a non-zero status. The project stays. */
+	InstallFailed: "create.install-failed",
+	/** A warning: the agent skill could not be fetched. The project is complete without it. */
+	SkillsUnavailable: "create.skills-unavailable"
+};
+//#endregion
+//#region src/registry-access.ts
+/** The verdict {@link RegistryAccess.probe} classifies an `npm view` attempt into. */
+const RegistryAccessStatus = {
+	/** The probe package resolved — the registry is reachable and authorized. */
+	Ok: "ok",
+	/** The registry rejected the request for lacking (or holding invalid) credentials. */
+	Unauthorized: "unauthorized",
+	/** The registry could not be reached at all (DNS, network, timeout, an unrecognized failure). */
+	Unreachable: "unreachable",
+	/** The registry was reached and authorized the request, but the probe package is not there. */
+	NotFound: "not-found"
+};
+/**
+* Probes whether `@heximon/*` packages are readable from GitHub Packages, the private registry the
+* framework publishes to (the `heximon` CLI itself stays on public npm). A scaffolded project needs a
+* `.npmrc` scope line plus a token in the user's `~/.npmrc`; this probe reuses npm's own config
+* resolution — the same files npm itself reads — so the verdict matches what an install would do.
+*/
+var RegistryAccess = class RegistryAccess {
+	/** The private registry `@heximon/*` packages publish to. */
+	static gitHubPackagesRegistry = "https://npm.pkg.github.com";
+	/** The package probed to decide reachability — small, always published, always current. */
+	static probePackage = "@heximon/runtime";
+	/** The scope line a scaffolded project's `.npmrc` carries, routing `@heximon/*` to GitHub Packages. */
+	static npmrcScopeLine = `@heximon:registry=${RegistryAccess.gitHubPackagesRegistry}`;
+	run;
+	/**
+	* @param run - The process runner to probe with. Defaults to spawning `npm` for real; a test injects a
+	* stub so the probe never touches the network.
+	*/
+	constructor(run = (command, commandArguments) => RegistryAccess.spawnProcess(command, commandArguments)) {
+		this.run = run;
+	}
+	/**
+	* Runs `npm view @heximon/runtime version` against GitHub Packages and classifies the result.
+	*
+	* @returns The classified verdict, with the raw output kept as `detail` for diagnostics.
+	*/
+	async probe() {
+		const result = await this.run("npm", [
+			"view",
+			RegistryAccess.probePackage,
+			"version",
+			`--registry=${RegistryAccess.gitHubPackagesRegistry}`,
+			"--json"
+		]);
+		const combined = `${result.stdout}\n${result.stderr}`;
+		const detail = combined.trim();
+		if (result.exitCode === 0) return {
+			status: RegistryAccessStatus.Ok,
+			detail: detail.length === 0 ? void 0 : detail
+		};
+		if (/E401|E403|ENEEDAUTH/.test(combined)) return {
+			status: RegistryAccessStatus.Unauthorized,
+			detail
+		};
+		if (/E404/.test(combined)) return {
+			status: RegistryAccessStatus.NotFound,
+			detail
+		};
+		return {
+			status: RegistryAccessStatus.Unreachable,
+			detail
+		};
+	}
+	/**
+	* The fix instructions printed when {@link probe} does not report {@link RegistryAccessStatus.Ok}.
+	*
+	* @param status - The non-Ok verdict, when known — shapes the wording between an auth fix and a network hint.
+	*/
+	static fixInstructions(status = RegistryAccessStatus.Unauthorized) {
+		if (status === RegistryAccessStatus.Unreachable) return [
+			`Cannot reach ${RegistryAccess.gitHubPackagesRegistry}.`,
+			"Check your network connection.",
+			"Then run the install again."
+		].join("\n");
+		return [
+			"Cannot read @heximon/* from GitHub Packages.",
+			"Add these lines to ~/.npmrc:",
+			`  ${RegistryAccess.npmrcScopeLine}`,
+			"  //npm.pkg.github.com/:_authToken=<a GitHub token with the read:packages scope>",
+			"Then run the install again."
+		].join("\n");
+	}
+	/** The default {@link ProcessRunner}: spawns `npm` for real, capturing stdout/stderr. */
+	static spawnProcess(command, commandArguments) {
+		return new Promise((resolveRun) => {
+			const child = spawn(command, commandArguments, { shell: false });
+			let stdout = "";
+			let stderr = "";
+			child.stdout.on("data", (chunk) => {
+				stdout += chunk.toString();
+			});
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+			child.on("error", (error) => {
+				resolveRun({
+					exitCode: 1,
+					stdout: "",
+					stderr: error.message
+				});
+			});
+			child.on("close", (exitCode) => {
+				resolveRun({
+					exitCode: exitCode ?? 1,
+					stdout,
+					stderr
+				});
+			});
+		});
+	}
+};
+//#endregion
+//#region src/project-scaffolder.ts
+/**
+* A template fetch that failed — the giget ref could not be downloaded. Distinct from every local failure so a
+* caller may retry another ref without also retrying (or cleaning up after) a validation or manifest error.
+*/
+var TemplateDownloadError = class extends Error {
+	/** The giget source string that could not be fetched. */
+	gigetSource;
+	constructor(gigetSource, cause) {
+		super(`Could not download the template ${gigetSource}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		this.name = "TemplateDownloadError";
+		this.gigetSource = gigetSource;
+	}
+};
+/** A target directory that already holds content. `create` never overwrites, so it refuses the target. */
+var ProjectDirectoryOccupiedError = class extends Error {
+	projectDirectory;
+	/**
+	* @param projectDirectory - The absolute directory that is not empty.
+	*/
+	constructor(projectDirectory) {
+		super(`The directory ${projectDirectory} already exists and is not empty — choose another name, or remove the directory yourself.`);
+		this.projectDirectory = projectDirectory;
+		this.name = "ProjectDirectoryOccupiedError";
+	}
+};
+/**
+* Materializes a new Heximon project from a starters template: resolves the template directory name from
+* the {@link TemplateSelection}, fetches (giget) or copies (local) it, then stamps the project name and
+* the `@heximon/*` dependency ranges onto the fetched `package.json`. Pure filesystem work — prompting,
+* git, and dependency installation live with the CLI command.
+*/
+var ProjectScaffolder = class ProjectScaffolder {
+	/** A project/directory name: lowercase npm-safe segments (no scopes — the directory is the name). */
+	static projectNamePattern = /^[a-z0-9][a-z0-9._-]*$/;
+	/**
+	* Resolve the concrete template directory name for a selection — the validator variant is a `-zod` /
+	* `-valibot` suffix; `"none"` selects the base directory.
+	*
+	* @param selection - The template + validator axes.
+	* @returns The starters directory name (e.g. `"database-valibot"`).
+	*/
+	static templateNameOf(selection) {
+		return selection.validator === "none" ? selection.template : `${selection.template}-${selection.validator}`;
+	}
+	/**
+	* Validate a project name for use as both the directory and the `package.json` name.
+	*
+	* @param name - The candidate name.
+	* @returns `undefined` when valid, else a human-readable problem statement.
+	*/
+	static validateProjectName(name) {
+		if (name.length === 0) return "The project name is empty.";
+		if (!ProjectScaffolder.projectNamePattern.test(name)) return `"${name}" is not a valid project name — use lowercase letters, digits, and . _ - (it becomes the directory and package name).`;
+	}
+	/**
+	* Materialize the project: fetch/copy the template into `<parentDirectory>/<projectName>` and stamp the
+	* manifest. A target directory that already holds content is refused, never overwritten.
+	*
+	* @param request - What to scaffold, from where, and with which stamped versions.
+	* @returns The created project directory + the resolved template name.
+	*/
+	async scaffold(request) {
+		const templateName = ProjectScaffolder.templateNameOf(request);
+		const { projectDirectory } = await ProjectScaffolder.prepareTarget(request.parentDirectory, request.projectName);
+		if (request.source.localDirectory !== void 0) await cp(join(request.source.localDirectory, templateName), projectDirectory, { recursive: true });
+		else if (request.source.gigetSource !== void 0) await ProjectScaffolder.fetchTemplate(request.source.gigetSource, projectDirectory);
+		else throw new Error("No template source: provide a giget source or a local starters directory.");
+		await this.stampManifest(projectDirectory, request);
+		await ProjectScaffolder.writeNpmrc(projectDirectory, request.heximonVersion);
+		return {
+			projectDirectory,
+			templateName,
+			source: request.source
+		};
+	}
+	/**
+	* Accept a target directory: the name must be valid, the resolved path must stay a direct child of the
+	* parent, and the directory must be absent or empty. A directory holding content is refused outright —
+	* `create` never overwrites.
+	*
+	* @param parentDirectory - The directory the project directory is created under.
+	* @param projectName - The candidate project (directory + package) name.
+	* @returns The accepted target, and whether this call created the directory.
+	*/
+	static async prepareTarget(parentDirectory, projectName) {
+		const problem = ProjectScaffolder.validateProjectName(projectName);
+		if (problem !== void 0) throw new Error(problem);
+		const parent = resolve(parentDirectory);
+		const projectDirectory = resolve(parent, projectName);
+		if (projectDirectory === parent || dirname(projectDirectory) !== parent) throw new Error(`"${projectName}" resolves to ${projectDirectory}, which is outside ${parent} — the project directory must be a direct child of the parent directory.`);
+		const entries = await ProjectScaffolder.readEntries(projectDirectory);
+		if (entries === void 0) {
+			await mkdir(projectDirectory, { recursive: true });
+			return {
+				projectDirectory,
+				createdDirectory: true
+			};
+		}
+		if (entries.length > 0) throw new ProjectDirectoryOccupiedError(projectDirectory);
+		return {
+			projectDirectory,
+			createdDirectory: false
+		};
+	}
+	/**
+	* Discard what a failed scaffold left in a prepared target: the directory itself when this run created it,
+	* otherwise only the entries — a pre-existing directory was empty when accepted, so nothing else is ours.
+	*/
+	static async discardPreparedTarget(target) {
+		if (target.createdDirectory) {
+			await rm(target.projectDirectory, {
+				recursive: true,
+				force: true
+			});
+			return;
+		}
+		for (const entry of await ProjectScaffolder.readEntries(target.projectDirectory) ?? []) await rm(join(target.projectDirectory, entry), {
+			recursive: true,
+			force: true
+		});
+	}
+	/** Fetch a giget template, tagging a fetch failure so a caller can tell it from a local error. */
+	static async fetchTemplate(gigetSource, projectDirectory) {
+		const { downloadTemplate } = await import("giget");
+		try {
+			await downloadTemplate(gigetSource, { dir: projectDirectory });
+		} catch (error) {
+			throw new TemplateDownloadError(gigetSource, error);
+		}
+	}
+	/**
+	* Rewrite the scaffolded `package.json`: the project name, and every `@heximon/*` range to the CLI's
+	* lockstep version (`^<version>`) or `workspace:*`.
+	*/
+	async stampManifest(projectDirectory, request) {
+		const manifestPath = join(projectDirectory, "package.json");
+		const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+		manifest["name"] = request.projectName;
+		const range = request.heximonVersion === "workspace" ? "workspace:*" : `^${request.heximonVersion}`;
+		for (const section of ["dependencies", "devDependencies"]) {
+			const record = manifest[section];
+			if (record === void 0) continue;
+			for (const dependencyName of Object.keys(record)) if (dependencyName.startsWith("@heximon/") || dependencyName === "heximon") record[dependencyName] = range;
+		}
+		await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+	}
+	/**
+	* Write the `.npmrc` scope line that routes `@heximon/*` installs to GitHub Packages — skipped when the
+	* template already ships its own `.npmrc` (never overwritten), and in workspace mode (`heximonVersion ===
+	* "workspace"`), where the `@heximon/*` ranges are workspace links and need no registry at all.
+	*/
+	static async writeNpmrc(projectDirectory, heximonVersion) {
+		if (heximonVersion === "workspace") return;
+		const npmrcPath = join(projectDirectory, ".npmrc");
+		if (await ProjectScaffolder.pathExists(npmrcPath)) return;
+		await writeFile(npmrcPath, `${RegistryAccess.npmrcScopeLine}\n`);
+	}
+	/** Whether a filesystem path exists, of any kind. */
+	static async pathExists(path) {
+		try {
+			await stat(path);
+			return true;
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+	}
+	/** A directory's entries, or `undefined` when the directory does not exist. */
+	static async readEntries(directory) {
+		try {
+			return await readdir(directory);
+		} catch (error) {
+			if (error.code === "ENOENT") return;
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/skill-installer.ts
+/**
+* Installs the published Heximon agent skill into a scaffolded project from the docs site's RFC 8615
+* well-known endpoint — `/.well-known/skills/index.json` plus `/.well-known/skills/<name>/<file>`, the
+* same layout `npx skills add https://heximon.dev` consumes (Docus serves the docs repo's `skills/`
+* directory there natively). Best-effort by contract: the caller treats a throw as a skippable step with
+* a printed hint, never a scaffold failure.
+*/
+var SkillInstaller = class SkillInstaller {
+	sourceUrl;
+	/** The published docs site serving the skill. */
+	static defaultSourceUrl = "https://heximon.dev";
+	/** Where skills land inside the project — the universal agent layout; `.claude/skills` symlinks here. */
+	static targetDirectory = ".agents/skills";
+	/** Per-agent skills directories, each created as a relative symlink onto {@link targetDirectory}. */
+	static agentSymlinks = [".claude/skills"];
+	/** Per-request timeout — scaffolding must never hang on an unreachable docs deploy. */
+	static fetchTimeoutMs = 15e3;
+	constructor(sourceUrl = SkillInstaller.defaultSourceUrl) {
+		this.sourceUrl = sourceUrl;
+	}
+	/**
+	* Install every skill the source publishes into `projectDirectory`.
+	*
+	* @returns The installed skills, in index order.
+	* @throws {Error} When the index is unreachable/malformed or any listed file fails to download.
+	*/
+	async install(projectDirectory) {
+		const base = this.sourceUrl.replace(/\/+$/, "");
+		const index = await SkillInstaller.fetchIndex(`${base}/.well-known/skills/index.json`);
+		const installed = [];
+		for (const entry of index) {
+			const files = entry.files.filter((file) => SkillInstaller.isSafeRelativePath(file));
+			const skillDirectory = join(projectDirectory, SkillInstaller.targetDirectory, entry.name);
+			for (const file of files) {
+				const content = await SkillInstaller.fetchText(`${base}/.well-known/skills/${entry.name}/${file}`);
+				const targetPath = join(skillDirectory, file);
+				await mkdir(dirname(targetPath), { recursive: true });
+				await writeFile(targetPath, content);
+			}
+			installed.push({
+				name: entry.name,
+				directory: skillDirectory,
+				fileCount: files.length
+			});
+		}
+		if (installed.length === 0) throw new Error(`No skills published at ${base}/.well-known/skills/index.json`);
+		await SkillInstaller.linkAgentDirectories(projectDirectory);
+		return installed;
+	}
+	/**
+	* Point each per-agent skills directory (`.claude/skills`) at the universal `.agents/skills` copy via a
+	* relative symlink, so every agent convention reads the one install. Best-effort: an existing entry is
+	* left untouched, and a filesystem that cannot symlink (e.g. Windows without developer mode) is not an
+	* install failure — the universal copy stands on its own.
+	*/
+	static async linkAgentDirectories(projectDirectory) {
+		for (const agentDirectory of SkillInstaller.agentSymlinks) {
+			const linkPath = join(projectDirectory, agentDirectory);
+			const parentSegments = agentDirectory.split("/").slice(0, -1);
+			const relativeTarget = join(...parentSegments.map(() => ".."), SkillInstaller.targetDirectory);
+			try {
+				await lstat(linkPath);
+				continue;
+			} catch {}
+			try {
+				await mkdir(dirname(linkPath), { recursive: true });
+				await symlink(relativeTarget, linkPath, "dir");
+			} catch {}
+		}
+	}
+	/** Fetch and validate the discovery index, keeping only well-shaped entries with safe names. */
+	static async fetchIndex(indexUrl) {
+		const body = await SkillInstaller.fetchJson(indexUrl);
+		if (!Array.isArray(body.skills)) throw new Error(`Malformed skills index at ${indexUrl}`);
+		return body.skills.flatMap((entry) => typeof entry.name === "string" && /^[a-z0-9][a-z0-9-]*$/.test(entry.name) && Array.isArray(entry.files) ? [{
+			name: entry.name,
+			files: entry.files.filter((file) => typeof file === "string")
+		}] : []);
+	}
+	/** A relative file path with no traversal, absolute prefix, or backslash trickery. */
+	static isSafeRelativePath(file) {
+		return file.length > 0 && !file.startsWith("/") && !file.includes("\\") && !file.split("/").includes("..");
+	}
+	static async fetchJson(url) {
+		const response = await fetch(url, { signal: AbortSignal.timeout(SkillInstaller.fetchTimeoutMs) });
+		if (!response.ok) throw new Error(`GET ${url} failed with ${response.status.toString()}`);
+		return response.json();
+	}
+	static async fetchText(url) {
+		const response = await fetch(url, { signal: AbortSignal.timeout(SkillInstaller.fetchTimeoutMs) });
+		if (!response.ok) throw new Error(`GET ${url} failed with ${response.status.toString()}`);
+		return response.text();
+	}
+};
+//#endregion
+//#region src/skill-sources.ts
+/**
+* The project's recorded agent-skill sources, persisted as `heximon.skills` in its `package.json`.
+*
+* The manifest rather than the config sidecar, for one reason: `heximon create` records the default source
+* before an app exists to compile, and a tool reads the list without evaluating any TypeScript. Every entry
+* is a base URL {@link SkillInstaller} can install from — the same value `npx skills add <url>` takes.
+*/
+var SkillSources = class SkillSources {
+	/** The `package.json` member holding the framework's own manifest block. */
+	static manifestKey = "heximon";
+	/** The member of that block holding the source list. */
+	static listKey = "skills";
+	/**
+	* The sources recorded for a project, in the order they were added.
+	*
+	* @param projectDirectory - The project root holding `package.json`.
+	* @returns The recorded base URLs; empty when the manifest records none (or has no readable list).
+	* @throws {Error} When `package.json` is missing or is not readable JSON — a project whose manifest cannot
+	*   be read is not one to silently report as having no skills.
+	*/
+	static async read(projectDirectory) {
+		const block = (await SkillSources.readManifest(projectDirectory))[SkillSources.manifestKey];
+		if (typeof block !== "object" || block === null || Array.isArray(block)) return [];
+		const list = block[SkillSources.listKey];
+		return Array.isArray(list) ? list.filter((entry) => typeof entry === "string") : [];
+	}
+	/**
+	* Record one source, leaving every other manifest member untouched.
+	*
+	* @param projectDirectory - The project root holding `package.json`.
+	* @param sourceUrl - The base URL to record, normalized by {@link normalize} first.
+	* @returns `true` when the source was added, `false` when it was already recorded — so recording twice is
+	*   a no-op the caller can report as such rather than a duplicated entry.
+	*/
+	static async record(projectDirectory, sourceUrl) {
+		const normalized = SkillSources.normalize(sourceUrl);
+		const manifest = await SkillSources.readManifest(projectDirectory);
+		const existingBlock = manifest[SkillSources.manifestKey];
+		const block = typeof existingBlock === "object" && existingBlock !== null && !Array.isArray(existingBlock) ? { ...existingBlock } : {};
+		const recorded = Array.isArray(block[SkillSources.listKey]) ? block[SkillSources.listKey].filter((entry) => typeof entry === "string") : [];
+		if (recorded.includes(normalized)) return false;
+		block[SkillSources.listKey] = [...recorded, normalized];
+		manifest[SkillSources.manifestKey] = block;
+		await writeFile(join(projectDirectory, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+		return true;
+	}
+	/**
+	* The canonical form of a source URL: trailing slashes removed, so `https://heximon.dev/` and
+	* `https://heximon.dev` are one recorded entry rather than two installs of the same site.
+	*/
+	static normalize(sourceUrl) {
+		return sourceUrl.replace(/\/+$/, "");
+	}
+	/** Whether a string is an absolute `http`/`https` URL — the only form the installer can fetch from. */
+	static isInstallable(sourceUrl) {
+		try {
+			const url = new URL(sourceUrl);
+			return url.protocol === "http:" || url.protocol === "https:";
+		} catch {
+			return false;
+		}
+	}
+	/** The project manifest as a mutable record. */
+	static async readManifest(projectDirectory) {
+		const manifestPath = join(projectDirectory, "package.json");
+		const contents = await readFile(manifestPath, "utf8");
+		const manifest = JSON.parse(contents);
+		if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) throw new Error(`${manifestPath} is not a JSON object.`);
+		return manifest;
+	}
+};
+//#endregion
+//#region src/create-command.ts
+/** Where a child process of `create` writes its output. */
+const ChildOutput = {
+	/** Discard every stream (a probe such as `git rev-parse`). */
+	Ignore: "ignore",
+	/** Share this terminal, so the user sees the real output. */
+	Inherit: "inherit",
+	/** No stdin, and stdout copied to this process's stderr: the `--json` mode. */
+	Stderr: "stderr"
+};
+/** The `heximon create` verb: scaffold a new Heximon app from the starters templates. */
+const createCommand = defineCommand({
+	meta: {
+		name: "create",
+		description: "Scaffold a new Heximon app from a starter template (minimal or database, with an optional zod/valibot validator)."
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "The project directory (and package) name.",
+			required: false
+		},
+		cwd: {
+			type: "string",
+			description: "Parent directory to create the project in.",
+			default: "."
+		},
+		template: {
+			type: "string",
+			description: "Starter template: minimal | database."
+		},
+		validator: {
+			type: "string",
+			description: "Request-body validator baked into the starter: zod | valibot | none."
+		},
+		pm: {
+			type: "string",
+			description: "Package manager for the install step + printed commands (npm/pnpm/yarn/bun). Default: detected from the invoking manager."
+		},
+		install: {
+			type: "boolean",
+			description: "Install dependencies after scaffolding (--no-install to skip)."
+		},
+		git: {
+			type: "boolean",
+			description: "Initialize a git repository in the new project (skipped automatically inside an existing repository).",
+			default: true
+		},
+		yes: {
+			type: "boolean",
+			description: "Accept every default without prompting (non-interactive/CI).",
+			default: false
+		},
+		skills: {
+			type: "boolean",
+			description: "Install the Heximon agent skill from heximon.dev into .agents/skills, with .claude/skills symlinked onto it (--no-skills to skip).",
+			default: true
+		},
+		local: {
+			type: "string",
+			description: "Maintainer path: scaffold from a local starters directory instead of fetching from GitHub."
+		},
+		workspace: {
+			type: "boolean",
+			description: "Maintainer path: stamp workspace:* onto the @heximon/* ranges (in-monorepo dogfooding).",
+			default: false
+		},
+		"skip-registry-check": {
+			type: "boolean",
+			description: "Skip the GitHub Packages read check before installing (@heximon/* publishes there; heximon itself is public npm).",
+			default: false
+		},
+		json: CommandOutput.jsonFlag
+	},
+	async run({ args }) {
+		const commandOutput = CommandOutput.resolve("create", args);
+		await commandOutput.run(async () => {
+			if (commandOutput.isJson() && !args.yes) CreateReport.assertAnswered(args);
+			const interactive = commandOutput.isInteractive() && !args.yes;
+			const packageManager = CreateDefaults.resolvePackageManager(args.pm);
+			const report = new CreateReport(packageManager);
+			intro("heximon create");
+			try {
+				let projectName = args.name;
+				if (projectName === void 0 || projectName.length === 0) {
+					if (interactive) {
+						commandOutput.assertCanPrompt(CreateReport.nameOption, "Project name");
+						const answer = await text({
+							message: "Project name",
+							placeholder: CreateDefaults.projectName,
+							defaultValue: CreateDefaults.projectName,
+							validate: (value) => ProjectScaffolder.validateProjectName(value === void 0 || value === "" ? CreateDefaults.projectName : value)
+						});
+						if (typeof answer === "symbol") {
+							cancel("Cancelled — nothing created.");
+							process.exitCode = 1;
+							return;
+						}
+						projectName = answer;
+					} else projectName = CreateDefaults.projectName;
+				}
+				const nameProblem = ProjectScaffolder.validateProjectName(projectName);
+				if (nameProblem !== void 0) throw new CommandFailure([CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, nameProblem, { option: CreateReport.nameOption })]);
+				const selection = await CreateDefaults.resolveSelection(args.template, args.validator, { interactive });
+				if (selection === void 0) {
+					cancel("Cancelled — nothing created.");
+					process.exitCode = 1;
+					return;
+				}
+				const scaffolder = new ProjectScaffolder();
+				const heximonVersion = args.workspace ? "workspace" : CreateDefaults.cliVersion();
+				const parentDirectory = resolve(process.cwd(), args.cwd);
+				const templateName = ProjectScaffolder.templateNameOf(selection);
+				let result;
+				if (args.local !== void 0) result = await scaffolder.scaffold({
+					...selection,
+					projectName,
+					parentDirectory,
+					heximonVersion,
+					source: { localDirectory: resolve(process.cwd(), args.local) }
+				});
+				else result = await CreateDefaults.scaffoldFromStarters(scaffolder, {
+					selection,
+					projectName,
+					parentDirectory,
+					heximonVersion,
+					templateName
+				});
+				report.scaffolded({
+					projectName,
+					selection,
+					heximonVersion,
+					result
+				});
+				log.success(`Scaffolded ${result.templateName} into ${result.projectDirectory}.`);
+				if (args.git && !args.workspace) {
+					const initialized = await CreateDefaults.initializeGit(result.projectDirectory);
+					report.gitInitialized = initialized;
+					log.info(initialized ? "Initialized a git repository." : "Skipped git init (already inside a repository, or git is unavailable).");
+				}
+				let installNow = args.install;
+				if (installNow === void 0 && interactive) {
+					commandOutput.assertCanPrompt("--install", `Install dependencies with ${packageManager}?`);
+					const answer = await confirm({ message: `Install dependencies with ${packageManager}?` });
+					if (typeof answer === "symbol") {
+						cancel("Cancelled after scaffolding — the project directory was kept.");
+						process.exitCode = 1;
+						return;
+					}
+					installNow = answer;
+				}
+				if (installNow === true || installNow === void 0 && args.yes) {
+					const registryReport = args.workspace || args["skip-registry-check"] ? void 0 : await new RegistryAccess().probe();
+					report.registryAccess = registryReport;
+					if (registryReport === void 0 || registryReport.status === RegistryAccessStatus.Ok) {
+						log.info(`Installing dependencies with ${packageManager}…`);
+						await CreateReport.install(packageManager, result.projectDirectory, { stdoutToStderr: commandOutput.isJson() });
+						log.success("Dependencies installed.");
+						report.dependenciesInstalled = true;
+					} else {
+						const instructions = RegistryAccess.fixInstructions(registryReport.status);
+						log.error(instructions);
+						report.addRegistryFailure(instructions);
+						process.exitCode = 1;
+					}
+				}
+				if (args.skills) try {
+					const installed = await new SkillInstaller().install(result.projectDirectory);
+					await SkillSources.record(result.projectDirectory, SkillInstaller.defaultSourceUrl);
+					report.addSkills(installed);
+					log.success(`Installed the ${installed.map((skill) => skill.name).join(", ")} agent skill into .agents/skills (.claude/skills symlinked), recorded in package.json.`);
+				} catch (error) {
+					report.addSkillsUnavailable(error);
+					log.info(`Could not fetch the agent skill — install it later with: npx skills add ${SkillInstaller.defaultSourceUrl}`);
+				}
+				const changeDirectory = relative(process.cwd(), result.projectDirectory);
+				const steps = [
+					`cd ${changeDirectory === "" ? "." : changeDirectory}`,
+					...report.dependenciesInstalled ? [] : [`${packageManager} install`],
+					`${packageManager} run dev`
+				];
+				report.nextSteps = steps;
+				outro(`Done. Next steps:\n\n  ${steps.join("\n  ")}\n\nThen: curl http://localhost:3000`);
+				commandOutput.emit(report.toDocument());
+			} catch (error) {
+				cancel(error instanceof Error ? error.message : String(error));
+				process.exitCode = 1;
+				if (!commandOutput.isJson()) return;
+				if (!report.isScaffolded()) throw new CommandFailure(CreateReport.diagnosticsOf(error, false));
+				report.addDiagnostics(CreateReport.diagnosticsOf(error, true));
+				commandOutput.emit(report.toDocument());
+			}
+		});
+	}
+});
+/**
+* The `create` command's defaults + environment glue: package-manager detection, the CLI's own lockstep
+* version, the starters giget refs (version branch → main fallback), git init, and the install spawn.
+*/
+var CreateDefaults = class CreateDefaults {
+	/** The default project (directory + package) name when none is given. */
+	static projectName = "my-heximon-app";
+	/** The GitHub repository the published templates are fetched from. */
+	static startersRepository = "heximon/starters";
+	/**
+	* The CLI's own version — the framework version, since `heximon` releases in the lockstep group. It is
+	* what `@heximon/*` ranges are stamped to.
+	*
+	* @returns The version from this package's own manifest.
+	*/
+	static cliVersion() {
+		return createRequire(import.meta.url)("../package.json").version;
+	}
+	/**
+	* Detect the invoking package manager from `npm_config_user_agent` (the create-vite trick).
+	*
+	* @param override - An explicit `--pm` value, which wins when given.
+	* @returns One of npm/pnpm/yarn/bun.
+	*/
+	static resolvePackageManager(override) {
+		if (override !== void 0 && [
+			"npm",
+			"pnpm",
+			"yarn",
+			"bun"
+		].includes(override)) return override;
+		const userAgent = process.env["npm_config_user_agent"] ?? "";
+		for (const manager of [
+			"pnpm",
+			"yarn",
+			"bun"
+		]) if (userAgent.startsWith(`${manager}/`)) return manager;
+		return "npm";
+	}
+	/**
+	* Resolve the template + validator axes from flags, prompts, or defaults.
+	*
+	* @param template - The `--template` flag value, if any.
+	* @param validator - The `--validator` flag value, if any.
+	* @param options - Whether prompting is allowed.
+	* @returns The resolved selection, or `undefined` when the user cancelled a prompt.
+	* @throws CommandFailure when a flag names an unknown template or validator.
+	*/
+	static async resolveSelection(template, validator, options) {
+		let resolvedTemplate = CreateDefaults.narrow(template, ["minimal", "database"]);
+		let resolvedValidator = CreateDefaults.narrow(validator, [
+			"zod",
+			"valibot",
+			"none"
+		]);
+		if (template !== void 0 && resolvedTemplate === void 0) throw new CommandFailure([CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, `Unknown template "${template}" — expected minimal or database.`, { option: "--template" })]);
+		if (validator !== void 0 && resolvedValidator === void 0) throw new CommandFailure([CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, `Unknown validator "${validator}" — expected zod, valibot, or none.`, { option: "--validator" })]);
+		if (resolvedTemplate === void 0) {
+			if (options.interactive) {
+				const answer = await select({
+					message: "Template",
+					options: [{
+						value: "minimal",
+						label: "minimal — the smallest real app"
+					}, {
+						value: "database",
+						label: "database — CRUD over Drizzle + libsql/SQLite"
+					}]
+				});
+				if (typeof answer === "symbol") return;
+				resolvedTemplate = answer;
+			} else resolvedTemplate = "minimal";
+		}
+		if (resolvedValidator === void 0) {
+			if (options.interactive) {
+				const answer = await select({
+					message: "Request-body validator",
+					options: [
+						{
+							value: "zod",
+							label: "zod (the docs default)"
+						},
+						{
+							value: "valibot",
+							label: "valibot"
+						},
+						{
+							value: "none",
+							label: "none — hand-checked bodies"
+						}
+					]
+				});
+				if (typeof answer === "symbol") return;
+				resolvedValidator = answer;
+			} else resolvedValidator = "zod";
+		}
+		return {
+			template: resolvedTemplate,
+			validator: resolvedValidator
+		};
+	}
+	/**
+	* Scaffold from the published starters repository: try the CLI's `v<major.minor>` branch first (the
+	* templates matching this CLI's framework minor), falling back to `main`.
+	*
+	* The target is accepted before the first attempt, so a refusal (bad name, escaping path, existing
+	* content) never reaches the retry — the cleanup below discards only what this call itself created.
+	*/
+	static async scaffoldFromStarters(scaffolder, request) {
+		const [major = "0", minor = "0"] = CreateDefaults.cliVersion().split(".");
+		const base = `gh:${CreateDefaults.startersRepository}/${request.templateName}`;
+		const target = await ProjectScaffolder.prepareTarget(request.parentDirectory, request.projectName);
+		try {
+			return await CreateDefaults.attemptScaffold(scaffolder, request, `${base}#v${major}.${minor}`);
+		} catch (error) {
+			await ProjectScaffolder.discardPreparedTarget(target);
+			if (!(error instanceof TemplateDownloadError)) throw error;
+		}
+		try {
+			return await CreateDefaults.attemptScaffold(scaffolder, request, `${base}#main`);
+		} catch (error) {
+			await ProjectScaffolder.discardPreparedTarget(target);
+			throw error;
+		}
+	}
+	/**
+	* `git init` the project directory, unless it already sits inside a work tree (or git is unavailable).
+	*
+	* @returns Whether a repository was initialized.
+	*/
+	static async initializeGit(projectDirectory) {
+		if (await CreateDefaults.run("git", ["rev-parse", "--is-inside-work-tree"], {
+			cwd: projectDirectory,
+			output: ChildOutput.Ignore
+		}) === 0) return false;
+		return await CreateDefaults.run("git", ["init"], {
+			cwd: projectDirectory,
+			output: ChildOutput.Ignore
+		}) === 0;
+	}
+	/**
+	* Run `<pm> install` in the project directory with inherited stdio (the user sees the real output).
+	*
+	* @param packageManager - The package manager binary.
+	* @param projectDirectory - The directory to install in.
+	* @param options - `stdoutToStderr` sends the child's stdout to stderr and gives it no stdin, for `--json`.
+	*/
+	static async runInstall(packageManager, projectDirectory, options = {}) {
+		const exitCode = await CreateDefaults.run(packageManager, ["install"], {
+			cwd: projectDirectory,
+			output: options.stdoutToStderr === true ? ChildOutput.Stderr : ChildOutput.Inherit
+		});
+		if (exitCode !== 0) throw new Error(`${packageManager} install failed (exit ${exitCode}) — run it manually inside the project.`);
+	}
+	/** Run one starters attempt against a single giget ref. */
+	static attemptScaffold(scaffolder, request, gigetSource) {
+		return scaffolder.scaffold({
+			...request.selection,
+			projectName: request.projectName,
+			parentDirectory: request.parentDirectory,
+			heximonVersion: request.heximonVersion,
+			source: { gigetSource }
+		});
+	}
+	/** Narrow a raw flag value to one of the allowed literals, or `undefined`. */
+	static narrow(value, allowed) {
+		return allowed.includes(value) ? value : void 0;
+	}
+	/** Spawn a child process and resolve its exit code (non-zero-safe; spawn errors resolve to 1). */
+	static run(command, commandArguments, options) {
+		return new Promise((resolveExit) => {
+			const child = spawn(command, commandArguments, {
+				cwd: options.cwd,
+				stdio: options.output === ChildOutput.Stderr ? [
+					"ignore",
+					"pipe",
+					"inherit"
+				] : options.output === ChildOutput.Ignore ? "ignore" : "inherit",
+				shell: false
+			});
+			child.stdout?.on("data", (chunk) => {
+				process.stderr.write(chunk);
+			});
+			child.on("error", () => resolveExit(1));
+			child.on("close", (code) => resolveExit(code ?? 1));
+		});
+	}
+};
+/**
+* Collects what one `heximon create` run did, for its `--json` document: the scaffold facts, the git, install
+* and skill steps, and the diagnostics.
+*/
+var CreateReport = class CreateReport {
+	packageManager;
+	/** The name of the positional argument that answers the "Project name" prompt. */
+	static nameOption = "<name>";
+	/** Whether the run created a git repository. */
+	gitInitialized = false;
+	/** Whether the run installed the dependencies. */
+	dependenciesInstalled = false;
+	/** The registry check before the install, when it ran. */
+	registryAccess;
+	/** The shell commands that start the app. */
+	nextSteps = [];
+	facts;
+	skills = [];
+	diagnostics = [];
+	/**
+	* @param packageManager - The package manager of the install step.
+	*/
+	constructor(packageManager) {
+		this.packageManager = packageManager;
+	}
+	/**
+	* Fail when a `--json` run without `--yes` lacks an answer that a prompt would ask for. Every missing answer
+	* gets its own diagnostic, so one run names them all.
+	*
+	* @param answers - The parsed arguments of the run.
+	* @throws CommandFailure with one {@link CliDiagnosticCode.OptionRequired} diagnostic per missing answer.
+	*/
+	static assertAnswered(answers) {
+		const missing = [];
+		if (answers.name === void 0 || answers.name.length === 0) missing.push(CreateReport.optionRequired(CreateReport.nameOption, "Project name", `Pass the project name as the first argument, or pass --yes to use ${CreateDefaults.projectName}.`));
+		if (answers.template === void 0) missing.push(CreateReport.optionRequired("--template", "Template", "Pass --template minimal or --template database, or pass --yes to use minimal."));
+		if (answers.validator === void 0) missing.push(CreateReport.optionRequired("--validator", "Request-body validator", "Pass --validator zod, valibot or none, or pass --yes to use zod."));
+		if (answers.install === void 0) missing.push(CreateReport.optionRequired("--install", "Install dependencies?", "Pass --install or --no-install, or pass --yes to install."));
+		if (missing.length > 0) throw new CommandFailure(missing);
+	}
+	/**
+	* Run the dependency install, and turn its failure into a {@link CommandFailure} with the same message.
+	*
+	* @param packageManager - The package manager binary.
+	* @param projectDirectory - The directory to install in.
+	* @param options - Passed on to {@link CreateDefaults.runInstall}.
+	*/
+	static async install(packageManager, projectDirectory, options) {
+		try {
+			await CreateDefaults.runInstall(packageManager, projectDirectory, options);
+		} catch (error) {
+			throw CommandFailure.of(CreateDiagnosticCode.InstallFailed, error instanceof Error ? error.message : String(error), `Run ${packageManager} install in ${projectDirectory}.`);
+		}
+	}
+	/**
+	* The diagnostics of an error that stopped the run.
+	*
+	* @param error - The thrown value.
+	* @param scaffolded - Whether the project directory was complete when the error came.
+	* @returns The diagnostics of a {@link CommandFailure}, else one diagnostic for the error.
+	*/
+	static diagnosticsOf(error, scaffolded) {
+		if (error instanceof CommandFailure) return error.diagnostics;
+		const message = error instanceof Error ? error.message : String(error);
+		if (error instanceof ProjectDirectoryOccupiedError) return [CliDiagnostics.error(CreateDiagnosticCode.TargetNotEmpty, message, {
+			hint: "Pass another project name.",
+			option: CreateReport.nameOption
+		})];
+		if (error instanceof TemplateDownloadError) return [CliDiagnostics.error(CreateDiagnosticCode.TemplateDownloadFailed, message, { hint: "Check the connection to GitHub, or pass --local <starters directory>." })];
+		return [CliDiagnostics.error(scaffolded ? CliDiagnosticCode.UnexpectedError : CreateDiagnosticCode.ScaffoldFailed, message)];
+	}
+	/** Whether the project directory is complete, so the document can say what is on disk. */
+	isScaffolded() {
+		return this.facts !== void 0;
+	}
+	/** Record the finished scaffold. */
+	scaffolded(facts) {
+		this.facts = facts;
+	}
+	/** Record the installed agent skills of the default source. */
+	addSkills(installed) {
+		for (const skill of installed) this.skills.push({
+			name: skill.name,
+			source: SkillInstaller.defaultSourceUrl,
+			directory: skill.directory,
+			fileCount: skill.fileCount
+		});
+	}
+	/** Record a skill fetch that failed: a warning, because the project is complete without the skill. */
+	addSkillsUnavailable(error) {
+		this.diagnostics.push({
+			severity: DiagnosticSeverity.Warning,
+			code: CreateDiagnosticCode.SkillsUnavailable,
+			message: `Could not fetch the agent skill: ${error instanceof Error ? error.message : String(error)}`,
+			hint: `Install it later with: npx skills add ${SkillInstaller.defaultSourceUrl}`
+		});
+	}
+	/** Record a registry check that failed, from the fix instructions of {@link RegistryAccess}. */
+	addRegistryFailure(instructions) {
+		const [message = instructions, ...hintLines] = instructions.split("\n");
+		this.diagnostics.push(CliDiagnostics.error(CreateDiagnosticCode.RegistryAccessFailed, message, hintLines.length === 0 ? {} : { hint: hintLines.join("\n") }));
+	}
+	/** Record the diagnostics of an error that stopped the run after the scaffold. */
+	addDiagnostics(diagnostics) {
+		this.diagnostics.push(...diagnostics);
+	}
+	/**
+	* The document of the run. `ok` is `false` when any diagnostic is an error.
+	*
+	* @throws Error before {@link scaffolded}: a run without a project has no full document.
+	*/
+	toDocument() {
+		if (this.facts === void 0) throw new Error("heximon create has no project to report.");
+		const { projectName, selection, heximonVersion, result } = this.facts;
+		return {
+			ok: !this.diagnostics.some((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error),
+			diagnostics: [...this.diagnostics],
+			projectName,
+			rootDir: result.projectDirectory,
+			template: selection.template,
+			validator: selection.validator,
+			templateName: result.templateName,
+			templateSource: result.source,
+			heximonVersion,
+			packageManager: this.packageManager,
+			gitInitialized: this.gitInitialized,
+			dependenciesInstalled: this.dependenciesInstalled,
+			...this.registryAccess === void 0 ? {} : { registryAccess: this.registryAccess },
+			skills: [...this.skills],
+			nextSteps: this.nextSteps
+		};
+	}
+	/** One {@link CliDiagnosticCode.OptionRequired} diagnostic, worded as {@link PromptRefusedError} words it. */
+	static optionRequired(option, question, hint) {
+		return CliDiagnostics.error(CliDiagnosticCode.OptionRequired, `The command needs an answer to "${question}", and it never prompts under --json.`, {
+			hint,
+			option
+		});
+	}
+};
+//#endregion
+//#region src/project-root.ts
+/**
+* The project root of a command: its `--cwd` option, resolved and checked. A command reads and writes the
+* project only after {@link ProjectRoot.resolve} accepts the root, so no step creates a mistyped directory.
+*/
+var ProjectRoot = class ProjectRoot {
+	/** The option the diagnostics name. */
+	static option = "--cwd";
+	/** The fix every refusal suggests. */
+	static hint = "Pass --cwd the path of an existing project directory, or leave it out to use the current directory.";
+	/**
+	* Resolve `--cwd` against the current directory, and refuse a path that is not an existing directory.
+	*
+	* @param cwdOption - The raw `--cwd` argument; a missing value means the current directory.
+	* @returns The absolute project root.
+	* @throws CommandFailure with one {@link CliDiagnosticCode.InvalidOptions} diagnostic for `--cwd` when the
+	*   path does not exist, is not a directory, or cannot be read.
+	*/
+	static resolve(cwdOption) {
+		const rootDir = resolve(process.cwd(), typeof cwdOption === "string" ? cwdOption : ".");
+		let stats;
+		try {
+			stats = statSync(rootDir, { throwIfNoEntry: false });
+		} catch (error) {
+			if (ProjectRoot.errorCodeOf(error) !== "ENOTDIR") throw ProjectRoot.refusal(`The --cwd project root ${rootDir} cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (stats === void 0) throw ProjectRoot.refusal(`The --cwd project root ${rootDir} does not exist.`);
+		if (!stats.isDirectory()) throw ProjectRoot.refusal(`The --cwd project root ${rootDir} is not a directory.`);
+		return rootDir;
+	}
+	/**
+	* Check the root in a process that hands the run to a child process. A refused root is reported here, through
+	* the output owner and no `--out` file, so no child starts and no startup failure can write under the root.
+	*
+	* @param cwdOption - The raw `--cwd` argument.
+	* @param commandOutput - The output owner of the run.
+	* @returns Whether the root was accepted; when not, the failure is printed and the exit status is 1.
+	*/
+	static async checkBeforeRelaunch(cwdOption, commandOutput) {
+		try {
+			ProjectRoot.resolve(cwdOption);
+			return true;
+		} catch (error) {
+			if (!(error instanceof CommandFailure)) throw error;
+			await commandOutput.run(() => Promise.reject(error));
+			return false;
+		}
+	}
+	/** The failure of one refused root. */
+	static refusal(message) {
+		return new CommandFailure([CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, message, {
+			hint: ProjectRoot.hint,
+			option: ProjectRoot.option
+		})]);
+	}
+	/** The `code` of a Node system error, when it has one. */
+	static errorCodeOf(error) {
+		return typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+	}
+};
+//#endregion
+//#region src/skills-json-document.ts
+/** The codes of the failures `heximon skills` raises in a `--json` document. */
+const SkillsDiagnosticCode = {
+	/** A source could not be installed: its index or one of its files did not download. */
+	InstallFailed: "skills.install-failed",
+	/** The project's `package.json` is missing, or is not a JSON object. */
+	ManifestUnreadable: "skills.manifest-unreadable"
+};
+/** What `heximon skills add` did with the `heximon.skills` list in `package.json`. */
+const SkillSourceRecording = {
+	/** The source was not in the list, and the run added it. */
+	Added: "added",
+	/** The source was in the list already; the run installed it again. */
+	AlreadyRecorded: "already-recorded",
+	/** The install failed, so the run did not record the source. */
+	NotRecorded: "not-recorded"
+};
+//#endregion
+//#region src/skills-command.ts
+/** The shared behavior behind `heximon skills add` and `heximon skills sync`. */
+var SkillsRunner = class SkillsRunner {
+	/** The arguments every `skills` subcommand takes. */
+	static baseArgs = {
+		cwd: {
+			type: "string",
+			description: "Project root directory.",
+			default: "."
+		},
+		json: CommandOutput.jsonFlag
+	};
+	/**
+	* Install one source into `projectDirectory`, logging what landed.
+	*
+	* @returns The outcome; a failure is logged and returned, never thrown, so `sync` over several sources
+	*   still attempts the rest.
+	*/
+	static async install(projectDirectory, sourceUrl) {
+		try {
+			const installed = await new SkillInstaller(sourceUrl).install(projectDirectory);
+			log.success(`${sourceUrl} → ${SkillsRunner.describe(installed)} in .agents/skills`);
+			return {
+				source: sourceUrl,
+				skills: installed
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			log.error(`${sourceUrl} — ${message}`);
+			return {
+				source: sourceUrl,
+				skills: [],
+				error: message
+			};
+		}
+	}
+	/** The `--json` entries of one install's skills. */
+	static entriesOf(install) {
+		return install.skills.map((skill) => ({
+			name: skill.name,
+			source: install.source,
+			directory: skill.directory,
+			fileCount: skill.fileCount
+		}));
+	}
+	/** The `skills add` document of a run that recorded nothing. */
+	static notRecorded(projectDirectory, sourceUrl, diagnostic) {
+		return {
+			ok: false,
+			diagnostics: [diagnostic],
+			rootDir: projectDirectory,
+			source: sourceUrl,
+			recording: SkillSourceRecording.NotRecorded,
+			skills: []
+		};
+	}
+	/** The `skills sync` document of the installs of every recorded source, in list order. */
+	static syncDocument(projectDirectory, installs) {
+		const diagnostics = installs.flatMap((install) => SkillsRunner.diagnosticOf(install) ?? []);
+		return {
+			ok: diagnostics.length === 0,
+			diagnostics,
+			rootDir: projectDirectory,
+			sources: installs.map((install) => ({
+				source: install.source,
+				installed: install.error === void 0
+			})),
+			skills: installs.flatMap((install) => SkillsRunner.entriesOf(install))
+		};
+	}
+	/** The diagnostic of a failed install, or `undefined` when it succeeded. */
+	static diagnosticOf(install) {
+		if (install.error === void 0) return;
+		return CliDiagnostics.error(SkillsDiagnosticCode.InstallFailed, `${install.source} — ${install.error}`, { hint: "Check that the site serves /.well-known/skills/index.json, then run the command again." });
+	}
+	/**
+	* Run one `package.json` read or write, and turn a failure into a {@link CommandFailure}.
+	*
+	* @param projectDirectory - The project root, named in the hint.
+	* @param work - The read or write of {@link SkillSources}.
+	* @returns What `work` returned.
+	*/
+	static async manifest(projectDirectory, work) {
+		try {
+			return await work();
+		} catch (error) {
+			throw CommandFailure.of(SkillsDiagnosticCode.ManifestUnreadable, error instanceof Error ? error.message : String(error), `Run the command in a project root with a valid package.json (now ${projectDirectory}), or pass --cwd.`);
+		}
+	}
+	/** One install's skills, as `name (n files)` entries. */
+	static describe(installed) {
+		return installed.map((skill) => `${skill.name} (${skill.fileCount.toString()} files)`).join(", ");
+	}
+};
+const addCommand = defineCommand({
+	meta: {
+		name: "add",
+		description: "Record an agent-skill source in package.json and install it into .agents/skills."
+	},
+	args: {
+		...SkillsRunner.baseArgs,
+		url: {
+			type: "positional",
+			description: `The site publishing the skills (default ${SkillInstaller.defaultSourceUrl}).`,
+			required: false
+		}
+	},
+	async run({ args }) {
+		const commandOutput = CommandOutput.resolve("skills add", args);
+		await commandOutput.run(async () => {
+			const projectDirectory = ProjectRoot.resolve(args.cwd);
+			const requested = args.url ?? SkillInstaller.defaultSourceUrl;
+			const sourceUrl = SkillSources.normalize(requested);
+			intro("heximon skills add");
+			if (!SkillSources.isInstallable(sourceUrl)) {
+				const message = `'${requested}' is not an absolute http(s) URL — pass the site publishing the skills.`;
+				process.exitCode = 1;
+				outro(message);
+				commandOutput.emit(SkillsRunner.notRecorded(projectDirectory, sourceUrl, CliDiagnostics.error(CliDiagnosticCode.InvalidOptions, message, {
+					hint: "Pass an absolute http(s) URL, for example https://heximon.dev.",
+					option: "<url>"
+				})));
+				return;
+			}
+			const install = await SkillsRunner.install(projectDirectory, sourceUrl);
+			const failure = SkillsRunner.diagnosticOf(install);
+			if (failure !== void 0) {
+				process.exitCode = 1;
+				outro("Nothing was installed, so nothing was recorded.");
+				commandOutput.emit(SkillsRunner.notRecorded(projectDirectory, sourceUrl, failure));
+				return;
+			}
+			const added = await SkillsRunner.manifest(projectDirectory, () => SkillSources.record(projectDirectory, sourceUrl));
+			const document = {
+				ok: true,
+				diagnostics: [],
+				rootDir: projectDirectory,
+				source: sourceUrl,
+				recording: added ? SkillSourceRecording.Added : SkillSourceRecording.AlreadyRecorded,
+				skills: SkillsRunner.entriesOf(install)
+			};
+			outro(added ? `Recorded ${sourceUrl} in package.json (heximon.skills). Re-install it any time with \`heximon skills sync\`.` : `${sourceUrl} was already recorded — the install refreshed it.`);
+			commandOutput.emit(document);
+		});
+	}
+});
+const syncCommand = defineCommand({
+	meta: {
+		name: "sync",
+		description: "Re-install every agent-skill source package.json records."
+	},
+	args: SkillsRunner.baseArgs,
+	async run({ args }) {
+		const commandOutput = CommandOutput.resolve("skills sync", args);
+		await commandOutput.run(async () => {
+			const projectDirectory = ProjectRoot.resolve(args.cwd);
+			intro("heximon skills sync");
+			const sources = await SkillsRunner.manifest(projectDirectory, () => SkillSources.read(projectDirectory));
+			if (sources.length === 0) {
+				outro("No skill sources recorded in package.json (heximon.skills) — add one with `heximon skills add <url>`.");
+				commandOutput.emit(SkillsRunner.syncDocument(projectDirectory, []));
+				return;
+			}
+			const installs = [];
+			for (const sourceUrl of sources) installs.push(await SkillsRunner.install(projectDirectory, sourceUrl));
+			const document = SkillsRunner.syncDocument(projectDirectory, installs);
+			if (!document.ok) {
+				process.exitCode = 1;
+				outro(`${document.diagnostics.length.toString()} of ${sources.length.toString()} source(s) failed — see above.`);
+				commandOutput.emit(document);
+				return;
+			}
+			outro(`${sources.length.toString()} source(s) re-installed into .agents/skills.`);
+			commandOutput.emit(document);
+		});
+	}
+});
+/**
+* The `heximon skills` command — install the published agent skills into a project and keep the list of
+* sources in `package.json` (`heximon.skills`), so a second machine or a fresh clone reproduces the same
+* install with one verb instead of a remembered URL.
+*
+* `heximon create` already installs the default source and records it, so an existing project's first use of
+* this command is usually `sync` after a clone, or `add` for a second, private skill site.
+*/
+const skillsCommand = defineCommand({
+	meta: {
+		name: "skills",
+		description: "Install and re-install the agent skills a project records in its package.json."
+	},
+	subCommands: {
+		add: addCommand,
+		sync: syncCommand
+	}
+});
+//#endregion
+export { StdoutRedirect as _, SkillSources as a, ClackPrompter as b, ProjectScaffolder as c, RegistryAccessStatus as d, CommandOutput as f, CliEntry as g, CliEnvironment as h, createCommand as i, TemplateDownloadError as l, PromptRefusedError as m, ProjectRoot as n, SkillInstaller as o, CommandFailure as p, CreateDefaults as r, ProjectDirectoryOccupiedError as s, skillsCommand as t, RegistryAccess as u, CliDiagnosticCode as v, PromptCancelledError as x, CliDiagnostics as y };