Initial commit - but way too late.

openspec/specs/analytics-umami/spec.md

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: Umami pageview tracking
+When Umami is enabled by configuration, the site MUST load Umami tracking on all indexable pages and MUST record pageviews.
+
+When Umami is disabled or not configured, the site MUST still function and MUST NOT error in the browser due to missing analytics.
+
+#### Scenario: Umami enabled
+- **WHEN** Umami is enabled by configuration
+- **THEN** the site includes the Umami script on `/`, `/videos`, `/podcast`, and `/about`
+
+#### Scenario: Umami disabled
+- **WHEN** Umami is not configured
+- **THEN** the site renders normally and no analytics script is required
+
+### Requirement: Custom event tracking
+When Umami is enabled, the site MUST support custom event emission for:
+- `cta_click`
+- `outbound_click`
+- a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
+
+Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
+
+All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum `target_id` and `placement`.
+
+#### Scenario: Emit outbound click event
+- **WHEN** a user clicks a non-CTA outbound link from the homepage
+- **THEN** the system emits an `outbound_click` event with a property identifying the destination domain
+
+#### Scenario: Emit general click event for any clickable
+- **WHEN** a user clicks an instrumented navigation link
+- **THEN** the system emits a click interaction event with `target_id` and `placement`
+
+#### Scenario: Uninstrumented clicks do not break the page
+- **WHEN** a user clicks an element with no tracking metadata
+- **THEN** the system does not throw and navigation/interaction proceeds normally
+
+### Requirement: Environment configuration
+The site MUST support configuration of Umami parameters (at minimum: website ID and script URL) without requiring code changes.
+
+#### Scenario: Configure Umami via environment
+- **WHEN** Umami configuration values are provided via environment or config file
+- **THEN** the site uses those values to initialize analytics without modifying source code