usability enhancements

openspec/changes/p12-umami-events-and-more/design.md

@@ -0,0 +1,57 @@
+## Context
+
+Current Umami event payloads for hero/feed CTA clicks and summary modal lifecycle events are identifier-heavy (`article_id`) and not directly human-readable in dashboards. Analysts must resolve IDs back to content to understand behavior patterns, which slows ad-hoc exploration and increases reporting friction.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `article_title` to existing CTA and summary modal analytics payloads.
+- Preserve existing event names and current fields for backward compatibility.
+- Keep changes scoped to frontend event payload construction.
+
+**Non-Goals:**
+- Renaming event names or changing event timing semantics.
+- Introducing new analytics providers or backend event pipelines.
+- Reworking existing dashboard taxonomy outside payload enrichment.
+
+## Decisions
+
+### Decision 1: Additive payload enrichment only
+**Choice:** Add `article_title` as an extra property while retaining `article_id` and existing metadata.
+
+**Rationale:**
+- Backward compatible for existing analytics queries.
+- Immediate analyst readability improvement without migration burden.
+
+### Decision 2: Use headline string from the in-memory item model
+**Choice:** Populate `article_title` from current article object (`item.headline` / `modalItem.headline`).
+
+**Rationale:**
+- No extra network calls or state plumbing.
+- Data already present where events are emitted.
+
+### Decision 3: Preserve event contracts and dispatch points
+**Choice:** Keep event names unchanged (`hero-cta-click`, `summary-modal-open`, `summary-modal-close`).
+
+**Rationale:**
+- Avoids dashboard/query breakage.
+- Keeps this change low risk and auditable.
+
+## Risks / Trade-offs
+
+- **[Risk] Long titles inflate payload size** -> Mitigation: send raw headline as-is; acceptable for low-volume client events.
+- **[Risk] Missing title on edge cases** -> Mitigation: include `article_id` as canonical fallback identifier.
+- **[Trade-off] Same event schema differs across historical windows** -> Mitigation: additive field keeps historical queries valid while enabling richer future segmentation.
+
+## Migration Plan
+
+1. Update event emitters in `frontend/index.html` to include `article_title`.
+2. Verify emitted payloads in browser devtools/Umami debug path.
+3. Update analytics-tagging spec deltas and task checklist.
+
+Rollback:
+- Remove `article_title` field additions; existing events remain unchanged.
+
+## Open Questions
+
+- Do analysts also want `article_permalink` included now, or defer to future UX/permalink change?

openspec/changes/p12-umami-events-and-more/specs/hero-display/spec.md

@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: News attribution display
+The system SHALL clearly attribute all news content and images to their sources.
+
+#### Scenario: Source attribution
+- **WHEN** displaying any news item
+- **THEN** the system SHALL show the original source name and link
+- **AND** display image credit if available
+
+#### Scenario: Perplexity attribution
+- **WHEN** displaying aggregated content
+- **THEN** the system SHALL include "Powered by Perplexity" in the footer
+
+#### Scenario: Analytics tracking
+- **WHEN** Umami analytics is configured via `UMAMI_SCRIPT_URL` and `UMAMI_WEBSITE_ID`
+- **THEN** the system SHALL inject Umami tracking script into page head
+- **AND** track page view events on initial load
+- **AND** track scroll depth events (25%, 50%, 75%, 100%)
+- **AND** track CTA click events (news item clicks, source link clicks)
+- **AND** CTA click payload includes both `article_id` and `article_title` when article context is available

openspec/changes/p12-umami-events-and-more/specs/summary-analytics-tagging/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Modal interactions are tagged for analytics
+The system SHALL emit Umami analytics events for summary modal open and close actions.
+
+#### Scenario: Modal open event tagging
+- **WHEN** a user opens the summary modal
+- **THEN** the system emits a modal-open Umami event
+- **AND** event payload includes article context identifier
+- **AND** event payload includes `article_title` when available
+
+#### Scenario: Modal close event tagging
+- **WHEN** a user closes the summary modal
+- **THEN** the system emits a modal-close Umami event
+- **AND** event payload includes article context identifier when available
+- **AND** event payload includes `article_title` when available
+
+### Requirement: Source link-out interactions are tagged for analytics
+The system SHALL emit Umami analytics events for source/citation link-outs from summary modal.
+
+#### Scenario: Source link-out event tagging
+- **WHEN** a user clicks source/citation link in summary modal
+- **THEN** the system emits a link-out Umami event before or at navigation trigger
+- **AND** event includes source URL or source identifier metadata

openspec/changes/p12-umami-events-and-more/tasks.md

@@ -0,0 +1,15 @@
+## 1. Event Payload Enrichment
+
+- [x] 1.1 Update hero/feed CTA tracking payloads in `frontend/index.html` to include `article_title` alongside `article_id`.
+- [x] 1.2 Update summary modal open tracking payload to include `article_title`.
+- [x] 1.3 Update summary modal close tracking payload to include `article_title` when available.
+
+## 2. Compatibility and Safety
+
+- [x] 2.1 Preserve existing event names (`hero-cta-click`, `summary-modal-open`, `summary-modal-close`) and existing fields.
+- [x] 2.2 Ensure payload enrichment is additive and does not break tracking when title is missing.
+
+## 3. Validation
+
+- [x] 3.1 Verify events in browser devtools/Umami network payload include `article_title`.
+- [x] 3.2 Verify existing dashboard queries based on `article_id` remain valid.