claude-toolkit 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.17.0 (2026-09-28)
+
+Nothing runs at install time any more. The `postinstall` script that regenerated `.claude/` is gone; projects opt in with one line in their own `package.json`, and the new `claude-toolkit refresh` does the work. The package also stops shipping `docs/`, and releases move to npm trusted publishing behind a tarball guard.
+
+**BREAKING:** installing or upgrading claude-toolkit no longer regenerates `.claude/`. After upgrading, run `bunx claude-toolkit` once, then add to your `package.json` scripts:
+
+    "prepare": "claude-toolkit refresh || exit 0"
+
+This line is **required** when `.claude/` is gitignored (the README's recommended setup): without it a fresh clone has no `.claude/` until someone runs `bunx claude-toolkit`. Yarn 2+ never runs `prepare` for your own project — use `"postinstall"` there. npm runs `prepare` only on a plain `npm install` and pnpm skips it on `pnpm add`; after those, run `bunx claude-toolkit refresh`. If you added `claude-toolkit` to Bun's `trustedDependencies` or pnpm's `onlyBuiltDependencies`, remove it.
+
+- feat!: remove the install-time `postinstall` script (`bin/postinstall.mjs`) and the internal `postinstall` command. The package now ships no install scripts and no `child_process` or `process.env` use.
+- feat: `claude-toolkit refresh [dir]` regenerates `.claude/` only when the installed toolkit version differs from `.claude/.toolkit-version`; the up-to-date path never imports the config. It never creates the config and never scaffolds `biome.json`/`tsconfig.json`; a config that fails to load exits 1. Accepts `claude-toolkit.config.ts` or `claude-toolkit.config.js`.
+- feat: every non-quiet `bunx claude-toolkit` run ends with the `prepare` line until `package.json` has a script running `claude-toolkit refresh` — with a named-script variant when `prepare` is already taken, `postinstall` for Yarn 2+ (`.yarnrc.yml`), the npm and pnpm cases where `prepare` does not run, and a leading line when upgrading from 0.16 or earlier. The CLI never edits `package.json`.
+- fix(settings): the protected-branch guard blocked every edit on every branch when two or more `git.protectedBranches` were configured (`[` does not accept `&&`). It is now a `case` statement; branch names are validated against `^[A-Za-z0-9._/][A-Za-z0-9._/-]*$`, and an invalid name fails generation with an error naming it. An empty list now generates no guard instead of blocking every edit.
+- build: stop shipping `docs/` (about 270 KB); the README links the docs on GitHub. `prepare` runs the husky 9 binary instead of `npx husky`. Dropped the dead pre-0.11 `skill-eval.sh` cleanup.
+- ci: publish with npm trusted publishing (OIDC, automatic provenance, no token secret); prerelease versions go to the `next` dist-tag, and the workflow can be re-run by hand on a tag. Before publishing it runs typecheck, lint and tests, strips `prepare`, and runs `check:pack --publish` (no install scripts, no shell or environment access in shipped code, no `docs/`) and `check:smoke` (installs the packed tarball and runs `refresh`). A new CI workflow runs the checks on every push and pull request.
+- build: the post-commit version hook no longer bumps prerelease versions (it turned `0.17.0-rc.0` into `0.17.NaN`); `@types/bun` is pinned to `^1.3.11`.
+- docs: README documents `refresh`, the `prepare` opt-in per package manager, upgrading from 0.16, and the release-candidate flow; the auto-format, auto-test and type-check hooks are marked not yet functional (fixed in 0.18.0). CLAUDE.md drops the postinstall description and corrects the post-commit and `core/hooks` notes.
+- fix(package): `bin` is now `bin/cli.ts` without a leading `./`. npm 11.10 and later silently drop a `./`-prefixed `bin` entry at publish time (`npm pack` keeps it), which would have shipped 0.17.0 without its CLI; `check:pack` now rejects such paths. `repository.url` uses the `git+https` form npm normalizes to.
+
 ## 0.16.0 (2026-08-08)
 
 `ct-typescript-conventions` now selects a compiler as well as types: prefer the TypeScript 7 native compiler where a project already ships it, fall back cleanly where it does not, and never upgrade a project unprompted. Availability-aware in the same spirit as `ct-esnext-idioms`.

package/README.md

@@ -18,12 +18,31 @@ bun add -d claude-toolkit
 bunx claude-toolkit
 ```
 
+Then add one line to your `package.json` so `.claude/` is rebuilt after toolkit upgrades and on fresh clones. It is **required** when `.claude/` is gitignored (the setup recommended below):
+
+```json
+{
+  "scripts": {
+    "prepare": "claude-toolkit refresh || exit 0"
+  }
+}
+```
+
+claude-toolkit itself runs nothing at install time: this is your project's own script, and `|| exit 0` keeps installs working where bun is missing. If `prepare` is already taken, add `"claude-toolkit:refresh": "claude-toolkit refresh || exit 0"` and append `&& bun run claude-toolkit:refresh` (or `npm run`/`pnpm run`/`yarn run`) to your `prepare`. Until one of these is in place, `bunx claude-toolkit` prints the exact line for your project.
+
+When your package manager runs it:
+
+- **bun** runs `prepare` on `bun install`, `bun add` and `bun update`.
+- **npm** runs it only on a plain `npm install`. After `npm install <pkg>` or `npm update`, run `bunx claude-toolkit refresh`.
+- **pnpm** runs it on `pnpm install` and `pnpm update`, not on `pnpm add`. After `pnpm add`, run `bunx claude-toolkit refresh`.
+- **Yarn 2+** never runs `prepare` for your own project. Use `"postinstall": "claude-toolkit refresh || exit 0"` instead; it runs whenever your dependencies change. If you publish the package, don't ship that `postinstall` — run `bunx claude-toolkit refresh` by hand instead.
+
 ## How It Works
 
 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
+4. After a toolkit upgrade, the `prepare` line from Quick Start runs `claude-toolkit refresh`, which rebuilds `.claude/` only when the installed version differs from the one that generated it. Nothing else runs at install time
 
 ```ts
 import { defineConfig } from "claude-toolkit";
@@ -46,13 +65,14 @@ export default defineConfig({
 
 ## CLI 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                                                 |
+| 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 refresh [dir]` | Regenerate `.claude/` only if the toolkit version changed. Never creates the config or other files. |
+| `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.
+Aliases (back-compat): `init` is a friendly name for the bare command, `update` equals `--update`, and `sync` is deprecated — use the bare command. `refresh` is what your `prepare` script runs: with no config it prints one setup line and exits 0, a config that fails to load exits 1, and `--quiet` silences it.
 
 ## Stack Auto-Detection
 
@@ -91,7 +111,7 @@ Generated .claude/ with 4 stack(s) and 4 core skills
 
 Stacks in your config that are no longer detected are reported but left unchanged (remove them manually if intended).
 
-**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.
+**Keeping `.claude/` in sync** — `claude-toolkit refresh` compares the installed toolkit version with `.claude/.toolkit-version` and regenerates only when they differ; when they match it returns without loading your config. It never creates the config and never scaffolds `biome.json`/`tsconfig.json`. Run it from your `prepare` script (see Quick Start).
 
 ## Available Stacks
 
@@ -113,9 +133,9 @@ Stacks in your config that are no longer detected are reported but left unchange
 
 - **Skill Evaluation Engine** — Analyzes prompts and suggests relevant skills
 - **Main Branch Protection** — Prevents accidental edits on protected branches
-- **Auto-formatting** — Formats files after edits
-- **Auto-testing** — Runs related tests when test files change
-- **Type checking** — Checks TypeScript types on save
+- **Auto-formatting** — Formats files after edits _(not yet functional — fixed in 0.18.0)_
+- **Auto-testing** — Runs related tests when test files change _(not yet functional — fixed in 0.18.0)_
+- **Type checking** — Checks TypeScript types on save _(not yet functional — fixed in 0.18.0)_
 
 ### Core Skills
 
@@ -149,6 +169,8 @@ Add `.claude/` to your `.gitignore` (it's generated, not tracked):
 CLAUDE.local.md
 ```
 
+With `.claude/` gitignored, a fresh clone has no `.claude/` until something generates it, so the `prepare` line from Quick Start is **required** in this setup.
+
 Track the config file and CLAUDE.md:
 
 ```
@@ -156,9 +178,17 @@ claude-toolkit.config.ts  # tracked — your project's Claude config
 CLAUDE.md                 # tracked — project-specific documentation
 ```
 
+## Upgrading from 0.16 or earlier
+
+0.17.0 removed the install-time `postinstall` script: installing or upgrading claude-toolkit no longer runs anything. After upgrading:
+
+1. Run `bunx claude-toolkit` once to regenerate `.claude/`.
+2. Add `"prepare": "claude-toolkit refresh || exit 0"` to your `package.json` scripts (the CLI prints the exact line for your project, including the Yarn 2+ and existing-`prepare` variants).
+3. If you added `claude-toolkit` to Bun's `trustedDependencies` or pnpm's `onlyBuiltDependencies` so its install script could run, remove it — there is no install script any more.
+
 ## Documentation
 
-Full reference documentation for all skills, commands, and agents is available in the [`docs/`](docs/README.md) directory.
+Full reference documentation for all skills, commands, and agents lives in the [`docs/` directory on GitHub](https://github.com/william-queant/claude-toolkit/blob/main/docs/README.md). It is not included in the npm package.
 
 ## Versioning
 
@@ -167,7 +197,15 @@ Version bumps are derived from your commit messages (Conventional Commits) by a
 - `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
 
-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`).
+To set an exact version deliberately (a re-baseline, a release candidate, or `1.0.0`), edit `package.json` and the `CHANGELOG.md` entry, then commit with `SKIP_POST_COMMIT=1` so the hook doesn't re-bump. While `package.json` holds a prerelease version (for example `0.17.0-rc.0`), the hook never bumps.
+
+Releases go through a release candidate:
+
+1. Set `X.Y.0-rc.N`, commit with `SKIP_POST_COMMIT=1`, and publish a GitHub **pre-release** for tag `vX.Y.0-rc.N`. `.github/workflows/publish.yml` publishes it to the `next` dist-tag.
+2. Verify the published candidate; fix and cut `rc.N+1` if needed.
+3. Set `X.Y.0`, commit with `SKIP_POST_COMMIT=1`, and publish a normal GitHub Release for `vX.Y.0`. It goes to `latest`.
+
+Publishing uses npm trusted publishing (OIDC): there is no npm token secret, and provenance is automatic. Before publishing, the workflow runs typecheck, lint and tests, strips the dev-only `prepare` script, then runs `bun run check:pack --publish` (no install scripts, no shell or environment access in shipped code, no `docs/`) and `bun run check:smoke` (installs the packed tarball and runs `claude-toolkit refresh`). `.github/workflows/ci.yml` runs typecheck, lint, tests, `check:pack` and `check:smoke` on every push and pull request.
 
 ## Development
 
@@ -175,4 +213,7 @@ To set an exact version deliberately (a re-baseline, or `1.0.0`), edit `package.
 git clone https://github.com/william-queant/claude-toolkit.git
 cd claude-toolkit
 bun install
+bun test               # test suite
+bun run check:pack     # tarball guard
+bun run check:smoke    # pack, install into a temp project, run refresh
 ```

package/bin/cli.ts

@@ -6,24 +6,34 @@
  * 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
+ *   bunx claude-toolkit refresh    Regenerate .claude/ only if the toolkit version changed
  *
  * 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).
+ * Nothing runs at install time. Consumers keep .claude/ in sync by adding
+ * "prepare": "claude-toolkit refresh || exit 0" to their own package.json scripts;
+ * the bare command prints that hint until they do.
  */
 
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { detectStacks } from "../src/detect.js";
-import { generate } from "../src/generator.js";
+import { generate, readMarker, readToolkitVersion } from "../src/generator.js";
+import { buildRefreshHint } from "../src/refresh-hint.js";
 import type { ClaudeToolkitConfig } from "../src/types.js";
 
 const CONFIG_FILENAME = "claude-toolkit.config.ts";
+/** Config files `loadConfig` and `refresh` accept, in lookup order. */
+const CONFIG_FILENAMES = [CONFIG_FILENAME, "claude-toolkit.config.js"];
+
+/** Path of the project's config file, or null when there is none. */
+function findConfigPath(projectDir: string): string | null {
+	return CONFIG_FILENAMES.map((name) => join(projectDir, name)).find((p) => existsSync(p)) ?? null;
+}
 
 /** Build a `stacks: [...]` literal for injection into the config file. */
 function buildStacksLiteral(stacks: string[]): string {
@@ -44,16 +54,16 @@ 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 "bunx claude-toolkit" first.`);
+	const configPath = findConfigPath(projectDir);
+	if (configPath === null) {
+		throw new Error(`Config not found in ${projectDir}\nRun "bunx claude-toolkit" first.`);
 	}
 	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 ` +
+			`Failed to load ${basename(configPath)}. 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}`,
 		);
 	}
@@ -104,11 +114,14 @@ interface RunOptions {
 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);
+	const existingConfig = findConfigPath(projectDir);
+	const configPath = existingConfig ?? join(projectDir, CONFIG_FILENAME);
+	// Read before generate() rewrites it: a pre-0.17 marker means this run is an upgrade.
+	const previousVersion = await readMarker(projectDir);
 
 	let config: ClaudeToolkitConfig;
 
-	if (!existsSync(configPath)) {
+	if (existingConfig === null) {
 		// First run: create the config from what we detect.
 		const detected = detectStacks(projectDir);
 		if (detected.length > 0) {
@@ -175,15 +188,52 @@ async function run(projectDir: string, options: RunOptions = {}): Promise<void>
 
 	await generate(projectDir, config, { quiet });
 	log("Done.");
+	if (!quiet) await printRefreshHint(projectDir, config.packageManager, previousVersion);
 }
 
-/** postinstall: quietly regenerate from an existing config. Never creates one. */
-async function postinstall(projectDir: string): Promise<void> {
-	if (!existsSync(join(projectDir, CONFIG_FILENAME))) return;
+/**
+ * Print the "keep .claude/ in sync" hint unless package.json already runs
+ * `claude-toolkit refresh`. Only prints: package.json is a committed file.
+ */
+async function printRefreshHint(
+	projectDir: string,
+	packageManager: ClaudeToolkitConfig["packageManager"],
+	previousVersion: string | null,
+): Promise<void> {
+	const pkgPath = join(projectDir, "package.json");
+	if (!existsSync(pkgPath)) return;
+	let scripts: Record<string, unknown>;
+	try {
+		scripts = JSON.parse(await readFile(pkgPath, "utf-8")).scripts ?? {};
+	} catch {
+		return; // an unparsable package.json is not worth failing the run over
+	}
+	const lines = buildRefreshHint({
+		scripts,
+		packageManager,
+		yarnBerry: existsSync(join(projectDir, ".yarnrc.yml")),
+		previousVersion,
+	});
+	if (lines.length > 0) console.log(`\n${lines.join("\n")}`);
+}
+
+/**
+ * refresh: regenerate .claude/ when the installed toolkit version differs from the
+ * one recorded in .claude/.toolkit-version. Built for the consumer's own "prepare"
+ * script: it never creates the config, never scaffolds committed files, and the
+ * up-to-date path returns before the config is imported.
+ */
+async function refresh(projectDir: string, quiet: boolean): Promise<void> {
+	const log = quiet ? (_msg = "") => {} : (msg = "") => console.log(msg);
+	if (findConfigPath(projectDir) === null) {
+		log('[claude-toolkit] No config found — run "bunx claude-toolkit" to set up .claude/.');
+		return;
+	}
+	const version = await readToolkitVersion();
+	if ((await readMarker(projectDir)) === version) return;
 	const config = await loadConfig(projectDir);
-	// 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.");
+	log(`[claude-toolkit] Regenerated .claude/ for toolkit ${version}.`);
 }
 
 const HELP = `
@@ -193,6 +243,10 @@ 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
 
+Commands:
+  refresh [project-dir]   Regenerate .claude/ only if the toolkit version changed.
+                          Never creates the config; meant for a "prepare" script.
+
 Commands (aliases):
   init      First-run friendly name (same as the bare command)
   update    Same as --update
@@ -203,14 +257,16 @@ Flags:
   --update, -u   Add newly-detected stacks to the config before regenerating
   --quiet, -q    Suppress informational output
 
-.claude/ also regenerates automatically on install when the toolkit version changes.
+Nothing runs at install time. To keep .claude/ in sync after upgrades, add to
+your package.json "scripts":
+  "prepare": "claude-toolkit refresh || exit 0"
 `;
 
 // ---- 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 COMMANDS = new Set(["init", "update", "sync", "help", "refresh"]);
 const KNOWN_FLAGS = new Set(["--update", "-u", "--quiet", "-q"]);
 
 // Reject unknown flags so a typo'd flag (e.g. --updat) isn't silently ignored.
@@ -248,8 +304,8 @@ try {
 		case "help":
 			console.log(HELP);
 			break;
-		case "postinstall":
-			await postinstall(projectDir);
+		case "refresh":
+			await refresh(projectDir, quiet);
 			break;
 		case "sync":
 			if (!quiet) {

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
-		"claude-toolkit": "./bin/cli.ts"
+		"claude-toolkit": "bin/cli.ts"
 	},
 	"exports": {
 		".": {
@@ -18,7 +18,6 @@
 		"core/",
 		"stacks/",
 		"templates/",
-		"docs/",
 		"CHANGELOG.md"
 	],
 	"scripts": {
@@ -26,8 +25,8 @@
 		"lint": "biome check --write",
 		"lint:check": "biome check",
 		"test": "bun test",
-		"postinstall": "bun bin/postinstall.mjs || node bin/postinstall.mjs || exit 0",
-		"prepare": "npx husky"
+		"check:pack": "bun scripts/check-pack.ts",
+		"check:smoke": "bun scripts/check-smoke.ts"
 	},
 	"lint-staged": {
 		"*.{ts,tsx,js,jsx,json,css}": "biome check --write --no-errors-on-unmatched"
@@ -44,11 +43,11 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/william-queant/claude-toolkit.git"
+		"url": "git+https://github.com/william-queant/claude-toolkit.git"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.10",
-		"@types/bun": "latest",
+		"@types/bun": "^1.3.11",
 		"husky": "^9.1.7",
 		"lint-staged": "^16.4.0",
 		"typescript": "^6.0.2"

package/src/generator.ts

@@ -1,12 +1,58 @@
-import { copyFile as fsCopyFile, readdir } from "node:fs/promises";
+import { copyFile as fsCopyFile, readdir, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ClaudeToolkitConfig, ResolvedConfig, StackPack } from "./types.js";
 import { copyDir, exists, readJson, removePath, writeFileEnsureDir } from "./utils.js";
 
 const TOOLKIT_ROOT = resolve(import.meta.dirname, "..");
 
+/** Branches protected when the config sets no `git.protectedBranches`. */
+const DEFAULT_PROTECTED_BRANCHES = ["main"];
+/** A protected branch name must match this before it is quoted into the guard's `case` pattern. */
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/;
+
+/** Throw a clear error naming the first protected branch that fails BRANCH_NAME_PATTERN. */
+function assertValidBranchNames(branches: string[]): void {
+	const invalid = branches.find((b) => !BRANCH_NAME_PATTERN.test(b));
+	if (invalid === undefined) return;
+	throw new Error(
+		`Invalid branch name in git.protectedBranches: ${JSON.stringify(invalid)}. ` +
+			'Use only letters, digits, ".", "_", "/" and "-", and do not start with "-".',
+	);
+}
+
+/**
+ * The PreToolUse command that blocks edits on a protected branch, or null when no
+ * branch is protected. Names are validated first, then single-quoted into a `case`
+ * pattern, so each name is matched literally and never parsed by the shell.
+ */
+function buildBranchGuard(branches: string[]): string | null {
+	assertValidBranchNames(branches);
+	if (branches.length === 0) return null;
+	const patterns = branches.map((b) => `'${b}'`).join("|");
+	return `# Prevent editing on protected branches\ncase "$(git branch --show-current)" in ${patterns}) echo '{"block": true, "message": "Cannot edit files on a protected branch. Create a feature branch first."}' >&2; exit 2;; esac`;
+}
+
+/** File in .claude/ recording the toolkit version that last generated it. */
+const MARKER_FILE = ".toolkit-version";
+
+/** The installed toolkit version, read from the toolkit's own package.json. */
+export async function readToolkitVersion(): Promise<string> {
+	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
+	return version;
+}
+
+/** The version recorded in `<projectDir>/.claude/.toolkit-version`, or null when absent. */
+export async function readMarker(projectDir: string): Promise<string | null> {
+	const markerPath = join(projectDir, ".claude", MARKER_FILE);
+	if (!exists(markerPath)) return null;
+	return (await readFile(markerPath, "utf-8")).trim();
+}
+
 /** Resolve the full configuration by merging core + stacks + project config */
 async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfig> {
+	// Fail before anything is written when a branch name is unsafe to quote into a hook.
+	assertValidBranchNames(config.git?.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES);
+
 	const stacks: StackPack[] = [];
 	const allMappings: Record<string, string> = {};
 
@@ -79,10 +125,8 @@ async function removeGenerated(claudeDir: string): Promise<void> {
 		// 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")),
-		// Stale files from prior installs: skill-eval.js was renamed to .cjs, and the
-		// skill-eval.sh wrapper was dropped in favour of exec-form node registration.
+		// Stale file from prior installs: skill-eval.js was renamed to .cjs.
 		removePath(join(claudeDir, "hooks", "skill-eval.js")),
-		removePath(join(claudeDir, "hooks", "skill-eval.sh")),
 	]);
 }
 
