dev-prune-darwin-x64 1.8.0 → 1.10.0

package/README.md

@@ -66,7 +66,7 @@ a single Rust binary, installs its own background schedule, and answers to two n
 
 <div align="center">
 
-**Start here**&nbsp;&nbsp; [Install](#install) · [Editors](#in-your-editor) · [60-second tour](#60-second-tour) · [What it looks like](#what-it-looks-like)
+**Start here**&nbsp;&nbsp; [Install](#install) · [Where it is published](#every-place-it-is-published) · [Editors](#in-your-editor) · [60-second tour](#60-second-tour) · [What it looks like](#what-it-looks-like)
 
 **How it thinks**&nbsp;&nbsp; [Why it is safe](#why-it-is-safe) · [Features](#features) · [Commands](#commands) · [Ecosystems](#supported-ecosystems) · [Monorepos](#repositories-with-more-than-one-ecosystem)
 
@@ -120,6 +120,9 @@ problem.
 
 ```bash
 npm install -g dev-prune      # or: npx dev-prune status
+bun add -g dev-prune          # same package, through bun
+pnpm add -g dev-prune
+yarn global add dev-prune     # Yarn 1.x
 uv tool install dev-prune     # or: uvx dev-prune status
 pipx install dev-prune
 pip install dev-prune
@@ -127,9 +130,10 @@ cargo binstall dev-prune      # fetches the prebuilt release archive
 cargo install dev-prune       # builds from source, needs Rust 1.88+
 ```
 
-The npm and PyPI packages **contain the binary** — there is no download step at install
-time, so they work under `npm ci --ignore-scripts`, behind a registry mirror and offline.
-Everything but `cargo install` ships a prebuilt executable.
+The [npm](https://www.npmjs.com/package/dev-prune) and
+[PyPI](https://pypi.org/project/dev-prune/) packages **contain the binary** — there is no
+download step at install time, so they work under `npm ci --ignore-scripts`, behind a
+registry mirror and offline. Everything but `cargo install` ships a prebuilt executable.
 
 npm delivers it the way esbuild and Biome do: one small `dev-prune` package that lists
 seven platform packages as optional dependencies, of which npm installs exactly the one
@@ -137,8 +141,14 @@ matching your machine. That is why there is no download step to block. Windows w
 1.8.0 onwards — earlier versions installed and then reported no binary to run, so a
 machine still holding `dev-prune@1.7.0` needs `npm install -g dev-prune@latest`.
 
-crates.io stores source and nothing else, so `cargo install` has no binary to fetch and
-always compiles. [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) is the
+bun, pnpm and Yarn install that same package, and dev-prune treats each as a channel of
+its own rather than as npm: a copy `bun add -g` put there is upgraded and removed with
+bun. Running npm against it would install a *second* copy under npm's prefix and leave
+bun's, still on `PATH`, at the old version. `devp update --channels` prints every
+channel's upgrade command if you want to see the whole table.
+
+[crates.io](https://crates.io/crates/dev-prune) stores source and nothing else, so
+`cargo install` has no binary to fetch and always compiles. [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) is the
 one that downloads: `Cargo.toml` tells it where this project's release archives live, so
 it unpacks the same executable the installers use, with no toolchain involved.
 
@@ -214,6 +224,18 @@ rules file that editor actually reads — `.github/copilot-instructions.md`, `.c
 `CLAUDE.md`, `.junie/guidelines.md` and the rest — so an agent working in the repository
 knows what dev-prune will and will not delete before it suggests anything.
 
+**Claude Code can go first**, before `devp` exists on the machine at all — this
+repository is also a Claude Code plugin marketplace:
+
+```text
+/plugin marketplace add Life-Experimentalist/dev-prune
+/plugin install dev-prune@dev-prune
+```
+
+One skill, no hooks and no MCP server, and it is the same `SKILL.md` the binary embeds.
+That is the useful order for an agent: read what dev-prune does and refuses to do, then
+install it.
+
 Everything about editors, in one place:
 [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md).
 
@@ -270,6 +292,39 @@ Every install channel in detail: [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md).
 > terminal and a scheduled task alike — with no profile to re-source, and no chance of an
 > upgrade leaving `devp` on the old version.
 
+### Every place it is published
+
+Nine channels, one project. The middle column is the **exact** string each registry
+answers to — names this close together are how a typo becomes somebody else's package,
+so they are worth copying rather than typing.
+
+| Where | Published as | What you get |
+|---|---|---|
+| [crates.io](https://crates.io/crates/dev-prune) | **`dev-prune`** | Source. `cargo install` compiles it; `cargo binstall` fetches the release archive instead. |
+| [PyPI](https://pypi.org/project/dev-prune/) | **`dev-prune`** | Six wheels, each containing the binary. `pip`, `pipx`, `uv tool`. |
+| [npm](https://www.npmjs.com/package/dev-prune) | **`dev-prune`** | A dispatcher plus seven platform packages; npm installs the one matching your machine. |
+| [GitHub Releases](https://github.com/Life-Experimentalist/dev-prune/releases) | `dev-prune-v<ver>-<platform>` | Seven checksummed, provenance-attested archives. What the install scripts fetch. |
+| [Homebrew](https://github.com/Life-Experimentalist/homebrew-tap) | **`Life-Experimentalist/tap`** | A one-formula tap, so `brew upgrade` keeps finding new versions. |
+| [Scoop](https://github.com/Life-Experimentalist/scoop-bucket) | **`life-experimentalist`** | A one-manifest bucket, for the same reason. |
+| [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=VKrishna04.dev-prune) | **`VKrishna04.dev-prune`** | The editor extension. VS Code and the forks on Microsoft's gallery. |
+| [Open VSX](https://open-vsx.org/extension/VKrishna04/dev-prune) | **`VKrishna04.dev-prune`** | The same extension, for VSCodium, Cursor, Windsurf, Positron and Kiro. |
+| [SchemaStore](https://www.schemastore.org/) | **`.devprune.json`** | The config schema, by filename. No extension and no `$schema` key needed. |
+
+[WinGet](https://github.com/microsoft/winget-pkgs/pull/422809) is submitted and in
+review. It is not in the table because it does not resolve yet.
+
+Two of those rows are not installs of dev-prune at all. SchemaStore is why JetBrains
+IDEs, Visual Studio, Neovim and Zed validate `.devprune.json` with nothing installed —
+the catalog entry points at a schema this repository hosts. And the editor extension is
+a separate product with a separate version number, released on its own `vscode-v*` tags,
+which is why the release marked *latest* on GitHub is always the CLI.
+
+Anything calling itself dev-prune from anywhere other than these was not published by
+its author. `devp doctor` names the channel the running copy came from, and every
+release archive carries [GitHub build provenance](docs/RELEASING.md) that
+`gh attestation verify` checks against this repository — a checksum only proves a file
+arrived intact, which a substituted pair also does.
+
 ---
 
 ## 60-second tour
@@ -287,6 +342,7 @@ A few more worth knowing on day one:
 ```bash
 devp stats                  # how much has been reclaimed so far, and by which repositories
 devp caches                 # every package manager cache, sized. The report deletes nothing
+devp caches docker          # what Docker holds, and the prune commands. Read-only, permanently
 devp status --drift         # anything installed that the lockfiles don't record?
 devp doctor .               # why is this repository not being pruned?
 devp doctor --fix           # repair a broken integration — never a first-time install
@@ -379,6 +435,13 @@ Package manager caches
   Total                  21.99 GiB  across 12 caches
 
 → Nothing above was deleted, and dev-prune never deletes any of it.
+
+Container engines
+
+  docker                          47.64 GiB  36.69 GiB reclaimable · devp caches docker
+
+  Container images, volumes and build cache are not package manager caches and are not in
+  the total above — dev-prune reports them and never deletes them.
 ```
 
 A cache lives outside every repository and is shared by all of them, so no single
@@ -395,6 +458,64 @@ a registered repository, and each such row names its store in the command it pri
 
 </details>
 
+<details>
+<summary><b><code>devp caches docker</code></b> — the engine that is usually bigger than all of them</summary>
+
+```console
+$ devp caches docker
+
+Container engines
+
+  docker
+
+  Images            37.36 GiB     29.28 GiB reclaimable   41 items, 9 in use
+  Containers         1.19 GiB      1.12 GiB reclaimable   12 items, 3 in use
+  Local Volumes      2.79 GiB           0 B reclaimable   5 items, 2 in use
+  Build Cache        6.29 GiB      6.29 GiB reclaimable   41 items, 0 in use
+
+  Total             47.64 GiB     36.69 GiB reclaimable
+
+  Reclaim it yourself             what it takes with it
+  docker builder prune            the build cache; costs a slower next build
+  docker image prune              dangling images no tag points at any more
+  docker container prune          stopped containers and each writable layer
+  docker system prune             the three above at once; volumes untouched
+  docker system prune --volumes   adds unused volumes — the one that deletes data
+
+  Nothing above was deleted, and nothing dev-prune runs on a schedule will ever delete it.
+  An image has no lockfile to prove it can be rebuilt, and a named volume is the one thing
+  here that cannot be rebuilt at all — so this command measures, prints the commands, and
+  leaves the decision with you.
+```
+
+Clearing 6 GiB of npm cache while a Docker install nobody has looked at in a year sits on
+40 GiB is the mistake this exists to prevent. `devp caches podman` and `devp caches
+nerdctl` are the same report for those engines, and `devp caches containers` runs every
+one it finds and lists any local Kubernetes clusters (kind, k3d, minikube) by name.
+
+**It is read-only, permanently.** There is no flag and no `clear` verb that makes
+dev-prune run one of those commands — `devp caches clear docker` is a usage error that
+says so — and no scheduler or Git hook reaches this code at all. That is the same rule
+as everywhere else rather than extra caution: an image has no lockfile to prove it can be
+rebuilt, the Dockerfile that built it may not be on this disk, and a named volume is the
+one thing on the machine that cannot be rebuilt at all.
+
+The figures come from the engine's own `system df`, not a walk of the disk. On Docker
+Desktop and Podman the store lives inside a VM disk image the host filesystem cannot see,
+so a size taken off the disk would be wrong by orders of magnitude in the reassuring
+direction — and asking is the only way to learn what is *reclaimable*, which is the
+figure that decides anything. 40 GB of images with 38 GB dangling is a different
+situation from 40 GB with 2 GB dangling.
+
+An engine that is installed with its daemon stopped is reported as exactly that, quoting
+the engine's own first line, and contributes no figures: a blank, not a zero. An engine
+that is not installed is absent from the report rather than listed as missing. Local
+Kubernetes clusters are named and deliberately not sized — their nodes are containers
+belonging to an engine already in the table, so a figure beside the cluster name would be
+the same gigabytes counted twice.
+
+</details>
+
 <details>
 <summary><b><code>devp doctor .</code></b> — the one reason a repository is being skipped</summary>
 
@@ -468,13 +589,14 @@ process that leaves a dirty working tree is a surprise.
 | 🧩 **Any number of ecosystems per repository** | uv, npm and cargo in one root, or spread across `frontend/`, `services/api/` and `tools/cli/` — each discovered, verified and pruned on its own terms                                                                                                                                                                                                       |
 | ↩️ **One-command restore**                     | `devp restore .` reinstalls a tree; `devp restore --last-run` puts back exactly what the most recent pass deleted, across every repository it touched                                                                                                                                                                                                       |
 | 🕒 **Activity-aware**                          | Combines `git log` timestamps with source-file `mtime`, so uncommitted work protects a repository just as a commit does                                                                                                                                                                                                                                     |
+| 🐳 **Container report**                        | `devp caches docker` (also `podman`, `nerdctl`, or `containers` for all of them plus local Kubernetes clusters) breaks a container engine's disk into images, containers, local volumes and build cache, each with what the engine itself calls reclaimable, and prints the prune commands narrowest first with what each takes with it. **Read-only, permanently** — `devp caches clear docker` is a usage error, and no scheduler or hook reaches this code: an image has no lockfile to prove it can be rebuilt, and a named volume cannot be rebuilt at all. `devp caches` carries a one-line summary per engine, outside its own total |
 | 📊 **Cache report**                            | `devp caches` sizes every package manager cache and store on the machine — npm to cargo to conda, Maven, Gradle, NuGet, vcpkg, Conan, Composer, CocoaPods and Hex — and prints the command that clears each. The report is read-only; `devp caches clear <manager>` runs that command for you, after asking. `devp config set cache_max_gb uv=10,npm=10` says how big is too big, per manager, and marks the ones past it — `devp caches clear --over-cap all` then empties exactly those, still only when you type it. Each manager also says how many of your registered repositories use it and what that works out to per repository, and `devp caches clear --unused all` empties the ones nothing uses at all. pnpm is reported once per filesystem, because a store it hardlinks into `node_modules` cannot cross one and projects kept off the system disk get a store of their own. Nothing on a schedule ever touches a cache, and Maven's `~/.m2/repository` is never cleared at all — it holds artifacts `mvn install:install-file` put there that no remote can hand back |
 | 🩺 **`devp doctor`**                           | One read-only pass that ends by naming the *single* reason a repository would or would not be pruned. Runs no package manager, repairs nothing, safe to run twice. `devp doctor --fix` then mends what it found — installed-but-broken only                                                                                                                 |
 | 🤖 **Self-installing automation**              | OS-native scheduler (Task Scheduler, LaunchAgent, systemd user timer) and non-blocking Git hooks, installed at install time and restored after an upgrade. `auto_setup`, `auto_hooks`, `auto_daemon` or `DEV_PRUNE_NO_AUTO_SETUP=1` turn it off                                                                                                             |
 | ⚡ **0ms opt-out**                             | An `ignore.devprune.json` in a repository root is honoured by file presence alone — no read, no parse                                                                                                                                                                                                                                                       |
 | 🔌 **`--json` on every reporting command**     | `run`, `status`, `stats`, `trust` and `caches` each emit one versioned document on stdout, diagnostics on stderr. Built for scripts and agents                                                                                                                                                                                                              |
-| 🧠 **AI agent skill**                          | A token-lean `SKILL.md` embedded in the binary; `devp skill` exports it and prints onboarding prompts for Claude Code, Gemini Antigravity, Cursor, Windsurf, Copilot and OpenClaw                                                                                                                                                                           |
-| 🧰 **Editor extension**                        | Validates `.devprune.json` as you type and shows the workspace's reclaimable size in the status bar. `devp setup` offers to install it — once, only at a terminal — into VS Code, VSCodium, Cursor, Windsurf, Positron or Kiro, each from its own registry with the release `.vsix` as fallback. [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md)         |
+| 🧠 **AI agent skill**                          | A token-lean `SKILL.md` embedded in the binary; `devp skill` exports it and prints onboarding prompts for Claude Code, Gemini Antigravity, Cursor, Windsurf, Copilot and OpenClaw, and the repository doubles as a Claude Code plugin marketplace                                                                                                                                                                           |
+| 🧰 **Editor extension**                        | Validates `.devprune.json` as you type and shows the workspace's reclaimable size in the status bar. `devp setup` offers to install it — once, only at a terminal — into VS Code, VSCodium, Cursor, Windsurf, Positron or Kiro, each from its own registry, falling back to the `.vsix` from the extension's own release. [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md)         |
 | 🖼️ **File manager icons**                      | `devp icon` registers `*.devprune.json` with the OS file manager — a real `shared-mime-info` type plus hicolor icons on Linux, a folder icon on Windows. It never edits your editor settings, `PATH` or shell startup files                                                                                                                                 |
 | 🌏 **Unicode-safe paths**                      | A repository at `ワークスペース/项目目录名称测试/프론트엔드` scans, verifies, prunes and restores exactly like an ASCII one, on all three platforms. Terminal tables are padded by display *column*, not by character, so full-width CJK names keep `devp status` and `devp doctor` aligned. Accented Latin, Cyrillic, Arabic and emoji directory names too |
 | 🚫 **No telemetry**                            | One optional unauthenticated `GET` to GitHub's public releases endpoint, at most weekly, no body and no identifier. Nothing else leaves the machine                                                                                                                                                                                                         |
@@ -491,9 +613,10 @@ process that leaves a dirty working tree is a surprise.
 | `devp undo`            | :------------------------------------------------------------------ | Reverts the most recent `init` or `link`                                                                                                                                                                                                                      |
 | `devp run [PATH]`      | `--dry-run`, `--only`, `--skip`, `--except`, `--min-size`, `--json` | Prunes every registered repository, or one target                                                                                                                                                                                                             |
 | `devp status`          | `--top N`, `--drift`, `--json`                                      | Interactive dashboard; a plain table when there is no TTY. `--top N` shows only the N biggest repositories; `--drift` lists every environment holding packages its lockfile never recorded                                                                    |
-| `devp stats`           | `--json`                                                            | What has already been reclaimed: lifetime total, prune passes, the last pass, and the biggest contributors                                                                                                                                                    |
+| `devp stats`           | `--json`                                                            | What has already been reclaimed: lifetime total from pruning, a separate lifetime total from `devp caches clear`, prune passes, the last pass, and the biggest contributors                                                                                                                                                    |
 | `devp completions`     | `bash`, `zsh`, `fish`, `powershell`, `elvish`                       | Prints a shell completion script to stdout, generated from the same argument definitions the binary parses with                                                                                                                                               |
 | `devp caches`          | `clear <manager\|all>`, `--json`                                    | Sizes every package manager cache on the machine and prints the command that clears each. The report deletes nothing and nothing on a schedule ever will; `clear` empties one when you type it, after asking                                                  |
+| `devp caches docker`   | `podman`, `nerdctl`, `containers [ENGINE]`, `--json`                | What a container engine holds — images, containers, volumes, build cache — each sized, with what the engine calls reclaimable, then the prune commands. Read-only permanently: it prints them, you run them                                                |
 | `devp trust`           | `--json`                                                            | What dev-prune may do on this machine: the guarantees the code enforces, then the scheduler, hooks and settings read live. Read-only                                                                                                                          |
 | `devp restore [PATH]`  | `--last-run`                                                        | Reinstalls dependencies for every project in a tree; `--last-run` undoes the last prune pass                                                                                                                                                                  |
 | `devp doctor [PATH]`   | `--fix`                                                             | Diagnoses the installation, or one repository — ending with the single reason a pass would or would not touch it. `--fix` repairs what the checks found; it never performs a first-time install                                                               |
@@ -661,30 +784,159 @@ Global settings live in `%APPDATA%\dev-prune` (Windows),
 once on a first install — so the defaults are something you agreed to rather than
 inherited — and again after an upgrade adds a setting you have never been shown.
 
-| Key                                                                                |  Default  | Meaning                                                                             |
-| :--------------------------------------------------------------------------------- | :-------: | :---------------------------------------------------------------------------------- |
-| `idle_days`                                                                        |   `15`    | How long a repository must be untouched to become a candidate                       |
-| `min_size_mb`                                                                      |    `0`    | Smallest bloat directory worth deleting; `0` disables the floor                     |
-| `scan_depth`                                                                       |    `6`    | Levels below a repository root that discovery descends                              |
-| `require_confirmation`                                                             |  `true`   | Whether a pass asks before deleting                                                 |
-| `allow_manifest_rewrite`                                                           |  `false`  | Whether verification may *repair* a drifted lockfile instead of refusing            |
-| `command_timeout_secs`                                                             |   `600`   | Ceiling on any one package manager command                                          |
-| `auto_setup` · `auto_daemon` · `auto_hooks`                                        |  `true`   | Whether the integration pass may run unattended, and what it may install            |
-| `auto_hooks_chain`                                                                 |  `false`  | Whether it may take a `core.hooksPath` another tool holds, forwarding every hook on |
-| `check_interval_days`                                                              |    `2`    | How often the OS scheduler runs a pass                                              |
-| `update_check`                                                                     |  `true`   | Whether the periodic release check runs                                             |
-| `update_check_interval_days` · `update_check_timeout_secs`                         | `7` · `5` | Minimum gap between checks, and how long one may hang                               |
-| `enable_cargo` … `enable_cmake_build`                                              |  `false`  | Turn on an opt-in build-tool adapter; `build_idle_days` (`45`) gates all eight      |
-| `adapter_idle_days`                                                                | *(none)*  | Per-adapter idle floors, as `cargo=90,npm=30` — each raises only its own window     |
-| `disabled_adapters`                                                                | *(none)*  | Adapters to leave alone entirely, by name — as if that ecosystem were not installed |
-| `cache_max_gb`                                                                     | *(none)*  | Per-manager cache caps in GiB, as `uv=10,npm=10` — the cap itself deletes nothing   |
+If you already know what you want, `devp config recommended` is the one-command version:
+it turns on the eight adapters and build trees that are off by default because they are
+not universally wanted, and leaves `allow_manifest_rewrite` — the one recommendation
+that edits files Git tracks — named, explained and off unless you add
+`--with-cautious`. `devp config show` lists whatever you have not taken yet.
+
+Thirty settings, in the seven groups the configurator asks them in — the order the
+decisions actually arrive in. Every key, with its full description and range, is in the
+[CLI reference](docs/CLI_REFERENCE.md#8-devp-config-action).
+
+**The language this is all in** — what dev-prune prints its own headings in.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `language` | `en` | One of twelve catalogues — `en`, `zh`, `hi`, `te`, `ta`, `kn`, `ml`, `bn`, `mr`, `gu`, `pa`, `sa`. Only dev-prune's own headings and summary lines move; `--json`, exit codes, flag names, config keys and adapter names are English in every one, so nothing a script reads changes. `DEV_PRUNE_LANG` overrides it for one command. See [TRANSLATIONS.md](docs/TRANSLATIONS.md) |
+
+**What gets pruned** — the size and age of what a pass considers at all.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `idle_days` | `15` | How long a repository must be untouched to become a candidate |
+| `min_size_mb` | `0` | Smallest bloat directory worth deleting; `0` disables the floor |
+| `scan_depth` | `6` | Levels below a repository root that discovery descends |
+| `disabled_adapters` | *(none)* | Adapters to leave alone entirely, by name — as if that ecosystem were not installed |
+| `adapter_idle_days` | *(none)* | Per-adapter idle floors, as `cargo=90,npm=30` — each raises only its own window |
+
+**Before anything is deleted** — what stands between a candidate and a deletion.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `require_confirmation` | `true` | Whether a pass asks before deleting |
+| `allow_manifest_rewrite` | `false` | Whether verification may *repair* a drifted lockfile instead of refusing |
+| `command_timeout_secs` | `600` | Ceiling on one package manager command; nothing compiles under it |
+
+**Build trees — off by default**, because everything here comes back by recompiling
+rather than downloading. That is the whole reason each one is a switch.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `enable_cargo` … `enable_cmake_build` | `false` | Turn on an opt-in build-tool adapter; `build_idle_days` (`45`) gates all eight |
+
+**Shared download caches** — one key, because the cap only ever marks.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `cache_max_gb` | *(none)* | Per-manager cache caps in GiB, as `uv=10,npm=10` — the cap itself deletes nothing |
+
+**Running without being asked** — what dev-prune may install here, and how often it may
+act on its own.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `auto_setup` · `auto_daemon` · `auto_hooks` | `true` | Whether the integration pass may run unattended, and what it may install |
+| `auto_config` | `false` | Whether `devp init` / `devp link` write a `.devprune.json` into newly registered repositories |
+| `auto_hooks_chain` | `false` | Whether it may take a `core.hooksPath` another tool holds — off, it is not yours |
+| `check_interval_days` | `2` | How often the OS scheduler runs a pass |
+
+**Keeping dev-prune current** — whether this copy looks for a newer one, and may install it.
+
+| Key | Default | Meaning |
+| :--- | :---: | :--- |
+| `update_check` | `true` | Whether the periodic release check runs |
+| `update_check_interval_days` · `update_check_timeout_secs` | `7` · `5` | Minimum gap between checks, and how long one may hang |
+| `auto_update` | `true` | Install a newer release at the end of a pass. Stands aside on WinGet, Scoop and Homebrew, where the manager owns the upgrade |
+| `version_lock` | `false` | Pin this copy to the version it is. Nothing dev-prune does then replaces the binary, and there is no flag that bypasses it |
+
+### Per-repository settings
 
 Three of them — `idle_days` (as `override_idle_days`), `min_size_mb` and `scan_depth` —
-also take a per-repository form in that project's `.devprune.json`, where they win for
-that tree only. The rest are deliberately global: a project can commit its
-`.devprune.json`, and a repository you have never read should not be able to grant itself
+also take a per-repository form, where they win for that tree only. The rest are
+deliberately global: a repository you have never read should not be able to grant itself
 permission to have its manifests rewritten during an unattended pass.
 
+A repository can hold **two** config files, and the difference is who they are for.
+
+| File | Committed? | For |
+|---|---|---|
+| `.devprune.json` | No — added to `.git/info/exclude` when written | Your copy of this one repository, on this one machine |
+| `project.devprune.json` | **Yes** — `devp config project . --team` writes it to be staged | What the project decided, reaching a fresh clone by itself |
+
+Where both exist, **every key the project file names wins**, and the personal file
+answers everything it does not. That is the inverse of the usual "local overrides
+global", and deliberately: a colleague's stale local answer should not quietly overrule
+what the project decided, while a personal override still works on every setting the team
+left open. "Names a key" means the key is literally in the file — a project file that
+never mentions `ignore` does not un-ignore your repository, which is why it is created
+holding nothing but its `$schema` line.
+
+```mermaid
+flowchart TD
+    Key["One setting, in one repository"] --> Shared{"Named in<br/>project.devprune.json?"}
+    Shared -->|Yes| WinShared["The team's value.<br/>Committed, so a fresh clone starts here."]
+    Shared -->|No| Personal{"Named in<br/>.devprune.json?"}
+    Personal -->|Yes| WinPersonal["Your value.<br/>Never committed, never in git status."]
+    Personal -->|No| Global["The global setting on this machine,<br/>or its default."]
+```
+
+Nothing dev-prune writes on its own touches the shared file. `devp link`,
+`devp doctor --fix`, `devp config project . --update` and `[i]` in the dashboard all
+write `.devprune.json`, so no routine action of yours turns into a change on a branch
+your colleagues share; `--team` is the only way to write the other file, and you
+have to type it. Run `devp config project .` in a repository that has both and it
+prints which file each effective value came from.
+
+### Directories only the project knows about
+
+Every adapter earns its right to delete the same way: it finds a lockfile, verifies the
+lockfile can rebuild what is about to go, and only then deletes. Some trees have no
+lockfile and are still rebuildable — a generated fixture set, a vendored toolchain, a
+cache with a `make` target behind it. A repository can name those itself, in either
+config file:
+
+```json
+{
+  "prunable": {
+    "directories": [
+      {
+        "path": "tools/vendor",
+        "rebuild": "make vendor",
+        "why": "regenerated from tools/manifest.toml"
+      }
+    ]
+  }
+}
+```
+
+`rebuild` is required, and required is the point: an optional one would make "delete
+this, I have no idea how to get it back" the easiest thing to write in a file that gets
+committed and cloned. If a directory genuinely needs nothing to bring it back, say so
+— `"rebuild": "echo not needed"` is a legal answer and works on every platform.
+dev-prune shows the command; it never runs it.
+
+Declared directories go through the ordinary pass under the adapter name `declared`, so
+they are listed by `devp status`, obey `--dry-run`, `--min-size` and `--only`, and are
+deleted by the scheduled run alongside everything else.
+
+A declaration is a claim, not an instruction. `project.devprune.json` is committed, so a
+repository you cloned can declare whatever it likes, and `devp run` may be running from a
+scheduler with nobody watching. Before deleting one, dev-prune requires that:
+
+- the path is relative, has no `..`, and is neither `.git` nor the repository root;
+- it resolves to somewhere inside the repository, even through a symlinked parent;
+- Git is tracking nothing inside it — a lockfile cannot rebuild a file that is in the
+  repository itself;
+- the first word of `rebuild` is a program this machine actually has.
+
+A claim that fails any of those is printed with the reason, and nothing is deleted.
+
+This section is the one part of either file that does not follow the precedence above:
+the two lists **add up**. A list is not a decision, so a team declaration never discards
+one you wrote yourself, and naming the same path in both leaves one directory, rebuilt
+by the committed command.
+
 An out-of-range value is rejected with the range in the message rather than silently
 clamped. `scan_depth` included: `config set` accepts `1`–`32` and refuses anything else
 outright — the clamp to that range survives only as the backstop for a hand-edited
@@ -747,7 +999,7 @@ flowchart TD
 
     Engine --> FastIgnore{ignore.devprune.json?}
     FastIgnore -->|Exists| Skip["Skip Repo O(1) 0ms"]
-    FastIgnore -->|Missing| PerRepoConfig["Read .devprune.json"]
+    FastIgnore -->|Missing| PerRepoConfig["Read project.devprune.json,<br/>then .devprune.json"]
 
     PerRepoConfig --> GitScanner["Git Scanner & Activity Solver<br/>(.git commits + mtime fallback)"]
     Engine --> PreCheck["Required Ecosystem Binary Pre-Checker"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-prune-darwin-x64",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Prebuilt dev-prune binary for darwin x64. Installed automatically by the 'dev-prune' package; not meant to be depended on directly.",
   "os": ["darwin"],
   "cpu": ["x64"],