docs(claude): codify VM test-iteration workflow

1 files changed, 5 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index a35c2e9..3264692 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -128,3 +128,8 @@ Full palette reference: `assets/color-themes/dupre/dupre-palette.org`
 - Never assume which machine this is — always run `uname -n` to find the hostname (the `hostname` binary is absent, so `uname -n` is the source of truth; `uname -r` is the kernel release, not the host). The fleet is **ratio** (workstation) and **velox** (laptop), both Hyprland (Wayland). archsetup still supports dwm/X11, but no current machine uses it.
 - Remote repository on cjennings.net
 - .ai/ is gitignored; living project context is in .ai/notes.org
+
+## Codified Insights
+
+- **VM tests run committed code, not your working tree.** `scripts/testing/run-test.sh` provisions the VM from `git bundle create <file> HEAD` (it simulates `git clone`), so an uncommitted edit to `archsetup` or the pytest suite silently runs the old code. Commit (even a throwaway WIP commit) before `make test FS_PROFILE=...`, or the change isn't exercised. (`gotcha` — 2026-06-25)
+- **Iterate the pytest sweep against a kept VM, not a reinstall.** `make test-keep FS_PROFILE=...` leaves the VM up after the install and writes `testinfra_ssh_config` + `root_key` into `test-results/<timestamp>/`. Point pytest at that ssh-config to re-run only the Testinfra checks in ~30s instead of a ~70-minute full reinstall. Use it when iterating test assertions, not installer logic. (`pattern` — 2026-06-25)