@damenor/agent-docs 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@damenor/agent-docs",
+  "version": "0.1.0",
+  "description": "CLI para generar documentación profesional para proyectos con agentes AI",
+  "type": "module",
+  "bin": {
+    "create-docs": "dist/index.js",
+    "agent-docs": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "4.1.5"
+  },
+  "keywords": [
+    "cli",
+    "documentation",
+    "ai-agents",
+    "template",
+    "diataxis",
+    "adr",
+    "scaffold",
+    "docs"
+  ],
+  "author": "damenordev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/damenordev/doc-projects.git"
+  },
+  "homepage": "https://github.com/damenordev/doc-projects#readme",
+  "bugs": {
+    "url": "https://github.com/damenordev/doc-projects/issues"
+  }
+}

package/templates/base/AGENTS.md

@@ -0,0 +1,177 @@
+---
+project: "{{PROJECT_NAME}}"
+stack: "{{TECH_STACK}}"
+created: "2025-01-01"
+updated: "2026-05-07"
+status: active
+type: agent-protocol
+tags: [agents, protocolo, operativo, ia]
+---
+
+# AGENTS.md — Protocolo Operativo
+
+Reglas que TODO agente de IA debe seguir al trabajar en este proyecto. Guía extendida: `docs/internal/agent-guide.md`.
+
+---
+
+## STOP — Lee esto ANTES de hacer nada
+
+1. **TRIAGE**: Clasifica la tarea (SMALL/MEDIUM/LARGE). No saltes este paso.
+2. **LEE**: Lee la documentación indicada en la tabla ANTES de escribir código.
+3. **PREGUNTA**: Si hay ambigüedad, haz TODAS las preguntas en UN solo mensaje.
+4. **NO IMPLEMENTES** sin seguir el protocolo completo (MEDIUM/LARGE).
+5. **@reviewer**: Invoca ANTES de marcar la tarea como completada (MEDIUM/LARGE).
+
+---
+
+## Triage de tarea
+
+Antes de ejecutar el protocolo, clasificar la tarea:
+
+| Tamaño | Criterio | Protocolo |
+|--------|----------|-----------|
+| **SMALL** | ≤2 archivos, <50 líneas | Leer CONTEXT.md → implementar → lint → done |
+| **MEDIUM** | 3-10 archivos, feature moderada | Protocolo completo (sin subdelegación) |
+| **LARGE** | Multi-día, arquitectural | Protocolo completo + ADR + subdelegación |
+
+**Ejemplos**: SMALL = fix typo, cambiar color, corregir import. MEDIUM = nuevo endpoint, nuevo componente, nuevo servicio simple. LARGE = sistema de auth, integración con provider externo, sistema de notificaciones multi-canal.
+
+Si empiezas SMALL y la tarea crece → escalar a MEDIUM.
+
+---
+
+## Stack y convenciones
+
+### Stack
+- **Frontend**: [framework y versión — ej. {{FRAMEWORK}}]
+- **Backend**: [framework y versión — ej. {{FRAMEWORK}}]
+- **Base de datos**: [tipo y versión — ej. {{TECH_STACK}}]
+- **CI/CD**: [plataforma — ej. {{TECH_STACK}}]
+
+### Detección automática de stack
+
+Si el stack no está rellenado arriba, el agente debe detectarlo:
+
+| Archivo detectado | Ecosistema | Comandos probables |
+|-------------------|------------|--------------------|
+| `package.json` | Node.js (npm/pnpm/yarn) | `npm run dev`, `npm run build` |
+| `requirements.txt` / `pyproject.toml` | Python (pip/poetry) | `python manage.py runserver`, `pytest` |
+| `go.mod` | Go | `go run .`, `go test ./...` |
+| `Cargo.toml` | Rust | `cargo run`, `cargo test` |
+| `pom.xml` / `build.gradle` | Java/Kotlin | `mvn spring-boot:run`, `gradle bootRun` |
+
+### Convenios obligatorios
+1. **Idioma**: Código en **inglés**. Comentarios y docs en **español**.
+2. **Nombramiento**: [convención de nombres — ej. camelCase variables/funciones, PascalCase componentes]
+3. **Estructura**: [convención — ej. feature-based folders]
+4. **Testing**: Todo código nuevo DEBE incluir tests.
+5. **Linting**: Pasar `npm run lint` sin errores antes de completar.
+6. **Commits**: Conventional Commits en español: `tipo(alcance): descripción`.
+7. **Seguridad**: Nunca commitear secrets. Usar variables de entorno.
+8. **Dependencias**: No añadir sin justificación. Si se añade → documentar en ADR.
+9. **Accesibilidad**: Todo componente UI cumple WCAG 2.1 AA.
+
+### Comandos
+
+| Comando | Uso |
+|---------|-----|
+| `npm run dev` | Desarrollo con hot-reload |
+| `npm run build` | Build producción |
+| `npm run test` | Tests unitarios e integración |
+| `npm run test:e2e` | Tests end-to-end |
+| `npm run lint` | Linter (debe pasar sin errores) |
+| `npm run typecheck` | Verificación de tipos |
+
+> **Detalle completo** de convenciones de git, commits, PRs y testing en [`docs/dev-workflow.md`](docs/dev-workflow.md).
+
+---
+
+## ANTES de cada tarea (MEDIUM/LARGE)
+
+### 1. Leer docs según tipo de tarea
+
+| Tipo de tarea | Documentación a leer primero |
+|---------------|------------------------------|
+| Cualquier tarea | `docs/CONTEXT.md` |
+| Feature nueva | `docs/roadmap.md`, `docs/explanation/architecture.md`, ADRs relevantes |
+| Bug/UI/Estilo | `docs/DESIGN.md`, `docs/CONTEXT.md` |
+| API/Backend | `docs/reference/api.md`, `docs/reference/configuration.md` |
+| Deploy/Infra | `docs/guides/deployment.md`, `docs/reference/infrastructure.md` |
+| Arquitectura | `docs/explanation/architecture.md`, `docs/adr/` (todos) |
+
+### 2. Verificar ADRs existentes
+
+Buscar en `docs/adr/` antes de tomar decisiones:
+- **Existe ADR aceptado** → SEGUIRLO. No reinventar.
+- **Contradice lo que vas a hacer** → Plantear discusión antes.
+- **No existe** → Evaluar si merece ADR (ver criterio y ejemplos en [`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md)).
+
+### 3. Verificar CONTEXT.md
+
+Si la tarea usa términos que no están en `docs/CONTEXT.md` → preparar para actualizar al terminar.
+
+Si `CONTEXT.md` tiene `completeness < 50%` → prioridad: completar CONTEXT.md antes de implementar features.
+
+### 4. Preguntar si hay ambigüedad
+
+Si después de leer la documentación hay ambigüedad → **batch TODAS las preguntas en un solo mensaje**. Cada pregunta con opciones cuando sea posible. No preguntar una por una.
+
+No preguntes si la tarea está clara, es implementación estándar, o la info está en los docs.
+
+---
+
+## DESPUÉS de cada tarea (MEDIUM/LARGE)
+
+### Árbol post-tarea
+
+```
+¿Tomaste una decisión?
+  ├── Arquitectónica → docs/adr/ (ADR formal)
+  ├── Implementación no obvia → JSDoc + docs/adr/ai-decisions.md
+  └── No → siguiente
+¿Términos nuevos del dominio? → docs/CONTEXT.md
+¿Endpoints cambiados? → docs/reference/api.md
+¿UI/UX cambiada? → docs/DESIGN.md
+¿Deploy a producción? → CHANGELOG.md + docs/guides/deployment.md
+¿Feature completado? → docs/roadmap.md
+¿Gotcha descubierto? → docs/guides/troubleshooting.md
+¿Refactor de patrones? → Revisar architecture.md y ADRs
+```
+
+> **Guía extendida** con diagramas y ejemplos en [`docs/internal/agent-guide.md`](docs/internal/agent-guide.md).
+> **Alternativa**: Invocar skill `doc-maintain` para detectar cambios y sugerir actualizaciones automáticamente.
+
+**Regla de oro**: Si cambias el código, cambias la documentación.
+
+---
+
+## Quality Gate — @reviewer (MEDIUM/LARGE)
+
+**ANTES de completar**, invocar `@reviewer` para verificar:
+- ✅ Code style conforme a convenciones
+- ✅ Sin duplicación — usa componentes/utilidades existentes
+- ✅ Sigue la arquitectura del proyecto y respeta ADRs
+- ✅ Sin vulnerabilidades de seguridad
+- ✅ Tests incluidos para código nuevo
+- ✅ Documentación actualizada
+- ✅ Sin problemas de performance evidentes
+
+- **❌ BLOQUEANTE** → arreglar antes de completar.
+- **⚠️ SUGERIDO** → recomendado pero no bloquea.
+
+---
+
+## Subdelegación
+
+Instrucciones mínimas al subagente:
+> Lee AGENTS.md y sigue el protocolo completo. Tarea: [descripción]. Docs relevantes: [lista].
+
+No repitas convenciones — ya están en AGENTS.md. Ver ejemplo completo en `docs/internal/agent-guide.md`.
+
+---
+
+## Skills y agentes disponibles
+
+- **Skills**: `doc-scaffold`, `doc-write`, `doc-design`, `doc-review`, `doc-maintain` — ver `.agents/skills/`
+- **Agentes**: `@reviewer` (quality gate), `@doc-writer`, `@doc-reviewer`, `@doc-designer`, `@doc-maintainer` — ver `.agents/agents/`
+- **Guía extendida**: `docs/internal/agent-guide.md`

package/templates/base/CHANGELOG.md

@@ -0,0 +1,86 @@
+---
+created: "2025-01-01"
+status: active
+type: changelog
+tags: [changelog, cambios, versiones]
+---
+
+# Changelog
+
+Todos los cambios notables de este proyecto se documentarán en este archivo.
+
+El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/),
+y este proyecto adhiere a [Versionado Semántico](https://semver.org/lang/es/).
+
+---
+
+## [Sin publicar]
+
+<!-- 
+  Sección para cambios que ya están en main pero que aún no se publican.
+  Mover las entradas aquí al momento de hacer un release.
+-->
+
+### Añadido
+- `TEMPLATE-README.md` con instrucciones paso a paso para usar este template.
+- `.editorconfig` para formato consistente entre editores.
+- `.markdownlint.json` para linting de archivos Markdown.
+- `.github/workflows/docs-check.yml` — CI que verifica frontmatter, archivos vacíos, links rotos y completeness de CONTEXT.md.
+- Tabla de detección automática de stack en `AGENTS.md` (soporte multi-lenguaje: Node, Python, Go, Rust, Java).
+- Diagramas Mermaid en `architecture.md` y `agent-guide.md` (reemplazan ASCII art).
+- Cross-references entre archivos para reducir duplicación interna.
+
+### Cambiado
+- `agent-flow.md` fusionado en `agent-guide.md` — el archivo original redirige.
+- `DESIGN.md` — bloque YAML ahora indica explícitamente que son valores de ejemplo.
+- `AGENTS.md` — criterio ADR referencia `TEMPLATE.md` en vez de duplicarlo.
+- `doc-maintain` skill — checklist post-tarea referencia `AGENTS.md` en vez de duplicar.
+- `doc-scaffold` skill — detección de stack ahora referencia tabla de `AGENTS.md`.
+
+### Corregido
+- Bug de caracteres chinos en `docs/README.md` ("命名" → "nomenclatura").
+
+### Cambiado
+<!-- Cambios en funcionalidad existente. Ejemplo: - Se actualizó el flujo de registro para incluir verificación por email. -->
+
+### Corregido
+<!-- Corrección de bugs. Ejemplo: - Se corrigió error 500 al enviar formularios con caracteres especiales. -->
+
+### Eliminado
+<!-- Funcionalidades eliminadas. Ejemplo: - Se eliminó el endpoint deprecated /api/v1/users. -->
+
+---
+
+## [0.1.0] - 2025-01-15
+
+### Añadido
+- Inicialización del proyecto con estructura base.
+- Configuración de CI/CD pipeline.
+- Documentación completa del proyecto (ver `docs/`).
+
+---
+
+<!-- 
+  GUÍA DE FORMATO:
+  
+  Tipos de cambios permitidos:
+  
+  - **Añadido**: para funcionalidades nuevas.
+  - **Cambiado**: para cambios en funcionalidad existente.
+  - **Deprecado**: para funcionalidades que serán eliminadas en futuras versiones.
+  - **Eliminado**: para funcionalidades eliminadas en esta versión.
+  - **Corregido**: para corrección de bugs.
+  - **Seguridad**: para correcciones de vulnerabilidades.
+  
+  Reglas:
+  
+  1. Cada versión tiene su fecha en formato YYYY-MM-DD.
+  2. La sección "Sin publicar" siempre está primero.
+  3. Los enlaces de comparación van al final del archivo.
+  4. Una entrada por cambio, prefijada con "- ".
+  5. Ordenar cambios: Añadido > Cambiado > Deprecado > Eliminado > Corregido > Seguridad.
+  6. Actualizar al momento de deploy (no al momento de codear).
+-->
+
+[0.1.0]: https://github.com/org/{{PROJECT_NAME}}/releases/tag/v0.1.0
+<!-- [Sin publicar]: https://github.com/org/{{PROJECT_NAME}}/compare/v0.1.0...HEAD -->

package/templates/base/README.md

@@ -0,0 +1,110 @@
+---
+created: "2025-01-01"
+status: active
+type: project-overview
+tags: [readme, proyecto, índice]
+---
+
+# {{PROJECT_NAME}}
+
+> [Una línea que describe qué hace este proyecto y para quién. Ejemplo: "Portal web corporativo para la gestión de trámites internos del sector finanzas."]
+
+---
+
+## Inicio rápido
+
+```bash
+# Clonar el repositorio
+git clone https://github.com/org/{{PROJECT_NAME}} && cd [NOMBRE_DEL_PROYECTO]
+
+# Instalar dependencias
+[comando de instalación]
+
+# Iniciar servidor de desarrollo
+[comando de dev]
+```
+
+El proyecto debería estar disponible en `http://localhost:3000`.
+
+---
+
+## Mapa de documentación
+
+Toda la documentación detallada vive en [`docs/`](docs/README.md).
+
+| Sección | Qué encontrarás | Ir a |
+|---------|-----------------|------|
+| Producto | Visión, roadmap, stakeholders | [`docs/product/`](docs/product/overview.md) |
+| Tutoriales | Quick start, setup, primera tarea | [`docs/tutorials/`](docs/tutorials/quick-start.md) |
+| Guías | Deploy, troubleshooting, runbooks | [`docs/guides/`](docs/guides/deployment.md) |
+| Referencia | API, configuración, infraestructura | [`docs/reference/`](docs/reference/api.md) |
+| Explicación | Arquitectura, decisiones (ADRs) | [`docs/explanation/`](docs/explanation/architecture.md) |
+| Operaciones | Monitoreo, incidentes, SLAs | [`docs/operations/`](docs/operations/README.md) |
+
+Archivos clave en la raíz:
+
+- [`AGENTS.md`](AGENTS.md) — Protocolo operativo para agentes de IA
+- [`CHANGELOG.md`](CHANGELOG.md) — Registro de cambios del proyecto
+- [`docs/CONTEXT.md`](docs/CONTEXT.md) — Vocabulario y lenguaje del dominio
+- [`docs/DESIGN.md`](docs/DESIGN.md) — Sistema de diseño (colores, tipografía, componentes)
+
+---
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `[npm run dev]` | Inicia el servidor de desarrollo con hot-reload |
+| `[npm run build]` | Genera la build de producción |
+| `[npm run test]` | Ejecuta la suite de tests |
+| `[npm run lint]` | Ejecuta el linter y el formateador |
+| `[npm run test:e2e]` | Ejecuta tests end-to-end |
+
+> **Fuente de verdad**: [`AGENTS.md`](AGENTS.md) § Comandos. Actualizar ahí primero.
+
+## Arquitectura
+
+Para entender cómo está construido el proyecto, leer [`docs/explanation/architecture.md`](docs/explanation/architecture.md).
+
+Resumen rápido:
+
+```
+[DIAGRAMA SIMPLIFICADO DE LA ARQUITECTURA]
+
+Cliente (Browser)
+  ↓
+[Frontend Framework]
+  ↓
+[API / Backend]
+  ↓
+[Base de datos]
+```
+
+Las decisiones de arquitectura se documentan como ADRs en [`docs/adr/`](docs/adr/TEMPLATE.md).
+
+---
+
+## Stack
+
+| Capa | Tecnología | Versión |
+|------|-----------|---------|
+| Frontend | [framework] | [versión] |
+| Backend | [framework] | [versión] |
+| Base de datos | [tipo] | [versión] |
+| CI/CD | [plataforma] | — |
+| Hosting | [proveedor] | — |
+| Lenguaje | [lenguaje] | [versión] |
+
+---
+
+## Contribuir
+
+1. Lee [`docs/dev-workflow.md`](docs/dev-workflow.md) para el flujo de trabajo interno.
+2. Lee [`AGENTS.md`](AGENTS.md) si trabajas con agentes de IA.
+3. Lee [`docs/tutorials/first-task.md`](docs/tutorials/first-task.md) para tu primera contribución.
+
+---
+
+## Licencia
+
+[TIPO DE LICENCIA — Ejemplo: Privada. Todos los derechos reservados.]

package/templates/base/docs/CONTEXT.md

@@ -0,0 +1,111 @@
+---
+created: "2025-01-01"
+updated: "2025-01-01"
+status: active
+completeness: "15%"
+type: domain-language
+tags: [contexto, dominio, vocabulario, glosario]
+---
+
+# CONTEXT.md — Lenguaje del Dominio
+
+Este archivo define el vocabulario compartido que se usa en este proyecto. Todo término de negocio o concepto clave del dominio debe estar documentado aquí.
+
+Si un término aparece en el código, la documentación o las conversaciones del equipo y NO está en este archivo, es un gap que debe cubrirse.
+
+---
+
+## Lenguaje del dominio
+
+### Entidades principales
+
+| Término | Definición | Ejemplo de uso | Equivalente técnico |
+|---------|-----------|----------------|-------------------|
+| **[Término 1]** | [Qué es, en una oración, desde la perspectiva del negocio] | "El [término] se vence el viernes." | `[nombre_en_codigo]` |
+| **[Término 2]** | [Qué es, en una oración, desde la perspectiva del negocio] | "Cada [término] puede tener múltiples [otro término]." | `[nombre_en_codigo]` |
+| **[Término 3]** | [Qué es, en una oración, desde la perspectiva del negocio] | "El sistema genera un [término] automáticamente." | `[nombre_en_codigo]` |
+
+### Estados y flujos
+
+| Término | Significa | Transiciones posibles |
+|---------|-----------|----------------------|
+| **[Estado A]** | [Qué significa este estado en términos de negocio] | → [Estado B], → [Estado C] |
+| **[Estado B]** | [Qué significa este estado en términos de negocio] | → [Estado C] |
+| **[Estado C]** | [Estado final — qué implica] | — |
+
+### Roles y permisos
+
+| Rol | Quién es | Qué puede hacer |
+|-----|----------|----------------|
+| **[Rol 1]** | [Descripción del perfil de usuario] | [Lista de permisos clave] |
+| **[Rol 2]** | [Descripción del perfil de usuario] | [Lista de permisos clave] |
+| **Admin** | Administrador del sistema con acceso total | Gestiona usuarios, configuración global, y puede asumir cualquier rol |
+
+### Términos de negocio
+
+| Término | Definición | Notas |
+|---------|-----------|-------|
+| **[Término de negocio]** | [Definición desde la perspectiva del negocio, no técnica] | [Contexto adicional o advertencias] |
+| **[Otro término]** | [Definición] | [Ejemplo: "No confundir con [término similar]. Ver [otra sección]."] |
+
+### Términos técnicos internos
+
+| Término | Definición | Por qué existe |
+|---------|-----------|----------------|
+| **[Término técnico]** | [Qué es y cómo se usa en este proyecto específicamente] | [Motivo por el que se introdujo o contexto de la decisión] |
+
+---
+
+## Relaciones entre conceptos
+
+```
+[Entidad 1] ─── 1:N ───→ [Entidad 2]
+                         └──→ [Entidad 3] (a través de [Entidad 4])
+
+[Rol 1] ─── puede ───→ [Acción A] sobre [Entidad 1]
+                     └──→ [Acción B] sobre [Entidad 2]
+
+[Estado A] ──→ [Estado B] ──→ [Estado C] ──→ [Estado D]
+                                              └──→ [Estado E] (reversión)
+```
+
+---
+
+## Ejemplo de diálogo usando el dominio
+
+Este ejemplo muestra cómo se usa el vocabulario en una conversación real del equipo:
+
+> **Product Manager**: "El cliente necesita que los [Término 1] en estado [Estado A] se puedan convertir automáticamente en [Término 2] cuando pasen a [Estado B]."
+>
+> **Developer**: "Entendido. ¿Esa conversación aplica para todos los [Rol 1] o solo para los que tienen permiso de [acción]?"
+>
+> **Product Manager**: "Solo para [Rol 1]. Los [Rol 2] solo ven el [Término 1] pero no pueden convertirlo."
+>
+> **Developer**: "Perfecto. Voy a añadir un botón de conversión en la vista de [Término 1] para [Rol 1], visible solo cuando esté en [Estado A]. ¿El [Término 2] resultante empieza en [Estado C]?"
+>
+> **Product Manager**: "Sí, empieza en [Estado C] y necesita aprobación de un [Rol 2] para pasar a [Estado D]."
+
+---
+
+## Ambigüedades flagadas
+
+Estos términos tienen significados que podrían confundirse. Prestar atención al contexto:
+
+| Término | Confusión posible | Aclaración |
+|---------|-------------------|-----------|
+| **[Término ambiguo]** | Se podría confundir con [otro término] | En este proyecto significa [definición precisa]. No es lo mismo que [otro término]. |
+| **[Otro término ambiguo]** | Significa cosas distintas según el contexto | Cuando dice "[término]" en el contexto de [área 1] significa [X]. En el contexto de [área 2] significa [Y]. |
+
+---
+
+## Cómo actualizar este archivo
+
+Cuando se añada un nuevo término al dominio:
+
+1. Identificar si es una **entidad**, un **estado**, un **rol**, un **término de negocio** o un **término técnico**.
+2. Añadirlo en la sección correspondiente con: definición, ejemplo de uso, y equivalente técnico.
+3. Si tiene relaciones con otras entidades, actualizar el diagrama de relaciones.
+4. Si es ambiguo o se confunde con otro término, añadirlo en "Ambigüedades flagadas".
+5. Si se introdujo un nuevo estado o flujo, actualizar la tabla de estados.
+
+**Regla**: Todo término que aparezca en código, APIs, UI o conversaciones del equipo DEBE estar aquí. Si no está, es un bug de documentación.

package/templates/base/docs/README.md

@@ -0,0 +1,131 @@
+---
+created: "2025-01-01"
+status: active
+type: doc-map
+tags: [documentación, índice, mapa, diátaxis]
+---
+
+# Mapa de Documentación
+
+Este directorio contiene **toda la documentación** del proyecto, organizada siguiendo el framework Diátaxis.
+
+---
+
+## Estructura de directorios
+
+```
+docs/
+├── README.md                           # ← ESTE ARCHIVO. Mapa y reglas de la documentación.
+├── CONTEXT.md                          # Vocabulario y lenguaje del dominio.
+├── DESIGN.md                           # Sistema de diseño (colores, tipografía, componentes).
+├── roadmap.md                          # Planificación y estado de features.
+├── dev-workflow.md                     # Convenciones internas de desarrollo.
+│
+├── product/                            # CONTEXTO DE PRODUCTO
+│   └── overview.md                     # Visión, usuarios, valor, métricas.
+│
+├── tutorials/                          # APRENDER — Orientados a aprendizaje
+│   ├── quick-start.md                  # Arrancar el proyecto en 15 minutos.
+│   ├── environment-setup.md            # Configurar el entorno de desarrollo.
+│   └── first-task.md                   # Hacer tu primera contribución end-to-end.
+│
+├── guides/                             # APLICAR — Orientados a tareas
+│   ├── deployment.md                   # Cómo hacer deploy a cada entorno.
+│   ├── troubleshooting.md              # Problemas comunes y soluciones.
+│   └── runbooks/                       # Runbooks para incidentes.
+│       └── TEMPLATE.md                 # Plantilla para crear runbooks nuevos.
+│
+├── reference/                          # CONSULTAR — Información objetiva
+│   ├── api.md                          # Referencia completa de la API.
+│   ├── code-style.md                   # Convenciones de código (naming, imports, etc.)
+│   ├── configuration.md                # Variables de entorno y configuración.
+│   └── infrastructure.md               # Entornos, URLs, acceso, CI/CD.
+│
+├── explanation/                        # ENTENDER — Orientados a comprensión
+│   ├── agent-flow.md                   # → Redirige a docs/internal/agent-guide.md
+│   └── architecture.md                 # Cómo y por qué está diseñado el sistema.
+│
+├── adr/                                # DECISIONES — Architecture Decision Records
+│   ├── TEMPLATE.md                     # Plantilla para crear ADRs nuevos.
+│   └── 0001-record-architecture-decisions.md  # Meta-ADR: por qué usamos ADRs.
+│
+└── operations/                         # OPERACIONES — Monitoreo e incidentes
+    └── README.md                       # Hub de operaciones: SLAs, monitoreo, post-mortems.
+```
+
+---
+
+## Clasificación Diátaxis
+
+La documentación se organiza en cuatro cuadrantes según su propósito:
+
+| Carpeta | Cuadrante | Propósito | Se lee cuando... |
+|---------|-----------|-----------|------------------|
+| `tutorials/` | **Aprender** | Guías paso a paso para aprender haciendo | "Quiero aprender cómo funciona esto" |
+| `guides/` | **Aplicar** | Instrucciones para completar una tarea específica | "Necesito hacer X, ¿cómo?" |
+| `reference/` | **Consultar** | Información técnica objetiva y completa | "¿Cuáles son los parámetros de esta función?" |
+| `explanation/` | **Entender** | Contexto, porqués, decisiones de diseño | "¿Por qué se diseñó así?" |
+
+Archivos transversales que no pertenecen a un cuadrante:
+
+| Archivo | Propósito |
+|---------|-----------|
+| `CONTEXT.md` | Define el vocabulario compartido del dominio. Se consulta constantemente. |
+| `DESIGN.md` | Sistema de diseño visual. Referencia para todo cambio de UI. |
+| `roadmap.md` | Estado de features y planificación. Se actualiza con cada sprint. |
+| `dev-workflow.md` | Convenciones internas: git, commits, PRs, code review. |
+| `product/` | Contexto de negocio: visión, usuarios, stakeholders, métricas. |
+| `adr/` | Registro de decisiones técnicas. Se consulta antes de tomar decisiones. |
+| `operations/` | Monitoreo, incidentes, SLAs. Se consulta durante y después de incidentes. |
+
+---
+
+## Reglas de crecimiento
+
+La documentación crece orgánicamente. **No crear archivos vacíos "por si acaso".**
+
+### Cuándo crear un archivo nuevo
+
+| Se crea cuando... | Dónde va | Tipo |
+|-------------------|----------|------|
+| Hay un nuevo tutorial paso a paso que no existe | `tutorials/` | Aprender |
+| Hay una tarea operativa recurrente sin guía | `guides/` | Aplicar |
+| Hay un componente/servicio nuevo que consultar | `reference/` | Consultar |
+| Hay un concepto que necesita explicación de fondo | `explanation/` | Entender |
+| Hay una decisión técnica con trade-offs | `adr/` | Decisión |
+| Hay un incidente recurrente que necesita pasos fijos | `guides/runbooks/` | Runbook |
+
+### Cuándo NO crear un archivo
+
+- Si la información ya existe en otro lado → **enlazar, no duplicar**.
+- Si es un "TODO" sin contenido real → **no crear el archivo hasta tener contenido**.
+- Si la información cambia constantemente → **mejor ponerla en código (ej. config en `.env.example`)**.
+
+### Reglas de nomenclatura
+
+- **Tutoriales**: Verbos en infinitivo, descriptivos. Ej. `quick-start.md`, `environment-setup.md`.
+- **Guías**: Sustantivos que describan la tarea. Ej. `deployment.md`, `troubleshooting.md`.
+- **Referencia**: Sustantivos del sistema. Ej. `api.md`, `configuration.md`, `infrastructure.md`.
+- **Explicación**: Conceptos amplios. Ej. `architecture.md`, `auth-flow.md`.
+- **ADRs**: Numerados. Ej. `0001-record-architecture-decisions.md`.
+- **Runbooks**: Nombre del incidente/servicio. Ej. `database-connection-timeout.md`.
+
+---
+
+## Convenciones de formato
+
+1. **Todo archivo** tiene YAML frontmatter con `created`, `status`, `type`, `tags`.
+2. **Todo archivo** empieza con un H1 (`#`) con el título del documento.
+3. **Contenido en español**, términos técnicos y nombres de archivos en inglés.
+4. **Enlaces relativos** entre archivos de documentación (no absolutos).
+5. **Una fuente de verdad**: cada dato vive en UN archivo. En los demás, enlazar.
+
+---
+
+## Mantenimiento
+
+La documentación se mantiene actualizada siguiendo el protocolo definido en [`AGENTS.md`](../AGENTS.md). Después de cada tarea, verificar la checklist post-tarea para actualizar los archivos afectados.
+
+Para auditar el estado de la documentación, usar la skill `doc-review`.
+
+Para validación automática en CI, ver [`.github/workflows/docs-check.yml`](../.github/workflows/docs-check.yml).