From 4768380b5ae13fe0cee966ea49f89fcbf669abdb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Aug 2026 08:11:03 +0000
Subject: [PATCH 1/2] docs: document heph tool clean
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

heph adds `heph tool clean <selection>` (hephbuild/heph#357) — removes
every cached revision of the selected target(s), regardless of the
history budget and whether or not the target still exists, as a
targeted counterpart to `heph tool gc`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cabo8vZ6e78QQWULEbAoG3
---
 .../heph-expert/skills/heph/references/cli.md    |  1 +
 website/docs/concepts/caching.md                 | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/plugins/heph-expert/skills/heph/references/cli.md b/plugins/heph-expert/skills/heph/references/cli.md
index eb06843..e441670 100644
--- a/plugins/heph-expert/skills/heph/references/cli.md
+++ b/plugins/heph-expert/skills/heph/references/cli.md
@@ -86,6 +86,7 @@ Maintenance subcommands operating on the workspace or local cache.
 | Subcommand | Does |
 |---|---|
 | `heph tool gc` | Garbage-collect the local cache (`.heph3/cache`): remove artifacts no longer reachable from any current target. Resolves specs, so providers may run. |
+| `heph tool clean <TARGET_ADDRESS>` / `heph tool clean <LABEL> <PACKAGE_MATCHER>` / `heph tool clean -e <EXPR>` | Remove every cached revision of the selected target(s) — all of them, regardless of `history`, whether or not the target still exists. Selection required (no whole-cache default, so a bare `heph tool clean` prints help); `all <PACKAGE_MATCHER>` selects by package without a label, same as `query`. `heph tool clean all //...` clears the entire local cache. |
 | `heph tool gen-gitignore [PACKAGE_MATCHER]` | Write/refresh the managed heph block in the root `.gitignore` with all `codegen = "copy"` outputs. Idempotent; a matcher rebuilds only that subtree's lines. |
 | `heph tool completions <SHELL>` | Emit a shell completion-registration script, e.g. `source <(heph tool completions zsh)`. |
 
diff --git a/website/docs/concepts/caching.md b/website/docs/concepts/caching.md
index 6816192..741ab13 100644
--- a/website/docs/concepts/caching.md
+++ b/website/docs/concepts/caching.md
@@ -115,3 +115,19 @@ that's no longer reachable (removed targets, orphaned entries):
 ```bash title="terminal"
 heph tool gc
 ```
+
+To deliberately remove cached entries for a specific target selection instead —
+every revision, regardless of `history`, whether or not the target still
+exists — use `heph tool clean`. Targets are selected the same way as for
+`run`: an address, a label followed by a package matcher, or `-e '<expr>'`.
+
+```bash title="terminal"
+heph tool clean //cmd/server:bin      # one target (that exact variant)
+heph tool clean all //cmd/...         # every cached target under a subtree
+heph tool clean test //cmd/...        # every target labelled "test"
+heph tool clean all //...             # clear the entire local cache
+```
+
+The selection is required — a bare `heph tool clean` prints help instead of
+wiping the cache. `all` selects a package without naming a label, the same way
+it does for [`query`](/docs/plugins/query).

From ff3c57b17dd5df7cb29c78d2ab630deb0507a739 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 5 Aug 2026 08:28:33 +0000
Subject: [PATCH 2/2] docs: note that clean shouldn't be a routine workaround

Per review feedback on #89: reaching for `heph tool clean` regularly on
an unchanged target is a symptom of an under-declared input, not
something to build a workflow around.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cabo8vZ6e78QQWULEbAoG3
---
 plugins/heph-expert/skills/heph/references/cli.md | 2 +-
 website/docs/concepts/caching.md                  | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/plugins/heph-expert/skills/heph/references/cli.md b/plugins/heph-expert/skills/heph/references/cli.md
index e441670..924df3b 100644
--- a/plugins/heph-expert/skills/heph/references/cli.md
+++ b/plugins/heph-expert/skills/heph/references/cli.md
@@ -86,7 +86,7 @@ Maintenance subcommands operating on the workspace or local cache.
 | Subcommand | Does |
 |---|---|
 | `heph tool gc` | Garbage-collect the local cache (`.heph3/cache`): remove artifacts no longer reachable from any current target. Resolves specs, so providers may run. |
-| `heph tool clean <TARGET_ADDRESS>` / `heph tool clean <LABEL> <PACKAGE_MATCHER>` / `heph tool clean -e <EXPR>` | Remove every cached revision of the selected target(s) — all of them, regardless of `history`, whether or not the target still exists. Selection required (no whole-cache default, so a bare `heph tool clean` prints help); `all <PACKAGE_MATCHER>` selects by package without a label, same as `query`. `heph tool clean all //...` clears the entire local cache. |
+| `heph tool clean <TARGET_ADDRESS>` / `heph tool clean <LABEL> <PACKAGE_MATCHER>` / `heph tool clean -e <EXPR>` | Remove every cached revision of the selected target(s) — all of them, regardless of `history`, whether or not the target still exists. Selection required (no whole-cache default, so a bare `heph tool clean` prints help); `all <PACKAGE_MATCHER>` selects by package without a label, same as `query`. `heph tool clean all //...` clears the entire local cache. Needing this regularly on an unchanged target usually means that target under-declares an input — fix the target, don't make `clean` routine. |
 | `heph tool gen-gitignore [PACKAGE_MATCHER]` | Write/refresh the managed heph block in the root `.gitignore` with all `codegen = "copy"` outputs. Idempotent; a matcher rebuilds only that subtree's lines. |
 | `heph tool completions <SHELL>` | Emit a shell completion-registration script, e.g. `source <(heph tool completions zsh)`. |
 
diff --git a/website/docs/concepts/caching.md b/website/docs/concepts/caching.md
index 741ab13..edcc49e 100644
--- a/website/docs/concepts/caching.md
+++ b/website/docs/concepts/caching.md
@@ -131,3 +131,10 @@ heph tool clean all //...             # clear the entire local cache
 The selection is required — a bare `heph tool clean` prints help instead of
 wiping the cache. `all` selects a package without naming a label, the same way
 it does for [`query`](/docs/plugins/query).
+
+:::tip
+Reaching for `clean` regularly on a target that hasn't changed is usually a
+symptom, not a fix — it means the cache is returning something stale, which
+points at an under-declared input on that target rather than a cache problem.
+Track down the missing input instead of making `clean` part of your workflow.
+:::