diff --git a/website/docs/guides/inspecting-builds.md b/website/docs/guides/inspecting-builds.md
index 56831ae..aa10fdd 100644
--- a/website/docs/guides/inspecting-builds.md
+++ b/website/docs/guides/inspecting-builds.md
@@ -64,6 +64,39 @@ Useful when a provider adds its own callable beyond the core
 [builtins](/docs/plugins/buildfile#authoring-build-files), or to check argument
 names and types before writing a call.
 
+## Reading failure output
+
+When a target fails, heph prints a diagnostic box with the trailing lines of its
+process log:
+
+```
+× target failed: //app:server
+╰─▶ exit status: 1
+    ╭─[log]
+  91 │ connecting to db...
+  92 │ FATAL: connection refused
+    ╰────
+```
+
+Line numbers reflect the real position in the full log — the last 10 lines of a
+100-line log are numbered 91–100, not 1–10.
+
+By default, `heph run` shows 10 trailing lines. Use `--log-lines` to see more:
+
+```bash title="terminal"
+heph run //app:server --log-lines 50
+```
+
+The full log is always written to `log.txt` inside the target's sandbox. A
+failed target's sandbox is preserved until its next run, so you can read the
+complete log by opening the sandbox:
+
+```bash title="terminal"
+heph run //app:server --shell
+# then inside the shell:
+cat log.txt
+```
+
 ## Reproducing the environment
 
 To go past inspection and actually poke at a failing target, open its