nteract
diff --git a/‎.claude/skills/python-bindings/SKILL.md‎
Lines changed: 41 additions & 48 deletions b/‎.claude/skills/python-bindings/SKILL.md‎
Lines changed: 41 additions & 48 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 32 additions & 6 deletions b/‎AGENTS.md‎
Lines changed: 32 additions & 6 deletions
diff --git a/‎contributing/development.md‎
Lines changed: 13 additions & 2 deletions b/‎contributing/development.md‎
Lines changed: 13 additions & 2 deletions
diff --git a/‎contributing/runtimed.md‎
Lines changed: 41 additions & 54 deletions b/‎contributing/runtimed.md‎
Lines changed: 41 additions & 54 deletions
diff --git a/‎contributing/testing.md‎
Lines changed: 11 additions & 11 deletions b/‎contributing/testing.md‎
Lines changed: 11 additions & 11 deletions
@@ -37,24 +37,29 @@ Running `maturin develop` without `VIRTUAL_ENV` installs the `.so` into whicheve
 ## Basic Usage
 
 ```python
+import asyncio
 import runtimed
 
-session = runtimed.Session()
-session.connect()
-session.start_kernel()
-
-result = session.run("print('hello')")
-print(result.stdout)   # "hello\n"
-print(result.outputs)  # [Output(stream, stdout: "hello\n")]
-
-# Rich output
-result = session.run("from IPython.display import Image, display; display(Image(filename='photo.png'))")
-for output in result.outputs:
-    for mime, value in output.data.items():
-        print(mime, type(value))
-        # image/png  <class 'bytes'>       -- raw binary, NOT base64
-        # text/llm+plain  <class 'str'>    -- synthesized blob URL
-        # text/plain <class 'str'>
+async def main():
+    client = runtimed.Client()
+    async with await client.create() as notebook:
+        cell = await notebook.cells.create("print('hello')")
+        result = await cell.run()
+        print(result.stdout)   # "hello\n"
+
+        # Sync reads from local CRDT
+        print(cell.source)      # "print('hello')"
+        print(cell.cell_type)   # "code"
+
+asyncio.run(main())
+```
+
+For the native session API (streaming, presence, metadata), use `NativeAsyncClient`:
+
+```python
+native_client = runtimed.NativeAsyncClient()
+session = await native_client.create_notebook()
+result = await session.run("print('hello')")
 ```
 
 ## Output.data Typing
@@ -72,32 +77,35 @@ for output in result.outputs:
 
 When an output contains a binary image MIME type, the daemon synthesizes a `text/llm+plain` entry combining text/plain, image metadata, and blob URL. Lets LLMs reference images without decoding binary data.
 
-## Per-Cell Accessors
+## High-Level Cell Access
 
-Prefer these O(1) methods over `get_cells()` (which materializes everything):
+The `Notebook.cells` collection provides sync reads and async writes:
 
 ```python
-source = session.get_cell_source(cell_id)    # just the source string
-cell_type = session.get_cell_type(cell_id)   # "code" | "markdown" | "raw"
-cell_ids = session.get_cell_ids()             # position-sorted IDs
+# Sync reads from local CRDT
+cell = notebook.cells.get_by_index(0)
+print(cell.source, cell.cell_type, cell.outputs)
 
-# Full cell with outputs
-cell = session.get_cell(cell_id)
-print(cell.outputs, cell.position)
-
-# Move a cell
-session.move_cell("cell-id", after_cell_id="other-cell-id")
+# Search
+matches = notebook.cells.find("import")
 
 # Runtime state
-state = await async_session.get_runtime_state()  # idle, busy, etc.
+print(notebook.runtime.kernel.status)  # sync read
+```
+
+For the native session API, per-cell accessors are also available:
+
+```python
+source = session.get_cell_source(cell_id)    # just the source string
+cell_type = session.get_cell_type(cell_id)   # "code" | "markdown" | "raw"
+cell_ids = session.get_cell_ids()             # position-sorted IDs
 ```
 
 ## Socket Path Configuration
 
 **System daemon (default):**
 ```python
-session = runtimed.Session()
-session.connect()  # ~/Library/Caches/runt/runtimed.sock
+client = runtimed.Client()  # ~/Library/Caches/runt/runtimed.sock
 ```
 
 **Worktree daemon (development):**
