bulk commit changes!

openspec/changes/archive/2026-02-13-p10-ui-fixes/.openspec.yaml

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

openspec/changes/archive/2026-02-13-p10-ui-fixes/design.md

@@ -0,0 +1,88 @@
+## 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?

openspec/changes/archive/2026-02-13-p10-ui-fixes/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+The current UX for the homepage hero and summary modal still has high-friction behavior and readability issues, and image relevance is still inconsistent for AI news topics. Fixing these now improves retention, trust, and content quality without changing the core product flow.
+
+## What Changes
+
+- Change hero primary CTA behavior to open the in-site TL;DR summary flow instead of immediately sending users off-site.
+- Improve hero readability over images so `LATEST` and relative time metadata remain visible across themes and screen sizes.
+- Increase modal width and adjust modal height behavior so long content can use near full-height viewport scrolling.
+- Add a short horizontal shimmer placeholder for TL;DR bullet content while summary details are loading.
+- Strengthen image relevance by extracting better keywords from news text, adding AI-topic default keywords, and using a generic AI fallback image when providers fail.
+
+## Capabilities
+
+### New Capabilities
+- `hero-summary-entry-and-readability`: Define hero CTA in-site summary entry behavior and image-overlay readability requirements for badges, timestamps, headline, and summary text.
+- `modal-layout-and-loading-feedback`: Define modal sizing/overflow behavior and TL;DR loading placeholders for clearer perceived loading state.
+- `news-image-relevance-and-fallbacks`: Define keyword extraction quality, default AI keyword fallback rules, and generic AI image fallback behavior when no relevant image is found.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- **Frontend/UI:** `frontend/index.html` (hero CTA wiring, hero overlay/readability styles, modal width/height classes, TL;DR loading skeleton state).
+- **Backend/Image Pipeline:** `backend/news_service.py` (keyword extraction and provider fallback behavior for summary images).
+- **Assets/Config:** generic AI fallback image path/asset contract and related docs may be updated.

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/hero-summary-entry-and-readability/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Hero primary action opens in-site TL;DR summary
+The homepage hero primary CTA SHALL open the in-site summary modal for the hero article instead of navigating off-site.
+
+#### Scenario: Hero CTA opens summary modal
+- **WHEN** a user clicks the hero primary CTA
+- **THEN** the system opens the summary modal for the current hero article
+- **AND** no external navigation is triggered by that CTA
+
+### Requirement: Hero source link remains available as secondary action
+The hero section SHALL keep an explicit secondary source-link action for external navigation.
+
+#### Scenario: Source link navigates externally
+- **WHEN** a user clicks the hero source link
+- **THEN** the system opens the article source URL in a new tab
+
+### Requirement: Hero metadata readability over images
+Hero metadata (`LATEST`, relative time, headline, and summary) SHALL remain visually legible across bright and dark images on desktop and mobile.
+
+#### Scenario: Bright image background
+- **WHEN** the hero image contains bright regions under metadata text
+- **THEN** overlay and text styles preserve readable contrast for metadata and headline blocks
+
+#### Scenario: Mobile viewport readability
+- **WHEN** the hero renders on a mobile viewport
+- **THEN** metadata and title remain readable without overlapping controls or clipping

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/modal-layout-and-loading-feedback/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Modal width supports comfortable desktop reading
+The summary modal SHALL render with a desktop width that is approximately half of viewport width or larger when space allows, while remaining responsive on small screens.
+
+#### Scenario: Desktop width expansion
+- **WHEN** the modal opens on desktop viewport widths
+- **THEN** the modal content area renders wider than the previous narrow baseline
+- **AND** text blocks are readable without excessive line wrapping
+
+#### Scenario: Mobile responsiveness
+- **WHEN** the modal opens on small mobile viewport widths
+- **THEN** modal width remains fully usable without horizontal overflow
+
+### Requirement: Modal height supports near-full viewport scrolling
+The summary modal SHALL use near full-height viewport behavior when content overflows.
+
+#### Scenario: Overflowing summary content
+- **WHEN** summary content exceeds modal viewport height
+- **THEN** modal body remains scrollable with close controls accessible
+- **AND** modal container uses near full viewport height constraints
+
+### Requirement: TL;DR loading placeholder is explicit
+The modal SHALL show a horizontal shimmer placeholder for TL;DR content while TL;DR bullets are not yet available.
+
+#### Scenario: TL;DR pending state
+- **WHEN** the summary modal is open and TL;DR bullet data is pending
+- **THEN** the system displays a low-height horizontal shimmer placeholder
+
+#### Scenario: TL;DR loaded state
+- **WHEN** TL;DR bullet data becomes available
+- **THEN** shimmer placeholder is removed
+- **AND** TL;DR bullet list is rendered

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/news-image-relevance-and-fallbacks/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Image query fallback uses AI-focused defaults
+When extracted image keywords are insufficient, the system SHALL use AI-focused default fallback terms.
+
+#### Scenario: Empty keyword extraction
+- **WHEN** keyword extraction yields no usable topic keywords
+- **THEN** the system uses default fallback terms including AI-domain keywords (for example `ai`, `machine learning`, `deep learning`)
+
+### Requirement: Generic AI image fallback is guaranteed
+If provider lookups fail to return a usable summary image, the system SHALL use a generic AI-themed fallback image.
+
+#### Scenario: Provider chain failure
+- **WHEN** all configured image providers return no usable image
+- **THEN** the system assigns a generic AI fallback image URL/path for summary image
+
+### Requirement: Fallback behavior remains context-aware first
+The system SHALL attempt context-aware keyword retrieval before any generic fallback image is selected.
+
+#### Scenario: Context-aware attempt precedes fallback
+- **WHEN** summary image selection runs for a news item
+- **THEN** the system first attempts provider queries from extracted context-aware keywords
+- **AND** only falls back to generic AI image if these attempts fail

