claude-toolkit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.10.0 (2026-06-09)
+
+One idempotent CLI command replaces `init`/`update`/`sync`, and `.claude/` now regenerates itself on toolkit upgrade.
+
+- feat: `bunx claude-toolkit` does it all — creates the config from stack detection on the first run, then cleanly regenerates `.claude/` on every run. `--update` pulls newly-detected stacks into the config. `init`/`update`/`sync` remain as back-compat aliases (`sync` deprecated).
+- feat: automatic regeneration on install — a `postinstall` hook rebuilds `.claude/` when the installed toolkit version changes, so an upgrade ships its updated skills without running anything. Never fails the consumer's install and never writes committed files.
+- feat: clean rebuilds — generation removes toolkit-owned (`ct-` prefixed) skills, agents, commands, and hooks before regenerating, so a stack removed from the config leaves no stale skills behind; user-authored files in `.claude/` are preserved.
+- feat: stricter CLI parsing — unknown flags and typo'd commands now error instead of silently doing nothing; added `--quiet`/`-q`.
+- docs: README and reference docs updated for the single-command workflow and conventional-commit versioning.
+
 ## 0.9.0 (2026-06-08)
 
 Re-baselined from 0.1.x to reflect accumulated scope: 10 stack connectors, the full `init`/`update`/`sync` CLI, stack auto-detection with drift and monorepo/workspace support, and a complete skill/command/agent/hook system. Versioning is now conventional-commit-driven from this release onward.

package/README.md

@@ -14,15 +14,16 @@ Whether you're starting a new project from scratch or consolidating an existing
 # Install as a dev dependency
 bun add -d claude-toolkit
 
-# Scaffold config and generate .claude/
-bunx claude-toolkit init
+# Generate .claude/ — creates the config from detection on the first run
+bunx claude-toolkit
 ```
 
 ## How It Works
 
-1. You define a `claude-toolkit.config.ts` at your project root
-2. The toolkit generates a `.claude/` directory with skills, hooks, commands, and agents
+1. Run `bunx claude-toolkit` — on the first run it creates a `claude-toolkit.config.ts` at your project root, pre-filled with the stacks it detects
+2. It generates a `.claude/` directory with skills, hooks, commands, and agents — regenerated cleanly each run, so stacks you remove leave no stale skills behind
 3. Claude Code picks up the generated config automatically
+4. `.claude/` regenerates automatically on install whenever the toolkit version changes, so upgrades land without running anything
 
 ```ts
 import { defineConfig } from "claude-toolkit";