@@ -106,21 +114,6 @@ export RUNTIMED_SOCKET_PATH="$(./target/debug/runt daemon status --json | python
 python your_script.py
 ```
 
-## Cross-Session Output Visibility
-
-The `Cell.outputs` field is from the Automerge document. Agents can see outputs from cells executed by other clients:
-
-```python
-s1 = runtimed.Session(notebook_id="shared")
-s1.connect(); s1.start_kernel()
-s1.run("x = 42")
-
-s2 = runtimed.Session(notebook_id="shared")
-s2.connect()
-cells = s2.get_cells()
-print(cells[0].outputs)  # Shows outputs from s1
-```
-
 ## Running Integration Tests
 
 ```bash
@@ -159,11 +152,11 @@ Three packages are workspace members:
 
 ### Wrong daemon
 
-If `session.run()` returns `Output(stream, stderr: "Failed to parse output: <hash>")`, the bindings are connecting to the wrong daemon. The blob store is per-daemon. Set `RUNTIMED_SOCKET_PATH` to the correct daemon socket.
+If `notebook.run()` returns `Output(stream, stderr: "Failed to parse output: <hash>")`, the bindings are connecting to the wrong daemon. The blob store is per-daemon. Set `RUNTIMED_SOCKET_PATH` to the correct daemon socket.
 
-### Empty outputs from get_cell()
+### Empty outputs from cell.outputs
 
-If `session.run()` shows outputs but `session.get_cell()` returns `outputs=[]`:
+If `cell.run()` shows outputs but `cell.outputs` returns `[]`:
 1. Check socket path — daemon needs blob store access
 2. Timing — outputs may not be written to Automerge yet. Try a small delay or re-fetch.
 
 
@@ -6,7 +6,23 @@ This document provides guidance for AI agents working in this repository. Claude
 
 ## Quick Recipes (Common Dev Tasks)
 
-These are copy-paste-ready commands. **All commands that interact with the dev daemon require two env vars.** Without them you'll hit the system daemon and cause problems.
+### If you have `supervisor_*` tools — use them
+
+If your MCP client provides `supervisor_status`, `supervisor_restart`, `supervisor_rebuild`, etc., **prefer those over manual terminal commands**. The supervisor manages the dev daemon lifecycle for you — no env vars, no extra terminals.
+
+| Instead of… | Use… |
+|-------------|------|
+| `cargo xtask dev-daemon` (in a terminal) | `supervisor_restart(target="daemon")` |
+| `maturin develop` (rebuild bindings) | `supervisor_rebuild` |
+| `runt daemon status` (with env vars) | `supervisor_status` |
+| `runt daemon logs` | `supervisor_logs` |
+| `cargo xtask vite` | `supervisor_start_vite` |
+
+The supervisor automatically handles per-worktree isolation, env var plumbing, and daemon restarts. You only need the manual commands below when the supervisor isn't available.
+
+### Manual commands (when supervisor is not available)
+
+All commands that interact with the dev daemon require two env vars. Without them you'll hit the system daemon and cause problems.
 
 ```bash
 # ── Dev daemon env vars (required for ALL dev commands) ────────────
@@ -59,6 +75,14 @@ python/runtimed/.venv/bin/python -m pytest python/runtimed/tests/test_session_un
 
 ### Running the notebook app (dev mode)
 
+**Do not launch the notebook app from an agent terminal.** The app is a GUI process that blocks until the user quits it (⌘Q), and the agent will misinterpret the exit. Let the human launch it from their own terminal or Zed task.
+
+With supervisor tools, the daemon and vite are already managed — the human just runs:
+```bash
+cargo xtask notebook
+```
+
+Without supervisor (human runs both):
 ```bash
 # Terminal 1: Start dev daemon
 cargo xtask dev-daemon
@@ -183,10 +207,10 @@ The supervisor watches `python/nteract/src/`, `python/runtimed/src/`, `crates/ru
 
 ### Tool availability
 
-- **Inkwell active** → all supervisor + nteract tools available
-- **nteract MCP only** → nteract tools only, no `supervisor_*`
+- **Inkwell active** → all supervisor + nteract tools available. **Prefer supervisor tools for daemon lifecycle** — they handle env vars and isolation automatically.
+- **nteract MCP only** → nteract tools only, no `supervisor_*`. Use manual terminal commands for daemon management.
 - **No MCP server** → use `cargo xtask run-mcp` to set one up
-- **Dev daemon not running** → Inkwell starts it automatically
+- **Dev daemon not running** → Inkwell starts it automatically via `supervisor_restart(target="daemon")`
 
 ## Build System (`cargo xtask`)
 
@@ -206,7 +230,9 @@ Use instead:
 
 ### Per-Worktree Daemon Isolation
 
-Each git worktree runs its own isolated daemon in dev mode.
+Each git worktree runs its own isolated daemon in dev mode. If you have supervisor tools, the daemon is managed for you — use `supervisor_restart(target="daemon")` to start or restart it, and `supervisor_status` to check it.
+
+Without supervisor (manual two-terminal workflow):
 
 ```bash
 # Terminal 1: Start dev daemon
