pruff-skills 0.1.0 → 0.3.0

package/README.md

@@ -38,6 +38,15 @@ The catalog also ships **Claude Code subagents**. `find` lists them alongside sk
 npx pruff-skills agents add <name>      # → .claude/agents/  (add -g for ~/.claude/agents/)
 ```
 
+It also ships **coding-convention rules** for the Pruff repos, each tagged by scope
+(`client` / `server` / `common`, where `common` applies to both). `find` lists them tagged
+`[rule]`. Install one by name, or a whole repo's set at once:
+
+```bash
+npx pruff-skills rules add <name>          # → .claude/rules/  (add -g for ~/.claude/rules/)
+npx pruff-skills rules add --scope server  # all server + common rules (client/server pull in common)
+```
+
 ## Use a Skill Without Installing
 
 Generate a prompt for one skill, or start a supported coding agent interactively:

package/dist/_chunks/libs/@clack/prompts.mjs

@@ -1,5 +1,5 @@
 import { __toESM } from "../../rolldown-runtime.mjs";
-import { LD, SD, _D, dD, fD, require_picocolors, require_src } from "./core.mjs";
+import { LD, RD, SD, _D, dD, fD, require_picocolors, require_src } from "./core.mjs";
 import { stripVTControlCharacters } from "node:util";
 import y from "node:process";
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
@@ -24,7 +24,29 @@ const V = ce(), u = (t, n) => V ? t : n, le = u("◆", "*"), L = u("■", "x"),
 		const j = v === 0 && $, E = v === f.length - 1 && g;
 		return j || E ? import_picocolors.default.dim("...") : i(p, v + l === n);
 	});
-}, ye = (t) => {
+}, he = (t) => new RD({
+	validate: t.validate,
+	placeholder: t.placeholder,
+	defaultValue: t.defaultValue,
+	initialValue: t.initialValue,
+	render() {
+		const n = `${import_picocolors.default.gray(o)}
+${b(this.state)}  ${t.message}
+`, r = t.placeholder ? import_picocolors.default.inverse(t.placeholder[0]) + import_picocolors.default.dim(t.placeholder.slice(1)) : import_picocolors.default.inverse(import_picocolors.default.hidden("_")), i = this.value ? this.valueWithCursor : r;
+		switch (this.state) {
+			case "error": return `${n.trim()}
+${import_picocolors.default.yellow(o)}  ${i}
+${import_picocolors.default.yellow(d)}  ${import_picocolors.default.yellow(this.error)}
+`;
+			case "submit": return `${n}${import_picocolors.default.gray(o)}  ${import_picocolors.default.dim(this.value || t.placeholder)}`;
+			case "cancel": return `${n}${import_picocolors.default.gray(o)}  ${import_picocolors.default.strikethrough(import_picocolors.default.dim(this.value ?? ""))}${this.value?.trim() ? `
+${import_picocolors.default.gray(o)}` : ""}`;
+			default: return `${n}${import_picocolors.default.cyan(o)}  ${i}
+${import_picocolors.default.cyan(d)}
+`;
+		}
+	}
+}).prompt(), ye = (t) => {
 	const n = t.active ?? "Yes", r = t.inactive ?? "No";
 	return new dD({
 		active: n,
@@ -329,4 +351,4 @@ ${J}${i.trimStart()}`), r = 3 + stripVTControlCharacters(i.trimStart()).length);
 		}
 	};
 };
-export { Ie, M, Me, Se, Y, be, fe, ve, xe, ye };
+export { Ie, M, Me, Se, Y, be, fe, he, ve, xe, ye };

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { __toESM } from "./_chunks/rolldown-runtime.mjs";
 import { pD, require_picocolors } from "./_chunks/libs/@clack/core.mjs";
-import { Ie, M, Me, Se, Y, be, fe, ve, xe, ye } from "./_chunks/libs/@clack/prompts.mjs";
+import { Ie, M, Me, Se, Y, be, fe, he, ve, xe, ye } from "./_chunks/libs/@clack/prompts.mjs";
 import { esm_default } from "./_chunks/libs/simple-git.mjs";
 import { xdgConfig } from "./_chunks/libs/xdg-basedir.mjs";
 import { require_dist } from "./_chunks/libs/@vercel/detect-agent.mjs";
@@ -16,7 +16,7 @@ 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 } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import { createHash as createHash$1 } from "node:crypto";
 import { gunzipSync, inflateRawSync } from "node:zlib";
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
@@ -434,7 +434,7 @@ const CLONE_TIMEOUT_MS = (() => {
 	const parsed = Number.parseInt(raw, 10);
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
 })();