openspec/changes/archive/2026-02-13-p10-ui-fixes/tasks.md

@@ -0,0 +1,29 @@
+## 1. Hero UX Fixes
+
+- [x] 1.1 Update hero primary CTA in `frontend/index.html` to open the in-site summary modal for the hero item.
+- [x] 1.2 Keep hero source link as a secondary external action and preserve tracking events.
+- [x] 1.3 Strengthen hero overlay and metadata styles so `LATEST` and relative time remain readable across image brightness levels.
+
+## 2. Modal Layout Improvements
+
+- [x] 2.1 Increase modal width for desktop while keeping mobile-safe responsive behavior.
+- [x] 2.2 Update modal height/overflow behavior to support near full-height scrolling for long content.
+- [x] 2.3 Verify close controls and keyboard escape behavior remain intact after sizing changes.
+
+## 3. TL;DR Loading Feedback
+
+- [x] 3.1 Add a dedicated horizontal shimmer placeholder for TL;DR content while modal summary data is initializing.
+- [x] 3.2 Hide the TL;DR shimmer placeholder when TL;DR bullets are available and render the bullet list.
+
+## 4. Image Relevance and Fallback
+
+- [x] 4.1 Update keyword fallback logic in `backend/news_service.py` to use AI-focused default terms when extracted keywords are insufficient.
+- [x] 4.2 Add explicit generic AI summary-image fallback behavior when provider chain returns no usable image.
+- [x] 4.3 Ensure context-aware keyword/provider attempts always run before generic AI fallback selection.
+
+## 5. Validation
+
+- [x] 5.1 Verify hero CTA opens summary modal instead of navigating away.
+- [x] 5.2 Verify modal sizing on desktop/mobile and long-content scrolling behavior.
+- [x] 5.3 Verify TL;DR shimmer appears during pending state and disappears after load.
+- [x] 5.4 Verify generic AI fallback image is used when provider chain fails.

openspec/changes/archive/2026-02-13-p11-superman-jetty/.openspec.yaml

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

openspec/changes/archive/2026-02-13-p11-superman-jetty/design.md

