@saulwade/swl-ses 1.0.0

package/comandos/swl/evolucionar.md

@@ -0,0 +1,259 @@
+---
+name: swl:evolucionar
+description: Activa el protocolo de auto-evolución del sistema SWL. Analiza outputs recientes de agentes para detectar patrones y errores, propone mejoras a agentes y skills basándose en evidencia concreta, versiona los cambios y genera entradas de CHANGELOG. Flags disponibles: --agente=[nombre], --skill=[nombre], --dry-run.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:evolucionar — Protocolo de auto-evolución del sistema SWL
+
+Eres el motor de evolución del sistema SWL. Analizas el desempeño real del sistema y conviertes esa evidencia en mejoras concretas a agentes y skills. Un sistema que no evoluciona acumula deuda metodológica.
+
+Este comando es distinto a `swl:aprender`: donde `aprender` extrae conocimiento de un proyecto específico, `evolucionar` mejora el propio sistema SWL a partir de su historial de ejecución.
+
+## Relación con otros canales de aprendizaje
+
+SWL tiene **tres canales independientes** de aprendizaje. Son complementarios, no solapados:
+
+| Canal | Produce | Disparadores | Escribe en |
+|-------|---------|--------------|------------|
+| `/swl:aprender` | Conocimiento del dominio (anti-patrones, patrones, gotchas, decisiones) | Manual o nudge de `auto-consolidacion.js` (≥24h + ≥5 sesiones) | `APRENDIZAJES.md`, skills, `CLAUDE.md` |
+| `/swl:evolucionar` *(este comando)* | Mejoras al sistema SWL (versionado de agentes/skills, patches, splits, deprecaciones) | Manual o nudge de `auto-evolucion.js` (≥3 fallos o ≥10 runs/14d de un agente) | `agentes/*.md`, `habilidades/*/SKILL.md`, CHANGELOG |
+| Agente `perfilador-usuario-swl` | Modelo del usuario (rol, stack preferido, correcciones repetidas, preferencias de comunicación) | Manual o nudge de `actualizar-perfil-usuario.js` (≥3 señales acumuladas) | `instintos/perfil-usuario.yaml` |
+
+### Cómo se coordinan
+
+- **Evolución + perfil**: el parser de fricción (`auto-evolucion-protocolo` v1.1) cruza el log
+  `.planning/auto-evolucion/agentes.jsonl` con las señales de corrección del usuario
+  para priorizar agentes cuyos runs coincidieron con correcciones. Ver tabla
+  "Categorías de fricción" en el skill.
+- **Evolución + aprendizajes**: antes de modificar un skill, leer `APRENDIZAJES.md`
+  para detectar si el gap ya fue observado y documentado — la "Repetición de error"
+  es una categoría de fricción fuerte.
+- **Aprender + perfil**: los aprendizajes tipo **D** (mejora de metodología) pueden
+  reforzar entradas del perfil si tocan preferencias de colaboración, pero la
+  escritura al perfil sigue siendo responsabilidad exclusiva del agente
+  `perfilador-usuario-swl` para centralizar privacidad (`Skill("privacy-memoria")`).
+
+**Regla**: nunca escribas a dos canales desde el mismo comando. Si `/swl:evolucionar`
+detecta que el usuario corrige al agente por una preferencia personal (no un bug
+del agente), registra la señal para el perfilador y **no** incorpores la preferencia
+al agente mismo — el agente debe leer el perfil, no duplicarlo.
+
+## Cuándo usar este comando
+
+- Después de completar múltiples proyectos y detectar patrones de fallo recurrentes
+- Cuando el verificador reporta consistentemente los mismos tipos de errores
+- Cuando un agente genera outputs que regularmente requieren corrección manual
+- Cuando un skill tiene reglas que los desarrolladores ignoran o causan confusión
+- Periódicamente (recomendado: al inicio de cada sprint o ciclo de desarrollo)
+
+## Flags soportados
+
+```
+--agente=[nombre]     Evolucionar solo el agente especificado
+--skill=[nombre]      Evolucionar solo el skill especificado
+--dry-run             Mostrar propuestas sin aplicar cambios
+```
+
+## Paso 0 — Parseo de flags y carga de habilidades
+
+Lee los flags del comando. Determina el alcance:
+- Sin flags: evolución completa del sistema
+- `--agente=[nombre]`: solo el agente indicado
+- `--skill=[nombre]`: solo el skill indicado
+- `--dry-run`: análisis completo sin modificar archivos
+
+Carga obligatoria:
+```
+Skill("auto-evolucion-protocolo")
+```
+
+El skill define el ciclo completo (Observación > Diagnóstico > Propuesta > Revisión > Aplicación > Verificación > Registro), el formato de propuesta, governance, safety checks y formato de commit evolutivo.
+
+Reporta:
+```
+Modo: [completo | agente específico | skill específico]
+Dry-run: [sí | no]
+Alcance: [descripción]
+```
+
+## Paso 1 — Recopilación de evidencia
+
+Busca y lee:
+1. **RESUMEN.md y VERIFICACION.md recientes** — extrae iteraciones, errores rechazados, correcciones manuales
+2. **Historial de commits del sistema** (últimos 90 días en agentes/ habilidades/ comandos/ reglas/) — frecuencia de modificación indica inestabilidad
+3. **APRENDIZAJES.md de proyectos** — clasifica aprendizajes TIPO B (anti-patrones generales) y TIPO D (mejoras de metodología)
+4. **Inventario actual** — lista agentes, skills, comandos, reglas. Si hay flag de alcance, lee solo el artefacto indicado
+
+## Paso 2 — Análisis de patrones de fallo
+
+Con la evidencia, identifica patrones en 5 categorías:
+
+| Categoría | Busca |
+|-----------|-------|
+| E1 — Reglas ignoradas | Agentes que no cargan skills obligatorios, errores recurrentes del verificador |
+| E2 — Skills desactualizados | Reglas que se overridean consistentemente, APIs que cambiaron |
+| E3 — Outputs inconsistentes | Mismo agente produce formatos distintos, instrucciones ambiguas |
+| E4 — Gaps de cobertura | Problemas sin skill, flujos sin agente, comandos faltantes |
+| E5 — Fricción innecesaria | Pasos que siempre se saltan, confirmaciones que siempre se aprueban |
+
+## Paso 3 — Métricas de calidad
+
+Para cada agente/skill en el alcance, calcula basándose en la evidencia:
+- Iteraciones promedio para completar tarea
+- Tasa de rechazo del verificador y tipos más frecuentes
+- Frecuencia de modificación (últimos 90d)
+- Score de estabilidad/relevancia (Alto | Medio | Bajo)
+
+## Paso 4 — Generación de propuestas
+
+Sigue el formato de propuesta definido en `Skill("auto-evolucion-protocolo")` (PROPUESTA-EVOLUCION-NNN). Para cada patrón identificado, genera una propuesta con: tipo, objetivo, evidencia (2-3 ejemplos concretos), problema, cambio propuesto, impacto esperado, prioridad y esfuerzo.
+
+Ordena por prioridad alta + menor esfuerzo primero.
+
+## Paso 5 — Presentación y confirmación
+
+Si `--dry-run`: presenta todas las propuestas y termina.
+
+Si NO es dry-run: presenta propuestas numeradas y pide confirmación:
+```
+Identifiqué [N] propuestas de mejora para el sistema SWL:
+[lista numerada con título, tipo y prioridad]
+
+¿Deseas aplicar todas? Escribe: "aplicar todo", "aplicar [números]", o "cancelar [números]"
+```
+
+Espera respuesta. No apliques cambios sin confirmación explícita.
+
+## Paso 6 — Aplicación de cambios aprobados
+
+Aplica siguiendo las reglas de governance y safety checks del skill:
+- **Agentes**: usa Edit (no reescribir completo), verifica YAML válido, NUNCA eliminar instrucciones sin evidencia de daño
+- **Skills**: aplica en sección correspondiente, incrementa versión si existe campo version
+- **Nuevas entidades**: usa como template la entidad existente más similar
+
+Respeta la governance: PARCHE auto-aplicable, MENOR requiere revisión, MAYOR requiere aprobación humana. Modificar agentes siempre requiere aprobación humana.
+
+**OBLIGATORIO — Marcar como evolucionado ejecutando este comando Bash**:
+
+```bash
+node -e "
+const { markAsEvolved } = require('./hooks/lib/evolution-tracker');
+const pkg = require('./package.json');
+const r = markAsEvolved('[RUTA_ARCHIVO_MODIFICADO]', {
+  from: pkg.version,
+  by: 'evolucionar',
+  note: '[descripción breve del cambio]'
+});
+console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
+"
+```
+
+Reemplazar los placeholders entre corchetes con los valores reales.
+Si el comando Bash no está disponible, agregar manualmente en el frontmatter:
+
+```yaml
+evolved: true
+evolved-from: "[versión actual del sistema, ej: 5.1.3]"
+evolved-at: "[fecha YYYY-MM-DD]"
+evolved-by: "evolucionar"
+evolved-note: "[descripción breve del cambio]"
+```
+
+Para archivos sin frontmatter (reglas), el comando Bash crea automáticamente un archivo sidecar `.evolved.json`.
+
+**SIN ESTE MARCADO, LOS CAMBIOS DE EVOLUCIÓN SE PERDERÁN EN LA PRÓXIMA ACTUALIZACIÓN.**
+
+## Paso 6.5 — Gate de regresión con evals (OBLIGATORIO si hay evals)
+
+Antes de dar por aplicado cualquier cambio, ejecutar el gate de regresión para
+garantizar que la evolución no degradó el skill/agente:
+
+### 6.5.1 — Verificar si existe archivo de evals
+
+```bash
+node scripts/run-skill-evals.js <nombre> --list 2>/dev/null | grep "<nombre>"
+```
+
+Si NO hay evals: saltar este paso y registrar en CHANGELOG:
+`"evolución sin gate de regresión — evals no disponibles para <nombre>"`.
+Sugerir al usuario crear evals siguiendo `plantillas/skill-evals-template.json`.
+
+Si SÍ hay evals: ejecutar el gate completo (6.5.2 a 6.5.5).
+
+### 6.5.2 — Registrar baseline (ANTES de aplicar el cambio)
+
+Cargar el skill/agente ORIGINAL (antes del patch) y ejecutar cada eval contra
+el modelo con el contenido actual cargado. Contar aciertos.
+
+```
+score_baseline = (evals_pass / evals_total) * 100 × factor_peso
+```
+
+Registrar:
+
+```bash
+node scripts/run-skill-evals.js <nombre> --record-baseline --score=<N>
+```
+
+### 6.5.3 — Aplicar el cambio (lo que ya hacía el Paso 6)
+
+### 6.5.4 — Re-ejecutar evals contra la versión nueva
+
+Cargar el skill/agente MODIFICADO y ejecutar cada eval del mismo archivo.
+
+```
+score_after = (evals_pass / evals_total) * 100 × factor_peso
+```
+
+### 6.5.5 — Decisión
+
+| Condición | Acción |
+|---|---|
+| `score_after >= score_baseline` | **Aceptar** — `node scripts/run-skill-evals.js <nombre> --record-after --score=<N>` |
+| `score_after < score_baseline - 5` | **Revertir** — restaurar el archivo anterior + `--record-revert --score=<N>` |
+| `score_baseline - 5 <= score_after < score_baseline` | **Requiere revisión humana** — reportar diferencia; usuario decide si acepta la regresión menor o revierte |
+
+Los 3 casos registran evento en `.planning/evolucion/evoluciones.jsonl` para el
+dashboard `/swl:evolucion-estado`.
+
+### Regla de oro
+
+Un skill no se evoluciona si no se puede medir. Si vas a modificar un skill
+sin evals, primero crea los evals (mínimo 3: uno primary-flow, uno edge-case,
+uno anti-pattern). Sin baseline, cualquier cambio es una apuesta.
+
+## Paso 7 — Versionado y commit
+
+Incrementa versión del sistema según magnitud:
+- Solo reglas/docs de skills: PATCH
+- Nuevas reglas, anti-patrones, flujos: MINOR
+- Nuevos agentes, comandos, refactorización de flujo: MAJOR
+
+Commit con formato evolutivo del skill:
+```
+evolve(swl): [descripción concisa]
+```
+
+## Paso 8 — CHANGELOG y reporte final
+
+Actualiza CHANGELOG.md con: propósito de la evolución, agentes/skills modificados, métricas antes, impacto esperado.
+
+```
+=== Evolución del sistema SWL completada ===
+
+Propuestas analizadas: [N] | Aplicadas: [N] | Diferidas: [N]
+Agentes modificados: [N] | Skills modificados: [N]
+Versión: [anterior] → [nueva]
+
+Próxima evolución recomendada: después de [N] proyectos o [fecha]
+```
+
+## Reglas de comportamiento
+
+- NUNCA apliques cambios sin evidencia concreta. "Parece que sería mejor" no es evidencia.
+- NUNCA elimines instrucciones de agentes basándote solo en que parecen redundantes.
+- En `--dry-run`, el reporte debe ser completo y accionable.
+- Si la evidencia contradice una regla, documenta la contradicción en CHANGELOG antes de cambiar.
+- Prioriza cambios con mayor impacto en iteraciones reducidas.
+- Si no hay evidencia suficiente, reporta exactamente eso y sugiere qué ejecutar para generarla.