@@ -45,18 +46,19 @@ export default defineConfig({
 
 ## CLI Commands
 
-| Command                      | Description                                          |
-| ---------------------------- | ---------------------------------------------------- |
-| `bunx claude-toolkit init`   | Scaffold config and generate `.claude/` (first run)  |
-| `bunx claude-toolkit update` | Add newly detected stacks to config, then regenerate |
-| `bunx claude-toolkit sync`   | Regenerate `.claude/` from the current config        |
-| `bunx claude-toolkit help`   | Show available commands                              |
+| Command                        | Description                                                             |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| `bunx claude-toolkit`          | Create the config if missing, then (re)generate `.claude/`. Idempotent. |
+| `bunx claude-toolkit --update` | Same, and also add newly-detected stacks to your config                 |
+| `bunx claude-toolkit help`     | Show available commands                                                 |
+
+Aliases (back-compat): `init` is a friendly name for the bare command, `update` equals `--update`, and `sync` is deprecated — use the bare command. `.claude/` also regenerates automatically on install when the toolkit version changes.
 
 ## Stack Auto-Detection
 
-The toolkit automatically detects which stacks your project uses by scanning `package.json` dependencies, config files, and project structure.
+The toolkit detects which stacks your project uses by scanning `package.json` dependencies, config files, and project structure.
 
-**On `init`** (new project), detected stacks are pre-filled in the generated config:
+**First run** (no config yet) — detected stacks are pre-filled into a new config:
 
 ```text
 Detected stacks:
@@ -65,36 +67,31 @@ Detected stacks:
   cloudflare — found wrangler.toml
 
 Created claude-toolkit.config.ts
+Generated .claude/ with 3 stack(s) and 4 core skills
 ```
 
-**On `sync`** (existing config), the toolkit compares your configured stacks against what it detects and reports any drift:
+**Later runs** (config exists) — `bunx claude-toolkit` regenerates `.claude/` and reports drift between your config and what it detects, but never edits the config:
 
 ```text
 Stack drift detected:
-  + playwright — found @playwright/test in dependencies (not in config)
-  - rust-wasm  — in config but not detected in project
+  + playwright — found @playwright/test in dependencies (detected, not in config)
+  - rust-wasm  — in config, not detected
 
-Suggested update in claude-toolkit.config.ts:
-  stacks: ["solidjs", "vite", "cloudflare", "playwright"]
-
-Run "claude-toolkit update" to add detected stacks automatically.
+Run "bunx claude-toolkit --update" to add detected stacks to your config.
 ```
 
-`sync` is non-destructive — it reports drift but never edits your config.
-
-**On `update`** (existing config), the toolkit adds any newly detected stacks to your config and regenerates `.claude/` in one step — use this when you add a new stack (e.g. Capacitor) to an existing project:
+**Pulling in new stacks** — `bunx claude-toolkit --update` adds any newly-detected stacks to your config and regenerates in one step (use it when you add a stack, e.g. Capacitor):
 
 ```text
 Adding newly detected stacks to config:
   + capacitor — found @capacitor/core in dependencies
 Updated claude-toolkit.config.ts
-Generated .claude/ with 3 stack(s) and 4 core skills
-Update complete.
+Generated .claude/ with 4 stack(s) and 4 core skills
 ```
 
-Stacks already in your config that are no longer detected are reported but left unchanged (remove them manually if intended). If no config exists yet, `update` tells you to run `init` first.
+Stacks in your config that are no longer detected are reported but left unchanged (remove them manually if intended).
 
-This keeps your config aligned as your project evolves — `init` for first-time setup, `update` to pull in new stacks, `sync` to regenerate from the current config.
+**Automatic regeneration** — when the installed toolkit version changes, `.claude/` is regenerated on install automatically (via a `postinstall` hook), so a toolkit upgrade ships its updated skills without you running anything. This only refreshes the generated `.claude/` — it never creates or edits committed files.
 
 ## Available Stacks
 
@@ -163,14 +160,12 @@ Full reference documentation for all skills, commands, and agents is available i
 
 ## Versioning
 
-The patch version auto-increments on every commit via a post-commit hook. `CHANGELOG.md` is updated automatically with the commit message.
+Version bumps are derived from your commit messages (Conventional Commits) by a post-commit hook, and `CHANGELOG.md` is updated automatically:
 
-To bump major or minor versions manually:
+- `feat:` → minor · `fix:` / `perf:` → patch · `feat!:` / `BREAKING CHANGE` → major (capped to minor while pre-1.0)
+- `docs:` / `chore:` / `refactor:` / `style:` / `test:` / `ci:` / `build:` → no version change
 
-```bash
-bun version major   # 0.1.x → 1.0.0
-bun version minor   # 0.1.x → 0.2.0
-```
+To set an exact version deliberately (a re-baseline, or `1.0.0`), edit `package.json` and prepend a `CHANGELOG.md` entry, then commit with `SKIP_POST_COMMIT=1` so the hook doesn't re-bump, and tag `vX.Y.Z`. Publishing to npm happens automatically when a GitHub Release is published (see `.github/workflows/publish.yml`).
 
 ## Development
 

package/bin/cli.ts

@@ -3,10 +3,17 @@
 /**
  * claude-toolkit CLI
  *
- * Commands:
- *   init    — Scaffold config file and generate .claude/ (first-time setup)
- *   update  — Add newly detected stacks to an existing config, then regenerate
- *   sync    — Regenerate .claude/ from existing config
+ * One idempotent command does it all:
+ *   bunx claude-toolkit            Create the config if missing, then (re)generate .claude/
+ *   bunx claude-toolkit --update   Also pull newly-detected stacks into the config
+ *
+ * Aliases / back-compat:
+ *   init     Friendly name for the first run (same as the bare command)
+ *   update   Same as `--update`
+ *   sync     Deprecated alias of the bare command
+ *
+ * .claude/ is also regenerated automatically on install when the installed
+ * toolkit version changes (see bin/postinstall.mjs).
  */
 
 import { existsSync } from "node:fs";
@@ -18,12 +25,12 @@ import type { ClaudeToolkitConfig } from "../src/types.js";
 
 const CONFIG_FILENAME = "claude-toolkit.config.ts";
 
-/** Build a `stacks: [...]` literal for injection into the config file */
+/** Build a `stacks: [...]` literal for injection into the config file. */
 function buildStacksLiteral(stacks: string[]): string {
 	return stacks.length > 0 ? `stacks: [${stacks.map((s) => `"${s}"`).join(", ")}]` : "stacks: []";
 }
 
-/** Rewrite the `stacks: [...]` array in an existing config file in place */
+/** Rewrite the `stacks: [...]` array in an existing config file in place. */
 async function updateConfigStacks(configPath: string, stacks: string[]): Promise<void> {
 	const content = await readFile(configPath, "utf-8");
 	const stacksArray = /stacks:\s*\[[^\]]*\]/;
@@ -39,194 +46,223 @@ async function updateConfigStacks(configPath: string, stacks: string[]): Promise
 async function loadConfig(projectDir: string): Promise<ClaudeToolkitConfig> {
 	const configPath = join(projectDir, CONFIG_FILENAME);
 	if (!existsSync(configPath)) {
-		throw new Error(`Config not found: ${configPath}\nRun "claude-toolkit init" first.`);
+		throw new Error(`Config not found: ${configPath}\nRun "bunx claude-toolkit" first.`);
 	}
-	const module = await import(configPath);
-	return module.default as ClaudeToolkitConfig;
-}
-
-async function init(projectDir: string): Promise<void> {
-	const configPath = join(projectDir, CONFIG_FILENAME);
-
-	if (existsSync(configPath)) {
-		console.log(`Config already exists: ${configPath}`);
-		console.log("\nThis project is already initialized. Did you mean to:");
-		console.log(
-			"  claude-toolkit update   # detect & add new stacks to your config, then regenerate",
+	let mod: { default?: ClaudeToolkitConfig };
+	try {
+		mod = await import(configPath);
+	} catch (err) {
+		throw new Error(
+			`Failed to load ${CONFIG_FILENAME}. Make sure claude-toolkit is installed in this project ` +
+				`(e.g. "bun add -d claude-toolkit"), then run "bunx claude-toolkit" again.\n  ${(err as Error).message}`,
 		);
-		console.log("  claude-toolkit sync     # regenerate .claude/ from the current config");
-		return;
 	}
+	return mod.default as ClaudeToolkitConfig;
+}
 
-	// Detect stacks
-	const detected = detectStacks(projectDir);
-	if (detected.length > 0) {
-		console.log("Detected stacks:");
-		const maxLen = Math.max(...detected.map((d) => d.name.length));
-		for (const d of detected) {
-			console.log(`  ${d.name.padEnd(maxLen)} — ${d.reason}`);
-		}
-	} else {
-		console.log(`No stacks detected. You can add them manually in ${CONFIG_FILENAME}`);
-	}
-
-	// Build stacks literal for config injection
-	const stacksLiteral = buildStacksLiteral(detected.map((d) => d.name));
-
-	// Copy starter config with detected stacks injected
+/** Create claude-toolkit.config.ts from the template with detected stacks injected. */
+async function scaffoldConfig(configPath: string, stacks: string[]): Promise<void> {
+	const stacksLiteral = buildStacksLiteral(stacks);
 	const templatePath = join(import.meta.dirname, "..", "templates", "claude-toolkit.config.ts");
+	let content: string;
 	if (existsSync(templatePath)) {
-		const template = await readFile(templatePath, "utf-8");
-		const configContent = template.replace("stacks: []", stacksLiteral);
-		await writeFile(configPath, configContent, "utf-8");
-		console.log(`Created ${CONFIG_FILENAME}`);
+		content = (await readFile(templatePath, "utf-8")).replace("stacks: []", stacksLiteral);
 	} else {
-		// Inline fallback
-		const defaultConfig = `import { defineConfig } from 'claude-toolkit'
+		content = `import { defineConfig } from "claude-toolkit";
 
 export default defineConfig({
-  ${stacksLiteral},
-  packageManager: 'bun',
-  hooks: {
-    formatter: 'bun run prettier --write',
-    testRunner: 'bun run vitest run',
-    typeCheck: 'bun run tsc --noEmit',
-  },
-  git: {
-    branchPrefix: 'dev',
-    protectedBranches: ['main'],
-  },
-})
+	${stacksLiteral},
+	packageManager: "bun",
+	hooks: {
+		formatter: "bun run prettier --write",
+		testRunner: "bun run vitest run",
+		typeCheck: "bun run tsc --noEmit",
+	},
+	git: {
+		branchPrefix: "dev",
+		protectedBranches: ["main"],
+	},
+});
 `;
-		await writeFile(configPath, defaultConfig, "utf-8");
-		console.log(`Created ${CONFIG_FILENAME}`);
 	}
+	await writeFile(configPath, content, "utf-8");
+}
 
-	// Generate
-	return sync(projectDir);
+interface RunOptions {
+	/** Also write newly-detected stacks into the config (the old `update`). */
+	update?: boolean;
+	/** Suppress informational output. */
+	quiet?: boolean;
 }
 
-async function sync(projectDir: string): Promise<void> {
-	const config = await loadConfig(projectDir);
+/**
+ * The one command. Idempotent:
+ *  - no config yet -> create it from detection
+ *  - config exists -> report drift (or, with `update`, merge detected stacks in)
+ * Always ends by cleanly regenerating .claude/.
+ */
+async function run(projectDir: string, options: RunOptions = {}): Promise<void> {
+	const { update = false, quiet = false } = options;
+	const log = quiet ? (_msg = "") => {} : (msg = "") => console.log(msg);
+	const configPath = join(projectDir, CONFIG_FILENAME);
 
-	// Compare detected stacks against config
-	const detected = detectStacks(projectDir);
-	const configuredNames = new Set(config.stacks);
-	const detectedNames = new Set(detected.map((d) => d.name));
+	let config: ClaudeToolkitConfig;
 
-	const missing = detected.filter((d) => !configuredNames.has(d.name));
-	const stale = config.stacks.filter((s) => !detectedNames.has(s));
+	if (!existsSync(configPath)) {
+		// First run: create the config from what we detect.
+		const detected = detectStacks(projectDir);
+		if (detected.length > 0) {
+			log("Detected stacks:");
+			const pad = Math.max(...detected.map((d) => d.name.length));
+			for (const d of detected) log(`  ${d.name.padEnd(pad)} — ${d.reason}`);
+		} else {
+			log(`No stacks detected. Add them manually in ${CONFIG_FILENAME}.`);
+		}
+		await scaffoldConfig(
+			configPath,
+			detected.map((d) => d.name),
+		);
+		log(`Created ${CONFIG_FILENAME}`);
+		// Build the config in memory (mirroring the scaffolded template defaults) so the
+		// first run never depends on importing the freshly-written config file — which
+		// imports "claude-toolkit" and would fail if the package isn't installed yet.
+		config = {
+			stacks: detected.map((d) => d.name),
+			packageManager: "bun",
+			hooks: {
+				formatter: "bun run prettier --write",
+				testRunner: "bun run vitest run",
+				typeCheck: "bun run tsc --noEmit",
+			},
+			git: { branchPrefix: "dev", protectedBranches: ["main"] },
+		};
+	} else {
+		config = await loadConfig(projectDir);
+		const detected = detectStacks(projectDir);
+		const configured = new Set(config.stacks);
+		const detectedNames = new Set(detected.map((d) => d.name));
+		const missing = detected.filter((d) => !configured.has(d.name));
+		const stale = config.stacks.filter((s) => !detectedNames.has(s));
 
-	if (missing.length > 0 || stale.length > 0) {
-		console.log("\nStack drift detected:");
-		if (missing.length > 0) {
-			const maxLen = Math.max(...missing.map((d) => d.name.length));
+		if (update) {
+			if (missing.length > 0) {
+				log("Adding newly detected stacks to config:");
+				const pad = Math.max(...missing.map((d) => d.name.length));
+				for (const d of missing) log(`  + ${d.name.padEnd(pad)} — ${d.reason}`);
+				config.stacks = [...config.stacks, ...missing.map((d) => d.name)];
+				await updateConfigStacks(configPath, config.stacks);
+				log(`Updated ${CONFIG_FILENAME}`);
+			} else {
+				log("Config already includes all detected stacks.");
+			}
+			if (stale.length > 0) {
+				log("\nIn config but not detected (left unchanged):");
+				for (const s of stale) log(`  - ${s}`);
+				log("Remove them from the config manually if they no longer apply.");
+			}
+		} else if (missing.length > 0 || stale.length > 0) {
+			log("\nStack drift detected:");
+			const pad = Math.max(1, ...missing.map((d) => d.name.length));
 			for (const d of missing) {
-				console.log(`  + ${d.name.padEnd(maxLen)} — ${d.reason} (not in config)`);
+				log(`  + ${d.name.padEnd(pad)} — ${d.reason} (detected, not in config)`);
 			}
-		}
-		if (stale.length > 0) {
-			for (const s of stale) {
-				console.log(`  - ${s} — in config but not detected in project`);
+			for (const s of stale) log(`  - ${s} — in config, not detected`);
+			if (missing.length > 0) {
+				log(`\nRun "bunx claude-toolkit --update" to add detected stacks to your config.`);
 			}
 		}
-		const suggested = [
-			...new Set([
-				...config.stacks.filter((s) => !stale.includes(s)),
-				...missing.map((d) => d.name),
-			]),
-		];
-		console.log(`\nSuggested update in ${CONFIG_FILENAME}:`);
-		console.log(`  ${buildStacksLiteral(suggested)}`);
-		if (missing.length > 0) {
-			console.log('\nRun "claude-toolkit update" to add detected stacks automatically.\n');
-		}
 	}
 
-	await generate(projectDir, config);
-	console.log("Sync complete.");
+	await generate(projectDir, config, { quiet });
+	log("Done.");
 }
 
-/**
- * Update an existing config by adding newly detected stacks, then regenerate.
- * Detected-but-missing stacks are added; stacks in config that are no longer
- * detected are reported but left unchanged. Errors out if no config exists.
- */
-async function update(projectDir: string): Promise<void> {
-	const configPath = join(projectDir, CONFIG_FILENAME);
-	if (!existsSync(configPath)) {
-		console.error(`No ${CONFIG_FILENAME} found in ${projectDir}.`);
-		console.error(`Run "claude-toolkit init" to create one first.`);
-		process.exit(1);
-	}
-
+/** postinstall: quietly regenerate from an existing config. Never creates one. */
+async function postinstall(projectDir: string): Promise<void> {
+	if (!existsSync(join(projectDir, CONFIG_FILENAME))) return;
 	const config = await loadConfig(projectDir);
-	const detected = detectStacks(projectDir);
-	const configuredNames = new Set(config.stacks);
-	const detectedNames = new Set(detected.map((d) => d.name));
+	// scaffold:false — never write committed project files (biome.json/tsconfig.json) on install.
+	await generate(projectDir, config, { quiet: true, scaffold: false });
+	console.log("[claude-toolkit] Regenerated .claude/ for the updated toolkit version.");
+}
 
-	const missing = detected.filter((d) => !configuredNames.has(d.name));
-	const stale = config.stacks.filter((s) => !detectedNames.has(s));
+const HELP = `
+claude-toolkit — Reusable Claude Code configuration
 
-	if (missing.length === 0) {
-		console.log("Config is already up to date — all detected stacks are present.");
-	} else {
-		console.log("Adding newly detected stacks to config:");
-		const maxLen = Math.max(...missing.map((d) => d.name.length));
-		for (const d of missing) {
-			console.log(`  + ${d.name.padEnd(maxLen)} — ${d.reason}`);
-		}
-		const nextStacks = [...config.stacks, ...missing.map((d) => d.name)];
-		await updateConfigStacks(configPath, nextStacks);
-		config.stacks = nextStacks;
-		console.log(`Updated ${CONFIG_FILENAME}`);
-	}
+Usage:
+  bunx claude-toolkit [project-dir]            Create config if missing, then regenerate .claude/
+  bunx claude-toolkit --update [project-dir]   Also add newly-detected stacks to the config
 
-	if (stale.length > 0) {
-		console.log("\nIn config but not detected (left unchanged):");
-		for (const s of stale) {
-			console.log(`  - ${s}`);
-		}
-		console.log("Remove them from the config manually if they no longer apply.");
-	}
+Commands (aliases):
+  init      First-run friendly name (same as the bare command)
+  update    Same as --update
+  sync      Deprecated — use the bare command
+  help      Show this message
 
-	await generate(projectDir, config);
-	console.log("Update complete.");
-}
+Flags:
+  --update, -u   Add newly-detected stacks to the config before regenerating
+  --quiet, -q    Suppress informational output
 
-// CLI entry
-const args = process.argv.slice(2);
-const command = args[0];
-const projectDir = resolve(args[1] ?? ".");
-
-switch (command) {
-	case "init":
-		await init(projectDir);
-		break;
-	case "sync":
-		await sync(projectDir);
-		break;
-	case "update":
-		await update(projectDir);
-		break;
-	case undefined:
-	case "help":
-		console.log(`
-claude-toolkit — Reusable Claude Code configuration
+.claude/ also regenerates automatically on install when the toolkit version changes.
+`;
 
-Commands:
-  init    Scaffold config file and generate .claude/ (first-time setup)
-  update  Add newly detected stacks to an existing config, then regenerate
-  sync    Regenerate .claude/ from the current config
-  help    Show this message
+// ---- entry ----
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith("-")));
+const positional = argv.filter((a) => !a.startsWith("-"));
+const COMMANDS = new Set(["init", "update", "sync", "help", "postinstall"]);
+const KNOWN_FLAGS = new Set(["--update", "-u", "--quiet", "-q"]);
 
-Usage:
-  bunx claude-toolkit init [project-dir]
-  bunx claude-toolkit update [project-dir]
-  bunx claude-toolkit sync [project-dir]
-`);
-		break;
-	default:
-		console.error(`Unknown command: ${command}`);
+// Reject unknown flags so a typo'd flag (e.g. --updat) isn't silently ignored.
+for (const f of flags) {
+	if (!KNOWN_FLAGS.has(f)) {
+		console.error(`Unknown flag: ${f}\nRun "bunx claude-toolkit help".`);
 		process.exit(1);
+	}
+}
+
+const first = positional[0];
+// A positional is treated as a project dir only when it's path-like (".", "..",
+// "./x", or contains a separator) AND exists — so a typo'd command that happens to
+// match a sibling dir name errors instead of silently generating in the wrong place.
+const looksLikePath = (s: string) =>
+	s === "." || s === ".." || s.startsWith(".") || /[\\/]/.test(s);
+let command: string | undefined;
+let dirArg: string | undefined;
+if (first && COMMANDS.has(first)) {
+	command = first;
+	dirArg = positional[1];
+} else if (first && looksLikePath(first) && existsSync(resolve(first))) {
+	dirArg = first; // explicit project dir
+} else if (first) {
+	console.error(`Unknown command: ${first}\nRun "bunx claude-toolkit help".`);
+	process.exit(1);
+}
+
+const projectDir = resolve(dirArg ?? ".");
+const wantUpdate = command === "update" || flags.has("--update") || flags.has("-u");
+const quiet = flags.has("--quiet") || flags.has("-q");
+
+try {
+	switch (command) {
+		case "help":
+			console.log(HELP);
+			break;
+		case "postinstall":
+			await postinstall(projectDir);
+			break;
+		case "sync":
+			if (!quiet) {
+				console.log('Note: "sync" is deprecated — just run "bunx claude-toolkit".');
+			}
+			await run(projectDir, { update: wantUpdate, quiet });
+			break;
+		default:
+			// undefined (bare command), "init", or "update"
+			await run(projectDir, { update: wantUpdate, quiet });
+			break;
+	}
+} catch (err) {
+	console.error(`Error: ${(err as Error).message}`);
+	process.exit(1);
 }

package/bin/postinstall.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * claude-toolkit postinstall
+ *
+ * Runs in the consumer project after install. If a claude-toolkit.config.ts
+ * exists, it regenerates .claude/ — but only when the installed toolkit version
+ * differs from the one that last generated it, so it fires on a toolkit update,
+ * not on every install.
+ *
+ * Guarantees:
+ *  - Never fails the consumer's install (all errors swallowed; always exit 0).
+ *  - Never runs inside the toolkit's own repo (dev install).
+ *  - Never creates or edits the committed config — only regenerates .claude/.
+ *  - Writes no committed files when there's no config (prints a one-line nudge).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function readJsonSafe(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+try {
+	const toolkitDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+	// INIT_CWD is set by npm/bun/pnpm/yarn to the dir where install was invoked.
+	const consumerRoot = resolve(process.env.INIT_CWD || process.cwd());
+
+	// 1. Skip when running inside the toolkit's own repo (dev install).
+	if (consumerRoot === toolkitDir) process.exit(0);
+	const consumerPkg = readJsonSafe(join(consumerRoot, "package.json"));
+	if (consumerPkg?.name === "claude-toolkit") process.exit(0);
+
+	// 2. No config -> stay hands-off; just nudge once. Never write committed files.
+	const hasConfig =
+		existsSync(join(consumerRoot, "claude-toolkit.config.ts")) ||
+		existsSync(join(consumerRoot, "claude-toolkit.config.js"));
+	if (!hasConfig) {
+		console.log(
+			'[claude-toolkit] Run "bunx claude-toolkit" to set up your Claude Code config (.claude/).',
+		);
+		process.exit(0);
+	}
+
+	// 3. Only regenerate when the toolkit version changed since the last generation.
+	const toolkitVersion = readJsonSafe(join(toolkitDir, "package.json"))?.version;
+	const markerPath = join(consumerRoot, ".claude", ".toolkit-version");
+	const lastVersion = existsSync(markerPath) ? readFileSync(markerPath, "utf8").trim() : null;
+	if (toolkitVersion && lastVersion === toolkitVersion) process.exit(0);
+
+	// 4. Regenerate via the CLI (reuses config loading + clean rebuild). Best-effort:
+	//    spawnSync sets `.error` if bun is missing — we ignore it rather than fail.
+	spawnSync("bun", [join(toolkitDir, "bin", "cli.ts"), "postinstall"], {
+		cwd: consumerRoot,
+		stdio: "inherit",
+		env: { ...process.env, INIT_CWD: consumerRoot },
+	});
+} catch {
+	// Never break the consumer's install over config regeneration.
+}
+
+process.exit(0);

package/docs/README.md

@@ -2,6 +2,10 @@
 
 Complete reference for all skills, commands, and agents provided by claude-toolkit.
 
+## Setup
+
+Run `bunx claude-toolkit` in your project — on the first run it creates `claude-toolkit.config.ts` (pre-filled from stack detection) and generates `.claude/`. Run it again anytime to regenerate; add `--update` to pull newly-detected stacks into the config. `.claude/` also regenerates automatically on install when the toolkit version changes. See the [README](../README.md#cli-commands) for the full CLI.
+
 ## Core Skills
 
 Skills that are always included regardless of stack configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
@@ -25,6 +25,7 @@
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check --write",
 		"lint:check": "biome check",
+		"postinstall": "bun bin/postinstall.mjs || node bin/postinstall.mjs || exit 0",
 		"prepare": "npx husky"
 	},
 	"lint-staged": {

package/src/generator.ts

@@ -1,7 +1,7 @@
-import { copyFile as fsCopyFile } from "node:fs/promises";
+import { copyFile as fsCopyFile, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ClaudeToolkitConfig, ResolvedConfig, StackPack } from "./types.js";
-import { copyDir, exists, readJson, writeFileEnsureDir } from "./utils.js";
+import { copyDir, exists, readJson, removePath, writeFileEnsureDir } from "./utils.js";
 
 const TOOLKIT_ROOT = resolve(import.meta.dirname, "..");
 
@@ -48,11 +48,52 @@ async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfi
 	return { config, skills, directoryMappings: allMappings, hooks, stacks };
 }
 
+/** Remove only `ct-` prefixed entries in a directory (preserves user-authored files). */
+async function removeCtPrefixed(dir: string): Promise<void> {
+	if (!exists(dir)) return;
+	const entries = await readdir(dir);
+	await Promise.all(
+		entries.filter((e) => e.startsWith("ct-")).map((e) => removePath(join(dir, e))),
+	);
+}
+
+/**
+ * Remove toolkit-generated artifacts from .claude/ before a rebuild, so a stack
+ * removed from the config doesn't leave an orphaned skill behind.
+ *
+ * Scoped to what the toolkit owns: `ct-` prefixed skills/agents, the generated
+ * skills index, the `ct/` command namespace, and the toolkit's own hook files.
+ * `.claude/skills`, `/agents`, and `/hooks` are shared Claude Code namespaces, so
+ * any user-authored files there — and the user files at the .claude root
+ * (settings.local.json, user-team-info.json, tasks/) — are preserved.
+ * (settings.json and .gitignore are single generated files, overwritten by generate.)
+ */
+async function removeGenerated(claudeDir: string): Promise<void> {
+	const coreHooks = join(TOOLKIT_ROOT, "core", "hooks");
+	const hookFiles = exists(coreHooks) ? await readdir(coreHooks) : [];
+	await Promise.all([
+		removeCtPrefixed(join(claudeDir, "skills")),
+		removeCtPrefixed(join(claudeDir, "agents")),
+		removePath(join(claudeDir, "skills", "README.md")),
+		removePath(join(claudeDir, "commands", "ct")),
+		// Toolkit hook files (copied from core/hooks) + the generated skill-rules.json.
+		...hookFiles.map((f) => removePath(join(claudeDir, "hooks", f))),
+		removePath(join(claudeDir, "hooks", "skill-rules.json")),
+	]);
+}
+
 /** Generate the .claude/ directory from resolved config */
-export async function generate(projectDir: string, config: ClaudeToolkitConfig): Promise<void> {
+export async function generate(
+	projectDir: string,
+	config: ClaudeToolkitConfig,
+	options: { quiet?: boolean; scaffold?: boolean } = {},
+): Promise<void> {
 	const resolved = await resolveConfig(config);
 	const claudeDir = join(projectDir, ".claude");
 
+	// 0. Clean previously-generated output so removed stacks don't leave stale skills.
+	await removeGenerated(claudeDir);
+
 	// 1. Copy core hooks
 	await copyDir(join(TOOLKIT_ROOT, "core", "hooks"), join(claudeDir, "hooks"));
 
@@ -92,18 +133,30 @@ export async function generate(projectDir: string, config: ClaudeToolkitConfig):
 			"# Task-specific context",
 			"tasks/",
 			"",
+			"# Toolkit regeneration marker",
+			".toolkit-version",
+			"",
 		].join("\n"),
 	);
 
-	// 9. Scaffold base configs
-	await scaffoldConfigs(projectDir, resolved);
+	// 9. Scaffold base configs into the project root (committed files). Skipped for
+	//    automatic/postinstall regeneration so an install never writes committed files.
+	if (options.scaffold !== false) {
+		await scaffoldConfigs(projectDir, resolved, options.quiet);
+	}
 
 	// 10. Generate skills README
 	await generateSkillsReadme(claudeDir, resolved);
 
-	console.log(
-		`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
-	);
+	// Record the toolkit version that produced this output — drives auto-regen on update.
+	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
+	await writeFileEnsureDir(join(claudeDir, ".toolkit-version"), `${version}\n`);
+
+	if (!options.quiet) {
+		console.log(
+			`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
+		);
+	}
 }
 
 /** Generate skill-rules.json from resolved config */
@@ -271,7 +324,11 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 }
 
 /** Scaffold base config files (biome.json, tsconfig.json) into the project */
-async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Promise<void> {
+async function scaffoldConfigs(
+	projectDir: string,
+	resolved: ResolvedConfig,
+	quiet = false,
+): Promise<void> {
 	if (resolved.config.scaffoldConfigs === false) return;
 
 	const configsDir = join(TOOLKIT_ROOT, "templates", "configs");
@@ -283,10 +340,10 @@ async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Pr
 	for (const { src, dest } of configs) {
 		const destPath = join(projectDir, dest);
 		if (exists(destPath)) {
-			console.log(`  Skipped ${dest} (already exists)`);
+			if (!quiet) console.log(`  Skipped ${dest} (already exists)`);
 		} else {
 			await fsCopyFile(join(configsDir, src), destPath);
-			console.log(`  Scaffolded ${dest}`);
+			if (!quiet) console.log(`  Scaffolded ${dest}`);
 		}
 	}
 }

package/src/utils.ts

@@ -1,11 +1,5 @@
 import { existsSync } from "node:fs";
-import {
-	copyFile,
-	mkdir,
-	readdir,
-	readFile,
-	writeFile,
-} from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 /** Recursively copy a directory */
@@ -24,11 +18,13 @@ export async function copyDir(src: string, dest: string): Promise<void> {
 	}
 }
 
+/** Remove a file or directory recursively. No-op if the path doesn't exist. */
+export async function removePath(path: string): Promise<void> {
+	await rm(path, { recursive: true, force: true });
+}
+
 /** Write a file, creating parent directories as needed */
-export async function writeFileEnsureDir(
-	filePath: string,
-	content: string,
-): Promise<void> {
+export async function writeFileEnsureDir(filePath: string, content: string): Promise<void> {
 	await mkdir(dirname(filePath), { recursive: true });
 	await writeFile(filePath, content, "utf-8");
 }
@@ -45,9 +41,6 @@ export function exists(filePath: string): boolean {
 }
 
 /** Simple template replacement: {{key}} → value */
-export function renderTemplate(
-	template: string,
-	vars: Record<string, string>,
-): string {
+export function renderTemplate(template: string, vars: Record<string, string>): string {
 	return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
 }