@saulwade/swl-ses 1.0.0

package/habilidades/event-driven/recursos/implementaciones-completas.md

@@ -0,0 +1,423 @@
+# Event-Driven — Implementaciones Completas de Referencia
+
+Ejemplos completos de código Python para arquitectura event-driven.
+
+---
+
+## RabbitMQ — Pub/Sub con Python (aio_pika)
+
+```python
+# pip install aio-pika
+import aio_pika
+import asyncio
+import json
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import Any, Callable, Awaitable
+import uuid
+
+@dataclass
+class Evento:
+    tipo: str
+    payload: dict
+    id: str = ""
+    timestamp: str = ""
+    correlation_id: str = ""
+    version: str = "1.0"
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+class BrokerEventos:
+    """Wrapper sobre aio_pika para publicar y consumir eventos."""
+
+    def __init__(self, url: str):
+        self._url = url
+        self._conexion: aio_pika.RobustConnection | None = None
+        self._canal: aio_pika.abc.AbstractChannel | None = None
+
+    async def conectar(self) -> None:
+        self._conexion = await aio_pika.connect_robust(
+            self._url,
+            heartbeat=60,
+            reconnect_interval=5.0,
+        )
+        self._canal = await self._conexion.channel()
+        await self._canal.set_qos(prefetch_count=10)
+
+    async def publicar(
+        self,
+        evento: Evento,
+        exchange: str = "eventos.rrhh",
+        routing_key: str | None = None,
+    ) -> None:
+        assert self._canal, "Llamar connect() primero"
+        exchange_obj = await self._canal.declare_exchange(
+            exchange, aio_pika.ExchangeType.TOPIC, durable=True,
+        )
+        await exchange_obj.publish(
+            aio_pika.Message(
+                body=json.dumps(asdict(evento), ensure_ascii=False).encode(),
+                content_type="application/json",
+                delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
+                message_id=evento.id,
+                timestamp=datetime.now(timezone.utc),
+                headers={
+                    "x-correlation-id": evento.correlation_id,
+                    "x-event-version": evento.version,
+                },
+            ),
+            routing_key=routing_key or evento.tipo,
+        )
+
+    async def suscribir(
+        self,
+        cola: str,
+        exchange: str,
+        routing_keys: list[str],
+        handler: Callable[[Evento], Awaitable[None]],
+    ) -> None:
+        assert self._canal
+        dlq_nombre = f"{cola}.dlq"
+        await self._canal.declare_queue(dlq_nombre, durable=True)
+        queue = await self._canal.declare_queue(
+            cola, durable=True,
+            arguments={
+                "x-dead-letter-exchange": "",
+                "x-dead-letter-routing-key": dlq_nombre,
+                "x-message-ttl": 86400000,
+            },
+        )
+        exchange_obj = await self._canal.declare_exchange(
+            exchange, aio_pika.ExchangeType.TOPIC, durable=True
+        )
+        for routing_key in routing_keys:
+            await queue.bind(exchange_obj, routing_key=routing_key)
+
+        async def procesar_mensaje(mensaje: aio_pika.IncomingMessage) -> None:
+            async with mensaje.process(requeue=False):
+                try:
+                    datos = json.loads(mensaje.body)
+                    evento = Evento(**datos)
+                    await handler(evento)
+                except Exception as e:
+                    logger.error("Error procesando evento %s: %s", mensaje.message_id, e)
+                    raise
+
+        await queue.consume(procesar_mensaje)
+```
+
+---
+
+## Kafka — Streaming de Alta Escala
+
+```python
+# pip install aiokafka
+from aiokafka import AIOKafkaProducer, AIOKafkaConsumer
+import asyncio
+import json
+
+class ProductorKafka:
+    def __init__(self, bootstrap_servers: str):
+        self._producer = AIOKafkaProducer(
+            bootstrap_servers=bootstrap_servers,
+            enable_idempotence=True,
+            max_batch_size=65536,
+            compression_type="gzip",
+            value_serializer=lambda v: json.dumps(v, ensure_ascii=False).encode(),
+            key_serializer=lambda k: k.encode() if k else None,
+        )
+
+    async def __aenter__(self) -> "ProductorKafka":
+        await self._producer.start()
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self._producer.stop()
+
+    async def enviar(self, topico: str, evento: dict, clave: str | None = None) -> None:
+        await self._producer.send_and_wait(
+            topico, value=evento, key=clave,
+            headers=[
+                ("content-type", b"application/json"),
+                ("event-id", evento.get("id", "").encode()),
+            ],
+        )
+
+class ConsumidorKafka:
+    def __init__(self, bootstrap_servers: str, group_id: str, topicos: list[str]):
+        self._consumer = AIOKafkaConsumer(
+            *topicos,
+            bootstrap_servers=bootstrap_servers,
+            group_id=group_id,
+            auto_offset_reset="earliest",
+            enable_auto_commit=False,
+            max_poll_records=100,
+            session_timeout_ms=30000,
+        )
+
+    async def consumir(self, handler) -> None:
+        await self._consumer.start()
+        try:
+            async for mensaje in self._consumer:
+                try:
+                    datos = json.loads(mensaje.value)
+                    await handler(datos)
+                    await self._consumer.commit()
+                except Exception as e:
+                    logger.error(
+                        "Error en topico=%s partition=%s offset=%s: %s",
+                        mensaje.topic, mensaje.partition, mensaje.offset, e,
+                    )
+        finally:
+            await self._consumer.stop()
+```
+
+---
+
+## Schemas de Eventos con Pydantic
+
+```python
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Literal
+import uuid
+
+class EventoBase(BaseModel):
+    id: str = ""
+    timestamp: datetime = None
+    version: str = "1.0"
+    correlation_id: str = ""
+    origen: str
+
+    def model_post_init(self, *args):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc)
+
+class EmpleadoCreadoPayload(BaseModel):
+    empleado_id: str
+    numero_empleado: str
+    nombre_completo: str
+    email_corporativo: str
+    departamento_id: str
+    puesto: str
+    fecha_ingreso: str
+
+class EventoEmpleadoCreado(EventoBase):
+    tipo: Literal["empleado.creado"] = "empleado.creado"
+    payload: EmpleadoCreadoPayload
+
+# Versioning — NUNCA romper compatibilidad hacia atrás
+class EmpleadoCreadoPayloadV2(EmpleadoCreadoPayload):
+    nss: str | None = None
+    curp: str | None = None
+```
+
+---
+
+## Idempotency — Registro con Redis
+
+```python
+class RegistroIdempotencia:
+    def __init__(self, redis_client):
+        self._redis = redis_client
+        self._ttl = 86400
+
+    async def ya_procesado(self, evento_id: str, consumer_id: str) -> bool:
+        clave = f"idempotencia:{consumer_id}:{evento_id}"
+        return bool(await self._redis.exists(clave))
+
+    async def marcar_procesado(self, evento_id: str, consumer_id: str) -> None:
+        clave = f"idempotencia:{consumer_id}:{evento_id}"
+        await self._redis.setex(clave, self._ttl, "1")
+
+class HandlerNuevaAlta:
+    def __init__(self, repo, idempotencia: RegistroIdempotencia):
+        self._repo = repo
+        self._idempotencia = idempotencia
+
+    async def manejar(self, evento: EventoEmpleadoCreado) -> None:
+        consumer_id = "handler.nueva_alta.configurar_nomina"
+        if await self._idempotencia.ya_procesado(evento.id, consumer_id):
+            logger.info("Evento %s ya procesado, ignorando", evento.id)
+            return
+        await self._repo.configurar_nomina(evento.payload)
+        await self._idempotencia.marcar_procesado(evento.id, consumer_id)
+```
+
+---
+
+## Retry con Backoff Exponencial
+
+```python
+class PoliticaReintento:
+    def __init__(self, max_intentos=5, delay_inicial=1.0, delay_maximo=60.0, multiplicador=2.0):
+        self.max_intentos = max_intentos
+        self.delay_inicial = delay_inicial
+        self.delay_maximo = delay_maximo
+        self.multiplicador = multiplicador
+
+    def delay_para_intento(self, intento: int) -> float:
+        import random
+        delay = min(
+            self.delay_inicial * (self.multiplicador ** (intento - 1)),
+            self.delay_maximo,
+        )
+        jitter = delay * 0.25 * (2 * random.random() - 1)
+        return delay + jitter
+
+class ProcesadorDLQ:
+    async def analizar_dlq(self, cola_dlq: str) -> list[dict]:
+        mensajes = []
+        async for mensaje in self._consumer.consumir_dlq(cola_dlq):
+            mensajes.append({
+                "id": mensaje.message_id,
+                "timestamp_original": mensaje.headers.get("x-first-death-time"),
+                "motivo_fallo": mensaje.headers.get("x-death")[0]["reason"],
+                "intentos": mensaje.headers.get("x-death")[0]["count"],
+                "cuerpo": json.loads(mensaje.body),
+            })
+        return mensajes
+```
+
+---
+
+## CQRS — Command Query Responsibility Segregation
+
+```python
+# COMMAND SIDE
+class ComandoCrearEmpleado(BaseModel):
+    nombre: str
+    apellido_paterno: str
+    apellido_materno: str
+    email: str
+    departamento_id: str
+
+class HandlerComandoCrearEmpleado:
+    async def manejar(self, comando, db, broker) -> str:
+        empleado = Empleado(**comando.model_dump())
+        db.add(empleado)
+        await db.flush()
+        evento = EventoEmpleadoCreado(
+            origen="servicio-empleados",
+            payload=EmpleadoCreadoPayload(
+                empleado_id=str(empleado.id),
+                nombre_completo=f"{comando.nombre} {comando.apellido_paterno}",
+                email_corporativo=comando.email,
+                departamento_id=comando.departamento_id,
+                numero_empleado=empleado.numero_empleado,
+                puesto=empleado.puesto,
+                fecha_ingreso=empleado.fecha_ingreso.isoformat(),
+            ),
+        )
+        await broker.publicar(evento)
+        await db.commit()
+        return str(empleado.id)
+
+# QUERY SIDE
+class VistaEmpleado(Base):
+    __tablename__ = "vista_empleados"
+    id = Column(UUID, primary_key=True)
+    nombre_completo = Column(String)
+    email = Column(String)
+    departamento_nombre = Column(String)
+    puesto = Column(String)
+    activo = Column(Boolean, default=True)
+    ultima_actualizacion = Column(DateTime)
+
+class ActualizadorVistaEmpleados:
+    async def en_empleado_creado(self, evento) -> None:
+        departamento = await self._repo.obtener_departamento(evento.payload.departamento_id)
+        vista = VistaEmpleado(
+            id=uuid.UUID(evento.payload.empleado_id),
+            nombre_completo=evento.payload.nombre_completo,
+            email=evento.payload.email_corporativo,
+            departamento_nombre=departamento.nombre,
+            puesto=evento.payload.puesto,
+            ultima_actualizacion=evento.timestamp,
+        )
+        await self._db.merge(vista)
+        await self._db.commit()
+```
+
+---
+
+## Transactional Outbox Pattern
+
+```python
+class EventoOutbox(Base):
+    __tablename__ = "eventos_outbox"
+    id = Column(UUID, primary_key=True, default=uuid.uuid4)
+    tipo = Column(String(100), nullable=False)
+    payload = Column(JSONB, nullable=False)
+    exchange = Column(String(100), nullable=False)
+    routing_key = Column(String(100), nullable=False)
+    creado_en = Column(DateTime(timezone=True), server_default=func.now())
+    publicado_en = Column(DateTime(timezone=True), nullable=True)
+    intentos = Column(Integer, default=0)
+
+async def crear_empleado_con_outbox(comando, db) -> str:
+    empleado = Empleado(**comando.model_dump())
+    db.add(empleado)
+    await db.flush()
+    evento_outbox = EventoOutbox(
+        tipo="empleado.creado",
+        payload={...},
+        exchange="eventos.rrhh",
+        routing_key="empleado.creado",
+    )
+    db.add(evento_outbox)
+    await db.commit()
+    return str(empleado.id)
+
+async def worker_outbox(db, broker) -> None:
+    while True:
+        eventos = await db.execute(
+            select(EventoOutbox)
+            .where(EventoOutbox.publicado_en.is_(None))
+            .where(EventoOutbox.intentos < 5)
+            .order_by(EventoOutbox.creado_en)
+            .limit(100)
+            .with_for_update(skip_locked=True)
+        )
+        for evento in eventos.scalars():
+            try:
+                await broker.publicar_raw(
+                    tipo=evento.tipo, payload=evento.payload,
+                    exchange=evento.exchange, routing_key=evento.routing_key,
+                )
+                evento.publicado_en = datetime.now(timezone.utc)
+            except Exception as e:
+                evento.intentos += 1
+                logger.error("Error publicando evento %s: %s", evento.id, e)
+        await db.commit()
+        await asyncio.sleep(5)
+```
+
+---
+
+## Eventual Consistency — Manejo en UI
+
+```python
+@router.post("/empleados", status_code=202)
+async def crear_empleado(comando: ComandoCrearEmpleado, ...):
+    empleado_id = await handler.manejar(comando, db, broker)
+    return {
+        "empleado_id": empleado_id,
+        "estado": "procesando",
+        "mensaje": "El empleado está siendo procesado. Estará disponible en segundos.",
+        "consultar_en": f"/empleados/{empleado_id}/estado",
+    }
+
+@router.get("/empleados/{id}/estado")
+async def estado_empleado(id: UUID, db: AsyncSession = Depends(get_db)):
+    vista = await db.get(VistaEmpleado, id)
+    if vista is None:
+        return {"estado": "procesando"}
+    return {"estado": "completado", "datos": vista}
+```

