openprompt-lang 1.2.7 → 1.4.0

package/docs/04-TICKETS/_archive/BOOST-005-micro-tasking.md

@@ -0,0 +1,67 @@
+# BOOST-005 — Micro-Tasking Engine
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-005 |
+| **Título** | Micro-Tasking Engine |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-003, BOOST-004 |
+| **Archivos** | `src/boost/micro-tasker.js` |
+
+## Descripción
+
+Motor que descompone tareas complejas de generación de código en micro-tareas secuenciales. Cada micro-tarea es una instrucción simple que un modelo pequeño puede seguir sin saturarse. El orquestador ejecuta las micro-tareas en cadena y el ensamblador une los resultados parciales en el archivo final.
+
+## Criterios de Aceptación
+
+### CA-1: Planificador de micro-tareas
+- [ ] `plan(task, kind)` → devuelve array de micro-tareas con: id, instrucción, formato esperado, validator
+- [ ] Para un hook: ["Define tipos/interface", "Define estado y efectos", "Implementa lógica", "Exporta"]
+- [ ] Para un componente: ["Define props", "Define variantes cva", "Implementa JSX", "Exporta"]
+- [ ] Para un page: ["Define imports y tipos", "Implementa layout", "Conecta datos", "Exporta"]
+
+### CA-2: Orquestador secuencial
+- [ ] `execute(task, kind, profile)` → ejecuta micro-tareas una por una
+- [ ] Cada micro-tarea se ejecuta con contexto mínimo (solo instrucción actual + resultado anterior)
+- [ ] Hay un shared state entre micro-tareas para mantener coherencia
+- [ ] Si una micro-tarea falla, el orquestador puede reintentarla (según perfil)
+
+### CA-3: Ensamblador
+- [ ] `assemble(partialResults, kind)` → combina resultados parciales en archivo final
+- [ ] Usa el hydrator (BOOST-003) para generar el código final con anotaciones
+- [ ] Si hay conflictos entre resultados parciales, resuelve con heurísticas (último valor gana)
+
+### CA-4: CLI microtask
+- [ ] `opl boost microtask "crea hook useAuth"` → muestra el plan de micro-tareas sin ejecutar
+- [ ] `opl boost microtask "crea hook useAuth" --execute` → ejecuta el plan
+- [ ] Opción `--verbose` muestra cada paso y su resultado
+- [ ] Opción `--plan-only` solo muestra el plan (alias de sin flag)
+
+### CA-5: Integración con generate
+- [ ] Cuando `opl boost generate` se ejecuta con perfil small, usa micro-tasking automáticamente
+- [ ] Cuando el perfil es medium, decide según complejidad de la tarea
+- [ ] Cuando el perfil es large, no usa micro-tasking
+
+### CA-6: Tests
+- [ ] Test de planificación para cada @kind que soporta
+- [ ] Test de orquestación con respuestas mock
+- [ ] Test de ensamblado con resultados parciales
+- [ ] Test de fallo de micro-tarea y reintento
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/micro-tasker.js` | ➕ Crear |
+
+## Notas técnicas
+
+- El orquestador es el componente más complejo del módulo Boost
+- El shared state es un simple objeto JSON que se pasa entre micro-tareas
+- Cada micro-tarea tiene un `validator` opcional que verifica el output antes de pasar a la siguiente
+- Los validators pueden ser: validate OPL, typecheck básico, o función custom
+- El orquestador debe ser extensible para soportar nuevos tipos de micro-tareas

package/docs/04-TICKETS/_archive/BOOST-006-validation-loop.md

@@ -0,0 +1,66 @@
+# BOOST-006 — Validation Feedback Loop
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-006 |
+| **Título** | Validation Feedback Loop |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-005 |
+| **Archivos** | `src/boost/validation-loop.js` |
+
+## Descripción
+
+Sistema post-generación que corre validación OPL y TypeScript sobre el código generado, y retroalimenta los errores específicos al modelo para que los corrija. Los modelos pequeños son significativamente mejores corrigiendo errores específicos que generando código correcto la primera vez.
+
+Si tras N reintentos el código sigue fallando, escala hacia abajo la complejidad de la tarea.
+
+## Criterios de Aceptación
+
+### CA-1: Validación post-generación
+- [ ] `validate(code, kind)` → ejecuta validación OPL sobre el código generado
+- [ ] Detecta: errores de anotaciones, errores de tipo, errores de sintaxis, violaciones de @limit
+- [ ] Retorna array de errores con: tipo, mensaje, línea, sugerencia de fix
+
+### CA-2: Feedback loop
+- [ ] `feedbackLoop(code, errors, profile)` → intenta corregir errores iterativamente
+- [ ] Por cada error, genera un mensaje de feedback claro para el modelo
+- [ ] El feedback dice exactamente qué está mal y da una sugerencia de cómo arreglarlo
+- [ ] El modelo corrige y se re-valida
+- [ ] Número de reintentos según perfil: small=3, medium=2, large=1
+
+### CA-3: Escalado de complejidad
+- [ ] Si tras 3 reintentos (small) el código sigue fallando, reduce complejidad
+- [ ] Estrategias de escalado: simplificar lógica, usar skeleton más básico, dividir en más micro-tareas
+- [ ] `escalateDown(task, attempt)` → devuelve versión simplificada de la tarea
+- [ ] El escalado se registra como @learn-error para futuras sesiones
+
+### CA-4: Integración con micro-tasker
+- [ ] Cuando una micro-tarea individual falla la validación, se reintenta antes de pasar a la siguiente
+- [ ] Si la micro-tarea falla consistentemente, el orquestador (BOOST-005) decide escalar
+
+### CA-5: Reporte de calidad
+- [ ] `generateReport(codeHistory, errors)` → genera reporte de cuántos intentos tomó, qué errores se corrigieron
+- [ ] El reporte se puede incluir en la documentación de la sesión
+
+### CA-6: Tests
+- [ ] Test de detección de errores de anotaciones
+- [ ] Test de feedback loop con mock de correcciones
+- [ ] Test de escalado tras N reintentos fallidos
+- [ ] Test de reporte de calidad
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/validation-loop.js` | ➕ Crear |
+
+## Notas técnicas
+
+- La validación OPL se hace invocando `npx openprompt-lang validate` o usando el módulo de validación directamente
+- El feedback loop necesita acceso al modelo para re-generar — pero en esta fase inicial, solo prepara los mensajes de feedback (la re-generación la hace quien llame al boost)
+- El escalado de complejidad es determinista (no necesita IA): simplifica basado en reglas
+- Los errores más comunes en modelos pequeños: @kind faltante, @limit excedido, tipos incorrectos

