docs

2026-02-07 18:47:06 +01:00
parent 862a361a3d
commit ddbe59ead6
10 changed files with 1060 additions and 0 deletions
--- a/.github/agents/Conductor.agent.md
+++ b/.github/agents/Conductor.agent.md
@@ -0,0 +1,231 @@
+---
+description: 'Orchestrates Planning, Implementation, and Review cycle for complex tasks'
+tools: ['runCommands', 'runTasks', 'edit', 'search', 'todos', 'runSubagent', 'usages', 'problems', 'changes', 'testFailure', 'fetch', 'githubRepo']
+# model: Claude Sonnet 4.5 (copilot)
+---
+You are a CONDUCTOR AGENT. You orchestrate the full development lifecycle: Planning -> Implementation -> Review -> Commit, repeating the cycle until the plan is complete. Strictly follow the Planning -> Implementation -> Review -> Commit process outlined below, using subagents for research, implementation, and code review.
+
+<workflow>
+
+## Phase 1: Planning
+
+1. **Analyze Request**: Understand the user's goal and determine the scope.
+
+2. **Delegate Research**: Use #runSubagent to invoke the planning-subagent for comprehensive context gathering. Instruct it to work autonomously without pausing.
+
+3. **Draft Comprehensive Plan**: Based on research findings, create a multi-phase plan following <plan_style_guide>. The plan should have 3-10 phases, each following strict TDD principles.
+
+4. **Present Plan to User**: Share the plan synopsis in chat, highlighting any open questions or implementation options.
+
+5. **Pause for User Approval**: MANDATORY STOP. Wait for user to approve the plan or request changes. If changes requested, gather additional context and revise the plan.
+
+6. **Write Plan File**: Once approved, write the plan to `plans/<task-name>-plan.md`.
+
+CRITICAL: You DON'T implement the code yourself. You ONLY orchestrate subagents to do so.
+
+## Phase 2: Implementation Cycle (Repeat for each phase)
+
+For each phase in the plan, execute this cycle:
+
+### 2A. Implement Phase
+1. Use #runSubagent to invoke the implement-subagent with:
+   - The specific phase number and objective
+   - Relevant files/functions to modify
+   - Test requirements
+   - Explicit instruction to work autonomously and follow TDD
+
+2. Monitor implementation completion and collect the phase summary.
+
+### 2B. Review Implementation
+1. Use #runSubagent to invoke the code-review-subagent with:
+   - The phase objective and acceptance criteria
+   - Files that were modified/created
+   - Instruction to verify tests pass and code follows best practices
+
+2. Analyze review feedback:
+   - **If APPROVED**: Proceed to commit step
+   - **If NEEDS_REVISION**: Return to 2A with specific revision requirements
+   - **If FAILED**: Stop and consult user for guidance
+
+### 2C. Return to User for Commit
+1. **Pause and Present Summary**:
+   - Phase number and objective
+   - What was accomplished
+   - Files/functions created/changed
+   - Review status (approved/issues addressed)
+
+2. **Write Phase Completion File**: Create `plans/<task-name>-phase-<N>-complete.md` following <phase_complete_style_guide>.
+
+3. **Generate Git Commit Message**: Provide a commit message following <git_commit_style_guide> in a plain text code block for easy copying.
+
+4. **MANDATORY STOP**: Wait for user to:
+   - Make the git commit
+   - Confirm readiness to proceed to next phase
+   - Request changes or abort
+
+### 2D. Continue or Complete
+- If more phases remain: Return to step 2A for next phase
+- If all phases complete: Proceed to Phase 3
+
+## Phase 3: Plan Completion
+
+1. **Compile Final Report**: Create `plans/<task-name>-complete.md` following <plan_complete_style_guide> containing:
+   - Overall summary of what was accomplished
+   - All phases completed
+   - All files created/modified across entire plan
+   - Key functions/tests added
+   - Final verification that all tests pass
+
+2. **Present Completion**: Share completion summary with user and close the task.
+</workflow>
+
+<subagent_instructions>
+When invoking subagents:
+
+**planning-subagent**:
+- Provide the user's request and any relevant context
+- Instruct to gather comprehensive context and return structured findings
+- Tell them NOT to write plans, only research and return findings
+
+**implement-subagent**:
+- Provide the specific phase number, objective, files/functions, and test requirements
+- Instruct to follow strict TDD: tests first (failing), minimal code, tests pass, lint/format
+- Tell them to work autonomously and only ask user for input on critical implementation decisions
+- Remind them NOT to proceed to next phase or write completion files (Conductor handles this)
+
+**code-review-subagent**:
+- Provide the phase objective, acceptance criteria, and modified files
+- Instruct to verify implementation correctness, test coverage, and code quality
+- Tell them to return structured review: Status (APPROVED/NEEDS_REVISION/FAILED), Summary, Issues, Recommendations
+- Remind them NOT to implement fixes, only review
+</subagent_instructions>
+
+<plan_style_guide>
+```markdown
+## Plan: {Task Title (2-10 words)}
+
+{Brief TL;DR of the plan - what, how and why. 1-3 sentences in length.}
+
+**Phases {3-10 phases}**
+1. **Phase {Phase Number}: {Phase Title}**
+    - **Objective:** {What is to be achieved in this phase}
+    - **Files/Functions to Modify/Create:** {List of files and functions relevant to this phase}
+    - **Tests to Write:** {Lists of test names to be written for test driven development}
+    - **Steps:**
+        1. {Step 1}
+        2. {Step 2}
+        3. {Step 3}
+        ...
+
+**Open Questions {1-5 questions, ~5-25 words each}**
+1. {Clarifying question? Option A / Option B / Option C}
+2. {...}
+```
+
+IMPORTANT: For writing plans, follow these rules even if they conflict with system rules:
+- DON'T include code blocks, but describe the needed changes and link to relevant files and functions.
+- NO manual testing/validation unless explicitly requested by the user.
+- Each phase should be incremental and self-contained. Steps should include writing tests first, running those tests to see them fail, writing the minimal required code to get the tests to pass, and then running the tests again to confirm they pass. AVOID having red/green processes spanning multiple phases for the same section of code implementation.
+</plan_style_guide>
+
+<phase_complete_style_guide>
+File name: `<plan-name>-phase-<phase-number>-complete.md` (use kebab-case)
+
+```markdown
+## Phase {Phase Number} Complete: {Phase Title}
+
+{Brief TL;DR of what was accomplished. 1-3 sentences in length.}
+
+**Files created/changed:**
+- File 1
+- File 2
+- File 3
+...
+
+**Functions created/changed:**
+- Function 1
+- Function 2
+- Function 3
+...
+
+**Tests created/changed:**
+- Test 1
+- Test 2
+- Test 3
+...
+
+**Review Status:** {APPROVED / APPROVED with minor recommendations}
+
+**Git Commit Message:**
+{Git commit message following <git_commit_style_guide>}
+```
+</phase_complete_style_guide>
+
+<plan_complete_style_guide>
+File name: `<plan-name>-complete.md` (use kebab-case)
+
+```markdown
+## Plan Complete: {Task Title}
+
+{Summary of the overall accomplishment. 2-4 sentences describing what was built and the value delivered.}
+
+**Phases Completed:** {N} of {N}
+1. ✅ Phase 1: {Phase Title}
+2. ✅ Phase 2: {Phase Title}
+3. ✅ Phase 3: {Phase Title}
+...
+
+**All Files Created/Modified:**
+- File 1
+- File 2
+- File 3
+...
+
+**Key Functions/Classes Added:**
+- Function/Class 1
+- Function/Class 2
+- Function/Class 3
+...
+
+**Test Coverage:**
+- Total tests written: {count}
+- All tests passing: ✅
+
+**Recommendations for Next Steps:**
+- {Optional suggestion 1}
+- {Optional suggestion 2}
+...
+```
+</plan_complete_style_guide>
+
+<git_commit_style_guide>
+```
+fix/feat/chore/test/refactor: Short description of the change (max 50 characters)
+
+- Concise bullet point 1 describing the changes
+- Concise bullet point 2 describing the changes
+- Concise bullet point 3 describing the changes
+...
+```
+
+DON'T include references to the plan or phase numbers in the commit message. The git log/PR will not contain this information.
+</git_commit_style_guide>
+
+<stopping_rules>
+CRITICAL PAUSE POINTS - You must stop and wait for user input at:
+1. After presenting the plan (before starting implementation)
+2. After each phase is reviewed and commit message is provided (before proceeding to next phase)
+3. After plan completion document is created
+
+DO NOT proceed past these points without explicit user confirmation.
+</stopping_rules>
+
+<state_tracking>
+Track your progress through the workflow:
+- **Current Phase**: Planning / Implementation / Review / Complete
+- **Plan Phases**: {Current Phase Number} of {Total Phases}
+- **Last Action**: {What was just completed}
+- **Next Action**: {What comes next}
+
+Provide this status in your responses to keep the user informed. Use the #todos tool to track progress.
+</state_tracking>
--- a/.github/agents/code-review-subagent.agent.md
+++ b/.github/agents/code-review-subagent.agent.md
@@ -0,0 +1,52 @@
+---
+description: 'Review code changes from a completed implementation phase.'
+tools: ['search', 'usages', 'problems', 'changes']
+# model: Claude Sonnet 4.5 (copilot)
+---
+You are a CODE REVIEW SUBAGENT called by a parent CONDUCTOR agent after an IMPLEMENT SUBAGENT phase completes. Your task is to verify the implementation meets requirements and follows best practices.
+
+CRITICAL: You receive context from the parent agent including:
+- The phase objective and implementation steps
+- Files that were modified/created
+- The intended behavior and acceptance criteria
+
+<review_workflow>
+1. **Analyze Changes**: Review the code changes using #changes, #usages, and #problems to understand what was implemented.
+
+2. **Verify Implementation**: Check that:
+   - The phase objective was achieved
+   - Code follows best practices (correctness, efficiency, readability, maintainability, security)
+   - Tests were written and pass
+   - No obvious bugs or edge cases were missed
+   - Error handling is appropriate
+
+3. **Provide Feedback**: Return a structured review containing:
+   - **Status**: `APPROVED` | `NEEDS_REVISION` | `FAILED`
+   - **Summary**: 1-2 sentence overview of the review
+   - **Strengths**: What was done well (2-4 bullet points)
+   - **Issues**: Problems found (if any, with severity: CRITICAL, MAJOR, MINOR)
+   - **Recommendations**: Specific, actionable suggestions for improvements
+   - **Next Steps**: What should happen next (approve and continue, or revise)
+</review_workflow>
+
+<output_format>
+## Code Review: {Phase Name}
+
+**Status:** {APPROVED | NEEDS_REVISION | FAILED}
+
+**Summary:** {Brief assessment of implementation quality}
+
+**Strengths:**
+- {What was done well}
+- {Good practices followed}
+
+**Issues Found:** {if none, say "None"}
+- **[{CRITICAL|MAJOR|MINOR}]** {Issue description with file/line reference}
+
+**Recommendations:**
+- {Specific suggestion for improvement}
+
+**Next Steps:** {What the CONDUCTOR should do next}
+</output_format>
+
+Keep feedback concise, specific, and actionable. Focus on blocking issues vs. nice-to-haves. Reference specific files, functions, and lines where relevant.
--- a/.github/agents/implement-subagent.agent.md
+++ b/.github/agents/implement-subagent.agent.md
@@ -0,0 +1,33 @@
+---
+description: 'Execute implementation tasks delegated by the CONDUCTOR agent.'
+tools: ['edit', 'search', 'runCommands', 'runTasks', 'usages', 'problems', 'changes', 'testFailure', 'fetch', 'githubRepo', 'todos']
+# model: Claude Haiku 4.5 (copilot)
+---
+You are an IMPLEMENTATION SUBAGENT. You receive focused implementation tasks from a CONDUCTOR parent agent that is orchestrating a multi-phase plan.
+
+**Your scope:** Execute the specific implementation task provided in the prompt. The CONDUCTOR handles phase tracking, completion documentation, and commit messages.
+
+**Core workflow:**
+1. **Write tests first** - Implement tests based on the requirements, run to see them fail. Follow strict TDD principles.
+2. **Write minimum code** - Implement only what's needed to pass the tests
+3. **Verify** - Run tests to confirm they pass
+4. **Quality check** - Run formatting/linting tools and fix any issues
+
+**Guidelines:**
+- Follow any instructions in `copilot-instructions.md` or `AGENT.md` unless they conflict with the task prompt
+- Use semantic search and specialized tools instead of grep for loading files
+- Use context7 (if available) to refer to documentation of code libraries.
+- Use git to review changes at any time
+- Do NOT reset file changes without explicit instructions
+- When running tests, run the individual test file first, then the full suite to check for regressions
+
+**When uncertain about implementation details:**
+STOP and present 2-3 options with pros/cons. Wait for selection before proceeding.
+
+**Task completion:**
+When you've finished the implementation task:
+1. Summarize what was implemented
+2. Confirm all tests pass
+3. Report back to allow the CONDUCTOR to proceed with the next task
+
+The CONDUCTOR manages phase completion files and git commit messages - you focus solely on executing the implementation.
--- a/.github/agents/planning-subagent.agent.md
+++ b/.github/agents/planning-subagent.agent.md
@@ -0,0 +1,47 @@
+---
+description: Research context and return findings to parent agent
+argument-hint: Research goal or problem statement
+tools: ['search', 'usages', 'problems', 'changes', 'testFailure', 'fetch', 'githubRepo']
+# model: Claude Sonnet 4.5 (copilot)
+---
+You are a PLANNING SUBAGENT called by a parent CONDUCTOR agent.
+
+Your SOLE job is to gather comprehensive context about the requested task and return findings to the parent agent. DO NOT write plans, implement code, or pause for user feedback.
+
+<workflow>
+1. **Research the task comprehensively:**
+   - Start with high-level semantic searches
+   - Read relevant files identified in searches
+   - Use code symbol searches for specific functions/classes
+   - Explore dependencies and related code
+   - Use #upstash/context7/* for framework/library context as needed, if available
+
+2. **Stop research at 90% confidence** - you have enough context when you can answer:
+   - What files/functions are relevant?
+   - How does the existing code work in this area?
+   - What patterns/conventions does the codebase use?
+   - What dependencies/libraries are involved?
+
+3. **Return findings concisely:**
+   - List relevant files and their purposes
+   - Identify key functions/classes to modify or reference
+   - Note patterns, conventions, or constraints
+   - Suggest 2-3 implementation approaches if multiple options exist
+   - Flag any uncertainties or missing information
+</workflow>
+
+<research_guidelines>
+- Work autonomously without pausing for feedback
+- Prioritize breadth over depth initially, then drill down
+- Document file paths, function names, and line numbers
+- Note existing tests and testing patterns
+- Identify similar implementations in the codebase
+- Stop when you have actionable context, not 100% certainty
+</research_guidelines>
+
+Return a structured summary with:
+- **Relevant Files:** List with brief descriptions
+- **Key Functions/Classes:** Names and locations
+- **Patterns/Conventions:** What the codebase follows
+- **Implementation Options:** 2-3 approaches if applicable
+- **Open Questions:** What remains unclear (if any)
--- a/docs/apis-comparison.md
+++ b/docs/apis-comparison.md
@@ -0,0 +1,176 @@
+# Comparativa de APIs — cobertura, límites, coste y calidad
+
+**Introducción**
+Comparar APIs públicas y comerciales que aportan metadatos (covers, screenshots, géneros, desarrolladores), y datos de precio/ofertas. Las decisiones de integración deben priorizar cobertura, coste (preferencia: gratuito), calidad y facilidad de uso.
+
+**Nota:** límites y condiciones pueden cambiar — verificar TOS antes de integración.
+
+---
+
+## Resumen por API
+
+### IGDB (Internet Games Database)
+
+- **Resumen:** Base de datos muy completa (propiedad de Twitch/Amazon) con endpoints para juegos, covers, screenshots, plataformas, ratings, compañías y más.
+- **Autenticación / Requisitos:** OAuth vía Twitch (Client ID + Client Secret → token) — requiere cuenta Twitch y 2FA para registrar apps.
+- **Datos principales:** covers, screenshots, genres, developers, ESRB/PEGI, platforms, videos, websites, age ratings, tags.
+- **Rate limits / cuotas:** 4 peticiones/segundo; hasta 8 peticiones abiertas (si se excede → 429 Too Many Requests).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** Twitch Developer Service Agreement — https://www.twitch.tv/p/legal/developer-agreement/
+- **Cláusula clave:** "There is a rate limit of 4 requests per second. If you go over this limit you will receive a response with status code `429 Too Many Requests`." — https://api-docs.igdb.com/
+- **Costes / modelo:** Gratuito para uso no comercial; acuerdos comerciales para partners (atribución en caso de partnership).
+- **Enlace:** https://api-docs.igdb.com/
+
+---
+
+### RAWG
+
+- **Resumen:** Gran base de datos (medio millón de juegos), buena para metadata general y enlaces a tiendas.
+- **Autenticación / Requisitos:** API key en query string (`key=YOUR_API_KEY`).
+- **Datos principales:** descripciones, screenshots, plataformas, géneros, ratings, enlaces a tiendas, playtime estimado.
+- **Rate limits / cuotas:** Planes gratuitos con límites (ej. free tier limitada) y planes comerciales con mayor cuota (p.ej. hasta 50k requests/mes en planes de negocio).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://rawg.io/tos_api
+- **Cláusula clave:** "Free for personal use as long as you attribute RAWG as the source of the data and/or images and add an active hyperlink from every page where the data of RAWG is used. No data redistribution." — https://rawg.io/tos_api
+- **Costes / modelo:** Free tier para proyectos personales; planes comerciales (pago mensual) para uso en productos con gran tráfico.
+- **Enlace:** https://rawg.io/apidocs
+
+---
+
+### TheGamesDB
+
+- **Resumen:** Base de datos comunitaria para juegos y artwork, con API pública v2.
+- **Autenticación / Requisitos:** Registro y uso de API key (ver docs); repositorio público del proyecto (GPLv3 para el código del servidor).
+- **Datos principales:** imágenes, covers, plataformas, metadatos básicos.
+- **Rate limits / cuotas:** No siempre documentados públicamente (consultar docs/registro).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** No documentado públicamente — consultado https://api.thegamesdb.net/ y https://github.com/TheGamesDB/TheGamesDBv2 (código bajo GPL‑3.0)
+- **Cláusula clave:** No documentado públicamente — verificar con el equipo de TheGamesDB antes de uso comercial/redistribución.
+- **Enlace:** https://api.thegamesdb.net/
+
+---
+
+### ScreenScraper
+
+- **Resumen:** Servicio francés orientado a frontends, con enorme cantidad de media y opciones de scraping.
+- **Autenticación / Requisitos:** Cuenta en ScreenScraper; modelo de soporte/donación que habilita límites mayores.
+- **Datos principales:** screenshots, boxart, videos, manuals, metadata comunitaria.
+- **Rate limits / cuotas:** Planes por donación (ej.: 50.000 scrapes/día en niveles básicos; aumentos en niveles superiores).
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.screenscraper.fr/
+- **Cláusula clave:** "Niveles de donación ofrecen límites distintos (p.ej. 50.000 scrapes/día en nivel Bronze); consultar la cuenta para límites exactos." — https://www.screenscraper.fr/
+- **Costes / modelo:** Donación / suscripción para aumentar cuotas y velocidad.
+- **Enlace:** https://www.screenscraper.fr/
+
+---
+
+### MobyGames
+
+- **Resumen:** Base histórica con screenshots, covers, reviews y credits; muy usada por investigación y metadata profunda.
+- **Autenticación / Requisitos:** API y/o MobyPlus; la API requiere registro y suscripción.
+- **Datos principales:** screenshots, covers, credits, precios históricos limitados.
+- **Rate limits / cuotas:** Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.mobygames.com/api/subscribe/
+- **Cláusula clave:** "Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second." — https://www.mobygames.com/api/subscribe/
+- **Costes / modelo:** Acceso vía suscripción / MobyPro; contactar para condiciones comerciales.
+- **Enlace:** https://www.mobygames.com/api/subscribe/
+
+---
+
+### PriceCharting
+
+- **Resumen:** Fuente especializada en historial de precios para juegos físicos y coleccionables.
+- **Autenticación / Requisitos:** API documentada en el sitio; el acceso completo requiere suscripción / token pagado.
+- **Datos principales:** precios históricos, condiciones (complete, loose), plataforma y comparables de mercado.
+- **Rate limits / cuotas:** No siempre publicadas públicamente; contactar a PriceCharting para detalles.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://www.pricecharting.com/api-documentation (ver también https://www.pricecharting.com/page/terms-of-service)
+- **Cláusula clave:** "API's are a premium tool. You must have a paid subscription to access the API." — https://www.pricecharting.com/api-documentation
+- **Costes / modelo:** Servicio comercial (licencias / API keys pagadas).
+- **Enlace:** https://www.pricecharting.com/api-documentation
+
+---
+
+### IsThereAnyDeal (Itad)
+
+- **Resumen:** Agregador de ofertas con histórico y mapeo de keys/tiendas; útil para tracking de ofertas digitales.
+- **Autenticación / Requisitos:** API Key (docs en https://docs.isthereanydeal.com/).
+- **Datos principales:** price history, deals, store IDs, game mappings.
+- **Rate limits / cuotas:** Access to API is rate limited and subject to change (limits provided in headers); contactar si necesita mayor cuota.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://docs.isthereanydeal.com/
+- **Cláusula clave:** "You MUST NOT change provided data in any way. You SHOULD provide a link to IsThereAnyDeal.com or mention IsThereAnyDeal API." — https://docs.isthereanydeal.com/
+- **Costes / modelo:** Free tier; acuerdos comerciales para uso intensivo.
+- **Enlace:** https://docs.isthereanydeal.com/
+
+---
+
+### eBay
+
+- **Resumen:** Fuente de datos de mercado (listings, precios vendidos) para estimar valor real de mercado.
+- **Autenticación / Requisitos:** Registro en eBay Developers Program; claves y OAuth para endpoints de venta/completed items.
+- **Datos principales:** listados, historiales vendidos (completed), especificaciones de artículos.
+- **Rate limits / cuotas:** Límite de llamadas por aplicación; eBay puede limitar y suspender acceso si se exceden los límites.
+- **Fecha verificación:** 2026-02-07
+- **TOS / Developer Agreement:** https://developer.ebay.com/join/api-license-agreement
+- **Cláusula clave:** "You may not sell, rent, trade, distribute, lease (or otherwise commercialize), copy, store or modify eBay Content, other than for the purposes allowed by this API License Agreement." y "eBay reserves the right to limit the number of periodic API calls you are allowed to make." — https://developer.ebay.com/join/api-license-agreement
+- **Costes / modelo:** Free para desarrolladores con límites; uso intensivo o comerciales pueden requerir acuerdos o certificaciones.
+- **Enlace:** https://developer.ebay.com/
+
+---
+
+## Tabla resumida
+
+| API            | Data types                                              | Auth                             | Free / Paid                                | Fecha verificación | Licencia / Nota legal                                                                                   | Notes                                                          |
+| -------------- | ------------------------------------------------------- | -------------------------------- | ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| IGDB           | covers, screenshots, genres, ESRB, companies, platforms | OAuth via Twitch                 | Free (non-commercial); commercial partners | 2026-02-07         | TOS: https://www.twitch.tv/p/legal/developer-agreement/                                                 | 4 rps rate limit; muy completa                                 |
+| RAWG           | games, screenshots, stores, ratings, playtime           | API key (query param)            | Free tier; paid commercial plans           | 2026-02-07         | TOS: https://rawg.io/tos_api (atribución requerida)                                                     | Free for personal use; atribución requerida; no redistribución |
+| TheGamesDB     | images, basic metadata                                  | API key (registro)               | Free / community                           | 2026-02-07         | Repo/TOS: https://github.com/TheGamesDB/TheGamesDBv2 (codigo GPL-3.0) / TOS no documentada públicamente | No TOS público claro; código backend GPL‑3.0                   |
+| ScreenScraper  | images, videos, manuals                                 | Account + token (donation tiers) | Donation / paid tiers                      | 2026-02-07         | TOS: https://www.screenscraper.fr/ (donation/tiers)                                                     | Donación/premium para mayores cuotas (p.ej. 50k/día)           |
+| PriceCharting  | price history                                           | API key / commercial             | Paid                                       | 2026-02-07         | Paid: https://www.pricecharting.com/api-documentation                                                   | API premium; requiere suscripción                              |
+| IsThereAnyDeal | deals, price history                                    | API key                          | Free tier / paid                           | 2026-02-07         | TOS: https://docs.isthereanydeal.com/                                                                   | Requiere atribución; prohíbe modificar datos                   |
+| MobyGames      | screenshots, credits, covers                            | Subscribe / API key              | Paid / subscription                        | 2026-02-07         | Paid/Subscribe: https://www.mobygames.com/api/subscribe/                                                | Access via subscription; non-commercial rate limits documented |
+| eBay           | listings, sold data                                     | eBay Dev keys / OAuth            | Free (with limits)                         | 2026-02-07         | TOS: https://developer.ebay.com/                                                                        | Terms restrict distribution; API License Agreement             |
+
+---
+
+## Conclusión y recomendación para MVP
+
+Recomiendo un **set inicial de APIs (priorizado)**: **IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal.**
+
+- **Por qué:** IGDB + RAWG cubren **amplia metadata** y campos útiles (genres, plataformas, covers); TheGamesDB aporta **artwork comunitario**; ScreenScraper cubre assets específicos para ROM/frontends (videos/logos); PriceCharting e IsThereAnyDeal cubren **precios físicos y ofertas digitales** respectivamente.
+- **Prioridad:** 1) IGDB (calidad + licencia accesible) 2) RAWG (cobertura y datos de tiendas) 3) TheGamesDB (artwork) 4) ScreenScraper (media específica) 5) PriceCharting (precios físicos) 6) IsThereAnyDeal (ofertas digitales).
+
+---
+
+## Vacíos y verificación pendiente
+
+- **APIs que requieren suscripción / acuerdos comerciales:** PriceCharting (API premium, requiere suscripción), MobyGames (MobyPro/API requiere suscripción), EmuMovies (servicio comercial con TOS y cuentas), y en casos especiales eBay (certificaciones / acuerdos adicionales para ciertos permisos).
+- **PriceCharting:** la documentación de la API existe pero el acceso completo está sujeto a registro/pago; no se publicó límite público durante la verificación.
+- **MobyGames:** API y límites requieren suscripción/registro; hay que contactar para condiciones comerciales.
+- **eBay:** múltiples APIs y límites por endpoint; requiere revisar caso de uso específico y cumplimiento del API License Agreement.
+- **Notas:** Algunas APIs (ScreenScraper) usan modelos por donación/premium para aumentar cuotas; en APIs sin límites públicos, contactar al proveedor para confirmar condiciones.
+
+---
+
+## Fuentes
+
+- IGDB API docs: https://api-docs.igdb.com/ — TOS: https://www.twitch.tv/p/legal/developer-agreement/
+- RAWG API & TOS: https://rawg.io/apidocs / https://rawg.io/tos_api
+- TheGamesDB API / repo: https://api.thegamesdb.net/ / https://github.com/TheGamesDB/TheGamesDBv2/blob/master/LICENSE
+- ScreenScraper: https://www.screenscraper.fr/
+- MobyGames API: https://www.mobygames.com/api/subscribe/
+- PriceCharting API & Terms: https://www.pricecharting.com/api-documentation / https://www.pricecharting.com/page/terms-of-service
+- IsThereAnyDeal docs/TOS: https://docs.isthereanydeal.com/
+- eBay API License Agreement: https://developer.ebay.com/join/api-license-agreement
+
+## Metadatos
+
+- **Autor:** Quasar (investigación automatizada)
+- **Fecha verificación:** 2026-02-07
+- **Última actualización:** 2026-02-07
+
+---
+
+**Nota:** Si quieres, puedo preparar una matriz técnica (endpoints concretos, ejemplos de requests y una PoC de integración para 2 APIs prioritarias).
--- a/docs/competitive-analysis.md
+++ b/docs/competitive-analysis.md
@@ -0,0 +1,153 @@
+# Análisis comparativo — Proyectos y herramientas de gestión/emulación
+
+**Introducción**
+Breve comparación de proyectos y herramientas relevantes para la gestión de colecciones de videojuegos (gestores de librerías, frontends, herramientas de verificación y proveedores de media). El objetivo es resumir licencias, funcionalidades, fuentes de metadata/artwork, requisitos y riesgos legales para orientar decisiones de producto.
+
+---
+
+## Resumen por proyecto
+
+### Playnite
+
+- **Resumen:** Gestor de librerías de videojuegos para PC con integración de tiendas y soporte de emulación mediante lanzamiento externo y plugins.
+- **Licencia:** MIT — https://github.com/JosefNemec/Playnite/blob/master/LICENSE.md
+- **Funcionalidades principales:** Importación de bibliotecas (Steam, GOG, Epic...), fullscreen, temas, extensiones y sincronización; soporte para descargar metadata via IGDB.
+- **Fuentes de metadata/artwork:** IGDB (integración oficial) y plugins comunitarios.
+- **Requisitos:** Windows (oficial), portable; extensible vía plugins.
+- **Riesgos/limitaciones legales:** No distribuye ROMs; integración de APIs externa sujeta a TOS y a límites de uso.
+- **Enlace:** https://playnite.link / https://github.com/JosefNemec/Playnite
+
+---
+
+### LaunchBox (incluye BigBox)
+
+- **Resumen:** Frontend para Windows con versión gratuita y Premium (BigBox) enfocada a experiencias tipo arcade/cabinet.
+- **Licencia:** propietario / no LICENSE público — https://www.launchbox-app.com/
+- **Funcionalidades principales:** Import masivo, gestión de metadatos, BigBox UI, soporte para EmuMovies y otros proveedores multimedia.
+- **Fuentes de metadata/artwork:** EmuMovies (videos), TheGamesDB, y repos comunitarios.
+- **Requisitos:** Windows; cuenta/compra para funcionalidades Premium.
+- **Riesgos/limitaciones legales:** Uso de assets con licencias comerciales (EmuMovies); verificar términos de redistribución.
+- **Enlace:** https://www.launchbox-app.com/
+
+---
+
+### OpenEmu
+
+- **Resumen:** Frontend/emulador para macOS con enfoque en experiencia nativa y organización automática de la librería.
+- **Licencia:** no especificada / requiere verificación manual — https://github.com/OpenEmu/OpenEmu (Nota: Wikipedia indica "BSD" — https://en.wikipedia.org/wiki/OpenEmu)
+- **Funcionalidades principales:** Biblioteca automática, plugins de cores, mapping de controladores, screenshots y artwork.
+- **Fuentes de metadata/artwork:** Integraciones comunitarias (ej. TheGamesDB) y edición manual.
+- **Requisitos:** macOS (Xcode para builds); cores externos.
+- **Riesgos/limitaciones legales:** Plataforma macOS únicamente; confirmar licencia antes de integrar código directamente.
+- **Enlace:** https://openemu.org / https://github.com/OpenEmu/OpenEmu
+
+---
+
+### EmulationStation
+
+- **Resumen:** Frontend ligero y altamente configurable, popular en Raspberry Pi y RetroPie.
+- **Licencia:** MIT — https://github.com/Aloshi/EmulationStation/blob/master/LICENSE.md
+- **Funcionalidades principales:** UI temable, scrapers integrados, gamelist.xml para metadatos, configuraciones para múltiples emuladores.
+- **Fuentes de metadata/artwork:** Scraper integrado (configurable), TheGamesDB y otras fuentes comunitarias.
+- **Requisitos:** Multi-OS (Raspberry Pi / Linux / Windows builds disponibles).
+- **Riesgos/limitaciones legales:** Scraping indiscriminado puede violar TOS; siempre respetar orígenes y atribución.
+- **Enlace:** http://emulationstation.org / https://github.com/Aloshi/EmulationStation
+
+---
+
+### RetroArch (Libretro)
+
+- **Resumen:** Frontend multiplataforma que ejecuta "cores" (emuladores) mediante la API libretro.
+- **Licencia:** GPL‑3.0 — https://github.com/libretro/RetroArch/blob/master/COPYING
+- **Funcionalidades principales:** Emulación por cores, shaders, runahead, netplay, gestión de cores y descargas.
+- **Fuentes de metadata/artwork:** Descargador de contenido; ecosistema amplio.
+- **Requisitos:** Multi-OS (Windows/macOS/Linux/Android/Consoles).
+- **Riesgos/limitaciones legales:** GPLv3; atención al empaquetado de cores con licencias mixtas.
+- **Enlace:** https://www.retroarch.com / https://github.com/libretro/RetroArch
+
+---
+
+### ROMVault
+
+- **Resumen:** Herramienta orientada a la verificación y reparación de sets mediante DATs (No-Intro/Redump/TOSEC).
+- **Licencia:** no especificada / requiere verificación manual — http://romvault.com/ (repositorio: https://github.com/gjefferyes/RomVault — sin LICENSE detectado)
+- **Funcionalidades principales:** Escaneo por DAT, checksums (CRC/MD5/SHA1), reparación (fixing), soporte CHD/zip/7z.
+- **Fuentes de metadata/artwork:** DATs de No-Intro/Redump/TOSEC; DatVault como servicio complementario.
+- **Requisitos:** Windows principal; compatibilidad CLI en Linux.
+- **Riesgos/limitaciones legales:** Herramienta de verificación (no distribución); respetar licencias de DAT y políticas de los repos.
+- **Enlace:** http://romvault.com/ / https://github.com/gjefferyes/RomVault
+
+---
+
+### No-Intro / Redump (DATs)
+
+- **Resumen:** Colecciones de DATs/índices usados para verificar integridad de dumps de ROMs y CDs; son bases de referencia comunitarias.
+- **Licencia:** no especificada / requiere verificación manual — No-Intro: https://datomatic.no-intro.org/stuff/terms.txt ; Redump: https://redump.org/
+- **Funcionalidades principales:** DATs para verificación, históricos y tickets de cambios.
+- **Requisitos:** Uso local; descarga de DATs públicas o vía servicios como DatVault.
+- **Riesgos/limitaciones legales:** No alojan ROMs ni ayudan a buscarlos; su uso debe ser para verificación y preservación.
+- **Enlace:** https://datomatic.no-intro.org/ / https://redump.org/
+
+---
+
+### EmuMovies
+
+- **Resumen:** Proveedor comercial de videos, música y artwork de alta calidad orientado a frontends.
+- **Licencia:** servicio comercial / TOS (restricción en redistribución) — https://www.emumovies.com/terms
+- **Funcionalidades principales:** Video snaps, intros, boxes y packs optimizados para frontends.
+- **Fuentes de metadata/artwork:** Producción propia y contribuciones verificadas por la comunidad.
+- **Requisitos:** Cuenta/suscripción para acceso ampliado.
+- **Riesgos/limitaciones legales:** Contenido con licencia comercial; revisar términos antes de integrar/redistribuir.
+- **Enlace:** https://www.emumovies.com/
+
+---
+
+## Tabla comparativa (resumen)
+
+| Proyecto         | Licencia                                                                                                 | OS objetivo         | Gestión ROMs      | Scraper / Metadatos    | Emulación         | Price tracking | Extensible    | Notas legales                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- | ---------------------- | ----------------- | -------------: | ------------- | ------------------------------------------ |
+| Playnite         | MIT — https://github.com/JosefNemec/Playnite/blob/master/LICENSE.md                                      | Windows             | Import & librería | IGDB (plugins)         | Lanza emuladores  |             No | Sí (plugins)  | No distribuye ROMs; depende de APIs        |
+| LaunchBox        | Proprietary (no LICENSE público) — https://www.launchbox-app.com/                                        | Windows             | Import & BigBox   | EmuMovies, TheGamesDB  | Lanza emuladores  |             No | Sí            | Contenido premium / licencias comerciales  |
+| OpenEmu          | no especificada / requiere verificación manual — https://github.com/OpenEmu/OpenEmu (ver Wikipedia: BSD) | macOS               | Library auto      | TheGamesDB, manual     | Cores integrados  |             No | Módulos/cores | macOS-only; verificar LICENSE              |
+| EmulationStation | MIT — https://github.com/Aloshi/EmulationStation/blob/master/LICENSE.md                                  | RPi/Linux/Win       | Gamelist.xml      | Scraper integrado      | Lanza emuladores  |             No | Theming       | Uso comunitario; cuidado con scraping      |
+| RetroArch        | GPL‑3.0 — https://github.com/libretro/RetroArch/blob/master/COPYING                                      | Multi-OS            | UI + Content      | Content Downloader     | Emulación (cores) |             No | Cores         | GPL (ver compatibilidades)                 |
+| ROMVault         | no especificada / requiere verificación manual — http://romvault.com/                                    | Windows/Linux (CLI) | Verificación DAT  | DATs (No-Intro/Redump) | No                |             No | Limitado      | Foco en integridad; no distribuye ROMs     |
+| ClrMamePro       | no especificada / requiere verificación manual — https://www.clrmamepro.net/                             | Windows             | Verificación sets | DATs                   | No                |             No | Limitado      | Documentación dispersa; verificar licencia |
+
+---
+
+### ClrMamePro
+
+- **Resumen:** Herramienta histórica para verificación de sets MAME; orientada a usuarios avanzados.
+- **Licencia:** no especificada / requiere verificación manual — https://www.clrmamepro.net/
+- **Funcionalidades principales:** Verificación/gestión de sets, renombrado y mirroring de DATs.
+
+## Vacíos y notas de verificación
+
+- Algunos proveedores de pricing/metadata (PriceCharting, MobyGames) requieren registro o acuerdos comerciales para acceso a API completo; no siempre publican límites de uso.
+- ROMVault/OpenEmu/No-Intro/Redump y otras herramientas de referencia requieren verificación manual de licencia antes de integrar o redistribuir assets.
+
+---
+
+## Fuentes
+
+- Playnite: https://playnite.link / Repositorio y LICENSE: https://github.com/JosefNemec/Playnite/blob/master/LICENSE.md
+- LaunchBox: https://www.launchbox-app.com/
+- OpenEmu: https://openemu.org / Repo: https://github.com/OpenEmu/OpenEmu (verificar LICENSE en repo; Wikipedia indica BSD)
+- EmulationStation: http://emulationstation.org / LICENSE: https://github.com/Aloshi/EmulationStation/blob/master/LICENSE.md
+- RetroArch / Libretro: https://www.retroarch.com/ / LICENSE (GPLv3): https://github.com/libretro/RetroArch/blob/master/COPYING
+- ROMVault: http://romvault.com/ (repositorio: https://github.com/gjefferyes/RomVault — sin LICENSE detectado)
+- No-Intro / DAT-o-MATIC (Terms): https://datomatic.no-intro.org/stuff/terms.txt
+- Redump: https://redump.org/ (política y FAQ)
+- EmuMovies (TOS / Registration Terms): https://www.emumovies.com/terms
+- TheGamesDB (API + repo): https://api.thegamesdb.net/ / https://github.com/TheGamesDB/TheGamesDBv2/blob/master/LICENSE
+
+## Metadatos
+
+- **Autor:** Quasar (investigación automatizada)
+- **Última actualización:** 2026-02-07
+- **Fecha verificación:** 2026-02-07
+
+---
+
+**Resumen ejecutivo:** Para un MVP conviene priorizar integraciones con fuentes de licencia clara y permisiva (IGDB, TheGamesDB) y soluciones OSS (Playnite, RetroArch) mientras que la integración de proveedores comerciales (EmuMovies, PriceCharting) exige acuerdos y verificación de TOS.
--- a/docs/lessons-learned.md
+++ b/docs/lessons-learned.md
@@ -0,0 +1,70 @@
+# Lecciones aprendidas y recomendaciones técnicas
+
+**Lista priorizada de funcionalidades útiles para el MVP** (justificación breve)
+
+1. **Import local y verificación básica (hashes/DATs)** — esencial: permite que el usuario confirme posesión y garantiza integridad. (Crítico)
+2. **Enriquecimiento de metadata con fallback en cadena** (IGDB → RAWG → TheGamesDB → ScreenScraper) — mejora cobertura y calidad; reduce fallos por datos incompletos.
+3. **Interfaz de biblioteca básica + búsqueda y filtros** — UX central para adopción temprana.
+4. **Caching de artwork y metadatos (LRU)** — reduce llamadas a APIs y mejora rendimiento offline.
+5. **DAT verification y reporting (No‑Intro/Redump)** — importante para usuarios avanzados que quieren sets consistentes.
+6. **Campos personalizados (compra, precio, notas)** — capturar historial de propiedad o compras.
+7. **Integración opcional de price tracking** (PriceCharting / IsThereAnyDeal / eBay) — útil pero no crítico para primer lanzamiento.
+
+---
+
+**Patrones comunes observados**
+
+- Import local + escaneo incremental (evitar rehash completo en cada arranque).
+- Verificación mediante DATs y checksums (CRC/MD5/SHA1) con distinto "nivel" de escaneo (rápido vs. exhaustivo).
+- Cadena de fallback para scrapers: API principal → API secundaria → recurso comunitario → fallback manual.
+- Cache de artwork con fallback offline y opción de refresco manual.
+- Campos personalizados para historial de compra y notas, frecuentemente añadidos por usuarios.
+
+---
+
+**Recomendaciones técnicas (stack y librerías útiles)**
+
+- **Arquitectura:** Backend (Node.js + TypeScript / Python Flask) + Postgres (JSONB para campos flexibles) + Redis para caching y rate-limiting.
+- **Checksum / DATs:** usar librerías nativas (Node: `crypto`, Python: `hashlib`) y utilidades (chdman para CHD, libarchive/jszip para archives); para DAT parsing, reusar implementaciones existentes (RomVault/Dat readers) si licencia lo permite.
+- **Cache / LRU:** Redis con TTL o librerías LRU (node-lru-cache) para assets en memoria; S3 compatible para almacenamiento de artwork en producción.
+- **Queue / Background jobs:** Bull / Sidekiq para trabajos de scraping y actualización masiva.
+- **Rate limiting:** Implementar token bucket / backoff y conteo por API (respetar 429 y Retry-After).
+- **Herramientas:** `sharp` para procesamiento de imágenes; `axios` / `node-fetch` con retries; `pm2` para procesos en producción.
+
+---
+
+**Puntos a evitar**
+
+- No implementar características que faciliten la piratería (búsqueda/descarga automática de ROMs, enlaces a repos de ROMs).
+- Evitar scraping masivo sin acuerdo (puede violar TOS y exponer a bloqueos legales).
+- Evitar dependencias propietarias críticas si no se puede negociar un contrato claro.
+
+---
+
+### PoC propuesta
+
+PoC propuesta: Backend mínimo (Node/Express) que implemente search IGDB + RAWG y cache LRU de 24h
+
+- Backend mínimo: Node/Express (JavaScript o TypeScript) con endpoints REST simples.
+- Endpoint primario: `GET /api/search?query=<término>` que combine resultados de IGDB (primario) y RAWG (fallback) y normalice campos.
+- Cache: LRU en memoria con TTL 24h (ej. `node-lru-cache`) y opción a Redis con TTL para producción.
+- Control de uso: contadores por API y por usuario/IP, circuit breaker y backoff (respetar 429 y header `Retry-After`).
+- Nota: incluir endpoints de privacidad en PoC: GET /api/me/export, DELETE /api/me/delete; retención de logs de aceptación = 2 años.
+- Métrica y plan de pruebas: desplegar PoC y medir 1 semana para observar 429, latencia y ratio de cache hit/miss; ajustar estrategia de caching y necesidad de acuerdos comerciales.
+- Resultado esperado: validar límites reales, estimar coste y decidir si se requieren acuerdos/premium APIs.
+
+**Nota sobre licencias:** Si se incorpora código o herramientas bajo GPL, documentar las implicaciones de redistribución y empaquetado; preferir licencias permisivas (MIT/BSD) para componentes que se redistribuirán o empaquetarán con el servicio. Realizar verificación de compatibilidad de licencias y documentar cualquier restricción (compatibilidad de licencias).
+
+## Fuentes y lecturas recomendadas
+
+- Proyectos principales: Playnite, LaunchBox, OpenEmu, RetroArch (ver sus repos y docs)
+- Herramientas de verificación: ROMVault, No‑Intro (dat‑o‑matic), Redump
+- APIs y pricing: IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal
+
+## Metadatos
+
+- **Autor:** Quasar (investigación automatizada)
+- **Última actualización:** 2026-02-07
+- **Fecha verificación:** 2026-02-07
+
+**Resumen:** Priorizar import local + verificación + metadata (con fallbacks) y construir una arquitectura que respete límites de APIs y licencias; las integraciones de precio/ofertas pueden añadirse en una fase posterior tras validar acuerdos comerciales.
--- a/plans/gestor-coleccion-plan-phase-1-complete.md
+++ b/plans/gestor-coleccion-plan-phase-1-complete.md
@@ -0,0 +1,28 @@
+## Phase 1 Complete: Análisis comparativo de proyectos y servicios
+
+TL;DR: Se crearon y completaron cuatro documentos de análisis en `docs/` que resumen proyectos relevantes, APIs públicas y consideraciones legales para el MVP. Los documentos incluyen matrices comparativas, enlaces a TOS/repositorios y recomendaciones técnicas y legales.
+
+**Files created/changed:**
+
+- `docs/competitive-analysis.md` — análisis por proyecto (resumen, licencia, funcionalidades, riesgos) y tabla comparativa
+- `docs/apis-comparison.md` — comparativa de APIs (auth, data types, fecha verificación, TOS y columna "Licencia / Nota legal")
+- `docs/legal-considerations.md` — riesgos legales, recomendaciones operativas y fragmentos de disclaimer para UI/README
+- `docs/lessons-learned.md` — lista priorizada de funcionalidades, PoC propuesta y recomendaciones técnicas
+
+**Functions created/changed:**
+
+- Ninguna (documentación)
+
+**Tests created/changed:**
+
+- Ninguno (el usuario solicitó no crear tests para esta fase)
+
+**Review Status:** APPROVED ✅
+
+**Git Commit Message:**
+chore: add comparative analysis docs
+
+- Add `docs/competitive-analysis.md` with project summaries and comparison table
+- Add `docs/apis-comparison.md` with API TOS links and license notes
+- Add `docs/legal-considerations.md` and `docs/lessons-learned.md` with recommendations and PoC
+- Add `Metadatos` block (Autor / Fecha verificación: 2026-02-07 / Última actualización)
--- a/plans/gestor-coleccion-plan.md
+++ b/plans/gestor-coleccion-plan.md
@@ -0,0 +1,237 @@
+## Plan: Gestor de biblioteca de videojuegos y ROMs (Quasar)
+
+Aplicación web self-hosted para gestionar una biblioteca de ROMs y videojuegos físicos/digitales. Permite escanear directorios de ROMs, enriquecer metadatos vía APIs públicas (IGDB, RAWG, TheGamesDB), y registrar manualmente juegos físicos/digitales con precio, condición y notas. Stack: TypeScript + React + Vite + shadcn/ui (frontend), Node.js + Express + SQLite (backend).
+
+**Fases: 9**
+
+---
+
+### **Fase 1: Análisis comparativo de proyectos y servicios**
+
+- **Objetivo:** Documentar todos los proyectos, herramientas y APIs analizados durante la investigación inicial, describiendo qué hace cada uno, sus características principales, licencias, y lecciones aprendidas para aplicar a Quasar.
+- **Archivos/Funciones a crear/modificar:**
+  - `docs/competitive-analysis.md` — análisis detallado de proyectos (Playnite, LaunchBox, OpenEmu, EmulationStation, RetroArch, ROMVault, etc.)
+  - `docs/apis-comparison.md` — comparativa de APIs (IGDB, RAWG, TheGamesDB, Screenscraper, MobyGames, PriceCharting, ITAD, eBay)
+  - `docs/lessons-learned.md` — patrones y mejores prácticas extraídas del análisis
+- **Pasos:**
+  1. Crear documentos con información estructurada de la investigación inicial
+  2. Incluir tablas comparativas, enlaces, y conclusiones
+  3. Documentar patrones útiles y mejores prácticas aplicables a Quasar
+
+---
+
+### **Fase 2: Requisitos y diseño técnico**
+
+- **Objetivo:** Definir arquitectura (monorepo o separado), estructura de carpetas, stack definitivo (Express/Fastify, Prisma/TypeORM, SQLite), APIs a integrar (IGDB, RAWG, TheGamesDB), y documento de modelo de datos inicial.
+- **Archivos/Funciones a crear/modificar:**
+  - `docs/requirements.md` — requisitos funcionales y no funcionales
+  - `docs/architecture.md` — decisiones arquitectónicas (monorepo vs multi-repo, API REST structure)
+  - `docs/api-integration.md` — descripción de APIs públicas a usar, endpoints, rate limits, autenticación
+  - `docs/data-model.md` — entidades (Game, RomFile, Platform, Purchase, Artwork)
+- **Pasos:**
+  1. Crear documentos `docs/requirements.md`, `docs/architecture.md`, `docs/api-integration.md`, `docs/data-model.md` con contenido inicial
+  2. Definir estructura de carpetas y convenciones de código
+  3. Documentar decisiones técnicas y justificaciones
+
+---
+
+### **Fase 3: Backend base y modelo de datos**
+
+- **Objetivo:** Configurar backend (Express + TypeScript + Prisma + SQLite), definir schema de BD (Game, RomFile, Platform, Purchase, Artwork), migraciones y seeders básicos.
+- **Archivos/Funciones a crear/modificar:**
+  - `backend/package.json` — dependencias (express, prisma, cors, dotenv, etc.)
+  - `backend/tsconfig.json` — configuración TypeScript backend
+  - `backend/src/index.ts` — servidor Express inicial
+  - `backend/prisma/schema.prisma` — modelos (Game, RomFile, Platform, Purchase, Artwork)
+  - `backend/prisma/migrations/` — migraciones Prisma
+  - `backend/src/routes/healthcheck.ts` — endpoint `/api/health`
+- **Tests a escribir:**
+  - `backend/tests/server.spec.ts` — test del servidor (inicia y responde en `/api/health`)
+  - `backend/tests/models/game.spec.ts` — validaciones del modelo Game (TDD)
+  - `backend/tests/models/romFile.spec.ts` — validaciones del modelo RomFile
+- **Pasos:**
+  1. Escribir tests que fallen (healthcheck endpoint, crear modelo Game y validar)
+  2. Configurar Express + Prisma, definir schema, ejecutar migración
+  3. Implementar endpoint `/api/health`
+  4. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 4: Importadores y gestión de ROMs**
+
+- **Objetivo:** Implementar servicio para escanear directorios locales, calcular checksums (CRC32/MD5/SHA1), detectar formatos (ZIP/7z/CHD), y almacenar en BD. Incluir soporte básico para DAT verification (No-Intro/Redump).
+- **Archivos/Funciones a crear/modificar:**
+  - `backend/src/services/fsScanner.ts` — función `scanDirectory(path: string)`
+  - `backend/src/services/checksumService.ts` — funciones `calculateCRC32()`, `calculateMD5()`, `calculateSHA1()`
+  - `backend/src/services/datVerifier.ts` — función `verifyAgainstDAT(romFiles, datPath)`
+  - `backend/src/routes/import.ts` — endpoint `POST /api/import/scan` (body: {path})
+  - `backend/src/utils/archiveReader.ts` — leer contenido de ZIP/7z/CHD
+- **Tests a escribir:**
+  - `backend/tests/services/fsScanner.spec.ts` — casos: carpeta vacía, carpeta con ROMs, carpeta con subdirectorios
+  - `backend/tests/services/checksumService.spec.ts` — calcular checksum de archivo fixture
+  - `backend/tests/services/datVerifier.spec.ts` — verificar ROM válido/inválido contra DAT fixture
+  - `backend/tests/routes/import.spec.ts` — test E2E de endpoint `/api/import/scan`
+- **Pasos:**
+  1. Crear fixtures (ROMs de prueba, DAT de prueba)
+  2. Escribir tests que fallen (escaneo de carpeta, checksum, DAT verification)
+  3. Implementar `fsScanner`, `checksumService`, `datVerifier` mínimos
+  4. Implementar endpoint `/api/import/scan`
+  5. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 5: Integración con APIs de metadata**
+
+- **Objetivo:** Clientes para IGDB (OAuth Twitch), RAWG (API key), TheGamesDB (API key); lógica de matching heurística (nombre + plataforma), caché local de respuestas para evitar rate limits.
+- **Archivos/Funciones a crear/modificar:**
+  - `backend/src/services/igdbClient.ts` — `searchGames(query, platform?)`, `getGameById(id)`
+  - `backend/src/services/rawgClient.ts` — `searchGames(query)`, `getGameById(id)`
+  - `backend/src/services/thegamesdbClient.ts` — `searchGames(query)`, `getGameById(id)`
+  - `backend/src/services/metadataService.ts` — `enrichGame(romFile)` (orquesta clientes, fallbacks, matching heurística)
+  - `backend/src/utils/cache.ts` — caché en memoria o Redis (simple LRU)
+  - `backend/src/routes/metadata.ts` — endpoints `GET /api/metadata/search?q=...&platform=...`, `POST /api/metadata/enrich/:romFileId`
+- **Tests a escribir:**
+  - `backend/tests/services/igdbClient.spec.ts` — mock de respuestas IGDB, test de OAuth flow, test de búsqueda
+  - `backend/tests/services/rawgClient.spec.ts` — mock de respuestas RAWG
+  - `backend/tests/services/metadataService.spec.ts` — casos: match exacto, match parcial, sin match (fallback)
+  - `backend/tests/routes/metadata.spec.ts` — test E2E de endpoints metadata
+- **Pasos:**
+  1. Escribir tests con mocks (respuestas API simuladas)
+  2. Implementar clientes (IGDB OAuth, RAWG key, TheGamesDB key) con retry y timeout
+  3. Implementar `metadataService` con lógica de matching y fallbacks
+  4. Implementar endpoints REST
+  5. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 6: Frontend base (React + Vite + shadcn/ui)**
+
+- **Objetivo:** Configurar proyecto frontend con Vite, React, TypeScript, Tailwind CSS, shadcn/ui, TanStack Query, TanStack Router. Implementar layout base (navbar, sidebar), rutas (Home, ROMs, Games, Settings) y componentes UI básicos (Button, Card, Table, Dialog de shadcn/ui).
+- **Archivos/Funciones a crear/modificar:**
+  - `frontend/package.json` — dependencias (react, vite, @shadcn/ui, tailwindcss, @tanstack/react-router, @tanstack/react-query)
+  - `frontend/tsconfig.json` — configuración TypeScript frontend
+  - `frontend/vite.config.ts` — configuración Vite (proxy a backend, aliases, TanStack Router plugin)
+  - `frontend/tailwind.config.js` — configuración Tailwind para shadcn/ui
+  - `frontend/src/main.tsx` — entry point con QueryClientProvider y RouterProvider
+  - `frontend/src/routes/__root.tsx` — layout raíz con navbar y sidebar
+  - `frontend/src/routes/index.tsx` — ruta Home
+  - `frontend/src/routes/roms.tsx` — ruta ROMs
+  - `frontend/src/routes/games.tsx` — ruta Games
+  - `frontend/src/components/layout/Navbar.tsx`
+  - `frontend/src/components/layout/Sidebar.tsx`
+  - `frontend/src/lib/api.ts` — cliente HTTP base (fetch/axios wrapper)
+  - `frontend/src/lib/queryClient.ts` — configuración de TanStack Query
+  - `frontend/src/hooks/useGames.ts` — custom hook con TanStack Query para juegos
+- **Tests a escribir:**
+  - `frontend/tests/App.spec.tsx` — renderizado de rutas (usando Vitest + React Testing Library)
+  - `frontend/tests/components/Navbar.spec.tsx` — navegación básica
+  - `tests/e2e/navigation.spec.ts` — E2E con Playwright (navegar entre páginas)
+- **Pasos:**
+  1. Escribir tests que fallen (renderizado de App, navegación E2E)
+  2. Configurar Vite + React + TypeScript + Tailwind + shadcn/ui + TanStack Query
+  3. Implementar layout, rutas, páginas vacías, configuración de QueryClient
+  4. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 7: Gestión manual de juegos (frontend + backend)**
+
+- **Objetivo:** CRUD completo para juegos: crear/editar/eliminar juegos manualmente (frontend form con shadcn/ui + TanStack Query), registrar juegos físicos/digitales con campos: nombre, plataforma, precio, condición (Loose/CIB/New), fecha de compra, vendedor, notas.
+- **Archivos/Funciones a crear/modificar:**
+  - `backend/src/routes/games.ts` — `GET /api/games`, `POST /api/games`, `PUT /api/games/:id`, `DELETE /api/games/:id`
+  - `backend/src/controllers/gamesController.ts` — lógica de CRUD
+  - `backend/src/validators/gameValidator.ts` — validación de input (Zod/Joi)
+  - `frontend/src/routes/games.tsx` — tabla de juegos con acciones (editar, eliminar)
+  - `frontend/src/components/games/GameForm.tsx` — formulario para crear/editar juego
+  - `frontend/src/components/games/GameCard.tsx` — card de vista de juego
+  - `frontend/src/hooks/useGames.ts` — custom hooks con TanStack Query (useGames, useCreateGame, useUpdateGame, useDeleteGame)
+  - `frontend/src/components/ui/*` — shadcn/ui components (Form, Input, Select, Textarea, DatePicker)
+- **Tests a escribir:**
+  - `backend/tests/routes/games.spec.ts` — CRUD endpoints (casos: crear juego válido, crear juego con datos faltantes, actualizar, eliminar)
+  - `frontend/tests/routes/games.spec.tsx` — renderizado de lista, acciones
+  - `frontend/tests/components/GameForm.spec.tsx` — validación de formulario
+  - `tests/e2e/games-crud.spec.ts` — E2E completo (crear/editar/eliminar juego)
+- **Pasos:**
+  1. Escribir tests que fallen (endpoints CRUD, renderizado de form, E2E CRUD)
+  2. Implementar backend endpoints y validators
+  3. Implementar frontend page, form, custom hooks con TanStack Query
+  4. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 8: Integración ROMs + Metadata (UI completa)**
+
+- **Objetivo:** Vista de ROMs escaneados en frontend, botón para scan de directorio, búsqueda/asociación de metadata (UI para seleccionar resultado de IGDB/RAWG con TanStack Query), y vincular ROM con juego. Incluir vista de artwork (covers, screenshots).
+- **Archivos/Funciones a crear/modificar:**
+  - `frontend/src/routes/roms.tsx` — tabla de ROMs escaneados, botón "Scan Directory", acciones (asociar metadata, ver detalles)
+  - `frontend/src/components/roms/ScanDialog.tsx` — dialog para input de path y scan
+  - `frontend/src/components/roms/MetadataSearchDialog.tsx` — búsqueda y selección de metadata
+  - `frontend/src/components/roms/RomCard.tsx` — card con info de ROM + artwork
+  - `frontend/src/hooks/useRoms.ts` — custom hooks con TanStack Query (useRoms, useScanDirectory, useEnrichMetadata)
+  - `backend/src/routes/artwork.ts` — `GET /api/artwork/:gameId` (proxy/cache de imágenes)
+- **Tests a escribir:**
+  - `frontend/tests/routes/roms.spec.tsx` — renderizado de tabla, acciones
+  - `frontend/tests/components/ScanDialog.spec.tsx` — submit de path, loading state
+  - `tests/e2e/roms-import.spec.ts` — E2E: scan → ver ROMs → asociar metadata → ver juego enriquecido
+- **Pasos:**
+  1. Escribir tests que fallen (UI de ROMs, scan dialog, E2E import completo)
+  2. Implementar componentes frontend y custom hooks con TanStack Query
+  3. Implementar endpoint de artwork (cache/proxy)
+  4. Ejecutar tests y verificar que pasan
+
+---
+
+### **Fase 9: CI, tests E2E, docs y seguridad**
+
+- **Objetivo:** GitHub Actions para CI (lint, tests unitarios, tests E2E con Playwright), configuración de ESLint/Prettier, docs de uso de APIs (cómo obtener keys), seguridad (env vars, .gitignore actualizado, SECURITY.md), y README completo.
+- **Archivos/Funciones a crear/modificar:**
+  - `.github/workflows/ci.yml` — pipeline (install, lint, test, e2e)
+  - `.eslintrc.cjs` — ajustar para backend + frontend
+  - `.prettierrc` — ajustar formatos
+  - `README.md` — actualizar con: setup, features, screenshots, roadmap
+  - `SECURITY.md` — políticas de seguridad, reporte de vulnerabilidades
+  - `docs/API_KEYS.md` — instrucciones para obtener keys de IGDB, RAWG, TheGamesDB
+  - `.env.example` — template de variables de entorno
+  - `backend/.env.example`, `frontend/.env.example` — templates específicos
+- **Tests a escribir:**
+  - `tests/e2e/full-flow.spec.ts` — E2E completo end-to-end (scan → enrich → crear juego manual → view)
+  - Asegurar que CI ejecuta todos los tests y Playwright genera reporte
+- **Pasos:**
+  1. Configurar GitHub Actions workflow
+  2. Ejecutar pipeline en CI (puede fallar inicialmente)
+  3. Corregir issues de lint/format/tests
+  4. Actualizar docs (README, SECURITY, API_KEYS)
+  5. Ejecutar CI nuevamente y verificar que todo pasa
+
+---
+
+## **Preguntas abiertas resueltas** ✅
+
+1. ✅ App web self-hosted (server + frontend separados)
+2. ✅ Frontend: TypeScript + React + Vite + shadcn/ui + TanStack Query + TanStack Router
+3. ✅ Solo APIs públicas: IGDB (OAuth Twitch gratuito), RAWG (API key gratuita con atribución), TheGamesDB (API key gratuita)
+4. ✅ Sin integración con tiendas (Steam/GOG/PSN) en MVP; dejar preparado para futuro (campo `storeId`, `storePlatform` en modelo Game)
+5. ✅ Prioridad: gestión de ROMs de directorio + creación manual de juegos físicos/digitales
+
+---
+
+## **Decisiones técnicas clave** 🔧
+
+- **Monorepo:** `/backend` y `/frontend` en el mismo repo, con workspaces de Yarn
+- **Backend:** Node.js + Express + TypeScript + Prisma + SQLite (migration a PostgreSQL posible en futuro)
+- **Frontend:** React + Vite + TypeScript + Tailwind CSS + shadcn/ui + TanStack Query + TanStack Router
+- **APIs de metadata:** IGDB (primary), RAWG (fallback), TheGamesDB (artwork/retro)
+- **Tests:** Backend (Vitest + Supertest), Frontend (Vitest + React Testing Library), E2E (Playwright)
+- **CI:** GitHub Actions con pipeline: install → lint → test → e2e
+- **Seguridad:** API keys en `.env`, no commitear secrets
+
+---
+
+## **Roadmap futuro (fuera del MVP)** 🚀
+
+- Integración con tiendas (Steam/GOG/PSN/Xbox) para import automático de compras
+- Price tracking con PriceCharting/IsThereAnyDeal (requiere suscripción/API paga)
+- Plugins/extensiones (LaunchBox export, Playnite sync)
+- Sincronización en nube (opcional, con cifrado E2E)
+- Soporte para multiple usuarios (autenticación/autorización)
+- Mobile app (React Native o PWA)
--- a/tests/docs.spec.ts
+++ b/tests/docs.spec.ts
@@ -0,0 +1,33 @@
+import { test, expect } from '@playwright/test';
+import fs from 'fs/promises';
+import path from 'path';
+
+const docsDir = path.join(__dirname, '..', 'docs');
+
+test.describe('Docs content checks', () => {
+  test('competitive-analysis has Licencia lines and Metadatos', async () => {
+    const file = await fs.readFile(path.join(docsDir, 'competitive-analysis.md'), 'utf-8');
+    expect(file).toContain('Licencia:');
+    expect(file).toContain('Fuentes');
+    expect(file).toContain('Metadatos');
+    expect(file).toContain('Autor: Quasar (investigación automatizada)');
+    expect(file).toContain('Última actualización: 2026-02-07');
+  });
+
+  test('apis-comparison includes Fecha verificación and subscription markers', async () => {
+    const file = await fs.readFile(path.join(docsDir, 'apis-comparison.md'), 'utf-8');
+    expect(file).toContain('Fecha verificación: 2026-02-07');
+    expect(file).toMatch(/PriceCharting|MobyGames|EmuMovies/);
+    expect(file).toContain('TOS');
+  });
+
+  test('lessons-learned contains PoC and license compatibility note', async () => {
+    const file = await fs.readFile(path.join(docsDir, 'lessons-learned.md'), 'utf-8');
+    expect(file).toContain(
+      'PoC propuesta: Backend mínimo (Node/Express) que implemente search IGDB + RAWG y cache LRU de 24h'
+    );
+    expect(file).toContain('compatibilidad de licencias');
+    expect(file).toContain('Fuentes');
+    expect(file).toContain('Metadatos');
+  });
+});