@@ -216,7 +242,7 @@ cargo xtask dev-daemon
 cargo xtask notebook
 ```
 
-Use `./target/debug/runt` to interact with the worktree daemon:
+Use `./target/debug/runt` to interact with the worktree daemon (or `supervisor_status`/`supervisor_logs` if available):
 
 ```bash
 ./target/debug/runt daemon status
 
@@ -166,7 +166,18 @@ In production, the Tauri app auto-installs and manages the system daemon. In dev
 - Your code changes take effect immediately on daemon restart
 - No interference with the system daemon
 
-**Two-terminal workflow:**
+**With Inkwell supervisor (preferred for agents):**
+
+If you have `supervisor_*` MCP tools available (e.g. in Zed with `mcp-supervisor`), the daemon is managed for you:
+
+- `supervisor_restart(target="daemon")` — start or restart the dev daemon
+- `supervisor_status` — check daemon status (includes `daemon_managed: true/false`)
+- `supervisor_rebuild` — rebuild Python bindings + restart
+- `supervisor_logs` — tail daemon logs
+
+No env vars or extra terminals needed. The supervisor handles per-worktree isolation automatically.
+
+**Two-terminal workflow (without supervisor):**
 
 ```bash
 # Terminal 1: Start the dev daemon (stays running)
@@ -205,7 +216,7 @@ RUNTIMED_DEV=1 cargo xtask notebook
 
 Per-worktree state is stored in `<cache>/runt-nightly/worktrees/{hash}/` (macOS: `~/Library/Caches/`, Linux: `~/.cache/`).
 
-**For AI agents:** Use `./target/debug/runt` directly to interact with the daemon. See the "Agent Access to Dev Daemon" section in CLAUDE.md. When using a raw terminal (not Zed tasks), set the env vars manually:
+**For AI agents:** If `supervisor_*` tools are available, prefer those — they handle env vars and daemon lifecycle automatically. Otherwise, use `./target/debug/runt` directly (see "Agent Access to Dev Daemon" in CLAUDE.md). When using a raw terminal (not Zed tasks), set the env vars manually:
 
 ```bash
 export RUNTIMED_DEV=1
 
@@ -83,7 +83,26 @@ cat ~/.cache/runt/daemon.json   # check "version" field
 
 ### Fast iteration: Daemon + bundled notebook
 
