@saulwade/swl-ses 1.0.0

package/habilidades/swl-dashboard/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: swl-dashboard
+description: >
+  Lanza el dashboard web interactivo de uso de Claude Code (claude-usage).
+  Muestra métricas históricas de tokens, costos por modelo, sesiones y proyectos
+  con gráficos interactivos. Requiere Python 3.8+. Subcomandos: dashboard (web),
+  today (resumen de hoy en terminal), stats (estadísticas históricas en terminal).
+  Activar cuando el usuario pide ver el dashboard, análisis histórico de costos,
+  métricas de sesiones anteriores o comparativa de modelos.
+user-invocable: false
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Glob]
+exclusiones:
+  - "No cargar para ver métricas de la sesión actual en tiempo real — usar `/swl:metricas`; este skill requiere datos históricos de múltiples sesiones en `~/.claude/projects/**/*.jsonl`."
+  - "No cargar si `claude-usage` no está disponible y el objetivo es solo verificar el estado del sistema SWL — usar `/swl:salud` que no depende de la instalación de la herramienta vendor."
+  - "No cargar para diagnosticar por qué un agente falló — este skill muestra métricas de tokens y costos, no trazas de error de agentes; para eso usar `tracing-processor` o revisar `.planning/traces/`."
+  - "No cargar en entornos CI/headless donde no hay browser para abrir el dashboard web — usar el subcomando `stats` o `today` que salen en terminal sin servidor HTTP."
+evolvable: true  # default para skill estandar
+---
+# Skill: swl-dashboard
+
+Lanza el análisis de uso histórico de Claude Code mediante claude-usage
+(scripts/vendor/claude-usage/), una herramienta Python zero-dependencies
+que parsea los JSONL de Claude Code y genera un dashboard web interactivo.
+
+## Subcomandos
+
+| Subcomando | Comportamiento |
+|------------|---------------|
+| (vacío) o `dashboard` | Escanea JSONL → abre dashboard web en http://localhost:8080 |
+| `today` | Imprime en terminal el resumen de consumo del día actual |
+| `stats` | Imprime estadísticas históricas completas (all-time) |
+| `scan` | Solo sincroniza JSONL → SQLite sin abrir dashboard |
+
+## Paso 0 — Verificar Python disponible
+
+```bash
+python3 --version 2>/dev/null || python --version 2>/dev/null
+```
+
+Si Python < 3.8 o no está disponible:
+```
+⚠ swl-dashboard requiere Python 3.8+. No se encontró intérprete compatible.
+   Instala Python desde https://python.org o usa: winget install Python.Python.3
+   Alternativa: usa /swl:metricas para métricas de la sesión actual.
+```
+Detener y mostrar el mensaje anterior.
+
+## Paso 1 — Detectar intérprete y localizar cli.py
+
+Localizar `cli.py` con búsqueda en cascada (proyecto → global ~/.claude → npm → caché npx):
+
+```bash
+# 1. Root del proyecto actual
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+CLI_PY="$PROJECT_ROOT/scripts/vendor/claude-usage/cli.py"
+
+# 2. Fallback: instalación global de swl-ses en cualquier runtime compatible
+#    Copiado automáticamente por `swl-ses install --global --target <runtime>`
+#    Cubre: claude, openclaude, opencode, gemini, copilot, codex
+if [ ! -f "$CLI_PY" ]; then
+  for RUNTIME_DIR in "$HOME/.claude" "$HOME/.openclaude" "$HOME/.opencode" "$HOME/.gemini" "$HOME/.github" "$HOME/.codex"; do
+    CANDIDATE="$RUNTIME_DIR/scripts/vendor/claude-usage/cli.py"
+    if [ -f "$CANDIDATE" ]; then
+      CLI_PY="$CANDIDATE"
+      break
+    fi
+  done
+fi
+
+# 3. Fallback: instalación global de npm (paquete canónico o mirror)
+if [ ! -f "$CLI_PY" ]; then
+  NPM_GLOBAL=$(npm root -g 2>/dev/null)
+  for SCOPE in "@saulwade/swl-ses" "@saul-wade/swl-ses"; do
+    CANDIDATE="$NPM_GLOBAL/$SCOPE/scripts/vendor/claude-usage/cli.py"
+    if [ -f "$CANDIDATE" ]; then
+      CLI_PY="$CANDIDATE"
+      break
+    fi
+  done
+fi
+
+# 4. Fallback: caché de npx (npx swl-ses sin instalar globalmente)
+if [ ! -f "$CLI_PY" ]; then
+  NPX_CACHE=$(npm config get cache 2>/dev/null)/_npx
+  FOUND=$(find "$NPX_CACHE" -name "cli.py" -path "*/claude-usage/cli.py" 2>/dev/null | sort -r | head -1)
+  [ -n "$FOUND" ] && CLI_PY="$FOUND"
+fi
+
+echo "CLI_PY=$CLI_PY"
+[ -f "$CLI_PY" ] && echo "OK" || echo "MISSING"
+```
+
+Si el resultado es `MISSING` después de los cuatro intentos:
+```
+⚠ claude-usage no encontrado en ninguna ubicación conocida.
+
+   La herramienta requiere que swl-ses esté instalado globalmente.
+   Ejecuta desde el directorio del repo swl-ses:
+
+     swl-ses install --global --profile completo
+
+   Esto copia claude-usage a ~/.claude/scripts/vendor/claude-usage/ y lo hace
+   disponible en todos los proyectos automáticamente.
+
+   Alternativa inmediata: /swl:metricas para métricas de la sesión actual.
+```
+
+> **Nota**: guardar `CLI_PY` y el directorio padre `VENDOR_DIR=$(dirname "$CLI_PY")` para usarlos en el Paso 2.
+
+## Paso 2 — Ejecutar según subcomando
+
+> Usar `CLI_PY` y `VENDOR_DIR` detectados en el Paso 1.
+> Todos los comandos necesitan `cd "$VENDOR_DIR"` previo para que los imports relativos (scanner.py, dashboard.py) funcionen.
+
+### Subcomando: `today`
+
+```bash
+cd "$VENDOR_DIR"
+python "$CLI_PY" scan 2>/dev/null
+python "$CLI_PY" today
+```
+
+Muestra el consumo del día en terminal. Ejemplo de salida esperada:
+```
+------------------------------------------------------------
+  Today's Usage  (2026-04-08)
+------------------------------------------------------------
+  claude-sonnet-4-6   turns=47  in=125.4K  out=42.9K  cost=$0.58
+------------------------------------------------------------
+  TOTAL               turns=47  in=125.4K  out=42.9K  cost=$0.58
+  Sessions today: 3
+------------------------------------------------------------
+```
+
+### Subcomando: `stats`
+
+```bash
+cd "$VENDOR_DIR"
+python "$CLI_PY" scan 2>/dev/null
+python "$CLI_PY" stats
+```
+
+Muestra estadísticas históricas all-time con desglose por modelo y top proyectos.
+
+### Subcomando: `scan`
+
+```bash
+cd "$VENDOR_DIR"
+python "$CLI_PY" scan
+echo "✓ Base de datos actualizada: ~/.claude/usage.db"
+```
+
+### Subcomando: `dashboard` (o vacío)
+
+`cli.py` detecta automáticamente el primer puerto libre (8888 → 9090 → 9191 …).
+**Nota:** 8080 está excluido intencionalmente — suele estar ocupado por Postgres, IIS u otros servicios.
+Si el usuario especificó un puerto con `/swl:dashboard --port 9090`, pasarlo explícitamente.
+
+**IMPORTANTE:** No verificar disponibilidad con `curl http://localhost:8080` — ese puerto puede estar
+ocupado por otro servicio y devolvería un falso positivo. Usar el flujo siguiente:
+
+```bash
+cd "$VENDOR_DIR"
+# Scan previo para asegurar datos actualizados
+python "$CLI_PY" scan 2>/dev/null
+
+# Detectar qué puerto está libre ANTES de iniciar (para saber cuál reportar al usuario)
+DASHBOARD_PORT=$(python3 -c "
+import socket
+candidates = [8888, 9090, 9191, 7777, 7878, 8181, 8282, 8383]
+for p in candidates:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind(('localhost', p))
+            print(p)
+            break
+        except OSError:
+            pass
+" 2>/dev/null)
+
+# Si el usuario especificó un puerto explícito, usarlo en su lugar
+# DASHBOARD_PORT="${PUERTO_EXPLICITO:-$DASHBOARD_PORT}"
+
+# Iniciar dashboard en background con el puerto detectado
+python "$CLI_PY" dashboard --port "$DASHBOARD_PORT" &
+sleep 3
+```
+
+Después de ejecutar el último comando, mostrar al usuario:
+```
+Dashboard iniciando en http://localhost:<DASHBOARD_PORT>
+
+Filtros disponibles:
+  • Rangos de tiempo: 7d, 30d, 90d, all
+  • Selección de modelos: checkboxes interactivos
+  • URLs bookmarkeables: ?range=7d&models=claude-sonnet-4-6
+
+Presiona Ctrl+C en el terminal para detener el servidor.
+```
+
+> El dashboard se auto-refresca cada 30 segundos. Para sesiones activas,
+> los datos se sincronizan al detener la sesión (Stop hook).
+
+## Paso 3 — Si falla la ejecución
+
+Si Python devuelve error al correr cli.py:
+
+```bash
+cd "$VENDOR_DIR"
+python "$CLI_PY" scan 2>&1
+```
+
+Mostrar el error exacto y sugerir según el tipo:
+
+| Error | Causa | Solución |
+|-------|-------|----------|
+| `No module named X` | cli.py es zero-dependencies; no debería ocurrir | Verifica integridad: `head -5 "$CLI_PY"` |
+| `No such file ~/.claude/projects/` | Claude Code no ha creado sesiones aún | Inicia una sesión de trabajo normal primero |
+| `PermissionError: [WinError 10013]` | Puerto reservado por Windows (Hyper-V, Docker, IIS) | El auto-detect de puertos debería evitarlo; si persiste: `python "$CLI_PY" dashboard --port 9999` |
+| `No se encontró ningún puerto disponible` | Todos los puertos candidatos bloqueados | Especificar uno manualmente: `--port 9999` |
+
+## Datos que visualiza el dashboard
+
+| Métrica | Descripción |
+|---------|-------------|
+| Daily token usage | Gráfico de barras apiladas: input / output / cache read / cache creation por día |
+| By model | Doughnut: distribución de tokens por modelo (sonnet vs opus vs haiku) |
+| Top projects | Barras horizontales: top 10 proyectos por consumo |
+| Sessions table | Tabla con: sesión, proyecto, duración, modelo, turns, tokens, costo estimado |
+| Model cost table | Desglose de costo total por modelo |
+
+## Dónde se almacenan los datos
+
+- **Base de datos**: `~/.claude/usage.db` (SQLite, ~cero dependencias)
+- **Fuente de datos**: `~/.claude/projects/**/*.jsonl` (logs de Claude Code)
+- **Actualización**: al ejecutar `scan` o al inicio de cada subcomando
+
+## Subcomando: `guardrails`
+
+Muestra en terminal las métricas de activación y bloqueo de los guardrails (hooks bloqueantes)
+de la sesión actual. Los datos provienen de `hooks/lib/guardrail-metrics.js`.
+
+```bash
+# Leer métricas de guardrails de la sesión actual desde /tmp/
+SESSION_ID="${CLAUDE_SESSION_ID:-default}"
+BRIDGE_FILE="/tmp/swl-guardrail-metrics-${SESSION_ID}.json"
+
+if [ -f "$BRIDGE_FILE" ]; then
+  node -e "
+    const m = require('$BRIDGE_FILE');
+    const hooks = m.hooks || {};
+    const entries = Object.entries(hooks).sort(([,a],[,b]) => b.bloqueos - a.bloqueos);
+    if (entries.length === 0) {
+      console.log('Ningún guardrail se activó en esta sesión.');
+    } else {
+      console.log('\\nGuardrails — Activaciones de la sesión\\n');
+      console.log('Hook'.padEnd(30) + 'Activaciones'.padStart(13) + 'Bloqueos'.padStart(9) + 'Warnings'.padStart(9) + 'Tasa'.padStart(7));
+      console.log('-'.repeat(68));
+      for (const [nombre, datos] of entries) {
+        const tasa = datos.activaciones > 0 ? Math.round(datos.bloqueos / datos.activaciones * 100) + '%' : '0%';
+        console.log(nombre.replace('.js','').padEnd(30) + String(datos.activaciones).padStart(13) + String(datos.bloqueos).padStart(9) + String(datos.warnings).padStart(9) + tasa.padStart(7));
+      }
+    }
+  "
+else
+  echo "Sin datos de guardrails para esta sesión. (bridge: $BRIDGE_FILE)"
+  echo "Los guardrails registran métricas cuando se activan durante la sesión."
+fi
+```
+
+Después de mostrar la tabla, ejecutar diagnóstico automático:
+
+```bash
+node -e "
+  try {
+    const { getMetrics, diagnosticar } = require('./hooks/lib/guardrail-metrics');
+    const SESSION_ID = process.env.CLAUDE_SESSION_ID || 'default';
+    const metricas = getMetrics(SESSION_ID);
+    const advertencias = diagnosticar(metricas);
+    if (advertencias.length > 0) {
+      console.log('\\n⚠ Diagnóstico:');
+      advertencias.forEach(a => console.log('  - ' + a));
+    } else {
+      console.log('\\n✓ Guardrails sin anomalías detectadas.');
+    }
+  } catch(e) { console.log('(sin datos disponibles)'); }
+"
+```
+
+> El resumen de guardrails también aparece automáticamente al final de cada sesión
+> (hook `resumen-sesion.js`) cuando hay advertencias de tasa anómala.
+
+## Estructura por widgets (v2, inspirado en mission-control)
+
+El módulo `scripts/lib/dashboard-widgets.js` define un catálogo estructurado de 19 widgets
+distribuidos en 7 categorías. Permite organizar la salida del dashboard por bloques
+categorizados en lugar del bloque monolítico actual.
+
+### Categorías disponibles
+
+| Categoría  | Widgets incluidos                                               | Modo     |
+|------------|-----------------------------------------------------------------|----------|
+| health     | health-score, health-row, health-componentes                    | offline  |
+| agentes    | agentes-activos, agentes-top-uso, cadenas-delegacion           | mixed    |
+| metricas   | tokens-hoy, costo-hoy, costo-por-agente, costo-por-modelo      | offline  |
+| evolucion  | nudges-recientes, evoluciones-aplicadas, alertas-persistentes  | offline  |
+| sesiones   | sesiones-activas, sesiones-historial                            | offline  |
+| costos     | costos-tendencia, costos-proyectos                              | offline  |
+| seguridad  | security-posture, auditoria-reciente                            | online   |
+
+Modos: `offline` = funciona leyendo archivos locales; `online` = requiere conexión activa.
+
+### Uso básico
+
+```javascript
+const { listarPorCategoria, listarPorModo, obtenerWidget, obtenerLayoutDefault } =
+  require('./scripts/lib/dashboard-widgets');
+
+// Todos los widgets de salud disponibles sin conexión
+const widgetsHealth = listarPorCategoria('health');
+
+// Layout sugerido para sesión sin gateway
+const layout = obtenerLayoutDefault('offline');
+
+// Obtener un widget por ID
+const w = obtenerWidget('health-score');
+// → { id: 'health-score', label: 'Score de Salud', categoria: 'health', modos: ['offline'], tamanoDefault: 'sm', ... }
+```
+
+### Integración futura en la salida del comando
+
+Al generar la salida de `/swl:dashboard`, iterar el layout default del modo detectado
+y renderizar cada widget con su categoría como sección:
+
+```javascript
+const layout = obtenerLayoutDefault('offline');
+for (const id of layout) {
+  const widget = obtenerWidget(id);
+  // Renderizar sección: `## ${widget.categoria} / ${widget.label}`
+}
+```
+
+La integración real de datos por widget es responsabilidad del código de ejecución del
+comando. El catálogo solo define la estructura — no accede a fuentes de datos.
+
+## Relación con otros componentes SWL
+
+| Componente SWL | Scope | Complemento |
+|---------------|-------|-------------|
+| `tracking-costos.js` (hook) | Sesión actual, tiempo real | swl-dashboard añade histórico multi-sesión |
+| `/swl:metricas` (comando) | Sesión actual | swl-dashboard añade visualización gráfica |
+| `.planning/METRICAS.md` | Persistencia por proyecto | swl-dashboard agrega consulta SQL cross-project |
+| `resumen-sesion.js` (hook) | Resumen inline al Stop | swl-dashboard añade análisis post-hoc detallado |
+| `guardrail-metrics.js` (lib) | Sesión actual | swl-dashboard `guardrails` muestra activaciones/bloqueos por hook |
+
+## Cuándo NO cargar
+
+- El usuario quiere ver métricas de la sesión activa actual — usar `/swl:metricas`; este skill procesa el historial persisitido en `~/.claude/projects/`, no el stream en tiempo real de la sesión.
+- `claude-usage` no está instalado y el objetivo es diagnosticar la salud del sistema SWL — usar `/swl:salud`; no tiene sentido cargar este skill si la única acción posible sería indicar que hay que instalar la herramienta vendor.
+- Se ejecuta en un entorno CI/headless o en un servidor remoto sin browser — los subcomandos `today` y `stats` funcionan en terminal, pero si el objetivo era el dashboard web interactivo, ese entorno no lo soporta.
+- Se busca trazar el motivo de fallo de un agente específico — este skill visualiza consumo de tokens y costos; los detalles de error de agente están en `.planning/traces/` y se analizan con `tracing-processor`.
+
+## Gotchas / Errores comunes no obvios
+
+- **`curl http://localhost:8080` devuelve 200 pero no es el dashboard**: el skill advierte explícitamente que el puerto 8080 suele estar ocupado por Postgres, IIS u otros servicios y puede devolver falso positivo. Causa: verificar disponibilidad en lugar de dejar que `cli.py` detecte el primer puerto libre. Solución: no verificar con `curl` — el flujo correcto es detectar el puerto libre con el script Python de socket binding del Paso 2 y reportar ese puerto al usuario; si el usuario abre ese puerto, verá el dashboard correcto.
+- **`cd "$VENDOR_DIR"` omitido antes de `python "$CLI_PY"`**: el script falla con `ModuleNotFoundError` porque `scanner.py` y `dashboard.py` se importan con rutas relativas. Causa: ejecutar `python $CLI_PY` desde el directorio de trabajo del proyecto en lugar de desde el directorio del vendor. Solución: siempre `cd "$VENDOR_DIR"` antes de cualquier invocación de `cli.py` — es el requisito documentado en el Paso 2 del skill.
+- **Base de datos vacía después de ejecutar el dashboard**: el dashboard muestra gráficos vacíos aunque hay sesiones en `~/.claude/projects/`. Causa: `scan` no se ejecutó antes del subcomando principal. Solución: ejecutar `python "$CLI_PY" scan 2>/dev/null` como paso previo a cualquier subcomando — `scan` es quien parsea los JSONL y puebla `~/.claude/usage.db`.
+- **Fallback a `~/.claude` cuando el repo tiene su propio vendor**: el script busca `CLI_PY` en el directorio del proyecto primero; si no lo encuentra, busca en instalaciones globales. Si el usuario tiene una versión global más antigua que la del repo, el skill usa la versión incorrecta. Causa: el Paso 1 resuelve los 4 fallbacks en orden pero no verifica versiones. Solución: si el repo tiene `scripts/vendor/claude-usage/cli.py`, esa siempre tiene precedencia — verificar con `head -1 "$CLI_PY"` que la versión encontrada es la del repo.

