Document the tracking surface

README.md

@@ -80,3 +80,31 @@ key. Deleting it revokes the key and breaks both functions.
 `https://foundersbreak.onetouch.studio/#rsvp`. Deliberately dark-on-white:
 inverted QR codes are unreliable on older scanners and these go on flyers.
 Regenerate with the `qrcode` npm package if the URL ever changes.
+
+## Tracking
+
+The Corben tracker is injected into every EJS site automatically, so pageviews
+(with UTM, referrer, device, browser), clicks on any `a`/`button`/`[data-track]`,
+`form_start`, `form_submit`, scroll depth and engagement time all land with no
+work from us. Key elements carry a `data-track` label so the click rows are
+readable: `rsvp-nav`, `rsvp-hero`, `rsvp-submit`, `add-to-calendar`, `venue-map`,
+`details-map`, `venue-instagram`, `hero-what-to-expect`.
+
+`public/js/main.js` adds the three steps the tracker cannot see on its own, via
+the same public `/analytics/events` endpoint:
+
+| Event | Means |
+|---|---|
+| `rsvp_reached` | scrolled the RSVP block into view |
+| `rsvp_completed` | submission stored, `event_data.via` is `form` or `reminder-email` |
+| `rsvp_failed` | submission rejected, with the reason |
+
+So "reached but did not finish" is `rsvp_reached` minus `rsvp_completed`, and
+"started typing then left" is `form_start` minus `form_submit`.
+
+Emails carry a 1x1 open pixel at `GET /analytics/open.gif?s=<site>&k=<kind>&e=<email>&d=<date>`,
+landing in `site_events` as `email_open` with kind `confirm-first`,
+`confirm-returning` or `reminder`. Apple Mail Privacy Protection and Gmail's
+image proxy prefetch images, so treat opens as a ceiling rather than a headcount.
+
+Read any of it with `get_site_analytics`, `get_site_events` or `get_site_click_map`.