docs: document heph tool clean

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. 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)`. |
 

website/docs/concepts/caching.md

@@ -115,3 +115,26 @@ 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).
+
+:::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.
+:::