openprompt-lang 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # OpenPrompt-Lang
 
-Framework de anotaciones para desarrollo asistido por IA. Sistema de anotaciones `@kind`, `@contract`, `@limit`, etc. para guiar a la IA en proyectos React + TypeScript.
+Framework de anotaciones **como código** para desarrollo asistido por IA. Escribe `@kind`, `@contract`, `@limit` como sintaxis directa (sin comentarios) para guiar a la IA sobre estructura, contratos y límites de tu código. Las anotaciones se eliminan automáticamente en build mediante plugins oficiales para Vite y TypeScript, y se integran con OpenCode vía MCP server. Extensible por módulos de lenguaje y tags personalizados.
 
 ```bash
 openPrompt-Lang --version
@@ -11,6 +11,14 @@ openPrompt-Lang --version
 ## Índice
 
 - [Instalación](#instalación)
+- [Nuevas Capacidades (v0.4.0)](#nuevas-capacidades-v040)
+  - [Aprender de proyectos reales](#aprender-de-proyectos-reales---extract---learn)
+  - [Aprender de documentación](#aprender-de-documentación---learn)
+  - [Transferencia de contexto](#transferencia-de-contexto---integrate---fromto)
+  - [Contexto por dominio](#contexto-por-dominio---context---domain)
+  - [Presets pre-ensamblados](#presets-pre-ensamblados---init---preset)
+  - [Reglas de base de datos](#reglas-de-base-de-datos---db-rules)
+  - [Filtros de componentes](#filtros-de-componentes---component-list---styletechvalidated)
 - [Anotaciones PromptLang (directorio completo)](#anotaciones-promptlang-directorio-completo)
   - [Tags de definición](#tags-de-definición)
   - [Tags de contrato](#tags-de-contrato)
@@ -31,7 +39,6 @@ openPrompt-Lang --version
 - [VS Code Extension](#vs-code-extension)
 - [Versionado (SemVer)](#versionado-semver)
 - [Documentación](#documentación)
-- [Publicación en npm](#publicación-en-npm)
 
 ---
 
@@ -84,10 +91,14 @@ npx openprompt-lang --help
 
 ## Anotaciones PromptLang (directorio completo)
 
-Las anotaciones se escriben como comentarios en el código. La IA las interpreta para entender restricciones, contratos y contexto del archivo.
+Las anotaciones se escriben en el código para guiar a la IA sobre restricciones, contratos y contexto del archivo. El parser detecta anotaciones tanto en comentarios como en código directo.
 
 ### Sintaxis general
 
+Soporta **dos modos**:
+
+#### Modo comentario (compatible con TS/JS estándar)
+
 ```typescript
 // @nombre(args)
 // @nombre(key: value, key2: value2)
