chore: añade directorio dev/ con issues y funciones implementadas

Tracking de issues completados (jupyter tools) y funciones implementadas (specs de diseño ya resueltas).

dev/issues/completed/001_jupyter_create_notebook.md

@@ -0,0 +1,27 @@
+# jupyter_write: crear notebooks nuevos
+
+**Componente:** `python/functions/notebook/jupyter_write.py`
+
+## Problema
+
+`jupyter_write.py append-*` falla con error websocket 4404 si el notebook no existe todavía. El modo colaborativo no puede inicializar un documento que no existe en disco.
+
+Actualmente hay que crear el .ipynb manualmente como archivo antes de poder usar las funciones jupyter.
+
+## Solución propuesta
+
+Añadir subcomando `create` a `jupyter_write.py`:
+
+```bash
+$PYTHON jupyter_write.py create notebooks/01_foo.ipynb
+$PYTHON jupyter_write.py create notebooks/01_foo.ipynb --kernel python3
+```
+
+Comportamiento:
+1. Crear el archivo .ipynb con estructura mínima válida (nbformat 4, kernel metadata)
+2. Opcionalmente aceptar celdas iniciales via stdin o argumentos
+3. Si el notebook ya existe, no sobreescribir (error o flag `--force`)
+
+## Contexto
+
+Encontrado al intentar crear `01_matching_engine_fifo.ipynb` en `analysis/estudio_mercados`. Tuve que escribir el archivo directamente con Write en vez de usar las funciones del registry.

dev/issues/completed/002_jupyter_discover_root_dir.md

@@ -0,0 +1,20 @@
+# jupyter_discover: detectar root_dir correctamente
+
+**Componente:** `python/functions/notebook/jupyter_discover.py`
+
+## Problema
+
+`jupyter_discover.py` reporta el campo `analysis` incorrecto. Con Jupyter corriendo desde `analysis/estudio_mercados/`, el discover devolvió `"analysis": "estudio_embeddings"`.
+
+El proceso real tenía `--ServerApp.root_dir=/home/lucas/fn_registry/analysis/estudio_mercados` en su cmdline, pero el discover no lo parsea.
+
+## Solución propuesta
+
+Mejorar la detección del analysis:
+1. Parsear `--ServerApp.root_dir` de la cmdline del proceso (via `/proc/{pid}/cmdline` o `psutil`)
+2. Alternativamente, consultar `GET /api/contents` que refleja el root_dir real
+3. Fallback al cwd del proceso si no hay root_dir explícito
+
+## Contexto
+
+Encontrado al verificar que Jupyter de estudio_mercados estaba activo. El discover decía estudio_embeddings, lo cual era confuso y requirió verificación manual con `ss` y `/proc`.

dev/issues/completed/003_jupyter_tools_documentation.md

@@ -0,0 +1,29 @@
+# Documentación consolidada de herramientas Jupyter
+
+**Componente:** `python/functions/notebook/`
+
+## Problema
+
+Las 5 funciones jupyter (`discover`, `read`, `exec`, `write`, `kernel`) tienen su documentación distribuida entre:
+- El `--help` de cada script
+- La sección de `CLAUDE.md` del proyecto raíz
+- Los `.md` de frontmatter de cada función
+
+No hay un documento único que explique el flujo completo, casos de uso comunes, y troubleshooting. Esto dificulta tanto el uso por agentes como por humanos.
+
+## Solución propuesta
+
+Crear una función de tipo `documentation` o un .md dedicado que incluya:
+
+1. **Flujo típico**: discover → read → write/exec (con ejemplo completo)
+2. **Tabla de subcomandos** por función con parámetros y ejemplos
+3. **Troubleshooting**: errores comunes y soluciones
+   - Websocket 4404 (notebook no existe)
+   - Kernel does not exist (sesión stale)
+   - Document not yet synced (timing de colaboración)
+4. **Limitaciones conocidas**: qué NO pueden hacer las funciones
+5. **Diferencias con MCP jupyter**: por qué estas funciones lo reemplazan
+
+## Ubicación sugerida
+
+`python/functions/notebook/README.md` o bien una función `jupyter_help_py_notebook` que imprima la guía.

