From 3dcb4b5c020ae9d56e4cc4a52f80dd7876077931 Mon Sep 17 00:00:00 2001
From: Evan Jarrett <evan@evanjarrett.com>
Date: Mon, 24 Aug 2026 14:53:58 -0500
Subject: [PATCH] test/e2e: document the batch-10 traps

Five things that each produced a confident wrong answer during val/10-anonpull,
so the next batch does not rediscover them: the repo page route, tags living in
a <select>, headed Chromium not launching from an agent shell, logged-out
checks needing their own browser profile, and the dev hold defaulting to
public:false with a propagation delay after the flip.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SeaUS5AFPX9gqCahoLRMRh
---
 test/e2e/README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/test/e2e/README.md b/test/e2e/README.md
index 3fde46b..4134a37 100644
--- a/test/e2e/README.md
+++ b/test/e2e/README.md
@@ -64,6 +64,36 @@ for crew on a tier absent from quota config (`handleCrewList`), so it is invisib
 on a healthy hold. Crew add/update do not validate the tier against config,
 which is how these tests manufacture the condition without restarting the hold.
 
+**The repo page is `/r/{handle}/*`.** Not `/{handle}/{repo}` — that is a 404
+"Lost at Sea" page, which reads exactly like an access denial if you are
+checking whether a logged-out visitor gets denied. Verify the route before
+concluding anything from a 404.
+
+**Tags are `<option>`s in a `<select>`.** Scraping `a`, `td` or `span` for tag
+text finds nothing and reports "no tags render" against a page that is
+rendering them correctly.
+
+**A headed browser will not launch from an agent shell here.** Both
+`chromium.launch()` and `launchPersistentContext()` time out on the handshake
+despite `DISPLAY=:0` being set; headless works. Interactive flows (the admin
+login, `docker-credential-atcr login`) still need a human at a real browser —
+but non-interactive page checks can run headless, and `batch10-anonpull.mjs`
+does.
+
+**Logged-out checks need their own profile.** `lib.mjs`'s `PROFILE` is signed
+in, and clearing its cookies costs an interactive re-login for everything else.
+Use a throwaway `launchPersistentContext` dir instead of a fresh
+`chromium.launch()`.
+
+**The dev hold is `public: false` by default,** so anything testing the
+*allowed* half of anonymous pull is unreachable until you flip it. Do not edit
+the captain record: `hold_pds.go:335` reconciles `captain.Public` from config
+on every boot, so an untracked `docker-compose.override.yml` setting
+`HOLD_SERVER_PUBLIC: "true"` flips it, and deleting the file flips it back.
+Never commit that file. Allow ~15s after the container comes up for the appview
+to see the new value — a token minted too early is still judged against the old
+one, which looks exactly like a failing test.
+
 ## Per-batch stack switching
 
 Use `val-switch.sh`. The appview DB migrates **forward only**, so older batch