@@ -0,0 +1,85 @@
+## Context
+
+Current operations are concentrated in `backend/cli.py` with a single `force-fetch` command and no unified admin maintenance suite. Operational actions such as archive cleanup, translation regeneration, image refresh, and cache/news reset require manual code/DB operations. Existing backend services already contain reusable primitives: ingestion (`process_and_store_news`), archival helpers (`archive_old_news`, `delete_archived_news`), and translation generation pipelines in `backend/news_service.py`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Introduce an admin command suite that consolidates common maintenance and recovery actions.
+- Implement queued image refetch for latest 30 items, sequentially processed with exponential backoff.
+- Improve image refresh relevance by combining keyword and mood/sentiment cues with deterministic fallback behavior.
+- Provide safe destructive operations (`clear-news`, `clean-archive`, cache clear) with operator guardrails.
+- Add translation regeneration and parameterized fetch count command to reduce manual intervention.
+
+**Non-Goals:**
+- Replacing the scheduled ingestion model.
+- Introducing external queue infrastructure (RabbitMQ/Redis workers) for this phase.
+- Redesigning storage models or adding new DB tables unless strictly necessary.
+- Building a web-based admin dashboard in this change.
+
+## Decisions
+
+### Decision: Extend existing CLI with subcommands
+**Decision:** Expand `backend/cli.py` into a multi-subcommand admin command suite.
+
+**Rationale:**
+- Reuses existing deployment/runtime assumptions.
+- Keeps operations scriptable via terminal/cron and avoids UI scope expansion.
+
+**Alternatives considered:**
+- New standalone admin binary: rejected due to duplicated bootstrapping/runtime checks.
+
+### Decision: Queue image refetch in-process with sequential workers
+**Decision:** Build a bounded in-memory queue for latest 30 items and process one-by-one.
+
+**Rationale:**
+- Meets rate-limit resilience requirement without new infrastructure.
+- Deterministic and easy to monitor in command output.
+
+**Alternatives considered:**
+- Parallel refetch workers: rejected due to higher provider throttling risk.
+
+### Decision: Exponential backoff for external image calls
+**Decision:** Apply exponential backoff with capped retries for rate-limited or transient failures.
+
+**Rationale:**
+- Reduces burst retry amplification.
+- Improves success rate under API pressure.
+
+### Decision: Safety-first destructive command ergonomics
+**Decision:** Destructive operations require explicit confirmation/flags and support dry-run where meaningful.
+
+**Rationale:**
+- Prevents accidental data loss.
+- Makes admin actions auditable and predictable.
+
+### Decision: Fetch-N command reuses ingestion pipeline
+**Decision:** Add a fetch-count option that drives existing ingestion/fetch flow rather than building a second implementation.
+
+**Rationale:**
+- Preserves deduplication/retry logic and minimizes divergence.
+
+## Risks / Trade-offs
+
+- **[Risk] Operator misuse of destructive commands** -> Mitigation: confirmation gate + explicit flags + dry-run.
+- **[Risk] Backoff can increase command runtime** -> Mitigation: cap retries and print progress ETA-style output.
+- **[Risk] Queue processing interruption mid-run** -> Mitigation: idempotent per-item updates and resumable reruns.
+- **[Trade-off] In-process queue is simpler but non-distributed** -> Mitigation: acceptable for admin-invoked maintenance scope.
+
+## Migration Plan
+
+1. Extend CLI parser with admin subcommands and argument validation.
+2. Add reusable maintenance handlers (archive clean, cache clear, clear news, rebuild, regenerate translations, fetch-n).
+3. Implement queued image-refetch handler with exponential backoff and per-item progress logs.
+4. Add safe guards (`--confirm`, optional `--dry-run`) for destructive operations.
+5. Document command usage and examples in README.
+
+Rollback:
+- Keep existing `force-fetch` path intact.
+- Revert new subcommands while preserving unaffected ingestion pipeline.
+
+## Open Questions
+
+- What cache layers are considered in-scope for `clear-cache` (in-memory only vs additional filesystem cache)?
+- Should `rebuild-site` chain all maintenance actions or remain a defined subset with explicit steps?
+- Should `fetch n` enforce an upper bound to avoid accidental high-cost runs?

openspec/changes/archive/2026-02-13-p11-superman-jetty/proposal.md

@@ -0,0 +1,34 @@
+## Why
+
+Operational recovery and maintenance flows are currently fragmented, manual, and risky for site admins during outages or data-quality incidents. We need a reliable admin command surface that supports safe reset/rebuild workflows without requiring ad-hoc scripts.
+
+## What Changes
+
+- Add a unified admin CLI command with maintenance subcommands for common operational tasks.
+- Add `refetch-images` mode that processes the latest 30 news items through a queue, one-by-one, with exponential backoff to reduce provider/API rate-limit failures.
+- Make image refetch context-aware using article keywords plus mood/sentiment signals to improve image relevance.
+- Add archive cleanup command for archived news maintenance.
+- Add cache clear command for application cache invalidation.
+- Add clear-news command for wiping existing news items.
+- Add rebuild-site command to re-run full rebuild workflow.
+- Add regenerate-translations command for all supported languages.
+- Add fetch command supporting user-provided `n` article count.
+- Add guardrails and operator UX improvements (dry-run where applicable, progress output, failure summaries, and safe defaults).
+
+## Capabilities
+
+### New Capabilities
+- `admin-maintenance-command-suite`: Defines a single admin command surface with subcommands for refetch images, archive cleanup, cache clear, news clear, rebuild, translation regeneration, and fetch-n workflows.
+- `queued-image-refetch-with-backoff`: Defines queue-based image refetch behavior for latest 30 items with sequential processing and exponential backoff for rate-limit resilience.
+- `context-aware-image-selection-recovery`: Defines keyword + sentiment/mood-informed image query rules and generic AI fallback behavior for refetch operations.
+- `site-admin-safety-and-ergonomics`: Defines operational safeguards and usability requirements (dry-run, confirmation for destructive actions, progress reporting, and actionable error summaries).
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- **Backend/CLI:** new admin command entrypoints and orchestration logic for maintenance workflows.
+- **News/Image Pipeline:** image re-fetch and optimization logic, retry/backoff strategy, and relevance heuristics.
+- **Data Layer:** archive cleanup, cache invalidation, news-clear, translation regeneration, and controlled fetch-count ingestion operations.
+- **Operations:** faster incident recovery, reduced manual intervention, and safer reset/rebuild procedures for admins.