@@ -100,6 +111,21 @@ Las anotaciones se escriben como comentarios en el código. La IA las interpreta
  */
 ```
 
+#### Modo código (sin //)
+
+```typescript
+@nombre(args)
+@nombre(key: value, key2: value2)
+```
+
+El parser reconoce automáticamente ambos formatos. Puedes mezclarlos libremente:
+
+```typescript
+// @use(kind, contract, deps)
+@kind(service)
+@contract(in: DTO -> out: Result @error: ServiceError)
+```
+
 ### @use — Declaración de tags (OBLIGATORIO)
 
 Primer tag de todo archivo. Declara qué tags se usan.
@@ -273,8 +299,69 @@ Compatibilidad:
 
 ---
 
+### Tags de aprendizaje y documentación
+
+#### @learn-error — Error aprendido
+
+Documenta un bug encontrado y su solución para prevenir regresiones:
+
+```
+// @learn-error id=BUTTON-001 input='...' expected=200 actual=500 fix='...' category=validation
+```
+
+Usado por `qa-gen` para generar tests de regresión automáticamente.
+
+#### @goodPractice — Buena práctica
+
+Marca una sección de código como ejemplo de buena práctica:
+
+```
+// @goodPractice("Usar early return reduce indentación")
+```
+
+#### @badPractice — Mala práctica
+
+Marca una sección como ejemplo de lo que no debe hacerse:
+
+```
+// @badPractice("No mutar props directamente")
+```
+
+#### @teachMe — Enseñanza estructurada
+
+Documenta el diseño, propósito o lección de un archivo para que la IA lo entienda:
+
+```
+// @teachMe
+// Este hook maneja autenticación con Supabase.
+// Usa early return para errores de validación antes de llamar a la API.
+// El token se persiste en localStorage y se verifica al montar.
+```
+
+Usado por `openPrompt-Lang teach` y el agente de Opencode.
+
+#### @template — Plantilla reutilizable
+
+Marca un archivo como template reutilizable dentro del módulo de lenguaje.
+
+#### @source — Origen de extracción
+
+Indica el archivo original del que se extrajo un template (usado por `extract`).
+
+#### @reuse — Reutilización
+
+Indica cuántas veces se ha reutilizado un template extraído.
+
+#### @extracted — Extraído
+
+Marca un template como generado por el extractor automático.
+
+---
+
 ### Ejemplos completos
 
+#### Modo comentario
+
 ```typescript
 // @use(kind, contract, limit, deps, platform, scope, meta)
 // @kind(hook)
@@ -297,26 +384,128 @@ export function useAuth() { ... }
 export function Button(props: ButtonProps) { ... }
 ```
 
+#### Modo código
+
+```typescript
+@use(kind, contract, limit, deps, platform, scope, meta)
+@kind(hook)
+@limit(lines: 75, params: 1)
+@contract(in: email, password -> out: user, token @error: AuthError)
+@deps(@external: [supabase], @forbidden: [axios])
+@platform(web)
+@scope(module: auth, affects: [login, register, session])
+@meta(@version: "1.0.0", @tags: [auth, supabase])
+export function useAuth() { ... }
+```
+
+```typescript
+@use(kind, props, state, limit, pattern)
+@kind(component)
+@props({ variant: string, size: string, children: ReactNode, disabled?: boolean })
+@state(idle, disabled, loading)
+@limit(lines: 90, functions: 2)
+@pattern(composition)
+export function Button(props: ButtonProps) { ... }
+```
+
+> **Nota:** El modo código usa la sintaxis `@tag( ... )` sin `//`. El parser solo reconoce tags conocidos (`@kind`, `@use`, `@props`, etc.) para evitar confundirlos con decoradores JS/TS como `@Component` o `@Injectable`. Funciona tanto en `.ts` como en `.js`, `.py`, `.vue`, etc.
+
 > 📖 **Especificación completa:** `docs/SYNTAX.md`
 
 ---
 
