@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/global/hooks/version-pin-guard.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+// version-pin-guard: refuses a new or changed version pin unless docs/versions.md has a row
+// for that dependency checked within MAX_AGE days. Pairs with the latest-versions skill.
+// PreToolUse on Write|Edit|MultiEdit|Bash. Exit 2 blocks; stderr goes back to Claude. Every route that writes a
+// dependency file is judged (WB-69): the Write tool, an Edit or MultiEdit (its new_string taken literally), an install
+// command, and the shell writing the file (>, >>, tee, sed -i, cp, mv, a heredoc; lib/shell-writes.mjs).
+// `node version-pin-guard.mjs --selftest` proves every extractor and the age check.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { afterText, shellWrites } from './lib/shell-writes.mjs';
+
+const MAX_AGE = Number(process.env.VERSION_GUARD_DAYS ?? 14);
+const DAY = 86_400_000;
+
+// ---------- extractors: text -> Map(name -> version) ----------
+function fromPackageJson(text) {
+  const out = new Map();
+  let json;
+  try { json = JSON.parse(text); } catch { return out; }
+  for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const [n, v] of Object.entries(json[key] ?? {})) out.set(n, String(v));
+  }
+  if (json.packageManager) out.set(json.packageManager.split('@')[0], json.packageManager);
+  return out;
+}
+
+function fromCmake(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/FetchContent_Declare\s*\(\s*([\w.-]+)([^)]*)\)/gi)) {
+    const v = m[2].match(/\b(?:GIT_TAG|URL)\s+("?)([^\s")]+)\1/i);
+    if (v) out.set(m[1], v[2]);
+  }
+  for (const m of text.matchAll(/CPMAddPackage\s*\(\s*"(?:gh:)?([\w./-]+)@([\w.+-]+)"/gi)) out.set(m[1].split('/').pop(), m[2]);
+  for (const m of text.matchAll(/ExternalProject_Add\s*\(\s*([\w.-]+)[^)]*?\bGIT_TAG\s+([^\s)]+)/gi)) out.set(m[1], m[2]);
+  return out;
+}
+
+function fromRequirements(text) {
+  const out = new Map();
+  for (const line of text.split('\n')) {
+    const m = line.replace(/#.*/, '').trim().match(/^([A-Za-z0-9_.\-\[\]]+)\s*(==|>=|~=|<=|>|<|===)\s*([^\s;,]+)/);
+    if (m) out.set(m[1].replace(/\[.*\]/, ''), `${m[2]}${m[3]}`);
+  }
+  return out;
+}
+
+function fromPyproject(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/["']([A-Za-z0-9_.-]+)(?:\[[^\]]*\])?\s*(==|>=|~=|<=|>|<)\s*([^"',;\s]+)/g)) out.set(m[1], `${m[2]}${m[3]}`);
+  return out;
+}
+
+function fromCargo(text) {
+  const out = new Map();
+  let inDeps = false;
+  for (const line of text.split('\n')) {
+    const h = line.match(/^\s*\[([^\]]+)\]/);
+    if (h) { inDeps = /dependencies/.test(h[1]); continue; }
+    if (!inDeps) continue;
+    const m = line.match(/^\s*([\w-]+)\s*=\s*(?:"([^"]+)"|\{[^}]*version\s*=\s*"([^"]+)")/);
+    if (m) out.set(m[1], m[2] ?? m[3]);
+  }
+  return out;
+}
+
+function fromGoMod(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/^\s*(?:require\s+)?([\w.\-/]+\.[\w.\-/]+)\s+(v[\w.+-]+)/gm)) out.set(m[1], m[2]);
+  return out;
+}
+
+function fromDockerfile(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/^\s*FROM\s+(?:--platform=\S+\s+)?([^\s:@]+)[:@](\S+)/gim)) out.set(m[1].split('/').pop(), m[2]);
+  return out;
+}
+
+function fromWorkflow(text) {
+  const out = new Map();
+  for (const m of text.matchAll(/uses:\s*["']?([\w.-]+\/[\w.-]+)(?:\/[\w./-]+)?@([\w.-]+)/g)) out.set(m[1], m[2]);
+  return out;
+}
+
+// The parser for each manifest: by exact file name, else by the first name pattern that fits, else a workflow by its path.
+const BY_NAME = { 'package.json': fromPackageJson, 'CMakeLists.txt': fromCmake, 'pyproject.toml': fromPyproject, 'Cargo.toml': fromCargo, 'go.mod': fromGoMod };
+const BY_PATTERN = [
+  [/\.cmake$/, fromCmake],
+  [/^requirements.*\.(txt|in)$/, fromRequirements],
+  [/^(Dockerfile|Containerfile)(\..+)?$|\.dockerfile$/i, fromDockerfile],
+];
+
+export function extractorFor(file) {
+  const name = basename(file);
+  if (Object.hasOwn(BY_NAME, name)) return BY_NAME[name];
+  const hit = BY_PATTERN.find(([re]) => re.test(name));
+  if (hit) return hit[1];
+  return /\.github[\\/]workflows[\\/].+\.ya?ml$/.test(file) ? fromWorkflow : null;
+}
+
+// Pins in `after` that are new or different from `before`.
+export function changedPins(extract, before, after) {
+  const old = extract(before);
+  return [...extract(after)].filter(([n, v]) => old.get(n) !== v).map(([n, v]) => ({ name: n, version: v }));
+}
+
+// A shell redirection is never a package: `2>&1`, `&>log`, `>/dev/null`, `> out.txt`, `< in`, and a
+// trailing `&` (0.5.x read `2>&1` as a package named "2" at version "&1" and refused the command).
+const REDIRECT = /(?:^|\s)(?:\d*|&)(?:>>?|<)(?:&\d+|&-|\s*[^\s&|;<>]+)?|\s&(?=\s|$)/g;
+
+// A heredoc's body is text, never a command (KWB-3: a script fed to python3 <<'EOF' that held the words
+// "npm install x" in a comment was read as forty installs).
+const HEREDOC = /<<-?\s*(['"]?)([A-Za-z_][\w-]*)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?=\n|$)/g;
+const PREFIX = /^(sudo|env|command|time|nohup|npx|[A-Za-z_]\w*=\S*)$/;
+
+// Package names added by an install command (the install is the command itself, never a word an echo prints).
+export function pinsFromCommand(cmd) {
+  const found = [];
+  for (const seg of cmd.replace(HEREDOC, ' ').split(/&&|\|\||;|\||\n/)) {
+    const words = seg.replace(REDIRECT, ' ').trim().split(/\s+/);
+    let lead = 0;
+    while (lead < words.length && PREFIX.test(words[lead])) lead += 1;
+    const w0 = words[lead] ?? '', w1 = words[lead + 1] ?? '';
+    const at = (/^(npm|pnpm|yarn|bun)$/.test(w0) && /^(i|install|add)$/.test(w1)) || (/^(pip|pip3|uv|poetry)$/.test(w0) && /^(install|add)$/.test(w1)) || (w0 === 'cargo' && w1 === 'add') || (w0 === 'go' && w1 === 'get') ? lead : -1;
+    if (at === -1) continue;
+    for (const w of words.slice(at + 2)) {
+      if (w.startsWith('-') || w === 'pip' || w.startsWith('.') || w.startsWith('/')) continue;
+      const m = w.match(/^(@?[^@=<>~\s]+)(?:[@=<>~]=?(.+))?$/);
+      if (m && !/^(-r|requirements)/.test(m[1])) found.push({ name: m[1], version: m[2] ?? '(unpinned)' });
+    }
+  }
+  return found;
+}
+
+// The folder an install in `cmd` runs in: a `cd <dir>` before it moves it (KWB-3: `cd <scratch repo> && npm install x`
+// was judged by the session folder's docs/versions.md, so a pin in a repo that had its row was refused).
+export function installDir(cmd, cwd) {
+  let here = cwd;
+  for (const seg of cmd.replace(HEREDOC, ' ').split(/&&|\|\||;|\||\n/)) {
+    const m = seg.trim().match(/^(?:cd|pushd)\s+(['"]?)([^'"\s]+)\1$/);
+    if (m) { here = resolve(here, m[2].replace(/^(~|\$HOME|\$\{HOME\})(?=\/|$)/, process.env.HOME ?? '~')); continue; }
+    if (pinsFromCommand(seg).length) return here;
+  }
+  return here;
+}
+
+// ---------- docs/versions.md ----------
+export function checkedDates(versionsText) {
+  const dates = new Map();
+  for (const line of versionsText.split('\n')) {
+    if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((c) => c.trim().replace(/`/g, '')).filter(Boolean);
+    const date = line.match(/\b(\d{4}-\d{2}-\d{2})\b/);
+    if (!cells.length || !date) continue;
+    const key = cells[0].toLowerCase();
+    const t = Date.parse(date[1]);
+    if (!dates.has(key) || dates.get(key) < t) dates.set(key, t);
+  }
+  return dates;
+}
+
+function lookup(dates, name) {
+  const n = name.toLowerCase();
+  for (const k of [n, n.split('/').pop(), n.replace(/^@[^/]+\//, '')]) if (dates.has(k)) return dates.get(k);
+  return undefined;
+}
+
+export function verdict(pins, dates, now = Date.now()) {
+  const problems = [];
+  for (const p of pins) {
+    const t = lookup(dates, p.name);
+    if (t === undefined) problems.push(`${p.name} ${p.version}: no row in docs/versions.md`);
+    else if (now - t > MAX_AGE * DAY) problems.push(`${p.name} ${p.version}: last checked ${new Date(t).toISOString().slice(0, 10)}, over ${MAX_AGE} days ago`);
+  }
+  return problems;
+}
+
+// The project the pin is written in: the nearest folder above it with docs/versions.md or .git
+// (a file in a git worktree), so an agent worktree and a sibling project read their own table.
+// CLAUDE_PROJECT_DIR is only the fallback, and for a worktree that carries no versions.md.
+export function projectRoot(start, env = process.env.CLAUDE_PROJECT_DIR) {
+  let d = resolve(start);
+  let found = null;
+  for (;;) {
+    if (existsSync(join(d, '.git')) || existsSync(join(d, 'docs', 'versions.md'))) { found = d; break; }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  if (!found) return env ?? resolve(start);
+  const has = (root) => existsSync(join(root, 'docs', 'versions.md'));
+  if (!has(found) && env && has(env) && !relative(resolve(env), found).startsWith('..')) return env;
+  return found;
+}
+
+// ---------- hook ----------
+function newText(input, current) {
+  if (typeof input.content === 'string') return input.content;
+  const edits = input.edits ?? (input.old_string !== undefined ? [input] : []);
+  let text = current;
+  // literally: a new_string holding `$&` or `$1` was read as a replacement pattern (the Edit gap, WB-69)
+  for (const e of edits) text = e.replace_all ? text.split(e.old_string).join(e.new_string ?? '') : text.replace(e.old_string, () => e.new_string ?? '');
+  return text;
+}
+
+function main(payload) {
+  const input = payload.tool_input ?? {};
+  let pins = [];
+  let where;
+  if (payload.tool_name === 'Bash') {
+    pins = pinsFromCommand(input.command ?? '');
+    where = installDir(input.command ?? '', payload.cwd ?? process.cwd());
+    for (const w of shellWrites(input.command ?? '', where)) {
+      const extract = extractorFor(w.path);
+      if (!extract) continue;
+      const { before, after } = afterText(w);
+      if (after !== null) pins.push(...changedPins(extract, before, after));
+      where = dirname(w.path);
+    }
+  } else {
+    const file = input.file_path;
+    const extract = file && extractorFor(file);
+    if (!extract) return 0;
+    const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    pins = changedPins(extract, before, newText(input, before));
+    where = dirname(file);
+  }
+  if (pins.length === 0) return 0;
+  const vfile = join(projectRoot(where), 'docs', 'versions.md');
+  const dates = existsSync(vfile) ? checkedDates(readFileSync(vfile, 'utf8')) : new Map();
+  const problems = verdict(pins, dates);
+  if (problems.length === 0) return 0;
+  process.stderr.write(`version-pin-guard: look up the newest release first (latest-versions skill).\n${problems.map((p) => `- ${p}`).join('\n')}\nAdd or refresh each row in ${vfile} (name | latest stable | YYYY-MM-DD | source URL | used | decision), then pin.\n`);
+  return 2;
+}
+
+function selftest() {
+  const eq = (a, b, what) => { if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${what}: got ${JSON.stringify(a)}`); };
+  const names = (pins) => pins.map((p) => p.name);
+  eq(names(changedPins(fromPackageJson, '{"dependencies":{"a":"1"}}', '{"dependencies":{"a":"1","fastify":"^5.6.0"}}')), ['fastify'], 'package.json add');
+  eq(names(changedPins(fromPackageJson, '{"dependencies":{"a":"1"}}', '{"dependencies":{"a":"1"},"x":2}')), [], 'package.json unchanged');
+  eq([...fromCmake('FetchContent_Declare(JUCE\n  GIT_REPOSITORY https://github.com/juce-framework/JUCE\n  GIT_TAG 9.0.4)')], [['JUCE', '9.0.4']], 'cmake GIT_TAG');
+  eq([...fromCmake('CPMAddPackage("gh:fmtlib/fmt@11.2.0")')], [['fmt', '11.2.0']], 'cmake CPM');
+  eq([...fromRequirements('numpy==2.3.1  # x\n-r base.txt\n')], [['numpy', '==2.3.1']], 'requirements');
+  eq([...fromPyproject('dependencies = ["httpx>=0.28", "rich"]')], [['httpx', '>=0.28']], 'pyproject');
+  eq([...fromCargo('[package]\nversion = "0.1.0"\n[dependencies]\nserde = { version = "1.0.219", features = ["derive"] }\n')], [['serde', '1.0.219']], 'cargo');
+  eq([...fromGoMod('module x\nrequire (\n  github.com/spf13/cobra v1.9.1\n)\n')], [['github.com/spf13/cobra', 'v1.9.1']], 'go.mod');
+  eq([...fromDockerfile('FROM --platform=linux/amd64 node:24-slim AS build\n')], [['node', '24-slim']], 'dockerfile');
+  eq([...fromWorkflow('- uses: actions/checkout@v5\n- uses: github/codeql-action/init@v3')], [['actions/checkout', 'v5'], ['github/codeql-action', 'v3']], 'workflow');
+  eq(names(pinsFromCommand('cd x && npm install -D typescript@5.9.3 zod')), ['typescript', 'zod'], 'npm install');
+  eq(names(pinsFromCommand('pip install --break-system-packages requests==2.32.5')), ['requests'], 'pip install');
+  eq(pinsFromCommand('npm install'), [], 'bare npm install');
+  eq(names(pinsFromCommand('npm install fastify 2>&1 | tail -5')), ['fastify'], 'install with 2>&1');
+  eq(names(pinsFromCommand('npm i zod > /tmp/npm.log 2>&1')), ['zod'], 'install with > log 2>&1');
+  eq(names(pinsFromCommand('pip install requests==2.32.5 &>/dev/null &')), ['requests'], 'install with &>/dev/null &');
+  eq(pinsFromCommand('npm install 2>&1'), [], 'bare install with 2>&1');
+  eq(pinsFromCommand("python3 - <<'EOF'\n# then npm install zod and pip install rich\nEOF"), [], 'a heredoc body is text');
+  eq(pinsFromCommand('echo run npm install zod first'), [], 'an echo that names an install');
+  eq(names(pinsFromCommand('sudo npm install -g zod@4')), ['zod'], 'install after a prefix');
+  eq(installDir('cd /p/other && npm install zod@4', '/p/here'), '/p/other', 'an install after cd runs there');
+  eq(installDir('npm install zod@4 && cd /p/other', '/p/here'), '/p/here', 'a cd after the install does not move it');
+  const now = Date.parse('2026-10-26');
+  const dates = checkedDates('| name | latest |\n|---|---|\n| fastify | 5.6.1 | 2026-10-20 | https://github.com/fastify/fastify/releases | 5.6.1 | use |\n| `JUCE` | 9.0.4 | 2026-09-01 | url | 8.0.4 | F4 |\n');
+  eq(verdict([{ name: 'fastify', version: '5.6.1' }], dates, now), [], 'fresh row passes');
+  eq(verdict([{ name: 'JUCE', version: '9.0.4' }], dates, now).length, 1, 'stale row blocks');
+  eq(verdict([{ name: 'zod', version: '4' }], dates, now).length, 1, 'missing row blocks');
+  eq(verdict([{ name: 'github.com/fastify', version: 'v1' }], dates, now), [], 'last path segment matches');
+  console.log('version-pin-guard selftest: OK (26 cases)');
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+  if (process.argv.includes('--selftest')) process.exit(selftest());
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    let payload;
+    try { payload = JSON.parse(raw || '{}'); } catch { process.exit(0); }
+    process.exit(main(payload));
+  });
+}

package/global/skills/latest-versions/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: latest-versions
+description: Use when starting a new project, or adding, choosing, pinning or upgrading any library, tool, compiler, runtime, SDK, GitHub Action or container image.
+---
+
+# Latest versions
+
+Your knowledge of versions is out of date by definition. Every version Stellix and every other project uses is looked up today, from the project's own release source, and written down before it is used.
+
+<constraints>
+Always do:
+- Look up the current stable release before you choose, add, pin or upgrade anything: a library, framework, tool, compiler, runtime, SDK, GitHub Action or container base image.
+- Take the version from a primary source, in this order:
+  1. the project's GitHub releases or tags page;
+  2. its official site or changelog;
+  3. its registry page (npm, PyPI, crates.io, pkg.go.dev, Homebrew, Docker Hub).
+  Blog posts, tutorials and AI answers are not sources.
+- Record every lookup in `docs/versions.md`, in the project being worked on, one row per dependency:
+  `| name | latest stable | date checked YYYY-MM-DD | source URL | version used | decision |`
+- Use the latest stable release unless there is a stated reason not to. Write that reason in the decision column (for example "9.0.4 latest; staying on 8.0.4 until F4").
+- Read the release notes between the version used and the latest. Name any breaking change in the decision column.
+- Pin exact versions: a full tag, release or commit, never a range or `latest`, in build files (CMake `GIT_TAG`, Docker `FROM`, Actions `uses`). Lockfiles do the pinning for package managers.
+- At the start of a new project, run this for the whole stack before the first build file is written.
+
+Never do:
+- Write a version number from memory, from an older project, or from an example in docs.
+- Pick a pre-release, beta, RC or nightly unless the user asks for one.
+- Treat a row older than 14 days as current. Look it up again and update the date.
+- Edit a version pin before its row exists. The `version-pin-guard` hook refuses pins that `docs/versions.md` has not checked within 14 days.
+</constraints>
+
+## How
+
+1. List what the change needs: each dependency, tool and image.
+2. For each one, fetch its releases page (WebFetch, or `gh release list -R owner/repo -L 5` / `gh api repos/owner/repo/releases/latest`). Note the newest non-pre-release and its date.
+3. Add or update its row in `docs/versions.md`. Create the file with this header if it is missing:
+
+   ```
+   # Versions
+   Checked by the latest-versions skill. One row per dependency; re-check after 14 days.
+
+   | name | latest stable | checked | source | used | decision |
+   |---|---|---|---|---|---|
+   ```
+
+4. Then write the pin.
+5. Tell the user, in one line per dependency, which version you chose and why, and flag any major jump.
+
+The name in the row must be the name the pin uses: the npm package name, the CMake FetchContent name, the image name or the Action `owner/repo`. That's how the hook matches the pin to its row.

package/lib/backup.mjs

@@ -0,0 +1,34 @@
+// Before every install or update, copies the files the package writes into (CLAUDE.md,
+// settings.json, layout.json, the lock) to .claude/.claude-packs-backup/<timestamp>/.
+// Keeps the last 5 backups.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DIR = join('.claude', '.claude-packs-backup');
+const KEEP = 5;
+const FILES = ['CLAUDE.md', '.claude/settings.json', '.claude/layout.json', '.claude/claude-packs.lock.json'];
+
+export function backup(projectDir) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const target = join(projectDir, DIR, stamp);
+  for (const rel of FILES) {
+    const src = join(projectDir, rel);
+    if (!existsSync(src)) continue;
+    mkdirSync(join(target, rel, '..'), { recursive: true });
+    copyFileSync(src, join(target, rel));
+  }
+  const all = existsSync(join(projectDir, DIR)) ? readdirSync(join(projectDir, DIR)).sort() : [];
+  for (const old of all.slice(0, Math.max(0, all.length - KEEP))) rmSync(join(projectDir, DIR, old), { recursive: true, force: true });
+  return join(DIR, stamp);
+}
+
+// Adds the backup folder, the hooks' run state (.claude/state: frozen list, last test log) and brief-guard's refusal counter
+// (.claude/usage.log, 0.9.2) to .gitignore (appends; never rewrites the file).
+export function ensureGitignore(projectDir) {
+  const file = join(projectDir, '.gitignore');
+  for (const line of [`${DIR.replace(/\\/g, '/')}/`, '.claude/state/', '.claude/usage.log', '.claude/hooks.log', '.claude/logs/']) {
+    const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    if (text.split('\n').includes(line)) continue;
+    appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}${line}\n`);
+  }
+}

package/lib/build-queue.mjs

@@ -0,0 +1,22 @@
+// KF-1: build-guard named a queue no pack shipped, and took any file called build.sh as a queue. doctor checks both ways it fails open: the tool is gone, or the project's
+// wrapper queues nothing. A wrapper that holds the law itself says so: layout.json "guards": { "build": { "queue": "none: <reason>" } }.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TOOL = '.claude/tools/buildq.mjs';
+
+const wrappersOf = (commands) => [...new Set(Object.values(commands ?? {}).flatMap((c) => String(c).split(/\s+/)).filter((w) => /(^|\/)build\.sh$/.test(w)))];
+
+export function buildQueueProblems(projectDir, layout) {
+  if (!existsSync(join(projectDir, '.claude/hooks/build-guard.mjs'))) return [];
+  const problems = [];
+  if (!existsSync(join(projectDir, TOOL))) problems.push(`build-guard sends every build to ${TOOL}, which is missing: run update`);
+  if (/^none:\s*\S/.test(layout.guards?.build?.queue ?? '')) return problems;
+  for (const rel of wrappersOf(layout.commands)) {
+    const file = join(projectDir, rel);
+    if (existsSync(file) && !readFileSync(file, 'utf8').includes('buildq')) {
+      problems.push(`${rel} does not call the queue, so build-guard passes it and no job waits. Call ${TOOL} in it, or set layout.json "guards": { "build": { "queue": "none: <reason>" } }`);
+    }
+  }
+  return problems;
+}

package/lib/claude-md.mjs

@@ -0,0 +1,60 @@
+// Writes the generated layout section into the project's CLAUDE.md, between markers.
+// Everything outside the markers is the user's and is never touched.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { noPackageLine } from './kit-command.mjs';
+
+const START = '<!-- claude-packs:start -->';
+const END = '<!-- claude-packs:end -->';
+
+// The house rules after the folders are the configuration's preamble (configurations/<name>/config.json, 0.10.0).
+function section(layout, packNames, preamble, notes = []) {
+  // Folders no kind points at are listed by purpose; the rest appear once, in the kinds list.
+  const used = new Set(Object.values(layout.kinds ?? {}).map((k) => k.in));
+  const folders = Object.entries(layout.folders)
+    .filter(([name]) => !used.has(name) && name !== 'src')
+    .sort(([, a], [, b]) => a.path.localeCompare(b.path))
+    .map(([, f]) => `  - \`${f.path}/\`: ${f.purpose}`);
+  return [
+    START,
+    '<!-- Generated by claude-packs from .claude/layout.json. Edit that file and run `npx --no-install @thedecipherist/claude-packs update`; edits here are replaced. -->',
+    '## Project layout',
+    '',
+    '<constraints>',
+    'Always do:',
+    '- Put every kind of thing in its one place. The rules, checks and skills for it load only there:',
+    ...kindLines(layout),
+    ...(folders.length ? ['- The other folders:', ...folders] : []),
+    ...preamble.always.map((l) => `- ${l}`),
+    '',
+    'Never do:',
+    ...preamble.never.map((l) => `- ${l}`),
+    '</constraints>',
+    '',
+    ...commandLines(layout),
+    ...notes,
+    `Installed packs: ${packNames.join(', ')}.`,
+    END,
+  ].join('\n');
+}
+
+function kindLines(layout) {
+  return Object.values(layout.kinds ?? {}).map((k) => `  - ${k.what} → \`${layout.folders?.[k.in] ? `${layout.folders[k.in].path}/` : k.in}\``);
+}
+
+function commandLines(layout) {
+  const entries = Object.entries(layout.commands ?? {});
+  if (entries.length === 0) return [];
+  return ['## Project commands', '', 'Skills and checks run these; use them, not the raw tools:', ...entries.map(([k, v]) => `- ${k}: \`${v}\``), ''];
+}
+
+export function writeClaudeMd(projectDir, layout, packNames, preamble) {
+  const file = join(projectDir, 'CLAUDE.md');
+  const block = section(layout, packNames, preamble, noPackageLine(projectDir));
+  let text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const s = text.indexOf(START);
+  const e = text.indexOf(END);
+  if (s !== -1 && e > s) text = text.slice(0, s) + block + text.slice(e + END.length);
+  else text = `${text.trimEnd()}${text.trim() ? '\n\n' : ''}${block}\n`;
+  writeFileSync(file, text);
+}

package/lib/config-cli.mjs

@@ -0,0 +1,36 @@
+// The `configs` and `config <name>` commands, and doctor's configuration line (0.10.0, STEP 3 item 1).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { allowedPacks, describeConfigs, describeSwitch, packsFor, readConfig, resolveConfig } from './configs.mjs';
+import { doctor } from './doctor.mjs';
+import { readLock } from './manifest.mjs';
+import { sync } from './sync.mjs';
+
+export { describeConfigs, readConfig };
+
+const layoutOf = (dir) => {
+  const file = join(dir, '.claude', 'layout.json');
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
+};
+
+export const layoutConfiguration = (dir) => layoutOf(dir)?.configuration ?? null;
+
+// Switch a project to configuration `name`: the packs it has that the new one takes stay; with none left, the new one's
+// default packs. What changes is printed first; --dry-run stops there.
+export async function switchConfig(dir, name, installed, { force = false, dryRun = false, log = console.log } = {}) {
+  if (!name) throw new Error('name the configuration: `config <name>` (`configs` lists them)');
+  if (installed.length === 0) throw new Error('nothing installed here; run `init --config <name>` first');
+  const to = readConfig(name);
+  const layout = layoutOf(dir) ?? { folders: {} };
+  const { config: from } = resolveConfig({ layout, packs: installed });
+  const fromSources = packsFor(from, installed);
+  const kept = installed.filter((p) => p === 'base' || (allowedPacks(to).includes(p) && !from.packs.always.includes(p)));
+  const chosen = kept.some((p) => p !== 'base') ? kept : [...kept, ...to.packs.default];
+  const toSources = packsFor(to, chosen);
+  const lines = describeSwitch(from, fromSources, to, toSources, { ...layout, disable: [...(layout.disable ?? [])] }, Object.keys(readLock(join(dir, '.claude')).files));
+  for (const l of lines) log(l);
+  if (dryRun) { log('dry run: nothing changed'); return 0; }
+  if (lines.at(-1) === '  no change' && layout.configuration === to.name) return 0;
+  await sync(dir, chosen, { force, mkdirs: true, config: name, log });
+  return doctor(dir, log, { installing: true });
+}

package/lib/configs.mjs

@@ -0,0 +1,145 @@
+// Configurations (0.10.0, STEP 3; KWB-31): a kind of project, as data. configurations/<name>/config.json holds
+//   "packs":     { "always": [...], "choose": [...], "default": [...] }  the packs it always installs (base first), the ones
+//                a project may add, and the ones `init --config <name>` takes when none are named
+//   "layout":    { "folders", "concepts", "kinds" }   the layout template: the folder structure of that kind of project
+//   "hookOrder": { "<event> <matcher>": ["a.mjs", ...] }   the order its hooks run in, per settings entry (optional)
+//   "leaveOut":  ["rules/x.md", "hooks/y.mjs", ...]   pack items this configuration does not install (optional)
+//   "sourceFiles": "<regex>"   what doctor's coverage counts as source (optional; default C, C++ and shaders)
+//   "preamble":  { "always": [...], "never": [...] }  the house rules of its CLAUDE.md block
+// Its rules, hooks, checks and skills are its packs' (`configs` lists them). layout.json "configuration" names the one a
+// project has; `update` applies it; an install from before 0.10.0 gets the smallest configuration that takes its packs.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { customPacks, planFiles, readPack } from './packs.mjs';
+
+export const CONFIGS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'configurations');
+
+export function availableConfigs() {
+  return readdirSync(CONFIGS_DIR).filter((d) => existsSync(join(CONFIGS_DIR, d, 'config.json'))).sort();
+}
+
+export function readConfig(name) {
+  const file = join(CONFIGS_DIR, String(name), 'config.json');
+  if (!existsSync(file)) throw new Error(`unknown configuration "${name}" (available: ${availableConfigs().join(', ')})`);
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+// Every pack a configuration takes, always-installed first.
+export const allowedPacks = (config) => [...config.packs.always, ...config.packs.choose, ...customPacks()]; // a team's own pack goes with any configuration
+
+// The packs a project names, checked against its configuration: base first, then the configuration's own, then the chosen.
+export function packsFor(config, requested) {
+  const allowed = allowedPacks(config);
+  const bad = requested.filter((p) => !allowed.includes(p));
+  if (bad.length) throw new Error(`${bad.join(', ')} ${bad.length > 1 ? 'are' : 'is'} not in configuration ${config.name} (it takes: ${allowed.join(', ')})`);
+  const out = [...config.packs.always];
+  for (const p of requested) if (!out.includes(p)) out.push(p);
+  return out;
+}
+
+// The packs written in the lock and named in CLAUDE.md: base and the chosen ones; a configuration's own packs come with it.
+export const listedPacks = (config, sources) => sources.filter((p) => p === 'base' || !config.packs.always.includes(p));
+
+// The configuration of an install that names none: the smallest one that takes all its packs.
+export function inferConfig(packs) {
+  const fits = availableConfigs().map(readConfig).filter((c) => packs.every((p) => allowedPacks(c).includes(p)));
+  if (!fits.length) throw new Error(`no configuration takes the packs ${packs.join(', ')}; name one with --config`);
+  // The configuration that has a pack by default first, then one with no folder layout of its own, then the smallest.
+  const rank = (c) => [packs.some((p) => c.packs.default.includes(p)) ? 0 : 1, c.packs.always.length, allowedPacks(c).length];
+  return fits.sort((a, b) => rank(a).map((v, i) => v - rank(b)[i]).find(Boolean) ?? 0)[0];
+}
+
+// Which configuration an install uses: the one named now (--config), else layout.json's, else its packs'.
+export function resolveConfig({ named = null, layout = {}, packs = [] } = {}) {
+  if (named) return { config: readConfig(named), how: 'named' };
+  if (layout.configuration) return { config: readConfig(layout.configuration), how: 'layout' };
+  return { config: inferConfig(packs), how: 'packs' };
+}
+
+// What a configuration installs with these packs: every file, by its place in the project, and the items by kind.
+export function planOf(config, sources, layout = { folders: {}, disable: [] }) {
+  const optIn = sources.flatMap((s) => readPack(s).optIn ?? []).filter((i) => !(layout.enable ?? []).includes(i)); // opt-in: only when enabled
+  const lay = { ...layout, disable: [...(layout.disable ?? []), ...(config.leaveOut ?? []), ...optIn] };
+  const files = new Set();
+  for (const name of sources) for (const { rel } of planFiles(name, lay)) files.add(rel);
+  return files;
+}
+
+export function itemsOf(files) {
+  const by = { rules: [], hooks: [], checks: [], skills: [] };
+  for (const rel of files) {
+    const p = rel.replace(/\\/g, '/');
+    const skill = p.match(/(?:^|\/)\.claude\/skills\/([^/]+)\/SKILL\.md$/);
+    if (skill) by.skills.push(skill[1]);
+    else if (/^\.claude\/rules\/[^/]+\.md$/.test(p)) by.rules.push(p.split('/').pop());
+    else if (/^\.claude\/hooks\/[^/]+\.(mjs|py)$/.test(p)) by.hooks.push(p.split('/').pop());
+    else if (/^\.claude\/checks\/[^/]+\.json$/.test(p)) by.checks.push(p.split('/').pop());
+  }
+  for (const k of Object.keys(by)) by[k].sort();
+  return by;
+}
+
+export function describeConfigs(current = null) {
+  return availableConfigs().map((name) => {
+    const c = readConfig(name);
+    const all = [...c.packs.always, ...c.packs.choose];
+    const n = itemsOf(planOf(c, all));
+    const choose = c.packs.choose.length ? `; ${c.packs.choose.join(', ')} (to choose)` : '';
+    return [
+      `${name}${name === current ? '  (this project)' : ''}`,
+      `  ${c.description}`,
+      `  packs: ${c.packs.always.join(', ')} (always)${choose}${c.packs.default.length ? `; init takes ${c.packs.default.join(', ')}` : ''}`,
+      `  with every pack: rules ${n.rules.length}, hooks ${n.hooks.length}, checks ${n.checks.length}, skills ${n.skills.length}`,
+      `  folders: ${Object.values(c.layout?.folders ?? {}).map((f) => `${f.path}/`).join(' ') || '(its packs\')'}`,
+    ].join('\n');
+  }).join('\n\n');
+}
+
+// The lines `config <name>` prints: what the switch adds and takes away.
+// `installed`: the files the project's lock names (what it has now); without it, what `from` would install.
+export function describeSwitch(from, fromSources, to, toSources, layout, installed = null) {
+  const before = itemsOf(installed ? new Set(installed) : planOf(from, fromSources, layout));
+  const after = itemsOf(planOf(to, toSources, layout));
+  const lines = [`  ${from.name} -> ${to.name}`];
+  const fromListed = listedPacks(from, fromSources), toListed = listedPacks(to, toSources);
+  const added = toListed.filter((p) => !fromListed.includes(p)), dropped = fromListed.filter((p) => !toListed.includes(p));
+  if (added.length) lines.push(`  packs added: ${added.join(', ')}`);
+  if (dropped.length) lines.push(`  packs dropped: ${dropped.join(', ')}`);
+  for (const kind of Object.keys(before)) {
+    const plus = after[kind].filter((x) => !before[kind].includes(x)), minus = before[kind].filter((x) => !after[kind].includes(x));
+    if (plus.length) lines.push(`  ${kind} added (${plus.length}): ${plus.join(', ')}`);
+    if (minus.length) lines.push(`  ${kind} removed (${minus.length}): ${minus.join(', ')}`);
+  }
+  if (JSON.stringify(from.preamble) !== JSON.stringify(to.preamble)) lines.push('  CLAUDE.md preamble: changes');
+  const missing = Object.values(to.layout?.folders ?? {}).filter((f) => !Object.values(layout.folders ?? {}).some((g) => g.path === f.path));
+  if (missing.length && !layout.complete) lines.push(`  folders added from its template: ${missing.map((f) => `${f.path}/`).join(' ')}`);
+  return lines.length > 1 ? lines : [...lines, '  no change'];
+}
+
+// doctor's lines: the configuration installed, and what does not fit it.
+export function configProblems(dir, lockPacks, log) {
+  const file = join(dir, '.claude', 'layout.json');
+  if (!existsSync(file)) return [];
+  const layout = JSON.parse(readFileSync(file, 'utf8'));
+  let config;
+  try {
+    config = resolveConfig({ layout, packs: lockPacks }).config;
+  } catch (e) {
+    return [layout.configuration ? `layout.json names configuration "${layout.configuration}", which this kit does not have (${e.message})` : e.message];
+  }
+  log(`  configuration: ${config.name}${layout.configuration ? '' : ' (from its packs; `update` writes it into layout.json)'}`);
+  return lockPacks.filter((p) => !allowedPacks(config).includes(p)).map((p) => `pack ${p} is installed but configuration ${config.name} does not take it (\`config <name>\` switches; \`configs\` lists them)`);
+}
+
+// The configuration's "sourceFiles" as a RegExp, or undefined (coverage's default) when it names none or cannot be read.
+export function sourceFilesOf(dir, lockPacks) {
+  try {
+    const file = join(dir, '.claude', 'layout.json');
+    const layout = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    const re = layout.sourceFiles ?? resolveConfig({ layout, packs: lockPacks }).config.sourceFiles;
+    return re ? new RegExp(re, 'i') : undefined;
+  } catch {
+    return undefined;
+  }
+}