diff --git a/CLAUDE.md b/CLAUDE.md
index 0663e14..2463daf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -18,13 +18,17 @@ Use it (and read the PNG) to self-check UI work instead of assuming it looks rig
 asking the user to look. Skip it for purely backend/non-visual edits. If `lp-shot`
 isn't present, fall back to asking the user for a screenshot.
 
-Every route except `/` is behind the WebUI login, so `lp-shot` needs a session in
-the environment — `LP_SHOT_TOKEN` (the `libreportal_token` cookie) or
-`LP_SHOT_USER` + `LP_SHOT_PASS`. Without one it stops with that message rather
-than screenshotting the sign-in box. Only the maintainer sets those: ask them to
-export it (or to run the `lp-shot` command for you) — never go looking for the
-credentials yourself. `lp-shot --help` lists the rest (`LP_SHOT_URL`,
-`LP_SHOT_VIEWPORT`, `LP_SHOT_SCALE`, …).
+Every route except `/` is behind the WebUI login, and `lp-shot` handles that
+itself — it signs a one-hour session from the `jwtSecret` the backend stores in
+`frontend/.auth.json`, the same token `/api/auth/login` would issue. No password
+is involved (the stored one is a bcrypt hash). So no setup: just run it. Override
+with `LP_SHOT_TOKEN`, or `LP_SHOT_USER`+`LP_SHOT_PASS`, when shooting a remote
+instance. `lp-shot --help` lists the rest (`LP_SHOT_URL`, `LP_SHOT_VIEWPORT`,
+`LP_SHOT_SCALE`, …).
+
+If a shot comes back as the boot splash, the page wasn't ready — `lp-shot` waits
+for `#libreportal-loading-screen` to leave the DOM, so a splash in the PNG means
+boot genuinely stalled. Read the `page error:` lines it prints to stderr.
 
 Testing against the live WebUI means updating the running install, not just the
 repo: `/libreportal-containers/libreportal/frontend/` is bind-mounted into the