From e95eb358b324dc39f9009df63e642f7e7ddaa57c Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Wed, 5 Aug 2026 21:24:21 +1000
Subject: [PATCH] README: add dev testing guide (owner form flow, finder URL,
 throttle, SMS log mode)

---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 48454cb..3c059c5 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,56 @@ Find your woof. A return-item tag platform (PetHub/ReturnMe style) — *"Where W
 GOAT front-end (Phase 1) built and verified — see `where_woof.md` for the full plan and roadmap.
 
 - Plan: [where_woof.md](where_woof.md), [awesome-design.md](awesome-design.md)
-- Specs & changes: `openspec/` (frontend-foundation ✅, scan-flow 🚧)
+- Specs & changes: `openspec/` (frontend-foundation ✅, scan-flow ✅)
 - Front-end: `frontend/` (Go + HTMX + Alpine + Tailwind + Postgres)
 - Mockups: `mockups/`
+
+## Testing the site (dev)
+
+Everything runs from this repo on `.27`. SMS is in **log mode** by default — no real SMS is sent until SMSGlobal credentials are set; instead you'll see `SMS to …` lines in the server log.
+
+### 1. Start it
+
+```bash
+make db-up     # apply schema (idempotent — safe to re-run)
+make seed      # insert 25 test tags: TEST000001 .. TEST000025
+make run       # http://localhost:3020
+```
+
+### 2. Create an account (fill in the form)
+
+Click **Register** (top right) → name, email, password (≥ 8 characters). You're logged in automatically and land on **My Tags**.
+
+### 3. Claim a tag (owner side — the form)
+
+- On **My Tags**, enter a code like `TEST000001` → **Add tag**. It appears as *Unset*.
+- Click **Edit** and fill the form: item type (Dog), description (e.g. Shadow), photo URL, **phone number (e.g. +61432374487)**, address, notes, and the *Send me SMS alerts* checkbox. Save → status becomes *Active*.
+
+### 4. The finder experience (the URL that works)
+
+Open **http://localhost:3020/t/TEST000001** in a **private/incognito window** (that's the finder — no login):
+
+- It asks for your location → **Allow**. Watch the server log — an `SMS to` line appears with the map link.
+- Deny instead → the page still works, and a **“Re-check my location”** button appears; click it and allow to send the location after all.
+- **Send an SMS** link → opens your phone's SMS app with the owner's number prefilled.
+- **Leave your number** → submit a mobile → the owner gets an SMS with the finder's number (also stored on the scan).
+
+### 5. Throttle behaviour (repeat scans)
+
+- Scan the same tag at the same location twice within 10 minutes → only **one** SMS.
+- Scan again from > 250 m away within the window → a **second** SMS (it moved).
+- Wait 10+ minutes → the next scan alerts again.
+
+### 6. Info-only tag
+
+Uncheck *Send me SMS alerts* on the edit form → scans are recorded but no SMS is sent.
+
+### 7. Watching the SMS
+
+In log mode: `tail -f /tmp/ww-server.log` and look for `SMS to`. With real SMSGlobal credentials (`SMS_API_KEY` / `SMS_API_SECRET` env vars), the owner's phone receives the text.
+
+### Notes
+
+- **Geolocation requires HTTPS** except on `localhost` — testing on a phone over the LAN needs the Caddy/TLS deployment (Phase 7) or `localhost`.
+- Reset the database any time: `make db-up` re-applies the schema (idempotent); drop the `wherewoof-db` container volume for a truly fresh start.
+- Automated suites live in `/tmp/verify.sh` (Phase 1, 22 checks) and `/tmp/verify2.sh` (Phase 2, 19 checks) — they reset the DB themselves.