From fa1a1b968d4459ffb2624fe8e074cfb21a2dfe2e Mon Sep 17 00:00:00 2001
From: Egutierrez <egutierrez@dead.dd>
Date: Wed, 1 Apr 2026 20:55:48 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20regla=20notebook=5Fcollaboration=20y=20?=
 =?UTF-8?q?actualizaci=C3=B3n=20INDEX?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nueva regla para colaboración en notebooks Jupyter via funciones del registry.
Documenta el flujo discover → read → write → exec y las reglas de uso.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/rules/INDEX.md                  |  1 +
 .claude/rules/notebook_collaboration.md | 55 +++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 .claude/rules/notebook_collaboration.md

diff --git a/.claude/rules/INDEX.md b/.claude/rules/INDEX.md
index cfa5009c..d845b5e2 100644
--- a/.claude/rules/INDEX.md
+++ b/.claude/rules/INDEX.md
@@ -15,3 +15,4 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente.
 | 09 | [go_packages.md](go_packages.md) | Nombre de paquete Go = nombre del directorio |
 | 10 | [apps_vs_functions.md](apps_vs_functions.md) | Codigo reutilizable en functions/, no reutilizable en apps/ |
 | 11 | [sources.md](sources.md) | Extraccion de funciones desde repos externos |
+| 12 | [notebook_collaboration.md](notebook_collaboration.md) | Colaboración en notebooks Jupyter via funciones del registry |
diff --git a/.claude/rules/notebook_collaboration.md b/.claude/rules/notebook_collaboration.md
new file mode 100644
index 00000000..6a6831cf
--- /dev/null
+++ b/.claude/rules/notebook_collaboration.md
@@ -0,0 +1,55 @@
+## Colaboración en notebooks Jupyter
+
+### Requisito previo
+
+El usuario debe tener Jupyter Lab corriendo en modo colaborativo (`--collaborative`) y el notebook abierto en el browser. Sin esto, los cambios no se ven en tiempo real.
+
+El launcher estándar (`run-jupyter-lab.sh` generado por `init_jupyter_analysis`) ya incluye `--collaborative`.
+
+### Funciones del registry (dominio `notebook`)
+
+| Función | ID | Para qué |
+|---|---|---|
+| `jupyter_discover` | `jupyter_discover_py_notebook` | Descubrir instancias Jupyter activas, kernels, sesiones, modo colaborativo |
+| `jupyter_read` | `jupyter_read_py_notebook` | Leer celdas (todas o una), metadata del notebook |
+| `jupyter_exec` | `jupyter_exec_py_notebook` | Ejecutar: append+execute, execute celda existente, o directo al kernel |
+| `jupyter_write` | `jupyter_write_py_notebook` | Escribir: append code/markdown, insert, edit, delete celdas |
+| `jupyter_kernel` | `jupyter_kernel_py_notebook` | CRUD de kernels: list, start, restart, interrupt, shutdown, sessions |
+
+### Invocación desde cualquier sesión de Claude
+
+```bash
+PYTHON="python/.venv/bin/python3"
+
+# 1. Descubrir qué Jupyter está corriendo
+$PYTHON python/functions/notebook/jupyter_discover.py --json
+
+# 2. Leer notebook
+$PYTHON python/functions/notebook/jupyter_read.py notebooks/01.ipynb --json
+
+# 3. Añadir celda y ejecutar (el usuario la ve en tiempo real)
+$PYTHON python/functions/notebook/jupyter_exec.py append notebooks/01.ipynb "df.describe()"
+
+# 4. Ejecutar celda existente
+$PYTHON python/functions/notebook/jupyter_exec.py cell notebooks/01.ipynb 3
+
+# 5. Ejecutar en kernel sin tocar notebook
+$PYTHON python/functions/notebook/jupyter_exec.py kernel "print(df.shape)"
+
+# 6. Añadir markdown
+$PYTHON python/functions/notebook/jupyter_write.py append-markdown notebooks/01.ipynb "## Resumen"
+
+# 7. Gestionar kernels
+$PYTHON python/functions/notebook/jupyter_kernel.py list
+$PYTHON python/functions/notebook/jupyter_kernel.py sessions
+$PYTHON python/functions/notebook/jupyter_kernel.py shutdown <kernel_id>
+```
+
+### Reglas de uso
+
+- **SIEMPRE** ejecutar `jupyter_discover` primero para confirmar que Jupyter está activo y el notebook abierto.
+- Las funciones resuelven automáticamente el `kernel_id` de la sesión del notebook y el `username` colaborativo via `/api/sessions` y `/api/me`.
+- Después de escribir/ejecutar, las funciones mantienen la conexión WebSocket 2 segundos para que Y.js propague los cambios al browser.
+- **NO usar MCP jupyter** — estas funciones reemplazan al MCP y funcionan desde cualquier directorio sin registrar nada.
+- El token por defecto es vacío (sin auth). Si el server tiene token, pasarlo con `--token`.
+- Los paths de notebooks son relativos a la raíz del servidor Jupyter (normalmente `analysis/{tema}/`).