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.

openspec/changes/p13-usability-enhancements/design.md

@@ -0,0 +1,84 @@
+## Context
+
+The current site works functionally but has usability gaps: dynamic homepage title behavior can confuse context, discovery/sharing of individual articles is weak, error pages are plain, and footer affordances are limited. Readability needs incremental tuning, especially for Tamil and Malayalam text rendering. These issues span frontend state management, metadata behavior, footer UX, and static asset/routing support.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Stabilize homepage title for clarity and SEO consistency.
+- Add back-to-top affordance and per-article permalink deep-linking that opens the correct modal.
+- Add minimal icon-based sharing (X/WhatsApp/LinkedIn) for modal/permalink flows.
+- Improve legibility via typography/color refinements, with explicit Tamil/Malayalam attention.
+- Introduce branded AI favicon.
+- Add expressive 404/500 pages with prominent code display and safe playful AI-style copy.
+- Add env-driven GitHub/email footer links with randomized safe feedback tooltip microcopy.
+
+**Non-Goals:**
+- Rewriting router architecture or adding server-side rendering.
+- Adding complex social auth or third-party share SDKs.
+- Replacing existing analytics instrumentation.
+- Building full i18n content moderation pipeline for tooltip text.
+
+## Decisions
+
+### Decision 1: Hash/query driven deep-link modal state
+**Choice:** Use permalink token (`?article=<id>` or hash equivalent) and resolve on load to open matching modal.
+
+**Rationale:**
+- Works with existing SPA flow and avoids backend route explosion.
+- Easy to share/copy and easy to close by clearing URL state.
+
+### Decision 2: Keep sharing implementation lightweight
+**Choice:** Construct provider share URLs client-side and use icon buttons without extra SDK dependencies.
+
+**Rationale:**
+- Minimal bundle impact.
+- Predictable behavior with native share endpoints.
+
+### Decision 3: Readability tuning via CSS tokens and language-aware classes
+**Choice:** Adjust text size/line-height/color contrast in existing theme token system; apply optional class hooks for Tamil/Malayalam content rendering.
+
+**Rationale:**
+- Incremental and low-risk.
+- Preserves current theme architecture.
+
+### Decision 4: Error pages with controlled safe message pool
+**Choice:** Use curated safe message templates (50+) and deterministic randomization per request/session.
+
+**Rationale:**
+- “Oh no!” playful tone without unsafe generation risks.
+- No runtime LLM dependency required for error path.
+
+### Decision 5: Footer extensibility via env-backed config
+**Choice:** Expose `GITHUB_REPO_URL` and `CONTACT_EMAIL` through existing frontend config bootstrap and render conditional links.
+
+**Rationale:**
+- Keeps deployment-specific metadata configurable.
+- Avoids hardcoded personal links.
+
+## Risks / Trade-offs
+
+- **[Risk] Deep-link to missing article id** -> Mitigation: fail gracefully (no modal open) and keep list view stable.
+- **[Risk] Tooltip microcopy quality drift** -> Mitigation: curate fixed safe message corpus and review before release.
+- **[Risk] Share URL encoding mistakes** -> Mitigation: centralized URL builder + encode all user-facing strings.
+- **[Trade-off] Stable homepage title reduces article-specific title SEO** -> Mitigation: keep OG/Twitter/article-level metadata contextual in card/modal/share surfaces.
+
+## Migration Plan
+
+1. Add permalink generation, URL parsing, and modal open-on-load logic.
+2. Add share icons/buttons and footer microinteraction links.
+3. Apply readability and color token tweaks; verify Tamil/Malayalam rendering.
+4. Add error page handlers/templates and safe message pool.
+5. Add favicon asset and head reference.
+6. Add env-config plumbing for GitHub/email footer links.
+
+Rollback:
+- Revert permalink and share UI additions.
+- Revert title and readability token changes.
+- Restore prior generic error page behavior.
+
+## Open Questions
+
+- Should permalink use numeric article id only, or slug+id hybrid for readability?
+- Should contact tooltip randomization rotate per hover event or per page load?
+- Should 404/500 messages be localized immediately or staged in English first?

