diff --git a/.extra.tmpl b/.extra.tmpl
index 4a828deb1db..ffa481e9bf2 100644
--- a/.extra.tmpl
+++ b/.extra.tmpl
@@ -2,24 +2,10 @@
 #
 # ~/.extra — machine-local secrets / overrides, sourced last by .zshrc.
 #
-# This TEMPLATE is tracked in the repo. bootstrap.sh renders it to ~/.extra
-# with 1Password's `op inject` (output mode 0600), so real secret *values*
-# never touch the repo — only op:// reference paths do. The rendered ~/.extra
-# is gitignored.
+# Rendered to ~/.extra by 1Password's `op inject` (bootstrap.sh runs it when
+# ~/.extra is missing). See CLAUDE.md "Machine-local secrets" for the exact
+# reference format and workflow.
 #
-# To add a secret:
-#   1. Store it in 1Password.
-#   2. Add an export below whose value is the secret's reference path, WRAPPED
-#      IN DOUBLE CURLY BRACES. The commented examples show the path format;
-#      to activate one, uncomment it and wrap the op://... path in {{ }}.
-#      (In the 1Password app: right-click a field -> "Copy Secret Reference".)
-#   3. Re-render (bootstrap.sh only renders when ~/.extra is missing):
-#          op inject -i .extra.tmpl -o ~/.extra -f
-#
-# With no braced references present, this renders to an (inert) ~/.extra.
-#
-# --- Examples — path format only; uncomment + add {{ }} to activate ---------
-
-# export GITHUB_TOKEN="op://Private/GitHub PAT/token"
-# export ANTHROPIC_API_KEY="op://Private/Anthropic API/credential"
-# export HOMEBREW_GITHUB_API_TOKEN="op://Private/GitHub PAT/token"
+# WARNING: op inject parses this ENTIRE file, comments included. Never write
+# curly-brace pairs or an "op" URI scheme anywhere in it except as a real,
+# brace-wrapped secret reference — anything else is a render error.
diff --git a/CLAUDE.md b/CLAUDE.md
index c397cbf0a71..82a2753bd1e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -86,3 +86,20 @@ only exists locally). There is **no GPG keypair** in this setup despite the
 ### Machine-local customization
 
 Add `~/.extra` (not committed) for per-machine overrides. Add `~/.path` for per-machine PATH entries. The `.macos` script skips the computer name block if `$COMPUTER_NAME` is unset.
+
+### Machine-local secrets (~/.extra)
+
+`~/.extra` is rendered from the tracked `.extra.tmpl` by 1Password's
+`op inject`. bootstrap.sh runs it automatically when `~/.extra` is missing;
+re-render manually with `op inject -i .extra.tmpl -o ~/.extra -f`. The
+template stores only secret *references*, never values:
+
+    export GITHUB_TOKEN="{{ op://Private/GitHub PAT/token }}"
+
+Get a reference path from the 1Password app: right-click a field →
+"Copy Secret Reference".
+
+CAUTION: `op inject` parses the whole template, comments included, and
+errors on any curly-brace pair or bare `op://` text that isn't a real
+brace-wrapped reference. That's why these instructions live here and not in
+the template itself. `tests/extra-tmpl.bats` enforces the invariant.
diff --git a/tests/extra-tmpl.bats b/tests/extra-tmpl.bats
new file mode 100644
index 00000000000..9cd4b59c666
--- /dev/null
+++ b/tests/extra-tmpl.bats
@@ -0,0 +1,31 @@
+#!/usr/bin/env bats
+
+# op inject parses ALL of .extra.tmpl — comments included — and errors on
+# any curly-brace pair or bare op:// text that isn't a real brace-wrapped
+# secret reference. These tests enforce that invariant without needing the
+# op CLI (CI runners don't have it); real references only ever appear on
+# non-comment export lines.
+
+TMPL=".extra.tmpl"
+
+@test "extra.tmpl comment lines contain no curly braces" {
+  cd "$BATS_TEST_DIRNAME/.."
+  run grep -nE '^[[:space:]]*#.*(\{\{|\}\})' "$TMPL"
+  [ "$status" -ne 0 ]
+}
+
+@test "extra.tmpl comment lines contain no op:// references" {
+  cd "$BATS_TEST_DIRNAME/.."
+  run grep -nE '^[[:space:]]*#.*op://' "$TMPL"
+  [ "$status" -ne 0 ]
+}
+
+@test "extra.tmpl secret references are brace-wrapped and well-formed" {
+  cd "$BATS_TEST_DIRNAME/.."
+  # Any op:// on an active line must look like "{{ op://vault/item/field }}"
+  # (at least three path segments) — a bare or malformed reference is a
+  # render error waiting to happen.
+  while IFS= read -r line; do
+    [[ "$line" =~ \{\{\ *op://[^/]+/[^/]+/[^}]+\ *\}\} ]]
+  done < <(grep -E '^[^#]*op://' "$TMPL" || true)
+}