diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..635002b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,19 @@
+# LibrePortal — agent notes
+
+## Verify WebUI changes visually before marking them done
+After changing anything user-visible in the WebUI (`containers/libreportal/frontend/`),
+confirm it actually renders correctly — syntax checks and type-correctness don't
+catch layout or visual regressions.
+
+The maintainer's dev environment provides a headless screenshot helper, `lp-shot`,
+that captures a WebUI route (or a single element, via a trailing CSS selector) to a
+PNG for review:
+
+```
+lp-shot /admin/system                       # full route -> /tmp/webui-shot.png
+lp-shot /admin/system /tmp/x.png 12 ".sys-strip"   # just one element, crisp
+```
+
+Use it (and read the PNG) to self-check UI work instead of assuming it looks right or
+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.