2 changed files with 56 additions and 0 deletions
@@ -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 |
@@ -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}/`).