+## Nuevas Capacidades (v0.4.0)
+
+### Aprender de proyectos reales — `extract --learn`
+Analiza un proyecto y extrae sus patrones: convención de nombres, arquitectura, estilo UI, hooks, anotaciones. Genera un perfil reutilizable.
+
+```bash
+openPrompt-Lang extract ./proyecto-pulido --learn
+openPrompt-Lang init --name nuevo --learn-from ./aprendizaje-perfil.json
+```
+
+### Aprender de documentación — `learn`
+Usa IA para transformar documentación local en módulos de lenguaje funcionales con templates, tests y prácticas.
+
+```bash
+openPrompt-Lang learn --docs ./docs-rust/ --name rust
+openPrompt-Lang learn --docs ./docs-react/ --from ./proyecto-real/ --name react
+openPrompt-Lang learn --docs ./docs/ --name django --integrate
+```
+
+Los módulos se guardan en `~/.openprompt/knowledge/langs/<id>/` (accesibles para cualquier proyecto).
+
+### Transferencia de contexto — `integrate --from/--to`
+Copia el contexto de negocio entre proyectos: stack, convenciones, @kind/@contract detectados, arquitectura.
+
+```bash
+openPrompt-Lang integrate --from ./web-react --to ./app-mobile
+```
+
+### Contexto por dominio — `context --domain`
+Filtra el contexto del proyecto por dominio de negocio: ecommerce, saas, mobile, api, admin, blog.
+
+```bash
+openPrompt-Lang context --domain ecommerce
+```
+
+### Presets pre-ensamblados — `init --preset`
+Stacks completos con servicios incluidos: Supabase, Stripe, Ionic, Tauri, Firebase.
+
+```bash
+openPrompt-Lang init --preset react-supabase-stripe --name tienda
+openPrompt-Lang init --list-presets
+```
+
+### Reglas de base de datos — `db-rules`
+Knowledge base de buenas prácticas, anti-patrones y reglas para SQL, Supabase, Postgres, Docker.
+
+```bash
+openPrompt-Lang db-rules --id db-001
+openPrompt-Lang db-rules --tag performance
+```
+
+### Filtros de componentes — `component list --style/--tech/--validated`
+```bash
+openPrompt-Lang component list --style shadcn
+openPrompt-Lang component list --tech vue
+openPrompt-Lang component list --validated
+```
+
+> 📖 **Manual completo para IA:** `docs/AI-MANUAL.md` — todos los comandos, workflows ordenados y configuración.
+
+---
+
 ## Comandos CLI
 
 | Comando | Descripción |
-|---|---|
+|---|---|---|
 | `openPrompt-Lang init --name miapp` | Crea proyecto desde 0 con scaffolding completo + scripts descriptivos |
 | `openPrompt-Lang init --existing` | Configura proyecto existente (solo archivos de config) |
 | `openPrompt-Lang context --output contexto.md` | Extrae todo el código + anotaciones para dar contexto a la IA |
-| `openPrompt-Lang validate` | Valida anotaciones y ejecuta pipeline de verificación |
+| `openPrompt-Lang validate [--fix]` | Valida anotaciones y ejecuta pipeline de verificación |
 | `openPrompt-Lang figma` | Genera prompt para diseño Figma |
 | `openPrompt-Lang suggest "descripción"` | IA sugiere stack y estructura según descripción |
+| `openPrompt-Lang wizard` | Asistente interactivo para configurar proyecto openPrompt-Lang |
+| `openPrompt-Lang teach <templateId>` | Enseñanza estructurada desde template con @teachMe |
+| `openPrompt-Lang ai-gen` | Genera componentes desde descripciones en lenguaje natural |
+| `openPrompt-Lang ai-providers` | Lista proveedores IA disponibles y su estado |
+| `openPrompt-Lang extract [sourceDir]` | Analiza proyecto y extrae componentes reutilizables como templates |
+| `openPrompt-Lang analyze [sourceDir]` | Analiza estructura, dependencias y salud del proyecto |
+| `openPrompt-Lang integrate [--all]` | Configura Opencode, Cursor y VS Code para el proyecto |
+| `openPrompt-Lang qa-gen` | Genera tests desde errores aprendidos (@learn-error) |
+| `openPrompt-Lang qa-learn` | Parsea @learn-error de un archivo al módulo de lenguaje |
+| `openPrompt-Lang lang list` | Lista lenguajes disponibles |
+| `openPrompt-Lang lang index <langId>` | Muestra índice de templates de un lenguaje |
+| `openPrompt-Lang lang search <query>` | Busca templates en todos los lenguajes |
+| `openPrompt-Lang lang errors [langId]` | Muestra errores aprendidos |
+| `openPrompt-Lang scaffold folders <framework>` | Crea estructura de carpetas según framework |
+| `openPrompt-Lang scaffold list` | Lista frameworks disponibles en el catálogo |
 | `openPrompt-Lang component init` | Inicializa biblioteca de componentes reutilizables |
 | `openPrompt-Lang component list` | Lista componentes disponibles (proyecto + biblioteca) |
 | `openPrompt-Lang component add <nombre>` | Agrega componente de la biblioteca al proyecto |
 | `openPrompt-Lang component manifest` | Muestra el manifiesto de la biblioteca |
