Add Dockerized local project workflow

ai/tasks/done/TASK-060-backend-dockerization.md

@@ -0,0 +1,60 @@
+# TASK-060-backend-dockerization
+
+## Goal
+Preparar el backend Python del proyecto para ejecutarse correctamente dentro de un contenedor Docker, con una imagen reproducible, variables de entorno claras y persistencia adecuada de datos históricos y snapshots.
+
+## Context
+El backend ya funciona localmente, pero aún no está preparado formalmente para una ejecución containerizada estándar. Antes de pensar en despliegue real, hace falta empaquetarlo de forma consistente y dejar claro cómo se inyectan configuración, rutas de datos y puertos.
+
+## Steps
+1. Revisar la estructura actual del backend y su forma de arranque.
+2. Diseñar un Dockerfile específico para el backend.
+3. Asegurar que el backend pueda arrancar en contenedor con:
+   - host correcto
+   - puerto configurable
+   - variables de entorno ya soportadas por el proyecto
+4. Revisar qué rutas del backend deben persistirse fuera del contenedor, especialmente:
+   - SQLite histórica
+   - snapshots JSON
+   - cualquier artefacto operativo relevante
+5. Preparar una estrategia razonable de `.dockerignore` para backend.
+6. Mantener la imagen lo más simple y reproducible posible.
+7. No resolver todavía reverse proxy final ni TLS en esta task.
+8. 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/main.py
+- backend/app/config.py
+- backend/app/historical_ingestion.py
+- backend/app/historical_runner.py
+- backend/app/historical_snapshots.py
+- backend/requirements.txt
+- .gitignore
+
+## Expected Files to Modify
+- backend/Dockerfile
+- backend/.dockerignore
+- backend/README.md
+- opcionalmente archivos de entorno de ejemplo si mejoran claridad, por ejemplo:
+  - backend/.env.example
+
+## Constraints
+- No romper el arranque local existente.
+- No eliminar la persistencia local del histórico.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en containerizar el backend.
+
+## Validation
+- Existe un Dockerfile de backend funcional.
+- La persistencia necesaria del backend queda identificada y documentada.
+- El backend puede ejecutarse con configuración inyectable por entorno.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-061-frontend-dockerization.md

@@ -0,0 +1,55 @@
+# TASK-061-frontend-dockerization
+
+## Goal
+Preparar el frontend estático del proyecto para ejecutarse dentro de un contenedor Docker de forma simple y estable, con una estrategia clara para servir `historico.html`, la landing y los assets.
+
+## Context
+El frontend actual es estático y ya funciona localmente, pero aún no tiene una imagen Docker formal para ejecución consistente. Hace falta dejarlo empaquetado de forma simple, sin introducir complejidad innecesaria.
+
+## Steps
+1. Revisar la estructura actual del frontend.
+2. Diseñar un Dockerfile adecuado para servir el frontend estático.
+3. Elegir una estrategia simple y mantenible para servir:
+   - `index.html`
+   - `historico.html`
+   - assets CSS/JS/img
+4. Asegurar que el frontend pueda configurarse para hablar con el backend containerizado si hay alguna URL/base path que deba quedar clara.
+5. Preparar una estrategia razonable de `.dockerignore` si procede.
+6. No introducir frameworks ni bundlers nuevos.
+7. No resolver todavía reverse proxy final ni TLS en esta task.
+8. 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
+- frontend/index.html
+- frontend/historico.html
+- frontend/assets/js/main.js
+- frontend/assets/js/historico.js
+- frontend/assets/css/styles.css
+- frontend/assets/css/historico.css
+- .gitignore
+
+## Expected Files to Modify
+- frontend/Dockerfile
+- frontend/.dockerignore
+- opcionalmente una mínima documentación asociada si ayuda a explicar el arranque
+- opcionalmente un archivo de configuración simple si mejora claridad del servido estático
+
+## Constraints
+- No romper el frontend local actual.
+- No introducir frameworks nuevos.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en containerizar el frontend estático.
+
+## Validation
+- Existe un Dockerfile de frontend funcional.
+- El frontend puede servirse correctamente desde contenedor.
+- La landing y la página histórica quedan accesibles.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados o creados.
+- Preferir menos de 180 líneas cambiadas.

