@theholocron/cli 5.0.0-alpha.11 → 5.0.0-alpha.111

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import path, { basename, dirname, join, relative, resolve } from "node:path";
+import path, { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { checkbox, input, select } from "@inquirer/prompts";
-import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
+import { KNOWN_WORKFLOWS, createAstromech, deployOnRelease, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -24,6 +24,8 @@ import { createGitHubClient } from "@theholocron/github-client";
 import { PostHogSink } from "@theholocron/observability/analytics";
 import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
 import { SentrySink } from "@theholocron/observability/errors";
+import load from "@commitlint/load";
+import lint from "@commitlint/lint";
 import { promisify } from "node:util";
 import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
 import search from "@inquirer/search";
@@ -295,7 +297,8 @@ function resolveConfig(raw) {
 		docs,
 		env: raw.env,
 		log: raw.log,
-		telemetry: raw.telemetry
+		telemetry: raw.telemetry,
+		eslint: raw.eslint
 	};
 }
 //#endregion
@@ -532,7 +535,8 @@ var PluginLoader = class {
 /** Default importer — resolves from cwd first so the global CLI finds project plugins. */
 const defaultImporter$1 = async (pkg) => {
 	try {
-		return import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
+		const resolved = createRequire(process.cwd() + "/").resolve(pkg);
+		return import(pathToFileURL(resolved).href);
 	} catch {
 		return import(pkg);
 	}
@@ -664,7 +668,8 @@ const style = {
 */
 const defaultImporter = async (pkg) => {
 	try {
-		return await import(pathToFileURL(createRequire(process.cwd() + "/").resolve(pkg)).href);
+		const resolved = createRequire(process.cwd() + "/").resolve(pkg);
+		return await import(pathToFileURL(resolved).href);
 	} catch {
 		return await import(pkg);
 	}
@@ -1106,8 +1111,10 @@ async function runClone(input) {
 		}).status };
 	});
 	print(style.header(`Holocron clone — org=${input.org} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
-	if (!existsSync(targetDir)) if (dryRun) print(style.dim(`  would create ${targetDir}`));
-	else mkdirSync(targetDir, { recursive: true });
+	if (!existsSync(targetDir)) {
+		if (dryRun) print(style.dim(`  would create ${targetDir}`));
+		else mkdirSync(targetDir, { recursive: true });
+	}
 	let repos;
 	try {
 		repos = await listOrgRepos(input.org, input.token, fetchFn);
@@ -1129,7 +1136,8 @@ async function runClone(input) {
 	let skipped = 0;
 	let failed = 0;
 	for (const repo of repos) {
-		const dest = join(targetDir, repo.name.startsWith(".") ? repo.name.slice(1) : repo.name);
+		const dirName = repo.name.startsWith(".") ? repo.name.slice(1) : repo.name;
+		const dest = join(targetDir, dirName);
 		if (existsSync(dest)) {
 			print(style.dim(`  skip   ${repo.full_name}`));
 			skipped++;
@@ -1214,8 +1222,10 @@ const COMMAND_CONTEXTS = {
 	"skills install": "global",
 	"skills remove": "global",
 	"skills update": "global",
+	"lint commit-msg": "global",
 	run: "repo-aware",
 	ci: "repo-aware",
+	"deploy-on-release": "repo-aware",
 	"config show": "repo-aware",
 	"sync-readme": "repo-aware",
 	doctor: "workspace",
@@ -1233,6 +1243,80 @@ function commandsInContext(context) {
 }
 //#endregion
 //#region src/commands/deploy.ts
+/**
+* `holocron deploy` — trigger a deployment via the configured
+* `deployment` capability.
+*
+* Two modes, one command: `runDeploy` (the default — a Git branch,
+* `triggerDeployment()`) and `runDeployFromFiles` (`--files <dir>` —
+* a local directory of source files, `deployFunction()`, no linked
+* repo required — for a consumer with no Git history to deploy from,
+* e.g. Sentinel, shipped as an npm package). Separate functions, not
+* one branching `runDeploy`, because their inputs genuinely differ
+* (`branch` vs `dir`) and their result shapes differ too
+* (`DeploymentRecord` carries `status`/`branch`; `DeployFunctionResult`
+* is deliberately minimal, same as `DeployScriptResult` for Workers).
+*
+* Errors clearly when `deployment` isn't loaded (no provider declared
+* in `holocron.config.json`), or when the configured provider doesn't
+* implement `deployFunction` (it's optional on `Deployment` — not
+* every provider has a files-based deploy API).
+*
+* Dry-run skips the actual deploy call but still verifies the
+* deployment capability (and, for `--files`, `deployFunction`) is
+* present, so operators can sanity-check the wiring without spinning
+* up a build.
+*
+* **Both modes wait for the deployment to finish** (holocron#911): a
+* provider accepting the upload/trigger is not the deployment succeeding.
+* Vercel builds asynchronously — an `npm install` failure there leaves
+* the deployment in `ERROR` while production keeps serving the previous
+* one, and this command used to report `ok` regardless (found live:
+* Sentinel's holocron#910 deploy "succeeded" in CI, never went live). So
+* after triggering, {@link waitForDeployment} polls
+* `Deployment.getDeployment()` until a terminal state; only `ready` is
+* `ok`, while `error` / `cancelled` / a timeout are `fail` (non-zero exit
+* via `cli.ts`).
+*/
+const DEFAULT_WAIT_TIMEOUT_MS = 6e5;
+const DEFAULT_WAIT_INTERVAL_MS = 5e3;
+const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+	"ready",
+	"error",
+	"cancelled"
+]);
+/**
+* Polls `getDeployment(id)` until the deployment reaches a terminal status
+* (`ready` / `error` / `cancelled`). Throws on timeout — the caller turns
+* that into a `fail` report, same as a provider throwing mid-trigger.
+*/
+async function waitForDeployment(deploy, deploymentId, options = {}) {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+	const intervalMs = options.intervalMs ?? DEFAULT_WAIT_INTERVAL_MS;
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const now = options.now ?? Date.now;
+	const deadline = now() + timeoutMs;
+	for (;;) {
+		const record = await deploy.getDeployment(deploymentId);
+		if (TERMINAL_STATUSES.has(record.status)) return record;
+		if (now() >= deadline) throw new Error(`deployment ${deploymentId} still ${record.status} after ${Math.round(timeoutMs / 1e3)}s — check the provider's dashboard`);
+		await sleep(intervalMs);
+	}
+}
+/** One terminal, non-ready record as a single human-readable failure line. */
+function terminalFailure(record) {
+	return `deployment ${record.id} ended ${record.status}${record.errorMessage ? `: ${record.errorMessage}` : ""}`;
+}
+/**
+* Provider `url` fields (Vercel's REST API, at least) come back as bare
+* hostnames — `"my-app.vercel.app"`, no scheme — which terminals don't
+* linkify and browsers won't navigate to unmodified. Printed output
+* should be a URL a human can click/paste; structured log fields keep
+* the raw provider value as-is.
+*/
+function withScheme(url) {
+	return /^https?:\/\//.test(url) ? url : `https://${url}`;
+}
 async function runDeploy(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1259,17 +1343,37 @@ async function runDeploy(input) {
 		};
 	}
 	try {
-		const record = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
+		const triggered = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
 			projectId: input.projectId,
 			branch: input.branch,
 			...input.target ? { target: input.target } : {}
 		}));
