diff --git a/AGENT-BRIEF.md b/AGENT-BRIEF.md
index 49fc85c60..d18b39d4b 100644
--- a/AGENT-BRIEF.md
+++ b/AGENT-BRIEF.md
@@ -150,6 +150,31 @@ with **each other**, not with the source. The same shape bit a `git merge` in th
 instead of piping, or `set -o pipefail` first. If you want short output AND a reliable
 status, capture to a file and `tail` the file afterwards.
 
+### And capture the status into a variable, not `$?` later
+
+`$?` is a single slot that EVERY command overwrites — including the harmless one somebody
+adds months later for readability. Measured here:
+
+```sh
+some_command > log 2>&1
+sed -n '1p' log                 # redact a token, rotate the log, echo a heading — anything
+if [ "$?" -ne 0 ]; then ...     # tests SED, not some_command. A failure reads as success.
+```
+
+The durable form names it on the very next line, and branches on the name:
+
+```sh
+some_command > log 2>&1
+rc=$?                           # nothing may come between these two lines
+sed -n '1p' log                 # now insert whatever you like
+if [ "$rc" -ne 0 ]; then tail log; exit 1; fi
+```
+
+Both were run: with the `sed` in between, the bare `$?` reported success on a command that
+had failed; `rc` still read 1. This is the same family as the pipe above — a status you read
+one step too late is a status about something else — and it matters most in exactly the
+scripts that redact a token before printing a log, because that redaction looks harmless.
+
 ## Landing on main: the shape of the lock
 
 `main` is shared and serialized by `main-capture`. The ordering is load-bearing and BOTH