Add monthly MVP snapshots and API

ai/tasks/done/TASK-068-monthly-mvp-snapshots-and-api.md

@@ -0,0 +1,69 @@
+# TASK-068-monthly-mvp-snapshots-and-api
+
+## Goal
+Exponer el ranking mensual MVP V1 mediante snapshots JSON y API propia del backend, siguiendo la misma filosofía rápida y estable ya usada por la capa histórica.
+
+## Context
+Una vez implementado el cálculo backend del monthly MVP, hace falta integrarlo en la capa de snapshots del proyecto para que:
+- no dependa de cálculos pesados on-demand
+- pueda servirse rápido a la UI
+- sea consistente con el resto de la arquitectura histórica
+
+## Steps
+1. Revisar la implementación del cálculo mensual MVP y la arquitectura actual de snapshots JSON.
+2. Diseñar la forma de snapshot para el ranking mensual MVP, tanto por servidor como para all-servers.
+3. Generar snapshots JSON apropiados, por ejemplo:
+   - server monthly mvp
+   - all-servers monthly mvp
+4. Incluir metadatos claros, como mínimo:
+   - generated_at
+   - source_range_start
+   - source_range_end
+   - freshness / is_stale si aplica
+   - month_key o periodo real usado
+5. Exponer endpoints claros y consistentes para leer esos snapshots.
+6. Mantener compatibilidad y coherencia con la API histórica existente.
+7. Integrar el monthly MVP en el runner/generación periódica de snapshots si corresponde.
+8. No crear todavía la UI final en esta task.
+9. Al completar la implementación:
+   - dejar el repositorio consistente
+   - hacer commit
+   - hacer push al remoto si el entorno lo permite
+
+## Files to Read First
+- AGENTS.md
+- backend/README.md
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_runner.py
+- backend/app/config.py
+- docs/monthly-mvp-ranking-scoring-design.md
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/historical_snapshots.py
+- backend/app/historical_snapshot_storage.py
+- backend/app/historical_runner.py
+- backend/README.md
+- opcionalmente nuevos módulos auxiliares si mejoran claridad
+
+## Constraints
+- No recalcular el ranking pesado en cada request de usuario.
+- No romper snapshots históricos existentes.
+- No crear todavía UI nueva en esta task.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en snapshots y API del monthly MVP.
+
+## Validation
+- Existen snapshots JSON del monthly MVP para servidor y/o all-servers según diseño.
+- Existen endpoints para leer esos snapshots.
+- El monthly MVP se integra con la operativa de snapshots del proyecto.
+- La respuesta es rápida y coherente con el resto de la API histórica.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.