package/docs/04-TICKETS/_archive/BOOST-007-progressive-pipeline.md

@@ -0,0 +1,69 @@
+# BOOST-007 — Progressive Disclosure Pipeline
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-007 |
+| **Título** | Progressive Disclosure Pipeline |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Alta |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-002, BOOST-006 |
+| **Archivos** | `src/boost/progressive-pipeline.js`, `src/boost/index.js` |
+
+## Descripción
+
+Pipeline multi-etapa que orquesta todos los componentes Boost en un flujo coherente. Cada etapa expone gradualmente más complejidad al modelo, de modo que nunca ve el problema completo de golpe.
+
+El `index.js` es el punto de entrada unificado del módulo Boost.
+
+## Criterios de Aceptación
+
+### CA-1: Pipeline multi-etapa
+- [ ] **Stage 1 — Diseño**: el modelo define props, tipos, interface, contract sin implementar lógica
+- [ ] **Stage 2 — Implementación**: el modelo rellena el skeleton con lógica de negocio
+- [ ] **Stage 3 — Polish**: el modelo recibe feedback de validación y corrige errores
+- [ ] Cada etapa es más específica que la anterior
+
+### CA-2: Orchestrador unificado (index.js)
+- [ ] `boost(task, options)` → orquesta todo el pipeline
+- [ ] `options.profile` → perfil a usar
+- [ ] `options.kind` → tipo de archivo a generar
+- [ ] `options.dryRun` → mostrar plan sin ejecutar
+- [ ] `options.output` → archivo de salida (opcional)
+- [ ] Retorna: `{ code, metadata, report }`
+
+### CA-3: Metadata de ejecución
+- [ ] `{ profile, stages: [{name, duration, result}], totalTime, compressionRatio, validationAttempts }`
+- [ ] Permite comparar rendimiento entre perfiles
+- [ ] Se puede exportar como JSON
+
+### CA-4: Modo dry-run
+- [ ] `boost(task, { dryRun: true })` → muestra qué haría en cada etapa sin ejecutar
+- [ ] Muestra: plan de micro-tareas, skeletons a usar, ejemplos a inyectar
+
+### CA-5: Integración con compress
+- [ ] Antes del Stage 1, comprime el contexto según perfil (usa BOOST-002)
+- [ ] El Stage 1 recibe contexto mínimo
+- [ ] Los Stages 2 y 3 pueden recibir contexto adicional si es necesario
+
+### CA-6: Tests
+- [ ] Test de pipeline completo con mock de modelo
+- [ ] Test de metadata de ejecución
+- [ ] Test de dry-run
+- [ ] Test de integración: pipeline completo produce código válido
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/boost/index.js` | ➕ Crear (orquestador unificado) |
+| `src/boost/progressive-pipeline.js` | ➕ Crear (pipeline multi-etapa) |
+
+## Notas técnicas
+
+- El index.js es el API público del módulo Boost
+- Cada etapa del pipeline es un plugin: `pipeline.use(stage)` para futura extensibilidad
+- El pipeline registra tiempo de cada etapa para diagnóstico
+- Si una etapa falla, el pipeline detiene la ejecución y devuelve error con estado parcial

package/docs/04-TICKETS/_archive/BOOST-008-cli-mcp-integration.md

@@ -0,0 +1,74 @@
+# BOOST-008 — CLI + MCP Integration
+
+## Metadatos
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | BOOST-008 |
+| **Título** | CLI + MCP Integration |
+| **Épica** | Módulo OPL Boost |
+| **Prioridad** | Media |
+| **Estado** | 🔴 Pendiente |
+| **Depende de** | BOOST-007 |
+| **Archivos** | `src/cli/commands-boost.js`, `src/mcp-server.js`, `src/mcp-refactor/router.js`, `AGENTS.md` |
+
+## Descripción
+
+Integrar el módulo Boost con la CLI de OPL (comandos `opl boost *`) y con el servidor MCP (tools `OPL_Boost_*`). También actualizar AGENTS.md con la sección Boost Workflow para que las IAs futuras sepan cómo usar el módulo.
+
+## Criterios de Aceptación
+
+### CA-1: CLI completa
+- [ ] `opl boost check` → diagnóstico del perfil activo
+- [ ] `opl boost profile <name>` → forzar perfil (small/medium/large/auto)
+- [ ] `opl boost generate <desc>` → generar código con pipeline completo
+- [ ] `opl boost microtask <task>` → descomponer tarea en micro-tareas
+- [ ] Todos los comandos tienen `--help` descriptivo
+- [ ] Todos los comandos tienen `--dry-run`
+
+### CA-2: MCP tools
+- [ ] `OPL_Boost_profile` → mostrar perfil actual del modelo
+- [ ] `OPL_Boost_compress` → comprimir contexto según perfil
+- [ ] `OPL_Boost_microtask` → ejecutar pipeline de micro-tasking
+- [ ] `OPL_Boost_hydrate` → hidratar un skeleton con lógica
+- [ ] `OPL_Boost_validate` → loop de validación con retroalimentación
+- [ ] Las tools aparecen en el servidor MCP y son invocables
+
+### CA-3: AGENTS.md actualizado
+- [ ] Nueva sección "## 🚀 OPL Boost — Potenciar modelos pequeños" en AGENTS.md
+- [ ] Describe: qué es, cuándo usarlo, cómo configurarlo
+- [ ] Tabla de perfiles (small/medium/large)
+- [ ] Workflow Boost para IAs que usan el módulo
+- [ ] Referencia rápida de comandos `opl boost *`
+
+### CA-4: Registrar en bin/cli.js
+- [ ] `registerBoost(program)` llamado desde `bin/cli.js`
+- [ ] Import y registro consistente con los otros comandos
+
+### CA-5: Registrar en MCP server
+- [ ] Tools de boost agregadas a TOOLS en `src/mcp-refactor/tools.js`
+- [ ] Router en `src/mcp-refactor/router.js` maneja boost tools
+- [ ] Workflow generator en `src/mcp-workflow.js` incluye boost
+
+### CA-6: Tests de integración
+- [ ] Test de CLI: `opl boost check` funciona sin errores
+- [ ] Test de MCP: tools registradas correctamente
+- [ ] Test que todos los comandos tienen `--help`
+
+## Archivos a crear/modificar
+
+| Archivo | Acción |
+|---------|--------|
+| `src/cli/commands-boost.js` | ➕ Crear (registro completo de comandos) |
+| `bin/cli.js` | ✏️ Modificar (import + register) |
+| `src/mcp-server.js` | ✏️ Modificar (boost tools en TOOLS) |
+| `src/mcp-refactor/router.js` | ✏️ Modificar (boost routes) |
+| `src/mcp-workflow.js` | ✏️ Modificar (boost instructions) |
+| `AGENTS.md` | ✏️ Modificar (sección Boost) |
+
+## Notas técnicas
+
+- Los MCP tools deben seguir el patrón existente en `src/mcp-refactor/tools.js`
+- Los comandos CLI deben seguir el patrón de commander (`.command().description().action()`)
+- La sección de AGENTS.md debe seguir el tono y formato del documento existente
+- No debe romper comandos existentes ni tools MCP existentes

package/docs/AI_CONTEXT.md

@@ -60,8 +60,24 @@ npx openPrompt-Lang validate        # Validar anotaciones
 npx openPrompt-Lang lang list       # Listar módulos
 npx openPrompt-Lang teach <id>      # Aprender de un template
 npx openPrompt-Lang qa-gen          # Generar tests de regresión
+
+# OPL Boost (multi-agente para modelos pequeños)
+opl boost check                     # Diagnóstico perfil + estado del sistema
+opl boost profile [name]            # Ver/forzar perfil (small/medium/large/auto)
+opl boost setup                     # Detectar hardware + configurar
+opl boost generate <desc>           # Generar código con pipeline Boost
+opl boost microtask <task>          # Descomponer tarea en DAG
+opl boost cache [action]            # Gestionar caché (stats, clear, clean)
 ```
 