openspec/changes/archive/2026-02-13-p11-superman-jetty/specs/admin-maintenance-command-suite/spec.md

@@ -0,0 +1,32 @@
+## ADDED Requirements
+
+### Requirement: Unified admin command surface
+The system SHALL provide a single admin CLI command family exposing maintenance subcommands.
+
+#### Scenario: Subcommand discovery
+- **WHEN** an operator runs the admin command help output
+- **THEN** available subcommands include refetch-images, clean-archive, clear-cache, clear-news, rebuild-site, regenerate-translations, and fetch
+
+### Requirement: Fetch command supports configurable article count
+The admin fetch command SHALL support an operator-provided article count parameter.
+
+#### Scenario: Fetch with explicit count
+- **WHEN** an operator invokes fetch with `n=25`
+- **THEN** the command executes ingestion targeting the requested count
+- **AND** prints completion summary including processed/stored counts
+
+### Requirement: Translation regeneration command
+The system SHALL provide a command to regenerate translations for existing articles.
+
+#### Scenario: Regenerate translations run
+- **WHEN** an operator runs regenerate-translations
+- **THEN** the system attempts translation regeneration for supported languages
+- **AND** outputs success/failure totals
+
+### Requirement: Rebuild site command
+The system SHALL provide a rebuild-site command that executes the defined rebuild workflow.
+
+#### Scenario: Rebuild execution
+- **WHEN** an operator runs rebuild-site
+- **THEN** the system executes the documented rebuild steps in deterministic order
+- **AND** prints a final success/failure summary

openspec/changes/archive/2026-02-13-p11-superman-jetty/specs/context-aware-image-selection-recovery/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Context-aware image query generation
+Image refetch SHALL construct provider queries from article context including keywords and mood/sentiment cues.
+
+#### Scenario: Context-enriched query
+- **WHEN** a queued article is processed for image refetch
+- **THEN** the system derives query terms from article headline/summary content
+- **AND** includes mood/sentiment-informed cues to improve relevance
+
+### Requirement: AI-domain fallback keywords
+When context extraction is insufficient, the system SHALL use AI-domain fallback keywords.
+
+#### Scenario: Empty or weak context extraction
+- **WHEN** extracted context terms are empty or below quality threshold
+- **THEN** the system applies fallback terms such as `ai`, `machine learning`, `deep learning`
+
+### Requirement: Generic AI fallback image on terminal failure
+If no usable provider image is returned, the system SHALL assign a generic AI fallback image.
+
+#### Scenario: Provider chain exhaustion
+- **WHEN** all provider attempts fail or return unusable images
+- **THEN** the system stores a generic AI fallback image for the article

openspec/changes/archive/2026-02-13-p11-superman-jetty/specs/queued-image-refetch-with-backoff/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Latest-30 queue construction
+The refetch-images command SHALL enqueue up to the latest 30 news items for processing.
+
+#### Scenario: Queue population
+- **WHEN** refetch-images is started
+- **THEN** the command loads recent news items
+- **AND** enqueues at most 30 items ordered from newest to oldest
+
+### Requirement: Sequential processing
+The image refetch queue SHALL be processed one item at a time.
+
+#### Scenario: Single-item worker behavior
+- **WHEN** queue processing runs
+- **THEN** only one queued item is processed concurrently
+- **AND** next item starts only after current item completes/fails
+
+### Requirement: Exponential backoff on transient failures
+The queue processor SHALL retry transient image-provider failures using exponential backoff.
+
+#### Scenario: Rate-limited provider response
+- **WHEN** provider call returns rate-limit or transient error
+- **THEN** command retries with exponential delay between attempts
+- **AND** stops retrying after configured max attempts
+
+### Requirement: Progress and completion reporting
+The command SHALL emit operator-readable progress and final summary output.
+
+#### Scenario: Queue progress output
+- **WHEN** queue processing is in progress
+- **THEN** the command prints per-item progress (processed/succeeded/failed)
+- **AND** prints final totals on completion

