## Context

`frontend/index.html` currently renders the hero CTA as an external redirect (`window.open(item.source_url)`), and modal sizing is constrained by `max-w-2xl` with `max-h-[90vh]`. TL;DR content does not expose a dedicated loading placeholder, and hero badges can lose readability over bright images. On the backend, `backend/news_service.py` already performs keyword extraction and provider fallback, but defaults remain too generic (`"news technology"`) and do not explicitly prioritize AI-topic fallback behavior.

## Goals / Non-Goals

**Goals:**
- Keep users on-site by making the hero primary CTA open the existing TL;DR modal flow.
- Ensure `LATEST` and relative timestamp remain legible over all hero images in light/dark themes.
- Increase modal usable area (width and near-full-height scrolling behavior) without breaking mobile usability.
- Add a small horizontal shimmer placeholder for TL;DR bullets while modal content initializes.
- Improve image relevance with stronger AI-focused keyword fallback and deterministic generic AI-image fallback when lookup fails.

**Non-Goals:**
- Rebuilding the full feed card architecture.
- Replacing existing provider integrations or adding new third-party image providers.
- Introducing backend sentiment ML models.
- Reworking scheduler or ingestion cadence.

## Decisions

### Decision: Reuse existing modal interaction path for hero CTA
**Decision:** Wire hero CTA to the same `openSummary(item)` behavior used by feed cards.

**Rationale:**
- Reuses existing event tracking and modal rendering logic.
- Avoids duplicate interaction models and reduces regression risk.

**Alternatives considered:**
- Add a second hero-only modal implementation: rejected due to duplicate UI state and maintenance cost.

### Decision: Enforce readability with layered overlay + contrast-safe tokens
**Decision:** Strengthen hero overlay and badge/text color tokens so metadata remains visible independent of image luminance.

**Rationale:**
- Solves visibility issues without image preprocessing.
- Keeps responsive behavior in CSS instead of JS image analysis.

**Alternatives considered:**
- Dynamic luminance detection per image: rejected as unnecessary complexity for current scope.

### Decision: Expand modal dimensions with responsive constraints
**Decision:** Use a wider desktop container (minimum half viewport intent) while preserving mobile full-width behavior and near-full-height scrolling.

**Rationale:**
- Improves readability for summary blocks and TL;DR bullets.
- Keeps accessibility of close controls and keyboard escape path.

**Alternatives considered:**
- Full-screen modal only: rejected due to excessive visual disruption on desktop.

### Decision: Treat TL;DR loading as explicit skeleton state
**Decision:** Add a low-height horizontal shimmer placeholder visible when TL;DR is not yet available.

**Rationale:**
- Reduces perceived latency ambiguity.
- Matches existing skeleton design language already used for images/cards.

### Decision: Improve fallback query semantics for AI-news image retrieval
**Decision:** Enhance keyword fallback to AI-focused defaults (`ai machine learning deep learning`) and add explicit generic AI image fallback contract.

**Rationale:**
- Reduces irrelevant imagery when topic extraction is weak or providers return noisy results.
- Keeps behavior deterministic and testable.

## Risks / Trade-offs

- **[Risk] Wider modal may crowd smaller laptops** -> Mitigation: use responsive width caps with mobile-first breakpoints and overflow handling.
- **[Risk] Hero overlay could darken images too much** -> Mitigation: tune gradient opacity and preserve theme-specific token overrides.
- **[Risk] Fallback image monotony if providers fail frequently** -> Mitigation: keep provider chain first; generic AI fallback only as terminal fallback.
- **[Trade-off] Stronger AI default keywords may reduce non-AI niche relevance** -> Mitigation: apply defaults only when extracted keywords are insufficient.

## Migration Plan

1. Update hero CTA and hero readability styles in `frontend/index.html`.
2. Update modal sizing and TL;DR shimmer loading state in `frontend/index.html`.
3. Update backend keyword fallback and generic AI image fallback behavior in `backend/news_service.py`.
4. Verify behavior manually on desktop/mobile and run relevant checks.

Rollback:
- Revert hero CTA to external link behavior.
- Revert modal class and shimmer additions.
- Revert keyword/default fallback updates in image pipeline.

## Open Questions

- Should generic AI fallback be local static asset only, or deterministic remote URL with local optimization?
- Do we need separate fallback keyword sets per language now, or keep English-focused defaults in this change?
