pruff-skills 1.8.0 → 1.9.0

package/README.md

@@ -147,6 +147,9 @@ npx pruff-skills add <skill> -g -a claude-code -y
 | `npx pruff-skills restore`         | Reinstall everything recorded in `skills-lock.json` |
 | `npx pruff-skills sync`            | Install skills found in `node_modules` into agent dirs |
 | `npx pruff-skills onboarding --db-access` | Set up personal read-only database access (team members) |
+| `npx pruff-skills doctor`          | Print a diagnostic block to paste when something fails |
+
+Troubleshooting: if a command fails, run `npx pruff-skills doctor` and paste the block it prints when you ask for help.
 
 ```bash
 npx pruff-skills list                 # list installed skills

package/dist/_chunks/libs/simple-git.mjs

@@ -1,8 +1,8 @@
 import { r as __toESM } from "../rolldown-runtime.mjs";
 import { n as require_src, t as require_dist } from "./@kwsites/file-exists.mjs";
 import { t as require_dist$1 } from "./@kwsites/promise-deferred.mjs";
-import { Buffer as Buffer$1 } from "node:buffer";
 import { spawn } from "child_process";
+import { Buffer as Buffer$1 } from "node:buffer";
 import { normalize } from "node:path";
 import { EventEmitter } from "node:events";
 var import_dist = require_dist();

package/dist/cli.mjs

@@ -7,20 +7,378 @@ import "./_chunks/libs/@kwsites/promise-deferred.mjs";
 import { t as esm_default } from "./_chunks/libs/simple-git.mjs";
 import { t as xdgConfig } from "./_chunks/libs/xdg-basedir.mjs";
 import { t as require_dist } from "./_chunks/libs/@vercel/detect-agent.mjs";
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "fs";
+import { accessSync, chmodSync, constants, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "fs";
 import { basename, delimiter, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { stripVTControlCharacters } from "node:util";
+import { execFile, execSync, spawn, spawnSync } from "child_process";
 import { homedir, platform, tmpdir } from "os";
 import * as readline from "readline";
 import { Writable } from "stream";
 import { promisify } from "util";
-import { execFile, execSync, spawn, spawnSync } from "child_process";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, symlink, writeFile } from "fs/promises";
 import { parse } from "yaml";
 import { createHash, randomBytes } from "crypto";
 import { createHash as createHash$1 } from "node:crypto";
 import { gunzipSync, inflateRawSync } from "node:zlib";
+var UserFacingError = class extends Error {};
+var LockVersionError = class extends UserFacingError {};
+const DIAGNOSTICS_HEADER = "Diagnóstico — copiá y pegá esto en #dev-tools o a Ramiro";
+const DIAGNOSTICS_FOOTER = "Si esto falla otra vez: pruff-skills doctor";
+const DEFAULT_CATALOG = "Pruff-Tech/pruff-skills";
+const PROBE_TIMEOUT_MS = 2500;
+const probeCache = /* @__PURE__ */ new Map();
+let currentStep = "start";
+let failure = null;
+const tail = [];
+function setStep(step) {
+	currentStep = step;
+}
+function recordFailure(message) {
+	failure ??= {
+		step: currentStep,
+		message
+	};
+}
+function resetDiagnosticsState() {
+	currentStep = "start";
+	failure = null;
+	tail.length = 0;
+}
+function recordedFailure() {
+	return failure;
+}
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+function redact(text, home = homedir()) {
+	let out = text.replace(ANSI, "");
+	if (home && home !== "/") out = out.split(home).join("~");
+	return out.replace(/(https?:\/\/)[^\s/@]+@/gi, "$1[redacted]@").replace(/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{10,}/g, "[redacted]").replace(/\bgithub_pat_[A-Za-z0-9_]{10,}/g, "[redacted]").replace(/\bAKIA[A-Z0-9]{12,}/g, "[redacted]").replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]").replace(/([?&]token=)[^&\s]+/gi, "$1[redacted]").replace(/(x-api-key["']?\s*[:=]?\s*)[^\s"',;]+/gi, "$1[redacted]").replace(/[A-Za-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}/g, "[email]");
+}
+function catalogKind(source) {
+	if (/^[^/\s]+\/[^/\s]+$/.test(source) && !source.startsWith(".")) return "owner/repo";
+	if (source.startsWith(".") || isAbsolute(source) || source.startsWith("~")) return "local path";
+	try {
+		return `git URL (${new URL(source).host})`;
+	} catch {
+		const scp = source.match(/^[^@\s]+@([^:\s]+):/);
+		return scp ? `git URL (${scp[1]})` : "git URL";
+	}
+}
+const yn = (v) => v ? "yes" : "no";
+function probe(cmd, args) {
+	const key = [cmd, ...args].join(" ");
+	const cached = probeCache.get(key);
+	if (cached) return cached;
+	const r = spawnSync(cmd, args, {
+		encoding: "utf-8",
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: "pipe",
+		env: {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0",
+			COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
+		}
+	});
+	const result = {
+		ok: r.status === 0,
+		out: `${r.stdout ?? ""}\n${r.stderr ?? ""}`.trim()
+	};
+	probeCache.set(key, result);
+	return result;
+}
+const onPath = (cmd) => {
+	return yn((process.env.PATH ?? "").split(delimiter).filter(Boolean).some((dir) => {
+		try {
+			accessSync(join(dir, cmd), constants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	}));
+};
+function version$2() {
+	try {
+		const dir = dirname(fileURLToPath(import.meta.url));
+		return JSON.parse(readFileSync(join(dir, "..", "package.json"), "utf-8")).version;
+	} catch {
+		return "unknown";
+	}
+}
+function timestamp(d = /* @__PURE__ */ new Date()) {
+	const pad = (n) => String(Math.trunc(Math.abs(n))).padStart(2, "0");
+	const off = -d.getTimezoneOffset();
+	const sign = off >= 0 ? "+" : "-";
+	return `${(/* @__PURE__ */ new Date(d.getTime() - d.getTimezoneOffset() * 6e4)).toISOString().slice(0, 19)}${sign}${pad(off / 60)}:${pad(off % 60)}`;
+}
+function packageManager() {
+	const pnpm = probe("pnpm", ["-v"]);
+	const npm = probe("npm", ["-v"]);
+	const v = (r) => r.ok && r.out.match(/\d+\.\d+\.\d+\S*/g)?.pop() || "n/a";
+	return `pnpm ${v(pnpm)}, npm ${v(npm)}`;
+}
+function ghStatus() {
+	if (onPath("gh") === "no") return {
+		summary: "n/a (gh not installed)",
+		loggedIn: false
+	};
+	const r = probe("gh", ["auth", "status"]);
+	const text = r.out;
+	const loggedIn = r.ok || /Logged in to/i.test(text);
+	const host = text.match(/Logged in to (\S+)/i)?.[1] ?? text.match(/^(\S+\.\S+)\s*$/m)?.[1];
+	const account = text.match(/account (\S+)/i)?.[1];
+	const scopes = text.match(/Token scopes:\s*(.+)/i)?.[1]?.replace(/['"]/g, "").trim();
+	if (!loggedIn) return {
+		summary: "logged_in=no",
+		loggedIn
+	};
+	return {
+		summary: redact(`logged_in=yes host=${host ?? "?"} account=${account ?? "?"} scopes=${scopes ?? "?"}`),
+		loggedIn
+	};
+}
+function checkCatalog(source) {
+	const kind = catalogKind(source);
+	if (kind === "local path") {
+		const root = resolve(source.replace(/^~(?=\/|$)/, homedir()));
+		if (!existsSync(root)) return {
+			ok: false,
+			detail: "fail (path does not exist)"
+		};
+		return existsSync(join(root, ".well-known", "agent-skills", "index.json")) ? {
+			ok: true,
+			detail: "ok (local path, index.json present)"
+		} : {
+			ok: false,
+			detail: "fail (index.json missing)"
+		};
+	}
+	if (kind === "owner/repo") {
+		const r = probe("gh", [
+			"api",
+			`repos/${source}`,
+			"--jq",
+			".default_branch"
+		]);
+		return r.ok ? {
+			ok: true,
+			detail: "ok (gh api)"
+		} : {
+			ok: false,
+			detail: `fail (gh api: ${redact(r.out.split("\n")[0] ?? "")})`
+		};
+	}
+	const r = probe("git", [
+		"ls-remote",
+		"--exit-code",
+		source,
+		"HEAD"
+	]);
+	return r.ok ? {
+		ok: true,
+		detail: "ok (git ls-remote)"
+	} : {
+		ok: false,
+		detail: `fail (git ls-remote: ${redact(r.out.split("\n").pop() ?? "")})`
+	};
+}
+function nearestExisting(path) {
+	let dir = path;
+	while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
+	return dir;
+}
+function writable(path) {
+	try {
+		accessSync(nearestExisting(path), constants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function target(ctx) {
+	const global = ctx.args.includes("-g") || ctx.args.includes("--global");
+	if (ctx.command === "onboarding") {
+		const arg = ctx.args.find((a) => !a.startsWith("-"));
+		return {
+			scope: "workspace",
+			dir: arg ? resolve(arg.replace(/^~(?=\/|$)/, homedir())) : join(homedir(), "pruff")
+		};
+	}
+	if (global) return {
+		scope: "global (-g)",
+		dir: process.env.CLAUDE_CONFIG_DIR?.trim() || homedir()
+	};
+	return {
+		scope: "project",
+		dir: process.cwd()
+	};
+}
+function settingsStatus() {
+	const file = join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "settings.json");
+	if (!existsSync(file)) return "missing";
+	try {
+		JSON.parse(readFileSync(file, "utf-8"));
+		return "valid JSON";
+	} catch {
+		return "NOT valid JSON";
+	}
+}
+function collectDiagnostics(ctx) {
+	const envCatalog = process.env.PRUFF_SKILLS_CATALOG;
+	const source = envCatalog || DEFAULT_CATALOG;
+	const gh = ghStatus();
+	const catalog = ctx.checkCatalog ? checkCatalog(source) : null;
+	const t = target(ctx);
+	const configDir = join(homedir(), ".config", "pruff");
+	const failed = recordedFailure();
+	const errorLine = ctx.error ?? failed?.message ?? "";
+	return {
+		cli: version$2(),
+		node: process.version,
+		packageManager: packageManager(),
+		os: `${process.platform} ${process.arch}`,
+		time: timestamp(),
+		command: redact([
+			"pruff-skills",
+			ctx.command,
+			...ctx.args
+		].join(" ")),
+		failedStep: ctx.step ?? failed?.step ?? (errorLine ? currentStep : "none"),
+		error: errorLine ? redact(errorLine.split("\n")[0] ?? "").slice(0, 200) : "none",
+		exitCode: ctx.exitCode === void 0 ? "n/a" : String(ctx.exitCode),
+		catalogEnv: envCatalog ? `PRUFF_SKILLS_CATALOG set (${catalogKind(envCatalog)})` : "not set",
+		catalogSource: envCatalog ? catalogKind(envCatalog) : `default (${DEFAULT_CATALOG})`,
+		catalogCheck: catalog ? catalog.detail : "not checked",
+		gh: onPath("gh"),
+		ghAuth: gh.summary,
+		git: onPath("git"),
+		mysql: onPath("mysql"),
+		security: onPath("security"),
+		scope: t.scope,
+		targetDir: `${redact(t.dir)} (writable=${yn(writable(t.dir))})`,
+		dbReaderConfig: yn(existsSync(join(configDir, "db-reader.json"))),
+		dbReaderCa: yn(existsSync(join(configDir, "rds-us-east-1-bundle.pem"))),
+		claudeSettings: settingsStatus(),
+		ghLoggedIn: gh.loggedIn,
+		catalogOk: catalog?.ok ?? false
+	};
+}
+function renderDiagnostics(d) {
+	return [
+		"```",
+		...[
+			DIAGNOSTICS_HEADER,
+			`cli: ${d.cli}`,
+			`node: ${d.node}`,
+			`package_manager: ${d.packageManager}`,
+			`os: ${d.os}`,
+			`time: ${d.time}`,
+			`command: ${d.command}`,
+			`failed_step: ${d.failedStep}`,
+			`error: ${d.error}`,
+			`exit_code: ${d.exitCode}`,
+			`catalog_env: ${d.catalogEnv}`,
+			`catalog_source: ${d.catalogSource}`,
+			`catalog_check: ${d.catalogCheck}`,
+			`gh_on_path: ${d.gh}`,
+			`gh_auth: ${d.ghAuth}`,
+			`git_on_path: ${d.git}`,
+			`mysql_on_path: ${d.mysql}`,
+			`security_on_path: ${d.security}`,
+			`install_scope: ${d.scope}`,
+			`target_dir: ${d.targetDir}`,
+			`db_reader_config: ${d.dbReaderConfig}`,
+			`db_reader_ca_bundle: ${d.dbReaderCa}`,
+			`claude_settings_json: ${d.claudeSettings}`,
+			DIAGNOSTICS_FOOTER
+		],
+		"```"
+	].join("\n");
+}
+function printDiagnostics(ctx) {
+	console.error("");
+	console.error(renderDiagnostics(collectDiagnostics(ctx)));
+}
+function lastLoggedError() {
+	return lastErrorLine(tail);
+}
+function lastErrorLine(lines) {
+	for (let i = lines.length - 1; i >= 0; i--) if (/✖|\bERROR\b|\bfailed\b|\bnot found\b|\bcould not\b|\bdoes not exist\b|\bcannot\b|\bnot authenticated\b/i.test(lines[i])) return lines[i];
+	return lines[lines.length - 1] ?? "";
+}
+async function withDiagnostics(command, args, fn) {
+	resetDiagnosticsState();
+	const realExit = process.exit;
+	const realOut = process.stdout.write.bind(process.stdout);
+	const realErr = process.stderr.write.bind(process.stderr);
+	const remember = (chunk) => {
+		if (typeof chunk !== "string") return;
+		for (const raw of chunk.replace(ANSI, "").split("\n")) {
+			const line = raw.replace(/^[\s│└├┌◇◆■▲●○]+/, "").trim();
+			if (line) tail.push(line);
+		}
+		if (tail.length > 60) tail.splice(0, tail.length - 60);
+	};
+	process.stdout.write = (chunk, ...rest) => {
+		remember(chunk);
+		return realOut(chunk, ...rest);
+	};
+	process.stderr.write = (chunk, ...rest) => {
+		remember(chunk);
+		return realErr(chunk, ...rest);
+	};
+	const restore = () => {
+		process.exit = realExit;
+		process.stdout.write = realOut;
+		process.stderr.write = realErr;
+	};
+	let printed = false;
+	const emit = (exitCode, error) => {
+		if (printed) return;
+		printed = true;
+		const message = error ?? recordedFailure()?.message ?? lastErrorLine(tail);
+		restore();
+		printDiagnostics({
+			command,
+			args,
+			exitCode,
+			error: message
+		});
+	};
+	process.exit = (code) => {
+		const n = Number(code ?? process.exitCode ?? 0);
+		if (n !== 0) emit(n);
+		restore();
+		return realExit(code);
+	};
+	try {
+		await fn();
+		restore();
+		if (recordedFailure()) {
+			emit(1);
+			return 1;
+		}
+		return 0;
+	} catch (error) {
+		restore();
+		const text = error instanceof Error ? error.message : String(error);
+		if (error instanceof UserFacingError) console.error(error.message);
+		else console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+		emit(1, text);
+		return 1;
+	} finally {
+		restore();
+	}
+}
+async function runDoctor() {
+	resetDiagnosticsState();
+	const d = collectDiagnostics({
+		command: "doctor",
+		args: [],
+		checkCatalog: true
+	});
+	console.log(renderDiagnostics(d));
+	return d.ghLoggedIn && d.catalogOk ? 0 : 1;
+}
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
 function getOwnerRepo(parsed) {
 	if (parsed.type === "local") return null;
@@ -436,7 +794,7 @@ const CLONE_TIMEOUT_MS = (() => {
 	const parsed = Number.parseInt(raw, 10);
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
 })();
-const execFileAsync$5 = promisify(execFile);
+const execFileAsync$4 = promisify(execFile);
 var GitCloneError = class extends Error {
 	url;
 	isTimeout;
@@ -514,7 +872,7 @@ async function resetTempDir(dir) {
 async function tryGhClone(repo, tempDir, ref) {
 	let cloneTarget = repo.slug;
 	try {
-		const { stdout, stderr } = await execFileAsync$5("gh", [
+		const { stdout, stderr } = await execFileAsync$4("gh", [
 			"auth",
 			"status",
 			"-h",
@@ -531,7 +889,7 @@ async function tryGhClone(repo, tempDir, ref) {
 	} catch {
 		return false;
 	}
-	await execFileAsync$5("gh", [
+	await execFileAsync$4("gh", [
 		"repo",
 		"clone",
 		cloneTarget,
@@ -683,8 +1041,6 @@ async function getPluginGroupings(basePath) {
 	} catch {}
 	return groupings;
 }
-var UserFacingError = class extends Error {};
-var LockVersionError = class extends UserFacingError {};
 const LOCAL_LOCK_FILE = "skills-lock.json";
 const CURRENT_VERSION$1 = 1;
 function getLocalLockPath(cwd) {
@@ -1695,6 +2051,27 @@ async function createSymlink(target, linkPath) {
 		return false;
 	}
 }
+const canonicalCopies = /* @__PURE__ */ new Map();
+async function copyCanonicalOnce(src, canonicalDir) {
+	const key = `${src}\0${canonicalDir}`;
+	let entry = canonicalCopies.get(key);
+	if (!entry || entry.done && !existsSync(canonicalDir)) {
+		const fresh = {
+			done: false,
+			promise: Promise.resolve()
+		};
+		fresh.promise = (async () => {
+			await cleanAndCreateDirectory(canonicalDir);
+			await copyDirectory(src, canonicalDir);
+		})();
+		fresh.promise.then(() => {
+			fresh.done = true;
+		}, () => canonicalCopies.delete(key));
+		canonicalCopies.set(key, fresh);
+		entry = fresh;
+	}
+	await entry.promise;
+}
 async function installSkillForAgent(skill, agentType, options = {}) {
 	const agent = agents[agentType];
 	const isGlobal = options.global ?? false;
@@ -1733,8 +2110,7 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 				mode: "copy"
 			};
 		}
-		await cleanAndCreateDirectory(canonicalDir);
-		await copyDirectory(skill.path, canonicalDir);
+		await copyCanonicalOnce(skill.path, canonicalDir);
 		if (isGlobal && isUniversalAgent(agentType)) return {
 			success: true,
 			path: canonicalDir,
@@ -2768,7 +3144,8 @@ async function fetchTreeBranch(ownerRepo, branch, token) {
 		}
 		return {
 			tree: null,
-			rateLimited: response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0"
+			rateLimited: response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0",
+			notFound: response.status === 404
 		};
 	} catch {
 		return {
@@ -2793,6 +3170,7 @@ async function fetchRepoTree(ownerRepo, ref, getToken) {
 		return null;
 	}
 	let rateLimited = false;
+	let privateSuspected = false;
 	for (const branch of branches) {
 		const result = await fetchTreeBranch(ownerRepo, branch, null);
 		if (result.tree) return result.tree;
@@ -2800,9 +3178,13 @@ async function fetchRepoTree(ownerRepo, ref, getToken) {
 			rateLimited = true;
 			break;
 		}
+		if (result.notFound && getToken) {
+			privateSuspected = true;
+			break;
+		}
 	}
-	if (!rateLimited || !getToken) return null;
-	_rateLimitedThisSession = true;
+	if (!(rateLimited || privateSuspected) || !getToken) return null;
+	if (rateLimited) _rateLimitedThisSession = true;
 	const token = getToken();
 	if (!token) return null;
 	for (const branch of branches) {
@@ -3120,6 +3502,7 @@ async function selectAgentsInteractive(options) {
 	});
 }
 async function handleWellKnownSkills(source, url, options, spinner) {
+	setStep("add:discover-skills");
 	spinner.start("Discovering skills from well-known endpoint...");
 	const skills = await wellKnownProvider.fetchAllSkills(url);
 	if (skills.length === 0) {
@@ -3194,6 +3577,7 @@ async function handleWellKnownSkills(source, url, options, spinner) {
 		}
 		targetAgents = options.agent;
 	} else {
+		setStep("add:load-agents");
 		spinner.start("Loading agents...");
 		const installedAgents = await detectInstalledAgents();
 		const totalAgents = Object.keys(agents).length;
@@ -3304,6 +3688,7 @@ async function handleWellKnownSkills(source, url, options, spinner) {
 	}
 	const sourceIdentifier = wellKnownProvider.getSourceIdentifier(url);
 	const wellKnownPrivacyPromise = isSourcePrivate(sourceIdentifier).catch(() => null);
+	setStep("add:install");
 	spinner.start("Installing skills...");
 	const results = [];
 	for (const skill of selectedSkills) for (const agent of targetAgents) {
@@ -3437,6 +3822,7 @@ async function runAdd(args, options = {}) {
 	let tempDir = null;
 	try {
 		const spinner = Y();
+		setStep("add:parse-source");
 		spinner.start("Parsing source...");
 		const parsed = parseSource(source);
 		spinner.stop(`Source: ${parsed.type === "local" ? parsed.localPath : parsed.url}${parsed.ref ? ` @ ${import_picocolors.default.yellow(parsed.ref)}` : ""}${parsed.subpath ? ` (${parsed.subpath})` : ""}${parsed.skillFilter ? ` ${import_picocolors.default.dim("@")}${import_picocolors.default.cyan(parsed.skillFilter)}` : ""}`);
@@ -3469,6 +3855,7 @@ async function runAdd(args, options = {}) {
 		let skills;
 		let blobResult = null;
 		if (parsed.type === "local") {
+			setStep("add:validate-path");
 			spinner.start("Validating local path...");
 			if (!existsSync(parsed.localPath)) {
 				spinner.stop(import_picocolors.default.red("Path not found"));
@@ -3476,6 +3863,7 @@ async function runAdd(args, options = {}) {
 				process.exit(1);
 			}
 			spinner.stop("Local path validated");
+			setStep("add:discover-skills");
 			spinner.start("Discovering skills...");
 			skills = await discoverSkills(parsed.localPath, parsed.subpath, {
 				includeInternal,
@@ -3486,6 +3874,7 @@ async function runAdd(args, options = {}) {
 			const ownerRepo = getOwnerRepo(parsed);
 			const owner = ownerRepo?.split("/")[0]?.toLowerCase();
 			if (ownerRepo && owner && BLOB_ALLOWED_OWNERS.includes(owner)) {
+				setStep("add:fetch-skills");
 				spinner.start("Fetching skills...");
 				blobResult = await tryBlobInstall(ownerRepo, {
 					subpath: parsed.subpath,
@@ -3500,9 +3889,11 @@ async function runAdd(args, options = {}) {
 				skills = blobResult.skills;
 				spinner.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
 			} else {
+				setStep("add:clone");
 				spinner.start("Cloning repository...");
 				tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 				spinner.stop("Repository cloned");
+				setStep("add:discover-skills");
 				spinner.start("Discovering skills...");
 				skills = await discoverSkills(tempDir, parsed.subpath, {
 					includeInternal,
@@ -3510,9 +3901,11 @@ async function runAdd(args, options = {}) {
 				});
 			}
 		} else {
+			setStep("add:clone");
 			spinner.start("Cloning repository...");
 			tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 			spinner.stop("Repository cloned");
+			setStep("add:discover-skills");
 			spinner.start("Discovering skills...");
 			skills = await discoverSkills(tempDir, parsed.subpath, {
 				includeInternal,
@@ -3639,6 +4032,7 @@ async function runAdd(args, options = {}) {
 			}
 			targetAgents = options.agent;
 		} else {
+			setStep("add:load-agents");
 			spinner.start("Loading agents...");
 			const installedAgents = await detectInstalledAgents();
 			const totalAgents = Object.keys(agents).length;
@@ -3784,6 +4178,7 @@ async function runAdd(args, options = {}) {
 				process.exit(0);
 			}
 		}
+		setStep("add:install");
 		spinner.start("Installing skills...");
 		const results = [];
 		for (const skill of selectedSkills) for (const agent of targetAgents) {
@@ -4031,20 +4426,42 @@ function parseAddOptions(args) {
 		options
 	};
 }
-const execFileAsync$4 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 const isLocalSource = (source) => source.startsWith(".") || isAbsolute(source);
 const isGitHubSource = (source) => /^[^/]+\/[^/]+$/.test(source);
 const ghEnv = () => ({
 	...process.env,
 	GIT_TERMINAL_PROMPT: "0"
 });
+const clones = /* @__PURE__ */ new Map();
+let exitHookInstalled = false;
+const settledDirs = /* @__PURE__ */ new Set();
+function cloneOnce(source) {
+	let pending = clones.get(source);
+	if (!pending) {
+		pending = cloneRepo$1(source);
+		clones.set(source, pending);
+		pending.catch(() => clones.delete(source));
+		if (!exitHookInstalled) {
+			exitHookInstalled = true;
+			process.on("exit", () => {
+				for (const dir of settledDirs) rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+			});
+		}
+		pending.then((dir) => settledDirs.add(dir)).catch(() => {});
+	}
+	return pending;
+}
 async function fetchCatalogFile(source, rel) {
 	if (isLocalSource(source)) {
 		const file = join(source, rel);
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	}
 	if (isGitHubSource(source)) try {
-		const { stdout } = await execFileAsync$4("gh", [
+		const { stdout } = await execFileAsync$3("gh", [
 			"api",
 			`repos/${source}/contents/${rel}`,
 			"--jq",
@@ -4055,7 +4472,7 @@ async function fetchCatalogFile(source, rel) {
 		return null;
 	}
 	try {
-		const file = join(await cloneRepo$1(source), rel);
+		const file = join(await cloneOnce(source), rel);
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	} catch {
 		return null;
@@ -4068,7 +4485,7 @@ async function listCatalogDir(source, dir) {
 		return null;
 	}
 	if (isGitHubSource(source)) try {
-		const { stdout } = await execFileAsync$4("gh", [
+		const { stdout } = await execFileAsync$3("gh", [
 			"api",
 			`repos/${source}/contents/${dir}`,
 			"--jq",
@@ -4079,7 +4496,7 @@ async function listCatalogDir(source, dir) {
 		return null;
 	}
 	try {
-		return await readdir(join(await cloneRepo$1(source), dir));
+		return await readdir(join(await cloneOnce(source), dir));
 	} catch {
 		return null;
 	}
@@ -4088,7 +4505,7 @@ const claudeAgentsDir = (global) => global ? join(process.env.CLAUDE_CONFIG_DIR?
 const fetchAgentFile = (source, name) => fetchCatalogFile(source, `agents/${name}.md`);
 async function listCatalogAgents(source) {
 	const files = await listCatalogDir(source, "agents");
-	return files ? files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3)) : null;
+	return files ? files.filter((f) => f.endsWith(".md") && !f.startsWith("_")).map((f) => f.slice(0, -3)) : null;
 }
 async function listInstalledAgents(targetDir) {
 	try {
@@ -4102,6 +4519,7 @@ async function updateAgents(options = {}) {
 	const targetDir = claudeAgentsDir(options.global ?? false);
 	const result = {
 		updated: [],
+		unchanged: [],
 		failed: [],
 		localOnly: [],
 		available: [],
@@ -4125,12 +4543,18 @@ async function updateAgents(options = {}) {
 			result.localOnly.push(name);
 			continue;
 		}
+		setStep(`agents:fetch:${name}`);
 		const content = await fetchAgentFile(source, name);
 		if (content === null) {
 			result.failed.push(name);
 			continue;
 		}
-		await writeFile(join(targetDir, `${sanitizeName(name)}.md`), content);
+		const dest = join(targetDir, `${sanitizeName(name)}.md`);
+		if (await readFile(dest, "utf8").catch(() => null) === content) {
+			result.unchanged.push(name);
+			continue;
+		}
+		await writeFile(dest, content);
 		result.updated.push(name);
 	}
 	return result;
@@ -4155,6 +4579,7 @@ async function addAgents(names, options) {
 		M.message(import_picocolors.default.dim("Browse them with `npx pruff-skills find`."));
 		process.exit(1);
 	}
+	setStep("agents:write");
 	await mkdir(targetDir, { recursive: true });
 	const installed = [];
 	for (const name of names) {
@@ -4212,7 +4637,6 @@ async function runAgents(args) {
 	console.log(`Unknown agents command: ${sub}`);
 	console.log(AGENTS_HELP);
 }
-const execFileAsync$3 = promisify(execFile);
 const RULE_SCOPES = [
 	"client",
 	"server",
@@ -4223,35 +4647,9 @@ function stripFrontmatter(md) {
 	const m = md.match(/^---\n[\s\S]*?\n---\n+/);
 	return m ? md.slice(m[0].length) : md;
 }
-async function fetchFromCatalog(source, rel) {
-	if (source.startsWith(".") || isAbsolute(source)) {
-		const file = join(source, rel);
-		return existsSync(file) ? readFile(file, "utf8") : null;
-	}
-	if (/^[^/]+\/[^/]+$/.test(source)) try {
-		const { stdout } = await execFileAsync$3("gh", [
-			"api",
-			`repos/${source}/contents/${rel}`,
-			"--jq",
-			".content"
-		], { env: {
-			...process.env,
-			GIT_TERMINAL_PROMPT: "0"
-		} });
-		return Buffer.from(stdout.trim(), "base64").toString("utf8");
-	} catch {
-		return null;
-	}
-	try {
-		const file = join(await cloneRepo$1(source), rel);
-		return existsSync(file) ? readFile(file, "utf8") : null;
-	} catch {
-		return null;
-	}
-}
-const fetchRuleFile = (source, name) => fetchFromCatalog(source, `rules/${name}.md`);
+const fetchRuleFile = (source, name) => fetchCatalogFile(source, `rules/${name}.md`);
 async function fetchRuleIndex(source) {
-	const raw = await fetchFromCatalog(source, ".well-known/agent-skills/index.json");
+	const raw = await fetchCatalogFile(source, ".well-known/agent-skills/index.json");
 	if (!raw) return [];
 	return parseCatalogIndex(raw, source).rules ?? [];
 }
@@ -4287,6 +4685,7 @@ async function addRules(names, options) {
 	Ie(import_picocolors.default.cyan("pruff-skills rules"));
 	let toInstall = names.filter(Boolean);
 	if (options.all || options.scopes?.length) {
+		setStep("rules:fetch-index");
 		const index = await fetchRuleIndex(source);
 		if (index.length === 0) {
 			M.error(`Could not read the rules catalog (${source}).`);
@@ -4303,6 +4702,7 @@ async function addRules(names, options) {
 		M.message(import_picocolors.default.dim("Browse them with `npx pruff-skills find`."));
 		process.exit(1);
 	}
+	setStep("rules:write");
 	await mkdir(targetDir, { recursive: true });
 	const installed = [];
 	for (const name of toInstall) {
@@ -4310,6 +4710,7 @@ async function addRules(names, options) {
 			M.warn(`Skipping invalid rule name: ${import_picocolors.default.yellow(name)}`);
 			continue;
 		}
+		setStep(`rules:fetch:${name}`);
 		const content = await fetchRuleFile(source, name);
 		if (!content) {
 			M.error(`Rule ${import_picocolors.default.yellow(name)} not found in the catalog (${source}).`);
@@ -5728,6 +6129,7 @@ async function updateProjectSkills(options = {}) {
 	const projectSkills = await getProjectSkillsForUpdate(options.skills);
 	let successCount = 0;
 	let failCount = 0;
+	let upToDateCount = 0;
 	if (projectSkills.length === 0) {
 		if (!options.skills) {
 			console.log(`${DIM$1}No project skills to update.${RESET$1}`);
@@ -5736,7 +6138,8 @@ async function updateProjectSkills(options = {}) {
 		return {
 			successCount,
 			failCount,
-			foundCount: 0
+			foundCount: 0,
+			upToDateCount
 		};
 	}
 	const updatable = projectSkills.filter((s) => s.entry.skillPath);
@@ -5747,7 +6150,8 @@ async function updateProjectSkills(options = {}) {
 		return {
 			successCount,
 			failCount,
-			foundCount: projectSkills.length
+			foundCount: projectSkills.length,
+			upToDateCount
 		};
 	}
 	const cwd = process.cwd();
@@ -5779,7 +6183,8 @@ async function updateProjectSkills(options = {}) {
 		return {
 			successCount,
 			failCount: updatable.length,
-			foundCount: projectSkills.length
+			foundCount: projectSkills.length,
+			upToDateCount
 		};
 	}
 	for (const [source, skillsForSource] of bySource) {
@@ -5790,12 +6195,19 @@ async function updateProjectSkills(options = {}) {
 		const allLockedForSource = Object.entries(localLock.skills).filter(([_, entry]) => entry.source === source).map(([name, _]) => name);
 		let tempDir = null;
 		let deletedSkills = [];
+		const unchangedSkills = /* @__PURE__ */ new Set();
 		try {
 			tempDir = await cloneRepo$1(sourceUrl, ref);
 			const discoveredPaths = (await discoverSkills(tempDir)).map((s) => {
 				return join(relative(tempDir, s.path), "SKILL.md").split(sep).join("/");
 			});
 			deletedSkills = await checkAndPromptForDeletions(source, allLockedForSource, localLock.skills, false, options, discoveredPaths);
+			for (const skill of skillsForSource) {
+				const { skillPath, computedHash } = skill.entry;
+				if (!skillPath || !computedHash || deletedSkills.includes(skill.name)) continue;
+				const currentHash = await computeSkillFolderHash(join(tempDir, dirname(skillPath))).catch(() => "");
+				if (currentHash && currentHash === computedHash) unchangedSkills.add(skill.name);
+			}
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
 			console.log(`${DIM$1}✗ Failed to check for deleted skills from ${source}: ${sanitizeMetadata(reason)}${RESET$1}`);
@@ -5805,6 +6217,11 @@ async function updateProjectSkills(options = {}) {
 		const remainingSkills = skillsForSource.filter((s) => !deletedSkills.includes(s.name));
 		for (const skill of remainingSkills) {
 			const safeName = sanitizeMetadata(skill.name);
+			if (unchangedSkills.has(skill.name)) {
+				upToDateCount++;
+				console.log(`${TEXT$1}✓${RESET$1} ${safeName} ${DIM$1}is up to date${RESET$1}`);
+				continue;
+			}
 			console.log(`${TEXT$1}Updating ${safeName}...${RESET$1}`);
 			const installUrl = formatSourceInput(skill.entry.source, skill.entry.ref);
 			if (spawnSync(process.execPath, [
@@ -5835,7 +6252,8 @@ async function updateProjectSkills(options = {}) {
 	return {
 		successCount,
 		failCount,
-		foundCount: projectSkills.length
+		foundCount: projectSkills.length,
+		upToDateCount
 	};
 }
 function printLegacyProjectSkills(legacy) {
@@ -5859,6 +6277,7 @@ async function syncAgentsForScope(isGlobal, options) {
 		return result;
 	}
 	for (const name of result.updated) console.log(`  ${TEXT$1}✓${RESET$1} Synced ${sanitizeMetadata(name)}`);
+	for (const name of result.unchanged) console.log(`  ${TEXT$1}✓${RESET$1} ${sanitizeMetadata(name)} ${DIM$1}is up to date${RESET$1}`);
 	for (const name of result.failed) console.log(`  ${DIM$1}✗ Failed to sync ${sanitizeMetadata(name)}${RESET$1}`);
 	if (result.localOnly.length > 0) {
 		const names = result.localOnly.map((n) => sanitizeMetadata(n)).join(", ");
@@ -5873,6 +6292,7 @@ async function syncAgentsForScope(isGlobal, options) {
 }
 async function runUpdate(args = []) {
 	const options = parseUpdateOptions(args);
+	setStep("update:resolve-scope");
 	const scope = await resolveUpdateScope(options);
 	if (options.skills) console.log(`${TEXT$1}Updating ${options.skills.join(", ")}...${RESET$1}`);
 	else console.log(`${TEXT$1}Checking for skill updates...${RESET$1}`);
@@ -5880,8 +6300,10 @@ async function runUpdate(args = []) {
 	let totalSuccess = 0;
 	let totalFail = 0;
 	let totalFound = 0;
+	let totalUpToDate = 0;
 	if (scope === "global" || scope === "both") {
 		if (scope === "both" && !options.skills) console.log(`${BOLD$1}Global Skills${RESET$1}`);
+		setStep("update:global-skills");
 		const { successCount, failCount, checkedCount } = await updateGlobalSkills(options);
 		totalSuccess += successCount;
 		totalFail += failCount;
@@ -5890,7 +6312,9 @@ async function runUpdate(args = []) {
 	}
 	if (scope === "project" || scope === "both") {
 		if (scope === "both" && !options.skills) console.log(`${BOLD$1}Project Skills${RESET$1}`);
-		const { successCount, failCount, foundCount } = await updateProjectSkills(options);
+		setStep("update:project-skills");
+		const { successCount, failCount, foundCount, upToDateCount } = await updateProjectSkills(options);
+		totalUpToDate += upToDateCount;
 		totalSuccess += successCount;
 		totalFail += failCount;
 		totalFound += foundCount;
@@ -5898,22 +6322,30 @@ async function runUpdate(args = []) {
 	console.log();
 	console.log(`${BOLD$1}Subagents${RESET$1}`);
 	console.log(`${DIM$1}ALL installed subagents will be updated and synced with the repo — local edits are overwritten.${RESET$1}`);
+	setStep("update:sync-agents");
 	const agentScopes = scope === "both" ? [true, false] : scope === "global" ? [true] : [false];
 	let agentsSynced = 0;
 	let agentsFailed = 0;
+	let agentsUnchanged = 0;
 	for (const isGlobal of agentScopes) {
 		const agentResult = await syncAgentsForScope(isGlobal, options);
 		agentsSynced += agentResult.updated.length;
+		agentsUnchanged += agentResult.unchanged.length;
 		agentsFailed += agentResult.failed.length;
 	}
-	if (agentsSynced === 0 && agentsFailed === 0) console.log(`  ${DIM$1}No installed subagents to sync.${RESET$1}`);
+	if (agentsSynced === 0 && agentsFailed === 0 && agentsUnchanged === 0) console.log(`  ${DIM$1}No installed subagents to sync.${RESET$1}`);
 	totalSuccess += agentsSynced;
 	totalFail += agentsFailed;
-	totalFound += agentsSynced + agentsFailed;
+	totalFound += agentsSynced + agentsFailed + agentsUnchanged;
+	totalUpToDate += agentsUnchanged;
 	if (options.skills && totalFound === 0) console.log(`${DIM$1}No installed skills found matching: ${options.skills.join(", ")}${RESET$1}`);
 	console.log();
 	if (totalSuccess > 0) console.log(`${TEXT$1}✓ Updated ${totalSuccess} item(s)${RESET$1}`);
-	if (totalFail > 0) console.log(`${DIM$1}Failed to update ${totalFail} item(s)${RESET$1}`);
+	else if (totalUpToDate > 0 && totalFail === 0) console.log(`${TEXT$1}✓ Everything is up to date${RESET$1}`);
+	if (totalFail > 0) {
+		recordFailure(`Failed to update ${totalFail} item(s)`);
+		console.log(`${DIM$1}Failed to update ${totalFail} item(s)${RESET$1}`);
+	}
 	String(totalSuccess + totalFail);
 	console.log();
 }
@@ -6836,6 +7268,7 @@ async function installReaderSkill(workspace, note) {
 }
 async function setupDbReader({ workspace, note }) {
 	M.step("Setting up read-only prod database access…");
+	setStep("db-reader:aws-identity");
 	const identity = aws([
 		"sts",
 		"get-caller-identity",
@@ -6854,6 +7287,7 @@ async function setupDbReader({ workspace, note }) {
 		return;
 	}
 	const secretId = `${DB_READER_SECRET_PREFIX}${iamUser}`;
+	setStep("db-reader:fetch-secret");
 	const fetched = aws([
 		"secretsmanager",
 		"get-secret-value",
@@ -6885,16 +7319,19 @@ async function setupDbReader({ workspace, note }) {
 		note(`Prod DB access not set up — ${secretId} does not hold a valid username and password.`);
 		return;
 	}
+	setStep("db-reader:keychain");
 	if (!storeInKeychain(secret.username, secret.password)) {
 		note(`Prod DB access not set up — the Keychain write failed. Add it by hand: ${import_picocolors.default.cyan(`security add-generic-password -U -s ${DB_READER_SERVICE} -a ${secret.username} -w`)} (prompts for the password).`);
 		return;
 	}
 	writeConfig(secret.username);
 	M.success(`Keychain entry ${DB_READER_SERVICE} stored for ${secret.username}`);
+	setStep("db-reader:ca-bundle");
 	if (!downloadCaBundle()) {
 		note(`Prod DB access not set up — the RDS CA bundle download failed. Run: ${import_picocolors.default.cyan(`curl -sSfo ${dbReaderCaPath()} ${RDS_CA_URL}`)}`);
 		return;
 	}
+	setStep("db-reader:install-scripts");
 	const installError = await installScripts();
 	if (installError) {
 		note(`Prod DB access not set up — ${installError}. Re-run once the catalog is reachable.`);
@@ -6902,6 +7339,7 @@ async function setupDbReader({ workspace, note }) {
 	}
 	M.success(`Installed ${DB_READER_SCRIPTS.join(" and ")} in ${dbReaderBinDir()}`);
 	if (!(process.env.PATH ?? "").split(delimiter).includes(dbReaderBinDir())) M.warn(`${dbReaderBinDir()} is not on your PATH. Add ${import_picocolors.default.cyan("export PATH=\"$HOME/.local/bin:$PATH\"")} to ~/.zshrc.`);
+	setStep("db-reader:verify");
 	const verify = runVerify$1();
 	if (!verify.ok) {
 		note(`Prod DB access not enabled — ${import_picocolors.default.cyan("pruff-db-verify")} failed. Run ${import_picocolors.default.cyan(`${join(dbReaderBinDir(), "pruff-db-verify")} ${DB_READER_VERIFY_DATABASE}`)} and share the output with the infra owner.`);
@@ -6909,6 +7347,7 @@ async function setupDbReader({ workspace, note }) {
 		return;
 	}
 	M.success("Read-only access verified");
+	setStep("db-reader:settings");
 	if (mergeAllowlist(workspace) === "invalid") note(`Add ${import_picocolors.default.cyan(DB_READER_ALLOW_ENTRY)} to permissions.allow in ${join(workspace, ".claude", "settings.json")} by hand — the file is not valid JSON.`);
 	const hooks = await installHooks(["prod-db-guard"]);
 	for (const failure of hooks.failed) note(`Hook ${failure.name} not installed: ${failure.reason}`);
@@ -7041,9 +7480,9 @@ function renderBlockLogoFrame(lines, palette, pos, band) {
 		return out + RESET;
 	}).join("\n");
 }
-async function showBlockLogo(lines, letterCuts, { slow = false, palette = BLUES } = {}) {
+async function showBlockLogo(lines, letterCuts, { slow = false, palette = BLUES, animate = true } = {}) {
 	console.log();
-	if (!canAnimate()) {
+	if (!animate || !canAnimate()) {
 		printStaticBlockLogo(lines, palette);
 		return;
 	}
@@ -7815,6 +8254,7 @@ function catalogInstallNames(rawIndex) {
 }
 const issues = [];
 function note(issue) {
+	recordFailure(issue);
 	issues.push(issue);
 }
 async function runOnboarding(args) {
@@ -7829,6 +8269,7 @@ async function runOnboarding(args) {
 	Ie(import_picocolors.default.bold("Pruff onboarding"));
 	issues.length = 0;
 	if (args.includes("--db-access")) {
+		setStep("db-access");
 		await setupDbReader({
 			workspace: await resolveWorkspace(args),
 			note
@@ -7837,28 +8278,51 @@ async function runOnboarding(args) {
 		Se(issues.length === 0 ? import_picocolors.default.green("Done.") : import_picocolors.default.yellow("Prod DB access is not complete — fix the items above and re-run."));
 		return;
 	}
+	setStep("preflight");
 	if (!await preflight()) {
+		recordFailure(lastLoggedError() || "Preflight failed");
 		Se(import_picocolors.default.yellow("Onboarding stopped — fix the items above and re-run."));
 		return;
 	}
+	setStep("install-claude-code");
 	installClaudeCode();
+	setStep("obsidian");
 	ensureObsidian();
+	setStep("bun");
 	ensureBun();
+	setStep("workspace");
 	const workspace = await resolveWorkspace(args);
 	mkdirSync(workspace, { recursive: true });
 	M.success(`Workspace ${import_picocolors.default.cyan(workspace)}`);
+	setStep("clone-knowledge");
 	cloneKnowledge(workspace);
-	for (const repo of MAIN_REPOS) cloneRepo(repo, workspace);
-	for (const repo of MAIN_REPOS) installDeps(repo, workspace);
+	for (const repo of MAIN_REPOS) {
+		setStep(`clone:${repo.name}`);
+		cloneRepo(repo, workspace);
+	}
+	for (const repo of MAIN_REPOS) {
+		setStep(`install-deps:${repo.name}`);
+		installDeps(repo, workspace);
+	}
+	setStep("workspace-config");
 	writeWorkspaceClaudeMd(workspace);
 	writeHarnessConfig(workspace);
+	setStep("install-catalog");
 	await installCatalog(workspace);
+	setStep("install-harness");
 	await installHarness(workspace);
-	if (await shouldSetupDatabase(args)) await setupLocalEnvironment(join(workspace, "Pruff-server"));
-	if (await shouldSetupDbAccess(args)) await setupDbReader({
-		workspace,
-		note
-	});
+	if (await shouldSetupDatabase(args)) {
+		setStep("local-database");
+		await setupLocalEnvironment(join(workspace, "Pruff-server"));
+	}
+	if (await shouldSetupDbAccess(args)) {
+		setStep("db-access");
+		await setupDbReader({
+			workspace,
+			note
+		});
+	}
+	setStep("guidance");
 	await showGuidance(workspace);
 	showTeamCredentialsAsk(workspace);
 	showIssues();
@@ -7867,6 +8331,7 @@ async function runOnboarding(args) {
 	else Se(`${import_picocolors.default.yellow(`Finished with ${issues.length} issue${issues.length === 1 ? "" : "s"}.`)} Fix them and re-run — every step is idempotent.`);
 }
 async function preflight() {
+	setStep("preflight:tools");
 	const missing = [
 		"git",
 		"node",
@@ -7877,9 +8342,13 @@ async function preflight() {
 		return false;
 	}
 	M.success("git · node · npm present");
+	setStep("preflight:gh");
 	if (!ensureGh()) return false;
+	setStep("preflight:gh-auth");
 	if (!await ensureGitHubAuth()) return false;
+	setStep("preflight:git-credentials");
 	if (!ensureGitCredentialHelper()) return false;
+	setStep("preflight:packages-scope");
 	ensurePackagesScope();
 	return true;
 }
@@ -9609,7 +10078,10 @@ const LETTER_CUTS = [
 	41
 ];
 async function showLogo(slow = false) {
-	await showBlockLogo(LOGO_LINES, LETTER_CUTS, { slow });
+	await showBlockLogo(LOGO_LINES, LETTER_CUTS, {
+		slow,
+		animate: slow
+	});
 }
 const BUILDING_LINES = [
 	"██████╗ ██╗   ██╗██╗██╗     ██████╗ ██╗███╗   ██╗ ██████╗ ",
@@ -9757,6 +10229,12 @@ ${BOLD}Onboarding Options:${RESET}
   --no-db              Skip the local database step
   --db-access          Only set up read-only prod database access (needs AWS credentials)
 
+${BOLD}Troubleshooting:${RESET}
+  doctor               Print a copy-pasteable diagnostic block (versions, GitHub auth,
+                       catalog reachability, install target). Exit 1 if gh is not logged
+                       in or the catalog does not resolve. The same block is printed when
+                       add, update, rules add, agents add or onboarding fails.
+
 ${BOLD}Updates:${RESET}
   update [skills...]   Update skills to latest versions (alias: upgrade)
                      Also syncs ALL installed subagents with the catalog,
@@ -9948,8 +10426,7 @@ async function main() {
 		case "add": {
 			if (!inAgent) await showLogo();
 			const { source: addSource, options: addOpts } = parseAddOptions(restArgs);
-			await runAdd(addSource, addOpts);
-			break;
+			return withDiagnostics("add", restArgs, () => runAdd(addSource, addOpts));
 		}
 		case "use": {
 			const { source: useSource, options: useOptions, errors: useErrors } = parseUseOptions(restArgs);
@@ -9959,13 +10436,11 @@ async function main() {
 		case "agents":
 		case "agent":
 			if (!inAgent) await showLogo();
-			await runAgents(restArgs);
-			break;
+			return withDiagnostics("agents", restArgs, () => runAgents(restArgs));
 		case "rules":
 		case "rule":
 			if (!inAgent) await showLogo();
-			await runRules(restArgs);
-			break;
+			return withDiagnostics("rules", restArgs, () => runRules(restArgs));
 		case "hooks":
 		case "hook":
 			if (!inAgent) await showLogo();
@@ -9985,8 +10460,8 @@ async function main() {
 				await showLogo(true);
 				await showTagline(true);
 			}
-			await runOnboarding(restArgs);
-			break;
+			return withDiagnostics("onboarding", restArgs, () => runOnboarding(restArgs));
+		case "doctor": return runDoctor();
 		case "remove":
 		case "rm":
 		case "r":
@@ -10010,9 +10485,7 @@ async function main() {
 			break;
 		case "check":
 		case "update":
-		case "upgrade":
-			await runUpdate(restArgs);
-			break;
+		case "upgrade": return withDiagnostics("update", restArgs, () => runUpdate(restArgs));
 		case "--help":
 		case "-h":
 			showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {