claude-dev-env 2.13.0 → 2.14.0

package/bin/CLAUDE.md

@@ -1,112 +1 @@
-# bin
-
-The installer and its companion modules. Running `npx claude-dev-env` (or `node bin/install.mjs`) copies package files into the managed root (`~/.claude/` by default; `CLAUDE_CONFIG_DIR` or `--target` selects another), merges hook entries into that root's `settings.json`, installs Git hooks, and writes `~/.mypy.ini` under the process home.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `install.mjs` | Main installer: builds a read-only plan via `install-plan.mjs`, then runs mutations inside `install-transaction.mjs` recovery (copy content directories, merge hooks, install skills, prune, git hooks, mypy.ini); routes `CLAUDE_HOME`, the manifest path, and `~/.mypy.ini` through `resolve-install-root.mjs`; resolves single or multi-profile targets before mutation and writes one ownership manifest per target |
-| `resolve-install-root.mjs` | Pure install-root resolver: precedence `--target` > `CLAUDE_CONFIG_DIR` > `~/.claude`, separator-boundary containment, and the declared external allowlist for `~/.mypy.ini` |
-| `select-install-targets.mjs` | Pure target selection for main-default, explicit `--target`, and `--profile`/`--profiles`; rejects ambiguous or duplicate targets; builds per-target manifest records with `targetIdentity` and `managedRoot` |
-| `install-plan.mjs` | Read-only install and uninstall plans: install preflight (managed root, source conflicts, Python, settings when hooks install) and uninstall preflight (settings JSON before removal, removable vs skipped manifest records), freezes plans E2/F execute |
-| `install-transaction.mjs` | Install, update, and uninstall transaction journal: captures prior settings, manifest, managed files, and `core.hooksPath`, restores them on failure, and supports fault injection phases for recovery tests |
-| `install.transaction.test.mjs` | Unit and sandbox installer tests for snapshot/restore and fault phases (`after_file_staging`, `after_settings_write`, `after_git_config`, `after_manifest_write`) |
-| `install.uninstall-transaction.test.mjs` | Uninstall plan preflight and recovery: malformed/non-object settings fail before removal, each fault phase restores files/settings/manifest/`core.hooksPath`, retry succeeds, selected-root containment |
-| `install.profile-root.test.mjs` | Contract tests for the install-root resolver: precedence, containment boundary, external allowlist, and the install.mjs import smoke check |
-| `install-constants.mjs` | The named values `install.mjs` reads: `SKIPPED_SOURCE_ENTRY_NAMES` and `SKIPPED_SOURCE_FILE_EXTENSIONS` for the build artifacts the source walk leaves behind, `RUN_BACKUP_DIRECTORY_NAME_PATTERN` for the timestamp shape a run backup directory carries, `MANAGED_SKILLS_DIRECTORY_NAME` and `MANAGED_HOOKS_DIRECTORY_NAME` for the directory name each of those trees carries in a package source and under `~/.claude` — read by the copy loops, the hooks.json reads, the git-hook shims, the mypy configuration, and the prunes alike — `SETTINGS_FILE_NAME` for the settings file the merge, the retired-hook prune, and the uninstall purge share, and `MYPY_INI_FILE_NAME` for the home-directory file `install_mypy_ini.mjs` writes (also imported by `resolve-install-root.mjs`) |
-| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
-| `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
-| `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
-| `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
-| `install.test.mjs` | Unit tests for `install.mjs` — covers conflict detection, interpreter detection, settings merging, the settings shapes the installer never wrote — those every hook walk hands back untouched, and the shipped-event value the merge replaces with a warning — the source-artifact skip in `collectFiles`, the case-only rename decision and the `copyTree` copy that acts on it, the retired-hook diff and settings prune, the stale-file prune: the manifest diff, path-key case folding, emptied-parent cleanup, and the warn-and-keep paths, and backup retention: the sweep a moved-content run drives, the empty root a run whose moves failed gives up, and the populated root retention keeps |
-| `install.profiles.test.mjs` | Profile target-selection and per-target ownership manifest contract tests (main-default, multi-profile, ambiguity/duplicate rejection, help text) |
-| `install.plan.test.mjs` | Read-only plan and preflight tests: zero-write plan construction, source-conflict and missing-Python fail-closed, settings check only when hooks install, tolerant broken-manifest, invalid managed root, mutation-kind list for E2 |
-| `install.prune.test.mjs` | End-to-end prune tests that run the real installer against a sandbox `HOME` — retired-skill, retired-hook, and stale-file moves into one timestamped backup, the settings entry a retired hook loses, the top-level paths every root's diff leaves alone, the manifest record a failed move keeps, the full-install and resolved-dependency gates, backup retention, and the uninstall: the `~/.mypy.ini` removal, the containment guard, and nested-directory cleanup |
-| `git_hooks_installer.test.mjs` | Tests for `git_hooks_installer.mjs` |
-| `install_mypy_ini.test.mjs` | Tests for `install_mypy_ini.mjs` |
-
-## Source build artifacts
-
-`collectFiles` walks the package source and skips the artifacts a contributor's tooling writes beside it: the entry names `__pycache__`, `.ruff_cache`, `.pytest_cache`, `.mypy_cache`, `node_modules`, `.DS_Store`, and any file ending `.pyc` or `.pyo`. A skipped directory takes everything under it out of the walk. The `files` negations in `package.json` (`!**/__pycache__/**`, `!**/*.py[cod]`, the cache directories, `!**/*.log`, `!**/*.egg-info/**`) keep the same artifacts out of the published tarball, and `.npmignore` carries those patterns for tooling that reads it — keep the two in step. An `npx` install reads a clean tree; the walk covers a local `node bin/install.mjs` run against a working tree that holds the artifacts.
-
-The skip and the cleanup of artifacts an earlier install copied are one code path. A `.pyc` a prior manifest records under any managed root sits outside the set the walk returns, so the next full install reads it as stale, moves it into that run's backup root, and drops it from the manifest the run writes.
-
-## Copying a file whose name changed letter case
-
-`copyTree` renames a destination entry that differs from the shipped file name only in letter case to the shipped name, then copies. On a case-insensitive volume `copyFileSync` writes its bytes through whichever entry the filesystem resolves the path to, so a package shipping `README.md` over an installed `Readme.md` would fill the installed entry and leave the earlier spelling standing. The rename runs first because `renameSync` inside one directory is atomic: a run interrupted between the rename and the copy leaves the file present under the shipped name holding the earlier content, which the next install overwrites.
-
-The decision reads the destination directory's entry names, cached one listing per directory for the whole copy run. On a case-sensitive volume the two names are two files, so the rename is skipped and each name keeps its own content. `caseOnlyRenameSourceName(shippedName, existingNames, options)` holds the decision, and `options.isCaseInsensitive` carries the platform answer as a value so a test drives either branch on a host of either kind.
-
-## Retired-skill prune
-
-The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/skills/<skill-name>/`, a backup root outside `~/.claude/skills` so a backed-up directory is never re-discovered as a skill. The `skills/` segment mirrors `~/.claude`, matching the layout the stale-file prune writes, so one recovery point reads as a copy of the tree it came from. One run shares one timestamped root, so a run leaves one recovery point. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
-
-Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.claude/skills/_shared`, is left in place. Recovery of a wrongly-matched directory runs until the next pruning install, which keeps its own backup and retires the rest.
-
-## Stale-file prune
-
-A full install also moves aside a file under a managed root that the run leaves unwritten. `copyTree` adds and overwrites but never removes, so every root the installer writes carries the same drift, and the prune covers all of them: `rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`, `skills`, and `hooks` — the names in `MANAGED_TOP_LEVEL_DIRECTORY_NAMES`.
-
-Nothing moves unless a prior install recorded it. That single rule is what makes covering ten roots as safe as covering one: the installer reads the file list from `~/.claude/.claude-dev-env-manifest.json`, subtracts every file the run copied across all source roots, and moves what remains.
-
-The prune runs once per root, each call confined to its own root. Per-root iteration gives the containment guard and the emptied-parent walk the root that owns each file, and it settles `_shared`: `~/.claude/_shared` and `~/.claude/skills/_shared` are distinct absolute paths, so the `_shared` call and the `skills` call each see their own files and no path enters two diffs. Each root's content lands under `~/.claude/.claude-dev-env-pruned/<timestamp>/<root-name>/<relative>`, so the backup mirrors `~/.claude`. Every prune in a run shares that one timestamped root. A recorded path under no managed root — `~/.claude/CLAUDE.md`, `settings.json`, the manifest itself, and the `~/.mypy.ini` that sits in the home directory beside `~/.claude` — reaches no root's diff and stays where it is. The install summary reports the skills root's own count on the `skills:` line and the sum across roots on its own line.
-
-The manifest diff limits the move to files the installer itself wrote. Runtime-generated content — a Python `__pycache__` entry, a ruff cache, a log — and any file a user authored under a managed root stay in place, because no install recorded them. Path comparison ignores letter case on Windows and macOS, so a package shipping `README.md` over an installed `Readme.md` keeps the bytes the run just wrote. A directory or a link standing where the manifest records a file is skipped with a warning, so the mover never renames a whole tree and never follows a link out of `~/.claude`. A directory emptied by a move is removed, walking up to the root the file sat under. A move that fails logs a warning and leaves the file in place, so a prune failure costs at most a stale file. The installer records each such path in the fresh manifest when the file is still on disk, so the file stays inside the next full install's diff and gets another attempt.
-
-A missing or unreadable manifest, or one carrying no file list, holds the stale-file prune for that run: with no record of what an install wrote, the run has nothing to diff against.
-
-A run writes both manifest keys — the file list and the skill-name list — wholesale from what it just installed only when the prunes ran that run and read the prior record all the way through, so the next diff reads as "the package stopped shipping this". Every other run unions what it wrote onto the prior lists: a scoped `--only` install, a full install holding its prunes behind an unresolved dependency group, and a run whose prune step ends early with a logged warning. The union keeps every entry a later prune needs to spot a stale file or a retired skill, and keeps `--uninstall` able to name the whole tree. The prune itself bounds the lists: a stale path leaves the record on the first full install that moves it aside.
-
-## Retired-hook entries in settings.json
-
-A hook script under `~/.claude/hooks` carries a second reference: the `settings.json` entry that runs it. A full install removes that entry in the same run that moves the script aside, and removes it first — a `settings.json` naming a script that has left the hooks directory makes every session start invoke a missing file.
-
-The retired set comes from the manifest diff alone: the hook files a prior install recorded that this run leaves unwritten, each taken relative to `~/.claude/hooks`. A script the run still writes stays out of the set, and a path no install of ours recorded never enters it, so a user-authored hook is out of reach of the prune. Each command is matched on the anchored `/.claude/hooks/<relative>` tail the merge uses to tell this installer's entries from a user's, so a command whose path is a retired tail plus a suffix (`retired_gate.py.bak`) names another file and stays.
-
-The walk covers every event type the settings file holds rather than the ones the current `hooks.json` names, so an entry under an event type the package stopped shipping is reached too. A matcher group left empty is dropped, and an event type left empty goes with it. The file is written once, and only when an entry left it, so a run that retires no hook leaves `settings.json` byte-identical.
-
-Every settings walk recognizes the shapes the installer writes and steps around the rest, so a hand-edited or third-party `settings.json` carries an install through rather than ending it. A matcher group carrying no `hooks` array and a hook entry whose `command` is not a string survive every walk untouched. An event type whose value is not an array of groups survives this prune and the uninstall purge; the merge replaces that value with the group list it ships for that event type, warning with the event type named so the user can recover the value from their own history. An event type the package ships no groups for keeps whatever value the file holds.
-
-## Backup retention
-
-A run that moves content into `~/.claude/.claude-dev-env-pruned/<timestamp>/` then retires the other run backups, so the directory holds the one recovery point closest to what sits on disk. The retired-skill prune and the stale-file prune each report how many moves succeeded, and their sum is the signal the sweep answers to. The sweep removes a direct child whose name matches the installer's timestamp shape (`2026-07-25T18-04-11-923Z`), which leaves anything else under the pruned-backup directory in place, along with the directory itself. A removal that fails logs a warning and the sweep carries on, so retention never ends an install. The install output names the count when the sweep removes anything.
-
-A run that moves nothing sweeps nothing, so every recovery point the user holds stays where it is. `moveIntoRunBackup` creates the directories leading to a backup path before it renames, so a run whose every move fails — the antivirus scanner or open editor case — leaves that timestamped root standing empty. Retention clears it with `rmdirSync` alone, depth first, so a directory holding anything survives every step.
-
-## Uninstall
-
-`--uninstall` builds a read-only uninstall plan, captures a recovery snapshot, then removes each file the plan lists.
-
-Settings JSON is validated before any removal. A malformed or non-object `settings.json` fails closed with the managed files still on disk. Each manifest record passes a containment guard: the path resolves under `~/.claude`, or it names the `~/.mypy.ini` the install writes in the home directory. Every other record is skipped with a warning and counted. Skipping keeps one malformed record — hand-edited, or written by an installer that ran against a different home — from stranding the user with a half-removed install. The purge removes every legitimate record, clears the manifest, and reports the skipped count.
-
-The uninstall runs inside the same snapshot/restore journal as install: prior settings, manifest, managed files, and `core.hooksPath` restore when a later phase fails, so a retry starts from a complete ownership record. The journal is discarded only after a successful commit.
-
-Removing a file leaves its directory a candidate for cleanup. Once the file loop ends, the purge walks up from each such directory to the managed top-level directory the file sits under (`MANAGED_TOP_LEVEL_DIRECTORY_NAMES`), removing each directory it finds empty. That reaches a nested tree such as `skills/<name>/scripts/`. A record under no managed root gets no walk, so `~/.claude` itself is never a stop root and a directory the installer never wrote stays. A separate pass drops each managed top-level directory the purge empties.
-
-## Prune gates
-
-Every prune runs behind the same two gates: a full install, and every declared dependency group resolved. When any dependency group fails to resolve, all of them are skipped for the whole run with a logged notice naming the unresolved group. An unresolved dependency contributes no skills to the installed set, so a live skill that a dependency package supplies would look retired and its files would look stale; holding every prune until each dependency resolves keeps that skill's files in place and keeps their manifest records, so a run with every dependency resolved can still prune them.
-
-## Key exports from install.mjs
-
-| Export | Description |
-|---|---|
-| `CONTENT_DIRECTORIES` | Array of package subdirectory names copied verbatim to `~/.claude/` |
-| `MANAGED_TOP_LEVEL_DIRECTORY_NAMES` | The content directories plus `skills` and `hooks`; the stale-file prune walks it to give each root its own diff, and the uninstall purge reads it to find the root a recorded file belongs to |
-| `collectFiles(directory)` | Lists every file under a source directory, skipping the build-artifact names and extensions in `install-constants.mjs` |
-| `pythonCandidatesForPlatform(platform)` | Returns ordered Python interpreter candidates to probe; `py -3` first on Windows to avoid Microsoft Store alias issues |
-| `isWindowsStorePythonStub(path)` | Returns true when the path resolves to the non-spawnable WindowsApps stub |
-| `interpreterCommandFromPath(path)` | Formats an absolute interpreter path as a settings.json hook command prefix |
-| `collectPackageSourceConflicts(dir)` | Returns any unmerged git conflicts in the package source; installer aborts when any exist |
-| `pruneStaleInstalledFiles(priorFiles, currentFiles, destinationRoot, backupRoot, options)` | Moves each manifest-recorded file under the destination root that the run leaves unwritten into the run's backup root; returns `{ prunedCount, failedPaths }`. `options.isCaseInsensitive` drives path-key case folding, defaulting to this host's filesystem; `options.managedHomeDirectory` sets the home the containment guard tests against, defaulting to `~/.claude` |
-| `copyTree(sourceBase, destBase, options)` | Copies every file under a source directory, renaming a destination entry that differs from the shipped name only in letter case to the shipped name first; returns `{ created, updated, paths }`. `options.isCaseInsensitive` drives that rename, defaulting to this host's filesystem |
-| `caseOnlyRenameSourceName(shippedName, existingNames, options)` | Returns the existing directory entry a shipped file name would overwrite through a case-only spelling difference, or null; `options.isCaseInsensitive` defaults to this host's filesystem |
-| `retiredManagedHookRelativePaths(priorFiles, currentFiles, hooksRoot)` | Returns the hook script paths a prior install recorded under the hooks root that this run leaves unwritten, each relative to that root |
-| `pruneRetiredHookEntriesFromSettings(settingsPath, retiredPaths)` | Removes each settings.json entry running a retired managed hook script, writing the file only when an entry left it; returns the removed count |
-| `retainNewestRunBackupOnly(runBackupRoot, didRunMoveContent)` | Retires every run backup sitting beside the run's own when `didRunMoveContent` holds; clears the run's empty root with `rmdirSync` when it does not |
-| `comparisonKeyForPath(path, options)` | Builds the key two paths are compared through: resolved, forward-slashed, and lowercased when `options.isCaseInsensitive` holds — which defaults to true on Windows and macOS |
-
-## Install groups
-
-`install.mjs` defines install groups (`core`, `journal`) plus any dependency groups discovered from `package.json` `dependencies`. The `core` group installs skills, all hooks, and the content directories. `journal` installs only its skill set.
+@AGENTS.md

package/bin/ever-shipped-skills.mjs

@@ -39,6 +39,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'gotcha',
     'grok-spawn',
     'grokify',
+    'imagegen',
     'implement',
     'issue-tracker',
     'log-audit',

package/bin/install-constants.mjs

@@ -6,14 +6,13 @@
  */
 
 /**
- * Entry names the source walk leaves behind, whatever directory they sit in.
+ * Entry names the source walk keeps out of installed trees.
  *
- * Each name belongs to a tool that writes beside the source it reads: Python
- * bytecode caches, the ruff, pytest, and mypy caches, an installed
- * `node_modules` tree, and the macOS Finder's `.DS_Store` marker. A contributor
- * who runs the test suites and then runs `node bin/install.mjs` copies from a
- * source tree carrying all of them, so skipping the names at the walk keeps them
- * out of `~/.claude` and out of the install manifest.
+ * Each name represents local metadata or build output.
+ * A contributor who runs the test suites and then runs `node bin/install.mjs`
+ * copies from a source tree carrying these entries, so skipping the names at
+ * the walk keeps installed trees and the install manifest focused on runtime
+ * files.
  */
 export const SKIPPED_SOURCE_ENTRY_NAMES = new Set([
     '__pycache__',

package/bin/install.mjs

@@ -115,7 +115,6 @@ export const CORE_INCLUDE_DIRECTORIES = [
 ];
 
 export const CORE_SKILLS = [
-    'imagegen',
     'orchestrator', 'orchestrator-refresh', 'team-advisor', 'grokify',
     'grok-spawn',
     'small-cl', 'comments', 'reviews', 'descriptions', 'emergencies',
@@ -896,9 +895,14 @@ export function copyTree(sourceBase, destBase, options = {}) {
 
 /**
  * If destPath exists and differs from incomingPath, copy the existing file to
- * ~/.claude/backups/CLAUDE.md.<timestamp>.bak before the installer overwrites it.
+ * ~/.claude/backups/<backupName>.<timestamp>.bak before the installer overwrites it.
+ *
+ * @param {string} destPath The managed file the installer writes.
+ * @param {string} incomingPath The package file that replaces it.
+ * @param {string} backupName The managed file name used in the backup path.
+ * @returns {string|null} The backup path when existing content differs.
  */
-function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
+function backupHubBeforeOverwrite(destPath, incomingPath, backupName) {
     if (!existsSync(destPath)) return null;
     const existingBytes = readFileSync(destPath);
     const incomingBytes = readFileSync(incomingPath);
@@ -906,7 +910,7 @@ function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
     const backupsDir = join(CLAUDE_HOME, 'backups');
     mkdirSync(backupsDir, { recursive: true });
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const backupPath = join(backupsDir, `CLAUDE.md.${stamp}.bak`);
+    const backupPath = join(backupsDir, `${backupName}.${stamp}.bak`);
     copyFileSync(destPath, backupPath);
     return backupPath;
 }
@@ -2060,7 +2064,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     const claudeHubSource = join(PACKAGE_ROOT, 'CLAUDE.md');
     if (existsSync(claudeHubSource)) {
         const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
-        const backupPath = backupClaudeHubBeforeOverwrite(claudeHubDest, claudeHubSource);
+        const backupPath = backupHubBeforeOverwrite(claudeHubDest, claudeHubSource, 'CLAUDE.md');
         if (backupPath) {
             console.log(
                 `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous CLAUDE.md hub preserved)`
@@ -2070,6 +2074,19 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         allInstalledFiles.push(claudeHubDest);
         console.log(`  \u2713 ${relative(CLAUDE_HOME, claudeHubDest)} (hub)`);
     }
+    const agentsHubSource = join(PACKAGE_ROOT, 'AGENTS.md');
+    if (existsSync(agentsHubSource)) {
+        const agentsHubDest = join(CLAUDE_HOME, 'AGENTS.md');
+        const backupPath = backupHubBeforeOverwrite(agentsHubDest, agentsHubSource, 'AGENTS.md');
+        if (backupPath) {
+            console.log(
+                `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous AGENTS.md guidance preserved)`
+            );
+        }
+        copyFileSync(agentsHubSource, agentsHubDest);
+        allInstalledFiles.push(agentsHubDest);
+        console.log(`  \u2713 ${relative(CLAUDE_HOME, agentsHubDest)} (canonical guidance)`);
+    }
     const isFullInstall = !selectedGroups;
     const didPruneRun = isFullInstall && UNRESOLVED_DEPENDENCY_NAMES.length === 0;
     let failedPrunePaths = [];
@@ -2424,6 +2441,8 @@ with package, version, targetIdentity, managedRoot, files, and skills.
 
 If ~/.claude/CLAUDE.md already exists and differs from the package copy, the installer
 writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak first.
+If ~/.claude/AGENTS.md already exists and differs from the package copy, the installer
+writes the previous contents to ~/.claude/backups/AGENTS.md.<timestamp>.bak first.
 `);
 }
 

package/bin/install.test.mjs

@@ -42,6 +42,7 @@ import {
     pruneRetiredHookEntriesFromSettings,
     retainNewestRunBackupOnly,
 } from './install.mjs';
+import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
     expandHomeDirectoryTokens,
     expandHomeDirectoryTokensInSettings,
@@ -204,6 +205,14 @@ test('CORE_SKILLS ships issue-tracker so the core group installs the skill the S
 });
 
 
+test('EVER_SHIPPED_SKILL_NAMES retains imagegen so reinstall prunes the retired skill', () => {
+    assert.ok(
+        EVER_SHIPPED_SKILL_NAMES.has('imagegen'),
+        'imagegen must remain in the retirement registry after the package stops shipping it',
+    );
+});
+
+
 test('CONTENT_DIRECTORIES includes audit-rubrics so installer copies category rubrics and prompts to ~/.claude/audit-rubrics/', () => {
     assert.ok(
         CONTENT_DIRECTORIES.includes('audit-rubrics'),
@@ -1658,6 +1667,31 @@ test('collectFiles skips every named cache directory and loose bytecode file', (
 });
 
 
+test('copyTree copies AGENTS.md with agent definitions', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-agents-source-'));
+    const destinationRoot = mkdtempSync(join(tmpdir(), 'cdev-copy-agents-destination-'));
+    try {
+        writeFileSync(join(sourceRoot, 'AGENTS.md'), '# Shared guidance\n');
+        const agentDefinitionPath = join(sourceRoot, 'docs-agent.md');
+        writeFileSync(
+            agentDefinitionPath,
+            '---\nname: docs-agent\ndescription: fixture agent\n---\n',
+        );
+
+        const copyStats = copyTree(sourceRoot, destinationRoot);
+        const copiedAgentsPath = join(destinationRoot, 'AGENTS.md');
+        const copiedAgentPath = join(destinationRoot, 'docs-agent.md');
+
+        assert.equal(existsSync(copiedAgentsPath), true, 'the canonical instructions install');
+        assert.equal(existsSync(copiedAgentPath), true, 'the real agent definition installs');
+        assert.deepEqual(copyStats.paths, [copiedAgentsPath, copiedAgentPath]);
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+        rmSync(destinationRoot, { recursive: true, force: true });
+    }
+});
+
+
 const SHIPPED_README_NAME = 'README.md';
 const INSTALLED_README_NAME = 'Readme.md';
 const RETIRED_HOOK_RELATIVE_PATH = 'blocking/retired_gate.py';

package/commands/AGENTS.md

@@ -0,0 +1,23 @@
+# commands
+
+Slash-command definitions installed into `~/.claude/commands/` by `bin/install.mjs`. Each `.md` file registers a `/command-name` the user can type in Claude Code. The file name (without `.md`) becomes the command name.
+
+## Command files
+
+| File | Command | What it does |
+|---|---|---|
+| `commit.md` | `/commit` | Commits and pushes changes to GitHub |
+| `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
+| `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
+| `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
+| `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
+| `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
+| `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
+| `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
+| `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
+| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
+| `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
+
+## Format
+
+Each file is plain Markdown. The first paragraph is the command's help text shown in the Claude Code UI. The body is the full instruction set Claude follows when the command runs.

package/commands/CLAUDE.md

@@ -1,23 +1 @@
-# commands
-
-Slash-command definitions installed into `~/.claude/commands/` by `bin/install.mjs`. Each `.md` file registers a `/command-name` the user can type in Claude Code. The file name (without `.md`) becomes the command name.
-
-## Command files
-
-| File | Command | What it does |
-|---|---|---|
-| `commit.md` | `/commit` | Commits and pushes changes to GitHub |
-| `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
-| `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
-| `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |
-| `implement.md` | `/implement` | Provides full implementation context to a right-sized engineer in XML format |
-| `plan.md` | `/plan` | Plans a feature through the `anthropic-plan` skill and workflow |
-| `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
-| `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
-| `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
-| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
-| `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
-
-## Format
-
-Each file is plain Markdown. The first paragraph is the command's help text shown in the Claude Code UI. The body is the full instruction set Claude follows when the command runs.
+@AGENTS.md

package/commands/hook-log-extract.md

@@ -38,9 +38,9 @@ suspected of drift.
 bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --summary
 ```
 
-Skip extraction. Print the top-10 blockers of the last 24 hours with
-their block count and a single truncated command preview, or
-`No new blocks since last run.` when the window is empty.
+Run summary mode to print the top-10 blockers of the last 24 hours with
+their block count and a single truncated command preview. An empty window
+prints `Blocked events recorded in the last 24 hours: 0.`.
 
 ```
 bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --query <name>

package/docs/AGENTS.md

@@ -0,0 +1,32 @@
+# docs
+
+Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. These files are loaded on demand by rules, skills, and agents — they are not always-on context.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `CODE_RULES.md` | Compact agent reference for all code rules; ⚡ marks hook-enforced rules; canonical source agents load before writing code |
+| `TEST_QUALITY.md` | Test writing standards: what to test, what to remove, React testing patterns, anti-patterns |
+| `BDD_DISCOVERY_PROTOCOL.md` | Example Mapping algorithm for discovery before implementation; based on Smart & Molak *BDD in Action* §6.4 |
+| `BDD_SCENARIO_QUALITY.md` | Seven scenario quality patterns (§7.6-style catalog) |
+| `BDD_TEST_LAYOUT.md` | `describe/when/should` test layout and soap-opera personas |
+| `DJANGO_PATTERNS.md` | Django-specific coding patterns |
+| `REACT_PATTERNS.md` | React-specific coding patterns |
+| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
+| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
+| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
+| `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
+| `host-pool-health-monitor.md` | Operator recipe for Windows pool/handle health: thresholds, clean-shell re-run of `Capture-PoolHealth.ps1`, RC2/RC3/RC4 remediation map |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `references/` | Pointer documents to external sources and standard terminology; loaded on demand |
+
+## Load pattern
+
+A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
+
+The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.

package/docs/CLAUDE.md

@@ -1,32 +1 @@
-# docs
-
-Reference documentation installed into `~/.claude/docs/` by `bin/install.mjs`. These files are loaded on demand by rules, skills, and agents — they are not always-on context.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `CODE_RULES.md` | Compact agent reference for all code rules; ⚡ marks hook-enforced rules; canonical source agents load before writing code |
-| `TEST_QUALITY.md` | Test writing standards: what to test, what to remove, React testing patterns, anti-patterns |
-| `BDD_DISCOVERY_PROTOCOL.md` | Example Mapping algorithm for discovery before implementation; based on Smart & Molak *BDD in Action* §6.4 |
-| `BDD_SCENARIO_QUALITY.md` | Seven scenario quality patterns (§7.6-style catalog) |
-| `BDD_TEST_LAYOUT.md` | `describe/when/should` test layout and soap-opera personas |
-| `DJANGO_PATTERNS.md` | Django-specific coding patterns |
-| `REACT_PATTERNS.md` | React-specific coding patterns |
-| `agent-spawn-protocol.md` | Full agent-spawn protocol behind the `rules/agent-spawn-protocol.md` kernel: context-sufficiency check, `/prompt-generator` prompt crafting, and the spawn step |
-| `nas-ssh-invocation.md` | Full NAS ssh policy behind the `rules/nas-ssh-invocation.md` kernel: the OpenSSH binary form, config sources, and hook enforcement |
-| `worker-completion-gate.md` | Full worker-completion gate behind the `rules/workers-done-before-complete.md` kernel: the checklist, examples, and run-state records |
-| `wsl-docker-cowork-starter-matrix.md` | Host matrix: WSL/Docker/cowork component → starter → required? → shutdown; policy options with costs; no unmeasured `.wslconfig` memory cap |
-| `host-pool-health-monitor.md` | Operator recipe for Windows pool/handle health: thresholds, clean-shell re-run of `Capture-PoolHealth.ps1`, RC2/RC3/RC4 remediation map |
-
-## Subdirectory
-
-| Entry | Description |
-|---|---|
-| `references/` | Pointer documents to external sources and standard terminology; loaded on demand |
-
-## Load pattern
-
-A rule points to a doc with the path wrapped in backticks, such as `@~/.claude/docs/<file>.md`. The backticks make it a plain pointer: Claude Code reads the doc only when a rule, skill, or agent opens it, so the doc stays out of session-start context. The same path without backticks expands into context at launch when it sits in a file that loads at session start.
-
-The `InstructionsLoaded` hook confirms this: a bare `@`-import fires an `include` load event; a backtick-wrapped path fires none.
+@AGENTS.md

package/docs/CODE_RULES.md

@@ -1,6 +1,6 @@
 # Code Rules Reference
 
-Compact **projection** of the repository-root canonical policy [`AGENTS.md`](../../../AGENTS.md). When this file and `AGENTS.md` disagree, **`AGENTS.md` wins** — update this projection in the same change.
+Compact **projection** of the checked-in review contract [`.cursor/BUGBOT.md`](../../../.cursor/BUGBOT.md). Update this reference alongside the full review contract when review rules change.
 
 ⚡ marks rules enforced by hand-maintained `code_rules_enforcer.py` — the hook blocks the Write/Edit and returns the corrective detail at violation time, so this document lists those rules by name only. Session policy (question routing, task tracking) lives in `rules/*.md`; see [`code-standards.md`](../rules/code-standards.md).
 

package/docs/imagegen.md

@@ -0,0 +1,22 @@
+# Image generation
+
+The canonical image-generation entrypoint lives in the
+`python-automation` repository at `shared_utils.imagegen`.
+
+Resolve `python_automation_root` and `python_exe` from the repository's
+`run/tooling.json`, set `PYTHONPATH` to the resolved root, and run:
+
+```powershell
+$tooling = Get-Content '<REPO>\\run\\tooling.json' | ConvertFrom-Json
+$python_automation_root = $tooling.python_automation_root
+$python_executable = $tooling.python_exe
+$env:PYTHONPATH = $python_automation_root
+
+& $python_executable -m shared_utils.imagegen `
+  --prompt-file <PROMPT.txt> `
+  --size 2880x2880 `
+  --out <IMAGE.png>
+```
+
+Repeat `--reference-image <IMAGE.png>` for up to two visual references.
+The command verifies the decoded PNG dimensions before reporting success.

package/docs/references/AGENTS.md

@@ -0,0 +1,17 @@
+# docs/references
+
+Pointer documents to external sources, standard terminology, and internal tool or skill usage. Files here are loaded on demand by rules that cite them.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
+| `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
+| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
+| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
+
+## Role
+
+A file naming an external concept gives a one-line definition and links a direct source. A file naming an internal tool or skill describes what it does and when to use it. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.

package/docs/references/CLAUDE.md

@@ -1,17 +1 @@
-# docs/references
-
-Pointer documents to external sources, standard terminology, and internal tool or skill usage. Files here are loaded on demand by rules that cite them.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `dead-code-elimination.md` | External sources and standard terms behind CODE_RULES §9.8 (remove code you orphan): DCE, tree shaking, reachability analysis, and the Lava Flow anti-pattern |
-| `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
-| `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
-| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
-| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
-
-## Role
-
-A file naming an external concept gives a one-line definition and links a direct source. A file naming an internal tool or skill describes what it does and when to use it. They back the rule text in `rules/` and `packages/claude-dev-env/docs/CODE_RULES.md` without embedding full third-party content inline.
+@AGENTS.md

package/hooks/AGENTS.md

@@ -0,0 +1,31 @@
+# hooks
+
+Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each hook answers one or more lifecycle events (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`) and either blocks a tool call, annotates it, or performs a side-effect.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `advisory/` | Hooks that warn but do not block (`permissionDecision: "ask"`) |
+| `blocking/` | Hooks that deny tool calls when a rule is violated |
+| `blocking/config/` | Shared constants for blocking hooks |
+| `diagnostic/` | Hooks that record and extract hook-firing records into Neon |
+| `diagnostic/migrations/` | SQL migrations for the `hook_events` Neon schema |
+| `diagnostic/queries/` | Parameterized SQL queries for inspecting blocked commands |
+| `git-hooks/` | Native git hooks (`pre-commit`, `pre-push`, `post-commit`) installed via the git-hooks path |
+| `git-hooks/git_hooks_constants/` | Shared constants for the git-hook scripts |
+| `hooks_constants/` | Shared constant modules imported by multiple hooks across this tree (includes `pii_prevention_constants.py` for personal-data and secret scan patterns) |
+| `lifecycle/` | Hooks that run at session or config-change boundaries |
+| `observability/` | PostToolUse hooks that record agent behavior for diagnostics |
+| `session/` | SessionStart and SessionEnd hooks for per-session cleanup |
+| `validation/` | PostToolUse hooks that validate code quality after a write (mypy, auto-format) |
+| `validators/` | Library modules used by the validation hooks — checks split by concern |
+| `workflow/` | PostToolUse hooks that trigger doc publishing and companion-file generation |
+
+## Conventions
+
+- **Event mapping:** Every hook reads JSON from stdin and exits 0 (allow) or prints a `hookSpecificOutput` block (block/ask). Blocking hooks set `permissionDecision: "block"`.
+- **Constants companion:** Each hook with more than a handful of tunable strings keeps them in a `hooks_constants/<hook_name>_constants.py` sibling. Import from there; do not repeat literals.
+- **Tests:** Each hook has one or more `test_<hookname>*.py` files beside it. Run with `python -m pytest <test_file>`.
+- **Registration:** Hooks are declared in `settings.json` under the right lifecycle event. The installer (`packages/claude-dev-env/bin/install.mjs`) merges the hook entries during `npx claude-dev-env`.
+- **Top-level utilities:** `_gh_pr_author_swap_utils.py` and `rewrite_plugin_paths.py` are shared helpers imported by multiple blocking hooks. `hooks.json` records the canonical hook-to-event mapping for auditing.

package/hooks/CLAUDE.md

@@ -1,31 +1 @@
-# hooks
-
-Python hook scripts wired into Claude Code's lifecycle via `settings.json`. Each hook answers one or more lifecycle events (`PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`) and either blocks a tool call, annotates it, or performs a side-effect.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `advisory/` | Hooks that warn but do not block (`permissionDecision: "ask"`) |
-| `blocking/` | Hooks that deny tool calls when a rule is violated |
-| `blocking/config/` | Shared constants for blocking hooks |
-| `diagnostic/` | Hooks that record and extract hook-firing records into Neon |
-| `diagnostic/migrations/` | SQL migrations for the `hook_events` Neon schema |
-| `diagnostic/queries/` | Parameterized SQL queries for inspecting blocked commands |
-| `git-hooks/` | Native git hooks (`pre-commit`, `pre-push`, `post-commit`) installed via the git-hooks path |
-| `git-hooks/git_hooks_constants/` | Shared constants for the git-hook scripts |
-| `hooks_constants/` | Shared constant modules imported by multiple hooks across this tree (includes `pii_prevention_constants.py` for personal-data and secret scan patterns) |
-| `lifecycle/` | Hooks that run at session or config-change boundaries |
-| `observability/` | PostToolUse hooks that record agent behavior for diagnostics |
-| `session/` | SessionStart and SessionEnd hooks for per-session cleanup |
-| `validation/` | PostToolUse hooks that validate code quality after a write (mypy, auto-format) |
-| `validators/` | Library modules used by the validation hooks — checks split by concern |
-| `workflow/` | PostToolUse hooks that trigger doc publishing and companion-file generation |
-
-## Conventions
-
-- **Event mapping:** Every hook reads JSON from stdin and exits 0 (allow) or prints a `hookSpecificOutput` block (block/ask). Blocking hooks set `permissionDecision: "block"`.
-- **Constants companion:** Each hook with more than a handful of tunable strings keeps them in a `hooks_constants/<hook_name>_constants.py` sibling. Import from there; do not repeat literals.
-- **Tests:** Each hook has one or more `test_<hookname>*.py` files beside it. Run with `python -m pytest <test_file>`.
-- **Registration:** Hooks are declared in `settings.json` under the right lifecycle event. The installer (`packages/claude-dev-env/bin/install.mjs`) merges the hook entries during `npx claude-dev-env`.
-- **Top-level utilities:** `_gh_pr_author_swap_utils.py` and `rewrite_plugin_paths.py` are shared helpers imported by multiple blocking hooks. `hooks.json` records the canonical hook-to-event mapping for auditing.
+@AGENTS.md

package/hooks/_gh_pr_author_swap_utils.py

@@ -155,6 +155,20 @@ def _switch_gh_account(to_account: str) -> bool:
     return completed_process.returncode == 0
 
 
+def _build_restore_failure_message(
+    hook_label: str,
+    original_account: str,
+    state_file: Path,
+    state_file_context: str,
+) -> str:
+    """Build the shared diagnostic for a failed account restoration."""
+    return (
+        f"[{hook_label}] Restore the gh account to {original_account!r}; "
+        f"gh account switch requires attention for {state_file_context} {state_file}. "
+        "The file remains for the next session."
+    )
+
+
 def _read_original_account(state_file: Path) -> str | None:
     """Read the original-account login from a swap-state file.
 

package/hooks/advisory/AGENTS.md

@@ -0,0 +1,16 @@
+# hooks/advisory
+
+Hooks that produce a warning prompt (`permissionDecision: "ask"`) rather than an outright block. The user sees the warning and can continue or cancel.
+
+## Key files
+
+| File | Event | What it guards |
+|---|---|---|
+| `migration_safety_advisor.py` | PreToolUse (Write/Edit) | Django migration files containing `RemoveField`, `RenameField`, `DeleteModel`, or `RenameModel` — warns that these operations must be backwards-compatible during deployment |
+| `refactor_guard.py` | PreToolUse (Edit) | Edits that rename or restructure existing code not present in the current git diff — warns that the change may be out of scope |
+
+## Conventions
+
+- Both hooks exit 0 (silent) when their trigger condition is not met.
+- `refactor_guard.py` respects a bypass token at `~/.claude/.refactor-bypass-token`; when that file exists the hook stays silent.
+- Tests live beside each hook following the `test_<name>.py` pattern used in `blocking/`. Run with `python -m pytest <test_file>`.

package/hooks/advisory/CLAUDE.md

@@ -1,16 +1 @@
-# hooks/advisory
-
-Hooks that produce a warning prompt (`permissionDecision: "ask"`) rather than an outright block. The user sees the warning and can continue or cancel.
-
-## Key files
-
-| File | Event | What it guards |
-|---|---|---|
-| `migration_safety_advisor.py` | PreToolUse (Write/Edit) | Django migration files containing `RemoveField`, `RenameField`, `DeleteModel`, or `RenameModel` — warns that these operations must be backwards-compatible during deployment |
-| `refactor_guard.py` | PreToolUse (Edit) | Edits that rename or restructure existing code not present in the current git diff — warns that the change may be out of scope |
-
-## Conventions
-
-- Both hooks exit 0 (silent) when their trigger condition is not met.
-- `refactor_guard.py` respects a bypass token at `~/.claude/.refactor-bypass-token`; when that file exists the hook stays silent.
-- Tests live beside each hook following the `test_<name>.py` pattern used in `blocking/`. Run with `python -m pytest <test_file>`.
+@AGENTS.md