-const execFileAsync$2 = promisify(execFile);
+const execFileAsync$3 = promisify(execFile);
 var GitCloneError = class extends Error {
 	url;
 	isTimeout;
@@ -513,7 +513,7 @@ async function resetTempDir(dir) {
 async function tryGhClone(repo, tempDir, ref) {
 	let cloneTarget = repo.slug;
 	try {
-		const { stdout, stderr } = await execFileAsync$2("gh", [
+		const { stdout, stderr } = await execFileAsync$3("gh", [
 			"auth",
 			"status",
 			"-h",
@@ -530,7 +530,7 @@ async function tryGhClone(repo, tempDir, ref) {
 	} catch {
 		return false;
 	}
-	await execFileAsync$2("gh", [
+	await execFileAsync$3("gh", [
 		"repo",
 		"clone",
 		cloneTarget,
@@ -555,7 +555,7 @@ function buildGitHubAuthError(url, repo, message) {
 	if (repo) return `Authentication failed for ${url}.\n  - For private repos, ensure you have access\n  - Retry with SSH: npx pruff-skills add ${repo.sshUrl}\n  - Check access with: gh auth status -h github.com or ssh -T git@github.com`;
 	return `Authentication failed for ${url}.\n  - For private repos, ensure you have access\n  - For SSH: Check your keys with 'ssh -T git@github.com'\n  - For HTTPS: Run 'gh auth login' or configure git credentials`;
 }
-async function cloneRepo(url, ref) {
+async function cloneRepo$1(url, ref) {
 	const tempDir = await mkdtemp(join(tmpdir(), "skills-"));
 	const cloneOptions = ref ? [
 		"--depth",
@@ -3467,7 +3467,7 @@ async function runAdd(args, options = {}) {
 				spinner.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
 			} else {
 				spinner.start("Cloning repository...");
-				tempDir = await cloneRepo(parsed.url, parsed.ref);
+				tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 				spinner.stop("Repository cloned");
 				spinner.start("Discovering skills...");
 				skills = await discoverSkills(tempDir, parsed.subpath, {
@@ -3477,7 +3477,7 @@ async function runAdd(args, options = {}) {
 			}
 		} else {
 			spinner.start("Cloning repository...");
-			tempDir = await cloneRepo(parsed.url, parsed.ref);
+			tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 			spinner.stop("Repository cloned");
 			spinner.start("Discovering skills...");
 			skills = await discoverSkills(tempDir, parsed.subpath, {
@@ -3997,7 +3997,7 @@ function parseAddOptions(args) {
 		options
 	};
 }
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 const claudeAgentsDir = (global) => global ? join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "agents") : join(process.cwd(), ".claude", "agents");
 async function fetchAgentFile(source, name) {
 	const rel = `agents/${name}.md`;
@@ -4006,7 +4006,7 @@ async function fetchAgentFile(source, name) {
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	}
 	if (/^[^/]+\/[^/]+$/.test(source)) try {
-		const { stdout } = await execFileAsync$1("gh", [
+		const { stdout } = await execFileAsync$2("gh", [
 			"api",
 			`repos/${source}/contents/${rel}`,
 			"--jq",
@@ -4020,7 +4020,7 @@ async function fetchAgentFile(source, name) {
 		return null;
 	}
 	try {
-		const file = join(await cloneRepo(source), rel);
+		const file = join(await cloneRepo$1(source), rel);
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	} catch {
 		return null;
@@ -4103,6 +4103,152 @@ async function runAgents(args) {
 	console.log(`Unknown agents command: ${sub}`);
 	console.log(AGENTS_HELP);
 }
+const execFileAsync$1 = promisify(execFile);
+const RULE_SCOPES = [
+	"client",
+	"server",
+	"common"
+];
+const claudeRulesDir = (global) => global ? join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude"), "rules") : join(process.cwd(), ".claude", "rules");
+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$1("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`);
+async function fetchRuleIndex(source) {
+	const raw = await fetchFromCatalog(source, ".well-known/agent-skills/index.json");
+	if (!raw) return [];
+	try {
+		return JSON.parse(raw).rules ?? [];
+	} catch {
+		return [];
+	}
+}
+function expandScopes(scopes) {
+	const set = new Set(scopes);
+	if (set.has("client") || set.has("server")) set.add("common");
+	return set;
+}
+function parseRulesOptions(args) {
+	const names = [];
+	const options = {};
+	const pushScope = (value) => {
+		if (value && RULE_SCOPES.includes(value)) (options.scopes ??= []).push(value);
+		else M.warn(`Ignoring invalid --scope value: ${import_picocolors.default.yellow(value ?? "(missing)")}`);
+	};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "-g" || arg === "--global") options.global = true;
+		else if (arg === "-y" || arg === "--yes") options.yes = true;
+		else if (arg === "--all") options.all = true;
+		else if (arg === "-s" || arg === "--scope") pushScope(args[++i]);
+		else if (arg.startsWith("--scope=")) pushScope(arg.slice(8));
+		else if (!arg.startsWith("-")) names.push(arg);
+	}
+	return {
+		names,
+		options
+	};
+}
+async function addRules(names, options) {
+	const source = PRUFF_CATALOG;
+	const targetDir = claudeRulesDir(options.global ?? false);
+	Ie(import_picocolors.default.cyan("pruff-skills rules"));
+	let toInstall = names.filter(Boolean);
+	if (options.all || options.scopes?.length) {
+		const index = await fetchRuleIndex(source);
+		if (index.length === 0) {
+			M.error(`Could not read the rules catalog (${source}).`);
+			process.exit(1);
+		}
+		const wanted = options.all ? null : expandScopes(options.scopes ?? []);
+		const matched = index.filter((r) => wanted ? !!r.scope && wanted.has(r.scope) : true).map((r) => r.name);
+		toInstall = Array.from(new Set([...toInstall, ...matched]));
+	}
+	if (toInstall.length === 0) {
+		M.error("Specify a rule name, a --scope, or --all.");
+		M.message(import_picocolors.default.dim("e.g. `pruff-skills rules add service-patterns`"));
+		M.message(import_picocolors.default.dim("or   `pruff-skills rules add --scope server`"));
+		M.message(import_picocolors.default.dim("Browse them with `npx pruff-skills find`."));
+		process.exit(1);
+	}
+	await mkdir(targetDir, { recursive: true });
+	const installed = [];
+	for (const name of toInstall) {
+		if (!isBareSkillName(name)) {
+			M.warn(`Skipping invalid rule name: ${import_picocolors.default.yellow(name)}`);
+			continue;
+		}
+		const content = await fetchRuleFile(source, name);
+		if (!content) {
+			M.error(`Rule ${import_picocolors.default.yellow(name)} not found in the catalog (${source}).`);
+			continue;
+		}
+		const dest = join(targetDir, `${sanitizeName(name)}.md`);
+		await writeFile(dest, stripFrontmatter(content));
+		installed.push(dest);
+		M.success(`${import_picocolors.default.green(name)} → ${dest}`);
+	}
+	if (installed.length === 0) {
+		Se(import_picocolors.default.red("No rules installed."));
+		process.exit(1);
+	}
+	Se(`Installed ${installed.length} rule${installed.length === 1 ? "" : "s"} into ${import_picocolors.default.dim(targetDir)}.`);
+}
+const RULES_HELP = `${import_picocolors.default.bold("Usage:")} pruff-skills rules <command> [options]
+
+${import_picocolors.default.bold("Commands:")}
+  add <name...>      Install one or more rules into .claude/rules/
+
+${import_picocolors.default.bold("Options:")}
+  -s, --scope <s>    Install every rule in a scope: client | server | common
+                     (client/server also pull in common). Repeatable.
+  --all              Install every rule in the catalog
+  -g, --global       Install to ~/.claude/rules/ instead of the project
+  -y, --yes          Skip prompts
+
+${import_picocolors.default.bold("Examples:")}
+  pruff-skills rules add service-patterns bigint-handling
+  pruff-skills rules add --scope server      ${import_picocolors.default.dim("# all server + common rules")}
+  pruff-skills rules add --scope client -g
+  pruff-skills rules add --all
+
+Browse available rules with ${import_picocolors.default.cyan("npx pruff-skills find")}.`;
+async function runRules(args) {
+	const sub = args[0];
+	if (!sub || sub === "--help" || sub === "-h") {
+		console.log(RULES_HELP);
+		return;
+	}
+	const { names, options } = parseRulesOptions(sub === "add" || sub === "a" || sub === "install" || sub === "i" ? args.slice(1) : args);
+	await addRules(names, options);
+}
 const execFileAsync = promisify(execFile);
 const RESET$3 = "\x1B[0m";
 const BOLD$3 = "\x1B[1m";
@@ -4111,6 +4257,7 @@ const TEXT$2 = "\x1B[38;5;145m";
 const CYAN$1 = "\x1B[36m";
 const GREEN = "\x1B[32m";
 const MAGENTA = "\x1B[35m";
+const BLUE$1 = "\x1B[38;2;110;139;255m";
 const CATALOG_SOURCE = process.env.PRUFF_SKILLS_CATALOG || "Pruff-Tech/pruff-skills";
 async function fetchCatalogIndex(source) {
 	const rel = ".well-known/agent-skills/index.json";
@@ -4149,6 +4296,10 @@ function agentInstalled(name) {
 	const globalClaude = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
 	return existsSync(join(process.cwd(), ".claude", "agents", `${name}.md`)) || existsSync(join(globalClaude, "agents", `${name}.md`));
 }
+function ruleInstalled(name) {
+	const globalClaude = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+	return existsSync(join(process.cwd(), ".claude", "rules", `${name}.md`)) || existsSync(join(globalClaude, "rules", `${name}.md`));
+}
 let catalogCache = null;
 async function loadCatalog() {
 	if (catalogCache) return catalogCache;
@@ -4157,6 +4308,8 @@ async function loadCatalog() {
 		const installedSkills = await installedSkillNames();
 		const toEntry = (e, kind) => {
 			const name = sanitizeMetadata(e.name);
+			const badge = kind === "rule" ? e.scope : e.category;
+			const installed = kind === "agent" ? agentInstalled(name) : kind === "rule" ? ruleInstalled(name) : installedSkills.has(name);
 			return {
 				name,
 				slug: name,
@@ -4164,11 +4317,15 @@ async function loadCatalog() {
 				installs: 0,
 				description: sanitizeMetadata(e.description || ""),
 				kind,
-				category: e.category ? sanitizeMetadata(e.category) : void 0,
-				installed: kind === "agent" ? agentInstalled(name) : installedSkills.has(name)
+				category: badge ? sanitizeMetadata(badge) : void 0,
+				installed
 			};
 		};
-		catalogCache = [...(index.skills ?? []).map((e) => toEntry(e, "skill")), ...(index.agents ?? []).map((e) => toEntry(e, "agent"))];
+		catalogCache = [
+			...(index.skills ?? []).map((e) => toEntry(e, "skill")),
+			...(index.agents ?? []).map((e) => toEntry(e, "agent")),
+			...(index.rules ?? []).map((e) => toEntry(e, "rule"))
+		];
 	} catch {
 		catalogCache = [];
 	}
@@ -4199,7 +4356,7 @@ async function runSearchPrompt(kind, initialQuery = "") {
 	let query = initialQuery;
 	let loading = false;
 	let lastRenderedLines = 0;
-	const noun = kind === "agent" ? "subagents" : "skills";
+	const noun = kind === "agent" ? "subagents" : kind === "rule" ? "rules" : "skills";
 	if (process.stdin.isTTY) process.stdin.setRawMode(true);
 	readline.emitKeypressEvents(process.stdin);
 	process.stdin.resume();
@@ -4316,10 +4473,10 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 			console.log(`${DIM$3}Nothing in the catalog matches "${query}"${RESET$3}`);
 			return;
 		}
-		console.log(`${DIM$3}Install a skill with${RESET$3} npx pruff-skills add <name>${DIM$3}, a subagent with${RESET$3} npx pruff-skills agents add <name>`);
+		console.log(`${DIM$3}Install a skill with${RESET$3} npx pruff-skills add <name>${DIM$3}, a subagent with${RESET$3} npx pruff-skills agents add <name>${DIM$3}, a rule with${RESET$3} npx pruff-skills rules add <name>`);
 		console.log();
 		for (const skill of results.slice(0, 10)) {
-			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$3}` : ` ${CYAN$1}[skill]${RESET$3}`;
+			const kindBadge = skill.kind === "agent" ? ` ${MAGENTA}[subagent]${RESET$3}` : skill.kind === "rule" ? ` ${BLUE$1}[rule]${RESET$3}` : ` ${CYAN$1}[skill]${RESET$3}`;
 			console.log(`${TEXT$2}${skill.name}${RESET$3}${kindBadge}${rowBadge(skill)}`);
 			if (skill.description) console.log(`${DIM$3}└ ${skill.description}${RESET$3}`);
 			console.log();
@@ -4335,19 +4492,28 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	const all = await searchSkillsAPI("");
 	const skillCount = all.filter((s) => s.kind === "skill").length;
 	const agentCount = all.filter((s) => s.kind === "agent").length;
+	const ruleCount = all.filter((s) => s.kind === "rule").length;
 	let selected = "back";
 	while (selected === "back") {
 		const kindChoice = await ve({
 			message: "What are you looking for?",
-			options: [{
-				value: "skill",
-				label: "Skills",
-				hint: `${skillCount} available`
-			}, {
-				value: "agent",
-				label: "Subagents",
-				hint: `${agentCount} available`
-			}]
+			options: [
+				{
+					value: "skill",
+					label: "Skills",
+					hint: `${skillCount} available`
+				},
+				{
+					value: "agent",
+					label: "Subagents",
+					hint: `${agentCount} available`
+				},
+				{
+					value: "rule",
+					label: "Rules",
+					hint: `${ruleCount} available`
+				}
+			]
 		});
 		if (pD(kindChoice)) {
 			console.log(`${DIM$3}Search cancelled${RESET$3}`);
@@ -4365,6 +4531,7 @@ ${DIM$3}  2) npx pruff-skills add <skill>${RESET$3}`;
 	const skillName = selected.name;
 	console.log();
 	if (selected.kind === "agent") await addAgents([skillName], {});
+	else if (selected.kind === "rule") await addRules([skillName], {});
 	else {
 		const pkg = selected.source || selected.slug;
 		console.log(`${TEXT$2}Installing ${BOLD$3}${skillName}${RESET$3} from ${DIM$3}${pkg}${RESET$3}...`);
@@ -5299,7 +5466,7 @@ async function updateGlobalSkills(options = {}) {
 				}
 				continue;
 			}
-			tempDir = await cloneRepo(sourceUrl, firstEntry.ref);
+			tempDir = await cloneRepo$1(sourceUrl, firstEntry.ref);
 			const discoveredPaths = (await discoverSkills(tempDir)).map((skill) => {
 				return join(relative(tempDir, skill.path), "SKILL.md").split(sep).join("/");
 			});
@@ -5455,7 +5622,7 @@ async function updateProjectSkills(options = {}) {
 		let tempDir = null;
 		let deletedSkills = [];
 		try {
-			tempDir = await cloneRepo(sourceUrl, ref);
+			tempDir = await cloneRepo$1(sourceUrl, ref);
 			const discoveredPaths = (await discoverSkills(tempDir)).map((s) => {
 				return join(relative(tempDir, s.path), "SKILL.md").split(sep).join("/");
 			});
@@ -5674,14 +5841,14 @@ async function runUse(sourceArgs, options = {}, parseErrors = []) {
 				});
 				if (blobResult) skills = blobResult.skills;
 				else {
-					cloneTempDir = await cloneRepo(parsed.url, parsed.ref);
+					cloneTempDir = await cloneRepo$1(parsed.url, parsed.ref);
 					skills = await discoverSkills(cloneTempDir, parsed.subpath, {
 						includeInternal,
 						fullDepth: options.fullDepth
 					});
 				}
 			} else {
-				cloneTempDir = await cloneRepo(parsed.url, parsed.ref);
+				cloneTempDir = await cloneRepo$1(parsed.url, parsed.ref);
 				skills = await discoverSkills(cloneTempDir, parsed.subpath, {
 					includeInternal,
 					fullDepth: options.fullDepth
@@ -5904,6 +6071,291 @@ function fail(message) {
 	process.exit(1);
 }
 var UseCommandError = class extends Error {};
+const RESET = "\x1B[0m";
+const DIM = "\x1B[38;5;102m";
+const BLUES = [
+	"\x1B[38;2;110;139;255m",
+	"\x1B[38;2;91;118;249m",
+	"\x1B[38;2;72;97;242m",
+	"\x1B[38;2;53;77;236m",
+	"\x1B[38;2;34;56;229m",
+	"\x1B[38;2;15;35;223m"
+];
+const SWEEP = "\x1B[38;2;214;226;255m";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function canAnimate() {
+	return !!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM;
+}
+function columnColor(col, width) {
+	return BLUES[Math.min(BLUES.length - 1, Math.floor(col / Math.max(1, width - 1) * BLUES.length))];
+}
+function renderSweepLine(chars, indent, pos, band) {
+	let out = indent;
+	let mode = "";
+	for (let c = 0; c < chars.length; c++) {
+		const color = c >= pos && c < pos + band ? SWEEP : columnColor(c, chars.length);
+		if (color !== mode) {
+			out += color;
+			mode = color;
+		}
+		out += chars[c];
+	}
+	return out + RESET;
+}
+async function sweepLine(text, { slow = false, indent = "  " } = {}) {
+	const chars = Array.from(text);
+	const width = chars.length;
+	const band = 5;
+	const step = slow ? 2 : 3;
+	const ms = slow ? 42 : 24;
+	if (!canAnimate()) {
+		console.log(renderSweepLine(chars, indent, -1, 0));
+		return;
+	}
+	process.stdout.write("\x1B[?25l");
+	try {
+		let first = true;
+		for (let pos = -5; pos <= width; pos += step) {
+			if (!first) process.stdout.write("\x1B[1A");
+			process.stdout.write("\r" + renderSweepLine(chars, indent, pos, band) + "\n");
+			first = false;
+			await sleep(ms);
+		}
+		process.stdout.write("\x1B[1A\r" + renderSweepLine(chars, indent, -1, 0) + "\n");
+	} finally {
+		process.stdout.write("\x1B[?25h");
+	}
+}
+const CLAUDE_CODE_PKG = "@anthropic-ai/claude-code";
+const KNOWLEDGE_REPO = "https://github.com/Pruff-Tech/pruff-knowledge";
+const KNOWLEDGE_DIR = "Pruff Knowledge";
+const DEFAULT_WORKSPACE = join(homedir(), "pruff");
+const MAIN_REPOS = [{
+	name: "Pruff-server",
+	url: "https://github.com/Pruff-Tech/Pruff-server"
+}, {
+	name: "Pruff-Client",
+	url: "https://github.com/Pruff-Tech/Pruff-Client"
+}];
+const CORE_SKILLS = [
+	"commit",
+	"create-pr",
+	"linear",
+	"start-issue",
+	"handoff",
+	"pruff-logs",
+	"pruff-pr-review",
+	"review-pr-comments",
+	"react-doctor"
+];
+const CORE_AGENTS = [
+	"codebase-navigator",
+	"db-query-reviewer",
+	"pruff-logs-investigator"
+];
+async function runOnboarding(args) {
+	if (process.platform !== "darwin") {
+		M.error(`${import_picocolors.default.bold("onboarding")} currently supports macOS only (detected ${import_picocolors.default.cyan(process.platform)}).`);
+		return;
+	}
+	Ie(import_picocolors.default.bold("Pruff onboarding"));
+	installClaudeCode();
+	ensureObsidian();
+	const workspace = await resolveWorkspace(args);
+	mkdirSync(workspace, { recursive: true });
+	M.success(`Workspace ${import_picocolors.default.cyan(workspace)}`);
+	cloneKnowledge(workspace);
+	for (const repo of MAIN_REPOS) cloneRepo(repo.name, repo.url, workspace);
+	await installCatalog(workspace);
+	await showGuidance(workspace);
+	Se(`${import_picocolors.default.green("Done.")} Welcome to Pruff — happy building.`);
+}
+function has(cmd) {
+	return spawnSync("command", ["-v", cmd], {
+		shell: true,
+		stdio: "ignore"
+	}).status === 0;
+}
+function run(cmd, args, cwd) {
+	return spawnSync(cmd, args, {
+		stdio: "inherit",
+		cwd
+	}).status === 0;
+}
+function expandHome(input) {
+	return input.startsWith("~") ? join(homedir(), input.slice(1)) : input;
+}
+function installClaudeCode() {
+	if (has("claude")) {
+		M.success("Claude Code already installed");
+		return;
+	}
+	const s = Y();
+	s.start("Installing Claude Code…");
+	if (run("npm", [
+		"install",
+		"-g",
+		CLAUDE_CODE_PKG
+	])) s.stop("Claude Code installed");
+	else {
+		s.stop(import_picocolors.default.yellow("Claude Code install failed"));
+		M.warn(`Install it manually: ${import_picocolors.default.cyan(`npm i -g ${CLAUDE_CODE_PKG}`)}`);
+	}
+}
+function ensureObsidian() {
+	if (existsSync("/Applications/Obsidian.app")) {
+		M.success("Obsidian already installed");
+		return;
+	}
+	if (!has("brew")) {
+		M.warn(`Obsidian not found and Homebrew is unavailable.\n  Install it from ${import_picocolors.default.cyan("https://obsidian.md")} and re-run.`);
+		return;
+	}
+	const s = Y();
+	s.start("Installing Obsidian (brew)…");
+	if (run("brew", [
+		"install",
+		"--cask",
+		"obsidian"
+	])) s.stop("Obsidian installed");
+	else {
+		s.stop(import_picocolors.default.yellow("Obsidian install failed"));
+		M.warn(`Install manually: ${import_picocolors.default.cyan("brew install --cask obsidian")}`);
+	}
+}
+async function resolveWorkspace(args) {
+	const fromArg = args.find((a) => !a.startsWith("-"));
+	if (fromArg) return expandHome(fromArg);
+	if (!process.stdout.isTTY) return DEFAULT_WORKSPACE;
+	const answer = await he({
+		message: "Where should the Pruff workspace live?",
+		placeholder: DEFAULT_WORKSPACE,
+		defaultValue: DEFAULT_WORKSPACE
+	});
+	if (pD(answer)) {
+		xe("Onboarding cancelled.");
+		process.exit(0);
+	}
+	return expandHome((answer || DEFAULT_WORKSPACE).trim());
+}
+function cloneKnowledge(workspace) {
+	const vaultPath = join(workspace, KNOWLEDGE_DIR);
+	const s = Y();
+	if (existsSync(join(vaultPath, ".git"))) {
+		s.start("Updating Pruff knowledge…");
+		const ok = run("git", [
+			"-C",
+			vaultPath,
+			"pull",
+			"--ff-only"
+		]);
+		s.stop(ok ? "Pruff knowledge up to date" : import_picocolors.default.yellow("git pull failed (keeping local copy)"));
+		registerVault(vaultPath);
+		return;
+	}
+	s.start("Cloning Pruff knowledge…");
+	if (run("git", [
+		"clone",
+		KNOWLEDGE_REPO,
+		vaultPath
+	])) {
+		s.stop(`Cloned knowledge to ${import_picocolors.default.dim(vaultPath)}`);
+		registerVault(vaultPath);
+		return;
+	}
+	s.stop(import_picocolors.default.yellow("Knowledge clone failed"));
+	M.warn(`Could not clone ${import_picocolors.default.cyan(KNOWLEDGE_REPO)}.\n  It's private — authenticate first with ${import_picocolors.default.cyan("gh auth login")} (or an SSH key), then re-run.`);
+}
+function cloneRepo(name, url, workspace) {
+	const target = join(workspace, name);
+	if (existsSync(join(target, ".git"))) {
+		M.success(`${name} already cloned`);
+		return;
+	}
+	const s = Y();
+	s.start(`Cloning ${name}…`);
+	if (run("git", [
+		"clone",
+		url,
+		target
+	], workspace)) s.stop(`Cloned ${import_picocolors.default.cyan(name)}`);
+	else {
+		s.stop(import_picocolors.default.yellow(`${name} clone failed`));
+		M.warn(`Could not clone ${name}. Authenticate with ${import_picocolors.default.cyan("gh auth login")} then run:\n  ${import_picocolors.default.dim(`git clone ${url}`)}  (inside ${workspace})`);
+	}
+}
+async function installCatalog(workspace) {
+	const prevCwd = process.cwd();
+	M.step("Installing Pruff rules, agents and skills into the workspace…");
+	try {
+		process.chdir(workspace);
+		await runRules(["add", "--all"]);
+		await runAgents(["add", ...CORE_AGENTS]);
+		await runAdd([PRUFF_CATALOG], {
+			skill: CORE_SKILLS,
+			agent: ["claude-code"],
+			yes: true
+		});
+	} catch (error) {
+		M.warn(`Catalog install hit an error: ${error instanceof Error ? error.message : String(error)}\n  Re-run once authenticated: ${import_picocolors.default.cyan("npx pruff-skills onboarding")}`);
+	} finally {
+		process.chdir(prevCwd);
+	}
+}
+async function showGuidance(workspace) {
+	console.log();
+	await sweepLine("W O R K S P A C E   R E A D Y", { slow: true });
+	console.log();
+	const line = (s) => console.log(`  ${s}`);
+	line(import_picocolors.default.bold("Recommended structure") + import_picocolors.default.dim("  (keep everything under one parent)"));
+	line("");
+	line(`${import_picocolors.default.cyan(workspace)}/`);
+	const tree = [
+		[".claude/", "rules · agents · skills (apply to every repo below)"],
+		[`${KNOWLEDGE_DIR}/`, "Obsidian vault — open it in Obsidian"],
+		["Pruff-server/", "backend"],
+		["Pruff-Client/", "frontend"],
+		["sls-*/", "serverless services — clone as you need them"]
+	];
+	const labelWidth = Math.max(...tree.map(([label]) => label.length)) + 2;
+	tree.forEach(([label, desc], i) => {
+		const connector = i === tree.length - 1 ? "└──" : "├──";
+		line(`${import_picocolors.default.dim(connector)} ${label.padEnd(labelWidth)}${import_picocolors.default.dim(desc)}`);
+	});
+	line("");
+	line(import_picocolors.default.bold("Next steps"));
+	line(`${import_picocolors.default.dim("1.")} Open ${import_picocolors.default.bold("Obsidian")} → the ${import_picocolors.default.cyan(KNOWLEDGE_DIR)} vault is registered and ready.`);
+	line(`${import_picocolors.default.dim("2.")} Start Claude Code from ${import_picocolors.default.cyan(workspace)} so the shared ${import_picocolors.default.dim(".claude/")} applies everywhere.`);
+	line(`${import_picocolors.default.dim("3.")} Backend:  ${import_picocolors.default.dim("cd Pruff-server && npm i && npm run local")}`);
+	line(`${import_picocolors.default.dim("4.")} Frontend: ${import_picocolors.default.dim("cd Pruff-Client && yarn && yarn start-local")}`);
+	line(`${import_picocolors.default.dim("5.")} Clone any serverless service into this folder with ${import_picocolors.default.dim("git clone <repo>")}.`);
+	console.log();
+}
+function registerVault(vaultPath) {
+	const dir = join(homedir(), "Library", "Application Support", "obsidian");
+	const configPath = join(dir, "obsidian.json");
+	let config = { vaults: {} };
+	if (existsSync(configPath)) try {
+		config = JSON.parse(readFileSync(configPath, "utf-8"));
+		if (!config.vaults) config.vaults = {};
+	} catch {
+		M.warn(`Could not parse ${import_picocolors.default.dim(configPath)} — leaving it untouched.`);
+		return;
+	}
+	else mkdirSync(dir, { recursive: true });
+	if (Object.values(config.vaults).some((v) => v.path === vaultPath)) {
+		M.success("Vault already registered in Obsidian");
+		return;
+	}
+	const id = randomBytes(8).toString("hex");
+	config.vaults[id] = {
+		path: vaultPath,
+		ts: Date.now(),
+		open: true
+	};
+	writeFileSync(configPath, JSON.stringify(config), "utf-8");
+	M.success("Registered vault in Obsidian");
+}
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function getVersion() {
 	try {
@@ -5914,9 +6366,7 @@ function getVersion() {
 	}
 }
 const VERSION = getVersion();
-const RESET = "\x1B[0m";
 const BOLD = "\x1B[1m";
-const DIM = "\x1B[38;5;102m";
 const TEXT = "\x1B[38;5;145m";
 const BLUE = "\x1B[38;2;110;139;255m";
 const LOGO_LINES = [
@@ -5927,16 +6377,6 @@ const LOGO_LINES = [
 	"██║     ██║  ██║╚██████╔╝██║     ██║     ",
 	"╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝     "
 ];
-const BLUES = [
-	"\x1B[38;2;110;139;255m",
-	"\x1B[38;2;91;118;249m",
-	"\x1B[38;2;72;97;242m",
-	"\x1B[38;2;53;77;236m",
-	"\x1B[38;2;34;56;229m",
-	"\x1B[38;2;15;35;223m"
-];
-const SWEEP = "\x1B[38;2;214;226;255m";
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function printStaticLogo() {
 	LOGO_LINES.forEach((line, i) => {
 		console.log(`${BLUES[i]}${line}${RESET}`);
@@ -5972,7 +6412,7 @@ function renderLogoFrame(pos, band) {
 		return out + RESET;
 	}).join("\n");
 }
-async function showLogo() {
+async function showLogo(slow = false) {
 	console.log();
 	if (!(!!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM)) {
 		printStaticLogo();
@@ -5981,6 +6421,9 @@ async function showLogo() {
 	const rows = LOGO_LINES.length;
 	const width = Math.max(...LOGO_LINES.map((l) => Array.from(l).length));
 	const band = 7;
+	const revealMs = slow ? 190 : 90;
+	const step = slow ? 3 : 4;
+	const sweepMs = slow ? 34 : 18;
 	process.stdout.write("\x1B[?25l");
 	try {
 		let first = true;
@@ -5988,15 +6431,75 @@ async function showLogo() {
 			if (!first) process.stdout.write(`\x1b[${rows}A`);
 			process.stdout.write("\r" + renderLogoReveal(cut, width) + "\n");
 			first = false;
-			await sleep(90);
+			await sleep(revealMs);
 		}
-		for (let pos = -7; pos <= width; pos += 4) {
+		for (let pos = -7; pos <= width; pos += step) {
 			process.stdout.write(`\x1b[${rows}A`);
 			process.stdout.write("\r" + renderLogoFrame(pos, band) + "\n");
-			await sleep(18);
+			await sleep(sweepMs);
 		}
 		process.stdout.write(`\x1b[${rows}A\r`);
 		process.stdout.write(LOGO_LINES.map((line, i) => `${BLUES[i]}${line}${RESET}`).join("\n") + "\n");
+		if (slow) await sleep(500);
+	} finally {
+		process.stdout.write("\x1B[?25h");
+	}
+}
+const TAGLINE_BLOCKS = [[
+	"██████╗ ██╗   ██╗██╗██╗     ██████╗ ██╗███╗   ██╗ ██████╗ ",
+	"██╔══██╗██║   ██║██║██║     ██╔══██╗██║████╗  ██║██╔════╝ ",
+	"██████╔╝██║   ██║██║██║     ██║  ██║██║██╔██╗ ██║██║  ███╗",
+	"██╔══██╗██║   ██║██║██║     ██║  ██║██║██║╚██╗██║██║   ██║",
+	"██████╔╝╚██████╔╝██║███████╗██████╔╝██║██║ ╚████║╚██████╔╝",
+	"╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ "
+], [
+	"███████╗██╗███╗   ██╗████████╗███████╗ ██████╗██╗  ██╗███████╗",
+	"██╔════╝██║████╗  ██║╚══██╔══╝██╔════╝██╔════╝██║  ██║██╔════╝",
+	"█████╗  ██║██╔██╗ ██║   ██║   █████╗  ██║     ███████║███████╗",
+	"██╔══╝  ██║██║╚██╗██║   ██║   ██╔══╝  ██║     ██╔══██║╚════██║",
+	"██║     ██║██║ ╚████║   ██║   ███████╗╚██████╗██║  ██║███████║",
+	"╚═╝     ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝"
+]];
+const TAGLINE_INDENT = "  ";
+function renderTaglineRow(line, row, pos, band) {
+	const chars = Array.from(line);
+	let out = TAGLINE_INDENT;
+	let mode = "";
+	for (let c = 0; c < chars.length; c++) {
+		const color = c >= pos && c < pos + band ? SWEEP : BLUES[row];
+		if (color !== mode) {
+			out += color;
+			mode = color;
+		}
+		out += chars[c];
+	}
+	return out + RESET;
+}
+function renderTaglineFrame(pos, band) {
+	return TAGLINE_BLOCKS.map((block) => block.map((line, row) => renderTaglineRow(line, row, pos, band)).join("\n")).join("\n");
+}
+async function showTagline(slow = false) {
+	console.log();
+	const rows = TAGLINE_BLOCKS.reduce((n, b) => n + b.length, 0);
+	const width = Math.max(...TAGLINE_BLOCKS.flat().map((l) => Array.from(l).length));
+	const band = 7;
+	const step = slow ? 3 : 4;
+	const sweepMs = slow ? 34 : 18;
+	if (!(!!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM)) {
+		console.log(renderTaglineFrame(-1, 0));
+		return;
+	}
+	process.stdout.write("\x1B[?25l");
+	try {
+		let first = true;
+		for (let pos = -7; pos <= width; pos += step) {
+			if (!first) process.stdout.write(`\x1b[${rows}A`);
+			process.stdout.write("\r" + renderTaglineFrame(pos, band) + "\n");
+			first = false;
+			await sleep(sweepMs);
+		}
+		process.stdout.write(`\x1b[${rows}A\r` + renderTaglineFrame(-1, 0) + "\n");
+		if (slow) await sleep(500);
 	} finally {
 		process.stdout.write("\x1B[?25h");
 	}
@@ -6012,6 +6515,7 @@ async function showBanner() {
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills list${RESET}              ${DIM}List installed skills${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills find ${DIM}[query]${RESET}      ${DIM}Search the Pruff catalog${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills agents add ${DIM}<name>${RESET} ${DIM}Add a Pruff subagent${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills rules add ${DIM}<name>${RESET}  ${DIM}Add a Pruff rule (.claude/rules/)${RESET}`);
 	console.log();
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills update${RESET}            ${DIM}Update installed skills${RESET}`);
 	console.log();
@@ -6039,6 +6543,15 @@ ${BOLD}Manage Skills:${RESET}
 ${BOLD}Subagents:${RESET}
   agents add <name>    Install a Claude Code subagent into .claude/agents/ (-g for global)
 
+${BOLD}Rules:${RESET}
+  rules add <name>     Install a coding-convention rule into .claude/rules/ (-g for global)
+  rules add --scope <client|server|common>
+                       Install a whole repo's rule set (client/server also pull in common)
+
+${BOLD}Onboarding:${RESET}
+  onboarding           Set up a new machine (macOS): install Claude Code,
+                       install Obsidian, and clone the Pruff knowledge vault
+
 ${BOLD}Updates:${RESET}
   update [skills...]   Update skills to latest versions (alias: upgrade)
 
@@ -6239,6 +6752,19 @@ async function main() {
 			if (!inAgent) await showLogo();
 			await runAgents(restArgs);
 			break;
+		case "rules":
+		case "rule":
+			if (!inAgent) await showLogo();
+			await runRules(restArgs);
+			break;
+		case "onboarding":
+		case "onboard":
+			if (!inAgent) {
+				await showLogo(true);
+				await showTagline(true);
+			}
+			await runOnboarding(restArgs);
+			break;
 		case "remove":
 		case "rm":
 		case "r":

package/package.json

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