openspec/changes/p13-usability-enhancements/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+Several small UX and content-discovery issues are adding friction across navigation, sharing, readability, and trust signals. Addressing them together delivers a noticeable quality jump with low implementation risk.
+
+## What Changes
+
+- Set a stable homepage title (for example, `ClawFort AI News`) instead of changing it to the latest article headline.
+- Add a footer `Back to Top` action for quick navigation.
+- Add per-article permalinks and support deep-link behavior that opens the correct article modal on page load.
+- Add minimal icon-only share actions for permalink sharing (`X`, `WhatsApp`, `LinkedIn`) in modal/footer share area.
+- Improve readability with small typography/color updates, with extra attention to Tamil and Malayalam legibility.
+- Add custom 404/500 pages that prominently show the error code and include safe, playful AI-generated “Oh no!” style messages.
+- Add footer links driven by environment configuration for GitHub repo and contact email; include enhanced hover/near-cursor feedback messages from a randomized safe message pool.
+- Add an AI-themed favicon asset and wire it into the site.
+
+## Capabilities
+
+### New Capabilities
+- `article-permalinks-and-deep-link-modal`: Defines canonical per-article permalink structure and modal auto-open behavior from URL state.
+- `share-and-contact-microinteractions`: Defines social share actions, configurable GitHub/email links, and randomized safe feedback microcopy for contact affordance.
+- `error-pages-with-playful-ai-messaging`: Defines 404/500 UX with prominent status codes and policy-safe AI-style messaging.
+- `site-branding-favicon`: Defines favicon asset requirements and integration.
+
+### Modified Capabilities
+- `seo-meta-and-social-tags`: Update homepage title behavior to remain stable and brand-oriented while preserving metadata quality.
+- `summary-modal-experience`: Extend modal contract to support permalink-driven open state and share entry points.
+- `responsive-device-agnostic-layout`: Apply small typography/color refinements for readability across devices.
+- `language-aware-content-delivery`: Improve Tamil/Malayalam presentation quality in the existing delivery surfaces.
+- `footer-policy-links`: Extend footer navigation with back-to-top, GitHub, and contact affordances.
+
+## Impact
+
+- **Frontend UI:** `frontend/index.html` (title policy, footer controls, permalink/deep-link modal behavior, share icons, readability tweaks, favicon link).
+- **Backend/Config:** environment variables for GitHub URL and contact email exposure; possible API/config exposure if frontend config bootstrapping is needed.
+- **Routing/Pages:** new error page templates/handlers for 404 and 500 responses.
+- **Content/UX:** curated safe message pool for contact tooltip/hover microcopy and error-page “Oh no!” messaging.

openspec/changes/p13-usability-enhancements/specs/article-permalinks-and-deep-link-modal/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Each news item exposes a permalink
+The system SHALL expose a stable, shareable permalink for each rendered news item.
+
+#### Scenario: Per-item permalink rendering
+- **WHEN** a news item is rendered in hero or feed context
+- **THEN** the UI provides a permalink target tied to that article context
+
+#### Scenario: Permalink copy/share usability
+- **WHEN** a user uses share/copy affordances for an item
+- **THEN** the resulting URL contains sufficient information to resolve that article on load
+
+### Requirement: Deep-link loads article modal in open state
+The system SHALL open the matching article modal when the page is loaded with a valid article permalink.
+
+#### Scenario: Valid permalink opens modal
+- **WHEN** a user lands on homepage with a permalink for an existing article
+- **THEN** the corresponding article modal is opened automatically
+- **AND** modal content matches the permalink target
+
+#### Scenario: Invalid permalink fails safely
+- **WHEN** a permalink references a missing or invalid article identifier
+- **THEN** the page remains usable without hard failure
+- **AND** modal is not opened with incorrect content

openspec/changes/p13-usability-enhancements/specs/error-pages-with-playful-ai-messaging/spec.md

