openprompt-lang 0.6.0 → 0.7.0

package/docs/AI_CONTEXT.md

@@ -1,12 +1,53 @@
 # AI_CONTEXT
 
 ## 1. Resumen corto
-- Proyecto: openPrompt-Lang
-- Objetivo: IA local especializada en desarrollo asistido.
-- Prioridad: contexto reducido y pasos pequeños.
+- Proyecto: openPrompt-Lang — framework de anotaciones y templates para desarrollo asistido por IA
+- Objetivo: IA local especializada en desarrollo asistido con contexto reducido y pasos pequeños.
+- Versión: 0.6.0 (CLI), módulos de lenguaje v1.0.0–1.1.0
 
-## 2. Contexto extendido
-- Ver AGENTS.md para stack y convenciones.
+## 2. Stack técnico
+- Frontend: React 19 + TypeScript + Vite 7 + Tailwind v4
+- Backend: Node.js + Express (TypeScript ESM), Spring Boot + Java
+- Auth/DB: Supabase (Backend/Auth/Storage)
+- UI: Lucide React, Sonner, Radix UI, shadcn/ui pattern (cva + cn())
 
-## 3. Desglose temático
-- Flujo: LEER → PLANIFICAR → IMPLEMENTAR → VERIFICAR.
+## 3. Módulos de lenguaje
+| Módulo | Templates | Versión | Extensiones |
+|--------|-----------|---------|-------------|
+| React + TypeScript (Vite) | 23 | 1.1.0 | 8 (supabase, stripe, prisma, ionic, tauri, next, auth0, webpay) |
+| Vue 3 + Nuxt | 12 | 1.0.0 | 3 |
+| Node.js + Express (TypeScript) | 12 | 1.0.0 | 5 (supabase, prisma, stripe, jwt, swagger) |
+| Spring Boot (Java) | 8 | 1.0.0 | 5 (spring-data-jpa, spring-security, spring-web, lombok-alt, mapstruct) |
+| OpenPrompt Core Knowledge | 3 | 1.0.0 | 0 |
+
+### Templates React (23)
+hook, component, page, service, store, layout, util, type — + CompoundComponent, ErrorBoundary, useQuery, useMutation, createContext, formSchema, SuspenseLoader, AuthGuard — + authFlow, dataFetching, formSystem, stateManagement
+
+### Templates Node.js (12)
+controller, service, route, middleware, model, repository, util, type, prisma, supabase, pagination, api-response
+
+### Templates Java (8)
+Controller, Service, Repository, DTOs, Entity, GlobalExceptionHandler, FeignClient, KafkaConfig
+
+## 4. Base de conocimiento
+- **10 dominios**: payments, mobile-pwa, systems, qa, frontend, backend, accessibility, algorithms, fundamentals, architecture
+- **13 playbooks**: flow-integration, capacitor-setup, rust-ownership, scrum-workflow, frontend-react, backend-nodejs, accessibility-wcag, algorithms-patterns, fundamentals-programs, spa-auth-flow, api-rest-design, db-schema-design, microservice-architecture
+- **33 fuentes** de conocimiento (libros/docs procesados)
+
+## 5. Comandos clave
+```bash
+npx openPrompt-Lang validate          # Validar anotaciones
+npx openPrompt-Lang lang list         # Listar módulos
+npx openPrompt-Lang lang index react  # Ver templates de un módulo
+npx openPrompt-Lang teach <id>        # Aprender de un template
+npx openPrompt-Lang knowledge list     # Listar conocimiento
+npx openPrompt-Lang knowledge search   # Buscar en conocimiento
+```
+
+## 6. Referencia canónica
+- `.openprompt/FRAMEWORK.md` — Manual completo: anotaciones, comandos CLI, MCP, dominios, módulos, reglas estrictas.
+- `AGENTS.md` — Stack, convenciones, UI, calidad.
+- `GEMINI.md` — Workflow obligatorio del agente.
+
+## 7. Flujo de trabajo
+LEER → PLANIFICAR → IMPLEMENTAR → VERIFICAR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openprompt-lang",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "PromptLang CLI — Framework de anotaciones para desarrollo asistido por IA",
   "type": "module",
   "main": "./bin/cli.js",