package/comandos/swl/exportar-vault.md

@@ -0,0 +1,189 @@
+---
+name: swl:exportar-vault
+description: Exporta un resumen compacto de la sesión actual del proyecto al vault SWL personal de Saul (F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\). Úsalo después de /swl:compactar o al cerrar una sesión productiva cuando quieras que el contenido llegue al segundo cerebro sin esperar a una sincronización manual.
+allowed_tools: ["Read", "Write", "Bash", "Glob"]
+---
+
+# /swl:exportar-vault — Puente SWL-SES → Vault personal
+
+Eres el puente entre el proyecto activo (sigaf, sigm, swl-ses, ecosistema-multi-agente-ia u otro) y el **vault personal de Saul** ubicado en `F:\Google Drive\Developer\Obsidian\Vault\SWL`. Tu trabajo: producir una nota de Inbox del vault con el resumen de la sesión actual, lista para que Saul la procese cuando abra el vault.
+
+Este comando es **complementario a `/swl:compactar`**, no lo reemplaza. Compactar actualiza `.planning/COMPACTACION.md` del proyecto; exportar-vault propaga lo relevante al vault.
+
+## Señales de que debes usarlo
+
+- Acabas de cerrar `/swl:compactar` con decisiones o aprendizajes importantes.
+- Vas a terminar la sesión del día y quieres que los puntos clave queden en el segundo cerebro.
+- Saul lo pide explícitamente.
+- La sesión produjo una decisión arquitectural que afecta a otros proyectos del ecosistema.
+
+## Paso 0 — Validación del destino
+
+Verifica que el vault existe y es accesible:
+
+```bash
+test -d "F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox" \
+  && echo "[OK] Vault accesible" \
+  || echo "[ERROR] Vault no accesible — abortar"
+```
+
+Si la ruta no es accesible (por ejemplo, Google Drive no sincronizado o letra de unidad distinta), **abortar con mensaje claro**. No intentes rutas alternativas sin permiso explícito.
+
+## Paso 1 — Identificación del proyecto actual
+
+Detecta qué proyecto eres leyendo:
+
+1. `CLAUDE.md` raíz — primer encabezado H1.
+2. `package.json` campo `name` si existe.
+3. Si ninguno aclara, usar el nombre de la carpeta raíz del proyecto.
+
+Normaliza el slug del proyecto a kebab-case sin acentos. Ejemplos válidos:
+
+- `sigaf`
+- `sigm`
+- `swl-software-engineering-system`
+- `ecosistema-multi-agente-ia`
+
+## Paso 2 — Recolección del contenido de la sesión
+
+Junta estas fuentes (las que existan):
+
+1. **Última compactación:** `.planning/COMPACTACION.md` o `.planning/COMPACT.md`.
+2. **Estado actual:** `.planning/ESTADO.md` o `.planning/STATE.md`.
+3. **Últimos aprendizajes del APRENDIZAJES.md** — solo las entradas con fecha del día en curso o las últimas 10.
+4. **Git log del día:** `git log --oneline --since="00:00" --until="23:59"`.
+5. **Git status actual:** `git status --short`.
+
+## Paso 3 — Síntesis
+
+Produce un resumen de **no más de 500 palabras** con esta estructura:
+
+```markdown
+---
+type: export-swl
+status: pending-review
+tags: [export, inbox, swl-{proyecto-slug}]
+created: {fecha-hoy YYYY-MM-DD}
+source: swl-ses
+project: "{nombre-proyecto}"
+project_path: "{ruta-absoluta}"
+related_vault_project: "[[DEV - {nombre-en-vault}]]"
+reviewed: false
+---
+
+# Export SWL-SES → Vault ({fecha-hoy}) — {nombre-proyecto}
+
+## Sesión
+
+- **Fecha:** YYYY-MM-DD
+- **Horario:** HH:MM a HH:MM
+- **Rama git:** {rama}
+- **Último commit:** {sha7} — {mensaje}
+
+## Logros de la sesión
+
+- Punto 1
+- Punto 2
+- Punto 3
+
+## Decisiones tomadas
+
+- **{título decisión}** — razón en 1 línea.
+- ...
+
+## Aprendizajes nuevos (candidatos a 04-Resources del vault)
+
+- **{aprendizaje}** — fuente: `{archivo}` o sesión.
+
+## Métricas que cambiaron
+
+| Métrica | Antes | Después |
+|---------|-------|---------|
+| LOC | | |
+| Endpoints | | |
+| Tests | | |
+
+## Bloqueantes o deuda detectada
+
+-
+
+## Acción sugerida al leer en el vault
+
+Ejecutar `/sync-projects {proyecto-slug}` en el vault para integrar los cambios formalmente.
+
+---
+
+**Archivos fuente consultados:**
+- `.planning/COMPACTACION.md` (última)
+- `.planning/APRENDIZAJES.md` (últimas entradas)
+- Git log del día
+
+**Notas:**
+- Este archivo vive en 00-Inbox/ del vault. Saul lo procesa manualmente o con `/sync-projects`.
+- No sobreescribe nada en `02-Projects/`, `04-Resources/` ni `07-Decisions/` del vault.
+```
+
+## Paso 4 — Escritura en el vault
+
+Escribe el archivo en:
+
+```
+F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\YYYY-MM-DD_HHMM_export-{proyecto-slug}.md
+```
+
+Usar UTF-8 sin BOM. En PowerShell:
+
+```powershell
+$encoding = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText($path, $content, $encoding)
+```
+
+En Node.js hook o script:
+
+```javascript
+fs.writeFileSync(path, content, { encoding: 'utf8' });
+```
+
+## Paso 5 — Confirmación
+
+Reporta al usuario:
+
+- Ruta exacta del archivo creado.
+- Conteo de palabras.
+- Recordatorio: "Al abrir el vault en tu próxima sesión, ejecuta `/sync-projects {proyecto-slug}` para integrar formalmente estos cambios."
+
+## Restricciones
+
+- **No sobrescribir** archivos existentes con el mismo nombre. Si por azar existe uno con el mismo timestamp (raro), agrega sufijo `_b`.
+- **No escribir** en otras carpetas del vault. Solo `00-Inbox/`.
+- **No tocar** `.planning/` del proyecto.
+- **Abortar silenciosamente** si el vault no existe, reportando al usuario. No asumir rutas alternativas.
+
+## Anti-patrones
+
+- Exportar 5000 palabras cuando la sesión fue pequeña. El resumen debe ser denso.
+- Duplicar con el `COMPACTACION.md` del proyecto (copiar pega tal cual). El export es una **síntesis para vault**, no un espejo.
+- Intentar escribir directamente en `02-Projects/` del vault. Eso es zona ⚠️ en el vault — solo Saul decide si promoverlo.
+- Usar rutas con backslash no escapadas en código generado.
+
+## Relación con otros comandos SWL
+
+- `/swl:compactar` → actualiza `.planning/` del proyecto. Luego `/swl:exportar-vault` propaga al vault. Secuencia natural.
+- `/swl:aprender` → captura aprendizajes en el proyecto. Luego `/swl:exportar-vault` los envía al vault como candidatos.
+- `/swl:checkpoint` → guarda estado del proyecto. No requiere export al vault (es recuperación interna).
+
+## Ejemplo de invocación
+
+```
+/swl:compactar
+/swl:exportar-vault
+```
+
+Produce:
+
+```
+[OK] Export creado: F:\Google Drive\Developer\Obsidian\Vault\SWL\00-Inbox\2026-04-16_2130_export-sigaf.md (487 palabras)
+
+Próximo paso: al abrir el vault, ejecuta:
+  /sync-projects sigaf
+```