-When iterating on daemon code, you often want to test changes in the notebook app without rebuilding the frontend:
+When iterating on daemon code, you often want to test changes in the notebook app without rebuilding the frontend.
+
+**With Inkwell supervisor** (if you have `supervisor_*` MCP tools — e.g. in Zed):
+
+The supervisor manages the dev daemon for you. No env vars or extra terminals needed.
+
+- `supervisor_restart(target="daemon")` — start or restart the dev daemon after code changes
+- `supervisor_rebuild` — rebuild Python bindings (`maturin develop`) + restart
+- `supervisor_status` — check daemon status (`daemon_managed: true` confirms it's running)
+- `supervisor_logs` — tail daemon logs
+- `supervisor_start_vite` — start the Vite dev server for hot-reload
+
+Then build and run the app normally:
+```bash
+cargo xtask build                 # Full build (includes frontend)
+cargo xtask build --rust-only     # Fast rebuild (reuses frontend assets)
+cargo xtask run                   # Run the bundled binary
+```
+
+**Without supervisor** (manual two-terminal workflow):
 
 ```bash
 # Terminal 1: Run dev daemon (restart when you change daemon code)
@@ -274,42 +293,29 @@ VIRTUAL_ENV=../../python/runtimed/.venv maturin develop
 ### Basic Usage
 
 ```python
+import asyncio
 import runtimed
 
-session = runtimed.Session()
-session.connect()
-session.start_kernel()
-
-result = session.run("print('hello')")
-print(result.stdout)  # "hello\n"
-print(result.outputs)  # [Output(stream, stdout: "hello\n")]
-
-# Rich output (e.g. display(Image(...)))
-result = session.run("from IPython.display import Image, display; display(Image(filename='photo.png'))")
-for output in result.outputs:
-    for mime, value in output.data.items():
-        print(mime, type(value))
-        # image/png  <class 'bytes'>       — raw binary, NOT base64
-        # text/llm+plain  <class 'str'>    — synthesized blob URL for LLM consumers
-        # text/plain <class 'str'>
-
-# Get cell with outputs (includes historical outputs from other clients)
-cell = session.get_cell(result.cell_id)
-print(cell.outputs)  # [Output(stream, stdout: "hello\n")]
-
-# Per-cell accessors (O(1), no full-doc materialization)
-source = session.get_cell_source(result.cell_id)  # just the source string
-cell_type = session.get_cell_type(result.cell_id)  # "code" | "markdown" | "raw"
-cell_ids = session.get_cell_ids()                   # position-sorted IDs
-
-# Move a cell (updates fractional index position)
-new_position = session.move_cell("cell-id", after_cell_id="other-cell-id")
-
-# Cell objects include position
-print(cell.position)  # fractional index string e.g. "80", "C0"
+async def main():
+    client = runtimed.Client()
+    async with await client.create_notebook() as notebook:
+        # Work with cells
+        cell = await notebook.cells.create("print('hello')")
+        result = await cell.run()
+        print(result.stdout)  # "hello\n"
+
+        cell = await notebook.cells.create("x = 42")
+        await cell.run()
+
+        # Sync reads from local CRDT
+        print(cell.source)      # "x = 42"
+        print(cell.cell_type)   # "code"
+        print(cell.outputs)     # resolved outputs
+
+asyncio.run(main())
 ```
 
-**Prefer per-cell accessors** (`get_cell_source`, `get_cell_type`, `get_cell_ids`) over `get_cells()` when you only need one cell or one field. `get_cells()` materializes every cell's source, outputs, and metadata.
+See [docs/python-bindings.md](../docs/python-bindings.md) for the full API reference.
 
 ### Output.data Typing
 
@@ -342,8 +348,7 @@ The Python bindings respect the `RUNTIMED_SOCKET_PATH` environment variable. Thi
 **System daemon (default):**
 ```python
 # Connects to system daemon at ~/Library/Caches/runt/runtimed.sock
-session = runtimed.Session()
-session.connect()
+client = runtimed.Client()
 ```
 
 **Worktree daemon (for development):**
@@ -367,25 +372,7 @@ export RUNTIMED_SOCKET_PATH=$(cat ~/Library/Caches/runt/worktrees/*/daemon.json
   jq -r 'select(.worktree_path == "'$(pwd)'") | .endpoint')
 
 # Now Python bindings will use the worktree daemon
-python -c "import runtimed; s = runtimed.Session(); s.connect(); print('Connected!')"
-```
-
-### Cross-Session Output Visibility
-
-The `Cell.outputs` field is populated from the Automerge document, enabling agents to see outputs from cells executed by other clients:
-
-```python
-# Session 1 executes code
-s1 = runtimed.Session(notebook_id="shared")
-s1.connect()
-s1.start_kernel()
-s1.run("x = 42")
-
-# Session 2 sees outputs without executing
-s2 = runtimed.Session(notebook_id="shared")
-s2.connect()
-cells = s2.get_cells()
-print(cells[0].outputs)  # Shows outputs from s1's execution
+python -c "import asyncio, runtimed; asyncio.run(runtimed.Client().ping())"
 ```
 
 ## Troubleshooting
 
@@ -215,19 +215,19 @@ RUNTIMED_INTEGRATION_TEST=1 pytest python/runtimed/tests/ -v
 
 ```python
 # Unit test (no daemon)
-class TestSessionConstruction:
-    def test_session_with_auto_id(self):
-        session = runtimed.Session()
-        assert session.notebook_id.startswith("agent-session-")
-        assert not session.is_connected
+class TestModuleExports:
+    def test_client_exported(self):
+        assert hasattr(runtimed, "Client")
 
-# Integration test (needs daemon)
+    def test_notebook_exported(self):
+        assert hasattr(runtimed, "Notebook")
+
+# Integration test (needs daemon, uses NativeAsyncClient for direct session access)
 @pytest.mark.asyncio
-async def test_kernel_execution(self):
-    async with runtimed.AsyncSession() as session:
-        await session.start_kernel()
-        result = await session.run("1 + 1")
-        assert result.success
+async def test_kernel_execution(async_session):
+    await async_session.start_kernel()
+    result = await async_session.run("1 + 1")
+    assert result.success
 ```
 
 **Environment variables:**