diff --git a/AGENTS.md b/AGENTS.md
index 742ac56..b6c257a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,3 +58,12 @@ Where Woof — a **return-tag platform** (not a tracker): pre-coded QR/NFC tags
 - `pkill -f` can match your own shell — use `pkill -x where-woof`
 - Reset the DB between the two verify suites (both bind `TEST000001`)
 - Postgres identity columns advance on failed inserts (duplicate-email test consumes an id)
+
+## KNOWN-GOOD STATE (2026-08-10) — read before testing
+
+- **User photo upload**: inside the MAIN edit form (`frontend/templates/tag-edit.html`) — `<input type="file" name="photo">` + Save; no JS needed. Live preview via FileReader (`#photo-preview`). `photo_url` input is `type="text"` (never `type="url"` — relative `/photos/...` paths fail URL validation). EditTag handler stores the file to MinIO when present, else uses the text URL. Do NOT use `-F "phone=%2B..."` in curl tests — curl `-F` does NOT decode `%XX`; it stores the literal `%2B`. Tag 6 data: phone +61423274487, address "9 Toora St Ivanhoe 3079", photo /photos/tags/32.jpg.
+- **Admin photo**: TagResource photo_url = TextInput (+ ImageColumn). The edit page header/inline "Upload photo" action modal FileUpload stores to MinIO (`/photos/{key}`) — NO `->image()` (rejects HEIC/phone formats → "failed to upload"). **Never use Filament FileUpload bound to a string column directly** (getUploadedFiles foreach over string = 500). Relative `Filament\...` namespaces in resource files break the whole panel (leading `\` required).
+- **Admin upload PHP limits**: raised via compose `command: php -d upload_max_filesize=12M -d post_max_size=14M artisan serve ...` (check `docker inspect` Cmd, not `docker exec php -r`).
+- **Logins**: admin@where-woof.com / AdminPass123! · owner@where-woof.com / OwnerPass123! · seed-admin writes `$2y$` bcrypt (Go prefix rewrite) so Laravel login works.
+- **Deploy**: explicit `rsync --checksum <file>` per file (dir rsync flaky due to clock skew); restart `systemctl --user restart where-woof` + `docker compose restart` in admin dir. Option (b): no lsyncd.
+- Test suites wipe the live DB (users/tags) — re-seed via `make db-up` (admin auto-seeded) + `make seed` + `make seed-registry`.