feat: add database maintenance and update home copy

ai/tasks/done/TASK-database-maintenance-docs.md

@@ -0,0 +1,152 @@
+---
+id: TASK-database-maintenance-docs
+title: Document database maintenance operations
+status: pending
+type: documentation
+team: PM
+supporting_teams: [Backend Senior, Arquitecto de Base de Datos]
+roadmap_item: historical-data-maintenance
+priority: medium
+---
+
+# TASK-database-maintenance-docs - Document database maintenance operations
+
+## Goal
+
+Document how database maintenance works, how to audit database growth, and how to run dry-run/apply safely.
+
+## Context
+
+Database cleanup will be implemented as application-level maintenance and scheduled inside historical-runner.
+
+Operators must understand:
+
+- what data is deleted;
+- what data is protected;
+- how to preview deletes;
+- how to enable/disable scheduled cleanup;
+- how to verify table sizes;
+- what not to do in Docker/Portainer.
+
+## Steps
+
+1. Inspect the listed files first.
+2. Add or update operational documentation.
+3. Include exact commands for PowerShell/Docker.
+4. Include safety warnings.
+5. Validate docs diff.
+6. Commit and push the task branch.
+
+## Files to Read First
+
+- `README.md`
+- `backend/README.md`
+- `ai/README.md`
+- `backend/app/database_maintenance.py`
+- `backend/app/historical_runner.py`
+- `docker-compose.yml`
+
+## Expected Files to Modify
+
+Preferred:
+
+- `docs/database-maintenance.md`
+
+Also update if relevant:
+
+- `README.md`
+- `backend/README.md`
+
+Do not modify runtime code in this task.
+
+## Required Documentation Content
+
+Include sections:
+
+- Overview
+- Why cleanup is application-level and not `pg_cron`
+- Scheduled cleanup inside `historical-runner`
+- Environment variables
+- Protected data
+- Deleted data
+- Dry-run command
+- Apply command
+- Table-size audit SQL
+- Row-count/age audit SQL
+- Logs to inspect
+- Docker/Portainer warnings
+- Rollback/restore considerations
+
+Required environment variables:
+
+- `HLL_DB_MAINTENANCE_ENABLED=false`
+- `HLL_DB_MAINTENANCE_INTERVAL_SECONDS=43200`
+- `HLL_RECENT_MATCHES_KEEP=100`
+- `HLL_ADMIN_LOG_NONCRITICAL_RETENTION_DAYS=30`
+- `HLL_ADMIN_LOG_CRITICAL_RETENTION_DAYS=90`
+- `HLL_SERVER_SNAPSHOT_RETENTION_DAYS=14`
+- `HLL_DB_MAINTENANCE_BATCH_SIZE=5000`
+
+Required warnings:
+
+- Never use `docker compose down -v` unless intentionally deleting volumes.
+- Always review dry-run output before enabling apply in production.
+- Do not manually delete protected match/stat rows from PostgreSQL.
+- Keep backups before changing retention settings.
+- Do not add Comunidad Hispana #03 back into RCON targets in this task.
+
+Required SQL:
+
+```sql
+select
+  schemaname,
+  relname as table_name,
+  pg_size_pretty(pg_total_relation_size(relid)) as total_size,
+  pg_size_pretty(pg_relation_size(relid)) as table_size,
+  pg_size_pretty(pg_total_relation_size(relid) - pg_relation_size(relid)) as indexes_size,
+  n_live_tup as estimated_rows,
+  n_dead_tup as estimated_dead_rows
+from pg_stat_user_tables
+order by pg_total_relation_size(relid) desc;
+```
+
+Also include table-specific examples for:
+
+- admin log events by type/date;
+- materialized matches by server/date;
+- server snapshots by date;
+- displayed snapshots count.
+
+## Validation
+
+Run:
+
+```powershell
+git diff --check
+```
+
+If README files are touched, ensure examples are consistent with the current Compose profiles.
+
+## Outcome
+
+Document:
+
+- files changed;
+- docs sections added;
+- validation performed;
+- any follow-up needed.
+
+Codex CLI must commit and push the completed task branch.
+
+Suggested implementation branch:
+
+`task/database-maintenance-docs`
+
+Suggested commit message:
+
+`docs: document database maintenance operations`
+
+## Change Budget
+
+- Documentation only.
+- Prefer fewer than 3 modified files.