From 342b533f4f9b573120c9876a63fd4e638aa3c255 Mon Sep 17 00:00:00 2001
From: claude-hdb <dan@heavyduty.builders>
Date: Wed, 15 Jul 2026 00:28:15 +0000
Subject: [PATCH] docs(readme): how to run the drill against the latest version
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The drill section showed the commands but not the step that actually
bites: making sure the checkout you run is the code you mean to judge.
Two versions are in play — the drill script itself, and the (repo, ref)
the drill installs from GitHub and asserts before any verdict. Spell both
out, plus --repo/--ref for drilling a release or a PR branch.

Also catch drill.sh's REPO default up with the rename — it still said
heavy-duty/claudebox (GitHub redirects it, but the default should name
the repo that exists).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md      | 20 ++++++++++++++++++++
 drill/drill.sh |  2 +-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4909cc7..b0d5cd6 100644
--- a/README.md
+++ b/README.md
@@ -249,13 +249,33 @@ pre-0.4.0 box through `migrate-host`, and removes what it minted —
 currently **81 checks, 81 passing**. [drill/RUNS.md](drill/RUNS.md) is the full
 history, including every trap that fooled a run into a wrong verdict.
 
+### Run the drill yourself
+
+The drill ships in the repo, not the installed tree — run it from a checkout.
+Two versions are in play and both must be current: **the drill script you
+run** (a stale checkout judges the past), and **the code under test** — the
+drill does not test your working tree; it installs box from GitHub
+(default: `heavy-duty/box@main`) and asserts the installed tree is exactly
+the ref it asked for before issuing any verdict.
+
 ```sh
+git clone https://github.com/heavy-duty/box && cd box   # or refresh an existing
+git log --oneline -1                                    #   checkout — this commit is
+                                                        #   the drill that will judge
 bash drill/doctor.sh    # read-only: is this host healthy and the stack live?
 bash drill/drill.sh     # FULL end-to-end — mutates the host; use a machine you own
 bash drill/wipe.sh      # scorched earth: strip BOTH name generations, images and
                         #   (--purge-storage) the pool, so a run starts from bare
 ```
 
+To drill something other than latest `main` — a release ref, or a PR branch
+on a fork:
+
+```sh
+bash drill/drill.sh --ref <branch-or-tag>
+bash drill/drill.sh --repo <owner>/<repo> --ref <branch>   # a PR under review
+```
+
 The doctor reads ground truth, not config claims — the kernel's `isolated on`
 flag per bridge port, the process table, the resolver actually in use — and
 diagnoses the host faults that have actually happened: a wedged Incus daemon,
diff --git a/drill/drill.sh b/drill/drill.sh
index 77c8be5..8e56575 100755
--- a/drill/drill.sh
+++ b/drill/drill.sh
@@ -32,7 +32,7 @@
 # false FAILs on the first live run. The pipeline verdict must be grep's alone.
 set -u
 
-REPO="${BOX_REPO:-heavy-duty/claudebox}"
+REPO="${BOX_REPO:-heavy-duty/box}"
 REF="${BOX_REF:-main}"
 YES=0; KEEP=0
 SELF="$(readlink -f "$0")"