Documentación de Tarkor

Mapa de toda la documentación del proyecto. Cada carpeta tiene un propósito y un tipo de lector; si no sabes dónde buscar, empieza por la tabla de "Qué quiero hacer".

Qué quiero hacer

Quiero…	Empieza por
Saber qué se va a hacer y en qué orden	producto/21-roadmap.md
Mejoras de diseño, animación y configuración del front	producto/roadmap-front.md
Mejoras del panel de Reino (información y gestión)	producto/roadmap-front-reino.md
Mejoras del mapa de zona (movimiento, iconos, animaciones)	producto/roadmap-front-zona.md
Experiencia de usuario: orden de vistas, flujos y bloqueos	producto/roadmap-front-ux.md
Historia viva de cada partida: sucesos, consecuencias y lore generado	producto/roadmap-cronista.md
Entender la arquitectura técnica	arquitectura/03-arquitectura.md y 04-decisiones-tecnicas.md
Saber cómo funciona el mundo vivo (Reino, facciones, mercado, producción)	arquitectura/22-mundo-vivo-x4-tecnico.md
Instalar el proyecto	arquitectura/15-instalacion.md
Consultar una regla de juego (tiradas, combate, XP, construcción)	mecanicas/
Consultar el lore (regiones, razas, historia, fauna)	rpgtarkor/lore-mundo/07-mundo-helek-sirik.md
Añadir un elemento al catálogo (NPC, objeto, fauna…)	runbooks/nuevo-elemento-catalogo.md y puntos-de-codigo-nuevo-contenido.md
Ampliar lore con OpenCode	runbooks/ampliar-lore.md y borradores-opencode/prompts/00-como-usar.md
Revisar una partida real buscando fallos	runbooks/revisar-partida.md
Saber qué código, tests y tablas tocar de un sistema (para agentes)	mapa-agente.md
Retomar el trabajo donde lo dejó la última sesión	registros/traspaso.md
Ver hallazgos abiertos	registros/

Carpetas

producto/ — qué es Tarkor y hacia dónde va

• 01-analisis-producto.md: análisis de partida del producto.
• 02-decisiones.md: decisiones de producto razonadas.
• 21-roadmap.md: roadmap activo a un año.
• roadmap-front.md: roadmap de front (menú de configuración, animaciones, atmósfera, sonido).
• roadmap-front-reino.md: roadmap de front del panel de Reino.
• roadmap-front-zona.md: roadmap de front del mapa de zona.
• roadmap-front-ux.md: roadmap de experiencia de usuario (flujos, orden y bloqueos).
• roadmap-cronista.md: el Cronista — Libro de Sucesos, consecuencias, mundo por partida y lore generado.

arquitectura/ — cómo está construido

• 03-arquitectura.md: piezas, flujo de un turno, reloj de mundo.
• 04-decisiones-tecnicas.md: modelos locales, benchmarks, ritmo.
• 15-instalacion.md: instalación local (Postgres en podman, Ollama).
• 20-instalador-distribuible.md: investigación del instalador.
• 22-mundo-vivo-x4-tecnico.md: referencia técnica del mundo vivo, verificada contra el código, con huecos y preguntas abiertas.

mecanicas/ — reglas del juego

Diseño de cada sistema. Cuando un documento dice "diseño", el estado actual puede haber cambiado: el código manda.

Doc	Sistema
05 / 06	Tiradas, clasificación de acciones, flujo del turno
08	Acciones por tiempo (instantáneas, largas, tránsitos)
09	Panel de personaje
10	Niveles, XP y Reino
12	Posición, NPC, recursos y armería
13	Escala real del mundo
14	Combate, muerte y descanso
16	Población dinámica y encuentros
17	Construcciones y fundación de reino
18

rpgtarkor/ — el mundo de Helek Sirik (fuente de verdad del lore)

• lore-mundo/: índice del mundo, génesis, historia, cronologías, razas, lenguas, clanes orcos, clima, estaciones y regiones/ (una ficha por región con su geografía, fauna, flora y asentamientos).
• personajes/: personajes jugables y NPC del presente.
• items-y-catalogo/: objetos y prompts de imagen.
• sistemas-combate/: clases, combate múltiple, IA de combate.
• sistemas-reino/: diseño del mundo vivo (Reino, facciones, edificios de oficio, expediciones, compañeros).

canon-opencode/ — resumen del canon para el agente de lore

Versión compacta de rpgtarkor/, pensada para el contexto de 32k de OpenCode. Se sincroniza al aprobar propuestas. Si choca con rpgtarkor/, manda rpgtarkor/. Ver su README.

borradores-opencode/ — propuestas de lore

• propuestas-lore.md: bandeja de entrada de OpenCode.
• propuestas-aprobadas.md: fichas aprobadas con su seguimiento de docs y código.
• revision-lore.md: propuestas no aprobadas, para consulta.
• prompts/: chuletas de petición por tipo.

runbooks/ — procedimientos repetibles

ampliar-lore · nuevo-elemento-catalogo · puntos-de-codigo-nuevo-contenido · revisar-partida

registros/ — hallazgos y checklists vivos

Se escriben durante las sesiones y se van cerrando. No son documentación de referencia.

• traspaso.md: bitácora de traspaso entre sesiones — rama, tarea en curso y siguiente paso (reglas en CLAUDE.md).
• checklist-pruebas-juego.md: pruebas de juego pendientes.
• pruebas-nube-2026-09-28-hallazgos.md y plan-cierre-hallazgos-2026-09-28.md: última tanda de pruebas (B1-B32) y su plan de cierre.
• plan-mecanicas-por-zona-2026-09-28.md: paso de habilidades a mecánicas de zona.
• revisar-partida-hallazgos.md, sesion-jugadora-hallazgos.md, deuda-tecnica-hallazgos.md, lore-hallazgos.md, ampliar-lore-checklist.md.

archivo/ — historia

Roadmaps y registros antiguos, cerrados. Solo para arqueología. Incluye deuda-tecnica-hallazgos-historico.md y checklist-pruebas-juego-historico-2026-09-04.md (entradas cerradas movidas de registros/ el 2026-09-29, sin editar).

ia/

• fine-tuning-ia-local.md: guía para entrenar un narrador local propio.

Convenciones

• Idioma: castellano de España.
• El código manda. Si un documento contradice el código, el documento está desactualizado.
• Estado arriba. Cada documento de diseño abre con una línea de estado (implementado, diseñado sin código, sin diseñar) y la fecha en que se comprobó.
• Historial abajo. Las notas "corregido el día X" van a una sección final de historial, no intercaladas en el texto.
• Enlaces: node tools/lore-links/check.mjs docs comprueba ficheros y anclas.
• Secciones citadas por el código (mundo-vivo-x4.md § 7.4, areas.md § …): no se renumeran.