-
-> 📖 **Comandos y opciones detallados:** `docs/COMMANDS.md`
+| `openPrompt-Lang mcp` | Inicia servidor MCP para integración con Opencode |
 
 ---
 
@@ -512,25 +701,77 @@ Generados automáticamente por `npm init` (o mergeables con `--existing`).
 
 ```
 openPrompt-Lang/
-├── bin/cli.js                  ← Entry point del CLI
+├── bin/
+│   ├── cli.js                  ← Entry point del CLI
+│   ├── create.js               ← Scafolder directo
+│   └── lint.js                 ← Linter independiente
 ├── src/
 │   ├── commands/
 │   │   ├── init.js             ← init + --existing
 │   │   ├── context.js          ← Extractor de contexto
-│   │   ├── validate.js         ← Validador de anotaciones
+│   │   ├── validate.js         ← Validador de anotaciones (con --fix)
 │   │   ├── figma.js            ← Generador de prompts Figma
-│   │   └── suggest.js          ← Sugerencia de stack vía IA
-│   └── utils/
-│       ├── annotations.js      ← Parser + validador de anotaciones
-│       ├── config.js           ← Loader de prompt-lang.json + detectStack
-│       └── ai.js               ← Módulo de IA (OpenAI / opencode)
+│   │   ├── suggest.js          ← Sugerencia de stack vía IA
+│   │   ├── wizard.js           ← Asistente interactivo
+│   │   ├── teach.js            ← Enseñanza desde @teachMe
+│   │   ├── ai-gen.js           ← Generación de componentes vía IA
+│   │   ├── extract.js          ← Extractor de templates reutilizables
+│   │   ├── integrate.js        ← Integración con Opencode/Cursor/VS Code
+│   │   ├── qa-gen.js           ← Generación de tests desde @learn-error
+│   │   ├── lang.js             ← Gestión de módulos de lenguaje
+│   │   ├── scaffold.js         ← Scaffolding de proyectos
+│   │   ├── component.js        ← Biblioteca de componentes
+│   │   └── mcp-server.js       ← Servidor MCP (9 herramientas)
+│   ├── utils/
+│   │   ├── annotations.js      ← Parser + validador de anotaciones
+│   │   ├── config.js           ← Loader de prompt-lang.json + deep merge
+│   │   ├── ai.js               ← Módulo de IA (OpenAI / Anthropic / Ollama)
+│   │   ├── language-loader.js  ← Cargador de módulos de lenguaje
+│   │   ├── error-learner.js    ← Sistema de @learn-error
+│   │   ├── file-utils.js       ← findAllFiles / findComponentFiles / analyzeImports / countFiles
+│   │   └── template-utils.js   ← extractLesson / extractTags (compartido)
+│   ├── annotations/
+│   │   ├── tags.json           ← Lista canónica de 24 tags
+│   │   └── registry.js         ← Fusiona builtin + módulo + proyecto
+│   ├── ai/
+│   │   ├── providers.js        ← Proveedores IA (OpenAI, Anthropic, Ollama, Mock, None)
+│   │   └── prompt-builder.js   ← Constructor de prompts
+│   ├── generators/
+│   │   └── figma-prompt.js     ← Generador de prompts Figma
+│   ├── vite-plugin/
+│   │   └── index.js            ← Plugin Vite para eliminar anotaciones en build
+│   └── templates/
+│       ├── langs/
+│       │   ├── react/          ← 11 templates (Button, Input, Select, Card, Modal, DataTable, hooks, services)
+│       │   └── vue/            ← 12 templates (6 UI components + 5 composables + 1 service)
+│       └── scripts/            ← Scripts shell (validate.sh, etc.)
+├── .opencode/                  ← Configuración para Opencode
+│   ├── opencode.json           ← MCP server + skills + default_agent
+│   ├── agent/openPrompt.md     ← Agente con 4 workflows + Default Workflow
+│   └── skills/openPrompt/SKILL.md ← Skill auto-detectable con MCP tools
 ├── tests/
-│   ├── annotations.test.js     ← ~65 tests de parser y validador
-│   └── config.test.js          ← Tests de configuración
+│   ├── annotations.test.js     ← ~45 tests de parser y validador
+│   ├── config.test.js          ← Tests de deep merge
+│   ├── init.test.js            ← Tests de init
+│   ├── language-loader.test.js ← Tests de language-loader
+│   ├── wizard.test.js          ← Tests de qualityGate
+│   ├── scaffold.test.js        ← Tests de scaffold
+│   ├── validate.test.js        ← Tests de validate
+│   ├── qa-gen.test.js          ← Tests de QA generation
+│   ├── mcp-integration.test.js ← 14 tests MCP end-to-end
+│   ├── context.test.js         ← Tests de extracción de contexto
+│   ├── integrate.test.js       ← Tests de integración Opencode/Cursor/VS Code
+│   ├── file-utils.test.js      ← Tests de findAllFiles / countFiles
+│   ├── template-utils.test.js  ← Tests de extractLesson / extractTags
+│   ├── teach.test.js           ← Tests de enseñanza desde templates
+│   ├── ai-gen.test.js          ← Tests de generación vía IA
+│   ├── extract.test.js         ← Tests de extracción de templates
+│   └── component.test.js       ← Tests de biblioteca de componentes
 ├── docs/
 │   ├── COMMANDS.md             ← Documentación completa de comandos
 │   ├── SYNTAX.md               ← Especificación del lenguaje PromptLang
 │   ├── DEPENDENCIES.md         ← Dependencias y versiones
+│   ├── VERSIONING.md           ← Convención SemVer
 │   ├── FRAMEWORK.md            ← Framework spec (acceso rápido)
 │   └── referencia-metodologia/ ← Metodología completa (17 archivos)
 │       ├── Indice General.md
@@ -540,6 +781,8 @@ openPrompt-Lang/
 ├── vscode-extension/          ← Extensión VS Code (highlighting + snippets)
 ├── schemas/
 │   └── prompt-lang.json        ← JSON Schema para la configuración
+├── scaffolds/                  ← Scaffolds base para proyectos
+│   └── AGENTS.md               ← Template de AGENTS.md
 ├── package.json
 └── .gitignore
 ```