package/habilidades/swl-markitdown/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: swl-markitdown
+description: >
+  Convierte cualquier formato de documento a Markdown estructurado para su
+  consumo por agentes SWL. Soporta PDF, DOCX, XLSX, PPTX, Jupyter, EPUB,
+  ZIP, HTML, CSV, JSON, YouTube URLs y más. Wrapper sobre Microsoft MarkItDown
+  (AutoGen Team). Usar cuando el Read tool no soporta el formato del archivo.
+  Complementa WebFetch/agent-browser para URLs con contenido estructurado.
+user-invocable: false
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Glob, Grep, WebFetch]
+evolved: false
+fuente: "Microsoft AutoGen Team — markitdown v0.1.5 (2025)"
+dependencias: "pip install markitdown[pdf,docx,pptx,xlsx]"
+exclusiones:
+  - "No cargar para archivos .md, .txt o código fuente — el Read tool los soporta directamente y es más rápido sin el overhead de conversión."
+  - "No cargar para PDFs de ≤20 páginas sin tablas complejas — el Read tool con parámetro `pages:` es suficiente y no requiere la dependencia Python."
+  - "No cargar para URLs web genéricas sin contenido estructurado de documento — WebFetch es el camino correcto para HTML; swl-markitdown agrega valor cuando el HTML tiene estructura de documento (Wikipedia, documentación técnica con tablas)."
+  - "No cargar cuando el objetivo es buscar un patrón o string dentro de un archivo — Grep sobre el archivo original es más eficiente que convertir a Markdown primero."
+evolvable: true  # default para skill estandar
+---
+# Skill: swl-markitdown
+
+Proporciona conversión universal de documentos a Markdown para agentes SWL.
+Es el puente entre archivos en formatos propietarios (DOCX, XLSX, PPTX, PDF)
+y el contexto de los agentes que solo consumen texto Markdown.
+
+## Árbol de decisión: qué herramienta usar
+
+| Fuente | Herramienta | Por qué |
+|--------|-------------|---------|
+| `.md`, `.txt` (local) | `Read` | Directo, sin overhead |
+| `.pdf` ≤ 20 páginas (local) | `Read` con `pages:` | Read soporta PDFs nativamente |
+| `.pdf` > 20 páginas o con tablas | **`swl-markitdown`** | Extrae tablas como Markdown |
+| `.docx`, `.pptx` (local) | **`swl-markitdown`** | Read no soporta estos formatos |
+| `.xlsx`, `.xls` (local) | **`swl-markitdown`** | Convierte hojas a tablas Markdown |
+| `.ipynb` Jupyter (local) | **`swl-markitdown`** | Read devuelve JSON crudo |
+| `.csv` (local) | `Read` o **`swl-markitdown`** | Ambos funcionan; MarkItDown da tabla formateada |
+| URL estática (HTML simple) | `WebFetch` | Más rápido, sin overhead |
+| URL dinámica (SPA, JS) | `agent-browser` | Renderiza JavaScript |
+| URL de YouTube | **`swl-markitdown`** | Transcripción automática sin LLM |
+| URL de Wikipedia | `WebFetch` o **`swl-markitdown`** | Ambos; MarkItDown da estructura más limpia |
+| ZIP con documentos mixtos | **`swl-markitdown`** | Descomprime y convierte recursivamente |
+
+## Paso 0 — Verificar disponibilidad
+
+```bash
+# Verificar que markitdown está instalado y funcional
+CLI_PATH=$(git rev-parse --show-toplevel 2>/dev/null)/scripts/vendor/markitdown/cli.py
+python "$CLI_PATH" --check 2>/dev/null | grep "Estado:" || echo "NO_DISPONIBLE"
+```
+
+Si devuelve `NO_DISPONIBLE` o falta el cli.py:
+
+```bash
+# Instalar markitdown con soporte para formatos principales
+pip install markitdown[pdf,docx,pptx,xlsx]
+
+# Verificar instalación
+python "$CLI_PATH" --check
+```
+
+Si pip no está disponible, reportar al usuario:
+```
+swl-markitdown requiere Python 3.10+ y pip.
+  pip install markitdown[pdf,docx,pptx,xlsx]
+
+El Read tool sigue disponible para .pdf (hasta 20 páginas), .txt y .md.
+WebFetch y agent-browser siguen disponibles para URLs.
+```
+
+## Paso 1 — Conversión básica
+
+### Archivo local
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+CLI_PY="$PROJECT_ROOT/scripts/vendor/markitdown/cli.py"
+
+# Convertir archivo a Markdown
+OUTPUT=$(python "$CLI_PY" "/ruta/absoluta/al/archivo.docx" 2>/dev/null)
+
+# Verificar que la conversión fue exitosa (output no vacío)
+if [ -n "$OUTPUT" ]; then
+  echo "$OUTPUT"
+else
+  echo "CONVERSION_FAILED — usar Read tool como fallback"
+fi
+```
+
+### Guardar directamente a raw/ del wiki
+
+```bash
+FECHA=$(date +%Y%m%d)
+NOMBRE=$(basename "ARCHIVO_FUENTE" | sed 's/\.[^.]*$//' | sed 's/[^a-zA-Z0-9]/-/g' | cut -c1-50)
+DESTINO="$PROJECT_ROOT/.planning/knowledge/raw/${FECHA}-${NOMBRE}.md"
+
+python "$CLI_PY" "/ruta/al/archivo.docx" > "$DESTINO" 2>/dev/null && \
+  echo "Guardado: $DESTINO" || \
+  echo "Error de conversion"
+```
+
+### URL de YouTube (transcripción)
+
+```bash
+# Requiere: pip install youtube-transcript-api
+OUTPUT=$(python "$CLI_PY" "https://www.youtube.com/watch?v=VIDEO_ID" 2>/dev/null)
+[ -n "$OUTPUT" ] && echo "$OUTPUT" | head -50
+```
+
+## Paso 2 — Patrones de uso frecuentes
+
+### Patrón A: Ingest masivo de documentación existente
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+CLI_PY="$PROJECT_ROOT/scripts/vendor/markitdown/cli.py"
+RAW_DIR="$PROJECT_ROOT/.planning/knowledge/raw"
+mkdir -p "$RAW_DIR"
+
+# Procesar todos los archivos Office en un directorio
+for FILE in ./docs/**/*.{docx,pptx,xlsx,pdf}; do
+  [ -f "$FILE" ] || continue
+  FECHA=$(date +%Y%m%d)
+  NOMBRE=$(basename "$FILE" | sed 's/\.[^.]*$//' | sed 's/[^a-zA-Z0-9]/-/g' | cut -c1-50)
+  DESTINO="$RAW_DIR/${FECHA}-${NOMBRE}.md"
+  
+  if python "$CLI_PY" "$FILE" > "$DESTINO" 2>/dev/null; then
+    echo "[OK] $FILE -> $DESTINO"
+  else
+    echo "[SKIP] $FILE — formato no soportado o dependencia faltante"
+    rm -f "$DESTINO"
+  fi
+done
+```
+
+### Patrón B: Comparar con Read tool para PDFs
+
+```bash
+# Para PDFs cortos (≤20 páginas): Read tool es más rápido
+# Para PDFs largos o con tablas: swl-markitdown extrae mejor
+
+CLI_PY="$(git rev-parse --show-toplevel)/scripts/vendor/markitdown/cli.py"
+OUTPUT=$(python "$CLI_PY" "documento.pdf" 2>/dev/null)
+
+# Verificar si hay tablas en el output (MarkItDown las extrae, Read no)
+TIENE_TABLAS=$(echo "$OUTPUT" | grep -c "^|" || echo 0)
+echo "Tablas detectadas: $TIENE_TABLAS"
+```
+
+### Patrón C: Preprocesamiento antes de invocar agente
+
+```bash
+# Convertir spec de requisitos DOCX a Markdown antes de pasarlo al planificador
+CLI_PY="$(git rev-parse --show-toplevel)/scripts/vendor/markitdown/cli.py"
+
+SPEC_MD=$(python "$CLI_PY" "requisitos/spec-v2.docx" 2>/dev/null)
+if [ -z "$SPEC_MD" ]; then
+  echo "ERROR: no se pudo convertir spec-v2.docx"
+  exit 1
+fi
+
+# Guardar en .planning/ para que planificador-swl lo lea
+echo "$SPEC_MD" > .planning/SPEC.md
+echo "Spec convertida a .planning/SPEC.md — invocar planificador-swl"
+```
+
+### Patrón D: Notebook Jupyter para investigador-swl
+
+```bash
+# Jupyter notebooks contienen código, outputs y análisis mezclados
+# swl-markitdown los convierte preservando celdas de código y markdown
+
+CLI_PY="$(git rev-parse --show-toplevel)/scripts/vendor/markitdown/cli.py"
+OUTPUT=$(python "$CLI_PY" "analisis/experimento.ipynb" 2>/dev/null)
+
+# El output incluye:
+# - Celdas markdown como texto normal
+# - Celdas de código en bloques ```python
+# - Outputs de celdas si están guardados en el notebook
+echo "$OUTPUT" | head -100
+```
+
+## Paso 3 — Manejo de errores
+
+| Código de salida | Causa | Acción |
+|-----------------|-------|--------|
+| `0` | Conversión exitosa | Usar el output |
+| `1` | Formato no soportado | Intentar WebFetch o Read |
+| `2` | Dependencia faltante | `pip install markitdown[<formato>]` |
+| `3` | Error de conversión (archivo corrupto) | Reportar al usuario |
+| `4` | Archivo no encontrado | Verificar la ruta |
+
+```bash
+CLI_PY="$(git rev-parse --show-toplevel)/scripts/vendor/markitdown/cli.py"
+python "$CLI_PY" "archivo.docx" > output.md 2>error.log
+EXIT_CODE=$?
+
+case $EXIT_CODE in
+  0) echo "OK — Markdown en output.md" ;;
+  1) echo "Formato no soportado — usar alternativa" ;;
+  2) cat error.log; echo "Instalar dependencia y reintentar" ;;
+  3) cat error.log; echo "Archivo probablemente corrupto" ;;
+  4) echo "Archivo no encontrado — verificar ruta" ;;
+esac
+```
+
+## Paso 4 — Formatos soportados
+
+```bash
+# Ver todos los formatos con el estado de dependencias actual
+python "$(git rev-parse --show-toplevel)/scripts/vendor/markitdown/cli.py" --formats
+```
+
+### Formatos siempre disponibles (sin dependencias extra)
+
+| Formato | Extensión | Notas |
+|---------|-----------|-------|
+| HTML | `.html` `.htm` | Conversión completa con BeautifulSoup |
+| Texto plano | `.txt` `.md` `.markdown` | Pass-through con detección de charset |
+| CSV | `.csv` | Convertido a tabla Markdown |
+| JSON | `.json` | Formateado estructuralmente |
+| XML / RSS / Atom | `.xml` `.rss` `.atom` | Feeds formateados |
+| ZIP | `.zip` | Descomprime y convierte todo el contenido |
+| EPUB | `.epub` | Libros electrónicos |
+| Jupyter | `.ipynb` | Celdas código + markdown |
+| Wikipedia URLs | `wikipedia.org/*` | Extracción de contenido principal |
+
+### Formatos con dependencias opcionales
+
+| Formato | Dependencia | Instalar |
+|---------|-------------|---------|
+| PDF | `pdfminer.six`, `pdfplumber` | `pip install markitdown[pdf]` |
+| Word (.docx) | `mammoth`, `lxml` | `pip install markitdown[docx]` |
+| Excel (.xlsx) | `pandas`, `openpyxl` | `pip install markitdown[xlsx]` |
+| Excel (.xls) | `pandas`, `xlrd` | `pip install markitdown[xls]` |
+| PowerPoint (.pptx) | `python-pptx` | `pip install markitdown[pptx]` |
+| YouTube | `youtube-transcript-api` | `pip install markitdown[youtube-transcription]` |
+
+## Qué NO usar de MarkItDown en swl-ses
+
+- **Azure Document Intelligence** — dependencia de nube, costo por página, conflicto con filosofía local-first
+- **Audio transcription** (SpeechRecognition) — sin caso de uso en swl-ses
+- **LLM Vision para imágenes** — Claude ya es multimodal; duplicidad
+- **markitdown-ocr plugin** — requiere GPT-4o explícito; Claude lo haría en el contexto actual
+
+## Integración con /swl:wiki
+
+El skill es transparente para `/swl:wiki ingest`: cuando se detecta un formato
+no-Markdown, el comando invoca `swl-markitdown` automáticamente antes de ingerir.
+
+```bash
+# El Paso I.1 del ingest decide la herramienta según extensión:
+# .md .txt → Read tool
+# .pdf .docx .xlsx .pptx .ipynb .epub .zip → swl-markitdown
+# http:// https:// → WebFetch, con agent-browser como fallback
+```
+
+## Señales de que swl-markitdown completó correctamente
+
+- Output tiene >100 palabras de contenido real (no solo metadatos)
+- No hay mensajes de error en stderr
+- El código de salida es 0
+- El contenido tiene estructura Markdown (encabezados, tablas o listas)
+
+## Señales de problema
+
+- Output vacío con código 1 → el formato no está registrado (revisar extensión)
+- Output vacío con código 2 → `pip install markitdown[<formato>]`
+- Output solo de metadatos → el archivo puede estar protegido con contraseña
+- Caracteres extraños → el archivo usa encoding no-UTF8; MarkItDown lo maneja internamente
+
+## Cuándo NO cargar
+
+- El archivo es `.md`, `.txt`, código fuente o cualquier texto plano — el Read tool lo lee directamente sin overhead de conversión ni dependencia Python.
+- El archivo es un PDF de ≤20 páginas sin tablas complejas — el Read tool con `pages:` es suficiente; swl-markitdown agrega valor principalmente para tablas que Read no puede extraer estructuradamente.
+- Se quiere acceder al contenido de una URL web genérica — WebFetch es el camino; swl-markitdown en URLs solo vale cuando son páginas con estructura de documento (Wikipedia, docs técnicas con tablas).
+- El objetivo es encontrar un patrón específico dentro del documento — Grep sobre el archivo original es más directo que convertir a Markdown primero para luego buscar en el resultado.
+
+## Gotchas / Errores comunes no obvios
+
+- **`python "$CLI_PY" archivo.docx` ejecutado sin `cd "$VENDOR_DIR"` previo**: el script falla con `ImportError` porque los módulos auxiliares se importan con rutas relativas al directorio del vendor. Causa: ejecutar el CLI desde el directorio de trabajo del proyecto en lugar del vendor. Solución: siempre ejecutar `CLI_PY` como `cd "$VENDOR_DIR" && python "$CLI_PY" <ruta-absoluta-al-archivo>` — la ruta del archivo debe ser absoluta para que no sea relativa al vendor.
+- **PDF con contraseña devuelve output vacío con código 0**: el agente asume que la conversión fue exitosa y pasa texto vacío al siguiente paso. Causa: algunos PDFs protegidos devuelven salida vacía sin código de error. Solución: verificar que el output tiene más de 100 palabras de contenido real (la sección "Señales de que swl-markitdown completó correctamente" lo documenta) antes de usar el output.
+- **Excel (.xls) no convertido aunque markitdown[xlsx] está instalado**: el agente instala `markitdown[xlsx]` pero `.xls` requiere `xlrd` además de `openpyxl`. Causa: la tabla de dependencias del skill muestra extensiones diferentes para `.xlsx` y `.xls`. Solución: para `.xls` instalar `markitdown[xls]` (incluye `xlrd`), no `markitdown[xlsx]` — son extras distintos.
+- **Ingest masivo con `for FILE in ./docs/**/*.docx` falla en bash sin globstar**: el globbing `**` no expande recursivamente en bash por defecto. Causa: `globstar` no está habilitado. Solución: usar `find ./docs -name "*.docx" -type f` en lugar de `**` glob, o habilitar explícitamente `shopt -s globstar` antes del loop — el Patrón A del skill usa `**` pero no activa globstar.