@@ -153,8 +197,8 @@ export async function generate(
 		].join("\n"),
 	);
 
-	// 9. Scaffold base configs into the project root (committed files). Skipped for
-	//    automatic/postinstall regeneration so an install never writes committed files.
+	// 9. Scaffold base configs into the project root (committed files). Skipped by
+	//    `refresh` (scaffold: false), which must never write committed files.
 	if (options.scaffold !== false) {
 		await scaffoldConfigs(projectDir, resolved, options.quiet);
 	}
@@ -162,9 +206,9 @@ export async function generate(
 	// 10. Generate skills README
 	await generateSkillsReadme(claudeDir, resolved);
 
-	// 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`);
+	// Record the toolkit version that produced this output — `refresh` compares against it.
+	const version = await readToolkitVersion();
+	await writeFileEnsureDir(join(claudeDir, MARKER_FILE), `${version}\n`);
 
 	if (!options.quiet) {
 		console.log(
@@ -230,11 +274,7 @@ async function generateSkillRules(claudeDir: string, resolved: ResolvedConfig):
 /** Generate settings.json with hooks */
 async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Promise<void> {
 	const { hooks, config } = resolved;
-	const protectedBranches = config.git?.protectedBranches ?? ["main"];
-
-	const branchCheck = protectedBranches
-		.map((b) => `"$(git branch --show-current)" != "${b}"`)
-		.join(" && ");
+	const branchGuard = buildBranchGuard(config.git?.protectedBranches ?? DEFAULT_PROTECTED_BRANCHES);
 
 	const postToolUseHooks: unknown[] = [];
 
@@ -313,18 +353,16 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 					],
 				},
 			],
-			PreToolUse: [
-				{
-					matcher: "Edit|MultiEdit|Write",
-					hooks: [
-						{
-							type: "command",
-							command: `# Prevent editing on protected branches\n[ ${branchCheck} ] || { echo '{"block": true, "message": "Cannot edit files on a protected branch. Create a feature branch first."}' >&2; exit 2; }`,
-							timeout: 5,
-						},
-					],
-				},
-			],
+			...(branchGuard === null
+				? {}
+				: {
+						PreToolUse: [
+							{
+								matcher: "Edit|MultiEdit|Write",
+								hooks: [{ type: "command", command: branchGuard, timeout: 5 }],
+							},
+						],
+					}),
 			PostToolUse: postToolUseHooks.map((hook) => ({
 				matcher: "Edit|MultiEdit|Write",
 				hooks: [hook],

package/src/refresh-hint.ts

@@ -0,0 +1,95 @@
+/**
+ * The "keep .claude/ in sync" hint printed after a bare CLI run. The toolkit never
+ * edits the consumer's package.json (a committed file); it only says what to add.
+ * Wording rule: no URLs and no filename literals with a TLD-like extension, since
+ * Socket's URL-strings detector reads both as links.
+ */
+
+/** Script body a consumer adds. `|| exit 0` keeps an install working when bun is missing. */
+export const REFRESH_COMMAND = "claude-toolkit refresh || exit 0";
+/** Script name suggested when the lifecycle script already exists. */
+export const REFRESH_SCRIPT_NAME = "claude-toolkit:refresh";
+/** First release that no longer regenerates .claude/ from a dependency install script. */
+export const INSTALL_SCRIPT_REMOVED_IN = "0.17.0";
+
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+
+export interface RefreshHintInput {
+	/** `scripts` from the project's package.json ({} when it has none). */
+	scripts: Record<string, unknown>;
+	/** `packageManager` from the toolkit config. */
+	packageManager: PackageManager;
+	/** True when the project uses Yarn 2+ (a `.yarnrc.yml` exists). */
+	yarnBerry: boolean;
+	/** `.claude/.toolkit-version` as it was before this run, or null. */
+	previousVersion: string | null;
+}
+
+/**
+ * When each package manager runs the project's own root lifecycle scripts, verified
+ * 2026-09-28 with a root project whose `prepare` and `postinstall` append to a file:
+ *   bun 1.3.11                       prepare on install, add and update
+ *   npm 10.9.3, 11.20.0, 12.1.0      prepare on a plain install only (not install <pkg>, not update)
+ *   pnpm 10.34.5, 11.28.0, 12.6.0    prepare on install and update, not on add
+ *   Yarn 4.18.1                      never prepare; postinstall whenever the dependency tree changes
+ */
+const CAVEATS: Record<PackageManager | "yarn-berry", string | null> = {
+	bun: null,
+	npm: 'npm runs "prepare" only on a plain "npm install"; after "npm install <pkg>" or "npm update", run "bunx claude-toolkit refresh".',
+	pnpm: 'pnpm skips "prepare" on "pnpm add"; after upgrading claude-toolkit that way, run "bunx claude-toolkit refresh".',
+	yarn: null,
+	"yarn-berry":
+		'Yarn 2+ never runs "prepare" for your own project; "postinstall" runs whenever your dependencies change.',
+};
+
+/** Compare x.y.z numerically. A prerelease counts as its release: 0.17.0-rc.0 is not before 0.17.0. */
+export function isBefore(version: string, floor: string): boolean {
+	const parts = (v: string) =>
+		(v.split("-")[0] ?? "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+	const a = parts(version);
+	const b = parts(floor);
+	for (let i = 0; i < 3; i++) {
+		const x = a[i] ?? 0;
+		const y = b[i] ?? 0;
+		if (x !== y) return x < y;
+	}
+	return false;
+}
+
+/** True when some package.json script already runs `claude-toolkit refresh`. */
+export function hasRefreshScript(scripts: Record<string, unknown>): boolean {
+	return Object.values(scripts).some(
+		(s) => typeof s === "string" && s.includes("claude-toolkit refresh"),
+	);
+}
+
+/** Lines of the hint, or [] when a script already runs `claude-toolkit refresh`. */
+export function buildRefreshHint(input: RefreshHintInput): string[] {
+	const { scripts, packageManager, yarnBerry, previousVersion } = input;
+	const lifecycle = yarnBerry ? "postinstall" : "prepare";
+	// Yarn 2+ never runs "prepare", so only a refresh reachable from "postinstall" counts there.
+	const satisfied = yarnBerry
+		? /claude-toolkit[ :]refresh/.test(String(scripts.postinstall ?? ""))
+		: hasRefreshScript(scripts);
+	if (satisfied) return [];
+
+	const runner = yarnBerry ? "yarn" : packageManager;
+	const lines: string[] = [];
+	if (previousVersion !== null && isBefore(previousVersion, INSTALL_SCRIPT_REMOVED_IN)) {
+		lines.push(
+			`Automatic regeneration on install was removed in ${INSTALL_SCRIPT_REMOVED_IN} (it relied on a dependency install script).`,
+		);
+	}
+	lines.push('Keep .claude/ in sync after toolkit upgrades — add to your package.json "scripts":');
+	if (scripts[lifecycle] === undefined) {
+		lines.push(`  "${lifecycle}": "${REFRESH_COMMAND}"`);
+	} else {
+		lines.push(`  "${REFRESH_SCRIPT_NAME}": "${REFRESH_COMMAND}"`);
+		lines.push(
+			`and append "&& ${runner} run ${REFRESH_SCRIPT_NAME}" to your existing "${lifecycle}" script.`,
+		);
+	}
+	const caveat = CAVEATS[yarnBerry ? "yarn-berry" : packageManager];
+	if (caveat !== null) lines.push(caveat);
+	return lines;
+}