package/src/commands/knowledge-ops.js

@@ -10,7 +10,7 @@ import { extractPDF, generatePDFId } from '../utils/pdf-extractor.js'
 import { detectChapters } from '../utils/pdf-chapterize.js'
 
 export const KNOWLEDGE_DIR = 'knowledge-repo'
-export const META_DIR = join(KNOWLEDGE_DIR, 'processed', 'index')
+export const INDEX_DIR = join(KNOWLEDGE_DIR, 'processed', 'index')
 
 export function base() {
   return process.cwd()
@@ -21,7 +21,7 @@ export function kPath(...parts) {
 }
 
 export function metaPath(id) {
-  return join(base(), META_DIR, `${id}.json`)
+  return join(base(), INDEX_DIR, `${id}.json`)
 }
 
 export function slug(name) {
@@ -45,27 +45,27 @@ export function readMeta(id) {
 }
 
 export function writeMeta(id, data) {
-  mkdirSync(kPath('meta'), { recursive: true })
+  mkdirSync(kPath('processed', 'index'), { recursive: true })
   writeFileAtomic(metaPath(id), JSON.stringify(data, null, 2))
 }
 
 export function rebuildIndex() {
-  const metaDir = kPath('meta')
-  if (!existsSync(metaDir)) return { pdfs: [] }
+  const indexDir = kPath('processed', 'index')
+  if (!existsSync(indexDir)) return { pdfs: [] }
 
-  const files = readdirSync(metaDir)
+  const files = readdirSync(indexDir)
     .filter(f => f.endsWith('.json') && f !== 'index.json')
     .sort()
 
   const pdfs = []
   for (const f of files) {
     try {
-      pdfs.push(JSON.parse(readFileSync(join(metaDir, f), 'utf-8')))
+      pdfs.push(JSON.parse(readFileSync(join(indexDir, f), 'utf-8')))
     } catch { /* skip corrupt files */ }
   }
 
   const indexData = { pdfs, updatedAt: now() }
-  writeFileAtomic(kPath('meta', 'index.json'), JSON.stringify(indexData, null, 2))
+  writeFileAtomic(kPath('processed', 'index', 'index.json'), JSON.stringify(indexData, null, 2))
 
   const headerLines = `# knowledge-repo — Índice de Conocimiento
 
@@ -83,7 +83,7 @@ export function rebuildIndex() {
 }
 
 export function getIndex() {
-  const indexPath = kPath('meta', 'index.json')
+  const indexPath = kPath('processed', 'index', 'index.json')
   if (existsSync(indexPath)) {
     try {
       return JSON.parse(readFileSync(indexPath, 'utf-8')).pdfs
@@ -103,7 +103,7 @@ export function migrateOldMetadata() {
       return
     }
 
-    mkdirSync(kPath('meta'), { recursive: true })
+    mkdirSync(kPath('processed', 'index'), { recursive: true })
     for (const pdf of old.pdfs) {
       if (!existsSync(metaPath(pdf.id))) {
         writeMeta(pdf.id, pdf)
@@ -117,7 +117,7 @@ export function migrateOldMetadata() {
 export async function init() {
   const dirs = [
     KNOWLEDGE_DIR,
-    META_DIR,
+    INDEX_DIR,
     join(KNOWLEDGE_DIR, 'sources', 'pdf'),
     join(KNOWLEDGE_DIR, 'sources', 'web'),
     join(KNOWLEDGE_DIR, 'sources', 'chapters'),
@@ -128,7 +128,7 @@ export async function init() {
     join(KNOWLEDGE_DIR, 'taxonomy', 'decisions'),
     join(KNOWLEDGE_DIR, 'taxonomy', 'workflows'),
     join(KNOWLEDGE_DIR, 'playbooks'),
-    join(KNOWLEDGE_DIR, 'metadata'),
+    join(KNOWLEDGE_DIR, 'processed', 'index'),
     join(KNOWLEDGE_DIR, 'logs', 'ingestion'),
     join(KNOWLEDGE_DIR, 'logs', 'parsing'),
     join(KNOWLEDGE_DIR, 'logs', 'errors'),

package/src/templates/knowledge-repo/manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "2.0.0",
-  "generated": "2026-05-17T09:13:01.454Z",
+  "version": "2.1.0",
+  "generated": "2026-05-17T12:30:00.000Z",
   "structure": "knowledge-repo",
   "totalBooks": 33,
   "totalChapters": 2905,
@@ -13,14 +13,50 @@
     "backend",
     "accessibility",
     "algorithms",
-    "fundamentals"
+    "fundamentals",
+    "architecture"
   ],
   "playbooks": [
     "flow-integration",
     "capacitor-setup",
     "rust-ownership",
-    "scrum-workflow"
+    "scrum-workflow",
+    "frontend-react",
+    "backend-nodejs",
+    "accessibility-wcag",
+    "algorithms-patterns",
+    "fundamentals-programs",
+    "spa-auth-flow",
+    "api-rest-design",
+    "db-schema-design",
+    "microservice-architecture"
   ],
+  "languageModules": {
+    "react": {
+      "version": "1.1.0",
+      "templates": 23,
+      "errorsLearned": 3,
+      "extensions": 8
+    },
+    "vue": {
+      "version": "1.0.0",
+      "templates": 10,
+      "errorsLearned": 0,
+      "extensions": 3
+    },
+    "node": {
+      "version": "1.0.0",
+      "templates": 12,
+      "errorsLearned": 0,
+      "extensions": 5
+    },
+    "java": {
+      "version": "1.0.0",
+      "templates": 8,
+      "errorsLearned": 0,
+      "extensions": 5
+    }
+  },
   "layers": {
     "sources": "Original content (PDFs, web, native markdown)",
     "processed": "Summaries, extractions, chunks, and index",

package/src/templates/knowledge-repo/playbooks/accessibility/accessibility-playbook.md

@@ -0,0 +1,66 @@
+---
+domain: accessibility
+sources: ['2-3-2-guia-tecnica-accesibilidad-web-en-chile', '2-3-5-gu-a-para-el-desarrollo-de-sitios-web', '2-3-7-tips-on-designing-for-web-accessibility', '2-3-6-guia-desarrollo-software-v2-0']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: Accesibilidad Web (WCAG)
+
+Implementación de estándares WCAG, ARIA y buenas prácticas para webs inclusivas
+
+## Overview
+
+La accesibilidad web garantiza que todas las personas, independientemente de sus capacidades, puedan percibir, entender, navegar e interactuar con sitios web. Los estándares WCAG 2.1 organizan los criterios en 4 principios: Perceptible, Operable, Comprensible y Robusto (POUR).
+
+Este playbook cubre desde la estructura semántica HTML hasta patrones ARIA avanzados, contraste de colores, navegación por teclado, y testing con lectores de pantalla.
+
+## Prerequisites
+
+- Conocimiento de los libros: 2-3-2-guia-tecnica-accesibilidad-web-en-chile, 2-3-7-tips-on-designing-for-web-accessibility
+- Conocimiento básico de HTML semántico y CSS
+- Navegador con herramientas de desarrollo (DevTools Accessibility panel)
+
+## Steps
+
+1. **Principios POUR: Perceptible, Operable, Comprensible, Robusto** → [2-3-2-guia-tecnica-accesibilidad-web-en-chile/ch-001]
+
+2. **Estructura semántica HTML** → [2-3-5-gu-a-para-el-desarrollo-de-sitios-web/ch-005]
+
+3. **Navegación por teclado y foco** → [2-3-7-tips-on-designing-for-web-accessibility/ch-002]
+
+4. **Contraste de colores y legibilidad** → [2-3-7-tips-on-designing-for-web-accessibility/ch-004]
+
+5. **ARIA: roles, states y properties** → [2-3-2-guia-tecnica-accesibilidad-web-en-chile/ch-010]
+
+6. **Formularios accesibles: labels, errores y anuncios** → [2-3-5-gu-a-para-el-desarrollo-de-sitios-web/ch-015]
+
+7. **Imágenes, alt text y media alternativo** → [2-3-7-tips-on-designing-for-web-accessibility/ch-003]
+
+8. **Componentes interactivos: modales, tabs, accordions** → [2-3-2-guia-tecnica-accesibilidad-web-en-chile/ch-020]
+
+9. **Testing con lectores de pantalla** → [2-3-6-guia-desarrollo-software-v2-0/ch-008]
+
+10. **Auditoría automatizada: Lighthouse, axe-core** → [2-3-6-guia-desarrollo-software-v2-0/ch-010]
+
+## Common Patterns
+
+- **wcag** → [2-3-2-guia-tecnica-accesibilidad-web-en-chile/ch-001]
+- **aria** → [2-3-2-guia-tecnica-accesibilidad-web-en-chile/ch-010]
+- **contraste** → [2-3-7-tips-on-designing-for-web-accessibility/ch-004]
+- **semántico** → [2-3-5-gu-a-para-el-desarrollo-de-sitios-web/ch-005]
+- **navegación** → [2-3-7-tips-on-designing-for-web-accessibility/ch-002]
+
+## Error Recovery
+
+- Para errores de contraste: usar herramientas como Colour Contrast Analyser o WebAIM Contrast Checker
+- Para errores de foco: verificar tabindex y orden de tabulación con DevTools
+- Para errores de ARIA: validar con axe-core o WAVE extension
+- Para errores de formulario: verificar que cada input tenga label asociado y aria-describedby para errores
+
+## References
+
+- 2-3-2-guia-tecnica-accesibilidad-web-en-chile
+- 2-3-5-gu-a-para-el-desarrollo-de-sitios-web
+- 2-3-7-tips-on-designing-for-web-accessibility
+- 2-3-6-guia-desarrollo-software-v2-0

package/src/templates/knowledge-repo/playbooks/algorithms/algorithms-playbook.md

@@ -0,0 +1,69 @@
+---
+domain: algorithms
+sources: ['algoritmos-pseudocodigo-ordinogramas', 'apuntes-estructuras-datos-algoritmos', 'estructuras-de-datos', 'problemas-y-algoritmos']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: Algoritmos y Estructuras de Datos
+
+Selección de estructuras, técnicas de diseño y análisis de complejidad para problemas comunes
+
+## Overview
+
+Los algoritmos y estructuras de datos son fundamentos transversales para todo tipo de desarrollo. La elección correcta de una estructura de datos (lista, pila, cola, árbol, grafo, hash) determina la eficiencia de las operaciones. Las técnicas de diseño (dividir y conquistar, programación dinámica, greedy, backtracking) resuelven categorías específicas de problemas.
+
+Este playbook guía la selección de estructuras y la aplicación de técnicas según el tipo de problema, con referencias a los libros del knowledge-repo.
+
+## Prerequisites
+
+- Conocimiento de los libros: algoritmos-pseudocodigo-ordinogramas, apuntes-estructuras-datos-algoritmos
+- Conocimiento básico de matemáticas discretas
+- Familiaridad con pseudocódigo y algoritmia básica
+
+## Steps
+
+1. **Fundamentos: notación O y análisis de complejidad** → [algoritmos-pseudocodigo-ordinogramas/ch-001]
+
+2. **Estructuras lineales: listas, pilas, colas** → [apuntes-estructuras-datos-algoritmos/ch-010]
+
+3. **Hash tables y mapeo** → [apuntes-estructuras-datos-algoritmos/ch-020]
+
+4. **Árboles: binarios, BST, AVL** → [estructuras-de-datos/ch-030]
+
+5. **Grafos: representación y recorrido** → [estructuras-de-datos/ch-050]
+
+6. **Algoritmos de ordenación: bubble, merge, quick** → [algoritmos-pseudocodigo-ordinogramas/ch-040]
+
+7. **Algoritmos de búsqueda: lineal, binaria, BFS, DFS** → [algoritmos-pseudocodigo-ordinogramas/ch-050]
+
+8. **Programación dinámica** → [problemas-y-algoritmos/ch-060]
+
+9. **Algoritmos greedy** → [problemas-y-algoritmos/ch-070]
+
+10. **Backtracking y Branch & Bound** → [problemas-y-algoritmos/ch-080]
+
+## Common Patterns
+
+- **ordenación** → [algoritmos-pseudocodigo-ordinogramas/ch-040]
+- **búsqueda** → [algoritmos-pseudocodigo-ordinogramas/ch-050]
+- **árbol** → [estructuras-de-datos/ch-030]
+- **grafo** → [estructuras-de-datos/ch-050]
+- **lista** → [apuntes-estructuras-datos-algoritmos/ch-010]
+- **pila** → [apuntes-estructuras-datos-algoritmos/ch-012]
+- **cola** → [apuntes-estructuras-datos-algoritmos/ch-014]
+- **complejidad** → [algoritmos-pseudocodigo-ordinogramas/ch-001]
+
+## Error Recovery
+
+- Para timeouts: verificar complejidad temporal — cambiar O(n²) por O(n log n)
+- Para memory overflow: verificar estructuras en memoria — considerar streaming o paginación
+- Para bugs en recursión: verificar caso base y llamadas recursivasReducidas
+- Para errores de índice: verificar límites de arrays y condiciones de parada
+
+## References
+
+- algoritmos-pseudocodigo-ordinogramas
+- apuntes-estructuras-datos-algoritmos
+- estructuras-de-datos
+- problemas-y-algoritmos

package/src/templates/knowledge-repo/playbooks/architecture/api-rest-design-playbook.md

@@ -0,0 +1,64 @@
+---
+domain: architecture
+sources: ['node-js-es', 'react-aprendiz-maestro', 'bases-conceptuales-programacion']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: API REST Design
+
+Diseño de APIs REST: naming, paginación, filtrado, versionado, error codes y cache
+
+## Overview
+
+El diseño de una API REST determina la calidad de la integración frontend-backend. Este playbook establece convenciones para resource naming, URI structure, HTTP methods, status codes, paginación, filtrado, versionado, y manejo de errores que siguen el contrato del módulo Node.js (@kind controller, route, service).
+
+## Prerequisites
+
+- Módulo Node.js configurado con Express + TypeScript
+- Conocimiento de HTTP methods y status codes
+- ApiClient del módulo React configurado
+
+## Steps
+
+1. **Definir resource naming** → Sustantivos plurales en lowercase: /users, /orders, /products. Evitar verbos en URIs
+
+2. **Estructurar endpoints** → CRUD estándar: GET (list), GET /:id (detail), POST (create), PUT /:id (update), PATCH /:id (partial), DELETE /:id
+
+3. **Implementar paginación** → Cursor-based (preferido) con `?cursor=abc&limit=20` o offset con `?page=1&limit=20`. Incluir metadata: total, hasNext
+
+4. **Agregar filtrado y ordenamiento** → `?status=active&sort=created_at:desc`. Usar query params para filtros, header para formato
+
+5. **Versionado de API** → URI versioning: `/api/v1/users`. Mantener v1 mientras v2 está en adopción
+
+6. **Estandarizar error responses** → Formato consistente: `{ error: { code, message, details, timestamp } }`. Mapear status codes a tipos de error
+
+7. **Implementar cache** → ETags para GET individuales, Cache-Control para listas, Last-Modified para timestamps
+
+8. **Rate limiting** → Middleware con rate-limit por IP y por usuario autenticado. Headers X-RateLimit-*
+
+## Common Patterns
+
+- **resource** → Sustantivo plural, lowercase, kebab-case para multi-palabra
+- **pagination** → Cursor para grandes volúmenes, offset para UI paginada
+- **filter** → Query params con operadores: status=active, created_after=2024-01-01
+- **version** → /api/v1/ prefix, mantener compatibilidad hacia atrás
+- **error** → Contrato @contract(input → output @error) con tipos tipados
+- **cache** → ETag + If-None-Match para validación, Cache-Control para TTL
+
+## Error Recovery
+
+- 400 Bad Request: incluir details de validación por campo
+- 401 Unauthorized: redirigir a refresh flow, no reintentar sin nuevo token
+- 403 Forbidden: incluir permiso requerido en error details
+- 404 Not Found: nunca exponer si el recurso existe pero el usuario no tiene acceso (usar 404 genérico)
+- 409 Conflict: incluir conflicto específico (duplicado, versión stale)
+- 422 Unprocessable: errores de validación con campo y mensaje
+- 429 Too Many Requests: incluir Retry-After header
+- 500 Internal: nunca exponer stack traces en producción
+
+## References
+
+- node-js-es
+- react-aprendiz-maestro
+- Patrones del módulo openPrompt-Lang: controller-crud, service-crud, type-api-response

package/src/templates/knowledge-repo/playbooks/architecture/db-schema-design-playbook.md

@@ -0,0 +1,62 @@
+---
+domain: architecture
+sources: ['bases-datos-diseno-introduccion', 'node-js-es', 'introduccion-poo']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: DB Schema Design
+
+Diseño de esquemas: normalización, indexes, RLS, migrations y seeding
+
+## Overview
+
+El diseño de esquemas de base de datos determina la escalabilidad y mantenibilidad de toda la aplicación. Este playbook cubre el ciclo completo: modelado relacional, normalización, elección de tipos de datos, indexes para queries frecuentes, Row Level Security (RLS) para Supabase, y estrategia de migrations con Prisma.
+
+## Prerequisites
+
+- Conocimiento de modelo relacional y normalización (bases-datos-diseno-introduccion)
+- Entorno con Prisma CLI o Supabase CLI configurado
+- Conocimiento de SQL básico y constraints
+
+## Steps
+
+1. **Modelo conceptual** → Identificar entidades principales, relaciones (1:1, 1:N, N:M) y atributos. Usar diagramas ER
+
+2. **Normalización** → Llevar a 3NF: eliminar dependencias parciales (2NF) y transitivas (3NF). Desnormalizar solo por rendimiento medido
+
+3. **Definir tipos de datos** → Elegir el tipo más restrictivo: UUID para IDs, TIMESTAMPTZ para fechas, VARCHAR(n) con n justificado, JSONB para datos flexibles
+
+4. **Crear indexes** → Agregar indexes en columnas de búsqueda frecuente, foreign keys, y campos de ordenamiento. Usar EXPLAIN ANALYZE para verificar
+
+5. **Implementar RLS (Supabase)** → Políticas de Row Level Security por tabla: SELECT con user_id, INSERT con auth check, UPDATE/DELETE con ownership verification
+
+6. **Escribir migrations** → Cada cambio de schema = migration. Nunca alterar schema manualmente. Prisma: `npx prisma migrate dev --name description`
+
+7. **Seed data** → Script de seed separado para desarrollo. Datos realistas pero anonimizados. Usar factories para generar volumen
+
+8. **Auditoría y soft delete** → Agregar created_at, updated_at, deleted_at. Nunca borrar físicamente en SaaS. created_by para trazabilidad
+
+## Common Patterns
+
+- **uuid** → ID primario: gen_random_uuid() en PostgreSQL, autoincrement en SQLite
+- **timestamp** → created_at DEFAULT now(), updated_at con trigger
+- **soft-delete** → deleted_at TIMESTAMPTZ NULL, filtrar con WHERE deleted_at IS NULL
+- **rls** → CREATE POLICY "Users can read own data" ON table FOR SELECT USING (user_id = auth.uid())
+- **index** → CREATE INDEX idx_table_column ON table(column) WHERE condition -- partial index
+- **migration** → Archivo .sql o .prisma con up/down reversible
+- **seed** → Script idempotente con UPSERT para datos referenciales
+
+## Error Recovery
+
+- Migration conflictida: `prisma migrate resolve --applied` o `--rolled-back`
+- Performance lenta: EXPLAIN ANALYZE → agregar indexes → verificar que ORM no haga N+1
+- RLS bloqueando datos: verificar auth.uid() en contexto de request, usar service_role solo en backend
+- Data corruption: backup antes de migraciones destructivas, test en staging primero
+- Constraint violation: revisar FK cascades, usar ON DELETE CASCADE o SET NULL según caso
+
+## References
+
+- bases-datos-diseno-introduccion
+- node-js-es
+- Patrones del módulo openPrompt-Lang: model-prisma, model-supabase

package/src/templates/knowledge-repo/playbooks/architecture/microservice-architecture-playbook.md

@@ -0,0 +1,66 @@
+---
+domain: architecture
+sources: ['introduccion-poo', 'bases-conceptuales-programacion', 'node-js-es']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: Microservice Architecture
+
+Patrones de microservicios: service discovery, API gateway, event-driven, CQRS y saga
+
+## Overview
+
+La arquitectura de microservicios descompone una aplicación monolítica en servicios independientes, cada uno con su propia base de datos (Database per Service), comunicación vía API o eventos, y despliegue autónomo. Este playbook cubre los patrones esenciales: service discovery, API gateway, comunicación asíncrona con eventos, y patrones de consistencia eventual.
+
+Basado en los conceptos de .opencode/learning/: microservicios-spring-boot, database-per-service, feign-client, kafka-event-driven, state-machine-pedidos, manejo-excepciones-global.
+
+## Prerequisites
+
+- Conocimiento de POO y principios SOLID (introduccion-poo)
+- Conocimiento de APIs REST y Node.js (node-js-es)
+- Docker y docker-compose para desarrollo local
+
+## Steps
+
+1. **Definir boundaries de servicio** → Cada servicio tiene una responsabilidad de negocio (Bounded Context). Identificar por capacidad, no por entidad
+
+2. **Database per Service** → Cada servicio posee su base de datos. Comunicación entre servicios vía API o eventos, nunca shared queries
+
+3. **API Gateway** → Punto de entrada único que enruta requests, maneja auth, rate limiting, y agrega responses de múltiples servicios
+
+4. **Service Discovery** → Registry de servicios (Eureka, Consul) para que los servicios se encuentren dinámicamente sin hardcoding URLs
+
+5. **Comunicación asíncrona** → Event-driven con Kafka/RabbitMQ para operaciones que no requieren respuesta inmediata. Patrones: Event Sourcing, CQRS
+
+6. **Saga Pattern** → Para transacciones distribuidas: orquestación o coreografía. Cada paso tiene acción compensatoria para rollback
+
+7. **Manejo de errores global** → Circuit breaker (Resilience4j), retry con backoff, fallback responses, timeout configuration
+
+8. **Observabilidad** → Distributed tracing (Zipkin/Jaeger), structured logging, health checks, metrics (Prometheus)
+
+## Common Patterns
+
+- **bounded-context** → Servicio delimitado por capacidad de negocio
+- **database-per-service** → Cada servicio con su DB, comunicación vía API/evento
+- **api-gateway** → Enrutamiento, auth, rate limiting, composición
+- **saga** → Coordinación de transacciones distribuidas con compensación
+- **cqrs** → Separar modelo de lectura (query) del modelo de escritura (command)
+- **circuit-breaker** → Proteger contra cascading failures
+- **event-sourcing** → Almacenar eventos como fuente de verdad
+- **feign** → Cliente HTTP declarativo para comunicación inter-servicio
+
+## Error Recovery
+
+- Servicio caído: circuit breaker retorna fallback en vez de timeout cascada
+- Evento perdido: guaranteed delivery con idempotent consumers y dead letter queue
+- Datos inconsistentes: saga compensating transactions para rollback distribuido
+- Latencia alta: async communication para operaciones que no necesitan respuesta síncrona
+- Debugging distribuido: correlation IDs en headers para trazar requests entre servicios
+
+## References
+
+- introduccion-poo
+- bases-conceptuales-programacion
+- node-js-es
+- Conceptos .opencode/learning/: microservicios-spring-boot, database-per-service, feign-client, kafka-event-driven, state-machine-pedidos, manejo-excepciones-global

package/src/templates/knowledge-repo/playbooks/architecture/spa-auth-flow-playbook.md

@@ -0,0 +1,61 @@
+---
+domain: architecture
+sources: ['react-aprendiz-maestro', 'node-js-es', 'introduccion-poo', 'bases-datos-diseno-introduccion', 'bases-conceptuales-programacion']
+version: 1.0.0
+generated: 2026-05-17T12:00:00.000Z
+---
+
+# Playbook: SPA Auth Flow
+
+Flujo completo de autenticación SPA: JWT, refresh, guards, persistencia y roles
+
+## Overview
+
+El flujo de autenticación en una SPA moderna requiere coordinated handling de: login/register con servidor, almacenamiento seguro de tokens, rotación de refresh tokens, protección de rutas en cliente, y sincronización de estado auth entre pestañas. Este playbook integra patrones del módulo React (useAuth hook) con el backend Node.js (auth middleware).
+
+## Prerequisites
+
+- Módulo React configurado con extensión Supabase o API custom
+- Backend con endpoint de auth (login, register, refresh, logout)
+- Conocimiento de JWT, cookies httpOnly, y localStorage vs sessionStorage
+
+## Steps
+
+1. **Definir tipos de autenticación** → Crear `types/auth.ts` con interfaces User, LoginRequest, RegisterRequest, AuthTokens
+
+2. **Crear servicio de autenticación** → Implementar `services/authService.ts` con login, register, refresh, logout sobre ApiClient
+
+3. **Implementar hook de autenticación** → Extender `useAuth` con persistencia Zustand, refresh automático, y logout en 401
+
+4. **Crear AuthGuard** → Componente @kind layout que redirige a /login si no autenticado, con soporte de roles
+
+5. **Implementar refresh token flow** → Interceptor en ApiClient que detecta 401, refresca token, y reintenta request original
+
+6. **Sincronizar entre pestañas** → BroadcastChannel API para logout simultáneo y sincronización de sesión
+
+7. **Proteger rutas** → Configurar React Router con ProtectedRoute wrapper y role-based access
+
+8. **Manejar logout global** → Limpiar store, token, redirect, y notificar a otras pestañas
+
+## Common Patterns
+
+- **jwt** → Token en httpOnly cookie (preferido) o Authorization header
+- **refresh** → Rotación de refresh token con expiry configurable
+- **guard** → @kind layout con check de autenticación antes de renderizar
+- **persist** → Zustand + localStorage/sessionStorage con partialize
+- **sync** → BroadcastChannel para logout cross-tab
+- **role** → Checker de rol/binding en AuthGuard con configuración por ruta
+
+## Error Recovery
+
+- Token expirado: refresh automático transparente al usuario
+- Refresh token expirado: redirect a login con mensaje de sesión expirada
+- 403 Forbidden: mostrar página de acceso denegado con contexto
+- Red offline: mantener UI funcional con datos cacheados, reintentar al reconectar
+- Rate limiting en login: implementar delay exponencial y CAPTCHA
+
+## References
+
+- react-aprendiz-maestro
+- node-js-es
+- Patrones del módulo openPrompt-Lang: hook-useAuth, service-api, AuthGuard