optimize README for audience

Author: Thomas Stromberg

README.md

@@ -6,94 +6,40 @@
 
 Email notifications for ADVRider threads. Built for Cloud Run, written in Go.
 
-ADVRider's built-in notifications only email you once after your last visit to that thread. This keeps the party going by emailing every new post until you unsubscribe.
+ADVRider's built-in notifications only email you once after your last visit. This keeps the conversation going by emailing every new post until you unsubscribe.
 
-## What it does
+## How it works
 
-Subscribe to ADVRider forum threads and get emails when new posts appear. That's it.
+Subscribe to any ADVRider thread and get emails when new posts appear.
 
-- Adaptive polling (5min to 4hr based on thread activity)
-- Multiple threads per email address
-- Handles login-required forums gracefully (reports 403, doesn't crash)
-- Exponential backoff with retry on transient failures
-- Local dev mode with mocked email
+**Respectful polling:** Adaptive intervals from 5 minutes (active threads) to 4 hours (quiet threads) using exponential backoff. Each thread is scraped once per cycle regardless of subscriber count, minimizing server load.
 
-## Running it
+**User limits:** Maximum 20 threads per email address. Notifications batch up to 10 posts to prevent spam.
 
-**Local (filesystem + mock email):**
-```bash
-go run .
-```
+**Security:** Rate limited to 5 requests/second per IP. Token-based subscription management. Thread verification before subscription. Email content sanitized to prevent XSS and phishing.
 
-Visit http://localhost:8080 and subscribe to a thread.
+**Email quality:** Dark mode support, WCAG AA compliant, clickable post anchors linking directly to specific posts.
+
+## Running locally
 
-**Cloud Run (GCS + Brevo):**
 ```bash
-export STORAGE_BUCKET=your-bucket-name
-export BASE_URL=https://your-service.run.app
-export BREVO_API_KEY=your-api-key
-ko apply -f service.yaml
+go run .
 ```
 
-Requires a service account with Cloud Storage access and a Brevo API key.
+Visit http://localhost:8080 and subscribe to a thread.
 
 ## Architecture
 
 ```
-/                    Homepage (subscribe form)
-/subscribe           POST: Create subscription (verifies thread exists first)
+/                    Subscribe form
+/subscribe           Create subscription (verifies thread exists)
 /manage?token=...    View/delete subscriptions
-/pollz               POST: Trigger immediate poll (no auth, rate limited by IP)
-```
-
-Storage is either local filesystem (`./data`) or GCS (`STORAGE_BUCKET`).
-
-Email via Brevo API. Auto-detects mock mode when `BREVO_API_KEY` is not set.
-
-Each thread is scraped once per poll cycle regardless of subscriber count. Polling interval calculated per-thread using exponential backoff: `5min × 2^(hours_since_post / 3)`, capped at 4 hours.
-
-## Security
-
-- Rate limiting: 5 subscriptions/hour per IP
-- Token-based subscription management (64-char random, constant-time comparison)
-- Thread limit: 20 per user (prevents resource exhaustion)
-- Email limit: 10 posts per notification (prevents abuse)
-- CSP, X-Frame-Options, X-Content-Type-Options headers
-- Thread verification before subscription (validates URL is actually an ADVRider thread)
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `STORAGE_BUCKET` | Cloud only | GCS bucket for subscription data |
-| `BASE_URL` | Cloud only | Public URL (for manage links in emails) |
-| `BREVO_API_KEY` | Cloud only | Brevo API key for sending emails |
-| `SALT` | Required | Secret salt for token generation (set in GSM or env) |
-| `PORT` | Optional | HTTP port (default: 8080) |
-| `LOCAL_STORAGE` | Optional | Local storage path (default: ./data) |
-| `MAIL_FROM` | Optional | From email address (defaults to postmaster@domain) |
-| `MAIL_NAME` | Optional | From name (default: ADVRider Notifier) |
-
-## Development
-
-```bash
-make build      # Build binary
-make test       # Run tests
-make lint       # golangci-lint
-make deploy     # Deploy to Cloud Run via ko
+/pollz               Trigger poll (rate limited)
 ```
 
-Tests use real ADVRider HTML parsing (no mocks for scraper). Exponential backoff algorithm is tested for correctness across all activity levels.
-
-## Email Templates
-
-Dark mode support via `prefers-color-scheme`. WCAG AA compliant. Post numbers are clickable anchors to specific posts on specific pages.
-
-Footer links: "View thread" (goes to last page + last post anchor) and "Manage" (token-authenticated subscription management).
-
-## Why Go?
+Storage: Local filesystem (`./data`) or GCS. Email via Brevo API (auto-mocks when `BREVO_API_KEY` not set).
 
-Fast cold starts on Cloud Run, trivial deploys with ko, stdlib has everything we need. No npm, no containers, no Dockerfile.
+Polling interval: `5min × 2^(hours_since_post / 3)`, capped at 4 hours.
 
 ## License