sistema A2S

ai/tasks/done/TASK-001-platform-readiness-check.md

@@ -0,0 +1,75 @@
+# TASK-001-platform-readiness-check
+
+## Goal
+Validar que la integración de AI Development Platform en el repositorio HLL Vietnam está completa, coherente y lista para ejecutar tasks de forma segura con Codex.
+
+## Context
+El repositorio ya tiene una estructura base de producto y se ha integrado la capa operativa inspirada en ai-dev-platform-template. Antes de generar tasks funcionales del producto, hay que verificar que el flujo por tasks, documentación, scripts y estructura están realmente alineados y no contienen inconsistencias.
+
+## Steps
+1. Revisar la estructura de carpetas del repositorio.
+2. Verificar que existen y son coherentes:
+   - AGENTS.md
+   - ai/task-template.md
+   - ai/repo-context.md
+   - ai/architecture-index.md
+   - ai/system-metrics.md
+   - ai/prompts/plan-feature.md
+   - ai/orchestrator/*
+   - ai/tasks/pending
+   - ai/tasks/in-progress
+   - ai/tasks/done
+   - scripts/codex-runner.ps1
+   - scripts/run-integration-tests.ps1
+3. Confirmar que AGENTS.md refleja el flujo correcto:
+   - el orquestador analiza código y redacta tasks
+   - Codex no actúa fuera de tasks salvo mantenimiento o inspección explícita
+   - backend previsto en Python
+   - frontend actual en HTML/CSS/JS
+4. Revisar que la documentación de contexto no contradice el proyecto HLL Vietnam.
+5. Revisar que la task actual y la plantilla de task usan una estructura coherente con el template.
+6. Si detectas incoherencias pequeñas, corrígelas.
+7. Dejar un breve resumen en ai/system-metrics.md o en la documentación correspondiente si el flujo del repo ya lo contempla.
+
+## Files to Read First
+- AGENTS.md
+- README.md
+- docs/project-overview.md
+- docs/decisions.md
+- ai/task-template.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- ai/orchestrator/README.md
+- scripts/codex-runner.ps1
+- scripts/run-integration-tests.ps1
+
+## Expected Files to Modify
+- Solo los estrictamente necesarios si se detectan inconsistencias menores.
+- No modificar archivos de producto salvo documentación mínima si es imprescindible.
+
+## Constraints
+- No implementar features del producto.
+- No tocar la landing salvo que haya una inconsistencia documental o estructural.
+- No añadir dependencias nuevas.
+- No hacer cambios destructivos.
+- Mantener el cambio pequeño y verificable.
+
+## Validation
+- La estructura AI Platform existe y es navegable.
+- AGENTS.md refleja correctamente el flujo de trabajo del proyecto.
+- No hay referencias obsoletas a .NET como arquitectura del producto.
+- Los scripts clave existen.
+- La plantilla de task es usable para futuras tasks.
+- El repo queda listo para que el siguiente paso sea crear una task funcional real.
+
+## Change Budget
+- Preferir menos de 8 archivos modificados.
+- Preferir menos de 250 líneas cambiadas.
+
+## Outcome
+- Verificada la existencia y coherencia de `AGENTS.md`, `ai/task-template.md`, `ai/repo-context.md`, `ai/architecture-index.md`, `ai/system-metrics.md`, `ai/prompts/plan-feature.md`, `ai/orchestrator/*`, `ai/tasks/*`, `scripts/codex-runner.ps1` y `scripts/run-integration-tests.ps1`.
+- Confirmado que `AGENTS.md` refleja correctamente el flujo por tasks, el alcance de Codex y la dirección técnica actual: frontend en HTML/CSS/JS y backend futuro en Python.
+- Corregidas dos incoherencias documentales menores:
+  - `README.md` ya no presenta la plataforma AI como integración futura.
+  - `docs/roadmap.md` ahora trata la orquestación como capacidad existente que debe evolucionar, no incorporarse desde cero.
+- Validación manual completada. El script `scripts/run-integration-tests.ps1` existe, pero actualmente solo documenta que no hay tests de integración configurados para este alcance.

ai/tasks/done/TASK-002-logo-asset-integration.md

@@ -0,0 +1,61 @@
+# TASK-002-logo-asset-integration
+
+## Goal
+Integrar correctamente el logo real del proyecto HLL Vietnam en la landing actual, asegurando que el frontend use un asset local estable y coherente con la identidad visual del proyecto.
+
+## Context
+La landing inicial ya existe y actualmente está preparada para mostrar un logo local en `frontend/assets/img/logo.png`. Antes de hacer mejoras visuales adicionales, hay que consolidar la integración del logo real para que el proyecto tenga una base visual correcta, mantenible y consistente.
+
+## Steps
+1. Revisar la estructura actual del frontend.
+2. Confirmar que existe la ruta esperada para el logo:
+   - `frontend/assets/img/logo.png`
+3. Si el logo real aún no está en esa ruta, dejar la integración preparada de forma segura sin romper la página.
+4. Revisar `frontend/index.html` para asegurar que:
+   - usa la ruta local correcta del logo
+   - el `alt` del logo es descriptivo y coherente
+   - no hay rutas temporales, absolutas o inconsistentes
+5. Revisar `frontend/assets/css/styles.css` para asegurar que:
+   - el bloque visual del logo tiene un tamaño adecuado
+   - mantiene buena presentación en escritorio y móvil
+   - no deforma la imagen
+6. Corregir cualquier inconsistencia menor relacionada con la carga o presentación del logo.
+7. Mantener la landing simple: logo, tráiler y botón de Discord.
+
+## Files to Read First
+- frontend/index.html
+- frontend/assets/css/styles.css
+- docs/project-overview.md
+- ai/repo-context.md
+- AGENTS.md
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+- opcionalmente `frontend/assets/img/logo.png` si el flujo de la task contempla dejar el asset correctamente ubicado
+
+## Constraints
+- No rediseñar toda la landing.
+- No añadir nuevas secciones.
+- No introducir frameworks ni dependencias nuevas.
+- No tocar backend.
+- No hacer cambios destructivos.
+- Mantener la estética militar sobria ya definida.
+
+## Validation
+- La landing referencia el logo local mediante una ruta estable.
+- El logo se muestra correctamente sin deformaciones.
+- El HTML sigue funcionando al abrirse directamente en navegador.
+- La presentación del logo es correcta tanto en móvil como en escritorio.
+- No se rompe el tráiler ni el botón de Discord.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 120 líneas cambiadas.
+
+## Outcome
+- Confirmada la existencia del asset local `frontend/assets/img/logo.png`; no fue necesario reemplazarlo ni moverlo.
+- `frontend/index.html` mantiene una ruta local estable (`./assets/img/logo.png`) y ahora usa un `alt` más descriptivo junto con dimensiones explícitas para reducir saltos de layout.
+- `frontend/assets/css/styles.css` ya no fuerza un contenedor cuadrado para el logo: la imagen conserva su proporción con `max-width` y `max-height`, con ajustes específicos para escritorio y móvil.
+- Validación completada mediante revisión del marcado, verificación de la ruta local del logo y revisión de `git diff --name-only`.
+- No hay tests de integración configurados para este alcance; la comprobación aplicable fue manual sobre HTML/CSS y compatibilidad con apertura directa en navegador.

ai/tasks/done/TASK-003-landing-minimal-polish.md

@@ -0,0 +1,67 @@
+# TASK-003-landing-minimal-polish
+
+## Goal
+Mejorar visualmente la landing actual de HLL Vietnam con un pulido minimo y controlado, reforzando la identidad militar y la claridad visual sin cambiar el alcance funcional de la pagina.
+
+## Context
+La landing ya tiene los tres elementos principales del alcance actual: logo local, boton de Discord y trailer embebido. Tras integrar correctamente el asset del logo, el siguiente paso es mejorar la presentacion general para que la pagina tenga una apariencia mas solida, mas limpia y mas coherente con la tematica del proyecto, sin anadir nuevas secciones ni complejidad innecesaria.
+
+## Steps
+1. Revisar la estructura actual de `frontend/index.html`.
+2. Revisar los estilos actuales en `frontend/assets/css/styles.css`.
+3. Mejorar la jerarquia visual del bloque principal:
+   - logo
+   - titulo principal
+   - subtitulo, si existe
+   - boton de Discord
+   - bloque del trailer
+4. Ajustar espaciados, tamanos, anchuras y alineaciones para mejorar legibilidad.
+5. Reforzar la identidad visual militar sobria:
+   - paleta oscura
+   - acentos controlados
+   - mejor contraste
+   - sensacion tactica/cinematica sin recargar
+6. Mejorar el contenedor del video para que se vea mas integrado en la composicion general.
+7. Verificar que la landing siga funcionando correctamente en escritorio y movil.
+8. Mantener el alcance estricto actual, sin anadir nuevas funcionalidades ni secciones.
+
+## Files to Read First
+- frontend/index.html
+- frontend/assets/css/styles.css
+- docs/project-overview.md
+- ai/repo-context.md
+- AGENTS.md
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+
+## Constraints
+- No anadir nuevas secciones de contenido.
+- No tocar backend.
+- No introducir frameworks ni librerias nuevas.
+- No modificar la ruta del logo.
+- No cambiar el enlace de Discord.
+- No cambiar el trailer.
+- No hacer cambios destructivos.
+- Mantener el HTML funcional abriendose directamente en navegador.
+
+## Validation
+- La landing se ve mas solida y ordenada visualmente.
+- Se mantiene el enfoque minimo: logo, identidad, Discord y trailer.
+- El logo sigue cargando desde `./assets/img/logo.png`.
+- El boton de Discord sigue visible y destacado.
+- El trailer sigue funcionando correctamente.
+- La presentacion sigue siendo responsive.
+- No se anaden elementos fuera del alcance actual.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 180 lineas cambiadas.
+
+## Outcome
+- `frontend/index.html` mantiene el contenido original de la landing y solo anade hooks de estilo para reforzar la jerarquia visual del bloque principal.
+- `frontend/assets/css/styles.css` mejora composicion, contraste, espaciados y tratamiento del bloque de video con una direccion mas sobria y tactica, sin introducir nuevas secciones ni funcionalidades.
+- Se mantuvieron sin cambios la ruta del logo (`./assets/img/logo.png`), el enlace de Discord y el `iframe` del trailer.
+- Validacion completada mediante revision del HTML/CSS resultante y `git diff --name-only`, confirmando que el alcance quedo limitado a los archivos esperados.
+- No hay tests de integracion configurados para este alcance; la validacion aplicable fue manual sobre compatibilidad de HTML/CSS para apertura directa en navegador y comportamiento responsive esperado.

ai/tasks/done/TASK-004-python-backend-bootstrap.md

@@ -0,0 +1,69 @@
+# TASK-004-python-backend-bootstrap
+
+## Goal
+Preparar una base minima y ordenada de backend en Python para el proyecto HLL Vietnam, dejando la estructura lista para crecer sin implementar todavia logica de negocio real ni integraciones externas.
+
+## Context
+El proyecto ya dispone de una landing minima funcional y de la capa operativa AI Platform integrada. El siguiente paso tecnico logico es dejar preparado el backend principal del proyecto, que estara basado en Python. En esta fase no se busca desarrollar funcionalidades reales, sino establecer una base limpia, mantenible y coherente con la futura evolucion del sistema.
+
+## Steps
+1. Revisar la estructura actual de la carpeta `backend/`.
+2. Preparar una base minima de aplicacion Python dentro de `backend/app/`.
+3. Crear o ajustar un punto de entrada claro para la aplicacion, por ejemplo un archivo principal como:
+   - `backend/app/main.py`
+4. Definir una estructura minima coherente para crecimiento posterior.
+5. Anadir un endpoint o mecanismo minimo de verificacion de estado, por ejemplo:
+   - `/health`
+   o equivalente segun la solucion elegida.
+6. Actualizar `backend/README.md` para explicar:
+   - proposito de la carpeta backend
+   - stack elegido en esta fase
+   - como arrancar localmente la base minima si ya aplica
+7. Ajustar `backend/requirements.txt` con las dependencias minimas reales, si fueran necesarias.
+8. Mantener el alcance estricto: solo bootstrap tecnico del backend.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/requirements.txt
+- backend/app/__init__.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/requirements.txt
+- backend/app/__init__.py
+- backend/app/main.py
+
+## Constraints
+- No implementar logica de Discord.
+- No implementar logica de servidores de juego.
+- No anadir base de datos todavia.
+- No introducir complejidad innecesaria.
+- No tocar frontend salvo documentacion cruzada minima si fuera imprescindible.
+- No hacer cambios destructivos.
+- Mantener la solucion simple, clara y preparada para crecer.
+
+## Validation
+- Existe una estructura backend mas solida que la inicial.
+- Existe un punto de entrada claro para la aplicacion Python.
+- Existe una verificacion minima de estado o equivalente.
+- La documentacion del backend refleja correctamente el nuevo estado.
+- No se han anadido funcionalidades fuera de alcance.
+- El backend queda listo para que una siguiente task defina contratos API o primeras rutas reales.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 220 lineas cambiadas.
+
+## Outcome
+- Bootstrap backend implementado con Python estandar, sin frameworks ni dependencias externas.
+- Punto de entrada creado en `backend/app/main.py`.
+- Health check minimo disponible en `GET /health`.
+- `backend/README.md` actualizado con estructura, alcance y forma de arranque local.
+- `backend/requirements.txt` mantenido sin dependencias externas para evitar compromisos prematuros de arquitectura.

ai/tasks/done/TASK-005-frontend-backend-contract.md

@@ -0,0 +1,86 @@
+# TASK-005-frontend-backend-contract
+
+## Goal
+Definir el contrato inicial entre frontend y backend para el proyecto HLL Vietnam, estableciendo endpoints, formatos de respuesta y convenciones mínimas sin implementar todavía integraciones reales con Discord, servidores de juego o base de datos.
+
+## Context
+El proyecto ya dispone de una landing mínima funcional y de un backend Python bootstrap con verificación básica de estado. Antes de añadir lógica real, es importante fijar un contrato claro entre frontend y backend para evitar improvisación posterior y permitir que futuras tasks implementen endpoints y consumo de datos de forma consistente.
+
+## Steps
+1. Revisar la estructura actual del frontend y del backend.
+2. Revisar el estado actual del backend bootstrap y el endpoint de salud existente.
+3. Definir el conjunto mínimo de endpoints previstos a corto plazo, aunque algunos queden documentados como futuros. Incluir al menos:
+   - `GET /health`
+   - `GET /api/community`
+   - `GET /api/trailer`
+   - `GET /api/discord`
+   - `GET /api/servers`
+4. Para cada endpoint, documentar:
+   - propósito
+   - método HTTP
+   - ruta
+   - formato de respuesta
+   - ejemplo JSON
+   - estado actual: implementado, previsto o placeholder
+5. Definir convenciones básicas de respuesta:
+   - nombres de campos
+   - estructura JSON
+   - uso de `status`
+   - tratamiento mínimo de errores
+6. Documentar cómo debería consumir el frontend estos endpoints más adelante, sin implementarlo todavía.
+7. Añadir o actualizar documentación técnica para que el contrato quede claro dentro del repositorio.
+8. Si detectas incoherencias pequeñas entre documentación y bootstrap actual, corrígelas sin salirte del alcance.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/main.py
+- frontend/index.html
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- docs/project-overview.md
+- docs/decisions.md
+- backend/README.md
+- ai/architecture-index.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - `docs/frontend-backend-contract.md`
+
+## Constraints
+- No implementar todavía endpoints reales adicionales.
+- No integrar Discord real.
+- No integrar servidores de juego reales.
+- No introducir base de datos.
+- No cambiar el comportamiento visible del frontend.
+- No añadir frameworks ni dependencias nuevas.
+- No hacer cambios destructivos.
+- Mantener la solución clara, pequeña y útil para futuras tasks.
+
+## Validation
+- Existe documentación clara del contrato inicial frontend-backend.
+- `GET /health` queda reflejado correctamente como endpoint actual.
+- Los endpoints futuros quedan documentados con ejemplos coherentes.
+- El contrato usa convenciones consistentes de respuesta JSON.
+- El repositorio queda preparado para que siguientes tasks implementen endpoints reales de forma ordenada.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.
+## Outcome
+
+- Se añadió `docs/frontend-backend-contract.md` como referencia central del contrato inicial frontend-backend.
+- Se actualizaron `docs/project-overview.md`, `docs/decisions.md` y `backend/README.md` para reflejar el contrato y el estado actual de `GET /health`.
+- No se implementaron endpoints nuevos ni se cambió el comportamiento visible del frontend.
+
+## Validation Result
+
+- Verificado con `python -c "from app.main import build_health_payload; print(build_health_payload())"` en `backend/`.
+- Resultado comprobado: `{'status': 'ok', 'service': 'hll-vietnam-backend', 'phase': 'bootstrap'}`.
+- No aplican integration tests para este alcance documental.

ai/tasks/done/TASK-006-discord-and-server-data-plan.md

@@ -0,0 +1,84 @@
+# TASK-006-discord-and-server-data-plan
+
+## Goal
+Definir la estrategia técnica inicial para obtener, modelar y exponer los futuros datos de Discord y de los servidores de juego en el proyecto HLL Vietnam, sin implementar todavía integraciones reales.
+
+## Context
+El proyecto ya dispone de una landing mínima, un backend Python bootstrap y un contrato inicial frontend-backend documentado. Antes de implementar endpoints reales o lógica de consumo en frontend, es necesario fijar un plan claro sobre qué datos se quieren mostrar, de qué fuentes podrían obtenerse, qué limitaciones existen y cuál será el orden recomendado de implementación.
+
+## Steps
+1. Revisar la documentación técnica actual del proyecto.
+2. Identificar qué información tendría sentido mostrar en la web sobre Discord. Incluir al menos posibles bloques como:
+   - enlace de invitación
+   - nombre de la comunidad
+   - estado o presencia aproximada si fuera viable
+   - información pública útil para comunidad
+3. Identificar qué información tendría sentido mostrar sobre los servidores de juego. Incluir al menos posibles bloques como:
+   - nombre del servidor
+   - estado online/offline
+   - mapa actual o rotación si fuera viable
+   - jugadores conectados
+   - capacidad máxima
+   - ping o metadatos similares si la fuente lo permite
+4. Documentar las posibles fuentes de datos para Discord, distinguiendo claramente entre:
+   - widget público
+   - API o integraciones externas
+   - bot propio
+   - datos configurados manualmente
+5. Documentar las posibles fuentes de datos para servidores de juego, distinguiendo claramente entre:
+   - consultas al servidor
+   - API externa
+   - datos mock/placeholder
+   - actualización manual
+6. Documentar riesgos, límites y restricciones:
+   - credenciales
+   - rate limits
+   - disponibilidad
+   - seguridad
+   - CORS
+   - latencia
+   - dependencia de servicios externos
+7. Proponer una estrategia por fases:
+   - fase inicial con placeholders o datos controlados
+   - fase intermedia con integración técnica limitada
+   - fase posterior con integración más real si procede
+8. Dejar claro qué NO se implementará todavía.
+9. Actualizar la documentación técnica del repositorio para que futuras tasks de backend y frontend tengan una base clara.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- docs/frontend-backend-contract.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+
+## Expected Files to Modify
+- docs/roadmap.md
+- docs/decisions.md
+- ai/architecture-index.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - docs/discord-and-server-data-plan.md
+
+## Constraints
+- No implementar integraciones reales.
+- No modificar comportamiento del frontend.
+- No añadir endpoints funcionales nuevos.
+- No introducir dependencias nuevas.
+- No tocar base de datos.
+- No hacer cambios destructivos.
+- Mantener el resultado claro, útil y centrado en planificación técnica.
+
+## Validation
+- Existe una estrategia documentada para los datos futuros de Discord.
+- Existe una estrategia documentada para los datos futuros de servidores.
+- Se distinguen claramente fuentes posibles, riesgos y fases.
+- Queda explícito qué se hará primero y qué se pospone.
+- La documentación sirve como base directa para siguientes tasks técnicas.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.

ai/tasks/done/TASK-007-backend-api-skeleton.md

@@ -0,0 +1,66 @@
+# TASK-007-backend-api-skeleton
+
+## Goal
+Preparar un esqueleto inicial de API en el backend Python para HLL Vietnam, dejando rutas y estructura listas para crecimiento posterior mediante respuestas placeholder o mock, sin integrar todavía Discord ni servidores reales.
+
+## Context
+El backend ya cuenta con un bootstrap mínimo y un endpoint de salud. El contrato frontend-backend ya define un conjunto inicial de endpoints previstos. El siguiente paso técnico es convertir esa definición en una estructura API básica y mantenible, con rutas organizadas y respuestas coherentes, aunque todavía sean estáticas o placeholder.
+
+## Steps
+1. Revisar el backend actual y la documentación del contrato frontend-backend.
+2. Confirmar el punto de entrada actual del backend y su estructura.
+3. Preparar una organización mínima para rutas API futuras dentro de `backend/app/`.
+4. Implementar o estructurar las rutas placeholder mínimas para:
+   - `GET /health`
+   - `GET /api/community`
+   - `GET /api/trailer`
+   - `GET /api/discord`
+   - `GET /api/servers`
+5. Hacer que las respuestas sean coherentes con el contrato ya documentado, aunque usen datos placeholder.
+6. Mantener una estructura clara para crecimiento posterior, por ejemplo separando:
+   - punto de entrada
+   - rutas
+   - utilidades o payloads placeholder si hiciera falta
+7. Actualizar la documentación del backend para reflejar la nueva estructura y cómo ejecutar la API localmente.
+8. Mantener el alcance estricto: esqueleto funcional, no integración real.
+
+## Files to Read First
+- AGENTS.md
+- docs/frontend-backend-contract.md
+- docs/project-overview.md
+- docs/decisions.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/requirements.txt
+- backend/app/__init__.py
+- backend/app/main.py
+
+## Expected Files to Modify
+- backend/app/main.py
+- backend/app/__init__.py
+- backend/README.md
+- opcionalmente archivos nuevos dentro de `backend/app/` si mejoran claridad, por ejemplo:
+  - backend/app/routes.py
+  - backend/app/payloads.py
+
+## Constraints
+- No integrar Discord real.
+- No integrar servidores reales.
+- No añadir base de datos.
+- No introducir complejidad innecesaria.
+- No tocar frontend.
+- No añadir frameworks nuevos si no son estrictamente necesarios para mantener coherencia con el bootstrap actual.
+- No hacer cambios destructivos.
+- Mantener la API simple, clara y consistente con la documentación ya existente.
+
+## Validation
+- El backend expone claramente los endpoints placeholder definidos.
+- `GET /health` sigue funcionando correctamente.
+- Los endpoints futuros definidos en el contrato existen al menos como placeholders coherentes.
+- La estructura backend queda mejor preparada para crecimiento.
+- La documentación del backend refleja el nuevo estado real.
+
+## Change Budget
+- Preferir menos de 7 archivos modificados o creados.
+- Preferir menos de 260 líneas cambiadas.

ai/tasks/done/TASK-008-frontend-data-consumption-plan.md

@@ -0,0 +1,68 @@
+# TASK-008-frontend-data-consumption-plan
+
+## Goal
+Definir cómo consumirá el frontend de HLL Vietnam los futuros endpoints del backend, dejando documentada una estrategia clara de integración de datos sin implementar todavía lógica real de consumo.
+
+## Context
+Ya existe una landing mínima y se ha definido un contrato inicial entre frontend y backend. Además, se va a preparar un esqueleto API en backend. Antes de introducir JavaScript de consumo real o secciones dinámicas, conviene dejar documentado cómo deberá organizarse la integración en frontend para mantener simplicidad, claridad y consistencia con la evolución del proyecto.
+
+## Steps
+1. Revisar el frontend actual y el contrato frontend-backend.
+2. Identificar qué bloques del frontend actual o futuro podrán depender de datos dinámicos del backend.
+3. Definir una estrategia mínima de consumo de datos adecuada al proyecto en esta fase, por ejemplo:
+   - `fetch`
+   - JavaScript simple
+   - módulos ligeros si fueran necesarios más adelante
+4. Documentar cómo deberían gestionarse:
+   - estados de carga
+   - errores
+   - ausencia de datos
+   - placeholders
+   - fallback visual
+5. Documentar qué endpoints podrían ser consumidos primero y con qué prioridad:
+   - `/health`
+   - `/api/community`
+   - `/api/trailer`
+   - `/api/discord`
+   - `/api/servers`
+6. Proponer una estrategia progresiva para pasar de landing estática a bloques dinámicos sin romper simplicidad.
+7. Añadir o actualizar documentación técnica del frontend o del proyecto con esta estrategia.
+8. Mantener el alcance documental: no implementar todavía fetch real ni renderizado dinámico.
+
+## Files to Read First
+- AGENTS.md
+- README.md
+- docs/project-overview.md
+- docs/frontend-backend-contract.md
+- docs/decisions.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Expected Files to Modify
+- docs/project-overview.md
+- docs/decisions.md
+- ai/architecture-index.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - docs/frontend-data-consumption-plan.md
+
+## Constraints
+- No implementar consumo real de API.
+- No cambiar comportamiento visible del frontend.
+- No añadir librerías nuevas.
+- No rediseñar la landing.
+- No tocar backend salvo referencias documentales mínimas si son imprescindibles.
+- No hacer cambios destructivos.
+- Mantener la solución centrada en planificación de integración.
+
+## Validation
+- Existe una estrategia documentada para el consumo de datos en frontend.
+- Quedan definidos criterios para loading, error, empty state y fallback.
+- Se identifican prioridades de consumo de endpoints.
+- El frontend queda preparado conceptualmente para evolucionar sin improvisación.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-009-backend-package-hygiene-and-entrypoint-alignment.md

@@ -0,0 +1,55 @@
+# TASK-009-backend-package-hygiene-and-entrypoint-alignment
+
+## Goal
+Corregir y alinear la estructura mínima del paquete backend en Python para HLL Vietnam, asegurando que el paquete, los imports y el entrypoint real sean consistentes, legibles y mantenibles.
+
+## Context
+El backend bootstrap y el esqueleto API placeholder ya existen, pero en resúmenes recientes aparece una posible inconsistencia con el archivo de paquete Python (`init.py` frente a `__init__.py`). Antes de continuar con más ajustes o integrar consumo desde frontend, es importante dejar la base del paquete limpia y sin ambigüedades.
+
+## Steps
+1. Revisar la estructura actual de `backend/app/`.
+2. Confirmar si el archivo correcto del paquete existe como:
+   - `backend/app/__init__.py`
+3. Si existe cualquier inconsistencia de naming o packaging, corregirla.
+4. Revisar y alinear los imports internos del backend para que sean coherentes con la estructura final.
+5. Confirmar cuál es el entrypoint real del backend y dejarlo claro en la documentación.
+6. Revisar el comando de arranque documentado y adaptarlo si fuera necesario.
+7. Validar que los endpoints placeholder actuales siguen funcionando tras el ajuste.
+8. Mantener el cambio pequeño y centrado en higiene estructural, no en nuevas funcionalidades.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/requirements.txt
+- backend/app/__init__.py
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- backend/app/__init__.py
+- backend/app/main.py
+- backend/app/routes.py
+- backend/README.md
+- opcionalmente otros archivos internos del backend si son estrictamente necesarios para alinear imports y entrypoint
+
+## Constraints
+- No añadir integraciones reales.
+- No introducir dependencias nuevas innecesarias.
+- No tocar frontend.
+- No añadir base de datos.
+- No hacer cambios destructivos fuera del alcance del paquete backend.
+- Mantener el backend simple y consistente con la fase actual.
+
+## Validation
+- Existe un archivo de paquete Python correcto en `backend/app/__init__.py`.
+- No quedan referencias ambiguas o incorrectas al package layout.
+- El entrypoint del backend está claro.
+- Los endpoints placeholder actuales siguen respondiendo.
+- La documentación del backend refleja el estado real.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados.
+- Preferir menos de 160 líneas cambiadas.

ai/tasks/done/TASK-010-backend-local-dev-config-and-cors-bootstrap.md

@@ -0,0 +1,55 @@
+# TASK-010-backend-local-dev-config-and-cors-bootstrap
+
+## Goal
+Preparar la configuración mínima de desarrollo local del backend para HLL Vietnam, incluyendo parámetros básicos de ejecución y soporte controlado para consumo desde frontend local durante la fase de desarrollo.
+
+## Context
+El proyecto ya tiene frontend estático y backend placeholder. El siguiente paso para permitir un primer enlace real entre ambos es dejar clara la forma de ejecución local y, si aplica, habilitar el mínimo soporte técnico necesario para consultas desde frontend local, evitando problemas básicos de entorno o de origen cruzado en desarrollo.
+
+## Steps
+1. Revisar cómo se ejecuta actualmente el backend.
+2. Definir y documentar claramente:
+   - host por defecto
+   - puerto por defecto
+   - comando de arranque local
+3. Revisar si el frontend local necesitará consumir el backend desde distinto origen durante desarrollo.
+4. Si hace falta, añadir una solución mínima y controlada para CORS o para origen local de desarrollo, sin sobredimensionar el sistema.
+5. Mantener la configuración simple y enfocada al entorno local.
+6. Actualizar la documentación relevante para que levantar el stack local sea fácil.
+7. No introducir complejidad de producción en esta fase.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- ai/repo-context.md
+- docs/project-overview.md
+- docs/frontend-backend-contract.md
+- backend/README.md
+- backend/app/main.py
+- backend/app/routes.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/main.py
+- opcionalmente un archivo nuevo de configuración mínima si mejora claridad, por ejemplo:
+  - backend/app/config.py
+- opcionalmente documentación raíz si conviene reflejar arranque local combinado
+
+## Constraints
+- No integrar Discord real.
+- No integrar servidores reales.
+- No añadir base de datos.
+- No añadir frameworks nuevos salvo que sean estrictamente necesarios y coherentes con la base ya existente.
+- No tocar el comportamiento visible del frontend todavía.
+- No hacer cambios destructivos.
+- Mantener la configuración pequeña, clara y orientada a desarrollo local.
+
+## Validation
+- El backend tiene host/puerto local claramente definidos o documentados.
+- Existe una forma clara de levantarlo en local.
+- Si el frontend necesita consultar el backend desde otro origen, la solución mínima está resuelta o documentada.
+- El proyecto queda listo para un primer consumo real desde frontend en una task posterior inmediata.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 180 líneas cambiadas.

ai/tasks/done/TASK-011-frontend-health-and-trailer-progressive-enhancement.md

@@ -0,0 +1,60 @@
+# TASK-011-frontend-health-and-trailer-progressive-enhancement
+
+## Goal
+Realizar el primer enlace real entre frontend y backend en HLL Vietnam mediante una mejora progresiva y controlada, consultando el estado del backend y, de forma opcional, el endpoint placeholder del tráiler, sin romper la landing estática actual.
+
+## Context
+La landing actual ya funciona como página estática simple con logo, botón de Discord y tráiler embebido. El backend ya dispone de un bootstrap y de endpoints placeholder. El siguiente ajuste lógico es introducir una mejora progresiva mínima desde `frontend/assets/js/main.js`, manteniendo fallback estático cuando el backend no esté disponible.
+
+## Steps
+1. Revisar el frontend actual y el plan de consumo de datos.
+2. Revisar el backend actual y el contrato frontend-backend.
+3. Preparar en `main.js` una integración mínima con el backend, manteniendo la simplicidad del proyecto.
+4. Consultar al menos:
+   - `GET /health`
+5. Evaluar si también conviene consumir:
+   - `GET /api/trailer`
+   siempre manteniendo fallback estático en el HTML.
+6. Añadir una señal visual mínima, discreta y no intrusiva para reflejar estado del backend si la integración lo justifica.
+7. Asegurar que, si el backend no está disponible, la landing sigue funcionando exactamente como página estática.
+8. No introducir todavía integración real de Discord ni servidores.
+9. Mantener intacta la identidad visual general de la landing.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/frontend-backend-contract.md
+- docs/frontend-data-consumption-plan.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- opcionalmente documentación mínima si fuera necesario reflejar el comportamiento progresivo
+
+## Constraints
+- No rediseñar la landing completa.
+- No añadir nuevas secciones grandes.
+- No integrar Discord real.
+- No integrar servidores reales.
+- No añadir librerías nuevas.
+- No romper el funcionamiento estático actual.
+- No hacer cambios destructivos.
+- Mantener la mejora contenida y reversible.
+
+## Validation
+- La landing sigue funcionando aunque el backend no esté disponible.
+- El frontend puede consultar `/health` correctamente cuando el backend está levantado.
+- El comportamiento visual añadido es discreto y coherente.
+- El tráiler y el botón de Discord siguen funcionando.
+- La solución sienta la base para consumos reales futuros sin introducir complejidad excesiva.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 200 líneas cambiadas.

ai/tasks/done/TASK-012-current-hll-servers-source-plan.md

@@ -0,0 +1,72 @@
+# TASK-012-current-hll-servers-source-plan
+
+## Goal
+Definir la estrategia técnica y de producto para mostrar en la web de HLL Vietnam un bloque provisional de servidores actuales de Hell Let Loose, diferenciándolos claramente del futuro contexto Vietnam y sin implementar todavía integración real definitiva.
+
+## Context
+A día de hoy el foco temático del proyecto es HLL Vietnam, pero todavía no existen servidores reales de ese entorno para consumirlos como fuente del producto. Como solución provisional y útil para la comunidad, se quiere mostrar información de servidores actuales de Hell Let Loose, dejando claro que se trata de servidores del juego actual y no de HLL Vietnam. Antes de construir integración backend o UI final, hay que documentar fuente, campos, límites y estrategia de sustitución futura.
+
+## Steps
+1. Revisar la documentación actual del proyecto y la estrategia de datos ya definida.
+2. Documentar el objetivo del bloque provisional de servidores actuales de HLL.
+3. Definir claramente cómo debe presentarse en producto para evitar confusión con HLL Vietnam.
+4. Identificar qué campos tiene sentido mostrar en esta fase. Incluir al menos:
+   - nombre del servidor
+   - estado online/offline
+   - jugadores actuales
+   - capacidad máxima
+   - mapa actual si está disponible
+   - región o etiqueta útil si existe
+5. Documentar las posibles fuentes de esos datos, distinguiendo entre:
+   - fuente externa pública
+   - datos controlados o placeholder
+   - integración futura más robusta
+6. Documentar riesgos y restricciones:
+   - disponibilidad de terceros
+   - CORS
+   - rate limits
+   - estabilidad del formato
+   - dependencia de scraping o fuentes no oficiales
+7. Proponer una estrategia por fases:
+   - fase 1: payload controlado/mock con forma realista
+   - fase 2: adaptador backend para fuente externa o dataset controlado
+   - fase 3: sustitución por datos más cercanos a HLL Vietnam cuando existan
+8. Dejar claro qué no se implementará todavía.
+9. Actualizar documentación técnica del repositorio para que siguientes tasks tengan base clara.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- docs/frontend-backend-contract.md
+- docs/discord-and-server-data-plan.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+
+## Expected Files to Modify
+- docs/roadmap.md
+- docs/decisions.md
+- ai/architecture-index.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - docs/current-hll-servers-source-plan.md
+
+## Constraints
+- No implementar integración real todavía.
+- No modificar comportamiento visible del frontend.
+- No añadir dependencias nuevas.
+- No tocar base de datos.
+- No hacer cambios destructivos.
+- Mantener el resultado centrado en planificación técnica y de producto.
+
+## Validation
+- Existe una estrategia documentada para mostrar servidores actuales de Hell Let Loose como contenido provisional.
+- Queda claramente diferenciada la identidad de HLL actual frente a HLL Vietnam.
+- Se documentan campos, fuentes, riesgos y fases.
+- La documentación sirve como base directa para una task backend y una task frontend posteriores.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-013-backend-current-hll-servers-placeholder-adapter.md

@@ -0,0 +1,57 @@
+# TASK-013-backend-current-hll-servers-placeholder-adapter
+
+## Goal
+Preparar en el backend Python un adaptador placeholder limpio y consistente para exponer al frontend una lista provisional de servidores actuales de Hell Let Loose, sin integrar todavía una fuente externa real.
+
+## Context
+El backend ya dispone de un esqueleto API y de endpoints placeholder. Se ha decidido que la web podrá mostrar, de forma provisional, servidores actuales de Hell Let Loose mientras no existan datos reales de HLL Vietnam. Antes de conectar fuentes externas, conviene preparar un adaptador backend limpio que devuelva datos controlados con una estructura estable y preparada para sustitución futura.
+
+## Steps
+1. Revisar el backend actual, especialmente el endpoint relacionado con servidores y los payloads placeholder existentes.
+2. Revisar la documentación del contrato frontend-backend y el plan de servidores actuales.
+3. Definir una estructura clara y estable para el payload de servidores actuales de HLL.
+4. Ajustar el backend para que `GET /api/servers` devuelva una respuesta coherente con ese modelo provisional.
+5. Asegurar que el payload distinga claramente que se trata de servidores actuales de Hell Let Loose y no de HLL Vietnam, si esa distinción encaja en el modelo.
+6. Mantener la implementación desacoplada para que más adelante pueda sustituirse la fuente sin romper al frontend.
+7. Actualizar la documentación backend si el comportamiento real del endpoint cambia respecto a lo documentado.
+8. Mantener el alcance estricto: adaptador placeholder estable, no integración real.
+
+## Files to Read First
+- AGENTS.md
+- docs/frontend-backend-contract.md
+- docs/discord-and-server-data-plan.md
+- docs/current-hll-servers-source-plan.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/config.py
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/main.py
+- backend/README.md
+- opcionalmente documentación contractual o técnica si necesita alineación menor
+
+## Constraints
+- No integrar todavía una fuente externa real.
+- No añadir scraping.
+- No añadir base de datos.
+- No tocar frontend en esta task.
+- No introducir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la API simple, estable y preparada para evolución posterior.
+
+## Validation
+- `GET /api/servers` devuelve un payload placeholder más consistente y útil.
+- La respuesta está preparada para consumo frontend.
+- La estructura deja claro que el contenido actual es provisional y basado en servidores actuales de HLL.
+- La documentación backend refleja el estado real del endpoint si cambió.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.

ai/tasks/done/TASK-014-landing-current-hll-servers-panel.md

@@ -0,0 +1,61 @@
+# TASK-014-landing-current-hll-servers-panel
+
+## Goal
+Añadir a la landing de HLL Vietnam un panel visual de servidores actuales de Hell Let Loose, alimentado por el backend placeholder, dejando claro que se trata de contenido provisional mientras no existan datos reales de HLL Vietnam.
+
+## Context
+La landing ya dispone de una mejora progresiva frontend-backend y el backend puede exponer endpoints placeholder. El proyecto necesita empezar a mostrar información más útil y dinámica, pero sin fingir que ya existen servidores de HLL Vietnam. Esta task debe introducir un bloque visual controlado que muestre servidores actuales de HLL como referencia provisional para la comunidad.
+
+## Steps
+1. Revisar la landing actual, los estilos y la mejora progresiva ya implementada en frontend.
+2. Revisar el payload real o previsto de `GET /api/servers`.
+3. Añadir un bloque visual nuevo en la landing para mostrar servidores actuales de Hell Let Loose.
+4. Hacer que el frontend consuma `GET /api/servers` de forma progresiva, manteniendo fallback seguro si el backend no está disponible.
+5. Mostrar de forma clara y ordenada, como mínimo:
+   - nombre del servidor
+   - estado
+   - jugadores
+   - capacidad máxima
+   - mapa si está disponible
+6. Añadir una etiqueta o texto breve que deje claro que son servidores actuales de Hell Let Loose usados como referencia provisional.
+7. Mantener coherencia visual con la identidad militar sobria del proyecto.
+8. Asegurar que la landing siga funcionando si el backend no responde o si no hay datos.
+9. No tocar todavía integración real de Discord ni fuentes externas reales.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/frontend-backend-contract.md
+- docs/frontend-data-consumption-plan.md
+- docs/current-hll-servers-source-plan.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- opcionalmente documentación mínima si fuera necesario reflejar el nuevo bloque
+
+## Constraints
+- No rediseñar completamente la landing.
+- No añadir librerías nuevas.
+- No romper el fallback estático actual.
+- No presentar esos servidores como si fueran de HLL Vietnam.
+- No integrar fuentes externas reales directamente desde frontend.
+- No hacer cambios destructivos.
+- Mantener la mejora acotada, clara y coherente con la fase actual.
+
+## Validation
+- La landing muestra un panel de servidores actuales de HLL de forma clara.
+- El panel obtiene datos desde `GET /api/servers` cuando el backend está disponible.
+- Si el backend no está disponible, la landing sigue funcionando sin romperse.
+- La UI deja claro que se trata de contenido provisional.
+- La integración visual es coherente con el resto de la página.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-015-landing-visual-system-pass.md

@@ -0,0 +1,66 @@
+# TASK-015-landing-visual-system-pass
+
+## Goal
+Realizar una pasada de sistema visual sobre la landing de HLL Vietnam para reforzar identidad, consistencia, contraste y jerarquia general, manteniendo el alcance actual del producto y sin cambiar la arquitectura funcional.
+
+## Context
+La landing ya cuenta con logo, trailer, CTA de Discord, estado de backend y panel provisional de servidores actuales de Hell Let Loose. La base funcional existe, pero ahora hace falta una pasada centrada unicamente en calidad visual para que la web tenga una presentacion mas solida, coherente y atractiva dentro del tono militar/tactico del proyecto.
+
+## Steps
+1. Revisar la composicion visual global de la landing actual.
+2. Revisar la paleta actual, contraste, espaciados, tipografias, contenedores y ritmo vertical.
+3. Refinar el sistema visual general sin redisenar por completo la pagina.
+4. Mejorar:
+   - jerarquia tipografica
+   - espaciado entre bloques
+   - consistencia entre tarjetas y paneles
+   - contraste entre fondo, texto y elementos destacados
+   - sensacion visual militar sobria y cinematografica
+5. Mantener una estetica oscura, tactica y limpia, evitando recargar la pagina.
+6. Asegurar que todos los bloques principales compartan un lenguaje visual coherente.
+7. Validar que el resultado siga funcionando bien en escritorio y movil.
+8. No cambiar el alcance funcional del producto.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/project-overview.md
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+
+## Constraints
+- No anadir nuevas funcionalidades.
+- No cambiar endpoints ni logica backend.
+- No introducir librerias nuevas.
+- No cambiar el flujo funcional de la landing.
+- No reescribir toda la estructura HTML salvo ajustes razonables para mejorar composicion.
+- No hacer cambios destructivos.
+- Mantener el diseno dentro del tono HLL Vietnam.
+
+## Validation
+- La landing tiene una apariencia mas coherente y profesional.
+- La jerarquia visual es mas clara.
+- El contraste y la legibilidad mejoran.
+- La identidad militar/tactica queda reforzada.
+- No se rompe ninguna funcionalidad existente.
+- La landing sigue viendose correctamente en movil y escritorio.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 220 lineas cambiadas.
+
+## Outcome
+- Se reforzo el sistema visual general de la landing sin cambiar su alcance funcional.
+- Se ajusto la jerarquia visual entre hero, panel de trailer y panel de servidores para que compartan mejor lenguaje visual.
+- Se mejoraron contraste, ritmo vertical, bordes, sombras y consistencia de contenedores dentro del tono militar sobrio del proyecto.
+
+## Validation Notes
+- `git diff --name-only -- frontend/index.html frontend/assets/css/styles.css` devuelve solo los archivos esperados por la task.
+- Se reviso el CSS para mantener compatibilidad responsive en escritorio y movil mediante los breakpoints existentes.
+- No se cambiaron endpoints, logica backend ni comportamiento funcional de la landing.
+- No hay pruebas automaticas configuradas para este ajuste visual; la validacion disponible en esta task es revision de alcance y consistencia del marcado y CSS.

ai/tasks/done/TASK-016-hero-logo-and-trailer-cinematic-polish.md

@@ -0,0 +1,73 @@
+# TASK-016-hero-logo-and-trailer-cinematic-polish
+
+## Goal
+Mejorar visualmente el bloque principal de la landing de HLL Vietnam, con foco en hero, logo y trailer, para darle una presencia mas cinematografica, mas inmersiva y mas propia de una comunidad tactica.
+
+## Context
+El usuario quiere priorizar el ajuste visual. El hero actual ya funciona, pero debe ganar impacto sin perder simplicidad. El logo debe sentirse mas protagonista, el bloque del trailer debe integrarse mejor en la composicion y el conjunto debe transmitir mejor el tono del proyecto.
+
+## Steps
+1. Revisar la composicion actual del hero.
+2. Revisar el tratamiento visual del logo:
+   - tamano
+   - posicion
+   - marco
+   - sombra
+   - integracion con el fondo
+3. Revisar el tratamiento visual del trailer:
+   - contenedor
+   - marco
+   - separacion respecto al resto
+   - equilibrio con el CTA y el titulo
+4. Mejorar la presencia del bloque principal sin anadir secciones nuevas.
+5. Reforzar:
+   - impacto inicial
+   - sensacion de identidad
+   - claridad del CTA principal
+   - integracion visual entre logo, titulo y video
+6. Mantener el diseno sobrio, sin caer en efectos exagerados.
+7. Validar que la composicion siga siendo responsive y estable.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+
+## Constraints
+- No cambiar la ruta del logo.
+- No cambiar el enlace de Discord.
+- No cambiar el enlace del trailer.
+- No anadir nuevas funcionalidades.
+- No romper el fallback actual.
+- No usar librerias nuevas.
+- No hacer cambios destructivos.
+- Mantener la landing simple.
+
+## Validation
+- El hero tiene mas presencia visual.
+- El logo se percibe mejor integrado y mas protagonista.
+- El trailer se siente mejor enmarcado dentro del diseno.
+- El CTA sigue siendo claro y visible.
+- El resultado mantiene coherencia con el tono militar/tactico del proyecto.
+- La composicion funciona en desktop y mobile.
+
+## Change Budget
+- Preferir menos de 2 archivos modificados.
+- Preferir menos de 180 lineas cambiadas.
+
+## Outcome
+- Se reorganizo el bloque principal para agrupar mejor estado backend y CTA sin cambiar su funcionamiento.
+- Se reforzo el tratamiento visual del logo con un marco mas trabajado, sombras mas controladas y una mejor integracion con el fondo del hero.
+- Se ajusto el panel de trailer para que se sienta mas cinematografico y mejor conectado con la identidad visual del hero.
+
+## Validation Notes
+- `git diff --name-only -- frontend/index.html frontend/assets/css/styles.css` devuelve solo los archivos esperados por la task.
+- Se confirmo que no se cambiaron la ruta del logo, el enlace de Discord ni la URL del trailer.
+- La task se mantuvo en cambios de composicion y estilo; no se altero el fallback ni la logica existente.
+- No hay pruebas automaticas especificas para esta composicion; la validacion disponible es revision estructural de HTML/CSS y del alcance del diff.

ai/tasks/done/TASK-017-server-panel-visual-polish-and-responsive-pass.md

@@ -0,0 +1,69 @@
+# TASK-017-server-panel-visual-polish-and-responsive-pass
+
+## Goal
+Pulir visualmente el panel de servidores actuales de Hell Let Loose y mejorar su comportamiento responsive para que se integre mejor con el resto de la landing y se vea claro, ordenado y fiable.
+
+## Context
+El panel de servidores ya existe y consume datos del backend placeholder con fallback estatico. Ahora hace falta una pasada especifica de UI para que las tarjetas o elementos del panel tengan una presentacion mas clara y mas profesional, sin tocar todavia estrategia de copy ni fuentes reales de datos.
+
+## Steps
+1. Revisar el marcado actual del panel de servidores en la landing.
+2. Revisar como se renderizan los datos desde frontend.
+3. Mejorar visualmente:
+   - tarjetas o filas de servidor
+   - jerarquia de nombre, estado, jugadores y mapa
+   - badges o indicadores de estado
+   - separacion entre items
+   - integracion con el resto de la landing
+4. Mejorar el comportamiento responsive del panel:
+   - anchuras
+   - apilado
+   - legibilidad en movil
+   - consistencia de espaciados
+5. Mantener claro que se trata de un bloque provisional sin tocar todavia el copy estrategico en profundidad.
+6. Respetar el fallback actual si el backend no responde.
+7. No cambiar el alcance funcional del panel.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+
+## Constraints
+- No cambiar el contrato del backend.
+- No tocar payloads backend.
+- No anadir librerias nuevas.
+- No romper el fallback estatico.
+- No presentar estos servidores como si fueran de HLL Vietnam.
+- No hacer cambios destructivos.
+- Mantener el ajuste centrado en UI y responsive.
+
+## Validation
+- El panel de servidores se ve mas limpio y claro.
+- La lectura de estado, jugadores y mapa mejora.
+- El panel responde bien en movil y escritorio.
+- El fallback sigue funcionando.
+- La integracion visual con la landing es mejor que antes.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 200 lineas cambiadas.
+
+## Outcome
+- Se mejoro la jerarquia visual de cada servidor con identidad, estado mas legible y mejor separacion entre bloques de datos.
+- Se anadio un indicador visual de ocupacion basado en los datos ya disponibles sin cambiar el contrato del backend.
+- Se alineo el markup estatico de `index.html` con el render dinamico de `main.js` para mantener el mismo acabado cuando el backend esta disponible o no.
+
+## Validation Notes
+- `git diff --name-only -- frontend/index.html frontend/assets/css/styles.css frontend/assets/js/main.js` devuelve solo los archivos esperados por la task.
+- `node --check frontend\\assets\\js\\main.js` se ejecuto correctamente.
+- No se modifico `backend/app/payloads.py` ni el contrato del backend.
+- El fallback estatico se conserva porque el HTML base y el render dinamico usan la misma estructura visual del panel.

ai/tasks/done/TASK-018-current-hll-data-ingestion-plan.md

@@ -0,0 +1,74 @@
+# TASK-018-current-hll-data-ingestion-plan
+
+## Goal
+Definir la estrategia técnica de ingesta de datos para Hell Let Loose actual, usándolo como banco de pruebas del proyecto HLL Vietnam, con foco en servidores, snapshots e históricos básicos sin implementar todavía la ingesta real completa.
+
+## Context
+La landing ya muestra servidores actuales de HLL como contenido provisional y el backend ya dispone de una base API placeholder. El siguiente paso lógico es fijar cómo se obtendrán y normalizarán datos reales o semirrealistas de HLL actual para validar la arquitectura que más adelante podrá reutilizarse con HLL Vietnam.
+
+## Steps
+1. Revisar la documentación actual del proyecto relacionada con servidores, backend y evolución de datos.
+2. Definir qué tipos de datos se quieren ingerir inicialmente desde HLL actual. Incluir al menos:
+   - listado de servidores
+   - estado online/offline
+   - jugadores actuales
+   - capacidad máxima
+   - mapa actual si está disponible
+   - timestamp de captura
+3. Definir el concepto de snapshot de servidor y cómo se usará para construir histórico.
+4. Documentar las posibles fuentes técnicas de ingesta para HLL actual, distinguiendo entre:
+   - datos controlados/mock
+   - fuente externa pública
+   - consulta directa de servidor o capa intermedia
+5. Documentar riesgos y límites:
+   - disponibilidad de terceros
+   - cambios de formato
+   - rate limits
+   - latencia
+   - CORS
+   - fiabilidad de datos
+   - dependencia de scraping o APIs no oficiales
+6. Proponer la arquitectura de ingesta por fases:
+   - fase 1: payload controlado y estructura estable
+   - fase 2: colector de snapshots con fuente real o casi real
+   - fase 3: explotación histórica y estadísticas básicas
+7. Dejar claro qué no se implementará todavía.
+8. Actualizar la documentación técnica del repositorio para servir de base a las siguientes tasks de base de datos y colector.
+
+## Files to Read First
+- README.md
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- docs/discord-and-server-data-plan.md
+- docs/current-hll-servers-source-plan.md
+- docs/frontend-backend-contract.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+
+## Expected Files to Modify
+- docs/roadmap.md
+- docs/decisions.md
+- ai/architecture-index.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - docs/current-hll-data-ingestion-plan.md
+
+## Constraints
+- No implementar todavía ingesta real.
+- No modificar comportamiento visible del frontend.
+- No añadir base de datos funcional en esta task.
+- No añadir dependencias nuevas.
+- No hacer cambios destructivos.
+- Mantener el resultado centrado en planificación técnica reutilizable para futuro HLL Vietnam.
+
+## Validation
+- Existe una estrategia documentada de ingesta para HLL actual como banco de pruebas.
+- Quedan definidos snapshots, fuentes posibles, riesgos y fases.
+- La documentación deja claro cómo se conectará este trabajo con almacenamiento e históricos.
+- La base sirve para una siguiente task de esquema de base de datos.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.

ai/tasks/done/TASK-019-stats-database-schema-foundation.md

@@ -0,0 +1,65 @@
+# TASK-019-stats-database-schema-foundation
+
+## Goal
+Diseñar y dejar preparada la base del esquema de almacenamiento para snapshots y estadísticas iniciales de servidores de HLL actual, con una modelización genérica que pueda reutilizarse en el futuro para HLL Vietnam.
+
+## Context
+El proyecto necesita pasar de payloads placeholder a una arquitectura capaz de almacenar históricos. Antes de implementar colectores reales, es necesario definir un esquema de datos claro, neutro y extensible para snapshots de servidores y primeras métricas agregadas.
+
+## Steps
+1. Revisar la documentación técnica actual sobre backend, contratos y plan de ingesta.
+2. Definir las entidades mínimas necesarias para la primera fase de persistencia. Incluir al menos:
+   - game o source context si aplica
+   - servers
+   - server_snapshots
+   - posibles tablas de agregación inicial o vistas documentadas para estadísticas
+3. Asegurar que el naming sea genérico y reutilizable, evitando acoplar el modelo a Vietnam.
+4. Definir para cada entidad:
+   - propósito
+   - campos principales
+   - claves
+   - relaciones
+   - timestamps
+5. Documentar qué datos deben persistirse por snapshot y cuáles pueden derivarse después.
+6. Si el backend ya usa o prevé una tecnología concreta para persistencia, reflejarlo con claridad. Si aún no, documentar una base neutra y coherente.
+7. Añadir o actualizar documentación técnica del repositorio para dejar claro el modelo inicial de almacenamiento.
+8. Mantener el alcance en diseño y preparación, no en implementación completa de persistencia productiva.
+
+## Files to Read First
+- AGENTS.md
+- docs/project-overview.md
+- docs/roadmap.md
+- docs/decisions.md
+- docs/frontend-backend-contract.md
+- docs/current-hll-data-ingestion-plan.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/main.py
+
+## Expected Files to Modify
+- docs/decisions.md
+- ai/architecture-index.md
+- backend/README.md
+- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
+  - docs/stats-database-schema-foundation.md
+- opcionalmente archivos base de estructura si el repositorio ya está preparado para ello, pero sin implementar una base de datos completa
+
+## Constraints
+- No implementar todavía la base de datos completa.
+- No añadir migraciones productivas si la decisión técnica aún no está consolidada.
+- No tocar frontend.
+- No añadir integraciones reales de servidor.
+- No hacer cambios destructivos.
+- Mantener el modelo simple, genérico y preparado para crecer.
+
+## Validation
+- Existe un esquema de almacenamiento inicial claro para snapshots y estadísticas básicas.
+- El naming es reutilizable para HLL actual y futuro HLL Vietnam.
+- La documentación deja claro qué se persistirá primero y por qué.
+- El resultado sirve como base directa para una siguiente task de colector de snapshots.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 220 líneas cambiadas.

ai/tasks/done/TASK-020-server-snapshot-collector-bootstrap.md

@@ -0,0 +1,61 @@
+# TASK-020-server-snapshot-collector-bootstrap
+
+## Goal
+Preparar un bootstrap técnico mínimo para un colector de snapshots de servidores en el backend Python, dejando la estructura lista para capturar y normalizar datos de HLL actual sin implementar todavía una ingesta completa de producción.
+
+## Context
+Tras definir la estrategia de ingesta y el esquema base de almacenamiento, el siguiente paso es dejar preparada la estructura mínima de un colector en backend. Esta task no debe resolver toda la persistencia ni depender de una fuente definitiva, pero sí debe sentar la base para un flujo futuro de captura periódica.
+
+## Steps
+1. Revisar la documentación de ingesta y esquema de almacenamiento.
+2. Revisar la estructura actual del backend Python.
+3. Crear una estructura mínima y clara para un colector o servicio de snapshots dentro de `backend/app/`.
+4. Definir interfaces o funciones base para:
+   - obtener datos crudos de una fuente
+   - normalizar esos datos
+   - producir un snapshot consistente
+5. Si encaja con la fase actual, permitir una ejecución manual o de desarrollo del colector usando datos controlados.
+6. Mantener la implementación desacoplada para que la fuente real pueda sustituirse más adelante sin romper el resto del backend.
+7. Actualizar la documentación backend para explicar el papel del colector y cómo encaja con futuras estadísticas.
+8. Mantener el alcance estricto: bootstrap técnico del colector, no pipeline completo de producción.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/current-hll-data-ingestion-plan.md
+- docs/stats-database-schema-foundation.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/config.py
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/__init__.py
+- opcionalmente archivos nuevos dentro de `backend/app/` si mejoran claridad, por ejemplo:
+  - backend/app/collector.py
+  - backend/app/normalizers.py
+  - backend/app/snapshots.py
+- opcionalmente documentación técnica relacionada si requiere alineación menor
+
+## Constraints
+- No implementar todavía una ingesta real completa.
+- No depender de scraping productivo.
+- No introducir una base de datos completa en esta task.
+- No tocar frontend.
+- No añadir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la estructura clara y pequeña.
+
+## Validation
+- El backend contiene una base mínima para un colector de snapshots.
+- La estructura separa captura, normalización y snapshot de forma razonable para la fase actual.
+- La documentación backend refleja el nuevo estado.
+- El resultado prepara el terreno para una siguiente task de persistencia real o ejecución periódica.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.

ai/tasks/done/TASK-021-snapshot-persistence-bootstrap.md

@@ -0,0 +1,73 @@
+# TASK-021-snapshot-persistence-bootstrap
+
+## Goal
+Preparar una persistencia local minima para snapshots de servidores en el backend Python, de forma que los datos recogidos durante las pruebas con HLL actual puedan guardarse y reutilizarse para consultas historicas posteriores.
+
+## Context
+El proyecto ya dispone de plan de ingesta, modelo logico de almacenamiento y bootstrap de colector. El siguiente paso es dejar de depender exclusivamente de estructuras temporales o payloads controlados y empezar a guardar snapshots de forma persistente para validar el circuito real de estadisticas.
+
+## Steps
+1. Revisar la documentacion actual de ingesta, esquema logico y colector.
+2. Definir una estrategia de persistencia local minima adecuada para esta fase de pruebas.
+3. Implementar una capa pequena de persistencia alineada con las entidades ya definidas logicamente:
+   - game_sources
+   - servers
+   - server_snapshots
+4. Mantener la implementacion simple, reutilizable y desacoplada de una base de datos de produccion futura.
+5. Hacer que el colector pueda guardar snapshots reales o controlados en esa persistencia local.
+6. Documentar como inicializar y usar esta persistencia en desarrollo.
+7. No introducir todavia consultas historicas complejas ni visualizacion en frontend.
+8. Mantener el alcance centrado en almacenamiento basico funcional.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/current-hll-data-ingestion-plan.md
+- docs/stats-database-schema-foundation.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/snapshots.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/snapshots.py
+- opcionalmente archivos nuevos dentro de backend/app/ si mejoran la separacion de persistencia, por ejemplo:
+  - backend/app/storage.py
+  - backend/app/repository.py
+
+## Constraints
+- No implementar todavia integraciones reales complejas de terceros.
+- No tocar frontend.
+- No anadir una infraestructura de produccion sobredimensionada.
+- No hacer cambios destructivos.
+- Mantener la persistencia simple y util para desarrollo local.
+
+## Validation
+- El backend puede guardar snapshots de servidores en una persistencia local real.
+- La persistencia sigue el modelo logico documentado.
+- La documentacion explica como usar esta base minima en local.
+- El resultado prepara el terreno para consultas historicas inmediatas.
+
+## Change Budget
+- Preferir menos de 7 archivos modificados o creados.
+- Preferir menos de 260 lineas cambiadas.
+
+## Outcome
+- Se anadio `backend/app/storage.py` con una persistencia SQLite minima basada en libreria estandar.
+- El colector puede persistir snapshots controlados en `game_sources`, `servers` y `server_snapshots`.
+- La configuracion local expone `HLL_BACKEND_STORAGE_PATH` para cambiar la ruta del archivo SQLite sin fijar una decision de produccion.
+- `backend/README.md` documenta la inicializacion y uso de la persistencia local.
+
+## Validation Result
+- Ejecutado: `python -m app.collector`
+- Resultado: lote de 3 snapshots persistido correctamente en SQLite local de desarrollo.
+
+## Decision Notes
+- Se eligio SQLite porque cubre persistencia local real con dependencias cero y mantiene abierta la migracion futura a otra tecnologia de almacenamiento.

ai/tasks/done/TASK-022-historical-server-query-api.md

@@ -0,0 +1,77 @@
+# TASK-022-historical-server-query-api
+
+## Goal
+Exponer desde el backend una primera API de consulta historica para snapshots de servidores, permitiendo recuperar el ultimo estado conocido y una evolucion basica a partir de la persistencia local ya preparada.
+
+## Context
+Una vez que los snapshots puedan guardarse, el siguiente paso es poder consultarlos de forma estructurada. Esta task debe convertir la persistencia inicial en una API util para comprobar que el flujo de estadisticas ya funciona extremo a extremo.
+
+## Steps
+1. Revisar la capa de persistencia de snapshots y el backend actual.
+2. Definir endpoints minimos de consulta historica, por ejemplo:
+   - `GET /api/servers/latest`
+   - `GET /api/servers/history`
+   - `GET /api/servers/{id}/history`
+3. Alinear el formato de respuesta con las convenciones del backend existente.
+4. Hacer que las respuestas devuelvan como minimo:
+   - timestamps
+   - ultimo estado conocido
+   - jugadores
+   - capacidad
+   - mapa si esta disponible
+   - contexto o fuente si aplica
+5. Mantener la implementacion simple y enfocada a validacion tecnica.
+6. Actualizar la documentacion del backend y del contrato si fuera necesario.
+7. No introducir todavia analitica avanzada ni agregaciones pesadas.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/frontend-backend-contract.md
+- docs/current-hll-data-ingestion-plan.md
+- docs/stats-database-schema-foundation.md
+- backend/README.md
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/collector.py
+- backend/app/snapshots.py
+- archivos de persistencia creados en la task anterior
+
+## Expected Files to Modify
+- backend/app/main.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/README.md
+- opcionalmente documentacion tecnica contractual si requiere alineacion menor
+
+## Constraints
+- No tocar frontend en esta task.
+- No anadir visualizacion nueva.
+- No introducir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la API clara, estable y centrada en historico basico.
+
+## Validation
+- Existen endpoints historicos minimos funcionales.
+- El backend puede devolver ultimo snapshot y una historia basica de snapshots.
+- La documentacion refleja correctamente el nuevo estado.
+- El resultado prepara el terreno para una primera visualizacion en frontend.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 lineas cambiadas.
+
+## Outcome
+- Se anadieron lecturas minimas desde SQLite para ultimo snapshot por servidor, historial agregado e historial por servidor.
+- `backend/app/routes.py` resuelve `GET /api/servers/latest`, `GET /api/servers/history` y `GET /api/servers/{id}/history`.
+- `backend/app/payloads.py` mantiene el formato JSON del backend y devuelve errores controlados para parametros invalidos.
+- `backend/README.md` y `docs/frontend-backend-contract.md` documentan los nuevos endpoints.
+
+## Validation Result
+- Ejecutado: `python -c "from app.collector import collect_server_snapshots; from app.routes import resolve_get_payload; collect_server_snapshots(persist=True); ..."`
+- Resultado: los tres endpoints historicos devolvieron datos persistidos y `limit=999` respondio con `status: "error"`.
+
+## Decision Notes
+- Se mantuvo la API sobre la persistencia SQLite local ya existente, evitando una capa analitica separada hasta que el frontend necesite algo mas que consultas historicas basicas.

ai/tasks/done/TASK-023-server-stats-preview-panel.md

@@ -0,0 +1,68 @@
+# TASK-023-server-stats-preview-panel
+
+## Goal
+Anadir a la web una primera visualizacion de estadisticas de servidores basada en datos persistidos, mostrando una vista previa util y controlada del historico sin convertir todavia la landing en una aplicacion compleja.
+
+## Context
+La landing ya dispone de un panel provisional de servidores y el backend va a disponer de persistencia local y consultas historicas minimas. Esta task debe conectar ambos mundos con una primera visualizacion ligera que confirme que el pipeline completo funciona.
+
+## Steps
+1. Revisar el frontend actual, el panel de servidores existente y el plan de consumo de datos.
+2. Revisar los nuevos endpoints historicos del backend.
+3. Disenar una mejora progresiva en frontend que pueda mostrar una vista previa de estadisticas sin romper la landing actual.
+4. Mostrar como minimo algunos indicadores utiles, por ejemplo:
+   - ultimo snapshot por servidor
+   - hora de ultima actualizacion
+   - evolucion basica de poblacion o actividad reciente
+5. Mantener fallback seguro si el backend o los endpoints historicos no estan disponibles.
+6. Integrar visualmente el bloque con el diseno actual sin redisenar toda la pagina.
+7. No anadir todavia dashboards complejos, graficas pesadas ni navegacion nueva.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/frontend-data-consumption-plan.md
+- docs/frontend-backend-contract.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/routes.py
+- backend/app/payloads.py
+- documentacion de endpoints historicos creada en la task anterior
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- opcionalmente documentacion minima si fuera necesario reflejar el nuevo bloque o comportamiento
+
+## Constraints
+- No redisenar completamente la landing.
+- No anadir librerias nuevas.
+- No romper el fallback actual.
+- No introducir analitica visual compleja.
+- No hacer cambios destructivos.
+- Mantener la mejora contenida, clara y alineada con la fase actual.
+
+## Validation
+- La web puede mostrar una primera vista previa de estadisticas de servidores usando datos persistidos.
+- El frontend sigue funcionando si el backend no esta disponible.
+- La mejora visual se integra con la landing actual.
+- El resultado demuestra que el flujo captura -> persistencia -> consulta -> visualizacion ya funciona.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 220 lineas cambiadas.
+
+## Outcome
+- El panel de servidores ahora puede mostrar una vista previa historica con resumen, ultima actualizacion y tendencia reciente por servidor.
+- `frontend/assets/js/main.js` mantiene el bloque estatico como fallback y solo sustituye el contenido cuando los endpoints historicos responden correctamente.
+- `frontend/index.html` anade un contenedor ligero para el resumen historico.
+- `frontend/assets/css/styles.css` integra la nueva vista previa con el lenguaje visual tactico existente.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`
+- Resultado: sintaxis valida en el script principal del frontend.
+
+## Decision Notes
+- Se mantuvo la mejora dentro del panel de servidores ya existente para evitar una nueva seccion o un dashboard separado en esta fase.

ai/tasks/done/TASK-024-a2s-client-bootstrap.md

@@ -0,0 +1,77 @@
+# TASK-024-a2s-client-bootstrap
+
+## Goal
+Preparar un cliente A2S mínimo en el backend Python para consultar servidores de Hell Let Loose actual mediante query pública, obteniendo metadata básica reutilizable por el colector de snapshots.
+
+## Context
+El proyecto ya dispone de colector bootstrap, persistencia local y consultas históricas mínimas. El siguiente paso es introducir una fuente real de datos en vivo. Hell Let Loose usa Steam A2S para metadata de servidor a través del query port, por lo que esta task debe preparar la base técnica para consultar servidores reales sin depender todavía de integraciones administrativas o scoreboards avanzados.
+
+## Steps
+1. Revisar el backend actual, especialmente el colector y las funciones de normalización.
+2. Revisar la documentación técnica de ingesta y el modelo de snapshots.
+3. Preparar un cliente A2S mínimo capaz de consultar al menos la información equivalente a:
+   - nombre del servidor
+   - mapa actual
+   - jugadores actuales
+   - capacidad máxima
+4. Mantener la implementación desacoplada para que futuras consultas de players o rules puedan añadirse después sin romper la base.
+5. Normalizar la salida del cliente A2S hacia el modelo interno ya usado por el proyecto.
+6. Asegurar que la implementación maneje fallos básicos de red o timeouts de forma controlada.
+7. Actualizar la documentación backend para reflejar que existe una fuente A2S real de prueba.
+8. Mantener el alcance centrado en bootstrap del cliente, no en pipeline completo.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/current-hll-data-ingestion-plan.md
+- docs/stats-database-schema-foundation.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/snapshots.py
+- backend/app/storage.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/normalizers.py
+- backend/app/collector.py
+- opcionalmente archivos nuevos dentro de backend/app/ si mejoran claridad, por ejemplo:
+  - backend/app/a2s_client.py
+  - backend/app/a2s_protocol.py
+
+## Constraints
+- No implementar todavía scraping de terceros.
+- No tocar frontend.
+- No añadir base de datos nueva.
+- No hacer cambios destructivos.
+- Mantener la implementación pequeña, clara y orientada a desarrollo local.
+
+## Validation
+- Existe un cliente A2S mínimo reutilizable desde el backend.
+- El cliente puede obtener metadata básica de servidor.
+- La salida se normaliza al modelo interno del proyecto.
+- La documentación backend refleja el nuevo estado.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 260 líneas cambiadas.
+
+## Outcome
+- Se anadio un cliente A2S minimo en `backend/app/a2s_client.py` usando solo libreria estandar para consultar `A2S_INFO`.
+- `backend/app/normalizers.py` ahora puede convertir una respuesta A2S al modelo interno de snapshots ya usado por el proyecto.
+- `backend/app/collector.py` expone `fetch_a2s_probe()` como adaptador pequeno reutilizable para la siguiente task de integracion del pipeline.
+- `backend/app/__init__.py` mantiene acceso ligero a `query_server_info()` y `fetch_a2s_probe()` sin acoplar la carga del paquete al CLI del cliente.
+- `backend/README.md` documenta el nuevo estado y una prueba manual local del cliente.
+
+## Validation Result
+- Ejecutado: `python -m compileall backend/app`
+- Resultado: compilacion correcta de los modulos del backend.
+- Ejecutado: `python -m app.a2s_client --help`
+- Resultado: CLI disponible sin warnings y con los argumentos esperados.
+
+## Decision Notes
+- Se mantuvo la implementacion en libreria estandar con UDP directo para evitar introducir dependencias antes de validar targets y configuracion en las siguientes tasks.

ai/tasks/done/TASK-025-a2s-source-configuration-and-target-registry.md

@@ -0,0 +1,67 @@
+# TASK-025-a2s-source-configuration-and-target-registry
+
+## Goal
+Definir y preparar una configuración limpia para registrar servidores objetivo de prueba consultables por A2S, de forma que el backend pueda trabajar con una lista controlada de targets sin acoplarse a valores hardcodeados.
+
+## Context
+Una vez que exista un cliente A2S mínimo, el proyecto necesita una manera clara de declarar qué servidores de HLL actual se usarán como fuentes de prueba. Esta task debe dejar preparada una configuración o registro simple de targets A2S, reutilizable por el colector y fácil de adaptar en desarrollo.
+
+## Steps
+1. Revisar la configuración actual del backend.
+2. Definir una forma clara de registrar targets A2S de prueba, incluyendo al menos:
+   - nombre amigable
+   - host o IP
+   - query port
+   - contexto o etiqueta de fuente
+3. Mantener el diseño desacoplado del resto del backend y fácil de ampliar.
+4. Permitir que el colector lea esa configuración sin depender de valores hardcodeados dentro de la lógica principal.
+5. Documentar cómo añadir, quitar o modificar servidores de prueba en entorno local.
+6. Mantener el alcance en configuración y registro de targets, no en analítica avanzada.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/current-hll-data-ingestion-plan.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/storage.py
+- backend/app/a2s_client.py si ya existe por la task anterior
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/config.py
+- backend/app/collector.py
+- opcionalmente archivos nuevos dentro de backend/app/ si mejoran claridad, por ejemplo:
+  - backend/app/server_targets.py
+
+## Constraints
+- No tocar frontend.
+- No introducir infraestructura compleja.
+- No añadir dependencias innecesarias.
+- No hacer cambios destructivos.
+- Mantener la configuración simple y orientada a pruebas.
+
+## Validation
+- El backend dispone de una lista configurable de targets A2S.
+- El colector puede leer esos targets sin depender de constantes dispersas.
+- La documentación deja claro cómo configurar servidores de prueba.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 180 líneas cambiadas.
+
+## Outcome
+- Se anadio `backend/app/server_targets.py` con un registro pequeno de targets A2S y una carga desacoplada en forma de dataclass.
+- `backend/app/config.py` ahora soporta `HLL_BACKEND_A2S_TARGETS` para sobrescribir la lista con un array JSON en desarrollo local.
+- `backend/app/collector.py` puede resolver los targets configurados mediante `fetch_configured_a2s_probes()` sin depender de valores hardcodeados en su logica principal.
+- `backend/README.md` documenta la ubicacion del registro y como anadir, quitar o modificar targets de prueba.
+
+## Validation Result
+- Ejecutado: `python -m compileall backend/app`
+- Resultado: compilacion correcta de los modulos del backend.
+- Ejecutado: `python -c "from app.server_targets import load_a2s_targets; print(load_a2s_targets())"`
+- Resultado: el registro carga el target por defecto con la estructura esperada.
+
+## Decision Notes
+- Se eligio JSON en variable de entorno para mantener el override simple, local y sin introducir un nuevo formato de configuracion ni dependencias externas.

ai/tasks/done/TASK-026-a2s-backed-snapshot-collection.md

@@ -0,0 +1,74 @@
+# TASK-026-a2s-backed-snapshot-collection
+
+## Goal
+Hacer que el colector de snapshots del backend pueda capturar datos reales desde servidores HLL consultables por A2S y persistir esos snapshots en la base local ya preparada.
+
+## Context
+El proyecto ya tiene persistencia local, consultas históricas mínimas y un bootstrap de colector. Tras introducir un cliente A2S y una configuración de targets, el siguiente paso es cerrar el primer flujo real de captura y persistencia sobre servidores actuales de HLL.
+
+## Steps
+1. Revisar el colector actual, la persistencia local y el cliente A2S.
+2. Integrar el cliente A2S dentro del flujo de colecta de snapshots.
+3. Hacer que el colector capture datos desde los targets configurados y los normalice al modelo interno.
+4. Persistir los snapshots reales usando la capa de almacenamiento ya existente.
+5. Manejar de forma controlada los casos de timeout, servidor inaccesible o respuesta inválida.
+6. Mantener la posibilidad de usar datos controlados o fallback de desarrollo si la fuente real no responde.
+7. Actualizar la documentación backend para explicar el flujo de captura real en esta fase.
+8. Mantener el alcance centrado en captura y persistencia, no en nuevas visualizaciones.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- docs/current-hll-data-ingestion-plan.md
+- docs/stats-database-schema-foundation.md
+- backend/README.md
+- backend/app/__init__.py
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/snapshots.py
+- backend/app/storage.py
+- backend/app/a2s_client.py
+- backend/app/server_targets.py si existe
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/storage.py
+- opcionalmente archivos auxiliares nuevos si son estrictamente necesarios para mantener claridad
+
+## Constraints
+- No tocar frontend en esta task.
+- No introducir todavía estadísticas complejas.
+- No añadir scraping de terceros.
+- No hacer cambios destructivos.
+- Mantener el pipeline claro, comprobable y pequeño.
+
+## Validation
+- El colector puede capturar snapshots reales desde al menos un target A2S configurado.
+- Los snapshots se persisten en la base local actual.
+- Los errores de consulta quedan manejados de forma razonable.
+- La documentación backend refleja cómo ejecutar esta captura en local.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados o creados.
+- Preferir menos de 240 líneas cambiadas.
+
+## Outcome
+- `backend/app/collector.py` ahora puede ejecutar captura en modo `a2s`, `controlled` o `auto`, persistiendo snapshots reales cuando las consultas A2S tienen exito.
+- El colector registra errores por target sin abortar todo el lote y usa fallback controlado cuando no obtiene respuestas reales y el fallback esta habilitado.
+- `backend/app/storage.py` persiste `source_name` por snapshot para conservar la procedencia efectiva de cada captura.
+- `backend/README.md` documenta como ejecutar captura real, captura controlada y captura automatica con fallback en local.
+
+## Validation Result
+- Ejecutado: `python -m compileall backend/app`
+- Resultado: compilacion correcta de los modulos del backend.
+- Ejecutado: validacion con `collect_server_snapshots(source_mode="a2s", persist=True, probe_target=stub_probe)` sobre SQLite temporal.
+- Resultado: flujo A2S simulado persistio 1 snapshot y `list_snapshot_history()` devolvio 1 registro.
+- Ejecutado: validacion con `collect_server_snapshots(source_mode="auto", timeout=0.1, persist=True)` usando el target local por defecto.
+- Resultado: el colector registro 1 error de consulta, activo fallback controlado y persistio 3 snapshots de desarrollo.
+
+## Decision Notes
+- Se mantuvo un fallback explicito de desarrollo para no romper el flujo local mientras los targets A2S reales siguen siendo configurables y potencialmente inestables.

ai/tasks/done/TASK-027-a2s-history-visibility-polish.md

@@ -0,0 +1,61 @@
+# TASK-027-a2s-history-visibility-polish
+
+## Goal
+Ajustar la capa de visualización actual para que la web pueda distinguir de forma clara cuándo muestra datos históricos procedentes de snapshots A2S reales frente a placeholders o fallbacks estáticos.
+
+## Context
+Una vez que la captura A2S real esté operativa, conviene hacer visible en frontend la procedencia efectiva de los datos sin convertir la landing en un dashboard complejo. Esta task debe mejorar la claridad del bloque actual de servidores y estadísticas sin rediseñarlo completamente.
+
+## Steps
+1. Revisar el frontend actual y el bloque de estadísticas/servidores existente.
+2. Revisar el formato real de los endpoints históricos tras la integración A2S.
+3. Añadir una mejora visual o de estado que permita reflejar claramente si los datos mostrados son:
+   - snapshots reales recientes
+   - datos persistidos antiguos
+   - fallback estático
+4. Mantener la mejora discreta y coherente con la landing actual.
+5. No convertir la página en una aplicación compleja ni añadir navegación nueva.
+6. Preservar el fallback si el backend no está disponible.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- docs/frontend-data-consumption-plan.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No rediseñar toda la landing.
+- No añadir librerías nuevas.
+- No tocar backend salvo referencias documentales mínimas si hicieran falta.
+- No hacer cambios destructivos.
+- Mantener la mejora contenida y alineada con la fase actual.
+
+## Validation
+- La web distingue visualmente entre datos reales A2S, históricos persistidos y fallback estático cuando aplique.
+- La integración visual sigue siendo coherente con la landing.
+- El frontend sigue funcionando si el backend no responde.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+
+## Outcome
+- `frontend/index.html` incorpora un bloque pequeno de procedencia para explicar si el panel muestra fallback estatico, historico persistido o snapshots A2S recientes.
+- `frontend/assets/js/main.js` clasifica el estado visible segun la procedencia y la antiguedad de los snapshots historicos sin romper el fallback actual.
+- `frontend/assets/css/styles.css` integra esos estados con una presentacion tactica discreta dentro del panel existente de servidores.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`
+- Resultado: sintaxis valida en el script principal del frontend.
+
+## Decision Notes
+- La distincion entre `snapshots A2S recientes` y `historico persistido` se resuelve de forma ligera usando `source_name` y la antiguedad de `captured_at`, evitando cambios de contrato backend en esta fase.

ai/tasks/done/TASK-028-real-a2s-target-onboarding.md

@@ -0,0 +1,72 @@
+# TASK-028-real-a2s-target-onboarding
+
+## Goal
+Dar de alta el primer target A2S real verificado del proyecto, correspondiente a Comunidad Hispana #01, integrandolo en la configuracion del backend de forma clara, mantenible y documentada.
+
+## Context
+El backend ya dispone de cliente A2S, registro configurable de targets y colector integrado con persistencia. Ademas, ya se ha identificado un target real consultable por A2S:
+- Comunidad Hispana #01
+- Host/IP: 152.114.195.174
+- Query Port: 7778
+- Game Port: 7777
+
+El objetivo de esta task es incorporar ese target real a la configuracion del proyecto sin asumir otros servidores aun no verificados.
+
+## Steps
+1. Revisar la configuracion actual de targets A2S del backend.
+2. Anadir el target real verificado de Comunidad Hispana #01 usando:
+   - nombre amigable claro
+   - host/IP: `152.114.195.174`
+   - query port: `7778`
+   - etiqueta o contexto de fuente coherente con el proyecto
+3. Asegurar que la configuracion no dependa de valores hardcodeados dispersos fuera del registro o capa configurada.
+4. Mantener separada la nocion de query port y game port para evitar confusiones.
+5. Reflejar en la documentacion del backend como esta registrado este primer target real.
+6. Dejar claro en documentacion que Comunidad Hispana #02 no debe anadirse aun sin confirmar su query port real.
+7. Mantener el cambio pequeno y estrictamente centrado en onboarding de target.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/server_targets.py
+- backend/app/collector.py
+- backend/app/a2s_client.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/config.py
+- backend/app/server_targets.py
+- opcionalmente backend/app/collector.py si necesita alineacion menor para consumir el target de forma limpia
+
+## Constraints
+- No tocar frontend.
+- No introducir nuevos targets no verificados.
+- No asumir datos de Comunidad Hispana #02.
+- No anadir scraping.
+- No hacer cambios destructivos.
+- Mantener la configuracion simple y clara.
+
+## Validation
+- El backend contiene el target real de Comunidad Hispana #01 correctamente registrado.
+- El query port configurado es `7778`.
+- La documentacion deja claro como esta definido este target.
+- No se han introducido targets inciertos o ambiguos.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 140 lineas cambiadas.
+
+## Outcome
+- `backend/app/server_targets.py` registra por defecto solo `Comunidad Hispana #01` con `host` real, `query_port` verificado y `game_port` separado como dato opcional de referencia.
+- `backend/app/config.py` centraliza el `source_name` por defecto para evitar valores dispersos en el registro A2S.
+- `backend/README.md` documenta el target real incorporado y deja explicito que Comunidad Hispana #02 no debe anadirse hasta confirmar su `query_port`.
+
+## Validation Result
+- Ejecutado desde `backend/`: `python -` importando `load_a2s_targets()`.
+- Resultado: el registro carga `Comunidad Hispana #01` con `host=152.114.195.174`, `query_port=7778`, `game_port=7777` y `source_name=community-hispana-a2s`.
+
+## Decision Notes
+- Se mantiene `game_port` fuera de la logica de consulta A2S y solo como metadato opcional del target para evitar confundirlo con `query_port`.

ai/tasks/done/TASK-029-real-a2s-capture-validation.md

@@ -0,0 +1,86 @@
+# TASK-029-real-a2s-capture-validation
+
+## Goal
+Validar una captura A2S real extremo a extremo contra Comunidad Hispana #01, confirmando que el colector puede consultar el servidor, normalizar la respuesta y persistir snapshots utiles en la base local.
+
+## Context
+El proyecto ya tiene:
+- cliente A2S
+- targets configurables
+- persistencia local
+- endpoints historicos
+- primer target real verificado para Comunidad Hispana #01
+
+Ahora hay que comprobar que el flujo real funciona de verdad con ese servidor:
+A2S -> colector -> persistencia local
+
+## Steps
+1. Revisar el target real configurado para Comunidad Hispana #01.
+2. Ejecutar el colector o flujo equivalente contra ese target real.
+3. Confirmar que el backend consulta correctamente el host `152.114.195.174` con query port `7778`.
+4. Validar que la respuesta A2S obtenida se normaliza al modelo interno del proyecto.
+5. Persistir al menos un snapshot real en la base local actual.
+6. Verificar que se registran de forma razonable:
+   - nombre del servidor
+   - timestamp de captura
+   - mapa actual si esta disponible
+   - jugadores actuales
+   - capacidad maxima
+   - procedencia efectiva del snapshot
+7. Verificar el comportamiento si la consulta falla, timeout o devuelve datos parciales.
+8. Actualizar la documentacion minima necesaria sobre como ejecutar esta validacion en local.
+9. Mantener el alcance centrado en validacion del flujo real, no en nuevas features.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/a2s_client.py
+- backend/app/server_targets.py
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/snapshots.py
+- backend/app/storage.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/storage.py
+- opcionalmente otros archivos backend si son estrictamente necesarios para una captura real robusta
+
+## Constraints
+- No tocar frontend.
+- No anadir analitica avanzada.
+- No anadir scraping de terceros.
+- No introducir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la validacion centrada en Comunidad Hispana #01.
+
+## Validation
+- Se realiza una captura real A2S sobre Comunidad Hispana #01.
+- Se persiste al menos un snapshot real en la base local.
+- El flujo real queda documentado y es repetible en local.
+- Los errores de consulta estan razonablemente manejados.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados.
+- Preferir menos de 180 lineas cambiadas.
+
+## Outcome
+- `backend/README.md` documenta el comando exacto de validacion A2S real y el resultado esperado cuando `Comunidad Hispana #01` responde.
+- No fue necesario cambiar `collector.py`, `normalizers.py` ni `storage.py` porque el flujo real ya normaliza y persiste correctamente.
+- La validacion tambien dejo ver el comportamiento de error: en entorno sandbox con UDP restringido el colector devuelve timeout controlado y `success_count: 0`.
+
+## Validation Result
+- Ejecutado en sandbox: `python -m app.collector --source a2s --no-fallback`.
+- Resultado en sandbox: timeout controlado hacia `152.114.195.174:7778`, `success_count: 0`, sin snapshots reales persistidos.
+- Ejecutado fuera del sandbox: `python -m app.collector --source a2s --no-fallback`.
+- Resultado fuera del sandbox: `success_count: 1`, un snapshot persistido para `comunidad-hispana-01` en `backend/data/hll_vietnam_dev.sqlite3`.
+- Snapshot validado en SQLite: `server_name=#01 [ESP] Comunidad Hispana - discord.comunidadhll.es - Spa Onl`, `current_map=Remagen`, `players=0`, `max_players=100`, `source_name=community-hispana-a2s`, `captured_at=2026-03-20T11:23:08.431142Z`.
+- Endpoints revisados desde Python: `/api/servers/latest`, `/api/servers/history` y `/api/servers/{id}/history` ya exponen el snapshot real persistido.
+
+## Decision Notes
+- El timeout observado en sandbox no se trato como bug de backend porque la misma consulta funciono fuera del sandbox sin cambios de codigo.
+- La procedencia efectiva del snapshot queda reflejada en `source_name=community-hispana-a2s`, mientras que el payload superior del colector mantiene `collection_mode=a2s`.

ai/tasks/done/TASK-030-historical-snapshot-quality-pass.md

@@ -0,0 +1,84 @@
+# TASK-030-historical-snapshot-quality-pass
+
+## Goal
+Revisar y ajustar la calidad de los snapshots persistidos tras la primera captura A2S real, asegurando consistencia de datos, timestamps, procedencia y utilidad de cara a historico y visualizacion.
+
+## Context
+Una vez incorporado el target real y validada una primera captura, el siguiente paso es comprobar la calidad del dato persistido. No basta con guardar snapshots; deben ser consistentes y utiles para construir historico, estadisticas y visualizacion sin ruido innecesario.
+
+## Steps
+1. Revisar snapshots persistidos a partir de la captura real de Comunidad Hispana #01.
+2. Verificar consistencia de campos clave:
+   - nombre del servidor
+   - host o referencia de origen
+   - timestamp
+   - mapa actual
+   - jugadores
+   - capacidad
+   - fuente efectiva
+3. Revisar si hay problemas de calidad como:
+   - duplicados innecesarios
+   - timestamps incoherentes
+   - normalizacion deficiente
+   - mezcla poco clara entre fallback y captura real
+4. Ajustar la capa de persistencia, normalizacion o payloads si fuera necesario para mejorar claridad.
+5. Revisar el impacto en endpoints historicos existentes:
+   - `/api/servers/latest`
+   - `/api/servers/history`
+   - `/api/servers/{id}/history`
+6. Mantener el cambio centrado en calidad y coherencia del historico, no en nuevas visualizaciones.
+7. Actualizar documentacion minima si el modelo efectivo de snapshot cambia ligeramente.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- datos persistidos generados en la task anterior
+
+## Expected Files to Modify
+- backend/app/normalizers.py
+- backend/app/storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/README.md
+- opcionalmente documentacion tecnica relacionada si la claridad del historico necesita ajuste
+
+## Constraints
+- No tocar frontend en esta task.
+- No anadir nuevas fuentes externas.
+- No introducir complejidad analitica alta.
+- No hacer cambios destructivos.
+- Mantener el resultado centrado en calidad de datos historicos.
+
+## Validation
+- Los snapshots reales persistidos son consistentes y utiles.
+- Los endpoints historicos reflejan correctamente el dato real almacenado.
+- La distincion entre captura real y fallback queda razonablemente clara.
+- El backend queda listo para una siguiente task de mejora visual o estadistica sobre datos reales.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados.
+- Preferir menos de 180 lineas cambiadas.
+
+## Outcome
+- `backend/app/normalizers.py` anade `snapshot_origin` y `source_ref` al modelo normalizado para que la procedencia no se infiera de forma ambigua en historico.
+- `backend/app/snapshots.py` conserva esos campos en cada snapshot persistible.
+- `backend/app/storage.py` migra la tabla SQLite sin destruir datos, serializa ambos campos en las consultas historicas y backfilla referencias A2S registradas para snapshots ya existentes.
+- `backend/README.md` documenta los nuevos metadatos historicos y el valor esperado para la captura real de Comunidad Hispana #01.
+
+## Validation Result
+- Ejecutado: lectura de `list_latest_snapshots()`, `list_snapshot_history()` y `list_server_history('comunidad-hispana-01')` desde Python.
+- Resultado: los snapshots historicos exponen `snapshot_origin` con `real-a2s` o `controlled-fallback` y `source_ref` coherente.
+- Ejecutado fuera del sandbox: `python -m app.collector --source a2s --no-fallback`.
+- Resultado: nuevo snapshot real persistido con `source_ref=a2s://152.114.195.174:7778`, `current_map=Remagen`, `players=0`, `max_players=100`.
+- Endpoints verificados: `/api/servers/latest`, `/api/servers/history` y `/api/servers/{id}/history` devuelven el snapshot real mas reciente con la nueva metadata de procedencia.
+
+## Decision Notes
+- No se tocaron `routes.py` ni `payloads.py` porque ya reutilizan directamente los registros serializados de almacenamiento y heredaron la mejora sin cambios de contrato adicionales.
+- No se introdujo deduplicacion agresiva de snapshots porque dos capturas reales con distinto `captured_at` siguen siendo historico valido; el ajuste se centro en claridad y consistencia de procedencia.

ai/tasks/done/TASK-031-local-cors-alignment-for-frontend-dev.md

@@ -0,0 +1,70 @@
+# TASK-031-local-cors-alignment-for-frontend-dev
+
+## Goal
+Corregir y alinear la configuracion CORS del backend para permitir que el frontend local de desarrollo consuma la API desde origenes locales habituales sin caer en fallback por bloqueo del navegador.
+
+## Context
+El backend responde correctamente a `/health`, `/api/servers/latest` y `/api/servers/history`, y los snapshots reales A2S ya estan persistidos. Sin embargo, el frontend servido localmente con `python -m http.server 8080` no puede consumir la API porque el navegador bloquea las respuestas por falta de la cabecera `Access-Control-Allow-Origin` para `http://localhost:8080`.
+
+La correccion debe centrarse en CORS de desarrollo local, sin cambiar la arquitectura funcional del producto.
+
+## Steps
+1. Revisar la configuracion actual de CORS del backend.
+2. Confirmar como se comparan y validan los origenes permitidos.
+3. Anadir soporte correcto para los origenes locales de desarrollo mas comunes, incluyendo al menos:
+   - `http://localhost:8080`
+   - `http://127.0.0.1:8080`
+4. Revisar si tambien conviene permitir otros puertos locales habituales documentados por el proyecto, sin abrir el backend de forma innecesaria.
+5. Asegurar que las respuestas GET del backend incluyan `Access-Control-Allow-Origin` cuando el origen este permitido.
+6. Asegurar que el backend maneje correctamente `OPTIONS` si el flujo actual lo requiere.
+7. Actualizar la documentacion del backend para dejar claro como probar frontend y backend juntos en local.
+8. Mantener el alcance centrado en desarrollo local y correccion CORS.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/main.py
+- backend/app/routes.py
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/config.py
+- backend/app/main.py
+- opcionalmente otros archivos backend si la logica CORS esta centralizada en otro sitio
+
+## Constraints
+- No tocar visualmente el frontend.
+- No cambiar endpoints ni payloads.
+- No introducir dependencias nuevas innecesarias.
+- No hacer cambios destructivos.
+- Mantener la solucion pequena y claramente orientada a desarrollo local.
+
+## Validation
+- Una peticion desde `http://localhost:8080` a `http://localhost:8000/api/servers/latest` ya no falla por CORS.
+- Una peticion desde `http://127.0.0.1:8080` tambien funciona si se decidio soportarla.
+- La landing deja de caer al fallback estatico cuando el backend esta disponible.
+- La documentacion refleja como ejecutar el stack local correctamente.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 140 lineas cambiadas.
+
+## Outcome
+- `backend/app/config.py` amplia la allowlist CORS local por defecto para cubrir `http://localhost:8080` y `http://127.0.0.1:8080`, manteniendo tambien `null` y los origenes ya usados en `5500`.
+- `backend/app/config.py` normaliza espacios y barras finales en `HLL_BACKEND_ALLOWED_ORIGINS` para que un override local no falle por formato.
+- `backend/README.md` documenta la prueba local recomendada con `python -m app.main` y `python -m http.server 8080`, y deja explicito que origenes locales quedan soportados por defecto.
+- No fue necesario cambiar `backend/app/main.py` ni `backend/app/routes.py` porque la emision de `Access-Control-Allow-Origin` y el manejo de `OPTIONS` ya estaban correctamente centralizados en el handler HTTP.
+
+## Validation Result
+- Ejecutado: validacion aislada desde Python levantando `app.main.create_server()` en `127.0.0.1:8010` dentro del mismo proceso.
+- Resultado `GET` con `Origin: http://localhost:8080`: `200 OK`, `Access-Control-Allow-Origin: http://localhost:8080`, `Vary: Origin`.
+- Resultado `GET` con `Origin: http://127.0.0.1:8080`: `200 OK`, `Access-Control-Allow-Origin: http://127.0.0.1:8080`, `Vary: Origin`.
+- Resultado `OPTIONS` con `Origin: http://localhost:8080`: `204 No Content`, `Access-Control-Allow-Origin: http://localhost:8080`, `Access-Control-Allow-Methods: GET, OPTIONS`, `Access-Control-Allow-Headers: Content-Type`.
+- Observacion de entorno: `127.0.0.1:8000` ya estaba ocupado por otro proceso ajeno a esta task, asi que la validacion final se hizo en `:8010` para comprobar exactamente el codigo modificado sin depender de ese proceso.
+
+## Decision Notes
+- Se mantuvo una allowlist cerrada de desarrollo local en lugar de abrir CORS globalmente, porque la task pedia corregir el flujo local sin introducir una configuracion de produccion prematura.
+- No se anadieron puertos arbitrarios extra; se alineo la configuracion con `5500`, `8080` y `null`, que cubren los flujos locales ya usados o documentados por el proyecto.

ai/tasks/done/TASK-032-connect-button-for-real-server-cards.md

@@ -0,0 +1,69 @@
+# TASK-032-connect-button-for-real-server-cards
+
+## Goal
+Añadir en la web un botón de conexión directa `steam://connect/...` para tarjetas de servidores reales, usando el game port correcto y manteniendo el comportamiento actual del panel de servidores.
+
+## Context
+La landing ya muestra snapshots reales A2S y distingue entre datos reales, históricos y fallback. Además, ya se han verificado servidores reales de Comunidad Hispana con separación entre game port y query port. El siguiente paso útil para producto es añadir un botón Connect en las tarjetas de servidores reales para permitir una acción directa desde la web.
+
+## Steps
+1. Revisar el frontend actual y cómo se renderizan las tarjetas de servidores.
+2. Revisar el backend y comprobar si el frontend dispone actualmente del `game_port` necesario para construir `steam://connect/...`.
+3. Si el dato no está disponible en los payloads actuales, ajustar la capa backend mínima necesaria para exponerlo de forma clara y estable.
+4. Añadir un botón Connect solo cuando la tarjeta represente un servidor real con datos suficientes.
+5. Usar siempre el `game_port`, nunca el `query_port`.
+6. Mantener el botón visualmente coherente con la landing actual.
+7. Preservar el fallback actual si un servidor no tiene datos reales o no dispone de `game_port`.
+8. Validar que los enlaces queden correctos al menos para:
+   - Comunidad Hispana #01 → `steam://connect/152.114.195.174:7777`
+   - Comunidad Hispana #02 → `steam://connect/152.114.195.150:7877`
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/server_targets.py
+- backend/README.md
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/routes.py
+- backend/app/payloads.py
+- opcionalmente backend/app/server_targets.py si hace falta alinear metadata
+
+## Constraints
+- No rediseñar toda la landing.
+- No romper el fallback actual.
+- No usar `query_port` para el enlace de conexión.
+- No añadir librerías nuevas.
+- No hacer cambios destructivos.
+- Mantener la mejora centrada en el panel de servidores y acción de conexión.
+
+## Validation
+- Las tarjetas de servidores reales muestran un botón Connect cuando corresponde.
+- El enlace de conexión usa `steam://connect/<host>:<game_port>`.
+- Los placeholders o tarjetas sin datos reales no rompen el render.
+- La mejora visual se integra con la landing actual.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+## Outcome
+- `backend/app/payloads.py` enriquece los snapshots reales con `host`, `query_port` y `game_port` a partir del registro A2S ya verificado, sin tocar la persistencia.
+- `frontend/assets/js/main.js` muestra un boton `Connect` solo para tarjetas `real-a2s` que dispongan de `host` y `game_port`, generando `steam://connect/<host>:<game_port>`.
+- `frontend/assets/css/styles.css` integra visualmente la nueva accion sin redisenar el panel ni afectar placeholders.
+
+## Validation Result
+- Ejecutado desde `backend/`: comprobacion de `build_server_latest_payload()` sobre `comunidad-hispana-01` y `comunidad-hispana-02`.
+- Resultado: ambos snapshots reales exponen `host`, `query_port` y `game_port`, conservando `snapshot_origin=real-a2s`.
+- Ejecutado desde `backend/`: validacion de enlaces esperados `steam://connect/152.114.195.174:7777` y `steam://connect/152.114.195.150:7877`.
+- Resultado: los enlaces calculados coinciden exactamente con los valores requeridos para `#01` y `#02`.
+
+## Decision Notes
+- Se evita duplicar `host` y `game_port` en SQLite porque ya existen como metadata estable del target A2S y basta con enriquecer el payload de lectura.

ai/tasks/done/TASK-033-real-vs-placeholder-server-panel-separation.md

@@ -0,0 +1,62 @@
+# TASK-033-real-vs-placeholder-server-panel-separation
+
+## Goal
+Mejorar la claridad visual y funcional del panel de servidores separando o priorizando de forma más evidente los snapshots reales A2S frente a los placeholders controlados.
+
+## Context
+El panel de servidores ya consume datos del backend y actualmente mezcla snapshots reales persistidos con tarjetas de fallback controlado. El sistema funciona, pero ahora conviene dejar visualmente más claro qué servidores son reales y cuáles siguen siendo referencias provisionales.
+
+## Steps
+1. Revisar el panel actual de servidores y su lógica de renderizado.
+2. Identificar cómo distingue actualmente el frontend entre:
+   - `real-a2s`
+   - `controlled-fallback`
+   - histórico persistido
+3. Mejorar la composición del panel para que los snapshots reales queden más destacados o separados de los placeholders.
+4. Mantener el cambio contenido y coherente con el diseño actual.
+5. Asegurar que la información de procedencia siga siendo clara.
+6. No eliminar el fallback si todavía es útil para el proyecto.
+7. No rediseñar la landing completa.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/payloads.py
+- backend/app/routes.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No tocar backend salvo si una referencia documental mínima fuera imprescindible.
+- No eliminar soporte para fallback.
+- No introducir librerías nuevas.
+- No hacer cambios destructivos.
+- Mantener la mejora centrada en claridad de datos y jerarquía visual.
+
+## Validation
+- El panel distingue mejor entre servidores reales y placeholders.
+- Los snapshots reales ganan prioridad o separación visual clara.
+- El fallback sigue funcionando.
+- La landing mantiene coherencia visual.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 160 líneas cambiadas.
+## Outcome
+- `frontend/assets/js/main.js` separa el render historico en dos bloques: `Snapshots reales A2S` y `Referencia provisional e historico auxiliar`, priorizando arriba los snapshots reales.
+- `frontend/assets/js/main.js` etiqueta cada tarjeta persistida como `Snapshot real A2S` o `Referencia persistida` segun `snapshot_origin`, manteniendo el fallback sin eliminarlo.
+- `frontend/assets/css/styles.css` refuerza la separacion visual con encabezados de seccion y variantes de tarjeta diferenciadas para reales y placeholders.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`.
+- Resultado: sintaxis JavaScript valida tras introducir el render por secciones.
+- Revisado en codigo: el panel renderiza una seccion prioritaria `Snapshots reales A2S` y una seccion separada para referencia/fallback, sin romper la grilla existente.
+
+## Decision Notes
+- La separacion se implementa dentro del mismo panel para mantener el alcance pequeno y evitar un redisenio estructural de la landing.

ai/tasks/done/TASK-034-real-a2s-target-onboarding-comunidad-hispana-02.md

@@ -0,0 +1,72 @@
+# TASK-034-real-a2s-target-onboarding-comunidad-hispana-02
+
+## Goal
+Dar de alta el segundo target A2S real verificado del proyecto, correspondiente a Comunidad Hispana #02, integrándolo en la configuración del backend de forma clara, mantenible y coherente con el target real ya existente de Comunidad Hispana #01.
+
+## Context
+El backend ya tiene onboarding real de Comunidad Hispana #01 y se ha validado la separación entre `game_port` y `query_port`. Ahora también se ha verificado un segundo servidor real:
+- Comunidad Hispana #02
+- Host/IP: `152.114.195.150`
+- Game Port: `7877`
+- Query Port: `7878`
+
+La task debe incorporarlo correctamente a la configuración sin introducir ambigüedades entre puertos ni mezclarlo con fuentes no verificadas.
+
+## Steps
+1. Revisar la configuración actual de targets A2S.
+2. Añadir Comunidad Hispana #02 con:
+   - nombre amigable claro
+   - host/IP: `152.114.195.150`
+   - query port: `7878`
+   - game port: `7877`
+   - contexto o etiqueta coherente con el proyecto
+3. Mantener la configuración desacoplada y limpia.
+4. Documentar el alta del nuevo target en el backend.
+5. Verificar que el target anterior (#01) sigue correcto y sin regresiones.
+6. Mantener el cambio acotado a onboarding de target real.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/server_targets.py
+- backend/app/collector.py
+- backend/app/a2s_client.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/server_targets.py
+- backend/app/config.py
+- opcionalmente backend/app/collector.py si necesita una alineación menor
+
+## Constraints
+- No tocar frontend.
+- No añadir targets no verificados.
+- No confundir `game_port` con `query_port`.
+- No añadir scraping.
+- No hacer cambios destructivos.
+- Mantener la configuración simple y clara.
+
+## Validation
+- El backend contiene el target real de Comunidad Hispana #02 correctamente registrado.
+- El query port configurado es `7878`.
+- El game port registrado es `7877`.
+- La documentación deja claro cómo está definido este target.
+- No se ha roto el target existente de Comunidad Hispana #01.
+
+## Change Budget
+- Preferir menos de 4 archivos modificados.
+- Preferir menos de 140 líneas cambiadas.
+## Outcome
+- `backend/app/server_targets.py` registra `Comunidad Hispana #02` junto a `#01` con `host`, `query_port`, `game_port` y `external_server_id` verificados.
+- `backend/README.md` documenta ambos targets reales por defecto y mantiene separada la semantica de `query_port` frente a `game_port`.
+- No fue necesario tocar `backend/app/config.py` ni `backend/app/collector.py` porque la configuracion existente ya consume el registro de forma desacoplada.
+
+## Validation Result
+- Ejecutado desde `backend/`: `python -c "from app.server_targets import load_a2s_targets; print([(t.name, t.host, t.query_port, t.game_port, t.external_server_id) for t in load_a2s_targets()])"`.
+- Resultado: el registro carga `Comunidad Hispana #01` y `Comunidad Hispana #02` con `query_port=7778/7878` y `game_port=7777/7877` respectivamente.
+
+## Decision Notes
+- Se mantiene un unico `source_name` para la misma familia de servidores reales porque la distincion operativa ya queda en `external_server_id`, host y puertos.

ai/tasks/done/TASK-035-real-a2s-capture-validation-comunidad-hispana-02.md

@@ -0,0 +1,80 @@
+# TASK-035-real-a2s-capture-validation-comunidad-hispana-02
+
+## Goal
+Validar una captura A2S real extremo a extremo contra Comunidad Hispana #02, confirmando que el colector puede consultar el servidor, normalizar la respuesta y persistir snapshots útiles junto a los ya existentes de Comunidad Hispana #01.
+
+## Context
+El proyecto ya ha validado el flujo real A2S con Comunidad Hispana #01. Ahora se ha verificado un segundo servidor real de Comunidad Hispana con:
+- Host/IP: `152.114.195.150`
+- Query Port: `7878`
+- Game Port: `7877`
+
+El objetivo es confirmar que el pipeline soporta múltiples targets reales y que la persistencia y los endpoints históricos siguen siendo coherentes.
+
+## Steps
+1. Revisar la configuración actual de targets A2S y el target recién añadido para Comunidad Hispana #02.
+2. Ejecutar el colector o flujo equivalente contra este target real.
+3. Confirmar que el backend consulta correctamente el host `152.114.195.150` con query port `7878`.
+4. Validar que la respuesta A2S obtenida se normaliza al modelo interno.
+5. Persistir al menos un snapshot real de Comunidad Hispana #02 en la base local actual.
+6. Verificar que los endpoints históricos reflejan este nuevo servidor junto al ya existente.
+7. Revisar el comportamiento si la consulta falla, timeout o devuelve datos parciales.
+8. Actualizar la documentación mínima necesaria sobre cómo repetir esta validación en local.
+9. Mantener el alcance centrado en validación del flujo real, no en nuevas features.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- ai/architecture-index.md
+- backend/README.md
+- backend/app/a2s_client.py
+- backend/app/server_targets.py
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/snapshots.py
+- backend/app/storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/collector.py
+- backend/app/normalizers.py
+- backend/app/storage.py
+- backend/app/routes.py
+- backend/app/payloads.py
+- opcionalmente otros archivos backend si son estrictamente necesarios para soportar mejor múltiples targets reales
+
+## Constraints
+- No tocar frontend salvo que una referencia mínima fuera imprescindible para mostrar el nuevo target una vez persistido.
+- No añadir analítica avanzada.
+- No añadir scraping de terceros.
+- No introducir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la validación centrada en Comunidad Hispana #02 y coexistencia con #01.
+
+## Validation
+- Se realiza una captura real A2S sobre Comunidad Hispana #02.
+- Se persiste al menos un snapshot real en la base local.
+- El flujo real queda documentado y es repetible en local.
+- Los endpoints históricos reflejan ambos targets reales cuando existan snapshots.
+- Los errores de consulta están razonablemente manejados.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+## Outcome
+- `backend/app/a2s_client.py` eleva el timeout A2S por defecto de `3.0s` a `6.0s` para reducir timeouts transitorios al consultar varios targets reales seguidos.
+- `backend/README.md` documenta la validacion local extremo a extremo con ambos targets reales por defecto y el resultado esperado cuando responden `#01` y `#02`.
+- No fue necesario cambiar `collector.py`, `normalizers.py`, `storage.py`, `routes.py` ni `payloads.py` porque el pipeline ya normalizaba, persistia y exponia historico multi-target correctamente.
+
+## Validation Result
+- Ejecutado desde `backend/`: `python -m app.a2s_client 152.114.195.150 7878 --timeout 6`.
+- Resultado: respuesta valida de `Comunidad Hispana #02` con `server_name=#02 [ESP] Comunidad Hispana - discord.comunidadhll.es - Spa Onl`, `map_name=StMarie`, `players=0`, `max_players=100`.
+- Ejecutado desde `backend/`: `python -m app.collector --source a2s --no-fallback`.
+- Resultado: `target_count: 2`, `success_count: 2`, snapshots persistidos para `comunidad-hispana-01` y `comunidad-hispana-02` en `backend/data/hll_vietnam_dev.sqlite3`.
+- Ejecutado desde `backend/`: `python -c "from app.payloads import build_server_history_payload, build_server_detail_history_payload; ..."` para revisar historico.
+- Resultado: `/api/servers/history` refleja ambos targets reales y `/api/servers/comunidad-hispana-02/history` devuelve el snapshot persistido de `#02`.
+
+## Decision Notes
+- Se ajusta el timeout por defecto en lugar de introducir reintentos o complejidad adicional porque la captura ya era funcional y el problema observado fue de sensibilidad temporal, no de arquitectura.

ai/tasks/done/TASK-036-hide-placeholders-when-real-servers-exist-and-localize-connect-label.md

@@ -0,0 +1,73 @@
+# TASK-036-hide-placeholders-when-real-servers-exist-and-localize-connect-label
+
+## Goal
+Ajustar el panel de servidores para ocultar los placeholders o referencias provisionales cuando ya existan snapshots reales A2S utilizables, y cambiar la etiqueta visible del botón de conexión de “Connect” a “Conectar”.
+
+## Context
+La landing ya muestra snapshots reales A2S de Comunidad Hispana #01 y #02. En este punto, mantener visibles los placeholders como bloque principal o paralelo degrada la claridad del producto y da una sensación de estado provisional que ya no corresponde al nivel real del sistema. Los placeholders deben quedar como fallback técnico, no como contenido normal cuando haya datos reales disponibles. Además, la CTA visible de conexión debe localizarse al español.
+
+## Steps
+1. Revisar el render actual del panel de servidores en frontend.
+2. Identificar la lógica que separa:
+   - snapshots `real-a2s`
+   - snapshots históricos persistidos
+   - placeholders o `controlled-fallback`
+3. Ajustar la lógica para que:
+   - si existen snapshots reales A2S utilizables, solo se muestren esos servidores reales en la vista principal
+   - los placeholders queden ocultos en la vista normal
+   - el fallback provisional solo se muestre cuando no existan datos reales o el backend no aporte snapshots utilizables
+4. Mantener clara la procedencia del dato real sin sobrecargar la UI.
+5. Cambiar la etiqueta visible del botón de conexión de:
+   - `Connect`
+   a:
+   - `Conectar`
+6. Mantener intacto el uso técnico del enlace `steam://connect/<host>:<game_port>`.
+7. Revisar el copy mínimo del bloque para que encaje con una fase más madura del producto.
+8. Mantener el ajuste visual contenido, sin rediseñar toda la landing.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/payloads.py
+- backend/app/routes.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No tocar backend salvo referencia documental mínima si fuera imprescindible.
+- No romper el fallback cuando no haya datos reales.
+- No quitar soporte para placeholders a nivel interno; solo ocultarlos cuando existan snapshots reales utilizables.
+- No añadir librerías nuevas.
+- No hacer cambios destructivos.
+- Mantener el ajuste centrado en claridad de producto y localización de la CTA.
+
+## Validation
+- Cuando existen snapshots `real-a2s`, la vista principal del panel muestra solo servidores reales.
+- Los placeholders ya no aparecen en la vista normal si hay datos reales disponibles.
+- Si no hay datos reales, el fallback sigue funcionando.
+- El botón visible muestra “Conectar”.
+- La landing gana claridad visual y semántica.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 140 líneas cambiadas.
+
+## Outcome
+- `frontend/assets/js/main.js` filtra la vista principal del panel para mostrar solo snapshots `real-a2s` cuando existen, manteniendo el fallback persistido solo para escenarios sin capturas reales utilizables.
+- `frontend/assets/js/main.js` localiza la CTA visible de conexión a `Conectar` sin alterar el esquema técnico `steam://connect/<host>:<game_port>`.
+- `frontend/index.html` y `frontend/assets/css/styles.css` ajustan el copy y la presentación base del bloque para que el estado por defecto sea más neutro y menos provisional.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`.
+- Resultado: sintaxis JavaScript válida tras el ajuste de filtrado y localización.
+- Revisado en código: la vista enriquecida usa `selectPrimaryServerItems(...)`, por lo que los placeholders quedan ocultos cuando hay snapshots reales y el fallback sigue siendo la ruta visible si no existen capturas reales utilizables.
+- Revisado en código: la CTA visible del enlace de conexión muestra `Conectar`.
+
+## Decision Notes
+- La ocultación de placeholders se resolvió en la capa de selección de items visibles, sin tocar backend ni eliminar soporte interno de fallback.

ai/tasks/done/TASK-037-scheduled-local-snapshot-refresh.md

@@ -0,0 +1,62 @@
+# TASK-037-scheduled-local-snapshot-refresh
+
+## Goal
+Preparar una forma simple, clara y repetible de refrescar snapshots A2S reales de forma periódica en entorno local, reduciendo la dependencia de ejecución manual del colector.
+
+## Context
+El proyecto ya dispone de cliente A2S, targets reales verificados, colector funcional, persistencia SQLite y visualización en frontend. Actualmente el flujo depende de lanzar manualmente el colector para actualizar snapshots. El siguiente paso útil es dejar preparado un mecanismo sencillo de refresco periódico local que permita validar mejor el comportamiento histórico y la evolución de los datos.
+
+## Steps
+1. Revisar el flujo actual de captura manual de snapshots.
+2. Definir una estrategia simple de refresco local, adecuada al estado actual del proyecto.
+3. Preparar una forma clara de ejecutar capturas periódicas sin introducir infraestructura compleja de producción.
+4. Mantener el diseño desacoplado para que en el futuro pueda reemplazarse por un scheduler más serio si hiciera falta.
+5. Documentar cómo arrancar este refresco local y cómo detenerlo.
+6. Si hace falta, añadir un modo seguro o flags para evitar comportamiento inesperado en desarrollo.
+7. Mantener el alcance en refresco local y desarrollo, no en despliegue productivo.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- backend/README.md
+- backend/app/config.py
+- backend/app/collector.py
+- backend/app/server_targets.py
+- backend/app/storage.py
+
+## Expected Files to Modify
+- backend/README.md
+- backend/app/config.py
+- backend/app/collector.py
+- opcionalmente archivos nuevos si mejoran claridad, por ejemplo:
+  - backend/app/scheduler.py
+  - backend/scripts/run_local_refresh.py
+
+## Constraints
+- No tocar frontend.
+- No introducir un sistema de colas o infraestructura pesada.
+- No añadir complejidad innecesaria.
+- No hacer cambios destructivos.
+- Mantener la solución simple y enfocada a entorno local.
+
+## Validation
+- Existe una forma documentada y funcional de refrescar snapshots periódicamente en local.
+- El flujo sigue siendo controlable y fácil de detener.
+- La solución encaja con el backend actual sin sobredimensionarlo.
+- El sistema queda preparado para capturas más frecuentes y validación histórica.
+
+## Change Budget
+- Preferir menos de 5 archivos modificados o creados.
+- Preferir menos de 180 líneas cambiadas.
+## Outcome
+- `backend/app/scheduler.py` añade un bucle local de refresco periódico reutilizando el colector existente, sin introducir infraestructura de producción ni dependencias nuevas.
+- `backend/app/config.py` centraliza el intervalo por defecto mediante `HLL_BACKEND_REFRESH_INTERVAL_SECONDS`.
+- `backend/README.md` documenta cómo arrancar el refresco local, cómo detenerlo con `Ctrl+C` y qué flags de seguridad usar (`--interval`, `--no-fallback`, `--max-runs`).
+
+## Validation Result
+- Ejecutado: `python -m app.scheduler --source controlled --interval 1 --max-runs 1` desde `backend/`.
+- Resultado: se ejecutó un ciclo persistido correctamente sobre `backend/data/hll_vietnam_dev.sqlite3` y el proceso terminó al alcanzar el límite seguro de ejecuciones.
+- Revisado en código: el refresco local queda desacoplado del servidor HTTP y reutiliza `collect_server_snapshots(...)` sin duplicar lógica del colector.
+
+## Decision Notes
+- El refresco periódico se resolvió como un bucle local explícito y controlable para desarrollo, en lugar de introducir un scheduler embebido en el backend HTTP o infraestructura más pesada.

ai/tasks/done/TASK-038-server-history-summary-cards.md

@@ -0,0 +1,72 @@
+# TASK-038-server-history-summary-cards
+
+## Goal
+Añadir al backend y al frontend una primera capa de métricas históricas resumidas para los servidores reales, de forma que el panel muestre información más útil que el simple último snapshot.
+
+## Context
+La web ya muestra snapshots reales A2S y dispone de histórico persistido. Sin embargo, el valor actual del panel sigue siendo limitado si solo enseña la última captura y una tendencia básica. El siguiente paso lógico es construir resúmenes históricos ligeros a partir de lo ya almacenado, sin convertir aún la landing en un dashboard complejo.
+
+## Steps
+1. Revisar los endpoints históricos actuales y el panel de servidores existente.
+2. Identificar qué métricas históricas resumidas son viables con los snapshots ya persistidos, por ejemplo:
+   - última vez visto online
+   - número de capturas recientes
+   - promedio reciente de jugadores
+   - valor máximo reciente de población
+   - tiempo desde la última captura
+3. Añadir la capa mínima necesaria en backend para exponer estas métricas de forma clara.
+4. Integrar esas métricas en las tarjetas de servidores reales del frontend.
+5. Mantener la mejora ligera y coherente con el diseño actual.
+6. No introducir cálculos pesados ni analítica compleja.
+7. Preservar el comportamiento correcto si aún hay pocos snapshots disponibles.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- backend/README.md
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/storage.py
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Expected Files to Modify
+- backend/app/routes.py
+- backend/app/payloads.py
+- backend/app/storage.py
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No rediseñar toda la landing.
+- No añadir gráficas complejas.
+- No introducir librerías nuevas.
+- No romper el fallback actual.
+- No hacer cambios destructivos.
+- Mantener la mejora centrada en valor histórico resumido.
+
+## Validation
+- El backend expone métricas históricas resumidas útiles para servidores reales.
+- El frontend las muestra de forma clara y legible.
+- La UI sigue funcionando aunque el histórico disponible sea limitado.
+- El panel gana valor funcional sin perder claridad.
+
+## Change Budget
+- Preferir menos de 6 archivos modificados.
+- Preferir menos de 220 líneas cambiadas.
+## Outcome
+- `backend/app/storage.py` adjunta a cada snapshot más reciente un `history_summary` ligero con capturas recientes, promedio de jugadores, pico, última vez visto online y minutos desde la última captura.
+- `backend/app/payloads.py` expone esas métricas en `GET /api/servers/latest` sin abrir un endpoint nuevo.
+- `frontend/assets/js/main.js` integra las métricas resumidas en las tarjetas reales e históricas ya renderizadas por la landing.
+- `frontend/assets/css/styles.css` añade el bloque visual compacto para mostrar esos resúmenes sin convertir la landing en un dashboard pesado.
+
+## Validation Result
+- Ejecutado: import directo de `build_server_latest_payload()` desde `backend/`.
+- Resultado: el payload devuelve `history_summary` por servidor con valores coherentes incluso cuando hay pocas capturas disponibles.
+- Ejecutado: `node --check frontend/assets/js/main.js`.
+- Resultado: sintaxis JavaScript válida tras integrar el bloque de métricas resumidas.
+
+## Decision Notes
+- Las métricas históricas resumidas se calculan sobre una ventana corta de snapshots recientes y se entregan junto al payload de último estado para mantener el backend simple y evitar analítica o endpoints adicionales en esta fase.

ai/tasks/done/TASK-039-real-server-panel-data-density-pass.md

@@ -0,0 +1,67 @@
+# TASK-039-real-server-panel-data-density-pass
+
+## Goal
+Mejorar la densidad informativa y la claridad de las tarjetas de servidores reales, aprovechando mejor los datos ya disponibles sin recargar visualmente la landing.
+
+## Context
+Tras ocultar los placeholders cuando existen snapshots reales y preparar una CTA de conexión en español, el panel real ya tiene buena base. Sin embargo, todavía puede ganar valor mostrando mejor la información disponible y organizando mejor la jerarquía interna de las tarjetas.
+
+## Steps
+1. Revisar la composición actual de las tarjetas de servidores reales.
+2. Revisar qué datos ya están disponibles o pasarán a estar disponibles tras la task de resúmenes históricos.
+3. Mejorar la jerarquía interna de cada tarjeta:
+   - nombre
+   - estado
+   - mapa
+   - jugadores
+   - región
+   - última captura
+   - CTA
+   - métricas resumidas si existen
+4. Hacer que la tarjeta transmita más información útil sin volverse pesada.
+5. Mantener coherencia visual con la landing actual.
+6. Mejorar legibilidad en desktop y móvil.
+7. No rediseñar toda la página ni añadir nuevas secciones grandes.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/payloads.py
+- backend/app/routes.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No tocar backend salvo si es estrictamente necesario por alineación menor con payloads ya existentes.
+- No añadir librerías nuevas.
+- No romper el fallback ni la CTA Conectar.
+- No hacer cambios destructivos.
+- Mantener la mejora centrada en claridad, jerarquía y densidad informativa.
+
+## Validation
+- Las tarjetas reales muestran mejor la información útil.
+- La jerarquía interna mejora.
+- La experiencia visual sigue siendo limpia.
+- El panel se entiende mejor en desktop y móvil.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+## Outcome
+- `frontend/assets/js/main.js` reorganiza la jerarquía interna de las tarjetas reales para destacar nombre, estado, población actual, mapa, región, última captura, CTA y métricas resumidas.
+- `frontend/assets/css/styles.css` refuerza la densidad informativa con una columna compacta de estado/población y una fila de quick facts legible en desktop y móvil.
+- La CTA `Conectar`, la tendencia reciente y el fallback existente se mantienen operativos.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`.
+- Resultado: sintaxis JavaScript válida tras el ajuste de jerarquía y densidad visual.
+- Revisado en código: la versión enriquecida de la tarjeta conserva `steam://connect/<host>:<game_port>` para snapshots reales y mantiene el fallback cuando no hay datos reales utilizables.
+
+## Decision Notes
+- La mejora de densidad se concentró dentro de la tarjeta existente, sin añadir nuevas secciones grandes ni cambiar la arquitectura del panel.

ai/tasks/done/TASK-040-full-width-page-shell-and-section-width-rebalance.md

@@ -0,0 +1,60 @@
+# TASK-040-full-width-page-shell-and-section-width-rebalance
+
+## Goal
+Reorganizar el layout general de la landing para aprovechar mucho mejor el ancho de página disponible, separando el ancho útil de las distintas secciones y eliminando la sensación de página excesivamente estrecha.
+
+## Context
+La UI actual ya funciona y muestra datos reales, pero la composición general está demasiado constreñida en ancho. Esto provoca mucho espacio muerto lateral, reduce el impacto visual del diseño y comprime en exceso el panel de servidores. La landing necesita una estructura de anchuras más flexible y más coherente con un formato panorámico de desktop.
+
+## Steps
+1. Revisar la estructura general de contenedores de `frontend/index.html`.
+2. Revisar el sistema de anchuras, `max-width`, paddings laterales y shells actuales en `frontend/assets/css/styles.css`.
+3. Reorganizar la página para que no todas las secciones dependan del mismo ancho máximo.
+4. Definir al menos una separación clara entre:
+   - ancho del hero
+   - ancho del tráiler
+   - ancho del panel de servidores
+5. Aumentar el ancho útil del bloque de servidores para aprovechar mejor desktop amplio.
+6. Mantener el diseño responsive y sin romper móvil o tablet.
+7. Preservar la identidad visual actual sin rediseñar completamente la página.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/css/styles.css
+
+## Constraints
+- No tocar backend.
+- No añadir librerías nuevas.
+- No romper el comportamiento actual del frontend.
+- No hacer cambios destructivos.
+- Mantener la landing coherente con el tono visual actual.
+
+## Validation
+- La página ocupa mejor el ancho disponible en desktop.
+- El panel de servidores gana anchura real.
+- El hero y el tráiler mantienen buen equilibrio visual.
+- La UI sigue funcionando correctamente en tablet y móvil.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+
+## Outcome
+- `frontend/assets/css/styles.css` separa el ancho del hero, del bloque de trailer y del panel de servidores con shells independientes.
+- El `page-shell` deja de imponer un unico ancho maximo a toda la landing y el panel de servidores gana mas ancho util en desktop.
+- La mejora se mantuvo en CSS para no introducir cambios estructurales innecesarios en el HTML.
+
+## Validation Result
+- Revisado en diff: el ajuste queda limitado a `frontend/assets/css/styles.css` y al propio archivo de task.
+- Revisado en codigo: hero, trailer y panel de servidores usan anchuras maximas distintas y el layout movil conserva los resets responsive existentes.
+- Limitacion: no se ejecuto una comprobacion visual automatizada del navegador en esta tarea.
+
+## Decision Notes
+- La separacion de shells se resolvio con anchuras por seccion en lugar de crear nuevos wrappers HTML, para mantener la landing estable y reducir riesgo sobre el frontend actual.

ai/tasks/done/TASK-041-real-server-card-layout-reorganization.md

@@ -0,0 +1,68 @@
+# TASK-041-real-server-card-layout-reorganization
+
+## Goal
+Reorganizar internamente las tarjetas de servidores reales para que aprovechen mejor el espacio horizontal, reduzcan compresión vertical y mejoren la legibilidad de los datos.
+
+## Context
+Las tarjetas actuales contienen información útil, pero en una composición demasiado estrecha y alta. Eso hace que varias métricas queden apelotonadas, con mala jerarquía y sensación de desborde. Esta task debe rediseñar la distribución interna de la tarjeta, no la arquitectura funcional del panel.
+
+## Steps
+1. Revisar la estructura HTML y JS que renderiza las tarjetas de servidores reales.
+2. Reorganizar la composición interna para que la tarjeta tenga una lectura más horizontal y clara.
+3. Priorizar visualmente:
+   - nombre del servidor
+   - estado
+   - botón Conectar
+   - jugadores
+   - mapa
+   - región
+   - última captura
+   - métricas resumidas
+4. Reducir altura innecesaria y mejorar la distribución interna de bloques.
+5. Mantener la CTA de conexión visible y bien integrada.
+6. Mejorar el comportamiento de nombres largos y textos densos.
+7. No romper el fallback ni la lógica actual del panel.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+- backend/app/payloads.py
+
+## Expected Files to Modify
+- frontend/index.html
+- frontend/assets/js/main.js
+- frontend/assets/css/styles.css
+
+## Constraints
+- No tocar backend salvo alineación mínima si fuera imprescindible.
+- No añadir librerías nuevas.
+- No romper la CTA Conectar.
+- No hacer cambios destructivos.
+- Mantener la mejora centrada en layout y legibilidad.
+
+## Validation
+- Las tarjetas reales son más legibles y aprovechan mejor el ancho.
+- La jerarquía interna mejora claramente.
+- El texto largo deja de sentirse comprimido o desbordado.
+- La UI mantiene coherencia visual con el resto de la landing.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 180 líneas cambiadas.
+
+## Outcome
+- `frontend/assets/js/main.js` reorganiza la tarjeta real en dos zonas: cabecera prioritaria con estado, poblacion y CTA, y cuerpo con quick facts, resumen historico y tendencia.
+- `frontend/assets/css/styles.css` adapta la tarjeta a una lectura mas horizontal en desktop y endurece el wrapping de nombres y valores largos.
+- No fue necesario tocar `frontend/index.html` ni alinear payloads del backend.
+
+## Validation Result
+- Ejecutado: `node --check frontend/assets/js/main.js`.
+- Resultado: sintaxis JavaScript valida tras la reorganizacion del render.
+- Revisado en codigo: la CTA `Conectar` sigue ligada a `steam://connect/<host>:<game_port>` y solo aparece para snapshots reales A2S.
+- Limitacion: no se ejecuto una comprobacion visual automatizada del navegador en esta tarea.
+
+## Decision Notes
+- La reduccion de altura se resolvio moviendo resumen y tendencia a una composicion interna mas horizontal, sin cambiar la logica de secciones del panel ni el fallback existente.

ai/tasks/done/TASK-042-server-panel-grid-and-overflow-hardening.md

@@ -0,0 +1,62 @@
+# TASK-042-server-panel-grid-and-overflow-hardening
+
+## Goal
+Fortalecer la rejilla del panel de servidores y corregir problemas de compresión, desborde y distribución espacial en desktop, tablet y móvil.
+
+## Context
+El panel de servidores ya consume datos reales y funciona correctamente, pero la rejilla actual no está aprovechando bien el espacio horizontal y deja tarjetas demasiado estrechas. Además, la estructura necesita endurecerse frente a nombres largos, métricas densas y cambios de anchura de viewport.
+
+## Steps
+1. Revisar la rejilla actual del panel de servidores.
+2. Ajustar el sistema de columnas para permitir una distribución más robusta y flexible.
+3. Usar una estrategia de `grid` adecuada para:
+   - desktop ancho
+   - desktop medio
+   - tablet
+   - móvil
+4. Revisar `min-width`, `max-width`, `gap`, `overflow-wrap` y cualquier punto de compresión o desborde.
+5. Asegurar que las tarjetas no se rompan visualmente con contenido real.
+6. Mantener una composición limpia, con buen aire y buen equilibrio.
+7. No rediseñar toda la landing fuera del panel de servidores.
+
+## Files to Read First
+- AGENTS.md
+- ai/repo-context.md
+- frontend/index.html
+- frontend/assets/css/styles.css
+- frontend/assets/js/main.js
+
+## Expected Files to Modify
+- frontend/assets/css/styles.css
+- frontend/index.html
+- opcionalmente frontend/assets/js/main.js si hay que ajustar clases o hooks del render
+
+## Constraints
+- No tocar backend.
+- No añadir librerías nuevas.
+- No romper el comportamiento actual del panel.
+- No hacer cambios destructivos.
+- Mantener el trabajo centrado en grid, responsive y overflow.
+
+## Validation
+- El panel de servidores ocupa mejor el ancho disponible.
+- Las tarjetas ya no se sienten excesivamente estrechas.
+- Se corrigen problemas de compresión y desborde.
+- El comportamiento responsive mejora en desktop, tablet y móvil.
+
+## Change Budget
+- Preferir menos de 3 archivos modificados.
+- Preferir menos de 160 líneas cambiadas.
+
+## Outcome
+- `frontend/assets/css/styles.css` sustituye la rejilla fija de dos columnas por un `auto-fit` con `minmax`, permitiendo mejor reparto en desktop ancho y desktop medio.
+- El mismo archivo endurece el panel con `min-width: 0`, `max-width: 100%`, `overflow: hidden` y subrejillas flexibles para quick facts y resumen.
+- No fue necesario tocar `frontend/index.html` ni `frontend/assets/js/main.js`.
+
+## Validation Result
+- Revisado en codigo: el panel ahora define comportamiento especifico para desktop ancho, desktop medio, tablet y movil mediante breakpoints en `1120px`, `760px` y el ajuste movil existente.
+- Revisado en diff: la task queda limitada a `frontend/assets/css/styles.css` y al archivo de task.
+- Limitacion: no se ejecuto una comprobacion visual automatizada del navegador en esta tarea.
+
+## Decision Notes
+- La hardening del panel se resolvio a nivel de grid y overflow sin volver a rediseñar las tarjetas ni tocar la logica de render ya ajustada en la task anterior.