-		print(`  ${style.success(`${record.status} — ${record.url}`)}`);
+		logger.info({
+			status: triggered.status,
+			url: triggered.url,
+			id: triggered.id
+		}, "deploy: triggered");
+		const record = TERMINAL_STATUSES.has(triggered.status) ? triggered : await withSpinner(`Waiting for ${withScheme(triggered.url)} to finish…`, () => waitForDeployment(deploy, triggered.id, input.wait));
+		if (record.status !== "ready") {
+			const message = terminalFailure(record);
+			print(`  ${style.fail(`${message} — ${withScheme(triggered.url)}`)}`);
+			logger.warn({
+				id: record.id,
+				status: record.status,
+				reason: record.errorMessage
+			}, "deploy: failed");
+			return {
+				deployment: record,
+				status: "fail",
+				message
+			};
+		}
+		print(`  ${style.success(`${record.status} — ${withScheme(triggered.url)}`)}`);
 		logger.info({
 			status: record.status,
-			url: record.url,
+			url: triggered.url,
 			id: record.id
-		}, "deploy: triggered");
+		}, "deploy: ready");
 		return {
 			deployment: record,
 			status: "ok"
@@ -1288,6 +1392,106 @@ async function runDeploy(input) {
 		};
 	}
 }
+const SKIP_DIRS$2 = /* @__PURE__ */ new Set([
+	".git",
+	"node_modules",
+	".turbo"
+]);
+/** Recursively lists absolute file paths under `dir`, skipping VCS/tooling noise. */
+function defaultWalkFiles$2(dir) {
+	const results = [];
+	for (const entry of readdirSync(dir)) {
+		if (SKIP_DIRS$2.has(entry)) continue;
+		const full = join(dir, entry);
+		const stat = statSync(full);
+		if (stat.isDirectory()) results.push(...defaultWalkFiles$2(full));
+		else if (stat.isFile()) results.push(full);
+	}
+	return results;
+}
+/** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
+async function runDeployFromFiles(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "deploy");
+	const dryRun = input.context.dryRun ?? false;
+	const walkFiles = input.walkFiles ?? defaultWalkFiles$2;
+	const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const files = {};
+	for (const abs of walkFiles(input.dir)) {
+		const rel = relative(input.dir, abs).split(sep).join("/");
+		files[rel] = readFile(abs);
+	}
+	const fileCount = Object.keys(files).length;
+	logger.info({
+		dir: input.dir,
+		fileCount,
+		target: input.target ?? "preview",
+		projectId: input.projectId,
+		dryRun: dryRun || void 0
+	}, "deploy: start (files)");
+	print(style.header(`Holocron deploy — files=${input.dir} (${fileCount} file${fileCount === 1 ? "" : "s"})${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`));
+	if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
+	const deploy = loader.get("deployment");
+	if (!deploy.deployFunction) throw new Error(`deployment provider "${deploy.providerName}" does not support deploying from files — deployFunction() is not implemented`);
+	if (dryRun) {
+		const message = `would: ${deploy.providerName}.deployFunction(projectId=${input.projectId}, files=${fileCount}${input.target ? `, target=${input.target}` : ""})`;
+		print(`  ${style.dim(`… ${message}`)}`);
+		return {
+			deployment: null,
+			status: "dry-run",
+			message
+		};
+	}
+	try {
+		const result = await withSpinner(`Deploying ${fileCount} file${fileCount === 1 ? "" : "s"} from ${input.dir}…`, () => deploy.deployFunction(input.projectId, {
+			files,
+			...input.target ? { target: input.target } : {}
+		}));
+		logger.info({
+			url: result.url,
+			id: result.deploymentId
+		}, "deploy: triggered (files)");
+		const record = await withSpinner(`Waiting for ${withScheme(result.url)} to finish…`, () => waitForDeployment(deploy, result.deploymentId, input.wait));
+		if (record.status !== "ready") {
+			const message = terminalFailure(record);
+			print(`  ${style.fail(`${message} — ${withScheme(result.url)}`)}`);
+			logger.warn({
+				id: record.id,
+				status: record.status,
+				reason: record.errorMessage
+			}, "deploy: failed (files)");
+			return {
+				deployment: result,
+				status: "fail",
+				message
+			};
+		}
+		print(`  ${style.success(withScheme(result.url))}`);
+		logger.info({
+			url: result.url,
+			id: result.deploymentId
+		}, "deploy: ready (files)");
+		return {
+			deployment: result,
+			status: "ok"
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		print(`  ${style.fail(message)}`);
+		logger.warn({
+			dir: input.dir,
+			reason: message
+		}, "deploy: failed (files)");
+		return {
+			deployment: null,
+			status: "fail",
+			message
+		};
+	}
+}
 //#endregion
 //#region src/commands/doctor.ts
 async function runDoctor(input) {
@@ -1963,14 +2167,16 @@ describe("resolveToken", () => {
 	});
 
 	it("throws AuthError with a helpful message when nothing is set", () => {
-		try {
-			resolveToken({ env: {}, keyring: noKeyring });
-			throw new Error("should have thrown");
-		} catch (err) {
-			expect(err).toBeInstanceOf(AuthError);
-			expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
-			expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
-		}
+		const err = (() => {
+			try {
+				resolveToken({ env: {}, keyring: noKeyring });
+			} catch (e) {
+				return e;
+			}
+		})();
+		expect(err).toBeInstanceOf(AuthError);
+		expect((err as Error).message).toMatch(/${inputs.tokenEnv}/);
+		expect((err as Error).message).toMatch(/holocron auth set ${inputs.slug}/);
 	});
 });
 `;
@@ -2014,24 +2220,24 @@ export class ${inputs.capabilityClass} {
 //#endregion
 //#region src/commands/plugin-create/templates/capability-test.ts
 function render$14(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
-	return `import { describe, it } from "vitest";
+	const factoryName = `create${inputs.vendorName}RestClient`;
+	return `import { describe, expect, it } from "vitest";
 
 import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
-import { ${clientClass} } from "../rest.js";
+import { ${factoryName} } from "../rest.js";
 import { stubFetch } from "./helpers.js";
 
 // Stub client used by the constructor smoke test. Real capability
 // tests replace this with per-method stubs once implementations land.
 function makeCapability() {
 	const stub = stubFetch([]);
-	const rest = new ${clientClass}({ token: "t", fetch: stub.fetch });
+	const rest = ${factoryName}({ token: "t", fetch: stub.fetch });
 	return new ${inputs.capabilityClass}(() => rest);
 }
 
 describe("${inputs.capabilityClass}", () => {
 	it("constructs with a REST client", () => {
-		makeCapability();
+		expect(makeCapability().key).toBe("${inputs.capability}");
 	});
 
 	// TODO: implement one test per ${inputs.capability} capability method
@@ -2047,14 +2253,11 @@ describe("${inputs.capabilityClass}", () => {
 //#endregion
 //#region src/commands/plugin-create/templates/eslint-config.ts
 function render$13(_inputs) {
-	return `import root from "../../eslint.config.js";
+	return `import type { Linter } from "eslint";
 
-export default [
-	...root,
-	{
-		ignores: ["dist/**", "coverage/**"],
-	},
-];
+import root from "../../eslint.config.js";
+
+export default [...root, { ignores: ["dist/**", "coverage/**"] }] satisfies Linter.Config[];
 `;
 }
 //#endregion
@@ -2137,10 +2340,17 @@ describe("AUTH_HINT", () => {
 //#endregion
 //#region src/commands/plugin-create/templates/package-json.ts
 function render$10(inputs) {
+	const keywords = [
+		inputs.capability,
+		"holocron",
+		"plugin",
+		inputs.slug
+	].sort((a, b) => a.localeCompare(b));
 	return JSON.stringify({
 		name: `@theholocron/holocron-plugin-${inputs.slug}`,
 		version: "2.0.0-alpha.1",
 		description: `Holocron plugin for ${inputs.vendorName}. Implements the ${inputs.capability} capability against ${inputs.vendorName}'s REST API, plus exports verifyToken + AUTH_HINT for \`holocron auth\`.`,
+		keywords,
 		homepage: `https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme`,
 		bugs: "https://github.com/theholocron/holocron/issues",
 		repository: {
@@ -2150,9 +2360,13 @@ function render$10(inputs) {
 		},
 		license: "MIT",
 		author: "Newton Koumantzelis",
+		sideEffects: false,
 		type: "module",
-		main: "./src/index.ts",
-		exports: { ".": "./src/index.ts" },
+		exports: { ".": {
+			types: "./dist/index.d.mts",
+			import: "./dist/index.mjs",
+			default: "./dist/index.mjs"
+		} },
 		scripts: {
 			"delivery.build": "tsdown",
 			"sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
@@ -2164,33 +2378,26 @@ function render$10(inputs) {
 		peerDependencies: { "@theholocron/cli": "workspace:*" },
 		devDependencies: {
 			"@theholocron/cli": "workspace:*",
-			"@theholocron/tsconfig": "catalog:",
-			"@tsconfig/node-lts": "catalog:",
+			"@theholocron/tsconfig": "catalog:configs",
+			"@types/node": "catalog:",
 			"@vitest/coverage-v8": "catalog:",
 			eslint: "catalog:",
 			globals: "catalog:",
-			typescript: "catalog:",
-			vitest: "catalog:",
 			tsdown: "catalog:",
-			tsx: "catalog:"
-		},
-		publishConfig: {
-			access: "public",
-			main: "./dist/index.mjs",
-			types: "./dist/index.d.mts",
-			exports: { ".": {
-				types: "./dist/index.d.mts",
-				import: "./dist/index.mjs",
-				default: "./dist/index.mjs"
-			} }
+			tsx: "catalog:",
+			typescript: "catalog:",
+			vitest: "catalog:"
 		},
-		files: ["dist", "README.md"]
-	}, null, "	") + "\n";
+		engines: { node: ">=22" },
+		publishConfig: { access: "public" },
+		files: ["dist"]
+	}, null, 2) + "\n";
 }
 //#endregion
 //#region src/commands/plugin-create/templates/plugin-index.ts
 function render$9(inputs) {
 	const clientClass = `${inputs.vendorName}RestClient`;
+	const factoryName = `create${inputs.vendorName}RestClient`;
 	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
 	return `/**
  * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
@@ -2207,7 +2414,7 @@ function render$9(inputs) {
 
 import { resolveToken, type ResolveTokenInput } from "./auth.js";
 import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
-import { ${clientClass} } from "./rest.js";
+import { ${factoryName}, type ${clientClass} } from "./rest.js";
 
 export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
 	/** Override base URL for tests. */