dev/issues/completed/004_jupyter_discover_multiple_instances.md

@@ -0,0 +1,20 @@
+# jupyter_discover: soporte para múltiples instancias
+
+**Componente:** `python/functions/notebook/jupyter_discover.py`
+
+## Problema
+
+Con varios análisis corriendo en puertos distintos (8888, 8889, etc.), el discover necesita:
+- Listar todas las instancias con su root_dir correcto (ver issue 002)
+- Indicar claramente qué análisis corresponde a qué puerto
+- Facilitar la selección de instancia para las demás funciones
+
+## Solución propuesta
+
+1. Escanear puertos comunes (8888-8899) o parsear procesos jupyter activos
+2. Devolver lista con: puerto, root_dir, analysis name, collaborative mode, kernels activos
+3. Añadir flag `--port` a todas las funciones jupyter para apuntar a instancia específica
+
+## Contexto
+
+Actualmente si hay dos Jupyter corriendo hay que pasar `--port` manualmente y no queda claro cuál es cuál.

dev/issues/completed/005_jupyter_write_batch.md

@@ -0,0 +1,29 @@
+# jupyter_write: crear múltiples celdas en batch
+
+**Componente:** `python/functions/notebook/jupyter_write.py`
+
+## Problema
+
+Para crear un notebook con contenido sustancial (como el matching engine con 12 celdas), hay que llamar `jupyter_write.py append-*` una vez por celda. Esto es lento por el overhead websocket+sync en cada llamada.
+
+## Solución propuesta
+
+Añadir subcomando `batch` que acepte un JSON/YAML con múltiples celdas:
+
+```bash
+$PYTHON jupyter_write.py batch notebooks/01_foo.ipynb --from cells.json
+```
+
+Donde `cells.json`:
+```json
+[
+  {"type": "markdown", "source": "# Título"},
+  {"type": "code", "source": "import pandas as pd"},
+  {"type": "markdown", "source": "## Sección 2"},
+  {"type": "code", "source": "df = pd.read_csv('data.csv')"}
+]
+```
+
+Una sola conexión websocket, todas las celdas de golpe, una sola espera de sync.
+
+Combinado con issue 001 (create), permitiría crear notebooks completos en una sola operación.

dev/issues/completed/006_jupyter_exec_outputs_keyerror.md

@@ -0,0 +1,28 @@
+# jupyter_exec cell: KeyError 'outputs' en notebooks creados manualmente
+
+**Componente:** `python/functions/notebook/jupyter_exec.py`
+
+## Problema
+
+Al ejecutar `jupyter_exec.py cell` sobre un notebook creado como archivo (no via Jupyter UI), falla con:
+
+```
+{"error": "'outputs'"}
+```
+
+La causa es que las celdas de código creadas manualmente pueden no incluir el campo `"outputs": []` o `"execution_count": null` que Jupyter espera. El exec no valida/normaliza la estructura antes de operar.
+
+## Reproducción
+
+1. Crear un .ipynb manualmente con celdas `"cell_type": "code"` sin campo `"outputs"`
+2. Abrir en Jupyter Lab
+3. Ejecutar `jupyter_exec.py cell notebook.ipynb <N>`
+4. Error: `{"error": "'outputs'"}`
+
+## Solución propuesta
+
+En `jupyter_exec.py`, antes de ejecutar una celda, normalizar campos faltantes:
+- Si `cell_type == "code"` y no tiene `outputs` → añadir `"outputs": []`
+- Si no tiene `execution_count` → añadir `"execution_count": null`
+
+Esto es especialmente relevante combinado con la issue 001 (crear notebooks) y 005 (batch), ya que los notebooks creados programáticamente son los más propensos a este problema.