@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: Error pages prominently display status code
+The system SHALL show prominent HTTP status code display on 404 and 500 pages.
+
+#### Scenario: 404 rendering
+- **WHEN** user visits a non-existent route
+- **THEN** the page prominently displays `404`
+
+#### Scenario: 500 rendering
+- **WHEN** an internal server error page is rendered
+- **THEN** the page prominently displays `500`
+
+### Requirement: Error pages include safe playful AI-style messaging
+The system SHALL render an "Oh no!" style playful message that is safe and policy-compliant.
+
+#### Scenario: Safe message selection
+- **WHEN** an error page is displayed
+- **THEN** a playful message is selected from a curated safe message set
+- **AND** message excludes profanity and discriminatory/abusive content

openspec/changes/p13-usability-enhancements/specs/footer-policy-links/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Footer exposes policy navigation links
+The system SHALL display footer links for Terms of Use and Attribution on the landing page.
+
+#### Scenario: Footer links visible on landing page
+- **WHEN** a user loads the main page
+- **THEN** the footer includes links labeled "Terms of Use" and "Attribution"
+- **AND** links are visually distinguishable and keyboard focusable
+
+#### Scenario: Footer links navigate correctly
+- **WHEN** a user activates either policy link
+- **THEN** the browser navigates to the corresponding policy page
+- **AND** navigation succeeds without API dependency
+
+#### Scenario: Footer includes back-to-top action
+- **WHEN** a user reaches lower sections of the page
+- **THEN** footer exposes a "Back to Top" control
+- **AND** activating it returns viewport to page top smoothly
+
+#### Scenario: Footer includes optional GitHub and email links
+- **WHEN** GitHub repository URL and/or contact email are configured
+- **THEN** footer renders corresponding links without replacing policy links
+- **AND** absent values do not break footer layout

openspec/changes/p13-usability-enhancements/specs/language-aware-content-delivery/spec.md

@@ -0,0 +1,32 @@
+## MODIFIED Requirements
+
+### Requirement: API supports language-aware content retrieval
+The system SHALL support language-aware content delivery for hero and feed reads using selected language input.
+
+#### Scenario: Language-specific latest article response
+- **WHEN** a client requests latest article data with a supported language selection
+- **THEN** the system returns headline and summary in the selected language when available
+- **AND** includes the corresponding base article metadata and media attribution
+
+#### Scenario: Language-specific paginated feed response
+- **WHEN** a client requests paginated feed data with a supported language selection
+- **THEN** the system returns each feed item's headline and summary in the selected language when available
+- **AND** preserves existing pagination behavior and ordering semantics
+
+#### Scenario: Tamil and Malayalam rendering quality support
+- **WHEN** Tamil (`ta`) or Malayalam (`ml`) content is delivered to frontend surfaces
+- **THEN** payload text preserves script fidelity and Unicode correctness
+- **AND** frontend presentation hooks can apply readability-focused typography adjustments without changing response shape
+
+### Requirement: Language fallback to English is deterministic
+The system SHALL return English source content when the requested translation is unavailable.
+
+#### Scenario: Missing translation fallback
+- **WHEN** a client requests Tamil or Malayalam content for an article lacking that translation
+- **THEN** the system returns the English headline and summary for that article
+- **AND** response shape remains consistent with language-aware responses
+
+#### Scenario: Unsupported language handling
+- **WHEN** a client requests a language outside supported values (`en`, `ta`, `ml`)
+- **THEN** the system applies the defined default language behavior for this phase
+- **AND** avoids breaking existing consumers of news endpoints

openspec/changes/p13-usability-enhancements/specs/responsive-device-agnostic-layout/spec.md

@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Core layout is device-agnostic and responsive
+The system SHALL render key surfaces (header, hero, feed, modal, footer) responsively across mobile, tablet, and desktop viewports.
+
+#### Scenario: Mobile layout behavior
+- **WHEN** a user opens the site on a mobile viewport
+- **THEN** content remains readable without horizontal overflow
+- **AND** interactive controls remain reachable and usable
+
+#### Scenario: Desktop and tablet adaptation
+- **WHEN** a user opens the site on tablet or desktop viewports
+- **THEN** layout reflows according to breakpoint design rules
+- **AND** no key content or controls are clipped
+
+#### Scenario: Readability-focused typography and contrast updates
+- **WHEN** content is rendered in core reading surfaces
+- **THEN** typography and color choices improve baseline readability
+- **AND** updates remain compatible with responsive behavior across breakpoints

openspec/changes/p13-usability-enhancements/specs/seo-meta-and-social-tags/spec.md

@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Core SEO metadata is present on public pages
+The system SHALL expose standards-compliant SEO metadata on the homepage and policy pages, including description, robots, canonical URL, and social preview metadata.
+
+#### Scenario: Homepage metadata baseline exists
+- **WHEN** a crawler or browser loads the homepage
+- **THEN** the document includes `description`, `robots`, and canonical metadata
+- **AND** Open Graph and Twitter card metadata fields are present with non-empty values
+
+#### Scenario: Policy pages include indexable metadata
+- **WHEN** a crawler loads `/terms` or `/attribution`
+- **THEN** the page includes page-specific `title` and `description` metadata
+- **AND** Open Graph and Twitter card metadata are present for link previews
+
+#### Scenario: Homepage title remains stable and brand-oriented
+- **WHEN** homepage content updates to newer articles
+- **THEN** document title remains a stable brand title (for example `ClawFort AI News`)
+- **AND** title does not switch to latest-article headline text

openspec/changes/p13-usability-enhancements/specs/share-and-contact-microinteractions/spec.md

@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Modal/footer exposes minimal icon-based share actions
+The system SHALL provide icon-only social share actions for article permalinks on supported providers.
+
+#### Scenario: Supported share providers
+- **WHEN** share controls are rendered
+- **THEN** icons for `X`, `WhatsApp`, and `LinkedIn` are displayed
+- **AND** activating an icon opens provider share flow with the article permalink
+
+### Requirement: Footer supports env-driven GitHub and contact links
+The system SHALL conditionally render GitHub and contact-email links from environment-backed configuration.
+
+#### Scenario: Config present
+- **WHEN** GitHub URL and contact email are configured
+- **THEN** footer renders both links as interactive controls
+
+#### Scenario: Config absent
+- **WHEN** either value is missing
+- **THEN** corresponding footer control is hidden without breaking layout
+
+### Requirement: Contact affordance provides randomized safe microcopy
+The contact link SHALL present randomized, policy-safe helper messages to encourage feedback.
+
+#### Scenario: Randomized helper tooltip
+- **WHEN** user hovers or nears the contact affordance
+- **THEN** a tooltip-style helper message is shown from a predefined safe message pool
+- **AND** message language avoids profanity/offensive/racist/sexist/misogynistic content

openspec/changes/p13-usability-enhancements/specs/site-branding-favicon/spec.md

@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: Site includes AI-themed favicon
+The system SHALL include an AI-themed favicon asset and reference it from public pages.
+
+#### Scenario: Favicon linked in document head
+- **WHEN** a public page is loaded
+- **THEN** a favicon link element resolves to the configured AI-themed icon asset
+
+#### Scenario: Favicon asset is cacheable and valid
+- **WHEN** browser requests favicon asset
+- **THEN** asset responds successfully with a valid icon format
+- **AND** can be cached using standard static-asset policy

openspec/changes/p13-usability-enhancements/specs/summary-modal-experience/spec.md

@@ -0,0 +1,30 @@
+## MODIFIED Requirements
+
+### Requirement: Summary is rendered in a modal dialog using standard template
+The system SHALL render article summary content in a modal dialog using the required structure.
+
+#### Scenario: Open summary modal
+- **WHEN** a user triggers summary view for an article
+- **THEN** a modal dialog opens and displays content in this order: relevant image, TL;DR bullets, summary body, source and citation, and "Powered by Perplexity"
+- **AND** modal content corresponds to the selected article
+
+#### Scenario: Close summary modal
+- **WHEN** a user closes the modal via close control or backdrop interaction
+- **THEN** the modal is dismissed cleanly
+- **AND** user returns to previous feed context without page navigation
+
+#### Scenario: Permalink-driven modal open
+- **WHEN** page is loaded with a valid article permalink state
+- **THEN** the modal opens for the linked article without requiring manual click
+
+### Requirement: Modal content preserves source link-out behavior
+The system SHALL provide source link-outs from the summary modal.
+
+#### Scenario: Source link-out from modal
+- **WHEN** a user clicks source/citation link in the modal
+- **THEN** the original source opens in a new tab/window
+- **AND** modal behavior remains stable for continued browsing
+
+#### Scenario: Modal exposes share entry points
+- **WHEN** a summary modal is open for an article
+- **THEN** share controls for the article permalink are available from modal/footer share area

openspec/changes/p13-usability-enhancements/tasks.md

@@ -0,0 +1,41 @@
+## 1. Homepage Metadata and Navigation
+
+- [x] 1.1 Set homepage title to stable brand title (e.g., `ClawFort AI News`) and prevent latest-article overrides.
+- [x] 1.2 Add footer `Back to Top` control with smooth scroll behavior.
+
+## 2. Permalinks and Deep-Link Modal
+
+- [x] 2.1 Add per-article permalink generation for hero and feed items.
+- [x] 2.2 Add URL parsing on load to detect permalink article target.
+- [x] 2.3 Open matching article modal automatically when permalink target is valid.
+- [x] 2.4 Handle invalid/missing permalink targets safely without UI breakage.
+
+## 3. Sharing and Footer Contact UX
+
+- [x] 3.1 Add icon-only share actions for `X`, `WhatsApp`, and `LinkedIn` using article permalinks.
+- [x] 3.2 Add env-driven footer GitHub link (`GITHUB_REPO_URL`) and contact email link (`CONTACT_EMAIL`).
+- [x] 3.3 Implement randomized safe tooltip microcopy pool (~50 messages) for contact affordance.
+
+## 4. Readability Improvements
+
+- [x] 4.1 Apply minor typography and color-contrast refinements across reading surfaces.
+- [x] 4.2 Add targeted Tamil/Malayalam readability tuning (font size/line-height/weight adjustments as needed).
+- [x] 4.3 Verify updates preserve responsive behavior across mobile/tablet/desktop.
+
+## 5. Error Experience
+
+- [x] 5.1 Implement custom 404 page with prominent status code and safe playful "Oh no!" message.
+- [x] 5.2 Implement custom 500 page with prominent status code and safe playful "Oh no!" message.
+- [x] 5.3 Add curated safe message set and deterministic/randomized selection strategy.
+
+## 6. Branding Asset
+
+- [x] 6.1 Add AI-themed favicon asset to static files with proper licensing/attribution notes if required.
+- [x] 6.2 Wire favicon reference in public page heads.
+
+## 7. Validation
+
+- [x] 7.1 Verify permalink deep-link opens correct modal and share links include correct URL.
+- [x] 7.2 Verify footer controls (policy links, back-to-top, GitHub, email) across breakpoints.
+- [x] 7.3 Verify Tamil/Malayalam readability changes in actual rendered content.
+- [x] 7.4 Verify 404/500 pages render status code + safe playful message.

openspec/changes/p14-bugs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-13

openspec/changes/p14-bugs/proposal.md

