docs: sync agent + contributor docs to current architecture (#1846)

* docs(agents): refresh CLAUDE.md/AGENTS.md and skills

- Crate table now lists 21 crates (was 17); added runt-mcp-proxy,
  nteract-predicate, sift-wasm, mcpb-runt; renamed runt → runt-cli to
  match the actual package name.
- MCP tool table corrected: 26 tools (was 27), launch_app replaces
  show_notebook, clear_outputs is a CRUD tool, join_notebook flagged as
  backward-compat alias.
- Replaced "supervisor" terminology in user-facing docs with
  nteract-dev (the registered MCP server name) or the specific tool
  names (up/down/status/logs/vite_logs). The literal mcp-supervisor
  crate name is retained where it refers to the actual package.

* docs(codex): drop "supervisor" terminology in codex skill references

* docs: socket-first daemon discovery, blob-ref save scope, Sift framing

- contributing/runtimed.md, contributing/protocol.md: clarify that
  daemon.json is a legacy fallback for pre-GetDaemonInfo daemons; the
  socket is the source of truth. Add frame type 0x06 PoolStateSync to
  the protocol frame table.
- contributing/architecture.md: nuance the isBinaryMime story — the TS
  looksLikeBinaryMime() helper is a cold-start safety net, not a
  parallel implementation. Document that .ipynb save inlines most
  outputs as base64 (vanilla Jupyter compat) and only externalizes a
  small whitelist (parquet) as BLOB_REF_MIME entries.
- contributing/frontend-architecture.md: note Lezer parsers replaced
  Prism for static highlighting in #1742.
- contributing/releasing.md: add Local Validation section pointing at
  cargo xtask build-app / build-dmg; do not surface install-daemon
  here (release flow is via the auto-updater, not manual installs).
- docs/python-bindings.md: position runt mcp as canonical MCP path so
  agents do not assume Python is required.
- docs/sharing.md, docs/environments.md: explain HMAC-SHA256 trust
  signing and key location, document the new ipynb save shape (mostly
  base64, parquet externalized for the Sift dataframe viewer).
- Brand correction: dataframe viewer is "Sift" / nteract dataframe
  viewer; the nteract/dx Python package is the helper that produces
  parquet payloads consumed by it.

Author: rgbkrk

.claude/rules/mcp-servers.md

@@ -10,34 +10,32 @@ Three nteract MCP servers may be available. Always use the right one:
 
 | Server | What it is | When to use |
 |--------|-----------|-------------|
-| `nteract-dev` | Dev MCP server with supervisor tools (`up`, `down`, `status`, `logs`, `vite_logs`). Manages a per-worktree dev daemon, hot-reloads on code changes. | **Default for all development work.** Use this for notebook interaction, daemon lifecycle, building, and testing. |
+| `nteract-dev` | Dev MCP server. Adds dev tools (`up`, `down`, `status`, `logs`, `vite_logs`) on top of the proxied `runt mcp` toolset. Manages a per-worktree dev daemon, hot-reloads on code changes. | **Default for all development work.** Use this for notebook interaction, daemon lifecycle, building, and testing. |
 | `nteract-nightly` | System-installed nightly release daemon | Diagnostics and inspection of the installed nightly app. Do NOT use for development. |
 | `nteract` | System-installed stable release daemon (nteract.app) | Diagnostics and inspection of the installed stable app. Do NOT use for development. |
 
 **Rules:**
 
-1. **Always prefer `nteract-dev`** (`mcp__nteract-dev__*` tools) for development work in this repo. It connects to the per-worktree dev daemon and includes supervisor tools for managing the build/daemon lifecycle.
+1. **Always prefer `nteract-dev`** (`mcp__nteract-dev__*` tools) for development work in this repo. It connects to the per-worktree dev daemon and includes the dev tools for managing the build/daemon lifecycle.
 2. **Never use `nteract-nightly` or `nteract` for development.** They connect to system-installed daemons and will not reflect your source changes.
 3. If `nteract-dev` tools are not available, fall back to `cargo xtask` commands — not to the system MCP servers.
-4. The supervisor tools are part of the `nteract-dev` server. They manage the dev daemon and build pipeline — prefer them over manual terminal commands.
+4. The dev tools (`up`, `down`, `status`, `logs`, `vite_logs`) live on the `nteract-dev` server. They manage the dev daemon and build pipeline — prefer them over manual terminal commands.
 
-## Supervisor tool surface (nteract-dev)
+## nteract-dev tool surface
 
-Consolidated around two verbs plus three read-only tools:
+Two verbs plus three read-only tools, layered on top of the proxied `runt mcp` toolset:
 
 | Tool | Purpose |
 |------|---------|
 | `up` | Idempotent "bring the dev environment to a working state." Sweeps zombie Vite processes, ensures the daemon is running, ensures the MCP child is healthy. Optional args: `vite=true` to also start Vite, `rebuild=true` to rebuild daemon + Python bindings first, `mode='debug'\|'release'` to switch build mode. Safe to call repeatedly — this is the first thing to reach for when things feel off. |
 | `down` | Stop the managed Vite dev server. Leaves the daemon running by default (launchd / the installed app may own it). Pass `daemon=true` to also stop the managed daemon process. |
-| `status` | Read-only report of supervisor, child, daemon, and managed-process state. |
+| `status` | Read-only report of `nteract-dev`, child, daemon, and managed-process state. |
 | `logs` | Tail the daemon log. Arg: `lines` (default 50). |
 | `vite_logs` | Tail the Vite dev server log. Arg: `lines` (default 50). |
 
-The older `supervisor_*` names (`supervisor_status`, `supervisor_restart`, `supervisor_rebuild`, `supervisor_logs`, `supervisor_vite_logs`, `supervisor_start_vite`, `supervisor_stop`, `supervisor_set_mode`) still work as aliases. Prefer the new names.
-
 ## MCP Server
 
-The supervisor always uses `runt mcp` (Rust-native, direct Automerge access, no Python overhead). It auto-builds `runt-cli` on startup and watches `crates/runt-mcp/src/` for hot reload. For the installed app, `runt mcp` ships as a sidecar binary — no Python or uv required.
+`nteract-dev` proxies `runt mcp` (Rust-native, direct Automerge access, no Python overhead). It auto-builds `runt-cli` on startup and watches `crates/runt-mcp/src/` for hot reload. For the installed app, `runt mcp` ships as a sidecar binary — no Python or uv required.
 
 ## System daemon CLI (`runt` / `runt-nightly`)
 
@@ -62,7 +60,7 @@ For the dev daemon, use `./target/debug/runt` directly (no `env -i` needed — d
 After setting up direnv, verify that the three MCP servers connect to the correct daemons:
 
 ```bash
-# 1. Check nteract-dev supervisor status (should show worktrees/ socket)
+# 1. Check nteract-dev status (should show worktrees/ socket)
 status
 # Expected socket: ~/.cache/runt-nightly/worktrees/{hash}/runtimed.sock
 

.claude/skills/architecture-review/SKILL.md

@@ -79,8 +79,8 @@ Python packages. The major architectural seams are:
 - `runt-workspace`: Per-worktree daemon socket isolation
 - `runt`: CLI binary (daemon management, kernel control, notebook launching, MCP server)
 - `runtimed-client`: Shared client library (output resolution, daemon paths, pool client)
-- `runt-mcp`: Rust-native MCP server (27 tools for notebook interaction)
-- `mcp-supervisor`: nteract-dev MCP supervisor proxy, daemon/vite lifecycle
+- `runt-mcp`: Rust-native MCP server (26 tools for notebook interaction)
+- `mcp-supervisor`: `nteract-dev` MCP server (proxies `runt mcp`, manages daemon/vite lifecycle)
 - `repr-llm`: LLM-friendly text summaries of visualization specs
 - `notebook`: Tauri desktop app (main GUI, bundles daemon+CLI as sidecars)
 

.claude/skills/diagnostics/SKILL.md

@@ -7,7 +7,7 @@ description: Collect and analyze nteract diagnostic logs. Use when debugging iss
 
 ## Why `env -i`?
 
-In the dev environment, `RUNTIMED_DEV` and `RUNTIMED_WORKSPACE_PATH` are set (by direnv, xtask, or the supervisor). These cause `runt` to target the per-worktree dev daemon. System diagnostics need to target the **system-installed** daemon, so we use `env -i` to strip all env vars except `PATH` and `HOME`.
+In the dev environment, `RUNTIMED_DEV` and `RUNTIMED_WORKSPACE_PATH` are set (by direnv, xtask, or `nteract-dev`). These cause `runt` to target the per-worktree dev daemon. System diagnostics need to target the **system-installed** daemon, so we use `env -i` to strip all env vars except `PATH` and `HOME`.
 
 The repo-local `bin/runt` wrapper is first in `$PATH` — it runs `./target/debug/runt`, which is the dev build. That's fine for quick checks, but for true system diagnostics, call the system binary by its channel-specific name (`runt` for stable, `runt-nightly` for nightly) via `env -i` so dev env vars don't leak through.
 

.claude/skills/frontend-dev/SKILL.md

@@ -17,7 +17,7 @@ description: Run the notebook app in dev mode with hot reload. Use when starting
 | Run bundled binary | `cargo xtask run` |
 | One-shot setup | `cargo xtask dev` |
 | Lint/format | `cargo xtask lint --fix` |
-| MCP supervisor | `cargo xtask run-mcp` |
+| nteract-dev MCP server | `cargo xtask run-mcp` |
 
 ## `cargo xtask notebook` — Hot Reload
 
@@ -118,13 +118,13 @@ RUNTIMED_DEV=1 cargo xtask notebook      # Terminal 2
 
 ## MCP Server Development
 
-### nteract-dev Supervisor (recommended)
+### nteract-dev (recommended)
 
 ```bash
 cargo xtask run-mcp
 ```
 
-Starts the dev daemon, launches the dev-only `nteract-dev` supervisor, spawns a child `runt mcp`, proxies notebook tool calls, watches for file changes, and hot-reloads. Python bindings are rebuilt when the watched Rust paths require it.
+Starts the dev daemon, launches `nteract-dev` (the dev-only MCP server for this source tree), spawns a child `runt mcp`, proxies notebook tool calls, watches for file changes, and hot-reloads. Python bindings are rebuilt when the watched Rust paths require it.
 
 For editor config:
 
@@ -150,7 +150,7 @@ Use `nteract-dev` as the repo-local MCP server name so it stays distinct from an
 }
 ```
 
-### Direct Mode (no supervisor)
+### Direct Mode (no proxy)
 
 ```bash
 # Terminal 1: start dev daemon
@@ -160,7 +160,7 @@ cargo xtask dev-daemon
 cargo xtask dev-mcp
 ```
 
-### Supervisor Tools
+### nteract-dev Tools
 
 | Tool | Purpose |
 |------|---------|
@@ -170,8 +170,6 @@ cargo xtask dev-mcp
 | `logs` | Tail daemon log file |
 | `vite_logs` | Tail Vite dev server log file |
 
-The older `supervisor_*` names (`supervisor_status`, `supervisor_restart`, `supervisor_rebuild`, `supervisor_logs`, `supervisor_vite_logs`, `supervisor_start_vite`, `supervisor_stop`, `supervisor_set_mode`) still work as aliases.
-
 ### Hot Reload
 
 Watches `python/nteract/src/`, `python/runtimed/src/`, `crates/runtimed-py/src/`, `crates/runtimed/src/`:

.claude/skills/python-bindings/SKILL.md

@@ -185,21 +185,23 @@ runt mcp
 # Or via the Python wrapper
 uv run nteract
 
-# Via nteract-dev supervisor (recommended for development, handles lifecycle)
+# Via nteract-dev (recommended for development, handles lifecycle)
 cargo xtask run-mcp
 ```
 
-### nteract MCP Tools (27 tools)
+### nteract MCP Tools (26 tools)
 
 | Category | Tools |
 |----------|-------|
-| Session | `list_active_notebooks`, `show_notebook`, `join_notebook`, `open_notebook`, `create_notebook`, `save_notebook` |
+| Session | `list_active_notebooks`, `open_notebook`, `create_notebook`, `save_notebook`, `launch_app` |
 | Kernel | `interrupt_kernel`, `restart_kernel` |
 | Dependencies | `add_dependency`, `remove_dependency`, `get_dependencies`, `sync_environment` |
-| Cell CRUD | `create_cell`, `get_cell`, `get_all_cells`, `set_cell`, `delete_cell`, `move_cell` |
+| Cell CRUD | `create_cell`, `get_cell`, `get_all_cells`, `set_cell`, `delete_cell`, `move_cell`, `clear_outputs` |
 | Cell metadata | `set_cells_source_hidden`, `set_cells_outputs_hidden`, `add_cell_tags`, `remove_cell_tags` |
-| Find/Replace | `replace_match`, `replace_regex` |
-| Execution | `execute_cell`, `run_all_cells`, `clear_outputs` |
+| Editing | `replace_match`, `replace_regex` |
+| Execution | `execute_cell`, `run_all_cells` |
+
+`join_notebook` is accepted as a backward-compat alias for `open_notebook`.
 
 Three packages are workspace members:
 
@@ -230,4 +232,4 @@ cd crates/runtimed-py
 VIRTUAL_ENV=../../.venv uv run --directory ../../python/runtimed maturin develop
 ```
 
-Or if using nteract-dev supervisor, call `up rebuild=true`.
+Or if using nteract-dev, call `up rebuild=true`.

.claude/skills/verify-changes/SKILL.md

@@ -24,16 +24,16 @@ Run `git diff --name-only` to see changed files and match them to the table belo
 | `crates/runt/src/**` | `cargo test -p runt` |
 | `crates/runt-workspace/src/**` | `cargo test -p runt-workspace` |
 | `crates/runtimed-py/src/**` | `up rebuild=true` (rebuilds Python bindings) |
-| `python/nteract/src/**` | Supervisor auto-restarts; no explicit test needed |
-| `python/runtimed/src/**` | Supervisor auto-restarts; run `pytest python/runtimed/tests/test_session_unit.py -v` |
+| `python/nteract/src/**` | `nteract-dev` auto-restarts; no explicit test needed |
+| `python/runtimed/src/**` | `nteract-dev` auto-restarts; run `pytest python/runtimed/tests/test_session_unit.py -v` |
 | `apps/notebook/src/**` | `pnpm test:run` |
 | `crates/runtimed-wasm/**` | `cargo xtask wasm` then `deno test --allow-read --allow-env --no-check` |
 
 If multiple crates changed, run tests for each: `cargo test -p runtimed -p notebook-doc`.
 
-## Step 3: MCP Live Verification (when supervisor tools are available)
+## Step 3: MCP Live Verification (when nteract-dev tools are available)
 
-If narrow tests pass and you have the nteract-dev supervisor (`up`/`down`/`status`) and `open_notebook`/`execute_cell` tools, do a live check:
+If narrow tests pass and you have `nteract-dev` (`up`/`down`/`status`) and `open_notebook`/`execute_cell` tools, do a live check:
 
 ### For daemon/kernel changes (`crates/runtimed/`, `crates/runtimed-py/`):
 
@@ -79,7 +79,7 @@ Run the setup cell first, then run any metric cell. Each metric cell is self-con
 - Uses the **project venv** (no inline dependencies) — `runtimed` and `matplotlib` are both project dev deps
 - Imports `runtimed.Client` directly for inline async measurements (no subprocess needed)
 - Loads `baseline.json` from the notebook's own directory (`scripts/metrics/`)
-- The daemon socket is discovered automatically via `RUNTIMED_SOCKET_PATH` env var (set by the daemon/supervisor)
+- The daemon socket is discovered automatically via `RUNTIMED_SOCKET_PATH` env var (set by the daemon or `nteract-dev`)
 
 **Three measurement cells:**
 - **Execution latency** — cold start + warm p50/p95 distribution, compared to baseline

.codex/skills/nteract-daemon-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nteract-daemon-dev
-description: Work with the per-worktree runtimed daemon in the nteract desktop repo. Use when changing `crates/runtimed/**`, debugging daemon-backed notebook behavior, deriving `RUNTIMED_SOCKET_PATH`, checking daemon logs/status, running daemon-backed tests or reviews, or deciding whether to use `supervisor_*` tools versus manual `cargo xtask dev-daemon` commands.
+description: Work with the per-worktree runtimed daemon in the nteract desktop repo. Use when changing `crates/runtimed/**`, debugging daemon-backed notebook behavior, deriving `RUNTIMED_SOCKET_PATH`, checking daemon logs/status, running daemon-backed tests or reviews, or deciding whether to use the `nteract-dev` MCP tools (`up`/`down`/`status`/`logs`/`vite_logs`) versus manual `cargo xtask dev-daemon` commands.
 ---
 
 # nteract Daemon Dev
@@ -9,7 +9,7 @@ Use this skill to avoid talking to the wrong daemon and to keep daemon-backed ve
 
 ## Workflow
 
-1. Prefer `supervisor_*` tools when they are available.
+1. Prefer the `nteract-dev` MCP tools (`up`, `down`, `status`, `logs`, `vite_logs`) when they are available.
 2. Decide whether you are validating the default nightly source flow or an explicit stable flow. Source builds are nightly unless `RUNT_BUILD_CHANNEL=stable`.
 3. Otherwise, treat the worktree daemon as mandatory for daemon-backed verification.
 4. Export `RUNTIMED_DEV=1` and `RUNTIMED_WORKSPACE_PATH="$(pwd)"` before any manual `runt` command.
@@ -27,6 +27,6 @@ Use this skill to avoid talking to the wrong daemon and to keep daemon-backed ve
 
 ## Quick Start
 
-If you have supervisor tools, use them for daemon lifecycle and logs.
+If you have `nteract-dev` tools, use them for daemon lifecycle and logs.
 
 If you do not, read [references/daemon-workflows.md](references/daemon-workflows.md) and follow the manual command sequence there.

.codex/skills/nteract-daemon-dev/references/daemon-workflows.md

@@ -58,17 +58,17 @@ Start or restart the worktree daemon when:
 - You are verifying MCP server behavior against local Rust changes
 - You are comparing behavior across worktrees and need isolation
 
-## Prefer supervisor tools when available
+## Prefer nteract-dev tools when available
 
-If the nteract-dev MCP supervisor is available, prefer:
+If `nteract-dev` is available, prefer:
 
 - `up` — idempotent "bring the dev environment up". Ensures daemon + child are healthy. Args: `vite=true`, `rebuild=true`, `mode="debug"|"release"`
 - `down` — stop the managed Vite dev server. `daemon=true` also stops the daemon
 - `status` — read-only report
 - `logs` — tail daemon logs
 - `vite_logs` — tail Vite dev server logs when you need the Vite side of a hot-reload session
 
-These avoid manual env-var mistakes. The older `supervisor_*` names (`supervisor_restart`, `supervisor_rebuild`, `supervisor_start_vite`, `supervisor_stop`, `supervisor_set_mode`, `supervisor_status`, `supervisor_logs`, `supervisor_vite_logs`) still work as aliases.
+These avoid manual env-var mistakes.
 
 ## Safety rules
 

.codex/skills/nteract-python-bindings/references/bindings-workflows.md

@@ -58,7 +58,7 @@ The MCP server is `runt mcp` (Rust, shipped with the desktop app). For developme
 uv run nteract
 ```
 
-If the MCP supervisor is available, prefer `cargo xtask run-mcp` or the supervisor tools instead of a manual launch.
+If `nteract-dev` is available, prefer `cargo xtask run-mcp` or its tools (`up`, `down`, `status`, `logs`, `vite_logs`) instead of a manual launch.
 
 Use `default_socket_path()` for current-process resolution. Use `socket_path_for_channel("stable"|"nightly")` only when you need an explicit channel path that ignores `RUNTIMED_SOCKET_PATH`.