@saulwade/swl-ses 2.6.0 → 2.8.0

package/habilidades/instalar-sistema/SKILL.md

@@ -1,227 +1,227 @@
----
-name: instalar-sistema
-description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
-user-invocable: false
-version: "1.0.3"
-herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
-exclusiones:
-  - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
-  - "No cargar para actualizar un skill o agente individual; editar el SKILL.md o agente directamente en `habilidades/` o `agentes/`."
-  - "No cargar para diagnosticar integridad del sistema instalado; usar `/swl:status salud`."
-  - "No cargar para añadir skills de `_userland/` al core; usar `/swl:contribuir`."
-evolvable: true  # default para skill estandar
----
-# Skill: instalar-sistema
-
-Gestiona la instalación, actualización y verificación del sistema SWL (swl-ses) dentro de un proyecto mediante Claude Code.
-
-## Cuándo se activa
-
-Este skill se activa proactivamente cuando:
-
-- El usuario dice "instala SWL", "quiero usar el sistema SWL", "configura SWL en este proyecto"
-- El usuario menciona perfiles: "necesito el perfil backend-python", "instala perfil completo"
-- Se detecta que el proyecto no tiene componentes SWL instalados (no hay `.claude/.swl-install-state.json`)
-- El usuario pide actualizar SWL: "actualiza SWL", "quiero la última versión"
-
-NO se activa cuando:
-- SWL ya está instalado y el usuario no pidió cambios
-- El usuario está trabajando normalmente con los agentes/skills ya instalados
-
-## Cuándo NO cargar
-
-- SWL está instalado y `npx swl-ses doctor` pasa sin errores; reinstalar no resuelve problemas de uso.
-- El usuario quiere modificar un skill o agente específico; editar los archivos en `habilidades/` o `agentes/` directamente.
-- Se quiere diagnosticar por qué algo del sistema no funciona; usar `/swl:status salud` que ejecuta validaciones sin reinstalar.
-- Se quiere incorporar skills de `_userland/` al core del sistema; ese flujo es `/swl:contribuir`, no una reinstalación.
-
-## Paquete npm
-
-```
-@saulwade/swl-ses          (canónico, npmjs.org — recomendado)
-@saul-wade/swl-ses         (mirror, GitHub Packages — requiere token)
-```
-
-Registry canónico: `https://registry.npmjs.org/` (sin auth para instalar)
-Mirror: `https://npm.pkg.github.com` (auth con token de GitHub en `~/.npmrc`)
-Requiere: Node.js >= 22
-
-## Comandos CLI disponibles
-
-| Comando | Función |
-|---------|---------|
-| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` y `_userland/` |
-| `npx @saulwade/swl-ses@latest install --target claude --profile <perfil>` | Instala componentes |
-| `npx @saulwade/swl-ses@latest doctor` | Verifica instalación |
-| `npx @saulwade/swl-ses@latest update` | Actualiza componentes |
-| `npx @saulwade/swl-ses@latest uninstall --target claude` | Desinstala componentes |
-
-## Perfiles
-
-| Perfil | Descripción | Componentes |
-|--------|-------------|-------------|
-| `core` | Mínimo viable | 13 agentes, 20 skills, 9 comandos, 5 reglas, 3 hooks |
-| `backend-python` | Python fullstack | Core + 7 skills Python + 3 skills API + 3 skills datos |
-| `backend-node` | Node.js fullstack | Core + 2 skills Node + 3 skills API |
-| `frontend-react` | React frontend | Core + 2 skills React + 5 skills estilos + 3 skills UX |
-| `frontend-angular` | Angular frontend | Core + 2 skills Angular + 5 skills estilos + 3 skills UX |
-| `fullstack-python-angular` | Python + Angular | Backend Python + Frontend Angular |
-| `fullstack-node-react` | Node + React | Backend Node + Frontend React |
-| `mobile` | Mobile dev | Core + 2 skills mobile + frontend agentes |
-| `devops` | Infraestructura | Core + 6 skills infra + 3 skills seguridad |
-| `completo` | Todo SWL | 37 agentes, 60 skills, 14 comandos, 11 reglas, 6 hooks |
-
-## Flujo de instalación
-
-### Instalación nueva (proyecto sin SWL)
-
-```bash
-# 1. Inicializar estructura
-npx @saulwade/swl-ses@latest init
-
-# 2. Instalar componentes (elegir perfil según necesidad)
-npx @saulwade/swl-ses@latest install --target claude --profile <perfil>
-
-# 3. Verificar
-npx @saulwade/swl-ses@latest doctor
-```
-
-### Actualización (SWL ya instalado)
-
-```bash
-# Re-instala con el mismo perfil, sobrescribiendo archivos
-npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --force
-```
-
-### Cambio de perfil
-
-```bash
-# Instalar con nuevo perfil (sobrescribe)
-npx @saulwade/swl-ses@latest install --target claude --profile <nuevo-perfil> --force
-```
-
-### Instalación global (todos los proyectos)
-
-```bash
-npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --global
-```
-
-## Detección automática de stack tecnológico
-
-El instalador detecta automáticamente los lenguajes presentes en el proyecto y filtra las reglas de lenguaje irrelevantes **antes** de copiarlas a `.claude/rules/`. Esto es crítico porque Claude Code auto-carga todos los `.md` de `.claude/rules/` en cada conversación.
-
-**Lenguajes detectados automáticamente:**
-
-| Lenguaje | Indicadores |
-|----------|-------------|
-| `java` | `pom.xml`, `build.gradle`, `build.gradle.kts`, archivos `.java` |
-| `go` | `go.mod`, archivos `.go` |
-| `rust` | `Cargo.toml`, archivos `.rs` |
-| `csharp` | Archivos `.csproj`, `.sln`, `.cs` |
-| `kotlin` | Archivos `.kt`, `.kts` |
-| `swift` | `Package.swift`, directorio `Sources/`, archivos `.swift` |
-| `php` | `composer.json`, `artisan`, archivos `.php` |
-| `nextjs` | `next.config.js/ts/mjs/cjs` |
-
-**Comportamiento:**
-- En un proyecto Python/Angular/TypeScript: **0 reglas de lenguaje instaladas** (Python/TS/Angular no tienen `reglas/lenguajes/` propias)
-- En un proyecto Java: solo las 5 reglas de `reglas/lenguajes/java/` se instalan
-- Perfil `completo` en proyecto Python: instala `reglas-core` + `reglas-calidad` únicamente (ahorra ~700 líneas de contexto)
-
-**Omitir la detección (instalar todos los lenguajes):**
-```bash
-npx swl-ses install --target claude --profile completo --all-langs
-```
-
-## Qué instala y dónde
-
-| Componente | Destino | Claude Code lo descubre |
-|------------|---------|------------------------|
-| Agentes (.md) | `.claude/agents/` | Si — disponibles como `subagent_type` |
-| Skills (dirs con SKILL.md) | `.claude/skills/` | Si — aparecen en system reminders, auto-activación |
-| Comandos (.md) | `.claude/commands/swl/` | Si — disponibles como `/swl:*` slash commands |
-| Reglas generales (.md) | `.claude/rules/` | Si — cargadas automáticamente en cada conversación |
-| Reglas de lenguaje (.md) | `.claude/rules/LANG/` | Si — solo para lenguajes detectados en el proyecto |
-| Hooks (.js) | `./hooks/` | Si — registrados automáticamente en `.claude/settings.json` |
-| Plantillas | `.planning/` | N/A — templates para planeación |
-
-## Prerrequisitos para instalación remota
-
-Si el usuario no tiene el registry configurado:
-
-```bash
-# Configurar registry de GitHub Packages (una vez por máquina)
-npm config set @saul-wade:registry https://npm.pkg.github.com
-
-# Configurar token en ~/.npmrc (una vez por máquina)
-# Agregar línea: //npm.pkg.github.com/:_authToken=<GITHUB_CLASSIC_PAT>
-```
-
-El token debe ser un **GitHub Classic PAT** con scopes `read:packages`.
-
-## Detección de instalación existente
-
-Para verificar si SWL está instalado:
-
-```bash
-# Verificar archivo de estado
-cat .claude/.swl-install-state.json 2>/dev/null
-
-# Verificar agentes SWL
-ls .claude/agents/*-swl.md 2>/dev/null | head -5
-
-# Verificar hooks registrados
-cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
-```
-
-## Gotchas / Errores comunes no obvios
-
-- **Todo mecanismo que ENCIENDE escritores debe sembrar el ignore de sus outputs en el mismo acto** [caso real 2026-07-10: `install --solo-hooks` activaba la telemetría (los hooks escriben METRICAS.md, audit*.jsonl, evolution/nudges.jsonl, runs/…) sin aplicar `gitignore-manifest` — 19 archivos runtime aparecieron como cambios pendientes en el editor del usuario en sistema-verificacion-oic]: activar hooks/telemetría/watchers es un contrato de DOS partes — registrar el escritor Y declarar sus outputs como runtime ignorado. Fix: `activar-hooks-proyecto` aplica `actualizarGitignore()` tras registrar (no bloqueante, reporta la ruta). Patrón general: al agregar cualquier writer nuevo al sistema, preguntarse en el mismo commit "¿quién ignora lo que este escribe en el destino?".
-
-- **Todo rename de path runtime necesita shim de migración en el manifest de ignorados** [caso real 2026-07-10: instalaciones pre-ADR-0031 escriben `.planning/evolucion/` (español) — el manifest solo ignoraba `evolution/` (inglés), así que los proyectos con hooks viejos ensuciaban su working tree hasta correr `update`]: al renombrar un directorio runtime, el path viejo sigue VIVO en el campo mientras existan instalaciones sin actualizar; el manifest debe cubrir ambas variantes (con comentario de vigencia) hasta que la base instalada migre. Señal en reportes de campo: un path "que ya no existe en el fuente" apareciendo en capturas del usuario delata instalación vieja — pedir `update`, no buscar el writer en el código actual.
-
-- **Un generador de archivos de instrucciones NUNCA sobrescribe un archivo sin su marcador de procedencia** [caso real 2026-07-08: `install --target opencode` pisó el AGENTS.md canónico del repo madre — 420 líneas de documentación curada reemplazadas por el stub del transformador]: la rama "clásica" de `generarArchivoInstrucciones` escribía a ciegas. Regla: antes de sobrescribir AGENTS.md/GEMINI.md/etc. en el destino, verificar que el archivo existente contenga el marcador `Generado por swl-ses`; sin marcador = contenido del usuario o doc canónica del proyecto → preservar y avisar ("borra el archivo y reinstala si quieres el generado"). El guard vive en `scripts/instalador.js` (rama clásica). Patrón general: todo writer de archivos compartidos necesita prueba de ownership antes de escribir — el mismo principio del merge-no-overwrite (ADR-0040) aplicado a archivos generados.
-
-- **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.
-- **`~/.npmrc` sin el token configurado bloquea la instalación silenciosamente**: `npx @saulwade/swl-ses@latest init` falla con `401 Unauthorized` desde GitHub Packages. Causa: el token de GitHub Packages no está en `~/.npmrc`. Solución: configurar el `_authToken` en `~/.npmrc` y verificar con `npm whoami --registry https://npm.pkg.github.com` antes de la primera instalación.
-- **Cambio de perfil sin `--force` no actualiza componentes existentes**: el usuario cambia de `backend-python` a `fullstack-python-angular` pero los nuevos skills de Angular no se instalan porque los archivos ya existen. Causa: el instalador no sobreescribe por defecto. Solución: usar `--force` explícitamente en cambios de perfil: `install --target claude --profile <nuevo-perfil> --force`.
-- **markitdown no instalado detectado tardíamente**: el agente intenta convertir un `.docx` en sesión y falla porque `markitdown` no está disponible, interrumpiendo el flujo de trabajo. Causa: el prerequisito de Python se documenta en el skill pero no se verifica automáticamente durante la instalación. Solución: ejecutar `markitdown --version` como parte del checklist post-instalación; si no está disponible, instalarlo antes de iniciar trabajo con documentos Office.
-- **Scripts o hooks que leen `swl-install-state.json` solo en el proyecto actual fallan silenciosamente en instalaciones globales**: un hook intenta detectar la versión instalada leyendo `.claude/.swl-install-state.json` relativo al cwd o relativo al directorio del hook; en instalaciones SWL **solo globales** (la mayoría), ese archivo solo existe en `~/.claude/.swl-install-state.json` y el check sale sin resultado — ninguna alerta, ninguna detección, falla invisible. Causa: el instalador crea el state file en la ubicación del target (`~/.claude/` para `--global`, `./.claude/` para `--local`), pero los consumidores suelen buscar en una sola de esas ubicaciones. Solución: cualquier script/hook que dependa del state del instalador debe buscar en **7 ubicaciones** y tomar la del `mtime` más reciente cuando haya varias:
-  ```
-  ~/.claude/.swl-install-state.json          (global Claude, mayoría de usuarios)
-  ./.claude/.swl-install-state.json          (local al proyecto)
-  ./.github/.swl-install-state.json          (Copilot)
-  ./.codex/.swl-install-state.json           (Codex CLI)
-  ./.gemini/.swl-install-state.json          (Gemini CLI)
-  ./.opencode/.swl-install-state.json        (OpenCode)
-  <dirname-del-script>/../../.claude/.swl-install-state.json   (hook instalado en .claude/hooks/)
-  ```
-  Ejemplo canónico: `hooks/check-update.js` versión 5.10.3+ implementa esta búsqueda con prioridad por `mtime` y fallback a `package.json` del repo madre. Nunca asumir una sola ubicación de state — el CLI puede instalarse en combinaciones arbitrarias.
-
-## Después de instalar
-
-### Prerequisito Python: markitdown
-
-SWL instala la regla `markitdown.md` en `.claude/rules/` para que los agentes
-sepan convertir archivos `.docx`, `.xlsx`, `.pptx` e `.ipynb` a Markdown.
-La herramienta en sí requiere instalación manual una vez por máquina:
-
-```bash
-pip install markitdown[pdf,docx,pptx,xlsx]
-```
-
-Verificar que quedó correctamente instalada:
-```bash
-markitdown --version
-```
-
-> Sin este prerequisito los agentes pueden pedir al usuario el contenido en texto plano,
-> pero no podrán convertir archivos Office ni Jupyter automáticamente.
-
-### Comandos disponibles tras la instalación
-
-- `/swl:nuevo-proyecto` — iniciar proyecto desde cero
-- `/swl:mapear-codebase` — analizar código existente
-- `/swl:planear-fase` — planificar una fase de trabajo
-- `/swl:ejecutar-fase` — ejecutar plan con commits atómicos
-- `/swl:status salud` — diagnóstico profundo del sistema
+---
+name: instalar-sistema
+description: "Instala o actualiza el sistema SWL en el proyecto actual. Usar PROACTIVAMENTE cuando: (1) el usuario pide instalar SWL, (2) se detecta que el proyecto no tiene .claude/agents/ ni .claude/skills/ con componentes SWL, (3) el usuario menciona perfiles de instalación o pide agregar agentes/skills al proyecto. NO usar cuando SWL ya está instalado y funcionando correctamente."
+user-invocable: false
+version: "1.0.3"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar si SWL ya está instalado y funcionando (`doctor` pasa sin errores); no reinstalar para resolver problemas de uso del sistema."
+  - "No cargar para actualizar un skill o agente individual; editar el SKILL.md o agente directamente en `habilidades/` o `agentes/`."
+  - "No cargar para diagnosticar integridad del sistema instalado; usar `/swl:status salud`."
+  - "No cargar para añadir skills de `_userland/` al core; usar `/swl:contribuir`."
+evolvable: true  # default para skill estandar
+---
+# Skill: instalar-sistema
+
+Gestiona la instalación, actualización y verificación del sistema SWL (swl-ses) dentro de un proyecto mediante Claude Code.
+
+## Cuándo se activa
+
+Este skill se activa proactivamente cuando:
+
+- El usuario dice "instala SWL", "quiero usar el sistema SWL", "configura SWL en este proyecto"
+- El usuario menciona perfiles: "necesito el perfil backend-python", "instala perfil completo"
+- Se detecta que el proyecto no tiene componentes SWL instalados (no hay `.claude/.swl-install-state.json`)
+- El usuario pide actualizar SWL: "actualiza SWL", "quiero la última versión"
+
+NO se activa cuando:
+- SWL ya está instalado y el usuario no pidió cambios
+- El usuario está trabajando normalmente con los agentes/skills ya instalados
+
+## Cuándo NO cargar
+
+- SWL está instalado y `npx swl-ses doctor` pasa sin errores; reinstalar no resuelve problemas de uso.
+- El usuario quiere modificar un skill o agente específico; editar los archivos en `habilidades/` o `agentes/` directamente.
+- Se quiere diagnosticar por qué algo del sistema no funciona; usar `/swl:status salud` que ejecuta validaciones sin reinstalar.
+- Se quiere incorporar skills de `_userland/` al core del sistema; ese flujo es `/swl:contribuir`, no una reinstalación.
+
+## Paquete npm
+
+```
+@saulwade/swl-ses          (canónico, npmjs.org — recomendado)
+@saul-wade/swl-ses         (mirror, GitHub Packages — requiere token)
+```
+
+Registry canónico: `https://registry.npmjs.org/` (sin auth para instalar)
+Mirror: `https://npm.pkg.github.com` (auth con token de GitHub en `~/.npmrc`)
+Requiere: Node.js >= 22
+
+## Comandos CLI disponibles
+
+| Comando | Función |
+|---------|---------|
+| `npx @saulwade/swl-ses@latest init` | Crea `.planning/` y `_userland/` |
+| `npx @saulwade/swl-ses@latest install --target claude --profile <perfil>` | Instala componentes |
+| `npx @saulwade/swl-ses@latest doctor` | Verifica instalación |
+| `npx @saulwade/swl-ses@latest update` | Actualiza componentes |
+| `npx @saulwade/swl-ses@latest uninstall --target claude` | Desinstala componentes |
+
+## Perfiles
+
+| Perfil | Descripción | Componentes |
+|--------|-------------|-------------|
+| `core` | Mínimo viable | 13 agentes, 20 skills, 9 comandos, 5 reglas, 3 hooks |
+| `backend-python` | Python fullstack | Core + 7 skills Python + 3 skills API + 3 skills datos |
+| `backend-node` | Node.js fullstack | Core + 2 skills Node + 3 skills API |
+| `frontend-react` | React frontend | Core + 2 skills React + 5 skills estilos + 3 skills UX |
+| `frontend-angular` | Angular frontend | Core + 2 skills Angular + 5 skills estilos + 3 skills UX |
+| `fullstack-python-angular` | Python + Angular | Backend Python + Frontend Angular |
+| `fullstack-node-react` | Node + React | Backend Node + Frontend React |
+| `mobile` | Mobile dev | Core + 2 skills mobile + frontend agentes |
+| `devops` | Infraestructura | Core + 6 skills infra + 3 skills seguridad |
+| `completo` | Todo SWL | 37 agentes, 60 skills, 14 comandos, 11 reglas, 6 hooks |
+
+## Flujo de instalación
+
+### Instalación nueva (proyecto sin SWL)
+
+```bash
+# 1. Inicializar estructura
+npx @saulwade/swl-ses@latest init
+
+# 2. Instalar componentes (elegir perfil según necesidad)
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil>
+
+# 3. Verificar
+npx @saulwade/swl-ses@latest doctor
+```
+
+### Actualización (SWL ya instalado)
+
+```bash
+# Re-instala con el mismo perfil, sobrescribiendo archivos
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --force
+```
+
+### Cambio de perfil
+
+```bash
+# Instalar con nuevo perfil (sobrescribe)
+npx @saulwade/swl-ses@latest install --target claude --profile <nuevo-perfil> --force
+```
+
+### Instalación global (todos los proyectos)
+
+```bash
+npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --global
+```
+
+## Detección automática de stack tecnológico
+
+El instalador detecta automáticamente los lenguajes presentes en el proyecto y filtra las reglas de lenguaje irrelevantes **antes** de copiarlas a `.claude/rules/`. Esto es crítico porque Claude Code auto-carga todos los `.md` de `.claude/rules/` en cada conversación.
+
+**Lenguajes detectados automáticamente:**
+
+| Lenguaje | Indicadores |
+|----------|-------------|
+| `java` | `pom.xml`, `build.gradle`, `build.gradle.kts`, archivos `.java` |
+| `go` | `go.mod`, archivos `.go` |
+| `rust` | `Cargo.toml`, archivos `.rs` |
+| `csharp` | Archivos `.csproj`, `.sln`, `.cs` |
+| `kotlin` | Archivos `.kt`, `.kts` |
+| `swift` | `Package.swift`, directorio `Sources/`, archivos `.swift` |
+| `php` | `composer.json`, `artisan`, archivos `.php` |
+| `nextjs` | `next.config.js/ts/mjs/cjs` |
+
+**Comportamiento:**
+- En un proyecto Python/Angular/TypeScript: **0 reglas de lenguaje instaladas** (Python/TS/Angular no tienen `reglas/lenguajes/` propias)
+- En un proyecto Java: solo las 5 reglas de `reglas/lenguajes/java/` se instalan
+- Perfil `completo` en proyecto Python: instala `reglas-core` + `reglas-calidad` únicamente (ahorra ~700 líneas de contexto)
+
+**Omitir la detección (instalar todos los lenguajes):**
+```bash
+npx swl-ses install --target claude --profile completo --all-langs
+```
+
+## Qué instala y dónde
+
+| Componente | Destino | Claude Code lo descubre |
+|------------|---------|------------------------|
+| Agentes (.md) | `.claude/agents/` | Si — disponibles como `subagent_type` |
+| Skills (dirs con SKILL.md) | `.claude/skills/` | Si — aparecen en system reminders, auto-activación |
+| Comandos (.md) | `.claude/commands/swl/` | Si — disponibles como `/swl:*` slash commands |
+| Reglas generales (.md) | `.claude/rules/` | Si — cargadas automáticamente en cada conversación |
+| Reglas de lenguaje (.md) | `.claude/rules/LANG/` | Si — solo para lenguajes detectados en el proyecto |
+| Hooks (.js) | `./hooks/` | Si — registrados automáticamente en `.claude/settings.json` |
+| Plantillas | `.planning/` | N/A — templates para planeación |
+
+## Prerrequisitos para instalación remota
+
+Si el usuario no tiene el registry configurado:
+
+```bash
+# Configurar registry de GitHub Packages (una vez por máquina)
+npm config set @saul-wade:registry https://npm.pkg.github.com
+
+# Configurar token en ~/.npmrc (una vez por máquina)
+# Agregar línea: //npm.pkg.github.com/:_authToken=<GITHUB_CLASSIC_PAT>
+```
+
+El token debe ser un **GitHub Classic PAT** con scopes `read:packages`.
+
+## Detección de instalación existente
+
+Para verificar si SWL está instalado:
+
+```bash
+# Verificar archivo de estado
+cat .claude/.swl-install-state.json 2>/dev/null
+
+# Verificar agentes SWL
+ls .claude/agents/*-swl.md 2>/dev/null | head -5
+
+# Verificar hooks registrados
+cat .claude/settings.json 2>/dev/null | grep -c "hooks/"
+```
+
+## Gotchas / Errores comunes no obvios
+
+- **Todo mecanismo que ENCIENDE escritores debe sembrar el ignore de sus outputs en el mismo acto** [caso real 2026-07-10: `install --solo-hooks` activaba la telemetría (los hooks escriben METRICAS.md, audit*.jsonl, evolution/nudges.jsonl, runs/…) sin aplicar `gitignore-manifest` — 19 archivos runtime aparecieron como cambios pendientes en el editor del usuario en sistema-verificacion-oic]: activar hooks/telemetría/watchers es un contrato de DOS partes — registrar el escritor Y declarar sus outputs como runtime ignorado. Fix: `activar-hooks-proyecto` aplica `actualizarGitignore()` tras registrar (no bloqueante, reporta la ruta). Patrón general: al agregar cualquier writer nuevo al sistema, preguntarse en el mismo commit "¿quién ignora lo que este escribe en el destino?".
+
+- **Todo rename de path runtime necesita shim de migración en el manifest de ignorados** [caso real 2026-07-10: instalaciones pre-ADR-0031 escriben `.planning/evolucion/` (español) — el manifest solo ignoraba `evolution/` (inglés), así que los proyectos con hooks viejos ensuciaban su working tree hasta correr `update`]: al renombrar un directorio runtime, el path viejo sigue VIVO en el campo mientras existan instalaciones sin actualizar; el manifest debe cubrir ambas variantes (con comentario de vigencia) hasta que la base instalada migre. Señal en reportes de campo: un path "que ya no existe en el fuente" apareciendo en capturas del usuario delata instalación vieja — pedir `update`, no buscar el writer en el código actual.
+
+- **Un generador de archivos de instrucciones NUNCA sobrescribe un archivo sin su marcador de procedencia** [caso real 2026-07-08: `install --target opencode` pisó el AGENTS.md canónico del repo madre — 420 líneas de documentación curada reemplazadas por el stub del transformador]: la rama "clásica" de `generarArchivoInstrucciones` escribía a ciegas. Regla: antes de sobrescribir AGENTS.md/GEMINI.md/etc. en el destino, verificar que el archivo existente contenga el marcador `Generado por swl-ses`; sin marcador = contenido del usuario o doc canónica del proyecto → preservar y avisar ("borra el archivo y reinstala si quieres el generado"). El guard vive en `scripts/instalador.js` (rama clásica). Patrón general: todo writer de archivos compartidos necesita prueba de ownership antes de escribir — el mismo principio del merge-no-overwrite (ADR-0040) aplicado a archivos generados.
+
+- **Instalación con perfil `completo` en proyecto Python/TypeScript instala reglas de lenguaje innecesarias**: si no se usa la detección automática de stack, el perfil `completo` instala 5 reglas Java + 5 Go + 5 Rust aunque el proyecto no use esos lenguajes, incrementando el contexto base en ~700 líneas por sesión. Causa: no se activó la detección automática de stack. Solución: dejar que el instalador detecte automáticamente o usar `--all-langs` solo si se trabaja con todos los lenguajes; verificar con `ls .claude/rules/` post-instalación.
+- **`~/.npmrc` sin el token configurado bloquea la instalación silenciosamente**: `npx @saulwade/swl-ses@latest init` falla con `401 Unauthorized` desde GitHub Packages. Causa: el token de GitHub Packages no está en `~/.npmrc`. Solución: configurar el `_authToken` en `~/.npmrc` y verificar con `npm whoami --registry https://npm.pkg.github.com` antes de la primera instalación.
+- **Cambio de perfil sin `--force` no actualiza componentes existentes**: el usuario cambia de `backend-python` a `fullstack-python-angular` pero los nuevos skills de Angular no se instalan porque los archivos ya existen. Causa: el instalador no sobreescribe por defecto. Solución: usar `--force` explícitamente en cambios de perfil: `install --target claude --profile <nuevo-perfil> --force`.
+- **markitdown no instalado detectado tardíamente**: el agente intenta convertir un `.docx` en sesión y falla porque `markitdown` no está disponible, interrumpiendo el flujo de trabajo. Causa: el prerequisito de Python se documenta en el skill pero no se verifica automáticamente durante la instalación. Solución: ejecutar `markitdown --version` como parte del checklist post-instalación; si no está disponible, instalarlo antes de iniciar trabajo con documentos Office.
+- **Scripts o hooks que leen `swl-install-state.json` solo en el proyecto actual fallan silenciosamente en instalaciones globales**: un hook intenta detectar la versión instalada leyendo `.claude/.swl-install-state.json` relativo al cwd o relativo al directorio del hook; en instalaciones SWL **solo globales** (la mayoría), ese archivo solo existe en `~/.claude/.swl-install-state.json` y el check sale sin resultado — ninguna alerta, ninguna detección, falla invisible. Causa: el instalador crea el state file en la ubicación del target (`~/.claude/` para `--global`, `./.claude/` para `--local`), pero los consumidores suelen buscar en una sola de esas ubicaciones. Solución: cualquier script/hook que dependa del state del instalador debe buscar en **7 ubicaciones** y tomar la del `mtime` más reciente cuando haya varias:
+  ```
+  ~/.claude/.swl-install-state.json          (global Claude, mayoría de usuarios)
+  ./.claude/.swl-install-state.json          (local al proyecto)
+  ./.github/.swl-install-state.json          (Copilot)
+  ./.codex/.swl-install-state.json           (Codex CLI)
+  ./.gemini/.swl-install-state.json          (Gemini CLI)
+  ./.opencode/.swl-install-state.json        (OpenCode)
+  <dirname-del-script>/../../.claude/.swl-install-state.json   (hook instalado en .claude/hooks/)
+  ```
+  Ejemplo canónico: `hooks/check-update.js` versión 5.10.3+ implementa esta búsqueda con prioridad por `mtime` y fallback a `package.json` del repo madre. Nunca asumir una sola ubicación de state — el CLI puede instalarse en combinaciones arbitrarias.
+
+## Después de instalar
+
+### Prerequisito Python: markitdown
+
+SWL instala la regla `markitdown.md` en `.claude/rules/` para que los agentes
+sepan convertir archivos `.docx`, `.xlsx`, `.pptx` e `.ipynb` a Markdown.
+La herramienta en sí requiere instalación manual una vez por máquina:
+
+```bash
+pip install markitdown[pdf,docx,pptx,xlsx]
+```
+
+Verificar que quedó correctamente instalada:
+```bash
+markitdown --version
+```
+
+> Sin este prerequisito los agentes pueden pedir al usuario el contenido en texto plano,
+> pero no podrán convertir archivos Office ni Jupyter automáticamente.
+
+### Comandos disponibles tras la instalación
+
+- `/swl:nuevo-proyecto` — iniciar proyecto desde cero
+- `/swl:mapear-codebase` — analizar código existente
+- `/swl:planear-fase` — planificar una fase de trabajo
+- `/swl:ejecutar-fase` — ejecutar plan con commits atómicos
+- `/swl:status salud` — diagnóstico profundo del sistema