@@ -2228,10 +2435,12 @@ export function createContext(options: ${inputs.vendorName}PluginOptions): Plugi
 		options,
 		rest: () => {
 			if (rest) return rest;
-			const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token: resolveToken(options) };
+			const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = {
+				token: resolveToken(options),
+			};
 			if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
 			if (options.fetch !== undefined) restOpts.fetch = options.fetch;
-			return (rest = new ${clientClass}(restOpts));
+			return (rest = ${factoryName}(restOpts));
 		},
 	};
 }
@@ -2265,7 +2474,7 @@ export const AUTH_HINT =
 // ── Public re-exports ────────────────────────────────────────────────
 
 export * from "./auth.js";
-export { ${clientClass} } from "./rest.js";
+export { type ${clientClass}, ${factoryName} } from "./rest.js";
 export { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
 export { verifyToken } from "./verify-token.js";
 export type { VerifyTokenResult, VerifyTokenSuccess, VerifyTokenFailure } from "./verify-token.js";
@@ -2342,15 +2551,26 @@ Not yet published; capability methods are stubs.
 //#endregion
 //#region src/commands/plugin-create/templates/rest.ts
 function render$7(inputs) {
-	return `import { createRestClient, type RequestOptions, type RestClient } from "@theholocron/cli";
+	const factoryName = `create${inputs.vendorName}RestClient`;
+	const clientType = `${inputs.vendorName}RestClient`;
+	return `import { createRestClient, type RestClient } from "@theholocron/cli";
+
+export type { RestClient };
 
-export type { RequestOptions, RestClient };
+/**
+ * TODO: narrow this to the specific ${inputs.vendorName} endpoints this
+ * plugin's capability needs (see \`@theholocron/holocron-plugin-axiom\`'s
+ * \`rest.ts\` for the pattern: an interface with one method per endpoint,
+ * built internally via \`createRestClient\`). Starts as an alias for the
+ * generic client so the scaffold compiles end to end immediately.
+ */
+export type ${clientType} = RestClient;
 
-export function ${`create${inputs.vendorName}RestClient`}(opts: {
+export function ${factoryName}(opts: {
 \ttoken: string;
 \tbaseUrl?: string;
 \tfetch?: typeof fetch;
-}): RestClient {
+}): ${clientType} {
 \treturn createRestClient({
 \t\tbaseUrl: opts.baseUrl ?? "${inputs.baseUrl}",
 \t\ttoken: opts.token,
@@ -2423,7 +2643,7 @@ describe("${factoryName}", () => {
 function render$5(inputs) {
 	return JSON.stringify({
 		display: `Holocron Plugin: ${inputs.vendorName}`,
-		extends: "@tsconfig/node-lts/tsconfig.json",
+		extends: "@theholocron/tsconfig/node-lts",
 		compilerOptions: {
 			baseUrl: "./",
 			outDir: "./dist",
@@ -2431,7 +2651,7 @@ function render$5(inputs) {
 		},
 		include: ["src/**/*.ts"],
 		exclude: ["node_modules", "dist"]
-	}, null, "	") + "\n";
+	}, null, 2) + "\n";
 }
 //#endregion
 //#region src/commands/plugin-create/templates/tsdown-config.ts
@@ -2547,6 +2767,7 @@ console.log("Done. Fill in capability method calls above before shipping.");
 // ── helpers ────────────────────────────────────────────────────────
 
 /** Wrap a capability call, print ERROR + hint on failure. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- called once a real capability check replaces the TODO example above
 async function runStep(body) {
 	try {
 		await body();
@@ -2586,7 +2807,7 @@ function hintFor(message) {
 //#endregion
 //#region src/commands/plugin-create/templates/verify-token.ts
 function render$2(inputs) {
-	const clientClass = `${inputs.vendorName}RestClient`;
+	const factoryName = `create${inputs.vendorName}RestClient`;
 	return `/**
  * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
  * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
@@ -2603,7 +2824,7 @@ function render$2(inputs) {
  * \`/me\`, \`/account\`.
  */
 
-import { ${clientClass} } from "./rest.js";
+import { ${factoryName} } from "./rest.js";
 
 export interface VerifyTokenSuccess {
 	ok: true;
@@ -2630,10 +2851,10 @@ export interface VerifyTokenOptions {
 }
 
 export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
-	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	const restOpts: { token: string; baseUrl?: string; fetch?: typeof fetch } = { token };
 	if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
 	if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
-	const rest = new ${clientClass}(restOpts);
+	const rest = ${factoryName}(restOpts);
 	try {
 		const me = await rest.request<MeResponse>("/me");
 		// Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
@@ -2659,18 +2880,14 @@ describe("verifyToken", () => {
 		const stub = stubFetch([{ status: 200, body: { email: "user@example.com" } }]);
 		const result = await verifyToken("token", { fetch: stub.fetch });
 		expect(result.ok).toBe(true);
-		if (result.ok) {
-			expect(result.subject).toMatch(/user@example.com/);
-		}
+		expect((result as { ok: boolean; subject?: string }).subject).toMatch(/user@example.com/);
 	});
 
 	it("returns ok:false with the error message on 401", async () => {
 		const stub = stubFetch([{ status: 401, body: { messages: ["Invalid token"] } }]);
 		const result = await verifyToken("bad", { fetch: stub.fetch });
 		expect(result.ok).toBe(false);
-		if (!result.ok) {
-			expect(result.message).toMatch(/→ 401/);
-		}
+		expect((result as { ok: boolean; message?: string }).message).toMatch(/→ 401/);
 	});
 
 	it("returns ok:false when the network layer throws", async () => {
@@ -2679,9 +2896,7 @@ describe("verifyToken", () => {
 		};
 		const result = await verifyToken("t", { fetch: throwing });
 		expect(result.ok).toBe(false);
-		if (!result.ok) {
-			expect(result.message).toMatch(/network down/);
-		}
+		expect((result as { ok: boolean; message?: string }).message).toMatch(/network down/);
 	});
 });
 `;
@@ -2755,7 +2970,7 @@ const TEMPLATES = [
 		render
 	},
 	{
-		path: "eslint.config.js",
+		path: "eslint.config.ts",
 		render: render$13
 	},
 	{
@@ -3696,10 +3911,13 @@ async function runSecretsSync(input) {
 	const rows = [];
 	if (loader.has("secrets")) {
 		const secrets = loader.get("secrets");
-		print(style.step("secrets (repo scope)"));
+		const scope = input.githubSecretScope ?? { kind: "repo" };
+		const allowedKeys = input.githubSecretKeys ? new Set(input.githubSecretKeys) : void 0;
+		print(style.step("secrets"));
 		for (const key of keys) {
-			rows.push(await runRow(`secrets:${secrets.providerName}`, "scope=repo", key, dryRun, async () => {
-				await secrets.setSecret({ kind: "repo" }, key, envVars[key]);
+			if (allowedKeys && !allowedKeys.has(key)) continue;
+			rows.push(await runRow(`secrets:${secrets.providerName}`, scopeLabel(scope), key, dryRun, async () => {
+				await secrets.setSecret(scope, key, envVars[key]);
 			}));
 			print(formatRow(rows[rows.length - 1]));
 		}
@@ -3791,11 +4009,114 @@ function formatRow(row) {
 	if (row.status === "dry-run") return `    ${style.dim(`… ${label}`)}`;
 	return `    ${style.dim(`· ${label}`)}`;
 }
+function scopeLabel(scope) {
+	if (scope.kind === "repo") return "scope=repo";
+	if (scope.kind === "organization") return `scope=organization,org=${scope.name}`;
+	return `scope=environment,env=${scope.name}`;
+}
 function vaultProviderName(loader) {
 	if (!loader.has("vault")) return "<missing>";
 	return loader.get("vault").providerName;
 }
 //#endregion
+//#region src/commands/setup/derived-properties.ts
+/**
+* Repo archetype, in priority order:
+* 1. `*-template` repo name → `template` (independent of package shape).
+* 2. Monorepo whose primary published artifact is a CLI (some workspace
+*    package has `bin`) → `platform` — matches `holocron` itself: the CLI is
+*    the deliverable, the plugin packages are supporting infrastructure for
+*    it, not separate products.
+* 3. Monorepo with no CLI but at least one non-private workspace package →
+*    `library` — matches `clients`/`configs`/`utils`/`themes`/
+*    `observability`: a family of published packages, none of them a CLI.
+*    Checked *before* falling into the root-package branch below, because
+*    these repos' own root `package.json` is private and often carries
+*    `@theholocron/astro-config` for a docs site built from the monorepo
+*    root — without this check they'd wrongly resolve to `docs` off that
+*    root-level signal alone, when the docs site is a secondary concern of
+*    a library collection, not what the repo fundamentally is.
+* 4. Single-package repo with `package.json#bin` → `cli`.
+* 5. Docs-only site (astro/starlight present, root package private, no
+*    publishable exports) → `docs`.
+* 6. Private, non-publishable, non-docs → `app`.
+* 7. Otherwise, a single publishable package → `library`.
+*/
+function deriveProfile(input) {
+	if (/-template$/.test(input.repoName)) return "template";
+	if (input.isMonorepo) {
+		if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
+		if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
+	}
+	const pkg = input.rootPackageJson;
+	if (pkg?.bin) return "cli";
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	const isDocsSite = Boolean(deps["@theholocron/astro-config"] || deps["astro"]);
+	if (pkg?.private && isDocsSite) return "docs";
+	if (pkg?.private) return "app";
+	return "library";
+}
+const KNOWN_STACK_DEPS = [
+	"next",
+	"vite",
+	"astro",
+	"tsdown",
+	"rollup",
+	"webpack",
+	"storybook",
+	"vitest",
+	"playwright",
+	"turbo"
+];
+/**
+* Detected build/framework tooling — the literal "does this repo need
+* next/vite/tsdown" signal `holocron.config.ts` has no field for today
+* (framework choice isn't a config concept, unlike `providers`/`tasks`).
+* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
+* frameworks show up rather than trying to detect anything on npm.
+*/
+function deriveStack(pkg) {
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	return KNOWN_STACK_DEPS.filter((name) => name in deps);
+}
+/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
+function deriveCapabilities(providers) {
+	return Object.keys(providers ?? {}).sort();
+}
+/**
+* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* touches wires — every `holocron.config.ts` in this org already satisfies
+* this, so `non-compliant` here means drift (a provider manually removed
+* after setup), not an unmet aspirational policy. Deliberately not a richer
+* per-profile policy yet (e.g. "a `library` must have `deployment`") — that's
+* a Phase B (GitHub App) refinement once it can post *why* on a check run.
+*/
+const REQUIRED_BASELINE = ["source", "ci"];
+function deriveCompliance(capabilities) {
+	return REQUIRED_BASELINE.every((key) => capabilities.includes(key)) ? "compliant" : "non-compliant";
+}
+/**
+* Reads each workspace package's actual `package.json` content (not just
+* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
+* `platform` detection needs `bin`, which that helper doesn't carry).
+* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
+* own soft-fail behavior.
+*/
+async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
+	const results = [];
+	for (const { slug, dir = "packages" } of workspacePackages) try {
+		const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
+		results.push(JSON.parse(raw));
+	} catch {}
+	return results;
+}
+//#endregion
 //#region src/commands/setup/labels.ts
 const CANONICAL_LABELS = [
 	{
@@ -3935,6 +4256,9 @@ var alexignore_default = ".github/*\nCHANGELOG.md\nLICENSE\n";
 //#region src/templates/configs/alexjs/alexrc.json
 var alexrc_default = { allow: [
 	"dead",
+	"execute",
+	"execution",
+	"executes",
 	"failure",
 	"failures",
 	"hook",
@@ -3953,12 +4277,21 @@ function createIgnoreConfig$1() {
 }
 //#endregion
 //#region src/templates/configs/commit-msg/commit-msg
-var commit_msg_default = "# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to commitlint's own auto-discovery of a local commitlint.config.ts when\n# the shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nCOMMITLINT_CONFIG=\"node_modules/@theholocron/commitlint-config/dist/index.js\"\nif [ -f \"$COMMITLINT_CONFIG\" ]; then\n	npx --no -- commitlint --config \"$COMMITLINT_CONFIG\" --edit \"$1\"\nelse\n	npx --no -- commitlint --edit \"$1\"\nfi\n";
+var commit_msg_default = "__HOLOCRON_SCRIPT__ lint commit-msg \"$1\"\n";
 //#endregion
 //#region src/templates/configs/commit-msg/create-config.ts
 const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cli/src/templates/configs/commit-msg/create-config.ts" });
-function createConfig$7() {
-	return `${workflowHeader$8("shebang")}${commit_msg_default}`;
+/**
+* `.husky/commit-msg` — lints the commit message via `holocron lint
+* commit-msg` (holocron#789), the real programmatic replacement for
+* shelling out to `commitlint --edit`. Installed by `holocron setup` when
+* hooks are enabled. Same `__HOLOCRON_SCRIPT__` substitution as `pre-push`.
+*
+* @param holocronScript - the command that invokes the CLI. Defaults to
+*   `pnpm exec holocron`; the source repo passes `node packages/cli/dist/cli.mjs`.
+*/
+function createConfig$7(holocronScript = "pnpm exec holocron") {
+	return `${workflowHeader$8("shebang")}${commit_msg_default.replace("__HOLOCRON_SCRIPT__", holocronScript)}`;
 }
 //#endregion
 //#region src/templates/configs/devmoji/create-config.ts
@@ -3974,7 +4307,7 @@ function createConfig$6() {
 }
 //#endregion
 //#region src/templates/configs/editorconfig/editorconfig
-var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
+var editorconfig_default = "root = true\n\n[*]\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nindent_style = tab\nindent_size = 4\n\n[.gitattributes]\nindent_style = space\nindent_size = 2\n\n[*.{json,yml,yaml}]\nindent_style = space\nindent_size = 2\n\n[*.{md,mdx}]\ntrim_trailing_whitespace = false\nindent_style = unset\n\n[.*{rc,ignore}]\nindent_style = space\nindent_size = 2\n";
 //#endregion
 //#region src/templates/configs/editorconfig/create-config.ts
 const { workflowHeader: workflowHeader$6 } = createHeader({ source: "packages/cli/src/templates/configs/editorconfig/create-config.ts" });
@@ -4954,7 +5287,10 @@ async function runSetup(input) {
 		print(formatStep(steps[steps.length - 1]));
 		if (effectivePreset && effectivePreset !== "none") {
 			steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
-				await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
+				await source.updateRepoSettings({
+					...BALANCED_REPO_SETTINGS,
+					...repo?.defaultBranch ? { default_branch: repo.defaultBranch } : {}
+				});
 			}));
 			print(formatStep(steps[steps.length - 1]));
 			const tasksConfig = { tasks: config.tasks };
@@ -5061,7 +5397,7 @@ async function runSetup(input) {
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		steps.push(await runStep("source", "write .husky/commit-msg", dryRun, async () => {
-			await source.writeRepoFile(".husky/commit-msg", createConfig$7());
+			await source.writeRepoFile(".husky/commit-msg", createConfig$7(config.holocronScript));
 		}));
 		print(formatStep(steps[steps.length - 1]));
 		if (hooksEnabled) {
@@ -5135,13 +5471,20 @@ async function runSetup(input) {
 					await source.writeRepoFile("turbo.json", content);
 				}));
 				print(formatStep(steps[steps.length - 1]));
-				const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
 				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
-				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const rootScripts = rootPkg?.scripts ?? {};
 				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
 				if (workspaceFix.changed) steps.push(await runStep("source", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
 					await source.writeRepoFile("pnpm-workspace.yaml", workspaceFix.content);
 				}));
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) steps.push(await runStep("source", "add turbo devDependency", dryRun, async () => {
+						await source.writeRepoFile("package.json", depFix.content);
+					}));
+				}
 			}
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5152,7 +5495,7 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		const properties = {};
-		if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
+		if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
 		const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
 		properties["monorepo"] = String(isMonorepo);
 		const manual = repo?.properties ?? {};
@@ -5160,6 +5503,21 @@ async function runSetup(input) {
 		if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
 		if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
 		if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+		{
+			const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+			const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+			const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+			properties["holocron_profile"] = deriveProfile({
+				rootPackageJson,
+				repoName: basename(input.context.repoRoot),
+				isMonorepo,
+				workspacePackageJsons
+			});
+			properties["holocron_stack"] = deriveStack(rootPackageJson);
+			const capabilities = deriveCapabilities(config.providers);
+			properties["holocron_capabilities"] = capabilities;
+			properties["holocron_compliance"] = deriveCompliance(capabilities);
+		}
 		if (source.syncProperties) {
 			steps.push(await runStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
 			print(formatStep(steps[steps.length - 1]));
@@ -5178,34 +5536,36 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		const teams = repo?.teams ?? [];
-		if (teams.length > 0) if (source.syncTeams) {
-			steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
-			print(formatStep(steps[steps.length - 1]));
-			const repoCoord = input.context.repo ?? repo?.name ?? "";
-			const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
-			const writeableTeams = teams.map((t) => typeof t === "string" ? {
-				slug: t,
-				permission: "push"
-			} : t).filter((t) => [
-				"push",
-				"maintain",
-				"admin"
-			].includes(t.permission));
-			if (org && writeableTeams.length > 0) {
-				steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
-					const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
-					await source.writeRepoFile(".github/CODEOWNERS", content);
-				}));
+		if (teams.length > 0) {
+			if (source.syncTeams) {
+				steps.push(await runStep("source", "sync teams", dryRun, () => source.syncTeams(teams), { skipCodes: [422] }));
+				print(formatStep(steps[steps.length - 1]));
+				const repoCoord = input.context.repo ?? repo?.name ?? "";
+				const org = repoCoord.includes("/") ? repoCoord.split("/")[0] : "";
+				const writeableTeams = teams.map((t) => typeof t === "string" ? {
+					slug: t,
+					permission: "push"
+				} : t).filter((t) => [
+					"push",
+					"maintain",
+					"admin"
+				].includes(t.permission));
+				if (org && writeableTeams.length > 0) {
+					steps.push(await runStep("source", "write .github/CODEOWNERS", dryRun, async () => {
+						const content = writeableTeams.map((t) => `* @${org}/${t.slug}`).join("\n") + "\n";
+						await source.writeRepoFile(".github/CODEOWNERS", content);
+					}));
+					print(formatStep(steps[steps.length - 1]));
+				}
+			} else {
+				steps.push({
+					capability: "source",
+					step: "sync teams",
+					status: "skip",
+					message: "provider does not implement syncTeams"
+				});
 				print(formatStep(steps[steps.length - 1]));
 			}
-		} else {
-			steps.push({
-				capability: "source",
-				step: "sync teams",
-				status: "skip",
-				message: "provider does not implement syncTeams"
-			});
-			print(formatStep(steps[steps.length - 1]));
 		}
 	}
 	if (loader.has("environments")) {
@@ -5261,11 +5621,9 @@ async function runSetup(input) {
 		const wikiProxy = wiki.proxyConfig?.();
 		if (wikiDns && loader.has("dns")) {
 			const dns = loader.get("dns");
-			steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
+			steps.push(await runStep("dns", `upsertRecord ${wikiDns.record.name}`, dryRun, async () => {
 				await dns.upsertRecord(wikiDns.zone, {
-					type: "CNAME",
-					name: wikiDns.cname,
-					content: wikiDns.target,
+					...wikiDns.record,
 					ttl: 1,
 					...wikiProxy ? { proxied: true } : {}
 				});
@@ -5274,8 +5632,8 @@ async function runSetup(input) {
 		}
 		if (wikiProxy && wikiDns && loader.has("workers")) {
 			const workers = loader.get("workers");
-			steps.push(await runStep("workers", `upsertProxy ${wikiDns.cname}`, dryRun, async () => {
-				await workers.upsertProxy(wikiDns.cname, wikiProxy);
+			steps.push(await runStep("workers", `upsertProxy ${wikiDns.record.name}`, dryRun, async () => {
+				await workers.upsertProxy(wikiDns.record.name, wikiProxy);
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5288,11 +5646,31 @@ async function runSetup(input) {
 			org: config.org,
 			domain: config.domain
 		}) : null;
+		const ensureCustomDomain = async (projectId, hostname) => {
+			if (!deploy.ensureCustomDomain) return;
+			const customDomainDns = { value: null };
+			steps.push(await runStep("deployment", `ensureCustomDomain ${hostname}`, dryRun, async () => {
+				customDomainDns.value = await deploy.ensureCustomDomain(projectId, hostname);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+			if (customDomainDns.value && loader.has("dns")) {
+				const dns = loader.get("dns");
+				const dnsRecord = customDomainDns.value;
+				steps.push(await runStep("dns", `upsertRecord ${dnsRecord.record.name}`, dryRun, async () => {
+					await dns.upsertRecord(dnsRecord.zone, {
+						...dnsRecord.record,
+						ttl: 1
+					});
+				}));
+				print(formatStep(steps[steps.length - 1]));
+			}
+		};
 		if (!previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
 				await deploy.ensureProject({ name: config.name });
 			}));
 			print(formatStep(steps[steps.length - 1]));
+			if (deploy.domain) await ensureCustomDomain(config.name, deploy.domain);
 		}
 		if (previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${previewCfg.project}`, dryRun, async () => {
@@ -5300,13 +5678,8 @@ async function runSetup(input) {
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
-		if (previewCfg?.domain && deploy.ensureCustomDomain) {
-			steps.push(await runStep("deployment", `ensureCustomDomain ${previewCfg.domain}`, dryRun, async () => {
-				await deploy.ensureCustomDomain(previewCfg.project, previewCfg.domain);
-			}));
-			print(formatStep(steps[steps.length - 1]));
-		}
-		if (previewCfg?.domain && loader.has("dns")) {
+		if (previewCfg?.domain) await ensureCustomDomain(previewCfg.project, previewCfg.domain);
+		if (previewCfg?.domain && deploy.providerName === "cloudflare" && loader.has("dns")) {
 			const dns = loader.get("dns");
 			const wildcardDomain = `*.${previewCfg.domain}`;
 			steps.push(await runStep("dns", `upsertRecord ${previewCfg.domain}`, dryRun, async () => {
@@ -5754,11 +6127,13 @@ async function runSyncReadme(input) {
 	}
 	const description = loaded.resolved.description ?? "";
 	const homepage = loaded.resolved.homepage ?? pkg.homepage ?? "";
+	const scripts = pkg.scripts ?? {};
+	const packages = pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0;
 	const sections = generateReadme({
 		description,
 		homepage,
-		scripts: pkg.scripts ?? {},
-		packages: pkg.name ? REGISTRY_MAP[pkg.name]?.() : void 0
+		scripts,
+		packages
 	});
 	const markerSections = {
 		...sections.packages !== void 0 && { packages: sections.packages },
@@ -6000,7 +6375,7 @@ async function runSyncWiki(input) {
 			capability: "local",
 			step: "sync wiki",
 			status: "fail",
-			message: err instanceof Error ? err.message : 			/* c8 ignore next */ String(err)
+			message: err instanceof Error ? err.message : /* c8 ignore next */ String(err)
 		};
 	}
 }
@@ -6062,40 +6437,59 @@ async function runSync(input) {
 		for (const stepName of SYNC_STEPS) {
 			if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
 			if (LOCAL_STEPS.has(stepName)) continue;
-			if (stepName === "labels") if (source.syncLabels) {
-				steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
-				print(formatSyncStep(steps[steps.length - 1]));
-			} else {
-				steps.push({
-					capability: "source",
-					step: "sync labels",
-					status: "skip",
-					message: "provider does not implement syncLabels"
-				});
-				print(formatSyncStep(steps[steps.length - 1]));
+			if (stepName === "labels") {
+				if (source.syncLabels) {
+					steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push({
+						capability: "source",
+						step: "sync labels",
+						status: "skip",
+						message: "provider does not implement syncLabels"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
 			}
-			if (stepName === "properties") if (source.syncProperties) {
-				const repo = config.repo;
-				const properties = {};
-				const effectivePreset = repo?.protection;
-				if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
-				const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
-				properties["monorepo"] = String(isMonorepo);
-				const manual = repo?.properties ?? {};
-				if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
-				if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
-				if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
-				if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
-				steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
-				print(formatSyncStep(steps[steps.length - 1]));
-			} else {
-				steps.push({
-					capability: "source",
-					step: "sync properties",
-					status: "skip",
-					message: "provider does not implement syncProperties"
-				});
-				print(formatSyncStep(steps[steps.length - 1]));
+			if (stepName === "properties") {
+				if (source.syncProperties) {
+					const repo = config.repo;
+					const properties = {};
+					const effectivePreset = repo?.protection;
+					if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
+					const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
+					properties["monorepo"] = String(isMonorepo);
+					const manual = repo?.properties ?? {};
+					if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
+					if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
+					if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
+					if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+					{
+						const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+						const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+						const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+						properties["holocron_profile"] = deriveProfile({
+							rootPackageJson,
+							repoName: basename(input.context.repoRoot),
+							isMonorepo,
+							workspacePackageJsons
+						});
+						properties["holocron_stack"] = deriveStack(rootPackageJson);
+						const capabilities = deriveCapabilities(config.providers);
+						properties["holocron_capabilities"] = capabilities;
+						properties["holocron_compliance"] = deriveCompliance(capabilities);
+					}
+					steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push({
+						capability: "source",
+						step: "sync properties",
+						status: "skip",
+						message: "provider does not implement syncProperties"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
 			}
 			if (stepName === "teams") {
 				const teams = config.repo?.teams ?? [];
@@ -6307,29 +6701,34 @@ async function runSync(input) {
 				}
 			}
 		}
-		if (stepName === "scripts") if (config.syncScripts === false) {
-			steps.push({
-				capability: "local",
-				step: "sync scripts",
-				status: "skip",
-				message: "syncScripts: false"
-			});
-			print(formatSyncStep(steps[steps.length - 1]));
-		} else {
-			const tasksConfig = { tasks: config.tasks };
-			if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
-			const desired = createAstromech({
-				cwd: input.context.repoRoot,
-				config: tasksConfig,
-				logger
-			}).packageScripts();
-			steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
-				const changed = await mergePackageJsonScripts(input.context.repoRoot, desired);
-				if (changed === null) return "no package.json";
-				if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
-				return `${changed.join(", ")} set`;
-			}));
-			print(formatSyncStep(steps[steps.length - 1]));
+		if (stepName === "scripts") {
+			if (config.syncScripts === false) {
+				steps.push({
+					capability: "local",
+					step: "sync scripts",
+					status: "skip",
+					message: "syncScripts: false"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			} else {
+				const tasksConfig = { tasks: config.tasks };
+				if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
+				const astromechScripts = createAstromech({
+					cwd: input.context.repoRoot,
+					config: tasksConfig,
+					logger
+				});
+				const desired = astromechScripts.packageScripts();
+				const turboContent = astromechScripts.turboConfig();
+				const turboEligible = new Set(turboContent ? Object.keys(JSON.parse(turboContent).tasks) : []);
+				steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
+					const changed = await mergePackageJsonScripts(input.context.repoRoot, desired, turboEligible);
+					if (changed === null) return "no package.json";
+					if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
+					return `${changed.join(", ")} set`;
+				}));
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
 		}
 		if (stepName === "turbo") {
 			const astromechTurbo = createAstromech({
@@ -6351,9 +6750,10 @@ async function runSync(input) {
 					await writeFile(join(input.context.repoRoot, "turbo.json"), content, "utf8");
 				}));
 				print(formatSyncStep(steps[steps.length - 1]));
-				const rootPkg = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
 				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
-				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const rootScripts = rootPkg?.scripts ?? {};
 				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
 				if (workspaceFix.changed) {
 					steps.push(await runSyncStep("local", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
@@ -6361,6 +6761,15 @@ async function runSync(input) {
 					}));
 					print(formatSyncStep(steps[steps.length - 1]));
 				}
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) {
+						steps.push(await runSyncStep("local", "add turbo devDependency", dryRun, async () => {
+							await writeFile(join(input.context.repoRoot, "package.json"), depFix.content, "utf8");
+						}));
+						print(formatSyncStep(steps[steps.length - 1]));
+					}
+				}
 			}
 		}
 		if (stepName === "wiki") {
@@ -6444,8 +6853,21 @@ async function writePackageJsonField(repoRoot, field, value) {
 * Merge `desired` script entries into `package.json#scripts` — sets only the
 * listed keys, never touches the rest. Returns the sorted list of keys that
 * drifted (empty when all current), or `null` when there is no `package.json`.
+*
+* `turboEligible` (#747): task names `turbo.json` fans out — the same set
+* {@link EnsureRootWorkspaceMemberResult} above already keys off. For those
+* only, an *existing* script that isn't the generated `holocron run <task>
+* --` wrapper is left untouched: root may genuinely be a directly-buildable
+* package (not an orchestrator) with its own real command (`tsc --noEmit`,
+* `vitest run`, …) for that task. Overwriting it would silently discard the
+* real command and, once `turbo.json` exists and root is a real workspace
+* member (#692), reintroduce infinite recursion — `turbo run <task>` →
+* root's own `<task>` script → the wrapper → `holocron run <task>` sees
+* `turbo.json` still defines the task → `turbo run <task>` again, forever.
+* Every other key (non-turbo tasks, `holocron`, `prepare`, …) has no
+* legitimate direct-command alternative and stays fully generator-owned.
 */
-async function mergePackageJsonScripts(repoRoot, desired) {
+async function mergePackageJsonScripts(repoRoot, desired, turboEligible) {
 	const pkgPath = join(repoRoot, "package.json");
 	let content;
 	try {
@@ -6456,15 +6878,31 @@ async function mergePackageJsonScripts(repoRoot, desired) {
 	const pkg = JSON.parse(content);
 	const scripts = pkg.scripts ?? {};
 	const changed = [];
-	for (const [name, command] of Object.entries(desired)) if (scripts[name] !== command) {
-		scripts[name] = command;
-		changed.push(name);
+	for (const [name, command] of Object.entries(desired)) {
+		const existing = scripts[name];
+		if (turboEligible.has(name) && existing !== void 0 && !isGeneratedRunWrapper(existing, name)) continue;
+		if (existing !== command) {
+			scripts[name] = command;
+			changed.push(name);
+		}
 	}
 	if (changed.length === 0) return [];
 	pkg.scripts = scripts;
 	await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
 	return changed.sort();
 }
+/**
+* Matches the exact shape `packageScripts()` generates for `taskName` —
+* `<bin> run <taskName> --`, `<bin>` normally `holocron` but substitutable
+* (`holocronScript`, itself allowed to be multi-word, e.g. `"node
+packages/cli/dist/cli.mjs"` — see its own test). Checking the *suffix*
+* rather than the whole string means an old wrapper survives a
+* `holocronScript` rename intact — it's still recognized as a wrapper (safe
+* to update to the new one), not mistaken for a real command.
+*/
+function isGeneratedRunWrapper(command, taskName) {
+	return command.endsWith(` run ${taskName} --`);
+}
 const README_DESC_START = "<!-- holocron:description -->";
 const README_DESC_END = "<!-- /holocron:description -->";
 async function updateReadmeDescription(repoRoot, description) {
@@ -7331,6 +7769,63 @@ async function runUpgradeNode(input) {
 	};
 }
 //#endregion
+//#region src/commit-lint/lint-message.ts
+/**
+* Lints one commit message string against an already-loaded commitlint
+* config. The genuinely environment-independent half of commit-message
+* linting (holocron#789) — *obtaining* a `QualifiedConfig` differs by
+* caller (Sentinel isolates itself from any ambient config since it runs
+* standalone, away from a real repo checkout; `lintCommitMsgFile` below
+* just lets cosmiconfig discover the invoking repo's own
+* `commitlint.config.*`, matching `commitlint --edit`'s own contract) —
+* but linting one message against a loaded config is identical either way.
+*
+* Real `@commitlint/lint` — the same programmatic API `@commitlint/cli`
+* itself uses internally — never a reimplementation of commitlint's rules.
+*/
+/** `parserPreset.parserOpts`, if the loaded config sets one — same lookup `@commitlint/cli`'s own `selectParserOpts()` does. */
+function selectParserOpts(parserPreset) {
+	return parserPreset?.parserOpts;
+}
+async function lintCommitMessage(message, loaded) {
+	const opts = {
+		/* istanbul ignore next -- see comment above */
+		parserOpts: selectParserOpts(loaded.parserPreset) ?? {},
+		plugins: loaded.plugins,
+		/* istanbul ignore next -- see comment above */
+		ignores: loaded.ignores ?? [],
+		defaultIgnores: loaded.defaultIgnores !== false
+	};
+	const outcome = await lint(message, loaded.rules, opts);
+	if (outcome.valid) return [];
+	return outcome.errors.map((error) => ({
+		rule: error.name,
+		message: error.message
+	}));
+}
+//#endregion
+//#region src/commit-lint/lint-commit-msg-file.ts
+/**
+* `holocron lint commit-msg <file>` — a real programmatic replacement for
+* shelling out to `commitlint --edit "$1"` from `.husky/commit-msg`
+* (holocron#789). Matches that CLI's own contract exactly: `file` is a
+* path to the commit message being written (the arg git's `commit-msg`
+* hook passes as `$1`), no `--config` override needed — `@commitlint/load`
+* runs from `cwd` with no seed, so cosmiconfig's own normal upward search
+* discovers the invoking repo's real `commitlint.config.*` file, exactly
+* as `commitlint --edit` (no `--config` flag) already does today. Unlike
+* Sentinel's `loadIsolatedConfig()`, no isolation is needed here — this
+* runs inside a real repo checkout with a real `node_modules`, not
+* standalone on a server.
+*/
+async function lintCommitMsgFile(filePath, cwd = process.cwd()) {
+	const violations = await lintCommitMessage(await readFile(filePath, "utf8"), await load({}, { cwd }));
+	return {
+		valid: violations.length === 0,
+		violations
+	};
+}
+//#endregion
 //#region src/config/load-config.ts
 /**
 * `holocron.config.{ts,js,mjs,cjs,json}` loader.
@@ -7441,7 +7936,9 @@ const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
 * The full command surface, hand-maintained in parallel with `cli.ts`'s
 * yargs registrations (this module does not introspect yargs at runtime).
 * `run <task>` is deliberately excluded — it's CI/scripting-oriented, and an
-* interactive prompt in front of it would work against that.
+* interactive prompt in front of it would work against that. `lint
+* commit-msg <file>` is excluded for the same reason: it's invoked
+* exclusively from `.husky/commit-msg "$1"`, never typed by a human.
 */
 const COMMAND_REGISTRY = [
 	{
@@ -7752,7 +8249,7 @@ async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessag
 //#endregion
 //#region src/update-notifier.ts
 const PACKAGE_NAME = "@theholocron/cli";
-const CACHE_TTL_MS = 1440 * 60 * 1e3;
+const CACHE_TTL_MS = 864e5;
 const FETCH_TIMEOUT_MS = 3e3;
 function getCacheDir() {
 	return env.get("HOLOCRON_CACHE_DIR") ?? join(homedir(), ".cache", "holocron");
@@ -8118,9 +8615,17 @@ try {
 		type: "array",
 		default: ["production", "preview"],
 		describe: "Deployment targets to sync to. Defaults to production + preview."
+	}).option("github-secret", {
+		type: "array",
+		describe: "Vault key(s) to push to GH Actions secrets (repeatable). Omit to push every key."
+	}).option("github-secret-scope", {
+		type: "string",
+		default: "repo",
+		describe: "Scope applied to every --github-secret key: \"repo\" (default), \"env=<name>\", or \"org=<name>\"."
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
+		const githubSecretScope = parseScope(argv.githubSecretScope);
 		const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
@@ -8134,11 +8639,13 @@ try {
 			},
 			environmentId,
 			...argv.projectId ? { projectId: argv.projectId } : {},
+			...argv.githubSecret?.length ? { githubSecretKeys: argv.githubSecret } : {},
+			githubSecretScope,
 			targets: argv.target
 		})).summary.fail > 0) process.exitCode = 1;
 	}).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
 		type: "string",
-		describe: "Git branch to deploy"
+		describe: "Git branch to deploy (omit when using --files)"
 	}).option("project-id", {
 		type: "string",
 		demandOption: true,
@@ -8147,20 +8654,34 @@ try {
 		type: "string",
 		choices: ["production", "staging"],
 		describe: "Named environment to deploy into. Omit for a branch preview."
-	}), async (argv) => {
+	}).option("files", {
+		type: "string",
+		describe: "Deploy from a local directory of source files instead of a Git branch — calls deployFunction(), no linked repo required. Conflicts with `branch`."
+	}).conflicts("files", "branch"), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
-		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
+		const context = {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...tokens,
+			org: resolveOrg(argv, loaded.resolved)
+		};
+		if (argv.files) {
+			if ((await runDeployFromFiles({
+				loaded,
+				context,
+				projectId: argv.projectId,
+				dir: argv.files,
+				...argv.target ? { target: argv.target } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
+		}
+		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		if ((await runDeploy({
 			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
+			context,
 			projectId: argv.projectId,
 			branch,
 			...argv.target ? { target: argv.target } : {}
@@ -8336,7 +8857,36 @@ try {
 			scope: argv.all ? "all" : "required",
 			...argv.filter ? { filter: argv.filter } : {}
 		}).status === "fail") process.exitCode = 1;
-	}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
+	}).command("deploy-on-release", "Deploy every workspace package whose delivery.deploy task is `on: release` — run by the delivery.publish workflow's deploy job", (y) => y.option("channel", {
+		type: "string",
+		default: "",
+		describe: "The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release."
+	}).option("from", {
+		type: "string",
+		describe: "The previous release's commit, to diff against. Omit when there is none."
+	}).option("to", {
+		type: "string",
+		describe: "The release commit. Default HEAD."
+	}), async (argv) => {
+		if ((await deployOnRelease({
+			cwd: argv.cwd,
+			channel: argv.channel,
+			...argv.from ? { from: argv.from } : {},
+			...argv.to ? { to: argv.to } : {},
+			dryRun: argv.dryRun,
+			print: (line) => console.log(line)
+		})).status === "fail") process.exitCode = 1;
+	}).command("lint", "Lint content locally against the org's shared rules", (y) => y.command("commit-msg <file>", "Lint a commit message file — matches `commitlint --edit`'s own contract, for use from .husky/commit-msg", (yy) => yy.positional("file", {
+		type: "string",
+		demandOption: true,
+		describe: "Path to the commit message file (git's commit-msg hook passes this as $1)."
+	}), async (argv) => {
+		const result = await lintCommitMsgFile(argv.file, argv.cwd);
+		if (!result.valid) {
+			for (const violation of result.violations) console.error(`✖ ${violation.rule}: ${violation.message}`);
+			process.exitCode = 1;
+		}
+	}), () => {}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {
 		type: "string",
 		default: "theholocron/.github",
 		describe: "Target org/repo (default: theholocron/.github)"