# AGENTS.md — Where Woof (resume brief)

> The **source of truth is `where_woof.md`** (product plan + roadmap) and the **`openspec/` changes**. This file is a quick-resume overview for any agent or session picking the project back up.
>
> **Fuller docs: `docs/ARCHITECTURE.md` (how systems tie together + where things run), `docs/TOOLS.md` (toolchain), `docs/RESUME-HIGHLIGHTS.md` (resume-ready summary).**

## What this is

Where Woof — a **return-tag platform** (not a tracker): pre-coded QR/NFC tags on items; a finder scans → sees return details → owner gets an SMS alert (with finder location when permitted). Branding: "Where Woof !" (werewolf wordplay).

## How we work (the pipeline)

- **Master/worker**: the main pi session (cwd = repo root) orchestrates; subagents do chunks — `database` (schema/queries), `coder-pro` (Go code), `devops-pro` (infra/secrets), `code-analysis` (review). User reviews via plannotator's browser UI when it cooperates; otherwise inline approval.
- Per change: **openspec** (propose → design/specs → tasks, `openspec validate`) → **plannotator** plan (`plans/<name>.md`, submit → approve) → execute with `[DONE:n]` → run `/tmp` verify suites → `code-analysis` review → commit + push to Gitea.
- This is a **learning exercise for the user** — explain decisions, don't just execute.

## Where we are (2026-08-07 EOD)

- **Phase 1 `frontend-foundation` — DONE** (22/22)
- **Phase 2 `scan-flow` — DONE** (19/19 + real SMS via SMSGlobal HTTP API)
- **Phase 2.5 `scan-alert-hardening` — DONE** (12/12: different-finder re-alert + fingerprint 24h block)
- **Phase 3 HTMX/Alpine polish — DONE** (+ tuxedo notes: photo upload, username/email display, favicon)
- **Phase 4 `laravel-admin` — DONE** (Docker Laravel + Filament on .27:3030, shared Postgres, verified)
- **Phase 7 `deploy-frontend` — LIVE on .13** (systemd user service :3020, Caddy blocks saved on .35)
  - ⏳ **Outstanding (user, AM)**: where-woof.com DNS/redirect — A record still at InMotion (173.231.229.92); lab domains use a redirect mechanism (NOT a plain A record — user correction, investigate how both are configured); may involve router/NAT settings
  - Admin (`admin.where-woof.com` → .13:3030) is Phase 8 — nothing runs on 3030 yet
- **Remaining**: Phase 5 billing, Phase 6 photos, Phase 8 admin deploy, Phase 9 hardening

## Key locations

| What | Where |
|---|---|
| Product plan + roadmap (source of truth) | `where_woof.md` |
| OpenSpec specs & changes | `openspec/` (`frontend-foundation` ✅, `scan-flow` ✅) |
| Plannotator plans | `plans/frontend-foundation.md`, `plans/scan-flow.md` |
| Go front-end | `frontend/` (stdlib `net/http`, `internal/{db,auth,handlers,sms}`) |
| Schema | `db/schema.sql` (canonical until Laravel owns migrations) |
| Build/run targets | `Makefile` — `db-up`, `seed`, `run`, `build`, `generate`, `psql` |
| Dev DB | `wherewoof-db` Postgres 16 container on **.13:5434** (user/db `wherewoof`; compose + `.env` in `/home/sam/Docker/Containers/wherewoof-db/` on .13) |
| Run locally | `make db-up && make seed && make run` → `http://localhost:3020` (SMS in **log mode** until creds set) |
| Live frontend | **.13:3020** systemd user service `where-woof` (`/var/www/where-woof`, env `~/.config/where-woof.env`); `where-woof.home.lab` works via .35 Caddy |
| Admin (dev) | **.27:3030** Docker Laravel (`admin/`, Filament) — `cd admin && docker compose up -d`; live deploy = Phase 8 |
| Verify suites | `/tmp/verify.sh` (Phase 1, 22), `/tmp/verify2.sh` (Phase 2, 19), `/tmp/verify3.sh` (hardening, 12) — ephemeral, they reset the DB (incl. admin user — re-seed via `php artisan wherewoof:admin`) |
| Prod target | `.13:/var/www/where-woof` — **frontend LIVE**; admin not yet deployed; Caddy on .35; `where-woof.com` DNS at InMotion (outstanding)
| Gitea | `sam/where_woof` — `ssh://git@gitea.lab.audasmedia.com.au:2222/sam/where_woof.git` |

## Tools

- `openspec` 1.3.1 (spec-driven dev), `plannotator` (plan + browser review), pi subagents (master/worker), `sqlc` 1.31.1 at `~/go/bin` (not on PATH — `make generate` handles it), `pgx` v5, `gorilla/sessions`, `bcrypt`
- **Secrets are env-only, never committed**: `DATABASE_URL`, `SESSION_SECRET`; SMS via **HTTP API** `SMS_USER`/`SMS_PASSWORD`/`SMS_FROM` (proven live 2026-08-07) with REST key/secret (`SMS_API_KEY`/`SMS_API_SECRET`) as unverified fallback
- SMS is a swappable `internal/sms.Sender` — `LogSender` (default) / `smsglobal.Client` (real)

## Gotchas worth remembering

- `.pi/` is gitignored (agent memory + extension tooling are machine-local)
- NixOS box: **no gcc** (`CGO_ENABLED=0` set via `go env -w`), `make` via `nix profile`, no `psql` (use `make psql` → docker exec on .13)
- `html/template` escapes `+` as `&#43;` in hrefs (`tel:`/`sms:` links still work in a browser)
- `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`.