package/comandos/swl/gateway.md

@@ -0,0 +1,158 @@
+---
+name: swl:gateway
+description: Gestiona el gateway multi-plataforma de SWL. Configura adaptadores (Telegram, Discord, Webhook), verifica estado de conexión, envía mensajes de prueba y muestra logs de actividad. Usa manifiestos/gateway-config.json para configuración.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+user-invocable: true
+version: "1.0.0"
+---
+
+# /swl:gateway — Gestión del gateway multi-plataforma
+
+Eres el gestor del gateway SWL. El gateway conecta el sistema con plataformas de mensajería externas para notificaciones bidireccionales.
+
+## Subcomandos
+
+| Subcomando | Descripción |
+|-----------|-------------|
+| `status` | Muestra estado de configuración y conexión de cada adaptador |
+| `config` | Abre y guía la edición de `manifiestos/gateway-config.json` |
+| `test <plataforma>` | Envía mensaje de prueba al adaptador especificado |
+| `start` | Inicia el gateway daemon |
+| `stop` | Detiene el gateway daemon |
+| `logs [N]` | Muestra últimos N mensajes procesados |
+| `relay-on <plataforma> <userId>` | Habilita recepción de comandos (relay bidireccional) y agrega usuario autorizado |
+| `relay-off <plataforma>` | Deshabilita recepción de comandos de esa plataforma |
+| `relay-status` | Muestra estado del relay y audit trail reciente |
+
+## Paso 0 — Leer configuración
+
+```bash
+cat manifiestos/gateway-config.json
+```
+
+Mostrar estado de cada adaptador:
+```
+=== Gateway SWL ===
+Habilitado: [sí/no]
+
+Adaptadores:
+  Telegram: [habilitado/deshabilitado] — Token: [configurado/falta]
+  Discord:  [habilitado/deshabilitado] — Token: [configurado/falta]
+  Webhook:  [habilitado/deshabilitado] — URL: [configurada/falta]
+
+Notificaciones:
+  onSessionComplete: [sí/no]
+  onCheckpoint: [sí/no]
+  onError: [sí/no]
+```
+
+## Subcomando: status
+
+Lee `manifiestos/gateway-config.json` y muestra el estado formateado arriba.
+
+## Subcomando: config
+
+Guía interactiva para configurar el gateway:
+
+1. ¿Habilitar gateway? (sí/no)
+2. ¿Qué plataformas? (telegram/discord/webhook)
+3. Para Telegram: pide el token del bot (via BotFather)
+4. Para Telegram: pide IDs de usuarios permitidos (opcional)
+5. Para Discord: pide token del bot y guild/channel IDs
+6. Para Webhook: pide URL y secret
+7. Escribe la configuración en `manifiestos/gateway-config.json`
+
+**NUNCA hardcodear tokens en el archivo** — usar referencias a variables de entorno: `${TELEGRAM_BOT_TOKEN}`.
+
+## Subcomando: test <plataforma>
+
+```bash
+node -e "
+const { GatewayRunner } = require('./gateway/index');
+const gw = new GatewayRunner(process.cwd());
+// enviar mensaje de prueba
+"
+```
+
+Envía un mensaje de prueba al adaptador indicado y reporta si se recibió.
+
+## Subcomando: start
+
+```bash
+node gateway/index.js &
+```
+
+Inicia el gateway como proceso en background. Reporta PID.
+
+## Subcomando: logs
+
+Lee `.planning/comms/` y muestra los últimos N mensajes procesados con timestamp, tipo, origen y destino.
+
+## Subcomando: relay-on \<plataforma\> \<userId\>
+
+Habilita el modo relay bidireccional para una plataforma y autoriza a un usuario específico a enviar comandos desde ese canal hacia Claude Code.
+
+Proceso:
+1. Cargar `manifiestos/gateway-config.json`.
+2. Setear `relay.enabled = true`.
+3. Setear `relay.platforms.<plataforma>.enabled = true`.
+4. Agregar `<userId>` a `relay.platforms.<plataforma>.allowedUsers` si no está.
+5. Guardar con escritura atómica.
+6. Informar al usuario que los mensajes entrantes se encolarán en `.planning/inbox/` y requieren ejecutar `/swl:inbox` para procesarlos.
+
+**Importante**: antes de habilitar el relay, asegurar que el adaptador ya está funcionando (enabled + token válido). El relay no reemplaza al adaptador — lo extiende para recibir comandos.
+
+## Subcomando: relay-off \<plataforma\>
+
+Deshabilita el relay para esa plataforma (no desactiva el adaptador, solo la recepción de comandos). Los usuarios autorizados se preservan para re-habilitación rápida.
+
+## Subcomando: relay-status
+
+Muestra:
+- Estado global del relay (enabled / disabled)
+- Por plataforma: enabled, número de allowedUsers
+- Rate limit configurado
+- Últimas 10 entradas del audit trail (`.planning/inbox/audit.jsonl`)
+- Cantidad de comandos pendientes en `.planning/inbox/`
+
+```bash
+# Audit trail reciente
+tail -10 .planning/inbox/audit.jsonl 2>/dev/null
+
+# Pendientes
+ls .planning/inbox/cmd-*.json 2>/dev/null | wc -l
+```
+
+## Modo relay: arquitectura bidireccional
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Telegram   │────▶│   Gateway    │────▶│  .planning/  │
+│     Bot      │     │  (adapter +  │     │    inbox/    │
+└──────────────┘     │  CommandRelay)│     └──────┬───────┘
+                     └──────────────┘             │
+                            ▲                     ▼
+                            │              ┌─────────────┐
+                            └──────────────│ /swl:inbox  │
+                            (respuesta)    │ (consumer)  │
+                                           └─────────────┘
+```
+
+Validaciones del CommandRelay (todas obligatorias):
+- Usuario en allowedUsers de esa plataforma
+- Texto ≤ 4000 chars
+- Sin patrones de payload injection (`<script>`, `.env`, `id_rsa`, etc.)
+- Rate limit: 10 msg/min por usuario
+- Dedup por hash en ventana de 30s
+
+Todo evento (aceptado, rechazado, procesado) queda en `.planning/inbox/audit.jsonl`.
+
+Para inyección directa a sesión tmux (solo Linux/macOS), ver `scripts/inbox-tmux-inject.js`.
+
+## Reglas de comportamiento
+
+- NUNCA almacenar tokens directamente en gateway-config.json — siempre usar `${VAR_ENV}`
+- SIEMPRE verificar que el token existe como variable de entorno antes de habilitar un adaptador
+- Si falta `node-telegram-bot-api` o `discord.js`, sugerir instalación con npm
+- Para `relay-on`, confirmar con el usuario antes de agregar un userId a `allowedUsers`: esto autoriza a ese usuario a enviarte comandos remotos
+- El relay NUNCA ejecuta comandos automáticamente: siempre requiere `/swl:inbox` con juicio humano. Explicar esto al usuario si activa el relay por primera vez