package/habilidades/extraccion-documentos/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: extraccion-documentos
+description: >
+  Extracción de contenido de documentos binarios (PDF, DOCX, PPTX, imágenes)
+  a Markdown usando MinerU. Soporta MCP (parse_documents), CLI (mineru-open-api)
+  y modo flash sin token. Cargar cuando el usuario pida leer, analizar o extraer
+  contenido de archivos PDF, Word, PowerPoint o imágenes con texto.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Grep]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para leer archivos de texto plano (.txt, .md, .csv, .json) — el Read tool los maneja directamente sin necesidad de MinerU."
+  - "No cargar para OCR de imágenes de alta precisión con modelos propios — para pipelines OCR especializados (Tesseract, Azure Form Recognizer) cargar el skill del proveedor correspondiente."
+  - "No cargar para extracción de datos estructurados de PDFs con formularios (XFA, AcroForm) — MinerU convierte a Markdown pero no preserva la estructura de formularios."
+  - "No cargar si la tarea es convertir documentos a formatos distintos de Markdown (DOCX→HTML, PDF→DOCX) — para conversión de formatos cargar `swl-markitdown` o el skill del pipeline de documentos."
+---
+# Extracción de documentos con MinerU
+
+## Cuándo NO cargar
+
+- La tarea es leer un archivo `.txt`, `.md`, `.csv` o `.json`: usar el Read tool directamente.
+- El pipeline requiere OCR con modelo propio (Tesseract, Azure Form Recognizer, AWS Textract): cargar el skill del proveedor correspondiente.
+- El PDF es un formulario con campos XFA o AcroForm y se necesita preservar la estructura de campos: MinerU no soporta esto.
+- La conversión requerida es de formato (DOCX→HTML, PDF→DOCX), no extracción de contenido: cargar `swl-markitdown` o el skill de conversión de documentos.
+
+## Cuándo activar
+
+- El usuario pide leer, analizar o extraer contenido de un PDF
+- El usuario proporciona un archivo .docx, .pptx, .doc, .ppt
+- El usuario quiere convertir un documento a Markdown
+- Se necesita leer una especificación, contrato o documento de requisitos
+- El investigador-swl o arquitecto-swl necesitan analizar documentación existente
+- El usuario dice "extrae", "lee este PDF", "convierte a texto", "analiza este documento"
+
+## Estrategia de extracción (orden de prioridad)
+
+### 1. MCP MinerU (preferido si está configurado)
+
+Verificar si el MCP está disponible:
+
+```
+Buscar en .mcp.json la entrada "mineru"
+```
+
+Si existe, usar directamente:
+
+```
+mcp__mineru__parse_documents(file_sources=["ruta/al/archivo.pdf"])
+```
+
+Ventajas: integrado en Claude Code, sin salir del flujo, soporta múltiples archivos.
+
+### 2. CLI mineru-open-api (alternativa sin MCP)
+
+Verificar si el CLI está instalado:
+
+```bash
+mineru-open-api version 2>/dev/null
+```
+
+Si existe, usar según el caso:
+
+| Situación | Comando |
+|-----------|---------|
+| Archivo pequeño (< 10 MB, < 20 págs) | `mineru-open-api flash-extract archivo.pdf` |
+| Archivo grande o con tablas | `mineru-open-api extract archivo.pdf` (requiere token) |
+| Página web | `mineru-open-api crawl https://url` |
+| Múltiples archivos | `mineru-open-api extract *.pdf -o ./salida/` |
+
+### 3. Herramienta Read nativa (último recurso)
+
+Si no hay MCP ni CLI, la herramienta Read de Claude Code puede leer PDFs
+directamente (con limitaciones de páginas). Usar como último recurso.
+
+> **Dependencia externa**: MinerU (MCP o CLI) no se incluye en la instalación
+> de SWL. Es un componente externo que cada equipo debe instalar por separado.
+> SWL instala la configuración del MCP y este skill, pero el servidor o CLI
+> de MinerU es responsabilidad del equipo. El skill detecta automáticamente
+> la disponibilidad y selecciona el mejor modo sin intervención del usuario.
+
+## Decisión flash-extract vs extract
+
+| Usar flash-extract cuando | Usar extract cuando |
+|--------------------------|-------------------|
+| No hay token configurado | Hay token y se necesita precisión |
+| Archivo < 10 MB y < 20 páginas | Archivo > 10 MB o > 20 páginas |
+| Solo se necesita Markdown | Se necesita DOCX, HTML o LaTeX |
+| No importan tablas/fórmulas | Hay tablas o fórmulas importantes |
+| Primera vez del usuario | El usuario ya tiene token |
+| Documento digital (texto nativo) | Documento escaneado o con firmas/sellos |
+| Texto simple sin formato denso | Texto legal, actas o documentos oficiales |
+
+> **Limitación conocida de flash-extract**: En documentos escaneados, con firmas
+> manuscritas, sellos oficiales o texto legal denso en español, flash-extract
+> produce resultados con texto truncado, palabras fusionadas y caracteres faltantes.
+> Para estos documentos, se recomienda usar `extract` con token (registro gratuito
+> en https://mineru.net/apiManage/token). Si el usuario reporta mala calidad de
+> extracción y no tiene token, sugerir el registro y configurar con
+> `mineru-open-api auth`.
+
+## Configuración del MCP
+
+Para habilitar el MCP de MinerU en un proyecto, agregar a `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mineru": {
+      "command": "uvx",
+      "args": ["mineru-open-mcp"],
+      "env": {
+        "MINERU_API_TOKEN": "tu_token_aqui"
+      }
+    }
+  }
+}
+```
+
+Sin token, el MCP usa modo Flash automáticamente (gratis, sin registro).
+
+Con token (obtener en https://mineru.net/apiManage/token), habilita extracción
+de precisión con tablas, fórmulas y formatos adicionales.
+
+## Configuración del token para extract
+
+El modo `extract` requiere un token gratuito de https://mineru.net/apiManage/token.
+
+**Configurar vía variable de entorno** (recomendado — funciona en Claude Code):
+
+```bash
+# Linux / macOS — agregar a ~/.bashrc o ~/.zshrc
+export MINERU_TOKEN="tu_token_aqui"
+
+# Windows PowerShell — persistente a nivel de usuario
+[System.Environment]::SetEnvironmentVariable("MINERU_TOKEN", "tu_token_aqui", "User")
+```
+
+**Verificar que el token funciona**:
+
+```bash
+mineru-open-api auth --verify
+# Debe mostrar: Token format is valid / Source: env
+```
+
+> **Nota**: El comando `mineru-open-api auth` (modo interactivo) no funciona
+> dentro de Claude Code porque requiere entrada interactiva. Usar siempre la
+> variable de entorno `MINERU_TOKEN` como método de configuración.
+
+Para el MCP, el token se configura en `.mcp.json` con la variable `MINERU_API_TOKEN`
+como se muestra en la sección anterior.
+
+## Instalación del CLI
+
+```bash
+# Linux / macOS
+curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh
+
+# Windows (PowerShell) — descargar, inspeccionar y ejecutar
+Invoke-WebRequest -Uri https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 -OutFile install-mineru.ps1
+Get-Content install-mineru.ps1   # inspeccionar
+.\install-mineru.ps1             # ejecutar
+Remove-Item install-mineru.ps1   # limpiar
+```
+
+> Algunos antivirus bloquean `irm URL | iex` con detección heurística. La alternativa manual de arriba evita el bloqueo.
+
+## Formatos soportados
+
+| Formato | flash-extract | extract |
+|---------|:---:|:---:|
+| PDF (.pdf) | Sí | Sí |
+| Imágenes (.png, .jpg, .jpeg) | Sí | Sí |
+| Word (.docx) | Sí | Sí |
+| Word (.doc) | No | Sí |
+| PowerPoint (.pptx) | Sí | Sí |
+| PowerPoint (.ppt) | No | Sí |
+| HTML (.html) | No | Sí |
+| URLs remotas | Sí | Sí |
+
+## Integración con agentes SWL
+
+| Agente | Uso de extracción |
+|--------|------------------|
+| `investigador-swl` | Leer especificaciones, papers, documentos de referencia en PDF |
+| `arquitecto-swl` | Analizar documentos de arquitectura existentes |
+| `mapear-codebase` | Incluir documentación no-código del proyecto |
+| `producto-prd-swl` | Extraer requisitos de documentos del cliente |
+| `revisor-seguridad-swl` | Leer políticas de seguridad en PDF |
+
+## Idiomas soportados
+
+| Código | Idiomas |
+|--------|---------|
+| `ch` | Chino, Inglés (predeterminado) |
+| `en` | Inglés |
+| `latin` | Español, Francés, Alemán, Portugués, Italiano y 40+ idiomas latinos |
+| `arabic` | Árabe, Persa, Urdu |
+| `cyrillic` | Ruso, Ucraniano, Búlgaro |
+| `devanagari` | Hindi, Marathi, Nepali |
+
+Para documentos en español: usar `--language latin` en el CLI.
+
+## Manejo de errores
+
+| Error | Causa | Solución |
+|-------|-------|---------|
+| Archivo > 10 MB en flash | Límite de flash-extract | Usar `extract` con token |
+| Archivo > 20 páginas en flash | Límite de flash-extract | Usar `extract` con token |
+| HTTP 429 | Rate limit por IP | Esperar o usar `extract` con token |
+| "no API token found" | Token no configurado | `mineru-open-api auth` o variable `MINERU_TOKEN` |
+| Tablas no extraídas | flash-extract no soporta tablas | Usar `extract` con token |
+
+## Gotchas / Errores comunes no obvios
+
+**`flash-extract` en documentos escaneados en español produce texto con palabras fusionadas y caracteres faltantes aunque el PDF parezca digital**: muchos PDFs "digitales" en México (contratos, actas) son en realidad imágenes escaneadas incrustadas. Flash no tiene OCR de precisión y entrega texto ilegible sin error visible. Causa: `flash-extract` no distingue si el PDF contiene texto nativo o imágenes rasterizadas. Fix: si el output de flash tiene palabras sin espacios o texto truncado, cambiar a `extract` con token inmediatamente. Señal temprana: `mineru-open-api flash-extract` devuelve Markdown con menos de 50 palabras para un documento de 10+ páginas.
+
+**El MCP de MinerU falla silenciosamente cuando `MINERU_API_TOKEN` está vacío en `.mcp.json`**: si la variable de entorno `MINERU_API_TOKEN` no está configurada, el MCP arranca en modo flash pero no emite error — simplemente produce output de menor calidad sin advertir. Causa: el MCP asume que la ausencia de token es intencional (modo gratuito). Fix: verificar que el MCP está usando token con `claude-notifications-go status` o inspeccionando el output: si `parse_documents` devuelve chunks de menos de 100 tokens para páginas densas, el token no está activo. Configurar `MINERU_API_TOKEN` en el `.env` del proyecto y reiniciar el MCP.
+
+**`mineru-open-api extract *.pdf` procesa los archivos en paralelo y puede saturar la quota de la API si hay más de 5 PDFs**: el comando acepta glob pero lanza todas las peticiones concurrentemente. Con 10+ PDFs, el servidor devuelve HTTP 429 y algunos archivos quedan con extracción incompleta sin error claro. Causa: el CLI no tiene rate limiting incorporado. Fix: procesar en lotes secuenciales con un bucle: `for f in *.pdf; do mineru-open-api extract "$f" -o ./salida/; sleep 2; done`.
+
+**La ruta de salida por defecto de `extract` crea subdirectorios por archivo y el agente no encuentra el Markdown resultante**: `mineru-open-api extract contrato.pdf` crea `./contrato/contrato.md` (no `./contrato.md`). Si el agente busca `contrato.md` directamente, no lo encuentra. Causa: MinerU crea un directorio con el nombre del archivo para agrupar el Markdown y los recursos (imágenes, tablas). Fix: usar `-o ./salida/` y luego buscar con `find ./salida -name "*.md"`, o especificar la ruta completa de destino con `--output-file` si la versión del CLI lo soporta.

package/habilidades/extractor-de-aprendizajes/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.11.0",
+    "evolvedAt": "2026-04-22",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Gotchas nuevos: registro dual manifiestos para hooks + inventario estimado a mano"
+  }
+}