ai/tasks/done/TASK-062-docker-compose-project-orchestration.md

@@ -0,0 +1,52 @@
+# TASK-062-docker-compose-project-orchestration
+
+## Goal
+Añadir una orquestación básica por Docker Compose para levantar conjuntamente frontend y backend del proyecto con persistencia adecuada del histórico.
+
+## Context
+Una vez frontend y backend estén dockerizados, hace falta una forma simple de arrancarlos juntos para desarrollo y predespliegue. Esta task debe dejar una base clara y operativa sin meterse todavía en infraestructura final de producción.
+
+## Steps
+1. Revisar los Dockerfile de frontend y backend.
+2. Diseñar un `docker-compose.yml` o equivalente moderno para levantar ambos servicios.
+3. Asegurar que el backend exponga correctamente su puerto al frontend.
+4. Configurar persistencia razonable para:
+   - SQLite histórica
+   - snapshots JSON
+5. Preparar nombres de servicio y red interna claros.
+6. Asegurar que el proyecto pueda arrancarse con una instrucción sencilla.
+7. No introducir todavía reverse proxy público, TLS ni balanceo.
+8. 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/Dockerfile
+- frontend/Dockerfile
+- backend/README.md
+- frontend files relevantes
+- .gitignore
+
+## Expected Files to Modify
+- docker-compose.yml
+- backend/README.md
+- opcionalmente README raíz si conviene documentar el arranque conjunto
+- opcionalmente archivos `.env.example` si mejoran claridad
+
+## Constraints
+- No romper el uso local fuera de Docker.
+- No meter todavía infraestructura final de producción.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en levantar el proyecto completo con Docker Compose.
+
+## Validation
+- Existe una orquestación Docker Compose clara para frontend y backend.
+- Los datos persistentes del backend no se pierden al recrear contenedores.
+- El proyecto puede levantarse con un flujo simple y documentado.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-063-docker-runbook-and-env-docs.md

@@ -0,0 +1,55 @@
+# TASK-063-docker-runbook-and-env-docs
+
+## Goal
+Documentar de forma clara cómo ejecutar el proyecto con Docker, qué variables de entorno utiliza y qué persistencia necesita, dejando una guía práctica para desarrollo y predespliegue.
+
+## Context
+Una containerización útil no queda cerrada solo con Dockerfiles y Compose; hace falta documentación clara para levantar el proyecto, entender los volúmenes, configurar entorno y evitar errores de operación.
+
+## Steps
+1. Revisar el estado final de la containerización del frontend y backend.
+2. Documentar cómo construir y arrancar el proyecto con Docker.
+3. Documentar variables de entorno relevantes del backend.
+4. Documentar qué carpetas o volúmenes deben persistirse.
+5. Incluir una guía breve para:
+   - primer arranque
+   - reinicio
+   - regeneración de snapshots
+   - backfill histórico dentro o fuera del contenedor si aplica
+6. No convertir esta task en una guía de infraestructura final.
+7. Mantener la documentación práctica y enfocada al estado real del proyecto.
+8. 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
+- README.md
+- backend/README.md
+- docker-compose.yml
+- backend/app/config.py
+- backend/app/historical_ingestion.py
+- backend/app/historical_runner.py
+
+## Expected Files to Modify
+- README.md
+- backend/README.md
+- opcionalmente docs/docker-deployment.md
+- opcionalmente archivos de ejemplo de entorno si ayudan a claridad
+
+## Constraints
+- No meter documentación ficticia.
+- No describir infraestructura que aún no exista.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en un runbook realista para Docker.
+
+## Validation
+- La documentación explica cómo levantar el proyecto con Docker.
+- Las variables y volúmenes relevantes quedan claras.
+- Existe una guía útil para el flujo operativo básico.
+- Los cambios quedan committeados y se hace push si el entorno lo permite.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.