From 0b7f1a1ec03f35a26f20817843786b447e1a8811 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?=
 <raphaelvigee@users.noreply.github.com>
Date: Sat, 20 Jun 2026 18:14:10 +0100
Subject: [PATCH] docs: document per-target remote cache exclusion
 (cache.remote)

Following hephbuild/heph#108 which fixed the engine to actually honor
the per-target `remote_enabled` flag. The cache={remote: False} option
existed and was set by the nix driver, but was silently ignored by the
engine. Now that it works, document it in both exec.md and remote-cache.md.
---
 website/docs/guides/remote-cache.md | 24 ++++++++++++++++++++++
 website/docs/plugins/exec.md        | 31 ++++++++++++++++++++++++++++-
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/website/docs/guides/remote-cache.md b/website/docs/guides/remote-cache.md
index 3d7ea32..32bf488 100644
--- a/website/docs/guides/remote-cache.md
+++ b/website/docs/guides/remote-cache.md
@@ -96,6 +96,30 @@ Remote cache latency (fastest first):
 The `[rw]` flags show the configured `read`/`write` permissions. The order
 is persisted and reused automatically until the cache definitions change.
 
+## Excluding targets from the remote cache
+
+Some targets produce outputs that embed host-local paths — a wrapper script
+that references an absolute path in a local toolchain store, for example.
+Sharing those artifacts causes another machine to pull a wrapper that points
+at a path it doesn't have, which fails at run time.
+
+Set `cache = {"remote": False}` on those targets. Local caching stays on;
+heph will never upload the artifact to or download it from a remote cache:
+
+```python title="BUILD"
+target(
+    name = "local-wrapper",
+    driver = "exec",
+    run = ["./gen-wrapper.sh"],
+    out = "wrapper.sh",
+    cache = {"remote": False},
+)
+```
+
+Every machine builds its own copy and caches it locally. Targets that depend
+on it get a local hit on the same machine; other machines build their own copy
+on first use.
+
 ## In CI
 
 A typical CI setup: grant write access to CI runners and read access
diff --git a/website/docs/plugins/exec.md b/website/docs/plugins/exec.md
index 67eb4c3..e2215a5 100644
--- a/website/docs/plugins/exec.md
+++ b/website/docs/plugins/exec.md
@@ -93,7 +93,7 @@ The following target config keys are available:
 | `pass_env`         | Host vars passed at parse time and hashed into the cache key. Accepts `["*"]` to pass all. |
 | `runtime_pass_env` | Host vars passed at run time only, not hashed. Accepts `["*"]` to pass all. |
 | `runtime_env`      | Runtime literal environment variables.               |
-| `cache`            | Bool or `{enabled, remote, history}`.                |
+| `cache`            | `True`/`False` toggles local + remote together; dict: `{enabled, remote, history}`. |
 | `codegen`          | Write generated outputs into the source tree (`copy` or `in_place`). |
 
 These environment variables are available inside the sandbox:
@@ -202,6 +202,35 @@ target(
 )
 ```
 
+## Cache control
+
+`cache` accepts a bare bool or a dict with up to three keys:
+
+| Key | Type | Default | Meaning |
+|-----|------|---------|---------|
+| `enabled` | bool | `true` | Enable local caching for this target. |
+| `remote` | bool | `true` | Enable remote caching for this target. Set `false` when outputs embed host-local paths that cannot be safely shared across machines. |
+| `history` | int | `1` | Number of past revisions to retain in the local cache (minimum `1`). |
+
+A bare `True` sets both `enabled` and `remote` to `true`. A bare `False` disables both.
+
+Use `cache = {"remote": False}` to keep local caching on but opt a specific
+target out of remote push and pull — useful for targets whose outputs reference
+paths that only exist on the machine that built them:
+
+```python title="BUILD"
+target(
+    name = "wrapper",
+    driver = "exec",
+    run = ["./gen-wrapper.sh"],
+    out = "wrapper.sh",
+    cache = {"remote": False},
+)
+```
+
+The target still builds and caches locally; it is never uploaded to or pulled
+from a remote cache.
+
 ## Interactive debugging with `--shell`
 
 When a target fails, drop into its sandbox with the exact inputs, tools, and