openspec/changes/archive/2026-02-13-p11-superman-jetty/specs/site-admin-safety-and-ergonomics/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Confirmation guard for destructive commands
+Destructive admin commands SHALL require explicit confirmation before execution.
+
+#### Scenario: Missing confirmation flag
+- **WHEN** an operator runs clear-news or clean-archive without required confirmation
+- **THEN** the command exits without applying destructive changes
+- **AND** prints guidance for explicit confirmation usage
+
+### Requirement: Dry-run support where applicable
+Maintenance commands SHALL provide dry-run mode for previewing effects where feasible.
+
+#### Scenario: Dry-run preview
+- **WHEN** an operator invokes a command with dry-run mode
+- **THEN** the command reports intended actions and affected counts
+- **AND** persists no data changes
+
+### Requirement: Actionable failure summaries
+Admin commands SHALL output actionable errors and final status summaries.
+
+#### Scenario: Partial failure reporting
+- **WHEN** a maintenance command partially fails
+- **THEN** output includes succeeded/failed counts
+- **AND** includes actionable next-step guidance

openspec/changes/archive/2026-02-13-p11-superman-jetty/tasks.md

@@ -0,0 +1,41 @@
+## 1. Admin CLI Foundation
+
+- [x] 1.1 Extend `backend/cli.py` parser with an admin maintenance command group and subcommands.
+- [x] 1.2 Add argument validation for subcommands including `fetch --count n`.
+- [x] 1.3 Keep existing `force-fetch` command behavior intact.
+
+## 2. Queue-Based Image Refetch
+
+- [x] 2.1 Implement latest-30 article selection query for refetch queue.
+- [x] 2.2 Implement in-process sequential queue worker for refetch-images.
+- [x] 2.3 Add exponential backoff retry logic for transient/rate-limit provider failures.
+- [x] 2.4 Add per-item progress logging and final queue summary output.
+
+## 3. Context-Aware Image Recovery
+
+- [x] 3.1 Add context-aware query generation using article keywords plus mood/sentiment cues.
+- [x] 3.2 Add AI-domain fallback keyword set when extracted context is weak.
+- [x] 3.3 Add explicit generic AI fallback image assignment for terminal provider failure.
+- [x] 3.4 Ensure refetched images are optimized and persisted using existing image pipeline contracts.
+
+## 4. Maintenance Operations
+
+- [x] 4.1 Implement clean-archive command using existing archival repository helpers.
+- [x] 4.2 Implement clear-cache command for configured cache layers in scope.
+- [x] 4.3 Implement clear-news command for non-archived and/or configured scope items.
+- [x] 4.4 Implement rebuild-site command to execute defined rebuild sequence.
+- [x] 4.5 Implement regenerate-translations command across supported languages.
+- [x] 4.6 Implement fetch command with configurable article count.
+
+## 5. Safety and Operator UX
+
+- [x] 5.1 Add explicit confirmation requirement for destructive commands.
+- [x] 5.2 Add dry-run support for commands where preview is feasible.
+- [x] 5.3 Standardize command output format for success/failure totals and next-step hints.
+
+## 6. Documentation and Validation
+
+- [x] 6.1 Update README command documentation with examples for each new subcommand.
+- [x] 6.2 Add operational guardrail notes (confirmation, dry-run, backoff behavior).
+- [x] 6.3 Validate command help output and argument handling.
+- [x] 6.4 Run end-to-end manual checks for refetch-images queue behavior and failure recovery output.

openspec/changes/p12-umami-events-and-more/.openspec.yaml

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

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

@@ -0,0 +1,23 @@
+## Why
+
+Current Umami event payloads for CTA clicks and summary modal interactions include only `article_id`, which makes analysis harder when reviewing dashboards and raw events. Adding human-readable article context improves analyst speed and reduces lookup friction.
+
+## What Changes
+
+- Add `article_title` to CTA-click event payloads so click analytics can be understood without cross-referencing IDs.
+- Add `article_title` to summary modal open/close event payloads in addition to existing `article_id` context.
+- Keep existing event names and current fields intact for backward compatibility.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `hero-display`: Update analytics tracking requirement so CTA click events include both `article_id` and `article_title`.
+- `summary-analytics-tagging`: Update modal open/close analytics requirements so payload includes `article_title` with existing article context identifier.
+
+## Impact
+
+- **Frontend analytics wiring:** `frontend/index.html` event payload construction for hero/feed CTA clicks and summary modal open/close events.
+- **Analytics consumers:** Umami dashboards and downstream event analysis gain readable article context while preserving existing identifiers.

openspec/changes/p13-usability-enhancements/.openspec.yaml

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