+## 5.5. Módulo OPL Boost
+- **12 tickets implementados** (BOOST-001 a BOOST-012, todos completados)
+- **Pipeline**: profile detection → context compression → few-shot → agent pool → skeleton hydration → validation loop
+- **Dos modos**: single-pass (default) y multi-agent (`--multi-agent`)
+- **Código**: `src/boost/` (17 archivos, ~3,700 líneas)
+- **MCP tools**: `boost_generate`, `boost_compress`, `boost_profile`, `boost_plan`, `boost_validate`
+- **Filosofía**: cada componente funciona independientemente; el multi-agente es opt-in
+
 ## 6. Referencia canónica
 - `.openprompt/FRAMEWORK.md` — Manual completo: anotaciones, comandos CLI, MCP, dominios, módulos, reglas estrictas.
 - `AGENTS.md` — Stack, convenciones, UI, calidad.

package/docs/EMBEDDINGS.md

@@ -0,0 +1,214 @@
+# Sistema de Embeddings Vectoriales
+
+## 📋 Overview
+
+openPrompt-Lang ahora soporta búsqueda semántica vectorial. En lugar de depender solo de coincidencia de palabras clave (tags, fulltext) o un mapa semántico manual, los documentos se dividen en **chunks semánticos**, cada chunk se convierte en un **vector embedding**, y las consultas se resuelven por **similitud de coseno**.
+
+## 🏗️ Arquitectura
+
+```
+Documento (opl format)
+    │
+    ▼
+┌─────────────────┐
+│   chunker.js    │  Divide: paragraph | section | fixed
+└────────┬────────┘
+         │ chunks[]
+         ▼
+┌─────────────────┐
+│   embedder.js   │  Vectoriza: Ollama | Transformers.js | auto-fallback
+└────────┬────────┘
+         │ vectors[]
+         ▼
+┌─────────────────────┐
+│  vector-store.js    │  Almacena + busca en SQLite
+│  (embeddings table) │
+└────────┬────────────┘
+         │ search(queryVector)
+         ▼
+┌─────────────────┐
+│  index-pipeline │  Orquestador: chunk → embed → store
+└─────────────────┘
+```
+
+## 📦 Módulos
+
+| Módulo | Archivo | Responsabilidad |
+|--------|---------|----------------|
+| Chunker | `src/embeddings/chunker.js` | Divide documentos en chunks semánticos |
+| Embedder | `src/embeddings/embedder.js` | Genera vectores numéricos (embeddings) |
+| Vector Store | `src/embeddings/vector-store.js` | Almacena/consulta vectores en SQLite |
+| Index Pipeline | `src/embeddings/index-pipeline.js` | Orquesta chunk → embed → store |
+
+## 🔧 Comandos CLI
+
+### `opl embeddings index <docId>`
+
+Indexa un documento en el vector store.
+
+```bash
+opl embeddings index react-fullstack-app
+opl embeddings index react-fullstack-app --strategy paragraph
+opl embeddings index react-fullstack-app --provider transformers
+opl embeddings index react-fullstack-app --dry-run  # simular sin persistir
+opl embeddings index react-fullstack-app --resume     # saltar chunks existentes
+```
+
+### `opl embeddings status`
+
+Muestra el estado actual del índice vectorial.
+
+```bash
+opl embeddings status
+# 📊  Estado del índice de embeddings
+#   Chunks indexados:   245
+#   Documentos:         12
+#   Dimensión:          768
+#   Modelo:             nomic-embed-text
+#   Último indexado:    2026-05-24 20:00:00
+#   Almacenamiento:     1.2 MB
+```
+
+### `opl embeddings remove <docId>`
+
+Elimina todos los embeddings de un documento.
+
+```bash
+opl embeddings remove react-fullstack-app
+```
+
+### `opl embeddings config`
+
+Ver o cambiar el proveedor de embeddings.
+
+```bash
+opl embeddings config                              # ver estado
+opl embeddings config --provider transformers      # cambiar a transformers
+opl embeddings config --provider ollama            # cambiar a ollama
+```
+
+### `opl search --mode vector <query>`
+
+Búsqueda semántica con embeddings.
+
+```bash
+opl search "autenticacion react" --mode vector     # solo vectorial
+opl search "pagos chile" --mode hybrid             # híbrido incluye vector
+```
+
+## 🧠 Proveedores de Embeddings
+
+### Ollama (primario, default)
+
+- **Modelo**: `nomic-embed-text` (768 dimensiones)
+- **URL**: `http://localhost:11434`
+- **Requisito**: `ollama pull nomic-embed-text`
+- **Ventaja**: Local, rápido, gratuito
+
+### Transformers.js (fallback)
+
+- **Modelo**: `Xenova/all-MiniLM-L6-v2` (384 dimensiones)
+- **Requisito**: `npm install @xenova/transformers`
+- **Ventaja**: No requiere servidor externo
+
+### Auto-fallback
+
+El embedder intenta Ollama primero. Si no está disponible, cae automáticamente a Transformers.js. Si ningún proveedor funciona, lanza un error instructivo.
+
+## 📐 Estrategias de Chunking
+
+| Estrategia | Descripción | Cuándo usarla |
+|------------|-------------|---------------|
+| `section` (default) | Divide por `##` respetando títulos | Documentos con estructura clara |
+| `paragraph` | Divide por doble salto de línea | Documentos sin estructura jerárquica |
+| `fixed` | Divide por tamaño fijo con solapamiento | Documentos sin estructura detectada |
+
+## 🔍 Búsqueda Híbrida
+
+`hybridSearch` combina FTS5 (texto completo) con reordenamiento semántico:
+
+1. **FTS5**: Busca palabras clave en el índice de texto completo
+2. **Coseno**: Reordena los candidatos por similitud semántica
+
+Esto da lo mejor de ambos mundos: precisión de FTS + semántica de embeddings.
+
+## 💾 Esquema SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS embeddings (
+    id          TEXT PRIMARY KEY,
+    doc_id      TEXT NOT NULL,
+    doc_title   TEXT NOT NULL DEFAULT '',
+    chapter_idx INTEGER NOT NULL DEFAULT 0,
+    chapter_title TEXT NOT NULL DEFAULT '',
+    chunk_idx   INTEGER NOT NULL DEFAULT 0,
+    content     TEXT NOT NULL,
+    vector      BLOB NOT NULL,
+    dimension   INTEGER NOT NULL DEFAULT 768,
+    tokens      INTEGER NOT NULL DEFAULT 0,
+    model       TEXT NOT NULL DEFAULT '',
+    strategy    TEXT NOT NULL DEFAULT 'section',
+    metadata    TEXT NOT NULL DEFAULT '{}',
+    created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS embeddings_fts USING fts5(
+    content,
+    content=embeddings,
+    content_rowid=rowid
+);
+```
+
+Los vectores se serializan como BLOB de Float32Array (4 bytes por float).
+
+## 📊 Límites de Escalabilidad
+
+| Métrica | Límite actual | Estrategia futura |
+|---------|--------------|-------------------|
+| Chunks totales | ~5000 | Búsqueda lineal OK |
+| Chunks > 100k | Podría ser lento | Índice HNSW |
+| Dimensión vectores | 768 (Ollama) / 384 (Transformers) | Cualquier dimensión |
+| Latencia búsqueda | < 50ms en 5000 chunks | Indexación en lote |
+
+## ✅ Tests
+
+```bash
+npx vitest run tests/embeddings/   # 87 tests, 4 suites
+```
+
+| Suite | Tests | Cubre |
+|-------|-------|-------|
+| `chunker.test.js` | 20 | Estrategias, límites, edge cases |
+| `embedder.test.js` | 23 | Proveedores, fallback, errores |
+| `vector-store.test.js` | 30 | CRUD, búsqueda, FTS5, híbrida |
+| `index-pipeline.test.js` | 14 | Pipeline completo, reindex, batch |
+
+## 🔗 Integración con OPL Search
+
+El modo `--mode vector` en `opl search`:
+1. Toma la consulta del usuario
+2. La convierte a vector con `embed()`
+3. Busca en el vector store con `hybridSearch()`
+4. Mapea chunks a documentos y muestra resultados
+
+El modo `--mode hybrid` incluye los resultados vectoriales junto con tags, fulltext y semántico.
+
+## ⚡ Auto-embedding
+
+Cuando se ingesta un PDF con `knowledge ingest`, se genera automáticamente el embedding del documento. Para saltar este paso:
+
+```bash
+knowledge ingest mi-documento.pdf --no-embed
+```
+
+## 🚀 Roadmap
+
+- [x] Chunker (3 estrategias)
+- [x] Embedder (Ollama + Transformers.js)
+- [x] Vector Store (SQLite + FTS5)
+- [x] Index Pipeline
+- [x] CLI: `opl embeddings index/status/remove/config`
+- [x] Modo vector en `opl search`
+- [x] Auto-embedding en `knowledge ingest`
+- [ ] Web scraper (`opl webscrape`)
+- [ ] Onboarding workflow en `opl init`

package/docs/ONBOARDING_WORKFLOW.md

@@ -0,0 +1,151 @@
+# 🚀 Onboarding Workflow para IA en openPrompt-Lang
+
+> **Propósito**: Este documento es el punto de entrada OBLIGATORIO para cualquier sesión de IA
+> en un proyecto que ya tiene elementos de openPrompt-Lang.
+>
+> **Generado por**: `opl init` al finalizar la configuración
+> **Versión del documento**: 1.0.0
+> **Última actualización**: {{fecha}}
+
+---
+
+## 📋 Instrucciones para la IA
+
+Al iniciar una sesión en este proyecto, SIGUE ESTE FLUJO ESTRICTAMENTE:
+
+```
+1. LEER este documento (ONBOARDING_WORKFLOW.md) → entender el estado del proyecto
+2. LEER AGENTS.md → stack, convenciones, reglas
+3. LEER docs/AI_CONTEXT.md → memoria del proyecto
+4. EJECUTAR workflow_check → ver qué pasos del workflow OPL faltan
+5. EJECUTAR context_unified → panorama completo del proyecto
+6. CONTINUAR desde el último paso registrado (ver sección "Estado Actual")
+```
+
+---
+
+## 🔍 Detección Automática de Contexto
+
+### ¿Este proyecto ya tiene OPL?
+
+Sí / No (según corresponda)
+
+| Elemento | Estado | Ruta |
+|----------|--------|------|
+| `prompt-lang.json` | ✅ / ❌ | `/ruta` |
+| `AGENTS.md` | ✅ / ❌ | `/ruta` |
+| `docs/AI_CONTEXT.md` | ✅ / ❌ | `/ruta` |
+| `docs/FRAMEWORK.md` | ✅ / ❌ | `/ruta` |
+| `src/` con anotaciones | ✅ / ❌ | `/ruta` |
+| `.opencode/` config | ✅ / ❌ | `/ruta` |
+| `.openprompt/` | ✅ / ❌ | `/ruta` |
+| `knowledge-repo/` | ✅ / ❌ | `/ruta` |
+| Base de conocimiento | ✅ / ❌ | `/ruta` |
+| Sistema de enseñanza | ✅ / ❌ | `/ruta` |
+
+---
+
+## 🧩 Stack del Proyecto
+
+| Componente | Valor |
+|------------|-------|
+| **Framework** | React / Vue / Node.js / Spring Boot |
+| **Lenguaje** | TypeScript / JavaScript / Java |
+| **UI** | Tailwind / shadcn / Mantine / Ninguno |
+| **Base de datos** | Supabase / SQLite / PostgreSQL |
+| **Extensiones** | Supabase, Stripe, Prisma, Ionic, ... |
+| **Módulos OPL activos** | React(23t), Vue(12t), Node(12t), Java(8t) |
+
+---
+
+## 📊 Estado Actual del Proyecto
+
+_Completar durante la última sesión. Esto permite a la próxima IA continuar sin pérdida de contexto._
+
+| Aspecto | Detalle |
+|---------|---------|
+| **Última sesión** | {{fecha}} |
+| **Último comando ejecutado** | `opl ...` |
+| **Fase del proyecto** | Inicial / En desarrollo / Refinamiento / Producción |
+| **Sprint activo** | embeddings-sprint-001 / ninguno |
+| **Ticket en progreso** | TICKET-XXX / ninguno |
+| **Próximo paso** | _Descripción de lo que sigue_ |
+| **Bloqueadores** | _Problemas pendientes_ |
+| **Branch activa** | `main` / `feature/...` |
+
+---
+
+## 🎯 Próximos Pasos Recomendados
+
+1. _Paso 1 — descripción_
+2. _Paso 2 — descripción_
+3. _Paso 3 — descripción_
+
+---
+
+## 🐛 Problemas Conocidos (Academic Issues)
+
+Ver `docs/OPL_ACADEMIC_ISSUES.md` para problemas reportados del sistema de enseñanza.
+
+| # | Título | Severidad | Estado |
+|---|--------|-----------|--------|
+| 1 | Onboarding IA en proyecto existente | 🔴 Alta | Abierto |
+| 2 | `opl rebuild` no detecta OPL | 🟡 Media | Abierto |
+| 3 | Falta documento post-init para IA | 🔴 Alta | Abierto |
+
+---
+
+## 📚 Documentos de Referencia
+
+| Documento | Propósito | Cuándo leerlo |
+|-----------|-----------|---------------|
+| `AGENTS.md` | Stack, convenciones, UI, calidad, reglas | ✅ Siempre — primera lectura |
+| `docs/AI_CONTEXT.md` | Memoria extendida del proyecto | ✅ Siempre — segunda lectura |
+| `docs/FRAMEWORK.md` | Manual completo: anotaciones, CLI, MCP | 🔍 Bajo demanda |
+| `docs/OPL_ACADEMIC_ISSUES.md` | Problemas del sistema de enseñanza | 🔍 Si tocas el módulo académico |
+| `docs/EMBEDDINGS.md` | Sistema de embeddings vectoriales | 🔍 Si tocas búsqueda semántica |
+| `.opencode/work-context/SESSION.json` | Estado actual de la sesión | 🔍 Para restaurar contexto |
+| `.opencode/work-context/LOG.json` | Bitácora de acciones | 🔍 Para auditoría |
+| `prompt-lang.json` | Configuración del proyecto | 🔍 Si necesitas ver config |
+
+---
+
+## ⚡ Comandos Rápidos para la IA
+
+```bash
+# Conocer el proyecto
+npx openprompt-lang context                     # Vista general
+npx openprompt-lang validate                    # Validar anotaciones
+npx openprompt-lang analyze .                   # Auditoría completa
+
+# Búsqueda de conocimiento
+opl index                                       # Navegar conocimiento
+opl search "término" --mode hybrid              # Búsqueda híbrida
+opl read <dominio>/<id> --chapter <n>           # Leer contenido
+
+# Evaluación del proyecto
+opl assess                                      # Production Readiness Assessment
+opl assess --verbose                            # Con detalle de 7 dimensiones
+
+# Sistema de enseñanza
+opl teach progress                              # Progreso de aprendizaje
+opl teach study <concepto>                      # Estudiar un concepto
+opl teach assess <concepto>                     # Evaluar nivel
+
+# Embeddings (si aplica)
+opl embeddings status                           # Estado del índice vectorial
+opl search "término" --mode vector              # Búsqueda semántica
+```
+
+---
+
+## 📝 Notas de la Sesión Actual
+
+```
+Espacio para que la IA o el usuario dejen notas sobre la sesión actual.
+```
+
+---
+
+*Documento generado automáticamente por `opl init`.*
+*Versión: 1.0.0*