@theholocron/cli 2.0.0-alpha.0 → 2.0.0-alpha.10

package/dist/cli.mjs

@@ -1,11 +1,404 @@
-#!/usr/bin/env -S tsx
-import { t as CARDINALITY } from "./capabilities-QjjhVlDd.mjs";
-import { n as resolveConfig, t as ConfigError } from "./config-DWlIfFZm.mjs";
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import { Entry, findCredentials } from "@napi-rs/keyring";
+import path, { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
+//#region src/capabilities/index.ts
+const CARDINALITY = {
+	source: "single",
+	ci: "single",
+	secrets: "single",
+	environments: "single",
+	issues: "single",
+	deployment: "single",
+	storage: "single",
+	auth: "single",
+	vault: "single",
+	dns: "single",
+	tooling: "many",
+	notifications: "many",
+	analytics: "many",
+	observability: "many"
+};
+/**
+* No capabilities are strictly required — repos without secrets (e.g. org
+* community health repos) legitimately omit vault. Plugins validate their
+* own requirements at call time.
+*/
+const REQUIRED_CAPABILITIES = [];
+/**
+* Surfaced from every capability call that hits a vendor API. Wraps
+* the underlying error with `status` (HTTP) and `details` so
+* orchestrators (`holocron setup`, `doctor`) can soft-skip rather
+* than abort.
+*/
+var ProviderApiError = class extends Error {
+	status;
+	details;
+	name = "ProviderApiError";
+	constructor(message, status, details) {
+		super(message);
+		this.status = status;
+		this.details = details;
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* `holocron.config.json` schema, parser, and provider resolution.
+*
+* ESLint-style entry forms:
+*
+*   "source": "github"                              ← single, short
+*   "deployment": ["vercel", { team: "rando" }]    ← single, with options
+*   "notifications": ["slack", "discord"]          ← multi, short
+*   "notifications": [
+*     ["slack",   { channel: "#ops" }],
+*     ["discord", { webhook: "env:HOOK" }]
+*   ]                                              ← multi, with options
+*
+* Discriminator: an array entry is a `[provider, options]` tuple when
+* the length is 2 AND element[1] is a non-array, non-null object.
+* Otherwise it's a multi-provider list (string[] or tuple[]).
+*
+* Validation rules:
+*   - `vault` is REQUIRED (every project has secrets somewhere)
+*   - Entries for `'many'` capabilities are normalized to an array of
+*     normalized tuples; entries for `'single'` capabilities are
+*     normalized to one tuple
+*   - Tokens / secret values never appear in config — providers read
+*     them from env (or pull from `vault` at runtime)
+*/
+var ConfigError = class extends Error {
+	name = "ConfigError";
+};
+const PLUGIN_PREFIX = "@theholocron/holocron-plugin-";
+const COMMUNITY_PREFIX = "holocron-plugin-";
+/**
+* Resolve `"github"` → `"@theholocron/holocron-plugin-github"`.
+* Fully-qualified names (scoped or not) are honored verbatim, which
+* is how third-party plugins published outside the org work.
+*/
+function resolvePluginPackage(provider) {
+	if (!provider) throw new ConfigError("provider name is empty");
+	if (provider.startsWith("@")) return provider;
+	if (provider.startsWith(COMMUNITY_PREFIX)) return provider;
+	if (provider.includes("/")) return provider;
+	return PLUGIN_PREFIX + provider;
+}
+/** A bare `[provider, options]` tuple, with both elements present? */
+function isOptionsTuple(value) {
+	if (!Array.isArray(value)) return false;
+	if (value.length !== 2) return false;
+	if (typeof value[0] !== "string") return false;
+	const opt = value[1];
+	return typeof opt === "object" && opt !== null && !Array.isArray(opt);
+}
+function normalizeEntry(entry) {
+	if (typeof entry === "string") return {
+		provider: entry,
+		packageName: resolvePluginPackage(entry),
+		options: {}
+	};
+	const [provider, options] = entry;
+	return {
+		provider,
+		packageName: resolvePluginPackage(provider),
+		options
+	};
+}
+function resolveEntry(key, raw) {
+	const cardinality = CARDINALITY[key];
+	if (typeof raw === "string") {
+		if (cardinality === "many") throw new ConfigError(`\`${key}\` accepts multiple providers; wrap a single one in an array: ["${raw}"]`);
+		return {
+			cardinality: "single",
+			tuple: normalizeEntry(raw)
+		};
+	}
+	if (!Array.isArray(raw)) throw new ConfigError(`\`${key}\` entry must be a string or array, got ${typeof raw}`);
+	if (isOptionsTuple(raw)) {
+		if (cardinality === "many") return {
+			cardinality: "many",
+			tuples: [normalizeEntry(raw)]
+		};
+		return {
+			cardinality: "single",
+			tuple: normalizeEntry(raw)
+		};
+	}
+	if (cardinality === "single") throw new ConfigError(`\`${key}\` accepts exactly one provider; got a multi-provider list with ${raw.length} entries`);
+	return {
+		cardinality: "many",
+		tuples: raw.map((entry, idx) => {
+			if (typeof entry === "string") return normalizeEntry(entry);
+			if (isOptionsTuple(entry)) return normalizeEntry(entry);
+			throw new ConfigError(`\`${key}[${idx}]\` must be a provider string or [provider, options] tuple`);
+		})
+	};
+}
+function resolveConfig(raw) {
+	if (!raw.project?.name) throw new ConfigError("`project.name` is required");
+	if (!raw.providers || typeof raw.providers !== "object") throw new ConfigError("`providers` block is required");
+	const providers = {};
+	for (const [key, entry] of Object.entries(raw.providers)) {
+		if (entry === void 0) continue;
+		providers[key] = resolveEntry(key, entry);
+	}
+	for (const required of REQUIRED_CAPABILITIES) if (!providers[required]) throw new ConfigError(`required capability \`${required}\` is missing from providers`);
+	return {
+		project: raw.project,
+		providers,
+		apps: raw.apps ?? [],
+		doctor: raw.doctor ?? {}
+	};
+}
+//#endregion
+//#region src/keyring.ts
+/**
+* Keyring-backed bootstrap credential store.
+*
+* Every holocron plugin's bootstrap token (the one it needs before it
+* can talk to its vendor's API) can be stored in the OS keyring under
+* a single reverse-DNS service scope. Managed via `holocron auth`
+* subcommands; consulted at position 4 in every plugin's auth
+* precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
+*
+* See `.notes/tech-auth-bootstrap.spec.md` for the design rationale.
+*
+* Failure model: keyring access is best-effort. Platforms without a
+* supported credential store (some Linux CI images, sandboxed
+* environments) will throw from the underlying library. Every export
+* here catches and returns a null/empty result rather than propagating
+* — the plugin's precedence chain then falls through to
+* env-var-only paths, which is exactly how CI is meant to work.
+*/
+const SERVICE = "com.theholocron.cli";
+/**
+* Store or overwrite a bootstrap token for a provider. Returns true on
+* success, false when the underlying keyring is unsupported or errored.
+*/
+function setToken(provider, token) {
+	try {
+		new Entry(SERVICE, provider).setPassword(token);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Read the bootstrap token for a provider. Returns `null` for both
+* "not stored" and "keyring unavailable" — callers can treat them the
+* same way (fall through to env-var precedence).
+*/
+function getToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).getPassword();
+	} catch {
+		return null;
+	}
+}
+/**
+* Delete a stored token. Returns true when a token was removed, false
+* when there was nothing to delete or the keyring is unavailable.
+* Distinguishing the two cases isn't worth the surface area — the
+* command output makes the situation clear either way.
+*/
+function deleteToken(provider) {
+	try {
+		return new Entry(SERVICE, provider).deletePassword();
+	} catch {
+		return false;
+	}
+}
+/**
+* List provider slugs with a stored token in this service scope.
+* Uses the library's `findCredentials(service)` — supported on all
+* platforms the underlying credential store supports.
+*/
+function listStoredProviders() {
+	try {
+		return findCredentials(SERVICE).map((c) => c.account);
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/commands/auth.ts
+/**
+* `holocron auth <subcommand>` — manage bootstrap credentials in the
+* OS keyring.
+*
+* Subcommands:
+*   auth set <provider> [token]   verify + store
+*   auth unset <provider>         remove
+*   auth check <provider>         re-verify a stored token
+*   auth list                     every provider with a stored entry
+*
+* See `.notes/tech-auth-bootstrap.spec.md`.
+*
+* Verification lives in each plugin as a top-level `verifyToken(token)`
+* export. The auth command dynamically imports
+* `@theholocron/holocron-plugin-<provider>` and calls it. Plugins that
+* don't export `verifyToken` can still store — with a warning — because
+* "no verify path" shouldn't block credential storage.
+*/
+const defaultImporter$1 = async (pkg) => await import(pkg);
+/**
+* Resolve a token from (positional → HOLOCRON_<X> → vendor-native env).
+* Keyring is NOT consulted here — `auth set` writes TO the keyring, so
+* pulling FROM it would just re-store the same value.
+*/
+function resolveAuthSetToken(input) {
+	const env = input.env ?? process.env;
+	const upper = input.provider.toUpperCase();
+	const holocronKey = `HOLOCRON_${upper}_TOKEN`;
+	return input.positional || env[holocronKey] || env[upper + "_TOKEN"] || null;
+}
+async function runAuthSet(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const { provider } = input;
+	const token = resolveAuthSetToken({
+		provider,
+		positional: input.positional,
+		env: input.env
+	});
+	const packageName = resolvePluginPackage(provider);
+	if (!token) {
+		print(`no token supplied for \`${provider}\`.`);
+		print(`  pass as positional arg: holocron auth set ${provider} <token>`);
+		print(`  or via env: HOLOCRON_${provider.toUpperCase()}_TOKEN / ${provider.toUpperCase()}_TOKEN`);
+		const hint = await tryLoadHint(importer, packageName);
+		if (hint) print(`  hint: ${hint}`);
+		return {
+			status: "fail",
+			message: "no token supplied"
+		};
+	}
+	let subject;
+	try {
+		const module = await importer(packageName);
+		if (typeof module.verifyToken === "function") {
+			const verified = await module.verifyToken(token);
+			if (!verified.ok) {
+				print(`token rejected by ${provider}: ${verified.message}`);
+				if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+				return {
+					status: "fail",
+					message: verified.message
+				};
+			}
+			subject = verified.subject;
+		} else print(`(${provider} plugin has no verifyToken; storing without verification)`);
+	} catch (err) {
+		print(`cannot verify token — failed to load ${packageName}: ${err instanceof Error ? err.message : String(err)}`);
+		print(`  storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`);
+	}
+	if (!setToken(provider, token)) {
+		print(`keyring unavailable — token not stored. Use env vars instead.`);
+		return {
+			status: "fail",
+			message: "keyring unavailable"
+		};
+	}
+	print(`stored ${provider} token${subject ? ` (${subject})` : ""}`);
+	return {
+		status: "ok",
+		...subject ? { message: subject } : {}
+	};
+}
+function runAuthUnset(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	if (deleteToken(input.provider)) {
+		print(`removed ${input.provider} token`);
+		return { status: "ok" };
+	}
+	print(`no stored token for ${input.provider}`);
+	return {
+		status: "skip",
+		message: "nothing to remove"
+	};
+}
+async function runAuthCheck(input) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const { provider } = input;
+	const token = getToken(provider);
+	if (!token) {
+		print(`no stored token for ${provider}`);
+		return {
+			status: "skip",
+			message: "no stored token"
+		};
+	}
+	const packageName = resolvePluginPackage(provider);
+	try {
+		const module = await importer(packageName);
+		if (typeof module.verifyToken !== "function") {
+			print(`${provider}: token stored (plugin has no verifyToken; can't confirm validity)`);
+			return {
+				status: "ok",
+				message: "stored, unverified"
+			};
+		}
+		const verified = await module.verifyToken(token);
+		if (verified.ok) {
+			print(`${provider}: ok — ${verified.subject}`);
+			return {
+				status: "ok",
+				message: verified.subject
+			};
+		}
+		print(`${provider}: rejected — ${verified.message}`);
+		if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+		return {
+			status: "fail",
+			message: verified.message
+		};
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		print(`${provider}: cannot verify — ${msg}`);
+		return {
+			status: "fail",
+			message: msg
+		};
+	}
+}
+async function runAuthList(input = {}) {
+	const print = input.print ?? ((l) => console.log(l));
+	const importer = input.importer ?? defaultImporter$1;
+	const providers = listStoredProviders();
+	if (providers.length === 0) {
+		print("no stored tokens.");
+		print("run: holocron auth set <provider> <token>");
+		return {
+			status: "ok",
+			message: "none"
+		};
+	}
+	for (const provider of providers.sort()) {
+		const check = await runAuthCheck({
+			provider,
+			importer,
+			print: () => {}
+		});
+		print(`  ${check.status === "ok" ? "✓" : check.status === "fail" ? "✗" : "·"} ${provider}${check.message ? ` — ${check.message}` : ""}`);
+	}
+	return { status: "ok" };
+}
+async function tryLoadHint(importer, packageName) {
+	try {
+		return (await importer(packageName)).AUTH_HINT ?? null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/loader.ts
 var LoaderError = class extends Error {
 	name = "LoaderError";
@@ -58,12 +451,23 @@ var PluginLoader = class {
 		});
 		if (typeof module.createPlugin !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\``);
 		const factory = module.createPlugin({
+			...this.projectDefaults(),
 			...this.context,
 			...tuple.options
 		}).capabilities[key];
 		if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
 		return factory();
 	}
+	/**
+	* Project-level defaults that get merged into every plugin's options
+	* unless overridden by the CLI context or per-plugin tuple options.
+	* See `.notes/tech-setup-and-config.spec.md` §Design.
+	*/
+	projectDefaults() {
+		const defaults = {};
+		if (this.config.project.repo) defaults.repo = this.config.project.repo;
+		return defaults;
+	}
 };
 /** Default importer — native dynamic import. */
 const defaultImporter = async (pkg) => {
@@ -175,149 +579,2702 @@ async function smokeCheck(key, provider, impl) {
 			default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 		}
 	} catch (err) {
-		return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
+		return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
+	}
+}
+function countResolvedLifecycle(report) {
+	return `${report.lifecycle.filter((l) => l.resolved).length}/${report.lifecycle.length} lifecycle slots ready`;
+}
+function mk(capability, provider, status, message) {
+	return {
+		capability,
+		provider,
+		status,
+		message
+	};
+}
+function pad(s, width) {
+	return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+//#endregion
+//#region src/commands/npm-bump-versions.ts
+async function runNpmBumpVersions(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const cwd = input.cwd ?? process.cwd();
+	const { version, dryRun = false } = input;
+	const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const writeFile = input.writeFile ?? ((p, c) => writeFileSync(p, c));
+	const listDir = input.listDir ?? ((p) => readdirSync(p));
+	const isDir = input.isDir ?? ((p) => statSync(p).isDirectory());
+	const bumped = [];
+	const skipped = [];
+	print(`Bumping monorepo to ${version}${dryRun ? " (dry-run)" : ""}…`);
+	function bumpFile(absPath, label) {
+		let pkg;
+		try {
+			pkg = JSON.parse(readFile(absPath));
+		} catch {
+			print(`  ✗ could not parse ${label}`);
+			return;
+		}
+		const old = pkg.version;
+		if (!dryRun) {
+			pkg.version = version;
+			writeFile(absPath, JSON.stringify(pkg, null, 2) + "\n");
+		}
+		print(`  ${dryRun ? "~" : "✓"} ${label}: ${old} → ${version}`);
+		bumped.push(label);
+	}
+	bumpFile(join(cwd, "package.json"), "root");
+	const packagesDir = join(cwd, "packages");
+	let entries;
+	try {
+		entries = listDir(packagesDir);
+	} catch {
+		return {
+			status: "fail",
+			bumped,
+			skipped,
+			message: `packages/ directory not found in ${cwd}`
+		};
+	}
+	for (const entry of entries) {
+		const pkgDir = join(packagesDir, entry);
+		try {
+			if (!isDir(pkgDir)) continue;
+		} catch {
+			continue;
+		}
+		const pkgFile = join(pkgDir, "package.json");
+		let pkg;
+		try {
+			pkg = JSON.parse(readFile(pkgFile));
+		} catch {
+			print(`  ! skipping packages/${entry}: no package.json or malformed JSON`);
+			continue;
+		}
+		if (pkg.private) {
+			print(`  · skipping private package packages/${entry}`);
+			skipped.push(`packages/${entry}`);
+			continue;
+		}
+		bumpFile(pkgFile, `packages/${entry}`);
+	}
+	return {
+		status: dryRun ? "dry-run" : "ok",
+		bumped,
+		skipped
+	};
+}
+//#endregion
+//#region src/templates/index.ts
+/**
+* All reusable workflow and composite action content bundled as string
+* constants so the CLI can push them to theholocron/.github without
+* needing filesystem access at runtime.
+*
+* These are the sources of truth — the YAML files in this directory
+* have been removed in favour of these constants.
+*/
+const ACTIONS = {
+	"setup/action": `\
+name: Setup
+description: Prepare the environment and install project dependencies.
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: false
+    default: "22.x"
+
+runs:
+  using: composite
+
+  steps:
+    - uses: theholocron/.github/.github/actions/setup-node@main
+      with:
+        node-version: \${{ inputs.node-version }}
+
+    - uses: theholocron/.github/.github/actions/install@main
+`,
+	"install/action": `\
+name: Install dependencies
+description: Install project dependencies with pnpm frozen lockfile.
+
+runs:
+  using: composite
+
+  steps:
+    - name: Install dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile
+`,
+	"setup-node/action": `\
+name: Setup Node
+description: Install pnpm and Node.js with pnpm dependency caching.
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: false
+    default: "22.x"
+
+runs:
+  using: composite
+
+  steps:
+    - name: Setup pnpm
+      uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: \${{ inputs.node-version }}
+        cache: pnpm
+
+    - name: Add node_modules/.bin to PATH
+      shell: bash
+      run: echo "$GITHUB_WORKSPACE/node_modules/.bin" >> $GITHUB_PATH
+`
+};
+const REUSABLE_WORKFLOWS = {
+	audit: `\
+name: Audit
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      build-script:
+        description: Script to build before analyzing bundle size
+        type: string
+        required: false
+        default: pnpm build
+    secrets:
+      BUNDLEWATCH_GITHUB_TOKEN:
+        required: true
+
+jobs:
+  bundle-size:
+    name: Audit the bundle size
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    concurrency:
+      group: audit-\${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - uses: jackyef/bundlewatch-gh-action@01f51133d3580a6daa046ca83eb233d79735e1c1 # 0.3.0
+        name: Analyze using BundleWatch
+        with:
+          build-script: \${{ inputs.build-script }}
+          bundlewatch-github-token: \${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
+`,
+	"bookkeeping-pr": `\
+name: PR Bookkeeping
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      configuration-path:
+        description: Path to the labeler configuration file in the calling repo
+        type: string
+        required: false
+        default: .github/labeler.yml
+
+jobs:
+  label:
+    name: Add Labels to PRs
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: bookkeeping-pr-\${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          sparse-checkout: \${{ inputs.configuration-path || '.github/labeler.yml' }}
+          sparse-checkout-cone-mode: false
+
+      - uses: github/issue-labeler@c1b0f9f52a63158c4adc09425e858e87b32e9685 # v3.4
+        if: \${{ hashFiles(inputs.configuration-path || '.github/labeler.yml') != '' }}
+        with:
+          # Fall back to default path when triggered directly (not via workflow_call)
+          # because inputs.* defaults only apply on workflow_call events.
+          configuration-path: \${{ inputs.configuration-path || '.github/labeler.yml' }}
+          include-title: 1
+          include-body: 0
+          sync-labels: 1
+          enable-versioned-regex: 0
+          repo-token: \${{ github.token }}
+`,
+	codeql: `\
+name: CodeQL
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      language:
+        description: CodeQL language to analyze
+        type: string
+        required: false
+        default: javascript-typescript
+
+jobs:
+  analyze:
+    name: Analyze (\${{ inputs.language }})
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    # Do not cancel in-progress security scans.
+    concurrency:
+      group: codeql-\${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: github/codeql-action/init@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Initialize CodeQL
+        with:
+          languages: \${{ inputs.language }}
+
+      - uses: github/codeql-action/autobuild@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Autobuild
+
+      - uses: github/codeql-action/analyze@411c4c9a36b3fca4d674f06b6396b2c6d23522c6 # v3
+        name: Analyze
+        with:
+          category: /language:\${{ inputs.language }}
+`,
+	dependencies: `\
+name: Dependencies
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    secrets:
+      merge-token:
+        description: >
+          Optional privileged token for auto-merge. Falls back to GITHUB_TOKEN.
+          Required when branch protection enforces required reviews — GITHUB_TOKEN
+          cannot approve its own PRs.
+        required: false
+
+jobs:
+  dependabot:
+    name: Update the dependencies
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: dependencies-\${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a # v2
+        name: Fetch Dependabot metadata
+        id: metadata
+
+      - run: gh pr merge --auto --squash "$PR_URL"
+        # --squash is intentional: repoPolicy sets allow_merge_commit: false,
+        # so --merge would fail on any repo using the standard preset.
+        name: Enable auto-merge for Dependabot PRs
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        env:
+          PR_URL: \${{ github.event.pull_request.html_url }}
+          GH_TOKEN: \${{ secrets.merge-token || github.token }}
+`,
+	greetings: `\
+name: Greetings
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+jobs:
+  greeting:
+    name: Greet first-time contributors
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Group by the issue/PR number so duplicate events don't race each other.
+    concurrency:
+      group: greetings-\${{ github.event.issue.number || github.event.pull_request.number }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        name: Greet on first contribution
+        with:
+          script: |
+            // Only greet on the initial open — ignore synchronize, reopened, etc.
+            if (context.payload.action !== 'opened') return;
+
+            const actor = context.actor;
+            const { owner, repo } = context.repo;
+
+            // Payload inspection is more reliable than context.eventName for detecting
+            // whether this is an issue vs. PR event — works regardless of how GitHub
+            // propagates event names through workflow_call chains.
+            const isIssue = !!context.payload.issue && !context.payload.pull_request;
+            // listForRepo returns both issues and PRs (GitHub treats PRs as issues),
+            // sorted newest-first. Filter by type to track first-issue and first-PR
+            // independently, and avoid search-index eventual-consistency lag.
+            const { data: recent } = await github.rest.issues.listForRepo({
+              owner, repo,
+              creator: actor,
+              state: 'all',
+              per_page: 100
+            });
+
+            const sameType = recent.filter(item =>
+              isIssue ? !item.pull_request : !!item.pull_request
+            );
+
+            if (sameType.length !== 1) return;
+            const body = isIssue
+              ? \`Hey @\${actor}!\\n\\nWe really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.\`
+              : \`Hey @\${actor}!\\n\\nWe really appreciate you taking the time to help out with this PR. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.\`;
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: context.issue.number,
+              body
+            });
+`,
+	lint: `\
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      prettier-config:
+        type: string
+        required: false
+        default: prettier.config.js
+      yaml-config:
+        type: string
+        required: false
+        default: yamllint.config.yml
+      enable-auto-commit:
+        description: Auto-commit super-linter fixes via GPG-signed commit
+        type: boolean
+        required: false
+        default: false
+    secrets:
+      SUPER_LINTER_GPG_PRIVATE_KEY:
+        required: false
+      SUPER_LINTER_GPG_PASSPHRASE:
+        required: false
+
+jobs:
+  super-lint:
+    name: Lint entire codebase
+    permissions:
+      contents: write
+      statuses: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+          token: \${{ github.token }}
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - uses: super-linter/super-linter/slim@b92721f792f381cedc002ecdbb9847a15ece5bb8 # v7.1.0
+        name: Run Super Linter
+        env:
+          GITHUB_TOKEN: \${{ github.token }}
+          ANNOTATE_ONLY: true
+          DISABLE_COMMENTS: false
+          IGNORE_GITIGNORED_FILES: true
+          LINTER_RULES_PATH: /
+          EDITORCONFIG_FILE_NAME: ".editorconfig-checker.json"
+          FIX_ENV: true
+          FIX_GRAPHQL_PRETTIER: true
+          FIX_HTML_PRETTIER: true
+          FIX_JAVASCRIPT_PRETTIER: true
+          FIX_JSX_PRETTIER: true
+          FIX_MARKDOWN_PRETTIER: true
+          FIX_TSX: true
+          FIX_TYPESCRIPT_PRETTIER: true
+          PRETTIER_CONFIG: \${{ inputs.prettier-config }}
+          VALIDATE_DOCKERFILE: true
+          VALIDATE_EDITORCONFIG: true
+          VALIDATE_ENV: true
+          VALIDATE_GIT_COMMITLINT: true
+          VALIDATE_GIT_MERGE_CONFLICT_MARKERS: true
+          VALIDATE_GITHUB_ACTIONS: true
+          VALIDATE_GITLEAKS: true
+          VALIDATE_GRAPHQL_PRETTIER: true
+          VALIDATE_HTML_PRETTIER: true
+          VALIDATE_JAVASCRIPT_PRETTIER: true
+          VALIDATE_JSX_PRETTIER: true
+          VALIDATE_MARKDOWN_PRETTIER: true
+          VALIDATE_TSX: true
+          VALIDATE_TYPESCRIPT_PRETTIER: true
+          VALIDATE_YAML: true
+          YAML_CONFIG_FILE: \${{ inputs.yaml-config }}
+
+      - uses: crazy-max/ghaction-import-gpg@e89d40939c28e39f97cf32126055eeae86ba74ec # v6
+        name: Import GPG Key
+        # Conditions mirror auto-commit exactly — no point importing GPG if the
+        # commit step will be skipped (fork PR, default branch, or secret unset).
+        if: >
+          inputs.enable-auto-commit == true &&
+          github.event.pull_request != null &&
+          github.event.pull_request.head.repo.full_name == github.repository &&
+          github.ref_name != github.event.repository.default_branch &&
+          secrets.SUPER_LINTER_GPG_PRIVATE_KEY != ''
+        with:
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+          GPG_PRIVATE_KEY: \${{ secrets.SUPER_LINTER_GPG_PRIVATE_KEY }}
+          PASSPHRASE: \${{ secrets.SUPER_LINTER_GPG_PASSPHRASE }}
+
+      - uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5
+        name: Commit and push linting fixes
+        if: >
+          inputs.enable-auto-commit == true &&
+          github.event.pull_request != null &&
+          github.event.pull_request.head.repo.full_name == github.repository &&
+          github.ref_name != github.event.repository.default_branch &&
+          secrets.SUPER_LINTER_GPG_PRIVATE_KEY != ''
+        with:
+          branch: \${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
+          commit_message: "chore: fix linting issues"
+          commit_options: "--no-verify --signoff"
+          commit_user_name: super-linter
+          commit_user_email: super-linter@super-linter.dev
+`,
+	release: `\
+name: Release
+
+# Semantic-release with OIDC Trusted Publishing — no NPM_TOKEN required.
+# The calling repo must have a .releaserc.json that configures branches,
+# plugins, and any publish options. npm@11+ is installed to support OIDC.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      run-build:
+        description: Run \`pnpm build\` before releasing
+        type: boolean
+        required: false
+        default: true
+
+jobs:
+  release:
+    name: Semantic release
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    # Do not cancel in-progress releases — a partial release is worse than a slow one.
+    concurrency:
+      group: release-\${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+          token: \${{ github.token }}
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: npm install -g npm@11 sigstore
+        name: Upgrade npm for OIDC support
+        # sigstore is required by libnpmpublish/provenance.js at module parse
+        # time — before any config takes effect. Some npm 11.x builds stopped
+        # bundling it; installing it globally into the same prefix ensures it
+        # resolves regardless of npm version. (Discovered 2026-07-09.)
+
+      - run: pnpm build
+        name: Build
+        if: \${{ inputs.run-build == true }}
+
+      - run: npx semantic-release
+        name: Release
+        env:
+          GITHUB_TOKEN: \${{ github.token }}
+          NPM_CONFIG_PROVENANCE: true
+`,
+	review: `\
+name: Review
+
+# ReviewDog is the annotation layer — posts inline PR diff annotations.
+# Runs on pull_request only: inline annotations require PR context,
+# and branch protection ensures all changes go through PRs anyway.
+# super-linter (lint.yml) is the CI gate covering push + PR events.
+# Gitleaks and YAML are intentionally duplicated: super-linter gates
+# merges; ReviewDog surfaces exact line annotations in the PR diff.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+concurrency:
+  group: review-\${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  reviewdog:
+    name: Review PRs
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup
+        if: \${{ hashFiles('pnpm-lock.yaml') != '' }}
+        uses: theholocron/.github/.github/actions/setup@main
+
+      - name: Install ReviewDog
+        uses: reviewdog/action-setup@d8a7baabd7f3e8544ee4dbde3ee41d0011c3a93f # v1
+        with:
+          reviewdog_version: latest
+
+      # Detect which tools are relevant for this repo, excluding node_modules.
+      # hashFiles('**/*') recurses into node_modules/.pnpm and produces false
+      # positives for repos that don't own those file types.
+      # -print -quit stops find after the first match without a pipe, avoiding
+      # the SIGPIPE/pipefail exit-141 that find|head-1 triggers under
+      # GitHub Actions' default bash --noprofile --norc -e -o pipefail mode.
+      - name: Detect project features
+        id: detect
+        shell: bash
+        run: |
+          has() { find . -not -path '*/node_modules/*' -name "$1" -print -quit 2>/dev/null | grep -q .; }
+          has_ext() { find . -not -path '*/node_modules/*' -name "$1" -print -quit 2>/dev/null | grep -q .; }
+          { { has 'eslint.config.js' || has 'eslint.config.mjs' || has 'eslint.config.cjs' || \\
+              has 'eslint.config.ts' || has '.eslintrc' || has '.eslintrc.js' || \\
+              has '.eslintrc.cjs' || has '.eslintrc.json' || has '.eslintrc.yaml' || \\
+              has '.eslintrc.yml'; } && grep -qF '"eslint":' package.json 2>/dev/null; } && echo "eslint=true" >> $GITHUB_OUTPUT || echo "eslint=false" >> $GITHUB_OUTPUT
+          { has 'tsconfig.json' && grep -qF '"typescript":' package.json 2>/dev/null; } && echo "tsconfig=true" >> $GITHUB_OUTPUT || echo "tsconfig=false" >> $GITHUB_OUTPUT
+          has_ext '*.sh' && echo "shell=true" >> $GITHUB_OUTPUT || echo "shell=false" >> $GITHUB_OUTPUT
+          has 'Dockerfile' || has_ext '*.Dockerfile' || has 'Containerfile' && \\
+            echo "docker=true" >> $GITHUB_OUTPUT || echo "docker=false" >> $GITHUB_OUTPUT
+          has_ext '.env*' && echo "dotenv=true" >> $GITHUB_OUTPUT || echo "dotenv=false" >> $GITHUB_OUTPUT
+          has_ext '*.md' && echo "markdown=true" >> $GITHUB_OUTPUT || echo "markdown=false" >> $GITHUB_OUTPUT
+
+      #
+      # Always applicable
+      #
+
+      - name: Gitleaks (secrets)
+        uses: reviewdog/action-gitleaks@2b7b5685e3e3eecddab5d30cfa04f18123031421 # v1
+        with:
+          reporter: github-pr-check
+
+      - name: YamlLint
+        uses: reviewdog/action-yamllint@b5f7217d8c815ae374d1d55840d5e569d82f01f0 # v1
+        with:
+          reporter: github-pr-check
+          yamllint_flags: >-
+            \${{ hashFiles('yamllint.config.yml') != ''
+                && format('-c {0}/yamllint.config.yml {0}', github.workspace)
+                || github.workspace }}
+
+      - name: ActionLint (GitHub Actions)
+        if: \${{ hashFiles('.github/workflows/*.yml', '.github/workflows/*.yaml') != '' }}
+        uses: reviewdog/action-actionlint@6fb7acc99f4a1008869fa8a0f09cfca740837d9d # v1
+        with:
+          reporter: github-pr-check
+
+      #
+      # TypeScript / JavaScript
+      #
+
+      - name: ESLint
+        if: steps.detect.outputs.eslint == 'true'
+        uses: reviewdog/action-eslint@556a3fdaf8b4201d4d74d406013386aa4f7dab96 # v1.34.0
+        with:
+          reporter: github-pr-check
+          eslint_flags: .
+
+      - name: TypeScript
+        if: steps.detect.outputs.tsconfig == 'true'
+        uses: EPMatt/reviewdog-action-tsc@63d923a3c5b4497671940b8874f58a404e2351b5 # v1
+        with:
+          reporter: github-pr-check
+
+      #
+      # Shell
+      #
+
+      - name: ShellCheck
+        if: steps.detect.outputs.shell == 'true'
+        uses: reviewdog/action-shellcheck@4c07458293ac342d477251099501a718ae5ef86e # v1
+        with:
+          reporter: github-pr-check
+          fail_level: none
+
+      #
+      # Docker
+      #
+
+      - name: Hadolint
+        if: steps.detect.outputs.docker == 'true'
+        uses: reviewdog/action-hadolint@1b2cfa6ba72072ad35158d7ff3aa49bbdc03506d # v1
+        with:
+          reporter: github-pr-check
+          fail_level: none
+
+      #
+      # Environment files
+      #
+
+      - name: dotenv-linter
+        if: steps.detect.outputs.dotenv == 'true'
+        uses: dotenv-linter/action-dotenv-linter@21287e2624aaf2dc8da5dd8ccfe8e49c63501116 # v2
+        with:
+          reporter: github-code-suggestions
+
+      #
+      # Documentation
+      #
+
+      - name: Alex (inclusive language)
+        if: steps.detect.outputs.markdown == 'true'
+        uses: reviewdog/action-alex@347481655add010a2ae302df34b57c9bcfa0d6e4 # v1
+        with:
+          reporter: github-pr-check
+`,
+	stale: `\
+name: Stale
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      days-before-stale:
+        description: Days of inactivity before an issue is marked stale
+        type: number
+        required: false
+        default: 30
+      days-before-close:
+        description: Days of inactivity after stale label before closing
+        type: number
+        required: false
+        default: 5
+
+jobs:
+  stale:
+    name: Mark stale issues and pull requests
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9
+        name: Run Stale
+        with:
+          close-issue-message: >
+            This issue was closed because it has been stalled for
+            \${{ inputs.days-before-close }} days with no activity.
+          days-before-close: \${{ inputs.days-before-close }}
+          days-before-stale: \${{ inputs.days-before-stale }}
+          exempt-all-pr-milestones: true
+          stale-issue-label: wontfix
+          stale-issue-message: >
+            This issue is stale because it has been open \${{ inputs.days-before-stale }}
+            days with no activity. Remove the stale label or comment, or this will be
+            closed in \${{ inputs.days-before-close }} days.
+          stale-pr-label: wontfix
+          stale-pr-message: >
+            This PR is stale because it has been open \${{ inputs.days-before-stale }}
+            days with no activity. Remove the stale label or comment, or this will be
+            closed in \${{ inputs.days-before-close }} days.
+`,
+	test: `\
+name: Test
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+
+jobs:
+  unit:
+    name: Run tests and collect coverage
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+        with:
+          fetch-depth: 0
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm test -- --coverage
+        name: Run tests with coverage
+
+      - uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4
+        name: Upload results to Codecov
+        with:
+          token: \${{ secrets.CODECOV_TOKEN }}
+`,
+	"sync-github": `\
+name: Sync GitHub Templates
+
+# Builds the holocron CLI from source and pushes updated workflow templates
+# and composite actions to downstream .github repos. Runs whenever the
+# template source files change on main or alpha.
+#
+# Secrets required:
+#   SYNC_TOKEN — fine-grained PAT or GitHub App token with Contents write
+#                access to the primary and secondary repos.
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+    inputs:
+      primary-repo:
+        description: >
+          Primary .github repo — receives composite actions, reusable workflows,
+          and thin-caller templates. Requires a PR (branch protection assumed).
+        type: string
+        required: false
+        default: theholocron/.github
+      secondary-repos:
+        description: >
+          Space-separated list of secondary repos (reusable workflows + thin
+          callers only, no composite actions). Pushed directly to main.
+        type: string
+        required: false
+        default: ""
+      sync-branch:
+        description: Branch name used for the primary-repo PR
+        type: string
+        required: false
+        default: chore/sync-templates
+    secrets:
+      SYNC_TOKEN:
+        required: true
+
+jobs:
+  sync:
+    name: Sync templates
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm build
+        name: Build CLI
+
+      - name: Validate generated workflows
+        run: |
+          node packages/cli/dist/cli.mjs sync-github \\
+            --repo "$PRIMARY_REPO" \\
+            --output-dir /tmp/sync-validate
+          curl -fsSL https://github.com/rhysd/actionlint/releases/download/v1.7.7/actionlint_1.7.7_linux_amd64.tar.gz \\
+            | tar -xz -C /tmp actionlint
+          /tmp/actionlint /tmp/sync-validate/.github/workflows/*.yml
+        env:
+          PRIMARY_REPO: \${{ inputs.primary-repo }}
+
+      - name: Sync primary repo (PR)
+        run: >
+          node packages/cli/dist/cli.mjs sync-github
+          --repo "$PRIMARY_REPO"
+          --branch "$SYNC_BRANCH"
+          --pr
+        env:
+          GITHUB_TOKEN: \${{ secrets.SYNC_TOKEN }}
+          PRIMARY_REPO: \${{ inputs.primary-repo }}
+          SYNC_BRANCH: \${{ inputs.sync-branch }}
+
+      - name: Sync secondary repos (direct push)
+        if: \${{ inputs.secondary-repos != '' }}
+        run: |
+          for repo in $SECONDARY_REPOS; do
+            node packages/cli/dist/cli.mjs sync-github --repo "$repo"
+          done
+        env:
+          GITHUB_TOKEN: \${{ secrets.SYNC_TOKEN }}
+          SECONDARY_REPOS: \${{ inputs.secondary-repos }}
+`,
+	typecheck: `\
+name: Typecheck
+
+on: # yamllint disable-line rule:truthy
+  workflow_call:
+
+jobs:
+  typecheck:
+    name: tsc --noEmit
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        name: Checkout repository
+
+      - uses: theholocron/.github/.github/actions/setup@main
+        name: Setup
+
+      - run: pnpm typecheck
+        name: Type check
+`
+};
+const WORKFLOW_TEMPLATE_PROPERTIES = { "sync-github": JSON.stringify({
+	name: "Sync GitHub Templates",
+	description: "Sync workflow templates and composite actions from the holocron CLI.",
+	iconName: "octicon sync"
+}, null, 2) };
+//#endregion
+//#region src/commands/setup-workflows.ts
+/**
+* Thin workflow wrapper templates for `holocron setup`.
+*
+* Each entry is a complete `.github/workflows/<name>.yml` that delegates
+* to the corresponding reusable `ci-<name>.yml` in `theholocron/.github`.
+* Files are overwritten on each setup run — they are generated artifacts.
+*/
+const WORKFLOW_REPO = "theholocron/.github";
+const WORKFLOW_REF = "main";
+function ref(name) {
+	return `${WORKFLOW_REPO}/.github/workflows/${name}.yml@${WORKFLOW_REF}`;
+}
+/** Header prepended when holocron setup writes a thin caller to a repo. */
+function workflowHeader() {
+	return [
+		`# AUTO-GENERATED — do not edit directly.`,
+		`# Source:  theholocron/holocron · packages/cli/src/commands/setup-workflows.ts`,
+		`# Synced:  ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`# Tool:    holocron setup`,
+		`# Changes: run \`holocron setup\` to regenerate.`,
+		``
+	].join("\n");
+}
+const WORKFLOW_TEMPLATES = {
+	lint: `\
+name: Lint
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: lint-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  statuses: write
+
+jobs:
+  lint:
+    name: Lint
+    uses: ${ref("lint")}
+    secrets: inherit
+    with:
+      enable-auto-commit: true
+`,
+	test: `\
+name: Test
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: test-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    uses: ${ref("test")}
+    secrets: inherit
+`,
+	typecheck: `\
+name: Typecheck
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+concurrency:
+  group: typecheck-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Typecheck
+    uses: ${ref("typecheck")}
+    secrets: inherit
+`,
+	codeql: `\
+name: CodeQL
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "0 0 * * 1"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    uses: ${ref("codeql")}
+    secrets: inherit
+`,
+	review: `\
+name: Review
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+concurrency:
+  group: review-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  review:
+    name: Review
+    uses: ${ref("review")}
+    secrets: inherit
+`,
+	release: `\
+name: Release
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+      - alpha
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    uses: ${ref("release")}
+    secrets: inherit
+`,
+	stale: `\
+name: Stale
+
+on: # yamllint disable-line rule:truthy
+  schedule:
+    - cron: "30 1 * * *"
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    uses: ${ref("stale")}
+    secrets: inherit
+`,
+	greetings: `\
+name: Greetings
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+  issues:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  greetings:
+    uses: ${ref("greetings")}
+    secrets: inherit
+`,
+	dependencies: `\
+name: Dependencies
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependencies:
+    uses: ${ref("dependencies")}
+    secrets: inherit
+`,
+	"bookkeeping-pr": `\
+name: PR Bookkeeping
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+    types:
+      - opened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  bookkeeping:
+    uses: ${ref("bookkeeping-pr")}
+    secrets: inherit
+`,
+	audit: `\
+name: Audit
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    uses: ${ref("audit")}
+    secrets: inherit
+`,
+	"sync-github": `\
+name: Sync GitHub Templates
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches: [main, alpha]
+    paths:
+      - packages/cli/src/templates/index.ts
+      - packages/cli/src/commands/setup-workflows.ts
+
+concurrency:
+  group: sync-github-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    name: Sync
+    uses: ${ref("sync-github")}
+    with:
+      secondary-repos: theholocron/.github-private
+    secrets:
+      SYNC_TOKEN: \${{ secrets.SYNC_TOKEN }}
+`
+};
+const KNOWN_WORKFLOWS = new Set(Object.keys(WORKFLOW_TEMPLATES));
+/**
+* Generate the thin caller content for a workflow, optionally injecting
+* `with:` inputs before `secrets: inherit` in the jobs block.
+*/
+function generateThinCallerContent(name, withOverrides) {
+	const base = WORKFLOW_TEMPLATES[name];
+	if (!base) return "";
+	if (!withOverrides || Object.keys(withOverrides).length === 0) return base;
+	const withBlock = Object.entries(withOverrides).map(([k, v]) => `      ${k}: ${v === true ? "true" : v === false ? "false" : String(v)}`).join("\n");
+	return base.replace(/ {4}secrets: inherit\n$/, `    with:\n${withBlock}\n    secrets: inherit\n`);
+}
+//#endregion
+//#region src/commands/sync-github.ts
+const DEFAULT_REPO = "theholocron/.github";
+const API_BASE = "https://api.github.com";
+function reusableHeader(source) {
+	return [
+		`# AUTO-GENERATED — do not edit in theholocron/.github directly.`,
+		`# Source:  theholocron/holocron · ${source}`,
+		`# Synced:  ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`# Tool:    holocron sync-github`,
+		`# Changes: edit source in theholocron/holocron and push to alpha or main.`,
+		``
+	].join("\n");
+}
+function thinCallerHeader() {
+	return [
+		`# AUTO-GENERATED — do not edit in theholocron/.github directly.`,
+		`# Source:  theholocron/holocron · packages/cli/src/commands/setup-workflows.ts`,
+		`# Synced:  ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`# Tool:    holocron sync-github`,
+		`# Changes: edit setup-workflows.ts in theholocron/holocron and push.`,
+		``
+	].join("\n");
+}
+function buildBatch(repo, allowedWorkflows) {
+	const files = [];
+	const isPrimaryGithubRepo = repo === DEFAULT_REPO;
+	if (isPrimaryGithubRepo) for (const [name, content] of Object.entries(ACTIONS)) files.push({
+		path: `.github/actions/${name}.yml`,
+		content: reusableHeader(`packages/cli/src/templates/index.ts`) + content
+	});
+	for (const [name, content] of Object.entries(REUSABLE_WORKFLOWS)) {
+		if (allowedWorkflows && !allowedWorkflows.has(name)) continue;
+		files.push({
+			path: `.github/workflows/${name}.yml`,
+			content: reusableHeader(`packages/cli/src/templates/index.ts`) + content
+		});
+	}
+	if (isPrimaryGithubRepo) for (const [name, content] of Object.entries(WORKFLOW_TEMPLATES)) {
+		files.push({
+			path: `workflow-templates/${name}.yml`,
+			content: thinCallerHeader() + content
+		});
+		const props = WORKFLOW_TEMPLATE_PROPERTIES[name];
+		if (props) files.push({
+			path: `workflow-templates/${name}.properties.json`,
+			content: props
+		});
+	}
+	return files;
+}
+/** Git blob SHA: sha1("blob {len}\0{content}") — used to detect unchanged files. */
+function gitBlobSha(content) {
+	const buf = Buffer.from(content, "utf8");
+	return createHash("sha1").update(`blob ${buf.length}\0`).update(buf).digest("hex");
+}
+async function runSyncGithub(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const repo = input.repo ?? DEFAULT_REPO;
+	const [owner, repoName] = repo.split("/");
+	const { token, dryRun = false, branch, createPr = false } = input;
+	const message = input.message ?? `chore: sync from theholocron/holocron`;
+	const fetchFn = input.fetch ?? globalThis.fetch;
+	const headers = {
+		Authorization: `Bearer ${token}`,
+		Accept: "application/vnd.github+json",
+		"Content-Type": "application/json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+	print(`holocron sync-github${dryRun ? " (dry-run)" : ""}`);
+	print(`  repo:   ${repo}`);
+	if (branch) print(`  branch: ${branch}`);
+	print("");
+	if (input.outputDir) {
+		const batch = buildBatch(repo);
+		for (const file of batch) {
+			const dest = join(input.outputDir, file.path);
+			mkdirSync(dirname(dest), { recursive: true });
+			writeFileSync(dest, file.content, "utf8");
+		}
+		print(`  ${batch.length} files written to ${input.outputDir}`);
+		return {
+			status: "ok",
+			created: batch.length,
+			updated: 0,
+			unchanged: 0
+		};
+	}
+	let targetBranch = branch;
+	if (!targetBranch) {
+		const repoRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}`, { headers });
+		if (!repoRes.ok) {
+			const msg = "failed to fetch repo metadata";
+			print(`  ✗ ${msg}`);
+			return {
+				status: "fail",
+				created: 0,
+				updated: 0,
+				unchanged: 0,
+				message: msg
+			};
+		}
+		targetBranch = (await repoRes.json()).default_branch;
+	}
+	const refRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/ref/heads/${targetBranch}`, { headers });
+	if (!refRes.ok) {
+		const msg = `Branch ${targetBranch} not found`;
+		print(`  ✗ ${msg}`);
+		return {
+			status: "fail",
+			created: 0,
+			updated: 0,
+			unchanged: 0,
+			message: msg
+		};
+	}
+	const { object: { sha: headSha } } = await refRes.json();
+	const { tree: { sha: baseTreeSha } } = await (await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/commits/${headSha}`, { headers })).json();
+	const { tree: existingTree } = await (await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/trees/${baseTreeSha}?recursive=1`, { headers })).json();
+	const existingBlobs = new Map(existingTree.filter((i) => i.type === "blob").map((i) => [i.path, i.sha]));
+	let allowedWorkflows;
+	if (repo !== DEFAULT_REPO) try {
+		const configRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/contents/holocron.config.json`, { headers });
+		if (configRes.ok) {
+			const configData = await configRes.json();
+			const workflows = JSON.parse(Buffer.from(configData.content.replace(/\n/g, ""), "base64").toString("utf8"))?.project?.workflows ?? [];
+			if (workflows.length > 0) allowedWorkflows = new Set(workflows.map((w) => typeof w === "string" ? w : w.name));
+		}
+	} catch {}
+	const batch = buildBatch(repo, allowedWorkflows);
+	let created = 0;
+	let updated = 0;
+	let unchanged = 0;
+	const changedFiles = [];
+	for (const file of batch) {
+		const localSha = gitBlobSha(file.content);
+		const existingSha = existingBlobs.get(file.path);
+		if (existingSha === localSha) {
+			print(`  · unchanged  ${file.path}`);
+			unchanged++;
+		} else if (existingSha) {
+			print(`  ${dryRun ? "~" : "✓"} updated  ${file.path}`);
+			updated++;
+			if (!dryRun) changedFiles.push(file);
+		} else {
+			print(`  ${dryRun ? "~" : "✓"} created  ${file.path}`);
+			created++;
+			if (!dryRun) changedFiles.push(file);
+		}
+	}
+	print("");
+	print(`  ${created} created, ${updated} updated, ${unchanged} unchanged`);
+	if (dryRun || changedFiles.length === 0) return {
+		status: dryRun ? "dry-run" : "ok",
+		created,
+		updated,
+		unchanged
+	};
+	const treeEntries = [];
+	for (const file of changedFiles) {
+		const blobRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/blobs`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				content: file.content,
+				encoding: "utf-8"
+			})
+		});
+		if (!blobRes.ok) {
+			const err = await blobRes.json();
+			const msg = `failed to create blob for ${file.path}: ${err.message ?? blobRes.status}`;
+			print(`  ✗ ${msg}`);
+			return {
+				status: "fail",
+				created,
+				updated,
+				unchanged,
+				message: msg
+			};
+		}
+		const { sha: blobSha } = await blobRes.json();
+		treeEntries.push({
+			path: file.path,
+			mode: "100644",
+			type: "blob",
+			sha: blobSha
+		});
+	}
+	const newTreeRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/trees`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			base_tree: baseTreeSha,
+			tree: treeEntries
+		})
+	});
+	if (!newTreeRes.ok) {
+		const msg = `failed to create tree: ${(await newTreeRes.json()).message ?? newTreeRes.status}`;
+		print(`  ✗ ${msg}`);
+		return {
+			status: "fail",
+			created,
+			updated,
+			unchanged,
+			message: msg
+		};
+	}
+	const { sha: newTreeSha } = await newTreeRes.json();
+	const newCommitRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/commits`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			message,
+			tree: newTreeSha,
+			parents: [headSha]
+		})
+	});
+	if (!newCommitRes.ok) {
+		const msg = `failed to create commit: ${(await newCommitRes.json()).message ?? newCommitRes.status}`;
+		print(`  ✗ ${msg}`);
+		return {
+			status: "fail",
+			created,
+			updated,
+			unchanged,
+			message: msg
+		};
+	}
+	const { sha: newCommitSha } = await newCommitRes.json();
+	const updateRefRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/git/refs/heads/${targetBranch}`, {
+		method: "PATCH",
+		headers,
+		body: JSON.stringify({ sha: newCommitSha })
+	});
+	if (!updateRefRes.ok) {
+		const msg = `failed to update ref: ${(await updateRefRes.json()).message ?? updateRefRes.status}`;
+		print(`  ✗ ${msg}`);
+		return {
+			status: "fail",
+			created,
+			updated,
+			unchanged,
+			message: msg
+		};
+	}
+	let prUrl;
+	if (branch && createPr && !dryRun) {
+		const prRes = await fetchFn(`${API_BASE}/repos/${owner}/${repoName}/pulls`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				title: message,
+				head: branch,
+				base: "main",
+				body: "Auto-generated by `holocron sync-github`. Review and merge to apply template updates."
+			})
+		});
+		if (prRes.ok) {
+			prUrl = (await prRes.json()).html_url;
+			print(`  → PR opened: ${prUrl}`);
+		} else {
+			const err = await prRes.json();
+			if (err.errors?.some((e) => e.message.includes("already exists"))) print(`  → PR already open for ${branch} — branch updated, ready to merge`);
+			else print(`  ⚠ PR creation failed: ${err.message ?? prRes.status}`);
+		}
+	}
+	return {
+		status: "ok",
+		created,
+		updated,
+		unchanged,
+		prUrl
+	};
+}
+//#endregion
+//#region src/commands/npm-publish-initial.ts
+/**
+* `holocron npm publish-initial` — bottles up the chicken-and-egg
+* bootstrap that every new npm-published holocron monorepo hits.
+*
+* npm requires a package to exist before Trusted Publishing can be
+* configured on it. So the first publish has to happen outside the
+* OIDC flow — using either a browser-auth session (`npm login
+* --auth-type=web`) or an ephemeral automation token. This command
+* runs the publish step + tells you exactly what to do next.
+*
+* Workflow:
+*
+*   $ npm login --auth-type=web          # one-time, browser-based
+*   $ pnpm install --frozen-lockfile
+*   $ pnpm build
+*   $ pnpm exec tsx packages/cli/src/cli.ts npm publish-initial
+*
+* The command itself only handles the publish step + the post-publish
+* Trusted Publisher setup reminder. `pnpm install` + `pnpm build`
+* stay outside the command (no pnpm-inside-pnpm).
+*
+* If `NPM_TOKEN` is detected in env, the command prints a final
+* "revoke this token at <url>" reminder — same pattern as `rando vc
+* setup` for the ephemeral GH admin PAT.
+*/
+const PUBLISHABLE_PACKAGES = [
+	"@theholocron/cli",
+	"@theholocron/holocron-plugin-github",
+	"@theholocron/holocron-plugin-vercel",
+	"@theholocron/holocron-plugin-neon",
+	"@theholocron/holocron-plugin-clerk",
+	"@theholocron/holocron-plugin-1password",
+	"@theholocron/holocron-plugin-postman"
+];
+async function runNpmPublishInitial(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const cwd = input.cwd ?? process.cwd();
+	const tag = input.tag ?? "alpha";
+	const dryRun = input.dryRun ?? false;
+	const otp = input.otp;
+	const env = input.env ?? process.env;
+	const exec = input.exec ?? defaultExec;
+	const publishArgs = [
+		"-r",
+		"--filter=./packages/*",
+		"--filter=!@theholocron/cli-utils",
+		"publish",
+		"--access",
+		"public",
+		"--no-git-checks",
+		"--tag",
+		tag,
+		...otp ? ["--otp", otp] : []
+	];
+	print(`Holocron npm publish-initial${dryRun ? " (dry-run)" : ""}`);
+	print(`  cwd: ${cwd}`);
+	print(`  tag: ${tag}`);
+	if (otp) print(`  otp: <${otp.length} chars>`);
+	print("");
+	print("  → verifying npm auth (`npm whoami`)…");
+	const whoami = await exec("npm", ["whoami"], { cwd });
+	if (whoami.exitCode !== 0) {
+		const message = "npm is not authenticated. Run `npm login --auth-type=web` (browser flow, no token stored) or `npm login`, then re-run this command.";
+		print(`  ✗ ${message}`);
+		return {
+			status: "fail",
+			message,
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
+	if (dryRun) {
+		print("");
+		print("  … (dry-run) skipping actual publish");
+		print(`    would run: pnpm ${publishArgs.join(" ")}`);
+		printNextSteps$1(print, env);
+		return {
+			status: "dry-run",
+			message: "dry-run — no publish executed",
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print("");
+	print("  → publishing all public @theholocron/* packages…");
+	const publish = await exec("pnpm", publishArgs, { cwd });
+	if (publish.exitCode !== 0) {
+		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
+		print(`  ✗ ${message}`);
+		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
+			print("");
+			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
+			print(`    pnpm exec tsx packages/cli/src/cli.ts npm publish-initial --otp <6-digit-code>`);
+		}
+		return {
+			status: "fail",
+			message,
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print("    ✓ publish complete");
+	printNextSteps$1(print, env);
+	return {
+		status: "ok",
+		packageNames: PUBLISHABLE_PACKAGES
+	};
+}
+function printNextSteps$1(print, env) {
+	print("");
+	print("  → next: configure Trusted Publisher for each package on npm:");
+	for (const name of PUBLISHABLE_PACKAGES) print(`    https://www.npmjs.com/package/${name}/access`);
+	print("    Publisher: GitHub Actions   Org: theholocron   Repo: holocron   Workflow: release.yml");
+	if (env.NPM_TOKEN) {
+		print("");
+		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
+		print("    https://www.npmjs.com/settings/~/tokens");
+	}
+}
+const defaultExec = async (cmd, args, opts) => {
+	const result = spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		exitCode: result.status ?? -1,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? ""
+	};
+};
+//#endregion
+//#region src/commands/plugin-create/template-inputs.ts
+/** Derive the standard defaults from a slug + vendor name. */
+function deriveDefaults(input) {
+	const vendorUpper = input.slug.toUpperCase().replace(/-/g, "_");
+	const capability = input.capability;
+	return {
+		vendorUpper,
+		capabilityClass: `${input.vendorName}${capability.charAt(0).toUpperCase() + capability.slice(1)}`,
+		tokenEnv: `HOLOCRON_${vendorUpper}_TOKEN`,
+		transport: "rest"
+	};
+}
+//#endregion
+//#region src/commands/plugin-create/templates/auth.ts
+function render$17(inputs) {
+	return `/**
+ * Token resolution for the ${inputs.vendorName} plugin.
+ *
+ * Resolution order (matches the standard 4-step precedence set by
+ * \`.notes/tech-auth-bootstrap.spec.md\`):
+ *   1. explicit \`cliToken\` argument (from \`--token\` flag)
+ *   2. ${inputs.tokenEnv} env var (preferred — explicit intent)
+ *   3. ${inputs.vendorEnv} env var (vendor-native)
+ *   4. keyring (com.theholocron.cli / "${inputs.slug}")
+ *   5. AuthError naming all four options + the bootstrap hint
+ */
+
+import { getToken as getKeyringToken } from "@theholocron/cli";
+
+export class AuthError extends Error {
+	override name = "AuthError";
+}
+
+export interface ResolveTokenInput {
+	/** From \`--token\` CLI flag. */
+	cliToken?: string;
+	/** Env vars; passed in for testability. Defaults to \`process.env\`. */
+	env?: NodeJS.ProcessEnv;
+	/** Keyring lookup fn; passed in for testability. Defaults to \`getToken(provider)\`. */
+	keyring?: (provider: string) => string | null;
+}
+
+export function resolveToken(input: ResolveTokenInput = {}): string {
+	const env = input.env ?? process.env;
+	const keyring = input.keyring ?? getKeyringToken;
+	// Bracket access so numeric-prefixed slugs (e.g., env.HOLOCRON_1PASSWORD_TOKEN
+	// which is invalid JS) still produce syntactically valid code.
+	const token =
+		input.cliToken || env["${inputs.tokenEnv}"] || env["${inputs.vendorEnv}"] || keyring("${inputs.slug}");
+	if (!token) {
+		throw new AuthError(
+			"no ${inputs.vendorName} token found. Pass --token <TOKEN>, set ${inputs.tokenEnv} / ${inputs.vendorEnv}, " +
+				"or run: holocron auth set ${inputs.slug} <TOKEN>"
+		);
+	}
+	return token;
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/auth-test.ts
+function render$16(inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { AuthError, resolveToken } from "../auth.js";
+
+const noKeyring = () => null;
+
+describe("resolveToken", () => {
+	it("prefers --token over env vars + keyring", () => {
+		expect(
+			resolveToken({
+				cliToken: "flag",
+				env: { ${inputs.tokenEnv}: "hlc", ${inputs.vendorEnv}: "vendor" },
+				keyring: () => "kr",
+			})
+		).toBe("flag");
+	});
+
+	it("prefers ${inputs.tokenEnv} over ${inputs.vendorEnv}", () => {
+		expect(
+			resolveToken({
+				env: { ${inputs.tokenEnv}: "hlc", ${inputs.vendorEnv}: "vendor" },
+				keyring: noKeyring,
+			})
+		).toBe("hlc");
+	});
+
+	it("falls back to ${inputs.vendorEnv} when ${inputs.tokenEnv} is unset", () => {
+		expect(resolveToken({ env: { ${inputs.vendorEnv}: "vendor" }, keyring: noKeyring })).toBe("vendor");
+	});
+
+	it("falls back to keyring when env vars are unset", () => {
+		expect(resolveToken({ env: {}, keyring: (p) => (p === "${inputs.slug}" ? "kr" : null) })).toBe("kr");
+	});
+
+	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}/);
+		}
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/capability.ts
+function render$15(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
+	return `/**
+ * \`${inputs.capability}\` capability for ${inputs.vendorName}.
+ *
+ * Methods are STUBS — implement them against ${inputs.vendorName}'s
+ * REST API per the \`${capabilityInterface}\` interface contract in
+ * \`@theholocron/cli\`.
+ *
+ * TODO once you've stubbed the interface methods, restore the type
+ * import + \`implements\` clause:
+ *   import type { ${capabilityInterface} } from "@theholocron/cli";
+ *   export class ${inputs.capabilityClass} implements ${capabilityInterface} { ... }
+ */
+
+import type { ${clientClass} } from "../rest.js";
+
+export class ${inputs.capabilityClass} {
+	readonly key = "${inputs.capability}" as const;
+	readonly providerName = "${inputs.slug}";
+
+	constructor(private readonly rest: ${clientClass}) {}
+
+	// TODO: implement the ${capabilityInterface} interface methods
+	// (see \`packages/cli/src/capabilities/index.ts\`). Each method
+	// should hit a specific ${inputs.vendorName} REST endpoint via
+	// \`this.rest.request(...)\`. Once methods are stubbed, add
+	// \`implements ${capabilityInterface}\` to the class declaration
+	// above and remove the \`as unknown as\` cast in src/index.ts.
+}
+`;
+}
+//#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";
+
+import { ${inputs.capabilityClass} } from "../capabilities/${inputs.capability}.js";
+import { ${clientClass} } 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 });
+	return new ${inputs.capabilityClass}(rest);
+}
+
+describe("${inputs.capabilityClass}", () => {
+	it("constructs with a REST client", () => {
+		makeCapability();
+	});
+
+	// TODO: implement one test per ${inputs.capability} capability method
+	// as you fill in the class stubs. See other plugins for reference
+	// patterns:
+	//   - REST behaviors (URL / method / body / query) via \`stub.calls\`
+	//   - Error paths via \`stubFetch([{ status: 4xx, body: {...} }])\`
+	//   - Idempotency (409 handling for ensure* methods, if applicable)
+	it.todo("implement per-method tests");
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/eslint-config.ts
+function render$13(_inputs) {
+	return `import root from "../../eslint.config.js";
+
+export default [
+	...root,
+	{
+		ignores: ["dist/**", "coverage/**"],
+	},
+];
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/helpers.ts
+function render$12(_inputs) {
+	return `import { vi, type Mock } from "vitest";
+
+export interface FetchCall {
+	url: string;
+	method: string;
+	headers: Record<string, string>;
+	body: unknown;
+}
+
+export interface FetchStub {
+	fetch: typeof fetch;
+	calls: FetchCall[];
+	mock: Mock;
+}
+
+export function stubFetch(responses: Array<{ status?: number; body?: unknown; text?: string }>): FetchStub {
+	const calls: FetchCall[] = [];
+	let i = 0;
+	const mock = vi.fn(async (input: string | URL, init?: RequestInit) => {
+		const url = typeof input === "string" ? input : input.toString();
+		const body = typeof init?.body === "string" ? safeJsonParse(init.body) : (init?.body ?? null);
+		calls.push({
+			url,
+			method: (init?.method ?? "GET").toUpperCase(),
+			headers: (init?.headers as Record<string, string>) ?? {},
+			body,
+		});
+		const next = responses[i++] ?? { status: 200, body: {} };
+		const status = next.status ?? 200;
+		if (status === 204 || status === 205 || status === 304) {
+			return new Response(null, { status });
+		}
+		const text = next.text ?? (typeof next.body === "string" ? next.body : JSON.stringify(next.body ?? {}));
+		return new Response(text, { status });
+	});
+	return { fetch: mock as unknown as typeof fetch, calls, mock };
+}
+
+function safeJsonParse(s: string): unknown {
+	try {
+		return JSON.parse(s);
+	} catch {
+		return s;
+	}
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/index-test.ts
+function render$11(inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { AUTH_HINT, createPlugin } from "../index.js";
+import { stubFetch } from "./helpers.js";
+
+describe("createPlugin", () => {
+	it("wires the ${inputs.capability} capability against the given fetch + token", () => {
+		const stub = stubFetch([]);
+		const plugin = createPlugin({
+			cliToken: "test-token",
+			fetch: stub.fetch,
+		});
+		expect(plugin.name).toBe("@theholocron/holocron-plugin-${inputs.slug}");
+		expect(typeof plugin.capabilities.${inputs.capability}).toBe("function");
+	});
+});
+
+describe("AUTH_HINT", () => {
+	it("mentions the holocron auth set command", () => {
+		expect(AUTH_HINT).toMatch(/holocron auth set ${inputs.slug}/);
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/package-json.ts
+function render$10(inputs) {
+	return `{
+  "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\`.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-${inputs.slug}#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-${inputs.slug}"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "workspace:*"
+  },
+  "devDependencies": {
+    "@theholocron/cli": "workspace:*",
+    "@theholocron/tsconfig": "catalog:",
+    "@tsconfig/node-lts": "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"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/plugin-index.ts
+function render$9(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	const capabilityInterface = inputs.capability.charAt(0).toUpperCase() + inputs.capability.slice(1);
+	return `/**
+ * \`@theholocron/holocron-plugin-${inputs.slug}\` — entrypoint.
+ *
+ * Implements the \`${inputs.capability}\` capability against ${inputs.vendorName}'s
+ * REST API. Also exports \`verifyToken\` + \`AUTH_HINT\` for
+ * \`holocron auth\`. See README for auth + config docs.
+ *
+ * TODO: once you fill in the ${inputs.capabilityClass} methods and add
+ * \`implements ${capabilityInterface}\` to the class, add the type import:
+ *   import type { ${capabilityInterface} } from "@theholocron/cli";
+ * and set \`: ${capabilityInterface}\` as the factory return type below.
+ */
+
+import { resolveToken, type ResolveTokenInput } from "./auth.js";
+import { ${inputs.capabilityClass} } from "./capabilities/${inputs.capability}.js";
+import { ${clientClass} } from "./rest.js";
+
+export interface ${inputs.vendorName}PluginOptions extends ResolveTokenInput {
+	/** Override base URL for tests. */
+	baseUrl?: string;
+	/** Override \`fetch\` for tests. */
+	fetch?: typeof fetch;
+}
+
+export interface PluginContext {
+	options: ${inputs.vendorName}PluginOptions;
+	rest: ${clientClass};
+}
+
+export function createContext(options: ${inputs.vendorName}PluginOptions): PluginContext {
+	const token = resolveToken(options);
+	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	if (options.baseUrl !== undefined) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== undefined) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new ${clientClass}(restOpts),
+	};
+}
+
+export function ${inputs.capability}(ctx: PluginContext) {
+	// Return type inferred at scaffold time — the class doesn't yet
+	// \`implements ${capabilityInterface}\`. Add the type import + the
+	// \`: ${capabilityInterface}\` annotation once methods are stubbed.
+	return new ${inputs.capabilityClass}(ctx.rest);
+}
+
+export function createPlugin(options: ${inputs.vendorName}PluginOptions) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-${inputs.slug}",
+		capabilities: {
+			${inputs.capability}: () => ${inputs.capability}(ctx),
+		},
+	};
+}
+
+/**
+ * One-line hint printed by \`holocron auth set ${inputs.slug}\` when no
+ * token is supplied or the supplied token is rejected. Edit this to
+ * point operators at the specific ${inputs.vendorName} docs path for
+ * generating a token.
+ */
+export const AUTH_HINT =
+	"generate a ${inputs.vendorName} API token, then run: holocron auth set ${inputs.slug} <TOKEN>";
+
+// ── Public re-exports ────────────────────────────────────────────────
+
+export * from "./auth.js";
+export { ${clientClass} } 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";
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/readme.ts
+function render$8(inputs) {
+	return `<!-- editorconfig-checker-disable-file -->
+
+# \`@theholocron/holocron-plugin-${inputs.slug}\`
+
+${inputs.vendorName} plugin for [Holocron](../cli). Implements the
+\`${inputs.capability}\` capability against [${inputs.vendorName}'s REST API](${inputs.baseUrl}),
+plus exports \`verifyToken\` + \`AUTH_HINT\` for use by \`holocron auth\`.
+
+## Install
+
+\`\`\`bash
+pnpm add -D @theholocron/holocron-plugin-${inputs.slug}@alpha
+\`\`\`
+
+## Auth
+
+Token resolution order (matches the standard 4-step precedence set by
+\`.notes/tech-auth-bootstrap.spec.md\`):
+
+1. \`--token <TOKEN>\` flag on the holocron invocation
+2. \`${inputs.tokenEnv}\` env var (preferred — explicit intent)
+3. \`${inputs.vendorEnv}\` env var (${inputs.vendorName}-native)
+4. **Keyring** — \`com.theholocron.cli\` service, account \`${inputs.slug}\`
+5. \`AuthError\` naming all four options + the bootstrap hint
+
+## Setup
+
+\`\`\`bash
+# Generate a ${inputs.vendorName} API token (see vendor docs), then:
+holocron auth set ${inputs.slug} <TOKEN>
+holocron auth check ${inputs.slug}    # verify
+\`\`\`
+
+## Config
+
+\`\`\`jsonc
+{
+	"providers": {
+		"${inputs.capability}": "${inputs.slug}",
+	},
+}
+\`\`\`
+
+Plugin options extend \`ResolveTokenInput\` — add whatever ${inputs.vendorName}-
+specific options you need here (project id, workspace slug, etc.) via
+the tuple form:
+
+\`\`\`jsonc
+{
+	"providers": {
+		"${inputs.capability}": ["${inputs.slug}", { "baseUrl": "${inputs.baseUrl}" }],
+	},
+}
+\`\`\`
+
+## What's implemented
+
+TODO: fill in as capability methods land.
+
+## Status
+
+**\`v2.0.0-alpha.1\`** — scaffolded via \`holocron plugin create\`.
+Not yet published; capability methods are stubs.
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/rest.ts
+function render$7(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `/**
+ * Thin REST wrapper around ${inputs.baseUrl}.
+ *
+ * Bearer auth, JSON-only bodies, transport-failure wrapping with
+ * \`status: 0\` so orchestrator soft-skip paths see a clear message
+ * instead of a generic \`TypeError: fetch failed\`.
+ */
+
+import { ProviderApiError } from "@theholocron/cli";
+
+export interface RestClientOptions {
+	token: string;
+	fetch?: typeof fetch;
+	baseUrl?: string;
+}
+
+export interface RequestOptions {
+	method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+	body?: unknown;
+	query?: Record<string, string>;
+	/** Treat this response as void even if 200 is returned. */
+	expectNoContent?: boolean;
+}
+
+export class ${clientClass} {
+	private readonly token: string;
+	private readonly fetchImpl: typeof fetch;
+	readonly baseUrl: string;
+
+	constructor(opts: RestClientOptions) {
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+		// Manual trailing-slash trim — CodeQL flags regex on library
+		// input as polynomial ReDoS. O(n) loop, no backtracking risk.
+		let url = opts.baseUrl ?? "${inputs.baseUrl}";
+		while (url.endsWith("/")) url = url.slice(0, -1);
+		this.baseUrl = url;
+	}
+
+	async request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+		const url = new URL(\`\${this.baseUrl}\${path.startsWith("/") ? path : "/" + path}\`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
+		const fullUrl = url.toString();
+
+		const headers: Record<string, string> = {
+			authorization: \`Bearer \${this.token}\`,
+			accept: "application/json",
+		};
+		const init: RequestInit = {
+			method: opts.method ?? "GET",
+			headers,
+		};
+		if (opts.body !== undefined) {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+
+		let res: Response;
+		try {
+			res = await this.fetchImpl(fullUrl, init);
+		} catch (err) {
+			const detail = err instanceof Error ? \`\${err.name}: \${err.message}\` : String(err);
+			throw new ProviderApiError(\`${inputs.vendorName} \${init.method} \${path} failed: \${detail}\`, 0, undefined);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(\`${inputs.vendorName} \${init.method} \${path} → \${res.status}\`, res.status, body);
+		}
+		if (opts.expectNoContent || res.status === 204) return undefined as T;
+		const text = await res.text();
+		if (!text) return undefined as T;
+		return JSON.parse(text) as T;
+	}
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/rest-test.ts
+function render$6(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `import { ProviderApiError } from "@theholocron/cli";
+import { describe, expect, it } from "vitest";
+
+import { ${clientClass} } from "../rest.js";
+import { stubFetch } from "./helpers.js";
+
+describe("${clientClass}", () => {
+	it("sends bearer + accept headers and returns the parsed body", async () => {
+		const stub = stubFetch([{ status: 200, body: { ok: true } }]);
+		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
+		const res = await client.request<{ ok: boolean }>("/me");
+		expect(res.ok).toBe(true);
+		expect(stub.calls[0]?.headers["authorization"]).toBe("Bearer t");
+		expect(stub.calls[0]?.headers["accept"]).toBe("application/json");
+	});
+
+	it("serializes body as JSON and sets content-type when present", async () => {
+		const stub = stubFetch([{ status: 200, body: {} }]);
+		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
+		await client.request<unknown>("/resource", { method: "POST", body: { name: "demo" } });
+		expect(stub.calls[0]?.method).toBe("POST");
+		expect(stub.calls[0]?.headers["content-type"]).toBe("application/json");
+		expect(stub.calls[0]?.body).toEqual({ name: "demo" });
+	});
+
+	it("returns undefined on 204", async () => {
+		const stub = stubFetch([{ status: 204 }]);
+		const client = new ${clientClass}({ token: "t", fetch: stub.fetch });
+		expect(await client.request<unknown>("/whatever")).toBeUndefined();
+	});
+
+	it("throws ProviderApiError with the HTTP status on non-2xx", async () => {
+		const stub = stubFetch([{ status: 401, body: { messages: ["invalid"] } }]);
+		const client = new ${clientClass}({ token: "bad", fetch: stub.fetch });
+		try {
+			await client.request<unknown>("/me");
+			throw new Error("should have thrown");
+		} catch (err) {
+			expect(err).toBeInstanceOf(ProviderApiError);
+			expect((err as ProviderApiError).status).toBe(401);
+		}
+	});
+
+	it("wraps transport-level failures with status 0", async () => {
+		const throwing: typeof fetch = async () => {
+			throw new TypeError("fetch failed");
+		};
+		const client = new ${clientClass}({ token: "t", fetch: throwing });
+		try {
+			await client.request<unknown>("/me");
+			throw new Error("should have thrown");
+		} catch (err) {
+			expect(err).toBeInstanceOf(ProviderApiError);
+			expect((err as ProviderApiError).status).toBe(0);
+		}
+	});
+
+	it("trims trailing slashes from the base URL", () => {
+		const client = new ${clientClass}({ token: "t", baseUrl: "${inputs.baseUrl}//" });
+		expect(client.baseUrl).toBe("${inputs.baseUrl}");
+	});
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/tsconfig-json.ts
+function render$5(inputs) {
+	return `{
+  "display": "Holocron Plugin: ${inputs.vendorName}",
+  "extends": "@tsconfig/node-lts/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./dist",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/tsdown-config.ts
+function render$4(_inputs) {
+	return `import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	entry: ["src/index.ts"],
+	format: "esm",
+	dts: true,
+	clean: true,
+	deps: { neverBundle: [/^@theholocron\\//] },
+});
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/validate-script.ts
+/**
+* Scaffolds `scripts/validate.mjs` — a smoke-test the operator runs
+* against a live vendor account to verify the plugin's REST endpoints,
+* auth, and response parsing all work in reality (the unit tests only
+* exercise stubbed HTTP responses). READ-ONLY BY DESIGN.
+*
+* Convention: every plugin ships this script + a matching `validate`
+* entry in `package.json`'s scripts block, so operators run
+* `pnpm --filter @theholocron/holocron-plugin-<slug> validate`.
+* Capability-specific args (project id, workspace, etc.) come from
+* positional command-line arguments; the plugin author fills in the
+* exact shape per their vendor.
+*
+* Includes a `hintFor(message)` helper the operator customizes with
+* vendor-specific "here's the likely fix" guidance for common error
+* shapes (401 / 403 / 404 / network / 5xx). Points users at docs and
+* setup steps rather than leaving them staring at a raw stack trace.
+*/
+function render$3(inputs) {
+	return `#!/usr/bin/env node
+/**
+ * Read-only smoke test for @theholocron/holocron-plugin-${inputs.slug} against
+ * a live ${inputs.vendorName} account.
+ *
+ * READ-ONLY BY DESIGN. Never calls write(), or bootstrap methods
+ * (\`ensureProject\`, \`ensureEnvironment\`, etc.). Any ERROR line means
+ * the plugin needs adjusting — the \`hintFor\` helper below points at
+ * the most likely fix per error shape.
+ *
+ * Auth: reads the ${inputs.vendorName} token from holocron's keyring —
+ * you must have run \`pnpm holocron auth set ${inputs.slug} <TOKEN>\` first.
+ *
+ * Usage:
+ *   pnpm --filter @theholocron/holocron-plugin-${inputs.slug} validate <arg1> [arg2] ...
+ *
+ * TODO: replace the positional args below with whatever your
+ * capability's methods need (e.g., project id, environment slug,
+ * secret name). Adapt the test steps to your capability's method
+ * surface. Model on \`packages/holocron-plugin-infisical/scripts/validate.mjs\`.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- filled in by operator
+import { AuthError, createPlugin, resolveToken, verifyToken } from "../src/index.ts";
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+	console.error("usage: pnpm --filter @theholocron/holocron-plugin-${inputs.slug} validate <args>");
+	process.exit(2);
+}
+
+// Use the plugin's own auth resolution so the validate script honors
+// the same 4-step precedence as the plugin's runtime:
+//   --token → ${inputs.tokenEnv} → ${inputs.vendorEnv} → keyring
+// (--token isn't available here since this is a bare Node script;
+// the other three all work.)
+let token;
+try {
+	token = resolveToken();
+} catch (err) {
+	if (err instanceof AuthError) {
+		console.error(err.message);
+		console.error("  see: packages/holocron-plugin-${inputs.slug}/README.md#setup");
+		process.exit(2);
+	}
+	throw err;
+}
+
+console.log("Validating @theholocron/holocron-plugin-${inputs.slug} (READ-ONLY)");
+console.log("");
+
+// ── 1. verifyToken ─────────────────────────────────────────────────
+console.log("[1/N] verifyToken");
+const verifyResult = await verifyToken(token);
+console.log(\`      \${verifyResult.ok ? "✓" : "✗"} \${JSON.stringify(verifyResult)}\`);
+if (!verifyResult.ok) {
+	const hint = hintFor(verifyResult.message);
+	if (hint) console.log(\`         hint: \${hint}\`);
+}
+console.log("");
+
+// ── 2..N. capability method calls ──────────────────────────────────
+// TODO: implement one \`runStep\`-wrapped call per meaningful read-side
+// capability method. Model on the infisical validate.mjs. Never call
+// write / ensure* / other mutating paths.
+//
+// Example:
+//   console.log("[2/N] vault.list()");
+//   await runStep(async () => {
+//       const keys = await vault.list();
+//       console.log(\`      ✓ \${keys.length} secrets\`);
+//   });
+
+console.log("Done. Fill in capability method calls above before shipping.");
+
+// ── helpers ────────────────────────────────────────────────────────
+
+/** Wrap a capability call, print ERROR + hint on failure. */
+async function runStep(body) {
+	try {
+		await body();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.log(\`      ✗ ERROR: \${message}\`);
+		const hint = hintFor(message);
+		if (hint) console.log(\`         hint: \${hint}\`);
+	}
+}
+
+/**
+ * Point the operator at the most likely fix based on the error shape.
+ * Generic defaults below — CUSTOMIZE per your vendor's docs URLs and
+ * common permission/config gotchas.
+ */
+function hintFor(message) {
+	if (/→ 401/.test(message)) {
+		return "token invalid — regenerate per ${inputs.vendorName}'s docs (see README §Setup)";
+	}
+	if (/→ 403/.test(message)) {
+		return "token authenticates but lacks scope — check the token/identity has permissions on the resource";
+	}
+	if (/→ 404/.test(message)) {
+		return "endpoint or resource not found — verify your positional args match a real resource";
+	}
+	if (/fetch failed|status: 0|network/i.test(message)) {
+		return "network error — check the base URL (${inputs.baseUrl}) and connectivity";
+	}
+	if (/→ 5\\d\\d/.test(message)) {
+		return "server error — vendor-side. Retry, and check the vendor's status page if persistent";
+	}
+	return null;
+}
+`;
+}
+//#endregion
+//#region src/commands/plugin-create/templates/verify-token.ts
+function render$2(inputs) {
+	const clientClass = `${inputs.vendorName}RestClient`;
+	return `/**
+ * \`verifyToken\` — plugin-level export used by \`holocron auth set\` +
+ * \`holocron auth check\`. Hits a lightweight whoami-style endpoint
+ * and translates the response into the normalized \`VerifyTokenResult\`
+ * shape.
+ *
+ * Kept as a standalone function (not a capability method) so the auth
+ * command can call it without initializing the full plugin — plugin
+ * construction requires an already-resolved token, which is exactly
+ * what we don't have yet at bootstrap time.
+ *
+ * TODO: replace \`/me\` with the ${inputs.vendorName} equivalent of a
+ * "check my token" endpoint. Common shapes: \`/user\`, \`/whoami\`,
+ * \`/me\`, \`/account\`.
+ */
+
+import { ${clientClass} } from "./rest.js";
+
+export interface VerifyTokenSuccess {
+	ok: true;
+	subject: string;
+}
+
+export interface VerifyTokenFailure {
+	ok: false;
+	message: string;
+}
+
+export type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+
+interface MeResponse {
+	/** Adjust to whatever ${inputs.vendorName}'s whoami endpoint returns. */
+	name?: string;
+	email?: string;
+	id?: string;
+}
+
+export interface VerifyTokenOptions {
+	baseUrl?: string;
+	fetch?: typeof fetch;
+}
+
+export async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<VerifyTokenResult> {
+	const restOpts: ConstructorParameters<typeof ${clientClass}>[0] = { token };
+	if (opts.baseUrl !== undefined) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== undefined) restOpts.fetch = opts.fetch;
+	const rest = new ${clientClass}(restOpts);
+	try {
+		const me = await rest.request<MeResponse>("/me");
+		// Optional chaining because \`me\` is \`undefined\` on 204 / empty body.
+		const subject = me?.email ?? me?.name ?? me?.id ?? "unknown";
+		return { ok: true, subject: \`user @ \${subject}\` };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { ok: false, message };
 	}
 }
-function countResolvedLifecycle(report) {
-	return `${report.lifecycle.filter((l) => l.resolved).length}/${report.lifecycle.length} lifecycle slots ready`;
+`;
 }
-function mk(capability, provider, status, message) {
-	return {
-		capability,
-		provider,
-		status,
-		message
-	};
+//#endregion
+//#region src/commands/plugin-create/templates/verify-token-test.ts
+function render$1(_inputs) {
+	return `import { describe, expect, it } from "vitest";
+
+import { verifyToken } from "../verify-token.js";
+import { stubFetch } from "./helpers.js";
+
+describe("verifyToken", () => {
+	it("returns ok with a subject when /me returns 200", async () => {
+		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/);
+		}
+	});
+
+	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/);
+		}
+	});
+
+	it("returns ok:false when the network layer throws", async () => {
+		const throwing: typeof fetch = async () => {
+			throw new TypeError("network down");
+		};
+		const result = await verifyToken("t", { fetch: throwing });
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.message).toMatch(/network down/);
+		}
+	});
+});
+`;
 }
-function pad(s, width) {
-	return s.length >= width ? s : s + " ".repeat(width - s.length);
+//#endregion
+//#region src/commands/plugin-create/templates/vitest-config.ts
+function render(_inputs) {
+	return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		environment: "node",
+		globals: false,
+		coverage: {
+			provider: "v8",
+			reporter: ["text", "html", "json-summary"],
+			include: ["src/**/*.ts"],
+			exclude: ["src/**/__tests__/**", "src/**/*.test.ts", "src/index.ts"],
+			thresholds: { lines: 0, functions: 0, branches: 0, statements: 0 },
+		},
+	},
+});
+`;
 }
 //#endregion
-//#region src/commands/npm-publish-initial.ts
+//#region src/commands/plugin-create/index.ts
 /**
-* `holocron npm publish-initial` — bottles up the chicken-and-egg
-* bootstrap that every new npm-published holocron monorepo hits.
-*
-* npm requires a package to exist before Trusted Publishing can be
-* configured on it. So the first publish has to happen outside the
-* OIDC flow — using either a browser-auth session (`npm login
-* --auth-type=web`) or an ephemeral automation token. This command
-* runs the publish step + tells you exactly what to do next.
-*
-* Workflow:
-*
-*   $ npm login --auth-type=web          # one-time, browser-based
-*   $ pnpm install --frozen-lockfile
-*   $ pnpm build
-*   $ pnpm exec tsx packages/cli/src/cli.ts npm publish-initial
+* `holocron plugin create <slug> <vendor>` — scaffold a new plugin
+* package matching the proven template.
 *
-* The command itself only handles the publish step + the post-publish
-* Trusted Publisher setup reminder. `pnpm install` + `pnpm build`
-* stay outside the command (no pnpm-inside-pnpm).
+* Design: see `.notes/tool-plugin-create.spec.md`.
 *
-* If `NPM_TOKEN` is detected in env, the command prints a final
-* "revoke this token at <url>" reminder — same pattern as `rando vc
-* setup` for the ephemeral GH admin PAT.
+* Flow:
+*   1. Preflight — verify CWD is a workspace root (pnpm-workspace.yaml
+*      + packages/ dir present).
+*   2. Slug collision — packages/holocron-plugin-<slug>/ must not exist.
+*   3. Capability sanity — must be one of the 14 known keys; warn for
+*      many-cardinality caps.
+*   4. Prompt — fill in any missing flags via cli-utils / inquirer
+*      (Phase B; Phase A takes fully-populated input).
+*   5. Generate — for each template, write to
+*      packages/holocron-plugin-<slug>/<path>.
+*   6. Verify (unless --no-verify) — Phase B; runs pnpm install +
+*      pnpm --filter <pkg> typecheck lint test.
+*   7. Print next steps.
 */
-const PUBLISHABLE_PACKAGES = [
-	"@theholocron/cli",
-	"@theholocron/holocron-plugin-github",
-	"@theholocron/holocron-plugin-vercel",
-	"@theholocron/holocron-plugin-neon",
-	"@theholocron/holocron-plugin-clerk",
-	"@theholocron/holocron-plugin-1password",
-	"@theholocron/holocron-plugin-postman"
+var PluginCreateError = class extends Error {
+	name = "PluginCreateError";
+};
+const TEMPLATES = [
+	{
+		path: "package.json",
+		render: render$10
+	},
+	{
+		path: "tsconfig.json",
+		render: render$5
+	},
+	{
+		path: "vitest.config.ts",
+		render
+	},
+	{
+		path: "eslint.config.js",
+		render: render$13
+	},
+	{
+		path: "tsdown.config.ts",
+		render: render$4
+	},
+	{
+		path: "README.md",
+		render: render$8
+	},
+	{
+		path: "src/auth.ts",
+		render: render$17
+	},
+	{
+		path: "src/rest.ts",
+		render: render$7
+	},
+	{
+		path: "src/verify-token.ts",
+		render: render$2
+	},
+	{
+		path: "src/index.ts",
+		render: render$9
+	},
+	{
+		path: "src/capabilities/{{capability}}.ts",
+		render: render$15
+	},
+	{
+		path: "src/__tests__/helpers.ts",
+		render: render$12
+	},
+	{
+		path: "src/__tests__/auth.test.ts",
+		render: render$16
+	},
+	{
+		path: "src/__tests__/rest.test.ts",
+		render: render$6
+	},
+	{
+		path: "src/__tests__/verify-token.test.ts",
+		render: render$1
+	},
+	{
+		path: "src/__tests__/{{capability}}.test.ts",
+		render: render$14
+	},
+	{
+		path: "src/__tests__/index.test.ts",
+		render: render$11
+	},
+	{
+		path: "scripts/validate.mjs",
+		render: render$3
+	}
 ];
-async function runNpmPublishInitial(input = {}) {
-	const print = input.print ?? ((line) => console.log(line));
+/** Replace `{{capability}}` in a template path with the actual capability key. */
+function resolvePath(template, inputs) {
+	return template.replace(/\{\{capability\}\}/g, inputs.capability);
+}
+function runPluginCreate(input) {
 	const cwd = input.cwd ?? process.cwd();
-	const tag = input.tag ?? "alpha";
-	const dryRun = input.dryRun ?? false;
-	const env = input.env ?? process.env;
-	const exec = input.exec ?? defaultExec;
-	print(`Holocron npm publish-initial${dryRun ? " (dry-run)" : ""}`);
-	print(`  cwd: ${cwd}`);
-	print(`  tag: ${tag}`);
-	print("");
-	print("  → verifying npm auth (`npm whoami`)…");
-	const whoami = await exec("npm", ["whoami"], { cwd });
-	if (whoami.exitCode !== 0) {
-		const message = "npm is not authenticated. Run `npm login --auth-type=web` (browser flow, no token stored) or `npm login`, then re-run this command.";
-		print(`  ✗ ${message}`);
-		return {
-			status: "fail",
-			message,
-			packageNames: PUBLISHABLE_PACKAGES
-		};
-	}
-	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
-	if (dryRun) {
-		print("");
-		print("  … (dry-run) skipping actual publish");
-		print(`    would run: pnpm -r --filter='./packages/*' --filter='!@theholocron/cli-utils' publish --access public --no-git-checks --tag ${tag}`);
-		printNextSteps(print, env);
-		return {
-			status: "dry-run",
-			message: "dry-run — no publish executed",
-			packageNames: PUBLISHABLE_PACKAGES
-		};
-	}
-	print("");
-	print("  → publishing all public @theholocron/* packages…");
-	const publish = await exec("pnpm", [
-		"-r",
-		"--filter=./packages/*",
-		"--filter=!@theholocron/cli-utils",
-		"publish",
-		"--access",
-		"public",
-		"--no-git-checks",
-		"--tag",
-		tag
-	], { cwd });
-	if (publish.exitCode !== 0) {
-		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
-		print(`  ✗ ${message}`);
-		return {
-			status: "fail",
-			message,
-			packageNames: PUBLISHABLE_PACKAGES
-		};
+	const print = input.print ?? ((line) => console.log(line));
+	const write = input.writeFile ?? defaultWrite;
+	preflight(cwd);
+	validateSlug(input.slug);
+	validateVendorName(input.vendorName);
+	const packageDir = path.join(cwd, "packages", `holocron-plugin-${input.slug}`);
+	if (existsSync(packageDir)) throw new PluginCreateError(`\`${packageDir}\` already exists — edit in place or pick a different slug.`);
+	validateCapability(input.capability, print);
+	const derived = deriveDefaults({
+		slug: input.slug,
+		vendorName: input.vendorName,
+		capability: input.capability
+	});
+	const inputs = {
+		slug: input.slug,
+		vendorName: input.vendorName,
+		vendorUpper: derived.vendorUpper,
+		capability: input.capability,
+		capabilityClass: derived.capabilityClass,
+		tokenEnv: input.tokenEnv ?? derived.tokenEnv,
+		vendorEnv: input.vendorEnv,
+		baseUrl: trimTrailingSlashes(input.baseUrl),
+		transport: derived.transport
+	};
+	const filesWritten = [];
+	print(`Scaffolding @theholocron/holocron-plugin-${inputs.slug}${input.dryRun ? " (dry-run)" : ""}`);
+	print(`  → ${packageDir}`);
+	for (const template of TEMPLATES) {
+		const resolvedPath = resolvePath(template.path, inputs);
+		const filepath = path.join(packageDir, resolvedPath);
+		const content = template.render(inputs);
+		if (input.dryRun) print(`  … would write ${resolvedPath} (${content.length} bytes)`);
+		else {
+			write(filepath, content);
+			print(`  ✓ ${resolvedPath}`);
+		}
+		filesWritten.push(resolvedPath);
 	}
-	print("    ✓ publish complete");
-	printNextSteps(print, env);
+	if (!input.dryRun) printNextSteps(print, inputs);
 	return {
 		status: "ok",
-		packageNames: PUBLISHABLE_PACKAGES
+		packagePath: packageDir,
+		filesWritten
 	};
 }
-function printNextSteps(print, env) {
+function preflight(cwd) {
+	if (!existsSync(path.join(cwd, "pnpm-workspace.yaml"))) throw new PluginCreateError(`\`pnpm-workspace.yaml\` not found in \`${cwd}\`. Run \`holocron plugin create\` from the monorepo root.`);
+	if (!existsSync(path.join(cwd, "packages"))) throw new PluginCreateError(`\`packages/\` directory not found in \`${cwd}\`.`);
+}
+/**
+* npm-package-name conventions: kebab-case, starts with lowercase
+* letter. Rejecting numeric-prefixed slugs also sidesteps the
+* `env.HOLOCRON_1FOO_TOKEN` invalid-identifier trap in the auth
+* template.
+*/
+const SLUG_RE = /^[a-z][a-z0-9-]*$/;
+function validateSlug(slug) {
+	if (!SLUG_RE.test(slug)) throw new PluginCreateError(`invalid slug "${slug}" — must be kebab-case: lowercase letter followed by lowercase letters, digits, or hyphens. Examples: "clerk", "cloud-flare", "doppler".`);
+}
+/** PascalCase — starts with uppercase, alphanumeric only. */
+const VENDOR_NAME_RE = /^[A-Z][a-zA-Z0-9]*$/;
+function validateVendorName(name) {
+	if (!VENDOR_NAME_RE.test(name)) throw new PluginCreateError(`invalid vendor name "${name}" — must be PascalCase: starts with uppercase, alphanumeric only. Examples: "Clerk", "CloudFlare", "Doppler".`);
+}
+/**
+* Trim trailing slashes with a plain loop (no regex — matches the
+* rest.ts template's own trimming to stay ReDoS-safe under CodeQL).
+*/
+function trimTrailingSlashes(url) {
+	let out = url;
+	while (out.endsWith("/")) out = out.slice(0, -1);
+	return out;
+}
+function validateCapability(capability, print) {
+	if (!(capability in CARDINALITY)) throw new PluginCreateError(`\`${capability}\` is not a known capability. See \`packages/cli/src/capabilities/index.ts\`.`);
+	if (CARDINALITY[capability] === "many") print(`  ! ${capability} is a many-cardinality capability — multiple providers can be active at once. Confirm your config wiring accordingly.`);
+}
+function defaultWrite(filepath, content) {
+	mkdirSync(path.dirname(filepath), { recursive: true });
+	writeFileSync(filepath, content, "utf8");
+}
+function printNextSteps(print, inputs) {
 	print("");
-	print("  → next: configure Trusted Publisher for each package on npm:");
-	for (const name of PUBLISHABLE_PACKAGES) print(`    https://www.npmjs.com/package/${name}/access`);
-	print("    Publisher: GitHub Actions   Org: theholocron   Repo: holocron   Workflow: release.yml");
-	if (env.NPM_TOKEN) {
-		print("");
-		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
-		print("    https://www.npmjs.com/settings/~/tokens");
-	}
+	print(`  Scaffolded @theholocron/holocron-plugin-${inputs.slug} (18 files).`);
+	print("");
+	print("  Next:");
+	print(`    1. pnpm install                                                        # picks up the workspace package`);
+	print(`    2. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} typecheck   # green`);
+	print(`    3. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} lint        # green`);
+	print(`    4. pnpm --filter @theholocron/holocron-plugin-${inputs.slug} test        # green (stubs pass, real tests are it.todo)`);
+	print(`    5. Implement ${inputs.capabilityClass} methods in src/capabilities/${inputs.capability}.ts`);
+	print(`    6. Replace it.todo(...) with real tests in src/__tests__/${inputs.capability}.test.ts`);
+	print("    7. Commit + push when capability is functionally complete.");
 }
-const defaultExec = async (cmd, args, opts) => {
-	const result = spawnSync(cmd, args, {
-		cwd: opts.cwd,
-		encoding: "utf8",
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		]
-	});
-	return {
-		exitCode: result.status ?? -1,
-		stdout: result.stdout ?? "",
-		stderr: result.stderr ?? ""
-	};
-};
 //#endregion
 //#region src/commands/secret-set.ts
 async function runSecretSet(input) {
@@ -486,6 +3443,153 @@ function vaultProviderName(loader) {
 }
 //#endregion
 //#region src/commands/setup.ts
+const DEPENDABOT_CONFIG = `\
+# AUTO-GENERATED by holocron — run \`holocron setup\` to regenerate.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      security-patches:
+        applies-to: security-updates
+        patterns:
+          - "*"
+      all-dependencies:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      all-actions:
+        patterns:
+          - "*"
+`;
+const RULESET_NAME = "holocron-default-branch";
+const BALANCED_REPO_SETTINGS = {
+	allow_squash_merge: true,
+	allow_merge_commit: false,
+	allow_rebase_merge: false,
+	allow_auto_merge: true,
+	allow_update_branch: true,
+	delete_branch_on_merge: true,
+	has_issues: true,
+	has_discussions: true,
+	has_projects: true,
+	has_wiki: false
+};
+function buildClassicProtectionPayload(requiredChecks = []) {
+	return {
+		required_status_checks: requiredChecks.length > 0 ? {
+			strict: false,
+			contexts: requiredChecks
+		} : null,
+		enforce_admins: false,
+		required_pull_request_reviews: {
+			required_approving_review_count: 0,
+			dismiss_stale_reviews: false,
+			require_code_owner_reviews: false
+		},
+		restrictions: null,
+		allow_force_pushes: false,
+		allow_deletions: false
+	};
+}
+function buildRulesetPayload(requiredChecks = []) {
+	const rules = [
+		{ type: "deletion" },
+		{ type: "non_fast_forward" },
+		{
+			type: "pull_request",
+			parameters: {
+				required_approving_review_count: 0,
+				dismiss_stale_reviews_on_push: false,
+				require_code_owner_review: false,
+				require_last_push_approval: false,
+				required_review_thread_resolution: false
+			}
+		}
+	];
+	if (requiredChecks.length > 0) rules.push({
+		type: "required_status_checks",
+		parameters: {
+			required_status_checks: requiredChecks.map((context) => ({ context })),
+			strict_required_status_checks_policy: false
+		}
+	});
+	return {
+		name: RULESET_NAME,
+		target: "branch",
+		enforcement: "active",
+		conditions: { ref_name: {
+			include: ["~DEFAULT_BRANCH"],
+			exclude: []
+		} },
+		rules
+	};
+}
+async function upsertBranchProtection(source, dryRun, requiredChecks) {
+	const step = `upsert ruleset ${RULESET_NAME}`;
+	if (dryRun) return {
+		capability: "source",
+		step,
+		status: "dry-run"
+	};
+	try {
+		const found = (await source.listRulesets()).find((r) => r.name === RULESET_NAME);
+		if (found) {
+			await source.updateRuleset(found.id, buildRulesetPayload(requiredChecks));
+			return {
+				capability: "source",
+				step,
+				status: "ok",
+				message: "updated"
+			};
+		}
+		await source.createRuleset(buildRulesetPayload(requiredChecks));
+		return {
+			capability: "source",
+			step,
+			status: "ok",
+			message: "created"
+		};
+	} catch (err) {
+		if (!(err instanceof ProviderApiError) || err.status !== 403) return {
+			capability: "source",
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+	try {
+		const repo = await source.getRepo();
+		await source.protectBranch(repo.defaultBranch, buildClassicProtectionPayload(requiredChecks));
+		return {
+			capability: "source",
+			step,
+			status: "ok",
+			message: `classic protection on ${repo.defaultBranch}`
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 403) return {
+			capability: "source",
+			step,
+			status: "skip",
+			message: "branch protection unavailable on private repos without GitHub Pro/Team"
+		};
+		return {
+			capability: "source",
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
 async function runSetup(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
@@ -503,13 +3607,59 @@ async function runSetup(input) {
 			"enableVulnerabilityAlerts",
 			"enableAutomatedSecurityFixes",
 			"enableSecretScanning",
-			"enablePrivateVulnerabilityReporting"
+			"enablePrivateVulnerabilityReporting",
+			"enableDependencyGraph"
 		]) {
 			steps.push(await runStep("source", method, dryRun, async () => {
 				await source[method]();
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
+		steps.push(await runStep("source", "enableCodeScanning", dryRun, async () => {
+			return await source.enableCodeScanning();
+		}));
+		print(formatStep(steps[steps.length - 1]));
+		const policy = config.project.repoPolicy;
+		if (policy && policy.preset !== "none") {
+			const preset = policy.preset ?? "balanced";
+			steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
+				await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+			const requiredChecks = preset === "strict" ? policy.requiredChecks ?? [] : [];
+			steps.push(await upsertBranchProtection(source, dryRun, requiredChecks));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	const workflows = config.project.workflows;
+	if (loader.has("source") && workflows && workflows.length > 0) {
+		const source = loader.get("source");
+		print("  → workflows");
+		for (const entry of workflows) {
+			const name = typeof entry === "string" ? entry : entry.name;
+			const withOverrides = typeof entry === "object" ? entry.with : void 0;
+			if (!KNOWN_WORKFLOWS.has(name)) {
+				steps.push({
+					capability: "source",
+					step: `write workflow ${name}`,
+					status: "skip",
+					message: `unknown workflow "${name}" — no template available`
+				});
+				print(formatStep(steps[steps.length - 1]));
+				continue;
+			}
+			steps.push(await runStep("source", `write workflow ${name}`, dryRun, async () => {
+				await source.writeWorkflowFile(`${name}.yml`, workflowHeader() + generateThinCallerContent(name, withOverrides));
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	if (loader.has("source") && config.project.repoPolicy?.preset !== "none") {
+		const source = loader.get("source");
+		steps.push(await runStep("source", "write .github/dependabot.yml", dryRun, async () => {
+			await source.writeRepoFile(".github/dependabot.yml", DEPENDABOT_CONFIG);
+		}));
+		print(formatStep(steps[steps.length - 1]));
 	}
 	if (loader.has("environments")) {
 		const envs = loader.get("environments");
@@ -550,6 +3700,22 @@ async function runSetup(input) {
 	if (loader.has("vault")) {
 		const vault = loader.get("vault");
 		print("  → vault");
+		if (vault.ensureProject) {
+			steps.push(await runStep("vault", `ensureProject ${config.project.name}`, dryRun, async () => {
+				return `project ${(await vault.ensureProject(config.project.name)).alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+		if (vault.ensureEnvironment) for (const envName of [
+			"dev",
+			"stg",
+			"prd"
+		]) {
+			steps.push(await runStep("vault", `ensureEnvironment ${envName}`, dryRun, async () => {
+				return `${envName} ${(await vault.ensureEnvironment(config.project.name, envName)).alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
 		try {
 			const keys = await vault.list();
 			steps.push({
@@ -686,6 +3852,7 @@ async function fileExists(path) {
 }
 //#endregion
 //#region src/cli.ts
+const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [options]").option("dry-run", {
 	type: "boolean",
 	default: false,
@@ -698,7 +3865,7 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	default: process.cwd(),
 	describe: "Directory to search for holocron.config.json"
 }).command("version", "Print the CLI version", () => {}, () => {
-	console.log("holocron 2.0.0-alpha.0");
+	console.log(`holocron ${CLI_VERSION}`);
 }).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
@@ -806,20 +3973,134 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		branch: argv.branch,
 		...argv.target ? { target: argv.target } : {}
 	})).status === "fail") process.exitCode = 1;
-}).command("npm publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (y) => y.option("tag", {
+}).command("npm", "npm-related monorepo utilities", (y) => y.command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (yy) => yy.positional("new-version", {
+	type: "string",
+	demandOption: true,
+	describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
+}), async (argv) => {
+	if ((await runNpmBumpVersions({
+		version: argv.newVersion,
+		cwd: argv.cwd,
+		dryRun: argv.dryRun
+	})).status === "fail") process.exitCode = 1;
+}).command("publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (yy) => yy.option("tag", {
 	type: "string",
 	default: "alpha",
 	describe: "npm distribution tag (defaults to alpha)"
+}).option("otp", {
+	type: "string",
+	describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
 }), async (argv) => {
 	if ((await runNpmPublishInitial({
 		cwd: argv.cwd,
 		tag: argv.tag,
-		dryRun: argv.dryRun
+		dryRun: argv.dryRun,
+		...argv.otp ? { otp: argv.otp } : {}
+	})).status === "fail") process.exitCode = 1;
+}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github via the GitHub API", (y) => y.option("repo", {
+	type: "string",
+	default: "theholocron/.github",
+	describe: "Target org/repo (default: theholocron/.github)"
+}).option("branch", {
+	type: "string",
+	describe: "Push to this branch instead of the default branch (enables PR-based workflow for protected repos)"
+}).option("pr", {
+	type: "boolean",
+	default: false,
+	describe: "Open a PR after pushing to --branch (no-op without --branch)"
+}).option("message", {
+	type: "string",
+	describe: "Commit message (default: chore: sync from theholocron/holocron)"
+}).option("output-dir", {
+	type: "string",
+	describe: "Write generated files to this local directory instead of pushing (for validation)"
+}), async (argv) => {
+	const outputDir = argv["output-dir"];
+	const token = outputDir ? "no-token-needed" : argv.token ?? process.env.GITHUB_TOKEN ?? process.env.HOLOCRON_GITHUB_TOKEN;
+	if (!token) {
+		console.error("sync-github: GitHub token required — pass --token or set GITHUB_TOKEN");
+		process.exitCode = 1;
+		return;
+	}
+	if ((await runSyncGithub({
+		token,
+		repo: argv.repo,
+		dryRun: argv.dryRun,
+		...argv.branch ? { branch: argv.branch } : {},
+		...argv.pr ? { createPr: true } : {},
+		...argv.message ? { message: argv.message } : {},
+		...outputDir ? { outputDir } : {}
 	})).status === "fail") process.exitCode = 1;
 }).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
 	const loaded = await loadConfig(argv.cwd);
 	console.log(JSON.stringify(loaded.resolved, null, 2));
-}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
+}).command("plugin create <slug> <vendor>", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
+	type: "string",
+	demandOption: true,
+	describe: "Package slug (kebab-case)"
+}).positional("vendor", {
+	type: "string",
+	demandOption: true,
+	describe: "Vendor display name (PascalCase)"
+}).option("capability", {
+	type: "string",
+	describe: "Capability key: source|ci|secrets|environments|issues|deployment|storage|auth|vault|dns|tooling|notifications|analytics|observability"
+}).option("token-env", {
+	type: "string",
+	describe: "Holocron env var name (defaults to HOLOCRON_<VENDOR>_TOKEN)"
+}).option("vendor-env", {
+	type: "string",
+	describe: "Vendor-native env var name"
+}).option("base-url", {
+	type: "string",
+	describe: "REST base URL"
+}).option("verify", {
+	type: "boolean",
+	default: true,
+	describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
+}), (argv) => {
+	try {
+		if (!argv.capability || !argv.vendorEnv || !argv.baseUrl) throw new PluginCreateError("Phase A: --capability, --vendor-env, and --base-url are required. Interactive prompts land in Phase B.");
+		if (runPluginCreate({
+			slug: argv.slug,
+			vendorName: argv.vendor,
+			capability: argv.capability,
+			vendorEnv: argv.vendorEnv,
+			baseUrl: argv.baseUrl,
+			...argv.tokenEnv ? { tokenEnv: argv.tokenEnv } : {},
+			dryRun: argv.dryRun,
+			noVerify: !argv.verify,
+			cwd: argv.cwd
+		}).status === "fail") process.exitCode = 1;
+	} catch (err) {
+		if (err instanceof PluginCreateError) {
+			console.error(`plugin create: ${err.message}`);
+			process.exitCode = 1;
+			return;
+		}
+		throw err;
+	}
+}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set <provider> [token]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", {
+	type: "string",
+	demandOption: true
+}).positional("token", { type: "string" }), async (argv) => {
+	if ((await runAuthSet({
+		provider: argv.provider,
+		...argv.token ? { positional: argv.token } : {}
+	})).status === "fail") process.exitCode = 1;
+}).command("unset <provider>", "Remove a stored bootstrap token", (yy) => yy.positional("provider", {
+	type: "string",
+	demandOption: true
+}), (argv) => {
+	runAuthUnset({ provider: argv.provider });
+}).command("check <provider>", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", {
+	type: "string",
+	demandOption: true
+}), async (argv) => {
+	if ((await runAuthCheck({ provider: argv.provider })).status === "fail") process.exitCode = 1;
+}).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
+	await runAuthList();
+}).demandCommand(1, "Run `holocron auth --help` to see available auth subcommands."), () => {}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
 /**
 * Parse `--scope` strings: `repo` | `env=NAME` | `org=NAME`.
 */