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

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.