@@ -559,6 +802,7 @@ openPrompt-Lang/
 | `docs/referencia-metodologia/docs/CONVENCIONES_DB.md` | 18 prácticas de base de datos (RLS, índices, batch, etc.) |
 | `docs/referencia-metodologia/docs/CONVENCIONES_DOCUMENTACION.md` | Estándar de documentación (tablas DB, Mermaid, contratos RPC) |
 | `docs/referencia-metodologia/docs/PROMPTS/` | Biblioteca de prompts reutilizables (17 plantillas + 3 stacks) |
+| `docs/PROMPT_AI_CONTEXT.md` | Prompt pre-hecho para copiar-pegar a Gemini/Claude/ChatGPT |
 | `vscode-extension/` | Extensión VS Code: syntax highlighting y snippets para anotaciones |
 | `schemas/prompt-lang.json` | JSON Schema para validar `prompt-lang.json` |
 
@@ -571,7 +815,7 @@ openPrompt-Lang sigue [SemVer estricto](docs/VERSIONING.md):
 | Bump | Cuándo | Ejemplo |
 |---|---|---|
 | **MAJOR** | Breaking changes en API, CLI o anotaciones | `1.0.0` → `2.0.0` |
-| **MINOR** | Nuevas funcionalidades, comandos, tags | `0.2.0` → `0.3.0` |
+| **MINOR** | Nuevas funcionalidades, comandos, tags | `0.3.0` → `0.4.0` |
 | **PATCH** | Fixes, docs, refactors sin cambio de API | `0.2.0` → `0.2.1` |
 
 Pre-release: `1.0.0-alpha.1`, `1.0.0-beta.1`, `1.0.0-rc.1`
