diff --git a/website/docs/plugins/buildfile.md b/website/docs/plugins/buildfile.md
index 69c371e..64da976 100644
--- a/website/docs/plugins/buildfile.md
+++ b/website/docs/plugins/buildfile.md
@@ -150,7 +150,10 @@ target(
 ```
 
 By default paths are resolved relative to the BUILD file's package; pass
-`abs = True` to resolve from the workspace root instead.
+`abs = True` to resolve from the workspace root instead. Paths are lexically
+normalized — `./` prefixes and empty segments are collapsed, `..` components
+resolve against the package path, and a path whose `..` segments escape the
+workspace root is an error.
 
 ### `target()` — what buildfile reads, and what it forwards
 
diff --git a/website/docs/plugins/exec.md b/website/docs/plugins/exec.md
index e2215a5..750008e 100644
--- a/website/docs/plugins/exec.md
+++ b/website/docs/plugins/exec.md
@@ -163,6 +163,10 @@ target(
 `support_files` declares files a target produces that are **not** outputs — kept
 in the sandbox for the command's own use but not published to dependents.
 
+Output and support-file paths are lexically normalized: `./` prefixes and empty
+segments are stripped, `..` resolves against the package path, and a path that
+escapes the workspace root is an error.
+
 ## Environment passthrough
 
 `pass_env` and `runtime_pass_env` each accept a list of variable names to
@@ -207,7 +211,7 @@ target(
 `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`). |