Document RCON-first historical architecture

README.md

@@ -230,6 +230,30 @@ Verificacion minima:
 - `docker compose logs -f historical-runner`
 - revisar `generated_at` en `backend/data/snapshots/`
 
+## Arquitectura historica RCON-first
+
+La linea historica actual usa RCON como fuente primaria. El flujo previsto es:
+
+- captura de sesiones RCON para cobertura, frescura y ventanas competitivas
+- ingesta de AdminLog mediante `app.rcon_admin_log_ingestion`
+- parsing de eventos AdminLog hacia eventos normalizados
+- almacenamiento en tablas `rcon_admin_log_*` y `rcon_historical_*`
+- materializacion de partidas cerradas y estadisticas de jugador desde eventos RCON
+- enriquecimiento opcional con snapshots de perfil de jugador, sin tratarlos
+  como hechos autoritativos de una partida
+
+El scoreboard publico queda limitado a enriquecimiento, links confiables o
+fallback historico cuando RCON falla, no tiene cobertura suficiente o no cubre
+una operacion concreta. Elo/MMR sigue pausado y Comunidad Hispana #03 permanece
+fuera de los targets RCON por defecto.
+
+Comandos manuales RCON dentro del contenedor backend:
+
+```powershell
+docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440
+docker compose exec backend python -m app.rcon_historical_worker capture
+```
+
 Si se prefiere operar fuera de Docker, el backend sigue pudiendo arrancar localmente con `python -m app.main` desde `backend/`.
 
 ## Evolucion prevista

ai/architecture-index.md

@@ -80,3 +80,6 @@ Community website repository with a static landing in the current phase and a pl
 - Comunidad Hispana #03 is disabled from default RCON targets, while existing historical/Elo code and persisted data remain available for explicit future reintroduction. Elo/MMR remains paused and decoupled from backend startup.
 - Frontend data consumption should remain progressive, endpoint by endpoint, with static fallbacks preserved during migration.
 - The frontend integration strategy is documented in `docs/frontend-data-consumption-plan.md`.
+- Historical RCON architecture is RCON-first end to end: session capture, AdminLog ingestion, parsed event storage, materialized matches/player stats and optional profile-snapshot enrichment.
+- Public-scoreboard data remains optional enrichment/link source or fallback only; it must not become the normal primary historical path while RCON coverage is available.
+- Manual RCON validation commands include `docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440` and `docker compose exec backend python -m app.rcon_historical_worker capture`.

ai/repo-context.md

@@ -22,6 +22,8 @@ This repository is in foundation stage. The objective is to grow in a controlled
 - Default deployment: `backend` + `frontend`; historical workers are advanced/manual only.
 - Live and historical defaults are RCON-first, with public-scoreboard kept only as historical fallback.
 - Comunidad Hispana #03 is not part of default RCON targets. Historical/Elo code and persisted data are preserved, while Elo/MMR remains paused and decoupled from backend startup.
+- RCON historical data flow is session capture plus AdminLog ingestion, parsed event storage, materialized matches/player stats and optional player profile snapshot enrichment.
+- Public scoreboard may enrich links or fill unsupported historical gaps, but it is not the primary historical source when RCON coverage exists.
 
 ## Repository Areas
 

ai/tasks/done/TASK-132-document-rcon-first-historical-architecture.md

@@ -1,7 +1,7 @@
 ---
 id: TASK-132
 title: Document RCON-first historical architecture
-status: pending
+status: done
 type: documentation
 team: PM
 supporting_teams:
@@ -84,3 +84,10 @@ HLL Vietnam is building a historical/live data platform for Comunidad Hispana se
 - Stage only intended files.
 - Commit the completed implementation.
 - Push the branch to origin.
+
+## Outcome
+
+- Documented the RCON-first historical architecture in README, backend README, decisions and AI context.
+- Covered RCON session capture, AdminLog ingestion/parser/storage, materialized matches/player stats, profile snapshot enrichment, public-scoreboard fallback boundaries, Elo/MMR paused state and Comunidad Hispana #03 disabled defaults.
+- Added the requested manual Docker commands for AdminLog ingestion and historical capture.
+- Validation: `powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1` returned exit code 0, but its nested historical UI regression check emitted an existing frontend assertion about the missing recent-match external action label. No frontend/backend behavior files were changed in this documentation-only task.

backend/README.md

@@ -426,6 +426,28 @@ Captura historica prospectiva por RCON:
   como fallback para operaciones competitivas que aun no tienen paridad RCON
 - no promete backfill retroactivo de matches ya perdidos
 
+Arquitectura RCON-first de datos historicos:
+
+- `app.rcon_historical_worker` captura sesiones RCON y mantiene ventanas
+  competitivas prospectivas.
+- `app.rcon_admin_log_ingestion` ingiere AdminLog para el periodo solicitado.
+- `app.rcon_admin_log_parser` normaliza eventos como inicio/cierre de partida,
+  kills, cambios de equipo, chat y mensajes de perfil.
+- `app.rcon_admin_log_storage` persiste eventos AdminLog deduplicados y
+  snapshots de perfil de jugador.
+- `app.rcon_admin_log_materialization` materializa partidas cerradas y
+  estadisticas por jugador desde eventos RCON.
+- `app.rcon_historical_read_model` expone las lecturas historicas actuales y
+  solo recurre a `public-scoreboard` como fallback/enriquecimiento cuando RCON
+  no cubre la operacion.
+
+Comandos manuales equivalentes dentro de Docker Compose:
+
+```powershell
+docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440
+docker compose exec backend python -m app.rcon_historical_worker capture
+```
+
 Comandos manuales desde `backend/`:
 
 ```powershell

docs/decisions.md

@@ -147,6 +147,19 @@ La politica por defecto para historico vuelve a ser RCON-first:
 mantiene como fallback controlado cuando RCON falla, no tiene cobertura util o
 no soporta todavia una operacion competitiva concreta.
 
+La arquitectura historica RCON-first se compone de captura de sesiones RCON,
+ingesta de AdminLog, parser de eventos, almacenamiento de eventos/snapshots y
+materializacion de partidas y estadisticas por jugador. Los snapshots de perfil
+procedentes de `MESSAGE` enriquecen lecturas de jugador, pero no sustituyen los
+hechos de partida derivados de eventos RCON.
+
+Comandos operativos manuales:
+
+```powershell
+docker compose exec backend python -m app.rcon_admin_log_ingestion --minutes 1440
+docker compose exec backend python -m app.rcon_historical_worker capture
+```
+
 Esta decision no reactiva Elo/MMR dentro del arranque normal del backend. Las
 piezas Elo/MMR, migraciones, datos persistidos y modulos historicos se
 conservan, pero su operativa compleja sigue pausada y desacoplada salvo task