@@ -592,6 +836,139 @@ openPrompt-Lang incluye un sistema de **biblioteca de componentes reutilizables*
 
 ---
 
+## Extensibilidad
+
+El sistema de tags es extensible en tres niveles sin modificar el core:
+
+### Nivel 1 — Módulo de lenguaje
+
+Agrega `annotationTags` en el `MODULE.json` de tu módulo:
+
+```json
+{
+  "id": "react-query",
+  "name": "React Query",
+  "annotationTags": ["query", "mutation"]
+}
+```
+
+### Nivel 2 — Configuración del proyecto
+
+Agrega `customTags` en `prompt-lang.json`:
+
+```json
+{
+  "annotations": {
+    "customTags": ["audit", "security", "performance"]
+  }
+}
+```
+
+### Nivel 3 — Plugins de build
+
+Los plugins de Vite, TypeScript y Transformer aceptan la opción `tags` o `customTags`:
+
+```javascript
+// vite.config.ts
+import { openPromptAnnotations } from "openprompt-lang/vite-plugin";
+
+export default {
+  plugins: [
+    openPromptAnnotations({ tags: ["audit", "security"] }),
+  ],
+};
+```
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "name": "openprompt-lang/ts-plugin", "customTags": ["audit"] }
+    ]
+  }
+}
+```
+
+### Canonical tag list
+
+La lista completa de tags builtin está en `src/annotations/tags.json`. El registry (`src/annotations/registry.js`) fusiona builtin + módulo + proyecto automáticamente. Todos los plugins y herramientas (parser, Vite, TS, grammar, MCP) consumen de esta misma fuente.
+
+---
+
+## Build Plugins
+
+Para usar anotaciones como **código** (sin `//`), necesitas que el compilador las ignore en build.
+
+### Vite Plugin (Recomendado)
+
+```bash
+npm install -D openprompt-lang
+```
+
+```typescript
+// vite.config.ts
+import { openPromptAnnotations } from "openprompt-lang/vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    openPromptAnnotations(),
+  ],
+});
+```
+
+Elimina las líneas `@tag(...)` antes de que esbuild las procese. Soporta paréntesis anidados y multi-línea.
+
+### TypeScript Language Service Plugin
+
+Para VS Code (suprime errores rojos en `@tag(...)`):
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "name": "openprompt-lang/ts-plugin" }
+    ]
+  }
+}
+```
+
+### TS Transformer (para tsc / Next.js)
+
+```javascript
+// next.config.js o en tsconfig.json via ts-patch
+const { createTransformer } = require("openprompt-lang/ts-transformer");
+
+module.exports = {
+  webpack: (config) => {
+    config.module.rules.push({
+      test: /\.tsx?$/,
+      use: {
+        loader: "ts-loader",
+        options: {
+          getCustomTransformers: () => ({
+            before: [createTransformer()],
+          }),
+        },
+      },
+    });
+    return config;
+  },
+};
+```
+
+### Auto-configuración
+
+```bash
+# Para proyectos existentes:
+openPrompt-Lang init --existing
+
+# Te preguntará si configurar Vite plugin y TS plugin automáticamente.
+```
+
+---
+
 ## VS Code Extension
 
 openPrompt-Lang incluye una extensión para VS Code en `vscode-extension/` con resaltado de sintaxis y snippets.
@@ -622,7 +999,7 @@ code --install-extension openprompt-lang-*.vsix
 
 ### Funcionalidades
 
-- **Syntax highlighting**: todos los tags (`@kind`, `@props`, `@contract`, etc.) se resaltan en comentarios de TypeScript/JavaScript
+- **Syntax highlighting**: todos los tags (`@kind`, `@props`, `@contract`, etc.) se resaltan tanto en comentarios (`// @kind`) como en código directo (`@kind`)
 - **Snippets**: escribe `@kind-` y autocompleta:
   - `@kind-hook` → hook con `@contract`
   - `@kind-component` → componente con `@props`
