where_woof/openspec/changes/scan-flow/proposal.md

Why

Phase 1 built the foundation (auth, tag setup, public page), but the core product moment is missing: a finder scans a lost item's tag and the owner is alerted so the item can be returned. Phase 2 delivers the scan flow — geolocation on scan, SMS alert to the owner via SMSGlobal, a finder-contact channel, and the branding polish ("Where Woof", werewolf wordplay).

What Changes

• Scan recording: POST /t/{tag_code}/scan records every scan (with or without location) into the existing scans table.
• Geolocation flow (vanilla JS on the public tag page): prompt for location on load (HTTPS), send coordinates with the scan, re-check location button, button hidden once shared.
• SMS alerts to owner (SMSGlobal): on scan of an sms_enabled tag, send the owner an SMS with item type + name, time, maps link, and tag page link. No location shared → alert still sent (first time) with "no location" wording.
• Location-aware throttle: within a 10-minute window per tag, only re-send if the new location is >250 m from the last alerted location. Same spot → record the scan but do not re-alert.
• sms_enabled per tag: new column (default true); owners can switch a tag to purely informational (no SMS at all) from the edit form.
• Finder contact: finder can leave their mobile → stored in scans.scanner_phone → owner is SMS'd with the finder's number.
• sms: link on the tag page (prefilled message asking the finder for their number).
• Branding: "WhereWoof" → "Where Woof", page title "Where Woof !" (play on werewolf).
• Provider detail (confirmed with owner): SMSGlobal, pooled/shared sender number (origin blank; upgrade to registered sender later), real test number +61423274487.

Capabilities

New Capabilities

• scan-flow: geolocation prompt, scan recording, re-check button, hide-after-share, sms: link.
• sms-alerting: SMSGlobal integration behind a swappable Sender interface, message template, location-aware throttle (250 m / 10 min), sms_enabled respected, alert_sent tracking.
• finder-contact: finder phone input → stored → owner notified.

Modified Capabilities

• tag-management: ADDED — per-tag sms_enabled toggle on the edit form (default on).
• database: ADDED — tags.sms_enabled column (idempotent ALTER TABLE ... ADD COLUMN IF NOT EXISTS, default TRUE).

Impact

• New Go: internal/sms (Sender interface, smsglobal HTTP client, log fake, haversine distance), internal/handlers/scan.go.
• Modified Go: internal/handlers/tags.go (sms_enabled in edit), internal/db/queries.sql (InsertScan, GetLastScan, UpdateTagDetails + sms_enabled), main.go (2 routes + sender wiring).
• Modified templates: tag-public.html (geolocation JS, sms: link, contact form), tag-edit.html (sms_enabled checkbox), all templates + README (branding).
• Schema: db/schema.sql gains idempotent sms_enabled column.
• Secrets (never in repo): SMS_API_KEY, SMS_API_SECRET (SMSGlobal MXT), optional SMS_FROM (blank = pooled number). No key set → app uses the log sender (safe dev default).
• No changes to auth, deployment, or billing phases.