@@ -0,0 +1,34 @@
+## Why
+
+Several regressions and UX defects slipped in after recent enhancements, affecting modal behavior, sharing visibility, footer/header usability, and image relevance. Fixing these together will restore trust, readability, and navigation quality without introducing new product scope.
+
+## What Changes
+
+- Fix permalink-to-hero modal behavior so image rendering and keyboard close (`Escape`) work consistently.
+- Restore footer contact email visibility and ensure env-driven contact link rendering is reliable.
+- Fix light-theme contrast for social share icons and add a copy-to-clipboard action alongside X, WhatsApp, and LinkedIn.
+- Replace inline footer "Back to Top" text button with a floating island-style control.
+- Make footer persistently sticky and compact while preserving reading comfort.
+- Make header persistently sticky with subtle shrink, elevation, and glass effect on scroll.
+- Tighten article-image relevance to avoid clearly unrelated images for finance/market stories.
+- Remove unnecessary per-card "Link" affordance from feed cards.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `article-permalinks-and-deep-link-modal`: Correct deep-link modal open-state parity for hero/feed targets and keyboard close behavior.
+- `share-and-contact-microinteractions`: Fix share-icon visibility in light mode, add copy-link action, and restore contact-email presence.
+- `footer-policy-links`: Update footer interaction model for sticky compact layout and floating back-to-top control.
+- `responsive-device-agnostic-layout`: Apply sticky header/footer behavior and ensure readability is not degraded.
+- `news-image-relevance-and-fallbacks`: Improve relevance guardrails to reduce obviously mismatched fallback/provider image outcomes.
+- `hero-display`: Remove redundant card-level permalink text affordance where it harms clarity.
+
+## Impact
+
+- **Frontend UI:** `frontend/index.html` modal behaviors, keyboard handling, share controls, footer/header interactions, and card affordances.
+- **Backend config/data:** contact link exposure verification through `/config` payload and env handling.
+- **Image pipeline:** backend relevance and fallback heuristics in image selection paths.
+- **UX quality:** stronger consistency across themes and navigation paths, especially for permalink and sharing flows.

openspec/changes/p15-complete-test-suite/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-13

openspec/changes/p15-complete-test-suite/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+The platform needs stronger quality gates to ensure stable, predictable behavior across releases. A complete testing and review program will reduce regressions, improve confidence in deployments, and surface performance, accessibility, and security risks earlier.
+
+## What Changes
+
+- Introduce a unified automated test suite strategy covering unit, integration, and end-to-end paths.
+- Add end-to-end test coverage for core UI flows, API contracts, and database state transitions.
+- Add WCAG-focused accessibility checks and include them in quality gates.
+- Add page speed and runtime performance checks with repeatable thresholds.
+- Add baseline security testing (dependency, config, and common web vulnerability checks).
+- Add user-experience validation scenarios for key journeys and failure states.
+- Define comprehensive coverage expectations for critical features and edge cases.
+- Add a structured code-review/remediation/optimization pass to resolve quality debt.
+- Add performance monitoring and alerting requirements for production health visibility.
+
+## Capabilities
+
+### New Capabilities
+- `platform-quality-gates`: Defines required CI quality gates and pass/fail criteria for release readiness.
+- `end-to-end-system-testing`: Defines end-to-end testing coverage across UI, API, and database workflows.
+- `security-and-performance-test-harness`: Defines security checks and page/runtime performance testing strategy.
+- `observability-monitoring-and-alerting`: Defines performance monitoring signals, dashboards, and alerting thresholds.
+- `code-review-remediation-workflow`: Defines structured remediation and optimization workflow after comprehensive review.
+
+### Modified Capabilities
+- `wcag-2-2-aa-accessibility`: Expand verification requirements to include automated accessibility testing in release gates.
+- `delivery-and-rendering-performance`: Add enforceable page speed benchmarks and regression thresholds.
+- `site-admin-safety-and-ergonomics`: Add operational verification requirements tied to maintenance command behaviors.
+
+## Impact
+
+- **Testing/Tooling:** New test suites, fixtures, and CI workflows for UI/API/DB/accessibility/security/performance.
+- **Frontend/Backend:** Potential bug fixes and optimizations discovered during comprehensive test and review passes.
+- **Operations:** Monitoring/alerting setup and documentation for performance and reliability signals.
+- **Release Process:** Stronger quality gates before archive/release actions.