@@ -639,25 +1016,169 @@ code --install-extension openprompt-lang-*.vsix
 
 ---
 
-## Publicación en npm
+## OpenCode Integration
+
+openPrompt-Lang tiene integración nativa con [OpenCode](https://opencode.ai) mediante **MCP server**, **agente especializado**, y **skill auto-detectable**.
+
+### Configuración rápida
 
 ```bash
-# 1. Build (si aplica)
-npm run build
+npx openprompt-lang integrate --all
+```
 
-# 2. Test
-npm test
+Esto genera:
 
-# 3. Versionar (e.g. 0.3.0 → 0.4.0 para nuevas features)
-npm version minor -m "feat: %s"
+- **`.opencode/opencode.json`** — Configuración con MCP server, skill paths y default_agent
+- **`.opencode/agent/openPrompt.md`** — Agente con 4 workflows + Default Workflow
+- **`.opencode/skills/openPrompt/SKILL.md`** — Skill auto-detectable (solo se activa si el proyecto usa anotaciones)
+- **MCP server** — Expone 9 herramientas que Opencode puede llamar directamente
 
-# 4. Publicar
-npm publish --access public
+### MCP Server
 
-# 5. Tag de release
-git push --follow-tags
+El MCP (Model Context Protocol) server permite que Opencode invoque herramientas de openPrompt-Lang de forma nativa, sin comandos slash. Las herramientas retornan estructura consistente:
+
+```
+## Result: success|error|warning
+<summary>
+### Details
+- <detalle 1>
+### Recommended Actions
+- <acción 1>
 ```
 
-> ⚠️ Requiere cuenta npm: `npm login` primero.
->
-> Pre-release: `npm publish --tag next`
+| Contexto | Herramienta | Descripción |
+|---|---|---|
+| **Auditar proyecto** | `analyze_project(dir)` | **Primera herramienta** en proyectos nuevos. Retorna config, conteo de archivos, estadísticas |
+| **Validar** | `validate([dir, filePath])` | Escanea proyecto/archivo buscando errores. Usar **antes de commits** |
+| | `lint_file(filePath, strict)` | Debug detallado de un archivo. Más información que `validate` |
+| | `parse_code(code)` | Valida sintaxis inline. Útil durante generación de código |
+| **Contexto** | `context([dir, scope])` | Extrae estructura del proyecto con resumen de config |
+| **Templates** | `search_templates(query, lang)` | Busca templates por keyword (button, auth, fetch) |
+| | `teach_template(templateId, showCode)` | Lección estructurada, prácticas y código del template |
+| **Testing** | `generate_tests(sourceDir, lang, output)` | Genera tests desde `@learn-error`. Usar **después de documentar un bug** |
+| **Scaffold** | `scaffold_project(framework, name)` | Crea estructura de proyecto y archivos base |
+
+### Auto-supervisión IA (Default Workflow)
+
+El **skill auto-detectable** se activa cuando el proyecto usa anotaciones y guía a la IA con este ciclo:
+
+```
+1. analyze_project  → entender el proyecto
+2. validate         → diagnosticar errores
+3. lint_file        → debug profundo de archivos con errores
+4. fix + @learn-error → documentar lo aprendido
+5. generate_tests   → prevenir regresión
+6. validate         → verificar que todo está limpio
+```
+
+El **agente `openPrompt`** incluye 4 workflows especializados (debugging de anotaciones, implementar componente, onboarding, nuevo proyecto) que la IA sigue automáticamente.
+
+### Uso manual (sin `integrate`)
+
+Crea `.opencode/opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "openPrompt": {
+      "type": "local",
+      "command": ["npx", "openprompt-lang", "mcp"],
+      "enabled": true
+    }
+  },
+  "skills": {
+    "paths": [".opencode/skills"]
+  },
+  "default_agent": "openPrompt",
+  "instructions": ["AGENTS.md"]
+}
+```
+
+Luego agrega `.opencode/agent/openPrompt.md` (instrucciones del agente) y `.opencode/skills/openPrompt/SKILL.md` (skill). O simplemente ejecuta `npx openprompt-lang integrate --all`.
+
+---
+
+## Tutorial: Usar openPrompt-Lang con cualquier IA
+
+Puedes usar openPrompt-Lang con **cualquier asistente de IA** — Google Gemini, Claude, ChatGPT, Cursor AI, etc. El framework no depende de Opencode; las anotaciones son simplemente código que cualquier IA puede leer e interpretar.
+
+### Con Google Gemini (u otro chat de IA)
+
+#### Paso 1: Extraer contexto del proyecto
+
+```bash
+npx openprompt-lang context --output contexto.md
+```
+
+Esto genera `contexto.md` con la estructura del proyecto, configuración, y archivos anotados.
+
+#### Paso 2: Compartir contexto con la IA
+
+Abre Google Gemini (o Claude, ChatGPT) y proporciona:
+
+1. El archivo `contexto.md` generado
+2. El archivo `AGENTS.md` del proyecto (stack, convenciones, reglas)
+3. El archivo `docs/SYNTAX.md` (especificación del lenguaje de anotaciones)
+
+**Prompt sugerido:**
+
+```
+Eres un desarrollador senior trabajando en este proyecto.
+Usa las anotaciones @kind, @contract, @props, @limit, @use para todo código nuevo que generes.
+Contexto del proyecto: [pega contexto.md]
+Reglas del proyecto: [pega AGENTS.md]
+Especificación de anotaciones: [pega SYNTAX.md]
+```
+
+#### Paso 3: La IA genera código con anotaciones
+
+La IA entenderá las anotaciones y generará código como:
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @limit(lines: 60, params: 1)
+// @contract(in: email, password -> out: User | null @error: string)
+// @deps(@external: [supabase])
+export function useAuth() { ... }
+```
+
+#### Paso 4: Validar el resultado
+
+```bash
+npx openprompt-lang validate src/mi-archivo.ts
+```
+
+### Con Cursor AI
+
+Cursor AI tiene integración nativa con openPrompt-Lang:
+
+```bash
+npx openprompt-lang integrate --all
+```
+
+Esto genera `.cursor/config.json` y `.cursorrules` con reglas específicas para que Cursor entienda las anotaciones. Luego solo abre el proyecto en Cursor:
+
+1. El archivo `.cursorrules` le dice a Cursor que use `@kind`, `@props`, etc.
+2. Cuando Cursor genere código, seguirá las convenciones del proyecto
+3. Ejecuta `openPrompt-Lang validate` para verificar el código generado
+
+### Con cualquier editor + API de IA
+
+Flujo genérico que funciona con cualquier herramienta:
+
+```
+1. Extraer contexto:  npx openprompt-lang context --output contexto.md
+2. Validar proyecto:  npx openprompt-lang validate
+3. Ver sintaxis:      docs/SYNTAX.md
+4. Compartir:         contexto.md + AGENTS.md + SYNTAX.md → IA
+5. Iterar:            IA genera código → validar → corregir
+```
+
+### Tips para mejores resultados
+
+- **Sé explícito**: dile a la IA "usa anotaciones @kind, @contract, @limit en todo el código"
+- **Comparte ejemplos**: muestra un archivo anotado como referencia (los ejemplos de este README funcionan bien)
+- **Valida siempre**: `npx openprompt-lang validate` detecta errores que la IA podría pasar por alto
+- **Documenta errores**: cuando la IA cometa un error de anotación, agrega `// @learn-error` para que futuras sesiones no repitan el mismo error