feat(infra): auto-commit con 2 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fix(infra): tmux_swap_window_into_console base-index-agnostico
2026-06-17 11:11:35 +02:00 · 2026-06-17 11:10:56 +02:00 · 2026-06-17 10:37:14 +02:00 · 2026-06-17 10:30:27 +02:00 · 2026-06-17 10:30:26 +02:00 · 2026-06-17 09:21:15 +02:00
396 changed files with 41700 additions and 372 deletions
@@ -150,7 +150,7 @@ Cualquier `SELECT ... FROM functions/types/apps/proposals WHERE ...` plano se ha
 **functions** — columnas: `id, name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, created_at, updated_at, props, emits, has_state, framework, variant, notes, documentation, code, content_hash, source_repo, source_license, source_file, params_schema`
 - `params_schema`: JSON con semántica de inputs/outputs. Formato: `{"params":[{"name":"x","desc":"..."}],"output":"..."}`. Buscable via FTS5.
 - Enums: `kind`(function|pipeline|component) `purity`(pure|impure) `lang`(go|py|bash|ps)
- Dominios: core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser
+- Dominios: core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser, obsidian

 **types** — columnas: `id, name, lang, domain, version, algebraic, definition, description, tags, uses_types, file_path, created_at, updated_at, examples, notes, documentation, code, content_hash, source_repo, source_license, source_file`
 - Enums: `algebraic`(product|sum)
@@ -2,7 +2,8 @@
  "permissions": {
    "allow": [
      "Bash(CGO_ENABLED=1 go test *)",
-      "Bash(sqlite3 *)"
+      "Bash(sqlite3 *)",
+      "Read(//home/enmanuel/.claude/**)"
    ]
  },
  "enabledMcpjsonServers": [
@@ -6,7 +6,7 @@
    },
    "jupyter": {
      "command": "bash",
-      "args": ["/home/enmanuel/fn_registry/bash/functions/infra/jupyter_mcp_serve.sh"]
+      "args": ["-c", "exec bash \"$(git rev-parse --show-toplevel)/bash/functions/infra/jupyter_mcp_serve.sh\""]
    }
  }
 }
@@ -0,0 +1,58 @@
+---
+name: ensure_project_gitignore
+kind: function
+lang: bash
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "ensure_project_gitignore(project_dir: string) -> void"
+description: "Garantiza de forma idempotente que el .gitignore de un directorio de project contiene las lineas canonicas que excluyen del repo del project el contenido de sus sub-repos hijos (apps y analyses son repos Gitea independientes) y sus vaults (datos fuera de git). Evita el doble-tracking al hacer push del project."
+tags: [git, gitignore, projects, infra]
+params:
+  - name: project_dir
+    desc: "Ruta al directorio del project (p. ej. projects/aurgi). Debe existir; si no, error a stderr y return 1. El .gitignore se escribe/actualiza en <project_dir>/.gitignore."
+output: "Sin salida en stdout. A stderr informa de la accion realizada: 'created' si creo el .gitignore, 'updated: anadidas N lineas' si anadio lineas faltantes, u 'ok: ya completo' si nada cambiaba. Codigo de salida 0 en exito, 1 si project_dir falta o no existe."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/infra/ensure_project_gitignore.sh"
+---
+
+## Ejemplo
+
+```bash
+source bash/functions/infra/ensure_project_gitignore.sh
+
+# Asegura que projects/aurgi/.gitignore excluye el contenido de sus hijos.
+ensure_project_gitignore projects/aurgi
+# stderr: ensure_project_gitignore: created projects/aurgi/.gitignore
+#   (o: updated: anadidas 2 lineas / ok: ya completo)
+```
+
+Las lineas canonicas que la funcion garantiza son:
+
+```
+apps/*/
+analysis/*/
+vaults/*
+!vaults/.gitkeep
+!vaults/vault.yaml
+```
+
+## Cuando usarla
+
+Llamala justo despues de crear un project nuevo (`mkdir -p projects/<nombre>/{apps,analysis,vaults}`) y antes de inicializar su repo Gitea con `ensure_repo_synced`, para que el repo del project nunca trackee el contenido de sus sub-repos hijos. Tambien al adoptar un project existente que aun no tiene estas exclusiones, o como paso de saneamiento cuando `git status` del project muestra contenido de `apps/`/`analysis/` que deberia estar ignorado.
+
+## Gotchas
+
+- La funcion modifica el filesystem (escribe en `<project_dir>/.gitignore`): es impura. No commitea ni hace push — solo deja el `.gitignore` correcto.
+- La comparacion para no duplicar es linea-exacta (`grep -Fxq`). Una linea equivalente pero con espacios extra, comentario adjunto o glob distinto (p. ej. `apps/*` sin la barra final) NO se considera presente y la canonica se anade igualmente; podrian quedar ambas formas. Mantener el `.gitignore` con las lineas canonicas tal cual evita ruido.
+- Si el `.gitignore` existente no termina en salto de linea, la funcion anade uno antes de apendar para no pegar la primera linea nueva al final de la ultima existente.
+- Solo gestiona las exclusiones de sub-repos hijos y vaults del nivel-project; no toca otras reglas que el `.gitignore` ya contenga ni las reordena.
+- Si una linea canonica ya existia con su forma exacta, no se vuelve a anadir (idempotente): re-ejecutar es seguro.
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# ensure_project_gitignore — Garantiza de forma idempotente que el .gitignore de
+# un directorio de project (projects/<nombre>/) contiene las lineas canonicas que
+# excluyen del repo del project el contenido de sus sub-repos hijos (apps y
+# analyses son repos Gitea independientes) y sus vaults (datos fuera de git).
+#
+# Esto evita que al hacer push del project se trackee por error el contenido de
+# los hijos (doble-tracking). Ver .claude/rules/apps_subrepo.md y
+# .claude/rules/projects.md.
+#
+# Uso:
+#   ensure_project_gitignore <project_dir>
+#
+# Salida:
+#   stdout vacio. A stderr informa de la accion realizada (created / updated / ok).
+
+ensure_project_gitignore() {
+    local project_dir="$1"
+
+    if [[ -z "$project_dir" ]]; then
+        echo "ensure_project_gitignore: se requiere project_dir" >&2
+        return 1
+    fi
+    if [[ ! -d "$project_dir" ]]; then
+        echo "ensure_project_gitignore: directorio '$project_dir' no existe" >&2
+        return 1
+    fi
+
+    local gitignore="$project_dir/.gitignore"
+
+    # Lineas canonicas que deben estar presentes (orden de referencia).
+    local -a canonical=(
+        "apps/*/"
+        "analysis/*/"
+        "vaults/*"
+        "!vaults/.gitkeep"
+        "!vaults/vault.yaml"
+    )
+
+    # Caso 1: el .gitignore no existe — crearlo con el contenido canonico.
+    if [[ ! -f "$gitignore" ]]; then
+        printf '%s\n' "${canonical[@]}" > "$gitignore"
+        echo "ensure_project_gitignore: created $gitignore" >&2
+        return 0
+    fi
+
+    # Caso 2: existe — anadir solo las lineas que falten (comparacion linea-exacta),
+    # preservando el contenido y el orden existentes.
+    # Si el archivo no termina en newline, anadir uno antes de apendar para no
+    # pegar la primera linea nueva al final de la ultima existente.
+    if [[ -s "$gitignore" && -n "$(tail -c 1 "$gitignore")" ]]; then
+        printf '\n' >> "$gitignore"
+    fi
+
+    local line added=0
+    for line in "${canonical[@]}"; do
+        # grep -F -x: match literal de linea completa, sin interpretar metacaracteres.
+        if ! grep -Fxq -- "$line" "$gitignore"; then
+            printf '%s\n' "$line" >> "$gitignore"
+            added=$((added + 1))
+        fi
+    done
+
+    if [[ $added -gt 0 ]]; then
+        echo "ensure_project_gitignore: updated: anadidas $added lineas a $gitignore" >&2
+    else
+        echo "ensure_project_gitignore: ok: ya completo $gitignore" >&2
+    fi
+
+    return 0
+}
+
+# Si se invoca como script (no source), ejecutar la funcion.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    ensure_project_gitignore "$@"
+fi
@@ -0,0 +1,113 @@
+---
+name: launch_fleetclaude
+kind: function
+lang: bash
+domain: infra
+version: "1.3.2"
+purity: impure
+signature: "launch_fleetclaude [--cwd <dir>] [--bin <path>] [--session <name>] [--cols <n>]"
+description: "Entrypoint de FleetView: abre una ventana kitty con una sesion tmux (socket aislado -L fleet) de dos panes (TUI fleetview a la izquierda, claude --dangerously-skip-permissions a la derecha) para centralizar la flota de Claudes. Instala atajos alt+flechas/alt+enter/alt+n que controlan la TUI desde cualquier pane, y fija el ancho del sidebar con hooks."
+tags: [claude-fleet, infra, kitty, tmux, claude, fleetview, launcher]
+params:
+  - name: --cwd
+    desc: "Directorio de trabajo de ambos panes tmux. Opcional. Default: raiz del repo fn_registry, derivada dinamicamente via git rev-parse desde la ubicacion del script (sin hardcodear paths de usuario)."
+  - name: --bin
+    desc: "Ruta al binario de la TUI fleetview que corre en el pane izquierdo. Opcional. Default: <repo>/apps/fleetview/fleetview. Si no es ejecutable, el pane izquierdo muestra un mensaje de como compilarla y deja una shell viva."
+  - name: --session
+    desc: "Nombre de la sesion tmux a crear o reutilizar. Opcional. Default: fleet. La funcion es idempotente sobre este nombre."
+  - name: --cols
+    desc: "Ancho en columnas del pane izquierdo (la TUI). Opcional. Default: 40."
+output: "Crea/reutiliza una sesion tmux detached con dos panes y lanza una ventana kitty 'FleetView' adjunta a ella, desacoplada del shell padre (setsid). Imprime el estado por stdout. Sin valor de retorno; exit 0 en exito."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/infra/launch_fleetclaude.sh"
+---
+
+## Ejemplo
+
+```bash
+# Via fn run (resuelve por nombre o ID):
+fn run launch_fleetclaude
+
+# Directo, con cwd explicito:
+launch_fleetclaude --cwd ~/fn_registry
+
+# Sesion y ancho de pane personalizados:
+launch_fleetclaude --session fleet --cols 50
+```
+
+Tras invocarlo aparece una ventana kitty titulada `FleetView` con dos panes
+lado a lado: a la izquierda la TUI `fleetview`, a la derecha una sesion de
+`claude --dangerously-skip-permissions`. Volver a invocarlo NO duplica la
+sesion: reusa la existente y solo abre otra kitty adjunta.
+
+## Cuando usarla
+
+Usala cuando quieras un unico punto de entrada a la flota de Claudes en vez de
+N ventanas kitty sueltas: lanzas `fleetclaude` y tienes la TUI de control y un
+Claude listo para trabajar en la misma ventana. Tipico al empezar la jornada o
+al retomar el trabajo en el repo `fn_registry`.
+
+## Gotchas
+
+- **Idempotencia tmux**: si la sesion `<session>` (default `fleet`) ya existe,
+  NO se recrea el layout; solo se abre una kitty nueva adjunta a la misma
+  sesion. Para empezar de cero: `tmux kill-session -t fleet` antes de invocar.
+- **kitty detached (setsid)**: la ventana se lanza con `setsid ... &` para
+  sobrevivir al cierre de la terminal que la invoco. No bloquea al shell padre.
+- **`exec` en los panes**: tanto la TUI como `claude` se lanzan con `exec`, asi
+  que al terminar el proceso el pane se cierra en vez de dejar una shell zombie
+  colgando. Excepcion: el fallback cuando `fleetview` no esta compilado deja una
+  shell interactiva a proposito (para que veas el mensaje y puedas compilar).
+- **Requiere fleetview compilado**: el default `--bin` apunta a
+  `<repo>/apps/fleetview/fleetview`. Si ese binario no existe, el pane izquierdo
+  muestra `cd apps/fleetview && go build -o fleetview .` en lugar de fallar en
+  silencio. Compila la TUI antes para el flujo completo.
+- **Socket tmux aislado (`-L fleet`)**: toda la sesion vive en un server tmux
+  propio, separado del tmux por defecto del usuario. Asi los atajos `bind -n`
+  NO afectan otras sesiones (ej. una sesion `mobile-1` del movil) y matar el
+  server fleet no toca nada mas: `tmux -L fleet kill-server`.
+- **Atajos en el socket, NO en kitty.conf**: instala `bind -n` para
+  `alt+flechas` (mover el cursor de la TUI), `alt+enter` (conmutar al Claude
+  seleccionado) y `alt+n` (abrir Claude nuevo). Son bindings de tmux que
+  redirigen la tecla al pane de la TUI (`send-keys -t console.0`), asi funcionan
+  ESTES DONDE ESTES (incluido escribiendo en el pane de Claude). No modifican la
+  configuracion de kitty ni los atajos globales del escritorio.
+- **Ancho del sidebar via hooks**: `client-resized` y `window-layout-changed`
+  re-fijan el pane 0 (TUI) a `--cols` columnas, porque el `attach` de kitty y el
+  conmutar de Claude redistribuyen el espacio.
+- **tmux siempre, kitty solo sin TTY**: `tmux` es obligatorio (aborta != 0 si
+  falta). `kitty` solo se necesita en la ruta sin-TTY (atajo de escritorio, cron,
+  script), donde abre una ventana nueva. Invocado desde una terminal interactiva
+  (el caso normal del alias `fleetclaude`), reutiliza la terminal actual con
+  `exec tmux attach` y NO necesita kitty — util en WSL u hosts sin kitty.
+
+## Capability growth log
+
+- v1.3.2 (2026-06-17) — targeting de panes por **pane ID** (`%0`/`%1`) en vez de
+  por indice (`console.0`). Antes fallaba con `can't find pane: 0` en hosts cuyo
+  `~/.tmux.conf` define `base-index 1`/`pane-base-index 1` (el socket `-L fleet`
+  hereda esa config). Los pane ID son inmunes al base-index. Bug latente que el
+  fix de kitty (v1.3.1) destapo al dejar de abortar antes de montar la sesion.
+- v1.3.1 (2026-06-17) — el guard de `kitty` se movio a la rama sin-TTY. La ruta
+  interactiva (`exec tmux attach`) ya no exige kitty, asi que `fleetclaude`
+  funciona en hosts sin kitty (p.ej. WSL) reutilizando la terminal actual.
+- v1.3.0 (2026-06-17) — renombrada de `launch_kittyclaude` a `launch_fleetclaude`
+  (comando `fleetclaude`). Atajos: `alt+0` (= alt+n, abrir Claude nuevo), `alt+k`
+  (kill con confirmacion), `alt+r` (picker de reanudar sesiones cerradas) y
+  `alt+flecha-izquierda` (volver atras desde el picker). Cierra la window al salir
+  el Claude (`remain-on-exit off`).
+- v1.2.0 (2026-06-16) — ancho del sidebar por defecto 47 columnas; `ctrl+0` como
+  atajo alterno para abrir Claude nuevo; `mouse on` (clic/rueda enrutados a la
+  TUI) y `extended-keys on` (para que `ctrl+0` llegue distinguible por el
+  protocolo de teclado de kitty).
+- v1.1.0 (2026-06-16) — socket tmux aislado `-L fleet`; instala atajos
+  `alt+flechas` / `alt+enter` / `alt+n` que controlan la TUI desde cualquier
+  pane; hooks que mantienen fijo el ancho del sidebar tras attach/conmutar.
@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+# launch_fleetclaude — Entrypoint MVP de FleetView.
+#
+# Abre UNA ventana kitty corriendo una sesion tmux de dos panes:
+#   - pane izquierdo: la TUI 'fleetview' (la flota de Claudes centralizada).
+#   - pane derecho:   'claude --dangerously-skip-permissions'.
+#
+# Objetivo: dejar de tener N ventanas kitty dispersas y centralizar el control
+# de los Claudes en una sola ventana.
+#
+# Funcion IMPURA: lanza procesos (tmux + kitty) con efectos secundarios.
+#   - Crea/reusa una sesion tmux detached llamada <session> (idempotente).
+#   - Lanza una ventana kitty desacoplada del shell padre (setsid) para que
+#     sobreviva al cierre de la terminal que la invoco.
+#   - No toca atajos de teclado ni kitty.conf.
+set -euo pipefail
+IFS=$' \t\n'
+
+launch_fleetclaude() {
+    local cwd=""
+    local bin=""
+    local session="fleet"
+    local cols=52
+    local T="tmux -L fleet"   # socket tmux aislado: no toca el tmux normal del usuario
+
+    # -----------------------------------------------------------------------
+    # Parseo de argumentos
+    # -----------------------------------------------------------------------
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --cwd)
+                shift
+                cwd="${1:-}"
+                ;;
+            --bin)
+                shift
+                bin="${1:-}"
+                ;;
+            --session)
+                shift
+                session="${1:-}"
+                ;;
+            --cols)
+                shift
+                cols="${1:-40}"
+                ;;
+            -h|--help)
+                cat <<'USAGE'
+Uso: launch_fleetclaude [opciones]
+
+Abre una ventana kitty con una sesion tmux de dos panes: la TUI fleetview a la
+izquierda y 'claude --dangerously-skip-permissions' a la derecha.
+
+Opciones:
+  --cwd <dir>       Directorio de trabajo de los panes.
+                    Default: raiz del repo fn_registry (derivada dinamicamente).
+  --bin <path>      Ruta al binario de la TUI fleetview.
+                    Default: <repo>/apps/fleetview/fleetview
+  --session <name>  Nombre de la sesion tmux. Default: fleet.
+  --cols <n>        Ancho (columnas) del pane izquierdo. Default: 40.
+  -h, --help        Muestra esta ayuda.
+
+Ejemplos:
+  launch_fleetclaude
+  launch_fleetclaude --cwd ~/fn_registry
+  launch_fleetclaude --session fleet --cols 50
+USAGE
+                return 0
+                ;;
+            *)
+                echo "launch_fleetclaude: opcion desconocida: '$1' (usa -h)" >&2
+                return 2
+                ;;
+        esac
+        shift
+    done
+
+    # -----------------------------------------------------------------------
+    # Derivar la raiz del repo fn_registry dinamicamente (NO hardcodear paths
+    # de usuario). Estrategia: subir desde la ubicacion del script con
+    # 'git rev-parse --show-toplevel'; fallbacks razonables si no aplica.
+    # -----------------------------------------------------------------------
+    local script_dir repo_root=""
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    # El script vive en <repo>/bash/functions/infra/, asi que la raiz son 3
+    # niveles arriba; pero preferimos git para robustez.
+    repo_root="$(git -C "$script_dir" rev-parse --show-toplevel 2>/dev/null || true)"
+    if [[ -z "$repo_root" ]]; then
+        # Fallback 1: navegacion relativa desde la ubicacion del script.
+        repo_root="$(cd "$script_dir/../../.." 2>/dev/null && pwd || true)"
+    fi
+    if [[ -z "$repo_root" ]]; then
+        # Fallback 2: variable de entorno del registry o el cwd actual.
+        repo_root="${FN_REGISTRY_ROOT:-$PWD}"
+    fi
+
+    # Defaults derivados de la raiz del repo.
+    [[ -z "$cwd" ]] && cwd="$repo_root"
+    [[ -z "$bin" ]] && bin="$repo_root/apps/fleetview/fleetview"
+
+    # Validar cwd: si no existe, caer al repo_root.
+    if [[ ! -d "$cwd" ]]; then
+        echo "launch_fleetclaude: --cwd '$cwd' no existe; usando '$repo_root'." >&2
+        cwd="$repo_root"
+    fi
+
+    # -----------------------------------------------------------------------
+    # Comprobar herramientas necesarias.
+    # -----------------------------------------------------------------------
+    if ! command -v tmux >/dev/null 2>&1; then
+        echo "launch_fleetclaude: tmux no esta instalado." >&2
+        return 1
+    fi
+    # Nota: kitty NO se exige aqui. La ruta interactiva (TTY) reutiliza la
+    # terminal actual con `exec tmux attach` y no necesita kitty. Solo la
+    # ruta sin-TTY (abrir ventana nueva con setsid kitty) lo requiere, y ahi
+    # se comprueba justo antes de usarlo.
+
+    # -----------------------------------------------------------------------
+    # Comando para el pane izquierdo:
+    #   - Si el binario fleetview existe -> ejecutarlo (exec, sin shell colgado).
+    #   - Si NO existe -> mensaje claro + shell interactiva (no falla en silencio).
+    # -----------------------------------------------------------------------
+    local left_cmd
+    if [[ -x "$bin" ]]; then
+        left_cmd="exec $(printf '%q' "$bin")"
+    else
+        # Fallback claro: instruye como compilar la TUI y deja una shell viva.
+        left_cmd="echo 'fleetview no compilado: cd apps/fleetview && go build -o fleetview .'; exec \"\$SHELL\""
+    fi
+
+    # -----------------------------------------------------------------------
+    # Montar la sesion tmux SOLO si no existe (idempotencia). Socket aislado $T.
+    #
+    # Targeting por PANE ID (%0/%1), no por indice (console.0). El socket
+    # -L fleet sigue leyendo ~/.tmux.conf; si el usuario tiene
+    # `base-index 1` / `pane-base-index 1` (muy comun), el primer pane es el
+    # indice 1 y cualquier referencia a console.0 falla con
+    # "can't find pane: 0". Los pane ID son estables e inmunes al base-index.
+    # -----------------------------------------------------------------------
+    local left_pane right_pane
+    if $T has-session -t "$session" 2>/dev/null; then
+        echo "launch_fleetclaude: la sesion tmux '$session' ya existe; reutilizandola."
+    else
+        echo "launch_fleetclaude: creando sesion tmux '$session' en '$cwd'."
+
+        # Sesion detached con ventana 'console'. Capturamos el pane ID del pane
+        # izquierdo (la TUI fleetview, o el fallback claro).
+        left_pane=$($T new-session -d -s "$session" -n console -c "$cwd" -P -F '#{pane_id}')
+        $T send-keys -t "$left_pane" "$left_cmd" C-m
+
+        # pane derecho = claude, dividiendo horizontalmente (split lado a lado).
+        right_pane=$($T split-window -h -t "$left_pane" -c "$cwd" -P -F '#{pane_id}')
+        $T send-keys -t "$right_pane" "exec claude --dangerously-skip-permissions" C-m
+
+        # Fijar el ancho del pane izquierdo en columnas.
+        $T resize-pane -t "$left_pane" -x "$cols"
+
+        # Foco inicial en el pane de claude (derecha).
+        $T select-pane -t "$right_pane"
+    fi
+
+    # Si reutilizamos sesion (o por seguridad), derivar el pane ID de la TUI:
+    # el primer pane de la ventana 'console' (orden por indice) es el izquierdo.
+    if [[ -z "$left_pane" ]]; then
+        left_pane=$($T list-panes -t "$session":console -F '#{pane_id}' 2>/dev/null | head -n1)
+    fi
+
+    # -----------------------------------------------------------------------
+    # Atajos globales (alt+*) en el socket aislado: redirigen la tecla al pane
+    # de la TUI (console.0) ESTES DONDE ESTES, para controlar la flota sin salir
+    # del pane de Claude. La TUI (fleetview) es quien interpreta Up/Down/Enter/n.
+    # `bind -n` = tabla root (sin prefijo). Idempotente: re-set en cada lanzamiento.
+    # -----------------------------------------------------------------------
+    $T bind -n M-Up    send-keys -t "$left_pane" Up
+    $T bind -n M-Down  send-keys -t "$left_pane" Down
+    $T bind -n M-Enter send-keys -t "$left_pane" Enter
+    $T bind -n M-n     send-keys -t "$left_pane" n
+    $T bind -n M-0     send-keys -t "$left_pane" n
+    $T bind -n M-k     send-keys -t "$left_pane" k
+    $T bind -n M-r     send-keys -t "$left_pane" r
+    $T bind -n M-u     send-keys -t "$left_pane" u
+    $T bind -n M-h     send-keys -t "$left_pane" h
+    $T bind -n M-Left  send-keys -t "$left_pane" Escape
+    $T bind -n M-q     send-keys -t "$left_pane" Q
+    # Raton: enruta clicks/rueda al pane bajo el cursor; la TUI los interpreta.
+    $T set -g mouse on
+    # Al salir un Claude (exit / Ctrl-D / kill), cerrar su window en vez de
+    # dejarla muerta ("dead" pane) en la sesion.
+    $T set -g remain-on-exit off
+
+    # Estetica neutra: sin el verde fosforo por defecto de tmux. Status bar gris y
+    # bordes de pane gris tenue, iguales en activo e inactivo (separacion simple,
+    # sin resaltado de enfoque).
+    $T set -g status-style "bg=colour236,fg=colour250"
+    $T set -g pane-border-style "fg=colour238"
+    $T set -g pane-active-border-style "fg=colour240"
+
+    # Mantener el ancho del sidebar (pane 0) cuando kitty redimensiona la ventana
+    # tras el attach, o cuando se conmuta de Claude (window-linked / layout change).
+    $T set-hook -g client-resized        "resize-pane -t $left_pane -x $cols"
+    $T set-hook -g window-layout-changed "resize-pane -t $left_pane -x $cols"
+
+    # -----------------------------------------------------------------------
+    # Lanzar kitty adjuntando la sesion, DESACOPLADA del shell padre con
+    # setsid, para que no muera al cerrar la terminal invocadora.
+    # (Mismo patron que reboot_all_claudes para relanzar terminales.)
+    # -----------------------------------------------------------------------
+    # Adjuntar la sesion:
+    #   - Si se invoca desde una terminal interactiva, convertir ESA terminal en
+    #     el panel FleetView (exec reemplaza el proceso; al hacer detach vuelve la
+    #     shell). Asi `fleetclaude` no abre otra ventana: usa la actual.
+    #   - Si NO hay TTY (atajo de escritorio, cron, script), abrir una ventana
+    #     kitty nueva desacoplada (setsid) como antes.
+    if [ -t 0 ] && [ -t 1 ]; then
+        exec tmux -L fleet attach -t "$session"
+    fi
+    # Ruta sin-TTY: necesitamos kitty para abrir la ventana nueva.
+    if ! command -v kitty >/dev/null 2>&1; then
+        echo "launch_fleetclaude: kitty no esta instalado (necesario solo sin TTY)." >&2
+        echo "launch_fleetclaude: lanzalo desde una terminal interactiva, o instala kitty." >&2
+        return 1
+    fi
+    setsid kitty --title "FleetView" -e tmux -L fleet attach -t "$session" </dev/null >/dev/null 2>&1 &
+    disown 2>/dev/null || true
+
+    echo "launch_fleetclaude: ventana kitty 'FleetView' adjunta a la sesion tmux '$session'."
+    return 0
+}
+
+# Permitir ejecutar el archivo directamente (no solo como funcion sourced).
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    launch_fleetclaude "$@"
+fi
@@ -3,14 +3,15 @@ name: full_git_pull
 kind: pipeline
 lang: bash
 domain: pipelines
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "full_git_pull() -> stdout: tabla resumen"
-description: "Pull automatico de fn_registry + todos los sub-repos locales + submodules + fn sync. Descubre repos locales, stashea dirty trees antes de pullear, hace pull --ff-only, actualiza submodulos del repo principal, pulla ~/.password-store, regenera registry.db con fn index y ejecuta fn sync."
+description: "Pull automatico de fn_registry + todos los sub-repos locales + submodules + fn sync. Descubre repos locales, stashea dirty trees antes de pullear, hace pull --ff-only, actualiza submodulos del repo principal, pulla ~/.password-store, regenera registry.db con fn index, ejecuta fn sync y reclona los sub-repos hijos faltantes de cada project (apps/analysis) via clone_project_subrepos."
 tags: [git, pull, sync, registry, pipeline, pendiente-usar]
 uses_functions:
  - discover_git_repos_bash_infra
  - git_pull_with_stash_bash_infra
+  - clone_project_subrepos_bash_pipelines
  - pass_get_bash_infra
 uses_types: []
 returns: []
@@ -51,4 +52,10 @@ bash bash/functions/pipelines/full_git_pull.sh

 ## Notas

-Solo hace pull fast-forward — nunca rebase ni merge automatico. Los repos con divergencia o conflicto de stash se listan al final del resumen para intervencion manual, pero el pipeline no aborta por ellos. No clona repos faltantes: cada PC tiene el subset que le interesa (clonar manualmente si se necesita uno nuevo). Modo completamente no-interactivo.
+Solo hace pull fast-forward — nunca rebase ni merge automatico. Los repos con divergencia o conflicto de stash se listan al final del resumen para intervencion manual, pero el pipeline no aborta por ellos. Modo completamente no-interactivo.
+
+Desde v1.1.0 SI reclona los sub-repos hijos faltantes de cada project: tras `fn sync` (que trae a `registry.db` las filas de apps/analysis de todos los PCs), itera los projects y llama `clone_project_subrepos` para traer al disco los hijos que falten, re-indexando si clono alguno. `registry.db` actua como manifest de sub-repos, asi que clonar el project paraguas + `/full-git-pull` reconstruye su arbol entero sin adivinar nombres. Los repos sueltos (sin project) siguen sin auto-clonarse: cada PC tiene el subset que le interesa.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-10) — anade el paso 6: reclonado de sub-repos hijos de cada project via `clone_project_subrepos` tras `fn sync`, con re-index si clona alguno. Permite reconstruir el arbol completo de un project en un PC nuevo (issue 0171).
@@ -149,6 +149,42 @@ full_git_pull() {
        fi
    fi

+    # --- Paso 6: Reclonar sub-repos hijos de cada project (issue 0171) ---
+    # Tras fn sync, registry.db contiene las filas apps/analysis de TODOS los PCs.
+    # clone_project_subrepos clona en este disco los hijos que falten (skip si ya
+    # existen). Asi, clonar el project paraguas y correr /full-git-pull reconstruye
+    # su arbol entero sin adivinar nombres de sub-repos: registry.db ES el manifest.
+    echo "" >&2
+    echo "[6/6] Reclonando sub-repos de projects..." >&2
+    local reclone_summary="  [skip] sin projects o registry.db"
+    if [[ -f "$registry_root/registry.db" ]] && command -v sqlite3 >/dev/null 2>&1; then
+        export FN_REGISTRY_ROOT="$registry_root"
+        export GITEA_URL="${GITEA_URL:-$(pass_get agentes/gitea-url | head -n1 2>/dev/null || true)}"
+        local clone_script="$SCRIPT_DIR/clone_project_subrepos.sh"
+        local any_cloned=0
+        if [[ -f "$clone_script" ]]; then
+            while IFS= read -r proj_id; do
+                [[ -z "$proj_id" ]] && continue
+                local clone_out
+                clone_out=$(bash "$clone_script" "$proj_id" 2>&1 || true)
+                if echo "$clone_out" | grep -q '\[cloned\]'; then
+                    any_cloned=1
+                    echo "  $proj_id: nuevos sub-repos clonados" >&2
+                fi
+            done < <(sqlite3 "$registry_root/registry.db" "SELECT id FROM projects;" 2>/dev/null)
+            if [[ "$any_cloned" -eq 1 ]]; then
+                echo "  re-index tras clonado..." >&2
+                [[ -x "$fn_bin" ]] && CGO_ENABLED=1 "$fn_bin" index >/dev/null 2>&1 || true
+                reclone_summary="  OK: nuevos sub-repos clonados + re-index"
+            else
+                reclone_summary="  OK: nada que clonar (todo presente)"
+            fi
+        else
+            reclone_summary="  [skip] clone_project_subrepos.sh no encontrado"
+        fi
+    fi
+    echo "  $reclone_summary" >&2
+
    # --- Resumen ---
    echo ""
    echo "===== RESUMEN full_git_pull ====="
@@ -171,6 +207,9 @@ full_git_pull() {
    echo ""
    echo "fn sync:"
    echo "$sync_summary"
+    echo ""
+    echo "Reclonado sub-repos de projects:"
+    echo "$reclone_summary"

    if [[ ${#diverged[@]} -gt 0 || ${#conflicts[@]} -gt 0 ]]; then
        echo ""
@@ -3,10 +3,10 @@ name: full_git_push
 kind: pipeline
 lang: bash
 domain: pipelines
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "full_git_push(commit_message?: string) -> stdout: tabla resumen"
-description: "Push automatico de fn_registry + todos los sub-repos + fn sync. Descubre repos, escanea secrets (aborta si detecta), auto-inicializa apps/analyses sin .git via ensure_repo_synced, auto-commitea dirty trees, pushea solo repos adelantados, pushea ~/.password-store sin commitear, y ejecuta fn sync."
+description: "Push automatico de fn_registry + todos los sub-repos + fn sync. Descubre repos, escanea secrets (aborta si detecta), auto-inicializa apps/analyses Y projects paraguas sin .git via ensure_repo_synced (asegurando el .gitignore canonico del project antes), auto-commitea dirty trees, pushea solo repos adelantados, pushea ~/.password-store sin commitear, y ejecuta fn sync."
 tags: [git, push, sync, registry, pipeline, pendiente-usar]
 uses_functions:
  - discover_git_repos_bash_infra
@@ -14,6 +14,7 @@ uses_functions:
  - git_auto_commit_dirty_bash_infra
  - git_push_if_ahead_bash_infra
  - ensure_repo_synced_bash_infra
+  - ensure_project_gitignore_bash_infra
  - pass_get_bash_infra
 uses_types: []
 returns: []
@@ -62,3 +63,7 @@ bash bash/functions/pipelines/full_git_push.sh "feat: nueva funcion"
 ## Notas

 El unico motivo para abortar antes de commitear es la deteccion de secrets. Cualquier otro error (push rechazado por non-fast-forward, fn sync no disponible) se reporta en el resumen y el pipeline continua con el resto de repos. Modo completamente no-interactivo.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-10) — auto-inicializa tambien los projects paraguas (`projects/<p>/`) sin repo Gitea, no solo apps/analyses. Antes de pushear cada project asegura su `.gitignore` canonico via `ensure_project_gitignore` para no trackear el contenido de los sub-repos hijos. Cierra el agujero por el que projects como aurgi/obsidian/osint vivian solo en disco y se perdian al borrar el PC (issue 0171).
@@ -13,6 +13,7 @@ source "$INFRA_DIR/git_auto_commit_dirty.sh"
 source "$INFRA_DIR/git_push_if_ahead.sh"
 source "$INFRA_DIR/pass_get.sh"
 source "$INFRA_DIR/ensure_repo_synced.sh"
+source "$INFRA_DIR/ensure_project_gitignore.sh"
 source "$CYBERSEC_DIR/scan_secrets_in_dirty.sh"

 full_git_push() {
@@ -65,6 +66,32 @@ full_git_push() {
                ensure_repo_synced "$d" dataforge "$(basename "$d")" master "chore: initial sync" || \
                    echo "  [warn] fallo inicializando $d" >&2
            done < <(sqlite3 "$registry_root/registry.db" "SELECT dir_path FROM apps WHERE dir_path != '' UNION SELECT dir_path FROM analysis WHERE dir_path != '';" 2>/dev/null)
+
+            # Paso 1c: Auto-inicializar los PROJECTS paraguas sin .git (issue 0171).
+            # El directorio projects/<p>/ versiona SOLO las docs de nivel-project
+            # (project.md, vault.yaml, CONVENTIONS.md, tools/...). Sus hijos apps/* y
+            # analysis/* son sub-repos Gitea independientes, excluidos por el .gitignore
+            # canonico que ensure_project_gitignore garantiza ANTES del push para no
+            # trackear su contenido (doble-tracking). Sin esto, un project sin repo
+            # (aurgi, obsidian, osint) vivia solo en disco y se perdia al borrar el PC.
+            if [[ -f "$registry_root/registry.db" ]] && command -v sqlite3 >/dev/null 2>&1; then
+                while IFS= read -r proj_dir; do
+                    [[ -z "$proj_dir" ]] && continue
+                    local pd="$registry_root/$proj_dir"
+                    [[ -d "$pd" ]] || continue
+                    # Garantizar el .gitignore canonico ANTES de cualquier git add -A.
+                    ensure_project_gitignore "$pd" || \
+                        echo "  [warn] no se pudo asegurar .gitignore de $pd" >&2
+                    if [[ -d "$pd/.git" ]]; then
+                        git -C "$pd" remote get-url origin >/dev/null 2>&1 && continue
+                        echo "  fix-remote: $pd (.git sin origin)" >&2
+                    else
+                        echo "  auto-init project: $pd" >&2
+                    fi
+                    ensure_repo_synced "$pd" dataforge "$(basename "$pd")" master "chore: initial sync project" || \
+                        echo "  [warn] fallo inicializando project $pd" >&2
+                done < <(sqlite3 "$registry_root/registry.db" "SELECT CASE WHEN dir_path != '' THEN dir_path ELSE 'projects/'||id END FROM projects;" 2>/dev/null)
+            fi
        else
            echo "  [warn] registry.db o sqlite3 no disponibles — omitiendo auto-init BD-driven" >&2
        fi
@@ -72,28 +99,13 @@ full_git_push() {
        echo "  [skip] GITEA_URL/GITEA_TOKEN no disponibles — omitiendo auto-init" >&2
    fi

-    # Redescubrir repos tras posibles inicializaciones
+    # Redescubrir repos tras posibles inicializaciones.
+    # El repo de config de Claude (dataforge/repo_Claude, al que apuntan los
+    # symlinks de ~/.claude/) vive en fn_registry/external/repo_Claude, asi que
+    # discover_git_repos ya lo encuentra y pasa por scan-secrets/commit/push
+    # como un repo mas. No necesita tratamiento especial.
    repos=$(discover_git_repos "$registry_root")

-    # --- Paso 1c: Incluir el repo de configuracion de Claude ---
-    # Los archivos de ~/.claude/ (settings.json, commands, skills, CLAUDE.md...)
-    # son symlinks a un repo git externo (dataforge/repo_Claude). Lo resolvemos
-    # de forma portable siguiendo el symlink de settings.json — sin hardcodear
-    # el path, que difiere entre PCs. Si resuelve a un repo git, lo anadimos a
-    # la lista para que pase por scan-secrets + auto-commit + push como los demas.
-    local claude_repo=""
-    if [[ -L "$HOME/.claude/settings.json" ]]; then
-        local _claude_settings_real
-        _claude_settings_real=$(readlink -f "$HOME/.claude/settings.json" 2>/dev/null || true)
-        if [[ -n "$_claude_settings_real" ]]; then
-            claude_repo=$(git -C "$(dirname "$_claude_settings_real")" rev-parse --show-toplevel 2>/dev/null || true)
-        fi
-    fi
-    if [[ -n "$claude_repo" && -d "$claude_repo/.git" ]]; then
-        echo "[1c] Incluyendo repo de config Claude: $claude_repo" >&2
-        repos="$repos"$'\n'"$claude_repo"
-    fi
-
    # --- Paso 2: Escanear secrets ---
    echo "" >&2
    echo "[2/6] Escaneando secrets en dirty trees..." >&2
@@ -0,0 +1,65 @@
+---
+name: close_onlyoffice_instance
+kind: function
+lang: bash
+domain: shell
+version: "1.0.0"
+purity: impure
+signature: "close_onlyoffice_instance(instance: string = demo, [--purge]) -> json"
+description: "Termina el/los proceso(s) DesktopEditors de una INSTANCIA AISLADA (slot) de ONLYOFFICE Desktop Editors, identificados por su HOME=/tmp/oo_<instance> leido de /proc/<pid>/environ — asi NUNCA mata la instancia personal del usuario, solo la aislada. Envia SIGTERM, espera ~3s por evento (read -t, sin sleep foreground) y SIGKILL a los que sigan vivos. Con el flag --purge borra ademas los directorios del slot (/tmp/oo_<instance>*). Imprime JSON con instance, killed_pids (array), purged y status (closed|not_running)."
+tags: [onlyoffice, desktop, x11, shell]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: instance
+    desc: "nombre del slot aislado a cerrar (default: demo). Solo se matan procesos DesktopEditors cuyo HOME sea /tmp/oo_<instance>"
+  - name: --purge
+    desc: "flag opcional: si se pasa, borra los directorios del slot (/tmp/oo_<instance>*) tras matar los procesos. Sin el flag, solo termina procesos y deja el estado del slot en disco"
+output: "una linea JSON a stdout: {\"instance\":\"<i>\",\"killed_pids\":[<pids>],\"purged\":true|false,\"status\":\"closed\"|\"not_running\"}. Exit 0 siempre que opere bien (closed si mato procesos, not_running si no habia ninguno del slot), exit 1 si falta dependencia, exit 2 si flag desconocido"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/shell/close_onlyoffice_instance.sh"
+---
+
+## Ejemplo
+
+```bash
+# Cerrar el slot demo (deja /tmp/oo_demo* en disco para reusar la config)
+bash bash/functions/shell/close_onlyoffice_instance.sh demo
+
+# Cerrar y limpiar todo el estado del slot
+bash bash/functions/shell/close_onlyoffice_instance.sh demo --purge
+
+# Slot por defecto (demo) sin argumentos
+bash bash/functions/shell/close_onlyoffice_instance.sh
+
+# Via fn run
+./fn run close_onlyoffice_instance_bash_shell reporte --purge
+
+# Sourceado
+source bash/functions/shell/close_onlyoffice_instance.sh
+out=$(close_onlyoffice_instance demo --purge)
+echo "$out"
+# {"instance":"demo","killed_pids":[12345,12350],"purged":true,"status":"closed"}
+```
+
+## Cuando usarla
+
+- Cuando terminas un flujo automatizado con ONLYOFFICE Desktop y quieres **cerrar la instancia aislada por completo** (cerrar la ventana con `wmctrl` deja el proceso vivo; esta funcion mata el proceso real).
+- Para **liberar recursos** de un slot que ya no usas, opcionalmente borrando su estado en /tmp con `--purge`.
+- Como ultimo paso del ciclo open -> reload -> close, garantizando que no quedan procesos huerfanos de la instancia aislada.
+
+## Gotchas
+
+- **Solo mata la instancia aislada**: identifica procesos por `HOME=/tmp/oo_<instance>` en `/proc/<pid>/environ`. La instancia personal del usuario (HOME real) NUNCA se toca. Esto es por diseño y por seguridad.
+- **Cerrar la ventana NO mata el proceso**: por eso esta funcion existe. Tras `reload`/`wmctrl -ic` el proceso de la instancia aislada sigue vivo (deseable para reusar). Usa esta funcion para terminarlo de verdad.
+- **`--purge` borra /tmp/oo_<instance>***: pierdes la config del slot (perfil, recientes). El slot se recreara limpio en el siguiente `open`. Sin `--purge`, el estado persiste y el siguiente arranque reusa esa config.
+- **El slot vive en /tmp**: aunque no purgues, `/tmp/oo_<instance>*` se pierde al reiniciar el PC. Estado desechable.
+- **Requiere X11 + wmctrl + xdotool** instalados (coherencia con el grupo, aunque esta funcion solo usa /proc para matar). Comprueba `command -v` y falla claro si falta alguna; no funciona en Wayland puro sin XWayland para el resto del grupo.
+- **Carrera de /proc**: si un pid muere entre listarlo y leer su environ, se ignora silenciosamente (guardas `2>/dev/null || true`); no rompe la funcion (`set -uo pipefail` sin `-e`).
+- **SIGKILL como ultimo recurso**: tras ~3s de SIGTERM, los procesos vivos reciben SIGKILL. Cambios sin guardar en la app (si los hubiera) se pierden — pero el flujo previsto edita en disco, no en la app, asi que no deberia haber estado sin guardar.
@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# close_onlyoffice_instance — termina el/los proceso(s) DesktopEditors de una
+# INSTANCIA AISLADA (slot) de ONLYOFFICE Desktop Editors, identificados por su
+# HOME=/tmp/oo_<instance> en /proc/<pid>/environ. Opcionalmente limpia los
+# directorios del slot con --purge.
+#
+# Funcion impura: lee /proc, envia señales a procesos y (con --purge) borra
+# directorios bajo /tmp. NO toca la instancia personal del usuario: solo mata
+# procesos cuyo HOME apunta al slot aislado.
+#
+# Slot aislado: cada instance usa HOME=/tmp/oo_<instance>,
+# XDG_RUNTIME_DIR=/tmp/oo_<instance>_run, XDG_CONFIG_HOME=/tmp/oo_<instance>/.config.
+
+# Sin -e: lecturas de /proc/<pid>/environ pueden fallar por carrera (el pid
+# muere entre listar y leer); no deben abortar la funcion.
+set -uo pipefail
+
+close_onlyoffice_instance() {
+    local instance="demo"
+    local purge=false
+
+    # Parseo de args: [instance] y/o --purge en cualquier orden.
+    local a
+    for a in "$@"; do
+        case "$a" in
+            --purge) purge=true ;;
+            -*) echo "close_onlyoffice_instance: flag desconocido '$a'" >&2; return 2 ;;
+            *) instance="$a" ;;
+        esac
+    done
+
+    # 1. Dependencias del sistema (consistencia con el grupo, aunque aqui solo
+    #    se usa /proc; onlyoffice/wmctrl/xdotool deben existir para operar el slot).
+    local dep
+    for dep in onlyoffice-desktopeditors wmctrl xdotool; do
+        if ! command -v "$dep" >/dev/null 2>&1; then
+            echo "close_onlyoffice_instance: falta dependencia '$dep'" >&2
+            return 1
+        fi
+    done
+
+    local oo_home="/tmp/oo_${instance}"
+
+    # 2. Encontrar pids de DesktopEditors con HOME=/tmp/oo_<instance>.
+    local pids=() pid environ
+    for pid in $(pgrep -f '/opt/onlyoffice/desktopeditors/DesktopEditors' 2>/dev/null || true); do
+        # Leer el entorno del proceso; saltar si no se puede (carrera/permisos).
+        environ=$(tr '\0' '\n' <"/proc/${pid}/environ" 2>/dev/null || true)
+        [[ -z "$environ" ]] && continue
+        if grep -qx "HOME=${oo_home}" <<<"$environ" 2>/dev/null; then
+            pids+=("$pid")
+        fi
+    done
+
+    # 3. Si no hay procesos del slot: not_running (purge opcional igualmente).
+    if [[ ${#pids[@]} -eq 0 ]]; then
+        local purged=false
+        if [[ "$purge" == true ]]; then
+            rm -rf -- /tmp/oo_"${instance}"* 2>/dev/null || true
+            purged=true
+        fi
+        printf '{"instance":"%s","killed_pids":[],"purged":%s,"status":"not_running"}\n' \
+            "$instance" "$purged"
+        return 0
+    fi
+
+    # 4. SIGTERM a todos los pids del slot.
+    kill -TERM "${pids[@]}" 2>/dev/null || true
+
+    # 5. Esperar ~3s a que mueran (NUNCA sleep foreground): read -t 0.3 x10.
+    local w=0 wmax=10
+    while [[ $w -lt $wmax ]]; do
+        local alive=false p
+        for p in "${pids[@]}"; do
+            if kill -0 "$p" 2>/dev/null; then alive=true; break; fi
+        done
+        [[ "$alive" == false ]] && break
+        read -t 0.3 _ </dev/null 2>/dev/null || true
+        w=$((w + 1))
+    done
+
+    # 6. SIGKILL a los que sigan vivos.
+    local p
+    for p in "${pids[@]}"; do
+        if kill -0 "$p" 2>/dev/null; then
+            kill -KILL "$p" 2>/dev/null || true
+        fi
+    done
+
+    # 7. Purge opcional de los dirs del slot.
+    local purged=false
+    if [[ "$purge" == true ]]; then
+        rm -rf -- /tmp/oo_"${instance}"* 2>/dev/null || true
+        purged=true
+    fi
+
+    # 8. JSON con el array de pids terminados.
+    local pids_json
+    pids_json=$(printf '%s,' "${pids[@]}")
+    pids_json="[${pids_json%,}]"
+    printf '{"instance":"%s","killed_pids":%s,"purged":%s,"status":"closed"}\n' \
+        "$instance" "$pids_json" "$purged"
+    return 0
+}
+
+# Ejecutable directo o sourceado.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    close_onlyoffice_instance "$@"
+fi
@@ -0,0 +1,78 @@
+---
+name: monitor_listening_ports
+kind: function
+lang: bash
+domain: shell
+version: "0.3.0"
+purity: impure
+signature: "monitor_listening_ports([--interval N], [--once]) -> void"
+description: "TUI ligera de terminal que refresca cada N segundos una tabla de los sockets TCP en escucha (LISTEN) del equipo local: IP | PUERTO | PROCESO | PID | TIEMPO ACTIVO | CMD (cmdline real, util para distinguir python3/node genericos), ordenada por tiempo de vida del proceso dueño (descendente). Una fila por pid. Lanzada como root rellena tambien los sockets de otros usuarios. Modo --once imprime un solo frame y sale."
+tags: [recon, ports, monitor, tui]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: --interval N
+    desc: "segundos entre refrescos en modo bucle (default: 1, acepta decimales)"
+  - name: --once
+    desc: "imprime un único frame de la tabla y termina con exit 0 (no interactivo; úsalo en tests y en `fn run` para no colgar)"
+output: "tabla a stdout con columnas IP, PUERTO, PROCESO, PID, TIEMPO ACTIVO ordenada por uptime del proceso descendente; sin --once refresca en bucle infinito hasta Ctrl-C"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/shell/monitor_listening_ports.sh"
+---
+
+## Ejemplo
+
+```bash
+# Un solo frame (no cuelga) — ideal para fn run o un pipe
+./fn run monitor_listening_ports_bash_shell --once
+
+# Como script directo
+bash bash/functions/shell/monitor_listening_ports.sh --once
+
+# Sourceada, en bucle interactivo refrescando cada segundo (Ctrl-C para salir)
+source bash/functions/shell/monitor_listening_ports.sh
+monitor_listening_ports --interval 1
+
+# Refresco mas lento
+monitor_listening_ports --interval 5
+```
+
+Salida (frame `--once`, recortado):
+
+```
+IP                                      PUERTO  PROCESO              PID      TIEMPO ACTIVO
+*                                       8420    registry_api         1885     4d 23:40:46
+::                                      8889    mitmweb              1892     4d 23:40:46
+127.0.0.1                               8484    sqlite_api           1889     4d 23:40:42
+127.0.0.1                               8899    jupyter-lab          155100   4d 19:33:55
+::1                                     631     -                    -        ?
+```
+
+## Cuando usarla
+
+- Cuando quieras vigilar **qué puertos abren tus dev-servers / procesos web locales y desde cuándo** llevan vivos, en una sola pantalla que se actualiza sola.
+- Para detectar de un vistazo un proceso recién levantado (aparece al fondo, con poco TIEMPO ACTIVO) o uno que lleva días escuchando (arriba del todo).
+- Como paso de reconocimiento local del grupo `recon`: inventario rápido de superficie de escucha TCP del propio equipo, con el dueño de cada socket.
+- En tests o automatizaciones que solo necesitan un snapshot: añade `--once` para obtener un frame y salir.
+
+## Gotchas
+
+- **Impura**: depende de `ss` (paquete iproute2) y `ps` (procps). Si falta cualquiera, sale con exit 1 y un mensaje a stderr.
+- **Sin sudo no ves PROCESO/PID/CMD de sockets de otros usuarios** (típicamente procesos de root, ej. systemd-resolved en `127.0.0.54:53`, kernels Jupyter de otra sesión, o servidores en contenedores). Esas filas muestran `-`/`?`. La función **no usa sudo** a propósito; para **rellenarlos, lánzala como root**: `pass show claude/sudo | sudo -S bash bash/functions/shell/monitor_listening_ports.sh --interval 1` (el password se pipea, no queda en la cmdline). Como root, `ss` resuelve el dueño de todos los sockets.
+- **Columna CMD = cmdline real** (`ps -o args=`, recortada a 90 chars). Es lo que distingue un `python3`/`node` genérico (PROCESO) de lo que realmente ejecuta: `python3 -m ipykernel_launcher ...`, `registry_api -port 8420`, etc. Procesos en distinto namespace (docker) pueden seguir sin CMD aunque corras como root.
+- **Una fila por pid**: un mismo puerto con varios workers (ej. nginx, gunicorn) genera varias filas, una por cada pid dueño del socket.
+- **`--once` evita colgar**: sin `--once` corre en bucle infinito. No lo lances así en tests ni en `fn run` desatendido — usa `--once`.
+- **El orden es por uptime del PROCESO, no por el tiempo de la conexión**. `ps -o etimes=` mide cuánto lleva vivo el proceso completo, no cuándo abrió ese socket concreto.
+- **Carrera ps**: si un pid muere entre `ss` y `ps`, su TIEMPO ACTIVO sale como `?` y la fila se ordena al final (no rompe el bucle; el script usa `set -uo pipefail` sin `-e`).
+- En modo bucle oculta el cursor (`tput civis`) y lo restaura + limpia en un `trap` EXIT/INT/TERM, de modo que Ctrl-C deja la terminal limpia.
+
+## Capability growth log
+
+- v0.3.0 (14/06/2026) — añade columna **CMD** con la cmdline real del proceso (mapa pid→args construido en la misma llamada `ps -eo pid=,etimes=,args=`), para distinguir un `python3`/`node` genérico de lo que realmente ejecuta. Documenta cómo rellenar los sockets de otros usuarios (`-`) lanzando la TUI como root. Anchos de columna reajustados para dar sitio a CMD.
+- v0.2.0 (14/06/2026) — corrige parpadeo y cuelgue del modo bucle. (1) Doble-buffer ANSI: cada frame se computa completo en una variable y se pinta con cursor-home `\033[H` + clear-to-end `\033[J` en vez de `tput clear` antes de recolectar, eliminando el instante en blanco. (2) Rendimiento: una sola llamada a `ps -eo pid=,etimes=` (mapa pid→uptime en memoria, antes era un fork de `ps` por pid) y construcción de filas con `printf -v` (builtin, antes un `$( )` por fila); frame de ~130 ms con cientos de sockets. (3) Bugfix de cuelgue: el avance del parser multi-pid usaba `BASH_REMATCH[0]`, que queda sobrescrito por el `[[ =~ ]]` interno de `_mlp_fmt_etime` → no recortaba el string y entraba en bucle infinito. Ahora el needle se captura justo tras el match, con guard anti-cuelgue si el recorte no progresa.
@@ -0,0 +1,271 @@
+#!/usr/bin/env bash
+# monitor_listening_ports — TUI ligera que refresca una tabla de sockets TCP en
+# escucha (LISTEN) del equipo local, ordenada por tiempo de vida del proceso
+# dueño (descendente). Columnas: IP | PUERTO | PROCESO | PID | TIEMPO ACTIVO.
+#
+# Funcion impura: lee estado del sistema (sockets via `ss`, uptime de procesos
+# via `ps`). Sin --once corre en bucle infinito refrescando cada N segundos.
+#
+# Rendimiento: cada frame hace UNA sola llamada a `ss` y UNA sola a `ps`
+# (mapa pid->etimes en memoria). El parseo de cada socket es bash puro y SIN
+# command substitution por fila: las cadenas se construyen con `printf -v`
+# (builtin, cero forks) y el formato de tiempo se devuelve en una variable
+# global. El modo bucle usa doble-buffer ANSI (cursor home + clear-to-end) en
+# lugar de limpiar la pantalla antes de computar, para que nunca se vea vacia
+# entre refrescos.
+
+# No usamos -e a proposito: una carrera donde un pid muere entre `ss` y `ps`
+# no debe matar el bucle entero. -u y pipefail se mantienen para robustez.
+set -uo pipefail
+
+# Formatea segundos a texto humano legible y lo deja en la global _mlp_human.
+# Se evita `$( )` (un fork por fila) usando una variable de retorno.
+#   <1h   -> MM:SS        ej. 12:45
+#   <1d   -> HH:MM:SS     ej. 03:12:45
+#   >=1d  -> Nd HH:MM:SS  ej. 1d 03:12:45
+_mlp_human=""
+_mlp_fmt_etime() {
+    local secs="$1"
+    # Si no es un numero entero valido, devolver tal cual (ej. "?").
+    if ! [[ "$secs" =~ ^[0-9]+$ ]]; then
+        _mlp_human="$secs"
+        return 0
+    fi
+    local days=$(( secs / 86400 ))
+    local rem=$(( secs % 86400 ))
+    local hours=$(( rem / 3600 ))
+    local mins=$(( (rem % 3600) / 60 ))
+    local s=$(( rem % 60 ))
+    if (( days > 0 )); then
+        printf -v _mlp_human '%dd %02d:%02d:%02d' "$days" "$hours" "$mins" "$s"
+    elif (( hours > 0 )); then
+        printf -v _mlp_human '%02d:%02d:%02d' "$hours" "$mins" "$s"
+    else
+        printf -v _mlp_human '%02d:%02d' "$mins" "$s"
+    fi
+}
+
+# Imprime un unico frame de la tabla a stdout.
+# Estrategia de rendimiento (cero forks por fila):
+#   1. Un solo `ps -eo pid=,etimes=` construye un mapa pid -> segundos vivo.
+#   2. Un solo `ss -H -tlnp` lista los sockets en escucha.
+#   3. Cada linea se parsea con bash puro: IP/puerto por parameter expansion,
+#      (nombre,pid) del campo users:(...) iterando con BASH_REMATCH, y cada
+#      fila se arma con `printf -v` (builtin). El uptime se resuelve por lookup
+#      O(1) en el mapa.
+#   4. Se ordena por segundos vivo descendente con un unico `sort`.
+_mlp_render_frame() {
+    # Mapas pid -> etimes (segundos vivo) y pid -> cmdline completa. Una sola
+    # invocacion de ps por frame. `args=` va al ultimo porque lleva espacios,
+    # asi `read` lo captura entero en la tercera variable.
+    local -A etmap=() argmap=()
+    local _pid _et _args
+    while read -r _pid _et _args; do
+        [[ -z "$_pid" ]] && continue
+        etmap["$_pid"]="$_et"
+        argmap["$_pid"]="$_args"
+    done < <(ps -eo pid=,etimes=,args= 2>/dev/null)
+
+    # Cada fila intermedia: "<etimes>\t<ip>\t<puerto>\t<proceso>\t<pid>\t<humano>"
+    local -a rows=()
+    local line row
+    while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+
+        # Campos de `ss -H -tlnp`: State Recv-Q Send-Q Local:Port Peer:Port users:(...)
+        # Local:Port es el 4o token. Lo extraemos sin fork con read en array.
+        local -a F=()
+        read -ra F <<<"$line"
+        local local_addr="${F[3]:-}"
+        [[ -z "$local_addr" ]] && continue
+
+        # Separar IP y PUERTO partiendo por el ULTIMO ':'.
+        local ip port
+        port="${local_addr##*:}"
+        ip="${local_addr%:*}"
+        # Quitar corchetes de IPv6: [::] -> ::  ,  [::1] -> ::1
+        ip="${ip#[}"
+        ip="${ip%]}"
+        # Caso de bind sin direccion explicita (raro): dejar marcador.
+        [[ -z "$ip" ]] && ip="*"
+
+        # Extraer el bloque users:(...) del final de la linea (si existe).
+        local users=""
+        [[ "$line" == *"users:("* ]] && users="${line#*users:(}"
+
+        if [[ -z "$users" ]]; then
+            # Socket sin info de proceso (pertenece a otro usuario y no corremos
+            # como root). Para verlo, lanzar la TUI como root (ver Gotchas).
+            printf -v row '%s\t%s\t%s\t%s\t%s\t%s\t%s' "-1" "$ip" "$port" "-" "-" "?" "-"
+            rows+=("$row")
+            continue
+        fi
+
+        # Dentro de users puede haber varios ("nombre",pid=N,fd=M). Una fila por
+        # pid. Iteramos con BASH_REMATCH avanzando sobre el string (cero forks).
+        local s="$users" pname pid etimes needle prev_s cmd found_any=0
+        while [[ "$s" =~ \"([^\"]*)\",pid=([0-9]+) ]]; do
+            # IMPORTANTE: capturar nombre/pid/needle ANTES de cualquier otra
+            # comparacion `[[ =~ ]]` (p.ej. dentro de _mlp_fmt_etime), porque
+            # cada `=~` SOBREESCRIBE BASH_REMATCH. Si se usara BASH_REMATCH[0]
+            # despues, contendria el match del ultimo `=~` y el recorte de `s`
+            # no avanzaria -> bucle infinito.
+            pname="${BASH_REMATCH[1]}"
+            pid="${BASH_REMATCH[2]}"
+            needle="${BASH_REMATCH[0]}"
+            found_any=1
+
+            # Lookup O(1) en el mapa. Si el pid ya no esta (carrera), marcar "?".
+            etimes="${etmap[$pid]:-}"
+            if [[ -z "$etimes" || ! "$etimes" =~ ^[0-9]+$ ]]; then
+                etimes="-1"
+                _mlp_human="?"
+            else
+                _mlp_fmt_etime "$etimes"
+            fi
+
+            # Comando real (cmdline completa) del pid; dice QUE es realmente un
+            # "python3"/"node" generico. Se recorta para no romper la tabla.
+            cmd="${argmap[$pid]:-}"
+            [[ -z "$cmd" ]] && cmd="-"
+            cmd="${cmd:0:90}"
+
+            printf -v row '%s\t%s\t%s\t%s\t%s\t%s\t%s' "$etimes" "$ip" "$port" "$pname" "$pid" "$_mlp_human" "$cmd"
+            rows+=("$row")
+
+            # Avanzar mas alla del match actual para no repetir el primer pid.
+            # Guard: si el recorte no cambia `s`, cortar para no colgar nunca.
+            prev_s="$s"
+            s="${s#*"$needle"}"
+            [[ "$s" == "$prev_s" ]] && break
+        done
+
+        # Si el formato fue inesperado y no se parseo ningun par, fila placeholder.
+        if (( found_any == 0 )); then
+            printf -v row '%s\t%s\t%s\t%s\t%s\t%s\t%s' "-1" "$ip" "$port" "-" "-" "?" "-"
+            rows+=("$row")
+        fi
+    done < <(ss -H -tlnp 2>/dev/null)
+
+    # Estilo de cabecera (negrita) si la terminal lo soporta.
+    local bold="" reset=""
+    if [[ -t 1 ]] && command -v tput >/dev/null 2>&1; then
+        bold=$(tput bold 2>/dev/null || true)
+        reset=$(tput sgr0 2>/dev/null || true)
+    fi
+
+    # Anchos fijos para alineacion estable (no usamos column -t). La ultima
+    # columna (CMD) es libre: muestra la cmdline real del proceso.
+    local fmt='%-26s %-7s %-16s %-8s %-13s %s\n'
+    # shellcheck disable=SC2059
+    printf "${bold}${fmt}${reset}" "IP" "PUERTO" "PROCESO" "PID" "TIEMPO ACTIVO" "CMD"
+
+    if (( ${#rows[@]} == 0 )); then
+        printf '(sin sockets TCP en escucha)\n'
+        return 0
+    fi
+
+    # Ordenar por la primera columna (etimes) numerica descendente y emitir las
+    # 5 columnas visibles (descartando la columna de orden).
+    printf '%s\n' "${rows[@]}" \
+        | sort -t$'\t' -k1,1nr \
+        | while IFS=$'\t' read -r _etimes ip port pname pid human cmd; do
+            # shellcheck disable=SC2059
+            printf "$fmt" "$ip" "$port" "$pname" "$pid" "$human" "$cmd"
+          done
+}
+
+monitor_listening_ports() {
+    local interval=1
+    local once=0
+
+    # Parseo de flags.
+    while (( $# > 0 )); do
+        case "$1" in
+            --interval)
+                interval="${2:-1}"
+                shift 2
+                ;;
+            --interval=*)
+                interval="${1#*=}"
+                shift
+                ;;
+            --once)
+                once=1
+                shift
+                ;;
+            -h|--help)
+                cat <<'USAGE'
+monitor_listening_ports [--interval N] [--once]
+
+  --interval N   Segundos entre refrescos (default: 1, acepta decimales).
+  --once         Imprime un solo frame de la tabla y termina (exit 0).
+
+Tabla de sockets TCP en escucha (LISTEN) ordenada por tiempo de vida del
+proceso dueño (descendente). Columnas: IP | PUERTO | PROCESO | PID | TIEMPO ACTIVO.
+USAGE
+                return 0
+                ;;
+            *)
+                printf 'monitor_listening_ports: argumento desconocido: %s\n' "$1" >&2
+                return 1
+                ;;
+        esac
+    done
+
+    # Dependencias minimas.
+    if ! command -v ss >/dev/null 2>&1; then
+        printf 'monitor_listening_ports: requiere `ss` (paquete iproute2)\n' >&2
+        return 1
+    fi
+    if ! command -v ps >/dev/null 2>&1; then
+        printf 'monitor_listening_ports: requiere `ps` (paquete procps)\n' >&2
+        return 1
+    fi
+
+    # Modo single-frame: util para tests y para `fn run` sin colgar.
+    if (( once == 1 )); then
+        _mlp_render_frame
+        return 0
+    fi
+
+    # Modo bucle interactivo: oculta cursor y lo restaura + limpia al salir.
+    local have_tput=0
+    command -v tput >/dev/null 2>&1 && have_tput=1
+
+    _mlp_cleanup() {
+        if (( have_tput == 1 )); then
+            tput cnorm 2>/dev/null || true   # restaurar cursor
+            tput sgr0 2>/dev/null || true    # resetear atributos
+        fi
+        printf '\n'
+    }
+    trap '_mlp_cleanup; trap - INT TERM EXIT; return 0 2>/dev/null || exit 0' INT TERM EXIT
+
+    (( have_tput == 1 )) && tput civis 2>/dev/null || true   # ocultar cursor
+
+    # Limpiamos la pantalla UNA sola vez al entrar. A partir de aqui cada frame
+    # se computa COMPLETO en una variable y luego se pinta con doble-buffer:
+    # cursor a home (\033[H), volcado del frame, y clear-to-end (\033[J) para
+    # borrar restos de un frame anterior mas largo. Asi nunca hay un instante
+    # con la pantalla vacia mientras se recolectan los datos.
+    printf '\033[2J'
+
+    local frame
+    while true; do
+        frame=$(
+            printf 'monitor_listening_ports  —  %s  —  intervalo %ss  —  orden: TIEMPO ACTIVO desc  (Ctrl-C para salir)\n\n' \
+                "$(date '+%d/%m/%Y %H:%M:%S')" "$interval"
+            _mlp_render_frame
+        )
+        printf '\033[H'        # cursor al inicio (sin borrar todavia)
+        printf '%s\n' "$frame" # volcar el frame ya calculado de golpe
+        printf '\033[J'        # borrar de aqui al final (restos del frame previo)
+        sleep "$interval" || break
+    done
+}
+
+# Auto-invocacion cuando se ejecuta como script (no al hacer source).
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    monitor_listening_ports "$@"
+fi
@@ -0,0 +1,62 @@
+---
+name: open_onlyoffice_file
+kind: function
+lang: bash
+domain: shell
+version: "1.0.0"
+purity: impure
+signature: "open_onlyoffice_file(file_path: string, instance: string = demo) -> json"
+description: "Abre un archivo en una INSTANCIA AISLADA de ONLYOFFICE Desktop Editors (Linux/X11) sin perturbar la instancia personal del usuario. Cada 'instance' (slot, default demo) usa su propio HOME=/tmp/oo_<instance>, XDG_RUNTIME_DIR y XDG_CONFIG_HOME bajo /tmp, lo que rompe el single-instance lock de ONLYOFFICE y permite una ventana propia en vez de una pestaña en la instancia del usuario. Espera la ventana por evento (xdotool, basename del archivo, timeout ~25s) sin sleep en foreground. Idempotente: si ya hay ventana para ese basename, no relanza y devuelve el wid existente. NO crea archivos: si file_path no existe, falla. Imprime una linea JSON con instance, file (ruta absoluta), wid (hex), pid y status (open|timeout)."
+tags: [onlyoffice, desktop, x11, shell]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: file_path
+    desc: "ruta (relativa o absoluta) al archivo a abrir; DEBE existir, esta funcion no crea archivos. Se normaliza con readlink -f y se busca la ventana por su basename"
+  - name: instance
+    desc: "nombre del slot aislado (default: demo). Determina el env: HOME=/tmp/oo_<instance>, XDG_RUNTIME_DIR=/tmp/oo_<instance>_run, XDG_CONFIG_HOME=/tmp/oo_<instance>/.config. Usa el MISMO instance en reload/close para operar la misma instancia"
+output: "una linea JSON a stdout: {\"instance\":\"<i>\",\"file\":\"<abs>\",\"wid\":\"<hex>|null\",\"pid\":<n>|null,\"status\":\"open\"|\"timeout\"}. Exit 0 si abrio (status open), exit 1 si la ventana no aparecio en el timeout (status timeout) o falta dependencia/archivo, exit 2 si falta el argumento file_path"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/shell/open_onlyoffice_file.sh"
+---
+
+## Ejemplo
+
+```bash
+# Como script directo (slot 'demo' por defecto)
+bash bash/functions/shell/open_onlyoffice_file.sh /tmp/demo_reload.xlsx
+
+# Slot nombrado distinto (ventana propia, no perturba la instancia personal)
+bash bash/functions/shell/open_onlyoffice_file.sh /tmp/informe.docx reporte
+
+# Via fn run
+./fn run open_onlyoffice_file_bash_shell /tmp/demo_reload.xlsx demo
+
+# Sourceado, capturando el wid del JSON
+source bash/functions/shell/open_onlyoffice_file.sh
+out=$(open_onlyoffice_file /tmp/demo_reload.xlsx demo)
+echo "$out"
+# {"instance":"demo","file":"/tmp/demo_reload.xlsx","wid":"0x3c00007","pid":12345,"status":"open"}
+```
+
+## Cuando usarla
+
+- Cuando necesites **abrir un archivo en ONLYOFFICE Desktop desde terminal en su propia ventana aislada**, sin que se agregue como pestaña a la instancia personal del usuario.
+- Como primer paso de un flujo automatizado open -> (editas el archivo en disco) -> `reload_onlyoffice_file` -> `close_onlyoffice_instance`.
+- Cuando quieras un slot reproducible por nombre (`instance`) que reuse la misma instancia aislada entre llamadas (reabrir rapido en vez de arrancar el motor de cero).
+
+## Gotchas
+
+- **ONLYOFFICE Desktop es single-instance por usuario**: sin el slot aislado (HOME/XDG_RUNTIME_DIR propios), un segundo lanzamiento se reenvia a la instancia viva y abre el archivo como PESTAÑA, no ventana nueva. El lock NO se rompe con XDG_CONFIG_HOME solo; SI con HOME + XDG_RUNTIME_DIR propios. Esta funcion ya aplica esa convencion.
+- **NO hay reload nativo de cambios externos** (GitHub Issue #2313 abierto, no implementado). Esta funcion solo abre; para reflejar ediciones hechas en disco hay que cerrar+reabrir con `reload_onlyoffice_file`.
+- **NO crea archivos**: si `file_path` no existe, falla con exit 1. Crea el archivo por tu cuenta antes de llamar.
+- **El slot vive en /tmp**: los dirs `/tmp/oo_<instance>*` se pierden al reiniciar el PC (tmpfs en muchos sistemas). No guardes nada importante ahi; es estado desechable de la instancia aislada.
+- **Requiere X11 + wmctrl + xdotool**: no funciona en Wayland puro sin XWayland (xdotool no encontrara la ventana). La funcion comprueba `command -v` de las 3 deps y falla claro si falta alguna.
+- **El pid reportado es el del launcher** (`onlyoffice-desktopeditors`), que puede reexec/fork al proceso real `DesktopEditors`; sirve como referencia best-effort, no para `kill` fiable (usa `close_onlyoffice_instance`, que localiza el proceso real por su HOME).
+- **Idempotencia por basename**: si ya existe una ventana cuyo titulo contiene el basename del archivo (lo abrio el usuario en su instancia personal, por ejemplo), la funcion la considera "ya abierta" y devuelve ese wid sin relanzar. Usa un basename unico para el slot de pruebas si quieres evitar colisiones.
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# open_onlyoffice_file — abre un archivo en una INSTANCIA AISLADA de ONLYOFFICE
+# Desktop Editors (Linux/X11), sin perturbar la instancia personal del usuario.
+#
+# Funcion impura: lanza un proceso GUI, lee estado de ventanas (xdotool) y
+# escribe directorios en /tmp. Imprime una linea JSON con el resultado.
+#
+# Por que "instancia aislada": ONLYOFFICE Desktop es single-instance por
+# usuario — un segundo `onlyoffice-desktopeditors <file>` se reenvia a la
+# instancia viva y abre el archivo como PESTAÑA en su ventana. El lock
+# single-instance NO se rompe con XDG_CONFIG_HOME, pero SI se rompe lanzando
+# con HOME y XDG_RUNTIME_DIR propios. Por eso cada "slot" nombrado (instance)
+# usa su propio HOME/XDG_RUNTIME_DIR/XDG_CONFIG_HOME bajo /tmp.
+
+# Sin -e: las busquedas de ventana (xdotool search) pueden no matchear y
+# devolver exit !=0; no deben abortar la funcion. -u y pipefail se mantienen.
+set -uo pipefail
+
+open_onlyoffice_file() {
+    local file_path="${1:-}"
+    local instance="${2:-demo}"
+
+    if [[ -z "$file_path" ]]; then
+        echo "open_onlyoffice_file: falta <file_path>" >&2
+        echo "uso: open_onlyoffice_file <file_path> [instance]" >&2
+        return 2
+    fi
+
+    # 1. Dependencias del sistema.
+    local dep
+    for dep in onlyoffice-desktopeditors wmctrl xdotool; do
+        if ! command -v "$dep" >/dev/null 2>&1; then
+            echo "open_onlyoffice_file: falta dependencia '$dep' (instala el paquete correspondiente)" >&2
+            return 1
+        fi
+    done
+
+    # 2. El archivo DEBE existir — esta funcion no crea archivos.
+    if [[ ! -f "$file_path" ]]; then
+        echo "open_onlyoffice_file: el archivo no existe: $file_path (esta funcion no crea archivos)" >&2
+        return 1
+    fi
+
+    # Ruta absoluta y basename para titular/buscar la ventana.
+    local abs_path base
+    abs_path=$(readlink -f -- "$file_path")
+    base=$(basename -- "$abs_path")
+
+    # 3. Slot aislado: HOME/XDG_RUNTIME_DIR/XDG_CONFIG_HOME propios bajo /tmp.
+    local oo_home="/tmp/oo_${instance}"
+    local oo_run="/tmp/oo_${instance}_run"
+    local oo_cfg="${oo_home}/.config"
+    mkdir -p "$oo_home" "$oo_cfg" "$oo_run"
+    chmod 700 "$oo_run" 2>/dev/null || true
+
+    # 4. Idempotencia: si ya hay ventana para ese basename, no relanzar.
+    local existing_wid
+    existing_wid=$(xdotool search --name -- "$base" 2>/dev/null | head -1 || true)
+    if [[ -n "$existing_wid" ]]; then
+        local wid_hex
+        wid_hex=$(printf '0x%x' "$existing_wid" 2>/dev/null || echo "$existing_wid")
+        printf '{"instance":"%s","file":"%s","wid":"%s","pid":null,"status":"open"}\n' \
+            "$instance" "$abs_path" "$wid_hex"
+        return 0
+    fi
+
+    # 5. Lanzar la instancia aislada con su env propio. setsid lo desacopla de
+    #    la terminal; redirige todo a un log del slot.
+    env HOME="$oo_home" XDG_RUNTIME_DIR="$oo_run" XDG_CONFIG_HOME="$oo_cfg" \
+        setsid onlyoffice-desktopeditors "$abs_path" \
+        >"/tmp/oo_${instance}.log" 2>&1 </dev/null &
+    local launch_pid=$!
+
+    # 6. Esperar la ventana por evento (NUNCA sleep en foreground).
+    #    ~25s con read -t 0.3 => ~83 iteraciones.
+    local wid="" i=0 max=83
+    while [[ $i -lt $max ]]; do
+        wid=$(xdotool search --name -- "$base" 2>/dev/null | head -1 || true)
+        [[ -n "$wid" ]] && break
+        read -t 0.3 _ </dev/null 2>/dev/null || true
+        i=$((i + 1))
+    done
+
+    if [[ -z "$wid" ]]; then
+        printf '{"instance":"%s","file":"%s","wid":null,"pid":%s,"status":"timeout"}\n' \
+            "$instance" "$abs_path" "$launch_pid"
+        return 1
+    fi
+
+    local wid_hex
+    wid_hex=$(printf '0x%x' "$wid" 2>/dev/null || echo "$wid")
+    # El pid del proceso real (DesktopEditors) puede diferir del launcher; el
+    # launcher reexec/fork. Reportamos el pid del launcher (best-effort).
+    printf '{"instance":"%s","file":"%s","wid":"%s","pid":%s,"status":"open"}\n' \
+        "$instance" "$abs_path" "$wid_hex" "$launch_pid"
+    return 0
+}
+
+# Ejecutable directo: `bash open_onlyoffice_file.sh <file> [instance]`.
+# Sourceado: define la funcion sin ejecutarla.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    open_onlyoffice_file "$@"
+fi
@@ -0,0 +1,61 @@
+---
+name: reload_onlyoffice_file
+kind: function
+lang: bash
+domain: shell
+version: "1.0.0"
+purity: impure
+signature: "reload_onlyoffice_file(file_path: string, instance: string = demo) -> json"
+description: "Recarga en la ventana de ONLYOFFICE Desktop Editors los datos que el caller edito EN DISCO, cerrando y reabriendo el archivo en la INSTANCIA AISLADA (slot). Es la funcion estrella del grupo: ONLYOFFICE no recarga cambios externos del archivo (GitHub Issue #2313 abierto, no implementado), asi que la unica forma de mostrar datos editados fuera de la app es cerrar la ventana (wmctrl -ic) y reabrir (ONLYOFFICE lee fresco del disco al abrir). Localiza la ventana por basename, la cierra y espera a que desaparezca (timeout ~10s), relanza con el env del slot aislado y espera la ventana nueva (timeout ~25s), todo por evento sin sleep en foreground. Si no habia ventana previa, actua como open. NO edita el archivo: el caller lo edita antes de llamar. Imprime JSON con wid_old, wid_new, reopened, elapsed_s y status (reloaded|timeout)."
+tags: [onlyoffice, desktop, x11, shell]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: file_path
+    desc: "ruta (relativa o absoluta) al archivo cuya ventana se recarga; DEBE existir. El caller ya lo edito en disco antes de llamar. Se busca la ventana por su basename"
+  - name: instance
+    desc: "nombre del slot aislado (default: demo); debe coincidir con el usado en open_onlyoffice_file para reusar la misma instancia. Determina HOME/XDG_RUNTIME_DIR/XDG_CONFIG_HOME bajo /tmp"
+output: "una linea JSON a stdout: {\"instance\":\"<i>\",\"file\":\"<abs>\",\"wid_old\":\"<hex>|null\",\"wid_new\":\"<hex>|null\",\"reopened\":true|false,\"elapsed_s\":<n>,\"status\":\"reloaded\"|\"timeout\"}. Exit 0 si reabrio (status reloaded), exit 1 si la ventana nueva no aparecio en el timeout (status timeout) o falta dependencia/archivo, exit 2 si falta file_path"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "bash/functions/shell/reload_onlyoffice_file.sh"
+---
+
+## Ejemplo
+
+```bash
+# Flujo tipico: editas el .xlsx en disco con tu herramienta y refrescas la vista
+# (este ejemplo asume que /tmp/demo_reload.xlsx ya esta abierto en el slot demo)
+bash bash/functions/shell/reload_onlyoffice_file.sh /tmp/demo_reload.xlsx demo
+
+# Via fn run
+./fn run reload_onlyoffice_file_bash_shell /tmp/demo_reload.xlsx demo
+
+# Sourceado, dentro de un bucle de "editar en disco -> ver en ONLYOFFICE"
+source bash/functions/shell/reload_onlyoffice_file.sh
+# ... el caller modifica /tmp/demo_reload.xlsx por su cuenta ...
+out=$(reload_onlyoffice_file /tmp/demo_reload.xlsx demo)
+echo "$out"
+# {"instance":"demo","file":"/tmp/demo_reload.xlsx","wid_old":"0x3c00007","wid_new":"0x3c0000b","reopened":true,"elapsed_s":4,"status":"reloaded"}
+```
+
+## Cuando usarla
+
+- Cuando **editaste un archivo en disco fuera de ONLYOFFICE** (script, otra herramienta, generador) y necesitas que la ventana de ONLYOFFICE muestre los datos nuevos: esta funcion cierra y reabre para forzar la lectura fresca del disco.
+- En bucles de iteracion rapida "modificar el archivo -> ver el resultado en ONLYOFFICE" sin tocar la instancia personal del usuario.
+- Como reemplazo del reload nativo inexistente (Issue #2313): es la unica via fiable de refrescar la vista desde disco.
+
+## Gotchas
+
+- **No edita el archivo**: solo recarga la ventana desde disco. El caller es responsable de modificar el archivo ANTES de llamar; si no lo modifico, reabrira los mismos datos.
+- **ONLYOFFICE no tiene reload de cambios externos** (GitHub Issue #2313 abierto, no implementado): por eso esta funcion existe y hace cerrar+reabrir. No hay forma "in-place" de refrescar.
+- **`wmctrl -ic` puede disparar el dialogo "Guardar cambios"** si el usuario edito EN la app (no en disco) y hay cambios sin guardar en esa ventana. El flujo previsto es editar SOLO en disco con la ventana sin tocar; si editaste en la app, guarda o descarta antes, o el cierre se quedara esperando interaccion (la funcion saldra por timeout).
+- **Single-instance + slot aislado**: usa el mismo `instance` que en `open_onlyoffice_file`. Con HOME/XDG_RUNTIME_DIR propios el relaunch reenvia a la instancia aislada viva y reabre rapido; con env por defecto se reenviaria a la instancia personal del usuario (no deseado).
+- **El slot vive en /tmp**: `/tmp/oo_<instance>*` se pierde al reiniciar el PC. Estado desechable.
+- **Requiere X11 + wmctrl + xdotool**: no funciona en Wayland puro sin XWayland. Comprueba las 3 deps y falla claro si falta alguna.
+- **Carrera de cierre**: si la ventana tarda mas de ~10s en cerrarse (dialogo modal, app ocupada), la funcion continua igualmente al relaunch; el resultado puede acabar en `timeout` si la ventana nueva no aparece a tiempo.
@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# reload_onlyoffice_file — cierra y reabre un archivo en la INSTANCIA AISLADA de
+# ONLYOFFICE Desktop Editors para que la ventana muestre los datos editados
+# EN DISCO por el caller (ONLYOFFICE no recarga cambios externos: GitHub Issue
+# #2313 abierto, no implementado — la unica forma es cerrar+reabrir).
+#
+# Funcion impura: cierra una ventana GUI (wmctrl), relanza un proceso y espera
+# la ventana nueva por evento. NO edita el archivo — solo recarga la ventana
+# desde el disco. El caller edita el archivo antes de llamar a esta funcion.
+#
+# Instancia aislada (slot): mismo HOME/XDG_RUNTIME_DIR/XDG_CONFIG_HOME que usa
+# open_onlyoffice_file, para que el relaunch reenvie a la instancia aislada
+# viva y reabra rapido en vez de arrancar el motor de cero.
+
+# Sin -e: busquedas de ventana (xdotool/wmctrl) pueden no matchear; no deben
+# abortar la funcion. -u y pipefail se mantienen.
+set -uo pipefail
+
+reload_onlyoffice_file() {
+    local file_path="${1:-}"
+    local instance="${2:-demo}"
+
+    if [[ -z "$file_path" ]]; then
+        echo "reload_onlyoffice_file: falta <file_path>" >&2
+        echo "uso: reload_onlyoffice_file <file_path> [instance]" >&2
+        return 2
+    fi
+
+    # 1. Dependencias del sistema.
+    local dep
+    for dep in onlyoffice-desktopeditors wmctrl xdotool; do
+        if ! command -v "$dep" >/dev/null 2>&1; then
+            echo "reload_onlyoffice_file: falta dependencia '$dep' (instala el paquete correspondiente)" >&2
+            return 1
+        fi
+    done
+
+    # 2. El archivo DEBE existir — no editamos ni creamos archivos.
+    if [[ ! -f "$file_path" ]]; then
+        echo "reload_onlyoffice_file: el archivo no existe: $file_path" >&2
+        return 1
+    fi
+
+    local abs_path base
+    abs_path=$(readlink -f -- "$file_path")
+    base=$(basename -- "$abs_path")
+
+    # 3. Slot aislado (identico a open_onlyoffice_file).
+    local oo_home="/tmp/oo_${instance}"
+    local oo_run="/tmp/oo_${instance}_run"
+    local oo_cfg="${oo_home}/.config"
+    mkdir -p "$oo_home" "$oo_cfg" "$oo_run"
+    chmod 700 "$oo_run" 2>/dev/null || true
+
+    local start_ts
+    start_ts=$(date +%s)
+
+    # 4. Localizar la ventana actual del archivo por basename.
+    local wid_old=""
+    wid_old=$(xdotool search --name -- "$base" 2>/dev/null | head -1 || true)
+
+    local wid_old_hex="null"
+    if [[ -n "$wid_old" ]]; then
+        wid_old_hex=$(printf '0x%x' "$wid_old" 2>/dev/null || echo "$wid_old")
+
+        # 5. Cerrar la ventana (sin teclear en la app) y esperar a que
+        #    desaparezca (~10s con read -t 0.3 => ~33 iteraciones).
+        wmctrl -ic "$wid_old" 2>/dev/null || true
+        local g=0 gmax=33
+        while [[ $g -lt $gmax ]]; do
+            if ! xdotool search --name -- "$base" 2>/dev/null | grep -q .; then
+                break
+            fi
+            read -t 0.3 _ </dev/null 2>/dev/null || true
+            g=$((g + 1))
+        done
+    fi
+
+    # 6. Relanzar con el env del slot aislado. (Si no habia ventana previa,
+    #    esto actua simplemente como open.)
+    env HOME="$oo_home" XDG_RUNTIME_DIR="$oo_run" XDG_CONFIG_HOME="$oo_cfg" \
+        setsid onlyoffice-desktopeditors "$abs_path" \
+        >"/tmp/oo_${instance}.log" 2>&1 </dev/null &
+
+    # 7. Esperar la ventana nueva por evento (~25s => ~83 iteraciones).
+    local wid_new="" i=0 max=83
+    while [[ $i -lt $max ]]; do
+        wid_new=$(xdotool search --name -- "$base" 2>/dev/null | head -1 || true)
+        # Si hubo ventana previa, aceptar cualquier wid que aparezca (el old
+        # ya se cerro; el nuevo puede reutilizar id o no). Si no la hubo,
+        # cualquier wid sirve.
+        [[ -n "$wid_new" ]] && break
+        read -t 0.3 _ </dev/null 2>/dev/null || true
+        i=$((i + 1))
+    done
+
+    local now_ts elapsed
+    now_ts=$(date +%s)
+    elapsed=$((now_ts - start_ts))
+
+    if [[ -z "$wid_new" ]]; then
+        printf '{"instance":"%s","file":"%s","wid_old":"%s","wid_new":null,"reopened":false,"elapsed_s":%s,"status":"timeout"}\n' \
+            "$instance" "$abs_path" "$wid_old_hex" "$elapsed"
+        return 1
+    fi
+
+    local wid_new_hex
+    wid_new_hex=$(printf '0x%x' "$wid_new" 2>/dev/null || echo "$wid_new")
+    printf '{"instance":"%s","file":"%s","wid_old":"%s","wid_new":"%s","reopened":true,"elapsed_s":%s,"status":"reloaded"}\n' \
+        "$instance" "$abs_path" "$wid_old_hex" "$wid_new_hex" "$elapsed"
+    return 0
+}
+
+# Ejecutable directo o sourceado.
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    reload_onlyoffice_file "$@"
+fi
@@ -0,0 +1,90 @@
+---
+name: save_onlyoffice_file
+kind: function
+lang: bash
+domain: shell
+purity: impure
+version: 1.1.0
+description: "Fuerza el guardado (Ctrl+S) de un documento abierto en una instancia de OnlyOffice Desktop en Linux/X11 y confirma que llego a disco por cambio de mtime. Primer paso del flujo seguro guardar -> actualizar -> recargar; evita perder cambios no guardados cuando un build regenera el archivo leyendo del disco."
+signature: "save_onlyoffice_file(file_path: string, [instance: string]) -> json"
+error_type: error_go_core
+tags: [onlyoffice, desktop, x11, gui, save, persist]
+uses_functions: []
+uses_types: []
+file_path: bash/functions/shell/save_onlyoffice_file.sh
+params:
+  - name: file_path
+    desc: "ruta al documento abierto en OnlyOffice cuyo guardado se quiere forzar. Debe existir. Se normaliza a ruta absoluta y se usa su basename para localizar la ventana."
+  - name: instance
+    desc: "nombre del slot/instancia para etiquetar la salida JSON (default: 'demo'). Usar el MISMO valor que en open/reload/close del mismo documento por coherencia."
+output: "linea JSON a stdout: {\"instance\":\"<i>\",\"file\":\"<abs>\",\"wid\":\"<hex>|null\",\"status\":\"saved\"|\"no_change\"|\"no_window\",\"dialog_confirmed\":0|1[,\"mtime_before\":N,\"mtime_after\":N]}. dialog_confirmed=1 si se envio Return para cerrar el dialogo modal de formato. Exit 0 salvo error de dependencia o archivo inexistente (exit 1)."
+---
+
+Fuerza el guardado (Ctrl+S) de un documento abierto en una instancia de ONLYOFFICE
+Desktop Editors en Linux/X11 y confirma que el guardado llegó a disco observando el
+cambio de `mtime` del archivo.
+
+Existe para cerrar una ventana de pérdida de datos: OnlyOffice mantiene los cambios
+en memoria hasta que el usuario guarda. Cualquier proceso que regenere el archivo
+leyendo del disco (un build que refresca hojas, un script de sincronización)
+perdería el trabajo manual no guardado. Esta función vuelca ese trabajo a disco
+ANTES de tocar el archivo, de modo que el paso de actualización pueda preservarlo.
+
+Es el primer paso del flujo seguro de refresco:
+
+```
+save_onlyoffice_file  ->  (actualizar el archivo en disco)  ->  reload_onlyoffice_file
+```
+
+## Ejemplo
+
+```bash
+# Forzar el guardado de un xlsx abierto en la instancia "afiliados"
+bash bash/functions/shell/save_onlyoffice_file.sh \
+  /home/enmanuel/afiliados/programas_afiliados.xlsx afiliados
+# {"instance":"afiliados","file":"/home/enmanuel/afiliados/programas_afiliados.xlsx","wid":"0x0a20002a","status":"saved","mtime_before":1718380000,"mtime_after":1718380042}
+
+# Via fn run (tras fn index)
+./fn run save_onlyoffice_file /home/enmanuel/afiliados/programas_afiliados.xlsx afiliados
+
+# Encadenado con la actualización y la recarga (flujo seguro completo)
+bash bash/functions/shell/save_onlyoffice_file.sh "$XLSX" afiliados
+python build_xlsx.py                      # regenera solo las hojas gestionadas
+./fn run reload_onlyoffice_file "$XLSX" afiliados
+```
+
+## Cuando usarla
+
+Llámala SIEMPRE justo antes de regenerar o modificar en disco un archivo que el
+usuario pueda tener abierto en OnlyOffice, para no pisar sus cambios sin guardar.
+Es el primer eslabón del flujo guardar -> actualizar -> recargar. Si no hay ventana
+abierta para ese archivo, es un no-op seguro (status `no_window`).
+
+## Gotchas
+
+- **Orden crítico**: guarda ANTES de actualizar el archivo. Si actualizas primero y
+  guardas OnlyOffice después, OnlyOffice sobrescribe tu actualización con su copia
+  en memoria (vieja). El flujo correcto es save -> update -> reload.
+- **status `no_change`**: el `mtime` no cambió. Normalmente significa que no había
+  cambios pendientes (no es un error).
+- **Auto-confirmación del diálogo de formato (v1.1.0)**: si tras Ctrl+S el guardado no
+  se completa en ~1.2s, la función asume que OnlyOffice mostró un diálogo modal
+  ("mantener formato") y le envía Return, que acepta la opción por defecto (mantener el
+  formato actual). El campo `dialog_confirmed` indica si se envió. Si no había diálogo,
+  el Return va al editor y solo mueve de celda (no altera datos). Para suprimir el
+  diálogo de forma permanente, desmárcalo en OnlyOffice: Configuración avanzada →
+  desactivar el aviso de formato al guardar.
+- **status `no_window`**: no hay ninguna ventana cuyo título contenga el basename del
+  archivo. No hay nada que guardar; el disco ya es la única fuente de verdad.
+- **Detección por basename**: dos archivos con el mismo nombre en rutas distintas
+  colisionan al localizar la ventana (igual que open/reload).
+- **X11 obligatorio**: depende de `xdotool` (y `stat` de coreutils). No funciona en
+  Wayland puro sin XWayland.
+- **Foco**: la función activa la ventana (`windowactivate --sync`) para que Ctrl+S
+  llegue al editor. Roba el foco un instante; es esperable.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-15) — auto-confirma el diálogo modal "mantener formato" enviando
+  Return a la ventana activa cuando el guardado no se completa en ~1.2s; añade el campo
+  `dialog_confirmed` a la salida JSON.
@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# save_onlyoffice_file — fuerza el guardado (Ctrl+S) de un documento abierto en una
+# instancia de ONLYOFFICE Desktop Editors en Linux/X11 y confirma que el archivo se
+# escribio a disco observando el cambio de mtime.
+#
+# Para que existe: OnlyOffice mantiene los cambios en memoria hasta que el usuario
+# guarda. Cualquier proceso que regenere el .xlsx leyendo del disco (por ejemplo un
+# build que refresca hojas) perderia el trabajo manual no guardado. Esta funcion
+# vuelca ese trabajo a disco ANTES de tocar el archivo, de modo que el paso de
+# actualizacion pueda preservarlo. Es el primer paso del flujo seguro:
+#   save_onlyoffice_file -> (actualizar el archivo) -> reload_onlyoffice_file
+#
+# La ventana se localiza por el basename del archivo (OnlyOffice titula la ventana
+# "<basename> — ONLYOFFICE"), igual que open_onlyoffice_file. Si no hay ventana
+# abierta para ese basename no hay nada que guardar: se devuelve status "no_window"
+# con exit 0 (el disco ya es la unica fuente de verdad).
+#
+# Funcion impura: envia eventos de teclado a X11 (xdotool) y lee el estado del
+# sistema de archivos. Imprime una linea JSON con el resultado a stdout.
+#
+# No usamos `set -e`: los pipelines de busqueda de ventanas (xdotool|head) pueden no
+# matchear y no deben abortar el script. Mantenemos -u y pipefail con guardas.
+set -uo pipefail
+
+save_onlyoffice_file() {
+    local file_path="${1:-}"
+    local instance="${2:-demo}"
+
+    # --- 1. Validacion de dependencias del sistema ---
+    local dep
+    for dep in xdotool stat; do
+        if ! command -v "$dep" >/dev/null 2>&1; then
+            echo "error: dependencia ausente: '$dep' (instala xdotool, coreutils)" >&2
+            return 1
+        fi
+    done
+
+    # --- 2. Validacion de argumentos ---
+    if [ -z "$file_path" ]; then
+        echo "error: uso: save_onlyoffice_file <file_path> [instance]" >&2
+        return 1
+    fi
+    if [ ! -f "$file_path" ]; then
+        echo "error: el archivo no existe: '$file_path'" >&2
+        return 1
+    fi
+    local abs_path
+    abs_path="$(cd "$(dirname "$file_path")" && pwd)/$(basename "$file_path")"
+    local base
+    base="$(basename "$abs_path")"
+
+    # --- 3. Localizar la ventana de OnlyOffice por basename ---
+    local wid=""
+    wid="$(xdotool search --name "$base" 2>/dev/null | head -1 || true)"
+    if [ -z "$wid" ]; then
+        printf '{"instance":"%s","file":"%s","wid":null,"status":"no_window"}\n' \
+            "$instance" "$abs_path"
+        return 0
+    fi
+    local hex
+    hex="$(printf '0x%08x' "$wid" 2>/dev/null || echo "$wid")"
+
+    # --- 4. mtime antes de guardar ---
+    local mtime_before
+    mtime_before="$(stat -c %Y "$abs_path" 2>/dev/null || echo 0)"
+
+    # --- 5. Enfocar la ventana y enviar Ctrl+S ---
+    xdotool windowactivate --sync "$wid" >/dev/null 2>&1 || true
+    xdotool key --clearmodifiers --window "$wid" ctrl+s >/dev/null 2>&1 || true
+
+    # --- 6. Esperar el guardado; auto-confirmar el dialogo de formato si aparece ---
+    # OnlyOffice puede mostrar un dialogo modal ("mantener formato") al guardar. Si el
+    # mtime no cambia en ~1.2s asumimos que hay un modal esperando y le enviamos Return:
+    # acepta la opcion por defecto, que es mantener el formato actual del archivo. Si no
+    # habia dialogo, el Return va al editor y solo mueve de celda (inofensivo: no altera
+    # datos). El intento se repite mientras el guardado no se confirme.
+    local mtime_after="$mtime_before" i=0 confirmed=0
+    local max=27   # ~8s a 0.3s por iteracion
+    until [ "$mtime_after" -gt "$mtime_before" ] || [ "$i" -ge "$max" ]; do
+        read -r -t 0.3 _ </dev/null 2>/dev/null || true
+        mtime_after="$(stat -c %Y "$abs_path" 2>/dev/null || echo "$mtime_before")"
+        i=$((i + 1))
+        # A partir de ~1.2s sin guardar, confirmar el dialogo modal con Return.
+        if [ "$i" -ge 4 ] && [ "$mtime_after" -le "$mtime_before" ]; then
+            local dlg
+            dlg="$(xdotool getactivewindow 2>/dev/null || true)"
+            if [ -n "$dlg" ]; then
+                xdotool key --clearmodifiers --window "$dlg" Return >/dev/null 2>&1 || true
+                confirmed=1
+            fi
+        fi
+    done
+
+    local status="saved"
+    if [ "$mtime_after" -le "$mtime_before" ]; then
+        # Sin cambio de mtime: no habia nada pendiente que guardar.
+        status="no_change"
+    fi
+    printf '{"instance":"%s","file":"%s","wid":"%s","status":"%s","dialog_confirmed":%s,"mtime_before":%s,"mtime_after":%s}\n' \
+        "$instance" "$abs_path" "$hex" "$status" "$confirmed" "$mtime_before" "$mtime_after"
+    return 0
+}
+
+# Ejecutable directo: `bash save_onlyoffice_file.sh <file> [instance]`.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    save_onlyoffice_file "$@"
+fi
@@ -70,6 +70,8 @@ func cmdDoctor(args []string) {
 		doctorDod(r, jsonOut)
 	case "e2e-coverage":
 		doctorE2ECoverage(r, jsonOut)
+	case "projects":
+		doctorProjects(r, jsonOut)
 	default:
 		fmt.Fprintf(os.Stderr, "unknown doctor subcommand: %s\n", sub)
 		doctorUsage()
@@ -100,6 +102,7 @@ Subcommands:
  modules         Drift entre uses_modules (app.md) y fn_module_<x> link calls (CMakeLists.txt) - issue 0097
  dod             Audita bloque dod_evidence_schema en dev/issues/ y dev/flows/ (issue 0114)
  e2e-coverage    Porcentaje de apps con e2e_checks declarado en su app.md (issue 0121b)
+  projects        Cobertura de projects vs sub-repos Gitea (repo propio + hijos clonables) (issue 0171)

 Flags:
  --json              Salida JSON (para scripting/agentes)
@@ -505,6 +508,29 @@ func doctorML(root string, jsonOut bool) {
 	fmt.Printf("\nOverall ML environment: %s\n", overall)
 }

+func doctorProjects(root string, jsonOut bool) {
+	rows, err := infra.AuditProjectsCoverage(root)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+	orphans, oerr := infra.FindOrphanProjectRefs(root)
+	if oerr != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", oerr)
+		os.Exit(1)
+	}
+	if jsonOut {
+		emit(map[string]any{
+			"coverage":        rows,
+			"orphan_project_ids": orphans,
+		})
+		return
+	}
+	fmt.Print(infra.FormatProjectsCoverage(rows))
+	fmt.Println("\n--- Check inverso: project_id huérfanos (apps/analysis sin project declarado) ---")
+	fmt.Print(infra.FormatOrphanProjectRefs(orphans))
+}
+
 func emit(v any) {
 	b, err := json.MarshalIndent(v, "", "  ")
 	if err != nil {
@@ -0,0 +1,199 @@
+---
+id: "0171"
+title: "Manifest de sub-repos por project + re-clonado y auditoría de cobertura en Gitea"
+status: pendiente
+type: enhancement
+domain:
+  - registry-quality
+  - infra
+scope: registry-only
+priority: alta
+depends: []
+blocks: []
+related: ["0166"]
+created: 2026-06-10
+updated: 2026-06-10
+tags: [projects, subrepo, gitea, clone, backup, manifest, fn-doctor]
+---
+
+> **Actualización 10/06/2026 — implementado el núcleo (enfoque KISS).** El manifest
+> `subrepos.yaml` propuesto abajo se **descartó**: `registry.db` (tablas `apps`/`analysis`
+> con `project_id`, propagadas entre PCs por `fn sync`) **ya es** el manifest de sub-repos, y
+> `clone_project_subrepos_bash_pipelines` ya lo consume. No hace falta un archivo nuevo. Lo que
+> faltaba era integración + auditoría. Ver `## Estado de implementación` al final.
+# 0171 — Manifest de sub-repos por project + re-clonado y auditoría de cobertura en Gitea
+
+## APP Metadata
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | 0171 |
+| **Estado** | pendiente |
+| **Prioridad** | alta (riesgo de pérdida de datos) |
+| **Tipo** | enhancement — metadata de projects + `/full-git-pull` + `fn doctor` |
+
+## Contexto
+
+El 10/06/2026, al preparar un dashboard sobre el project `aurgi`, se descubrió que el project
+paraguas **no existía en Gitea** (`dataforge/aurgi` → 404). Sus 3 analyses sí estaban a salvo como
+sub-repos independientes (`dataforge/venta_web`, `dataforge/sale_prices_comprobation`,
+`dataforge/presupuestos_callcenter`), pero **el `project.md`, `vault.yaml` y `CONVENTIONS.md` de
+nivel-project no estaban versionados en ningún sitio**. Reconstruir el project obligó a *adivinar*
+los nombres de los sub-repos hijos uno a uno desde la lista completa de repos de Gitea.
+
+Una auditoría de cobertura `projects ↔ Gitea` confirmó el agujero:
+
+| Project | Repo Gitea | Riesgo |
+|---|---|---|
+| fleet_monitoring, fn_monitoring, message_bus, web_scraping | ✅ | ninguno |
+| **obsidian**, **osint** | ❌ (solo en disco local) | alto — resuelto en esta sesión (subidos a `dataforge/obsidian`, `dataforge/osint`) |
+| **aurgi** | ❌ (404, paraguas inexistente) | pendiente — analyses salvados, docs nivel-project no |
+
+Dos problemas estructurales quedan abiertos:
+
+1. **Projects sin repo Gitea**: su contenido de nivel-project vive solo en disco. Si se borra el
+   disco (o el project no se sincroniza a otro PC), se pierde. La regla `projects.md` dice que cada
+   project debe ser su propio repo Gitea, pero no hay nada que lo **verifique ni lo fuerce**.
+
+2. **Sub-repos hijos no referenciados**: el `.gitignore` de cada project excluye `apps/*/` y
+   `analysis/*/` (son sub-repos independientes). Por tanto, **un clon fresco del project NO trae sus
+   hijos**, y no existe ningún manifest que diga *qué hijos clonar*. Hoy `/full-git-pull` solo
+   descubre repos vía `discover_git_repos_bash_infra` (busca `.git` ya presentes en disco): si el
+   hijo nunca se clonó, es invisible. Resultado: para reconstruir un project en una máquina nueva hay
+   que adivinar sus sub-repos (exactamente lo que pasó con aurgi).
+
+## Objetivo
+
+Que **todo project** (a) tenga su repo Gitea garantizado y (b) **referencie declarativamente sus
+sub-repos hijos** (apps + analyses), de modo que clonar el project en cualquier PC permita
+re-clonar automáticamente todo su árbol sin adivinar nada.
+
+## Propuesta
+
+### 1. Manifest de sub-repos por project
+
+Añadir a cada project un manifest declarativo de sus hijos. Dos opciones de formato (decidir una):
+
+- **Opción A (KISS, preferida): `subrepos.yaml`** en la raíz del project, análogo a `vault.yaml`:
+
+  ```yaml
+  # projects/<p>/subrepos.yaml — sub-repos hijos de este project (apps + analyses)
+  subrepos:
+    - kind: analysis            # app | analysis
+      name: venta_web
+      path: analysis/venta_web
+      repo: dataforge/venta_web
+      url: https://gitea-.../dataforge/venta_web
+    - kind: analysis
+      name: sale_prices_comprobation
+      path: analysis/sale_prices_comprobation
+      repo: dataforge/sale_prices_comprobation
+      url: https://gitea-.../dataforge/sale_prices_comprobation
+  ```
+
+- **Opción B: sección `## Sub-repos`** en `project.md` con una tabla `kind | name | path | url`.
+
+`subrepos.yaml` (Opción A) es más fácil de parsear por las funciones de git y se versiona con el
+project (no está en el `.gitignore`). El manifest se **autogenera/actualiza** escaneando los `.git`
+hijos presentes en disco + su `remote get-url origin` (reusar `discover_git_repos_bash_infra`).
+
+### 2. Generación y mantenimiento del manifest
+
+Función/pipeline nueva (delegar a `fn-constructor`, grupo `infra`/git) que, dado un project:
+- Escanea `apps/*/.git` y `analysis/*/.git`, lee su remote origin.
+- Escribe/actualiza `subrepos.yaml`.
+- Idempotente. Se invoca dentro de `/full-git-push` (o `fn index`) para mantener el manifest al día.
+
+### 3. Re-clonado desde el manifest en `/full-git-pull`
+
+Extender `/full-git-pull` para que, tras actualizar cada project, lea su `subrepos.yaml` y **clone
+los hijos que falten** (`url` → `path`). Así, en un PC nuevo: clonar `dataforge/<project>` →
+`/full-git-pull` → reconstruye apps + analyses automáticamente. Requiere una función
+`clone_missing_subrepos_bash_infra(project_dir)` (delegar a `fn-constructor`).
+
+### 4. Garantizar repo Gitea de cada project + auditoría en `fn doctor`
+
+- Subcomando nuevo `fn doctor projects` (función `audit_projects_coverage_go_infra`): por cada
+  project en disco reporta `repo_gitea` (existe en Gitea sí/no), `repo_url` (declarado en project.md
+  sí/no), y `subrepos_manifest` (presente + cuántos hijos en disco sin entrada / en manifest sin
+  clonar). Salida `--json`. Cero hallazgos = sano.
+- Acción derivada documentada: `repo_gitea=no` → `ensure_repo_synced_bash_infra projects/<p>
+  dataforge <p> master "init: project <p>"`.
+
+### 5. Backfill inicial
+
+- `aurgi`: traer su `project.md` / `vault.yaml` / `CONVENTIONS.md` de `aurgi-pc` (o `home-wsl`) y
+  crear `dataforge/aurgi` + `subrepos.yaml` con los 3 analyses ya conocidos. **No** reconstruir a
+  mano un `project.md` mínimo (divergiría del real).
+- Resto de projects con hijos (`fleet_monitoring`, `fn_monitoring`, `message_bus`, `web_scraping`):
+  generar su `subrepos.yaml` con la función del punto 2.
+
+## Definition of Done
+
+| Escenario | Tipo | Comando / evidencia | Resultado esperado |
+|---|---|---|---|
+| Golden: clon fresco reconstruye árbol | e2e | clonar `dataforge/<p>` en dir limpio → `/full-git-pull` | apps + analyses del project re-clonados desde `subrepos.yaml` |
+| Edge: project sin hijos (obsidian) | e2e | generar manifest | `subrepos.yaml` válido y vacío (o ausente), sin error |
+| Edge: hijo en disco sin `.git` | unit | auditoría | `fn doctor projects` lo reporta como "hijo sin sub-repo" |
+| Error: project sin repo Gitea | e2e | `fn doctor projects --json` | lo marca `repo_gitea=false`, sugiere `ensure_repo_synced` |
+| Cobertura | audit | `fn doctor projects` | 0 projects sin repo, 0 hijos sin referenciar |
+
+## Decisiones abiertas
+
+1. **Formato del manifest**: `subrepos.yaml` (A) vs. sección en `project.md` (B). Recomendado A.
+2. **¿Auto-generar el manifest en `fn index`** o solo en `/full-git-push`? (evitar I/O de red en
+   `fn index`; preferible en push).
+3. **aurgi**: ¿traer de `aurgi-pc` por SSH ahora, o dejarlo para cuando el project se sincronice?
+
+## Notas
+
+En esta sesión ya se resolvió el riesgo inmediato: `obsidian` y `osint` se subieron a Gitea
+(`dataforge/obsidian`, `dataforge/osint`) con `ensure_repo_synced_bash_infra` y se les añadió
+`repo_url` en su `project.md`. Este issue cubre la solución **estructural y reutilizable** para que
+el caso no vuelva a ocurrir con ningún project. Relacionado con #0166 (dependencias app→app para
+build reproducible): ambos persiguen que clonar el ecosistema en un PC nuevo sea determinista.
+
+## Estado de implementación (10/06/2026)
+
+Implementado con enfoque KISS, **sin** `subrepos.yaml` (registry.db + `fn sync` ya cumplen esa
+función). Cambios:
+
+**Funciones nuevas:**
+- `ensure_project_gitignore_bash_infra` — garantiza idempotente el `.gitignore` canónico de un
+  project (`apps/*/`, `analysis/*/`, `vaults/*` + excepciones) antes de cualquier `git add -A`,
+  para no trackear el contenido de los sub-repos hijos.
+- `audit_projects_coverage_go_infra` (+ `FormatProjectsCoverage`) — motor de `fn doctor projects`.
+  Reporta por project: `git`/`remote`/`repo_url`/`children (cloned/inDB)` + issues
+  (`no_gitea_repo`, `children_missing`, `dir_not_found`). Solo git local + registry.db, sin red.
+
+**Integraciones:**
+- `full_git_push` v1.1.0 — paso 1c: auto-inicializa y pushea los **projects paraguas** sin repo
+  (antes solo apps/analyses), asegurando el `.gitignore` canónico primero. Cierra el agujero
+  aurgi/obsidian/osint.
+- `full_git_pull` v1.1.0 — paso 6: tras `fn sync`, reclona los sub-repos hijos faltantes de cada
+  project con `clone_project_subrepos` + re-index. Clonar el paraguas + `/full-git-pull` reconstruye
+  el árbol entero.
+- `fn doctor projects` — nuevo subcomando (`cmd/fn/doctor.go`). Hoy reporta **0 projects con
+  problemas**.
+
+**Hecho aparte (riesgo inmediato):** `dataforge/obsidian` + `dataforge/osint` creados, `repo_url`
+en sus `project.md`.
+
+### Pendientes (no bloquean el núcleo)
+
+1. **Check inverso — HECHO (10/06/2026).** `FindOrphanProjectRefs` + `FormatOrphanProjectRefs` en
+   `audit_projects_coverage_go_infra`, enchufado en `fn doctor projects`. Detecta apps/analysis con
+   `project_id` sin fila en `projects`. Hoy reporta 4 paraguas huérfanos (existen en otro PC, nunca
+   subidos a Gitea — mismo caso que aurgi):
+   - `element_agents` (6 apps: agents_and_robots, agents_dashboard, device_agent, element_matrix_chat,
+     matrix_admin_panel, matrix_client_pc)
+   - `imagegen` (image_to_3d_studio)
+   - `osint_graph` (graph_explorer)
+   - `aurgi` (sus analyses sí están en Gitea; el paraguas no)
+2. **Fix de datos de los 4 paraguas huérfanos — pendiente, requiere el PC origen.** No están en disco
+   ni en Gitea en este PC (`lucas-linux`), así que no se pueden reconstruir aquí sin inventar. El fix
+   correcto: correr `/full-git-push` en el PC donde cada paraguas existe en disco (`aurgi-pc` /
+   `home-wsl`). Con `full_git_push` v1.1.0 (paso 1c) eso ya los crea en Gitea automáticamente. Tras
+   eso, `/full-git-pull` aquí (paso 6) los traerá. NO reconstruir un `project.md` mínimo a mano.
+3. **DoD vida útil**: validar el reclonado en un PC nuevo real (clon limpio del paraguas →
+   `/full-git-pull` → árbol reconstruido) antes de declarar el issue cerrado.
@@ -0,0 +1,184 @@
+---
+id: "0172"
+title: "App web OSINT: grafo sigma.js + tablas por tipo + fichas con imágenes sobre el vault osint"
+status: pendiente
+type: app
+domain:
+  - osint
+  - frontend
+scope: app-scoped
+priority: media
+depends: []
+blocks: []
+related: ["0171"]
+created: 2026-06-10
+updated: 2026-06-10
+tags: [osint, web, sigma, graph, mantine, obsidian, vault, dashboard]
+---
+# 0172 — App web OSINT: grafo sigma.js + tablas por tipo + fichas con imágenes
+
+## APP Metadata
+
+| Campo | Valor |
+|-------|-------|
+| **ID** | 0172 |
+| **Estado** | pendiente (solo plan — se construye cuando el vault tenga más datos) |
+| **Prioridad** | media |
+| **Tipo** | app — nueva app web en `projects/osint/apps/osint_web` |
+| **Project** | osint (`projects/osint/`) |
+
+## Contexto
+
+El project `osint` guarda sus investigaciones en el vault de Obsidian
+`/home/enmanuel/Obsidian/osint` (sub-repo `dataforge/osint`). Hoy ese vault tiene:
+
+- **~82 nodos** repartidos en carpetas tipadas: `personas/` (45), `organizaciones/` (25),
+  `lugares/` (10), `dominios/` (1), `casos/` (1).
+- **Datos tabulares** en el frontmatter YAML de cada ficha: `tipo`, `nombre`, `sexo`,
+  `fecha_nacimiento`, `dni`, `direccion`, `pais`, `aliases`, `tags`, etc.
+- **Aristas implícitas**: los wikilinks `[[...]]` en las secciones `Relaciones`, `Lugares` y
+  `Documentos` conectan unas fichas con otras (y con sus attachments).
+- **~240 attachments**: fotos, DNIs, certificados y PDFs en `attachments/<tipo>/<slug>/`,
+  embebidos en las notas con `![[...]]`.
+
+Obsidian es bueno para *escribir* la investigación, pero malo para *explorarla* de un vistazo:
+no da un grafo navegable de todos los objetivos, ni una tabla filtrable, ni una ficha-resumen
+con la galería de imágenes de cada persona. Metabase/Grafana no encajan: leen BD SQL (no `.md`),
+y no muestran ni grafo de nodos ni imágenes inline.
+
+Decisión del usuario (10/06/2026): construir una **app web propia** que lea el vault y ofrezca
+tres vistas — **grafo explorable con sigma.js**, **tablas filtradas por tipo**, y **fichas con
+imágenes**. Este issue es **solo el plan**: la recopilación de datos en Obsidian continúa primero;
+la app se implementa cuando haya suficiente material que justifique la inversión.
+
+## Objetivo
+
+Una app web local que, leyendo directamente los `.md` del vault `osint` (sin BD intermedia
+obligatoria en v1), permita:
+
+1. **Explorar el grafo** de nodos (personas, organizaciones, lugares, dominios, casos) y sus
+   conexiones por wikilinks, con sigma.js: zoom, pan, click en nodo → ficha, colores por tipo,
+   filtro de tipos visibles, búsqueda de nodo.
+2. **Ver tablas filtradas por tipo**: una tabla por categoría (personas, organizaciones, ...)
+   con las columnas del frontmatter, ordenable y filtrable (por dni, lugar, fecha, tag).
+3. **Abrir la ficha** de cualquier nodo: frontmatter renderizado + cuerpo Markdown + galería de
+   sus attachments (fotos, DNIs, PDFs) servidos por el backend.
+
+## Arquitectura propuesta
+
+```
+projects/osint/apps/osint_web/        (sub-repo Gitea dataforge/osint_web)
+  app.md                              frontmatter de registro (framework: react-vite-mantine)
+  server/                             backend Python (lee el vault, sirve JSON + attachments)
+    main.py                           FastAPI o stdlib http
+  frontend/                           React + Vite + Mantine + sigma.js
+    src/
+      views/GraphView.tsx             sigma.js + graphology
+      views/TablesView.tsx            Mantine DataTable filtrable por tipo
+      views/NodeCard.tsx              ficha + galería de attachments
+```
+
+### Backend (Python — máximo reuso del grupo `obsidian`)
+
+Python porque el grupo de capacidad `obsidian` (11 funciones, dominio `obsidian`) ya cubre casi
+todo el parseo del vault. **Registry-first**: el backend orquesta estas funciones, no reimplementa
+el parseo.
+
+Funciones del registry a reutilizar:
+
+| Función | Uso en la app |
+|---|---|
+| `list_obsidian_notes_py_obsidian` | enumerar nodos por carpeta/tipo |
+| `read_obsidian_note_py_obsidian` | leer ficha: `{frontmatter, body, wikilinks, tags}` |
+| `parse_obsidian_frontmatter_py_obsidian` | datos tabulares de cada nodo |
+| `extract_obsidian_wikilinks_py_obsidian` | aristas del grafo |
+| `extract_obsidian_embeds_py_obsidian` | attachments embebidos en cada nota |
+| `resolve_obsidian_embed_py_obsidian` | resolver `![[foto.jpg]]` → path real en disco para servir la imagen |
+| `slugify_obsidian_name_py_obsidian` | normalizar nombre de wikilink → id de nodo |
+| `search_obsidian_notes_py_obsidian` | búsqueda global en el grafo |
+
+Funciones **nuevas** a delegar a `fn-constructor` (no escribir inline en la app):
+
+- `build_obsidian_graph_py_obsidian` (impure) — dado `vault_dir`, devuelve
+  `{"nodes": [{id, tipo, label, frontmatter}], "edges": [{source, target, kind}]}`.
+  Resuelve cada wikilink a un nodo existente (vía slug / nombre de archivo); los wikilinks que
+  no resuelven a un `.md` del vault se marcan como aristas "dangling" o se descartan según flag.
+  Tag de grupo: `obsidian`. Es la pieza que el grupo declara como frontera no cubierta
+  ("No indexa el grafo agregado") — esta función la cierra.
+
+Endpoints HTTP (JSON salvo el de attachments):
+
+| Método | Ruta | Devuelve |
+|---|---|---|
+| GET | `/api/graph` | grafo completo `{nodes, edges}` para sigma.js |
+| GET | `/api/nodes?tipo=persona` | filas de la tabla de ese tipo (frontmatter aplanado) |
+| GET | `/api/node/{slug}` | ficha: frontmatter + body (HTML/markdown) + lista de attachments |
+| GET | `/api/attachment?path=...` | sirve el binario del attachment (image/pdf), con allowlist al vault |
+| GET | `/api/search?q=...` | nodos que matchean |
+
+Seguridad: el backend solo sirve archivos **dentro** del vault osint (path traversal bloqueado).
+El vault contiene datos personales sensibles (DNIs) → la app escucha **solo en `127.0.0.1`**, sin
+exponer a red. No es un service desplegable a VPS.
+
+### Frontend (React + Vite + Mantine + sigma.js)
+
+- Sistema del registry: React + Vite + Mantine v9 + `@fn_library` (grupo `mantine`, 63 funciones).
+  Componentes propios de `@fn_library` antes que HTML nativo (regla `frontend_theming.md`).
+- **Grafo**: `sigma.js` + `graphology`. Color por `tipo`, tamaño por grado, layout
+  force-directed (graphology-layout-forceatlas2). Click en nodo → abre `NodeCard`. Panel lateral
+  con toggles de tipos visibles y caja de búsqueda.
+- **Tablas**: una pestaña por tipo, Mantine `Table`/DataTable con columnas del frontmatter,
+  orden y filtro por columna (dni, lugar, fecha_nacimiento, tags).
+- **Fichas**: `NodeCard` con frontmatter en formato clave-valor (fechas en formato europeo
+  DD/MM/AAAA — memoria `formato-fecha-europeo`), cuerpo Markdown, y galería de attachments
+  (imágenes con lightbox; PDFs como enlace/embed).
+
+`sigma.js` y `graphology` son dependencias nuevas del frontend (no en `@fn_library`). KISS:
+añadir solo esas dos; el resto (tabla, layout, modales) sale de Mantine/`@fn_library`.
+
+## Decisiones abiertas
+
+1. **¿BD intermedia o lectura directa del vault?** v1 lee el vault en cada arranque (cachea el
+   grafo en memoria). Si el vault crece mucho o se quiere histórico/diff, evaluar un
+   `operations.db` con `entities`/`relations` (encaja con el bucle reactivo). Recomendado:
+   empezar sin BD (KISS), añadirla solo si el rendimiento o un caso de uso lo exige.
+2. **Backend FastAPI vs stdlib http**: FastAPI da validación y OpenAPI gratis; stdlib evita una
+   dependencia. Como el backend es fino (orquesta funciones del registry), decidir al construir.
+3. **Live-reload del vault**: ¿re-escanear bajo demanda (botón "refrescar") o watcher de
+   filesystem? v1: botón refrescar (simple). Watcher si molesta.
+4. **Aristas dangling**: wikilinks a notas que aún no existen — ¿mostrarlos como nodos fantasma
+   (útil para ver "objetivos pendientes de fichar") o esconderlos? Propuesta: nodo fantasma con
+   estilo atenuado, toggle para ocultar.
+
+## Definition of Done
+
+| Escenario | Tipo | Comando / evidencia | Resultado esperado |
+|---|---|---|---|
+| Golden: grafo carga el vault | e2e | `GET /api/graph` con el vault osint real | `nodes` ≥ nº de `.md`, `edges` con los wikilinks resueltos; sigma.js los pinta |
+| Golden: ficha con imágenes | e2e | `GET /api/node/<persona con fotos>` + abrir NodeCard | frontmatter + cuerpo + galería con las imágenes de `attachments/personas/<slug>/` |
+| Edge: tabla filtrada por tipo | e2e | `GET /api/nodes?tipo=organizacion` | solo nodos de ese tipo, columnas del frontmatter |
+| Edge: wikilink dangling | unit | nota con `[[Persona-Inexistente]]` | arista marcada dangling / nodo fantasma, sin crash |
+| Edge: nombre con mayúsculas/acentos | unit | wikilink `[[María del Mar]]` → slug | resuelve a `maria-del-mar-...md` vía `slugify_obsidian_name` |
+| Error: path traversal en attachment | e2e | `GET /api/attachment?path=../../etc/passwd` | 403/404, jamás sirve fuera del vault |
+| Error: vault inexistente | e2e | arrancar con `--vault /no/existe` | error claro al arrancar, no 500 silencioso |
+| Cobertura | audit | `uses_functions` del `app.md` | declara todas las funciones del grupo `obsidian` consumidas |
+
+Vida útil (cuando se construya): usar la app de verdad sobre el vault osint durante ≥7 días en
+investigaciones reales; medir que el grafo sigue cargando sin romperse al crecer el vault.
+
+## Notas
+
+**Estado actual: solo plan.** No construir todavía — la recopilación de datos en Obsidian
+continúa; cuando el vault tenga masa crítica de objetivos/relaciones, se arranca con
+`/new-cpp-app` no aplica (es web): se hace `git init` del sub-repo `dataforge/osint_web` dentro de
+`projects/osint/apps/osint_web/` antes de limpiar cualquier worktree (regla `apps_subrepo.md`),
+scaffolding de frontend con el stack Mantine del registry, y backend Python orquestando el grupo
+`obsidian`.
+
+Onboarding (para cuando exista): arrancar backend `python server/main.py --vault
+/home/enmanuel/Obsidian/osint --port 8470` y `pnpm dev` en `frontend/`; abrir
+`http://127.0.0.1:5173`. Pestañas: Grafo / Tablas / (ficha al click). Solo localhost por los
+datos sensibles del vault.
+
+Relación con #0171 (manifest de sub-repos): cuando esta app exista será un hijo del project
+`osint` y debe entrar en su `subrepos.yaml` para re-clonarse en otros PCs.
@@ -24,7 +24,10 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
 | [docker](docker.md) | 38 | Operar Docker desde Go/Bash: build/run/stop, compose, networks, volumes, logs, deploys |
 | [android](android.md) | 37 | Toolbelt Android desde WSL2: adb, emuladores AVD, APK build/install, Capacitor, logcat |
 | [web-proxy](web-proxy.md) | 5 | Captura de trafico HTTP/HTTPS liviana (mitmproxy): proxy con rotacion, navegador proxeado, consulta de capturas, tee del SSE de claude. Alternativa ligera a ZAP/Burp |
+| [claude-fleet](claude-fleet.md) | 5 | Orquestar la flota de procesos Claude Code vivos: panel TUI (fleetview) + comando fleetclaude que centraliza N Claudes en una ventana kitty/tmux (socket -L fleet), conmuta cual esta embebido (alt+flechas/enter/n) y los lista desde ~/.claude/sessions+goals |
 | [flow-replay](flow-replay.md) | 3 | Guardar un flujo web (login, reiniciar server, formulario) como funcion reproducible: destila un HAR a call specs y lo reproduce sin navegador (HTTP puro), con fallback a chromium headless/visible. Consume las capturas de web-proxy |
+| [hoppscotch](hoppscotch.md) | 7 | Operar Hoppscotch SELF-HOSTED (docker en selfhost/) via API GraphQL: login (magic link headless via mailpit), CRUD de requests (create/update/delete/list), set_environment (idempotente, resuelve secretos pass:). El agente crea/edita y el humano lo ve en vivo en su GUI (subscriptions). build es helper interno de serializacion. Modo .json local ELIMINADO |
+| [dav](dav.md) | 9 | Cliente CardDAV/CalDAV (Python, solo stdlib) para Xandikos: parte un .vcf/.ics export de Google en recursos individuales (split puro), extrae/sintetiza UID, sube por HTTP PUT con Basic auth, lista (PROPFIND) y descarga (GET) recursos. Dos pipelines de import (vcf->carddav, ics->caldav). Formaliza la migracion ad-hoc de contactos/calendario |
 | [metabase](metabase.md) | 106 | Operar Metabase via API REST: auth, cards, dashboards, collections, snippets, permissions |
 | [doctor](doctor.md) | 11 | Diagnostico read-only del registry: artefactos, servicios, drift, funciones huerfanas |
 | [notebook](notebook.md) | 5 | Operar Jupyter Lab colaborativo (discover/read/exec/write/kernel) |
@@ -49,6 +52,15 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
 | [mesh-3d](mesh-3d.md) | 3 | Carga y upload a GPU de meshes 3D (OBJ, GLB/glTF 2.0): loaders CPU + mesh_gpu_upload OpenGL |
 | [terminal-capture](terminal-capture.md) | 6 | Automatizar y capturar el texto de una CLI/TUI interactiva via PTY headless: spawn+input scripteado (one-shot y streaming), render del layout 2D (emulador VT), strip ANSI, delta por prefijo, y parseo de la TUI de claude a datos |
 | [claude-direct](claude-direct.md) | 3 | Hablar directamente con la API de Anthropic Messages usando el token OAuth de Claude Code (Claude Max): leer token, stream SSE, bucle agentico de tool-use |
+| [obsidian](obsidian.md) | 16 | CRUD headless de vaults y notas Obsidian como Markdown plano (frontmatter YAML + wikilinks): parse/format, read/create/update/delete/list/search notas, list/create vaults, slugify/embeds/resolve, render tabla Markdown + bloques sentinel gestionados. Sin app GUI |
+| [duckdb](duckdb.md) | 10 | Operar bases DuckDB: open (Go), query/execute/upsert, introspeccion (list_tables, table_schema), CSV->Parquet, dedup, OHLCV, e ingesta desde Excel (excel_to_duckdb) + salida a Postgres (duckdb_to_postgres). Motor analitico del stack de datos Excel->DuckDB->Postgres->viz |
+| [excel](excel.md) | 6 | CRUD de hojas Excel (.xlsx) con openpyxl: escribir multi-hoja, upsert no destructivo (preserva columnas manuales), leer a memoria, leer a markdown, graficos nativos (bar/line/pie/scatter), e ingesta a DuckDB. Round-trip de datos con humanos |
+| [postgres](postgres.md) | 7 | CRUD de PostgreSQL via psycopg2 (dsn): connect (Go), query read-only, insert append-only, upsert idempotente, crear tabla inferida, introspeccion, aplicar .sql. Capa que sirve datos a Metabase/Grafana (que no hablan DuckDB nativo) |
+| [recon](recon.md) | 8 | Reconocimiento de red OSINT: whois, rdap, dns (dig), ping, traceroute, nmap por perfiles. Cada scan se archiva en OSINT (nota vault + tabla DuckDB network_scans) via el sink save_scan_to_osint o el pipeline one-shot recon_osint. Perfiles nmap pesados (full-tcp/vuln/udp-top) en segundo plano. No es framework de explotacion; solo hosts autorizados |
+| [osint-passive](osint-passive.md) | 8 | Recoleccion OSINT pasiva (fuentes publicas, no intrusiva): EXIF/PDF metadata, whois RDAP, DNS, subdominios crt.sh, guess emails, username enumeration, search dorks |
+| [osint-enrich](osint-enrich.md) | 3 | Orquestadores de enriquecimiento OSINT: componen osint-passive para aumentar datapoints de personas (emails/usernames/dorks), orgs (whois+dns+subdominios) y metadatos de attachments |
+| [market-intel](market-intel.md) | 8 | Inteligencia de mercado para captacion de clientes: scrapers de tendencias de productos/nichos (Amazon, Google Trends, TikTok, AliExpress) + precios de competencia, aterrizados en Postgres (pg_insert_rows/pg_apply_sql) y analizados en Metabase. Dispatcher ingest_market_trends invocado por dag_engine. TikTok/AliExpress por HTTP caen (anti-bot); pendiente browser CDP |
+| [onlyoffice](onlyoffice.md) | 3 | Operar ONLYOFFICE Desktop Editors (binario onlyoffice-desktopeditors) en Linux/X11 desde terminal via instancia aislada (slot HOME=/tmp/oo_<instance>): abrir un archivo en ventana propia, cerrar+reabrir para mostrar datos editados en disco (no hay reload nativo, Issue #2313), y matar el proceso del slot. Solo gestiona la ventana, NO edita ni crea archivos. Requiere X11 + wmctrl + xdotool. No confundir con el Document Server (web/Docker) |

 ## Como anadir grupo

@@ -0,0 +1,68 @@
+# Capability group: claude-fleet
+
+Operar la **flota de procesos Claude Code** vivos en la máquina como una sola
+unidad: descubrirlos, listarlos en un panel TUI y centralizarlos en una ventana
+kitty con tmux donde se conmuta cuál está embebido a la derecha. Reemplaza el
+caos de N ventanas kitty dispersas por un único punto de entrada.
+
+Pieza visible: la app `fleetview` (TUI). Entrypoint: el comando `fleetclaude`.
+
+## Funciones
+
+| ID | Firma | Qué hace |
+|---|---|---|
+| `list_claude_fleet_go_infra` | `ListClaudeFleet() ([]ClaudeFleet, error)` | Escanea `~/.claude/sessions/*.json` + `goals/`, valida procesos vivos (anti-PID-reciclado), join por `sessionId` → lista tipada con status/objetivo/cwd/target. |
+| `launch_fleetclaude_bash_infra` | `launch_fleetclaude [--cwd <d>] [--bin <p>] [--session <n>] [--cols <n>]` | Entrypoint: abre kitty con sesión tmux (socket aislado `-L fleet`) de dos panes (TUI izq + Claude der). Instala atajos `alt+*` e hijos del sidebar. |
+| `tmux_new_claude_window_go_infra` | `TmuxNewClaudeWindow(socket, session, cwd string) (string, error)` | Crea una window tmux nueva con `claude --dangerously-skip-permissions`. Devuelve el `window_id`. |
+| `tmux_swap_window_into_console_go_infra` | `TmuxSwapWindowIntoConsole(socket, session, windowID string) error` | Trae el Claude de `windowID` al pane derecho de `console` (junto a la TUI), parkea el anterior, re-fija el ancho del sidebar. |
+| `tmux_map_claude_panes_go_infra` | `TmuxMapClaudePanes(socket string) (map[int]string, error)` | Mapa `claudePID → window_id` de los Claude que viven en la sesión (vía `list-panes` + descendencia `/proc`). Permite a la TUI saber cuáles son conmutables. |
+
+App relacionada: `fleetview_go_infra` (`apps/fleetview/`) — la TUI Bubble Tea que consume `list_claude_fleet` y orquesta los wrappers tmux.
+
+## Ejemplo canónico (end-to-end)
+
+```bash
+# 1. Compilar la TUI una vez.
+cd ~/fn_registry/apps/fleetview && go build -o fleetview .
+
+# 2. Abrir la flota (una ventana kitty: panel izq + Claude der).
+fn run launch_fleetclaude
+
+# 3. Dentro de la ventana, desde CUALQUIER pane (incluido escribiendo en Claude):
+#    alt+↑/↓     mueve el cursor de la lista
+#    alt+enter   conmuta el pane derecho al Claude seleccionado
+#    alt+n       abre un Claude nuevo (window en fleet) y conmuta a él
+
+# Inspección headless de la flota sin abrir nada:
+fn run list_claude_fleet | jq '.[] | {rename, status, goal}'
+```
+
+Bajo el capó de `alt+enter`/`alt+n`: tmux redirige la tecla al pane de la TUI
+(`bind -n M-Enter send-keys -t console.0 Enter`); la TUI resuelve el Claude
+seleccionado con `TmuxMapClaudePanes` y lo trae con `TmuxSwapWindowIntoConsole`
+(o crea uno con `TmuxNewClaudeWindow`).
+
+## Fronteras (qué NO cubre)
+
+- **No gestiona Claudes remotos** (ej. los de una sesión tmux del móvil): se
+  listan como contexto pero no se embeben localmente (no son panes de fleet).
+- **Adopción de Claudes sueltos pendiente**: un Claude vivo en otra ventana kitty
+  (fuera de fleet) se lista, pero `alt+enter` sobre él aún no lo trae —
+  requerirá relaunch `claude --resume <sessionId>` dentro de fleet (patrón de
+  `reboot_all_claudes_bash_infra`).
+- **No reinicia ni mata Claudes** (todavía): `resume`/`kill` desde el panel son
+  fase posterior. Para reiniciar toda la flota existe `reboot_all_claudes_bash_infra`.
+- **Linux + kitty + tmux** únicamente (build tag `!windows`, usa `/proc`).
+
+## Prerequisitos
+
+- `kitty` y `tmux` en el PATH. La sesión vive en un server tmux aislado (`-L fleet`).
+- La TUI `fleetview` compilada (`apps/fleetview/fleetview`).
+- Claude Code ≥ 2.1.x (escribe `~/.claude/sessions/<PID>.json` con `status`).
+
+## Notas
+
+- Toda la sesión usa el socket `-L fleet`: los atajos `bind -n` no afectan al
+  tmux por defecto del usuario; `tmux -L fleet kill-server` lo limpia entero.
+- `reboot_all_claudes_bash_infra` comparte la misma fuente de verdad
+  (`~/.claude/sessions/<PID>.json`) y es el complemento para reiniciar la flota.
@@ -0,0 +1,106 @@
+# dav — Cliente CardDAV/CalDAV (Python, solo stdlib)
+
+Grupo de capacidad para operar un servidor **CardDAV/CalDAV** (Xandikos, git-backed,
+en el VPS `magnus`) desde Python sin dependencias externas. Cubre el flujo de
+**migracion**: partir un export de Google (un `.vcf` con N contactos, un `.ics` con
+N eventos) en recursos individuales y subirlos uno a uno por HTTP PUT con Basic auth.
+Tambien listar y descargar recursos para verificar o hacer backup.
+
+Formaliza el flujo ad-hoc (heredocs) que migro 820 contactos + 98 eventos a Xandikos
+(regla `function_growth_and_self_docs`: una composicion repetida >2 veces se promueve
+a funciones/pipelines del registry).
+
+## Restriccion de diseno
+
+**Solo stdlib** (`urllib.request`, `re`, `hashlib`, `base64`, `ssl`). Sin `requests`,
+`caldav` ni `vobject`. El header `Authorization: Basic base64(user:pass)` se construye
+a mano. `verify_tls=True` por defecto. Coherente con el grupo `osint-passive` (sin deps).
+
+## Funciones
+
+| ID | Firma corta | Que hace | Purity |
+|---|---|---|---|
+| `split_vcards_py_infra` | `split_vcards(vcf_text) -> list` | Parte un `.vcf` en VCARDs individuales | pure |
+| `split_vevents_to_vcalendars_py_infra` | `split_vevents_to_vcalendars(ics_text, prodid?) -> list` | Parte un VCALENDAR con N VEVENT en N VCALENDARs autonomos (replica VTIMEZONE) | pure |
+| `extract_or_make_uid_py_infra` | `extract_or_make_uid(text, prefix?) -> str` | Extrae el `UID:` o sintetiza `<prefix><md5[:16]>` determinista | pure |
+| `carddav_put_vcard_py_infra` | `carddav_put_vcard(base_url, user, pw, coll, uid, vcard) -> dict` | PUT de un VCARD (`.vcf`, `text/vcard`) | impure |
+| `caldav_put_event_py_infra` | `caldav_put_event(base_url, user, pw, coll, uid, vcal) -> dict` | PUT de un VCALENDAR (`.ics`, `text/calendar`) | impure |
+| `dav_list_resources_py_infra` | `dav_list_resources(base_url, user, pw, coll) -> dict` | PROPFIND Depth:1 -> lista de `{href, etag}` | impure |
+| `dav_get_resource_py_infra` | `dav_get_resource(base_url, user, pw, href) -> dict` | GET de un recurso -> texto VCARD/VCALENDAR | impure |
+| `dav_make_calendar_py_infra` | `dav_make_calendar(base_url, user, pw, calendar_home, slug, name?, color?, desc?) -> dict` | MKCALENDAR + PROPPATCH: crea una coleccion de calendario (agenda) nueva | impure |
+| `dav_make_addressbook_py_infra` | `dav_make_addressbook(base_url, user, pw, contacts_home, slug, name?, desc?) -> dict` | Extended MKCOL: crea una coleccion CardDAV (libreta/agenda de contactos) nueva | impure |
+| `dav_list_addressbooks_py_infra` | `dav_list_addressbooks(base_url, user, pw, contacts_home) -> dict` | PROPFIND Depth:1: lista las libretas CardDAV del contacts-home con nombre y descripcion | impure |
+| `build_vcard_py_core` | `build_vcard(contact: dict) -> str` | Serializa un contacto a VCARD 3.0 MULTI-VALOR (N TEL/EMAIL/ADR + X-OSINT-*); pura | pure |
+| `expand_rrule_py_infra` | `expand_rrule(dtstart_ical, rrule, range_start, range_end, all_day?) -> list` | Expande una RRULE iCalendar a las fechas de cada ocurrencia dentro de un rango | pure |
+| `import_vcf_to_carddav_py_pipelines` | `import_vcf_to_carddav(vcf_path, base_url, user, pw, coll) -> dict` | Pipeline: .vcf -> split -> uid -> PUT por tarjeta | impure |
+| `import_ics_to_caldav_py_pipelines` | `import_ics_to_caldav(ics_path, base_url, user, pw, coll) -> dict` | Pipeline: .ics -> split -> uid -> PUT por evento | impure |
+
+## Sistema real (para los ejemplos)
+
+- Servidor: **Xandikos** en `https://dav-eedeb681c4ab89ab8e444ac9.organic-machine.com`, Basic auth, usuario `enmanuel`.
+- Password: `pass dav/xandikos-enmanuel` (primera linea). Resolver con `pass_get_secret_py_infra`, NUNCA hardcodear.
+- Principal: `/enmanuel/`. Colecciones:
+  - CardDAV: `/enmanuel/contacts/addressbook/`
+  - CalDAV: `/enmanuel/calendars/calendar/`
+
+## Ejemplo canonico end-to-end
+
+Importar un `.vcf` exportado de Google a Xandikos, leyendo la password de `pass`:
+
+```python
+import sys
+sys.path.insert(0, "python/functions")
+from infra.pass_get_secret import pass_get_secret
+from pipelines.import_vcf_to_carddav import import_vcf_to_carddav
+
+BASE = "https://dav-eedeb681c4ab89ab8e444ac9.organic-machine.com"
+pw = pass_get_secret("dav/xandikos-enmanuel")["value"]  # NO logear
+
+summary = import_vcf_to_carddav(
+    vcf_path="/home/enmanuel/Descargas/contacts.vcf",
+    base_url=BASE,
+    username="enmanuel",
+    password=pw,
+    collection_path="/enmanuel/contacts/addressbook/",
+)
+print(summary["ok"], summary["fail"], summary["total"])  # 820 0 820
+```
+
+Verificar el resultado listando la coleccion:
+
+```python
+from infra.dav_list_resources import dav_list_resources
+res = dav_list_resources(BASE, "enmanuel", pw, "/enmanuel/contacts/addressbook/")
+print(res["status"], len(res["resources"]))  # ok 820
+```
+
+El calendario es analogo con `import_ics_to_caldav` + `/enmanuel/calendars/calendar/`.
+
+Desde la CLI del registry (resuelve la pass como variable, no la pongas en claro):
+
+```bash
+PW=$(pass show dav/xandikos-enmanuel | head -n1)
+./fn run import_vcf_to_carddav /home/enmanuel/Descargas/contacts.vcf \
+  https://dav-eedeb681c4ab89ab8e444ac9.organic-machine.com \
+  enmanuel "$PW" /enmanuel/contacts/addressbook/
+```
+
+## Fronteras
+
+- **No descubre el principal ni las colecciones**: hay que conocer los paths
+  (`/enmanuel/contacts/addressbook/`, etc.). No implementa `current-user-principal`
+  ni `addressbook-home-set` discovery.
+- **No hace sync incremental** real: `dav_list_resources` devuelve etags pero no
+  hay logica de diff/merge. Re-importar es idempotente por UID (sobrescribe), no
+  incremental.
+- **No parsea campos VCARD/VEVENT**: trata cada componente como texto opaco. Para
+  transformar contenido (renombrar, deduplicar por nombre) usa otra herramienta.
+- **Solo VEVENT** en calendario: VTODO/VJOURNAL se ignoran al partir el `.ics`.
+- **Escrituras irreversibles**: los PUT sobrescriben en el servidor. Idempotente
+  por UID pero no hay confirmacion previa; valida el `.vcf`/`.ics` antes de importar.
+
+## Prerequisitos
+
+- `pass` configurado con la entrada `dav/xandikos-enmanuel`.
+- Conectividad TLS al endpoint publico (`verify_tls=True`).
+- Python del registry: `python/.venv/bin/python3`.
@@ -0,0 +1,90 @@
+# Capability: duckdb
+
+Operar bases de datos DuckDB desde el registry: abrir/crear bases, consultas read-only seguras, conversion CSV -> Parquet, deduplicacion por hash y carga de series temporales. DuckDB es el motor analitico embebido del ecosistema (OLAP local, archivos `.duckdb`, lectura directa de CSV/Parquet/JSON).
+
+Pieza central del patron **BD como fuente de verdad + Obsidian como vista** (project `osint`): la app `osint_db` posee la DuckDB maestra y este grupo aporta las primitivas de acceso.
+
+## Funciones
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `duckdb_open_go_infra` | `DuckDBOpen(path string) (*sql.DB, error)` | Abre (o crea) una base DuckDB desde Go. Path vacio o `:memory:` abre en memoria. |
+| `duckdb_query_readonly_py_infra` | `duckdb_query_readonly(db_path, sql, params=None, max_rows=10000) -> dict` | Consulta read-only segura: conexion `read_only=True`, params posicionales `?`, filas como `list[dict]` con tipos normalizados a JSON (date/datetime -> isoformat, Decimal -> float, bytes -> base64). Devuelve `{status, columns, rows, row_count, truncated}` sin lanzar. |
+| `duckdb_execute_py_infra` | `duckdb_execute(db_path, sql, params=None) -> dict` | Ejecuta UNA sentencia de escritura (INSERT/UPDATE/DELETE/DDL) en conexion read-write, commit, devuelve `{status, rowcount}` sin lanzar. Primitivo de escritura del grupo (complementa a `duckdb_query_readonly`). |
+| `duckdb_upsert_py_infra` | `duckdb_upsert(db_path, table, rows, key_cols, update_cols=None) -> dict` | UPSERT idempotente `INSERT ... ON CONFLICT (key_cols) DO UPDATE SET ...` actualizando SOLO `update_cols`. Excluir columnas de `update_cols` permite que un re-upsert NO las pise (ownership selectivo: la DB es la verdad). Devuelve `{status, inserted, updated}`. |
+| `csv_to_parquet_duckdb_py_core` | `csv_to_parquet_duckdb(csv_path, parquet_path, column_casts=None, overwrite=False) -> bool` | Convierte CSV -> Parquet con `read_csv_auto`. `column_casts` fuerza tipos por columna. No reescribe si el parquet existe y `overwrite=False`. |
+| `dedup_duckdb_table_by_hash_py_pipelines` | `dedup_duckdb_table_by_hash(duckdb_path, table, exclude_cols=None) -> dict` | Pipeline: anade columna `row_hash` (md5 de columnas de datos) idempotentemente y borra filas duplicadas conservando la primera insercion. |
+| `load_ohlcv_from_duckdb_go_finance` | `LoadOHLCVFromDuckDB(dbPath, query string) ([][]float64, error)` | Carga datos OHLCV ejecutando una query SQL sobre una base DuckDB (consumo desde apps Go de finanzas). |
+| `duckdb_list_tables_py_infra` | `duckdb_list_tables(db_path) -> dict` | Introspección read-only: lista las tablas (`information_schema.tables`, schema main) ordenadas. Devuelve `{status, tables}`. |
+| `duckdb_table_schema_py_infra` | `duckdb_table_schema(db_path, table) -> dict` | Introspección read-only: schema de una tabla (`DESCRIBE`). Devuelve `{status, table, columns:[{name,type}]}`. Útil para mapear tipos a otro motor (p.ej. PostgreSQL). |
+| `excel_to_duckdb_py_infra` | `excel_to_duckdb(xlsx_path, duckdb_path, table, sheet=None, mode='replace') -> dict` | **Puente de entrada Excel→DuckDB**: ingiere una hoja `.xlsx` a una tabla con la extensión nativa `excel` de DuckDB. `replace`/`append`. Devuelve `{status, table, row_count}`. |
+| `duckdb_to_postgres_py_pipelines` | `duckdb_to_postgres(duckdb_path, table, pg_dsn, pg_table=None, mode='replace', key_cols=None, batch_size=5000) -> dict` | **Puente de salida DuckDB→Postgres**: mapea tipos, crea la tabla y sincroniza filas. Desbloquea que Metabase/Grafana/Superset (que no hablan DuckDB) lean los datos. Devuelve `{status, pg_table, rows_synced, created}`. |
+
+## Puentes: Excel → DuckDB → Postgres → visualización
+
+DuckDB es el centro del stack de datos: el motor analítico embebido. Los datos entran desde Excel y salen hacia BI:
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from infra import excel_to_duckdb, duckdb_list_tables, duckdb_query_readonly
+from pipelines.duckdb_to_postgres import duckdb_to_postgres
+
+# 1. Excel -> DuckDB (extensión nativa, sin pandas)
+excel_to_duckdb("/tmp/ventas.xlsx", "/tmp/datos.duckdb", "ventas", sheet="ventas")
+print(duckdb_list_tables("/tmp/datos.duckdb"))
+
+# 2. Analítica en DuckDB
+print(duckdb_query_readonly("/tmp/datos.duckdb",
+    "SELECT categoria, SUM(importe) AS total FROM ventas GROUP BY 1")["rows"])
+
+# 3. DuckDB -> Postgres (para que Metabase/Grafana lo lean)
+# dsn = "postgresql://captacion:<pass>@localhost:5433/trends"
+# duckdb_to_postgres("/tmp/datos.duckdb", "ventas", dsn, pg_table="ventas", mode="replace")
+PYEOF
+```
+
+- **Evidence.dev** lee el `.duckdb` directamente (nativo) — no necesita el puente a Postgres.
+- **Metabase / Grafana / Superset** no hablan DuckDB → usa `duckdb_to_postgres` y apunta la herramienta al Postgres espejo.
+
+## Ejemplo canonico
+
+Consulta read-only desde cualquier sesion (la conexion se abre `read_only=True` y se cierra siempre):
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from infra import duckdb_query_readonly
+
+res = duckdb_query_readonly(
+    "projects/osint/apps/osint_db/data/osint.duckdb",
+    "SELECT contexto, COUNT(*) AS n FROM persons GROUP BY contexto ORDER BY n DESC",
+    max_rows=50,
+)
+print(res["status"], res["row_count"])
+for row in res["rows"]:
+    print(row)
+PYEOF
+```
+
+Conversion CSV -> Parquet en una linea:
+
+```bash
+./fn run csv_to_parquet_duckdb datos.csv datos.parquet
+```
+
+## Gotchas del grupo
+
+- **Single-writer**: DuckDB permite UN solo proceso escritor por archivo. Si un service (ej. `osint_db`) posee la base, el resto de procesos deben leer con `read_only=True` (`duckdb_query_readonly` ya lo hace) o pasar por la API HTTP del service. Las funciones de escritura (`duckdb_execute`, `duckdb_upsert`) abren en read-write y SOLO debe usarlas el proceso dueño de la base (dentro de su write lock), nunca un cliente concurrente.
+- **Version del motor**: el formato de archivo puede cambiar entre versiones mayores de DuckDB. El venv del registry lleva `duckdb` 1.5.x; no mezclar con CLIs/WASM antiguos sobre el mismo archivo.
+- `read_only=True` exige que el archivo exista — no crea bases nuevas.
+
+## Fronteras
+
+- NO cubre SQLite (`sqlite_open_go_infra` y el grupo de operations.db van aparte).
+- NO cubre el render de resultados a Markdown/notas — eso es `render_markdown_table_py_core` + `upsert_sentinel_block_py_core` (grupo `obsidian`).
+- El analisis exploratorio pesado (notebooks) vive en `analysis/` con sus propios venvs.
@@ -0,0 +1,64 @@
+# Capability: excel
+
+CRUD de hojas de cálculo Excel (`.xlsx`) desde el registry con openpyxl: escribir libros multi-hoja, actualizar una hoja sin destruir las demás (preservando columnas editadas a mano), leer a estructuras en memoria o a markdown, añadir gráficos nativos, e ingerir una hoja a DuckDB.
+
+Es el extremo Excel del **stack de datos** `Excel → DuckDB → Postgres → visualización`: el Excel sirve como entrada (lo que produce un humano o un export) y como entregable (un libro con gráficos que viaja por email/disco, sin servidor). El round-trip humano lo cubre `upsert_xlsx_sheet`, que conserva las columnas que las personas rellenan a mano mientras regenera las columnas calculadas.
+
+## Funciones
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `write_xlsx_sheets_py_infra` | `write_xlsx_sheets(out_path, sheets, header_bold=True, autofit=True, freeze_header=True) -> str` | Escribe (o sobrescribe) un libro `.xlsx` multi-hoja desde un dict `{nombre_hoja: datos}`. Cada hoja acepta `list[list]` (primera fila = headers) o `{"headers": [...], "rows": [[...]]}`. Cabecera en negrita, auto-ancho, freeze de cabecera. Devuelve la ruta absoluta. |
+| `upsert_xlsx_sheet_py_infra` | `upsert_xlsx_sheet(xlsx_path, sheet_name, records, columns, key_col="", preserve_cols=None, formulas=None, backup=True, ...) -> dict` | Actualiza NO destructivamente UNA hoja: reescribe solo `sheet_name` y conserva las demás. Antes de limpiar, lee por `key_col` las columnas de trabajo manual (`preserve_cols`) y las reescribe ganando sobre los datos nuevos. Cabecera estilizada, freeze, autofilter, fórmulas por columna, backup `.bak`. |
+| `read_xlsx_py_infra` | `read_xlsx(path, sheet=None, max_rows=None, header=True) -> dict` | Lee un `.xlsx` a memoria (NO a markdown). Devuelve `{status, sheets: {nombre: {headers, rows}}}`. `sheet=None` lee todas. Tipos de celda: fechas→ISO, int/float, bool, None, fórmulas (valor calculado, `data_only=True`). Espejo en lectura de `write_xlsx_sheets`. |
+| `excel_to_markdown_py_core` | `excel_to_markdown(path, max_rows_per_sheet=1000) -> str` | Convierte `.xlsx/.xls/.xlsm` a markdown, cada hoja como sección H2. Para inspección rápida / pegar en un prompt o nota. |
+| `add_xlsx_chart_py_infra` | `add_xlsx_chart(xlsx_path, sheet_name, chart_type, data_range, cats_range=None, anchor='H2', title='', x_title='', y_title='') -> dict` | Añade un gráfico nativo (`bar`/`line`/`pie`/`scatter`) a una hoja EXISTENTE, refiriendo rangos de celdas ya escritos (notación Excel `'C1:C7'`). `anchor` = celda destino. La pieza para generar hojas Excel CON gráficos. |
+| `excel_to_duckdb_py_infra` | `excel_to_duckdb(xlsx_path, duckdb_path, table, sheet=None, mode='replace') -> dict` | Ingesta una hoja del `.xlsx` a una tabla DuckDB con la extensión nativa `excel` de DuckDB. Puente Excel→DuckDB. También etiquetada en el grupo `duckdb`. |
+
+## Ejemplo canónico
+
+Escribir un libro, añadirle un gráfico y releerlo a memoria (verificado):
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from infra import write_xlsx_sheets, add_xlsx_chart, read_xlsx
+
+xlsx = "/tmp/ventas.xlsx"
+write_xlsx_sheets(xlsx, {"ventas": [
+    ["mes", "categoria", "importe"],
+    ["2026-01", "neumaticos", 12500.50],
+    ["2026-02", "neumaticos", 15800.75],
+    ["2026-03", "neumaticos", 18200.00],
+]})
+
+# Gráfico de barras del importe por mes, anclado en la celda G2
+add_xlsx_chart(xlsx, "ventas", "bar", data_range="C1:C4", cats_range="A2:A4",
+               anchor="G2", title="Importe por mes", y_title="EUR")
+
+rd = read_xlsx(xlsx, sheet="ventas")
+print(rd["sheets"]["ventas"]["headers"], len(rd["sheets"]["ventas"]["rows"]))
+PYEOF
+```
+
+## Gotchas del grupo
+
+- **openpyxl no evalúa fórmulas.** `read_xlsx` con `data_only=True` devuelve el valor **cacheado** por la última app que guardó el libro (Excel/LibreOffice). Un `.xlsx` con fórmulas escritas por openpyxl y nunca abierto en una hoja de cálculo devuelve `None` en esas celdas.
+- **`add_xlsx_chart` exige libro y hoja existentes:** no crea el `.xlsx` ni escribe datos; los rangos deben apuntar a celdas ya escritas. Flujo: `write_xlsx_sheets` → `add_xlsx_chart`.
+- **Rangos 1-indexed, notación Excel** (`'C1:C7'`). Si `data_range` incluye la fila de cabecera, el nombre de la serie sale de esa celda (`titles_from_data`). `scatter` usa `data_range` como Y y `cats_range` como X; `pie` ignora los títulos de eje.
+- **Carga en memoria:** openpyxl carga el libro entero; para libros muy grandes considera ingerir a DuckDB (`excel_to_duckdb`) y consultar allí.
+- **`upsert_xlsx_sheet` es la vía para datos editados por humanos:** si una persona rellena columnas a mano, pásalas en `preserve_cols` para que un re-volcado no las pise.
+
+## Fronteras
+
+- NO es una herramienta de BI ni de dashboards. Para visualización interactiva/compartida: Metabase, Evidence (sobre DuckDB) o gráficos embebidos con `add_xlsx_chart` para el caso "todo en el .xlsx".
+- El análisis pesado (agregaciones, joins, histórico) NO se hace en Excel: ingiere a DuckDB con `excel_to_duckdb` y usa el grupo `duckdb`.
+- NO cubre `.csv` de entrada con encodings legacy — eso es `safe_read_csv_fallback_py_core`.
+
+## Relación con otros grupos
+
+- `duckdb` — `excel_to_duckdb` es el puente de entrada; el motor analítico vive allí.
+- `postgres` — la salida hacia BI pasa por `duckdb_to_postgres` (grupo `duckdb`/`postgres`).
+- `metabase` — consume los datos una vez en Postgres.
@@ -0,0 +1,83 @@
+# Capability group: `hoppscotch`
+
+Operar una instancia **self-hosted de Hoppscotch** (consola de APIs, alternativa open-source a
+Postman) desde el registry, vía su **API GraphQL**. El agente crea/edita requests, colecciones y
+environments por la API; el humano los ve **en vivo** en su GUI (subscriptions = hot-reload real).
+Las requests viven en la base de datos del self-host (Postgres), compartida entre el agente y la GUI.
+
+Este es el **flujo canónico**. El antiguo modo "archivo `.json` local" (funciones
+`parse_*` / `run_*` / `add_hoppscotch_request`) **fue eliminado**: escribía un `.json` en disco que
+NO subía al workspace, así que el humano no lo veía en la GUI. No lo reintroduzcas.
+
+## Stack self-host
+
+Vive en `projects/web_scraping/hoppscotch/selfhost/` (docker compose: AIO + Postgres + mailpit).
+
+| Servicio | URL | Para qué |
+|---|---|---|
+| App (cliente) | `http://localhost:3009` | la GUI donde el humano usa las colecciones (instalable como PWA) |
+| Admin dashboard | `http://localhost:3100` | gestión (usuarios, config) |
+| Backend GraphQL | `http://localhost:3170/graphql` | la API que usan las funciones |
+| Mailpit | `http://localhost:8025` | captura el magic link del login (SMTP de pruebas, sin correo real) |
+
+Levantar: `cd selfhost && docker compose up -d`. Team de trabajo: **"registry"**. Cuenta: `admin@example.com`.
+
+## Funciones
+
+| ID | Firma corta | Qué hace |
+|---|---|---|
+| `hoppscotch_login_py_infra` | `(email, *, backend_url, mailpit_url) -> {access_token,...}` | login por magic link headless (lee el link de mailpit) → JWT |
+| `hoppscotch_create_request_py_infra` | `(collection_id, method, url, *, title, headers, body, body_type, team_id, access_token) -> dict` | crea una request en una colección de la team |
+| `hoppscotch_update_request_py_infra` | `(request_id, method, url, *, title, headers, body, body_type, access_token) -> dict` | actualiza una request |
+| `hoppscotch_delete_request_py_infra` | `(request_id, *, access_token) -> dict` | borra una request |
+| `hoppscotch_list_requests_py_infra` | `(collection_id, *, access_token) -> {requests:[...]}` | lista las requests de una colección |
+| `hoppscotch_set_environment_py_infra` | `(team_id, name, variables, *, access_token) -> dict` | crea/actualiza (idempotente) el environment de la team; resuelve secretos `pass:` |
+| `build_hoppscotch_collection_py_infra` | `(calls, *, name, request_names) -> dict` | **helper interno** de create/update: serializa call specs al formato HoppRESTRequest. NO para escribir `.json` a mano |
+| `pass_get_secret_py_infra` | `(path, *, line) -> {value}` | lee un secreto de `pass` (lo consume `set_environment` para no hardcodear keys) |
+
+`access_token` se pasa como **cookie**, no header `Authorization`. Caduca a 24h → re-login con `hoppscotch_login`.
+
+## Ejemplo canónico (end-to-end)
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.path.expanduser("~/fn_registry"), "python", "functions"))
+from infra.hoppscotch_login import hoppscotch_login
+from infra.hoppscotch_create_request import hoppscotch_create_request
+from infra.hoppscotch_set_environment import hoppscotch_set_environment
+
+TEAM = "cmq8kn0v500030xls1nvminjy"          # team "registry"
+COLL = "cmq8knppc00040xlskt4ist27"          # colección registry_api (de hoppscotch_list/DB)
+
+tok = hoppscotch_login("admin@example.com")["access_token"]
+
+# 1. Variables del workspace (secreto resuelto desde pass, no hardcodeado)
+hoppscotch_set_environment(TEAM, "registry", [
+    {"key": "baseURL", "value": "https://registry.organic-machine.com", "secret": False},
+    {"key": "api_key", "value": "pass:apis/registry", "secret": True},   # pass: -> pass_get_secret
+], access_token=tok)
+
+# 2. Crear una request → aparece EN VIVO en la GUI del humano (subscriptions)
+hoppscotch_create_request(
+    COLL, "GET", "<<baseURL>>/api/status",
+    title="status", headers={"Accept": "application/json"},
+    team_id=TEAM, access_token=tok,
+)
+```
+
+## Fronteras (qué NO cubre)
+
+- **No es modo archivo**: no escribe colecciones `.json` locales como fuente. Las requests viven en el
+  Postgres del self-host. (Los `.json` en `collections/` son solo respaldo/semilla importable.)
+- **No automatiza la GUI**: opera por la API; la GUI la mira el humano.
+- **No gestiona usuarios/teams del dashboard**: eso es el admin dashboard (`:3100`).
+- **No ejecuta los scripts pre/post-request JS** de Hoppscotch.
+
+## Gotchas
+
+- `access_token` como **cookie** (`cookies={"access_token": tok}`), no `Authorization`. 24h de vida.
+- `createRequestInCollection` de esta instancia **exige `team_id`** en el input (no solo el collectionID).
+- Variables `<<var>>` se resuelven con el environment de la team (subscriptions las propagan a la GUI).
+- Secretos: usa `value="pass:<ruta>"` en `set_environment` → se resuelve de `pass`, nunca se hardcodea
+  ni se logea en crudo.
+- El secreto viaja en claro al backend local por GraphQL — es local (`127.0.0.1`), aceptable.
@@ -0,0 +1,54 @@
+# market-intel
+
+Inteligencia de mercado para captación de clientes: scrapers de señales de demanda y
+tendencias de productos/nichos desde varias fuentes públicas, más vigilancia de precios de
+la competencia, aterrizados en Postgres y analizados con Metabase. Scheduling con
+`dag_engine`. Origen: proyecto `captacion_clientes`.
+
+## Funciones
+
+| ID | Firma corta | Qué hace |
+|---|---|---|
+| `scrape_amazon_bestsellers_py_datascience` | `(marketplace, categories, list_type, max_items)` | Amazon Best Sellers + Movers & Shakers (ranking real de demanda). HTTP, funciona. |
+| `scrape_google_trends_py_datascience` | `(keywords, geo, timeframe, include_related)` | Interés de búsqueda (0-100) + rising/top via pytrends. Backoff ante 429. |
+| `scrape_tiktok_creative_py_datascience` | `(country, kind, limit, period)` | TikTok Creative Center (hashtags/songs/creators). **Bloqueado por anti-bot vía HTTP**; pendiente browser CDP. |
+| `scrape_aliexpress_trending_py_datascience` | `(query, category, limit, ship_to)` | Productos populares AliExpress (orders/rating). **Bloqueado por captcha vía HTTP**; pendiente browser CDP. |
+| `scrape_competitor_prices_py_datascience` | `(targets) -> list[dict]` | Precio actual de una lista de URLs de competidores (cascada: selector → JSON-LD → meta → heurística). |
+| `pg_insert_rows_py_infra` | `(dsn, table, rows, add_snapshot_date=True)` | Insert append-only por lote en Postgres (execute_values parametrizado, añade snapshot_date). |
+| `pg_apply_sql_py_infra` | `(dsn, sql_path) -> int` | Aplica un `.sql` de migración a Postgres (idempotente con IF NOT EXISTS). |
+| `ingest_market_trends_py_pipelines` | `(source)` | Dispatcher: scrapea una fuente y la aterriza en su tabla. Lo invoca `dag_engine`. |
+
+## Ejemplo canónico (end-to-end)
+
+```bash
+# 1. (una vez) Stack Metabase + Postgres en Docker
+fn run init_metabase_go_infra --project captacion --metabase-port 3030 --pg-port 5433 \
+  --pg-user captacion --pg-password "$(pass show captacion/postgres | head -1)"
+docker exec captacion-postgres psql -U captacion -d metabase -c "CREATE DATABASE trends OWNER captacion"
+
+# 2. (una vez) Aplicar el schema
+python3 -c "import sys; sys.path.insert(0,'python/functions'); from infra import pg_apply_sql; \
+  pg_apply_sql('postgresql://captacion:PW@localhost:5433/trends', 'projects/captacion_clientes/db/migrations/001_schema.sql')"
+
+# 3. Ingesta una fuente (manual o vía dag_engine)
+fn run ingest_market_trends_py_pipelines amazon
+fn run ingest_market_trends_py_pipelines google_trends
+
+# 4. dag_engine lo hace solo: dags market-intel-daily (06:30) y competitor-prices-hourly
+```
+
+## Fronteras
+
+- NO hace explotación ni bypass agresivo de anti-bot: TikTok/AliExpress por HTTP-directo
+  caen desde datacenter; la vía robusta es el browser MCP/CDP (grupo `navegator`/`web-proxy`,
+  doctrina `flow_replay.md`), aún no implementada para estas dos fuentes.
+- NO es un grupo de visualización: el análisis vive en Metabase (grupo `metabase`).
+- NO gestiona el scheduling: eso es `dag_engine` (grupo `scheduler`).
+- El DSN de Postgres y credenciales NO se hardcodean: van en `pass`/`.env` del proyecto.
+
+## Notas
+
+- Las tablas de `trends` son append-only particionadas por `snapshot_date` — pensadas para
+  series temporales en Metabase (qué tendencia sube/baja). No correr en bucle apretado.
+- `competitor_prices` se nutre de la tabla `competitor_targets` (el usuario inserta los
+  objetivos a vigilar: competidor + product_key + URL).
@@ -0,0 +1,91 @@
+# Capability: obsidian
+
+CRUD headless de vaults y notas de Obsidian, tratadas como Markdown plano con frontmatter YAML y wikilinks `[[...]]`. El nucleo del grupo manipula los archivos `.md` directamente en disco (no necesita la app GUI). Un sub-conjunto aparte gestiona la **lista de vaults que la app de escritorio Obsidian conoce** (su config `~/.config/obsidian/obsidian.json` + el URI scheme `obsidian://`): `register_*`, `list_registered_*`, `unregister_*`, `open_obsidian_vault`. Scriptable, rapido, con telemetria del registry.
+
+Los vaults de Obsidian del usuario viven en `/home/enmanuel/Obsidian/` y estan enlazados como vaults del registry en el project `obsidian` (`projects/obsidian/vaults/`). Ver `projects/obsidian/project.md`.
+
+## Funciones
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `parse_obsidian_frontmatter_py_obsidian` | `parse_obsidian_frontmatter(content: str) -> {"frontmatter": dict, "body": str}` | **Pure.** Separa el frontmatter YAML (bloque `---` inicial) del cuerpo. Si no hay frontmatter valido devuelve `{}` + el contenido completo. |
+| `extract_obsidian_wikilinks_py_obsidian` | `extract_obsidian_wikilinks(body: str) -> list` | **Pure.** Extrae los targets de los wikilinks `[[...]]` y embeds `![[...]]`. Normaliza `[[nota\|alias]]`, `[[nota#heading]]`, `[[nota#^block]]` -> `nota`. Dedup preservando orden. |
+| `format_obsidian_note_py_obsidian` | `format_obsidian_note(frontmatter: dict, body: str) -> str` | **Pure.** Inversa de parse: serializa frontmatter (YAML entre `---`) + body a una nota `.md` completa. |
+| `read_obsidian_note_py_obsidian` | `read_obsidian_note(path: str) -> dict` | Lee una nota: `{path, frontmatter, body, wikilinks, tags}`. Compone parse + extract. |
+| `create_obsidian_note_py_obsidian` | `create_obsidian_note(vault_dir, rel_path, body="", frontmatter=None, overwrite=False) -> str` | Crea nota nueva (crea dirs padre, añade `.md`). Error si existe y `overwrite=False`. |
+| `update_obsidian_note_py_obsidian` | `update_obsidian_note(path, body=None, set_frontmatter=None, append=None) -> str` | Edita nota existente: merge de frontmatter, reemplazo de body, o append al final. |
+| `delete_obsidian_note_py_obsidian` | `delete_obsidian_note(path: str) -> bool` | Borra una nota (solo archivo, nunca directorio). Error si no existe. |
+| `list_obsidian_notes_py_obsidian` | `list_obsidian_notes(vault_dir, subfolder="", tag="") -> list` | Lista paths de notas `.md` (recursivo). Excluye `.obsidian/` y `.trash/`. Filtro opcional por tag de frontmatter. |
+| `search_obsidian_notes_py_obsidian` | `search_obsidian_notes(vault_dir, query, in_body=True, in_frontmatter=True) -> list` | Busca substring (case-insensitive) en las notas. Devuelve `[{path, matches:[{line, text}]}]`. |
+| `list_obsidian_vaults_py_obsidian` | `list_obsidian_vaults(base_dir: str) -> list` | Lista los vaults (subdirs con `.obsidian/`) bajo `base_dir`. `[{name, path}]`. |
+| `create_obsidian_vault_py_obsidian` | `create_obsidian_vault(parent_dir, name) -> str` | Crea un vault nuevo: carpeta + `.obsidian/app.json` minimo. Error si ya existe. |
+| `register_obsidian_vault_py_obsidian` | `register_obsidian_vault(vault_path, open=False, config_path="") -> dict` | Da de alta un vault en la **app** Obsidian (entrada en `~/.config/obsidian/obsidian.json`). Idempotente por path, backup `.bak`, preserva el resto del JSON. NO toca el filesystem del vault. |
+| `list_registered_obsidian_vaults_py_obsidian` | `list_registered_obsidian_vaults(config_path="") -> list` | Lista los vaults que la **app** Obsidian conoce (de `obsidian.json`), ordenados por path. `[{id, path, open, ts}]`. Distinto de `list_obsidian_vaults` (que escanea el filesystem). |
+| `unregister_obsidian_vault_py_obsidian` | `unregister_obsidian_vault(vault_ref, config_path="") -> dict` | Quita un vault de la lista de la **app** Obsidian (por id o por path). NO borra la carpeta del vault. Backup `.bak`, preserva el resto del JSON. |
+| `open_obsidian_vault_py_obsidian` | `open_obsidian_vault(vault, register_if_missing=True, launch=True, config_path="") -> dict` | Abre un vault en la **app** Obsidian via `obsidian://open?vault=<name>` (lanza `xdg-open`). Registra el vault antes si falta. `launch=False` solo construye el URI. |
+| `slugify_obsidian_name_py_obsidian` | `slugify_obsidian_name(name: str) -> str` | **Pure.** Nombre/titulo -> slug kebab-case estable (translitera acentos, ñ->n). Estabiliza ids de nodo y nombres de archivo. |
+| `extract_obsidian_embeds_py_obsidian` | `extract_obsidian_embeds(body: str) -> list` | **Pure.** Solo los embeds `![[...]]` (attachments incrustados), ignorando wikilinks normales. Dedup preservando orden. |
+| `resolve_obsidian_embed_py_obsidian` | `resolve_obsidian_embed(vault_dir, embed_name) -> str` | Resuelve un embed `![[foto.jpg]]` a su path absoluto real (busca por basename unico en el vault). Cadena vacia si no existe. |
+| `build_obsidian_graph_py_obsidian` | `build_obsidian_graph(vault_dir, include_dangling=True) -> {"nodes":[...], "edges":[...]}` | **Grafo agregado** del vault: cada nota = nodo tipado (`id`=slug, `label`, `tipo`, `frontmatter`); cada wikilink `[[...]]` = arista con `kind` por seccion. Wikilinks rotos -> nodos fantasma `dangling`. |
+| `render_markdown_table_py_core` | `render_markdown_table(rows: list[dict], columns=None, max_rows=0) -> str` | **Pure** (vive en `core`). Lista de dicts -> tabla Markdown GFM. Escapa pipes, saltos de linea -> `<br>`, truncado opcional con pie `... N de M filas`. Base del render BD -> nota. |
+| `upsert_sentinel_block_py_core` | `upsert_sentinel_block(text, block_id, content, marker="osintdb") -> str` | **Pure** (vive en `core`). Inserta o reemplaza un bloque gestionado entre sentinels `<!-- marker:begin id=X -->` / `<!-- marker:end id=X -->` dentro del body de una nota. Idempotente; ValueError si el bloque esta corrupto. |
+
+## Ejemplo canonico
+
+Componer varias funciones del grupo se hace por heredoc importando del registry (las funciones se importan, no se reescriben):
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from obsidian import (
+    list_obsidian_vaults, list_obsidian_notes, search_obsidian_notes,
+    create_obsidian_note, read_obsidian_note, update_obsidian_note, delete_obsidian_note,
+)
+
+# 1. Descubrir vaults del usuario
+vaults = list_obsidian_vaults("/home/enmanuel/Obsidian")
+print("vaults:", [v["name"] for v in vaults])
+
+# 2. Listar y buscar notas en un vault
+finanzas = "/home/enmanuel/Obsidian/Finanzas"
+print("notas:", len(list_obsidian_notes(finanzas)))
+print("hits:", [h["path"] for h in search_obsidian_notes(finanzas, "presupuesto")][:5])
+
+# 3. CRUD de una nota (crear -> leer -> editar -> borrar)
+p = create_obsidian_note(finanzas, "inbox/idea_x", body="Primera linea",
+                         frontmatter={"tags": ["inbox"], "created": "2026-06-09"})
+note = read_obsidian_note(p)
+print("creada:", note["path"], note["frontmatter"], note["wikilinks"])
+update_obsidian_note(p, set_frontmatter={"status": "done"}, append="Ver [[Otra Nota]]")
+delete_obsidian_note(p)
+PYEOF
+```
+
+Para una sola operacion con un id conocido, `fn run` tambien sirve:
+
+```bash
+./fn run list_obsidian_vaults /home/enmanuel/Obsidian
+./fn run list_obsidian_notes /home/enmanuel/Obsidian/Finanzas
+```
+
+## Cuando usar el grupo
+
+- Crear/editar/leer notas de cualquier vault de Obsidian desde un agente o script, sin abrir la app.
+- Buscar o listar notas por contenido o tag (ingesta, migracion, reporting sobre el vault).
+- Crear vaults nuevos o inventariar los existentes.
+
+## Fronteras (que NO cubre)
+
+- **El CRUD de notas no habla con la app GUI** (no abre notas en la interfaz ni dispara plugins). Si la app esta abierta, escribir en disco puede chocar con sus locks/cache — cerrar la app o refrescar manualmente. La unica interaccion con la app es la **gestion de su lista de vaults** (`register_*`/`unregister_*`/`list_registered_*` sobre `obsidian.json`) y `open_obsidian_vault` (lanza el URI `obsidian://`); estas no editan notas ni renderizan nada.
+- **Single-instance gotcha**: Obsidian cachea su `obsidian.json` en memoria al arrancar. Registrar/desregistrar un vault con la app abierta no se reflejara hasta reiniciarla; `open_obsidian_vault` sobre un vault recien registrado puede dar "unable to find a vault" hasta el reinicio.
+- **No resuelve wikilinks a paths** automaticamente (devuelve los targets crudos). Resolver `[[nota]]` -> archivo real es responsabilidad del caller (busqueda por nombre en el vault).
+- **No renderiza Markdown** ni evalua Dataview/templating. Trata las notas como texto + frontmatter.
+- **El grafo agregado** del vault ya lo cubre `build_obsidian_graph_py_obsidian` (nodos tipados + aristas con `kind` + nodos fantasma `dangling`). Es la base de la vista grafo (sigma.js) de la app `osint_web`. Lo que sigue fuera del grupo es el *layout* visual del grafo (force-directed) — eso vive en el frontend.
+
+## Gotchas
+
+- Vaults grandes son caros: `NotasDeObsidian` pesa ~554M. `list_obsidian_notes` / `search_obsidian_notes` recorren todo el arbol — filtra por `subfolder` cuando puedas.
+- `delete_obsidian_note` borra de verdad (no manda a `.trash/`). Para acciones destructivas masivas, listar primero y confirmar.
+- El frontmatter `tags` puede venir como lista o como CSV string; `read_obsidian_note` lo normaliza a lista.
@@ -0,0 +1,79 @@
+# Capability group: onlyoffice
+
+Operar **ONLYOFFICE Desktop Editors** (binario `/usr/bin/onlyoffice-desktopeditors`) en Linux/X11 desde terminal, gestionando la **ventana** de los archivos sin perturbar la instancia personal del usuario.
+
+Este grupo NO es el ONLYOFFICE **Document Server** (web/Docker) — para eso ver `start_documentserver_bash_infra`, `documentserver_health_go_infra`, `onlyoffice_command_service_go_infra` y compañia. Este grupo es el editor de **escritorio**.
+
+## Convencion de instancia aislada (slot)
+
+ONLYOFFICE Desktop es **single-instance por usuario**: un segundo `onlyoffice-desktopeditors <file>` se reenvia a la instancia viva y abre el archivo como PESTAÑA en su ventana, no como ventana nueva. El lock single-instance NO se rompe con `XDG_CONFIG_HOME`, pero SI se rompe lanzando con `HOME` y `XDG_RUNTIME_DIR` propios.
+
+Por eso las 3 funciones comparten un "slot" nombrado por `instance` (string, default `demo`):
+
+```
+HOME=/tmp/oo_<instance>
+XDG_RUNTIME_DIR=/tmp/oo_<instance>_run      (mkdir -p + chmod 700)
+XDG_CONFIG_HOME=/tmp/oo_<instance>/.config
+```
+
+Lanzamiento canonico (identico en open y reload):
+
+```bash
+env HOME=/tmp/oo_<instance> XDG_RUNTIME_DIR=/tmp/oo_<instance>_run \
+    XDG_CONFIG_HOME=/tmp/oo_<instance>/.config \
+    setsid onlyoffice-desktopeditors <file> >/tmp/oo_<instance>.log 2>&1 </dev/null &
+```
+
+Usar el MISMO `instance` en todas las operaciones del slot: asi el relaunch reenvia a la instancia aislada viva y reabre rapido en vez de arrancar el motor de cero.
+
+## Funciones
+
+| ID | Firma corta | Que hace |
+|---|---|---|
+| `open_onlyoffice_file_bash_shell` | `open_onlyoffice_file <file> [instance]` | Abre un archivo existente en el slot aislado; espera la ventana por basename (~25s); JSON con wid/status. Idempotente, NO crea archivos. |
+| `reload_onlyoffice_file_bash_shell` | `reload_onlyoffice_file <file> [instance]` | **Funcion estrella**: cierra (wmctrl -ic) y reabre el archivo en el slot para mostrar datos editados EN DISCO (ONLYOFFICE no tiene reload nativo, Issue #2313). JSON con wid_old/wid_new/elapsed_s/status. NO edita el archivo. |
+| `close_onlyoffice_instance_bash_shell` | `close_onlyoffice_instance [instance] [--purge]` | Mata los procesos DesktopEditors del slot (por HOME=/tmp/oo_<instance> en /proc), SIGTERM->SIGKILL; con --purge borra /tmp/oo_<instance>*. JSON con killed_pids/status. |
+
+## Ejemplo canonico (end-to-end)
+
+Flujo completo "abrir -> editar el archivo en disco -> recargar la vista -> cerrar", todo sobre un slot aislado `demo` que no toca la instancia personal del usuario:
+
+```bash
+cd /home/enmanuel/fn_registry
+
+# 0. El caller prepara el archivo (esta funcion NO crea archivos)
+printf 'a,b\n1,2\n' > /tmp/demo_reload.csv
+
+# 1. Abrir en el slot aislado 'demo' -> ventana propia
+./fn run open_onlyoffice_file_bash_shell /tmp/demo_reload.csv demo
+# {"instance":"demo","file":"/tmp/demo_reload.csv","wid":"0x3c00007","pid":12345,"status":"open"}
+
+# 2. El caller edita el archivo EN DISCO (script, generador, otra herramienta)
+printf 'a,b\n1,2\n3,4\n5,6\n' > /tmp/demo_reload.csv
+
+# 3. Recargar la ventana para que muestre los datos nuevos (cierra+reabre)
+./fn run reload_onlyoffice_file_bash_shell /tmp/demo_reload.csv demo
+# {"instance":"demo","file":"/tmp/demo_reload.csv","wid_old":"0x3c00007","wid_new":"0x3c0000b","reopened":true,"elapsed_s":4,"status":"reloaded"}
+
+# 4. Cerrar la instancia aislada y limpiar su estado
+./fn run close_onlyoffice_instance_bash_shell demo --purge
+# {"instance":"demo","killed_pids":[12345],"purged":true,"status":"closed"}
+```
+
+## Fronteras (que NO hace el grupo)
+
+- **NO edita ni crea archivos**. Solo gestiona la VENTANA (abrir, cerrar+reabrir, matar proceso). El contenido lo prepara y modifica el caller en disco.
+- **NO es el Document Server** (web/Docker/JWT/Command Service). Eso es otro conjunto de funciones (`*documentserver*`, `*onlyoffice_jwt*`, `onlyoffice_command_service_*`).
+- **NO recarga in-place**: ONLYOFFICE Desktop no soporta reload de cambios externos (Issue #2313 abierto). `reload_onlyoffice_file` lo emula con cerrar+reabrir; no hay alternativa "sin parpadeo".
+- **NO toca la instancia personal del usuario**: todo opera sobre el slot aislado (HOME=/tmp/oo_<instance>). `close` solo mata procesos cuyo HOME es del slot.
+
+## Prerequisitos
+
+- Linux con **X11** (o XWayland). En Wayland puro sin XWayland, `xdotool`/`wmctrl` no encuentran la ventana.
+- Binarios en PATH: `onlyoffice-desktopeditors`, `wmctrl`, `xdotool`. Cada funcion comprueba `command -v` y falla con exit !=0 si falta alguno.
+
+## Notas
+
+- Las esperas son **por evento** (`xdotool search` + `read -t`), nunca `sleep` en foreground, para no colgar bajo `fn run` ni tests.
+- El slot vive en `/tmp` y se pierde al reiniciar el PC (estado desechable). `--purge` lo borra explicitamente.
+- `wmctrl -ic` puede disparar el dialogo "Guardar cambios" SOLO si se edito dentro de la app con cambios sin guardar; el flujo previsto edita en disco, asi que la ventana no tiene estado pendiente.
@@ -0,0 +1,51 @@
+# Capability: osint-enrich
+
+Orquestadores de enriquecimiento OSINT: componen las funciones atómicas de
+[osint-passive](osint-passive.md) para aumentar los datapoints de una entidad (persona u
+organización) del vault `osint` a partir de fuentes públicas. No tocan al objetivo de forma
+intrusiva. Mismo encuadre dual-use que `osint-passive`: solo investigación autorizada.
+
+## Funciones
+
+| ID | Firma | Qué hace |
+|---|---|---|
+| `scan_ficha_attachments_metadata_py_cybersecurity` | `scan_ficha_attachments_metadata(attachments_dir) -> dict` | Escanea los attachments de una ficha (imágenes + PDFs), extrae EXIF/PDF metadata y agrega GPS y fechas. |
+| `enrich_person_passive_py_cybersecurity` | `enrich_person_passive(nombre, apellidos, dominios=None, usernames=None) -> dict` | Candidatos para una persona: emails (guess), username hits, dorks. No verifica ni ejecuta. |
+| `enrich_org_passive_py_cybersecurity` | `enrich_org_passive(dominio) -> dict` | Perfil pasivo de una org: whois + dns + subdominios. Resiliente a fallo parcial (campo `errors`). |
+
+## Ejemplo canónico
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys; sys.path.insert(0, "python/functions")
+from cybersecurity import (scan_ficha_attachments_metadata,
+                           enrich_person_passive, enrich_org_passive)
+
+# 1. Metadatos de los documentos ya guardados de una persona (datos propios)
+m = scan_ficha_attachments_metadata(
+    "/home/enmanuel/Obsidian/osint/attachments/personas/enmanuel-gutierrez-perez")
+print(m["summary"])              # {n_files, n_images, n_pdfs, n_gps_points, n_dates, errors}
+
+# 2. Candidatos de enriquecimiento de una persona (no toca al objetivo)
+p = enrich_person_passive("Enmanuel", "Gutierrez Perez",
+                          dominios=["gmail.com"], usernames=["enmanuelgp"])
+print(p["email_candidates"][:5], len(p["dorks"]))
+
+# 3. Perfil pasivo de una organización por su dominio
+o = enrich_org_passive("organic-machine.com")
+print(o["whois"].get("registrar"), o["dns"].get("A"), len(o["subdomains"]), o["errors"])
+PYEOF
+```
+
+## Fronteras
+
+- Compone solo funciones `osint-passive`. Para activa (port scan, fingerprint) haría falta
+  `osint-active` (no construido).
+- Devuelve candidatos/datos crudos; **decidir qué escribir en la ficha** (y verificar) es del
+  caller. Encaja con el reporte de `projects/osint/tools/person_datapoints.py`.
+
+## Gotchas
+
+- `enrich_org_passive` nunca peta por una fuente lenta (crt.sh): el fallo va a `errors`.
+- `enrich_person_passive` puede tardar por `enumerate_username_sites` (un request por sitio).
@@ -0,0 +1,64 @@
+# Capability: osint-passive
+
+Recolección OSINT **pasiva**: obtener información sin interactuar de forma intrusiva con el
+objetivo, usando solo fuentes públicas (DNS público, RDAP, Certificate Transparency, metadatos
+de documentos propios, servicios de perfil públicos). Pensado para investigación autorizada,
+due diligence, pentest con permiso y enriquecimiento de las fichas del vault `osint`.
+
+**Encuadre:** dual-use. Úsese solo contra objetivos propios o con autorización. Las funciones
+que tocan servicios públicos (`enumerate_username_sites`, `enum_subdomains_crtsh`) dejan una
+huella mínima (un request a cada servicio); respeta sus rate limits.
+
+## Funciones
+
+| ID | Firma | Qué hace |
+|---|---|---|
+| `extract_exif_metadata_py_cybersecurity` | `extract_exif_metadata(image_path) -> dict` | EXIF de una imagen (fecha, cámara, software, GPS decimal) vía Pillow. |
+| `extract_pdf_metadata_py_cybersecurity` | `extract_pdf_metadata(pdf_path) -> dict` | Document Info de un PDF (autor, fechas, software, páginas) vía pypdf. |
+| `guess_email_formats_py_cybersecurity` | `guess_email_formats(nombre, apellidos, dominio) -> list` | **Pure.** Candidatos de email comunes a partir de nombre + dominio. |
+| `enumerate_username_sites_py_cybersecurity` | `enumerate_username_sites(username, ...) -> list` | ¿Existe un username en ~12 redes públicas? (sherlock ligero, por código HTTP). |
+| `build_search_dorks_py_cybersecurity` | `build_search_dorks(target, tipo, ...) -> list` | **Pure.** Genera dorks de motor de búsqueda (persona/email/dominio/usuario). |
+| `dns_records_py_cybersecurity` | `dns_records(dominio, types=None) -> dict` | Registros DNS (A/AAAA/MX/TXT/NS/CNAME) vía `dig`. |
+| `whois_lookup_py_cybersecurity` | `whois_lookup(dominio, ...) -> dict` | Datos de registro vía RDAP (WHOIS moderno HTTP/JSON, sin CLI). |
+| `enum_subdomains_crtsh_py_cybersecurity` | `enum_subdomains_crtsh(dominio, ...) -> list` | Subdominios desde Certificate Transparency (crt.sh). |
+
+Orquestadores (grupo [osint-enrich](osint-enrich.md)): `scan_ficha_attachments_metadata`,
+`enrich_person_passive`, `enrich_org_passive`.
+
+## Ejemplo canónico
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys; sys.path.insert(0, "python/functions")
+from cybersecurity import (dns_records, whois_lookup, enum_subdomains_crtsh,
+                           guess_email_formats, build_search_dorks, extract_exif_metadata)
+
+# Dominio (org)
+print(whois_lookup("organic-machine.com")["registrar"])      # OVH sas
+print(dns_records("organic-machine.com")["A"])                # ['135.125.201.30']
+print(enum_subdomains_crtsh("organic-machine.com")[:5])
+
+# Persona
+print(guess_email_formats("Enmanuel", "Gutierrez Perez", "gmail.com")[:5])
+print(build_search_dorks("Enmanuel Gutierrez Perez", "persona")[:3])
+
+# Metadatos de un documento propio
+print(extract_exif_metadata("/home/enmanuel/Obsidian/osint/attachments/personas/enmanuel-gutierrez-perez/dni-1.jpg"))
+PYEOF
+```
+
+## Fronteras (qué NO es)
+
+- **No es recolección activa**: no hace port scan, dns brute, ni sondea la infra del objetivo.
+  Eso sería el grupo `osint-active` (no construido todavía).
+- **No verifica** los candidatos: `guess_email_formats` propone, no confirma que el email exista.
+- **No ejecuta** los dorks: `build_search_dorks` los genera; ejecutarlos es otro paso (browser).
+- **No incluye breach/leak lookup** (HIBP requiere API key de pago) — pendiente.
+
+## Gotchas
+
+- `crt.sh` va lento / rate-limitado y a veces responde 404; los orquestadores lo capturan en
+  `errors` y siguen.
+- `enumerate_username_sites` da falsos positivos/negativos por anti-bot de algunos sitios.
+- El GPS de EXIF revela ubicación — dato sensible; trátese como PII.
@@ -0,0 +1,61 @@
+# Capability: postgres
+
+CRUD de PostgreSQL desde el registry. Las funciones Python (psycopg2) reciben un `dsn: str`, son impuras y devuelven un dict `{status:'ok'|'error', ...}` sin lanzar (mismo estilo que el grupo `duckdb`); la función Go (`postgres_open`) abre un `*sql.DB` desde parámetros individuales.
+
+Postgres es la **capa que sirve datos a las herramientas de BI** del stack (`Excel → DuckDB → Postgres → visualización`). Metabase, Grafana y Superset NO hablan DuckDB de forma nativa, pero todas hablan PostgreSQL: por eso el motor analítico de trabajo es DuckDB y, cuando un dashboard tiene que consumir esos datos, se sincronizan a Postgres con `duckdb_to_postgres` (grupo `duckdb`).
+
+## Funciones
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `postgres_open_go_infra` | `PostgresOpen(host, port, user, password, dbname, sslmode) (*sql.DB, error)` | Conecta a PostgreSQL desde Go construyendo el DSN. `sslmode` por defecto `disable`. |
+| `pg_query_py_infra` | `pg_query(dsn, sql, params=None, max_rows=10000) -> dict` | SELECT read-only (`SET TRANSACTION READ ONLY`) con `RealDictCursor`. Devuelve `{status, columns, rows, row_count, truncated}`. Normaliza tipos no JSON (date/datetime→ISO, Decimal→float, bytes→base64, UUID→str). Espejo de `duckdb_query_readonly`. Valores por `%s`. |
+| `pg_insert_rows_py_infra` | `pg_insert_rows(dsn, table, rows, add_snapshot_date=True) -> int` | INSERT append-only en lote (`execute_values`). Deriva columnas de las claves. Opcional `snapshot_date = date.today()`. Retorna nº de filas. |
+| `pg_upsert_py_infra` | `pg_upsert(dsn, table, rows, key_cols, update_cols=None) -> dict` | UPSERT idempotente `INSERT ... ON CONFLICT (key_cols) DO UPDATE SET col=EXCLUDED.col`. `update_cols` = ownership selectivo (las no listadas conservan su valor); `[]` = DO NOTHING. Devuelve `{status, inserted, updated}`. `key_cols` deben tener PK/UNIQUE. Espejo de `duckdb_upsert`. |
+| `pg_create_table_from_rows_py_infra` | `pg_create_table_from_rows(dsn, table, rows, primary_key=None) -> dict` | `CREATE TABLE IF NOT EXISTS` infiriendo columnas y tipos desde los valores (bool→BOOLEAN, int→BIGINT, float→DOUBLE PRECISION, datetime→TIMESTAMP, date→DATE, resto→TEXT). Idempotente. Devuelve `{status, created, table, columns}`. |
+| `pg_list_tables_py_infra` | `pg_list_tables(dsn, schema='public') -> dict` | Introspección read-only: tablas base con sus columnas vía `information_schema`. Devuelve `{status, schema, tables:[{name, columns:[{name,type,nullable}]}]}`. |
+| `pg_apply_sql_py_infra` | `pg_apply_sql(dsn, sql_path) -> int` | Ejecuta un archivo `.sql` completo (multi-statement, una transacción). Para migraciones idempotentes (`IF NOT EXISTS`). |
+
+Relacionadas (otros grupos): `duckdb_to_postgres_py_pipelines` (sincroniza una tabla DuckDB a Postgres) e `init_metabase_go_infra` (despliega el stack Metabase + Postgres en Docker).
+
+## Ejemplo canónico
+
+Crear una tabla inferida, hacer upsert idempotente y consultar (DSN desde `pass`):
+
+```bash
+cd /home/enmanuel/fn_registry
+DSN="postgresql://captacion:$(pass captacion/postgres | head -1)@localhost:5433/trends"
+python/.venv/bin/python3 - "$DSN" <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from infra import pg_create_table_from_rows, pg_upsert, pg_query
+
+dsn = sys.argv[1]
+rows = [{"mes": "2026-01", "total": 12500.5}, {"mes": "2026-02", "total": 15800.75}]
+
+pg_create_table_from_rows(dsn, "demo_kpi", rows, primary_key=["mes"])
+print(pg_upsert(dsn, "demo_kpi", rows, key_cols=["mes"]))          # inserted/updated
+print(pg_upsert(dsn, "demo_kpi", rows, key_cols=["mes"]))          # idempotente: 0 inserts
+print(pg_query(dsn, "SELECT * FROM demo_kpi ORDER BY mes")["rows"])
+PYEOF
+```
+
+## Gotchas del grupo
+
+- **El DSN lleva credenciales — nunca hardcodear.** Resuélvelo desde `pass` (ej. `pass captacion/postgres`: L1 = password, resto `user/host/port/datadb`). No imprimas el DSN en logs.
+- **`pg_query`/`pg_list_tables` son read-only por convención** (`SET TRANSACTION READ ONLY` + rollback), protegen la base pero NO son sandbox; los identificadores (tabla/schema) NO se parametrizan — los valores sí (`%s`). Las funciones validan identificadores con `^[A-Za-z_][A-Za-z0-9_]*$`.
+- **`pg_upsert` cuenta insert vs update con el pseudo-columna `xmax`** (`RETURNING (xmax = 0)`). Fiable en el caso normal (single-writer, sin triggers raros). Con `update_cols=[]` (DO NOTHING) las filas en conflicto no se devuelven, así que solo se cuentan las nuevas. BEFORE-triggers / REPLICA IDENTITY pueden desviar el conteo.
+- **`pg_create_table_from_rows` no reconcilia schema:** si la tabla ya existe, `columns` reporta los tipos inferidos de las filas, no los reales. Inferencia best-effort sin NUMERIC/escala — para dinero define el schema a mano con `pg_apply_sql`.
+- **`pg_insert_rows` y `pg_apply_sql` lanzan en error** (no devuelven dict); envuélvelas si compones.
+
+## Fronteras
+
+- NO es el motor analítico del stack — ese es DuckDB (columnar, lee CSV/Parquet/Excel nativo). Postgres es el destino para BI.
+- NO dibuja dashboards: eso es Metabase / Grafana / Evidence leyendo de Postgres.
+- NO cubre PostGIS más allá de `osm2pgsql_ingest_py_infra` (geo, aparte).
+
+## Relación con otros grupos
+
+- `duckdb` — `duckdb_to_postgres` es el puente de entrada de datos a esta capa.
+- `metabase` — registra la base con `metabase_add_database(engine='postgres', ...)` y consume las tablas.
+- `excel` — el origen de los datos suele ser un `.xlsx` ingerido por `excel_to_duckdb`.
@@ -0,0 +1,195 @@
+# Capability: recon
+
+Reconocimiento de red para OSINT desde el registry: lookups de registro (WHOIS/RDAP), DNS, sondeo de disponibilidad y ruta (ping/traceroute), escaneo de puertos y servicios, y fingerprint de la tecnologia web de un sitio (estilo Wappalyzer). El escaneo de puertos tiene dos caminos: el wrapper pesado de `nmap` (perfiles, scripts NSE, versiones), y un **camino nativo en Python puro** (`scan_tcp_ports` + `grab_service_banner` + `identify_port_service`, solo stdlib, sin nmap ni sudo) para escaneo rapido y portable. El fingerprint web sigue el mismo patron pura/impura: `fetch_http_fingerprint` recoge las señales (headers, html, cookies) y `detect_web_tech` (pura) matchea firmas para identificar servidor, CMS, frameworks JS, analytics y CDN. La mayoria de funciones son Python impuras, wrappean CLIs del sistema (`whois`, `rdap`, `dig`, `ping`, `traceroute`, `nmap`) o usan sockets/urllib stdlib, y devuelven siempre un dict `{status: ok|error}` sin lanzar excepciones. El grupo cierra el bucle con un **sink comun** que archiva cada escaneo en el ecosistema OSINT (nota Obsidian + registro DuckDB) y pipelines one-shot que escanean y guardan en una sola llamada.
+
+Comparte tag y dominio (`cybersecurity`) con el grupo `osint-passive` (recoleccion no intrusiva desde fuentes publicas), del que reutiliza primitivas. La regla de operacion es la misma del project `osint`: **todo escaneo se archiva en OSINT**.
+
+## Funciones
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `whois_lookup_py_cybersecurity` | `whois_lookup(target, timeout_s=30) -> dict` | Lookup WHOIS via el CLI `whois`. Captura el `raw` completo y parsea best-effort registrar, registrant_country, creation_date, expiry_date, updated_date, name_servers. Acepta dominio o IP. |
+| `rdap_lookup_py_cybersecurity` | `rdap_lookup(target, timeout_s=30) -> dict` | Lookup RDAP (reemplazo JSON moderno de WHOIS) via el CLI openrdap `rdap`. Devuelve `data` (dict JSON), `handle`, `ldhName` y el `raw`. Acepta dominio, IP o ASN (`AS15169`). |
+| `dns_records_py_cybersecurity` | `dns_records(domain, record_types=None, timeout_s=20) -> dict` | Registros DNS via `dig +short` (default A, AAAA, MX, NS, SOA, TXT, CNAME). Devuelve `records` (dict por tipo) y `raw` legible por bloque para el vault. |
+| `ping_host_py_cybersecurity` | `ping_host(host, count=4, timeout_s=30) -> dict` | Sondeo ICMP via `ping`. Devuelve `loss_pct`, `rtt_avg_ms` (y min/max), `packets_sent`/`recv`, `raw`. Host filtrado = `status:ok` con `loss_pct=100`, no error. |
+| `traceroute_host_py_cybersecurity` | `traceroute_host(host, max_hops=30, timeout_s=60) -> dict` | Traza la ruta via `traceroute`. Devuelve `hops` (lista de `{hop, hosts:[{name, ip, rtt_ms}]}`) y `raw`. Hops filtrados (`* * *`) = `hosts: []`. |
+| `nmap_scan_py_cybersecurity` | `nmap_scan(target, profile="quick", ports=None, extra_args=None, out_dir=None, timeout_s=1800) -> dict` | Escaneo de puertos/servicios via `nmap` por perfiles (salida XML parseada). Devuelve `open_ports`, `hosts_up`, `xml_path`, `raw`, `elapsed_s`. Funcion estrella del grupo. |
+| `scan_tcp_ports_py_cybersecurity` | `scan_tcp_ports(host, ports="common", timeout_s=1.0, workers=100) -> dict` | **Connect-scan TCP nativo (stdlib, sin nmap ni sudo).** Escanea puertos en paralelo con threads y clasifica cada uno en open/closed/filtered. `ports` acepta lista, preset `"common"`, rango `"1-1024"` o CSV. Devuelve `open` (lista de ints), `ip`, `raw`. NO detecta version de servicio. |
+| `grab_service_banner_py_cybersecurity` | `grab_service_banner(host, port, timeout_s=3.0, send_probe=True) -> dict` | **Banner grab nativo (stdlib, sin nmap -sV).** Abre socket TCP, lee el banner e identifica el servicio real (ssh, http, ftp, smtp, mysql, redis, pop3, imap, telnet...) extrayendo `product` y `version` best-effort. Dice QUE habla detras de un puerto abierto. TLS/HTTPS no da banner plano. |
+| `identify_port_service_py_cybersecurity` | `identify_port_service(port, proto="tcp") -> dict` | **Pure.** Mapea un puerto a su servicio IANA well-known esperado por convencion (`{service, description, known}`) desde una tabla embebida (~120 puertos). No sondea en vivo: dice que se ESPERA, no que hay. |
+| `save_scan_to_osint_py_cybersecurity` | `save_scan_to_osint(target, scan_type, raw, summary=None, vault_dir="~/Obsidian/osint", service_url="http://127.0.0.1:8771", tool=None) -> dict` | **Sink OSINT.** Archiva un scan: nota Markdown tipada en el vault (capa critica) + POST a `osint_db` para registro DuckDB (best-effort). Devuelve `note_path`, `registered`, `scan_id`. |
+| `recon_osint_py_pipelines` | `recon_osint(target, scan_type="whois", save=True, profile="quick", ...) -> dict` | **Pipeline one-shot.** Ejecuta un scan del tipo pedido y lo archiva en OSINT en una sola llamada (compone la funcion de scan + `save_scan_to_osint`). El camino canonico para recon + archivado. |
+| `scan_port_services_py_pipelines` | `scan_port_services(host, ports="common", timeout_s=1.0, workers=100, grab_banners=True, banner_timeout_s=3.0, save=True) -> dict` | **Pipeline one-shot nativo.** Escanea puertos y, por cada abierto, devuelve servicio esperado (IANA) + servicio/version real del banner. Compone `scan_tcp_ports` + `identify_port_service` + `grab_service_banner` (+ sink OSINT). Reemplaza el patron scan→identify→grab sin nmap. |
+| `fetch_http_fingerprint_py_cybersecurity` | `fetch_http_fingerprint(url, timeout_s=15.0, verify_tls=True, max_html_bytes=500000, user_agent=None) -> dict` | **Fetch de señales web (stdlib).** GET con UA de navegador, sigue redirects, descomprime gzip. Devuelve `headers` (lowercase), `cookies` (solo NOMBRES, sin valores), `html`, `title`, `server`, `status_code`, `final_url`, `raw`. Capa impura del fingerprint web. |
+| `detect_web_tech_py_cybersecurity` | `detect_web_tech(headers, html="", cookies=None, final_url="") -> dict` | **Pure. Detector de tecnologia web estilo Wappalyzer.** Matchea ~50 firmas embebidas (regex) contra headers/html/cookies → `technologies[{name, category, version, confidence, evidence}]`, `by_category`, `count`. Cubre server, lenguaje, CMS, frameworks JS, librerias, analytics, CDN, e-commerce, WAF. |
+| `fetch_http_fingerprint_cdp_py_browser` | `fetch_http_fingerprint_cdp(url, *, port=9222, wait_render_s=2.0, timeout_s=30.0, close_tab=True) -> dict` | **Fetch del HTML RENDERIZADO (post-JS) via CDP.** Navega en un Chrome remoto (compone `cdp_open_url_and_wait` + `cdp_eval`), espera el render y devuelve el `html` con el DOM ya montado por JS → detecta SPAs (React/Vue/Angular/Next) que el fetch estatico no ve. Mismo shape que `fetch_http_fingerprint` (headers={}, status_code=None: la red la aporta el estatico). |
+| `fingerprint_web_stack_py_pipelines` | `fingerprint_web_stack(url, timeout_s=15.0, verify_tls=True, max_html_bytes=500000, save=True, use_cdp=False, cdp_port=9222, wait_render_s=2.0) -> dict` | **Pipeline one-shot = Wappalyzer del registry.** url → tecnologias detectadas. Compone `fetch_http_fingerprint` + `detect_web_tech` (+ sink OSINT). Con `use_cdp=True` añade `fetch_http_fingerprint_cdp`: headers reales del estatico + HTML renderizado del CDP (detecta SPAs); degrada a estatico con warning si no hay Chrome. El camino canonico para fingerprint web. |
+
+### OSINT pasivo relacionado
+
+Estas funciones llevan tambien el tag `recon` (y `osint-passive`): recoleccion no intrusiva desde fuentes publicas, sin tocar al objetivo. Utiles antes o junto al escaneo de red. Pagina madre completa: `docs/capabilities/osint-passive.md`.
+
+| ID | Firma | Que hace |
+|---|---|---|
+| `build_search_dorks_py_cybersecurity` | `build_search_dorks(target, tipo="persona", extra_domains=None) -> list` | **Pure.** Genera dorks de buscador (frase exacta, `site:`, `filetype:`, leaks/pastebin) segun el tipo de target. Sin red. |
+| `enum_subdomains_crtsh_py_cybersecurity` | `enum_subdomains_crtsh(dominio, timeout_s=20.0) -> list` | Enumera subdominios desde Certificate Transparency (crt.sh). Dedup, ordenado, sin wildcards. |
+| `enumerate_username_sites_py_cybersecurity` | `enumerate_username_sites(username, timeout_s=8.0, sites=None) -> list` | Comprueba si un username existe en ~12 sitios publicos (estilo sherlock ligero) por codigo HTTP. |
+| `guess_email_formats_py_cybersecurity` | `guess_email_formats(nombre, apellidos, dominio) -> list` | **Pure.** Genera candidatos de email comunes (nombre.apellido, inicial+apellido, ...). Sin red. |
+| `enrich_org_passive_py_cybersecurity` | `enrich_org_passive(dominio) -> dict` | Orquestador: perfil pasivo de una organizacion componiendo whois + dns + subdominios crt.sh. |
+
+## Ejemplo canonico end-to-end
+
+**1. One-shot (preferido): escanear y archivar en una llamada.** El pipeline corre el scan y lo guarda en OSINT (nota + registro DuckDB) por ti.
+
+```bash
+cd /home/enmanuel/fn_registry
+./fn run recon_osint ejemplo.com whois
+```
+
+Equivalente desde Python (cuando necesitas el dict de resultado):
+
+```bash
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from pipelines.recon_osint import recon_osint
+
+res = recon_osint("ejemplo.com", scan_type="whois", save=True)
+print(res["status"], res.get("note_path"), res.get("registered"))
+PYEOF
+```
+
+**2. Manual atomico + sink.** Cuando quieres controlar el scan (perfil, puertos, summary propio) y guardarlo aparte. La funcion de scan se importa, no se reescribe.
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from cybersecurity import dns_records
+from cybersecurity.save_scan_to_osint import save_scan_to_osint
+
+scan = dns_records("ejemplo.com")               # 1. escanear
+if scan["status"] == "ok":
+    saved = save_scan_to_osint(                  # 2. archivar en OSINT
+        "ejemplo.com",
+        "dns",
+        scan["raw"],
+        summary={"A": scan["records"].get("A"), "MX": scan["records"].get("MX")},
+        tool="dig",
+    )
+    print(saved["note_path"], "registered:", saved["registered"])
+PYEOF
+```
+
+**3. nmap largo en segundo plano.** Los perfiles pesados tardan de minutos a horas: lanzalos en background con `out_dir` (conserva el XML) y `timeout_s` alto, y archiva al terminar.
+
+```bash
+cd /home/enmanuel/fn_registry
+# El pipeline one-shot tambien sirve para nmap; lanzar en background por la duracion:
+nohup ./fn run recon_osint scanme.nmap.org nmap --profile full-tcp --timeout-s 7200 \
+  > /tmp/recon-fulltcp.log 2>&1 &
+```
+
+> `scanme.nmap.org` es el host oficial de pruebas de nmap (legal escanear). Cualquier otro objetivo de terceros exige autorizacion.
+
+**4. Escaneo nativo de servicios de puertos (sin nmap), one-shot.** Cuando no quieres depender de `nmap`/sudo o buscas un barrido rapido y portable: el pipeline `scan_port_services` escanea los puertos y, por cada abierto, dice el servicio esperado por convencion (IANA) y el servicio/version real leido del banner.
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from pipelines.scan_port_services import scan_port_services
+
+res = scan_port_services("scanme.nmap.org", ports="common", save=True)
+print(res["status"], "abiertos:", res.get("open_ports"))
+for s in res.get("services", []):
+    print(f"  {s['port']}: esperado={s['expected_service']} real={s.get('actual_service')} version={s.get('version')}")
+PYEOF
+```
+
+Las primitivas tambien sirven sueltas: `scan_tcp_ports(host, ports)` para solo el estado de los puertos, `grab_service_banner(host, port)` para identificar un servicio concreto, e `identify_port_service(port)` (pura) para el servicio esperado por convencion.
+
+**5. Fingerprint de tecnologia web (Wappalyzer del registry), one-shot.** Identifica el stack de un sitio — servidor, lenguaje, CMS, frameworks JS, analytics, CDN — desde el HTML + cabeceras + cookies, sin ejecutar JS. El pipeline `fingerprint_web_stack` hace fetch + matching de firmas en una llamada.
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from pipelines.fingerprint_web_stack import fingerprint_web_stack
+
+res = fingerprint_web_stack("https://example.com", save=True)
+print(res["status"], "->", res.get("count"), "tecnologias")
+for t in res.get("technologies", []):
+    print(f"  {t['name']} [{t['category']}] v={t['version']!r} ({t['confidence']})")
+PYEOF
+```
+
+Las dos capas tambien sueltas: `fetch_http_fingerprint(url)` para inspeccionar cabeceras+html+cookies crudos de una URL, y `detect_web_tech(headers, html, cookies)` (pura) para matchear firmas sobre señales ya recogidas (testeable sin red).
+
+**Modo CDP (SPAs): detectar mas eficientemente el HTML renderizado.** Un fetch estatico NO ejecuta JavaScript: una SPA (React/Vue/Angular/Next con HTML inicial casi vacio) monta su DOM en runtime y el estatico la pierde. Con `use_cdp=True` el pipeline usa `fetch_http_fingerprint_cdp` (Chrome remoto via CDP) para analizar el DOM ya renderizado, combinando los headers reales del estatico con el HTML post-JS.
+
+```bash
+cd /home/enmanuel/fn_registry
+python/.venv/bin/python3 - <<'PYEOF'
+import sys
+sys.path.insert(0, "python/functions")
+from pipelines.fingerprint_web_stack import fingerprint_web_stack
+
+# cdp_port=9333 = Chrome aislado del browser_mcp (recomendado para terceros); 9222 = navegador diario.
+res = fingerprint_web_stack("https://una-spa.com", use_cdp=True, cdp_port=9333, save=False)
+print(res["html_source"], "->", [t["name"] for t in res["technologies"]])
+PYEOF
+```
+
+Ganancia verificada en vivo: sobre una SPA cuyo marcador de framework solo aparece tras ejecutar JS, el estatico detecta solo `nginx`; con `use_cdp=True` detecta ademas `Next.js`, `React`, `Node.js`. Si no hay Chrome en `cdp_port`, degrada al fetch estatico con un `warning` (no falla).
+
+## Integracion OSINT
+
+Cada escaneo guardado acaba en **dos sitios**, y por eso `save_scan_to_osint` (y el pipeline `recon_osint`) son el cierre obligatorio del grupo:
+
+1. **Nota Markdown en el vault** `~/Obsidian/osint` bajo
+   `dominios/<slug>/recon/<scan_type>-<YYYYMMDD-HHMM>.md`. Frontmatter tipado
+   (`tipo: scan-red`, `scan_tipo`, `target`, `slug`, `fecha`, `herramienta`,
+   `tags: [scan-red, <scan_type>, recon]`) y el `raw` del scan en un bloque de
+   codigo. Es la **capa critica**: si falla, el sink devuelve `status:error`.
+2. **Fila en la tabla DuckDB `network_scans`** (schema `main`) del service
+   `osint_db`, via `POST http://127.0.0.1:8771/api/scan`. Columnas:
+   `id, target, target_slug, scan_type, tool, scan_ts, note_path, summary(JSON),
+   created_at`. Es la **capa best-effort**: si el service esta caido o no expone
+   el endpoint, el sink degrada a solo-nota con `registered=False` +
+   `register_warning`, sin romper. El re-ingest del vault NO borra esta tabla.
+
+**REGLA: todo escaneo se guarda en OSINT.** No hay scans "sueltos". O usas el
+pipeline `recon_osint` (scan + archivado en 1 call), o llamas la funcion de scan
+atomica y a continuacion `save_scan_to_osint` con su `raw`. El slug del target se
+deriva con `re.sub(r"[^a-z0-9._-]+", "-", target.lower())`.
+
+## Escaneos nmap utiles para segundo plano
+
+Los perfiles pesados de `nmap_scan` deben lanzarse en background (`&` / `nohup` / `run_in_background`) por su duracion. Pasa `out_dir` para conservar el XML y sube `timeout_s`.
+
+| Perfil | Flags nmap | Cuando usarlo | Duracion |
+|---|---|---|---|
+| `full-tcp` | `-p- -T4` | Mapear los 65535 puertos TCP (no solo el top 1000). Cuando buscas servicios en puertos no estandar. | Minutos a horas → background |
+| `vuln` | `-sV --script vuln -T4` | Correr los scripts NSE de vulnerabilidades sobre los servicios detectados. Fase posterior a un service scan. | Largo, ruidoso → background |
+| `udp-top` | `-sU --top-ports 100 -T4` | Descubrir servicios UDP (DNS, SNMP, NTP...). UDP es lento y suele requerir sudo. | Largo → background |
+| `service` | `-sV -sC -T4` | Deteccion de version + scripts default sobre puertos abiertos. A veces tolerable en primer plano. | Medio (puede ir a background) |
+| `aggressive` | `-A -T4` | OS + version + scripts + traceroute de golpe. Muy detectable; el `-O` interno puede pedir sudo. | Largo, ruidoso → background |
+
+Perfiles ligeros que SI corren bien en primer plano: `quick` (`-T4 -F`, top 100), `top1000` (`-T4`), `discovery` (`-sn`, ping sweep de una subred → puebla `hosts_up`), `os` (`-O`, requiere sudo).
+
+## Prerequisitos
+
+- **CLIs instaladas** en el PATH: `whois` (`apt install whois`), `rdap` (openrdap, normalmente en `~/go/bin/rdap` — `go install github.com/openrdap/rdap/cmd/rdap@latest`), `dig` (`dnsutils`/`bind-utils`), `ping` (`iputils-ping`), `traceroute`, `nmap`. Si falta el binario, la funcion devuelve `status:error` con la instruccion de instalacion, nunca lanza.
+- **Privilegios**: los perfiles de nmap `os` (-O), `udp-top` (-sU) y parte de `aggressive` requieren sudo/root; sin privilegios nmap cae a connect-scan TCP y esos modos quedan incompletos (estas funciones no usan sudo).
+- **Service `osint_db` vivo** en `http://127.0.0.1:8771` para el registro estructurado en `network_scans`. Si esta caido, los scans siguen guardandose como nota (solo se pierde la fila DuckDB hasta el siguiente re-registro). Ver memoria `osint-duckdb-stack`.
+
+## Fronteras (que NO cubre)
+
+- **No es un framework de explotacion.** Es reconocimiento: identifica superficie (puertos, servicios, versiones, registro, ruta). No explota vulnerabilidades, no hace fuerza bruta de credenciales, no entrega payloads. Para eso, herramientas dedicadas fuera del registry.
+- **Solo hosts autorizados o propios.** Escanear infraestructura de terceros sin permiso explicito puede ser delito. `scanme.nmap.org` es el unico host de terceros legal por defecto (es el host oficial de pruebas de nmap).
+- **No evade deteccion.** No implementa tecnicas de evasion de IDS/WAF, fragmentacion, decoys ni timing de sigilo; `-T4` es ruidoso a proposito. Un objetivo que defienda activamente puede detectar y filtrar el escaneo.
+- **No cubre OSINT pasivo de personas** (dorks, usernames, emails) mas alla de listar las funciones afines: esas viven en el grupo `osint-passive`. El render BD→nota y el grafo del vault son de `obsidian`/`duckdb`.
@@ -19,6 +19,7 @@ Filtro MCP: `mcp__registry__fn_search query="" tag="sink"`.
 | [http_post_json_py_infra](../../python/functions/infra/http_post_json.md) | py | HTTP JSON POST |
 | [http_post_json_go_infra](../../functions/infra/http_post_json.md) | go | HTTP JSON POST |
 | [db_insert_row_go_infra](../../functions/infra/db_insert_row.md) | go | SQL row insert |
+| [save_scan_to_osint_py_cybersecurity](../../python/functions/cybersecurity/save_scan_to_osint.md) | py | Vault Obsidian (nota) + osint_db (DuckDB via HTTP) — sink de scans de red |

 ## Ejemplo canonico

@@ -1,6 +1,15 @@
 package browser

-import "fmt"
+import (
+	"fmt"
+	"time"
+)
+
+// refActionableTimeout es cuánto espera CdpClickRef/CdpHoverRef a que el elemento
+// sea accionable (visible+stable+hit-test) antes de caer al cálculo de centro
+// previo. Lo bastante para tragar animaciones/overlays transitorios sin penalizar
+// el caso común (que converge en ~1 frame).
+const refActionableTimeout = 2 * time.Second

 // refBoxCenter resuelve el centro (x,y) en coords de página de un nodo DOM por su
 // backendDOMNodeId, vía DOM.getBoxModel. El content quad son 8 floats (4 esquinas).
@@ -37,6 +46,13 @@ func CdpClickRef(c *CDPConn, backendNodeID int, opts MouseHumanOpts) error {
 	if opts.Mode == "instant" {
 		return clickRefViaJS(c, backendNodeID)
 	}
+	// Preferir el punto validado por actionability (visible + stable + hit-test):
+	// evita clicks tragados por overlays/banners y elementos aún montándose o
+	// animándose. Si no converge dentro del timeout, se cae al cálculo de centro
+	// previo (sin regresión).
+	if x, y, err := CdpWaitActionable(c, backendNodeID, false, refActionableTimeout); err == nil {
+		return CdpClickXYHuman(c, x, y, opts)
+	}
 	// scroll al elemento si no está visible; ignorar error (no fatal)
 	_, _ = c.sendCDP("DOM.scrollIntoViewIfNeeded", map[string]any{"backendNodeId": backendNodeID})
 	cx, cy, err := refBoxCenter(c, backendNodeID)
@@ -8,7 +8,7 @@ purity: impure
 signature: "func CdpClickRef(c *CDPConn, backendNodeID int, opts MouseHumanOpts) error"
 description: "Click humanizado (Bézier + jitter) sobre el elemento identificado por su #ref del AX outline. El #ref es el backendDOMNodeId estable del nodo DOM. Hace scroll al elemento si no está en viewport antes de calcular las coordenadas vía DOM.getBoxModel."
 tags: [cdp, browser, action, ref, humanized, navegator]
-uses_functions: [cdp_click_xy_human_go_browser]
+uses_functions: [cdp_click_xy_human_go_browser, cdp_wait_actionable_go_browser]
 uses_types: []
 returns: []
 returns_optional: false
@@ -51,12 +51,12 @@ func CdpClickXYHuman(c *CDPConn, x, y float64, opts MouseHumanOpts) error {
 }

 // clickPauseMs devuelve la pausa (ms) entre press y release según el modo de
-// velocidad: human 30-90, fast 5-15, instant 0.
+// velocidad: human 30-90, auto/fast 5-15, instant 0.
 func clickPauseMs(mode string) int {
 	switch mode {
 	case "instant":
 		return 0
-	case "fast":
+	case "fast", "auto":
 		return 5 + rand.Intn(11) // 5..15
 	default: // "human" o ""
 		return 30 + rand.Intn(61) // 30..90
@@ -0,0 +1,281 @@
+package browser
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+)
+
+// ConsoleEntry es una entrada del log de consola/diagnostico capturada via CDP
+// durante una ventana temporal. Type clasifica el origen:
+//   - "log"/"info"/"warn"/"error"/"debug" — Runtime.consoleAPICalled (console.*)
+//   - "exception" — Runtime.exceptionThrown (errores JS no capturados)
+//   - el level de Log.entryAdded ("verbose"/"info"/"warning"/"error") para
+//     avisos del propio navegador (network, security, deprecaciones...)
+type ConsoleEntry struct {
+	Type      string  `json:"type"`      // log|info|warn|warning|error|debug|exception|verbose
+	Text      string  `json:"text"`      // mensaje legible (args concatenados / descripcion + stack)
+	URL       string  `json:"url"`       // URL del script o recurso, si Chrome lo informa
+	Line      int     `json:"line"`      // numero de linea (1-based), 0 si desconocido
+	Timestamp float64 `json:"timestamp"` // CDP timestamp (monotonic seconds) o wall time
+}
+
+// consoleCollectDefaultMax es el tope de entradas por defecto cuando el caller
+// pasa maxEntries <= 0. Acota la salida en paginas verbosas (setInterval ruidoso,
+// SPA que loguea sin parar) para no devolver cientos de entradas y reventar el
+// output del tool.
+const consoleCollectDefaultMax = 200
+
+// CdpCollectConsole habilita los dominios Runtime y Log en la conexion, se
+// suscribe a los eventos de consola/excepcion/log del navegador y acumula todo
+// lo que ocurra durante `durationMs` milisegundos, hasta un maximo de
+// `maxEntries` entradas. Es un SNAPSHOT temporal: captura solo lo emitido dentro
+// de la ventana, no el historico previo de la pagina. Si durationMs <= 0 usa
+// 1500ms por defecto; si maxEntries <= 0 usa 200 por defecto.
+//
+// Dos defensas contra el backlog de una conexion del pool que lleva rato abierta
+// con Runtime habilitado (donde Runtime.enable flushea consoleAPICalled rezagados
+// con timestamps antiguos, y un setInterval verboso puede inundar):
+//   - Filtro por timestamp: se captura `startMs` (wall time, ms epoch) JUSTO antes
+//     de habilitar los dominios y solo se acumulan eventos cuyo timestamp sea >=
+//     startMs. Los eventos `consoleAPICalled`/`exceptionThrown`/`Log.entryAdded`
+//     traen `timestamp` en ms epoch, asi que los rezagados del flush (anteriores
+//     a startMs) se descartan. Eventos sin timestamp (0) se aceptan: no hay forma
+//     de fecharlos y casi siempre son nuevos.
+//   - Cap por cantidad: alcanzado `maxEntries` se dejan de acumular entradas, pero
+//     la funcion NO corta la ventana — sigue durmiendo hasta `durationMs` para no
+//     dejar los dominios CDP en estado raro (handlers a medio drenar). Las entradas
+//     posteriores al cap simplemente se descartan; el flag de truncamiento se
+//     refleja como una ConsoleEntry final de Type "_truncated".
+//
+// Eventos capturados y como se mapean a ConsoleEntry.Type:
+//   - Runtime.consoleAPICalled  -> el `type` del evento (log/info/warning/error/...)
+//   - Runtime.exceptionThrown   -> "exception" (texto = descripcion + stack)
+//   - Log.entryAdded            -> el `level` del entry (warning/error del browser)
+//
+// Robusta ante silencio: si no llega ningun evento devuelve un slice vacio
+// (no nil, no error). La conexion debe estar abierta; la funcion no la cierra.
+func CdpCollectConsole(c *CDPConn, durationMs int, maxEntries int) ([]ConsoleEntry, error) {
+	if c == nil {
+		return nil, fmt.Errorf("cdp collect console: conexion nula")
+	}
+	if durationMs <= 0 {
+		durationMs = 1500
+	}
+	if maxEntries <= 0 {
+		maxEntries = consoleCollectDefaultMax
+	}
+
+	// startMs marca el inicio de la ventana en ms epoch (mismo dominio que el
+	// `timestamp` de los eventos CDP). Eventos anteriores = backlog -> se descartan.
+	startMs := float64(time.Now().UnixMilli())
+
+	var (
+		mu        sync.Mutex
+		entries   = make([]ConsoleEntry, 0, 16)
+		truncated bool
+	)
+
+	// add intenta acumular una entrada respetando el filtro por timestamp y el cap.
+	// Devuelve sin hacer nada si la entrada es backlog o si ya se alcanzo el tope.
+	add := func(e ConsoleEntry) {
+		// Descartar backlog: eventos fechados antes del inicio de la ventana.
+		// Timestamp 0 (sin fecha) se acepta — no se puede clasificar como viejo.
+		if e.Timestamp != 0 && e.Timestamp < startMs {
+			return
+		}
+		mu.Lock()
+		if len(entries) >= maxEntries {
+			truncated = true
+			mu.Unlock()
+			return
+		}
+		entries = append(entries, e)
+		mu.Unlock()
+	}
+
+	// Helpers para extraer campos de map[string]any sin pelearse con cast.
+	str := func(m map[string]any, k string) string {
+		if v, ok := m[k]; ok {
+			if s, ok := v.(string); ok {
+				return s
+			}
+		}
+		return ""
+	}
+	num := func(m map[string]any, k string) float64 {
+		if v, ok := m[k]; ok {
+			if f, ok := v.(float64); ok {
+				return f
+			}
+		}
+		return 0
+	}
+
+	// argToText convierte un RemoteObject de Runtime a una representacion legible.
+	// Para primitivas usa `value`; para objetos sin value cae a `description` o
+	// `unserializableValue`; ultimo recurso, el `type`.
+	argToText := func(arg map[string]any) string {
+		if v, ok := arg["value"]; ok && v != nil {
+			if s, ok := v.(string); ok {
+				return s
+			}
+			// objetos/arrays serializados por valor -> JSON real.
+			if b, err := json.Marshal(v); err == nil {
+				return string(b)
+			}
+			return fmt.Sprintf("%v", v)
+		}
+		if d := str(arg, "description"); d != "" {
+			return d
+		}
+		if u := str(arg, "unserializableValue"); u != "" {
+			return u
+		}
+		return str(arg, "type")
+	}
+
+	// --- Runtime.consoleAPICalled: console.log / info / warn / error / ... ---
+	cancel1 := c.OnEvent("Runtime.consoleAPICalled", func(_ string, p map[string]any) {
+		entry := ConsoleEntry{
+			Type:      str(p, "type"),
+			Timestamp: num(p, "timestamp"),
+		}
+		// Concatenar los args a un texto legible separado por espacios.
+		if rawArgs, ok := p["args"].([]any); ok {
+			parts := make([]string, 0, len(rawArgs))
+			for _, ra := range rawArgs {
+				if am, ok := ra.(map[string]any); ok {
+					parts = append(parts, argToText(am))
+				}
+			}
+			entry.Text = strings.Join(parts, " ")
+		}
+		// stackTrace -> primer frame para URL/linea.
+		if st, ok := p["stackTrace"].(map[string]any); ok {
+			if frames, ok := st["callFrames"].([]any); ok && len(frames) > 0 {
+				if f0, ok := frames[0].(map[string]any); ok {
+					entry.URL = str(f0, "url")
+					// lineNumber es 0-based en CDP; +1 para ser 1-based legible.
+					if ln := int(num(f0, "lineNumber")); ln >= 0 {
+						entry.Line = ln + 1
+					}
+				}
+			}
+		}
+		add(entry)
+	})
+	defer cancel1()
+
+	// --- Runtime.exceptionThrown: errores JS no capturados ---
+	cancel2 := c.OnEvent("Runtime.exceptionThrown", func(_ string, p map[string]any) {
+		entry := ConsoleEntry{
+			Type:      "exception",
+			Timestamp: num(p, "timestamp"),
+		}
+		ed, _ := p["exceptionDetails"].(map[string]any)
+		if ed != nil {
+			// Texto base de la excepcion.
+			text := str(ed, "text")
+			// Si hay un objeto de excepcion con descripcion (stack completo), preferirlo.
+			if exc, ok := ed["exception"].(map[string]any); ok {
+				if desc := str(exc, "description"); desc != "" {
+					if text != "" && !strings.Contains(desc, text) {
+						text = text + ": " + desc
+					} else {
+						text = desc
+					}
+				}
+			}
+			entry.Text = text
+			entry.URL = str(ed, "url")
+			// lineNumber 0-based -> 1-based.
+			if ln := int(num(ed, "lineNumber")); ln >= 0 {
+				entry.Line = ln + 1
+			}
+			// stackTrace top frame como respaldo de URL/linea.
+			if entry.URL == "" {
+				if st, ok := ed["stackTrace"].(map[string]any); ok {
+					if frames, ok := st["callFrames"].([]any); ok && len(frames) > 0 {
+						if f0, ok := frames[0].(map[string]any); ok {
+							entry.URL = str(f0, "url")
+							if entry.Line == 0 {
+								if ln := int(num(f0, "lineNumber")); ln >= 0 {
+									entry.Line = ln + 1
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+		if entry.Text == "" {
+			entry.Text = "uncaught exception"
+		}
+		add(entry)
+	})
+	defer cancel2()
+
+	// --- Log.entryAdded: avisos del propio navegador (network, security...) ---
+	cancel3 := c.OnEvent("Log.entryAdded", func(_ string, p map[string]any) {
+		le, _ := p["entry"].(map[string]any)
+		if le == nil {
+			return
+		}
+		// Log.entryAdded reporta `timestamp` en segundos epoch (a diferencia de
+		// consoleAPICalled/exceptionThrown que lo dan en ms). Normalizar a ms para
+		// que el filtro por startMs compare en el mismo dominio. Heurística: si el
+		// valor parece segundos (varios órdenes por debajo de un ms epoch actual),
+		// multiplicar por 1000.
+		ts := num(le, "timestamp")
+		if ts > 0 && ts < startMs/100 {
+			ts *= 1000
+		}
+		entry := ConsoleEntry{
+			Type:      str(le, "level"), // verbose|info|warning|error
+			Text:      str(le, "text"),
+			URL:       str(le, "url"),
+			Line:      int(num(le, "lineNumber")),
+			Timestamp: ts,
+		}
+		add(entry)
+	})
+	defer cancel3()
+
+	// Habilitar dominios. Runtime.enable provoca un flush de consoleAPICalled
+	// rezagados; Log.enable abre el stream de avisos del navegador.
+	if _, err := c.sendCDP("Runtime.enable", nil); err != nil {
+		return nil, fmt.Errorf("cdp collect console: Runtime.enable: %w", err)
+	}
+	if _, err := c.sendCDP("Log.enable", nil); err != nil {
+		// Log.enable puede no estar disponible en algunos targets; no es fatal,
+		// seguimos capturando Runtime.*. Deshabilitar Runtime no hace falta.
+		_ = err
+	}
+	// No deshabilitamos Runtime al salir: otras funciones (ej. cdp_pick_element_js)
+	// dependen de consoleAPICalled. Solo cerramos Log que abrimos aqui.
+	defer c.sendCDP("Log.disable", nil)
+
+	// Ventana de captura. No hacemos early-return al alcanzar el cap: seguimos
+	// durmiendo la ventana completa para no dejar los dominios CDP a medio drenar.
+	time.Sleep(time.Duration(durationMs) * time.Millisecond)
+
+	mu.Lock()
+	out := make([]ConsoleEntry, len(entries))
+	copy(out, entries)
+	wasTruncated := truncated
+	mu.Unlock()
+
+	// Senal de truncamiento limpia: una entrada final que el caller puede detectar
+	// por Type == "_truncated" sin cambiar la forma del slice.
+	if wasTruncated {
+		out = append(out, ConsoleEntry{
+			Type:      "_truncated",
+			Text:      fmt.Sprintf("output truncado al alcanzar maxEntries=%d; entradas posteriores descartadas", maxEntries),
+			Timestamp: float64(time.Now().UnixMilli()),
+		})
+	}
+	return out, nil
+}
@@ -0,0 +1,82 @@
+---
+name: cdp_collect_console
+kind: function
+lang: go
+domain: browser
+version: "1.1.0"
+purity: impure
+signature: "func CdpCollectConsole(c *CDPConn, durationMs int, maxEntries int) ([]ConsoleEntry, error)"
+description: "Captura un snapshot temporal del log de consola y diagnostico de una pagina Chrome via CDP. Habilita los dominios Runtime y Log, se suscribe a Runtime.consoleAPICalled (console.log/info/warn/error con args concatenados), Runtime.exceptionThrown (errores JS no capturados, type=exception con descripcion + stack) y Log.entryAdded (avisos del propio navegador: network, security, deprecaciones) y acumula todo lo que ocurra durante durationMs ms (default 1500), hasta un maximo de maxEntries entradas (default 200). Devuelve un slice de ConsoleEntry (Type, Text, URL, Line, Timestamp). Es un snapshot de la ventana, no historico previo: filtra por timestamp para descartar el backlog de eventos que una conexion del pool acumulo antes de la llamada. Si se alcanza maxEntries deja de acumular pero no corta la ventana; anade una entrada final con Type=_truncated. Robusta ante silencio: devuelve slice vacio si no llega ningun evento."
+tags: [chrome, cdp, browser, automation, console, devtools, debug, diagnostics, logs, errors, exceptions, flow-replay]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [encoding/json, fmt, strings, sync, time]
+params:
+  - name: c
+    desc: "conexión CDP activa (*CDPConn) contra una pestaña Chrome con el target abierto"
+  - name: durationMs
+    desc: "ventana de captura en milisegundos; si <=0 usa 1500ms. Es el tiempo durante el cual se acumulan eventos de consola/excepcion/log antes de devolver. La función duerme la ventana completa aunque se alcance maxEntries antes"
+  - name: maxEntries
+    desc: "tope de entradas a acumular; si <=0 usa 200. Al alcanzarlo se descartan las entradas posteriores (no se corta la ventana) y se añade una entrada final con Type=_truncated. Acota la salida en páginas verbosas (setInterval ruidoso, SPA que loguea sin parar)"
+output: "slice de ConsoleEntry (Type, Text, URL, Line, Timestamp) con todo lo emitido en la ventana (filtrado de backlog previo a la llamada y acotado a maxEntries); si se truncó, la última entrada tiene Type=_truncated; slice vacío (no nil, no error) si no hubo eventos; error solo si la conexión es nula o falla Runtime.enable"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_collect_console.go"
+---
+
+## Ejemplo
+
+```go
+conn, _ := CdpConnect(9222)
+CdpNavigate(conn, "https://example.com")
+
+// Captura todo lo que la pagina escriba en consola durante 2 segundos,
+// hasta un maximo de 100 entradas (descarta el backlog previo de la conexion).
+entries, err := CdpCollectConsole(conn, 2000, 100)
+if err != nil {
+    log.Fatal(err)
+}
+for _, e := range entries {
+    if e.Type == "_truncated" {
+        fmt.Println("...", e.Text) // se alcanzo el cap de 100 entradas
+        continue
+    }
+    fmt.Printf("[%s] %s  (%s:%d)\n", e.Type, e.Text, e.URL, e.Line)
+}
+// Ejemplo de salida:
+// [error] Uncaught TypeError: x is not a function  (https://example.com/app.js:42)
+// [warning] Mixed Content: requested an insecure resource  (https://example.com:0)
+// [log] app initialized  (https://example.com/app.js:5)
+
+// Cap por defecto (200): pasar maxEntries <= 0.
+entries, _ = CdpCollectConsole(conn, 1500, 0)
+```
+
+## Cuando usarla
+
+Cuando necesitas ver qué errores, warnings o mensajes de consola produce una página justo después de navegar o tras disparar una acción (click, submit). Úsala para depurar por qué un flujo web falla en silencio (excepción JS no capturada, recurso bloqueado por CSP/mixed-content, error de red que solo aparece en consola), para validar que una SPA arrancó sin errores, o como paso de diagnóstico dentro de un flow-replay antes de dar por bueno un replay. Llámala envolviendo la acción que quieres observar: navega/interactúa y deja que la ventana de captura recoja lo que emita.
+
+## Gotchas
+
+- **Impura: requiere Chrome vivo.** Necesita una conexión CDP activa (`*CDPConn`) contra una instancia de Chrome con el target abierto. No funciona sin navegador.
+- **Es un snapshot temporal, no histórico — y filtra el backlog.** Solo captura eventos emitidos DURANTE la ventana `durationMs`. La función captura `startMs` (wall time, ms epoch) justo antes de habilitar los dominios y descarta todo evento con `timestamp` anterior a ese inicio. Esto resuelve el problema real con conexiones del pool que llevan rato abiertas con `Runtime` ya habilitado: cuando `Runtime.enable` se reenvía, Chrome flushea `consoleAPICalled` rezagados con timestamps antiguos; esos backlog se descartan por el filtro. Sin el filtro, en una página verbosa o con un `setInterval` la función devolvía cientos de entradas históricas que reventaban el output. **Por qué `OnEvent` no basta:** los handlers de `OnEvent` solo reciben eventos que lleguen al `readLoop` DESPUÉS del registro, pero el flush de `Runtime.enable` llega justo después y arrastra mensajes viejos — de ahí el backlog. El filtro por timestamp es la defensa que lo separa. Si quieres capturar el arranque, conéctate y llama ANTES de navegar, o navega dentro de la ventana.
+- **Eventos sin timestamp se aceptan.** Si un evento llega con `timestamp` 0 (sin fechar) no se puede clasificar como backlog, así que se acumula. En la práctica casi siempre son nuevos.
+- **`Log.entryAdded` reporta en segundos, no ms.** A diferencia de `consoleAPICalled`/`exceptionThrown` (ms epoch), `Log.entryAdded` da `timestamp` en segundos epoch. La función lo normaliza a ms (heurística: si el valor es varios órdenes menor que un ms epoch actual, lo multiplica por 1000) para que el filtro por `startMs` compare en el mismo dominio.
+- **Cap por cantidad (`maxEntries`).** Al alcanzar `maxEntries` entradas (default 200) la función deja de acumular y descarta las posteriores, pero **NO corta la ventana** — sigue durmiendo hasta `durationMs` para no dejar los dominios CDP a medio drenar (handlers a medias) ni el estado de la conexión raro. Si se truncó, la **última** entrada del slice tiene `Type == "_truncated"` y un `Text` con el cap alcanzado; el caller debe filtrarla o tratarla como señal, no como un log real.
+- **Bloquea durante `durationMs`.** La función duerme la goroutine la ventana completa antes de devolver — no hay early-return aunque ya tengas eventos o se alcance el cap. Elige `durationMs` acorde a lo que esperas observar (1500ms default suele bastar para el load inicial).
+- **`Type` mezcla tres taxonomías.** `consoleAPICalled` usa `log|info|warning|error|debug|...`; `exceptionThrown` siempre marca `exception`; `Log.entryAdded` usa el `level` del navegador (`verbose|info|warning|error`). Filtra por substring (`warn`, `error`) si quieres agrupar severidades; nota que console.warn produce `warning`, no `warn`.
+- **`Line` es 1-based.** CDP reporta `lineNumber` 0-based; esta función suma 1 para que coincida con lo que muestran las DevTools. Los `Log.entryAdded` se dejan tal cual los da Chrome.
+- **No deshabilita `Runtime` al salir.** Otras funciones del package (ej. `cdp_pick_element_js`) dependen de `Runtime.consoleAPICalled`; deshabilitarlo rompería sus handlers. Sí cierra el dominio `Log` que abre aquí.
+- **`Log.enable` puede no estar disponible** en algunos targets (workers, ciertos contextos). Si falla, la función NO aborta: sigue capturando `Runtime.*` y solo pierde los avisos de `Log.entryAdded`.
+
+## Capability growth log
+
+- v1.1.0 (16/06/2026) — añade parámetro `maxEntries` (cap, default 200) + filtro de backlog por timestamp. Resuelve bug real: en conexiones del pool con `Runtime` ya habilitado, el flush de `Runtime.enable` arrastraba eventos históricos (cientos en páginas verbosas con `setInterval`) que reventaban el output. Ahora se descarta lo anterior a `startMs` y se acota la salida con señal `_truncated`.
+
+## Notas
+
+`ConsoleEntry` se define como tipo simple del package `browser` en el mismo `.go` (igual que `HarEntry`/`HarHeader` en `cdp_har_record.go`), no como tipo del registry — evita import circular y mantiene la firma autosuficiente. La acumulación usa un `sync.Mutex` porque los handlers de `OnEvent` corren en la goroutine del `readLoop` de `CDPConn`, concurrente con la goroutine que duerme la ventana. La conversión de args de `consoleAPICalled` serializa objetos/arrays a JSON real (no la repr `%v` de Go) para que datos estructurados sean parseables.
@@ -14,8 +14,16 @@ import (
 	"strings"
 	"sync"
 	"sync/atomic"
+	"time"
 )

+// cdpCmdTimeout es el tope que sendCDP espera por la respuesta a un comando antes
+// de rendirse. Sin el, una respuesta que Chrome nunca envia (tab cerrada a media
+// peticion, proceso colgado) bloquearia la goroutine del tool para siempre — el
+// agente lo percibe como "lentitud infinita". Con el timeout, el tool falla limpio
+// y el retry de withConn puede reconectar.
+const cdpCmdTimeout = 30 * time.Second
+
 // EventHandler es invocado cuando llega un evento CDP del metodo subscrito.
 // El handler corre en la goroutine del readLoop — debe ser rapido o despachar
 // a un canal/goroutine propio. params puede ser nil si Chrome no envia.
@@ -36,6 +44,15 @@ type CDPConn struct {
 	handlers map[string][]EventHandler
 	hMu      sync.Mutex

+	// axEnabled/netEnabled/pageEnabled cachean si ya enviamos el enable de cada
+	// dominio CDP en esta conexion. enable/disable es idempotente pero cuesta un
+	// round-trip; en el hot path del agente (percibir->actuar repetido) re-enviar
+	// Accessibility.enable / Network.enable en cada llamada duplica los RTT.
+	// Habilitar una vez y cachear el flag elimina ese coste por percepcion/espera.
+	axEnabled   atomic.Bool
+	netEnabled  atomic.Bool
+	pageEnabled atomic.Bool
+
 	// frameCtx cachea el executionContextId del isolated world por frameID, para
 	// que CdpEvalInFrame no cree un mundo aislado nuevo en cada llamada.
 	// frameCtxMu protege solo el lazy-init del puntero (el cache tiene su mutex).
@@ -250,12 +267,60 @@ func (c *CDPConn) sendCDP(method string, params map[string]any) (map[string]any,
 		return nil, fmt.Errorf("cdp send %s: %w", method, err)
 	}

-	// Esperar respuesta
-	resp := <-ch
-	if resp.Error != nil {
-		return nil, fmt.Errorf("cdp %s: error %d: %s", method, resp.Error.Code, resp.Error.Message)
+	// Esperar respuesta (con timeout para no colgar el tool indefinidamente).
+	select {
+	case resp := <-ch:
+		if resp.Error != nil {
+			return nil, fmt.Errorf("cdp %s: error %d: %s", method, resp.Error.Code, resp.Error.Message)
+		}
+		return resp.Result, nil
+	case <-time.After(cdpCmdTimeout):
+		c.pendMu.Lock()
+		delete(c.pending, id)
+		c.pendMu.Unlock()
+		return nil, fmt.Errorf("cdp %s: sin respuesta tras %s (conexion colgada?)", method, cdpCmdTimeout)
 	}
-	return resp.Result, nil
+}
+
+// ensureAX habilita el dominio Accessibility una sola vez por conexion (necesario
+// antes de Accessibility.getFullAXTree). Idempotente y cacheado: la segunda y
+// sucesivas llamadas son no-op, evitando un round-trip por percepcion.
+func (c *CDPConn) ensureAX() error {
+	if c.axEnabled.Load() {
+		return nil
+	}
+	if _, err := c.sendCDP("Accessibility.enable", nil); err != nil {
+		return err
+	}
+	c.axEnabled.Store(true)
+	return nil
+}
+
+// ensureNetwork habilita el dominio Network una sola vez por conexion. Cacheado:
+// no lo deshabilitamos al terminar una espera (eso borraria el estado y forzaria
+// el enable de nuevo); los handlers de eventos se desregistran por su cancel().
+func (c *CDPConn) ensureNetwork() error {
+	if c.netEnabled.Load() {
+		return nil
+	}
+	if _, err := c.sendCDP("Network.enable", nil); err != nil {
+		return err
+	}
+	c.netEnabled.Store(true)
+	return nil
+}
+
+// ensurePage habilita el dominio Page una sola vez por conexion (necesario para
+// recibir Page.loadEventFired y demas eventos de ciclo de vida de la pagina).
+func (c *CDPConn) ensurePage() error {
+	if c.pageEnabled.Load() {
+		return nil
+	}
+	if _, err := c.sendCDP("Page.enable", nil); err != nil {
+		return err
+	}
+	c.pageEnabled.Store(true)
+	return nil
 }

 // readLoop lee mensajes del WebSocket y los enruta a los canales pendientes
@@ -0,0 +1,298 @@
+package browser
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+// fillNodeInfo es el diagnostico que devuelve fillPrepare tras inspeccionar y
+// preparar el nodo en el contexto JS de la pagina. Replica la logica de
+// InjectedScript.fill de Playwright sin usar el "native value setter": para los
+// campos de texto/contenteditable selecciona el contenido previo y deja que el
+// motor inserte el valor con eventos confiables (ruta needsinput); para los
+// inputs especiales fija el valor y dispara los eventos (ruta setvalue).
+type fillNodeInfo struct {
+	// Route es "needsinput" (hay que insertar el valor via Input.insertText),
+	// "setvalue" (ya se fijo el valor + eventos, nada mas que hacer) o "" si hubo error.
+	Route string `json:"route"`
+	// Error describe por que el nodo no se puede rellenar (no editable, readonly,
+	// disabled, oculto, tipo no soportado). Vacio si todo OK.
+	Error string `json:"error"`
+}
+
+// resolveObjectID resuelve un backendDOMNodeId a un Runtime objectId, para poder
+// ejecutar JS con `this` apuntando a ese nodo concreto via Runtime.callFunctionOn.
+func resolveObjectID(c *CDPConn, backendNodeID int) (string, error) {
+	res, err := c.sendCDP("DOM.resolveNode", map[string]any{"backendNodeId": backendNodeID})
+	if err != nil {
+		return "", fmt.Errorf("resolveNode ref %d: %w", backendNodeID, err)
+	}
+	obj, _ := res["object"].(map[string]any)
+	objID, _ := obj["objectId"].(string)
+	if objID == "" {
+		return "", fmt.Errorf("sin objectId para ref %d", backendNodeID)
+	}
+	return objID, nil
+}
+
+// callFunctionOnJSON ejecuta functionDeclaration con `this` = objectId, pasando
+// args como argumentos posicionales, y deserializa el valor de retorno (por valor)
+// en out. La funcion JS debe devolver un objeto serializable.
+func callFunctionOnJSON(c *CDPConn, objectID, functionDeclaration string, args []any, out any) error {
+	callArgs := make([]any, len(args))
+	for i, a := range args {
+		callArgs[i] = map[string]any{"value": a}
+	}
+	res, err := c.sendCDP("Runtime.callFunctionOn", map[string]any{
+		"objectId":            objectID,
+		"functionDeclaration": functionDeclaration,
+		"arguments":           callArgs,
+		"returnByValue":       true,
+		"awaitPromise":        true,
+	})
+	if err != nil {
+		return err
+	}
+	if exc, ok := res["exceptionDetails"]; ok && exc != nil {
+		excMap, _ := exc.(map[string]any)
+		text, _ := excMap["text"].(string)
+		return fmt.Errorf("excepcion JS: %s", text)
+	}
+	if out == nil {
+		return nil
+	}
+	resVal, ok := res["result"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("resultado inesperado: %v", res)
+	}
+	b, err := json.Marshal(resVal["value"])
+	if err != nil {
+		return fmt.Errorf("marshal valor de retorno: %w", err)
+	}
+	return json.Unmarshal(b, out)
+}
+
+// fillPrepareJS es la funcion JS (con `this` = elemento) que valida editabilidad,
+// detecta el tipo y prepara el nodo. Replica InjectedScript.fill de Playwright:
+// NO usa el native value setter para text/textarea/contenteditable (selecciona el
+// valor previo y devuelve "needsinput" para que Input.insertText, con eventos
+// confiables del motor, haga que React/Vue reconcilien solos). Para inputs
+// especiales fija el valor y dispara input/change con {bubbles, composed}.
+//
+// arg[0] = value (string).
+const fillPrepareJS = `function(value){
+  var el = this;
+  if (!el || el.nodeType !== 1) return {route:"", error:"el #ref no es un elemento"};
+  // Visibilidad: rect con area + no display:none/visibility:hidden.
+  var rect = el.getBoundingClientRect();
+  var style = el.ownerDocument.defaultView.getComputedStyle(el);
+  if (style.visibility === "hidden" || style.display === "none" || (rect.width === 0 && rect.height === 0))
+    return {route:"", error:"elemento no visible"};
+  var tag = el.nodeName.toLowerCase();
+  if (tag === "input") {
+    var type = (el.type || "text").toLowerCase();
+    if (el.disabled) return {route:"", error:"input deshabilitado"};
+    if (el.readOnly) return {route:"", error:"input es readonly"};
+    var kSetValue = {color:1, date:1, time:1, "datetime-local":1, month:1, range:1, week:1};
+    var kTypeInto = {"":1, email:1, number:1, password:1, search:1, tel:1, text:1, url:1};
+    if (!kTypeInto[type] && !kSetValue[type])
+      return {route:"", error:"input de tipo '"+type+"' no se puede rellenar"};
+    if (type === "number") {
+      value = value.trim();
+      if (value !== "" && isNaN(Number(value)))
+        return {route:"", error:"no se puede escribir texto en input[type=number]"};
+    }
+    if (type === "color") value = value.toLowerCase();
+    if (kSetValue[type]) {
+      value = value.trim();
+      el.focus();
+      el.value = value;
+      if (el.value !== value) return {route:"", error:"valor malformado para input[type="+type+"]"};
+      el.dispatchEvent(new Event("input", {bubbles:true, composed:true}));
+      el.dispatchEvent(new Event("change", {bubbles:true}));
+      return {route:"setvalue", error:""};
+    }
+    // Ruta needsinput: seleccionar el valor previo para que insertText lo reemplace.
+    el.select();
+    el.focus();
+    return {route:"needsinput", error:""};
+  }
+  if (tag === "textarea") {
+    if (el.disabled) return {route:"", error:"textarea deshabilitado"};
+    if (el.readOnly) return {route:"", error:"textarea es readonly"};
+    el.selectionStart = 0;
+    el.selectionEnd = el.value.length;
+    el.focus();
+    return {route:"needsinput", error:""};
+  }
+  if (el.isContentEditable) {
+    el.focus();
+    var range = el.ownerDocument.createRange();
+    range.selectNodeContents(el);
+    var sel = el.ownerDocument.defaultView.getSelection();
+    if (sel) { sel.removeAllRanges(); sel.addRange(range); }
+    return {route:"needsinput", error:""};
+  }
+  return {route:"", error:"el elemento no es input, textarea ni [contenteditable]"};
+}`
+
+// fillVerifyJS lee el valor actual del nodo (input.value/textarea.value o
+// textContent de contenteditable) para verificar que el fill surtio efecto.
+// arg[0] = expected (string). Devuelve {ok:bool, got:string, verifiable:bool}.
+const fillVerifyJS = `function(expected){
+  var el = this;
+  var tag = el.nodeName.toLowerCase();
+  if (tag === "input" || tag === "textarea") {
+    var type = tag === "input" ? (el.type||"text").toLowerCase() : "text";
+    var got = String(el.value);
+    var exp = expected;
+    if (type === "number" || type === "color" || type === "date" || type === "time" ||
+        type === "datetime-local" || type === "month" || type === "range" || type === "week") {
+      exp = expected.trim();
+      if (type === "color") exp = exp.toLowerCase();
+    }
+    return {ok: got === exp, got: got, verifiable: true};
+  }
+  // contenteditable: no verificable de forma fiable (el motor normaliza el HTML).
+  return {ok: true, got: String(el.textContent||""), verifiable: false};
+}`
+
+// CdpFill rellena un campo de texto controlado por frameworks (React/Vue) de
+// forma robusta, estilo Playwright. backendNodeID es un backendDOMNodeId (el #ref
+// del AX outline de page_perceive).
+//
+// Comportamiento (replica InjectedScript.fill):
+//  1. Valida visible + enabled + editable (no readonly/disabled) en el contexto JS.
+//  2. Enfoca el nodo.
+//  3. Detecta el tipo:
+//     - text/textarea/email/search/url/tel/password/number/contenteditable: ruta
+//       "needsinput" — selecciona el valor previo y luego inserta value con
+//       Input.insertText (eventos input/beforeinput confiables del motor; React/Vue
+//       reconcilian solos). Con value=="" borra la seleccion (Delete) en vez de insertar.
+//     - color/date/time/datetime-local/month/range/week: ruta "setvalue" — fija
+//       el.value y dispara input{bubbles,composed} + change{bubbles}.
+//  4. Verifica que el.value === value al final (casos verificables); si no, error.
+//
+// A diferencia del patron focus+type que concatena al valor existente, CdpFill
+// reemplaza el contenido entero y es fiable con inputs controlados por frameworks.
+func CdpFill(c *CDPConn, backendNodeID int, value string) error {
+	if c == nil {
+		return fmt.Errorf("cdp fill: conexion nula")
+	}
+
+	objID, err := resolveObjectID(c, backendNodeID)
+	if err != nil {
+		return fmt.Errorf("cdp fill: %w", err)
+	}
+
+	// Enfocar el nodo (idempotente; fillPrepareJS tambien enfoca, pero DOM.focus
+	// hace scroll-into-view y deja el activeElement listo para Input.insertText).
+	if _, err := c.sendCDP("DOM.focus", map[string]any{"backendNodeId": backendNodeID}); err != nil {
+		return fmt.Errorf("cdp fill: focus ref %d: %w", backendNodeID, err)
+	}
+
+	// Validar + preparar el nodo (selecciona valor previo o fija value+eventos).
+	var info fillNodeInfo
+	if err := callFunctionOnJSON(c, objID, fillPrepareJS, []any{value}, &info); err != nil {
+		return fmt.Errorf("cdp fill: preparar ref %d: %w", backendNodeID, err)
+	}
+	if info.Error != "" {
+		return fmt.Errorf("cdp fill: ref %d no editable: %s", backendNodeID, info.Error)
+	}
+
+	switch info.Route {
+	case "setvalue":
+		// El valor ya se fijo y se dispararon los eventos en fillPrepareJS.
+	case "needsinput":
+		if value == "" {
+			// Sin valor: borrar la seleccion (el valor previo ya esta seleccionado).
+			// Delete elimina la seleccion sin insertar nada.
+			del := map[string]any{"type": "keyDown", "key": "Delete", "code": "Delete", "windowsVirtualKeyCode": 46}
+			if _, err := c.sendCDP("Input.dispatchKeyEvent", del); err != nil {
+				return fmt.Errorf("cdp fill: borrar ref %d: %w", backendNodeID, err)
+			}
+			delUp := map[string]any{"type": "keyUp", "key": "Delete", "code": "Delete", "windowsVirtualKeyCode": 46}
+			if _, err := c.sendCDP("Input.dispatchKeyEvent", delUp); err != nil {
+				return fmt.Errorf("cdp fill: borrar ref %d: %w", backendNodeID, err)
+			}
+		} else {
+			// Insertar el valor (reemplaza la seleccion previa) en un round-trip.
+			// Input.insertText emite los eventos confiables que React/Vue necesitan.
+			if _, err := c.sendCDP("Input.insertText", map[string]any{"text": value}); err != nil {
+				return fmt.Errorf("cdp fill: insertText ref %d: %w", backendNodeID, err)
+			}
+		}
+	default:
+		return fmt.Errorf("cdp fill: ruta de preparacion desconocida %q para ref %d", info.Route, backendNodeID)
+	}
+
+	// Verificar que el valor cuajo (solo casos verificables: input/textarea).
+	var ver struct {
+		OK         bool   `json:"ok"`
+		Got        string `json:"got"`
+		Verifiable bool   `json:"verifiable"`
+	}
+	if err := callFunctionOnJSON(c, objID, fillVerifyJS, []any{value}, &ver); err != nil {
+		// La verificacion en si fallo (nodo desaparecido, etc.): no enmascarar.
+		return fmt.Errorf("cdp fill: verificar ref %d: %w", backendNodeID, err)
+	}
+	if ver.Verifiable && !ver.OK {
+		return fmt.Errorf("cdp fill: verificacion fallida en ref %d: el campo quedo con %q, se esperaba %q", backendNodeID, ver.Got, value)
+	}
+
+	return nil
+}
+
+// CdpFillSelector resuelve un selector CSS a su backendDOMNodeId (via
+// DOM.getDocument + DOM.querySelector + DOM.describeNode) y delega en CdpFill.
+// Util cuando se tiene un selector estable en vez del #ref del AX outline.
+func CdpFillSelector(c *CDPConn, selector string, value string) error {
+	if c == nil {
+		return fmt.Errorf("cdp fill selector: conexion nula")
+	}
+	if strings.TrimSpace(selector) == "" {
+		return fmt.Errorf("cdp fill selector: selector vacio")
+	}
+
+	docRes, err := c.sendCDP("DOM.getDocument", map[string]any{"depth": 0})
+	if err != nil {
+		return fmt.Errorf("cdp fill selector: DOM.getDocument: %w", err)
+	}
+	root, ok := docRes["root"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("cdp fill selector: respuesta de DOM.getDocument sin root")
+	}
+	rootNodeID, ok := root["nodeId"].(float64)
+	if !ok {
+		return fmt.Errorf("cdp fill selector: DOM.getDocument sin nodeId raiz")
+	}
+
+	qsRes, err := c.sendCDP("DOM.querySelector", map[string]any{
+		"nodeId":   int(rootNodeID),
+		"selector": selector,
+	})
+	if err != nil {
+		return fmt.Errorf("cdp fill selector: DOM.querySelector %q: %w", selector, err)
+	}
+	nodeIDVal, ok := qsRes["nodeId"].(float64)
+	if !ok || int(nodeIDVal) == 0 {
+		return fmt.Errorf("cdp fill selector: el selector %q no coincide con ningun elemento", selector)
+	}
+
+	// Resolver el nodeId a backendNodeId (CdpFill opera sobre backendDOMNodeId).
+	descRes, err := c.sendCDP("DOM.describeNode", map[string]any{"nodeId": int(nodeIDVal)})
+	if err != nil {
+		return fmt.Errorf("cdp fill selector: DOM.describeNode %q: %w", selector, err)
+	}
+	node, ok := descRes["node"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("cdp fill selector: DOM.describeNode %q sin node", selector)
+	}
+	backendID, ok := node["backendNodeId"].(float64)
+	if !ok || int(backendID) == 0 {
+		return fmt.Errorf("cdp fill selector: %q sin backendNodeId", selector)
+	}
+
+	return CdpFill(c, int(backendID), value)
+}
@@ -0,0 +1,66 @@
+---
+name: cdp_fill
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpFill(c *CDPConn, backendNodeID int, value string) error"
+description: "Rellena un campo de texto de forma robusta estilo Playwright, fiable con inputs controlados por frameworks (React/Vue). Valida visible+enabled+editable, enfoca el nodo, y según el tipo: para text/textarea/email/search/url/tel/password/number/contenteditable selecciona el valor previo y lo reemplaza con Input.insertText (eventos input/beforeinput confiables del motor — React/Vue reconcilian solos); para inputs especiales (color/date/time/range/week/month/datetime-local) fija el.value y dispara input{bubbles,composed}+change{bubbles}. Verifica que el.value===value al final. backendNodeID es el #ref del AX outline. Variante por selector: CdpFillSelector. Reemplaza el patrón frágil focus+type que concatena al valor existente."
+tags: [cdp, browser, action, ref, fill, form, react, vue, navegator]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+params:
+  - name: c
+    desc: "Conexión CDP activa al tab objetivo (*CDPConn)."
+  - name: backendNodeID
+    desc: "El #ref del AX outline = backendDOMNodeId estable del nodo DOM. Se obtiene de page_perceive / render_ax_outline."
+  - name: value
+    desc: "Valor a poner en el campo. Reemplaza el contenido entero (no concatena). value=='' borra el campo. Para input[type=number] debe ser numérico; para color se normaliza a minúsculas."
+output: "nil si el campo quedó con el valor pedido; error si la conexión es nil, el nodo no es editable (readonly/disabled/oculto), el tipo de input no se puede rellenar, o la verificación final (el.value===value) falla."
+file_path: "functions/browser/cdp_fill.go"
+---
+
+## Ejemplo
+
+```go
+// Tras un page_perceive que devuelve un <input> React con #ref=4521:
+conn, _ := CdpConnect(9222)
+
+// Por #ref del AX outline (camino habitual del bucle percibir→actuar):
+if err := CdpFill(conn, 4521, "ada@example.com"); err != nil {
+    log.Fatal(err)
+}
+
+// Por selector CSS estable (resuelve a backendNodeID y delega en CdpFill):
+if err := CdpFillSelector(conn, "input[name='email']", "ada@example.com"); err != nil {
+    log.Fatal(err)
+}
+
+// Vaciar un campo:
+_ = CdpFillSelector(conn, "#search", "")
+
+// Input especial (date): ruta setvalue + eventos input/change:
+_ = CdpFillSelector(conn, "input[type='date']", "2026-06-16")
+```
+
+## Cuando usarla
+
+Cuando necesites rellenar inputs de formularios controlados por React/Vue/otros frameworks de forma fiable. Es el reemplazo del patrón `DOM.focus` + `CdpTypeText`/`CdpInsertText` que **concatena** al valor existente y a menudo deja el estado del framework desincronizado (el `value` del DOM cambia pero el estado de React no, o al revés). `CdpFill` selecciona y reemplaza el contenido entero y, al usar `Input.insertText` (no el native value setter), emite los eventos `input`/`beforeinput` confiables que hacen que el framework reconcilie su estado. Úsala para login, registro, búsquedas y cualquier campo donde el patrón focus+type falle o duplique texto. Para teclear carácter a carácter simulando un humano (sitios con detección por pulsación o autocompletes estrictos) sigue prefiriendo `CdpTypeRef` (camino human).
+
+## Gotchas
+
+- El `#ref` es un **backendDOMNodeId**, no el nodeId efímero del AX tree. Si la página recargó o navegó tras el snapshot, el ref puede estar muerto — re-percibir (`page_perceive`) antes de actuar.
+- **contenteditable**: la ruta needsinput inserta el valor seleccionando todo el contenido, pero la verificación final **no es fiable** para contenteditable (el motor normaliza el HTML). Por eso para contenteditable `CdpFill` no falla por verificación; confía en que `Input.insertText` cuajó. Si necesitas garantía dura del contenido, léelo aparte con `CdpEvaluate`.
+- **Inputs especiales** (color/date/time/datetime-local/month/range/week) van por la ruta setvalue: fijan `el.value` y disparan `input`{bubbles,composed}+`change`{bubbles}. Algunos frameworks que escuchan eventos de teclado en estos inputs pueden no reaccionar — es el mismo trade-off que hace Playwright.
+- **input[type=number]**: el valor debe ser numérico (`isNaN` lo rechaza con error claro). Espacios se recortan.
+- **Frameworks y el evento nativo**: la clave de la robustez es NO usar el "native value setter" (`Object.getOwnPropertyDescriptor(...).set`). React parchea el setter de `value` y se confunde si lo invocas a mano; `Input.insertText` del motor emite los eventos que React intercepta correctamente. Si una versión muy vieja de un framework custom no reacciona, cae a `CdpTypeRef` (char por char).
+- **No hace scroll humanizado**: `DOM.focus` hace scroll-into-view del nodo, pero si el input está dentro de un contenedor con scroll propio y oculto, valida visible y puede fallar con "elemento no visible". En ese caso haz `CdpClickRef` (que hace `scrollIntoViewIfNeeded`) antes.
+- **value==""** borra el campo enviando `Delete` sobre la selección previa (no `Input.insertText` con cadena vacía, que sería no-op). Esto dispara los eventos de borrado que el framework espera.
@@ -0,0 +1,191 @@
+package browser
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// CdpFindByRoleOpts configura el matching del accessible name de CdpFindByRole.
+// Si Name == "", solo se filtra por role (cualquier name vale).
+type CdpFindByRoleOpts struct {
+	// Name es el accessible name a matchear. Vacio = no filtra por name.
+	Name string
+	// Exact: true = el name normalizado debe ser igual al buscado.
+	// false (default) = el name normalizado contiene el buscado (substring).
+	Exact bool
+	// Regex: true = Name se interpreta como expresion regular (RE2 de Go).
+	// Tiene prioridad sobre Exact si ambos estan a true.
+	Regex bool
+	// CaseSensitive: false (default) = comparacion insensible a mayusculas.
+	// Para Regex, false añade el flag (?i) a la expresion.
+	CaseSensitive bool
+}
+
+// normalizeWhiteSpace replica la regla de Playwright (utils/isomorphic/stringUtils.ts):
+// elimina el zero-width space (U+200B) y el soft hyphen (U+00AD), recorta extremos y
+// colapsa cualquier run de whitespace a un unico espacio. Es la normalizacion que
+// Playwright aplica a ambos lados al comparar el accessible name (getByRole({name})),
+// para que diferencias de whitespace/caracteres invisibles no rompan el match.
+func normalizeWhiteSpace(s string) string {
+	// Strip zero-width space y soft hyphen.
+	s = strings.ReplaceAll(s, "", "")
+	s = strings.ReplaceAll(s, "", "")
+	// Colapsar runs de whitespace a un espacio.
+	s = whitespaceRun.ReplaceAllString(s, " ")
+	// Trim de extremos.
+	return strings.TrimSpace(s)
+}
+
+// whitespaceRun matchea uno o mas caracteres de espacio en blanco. Equivale a
+// `\s+` de la regex de normalizeWhiteSpace de Playwright.
+var whitespaceRun = regexp.MustCompile(`\s+`)
+
+// CdpFindByRole localiza el primer elemento por su ROLE ARIA y, opcionalmente, su
+// accessible name — el equivalente a getByRole de Playwright. Reutiliza el AX tree
+// que ya pedimos para page_perceive (Accessibility.getFullAXTree) en vez de tocar el
+// DOM/CSS, lo que la hace robusta a cambios de markup/estilos.
+//
+// Recorre los nodos del AX tree y matchea:
+//   - role: igualdad exacta del rol ARIA (ej "button", "link", "textbox").
+//   - name (si opts.Name != ""): el accessible name del nodo contra opts.Name, con
+//     normalizeWhiteSpace aplicado a ambos lados (regla Playwright). Por defecto es
+//     substring; Exact => igualdad; Regex => expresion regular. Insensible a
+//     mayusculas salvo CaseSensitive.
+//
+// Retorna (ref, count, error):
+//   - ref: backendDOMNodeId del primer match — el mismo #ref que produce el outline
+//     de page_perceive y que consume CdpClickRef/CdpHoverRef.
+//   - count: numero total de nodos que matchean. count > 1 indica ambiguedad: el
+//     caller decide si refinar (Name mas especifico, Exact, etc.).
+//   - error: conexion nula, role vacio, regex invalida, fallo CDP, o 0 matches.
+func CdpFindByRole(c *CDPConn, role string, opts CdpFindByRoleOpts) (ref int, count int, err error) {
+	if c == nil {
+		return 0, 0, fmt.Errorf("cdp find by role: conexion nula")
+	}
+	if role == "" {
+		return 0, 0, fmt.Errorf("cdp find by role: role vacio")
+	}
+
+	// Construir el matcher del name una sola vez (compila la regex si aplica).
+	matchName, err := buildNameMatcher(opts)
+	if err != nil {
+		return 0, 0, fmt.Errorf("cdp find by role: %w", err)
+	}
+
+	// Accessibility.enable (idempotente, cacheado) antes de getFullAXTree.
+	if err := c.ensureAX(); err != nil {
+		return 0, 0, fmt.Errorf("cdp find by role: Accessibility.enable: %w", err)
+	}
+
+	res, err := c.sendCDP("Accessibility.getFullAXTree", nil)
+	if err != nil {
+		return 0, 0, fmt.Errorf("cdp find by role: Accessibility.getFullAXTree: %w", err)
+	}
+
+	nodes := axoParseNodes(res)
+
+	firstRef := 0
+	haveFirst := false
+	for _, n := range nodes {
+		if n.ignored {
+			continue
+		}
+		if n.role != role {
+			continue
+		}
+		if opts.Name != "" && !matchName(n.name) {
+			continue
+		}
+		count++
+		if !haveFirst {
+			// axoRefID prefiere backendDOMNodeID; ese es el ref que consume CdpClickRef.
+			if id, ok := atoiRef(axoRefID(n)); ok {
+				firstRef = id
+				haveFirst = true
+			}
+		}
+	}
+
+	if count == 0 {
+		if opts.Name != "" {
+			return 0, 0, fmt.Errorf("cdp find by role: no element with role %q and name %q", role, opts.Name)
+		}
+		return 0, 0, fmt.Errorf("cdp find by role: no element with role %q", role)
+	}
+	if !haveFirst {
+		// Hubo matches pero ninguno tenia un ref entero usable (backendDOMNodeId
+		// ausente y nodeId no numerico): no podemos devolver un #ref valido.
+		return 0, count, fmt.Errorf("cdp find by role: %d match(es) para role %q pero sin backendDOMNodeId usable", count, role)
+	}
+	return firstRef, count, nil
+}
+
+// buildNameMatcher devuelve la funcion que decide si un accessible name candidato
+// matchea opts.Name, normalizando ambos lados con normalizeWhiteSpace. Si Name == ""
+// el matcher siempre es true (no se filtra por name). Compila la regex una vez.
+func buildNameMatcher(opts CdpFindByRoleOpts) (func(candidate string) bool, error) {
+	if opts.Name == "" {
+		return func(string) bool { return true }, nil
+	}
+
+	want := normalizeWhiteSpace(opts.Name)
+
+	if opts.Regex {
+		pat := opts.Name
+		if !opts.CaseSensitive {
+			pat = "(?i)" + pat
+		}
+		re, err := regexp.Compile(pat)
+		if err != nil {
+			return nil, fmt.Errorf("regex invalida %q: %w", opts.Name, err)
+		}
+		return func(candidate string) bool {
+			return re.MatchString(normalizeWhiteSpace(candidate))
+		}, nil
+	}
+
+	if !opts.CaseSensitive {
+		want = strings.ToLower(want)
+	}
+
+	return func(candidate string) bool {
+		got := normalizeWhiteSpace(candidate)
+		if !opts.CaseSensitive {
+			got = strings.ToLower(got)
+		}
+		if opts.Exact {
+			return got == want
+		}
+		return strings.Contains(got, want)
+	}, nil
+}
+
+// atoiRef convierte el ref string (backendDOMNodeId, ya normalizado a entero-string
+// por axoStr) a int. Devuelve (0, false) si no es un entero parseable.
+func atoiRef(s string) (int, bool) {
+	if s == "" {
+		return 0, false
+	}
+	neg := false
+	i := 0
+	if s[0] == '-' {
+		neg = true
+		i = 1
+		if len(s) == 1 {
+			return 0, false
+		}
+	}
+	n := 0
+	for ; i < len(s); i++ {
+		ch := s[i]
+		if ch < '0' || ch > '9' {
+			return 0, false
+		}
+		n = n*10 + int(ch-'0')
+	}
+	if neg {
+		n = -n
+	}
+	return n, true
+}
@@ -0,0 +1,82 @@
+---
+name: cdp_find_by_role
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpFindByRole(c *CDPConn, role string, opts CdpFindByRoleOpts) (ref int, count int, err error)"
+description: "Localiza el primer elemento por su ROLE ARIA + accessible name (estilo getByRole de Playwright) reusando el AX tree (Accessibility.getFullAXTree). Devuelve el backendDOMNodeId (#ref) del primer match y el total de matches para detectar ambiguedad."
+tags: [browser]
+params:
+  - name: c
+    desc: "Conexion CDP viva (*CDPConn) del pool. nil => error."
+  - name: role
+    desc: "Rol ARIA exacto a matchear (ej 'button', 'link', 'textbox', 'checkbox')."
+  - name: opts
+    desc: "CdpFindByRoleOpts: Name (accessible name, vacio = no filtra), Exact (igualdad en vez de substring), Regex (Name como expresion regular RE2), CaseSensitive (default false)."
+output: "(ref int, count int, err error): ref = backendDOMNodeId del primer match (#ref para CdpClickRef/CdpHoverRef); count = total de matches (>1 = ambiguo); err si conexion nula, role vacio, regex invalida, fallo CDP o 0 matches."
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_find_by_role.go"
+---
+
+## Ejemplo
+
+```go
+c, _ := browser.CdpConnect(9333) // conexion CDP del pool
+ref, count, err := browser.CdpFindByRole(c, "button", browser.CdpFindByRoleOpts{
+    Name: "Aceptar", // substring del accessible name, case-insensitive
+})
+if err != nil {
+    log.Fatal(err) // ej: no element with role "button" and name "Aceptar"
+}
+if count > 1 {
+    log.Printf("aviso: %d botones matchean 'Aceptar', usando el primero", count)
+}
+// ref es el mismo #ref que produce page_perceive: alimentarlo a CdpClickRef.
+_ = browser.CdpClickRef(c, ref, browser.MouseHumanOpts{})
+
+// Match exacto + case-sensitive:
+ref, _, _ = browser.CdpFindByRole(c, "link", browser.CdpFindByRoleOpts{
+    Name: "Iniciar sesion", Exact: true, CaseSensitive: true,
+})
+
+// Match por regex (ej "Eliminar 3 elementos" / "Eliminar 12 elementos"):
+ref, _, _ = browser.CdpFindByRole(c, "button", browser.CdpFindByRoleOpts{
+    Name: `^Eliminar \d+ elementos$`, Regex: true,
+})
+```
+
+## Cuando usarla
+
+Cuando necesites localizar un control de forma robusta a cambios de DOM/CSS: el rol
+ARIA + accessible name sobreviven a refactors de markup y clases CSS que romperian un
+selector `nth-of-type`. Es el patron primario que recomienda Playwright (getByRole)
+para encontrar elementos accionables (botones, links, inputs). Combina el `ref`
+devuelto directamente con `cdp_click_ref` / `cdp_hover_ref` para actuar sin pasar por
+un selector fragil. Revisa `count` antes de actuar: si es >1 la busqueda es ambigua
+y conviene refinar (Name mas especifico, Exact, o Regex anclada).
+
+## Gotchas
+
+- El `name` que se matchea es el **accessible name computado** por el motor de
+  accesibilidad de Chrome (deriva de aria-label, label asociado, contenido, alt,
+  title segun la spec ARIA), **no** el `innerText` del elemento. Si buscas por el
+  texto visible literal, usa `cdp_find_ref_by_text` en su lugar.
+- `count > 1` => ambiguedad: se devuelve el primer match en orden del AX tree, que no
+  siempre es el visualmente primero ni el que quieres. Refina la busqueda.
+- El `role` se compara por **igualdad exacta** del rol ARIA: "button" no matchea
+  "menuitem" aunque ambos sean clicables. Mira el outline de `page_perceive` /
+  `cdp_get_ax_outline` para ver el rol real que Chrome asigna a cada nodo.
+- Nodos `ignored` del AX tree se descartan. Si el elemento esta oculto (aria-hidden,
+  display:none) puede no aparecer y dar 0 matches.
+- El `ref` es un `backendDOMNodeId`: estable mientras el nodo viva, pero si el DOM
+  muta entre el find y el click el ref puede quedar obsoleto.
@@ -72,8 +72,10 @@ func CdpGetAXOutline(c *CDPConn, frameID string, maxChars int) (string, error) {
 		return "", fmt.Errorf("cdp get ax outline: conexion nula")
 	}

-	// Accessibility.enable es idempotente; necesario antes de getFullAXTree.
-	if _, err := c.sendCDP("Accessibility.enable", nil); err != nil {
+	// Accessibility.enable (idempotente, cacheado por conexion): necesario antes de
+	// getFullAXTree. Cachear el flag evita un round-trip extra en cada percepcion,
+	// que es la operacion mas frecuente del bucle percibir->actuar del agente.
+	if err := c.ensureAX(); err != nil {
 		return "", fmt.Errorf("cdp get ax outline: Accessibility.enable: %w", err)
 	}

@@ -9,6 +9,10 @@ func CdpHoverRef(c *CDPConn, backendNodeID int, opts MouseHumanOpts) error {
 	if c == nil {
 		return fmt.Errorf("cdp hover ref: conexión nil")
 	}
+	// Preferir el punto validado por actionability; si no converge, caer al centro.
+	if x, y, err := CdpWaitActionable(c, backendNodeID, false, refActionableTimeout); err == nil {
+		return CdpMoveMouseHuman(c, x, y, opts)
+	}
 	// scroll al elemento si no está visible; ignorar error (no fatal)
 	_, _ = c.sendCDP("DOM.scrollIntoViewIfNeeded", map[string]any{"backendNodeId": backendNodeID})
 	cx, cy, err := refBoxCenter(c, backendNodeID)
@@ -8,7 +8,7 @@ purity: impure
 signature: "func CdpHoverRef(c *CDPConn, backendNodeID int, opts MouseHumanOpts) error"
 description: "Mueve el ratón con trayectoria humanizada (Bézier) sobre el elemento identificado por su #ref del AX outline. Útil para activar menús desplegables, tooltips y cualquier interacción que dependa de hover. El #ref es el backendDOMNodeId estable del nodo DOM."
 tags: [cdp, browser, action, ref, humanized, navegator]
-uses_functions: [cdp_move_mouse_human_go_browser]
+uses_functions: [cdp_move_mouse_human_go_browser, cdp_wait_actionable_go_browser]
 uses_types: []
 returns: []
 returns_optional: false
@@ -9,11 +9,12 @@ import (

 // MouseHumanOpts configura el movimiento humano del ratón.
 type MouseHumanOpts struct {
-	// Mode es la política de velocidad: "human" (default, ""), "fast" o "instant".
-	// Controla los defaults de Steps/DurationMs/JitterPx y la pausa press/release:
+	// Mode es la política de velocidad: "auto"/"fast" (rápido), "human" (sigiloso,
+	// también "") o "instant". Controla los defaults de Steps/DurationMs/JitterPx y
+	// la pausa press/release:
+	//   - auto/fast: recta ~5 pts, 40-80ms, jitter mínimo (eventos de ratón reales,
+	//              rápido — modo por defecto del MCP para automatización propia).
 	//   - human:   Bézier ~25 pts, 350-800ms, jitter 2px (sigilo anti-bot alto).
-	//   - fast:    recta ~5 pts, 40-80ms, jitter mínimo (eventos de ratón reales,
-	//              para scraping masivo propio).
 	//   - instant: sin movimiento de ratón (CdpMoveMouseHuman es no-op); el click
 	//              por #ref usa element.click() JS. Para tests y fallback sin bbox.
 	// Los valores explícitos (Steps/DurationMs/JitterPx != 0) ganan al preset del modo.
@@ -37,7 +38,7 @@ type MouseHumanOpts struct {
 // Un modo desconocido se trata como "human" (el más seguro).
 func MouseProfileForMode(mode string) MouseHumanOpts {
 	switch mode {
-	case "fast", "instant", "human", "":
+	case "auto", "fast", "instant", "human", "":
 		return MouseHumanOpts{Mode: mode, FromX: -1, FromY: -1}
 	default:
 		return MouseHumanOpts{Mode: "human", FromX: -1, FromY: -1}
@@ -56,14 +57,14 @@ func mouseHumanDefaults(opts MouseHumanOpts) MouseHumanOpts {
 			opts.DurationMs = 1
 		}
 		// JitterPx se queda en 0.
-	case "fast":
+	case "fast", "auto":
 		if opts.Steps <= 0 {
 			opts.Steps = 5
 		}
 		if opts.DurationMs <= 0 {
 			opts.DurationMs = 40 + rand.Intn(41) // 40..80
 		}
-		// JitterPx se queda en lo recibido (0 por defecto, sin jitter en fast).
+		// JitterPx se queda en lo recibido (0 por defecto, sin jitter en fast/auto).
 	default: // "human" o ""
 		if opts.Steps <= 0 {
 			opts.Steps = 25
@@ -0,0 +1,77 @@
+package browser
+
+import (
+	"encoding/base64"
+	"fmt"
+)
+
+// CdpPrintPDFOpts configura la generacion del PDF via Page.printToPDF.
+type CdpPrintPDFOpts struct {
+	// Landscape orienta la pagina en horizontal cuando es true (vertical por defecto).
+	Landscape bool
+	// PrintBackground incluye los graficos de fondo (colores e imagenes CSS) cuando es true.
+	PrintBackground bool
+	// Scale es el factor de escala del renderizado (1.0 = tamano natural).
+	// Si es <= 0 se usa 1.0. Chrome acepta el rango [0.1, 2].
+	Scale float64
+	// PaperWidthIn es el ancho del papel en pulgadas. 0 deja el default del navegador (8.5in).
+	PaperWidthIn float64
+	// PaperHeightIn es el alto del papel en pulgadas. 0 deja el default del navegador (11in).
+	PaperHeightIn float64
+}
+
+// CdpPrintPDF genera un PDF de la pagina actual via el metodo CDP Page.printToPDF
+// y devuelve los bytes del PDF ya decodificados, sin tocar el disco.
+//
+// Usa transferMode "ReturnAsBase64" (el default de CDP): Chrome devuelve el PDF
+// completo como string base64 en el campo "data" de la respuesta, que esta
+// funcion decodifica a []byte. Es robusto ante paginas grandes porque sendCDP
+// espera la respuesta completa por el WebSocket antes de decodificar.
+//
+// Las opciones se traducen a los params de Page.printToPDF: Landscape,
+// PrintBackground y Scale siempre se envian (con Scale forzado a 1.0 si opts pide
+// <= 0). PaperWidthIn/PaperHeightIn solo se envian cuando son > 0, dejando el
+// tamano de papel por defecto del navegador en caso contrario.
+//
+// Es la primitiva reutilizable de impresion a PDF: util para devolver el PDF al
+// LLM como document content (bytes) o para que un caller lo persista a disco.
+func CdpPrintPDF(c *CDPConn, opts CdpPrintPDFOpts) ([]byte, error) {
+	if c == nil {
+		return nil, fmt.Errorf("cdp print pdf: conexion nula")
+	}
+
+	scale := opts.Scale
+	if scale <= 0 {
+		scale = 1.0
+	}
+
+	params := map[string]any{
+		"transferMode":    "ReturnAsBase64",
+		"landscape":       opts.Landscape,
+		"printBackground": opts.PrintBackground,
+		"scale":           scale,
+	}
+	if opts.PaperWidthIn > 0 {
+		params["paperWidth"] = opts.PaperWidthIn
+	}
+	if opts.PaperHeightIn > 0 {
+		params["paperHeight"] = opts.PaperHeightIn
+	}
+
+	result, err := c.sendCDP("Page.printToPDF", params)
+	if err != nil {
+		return nil, fmt.Errorf("cdp print pdf: %w", err)
+	}
+
+	dataStr, ok := result["data"].(string)
+	if !ok {
+		return nil, fmt.Errorf("cdp print pdf: campo data ausente en respuesta")
+	}
+
+	pdfData, err := base64.StdEncoding.DecodeString(dataStr)
+	if err != nil {
+		return nil, fmt.Errorf("cdp print pdf: decodificar base64: %w", err)
+	}
+
+	return pdfData, nil
+}
@@ -0,0 +1,61 @@
+---
+name: cdp_print_pdf
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpPrintPDF(c *CDPConn, opts CdpPrintPDFOpts) ([]byte, error)"
+description: "Genera un PDF de la pagina actual via el metodo CDP Page.printToPDF y devuelve los bytes ya decodificados, sin tocar el disco. Usa transferMode ReturnAsBase64 (Chrome devuelve el PDF como base64 en el campo data) y lo decodifica a []byte. Aplica las opciones a los params: Landscape, PrintBackground y Scale siempre (Scale forzado a 1.0 si opts pide <= 0); PaperWidthIn/PaperHeightIn solo cuando son > 0, dejando el tamano de papel por defecto del navegador en caso contrario. Robusto ante paginas grandes. Primitiva reutilizable para devolver el PDF al LLM como document content o persistirlo a disco."
+tags: [chrome, cdp, browser, automation, pdf, print, printToPDF, devtools, document, navegator]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [encoding/base64, fmt]
+params:
+  - name: c
+    desc: "conexión CDP activa (*CDPConn) contra Chrome con el target abierto"
+  - name: opts
+    desc: "opciones de impresión (Landscape, PrintBackground, Scale, PaperWidthIn, PaperHeightIn en pulgadas)"
+output: "bytes del PDF decodificados desde base64, o error si falla la generación o la decodificación"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_print_pdf.go"
+---
+
+## Ejemplo
+
+```go
+conn, _ := CdpConnect(9222)
+CdpNavigate(conn, "https://example.com")
+
+pdfData, err := CdpPrintPDF(conn, CdpPrintPDFOpts{
+    Landscape:       false,
+    PrintBackground: true,
+    Scale:           1.0,
+    PaperWidthIn:    8.27,  // A4
+    PaperHeightIn:   11.69, // A4
+})
+// pdfData: bytes del PDF listos para escribir a disco o devolver al LLM
+// os.WriteFile("example.pdf", pdfData, 0644)
+```
+
+## Cuando usarla
+
+Cuando necesitas el PDF de la página actual en memoria: para devolverlo al LLM como document content (bytes), para archivar el render de una página (factura, informe, dashboard) o como primitiva sobre la que un caller compone la escritura a disco. Úsala tras `CdpNavigate` + espera de carga (`CdpWaitIdle`) para asegurar que el contenido está renderizado antes de imprimir.
+
+## Gotchas
+
+- **Impura: requiere Chrome vivo**: necesita una conexión CDP activa (`*CDPConn`) contra una instancia de Chrome con el target abierto. No funciona sin navegador.
+- **Solo en modo headless completo de impresión**: `Page.printToPDF` funciona de forma fiable en Chrome headless. En modo headed (con UI), algunas builds de Chrome devuelven `PrintToPDF is not implemented`; si lo necesitas con UI, lanza Chrome con `--headless=new`.
+- **Scale fuera de rango**: Chrome acepta `scale` en `[0.1, 2]`. Esta función fuerza `1.0` cuando `opts.Scale <= 0`, pero no recorta valores válidos fuera de rango — si pasas `5.0`, Chrome puede rechazar el comando con error.
+- **Paper en pulgadas**: `PaperWidthIn`/`PaperHeightIn` son pulgadas (la unidad nativa de CDP), no mm. A4 ≈ 8.27 × 11.69 in, Letter = 8.5 × 11 in. `0` deja el default del navegador (Letter).
+- **Contenido lazy-load / dinámico**: `printToPDF` captura el DOM en el instante de la llamada. Si la página carga contenido al hacer scroll o por JS diferido, espera a que termine (scroll + `CdpWaitIdle`) antes de imprimir.
+- **PrintBackground apagado por defecto**: igual que el diálogo de impresión de Chrome, los fondos CSS (colores e imágenes) no salen salvo que pongas `PrintBackground: true`.
+
+## Notas
+
+Adición al dominio `browser` (estilo CDP del paquete): el `.go` vive junto a las demás funciones `cdp_*.go` en el mismo paquete `browser`. El struct `CdpPrintPDFOpts` se define en el mismo archivo. Chrome retorna el PDF como base64 (`transferMode: "ReturnAsBase64"`, el default de CDP); esta función lo decodifica a `[]byte` y lo devuelve sin escribir a disco — el caller decide el destino. Patrón gemelo de `CdpScreenshotBytes` para el caso de impresión a PDF.
@@ -0,0 +1,275 @@
+package browser
+
+import (
+	"fmt"
+	"strings"
+	"time"
+)
+
+// CdpDropdownOpts configura la seleccion en un desplegable custom (no nativo).
+type CdpDropdownOpts struct {
+	// Exact: true = el texto de la opcion debe ser igual (tras normalizar) a
+	// optionText. false (default) = match por substring. La comparacion siempre
+	// es case-insensitive y sobre el texto normalizado (trim + colapsar espacios).
+	Exact bool
+	// TimeoutMs es el tope de espera (ms) para que el listbox monte/anime y la
+	// opcion aparezca visible. <=0 usa el default 3000.
+	TimeoutMs int
+	// OptionRole es el rol ARIA de las opciones a buscar ("option" por defecto).
+	// Usar "menuitem" para menus tipo dropdown-menu, "treeitem" para arboles, etc.
+	OptionRole string
+}
+
+// CdpSelectDropdown selecciona una opcion en un DESPLEGABLE CUSTOM (combobox/listbox
+// ARIA, react-select, MUI Select, headlessui, select2, ...) — esos en los que un
+// <select> nativo NO aplica y por tanto CdpSelectOption no sirve.
+//
+// El patron replica como Playwright compone la accion (no tiene API para custom
+// dropdowns): click(trigger) -> esperar apertura -> getByRole('option', {name}) ->
+// click(option). Pasos:
+//
+//  1. Localiza el trigger por triggerSelector (CSS) y hace CLICK REAL (mouse
+//     mousePressed/mouseReleased sobre el centro del bbox, no element.click() JS):
+//     muchos dropdowns escuchan 'mousedown', no 'click'.
+//  2. Espera la apertura (polling hasta TimeoutMs): el trigger pasa a
+//     aria-expanded="true", O aparece un [role=listbox]/[role=menu] visible, O hay
+//     elementos con el rol de opcion (OptionRole / li[role] / menuitem) con rect>0.
+//     No avanza hasta que haya opciones visibles.
+//  3. Localiza la opcion cuyo texto normalizado (trim + colapsar espacios)
+//     coincide con optionText (substring si Exact=false, igualdad si Exact=true),
+//     entre las opciones con rol visibles. Error claro si no aparece en el timeout.
+//  4. CLICK REAL en el centro de esa opcion.
+//  5. Verifica el cierre/seleccion: aria-expanded vuelve a false O el trigger
+//     refleja el texto elegido; si la verificacion es ambigua, intenta Enter como
+//     fallback suave. No falla duro si el click se hizo pero la verificacion queda
+//     incierta.
+//
+// purity: impure (DOM + input real + tiempo). Devuelve error si el trigger no
+// existe, si el dropdown no abre en el timeout, o si la opcion no aparece.
+func CdpSelectDropdown(c *CDPConn, triggerSelector string, optionText string, opts CdpDropdownOpts) error {
+	if c == nil {
+		return fmt.Errorf("cdp select dropdown: conexion nula")
+	}
+	if strings.TrimSpace(triggerSelector) == "" {
+		return fmt.Errorf("cdp select dropdown: triggerSelector vacio")
+	}
+	if strings.TrimSpace(optionText) == "" {
+		return fmt.Errorf("cdp select dropdown: optionText vacio")
+	}
+
+	timeoutMs := opts.TimeoutMs
+	if timeoutMs <= 0 {
+		timeoutMs = 3000
+	}
+	optionRole := strings.TrimSpace(opts.OptionRole)
+	if optionRole == "" {
+		optionRole = "option"
+	}
+	deadline := time.Now().Add(time.Duration(timeoutMs) * time.Millisecond)
+
+	// 1. Click REAL en el trigger.
+	if err := dropdownClickSelector(c, triggerSelector); err != nil {
+		return fmt.Errorf("cdp select dropdown: click trigger %q: %w", triggerSelector, err)
+	}
+
+	// 2. Esperar apertura (opciones visibles).
+	if err := dropdownWaitOpen(c, triggerSelector, optionRole, deadline); err != nil {
+		return fmt.Errorf("cdp select dropdown: %w", err)
+	}
+
+	// 3 + 4. Localizar la opcion por texto y click REAL en su centro.
+	cx, cy, err := dropdownFindOptionCenter(c, optionRole, optionText, opts.Exact, deadline)
+	if err != nil {
+		return fmt.Errorf("cdp select dropdown: %w", err)
+	}
+	if err := CdpClickXYHuman(c, cx, cy, MouseHumanOpts{Mode: "auto"}); err != nil {
+		return fmt.Errorf("cdp select dropdown: click opcion %q: %w", optionText, err)
+	}
+
+	// 5. Verificacion suave: dar un instante a que se cierre/refleje, y si sigue
+	// abierto intentar Enter (algunos comboboxes confirman con Enter sobre la
+	// opcion activa). No es fatal si la verificacion queda ambigua.
+	time.Sleep(120 * time.Millisecond)
+	if dropdownStillOpen(c, triggerSelector, optionRole) {
+		_ = CdpPressKey(c, "Enter")
+	}
+	return nil
+}
+
+// dropdownClickSelector resuelve el bbox del elemento (por selector CSS) y hace
+// click real sobre su centro. Hace scroll si hace falta. Cae a element.click() JS
+// solo si el nodo no tiene geometria (display:contents, area 0).
+func dropdownClickSelector(c *CDPConn, selector string) error {
+	// Centro del bbox del elemento via getBoundingClientRect en el contexto JS.
+	js := fmt.Sprintf(`(function(){
+		var el = document.querySelector(%s);
+		if (!el) return '__NO_EL__';
+		el.scrollIntoView({block:'center', inline:'center'});
+		var r = el.getBoundingClientRect();
+		if (r.width <= 0 || r.height <= 0) return '__NO_BOX__';
+		return JSON.stringify({x: r.left + r.width/2, y: r.top + r.height/2});
+	})()`, jsString(selector))
+
+	res, err := CdpEvaluate(c, js)
+	if err != nil {
+		return fmt.Errorf("resolver bbox: %w", err)
+	}
+	res = strings.Trim(res, `"`)
+	switch res {
+	case "__NO_EL__":
+		return fmt.Errorf("trigger no encontrado para selector %q", selector)
+	case "__NO_BOX__":
+		// Sin geometria: fallback a element.click() JS (no dispara mousedown real).
+		return dropdownClickViaJS(c, selector)
+	}
+
+	x, y, ok := parseXY(res)
+	if !ok {
+		return fmt.Errorf("bbox invalido %q", res)
+	}
+	return CdpClickXYHuman(c, x, y, MouseHumanOpts{Mode: "auto"})
+}
+
+// dropdownClickViaJS es el fallback sin geometria: element.click() en el contexto JS.
+func dropdownClickViaJS(c *CDPConn, selector string) error {
+	js := fmt.Sprintf(`(function(){
+		var el = document.querySelector(%s);
+		if (!el) return '__NO_EL__';
+		el.click();
+		return '__OK__';
+	})()`, jsString(selector))
+	res, err := CdpEvaluate(c, js)
+	if err != nil {
+		return err
+	}
+	if strings.Trim(res, `"`) != "__OK__" {
+		return fmt.Errorf("element.click() JS fallo (%s)", strings.Trim(res, `"`))
+	}
+	return nil
+}
+
+// dropdownWaitOpen hace polling hasta deadline esperando que el dropdown este
+// abierto: trigger con aria-expanded="true", O un [role=listbox]/[role=menu]
+// visible, O algun elemento con el rol de opcion (rect>0). Error si no abre.
+func dropdownWaitOpen(c *CDPConn, triggerSelector, optionRole string, deadline time.Time) error {
+	for {
+		open, err := dropdownIsOpen(c, triggerSelector, optionRole)
+		if err != nil {
+			return err
+		}
+		if open {
+			return nil
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("el dropdown no abrio (sin opciones visibles) tras el timeout para trigger %q", triggerSelector)
+		}
+		time.Sleep(80 * time.Millisecond)
+	}
+}
+
+// dropdownIsOpen comprueba una vez si el dropdown esta abierto.
+func dropdownIsOpen(c *CDPConn, triggerSelector, optionRole string) (bool, error) {
+	js := fmt.Sprintf(`(function(){
+		var trigger = document.querySelector(%s);
+		if (trigger && trigger.getAttribute('aria-expanded') === 'true') return 'open';
+		function visible(el){
+			if (!el) return false;
+			var r = el.getBoundingClientRect();
+			if (r.width <= 0 || r.height <= 0) return false;
+			var cs = getComputedStyle(el);
+			if (cs.visibility === 'hidden' || cs.display === 'none') return false;
+			return true;
+		}
+		// Un contenedor listbox/menu visible cuenta como abierto.
+		var containers = document.querySelectorAll('[role=listbox],[role=menu]');
+		for (var i=0;i<containers.length;i++){ if (visible(containers[i])) return 'open'; }
+		// O al menos una opcion (por rol o por li[role]) visible.
+		var role = %s;
+		var sel = '[role=' + role + '],li[role],[role=menuitem]';
+		var opts = document.querySelectorAll(sel);
+		for (var j=0;j<opts.length;j++){ if (visible(opts[j])) return 'open'; }
+		return 'closed';
+	})()`, jsString(triggerSelector), jsString(optionRole))
+
+	res, err := CdpEvaluate(c, js)
+	if err != nil {
+		return false, fmt.Errorf("comprobar apertura: %w", err)
+	}
+	return strings.Trim(res, `"`) == "open", nil
+}
+
+// dropdownStillOpen es una comprobacion best-effort para la verificacion final;
+// nunca propaga error (un fallo aqui no debe invalidar el click ya hecho).
+func dropdownStillOpen(c *CDPConn, triggerSelector, optionRole string) bool {
+	open, err := dropdownIsOpen(c, triggerSelector, optionRole)
+	if err != nil {
+		return false
+	}
+	return open
+}
+
+// dropdownFindOptionCenter localiza, entre las opciones visibles del dropdown, la
+// que matchea optionText (substring si exact=false, igualdad si exact=true; ambas
+// case-insensitive sobre texto normalizado) y devuelve el centro de su bbox. Hace
+// polling hasta deadline para tolerar listas virtualizadas que montan tarde.
+func dropdownFindOptionCenter(c *CDPConn, optionRole, optionText string, exact bool, deadline time.Time) (float64, float64, error) {
+	js := fmt.Sprintf(`(function(){
+		var role = %s;
+		var want = %s;
+		var exact = %t;
+		function norm(v){ return (v||'').replace(/\s+/g,' ').trim().toLowerCase(); }
+		function visible(el){
+			var r = el.getBoundingClientRect();
+			if (r.width <= 0 || r.height <= 0) return false;
+			var cs = getComputedStyle(el);
+			if (cs.visibility === 'hidden' || cs.display === 'none') return false;
+			return true;
+		}
+		var target = norm(want);
+		var sel = '[role=' + role + '],li[role],[role=menuitem]';
+		var nodes = document.querySelectorAll(sel);
+		for (var i=0;i<nodes.length;i++){
+			var el = nodes[i];
+			if (!visible(el)) continue;
+			var t = norm(el.innerText || el.textContent || '');
+			var ok = exact ? (t === target) : (t.indexOf(target) >= 0);
+			if (ok){
+				var r = el.getBoundingClientRect();
+				return JSON.stringify({x: r.left + r.width/2, y: r.top + r.height/2});
+			}
+		}
+		return '__NO_OPTION__';
+	})()`, jsString(optionRole), jsString(optionText), exact)
+
+	for {
+		res, err := CdpEvaluate(c, js)
+		if err != nil {
+			return 0, 0, fmt.Errorf("buscar opcion: %w", err)
+		}
+		res = strings.Trim(res, `"`)
+		if res != "__NO_OPTION__" {
+			if x, y, ok := parseXY(res); ok {
+				return x, y, nil
+			}
+		}
+		if time.Now().After(deadline) {
+			return 0, 0, fmt.Errorf("option %q not found in dropdown", optionText)
+		}
+		time.Sleep(80 * time.Millisecond)
+	}
+}
+
+// parseXY extrae x/y de un JSON {"x":..,"y":..} que llega ya des-escapado de
+// CdpEvaluate (que devuelve el JSON.stringify como string). Hace un parse ligero
+// sin importar encoding/json de nuevo en el hot path: busca los numeros tras x/y.
+func parseXY(s string) (float64, float64, bool) {
+	// CdpEvaluate devuelve la cadena producida por JSON.stringify; las comillas
+	// internas vienen escapadas como \" tras pasar por el unmarshal de Go.
+	s = strings.ReplaceAll(s, `\"`, `"`)
+	var x, y float64
+	n, err := fmt.Sscanf(s, `{"x":%g,"y":%g}`, &x, &y)
+	if err != nil || n != 2 {
+		return 0, 0, false
+	}
+	return x, y, true
+}
@@ -0,0 +1,98 @@
+---
+name: cdp_select_dropdown
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpSelectDropdown(c *CDPConn, triggerSelector string, optionText string, opts CdpDropdownOpts) error"
+description: "Selecciona una opcion en un DESPLEGABLE CUSTOM (combobox/listbox ARIA, react-select, MUI Select, headlessui, select2) — esos donde un <select> nativo NO aplica. Replica el patron de Playwright (que no tiene API para custom dropdowns): click REAL en el trigger (mousedown, no element.click JS), espera la apertura por polling (aria-expanded=true O [role=listbox]/[role=menu] visible O opciones con rect>0), localiza la opcion por texto normalizado (substring o exacto, case-insensitive) y hace click REAL en su centro, con verificacion suave (aria-expanded vuelve a false o Enter como fallback). Reusa CdpEvaluate, CdpClickXYHuman y CdpPressKey."
+tags: [browser, chrome, cdp, automation, dropdown, combobox, listbox, aria, select, react-select, mui, headlessui, devtools]
+uses_functions: [cdp_evaluate_go_browser, cdp_click_xy_human_go_browser, cdp_press_key_go_browser]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, strings, time]
+params:
+  - name: c
+    desc: "conexion CDP activa (*CDPConn)"
+  - name: triggerSelector
+    desc: "selector CSS del elemento que abre el desplegable (el boton/combobox sobre el que se hace click real)"
+  - name: optionText
+    desc: "texto visible de la opcion a elegir; se normaliza (trim + colapsar espacios) y se compara case-insensitive, por substring si opts.Exact=false o por igualdad si opts.Exact=true"
+  - name: opts
+    desc: "CdpDropdownOpts{Exact bool (igualdad vs substring, default substring); TimeoutMs int (espera apertura+opcion, default 3000); OptionRole string (rol ARIA de las opciones, default 'option' — usar 'menuitem' para menus, 'treeitem' para arboles)}"
+output: "error si el trigger no existe, si el dropdown no abre dentro del timeout (\"el dropdown no abrio\"), o si la opcion no aparece (\"option %q not found in dropdown\"); nil si el click sobre la opcion se realizo (la verificacion de cierre es suave y no falla duro si queda ambigua)"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_select_dropdown.go"
+---
+
+## Ejemplo
+
+```go
+conn, _ := CdpConnect(9222)
+CdpNavigate(conn, "https://mui.com/material-ui/react-select/")
+
+// Combobox MUI: el trigger es el div con role=combobox; el listbox monta y
+// anima al abrir. CdpSelectDropdown clica el trigger, espera a que el listbox
+// este visible y entonces clica la opcion "Twenty".
+err := CdpSelectDropdown(conn, "[role=combobox]", "Twenty", CdpDropdownOpts{})
+if err != nil {
+    log.Fatal(err)
+}
+
+// react-select / headlessui: trigger por clase + match exacto + timeout amplio
+// para listas que tardan en montar.
+err = CdpSelectDropdown(conn, ".select__control", "España", CdpDropdownOpts{
+    Exact:     true,
+    TimeoutMs: 6000,
+})
+
+// Menu tipo dropdown-menu (no listbox): las opciones son role=menuitem.
+err = CdpSelectDropdown(conn, "#user-menu-btn", "Cerrar sesion", CdpDropdownOpts{
+    OptionRole: "menuitem",
+})
+```
+
+## Cuando usarla
+
+Usala cuando el desplegable NO es un `<select>` nativo: comboboxes/listboxes ARIA,
+react-select, MUI Select, headlessui, select2, Ant Design, o cualquier menu hecho
+con `<div>`/`<li>` + JS donde elegir = clicar el trigger y luego clicar la opcion
+del menu desplegado. Es el equivalente al patron de Playwright
+`click(trigger) -> getByRole('option', {name}) -> click(option)`, con la espera de
+apertura ya resuelta. Para un `<select>` nativo de HTML usa `CdpSelectOption` (setea
+`select.value` + dispara `input`/`change`), que es mas robusto y directo para ese
+caso.
+
+## Gotchas
+
+- **Click real, no element.click()**: muchos dropdowns custom escuchan `mousedown`
+  (no `click`), por eso esta funcion despacha eventos de raton reales sobre el
+  centro del bbox. Solo cae a `element.click()` JS si el nodo no tiene geometria.
+- **Animaciones de apertura**: el fallo nº1 reportado en Playwright es clicar la
+  opcion ANTES de que el listbox monte/anime. Por eso hay polling de apertura
+  (`dropdownWaitOpen`) que no avanza hasta que hay opciones visibles. Si tu
+  dropdown anima muy lento, sube `TimeoutMs`.
+- **Listas virtualizadas** (react-window, virtuoso): solo renderizan las opciones
+  en viewport. Si la opcion buscada esta fuera del scroll inicial, puede que nunca
+  se monte y la funcion devuelva "not found" aunque exista. Mitigacion: escribe en
+  el combobox para filtrar (`CdpTypeText`) antes de llamar a esta funcion, o haz
+  scroll dentro del listbox primero.
+- **Trigger vs contenedor**: `triggerSelector` debe apuntar al elemento que ABRE el
+  menu (el boton/combobox), no al `[role=listbox]` (que no existe hasta abrir).
+- **Match de texto**: normaliza espacios y es case-insensitive; por defecto es
+  substring (`Exact=false`). Si varias opciones comparten substring, elige la
+  primera visible en orden de documento — usa `Exact=true` para desambiguar.
+- **OptionRole**: por defecto `option` (`[role=option]`). Para menus de acciones usa
+  `menuitem`; para arboles `treeitem`. La deteccion de apertura tambien considera
+  `[role=menu]` y `li[role]` para cubrir patrones comunes.
+- **Verificacion suave**: tras clicar, si el dropdown sigue abierto la funcion pulsa
+  `Enter` como fallback y devuelve `nil`. No falla duro si la seleccion no se puede
+  confirmar inequivocamente pero el click se hizo — comprueba el estado resultante
+  (texto del trigger, valor del formulario) si necesitas certeza.
+- **iframes**: opera en el documento principal (via `CdpEvaluate`). Para un dropdown
+  dentro de un iframe necesitarias el contexto del frame (no cubierto aqui).
@@ -0,0 +1,153 @@
+package browser
+
+import (
+	"fmt"
+	"strings"
+)
+
+// CdpSelectOption selecciona una <option> de un <select> nativo (localizado por
+// selector CSS) replicando la semantica de Playwright (injectedScript.selectOptions).
+//
+// Orden de matching de value contra cada <option>, en este orden:
+//  1. value exacto: option.value === value.
+//  2. label/texto exacto: option.label === value (sin normalizar).
+//  3. label/texto NORMALIZADO: normalizeWhiteSpace(option.label) === normalizeWhiteSpace(value),
+//     donde normalizar = quitar zero-width space (U+200B) y soft hyphen (U+00AD),
+//     trim, y colapsar cualquier secuencia de whitespace a un solo espacio.
+//  4. label/texto por substring NORMALIZADO: la primera option cuyo label normalizado
+//     contenga el value normalizado (fallback para etiquetas largas).
+//  5. fallback por indice: solo si value es un entero (>= 0) y existe esa posicion.
+//
+// Sobre la option encontrada hace focus del select, setea option.selected = true
+// (no solo select.value, para que funcione tambien con <select multiple>) y despacha
+// 'input' {bubbles:true, composed:true} seguido de 'change' {bubbles:true}, en ese
+// orden, para que frameworks (React/Vue/Angular) y shadow DOM reaccionen al cambio.
+//
+// Si el selector apunta a un <label for=...>, sigue la referencia hasta su control
+// (retarget follow-label) antes de validar que sea un <select>.
+//
+// Devuelve error claro si:
+//   - el selector no encuentra elemento ("element not found"),
+//   - el elemento no es un <select> ("element is not a <select> ..."),
+//   - ninguna option coincide ("option not found in <select>").
+func CdpSelectOption(c *CDPConn, selector string, value string) error {
+	if c == nil {
+		return fmt.Errorf("cdp select option: conexion nula")
+	}
+
+	// Script JS alineado con Playwright. Devuelve centinelas en string:
+	//   __OK__:<value>  cuando selecciona; el resto son codigos de error claros.
+	// Usamos jsString para inyectar selector/value de forma segura (anti-inyeccion).
+	js := fmt.Sprintf(`(function() {
+		function normWS(t) {
+			return (t == null ? '' : String(t))
+				.replace(/[]/g, '')
+				.trim()
+				.replace(/\s+/g, ' ');
+		}
+		var el = document.querySelector(%s);
+		if (!el) return '__NO_EL__';
+		// retarget follow-label: si es un <label for>, salta a su control.
+		if (el.nodeName.toLowerCase() === 'label') {
+			var labelled = null;
+			var forId = el.getAttribute('for');
+			if (forId) labelled = document.getElementById(forId);
+			if (!labelled) labelled = el.querySelector('select, input, textarea');
+			if (labelled) el = labelled;
+		}
+		if (el.nodeName.toLowerCase() !== 'select') return '__NOT_SELECT__';
+		var sel = el;
+		var want = %s;
+		var wantNorm = normWS(want);
+		var opts = Array.prototype.slice.call(sel.options);
+		var match = null;
+
+		// 1. value exacto.
+		for (var i = 0; i < opts.length && !match; i++) {
+			if (opts[i].value === want) match = opts[i];
+		}
+		// 2. label/texto exacto.
+		if (!match) {
+			for (var j = 0; j < opts.length && !match; j++) {
+				if (opts[j].label === want || (opts[j].textContent || '') === want) match = opts[j];
+			}
+		}
+		// 3. label/texto normalizado exacto.
+		if (!match && wantNorm !== '') {
+			for (var k = 0; k < opts.length && !match; k++) {
+				var ln = normWS(opts[k].label || opts[k].textContent);
+				if (ln === wantNorm) match = opts[k];
+			}
+		}
+		// 4. label/texto por substring normalizado.
+		if (!match && wantNorm !== '') {
+			for (var m = 0; m < opts.length && !match; m++) {
+				var ln2 = normWS(opts[m].label || opts[m].textContent);
+				if (ln2.indexOf(wantNorm) !== -1) match = opts[m];
+			}
+		}
+		// 5. fallback por indice: solo si want es un entero >= 0 valido.
+		if (!match && /^[0-9]+$/.test(want)) {
+			var idx = parseInt(want, 10);
+			if (idx >= 0 && idx < opts.length) match = opts[idx];
+		}
+
+		if (!match) return '__NO_OPTION__';
+
+		try { sel.focus(); } catch (e) {}
+		// option.selected en vez de solo select.value: necesario para <select multiple>
+		// y mas fiel a como un usuario elige una entrada concreta.
+		if (!sel.multiple) {
+			for (var n = 0; n < opts.length; n++) opts[n].selected = false;
+		}
+		match.selected = true;
+		sel.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+		sel.dispatchEvent(new Event('change', { bubbles: true }));
+		return '__OK__:' + match.value;
+	})()`, jsString(selector), jsString(value))
+
+	res, err := CdpEvaluate(c, js)
+	if err != nil {
+		return fmt.Errorf("cdp select option: evaluar selector %q: %w", selector, err)
+	}
+
+	res = strings.Trim(res, `"`)
+	switch {
+	case strings.HasPrefix(res, "__OK__"):
+		return nil
+	case res == "__NO_EL__":
+		return fmt.Errorf("cdp select option: element not found para selector %q", selector)
+	case res == "__NOT_SELECT__":
+		return fmt.Errorf("cdp select option: element %q is not a <select> (use cdp_select_dropdown / click el trigger+option para dropdowns custom)", selector)
+	case res == "__NO_OPTION__":
+		return fmt.Errorf("cdp select option: option %q not found in <select> %q", value, selector)
+	default:
+		return fmt.Errorf("cdp select option: resultado inesperado %q para selector %q", res, selector)
+	}
+}
+
+// jsString convierte un string Go en un literal JS seguro (entre comillas dobles,
+// con escapes para comillas, backslashes y saltos de linea). Evita la inyeccion
+// de codigo al interpolar selectores/valores arbitrarios en el script JS.
+func jsString(s string) string {
+	var b strings.Builder
+	b.WriteByte('"')
+	for _, r := range s {
+		switch r {
+		case '"':
+			b.WriteString(`\"`)
+		case '\\':
+			b.WriteString(`\\`)
+		case '\n':
+			b.WriteString(`\n`)
+		case '\r':
+			b.WriteString(`\r`)
+		case '\t':
+			b.WriteString(`\t`)
+		default:
+			b.WriteRune(r)
+		}
+	}
+	b.WriteByte('"')
+	return b.String()
+}
@@ -0,0 +1,107 @@
+---
+name: cdp_select_option
+kind: function
+lang: go
+domain: browser
+version: "1.1.0"
+purity: impure
+signature: "func CdpSelectOption(c *CDPConn, selector string, value string) error"
+description: "Selecciona una <option> de un <select> nativo (localizado por selector CSS) replicando la semantica de Playwright (injectedScript.selectOptions). Match por value exacto, luego label/texto exacto, luego label normalizado (whitespace-collapse + strip zero-width/soft-hyphen), luego substring normalizado, y por ultimo indice si value es entero. Setea option.selected (soporta <select multiple>), hace focus, y despacha 'input' {bubbles,composed} + 'change' {bubbles}. Valida que el elemento sea <select> (error claro si no) y sigue <label for>. Via Runtime.evaluate, reusa CdpEvaluate."
+tags: [chrome, cdp, browser, automation, select, dropdown, form, dom, devtools]
+uses_functions: [cdp_evaluate_go_browser]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, strings]
+params:
+  - name: c
+    desc: "conexión CDP activa"
+  - name: selector
+    desc: "selector CSS del elemento <select> a modificar"
+  - name: value
+    desc: "criterio de seleccion. Se prueba en orden: value exacto → label/texto exacto → label normalizado (whitespace-collapse + strip U+200B/U+00AD) → label por substring normalizado → indice (si value es un entero)"
+output: "error si el selector no encuentra elemento (\"element not found\"), si el elemento no es un <select> (\"element is not a <select> ...\"), o si ninguna option coincide (\"option not found in <select>\"); nil si la selección y los eventos se despacharon correctamente"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_select_option.go"
+---
+
+## Ejemplo
+
+```go
+conn, _ := CdpConnect(9222)
+CdpNavigate(conn, "https://example.com/form")
+
+// Seleccionar por value
+if err := CdpSelectOption(conn, "#country", "ES"); err != nil {
+    log.Fatal(err)
+}
+
+// Seleccionar por texto visible cuando no se conoce el value interno
+if err := CdpSelectOption(conn, "select[name=lang]", "Español"); err != nil {
+    log.Fatal(err)
+}
+
+// Seleccionar por indice (3a opcion) cuando ni value ni texto son estables
+if err := CdpSelectOption(conn, "#size", "2"); err != nil { // index 2 = 3a option
+    log.Fatal(err)
+}
+```
+
+## Cuando usarla
+
+Usala cuando necesites elegir una opcion de un `<select>` nativo en un formulario
+web y quieras que un framework (React, Vue, Angular) reaccione al cambio. Es la
+forma robusta de rellenar dropdowns durante automatizacion/scraping: a diferencia
+de un click sobre la option, setea `option.selected` y dispara `input`+`change`,
+que es lo que los frameworks escuchan. Combinala con `CdpClick` para enviar el
+formulario despues. Si no conoces el `value` interno, pasa el texto visible (se
+normaliza el whitespace) o el indice numerico de la option.
+
+## Gotchas
+
+- **Solo `<select>` nativos.** Si el elemento no es un `<select>` retorna error
+  claro `element is not a <select> ...`. Dropdowns custom hechos con `<div>` + JS
+  (react-select, headlessui, Radix, etc.) NO son `<select>` reales: para esos usa
+  `cdp_select_dropdown` (cuando exista) o clica el trigger con `CdpClickRef` y
+  luego la opcion del menu desplegado (`CdpFindRefByText` + `CdpClickRef`). NO uses
+  esta funcion para ellos.
+- **Orden de matching del `value` recibido** (se prueba en este orden y para en el
+  primer match):
+  1. `option.value` exacto (`===`).
+  2. `option.label` / `textContent` exacto (sin normalizar).
+  3. label/texto NORMALIZADO exacto: se quita zero-width space (U+200B) y soft
+     hyphen (U+00AD), se hace `trim`, y se colapsa cualquier whitespace (`\s+`) a un
+     solo espacio — igual que `normalizeWhiteSpace` de Playwright.
+  4. label/texto por SUBSTRING normalizado (primera option cuyo label normalizado
+     contenga el value normalizado). Util para etiquetas largas; cuidado con
+     ambiguedad (gana la primera en orden de documento).
+  5. fallback por INDICE: solo si `value` es un entero `>= 0` valido (`"2"` → 3a
+     option). Por eso un `value` que casualmente sea numerico puede caer aqui si no
+     hubo ningun match textual antes — preferi el `value` real cuando exista.
+  El matching es case-sensitive en todos los pasos (no se hace lowercase).
+- **`<select multiple>` soportado:** setea `option.selected = true` sobre la option
+  encontrada sin tocar el resto de selecciones. En un `<select>` simple deselecciona
+  las demas antes de marcar la elegida. (La version 1.0.0 solo seteaba `select.value`
+  y reseteaba el multiple — corregido.)
+- **Eventos:** dispara `input` con `{bubbles:true, composed:true}` (el `composed`
+  permite cruzar shadow DOM, p.ej. web components que envuelven el `<select>`) y
+  luego `change` con `{bubbles:true}`, en ese orden. Hace `focus()` del select antes.
+- No hace scroll ni verifica visibilidad/enabled: opera sobre el DOM directamente.
+  Si el `<select>` o la `<option>` estan `disabled`, la seleccion se aplica igual
+  pero la UI puede ignorarla segun el framework (Playwright aqui devolveria
+  `optionnotenabled`; esta funcion no chequea enabled — mantiene KISS).
+- Si el elemento aun no existe (carga dinamica), retorna `element not found` sin
+  esperar — combinar con `CdpWaitElement` para elementos diferidos.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-16) — alineada con Playwright `injectedScript.selectOptions`:
+  valida que el elemento sea `<select>` (error claro si no, apuntando a dropdowns
+  custom), sigue `<label for>`, matching multi-criterio (value → label exacto →
+  label normalizado whitespace-collapse → substring → indice), usa
+  `option.selected` en vez de solo `select.value` (soporta `<select multiple>`),
+  añade `composed:true` al evento `input` (cruza shadow DOM) y `focus()` previo.
+  Firma intacta (no rompe el caller del MCP `dom_select_option`).
@@ -0,0 +1,82 @@
+package browser
+
+import (
+	"fmt"
+	"os"
+)
+
+// CdpSetFileInput sube archivos a un <input type="file"> identificado por el
+// selector CSS. Resuelve el nodo via DOM.getDocument + DOM.querySelector y luego
+// asigna los archivos con DOM.setFileInputFiles. Util para automatizar formularios
+// de subida sin simular el dialogo nativo de seleccion de archivos.
+//
+// Cada path de paths se valida con os.Stat ANTES de enviar el comando: si alguno
+// no existe (o no es accesible) se devuelve error inmediato sin tocar el DOM. Los
+// paths deben ser absolutos y accesibles por el proceso de Chrome (ver Gotchas en
+// el .md): Chrome lee los archivos desde su propio contexto, no desde el de este
+// programa.
+func CdpSetFileInput(c *CDPConn, selector string, paths []string) error {
+	if c == nil {
+		return fmt.Errorf("cdp set file input: conexion nula")
+	}
+	if selector == "" {
+		return fmt.Errorf("cdp set file input: selector vacio")
+	}
+	if len(paths) == 0 {
+		return fmt.Errorf("cdp set file input: lista de paths vacia")
+	}
+
+	// Validar que cada path exista en disco antes de mandar nada a Chrome.
+	for _, p := range paths {
+		if p == "" {
+			return fmt.Errorf("cdp set file input: path vacio en la lista")
+		}
+		if _, err := os.Stat(p); err != nil {
+			if os.IsNotExist(err) {
+				return fmt.Errorf("cdp set file input: el archivo no existe: %q", p)
+			}
+			return fmt.Errorf("cdp set file input: no se puede acceder al archivo %q: %w", p, err)
+		}
+	}
+
+	// Obtener el nodo raiz del documento.
+	docRes, err := c.sendCDP("DOM.getDocument", map[string]any{"depth": 0})
+	if err != nil {
+		return fmt.Errorf("cdp set file input: DOM.getDocument: %w", err)
+	}
+	root, ok := docRes["root"].(map[string]any)
+	if !ok {
+		return fmt.Errorf("cdp set file input: respuesta de DOM.getDocument sin root")
+	}
+	rootNodeID, ok := root["nodeId"].(float64)
+	if !ok {
+		return fmt.Errorf("cdp set file input: DOM.getDocument sin nodeId raiz")
+	}
+
+	// Resolver el input por selector.
+	qsRes, err := c.sendCDP("DOM.querySelector", map[string]any{
+		"nodeId":   int(rootNodeID),
+		"selector": selector,
+	})
+	if err != nil {
+		return fmt.Errorf("cdp set file input: DOM.querySelector %q: %w", selector, err)
+	}
+	nodeIDVal, ok := qsRes["nodeId"].(float64)
+	if !ok || int(nodeIDVal) == 0 {
+		return fmt.Errorf("cdp set file input: el selector %q no coincide con ningun elemento", selector)
+	}
+
+	// Asignar los archivos al input.
+	files := make([]any, len(paths))
+	for i, p := range paths {
+		files[i] = p
+	}
+	if _, err := c.sendCDP("DOM.setFileInputFiles", map[string]any{
+		"files":  files,
+		"nodeId": int(nodeIDVal),
+	}); err != nil {
+		return fmt.Errorf("cdp set file input: DOM.setFileInputFiles en %q: %w", selector, err)
+	}
+
+	return nil
+}
@@ -0,0 +1,79 @@
+---
+name: cdp_set_file_input
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpSetFileInput(c *CDPConn, selector string, paths []string) error"
+description: "Sube archivos a un <input type=\"file\"> identificado por selector CSS, sin abrir el dialogo nativo de seleccion de archivos. Resuelve el nodo via DOM.getDocument + DOM.querySelector y asigna los archivos con DOM.setFileInputFiles. Valida con os.Stat que cada path exista en disco antes de tocar el DOM."
+tags: [chrome, cdp, browser, automation, upload, file, input, form, dom, devtools]
+uses_functions: [cdp_connect_go_browser]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, os]
+params:
+  - name: c
+    desc: "conexión CDP activa (*CDPConn)"
+  - name: selector
+    desc: "selector CSS del <input type=\"file\"> destino (ej. 'input[type=file]', '#avatar')"
+  - name: paths
+    desc: "rutas absolutas de los archivos a subir; cada una debe existir y ser accesible por el proceso Chrome"
+output: "error si algún path no existe, si el selector no coincide con ningún nodo, o si falla el comando CDP; nil si los archivos quedaron asignados al input"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/browser/cdp_set_file_input.go"
+---
+
+## Ejemplo
+
+```go
+conn, _ := CdpConnect(9222)
+CdpNavigate(conn, "https://example.com/upload")
+
+// Subir un solo archivo
+err := CdpSetFileInput(conn, "input[type=file]", []string{"/home/enmanuel/docs/cv.pdf"})
+if err != nil {
+    log.Fatal(err)
+}
+
+// Subir varios archivos a un input con multiple
+err = CdpSetFileInput(conn, "#gallery", []string{
+    "/home/enmanuel/fotos/1.jpg",
+    "/home/enmanuel/fotos/2.jpg",
+})
+if err != nil {
+    log.Fatal(err)
+}
+```
+
+## Cuando usarla
+
+Cuando automatices un formulario web de subida de archivos y necesites rellenar un
+`<input type="file">` sin poder interactuar con el dialogo nativo del sistema
+operativo (que CDP no puede manejar haciendo click). Llamala despues de navegar a
+la pagina y de que el input exista en el DOM; combina con `CdpWaitElement` si el
+input aparece de forma dinamica.
+
+## Gotchas
+
+- **Los paths deben ser ABSOLUTOS y accesibles por el proceso de Chrome**, no por
+  este programa. Chrome lee los archivos desde su propio contexto/usuario; un path
+  relativo o un archivo en un directorio que Chrome no puede leer fallara en el
+  navegador aunque `os.Stat` pase localmente (caso tipico: Chrome corriendo en otro
+  usuario, contenedor o maquina remota via CDP).
+- La validacion `os.Stat` se ejecuta en la maquina donde corre esta funcion. Si el
+  Chrome del CDP esta en otra maquina/contenedor, que `os.Stat` pase NO garantiza
+  que Chrome encuentre el archivo. En ese escenario los paths deben ser validos en
+  el filesystem de Chrome.
+- El selector debe apuntar a un `<input type="file">` real. Apuntar a un boton o
+  label que dispara el dialogo nativo no funciona: hay que resolver el input
+  subyacente.
+- Asignar mas de un archivo requiere que el input tenga el atributo `multiple`; si
+  no lo tiene, Chrome puede rechazar o quedarse solo con el primero.
+- No dispara automaticamente el submit del formulario ni eventos `change`
+  personalizados mas alla de los que el propio CDP emite al asignar los archivos;
+  si la pagina depende de listeners adicionales, comprueba el comportamiento.
@@ -14,3 +14,17 @@ func CdpTypeRef(c *CDPConn, backendNodeID int, text string) error {
 	}
 	return CdpTypeText(c, text)
 }
+
+// CdpTypeRefFast enfoca el elemento del #ref e inserta el texto en UN solo
+// round-trip (Input.insertText), sin teclear caracter por caracter. Es el camino
+// rápido del modo automático: equivale a focus(ref) → CdpInsertText. Para sitios
+// con detección por pulsación usa CdpTypeRef (modo human, char por char).
+func CdpTypeRefFast(c *CDPConn, backendNodeID int, text string) error {
+	if c == nil {
+		return fmt.Errorf("cdp type ref fast: conexión nil")
+	}
+	if _, err := c.sendCDP("DOM.focus", map[string]any{"backendNodeId": backendNodeID}); err != nil {
+		return fmt.Errorf("cdp type ref fast: focus ref %d: %w", backendNodeID, err)
+	}
+	return CdpInsertText(c, text)
+}
@@ -3,10 +3,10 @@ name: cdp_type_ref
 kind: function
 lang: go
 domain: browser
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "func CdpTypeRef(c *CDPConn, backendNodeID int, text string) error"
-description: "Enfoca el elemento identificado por su #ref del AX outline vía DOM.focus y escribe el texto dado usando CdpTypeText. El #ref es el backendDOMNodeId estable del nodo DOM. El elemento debe aceptar input de texto (input, textarea, contenteditable)."
+description: "Enfoca el elemento identificado por su #ref del AX outline vía DOM.focus y escribe el texto dado usando CdpTypeText (carácter a carácter, camino human). El #ref es el backendDOMNodeId estable del nodo DOM. Para el camino rápido (un solo round-trip Input.insertText) hay CdpTypeRefFast. El elemento debe aceptar input de texto (input, textarea, contenteditable)."
 tags: [cdp, browser, action, ref, humanized, navegator]
 uses_functions: [cdp_type_text_go_browser]
 uses_types: []
@@ -49,3 +49,7 @@ Tras `page_perceive` / `render_ax_outline`, cuando el agente quiere escribir en
 - `DOM.focus` falla si el elemento no es focusable (no es `input`, `textarea`, `contenteditable`, o similar). El error indica el ref y la causa.
 - Si el elemento necesita un click previo para activarse (algunos inputs con JS custom), combinar con `CdpClickRef` antes de `CdpTypeRef`.
 - No hace scroll previo — si el elemento no está visible en el viewport el focus CDP puede fallar en algunos navegadores. Combinar con `CdpClickRef` (que sí hace scroll) si hay dudas.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-13) — Nueva función hermana `CdpTypeRefFast`: enfoca el #ref e inserta el texto en un solo round-trip (`Input.insertText`) en vez de teclear carácter a carácter. Es el camino rápido del modo automático del MCP (`dom_type_ref` con `mode=auto`); `CdpTypeRef` queda como el camino human (carácter a carácter con pausas aleatorias) para sitios con detección por pulsación.
@@ -2,27 +2,38 @@ package browser

 import (
 	"fmt"
+	"math/rand"
 	"strings"
 	"time"
 )

-// CdpTypeText escribe texto en el elemento activo de la pagina caracter por caracter.
-// Usa Input.dispatchKeyEvent para simular pulsaciones de teclado reales.
-// Recomienda usar CdpClick primero para enfocar el elemento objetivo.
+// assertEditableFocus verifica que el activeElement de la pagina acepta texto
+// (input/textarea/select/contentEditable). Sin foco, los caracteres se pierden
+// silenciosamente (van a document.body); devolvemos un error claro en vez de
+// "escribir a la nada". Compartido por CdpTypeText (camino human) y CdpInsertText
+// (camino rapido).
+func assertEditableFocus(c *CDPConn) error {
+	focus, ferr := CdpEvaluate(c, `(function(){var a=document.activeElement;if(!a)return 'none';var t=a.tagName.toLowerCase();return (t==='input'||t==='textarea'||t==='select'||a.isContentEditable)?'ok':t;})()`)
+	if ferr != nil {
+		return fmt.Errorf("verificar foco: %w", ferr)
+	}
+	if strings.TrimSpace(focus) != "ok" {
+		return fmt.Errorf("no hay campo de texto enfocado (activeElement: %s); enfoca el input primero", strings.TrimSpace(focus))
+	}
+	return nil
+}
+
+// CdpTypeText escribe texto en el elemento activo de la pagina caracter por
+// caracter, con una pausa ALEATORIA entre teclas. Es el camino "human": emite
+// keyDown/keyUp reales por tecla (sitios que validan pulsacion a pulsacion
+// reaccionan) y el ritmo irregular reduce la deteccion de automatizacion. Para el
+// camino rapido (modo auto) usa CdpInsertText: un solo round-trip, sin teclear.
 func CdpTypeText(c *CDPConn, text string) error {
 	if c == nil {
 		return fmt.Errorf("cdp type text: conexion nula")
 	}
-
-	// Verificar que hay un campo editable enfocado. Sin foco, los caracteres se
-	// pierden silenciosamente (van a document.body). Devolvemos error claro en vez
-	// de "escribir a la nada".
-	focus, ferr := CdpEvaluate(c, `(function(){var a=document.activeElement;if(!a)return 'none';var t=a.tagName.toLowerCase();return (t==='input'||t==='textarea'||t==='select'||a.isContentEditable)?'ok':t;})()`)
-	if ferr != nil {
-		return fmt.Errorf("cdp type text: verificar foco: %w", ferr)
-	}
-	if strings.TrimSpace(focus) != "ok" {
-		return fmt.Errorf("cdp type text: no hay campo de texto enfocado (activeElement: %s); usa CdpClick sobre el input primero", strings.TrimSpace(focus))
+	if err := assertEditableFocus(c); err != nil {
+		return fmt.Errorf("cdp type text: %w", err)
 	}

 	// keyDown (con `text`) ya inserta el caracter en el elemento focado en
@@ -49,9 +60,28 @@ func CdpTypeText(c *CDPConn, text string) error {
 			return fmt.Errorf("cdp type text: keyUp %q: %w", charStr, err)
 		}

-		// Pequena pausa entre caracteres para simular escritura humana.
-		time.Sleep(10 * time.Millisecond)
+		// Pausa ALEATORIA entre caracteres (15-65 ms) para imitar el ritmo
+		// irregular de un humano escribiendo, en vez de un intervalo de maquina fijo.
+		time.Sleep(time.Duration(15+rand.Intn(51)) * time.Millisecond)
 	}

 	return nil
 }
+
+// CdpInsertText inserta todo el texto en el elemento enfocado en UN solo
+// round-trip via Input.insertText. Es el camino rapido del modo automatico: no
+// emite keyDown/keyUp por tecla, por lo que sitios que validan pulsacion a
+// pulsacion (autocompletes muy estrictos) pueden no reaccionar — para esos casos
+// usa CdpTypeText (modo human). Requiere un campo editable enfocado.
+func CdpInsertText(c *CDPConn, text string) error {
+	if c == nil {
+		return fmt.Errorf("cdp insert text: conexion nula")
+	}
+	if err := assertEditableFocus(c); err != nil {
+		return fmt.Errorf("cdp insert text: %w", err)
+	}
+	if _, err := c.sendCDP("Input.insertText", map[string]any{"text": text}); err != nil {
+		return fmt.Errorf("cdp insert text: %w", err)
+	}
+	return nil
+}
@@ -3,11 +3,11 @@ name: cdp_type_text
 kind: function
 lang: go
 domain: browser
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "func CdpTypeText(c *CDPConn, text string) error"
-description: "Escribe texto en el elemento activo de la pagina caracter por caracter via Input.dispatchKeyEvent. Envia eventos keyDown, char y keyUp por cada caracter con 10ms de pausa entre ellos. Usar CdpClick primero para enfocar el elemento."
-tags: [chrome, cdp, browser, automation, keyboard, input, devtools]
+description: "Escribe texto en el elemento activo de la pagina caracter por caracter via Input.dispatchKeyEvent (camino human). Envia keyDown+keyUp por cada caracter con una pausa ALEATORIA (15-65ms) que imita el ritmo irregular humano. Para el camino rapido (un solo round-trip, sin teclear) usa CdpInsertText. Usar CdpClick primero para enfocar el elemento."
+tags: [chrome, cdp, browser, automation, keyboard, input, devtools, navegator]
 uses_functions: [cdp_connect_go_browser]
 uses_types: []
 returns: []
@@ -39,4 +39,10 @@ CdpTypeText(conn, "golang websocket")

 ## Notas

-Envia tres eventos por caracter: `keyDown`, `char` (dispara el evento `input` del DOM) y `keyUp`. La pausa de 10ms entre caracteres simula escritura humana y ayuda con inputs que tienen debounce. Para texto largo, considerar inyectar directamente via `CdpEvaluate` con `element.value = "..."` + evento `input`.
+Envia dos eventos por caracter: `keyDown` (con `text`, que ya inserta el caracter en Chrome) y `keyUp`. No envia un evento `char` extra: lo duplicaba en sitios que reaccionan a eventos `input` (DuckDuckGo, Google). La pausa ALEATORIA de 15-65ms entre caracteres imita el ritmo irregular humano (reduce deteccion) y ayuda con inputs que tienen debounce.
+
+Para el camino rapido del modo automatico hay `CdpInsertText` (todo el texto en un solo `Input.insertText`, sin keyDown/keyUp por tecla) — mucho mas rapido, pero sitios que validan pulsacion a pulsacion pueden no reaccionar. Para texto largo donde no importa el sigilo, `CdpInsertText` es preferible.
+
+## Capability growth log
+
+- v1.1.0 (2026-06-13) — La pausa entre caracteres pasa de 10ms fija a aleatoria 15-65ms (ritmo no-máquina). Nueva función hermana `CdpInsertText`: inserta todo el texto en un solo round-trip (`Input.insertText`) para el modo automático rápido. Se extrajo el chequeo de foco a `assertEditableFocus` (compartido).
@@ -0,0 +1,343 @@
+package browser
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// actionableBackoff es el calendario de espera entre reintentos del bucle de
+// actionability, copiado del _retryAction de Playwright (waitTime [0,20,100,100,500]).
+// Tras agotar la tabla, se mantiene en el ultimo valor (500ms) hasta el timeout.
+// El primer intento es inmediato (0ms): muchas veces el elemento ya esta listo.
+var actionableBackoff = []time.Duration{
+	0,
+	20 * time.Millisecond,
+	100 * time.Millisecond,
+	100 * time.Millisecond,
+	500 * time.Millisecond,
+}
+
+// actionableScrollAligns rota la alineacion block de scrollIntoView entre
+// reintentos. Cyclar las alineaciones (center/start/end) destraba casos donde un
+// header position:sticky o un footer fijo tapa el punto al alinear de una sola
+// forma — replica el scrollOptions cycling de _retryPointerAction de Playwright.
+var actionableScrollAligns = []string{"center", "start", "end"}
+
+// actionableResult es el veredicto que el JS inyectado devuelve por iteracion.
+// state describe el primer estado que fallo (para el mensaje de error final);
+// x,y son el punto central listo para el pointer cuando ok==true.
+type actionableResult struct {
+	OK     bool    `json:"ok"`
+	State  string  `json:"state"`  // "visible" | "stable" | "enabled" | "inviewport" | "intercepted" | "notconnected"
+	Detail string  `json:"detail"` // descripcion del interceptor u otro detalle
+	X      float64 `json:"x"`      // punto central viewport (CSS px)
+	Y      float64 `json:"y"`      //
+	PageX  float64 `json:"pageX"`  // punto central en coords de pagina (scroll incluido)
+	PageY  float64 `json:"pageY"`  //
+}
+
+// CdpWaitActionable bloquea hasta que el elemento identificado por backendNodeID
+// sea accionable (listo para recibir un click/hover fiable) o expire timeout.
+// Reproduce el modelo de actionability de Playwright: en cada iteracion comprueba
+// que el elemento esta visible, estable (mismo rect en dos requestAnimationFrame
+// consecutivos), opcionalmente enabled, dentro del viewport tras scrollIntoView,
+// y que el hit-test (document.elementFromPoint subiendo por shadow DOM) apunta al
+// propio nodo o a un descendiente. Si algo falla, espera con backoff
+// [0,20,100,100,500]ms (luego 500ms constante) y reintenta, rotando la alineacion
+// del scroll para destrabar overlays sticky.
+//
+// Devuelve el punto central (x,y) en coordenadas de viewport (CSS px), listo para
+// Input.dispatchMouseEvent. Al expirar, el error indica QUE estado fallo en el
+// ultimo intento (not visible / not stable / disabled / outside viewport /
+// intercepted by other element).
+//
+// needEnabled controla si se exige el estado enabled (no `disabled`,
+// `aria-disabled="true"`, ni dentro de un <fieldset disabled>). Pasar false para
+// elementos no interactivos (texto, contenedores) donde enabled no aplica.
+func CdpWaitActionable(c *CDPConn, backendNodeID int, needEnabled bool, timeout time.Duration) (x float64, y float64, err error) {
+	if c == nil {
+		return 0, 0, fmt.Errorf("cdp wait actionable: conexión nil")
+	}
+	if timeout <= 0 {
+		timeout = 5 * time.Second
+	}
+
+	// Resolver el backendNodeID a un objectId una sola vez. El objectId apunta al
+	// nodo DOM vivo y se reutiliza en cada iteracion via Runtime.callFunctionOn,
+	// evitando un resolveNode por reintento.
+	res, err := c.sendCDP("DOM.resolveNode", map[string]any{"backendNodeId": backendNodeID})
+	if err != nil {
+		return 0, 0, fmt.Errorf("cdp wait actionable: resolveNode ref %d: %w", backendNodeID, err)
+	}
+	obj, _ := res["object"].(map[string]any)
+	objID, _ := obj["objectId"].(string)
+	if objID == "" {
+		return 0, 0, fmt.Errorf("cdp wait actionable: sin objectId para ref %d (nodo inexistente)", backendNodeID)
+	}
+
+	deadline := time.Now().Add(timeout)
+	var last actionableResult
+	last.State = "visible" // estado por defecto si nunca llegamos a evaluar
+
+	for retry := 0; ; retry++ {
+		// Espera con backoff antes de reintentar (el primer intento es inmediato).
+		if retry > 0 {
+			wait := actionableBackoff[len(actionableBackoff)-1]
+			if retry-1 < len(actionableBackoff) {
+				wait = actionableBackoff[retry-1]
+			}
+			if wait > 0 {
+				// No dormir mas alla del deadline.
+				if remaining := time.Until(deadline); remaining < wait {
+					wait = remaining
+				}
+				if wait > 0 {
+					time.Sleep(wait)
+				}
+			}
+		}
+
+		align := actionableScrollAligns[retry%len(actionableScrollAligns)]
+		r, evalErr := evalActionable(c, objID, needEnabled, align)
+		if evalErr != nil {
+			// Un error de protocolo (tab cerrada, nodo liberado) es terminal: no
+			// tiene sentido reintentar sobre un objectId muerto.
+			return 0, 0, fmt.Errorf("cdp wait actionable: ref %d: %w", backendNodeID, evalErr)
+		}
+		last = r
+
+		if r.OK {
+			return r.X, r.Y, nil
+		}
+		if r.State == "notconnected" {
+			// El nodo dejo de estar conectado al DOM — reintentar no lo revivira.
+			return 0, 0, fmt.Errorf("cdp wait actionable: ref %d desconectado del DOM", backendNodeID)
+		}
+
+		if time.Now().After(deadline) {
+			break
+		}
+	}
+
+	return 0, 0, fmt.Errorf("cdp wait actionable: ref %d no accionable tras %s: %s", backendNodeID, timeout, describeActionableFailure(last))
+}
+
+// describeActionableFailure traduce el estado fallido a un mensaje humano.
+func describeActionableFailure(r actionableResult) string {
+	switch r.State {
+	case "visible":
+		return "not visible (display:none, visibility:hidden, opacity:0 o tamaño 0)"
+	case "stable":
+		return "not stable (el rect sigue cambiando entre frames; animación o layout en curso)"
+	case "enabled":
+		return "disabled (atributo disabled, aria-disabled=true o <fieldset disabled>)"
+	case "inviewport":
+		return "outside of the viewport (scrollIntoView no logró revelarlo)"
+	case "intercepted":
+		if r.Detail != "" {
+			return "intercepted by other element: " + r.Detail
+		}
+		return "intercepted by other element (overlay capta el pointer en el punto central)"
+	case "notconnected":
+		return "not connected to the DOM"
+	default:
+		if r.State != "" {
+			return "not " + r.State
+		}
+		return "estado desconocido"
+	}
+}
+
+// evalActionable corre una iteracion completa de chequeos en el contexto JS de la
+// pagina, sobre el nodo apuntado por objID. Devuelve el veredicto serializado.
+//
+// El JS hace, en orden y cortocircuitando al primer fallo:
+//  1. visible: tiene client rects y computed style no lo oculta.
+//  2. stable: getBoundingClientRect identico en dos requestAnimationFrame seguidos.
+//  3. enabled (si needEnabled): no disabled / aria-disabled=true / dentro de
+//     <fieldset disabled> (subiendo por la jerarquia, como getAriaDisabled).
+//  4. scrollIntoView con la alineacion dada + comprobacion de que el centro cae
+//     dentro del viewport.
+//  5. hit-test: elementFromPoint en el punto central, subiendo por shadow roots
+//     (assignedSlot / parentNode.host) y comprobando que el elemento golpeado es
+//     el target o uno de sus descendientes.
+func evalActionable(c *CDPConn, objID string, needEnabled bool, scrollAlign string) (actionableResult, error) {
+	params := map[string]any{
+		"objectId":            objID,
+		"functionDeclaration": actionableJS,
+		"arguments": []any{
+			map[string]any{"value": needEnabled},
+			map[string]any{"value": scrollAlign},
+		},
+		"awaitPromise":  true,
+		"returnByValue": true,
+	}
+	result, err := c.sendCDP("Runtime.callFunctionOn", params)
+	if err != nil {
+		return actionableResult{}, err
+	}
+	if exc, ok := result["exceptionDetails"]; ok && exc != nil {
+		excMap, _ := exc.(map[string]any)
+		text, _ := excMap["text"].(string)
+		return actionableResult{}, fmt.Errorf("excepción JS en chequeo de actionability: %s", text)
+	}
+	resVal, ok := result["result"].(map[string]any)
+	if !ok {
+		return actionableResult{}, fmt.Errorf("resultado inesperado: %v", result)
+	}
+	raw, ok := resVal["value"]
+	if !ok {
+		return actionableResult{}, fmt.Errorf("chequeo de actionability sin valor de retorno")
+	}
+	// returnByValue=true entrega el objeto JS ya deserializado a map[string]any;
+	// lo re-marshalamos para decodificar en el struct tipado de forma robusta.
+	b, err := json.Marshal(raw)
+	if err != nil {
+		return actionableResult{}, fmt.Errorf("marshal resultado: %w", err)
+	}
+	var out actionableResult
+	if err := json.Unmarshal(b, &out); err != nil {
+		return actionableResult{}, fmt.Errorf("unmarshal resultado %q: %w", string(b), err)
+	}
+	return out, nil
+}
+
+// actionableJS es la funcion ejecutada sobre el nodo (this) via callFunctionOn.
+// Devuelve una Promise<actionableResult>. La logica replica checkElementStates +
+// _checkElementIsStable + expectHitTarget del injected script de Playwright,
+// adaptada a un solo paso autocontenido (sin caches ni dependencias externas).
+const actionableJS = `function(needEnabled, scrollAlign) {
+  var target = this;
+  var fail = function(state, detail) { return {ok:false, state:state, detail:detail||"", x:0, y:0, pageX:0, pageY:0}; };
+
+  if (!target || !target.isConnected) return Promise.resolve(fail("notconnected"));
+  if (target.nodeType !== 1) {
+    // Si el nodo no es un Element (ej. texto), intentar su elemento padre.
+    target = target.parentElement;
+    if (!target) return Promise.resolve(fail("notconnected"));
+  }
+
+  // 1) VISIBLE: rect con area + computed style no oculto.
+  var isVisible = function(el) {
+    if (!el || !el.isConnected) return false;
+    var rects = el.getClientRects();
+    if (!rects || rects.length === 0) return false;
+    var st = (el.ownerDocument && el.ownerDocument.defaultView)
+      ? el.ownerDocument.defaultView.getComputedStyle(el) : null;
+    if (st) {
+      if (st.visibility === "hidden" || st.display === "none") return false;
+      if (parseFloat(st.opacity || "1") === 0) return false;
+    }
+    var r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  if (!isVisible(target)) return Promise.resolve(fail("visible"));
+
+  // 2) ENABLED (opcional): disabled nativo, aria-disabled o <fieldset disabled>.
+  if (needEnabled) {
+    var isDisabled = function(el) {
+      var native = ["BUTTON","INPUT","SELECT","TEXTAREA","OPTION","OPTGROUP"];
+      var n = el;
+      while (n) {
+        if (n.nodeType === 1) {
+          var tag = (n.tagName || "").toUpperCase();
+          if (native.indexOf(tag) !== -1 && n.hasAttribute && n.hasAttribute("disabled")) return true;
+          // fieldset disabled deshabilita a sus controles (salvo dentro del legend).
+          if (tag === "FIELDSET" && n.hasAttribute && n.hasAttribute("disabled")) return true;
+          var ad = n.getAttribute && n.getAttribute("aria-disabled");
+          if (ad && ad.toLowerCase() === "true") return true;
+        }
+        // Subir por DOM y cruzar shadow boundaries.
+        n = n.parentElement || (n.parentNode && n.parentNode.host) || (n.assignedSlot || null);
+      }
+      return false;
+    };
+    if (isDisabled(target)) return Promise.resolve(fail("enabled"));
+  }
+
+  // 4) SCROLL INTO VIEW con la alineacion rotada por el caller.
+  try { target.scrollIntoView({block: scrollAlign, inline: scrollAlign, behavior: "instant"}); }
+  catch (e) { try { target.scrollIntoView(); } catch (e2) {} }
+
+  // 3) STABLE: comparar getBoundingClientRect en dos requestAnimationFrame seguidos.
+  var rectOf = function(el) {
+    var r = el.getBoundingClientRect();
+    return {x: r.left, y: r.top, w: r.width, h: r.height};
+  };
+  var rafTwice = function() {
+    return new Promise(function(res) {
+      requestAnimationFrame(function() { requestAnimationFrame(function() { res(); }); });
+    });
+  };
+
+  var first = rectOf(target);
+  return rafTwice().then(function() {
+    if (!target.isConnected) return fail("notconnected");
+    var second = rectOf(target);
+    var same = first.x === second.x && first.y === second.y && first.w === second.w && first.h === second.h;
+    if (!same) return fail("stable");
+
+    var r = second;
+    var vw = window.innerWidth || document.documentElement.clientWidth;
+    var vh = window.innerHeight || document.documentElement.clientHeight;
+    var cx = r.x + r.w / 2;
+    var cy = r.y + r.h / 2;
+
+    // 4b) IN VIEWPORT: el punto central debe caer dentro del viewport tras el scroll.
+    if (cx < 0 || cy < 0 || cx > vw || cy > vh) return fail("inviewport");
+
+    // 5) HIT-TEST: elementFromPoint subiendo por shadow roots; el golpeado debe ser
+    // el target o un descendiente suyo (cruzando shadow boundaries).
+    var enclosingRoot = function(el) {
+      var node = el;
+      while (node && node.parentNode) node = node.parentNode;
+      if (node && (node.nodeType === 11 || node.nodeType === 9)) return node;
+      return null;
+    };
+    var parentOrHost = function(el) {
+      if (el.parentElement) return el.parentElement;
+      if (el.parentNode && el.parentNode.nodeType === 11 && el.parentNode.host) return el.parentNode.host;
+      return null;
+    };
+
+    // Recolectar roots desde el target hacia arriba (document u shadow roots).
+    var roots = [];
+    var p = target;
+    while (p) {
+      var root = enclosingRoot(p);
+      if (!root) break;
+      roots.push(root);
+      if (root.nodeType === 9) break;
+      p = root.host;
+    }
+
+    // Hit en cada root debe apuntar al siguiente root; en el ultimo, al target/descendiente.
+    var hit = null;
+    for (var i = roots.length - 1; i >= 0; i--) {
+      var rt = roots[i];
+      var inner = rt.elementFromPoint ? rt.elementFromPoint(cx, cy) : null;
+      if (!inner) break;
+      hit = inner;
+      if (i && roots[i - 1] && inner !== roots[i - 1].host) break;
+    }
+    if (!hit) return fail("intercepted", "ningún elemento en el punto central");
+
+    // Subir desde el hit hasta el target (composed tree: assignedSlot primero).
+    var cur = hit;
+    while (cur && cur !== target) {
+      cur = cur.assignedSlot || parentOrHost(cur);
+    }
+    if (cur !== target) {
+      var desc = hit.tagName ? hit.tagName.toLowerCase() : "node";
+      if (hit.id) desc += "#" + hit.id;
+      else if (hit.className && typeof hit.className === "string" && hit.className.trim())
+        desc += "." + hit.className.trim().split(/\s+/)[0];
+      return fail("intercepted", desc);
+    }
+
+    var sx = window.scrollX || window.pageXOffset || 0;
+    var sy = window.scrollY || window.pageYOffset || 0;
+    return {ok:true, state:"ok", detail:"", x:cx, y:cy, pageX:cx + sx, pageY:cy + sy};
+  });
+}`
@@ -0,0 +1,85 @@
+---
+name: cdp_wait_actionable
+kind: function
+lang: go
+domain: browser
+version: "1.0.0"
+purity: impure
+signature: "func CdpWaitActionable(c *CDPConn, backendNodeID int, needEnabled bool, timeout time.Duration) (x float64, y float64, err error)"
+description: "Bloquea hasta que el elemento del #ref sea accionable (listo para un click/hover fiable) o expire timeout. Reproduce el modelo de actionability de Playwright: en bucle con backoff [0,20,100,100,500]ms comprueba visible (client rects + computed style), stable (mismo getBoundingClientRect en dos requestAnimationFrame seguidos), enabled opcional (disabled / aria-disabled / fieldset disabled subiendo la jerarquía), scroll into view rotando alineación block (center/start/end), y hit-test (elementFromPoint subiendo por shadow DOM apunta al target o descendiente). Devuelve el punto central (x,y) en coords de viewport listo para Input.dispatchMouseEvent. Al expirar, el error indica qué estado falló (not visible / not stable / disabled / outside viewport / intercepted by other element)."
+tags: [cdp, browser, action, ref, actionability, browser-actionability, navegator]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+tested: false
+tests: []
+test_file_path: ""
+params:
+  - name: c
+    desc: "Conexión CDP activa al tab objetivo."
+  - name: backendNodeID
+    desc: "El #ref del AX outline = backendDOMNodeId estable del nodo DOM. Se obtiene de page_perceive / render_ax_outline."
+  - name: needEnabled
+    desc: "Si true, exige también el estado enabled (no disabled, no aria-disabled=true, no dentro de <fieldset disabled>). Pasar false para elementos no interactivos (texto, contenedores) donde enabled no aplica."
+  - name: timeout
+    desc: "Tiempo máximo de espera antes de rendirse. <=0 usa 5s por defecto. El bucle de reintento nunca duerme más allá de este deadline."
+output: "(x, y) punto central del elemento en coordenadas de viewport (CSS px), listo para despachar el pointer, cuando todos los chequeos pasan; error si la conexión es nil, el nodo no resuelve a objectId, se desconecta del DOM, o expira el timeout (con el estado que falló al final)."
+file_path: "functions/browser/cdp_wait_actionable.go"
+---
+
+## Ejemplo
+
+```go
+// Tras un page_perceive que devuelve outline con #ref=1234, esperar a que el
+// elemento sea accionable y luego clicar el punto exacto que devuelve:
+conn, _ := CdpConnect(9222)
+x, y, err := CdpWaitActionable(conn, 1234, true, 5*time.Second)
+if err != nil {
+    log.Fatalf("no accionable: %v", err) // ej: "intercepted by other element: div#cookie-banner"
+}
+// x,y ya están en viewport, estables y sin overlay encima: click fiable.
+_ = CdpClickXYHuman(conn, x, y, MouseHumanOpts{})
+```
+
+## Cuando usarla
+
+Antes de CUALQUIER click/hover/type que deba ser fiable sobre un #ref del outline.
+Llamarla justo después de `page_perceive` y antes de `cdp_click_ref` /
+`cdp_click_xy_human` / `dom_*_ref` para evitar los fallos clásicos del navegador:
+clicar un botón que aún se está animando hacia su posición, un elemento tapado por
+un banner de cookies / modal / spinner, o un control todavía `disabled`. Es la
+puerta de actionability que separa "el nodo existe en el DOM" de "el nodo está
+listo para recibir el evento ahí donde lo voy a despachar". Usar `needEnabled=true`
+para botones/inputs/enlaces; `needEnabled=false` para hover sobre texto o medir un
+contenedor.
+
+## Gotchas
+
+- **Coste de polling.** Es síncrona y bloqueante: hace un `Runtime.callFunctionOn`
+  por iteración + 2 `requestAnimationFrame` por chequeo de estabilidad. En el peor
+  caso poll-ea hasta `timeout` con backoff creciente (0,20,100,100,500ms → 500ms).
+  No la metas en un bucle apretado sobre N elementos sin necesidad; una sola
+  llamada por acción es lo correcto. Timeouts altos sobre elementos que nunca
+  llegan (genuinamente ocultos) cuestan el timeout entero.
+- **Shadow DOM.** El hit-test sube por shadow roots (`assignedSlot` /
+  `parentNode.host`) y por eso funciona con web components con shadow root
+  *abierto*. Con shadow roots **cerrados** `elementFromPoint` no expone el interior
+  y el hit-test puede reportar `intercepted` erróneamente; en ese caso usar el
+  click vía `element.click()` (modo instant de `cdp_click_ref`), que no depende del
+  hit-test geométrico.
+- **iframes.** Opera sobre el contexto de la página/frame al que apunta el
+  `*CDPConn`. Un `backendNodeID` de otro frame no resuelve aquí: hay que tener la
+  conexión/contexto del frame correcto (ver `cdp_eval_in_frame`). Las coordenadas
+  devueltas son relativas al viewport de ESE documento, no compuestas con el offset
+  del iframe en la página padre.
+- **Estabilidad vs animaciones infinitas.** Un elemento con una animación CSS
+  perpetua que mueve su rect (spinner que se desplaza, marquee) nunca pasará el
+  chequeo `stable` y agotará el timeout con "not stable". Es comportamiento
+  correcto (no es accionable de forma fiable), pero conviene saberlo.
+- **El punto devuelto es (x,y) de viewport**, no de página. Es lo que
+  `Input.dispatchMouseEvent` espera. Si necesitas coords de página (con scroll),
+  el JS interno ya las calcula (`pageX/pageY`) pero la firma pública expone solo
+  las de viewport para encajar con el dispatch de pointer.
@@ -136,11 +136,14 @@ func CdpWaitIdle(c *CDPConn, opts CdpWaitIdleOpts) error {
 	})
 	defer cancel3()

-	// Habilitar dominio Network (igual que cdp_har_record).
-	if _, err := c.sendCDP("Network.enable", nil); err != nil {
+	// Habilitar dominio Network (idempotente, cacheado por conexion). NO lo
+	// deshabilitamos al salir: Network.disable borraria el estado y el siguiente
+	// wait_idle pagaria el enable de nuevo (round-trip extra). Los handlers de
+	// eventos se desregistran por sus cancel() de defer, que es lo unico necesario
+	// para dejar de contar.
+	if err := c.ensureNetwork(); err != nil {
 		return fmt.Errorf("cdp wait idle: Network.enable: %w", err)
 	}
-	defer c.sendCDP("Network.disable", nil) //nolint:errcheck

 	deadline := time.Now().Add(opts.Timeout)
 	pollInterval := time.Duration(opts.PollMs) * time.Millisecond
@@ -6,9 +6,11 @@ import (
 )

 // CdpWaitLoad espera a que la página actual termine de cargar completamente.
-// Hace polling de document.readyState via Runtime.evaluate cada 200ms hasta
-// que sea "complete", o hasta que se agote el timeout.
-// Retorna error si el timeout se agota o si CdpEvaluate falla (conexion rota).
+// Bloquea hasta recibir el evento CDP Page.loadEventFired (sin polling): suscribe
+// el evento via OnEvent y espera en un canal con timeout. Antes de esperar hace un
+// fast path comprobando document.readyState — si la página ya está "complete",
+// retorna de inmediato sin armar el handler.
+// Retorna error si el timeout se agota o si no logra habilitar el dominio Page.
 func CdpWaitLoad(c *CDPConn, timeout time.Duration) error {
 	if c == nil {
 		return fmt.Errorf("cdp wait load: conexion nula")
@@ -17,19 +19,35 @@ func CdpWaitLoad(c *CDPConn, timeout time.Duration) error {
 		timeout = 30 * time.Second
 	}

-	deadline := time.Now().Add(timeout)
-	interval := 200 * time.Millisecond
-
-	for time.Now().Before(deadline) {
-		result, err := CdpEvaluate(c, "document.readyState")
-		if err != nil {
-			return fmt.Errorf("cdp wait load: error evaluando readyState: %w", err)
-		}
-		if result == "complete" {
-			return nil
-		}
-		time.Sleep(interval)
+	// Fast path: si el documento ya terminó de cargar, no esperamos eventos.
+	if rs, err := CdpEvaluate(c, "document.readyState"); err == nil && rs == "complete" {
+		return nil
 	}

-	return fmt.Errorf("cdp wait load: pagina no cargo despues de %s", timeout)
+	// Habilitar Page (idempotente, cacheado) y suscribir el evento de carga.
+	if err := c.ensurePage(); err != nil {
+		return fmt.Errorf("cdp wait load: Page.enable: %w", err)
+	}
+	loaded := make(chan struct{}, 1)
+	cancel := c.OnEvent("Page.loadEventFired", func(_ string, _ map[string]any) {
+		select {
+		case loaded <- struct{}{}:
+		default:
+		}
+	})
+	defer cancel()
+
+	// Re-chequear readyState tras suscribir: si la carga terminó entre el fast
+	// path y el registro del handler, ya no llegaría el evento (carrera) — lo
+	// captamos aquí en vez de colgarnos hasta el timeout.
+	if rs, err := CdpEvaluate(c, "document.readyState"); err == nil && rs == "complete" {
+		return nil
+	}
+
+	select {
+	case <-loaded:
+		return nil
+	case <-time.After(timeout):
+		return fmt.Errorf("cdp wait load: pagina no cargo despues de %s", timeout)
+	}
 }
@@ -3,11 +3,11 @@ name: cdp_wait_load
 kind: function
 lang: go
 domain: browser
-version: "1.0.0"
+version: "1.1.0"
 purity: impure
 signature: "func CdpWaitLoad(c *CDPConn, timeout time.Duration) error"
-description: "Espera a que la pagina actual termine de cargar completamente. Hace polling de document.readyState via Runtime.evaluate cada 200ms hasta que sea \"complete\", o hasta que se agote el timeout. Retorna error inmediato si CdpEvaluate falla (la conexion puede estar rota)."
-tags: [chrome, cdp, browser, automation, wait, polling, devtools, readystate, load]
+description: "Espera a que la pagina actual termine de cargar completamente. Bloquea hasta recibir el evento CDP Page.loadEventFired (sin polling), con un fast path inicial de document.readyState: si ya esta complete, retorna de inmediato. Retorna error si se agota el timeout o si no logra habilitar el dominio Page."
+tags: [chrome, cdp, browser, automation, wait, event, devtools, readystate, load, loadeventfired, navegator]
 uses_functions: [cdp_evaluate_go_browser]
 uses_types: []
 returns: []
@@ -42,6 +42,10 @@ html, _ := CdpGetHTML(conn)

 ## Notas

-A diferencia de `CdpWaitElement`, que ignora errores de `CdpEvaluate` durante el polling (la pagina puede aun no estar lista), `CdpWaitLoad` retorna el error inmediatamente porque un fallo en `document.readyState` indica una conexion rota, no una condicion transitoria.
+Bloquea esperando el evento CDP `Page.loadEventFired` (sin polling). Antes de esperar hace un fast path con `document.readyState`: si la página ya está `complete`, retorna de inmediato sin armar el handler. Tras suscribir el evento re-chequea `readyState` una vez más para no perder la carga por una carrera entre el fast path y el registro del handler. Habilita el dominio `Page` vía `ensurePage` (cacheado por conexión, idempotente).

 Si `timeout <= 0` usa 30s por defecto (mas largo que `CdpWaitElement` porque la carga completa de red puede tardar mas que la aparicion de un elemento DOM).
+
+## Capability growth log
+
+- v1.1.0 (2026-06-13) — De polling de `document.readyState` cada 200ms a esperar el evento `Page.loadEventFired` (vía `OnEvent` + canal con timeout), con fast path inicial de `readyState`. Elimina los round-trips de polling y la cuantización de ±200ms: si la página ya está cargada retorna en microsegundos.
@@ -0,0 +1,347 @@
+package infra
+
+import (
+	"database/sql"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"text/tabwriter"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// ProjectCoverage reports how well a project registered in registry.db is
+// backed by a Gitea sub-repo and how many of its children (apps + analyses)
+// are actually cloned on disk. It is the engine of `fn doctor projects`.
+//
+// The audit only touches the local filesystem and registry.db: it never hits
+// the network nor the Gitea API, so it runs fast and requires no token.
+type ProjectCoverage struct {
+	ProjectID       string   `json:"project_id"`
+	DirPath         string   `json:"dir_path"`
+	HasGit          bool     `json:"has_git"`          // <root>/<dir_path>/.git exists as a directory
+	HasRemote       bool     `json:"has_remote"`       // git -C <dir> remote get-url origin returned a non-empty url
+	RepoURLDeclared bool     `json:"repo_url_declared"` // projects.repo_url != ""
+	ChildrenInDB    int      `json:"children_in_db"`   // apps + analyses with project_id = ProjectID
+	ChildrenCloned  int      `json:"children_cloned"`  // of those, how many have a .git on disk
+	ChildrenMissing int      `json:"children_missing"` // ChildrenInDB - ChildrenCloned (at risk when re-cloning)
+	Issues          []string `json:"issues"`           // e.g. "dir_not_found", "no_gitea_repo", "children_missing"
+}
+
+// AuditProjectsCoverage walks every row in the projects table and reports, per
+// project, whether it has a local git repo, whether that repo declares a remote
+// origin, whether its repo_url is filled in registry.db, and how many of its
+// children (apps + analyses) are cloned versus only known to the database.
+//
+// registryRoot is the repository root (the directory that holds registry.db).
+// All relative dir_path values are resolved against it.
+//
+// Returns an error only if registry.db cannot be opened or queried. Projects
+// whose directory is missing on disk are still reported, flagged with the
+// "dir_not_found" issue, so the caller can surface them rather than silently
+// dropping them.
+func AuditProjectsCoverage(registryRoot string) ([]ProjectCoverage, error) {
+	dbPath := filepath.Join(registryRoot, "registry.db")
+	dsn := fmt.Sprintf("file:%s?mode=ro&_foreign_keys=on", dbPath)
+	db, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("audit_projects_coverage: open db: %w", err)
+	}
+	defer db.Close()
+	if err := db.Ping(); err != nil {
+		return nil, fmt.Errorf("audit_projects_coverage: ping db: %w", err)
+	}
+
+	rows, err := db.Query(`SELECT id, COALESCE(dir_path,''), COALESCE(repo_url,'') FROM projects ORDER BY id`)
+	if err != nil {
+		return nil, fmt.Errorf("audit_projects_coverage: query projects: %w", err)
+	}
+	defer rows.Close()
+
+	var out []ProjectCoverage
+	for rows.Next() {
+		var pc ProjectCoverage
+		var dirPath, repoURL string
+		if err := rows.Scan(&pc.ProjectID, &dirPath, &repoURL); err != nil {
+			return nil, fmt.Errorf("audit_projects_coverage: scan project: %w", err)
+		}
+
+		// DirPath: use projects.dir_path; if empty, derive projects/<id>.
+		if dirPath == "" {
+			dirPath = filepath.Join("projects", pc.ProjectID)
+		}
+		pc.DirPath = dirPath
+		pc.RepoURLDeclared = repoURL != ""
+
+		absDir := dirPath
+		if !filepath.IsAbs(absDir) {
+			absDir = filepath.Join(registryRoot, dirPath)
+		}
+
+		dirFound := dirExists(absDir)
+		if !dirFound {
+			pc.Issues = append(pc.Issues, "dir_not_found")
+		} else {
+			pc.HasGit = dirExists(filepath.Join(absDir, ".git"))
+			if pc.HasGit {
+				pc.HasRemote = gitHasRemoteOrigin(absDir)
+			}
+		}
+
+		// Children: apps + analyses with this project_id.
+		children, err := projectChildren(db, pc.ProjectID)
+		if err != nil {
+			return nil, err
+		}
+		pc.ChildrenInDB = len(children)
+		for _, childDir := range children {
+			absChild := childDir
+			if !filepath.IsAbs(absChild) {
+				absChild = filepath.Join(registryRoot, childDir)
+			}
+			if dirExists(filepath.Join(absChild, ".git")) {
+				pc.ChildrenCloned++
+			}
+		}
+		pc.ChildrenMissing = pc.ChildrenInDB - pc.ChildrenCloned
+
+		// Issues derived from the gathered state.
+		if !pc.HasRemote && !pc.RepoURLDeclared {
+			pc.Issues = append(pc.Issues, "no_gitea_repo")
+		}
+		if pc.ChildrenMissing > 0 {
+			pc.Issues = append(pc.Issues, "children_missing")
+		}
+
+		out = append(out, pc)
+	}
+	return out, rows.Err()
+}
+
+// projectChildren returns the dir_path of every app and analysis whose
+// project_id matches the given project id.
+func projectChildren(db *sql.DB, projectID string) ([]string, error) {
+	var dirs []string
+	for _, table := range []string{"apps", "analysis"} {
+		q := fmt.Sprintf(`SELECT COALESCE(dir_path,'') FROM %s WHERE project_id = ?`, table)
+		rows, err := db.Query(q, projectID)
+		if err != nil {
+			return nil, fmt.Errorf("audit_projects_coverage: query %s children: %w", table, err)
+		}
+		for rows.Next() {
+			var dp string
+			if err := rows.Scan(&dp); err != nil {
+				rows.Close()
+				return nil, fmt.Errorf("audit_projects_coverage: scan %s child: %w", table, err)
+			}
+			if dp != "" {
+				dirs = append(dirs, dp)
+			}
+		}
+		if err := rows.Err(); err != nil {
+			rows.Close()
+			return nil, err
+		}
+		rows.Close()
+	}
+	return dirs, nil
+}
+
+// gitHasRemoteOrigin reports whether the git repo at dir declares an origin
+// remote with a non-empty URL. It shells out to `git -C <dir> remote get-url
+// origin` and treats exit 0 with non-empty output as success. Any error
+// (no origin, not a repo, git missing) is reported as false.
+func gitHasRemoteOrigin(dir string) bool {
+	cmd := exec.Command("git", "-C", dir, "remote", "get-url", "origin")
+	outBytes, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+	return strings.TrimSpace(string(outBytes)) != ""
+}
+
+// FormatProjectsCoverage renders a tabwriter table, one row per project, with
+// git / remote / repo_url presence, children cloned vs declared, and the
+// issues list. When no project has coverage problems it makes that explicit.
+func FormatProjectsCoverage(rows []ProjectCoverage) string {
+	var sb strings.Builder
+	w := tabwriter.NewWriter(&sb, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(w, "PROJECT\tGIT\tREMOTE\tREPO_URL\tCHILDREN\tISSUES")
+
+	withIssues := 0
+	for _, r := range rows {
+		issues := "-"
+		if len(r.Issues) > 0 {
+			issues = strings.Join(r.Issues, "; ")
+			withIssues++
+		}
+		fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%d/%d\t%s\n",
+			r.ProjectID,
+			checkMark(r.HasGit),
+			checkMark(r.HasRemote),
+			checkMark(r.RepoURLDeclared),
+			r.ChildrenCloned, r.ChildrenInDB,
+			issues,
+		)
+	}
+	w.Flush()
+
+	if len(rows) == 0 {
+		sb.WriteString("\nNo projects registered.\n")
+		return sb.String()
+	}
+	if withIssues == 0 {
+		sb.WriteString("\n0 projects con problemas de cobertura.\n")
+	} else {
+		fmt.Fprintf(&sb, "\n%d/%d projects con problemas de cobertura.\n", withIssues, len(rows))
+	}
+	return sb.String()
+}
+
+// checkMark returns ✓ for true, ✗ for false.
+func checkMark(b bool) string {
+	if b {
+		return "✓"
+	}
+	return "✗"
+}
+
+// OrphanProjectRef describes a project_id that one or more children (apps and
+// analyses) reference in registry.db but for which no row exists in the projects
+// table. This is the inverse drift of AuditProjectsCoverage: instead of a
+// registered project whose children are not cloned, it surfaces an umbrella
+// project that was never synced to this PC (or never created here at all), so
+// the children are pointing at a project that this registry does not know about.
+// That is a data-loss risk: the umbrella project may exist on another machine
+// and the link would be silently broken on a clone/sync into this one.
+type OrphanProjectRef struct {
+	ProjectID string   `json:"project_id"` // referenced by children but missing from projects
+	Apps      []string `json:"apps"`       // ids of apps that reference it (sorted)
+	Analyses  []string `json:"analyses"`   // ids of analyses that reference it (sorted)
+}
+
+// FindOrphanProjectRefs scans every app and analysis that declares a non-empty
+// project_id and reports those project_id values that have no matching row in
+// the projects table. Each orphan groups the ids of the apps and analyses that
+// reference it.
+//
+// registryRoot is the repository root (the directory that holds registry.db).
+//
+// The result is sorted by ProjectID, and within each entry the Apps and
+// Analyses lists are sorted alphabetically. When every child references a known
+// project, an empty (non-nil) slice is returned with a nil error.
+//
+// Like AuditProjectsCoverage it only reads registry.db (opened read-only) and
+// never touches the network nor the Gitea API. Returns an error only when
+// registry.db cannot be opened or queried.
+func FindOrphanProjectRefs(registryRoot string) ([]OrphanProjectRef, error) {
+	dbPath := filepath.Join(registryRoot, "registry.db")
+	dsn := fmt.Sprintf("file:%s?mode=ro&_foreign_keys=on", dbPath)
+	db, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("find_orphan_project_refs: open db: %w", err)
+	}
+	defer db.Close()
+	if err := db.Ping(); err != nil {
+		return nil, fmt.Errorf("find_orphan_project_refs: ping db: %w", err)
+	}
+
+	// Set of known project ids.
+	known := map[string]bool{}
+	prows, err := db.Query(`SELECT id FROM projects`)
+	if err != nil {
+		return nil, fmt.Errorf("find_orphan_project_refs: query projects: %w", err)
+	}
+	for prows.Next() {
+		var id string
+		if err := prows.Scan(&id); err != nil {
+			prows.Close()
+			return nil, fmt.Errorf("find_orphan_project_refs: scan project: %w", err)
+		}
+		known[id] = true
+	}
+	if err := prows.Err(); err != nil {
+		prows.Close()
+		return nil, err
+	}
+	prows.Close()
+
+	// Accumulate orphan references from apps and analyses.
+	orphans := map[string]*OrphanProjectRef{}
+
+	get := func(pid string) *OrphanProjectRef {
+		o, ok := orphans[pid]
+		if !ok {
+			o = &OrphanProjectRef{ProjectID: pid}
+			orphans[pid] = o
+		}
+		return o
+	}
+
+	for _, table := range []string{"apps", "analysis"} {
+		q := fmt.Sprintf(`SELECT id, project_id FROM %s WHERE project_id != ''`, table)
+		rows, err := db.Query(q)
+		if err != nil {
+			return nil, fmt.Errorf("find_orphan_project_refs: query %s: %w", table, err)
+		}
+		for rows.Next() {
+			var id, pid string
+			if err := rows.Scan(&id, &pid); err != nil {
+				rows.Close()
+				return nil, fmt.Errorf("find_orphan_project_refs: scan %s row: %w", table, err)
+			}
+			if known[pid] {
+				continue
+			}
+			o := get(pid)
+			if table == "apps" {
+				o.Apps = append(o.Apps, id)
+			} else {
+				o.Analyses = append(o.Analyses, id)
+			}
+		}
+		if err := rows.Err(); err != nil {
+			rows.Close()
+			return nil, err
+		}
+		rows.Close()
+	}
+
+	out := make([]OrphanProjectRef, 0, len(orphans))
+	for _, o := range orphans {
+		sort.Strings(o.Apps)
+		sort.Strings(o.Analyses)
+		out = append(out, *o)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ProjectID < out[j].ProjectID })
+	return out, nil
+}
+
+// FormatOrphanProjectRefs renders a human-readable report of orphan project_id
+// references, one block per orphan, listing how many apps and analyses point at
+// the missing project plus their ids. When there are no orphans it makes that
+// explicit on a single line.
+func FormatOrphanProjectRefs(rows []OrphanProjectRef) string {
+	if len(rows) == 0 {
+		return "0 project_id huérfanos (todos los hijos tienen project declarado)\n"
+	}
+
+	var sb strings.Builder
+	w := tabwriter.NewWriter(&sb, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(w, "PROJECT_ID\tAPPS\tANALYSES\tREFERENCED_BY")
+	for _, r := range rows {
+		refs := append(append([]string{}, r.Apps...), r.Analyses...)
+		refStr := strings.Join(refs, ", ")
+		if refStr == "" {
+			refStr = "-"
+		}
+		fmt.Fprintf(w, "%s\t%d\t%d\t%s\n",
+			r.ProjectID, len(r.Apps), len(r.Analyses), refStr)
+	}
+	w.Flush()
+
+	fmt.Fprintf(&sb, "\n%d project_id huérfanos (referenciados por hijos pero sin fila en projects).\n", len(rows))
+	return sb.String()
+}
@@ -0,0 +1,109 @@
+---
+name: audit_projects_coverage
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func AuditProjectsCoverage(registryRoot string) ([]ProjectCoverage, error)"
+description: "Audita la cobertura de los projects del registry frente a sus sub-repos Gitea: comprueba si cada project tiene .git local, remote origin y repo_url declarado, y cuantos de sus hijos (apps + analyses) estan clonados en disco versus solo conocidos por la BD. Motor del subcomando fn doctor projects. Solo lee registry.db + filesystem + git local, nunca la red ni la API de Gitea. Incluye FindOrphanProjectRefs, el check inverso: detecta apps o analyses que declaran un project_id sin fila en la tabla projects (project paraguas huerfano, riesgo de perdida al sincronizar)."
+tags: [projects, gitea, subrepo, audit, infra, fn-doctor, doctor]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["database/sql", "os/exec", "path/filepath", "strings", "text/tabwriter", "github.com/mattn/go-sqlite3"]
+tested: true
+tests: ["healthy project con un hijo sin clonar marca children_missing", "project sin repo_url ni remote marca no_gitea_repo", "project sin directorio en disco marca dir_not_found", "error si registry.db no existe", "repo con origin devuelve true", "repo sin origin devuelve false", "sin issues lo deja claro", "con issues cuenta los afectados", "app con project_id huerfano lo detecta y agrupa ordenado", "app con project_id valido no aparece", "sin huerfanos devuelve slice vacio sin error", "sin huerfanos lo deja claro", "con huerfanos lista ids y cuenta"]
+test_file_path: "functions/infra/audit_projects_coverage_test.go"
+file_path: "functions/infra/audit_projects_coverage.go"
+params:
+  - name: registryRoot
+    desc: "Raiz del repositorio (el directorio que contiene registry.db). Los dir_path relativos de projects, apps y analysis se resuelven contra esta raiz."
+output: "Slice de ProjectCoverage, una entrada por fila de la tabla projects, con flags de git/remote/repo_url, conteos de hijos clonados vs declarados, y la lista de issues detectados. La funcion de formato FormatProjectsCoverage produce una tabla de texto humano."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	rows, err := infra.AuditProjectsCoverage("/home/enmanuel/fn_registry")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(infra.FormatProjectsCoverage(rows))
+}
+```
+
+Salida típica:
+
+```
+PROJECT          GIT  REMOTE  REPO_URL  CHILDREN  ISSUES
+fleet_monitoring  ✓    ✓       ✓         2/2       -
+fn_monitoring     ✓    ✓       ✓         3/3       -
+message_bus       ✓    ✓       ✓         3/4       children_missing
+web_scraping      ✗    ✗       ✗         0/3       no_gitea_repo; children_missing
+
+1/4 projects con problemas de cobertura.
+```
+
+## Check inverso: FindOrphanProjectRefs
+
+Mientras `AuditProjectsCoverage` parte de la tabla `projects` y mira hacia abajo (¿están sus hijos clonados?), `FindOrphanProjectRefs` recorre el grafo en sentido contrario: parte de las apps y analyses y mira hacia arriba (¿existe el project paraguas que declaran?). Detecta el drift inverso, apps o analyses cuyo `project_id` no tiene ninguna fila en la tabla `projects`. Es un project huérfano: existe en otro PC y nunca se sincronizó a este, o nunca se creó aquí. Es un riesgo de pérdida silenciosa, porque el enlace del hijo apunta a un project que este registro no conoce.
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	orphans, err := infra.FindOrphanProjectRefs("/home/enmanuel/fn_registry")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(infra.FormatOrphanProjectRefs(orphans))
+}
+```
+
+La firma es `func FindOrphanProjectRefs(registryRoot string) ([]OrphanProjectRef, error)`. Cada `OrphanProjectRef` agrupa, por `ProjectID` huérfano, los ids de las apps (`Apps`) y analyses (`Analyses`) que lo referencian, ambas listas ordenadas alfabéticamente y el slice resultante ordenado por `ProjectID`. Cuando todos los hijos apuntan a un project conocido devuelve un slice vacío (no nil) sin error. `FormatOrphanProjectRefs` produce una tabla de texto humano con el `project_id`, cuántas apps y analyses lo referencian y sus ids; si no hay huérfanos imprime una sola línea dejándolo claro.
+
+Caso real detectado en este registro: apps con `project_id` ∈ {`element_agents`, `imagegen`, `osint_graph`} sin fila correspondiente en `projects`.
+
+Salida típica con huérfanos:
+
+```
+PROJECT_ID      APPS  ANALYSES  REFERENCED_BY
+element_agents  1     0         shell_agent
+imagegen        1     0         imagegen_ui
+osint_graph     2     1         graph_explorer, scraper, gliner_glirel_tuning
+
+3 project_id huérfanos (referenciados por hijos pero sin fila en projects).
+```
+
+## Cuando usarla
+
+Úsala antes de un `/full-git-pull` masivo o tras clonar el registry en un PC nuevo para saber qué projects están realmente respaldados por su sub-repo Gitea y cuántos de sus hijos (apps y analyses) quedarían sin clonar. También como motor del futuro subcomando `fn doctor projects`: el caller la enchufa desde `cmd/fn/doctor.go` igual que `AuditUsesFunctions` o `AuditServicesSpec`, formatea con `FormatProjectsCoverage` para texto humano y serializa el slice directamente para `--json`.
+
+## Gotchas
+
+- Es **impura**: lee `registry.db` (abierto en modo read-only `?mode=ro`), recorre el filesystem y ejecuta `git -C <dir> remote get-url origin`. No toca la red ni la API de Gitea, así que no necesita token y es rápida.
+- `HasRemote` solo se evalúa cuando el project tiene `.git` local; si no hay `.git`, queda `false` sin intentar el comando git.
+- `gitHasRemoteOrigin` devuelve `false` ante cualquier error (no hay remote `origin`, no es un repo, git no instalado). No distingue "sin origin" de "git ausente"; si necesitas esa distinción, comprueba `git` por separado.
+- El issue `no_gitea_repo` se emite solo cuando faltan **ambos** indicadores (`!HasRemote && !RepoURLDeclared`). Un project con `repo_url` declarado pero sin clonar (`dir_not_found`) NO se marca `no_gitea_repo` — el repo existe en Gitea, simplemente no está en este disco.
+- `ChildrenMissing` cuenta los hijos (apps + analyses con ese `project_id`) cuya carpeta no tiene `.git` en disco: son los que se perderían o habría que reclonar. Cero hijos en la BD produce `0/0` y no genera issue.
+- Si `projects.dir_path` está vacío, se deriva `projects/<id>`. Los `dir_path` ya absolutos se respetan tal cual.
+- Devuelve error únicamente si `registry.db` no puede abrirse o consultarse. Los projects cuyo directorio no existe SÍ aparecen en el resultado, marcados con `dir_not_found`, para que el caller los muestre en vez de descartarlos en silencio.
+- `FindOrphanProjectRefs` también es **impura**: lee `registry.db` en modo read-only (`?mode=ro`), pero no toca el filesystem ni git, solo cruza las tablas `projects`, `apps` y `analysis`. Ignora los hijos con `project_id` vacío (no son huérfanos, simplemente no pertenecen a ningún project). Devuelve un slice vacío no-nil cuando no hay huérfanos, así que el caller puede distinguir "sin huérfanos" (slice vacío, error nil) de "fallo al leer la BD" (error no nil).
@@ -0,0 +1,417 @@
+package infra
+
+import (
+	"database/sql"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// seedProjectsRegistry builds a temp registry.db with the columns
+// AuditProjectsCoverage reads, plus a handful of on-disk directories that
+// model the cloned/missing states.
+func seedProjectsRegistry(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "registry.db")
+
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatalf("open temp db: %v", err)
+	}
+	defer db.Close()
+
+	_, err = db.Exec(`
+		CREATE TABLE projects (
+			id       TEXT PRIMARY KEY,
+			dir_path TEXT NOT NULL DEFAULT '',
+			repo_url TEXT NOT NULL DEFAULT ''
+		);
+		CREATE TABLE apps (
+			id         TEXT PRIMARY KEY,
+			dir_path   TEXT NOT NULL DEFAULT '',
+			project_id TEXT NOT NULL DEFAULT ''
+		);
+		CREATE TABLE analysis (
+			id         TEXT PRIMARY KEY,
+			dir_path   TEXT NOT NULL DEFAULT '',
+			project_id TEXT NOT NULL DEFAULT ''
+		);
+	`)
+	if err != nil {
+		t.Fatalf("create schema: %v", err)
+	}
+
+	_, err = db.Exec(`
+		INSERT INTO projects VALUES
+			('healthy',  'projects/healthy',  'https://gitea.example/dataforge/healthy'),
+			('no_repo',  'projects/no_repo',  ''),
+			('missing',  'projects/missing',  'https://gitea.example/dataforge/missing');
+		INSERT INTO apps VALUES
+			('app_cloned',  'projects/healthy/apps/app_cloned',  'healthy'),
+			('app_orphan',  'projects/healthy/apps/app_orphan',  'healthy');
+		INSERT INTO analysis VALUES
+			('an_cloned',   'projects/healthy/analysis/an_cloned', 'healthy');
+	`)
+	if err != nil {
+		t.Fatalf("seed data: %v", err)
+	}
+
+	// healthy: directory + .git present; one child cloned, one missing.
+	mkGitDir(t, dir, "projects/healthy")
+	mkGitDir(t, dir, "projects/healthy/apps/app_cloned")
+	mkGitDir(t, dir, "projects/healthy/analysis/an_cloned")
+	// app_orphan has no .git on disk → counts as missing.
+
+	// no_repo: directory exists, no .git.
+	if err := os.MkdirAll(filepath.Join(dir, "projects/no_repo"), 0o755); err != nil {
+		t.Fatalf("mkdir no_repo: %v", err)
+	}
+
+	// missing: no directory at all on disk.
+
+	return dir
+}
+
+// mkGitDir creates <root>/<rel>/.git so dirExists treats it as a git repo.
+func mkGitDir(t *testing.T, root, rel string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Join(root, rel, ".git"), 0o755); err != nil {
+		t.Fatalf("mkdir %s/.git: %v", rel, err)
+	}
+}
+
+func findCoverage(rows []ProjectCoverage, id string) *ProjectCoverage {
+	for i := range rows {
+		if rows[i].ProjectID == id {
+			return &rows[i]
+		}
+	}
+	return nil
+}
+
+func hasIssue(pc *ProjectCoverage, issue string) bool {
+	for _, i := range pc.Issues {
+		if i == issue {
+			return true
+		}
+	}
+	return false
+}
+
+func TestAuditProjectsCoverage(t *testing.T) {
+	t.Run("healthy project con un hijo sin clonar marca children_missing", func(t *testing.T) {
+		dir := seedProjectsRegistry(t)
+		rows, err := AuditProjectsCoverage(dir)
+		if err != nil {
+			t.Fatalf("AuditProjectsCoverage error: %v", err)
+		}
+		pc := findCoverage(rows, "healthy")
+		if pc == nil {
+			t.Fatal("project 'healthy' missing from results")
+		}
+		if !pc.HasGit {
+			t.Error("expected HasGit=true for healthy")
+		}
+		if !pc.RepoURLDeclared {
+			t.Error("expected RepoURLDeclared=true for healthy")
+		}
+		if pc.ChildrenInDB != 3 {
+			t.Errorf("expected 3 children in db, got %d", pc.ChildrenInDB)
+		}
+		if pc.ChildrenCloned != 2 {
+			t.Errorf("expected 2 cloned children, got %d", pc.ChildrenCloned)
+		}
+		if pc.ChildrenMissing != 1 {
+			t.Errorf("expected 1 missing child, got %d", pc.ChildrenMissing)
+		}
+		if !hasIssue(pc, "children_missing") {
+			t.Errorf("expected children_missing issue, got %v", pc.Issues)
+		}
+	})
+
+	t.Run("project sin repo_url ni remote marca no_gitea_repo", func(t *testing.T) {
+		dir := seedProjectsRegistry(t)
+		rows, err := AuditProjectsCoverage(dir)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		pc := findCoverage(rows, "no_repo")
+		if pc == nil {
+			t.Fatal("project 'no_repo' missing")
+		}
+		if pc.HasGit {
+			t.Error("expected HasGit=false for no_repo")
+		}
+		if pc.RepoURLDeclared {
+			t.Error("expected RepoURLDeclared=false for no_repo")
+		}
+		if !hasIssue(pc, "no_gitea_repo") {
+			t.Errorf("expected no_gitea_repo issue, got %v", pc.Issues)
+		}
+	})
+
+	t.Run("project sin directorio en disco marca dir_not_found", func(t *testing.T) {
+		dir := seedProjectsRegistry(t)
+		rows, err := AuditProjectsCoverage(dir)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		pc := findCoverage(rows, "missing")
+		if pc == nil {
+			t.Fatal("project 'missing' missing")
+		}
+		if !hasIssue(pc, "dir_not_found") {
+			t.Errorf("expected dir_not_found issue, got %v", pc.Issues)
+		}
+		if pc.HasGit {
+			t.Error("expected HasGit=false when dir not found")
+		}
+	})
+
+	t.Run("error si registry.db no existe", func(t *testing.T) {
+		dir := t.TempDir()
+		if _, err := AuditProjectsCoverage(dir); err == nil {
+			t.Error("expected error for missing db, got nil")
+		}
+	})
+}
+
+func TestGitHasRemoteOrigin(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	t.Run("repo con origin devuelve true", func(t *testing.T) {
+		dir := t.TempDir()
+		runGit(t, dir, "init", "-q")
+		runGit(t, dir, "remote", "add", "origin", "https://example.com/x.git")
+		if !gitHasRemoteOrigin(dir) {
+			t.Error("expected true for repo with origin")
+		}
+	})
+	t.Run("repo sin origin devuelve false", func(t *testing.T) {
+		dir := t.TempDir()
+		runGit(t, dir, "init", "-q")
+		if gitHasRemoteOrigin(dir) {
+			t.Error("expected false for repo without origin")
+		}
+	})
+}
+
+func runGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %v: %v\n%s", args, err, out)
+	}
+}
+
+// seedOrphanRefsRegistry builds a temp registry.db where some children declare
+// a project_id with no matching row in the projects table (orphan refs) while
+// others reference a valid project. It returns the registry root directory.
+func seedOrphanRefsRegistry(t *testing.T, withOrphans bool) string {
+	t.Helper()
+	dir := t.TempDir()
+	dbPath := filepath.Join(dir, "registry.db")
+
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatalf("open temp db: %v", err)
+	}
+	defer db.Close()
+
+	_, err = db.Exec(`
+		CREATE TABLE projects (
+			id       TEXT PRIMARY KEY,
+			dir_path TEXT NOT NULL DEFAULT '',
+			repo_url TEXT NOT NULL DEFAULT ''
+		);
+		CREATE TABLE apps (
+			id         TEXT PRIMARY KEY,
+			dir_path   TEXT NOT NULL DEFAULT '',
+			project_id TEXT NOT NULL DEFAULT ''
+		);
+		CREATE TABLE analysis (
+			id         TEXT PRIMARY KEY,
+			dir_path   TEXT NOT NULL DEFAULT '',
+			project_id TEXT NOT NULL DEFAULT ''
+		);
+	`)
+	if err != nil {
+		t.Fatalf("create schema: %v", err)
+	}
+
+	// One known project exists in the projects table.
+	if _, err := db.Exec(`INSERT INTO projects VALUES ('known', 'projects/known', '')`); err != nil {
+		t.Fatalf("seed projects: %v", err)
+	}
+
+	// app_valid + an_valid reference the known project: never orphans.
+	if _, err := db.Exec(`
+		INSERT INTO apps VALUES ('app_valid', 'projects/known/apps/app_valid', 'known');
+		INSERT INTO analysis VALUES ('an_valid', 'projects/known/analysis/an_valid', 'known');
+	`); err != nil {
+		t.Fatalf("seed valid children: %v", err)
+	}
+
+	// app_no_project has an empty project_id: must be ignored.
+	if _, err := db.Exec(`INSERT INTO apps VALUES ('app_no_project', 'apps/app_no_project', '')`); err != nil {
+		t.Fatalf("seed no-project app: %v", err)
+	}
+
+	if withOrphans {
+		// Two apps + one analysis pointing at 'ghost' (missing from projects),
+		// plus one app pointing at 'specter' (also missing). Insert the apps for
+		// 'ghost' out of alphabetical order to exercise sorting.
+		if _, err := db.Exec(`
+			INSERT INTO apps VALUES ('app_zeta', 'apps/app_zeta', 'ghost');
+			INSERT INTO apps VALUES ('app_alpha', 'apps/app_alpha', 'ghost');
+			INSERT INTO analysis VALUES ('an_ghost', 'analysis/an_ghost', 'ghost');
+			INSERT INTO apps VALUES ('app_specter', 'apps/app_specter', 'specter');
+		`); err != nil {
+			t.Fatalf("seed orphan children: %v", err)
+		}
+	}
+
+	return dir
+}
+
+func findOrphan(rows []OrphanProjectRef, id string) *OrphanProjectRef {
+	for i := range rows {
+		if rows[i].ProjectID == id {
+			return &rows[i]
+		}
+	}
+	return nil
+}
+
+func TestFindOrphanProjectRefs(t *testing.T) {
+	t.Run("app con project_id huerfano lo detecta y agrupa ordenado", func(t *testing.T) {
+		dir := seedOrphanRefsRegistry(t, true)
+		rows, err := FindOrphanProjectRefs(dir)
+		if err != nil {
+			t.Fatalf("FindOrphanProjectRefs error: %v", err)
+		}
+		if len(rows) != 2 {
+			t.Fatalf("expected 2 orphan refs, got %d: %+v", len(rows), rows)
+		}
+		// Sorted by ProjectID: ghost before specter.
+		if rows[0].ProjectID != "ghost" || rows[1].ProjectID != "specter" {
+			t.Fatalf("expected [ghost specter], got [%s %s]", rows[0].ProjectID, rows[1].ProjectID)
+		}
+
+		ghost := findOrphan(rows, "ghost")
+		if ghost == nil {
+			t.Fatal("orphan 'ghost' missing")
+		}
+		wantApps := []string{"app_alpha", "app_zeta"} // alphabetical
+		if len(ghost.Apps) != 2 || ghost.Apps[0] != wantApps[0] || ghost.Apps[1] != wantApps[1] {
+			t.Errorf("expected ghost.Apps=%v, got %v", wantApps, ghost.Apps)
+		}
+		if len(ghost.Analyses) != 1 || ghost.Analyses[0] != "an_ghost" {
+			t.Errorf("expected ghost.Analyses=[an_ghost], got %v", ghost.Analyses)
+		}
+
+		specter := findOrphan(rows, "specter")
+		if specter == nil {
+			t.Fatal("orphan 'specter' missing")
+		}
+		if len(specter.Apps) != 1 || specter.Apps[0] != "app_specter" {
+			t.Errorf("expected specter.Apps=[app_specter], got %v", specter.Apps)
+		}
+		if len(specter.Analyses) != 0 {
+			t.Errorf("expected specter.Analyses empty, got %v", specter.Analyses)
+		}
+	})
+
+	t.Run("app con project_id valido no aparece", func(t *testing.T) {
+		dir := seedOrphanRefsRegistry(t, true)
+		rows, err := FindOrphanProjectRefs(dir)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if findOrphan(rows, "known") != nil {
+			t.Error("valid project 'known' should not appear as orphan")
+		}
+		// Children of 'known' must never be listed in any orphan entry.
+		for _, r := range rows {
+			for _, a := range append(append([]string{}, r.Apps...), r.Analyses...) {
+				if a == "app_valid" || a == "an_valid" || a == "app_no_project" {
+					t.Errorf("child %q with valid/empty project leaked into orphan %q", a, r.ProjectID)
+				}
+			}
+		}
+	})
+
+	t.Run("sin huerfanos devuelve slice vacio sin error", func(t *testing.T) {
+		dir := seedOrphanRefsRegistry(t, false)
+		rows, err := FindOrphanProjectRefs(dir)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if rows == nil {
+			t.Fatal("expected non-nil empty slice, got nil")
+		}
+		if len(rows) != 0 {
+			t.Errorf("expected 0 orphans, got %d: %+v", len(rows), rows)
+		}
+	})
+
+	t.Run("error si registry.db no existe", func(t *testing.T) {
+		dir := t.TempDir()
+		if _, err := FindOrphanProjectRefs(dir); err == nil {
+			t.Error("expected error for missing db, got nil")
+		}
+	})
+}
+
+func TestFormatOrphanProjectRefs(t *testing.T) {
+	t.Run("sin huerfanos lo deja claro", func(t *testing.T) {
+		out := FormatOrphanProjectRefs(nil)
+		if !contains(out, "0 project_id huérfanos") {
+			t.Errorf("expected clean message, got:\n%s", out)
+		}
+	})
+
+	t.Run("con huerfanos lista ids y cuenta", func(t *testing.T) {
+		rows := []OrphanProjectRef{
+			{ProjectID: "ghost", Apps: []string{"app_alpha", "app_zeta"}, Analyses: []string{"an_ghost"}},
+		}
+		out := FormatOrphanProjectRefs(rows)
+		if !contains(out, "ghost") {
+			t.Errorf("expected project_id in output, got:\n%s", out)
+		}
+		if !contains(out, "app_alpha") || !contains(out, "an_ghost") {
+			t.Errorf("expected referencing ids in output, got:\n%s", out)
+		}
+		if !contains(out, "1 project_id huérfanos") {
+			t.Errorf("expected count line, got:\n%s", out)
+		}
+	})
+}
+
+func TestFormatProjectsCoverage(t *testing.T) {
+	t.Run("sin issues lo deja claro", func(t *testing.T) {
+		rows := []ProjectCoverage{
+			{ProjectID: "ok", HasGit: true, HasRemote: true, RepoURLDeclared: true, ChildrenInDB: 2, ChildrenCloned: 2},
+		}
+		out := FormatProjectsCoverage(rows)
+		if !contains(out, "0 projects con problemas de cobertura") {
+			t.Errorf("expected clean message, got:\n%s", out)
+		}
+	})
+
+	t.Run("con issues cuenta los afectados", func(t *testing.T) {
+		rows := []ProjectCoverage{
+			{ProjectID: "bad", Issues: []string{"no_gitea_repo"}},
+			{ProjectID: "ok", HasGit: true, HasRemote: true, RepoURLDeclared: true},
+		}
+		out := FormatProjectsCoverage(rows)
+		if !contains(out, "1/2 projects con problemas de cobertura") {
+			t.Errorf("expected 1/2 count, got:\n%s", out)
+		}
+	})
+}
@@ -0,0 +1,28 @@
+//go:build !windows
+
+package infra
+
+// ClaudeFleet describes a single Claude Code session process on the local
+// machine, cross-joining the live process state (/proc) with the session and
+// goal metadata that Claude Code persists under ~/.claude.
+//
+// It is the data record consumed by the fleetview TUI. Every field is derived
+// from a single ~/.claude/sessions/<PID>.json entry plus its optional
+// ~/.claude/goals/<sessionId>.json sidecar and the process' own /proc entry.
+type ClaudeFleet struct {
+	PID        int    `json:"pid"`
+	KittyPID   int    `json:"kitty_pid"`   // KITTY_PID from the process environ; 0 if not applicable (e.g. remote tmux)
+	SessionID  string `json:"session_id"`  // Claude Code sessionId (UUID)
+	Rename     string `json:"rename"`      // display name: short goal if present, else basename(cwd)
+	Target     string `json:"target"`      // sessionId[:8] + "@" + basename(cwd)
+	Goal       string `json:"goal"`        // from goals/<sessionId>.json .goal ("" if absent)
+	Phase      string `json:"phase"`       // from goals/<sessionId>.json .phase ("" if absent)
+	Emojis     string `json:"emojis"`      // 3 emojis representing the task (from goals .emojis; "" if absent)
+	Name       string `json:"name"`        // manual rename of the terminal (from goals .rename; "" if none)
+	Status     string `json:"status"`      // idle|busy|waiting (from sessions/<pid>.json)
+	Cwd        string `json:"cwd"`         // working directory of the session
+	TmuxWindow string `json:"tmux_window"` // "" for now (populated in a later phase)
+	Alive      bool   `json:"alive"`       // process alive AND procStart matches (guards against PID recycling)
+	UpdatedAt  int64  `json:"updated_at"`  // from sessions/<pid>.json .updatedAt (epoch millis)
+	CtxPct     int    `json:"ctx_pct"`     // context window used %, from runtime/<sessionId>.json; -1 if unknown
+}
@@ -0,0 +1,259 @@
+//go:build !windows
+
+package infra
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// sessionFile mirrors the on-disk shape of ~/.claude/sessions/<PID>.json
+// written by Claude Code 2.1.x. Only the fields we consume are declared.
+type sessionFile struct {
+	PID       int    `json:"pid"`
+	SessionID string `json:"sessionId"`
+	Cwd       string `json:"cwd"`
+	ProcStart string `json:"procStart"`
+	Status    string `json:"status"`
+	UpdatedAt int64  `json:"updatedAt"`
+}
+
+// goalFile mirrors the on-disk shape of ~/.claude/goals/<sessionId>.json.
+type goalFile struct {
+	Goal   string `json:"goal"`
+	Phase  string `json:"phase"`
+	Emojis string `json:"emojis"`
+	Rename string `json:"rename"`
+}
+
+// runtimeFile mirrors ~/.claude/runtime/<sessionId>.json written by statusline.sh
+// with the live context-window usage of that session.
+type runtimeFile struct {
+	CtxPct int `json:"ctx_pct"`
+}
+
+// ListClaudeFleet scans the current user's ~/.claude directory and returns the
+// fleet of Claude Code sessions known to the machine. It is a thin wrapper over
+// ListClaudeFleetFrom resolving the home directory.
+func ListClaudeFleet() ([]ClaudeFleet, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, fmt.Errorf("resolve home dir: %w", err)
+	}
+	return ListClaudeFleetFrom(filepath.Join(home, ".claude"))
+}
+
+// ListClaudeFleetFrom scans claudeDir (e.g. ~/.claude) and returns the fleet of
+// Claude Code sessions. It reads sessions/*.json, joins each against its
+// goals/<sessionId>.json sidecar, validates liveness against /proc (guarding
+// against PID recycling), and derives the display fields.
+//
+// Every session that produced a parseable JSON is returned; the Alive flag
+// reflects whether the underlying process is actually running. The caller is
+// expected to filter on Alive as needed. Records are ordered by status
+// (idle, waiting, busy, other) and within a status by UpdatedAt descending.
+func ListClaudeFleetFrom(claudeDir string) ([]ClaudeFleet, error) {
+	sessionsDir := filepath.Join(claudeDir, "sessions")
+	goalsDir := filepath.Join(claudeDir, "goals")
+	runtimeDir := filepath.Join(claudeDir, "runtime")
+
+	entries, err := os.ReadDir(sessionsDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []ClaudeFleet{}, nil
+		}
+		return nil, fmt.Errorf("read sessions dir %q: %w", sessionsDir, err)
+	}
+
+	fleet := make([]ClaudeFleet, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+
+		raw, readErr := os.ReadFile(filepath.Join(sessionsDir, entry.Name()))
+		if readErr != nil {
+			continue
+		}
+		var sess sessionFile
+		if json.Unmarshal(raw, &sess) != nil {
+			continue
+		}
+		if sess.PID == 0 || sess.SessionID == "" {
+			continue
+		}
+
+		f := ClaudeFleet{
+			PID:        sess.PID,
+			SessionID:  sess.SessionID,
+			Status:     sess.Status,
+			Cwd:        sess.Cwd,
+			UpdatedAt:  sess.UpdatedAt,
+			TmuxWindow: "",
+		}
+
+		// Liveness + anti-PID-recycling: the process must exist AND its
+		// /proc starttime must match the procStart recorded in the JSON.
+		f.Alive = procIsAlive(sess.PID, sess.ProcStart)
+
+		// KITTY_PID from the process environ (0 if unreadable / absent).
+		f.KittyPID = readKittyPID(sess.PID)
+
+		// Join goal/phase/emojis/name from goals/<sessionId>.json (optional).
+		f.Goal, f.Phase, f.Emojis, f.Name = readGoal(goalsDir, sess.SessionID)
+
+		// Context usage from runtime/<sessionId>.json (written by statusline).
+		f.CtxPct = readCtxPct(runtimeDir, sess.SessionID)
+
+		// Derived display fields.
+		f.Target = deriveTarget(sess.SessionID, sess.Cwd)
+		f.Rename = deriveRename(f.Goal, sess.Cwd)
+
+		fleet = append(fleet, f)
+	}
+
+	sortFleet(fleet)
+	return fleet, nil
+}
+
+// procIsAlive reports whether pid is running and its kernel starttime matches
+// procStartJSON. An empty procStartJSON only requires the process to exist.
+func procIsAlive(pid int, procStartJSON string) bool {
+	real, ok := procStartTime(pid)
+	if !ok {
+		return false
+	}
+	if procStartJSON == "" {
+		return true
+	}
+	return strings.TrimSpace(procStartJSON) == strings.TrimSpace(real)
+}
+
+// procStartTime returns field 22 (starttime, in clock ticks) of
+// /proc/<pid>/stat. The comm field (field 2) is wrapped in parentheses and may
+// itself contain spaces and ')' characters, so we parse the portion after the
+// LAST ')' and index from there: starttime is index 20 of that remainder
+// (fields 3..n), which is field 22 globally.
+func procStartTime(pid int) (string, bool) {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/stat", pid))
+	if err != nil {
+		return "", false
+	}
+	s := string(data)
+	close := strings.LastIndex(s, ")")
+	if close < 0 || close+1 >= len(s) {
+		return "", false
+	}
+	rest := strings.Fields(s[close+1:])
+	// rest[0] = state (field 3); starttime (field 22) is index 19 here:
+	// field N maps to rest[N-3]. 22 - 3 = 19.
+	const startTimeIdx = 19
+	if len(rest) <= startTimeIdx {
+		return "", false
+	}
+	return rest[startTimeIdx], true
+}
+
+// readKittyPID parses /proc/<pid>/environ (NUL-separated KEY=VALUE pairs) and
+// returns the KITTY_PID value. Returns 0 if the environ is unreadable, the key
+// is absent, or the value is not an integer.
+func readKittyPID(pid int) int {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/environ", pid))
+	if err != nil {
+		return 0
+	}
+	for _, kv := range strings.Split(string(data), "\x00") {
+		if v, ok := strings.CutPrefix(kv, "KITTY_PID="); ok {
+			n, convErr := strconv.Atoi(strings.TrimSpace(v))
+			if convErr != nil {
+				return 0
+			}
+			return n
+		}
+	}
+	return 0
+}
+
+// readGoal reads goals/<sessionID>.json and returns its goal, phase, emojis and
+// manual rename. If the file is absent or unparseable, all are "".
+func readGoal(goalsDir, sessionID string) (goal, phase, emojis, rename string) {
+	raw, err := os.ReadFile(filepath.Join(goalsDir, sessionID+".json"))
+	if err != nil {
+		return "", "", "", ""
+	}
+	var g goalFile
+	if json.Unmarshal(raw, &g) != nil {
+		return "", "", "", ""
+	}
+	return g.Goal, g.Phase, g.Emojis, g.Rename
+}
+
+// readCtxPct reads runtime/<sessionID>.json and returns the context-window used
+// percentage. Returns -1 if the file is absent or unparseable (unknown).
+func readCtxPct(runtimeDir, sessionID string) int {
+	raw, err := os.ReadFile(filepath.Join(runtimeDir, sessionID+".json"))
+	if err != nil {
+		return -1
+	}
+	var r runtimeFile
+	if json.Unmarshal(raw, &r) != nil {
+		return -1
+	}
+	return r.CtxPct
+}
+
+// deriveTarget builds sessionID[:8] + "@" + basename(cwd). If sessionID is
+// shorter than 8 runes it is used whole.
+func deriveTarget(sessionID, cwd string) string {
+	short := sessionID
+	if r := []rune(sessionID); len(r) >= 8 {
+		short = string(r[:8])
+	}
+	return short + "@" + filepath.Base(cwd)
+}
+
+// deriveRename returns goal truncated to 48 runes if non-empty, else
+// basename(cwd).
+func deriveRename(goal, cwd string) string {
+	if goal != "" {
+		return truncateRunes(goal, 48)
+	}
+	return filepath.Base(cwd)
+}
+
+// truncateRunes returns s capped at max runes (no ellipsis).
+func truncateRunes(s string, max int) string {
+	r := []rune(s)
+	if len(r) <= max {
+		return s
+	}
+	return string(r[:max])
+}
+
+// sortFleet orders the fleet by status rank then by UpdatedAt descending.
+func sortFleet(fleet []ClaudeFleet) {
+	rank := func(status string) int {
+		switch status {
+		case "idle":
+			return 0
+		case "waiting":
+			return 1
+		case "busy":
+			return 2
+		default:
+			return 3
+		}
+	}
+	sort.SliceStable(fleet, func(i, j int) bool {
+		ri, rj := rank(fleet[i].Status), rank(fleet[j].Status)
+		if ri != rj {
+			return ri < rj
+		}
+		return fleet[i].UpdatedAt > fleet[j].UpdatedAt
+	})
+}
@@ -0,0 +1,72 @@
+---
+name: list_claude_fleet
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func ListClaudeFleetFrom(claudeDir string) ([]ClaudeFleet, error) | func ListClaudeFleet() ([]ClaudeFleet, error)"
+description: "Lista la flota de procesos Claude Code de la maquina local (Linux). Escanea ~/.claude/sessions/*.json, cruza cada PID vivo contra /proc para validar liveness (anti-PID-reciclado via procStart == campo 22 de /proc/<pid>/stat), une el goal/phase de ~/.claude/goals/<sessionId>.json, extrae KITTY_PID del environ y deriva los campos de display (Target, Rename). Devuelve todas las sesiones ordenadas por status (idle, waiting, busy, otro) y por updatedAt desc; el caller filtra por Alive. Pieza de datos de la app TUI fleetview."
+tags: [claude-fleet, infra, claude, session, proc, fleet, tui]
+uses_functions: []
+uses_types: [claude_fleet_go_infra]
+returns: [claude_fleet_go_infra]
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "claudeDir"
+    desc: "Directorio raiz de Claude Code a escanear (ej. /home/enmanuel/.claude). ListClaudeFleetFrom lo recibe explicito (testeable con t.TempDir()); ListClaudeFleet lo resuelve via os.UserHomeDir() + .claude."
+output: "Slice de ClaudeFleet (claude_fleet_go_infra), una entrada por sesion con JSON parseable en sessions/. Cada entrada lleva PID, KittyPID, SessionID, Rename, Target, Goal, Phase, Status, Cwd, TmuxWindow (\"\"), Alive y UpdatedAt. Ordenado por rango de status y luego por UpdatedAt descendente. Devuelve slice vacio (sin error) si la carpeta sessions/ no existe; error si no se puede leer la carpeta por otra causa."
+tested: true
+tests: ["TestListClaudeFleetFrom", "TestListClaudeFleetFromMissingDir"]
+test_file_path: "functions/infra/list_claude_fleet_test.go"
+file_path: "functions/infra/list_claude_fleet.go"
+notes: "Misma fuente de verdad que reboot_all_claudes_bash_infra (~/.claude/sessions/<PID>.json de Claude Code 2.1.x: pid, sessionId, cwd, procStart, status, updatedAt). Solo LEE y valida — no relanza ni mata nada. La validacion anti-PID-reciclado replica la del bash (procStart del JSON vs campo 22 de /proc/<pid>/stat) pero parseando de forma robusta el comm (campo 2 entre parentesis, que puede contener espacios y ')'): se toma lo que hay tras el ULTIMO ')' y starttime es el indice 19 de ese resto. TmuxWindow queda \"\" (se rellena en una fase posterior). Build tag //go:build !windows (depende de /proc, no portable a Windows)."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	fleet, err := infra.ListClaudeFleet() // escanea ~/.claude
+	if err != nil {
+		panic(err)
+	}
+	for _, c := range fleet {
+		if !c.Alive {
+			continue // el caller filtra las sesiones muertas
+		}
+		fmt.Printf("[%s] %-20s pid=%d kitty=%d  %s\n",
+			c.Status, c.Rename, c.PID, c.KittyPID, c.Target)
+	}
+}
+```
+
+```go
+// Variante testeable: escanea un directorio arbitrario (fixtures en tests).
+fleet, _ := infra.ListClaudeFleetFrom("/home/enmanuel/.claude")
+fmt.Println(len(fleet), "sesiones conocidas")
+```
+
+## Cuando usarla
+
+Cuando necesites enumerar las sesiones de Claude Code vivas en la maquina local para mostrarlas, monitorizarlas o actuar sobre ellas (TUI fleetview, dashboards, automatizaciones). Da el join PID -> sessionId -> cwd -> goal/phase ya resuelto y validado contra /proc, en lugar de reimplementarlo a mano cada vez. Usa `ListClaudeFleetFrom` en tests (inyectando un directorio con fixtures) y `ListClaudeFleet` en runtime real.
+
+## Gotchas
+
+- **Impura: lee el filesystem y /proc.** No es determinista entre llamadas (las sesiones nacen y mueren). Solo lectura — nunca mata ni relanza procesos.
+- **Anti-PID-reciclado.** `Alive` solo es true si el proceso existe Y su starttime (campo 22 de `/proc/<pid>/stat`) coincide con el `procStart` del JSON. Un JSON huerfano cuyo PID fue reasignado a otro proceso se marca `Alive=false` aunque ese PID este vivo. Si el JSON no trae `procStart`, basta con que el proceso exista.
+- **Parseo del `comm` en /proc/<pid>/stat.** El campo 2 (comm) va entre parentesis y puede contener espacios y el caracter ')'. La funcion parsea tomando lo que hay tras el ULTIMO ')'; un split ingenuo por espacios daria un starttime equivocado.
+- **/proc no es portable.** Build tag `//go:build !windows`; depende de `/proc/<pid>/stat` y `/proc/<pid>/environ` (Linux). En macOS/BSD no funciona tal cual.
+- **environ ilegible -> KittyPID=0.** Si `/proc/<pid>/environ` no es legible (permisos, proceso de otro usuario, o el proceso ya murio entre el ReadDir y el ReadFile) `KittyPID` cae a 0 sin error. Tambien es 0 legitimamente cuando claude no corre bajo kitty (ej. tmux remoto).
+- **Devuelve TODAS las sesiones con JSON parseable**, vivas o muertas. El caller decide filtrar por `Alive`. Archivos no-`.json` y JSON corrupto se ignoran silenciosamente.
+- **TmuxWindow siempre "".** Reservado para una fase posterior; hoy no se rellena.
@@ -0,0 +1,162 @@
+//go:build !windows && linux
+
+package infra
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// readOwnProcStart reads field 22 (starttime) of /proc/<pid>/stat for the
+// current test process, so a fixture can be marked Alive deterministically.
+func readOwnProcStart(t *testing.T, pid int) string {
+	t.Helper()
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/stat", pid))
+	if err != nil {
+		t.Fatalf("read own /proc/%d/stat: %v", pid, err)
+	}
+	s := string(data)
+	close := strings.LastIndex(s, ")")
+	if close < 0 {
+		t.Fatalf("malformed stat line: %q", s)
+	}
+	rest := strings.Fields(s[close+1:])
+	const startTimeIdx = 19 // field 22 == rest[22-3]
+	if len(rest) <= startTimeIdx {
+		t.Fatalf("stat has too few fields after comm: %d", len(rest))
+	}
+	return rest[startTimeIdx]
+}
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %q: %v", filepath.Dir(path), err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write %q: %v", path, err)
+	}
+}
+
+func TestListClaudeFleetFrom(t *testing.T) {
+	tmp := t.TempDir()
+	sessions := filepath.Join(tmp, "sessions")
+	goals := filepath.Join(tmp, "goals")
+
+	livePID := os.Getpid()
+	liveProcStart := readOwnProcStart(t, livePID)
+
+	const deadPID = 2147480000 // implausibly high; no such process
+
+	// Session A: alive (own PID), with a goal -> rename = truncated goal,
+	// status idle. cwd basename = fn_registry.
+	writeFile(t, filepath.Join(sessions, fmt.Sprintf("%d.json", livePID)),
+		fmt.Sprintf(`{"pid":%d,"sessionId":"aaaaaaaa-1111-2222-3333-444444444444","cwd":"/home/enmanuel/fn_registry","procStart":%q,"status":"idle","updatedAt":1000}`,
+			livePID, liveProcStart))
+	writeFile(t, filepath.Join(goals, "aaaaaaaa-1111-2222-3333-444444444444.json"),
+		`{"goal":"Recomendar stack tecnologico para la nueva app de inventario y validar dependencias","phase":"investigando","history":["haciendo","investigando"]}`)
+
+	// Session B: alive (own PID again — same process, valid procStart), no
+	// goal sidecar -> rename = basename(cwd) = projectx, status busy.
+	writeFile(t, filepath.Join(sessions, "b.json"),
+		fmt.Sprintf(`{"pid":%d,"sessionId":"bbbbbbbb-5555","cwd":"/var/tmp/projectx","procStart":%q,"status":"busy","updatedAt":2000}`,
+			livePID, liveProcStart))
+
+	// Session C: dead PID -> Alive=false, status waiting, has goal.
+	writeFile(t, filepath.Join(sessions, fmt.Sprintf("%d.json", deadPID)),
+		fmt.Sprintf(`{"pid":%d,"sessionId":"cccccccc-9999-0000","cwd":"/srv/work/zeta","procStart":"99999999","status":"waiting","updatedAt":3000}`,
+			deadPID))
+	writeFile(t, filepath.Join(goals, "cccccccc-9999-0000.json"),
+		`{"goal":"limpiar logs","phase":"haciendo"}`)
+
+	// Noise files that must be ignored.
+	writeFile(t, filepath.Join(sessions, "notjson.txt"), "ignore me")
+	writeFile(t, filepath.Join(sessions, "broken.json"), "{ this is not json")
+
+	fleet, err := ListClaudeFleetFrom(tmp)
+	if err != nil {
+		t.Fatalf("ListClaudeFleetFrom: %v", err)
+	}
+	if len(fleet) != 3 {
+		t.Fatalf("expected 3 sessions, got %d: %+v", len(fleet), fleet)
+	}
+
+	by := map[string]ClaudeFleet{}
+	for _, f := range fleet {
+		by[f.SessionID] = f
+	}
+
+	// --- Session A assertions ---
+	a := by["aaaaaaaa-1111-2222-3333-444444444444"]
+	if !a.Alive {
+		t.Errorf("session A: expected Alive=true (own PID + matching procStart)")
+	}
+	if a.Goal != "Recomendar stack tecnologico para la nueva app de inventario y validar dependencias" {
+		t.Errorf("session A: goal join failed, got %q", a.Goal)
+	}
+	if a.Phase != "investigando" {
+		t.Errorf("session A: phase join failed, got %q", a.Phase)
+	}
+	// Rename = goal truncated to 48 runes.
+	wantRename := string([]rune(a.Goal)[:48])
+	if a.Rename != wantRename {
+		t.Errorf("session A: rename = %q, want truncated goal %q", a.Rename, wantRename)
+	}
+	if len([]rune(a.Rename)) != 48 {
+		t.Errorf("session A: rename should be 48 runes, got %d", len([]rune(a.Rename)))
+	}
+	if a.Target != "aaaaaaaa@fn_registry" {
+		t.Errorf("session A: target = %q, want %q", a.Target, "aaaaaaaa@fn_registry")
+	}
+
+	// --- Session B assertions: no goal -> fallback rename = basename(cwd) ---
+	b := by["bbbbbbbb-5555"]
+	if b.Goal != "" || b.Phase != "" {
+		t.Errorf("session B: expected empty goal/phase, got goal=%q phase=%q", b.Goal, b.Phase)
+	}
+	if b.Rename != "projectx" {
+		t.Errorf("session B: rename = %q, want basename(cwd) %q", b.Rename, "projectx")
+	}
+	if b.Target != "bbbbbbbb@projectx" {
+		t.Errorf("session B: target = %q, want %q", b.Target, "bbbbbbbb@projectx")
+	}
+	if !b.Alive {
+		t.Errorf("session B: expected Alive=true (own PID + matching procStart)")
+	}
+
+	// --- Session C assertions: dead PID ---
+	c := by["cccccccc-9999-0000"]
+	if c.Alive {
+		t.Errorf("session C: expected Alive=false for dead PID %d", deadPID)
+	}
+	if c.Target != "cccccccc@zeta" {
+		t.Errorf("session C: target = %q, want %q", c.Target, "cccccccc@zeta")
+	}
+
+	// --- Ordering: status rank idle(0) < waiting(1) < busy(2) ---
+	// A=idle, C=waiting, B=busy => expected order A, C, B.
+	wantOrder := []string{
+		"aaaaaaaa-1111-2222-3333-444444444444",
+		"cccccccc-9999-0000",
+		"bbbbbbbb-5555",
+	}
+	for i, want := range wantOrder {
+		if fleet[i].SessionID != want {
+			t.Errorf("order[%d] = %q (status %q), want %q", i, fleet[i].SessionID, fleet[i].Status, want)
+		}
+	}
+}
+
+func TestListClaudeFleetFromMissingDir(t *testing.T) {
+	tmp := t.TempDir()
+	fleet, err := ListClaudeFleetFrom(filepath.Join(tmp, "nope"))
+	if err != nil {
+		t.Fatalf("expected nil error for missing sessions dir, got %v", err)
+	}
+	if len(fleet) != 0 {
+		t.Fatalf("expected empty fleet, got %d", len(fleet))
+	}
+}
@@ -0,0 +1,150 @@
+package infra
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// natsVarz refleja los campos relevantes de la respuesta JSON del endpoint
+// /varz del monitoring HTTP embebido de un nats-server (puerto 8222, loopback).
+// Solo se mapean los campos que producen series; el resto se ignora.
+type natsVarz struct {
+	InMsgs        int64  `json:"in_msgs"`
+	OutMsgs       int64  `json:"out_msgs"`
+	InBytes       int64  `json:"in_bytes"`
+	OutBytes      int64  `json:"out_bytes"`
+	Connections   int    `json:"connections"`
+	SlowConsumers int    `json:"slow_consumers"`
+	Subscriptions int    `json:"subscriptions"`
+	Mem           int64  `json:"mem"`
+	Start         string `json:"start"`
+}
+
+// natsConnz refleja los campos relevantes de /connz.
+type natsConnz struct {
+	NumConnections int `json:"num_connections"`
+}
+
+// natsStreamDetail refleja un stream dentro de account_details[].stream_detail[].
+type natsStreamDetail struct {
+	Name    string `json:"name"`
+	Cluster struct {
+		Leader string `json:"leader"`
+	} `json:"cluster"`
+	State struct {
+		Messages int64 `json:"messages"`
+		Bytes    int64 `json:"bytes"`
+	} `json:"state"`
+}
+
+// natsJsz refleja los campos relevantes de /jsz?streams=1.
+type natsJsz struct {
+	Streams        int64 `json:"streams"`
+	Messages       int64 `json:"messages"`
+	Bytes          int64 `json:"bytes"`
+	Memory         int64 `json:"memory"`
+	Storage        int64 `json:"storage"`
+	AccountDetails []struct {
+		StreamDetail []natsStreamDetail `json:"stream_detail"`
+	} `json:"account_details"`
+}
+
+// ParseNatsMonitor convierte las respuestas JSON del endpoint de monitoring HTTP
+// embebido de un nats-server (puerto 8222, loopback) en una serie de PromSample
+// lista para empujar a VictoriaMetrics. Es la hermana de ParseUnibusHealth para
+// las métricas server-level de NATS/JetStream (msgs/s, conexiones, KV bucket
+// msgs, RAFT leader por stream, memoria). La consume el unibus_exporter de
+// fleet_monitoring en modo scraper local por nodo.
+//
+// node es el nombre lógico del nodo (p.ej. "magnus"); se adjunta a CADA serie
+// como las labels "node" e "instance" para distinguir los nodos cuando un único
+// exporter scrapea varios.
+//
+// varz, connz y jsz son los cuerpos crudos de GET /varz, GET /connz y
+// GET /jsz?streams=1 respectivamente:
+//   - varz es el core: si NO parsea como JSON válido devuelve (nil, error).
+//   - connz y jsz son best-effort: si vienen vacíos o no parsean, sus series se
+//     omiten sin abortar (no error), para que el scraper resista que un endpoint
+//     falle. nats_connections cae a varz.connections cuando connz no parsea.
+func ParseNatsMonitor(node string, varz, connz, jsz []byte) ([]PromSample, error) {
+	var v natsVarz
+	if err := json.Unmarshal(varz, &v); err != nil {
+		return nil, fmt.Errorf("parse nats varz for node %q: %w", node, err)
+	}
+
+	// mk construye un PromSample con las labels base {node, instance} más, de
+	// forma opcional, labels extra (clave/valor alternados). Las labels base no
+	// se pueden sobreescribir desde extra.
+	mk := func(name string, val float64, extra ...string) PromSample {
+		labels := map[string]string{"node": node, "instance": node}
+		for i := 0; i+1 < len(extra); i += 2 {
+			labels[extra[i]] = extra[i+1]
+		}
+		return PromSample{Name: name, Labels: labels, Value: val}
+	}
+
+	out := []PromSample{
+		mk("nats_msgs_in_total", float64(v.InMsgs)),
+		mk("nats_msgs_out_total", float64(v.OutMsgs)),
+		mk("nats_bytes_in_total", float64(v.InBytes)),
+		mk("nats_bytes_out_total", float64(v.OutBytes)),
+	}
+
+	// nats_connections: prefiere connz.num_connections; si connz no parsea, cae
+	// a varz.connections para no perder la serie.
+	connections := float64(v.Connections)
+	if len(connz) > 0 {
+		var c natsConnz
+		if err := json.Unmarshal(connz, &c); err == nil {
+			connections = float64(c.NumConnections)
+		}
+	}
+	out = append(out,
+		mk("nats_connections", connections),
+		mk("nats_slow_consumers", float64(v.SlowConsumers)),
+		mk("nats_mem_bytes", float64(v.Mem)),
+		mk("nats_subscriptions", float64(v.Subscriptions)),
+	)
+
+	// nats_server_start_seconds: epoch (segundos Unix) del campo start (RFC3339).
+	// Proxy de reinicios del nats-server: un cambio de este valor = el server
+	// reinició. Si el parse de la fecha falla, se omite la serie (no se aborta).
+	if t, err := time.Parse(time.RFC3339, v.Start); err == nil {
+		out = append(out, mk("nats_server_start_seconds", float64(t.Unix())))
+	}
+
+	// jsz es best-effort: si vacío o inválido, se omiten todas sus series.
+	if len(jsz) > 0 {
+		var j natsJsz
+		if err := json.Unmarshal(jsz, &j); err == nil {
+			out = append(out,
+				mk("nats_jetstream_streams", float64(j.Streams)),
+				mk("nats_jetstream_messages", float64(j.Messages)),
+				mk("nats_jetstream_bytes", float64(j.Bytes)),
+				mk("nats_jetstream_memory_bytes", float64(j.Memory)),
+				mk("nats_jetstream_storage_bytes", float64(j.Storage)),
+			)
+			for _, acc := range j.AccountDetails {
+				for _, sd := range acc.StreamDetail {
+					out = append(out,
+						mk("nats_stream_messages", float64(sd.State.Messages), "stream", sd.Name),
+						mk("nats_stream_bytes", float64(sd.State.Bytes), "stream", sd.Name),
+					)
+					leader := 0.0
+					if sd.Cluster.Leader == node {
+						leader = 1
+					}
+					out = append(out, mk("nats_jetstream_raft_leader", leader, "stream", sd.Name))
+
+					if bucket, ok := strings.CutPrefix(sd.Name, "KV_"); ok {
+						out = append(out, mk("kv_bucket_msgs", float64(sd.State.Messages), "bucket", bucket))
+					}
+				}
+			}
+		}
+	}
+
+	return out, nil
+}
@@ -0,0 +1,119 @@
+---
+name: parse_nats_monitor
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func ParseNatsMonitor(node string, varz, connz, jsz []byte) ([]PromSample, error)"
+description: "Convierte las respuestas JSON del endpoint de monitoring HTTP embebido de un nats-server (puerto 8222, loopback) en una serie de PromSample lista para empujar a VictoriaMetrics. Hermana de ParseUnibusHealth pero para las métricas server-level de NATS/JetStream: msgs/s, bytes, conexiones, slow consumers, memoria RSS, start epoch (proxy de reinicios), streams/messages/bytes/memory/storage de JetStream, y por stream nats_stream_messages/bytes, nats_jetstream_raft_leader y kv_bucket_msgs para los buckets KV_. Adjunta labels node e instance a cada serie. varz es el core (error si no parsea); connz y jsz son best-effort (se omiten sin abortar). La consume el unibus_exporter de fleet_monitoring como scraper local por nodo."
+tags: [prometheus, metrics, nats, jetstream, monitoring, varz, connz, jsz, kv, raft, fleet-metrics, infra]
+uses_functions: []
+uses_types: ["PromSample_go_infra"]
+returns: []
+returns_optional: true
+error_type: "error_go_core"
+imports: ["encoding/json", "fmt", "strings", "time"]
+params:
+  - name: node
+    desc: "nombre lógico del nodo (p.ej. \"magnus\"); se adjunta como labels node e instance a CADA serie y se compara con cluster.leader de cada stream para nats_jetstream_raft_leader"
+  - name: varz
+    desc: "cuerpo JSON crudo de GET http://127.0.0.1:8222/varz; core de la función (in_msgs, out_msgs, in_bytes, out_bytes, connections, slow_consumers, subscriptions, mem, start). Si no parsea, la función devuelve error"
+  - name: connz
+    desc: "cuerpo JSON crudo de GET http://127.0.0.1:8222/connz; best-effort (num_connections). Si vacío o inválido, nats_connections cae a varz.connections sin abortar"
+  - name: jsz
+    desc: "cuerpo JSON crudo de GET http://127.0.0.1:8222/jsz?streams=1; best-effort (streams, messages, bytes, memory, storage y account_details[].stream_detail[]). Si vacío o inválido, se omiten sus series sin abortar. Necesita ?streams=1 para traer stream_detail"
+output: "slice de PromSample con labels base {node,instance}: nats_msgs_in/out_total, nats_bytes_in/out_total, nats_connections, nats_slow_consumers, nats_mem_bytes, nats_subscriptions, nats_server_start_seconds (omitida si start no parsea), nats_jetstream_streams/messages/bytes/memory_bytes/storage_bytes; y por stream nats_stream_messages{stream}, nats_stream_bytes{stream}, nats_jetstream_raft_leader{stream} (1 si cluster.leader==node) y, para streams KV_, kv_bucket_msgs{bucket} con el prefijo KV_ recortado. Error solo si varz no es JSON válido."
+tested: true
+test_file_path: "functions/infra/parse_nats_monitor_test.go"
+tests:
+  - "TestParseNatsMonitorGolden"
+  - "TestParseNatsMonitorEmptyJsz"
+  - "TestParseNatsMonitorInvalidConnz"
+  - "TestParseNatsMonitorInvalidVarz"
+---
+
+# parse_nats_monitor
+
+Función de transformación (clasificada `impure` porque devuelve `error` al fallar el
+unmarshal del core; no hace I/O ni red por sí misma) que traduce las métricas
+server-level de un **nats-server** a series Prometheus. Es la hermana de
+`parse_unibus_health_go_infra`: aquella lee el `/healthz` de `membershipd` (posture),
+esta lee el monitoring embebido de NATS (puerto 8222) para las métricas profundas que
+`/healthz` no expone: msgs/s, conexiones, RAFT leader por stream, memoria, KV buckets.
+
+Pertenece al grupo de capacidad `fleet-metrics`: se compone con
+`format_prom_exposition_go_infra` (serializar) y `push_prom_remote_go_infra` (empujar a
+VictoriaMetrics). La consume el `unibus_exporter` de `fleet_monitoring` en modo scraper
+local por nodo, que hace los tres GET y le pasa los cuerpos crudos.
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"fn-registry/functions/infra"
+)
+
+func get(url string) []byte {
+	resp, err := http.Get(url)
+	if err != nil {
+		return nil // best-effort: connz/jsz pueden faltar
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return b
+}
+
+func main() {
+	base := "http://127.0.0.1:8222"
+	varz := get(base + "/varz")
+	connz := get(base + "/connz")
+	jsz := get(base + "/jsz?streams=1")
+
+	samples, err := infra.ParseNatsMonitor("magnus", varz, connz, jsz)
+	if err != nil {
+		panic(err) // varz es el core: sin él no hay métricas
+	}
+	fmt.Print(infra.FormatPromExposition(samples, time.Now().UnixMilli()))
+	// nats_msgs_in_total{instance="magnus",node="magnus"} 17 ...
+	// kv_bucket_msgs{bucket="UNIBUS_users",instance="magnus",node="magnus"} 2 ...
+	// nats_jetstream_raft_leader{instance="magnus",node="magnus",stream="KV_UNIBUS_users"} 1 ...
+}
+```
+
+## Cuando usarla
+
+Úsala dentro de un exporter que monitoriza un nats-server con el monitoring HTTP
+embebido activado (`http: 127.0.0.1:8222` en la config de NATS): tras hacer
+`GET /varz`, `GET /connz` y `GET /jsz?streams=1` contra loopback, pasa los tres cuerpos
+crudos a esta función para obtener todas las series server-level del nodo. Llámala como
+scraper local por nodo (cada nodo expone su 8222 solo en loopback), no centralizado.
+
+## Gotchas
+
+- **Impura por contrato**: solo devuelve `error` si `varz` no es JSON válido (es el core).
+  `connz` y `jsz` son **best-effort**: si vienen vacíos o no parsean, sus series se omiten
+  sin abortar. Esto hace al scraper resistente a que un endpoint falle de forma puntual.
+- **Monitoring loopback-only sin auth**: el puerto 8222 de NATS no tiene autenticación; por
+  eso debe bindearse a `127.0.0.1` y scrapearse localmente en cada nodo, nunca exponerse a
+  la red. El push agregado a VictoriaMetrics lo hace el exporter, no esta función.
+- **`/jsz` necesita `?streams=1`** para traer `account_details[].stream_detail[]`. Sin ese
+  parámetro el cuerpo trae los totales pero no el detalle por stream, y entonces no salen
+  `nats_stream_*`, `nats_jetstream_raft_leader` ni `kv_bucket_msgs`.
+- **`nats_connections`**: prefiere `connz.num_connections`; si `connz` no parsea, cae a
+  `varz.connections` para no perder la serie.
+- **RAFT leader en standalone**: en un nats-server sin clúster, el objeto `cluster` puede
+  faltar o `leader` venir vacío; en ese caso `nats_jetstream_raft_leader` sale 0 salvo que
+  `cluster.leader == node`. Es esperado: en standalone no hay quorum RAFT real.
+- **`kv_bucket_msgs`** solo se emite para streams cuyo nombre empieza por `KV_`, recortando
+  el prefijo (stream `KV_UNIBUS_users` → bucket `UNIBUS_users`).
+- **`nats_server_start_seconds`** es el epoch Unix del campo `start` (RFC3339): sirve como
+  proxy de reinicios (un cambio de valor = el server reinició). Si el campo no parsea como
+  fecha válida, la serie se omite en lugar de abortar.
@@ -0,0 +1,160 @@
+package infra
+
+import (
+	"os"
+	"testing"
+)
+
+// findNatsSample devuelve el primer PromSample cuyo Name coincide y cuyos labels
+// extra (clave/valor alternados) están todos presentes con el valor esperado.
+// El segundo retorno indica si se encontró.
+func findNatsSample(samples []PromSample, name string, labels ...string) (PromSample, bool) {
+	for _, s := range samples {
+		if s.Name != name {
+			continue
+		}
+		match := true
+		for i := 0; i+1 < len(labels); i += 2 {
+			if s.Labels[labels[i]] != labels[i+1] {
+				match = false
+				break
+			}
+		}
+		if match {
+			return s, true
+		}
+	}
+	return PromSample{}, false
+}
+
+func mustRead(t *testing.T, path string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", path, err)
+	}
+	return b
+}
+
+// golden: fixtures reales de un nats-server 2.11.15, node="probe" (== el leader
+// de los streams), valores concretos verificados a mano.
+func TestParseNatsMonitorGolden(t *testing.T) {
+	varz := mustRead(t, "testdata/nats_varz.json")
+	connz := mustRead(t, "testdata/nats_connz.json")
+	jsz := mustRead(t, "testdata/nats_jsz.json")
+
+	got, err := ParseNatsMonitor("probe", varz, connz, jsz)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	want := map[string]float64{
+		"nats_msgs_in_total":      17,
+		"nats_msgs_out_total":     17,
+		"nats_mem_bytes":          18288640,
+		"nats_jetstream_streams":  3,
+		"nats_connections":        1,
+		"nats_jetstream_messages": 6,
+	}
+	for name, w := range want {
+		s, ok := findNatsSample(got, name)
+		if !ok {
+			t.Errorf("missing sample %q", name)
+			continue
+		}
+		if s.Value != w {
+			t.Errorf("%s = %v, want %v", name, s.Value, w)
+		}
+		if s.Labels["node"] != "probe" || s.Labels["instance"] != "probe" {
+			t.Errorf("%s labels = %v, want node=instance=probe", name, s.Labels)
+		}
+	}
+
+	// kv_bucket_msgs por cada KV bucket (prefijo KV_ recortado).
+	for bucket, w := range map[string]float64{
+		"UNIBUS_users":   2,
+		"UNIBUS_rooms":   2,
+		"UNIBUS_members": 2,
+	} {
+		s, ok := findNatsSample(got, "kv_bucket_msgs", "bucket", bucket)
+		if !ok {
+			t.Errorf("missing kv_bucket_msgs{bucket=%q}", bucket)
+			continue
+		}
+		if s.Value != w {
+			t.Errorf("kv_bucket_msgs{bucket=%q} = %v, want %v", bucket, s.Value, w)
+		}
+	}
+
+	// raft leader: probe == node, así que el stream KV_UNIBUS_users tiene leader=1.
+	s, ok := findNatsSample(got, "nats_jetstream_raft_leader", "stream", "KV_UNIBUS_users")
+	if !ok {
+		t.Fatal("missing nats_jetstream_raft_leader{stream=KV_UNIBUS_users}")
+	}
+	if s.Value != 1 {
+		t.Errorf("nats_jetstream_raft_leader{stream=KV_UNIBUS_users} = %v, want 1", s.Value)
+	}
+
+	// stream_detail también emite nats_stream_messages con label stream completo.
+	if s, ok := findNatsSample(got, "nats_stream_messages", "stream", "KV_UNIBUS_users"); !ok || s.Value != 2 {
+		t.Errorf("nats_stream_messages{stream=KV_UNIBUS_users} = %v ok=%v, want 2", s.Value, ok)
+	}
+
+	// nats_server_start_seconds presente (start es RFC3339 válido).
+	if _, ok := findNatsSample(got, "nats_server_start_seconds"); !ok {
+		t.Error("missing nats_server_start_seconds (start is a valid RFC3339)")
+	}
+}
+
+// edge: jsz sin streams ni account_details. No produce series kv_bucket_msgs ni
+// nats_stream_*, pero sí las de varz/connz y las jetstream top-level (en 0).
+func TestParseNatsMonitorEmptyJsz(t *testing.T) {
+	varz := mustRead(t, "testdata/nats_varz.json")
+	connz := mustRead(t, "testdata/nats_connz.json")
+	jsz := []byte(`{"streams":0,"account_details":[]}`)
+
+	got, err := ParseNatsMonitor("probe", varz, connz, jsz)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := findNatsSample(got, "kv_bucket_msgs", "bucket", "UNIBUS_users"); ok {
+		t.Error("did not expect kv_bucket_msgs with empty account_details")
+	}
+	if _, ok := findNatsSample(got, "nats_stream_messages"); ok {
+		t.Error("did not expect nats_stream_messages with empty account_details")
+	}
+	// varz/connz siguen presentes.
+	if s, ok := findNatsSample(got, "nats_msgs_in_total"); !ok || s.Value != 17 {
+		t.Errorf("nats_msgs_in_total = %v ok=%v, want 17", s.Value, ok)
+	}
+	if s, ok := findNatsSample(got, "nats_connections"); !ok || s.Value != 1 {
+		t.Errorf("nats_connections = %v ok=%v, want 1", s.Value, ok)
+	}
+}
+
+// edge: connz inválido. No es error; nats_connections cae a varz.connections (1).
+// varz/jsz siguen produciendo sus series.
+func TestParseNatsMonitorInvalidConnz(t *testing.T) {
+	varz := mustRead(t, "testdata/nats_varz.json")
+	jsz := mustRead(t, "testdata/nats_jsz.json")
+
+	got, err := ParseNatsMonitor("probe", varz, []byte("not json"), jsz)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// fallback a varz.connections (= 1).
+	if s, ok := findNatsSample(got, "nats_connections"); !ok || s.Value != 1 {
+		t.Errorf("nats_connections = %v ok=%v, want 1 (fallback varz.connections)", s.Value, ok)
+	}
+	// jsz sigue vivo.
+	if s, ok := findNatsSample(got, "nats_jetstream_streams"); !ok || s.Value != 3 {
+		t.Errorf("nats_jetstream_streams = %v ok=%v, want 3", s.Value, ok)
+	}
+}
+
+// error path: varz inválido devuelve error no-nil (es el core, sin él no hay nada).
+func TestParseNatsMonitorInvalidVarz(t *testing.T) {
+	if _, err := ParseNatsMonitor("probe", []byte("{{{"), nil, nil); err == nil {
+		t.Fatal("expected error for invalid varz, got nil")
+	}
+}
@@ -0,0 +1,67 @@
+package infra
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// unibusHealth refleja la respuesta JSON del endpoint /healthz de un nodo del
+// cluster de mensajería unibus (membershipd). Forma verificada en producción:
+//
+//	{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}
+type unibusHealth struct {
+	Status  string `json:"status"`
+	Posture struct {
+		Enforce bool   `json:"enforce"`
+		ACL     bool   `json:"acl"`
+		TLS     bool   `json:"tls"`
+		Cluster bool   `json:"cluster"`
+		Store   string `json:"store"`
+	} `json:"posture"`
+}
+
+// ParseUnibusHealth convierte la respuesta JSON del endpoint /healthz de un nodo
+// del cluster de mensajería unibus en una serie de PromSample lista para empujar
+// a VictoriaMetrics, sin instrumentar el bus (solo lee su endpoint de salud).
+//
+// node es el nombre lógico del nodo (p.ej. "magnus"); se adjunta a cada serie
+// como las labels "node" e "instance" para distinguir los nodos cuando un único
+// exporter scrapea varios. La función SOLO debe llamarse cuando el nodo
+// respondió: el caso "no responde" (unibus_up=0) lo emite el llamador, no esta
+// función, porque sin cuerpo no hay nada que parsear.
+//
+// Devuelve siete series por nodo:
+//   - unibus_up = 1 (si el body parseó, el nodo respondió)
+//   - unibus_status_ok = 1 si status=="ok", si no 0
+//   - unibus_posture_enforce / _acl / _tls / _cluster = 1/0 según el booleano
+//   - unibus_store_kv = 1 si posture.store=="kv", si no 0
+//
+// Si el body no es JSON válido con la forma esperada, devuelve (nil, error).
+func ParseUnibusHealth(node string, body []byte) ([]PromSample, error) {
+	var h unibusHealth
+	if err := json.Unmarshal(body, &h); err != nil {
+		return nil, fmt.Errorf("parse unibus healthz for node %q: %w", node, err)
+	}
+	b2f := func(b bool) float64 {
+		if b {
+			return 1
+		}
+		return 0
+	}
+	mk := func(name string, v float64) PromSample {
+		return PromSample{
+			Name:   name,
+			Labels: map[string]string{"node": node, "instance": node},
+			Value:  v,
+		}
+	}
+	return []PromSample{
+		mk("unibus_up", 1),
+		mk("unibus_status_ok", b2f(h.Status == "ok")),
+		mk("unibus_posture_enforce", b2f(h.Posture.Enforce)),
+		mk("unibus_posture_acl", b2f(h.Posture.ACL)),
+		mk("unibus_posture_tls", b2f(h.Posture.TLS)),
+		mk("unibus_posture_cluster", b2f(h.Posture.Cluster)),
+		mk("unibus_store_kv", b2f(h.Posture.Store == "kv")),
+	}, nil
+}
@@ -0,0 +1,89 @@
+---
+name: parse_unibus_health
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func ParseUnibusHealth(node string, body []byte) ([]PromSample, error)"
+description: "Convierte la respuesta JSON del endpoint /healthz de un nodo del cluster de mensajería unibus (membershipd) en una serie de PromSample lista para empujar a VictoriaMetrics, sin instrumentar el bus: solo lee su endpoint de salud. Adjunta a cada serie las labels node e instance (= nombre lógico del nodo) para distinguir los nodos cuando un único exporter scrapea varios. Emite siete series por nodo: unibus_up, unibus_status_ok, unibus_posture_enforce/acl/tls/cluster y unibus_store_kv. Devuelve error si el body no es JSON válido con la forma esperada."
+tags: [prometheus, metrics, unibus, nats, healthz, posture, fleet-metrics, infra, monitoring]
+uses_functions: []
+uses_types: ["PromSample_go_infra"]
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: ["encoding/json", "fmt"]
+params:
+  - name: node
+    desc: "nombre lógico del nodo (p.ej. \"magnus\"); se adjunta como labels node e instance a cada serie"
+  - name: body
+    desc: "cuerpo JSON crudo devuelto por GET https://<nodo>:8470/healthz, forma {\"posture\":{enforce,acl,tls,cluster bool; store string},\"status\":string}"
+output: "slice de 7 PromSample con labels {node,instance}: unibus_up=1, unibus_status_ok (1 si status==ok), unibus_posture_enforce/acl/tls/cluster (1/0), unibus_store_kv (1 si posture.store==kv). Error si el body no es JSON válido."
+tested: true
+test_file_path: "functions/infra/parse_unibus_health_test.go"
+tests:
+  - "TestParseUnibusHealthGolden"
+  - "TestParseUnibusHealthDegraded"
+  - "TestParseUnibusHealthInvalid"
+---
+
+# parse_unibus_health
+
+Función pura de transformación (clasificada `impure` solo porque devuelve `error` al
+fallar el unmarshal; no hace I/O ni red) que traduce la salud de un nodo del bus de
+mensajería **unibus** a métricas Prometheus. Pertenece al grupo de capacidad
+`fleet-metrics`: se compone con `format_prom_exposition_go_infra` (serializar) y
+`push_prom_remote_go_infra` (empujar a VictoriaMetrics).
+
+El endpoint `/healthz` de cada nodo (`membershipd`) responde, verificado en producción:
+
+```json
+{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}
+```
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	body := []byte(`{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}`)
+	samples, err := infra.ParseUnibusHealth("magnus", body)
+	if err != nil {
+		panic(err)
+	}
+	// Serializa y (en un exporter real) empuja a VictoriaMetrics.
+	fmt.Print(infra.FormatPromExposition(samples, time.Now().UnixMilli()))
+	// unibus_up{instance="magnus",node="magnus"} 1 ...
+	// unibus_posture_enforce{instance="magnus",node="magnus"} 1 ...
+}
+```
+
+## Cuando usarla
+
+Úsala dentro de un exporter que monitoriza el cluster unibus: tras hacer
+`GET https://<nodo>:8470/healthz` con la CA del cluster, pasa el cuerpo a esta función
+para obtener las series del nodo. Llámala **solo cuando el nodo respondió**; si el GET
+falla (timeout, TLS, no-2xx), emite tú `unibus_up=0` para ese nodo, porque sin cuerpo
+no hay nada que parsear.
+
+## Gotchas
+
+- No emite `unibus_up=0`: ese caso (nodo caído) es responsabilidad del llamador, que sabe
+  si el GET falló. Esta función siempre emite `unibus_up=1` porque solo se la llama con un
+  cuerpo recibido.
+- Las labels `node` e `instance` toman el mismo valor (el nombre lógico del nodo). El
+  `push_prom_remote_go_infra` añadiría `instance` vía `extra_label` por igual a todas las
+  series del body; por eso aquí ya se fija `instance` por-serie, para que cada nodo unibus
+  conserve su identidad cuando un solo exporter empuja los de varios nodos en un único POST.
+- Solo lee la posture y el status que hoy expone `/healthz`. Métricas profundas de
+  NATS/JetStream (msgs/s, conexiones, RAFT leader por stream) NO salen de aquí: requieren
+  el monitoring embebido de NATS (puerto 8222), que en producción está cerrado.
@@ -0,0 +1,67 @@
+package infra
+
+import "testing"
+
+// golden: nodo seguro con la posture homogénea esperada en producción.
+func TestParseUnibusHealthGolden(t *testing.T) {
+	body := []byte(`{"posture":{"enforce":true,"acl":true,"tls":true,"cluster":true,"store":"kv"},"status":"ok"}`)
+	got, err := ParseUnibusHealth("magnus", body)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := map[string]float64{
+		"unibus_up":              1,
+		"unibus_status_ok":       1,
+		"unibus_posture_enforce": 1,
+		"unibus_posture_acl":     1,
+		"unibus_posture_tls":     1,
+		"unibus_posture_cluster": 1,
+		"unibus_store_kv":        1,
+	}
+	if len(got) != len(want) {
+		t.Fatalf("got %d samples, want %d", len(got), len(want))
+	}
+	for _, s := range got {
+		w, ok := want[s.Name]
+		if !ok {
+			t.Errorf("unexpected sample %q", s.Name)
+			continue
+		}
+		if s.Value != w {
+			t.Errorf("%s = %v, want %v", s.Name, s.Value, w)
+		}
+		if s.Labels["node"] != "magnus" || s.Labels["instance"] != "magnus" {
+			t.Errorf("%s labels = %v, want node=instance=magnus", s.Name, s.Labels)
+		}
+	}
+}
+
+// edge: nodo degradado (posture todo false, store distinto de kv, status != ok).
+func TestParseUnibusHealthDegraded(t *testing.T) {
+	body := []byte(`{"posture":{"enforce":false,"acl":false,"tls":false,"cluster":false,"store":"sqlite"},"status":"degraded"}`)
+	got, err := ParseUnibusHealth("homer", body)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := map[string]float64{
+		"unibus_up":              1,
+		"unibus_status_ok":       0,
+		"unibus_posture_enforce": 0,
+		"unibus_posture_acl":     0,
+		"unibus_posture_tls":     0,
+		"unibus_posture_cluster": 0,
+		"unibus_store_kv":        0,
+	}
+	for _, s := range got {
+		if s.Value != want[s.Name] {
+			t.Errorf("%s = %v, want %v", s.Name, s.Value, want[s.Name])
+		}
+	}
+}
+
+// error path: body que no es JSON válido devuelve error, no panic.
+func TestParseUnibusHealthInvalid(t *testing.T) {
+	if _, err := ParseUnibusHealth("datardos", []byte("not json at all")); err == nil {
+		t.Fatal("expected error for invalid body, got nil")
+	}
+}
@@ -0,0 +1,150 @@
+//go:build !windows
+
+package infra
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// ResumableClaude describes a CLOSED Claude Code session that still has a saved
+// goal and can therefore be reopened with `claude --resume <SessionID>`. The
+// fleetview TUI consumes these for its "resume" picker.
+type ResumableClaude struct {
+	SessionID  string `json:"session_id"`
+	Goal       string `json:"goal"`        // from goals/<id>.json .goal ("" if absent)
+	Emojis     string `json:"emojis"`      // from goals/<id>.json .emojis ("" if absent)
+	Name       string `json:"name"`        // from goals/<id>.json .rename ("" if absent)
+	LastActive int64  `json:"last_active"` // mtime of the goal.json file, epoch seconds
+}
+
+// maxResumable caps the number of resumable sessions returned, keeping only the
+// most recently touched ones.
+const maxResumable = 40
+
+// ListResumableClaudes scans the current user's ~/.claude directory and returns
+// the closed sessions that can be reopened with `claude --resume`. It is a thin
+// wrapper over ListResumableClaudesFrom resolving the home directory.
+func ListResumableClaudes() ([]ResumableClaude, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil, fmt.Errorf("resolve home dir: %w", err)
+	}
+	return ListResumableClaudesFrom(filepath.Join(home, ".claude"))
+}
+
+// ListResumableClaudesFrom scans claudeDir (e.g. ~/.claude) and returns the
+// sessions that have a goal (goals/<id>.json) whose process is NOT alive — i.e.
+// candidates to reopen with `claude --resume <SessionID>`.
+//
+// A session is considered live (and thus excluded) when sessions/<PID>.json
+// reports a PID whose /proc starttime matches the recorded procStart, using the
+// exact same liveness criterion as ListClaudeFleetFrom (procIsAlive). Goals
+// without a non-empty goal string are skipped. Results are ordered by
+// LastActive descending and capped at maxResumable.
+func ListResumableClaudesFrom(claudeDir string) ([]ResumableClaude, error) {
+	sessionsDir := filepath.Join(claudeDir, "sessions")
+	goalsDir := filepath.Join(claudeDir, "goals")
+
+	// 1. Build the set of LIVE sessionIds from sessions/*.json.
+	live := liveSessionIDs(sessionsDir)
+
+	// 2. Scan goals/*.json.
+	entries, err := os.ReadDir(goalsDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []ResumableClaude{}, nil
+		}
+		return nil, fmt.Errorf("read goals dir %q: %w", goalsDir, err)
+	}
+
+	out := make([]ResumableClaude, 0, len(entries))
+	for _, entry := range entries {
+		name := entry.Name()
+		if entry.IsDir() || !strings.HasSuffix(name, ".json") {
+			continue
+		}
+		sessionID := strings.TrimSuffix(name, ".json")
+		if sessionID == "" {
+			continue
+		}
+		// Skip sessions that are alive (already in the fleet, not resumable).
+		if live[sessionID] {
+			continue
+		}
+
+		path := filepath.Join(goalsDir, name)
+		raw, readErr := os.ReadFile(path)
+		if readErr != nil {
+			continue
+		}
+		var g goalFile
+		if json.Unmarshal(raw, &g) != nil {
+			continue
+		}
+		// No real work to resume without a goal.
+		if strings.TrimSpace(g.Goal) == "" {
+			continue
+		}
+
+		info, statErr := os.Stat(path)
+		if statErr != nil {
+			continue
+		}
+
+		out = append(out, ResumableClaude{
+			SessionID:  sessionID,
+			Goal:       g.Goal,
+			Emojis:     g.Emojis,
+			Name:       g.Rename,
+			LastActive: info.ModTime().Unix(),
+		})
+	}
+
+	// 3. Order by LastActive descending (most recent first).
+	sort.SliceStable(out, func(i, j int) bool {
+		return out[i].LastActive > out[j].LastActive
+	})
+
+	// 4. Cap at maxResumable.
+	if len(out) > maxResumable {
+		out = out[:maxResumable]
+	}
+	return out, nil
+}
+
+// liveSessionIDs scans sessionsDir (sessions/*.json) and returns the set of
+// sessionIds whose process is currently alive, applying the same anti-PID-
+// recycling check as ListClaudeFleetFrom (procIsAlive matches /proc starttime
+// against the recorded procStart). Missing or unparseable files are ignored.
+func liveSessionIDs(sessionsDir string) map[string]bool {
+	live := make(map[string]bool)
+	entries, err := os.ReadDir(sessionsDir)
+	if err != nil {
+		return live
+	}
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
+			continue
+		}
+		raw, readErr := os.ReadFile(filepath.Join(sessionsDir, entry.Name()))
+		if readErr != nil {
+			continue
+		}
+		var sess sessionFile
+		if json.Unmarshal(raw, &sess) != nil {
+			continue
+		}
+		if sess.PID == 0 || sess.SessionID == "" {
+			continue
+		}
+		if procIsAlive(sess.PID, sess.ProcStart) {
+			live[sess.SessionID] = true
+		}
+	}
+	return live
+}
@@ -0,0 +1,68 @@
+---
+name: list_resumable_claudes
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func ListResumableClaudesFrom(claudeDir string) ([]ResumableClaude, error) | func ListResumableClaudes() ([]ResumableClaude, error)"
+description: "Lista las sesiones de Claude Code CERRADAS que se pueden reabrir con `claude --resume <sessionId>` (Linux). Escanea ~/.claude/sessions/*.json para construir el conjunto de sessionIds VIVOS (mismo criterio anti-PID-reciclado que list_claude_fleet: procStart == campo 22 de /proc/<pid>/stat), luego recorre ~/.claude/goals/*.json y devuelve cada sesion cuyo proceso NO esta vivo y que tiene un goal no vacio. Cada entrada lleva session_id, goal, emojis y name (rename) del goal.json, y last_active = mtime del goal.json. Ordenadas por last_active desc y limitadas a 40. Pieza de datos del picker de resume de la app TUI fleetview."
+tags: [claude-fleet, infra, claude, session, resume, proc, tui]
+uses_functions: [list_claude_fleet_go_infra]
+uses_types: [resumable_claude_go_infra]
+returns: [resumable_claude_go_infra]
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "claudeDir"
+    desc: "Directorio raiz de Claude Code a escanear (ej. /home/enmanuel/.claude). ListResumableClaudesFrom lo recibe explicito (testeable con t.TempDir()); ListResumableClaudes lo resuelve via os.UserHomeDir() + .claude."
+output: "Slice de ResumableClaude (resumable_claude_go_infra), una entrada por sesion CERRADA con goal en goals/<id>.json. Cada entrada lleva SessionID (basename del goal.json sin .json), Goal, Emojis, Name (rename) y LastActive (mtime del goal.json en epoch segundos). Excluye las sesiones cuyo proceso sigue vivo (ya en la flota) y las que no tienen goal. Ordenado por LastActive descendente y capado a 40 resultados. Devuelve slice vacio (sin error) si la carpeta goals/ no existe; error si no se puede leer por otra causa."
+tested: true
+tests: ["TestListResumableClaudesFrom"]
+test_file_path: "functions/infra/resumable_claude_test.go"
+file_path: "functions/infra/resumable_claude.go"
+notes: "Complementaria de list_claude_fleet_go_infra: aquella lista las sesiones VIVAS, esta las CERRADAS-pero-resumibles. Reutiliza los helpers procIsAlive/procStartTime del mismo paquete infra (definidos en functions/infra/list_claude_fleet.go) — no los redefine. El conjunto de vivos se construye desde sessions/*.json; el catalogo de candidatas desde goals/*.json. El sessionId de una candidata es el basename del goal.json (no hay sessions/<PID>.json para ella porque su proceso ya murio). LastActive es el mtime del archivo, no la actividad real de la conversacion. Build tag //go:build !windows (depende de /proc, no portable a Windows)."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	resumables, err := infra.ListResumableClaudes() // escanea ~/.claude
+	if err != nil {
+		panic(err)
+	}
+	for _, r := range resumables {
+		fmt.Printf("%s %-40s  claude --resume %s\n", r.Emojis, r.Goal, r.SessionID)
+	}
+}
+```
+
+```go
+// Variante testeable: escanea un directorio arbitrario (fixtures en tests).
+resumables, _ := infra.ListResumableClaudesFrom("/home/enmanuel/.claude")
+fmt.Println(len(resumables), "sesiones reabribles")
+```
+
+## Cuando usarla
+
+Cuando necesites poblar un picker de "reanudar" en la TUI fleetview (o cualquier UI/automatizacion equivalente): te da las sesiones de Claude Code que ya cerraste pero que tenian un objetivo guardado, listas para `claude --resume <session_id>`. Excluye las que siguen vivas (esas ya estan en la flota, las lista `list_claude_fleet_go_infra`). Usa `ListResumableClaudesFrom` en tests (inyectando un directorio con fixtures) y `ListResumableClaudes` en runtime real.
+
+## Gotchas
+
+- **Impura: lee el filesystem y /proc.** No es determinista entre llamadas (las sesiones nacen y mueren). Solo lectura — nunca relanza ni mata nada.
+- **El statusline purga goals viejos.** Las sesiones de mas de ~7 dias suelen tener su `goals/<id>.json` purgado por el statusline, asi que dejan de aparecer aqui aunque `claude --resume` siga pudiendo reabrirlas. Esta funcion solo ve lo que queda en `goals/`.
+- **PID reciclado.** El conjunto de "vivos" usa el mismo guardado anti-PID-reciclado que `list_claude_fleet`: un PID reasignado a otro proceso NO marca la sesion como viva (procStart != campo 22 de /proc/<pid>/stat), por lo que su goal seguira saliendo como resumible correctamente.
+- **Orden por mtime, no por actividad real.** `LastActive` es el `mtime` del `goal.json`, que se toca cuando el statusline reescribe el objetivo/fase — no es el instante exacto del ultimo mensaje de la conversacion. Es una aproximacion "lo mas reciente arriba", no un timestamp exacto de actividad.
+- **Cap a 40.** Solo se devuelven las 40 mas recientes; si hay mas goals cerrados, los antiguos se omiten.
+- **Goals sin goal o ilegibles se omiten** silenciosamente. Un `goal.json` con `goal` vacio (o solo espacios) no es resumible (no hay trabajo que reanudar). Archivos no-`.json` y JSON corrupto se ignoran.
+- **/proc no es portable.** Build tag `//go:build !windows`; depende de `/proc/<pid>/stat` (Linux) para decidir que sesiones estan vivas.
@@ -0,0 +1,172 @@
+//go:build !windows && linux
+
+package infra
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// writeJSON marshals v and writes it to path, failing the test on error.
+func writeJSON(t *testing.T, path string, v any) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %q: %v", filepath.Dir(path), err)
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if err := os.WriteFile(path, b, 0o644); err != nil {
+		t.Fatalf("write %q: %v", path, err)
+	}
+}
+
+// touch sets the mtime of path to the given unix epoch seconds.
+func touch(t *testing.T, path string, epoch int64) {
+	t.Helper()
+	mt := time.Unix(epoch, 0)
+	if err := os.Chtimes(path, mt, mt); err != nil {
+		t.Fatalf("chtimes %q: %v", path, err)
+	}
+}
+
+func TestListResumableClaudesFrom(t *testing.T) {
+	t.Run("excluye sesion viva, incluye muertas con goal ordenadas por LastActive", func(t *testing.T) {
+		dir := t.TempDir()
+		sessionsDir := filepath.Join(dir, "sessions")
+		goalsDir := filepath.Join(dir, "goals")
+
+		// A LIVE session: real running PID (this test process) + its real
+		// /proc starttime as procStart, so procIsAlive returns true.
+		livePID := os.Getpid()
+		liveStart, ok := procStartTime(livePID)
+		if !ok {
+			t.Fatalf("could not read procStartTime for self pid %d", livePID)
+		}
+		const liveSession = "11111111-aaaa-bbbb-cccc-000000000001"
+		writeJSON(t, filepath.Join(sessionsDir, "9001.json"), sessionFile{
+			PID:       livePID,
+			SessionID: liveSession,
+			Cwd:       "/tmp/live",
+			ProcStart: liveStart,
+			Status:    "busy",
+		})
+
+		// A goal for the live session: must be EXCLUDED (already in fleet).
+		liveGoal := filepath.Join(goalsDir, liveSession+".json")
+		writeJSON(t, liveGoal, goalFile{Goal: "trabajo en curso", Emojis: "🔥", Rename: "vivo"})
+		touch(t, liveGoal, 5000)
+
+		// A DEAD session with a goal: must be INCLUDED. No sessions/ entry,
+		// so it can never be live.
+		const deadOld = "22222222-aaaa-bbbb-cccc-000000000002"
+		oldGoal := filepath.Join(goalsDir, deadOld+".json")
+		writeJSON(t, oldGoal, goalFile{Goal: "objetivo antiguo", Emojis: "🛠️", Rename: "viejo"})
+		touch(t, oldGoal, 1000)
+
+		// Another DEAD session with a goal, more recent: must come FIRST.
+		const deadNew = "33333333-aaaa-bbbb-cccc-000000000003"
+		newGoal := filepath.Join(goalsDir, deadNew+".json")
+		writeJSON(t, newGoal, goalFile{Goal: "objetivo reciente", Rename: "nuevo"})
+		touch(t, newGoal, 4000)
+
+		// A DEAD session WITHOUT a goal string: must be OMITTED.
+		const deadEmpty = "44444444-aaaa-bbbb-cccc-000000000004"
+		emptyGoal := filepath.Join(goalsDir, deadEmpty+".json")
+		writeJSON(t, emptyGoal, goalFile{Goal: "   ", Emojis: "💤"})
+		touch(t, emptyGoal, 6000)
+
+		got, err := ListResumableClaudesFrom(dir)
+		if err != nil {
+			t.Fatalf("ListResumableClaudesFrom: %v", err)
+		}
+
+		if len(got) != 2 {
+			t.Fatalf("got %d resumable, want 2: %+v", len(got), got)
+		}
+
+		// Order by LastActive desc: deadNew (4000) before deadOld (1000).
+		if got[0].SessionID != deadNew {
+			t.Errorf("got[0].SessionID = %q, want %q", got[0].SessionID, deadNew)
+		}
+		if got[1].SessionID != deadOld {
+			t.Errorf("got[1].SessionID = %q, want %q", got[1].SessionID, deadOld)
+		}
+
+		// Live session must not appear.
+		for _, r := range got {
+			if r.SessionID == liveSession {
+				t.Errorf("live session %q must be excluded", liveSession)
+			}
+			if r.SessionID == deadEmpty {
+				t.Errorf("session without goal %q must be omitted", deadEmpty)
+			}
+		}
+
+		// Field mapping for the most-recent record.
+		if got[0].Goal != "objetivo reciente" {
+			t.Errorf("got[0].Goal = %q", got[0].Goal)
+		}
+		if got[0].Name != "nuevo" {
+			t.Errorf("got[0].Name = %q, want \"nuevo\"", got[0].Name)
+		}
+		if got[0].LastActive != 4000 {
+			t.Errorf("got[0].LastActive = %d, want 4000", got[0].LastActive)
+		}
+		if got[1].Emojis != "🛠️" {
+			t.Errorf("got[1].Emojis = %q", got[1].Emojis)
+		}
+	})
+
+	t.Run("dir de goals inexistente retorna slice vacio sin error", func(t *testing.T) {
+		dir := t.TempDir() // no goals/ subdir
+		got, err := ListResumableClaudesFrom(dir)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(got) != 0 {
+			t.Errorf("got %d, want 0", len(got))
+		}
+	})
+
+	t.Run("cap a 40 resultados mas recientes", func(t *testing.T) {
+		dir := t.TempDir()
+		goalsDir := filepath.Join(dir, "goals")
+		// 50 dead sessions with goals, mtimes 1..50.
+		for i := 1; i <= 50; i++ {
+			id := uuidLike(i)
+			p := filepath.Join(goalsDir, id+".json")
+			writeJSON(t, p, goalFile{Goal: "objetivo", Rename: id})
+			touch(t, p, int64(i))
+		}
+		got, err := ListResumableClaudesFrom(dir)
+		if err != nil {
+			t.Fatalf("ListResumableClaudesFrom: %v", err)
+		}
+		if len(got) != 40 {
+			t.Fatalf("got %d, want 40 (capped)", len(got))
+		}
+		// Most recent first: LastActive should be 50 then descending.
+		if got[0].LastActive != 50 {
+			t.Errorf("got[0].LastActive = %d, want 50", got[0].LastActive)
+		}
+		if got[39].LastActive != 11 {
+			t.Errorf("got[39].LastActive = %d, want 11", got[39].LastActive)
+		}
+	})
+}
+
+// uuidLike builds a deterministic, unique filename stem for index i.
+func uuidLike(i int) string {
+	const hex = "0123456789abcdef"
+	b := []byte("00000000-0000-0000-0000-000000000000")
+	// Fill the last 3 chars with i (i <= 50 fits in 2 hex digits, keep simple).
+	b[len(b)-1] = hex[i%16]
+	b[len(b)-2] = hex[(i/16)%16]
+	b[len(b)-3] = hex[(i/256)%16]
+	return string(b)
+}
@@ -0,0 +1,30 @@
+{
+  "server_id": "NC23B47RQSJYPX5AIUC5CA3ND5RLCYREKSAFLM65MLBY5PBRIXPAFL7O",
+  "now": "2026-06-07T19:02:25.326833943Z",
+  "num_connections": 1,
+  "total": 1,
+  "offset": 0,
+  "limit": 1024,
+  "connections": [
+    {
+      "cid": 5,
+      "kind": "Client",
+      "type": "nats",
+      "ip": "127.0.0.1",
+      "port": 52734,
+      "start": "2026-06-07T21:02:24.812382826+02:00",
+      "last_activity": "2026-06-07T21:02:24.821005187+02:00",
+      "rtt": "623µs",
+      "uptime": "0s",
+      "idle": "0s",
+      "pending_bytes": 0,
+      "in_msgs": 17,
+      "out_msgs": 17,
+      "in_bytes": 1304,
+      "out_bytes": 3905,
+      "subscriptions": 2,
+      "lang": "go",
+      "version": "1.49.0"
+    }
+  ]
+}
@@ -0,0 +1,97 @@
+{
+  "memory": 0,
+  "storage": 310,
+  "reserved_memory": 0,
+  "reserved_storage": 0,
+  "accounts": 1,
+  "ha_assets": 0,
+  "api": {
+    "level": 1,
+    "total": 6,
+    "errors": 0
+  },
+  "server_id": "NC23B47RQSJYPX5AIUC5CA3ND5RLCYREKSAFLM65MLBY5PBRIXPAFL7O",
+  "now": "2026-06-07T19:02:25.327216549Z",
+  "config": {
+    "max_memory": 3221225472,
+    "max_storage": 546399169536,
+    "store_dir": "/tmp/natsprobe4019469486/jetstream",
+    "sync_interval": 120000000000
+  },
+  "limits": {},
+  "streams": 3,
+  "consumers": 0,
+  "messages": 6,
+  "bytes": 310,
+  "account_details": [
+    {
+      "name": "$G",
+      "id": "$G",
+      "memory": 0,
+      "storage": 310,
+      "reserved_memory": 18446744073709551615,
+      "reserved_storage": 18446744073709551615,
+      "accounts": 0,
+      "ha_assets": 0,
+      "api": {
+        "level": 0,
+        "total": 6,
+        "errors": 0
+      },
+      "stream_detail": [
+        {
+          "name": "KV_UNIBUS_rooms",
+          "created": "2026-06-07T19:02:24.8170934Z",
+          "cluster": {
+            "leader": "probe"
+          },
+          "state": {
+            "messages": 2,
+            "bytes": 102,
+            "first_seq": 1,
+            "first_ts": "2026-06-07T19:02:24.817910599Z",
+            "last_seq": 2,
+            "last_ts": "2026-06-07T19:02:24.818011867Z",
+            "num_subjects": 2,
+            "consumer_count": 0
+          }
+        },
+        {
+          "name": "KV_UNIBUS_members",
+          "created": "2026-06-07T19:02:24.818494147Z",
+          "cluster": {
+            "leader": "probe"
+          },
+          "state": {
+            "messages": 2,
+            "bytes": 106,
+            "first_seq": 1,
+            "first_ts": "2026-06-07T19:02:24.81917932Z",
+            "last_seq": 2,
+            "last_ts": "2026-06-07T19:02:24.819283444Z",
+            "num_subjects": 2,
+            "consumer_count": 0
+          }
+        },
+        {
+          "name": "KV_UNIBUS_users",
+          "created": "2026-06-07T19:02:24.814500069Z",
+          "cluster": {
+            "leader": "probe"
+          },
+          "state": {
+            "messages": 2,
+            "bytes": 102,
+            "first_seq": 1,
+            "first_ts": "2026-06-07T19:02:24.81638123Z",
+            "last_seq": 2,
+            "last_ts": "2026-06-07T19:02:24.816570377Z",
+            "num_subjects": 2,
+            "consumer_count": 0
+          }
+        }
+      ]
+    }
+  ],
+  "total": 1
+}
@@ -0,0 +1,80 @@
+{
+  "server_id": "NC23B47RQSJYPX5AIUC5CA3ND5RLCYREKSAFLM65MLBY5PBRIXPAFL7O",
+  "server_name": "probe",
+  "version": "2.11.15",
+  "proto": 1,
+  "go": "go1.26.4",
+  "host": "127.0.0.1",
+  "port": 14260,
+  "max_connections": 65536,
+  "ping_interval": 120000000000,
+  "ping_max": 2,
+  "http_host": "127.0.0.1",
+  "http_port": 8222,
+  "http_base_path": "",
+  "https_port": 0,
+  "auth_timeout": 2,
+  "max_control_line": 4096,
+  "max_payload": 1048576,
+  "max_pending": 67108864,
+  "cluster": {},
+  "gateway": {},
+  "leaf": {},
+  "mqtt": {},
+  "websocket": {},
+  "jetstream": {
+    "config": {
+      "max_memory": 3221225472,
+      "max_storage": 546399169536,
+      "store_dir": "/tmp/natsprobe4019469486/jetstream",
+      "sync_interval": 120000000000
+    },
+    "stats": {
+      "memory": 0,
+      "storage": 310,
+      "reserved_memory": 0,
+      "reserved_storage": 0,
+      "accounts": 1,
+      "ha_assets": 0,
+      "api": {
+        "level": 1,
+        "total": 6,
+        "errors": 0
+      }
+    },
+    "limits": {}
+  },
+  "tls_timeout": 2,
+  "write_deadline": 10000000000,
+  "start": "2026-06-07T19:02:24.785745698Z",
+  "now": "2026-06-07T19:02:25.325501038Z",
+  "uptime": "0s",
+  "mem": 18288640,
+  "cores": 24,
+  "gomaxprocs": 24,
+  "gomemlimit": 4294967296,
+  "cpu": 0,
+  "connections": 1,
+  "total_connections": 1,
+  "routes": 0,
+  "remotes": 0,
+  "leafnodes": 0,
+  "in_msgs": 17,
+  "out_msgs": 17,
+  "in_bytes": 1304,
+  "out_bytes": 3905,
+  "slow_consumers": 0,
+  "subscriptions": 75,
+  "http_req_stats": {
+    "/varz": 1
+  },
+  "config_load_time": "2026-06-07T19:02:24.785745698Z",
+  "config_digest": "",
+  "system_account": "$SYS",
+  "slow_consumer_stats": {
+    "clients": 0,
+    "routes": 0,
+    "gateways": 0,
+    "leafs": 0
+  }
+}
@@ -0,0 +1,180 @@
+//go:build !windows
+
+package infra
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// TmuxMapClaudePanes devuelve un mapa claudePID -> window_id de todos los panes
+// del socket cuyo proceso de pane (o algun descendiente directo) sea un proceso
+// `claude`. Permite a la TUI saber que Claude de su lista ya vive en la sesion
+// fleet (y por tanto es conmutable) y en que window.
+//
+// Como cada pane que corre Claude lo hace con `exec claude ...`, el #{pane_pid}
+// del pane normalmente ES el PID de claude (comm == "claude"). Por robustez, si
+// el propio pane_pid no es claude (p.ej. un shell que lanzo claude como hijo),
+// se recorren sus descendientes directos buscando el primer comm == "claude".
+// Si no se encuentra claude bajo un pane, ese pane se omite.
+//
+// Opera SIEMPRE sobre el socket aislado pasado como parametro (tmux -L <socket>)
+// y lee /proc (no portable a Windows; de ahi el build tag //go:build !windows).
+func TmuxMapClaudePanes(socket string) (map[int]string, error) {
+	if socket == "" {
+		return nil, fmt.Errorf("tmux_map_claude_panes: socket vacio")
+	}
+
+	out, stderr, err := runTmux(socket, "list-panes", "-a", "-F", "#{pane_pid} #{window_id}")
+	if err != nil {
+		return nil, fmt.Errorf("tmux_map_claude_panes: list-panes -a: %w (%s)", err, stderr)
+	}
+
+	result := make(map[int]string)
+	for _, line := range strings.Split(strings.TrimSpace(out), "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		fields := strings.Fields(line)
+		if len(fields) < 2 {
+			continue
+		}
+		panePID, convErr := strconv.Atoi(fields[0])
+		if convErr != nil {
+			continue
+		}
+		windowID := fields[1]
+
+		claudePID, ok := findClaudePID(panePID)
+		if !ok {
+			continue // no hay claude bajo este pane
+		}
+		result[claudePID] = windowID
+	}
+	return result, nil
+}
+
+// findClaudePID devuelve el PID de un proceso `claude` que sea el propio pid o
+// un hijo directo suyo. Devuelve (pid, true) si lo encuentra; (0, false) si no.
+func findClaudePID(pid int) (int, bool) {
+	if procComm(pid) == "claude" {
+		return pid, true
+	}
+	for _, child := range procChildren(pid) {
+		if procComm(child) == "claude" {
+			return child, true
+		}
+	}
+	return 0, false
+}
+
+// procComm lee el nombre del comando (comm) de /proc/<pid>/comm. Devuelve ""
+// si el proceso no existe o no se puede leer.
+func procComm(pid int) string {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/comm", pid))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
+// procChildren devuelve los PIDs de los hijos DIRECTOS de <pid>. Intenta primero
+// /proc/<pid>/task/<pid>/children (rapido, requiere CONFIG_PROC_CHILDREN); si no
+// esta disponible, cae a escanear /proc/*/stat por PPID (campo 4).
+func procChildren(pid int) []int {
+	if kids := procChildrenFromTask(pid); kids != nil {
+		return kids
+	}
+	return procChildrenFromScan(pid)
+}
+
+// procChildrenFromTask agrega /proc/<pid>/task/<tid>/children sobre TODOS los
+// hilos (tasks) del proceso. Cada `children` lista solo los hijos parenteados
+// a ESE task, asi que un proceso multihilo (un shell que hizo fork desde un
+// hilo no principal, o el propio test runner de Go) puede tener hijos repartidos
+// entre varios tasks. Devuelve nil si el directorio task/ no existe o ningun
+// task expone `children` (kernel sin CONFIG_PROC_CHILDREN), para que el caller
+// use el fallback de scan por PPID.
+func procChildrenFromTask(pid int) []int {
+	taskDir := fmt.Sprintf("/proc/%d/task", pid)
+	tasks, err := os.ReadDir(taskDir)
+	if err != nil {
+		return nil
+	}
+	var kids []int
+	supported := false
+	for _, task := range tasks {
+		tid := task.Name()
+		data, err := os.ReadFile(filepath.Join(taskDir, tid, "children"))
+		if err != nil {
+			continue // este task no expone children; probar el resto
+		}
+		supported = true
+		for _, tok := range strings.Fields(string(data)) {
+			if k, err := strconv.Atoi(tok); err == nil {
+				kids = append(kids, k)
+			}
+		}
+	}
+	if !supported {
+		return nil // kernel sin CONFIG_PROC_CHILDREN -> fallback a scan
+	}
+	// Distinguir "sin hijos" (slice vacio no-nil) de "sin soporte" (nil arriba).
+	if kids == nil {
+		return []int{}
+	}
+	return kids
+}
+
+// procChildrenFromScan escanea /proc/*/stat buscando procesos cuyo PPID (campo
+// 4 de stat, indice 1 tras el comm entre parentesis) sea <pid>.
+func procChildrenFromScan(parent int) []int {
+	entries, err := os.ReadDir("/proc")
+	if err != nil {
+		return nil
+	}
+	var kids []int
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		childPID, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue // no es un directorio de PID
+		}
+		if procPPID(childPID) == parent {
+			kids = append(kids, childPID)
+		}
+	}
+	return kids
+}
+
+// procPPID extrae el PPID (campo 4 de /proc/<pid>/stat). El comm (campo 2) va
+// entre parentesis y puede contener espacios y ')', asi que se parsea tomando
+// lo que hay tras el ULTIMO ')'. Tras el comm, los campos son: state(0) ppid(1)
+// pgrp(2)... -> el PPID es el indice 1 de ese resto.
+func procPPID(pid int) int {
+	data, err := os.ReadFile(filepath.Join("/proc", strconv.Itoa(pid), "stat"))
+	if err != nil {
+		return -1
+	}
+	s := string(data)
+	close := strings.LastIndex(s, ")")
+	if close < 0 {
+		return -1
+	}
+	rest := strings.Fields(s[close+1:])
+	const ppidIdx = 1 // state=rest[0], ppid=rest[1]
+	if len(rest) <= ppidIdx {
+		return -1
+	}
+	ppid, err := strconv.Atoi(rest[ppidIdx])
+	if err != nil {
+		return -1
+	}
+	return ppid
+}
@@ -0,0 +1,62 @@
+---
+name: tmux_map_claude_panes
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func TmuxMapClaudePanes(socket string) (map[int]string, error)"
+description: "Devuelve un mapa claudePID -> window_id de todos los panes de un socket tmux aislado (tmux -L <socket>) cuyo proceso de pane (o un descendiente directo) sea un proceso `claude`. Lee /proc para decidir si cada #{pane_pid} es o tiene como hijo un comm == 'claude'. Permite a la TUI fleetview saber que Claude de su lista ya vive en la sesion fleet (y por tanto es conmutable) y en que window. Capa de control tmux de fleetview."
+tags: [claude-fleet, infra, tmux, claude, proc, fleet, tui]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "socket"
+    desc: "Nombre del socket tmux aislado (tmux -L <socket>). En fleetview es 'fleet'. Escanea TODOS los panes del servidor de ese socket (list-panes -a)."
+output: "map[int]string con clave = PID del proceso claude encontrado bajo cada pane y valor = window_id (@N) de ese pane. Panes sin claude (ni pane_pid ni hijo directo con comm 'claude') se omiten. Mapa vacio (sin error) si ningun pane corre claude. Error si socket viene vacio o si `tmux list-panes -a` falla."
+tested: true
+tests: ["TestTmuxMapClaudePanesNoClaude", "TestTmuxMapClaudePanesEmptySocket", "TestProcCommSelf", "TestFindClaudePIDDetectsChild"]
+test_file_path: "functions/infra/tmux_map_claude_panes_test.go"
+file_path: "functions/infra/tmux_map_claude_panes.go"
+notes: "Build tag //go:build !windows (depende de /proc). Comparte runTmux con tmux_new_claude_window y tmux_swap_window_into_console (mismo paquete infra). Deteccion claude: lee /proc/<pid>/comm; si no es 'claude', recorre hijos directos. Hijos directos via /proc/<pid>/task/<pid>/children (rapido, requiere CONFIG_PROC_CHILDREN); fallback a escanear /proc/*/stat por PPID (campo 4, parseando el comm entre parentesis tomando lo que hay tras el ULTIMO ')'). En produccion cada pane corre `exec claude`, asi que pane_pid == claude PID y basta el primer comm; el barrido de hijos es robustez para shells intermedios."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	// Que Claude ya vive en la sesion fleet (socket aislado 'fleet') y donde.
+	byPID, err := infra.TmuxMapClaudePanes("fleet")
+	if err != nil {
+		panic(err)
+	}
+	for claudePID, windowID := range byPID {
+		fmt.Printf("claude pid=%d -> window %s\n", claudePID, windowID)
+	}
+}
+```
+
+## Cuando usarla
+
+Cuando la TUI fleetview refresca su lista de Claudes y necesita marcar cuales ya estan dentro de la sesion `fleet` (conmutables con `tmux_swap_window_into_console`) y en que window. Cruza el PID de cada entrada de `list_claude_fleet` contra este mapa: si el PID esta, el Claude es swap-able y el valor es su `window_id`.
+
+## Gotchas
+
+- Mapea por PID de claude, no por pane_pid: si el pane corre un shell que lanzo claude como hijo, la clave es el PID del hijo claude.
+- Solo busca hijos DIRECTOS (un nivel). En produccion fleetview usa `exec claude`, asi que pane_pid == claude PID y el caso comun no necesita el barrido.
+- Depende de `/proc` (Linux): build tag `//go:build !windows`. En kernels sin `CONFIG_PROC_CHILDREN` cae a escanear `/proc/*/stat` por PPID, mas lento pero equivalente.
+- Lee `comm` (truncado a 15 chars por el kernel); `claude` cabe entero, sin riesgo de truncado.
+- Panes sin claude se omiten silenciosamente: un mapa vacio significa "ningun Claude vivo en este socket", no es error.
+- Opera SIEMPRE sobre el socket aislado (`tmux -L <socket>`), escaneando todos sus panes con `list-panes -a`.
@@ -0,0 +1,102 @@
+//go:build !windows && linux
+
+package infra
+
+import (
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestTmuxMapClaudePanesNoClaude verifica que, sobre un servidor tmux aislado
+// cuyos panes solo corren `cat` (no claude), el mapa devuelto esta vacio: ningun
+// pane es ni tiene como hijo un proceso `claude`. Tambien valida que el comando
+// list-panes -a se ejecuta sin error sobre el socket aislado.
+func TestTmuxMapClaudePanesNoClaude(t *testing.T) {
+	tmuxAvailable(t)
+	socket := isolatedSocket(t)
+	session := "fleet"
+	startConsoleSession(t, socket, session)
+	newCatWindow(t, socket, session)
+	newCatWindow(t, socket, session)
+
+	m, err := TmuxMapClaudePanes(socket)
+	if err != nil {
+		t.Fatalf("TmuxMapClaudePanes: %v", err)
+	}
+	if len(m) != 0 {
+		t.Errorf("ningun pane corre claude, el mapa deberia estar vacio, tiene %d: %v", len(m), m)
+	}
+}
+
+func TestTmuxMapClaudePanesEmptySocket(t *testing.T) {
+	if _, err := TmuxMapClaudePanes(""); err == nil {
+		t.Error("socket vacio deberia dar error")
+	}
+}
+
+// TestProcCommSelf valida procComm contra el propio proceso de test: comm debe
+// coincidir con el de /proc/self/comm (el binario de test, no "claude").
+func TestProcCommSelf(t *testing.T) {
+	self := os.Getpid()
+	got := procComm(self)
+	if got == "" {
+		t.Fatalf("procComm(%d) devolvio vacio", self)
+	}
+	want := strings.TrimSpace(readSelfComm(t))
+	if got != want {
+		t.Errorf("procComm(%d) = %q, /proc/self/comm = %q", self, got, want)
+	}
+}
+
+func readSelfComm(t *testing.T) string {
+	t.Helper()
+	data, err := os.ReadFile("/proc/self/comm")
+	if err != nil {
+		t.Fatalf("read /proc/self/comm: %v", err)
+	}
+	return string(data)
+}
+
+// TestFindClaudePIDDetectsChild ejercita el mecanismo "¿este pid o hijo es
+// claude?" SIN claude real: lanza un proceso hijo cuyo comm sea verificable y
+// comprueba que (a) findClaudePID(propio pid) no lo confunde con claude, y (b)
+// procChildren detecta al hijo lanzado. Testear con un proceso `claude` real es
+// inviable en CI; este test valida el helper de deteccion con un comm conocido.
+func TestFindClaudePIDDetectsChild(t *testing.T) {
+	// (a) El proceso de test NO es claude: findClaudePID no debe reportarlo.
+	if _, ok := findClaudePID(os.Getpid()); ok {
+		// Solo seria true si el binario de test se llamara "claude" (no es el caso).
+		t.Errorf("findClaudePID(self) reporto claude para un proceso que no lo es")
+	}
+
+	// (b) Lanzamos un hijo `sleep` (comm conocido "sleep") y verificamos que
+	//     procChildren lo detecta como descendiente directo. Esto valida el
+	//     mecanismo de barrido de hijos que findClaudePID usa internamente para
+	//     localizar un comm objetivo (en produccion: "claude").
+	cmd := exec.Command("sleep", "3")
+	if err := cmd.Start(); err != nil {
+		t.Skipf("no se pudo lanzar sleep: %v", err)
+	}
+	childPID := cmd.Process.Pid
+	t.Cleanup(func() { _ = cmd.Process.Kill(); _ = cmd.Wait() })
+
+	kids := procChildren(os.Getpid())
+	found := false
+	for _, k := range kids {
+		if k == childPID {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("procChildren(self) no incluyo al hijo %d; kids=%v", childPID, kids)
+	}
+
+	// Y el comm del hijo debe ser "sleep", confirmando el camino que findClaudePID
+	// usa para comparar contra "claude".
+	if comm := procComm(childPID); comm != "sleep" {
+		t.Errorf("procComm(%d) = %q, esperado \"sleep\"", childPID, comm)
+	}
+}
@@ -0,0 +1,63 @@
+//go:build !windows
+
+package infra
+
+import (
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+// TmuxNewClaudeWindow crea una window nueva en <session> del socket <socket>
+// que corre `claude --dangerously-skip-permissions` en <cwd>. Acepta argumentos
+// extra opcionales que se anaden al comando (ej. "--resume", "<sessionId>" para
+// reabrir una conversacion). Devuelve el window_id (ej "@7"). No cambia el foco
+// (-d). Opera SIEMPRE sobre el socket aislado pasado como parametro
+// (tmux -L <socket>), nunca sobre el servidor tmux por defecto del usuario.
+func TmuxNewClaudeWindow(socket, session, cwd string, extraArgs ...string) (string, error) {
+	if socket == "" {
+		return "", fmt.Errorf("tmux_new_claude_window: socket vacio")
+	}
+	if session == "" {
+		return "", fmt.Errorf("tmux_new_claude_window: session vacia")
+	}
+	if cwd == "" {
+		return "", fmt.Errorf("tmux_new_claude_window: cwd vacio")
+	}
+
+	// El comando del pane: claude reemplaza al shell, asi que #{pane_pid} sera el
+	// PID de claude. Se anaden los argumentos extra (ej. --resume <id>).
+	command := "claude --dangerously-skip-permissions"
+	if len(extraArgs) > 0 {
+		command += " " + strings.Join(extraArgs, " ")
+	}
+
+	// -d: no cambia el foco. -P -F '#{window_id}': imprime el id de la window
+	// creada. -t <session>: la crea en esa sesion. -c <cwd>: working dir del pane.
+	out, stderr, err := runTmux(socket,
+		"new-window", "-d", "-P", "-F", "#{window_id}",
+		"-t", session, "-c", cwd,
+		command,
+	)
+	if err != nil {
+		return "", fmt.Errorf("tmux_new_claude_window: new-window en %q: %w (%s)", session, err, stderr)
+	}
+
+	windowID := strings.TrimSpace(out)
+	if windowID == "" {
+		return "", fmt.Errorf("tmux_new_claude_window: new-window no devolvio window_id (stderr=%q)", stderr)
+	}
+	return windowID, nil
+}
+
+// runTmux ejecuta `tmux -L <socket> <args...>` y devuelve stdout, stderr y el
+// error de ejecucion. Helper comun a la capa de control tmux de fleetview.
+func runTmux(socket string, args ...string) (stdout, stderr string, err error) {
+	full := append([]string{"-L", socket}, args...)
+	cmd := exec.Command("tmux", full...)
+	var outBuf, errBuf strings.Builder
+	cmd.Stdout = &outBuf
+	cmd.Stderr = &errBuf
+	err = cmd.Run()
+	return outBuf.String(), errBuf.String(), err
+}
@@ -0,0 +1,64 @@
+---
+name: tmux_new_claude_window
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func TmuxNewClaudeWindow(socket, session, cwd string) (string, error)"
+description: "Crea una window detached nueva en una sesion tmux de un socket aislado (tmux -L <socket>) que corre `claude --dangerously-skip-permissions` en el cwd dado, y devuelve su window_id (ej @7). No cambia el foco. Capa de control tmux de la app TUI fleetview para arrancar un Claude nuevo dentro de la sesion fleet. Como el pane corre claude via exec, el #{pane_pid} del pane resultante es el PID del proceso claude."
+tags: [claude-fleet, infra, tmux, claude, fleet, tui]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "socket"
+    desc: "Nombre del socket tmux aislado (se invoca tmux -L <socket>). En fleetview es 'fleet'. Nunca opera sobre el servidor tmux por defecto del usuario."
+  - name: "session"
+    desc: "Nombre de la sesion tmux donde crear la window (ej 'fleet'). Debe existir."
+  - name: "cwd"
+    desc: "Working directory del nuevo pane/Claude (-c). Ruta absoluta del proyecto donde arrancar el Claude."
+output: "window_id de la window creada (string con la forma @N, ej '@7'), tal cual lo imprime `tmux new-window -P -F '#{window_id}'`. Error si socket/session/cwd vienen vacios o si tmux falla (sesion inexistente, socket no accesible)."
+tested: true
+tests: ["TestTmuxNewClaudeWindow", "TestTmuxNewClaudeWindowEmptyArgs"]
+test_file_path: "functions/infra/tmux_new_claude_window_test.go"
+file_path: "functions/infra/tmux_new_claude_window.go"
+notes: "Build tag //go:build !windows (capa tmux de fleetview, no portable a Windows). Comparte el helper runTmux con tmux_swap_window_into_console y tmux_map_claude_panes (mismo paquete infra). El comando que corre el pane es literalmente 'claude --dangerously-skip-permissions'; tmux lo arranca via su shell pero claude reemplaza al proceso, asi que pane_pid == claude PID."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"fn-registry/functions/infra"
+)
+
+func main() {
+	// Arranca un Claude nuevo en /home/enmanuel/fn_registry dentro de la
+	// sesion 'fleet' del socket aislado 'fleet'. No roba el foco.
+	windowID, err := infra.TmuxNewClaudeWindow("fleet", "fleet", "/home/enmanuel/fn_registry")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("Claude nuevo en window", windowID) // ej: @7
+}
+```
+
+## Cuando usarla
+
+Cuando la TUI fleetview necesita arrancar un Claude nuevo dentro de la sesion `fleet` sin sacar al usuario de la consola actual. El Claude nace parkeado en su propia window (detached); luego `TmuxSwapWindowIntoConsole` lo trae a la derecha de la TUI cuando el usuario lo selecciona.
+
+## Gotchas
+
+- Opera SIEMPRE sobre el socket aislado (`tmux -L <socket>`). Nunca toca el servidor tmux por defecto del usuario.
+- La sesion `session` debe existir antes de llamar; la funcion crea la window, no la sesion.
+- Devuelve el `window_id` (`@N`), no el `window_index`. El swap posterior usa este id.
+- `-d` garantiza que no cambia el foco: el Claude nuevo queda parkeado, no se muestra solo.
+- Build tag `//go:build !windows`: no compila ni corre en Windows.
@@ -0,0 +1,84 @@
+//go:build !windows && linux
+
+package infra
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+// tmuxAvailable reports whether the tmux binary is present. Tests skip when it
+// is not (CI without tmux).
+func tmuxAvailable(t *testing.T) {
+	t.Helper()
+	if _, err := exec.LookPath("tmux"); err != nil {
+		t.Skipf("tmux no disponible en PATH: %v", err)
+	}
+}
+
+// isolatedSocket returns a per-test isolated tmux socket name and registers a
+// cleanup that kills its server. All commands in a test run against
+// `tmux -L <socket> ...`, never the user's default server.
+func isolatedSocket(t *testing.T) string {
+	t.Helper()
+	socket := fmt.Sprintf("fleettest_%d_%d", os.Getpid(), time.Now().UnixNano())
+	t.Cleanup(func() {
+		// best-effort: el server puede no existir si el test fallo antes de crearlo
+		_ = exec.Command("tmux", "-L", socket, "kill-server").Run()
+	})
+	return socket
+}
+
+// startConsoleSession crea una sesion <session> con una window "console" cuyo
+// pane 0 corre `cat` (simula la TUI fleetview, un proceso que no termina).
+func startConsoleSession(t *testing.T, socket, session string) {
+	t.Helper()
+	cmd := exec.Command("tmux", "-L", socket,
+		"new-session", "-d", "-s", session, "-n", "console", "cat")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("new-session: %v (%s)", err, out)
+	}
+}
+
+func TestTmuxNewClaudeWindow(t *testing.T) {
+	tmuxAvailable(t)
+	socket := isolatedSocket(t)
+	session := "fleet"
+	startConsoleSession(t, socket, session)
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+
+	// El comando real ("claude ...") no esta disponible en el test, pero
+	// new-window devuelve el window_id ANTES de que el comando pueda fallar:
+	// tmux crea la window y reporta su id sincronamente. Validamos que el id
+	// venga con la forma esperada (@N) y no vacio.
+	windowID, err := TmuxNewClaudeWindow(socket, session, cwd)
+	if err != nil {
+		t.Fatalf("TmuxNewClaudeWindow: %v", err)
+	}
+	if windowID == "" {
+		t.Fatal("window_id vacio")
+	}
+	if !strings.HasPrefix(windowID, "@") {
+		t.Errorf("window_id %q no tiene la forma esperada @N", windowID)
+	}
+}
+
+func TestTmuxNewClaudeWindowEmptyArgs(t *testing.T) {
+	if _, err := TmuxNewClaudeWindow("", "fleet", "/tmp"); err == nil {
+		t.Error("socket vacio deberia dar error")
+	}
+	if _, err := TmuxNewClaudeWindow("sock", "", "/tmp"); err == nil {
+		t.Error("session vacia deberia dar error")
+	}
+	if _, err := TmuxNewClaudeWindow("sock", "fleet", ""); err == nil {
+		t.Error("cwd vacio deberia dar error")
+	}
+}
@@ -0,0 +1,213 @@
+//go:build !windows
+
+package infra
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// TmuxSwapWindowIntoConsole trae el primer pane de <windowID> al pane derecho
+// de la window "console" de <session> (al lado del pane sidebar = la TUI),
+// parkeando el Claude que estuviera a la derecha en su propia window (detached,
+// sin robar foco), y re-fija el ancho del pane sidebar al que tuviera antes.
+//
+// Contrato de la window console:
+//   - pane MAS A LA IZQUIERDA (menor pane_index) = siempre la TUI fleetview.
+//   - cualquier otro pane en console = el Claude activo (puede no haber ninguno).
+//
+// NOTA base-index: el socket aislado (tmux -L <socket>) sigue leyendo
+// ~/.tmux.conf, asi que si el usuario tiene `pane-base-index 1` (muy comun) el
+// primer pane es el indice 1, no 0. Por eso esta funcion NUNCA referencia panes
+// por indice literal "0": resuelve el pane sidebar como el de MENOR pane_index y
+// opera siempre por pane_id, que es estable e inmune al base-index. Targetear
+// "console.0" rompia con "can't find pane: 0" en esas configuraciones.
+//
+// Idempotente: si <windowID> ES ya la window console, no hace nada salvo
+// re-fijar el ancho del sidebar. Si el Claude objetivo ya esta en console,
+// tampoco rompe nada. Opera SIEMPRE sobre el socket aislado pasado como
+// parametro (tmux -L <socket>).
+func TmuxSwapWindowIntoConsole(socket, session, windowID string) error {
+	if socket == "" {
+		return fmt.Errorf("tmux_swap_window_into_console: socket vacio")
+	}
+	if session == "" {
+		return fmt.Errorf("tmux_swap_window_into_console: session vacia")
+	}
+	if windowID == "" {
+		return fmt.Errorf("tmux_swap_window_into_console: windowID vacio")
+	}
+
+	// Capturar el ancho ACTUAL del pane sidebar (la TUI) antes de tocar nada,
+	// para preservarlo tras el break/join (que redistribuyen el espacio). Asi el
+	// ancho del sidebar lo decide quien creo la sesion (launch_fleetclaude), no un
+	// valor fijo aqui.
+	width := tmuxSidebarWidth(socket, session)
+
+	// Caso borde: si windowID ya ES la window console, no hay nada que hacer.
+	// Resolvemos el window_id real de console y lo comparamos con el pedido.
+	consoleID, err := tmuxConsoleWindowID(socket, session)
+	if err != nil {
+		return err
+	}
+	if consoleID == windowID {
+		// El objetivo ya es console. Solo re-fijamos el ancho de la TUI.
+		return tmuxResizeConsoleTUI(socket, session, width)
+	}
+
+	// 1. Localiza el pane sidebar (TUI, menor indice) y el pane derecho actual
+	//    (cualquier otro) de console, ambos por pane_id.
+	tuiPaneID, rightPaneID, err := tmuxConsolePanes(socket, session)
+	if err != nil {
+		return err
+	}
+	if tuiPaneID == "" {
+		return fmt.Errorf("tmux_swap_window_into_console: console sin panes en %q", session)
+	}
+
+	// 2. Si existe un pane no-sidebar en console, sacarlo a su propia window
+	//    (parking), detached y sin cambiar foco.
+	if rightPaneID != "" {
+		if _, stderr, err := runTmux(socket, "break-pane", "-d", "-s", rightPaneID); err != nil {
+			return fmt.Errorf("tmux_swap_window_into_console: break-pane de %q: %w (%s)", rightPaneID, err, stderr)
+		}
+	}
+
+	// 3. Traer el primer pane de windowID a la derecha de la TUI (-h = split
+	//    horizontal, lado a lado). join-pane requiere que origen y destino sean
+	//    windows distintas (ya garantizado: consoleID != windowID arriba).
+	srcPaneID, err := tmuxFirstPaneID(socket, windowID)
+	if err != nil {
+		return err
+	}
+	if _, stderr, err := runTmux(socket, "join-pane", "-h", "-s", srcPaneID, "-t", tuiPaneID); err != nil {
+		return fmt.Errorf("tmux_swap_window_into_console: join-pane %q -> %q: %w (%s)", srcPaneID, tuiPaneID, err, stderr)
+	}
+
+	// 4. Re-fijar el ancho del pane sidebar (TUI) al que tenia antes del swap.
+	if _, stderr, err := runTmux(socket, "resize-pane", "-t", tuiPaneID, "-x", strconv.Itoa(width)); err != nil {
+		return fmt.Errorf("tmux_swap_window_into_console: resize-pane de %q a %d col: %w (%s)", tuiPaneID, width, err, stderr)
+	}
+	return nil
+}
+
+// tmuxConsoleWindowID resuelve el window_id (ej "@3") de la window llamada
+// "console" en <session>.
+func tmuxConsoleWindowID(socket, session string) (string, error) {
+	out, stderr, err := runTmux(socket, "list-windows", "-t", session, "-F", "#{window_id} #{window_name}")
+	if err != nil {
+		return "", fmt.Errorf("tmux_swap_window_into_console: list-windows de %q: %w (%s)", session, err, stderr)
+	}
+	for _, line := range strings.Split(strings.TrimSpace(out), "\n") {
+		fields := strings.Fields(strings.TrimSpace(line))
+		if len(fields) < 2 {
+			continue
+		}
+		if fields[1] == "console" {
+			return fields[0], nil
+		}
+	}
+	return "", fmt.Errorf("tmux_swap_window_into_console: window 'console' no encontrada en %q", session)
+}
+
+// tmuxConsolePanes devuelve el pane_id del sidebar (pane de MENOR pane_index =
+// la TUI) y el pane_id del primer pane no-sidebar (el Claude actual, si lo hay)
+// de la window console. rightPaneID es "" si console solo tiene el sidebar.
+// Inmune al base-index porque ordena por pane_index numerico, no asume "0".
+func tmuxConsolePanes(socket, session string) (tuiPaneID, rightPaneID string, err error) {
+	panes, err := tmuxPanesSorted(socket, session+":console")
+	if err != nil {
+		return "", "", fmt.Errorf("tmux_swap_window_into_console: %w", err)
+	}
+	if len(panes) == 0 {
+		return "", "", nil
+	}
+	tuiPaneID = panes[0].id
+	if len(panes) > 1 {
+		rightPaneID = panes[1].id
+	}
+	return tuiPaneID, rightPaneID, nil
+}
+
+// tmuxFirstPaneID devuelve el pane_id del primer pane (menor pane_index) de la
+// window <windowID>.
+func tmuxFirstPaneID(socket, windowID string) (string, error) {
+	panes, err := tmuxPanesSorted(socket, windowID)
+	if err != nil {
+		return "", fmt.Errorf("tmux_swap_window_into_console: %w", err)
+	}
+	if len(panes) == 0 {
+		return "", fmt.Errorf("tmux_swap_window_into_console: window %q sin panes", windowID)
+	}
+	return panes[0].id, nil
+}
+
+type tmuxPaneRef struct {
+	index int
+	id    string
+	width int
+}
+
+// tmuxPanesSorted lista los panes de <target> ordenados por pane_index
+// ascendente. El primero es el mas a la izquierda/arriba (el sidebar en
+// console).
+func tmuxPanesSorted(socket, target string) ([]tmuxPaneRef, error) {
+	out, stderr, err := runTmux(socket, "list-panes", "-t", target, "-F", "#{pane_index} #{pane_id} #{pane_width}")
+	if err != nil {
+		return nil, fmt.Errorf("list-panes de %q: %w (%s)", target, err, stderr)
+	}
+	var panes []tmuxPaneRef
+	for _, line := range strings.Split(strings.TrimSpace(out), "\n") {
+		fields := strings.Fields(strings.TrimSpace(line))
+		if len(fields) < 2 {
+			continue
+		}
+		idx, e := strconv.Atoi(fields[0])
+		if e != nil {
+			continue
+		}
+		ref := tmuxPaneRef{index: idx, id: fields[1]}
+		if len(fields) >= 3 {
+			if w, e := strconv.Atoi(fields[2]); e == nil {
+				ref.width = w
+			}
+		}
+		panes = append(panes, ref)
+	}
+	sort.Slice(panes, func(i, j int) bool { return panes[i].index < panes[j].index })
+	return panes, nil
+}
+
+// tmuxSidebarWidth devuelve el ancho a preservar para el pane sidebar (la TUI).
+// Solo tiene sentido leer el ancho actual si console ya tiene >1 pane (TUI +
+// Claude); con un unico pane, el sidebar es full-width y no representa el ancho
+// real del sidebar, asi que se usa el default.
+func tmuxSidebarWidth(socket, session string) int {
+	const def = 52
+	panes, err := tmuxPanesSorted(socket, session+":console")
+	if err != nil || len(panes) <= 1 {
+		return def
+	}
+	if w := panes[0].width; w > 0 {
+		return w
+	}
+	return def
+}
+
+// tmuxResizeConsoleTUI fija el ancho del pane sidebar de console a width
+// columnas, resolviendo su pane_id (no asume el indice 0).
+func tmuxResizeConsoleTUI(socket, session string, width int) error {
+	tuiPaneID, _, err := tmuxConsolePanes(socket, session)
+	if err != nil {
+		return err
+	}
+	if tuiPaneID == "" {
+		return nil // console sin panes: nada que redimensionar
+	}
+	if _, stderr, err := runTmux(socket, "resize-pane", "-t", tuiPaneID, "-x", strconv.Itoa(width)); err != nil {
+		return fmt.Errorf("tmux_swap_window_into_console: resize-pane de %q a %d col: %w (%s)", tuiPaneID, width, err, stderr)
+	}
+	return nil
+}
@@ -0,0 +1,65 @@
+---
+name: tmux_swap_window_into_console
+kind: function
+lang: go
+domain: infra
+version: "1.0.1"
+purity: impure
+signature: "func TmuxSwapWindowIntoConsole(socket, session, windowID string) error"
+description: "Conmuta que Claude esta a la derecha de la TUI fleetview en una sesion tmux de un socket aislado (tmux -L <socket>). Trae el primer pane de <windowID> al pane derecho de la window 'console' (al lado del pane sidebar = la TUI), parkea en su propia window el Claude que estuviera a la derecha (detached, sin robar foco) y re-fija el ancho del sidebar al que tuviera antes (default 52 col). El sidebar se resuelve como el pane de MENOR pane_index y se opera por pane_id, NO por indice literal 0: inmune a `pane-base-index 1` del ~/.tmux.conf del usuario. Idempotente: si el objetivo ya es la window console solo re-aplica el ancho. Capa de control tmux de la app TUI fleetview."
+tags: [claude-fleet, infra, tmux, claude, fleet, tui]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: "socket"
+    desc: "Nombre del socket tmux aislado (tmux -L <socket>). En fleetview es 'fleet'. Nunca opera sobre el servidor tmux por defecto."
+  - name: "session"
+    desc: "Sesion tmux que contiene la window 'console' (ej 'fleet'). El pane 0 de console es la TUI; el resto, el Claude activo."
+  - name: "windowID"
+    desc: "window_id (@N) de la window cuyo primer pane se quiere traer a la derecha de la TUI. Tipicamente el devuelto por tmux_new_claude_window o por tmux_map_claude_panes."
+output: "nil en exito. Error si socket/session/windowID vienen vacios, si la window 'console' no existe en la sesion, o si alguno de los comandos tmux (list-panes, break-pane, join-pane, resize-pane) falla. El estado final de console: pane sidebar (menor indice) = TUI (52 col por default) + pane derecho = el Claude de windowID."
+tested: true
+tests: ["TestTmuxSwapWindowIntoConsole", "TestTmuxSwapWindowIntoConsoleParksPrevious", "TestTmuxSwapWindowIntoConsoleEmptyArgs"]
+test_file_path: "functions/infra/tmux_swap_window_into_console_test.go"
+file_path: "functions/infra/tmux_swap_window_into_console.go"
+notes: "Build tag //go:build !windows. Comparte runTmux con tmux_new_claude_window y tmux_map_claude_panes (mismo paquete infra). Secuencia interna: (1) list-panes de console ordenados por pane_index, sidebar = menor indice (TUI), right = primer pane no-sidebar; (2) break-pane -d del right si existe (parking); (3) join-pane -h del primer pane de windowID a la derecha del sidebar (por pane_id); (4) resize-pane -x <ancho> del sidebar por pane_id. Caso borde: si windowID ya ES la window console, solo re-aplica el resize. TODO targeting es por pane_id, NUNCA por indice literal 0 (rompia con 'can't find pane: 0' bajo pane-base-index 1 que el socket aislado hereda de ~/.tmux.conf). break-pane requiere que la window destino sea distinta del origen, garantizado por la comprobacion consoleID != windowID."
+---
+
+## Ejemplo
+
+```go
+package main
+
+import "fn-registry/functions/infra"
+
+func main() {
+	// El usuario selecciona en fleetview el Claude que vive en la window @7.
+	// Lo trae a la derecha de la TUI (pane 1 de console), parkeando el que
+	// estuviera ahi. La TUI (pane 0) queda re-fijada a 40 columnas.
+	if err := infra.TmuxSwapWindowIntoConsole("fleet", "fleet", "@7"); err != nil {
+		panic(err)
+	}
+}
+```
+
+## Cuando usarla
+
+Cada vez que el usuario conmuta en fleetview que Claude quiere ver a la derecha. Llamala con el `window_id` del Claude destino (de `tmux_map_claude_panes` para los ya vivos en la sesion, o de `tmux_new_claude_window` para uno recien arrancado). Encadena de forma natural tras `tmux_new_claude_window` para mostrar inmediatamente el Claude nuevo.
+
+## Gotchas
+
+- Idempotente: si el Claude objetivo ya es la window console, solo re-aplica el ancho del sidebar; no rompe nada.
+- El pane sidebar de console (el de MENOR pane_index) es SIEMPRE la TUI y nunca se mueve ni se parkea: la funcion solo toca el pane derecho (cualquier otro pane).
+- NO asume que el sidebar es el indice 0. El socket aislado (`tmux -L <socket>`) hereda `~/.tmux.conf`, asi que con `pane-base-index 1` (muy comun) el primer pane es el indice 1. Targetear `console.0` rompia con `can't find pane: 0` y dejaba console a medias (break ya hecho, join fallido). Por eso todo el targeting es por `pane_id`.
+- `join-pane` exige que la window origen sea distinta de console; la funcion lo comprueba (consoleID != windowID) y si coinciden no hace el join.
+- `break-pane -d` saca el Claude anterior a su propia window detached: sigue vivo y parkeado, no se mata.
+- El ancho del sidebar se re-fija SIEMPRE al final (incluso en el caso borde) para que la TUI no se reduzca tras el reflow del split.
+- Opera SIEMPRE sobre el socket aislado (`tmux -L <socket>`). Build tag `//go:build !windows`.
+
+## Capability growth log
+
+- v1.0.1 (2026-06-17) — fix: resuelve el pane sidebar por menor `pane_index` y opera por `pane_id` en vez de `console.0`/indice 0. Antes rompia con `can't find pane: 0` bajo `pane-base-index 1` (el socket aislado hereda ~/.tmux.conf), dejando la sesion fleet con las windows desperdigadas y sin sidebar. Tests actualizados a base-index-agnostico; default de ancho del sidebar 47 -> 52 (coincide con launch_fleetclaude).
@@ -0,0 +1,154 @@
+//go:build !windows && linux
+
+package infra
+
+import (
+	"os/exec"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// newCatWindow crea una window detached en <session> que corre `cat` (un
+// proceso persistente que simula un claude parkeado) y devuelve su window_id.
+func newCatWindow(t *testing.T, socket, session string) string {
+	t.Helper()
+	out, err := exec.Command("tmux", "-L", socket,
+		"new-window", "-d", "-P", "-F", "#{window_id}", "-t", session, "cat").CombinedOutput()
+	if err != nil {
+		t.Fatalf("new-window cat: %v (%s)", err, out)
+	}
+	id := strings.TrimSpace(string(out))
+	if id == "" {
+		t.Fatal("new-window cat no devolvio window_id")
+	}
+	return id
+}
+
+// consolePanes devuelve las lineas "pane_index pane_id width" de la window
+// console de <session>.
+func consolePanes(t *testing.T, socket, session string) []string {
+	t.Helper()
+	out, err := exec.Command("tmux", "-L", socket,
+		"list-panes", "-t", session+":console",
+		"-F", "#{pane_index} #{pane_id} #{pane_width}").CombinedOutput()
+	if err != nil {
+		t.Fatalf("list-panes console: %v (%s)", err, out)
+	}
+	var lines []string
+	for _, l := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		if l = strings.TrimSpace(l); l != "" {
+			lines = append(lines, l)
+		}
+	}
+	return lines
+}
+
+func TestTmuxSwapWindowIntoConsole(t *testing.T) {
+	tmuxAvailable(t)
+	socket := isolatedSocket(t)
+	session := "fleet"
+	startConsoleSession(t, socket, session)
+
+	// Una window aparte con `cat` simula un Claude parkeado conmutable.
+	claudeWin := newCatWindow(t, socket, session)
+
+	// Estado inicial: console tiene un solo pane (la TUI, indice 0).
+	if got := len(consolePanes(t, socket, session)); got != 1 {
+		t.Fatalf("console deberia empezar con 1 pane, tiene %d", got)
+	}
+
+	if err := TmuxSwapWindowIntoConsole(socket, session, claudeWin); err != nil {
+		t.Fatalf("TmuxSwapWindowIntoConsole: %v", err)
+	}
+
+	// Tras el swap: console tiene 2 panes y el sidebar (pane de MENOR indice)
+	// mide 52 columnas (default del sidebar, ya que la console arrancó con un
+	// solo pane full-width). Se localiza por menor pane_index, NO por indice
+	// literal "0": bajo `pane-base-index 1` (que el socket hereda de
+	// ~/.tmux.conf) el primer pane es el indice 1.
+	panes := consolePanes(t, socket, session)
+	if len(panes) != 2 {
+		t.Fatalf("console deberia tener 2 panes tras swap, tiene %d: %v", len(panes), panes)
+	}
+	minIdx, sidebarWidth, found := -1, 0, false
+	for _, line := range panes {
+		f := strings.Fields(line)
+		if len(f) < 3 {
+			continue
+		}
+		idx, err := strconv.Atoi(f[0])
+		if err != nil {
+			t.Fatalf("pane_index no numerico: %q", f[0])
+		}
+		w, err := strconv.Atoi(f[2])
+		if err != nil {
+			t.Fatalf("ancho de pane no numerico: %q", f[2])
+		}
+		if !found || idx < minIdx {
+			minIdx, sidebarWidth, found = idx, w, true
+		}
+	}
+	if !found {
+		t.Fatal("no se encontro ningun pane en console")
+	}
+	if sidebarWidth != 52 {
+		t.Errorf("ancho del sidebar (pane menor indice = %d) = %d, esperado 52", minIdx, sidebarWidth)
+	}
+}
+
+func TestTmuxSwapWindowIntoConsoleParksPrevious(t *testing.T) {
+	tmuxAvailable(t)
+	socket := isolatedSocket(t)
+	session := "fleet"
+	startConsoleSession(t, socket, session)
+
+	winA := newCatWindow(t, socket, session)
+	winB := newCatWindow(t, socket, session)
+
+	// Trae A a console.
+	if err := TmuxSwapWindowIntoConsole(socket, session, winA); err != nil {
+		t.Fatalf("swap A: %v", err)
+	}
+	if got := len(consolePanes(t, socket, session)); got != 2 {
+		t.Fatalf("tras swap A console deberia tener 2 panes, tiene %d", got)
+	}
+
+	// Trae B: A se parkea fuera, console vuelve a 2 panes (TUI + B).
+	if err := TmuxSwapWindowIntoConsole(socket, session, winB); err != nil {
+		t.Fatalf("swap B: %v", err)
+	}
+	if got := len(consolePanes(t, socket, session)); got != 2 {
+		t.Fatalf("tras swap B console deberia tener 2 panes, tiene %d", got)
+	}
+
+	// El Claude A parkeado debe seguir vivo en alguna window de la sesion.
+	out, err := exec.Command("tmux", "-L", socket,
+		"list-windows", "-t", session, "-F", "#{window_id}").CombinedOutput()
+	if err != nil {
+		t.Fatalf("list-windows: %v (%s)", err, out)
+	}
+	winCount := 0
+	for _, l := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		if strings.TrimSpace(l) != "" {
+			winCount++
+		}
+	}
+	// Esperadas: console + (window de A parkeada). winB se consumio al unir su
+	// pane a console (la window vacia se cierra). winA: una window de parking.
+	if winCount < 2 {
+		t.Errorf("se esperaban >=2 windows (console + A parkeado), hay %d", winCount)
+	}
+}
+
+func TestTmuxSwapWindowIntoConsoleEmptyArgs(t *testing.T) {
+	if err := TmuxSwapWindowIntoConsole("", "fleet", "@1"); err == nil {
+		t.Error("socket vacio deberia dar error")
+	}
+	if err := TmuxSwapWindowIntoConsole("sock", "", "@1"); err == nil {
+		t.Error("session vacia deberia dar error")
+	}
+	if err := TmuxSwapWindowIntoConsole("sock", "fleet", ""); err == nil {
+		t.Error("windowID vacio deberia dar error")
+	}
+}
--- a/Show More
+++ b/Show More